@flyingrobots/bijou-tui 0.9.0 → 1.0.0

package/dist/keybindings.d.ts

@@ -24,60 +24,152 @@ import type { KeyMsg } from './types.js';
 import type { InputHandler } from './inputstack.js';
 /** A parsed key descriptor: the key name + modifier flags. */
 export interface KeyCombo {
+    /** Key name (e.g. `"q"`, `"enter"`, `"tab"`). */
     readonly key: string;
+    /** Whether the Ctrl modifier is required. */
     readonly ctrl: boolean;
+    /** Whether the Alt modifier is required. */
     readonly alt: boolean;
+    /** Whether the Shift modifier is required. */
     readonly shift: boolean;
 }
-/** A single registered binding. */
+/**
+ * A single registered binding associating a key combo with an action.
+ *
+ * @template A - Action type returned when this binding matches.
+ */
 export interface Binding<A> {
+    /** Key combination that triggers this binding. */
     readonly combo: KeyCombo;
+    /** Human-readable description for help text. */
     readonly description: string;
+    /** Group name this binding belongs to (empty string if ungrouped). */
     readonly group: string;
+    /** Action to return when this binding matches. */
     readonly action: A;
+    /** Whether this binding is currently active. */
     enabled: boolean;
 }
-/** Read-only view of a binding for help generation. */
+/** Read-only view of a binding for help generation and introspection. */
 export interface BindingInfo {
+    /** Key combination that triggers this binding. */
     readonly combo: KeyCombo;
+    /** Human-readable description for help text. */
     readonly description: string;
+    /** Group name this binding belongs to. */
     readonly group: string;
+    /** Whether this binding is currently active. */
     readonly enabled: boolean;
 }
-/** The keybinding manager. */
+/**
+ * The keybinding manager.
+ *
+ * Provide a fluent API for registering key bindings, matching incoming
+ * key events, and managing binding state at runtime.
+ *
+ * @template A - Action type returned when a binding matches.
+ */
 export interface KeyMap<A> extends InputHandler<KeyMsg, A> {
-    /** Register a binding. `key` is a descriptor like `"q"`, `"ctrl+c"`, `"shift+tab"`. */
+    /**
+     * Register a binding. `key` is a descriptor like `"q"`, `"ctrl+c"`, `"shift+tab"`.
+     *
+     * @param key - Key descriptor string.
+     * @param description - Human-readable description for help text.
+     * @param action - Action to return when this binding matches.
+     * @returns This key map for chaining.
+     */
     bind(key: string, description: string, action: A): KeyMap<A>;
-    /** Register bindings under a named group. */
+    /**
+     * Register bindings under a named group.
+     *
+     * @param name - Group name for categorizing bindings.
+     * @param fn - Builder callback receiving a scoped group builder.
+     * @returns This key map for chaining.
+     */
     group(name: string, fn: (g: KeyMapGroup<A>) => KeyMapGroup<A>): KeyMap<A>;
-    /** Match a KeyMsg and return its action, or undefined if no match. */
+    /**
+     * Match a {@link KeyMsg} and return its action, or `undefined` if no match.
+     *
+     * @param msg - Incoming key message to match against registered bindings.
+     * @returns The matched action, or `undefined` if no enabled binding matches.
+     */
     handle(msg: KeyMsg): A | undefined;
-    /** Enable bindings whose description matches the predicate. */
+    /**
+     * Enable bindings whose description matches the predicate.
+     *
+     * @param predicate - Description string for exact match, or a filter function.
+     */
     enable(predicate: string | ((b: BindingInfo) => boolean)): void;
-    /** Disable bindings whose description matches the predicate. */
+    /**
+     * Disable bindings whose description matches the predicate.
+     *
+     * @param predicate - Description string for exact match, or a filter function.
+     */
     disable(predicate: string | ((b: BindingInfo) => boolean)): void;
-    /** Enable all bindings in a group. */
+    /**
+     * Enable all bindings in a group.
+     *
+     * @param group - Group name to enable.
+     */
     enableGroup(group: string): void;
-    /** Disable all bindings in a group. */
+    /**
+     * Disable all bindings in a group.
+     *
+     * @param group - Group name to disable.
+     */
     disableGroup(group: string): void;
-    /** Return all bindings (for help generation). */
+    /**
+     * Return a snapshot of all bindings for help generation.
+     *
+     * @returns Read-only array of binding info objects.
+     */
     bindings(): readonly BindingInfo[];
 }
-/** Group builder — same as KeyMap but scoped to a group name. */
+/**
+ * Group builder — same as KeyMap but scoped to a group name.
+ *
+ * @template A - Action type returned when a binding matches.
+ */
 export interface KeyMapGroup<A> {
+    /**
+     * Register a binding within this group.
+     *
+     * @param key - Key descriptor string (e.g. `"j"`, `"ctrl+c"`).
+     * @param description - Human-readable description for help text.
+     * @param action - Action to return when this binding matches.
+     * @returns This group builder for chaining.
+     */
     bind(key: string, description: string, action: A): KeyMapGroup<A>;
 }
 /**
- * Parse a key descriptor string into a KeyCombo.
+ * Parse a key descriptor string into a {@link KeyCombo}.
  *
  * Examples: `"q"`, `"ctrl+c"`, `"alt+shift+tab"`, `"enter"`, `"space"`
+ *
+ * @param descriptor - Key descriptor string with optional modifier prefixes.
+ * @returns Parsed key combo with key name and modifier flags.
+ * @throws {Error} If a modifier is duplicated, unknown, or the key part is empty.
  */
 export declare function parseKeyCombo(descriptor: string): KeyCombo;
 /**
- * Format a KeyCombo back into a human-readable string.
+ * Format a {@link KeyCombo} back into a human-readable string.
  *
+ * Capitalize modifier names and multi-character key names.
  * Examples: `"Ctrl+c"`, `"q"`, `"Shift+Tab"`
+ *
+ * @param combo - Key combo to format.
+ * @returns Human-readable key string.
  */
 export declare function formatKeyCombo(combo: KeyCombo): string;
+/**
+ * Create a new keybinding manager.
+ *
+ * Return a fluent {@link KeyMap} that registers key bindings, matches
+ * incoming {@link KeyMsg} events, and supports runtime enable/disable
+ * of individual bindings or groups.
+ *
+ * @template A - Action type returned when a binding matches.
+ * @returns A new empty key map.
+ */
 export declare function createKeyMap<A>(): KeyMap<A>;
 //# sourceMappingURL=keybindings.d.ts.map

package/dist/keybindings.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"keybindings.d.ts","sourceRoot":"","sources":["../src/keybindings.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,YAAY,CAAC;AACzC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAMpD,8DAA8D;AAC9D,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,QAAQ,CAAC,GAAG,EAAE,OAAO,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;CACzB;AAED,mCAAmC;AACnC,MAAM,WAAW,OAAO,CAAC,CAAC;IACxB,QAAQ,CAAC,KAAK,EAAE,QAAQ,CAAC;IACzB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,CAAC,CAAC;IACnB,OAAO,EAAE,OAAO,CAAC;CAClB;AAED,uDAAuD;AACvD,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,KAAK,EAAE,QAAQ,CAAC;IACzB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;CAC3B;AAED,8BAA8B;AAC9B,MAAM,WAAW,MAAM,CAAC,CAAC,CAAE,SAAQ,YAAY,CAAC,MAAM,EAAE,CAAC,CAAC;IACxD,uFAAuF;IACvF,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC,GAAG,MAAM,CAAC,CAAC,CAAC,CAAC;IAE7D,6CAA6C;IAC7C,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,WAAW,CAAC,CAAC,CAAC,KAAK,WAAW,CAAC,CAAC,CAAC,GAAG,MAAM,CAAC,CAAC,CAAC,CAAC;IAE1E,sEAAsE;IACtE,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,CAAC,GAAG,SAAS,CAAC;IAEnC,+DAA+D;IAC/D,MAAM,CAAC,SAAS,EAAE,MAAM,GAAG,CAAC,CAAC,CAAC,EAAE,WAAW,KAAK,OAAO,CAAC,GAAG,IAAI,CAAC;IAEhE,gEAAgE;IAChE,OAAO,CAAC,SAAS,EAAE,MAAM,GAAG,CAAC,CAAC,CAAC,EAAE,WAAW,KAAK,OAAO,CAAC,GAAG,IAAI,CAAC;IAEjE,sCAAsC;IACtC,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IAEjC,uCAAuC;IACvC,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IAElC,iDAAiD;IACjD,QAAQ,IAAI,SAAS,WAAW,EAAE,CAAC;CACpC;AAED,iEAAiE;AACjE,MAAM,WAAW,WAAW,CAAC,CAAC;IAC5B,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC,GAAG,WAAW,CAAC,CAAC,CAAC,CAAC;CACnE;AAMD;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,UAAU,EAAE,MAAM,GAAG,QAAQ,CAiC1D;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,QAAQ,GAAG,MAAM,CAatD;AAqBD,wBAAgB,YAAY,CAAC,CAAC,KAAK,MAAM,CAAC,CAAC,CAAC,CA4F3C"}
+{"version":3,"file":"keybindings.d.ts","sourceRoot":"","sources":["../src/keybindings.ts"],"names":[],"mappings":"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"}

package/dist/keybindings.js

@@ -24,9 +24,13 @@
 // Key descriptor parsing
 // ---------------------------------------------------------------------------
 /**
- * Parse a key descriptor string into a KeyCombo.
+ * Parse a key descriptor string into a {@link KeyCombo}.
  *
  * Examples: `"q"`, `"ctrl+c"`, `"alt+shift+tab"`, `"enter"`, `"space"`
+ *
+ * @param descriptor - Key descriptor string with optional modifier prefixes.
+ * @returns Parsed key combo with key name and modifier flags.
+ * @throws {Error} If a modifier is duplicated, unknown, or the key part is empty.
  */
 export function parseKeyCombo(descriptor) {
     // Lowercase the entire descriptor for consistency with parseKey(), which always
@@ -65,9 +69,13 @@ export function parseKeyCombo(descriptor) {
     return { key, ctrl, alt, shift };
 }
 /**
- * Format a KeyCombo back into a human-readable string.
+ * Format a {@link KeyCombo} back into a human-readable string.
  *
+ * Capitalize modifier names and multi-character key names.
  * Examples: `"Ctrl+c"`, `"q"`, `"Shift+Tab"`
+ *
+ * @param combo - Key combo to format.
+ * @returns Human-readable key string.
  */
 export function formatKeyCombo(combo) {
     const parts = [];
@@ -87,6 +95,13 @@ export function formatKeyCombo(combo) {
 // ---------------------------------------------------------------------------
 // Matching
 // ---------------------------------------------------------------------------
+/**
+ * Test whether a key combo matches a key message exactly.
+ *
+ * @param combo - Registered key combo to match against.
+ * @param msg - Incoming key message from the terminal.
+ * @returns `true` if all key name and modifier flags match.
+ */
 function matches(combo, msg) {
     return (combo.key === msg.key &&
         combo.ctrl === msg.ctrl &&
@@ -96,7 +111,18 @@ function matches(combo, msg) {
 // ---------------------------------------------------------------------------
 // Implementation
 // ---------------------------------------------------------------------------
+/** Group name used for bindings registered outside any named group. */
 const DEFAULT_GROUP = '';
+/**
+ * Create a new keybinding manager.
+ *
+ * Return a fluent {@link KeyMap} that registers key bindings, matches
+ * incoming {@link KeyMsg} events, and supports runtime enable/disable
+ * of individual bindings or groups.
+ *
+ * @template A - Action type returned when a binding matches.
+ * @returns A new empty key map.
+ */
 export function createKeyMap() {
     const allBindings = [];
     let currentGroup = DEFAULT_GROUP;

package/dist/keybindings.js.map

@@ -1 +1 @@
-{"version":3,"file":"keybindings.js","sourceRoot":"","sources":["../src/keybindings.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"keybindings.js","sourceRoot":"","sources":["../src/keybindings.ts"],"names":[],"mappings":"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"}

package/dist/keys.d.ts

@@ -1,7 +1,33 @@
-import type { KeyMsg } from './types.js';
 /**
- * Parse a raw ANSI byte string from rawInput() into a structured KeyMsg.
- * Unrecognized sequences produce { key: 'unknown' }.
+ * Keyboard and mouse input parsing for raw ANSI/SGR terminal sequences.
+ *
+ * Convert raw byte strings from stdin into structured {@link KeyMsg} and
+ * {@link MouseMsg} objects for use in the TEA update loop.
+ *
+ * @module
+ */
+import type { KeyMsg, MouseMsg } from './types.js';
+/**
+ * Parse a raw ANSI byte string from `rawInput()` into a structured {@link KeyMsg}.
+ *
+ * Handle arrow keys, function keys, enter, tab, backspace, space, escape,
+ * Ctrl+A through Ctrl+Z, and printable ASCII characters. Unrecognized
+ * sequences produce `{ key: 'unknown' }`.
+ *
+ * @param raw - Raw byte string from terminal stdin.
+ * @returns Parsed key message.
  */
 export declare function parseKey(raw: string): KeyMsg;
+/**
+ * Parse an SGR extended mouse sequence into a {@link MouseMsg}.
+ *
+ * SGR format: `ESC [ < button ; col ; row M/m`
+ * - `M` = press, `m` = release
+ * - Button byte bits: 0-1 = button, 2 = shift, 3 = alt, 4 = ctrl, 5 = motion, 6-7 = scroll
+ * - Column and row are 1-based in the protocol, converted to 0-based here
+ *
+ * @param raw - Raw byte string that may contain an SGR mouse sequence.
+ * @returns Parsed mouse message, or `null` if the string is not a valid SGR mouse sequence.
+ */
+export declare function parseMouse(raw: string): MouseMsg | null;
 //# sourceMappingURL=keys.d.ts.map

package/dist/keys.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"keys.d.ts","sourceRoot":"","sources":["../src/keys.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,YAAY,CAAC;AAMzC;;;GAGG;AACH,wBAAgB,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CA2C5C"}
+{"version":3,"file":"keys.d.ts","sourceRoot":"","sources":["../src/keys.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,QAAQ,EAA4B,MAAM,YAAY,CAAC;AAe7E;;;;;;;;;GASG;AACH,wBAAgB,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CA2C5C;AAKD;;;;;;;;;;GAUG;AACH,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,QAAQ,GAAG,IAAI,CAqCvD"}

package/dist/keys.js

@@ -1,9 +1,32 @@
+/**
+ * Keyboard and mouse input parsing for raw ANSI/SGR terminal sequences.
+ *
+ * Convert raw byte strings from stdin into structured {@link KeyMsg} and
+ * {@link MouseMsg} objects for use in the TEA update loop.
+ *
+ * @module
+ */
+/**
+ * Create a {@link KeyMsg} with the given key name and modifier flags.
+ *
+ * @param key - Key name (e.g. `"a"`, `"enter"`, `"up"`).
+ * @param ctrl - Whether the Ctrl modifier is active.
+ * @param alt - Whether the Alt modifier is active.
+ * @param shift - Whether the Shift modifier is active.
+ * @returns A new `KeyMsg`.
+ */
 function keyMsg(key, ctrl = false, alt = false, shift = false) {
     return { type: 'key', key, ctrl, alt, shift };
 }
 /**
- * Parse a raw ANSI byte string from rawInput() into a structured KeyMsg.
- * Unrecognized sequences produce { key: 'unknown' }.
+ * Parse a raw ANSI byte string from `rawInput()` into a structured {@link KeyMsg}.
+ *
+ * Handle arrow keys, function keys, enter, tab, backspace, space, escape,
+ * Ctrl+A through Ctrl+Z, and printable ASCII characters. Unrecognized
+ * sequences produce `{ key: 'unknown' }`.
+ *
+ * @param raw - Raw byte string from terminal stdin.
+ * @returns Parsed key message.
  */
 export function parseKey(raw) {
     // Arrow keys and other CSI sequences
@@ -59,4 +82,52 @@ export function parseKey(raw) {
     }
     return keyMsg('unknown');
 }
+/** Regular expression matching SGR extended mouse sequences: `ESC [ < button ; col ; row M/m`. */
+const SGR_MOUSE_RE = /^\x1b\[<(\d+);(\d+);(\d+)([Mm])$/;
+/**
+ * Parse an SGR extended mouse sequence into a {@link MouseMsg}.
+ *
+ * SGR format: `ESC [ < button ; col ; row M/m`
+ * - `M` = press, `m` = release
+ * - Button byte bits: 0-1 = button, 2 = shift, 3 = alt, 4 = ctrl, 5 = motion, 6-7 = scroll
+ * - Column and row are 1-based in the protocol, converted to 0-based here
+ *
+ * @param raw - Raw byte string that may contain an SGR mouse sequence.
+ * @returns Parsed mouse message, or `null` if the string is not a valid SGR mouse sequence.
+ */
+export function parseMouse(raw) {
+    const match = SGR_MOUSE_RE.exec(raw);
+    if (!match)
+        return null;
+    const buttonByte = parseInt(match[1], 10);
+    const rawCol = parseInt(match[2], 10);
+    const rawRow = parseInt(match[3], 10);
+    if (rawCol < 1 || rawRow < 1)
+        return null;
+    const col = rawCol - 1; // 1-based → 0-based
+    const row = rawRow - 1;
+    const suffix = match[4];
+    const shift = (buttonByte & 4) !== 0;
+    const alt = (buttonByte & 8) !== 0;
+    const ctrl = (buttonByte & 16) !== 0;
+    const isMotion = (buttonByte & 32) !== 0;
+    const isScroll = (buttonByte & 64) !== 0;
+    const lowBits = buttonByte & 3;
+    const buttonFromBits = (bits) => bits === 0 ? 'left' : bits === 1 ? 'middle' : bits === 2 ? 'right' : 'none';
+    let button;
+    let action;
+    if (isScroll) {
+        button = 'none';
+        action = lowBits === 0 ? 'scroll-up' : 'scroll-down';
+    }
+    else if (isMotion) {
+        button = buttonFromBits(lowBits);
+        action = 'move';
+    }
+    else {
+        button = buttonFromBits(lowBits);
+        action = suffix === 'M' ? 'press' : 'release';
+    }
+    return { type: 'mouse', button, action, col, row, shift, alt, ctrl };
+}
 //# sourceMappingURL=keys.js.map

package/dist/keys.js.map

@@ -1 +1 @@
-{"version":3,"file":"keys.js","sourceRoot":"","sources":["../src/keys.ts"],"names":[],"mappings":"AAEA,SAAS,MAAM,CAAC,GAAW,EAAE,IAAI,GAAG,KAAK,EAAE,GAAG,GAAG,KAAK,EAAE,KAAK,GAAG,KAAK;IACnE,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,GAAG,EAAE,IAAI,EAAE,GAAG,EAAE,KAAK,EAAE,CAAC;AAChD,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,QAAQ,CAAC,GAAW;IAClC,qCAAqC;IACrC,IAAI,GAAG,KAAK,QAAQ;QAAE,OAAO,MAAM,CAAC,IAAI,CAAC,CAAC;IAC1C,IAAI,GAAG,KAAK,QAAQ;QAAE,OAAO,MAAM,CAAC,MAAM,CAAC,CAAC;IAC5C,IAAI,GAAG,KAAK,QAAQ;QAAE,OAAO,MAAM,CAAC,OAAO,CAAC,CAAC;IAC7C,IAAI,GAAG,KAAK,QAAQ;QAAE,OAAO,MAAM,CAAC,MAAM,CAAC,CAAC;IAC5C,IAAI,GAAG,KAAK,QAAQ;QAAE,OAAO,MAAM,CAAC,MAAM,CAAC,CAAC;IAC5C,IAAI,GAAG,KAAK,QAAQ;QAAE,OAAO,MAAM,CAAC,KAAK,CAAC,CAAC;IAC3C,IAAI,GAAG,KAAK,SAAS;QAAE,OAAO,MAAM,CAAC,QAAQ,CAAC,CAAC;IAC/C,IAAI,GAAG,KAAK,SAAS;QAAE,OAAO,MAAM,CAAC,QAAQ,CAAC,CAAC;IAC/C,IAAI,GAAG,KAAK,SAAS;QAAE,OAAO,MAAM,CAAC,UAAU,CAAC,CAAC;IAEjD,uCAAuC;IACvC,IAAI,GAAG,KAAK,IAAI,IAAI,GAAG,KAAK,IAAI;QAAE,OAAO,MAAM,CAAC,OAAO,CAAC,CAAC;IACzD,IAAI,GAAG,KAAK,IAAI;QAAE,OAAO,MAAM,CAAC,KAAK,CAAC,CAAC;IACvC,IAAI,GAAG,KAAK,QAAQ;QAAE,OAAO,MAAM,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,IAAI,CAAC,CAAC,CAAC,YAAY;IAC5E,IAAI,GAAG,KAAK,MAAM;QAAE,OAAO,MAAM,CAAC,WAAW,CAAC,CAAC;IAC/C,IAAI,GAAG,KAAK,GAAG;QAAE,OAAO,MAAM,CAAC,OAAO,CAAC,CAAC;IAExC,iBAAiB;IACjB,IAAI,GAAG,KAAK,MAAM;QAAE,OAAO,MAAM,CAAC,QAAQ,CAAC,CAAC;IAE5C,SAAS;IACT,IAAI,GAAG,KAAK,MAAM;QAAE,OAAO,MAAM,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;IAE7C,qEAAqE;IACrE,IAAI,GAAG,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACrB,MAAM,IAAI,GAAG,GAAG,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC;QAC/B,IAAI,IAAI,IAAI,IAAI,IAAI,IAAI,IAAI,IAAI,EAAE,CAAC;YACjC,MAAM,MAAM,GAAG,MAAM,CAAC,YAAY,CAAC,IAAI,GAAG,IAAI,CAAC,CAAC,CAAC,+BAA+B;YAChF,OAAO,MAAM,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;QAC9B,CAAC;IACH,CAAC;IAED,8BAA8B;IAC9B,IAAI,GAAG,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACrB,MAAM,IAAI,GAAG,GAAG,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC;QAC/B,IAAI,IAAI,IAAI,IAAI,IAAI,IAAI,IAAI,IAAI,EAAE,CAAC;YACjC,OAAO,MAAM,CAAC,GAAG,CAAC,CAAC;QACrB,CAAC;IACH,CAAC;IAED,OAAO,MAAM,CAAC,SAAS,CAAC,CAAC;AAC3B,CAAC"}
+{"version":3,"file":"keys.js","sourceRoot":"","sources":["../src/keys.ts"],"names":[],"mappings":"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"}

package/dist/layout.d.ts

@@ -1,24 +1,50 @@
+/**
+ * Layout primitives for composing terminal UI views.
+ *
+ * Provides `place()` for positioning content within a fixed rectangle,
+ * and `vstack()`/`hstack()` for vertical and horizontal composition.
+ *
+ * @module layout
+ */
+/** Horizontal alignment option for {@link place}. */
 export type HAlign = 'left' | 'center' | 'right';
+/** Vertical alignment option for {@link place}. */
 export type VAlign = 'top' | 'middle' | 'bottom';
+/** Configuration for the {@link place} layout function. */
 export interface PlaceOptions {
+    /** Width of the bounding rectangle in visible characters. */
     readonly width: number;
+    /** Height of the bounding rectangle in lines. */
     readonly height: number;
+    /** Horizontal alignment within the rectangle. Default: `'left'`. */
     readonly hAlign?: HAlign;
+    /** Vertical alignment within the rectangle. Default: `'top'`. */
     readonly vAlign?: VAlign;
 }
 /**
  * Place content within a fixed-size rectangle, aligned horizontally and
  * vertically. Lines are padded/clipped to exactly `width` visible characters
  * and the output is exactly `height` lines tall.
+ *
+ * @param content - The text content to place (may contain newlines).
+ * @param options - Rectangle dimensions and alignment settings.
+ * @returns A string of exactly `height` lines, each exactly `width` visible characters.
  */
 export declare function place(content: string, options: PlaceOptions): string;
 /**
  * Vertical stack — join blocks with newlines.
+ *
+ * @param blocks - One or more rendered string blocks to stack vertically.
+ * @returns A single string with blocks separated by newlines.
  */
 export declare function vstack(...blocks: string[]): string;
 /**
  * Horizontal stack — place blocks side by side with a gap between columns.
  * Pads shorter blocks with empty lines to align rows.
+ *
+ * @param gap    - Number of space characters between adjacent columns.
+ * @param blocks - One or more rendered string blocks to stack horizontally.
+ * @returns A single string with blocks arranged side by side.
  */
 export declare function hstack(gap: number, ...blocks: string[]): string;
 //# sourceMappingURL=layout.d.ts.map

package/dist/layout.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"layout.d.ts","sourceRoot":"","sources":["../src/layout.ts"],"names":[],"mappings":"AAMA,MAAM,MAAM,MAAM,GAAG,MAAM,GAAG,QAAQ,GAAG,OAAO,CAAC;AACjD,MAAM,MAAM,MAAM,GAAG,KAAK,GAAG,QAAQ,GAAG,QAAQ,CAAC;AAEjD,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CAC1B;AAMD;;;;GAIG;AACH,wBAAgB,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,YAAY,GAAG,MAAM,CAqEpE;AAMD;;GAEG;AACH,wBAAgB,MAAM,CAAC,GAAG,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,CAElD;AAED;;;GAGG;AACH,wBAAgB,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,CAwB/D"}
+{"version":3,"file":"layout.d.ts","sourceRoot":"","sources":["../src/layout.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAQH,qDAAqD;AACrD,MAAM,MAAM,MAAM,GAAG,MAAM,GAAG,QAAQ,GAAG,OAAO,CAAC;AACjD,mDAAmD;AACnD,MAAM,MAAM,MAAM,GAAG,KAAK,GAAG,QAAQ,GAAG,QAAQ,CAAC;AAEjD,2DAA2D;AAC3D,MAAM,WAAW,YAAY;IAC3B,6DAA6D;IAC7D,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,iDAAiD;IACjD,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,oEAAoE;IACpE,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,iEAAiE;IACjE,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CAC1B;AAMD;;;;;;;;GAQG;AACH,wBAAgB,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,YAAY,GAAG,MAAM,CAqEpE;AAMD;;;;;GAKG;AACH,wBAAgB,MAAM,CAAC,GAAG,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,CAElD;AAED;;;;;;;GAOG;AACH,wBAAgB,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,CAwB/D"}

package/dist/layout.js

@@ -1,3 +1,11 @@
+/**
+ * Layout primitives for composing terminal UI views.
+ *
+ * Provides `place()` for positioning content within a fixed rectangle,
+ * and `vstack()`/`hstack()` for vertical and horizontal composition.
+ *
+ * @module layout
+ */
 import { visibleLength, clipToWidth } from './viewport.js';
 // ---------------------------------------------------------------------------
 // place()
@@ -6,6 +14,10 @@ import { visibleLength, clipToWidth } from './viewport.js';
  * Place content within a fixed-size rectangle, aligned horizontally and
  * vertically. Lines are padded/clipped to exactly `width` visible characters
  * and the output is exactly `height` lines tall.
+ *
+ * @param content - The text content to place (may contain newlines).
+ * @param options - Rectangle dimensions and alignment settings.
+ * @returns A string of exactly `height` lines, each exactly `width` visible characters.
  */
 export function place(content, options) {
     const { width, height, hAlign = 'left', vAlign = 'top' } = options;
@@ -71,6 +83,9 @@ export function place(content, options) {
 // ---------------------------------------------------------------------------
 /**
  * Vertical stack — join blocks with newlines.
+ *
+ * @param blocks - One or more rendered string blocks to stack vertically.
+ * @returns A single string with blocks separated by newlines.
  */
 export function vstack(...blocks) {
     return blocks.join('\n');
@@ -78,6 +93,10 @@ export function vstack(...blocks) {
 /**
  * Horizontal stack — place blocks side by side with a gap between columns.
  * Pads shorter blocks with empty lines to align rows.
+ *
+ * @param gap    - Number of space characters between adjacent columns.
+ * @param blocks - One or more rendered string blocks to stack horizontally.
+ * @returns A single string with blocks arranged side by side.
  */
 export function hstack(gap, ...blocks) {
     if (blocks.length === 0)
@@ -105,7 +124,12 @@ export function hstack(gap, ...blocks) {
     }
     return rows.join('\n');
 }
-/** Width of a string with ANSI escapes stripped. */
+/**
+ * Compute the visible width of a string after stripping ANSI escape sequences.
+ *
+ * @param s - The string possibly containing ANSI color/style codes.
+ * @returns The character count excluding escape sequences.
+ */
 function visualWidth(s) {
     // Strip ANSI escape sequences
     // eslint-disable-next-line no-control-regex

package/dist/layout.js.map

@@ -1 +1 @@
-{"version":3,"file":"layout.js","sourceRoot":"","sources":["../src/layout.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"layout.js","sourceRoot":"","sources":["../src/layout.ts"],"names":[],"mappings":"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"}

package/dist/navigable-table.d.ts

@@ -18,41 +18,81 @@
  */
 import { type TableColumn, type BijouContext } from '@flyingrobots/bijou';
 import { type KeyMap } from './keybindings.js';
+/** Immutable state for the navigable table widget. */
 export interface NavigableTableState {
+    /** Column definitions (headers, widths, alignment). */
     readonly columns: TableColumn[];
+    /** All data rows as arrays of cell strings. */
     readonly rows: readonly (readonly string[])[];
+    /** Index of the currently focused row. */
     readonly focusRow: number;
+    /** Vertical scroll offset (first visible row index). */
     readonly scrollY: number;
+    /** Maximum number of visible data rows. */
     readonly height: number;
 }
+/** Options for creating a new navigable table state. */
 export interface NavigableTableOptions {
+    /** Column definitions (headers, widths, alignment). */
     readonly columns: TableColumn[];
+    /** Data rows as arrays of cell strings. */
     readonly rows: readonly (readonly string[])[];
+    /** Maximum number of visible data rows (default: 10). */
     readonly height?: number;
 }
+/** Options for rendering the navigable table view. */
 export interface NavTableRenderOptions {
+    /** Character(s) prepended to the focused row's first cell (default: `"\u25b8"`). */
     readonly focusIndicator?: string;
+    /** Bijou context for theming and styling. */
     readonly ctx?: BijouContext;
 }
 /**
  * Create initial navigable table state.
  *
  * `height` defaults to 10 rows when not provided.
+ *
+ * @param options - Columns, rows, and optional viewport height.
+ * @returns Fresh table state with focus on the first row.
  */
 export declare function createNavigableTableState(options: NavigableTableOptions): NavigableTableState;
-/** Move focus to the next row (wraps around). */
+/**
+ * Move focus to the next row (wraps around).
+ *
+ * @param state - Current table state.
+ * @returns Updated table state with focus on the next row.
+ */
 export declare function navTableFocusNext(state: NavigableTableState): NavigableTableState;
-/** Move focus to the previous row (wraps around). */
+/**
+ * Move focus to the previous row (wraps around).
+ *
+ * @param state - Current table state.
+ * @returns Updated table state with focus on the previous row.
+ */
 export declare function navTableFocusPrev(state: NavigableTableState): NavigableTableState;
-/** Move focus down by one page (clamps to last row). */
+/**
+ * Move focus down by one page (clamps to last row).
+ *
+ * @param state - Current table state.
+ * @returns Updated table state with focus advanced by one page.
+ */
 export declare function navTablePageDown(state: NavigableTableState): NavigableTableState;
-/** Move focus up by one page (clamps to first row). */
+/**
+ * Move focus up by one page (clamps to first row).
+ *
+ * @param state - Current table state.
+ * @returns Updated table state with focus moved back by one page.
+ */
 export declare function navTablePageUp(state: NavigableTableState): NavigableTableState;
 /**
  * Render the navigable table with a focus indicator on the focused row.
  *
  * Slices visible rows based on `scrollY` and `height`, prepends a focus
  * indicator to the first column, then delegates to core `table()`.
+ *
+ * @param state - Current table state.
+ * @param options - Rendering options (focus indicator, context).
+ * @returns Rendered table string with focus indicator on the active row.
  */
 export declare function navigableTable(state: NavigableTableState, options?: NavTableRenderOptions): string;
 /**
@@ -68,6 +108,10 @@ export declare function navigableTable(state: NavigableTableState, options?: Nav
  *   quit:      { type: 'quit' },
  * });
  * ```
+ *
+ * @template Msg - Application message type dispatched by key bindings.
+ * @param actions - Map of navigation actions to message values.
+ * @returns Preconfigured key map with vim-style table row bindings.
  */
 export declare function navTableKeyMap<Msg>(actions: {
     focusNext: Msg;