====== TUI-Razvoj ======

Pregled razvoja Terminal UI (TUI) za WvdS FPC RAD Studio.

<note>TUI-Rendering u WvdS postiže **GUI-sličnu kvalitetu**: flicker-free, Unicode-korektan, themeable, virtualiziran.</note>

===== Što je TUI? =====

Terminal User Interface (TUI) omogućuje grafička sučelja u terminalu:

  * **Tekstualni prikaz** - znakovi umjesto piksela
  * **Cross-Platform** - Radi na Windows Terminal, WezTerm, iTerm2, Linux Console
  * **Štedi resurse** - Idealno za servere, SSH, kontejnere
  * **Pristupačno** - Kompatibilno sa screenreaderima

===== Kada koristiti TUI =====

^ Slučaj korištenja ^ Preporučeno ^
| Server-Administracija | TUI |
| SSH-bazirani alati | TUI |
| Container/Docker | TUI |
| CI/CD Pipelines | TUI |
| Desktop-aplikacija s GUI | Desktop (LCL) |
| Web-aplikacija | Web (pas2js) |
| Oboje (Server + Desktop) | TUI + Desktop |

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

WVDS TUI-Standard se orijentira na **Ratatui-kvalitetu** ili bolju:

==== Karakteristike kvalitete ====

^ Karakteristika ^ Opis ^
| Flicker-free | Double-Buffering, Diff-based Flush |
| Unicode-korektan | Wide Chars, Emoji, Grapheme-aware Cursor |
| Themeable | Style Tokens, State Layering |
| Virtualiziran | Velike količine podataka efikasno renderirati |
| Responsive | Anchoring-first Layout, Resize-stabilan |
| Image-sposoban | Kitty/Sixel s Fallbackom |

==== Pregled arhitekture ====

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

===== Temeljni koncepti =====

==== Target-neutralni Modeli ====

Control-Modeli ne sadrže **nikakvu** Terminal-specifičnu logiku:

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

(* ZABRANJENO - Terminal-specifično u Modelu *)
TWvdSButton = class(TWvdSControl)
  procedure WriteAnsiSequence;  (* ZABRANJENO! *)
end;
</code>

==== Target-specifični Rendereri ====

Rendereri crtaju Model u 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 kao Default ====

Svaki Control ima **standardno** aktiviran Anchoring:

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

Default: Left+Top (stabilna pozicija)
Left+Right: Širina se rasteže s Parentom
Top+Bottom: Visina se rasteže s Parentom
Sva četiri: Rect se rasteže u oba smjera
</code>

===== Dokumentacija za TUI =====

^ Dokument ^ Sadržaj ^
| [[.:tui-engine|TUI Engine]] | CellBuffer, DiffEngine, Terminal Capabilities |
| [[.:tui-controls|TUI Controls]] | Implementacija Controla, Focus, Input |
| [[.:tui-layout|TUI Layout]] | Anchoring, Responsive, Breakpoints |

===== Brzi početak: Kreiranje TUI Controla =====

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

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

===== Verifikacija =====

Svaka TUI-implementacija mora se verificirati:

<code>
[ ] Nema flickera pri ponovljenom Repaintu
[ ] Resize proizvodi stabilan Layout
[ ] TextEdit Caret je stabilan kod Wide/Combining Chars
[ ] Table/List renderira 10k redaka s glatkim Scrollom
[ ] Images se ponašaju ispravno prema TerminalCaps
[ ] Focus ostaje stabilan kroz Reflow
</code>

===== Vidi također =====

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