@sigrun/tui 0.4.1 → 0.5.0

package/dist/blocks/layout.js

@@ -0,0 +1,155 @@
+/**
+ * The layout blocks (UI-blocks spec §5.2): `stack`, `columns`, `grid`,
+ * `section` as pi-tui components.
+ *
+ * Columns/grid honour the compact fallbacks (spec §12.3): `columns`
+ * stack when the minimums don't fit; `grid` runs
+ * `max(1, floor(width / minItemWidth))` columns so a compact pane gets
+ * one. Every line every block emits is clamped to the pane
+ * ({@link truncate} — Review Focus 2).
+ */
+import { visibleWidth } from "@earendil-works/pi-tui";
+import { renderBlock } from "./render.js";
+import { bindText, bindTone } from "./context.js";
+import { SIZE_CELLS, pad, truncate } from "./width.js";
+import { toneFg, toneMarker } from "./tones.js";
+/** The blank line counts the `gap` tokens map to. */
+const GAP_LINES = { s: 0, m: 1, l: 2 };
+/** The section header rule character. */
+const RULE = "─";
+/**
+ * A component from a width-aware line builder. Each produced line is
+ * clamped to the render width (the invariant every block must keep).
+ */
+export class Lines {
+    #build;
+    constructor(build) {
+        this.#build = build;
+    }
+    render(width) {
+        return this.#build(width).map((line) => truncate(line, width));
+    }
+    invalidate() {
+        // Stateless render: lines re-assemble on the next render call.
+    }
+}
+/** Join child blocks vertically, a blank line between neighbours. */
+function stacked(children, ctx, width, gap) {
+    const out = [];
+    for (const child of children) {
+        const lines = renderBlock(child, ctx).render(width);
+        if (out.length > 0 && lines.length > 0) {
+            for (let i = 0; i < gap; i++)
+                out.push("");
+        }
+        out.push(...lines);
+    }
+    return out;
+}
+/** Render `children` vertically with `gap` blank lines between. */
+export function renderStack(block, ctx) {
+    return new Lines((width) => stacked(block.children, ctx, width, GAP_LINES[block.gap ?? "m"]));
+}
+/** Render children side by side, stacking when the minimums don't fit. */
+export function renderColumns(block, ctx) {
+    return new Lines((width) => {
+        const minimums = block.children.map((child) => child.minWidth === undefined ? SIZE_CELLS.s : SIZE_CELLS[child.minWidth]);
+        const total = minimums.reduce((a, b) => a + b, 0) + Math.max(0, block.children.length - 1);
+        // Compact fallback (spec §12.3): stack when the minimums don't fit.
+        if (width < total) {
+            return stacked(block.children.map((child) => child.block), ctx, width, 1);
+        }
+        // Side by side: render each child at a weighted slot, then zip
+        // the line arrays into rows (shorter columns pad with blanks).
+        const weights = block.children.map((child) => child.weight ?? 1);
+        const weightSum = weights.reduce((a, b) => a + b, 0);
+        const separators = block.children.length - 1;
+        const slots = weights.map((weight) => Math.max(1, Math.floor(((width - separators) * weight) / weightSum)));
+        const rendered = block.children.map((child, index) => renderBlock(child.block, ctx).render(slots[index]));
+        const height = Math.max(...rendered.map((lines) => lines.length));
+        const rows = [];
+        for (let row = 0; row < height; row++) {
+            rows.push(rendered
+                .map((lines, index) => pad(lines[row] ?? "", slots[index]))
+                .join(" "));
+        }
+        return rows;
+    });
+}
+/** Render children in as many columns as `minItemWidth` allows. */
+export function renderGrid(block, ctx) {
+    return new Lines((width) => {
+        const minItem = SIZE_CELLS[block.minItemWidth];
+        const columns = Math.max(1, Math.floor(width / minItem));
+        const columnWidth = Math.max(1, Math.floor((width - (columns - 1)) / columns));
+        // Slot each child by its span ("full" spans every column).
+        const rows = [];
+        let current = [];
+        let used = 0;
+        const flush = () => {
+            if (current.length > 0)
+                rows.push(current);
+            current = [];
+            used = 0;
+        };
+        for (const child of block.children) {
+            let span = 1;
+            if (child.span === "full")
+                span = columns;
+            else if (child.span !== undefined)
+                span = Math.min(child.span, columns);
+            if (used > 0 && used + span > columns)
+                flush();
+            current.push({
+                span,
+                lines: renderBlock(child.block, ctx).render(columnWidth * span + (span - 1)),
+            });
+            used += span;
+        }
+        flush();
+        // Zip each row's cells into lines (shorter cells pad with blanks).
+        const out = [];
+        for (const row of rows) {
+            const height = Math.max(...row.map((cell) => cell.lines.length));
+            const widths = row.map((cell) => columnWidth * cell.span + (cell.span - 1));
+            for (let line = 0; line < height; line++) {
+                out.push(row
+                    .map((cell, index) => pad(cell.lines[line] ?? "", widths[index]))
+                    .join(" "));
+            }
+        }
+        return out;
+    });
+}
+/** Render a titled, optionally toned group of children. */
+export function renderSection(block, ctx) {
+    return new Lines((width) => {
+        const title = bindText(block.title ?? "", ctx);
+        const subtitle = bindText(block.subtitle ?? "", ctx);
+        const out = [];
+        if (title !== "") {
+            if (block.tone !== undefined) {
+                const tone = bindTone(block.tone, ctx);
+                const head = `${toneFg(ctx.theme, tone)(toneMarker(tone, !ctx.unicode))} ${title}`;
+                const rule = RULE.repeat(Math.max(0, width - visibleWidth(head) - 1));
+                out.push(`${head} ${ctx.theme.dim(rule)}`);
+            }
+            else {
+                const rule = RULE.repeat(Math.max(0, width - visibleWidth(title) - 1));
+                out.push(`${title} ${ctx.theme.dim(rule)}`);
+            }
+        }
+        if (subtitle !== "")
+            out.push(ctx.theme.dim(subtitle));
+        // `collapsed` is the author's INITIAL state (§5.2): children stay
+        // hidden until a later task's toggle expands them.
+        const children = block.collapsed
+            ? []
+            : block.children.filter((child) => "name" in child === false);
+        const inner = width - 2;
+        const body = stacked(children, ctx, Math.max(1, inner), GAP_LINES.m);
+        for (const line of body)
+            out.push(line === "" ? "" : `  ${line}`);
+        return out;
+    });
+}

package/dist/blocks/log.d.ts

@@ -0,0 +1,24 @@
+/**
+ * The `log` block (UI-blocks spec §5.3): bound `{at?, level?, text}[]`
+ * lines in a block-local viewport of {@link LOG_VIEWPORT_ROWS} rows.
+ *
+ * With `follow` the viewport pins to the tail until the user scrolls
+ * up; scrolling back to the bottom re-arms the following (the
+ * transcript convention). Per-level tones default `error`→bad,
+ * `warn`→warn, `info`→neutral, `debug`→info (the muted token);
+ * `tones` overrides per level. `wrap` folds long lines instead of
+ * truncating them.
+ */
+import type { Component } from "@earendil-works/pi-tui";
+import type { LogBlock } from "@sigrun/shared/blocks";
+import { type BlockCtx } from "./context.js";
+/** The viewport height in rows. */
+export declare const LOG_VIEWPORT_ROWS = 10;
+/** `log`: the follow-tail viewport. */
+export declare class LogComponent implements Component {
+    #private;
+    constructor(block: LogBlock, ctx: BlockCtx);
+    render(width: number): string[];
+    handleInput(data: string): void;
+    invalidate(): void;
+}

package/dist/blocks/log.js

@@ -0,0 +1,111 @@
+/**
+ * The `log` block (UI-blocks spec §5.3): bound `{at?, level?, text}[]`
+ * lines in a block-local viewport of {@link LOG_VIEWPORT_ROWS} rows.
+ *
+ * With `follow` the viewport pins to the tail until the user scrolls
+ * up; scrolling back to the bottom re-arms the following (the
+ * transcript convention). Per-level tones default `error`→bad,
+ * `warn`→warn, `info`→neutral, `debug`→info (the muted token);
+ * `tones` overrides per level. `wrap` folds long lines instead of
+ * truncating them.
+ */
+import { formatValue } from "@sigrun/shared/blocks";
+import { bindRaw } from "./context.js";
+import { truncate } from "./width.js";
+import { toneFg } from "./tones.js";
+/** The viewport height in rows. */
+export const LOG_VIEWPORT_ROWS = 10;
+/** The default per-level tones (spec §5.3's table; `debug` mutes). */
+const LEVEL_TONES = {
+    error: "bad",
+    warn: "warn",
+    info: "neutral",
+    debug: "info",
+};
+/** Read the bound lines, dropping malformed entries. */
+function logLines(block, ctx) {
+    const raw = bindRaw(block.lines, ctx);
+    if (!Array.isArray(raw))
+        return [];
+    const out = [];
+    for (const entry of raw) {
+        if (entry === null || typeof entry !== "object" || Array.isArray(entry))
+            continue;
+        const record = entry;
+        if (typeof record.text !== "string")
+            continue;
+        out.push({
+            at: typeof record.at === "number" || typeof record.at === "string" ? record.at : undefined,
+            level: typeof record.level === "string" ? record.level : undefined,
+            text: record.text,
+        });
+    }
+    return out;
+}
+/** The head of one line: `time [level] ` (each part optional). */
+function lineHead(line, ctx) {
+    const at = line.at === undefined
+        ? ""
+        : formatValue(line.at, "time", ctx.locale, ctx.timeZone);
+    const level = line.level === undefined ? "" : `[${line.level}]`;
+    return [at, level].filter((part) => part !== "").join(" ");
+}
+/** `log`: the follow-tail viewport. */
+export class LogComponent {
+    #block;
+    #ctx;
+    /** The first visible row in the stream; `undefined` = the tail. */
+    #offset;
+    constructor(block, ctx) {
+        this.#block = block;
+        this.#ctx = ctx;
+    }
+    /** Every display row: one source line plus its wrapped folds. */
+    #rows(width) {
+        const rows = [];
+        for (const line of logLines(this.#block, this.#ctx)) {
+            const head = lineHead(line, this.#ctx);
+            const text = head === "" ? line.text : `${head} ${line.text}`;
+            const tone = this.#block.tones?.[line.level ?? ""] ??
+                (line.level === undefined ? undefined : LEVEL_TONES[line.level]);
+            const paint = tone === undefined ? (s) => s : toneFg(this.#ctx.theme, tone);
+            if (this.#block.wrap === true) {
+                // Hard-fold at the cell budget (logs are not prose).
+                for (let at = 0; at < text.length; at += Math.max(1, width)) {
+                    rows.push(paint(text.slice(at, at + Math.max(1, width))));
+                }
+            }
+            else {
+                rows.push(truncate(paint(text), width));
+            }
+        }
+        return rows;
+    }
+    render(width) {
+        const rows = this.#rows(width);
+        if (rows.length <= LOG_VIEWPORT_ROWS)
+            return rows;
+        const tail = this.#block.follow === true ? rows.length - LOG_VIEWPORT_ROWS : 0;
+        const start = Math.max(0, Math.min(this.#offset ?? tail, rows.length - LOG_VIEWPORT_ROWS));
+        return rows.slice(start, start + LOG_VIEWPORT_ROWS);
+    }
+    handleInput(data) {
+        // The viewport moves by display rows within the last render's
+        // stream; `render` clamps the offset back into range.
+        const tail = Math.max(0, logLines(this.#block, this.#ctx).length - LOG_VIEWPORT_ROWS);
+        if (data === "\x1b[A") {
+            const current = this.#offset ?? tail;
+            this.#offset = Math.max(0, current - 1);
+        }
+        else if (data === "\x1b[B") {
+            if (this.#offset !== undefined) {
+                this.#offset += 1;
+                if (this.#offset >= tail)
+                    this.#offset = undefined; // re-arm follow
+            }
+        }
+    }
+    invalidate() {
+        // The viewport offset is the only mutable state.
+    }
+}

package/dist/blocks/meter.d.ts

@@ -0,0 +1,16 @@
+/**
+ * The `meter` block (UI-blocks spec §5.3): `label value` plus a bar
+ * filling the rest of the line — `█`/`░` on a Unicode terminal,
+ * `#`/`-` without one. A crossed threshold's tone paints the bar and
+ * the value (the LAST crossed threshold wins, matching the webui).
+ */
+import type { Component } from "@earendil-works/pi-tui";
+import type { MeterBlock } from "@sigrun/shared/blocks";
+import { type BlockCtx } from "./context.js";
+/** `meter`: one line, `label value bar` exactly `width` cells. */
+export declare function renderMeter(block: MeterBlock, ctx: BlockCtx): Component;
+/**
+ * The bare meter bar (no label): `filled`/`empty` cells of the 0–1
+ * `level`, for inline cells (the collection table's `meter` column).
+ */
+export declare function meterBar(level: number, cells: number, ascii: boolean): string;

package/dist/blocks/meter.js

@@ -0,0 +1,50 @@
+/**
+ * The `meter` block (UI-blocks spec §5.3): `label value` plus a bar
+ * filling the rest of the line — `█`/`░` on a Unicode terminal,
+ * `#`/`-` without one. A crossed threshold's tone paints the bar and
+ * the value (the LAST crossed threshold wins, matching the webui).
+ */
+import { visibleWidth } from "@earendil-works/pi-tui";
+import { formatValue } from "@sigrun/shared/blocks";
+import { bindRaw, bindText } from "./context.js";
+import { truncate } from "./width.js";
+import { toneFg } from "./tones.js";
+import { Lines } from "./layout.js";
+/** The highest threshold the value crosses, if any. */
+function crossedTone(block, value) {
+    let tone;
+    for (const threshold of block.thresholds ?? []) {
+        if (value >= threshold.at)
+            tone = threshold.tone;
+    }
+    return tone;
+}
+/** `meter`: one line, `label value bar` exactly `width` cells. */
+export function renderMeter(block, ctx) {
+    return new Lines((width) => {
+        const raw = bindRaw(block.value, ctx);
+        const value = typeof raw === "number" ? raw : 0;
+        const min = block.min ?? 0;
+        const max = block.max ?? 1;
+        const label = bindText(block.label, ctx);
+        const text = formatValue(value, block.format, ctx.locale);
+        const head = label === "" ? text : `${label} ${text}`;
+        const tone = crossedTone(block, value);
+        const paint = tone === undefined ? (s) => s : toneFg(ctx.theme, tone);
+        const barCells = Math.max(1, width - visibleWidth(head) - 1);
+        const t = max === min ? 0 : Math.max(0, Math.min(1, (value - min) / (max - min)));
+        const bar = meterBar(t, barCells, !ctx.unicode);
+        return [truncate(`${paint(head)} ${paint(bar)}`, width)];
+    });
+}
+/**
+ * The bare meter bar (no label): `filled`/`empty` cells of the 0–1
+ * `level`, for inline cells (the collection table's `meter` column).
+ */
+export function meterBar(level, cells, ascii) {
+    const fill = ascii ? "#" : "█";
+    const empty = ascii ? "-" : "░";
+    const t = Math.max(0, Math.min(1, level));
+    const filled = Math.floor(cells * t);
+    return fill.repeat(filled) + empty.repeat(cells - filled);
+}

package/dist/blocks/page.d.ts

@@ -0,0 +1,54 @@
+/**
+ * The `page` shell (UI-blocks U2 Task 5, spec §5.1/§12.3 — the TUI port
+ * of U1's `Page.tsx`): a header line (title, subtitle), sidebar, main
+ * and detail regions — the channel draws them, the extension never
+ * positions them.
+ *
+ * - `empty` replaces MAIN ONLY when main's first collection binds to a
+ *   missing path, `null` or `[]`; the sidebar and detail keep rendering.
+ * - At ≥ 100 columns the sidebar is a focusable pane beside main
+ *   (Tab cycles sidebar → main); below 100 it is a toggled overlay
+ *   (Tab toggles it; Esc closes it).
+ * - `ctrl+s` opens the header switcher (a `choice` field): Up/Down
+ *   pick, Enter dispatches a `navigate` action with `{<name>: id}`.
+ * - `.` opens the actions menu: Up/Down pick, Enter dispatches the
+ *   action, Esc closes. (Access `read` hides edit/answer actions.)
+ * - The detail region is a pushed view: Enter on main pushes it, Esc
+ *   pops back. At ≥ 100 columns it renders beside main once pushed.
+ * - Esc with nothing open resolves at THIS layer (Task 4's host note:
+ *   the app-level Esc handling for a surface with no pick-up and no
+ *   open menu is the page's "unfocus" — the host routes it; the page
+ *   reports `hasOverlay` so the host knows when Esc is already spoken
+ *   for).
+ */
+import type { Component } from "@earendil-works/pi-tui";
+import type { Block, CollectionBlock, JsonObject, PageBlock } from "@sigrun/shared/blocks";
+import { type BlockCtx } from "./context.js";
+import { type RenderOptions } from "./render.js";
+/** The sidebar-pane minimum (spec §5.1/brief: ≥ 100 columns). */
+export declare const SIDEBAR_PANE_MIN = 100;
+/** The sidebar's pane width at the side-by-side layout. */
+export declare const SIDEBAR_CELLS = 30;
+/** The first `collection` block in a slot list, depth-first (mirrors
+ *  U1's `firstCollection`). */
+export declare function firstCollection(blocks: readonly Block[]): CollectionBlock | undefined;
+/** Whether `empty` replaces main (spec §5.1): the first collection's
+ *  `items` binding resolves missing, null or an empty array. */
+export declare function isMainEmpty(block: PageBlock, data: JsonObject): boolean;
+export declare class PageComponent implements Component {
+    #private;
+    constructor(block: PageBlock, ctx: BlockCtx, options?: RenderOptions);
+    /** True while an overlay (menu, sidebar drawer, pushed detail) owns Esc. */
+    get hasOverlay(): boolean;
+    render(width: number): string[];
+    handleInput(data: string): void;
+    /** The host tells the page the current pane width's layout class
+     *  (render computes it too; this setter keeps Tab consistent when
+     *  input arrives between renders). */
+    setSideBySide(sideBySide: boolean): void;
+    invalidate(): void;
+    /** Test introspection: the pushed detail / overlay state. */
+    get detailPushed(): boolean;
+    get sidebarOpen(): boolean;
+    get menuKind(): "switcher" | "actions" | null;
+}