@cosmicdrift/kumiko-headless 0.220.1 → 0.222.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-headless",
-  "version": "0.220.1",
+  "version": "0.222.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.220.1",
+    "@cosmicdrift/kumiko-framework": "0.222.0",
     "temporal-polyfill": "^0.3.2",
     "zod": "^4.4.3"
   },

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

@@ -35,13 +35,41 @@ describe("createFormController — submit()", () => {
     await expect(form.submit()).rejects.toThrow(/submit\(\) called without a `submit` config/);
   });
 
-  test("throws when submit-config has no dispatcher — forgot the provider", async () => {
+  test("returns isSuccess:false when submit-config has no dispatcher — forgot the provider", async () => {
     const form = createFormController({
       initial: { title: "hello" },
       submit: { type: "app:write:task:create" },
     });
 
-    await expect(form.submit()).rejects.toThrow(/submit\(\) called without a dispatcher/);
+    const result = await form.submit();
+    expect(result.validationBlocked).toBe(false);
+    expect(result.isSuccess).toBe(false);
+    if (result.isSuccess || result.validationBlocked) throw new Error("expected write failure");
+    expect(result.error.message).toMatch(/submit\(\) called without a dispatcher/);
+  });
+
+  test("returns validationBlocked without a dispatcher when schema fails first", async () => {
+    const form = createFormController({
+      initial: { title: "" },
+      schema: z.object({ title: z.string().min(3) }),
+      submit: { type: "app:write:task:create" },
+    });
+
+    const result = await form.submit();
+    expect(result.validationBlocked).toBe(true);
+  });
+
+  test("returns isNoOp without a dispatcher when payloadMode changes is empty", async () => {
+    const form = createFormController({
+      initial: { title: "hello" },
+      submit: { type: "app:write:task:update", payloadMode: "changes" },
+    });
+
+    const result = await form.submit();
+    expect(result.validationBlocked).toBe(false);
+    if (!result.validationBlocked) {
+      expect(result.isNoOp).toBe(true);
+    }
   });
 
   test("happy path: dispatches values, returns success, rebases form", async () => {
@@ -446,4 +474,41 @@ describe("createFormController — submit()", () => {
     expect(result.validationBlocked).toBe(true);
     expect(disp.writeSpy).not.toHaveBeenCalled();
   });
+
+  test("cross-field refine still blocks submit when validateScope is set (#1907)", async () => {
+    const schema = z
+      .object({ title: z.string().min(1), note: z.string() })
+      .refine((v) => v.title !== v.note, { message: "title and note must differ" });
+    const disp = makeDispatcher();
+    const form = createFormController({
+      initial: { title: "same", note: "same" },
+      schema,
+      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();
+  });
+
+  test("intentional empty clear survives second submit after rebase (#1858)", async () => {
+    const schema = z.object({ title: z.string().min(1), note: z.string().optional() });
+    const disp = makeDispatcher();
+    const form = createFormController({
+      initial: { title: "t", note: "x" },
+      schema,
+      submit: { dispatcher: disp, type: "app:write:task:create" },
+    });
+    form.setField("note", "");
+    const first = await form.submit();
+    expect(first.isSuccess).toBe(true);
+    expect(disp.writeSpy.mock.calls[0]?.[1]).toMatchObject({ note: "" });
+    form.setField("title", "t2");
+    const second = await form.submit();
+    expect(second.isSuccess).toBe(true);
+    expect(disp.writeSpy.mock.calls[1]?.[1]).toMatchObject({ note: "" });
+  });
 });

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

@@ -187,6 +187,18 @@ describe("createFormController — validate(scope)", () => {
     expect(form.getSnapshot().errors).toEqual({});
   });
 
+  test("nested scope path matches issue root segment (#1898)", () => {
+    const schema = z.object({
+      address: z.object({ city: z.string().min(1) }),
+    });
+    const form = createFormController({
+      initial: { address: { city: "" } },
+      schema,
+    });
+    expect(form.validate(["address.city"])).toBe(false);
+    expect(form.getSnapshot().errors["address.city"]).toBeDefined();
+  });
+
   // 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

package/src/form/form-controller.ts

@@ -84,12 +84,15 @@ function valuesDiff<TValues extends FormValues>(
 function stripUntouchedEmptyStrings<TValues extends FormValues>(
   values: TValues,
   initial: TValues,
+  forceIncludeEmpty: ReadonlySet<string>,
 ): TValues {
   const v = values as Record<string, unknown>; // @cast-boundary form-values
   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] === "" && ini[key] === "") {
+    // Value-based seed strip, except keys previously submitted as "" after a
+    // real clear — those must survive post-rebase submits (#1858).
+    if (!forceIncludeEmpty.has(key) && v[key] === "" && ini[key] === "") {
       out ??= { ...v };
       delete out[key];
     }
@@ -118,6 +121,9 @@ export function createFormController<TValues extends FormValues, TCtx = unknown>
   let values: TValues = { ...options.initial };
   let initial: TValues = { ...options.initial };
   let errors: Readonly<Record<string, readonly FieldIssue[]>> = Object.freeze({});
+  // Keys last submitted as "" (intentional clear). Survives rebase so a later
+  // submit of other fields does not drop them (#1858).
+  const forceIncludeEmpty = new Set<string>();
   // ctx is cast-held as TCtx; `undefined` is valid when callers don't
   // declare conditional predicates that depend on it.
   let ctx: TCtx = (options.ctx as TCtx) ?? (undefined as TCtx);
@@ -178,9 +184,16 @@ export function createFormController<TValues extends FormValues, TCtx = unknown>
     errors = Object.freeze(merged);
   }
 
-  function runValidate(scope?: readonly string[]): boolean {
+  function runValidate(
+    scope?: readonly string[],
+    opts?: { readonly includeRoot?: boolean },
+  ): boolean {
     // See the validate() doc comment in types.ts for the scope contract.
-    const scopeSet = scope === undefined ? undefined : new Set(scope);
+    // Normalize nested scope entries (`address.city` → `address`) so wizard
+    // callers that pass dotted paths still match issue root segments (#1898).
+    const scopeSet =
+      scope === undefined ? undefined : new Set(scope.map((s) => s.split(".")[0] ?? s));
+    const includeRoot = opts?.includeRoot === true;
     if (!options.schema) {
       if (Object.keys(errors).length > 0) {
         replaceScopedErrors(scopeSet, {});
@@ -205,7 +218,13 @@ export function createFormController<TValues extends FormValues, TCtx = unknown>
     const relevantIssues = allIssues.filter((issue) => {
       const rootField = issue.path.split(".")[0] ?? "";
       if (hiddenFields.has(rootField)) return false;
-      if (scopeSet && !scopeSet.has(rootField)) return false;
+      // Root-level .refine() issues use path "(root)". Wizard step validate()
+      // still drops them (#1885); submit() passes includeRoot so RenderEdit
+      // fields={…} cannot silently skip cross-field rules (#1907).
+      const isRootIssue = issue.path === "(root)";
+      if (scopeSet && !(includeRoot && isRootIssue) && !scopeSet.has(rootField)) {
+        return false;
+      }
       return true;
     });
     if (relevantIssues.length === 0) {
@@ -295,6 +314,7 @@ export function createFormController<TValues extends FormValues, TCtx = unknown>
       if (alreadyClean) return;
       values = { ...initial };
       errors = Object.freeze({});
+      forceIncludeEmpty.clear();
       invalidate();
     },
     rebase: runRebase,
@@ -322,7 +342,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(submitCfg.validateScope)) {
+      if (!runValidate(submitCfg.validateScope, { includeRoot: true })) {
         return { validationBlocked: true, isSuccess: false };
       }
 
@@ -355,7 +375,11 @@ export function createFormController<TValues extends FormValues, TCtx = unknown>
       } else if (submitCfg.stripEmptySeeds === false) {
         payload = submittedValues;
       } else {
-        payload = stripUntouchedEmptyStrings(submittedValues, submittedSnapshot.initial);
+        payload = stripUntouchedEmptyStrings(
+          submittedValues,
+          submittedSnapshot.initial,
+          forceIncludeEmpty,
+        );
       }
 
       // Only enforced here, right before the write actually happens — a
@@ -364,15 +388,33 @@ export function createFormController<TValues extends FormValues, TCtx = unknown>
       // dispatcher was ever wired up.
       const dispatcher = submitCfg.dispatcher;
       if (!dispatcher) {
-        throw new Error(
-          "createFormController: submit() called without a dispatcher. Pass `submit.dispatcher` explicitly, or mount a <DispatcherProvider> above this form.",
-        );
+        // Return SubmitResult (not throw) so RenderEdit's banner path shows
+        // the misconfiguration instead of an unhandled rejection on save.
+        return {
+          validationBlocked: false,
+          isSuccess: false,
+          isNoOp: false,
+          error: {
+            code: "misconfigured",
+            httpStatus: 500,
+            i18nKey: "errors.internal",
+            message:
+              "createFormController: submit() called without a dispatcher (dispatcher was absent when the form mounted). Pass `submit.dispatcher` explicitly, or mount a <DispatcherProvider> above this form.",
+          },
+        };
       }
 
       const runWrite = async (): Promise<SubmitResult<TData>> => {
         const result = await dispatcher.write<TData>(submitCfg.type, payload);
 
         if (result.isSuccess) {
+          // Remember intentional empty clears so post-rebase submits keep them (#1858).
+          if (payload && typeof payload === "object" && !Array.isArray(payload)) {
+            for (const [k, v] of Object.entries(payload as Record<string, unknown>)) {
+              if (v === "") forceIncludeEmpty.add(k);
+              else forceIncludeEmpty.delete(k);
+            }
+          }
           // Rebase to the SNAPSHOT, not to the current values — see
           // runRebaseToSnapshot comment for why.
           runRebaseToSnapshot(submittedValues);

package/src/form/types.ts

@@ -143,8 +143,10 @@ export type FormController<TValues extends FormValues> = {
   // relies entirely on server-side validation via the submit() path.
   //
   // `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.
+  // `.refine()` issues (path `(root)`) are dropped on scoped `validate()`
+  // calls (wizard steps, #1885). `submit()` always re-includes them even
+  // when `validateScope` is set so RenderEdit `fields={…}` cannot skip
+  // cross-field rules (#1907).
   validate(scope?: readonly string[]): boolean;
 
   // Reverts values to `initial`, clears errors. Doesn't fire a new

package/src/format/__tests__/format.test.ts

@@ -1,5 +1,5 @@
 import { describe, expect, test } from "bun:test";
-import { applyFormatSpec } from "../index";
+import { applyFormatSpec, UNIT_FORMAT_KEYS } from "../index";
 
 describe("applyFormatSpec — priority", () => {
   test("rendert emptyLabel für undefined/null/leer/0 (nicht den globalen ''-Collapse)", () => {
@@ -111,6 +111,14 @@ describe("applyFormatSpec — unit (fw#2187)", () => {
         unitDisplay: "short",
       }).format(12),
     );
+    // Ratio 0.15 must NOT become 15 % — unit:"percent" is percent-points.
+    expect(applyFormatSpec({ format: "unit", unit: "percent", locale: "de-DE" }, 0.15)).toBe(
+      new Intl.NumberFormat("de-DE", {
+        style: "unit",
+        unit: "percent",
+        unitDisplay: "short",
+      }).format(0.15),
+    );
   });
 
   test("m2 hat kein ECMA-402-sanktioniertes Intl-Unit (RangeError für 'square-meter') — Zahl + literales Suffix", () => {
@@ -189,3 +197,18 @@ describe("applyFormatSpec — enumOption (fw#2315)", () => {
     expect(applyFormatSpec(spec, "", (k) => k)).toBe("");
   });
 });
+
+describe("unit format keys stay in lockstep with UnitKey", () => {
+  // Mirror of packages/types/src/screen.ts UnitKey — keep lists equal without
+  // adding a kumiko-types dependency to headless.
+  const TYPE_UNIT_KEYS = ["m2", "km", "m", "kg", "percent"] as const;
+  test("every UnitKey formats with a non-bare number", () => {
+    for (const k of TYPE_UNIT_KEYS) {
+      expect(UNIT_FORMAT_KEYS.includes(k)).toBe(true);
+      expect(applyFormatSpec({ format: "unit", unit: k }, 1)).not.toBe("1");
+    }
+  });
+  test("no extra runtime keys beyond UnitKey", () => {
+    expect([...UNIT_FORMAT_KEYS].sort()).toEqual([...TYPE_UNIT_KEYS].sort());
+  });
+});

package/src/format/index.ts

@@ -97,12 +97,12 @@ const UNIT_INTL_IDS = {
 // the literal suffix instead of going through `style: "unit"`.
 const UNIT_SUFFIXES = { m2: "m²" } as const;
 
-type UnitKey = keyof typeof UNIT_INTL_IDS | keyof typeof UNIT_SUFFIXES;
+function isIntlUnit(unit: string): unit is keyof typeof UNIT_INTL_IDS {
+  return Object.hasOwn(UNIT_INTL_IDS, unit);
+}
 
-function isUnitKey(unit: string): unit is UnitKey {
-  // Object.hasOwn, not `in` — `in` walks the prototype chain, so
-  // "toString" or "constructor" would pass as a valid unit key.
-  return Object.hasOwn(UNIT_INTL_IDS, unit) || Object.hasOwn(UNIT_SUFFIXES, unit);
+function isSuffixUnit(unit: string): unit is keyof typeof UNIT_SUFFIXES {
+  return Object.hasOwn(UNIT_SUFFIXES, unit);
 }
 
 function formatUnitCell(
@@ -112,12 +112,12 @@ function formatUnitCell(
   unitDisplay: Intl.NumberFormatOptions["unitDisplay"],
 ): string {
   const n = typeof value === "number" ? value : Number(value);
-  if (unit === undefined || !isUnitKey(unit) || !Number.isFinite(n)) return String(value);
-  if (Object.hasOwn(UNIT_INTL_IDS, unit)) {
+  if (unit === undefined || !Number.isFinite(n)) return String(value);
+  if (isIntlUnit(unit)) {
     try {
       return new Intl.NumberFormat(locale, {
         style: "unit",
-        unit: UNIT_INTL_IDS[unit as keyof typeof UNIT_INTL_IDS],
+        unit: UNIT_INTL_IDS[unit],
         unitDisplay,
       }).format(n);
     } catch {
@@ -125,9 +125,18 @@ function formatUnitCell(
       return formatNumberCell(n, locale);
     }
   }
-  return `${formatNumberCell(n, locale)} ${UNIT_SUFFIXES[unit as keyof typeof UNIT_SUFFIXES]}`;
+  if (isSuffixUnit(unit)) {
+    return `${formatNumberCell(n, locale)} ${UNIT_SUFFIXES[unit]}`;
+  }
+  return String(value);
 }
 
+/** Exported for UnitKey parity tests against @cosmicdrift/kumiko-types/screen. */
+export const UNIT_FORMAT_KEYS = [
+  ...Object.keys(UNIT_INTL_IDS),
+  ...Object.keys(UNIT_SUFFIXES),
+] as const;
+
 export { escapeHtml, escapeHtmlAttr, escapeXml, isSafeHref, stripControlChars } from "./escape";
 export { type HtmlValue, html, RawHtml, raw } from "./html-template";
 export { currencyDecimals } from "./money";

package/src/index.ts

@@ -110,6 +110,7 @@ export {
   embeddedCellOptionLabelKey,
   fieldLabelKey,
   fieldOptionLabelKey,
+  fieldOptionLabelKeyPrefix,
   groupEmbeddedListIssues,
   roundDerivedCellValue,
   sumEmbeddedListColumn,

package/src/locale-routing/__tests__/locale-routing.test.ts

@@ -198,6 +198,37 @@ describe("wrapUrlLocaleResolver", () => {
     expect(wrapped.locale()).toBe("de");
   });
 
+  test("missing pathname falls back to base locale (no fake /)", () => {
+    const wrapped = wrapUrlLocaleResolver(staticBase("en"), {
+      resolvePage: (pathname) => moneyHorseRouter.resolvePage(pathname),
+      detectLang: (pathname) => moneyHorseRouter.detectLang(pathname),
+      pathname: () => undefined,
+    });
+    expect(wrapped.locale()).toBe("en");
+  });
+
+  test("subscribe fires on pathname subscription", () => {
+    let pathListener: (() => void) | undefined;
+    const wrapped = wrapUrlLocaleResolver(staticBase("de"), {
+      resolvePage: () => "home",
+      detectLang: () => "en",
+      pathname: () => "/en",
+      subscribePathname: (listener) => {
+        pathListener = listener;
+        return () => {
+          pathListener = undefined;
+        };
+      },
+    });
+    let hits = 0;
+    const unsub = wrapped.subscribe(() => {
+      hits += 1;
+    });
+    pathListener?.();
+    expect(hits).toBe(1);
+    unsub();
+  });
+
   test("unregistered path keeps base locale", () => {
     const wrapped = wrapUrlLocaleResolver(staticBase("de"), {
       resolvePage: (pathname) => moneyHorseRouter.resolvePage(pathname),
@@ -218,4 +249,28 @@ describe("wrapUrlLocaleResolver", () => {
     expect(base.locale()).toBe("en");
     expect(wrapped.locale()).toBe("en");
   });
+
+  test("URL locale wins over sticky setLocale on a registered path", () => {
+    const base = staticBase("de");
+    const wrapped = wrapUrlLocaleResolver(base, {
+      resolvePage: (pathname) => moneyHorseRouter.resolvePage(pathname),
+      detectLang: (pathname) => moneyHorseRouter.detectLang(pathname),
+      pathname: () => "/en/features",
+    });
+    wrapped.setLocale?.("de");
+    expect(base.locale()).toBe("de");
+    expect(wrapped.locale()).toBe("en");
+  });
+
+  test("translateFor resolves copy against the URL locale", () => {
+    const base = staticBase("de");
+    const wrapped = wrapUrlLocaleResolver(base, {
+      resolvePage: (pathname) => moneyHorseRouter.resolvePage(pathname),
+      detectLang: (pathname) => moneyHorseRouter.detectLang(pathname),
+      pathname: () => "/en/features",
+      translateFor: (locale, key) => `${locale}:${key}`,
+    });
+    expect(wrapped.translate("hello")).toBe("en:hello");
+    expect(wrapped.locale()).toBe("en");
+  });
 });

package/src/locale-routing/index.ts

@@ -146,36 +146,73 @@ export function createLocaleRouter<TPage extends string>(
 }
 
 export type WrapUrlLocaleResolverOptions = {
-  resolvePage: (pathname: string) => unknown;
+  resolvePage: (pathname: string) => string | undefined;
   detectLang: (pathname: string) => string;
-  pathname?: () => string;
+  pathname?: () => string | undefined;
+  /** Optional pathname-change subscription (browser default: popstate). */
+  subscribePathname?: (listener: () => void) => () => void;
+  /** When set, translate against the URL-resolved locale instead of base.translate
+   *  (needed for fixed-T / cloneInstance resolvers that are not locale-live). */
+  translateFor?: (
+    locale: string,
+    key: string,
+    params?: Readonly<Record<string, unknown>>,
+  ) => string;
 };
 
-function defaultBrowserPathname(): string {
+function defaultBrowserPathname(): string | undefined {
   const loc = (globalThis as { location?: { pathname?: string } }).location;
-  return typeof loc?.pathname === "string" ? loc.pathname : "/";
+  return typeof loc?.pathname === "string" ? loc.pathname : undefined;
+}
+
+function defaultSubscribePathname(listener: () => void): () => void {
+  const g = globalThis as {
+    addEventListener?: typeof addEventListener;
+    removeEventListener?: typeof removeEventListener;
+  };
+  if (typeof g.addEventListener !== "function" || typeof g.removeEventListener !== "function") {
+    return () => {};
+  }
+  g.addEventListener("popstate", listener);
+  return () => {
+    g.removeEventListener?.("popstate", listener);
+  };
 }
 
 /**
  * Prefer URL-derived locale when `resolvePage` matches the current path;
  * otherwise defer to `base.locale()`. Passes through setLocale and the rest of LocaleResolver.
+ * Without `translateFor`, `base.translate` must already be locale-live.
  */
 export function wrapUrlLocaleResolver(
   base: LocaleResolver,
   options: WrapUrlLocaleResolverOptions,
 ): LocaleResolver {
   const getPathname = options.pathname ?? defaultBrowserPathname;
+  const subscribePathname = options.subscribePathname ?? defaultSubscribePathname;
+  const resolveLocale = (): string => {
+    const path = getPathname();
+    if (path === undefined) return base.locale();
+    if (options.resolvePage(path) != null) {
+      return options.detectLang(path);
+    }
+    return base.locale();
+  };
   return {
-    translate: (key, params) => base.translate(key, params),
+    translate: (key, params) =>
+      options.translateFor
+        ? options.translateFor(resolveLocale(), key, params)
+        : base.translate(key, params),
     timeZone: () => base.timeZone(),
-    subscribe: (listener) => base.subscribe(listener),
-    setLocale: base.setLocale !== undefined ? (locale) => base.setLocale?.(locale) : undefined,
-    locale: () => {
-      const path = getPathname();
-      if (options.resolvePage(path) !== undefined) {
-        return options.detectLang(path);
-      }
-      return base.locale();
+    subscribe: (listener) => {
+      const unsubBase = base.subscribe(listener);
+      const unsubPath = subscribePathname(listener);
+      return () => {
+        unsubBase();
+        unsubPath();
+      };
     },
+    setLocale: base.setLocale !== undefined ? (locale) => base.setLocale?.(locale) : undefined,
+    locale: resolveLocale,
   };
 }

package/src/view-model/edit.ts

@@ -178,7 +178,8 @@ export function computeEditViewModel<
           : undefined;
       // 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";
+      const isFileType =
+        fieldDef.type === "file" || fieldDef.type === "image" || fieldDef.type === "images";
       // 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
@@ -193,7 +194,9 @@ export function computeEditViewModel<
           })
         : undefined;
       const imageVariant =
-        fieldDef.type === "image" ? Object.keys(fileDef?.variants ?? {})[0] : undefined;
+        fieldDef.type === "image" || fieldDef.type === "images"
+          ? 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

package/src/view-model/index.ts

@@ -18,6 +18,7 @@ export {
   embeddedCellOptionLabelKey,
   fieldLabelKey,
   fieldOptionLabelKey,
+  fieldOptionLabelKeyPrefix,
 } from "./list";
 export type {
   EditExtensionSectionViewModel,

package/src/view-model/list.ts

@@ -144,13 +144,21 @@ export function fieldLabelKey(featureName: string, entityName: string, fieldName
   return `${featureName}:entity:${entityName}:field:${fieldName}`;
 }
 
+export function fieldOptionLabelKeyPrefix(
+  featureName: string,
+  entityName: string,
+  fieldName: string,
+): string {
+  return `${fieldLabelKey(featureName, entityName, fieldName)}:option:`;
+}
+
 export function fieldOptionLabelKey(
   featureName: string,
   entityName: string,
   fieldName: string,
   value: string,
 ): string {
-  return `${featureName}:entity:${entityName}:field:${fieldName}:option:${value}`;
+  return `${fieldOptionLabelKeyPrefix(featureName, entityName, fieldName)}${value}`;
 }
 
 // Embedded-list cell label key — one level deeper than fieldLabelKey,

package/src/view-model/types.ts

@@ -1,6 +1,7 @@
 import type {
   EditFieldSpec,
   EditSectionSpec,
+  FieldIconKey,
   FieldRenderer,
   ListColumnSpec,
   PlatformComponent,
@@ -191,11 +192,8 @@ export type EditFieldViewModel = {
   /** 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
-   *  fall back to "no icon". */
-  readonly icon?: string;
+  /** Closed FieldIconKey from EditFieldSpec.icon (FIELD_ICONS registry). */
+  readonly icon?: FieldIconKey;
   /** Only set for an embedded-LIST field (`multiple: true`) — the per-cell
    *  metadata the renderer needs to draw each column/cell. Absent for a
    *  plain (non-list) embedded field. */