FractalDataWorks.TUI.Management 0.1.0-preview.11

FractalDataWorks.TUI.Management

Terminal UI management application for FractalDataWorks services. Provides a console-based interface for monitoring, configuration, and instance connection management.

Overview

This application uses Spectre.Console to render terminal interfaces for:

• Connecting to FractalDataWorks instances
• System dashboards with status and metrics
• Configuration and settings management
• Monitoring screens

Running

cd public/src/FractalDataWorks.TUI.Management
dotnet run

Architecture

FractalDataWorks.TUI.Management/
├── Navigation/
│   ├── IScreen.cs              # Screen interface and NavigationResult
│   ├── INavigationService.cs   # Navigation stack interface
│   ├── NavigationService.cs    # Stack-based navigation
│   ├── IScreenFactory.cs       # DI-based screen factory
│   ├── ScreenFactory.cs        # Screen factory implementation
│   └── MenuTargets/            # TypeCollection for menu dispatch
│       ├── MenuTargets.cs      # TypeCollection definition
│       ├── IMenuTarget.cs      # Menu target interface
│       ├── MenuTargetBase.cs   # Base class for targets
│       └── *MenuTarget.cs      # Concrete menu targets
├── Screens/
│   ├── ScreenBase.cs           # Base class for all screens
│   ├── MainMenuScreen.cs       # Main menu using MenuTargets dispatch
│   ├── DashboardScreen.cs      # System dashboard with metrics
│   ├── ConnectionsScreen.cs    # Instance connection management
│   ├── SettingsScreen.cs       # Application settings
│   ├── ConfigurationMenuScreen.cs
│   └── MonitoringMenuScreen.cs
├── Services/
│   ├── IConnectionManager.cs   # Connection management interface
│   ├── ConnectionManager.cs    # Connection manager implementation
│   ├── ISettingsService.cs     # Settings service interface
│   └── SettingsService.cs      # Settings service implementation
├── ManagementApp.cs            # Main application loop
└── Program.cs                  # Entry point and DI configuration

Screen Navigation

The application uses a stack-based navigation model. Screens implement IScreen and return NavigationResult to control navigation flow.

From IScreen.cs:8-20:

public interface IScreen
{
    /// <summary>
    /// Gets the title of the screen.
    /// </summary>
    string Title { get; }

    /// <summary>
    /// Shows the screen and returns a navigation result.
    /// </summary>
    /// <returns>The navigation result indicating what to do next.</returns>
    Task<NavigationResult> Show();
}

From IScreen.cs:38-59:

/// <summary>
/// Creates a result to push a new screen onto the stack.
/// </summary>
public static NavigationResult Push(IScreen screen) =>
    new() { Action = NavigationAction.Push, NextScreen = screen };

/// <summary>
/// Creates a result to pop the current screen off the stack.
/// </summary>
public static NavigationResult Pop() =>
    new() { Action = NavigationAction.Pop };

/// <summary>
/// Creates a result to replace the current screen.
/// </summary>
public static NavigationResult Replace(IScreen screen) =>
    new() { Action = NavigationAction.Replace, NextScreen = screen };

/// <summary>
/// Creates a result to exit the application.
/// </summary>
public static NavigationResult Exit() =>
    new() { Action = NavigationAction.Exit };

From NavigationService.cs:9-27:

public sealed class NavigationService : INavigationService
{
    private readonly Stack<IScreen> _stack = new();

    /// <inheritdoc />
    public IScreen? Current => _stack.Count > 0 ? _stack.Peek() : null;

    /// <inheritdoc />
    public bool HasScreens => _stack.Count > 0;

    /// <inheritdoc />
    public int Depth => _stack.Count;

    /// <inheritdoc />
    public void Push(IScreen screen)
    {
        ArgumentNullException.ThrowIfNull(screen);
        _stack.Push(screen);
    }

Menu Dispatch Pattern

The main menu uses a TypeCollection-based dispatch pattern to avoid switch statements. Menu targets are discovered via the [TypeOption] attribute and looked up by name.

From MenuTargets.cs:1-13:

using FractalDataWorks.Collections;
using FractalDataWorks.Collections.Attributes;

namespace FractalDataWorks.TUI.Management.Navigation;

/// <summary>
/// TypeCollection of available menu targets.
/// Use MenuTargets.ByName() for dispatch-based menu navigation.
/// </summary>
[TypeCollection(typeof(MenuTargetBase), typeof(IMenuTarget), typeof(MenuTargets))]
public partial class MenuTargets : TypeCollectionBase<MenuTargetBase, IMenuTarget>
{
}

From MainMenuScreen.cs:81-92:

private NavigationResult HandleSelection(string id)
{
    // Dispatch pattern - each MenuTarget knows its own navigation behavior
    var target = MenuTargets.ByName(id);

    if (target == MenuTargets.Empty)
    {
        return NavigationResult.Stay();
    }

    return target.Navigate(ScreenFactory);
}

Example menu target implementation:

From MonitoringMenuTarget.cs:1-30:

using FractalDataWorks.Collections.Attributes;
using FractalDataWorks.TUI.Management.Screens;

namespace FractalDataWorks.TUI.Management.Navigation;

/// <summary>
/// Menu target for monitoring and logs.
/// </summary>
[TypeOption(typeof(MenuTargets), "monitoring")]
public sealed class MonitoringMenuTarget : MenuTargetBase
{
    /// <summary>
    /// Creates the monitoring menu target.
    /// </summary>
    public MonitoringMenuTarget() : base(
        id: 3,
        name: "monitoring",
        label: "Monitoring & Logs",
        group: "Main",
        order: 3,
        requiresConnection: true)
    {
    }

    /// <inheritdoc />
    public override NavigationResult Navigate(IScreenFactory screenFactory)
    {
        return NavigationResult.Push(screenFactory.Create<MonitoringMenuScreen>());
    }
}

Screens

All screens inherit from ScreenBase which provides common functionality:

From ScreenBase.cs:12-44:

public abstract class ScreenBase : IScreen
{
    /// <summary>
    /// Gets the console instance.
    /// </summary>
    protected IAnsiConsole Console { get; }

    /// <summary>
    /// Gets the theme.
    /// </summary>
    protected IMenuTheme Theme { get; }

    /// <summary>
    /// Gets the screen factory.
    /// </summary>
    protected IScreenFactory ScreenFactory { get; }

    /// <inheritdoc />
    public abstract string Title { get; }

    /// <summary>
    /// Initializes a new instance of the <see cref="ScreenBase"/> class.
    /// </summary>
    protected ScreenBase(IAnsiConsole console, IMenuTheme theme, IScreenFactory screenFactory)
    {
        Console = console ?? throw new ArgumentNullException(nameof(console));
        Theme = theme ?? throw new ArgumentNullException(nameof(theme));
        ScreenFactory = screenFactory ?? throw new ArgumentNullException(nameof(screenFactory));
    }

    /// <inheritdoc />
    public abstract Task<NavigationResult> Show();

Keyboard Shortcuts

Dependencies

• FractalDataWorks.UI.Rendering.Spectre - Page renderers for dashboard widgets
• FractalDataWorks.UI.Components - Page model interfaces (DashboardPageModel, StatusWidget, etc.)
• FractalDataWorks.UI.Themes - Theme abstractions (IMenuTheme, MenuThemes collection)
• FractalDataWorks.Configuration.Abstractions - Configuration interfaces
• FractalDataWorks.Collections - TypeCollection base classes
• Spectre.Console - Terminal rendering
• Microsoft.Extensions.Hosting - Host builder and DI

See Also

• TypeCollections Overview
• Dispatcher Pattern