@kahitsan/ksui 0.19.0 → 0.20.0

package/src/components/composite/FlowRunner.test.tsx

@@ -0,0 +1,127 @@
+// U7 — FlowRunner component tests: renders each node kind, calls advance with the
+// node's input, handles a terminal node + an error.
+import { describe, expect, it, vi } from "vitest";
+import { render, fireEvent, waitFor } from "@solidjs/testing-library";
+import FlowRunner from "./FlowRunner";
+import type { FlowNode } from "../../utils/flow";
+
+const terminal: FlowNode = { kind: "terminal", id: "end", message: "Done" };
+
+describe("FlowRunner", () => {
+  it("renders a form and calls advance with the form input on submit", async () => {
+    const advance = vi.fn(async () => terminal);
+    const onComplete = vi.fn();
+    const { getByTestId } = render(() => (
+      <FlowRunner
+        testId="fr"
+        initialNode={{
+          kind: "form",
+          id: "n1",
+          title: "Pay",
+          fields: [{ key: "amount", label: "Amount", type: "number", required: true }],
+        }}
+        advance={advance}
+        state={{ token: "abc" }}
+        onComplete={onComplete}
+      />
+    ));
+    fireEvent.input(getByTestId("fr-field-amount"), { target: { value: "50" } });
+    fireEvent.click(getByTestId("fr-submit"));
+    await waitFor(() => expect(advance).toHaveBeenCalledWith({ token: "abc" }, { amount: "50" }));
+    await waitFor(() => expect(getByTestId("fr-terminal")).toBeTruthy());
+    expect(onComplete).toHaveBeenCalled();
+  });
+
+  it("blocks submit while a required field is empty", () => {
+    const advance = vi.fn(async () => terminal);
+    const { getByTestId } = render(() => (
+      <FlowRunner
+        testId="fr"
+        initialNode={{
+          kind: "form",
+          id: "n1",
+          fields: [{ key: "amount", label: "Amount", required: true }],
+        }}
+        advance={advance}
+      />
+    ));
+    fireEvent.click(getByTestId("fr-submit"));
+    expect(advance).not.toHaveBeenCalled();
+  });
+
+  it("renders a choice and submits the picked value", async () => {
+    const advance = vi.fn(async () => terminal);
+    const { getByTestId } = render(() => (
+      <FlowRunner
+        testId="fr"
+        initialNode={{
+          kind: "choice",
+          id: "c1",
+          options: [{ value: "yes", label: "Yes" }, { value: "no", label: "No" }],
+        }}
+        advance={advance}
+      />
+    ));
+    fireEvent.click(getByTestId("fr-choice-yes"));
+    await waitFor(() => expect(advance).toHaveBeenCalledWith(undefined, { value: "yes" }));
+  });
+
+  it("renders a display node and continues with null input", async () => {
+    const advance = vi.fn(async () => terminal);
+    const { getByTestId } = render(() => (
+      <FlowRunner
+        testId="fr"
+        initialNode={{ kind: "display", id: "d1", body: "Review this" }}
+        advance={advance}
+      />
+    ));
+    expect(getByTestId("fr-display").textContent).toContain("Review this");
+    fireEvent.click(getByTestId("fr-continue"));
+    await waitFor(() => expect(advance).toHaveBeenCalledWith(undefined, null));
+  });
+
+  it("renders a message node and acks", async () => {
+    const advance = vi.fn(async () => terminal);
+    const { getByTestId } = render(() => (
+      <FlowRunner
+        testId="fr"
+        initialNode={{ kind: "message", id: "m1", text: "Heads up", tone: "info" }}
+        advance={advance}
+      />
+    ));
+    expect(getByTestId("fr-message").textContent).toContain("Heads up");
+    fireEvent.click(getByTestId("fr-ack"));
+    await waitFor(() => expect(advance).toHaveBeenCalled());
+  });
+
+  it("surfaces an error when advance rejects, without inventing the next node", async () => {
+    const advance = vi.fn(async () => {
+      throw new Error("server said no");
+    });
+    const { getByTestId, queryByTestId } = render(() => (
+      <FlowRunner
+        testId="fr"
+        initialNode={{ kind: "choice", id: "c1", options: [{ value: "go", label: "Go" }] }}
+        advance={advance}
+      />
+    ));
+    fireEvent.click(getByTestId("fr-choice-go"));
+    await waitFor(() => expect(getByTestId("fr-error").textContent).toContain("server said no"));
+    // still on the choice node — the client never invents a next node
+    expect(queryByTestId("fr-choice")).toBeTruthy();
+  });
+
+  it("takes the cancel path on a cancelable form", () => {
+    const onCancel = vi.fn();
+    const { getByTestId } = render(() => (
+      <FlowRunner
+        testId="fr"
+        initialNode={{ kind: "form", id: "n1", cancelable: true, fields: [] }}
+        advance={vi.fn(async () => terminal)}
+        onCancel={onCancel}
+      />
+    ));
+    fireEvent.click(getByTestId("fr-cancel"));
+    expect(onCancel).toHaveBeenCalled();
+  });
+});

package/src/components/composite/FlowRunner.tsx

@@ -0,0 +1,348 @@
+// U7 — FlowRunner (Vision §9): a client renderer for a SERVER-DRIVEN node graph.
+// It renders the current UI-effect node (form / display / choice / message /
+// terminal) and POSTs each step to the host-injected `advance(state, input)`
+// resolver — which owns ALL authority, data and branching. The client never
+// decides the graph: it shows the node, collects input, calls `advance`, and
+// renders whatever node comes back, stopping at a terminal node.
+//
+// Composite because it composes the node model (utils/flow) with loading/terminal/
+// error UI. Self-contained CSS (ksui-fr-* unscoped classes + CSS custom props);
+// no Tailwind, no host-brand classes (standalone-library rule).
+
+import type { Component, JSX } from "solid-js";
+import { For, Match, Show, Switch, createSignal } from "solid-js";
+import {
+  collectsInput,
+  formNodeInput,
+  isTerminal,
+  missingRequired,
+  type FlowAdvance,
+  type FlowChoiceNode,
+  type FlowDisplayNode,
+  type FlowFormNode,
+  type FlowInput,
+  type FlowMessageNode,
+  type FlowNode,
+  type FlowState,
+} from "../../utils/flow";
+
+const STYLE_ID = "ksui-flow-runner-style";
+
+function ensureStyle(): void {
+  if (typeof document === "undefined") return;
+  if (document.getElementById(STYLE_ID)) return;
+  const style = document.createElement("style");
+  style.id = STYLE_ID;
+  style.textContent = `
+.ksui-fr{display:flex;flex-direction:column;gap:0.875rem;color:var(--ksui-fr-fg,inherit);}
+.ksui-fr-title{font-size:0.95rem;font-weight:600;margin:0;}
+.ksui-fr-prompt,.ksui-fr-body{font-size:0.85rem;opacity:0.85;margin:0;}
+.ksui-fr-field{display:flex;flex-direction:column;gap:0.25rem;}
+.ksui-fr-label{font-size:0.78rem;font-weight:500;}
+.ksui-fr-input{padding:0.5rem 0.625rem;border-radius:0.5rem;border:1px solid var(--ksui-fr-border,rgba(255,255,255,0.15));background:var(--ksui-fr-input-bg,rgba(255,255,255,0.04));color:inherit;font-size:0.85rem;}
+.ksui-fr-actions{display:flex;gap:0.5rem;flex-wrap:wrap;}
+.ksui-fr-btn{padding:0.5rem 0.875rem;border-radius:0.5rem;border:1px solid var(--ksui-fr-border,rgba(255,255,255,0.15));background:var(--ksui-fr-btn-bg,rgba(255,255,255,0.06));color:inherit;font-size:0.82rem;cursor:pointer;}
+.ksui-fr-btn:disabled{opacity:0.5;cursor:not-allowed;}
+.ksui-fr-btn.primary{background:var(--ksui-fr-primary,#c9a961);color:var(--ksui-fr-primary-fg,#18181b);border-color:transparent;}
+.ksui-fr-btn.danger{background:var(--ksui-fr-danger,#ef4444);color:#fff;border-color:transparent;}
+.ksui-fr-msg{padding:0.625rem 0.75rem;border-radius:0.5rem;font-size:0.85rem;}
+.ksui-fr-msg.info{background:rgba(59,130,246,0.1);}
+.ksui-fr-msg.success{background:rgba(34,197,94,0.12);}
+.ksui-fr-msg.error{background:rgba(239,68,68,0.12);}
+.ksui-fr-error{padding:0.625rem 0.75rem;border-radius:0.5rem;font-size:0.82rem;background:rgba(239,68,68,0.12);border:1px solid rgba(239,68,68,0.3);}
+.ksui-fr-loading{font-size:0.82rem;opacity:0.7;}
+`;
+  document.head.appendChild(style);
+}
+
+export interface FlowRunnerProps {
+  /** The first node the server handed the client (the flow entry). */
+  initialNode: FlowNode;
+  /**
+   * Host-injected resolver — owns authority, data and branching (§9). Given the
+   * opaque state and the step input it returns the next node. ksui never decides.
+   */
+  advance: FlowAdvance;
+  /**
+   * Opaque flow state threaded into each `advance` call. The client never reads
+   * into it; the server correlates the step from it.
+   */
+  state?: FlowState;
+  /** Fired when a terminal node is reached (host closes the flow / refreshes). */
+  onComplete?: (node: FlowNode) => void;
+  /** Fired when the user cancels a cancelable form (host takes the onCancel edge). */
+  onCancel?: () => void;
+  /** Optional test id prefix. */
+  testId?: string;
+}
+
+export const FlowRunner: Component<FlowRunnerProps> = (props) => {
+  ensureStyle();
+  const [node, setNode] = createSignal<FlowNode>(props.initialNode);
+  const [busy, setBusy] = createSignal(false);
+  const [error, setError] = createSignal<string | null>(null);
+  // Form field values for the current form node (reset whenever the node changes).
+  const [values, setValues] = createSignal<Record<string, unknown>>({});
+
+  const tid = (s: string) => (props.testId ? `${props.testId}-${s}` : undefined);
+
+  // Submit `input` to the server resolver and swap in the node it returns. A
+  // rejected `advance` surfaces as an error state — the client never invents the
+  // next node, so a failure halts on the current step (re-submittable).
+  const submit = async (input: FlowInput) => {
+    setError(null);
+    setBusy(true);
+    try {
+      const next = await props.advance(props.state, input);
+      setNode(next);
+      setValues({});
+      if (isTerminal(next)) props.onComplete?.(next);
+    } catch (e) {
+      setError(e instanceof Error ? e.message : "Something went wrong");
+    } finally {
+      setBusy(false);
+    }
+  };
+
+  const setField = (key: string, v: unknown) =>
+    setValues((prev) => ({ ...prev, [key]: v }));
+
+  const submitForm = (n: FlowFormNode) => {
+    if (missingRequired(n, values()).length > 0) return; // UX gate; server re-validates
+    void submit(formNodeInput(n, values()));
+  };
+
+  return (
+    <div class="ksui-fr" data-testid={tid("root")}>
+      <Show when={error()}>
+        <div class="ksui-fr-error" role="alert" data-testid={tid("error")}>
+          {error()}
+        </div>
+      </Show>
+
+      <Switch>
+        <Match when={node().kind === "form"}>
+          {renderForm(node() as FlowFormNode, values(), setField, () => submitForm(node() as FlowFormNode), () => props.onCancel?.(), busy(), tid)}
+        </Match>
+        <Match when={node().kind === "display"}>
+          {renderDisplay(node() as FlowDisplayNode, () => void submit(null), busy(), tid)}
+        </Match>
+        <Match when={node().kind === "choice"}>
+          {renderChoice(node() as FlowChoiceNode, (value) => void submit({ value }), busy(), tid)}
+        </Match>
+        <Match when={node().kind === "message"}>
+          {renderMessage(node() as FlowMessageNode, () => void submit(null), busy(), tid)}
+        </Match>
+        <Match when={node().kind === "terminal"}>
+          {renderTerminal(node(), tid)}
+        </Match>
+      </Switch>
+
+      <Show when={busy()}>
+        <span class="ksui-fr-loading" data-testid={tid("loading")}>Working…</span>
+      </Show>
+    </div>
+  );
+};
+
+// ---- node renderers (plain functions returning JSX; no per-node reactivity needed) ----
+
+function renderForm(
+  n: FlowFormNode,
+  values: Record<string, unknown>,
+  setField: (k: string, v: unknown) => void,
+  onSubmit: () => void,
+  onCancel: () => void,
+  busy: boolean,
+  tid: (s: string) => string | undefined,
+): JSX.Element {
+  const blocked = missingRequired(n, values).length > 0;
+  return (
+    <div class="ksui-fr" data-testid={tid("form")}>
+      <Show when={n.title}>
+        <h3 class="ksui-fr-title">{n.title}</h3>
+      </Show>
+      <For each={n.fields}>
+        {(f) => (
+          <div class="ksui-fr-field">
+            <label class="ksui-fr-label" for={`ksui-fr-${f.key}`}>
+              {f.label}
+              {f.required ? " *" : ""}
+            </label>
+            <Switch
+              fallback={
+                <input
+                  id={`ksui-fr-${f.key}`}
+                  class="ksui-fr-input"
+                  type={f.type === "number" ? "number" : "text"}
+                  placeholder={f.placeholder}
+                  data-testid={tid(`field-${f.key}`)}
+                  onInput={(e) => setField(f.key, e.currentTarget.value)}
+                />
+              }
+            >
+              <Match when={f.type === "textarea"}>
+                <textarea
+                  id={`ksui-fr-${f.key}`}
+                  class="ksui-fr-input"
+                  placeholder={f.placeholder}
+                  data-testid={tid(`field-${f.key}`)}
+                  onInput={(e) => setField(f.key, e.currentTarget.value)}
+                />
+              </Match>
+              <Match when={f.type === "select"}>
+                <select
+                  id={`ksui-fr-${f.key}`}
+                  class="ksui-fr-input"
+                  data-testid={tid(`field-${f.key}`)}
+                  onChange={(e) => setField(f.key, e.currentTarget.value)}
+                >
+                  <option value="" />
+                  <For each={f.options ?? []}>
+                    {(o) => <option value={o.value}>{o.label}</option>}
+                  </For>
+                </select>
+              </Match>
+              <Match when={f.type === "toggle"}>
+                <input
+                  id={`ksui-fr-${f.key}`}
+                  type="checkbox"
+                  data-testid={tid(`field-${f.key}`)}
+                  onChange={(e) => setField(f.key, e.currentTarget.checked)}
+                />
+              </Match>
+            </Switch>
+          </div>
+        )}
+      </For>
+      <div class="ksui-fr-actions">
+        <button
+          type="button"
+          class="ksui-fr-btn primary"
+          disabled={busy || blocked}
+          data-testid={tid("submit")}
+          onClick={onSubmit}
+        >
+          {n.submitLabel ?? "Submit"}
+        </button>
+        <Show when={n.cancelable}>
+          <button
+            type="button"
+            class="ksui-fr-btn"
+            disabled={busy}
+            data-testid={tid("cancel")}
+            onClick={onCancel}
+          >
+            Cancel
+          </button>
+        </Show>
+      </div>
+    </div>
+  );
+}
+
+function renderDisplay(
+  n: FlowDisplayNode,
+  onContinue: () => void,
+  busy: boolean,
+  tid: (s: string) => string | undefined,
+): JSX.Element {
+  return (
+    <div class="ksui-fr" data-testid={tid("display")}>
+      <Show when={n.title}>
+        <h3 class="ksui-fr-title">{n.title}</h3>
+      </Show>
+      {/* Server-provided, already-sanitized read-only text. Rendered as text, not
+          innerHTML, so the client never trusts markup it didn't sanitize. */}
+      <p class="ksui-fr-body">{n.body}</p>
+      <div class="ksui-fr-actions">
+        <button
+          type="button"
+          class="ksui-fr-btn primary"
+          disabled={busy}
+          data-testid={tid("continue")}
+          onClick={onContinue}
+        >
+          {n.continueLabel ?? "Continue"}
+        </button>
+      </div>
+    </div>
+  );
+}
+
+function renderChoice(
+  n: FlowChoiceNode,
+  onPick: (value: string) => void,
+  busy: boolean,
+  tid: (s: string) => string | undefined,
+): JSX.Element {
+  return (
+    <div class="ksui-fr" data-testid={tid("choice")}>
+      <Show when={n.title}>
+        <h3 class="ksui-fr-title">{n.title}</h3>
+      </Show>
+      <Show when={n.prompt}>
+        <p class="ksui-fr-prompt">{n.prompt}</p>
+      </Show>
+      <div class="ksui-fr-actions">
+        <For each={n.options}>
+          {(o) => (
+            <button
+              type="button"
+              class={`ksui-fr-btn ${o.intent ?? ""}`}
+              disabled={busy}
+              data-testid={tid(`choice-${o.value}`)}
+              onClick={() => onPick(o.value)}
+            >
+              {o.label}
+            </button>
+          )}
+        </For>
+      </div>
+    </div>
+  );
+}
+
+function renderMessage(
+  n: FlowMessageNode,
+  onAck: () => void,
+  busy: boolean,
+  tid: (s: string) => string | undefined,
+): JSX.Element {
+  return (
+    <div class="ksui-fr" data-testid={tid("message")}>
+      <div class={`ksui-fr-msg ${n.tone ?? "info"}`} role="status">
+        {n.text}
+      </div>
+      <div class="ksui-fr-actions">
+        <button
+          type="button"
+          class="ksui-fr-btn"
+          disabled={busy}
+          data-testid={tid("ack")}
+          onClick={onAck}
+        >
+          {n.ackLabel ?? "OK"}
+        </button>
+      </div>
+    </div>
+  );
+}
+
+function renderTerminal(n: FlowNode, tid: (s: string) => string | undefined): JSX.Element {
+  if (!isTerminal(n)) return <></>;
+  return (
+    <div class="ksui-fr" data-testid={tid("terminal")}>
+      <Show when={n.title}>
+        <h3 class="ksui-fr-title">{n.title}</h3>
+      </Show>
+      <Show when={n.message}>
+        <div class={`ksui-fr-msg ${n.tone ?? "success"}`} role="status">
+          {n.message}
+        </div>
+      </Show>
+    </div>
+  );
+}
+
+export default FlowRunner;

package/src/index.ts

@@ -160,6 +160,18 @@ export type {
 } from "./components/composite/resource/ResourcePage";
 export * from "./components/composite/resource/spec";
 
+// U6 — declarative file/media field for the spec-driven form runtime. Value is an
+// opaque asset handle; host injects onUpload + presignUrl (storage-agnostic).
+export { default as FileField, type FileFieldProps, type AssetHandle, type FileFieldStatus } from "./components/composite/FileField";
+
+// U7 — client renderer for a server-driven flow node graph. Host injects `advance`;
+// the client only renders UI-effect nodes and POSTs each step (authority is server-side).
+export { default as FlowRunner, type FlowRunnerProps } from "./components/composite/FlowRunner";
+
+// U8 — schema-bound custom renderer: looks up an id in the in-process registry and
+// renders it with validated props, falling back safely on miss/mismatch.
+export { default as CustomRenderer, type CustomRendererProps } from "./components/composite/CustomRenderer";
+
 // ---------------------------------------------------------------------------
 // Utils (not components)
 // ---------------------------------------------------------------------------
@@ -199,6 +211,46 @@ export { highlightMatch, HighlightedText, matchesQuery, matchesAny } from "./uti
 export { confirm, type ConfirmOptions } from "./utils/confirm";
 export { useFocusTrap, autoFocusOnMount, lockPullToRefresh, unlockPullToRefresh } from "./utils/dom";
 
+// U7 — flow node model (pure): the discriminated union of client-renderable
+// UI-effect nodes + the host-injected `advance` resolver type + pure step helpers.
+export {
+  isTerminal,
+  collectsInput,
+  formNodeInput,
+  missingRequired,
+} from "./utils/flow";
+export type {
+  FlowNode,
+  FlowFormNode,
+  FlowDisplayNode,
+  FlowChoiceNode,
+  FlowMessageNode,
+  FlowTerminalNode,
+  FlowFormField,
+  FlowChoiceOption,
+  FlowAdvance,
+  FlowState,
+  FlowInput,
+} from "./utils/flow";
+
+// U8 — in-process, build-time custom renderer registry (no eval/remote code) and
+// its consumes-schema validator. Hosts register renderers at startup.
+export {
+  registerRenderer,
+  getRenderer,
+  hasRenderer,
+  unregisterRenderer,
+  clearRenderers,
+  validateConsumes,
+} from "./utils/renderers";
+export type {
+  RendererDefinition,
+  RendererProps,
+  ConsumesSchema,
+  ConsumeKind,
+  ValidationResult,
+} from "./utils/renderers";
+
 // Optional host integrations. Components degrade gracefully when these are not
 // configured; a host app opts in once at startup.
 export {

package/src/utils/flow.test.ts

@@ -0,0 +1,41 @@
+// U7 — flow node-model pure helpers (no DOM).
+import { describe, expect, it } from "vitest";
+import {
+  collectsInput,
+  formNodeInput,
+  isTerminal,
+  missingRequired,
+  type FlowFormNode,
+} from "./flow";
+
+const form: FlowFormNode = {
+  kind: "form",
+  id: "n1",
+  fields: [
+    { key: "amount", label: "Amount", type: "number", required: true },
+    { key: "note", label: "Note", type: "text" },
+  ],
+};
+
+describe("flow helpers", () => {
+  it("isTerminal flags only terminal nodes", () => {
+    expect(isTerminal({ kind: "terminal", id: "t" })).toBe(true);
+    expect(isTerminal(form)).toBe(false);
+  });
+
+  it("collectsInput flags form + choice", () => {
+    expect(collectsInput(form)).toBe(true);
+    expect(collectsInput({ kind: "choice", id: "c", options: [] })).toBe(true);
+    expect(collectsInput({ kind: "display", id: "d", body: "" })).toBe(false);
+  });
+
+  it("formNodeInput keeps declared fields, drops undefined", () => {
+    expect(formNodeInput(form, { amount: 5, stray: "x" })).toEqual({ amount: 5 });
+  });
+
+  it("missingRequired reports empty required fields only", () => {
+    expect(missingRequired(form, {})).toEqual(["amount"]);
+    expect(missingRequired(form, { amount: 5 })).toEqual([]);
+    expect(missingRequired(form, { amount: "" })).toEqual(["amount"]);
+  });
+});