take4-console 0.15.0

package/src/Screen/InterfaceBuilder.mts

@@ -0,0 +1,403 @@
+import { parse } from 'yaml';
+import { readFile } from 'node:fs/promises';
+import type {
+  YamlLayout,
+  YamlWindowDef,
+  YamlPosSpec,
+  YamlSizeSpec,
+  YamlAxisValue,
+  StyleId,
+  Focusable,
+  WindowProperties,
+} from './types.mjs';
+import { Window } from './Window.mjs';
+import { Screen } from './Screen.mjs';
+import { WindowManager } from './WindowManager.mjs';
+import { Pos, Pct, pct } from './Pos.mjs';
+import { Size } from './Size.mjs';
+import { getRegistry } from './RegistryHolder.mjs';
+import { Button }       from './controls/Button.mjs';
+import { TextBox }      from './controls/TextBox.mjs';
+import { TextArea }     from './controls/TextArea.mjs';
+import { Checkbox }     from './controls/Checkbox.mjs';
+import { Radio }        from './controls/Radio.mjs';
+import { StatusLED }    from './controls/StatusLED.mjs';
+import { ProgressBar }  from './controls/ProgressBar.mjs';
+import { ProgressBarV } from './controls/ProgressBarV.mjs';
+import { LineChart }    from './controls/LineChart.mjs';
+import { BarChart }     from './controls/BarChart.mjs';
+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 ──────────────────────────────────────────────────────────
+
+/** A focusable control with its resolved parent chain, queued for WM registration. */
+interface PendingRegistration {
+  control: Focusable & Window;
+  parents: Window[];
+}
+
+/** Converts a YamlAxisValue ("N%", or a number) to a number or Pct instance. */
+function parseAxisValue(v: YamlAxisValue): number | Pct {
+  if (typeof v === 'string') {
+    const m = v.match(/^(-?\d+(?:\.\d+)?)%$/);
+    if (!m) throw new Error(`Invalid axis value: "${v}". Expected a number or "N%" string.`);
+    return pct(parseFloat(m[1]));
+  }
+  return v;
+}
+
+/** Converts a YamlPosSpec to a Pos instance. */
+function parsePos(spec: YamlPosSpec | undefined): Pos {
+  if (!spec) return new Pos(0, 0);
+  if (spec === 'center')      return Pos.center();
+  if (spec === 'topLeft')     return Pos.topLeft();
+  if (spec === 'topRight')    return Pos.topRight();
+  if (spec === 'bottomLeft')  return Pos.bottomLeft();
+  if (spec === 'bottomRight') return Pos.bottomRight();
+  if (typeof spec === 'object') {
+    if ('preset' in spec) {
+      const off = spec.offset !== undefined ? parseAxisValue(spec.offset) : 0;
+      switch (spec.preset) {
+        case 'top':    return Pos.top(off);
+        case 'left':   return Pos.left(off);
+        case 'right':  return Pos.right(off);
+        case 'bottom': return Pos.bottom(off);
+      }
+    }
+    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 YamlSizeSpec to a Size instance. */
+function parseSize(spec: YamlSizeSpec): Size {
+  if (spec === 'fill') return Size.fill();
+  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 ('width' in spec && 'height' in spec) {
+      return new Size(parseAxisValue(spec.width), parseAxisValue(spec.height));
+    }
+  }
+  throw new Error(`Invalid size spec: ${JSON.stringify(spec)}`);
+}
+
+/** Resolves a YAML background value (style name or numeric StyleId) to a StyleId.
+ *  String values are looked up by name in the global registry (returns 0 if not found).
+ *  Numeric values are passed through as-is. Undefined becomes undefined (transparent). */
+function resolveBackground(bg: string | number | undefined): StyleId | undefined {
+  if (bg === undefined) return undefined;
+  if (typeof bg === 'string') return getRegistry().getNamed(bg) ?? 0;
+  return bg;
+}
+
+// ── InterfaceBuilder ──────────────────────────────────────────────────────────
+
+/** Builds a window hierarchy from a YAML description.
+ *
+ * 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.
+ *
+ * YAML schema:
+ *   windows:
+ *     - id: myBtn
+ *       type: button          # window | button | textbox | textarea | checkbox | radio
+ *       pos: center           # {x, y} | center | topLeft | topRight | bottomLeft | bottomRight | {preset: top|left|right|bottom, offset?}
+ *       size: { width: 20, height: 3 }  # {width, height} | fill | {fillWidth: N} | {fillHeight: N}
+ *       label: "Click me"
+ *       onPress: my_callback
+ *       children:
+ *         - ...
+ */
+export class InterfaceBuilder {
+  private callbacks: Map<string, (...args: unknown[]) => void>;
+
+  /** Creates an InterfaceBuilder with an empty callback registry. */
+  public constructor() {
+    this.callbacks = new Map();
+  }
+
+  /** Registers a named callback for use with onPress or onChange in YAML definitions. */
+  public registerCallback(id: string, fn: (...args: unknown[]) => void): void {
+    this.callbacks.set(id, fn);
+  }
+
+  /** 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.
+   *  Returns a map of all windows and controls keyed by their YAML id. */
+  public build(yamlText: string, screen: Screen, wm?: WindowManager): Map<string, Window> {
+    const layout        = parse(yamlText) as YamlLayout;
+    const result        = new Map<string, Window>();
+    const pending: PendingRegistration[] = [];
+    const contentWrites: Array<{ win: Window; text: string }> = [];
+
+    // Register YAML-defined named styles before building the window tree.
+    if (layout.styles) {
+      const registry = getRegistry();
+      for (const styleDef of layout.styles) {
+        const { name, ...attrs } = styleDef;
+        registry.registerNamed(name, attrs);
+      }
+    }
+
+    for (const def of layout.windows) {
+      const win = this.buildNode(def, result, pending, contentWrites, []);
+      // Adding to screen resolves percentage-based sizes for the entire subtree.
+      screen.addChild(win);
+    }
+
+    // Write static content after sizing so text lands in correctly-sized regions.
+    for (const { win, text } of contentWrites) {
+      win.writeText(text);
+    }
+
+    if (wm) {
+      for (const { control, parents } of pending) {
+        wm.register(control, ...parents);
+      }
+    }
+
+    return result;
+  }
+
+  /** Builds the UI from a YAML file. See build() for details. */
+  public async buildFromFile(filePath: string, screen: Screen, wm?: WindowManager): Promise<Map<string, Window>> {
+    const text = await readFile(filePath, 'utf8');
+    return this.build(text, screen, wm);
+  }
+
+  // ── Private helpers ───────────────────────────────────────────────────────────
+
+  /** Recursively creates a single widget and all of its children from a YamlWindowDef.
+   *  Static content strings are collected into contentWrites instead of being written
+   *  immediately, so they are applied after all sizes are resolved. */
+  private buildNode(
+    def: YamlWindowDef,
+    result: Map<string, Window>,
+    pending: PendingRegistration[],
+    contentWrites: Array<{ win: Window; text: string }>,
+    parentChain: Window[],
+  ): Window {
+    const pos      = parsePos(def.pos);
+    const bgId     = resolveBackground(def.background);
+
+    /** Common window properties shared by all control types. */
+    const wp: WindowProperties = {
+      pos,
+      size:       def.size ? parseSize(def.size) : undefined,
+      background: bgId,
+      border:     def.border,
+      active:     def.active,
+      focused:    def.focused,
+      disabled:   def.disabled,
+      label:      def.label,
+    };
+
+    let win: Window;
+
+    switch (def.type ?? 'window') {
+      case 'button': {
+        const pressCb = def.onPress ? this.callbacks.get(def.onPress) : undefined;
+        wp.size = wp.size ?? this.requireSize(def);
+        const btn = new Button(wp, {
+          onPress: pressCb ? () => pressCb() : undefined,
+        });
+        pending.push({ control: btn, parents: [...parentChain] });
+        win = btn;
+        break;
+      }
+
+      case 'textbox': {
+        wp.size = wp.size ?? this.requireSize(def);
+        const tb = new TextBox(wp, {
+          value:       def.value,
+          placeholder: def.placeholder,
+        });
+        pending.push({ control: tb, parents: [...parentChain] });
+        win = tb;
+        break;
+      }
+
+      case 'textarea': {
+        wp.size = wp.size ?? this.requireSize(def);
+        const ta = new TextArea(wp, {
+          value:       def.value,
+          placeholder: def.placeholder,
+        });
+        pending.push({ control: ta, parents: [...parentChain] });
+        win = ta;
+        break;
+      }
+
+      case 'checkbox': {
+        const changeCb = def.onChange ? this.callbacks.get(def.onChange) : undefined;
+        const cb = new Checkbox(wp, {
+          checked:  def.checked,
+          onChange: changeCb ? (checked: boolean) => changeCb(checked) : undefined,
+        });
+        pending.push({ control: cb, parents: [...parentChain] });
+        win = cb;
+        break;
+      }
+
+      case 'radio': {
+        const changeCb = def.onChange ? this.callbacks.get(def.onChange) : undefined;
+        const r = new Radio(wp, {
+          checked:  def.checked,
+          onChange: changeCb ? (checked: boolean) => changeCb(checked) : undefined,
+        });
+        pending.push({ control: r, parents: [...parentChain] });
+        win = r;
+        break;
+      }
+
+      case 'statusled': {
+        const led = new StatusLED(wp, {
+          state: def.state,
+        });
+        win = led;
+        break;
+      }
+
+      case 'progressbar': {
+        wp.size = wp.size ?? this.requireSize(def);
+        const pb = new ProgressBar(wp, {
+          value:      def.barValue,
+          max:        def.max,
+          showLabel:  def.showLabel,
+          fillColor:  def.fillColor,
+          emptyColor: def.emptyColor,
+        });
+        win = pb;
+        break;
+      }
+
+      case 'progressbarv': {
+        wp.size = wp.size ?? this.requireSize(def);
+        const pbv = new ProgressBarV(wp, {
+          value:      def.barValue,
+          max:        def.max,
+          fillColor:  def.fillColor,
+          emptyColor: def.emptyColor,
+        });
+        win = pbv;
+        break;
+      }
+
+      case 'linechart': {
+        wp.size = wp.size ?? this.requireSize(def);
+        const lc = new LineChart(wp, {
+          data:  def.data,
+          min:   def.min,
+          max:   def.max,
+          color: def.chartColor,
+        });
+        win = lc;
+        break;
+      }
+
+      case 'barchart': {
+        wp.size = wp.size ?? this.requireSize(def);
+        const bc = new BarChart(wp, {
+          data:     def.data,
+          labels:   def.barLabels,
+          max:      def.max,
+          barColor: def.chartColor,
+          barWidth: def.barWidth,
+        });
+        win = bc;
+        break;
+      }
+
+      case 'listbox': {
+        const changeCb = def.onChange ? this.callbacks.get(def.onChange) : undefined;
+        wp.size = wp.size ?? this.requireSize(def);
+        const lb = new ListBox(wp, {
+          items:         def.items,
+          selectedIndex: def.selectedIndex,
+          onChange:      changeCb ? (idx: number, item: string) => changeCb(idx, item) : undefined,
+        });
+        pending.push({ control: lb, parents: [...parentChain] });
+        win = lb;
+        break;
+      }
+
+      case 'tabs': {
+        const changeCb = def.onChange ? this.callbacks.get(def.onChange) : undefined;
+        wp.size = wp.size ?? this.requireSize(def);
+        const tabs = new Tabs(wp, {
+          titles:      def.titles,
+          activeIndex: def.activeIndex,
+          onChange:    changeCb ? (idx: number, title: string) => changeCb(idx, title) : undefined,
+        });
+        pending.push({ control: tabs, parents: [...parentChain] });
+        win = tabs;
+        break;
+      }
+
+      case 'sparkline': {
+        wp.size = wp.size ?? this.requireSize(def);
+        const sp = new Sparkline(wp, {
+          data:  def.data,
+          min:   def.min,
+          max:   def.max,
+          color: def.chartColor,
+        });
+        win = sp;
+        break;
+      }
+
+      case 'spinner': {
+        const sp = new Spinner(wp, {
+          style:   def.spinnerStyle,
+          frame:   def.frame,
+          running: def.running,
+          color:   def.chartColor,
+        });
+        win = sp;
+        break;
+      }
+
+      default: {
+        wp.size = wp.size ?? this.requireSize(def);
+        win = new Window(wp);
+        break;
+      }
+    }
+
+    if (def.id) result.set(def.id, win);
+    // Defer content write – the window may not have its final size yet.
+    if (def.content) contentWrites.push({ win, text: def.content });
+
+    if (def.children) {
+      for (const childDef of def.children) {
+        const child = this.buildNode(childDef, result, pending, contentWrites, [win, ...parentChain]);
+        if (win instanceof Tabs && childDef.tab !== undefined) {
+          win.addChildToTab(childDef.tab, child);
+        } else {
+          win.addChild(child);
+        }
+      }
+    }
+
+    return win;
+  }
+
+  /** Returns a parsed Size from the definition or throws if size is missing. */
+  private requireSize(def: YamlWindowDef): Size {
+    if (!def.size) {
+      const label = def.id ? `"${def.id}"` : (def.type ?? 'window');
+      throw new Error(`Missing required "size" for ${label}.`);
+    }
+    return parseSize(def.size);
+  }
+}

package/src/Screen/Pos.mts

@@ -0,0 +1,119 @@
+import type { AxisSpec } from './types.mjs';
+
+/** Wraps a percentage value (0–100) for use in Pos and Size constructors. */
+export class Pct {
+	public constructor(public readonly value: number) {}
+}
+
+/** Creates a Pct instance representing the given percentage. */
+export function pct(value: number): Pct {
+	return new Pct(value);
+}
+
+/** Converts a user-supplied coordinate to an internal AxisSpec. */
+function toAxisSpec(v: number | Pct): AxisSpec {
+	if (v instanceof Pct) return { mode: 'pct', value: v.value };
+	if (v < 0)           return { mode: 'end', value: -v };
+	return { mode: 'start', value: v };
+}
+
+/** Resolves a single axis spec to a pixel offset. */
+function resolveAxis(spec: AxisSpec, parentSize: number, ownSize: number): number {
+	switch (spec.mode) {
+		case 'start':  return spec.value;
+		case 'end':    return parentSize - ownSize - spec.value;
+		case 'pct':    return Math.floor(parentSize * spec.value / 100);
+		case 'center': return Math.floor((parentSize - ownSize) / 2);
+	}
+}
+
+/** Encodes a window position. Supports absolute coordinates, edge-relative (negative),
+ *  percentage-based, center alignment, and named edge presets. */
+export class Pos {
+	private xSpec: AxisSpec;
+	private ySpec: AxisSpec;
+
+	/** Creates a position.
+	 *  - Positive number: absolute distance from left/top.
+	 *  - Negative number: own right/bottom edge at that distance from parent's right/bottom.
+	 *  - Pct instance: percentage of parent dimension from left/top. */
+	public constructor(x: number | Pct, y: number | Pct) {
+		this.xSpec = toAxisSpec(x);
+		this.ySpec = toAxisSpec(y);
+	}
+
+	/** Builds a Pos directly from raw AxisSpec values (used by static factories). */
+	private static fromSpecs(x: AxisSpec, y: AxisSpec): Pos {
+		const p  = Object.create(Pos.prototype) as Pos;
+		p.xSpec  = x;
+		p.ySpec  = y;
+		return p;
+	}
+
+	/** Aligns the top-left corner with the parent's top-left corner (0, 0). */
+	public static topLeft(): Pos {
+		return Pos.fromSpecs({ mode: 'start', value: 0 }, { mode: 'start', value: 0 });
+	}
+
+	/** Aligns the top-right corner with the parent's top-right corner. */
+	public static topRight(): Pos {
+		return Pos.fromSpecs({ mode: 'end', value: 0 }, { mode: 'start', value: 0 });
+	}
+
+	/** Aligns the bottom-left corner with the parent's bottom-left corner. */
+	public static bottomLeft(): Pos {
+		return Pos.fromSpecs({ mode: 'start', value: 0 }, { mode: 'end', value: 0 });
+	}
+
+	/** Aligns the bottom-right corner with the parent's bottom-right corner. */
+	public static bottomRight(): Pos {
+		return Pos.fromSpecs({ mode: 'end', value: 0 }, { mode: 'end', value: 0 });
+	}
+
+	/** Centers the window within the parent on both axes. */
+	public static center(): Pos {
+		return Pos.fromSpecs({ mode: 'center' }, { mode: 'center' });
+	}
+
+	/** Aligns the top edge with the parent's top edge; x sets horizontal position. */
+	public static top(x: number | Pct = 0): Pos {
+		return Pos.fromSpecs(toAxisSpec(x), { mode: 'start', value: 0 });
+	}
+
+	/** Aligns the left edge with the parent's left edge; y sets vertical position. */
+	public static left(y: number | Pct = 0): Pos {
+		return Pos.fromSpecs({ mode: 'start', value: 0 }, toAxisSpec(y));
+	}
+
+	/** Aligns the right edge with the parent's right edge; y sets vertical position. */
+	public static right(y: number | Pct = 0): Pos {
+		return Pos.fromSpecs({ mode: 'end', value: 0 }, toAxisSpec(y));
+	}
+
+	/** Aligns the bottom edge with the parent's bottom edge; x sets horizontal position. */
+	public static bottom(x: number | Pct = 0): Pos {
+		return Pos.fromSpecs(toAxisSpec(x), { mode: 'end', value: 0 });
+	}
+
+	/** Returns true when both axes are absolute-from-start values (no parent/own-size needed). */
+	public isAbsolute(): boolean {
+		return this.xSpec.mode === 'start' && this.ySpec.mode === 'start';
+	}
+
+	/** Resolves absolute position without needing parent or own dimensions.
+	 *  Only call when isAbsolute() returns true. */
+	public resolveAbsolute(): { x: number; y: number } {
+		return {
+			x: (this.xSpec as { mode: 'start'; value: number }).value,
+			y: (this.ySpec as { mode: 'start'; value: number }).value,
+		};
+	}
+
+	/** Resolves this position to pixel coordinates given parent and own dimensions. */
+	public resolve(parentW: number, parentH: number, ownW: number, ownH: number): { x: number; y: number } {
+		return {
+			x: resolveAxis(this.xSpec, parentW, ownW),
+			y: resolveAxis(this.ySpec, parentH, ownH),
+		};
+	}
+}

package/src/Screen/Region.mts

@@ -0,0 +1,88 @@
+import type { StyleId, TerminalSize } from './types.mjs';
+
+export class Region {
+	private chars: string[];
+	private styleIds: number[];
+	private size: TerminalSize;
+
+	/** Allocates a cell buffer for the given dimensions. All cells start with style ID 0 (empty). */
+	public constructor(width: number, height: number) {
+		this.size = { width, height };
+		const len = width * height;
+		this.chars    = Array(len).fill(' ');
+		this.styleIds = new Array(len).fill(0);
+	}
+
+	/** Returns the region dimensions (columns × rows). */
+	public getSize(): TerminalSize {
+		return { ...this.size };
+	}
+
+	/** Returns the style ID stored at (x, y). Throws RangeError if out of bounds. */
+	public getStyleId(x: number, y: number): StyleId {
+		this.assertBounds(x, y);
+		return this.styleIds[this.index(x, y)];
+	}
+
+	/** Sets only the character at (x, y) without modifying the style ID. Throws RangeError if out of bounds. */
+	public setChar(x: number, y: number, char: string): void {
+		this.assertBounds(x, y);
+		this.chars[this.index(x, y)] = char;
+	}
+
+	/** Sets the character and style ID at (x, y). Throws RangeError if out of bounds. */
+	public setCell(x: number, y: number, char: string, styleId: StyleId = 0): void {
+		this.assertBounds(x, y);
+		const i = this.index(x, y);
+		this.chars[i]    = char;
+		this.styleIds[i] = styleId;
+	}
+
+	/** Replaces only the style ID at (x, y) without changing the character. Throws RangeError if out of bounds. */
+	public setStyleId(x: number, y: number, styleId: StyleId): void {
+		this.assertBounds(x, y);
+		this.styleIds[this.index(x, y)] = styleId;
+	}
+
+	/** Resets every cell to a blank space with style ID 0. */
+	public clear(): void {
+		const len = this.chars.length;
+		for (let i = 0; i < len; i++) {
+			this.chars[i]    = ' ';
+			this.styleIds[i] = 0;
+		}
+	}
+
+	/** Fills every cell with the given character and style ID. */
+	public fill(char: string, styleId: StyleId = 0): void {
+		const len = this.chars.length;
+		for (let i = 0; i < len; i++) {
+			this.chars[i]    = char;
+			this.styleIds[i] = styleId;
+		}
+	}
+
+	/** Returns a readonly view of the character buffer for rendering. */
+	public getChars(): readonly string[] {
+		return this.chars;
+	}
+
+	/** Returns a readonly view of the style-ID buffer for rendering. */
+	public getStyleIds(): readonly number[] {
+		return this.styleIds;
+	}
+
+	/** Returns the flat buffer index for the given (x, y) coordinates. */
+	private index(x: number, y: number): number {
+		return y * this.size.width + x;
+	}
+
+	/** Throws RangeError if the coordinates (x, y) are outside the region boundaries. */
+	private assertBounds(x: number, y: number): void {
+		if (x < 0 || x >= this.size.width || y < 0 || y >= this.size.height) {
+			throw new RangeError(
+				`Cell (${x}, ${y}) is out of bounds for region ${this.size.width}×${this.size.height}`
+			);
+		}
+	}
+}

package/src/Screen/RegistryHolder.mts

@@ -0,0 +1,16 @@
+import { StyleRegistry } from './StyleRegistry.mjs';
+
+/** Module-level singleton holding the active StyleRegistry.
+ *  Initialized with an empty registry so Window and controls work
+ *  in isolation (e.g. in tests) before any Screen is constructed. */
+let activeRegistry: StyleRegistry = new StyleRegistry();
+
+/** Returns the currently active StyleRegistry. */
+export function getRegistry(): StyleRegistry {
+	return activeRegistry;
+}
+
+/** Sets the active StyleRegistry. Called by the Screen constructor. */
+export function setRegistry(registry: StyleRegistry): void {
+	activeRegistry = registry;
+}