@cosmicdrift/kumiko-headless 0.187.0 → 0.189.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-headless",
-  "version": "0.187.0",
+  "version": "0.189.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.189.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

@@ -45,6 +45,45 @@ describe("zodErrorToFieldIssues", () => {
     expect(issues[0]?.params).toBeDefined();
     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 === "") {
+        ctx.addIssue({
+          code: "custom",
+          path: ["name"],
+          message: '"name" is required.',
+          params: { i18nKey: "kumiko.validation.required" },
+        });
+      }
+    });
+    const result = schema.safeParse({ name: "" });
+
+    expect(result.success).toBe(false);
+    if (result.success) return;
+    const issues = zodErrorToFieldIssues(result.error);
+
+    expect(issues[0]?.i18nKey).toBe("kumiko.validation.required");
+  });
+
+  test("custom issue without params.i18nKey still falls back to errors.validation.custom", () => {
+    const schema = z.object({ name: z.string() }).superRefine((values, ctx) => {
+      if (values.name === "bad") {
+        ctx.addIssue({ code: "custom", path: ["name"], message: "not allowed" });
+      }
+    });
+    const result = schema.safeParse({ name: "bad" });
+
+    expect(result.success).toBe(false);
+    if (result.success) return;
+    const issues = zodErrorToFieldIssues(result.error);
+
+    expect(issues[0]?.i18nKey).toBe("errors.validation.custom");
+  });
 });
 
 describe("groupIssuesByPath", () => {
@@ -122,3 +161,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/form/zod-bridge.ts

@@ -43,12 +43,30 @@ export function zodErrorToFieldIssues(error: ZodError): FieldIssue[] {
       // malformed" errors under — matches what the server does.
       path: issue.path.map(String).join(".") || "(root)",
       code: issue.code,
-      i18nKey: `errors.validation.${issue.code}`,
+      i18nKey: resolveI18nKey(issue),
       ...(params && { params }),
     };
   });
 }
 
+// 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.
+function resolveI18nKey(issue: ZodIssue): string {
+  if (issue.code === "custom") {
+    const override = issue.params?.["i18nKey"];
+    if (typeof override === "string") return override;
+  }
+  return `errors.validation.${issue.code}`;
+}
+
 function extractIssueParams(issue: ZodIssue): Readonly<Record<string, unknown>> | undefined {
   const out: Record<string, unknown> = {};
   const bag = issue as unknown as Record<string, unknown>; // @cast-boundary zod-issue

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

@@ -102,7 +102,7 @@ export function computeEditViewModel<
       // List-Builder), damit Form-Selects und List-Cells dieselbe
       // i18n-Quelle teilen.
       const options =
-        fieldDef.type === "select"
+        fieldDef.type === "select" || fieldDef.type === "multiSelect"
           ? ((fieldDef as unknown as { options?: readonly string[] }).options ?? [])
           : undefined;
       const optionLabels =
@@ -113,11 +113,12 @@ export function computeEditViewModel<
               options,
             )
           : undefined;
-      // Multiline-Hint bei `type: "text"` — der Renderer wechselt
-      // dann auf textarea. ViewModel hält die Form-Render-Decision
-      // damit der Renderer nicht selbst auf die FieldDefinition greift.
+      // Multiline hint for `type: "text"` — the renderer then switches to a
+      // textarea. `type: "longText"` always renders a textarea regardless
+      // of this hint; it's only carried through as an optional `{ rows }`
+      // override (#1925).
       const multiline =
-        fieldDef.type === "text"
+        fieldDef.type === "text" || fieldDef.type === "longText"
           ? (fieldDef as unknown as { multiline?: boolean | { rows?: number } }).multiline
           : undefined;
       // Wall-Clock-Hint bei `type: "timestamp"` mit locatedBy — der
@@ -163,6 +164,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 +275,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

@@ -128,18 +128,22 @@ export type EditFieldViewModel = {
   readonly required: boolean;
   readonly span?: number;
   readonly renderer?: FieldRenderer;
-  /** Nur bei `type: "select"` gesetzt — die zugelassenen Werte. Wird
-   *  vom Renderer als Dropdown-Optionen genutzt. Quelle ist
-   *  SelectFieldDef.options aus der EntityDefinition. */
+  /** Set for `type: "select"` and `type: "multiSelect"` — the allowed
+   *  values. The renderer uses these as dropdown/combobox options.
+   *  Source is SelectFieldDef.options / MultiSelectFieldDef.options on
+   *  the EntityDefinition. */
   readonly options?: readonly string[];
-  /** Nur bei `type: "select"` gesetzt — translated Labels pro Option,
-   *  keyed nach raw value. Renderer zeigt `optionLabels[value]` als
-   *  Dropdown-Label statt raw value. Convention-Key:
+  /** Set for `type: "select"` and `type: "multiSelect"` — translated
+   *  labels per option, keyed by raw value. The renderer shows
+   *  `optionLabels[value]` as the dropdown/combobox label instead of the
+   *  raw value. Convention key:
    *  `<feature>:entity:<entity>:field:<field>:option:<value>`. */
   readonly optionLabels?: Readonly<Record<string, string>>;
-  /** Nur bei `type: "text"` gesetzt wenn TextFieldDef.multiline true
-   *  ist — dann rendert der Renderer textarea statt single-line input.
-   *  `true` = Default-Zeilen, `{ rows }` = explizite Höhe. */
+  /** For `type: "text"`, set when TextFieldDef.multiline is true — the
+   *  renderer then renders a textarea instead of a single-line input.
+   *  `type: "longText"` always renders a textarea regardless of this
+   *  value; here it only carries an optional `{ rows }` override.
+   *  `true` = default rows, `{ rows }` = explicit height. */
   readonly multiline?: boolean | { readonly rows?: number };
   /** Nur bei `type: "timestamp"` gesetzt wenn TimestampFieldDef.locatedBy
    *  existiert — Wall-Clock-Zeit ohne Offset. Der Renderer emittiert
@@ -204,6 +208,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.