@cosmicdrift/kumiko-renderer 0.321.0 → 0.322.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-renderer",
-  "version": "0.321.0",
+  "version": "0.322.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,9 +15,9 @@
     }
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-framework": "0.321.0",
-    "@cosmicdrift/kumiko-headless": "0.321.0",
-    "@cosmicdrift/kumiko-types": "0.321.0",
+    "@cosmicdrift/kumiko-framework": "0.322.0",
+    "@cosmicdrift/kumiko-headless": "0.322.0",
+    "@cosmicdrift/kumiko-types": "0.322.0",
     "react": "^19.2.6",
     "temporal-polyfill": "^0.3.2",
     "zod": "^4.4.3"
@@ -28,7 +28,7 @@
     "@types/react-dom": "^19.2.3",
     "jsdom": "^29.1.1",
     "react-dom": "^19.2.6",
-    "@cosmicdrift/kumiko-locale-de": "0.321.0"
+    "@cosmicdrift/kumiko-locale-de": "0.322.0"
   },
   "repository": {
     "type": "git",

package/src/__tests__/i18n.test.tsx

@@ -88,6 +88,34 @@ describe("useTranslation — lookup order", () => {
     });
     expect(result.current("greet", { name: "Marc" })).toBe("Hallo Marc!");
   });
+  test("resolves a plural entry's CLDR category from a fallback bundle — matches the server's output", () => {
+    const bundles: TranslationsByLocale[] = [
+      {
+        de: {
+          "notifications.unread": {
+            one: "{count} ungelesene Nachricht",
+            other: "{count} ungelesene Nachrichten",
+          },
+        },
+        en: {
+          "notifications.unread": {
+            one: "{count} unread message",
+            other: "{count} unread messages",
+          },
+        },
+      },
+    ];
+    const { result: en } = renderHook(() => useTranslation(), {
+      wrapper: wrap(createStaticLocaleResolver({ locale: "en" }), bundles),
+    });
+    expect(en.current("notifications.unread", { count: 1 })).toBe("1 unread message");
+    expect(en.current("notifications.unread", { count: 5 })).toBe("5 unread messages");
+
+    const { result: de } = renderHook(() => useTranslation(), {
+      wrapper: wrap(createStaticLocaleResolver({ locale: "de" }), bundles),
+    });
+    expect(de.current("notifications.unread", { count: 1 })).toBe("1 ungelesene Nachricht");
+  });
 });
 describe("useTranslation — formality", () => {
   const bundles: TranslationsByLocale[] = [

package/src/app/__tests__/list-filter-facets.test.tsx

@@ -7,10 +7,11 @@
 // with boolean facets coerced from URL-state strings to real booleans.
 
 import { describe, expect, test } from "bun:test";
-import type {
-  EntityDefinition,
-  EntityListScreenDefinition,
-  ProjectionListScreenDefinition,
+import {
+  type EntityDefinition,
+  type EntityListScreenDefinition,
+  type ProjectionListScreenDefinition,
+  translationValueOtherText,
 } from "@cosmicdrift/kumiko-framework/ui-types";
 import type { Dispatcher } from "@cosmicdrift/kumiko-headless";
 import { act, render, waitFor } from "@testing-library/react";
@@ -360,8 +361,10 @@ describe("projectionList filter + facets (fw#2224)", () => {
     if (en === undefined) throw new Error("missing en default translations");
     const save = de?.["kumiko.actions.save"] ?? en["kumiko.actions.save"];
     const cancel = de?.["kumiko.actions.cancel"] ?? en["kumiko.actions.cancel"];
-    expect(facet?.label).toBe(save);
-    expect(facet?.options?.[0]?.label).toBe(cancel);
+    expect(facet?.label).toBe(save === undefined ? undefined : translationValueOtherText(save));
+    expect(facet?.options?.[0]?.label).toBe(
+      cancel === undefined ? undefined : translationValueOtherText(cancel),
+    );
   });
 
   test("a reference facet loads its options from the referenced entity's list query, and selecting one sends an id filter", async () => {

package/src/i18n.tsx

@@ -14,7 +14,12 @@
 //      resolver's `subscribe()` — app code can switch language mid-session
 //      without a reload.
 
-import { type Formality, formalLocaleTag } from "@cosmicdrift/kumiko-framework/ui-types";
+import {
+  type Formality,
+  formalLocaleTag,
+  resolveTranslationValue,
+  type TranslationValue,
+} from "@cosmicdrift/kumiko-framework/ui-types";
 import type { LocaleResolver } from "@cosmicdrift/kumiko-headless";
 import {
   createContext,
@@ -25,19 +30,22 @@ import {
   useSyncExternalStore,
 } from "react";
 
-/** Map von i18n-Key → Template-String. Templates dürfen `{name}`-
- *  Platzhalter enthalten — identische Semantik zu i18next-t. */
-export type TranslationBundle = Readonly<Record<string, string>>;
+/** Map of i18n key → TranslationValue. Strings may contain `{name}`
+ *  placeholders (same semantics as i18next t); plural entries resolve via
+ *  `resolveTranslationValue`. */
+export type TranslationBundle = Readonly<Record<string, TranslationValue>>;
 
 /** Map von Locale-Code (BCP-47, z.B. `"de"`, `"en-US"`) → Bundle. */
 export type TranslationsByLocale = Readonly<Record<string, TranslationBundle>>;
 
-/** Key-first shape for `r.translations({ keys })` — each key maps locale → string. */
-export type TranslationsByKey = Readonly<Record<string, Readonly<Record<string, string>>>>;
+/** Key-first shape for `r.translations({ keys })` — each key maps locale → TranslationValue. */
+export type TranslationsByKey = Readonly<
+  Record<string, Readonly<Record<string, TranslationValue>>>
+>;
 
 /** Pivot key-first server translations to locale-first client bundles. */
 export function translationsByLocaleFromKeys(source: TranslationsByKey): TranslationsByLocale {
-  const out: Record<string, Record<string, string>> = {};
+  const out: Record<string, Record<string, TranslationValue>> = {};
   for (const [key, byLocale] of Object.entries(source)) {
     for (const [locale, value] of Object.entries(byLocale)) {
       out[locale] ??= {};
@@ -55,7 +63,7 @@ export function mergeTranslations(
   override: TranslationsByLocale,
 ): TranslationsByLocale {
   const locales = new Set([...Object.keys(base), ...Object.keys(override)]);
-  const merged: Record<string, Record<string, string>> = {};
+  const merged: Record<string, Record<string, TranslationValue>> = {};
   for (const locale of locales) {
     merged[locale] = { ...(base[locale] ?? {}), ...(override[locale] ?? {}) };
   }
@@ -199,7 +207,7 @@ function translateWithFallbacks(
     for (const bundle of ctx.fallbackBundles) {
       for (const localeToTry of localesToTry) {
         const value = bundle[localeToTry]?.[key];
-        if (value !== undefined) return interpolate(value, params);
+        if (value !== undefined) return resolveTranslationValue(value, localeToTry, params);
       }
     }
   }
@@ -217,14 +225,6 @@ function bundleLocaleTiers(
   return [[formalLocaleTag(locale), formalLocaleTag(languageRoot)], plainTier];
 }
 
-function interpolate(template: string, params?: Readonly<Record<string, unknown>>): string {
-  if (params === undefined) return template;
-  return template.replace(/\{(\w+)\}/g, (_, name: string) => {
-    const value = params[name];
-    return value !== undefined ? String(value) : `{${name}}`;
-  });
-}
-
 /** Non-throwing LocaleContext read — undefined outside LocaleProvider.
  *  Used by DataTable FormatCell so plain tables without a provider do not crash. */
 export function useOptionalLocale(): string | undefined {