take4-console 0.15.1 → 0.25.0

package/CHANGELOG.md

@@ -1,5 +1,365 @@
 # Changelog
 
+## [0.25.0] – 2026-04-18
+
+### Added — backlog P0-10 (InterfaceBuilder: register custom types)
+- **`InterfaceBuilder#registerType(name, factory)`** — rejestruje niestandardową
+  fabrykę kontrolki adresowalną przez `type: <name>` w YAML. Fabryka otrzymuje
+  surowy `YamlWindowDef` oraz `CustomTypeContext` z wstępnie zresolvowanym
+  `wp: WindowProperties`, aktywnym `registry: StyleRegistry` oraz pomocniczym
+  `resolveCallback(id)` przekierowującym do wcześniej zarejestrowanych
+  callbacków. Próba rejestracji pod nazwą wbudowanego typu rzuca wyjątkiem,
+  żeby uniknąć cichego shadowingu.
+- **`YamlWindowDef.props`** — wolne pole `Record<string, unknown>` forwardowane
+  w całości do fabryki; wbudowane typy je ignorują.
+- **Auto-focus registration** — jeśli fabryka zwróci `Window` z metodą
+  `handleKey()`, builder automatycznie rejestruje go w `WindowManager` razem
+  z łańcuchem rodziców, tak samo jak wbudowane `Button`/`TextBox`/itd.
+- **Eksporty**: nowe typy `CustomTypeContext` oraz `CustomTypeFactory` są
+  publicznie dostępne z `take4-console`.
+- **Demo**: w `src/demo.mts` rejestrowany jest custom typ `badge` (klasa
+  `Badge extends Window` malująca etykietę w render()), a `src/layout.yaml`
+  używa go w pasku nagłówka (`id: buildBadge`, `props: { text, color }`).
+
+## [0.24.0] – 2026-04-18
+
+### Added — backlog P0-3 (flex layout / auto-sizing)
+- **`WindowProperties.layout: 'absolute' | 'row' | 'column' | 'grid'`** — nowy,
+  per-okienny tryb layoutu dla bezpośrednich dzieci. Domyślnie `'absolute'`,
+  czyli dotychczasowe zachowanie (`Pos`/`Size` rozwiązuje każde dziecko
+  niezależnie). `'row'` i `'column'` uruchamiają silnik flex (rozdzielenie osi
+  głównej pro-rata `grow`, skurcz `shrink`, wyrównanie cross-axis), `'grid'`
+  rozkłada dzieci w równe komórki wiersz-po-wierszu.
+- **Nowe pola `WindowProperties`**: `gap` (odstęp między dziećmi w cellach),
+  `padding` (uniform number | `[v, h]` tuple | per-side record; wpływa na
+  `getInnerSize()` / `getInnerOffset()` — stackuje na border inset),
+  `gridColumns` (liczba kolumn dla `grid`), `alignItems`
+  (`start | center | end | stretch`, domyślnie `'stretch'`) oraz
+  `justifyContent` (`start | center | end | space-between | space-around`).
+- **`Pos.flex(order?)` / `Pos#getFlexOrder()`** — marker pozycji flex. Silnik
+  layoutu parenta ustawia finalne `child.x / child.y`; `order` sortuje dzieci
+  niezależnie od kolejności `addChild` (stabilne ties → kolejność wstawiania).
+- **`Size.flex(grow?, shrink?, basis?)` / `Size.content()`** oraz osobne
+  fabryki `flex()` i `content()` — `Size.flex(...)` zaznacza oba axes jako
+  flex (silnik decyduje który jest main vs cross na podstawie parenta),
+  `Size.content()` używa aktualnych wymiarów regionu dziecka jako naturalnego
+  rozmiaru. Dla mieszanych osi: `new Size(flex(), 10)` / `new Size(content(),
+  pct(50))`. `Size.isAbsolute()` zwraca `false` dla flex/content — `resolve()`
+  daje bezpieczny fallback (basis dla flex, 1 dla content) dopóki silnik nie
+  nadpisze wartości. Nowe gettery `getWidthSpec()` / `getHeightSpec()`.
+- **Silnik layoutu w `Window`** — `addChild` i `setSize` (→ `reflowChildren`)
+  delegują do `runLayout()`. Absolute path zachowany 1:1 dla back-compat;
+  row / column liczą basis, rozdzielają `remainder` przez `grow` (całkowite,
+  reszta od truncation trafia do ostatniego flex-a), skracają przy ujemnym
+  remainderze przez `shrink`, aplikują stretch/align cross-axis i — gdy nic
+  nie zjada slack'u — uruchamiają `justifyContent`. `grid` liczy równe komórki
+  `(inner - gap * (cols|rows - 1)) / (cols|rows)`. Niewidoczne dzieci są
+  pomijane, więc `setVisible(false)` wyjmuje je ze stacka.
+- **YAML (InterfaceBuilder)** — wspiera `pos: flex` / `pos: { flex: N }`,
+  `size: flex` / `size: content` / `size: { flex: { grow, shrink, basis } }`,
+  a także per-axis `size: { width: content, height: { flex: { grow: 2 } } }`.
+  Nowe pola `layout`, `gap`, `padding`, `gridColumns`, `alignItems`,
+  `justifyContent` na każdej definicji okna.
+- **`Window#blitChild`** czyta teraz `child.x / child.y` zamiast re-solve'ować
+  `posSpec`, więc absolute i flex lecą tym samym kodem kompozycji.
+
+### Demo
+- `src/layout.yaml` — dolny pasek akcji (Delete / Cancel /  Save) przekonwertowany
+  z trzech absolutnych pozycji na kontener `buttonRow` z `layout: row`,
+  `gap: 1`, `alignItems: stretch` i dzieckiem-spacerem `{ size: flex }` między
+  "Delete" a grupą "Cancel /  Save" — ten sam wygląd co wcześniej, zapisany
+  deklaratywnie, automatycznie re-flow przy SIGWINCH.
+
+## [0.23.0] – 2026-04-16
+
+### Added — backlog P0-5 (WindowManager.pause / resume)
+- **`WindowManager.pause(options?)` / `resume(options?)` / `isPaused()`** —
+  tymczasowo zwalnia kontrolę nad terminalem bez niszczenia focus tree,
+  rejestracji kontrolek ani stosu dialogów. `pause()` odłącza listener
+  stdin, wyłącza raw mode + mouse tracking, pokazuje kursor i opcjonalnie
+  (`{ leaveAltScreen: true }`) wychodzi z alt-screen buffer. `resume()`
+  re-enter-uje alt-screen (jeśli pause go zamknął), re-enable mouse,
+  ukrywa kursor z powrotem, re-attach stdin + raw mode i re-renderuje
+  klatkę (chyba że `{ rerender: false }`). Obie metody są idempotentne.
+  Typowe użycie: `pause({ leaveAltScreen: true })` → `spawnSync('$EDITOR')`
+  → `resume()`.
+- **`WindowManager.stop()`** rozpoznaje stan pauzy i nie powtarza teardownu
+  stdin / mouse / raw mode, które pause już zrobiła — unika podwójnego
+  `stdin.off('data', …)`. Reszta semantyki stop bez zmian.
+
+### Demo
+- `src/demo.mts` — `bindKey('ctrl+e')` pauzuje TUI (wychodzi z alt-screen),
+  drukuje prompt `--- paused … Press Enter to return ---`, blokuje na
+  `bash -c 'read -r _'` w podpowłoce i po `Enter` wywołuje `resume()`.
+  Focus, helpMode i historia sparkline-ów są zachowane przez cały cykl.
+- Status bar dostaje `Ctrl+E` w obu trybach (help / normal).
+
+## [0.22.0] – 2026-04-16
+
+### Added — backlog P0-8 (Window.setVisible)
+- **`Window.setVisible(visible: boolean)` / `Window.isVisible(): boolean`** —
+  ortogonalny do `disabled` przełącznik widoczności. Okna konstruują się
+  jako `visible: true`; `setVisible(false)` zamienia `render()` w no-op
+  (żadna faza `paintBackground → blitContent → paintBorder → children` się
+  nie odpala), a przy przeglądzie dzieci rodzic **pomija** ukryte dziecko,
+  więc jego dotychczasowy region nie jest blitowany — widoczne jest tło
+  rodzica. `getCell` na ukrytym oknie rzuca wyjątek; `setVisible(true)`
+  przywraca okno z nienaruszoną zawartością `content` (hide/show to
+  logiczne ukrycie, a nie kasowanie buforu).
+- **`WindowManager` respektuje widoczność** — nowy prywatny helper
+  `isFocusable(control)` = `!disabled && visible`. Tab / Shift-Tab,
+  `setFocus()`, auto-init focusa oraz mouse click hit-test pomijają
+  niewidoczne kontrolki tak samo, jak od dawna pomijają disabled.
+
+### Demo
+- `src/demo.mts` — `bindKey('v')` toggle'uje widoczność panelu
+  `chartsPanel` (Tabs). Status bar dostaje skrót `v` w trybie normal
+  i help, żeby feature był używalny bez sięgania do docs.
+
+## [0.21.0] – 2026-04-16
+
+### Added — backlog P0-6 (onChange / onSubmit / onKeyDown w TextBox + TextArea)
+- **`TextBoxProperties` / `TextAreaProperties`** rozszerzone o
+  `onChange(value)`, `onSubmit(value)` i `onKeyDown(key)` (pre-dispatch
+  hook z semantyką `boolean | void` — return `true` = consumed,
+  identycznie jak `WindowManagerOptions.onKey` z P0-4).
+- **`TextAreaProperties.insertTabAsSpaces`** (domyślnie `0`) — gdy
+  `> 0`, Tab wstawia N spacji zamiast cyklować focus; Shift-Tab
+  **zawsze** cykluje focus, dzięki czemu user ma kontrolowany escape
+  z multi-line input-a.
+- **`TextAreaProperties.ctrlDDeletesForward`** (domyślnie `false`) —
+  opt-in forward-delete pod `\x04`.
+- **`Focusable.capturesTab?()`** — opcjonalny hook sprawdzany przez
+  `WindowManager`. `TextArea` implementuje go tak, by zwracał `true`
+  wtedy i tylko wtedy gdy `insertTabAsSpaces > 0`.
+- **Settery**: `TextBox.setOnChange/SetOnSubmit/SetOnKeyDown`,
+  `TextArea.setOnChange/SetOnSubmit/SetOnKeyDown` — do wstrzykiwania
+  callbacków po konstrukcji (np. przy YAML-buildowanych kontrolkach).
+- **YAML / `InterfaceBuilder`** — nowe pola `YamlWindowDef`:
+  `onSubmit`, `onKeyDown`, `insertTabAsSpaces`, `ctrlDDeletesForward`.
+  Callbacki wiązane przez istniejące `ib.registerCallback(id, fn)`.
+
+### Changed
+- **`TextBox.handleKey`**: Enter (`\r` / `\n` / `'enter'`) nie
+  wstawia znaku — odpala `onSubmit(value)`.
+- **`TextArea.handleKey`**: alias `'ctrl+enter'` odpala `onSubmit`;
+  plain Enter bez zmian (wstawia newline).
+- **`WindowManager.handleInput`**: Tab najpierw pyta focused control
+  o `capturesTab()` — gdy odpowiedź to `true`, `handleKey('\t')`
+  dostaje klawisz zamiast standardowego `moveFocus(+1)`.
+
+### Demo
+- `layout.yaml` — `tbUsername` wiąże `onSubmit: usernameSubmitted`.
+- `src/demo.mts` — registerCallback `usernameSubmitted` dopisuje
+  event do log-u po Enter w polu username.
+
+## [0.20.0] – 2026-04-16
+
+### Added — backlog P0-4 (onKey preventDefault + kolejność)
+- **`WindowManagerOptions.onKey`** — nowa sygnatura
+  `(key: string, ctx: KeyContext) => boolean | void`. Zwrot `true`
+  *konsumuje* klawisz: pomija exit-key check, Tab/Shift-Tab navigation
+  i dispatch do focused control. Zwrot `void` / `false` zachowuje
+  dotychczasowe pass-through — istniejący kod działa bez zmian.
+- **`KeyContext`** — nowy typ publiczny: `{ focusedControl, inDialog,
+  dialogDepth }`. Snapshot wzięty przed wywołaniem global handlerów,
+  więc widzą spójny widok focus / dialog stack.
+- **`WindowManager.bindKey(keySpec, handler)` / `unbindKey(keySpec, handler?)`**
+  — register-based alternative dla global shortcut-ów. `bindKey` zwraca
+  unbind-funkcję. `keySpec` akceptuje raw strings, nazwy (`enter`,
+  `space`, `esc`, strzałki, `pageup/down`, `home/end`, …) oraz
+  `ctrl+<letter>`. Wiele handlerów pod jeden klawisz — fire w kolejności
+  rejestracji aż pierwszy zwróci `true`.
+- **`KeyBindHandler`** — typ publiczny: `(ctx: KeyContext) => boolean | void`.
+
+### Changed
+- **Kolejność dispatchu** w `WindowManager.handleInput` — global
+  handlery (`bindKey` → `onKey`) **przed** exit-key check / Tab /
+  dispatch. Dzięki temu global shortcut może zablokować `q` exit
+  (np. confirmation dialog), a TextBox nie "połyka" `?` / `:` / itp.
+- **Demo (`src/demo.mts`)** — `bindKey('?')` toggluje help mode
+  w status barze; `bindKey('ctrl+r')` wymusza `tick()` out-of-band.
+  Status bar stale pokazuje skrót `?` zamiast tylko `q`.
+
+## [0.19.0] – 2026-04-16
+
+### Added — backlog P0-11 (Screen alt-screen + hide-cursor opcja)
+- **`ScreenOptions`** — nowy interfejs publiczny: `altScreen?`, `hideCursor?`,
+  `targetFps?`. `new Screen({ altScreen: true, hideCursor: true })` sam
+  wchodzi w alt-screen buffer i ukrywa kursor — koniec boilerplate'u dla
+  konsumentów-bez-WindowManagera.
+- **`Screen.enterAltScreen` / `exitAltScreen` / `hideHardwareCursor` /
+  `showHardwareCursor`** + odpowiadające `is…` queries. Wszystkie idempotentne;
+  pozwalają zewnętrznemu kodowi (w tym `WindowManager`-owi) dzielić ten sam
+  state machine.
+- **`Screen.dispose`** — przywraca każdą zmianę w stanie terminala i
+  odpina listenery sygnałów. Idempotentne. Połączone z `process.on('exit')`,
+  więc cleanup last-chance odpalą się też przy `process.exit()` /
+  naturalnym end-of-loop.
+- **`Screen.getTargetFps`** — soft cap z `ScreenOptions` zwracany do inspekcji
+  (pełny enforcement w P2-47).
+
+### Added — backlog P0-12 (SIGWINCH autoresize + event)
+- **`Screen` event API**: `screen.on('resize', listener)` i
+  `screen.on('frame', listener)` (typed overloads). Pod spodem
+  composed `EventEmitter`, więc Window class hierarchy zostaje płaska.
+- **`Screen.resize(width?, height?)`** — pobiera nowe wymiary z
+  `process.stdout` (lub z explicit args), reflowuje dzieci procentowe,
+  emituje `'resize'`. Wywoływane automatycznie przez SIGWINCH handler.
+- **`render()`** mierzy wall-clock i emituje `'frame'` z `{ ms }`
+  po każdym wywołaniu — daje hak do telemetrii FPS / animation loopów.
+- **`Window.setSize(width, height)`** — publiczny wrapper na
+  `resizeRegions` (zmienione z `private` na `protected`). Reflowuje
+  dzieci procentowe pod nowy parent area.
+
+### Changed
+- **`WindowManager.run/stop`** — używa `screen.enterAltScreen` /
+  `hideHardwareCursor` zamiast pisać escape'y wprost. Tracking ownership
+  przez `ownsAltScreen` / `ownsCursor`: jeżeli `Screen` ustawił stan
+  w konstruktorze (`ScreenOptions`), `stop()` go nie wycofuje — alt-screen
+  przeżywa restart WM-a aż do `Screen.dispose()`.
+- **Demo (`src/demo.mts`)** — `new Screen({ altScreen: true, hideCursor: true })`,
+  `screen.on('resize', …)` aktualizujący status bar i wykonujący `screen.render()`,
+  `screen.dispose()` w `onExit` callbacku WindowManagera. Status bar wydzielony
+  jako `redrawStatusBar()` żeby etykieta `${width}×${height}` mogła być
+  przerysowana po resize.
+- **`Screen` listener cap** — statyczny licznik aktywnych instancji bumpuje
+  `process.setMaxListeners(10 + n*2)`, dispose dekrementuje. Eliminuje
+  `MaxListenersExceededWarning` w suite-ach testowych z wieloma `new Screen()`.
+
+### Tests
+- 9 nowych testów w `tests/Screen.test.mts` (ScreenOptions, dispose,
+  resize, frame event) + `afterEach(dispose)`.
+- 1 nowy test w `tests/WindowManager.test.mts` (lifecycle: brak podwójnego
+  toggle dla alt-screen i kursora) + `afterEach(dispose)`.
+- Pełna suita: 499 testów, wszystkie zielone.
+
+### Docs
+- Dodano `doc/p0-11-and-p0-12-screen-lifecycle.md` — pełny opis API,
+  cyklu życia, interakcji z WindowManager, backwards compatibility i
+  zmienionych plików.
+
+## [0.18.0] – 2026-04-16
+
+### Added — backlog P0-2 (rich text / multi-style writeText)
+- **`Window.writeText`** akceptuje teraz `WriteTextInput = string | WriteTextSegment[]`.
+  Segmenty są renderowane inline — kursor „płynie" przez kolejne segmenty bez
+  resetowania X, więc info-bary, history rows czy command completion nie
+  wymagają ręcznego liczenia pozycji. Każdy segment może podać własny
+  `style: StyleId` (mergowany z base) albo `attrs: CellAttributes` (rejestrowane
+  ad hoc w `StyleRegistry`). Pusta tablica jest no-opem.
+- **`Window.writeMarkup(template, options?)`** — mini-markup `{name}…{/}` dla
+  nazwanych stylów z `StyleRegistry`. Tagi wspierają zagnieżdżanie
+  (wewnętrzny styl jest mergowany na zewnętrzny), `{/}` zamyka najbliższy
+  otwarty tag, `{{` / `}}` to escape literalnych nawiasów klamrowych, nieznane
+  nazwy nie zmieniają stylu. Template kompilowany jest do `WriteTextSegment[]`
+  i puszczany przez `writeText`, więc layout/width/clipping idą tą samą ścieżką.
+- **`WriteTextSegment`**, **`WriteTextInput`** — nowe typy publiczne w
+  `src/Screen/types.mts`, eksportowane z `take4-console` barrel-a.
+
+### Changed
+- **`Window.writeText` pętla renderująca**: zachowana (East-Asian width,
+  zero-width skip, sentinel `''` dla wide chars, clipping). Dodano zewnętrzną
+  pętlę po segmentach i jednorazowe policzenie bazowego stylu.
+- **Demo (`src/demo.mts`)** — nagłówek ekranu używa `writeMarkup` z nazwanymi
+  stylami `hdr:app` / `hdr:mode` / `hdr:sep` (rejestrowane przez
+  `Screen.setBuiltinStyle`). Status bar przeszedł na segmentowy `writeText`
+  z inline'owymi skrótami, separatorem i sekcją dim pokazującą emoji/CJK
+  (double-width) — cała linia jednym wywołaniem.
+
+### Docs
+- Dodano `doc/p0-2-rich-text-writetext.md` — pełny opis API, algorytmu,
+  gramatyki markup-u i kompatybilności wstecznej.
+
+## [0.17.0] – 2026-04-16
+
+### Added — backlog P0-7 (text measurement z East-Asian width)
+- **`src/Screen/textWidth.mts`** — nowy moduł z funkcjami `charWidth(cp)`,
+  `stringWidth(str)`, `setPuaWidth(1|2)`, `getPuaWidth()`. Tabela szerokości
+  oparta o Unicode East Asian Width (kategorie W i F) plus zero-width
+  control / combining / format / variation selectors / ZWJ / BOM.
+- **`Window.getTextWidth(text)`** — zwraca display width tekstu w komórkach
+  terminala, odpowiednik `stringWidth` dostępny na każdym Window/kontrolce.
+- **`Window.writeText`** uwzględnia szerokość znaków:
+  - znaki szerokie (CJK, emoji, double-width NerdFonts) zajmują dwie kolejne
+    komórki — `''` w komórce kontynuacyjnej jako sentinel;
+  - kursor wewnątrz pętli zaawansowuje się o `charWidth(ch)`;
+  - znaki o szerokości 0 (combining, control) są pomijane;
+  - wide znaki, których prawa połówka wykraczałaby poza inner-width, są
+    pomijane w całości (zachowanie alignmentu).
+- **`Screen.render`** pomija continuation cells (`ch === ''`), dzięki czemu
+  ANSI output nie emituje stub'a — terminal po wide znaku już ma kursor
+  zaawansowany o 2 kolumny.
+- **Konfigurowalna szerokość PUA** (NerdFonts) przez `setPuaWidth(1|2)` —
+  domyślnie `1` (większość patched fontów ma single-cell glyphs).
+- Eksportowane z `take4-console` barrel-a: `charWidth`, `stringWidth`,
+  `setPuaWidth`, `getPuaWidth`.
+
+### Changed
+- **Demo (`src/demo.mts`)** — kilka templates eventów ma double-width
+  emoji (`'cache warmed 🚀'`, `'job completed 💾'`); demo prezentuje, że
+  wide glyphs nie psują wyrównania w `ListBox` (przy emoji surrogate-pair,
+  gdzie `length=2 = displayWidth=2`).
+
+### Added — backlog P0-9 (rozszerzenie BorderStyle)
+- **`BorderStyle`** rozszerzony o cztery nowe warianty:
+  - `'thick'` — heavy box-drawing (`━┃┏┓┗┛`),
+  - `'dashed'` — dashed lines z light corners (`╌╎┌┐└┘`),
+  - `'ascii'` — fallback ASCII (`-|+`),
+  - `'none'` — jawny placeholder równoważny brakowi ramki (bez insetów).
+- **`BorderChars`** — nowy interfejs publiczny opisujący komplet glifów
+  (krawędzie, narożniki, opcjonalne T-junctions i cross dla
+  przyszłych kontrolek typu Table).
+- **`WindowBorder.chars?: Partial<BorderChars>`** — per-glyph override
+  aplikowany na bazowy zestaw wybranego `style`. Pozwala podmienić tylko
+  wybrane znaki (np. narożniki) bez redefiniowania całej tabeli.
+- Eksportowane z `take4-console` barrel-a: typ `BorderChars`.
+
+### Changed — backlog P0-9
+- **`Window.borderInset`** traktuje `style: 'none'` jako brak ramki —
+  `getInnerOffset()` / `getInnerSize()` nie odejmują 1 cell-a po stronach.
+- **`Window.paintBorder`** mergeuje `border.chars` na bazowy zestaw
+  (`{ ...baseChars, ...border.chars }`) i przerywa się natychmiast dla
+  `'none'`.
+- **Internal `BORDER_CHARS`** używa pełnych nazw glifów z `BorderChars`
+  (`horizontal`/`vertical`/`topLeft`/…) zamiast wcześniejszych skrótów
+  (`h`/`v`/`tl`/…). Pole jest prywatne — bez wpływu na konsumentów.
+- **Demo (`src/layout.yaml`)** — `monitorPanel` używa `style: thick`,
+  `eventsPanel` używa `style: dashed`, `leftPanel` demonstruje override
+  pojedynczych glifów (`chars: { topLeft: '◆', topRight: '◆' }`).
+
+### Docs
+- Dodano `doc/p0-7-text-width.md` — pełny opis API, algorytmu sentinela
+  continuation cell, tabel Unicode i kompatybilności wstecznej.
+- Dodano `doc/p0-9-border-styles.md` — opis nowych stylów, tabela
+  glifów, semantyka `'none'` i przykłady override `chars`.
+
+## [0.16.0] – 2026-04-16
+
+### Added — backlog P0-1 (custom per-row rendering w ListBox)
+- **`ListBox<T>` jest teraz generyczny** — element listy może być dowolnym typem
+  (domyślnie `string`, co zachowuje wsteczną kompatybilność). `ListBoxProperties<T>`,
+  `setItems(items: T[])`, `getSelectedItem(): T | undefined`, `onChange(idx, item: T)`.
+- **`renderItem(item, ctx): string | ListBoxRowSegment[]`** — opcjonalny per-row
+  renderer. Obsługuje segmenty z wyrównaniem `left` / `right` / `fill`; style
+  segmentów są mergowane ze stylem bazowym wiersza (tło selekcji pozostaje widoczne).
+- **`rowHeight`** — wysokość slotu w komórkach (domyślnie 1). `handleKey` PgUp/PgDn
+  uwzględnia liczbę widocznych slotów, nie surowych wierszy.
+- **`keyFn`** — stały klucz per-item, dostępny przez `getItemKey(item)`; przechowywany
+  pod kątem późniejszej reconciliation w `setItems()`.
+- **`setRenderItem(fn)`** — podmiana renderera po konstrukcji.
+- Nowe typy w `src/Screen/types.mts`: `ListBoxRenderContext`, `ListBoxRowSegment`,
+  `ListBoxRowSegments`. Eksportowane z `take4-console` barrel-a.
+
+### Changed
+- **Demo (`src/demo.mts` + `src/layout.yaml`)** — lista zdarzeń (`eventsList`) to teraz
+  `ListBox<EventRow>` z customowym rendererem pokazującym kolorowe ikony (✓/⚠/✖),
+  wyciemniony timestamp i licznik wyrównany do prawej krawędzi.
+
+### Docs
+- Dodano `doc/p0-1-listbox-custom-render.md` — pełny opis API, algorytmu
+  renderowania segmentów i kompatybilności wstecznej.
+
 ## [0.15.1] – 2026-04-12
 
 ### Fixed

package/dist/Screen/InterfaceBuilder.d.mts

@@ -1,3 +1,4 @@
+import type { CustomTypeFactory } from './types.mjs';
 import { Window } from './Window.mjs';
 import { Screen } from './Screen.mjs';
 import { WindowManager } from './WindowManager.mjs';
@@ -5,9 +6,11 @@ import { WindowManager } from './WindowManager.mjs';
  *
  * Usage:
  *   1. Create an InterfaceBuilder and call registerCallback() for any onPress/onChange IDs.
- *   2. Call build(yamlText, screen) or buildFromFile(path, screen).
- *   3. Optionally pass a WindowManager to automatically register all focusable controls.
- *   4. The returned Map<string, Window> gives access to windows by their YAML id.
+ *   2. Optionally call registerType(name, factory) to teach the builder about
+ *      user-defined controls addressable via `type: <name>` in YAML.
+ *   3. Call build(yamlText, screen) or buildFromFile(path, screen).
+ *   4. Optionally pass a WindowManager to automatically register all focusable controls.
+ *   5. The returned Map<string, Window> gives access to windows by their YAML id.
  *
  * YAML schema:
  *   windows:
@@ -22,10 +25,18 @@ import { WindowManager } from './WindowManager.mjs';
  */
 export declare class InterfaceBuilder {
     private callbacks;
-    /** Creates an InterfaceBuilder with an empty callback registry. */
+    private customTypes;
+    /** Creates an InterfaceBuilder with empty callback and custom-type registries. */
     constructor();
     /** Registers a named callback for use with onPress or onChange in YAML definitions. */
     registerCallback(id: string, fn: (...args: unknown[]) => void): void;
+    /** Registers a custom control factory addressable by `type: <name>` in YAML.
+     *  The factory receives the raw YAML node plus a context with pre-resolved
+     *  `wp` (WindowProperties), the style registry, and a callback resolver.
+     *  Custom names cannot override a built-in type tag. If the returned window
+     *  implements Focusable, it is auto-registered with WindowManager (when one
+     *  is supplied to `build()`). */
+    registerType(name: string, factory: CustomTypeFactory): void;
     /** Builds the UI from a YAML string, adds all top-level windows to Screen,
      *  and registers focusable controls with WindowManager if provided.
      *  Styles defined in the `styles:` section are registered before any windows are built.

package/dist/Screen/InterfaceBuilder.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"InterfaceBuilder.d.mts","sourceRoot":"","sources":["../../src/Screen/InterfaceBuilder.mts"],"names":[],"mappings":"AAYA,OAAO,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AACtC,OAAO,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AACtC,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAsFpD;;;;;;;;;;;;;;;;;;GAkBG;AACH,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,SAAS,CAA4C;IAE7D,mEAAmE;;IAKnE,uFAAuF;IAChF,gBAAgB,CAAC,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,IAAI,GAAG,IAAI;IAI3E;;;4EAGwE;IACjE,KAAK,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,EAAE,CAAC,EAAE,aAAa,GAAG,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC;IAmCvF,+DAA+D;IAClD,aAAa,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,EAAE,CAAC,EAAE,aAAa,GAAG,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAO9G;;yEAEqE;IACrE,OAAO,CAAC,SAAS;IAoNjB,8EAA8E;IAC9E,OAAO,CAAC,WAAW;CAOpB"}
+{"version":3,"file":"InterfaceBuilder.d.mts","sourceRoot":"","sources":["../../src/Screen/InterfaceBuilder.mts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAUV,iBAAiB,EAElB,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AACtC,OAAO,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AACtC,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAiIpD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,SAAS,CAA8C;IAC/D,OAAO,CAAC,WAAW,CAAiC;IAEpD,kFAAkF;;IAMlF,uFAAuF;IAChF,gBAAgB,CAAC,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,IAAI,GAAG,IAAI;IAI3E;;;;;qCAKiC;IAC1B,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,iBAAiB,GAAG,IAAI;IAOnE;;;4EAGwE;IACjE,KAAK,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,EAAE,CAAC,EAAE,aAAa,GAAG,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC;IAmCvF,+DAA+D;IAClD,aAAa,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,EAAE,CAAC,EAAE,aAAa,GAAG,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAO9G;;yEAEqE;IACrE,OAAO,CAAC,SAAS;IAqPjB,8EAA8E;IAC9E,OAAO,CAAC,WAAW;CAOpB"}

package/dist/Screen/InterfaceBuilder.mjs

@@ -2,7 +2,7 @@ import { parse } from 'yaml';
 import { readFile } from 'node:fs/promises';
 import { Window } from './Window.mjs';
 import { Pos, pct } from './Pos.mjs';
-import { Size } from './Size.mjs';
+import { Size, flex, content } from './Size.mjs';
 import { getRegistry } from './RegistryHolder.mjs';
 import { Button } from './controls/Button.mjs';
 import { TextBox } from './controls/TextBox.mjs';
@@ -18,6 +18,21 @@ import { ListBox } from './controls/ListBox.mjs';
 import { Tabs } from './controls/Tabs.mjs';
 import { Sparkline } from './controls/Sparkline.mjs';
 import { Spinner } from './controls/Spinner.mjs';
+// ── Internal helpers ──────────────────────────────────────────────────────────
+/** Reserved `type:` tags owned by the built-in widget switch — custom factories
+ *  cannot override these. */
+/** Structural check: returns true when the window opts into keyboard input by
+ *  exposing `handleKey` (on top of the focus helpers inherited from Window).
+ *  Used to auto-register custom-type controls with WindowManager. */
+function isFocusable(win) {
+    const w = win;
+    return typeof w.handleKey === 'function';
+}
+const BUILTIN_TYPE_NAMES = new Set([
+    'window', 'button', 'textbox', 'textarea', 'checkbox', 'radio',
+    'statusled', 'progressbar', 'progressbarv', 'linechart', 'barchart',
+    'listbox', 'tabs', 'sparkline', 'spinner',
+]);
 /** Converts a YamlAxisValue ("N%", or a number) to a number or Pct instance. */
 function parseAxisValue(v) {
     if (typeof v === 'string') {
@@ -42,6 +57,8 @@ function parsePos(spec) {
         return Pos.bottomLeft();
     if (spec === 'bottomRight')
         return Pos.bottomRight();
+    if (spec === 'flex')
+        return Pos.flex();
     if (typeof spec === 'object') {
         if ('preset' in spec) {
             const off = spec.offset !== undefined ? parseAxisValue(spec.offset) : 0;
@@ -52,23 +69,52 @@ function parsePos(spec) {
                 case 'bottom': return Pos.bottom(off);
             }
         }
+        if ('flex' in spec) {
+            return Pos.flex(spec.flex ?? 0);
+        }
         if ('x' in spec && 'y' in spec) {
             return new Pos(parseAxisValue(spec.x), parseAxisValue(spec.y));
         }
     }
     throw new Error(`Invalid pos spec: ${JSON.stringify(spec)}`);
 }
+/** Converts a single axis value within a Size spec — extends the plain-axis
+ *  parser with the 'flex' / 'content' shorthands and the `{ flex: {...} }` /
+ *  `{ content: true }` objects so each axis can be chosen independently. */
+function parseDimValue(v) {
+    if (v === 'flex')
+        return flex();
+    if (v === 'content')
+        return content();
+    if (typeof v === 'object' && v !== null) {
+        if ('flex' in v) {
+            const basis = v.flex.basis !== undefined ? parseAxisValue(v.flex.basis) : 0;
+            return flex(v.flex.grow ?? 1, v.flex.shrink ?? 1, basis);
+        }
+        if ('content' in v && v.content === true)
+            return content();
+    }
+    return parseAxisValue(v);
+}
 /** Converts a YamlSizeSpec to a Size instance. */
 function parseSize(spec) {
     if (spec === 'fill')
         return Size.fill();
+    if (spec === 'flex')
+        return Size.flex();
+    if (spec === 'content')
+        return Size.content();
     if (typeof spec === 'object') {
         if ('fillWidth' in spec)
             return Size.fillWidth(parseAxisValue(spec.fillWidth));
         if ('fillHeight' in spec)
             return Size.fillHeight(parseAxisValue(spec.fillHeight));
+        if ('flex' in spec) {
+            const basis = spec.flex.basis !== undefined ? parseAxisValue(spec.flex.basis) : 0;
+            return Size.flex(spec.flex.grow ?? 1, spec.flex.shrink ?? 1, basis);
+        }
         if ('width' in spec && 'height' in spec) {
-            return new Size(parseAxisValue(spec.width), parseAxisValue(spec.height));
+            return new Size(parseDimValue(spec.width), parseDimValue(spec.height));
         }
     }
     throw new Error(`Invalid size spec: ${JSON.stringify(spec)}`);
@@ -88,9 +134,11 @@ function resolveBackground(bg) {
  *
  * Usage:
  *   1. Create an InterfaceBuilder and call registerCallback() for any onPress/onChange IDs.
- *   2. Call build(yamlText, screen) or buildFromFile(path, screen).
- *   3. Optionally pass a WindowManager to automatically register all focusable controls.
- *   4. The returned Map<string, Window> gives access to windows by their YAML id.
+ *   2. Optionally call registerType(name, factory) to teach the builder about
+ *      user-defined controls addressable via `type: <name>` in YAML.
+ *   3. Call build(yamlText, screen) or buildFromFile(path, screen).
+ *   4. Optionally pass a WindowManager to automatically register all focusable controls.
+ *   5. The returned Map<string, Window> gives access to windows by their YAML id.
  *
  * YAML schema:
  *   windows:
@@ -105,14 +153,28 @@ function resolveBackground(bg) {
  */
 export class InterfaceBuilder {
     callbacks;
-    /** Creates an InterfaceBuilder with an empty callback registry. */
+    customTypes;
+    /** Creates an InterfaceBuilder with empty callback and custom-type registries. */
     constructor() {
         this.callbacks = new Map();
+        this.customTypes = new Map();
     }
     /** Registers a named callback for use with onPress or onChange in YAML definitions. */
     registerCallback(id, fn) {
         this.callbacks.set(id, fn);
     }
+    /** Registers a custom control factory addressable by `type: <name>` in YAML.
+     *  The factory receives the raw YAML node plus a context with pre-resolved
+     *  `wp` (WindowProperties), the style registry, and a callback resolver.
+     *  Custom names cannot override a built-in type tag. If the returned window
+     *  implements Focusable, it is auto-registered with WindowManager (when one
+     *  is supplied to `build()`). */
+    registerType(name, factory) {
+        if (BUILTIN_TYPE_NAMES.has(name)) {
+            throw new Error(`Cannot register custom type "${name}": name is reserved by a built-in type.`);
+        }
+        this.customTypes.set(name, factory);
+    }
     /** Builds the UI from a YAML string, adds all top-level windows to Screen,
      *  and registers focusable controls with WindowManager if provided.
      *  Styles defined in the `styles:` section are registered before any windows are built.
@@ -168,6 +230,12 @@ export class InterfaceBuilder {
             focused: def.focused,
             disabled: def.disabled,
             label: def.label,
+            layout: def.layout,
+            gap: def.gap,
+            padding: def.padding,
+            gridColumns: def.gridColumns,
+            alignItems: def.alignItems,
+            justifyContent: def.justifyContent,
         };
         let win;
         switch (def.type ?? 'window') {
@@ -183,9 +251,15 @@ export class InterfaceBuilder {
             }
             case 'textbox': {
                 wp.size = wp.size ?? this.requireSize(def);
+                const tbChange = def.onChange ? this.callbacks.get(def.onChange) : undefined;
+                const tbSubmit = def.onSubmit ? this.callbacks.get(def.onSubmit) : undefined;
+                const tbKeyDown = def.onKeyDown ? this.callbacks.get(def.onKeyDown) : undefined;
                 const tb = new TextBox(wp, {
                     value: def.value,
                     placeholder: def.placeholder,
+                    onChange: tbChange,
+                    onSubmit: tbSubmit,
+                    onKeyDown: tbKeyDown,
                 });
                 pending.push({ control: tb, parents: [...parentChain] });
                 win = tb;
@@ -193,9 +267,17 @@ export class InterfaceBuilder {
             }
             case 'textarea': {
                 wp.size = wp.size ?? this.requireSize(def);
+                const taChange = def.onChange ? this.callbacks.get(def.onChange) : undefined;
+                const taSubmit = def.onSubmit ? this.callbacks.get(def.onSubmit) : undefined;
+                const taKeyDown = def.onKeyDown ? this.callbacks.get(def.onKeyDown) : undefined;
                 const ta = new TextArea(wp, {
                     value: def.value,
                     placeholder: def.placeholder,
+                    onChange: taChange,
+                    onSubmit: taSubmit,
+                    onKeyDown: taKeyDown,
+                    insertTabAsSpaces: def.insertTabAsSpaces,
+                    ctrlDDeletesForward: def.ctrlDDeletesForward,
                 });
                 pending.push({ control: ta, parents: [...parentChain] });
                 win = ta;
@@ -320,8 +402,22 @@ export class InterfaceBuilder {
                 break;
             }
             default: {
-                wp.size = wp.size ?? this.requireSize(def);
-                win = new Window(wp);
+                const customFactory = def.type ? this.customTypes.get(def.type) : undefined;
+                if (customFactory) {
+                    const ctx = {
+                        wp,
+                        registry: getRegistry(),
+                        resolveCallback: (id) => (id ? this.callbacks.get(id) : undefined),
+                    };
+                    win = customFactory(def, ctx);
+                    if (isFocusable(win)) {
+                        pending.push({ control: win, parents: [...parentChain] });
+                    }
+                }
+                else {
+                    wp.size = wp.size ?? this.requireSize(def);
+                    win = new Window(wp);
+                }
                 break;
             }
         }