@cosmicdrift/kumiko-headless 0.1.0

package/src/form/zod-bridge.ts

@@ -0,0 +1,75 @@
+import type { ZodError, ZodIssue } from "zod";
+import type { FieldIssue } from "../dispatcher";
+
+// Translates a ZodError into the same FieldIssue shape the server emits via
+// its own zod-bridge (packages/framework/src/errors/zod-bridge.ts). The two
+// bridges stay in sync on purpose: a field failing zod on the client reads
+// identically to the same field failing zod on the server, so the UI's
+// error-display path doesn't branch on provenance.
+//
+// Duplicated here (not imported) so ui-core remains free of
+// @cosmicdrift/kumiko-framework — this package has to bundle for browsers and Expo,
+// where a server-oriented framework dep would balloon bundle size and drag
+// in Node-only modules (postgres, drizzle, bullmq) even if only types are
+// consumed.
+//
+// Keep this list in sync with the server-side mirror — Zod version bumps
+// tend to introduce new param keys, and the server's classes.test.ts is
+// what catches them. A value added there should be added here too.
+const ISSUE_PARAM_KEYS = [
+  "minimum",
+  "maximum",
+  "expected",
+  "received",
+  "type",
+  "inclusive",
+  "exact",
+  "keys",
+  // Zod 4 additions
+  "format",
+  "divisor",
+  "values",
+  "pattern",
+] as const;
+
+// Flat FieldIssue list — same shape as server-side ValidationError.fields.
+// The form-controller groups this by `path` for its snapshot's errors map.
+export function zodErrorToFieldIssues(error: ZodError): FieldIssue[] {
+  return error.issues.map<FieldIssue>((issue) => {
+    const params = extractIssueParams(issue);
+    return {
+      // Empty-path issues (top-level object/array failures) use "(root)" so
+      // the form-controller has a stable key to show "form itself is
+      // malformed" errors under — matches what the server does.
+      path: issue.path.map(String).join(".") || "(root)",
+      code: issue.code,
+      i18nKey: `errors.validation.${issue.code}`,
+      ...(params && { params }),
+    };
+  });
+}
+
+function extractIssueParams(issue: ZodIssue): Readonly<Record<string, unknown>> | undefined {
+  const out: Record<string, unknown> = {};
+  const bag = issue as unknown as Record<string, unknown>; // @cast-boundary zod-issue
+  for (const key of ISSUE_PARAM_KEYS) {
+    if (bag[key] !== undefined) out[key] = bag[key];
+  }
+  return Object.keys(out).length > 0 ? out : undefined;
+}
+
+// Groups a flat FieldIssue list into the `errors` map carried by a
+// FormSnapshot. A field with multiple issues (e.g. both "required" and
+// "min") keeps both — UIs that only render the first can pick the first
+// element, those that want a full list have it.
+export function groupIssuesByPath(
+  issues: readonly FieldIssue[],
+): Record<string, readonly FieldIssue[]> {
+  const out: Record<string, FieldIssue[]> = {};
+  for (const issue of issues) {
+    const bucket = out[issue.path];
+    if (bucket) bucket.push(issue);
+    else out[issue.path] = [issue];
+  }
+  return out;
+}

package/src/index.ts

@@ -0,0 +1,81 @@
+export type { ParsedRefTarget } from "@cosmicdrift/kumiko-framework/ui-types";
+// Re-Export aus framework/ui-types damit Renderer-Code denselben
+// Parser nutzt wie der Server-Boot-Validator (Cross-Feature-Refs).
+export { parseRefTarget } from "@cosmicdrift/kumiko-framework/ui-types";
+export type {
+  AssetResolution,
+  AssetResolveContext,
+  AssetResolver,
+  BadgeProps,
+  ButtonProps,
+  CardProps,
+  DatePickerProps,
+  IconProps,
+  LocaleResolver,
+  ModalProps,
+  NumberInputProps,
+  PrimitiveCommonProps,
+  PrimitivesContract,
+  SelectOption,
+  SelectProps,
+  TextInputProps,
+  ToastIntent,
+  ToastProps,
+  ToggleProps,
+} from "./contracts";
+export type {
+  BatchResult,
+  Command,
+  Dispatcher,
+  DispatcherError,
+  DispatcherStatus,
+  FieldIssue,
+  PendingFile,
+  PendingWrite,
+  QueryOpts,
+  QueryResult,
+  WriteOpts,
+  WriteResult,
+} from "./dispatcher";
+export type {
+  FieldConditionPredicate,
+  FieldConditions,
+  FieldConditionValue,
+  FieldState,
+  FormController,
+  FormControllerOptions,
+  FormSnapshot,
+  FormValues,
+  SubmitConfig,
+  SubmitPayloadMode,
+  SubmitResult,
+} from "./form";
+export { createFormController } from "./form";
+export type {
+  NavDefinition,
+  NavNode,
+  NavRegistrySlice,
+  NavTree,
+  ResolveNavigationOptions,
+} from "./nav";
+export { resolveNavigation } from "./nav";
+export type { Store, WritableStore } from "./store";
+export { createStore, shallowEqual } from "./store";
+export type {
+  ComputeEditViewModelInput,
+  ComputeListViewModelInput,
+  EditFieldSpec,
+  EditFieldViewModel,
+  EditSectionSpec,
+  EditSectionViewModel,
+  EditViewModel,
+  FieldConditionCtx,
+  FieldRenderer,
+  ListColumnSpec,
+  ListColumnViewModel,
+  ListRowViewModel,
+  ListViewModel,
+  ScreenSlots,
+  Translate,
+} from "./view-model";
+export { computeEditViewModel, computeListViewModel, fieldLabelKey } from "./view-model";

package/src/nav/__tests__/resolve.test.ts

@@ -0,0 +1,202 @@
+import type { NavDefinition } from "@cosmicdrift/kumiko-framework/ui-types";
+import { describe, expect, test } from "vitest";
+import { resolveNavigation } from "../resolve";
+import type { NavRegistrySlice } from "../types";
+
+// Builds the minimal NavRegistrySlice resolveNavigation consumes from a
+// flat NavDefinition list. Shape matches what the framework registry
+// exposes: `topLevel` collects entries without a parent, `byParent`
+// looks up children by qualified parent-id. Ids in the list MUST already
+// be qualified ("feature:nav:short") — that's what the registry hands
+// back, so tests here mirror it 1:1.
+function buildSource(navs: readonly NavDefinition[]): NavRegistrySlice {
+  const byParent = new Map<string, NavDefinition[]>();
+  const topLevel: NavDefinition[] = [];
+  for (const nav of navs) {
+    if (nav.parent) {
+      const bucket = byParent.get(nav.parent);
+      if (bucket) bucket.push(nav);
+      else byParent.set(nav.parent, [nav]);
+    } else {
+      topLevel.push(nav);
+    }
+  }
+  return {
+    topLevel,
+    byParent: (qn) => byParent.get(qn) ?? [],
+  };
+}
+
+const userAdmin = { id: "u-admin", roles: ["Admin"] };
+const userStandard = { id: "u-std", roles: ["User"] };
+
+describe("resolveNavigation", () => {
+  test("flat list: all top-level entries become root nodes", () => {
+    const source = buildSource([
+      { id: "orders:nav:list", label: "Orders", screen: "orders:screen:order-list" },
+      { id: "orders:nav:dashboard", label: "Home" },
+    ]);
+
+    const tree = resolveNavigation({ source });
+
+    expect(tree).toHaveLength(2);
+    expect(tree.map((n) => n.qualifiedName).sort()).toEqual([
+      "orders:nav:dashboard",
+      "orders:nav:list",
+    ]);
+    expect(tree.every((n) => n.children.length === 0)).toBe(true);
+  });
+
+  test("parent refs assemble the tree — one level deep", () => {
+    const source = buildSource([
+      { id: "app:nav:ops", label: "Operations" },
+      {
+        id: "app:nav:ops-orders",
+        label: "Orders",
+        parent: "app:nav:ops",
+        screen: "orders:screen:order-list",
+      },
+      {
+        id: "app:nav:ops-shipments",
+        label: "Shipments",
+        parent: "app:nav:ops",
+        screen: "ship:screen:ship-list",
+      },
+    ]);
+
+    const tree = resolveNavigation({ source });
+
+    expect(tree).toHaveLength(1);
+    const ops = tree[0];
+    expect(ops?.qualifiedName).toBe("app:nav:ops");
+    expect(ops?.children).toHaveLength(2);
+    expect(ops?.children.map((c) => c.qualifiedName).sort()).toEqual([
+      "app:nav:ops-orders",
+      "app:nav:ops-shipments",
+    ]);
+  });
+
+  test("sort order: `order` ASC, ties broken by qualifiedName alphabetic", () => {
+    const source = buildSource([
+      { id: "app:nav:alpha", label: "A", order: 10 },
+      { id: "app:nav:beta", label: "B", order: 5 },
+      { id: "app:nav:charlie", label: "C", order: 5 }, // same order as beta
+    ]);
+
+    const tree = resolveNavigation({ source });
+
+    // beta (order=5) and charlie (order=5) first, both alphabetical, then alpha
+    expect(tree.map((n) => n.qualifiedName)).toEqual([
+      "app:nav:beta",
+      "app:nav:charlie",
+      "app:nav:alpha",
+    ]);
+  });
+
+  test("access: role-gated entries drop out for non-matching users", () => {
+    const source = buildSource([
+      { id: "app:nav:public", label: "Public" },
+      { id: "app:nav:admin-only", label: "Admin Area", access: { roles: ["Admin"] } },
+    ]);
+
+    const adminTree = resolveNavigation({ source, user: userAdmin });
+    expect(adminTree.map((n) => n.qualifiedName).sort()).toEqual([
+      "app:nav:admin-only",
+      "app:nav:public",
+    ]);
+
+    const stdTree = resolveNavigation({ source, user: userStandard });
+    expect(stdTree.map((n) => n.qualifiedName)).toEqual(["app:nav:public"]);
+  });
+
+  test("access: openToAll bypasses user-role check (matches handler-access semantic)", () => {
+    const source = buildSource([
+      { id: "app:nav:help", label: "Help", access: { openToAll: true } },
+    ]);
+
+    // Anonymous sees it.
+    expect(resolveNavigation({ source })).toHaveLength(1);
+    // Standard user sees it.
+    expect(resolveNavigation({ source, user: userStandard })).toHaveLength(1);
+  });
+
+  test("access: no user + role-gated entry → dropped (anonymous can't satisfy roles)", () => {
+    const source = buildSource([
+      { id: "app:nav:gated", label: "Gated", access: { roles: ["Admin"] } },
+    ]);
+
+    expect(resolveNavigation({ source })).toHaveLength(0);
+  });
+
+  test("hidden parent hides descendants (no orphaned children)", () => {
+    // "Reports" is Admin-only; the child "Sales Report" has no access rule
+    // (would be publicly visible by itself). With the parent gone, the
+    // child drops too — the resolver never recurses into a hidden node,
+    // so a lone link without its containing group can't appear.
+    const source = buildSource([
+      { id: "app:nav:reports", label: "Reports", access: { roles: ["Admin"] } },
+      {
+        id: "app:nav:sales-report",
+        label: "Sales",
+        parent: "app:nav:reports",
+        screen: "reports:screen:sales",
+      },
+    ]);
+
+    const tree = resolveNavigation({ source, user: userStandard });
+    expect(tree).toHaveLength(0);
+  });
+
+  test("entries pass through label/icon/screen verbatim — renderer translates label", () => {
+    const source = buildSource([
+      {
+        id: "app:nav:orders",
+        label: "orders:i18n:nav.orders",
+        icon: "package",
+        screen: "orders:screen:list",
+        order: 1,
+      },
+    ]);
+
+    const [node] = resolveNavigation({ source });
+    expect(node?.label).toBe("orders:i18n:nav.orders");
+    expect(node?.icon).toBe("package");
+    expect(node?.screen).toBe("orders:screen:list");
+    expect(node?.order).toBe(1);
+  });
+
+  test("order default is 0 on the NavNode when not provided", () => {
+    const source = buildSource([{ id: "app:nav:x", label: "X" }]);
+    expect(resolveNavigation({ source })[0]?.order).toBe(0);
+  });
+
+  test("dangling parent ref → child never reached (boot-validator should catch upstream)", () => {
+    // "orphan" has parent="missing"; "missing" is not registered.
+    // Because the walk is top-down, orphan sits only in byParent("missing")
+    // and byParent is never called for "missing" (it's not in topLevel,
+    // it's not reachable). So the child naturally drops.
+    const source = buildSource([
+      { id: "app:nav:orphan", label: "Orphan", parent: "app:nav:missing" },
+    ]);
+
+    expect(resolveNavigation({ source })).toHaveLength(0);
+  });
+
+  test("empty registry → empty tree", () => {
+    const source: NavRegistrySlice = { topLevel: [], byParent: () => [] };
+    expect(resolveNavigation({ source })).toEqual([]);
+  });
+
+  test("deeper nesting: three levels compose correctly", () => {
+    const source = buildSource([
+      { id: "a:nav:root", label: "Root" },
+      { id: "a:nav:mid", label: "Mid", parent: "a:nav:root" },
+      { id: "a:nav:leaf", label: "Leaf", parent: "a:nav:mid", screen: "a:screen:x" },
+    ]);
+
+    const tree = resolveNavigation({ source });
+    expect(tree[0]?.qualifiedName).toBe("a:nav:root");
+    expect(tree[0]?.children[0]?.qualifiedName).toBe("a:nav:mid");
+    expect(tree[0]?.children[0]?.children[0]?.qualifiedName).toBe("a:nav:leaf");
+  });
+});

package/src/nav/index.ts

@@ -0,0 +1,8 @@
+export { resolveNavigation } from "./resolve";
+export type {
+  NavDefinition,
+  NavNode,
+  NavRegistrySlice,
+  NavTree,
+  ResolveNavigationOptions,
+} from "./types";

package/src/nav/resolve.ts

@@ -0,0 +1,77 @@
+import type { AccessRule, NavDefinition } from "@cosmicdrift/kumiko-framework/ui-types";
+import type { NavNode, NavTree, ResolveNavigationOptions } from "./types";
+
+// Assembles the renderable nav tree from the registry's pre-grouped
+// indexes (topLevel + byParent). Walks top-down: each node is
+// access-checked; a hidden parent drops its entire subtree implicitly
+// because we never recurse into it. Siblings sort by `order` (ascending,
+// default 0), tie-broken by qualified name so renders stay deterministic
+// across registry iteration orders.
+//
+// Pure — same inputs produce the same tree. The renderer memoizes the
+// result and only recomputes when the registry changes (rare — boot
+// only) or the user's roles change (logout/login, tenant-switch).
+export function resolveNavigation(options: ResolveNavigationOptions): NavTree {
+  const { source, user } = options;
+
+  function build(entry: NavDefinition): NavNode | null {
+    if (!userCanSee(entry.access, user)) return null;
+    // `entry.id` is already the qualified name — the registry stores
+    // it that way. No reverse-index lookup needed.
+    const children: NavNode[] = [];
+    for (const child of source.byParent(entry.id)) {
+      const node = build(child);
+      if (node !== null) children.push(node);
+    }
+    children.sort(bySortKey);
+    return {
+      qualifiedName: entry.id,
+      label: entry.label,
+      order: entry.order ?? 0,
+      children,
+      ...(entry.icon !== undefined && { icon: entry.icon }),
+      ...(entry.screen !== undefined && { screen: entry.screen }),
+    };
+  }
+
+  const roots: NavNode[] = [];
+  for (const entry of source.topLevel) {
+    const node = build(entry);
+    if (node !== null) roots.push(node);
+  }
+  roots.sort(bySortKey);
+  return roots;
+}
+
+function bySortKey(a: NavNode, b: NavNode): number {
+  // Primary key: `order` ascending. Secondary: qualifiedName alphabetic,
+  // which is a stable fallback — the registry-iteration order isn't
+  // guaranteed across boots, so tied-order entries would otherwise
+  // shuffle between renders.
+  if (a.order !== b.order) return a.order - b.order;
+  return a.qualifiedName.localeCompare(b.qualifiedName);
+}
+
+// Access evaluator. Duplicated minimal logic instead of importing
+// hasAccess from @cosmicdrift/kumiko-framework/engine at runtime — that module pulls
+// in server-side deps (tenant-db, ownership-evaluator) and would break
+// ui-core's bundle-purity guarantee. Only roles + openToAll are checked;
+// ownership-level row-filtering is a server-side concern and doesn't
+// apply to navigation entries (they're a menu, not a dataset).
+function userCanSee(
+  access: AccessRule | undefined,
+  user: ResolveNavigationOptions["user"],
+): boolean {
+  // No rule = always visible — matches the framework's "engine stays
+  // un-opinionated about who sees what" stance in the nav docs.
+  if (!access) return true;
+  if ("openToAll" in access && access.openToAll) return true;
+  if (!user) return false; // anonymous can't match a role-gated rule
+  if ("roles" in access) {
+    const allowed = access.roles;
+    for (const role of user.roles) {
+      if (allowed.includes(role)) return true;
+    }
+  }
+  return false;
+}

package/src/nav/types.ts

@@ -0,0 +1,61 @@
+import type { NavDefinition } from "@cosmicdrift/kumiko-framework/ui-types";
+
+// A single resolved nav entry as the renderer consumes it. Labels are NOT
+// translated yet — nav can be used in SSR contexts where the locale isn't
+// known at resolve time; the renderer runs `label` through
+// LocaleResolver.translate() when it draws the sidebar/topbar item.
+//
+// Identity: `qualifiedName` is the same QN the registry uses
+// ("{feature}:nav:{id}"). Renderers key off this for active-route tracking
+// and for `parent` matching in screen extensions (M4).
+export type NavNode = {
+  readonly qualifiedName: string;
+  readonly label: string;
+  readonly icon?: string;
+  readonly screen?: string;
+  readonly order: number;
+  readonly children: readonly NavNode[];
+};
+
+// The tree returned by resolveNavigation. Empty when the user can see no
+// entries — renderer draws a fallback ("no navigation available" or just
+// a blank sidebar, app decision).
+export type NavTree = readonly NavNode[];
+
+// Minimal registry surface resolveNavigation reads from. Deliberately
+// narrower than the full Registry — keeps the resolver test-friendly
+// (callers can stub with a two-field plain object) and pins the
+// coupling to just the two index-accessors the resolver actually uses:
+//
+//   - `topLevel` : roots list (entries with no parent). Pre-grouped in
+//                  the registry — resolver starts its walk here.
+//   - `byParent` : O(1) children lookup by parent qualified name. The
+//                  walk descends into this for each node; access-gating
+//                  happens top-down, so a hidden parent implicitly
+//                  hides the whole subtree.
+//
+// Note: the registry stores each NavDefinition with its `id` already
+// qualified ("feature:nav:short"); resolveNavigation reads that directly.
+//
+// Production callers pass:
+//   { topLevel: registry.getTopLevelNavs(),
+//     byParent: (qn) => registry.getNavsByParent(qn) }
+export type NavRegistrySlice = {
+  readonly topLevel: readonly NavDefinition[];
+  readonly byParent: (parentQualifiedName: string) => readonly NavDefinition[];
+};
+
+// Options passed to resolveNavigation.
+export type ResolveNavigationOptions = {
+  readonly source: NavRegistrySlice;
+  // Current session user. Access-rule enforcement compares
+  // rule.roles against user.roles. When user is undefined, ONLY
+  // entries with access.openToAll === true (or no access declared)
+  // survive — matches the "anonymous visit" semantic.
+  readonly user?: {
+    readonly id: string;
+    readonly roles: readonly string[];
+  };
+};
+
+export type { NavDefinition };

package/src/store/__tests__/create-store.test.ts

@@ -0,0 +1,139 @@
+import { describe, expect, test, vi } from "vitest";
+import { createStore } from "../create-store";
+
+describe("createStore — snapshot & setState", () => {
+  test("getSnapshot returns the initial value", () => {
+    const store = createStore({ count: 0 });
+    expect(store.getSnapshot()).toEqual({ count: 0 });
+  });
+
+  test("setState with a value updates the snapshot", () => {
+    const store = createStore({ count: 0 });
+    store.setState({ count: 5 });
+    expect(store.getSnapshot()).toEqual({ count: 5 });
+  });
+
+  test("setState with a reducer receives the current snapshot", () => {
+    const store = createStore({ count: 3 });
+    store.setState((prev) => ({ count: prev.count + 1 }));
+    expect(store.getSnapshot()).toEqual({ count: 4 });
+  });
+
+  test("getSnapshot returns stable reference when value unchanged (Object.is gate)", () => {
+    const initial = { count: 0 };
+    const store = createStore(initial);
+    const before = store.getSnapshot();
+    store.setState(initial); // same reference
+    expect(store.getSnapshot()).toBe(before);
+  });
+});
+
+describe("createStore — subscribe & notify", () => {
+  test("subscribed listener fires on setState", () => {
+    const store = createStore({ count: 0 });
+    const listener = vi.fn();
+    store.subscribe(listener);
+
+    store.setState({ count: 1 });
+
+    expect(listener).toHaveBeenCalledTimes(1);
+  });
+
+  test("multiple listeners all fire on setState", () => {
+    const store = createStore({ count: 0 });
+    const a = vi.fn();
+    const b = vi.fn();
+    store.subscribe(a);
+    store.subscribe(b);
+
+    store.setState({ count: 1 });
+
+    expect(a).toHaveBeenCalledTimes(1);
+    expect(b).toHaveBeenCalledTimes(1);
+  });
+
+  test("unsubscribe stops further notifications", () => {
+    const store = createStore({ count: 0 });
+    const listener = vi.fn();
+    const unsub = store.subscribe(listener);
+
+    store.setState({ count: 1 });
+    unsub();
+    store.setState({ count: 2 });
+
+    expect(listener).toHaveBeenCalledTimes(1);
+  });
+
+  test("Object.is-equal setState does NOT notify listeners", () => {
+    const store = createStore({ count: 0 });
+    const same = store.getSnapshot();
+    const listener = vi.fn();
+    store.subscribe(listener);
+
+    // Same reference — gate blocks notification.
+    store.setState(same);
+    // Primitive-equal setState on primitive-valued store also no-ops.
+    const primStore = createStore(42);
+    const primListener = vi.fn();
+    primStore.subscribe(primListener);
+    primStore.setState(42);
+
+    expect(listener).not.toHaveBeenCalled();
+    expect(primListener).not.toHaveBeenCalled();
+  });
+
+  test("setState inside reducer that returns same ref does NOT notify", () => {
+    const store = createStore({ count: 0 });
+    const listener = vi.fn();
+    store.subscribe(listener);
+
+    store.setState((prev) => prev); // reducer returns same ref
+
+    expect(listener).not.toHaveBeenCalled();
+  });
+});
+
+describe("createStore — reentrancy safety", () => {
+  test("listener unsubscribing itself during callback does not break iteration", () => {
+    const store = createStore({ count: 0 });
+    const order: string[] = [];
+
+    const unsubA = store.subscribe(() => {
+      order.push("a");
+      unsubA(); // self-unsubscribe mid-loop
+    });
+    store.subscribe(() => {
+      order.push("b");
+    });
+
+    store.setState({ count: 1 });
+
+    // Both fire on this cycle; A must not prevent B from running.
+    expect(order).toEqual(["a", "b"]);
+
+    // A is gone; only B fires on the next cycle.
+    order.length = 0;
+    store.setState({ count: 2 });
+    expect(order).toEqual(["b"]);
+  });
+
+  test("listener unsubscribing ANOTHER listener mid-loop does not re-invoke it", () => {
+    const store = createStore({ count: 0 });
+    const order: string[] = [];
+
+    let unsubB: (() => void) | null = null;
+
+    store.subscribe(() => {
+      order.push("a");
+      unsubB?.(); // kill B before its turn
+    });
+    unsubB = store.subscribe(() => {
+      order.push("b");
+    });
+
+    store.setState({ count: 1 });
+
+    // B was unsubscribed by A before iteration reached it.
+    expect(order).toEqual(["a"]);
+  });
+});