@cosmicdrift/kumiko-headless 0.220.0 → 0.221.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-headless",
-  "version": "0.220.0",
+  "version": "0.221.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.0",
+    "@cosmicdrift/kumiko-framework": "0.221.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 () => {

package/src/form/form-controller.ts

@@ -178,7 +178,7 @@ export function createFormController<TValues extends FormValues, TCtx = unknown>
     errors = Object.freeze(merged);
   }
 
-  function runValidate(scope?: readonly string[]): boolean {
+  function runValidate(scope?: readonly (keyof TValues & string)[]): boolean {
     // See the validate() doc comment in types.ts for the scope contract.
     const scopeSet = scope === undefined ? undefined : new Set(scope);
     if (!options.schema) {
@@ -364,9 +364,20 @@ 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>> => {

package/src/form/types.ts

@@ -145,7 +145,7 @@ export type FormController<TValues extends FormValues> = {
   // `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.
-  validate(scope?: readonly string[]): boolean;
+  validate(scope?: readonly (keyof TValues & string)[]): boolean;
 
   // Reverts values to `initial`, clears errors. Doesn't fire a new
   // "initial" baseline — to adopt the current values as the new baseline

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. */