@sigrun/tui 0.4.1 → 0.5.0

package/dist/blocks/page.js

@@ -0,0 +1,360 @@
+/**
+ * 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 { resolvePointer } from "@sigrun/shared/blocks";
+import { bindText } from "./context.js";
+import { iconGlyph } from "./icons.js";
+import { renderBlock } from "./render.js";
+import { pad, truncate, wrapPlain } from "./width.js";
+/** The sidebar-pane minimum (spec §5.1/brief: ≥ 100 columns). */
+export const SIDEBAR_PANE_MIN = 100;
+/** The sidebar's pane width at the side-by-side layout. */
+export const SIDEBAR_CELLS = 30;
+/** The first `collection` block in a slot list, depth-first (mirrors
+ *  U1's `firstCollection`). */
+export function firstCollection(blocks) {
+    for (const block of blocks) {
+        if (block.type === "collection")
+            return block;
+        if (block.type === "stack") {
+            const found = firstCollection(block.children);
+            if (found !== undefined)
+                return found;
+        }
+        if (block.type === "section") {
+            const found = firstCollection(block.children.filter((child) => child.type === "collection" ||
+                child.type === "stack" ||
+                child.type === "columns" ||
+                child.type === "grid" ||
+                child.type === "section"));
+            if (found !== undefined)
+                return found;
+        }
+        if (block.type === "columns" || block.type === "grid") {
+            for (const child of block.children) {
+                const found = firstCollection([child.block]);
+                if (found !== undefined)
+                    return found;
+            }
+        }
+    }
+    return undefined;
+}
+/** Whether `empty` replaces main (spec §5.1): the first collection's
+ *  `items` binding resolves missing, null or an empty array. */
+export function isMainEmpty(block, data) {
+    if (block.empty === undefined)
+        return false;
+    const collection = firstCollection(block.main);
+    if (collection === undefined)
+        return false;
+    const itemsProp = collection.items;
+    // Literal rows (the ambient shape, U6 Task 3) resolve directly; the
+    // "$" check discriminates the binding (Array.isArray cannot narrow
+    // a readonly-array union).
+    if (typeof itemsProp !== "object" || !("$" in itemsProp)) {
+        return itemsProp.length === 0;
+    }
+    const items = resolvePointer(data, itemsProp.$);
+    return !Array.isArray(items) || items.length === 0;
+}
+export class PageComponent {
+    #block;
+    #ctx;
+    /** The open overlay: the switcher or the actions menu. */
+    #menu = null;
+    /** The pushed detail view (spec §12.3: detail → pushed page, Esc back). */
+    #detailPushed = false;
+    /** The sidebar overlay (compact) / focused pane (side-by-side). */
+    #sidebarOpen = false;
+    #region = "main";
+    /** The rendered region components (input forwards to the focused one). */
+    #main;
+    #sidebar;
+    #detail;
+    constructor(block, ctx, options = {}) {
+        this.#block = block;
+        this.#ctx = ctx;
+        this.#main = block.main.map((child) => renderBlock(child, ctx, options));
+        this.#sidebar = (block.sidebar ?? []).map((child) => renderBlock(child, ctx, options));
+        this.#detail = (block.detail ?? []).map((child) => renderBlock(child, ctx, options));
+    }
+    get #hasSidebar() {
+        return this.#sidebar.length > 0;
+    }
+    get #hasDetail() {
+        return this.#detail.length > 0;
+    }
+    /** True while an overlay (menu, sidebar drawer, pushed detail) owns Esc. */
+    get hasOverlay() {
+        return this.#menu !== null || this.#detailPushed || this.#sidebarOpen;
+    }
+    /** The header line: title (+ subtitle), switcher/actions hints. */
+    #headerLines(width) {
+        const title = bindText(this.#block.title, this.#ctx);
+        const subtitle = bindText(this.#block.subtitle, this.#ctx);
+        const hints = [];
+        if (this.#block.switcher !== undefined)
+            hints.push("ctrl+s switch");
+        if ((this.#block.actions ?? []).length > 0)
+            hints.push(". actions");
+        const hint = hints.length > 0 ? this.#ctx.theme.dim(`  (${hints.join(" · ")})`) : "";
+        const lines = [truncate(`${this.#ctx.theme.bold(title)}${hint}`, width)];
+        if (subtitle !== "")
+            lines.push(truncate(this.#ctx.theme.dim(subtitle), width));
+        return lines;
+    }
+    #emptyLines(width) {
+        const empty = this.#block.empty;
+        if (empty === undefined)
+            return [];
+        const icon = iconGlyph(empty.icon, !this.#ctx.unicode);
+        const lines = [`${icon} ${empty.title}`];
+        if (empty.hint !== undefined && empty.hint !== "") {
+            for (const line of wrapPlain(empty.hint, width))
+                lines.push(this.#ctx.theme.dim(line));
+        }
+        return lines.map((line) => truncate(line, width));
+    }
+    #menuLines(width) {
+        const menu = this.#menu;
+        if (menu === null)
+            return [];
+        if (menu.kind === "switcher") {
+            const field = this.#block.switcher;
+            if (field === undefined)
+                return [];
+            const options = this.#switcherOptions(field);
+            return [
+                truncate(this.#ctx.theme.bold("Switch"), width),
+                ...options.map((option, index) => {
+                    const cursor = index === menu.cursor ? "> " : "  ";
+                    return truncate(`${cursor}${bindText(option.label, this.#ctx) || option.id}`, width);
+                }),
+                truncate(this.#ctx.theme.dim("Enter selects · Esc closes"), width),
+            ];
+        }
+        const actions = this.#visibleActions();
+        return [
+            truncate(this.#ctx.theme.bold("Actions"), width),
+            ...actions.map((button, index) => {
+                const cursor = index === menu.cursor ? "> " : "  ";
+                const icon = button.icon === undefined ? "" : `${iconGlyph(button.icon, !this.#ctx.unicode)} `;
+                return truncate(`${cursor}${icon}${bindText(button.label, this.#ctx) || button.id}`, width);
+            }),
+            truncate(this.#ctx.theme.dim("Enter runs · Esc closes"), width),
+        ];
+    }
+    #switcherOptions(field) {
+        const raw = field.options;
+        if (Array.isArray(raw))
+            return raw;
+        if (typeof raw === "object" && raw !== null && typeof raw.$ === "string") {
+            const resolved = resolvePointer(this.#ctx.data, raw.$);
+            if (Array.isArray(resolved))
+                return resolved;
+        }
+        return [];
+    }
+    /** The header actions the principal may run (access read hides
+     *  edit/answer actions; navigate/open/copy stay — §6.5's read rule). */
+    #visibleActions() {
+        if (this.#ctx.access === "write")
+            return this.#block.actions ?? [];
+        return (this.#block.actions ?? []).filter((button) => button.action.type === "navigate" ||
+            button.action.type === "open" ||
+            button.action.type === "copy");
+    }
+    render(width) {
+        const lines = this.#headerLines(width);
+        if (this.#menu !== null) {
+            return [...lines, ...this.#menuLines(width)];
+        }
+        if (this.#detailPushed && this.#hasDetail) {
+            lines.push(truncate(this.#ctx.theme.dim("Esc back"), width));
+            for (const component of this.#detail) {
+                lines.push(...component.render(width));
+            }
+            return lines;
+        }
+        const empty = isMainEmpty(this.#block, this.#ctx.data);
+        const mainLines = empty
+            ? this.#emptyLines(width)
+            : this.#main.flatMap((component) => component.render(this.#mainWidth(width)));
+        const sideBySide = width >= SIDEBAR_PANE_MIN && this.#hasSidebar;
+        if (!sideBySide) {
+            // Compact/regular below the pane minimum: the sidebar is a
+            // toggled overlay (rendered above main while open).
+            if (this.#sidebarOpen && this.#hasSidebar) {
+                lines.push(truncate(this.#ctx.theme.dim("Esc closes the sidebar"), width));
+                for (const component of this.#sidebar) {
+                    lines.push(...component.render(width));
+                }
+                return lines;
+            }
+            return [...lines, ...mainLines];
+        }
+        // The side-by-side layout: sidebar pane, gutter, main.
+        const sidebarLines = this.#sidebar.flatMap((component) => component.render(SIDEBAR_CELLS));
+        const height = Math.max(sidebarLines.length, mainLines.length);
+        for (let row = 0; row < height; row++) {
+            const left = pad(sidebarLines[row] ?? "", SIDEBAR_CELLS);
+            const right = mainLines[row] ?? "";
+            lines.push(truncate(`${left} ${right}`, width));
+        }
+        return lines;
+    }
+    #mainWidth(width) {
+        return width >= SIDEBAR_PANE_MIN && this.#hasSidebar
+            ? Math.max(1, width - SIDEBAR_CELLS - 1)
+            : width;
+    }
+    handleInput(data) {
+        // An open menu owns the keys.
+        if (this.#menu !== null) {
+            if (data === "\x1b") {
+                this.#menu = null;
+                return;
+            }
+            if (this.#menu.kind === "switcher") {
+                const field = this.#block.switcher;
+                if (field === undefined)
+                    return;
+                const options = this.#switcherOptions(field);
+                if (data === "\x1b[A") {
+                    this.#menu.cursor = Math.max(0, this.#menu.cursor - 1);
+                    return;
+                }
+                if (data === "\x1b[B") {
+                    this.#menu.cursor = Math.min(options.length - 1, this.#menu.cursor + 1);
+                    return;
+                }
+                if (data === "\r") {
+                    const option = options[this.#menu.cursor];
+                    if (option !== undefined) {
+                        // The switcher navigates (spec §5.1): params carry the id.
+                        this.#ctx.dispatch({ type: "navigate", params: { [field.name]: option.id } }, { [field.name]: option.id });
+                    }
+                    this.#menu = null;
+                    return;
+                }
+                return;
+            }
+            const actions = this.#visibleActions();
+            if (data === "\x1b[A") {
+                this.#menu.cursor = Math.max(0, this.#menu.cursor - 1);
+                return;
+            }
+            if (data === "\x1b[B") {
+                this.#menu.cursor = Math.min(actions.length - 1, this.#menu.cursor + 1);
+                return;
+            }
+            if (data === "\r") {
+                const button = actions[this.#menu.cursor];
+                if (button !== undefined)
+                    this.#ctx.dispatch(button.action, {});
+                this.#menu = null;
+                return;
+            }
+            return;
+        }
+        // The pushed detail owns Esc (back).
+        if (this.#detailPushed) {
+            if (data === "\x1b") {
+                this.#detailPushed = false;
+                return;
+            }
+            for (const component of this.#detail)
+                component.handleInput?.(data);
+            return;
+        }
+        // The compact sidebar overlay owns Esc (close).
+        if (this.#sidebarOpen) {
+            if (data === "\x1b") {
+                this.#sidebarOpen = false;
+                return;
+            }
+            for (const component of this.#sidebar)
+                component.handleInput?.(data);
+            return;
+        }
+        if (data === "\x13") {
+            // ctrl+s opens the switcher.
+            if (this.#block.switcher !== undefined) {
+                this.#menu = { kind: "switcher", cursor: 0 };
+            }
+            return;
+        }
+        if (data === ".") {
+            if (this.#visibleActions().length > 0)
+                this.#menu = { kind: "actions", cursor: 0 };
+            return;
+        }
+        if (data === "\t") {
+            // Tab cycles the sidebar (a focused pane at ≥ 100 columns, a
+            // toggled overlay below).
+            if (this.#hasSidebar) {
+                if (this.#sideBySideKnown === true) {
+                    this.#region = this.#region === "sidebar" ? "main" : "sidebar";
+                }
+                else {
+                    this.#sidebarOpen = !this.#sidebarOpen;
+                }
+            }
+            return;
+        }
+        if (data === "\r" && this.#hasDetail && !this.#detailPushed) {
+            this.#detailPushed = true;
+            return;
+        }
+        // Forward to the focused region.
+        const target = this.#region === "sidebar" && this.#hasSidebar ? this.#sidebar : this.#main;
+        for (const component of target)
+            component.handleInput?.(data);
+    }
+    /** Whether the last render was the side-by-side layout (Tab's
+     *  pane-vs-overlay decision — set by the host when it knows; the
+     *  render path computes it from the width). */
+    #sideBySideKnown;
+    /** 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) {
+        this.#sideBySideKnown = sideBySide;
+    }
+    invalidate() {
+        for (const component of [...this.#main, ...this.#sidebar, ...this.#detail]) {
+            component.invalidate();
+        }
+    }
+    /** Test introspection: the pushed detail / overlay state. */
+    get detailPushed() {
+        return this.#detailPushed;
+    }
+    get sidebarOpen() {
+        return this.#sidebarOpen;
+    }
+    get menuKind() {
+        return this.#menu?.kind ?? null;
+    }
+}

package/dist/blocks/render.d.ts

@@ -0,0 +1,31 @@
+/**
+ * The renderer's front door (UI-blocks U2 Task 1): one pi-tui
+ * component per block, dispatched on `block.type`. Layout blocks come
+ * from `layout.ts`, the simple content blocks from `content.ts`; later
+ * tasks slot their blocks into the same dispatch.
+ *
+ * - `visibleAt` (spec §12.2) gates here so every block inherits it:
+ *   `atLeast:regular` renders nothing in a compact pane. An unknown
+ *   condition fails visible, matching §4.4's lean (a newer spec's
+ *   blocks stay on screen).
+ * - A type this client can't render yet (spec §4.4) shows the block's
+ *   `fallback` text plus "Not supported in this client" — never
+ *   dropped silently.
+ */
+import type { Component } from "@earendil-works/pi-tui";
+import type { Block } from "@sigrun/shared/blocks";
+import { type BlockCtx } from "./context.js";
+import type { ImageOptions } from "./image.js";
+export { widthClassOf } from "./width.js";
+export type { WidthClass } from "./width.js";
+export type { BlockCtx, ViewState } from "./context.js";
+export type { ImageOptions } from "./image.js";
+/** The fallback notice (spec §4.4's exact words). */
+export declare const NOT_SUPPORTED = "Not supported in this client";
+/** The seams `renderBlock` threads to the blocks that need them. */
+export type RenderOptions = ImageOptions & {
+    /** Whether the form sits in an interaction placement (§9.1 stepper). */
+    interaction?: boolean;
+};
+/** Render any block as a pi-tui component (the renderer's dispatch). */
+export declare function renderBlock(block: Block, ctx: BlockCtx, options?: RenderOptions): Component;

package/dist/blocks/render.js

@@ -0,0 +1,163 @@
+/**
+ * The renderer's front door (UI-blocks U2 Task 1): one pi-tui
+ * component per block, dispatched on `block.type`. Layout blocks come
+ * from `layout.ts`, the simple content blocks from `content.ts`; later
+ * tasks slot their blocks into the same dispatch.
+ *
+ * - `visibleAt` (spec §12.2) gates here so every block inherits it:
+ *   `atLeast:regular` renders nothing in a compact pane. An unknown
+ *   condition fails visible, matching §4.4's lean (a newer spec's
+ *   blocks stay on screen).
+ * - A type this client can't render yet (spec §4.4) shows the block's
+ *   `fallback` text plus "Not supported in this client" — never
+ *   dropped silently.
+ */
+import { hiddenAtCompact } from "./context.js";
+import { Lines, renderColumns, renderGrid, renderSection, renderStack } from "./layout.js";
+import { renderContent } from "./content.js";
+import { renderChart } from "./chart.js";
+import { renderMeter } from "./meter.js";
+import { LogComponent } from "./log.js";
+import { TreeComponent } from "./treeview.js";
+import { ImageComponent } from "./image.js";
+import { renderCollection } from "./collection/collection.js";
+import { FormComponent } from "./form/form.js";
+import { PageComponent } from "./page.js";
+import { wrapPlain } from "./width.js";
+// The renderer's public surface re-exports its seam types and the width
+// classes so callers have ONE import site (`render.js`).
+export { widthClassOf } from "./width.js";
+/** The fallback notice (spec §4.4's exact words). */
+export const NOT_SUPPORTED = "Not supported in this client";
+/** A block this client can't render: its fallback text plus the notice. */
+function unsupported(block, ctx) {
+    return new Lines((width) => {
+        const lines = [];
+        const fallback = typeof block.fallback === "string" ? block.fallback : "";
+        if (fallback !== "")
+            lines.push(...wrapPlain(fallback, width));
+        lines.push(ctx.theme.dim(NOT_SUPPORTED));
+        return lines;
+    });
+}
+/**
+ * `visibleAt` as a width-aware wrapper: the same component answers
+ * every pane width, so a resize re-evaluates the gate. Input handling
+ * (button picks, the confirm gate) forwards to the inner component.
+ */
+class WidthGated {
+    #block;
+    #inner;
+    constructor(block, inner) {
+        this.#block = block;
+        this.#inner = inner;
+    }
+    render(width) {
+        if (hiddenAtCompact(this.#block, width))
+            return [];
+        return this.#inner.render(width);
+    }
+    handleInput(data) {
+        // Input forwards to the inner component. Width cannot gate it here
+        // (a component learns widths only while rendering); the host only
+        // routes keys to components it shows, which is where hiding lands.
+        this.#inner.handleInput?.(data);
+    }
+    invalidate() {
+        this.#inner.invalidate();
+    }
+    /** Dispose forwards too (a form's pending live debounce must not
+     *  outlive its surface host). */
+    dispose() {
+        this.#inner.dispose?.();
+    }
+    /** Form introspection forwards (tests and hosts read the wrapped
+     *  form's values/focus — the wrapper is transparent). */
+    get values() {
+        return this.#inner instanceof FormComponent ? this.#inner.values : undefined;
+    }
+    /** The form's field read (the interaction prompter's digit
+     *  accelerator reads the working set before toggling). */
+    fieldValue(name) {
+        return this.#inner instanceof FormComponent
+            ? this.#inner.fieldValue(name)
+            : undefined;
+    }
+    get focusIndex() {
+        return this.#inner instanceof FormComponent ? this.#inner.focusIndex : undefined;
+    }
+    /** Focus-by-name forward (the settings view's search-resolve seam). */
+    focusName(name) {
+        return this.#inner instanceof FormComponent ? this.#inner.focusName(name) : false;
+    }
+    get step() {
+        return this.#inner instanceof FormComponent ? this.#inner.step : undefined;
+    }
+    get submittedOnce() {
+        return this.#inner instanceof FormComponent ? this.#inner.submittedOnce : undefined;
+    }
+    /** The interaction prompter's digit accelerator writes the pick into
+     *  the wrapped form (the wrapper is transparent). */
+    setFieldValue(name, value) {
+        if (this.#inner instanceof FormComponent) {
+            this.#inner.setFieldValue(name, value);
+        }
+    }
+    /** Page introspection forwards (the wrapper is transparent for the
+     *  page shell's overlay/detail state too). */
+    get hasOverlay() {
+        return this.#inner instanceof PageComponent ? this.#inner.hasOverlay : undefined;
+    }
+    get detailPushed() {
+        return this.#inner instanceof PageComponent ? this.#inner.detailPushed : undefined;
+    }
+    get sidebarOpen() {
+        return this.#inner instanceof PageComponent ? this.#inner.sidebarOpen : undefined;
+    }
+    get menuKind() {
+        return this.#inner instanceof PageComponent ? this.#inner.menuKind : undefined;
+    }
+    setSideBySide(sideBySide) {
+        if (this.#inner instanceof PageComponent)
+            this.#inner.setSideBySide(sideBySide);
+    }
+}
+/** The type dispatch; unknown types answer `undefined` from content. */
+function dispatch(block, ctx, options) {
+    switch (block.type) {
+        case "stack":
+            return renderStack(block, ctx);
+        case "columns":
+            return renderColumns(block, ctx);
+        case "grid":
+            return renderGrid(block, ctx);
+        case "section":
+            return renderSection(block, ctx);
+        case "chart":
+            return renderChart(block, ctx);
+        case "meter":
+            return renderMeter(block, ctx);
+        case "log":
+            return new LogComponent(block, ctx);
+        case "tree":
+            return new TreeComponent(block, ctx);
+        case "image":
+            return new ImageComponent(block, ctx, options);
+        case "collection": {
+            const component = renderCollection(block, ctx);
+            return component ?? unsupported(block, ctx);
+        }
+        case "form":
+            return new FormComponent(block, ctx, {
+                interaction: options.interaction === true,
+            });
+        case "page":
+            return new PageComponent(block, ctx, options);
+        default:
+            return renderContent(block, ctx) ?? unsupported(block, ctx);
+    }
+}
+/** Render any block as a pi-tui component (the renderer's dispatch). */
+export function renderBlock(block, ctx, options = {}) {
+    return new WidthGated(block, dispatch(block, ctx, options));
+}

package/dist/blocks/surface-view.d.ts

@@ -0,0 +1,41 @@
+/**
+ * SurfaceView (UI-blocks U2 Task 5, the port of U1's `SurfaceView.tsx`):
+ * the component host for a `SurfaceState` — loading, not-found, an
+ * error line with `r` to retry, ready. Ready builds the render context
+ * (the confirmed-plus-overlay data, the `/view/` branch, server field
+ * errors, dispatch and access) and renders the tree's root block.
+ *
+ * `handleInput` forwards to the rendered root component while ready;
+ * while error is showing, `r` retries the load (spec §12.3's fallback
+ * posture: an error never strands the surface).
+ */
+import type { Component } from "@earendil-works/pi-tui";
+import type { TuiTheme } from "../theme.js";
+import { type RenderOptions } from "./render.js";
+import type { SurfaceState } from "./surface.js";
+/** The state lines (U1's wording, terminal-cased). */
+export declare const SURFACE_LOADING = "loading\u2026";
+export declare const SURFACE_NOT_FOUND = "surface not found";
+export declare const SURFACE_ERROR = "something went wrong \u2014 r to retry";
+export declare class SurfaceView implements Component {
+    #private;
+    constructor(surface: SurfaceState, opts: {
+        theme: TuiTheme;
+        locale?: string;
+        unicode: boolean;
+        options?: RenderOptions;
+    });
+    render(width: number): string[];
+    /**
+     * Focus the field with this name in the rendered form (the settings
+     * view's search-resolve seam, U4 Task 4): forces the component to
+     * build (the render gate) and forwards to the form's focus-by-name.
+     * Returns false when the surface is not a form or has no such field.
+     */
+    focusField(name: string): boolean;
+    handleInput(data: string): void;
+    invalidate(): void;
+    /** The wrapped component (test introspection AND the interaction
+     *  prompter's pre-paint key routing: forms expose state). */
+    get inner(): Component | undefined;
+}