@cosmicdrift/kumiko-headless 0.1.0

package/src/store/__tests__/equality.test.ts

@@ -0,0 +1,66 @@
+import { describe, expect, test } from "vitest";
+import { shallowEqual } from "../equality";
+
+describe("shallowEqual — primitive cases", () => {
+  test("Object.is-equal primitives are equal", () => {
+    expect(shallowEqual(1, 1)).toBe(true);
+    expect(shallowEqual("a", "a")).toBe(true);
+    expect(shallowEqual(true, true)).toBe(true);
+    expect(shallowEqual(null, null)).toBe(true);
+    expect(shallowEqual(undefined, undefined)).toBe(true);
+  });
+
+  test("NaN equals NaN (Object.is semantics)", () => {
+    expect(shallowEqual(Number.NaN, Number.NaN)).toBe(true);
+  });
+
+  test("differing primitives are not equal", () => {
+    expect(shallowEqual(1, 2)).toBe(false);
+    expect(shallowEqual("a", "b")).toBe(false);
+    expect(shallowEqual(0, -0)).toBe(false); // Object.is distinguishes
+  });
+
+  test("primitive vs object is not equal", () => {
+    expect(shallowEqual(1, { 0: 1 })).toBe(false);
+    expect(shallowEqual(null, {})).toBe(false);
+    expect(shallowEqual({}, null)).toBe(false);
+  });
+});
+
+describe("shallowEqual — object cases", () => {
+  test("same reference is equal", () => {
+    const o = { a: 1 };
+    expect(shallowEqual(o, o)).toBe(true);
+  });
+
+  test("same keys + same values → equal", () => {
+    expect(shallowEqual({ a: 1, b: 2 }, { a: 1, b: 2 })).toBe(true);
+  });
+
+  test("same keys, different value → not equal", () => {
+    expect(shallowEqual({ a: 1, b: 2 }, { a: 1, b: 3 })).toBe(false);
+  });
+
+  test("different number of keys → not equal", () => {
+    expect(shallowEqual({ a: 1 }, { a: 1, b: 2 })).toBe(false);
+    expect(shallowEqual({ a: 1, b: 2 }, { a: 1 })).toBe(false);
+  });
+
+  test("same count, different key names → not equal", () => {
+    expect(shallowEqual({ a: 1 }, { b: 1 })).toBe(false);
+  });
+
+  test("nested object: only top-level refs compared (shallow)", () => {
+    const inner = { x: 1 };
+    // Same nested ref → equal at top level.
+    expect(shallowEqual({ inner }, { inner })).toBe(true);
+    // Equivalent but distinct nested ref → NOT equal (shallow doesn't recurse).
+    expect(shallowEqual({ inner: { x: 1 } }, { inner: { x: 1 } })).toBe(false);
+  });
+
+  test("arrays compared as objects: same length + same values → equal", () => {
+    expect(shallowEqual([1, 2, 3], [1, 2, 3])).toBe(true);
+    expect(shallowEqual([1, 2, 3], [1, 2, 4])).toBe(false);
+    expect(shallowEqual([1, 2], [1, 2, 3])).toBe(false);
+  });
+});

package/src/store/create-store.ts

@@ -0,0 +1,44 @@
+import type { WritableStore } from "./types";
+
+// Subscribe/Emit primitive matching React's useSyncExternalStore.
+// Single canonical implementation — every stateful controller in
+// ui-core/renderer land composes on top of this instead of rolling
+// its own listener-set + notify-loop.
+//
+// Reentrancy semantics use the Set's documented iteration behavior:
+// listeners deleted DURING the notify-loop but BEFORE their turn are
+// skipped; listeners deleting themselves AFTER firing don't break the
+// loop (Set iteration tolerates concurrent mutation of already-visited
+// entries). MDN: "callbackFn is not invoked for values deleted before
+// being visited." This is exactly the contract callers expect.
+//
+// Caveat — Function-valued stores: setState detects the reducer-form via
+// `typeof next === "function"`. If T itself is a function type
+// (`createStore<() => string>(...)`), there is no way to tell a "new
+// value that happens to be a function" apart from a "reducer producing a
+// new function". Same trap React's useState has. Workaround: wrap the
+// new function in a reducer that ignores prev:
+//   store.setState(() => myNewFn);
+// In practice, function-valued stores are rare — feature controllers
+// hold values, not callbacks.
+
+export function createStore<T>(initial: T): WritableStore<T> {
+  let snapshot = initial;
+  const listeners = new Set<() => void>();
+
+  return {
+    getSnapshot: () => snapshot,
+    subscribe: (listener) => {
+      listeners.add(listener);
+      return () => {
+        listeners.delete(listener);
+      };
+    },
+    setState: (next) => {
+      const nextValue = typeof next === "function" ? (next as (prev: T) => T)(snapshot) : next;
+      if (Object.is(nextValue, snapshot)) return;
+      snapshot = nextValue;
+      for (const listener of listeners) listener();
+    },
+  };
+}

package/src/store/equality.ts

@@ -0,0 +1,34 @@
+// Shallow equality — Object.is on each own enumerable key. The
+// recommended Equality-Arg for useStoreSelector when the selector
+// returns a plain object/array literal (`s => ({ a: s.a, b: s.b })`),
+// which would otherwise produce a fresh reference each render and
+// trip useSyncExternalStore's identity check.
+//
+// Mirrors Zustand's `shallow` and react-redux's `shallowEqual` — same
+//8-line shape, no recursion. Apps that need deep equality reach for
+// their own helper.
+
+// Signature is `(a: unknown, b: unknown)` not `<T>(a: T, b: T)` because the
+// function legitimately compares cross-type values (primitive vs. object,
+// null vs. {}, etc.) and returns false for mismatches. A generic `<T>`
+// would force callers into type-gymnastics for those cases. Contra-variance
+// ensures this still satisfies `(a: S, b: S) => boolean` slots like
+// useStoreSelector's `equals` arg.
+export function shallowEqual(a: unknown, b: unknown): boolean {
+  if (Object.is(a, b)) return true;
+  if (typeof a !== "object" || a === null) return false;
+  if (typeof b !== "object" || b === null) return false;
+
+  const keysA = Object.keys(a);
+  const keysB = Object.keys(b);
+  if (keysA.length !== keysB.length) return false;
+
+  for (const key of keysA) {
+    if (!Object.hasOwn(b, key)) return false;
+    if (!Object.is((a as Record<string, unknown>)[key], (b as Record<string, unknown>)[key])) {
+      // @cast-boundary generic-record
+      return false;
+    }
+  }
+  return true;
+}

package/src/store/index.ts

@@ -0,0 +1,3 @@
+export { createStore } from "./create-store";
+export { shallowEqual } from "./equality";
+export type { Store, WritableStore } from "./types";

package/src/store/types.ts

@@ -0,0 +1,27 @@
+// Store contract — Pull-Style Subscribe/Emit matching React's
+// useSyncExternalStore signature. The single canonical shape for
+// every stateful controller in ui-core/renderer land (form,
+// dispatcher-status, locale, token, nav, lifecycle).
+//
+// Rationale in docs/plans/ui-store.md. Not a new state-management
+// decision — ui-decisions.md already picked Subscribe/Emit; this
+// module just materializes the pattern instead of rolling a new
+// Set<() => void> per controller.
+
+export type Store<T> = {
+  // Current snapshot. Referentially stable across no-op setState calls
+  // (see createStore's Object.is gate) so useSyncExternalStore doesn't
+  // re-render consumers when nothing actually changed.
+  getSnapshot(): T;
+  // Subscribe listener, returns unsubscribe. Listener receives no
+  // payload — it reads via getSnapshot(). Direct match for
+  // useSyncExternalStore's contract.
+  subscribe(listener: () => void): () => void;
+};
+
+export type WritableStore<T> = Store<T> & {
+  // Update with a new value or a reducer function. If the resulting
+  // snapshot is Object.is-equal to the current one, listeners are NOT
+  // notified — re-render prevention at the source.
+  setState(next: T | ((prev: T) => T)): void;
+};

package/src/view-model/__tests__/edit.test.ts

@@ -0,0 +1,242 @@
+import type {
+  EntityDefinition,
+  EntityEditScreenDefinition,
+} from "@cosmicdrift/kumiko-framework/ui-types";
+import { describe, expect, test } from "vitest";
+import { computeEditViewModel } from "../edit";
+
+const orderEntity = {
+  fields: {
+    customerName: { type: "text", required: true },
+    notes: { type: "text" },
+    vatExempt: { type: "boolean" },
+    vatReason: { type: "text" },
+  },
+} as unknown as EntityDefinition;
+
+function editScreen(
+  layout: EntityEditScreenDefinition["layout"],
+  overrides?: Partial<EntityEditScreenDefinition>,
+): EntityEditScreenDefinition {
+  return {
+    id: "orders:screen:order-edit",
+    type: "entityEdit",
+    entity: "order",
+    layout,
+    ...overrides,
+  };
+}
+
+const translate = (key: string) => key;
+
+describe("computeEditViewModel", () => {
+  test("flat screen: single section, string-form fields → resolved field view models", () => {
+    const vm = computeEditViewModel({
+      screen: editScreen({
+        sections: [{ title: "Hauptdaten", fields: ["customerName", "notes"] }],
+      }),
+      entity: orderEntity,
+      values: { customerName: "Acme", notes: "VIP" },
+      translate,
+      featureName: "orders",
+    });
+
+    expect(vm.sections).toHaveLength(1);
+    const section = vm.sections[0];
+    expect(section?.title).toBe("Hauptdaten");
+    expect(section?.columns).toBe(1); // default
+    expect(section?.fields).toEqual([
+      {
+        field: "customerName",
+        label: "orders:entity:order:field:customerName",
+        type: "text",
+        value: "Acme",
+        visible: true,
+        readOnly: false,
+        required: true, // from entity
+      },
+      {
+        field: "notes",
+        label: "orders:entity:order:field:notes",
+        type: "text",
+        value: "VIP",
+        visible: true,
+        readOnly: false,
+        required: false,
+      },
+    ]);
+  });
+
+  test("section.columns override is respected; defaults to 1 when absent", () => {
+    const vm = computeEditViewModel({
+      screen: editScreen({
+        sections: [
+          { title: "Main", columns: 2, fields: ["customerName"] },
+          { title: "Notes", fields: ["notes"] },
+        ],
+      }),
+      entity: orderEntity,
+      values: {},
+      translate,
+      featureName: "orders",
+    });
+
+    expect(vm.sections[0]?.columns).toBe(2);
+    expect(vm.sections[1]?.columns).toBe(1);
+  });
+
+  test("visible predicate evaluated against current values (live-reactive)", () => {
+    const screen = editScreen({
+      sections: [
+        {
+          title: "VAT",
+          fields: [
+            "vatExempt",
+            {
+              field: "vatReason",
+              // Only visible when VAT is exempt.
+              visible: (data) => (data as { vatExempt?: boolean }).vatExempt === true,
+              required: (data) => (data as { vatExempt?: boolean }).vatExempt === true,
+            },
+          ],
+        },
+      ],
+    });
+
+    const hidden = computeEditViewModel({
+      screen,
+      entity: orderEntity,
+      values: { vatExempt: false },
+      translate,
+      featureName: "orders",
+    });
+    const reasonHidden = hidden.sections[0]?.fields[1];
+    expect(reasonHidden?.visible).toBe(false);
+    expect(reasonHidden?.required).toBe(false);
+
+    const shown = computeEditViewModel({
+      screen,
+      entity: orderEntity,
+      values: { vatExempt: true },
+      translate,
+      featureName: "orders",
+    });
+    const reasonShown = shown.sections[0]?.fields[1];
+    expect(reasonShown?.visible).toBe(true);
+    expect(reasonShown?.required).toBe(true);
+  });
+
+  test("readonly predicate receives ctx and evaluates per snapshot", () => {
+    const screen = editScreen({
+      sections: [
+        {
+          title: "x",
+          fields: [
+            {
+              field: "customerName",
+              readOnly: (_d, ctx) => (ctx as { isAdmin: boolean }).isAdmin === false,
+            },
+          ],
+        },
+      ],
+    });
+
+    const nonAdmin = computeEditViewModel({
+      screen,
+      entity: orderEntity,
+      values: { customerName: "A" },
+      ctx: { isAdmin: false },
+      translate,
+      featureName: "orders",
+    });
+    expect(nonAdmin.sections[0]?.fields[0]?.readOnly).toBe(true);
+
+    const admin = computeEditViewModel({
+      screen,
+      entity: orderEntity,
+      values: { customerName: "A" },
+      ctx: { isAdmin: true },
+      translate,
+      featureName: "orders",
+    });
+    expect(admin.sections[0]?.fields[0]?.readOnly).toBe(false);
+  });
+
+  test("screen-level required override wins over entity-level required", () => {
+    // customerName is required:true on the entity. Screen marks it
+    // required:false — a short-form wizard might collect less up-front.
+    const vm = computeEditViewModel({
+      screen: editScreen({
+        sections: [
+          {
+            title: "x",
+            fields: [{ field: "customerName", required: () => false }],
+          },
+        ],
+      }),
+      entity: orderEntity,
+      values: {},
+      translate,
+      featureName: "orders",
+    });
+
+    expect(vm.sections[0]?.fields[0]?.required).toBe(false);
+  });
+
+  test("id is extracted from values or null on create (no existing row)", () => {
+    const create = computeEditViewModel({
+      screen: editScreen({ sections: [{ title: "x", fields: ["customerName"] }] }),
+      entity: orderEntity,
+      values: { customerName: "new" },
+      translate,
+      featureName: "orders",
+    });
+    expect(create.id).toBeNull();
+
+    const edit = computeEditViewModel({
+      screen: editScreen({ sections: [{ title: "x", fields: ["customerName"] }] }),
+      entity: orderEntity,
+      values: { id: "o-1", customerName: "existing" },
+      translate,
+      featureName: "orders",
+    });
+    expect(edit.id).toBe("o-1");
+  });
+
+  test("unknown field in a section throws — no silent-ignore of a typo", () => {
+    expect(() =>
+      computeEditViewModel({
+        screen: editScreen({ sections: [{ title: "x", fields: ["ghost"] }] }),
+        entity: orderEntity,
+        values: {},
+        translate,
+        featureName: "orders",
+      }),
+    ).toThrow(/unknown field "ghost"/);
+  });
+
+  test("slots pass through for the renderer to mount", () => {
+    const slots = { header: { react: "H" } };
+    const vm = computeEditViewModel({
+      screen: editScreen({ sections: [{ title: "x", fields: ["customerName"] }] }, { slots }),
+      entity: orderEntity,
+      values: {},
+      translate,
+      featureName: "orders",
+    });
+    expect(vm.slots).toBe(slots);
+  });
+
+  test("span on field-spec propagates to the view model", () => {
+    const vm = computeEditViewModel({
+      screen: editScreen({
+        sections: [{ title: "x", columns: 3, fields: [{ field: "customerName", span: 2 }] }],
+      }),
+      entity: orderEntity,
+      values: {},
+      translate,
+      featureName: "orders",
+    });
+    expect(vm.sections[0]?.fields[0]?.span).toBe(2);
+  });
+});

package/src/view-model/__tests__/list.test.ts

@@ -0,0 +1,139 @@
+import type {
+  EntityDefinition,
+  EntityListScreenDefinition,
+} from "@cosmicdrift/kumiko-framework/ui-types";
+import { describe, expect, test, vi } from "vitest";
+import { computeListViewModel } from "../list";
+
+// Minimal EntityDefinition-shape. ui-core's view-model only reads
+// entity.fields and per-field metadata; tests stay untyped-casted via
+// `as unknown as EntityDefinition` so we don't pull the entire framework
+// FieldDefinition union into fixtures.
+const taskEntity = {
+  fields: {
+    title: { type: "text", required: true, sortable: true },
+    done: { type: "boolean" },
+    priority: { type: "number", sortable: true },
+  },
+} as unknown as EntityDefinition;
+
+function listScreen(columns: EntityListScreenDefinition["columns"]): EntityListScreenDefinition {
+  return {
+    id: "tasks:screen:task-list",
+    type: "entityList",
+    entity: "task",
+    columns,
+  };
+}
+
+// Fake translate passes the key through so tests can assert on the
+// key-composition convention without wiring i18next.
+const translate = (key: string) => key;
+
+describe("computeListViewModel", () => {
+  test("string columns expand to field-name + resolved label + type", () => {
+    const vm = computeListViewModel({
+      screen: listScreen(["title", "done"]),
+      entity: taskEntity,
+      rows: [],
+      translate,
+      featureName: "tasks",
+    });
+
+    expect(vm.columns).toEqual([
+      {
+        field: "title",
+        label: "tasks:entity:task:field:title",
+        type: "text",
+        sortable: true,
+      },
+      {
+        field: "done",
+        label: "tasks:entity:task:field:done",
+        type: "boolean",
+        sortable: false,
+      },
+    ]);
+  });
+
+  test("object-form column carries renderer through to the view model", () => {
+    const fmt = (v: unknown) => `${v} !`;
+    const vm = computeListViewModel({
+      screen: listScreen([{ field: "title", renderer: fmt }]),
+      entity: taskEntity,
+      rows: [],
+      translate,
+      featureName: "tasks",
+    });
+
+    expect(vm.columns[0]?.renderer).toBe(fmt);
+  });
+
+  test("rows map to { id, values } with id pulled from the row", () => {
+    const vm = computeListViewModel({
+      screen: listScreen(["title"]),
+      entity: taskEntity,
+      rows: [
+        { id: "t-1", title: "first" },
+        { id: "t-2", title: "second" },
+      ],
+      translate,
+      featureName: "tasks",
+    });
+
+    expect(vm.rows).toEqual([
+      { id: "t-1", values: { id: "t-1", title: "first" } },
+      { id: "t-2", values: { id: "t-2", title: "second" } },
+    ]);
+    expect(vm.isEmpty).toBe(false);
+  });
+
+  test("empty rows list flags isEmpty for the renderer's 'no results' state", () => {
+    const vm = computeListViewModel({
+      screen: listScreen(["title"]),
+      entity: taskEntity,
+      rows: [],
+      translate,
+      featureName: "tasks",
+    });
+    expect(vm.isEmpty).toBe(true);
+  });
+
+  test("unknown field reference throws — stale rename caught at render-time, not silently", () => {
+    expect(() =>
+      computeListViewModel({
+        screen: listScreen(["doesNotExist"]),
+        entity: taskEntity,
+        rows: [],
+        translate,
+        featureName: "tasks",
+      }),
+    ).toThrow(/unknown field "doesNotExist"/);
+  });
+
+  test("translate is called with the expected i18n-key per field", () => {
+    const spy = vi.fn((key: string) => `T:${key}`);
+    computeListViewModel({
+      screen: listScreen(["title", "priority"]),
+      entity: taskEntity,
+      rows: [],
+      translate: spy,
+      featureName: "tasks",
+    });
+
+    expect(spy).toHaveBeenCalledWith("tasks:entity:task:field:title");
+    expect(spy).toHaveBeenCalledWith("tasks:entity:task:field:priority");
+  });
+
+  test("slots pass through unchanged for the renderer to mount", () => {
+    const slots = { header: { react: { component: "HeaderRef" } } };
+    const vm = computeListViewModel({
+      screen: { ...listScreen(["title"]), slots },
+      entity: taskEntity,
+      rows: [],
+      translate,
+      featureName: "tasks",
+    });
+    expect(vm.slots).toBe(slots);
+  });
+});