@cosmicdrift/kumiko-headless 0.196.0 → 0.197.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-headless",
-  "version": "0.196.0",
+  "version": "0.197.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.196.0",
+    "@cosmicdrift/kumiko-framework": "0.197.0",
     "temporal-polyfill": "^0.3.2",
     "zod": "^4.4.3"
   },

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

@@ -35,6 +35,15 @@ 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 () => {
+    const form = createFormController({
+      initial: { title: "hello" },
+      submit: { type: "app:write:task:create" },
+    });
+
+    await expect(form.submit()).rejects.toThrow(/submit\(\) called without a dispatcher/);
+  });
+
   test("happy path: dispatches values, returns success, rebases form", async () => {
     const disp = makeDispatcher();
     const form = createFormController({

package/src/form/form-controller.ts

@@ -358,8 +358,19 @@ export function createFormController<TValues extends FormValues, TCtx = unknown>
         payload = stripUntouchedEmptyStrings(submittedValues, submittedSnapshot.initial);
       }
 
+      // Only enforced here, right before the write actually happens — a
+      // form that never reaches this point (blocked by validation, or a
+      // clean payloadMode "changes" no-op) must not throw just because no
+      // 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.",
+        );
+      }
+
       const runWrite = async (): Promise<SubmitResult<TData>> => {
-        const result = await submitCfg.dispatcher.write<TData>(submitCfg.type, payload);
+        const result = await dispatcher.write<TData>(submitCfg.type, payload);
 
         if (result.isSuccess) {
           // Rebase to the SNAPSHOT, not to the current values — see

package/src/form/types.ts

@@ -240,7 +240,10 @@ export type FormControllerOptions<TValues extends FormValues, TCtx = unknown> =
 export type SubmitPayloadMode = "values" | "changes";
 
 export type SubmitConfig<TValues extends FormValues = FormValues> = {
-  readonly dispatcher: Dispatcher;
+  // Optional so callers can default it from an ambient DispatcherProvider
+  // (see kumiko-renderer's useForm) instead of requiring it at every call
+  // site — submit() throws at write-time if it's still missing then.
+  readonly dispatcher?: Dispatcher;
   // Qualified write-handler name (e.g. "orders:write:order:create").
   readonly type: string;
   readonly payloadMode?: SubmitPayloadMode;

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

@@ -93,6 +93,47 @@ describe("createLocaleRouter inverted default (website-style)", () => {
   });
 });
 
+type OfflotPage = "home" | "features";
+
+const offlotRouter = createLocaleRouter<OfflotPage>({
+  defaultLocale: "es",
+  prefixedLocales: ["en", "de"],
+  routes: {
+    home: { es: "/", en: "/en", de: "/de" },
+    features: { es: "/funciones", en: "/en/features", de: "/de/funktionen" },
+  },
+});
+
+describe("createLocaleRouter with a third locale", () => {
+  test("altLocalePath with explicit targetLocale reaches any locale", () => {
+    expect(offlotRouter.altLocalePath("/", "de")).toBe("/de");
+    expect(offlotRouter.altLocalePath("/", "en")).toBe("/en");
+    expect(offlotRouter.altLocalePath("/en/features", "de")).toBe("/de/funktionen");
+    expect(offlotRouter.altLocalePath("/de/funktionen", "es")).toBe("/funciones");
+  });
+
+  test("altLocalePath with explicit targetLocale equal to current locale is identity", () => {
+    expect(offlotRouter.altLocalePath("/en/features", "en")).toBe("/en/features");
+    expect(offlotRouter.altLocalePath("/funciones", "es")).toBe("/funciones");
+  });
+
+  test("altLocalePath falls back to homePage for unknown path with explicit target", () => {
+    expect(offlotRouter.altLocalePath("/unknown", "de")).toBe("/de");
+  });
+
+  test("altLocalePath rejects a targetLocale that only resolves via the prototype chain", () => {
+    expect(() => offlotRouter.altLocalePath("/", "__proto__")).toThrow(/no path for page/);
+    expect(() => offlotRouter.altLocalePath("/", "constructor")).toThrow(/no path for page/);
+    expect(() => offlotRouter.altLocalePath("/", "toString")).toThrow(/no path for page/);
+  });
+
+  test("altLocalePath without targetLocale keeps binary toggle to prefixedLocales[0]", () => {
+    expect(offlotRouter.altLocalePath("/")).toBe("/en");
+    expect(offlotRouter.altLocalePath("/en")).toBe("/");
+    expect(offlotRouter.altLocalePath("/de")).toBe("/");
+  });
+});
+
 describe("createLocaleRouter homePage validation", () => {
   test("throws at construction when homePage has no routes entry", () => {
     expect(() =>

package/src/locale-routing/index.ts

@@ -17,7 +17,7 @@ export type LocaleRouter<TPage extends string> = {
   detectLang(pathname: string): string;
   publicPath(page: TPage, locale: string): string;
   resolvePage(pathname: string): TPage | undefined;
-  altLocalePath(pathname: string): string;
+  altLocalePath(pathname: string, targetLocale?: string): string;
   sectionAnchor(page: TPage, locale: string, fragment: string): string;
 };
 
@@ -109,16 +109,16 @@ export function createLocaleRouter<TPage extends string>(
   function publicPath(page: TPage, locale: string): string {
     const localePaths = routes[page];
     const routePath = localePaths?.[locale];
-    if (routePath === undefined) {
+    if (
+      localePaths === undefined ||
+      !Object.hasOwn(localePaths, locale) ||
+      routePath === undefined
+    ) {
       throw new Error(`locale-routing: no path for page "${String(page)}" locale "${locale}"`);
     }
     return routePath;
   }
 
-  // Binary toggle (defaultLocale <-> prefixedLocales[0]) — altLocalePath has
-  // no way to target a specific alt locale beyond the first prefixed one.
-  // Fine for the current bilingual (de/en) setup; a third prefixed locale
-  // needs altLocalePath to take an explicit targetLocale param instead.
   function otherLocale(currentLocale: string): string {
     if (currentLocale === defaultLocale) {
       return prefixedLocales[0] ?? defaultLocale;
@@ -126,14 +126,14 @@ export function createLocaleRouter<TPage extends string>(
     return defaultLocale;
   }
 
-  function altLocalePath(pathname: string): string {
+  function altLocalePath(pathname: string, targetLocale?: string): string {
     const path = normalizePath(pathname);
     const resolved = pathIndex.get(path);
-    const targetLocale = otherLocale(detectLang(pathname));
+    const locale = targetLocale ?? otherLocale(detectLang(pathname));
     if (resolved !== undefined) {
-      return publicPath(resolved.page, targetLocale);
+      return publicPath(resolved.page, locale);
     }
-    return publicPath(homePage, targetLocale);
+    return publicPath(homePage, locale);
   }
 
   function sectionAnchor(page: TPage, locale: string, fragment: string): string {