take4-console 0.25.0 → 0.31.0

package/src/Screen/types.mts

@@ -28,6 +28,41 @@ export const BUILTIN_TEXT_PLACEHOLDER   = 'builtin:text-placeholder';
 export const BUILTIN_TEXT_CHECKED       = 'builtin:text-checked';
 /** Name of the cursor highlight style (inverse) used by text input controls. */
 export const BUILTIN_CURSOR             = 'builtin:cursor';
+/** Name of the selection highlight style merged over selected cells in
+ *  `TextBox` / `TextArea` (backlog P1-20). */
+export const BUILTIN_TEXT_SELECTION     = 'builtin:text-selection';
+/** Name of the default background + text style used by `Screen.toast()`
+ *  overlay windows (backlog P1-27). Consumers can override it via
+ *  `Screen.setBuiltinStyle(BUILTIN_TOAST, …)` to recolour every toast at
+ *  once without threading a per-call `style` option. */
+export const BUILTIN_TOAST              = 'builtin:toast';
+
+// ── Virtual cursor ────────────────────────────────────────────────────────────
+
+/** Blink configuration for a `VirtualCursor`.
+ *  - `off`       — cursor is never drawn (hide software cursor entirely).
+ *  - `steady`    — cursor is always drawn (no blink).
+ *  - `slow`      — 600 ms on / 600 ms off.
+ *  - `fast`      — 250 ms on / 250 ms off.
+ *  - `irregular` — each on/off phase picks a randomised duration so the
+ *                  cursor pulses in a non-metronomic "alive" rhythm.
+ *  - `custom`    — caller-supplied on / off durations in milliseconds. */
+export type CursorBlink =
+  | { mode: 'off' }
+  | { mode: 'steady' }
+  | { mode: 'slow' }
+  | { mode: 'fast' }
+  | { mode: 'irregular' }
+  | { mode: 'custom'; onMs: number; offMs: number };
+
+/** Construction options for `VirtualCursor`. Both fields are optional;
+ *  defaults: `symbol = '▎'`, `blink = { mode: 'steady' }`. */
+export interface VirtualCursorOptions {
+  /** Glyph rendered for the cursor when visible. Default: `'▎'`. */
+  symbol?: string;
+  /** Blink schedule. Default: `{ mode: 'steady' }` (no blink). */
+  blink?: CursorBlink;
+}
 
 /** Integer handle returned by StyleRegistry.register(). ID 0 always means no style (empty {}). */
 export type StyleId = number;
@@ -75,12 +110,39 @@ export interface ScreenOptions {
    *  for inspection; full enforcement (frame coalescing) lands with backlog
    *  item P2-47. Default: undefined (uncapped). */
   targetFps?: number;
+  /** Enables damage-region tracking: `Screen.render()` collects dirty rects
+   *  propagated bottom-up from each mutated window and emits ANSI sequences
+   *  only for the changed cells. A frame with no dirty rects is skipped
+   *  entirely (no stdout traffic). The first frame and every frame after
+   *  `resize()` / `invalidate()` fall back to a full repaint. Default:
+   *  `true`. Set to `false` for the pre-0.31 behaviour (always emit the
+   *  full buffer), useful for debugging or terminals that mis-handle
+   *  partial cursor jumps. */
+  damageTracking?: boolean;
 }
 
 /** 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;
+  /** Number of cells emitted to stdout during this frame (0 when the frame
+   *  was skipped because nothing was dirty). Populated only when damage
+   *  tracking is enabled; undefined otherwise. */
+  cellsEmitted?: number;
+  /** True when the emit path was a full-screen repaint (first frame,
+   *  post-resize, or damage tracking disabled); false when only dirty runs
+   *  were emitted. Undefined when the frame was skipped entirely. */
+  fullRepaint?: boolean;
+}
+
+/** Rectangle expressed in the owning Window's local coordinate space (for
+ *  dirty regions on a Window) or in Screen coordinates (when collected by
+ *  `Screen.render()` during damage tracking). */
+export interface DirtyRect {
+  x: number;
+  y: number;
+  w: number;
+  h: number;
 }
 
 /** Box-drawing character style for window borders.
@@ -167,6 +229,16 @@ export interface WindowProperties {
    *  padded inner area, and `getInnerSize()` / `getInnerOffset()` reflect the
    *  padding as well as the border. Default: 0 on every side. */
   padding?: PaddingSpec;
+  /** Outer spacing reserved around the window inside its parent's layout.
+   *  - In `row` / `column` flex layouts margin stacks with `gap`: each child
+   *    claims `intrinsic + marginMain` cells on the main axis, and its cross
+   *    extent is reduced by the cross margin.
+   *  - In `grid` layout the child fits inside `cell − margin` and is offset by
+   *    `marginTop` / `marginLeft` within the cell.
+   *  - In `absolute` layout margin shifts the child's resolved position by
+   *    `(marginLeft, marginTop)` without changing its size.
+   *  Default: 0 on every side. */
+  margin?: MarginSpec;
   /** 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. */
@@ -177,6 +249,21 @@ export interface WindowProperties {
   /** Main-axis distribution of leftover space for `layout: 'row'` / `'column'`
    *  when no child consumes it via flex-grow. Default: 'start'. */
   justifyContent?: JustifyContent;
+  /** Optional string identifier used by `WindowManager.focusById` and for
+   *  diagnostics. InterfaceBuilder copies the YAML `id:` into this field so
+   *  the runtime can cross-reference programmatic focus with the builder map. */
+  id?: string;
+  /** Stacking order among siblings — windows with a higher `zIndex` render
+   *  on top of windows with a lower value. Ties are broken by `addChild`
+   *  insertion order, so the pre-0.26 behaviour (everything at `zIndex: 0`)
+   *  is preserved for callers that don't opt in. Default: 0. */
+  zIndex?: number;
+  /** Fires once when this window transitions from unfocused to focused, via
+   *  any code path (WindowManager, explicit `setFocused(true)`, focus
+   *  inheritance on dialog open). Not fired when the state does not change. */
+  onFocus?: () => void;
+  /** Fires once when this window transitions from focused to unfocused. */
+  onBlur?: () => void;
 }
 
 /** Internal per-axis position spec used by Pos.
@@ -240,6 +327,20 @@ export interface Padding {
  *  a partial per-side record (missing sides default to 0). */
 export type PaddingSpec = number | [number, number] | Partial<Padding>;
 
+/** Resolved per-side margin values (in cells). Margin is the outer counterpart
+ *  of padding — it pushes the window away from its parent's inner edges /
+ *  siblings without reserving space inside the window itself. */
+export interface Margin {
+  top:    number;
+  right:  number;
+  bottom: number;
+  left:   number;
+}
+
+/** User-supplied margin: a uniform number, a [vertical, horizontal] tuple, or
+ *  a partial per-side record (missing sides default to 0). Mirrors `PaddingSpec`. */
+export type MarginSpec = number | [number, number] | Partial<Margin>;
+
 /** Options for Window.writeText() – position defaults to (0, 0). */
 export interface WriteTextOptions {
   /** Column to start writing at. Default: 0. */
@@ -298,6 +399,15 @@ export interface TextBoxProperties {
    *  `true` to mark the key as handled — the default behaviour (inserting,
    *  moving cursor, deleting, …) is then skipped. */
   onKeyDown?: (key: string) => boolean | void;
+  /** Virtual-cursor glyph. Overrides the default inverse-block look. When
+   *  set, the character under the cursor is replaced by this symbol (unless
+   *  the symbol is a zero-width string, in which case the underlying
+   *  character stays). Default: undefined (inverse block). */
+  cursorSymbol?: string;
+  /** Blink schedule for the virtual cursor. Default: `{ mode: 'steady' }`
+   *  (no blink). Requires `WindowManager.enableCursorBlink()` for timed
+   *  modes to actually animate. */
+  cursorBlink?: CursorBlink;
 }
 
 /** Control-specific properties for the TextArea control. */
@@ -324,6 +434,10 @@ export interface TextAreaProperties {
   /** 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;
+  /** Virtual-cursor glyph. Overrides the default inverse-block look. */
+  cursorSymbol?: string;
+  /** Blink schedule for the virtual cursor. Default: `{ mode: 'steady' }`. */
+  cursorBlink?: CursorBlink;
 }
 
 /** Control-specific properties for the Checkbox control. */
@@ -465,6 +579,43 @@ export interface SpinnerProperties {
   color?: number;
 }
 
+/** Corner (or top/bottom centre) where `Screen.toast()` anchors its overlay
+ *  windows. Toasts launched at the same position stack vertically in the
+ *  order they were created; a dismissal shifts the remaining stack towards
+ *  the anchor edge so the UI stays compact. */
+export type ToastPosition =
+  | 'top-left'    | 'top-center'    | 'top-right'
+  | 'bottom-left' | 'bottom-center' | 'bottom-right';
+
+/** Options accepted by `Screen.toast()`. All fields are optional; sensible
+ *  defaults make `screen.toast('Saved!')` a single-call notification. */
+export interface ToastOptions {
+  /** Auto-dismiss delay in milliseconds. Pass `0` to keep the toast sticky
+   *  until `toast.dismiss()` is called manually. Default: `2000`. */
+  duration?: number;
+  /** Pre-registered style ID used as both the window background and the
+   *  text style. Default: `BUILTIN_TOAST` (falls back to a high-contrast
+   *  style registered on first use). */
+  style?: StyleId;
+  /** Corner (or top/bottom centre) the toast anchors to. Default:
+   *  `'top-right'`. */
+  position?: ToastPosition;
+  /** Border configuration. Pass `false` for a borderless toast. Default:
+   *  a rounded single-line border on all four sides. */
+  border?: WindowBorder | boolean;
+  /** Stacking order among Screen children. Default: `10_000` so toasts
+   *  draw on top of every regular window without callers having to raise
+   *  other `zIndex` values by hand. */
+  zIndex?: number;
+  /** Override the automatic text-based width (in cells, not counting the
+   *  border). When the text is wider than this value it overflows
+   *  normally — toasts never wrap. Default: `undefined` (auto-size). */
+  width?: number;
+  /** Fires once after the toast has been removed from the Screen
+   *  (auto-dismiss or manual). */
+  onDismiss?: () => void;
+}
+
 /** Control-specific properties for the BarChart control. */
 export interface BarChartProperties {
   /** Data values for each bar. Default: []. */
@@ -575,6 +726,10 @@ export interface YamlWindowDef {
   insertTabAsSpaces?: number;
   /** TextArea: when true, Ctrl+D deletes the character to the right of the cursor. */
   ctrlDDeletesForward?: boolean;
+  /** TextBox / TextArea: virtual-cursor glyph (overrides inverse-block look). */
+  cursorSymbol?: string;
+  /** TextBox / TextArea: virtual-cursor blink schedule. */
+  cursorBlink?: CursorBlink;
   /** 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. */
@@ -620,6 +775,9 @@ export interface YamlWindowDef {
   /** 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 };
+  /** Outer spacing reserved around this window inside its parent's layout.
+   *  Same shape as `padding`. */
+  margin?: 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`. */
@@ -629,6 +787,9 @@ export interface YamlWindowDef {
   /** 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>;
+  /** Stacking order among siblings. Higher values render on top; ties keep
+   *  YAML declaration order. Default: 0. */
+  zIndex?: number;
 }
 
 /** Context passed to factories registered via `InterfaceBuilder.registerType`.
@@ -718,4 +879,10 @@ export interface WindowManagerOptions {
   onMouse?: (event: TerminalMouseEvent) => void;
   /** Enable mouse click tracking (SGR protocol). Default: false. */
   mouse?: boolean;
+  /** Fires when a descendant Window throws during its `render()` call (or its
+   *  blit onto the parent). The offending subtree is replaced in-place with a
+   *  single-line error placeholder so the rest of the frame still paints;
+   *  the handler is invoked once per error with the thrown value and the
+   *  Window that produced it. Default: no-op. */
+  onError?: (err: unknown, control: Window) => void;
 }

package/src/demo.mts

@@ -13,7 +13,10 @@ import { Spinner }      from './Screen/controls/Spinner.mjs';
 import { Sparkline }    from './Screen/controls/Sparkline.mjs';
 import { ListBox }      from './Screen/controls/ListBox.mjs';
 import { Tabs }         from './Screen/controls/Tabs.mjs';
+import { TextBox }      from './Screen/controls/TextBox.mjs';
 import { Window } from './Screen/Window.mjs';
+import { Pos } from './Screen/Pos.mjs';
+import { Size } from './Screen/Size.mjs';
 import type { ListBoxRowSegments, WindowProperties, StyleId } from './Screen/types.mjs';
 
 /** Custom Window subclass registered with InterfaceBuilder via
@@ -73,6 +76,18 @@ const main = async (): Promise<void> => {
 			process.exit(0);
 		},
 		mouse:    true,
+		// P1-23 demo: whenever a descendant Window.render() raises, append a
+		// red row to the events list instead of tearing down the TUI.
+		onError:  (err, control) => {
+			const list  = result.get('eventsList') as ListBox<EventRow>;
+			const entry: EventRow = {
+				timestamp: timestamp(),
+				level:     'error',
+				message:   `render fail (${control.getId() ?? 'unnamed'}): ${err instanceof Error ? err.message : String(err)}`,
+				count:     1,
+			};
+			list.setItems([entry, ...list.getItems()].slice(0, 20));
+		},
 	});
 
 	// 0.19.0: SIGWINCH autoresize. The Screen reflows percentage-based children
@@ -369,6 +384,55 @@ const main = async (): Promise<void> => {
 	// buffer, re-hides the cursor, re-enables mouse tracking, and re-renders
 	// the frame. The focus / dialog stack / key bindings stay intact across
 	// the cycle.
+	// P1-18 demo: Ctrl+G jumps focus to the  Save button via its YAML id,
+	// without the user having to Tab through every field in between.
+	wm.bindKey('ctrl+g', () => {
+		wm.focusById('btnSave');
+		screen.render();
+		return true;
+	});
+
+	// P1-22 demo: observe focus transitions on btnSave without subclassing —
+	// the hooks append a short trail to the events list so the user can see
+	// exactly when setFocus fires them.
+	const btnSave = result.get('btnSave')!;
+	btnSave.setOnFocus(() => {
+		const list = result.get('eventsList') as ListBox<EventRow>;
+		const entry: EventRow = { timestamp: timestamp(), level: 'ok', message: 'btnSave → focus', count: 1 };
+		list.setItems([entry, ...list.getItems()].slice(0, 20));
+	});
+	btnSave.setOnBlur(() => {
+		const list = result.get('eventsList') as ListBox<EventRow>;
+		const entry: EventRow = { timestamp: timestamp(), level: 'warn', message: 'btnSave → blur', count: 1 };
+		list.setItems([entry, ...list.getItems()].slice(0, 20));
+	});
+
+	// P1-27 demo: Ctrl+T pops a short-lived top-right toast so the overlay
+	// subsystem is visible at runtime. Repeated presses stack vertically and
+	// auto-dismiss in the same order. Ctrl+Y fires a sticky bottom-right toast
+	// that can only be cleared via its own dismiss button (`Enter` on focus)
+	// — here we close it on the next press to keep the demo self-contained.
+	let toastCounter = 0;
+	let stickyToast: ReturnType<typeof screen.toast> | null = null;
+	wm.bindKey('ctrl+t', () => {
+		toastCounter += 1;
+		screen.toast(` Saved #${toastCounter} at ${timestamp()} `, { duration: 2500 });
+		return true;
+	});
+	wm.bindKey('ctrl+y', () => {
+		if (stickyToast) {
+			stickyToast.dismiss();
+			stickyToast = null;
+		} else {
+			stickyToast = screen.toast(' Sticky: press Ctrl+Y again to dismiss ', {
+				position: 'bottom-right',
+				duration: 0,
+				onDismiss: () => { stickyToast = null; },
+			});
+		}
+		return true;
+	});
+
 	wm.bindKey('ctrl+e', () => {
 		wm.pause({ leaveAltScreen: true });
 		process.stdout.write('\n--- paused take4_console TUI. Press Enter to return ---\n');
@@ -377,6 +441,73 @@ const main = async (): Promise<void> => {
 		return true;
 	});
 
+	// P2-59 demo: Ctrl+D toggles damage tracking at runtime and posts a
+	// sticky toast with the new state so the effect is visible. When
+	// tracking is on, the 'frame' event reports only the dirty cells each
+	// frame (watch the toast subtitle); when it's off, every frame is a
+	// full repaint as before.
+	wm.bindKey('ctrl+d', () => {
+		const next = !screen.isDamageTrackingEnabled();
+		screen.setDamageTracking(next);
+		screen.toast(
+			next ? ' Damage tracking ON — only dirty cells are emitted '
+			     : ' Damage tracking OFF — every frame is a full repaint ',
+			{ position: 'top-center', duration: 2500 },
+		);
+		return true;
+	});
+
+	// Virtual cursor: animated caret in TextBox/TextArea. The `tbEmail`
+	// TextBox opts into slow blink via layout.yaml; here we flip the
+	// `tbUsername` TextBox into the `irregular` mode so the two
+	// side-by-side inputs show off two different rhythms. The
+	// `enableCursorBlink()` call boots the periodic rerender that makes
+	// the blink phases actually reach the terminal.
+	const tbUsername = result.get('tbUsername') as TextBox | undefined;
+	if (tbUsername) {
+		tbUsername.getVirtualCursor().setSymbol('▏');
+		tbUsername.getVirtualCursor().setBlink({ mode: 'irregular' });
+		// P1-20 showcase: pre-select the initial value so the merged
+		// selection style is visible on boot. Shift+Left/Right, Ctrl+A,
+		// and plain arrows collapse it the moment the user interacts.
+		const text = tbUsername.getValue();
+		if (text.length > 0) tbUsername.setSelection(0, Math.min(3, text.length));
+	}
+	wm.enableCursorBlink(80);
+
+	// P2-59 showcase: five independent spinners with different styles,
+	// cadences, and positions, each driven by its own `setInterval`.
+	// With damage tracking ON, every tick emits only that spinner's 1–2
+	// cells (check the 'frame' event `cellsEmitted`); with tracking OFF
+	// (Ctrl+D) each tick repaints the whole screen. Placed along the
+	// bottom edge so they don't overlap existing widgets.
+	const spinnerStyles: Array<'braille' | 'dots' | 'line' | 'circle' | 'arrow'> =
+		['braille', 'dots', 'line', 'circle', 'arrow'];
+	const spinnerCadences = [120, 180, 240, 320, 420];
+	const spinnerTimers: NodeJS.Timeout[] = [];
+	const { width: screenW, height: screenH } = screen.getSize();
+	for (let i = 0; i < spinnerStyles.length; i++) {
+		const sp = new Spinner(
+			{ pos: new Pos(screenW - 12 - i * 3, screenH - 2), size: new Size(2, 1) },
+			{ style: spinnerStyles[i], color: 75 + i * 10 },
+		);
+		screen.addChild(sp);
+		const timer = setInterval(() => {
+			sp.step();
+			screen.render();
+		}, spinnerCadences[i]!);
+		if (typeof timer === 'object' && timer !== null && 'unref' in timer
+		    && typeof timer.unref === 'function') timer.unref();
+		spinnerTimers.push(timer);
+	}
+	// Ensure the spinner timers are torn down alongside the main demo
+	// timer when the user quits (the existing onExit handler already
+	// clears `demoTimer`, so extend it with ours).
+	const originalOnExit = () => {
+		for (const t of spinnerTimers) clearInterval(t);
+	};
+	process.once('exit', originalOnExit);
+
 	wm.run();
 };
 

package/src/index.mts

@@ -15,6 +15,7 @@ export { Window }         from './Screen/Window.mjs';
 export { Region }         from './Screen/Region.mjs';
 export { StyleRegistry }  from './Screen/StyleRegistry.mjs';
 export { WindowManager }  from './Screen/WindowManager.mjs';
+export { VirtualCursor, DEFAULT_CURSOR_SYMBOL } from './Screen/VirtualCursor.mjs';
 
 // ── Geometry ──────────────────────────────────────────────────────────────────
 export { Pos }                            from './Screen/Pos.mjs';
@@ -39,6 +40,7 @@ export { LineChart }      from './Screen/controls/LineChart.mjs';
 export { BarChart }       from './Screen/controls/BarChart.mjs';
 export { Sparkline }      from './Screen/controls/Sparkline.mjs';
 export { Spinner }        from './Screen/controls/Spinner.mjs';
+export { Toast }          from './Screen/controls/Toast.mjs';
 
 // ── YAML layout builder ───────────────────────────────────────────────────────
 export { InterfaceBuilder } from './Screen/InterfaceBuilder.mjs';
@@ -58,6 +60,8 @@ export {
 	BUILTIN_TEXT_PLACEHOLDER,
 	BUILTIN_TEXT_CHECKED,
 	BUILTIN_CURSOR,
+	BUILTIN_TEXT_SELECTION,
+	BUILTIN_TOAST,
 } from './Screen/types.mjs';
 
 // ── Public type exports ───────────────────────────────────────────────────────
@@ -70,6 +74,7 @@ export type {
 	TerminalSize,
 	ScreenOptions,
 	ScreenFrameStats,
+	DirtyRect,
 	AxisSpec,
 	DimSpec,
 	FlexBasis,
@@ -78,6 +83,8 @@ export type {
 	JustifyContent,
 	Padding,
 	PaddingSpec,
+	Margin,
+	MarginSpec,
 
 	// Window / border
 	BorderStyle,
@@ -106,12 +113,18 @@ export type {
 	TabsProperties,
 	SparklineProperties,
 	SpinnerProperties,
+	ToastPosition,
+	ToastOptions,
 
 	// Focus & input
 	Focusable,
 	TerminalMouseEvent,
 	WindowManagerOptions,
 
+	// Virtual cursor
+	CursorBlink,
+	VirtualCursorOptions,
+
 	// InterfaceBuilder YAML schema
 	YamlAxisValue,
 	YamlPosSpec,

package/src/layout.yaml

@@ -17,9 +17,19 @@ windows:
         type: badge
         pos: { x: 18, y: 0 }
         size: { width: 10, height: 1 }
+        # P1-17 demo: painted after its siblings thanks to the higher zIndex,
+        # so any overlapping overlay child below zIndex 10 stays underneath.
+        zIndex: 10
         props:
           text: "P0-10 "
           color: 220
+      - id: headerOverlay
+        pos: { x: 15, y: 0 }
+        size: { width: 16, height: 1 }
+        background: 52
+        # P1-17 demo: sits behind buildBadge even though declared later — the
+        # Window.render loop sorts siblings by (zIndex asc, insertion order).
+        zIndex: 1
 
   - id: statusBar
     pos: { preset: bottom }
@@ -67,6 +77,9 @@ windows:
             size: { fillWidth: 3 }
             value: "jan@example.com"
             placeholder: "e-mail"
+            # Virtual cursor: custom caret glyph with a slow blink.
+            cursorSymbol: "▎"
+            cursorBlink: { mode: "slow" }
           - id: cb1
             type: checkbox
             pos: { x: 1, y: 9 }
@@ -265,4 +278,7 @@ windows:
             type: button
             pos: flex
             size: { width: 11, height: 3 }
+            # Extra breathing room between "Cancel" and "Save" via P1-16 margin
+            # (horizontal cells reserved on top of layout gap).
+            margin: { left: 2 }
             label: " Save"