take4-console 0.15.1 → 0.25.0

package/src/demo.mts

@@ -1,5 +1,6 @@
 import { fileURLToPath } from 'node:url';
 import { join, dirname } from 'node:path';
+import { spawnSync } from 'node:child_process';
 import { Screen } from './Screen/Screen.mjs';
 import { WindowManager } from './Screen/WindowManager.mjs';
 import { InterfaceBuilder } from './Screen/InterfaceBuilder.mjs';
@@ -12,15 +13,53 @@ 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 { Window } from './Screen/Window.mjs';
+import type { ListBoxRowSegments, WindowProperties, StyleId } from './Screen/types.mjs';
+
+/** Custom Window subclass registered with InterfaceBuilder via
+ *  `registerType('badge', …)` to demonstrate P0-10 — the factory resolves
+ *  `props.text` / `props.color` from the YAML node and stashes them so the
+ *  overridden render() can repaint the label every frame after the size is
+ *  resolved by the parent layout pass. */
+class Badge extends Window {
+	private msg: string;
+	private styleId: StyleId;
+
+	/** Constructs a Badge with its visible text and pre-registered style id. */
+	public constructor(wp: WindowProperties, msg: string, styleId: StyleId) {
+		super(wp);
+		this.msg     = msg;
+		this.styleId = styleId;
+	}
+
+	/** Repaints the badge text before delegating to the default compositing pipeline. */
+	public override render(): void {
+		this.clear();
+		this.writeText(this.msg, { x: 0, y: 0, style: this.styleId });
+		super.render();
+	}
+}
 
 type LedState = 'ok' | 'warn' | 'error' | 'off';
+type EventLevel = 'ok' | 'warn' | 'error';
+
+interface EventRow {
+	timestamp: string;
+	level:     EventLevel;
+	message:   string;
+	count:     number;
+}
 
 // ── Entry point ───────────────────────────────────────────────────────────────
 
 /** Renders the controls demo. */
 const main = async (): Promise<void> => {
-	const screen  = new Screen();
-	const { width, height } = screen.getSize();
+	// 0.19.0: Screen owns the alt-screen + cursor toggles, so WindowManager won't
+	// re-enter them. dispose() runs on exit (via process.on('exit', …)) so the
+	// terminal state is restored even when the user kills the process with a
+	// signal that bypasses WindowManager.stop().
+	const screen  = new Screen({ altScreen: true, hideCursor: true });
+	let { width, height } = screen.getSize();
 
 	screen.fill(' ', screen.registerStyle({ background: 234 }));
 
@@ -30,26 +69,123 @@ const main = async (): Promise<void> => {
 		exitKeys: ['q', '\x03'],
 		onExit:   () => {
 			if (demoTimer) clearInterval(demoTimer);
+			screen.dispose();
 			process.exit(0);
 		},
 		mouse:    true,
 	});
 
+	// 0.19.0: SIGWINCH autoresize. The Screen reflows percentage-based children
+	// for us; the demo only needs to redraw the current-size label in the
+	// status bar so the new geometry is visible at runtime.
+	screen.on('resize', size => {
+		width  = size.width;
+		height = size.height;
+		redrawStatusBar();
+		screen.render();
+	});
+
 	const layoutPath = join(dirname(fileURLToPath(import.meta.url)), 'layout.yaml');
-	const result = await new InterfaceBuilder().buildFromFile(layoutPath, screen, wm);
+	const ib = new InterfaceBuilder();
+
+	// P0-10 demo: register a user-defined 'badge' control so the header can
+	// host a yellow "P0-10" label built from a class that never needed to be
+	// baked into InterfaceBuilder's built-in switch.
+	ib.registerType('badge', (node, ctx) => {
+		const props = (node.props ?? {}) as { text?: string; color?: number };
+		const styleId = screen.registerStyle({
+			background: 24,
+			foreground: props.color ?? 220,
+			bold:       true,
+		});
+		return new Badge(ctx.wp, props.text ?? '', styleId);
+	});
+
+	// P0-6 demo: when the user presses Enter in the username field, push an
+	// event into the log so the new onSubmit callback is visible at runtime.
+	ib.registerCallback('usernameSubmitted', (...args: unknown[]) => {
+		const value = String(args[0] ?? '');
+		const list = result.get('eventsList') as ListBox<EventRow>;
+		const entry: EventRow = {
+			timestamp: timestamp(),
+			level:     'ok',
+			message:   `user submit: ${value}`,
+			count:     1,
+		};
+		list.setItems([entry, ...list.getItems()].slice(0, 20));
+		screen.render();
+	});
+
+	const result = await ib.buildFromFile(layoutPath, screen, wm);
 
 	// ── Header & status bar ───────────────────────────────────────────────────
-	const headerStyle = screen.registerStyle({ background: 24, foreground: 255, bold: true });
-	result.get('header')!.writeText(' take4_console  │  controls demo ', { style: headerStyle });
-
-	const statusStyle = screen.registerStyle({ background: 24, foreground: 250 });
-	result.get('statusBar')!.writeText(
-		` ${width}×${height}  │  `
-		+ 'Button  Checkbox  Radio  TextBox  '
-		+ 'StatusLED  ProgressBar  ProgressBarV  LineChart  BarChart',
-		{ style: statusStyle },
+	// Header is rendered via writeMarkup() so the named styles in the registry drive
+	// the per-word colouring. `hdr:*` names are registered for the demo and then
+	// referenced from the template string — no manual StyleId threading.
+	screen.setBuiltinStyle('hdr:app',  { background: 24, foreground: 231, bold: true });
+	screen.setBuiltinStyle('hdr:mode', { background: 24, foreground: 153 });
+	screen.setBuiltinStyle('hdr:sep',  { background: 24, foreground: 110 });
+	const headerBase = screen.registerStyle({ background: 24 });
+	result.get('header')!.writeMarkup(
+		' {hdr:app}take4_console{/}  {hdr:sep}│{/}  {hdr:mode}controls demo{/} ',
+		{ style: headerBase },
 	);
 
+	// Status bar demonstrates the new segmented writeText() — each shortcut label is
+	// drawn in a distinct style while the cursor flows across segments without a
+	// separate writeText() call per piece.
+	const statusBase  = screen.registerStyle({ background: 24, foreground: 250 });
+	const shortcutId  = screen.registerStyle({ background: 24, foreground: 220, bold: true });
+	const sepId       = screen.registerStyle({ background: 24, foreground: 110 });
+	const dimId       = screen.registerStyle({ background: 24, foreground: 244, dim: true });
+	const helpId      = screen.registerStyle({ background: 24, foreground: 118, bold: true });
+	const statusBar   = result.get('statusBar')!;
+
+	// Toggled by the '?' global shortcut to flip the status bar into "help mode".
+	let helpMode = false;
+
+	/** Repaints the status bar so the live width × height label tracks SIGWINCH. */
+	const redrawStatusBar = (): void => {
+		statusBar.clear();
+		if (helpMode) {
+			statusBar.writeText([
+				{ text: ' HELP ', style: helpId },
+				{ text: '│', style: sepId },
+				{ text: '  ' },
+				{ text: '?',     style: shortcutId }, { text: ' toggle help  ' },
+				{ text: 'Ctrl+R', style: shortcutId }, { text: ' random jiggle  ' },
+				{ text: 'Ctrl+E', style: shortcutId }, { text: ' pause TUI  ' },
+				{ text: 'v',     style: shortcutId }, { text: ' hide charts  ' },
+				{ text: 'q',     style: shortcutId }, { text: ' quit ' },
+			], { style: statusBase });
+			return;
+		}
+		statusBar.writeText([
+			{ text: ` ${width}×${height}  ` },
+			{ text: '│', style: sepId },
+			{ text: '  ' },
+			{ text: 'Tab',   style: shortcutId }, { text: ' focus  ' },
+			{ text: '←/→',   style: shortcutId }, { text: ' tabs   ' },
+			{ text: 'Space', style: shortcutId }, { text: ' toggle  ' },
+			{ text: 'v',     style: shortcutId }, { text: ' charts  ' },
+			{ text: 'Ctrl+E', style: shortcutId }, { text: ' pause  ' },
+			{ text: '?',     style: shortcutId }, { text: ' help  ' },
+			{ text: 'q',     style: shortcutId }, { text: ' quit ' },
+			{ text: ' · emoji 🚀 CJK 日本語 · ', style: dimId },
+		], { style: statusBase });
+	};
+	redrawStatusBar();
+
+	// P0-4 demo: '?' toggles the help line in the status bar (consumed, so it
+	// never reaches the focused control). Ctrl+R re-jiggles the chart data
+	// without waiting for the timer — shows that bindKey co-exists with the
+	// regular key dispatch path as long as handlers return true.
+	wm.bindKey('?', () => {
+		helpMode = !helpMode;
+		redrawStatusBar();
+		return true;
+	});
+
 	// ── Resource labels in monitorPanel ──────────────────────────────────────
 	const labelStyle  = screen.registerStyle({ foreground: 245 });
 	const monitor = result.get('monitorPanel')!;
@@ -86,12 +222,47 @@ const main = async (): Promise<void> => {
 	tabs.writeText('MEM', { x: 1, y: 3, style: sparkLblStyle });
 	tabs.writeText('DSK', { x: 1, y: 4, style: sparkLblStyle });
 
-	// ── Events list (tab 2) ──────────────────────────────────────────────────
-	const events = result.get('eventsList') as ListBox;
-	const EVENT_TEMPLATES = [
-		'user logged in', 'cache warmed', 'metric collected', 'job completed',
-		'config reloaded', 'heartbeat ok', 'worker spawned', 'session expired',
-		'gc finished', 'index rebuilt',
+	// ── Events list (with custom per-row renderer: icon + dimmed timestamp + right-aligned count) ─
+	const events = result.get('eventsList') as ListBox<EventRow>;
+
+	// Register the accent styles used by the custom row renderer.
+	const iconOkStyle    = screen.registerStyle({ foreground: 82,  bold: true });
+	const iconWarnStyle  = screen.registerStyle({ foreground: 214, bold: true });
+	const iconErrorStyle = screen.registerStyle({ foreground: 196, bold: true });
+	const tsStyle        = screen.registerStyle({ foreground: 244, dim: true });
+	const countStyle     = screen.registerStyle({ foreground: 220 });
+
+	const levelIcon = (lvl: EventLevel): { glyph: string; style: number } => {
+		if (lvl === 'ok')    return { glyph: '✓', style: iconOkStyle };
+		if (lvl === 'warn')  return { glyph: '⚠', style: iconWarnStyle };
+		return                      { glyph: '✖', style: iconErrorStyle };
+	};
+
+	events.setRenderItem((row): ListBoxRowSegments => {
+		const { glyph, style: iconSt } = levelIcon(row.level);
+		return [
+			{ text: `${glyph} `,         align: 'left',  style: iconSt },
+			{ text: `[${row.timestamp}] `, align: 'left',  style: tsStyle },
+			{ text: row.message,         align: 'left' },
+			{ text: `×${row.count}`,     align: 'right', style: countStyle },
+		];
+	});
+
+	// A few entries embed double-width emoji (UTF-16 surrogate pairs) so the
+	// East-Asian-width-aware writeText() introduced in 0.17.0 is exercised
+	// at runtime — wide glyphs occupy two consecutive buffer cells with a ''
+	// continuation sentinel that Screen.render() skips.
+	const EVENT_TEMPLATES: Array<{ level: EventLevel; message: string }> = [
+		{ level: 'ok',    message: 'user logged in'     },
+		{ level: 'ok',    message: 'cache warmed 🚀'    },
+		{ level: 'ok',    message: 'metric collected'   },
+		{ level: 'ok',    message: 'job completed 💾'   },
+		{ level: 'warn',  message: 'config reloaded'    },
+		{ level: 'ok',    message: 'heartbeat ok'       },
+		{ level: 'ok',    message: 'worker spawned'     },
+		{ level: 'warn',  message: 'session expired'    },
+		{ level: 'ok',    message: 'gc finished'        },
+		{ level: 'error', message: 'index rebuild fail' },
 	];
 
 	// ── Live-updating handles ─────────────────────────────────────────────────
@@ -156,8 +327,14 @@ const main = async (): Promise<void> => {
 		headerSpinner.step();
 
 		// prepend a new event to the log; keep the list bounded
-		const msg   = EVENT_TEMPLATES[rand(EVENT_TEMPLATES.length)]!;
-		const next  = [`[${timestamp()}] ${msg}`, ...events.getItems()];
+		const tpl   = EVENT_TEMPLATES[rand(EVENT_TEMPLATES.length)]!;
+		const entry: EventRow = {
+			timestamp: timestamp(),
+			level:     tpl.level,
+			message:   tpl.message,
+			count:     1 + rand(9),
+		};
+		const next = [entry, ...events.getItems()];
 		events.setItems(next.slice(0, 20));
 
 		screen.render();
@@ -165,6 +342,41 @@ const main = async (): Promise<void> => {
 
 	demoTimer = setInterval(tick, 1000);
 
+	// P0-4 demo (cont'd): Ctrl+R force-refreshes the charts out-of-band so the
+	// key handler ordering is easy to observe — the TextBox in the layout never
+	// receives a '\x12' control code.
+	wm.bindKey('ctrl+r', () => {
+		tick();
+		return true;
+	});
+
+	// P0-8 demo: 'v' toggles the visibility of the charts panel. Hidden children
+	// are fully skipped by render() (neither painted nor blitted), so the panel
+	// vanishes leaving the dialog background in its place — and reappears
+	// unchanged when shown again. The Tab focus cycle also skips focusables
+	// inside a hidden subtree.
+	const chartsPanel = result.get('chartsPanel') as Tabs;
+	wm.bindKey('v', () => {
+		chartsPanel.setVisible(!chartsPanel.isVisible());
+		screen.render();
+		return true;
+	});
+
+	// P0-5 demo: Ctrl+E pauses the WindowManager (drops the TUI), exits the
+	// alternate screen buffer, and spawns a short inline shell so you can see
+	// that the terminal is fully reusable for an external process. Pressing
+	// Enter at the prompt returns to the TUI — resume() re-enters the alt
+	// 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.
+	wm.bindKey('ctrl+e', () => {
+		wm.pause({ leaveAltScreen: true });
+		process.stdout.write('\n--- paused take4_console TUI. Press Enter to return ---\n');
+		spawnSync('bash', ['-c', 'read -r _'], { stdio: 'inherit' });
+		wm.resume();
+		return true;
+	});
+
 	wm.run();
 };
 

package/src/index.mts

@@ -17,9 +17,10 @@ export { StyleRegistry }  from './Screen/StyleRegistry.mjs';
 export { WindowManager }  from './Screen/WindowManager.mjs';
 
 // ── Geometry ──────────────────────────────────────────────────────────────────
-export { Pos }            from './Screen/Pos.mjs';
-export { Pct, pct }       from './Screen/Pos.mjs';
-export { Size }           from './Screen/Size.mjs';
+export { Pos }                            from './Screen/Pos.mjs';
+export { Pct, pct }                       from './Screen/Pos.mjs';
+export { Size, FlexDim, ContentDim,
+         flex, content }                  from './Screen/Size.mjs';
 
 // ── Interactive controls ──────────────────────────────────────────────────────
 export { Button }         from './Screen/controls/Button.mjs';
@@ -42,6 +43,9 @@ export { Spinner }        from './Screen/controls/Spinner.mjs';
 // ── YAML layout builder ───────────────────────────────────────────────────────
 export { InterfaceBuilder } from './Screen/InterfaceBuilder.mjs';
 
+// ── Unicode text width helpers ────────────────────────────────────────────────
+export { charWidth, stringWidth, setPuaWidth, getPuaWidth } from './Screen/textWidth.mjs';
+
 // ── Built-in style name constants ─────────────────────────────────────────────
 export {
 	BUILTIN_WINDOW_BG,
@@ -64,14 +68,25 @@ export type {
 	Cell,
 	CellAttributes,
 	TerminalSize,
+	ScreenOptions,
+	ScreenFrameStats,
 	AxisSpec,
 	DimSpec,
+	FlexBasis,
+	LayoutMode,
+	AlignItems,
+	JustifyContent,
+	Padding,
+	PaddingSpec,
 
 	// Window / border
 	BorderStyle,
+	BorderChars,
 	WindowBorder,
 	WindowProperties,
 	WriteTextOptions,
+	WriteTextSegment,
+	WriteTextInput,
 
 	// Control properties
 	ButtonProperties,
@@ -85,6 +100,9 @@ export type {
 	LineChartProperties,
 	BarChartProperties,
 	ListBoxProperties,
+	ListBoxRenderContext,
+	ListBoxRowSegment,
+	ListBoxRowSegments,
 	TabsProperties,
 	SparklineProperties,
 	SpinnerProperties,
@@ -102,4 +120,6 @@ export type {
 	YamlStyleDef,
 	YamlWindowDef,
 	YamlLayout,
+	CustomTypeContext,
+	CustomTypeFactory,
 } from './Screen/types.mjs';

package/src/layout.yaml

@@ -10,6 +10,16 @@ windows:
         spinnerStyle: braille
         label: "LIVE"
         chartColor: 231
+      # P0-10: custom control registered in demo.mts via
+      # InterfaceBuilder.registerType('badge', …). Fields under `props:` are
+      # forwarded to the factory untouched.
+      - id: buildBadge
+        type: badge
+        pos: { x: 18, y: 0 }
+        size: { width: 10, height: 1 }
+        props:
+          text: "P0-10 "
+          color: 220
 
   - id: statusBar
     pos: { preset: bottom }
@@ -35,7 +45,10 @@ windows:
         pos: { x: 1, y: 2 }
         size: { width: "46%", height: "43%" }
         background: 235
-        border: { top: true, right: true, bottom: true, left: true, style: single, color: 238 }
+        # Demonstrates the per-character override: the corners are swapped for diamond glyphs
+        # while the rest of the 'single' style is kept untouched.
+        border: { top: true, right: true, bottom: true, left: true, style: single, color: 238,
+                  chars: { topLeft: '◆', topRight: '◆' } }
         content: "Personal info"
         children:
           - id: tbUsername
@@ -45,6 +58,9 @@ windows:
             value: "jan_kowalski"
             placeholder: "username"
             focused: true
+            # P0-6: YAML-wired onSubmit — pressing Enter while this TextBox is
+            # focused fires `usernameSubmitted`, registered in demo.mts.
+            onSubmit: usernameSubmitted
           - id: tbEmail
             type: textbox
             pos: { x: 0, y: 5 }
@@ -124,7 +140,8 @@ windows:
         pos: { x: 1, y: "46%" }
         size: { width: "46%", height: "43%" }
         background: 235
-        border: { top: true, right: true, bottom: true, left: true, style: single, color: 238 }
+        # Demonstrates the new 'thick' (heavy) box-drawing style.
+        border: { top: true, right: true, bottom: true, left: true, style: thick, color: 38 }
         content: "Resources"
         children:
           - id: pbCpu
@@ -204,33 +221,48 @@ windows:
         pos: { x: "81%", y: "46%" }
         size: { width: "17%", height: "43%" }
         background: 235
-        border: { top: true, right: true, bottom: true, left: true, style: single, color: 238 }
+        # Demonstrates the new 'dashed' style.
+        border: { top: true, right: true, bottom: true, left: true, style: dashed, color: 33 }
         content: "Events"
         children:
           - id: eventsList
             type: listbox
             pos: { x: 0, y: 1 }
             size: { width: "100%", height: "85%" }
-            items:
-              - "[12:04:21] user logged in"
-              - "[12:04:33] cache warmed"
-              - "[12:05:01] metric collected"
-              - "[12:05:18] job completed"
+            # Items populated at runtime via ListBox.setItems() with structured EventRow objects;
+            # a demo.mts renderItem() draws icon + dimmed timestamp + right-aligned count.
 
       # ── Buttons ───────────────────────────────────────────────────────────────
-      - id: btnDisabled
-        type: button
-        pos: { x: 1, y: -4 }
-        size: { width: 11, height: 3 }
-        label: "Delete"
-        disabled: true
-      - id: btnCancel
-        type: button
-        pos: { x: -15, y: -4 }
-        size: { width: 11, height: 3 }
-        label: "Cancel"
-      - id: btnSave
-        type: button
-        pos: { x: -27, y: -4 }
-        size: { width: 11, height: 3 }
-        label: " Save"
+      # Bottom action bar — demonstrates P0-3 flex layout. The container uses
+      # `layout: row` with `gap: 1`; the middle `spacer` child has `size: flex`
+      # (grow=1 by default), so it soaks up leftover inner width between the
+      # left-aligned "Delete" and the right-aligned "Cancel" / " Save" group.
+      # alignItems: stretch pins children to the row height. This is the same
+      # visual outcome as the previous absolute positioning but authored
+      # declaratively, and it adapts automatically if the dialog is resized.
+      - id: buttonRow
+        pos: { x: 0, y: -4 }
+        size: { fillWidth: 3 }
+        layout: row
+        gap: 1
+        alignItems: stretch
+        children:
+          - id: btnDisabled
+            type: button
+            pos: flex
+            size: { width: 11, height: 3 }
+            label: "Delete"
+            disabled: true
+          - id: buttonSpacer
+            pos: flex
+            size: flex
+          - id: btnCancel
+            type: button
+            pos: flex
+            size: { width: 11, height: 3 }
+            label: "Cancel"
+          - id: btnSave
+            type: button
+            pos: flex
+            size: { width: 11, height: 3 }
+            label: " Save"