@sigrun/tui 0.4.1 → 0.5.0

package/dist/blocks/surface-view.js

@@ -0,0 +1,137 @@
+/**
+ * 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;
+    /** The ONE mutable render context (fix round 2): the cached root
+     *  component holds this object by reference, so a post-settle
+     *  `setAccess("read")` reaches the form's `#readOnly` — refreshing
+     *  `data`/`access` per render instead of rebuilding the component
+     *  keeps typed state. */
+    #ctx;
+    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, refreshed from `#surface.view` on every
+     *  access (data updates and access swaps flow through to the
+     *  cached component's `#readOnly`/binding reads). */
+    #context() {
+        const view = this.#surface.view;
+        if (this.#ctx === undefined) {
+            this.#ctx = {
+                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,
+                // The live read (fix wave C3): memoized block components
+                // re-resolve the confirmed data + rev off the state, never
+                // the construction-time snapshot.
+                ctxRefresh: () => {
+                    const current = this.#surface.view;
+                    return { data: current.data, rev: current.rev };
+                },
+            };
+            return this.#ctx;
+        }
+        const ctx = this.#ctx;
+        ctx.data = view.data;
+        ctx.access = view.access === "write" ? "write" : "read";
+        ctx.serverErrors = this.#surface.serverErrors;
+        return ctx;
+    }
+    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 [];
+        return this.#readyComponent(view.tree).render(width);
+    }
+    /** Build the ready-state root component on demand (a key can arrive
+     *  before the first render — the interaction prompter's answer keys
+     *  must not wait for a paint). */
+    #readyComponent(tree) {
+        if (this.#component === undefined) {
+            this.#component = renderBlock(tree.root, this.#context(), this.#options);
+        }
+        else {
+            // The component is cached: refresh the shared context so it
+            // renders against the CURRENT view (access, data, errors).
+            this.#context();
+        }
+        return this.#component;
+    }
+    /**
+     * 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) {
+        const view = this.#surface.view;
+        if (view.status !== "ready" || view.tree === undefined)
+            return false;
+        const focusable = this.#readyComponent(view.tree);
+        return focusable.focusName?.(name) === true;
+    }
+    handleInput(data) {
+        const view = this.#surface.view;
+        if (view.status === "error") {
+            if (data === "r")
+                void this.#surface.retry();
+            return;
+        }
+        if (view.status !== "ready" || view.tree === undefined)
+            return;
+        // Build on demand: a key can arrive before the first paint (the
+        // interaction prompter's answer keys route here directly).
+        this.#readyComponent(view.tree).handleInput?.(data);
+    }
+    invalidate() {
+        this.#component?.invalidate();
+    }
+    /** The wrapped component (test introspection AND the interaction
+     *  prompter's pre-paint key routing: forms expose state). */
+    get inner() {
+        const view = this.#surface.view;
+        if (view.status !== "ready" || view.tree === undefined) {
+            return this.#component;
+        }
+        return this.#readyComponent(view.tree);
+    }
+}

package/dist/blocks/surface.d.ts

@@ -0,0 +1,80 @@
+/**
+ * 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[];
+    /** Flip the live surface's access (a mid-edit settle swap renders
+     *  read-only: the transport's access was captured at load, so the
+     *  settle path flips the state directly — the view re-renders via
+     *  the emitted change). Only narrows: once read, never back. */
+    setAccess(access: "read" | "write"): void;
+    /** 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;
+}