@sigrun/tui 0.1.0 → 0.1.1

package/dist/blocks/collection/list.js

@@ -0,0 +1,273 @@
+/**
+ * The `list` display (UI-blocks spec §5.5): rows with group headings in
+ * `groups` order, 2-cell-per-level nesting on `children`, `numbered`,
+ * checkboxes, quiet items folded behind "N more", and the multi-select
+ * bulk action menu (`.`).
+ *
+ * Keys (spec §12.4): Up/Down move the cursor; `x` toggles the checkable
+ * field and dispatches `onCheck` (`edit`, `{itemId, value}`); `Space`
+ * selects; `.` opens the bulk menu; Enter activates a row (`onActivate`
+ * with `{itemId}`), unfolds the "N more" fold, or picks a menu entry.
+ * Selection, folds and menus are view-only — they never dispatch.
+ *
+ * The bulk menu is the seam Task 5's form renderer plugs into: an
+ * action with a `form` opens a minimal seam form here (labeled line
+ * per top-level field name, values keyed by name) and its submit rides
+ * the bulk payload as `{ids, values}` — mirroring U1 Task 3's note.
+ */
+import { bindText } from "../context.js";
+import { truncate, widthClassOf } from "../width.js";
+import { cardLines } from "./card.js";
+import { CollectionState, childItems, collectionItems, dispatchActivate, dispatchBulk, dispatchCheck, groupItems, isQuiet, sortItems, } from "./shared.js";
+/** Top-level `form` block fields of a bulk action's form tree. */
+function seamFields(form, ctx) {
+    const root = form.root;
+    if (root.type !== "form")
+        return [];
+    const fields = [];
+    for (const child of root.children) {
+        if (child.type === "section")
+            continue;
+        fields.push({ name: child.name, label: bindText(child.label, ctx) || child.name });
+    }
+    return fields;
+}
+/** `list`: groups, nesting, numbering, checkboxes, quiet fold, bulk menu. */
+export class ListComponent {
+    #block;
+    #ctx;
+    #state = new CollectionState();
+    #tick = 0;
+    constructor(block, ctx) {
+        this.#block = block;
+        this.#ctx = ctx;
+    }
+    /** The items in render order (block's initial `sort`). */
+    #items() {
+        return sortItems(collectionItems(this.#block, this.#ctx), this.#block.sort);
+    }
+    /** Flatten the render into addressable rows. */
+    #rows() {
+        const rows = [];
+        const push = (row, depth) => {
+            rows.push({ kind: "item", row, depth });
+            for (const child of childItems(this.#block, row.item))
+                push(child, depth + 1);
+        };
+        for (const group of this.#groups()) {
+            if (group.id !== "" && group.title !== "") {
+                rows.push({ kind: "group", groupId: group.id });
+            }
+            if (group.collapsed && !this.#state.unfoldedGroups.has(group.id))
+                continue;
+            const quiet = group.items.filter((row) => isQuiet(this.#block, this.#ctx, row.item));
+            const loud = group.items.filter((row) => !isQuiet(this.#block, this.#ctx, row.item));
+            for (const row of loud)
+                push(row, 0);
+            if (quiet.length > 0) {
+                if (this.#state.quietShownFor(group.id)) {
+                    for (const row of quiet)
+                        push(row, 0);
+                    rows.push({ kind: "quiet", groupId: group.id, quietRows: [] }); // the "Show less" row
+                }
+                else {
+                    rows.push({ kind: "quiet", groupId: group.id, quietRows: quiet });
+                }
+            }
+        }
+        return rows;
+    }
+    #groups() {
+        return groupItems(this.#block, this.#items(), this.#ctx);
+    }
+    render(width) {
+        this.#tick += 1;
+        const rows = this.#rows();
+        if (this.#state.cursor >= rows.length)
+            this.#state.cursor = Math.max(0, rows.length - 1);
+        const lines = [];
+        const unicode = this.#ctx.unicode;
+        if (this.#state.menu?.kind === "bulk") {
+            lines.push(truncate(`Bulk actions (${this.#state.selected.size} selected)`, width));
+            const actions = this.#block.bulkActions ?? [];
+            actions.forEach((action, index) => {
+                const cursor = index === this.#state.menuCursor ? "> " : "  ";
+                lines.push(truncate(`${cursor}${bindText(action.label, this.#ctx) || action.id}`, width));
+            });
+            return lines;
+        }
+        if (this.#state.menu?.kind === "form") {
+            const menu = this.#state.menu;
+            const value = this.#state.formBuffer === "" ? "…" : this.#state.formBuffer;
+            for (const field of seamFields(menu.form, this.#ctx)) {
+                lines.push(truncate(`${field.label}: ${value}`, width));
+            }
+            lines.push(truncate("Enter to submit · Esc to cancel", width));
+            return lines;
+        }
+        rows.forEach((row, index) => {
+            const cursor = index === this.#state.cursor ? "> " : "  ";
+            if (row.kind === "group") {
+                lines.push(truncate(cursor + this.#ctx.theme.bold(`## ${this.#groupTitle(row.groupId ?? "")}`), width));
+                return;
+            }
+            if (row.kind === "quiet") {
+                const count = row.quietRows?.length ?? 0;
+                const label = this.#state.quietShownFor(row.groupId ?? "") ? "Show less" : `${count} more`;
+                lines.push(truncate(cursor + this.#ctx.theme.dim(label), width));
+                return;
+            }
+            const item = row.row;
+            if (item === undefined)
+                return;
+            let prefix = "";
+            const indentStr = "  ".repeat(row.depth ?? 0);
+            if (this.#block.numbered === true && (row.depth ?? 0) === 0) {
+                prefix += `${this.#numberOf(rows, index)}. `;
+            }
+            if (this.#block.checkable !== undefined) {
+                prefix += this.#state.checkedValue(this.#block, item) ? "[x] " : "[ ] ";
+            }
+            if (this.#block.select !== undefined) {
+                const box = this.#state.selected.has(item.id)
+                    ? unicode
+                        ? "(•) "
+                        : "(*) "
+                    : "( ) ";
+                prefix += box;
+            }
+            const card = cardLines(this.#block.item, item.item, this.#ctx, width - cursor.length - indentStr.length - prefix.length, 0, this.#tick);
+            // The first card line carries the prefixes (title line by slot
+            // order — an eyebrow hoists the prefixes onto the eyebrow line,
+            // keeping one fixed line layout).
+            const [first, ...rest] = card;
+            lines.push(truncate(`${cursor}${indentStr}${prefix}${first ?? ""}`, width));
+            for (const line of rest) {
+                lines.push(truncate(`${cursor}${indentStr}${" ".repeat(prefix.length)}${line}`, width));
+            }
+        });
+        return lines;
+    }
+    #groupTitle(id) {
+        return this.#groups().find((group) => group.id === id)?.title ?? id;
+    }
+    /** The running number of a depth-0 item row (numbered lists). */
+    #numberOf(rows, at) {
+        let number = 0;
+        for (let i = 0; i <= at; i++) {
+            const row = rows[i];
+            if (row?.kind === "item" && row.depth === 0)
+                number += 1;
+        }
+        return number;
+    }
+    handleInput(data) {
+        if (this.#state.menu !== null) {
+            this.#menuInput(data);
+            return;
+        }
+        const rows = this.#rows();
+        if (data === "\x1b[B") {
+            this.#state.cursor = Math.min(rows.length - 1, this.#state.cursor + 1);
+            return;
+        }
+        if (data === "\x1b[A") {
+            this.#state.cursor = Math.max(0, this.#state.cursor - 1);
+            return;
+        }
+        const row = rows[this.#state.cursor];
+        if (row === undefined)
+            return;
+        if (data === "x" && row.kind === "item" && row.row !== undefined) {
+            dispatchCheck(this.#block, this.#ctx, this.#state, row.row);
+            return;
+        }
+        if (data === " " && this.#block.select !== undefined && row.kind === "item" && row.row !== undefined) {
+            const id = row.row.id;
+            if (this.#state.selected.has(id))
+                this.#state.selected.delete(id);
+            else
+                this.#state.selected.add(id);
+            return;
+        }
+        if (data === "." && this.#block.select === "multi" && this.#state.selected.size > 0) {
+            if ((this.#block.bulkActions ?? []).length > 0) {
+                this.#state.menu = { kind: "bulk" };
+                this.#state.menuCursor = 0;
+            }
+            return;
+        }
+        if (data !== "\r")
+            return;
+        if (row.kind === "quiet") {
+            this.#state.toggleQuiet(row.groupId ?? "");
+            return;
+        }
+        if (row.kind === "group" && row.groupId !== undefined) {
+            if (this.#state.unfoldedGroups.has(row.groupId)) {
+                this.#state.unfoldedGroups.delete(row.groupId);
+            }
+            else {
+                this.#state.unfoldedGroups.add(row.groupId);
+            }
+            return;
+        }
+        if (row.row !== undefined)
+            dispatchActivate(this.#block, this.#ctx, row.row);
+    }
+    #menuInput(data) {
+        const menu = this.#state.menu;
+        if (menu === null)
+            return;
+        if (data === "\x1b") {
+            this.#state.menu = null;
+            return;
+        }
+        if (menu.kind === "form") {
+            if (data === "\r") {
+                const values = {};
+                for (const field of seamFields(menu.form, this.#ctx)) {
+                    values[field.name] = this.#state.formBuffer;
+                }
+                this.#state.formBuffer = "";
+                dispatchBulk(this.#ctx, this.#state, menu.onSubmit, values);
+                return;
+            }
+            if (data === "\x7f") {
+                this.#state.formBuffer = this.#state.formBuffer.slice(0, -1);
+                return;
+            }
+            if (!data.startsWith("\x1b") && data.length >= 1) {
+                this.#state.formBuffer += data;
+            }
+            return;
+        }
+        const actions = this.#block.bulkActions ?? [];
+        if (data === "\x1b[B") {
+            this.#state.menuCursor = Math.min(actions.length - 1, this.#state.menuCursor + 1);
+            return;
+        }
+        if (data === "\x1b[A") {
+            this.#state.menuCursor = Math.max(0, this.#state.menuCursor - 1);
+            return;
+        }
+        if (data !== "\r")
+            return;
+        const action = actions[this.#state.menuCursor];
+        if (action === undefined)
+            return;
+        if (action.form !== undefined) {
+            // The Task-5 seam: the form's full rendering lands with the
+            // form block; this menu opens the seam form and its values
+            // ride the payload (mirroring U1 Task 3's note in rows.tsx).
+            this.#state.menu = { kind: "form", form: action.form, onSubmit: action.onSubmit };
+            this.#state.formBuffer = "";
+            return;
+        }
+        dispatchBulk(this.#ctx, this.#state, action.onSubmit);
+    }
+    invalidate() {
+        // State survives re-renders (view-only by design).
+    }
+}
+export { widthClassOf };

package/dist/blocks/collection/move.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Keyboard moves (UI-blocks U2 Task 4, spec §12.4): the shared
+ * placement machinery the lanes and calendar displays drive. `m` picks
+ * the item under the cursor up, arrows move the placement (left/right
+ * across groups, up/down within), Enter drops — dispatching
+ * `{itemId, from: {group, index}, to: {group, index}}`, the EXACT
+ * payload U1's pointer drop builds — and Esc cancels.
+ *
+ * The held item counts as PRESENT in the lane sizing (its removal
+ * happens on drop, not on pickup) — the same rule as U1's lanes. A
+ * dropped placement equal to the item's current one dispatches nothing.
+ *
+ * Review Focus 1: a resize while picked up is handled by the DISPLAYS,
+ * which recompute placements from the live block data on every key; the
+ * held state survives because it lives in the component, not the
+ * rendered lines.
+ */
+import type { CollectionBlock, JsonObject } from "@sigrun/shared/blocks";
+import { type CollectionItem, type ItemGroup } from "./shared.js";
+import type { BlockCtx } from "../context.js";
+/** A placement: a group plus the index within its VISIBLE items. */
+export interface Placement {
+    readonly group: string;
+    readonly index: number;
+}
+/** The keyboard-move session (the picked-up item and its placement). */
+export interface MoveState {
+    readonly itemId: string;
+    readonly from: Placement;
+    readonly at: Placement;
+}
+/** The visible items of a group (sorted, loud items — quiet items are
+ *  folded behind the fold row and not placement targets). */
+export declare function visibleLaneItems(block: CollectionBlock, ctx: BlockCtx, group: ItemGroup): CollectionItem[];
+/** Every group with its visible items, in group order. */
+export declare function lanes(block: CollectionBlock, ctx: BlockCtx): {
+    groups: ItemGroup[];
+    visible: Map<string, CollectionItem[]>;
+};
+/** An item's current placement across every group. */
+export declare function placementOf(groups: readonly ItemGroup[], visible: ReadonlyMap<string, CollectionItem[]>, itemId: string): Placement | undefined;
+/** The move payload (spec §6.3 step 2; U1's pointer-drop shape exactly). */
+export declare function movePayload(move: {
+    itemId: string;
+    from: Placement;
+    to: Placement;
+}): JsonObject;
+/** Move the placement left/right across groups (the index clamps to
+ *  the target lane's size; out-of-range directions are inert). */
+export declare function shiftAcross(move: MoveState, groups: readonly ItemGroup[], visible: ReadonlyMap<string, CollectionItem[]>, delta: 1 | -1): MoveState;
+/** Move the placement up/down within its group (clamped). */
+export declare function shiftWithin(move: MoveState, visible: ReadonlyMap<string, CollectionItem[]>, delta: 1 | -1): MoveState;
+/**
+ * Dispatch the drop: nothing when the placement equals the current
+ * position; otherwise the `move` action with the U1 payload. The
+ * optimistic flip lives in SurfaceState's overlay — the component
+ * itself keeps no per-item move override.
+ */
+export declare function dispatchMove(block: CollectionBlock, ctx: BlockCtx, move: MoveState): void;
+/** The per-display move session state (held in the component). */
+export declare class MoveSession {
+    held: MoveState | undefined;
+    /** Pick up the item (undefined placement = no pickup). */
+    pickUp(itemId: string, from: Placement): void;
+    /** Cancel (Esc): drop the session without dispatching. */
+    cancel(): void;
+}

package/dist/blocks/collection/move.js

@@ -0,0 +1,96 @@
+/**
+ * Keyboard moves (UI-blocks U2 Task 4, spec §12.4): the shared
+ * placement machinery the lanes and calendar displays drive. `m` picks
+ * the item under the cursor up, arrows move the placement (left/right
+ * across groups, up/down within), Enter drops — dispatching
+ * `{itemId, from: {group, index}, to: {group, index}}`, the EXACT
+ * payload U1's pointer drop builds — and Esc cancels.
+ *
+ * The held item counts as PRESENT in the lane sizing (its removal
+ * happens on drop, not on pickup) — the same rule as U1's lanes. A
+ * dropped placement equal to the item's current one dispatches nothing.
+ *
+ * Review Focus 1: a resize while picked up is handled by the DISPLAYS,
+ * which recompute placements from the live block data on every key; the
+ * held state survives because it lives in the component, not the
+ * rendered lines.
+ */
+import { collectionItems, groupItems, isQuiet, sortItems, } from "./shared.js";
+/** The visible items of a group (sorted, loud items — quiet items are
+ *  folded behind the fold row and not placement targets). */
+export function visibleLaneItems(block, ctx, group) {
+    const sorted = sortItems(group.items, block.sort);
+    return sorted.filter((row) => !isQuiet(block, ctx, row.item));
+}
+/** Every group with its visible items, in group order. */
+export function lanes(block, ctx) {
+    const groups = groupItems(block, sortItems(collectionItems(block, ctx), block.sort), ctx);
+    const visible = new Map();
+    for (const group of groups) {
+        visible.set(group.id, visibleLaneItems(block, ctx, group));
+    }
+    return { groups, visible };
+}
+/** An item's current placement across every group. */
+export function placementOf(groups, visible, itemId) {
+    for (const group of groups) {
+        const items = visible.get(group.id) ?? [];
+        const index = items.findIndex((row) => row.id === itemId);
+        if (index >= 0)
+            return { group: group.id, index };
+    }
+    return undefined;
+}
+/** The move payload (spec §6.3 step 2; U1's pointer-drop shape exactly). */
+export function movePayload(move) {
+    return {
+        itemId: move.itemId,
+        from: { group: move.from.group, index: move.from.index },
+        to: { group: move.to.group, index: move.to.index },
+    };
+}
+/** Move the placement left/right across groups (the index clamps to
+ *  the target lane's size; out-of-range directions are inert). */
+export function shiftAcross(move, groups, visible, delta) {
+    const order = groups.map((group) => group.id);
+    const laneIndex = order.indexOf(move.at.group);
+    const target = order[laneIndex + delta];
+    if (target === undefined)
+        return move;
+    const size = (visible.get(target) ?? []).length;
+    return {
+        ...move,
+        at: { group: target, index: Math.min(move.at.index, size) },
+    };
+}
+/** Move the placement up/down within its group (clamped). */
+export function shiftWithin(move, visible, delta) {
+    const size = (visible.get(move.at.group) ?? []).length;
+    const index = delta === 1 ? Math.min(move.at.index + 1, size) : Math.max(move.at.index - 1, 0);
+    return { ...move, at: { group: move.at.group, index } };
+}
+/**
+ * Dispatch the drop: nothing when the placement equals the current
+ * position; otherwise the `move` action with the U1 payload. The
+ * optimistic flip lives in SurfaceState's overlay — the component
+ * itself keeps no per-item move override.
+ */
+export function dispatchMove(block, ctx, move) {
+    if (block.onMove === undefined)
+        return;
+    if (move.from.group === move.at.group && move.from.index === move.at.index)
+        return;
+    ctx.dispatch({ type: "move", name: block.onMove }, movePayload({ itemId: move.itemId, from: move.from, to: move.at }));
+}
+/** The per-display move session state (held in the component). */
+export class MoveSession {
+    held;
+    /** Pick up the item (undefined placement = no pickup). */
+    pickUp(itemId, from) {
+        this.held = { itemId, from, at: from };
+    }
+    /** Cancel (Esc): drop the session without dispatching. */
+    cancel() {
+        this.held = undefined;
+    }
+}

package/dist/blocks/collection/shared.d.ts

@@ -0,0 +1,87 @@
+/**
+ * Shared collection machinery (UI-blocks spec §5.5): item resolution,
+ * grouping, sorting and the view-only interaction state (selection,
+ * folds, menu) the list/table/grid displays drive.
+ *
+ * Every interactive display owns a {@link CollectionState} — its shape
+ * mirrors the `/view/<blockId>/` branch Task 4's surface state will own
+ * (sort, page, selection, expanded, quietShown). View-only state never
+ * dispatches (§6.2): only `onCheck` (`edit`), `onActivate`, and bulk
+ * `submit` actions reach `ctx.dispatch`.
+ */
+import type { CollectionBlock, JsonObject, JsonValue, Tree } from "@sigrun/shared/blocks";
+import { type BlockCtx } from "../context.js";
+/** A resolved collection row: the item and its stable id. */
+export interface CollectionItem {
+    id: string;
+    item: JsonObject;
+}
+/** A resolved group: heading text and its items, in `groups` order. */
+export interface ItemGroup {
+    id: string;
+    title: string;
+    collapsed: boolean;
+    items: CollectionItem[];
+}
+/** Resolve `items` to rows, dropping malformed entries. */
+export declare function collectionItems(block: CollectionBlock, ctx: BlockCtx): CollectionItem[];
+/** Nested child rows of an item (the `children` field's records). */
+export declare function childItems(block: CollectionBlock, item: JsonObject): CollectionItem[];
+/** Compare two items on `field`, ascending. */
+export declare function compareItems(a: JsonObject, b: JsonObject, field: string): number;
+/** Order items by a `{field, dir}` sort (stable; view state wins over the block's). */
+export declare function sortItems(items: readonly CollectionItem[], sort: {
+    field: string;
+    dir: "asc" | "desc";
+} | undefined): CollectionItem[];
+/**
+ * Group items by `groupBy`: declared `groups` in declared order, then
+ * unseen values in first-appearance item order. With no `groupBy`,
+ * one anonymous group holds everything.
+ */
+export declare function groupItems(block: CollectionBlock, items: readonly CollectionItem[], ctx: BlockCtx): ItemGroup[];
+/** Is an item quiet (folded behind "N more")? */
+export declare function isQuiet(block: CollectionBlock, ctx: BlockCtx, item: JsonValue): boolean;
+/**
+ * The view-only interaction state of one collection component. The
+ * checkable toggle's optimistic flip is part of it: the data update
+ * that follows a successful `onCheck` replaces the optimistic value
+ * (§6.3's convention, without moves).
+ */
+export declare class CollectionState {
+    cursor: number;
+    readonly selected: Set<string>;
+    readonly checkedOverrides: Map<string, boolean>;
+    readonly expanded: Set<string>;
+    readonly unfoldedGroups: Set<string>;
+    /** The groups whose quiet fold is open (per-group; Task 3's global
+     *  toggle became per-group with the lanes' per-lane folds). */
+    readonly quietOpen: Set<string>;
+    /** Is the quiet fold of `groupId` open? */
+    quietShownFor(groupId: string): boolean;
+    /** Toggle the quiet fold of `groupId`. */
+    toggleQuiet(groupId: string): void;
+    /** The open overlay: the sort choice, the bulk menu, the seam form,
+     *  or the compact lanes' "Move to…" target list (Task 4). */
+    menu: {
+        kind: "sort";
+    } | {
+        kind: "bulk";
+    } | {
+        kind: "form";
+        form: Tree;
+        onSubmit: string;
+    } | {
+        kind: "moveTo";
+    } | null;
+    menuCursor: number;
+    formBuffer: string;
+    /** The effective checked value of an item (data plus the optimistic flip). */
+    checkedValue(block: CollectionBlock, row: CollectionItem): boolean;
+}
+/** Dispatch the `onCheck` edit for an item (spec §5.5: `{itemId, value}`). */
+export declare function dispatchCheck(block: CollectionBlock, ctx: BlockCtx, state: CollectionState, row: CollectionItem): void;
+/** Dispatch `onActivate` for an item, payload `{itemId}`. */
+export declare function dispatchActivate(block: CollectionBlock, ctx: BlockCtx, row: CollectionItem): void;
+/** Dispatch a bulk action's submit for the current selection. */
+export declare function dispatchBulk(ctx: BlockCtx, state: CollectionState, onSubmit: string, values?: JsonObject): void;