@kahitsan/ksui 0.19.0 → 0.20.0

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;
+}

package/src/utils/renderers.test.ts

@@ -0,0 +1,87 @@
+// U8 — registry + consumes-validation unit tests (pure, no DOM).
+import { afterEach, describe, expect, it } from "vitest";
+import {
+  clearRenderers,
+  getRenderer,
+  hasRenderer,
+  registerRenderer,
+  unregisterRenderer,
+  validateConsumes,
+  type RendererDefinition,
+} from "./renderers";
+
+const noopDef = (id: string): RendererDefinition => ({
+  id,
+  consumes: { name: "string" },
+  emits: ["edit"],
+  render: () => null as never,
+});
+
+afterEach(() => clearRenderers());
+
+describe("renderer registry", () => {
+  it("registers and looks up by id", () => {
+    registerRenderer(noopDef("card"));
+    expect(hasRenderer("card")).toBe(true);
+    expect(getRenderer("card")?.id).toBe("card");
+  });
+
+  it("re-registering the same id replaces (last write wins)", () => {
+    registerRenderer(noopDef("card"));
+    registerRenderer({ ...noopDef("card"), emits: ["pay"] });
+    expect(getRenderer("card")?.emits).toEqual(["pay"]);
+  });
+
+  it("unknown id is undefined, not a throw", () => {
+    expect(getRenderer("missing")).toBeUndefined();
+    expect(hasRenderer("missing")).toBe(false);
+  });
+
+  it("unregister removes a renderer", () => {
+    registerRenderer(noopDef("card"));
+    unregisterRenderer("card");
+    expect(hasRenderer("card")).toBe(false);
+  });
+});
+
+describe("validateConsumes", () => {
+  it("accepts a matching item", () => {
+    const r = validateConsumes(
+      { customer: "string", progress: "number", packages: "array", balance: "currency?" },
+      { customer: "Acme", progress: 3, packages: [], balance: 1200 },
+    );
+    expect(r.ok).toBe(true);
+    expect(r.errors).toEqual([]);
+  });
+
+  it("allows an optional field to be absent", () => {
+    const r = validateConsumes({ name: "string", balance: "currency?" }, { name: "x" });
+    expect(r.ok).toBe(true);
+  });
+
+  it("rejects a missing required field", () => {
+    const r = validateConsumes({ name: "string" }, {});
+    expect(r.ok).toBe(false);
+    expect(r.errors[0]).toContain("name");
+  });
+
+  it("rejects a type mismatch", () => {
+    const r = validateConsumes({ progress: "number" }, { progress: "nope" });
+    expect(r.ok).toBe(false);
+    expect(r.errors[0]).toContain("expected number");
+  });
+
+  it("rejects a non-object item", () => {
+    expect(validateConsumes({ a: "string" }, null).ok).toBe(false);
+    expect(validateConsumes({ a: "string" }, [] as unknown).ok).toBe(false);
+  });
+
+  it("ignores extra keys not in the schema", () => {
+    const r = validateConsumes({ name: "string" }, { name: "x", extra: 99 });
+    expect(r.ok).toBe(true);
+  });
+
+  it("any matches anything", () => {
+    expect(validateConsumes({ blob: "any" }, { blob: { x: 1 } }).ok).toBe(true);
+  });
+});

package/src/utils/renderers.ts

@@ -0,0 +1,153 @@
+// U8 — schema-bound custom renderer registry (Vision §8).
+//
+// A custom renderer is a REAL, in-process SolidJS component built on ksui
+// primitives — never an iframe/VM. The Vision is explicit that runtime isolation
+// is deliberately omitted (theming fidelity + performance); what keeps a renderer
+// safe is that it holds NO authority: it receives only its declared `consumes`
+// data and can only fire its declared `emits` (flow triggers, §9). It cannot read
+// or write data or call peers.
+//
+// WHY a build-time, in-process registry (no eval, no remote code): the security
+// boundary for code-bearing UI is SUPPLY-CHAIN, not sandbox (Vision §8 / §14 —
+// the VS Code model). The registry holds only components linked into the bundle
+// at build time, so trust comes from the package supply chain (signing, scanning,
+// verified publishers), not from caging a string of code at runtime. There is no
+// `eval`, no dynamic `import(url)`, no Function constructor anywhere here.
+
+import type { Component } from "solid-js";
+
+/** The set of primitive shapes a renderer can declare it consumes per field. */
+export type ConsumeKind =
+  | "string"
+  | "number"
+  | "boolean"
+  | "enum"
+  | "array"
+  | "object"
+  | "currency"
+  | "any";
+
+/**
+ * The input-schema contract a renderer declares (§8 `consumes`): a map of
+ * prop name → expected kind. A trailing "?" on the kind marks the field optional
+ * (e.g. `balance: "currency?"` in the Vision example). The registry validates an
+ * `item` against this before rendering and falls back when it doesn't match.
+ */
+export type ConsumesSchema = Readonly<Record<string, `${ConsumeKind}` | `${ConsumeKind}?`>>;
+
+/** The props a registered renderer receives. `emit` only fires declared triggers. */
+export interface RendererProps {
+  /** The validated data object, shaped by the renderer's `consumes` schema. */
+  readonly item: Record<string, unknown>;
+  /**
+   * Fire one of the renderer's declared `emits` interaction points. The host
+   * wires each emit name to a flow trigger (§9); ksui never executes authority.
+   * An emit NOT in the declared set is dropped with a warning (a renderer cannot
+   * forge an interaction it never declared).
+   */
+  readonly emit: (event: string, payload?: unknown) => void;
+}
+
+/** A registry entry: the schema-bound contract plus the in-process component. */
+export interface RendererDefinition {
+  /** Stable id a spec binds to (e.g. "availment-card"). */
+  readonly id: string;
+  /** Input schema the component consumes (§8). */
+  readonly consumes: ConsumesSchema;
+  /** Interaction points the component may emit (§8) → flow triggers (§9). */
+  readonly emits: readonly string[];
+  /** The real, in-process SolidJS component. Built on ksui primitives. */
+  readonly render: Component<RendererProps>;
+}
+
+/** Result of validating an item against a `consumes` schema. */
+export interface ValidationResult {
+  readonly ok: boolean;
+  /** Human-readable reasons a prop failed (empty when ok). */
+  readonly errors: readonly string[];
+}
+
+// ---------------------------------------------------------------------------
+// The registry (module-scoped, in-process). Populated at build time by the host
+// calling `registerRenderer` during startup wiring — never from network input.
+// ---------------------------------------------------------------------------
+
+const REGISTRY = new Map<string, RendererDefinition>();
+
+/**
+ * Register an in-process renderer. Re-registering the same id REPLACES the prior
+ * one (last write wins) so a host can override a kit default deterministically.
+ */
+export function registerRenderer(def: RendererDefinition): void {
+  REGISTRY.set(def.id, def);
+}
+
+/** Look up a registered renderer, or undefined when the id is unknown. */
+export function getRenderer(id: string): RendererDefinition | undefined {
+  return REGISTRY.get(id);
+}
+
+/** True when an id is registered. */
+export function hasRenderer(id: string): boolean {
+  return REGISTRY.has(id);
+}
+
+/** Remove a renderer (used by tests + hot-reload). */
+export function unregisterRenderer(id: string): void {
+  REGISTRY.delete(id);
+}
+
+/** Clear the whole registry (test isolation). */
+export function clearRenderers(): void {
+  REGISTRY.clear();
+}
+
+// ---------------------------------------------------------------------------
+// Validation — does an item satisfy a renderer's declared `consumes` schema?
+// ---------------------------------------------------------------------------
+
+function kindMatches(kind: ConsumeKind, value: unknown): boolean {
+  switch (kind) {
+    case "any":
+      return true;
+    case "string":
+    case "enum": // an enum value arrives as a string; the renderer maps it
+      return typeof value === "string";
+    case "number":
+    case "currency": // currency is a numeric amount in minor/major units
+      return typeof value === "number" && !Number.isNaN(value);
+    case "boolean":
+      return typeof value === "boolean";
+    case "array":
+      return Array.isArray(value);
+    case "object":
+      return typeof value === "object" && value !== null && !Array.isArray(value);
+  }
+}
+
+/**
+ * Validate `item` against a `consumes` schema. A field whose kind ends in "?" is
+ * optional — absent/undefined is allowed, but a present value still type-checks.
+ * Extra keys on `item` not named in the schema are IGNORED (the renderer simply
+ * won't read them); only declared fields are enforced.
+ */
+export function validateConsumes(consumes: ConsumesSchema, item: unknown): ValidationResult {
+  if (typeof item !== "object" || item === null || Array.isArray(item)) {
+    return { ok: false, errors: ["item must be a non-null object"] };
+  }
+  const record = item as Record<string, unknown>;
+  const errors: string[] = [];
+  for (const [key, spec] of Object.entries(consumes)) {
+    const optional = spec.endsWith("?");
+    const kind = (optional ? spec.slice(0, -1) : spec) as ConsumeKind;
+    const value = record[key];
+    if (value === undefined || value === null) {
+      if (!optional) errors.push(`missing required "${key}" (${kind})`);
+      continue;
+    }
+    if (!kindMatches(kind, value)) {
+      errors.push(`"${key}" expected ${kind}, got ${typeof value}`);
+    }
+  }
+  return { ok: errors.length === 0, errors };
+}