@cosmicdrift/kumiko-headless 0.1.0

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@cosmicdrift/kumiko-headless",
+  "version": "0.1.0",
+  "description": "Headless UI logic for Kumiko — Dispatcher contract, Form-Controller, View-Model, Nav-Resolver. Plattform- und React-frei; jeder Renderer (renderer, renderer-web, renderer-native, …) komponiert darauf.",
+  "license": "BUSL-1.1",
+  "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/cosmicdriftgamestudio/kumiko-framework.git",
+    "directory": "packages/headless"
+  },
+  "bugs": {
+    "url": "https://github.com/cosmicdriftgamestudio/kumiko-framework/issues"
+  },
+  "homepage": "https://kumiko.so",
+  "type": "module",
+  "kumiko": {
+    "runtime": "client"
+  },
+  "exports": {
+    ".": "./src/index.ts",
+    "./dispatcher": "./src/dispatcher/index.ts"
+  },
+  "dependencies": {
+    "@cosmicdrift/kumiko-framework": "workspace:*",
+    "zod": "^4.3.6"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ]
+}

package/src/contracts/__tests__/contracts.test.ts

@@ -0,0 +1,123 @@
+import { describe, expect, test, vi } from "vitest";
+import type {
+  AssetResolver,
+  ButtonProps,
+  LocaleResolver,
+  PrimitiveCommonProps,
+  PrimitivesContract,
+  SelectProps,
+  TextInputProps,
+} from "../index";
+
+// These aren't unit tests — they're compile-time contract guards in
+// runtime clothing. Building a small fake that satisfies each contract
+// ensures a future refactor that drops or renames a required field
+// breaks here loudly instead of in some downstream renderer.
+
+describe("Asset / Locale / Primitives contracts", () => {
+  test("AssetResolver — a minimal in-memory resolver compiles and runs", () => {
+    const table = new Map<string, { uri: string; alt?: string }>([
+      ["app:asset:logo", { uri: "/static/logo.svg", alt: "Kumiko" }],
+    ]);
+    const resolver: AssetResolver = {
+      resolve(qn) {
+        const found = table.get(qn);
+        return found ? { uri: found.uri, alt: found.alt } : null;
+      },
+    };
+
+    expect(resolver.resolve("app:asset:logo")?.uri).toBe("/static/logo.svg");
+    expect(resolver.resolve("app:asset:missing")).toBeNull();
+  });
+
+  test("LocaleResolver — subscribe/unsubscribe + translate with params", () => {
+    const listeners = new Set<() => void>();
+    const resolver: LocaleResolver = {
+      translate(key, params) {
+        // Minimal translation: "errors.value.minimum" + {min:3} → "≥3"
+        if (key === "errors.value.minimum" && params?.["min"] !== undefined) {
+          return `≥${params["min"]}`;
+        }
+        return key;
+      },
+      locale: () => "de-AT",
+      timeZone: () => "Europe/Vienna",
+      subscribe(listener) {
+        listeners.add(listener);
+        return () => listeners.delete(listener);
+      },
+    };
+
+    expect(resolver.translate("errors.value.minimum", { min: 3 })).toBe("≥3");
+    expect(resolver.locale()).toBe("de-AT");
+
+    const listener = vi.fn();
+    const unsubscribe = resolver.subscribe(listener);
+    for (const l of listeners) l();
+    expect(listener).toHaveBeenCalledTimes(1);
+    unsubscribe();
+    for (const l of listeners) l();
+    expect(listener).toHaveBeenCalledTimes(1);
+  });
+
+  test("PrimitivesContract — a fake renderer's primitives satisfy the type", () => {
+    // The renderer-side wiring creates a concrete object where each
+    // member is a component. From ui-core's vantage they're opaque
+    // values typed as `unknown` — we only care that all 11 keys are
+    // present.
+    const primitives: PrimitivesContract = {
+      TextInput: { kind: "text-input" },
+      NumberInput: { kind: "number-input" },
+      Select: { kind: "select" },
+      Toggle: { kind: "toggle" },
+      DatePicker: { kind: "date-picker" },
+      Button: { kind: "button" },
+      Modal: { kind: "modal" },
+      Toast: { kind: "toast" },
+      Badge: { kind: "badge" },
+      Card: { kind: "card" },
+      Icon: { kind: "icon" },
+    };
+
+    // Exhaustiveness — missing a key means the contract drifted without
+    // updating this test (and, by implication, every primitives-* impl).
+    expect(Object.keys(primitives)).toHaveLength(11);
+  });
+
+  test("PrimitiveCommonProps propagate to concrete props (TextInput, Select, Button)", () => {
+    // Compile-time assertion: PrimitiveCommonProps members narrow correctly
+    // on each derived prop type. Runtime side just checks the object
+    // shape we'd hand to a primitive component.
+    const textProps: TextInputProps = {
+      id: "title",
+      name: "title",
+      disabled: false,
+      readOnly: false,
+      required: true,
+      label: "Title",
+      value: "hello",
+      onChange: () => {},
+      type: "text",
+    };
+    const selectProps: SelectProps<"a" | "b"> = {
+      label: "Pick one",
+      value: "a",
+      onChange: () => {},
+      options: [
+        { value: "a", label: "A" },
+        { value: "b", label: "B" },
+      ],
+    };
+    const buttonProps: ButtonProps = {
+      label: "Save",
+      onPress: () => {},
+      variant: "primary",
+    };
+
+    const common: PrimitiveCommonProps = { label: "Title" };
+    expect(common.label).toBe("Title");
+    expect(textProps.value).toBe("hello");
+    expect(selectProps.options).toHaveLength(2);
+    expect(buttonProps.variant).toBe("primary");
+  });
+});

package/src/contracts/asset.ts

@@ -0,0 +1,48 @@
+// Asset-Resolver — the layer between "qualified asset name" and "URL the
+// renderer can point an <img>/<Image> at". An asset (logo, illustration,
+// icon bundle) is declared by a feature with a qualified name
+// ("admin:asset:hero-logo") and resolved at render-time against the
+// current tenant / theme / platform.
+//
+// Why a resolver indirection:
+//   - Tenant-theming (different logo per tenant) without the feature
+//     knowing what tenant it's rendering for.
+//   - Dark-mode / light-mode variants picked up from the current theme
+//     context.
+//   - Web vs mobile different asset bundles (e.g. PNG vs SVG).
+//
+// The app registers a concrete resolver on startup and hands it to the
+// renderer via context. Feature code calls `useAsset("admin:asset:logo")`
+// (renderer-side hook) → internally `AssetResolver.resolve(qn)`.
+
+// Render-context the resolver may consult. Everything here is optional;
+// the default resolver ignores fields it doesn't use.
+export type AssetResolveContext = {
+  readonly tenantId?: string;
+  readonly theme?: "light" | "dark";
+  readonly platform?: "web" | "ios" | "android";
+  readonly locale?: string;
+};
+
+export type AssetResolution = {
+  // Final URL / URI — web uses https://, Expo uses local file:// or
+  // remote https://, SSR may get a data: URI for inlined critical
+  // assets.
+  readonly uri: string;
+  // Optional pre-computed dimensions so the renderer can reserve layout
+  // space without a first-paint reflow (fixes the image-loads-then-
+  // layout-jumps UX on mobile).
+  readonly width?: number;
+  readonly height?: number;
+  // Alt-text to apply when the asset renders into an <img>. The i18n
+  // layer resolved it to a string before the resolver returned.
+  readonly alt?: string;
+};
+
+export type AssetResolver = {
+  // Returns null when the asset isn't known; renderer shows a fallback
+  // (missing-image placeholder) instead of crashing. Kumiko's standard
+  // renderer logs a warn when it sees null so features catch typos in
+  // the asset qualified name early.
+  resolve(qn: string, ctx?: AssetResolveContext): AssetResolution | null;
+};

package/src/contracts/index.ts

@@ -0,0 +1,23 @@
+export type {
+  AssetResolution,
+  AssetResolveContext,
+  AssetResolver,
+} from "./asset";
+export type { LocaleResolver } from "./locale";
+export type {
+  BadgeProps,
+  ButtonProps,
+  CardProps,
+  DatePickerProps,
+  IconProps,
+  ModalProps,
+  NumberInputProps,
+  PrimitiveCommonProps,
+  PrimitivesContract,
+  SelectOption,
+  SelectProps,
+  TextInputProps,
+  ToastIntent,
+  ToastProps,
+  ToggleProps,
+} from "./primitives";

package/src/contracts/locale.ts

@@ -0,0 +1,33 @@
+// Locale-Resolver — translation lookup + language/region info the
+// renderer needs. Sits in front of i18next (or whatever i18n library
+// the app wires up). ui-core calls it generically so form-controller,
+// view-model, and nav-resolver all produce already-translated strings
+// to hand to the renderer.
+//
+// The framework already has an i18n layer (@cosmicdrift/kumiko-framework/i18n) that
+// features register translations against. This contract is what ui-core
+// consumes — the app's entrypoint instantiates the resolver from a
+// framework i18next instance and passes it to the renderer via context.
+
+export type LocaleResolver = {
+  // Resolve an i18n key to a localized string. `params` are interpolated
+  // (`{name}` → params.name) — same semantics as i18next t().
+  translate(key: string, params?: Readonly<Record<string, unknown>>): string;
+  // Current locale in BCP-47 form (e.g. "de-AT", "en-US"). Feature code
+  // that does manual formatting (e.g. a custom number renderer) reads
+  // this instead of calling translate() on a placeholder.
+  locale(): string;
+  // Preferred time-zone for the current user. Time-zone-aware fields
+  // (Kumiko's locatedTimestamp) render in this zone unless the entity
+  // overrides it with a per-row locatedBy reference.
+  timeZone(): string;
+  // Subscribe to locale/timezone changes. Hooks (useTranslation) rely
+  // on this so a user switching language mid-session triggers a
+  // re-render across every subscribed consumer.
+  subscribe(listener: () => void): () => void;
+  // Optional — when present, the resolver is stateful and callers (like
+  // a language-picker UI) can trigger a locale change that will be
+  // broadcast via `subscribe`. Static resolvers (e.g. server-side
+  // render with a fixed locale) omit it.
+  setLocale?(locale: string): void;
+};

package/src/contracts/primitives.ts

@@ -0,0 +1,158 @@
+// Primitives-Contract — the minimal set of UI building blocks every
+// renderer must provide. A "primitive" is a unit the standard-renderers
+// (entityList, entityEdit, etc.) call into without knowing which library
+// implements it. On web that's shadcn; on mobile it's react-native-paper;
+// both packages (primitives-shadcn, primitives-paper) implement this
+// contract and the app wires one of them into the renderer via context.
+//
+// Why a contract here (in ui-core) instead of in each renderer:
+// ui-core's view-model builder and form-controller produce metadata
+// (field-type, validation-state, label, placeholder) that the renderer
+// translates into primitive invocations. Having the contract shape in
+// ui-core means the metadata can carry references to primitives by name
+// ("text-input", "select") and the translation is a pure map-lookup on
+// the renderer side, not a switch statement that re-derives UI intent
+// from entity-schema.
+//
+// Runtime-free: every primitive is expressed as its input contract only
+// (what props it takes). Concrete components live in each primitives-*
+// package and depend on React / React Native / etc.; ui-core never
+// imports them.
+
+// Common props every primitive accepts. Renderers pass down the
+// current field-state (visible/readonly/required from FormController)
+// through these — a primitive that honours them doesn't need to know
+// about Kumiko's form-controller, it just renders according to flags.
+export type PrimitiveCommonProps = {
+  readonly id?: string;
+  readonly name?: string;
+  readonly disabled?: boolean;
+  readonly readOnly?: boolean;
+  readonly required?: boolean;
+  // Accessible label / placeholder / helper text. These are already
+  // localized strings — the renderer resolves i18n keys via useTranslation
+  // before handing them to the primitive.
+  readonly label?: string;
+  readonly placeholder?: string;
+  readonly helperText?: string;
+  // One or more issue messages to display. Localised; the renderer
+  // picked them up from FormSnapshot.errors and ran them through
+  // i18n.
+  readonly errors?: readonly string[];
+};
+
+export type TextInputProps = PrimitiveCommonProps & {
+  readonly value: string;
+  readonly onChange: (next: string) => void;
+  readonly onBlur?: () => void;
+  readonly type?: "text" | "email" | "url" | "tel" | "password";
+  readonly maxLength?: number;
+  readonly autoComplete?: string;
+};
+
+export type NumberInputProps = PrimitiveCommonProps & {
+  readonly value: number | null;
+  readonly onChange: (next: number | null) => void;
+  readonly onBlur?: () => void;
+  readonly min?: number;
+  readonly max?: number;
+  readonly step?: number;
+};
+
+export type SelectOption<TValue extends string = string> = {
+  readonly value: TValue;
+  readonly label: string;
+};
+
+export type SelectProps<TValue extends string = string> = PrimitiveCommonProps & {
+  readonly value: TValue | null;
+  readonly onChange: (next: TValue | null) => void;
+  readonly options: readonly SelectOption<TValue>[];
+};
+
+export type ToggleProps = PrimitiveCommonProps & {
+  readonly value: boolean;
+  readonly onChange: (next: boolean) => void;
+};
+
+export type DatePickerProps = PrimitiveCommonProps & {
+  // ISO-8601 date string (YYYY-MM-DD) or null. The primitive translates
+  // to/from the native date widget on each platform; ui-core stays
+  // platform-free by using the serialized string form.
+  readonly value: string | null;
+  readonly onChange: (next: string | null) => void;
+  readonly minDate?: string;
+  readonly maxDate?: string;
+};
+
+// Container primitives — layout / feedback that renderers compose but
+// don't directly bind to a form field. Props stay minimal: anything that
+// feels like "more variants" (destructive button, soft button, ghost
+// button) gets a `variant` prop the primitive interprets.
+
+export type ButtonProps = {
+  readonly onPress: () => void;
+  readonly label: string;
+  readonly variant?: "primary" | "secondary" | "destructive" | "ghost";
+  readonly disabled?: boolean;
+  readonly loading?: boolean;
+  // Left/right icons addressed by name through the Icon primitive.
+  readonly leftIcon?: string;
+  readonly rightIcon?: string;
+};
+
+export type ModalProps = {
+  readonly open: boolean;
+  readonly onClose: () => void;
+  readonly title?: string;
+  readonly description?: string;
+};
+
+export type ToastIntent = "info" | "success" | "warning" | "error";
+export type ToastProps = {
+  readonly intent: ToastIntent;
+  readonly title: string;
+  readonly description?: string;
+  readonly onDismiss?: () => void;
+};
+
+export type BadgeProps = {
+  readonly label: string;
+  readonly intent?: ToastIntent;
+};
+
+export type CardProps = {
+  readonly title?: string;
+  readonly description?: string;
+};
+
+// Icons are referenced by string name so ui-core doesn't own an icon set.
+// primitives-shadcn maps "check" → `<Check />` from lucide-react;
+// primitives-paper maps "check" → `<Icon source="check" />`. The set of
+// names is deliberately open — renderer-level code can introduce feature-
+// specific icons without a ui-core round-trip.
+export type IconProps = {
+  readonly name: string;
+  readonly size?: number;
+};
+
+// The full contract. A primitives package implements each member — the
+// renderer consumes them from a single context object (PrimitivesProvider).
+// Adding a new primitive to the contract is a breaking change for all
+// primitives-* packages; removing one is not (renderers just stop using
+// it). Keep the surface small: something that only one or two renderers
+// need (masked input, signature pad, chart) should live in the feature
+// module, not here.
+export type PrimitivesContract<TPrimitive = unknown> = {
+  readonly TextInput: TPrimitive;
+  readonly NumberInput: TPrimitive;
+  readonly Select: TPrimitive;
+  readonly Toggle: TPrimitive;
+  readonly DatePicker: TPrimitive;
+  readonly Button: TPrimitive;
+  readonly Modal: TPrimitive;
+  readonly Toast: TPrimitive;
+  readonly Badge: TPrimitive;
+  readonly Card: TPrimitive;
+  readonly Icon: TPrimitive;
+};

package/src/dispatcher/__tests__/contract.test.ts

@@ -0,0 +1,160 @@
+import { describe, expect, test } from "vitest";
+import { createStore } from "../../store";
+import type {
+  BatchResult,
+  Command,
+  Dispatcher,
+  DispatcherStatus,
+  PendingFile,
+  PendingWrite,
+  QueryResult,
+  WriteResult,
+} from "../types";
+
+// A minimal fake dispatcher — proves the Dispatcher interface is sufficient
+// to implement a synchronous in-memory client, and pins the public shape of
+// WriteResult / QueryResult / BatchResult so a PR that renames or reshapes
+// a field breaks this file loud.
+//
+// The fake records every call, so the test can assert on the exact
+// sequence without re-exercising real HTTP. Block 2's form-controller uses
+// this fake as its default test double.
+function createFakeDispatcher(options?: {
+  readonly writeResponses?: Record<string, WriteResult>;
+  readonly queryResponses?: Record<string, QueryResult>;
+}): Dispatcher & {
+  readonly calls: ReadonlyArray<{
+    kind: "write" | "query" | "batch";
+    type?: string;
+    payload?: unknown;
+  }>;
+  setStatus(next: DispatcherStatus): void;
+} {
+  const calls: Array<{ kind: "write" | "query" | "batch"; type?: string; payload?: unknown }> = [];
+  const statusStore = createStore<DispatcherStatus>("online");
+  const pendingWritesStore: PendingWrite[] = [];
+  const pendingFilesStore: PendingFile[] = [];
+
+  return {
+    calls,
+    async write<TData>(type: string, payload: unknown) {
+      calls.push({ kind: "write", type, payload });
+      const response = options?.writeResponses?.[type];
+      return (response ?? {
+        isSuccess: true,
+        data: { id: `fake-${calls.length}` },
+      }) as WriteResult<TData>;
+    },
+    async query<TData>(type: string, payload: unknown) {
+      calls.push({ kind: "query", type, payload });
+      const response = options?.queryResponses?.[type];
+      return (response ?? { isSuccess: true, data: null }) as QueryResult<TData>;
+    },
+    async batch(commands) {
+      calls.push({ kind: "batch", payload: commands });
+      const results: WriteResult[] = commands.map((_, i) => ({
+        isSuccess: true as const,
+        data: { id: `fake-batch-${i}` },
+      }));
+      const result: BatchResult = { isSuccess: true, results };
+      return result;
+    },
+    statusStore,
+    pendingWrites: () => pendingWritesStore,
+    pendingFiles: () => pendingFilesStore,
+    setStatus(next) {
+      statusStore.setState(next);
+    },
+  };
+}
+
+describe("Dispatcher contract", () => {
+  test("write() records the call and returns the configured response", async () => {
+    const disp = createFakeDispatcher({
+      writeResponses: {
+        "app:write:task:create": { isSuccess: true, data: { id: "t-1", title: "hello" } },
+      },
+    });
+
+    const result = await disp.write("app:write:task:create", { title: "hello" });
+
+    expect(result.isSuccess).toBe(true);
+    if (result.isSuccess) {
+      expect((result.data as { id: string }).id).toBe("t-1");
+    }
+    expect(disp.calls).toHaveLength(1);
+    expect(disp.calls[0]).toEqual({
+      kind: "write",
+      type: "app:write:task:create",
+      payload: { title: "hello" },
+    });
+  });
+
+  test("write() failure shape carries code + message + optional field issues", async () => {
+    const disp = createFakeDispatcher({
+      writeResponses: {
+        "app:write:task:create": {
+          isSuccess: false,
+          error: {
+            code: "validation_error",
+            httpStatus: 400,
+            i18nKey: "errors.validation.failed",
+            message: "Validation failed",
+            details: {
+              fields: [
+                { path: "title", code: "too_small", i18nKey: "errors.validation.too_small" },
+              ],
+            },
+          },
+        },
+      },
+    });
+
+    const result = await disp.write("app:write:task:create", { title: "" });
+
+    expect(result.isSuccess).toBe(false);
+    if (!result.isSuccess) {
+      expect(result.error.code).toBe("validation_error");
+      expect(result.error.details?.fields?.[0]?.path).toBe("title");
+    }
+  });
+
+  test("batch() returns one result per command, in order", async () => {
+    const disp = createFakeDispatcher();
+    const commands: readonly Command[] = [
+      { type: "app:write:task:create", payload: { title: "a" } },
+      { type: "app:write:task:create", payload: { title: "b" } },
+      { type: "app:write:task:create", payload: { title: "c" } },
+    ];
+
+    const result = await disp.batch(commands);
+
+    expect(result.isSuccess).toBe(true);
+    if (result.isSuccess) {
+      expect(result.results).toHaveLength(3);
+      for (const r of result.results) {
+        expect(r.isSuccess).toBe(true);
+      }
+    }
+  });
+
+  test("statusStore fires on transitions and unsubscribes cleanly", () => {
+    const disp = createFakeDispatcher();
+    const seen: DispatcherStatus[] = [];
+
+    const unsubscribe = disp.statusStore.subscribe(() => seen.push(disp.statusStore.getSnapshot()));
+    disp.setStatus("offline");
+    disp.setStatus("syncing");
+    unsubscribe();
+    disp.setStatus("online");
+
+    expect(seen).toEqual(["offline", "syncing"]);
+  });
+
+  test("pending queues are empty by default (live-dispatcher semantic)", () => {
+    const disp = createFakeDispatcher();
+
+    expect(disp.pendingWrites()).toEqual([]);
+    expect(disp.pendingFiles()).toEqual([]);
+  });
+});

package/src/dispatcher/index.ts

@@ -0,0 +1,14 @@
+export type {
+  BatchResult,
+  Command,
+  Dispatcher,
+  DispatcherError,
+  DispatcherStatus,
+  FieldIssue,
+  PendingFile,
+  PendingWrite,
+  QueryOpts,
+  QueryResult,
+  WriteOpts,
+  WriteResult,
+} from "./types";