@cosmicdrift/kumiko-renderer 0.187.0 → 0.188.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-renderer",
-  "version": "0.187.0",
+  "version": "0.188.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.188.0",
+    "@cosmicdrift/kumiko-headless": "0.188.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,165 @@
+import { describe, expect, test } from "bun:test";
+import type {
+  EditFieldSpec,
+  EntityDefinition,
+  EntityEditScreenDefinition,
+} from "@cosmicdrift/kumiko-framework/ui-types";
+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"]);
+      });
+    }
+  });
+
+  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 → no issue (no editable widget on the auto-wired path)", () => {
+    const entity = entityWith({
+      tags: { type: "multiSelect", required: true, options: ["a", "b"] },
+    });
+    const screen = screenWith(["tags"]);
+    expect(buildFormSchema(entity, screen).safeParse({ tags: undefined }).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 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,82 @@
+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.
+// Tracked in #1925 (field types without an operable widget). `money` has an
+// operable widget (MoneyInput) and stays out of this set.
+const FIELD_TYPES_WITHOUT_WIDGET = new Set(["multiSelect", "jsonb", "embedded"]);
+
+// 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.`,
+        });
+      }
+    });
+}

package/src/app/kumiko-screen.tsx

@@ -15,11 +15,7 @@ import type {
   ScreenDefinition,
   ToolbarAction,
 } from "@cosmicdrift/kumiko-framework/ui-types";
-import {
-  evalFieldCondition,
-  isExtensionEditSection,
-  normalizeEditField,
-} from "@cosmicdrift/kumiko-framework/ui-types";
+import { evalFieldCondition } from "@cosmicdrift/kumiko-framework/ui-types";
 import type {
   Command,
   FormSnapshot,
@@ -43,6 +39,8 @@ import { synthesizeConfigEditEntity, synthesizeConfigEditScreen } from "./config
 import { useCustomScreenComponent } from "./custom-screens";
 import { useDashboardBody } from "./dashboard-body";
 import type { FeatureSchema } from "./feature-schema";
+import { buildFormSchema } from "./form-schema";
+import { layoutFieldNames } from "./layout-fields";
 import { useNav } from "./nav";
 import {
   synthesizeProjectionDetailEntity,
@@ -310,8 +308,15 @@ function useNavigateToCreateFor(
 // with a `default: true`/`default: 5` would show the form in a state
 // the entity didn't ask for — subtle and easy to miss until a user
 // submits and is surprised.
+// `defaultCurrency` is only passed by entityEdit call sites — the money
+// payload shape it enables (`{amount, currency}`) matches the entity's
+// write schema (schema-builder.ts, kumiko-framework#1923). Callers outside
+// that path (config-edit, action-form) synthesize their own entity and use
+// money as a plain number against a different write contract, so they
+// deliberately keep the old bare-`0` default by omitting the argument.
 export function buildInitialValues(
   fields: Readonly<Record<string, unknown>>,
+  defaultCurrency?: string,
 ): Readonly<Record<string, unknown>> {
   const out: Record<string, unknown> = {};
   for (const [name, def] of Object.entries(fields)) {
@@ -320,33 +325,23 @@ export function buildInitialValues(
       out[name] = shape.default;
       continue;
     }
+    if (shape.type === "money" && defaultCurrency !== undefined) {
+      out[name] = { amount: 0, currency: defaultCurrency };
+      continue;
+    }
     out[name] =
       shape.type === "boolean" ? false : shape.type === "number" || shape.type === "money" ? 0 : "";
   }
   return out;
 }
 
-// Field names actually rendered by the screen's layout — a search-param
-// merge must not set fields the form never shows the user (#1708:
-// unrendered fields get no client-side validation and no chance to
-// review/correct the injected value).
-function layoutFieldNames(screen: EntityEditScreenDefinition): ReadonlySet<string> {
-  const names = new Set<string>();
-  for (const section of screen.layout.sections) {
-    if (isExtensionEditSection(section)) continue;
-    for (const spec of section.fields) {
-      names.add(normalizeEditField(spec).field);
-    }
-  }
-  return names;
-}
-
 export function mergeSearchParamsIntoInitial(
   fields: Readonly<Record<string, unknown>>,
   searchParams: Readonly<Record<string, string>>,
   renderableFields?: ReadonlySet<string>,
+  defaultCurrency?: string,
 ): Record<string, unknown> {
-  const defaults = buildInitialValues(fields) as Record<string, unknown>;
+  const defaults = buildInitialValues(fields, defaultCurrency) as Record<string, unknown>;
   const merged: Record<string, unknown> = { ...defaults };
   for (const [name, fieldDef] of Object.entries(fields)) {
     if (renderableFields !== undefined && !renderableFields.has(name)) continue;
@@ -354,9 +349,16 @@ export function mergeSearchParamsIntoInitial(
     if (shape.sensitive === true) continue;
     const raw = searchParams[name];
     if (raw === undefined) continue;
-    if (shape.type === "number" || shape.type === "money") {
+    if (shape.type === "number") {
       const parsed = Number(raw);
       merged[name] = Number.isNaN(parsed) ? defaults[name] : parsed;
+    } else if (shape.type === "money") {
+      const parsed = Number(raw);
+      merged[name] = Number.isNaN(parsed)
+        ? defaults[name]
+        : defaultCurrency !== undefined
+          ? { amount: parsed, currency: defaultCurrency }
+          : parsed;
     } else if (shape.type === "boolean") {
       merged[name] = raw === "true";
     } else {
@@ -443,9 +445,11 @@ function EntityEditCreateBody({
         entity.fields,
         nav.searchParams,
         layoutFieldNames(screen),
+        entity.defaultCurrency ?? "EUR",
       ) as FormValues,
-    [entity.fields, nav.searchParams, screen],
+    [entity.fields, nav.searchParams, screen, entity.defaultCurrency],
   );
+  const formSchema = useMemo(() => buildFormSchema(entity, screen), [entity, screen]);
   const writeCommand = entityWriteCommand(schema.featureName, screen.entity, "create");
   const navigateToList = useNavigateToListAfter(schema, screen.entity);
   const handleSubmitted = useCallback(
@@ -460,6 +464,7 @@ function EntityEditCreateBody({
       entity={entity}
       featureName={schema.featureName}
       initial={initial}
+      schema={formSchema}
       writeCommand={writeCommand}
       onSubmit={handleSubmitted}
       onCancel={navigateToList}
@@ -566,11 +571,15 @@ function EntityEditUpdateForm({
   const recordVersion = (record as { version?: number }).version ?? 1;
   const initial = useMemo(() => {
     const out: Record<string, unknown> = {};
+    const defaultCurrency = entity.defaultCurrency ?? "EUR";
     for (const name of Object.keys(entity.fields)) {
-      out[name] = record[name] ?? buildInitialValues({ [name]: entity.fields[name] })[name];
+      out[name] =
+        record[name] ?? buildInitialValues({ [name]: entity.fields[name] }, defaultCurrency)[name];
     }
     return out as FormValues;
-  }, [entity.fields, record]);
+  }, [entity.fields, entity.defaultCurrency, record]);
+
+  const formSchema = useMemo(() => buildFormSchema(entity, screen), [entity, screen]);
 
   // Extension-Werte (z.B. customFields-jsonb) an extension-sections geben,
   // damit sie beim Edit den Bestand zeigen statt write-only zu sein.
@@ -619,6 +628,7 @@ function EntityEditUpdateForm({
       // customFields-Bestand an die extension-section, damit sie beim Edit
       // die gespeicherten Werte zeigt (nicht write-only).
       extensionInitialValues={extensionInitialValues}
+      schema={formSchema}
       writeCommand={writeCommand}
       payloadMode="changes"
       buildPayload={buildPayload}
@@ -1513,6 +1523,19 @@ type ConfigValueResponse = Readonly<
   Record<string, { value: string | number | boolean | undefined; scope: string; source: string }>
 >;
 
+// A money-typed config-edit field renders through RenderField's entityEdit
+// `{amount, currency}` payload shape (render-field.tsx, #1923), but
+// `ConfigKeyType` (write-helpers.ts validateType) only ever knows
+// number/boolean/text/select — a config value is always a bare scalar.
+// Unwrap back to the amount before it hits config:write:set.
+function unwrapMoneyValue(value: unknown): unknown {
+  if (typeof value === "object" && value !== null && "amount" in value) {
+    const amount = (value as { amount?: unknown }).amount;
+    if (typeof amount === "number") return amount;
+  }
+  return value;
+}
+
 function ConfigEditBody({
   schema,
   screen,
@@ -1604,9 +1627,14 @@ function ConfigEditBody({
       for (const [shortName, value] of Object.entries(snapshot.changes)) {
         const qualified = screen.configKeys[shortName];
         if (qualified === undefined) continue;
+        const ftype = (screen.fields[shortName] as { type?: string } | undefined)?.type;
         commands.push({
           type: "config:write:set",
-          payload: { key: qualified, value, scope: screen.scope },
+          payload: {
+            key: qualified,
+            value: ftype === "money" ? unwrapMoneyValue(value) : value,
+            scope: screen.scope,
+          },
         });
       }
       if (commands.length === 0) {
@@ -1623,7 +1651,14 @@ function ConfigEditBody({
       await Promise.allSettled([valuesQuery.refetch?.(), cascadeQuery.refetch?.()]);
       return { validationBlocked: false, isSuccess: true, data: undefined };
     },
-    [dispatcher, screen.configKeys, screen.scope, valuesQuery.refetch, cascadeQuery.refetch],
+    [
+      dispatcher,
+      screen.configKeys,
+      screen.fields,
+      screen.scope,
+      valuesQuery.refetch,
+      cascadeQuery.refetch,
+    ],
   );
 
   // Cascade-Disclosure (#429): Trigger sitzt in der Label-Row, das Panel

package/src/app/layout-fields.ts

@@ -0,0 +1,27 @@
+import type {
+  EditFieldSpec,
+  EntityEditScreenDefinition,
+} from "@cosmicdrift/kumiko-framework/ui-types";
+import { isExtensionEditSection, normalizeEditField } from "@cosmicdrift/kumiko-framework/ui-types";
+
+// Normalized field specs actually rendered by the screen's layout, extension
+// sections skipped. Both this and `layoutFieldNames` key off "rendered by
+// the layout" for the same reason: a field the user never sees gets no
+// chance to review/correct a value nor to fix a presence error
+// (search-param merge, #1708; presence schema in form-schema.ts).
+export function layoutEditFields(
+  screen: EntityEditScreenDefinition,
+): readonly Exclude<EditFieldSpec, string>[] {
+  const specs: Exclude<EditFieldSpec, string>[] = [];
+  for (const section of screen.layout.sections) {
+    if (isExtensionEditSection(section)) continue;
+    for (const spec of section.fields) {
+      specs.push(normalizeEditField(spec));
+    }
+  }
+  return specs;
+}
+
+export function layoutFieldNames(screen: EntityEditScreenDefinition): ReadonlySet<string> {
+  return new Set(layoutEditFields(screen).map((spec) => spec.field));
+}

package/src/components/__tests__/render-edit-logic.test.ts

@@ -6,6 +6,7 @@ import type {
   SubmitResult,
 } from "@cosmicdrift/kumiko-headless";
 import {
+  filterEditSections,
   hasEditableSection,
   resolveExtensionEntityId,
   shouldNotifyCaller,
@@ -177,3 +178,50 @@ describe("hasEditableSection", () => {
     expect(hasEditableSection([section])).toBe(false);
   });
 });
+
+const namedField = (name: string): EditFieldViewModel => ({
+  field: name,
+  label: name,
+  type: "text",
+  value: "",
+  visible: true,
+  readOnly: false,
+  required: false,
+});
+const namedFieldsSection = (...names: string[]): EditSectionViewModel => ({
+  kind: "fields",
+  columns: 1,
+  visible: true,
+  fields: names.map(namedField),
+});
+
+describe("filterEditSections", () => {
+  test("fieldsFilter undefined → returns the same array reference (unchanged behavior)", () => {
+    const sections = [namedFieldsSection("a", "b")];
+    expect(filterEditSections(sections, undefined)).toBe(sections);
+  });
+
+  test("mixed section → only the filtered-in fields remain in section.fields", () => {
+    const sections = [namedFieldsSection("a", "b", "c")];
+    const result = filterEditSections(sections, ["a", "c"]);
+    expect(result).toHaveLength(1);
+    expect(result[0]?.kind).toBe("fields");
+    expect(result[0]?.kind === "fields" ? result[0].fields.map((f) => f.field) : []).toEqual([
+      "a",
+      "c",
+    ]);
+  });
+
+  test("section whose filtered field list becomes empty is dropped entirely, not rendered empty", () => {
+    const sections = [namedFieldsSection("a", "b"), namedFieldsSection("c")];
+    const result = filterEditSections(sections, ["c"]);
+    expect(result).toHaveLength(1);
+    expect(result[0]?.kind === "fields" ? result[0].fields.map((f) => f.field) : []).toEqual(["c"]);
+  });
+
+  test("extension section always survives the filter regardless of its content", () => {
+    const sections = [extensionSection, namedFieldsSection("a")];
+    const result = filterEditSections(sections, ["zzz"]);
+    expect(result).toEqual([extensionSection]);
+  });
+});