@cosmicdrift/kumiko-headless 0.1.0

package/src/dispatcher/types.ts

@@ -0,0 +1,194 @@
+// Dispatcher Contract — the interface every client-side Dispatcher implements.
+// Two implementations ship with Kumiko:
+//
+//   - dispatcher-live: HTTP-only, always online. Writes go straight to
+//     /api/write or /api/batch; a failed network call is a failed write.
+//     Used on the web by default and on mobile when the app is "cockpit"-
+//     style (admin dashboards, back-office UIs).
+//
+//   - dispatcher-savable: Local-first with an outbound queue. Writes land
+//     in a local store, the queue syncs when the network is back. Used on
+//     mobile and for PWA-style web apps.
+//
+// The UI code never reaches for either implementation directly — it takes
+// a `Dispatcher` through a provider/context and calls `write` / `query` /
+// `batch`. A feature-module can therefore be rendered identically on a
+// live-online admin screen and on a mobile app that edits offline; the
+// dispatcher choice is an app-level concern, not a feature-level one.
+//
+// Result shape: `{ isSuccess: true, data } | { isSuccess: false, error }`.
+// Pattern matches the server's WriteResult but does not import it — this
+// package stays free of @cosmicdrift/kumiko-framework so it runs in any JS runtime
+// (browser, Expo/React Native, Web Worker). The HTTP dispatcher adapts
+// the server response to this shape; the savable dispatcher synthesizes
+// it from its own state machine. The shape is the boundary, not the
+// internal detail.
+
+// ---------------------------------------------------------------------------
+// Result envelopes
+// ---------------------------------------------------------------------------
+
+// A validation failure issue pinned to a specific payload field. Paths follow
+// the same dotted convention the server uses (see kumiko errors/classes.ts),
+// so form-controllers can map `tasks.2.title` back to the right sub-line's
+// input without any translation.
+import type { Store } from "../store";
+
+export type FieldIssue = {
+  readonly path: string;
+  readonly code: string;
+  readonly i18nKey: string;
+  readonly params?: Readonly<Record<string, unknown>>;
+};
+
+// Everything the UI needs to show or retry a failed call. `code` + `httpStatus`
+// are the structured hooks (Toast picks icon/colour, Form-Controller filters
+// field-level failures); `message` is the fallback for logs + generic toasts.
+// `details.fields` is populated for validation errors — other error classes
+// leave it undefined and callers treat the failure as a toast.
+export type DispatcherError = {
+  readonly code: string;
+  readonly httpStatus: number;
+  readonly i18nKey: string;
+  readonly i18nParams?: Readonly<Record<string, unknown>>;
+  readonly message: string;
+  readonly details?: {
+    readonly fields?: readonly FieldIssue[];
+  } & Record<string, unknown>;
+  // Self-service deep-link to docs.kumiko.so/errors/<reason>. Always set on
+  // server-side errors (computed from details.reason or code by KumikoError).
+  // Optional only because client-synthesized errors (network drop, savable-
+  // queue rejection before transport) can't compute a meaningful docs URL.
+  readonly docsUrl?: string;
+  // Server-assigned id for log correlation; missing on client-synthesized
+  // errors (network drop, savable-queue rejection before transport).
+  readonly requestId?: string;
+};
+
+export type WriteResult<TData = unknown> =
+  | { readonly isSuccess: true; readonly data: TData }
+  | { readonly isSuccess: false; readonly error: DispatcherError };
+
+export type QueryResult<TData = unknown> =
+  | { readonly isSuccess: true; readonly data: TData }
+  | { readonly isSuccess: false; readonly error: DispatcherError };
+
+// Batch returns an array of per-command results plus the index of the first
+// failure (if any). Matches the server's BatchResult so callers can inspect
+// partial progress before the rollback in a failed batch.
+export type BatchResult =
+  | { readonly isSuccess: true; readonly results: readonly WriteResult[] }
+  | {
+      readonly isSuccess: false;
+      readonly error: DispatcherError;
+      readonly failedIndex: number;
+      readonly results: readonly WriteResult[];
+    };
+
+// ---------------------------------------------------------------------------
+// Commands
+// ---------------------------------------------------------------------------
+
+// One entry in a batch. `type` is the qualified handler name
+// (`feature:write:entity:action`). `payload` is the handler's input — shape
+// is declared by the feature author's zod schema on the server, so this
+// stays generic here. Nested-write payloads (parent + hasMany children in a
+// single object) travel through as-is; the server expands them.
+export type Command = {
+  readonly type: string;
+  readonly payload: unknown;
+};
+
+// ---------------------------------------------------------------------------
+// Status + pending queues
+// ---------------------------------------------------------------------------
+
+// "online"  — transport reachable, writes/queries go through synchronously.
+// "offline" — transport unreachable; savable queues, live fails immediately.
+// "syncing" — savable's catch-up window after reconnect (queue draining).
+//             live-dispatcher never reports "syncing" — nothing to catch up.
+export type DispatcherStatus = "online" | "offline" | "syncing";
+
+// What the UI shows as "N changes waiting" badges. Both entries hold enough
+// context for a user-facing list ("Task 'Buy milk' – retry? / discard?");
+// the dispatcher itself drives the retry/sync — this is read-only for
+// rendering.
+export type PendingWrite = {
+  readonly id: string;
+  readonly type: string;
+  readonly payload: unknown;
+  // Optimistic snapshot of when the user clicked submit, so the UI can show
+  // "3 min ago" without reaching for the internal queue's timestamps.
+  readonly queuedAt: string;
+  readonly attempts: number;
+  readonly lastError?: DispatcherError;
+};
+
+export type PendingFile = {
+  readonly id: string;
+  readonly fileName: string;
+  readonly sizeBytes: number;
+  readonly queuedAt: string;
+  readonly attempts: number;
+  readonly progress?: number; // 0..1 when uploading; undefined when queued
+  readonly lastError?: DispatcherError;
+};
+
+// ---------------------------------------------------------------------------
+// Call-site options
+// ---------------------------------------------------------------------------
+
+export type WriteOpts = {
+  // Client-generated idempotency key — server dedupes and returns the
+  // cached result on retry. Required for any write a user can trigger
+  // twice (double-click submits, connection-retry in savable).
+  readonly requestId?: string;
+  // Abort handle — the UI cancels a stale submit when the screen changes
+  // or the user presses Escape. Live-dispatcher passes this through to
+  // fetch; savable-dispatcher removes the entry from its queue.
+  readonly signal?: AbortSignal;
+};
+
+export type QueryOpts = {
+  readonly signal?: AbortSignal;
+};
+
+// ---------------------------------------------------------------------------
+// The contract
+// ---------------------------------------------------------------------------
+
+// Every client-side dispatcher implements this interface. Hooks
+// (`useMutation`, `useCommand`) take it via provider/context; features don't
+// know or care which concrete dispatcher they run against. Adding a new
+// dispatcher (e.g. a server-sent dispatcher for SSR prefetch) means
+// implementing this interface — no changes to feature code.
+export type Dispatcher = {
+  write<TData = unknown>(
+    type: string,
+    payload: unknown,
+    opts?: WriteOpts,
+  ): Promise<WriteResult<TData>>;
+
+  query<TData = unknown>(
+    type: string,
+    payload: unknown,
+    opts?: QueryOpts,
+  ): Promise<QueryResult<TData>>;
+
+  batch(commands: readonly Command[], opts?: WriteOpts): Promise<BatchResult>;
+
+  // --- Status ---
+
+  // Subscribe/Emit-Store für Online/Offline/Syncing-Transitions. Konsumenten
+  // greifen direkt mit `useStore(dispatcher.statusStore)` zu — keine eigenen
+  // status()/subscribe()-Wrapper, der Store ist die ganze API.
+  // `Store` (read-only): UI darf den Status NICHT setzen, das ist
+  // Dispatcher-intern. Live-Dispatcher hält intern eine WritableStore-Ref,
+  // exportiert aber nur den Read-View.
+  readonly statusStore: Store<DispatcherStatus>;
+
+  // --- Pending queues (only meaningful for savable; live returns []) ---
+
+  pendingWrites(): readonly PendingWrite[];
+  pendingFiles(): readonly PendingFile[];
+};

package/src/form/__tests__/conditional-fields.test.ts

@@ -0,0 +1,177 @@
+import { describe, expect, test } from "vitest";
+import { z } from "zod";
+import { createFormController } from "../form-controller";
+
+describe("conditional fields — FieldState resolution", () => {
+  test("unlisted fields get the default {visible:true, readonly:false, required:false}", () => {
+    const form = createFormController({ initial: { title: "hello" } });
+    const snap = form.getSnapshot();
+
+    // No rules declared → snapshot.fields is empty. Renderer treats
+    // missing keys as defaults.
+    expect(snap.fields).toEqual({});
+  });
+
+  test("static boolean condition resolves once at snapshot time", () => {
+    const form = createFormController({
+      initial: { title: "" },
+      fields: {
+        title: { visible: true, readonly: true, required: true },
+      },
+    });
+
+    expect(form.getSnapshot().fields["title"]).toEqual({
+      visible: true,
+      readonly: true,
+      required: true,
+    });
+  });
+
+  test("predicate condition gets current values", () => {
+    const form = createFormController<{ type: "a" | "b"; extra: string }>({
+      initial: { type: "a", extra: "" },
+      fields: {
+        extra: {
+          // "extra" is only required when type === "b"
+          required: (values) => values.type === "b",
+          visible: (values) => values.type === "b",
+        },
+      },
+    });
+
+    expect(form.getSnapshot().fields["extra"]).toEqual({
+      visible: false,
+      readonly: false,
+      required: false,
+    });
+
+    form.setField("type", "b");
+
+    expect(form.getSnapshot().fields["extra"]).toEqual({
+      visible: true,
+      readonly: false,
+      required: true,
+    });
+  });
+
+  test("predicate reads ctx for cross-cutting conditions (tenant, role)", () => {
+    type Ctx = { readonly isAdmin: boolean };
+    const form = createFormController<{ title: string }, Ctx>({
+      initial: { title: "" },
+      fields: {
+        title: {
+          readonly: (_values, ctx) => !ctx.isAdmin,
+        },
+      },
+      ctx: { isAdmin: false },
+    });
+
+    expect(form.getSnapshot().fields["title"]?.readonly).toBe(true);
+
+    form.setCtx({ isAdmin: true });
+
+    expect(form.getSnapshot().fields["title"]?.readonly).toBe(false);
+  });
+
+  test("setCtx: predicate re-reads ctx on the next snapshot (not captured-at-create)", () => {
+    // Regression guard: a future "cache predicates for perf" refactor could
+    // bind the ctx into the predicate at create-time instead of calling it
+    // fresh each buildSnapshot. If that happens, setCtx would fire a
+    // notification but the predicate would still see the old ctx. This
+    // test asserts the predicate actually reads the new ctx value after
+    // setCtx — the notification alone isn't enough.
+    type Ctx = { readonly role: "user" | "admin" };
+    let lastCtxSeen: string | null = null;
+    const form = createFormController<{ title: string }, Ctx>({
+      initial: { title: "" },
+      fields: {
+        title: {
+          readonly: (_v, ctx) => {
+            lastCtxSeen = ctx.role;
+            return ctx.role !== "admin";
+          },
+        },
+      },
+      ctx: { role: "user" },
+    });
+
+    // Force a snapshot build so the predicate runs once.
+    form.getSnapshot();
+    expect(lastCtxSeen).toBe("user");
+
+    form.setCtx({ role: "admin" });
+    form.getSnapshot();
+
+    // The predicate must have been re-called AND observed the new ctx.
+    expect(lastCtxSeen).toBe("admin");
+  });
+
+  test("setCtx produces a new snapshot and notifies listeners", () => {
+    const form = createFormController<{ title: string }, { readonly role: string }>({
+      initial: { title: "" },
+      fields: {
+        title: { readonly: (_v, ctx) => ctx.role !== "admin" },
+      },
+      ctx: { role: "user" },
+    });
+
+    const before = form.getSnapshot();
+    form.setCtx({ role: "admin" });
+
+    expect(form.getSnapshot()).not.toBe(before);
+    expect(form.getSnapshot().fields["title"]?.readonly).toBe(false);
+  });
+
+  test("hidden fields are excluded from validate() — required:false for hidden works as expected", () => {
+    // A hidden field with required:true on its schema should NOT fail
+    // validation. The user isn't shown the field, so they can't satisfy
+    // it — forcing them to is a UX footgun.
+    const schema = z.object({
+      type: z.enum(["a", "b"]),
+      extra: z.string().min(1), // required in schema
+    });
+
+    const form = createFormController<{ type: "a" | "b"; extra: string }>({
+      initial: { type: "a", extra: "" },
+      schema,
+      fields: {
+        extra: {
+          // Hidden when type !== "b"
+          visible: (v) => v.type === "b",
+        },
+      },
+    });
+
+    // type="a" → extra hidden → even with empty `extra`, validate() succeeds.
+    expect(form.validate()).toBe(true);
+
+    form.setField("type", "b");
+    // type="b" → extra visible → empty value now fails.
+    expect(form.validate()).toBe(false);
+    expect(form.getSnapshot().errors["extra"]).toBeDefined();
+  });
+
+  test("snapshot.fields resolves after each setField call (live-reactive)", () => {
+    let predicateCalls = 0;
+    const form = createFormController<{ type: "a" | "b"; extra: string }>({
+      initial: { type: "a", extra: "" },
+      fields: {
+        extra: {
+          visible: (v) => {
+            predicateCalls++;
+            return v.type === "b";
+          },
+        },
+      },
+    });
+
+    form.getSnapshot(); // build 1
+    form.setField("type", "b"); // build 2
+    form.getSnapshot(); // still build 2 (identity preserved)
+    form.getSnapshot();
+
+    // Snapshot is cached — predicate only runs on mutator-driven rebuilds,
+    // not on every getSnapshot().
+    expect(predicateCalls).toBeLessThanOrEqual(3); // initial + 1 mutation + possibly 1 buffer
+  });
+});

package/src/form/__tests__/form-controller.test.ts

@@ -0,0 +1,195 @@
+import { describe, expect, test, vi } from "vitest";
+import { createFormController } from "../form-controller";
+
+describe("createFormController — core state machine", () => {
+  test("initial state: values === initial, no changes, not dirty, no errors", () => {
+    const form = createFormController({ initial: { title: "hello", count: 3 } });
+    const snap = form.getSnapshot();
+
+    expect(snap.values).toEqual({ title: "hello", count: 3 });
+    expect(snap.initial).toEqual({ title: "hello", count: 3 });
+    expect(snap.changes).toEqual({});
+    expect(snap.isDirty).toBe(false);
+    expect(snap.isUnchanged).toBe(true);
+    expect(snap.errors).toEqual({});
+  });
+
+  test("setField: tracks the single-field change and flips isDirty", () => {
+    const form = createFormController({ initial: { title: "hello", count: 3 } });
+
+    form.setField("title", "world");
+    const snap = form.getSnapshot();
+
+    expect(snap.values.title).toBe("world");
+    expect(snap.values.count).toBe(3);
+    expect(snap.initial.title).toBe("hello"); // baseline unchanged
+    expect(snap.changes).toEqual({ title: "world" });
+    expect(snap.isDirty).toBe(true);
+    expect(snap.isUnchanged).toBe(false);
+  });
+
+  test("setField to same value is a no-op: no new snapshot, no listener fires", () => {
+    const form = createFormController({ initial: { title: "hello" } });
+    const before = form.getSnapshot();
+    const listener = vi.fn();
+    form.subscribe(listener);
+
+    form.setField("title", "hello");
+
+    expect(form.getSnapshot()).toBe(before); // identity preserved
+    expect(listener).not.toHaveBeenCalled();
+  });
+
+  test("typing back to the initial value clears the change from `changes`", () => {
+    const form = createFormController({ initial: { title: "hello" } });
+
+    form.setField("title", "world");
+    expect(form.getSnapshot().changes).toEqual({ title: "world" });
+
+    form.setField("title", "hello");
+    const snap = form.getSnapshot();
+    expect(snap.changes).toEqual({});
+    expect(snap.isDirty).toBe(false);
+  });
+
+  test("setValues: bulk update fires one notify, one snapshot rebuild", () => {
+    const form = createFormController({ initial: { a: 1, b: 2, c: 3 } });
+    const listener = vi.fn();
+    form.subscribe(listener);
+
+    form.setValues({ a: 10, b: 20 });
+
+    expect(form.getSnapshot().changes).toEqual({ a: 10, b: 20 });
+    expect(listener).toHaveBeenCalledTimes(1); // not 2
+  });
+
+  test("setValues with no effective changes is a no-op", () => {
+    const form = createFormController({ initial: { a: 1, b: 2 } });
+    const before = form.getSnapshot();
+    const listener = vi.fn();
+    form.subscribe(listener);
+
+    form.setValues({ a: 1 });
+
+    expect(form.getSnapshot()).toBe(before);
+    expect(listener).not.toHaveBeenCalled();
+  });
+
+  test("subscribe/unsubscribe: listener stops firing after unsubscribe", () => {
+    const form = createFormController({ initial: { title: "hello" } });
+    const listener = vi.fn();
+    const unsubscribe = form.subscribe(listener);
+
+    form.setField("title", "world");
+    expect(listener).toHaveBeenCalledTimes(1);
+
+    unsubscribe();
+    form.setField("title", "again");
+    expect(listener).toHaveBeenCalledTimes(1); // still 1
+  });
+
+  test("getSnapshot returns stable reference between mutators", () => {
+    const form = createFormController({ initial: { title: "hello" } });
+
+    const a = form.getSnapshot();
+    const b = form.getSnapshot();
+    expect(a).toBe(b); // identity compare — required for useSyncExternalStore
+
+    form.setField("title", "world");
+    const c = form.getSnapshot();
+    expect(c).not.toBe(a); // mutation produced a new snapshot
+  });
+
+  test("snapshot is frozen — mutating it throws in strict mode", () => {
+    const form = createFormController({ initial: { title: "hello" } });
+    const snap = form.getSnapshot();
+
+    expect(() => {
+      (snap as unknown as { values: unknown }).values = {};
+    }).toThrow();
+  });
+
+  test("reset: restores values to initial and clears errors", () => {
+    const form = createFormController({ initial: { title: "hello", count: 3 } });
+    form.setField("title", "world");
+    form.setErrors({ title: [{ path: "title", code: "bad", i18nKey: "x" }] });
+
+    form.reset();
+    const snap = form.getSnapshot();
+
+    expect(snap.values).toEqual({ title: "hello", count: 3 });
+    expect(snap.isDirty).toBe(false);
+    expect(snap.errors).toEqual({});
+  });
+
+  test("reset is a no-op when already clean and error-free", () => {
+    const form = createFormController({ initial: { title: "hello" } });
+    const before = form.getSnapshot();
+    const listener = vi.fn();
+    form.subscribe(listener);
+
+    form.reset();
+
+    expect(form.getSnapshot()).toBe(before);
+    expect(listener).not.toHaveBeenCalled();
+  });
+
+  test("rebase: current values become the new baseline, changes collapse to {}", () => {
+    const form = createFormController({ initial: { title: "hello" } });
+    form.setField("title", "world");
+    expect(form.getSnapshot().changes).toEqual({ title: "world" });
+
+    form.rebase();
+    const snap = form.getSnapshot();
+
+    expect(snap.values.title).toBe("world");
+    expect(snap.initial.title).toBe("world"); // baseline updated
+    expect(snap.changes).toEqual({});
+    expect(snap.isDirty).toBe(false);
+  });
+
+  test("setErrors + clearErrors(path): targeted removal leaves other errors alone", () => {
+    const form = createFormController({ initial: { a: "", b: "" } });
+    form.setErrors({
+      a: [{ path: "a", code: "required", i18nKey: "x" }],
+      b: [{ path: "b", code: "required", i18nKey: "x" }],
+    });
+
+    form.clearErrors("a");
+    const snap = form.getSnapshot();
+
+    expect(snap.errors["a"]).toBeUndefined();
+    expect(snap.errors["b"]).toBeDefined();
+  });
+
+  test("clearErrors() without path wipes everything", () => {
+    const form = createFormController({ initial: { a: "" } });
+    form.setErrors({ a: [{ path: "a", code: "required", i18nKey: "x" }] });
+
+    form.clearErrors();
+
+    expect(form.getSnapshot().errors).toEqual({});
+  });
+
+  test("mutating the input object after create does not bleed into controller state", () => {
+    const initial = { title: "hello" };
+    const form = createFormController({ initial });
+
+    initial.title = "mutated-from-outside";
+
+    expect(form.getSnapshot().initial.title).toBe("hello");
+    expect(form.getSnapshot().values.title).toBe("hello");
+  });
+
+  test("deleted field via setValues({ key: undefined }) still counts as a change", () => {
+    // Covers the both-sides iteration in valuesDiff — a field cleared from
+    // the current values still diverges from initial and shows up in changes.
+    const form = createFormController({ initial: { title: "hello" } });
+    form.setValues({ title: undefined });
+
+    const snap = form.getSnapshot();
+    expect(snap.isDirty).toBe(true);
+    expect("title" in snap.changes).toBe(true);
+    expect(snap.changes["title"]).toBeUndefined();
+  });
+});