@cosmicdrift/kumiko-renderer 0.187.0 → 0.189.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-renderer",
-  "version": "0.187.0",
+  "version": "0.189.0",
   "description": "Platform-agnostic React renderer for Kumiko screens. Contains the shared logic — primitives-contract, hooks, KumikoScreen, navigation & SSE abstractions — that any platform-specific renderer (web, native) composes. No DOM, no EventSource, no react-dom.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -15,10 +15,11 @@
     }
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-framework": "0.187.0",
-    "@cosmicdrift/kumiko-headless": "0.187.0",
+    "@cosmicdrift/kumiko-framework": "0.189.0",
+    "@cosmicdrift/kumiko-headless": "0.189.0",
     "react": "^19.2.6",
-    "temporal-polyfill": "^0.3.2"
+    "temporal-polyfill": "^0.3.2",
+    "zod": "^4.4.3"
   },
   "devDependencies": {
     "@testing-library/react": "^16.3.2",

package/src/__tests__/merge-search-params-into-initial.test.ts

@@ -40,12 +40,24 @@ describe("mergeSearchParamsIntoInitial", () => {
     expect(result["total"]).toBe(100);
   });
 
-  test("money-type field coerces a numeric string", () => {
+  test("money-type field without a defaultCurrency coerces a bare numeric string (legacy callers, e.g. config-edit/action-form)", () => {
     const fields: Record<string, FieldDef> = { price: { type: "money" } };
     const result = mergeSearchParamsIntoInitial(fields, { price: "19.99" });
     expect(result["price"]).toBe(19.99);
   });
 
+  test("money-type field WITH a defaultCurrency merges the entityEdit payload shape (#1923)", () => {
+    const fields: Record<string, FieldDef> = { price: { type: "money" } };
+    const result = mergeSearchParamsIntoInitial(fields, { price: "19.99" }, undefined, "USD");
+    expect(result["price"]).toEqual({ amount: 19.99, currency: "USD" });
+  });
+
+  test("money-type field WITH a defaultCurrency but no matching searchParam still defaults to the object shape", () => {
+    const fields: Record<string, FieldDef> = { price: { type: "money" } };
+    const result = mergeSearchParamsIntoInitial(fields, {}, undefined, "USD");
+    expect(result["price"]).toEqual({ amount: 0, currency: "USD" });
+  });
+
   test("renderableFields set given: searchParam for a non-rendered field is ignored (#1708)", () => {
     const fields: Record<string, FieldDef> = {
       status: { type: "text", default: "draft" },

package/src/app/__tests__/form-schema.test.ts

@@ -0,0 +1,227 @@
+import { describe, expect, test } from "bun:test";
+import type {
+  EditFieldSpec,
+  EntityDefinition,
+  EntityEditScreenDefinition,
+} from "@cosmicdrift/kumiko-framework/ui-types";
+import { createFormController } from "@cosmicdrift/kumiko-headless";
+import { buildFormSchema } from "../form-schema";
+
+function screenWith(fields: readonly EditFieldSpec[]): EntityEditScreenDefinition {
+  return {
+    id: "s",
+    type: "entityEdit",
+    entity: "e",
+    layout: { sections: [{ fields }] },
+  };
+}
+
+function entityWith(fields: EntityDefinition["fields"]): EntityDefinition {
+  return { fields } as EntityDefinition;
+}
+
+describe("buildFormSchema", () => {
+  describe("required field missing → issue on that field", () => {
+    const entity = entityWith({ name: { type: "text", required: true } });
+    const screen = screenWith(["name"]);
+
+    for (const [label, value] of [
+      ['""', ""],
+      ["null", null],
+      ["undefined", undefined],
+      ["[]", [] as unknown[]],
+    ] as const) {
+      test(label, () => {
+        const result = buildFormSchema(entity, screen).safeParse({ name: value });
+        expect(result.success).toBe(false);
+        if (result.success) return;
+        expect(result.error.issues).toHaveLength(1);
+        expect(result.error.issues[0]?.path).toEqual(["name"]);
+      });
+    }
+  });
+
+  // kumiko-framework#1927: a bare presence issue used to render as
+  // "Invalid value." — pin the params.i18nKey override so the resolved
+  // FieldIssue points at "kumiko.validation.required" ("Pflichtfeld.")
+  // instead of the generic errors.validation.custom fallback.
+  test("required field missing → issue carries the required-field i18nKey override", () => {
+    const entity = entityWith({ name: { type: "text", required: true } });
+    const screen = screenWith(["name"]);
+
+    const result = buildFormSchema(entity, screen).safeParse({ name: "" });
+    expect(result.success).toBe(false);
+    if (result.success) return;
+    const issue = result.error.issues[0];
+    if (issue?.code !== "custom") throw new Error("expected a custom issue");
+    expect(issue.params).toMatchObject({ i18nKey: "kumiko.validation.required" });
+  });
+
+  // kumiko-framework#1927: the seam the bug actually lived in — a schema
+  // built here only round-trips through createFormController's validate(),
+  // which is what feeds FormSnapshot.errors that render-edit.tsx passes to
+  // RenderField. A unit test on buildFormSchema() alone can't catch a break
+  // in that hand-off (e.g. zodErrorToFieldIssues not honoring the override).
+  test("end-to-end via createFormController: required field left empty → snapshot error carries kumiko.validation.required", () => {
+    const entity = entityWith({ name: { type: "text", required: true } });
+    const screen = screenWith(["name"]);
+
+    const form = createFormController({
+      initial: { name: "" },
+      schema: buildFormSchema(entity, screen),
+    });
+
+    expect(form.validate()).toBe(false);
+    const fieldErrors = form.getSnapshot().errors["name"];
+    expect(fieldErrors?.[0]?.i18nKey).toBe("kumiko.validation.required");
+  });
+
+  describe("required field present → no issue", () => {
+    const entity = entityWith({ name: { type: "number", required: true } });
+    const screen = screenWith(["name"]);
+
+    for (const [label, value] of [
+      ["0", 0],
+      ["false", false],
+      ['"Ada"', "Ada"],
+    ] as const) {
+      test(label, () => {
+        const result = buildFormSchema(entity, screen).safeParse({ name: value });
+        expect(result.success).toBe(true);
+      });
+    }
+  });
+
+  test("optional field left empty → no issue", () => {
+    const entity = entityWith({ name: { type: "text", required: false } });
+    const screen = screenWith(["name"]);
+    expect(buildFormSchema(entity, screen).safeParse({ name: "" }).success).toBe(true);
+  });
+
+  test("required field not rendered by the layout → no issue", () => {
+    const entity = entityWith({
+      name: { type: "text", required: true },
+      hidden: { type: "text", required: true },
+    });
+    const screen = screenWith(["name"]);
+    const result = buildFormSchema(entity, screen).safeParse({ name: "Ada", hidden: "" });
+    expect(result.success).toBe(true);
+  });
+
+  test("required multiSelect, empty array → issue on that field (#1925: has a combobox widget now)", () => {
+    const entity = entityWith({
+      tags: { type: "multiSelect", required: true, options: ["a", "b"] },
+    });
+    const screen = screenWith(["tags"]);
+    const result = buildFormSchema(entity, screen).safeParse({ tags: [] });
+    expect(result.success).toBe(false);
+    if (result.success) return;
+    expect(result.error.issues).toHaveLength(1);
+    expect(result.error.issues[0]?.path).toEqual(["tags"]);
+  });
+
+  test("required multiSelect, non-empty array → no issue", () => {
+    const entity = entityWith({
+      tags: { type: "multiSelect", required: true, options: ["a", "b"] },
+    });
+    const screen = screenWith(["tags"]);
+    expect(buildFormSchema(entity, screen).safeParse({ tags: ["a"] }).success).toBe(true);
+  });
+
+  test("jsonb field → no issue (no editable widget on the auto-wired path)", () => {
+    const entity = entityWith({ data: { type: "jsonb" } });
+    const screen = screenWith(["data"]);
+    expect(buildFormSchema(entity, screen).safeParse({ data: undefined }).success).toBe(true);
+  });
+
+  test("required embedded field → no issue (no editable widget on the auto-wired path)", () => {
+    const entity = entityWith({
+      lines: { type: "embedded", required: true, schema: {} },
+    });
+    const screen = screenWith(["lines"]);
+    expect(buildFormSchema(entity, screen).safeParse({ lines: undefined }).success).toBe(true);
+  });
+
+  test("required files field → no issue (#1925: no multi-upload widget yet, deliberately deferred)", () => {
+    const entity = entityWith({ attachments: { type: "files" } });
+    const screen = screenWith([{ field: "attachments", required: true }]);
+    expect(buildFormSchema(entity, screen).safeParse({ attachments: undefined }).success).toBe(
+      true,
+    );
+  });
+
+  test("required images field → no issue (#1925: no multi-upload widget yet, deliberately deferred)", () => {
+    const entity = entityWith({ gallery: { type: "images" } });
+    const screen = screenWith([{ field: "gallery", required: true }]);
+    expect(buildFormSchema(entity, screen).safeParse({ gallery: undefined }).success).toBe(true);
+  });
+
+  test("required money — bare number (create-form representation) → no issue", () => {
+    const entity = entityWith({ price: { type: "money", required: true } });
+    const screen = screenWith(["price"]);
+    expect(buildFormSchema(entity, screen).safeParse({ price: 1000 }).success).toBe(true);
+  });
+
+  test("required money — {amount,currency} (update-form representation) → no issue", () => {
+    const entity = entityWith({ price: { type: "money", required: true } });
+    const screen = screenWith(["price"]);
+    const result = buildFormSchema(entity, screen).safeParse({
+      price: { amount: 10, currency: "EUR" },
+    });
+    expect(result.success).toBe(true);
+  });
+
+  test("required money — undefined → issue on that field (has a widget)", () => {
+    const entity = entityWith({ price: { type: "money", required: true } });
+    const screen = screenWith(["price"]);
+    const result = buildFormSchema(entity, screen).safeParse({ price: undefined });
+    expect(result.success).toBe(false);
+    if (result.success) return;
+    expect(result.error.issues).toHaveLength(1);
+    expect(result.error.issues[0]?.path).toEqual(["price"]);
+  });
+
+  describe("screen-spec required/readOnly override the entity default", () => {
+    test("spec required:false on an entity-required field, left empty → no issue", () => {
+      const entity = entityWith({ x: { type: "text", required: true } });
+      const screen = screenWith([{ field: "x", required: false }]);
+      expect(buildFormSchema(entity, screen).safeParse({ x: "" }).success).toBe(true);
+    });
+
+    test("spec required:true on an entity-optional field, left empty → issue on that field", () => {
+      const entity = entityWith({ x: { type: "text", required: false } });
+      const screen = screenWith([{ field: "x", required: true }]);
+      const result = buildFormSchema(entity, screen).safeParse({ x: "" });
+      expect(result.success).toBe(false);
+      if (result.success) return;
+      expect(result.error.issues).toHaveLength(1);
+      expect(result.error.issues[0]?.path).toEqual(["x"]);
+    });
+
+    test("readOnly field, entity-required and left empty → no issue (unresolvable by the user)", () => {
+      const entity = entityWith({ x: { type: "text", required: true } });
+      const screen = screenWith([{ field: "x", readOnly: true }]);
+      expect(buildFormSchema(entity, screen).safeParse({ x: "" }).success).toBe(true);
+    });
+
+    test("conditional required, entity-optional field", () => {
+      const entity = entityWith({
+        kind: { type: "text", required: false },
+        x: { type: "text", required: false },
+      });
+      const screen = screenWith([
+        "kind",
+        { field: "x", required: { field: "kind", eq: "business" } },
+      ]);
+
+      const notTriggered = buildFormSchema(entity, screen).safeParse({ kind: "private", x: "" });
+      expect(notTriggered.success).toBe(true);
+
+      const triggered = buildFormSchema(entity, screen).safeParse({ kind: "business", x: "" });
+      expect(triggered.success).toBe(false);
+      if (triggered.success) return;
+      expect(triggered.error.issues).toHaveLength(1);
+      expect(triggered.error.issues[0]?.path).toEqual(["x"]);
+    });
+  });
+});

package/src/app/extension-sections.tsx

@@ -46,6 +46,23 @@ export type ExtensionSectionProps = {
    *  Panels haben keine Entity — entityName/entityId tragen dort die
    *  screen.id bzw. null, siehe CustomPanelBody in dashboard-body.tsx. */
   readonly filterParams?: Readonly<Record<string, unknown>>;
+  /** Current form values of the host RenderEdit (controlled mode,
+   *  issue #1887/#1888) — same snapshot reference as
+   *  `RenderEditChangeState.values`. Lets the section read the host
+   *  form's live state (e.g. for a review step). Only set in
+   *  entityEdit sections; undefined in list-header and dashboard
+   *  mounts, where no host form exists. */
+  readonly values?: Readonly<Record<string, unknown>>;
+  /** Sets host RenderEdit form values from outside (e.g. a VIN-decode
+   *  roundtrip that fills other fields) — same function as
+   *  `RenderEditControls.patch`, merges only the given keys. Undefined
+   *  outside entityEdit sections. */
+  readonly patch?: (partial: Readonly<Record<string, unknown>>) => void;
+  /** Validates the host form without writing — same function as
+   *  `RenderEditControls.validate`; field errors land in
+   *  `snapshot.errors` on the field instead of a collective message.
+   *  Undefined outside entityEdit sections. */
+  readonly validate?: () => boolean;
 };
 
 export type ExtensionSectionComponent = ComponentType<ExtensionSectionProps>;

package/src/app/form-schema.ts

@@ -0,0 +1,90 @@
+import type {
+  EntityDefinition,
+  EntityEditScreenDefinition,
+} from "@cosmicdrift/kumiko-framework/ui-types";
+import { evalFieldCondition } from "@cosmicdrift/kumiko-framework/ui-types";
+import { z } from "zod";
+import { layoutEditFields } from "./layout-fields";
+
+// `required` means "has a value", not "is truthy" — `false` and `0` count
+// as present, only the actually-empty representations don't.
+function isPresent(value: unknown): boolean {
+  if (value === undefined || value === null || value === "") return false;
+  if (Array.isArray(value) && value.length === 0) return false;
+  return true;
+}
+
+// Field types without a bound, editable widget on the auto-wired
+// entityEdit path (render-field.tsx renders a read-only banner instead) —
+// a presence error on one of them would be unresolvable by the user.
+// #1925 gave multiSelect/decimal/bigInt/tz/longText real widgets, so they
+// dropped out of this set; files/images stay out of scope (deferred, no
+// multi-upload widget yet) alongside jsonb/embedded (structural types with
+// no editor at all). A statically-`required: true` field of one of these
+// types is caught loudly at boot — validateNoWidgetRequiredField in
+// packages/framework/src/engine/boot-validator/screens.ts, which mirrors
+// this set (framework can't import renderer, so it can't import this
+// constant directly — keep both in sync).
+const FIELD_TYPES_WITHOUT_WIDGET = new Set(["jsonb", "embedded", "files", "images"]);
+
+// Client-side presence validation for the auto-wired entityEdit path —
+// checks that every rendered required field HAS a value, not that the
+// value has the right shape. Format/range/type validation stays server-
+// authoritative (buildInsertSchema/buildUpdateSchema): the form-state
+// representation of a value can diverge from the server-payload shape (e.g.
+// money is `{amount,currency}`, not a bare number), so a format check here
+// would either reject valid values or need per-representation branches that
+// rot the moment either side changes.
+//
+// One `superRefine` instead of a per-field shape: a field-level `.refine()`
+// wouldn't run at all for a key that's simply absent from `values` —
+// `superRefine` sees the whole object and catches that case too.
+// `.passthrough()` is load-bearing: the default `z.object({})` STRIPS every
+// key (there's no declared shape), so `superRefine` would see an empty
+// object regardless of what was actually submitted — every required field
+// would misreport as missing.
+//
+// Iterates the screen's layout field specs, not `entity.fields` — `required`
+// and `readOnly` are per-spec, evaluated against the current values the
+// same way `view-model/edit.ts` resolves them for the rendered form. Not
+// checked here: `visible`. `runValidate` already filters issues on hidden
+// fields via `computeFieldStates(options.fields, …)` (form-controller.ts:163,181),
+// fed by `deriveFormFields(screen)` in render-edit.tsx.
+export function buildFormSchema(
+  entity: EntityDefinition,
+  screen: EntityEditScreenDefinition,
+): z.ZodType {
+  const fields = layoutEditFields(screen);
+  return z
+    .object({})
+    .passthrough()
+    .superRefine((values, ctx) => {
+      // `.passthrough()` types `values` as a plain object but doesn't declare
+      // its keys — the runtime object always carries every form field.
+      // @cast-boundary form-values
+      const record = values as Record<string, unknown>;
+      for (const spec of fields) {
+        const field = entity.fields[spec.field];
+        if (!field) continue;
+        // Not operable by the user — a presence error would be unresolvable,
+        // same reason as the FIELD_TYPES_WITHOUT_WIDGET check below.
+        if (spec.readOnly !== undefined && evalFieldCondition(spec.readOnly, record)) continue;
+        // Screen-spec `required` overrides the entity default, mirroring
+        // `view-model/edit.ts` — the rendered form is the reference, and a
+        // presence check stricter than the form blocks the user for nothing.
+        const entityRequired = "required" in field && field.required === true;
+        const isRequired =
+          spec.required === undefined ? entityRequired : evalFieldCondition(spec.required, record);
+        if (!isRequired) continue;
+        if (FIELD_TYPES_WITHOUT_WIDGET.has(field.type)) continue;
+        if (isPresent(record[spec.field])) continue;
+        ctx.addIssue({
+          code: "custom",
+          path: [spec.field],
+          message: `"${spec.field}" is required.`,
+          // `params.i18nKey` override, see packages/headless/src/form/zod-bridge.ts.
+          params: { i18nKey: "kumiko.validation.required" },
+        });
+      }
+    });
+}