take4-console 0.15.0 → 0.25.0

package/src/Screen/types.mts

@@ -1,5 +1,7 @@
 import type { Pos } from './Pos.mjs';
 import type { Size } from './Size.mjs';
+import type { Window } from './Window.mjs';
+import type { StyleRegistry } from './StyleRegistry.mjs';
 
 /** Text and background color, expressed as ANSI color number (0–255) or hex string (e.g. '#ff0000'). */
 export type Color = number | string;
@@ -57,8 +59,63 @@ export interface TerminalSize {
   height: number;
 }
 
-/** Box-drawing character style for window borders. */
-export type BorderStyle = 'single' | 'double' | 'rounded';
+/** Constructor options for Screen. All fields are optional; defaults preserve
+ *  the pre-0.19.0 behaviour where Screen does not touch the terminal state on
+ *  construction (WindowManager.run/stop handle alt-screen and cursor hiding).
+ *  Setting any flag here lets a Screen-only consumer (no WindowManager) opt
+ *  into the same lifecycle semantics without writing the boilerplate by hand. */
+export interface ScreenOptions {
+  /** Switch to the terminal's alternate screen buffer on construction and
+   *  restore the primary buffer on dispose() / process exit. Default: false. */
+  altScreen?: boolean;
+  /** Hide the hardware cursor on construction and restore on dispose() /
+   *  process exit. Default: false. */
+  hideCursor?: boolean;
+  /** Soft cap on render frequency in frames per second. Stored on the Screen
+   *  for inspection; full enforcement (frame coalescing) lands with backlog
+   *  item P2-47. Default: undefined (uncapped). */
+  targetFps?: number;
+}
+
+/** Statistics emitted by the Screen 'frame' event after each render() call. */
+export interface ScreenFrameStats {
+  /** Wall-clock duration of the render() call in milliseconds. */
+  ms: number;
+}
+
+/** Box-drawing character style for window borders.
+ *  - 'single'  ─│┌┐└┘     classic light box drawing
+ *  - 'double'  ═║╔╗╚╝     double-line box drawing
+ *  - 'rounded' ─│╭╮╰╯     light box with rounded corners
+ *  - 'thick'   ━┃┏┓┗┛     heavy / bold box drawing
+ *  - 'dashed'  ╌╎┌┐└┘     dashed lines with light corners
+ *  - 'ascii'   -|+        plain ASCII fallback for non-Unicode terminals
+ *  - 'none'    placeholder equivalent to no border (no insets, no painting). */
+export type BorderStyle = 'single' | 'double' | 'rounded' | 'thick' | 'dashed' | 'ascii' | 'none';
+
+/** Glyphs used to draw a window border. The four corners and the two edge
+ *  characters are mandatory; T-junctions and the cross are optional and only
+ *  used by composite controls (tables, split panes) that draw inner lines. */
+export interface BorderChars {
+  /** Horizontal edge glyph (top and bottom rows). */
+  horizontal: string;
+  /** Vertical edge glyph (left and right columns). */
+  vertical: string;
+  topLeft: string;
+  topRight: string;
+  bottomLeft: string;
+  bottomRight: string;
+  /** T-junction joining a horizontal line to the right side of a vertical line. */
+  verticalLeft?: string;
+  /** T-junction joining a horizontal line to the left side of a vertical line. */
+  verticalRight?: string;
+  /** T-junction joining a vertical line to the bottom of a horizontal line. */
+  horizontalTop?: string;
+  /** T-junction joining a vertical line to the top of a horizontal line. */
+  horizontalBottom?: string;
+  /** Four-way intersection. */
+  cross?: string;
+}
 
 /** Per-side border configuration. */
 export interface WindowBorder {
@@ -70,6 +127,10 @@ export interface WindowBorder {
   style?:  BorderStyle;
   /** Border color. Default: inherits from cell. */
   color?:  Color;
+  /** Optional per-glyph overrides applied on top of the chosen `style`'s char set.
+   *  Useful for swapping individual characters (e.g. a custom corner) without
+   *  redefining the entire set. */
+  chars?:  Partial<BorderChars>;
 }
 
 /** Common properties shared by Window and all controls. Passed as the first constructor parameter. */
@@ -92,19 +153,92 @@ export interface WindowProperties {
   disabled?: boolean;
   /** Text label displayed by the control. Default: ''. */
   label?: string;
+  /** Layout algorithm applied to the direct children of this window. Default:
+   *  'absolute' (pre-0.24 behaviour — each child is positioned by its Pos/Size).
+   *  Setting this to 'row', 'column', or 'grid' enables flex-style auto-layout:
+   *  the engine distributes the inner area, honours `gap` / `padding` /
+   *  `alignItems` / `justifyContent`, and grows children with `Size.flex(...)`
+   *  to fill remaining space. */
+  layout?: LayoutMode;
+  /** Spacing (in cells) inserted between adjacent children when `layout` is
+   *  'row', 'column', or 'grid'. Ignored by 'absolute' layout. Default: 0. */
+  gap?: number;
+  /** Extra inset applied inside the border — children are laid out within the
+   *  padded inner area, and `getInnerSize()` / `getInnerOffset()` reflect the
+   *  padding as well as the border. Default: 0 on every side. */
+  padding?: PaddingSpec;
+  /** Number of columns for `layout: 'grid'`. Children are placed row-major,
+   *  so `gridColumns` implicitly determines the number of rows from the child
+   *  count. Default: 1. */
+  gridColumns?: number;
+  /** Cross-axis alignment for `layout: 'row'` or `layout: 'column'`.
+   *  Default: 'stretch' (children are stretched to fill the cross axis). */
+  alignItems?: AlignItems;
+  /** Main-axis distribution of leftover space for `layout: 'row'` / `'column'`
+   *  when no child consumes it via flex-grow. Default: 'start'. */
+  justifyContent?: JustifyContent;
 }
 
-/** Internal per-axis position spec used by Pos. */
+/** Internal per-axis position spec used by Pos.
+ *  - 'start' / 'end' / 'pct' / 'center' are resolved against the parent's
+ *    inner area by the regular absolute-layout path.
+ *  - 'flex' marks the child as belonging to a flex layout slot; the final
+ *    (x, y) is computed by the parent's layout engine (see `WindowProperties.layout`).
+ *    The `order` field lets users reorder flex children without changing the
+ *    addChild() insertion order. */
 export type AxisSpec =
   | { mode: 'start'; value: number }
   | { mode: 'end';   value: number }
   | { mode: 'pct';   value: number }
-  | { mode: 'center' };
-
-/** Internal per-axis size spec used by Size. */
+  | { mode: 'center' }
+  | { mode: 'flex';  order: number };
+
+/** Basis value stored inside `{ mode: 'flex' }` DimSpec entries. Supports
+ *  absolute pixel values and parent-relative percentages. */
+export type FlexBasis =
+  | { kind: 'abs'; value: number }
+  | { kind: 'pct'; value: number };
+
+/** Internal per-axis size spec used by Size.
+ *  - 'abs' / 'pct' mirror the pre-flex behaviour (fixed pixels or % of parent).
+ *  - 'flex' marks the child as a flex item; the parent's layout engine
+ *    distributes the inner area in proportion to `grow` and shrinks in
+ *    proportion to `shrink` when space is tight. `basis` is the starting
+ *    main-axis size before distribution (default `{ kind: 'abs', value: 0 }`).
+ *  - 'content' marks the child as auto-sized; the layout engine measures the
+ *    child's natural size (its current Region dimensions) and uses that. */
 export type DimSpec =
-  | { mode: 'abs'; value: number }
-  | { mode: 'pct'; value: number };
+  | { mode: 'abs';     value: number }
+  | { mode: 'pct';     value: number }
+  | { mode: 'flex';    grow: number; shrink: number; basis: FlexBasis }
+  | { mode: 'content' };
+
+/** Layout algorithm applied to a window's direct children.
+ *  - 'absolute' (default): each child is positioned/sized via its own Pos/Size,
+ *    matching the pre-0.24 behaviour — existing layouts continue to work unchanged.
+ *  - 'row'     : children flow horizontally; main axis = width, cross axis = height.
+ *  - 'column'  : children flow vertically;   main axis = height, cross axis = width.
+ *  - 'grid'    : children are placed in a uniform N-column grid (see `gridColumns`). */
+export type LayoutMode = 'absolute' | 'row' | 'column' | 'grid';
+
+/** Cross-axis alignment for flex layouts (row/column). Default: 'stretch'. */
+export type AlignItems = 'start' | 'center' | 'end' | 'stretch';
+
+/** Main-axis distribution of leftover space when no flex-grow child consumes it.
+ *  Default: 'start'. */
+export type JustifyContent = 'start' | 'center' | 'end' | 'space-between' | 'space-around';
+
+/** Resolved per-side padding values (in cells). */
+export interface Padding {
+  top:    number;
+  right:  number;
+  bottom: number;
+  left:   number;
+}
+
+/** User-supplied padding: a uniform number, a [vertical, horizontal] tuple, or
+ *  a partial per-side record (missing sides default to 0). */
+export type PaddingSpec = number | [number, number] | Partial<Padding>;
 
 /** Options for Window.writeText() – position defaults to (0, 0). */
 export interface WriteTextOptions {
@@ -112,10 +246,34 @@ export interface WriteTextOptions {
   x?: number;
   /** Row to start writing at. Default: 0. */
   y?: number;
-  /** Style ID registered in a StyleRegistry. Default: 0 (no style). */
+  /** Base style ID merged under every segment's style. Default: auto-picked
+   *  from disabled/focused/normal state (see Window.writeText()). */
+  style?: StyleId;
+}
+
+/** A single inline-styled segment accepted by Window.writeText(). The cursor
+ *  advances across consecutive segments without resetting, so segments flow
+ *  inline on the same row like a rich-text span.
+ *  - `style` is a pre-registered StyleId (merged with the base style).
+ *  - `attrs` is registered on the fly (convenience, avoids pre-registering).
+ *  - When both are present, `style` wins; when neither is present the base style applies. */
+export interface WriteTextSegment {
+  /** Literal text for this segment. May contain '\n' which resets the cursor
+   *  to the starting column and advances to the next row. */
+  text: string;
+  /** Optional pre-registered style ID merged with the base style. */
   style?: StyleId;
+  /** Optional inline CellAttributes; registered into the StyleRegistry automatically. */
+  attrs?: CellAttributes;
 }
 
+/** Input accepted by Window.writeText().
+ *  - A plain string keeps the pre-0.18.0 behaviour: one style for the whole text.
+ *  - An array of segments applies per-segment styles while the cursor flows across
+ *    them; each segment's style is merged with the base style.
+ *  - An empty array is a no-op. */
+export type WriteTextInput = string | WriteTextSegment[];
+
 /** Control-specific properties for the Button control. */
 export interface ButtonProperties {
   /** Called when the button is activated (Enter or Space while focused). */
@@ -130,6 +288,16 @@ export interface TextBoxProperties {
   placeholder?: string;
   /** Initial cursor position (character index). Default: end of value. */
   cursor?: number;
+  /** Fires after every value change driven by `handleKey` (typing, backspace,
+   *  delete, paste of a single char, …). Not fired by `setValue`. */
+  onChange?: (value: string) => void;
+  /** Fires when the user presses Enter (`\r` / `\n`) while the TextBox has
+   *  focus. The current value is passed unchanged. */
+  onSubmit?: (value: string) => void;
+  /** Pre-dispatch hook: runs before the built-in `handleKey` logic. Return
+   *  `true` to mark the key as handled — the default behaviour (inserting,
+   *  moving cursor, deleting, …) is then skipped. */
+  onKeyDown?: (key: string) => boolean | void;
 }
 
 /** Control-specific properties for the TextArea control. */
@@ -140,6 +308,22 @@ export interface TextAreaProperties {
   placeholder?: string;
   /** Initial cursor position. Default: { x: 0, y: 0 }. */
   cursor?: { x: number; y: number };
+  /** Fires after every value change driven by `handleKey`. Not fired by
+   *  `setValue`. */
+  onChange?: (value: string) => void;
+  /** Fires when the user submits — by default Ctrl+Enter. Plain Enter still
+   *  inserts a newline. */
+  onSubmit?: (value: string) => void;
+  /** Pre-dispatch hook: runs before the built-in `handleKey` logic. Return
+   *  `true` to short-circuit the default behaviour for this key. */
+  onKeyDown?: (key: string) => boolean | void;
+  /** When > 0, Tab inserts that many space characters instead of cycling
+   *  focus. When 0 (default) Tab passes through unchanged so the
+   *  WindowManager sees it. */
+  insertTabAsSpaces?: number;
+  /** When true, Ctrl+D deletes the character to the right of the cursor
+   *  (or joins with the next line at end of line). Default: false. */
+  ctrlDDeletesForward?: boolean;
 }
 
 /** Control-specific properties for the Checkbox control. */
@@ -202,14 +386,49 @@ export interface LineChartProperties {
   color?: number;
 }
 
-/** Control-specific properties for the ListBox control. */
-export interface ListBoxProperties {
+/** Context passed to ListBox.renderItem() for a single row. */
+export interface ListBoxRenderContext {
+  /** 0-based index of the item in the list. */
+  index: number;
+  /** Whether the owning ListBox currently has keyboard focus. */
+  focused: boolean;
+  /** Whether this particular row is the selected one. */
+  selected: boolean;
+  /** Inner width (in cells) available for the row. */
+  width: number;
+}
+
+/** A single styled text segment produced by ListBox.renderItem(). */
+export interface ListBoxRowSegment {
+  /** Literal text drawn into the row at the segment's computed position. */
+  text: string;
+  /** Optional style ID merged onto the row's base (selection) style. */
+  style?: StyleId;
+  /** Horizontal alignment within the row. Default: 'left'.
+   *  - 'left'  segments are laid out left-to-right from column 0.
+   *  - 'right' segments are flushed to the right edge of the row.
+   *  - 'fill'  segment occupies the remaining space between the left and right groups.
+   *    Only the first 'fill' segment in a row is honoured. */
+  align?: 'left' | 'right' | 'fill';
+}
+
+/** Return type of ListBox.renderItem(). A plain string is treated as a single left-aligned segment. */
+export type ListBoxRowSegments = string | ListBoxRowSegment[];
+
+/** Control-specific properties for the ListBox control. Generic over the item type. */
+export interface ListBoxProperties<T = string> {
   /** Initial items shown in the list. Default: []. */
-  items?: string[];
+  items?: T[];
   /** Initial selected index, or -1 for no selection. Default: 0 if items is non-empty, else -1. */
   selectedIndex?: number;
   /** Called when the selected index changes via handleKey(). */
-  onChange?: (index: number, item: string) => void;
+  onChange?: (index: number, item: T) => void;
+  /** Optional per-row renderer returning styled segments. Default: single text segment (item.toString()). */
+  renderItem?: (item: T, ctx: ListBoxRenderContext) => ListBoxRowSegments;
+  /** Row height in cells. Default: 1. Items occupy this many consecutive rows in the viewport. */
+  rowHeight?: number;
+  /** Stable key for reconciliation — currently stored only; future use: preserve scroll/selection across setItems(). */
+  keyFn?: (item: T) => string;
 }
 
 /** Control-specific properties for the Tabs control. */
@@ -265,21 +484,38 @@ export interface BarChartProperties {
 /** A single axis value: absolute number, edge-relative negative, or percentage string ("N%"). */
 export type YamlAxisValue = number | string;
 
-/** YAML position specification for a window. */
+/** YAML position specification for a window.
+ *  - Shorthand strings ('center', 'topLeft', …, 'flex') map to the matching
+ *    `Pos` static factory with no arguments.
+ *  - `{ preset, offset? }` maps to `Pos.top/left/right/bottom(offset)`.
+ *  - `{ flex: N }` is shorthand for `Pos.flex(N)` so authors can set a layout
+ *    order from YAML.
+ *  - `{ x, y }` defers to the two-argument `new Pos(x, y)` constructor. */
 export type YamlPosSpec =
-  | 'center' | 'topLeft' | 'topRight' | 'bottomLeft' | 'bottomRight'
+  | 'center' | 'topLeft' | 'topRight' | 'bottomLeft' | 'bottomRight' | 'flex'
   | { preset: 'top';    offset?: YamlAxisValue }
   | { preset: 'left';   offset?: YamlAxisValue }
   | { preset: 'right';  offset?: YamlAxisValue }
   | { preset: 'bottom'; offset?: YamlAxisValue }
+  | { flex: number }
   | { x: YamlAxisValue; y: YamlAxisValue };
 
-/** YAML size specification for a window. */
+/** YAML size specification for a window.
+ *  - `'fill'`, `'flex'`, `'content'` map to the matching zero-arg
+ *    `Size.fill()` / `Size.flex()` / `Size.content()` factories.
+ *  - `{ fillWidth }` / `{ fillHeight }` mirror the pre-0.24 shorthands.
+ *  - `{ flex: { grow?, shrink?, basis? } }` builds `Size.flex(grow, shrink, basis)`.
+ *  - `{ width, height }` maps to `new Size(width, height)`; the axis values may
+ *    themselves be literal numbers, "N%" strings, `'flex'`/`'content'` strings,
+ *    or `{ flex: {...} }` / `{ content: true }` objects for per-axis control. */
+export type YamlDimValue = YamlAxisValue | 'flex' | 'content' | { flex: { grow?: number; shrink?: number; basis?: YamlAxisValue } } | { content: true };
+
 export type YamlSizeSpec =
-  | 'fill'
+  | 'fill' | 'flex' | 'content'
   | { fillWidth: YamlAxisValue }
   | { fillHeight: YamlAxisValue }
-  | { width: YamlAxisValue; height: YamlAxisValue };
+  | { flex: { grow?: number; shrink?: number; basis?: YamlAxisValue } }
+  | { width: YamlDimValue; height: YamlDimValue };
 
 /** Control type tags supported by InterfaceBuilder. */
 export type YamlWindowType = 'window' | 'button' | 'textbox' | 'textarea' | 'checkbox' | 'radio'
@@ -296,8 +532,9 @@ export interface YamlStyleDef extends CellAttributes {
 export interface YamlWindowDef {
   /** Optional identifier for retrieving the built window from the result map. */
   id?: string;
-  /** Widget type. Defaults to 'window'. */
-  type?: YamlWindowType;
+  /** Widget type. Defaults to 'window'. May be a built-in tag or a custom
+   *  name registered via `InterfaceBuilder.registerType()`. */
+  type?: YamlWindowType | (string & {});
   /** Position within the parent. Defaults to { x: 0, y: 0 }. */
   pos?: YamlPosSpec;
   /** Dimensions of the window. Required for window/button/textbox/textarea; ignored for checkbox/radio (auto-sized). */
@@ -328,6 +565,16 @@ export interface YamlWindowDef {
   onPress?: string;
   /** Callback ID registered via InterfaceBuilder.registerCallback() — fired on value change. */
   onChange?: string;
+  /** Callback ID registered via InterfaceBuilder.registerCallback() — fired on submit
+   *  (Enter in TextBox; `ctrl+enter` in TextArea). */
+  onSubmit?: string;
+  /** Pre-dispatch hook callback ID — fired before the built-in handleKey logic
+   *  in TextBox / TextArea; handler returning `true` short-circuits default. */
+  onKeyDown?: string;
+  /** TextArea: when > 0, Tab inserts that many spaces instead of cycling focus. */
+  insertTabAsSpaces?: number;
+  /** TextArea: when true, Ctrl+D deletes the character to the right of the cursor. */
+  ctrlDDeletesForward?: boolean;
   /** LED state ('ok' | 'warn' | 'error' | 'off') — used by statusled. */
   state?: 'ok' | 'warn' | 'error' | 'off';
   /** Whether to show a percentage label over a progress bar. Default: true. */
@@ -366,8 +613,41 @@ export interface YamlWindowDef {
   running?: boolean;
   /** Tab index this child belongs to when its parent is a Tabs control. */
   tab?: number;
+  /** Layout algorithm for direct children — 'absolute' / 'row' / 'column' / 'grid'. */
+  layout?: 'absolute' | 'row' | 'column' | 'grid';
+  /** Spacing (in cells) between adjacent children for flex / grid layouts. */
+  gap?: number;
+  /** Padding inside the border: uniform number, [vertical, horizontal] tuple,
+   *  or a partial per-side record. */
+  padding?: number | [number, number] | { top?: number; right?: number; bottom?: number; left?: number };
+  /** Number of columns for `layout: grid`. */
+  gridColumns?: number;
+  /** Cross-axis alignment for `layout: row|column`. */
+  alignItems?: 'start' | 'center' | 'end' | 'stretch';
+  /** Main-axis distribution of leftover space for `layout: row|column`. */
+  justifyContent?: 'start' | 'center' | 'end' | 'space-between' | 'space-around';
+  /** Free-form property bag for user-registered custom types. Built-in types
+   *  ignore this field; custom factories read it via `node.props`. */
+  props?: Record<string, unknown>;
 }
 
+/** Context passed to factories registered via `InterfaceBuilder.registerType`.
+ *  Exposes pre-resolved common window properties plus the active style registry
+ *  so factories can compose their own control-specific options. */
+export interface CustomTypeContext {
+  /** Common window properties resolved from the YAML node (pos/size/border/…). */
+  wp: WindowProperties;
+  /** The style registry the builder is writing into. */
+  registry: StyleRegistry;
+  /** Looks up a callback registered via `InterfaceBuilder.registerCallback`. */
+  resolveCallback: (id: string | undefined) => ((...args: unknown[]) => void) | undefined;
+}
+
+/** Signature for a custom type factory registered via
+ *  `InterfaceBuilder.registerType`. The factory receives the raw YAML node
+ *  together with a resolved `ctx.wp` and must return the constructed window. */
+export type CustomTypeFactory = (node: YamlWindowDef, ctx: CustomTypeContext) => Window;
+
 /** Top-level YAML layout document consumed by InterfaceBuilder. */
 export interface YamlLayout {
   /** Named style definitions registered before windows are built. */
@@ -384,6 +664,10 @@ export interface Focusable {
   setFocused(focused: boolean): void;
   isDisabled(): boolean;
   handleKey?(key: string): void;
+  /** If present and returns `true`, the WindowManager skips Tab focus
+   *  navigation and dispatches Tab to `handleKey` instead. Used by controls
+   *  that consume Tab themselves (e.g. `TextArea` with `insertTabAsSpaces`). */
+  capturesTab?(): boolean;
 }
 
 /** Mouse event emitted by the terminal (SGR or X10 protocol). */
@@ -401,14 +685,35 @@ export interface TerminalMouseEvent {
   ctrl?: boolean;
 }
 
+/** Context passed to global key handlers (`onKey`, `bindKey`). */
+export interface KeyContext {
+  /** The control that currently has focus, or null when none. */
+  focusedControl: (Focusable & Window) | null;
+  /** True when at least one modal dialog is open. */
+  inDialog: boolean;
+  /** Nesting level of the dialog stack (0 = main context). */
+  dialogDepth: number;
+}
+
+/** Signature for handlers registered via `WindowManager.bindKey`.
+ *  Returning `true` marks the key as consumed — further handlers, exit keys,
+ *  focus navigation, and dispatch to the focused control are all skipped. */
+export type KeyBindHandler = (ctx: KeyContext) => boolean | void;
+
 /** Constructor options for WindowManager. */
 export interface WindowManagerOptions {
-  /** Key strings that trigger application exit. Default: ['\x03'] (Ctrl+C). */
+  /** Key strings that trigger application exit. Default: ['\x03'] (Ctrl+C).
+   *  Exit keys are checked **after** `onKey` / `bindKey` handlers; a handler
+   *  returning `true` prevents the exit from firing. */
   exitKeys?: string[];
   /** Called after the input loop stops and the terminal state is restored. */
   onExit?: () => void;
-  /** Called for every raw key string before it is dispatched to a control. */
-  onKey?: (key: string) => void;
+  /** Called for every raw key string before it is dispatched to a control.
+   *  Return `true` to mark the key as consumed — it will then **not** be
+   *  checked against `exitKeys`, will not trigger focus navigation, and will
+   *  not be dispatched to the focused control. Return `false` / `void` to
+   *  keep the previous pass-through behaviour. */
+  onKey?: (key: string, ctx: KeyContext) => boolean | void;
   /** Called for every mouse event when mouse support is enabled. */
   onMouse?: (event: TerminalMouseEvent) => void;
   /** Enable mouse click tracking (SGR protocol). Default: false. */