@elabs-ai/components-ui 4.0.0 → 4.2.0

package/src/components/locale-provider/locale-provider.stories.tsx

@@ -2,9 +2,23 @@ import type { Meta, StoryObj } from "@storybook/react-vite";
 import { LocaleProvider, useLocale } from "./locale-provider";
 
 const meta = {
-  title: "Providers/LocaleProvider",
+  title: "Foundations/Localization",
   component: LocaleProvider,
   tags: ["autodocs"],
+  parameters: {
+    docs: {
+      description: {
+        component:
+          "Root i18n provider — one of the two providers every app mounts once, at the root. " +
+          'Wrap it around your app inside `ThemeProvider`: `<ThemeProvider><LocaleProvider locale="en-US">…' +
+          "</LocaleProvider></ThemeProvider>`. Every component's microcopy, number formatting and " +
+          "date formatting then reads through `useLocale()`. Full resolution chain (`translate` → " +
+          "`messages` → shipped English defaults → raw key), cardinal plurals and bridging to your " +
+          "own i18n runtime (next-intl, react-intl, i18next, …): `docs/I18N.md`. See " +
+          "[Foundations / Theming](?path=/docs/foundations-theming--docs) for the other root provider.",
+      },
+    },
+  },
 } satisfies Meta<typeof LocaleProvider>;
 
 export default meta;
@@ -52,6 +66,24 @@ function LocaleDemo() {
   );
 }
 
+// ---------------------------------------------------------------------------
+// Demo component: cardinal-plural microcopy via `Intl.PluralRules`
+// ---------------------------------------------------------------------------
+
+function PluralDemo() {
+  const { t } = useLocale();
+  return (
+    <div className="space-y-1 rounded-md border border-border p-4 text-body">
+      {[0, 1, 2, 5].map((count) => (
+        <p key={count}>
+          <span className="font-medium text-muted-foreground">count={count}: </span>
+          {t("itemsSelected", { count })}
+        </p>
+      ))}
+    </div>
+  );
+}
+
 // ---------------------------------------------------------------------------
 // Stories
 // ---------------------------------------------------------------------------
@@ -81,3 +113,59 @@ export const RtlArabic: Story = {
 export const NoProvider: Story = {
   render: () => <LocaleDemo />,
 };
+
+/**
+ * The `translate` resolver bridge (#19) — stands in for an app's own i18n
+ * runtime (next-intl, react-intl, i18next, …). It takes precedence over both
+ * `messages` and the shipped English defaults; returning `undefined` for a
+ * key falls through to the normal chain. See `docs/I18N.md` for a worked
+ * next-intl example.
+ */
+export const ExternalTranslateResolver: Story = {
+  render: () => (
+    <LocaleProvider
+      locale="de-DE"
+      messages={{ close: "Schließen (via messages)" }}
+      translate={(key) => (key === "close" ? "Schließen (via translate)" : undefined)}
+    >
+      <LocaleDemo />
+    </LocaleProvider>
+  ),
+};
+
+/**
+ * Cardinal-plural microcopy (#19) — `t("itemsSelected", { count })` selects
+ * the right English form ("1 item selected" vs "N items selected") from a
+ * `PluralMessage` map as `count` changes, via `Intl.PluralRules`.
+ */
+export const PluralForms: Story = {
+  render: () => (
+    <LocaleProvider locale="en-US">
+      <PluralDemo />
+    </LocaleProvider>
+  ),
+};
+
+/**
+ * The same plural key resolved for Polish (`pl-PL`), which has FOUR cardinal
+ * categories (one/few/many/other) with different count boundaries than
+ * English's two (one/other) — the case a plural design that only handles
+ * English silently gets wrong. Count 1 → "one", 2 → "few", 5 → "many".
+ */
+export const PluralFormsPolish: Story = {
+  render: () => (
+    <LocaleProvider
+      locale="pl-PL"
+      messages={{
+        itemsSelected: {
+          one: "{count} plik zaznaczony",
+          few: "{count} pliki zaznaczone",
+          many: "{count} plików zaznaczonych",
+          other: "{count} pliku zaznaczonego",
+        },
+      }}
+    >
+      <PluralDemo />
+    </LocaleProvider>
+  ),
+};

package/src/components/locale-provider/locale-provider.test.tsx

@@ -1,4 +1,4 @@
-import { describe, expect, it } from "vitest";
+import { describe, expect, it, vi } from "vitest";
 import { render, screen } from "@testing-library/react";
 import { createPortal } from "react-dom";
 import { useDirection } from "@radix-ui/react-direction";
@@ -236,3 +236,259 @@ describe("t() — variable interpolation", () => {
     expect(screen.getByTestId("result").textContent).toBe("greeting");
   });
 });
+
+// ---------------------------------------------------------------------------
+// t() — pluggable `translate` resolver bridge (#19)
+// ---------------------------------------------------------------------------
+
+describe("LocaleProvider — translate resolver bridge", () => {
+  function TranslateReader({ vars }: { vars?: Record<string, string | number> }) {
+    const { t } = useLocale();
+    return <span data-testid="result">{t("close", vars)}</span>;
+  }
+
+  it("a translate() result overrides both a messages override and the English default", () => {
+    render(
+      <LocaleProvider
+        messages={{ close: "Fermer" }}
+        translate={(key) => (key === "close" ? "Schließen" : undefined)}
+      >
+        <TranslateReader />
+      </LocaleProvider>,
+    );
+    expect(screen.getByTestId("result").textContent).toBe("Schließen");
+  });
+
+  it("translate() returning undefined falls through to messages, then DEFAULT_MESSAGES, then the key", () => {
+    // Rung 1: messages override present -> used.
+    const { rerender } = render(
+      <LocaleProvider messages={{ close: "Fermer" }} translate={() => undefined}>
+        <TranslateReader />
+      </LocaleProvider>,
+    );
+    expect(screen.getByTestId("result").textContent).toBe("Fermer");
+
+    // Rung 2: no messages override -> DEFAULT_MESSAGES English default.
+    rerender(
+      <LocaleProvider translate={() => undefined}>
+        <TranslateReader />
+      </LocaleProvider>,
+    );
+    expect(screen.getByTestId("result").textContent).toBe("Close");
+
+    // Rung 3: a key with no default and no override -> the raw key itself.
+    function UnknownKeyReader() {
+      const { t } = useLocale();
+      return <span data-testid="unknown">{t("totallyUnknownKey")}</span>;
+    }
+    rerender(
+      <LocaleProvider translate={() => undefined}>
+        <UnknownKeyReader />
+      </LocaleProvider>,
+    );
+    expect(screen.getByTestId("unknown").textContent).toBe("totallyUnknownKey");
+  });
+
+  it("passes the raw key and vars to translate(), not a pre-interpolated string", () => {
+    const translate = vi.fn((_key: string, _vars?: Record<string, string | number>) => undefined);
+    function CountReader() {
+      const { t } = useLocale();
+      return (
+        <span data-testid="result">
+          {t("ui.viewToolbar.countOfTotal", { count: 3, total: 10 })}
+        </span>
+      );
+    }
+    render(
+      <LocaleProvider translate={translate}>
+        <CountReader />
+      </LocaleProvider>,
+    );
+    expect(translate).toHaveBeenCalledWith("ui.viewToolbar.countOfTotal", { count: 3, total: 10 });
+  });
+
+  it("does not double-interpolate a translate() return value that itself contains a literal '{'", () => {
+    render(
+      <LocaleProvider translate={(key) => (key === "close" ? "raw {not-a-var} text" : undefined)}>
+        <TranslateReader />
+      </LocaleProvider>,
+    );
+    // brand-ui's own {name}-replacement must NOT run a second time over the
+    // resolver's own output — a real ICU formatter already interpolated it.
+    expect(screen.getByTestId("result").textContent).toBe("raw {not-a-var} text");
+  });
+
+  it("with no resolver and no message, t() still falls back to the key exactly as today", () => {
+    function UnknownKeyReader() {
+      const { t } = useLocale();
+      return <span data-testid="result">{t("anotherUnknownKey")}</span>;
+    }
+    render(
+      <LocaleProvider>
+        <UnknownKeyReader />
+      </LocaleProvider>,
+    );
+    expect(screen.getByTestId("result").textContent).toBe("anotherUnknownKey");
+  });
+});
+
+// ---------------------------------------------------------------------------
+// t() — ICU cardinal-plural forms via `Intl.PluralRules` (#19)
+// ---------------------------------------------------------------------------
+
+describe("LocaleProvider — plural forms (Intl.PluralRules)", () => {
+  const ITEM_COUNT_MESSAGE = {
+    one: "{count} item selected",
+    other: "{count} items selected",
+  };
+
+  function PluralReader({ count }: { count: number }) {
+    const { t } = useLocale();
+    return <span data-testid="result">{t("itemCount", { count })}</span>;
+  }
+
+  it("selects the English 'one' form for count=1 and 'other' for 0 and many", () => {
+    const { rerender } = render(
+      <LocaleProvider locale="en-US" messages={{ itemCount: ITEM_COUNT_MESSAGE }}>
+        <PluralReader count={1} />
+      </LocaleProvider>,
+    );
+    expect(screen.getByTestId("result").textContent).toBe("1 item selected");
+
+    rerender(
+      <LocaleProvider locale="en-US" messages={{ itemCount: ITEM_COUNT_MESSAGE }}>
+        <PluralReader count={0} />
+      </LocaleProvider>,
+    );
+    expect(screen.getByTestId("result").textContent).toBe("0 items selected");
+
+    rerender(
+      <LocaleProvider locale="en-US" messages={{ itemCount: ITEM_COUNT_MESSAGE }}>
+        <PluralReader count={5} />
+      </LocaleProvider>,
+    );
+    expect(screen.getByTestId("result").textContent).toBe("5 items selected");
+  });
+
+  // Polish has FOUR cardinal categories (one/few/many/other) with different
+  // boundaries than English's two (one/other) — this is the case a
+  // design that only handles English silently gets wrong.
+  const PL_FILE_MESSAGE = {
+    one: "{count} plik",
+    few: "{count} pliki",
+    many: "{count} plików",
+    other: "{count} pliku",
+  };
+
+  function PlPluralReader({ count }: { count: number }) {
+    const { t } = useLocale();
+    return <span data-testid="result">{t("fileCount", { count })}</span>;
+  }
+
+  it("selects the correct Polish plural category for 1 (one), 2 (few), 5 (many), 12 (many), and 22 (few) — teens boundary", () => {
+    const { rerender } = render(
+      <LocaleProvider locale="pl-PL" messages={{ fileCount: PL_FILE_MESSAGE }}>
+        <PlPluralReader count={1} />
+      </LocaleProvider>,
+    );
+    expect(screen.getByTestId("result").textContent).toBe("1 plik");
+
+    rerender(
+      <LocaleProvider locale="pl-PL" messages={{ fileCount: PL_FILE_MESSAGE }}>
+        <PlPluralReader count={2} />
+      </LocaleProvider>,
+    );
+    expect(screen.getByTestId("result").textContent).toBe("2 pliki");
+
+    rerender(
+      <LocaleProvider locale="pl-PL" messages={{ fileCount: PL_FILE_MESSAGE }}>
+        <PlPluralReader count={5} />
+      </LocaleProvider>,
+    );
+    expect(screen.getByTestId("result").textContent).toBe("5 plików");
+
+    // Polish teens (11–21) always use "many" category, breaking the pattern.
+    // 12 → "many"; 22 → "few" demonstrates this non-contiguous boundary.
+    rerender(
+      <LocaleProvider locale="pl-PL" messages={{ fileCount: PL_FILE_MESSAGE }}>
+        <PlPluralReader count={12} />
+      </LocaleProvider>,
+    );
+    expect(screen.getByTestId("result").textContent).toBe("12 plików");
+
+    rerender(
+      <LocaleProvider locale="pl-PL" messages={{ fileCount: PL_FILE_MESSAGE }}>
+        <PlPluralReader count={22} />
+      </LocaleProvider>,
+    );
+    expect(screen.getByTestId("result").textContent).toBe("22 pliki");
+  });
+
+  it("falls back to the 'other' form when a category has no entry", () => {
+    // Only "one" and "other" are supplied; Polish "few"/"many" counts must
+    // fall back to "other" rather than rendering undefined/blank.
+    const PARTIAL = { one: "{count} rzecz", other: "{count} rzeczy" };
+    render(
+      <LocaleProvider locale="pl-PL" messages={{ fileCount: PARTIAL }}>
+        <PlPluralReader count={2} />
+      </LocaleProvider>,
+    );
+    expect(screen.getByTestId("result").textContent).toBe("2 rzeczy");
+  });
+
+  it("handles locales with zero/two categories (Arabic example)", () => {
+    // Arabic (ar-EG) has categories: zero, one, two, few, many, other.
+    // This test verifies that locales with non-English category sets work
+    // and that partial maps (not providing every category) fall back correctly.
+    const AR_MESSAGE: Record<string, string> = {
+      zero: "{count} ملفات", // zero
+      one: "{count} ملف", // one
+      two: "{count} ملفان", // two
+      few: "{count} ملفات", // few
+      many: "{count} ملف", // many
+      other: "{count} ملف", // other
+    };
+
+    function ArPluralReader({ count }: { count: number }) {
+      const { t } = useLocale();
+      return <span data-testid="result">{t("fileCount", { count })}</span>;
+    }
+
+    const { rerender } = render(
+      <LocaleProvider locale="ar-EG" messages={{ fileCount: AR_MESSAGE }}>
+        <ArPluralReader count={0} />
+      </LocaleProvider>,
+    );
+    expect(screen.getByTestId("result").textContent).toBe("0 ملفات");
+
+    rerender(
+      <LocaleProvider locale="ar-EG" messages={{ fileCount: AR_MESSAGE }}>
+        <ArPluralReader count={1} />
+      </LocaleProvider>,
+    );
+    expect(screen.getByTestId("result").textContent).toBe("1 ملف");
+
+    rerender(
+      <LocaleProvider locale="ar-EG" messages={{ fileCount: AR_MESSAGE }}>
+        <ArPluralReader count={2} />
+      </LocaleProvider>,
+    );
+    expect(screen.getByTestId("result").textContent).toBe("2 ملفان");
+  });
+
+  it("the no-provider default value also resolves plural forms (en-US)", () => {
+    // No provider, so this exercises makeDefaultValue()'s t() directly against
+    // the shipped DEFAULT_MESSAGES "itemsSelected" plural entry — proving the
+    // singleton default value branches on plural forms too, not only a
+    // provider's merged messages.
+    function DefaultPluralReader({ count }: { count: number }) {
+      const { t } = useLocale();
+      return <span data-testid="result">{t("itemsSelected", { count })}</span>;
+    }
+    const { rerender } = render(<DefaultPluralReader count={1} />);
+    expect(screen.getByTestId("result").textContent).toBe("1 item selected");
+
+    rerender(<DefaultPluralReader count={5} />);
+    expect(screen.getByTestId("result").textContent).toBe("5 items selected");
+  });
+});

package/src/components/locale-provider/locale-provider.tsx

@@ -2,14 +2,19 @@
 
 import { createContext, use, useMemo, type ReactNode } from "react";
 import { DirectionProvider } from "@radix-ui/react-direction";
-import { DEFAULT_MESSAGES } from "./messages";
+import { DEFAULT_MESSAGES, type MessageValue, type PluralCategory } from "./messages";
 
 // ---------------------------------------------------------------------------
 // Public types
 // ---------------------------------------------------------------------------
 
-/** A flat map of string keys to their translated values. */
-export type Messages = Record<string, string>;
+/**
+ * A flat map of string keys to their translated values — a plain string, or a
+ * `PluralMessage` (one string per ICU cardinal-plural category, e.g.
+ * `{ one: "{count} item", other: "{count} items" }`) for microcopy whose
+ * wording changes with a count. See `PluralMessage` in `./messages`.
+ */
+export type Messages = Record<string, MessageValue>;
 
 export interface LocaleContextValue {
   /** BCP-47 locale tag, e.g. "en-US", "ar-EG", "de-DE". */
@@ -18,8 +23,13 @@ export interface LocaleContextValue {
   dir: "ltr" | "rtl";
   /**
    * Translate a key.
-   * Falls back to: consumer messages → English default → the key itself.
-   * Supports simple `{name}`-style variable interpolation.
+   * Falls back to: an external `translate` resolver (if the provider was
+   * given one) → consumer `messages` → English default → the key itself.
+   * Supports simple `{name}`-style variable interpolation, and ICU
+   * cardinal-plural forms (`Intl.PluralRules`) when the resolved message is a
+   * `PluralMessage` map and `vars.count` is a number. Note: `count` must be a
+   * number, not a numeric string (e.g., `count: 3`, not `count: "3"`) to select
+   * the correct plural category.
    */
   t: (key: string, vars?: Record<string, string | number>) => string;
   /** Format a number using the active locale. Memoized per locale+opts hash. */
@@ -45,18 +55,41 @@ function interpolate(template: string, vars?: Record<string, string | number>):
   );
 }
 
+/**
+ * Resolve a `MessageValue` (a plain string or a `PluralMessage`) to its final,
+ * interpolated string.
+ *
+ * A `PluralMessage` selects its category via `Intl.PluralRules(locale).select(count)`
+ * when `vars.count` is a number; with no `count`, or when the selected
+ * category has no entry, it falls back to `"other"` (the one category every
+ * locale defines), then to the raw `key` if even `"other"` is missing.
+ */
+function resolveMessage(
+  key: string,
+  template: MessageValue,
+  vars: Record<string, string | number> | undefined,
+  pluralRules: Intl.PluralRules,
+): string {
+  if (typeof template === "string") return interpolate(template, vars);
+  const count = typeof vars?.count === "number" ? vars.count : undefined;
+  const category: PluralCategory = count !== undefined ? pluralRules.select(count) : "other";
+  const form = template[category] ?? template.other ?? key;
+  return interpolate(form, vars);
+}
+
 function makeDefaultValue(): LocaleContextValue {
   const locale = "en-US";
   // Simple cache: one Intl object per serialized opts string
   const numberCache = new Map<string, Intl.NumberFormat>();
   const dateCache = new Map<string, Intl.DateTimeFormat>();
+  const pluralRules = new Intl.PluralRules(locale);
 
   return {
     locale,
     dir: "ltr",
     t(key, vars) {
       const template = DEFAULT_MESSAGES[key] ?? key;
-      return interpolate(template, vars);
+      return resolveMessage(key, template, vars, pluralRules);
     },
     formatNumber(n, opts) {
       const k = JSON.stringify(opts ?? null);
@@ -95,6 +128,21 @@ export interface LocaleProviderProps {
    * to the English bundle.
    */
   messages?: Messages;
+  /**
+   * Optional external resolver — hand brand-ui's microcopy off to an app's own
+   * i18n runtime (next-intl, react-intl, i18next, …) instead of maintaining a
+   * second, flattened message catalogue. Called with the raw key and vars
+   * (not pre-interpolated), so a real ICU formatter gets real values and can
+   * do its own pluralization/number/date formatting.
+   *
+   * Return a string to use it as-is (brand-ui does NOT re-run its own
+   * `{name}` interpolation on it — the app's runtime already formatted it).
+   * Return `undefined`/`null` to decline a key; brand-ui then falls back to
+   * `messages` → `DEFAULT_MESSAGES` → the raw key, in that order — so a
+   * resolver only needs to cover the keys it actually wants to override.
+   * See `docs/I18N.md`.
+   */
+  translate?: (key: string, vars?: Record<string, string | number>) => string | undefined | null;
   children: ReactNode;
 }
 
@@ -118,6 +166,7 @@ export function LocaleProvider({
   locale = "en-US",
   dir = "ltr",
   messages,
+  translate,
   children,
 }: LocaleProviderProps) {
   // Merge consumer messages over the shipped English defaults.
@@ -131,14 +180,20 @@ export function LocaleProvider({
   // Memoized Intl formatter caches — keyed by serialised opts
   const numberCache = useMemo(() => new Map<string, Intl.NumberFormat>(), [locale]);
   const dateCache = useMemo(() => new Map<string, Intl.DateTimeFormat>(), [locale]);
+  const pluralRules = useMemo(() => new Intl.PluralRules(locale), [locale]);
 
   const value = useMemo<LocaleContextValue>(
     () => ({
       locale,
       dir,
       t(key, vars) {
+        // An external runtime (next-intl, react-intl, i18next, …) gets first
+        // say, and its result is used AS-IS — it already interpolated and
+        // pluralized. `undefined`/`null` means "I decline this key".
+        const resolved = translate?.(key, vars);
+        if (resolved != null) return resolved;
         const template = merged[key] ?? key;
-        return interpolate(template, vars);
+        return resolveMessage(key, template, vars, pluralRules);
       },
       formatNumber(n, opts) {
         const k = JSON.stringify(opts ?? null);
@@ -151,7 +206,7 @@ export function LocaleProvider({
         return dateCache.get(k)!.format(d);
       },
     }),
-    [locale, dir, merged, numberCache, dateCache],
+    [locale, dir, merged, numberCache, dateCache, pluralRules, translate],
   );
 
   return (