@sigrun/tui 0.0.0-stage → 0.1.1

package/dist/blocks/render.js

@@ -0,0 +1,145 @@
+/**
+ * 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;
+    }
+    get focusIndex() {
+        return this.#inner instanceof FormComponent ? this.#inner.focusIndex : undefined;
+    }
+    get step() {
+        return this.#inner instanceof FormComponent ? this.#inner.step : undefined;
+    }
+    get submittedOnce() {
+        return this.#inner instanceof FormComponent ? this.#inner.submittedOnce : undefined;
+    }
+    /** 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,33 @@
+/**
+ * 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[];
+    handleInput(data: string): void;
+    invalidate(): void;
+    /** The wrapped component (test introspection: forms expose state). */
+    get inner(): Component | undefined;
+}

package/dist/blocks/surface-view.js

@@ -0,0 +1,86 @@
+/**
+ * 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 { renderBlock } from "./render.js";
+import { truncate } from "./width.js";
+/** The state lines (U1's wording, terminal-cased). */
+export const SURFACE_LOADING = "loading…";
+export const SURFACE_NOT_FOUND = "surface not found";
+export const SURFACE_ERROR = "something went wrong — r to retry";
+export class SurfaceView {
+    #surface;
+    #theme;
+    #locale;
+    #unicode;
+    #options;
+    #component;
+    constructor(surface, opts) {
+        this.#surface = surface;
+        this.#theme = opts.theme;
+        this.#locale = opts.locale ?? "en";
+        this.#unicode = opts.unicode;
+        this.#options = opts.options ?? {};
+    }
+    /** The render context (rebuilt per view change — data updates flow
+     *  through SurfaceState's change events; the host re-renders). */
+    #ctx() {
+        const view = this.#surface.view;
+        return {
+            data: view.data,
+            theme: this.#theme,
+            locale: this.#locale,
+            access: view.access === "write" ? "write" : "read",
+            unicode: this.#unicode,
+            dispatch: (action, payload) => this.#surface.dispatch(action, payload),
+            view: { values: this.#surface.viewValues },
+            setView: (path, value) => this.#surface.setView(path, value),
+            serverErrors: this.#surface.serverErrors,
+        };
+    }
+    render(width) {
+        const view = this.#surface.view;
+        if (view.status === "loading") {
+            return [truncate(this.#theme.dim(SURFACE_LOADING), width)];
+        }
+        if (view.status === "notFound") {
+            return [truncate(this.#theme.dim(SURFACE_NOT_FOUND), width)];
+        }
+        if (view.status === "error") {
+            return [truncate(this.#theme.fg("bad")(SURFACE_ERROR), width)];
+        }
+        if (view.tree === undefined)
+            return [];
+        if (this.#component === undefined) {
+            this.#component = renderBlock(view.tree.root, this.#ctx(), this.#options);
+        }
+        return this.#component.render(width);
+    }
+    handleInput(data) {
+        const view = this.#surface.view;
+        if (view.status === "error") {
+            if (data === "r")
+                void this.#surface.retry();
+            return;
+        }
+        if (view.status !== "ready")
+            return;
+        // The root component was built against the CURRENT ctx; rebuild
+        // statelessly so input handlers close over the live dispatch.
+        this.#component?.handleInput?.(data);
+    }
+    invalidate() {
+        this.#component?.invalidate();
+    }
+    /** The wrapped component (test introspection: forms expose state). */
+    get inner() {
+        return this.#component;
+    }
+}

package/dist/blocks/surface.d.ts

@@ -0,0 +1,75 @@
+/**
+ * SurfaceState (UI-blocks U2 Task 4, spec §6.3): the confirmed-data plus
+ * optimistic-overlay model every TUI surface renders through — the TUI
+ * port of U1's `useSurface.ts`, with EXACTLY the same overlay rules:
+ *
+ * - **Confirmed data** changes ONLY from server data or ops (load,
+ *   fetch, accepted actions carrying ops).
+ * - **The overlay** is a list of pending moves `{actionId, payload,
+ *   target, untilRev?}`, keyed by `actionId`; the rendered `view` is
+ *   confirmed data with the overlay applied on top.
+ * - `{ok: true, rev, ops}` → apply the ops to confirmed, drop the entry.
+ * - `{ok: true, rev}` (no ops) → keep the entry with `untilRev = rev`
+ *   until a fetch at ≥ that rev arrives, then drop it — the item stays
+ *   where the user dropped it with no snap-back flicker.
+ * - `{ok: false}` or the 10 s timeout → drop the entry and surface a
+ *   NOTICE. U1 toasts; the TUI's notice is a line the app flashes in
+ *   the status bar — `SurfaceState` collects `notices` and the host
+ *   drains them through `consumeNotices` (the status-bar wiring is the
+ *   app's seam, Task 6's surface host).
+ * - A `rev` gap (ops land behind the announced rev) or a `DataOpError`
+ *   applying ops → a full refetch.
+ * - `access: "none"` → the not-found state (§6.5); a `treeRev` change
+ *   → a full reload.
+ *
+ * The overlay locates a move in the data by scanning the loaded tree
+ * for the collection whose `onMove` handler name matches the action —
+ * identical to U1 (a move against an unknown handler still goes to the
+ * transport, unoverlaid).
+ */
+import type { Action, JsonObject, JsonValue, SurfaceTransport, Tree } from "@sigrun/shared/blocks";
+/** An action has 10 s to answer before it counts as a reject (§6.3). */
+export declare const ACT_TIMEOUT_MS = 10000;
+/** The notice cap: pending notices drop oldest-first past 50 (a flood
+ *  of failures must not grow the list without bound; the host drains
+ *  them through `consumeNotices`). */
+export declare const NOTICE_CAP = 50;
+/** The snapshot a render reads (the brief's `ViewState`). */
+export interface SurfaceView {
+    readonly status: "loading" | "ready" | "notFound" | "error";
+    readonly tree?: Tree;
+    /** Confirmed data with the overlay applied — what blocks render. */
+    readonly data: JsonObject;
+    readonly rev: number;
+    readonly treeRev: number;
+    readonly access: "none" | "read" | "write";
+    /** Pending notice lines (drain via {@link SurfaceState.consumeNotices}). */
+    readonly notices: readonly string[];
+}
+/** The surface state container (class shape — the TUI has no hook layer). */
+export declare class SurfaceState {
+    #private;
+    constructor(transport: SurfaceTransport);
+    /** The current snapshot: confirmed data with the overlay applied. */
+    get view(): SurfaceView;
+    /** Subscribe to state changes (returns the unsubscribe). */
+    onChange(cb: () => void): () => void;
+    /** Drain the pending notices (the host flashes them in the status bar). */
+    consumeNotices(): readonly string[];
+    /** The channel-owned `/view/` branch (spec §6.2) — a BlockCtx's
+     *  `view.values` reads this object. */
+    get viewValues(): JsonObject;
+    /** The server field errors from the latest rejected action. */
+    get serverErrors(): Readonly<Record<string, string>>;
+    /** Write a pointer under the `/view/` branch (the form's live
+     *  `/view/`-bound flush lands here; the write never dispatches). */
+    setView(path: string, value: JsonValue): void;
+    /** Reload after an error (SurfaceView's `r` key). */
+    retry(): Promise<void>;
+    /** Load the tree and initial data; subscribe to change events. */
+    load(): Promise<void>;
+    /** Stop listening and cancel every pending action timer. */
+    dispose(): void;
+    /** Dispatch an action to the surface; a move joins the overlay first. */
+    dispatch(action: Action, payload: JsonValue): void;
+}