@ashley-shrok/viewmodel-shell 0.4.9 → 0.6.0

package/dist/tui.d.ts

@@ -1,151 +1,75 @@
-import type { ReactElement } from "react";
 import type { Adapter, ActionEvent, ViewNode } from "./index.js";
-/** OSC 52 clipboard write — the terminal-native analog of the clipboard API.
- *  Works over SSH (no local clipboard dependency). Exported for a direct,
- *  deterministic unit test of the byte format. */
-export declare function osc52(text: string): string;
-/** Hand a URL to a real browser — the terminal analog of a redirect. Zero-dep
- *  (node:child_process). Opener order: $BROWSER → platform default. Detached +
- *  unref so a launched browser can never hold or block the Node event loop
- *  (teardown discipline). Returns false only if spawn threw *synchronously*
- *  (no opener attempted); an async spawn failure (e.g. ENOENT — no xdg-open)
- *  invokes `onSpawnError`. Callers map BOTH false and onSpawnError to the loud
- *  interstitial, so a redirect is never silently lost. Exported so a unit test
- *  can drive it with a stubbed node:child_process. */
-export declare function openExternal(url: string, onSpawnError?: () => void): boolean;
-/** How the vms-tui CLI's default onRedirect classifies a server redirect.
- *  No new wire — pure URL/origin analysis against the current endpoint. A
- *  relative path resolves against the endpoint ⇒ same-origin by construction;
- *  an absolute URL is same-origin iff its `origin` matches (origin compare,
- *  never a string prefix — `http://evil/?x=http://good` must NOT pass). */
-export type RedirectKind = {
-    kind: "same-origin";
-    endpoint: string;
-} | {
-    kind: "different-origin";
-    url: string;
-} | {
-    kind: "invalid";
-    url: string;
-};
-export declare function classify(url: string, fromEndpoint: string): RedirectKind;
-/**
- * Phase 5b terminal adapter — single-line + multi-line editors + selects.
- *
- * Every node renders byte-identically to Phase 1/2 when UNFOCUSED and on the
- * pure `renderTree`/non-TTY path (NO_CTX → interactive:false → no editor). On
- * a TTY the shell's view is interactive: a self-managed focus ring
- * (Tab/Shift-Tab/arrows), Enter/Space dispatch, focus continuity; button /
- * checkbox (`{checked}`) / tabs (`{value}`) / link / copy-button (OSC 52) /
- * form-submit. The focused single-line `field` is an editable
- * `ink-text-input`; the focused `textarea`/`code` field is the contained
- * `MultilineEditor` (Enter→newline; submit via the ring's submit button;
- * `code` adds a dim language label, no literal-tab). The focused `select` is
- * an `ink-select-input` list; the focused `select-multiple` is the contained
- * `MultiSelectInput` (Space toggles; comma-joined wire value; submit via the
- * ring's submit button). Typed drafts survive poll/dispatch re-renders unless
- * the field disappears or the server changes its value — mirroring
- * BrowserAdapter; selects are additionally server-authoritative on ANY server
- * re-render (excluded from draft preservation); password is masked;
- * form-`checkbox` toggles on Space. The still-deferred tier (`file`/`modal`/
- * `table`) arrives in later phases and still renders a visible fail-loud
- * placeholder — never blank, never silent.
- *
- * LEAF MODULE: never imported by src/index.ts / src/browser.ts /
- * src/server.ts, so `ink`/`react` never enter the web or server dependency
- * graph (a unit test asserts this).
- */
+interface TuiOpts {
+    /** "fill" (default) takes the full terminal via alternate-screen buffer;
+     *  "content" renders intrinsic content size in the inline scrollback. */
+    viewport?: "fill" | "content";
+    /** Sidebar rail fraction (0.15–0.6; default 1/3). When `page.layout === "sidebar"`
+     *  (and the same on `section.layout`), the FIRST child occupies this fraction
+     *  of the available width; the remainder fills with the rest of the children. */
+    sidebarFraction?: number;
+}
 export declare class TuiAdapter implements Adapter {
-    private instance;
+    private renderer;
+    private root;
+    private pending;
+    private initPromise;
     private disposed;
-    /** "fill" (default) = occupy the terminal + alternate-screen on a real
-     *  interactive TTY; "content" = legacy intrinsic-content size, no
-     *  alt-screen (the opt-out escape hatch — pre-0.4.5 behavior). */
     private readonly viewport;
-    /** `sidebar` rail width as a fraction of the terminal (fill path only).
-     *  Default 1/3; clamped to a sane [0.15, 0.6] so a bad value can't break
-     *  the layout. Adapter-level styling knob (NOT wire — appearance, not
-     *  arrangement). */
     private readonly sidebarFraction;
-    /** Set once ESC[?1049h was written, so dispose() emits the paired
-     *  ESC[?1049l exactly once (idempotent restore — same discipline as the
-     *  cursor restore Ink does on unmount). */
-    private altEntered;
-    constructor(opts?: {
-        viewport?: "fill" | "content";
-        sidebarFraction?: number;
-    });
-    /** Injected by tui-cli.ts: lets a keyboard Ctrl-C (which, under Ink's raw
-     *  mode, is delivered as input 0x03 and never raises SIGINT) reach the
-     *  CLI's single idempotent shutdown. A TUI-internal seam between our two
-     *  leaf files — NOT part of the core Adapter interface. */
-    private requestExit;
-    /** session storage — in-memory, process lifetime (browser sessionStorage
-     *  analog for a single-process CLI). Write-only per the wire contract. */
-    private sessionStore;
-    /** When non-null, App renders the loud Interstitial instead of the vm. */
-    private interstitial;
-    /** Last rendered vm/onAction — so showInterstitial can rerender through the
-     *  SAME single Ink instance (never a 2nd inkRender). */
-    private lastVm;
-    private lastOnAction;
-    setRequestExit(fn: (code: number) => void): void;
+    private readonly sessionStore;
+    private focusedPaneIndex;
+    private lastPaneCount;
+    private readonly fieldValues;
+    private readonly fieldWireValues;
+    private copiedKey;
+    private copiedTimer;
+    constructor(opts?: TuiOpts);
+    private setFieldValue;
+    /** Resolve a field's display value at render time. The draft-preservation
+     *  contract (AGENTS.md) is "user edits survive re-renders UNLESS the server
+     *  explicitly sets a new value for that field." Three states:
+     *    1. First time we see this field name — initialize the wire baseline
+     *       WITHOUT clobbering any pre-existing edit value (matters when a test
+     *       primes fieldValues via setFieldValue before the first render).
+     *    2. Wire value unchanged since last render — preserve the edit value.
+     *    3. Wire value differs from the prior wire baseline — server intent
+     *       change → reset the edit value to match. */
+    private copy;
+    private resolveFieldValue;
     render(vm: ViewNode, onAction: (action: ActionEvent) => void): void;
-    /** The interactive element used by render() and by interaction unit tests. */
-    createApp(vm: ViewNode, onAction: (a: ActionEvent) => void, opts?: {
-        requestExit?: (code: number) => void;
-    }): ReactElement;
-    /** Render a full-screen loud notice through the SINGLE existing Ink instance
-     *  (never a 2nd inkRender, never a raw stdout write that would corrupt Ink's
-     *  diff / the ESC[?25h restore). No-op once disposed — closes the
-     *  redirect-during-teardown rerender-after-unmount race. Process stays
-     *  alive; the CLI owns exit (Ctrl-C via App's existing useInput → shutdown).
-     *  Mounts the instance if a notice somehow precedes the first render (that
-     *  is still the FIRST inkRender, not a second). */
-    showInterstitial(msg: string): void;
-    /** Standalone redirect fallback. Only reached when a consumer wires
-     *  TuiAdapter WITHOUT ShellOptions.onRedirect — core precedence means the
-     *  vms-tui CLI's onRedirect suppresses this (proven by adapter-seam C/F).
-     *  Origin-blind (the adapter has no shell/endpoint ref): hand off to a
-     *  browser, else the loud interstitial. Never silent, never throws into
-     *  core. No-op once disposed. */
+    private init;
+    private flushPending;
+    private navigateForLinks;
+    /** Test-only: read the current edit value for a named field (for asserting
+     *  draft preservation across server re-renders). */
+    _peekFieldValue(name: string): string | undefined;
+    /** Test-only: read the current "copied" key for asserting that activation
+     *  set the feedback state. Returns null when no button is currently flashing. */
+    _peekCopiedKey(): string | null;
+    private cycleFocus;
+    /** B5 — keyboard activation of the focused pane's primary actionable.
+     *
+     *  Mode mapping:
+     *    "enter" → dispatch the first button.action / link → navigate /
+     *              copy-button → copy(). No-op if the pane has inputs
+     *              (FieldView's <input onSubmit> handles Enter for forms).
+     *    "space" → toggle the first checkbox (dispatch action with
+     *              {checked: !node.checked}). No-op if the pane has inputs
+     *              (Space is a printable character in text fields).
+     *
+     *  Always reads pane state from the CURRENT vm (this.pending), so a key
+     *  pressed mid-render still acts on the structure the user can see.
+     */
+    private activatePane;
+    /** Teardown — restore terminal cleanly. Idempotent. */
+    dispose(): void;
     navigate(url: string): void;
-    /** Write-only client storage. `session` → in-memory (process lifetime).
-     *  `local` → a SYNCHRONOUS XDG state-file write — synchronous is mandatory:
-     *  the core applies side-effects before the redirect branch (adapter-seam
-     *  Case E), so the token must land before navigation. Fail-loud, never
-     *  swallow, never re-throw into core (push() has no try/catch): an I/O error
-     *  or an unparseable EXISTING store surfaces the loud interstitial + a
-     *  stderr line and does NOT clobber a possibly-unrelated user file. */
     storage(scope: "local" | "session", key: string, value: string): void;
-    /** Test-only: read back a session value. The wire contract has no storage
-     *  read; this exists solely so a unit test can prove the write landed
-     *  (same rationale as exporting osc52 for a deterministic test). */
+    saveFile(data: Blob, filename: string, _contentType: string): Promise<void>;
+    /** Test-only: read back a session value. The wire contract has no
+     *  storage read; this exists solely so unit tests can prove the write
+     *  landed (parity with the Ink adapter's _peekSession). */
     _peekSession(key: string): string | undefined;
-    /** Pure ViewNode → Ink element, UNFOCUSED (NO_CTX). Used by static unit
-     *  tests; byte-identical to Phase 1 output. */
-    renderTree(vm: ViewNode): ReactElement;
-    /** Spacing rhythm. compact collapses gaps/padding (mirrors .vms--compact). */
-    private spacing;
-    /**
-     * React key: the roadmap's identity heuristic — explicit id/name where
-     * present, else positional index. Render-only; never a wire field.
-     */
-    private keyOf;
-    /** Fail-loud placeholder — single source of the phase string. */
-    private unsupported;
-    /** Focused-node affordance. Unfocused → returns the element unchanged, so
-     *  the static path stays byte-identical to Phase 1. Focused → a leading
-     *  cyan caret (deterministic + information-honest; ▸ U+25B8 is distinct
-     *  from the list-item markers › / ·). */
-    private focusWrap;
-    /** Shipped list-item variant → marker + child tint (fail-soft: unknown ok). */
-    private listItemStyle;
-    /** page & section share the 4 layout presets. Information-honest, not pixel. */
-    private layoutContainer;
-    private renderNode;
-    /** Resolves when the Ink app unmounts; immediate if nothing was rendered. */
-    waitUntilExit(): Promise<void>;
-    /** Idempotent terminal restore — unmount restores cursor/raw mode. */
-    dispose(): void;
 }
+export declare function renderTree(vm: ViewNode): React.ReactNode;
+export {};