====== Sviluppo TUI ======

Panoramica dello sviluppo Terminal UI (TUI) per WvdS FPC RAD Studio.

<note>Il rendering TUI in WvdS raggiunge **qualità simile alla GUI**: flicker-free, Unicode corretto, themeable, virtualizzato.</note>

===== Cos'è TUI? =====

Terminal User Interface (TUI) permette interfacce grafiche nel terminale:

  * **Rappresentazione testuale** - Caratteri invece di pixel
  * **Cross-platform** - Funziona su Windows Terminal, WezTerm, iTerm2, Linux Console
  * **Efficiente** - Ideale per server, SSH, container
  * **Accessibile** - Compatibile con screen reader

===== Quando usare TUI =====

^ Caso d'uso ^ Raccomandato ^
| Amministrazione server | TUI |
| Tool basati su SSH | TUI |
| Container/Docker | TUI |
| Pipeline CI/CD | TUI |
| Applicazione desktop con GUI | Desktop (LCL) |
| Applicazione web | Web (pas2js) |
| Entrambi (server + desktop) | TUI + Desktop |

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

Lo standard WVDS TUI si orienta alla **qualità Ratatui** o superiore:

==== Caratteristiche qualità ====

^ Caratteristica ^ Descrizione ^
| Flicker-free | Double buffering, flush basato su diff |
| Unicode corretto | Wide char, emoji, cursor grapheme-aware |
| Themeable | Token di stile, layering stati |
| Virtualizzato | Rendering efficiente grandi quantità dati |
| Responsive | Layout anchoring-first, stabile al resize |
| Supporto immagini | Kitty/Sixel con fallback |

==== Panoramica architettura ====

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

===== Concetti fondamentali =====

==== Model target-neutrali ====

I model dei controlli NON contengono logica specifica del terminale:

<code pascal>
(* CORRETTO - 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;

(* VIETATO - Specifico terminale nel model *)
TWvdSButton = class(TWvdSControl)
  procedure WriteAnsiSequence;  (* VIETATO! *)
end;
</code>

==== Renderer target-specifici ====

I renderer disegnano il model nel 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 come default ====

Ogni controllo ha l'anchoring **attivato per default**:

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

Default: Left+Top (posizione stabile)
Left+Right: larghezza si espande con il parent
Top+Bottom: altezza si espande con il parent
Tutti e quattro: rect si espande in entrambe le direzioni
</code>

===== Documentazione TUI =====

^ Documento ^ Contenuto ^
| [[.:tui-engine|TUI Engine]] | CellBuffer, DiffEngine, capability terminale |
| [[.:tui-controls|Controlli TUI]] | Implementazione controlli, focus, input |
| [[.:tui-layout|Layout TUI]] | Anchoring, responsive, breakpoint |

===== Quickstart: Creare un controllo TUI =====

==== 1. Unit Model (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. Unit TUI Renderer ====

<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>

===== Verifica =====

Ogni implementazione TUI deve essere verificata:

<code>
[ ] Nessun flicker al repaint ripetuto
[ ] Resize produce layout stabile
[ ] Cursore TextEdit stabile con wide/combining char
[ ] Table/List renderizza 10k righe con scroll fluido
[ ] Immagini si comportano correttamente per TerminalCaps
[ ] Focus rimane stabile durante reflow
</code>

===== Vedi anche =====

  * [[.:tui-engine|TUI Engine]]
  * [[.:tui-controls|Controlli TUI]]
  * [[.:tui-layout|Layout TUI]]
  * [[.:targets|Target di build]]
  * [[.:control-entwicklung|Sviluppo controlli]]