@cosmicdrift/kumiko-headless 0.193.1 → 0.194.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-headless",
-  "version": "0.193.1",
+  "version": "0.194.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>",
@@ -36,7 +36,7 @@
     }
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-framework": "0.193.1",
+    "@cosmicdrift/kumiko-framework": "0.194.0",
     "temporal-polyfill": "^0.3.2",
     "zod": "^4.4.3"
   },

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

@@ -1,4 +1,5 @@
 import { describe, expect, mock, test } from "bun:test";
+import { z } from "zod";
 import { createFormController } from "../form-controller";
 
 describe("createFormController — core state machine", () => {
@@ -193,3 +194,38 @@ describe("createFormController — core state machine", () => {
     expect(snap.changes["title"]).toBeUndefined();
   });
 });
+
+describe("validate() scoping", () => {
+  const schema = z.object({ step1: z.string().min(1), step2: z.string().min(1) });
+
+  test("a clean scoped validate() doesn't wipe an out-of-scope field's existing errors", () => {
+    const form = createFormController({ initial: { step1: "", step2: "filled" }, schema });
+
+    // Unscoped run (e.g. submit) surfaces errors on both fields.
+    expect(form.validate()).toBe(false);
+    expect(form.getSnapshot().errors["step1"]).toBeDefined();
+
+    // step2 is now fixed; a scoped validate() for step2 alone must not
+    // clear step1's still-outstanding error.
+    form.setField("step2", "filled");
+    expect(form.validate(["step2"])).toBe(true);
+    const snap = form.getSnapshot();
+    expect(snap.errors["step2"]).toBeUndefined();
+    expect(snap.errors["step1"]).toBeDefined();
+  });
+
+  test("a failing scoped validate() doesn't overwrite an out-of-scope field's existing errors", () => {
+    const form = createFormController({ initial: { step1: "", step2: "" }, schema });
+
+    expect(form.validate()).toBe(false);
+    expect(form.getSnapshot().errors["step1"]).toBeDefined();
+    expect(form.getSnapshot().errors["step2"]).toBeDefined();
+
+    // Re-running validate scoped to step1 only (still empty) must refresh
+    // step1's error without touching step2's independently-set error.
+    expect(form.validate(["step1"])).toBe(false);
+    const snap = form.getSnapshot();
+    expect(snap.errors["step1"]).toBeDefined();
+    expect(snap.errors["step2"]).toBeDefined();
+  });
+});

package/src/form/__tests__/submit.test.ts

@@ -231,6 +231,44 @@ describe("createFormController — submit()", () => {
     });
   });
 
+  test("payloadMode: 'values' — strips a field that was touched and returned to \"\" (value-based, not touch-based)", async () => {
+    // stripUntouchedEmptyStrings only compares current vs. initial value —
+    // it has no concept of "touched". A field the user typed into and then
+    // cleared back to "" is dropped exactly like one nobody ever touched.
+    const disp = makeDispatcher();
+    const form = createFormController({
+      initial: { title: "hello", dueDate: "" },
+      submit: { dispatcher: disp, type: "app:write:task:create" },
+    });
+    form.setField("dueDate", "x");
+    form.setField("dueDate", "");
+
+    await form.submit();
+
+    const call = disp.writeSpy.mock.calls[0]?.[1] as Record<string, unknown>;
+    expect("dueDate" in call).toBe(false);
+  });
+
+  test("second submit after a rebase diffs against the new baseline, not the stale original initial", async () => {
+    const disp = makeDispatcher();
+    const form = createFormController({
+      initial: { title: "hello" },
+      submit: { dispatcher: disp, type: "app:write:task:update", payloadMode: "changes" },
+    });
+
+    form.setField("title", "world");
+    await form.submit();
+    expect(form.getSnapshot().initial.title).toBe("world"); // baseline rebased
+
+    // Revert to the ORIGINAL initial value — clean against the stale
+    // baseline, but a real change against the rebased one.
+    form.setField("title", "hello");
+    await form.submit();
+
+    expect(disp.writeSpy).toHaveBeenCalledTimes(2);
+    expect(disp.writeSpy.mock.calls[1]).toEqual(["app:write:task:update", { title: "hello" }]);
+  });
+
   test("stale-submit race: edits during the in-flight write stay dirty after success", async () => {
     // User submits "hello", the network takes 50ms. During those 50ms the
     // user types "world" into the same field. The server sees "hello"

package/src/form/__tests__/validation.test.ts

@@ -46,10 +46,6 @@ describe("zodErrorToFieldIssues", () => {
     expect(issues[0]?.params?.["minimum"]).toBe(10);
   });
 
-  // kumiko-framework#1927: a bare `code:"custom"` issue (superRefine's only
-  // code) would otherwise always resolve to the generic "Invalid value."
-  // key — `params.i18nKey` lets a check like form-schema.ts's presence
-  // check point at its own key instead.
   test("custom issue with params.i18nKey overrides the mechanical errors.validation.custom key", () => {
     const schema = z.object({ name: z.string() }).superRefine((values, ctx) => {
       if (values.name === "") {

package/src/form/form-controller.ts

@@ -76,6 +76,11 @@ function valuesDiff<TValues extends FormValues>(
 
 // buildInitialValues seeds untouched optional fields with "" for controlled
 // inputs; a `.optional()` server schema accepts undefined but not "".
+// String-only: number/money seed to 0 and boolean seeds to false, and an
+// untouched optional field of those types still submits that seed instead
+// of being omitted — no validation error surfaces it, unlike the "" case.
+// Fixing that needs real per-field seed-tracking (which value was actually
+// user-set vs. defaulted), not just a wider strip predicate here.
 function stripUntouchedEmptyStrings<TValues extends FormValues>(
   values: TValues,
   initial: TValues,
@@ -84,7 +89,7 @@ function stripUntouchedEmptyStrings<TValues extends FormValues>(
   const ini = initial as Record<string, unknown>; // @cast-boundary form-values
   let out: Record<string, unknown> | undefined;
   for (const key of Object.keys(v)) {
-    if (v[key] === "" && Object.is(v[key], ini[key])) {
+    if (v[key] === "" && ini[key] === "") {
       out ??= { ...v };
       delete out[key];
     }
@@ -152,10 +157,33 @@ export function createFormController<TValues extends FormValues, TCtx = unknown>
   // Local shared implementations so submit() can call validate/rebase
   // without the this-in-object-literal dance. Both also expose themselves
   // as methods on the returned controller.
+  // Clears/replaces errors for a scoped run without touching fields outside
+  // the scope — a step-2 validate() that comes back clean must not wipe
+  // step-1's still-unresolved errors from an earlier submit() (or vice
+  // versa when step-2 newly has issues).
+  function replaceScopedErrors(
+    scopeSet: Set<string> | undefined,
+    grouped: Readonly<Record<string, readonly FieldIssue[]>>,
+  ): void {
+    if (scopeSet === undefined) {
+      errors = Object.freeze(grouped);
+      // skip: unscoped replace — wholesale overwrite, nothing left to merge
+      return;
+    }
+    const merged: Record<string, readonly FieldIssue[]> = {};
+    for (const [path, issues] of Object.entries(errors)) {
+      if (!scopeSet.has(path)) merged[path] = issues;
+    }
+    Object.assign(merged, grouped);
+    errors = Object.freeze(merged);
+  }
+
   function runValidate(scope?: readonly string[]): boolean {
+    // See the validate() doc comment in types.ts for the scope contract.
+    const scopeSet = scope === undefined ? undefined : new Set(scope);
     if (!options.schema) {
       if (Object.keys(errors).length > 0) {
-        errors = Object.freeze({});
+        replaceScopedErrors(scopeSet, {});
         invalidate();
       }
       return true;
@@ -164,7 +192,7 @@ export function createFormController<TValues extends FormValues, TCtx = unknown>
     const parsed = options.schema.safeParse(values);
     if (parsed.success) {
       if (Object.keys(errors).length > 0) {
-        errors = Object.freeze({});
+        replaceScopedErrors(scopeSet, {});
         invalidate();
       }
       return true;
@@ -173,8 +201,6 @@ export function createFormController<TValues extends FormValues, TCtx = unknown>
     for (const [fieldKey, state] of Object.entries(fieldStates)) {
       if (!state.visible) hiddenFields.add(fieldKey);
     }
-    // See the validate() doc comment in types.ts for the scope contract.
-    const scopeSet = scope === undefined ? undefined : new Set(scope);
     const allIssues = zodErrorToFieldIssues(parsed.error);
     const relevantIssues = allIssues.filter((issue) => {
       const rootField = issue.path.split(".")[0] ?? "";
@@ -184,12 +210,12 @@ export function createFormController<TValues extends FormValues, TCtx = unknown>
     });
     if (relevantIssues.length === 0) {
       if (Object.keys(errors).length > 0) {
-        errors = Object.freeze({});
+        replaceScopedErrors(scopeSet, {});
         invalidate();
       }
       return true;
     }
-    errors = Object.freeze(groupIssuesByPath(relevantIssues));
+    replaceScopedErrors(scopeSet, groupIssuesByPath(relevantIssues));
     invalidate();
     return false;
   }

package/src/form/index.ts

@@ -12,4 +12,4 @@ export type {
   SubmitPayloadMode,
   SubmitResult,
 } from "./types";
-export { groupIssuesByPath, zodErrorToFieldIssues } from "./zod-bridge";
+export { groupIssuesByPath, I18N_KEY_PARAM, zodErrorToFieldIssues } from "./zod-bridge";

package/src/form/types.ts

@@ -142,17 +142,9 @@ export type FormController<TValues extends FormValues> = {
   // `true` when no schema was wired — a controller without a schema
   // relies entirely on server-side validation via the submit() path.
   //
-  // `scope` restricts which fields' issues get reported — pass the current
-  // wizard step's field names to validate only that step (used on
-  // "Weiter"). Issues on fields outside `scope` are silently dropped, and
-  // so are root-level issues from an object-level `.refine()` (their path
-  // is `(root)`, which never matches a real field name) — a scoped run can
-  // never surface those. That's deliberate: a step-boundary check exists
-  // to gate moving forward, not to catch whole-form invariants. Omit
-  // `scope` (as submit() does) to validate everything, including root
-  // issues — the final gate before dispatch must not let them through
-  // unnoticed. Hidden fields are filtered out in both modes regardless of
-  // scope.
+  // `scope` restricts reported issues to those field names; root-level
+  // `.refine()` issues (path `(root)`) never match a scope and are dropped
+  // by design — omit `scope` (as submit() does) to see them.
   validate(scope?: readonly string[]): boolean;
 
   // Reverts values to `initial`, clears errors. Doesn't fire a new

package/src/form/zod-bridge.ts

@@ -49,19 +49,17 @@ export function zodErrorToFieldIssues(error: ZodError): FieldIssue[] {
   });
 }
 
-// Every zod code maps mechanically to `errors.validation.<code>` — except
-// `code: "custom"`, which is zod's one-size-fits-all bucket for every
-// `superRefine`/`refine` check in the codebase. Left mechanical, ALL of them
-// would collapse onto the same `errors.validation.custom` ("Invalid
-// value.") key, which is wrong for a check that has a more specific message
-// (e.g. form-schema.ts's presence check wants "Pflichtfeld." / "Required.").
-// A `superRefine` that needs its own key sets `params.i18nKey` on the issue;
-// this is the one place that honors it. Keep in sync with the server-side
-// mirror (packages/framework/src/errors/zod-bridge.ts) — a superRefine can
-// run on either side.
+// Same magic key both sides of a superRefine can set to opt out of the
+// generic `errors.validation.custom` message — see form-schema.ts.
+export const I18N_KEY_PARAM = "i18nKey";
+
+// `code: "custom"` is zod's catch-all for every superRefine/refine check;
+// left mechanical it'd collapse onto one generic key, so a superRefine can
+// set `params[I18N_KEY_PARAM]` to override it. Keep in sync with the server
+// mirror (packages/framework/src/errors/zod-bridge.ts).
 function resolveI18nKey(issue: ZodIssue): string {
   if (issue.code === "custom") {
-    const override = issue.params?.["i18nKey"];
+    const override = issue.params?.[I18N_KEY_PARAM];
     if (typeof override === "string") return override;
   }
   return `errors.validation.${issue.code}`;

package/src/index.ts

@@ -52,7 +52,7 @@ export type {
   SubmitPayloadMode,
   SubmitResult,
 } from "./form";
-export { createFormController } from "./form";
+export { createFormController, I18N_KEY_PARAM } from "./form";
 export {
   applyFormatSpec,
   currencyDecimals,

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

@@ -593,4 +593,42 @@ describe("computeEditViewModel — embedded-list cells (#1835)", () => {
     const field = asFields(vm.sections[0]).fields[0];
     expect(field?.imageVariant).toBeUndefined();
   });
+
+  test("capture is forwarded for an image field that declares it", () => {
+    const entity = {
+      fields: {
+        avatar: { type: "image", capture: "environment" },
+      },
+    } as unknown as EntityDefinition;
+
+    const vm = computeEditViewModel({
+      screen: editScreen({ sections: [{ title: "x", fields: ["avatar"] }] }),
+      entity,
+      values: {},
+      translate,
+      featureName: "orders",
+    });
+
+    const field = asFields(vm.sections[0]).fields[0];
+    expect(field?.capture).toBe("environment");
+  });
+
+  test("capture is undefined for an image field without it", () => {
+    const entity = {
+      fields: {
+        avatar: { type: "image" },
+      },
+    } as unknown as EntityDefinition;
+
+    const vm = computeEditViewModel({
+      screen: editScreen({ sections: [{ title: "x", fields: ["avatar"] }] }),
+      entity,
+      values: {},
+      translate,
+      featureName: "orders",
+    });
+
+    const field = asFields(vm.sections[0]).fields[0];
+    expect(field?.capture).toBeUndefined();
+  });
 });

package/src/view-model/edit.ts

@@ -174,10 +174,12 @@ export function computeEditViewModel<
             accept?: readonly string[];
             maxSize?: string;
             variants?: Readonly<Record<string, unknown>>;
+            capture?: "environment" | "user";
           })
         : undefined;
       const imageVariant =
         fieldDef.type === "image" ? Object.keys(fileDef?.variants ?? {})[0] : undefined;
+      const capture = fieldDef.type === "image" ? fileDef?.capture : undefined;
       // Embedded-LIST field (`multiple: true`) — per-cell metadata for a
       // renderer to draw one row per array item (invoice-positions-style
       // table). A plain (non-list) embedded field emits none of this; the
@@ -268,6 +270,7 @@ export function computeEditViewModel<
         ...(fileDef?.maxSize !== undefined && { maxSize: fileDef.maxSize }),
         ...(isFileType && { entityType: screen.entity, fieldName: normalized.field }),
         ...(imageVariant !== undefined && { imageVariant }),
+        ...(capture !== undefined && { capture }),
         ...(normalized.icon !== undefined && { icon: normalized.icon }),
         ...(embeddedListCells !== undefined && { embeddedListCells }),
         ...(embeddedListDef?.minItems !== undefined && {

package/src/view-model/embedded-list.ts

@@ -1,6 +1,7 @@
+import type { EmbeddedDerivedCellDef } from "@cosmicdrift/kumiko-framework/ui-types";
 import type { FieldIssue } from "../dispatcher";
 
-export type EmbeddedDerivedOp = "multiply" | "sum" | "subtract";
+export type EmbeddedDerivedOp = EmbeddedDerivedCellDef["op"];
 
 export type { DerivedCellRoundingTarget } from "@cosmicdrift/kumiko-framework/ui-types";
 // Canonical implementation moved to packages/framework/src/engine/embedded-derived.ts

package/src/view-model/types.ts

@@ -188,6 +188,9 @@ export type EditFieldViewModel = {
    *  is not a rule that always has an answer. Absent when the field declares
    *  no variants — the preview then loads the original. */
   readonly imageVariant?: string;
+  /** Only for `type: "image"` — forwarded to the file input's `capture`
+   *  attribute so a phone opens the camera instead of the file picker. */
+  readonly capture?: "environment" | "user";
   /** Prefix-icon key from `EditFieldSpec.icon`, passed through unchanged
    *  (no i18n — it's a symbolic key, not a display string). The renderer
    *  resolves it against the FIELD_ICONS registry; unknown keys silently