====== TUI-Entwicklung ======

Übersicht der Terminal UI (TUI) Entwicklung für WvdS FPC RAD Studio.

<note>TUI-Rendering in WvdS erreicht **GUI-ähnliche Qualität**: flicker-free, Unicode-korrekt, themeable, virtualisiert.</note>

===== Was ist TUI? =====

Terminal User Interface (TUI) ermöglicht grafische Oberflächen im Terminal:

  * **Textbasierte Darstellung** - Zeichen statt Pixel
  * **Cross-Platform** - Läuft auf Windows Terminal, WezTerm, iTerm2, Linux Console
  * **Ressourcenschonend** - Ideal für Server, SSH, Container
  * **Barrierearm** - Screenreader-kompatibel

===== Wann TUI verwenden =====

^ Anwendungsfall ^ Empfohlen ^
| Server-Administration | TUI |
| SSH-basierte Tools | TUI |
| Container/Docker | TUI |
| CI/CD Pipelines | TUI |
| Desktop-Anwendung mit GUI | Desktop (LCL) |
| Web-Anwendung | Web (pas2js) |
| Beides (Server + Desktop) | TUI + Desktop |

===== WVDS TUI-Standard =====

Der WVDS TUI-Standard orientiert sich an **Ratatui-Qualität** oder besser:

==== Qualitätsmerkmale ====

^ Merkmal ^ Beschreibung ^
| Flicker-free | Double-Buffering, Diff-based Flush |
| Unicode-korrekt | Wide Chars, Emoji, Grapheme-aware Cursor |
| Themeable | Style Tokens, State Layering |
| Virtualisiert | Große Datenmengen effizient rendern |
| Responsive | Anchoring-first Layout, Resize-stabil |
| Image-fähig | Kitty/Sixel mit Fallback |

==== Architektur-Überblick ====

<code>
┌─────────────────────────────────────────────────────────────┐
│  PXAML (Markup)                                             │
├─────────────────────────────────────────────────────────────┤
│  Control Model (TWvdS*) - Target-neutral                    │
├─────────────────────────────────────────────────────────────┤
│  TUI Renderer - Target-spezifisch                           │
├─────────────────────────────────────────────────────────────┤
│  Render Surface → CellBuffer → DiffEngine                   │
├─────────────────────────────────────────────────────────────┤
│  Terminal IO (ANSI Escape Sequences)                        │
└─────────────────────────────────────────────────────────────┘
</code>

===== Kernkonzepte =====

==== Target-neutrale Models ====

Control-Models enthalten **keine** Terminal-spezifische Logik:

<code pascal>
(* KORREKT - Target-neutral *)
TWvdSButton = class(TWvdSControl)
private
  FCaption: string;
  FOnClick: TNotifyEvent;
public
  property Caption: string read FCaption write SetCaption;
  property OnClick: TNotifyEvent read FOnClick write FOnClick;
end;

(* VERBOTEN - Terminal-spezifisch im Model *)
TWvdSButton = class(TWvdSControl)
  procedure WriteAnsiSequence;  (* VERBOTEN! *)
end;
</code>

==== Target-spezifische Renderer ====

Renderer zeichnen das Model in den CellBuffer:

<code pascal>
TWvdSTUIButtonRenderer = class(TWvdSTUIRenderer)
public
  procedure Measure(AControl: TWvdSControl; AAvail: TSize): TSize; override;
  procedure Paint(AControl: TWvdSControl; ASurface: TRenderSurface); override;
  function HandleInput(AControl: TWvdSControl; AEvent: TInputEvent): Boolean; override;
end;
</code>

==== Anchoring als Default ====

Jedes Control hat **standardmäßig** Anchoring aktiviert:

<code>
Anchors: Left, Top, Right, Bottom

Default: Left+Top (stabile Position)
Left+Right: Breite dehnt sich mit Parent
Top+Bottom: Höhe dehnt sich mit Parent
Alle vier: Rect dehnt sich in beide Richtungen
</code>

===== Dokumentation für TUI =====

^ Dokument ^ Inhalt ^
| [[.:tui-engine|TUI Engine]] | CellBuffer, DiffEngine, Terminal Capabilities |
| [[.:tui-controls|TUI Controls]] | Control-Implementierung, Focus, Input |
| [[.:tui-layout|TUI Layout]] | Anchoring, Responsive, Breakpoints |

===== Schnellstart: TUI Control erstellen =====

==== 1. Model Unit (target-neutral) ====

<code pascal>
unit WvdS.UI.Controls.MyControl;

type
  TWvdSMyControl = class(TWvdSControl)
  private
    FValue: string;
  public
    property Value: string read FValue write SetValue;
  end;
</code>

==== 2. TUI Renderer Unit ====

<code pascal>
unit WvdS.UI.TUI.Renderers.MyControl;

type
  TWvdSTUIMyControlRenderer = class(TWvdSTUIRenderer)
  public
    procedure Measure(AControl: TWvdSControl; AAvail: TSize): TSize; override;
    procedure Paint(AControl: TWvdSControl; ASurface: TRenderSurface); override;
  end;
</code>

==== 3. Pack Manifest ====

<code javascript>
{
  "id": "mycontrol",
  "renderers": {
    "tui": {
      "unit": "WvdS.UI.TUI.Renderers.MyControl",
      "class": "TWvdSTUIMyControlRenderer"
    }
  },
  "targetCaps": {
    "requires": ["keyboard"],
    "optional": ["mouse"]
  }
}
</code>

===== Verifikation =====

Jede TUI-Implementierung muss verifiziert werden:

<code>
[ ] Kein Flicker bei wiederholtem Repaint
[ ] Resize produziert stabiles Layout
[ ] TextEdit Caret ist stabil bei Wide/Combining Chars
[ ] Table/List rendert 10k Rows mit smooth Scroll
[ ] Images verhalten sich korrekt per TerminalCaps
[ ] Focus bleibt stabil durch Reflow
</code>

===== Siehe auch =====

  * [[.:tui-engine|TUI Engine]]
  * [[.:tui-controls|TUI Controls]]
  * [[.:tui-layout|TUI Layout]]
  * [[.:targets|Build-Targets]]
  * [[.:control-entwicklung|Control-Entwicklung]]