FractalDataWorks.TUI.Abstractions 0.1.0-preview.11

FractalDataWorks.TUI.Abstractions

Theme and renderer abstractions for the FractalDataWorks TUI menu system.

Overview

This package defines the contracts for building terminal-based user interfaces that are renderer-agnostic. It provides interfaces for page models, components, and a TypeCollection-based renderer system.

Installation

<PackageReference Include="FractalDataWorks.TUI.Abstractions" Version="x.x.x" />

Dependencies

• FractalDataWorks.Abstractions
• FractalDataWorks.Collections
• FractalDataWorks.UI.Abstractions
• FractalDataWorks.UI.Themes
• Spectre.Console

Key Types

Components

From IComponentModel.cs:6-48:

public interface IComponentModel
{
    string Id { get; }
    string? Label { get; }
    string? HelpText { get; }
    bool IsRequired { get; }
    bool IsReadOnly { get; }
    bool IsVisible { get; }
    int Order { get; }
    ValidationResult Validate();
}

From IInputComponentModel.cs:9-25:

public interface IInputComponentModel<T> : IComponentModel
{
    T? Value { get; set; }
    T? DefaultValue { get; }
    Func<T?, ValidationResult>? CustomValidator { get; }
}

Page Structure

From IPageModel.cs:9-35:

public interface IPageModel
{
    string Id { get; }
    string Title { get; }
    string? Description { get; }
    IReadOnlyList<ISectionModel> Sections { get; }
    IPageMode Mode { get; }
}

From ISectionModel.cs:8-34:

public interface ISectionModel
{
    string Id { get; }
    string? Title { get; }
    bool IsCollapsible { get; }
    bool IsExpanded { get; set; }
    IReadOnlyList<IColumnModel> Columns { get; }
}

From IColumnModel.cs:8-24:

public interface IColumnModel
{
    string Id { get; }
    int Width { get; }  // 1-12 grid system
    IReadOnlyList<IComponentModel> Components { get; }
}

Rendering

From IUIRenderer.cs:15-73:

public interface IUIRenderer : ITypeOption<int, UIRendererBase>
{
    bool SupportsInteractiveMode { get; }
    bool SupportsAnsiColors { get; }
    bool SupportsFocusManagement { get; }
    bool SupportsHotReload { get; }

    Task<RenderResult> Render(
        IComponentModel model,
        IRenderContext context,
        CancellationToken cancellationToken = default);

    Task<PromptResult<T>> Prompt<T>(
        IInputComponentModel<T> model,
        IRenderContext context,
        CancellationToken cancellationToken = default);

    Task<PageResult> RenderPage(
        IPageModel page,
        IRenderContext context,
        CancellationToken cancellationToken = default);
}

From IRenderContext.cs:8-44:

public interface IRenderContext
{
    IMenuTheme Theme { get; }
    RenderMode Mode { get; }
    int ConsoleWidth { get; }
    int ConsoleHeight { get; }
    bool SupportsAnsiColors { get; }
    bool SupportsUnicode { get; }
    string? FocusedComponentId { get; }
}

From RenderMode.cs:6-22:

public enum RenderMode
{
    Display = 0,
    Edit = 1,
    ReadOnly = 2
}

Result Types

From RenderResult.cs:6-34:

public sealed class RenderResult
{
    public bool Success { get; }
    public string? ErrorMessage { get; }

    public static RenderResult Ok() => new(true);
    public static RenderResult Fail(string errorMessage) => new(false, errorMessage);
}

From ValidationResult.cs:8-42:

public sealed class ValidationResult
{
    public bool IsValid { get; }
    public IReadOnlyList<string> Errors { get; }

    public static ValidationResult Valid() => new(true, null);
    public static ValidationResult Invalid(string error) => new(false, [error]);
    public static ValidationResult Invalid(IReadOnlyList<string> errors) => new(false, errors);
}

Architecture

IPageModel
├── Sections: IReadOnlyList<ISectionModel>
│   └── Columns: IReadOnlyList<IColumnModel> (12-column grid)
│       └── Components: IReadOnlyList<IComponentModel>

UIRenderers TypeCollection

From UIRenderers.cs:1-26:

[TypeCollection(typeof(UIRendererBase), typeof(IUIRenderer), typeof(UIRenderers))]
public partial class UIRenderers : TypeCollectionBase<UIRendererBase, IUIRenderer>
{
}

Access renderers by name or id:

var renderer = UIRenderers.ByName("Spectre");
var renderer = UIRenderers.ById(1);
var allRenderers = UIRenderers.All();

Implementing a Custom Renderer

From UIRendererBase.cs:16-63:

public abstract class UIRendererBase : TypeOptionBase<int, UIRendererBase>, IUIRenderer
{
    protected UIRendererBase(int id, string name) : base(id, name) { }

    public virtual bool SupportsInteractiveMode => false;
    public virtual bool SupportsAnsiColors => false;
    public virtual bool SupportsFocusManagement => false;
    public virtual bool SupportsHotReload => false;

    // Override these methods in your implementation
    public virtual Task<RenderResult> Render(...) { ... }
    public virtual Task<PromptResult<T>> Prompt<T>(...) { ... }
    public virtual Task<PageResult> RenderPage(...) { ... }
}

Renderer Implementations

• FractalDataWorks.UI.Rendering.Spectre - Spectre.Console renderer
• FractalDataWorks.UI.Components.RazorConsole - RazorConsole renderer

Related Packages

• FractalDataWorks.UI.Abstractions - Core UI abstractions including ISelectableComponentModel and IMultiSelectComponentModel
• FractalDataWorks.UI.Components - Concrete component implementations and PageModes TypeCollection
• FractalDataWorks.UI.Themes - Theme definitions for UI rendering