@sigrun/tui 0.4.1 → 0.5.0

package/dist/blocks/form/file.js

@@ -0,0 +1,121 @@
+/**
+ * The secret and file fields (UI-blocks U2 Task 5, spec §5.6).
+ *
+ * `secret` is write-only: it NEVER renders a value, only the bound
+ * status — `set (stored)` / `set (env)` / `not set` — and a masked
+ * editor (`•` per typed character; ASCII `*` with ctx.unicode false).
+ *
+ * `file` prompts for a path, checks `accept` (MIME patterns) and
+ * `maxBytes`, reads the file's bytes, dispatches `onUpload` (a
+ * `submit` action, turn false) with the file descriptor plus the base64
+ * bytes, and hands the bytes to the surface's upload seam
+ * (`uploadBytes`) when the host provides one (§7.2). A failed check
+ * shows its error under the field and dispatches nothing.
+ */
+import { readFileSync, statSync } from "node:fs";
+import { bindRaw } from "../context.js";
+import { truncate } from "../width.js";
+/** The secret status text (spec §5.6's exact strings). */
+export function secretStatusText(status) {
+    if (status === "stored")
+        return "set (stored)";
+    if (status === "env")
+        return "set (env)";
+    return "not set";
+}
+/** The status line of a secret field: the bound status (the field's
+ *  name resolved against the form's bind, as U1's SecretField does). */
+export function secretStatusLine(field, formBind, ctx) {
+    const pointer = `${formBind === "" ? "" : formBind}/${field.name}`.replace(/^\/+/, "/");
+    const status = bindRaw({ $: pointer }, ctx);
+    return secretStatusText(status);
+}
+/** The masked editor text: one dot per typed character. */
+export function maskText(textValue, unicode) {
+    return (unicode ? "•" : "*").repeat(textValue.length);
+}
+/** Whether a file matches the accept patterns (comma-separated:
+ *  `image/*`, `image/png`, `.png`) — U1's `acceptsMime` rule, extended
+ *  with an extension fallback when the MIME guess is empty. */
+export function acceptsMime(accept, file) {
+    if (accept === undefined || accept.trim() === "")
+        return true;
+    return accept.split(",").some((raw) => {
+        const pattern = raw.trim();
+        if (pattern === "")
+            return false;
+        if (pattern.startsWith("."))
+            return file.name.endsWith(pattern);
+        if (pattern.endsWith("/*")) {
+            return file.type !== "" && file.type.startsWith(pattern.slice(0, -1));
+        }
+        return file.type === pattern;
+    });
+}
+/** A small extension → MIME map (the TUI has no file picker; the type
+ *  is guessed from the name, empty when unknown). */
+const EXT_MIME = {
+    ".png": "image/png",
+    ".jpg": "image/jpeg",
+    ".jpeg": "image/jpeg",
+    ".gif": "image/gif",
+    ".webp": "image/webp",
+    ".svg": "image/svg+xml",
+    ".txt": "text/plain",
+    ".md": "text/markdown",
+    ".json": "application/json",
+    ".pdf": "application/pdf",
+};
+/** The MIME guess from a file name ("" when unknown). */
+export function mimeOf(name) {
+    const dot = name.lastIndexOf(".");
+    if (dot < 0)
+        return "";
+    return EXT_MIME[name.slice(dot).toLowerCase()] ?? "";
+}
+/**
+ * Check `accept`/`maxBytes`, read the file and build the descriptor +
+ * payload. A failure answers `{ok: false, error}` and nothing else
+ * happens (no dispatch).
+ */
+export function pickFile(field, path, read = (p) => new Uint8Array(readFileSync(p)), sizeOf = (p) => statSync(p).size) {
+    const name = path.split("/").pop() ?? path;
+    let size;
+    let bytes;
+    try {
+        size = sizeOf(path);
+        bytes = read(path);
+    }
+    catch {
+        return { ok: false, error: `${path}: cannot read the file` };
+    }
+    const type = mimeOf(name);
+    if (!acceptsMime(field.accept, { type, name })) {
+        return { ok: false, error: `${name}: not an accepted type` };
+    }
+    if (field.maxBytes !== undefined && size > field.maxBytes) {
+        return { ok: false, error: `${name} is larger than ${field.maxBytes} bytes` };
+    }
+    return {
+        ok: true,
+        descriptor: { name, size, type },
+        bytes,
+        payloadFile: {
+            name,
+            size,
+            type,
+            bytesBase64: Buffer.from(bytes).toString("base64"),
+        },
+    };
+}
+/** The per-field secret/file editor state (the path/masked buffer). */
+export class FileFieldState {
+    error;
+    uploaded = [];
+}
+/** The status line a file field shows after an upload. */
+export function fileStatusLine(state, width) {
+    if (state.uploaded.length === 0)
+        return undefined;
+    return truncate(`uploaded: ${state.uploaded.join(", ")}`, width);
+}

package/dist/blocks/form/form.d.ts

@@ -0,0 +1,66 @@
+/**
+ * The `form` block (UI-blocks U2 Task 5, spec §5.6/§6.2/§9.1 — the TUI
+ * port of U1's `Form.tsx`): modes (submit / live / inline), client
+ * validation before dispatch, the live-mode 300 ms debounce with the
+ * `/view/` view-only branch, and the interaction stepper — several
+ * sections each holding a `choice` in an interaction placement present
+ * one question at a time with a review step, submitting ONCE with every
+ * field's value.
+ *
+ * TUI editing model (the app owns keymaps; the form owns text editing):
+ * Up/Down move between fields (the stepper moves BETWEEN sections);
+ * the focused field edits inline — characters insert, Backspace
+ * deletes, Enter submits (text/number/date/secret), toggles (toggle)
+ * or activates an option (choice); Tab moves to the next field.
+ * `syntax: "code"` longtext opens the host's $EDITOR seam with `e`.
+ * Editing is per-mode: `submit` edits locally until Enter on the button
+ * row; `live` dispatches every change after 300 ms (a `/view/`-bound
+ * live form writes through ctx.setView and never dispatches); `inline`
+ * renders one row (field plus the submit label) and clears on success.
+ *
+ * The focused field survives a data update (Review Focus 4): values
+ * and focus live in the component, not the render; a re-render after a
+ * server data change keeps both.
+ */
+import type { Component } from "@earendil-works/pi-tui";
+import type { FormBlock, JsonObject, JsonValue, SectionBlock } from "@sigrun/shared/blocks";
+import { type BlockCtx } from "../context.js";
+/** The live-mode debounce (spec §5.6: "every change is applied after
+ *  300 ms"). */
+export declare const LIVE_DEBOUNCE_MS = 300;
+/** The stepper: does this form qualify (several sections each holding
+ *  a choice, interaction placement)? (§9.1) */
+export declare function stepperSections(block: FormBlock, interaction: boolean): readonly SectionBlock[] | null;
+/** The form component. */
+export declare class FormComponent implements Component {
+    #private;
+    constructor(block: FormBlock, ctx: BlockCtx, opts?: {
+        interaction?: boolean;
+    });
+    /** Render (the form re-renders against the current ctx data — the
+     *  host re-creates or re-renders on SurfaceState changes). */
+    render(width: number): string[];
+    /** Input handling (the host routes keys while the form has focus). */
+    handleInput(data: string): void;
+    invalidate(): void;
+    /** Cancel any pending live debounce (the host's dispose seam). */
+    dispose(): void;
+    /** Test/host introspection: the current values and focus. */
+    get values(): JsonObject;
+    get focusIndex(): number;
+    /** Move focus to the field with this name (the settings view's
+     *  search-resolve seam, U4 Task 4: a "naming" hit lands the
+     *  caret on the naming-model row). Returns false when no field
+     *  carries the name. */
+    focusName(name: string): boolean;
+    /** The flattened field names (the host's search-resolve check). */
+    get fieldNames(): readonly string[];
+    get step(): number;
+    get submittedOnce(): boolean;
+    /** Set one field's value from the host (the interaction prompter's
+     *  digit accelerator writes the pick; the form's own key handling
+     *  stays the editor). Read-only forms ignore the write. */
+    setFieldValue(name: string, value: JsonValue): void;
+    /** One field's current value (the host's review/dispatch reads). */
+    fieldValue(name: string): JsonValue | undefined;
+}