@cosmicdrift/kumiko-headless 0.127.0 → 0.128.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-headless",
-  "version": "0.127.0",
+  "version": "0.128.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>",
@@ -29,10 +29,14 @@
     "./apex": {
       "types": "./src/apex/index.ts",
       "default": "./src/apex/index.ts"
+    },
+    "./locale-routing": {
+      "types": "./src/locale-routing/index.ts",
+      "default": "./src/locale-routing/index.ts"
     }
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-framework": "0.127.0",
+    "@cosmicdrift/kumiko-framework": "0.128.0",
     "zod": "^4.4.3"
   },
   "publishConfig": {

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

@@ -0,0 +1,94 @@
+import { describe, expect, test } from "bun:test";
+import { createLocaleRouter } from "../index";
+
+type MoneyHorsePage = "home" | "features" | "rechner" | "budget" | "ltv";
+
+const moneyHorseRouter = createLocaleRouter<MoneyHorsePage>({
+  defaultLocale: "de",
+  prefixedLocales: ["en"],
+  routes: {
+    home: { de: "/", en: "/en" },
+    features: { de: "/funktionen", en: "/en/features" },
+    rechner: { de: "/rechner", en: "/en/rechner" },
+    budget: { de: "/budget-rechner", en: "/en/budget-rechner" },
+    ltv: { de: "/beleihungsauslauf", en: "/en/beleihungsauslauf" },
+  },
+  localeHints: { en: ["/features"] },
+});
+
+describe("createLocaleRouter money-horse config", () => {
+  test("detectLang: prefixed, default, legacy hint", () => {
+    expect(moneyHorseRouter.detectLang("/")).toBe("de");
+    expect(moneyHorseRouter.detectLang("/en")).toBe("en");
+    expect(moneyHorseRouter.detectLang("/en/rechner")).toBe("en");
+    expect(moneyHorseRouter.detectLang("/rechner")).toBe("de");
+    expect(moneyHorseRouter.detectLang("/features")).toBe("en");
+    expect(moneyHorseRouter.detectLang("/features/")).toBe("en");
+  });
+
+  test("publicPath returns canonical paths per locale", () => {
+    expect(moneyHorseRouter.publicPath("features", "de")).toBe("/funktionen");
+    expect(moneyHorseRouter.publicPath("features", "en")).toBe("/en/features");
+    expect(moneyHorseRouter.publicPath("rechner", "en")).toBe("/en/rechner");
+  });
+
+  test("resolvePage maps canonical and legacy paths", () => {
+    expect(moneyHorseRouter.resolvePage("/funktionen")).toBe("features");
+    expect(moneyHorseRouter.resolvePage("/en/features")).toBe("features");
+    expect(moneyHorseRouter.resolvePage("/features")).toBe("features");
+    expect(moneyHorseRouter.resolvePage("/en/rechner")).toBe("rechner");
+    expect(moneyHorseRouter.resolvePage("/login")).toBeUndefined();
+  });
+
+  test("altLocalePath keeps logical page across locales", () => {
+    expect(moneyHorseRouter.altLocalePath("/en")).toBe("/");
+    expect(moneyHorseRouter.altLocalePath("/")).toBe("/en");
+    expect(moneyHorseRouter.altLocalePath("/en/features")).toBe("/funktionen");
+    expect(moneyHorseRouter.altLocalePath("/funktionen")).toBe("/en/features");
+    expect(moneyHorseRouter.altLocalePath("/features")).toBe("/funktionen");
+    expect(moneyHorseRouter.altLocalePath("/en/rechner")).toBe("/rechner");
+    expect(moneyHorseRouter.altLocalePath("/rechner")).toBe("/en/rechner");
+    expect(moneyHorseRouter.altLocalePath("/unknown")).toBe("/en");
+  });
+
+  test("sectionAnchor attaches fragment to page path", () => {
+    expect(moneyHorseRouter.sectionAnchor("home", "de", "pricing")).toBe("/#pricing");
+    expect(moneyHorseRouter.sectionAnchor("home", "en", "pricing")).toBe("/en#pricing");
+  });
+});
+
+type PublicStatusPage = "home" | "developers";
+
+const publicStatusRouter = createLocaleRouter<PublicStatusPage>({
+  defaultLocale: "de",
+  prefixedLocales: ["en"],
+  routes: {
+    home: { de: "/", en: "/en" },
+    developers: { de: "/developers", en: "/en/developers" },
+  },
+});
+
+describe("createLocaleRouter publicstatus config", () => {
+  test("altLocalePath for developers", () => {
+    expect(publicStatusRouter.altLocalePath("/en/developers")).toBe("/developers");
+    expect(publicStatusRouter.altLocalePath("/developers")).toBe("/en/developers");
+  });
+});
+
+describe("createLocaleRouter inverted default (website-style)", () => {
+  const router = createLocaleRouter({
+    defaultLocale: "en",
+    prefixedLocales: ["de"],
+    prefixFor: () => "/de",
+    routes: {
+      home: { en: "/", de: "/de" },
+    },
+  });
+
+  test("detectLang with non-default prefix locale", () => {
+    expect(router.detectLang("/")).toBe("en");
+    expect(router.detectLang("/de")).toBe("de");
+    expect(router.altLocalePath("/")).toBe("/de");
+    expect(router.altLocalePath("/de")).toBe("/");
+  });
+});

package/src/locale-routing/index.ts

@@ -0,0 +1,134 @@
+export type LocaleRouterConfig<TPage extends string> = {
+  /** Canonical default, usually "de". No URL prefix. */
+  readonly defaultLocale: string;
+  /** Locales that get a URL prefix, e.g. ["en"] → /en/... */
+  readonly prefixedLocales: readonly string[];
+  /** Prefix segment per locale, default: locale code ("en" → "/en"). */
+  readonly prefixFor?: (locale: string) => string;
+  /** Logical page → path per locale. Every page must define defaultLocale path. */
+  readonly routes: Record<TPage, Record<string, string>>;
+  /** Legacy slug-only paths for detectLang/resolvePage, e.g. { en: ["/features"] }. */
+  readonly localeHints?: Readonly<Record<string, readonly string[]>>;
+  /** Fallback page when altLocalePath cannot resolve pathname. Default: "home". */
+  readonly homePage?: TPage;
+};
+
+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;
+  sectionAnchor(page: TPage, locale: string, fragment: string): string;
+};
+
+function normalizePath(pathname: string): string {
+  if (pathname === "" || pathname === "/") return "/";
+  return pathname.endsWith("/") ? pathname.slice(0, -1) : pathname;
+}
+
+function defaultPrefixFor(locale: string): string {
+  return `/${locale}`;
+}
+
+function stripLocalePrefix(
+  path: string,
+  locale: string,
+  prefixFor: (locale: string) => string,
+): string {
+  const prefix = prefixFor(locale);
+  if (path === prefix) return "/";
+  if (path.startsWith(`${prefix}/`)) return path.slice(prefix.length);
+  return path;
+}
+
+export function createLocaleRouter<TPage extends string>(
+  config: LocaleRouterConfig<TPage>,
+): LocaleRouter<TPage> {
+  const {
+    defaultLocale,
+    prefixedLocales,
+    routes,
+    localeHints = {},
+    prefixFor = defaultPrefixFor,
+    homePage = "home" as TPage,
+  } = config;
+
+  const pathIndex = new Map<string, { page: TPage; locale: string }>();
+
+  for (const [page, localePaths] of Object.entries(routes) as [TPage, Record<string, string>][]) {
+    for (const [locale, routePath] of Object.entries(localePaths)) {
+      pathIndex.set(normalizePath(routePath), { page, locale });
+    }
+  }
+
+  for (const [hintLocale, hints] of Object.entries(localeHints)) {
+    for (const hint of hints) {
+      const normalizedHint = normalizePath(hint);
+      if (pathIndex.has(normalizedHint)) continue;
+
+      for (const [page, localePaths] of Object.entries(routes) as [
+        TPage,
+        Record<string, string>,
+      ][]) {
+        const canonical = localePaths[hintLocale];
+        if (canonical === undefined) continue;
+        const canonicalNorm = normalizePath(canonical);
+        const hintSlug = stripLocalePrefix(normalizedHint, hintLocale, prefixFor);
+        const canonicalSlug = stripLocalePrefix(canonicalNorm, hintLocale, prefixFor);
+        if (hintSlug === canonicalSlug) {
+          pathIndex.set(normalizedHint, { page, locale: hintLocale });
+          break;
+        }
+      }
+    }
+  }
+
+  function detectLang(pathname: string): string {
+    const path = normalizePath(pathname);
+    for (const locale of prefixedLocales) {
+      const prefix = prefixFor(locale);
+      if (path === prefix || path.startsWith(`${prefix}/`)) return locale;
+    }
+    const resolved = pathIndex.get(path);
+    if (resolved !== undefined) return resolved.locale;
+    for (const [locale, hints] of Object.entries(localeHints)) {
+      if (hints.some((hint) => normalizePath(hint) === path)) return locale;
+    }
+    return defaultLocale;
+  }
+
+  function resolvePage(pathname: string): TPage | undefined {
+    return pathIndex.get(normalizePath(pathname))?.page;
+  }
+
+  function publicPath(page: TPage, locale: string): string {
+    const routePath = routes[page][locale];
+    if (routePath === undefined) {
+      throw new Error(`locale-routing: no path for page "${String(page)}" locale "${locale}"`);
+    }
+    return routePath;
+  }
+
+  function otherLocale(currentLocale: string): string {
+    if (currentLocale === defaultLocale) {
+      return prefixedLocales[0] ?? defaultLocale;
+    }
+    return defaultLocale;
+  }
+
+  function altLocalePath(pathname: string): string {
+    const path = normalizePath(pathname);
+    const resolved = pathIndex.get(path);
+    const targetLocale = otherLocale(detectLang(pathname));
+    if (resolved !== undefined) {
+      return publicPath(resolved.page, targetLocale);
+    }
+    return publicPath(homePage, targetLocale);
+  }
+
+  function sectionAnchor(page: TPage, locale: string, fragment: string): string {
+    return `${publicPath(page, locale)}#${fragment}`;
+  }
+
+  return { detectLang, publicPath, resolvePage, altLocalePath, sectionAnchor };
+}