@cosmicdrift/kumiko-headless 0.187.0 → 0.188.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-headless",
-  "version": "0.187.0",
+  "version": "0.188.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.187.0",
+    "@cosmicdrift/kumiko-framework": "0.188.0",
     "temporal-polyfill": "^0.3.2",
     "zod": "^4.4.3"
   },

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

@@ -73,6 +73,40 @@ describe("createFormController — submit()", () => {
     expect(form.getSnapshot().errors["title"]).toBeDefined();
   });
 
+  test("validateScope: a required field outside the scope missing/empty does not block submit", async () => {
+    // RenderEdit's `fields` filter narrows what's rendered; a schema-required
+    // field the user never sees (outside validateScope) must not be able to
+    // block a submit they have no way to fix.
+    const disp = makeDispatcher();
+    const form = createFormController({
+      initial: { title: "hello", notes: "" },
+      schema: z.object({ title: z.string().min(1), notes: z.string().min(1) }),
+      submit: { dispatcher: disp, type: "app:write:task:create", validateScope: ["title"] },
+    });
+
+    const result = await form.submit();
+
+    expect(result.validationBlocked).toBe(false);
+    expect(disp.writeSpy).toHaveBeenCalledTimes(1);
+    const call = disp.writeSpy.mock.calls[0]?.[1] as Record<string, unknown>;
+    expect(call["title"]).toBe("hello");
+  });
+
+  test("validateScope: a required field inside the scope missing/empty still blocks submit", async () => {
+    const disp = makeDispatcher();
+    const form = createFormController({
+      initial: { title: "", notes: "filled" },
+      schema: z.object({ title: z.string().min(1), notes: z.string().min(1) }),
+      submit: { dispatcher: disp, type: "app:write:task:create", validateScope: ["title"] },
+    });
+
+    const result = await form.submit();
+
+    expect(result.validationBlocked).toBe(true);
+    expect(disp.writeSpy).not.toHaveBeenCalled();
+    expect(form.getSnapshot().errors["title"]).toBeDefined();
+  });
+
   test("server validation failure: field errors land on the form", async () => {
     const disp = makeDispatcher({
       isSuccess: false,

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

@@ -122,3 +122,106 @@ describe("createFormController — validate()", () => {
     expect(form.getSnapshot().errors["address.city"]).toBeDefined();
   });
 });
+
+describe("createFormController — validate(scope)", () => {
+  test("scoped run reports only fields inside scope, drops issues outside it", () => {
+    const schema = z.object({
+      a: z.string().min(3),
+      b: z.string().min(3),
+    });
+    const form = createFormController({ initial: { a: "x", b: "y" }, schema });
+
+    const ok = form.validate(["a"]);
+    const snap = form.getSnapshot();
+
+    expect(ok).toBe(false);
+    expect(snap.errors["a"]).toBeDefined();
+    expect(snap.errors["b"]).toBeUndefined();
+  });
+
+  test("scoped run returns true when every field in scope is valid, even if fields outside scope are not", () => {
+    const schema = z.object({
+      a: z.string().min(1),
+      b: z.string().min(3),
+    });
+    const form = createFormController({ initial: { a: "ok", b: "y" }, schema });
+
+    const ok = form.validate(["a"]);
+
+    expect(ok).toBe(true);
+    expect(form.getSnapshot().errors).toEqual({});
+  });
+
+  // Hard rule (kumiko-framework#1885): an object-level .refine() issue has
+  // path "(root)", which never matches a field name — every scoped
+  // validate() call must ignore it, and only the unscoped final-submit
+  // validate() may surface it. Otherwise a step-boundary check would block
+  // a wizard step forever on an invariant no single step owns.
+  describe("root-path .refine() issues", () => {
+    const schema = z
+      .object({
+        start: z.string(),
+        end: z.string(),
+      })
+      .refine((v) => v.end >= v.start, { message: "end must be >= start" });
+
+    test("scoped validate() ignores the root issue regardless of which fields are in scope", () => {
+      const form = createFormController({ initial: { start: "b", end: "a" }, schema });
+
+      expect(form.validate(["start"])).toBe(true);
+      expect(form.validate(["end"])).toBe(true);
+      expect(form.validate(["start", "end"])).toBe(true);
+      expect(form.getSnapshot().errors).toEqual({});
+    });
+
+    test("unscoped validate() (final submit) reports the root issue under '(root)'", () => {
+      const form = createFormController({ initial: { start: "b", end: "a" }, schema });
+
+      const ok = form.validate();
+
+      expect(ok).toBe(false);
+      expect(form.getSnapshot().errors["(root)"]).toBeDefined();
+    });
+  });
+
+  test("hidden fields stay filtered in scoped mode even when the hidden field is itself in scope", () => {
+    // Discriminating case: field `b` is both hidden AND inside `scope`, so
+    // the assertion actually exercises the hidden-field filter — not just
+    // the scope filter dropping an out-of-scope field.
+    const schema = z.object({
+      a: z.string().min(3),
+      b: z.string().min(3),
+    });
+    const form = createFormController({
+      initial: { a: "x", b: "y", showB: false },
+      schema,
+      fields: { b: { visible: (values) => values.showB } },
+    });
+
+    const ok = form.validate(["a", "b"]);
+    const snap = form.getSnapshot();
+
+    expect(ok).toBe(false);
+    expect(snap.errors["a"]).toBeDefined();
+    expect(snap.errors["b"]).toBeUndefined();
+  });
+
+  test("hidden fields stay filtered in unscoped mode (regression guard alongside the scoped case)", () => {
+    const schema = z.object({
+      a: z.string().min(3),
+      b: z.string().min(3),
+    });
+    const form = createFormController({
+      initial: { a: "x", b: "y", showB: false },
+      schema,
+      fields: { b: { visible: (values) => values.showB } },
+    });
+
+    const ok = form.validate();
+    const snap = form.getSnapshot();
+
+    expect(ok).toBe(false);
+    expect(snap.errors["a"]).toBeDefined();
+    expect(snap.errors["b"]).toBeUndefined();
+  });
+});

package/src/form/form-controller.ts

@@ -152,7 +152,7 @@ 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.
-  function runValidate(): boolean {
+  function runValidate(scope?: readonly string[]): boolean {
     if (!options.schema) {
       if (Object.keys(errors).length > 0) {
         errors = Object.freeze({});
@@ -173,10 +173,14 @@ 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] ?? "";
-      return !hiddenFields.has(rootField);
+      if (hiddenFields.has(rootField)) return false;
+      if (scopeSet && !scopeSet.has(rootField)) return false;
+      return true;
     });
     if (relevantIssues.length === 0) {
       if (Object.keys(errors).length > 0) {
@@ -292,7 +296,7 @@ export function createFormController<TValues extends FormValues, TCtx = unknown>
       // pattern the server-side event-dispatcher uses (passInFlight).
       if (submitInFlight) return submitInFlight as Promise<SubmitResult<TData>>;
 
-      if (!runValidate()) {
+      if (!runValidate(submitCfg.validateScope)) {
         return { validationBlocked: true, isSuccess: false };
       }
 

package/src/form/types.ts

@@ -141,7 +141,19 @@ export type FormController<TValues extends FormValues> = {
   // values. Populates errors and returns true iff valid. Noop-returns
   // `true` when no schema was wired — a controller without a schema
   // relies entirely on server-side validation via the submit() path.
-  validate(): boolean;
+  //
+  // `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.
+  validate(scope?: readonly string[]): boolean;
 
   // Reverts values to `initial`, clears errors. Doesn't fire a new
   // "initial" baseline — to adopt the current values as the new baseline
@@ -251,6 +263,12 @@ export type SubmitConfig<TValues extends FormValues = FormValues> = {
   // That's intentional: a caller choosing to write a transformer is
   // making an explicit statement about payload shape.
   readonly buildPayload?: (snapshot: FormSnapshot<TValues>) => unknown;
+  /** Restricts submit()'s internal validate() call to these field names —
+   *  same contract as validate()'s `scope` param. Set by RenderEdit when the
+   *  caller's `fields` prop narrows which fields are rendered, so an
+   *  unrendered required field can't block a submit the user can't fix.
+   *  Omitted = unscoped (existing behavior, validates everything). */
+  readonly validateScope?: readonly string[];
 };
 
 // What submit() returns. Mirrors WriteResult so a failed submit can

package/src/format/index.ts

@@ -69,6 +69,7 @@ function formatDateCell(
 
 export { escapeHtml, escapeHtmlAttr, escapeXml, isSafeHref, stripControlChars } from "./escape";
 export { type HtmlValue, html, RawHtml, raw } from "./html-template";
+export { currencyDecimals } from "./money";
 export function applyFormatSpec(
   spec: { format: string } & Record<string, unknown>,
   value: unknown,

package/src/format/money.ts

@@ -0,0 +1,11 @@
+// Currency decimal places — covers the world's zero- and three-decimal
+// outliers, defaults to 2 for everything else. Shared between renderer-web's
+// MoneyInput (minor-unit display factor) and RenderField's minor/major-unit
+// conversion (kumiko-framework#1923) — a single source keeps both sides
+// scaling the same currency the same way.
+export function currencyDecimals(code: string): number {
+  if (code === "JPY" || code === "KRW" || code === "VND" || code === "ISK") return 0;
+  if (code === "BHD" || code === "JOD" || code === "KWD" || code === "OMR" || code === "TND")
+    return 3;
+  return 2;
+}

package/src/index.ts

@@ -55,6 +55,7 @@ export type {
 export { createFormController } from "./form";
 export {
   applyFormatSpec,
+  currencyDecimals,
   escapeHtml,
   escapeHtmlAttr,
   escapeXml,

package/src/view-model/edit.ts

@@ -163,6 +163,11 @@ export function computeEditViewModel<
       // file/image: accept/maxSize ins ViewModel + entityType/fieldName für
       // den Upload-POST (Endpoint validiert gegen die richtige Field-Def).
       const isFileType = fieldDef.type === "file" || fieldDef.type === "image";
+      // ponytail: "EUR" mirrors DEFAULT_CURRENCIES[0] from
+      // framework/src/engine/field-helpers.ts — headless has no dependency
+      // on that module, so the literal is duplicated here instead of
+      // importing it just for one fallback string.
+      const resolvedCurrency = entity.defaultCurrency ?? "EUR";
       const fileDef = isFileType
         ? (fieldDef as unknown as { accept?: readonly string[]; maxSize?: string })
         : undefined;
@@ -269,15 +274,10 @@ export function computeEditViewModel<
         ...(embeddedListDef?.totals !== undefined && {
           embeddedListTotals: embeddedListDef.totals,
         }),
-        // ponytail: "EUR" mirrors DEFAULT_CURRENCIES[0] from
-        // framework/src/engine/field-helpers.ts — headless has no dependency
-        // on that module, so the literal is duplicated here instead of
-        // importing it just for one fallback string. Currency lives on the
-        // head aggregate (entity.defaultCurrency), not per row — one value
-        // for the whole embedded list.
-        ...(embeddedListDef !== undefined && {
-          embeddedListCurrency: entity.defaultCurrency ?? "EUR",
-        }),
+        // Currency lives on the head aggregate (entity.defaultCurrency), not
+        // per row — one value for the whole embedded list.
+        ...(embeddedListDef !== undefined && { embeddedListCurrency: resolvedCurrency }),
+        ...(fieldDef.type === "money" && { currency: resolvedCurrency }),
       };
       return view;
     });

package/src/view-model/types.ts

@@ -204,6 +204,11 @@ export type EditFieldViewModel = {
    *  currency lives on the head aggregate (EntityDefinition.defaultCurrency),
    *  not per row. Falls back to "EUR" when the entity has no defaultCurrency. */
   readonly embeddedListCurrency?: string;
+  /** Only set for a plain (non-list, non-embedded) `type: "money"` field —
+   *  same source as embeddedListCurrency (EntityDefinition.defaultCurrency,
+   *  falls back to "EUR"). The renderer needs this to build the payload's
+   *  `{amount, currency}` shape (kumiko-framework#1923). */
+  readonly currency?: string;
 };
 
 // Discriminated by `kind` — mirrors EditSectionSpec on the engine side.