@kahitsan/ksui 0.19.0 → 0.21.0

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

@@ -64,6 +64,7 @@ export { default as KpiCard, type KpiCardProps, type KpiTone } from "./component
 export { default as RadioCardGroup } from "./components/base/RadioCardGroup";
 export { default as FormErrorBanner } from "./components/base/FormErrorBanner";
 export { default as TagPill } from "./components/base/TagPill";
+export { default as BadgeSelect, type BadgeSelectProps, type BadgeSelectOption } from "./components/base/BadgeSelect";
 export { default as DateTile, type DateTileProps } from "./components/base/DateTile";
 export { default as Button, type ButtonProps, type ButtonIntent, type ButtonVariant } from "./components/base/Button";
 export { default as ThemeToggle, type ThemeToggleProps, type ThemeToggleValue } from "./components/base/ThemeToggle";
@@ -160,6 +161,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 +212,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"]);
+  });
+});

package/src/utils/flow.ts

@@ -0,0 +1,149 @@
+// U7 — flow node model (Vision §9). The CLIENT renders only UI-EFFECT nodes;
+// ALL authority/data/branching lives server-side. The client never decides the
+// graph — it renders the current node and POSTs each step to a host-injected
+// `advance(state, input) => Promise<nextNode>` resolver. ksui ships NO server
+// logic and NO `command`/`call(peer)` node kinds: those carry authority and run
+// on the kernel (§9 "authority is server-side, presentation is client-side").
+//
+// This file is PURE (no solid-js, no component imports) so the node model + its
+// type guards unit-test under plain node, mirroring the resource `spec.ts` split.
+
+/** A single field a flow `form` node asks the user to fill (§10, UI subset). */
+export interface FlowFormField {
+  readonly key: string;
+  readonly label: string;
+  /** Widget hint the runner maps to an input; defaults to "text". */
+  readonly type?: "text" | "textarea" | "number" | "select" | "toggle";
+  readonly required?: boolean;
+  readonly placeholder?: string;
+  /** For "select": the choices. */
+  readonly options?: ReadonlyArray<{ readonly value: string; readonly label: string }>;
+}
+
+/** A choice the user picks; its `value` is the input POSTed to `advance` (§9). */
+export interface FlowChoiceOption {
+  readonly value: string;
+  readonly label: string;
+  /** Visual emphasis hint; the runner styles primary distinctly. */
+  readonly intent?: "primary" | "neutral" | "danger";
+}
+
+// ---- The UI-effect node kinds the CLIENT renders (and ONLY these) ----------
+
+/** A form node: collect typed values, submit continues the flow (§10). */
+export interface FlowFormNode {
+  readonly kind: "form";
+  /** Server-assigned node id, echoed back so the server correlates the step. */
+  readonly id: string;
+  readonly title?: string;
+  readonly fields: readonly FlowFormField[];
+  readonly submitLabel?: string;
+  /** When true the runner offers a cancel affordance taking the onCancel edge. */
+  readonly cancelable?: boolean;
+}
+
+/** A display node: render server-provided read-only content, then continue. */
+export interface FlowDisplayNode {
+  readonly kind: "display";
+  readonly id: string;
+  readonly title?: string;
+  /** Read-only text/markup string the server already rendered/sanitized. */
+  readonly body: string;
+  readonly continueLabel?: string;
+}
+
+/** A choice node: the user picks one option; its value is the step input. */
+export interface FlowChoiceNode {
+  readonly kind: "choice";
+  readonly id: string;
+  readonly title?: string;
+  readonly prompt?: string;
+  readonly options: readonly FlowChoiceOption[];
+}
+
+/** A message node: a transient toast-like notice; continues automatically or on ack. */
+export interface FlowMessageNode {
+  readonly kind: "message";
+  readonly id: string;
+  readonly text: string;
+  readonly tone?: "info" | "success" | "error";
+  readonly ackLabel?: string;
+}
+
+/**
+ * A terminal node: the flow is done. The client stops here and renders the
+ * outcome; it never calls `advance` from a terminal node. The server marks
+ * terminality — the client does not infer it.
+ */
+export interface FlowTerminalNode {
+  readonly kind: "terminal";
+  readonly id: string;
+  readonly title?: string;
+  readonly message?: string;
+  readonly tone?: "success" | "error" | "info";
+}
+
+/** The discriminated union of client-renderable nodes (UI-effect + terminal). */
+export type FlowNode =
+  | FlowFormNode
+  | FlowDisplayNode
+  | FlowChoiceNode
+  | FlowMessageNode
+  | FlowTerminalNode;
+
+/** Opaque server state threaded through each step; the client never reads into it. */
+export type FlowState = unknown;
+
+/** The input a step submits back to the server (form values / choice value / ack). */
+export type FlowInput = Record<string, unknown> | null;
+
+/**
+ * The host-injected resolver that owns ALL authority + branching. Given the
+ * current opaque state and the step's input, it returns the next node (which may
+ * be terminal). ksui never decides what comes next — it only renders + POSTs.
+ */
+export type FlowAdvance = (state: FlowState, input: FlowInput) => Promise<FlowNode>;
+
+/** True for the terminal node kind (the runner stops calling `advance`). */
+export function isTerminal(node: FlowNode): node is FlowTerminalNode {
+  return node.kind === "terminal";
+}
+
+/** True for a node the runner submits user input from (form/choice/message). */
+export function collectsInput(node: FlowNode): node is FlowFormNode | FlowChoiceNode {
+  return node.kind === "form" || node.kind === "choice";
+}
+
+/**
+ * Build the input payload for a form node from its current field values,
+ * dropping undefined and coercing nothing (the server re-validates — §10.5).
+ * Pure helper so submission shaping is testable without a DOM.
+ */
+export function formNodeInput(
+  node: FlowFormNode,
+  values: Record<string, unknown>,
+): Record<string, unknown> {
+  const out: Record<string, unknown> = {};
+  for (const f of node.fields) {
+    const v = values[f.key];
+    if (v !== undefined) out[f.key] = v;
+  }
+  return out;
+}
+
+/**
+ * Which required form fields are still empty. Client-side gating is UX only;
+ * the kernel re-validates every rule server-side (§10.5) — this never authorizes.
+ */
+export function missingRequired(
+  node: FlowFormNode,
+  values: Record<string, unknown>,
+): string[] {
+  const missing: string[] = [];
+  for (const f of node.fields) {
+    if (!f.required) continue;
+    const v = values[f.key];
+    if (v === undefined || v === null || v === "") missing.push(f.key);
+  }
+  return missing;
+}