@usequeek/theme-kit 0.1.17 → 0.1.18

package/strings/theme-strings.ts

@@ -0,0 +1,356 @@
+/**
+ * Theme strings — the kit's Shopify-shaped UI-string mechanism (slice K0).
+ *
+ * PURE AND SERVER-SAFE: this module imports nothing from `next/*` and nothing
+ * from React, so server components, Node tooling and the browser all share it
+ * (precedent: `utils/locale.ts`). Keep it that way — `tests/theme-strings*`
+ * fails a build that adds either import here.
+ *
+ * Two surfaces (plan decision 4):
+ *  - Server: `createThemeStrings({ locale, loaders })` returns a bound `t`
+ *    that a server component receives via props/closure. NO provider in the
+ *    tree. The host supplies the loaders (per-locale dynamic imports) so the
+ *    kit never bundles locale files.
+ *  - Client: `StorefrontProvider` takes an optional `strings` prop and
+ *    `useThemeStrings()` returns the same bound `t`. Absent prop = English
+ *    defaults, byte-identical to the old hardcoded literals.
+ *
+ * Fallback (plan decision 3): the caller supplies an ordered list of
+ * dictionaries (merchant override, theme locale, kit core locale) and `t`
+ * returns the FIRST hit. The LAST entry is always the English default value —
+ * never the raw dotted key, never "translation missing". A key absent
+ * everywhere returns `''` (and warns once per key in development only).
+ *
+ * Key budget: dotted lowercase `scope.thing.state`, total length <= 40 chars.
+ * The backend overlay stores `<theme-slug>.<key>` in a varchar(64), so 40 for
+ * the key leaves 23 for the slug plus the dot separator. Values <= 1000 chars.
+ */
+
+import { parseLocaleCode } from '../utils/locale';
+import enDefault from '../locales/en.default.json';
+
+/** Interpolation variables: `{name}` in a value. `count` drives plurals. */
+export type ThemeStringsVars = Record<string, string | number | boolean | null | undefined>;
+
+/**
+ * CLDR plural variants for one key, using the `one/two/few/many/other`
+ * suffix convention. `other` is required (the fallback form); the rest are
+ * used only when `Intl.PluralRules` for the active locale selects them.
+ */
+export interface ThemeStringsPluralMap {
+  one?: string;
+  two?: string;
+  few?: string;
+  many?: string;
+  other: string;
+}
+
+export type ThemeStringsValue =
+  | string
+  | ThemeStringsPluralMap
+  | { [key: string]: ThemeStringsValue };
+
+/** One dictionary: nested objects traversed by dot-path, or flat dotted keys. */
+export type ThemeStringsDictionary = { [key: string]: ThemeStringsValue };
+
+/** The bound translator both surfaces hand out. */
+export type ThemeStringsFn = (
+  key: string,
+  vars?: ThemeStringsVars,
+  locale?: string | null,
+) => string;
+
+/** The kit's default English core dictionary (`locales/en.default.json`). */
+export const defaultThemeStrings: ThemeStringsDictionary =
+  enDefault as ThemeStringsDictionary;
+
+/** Maximum total key length — see the module docblock for the budget. */
+export const THEME_STRING_KEY_MAX_LENGTH = 40;
+
+/** Maximum value length. */
+export const THEME_STRING_VALUE_MAX_LENGTH = 1000;
+
+const PLURAL_FORMS = ['one', 'two', 'few', 'many', 'other'] as const;
+
+/**
+ * Canonical locale for string selection. Unknown/unparseable codes become
+ * English, mirroring `parseLocaleCode` (and the backend's unknown-locale
+ * rule). A well-formed code the runtime's ICU does not know also becomes
+ * English, so plural selection never silently follows the wrong language.
+ */
+export function canonicalThemeLocale(locale: string | null | undefined): string {
+  const code = parseLocaleCode(locale) ?? 'en';
+  try {
+    return Intl.PluralRules.supportedLocalesOf([code]).length > 0 ? code : 'en';
+  } catch {
+    return 'en';
+  }
+}
+
+/**
+ * Text direction for a locale (`dir` attribute). There is no locale catalogue
+ * in the kit to read this from, so the base language decides: Arabic-script
+ * languages render `rtl`, everything else (including unknown codes) `ltr`.
+ */
+export function themeLocaleDir(locale: string | null | undefined): 'rtl' | 'ltr' {
+  const base = (parseLocaleCode(locale) ?? 'en').split('-')[0]?.toLowerCase() ?? 'en';
+  return RTL_BASE_LANGUAGES.has(base) ? 'rtl' : 'ltr';
+}
+
+const RTL_BASE_LANGUAGES: ReadonlySet<string> = new Set([
+  'ar', 'he', 'fa', 'ur', 'ps', 'sd', 'yi', 'ug', 'dv', 'ku',
+]);
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function isPluralMap(value: unknown): value is ThemeStringsPluralMap {
+  if (!isRecord(value)) return false;
+  const keys = Object.keys(value);
+  return (
+    keys.length > 0 &&
+    keys.every((k) => (PLURAL_FORMS as readonly string[]).includes(k)) &&
+    keys.every((k) => typeof value[k] === 'string')
+  );
+}
+
+/** Dot-path lookup that also accepts a flat literal dotted key. */
+function lookupValue(
+  dictionary: ThemeStringsDictionary,
+  key: string,
+): ThemeStringsValue | undefined {
+  if (Object.prototype.hasOwnProperty.call(dictionary, key)) {
+    return dictionary[key];
+  }
+  let node: ThemeStringsValue = dictionary;
+  for (const part of key.split('.')) {
+    if (!isRecord(node) || !Object.prototype.hasOwnProperty.call(node, part)) return undefined;
+    node = node[part] as ThemeStringsValue;
+  }
+  return node;
+}
+
+function pluralCount(vars: ThemeStringsVars | undefined): number | null {
+  const count = vars?.['count'];
+  return typeof count === 'number' && Number.isFinite(count) ? count : null;
+}
+
+function selectPluralForm(
+  map: ThemeStringsPluralMap,
+  vars: ThemeStringsVars | undefined,
+  locale: string,
+): string {
+  const count = pluralCount(vars);
+  if (count === null) return map.other;
+  let form: string;
+  try {
+    form = new Intl.PluralRules(locale).select(count);
+  } catch {
+    form = new Intl.PluralRules('en').select(count);
+  }
+  return map[form as keyof ThemeStringsPluralMap] ?? map.other;
+}
+
+/** Suffix convention: `key.one` … `key.other` looked up as (flat or nested) keys. */
+function lookupSuffixed(
+  dictionary: ThemeStringsDictionary,
+  key: string,
+  vars: ThemeStringsVars | undefined,
+  locale: string,
+): string | undefined {
+  const count = pluralCount(vars);
+  let form = 'other';
+  if (count !== null) {
+    try {
+      form = new Intl.PluralRules(locale).select(count);
+    } catch {
+      form = new Intl.PluralRules('en').select(count);
+    }
+  }
+  for (const candidate of form === 'other' ? ['other'] : [form, 'other']) {
+    const value = lookupValue(dictionary, `${key}.${candidate}`);
+    if (typeof value === 'string') return interpolate(value, vars);
+  }
+  return undefined;
+}
+
+/**
+ * `{var}` interpolation. A missing/nullish var keeps its `{placeholder}`
+ * (visible, greppable, never a crash); `{{` / `}}` escape to literal braces.
+ */
+export function interpolate(
+  template: string,
+  vars: ThemeStringsVars | undefined,
+): string {
+  if (!template.includes('{') && !template.includes('}')) return template;
+  let out = '';
+  let i = 0;
+  while (i < template.length) {
+    const ch = template[i];
+    if (ch === '{') {
+      if (template[i + 1] === '{') {
+        out += '{';
+        i += 2;
+        continue;
+      }
+      const close = template.indexOf('}', i + 1);
+      const name = close === -1 ? '' : template.slice(i + 1, close);
+      if (close !== -1 && /^[A-Za-z0-9_]+$/.test(name)) {
+        const value = vars?.[name];
+        out += value === undefined || value === null ? template.slice(i, close + 1) : String(value);
+        i = close + 1;
+        continue;
+      }
+      out += ch;
+      i += 1;
+      continue;
+    }
+    if (ch === '}' && template[i + 1] === '}') {
+      out += '}';
+      i += 2;
+      continue;
+    }
+    out += ch;
+    i += 1;
+  }
+  return out;
+}
+
+const warnedKeys = new Set<string>();
+
+function warnMissingKey(key: string): void {
+  if (typeof process !== 'undefined' && process.env['NODE_ENV'] === 'production') return;
+  if (warnedKeys.has(key)) return;
+  warnedKeys.add(key);
+  console.warn(`[theme-kit] missing theme string: "${key}" (no dictionary has it; rendered "")`);
+}
+
+/** Test-only: reset the warn-once set between cases. */
+export function resetThemeStringsWarnings(): void {
+  warnedKeys.clear();
+}
+
+/**
+ * Pure lookup: first hit across the ordered dictionaries wins
+ * (override, theme locale, kit core locale — the caller appends
+ * `defaultThemeStrings` LAST). Absent everywhere: `''` in production, plus a
+ * once-per-key `console.warn` in development. Never the raw key.
+ */
+export function t(
+  dictionaries: ThemeStringsDictionary | Array<ThemeStringsDictionary | null | undefined>,
+  key: string,
+  vars?: ThemeStringsVars,
+  locale?: string | null,
+): string {
+  const list = Array.isArray(dictionaries) ? dictionaries : [dictionaries];
+  const canonical = canonicalThemeLocale(locale);
+  for (const dictionary of list) {
+    if (!dictionary) continue;
+    const value = lookupValue(dictionary, key);
+    if (typeof value === 'string') return interpolate(value, vars);
+    if (isPluralMap(value)) return interpolate(selectPluralForm(value, vars, canonical), vars);
+    const suffixed = lookupSuffixed(dictionary, key, vars, canonical);
+    if (suffixed !== undefined) return suffixed;
+  }
+  warnMissingKey(key);
+  return '';
+}
+
+/** Per-locale loader the host supplies — usually a dynamic `import()`. */
+export type ThemeStringsLoader = (
+  locale: string,
+) => Promise<ThemeStringsDictionary | null | undefined>;
+
+export interface ThemeStringsLoaders {
+  /** Merchant overrides for the active locale (highest precedence). */
+  override?: ThemeStringsLoader;
+  /** Active theme's `{locale}.json`. */
+  theme?: ThemeStringsLoader;
+  /** Kit core pack for the active locale. */
+  core?: ThemeStringsLoader;
+}
+
+export interface BoundThemeStrings {
+  /** Bound to the active locale's dictionaries (+ English default last). */
+  t: ThemeStringsFn;
+  /** Validated requested locale (`en` when unknown) — what loaders were read with. */
+  locale: string;
+  /** Ordered dictionaries the bound `t` reads (override, theme, core, default). */
+  dictionaries: ThemeStringsDictionary[];
+}
+
+/**
+ * Server-safe, provider-free loader contract. Reads ONLY the active locale
+ * (one locale crosses to the client — never every `{lang}.json`), merges
+ * override → theme → core → English default, and returns a bound `t` for
+ * props/closure use. A loader that throws or returns null (e.g. a missing
+ * locale file) simply drops out of the chain — never an error.
+ */
+export async function createThemeStrings(options?: {
+  locale?: string | null;
+  loaders?: ThemeStringsLoaders;
+}): Promise<BoundThemeStrings> {
+  const requested = parseLocaleCode(options?.locale) ?? 'en';
+  const loaders = options?.loaders;
+  const dictionaries: ThemeStringsDictionary[] = [];
+  for (const load of [loaders?.override, loaders?.theme, loaders?.core]) {
+    if (!load) continue;
+    try {
+      const dictionary = await load(requested);
+      if (dictionary && isRecord(dictionary)) {
+        dictionaries.push(dictionary as ThemeStringsDictionary);
+      }
+    } catch {
+      // Missing locale file et al: fall through to the next dictionary.
+    }
+  }
+  dictionaries.push(defaultThemeStrings);
+  const active = requested;
+  return {
+    t: (key, vars, overrideLocale) =>
+      t(dictionaries, key, vars, overrideLocale ?? active),
+    locale: active,
+    dictionaries,
+  };
+}
+
+/** Locale-aware number formatting keyed by the active locale (unknown → English). */
+export function formatThemeNumber(
+  value: number,
+  locale?: string | null,
+  options?: Intl.NumberFormatOptions,
+): string {
+  return new Intl.NumberFormat(canonicalThemeLocale(locale), options).format(value);
+}
+
+/** Locale-aware date formatting keyed by the active locale (unknown → English). `''` if unparseable. */
+export function formatThemeDate(
+  value: string | number | Date,
+  locale?: string | null,
+  options: Intl.DateTimeFormatOptions = { day: 'numeric', month: 'short', year: 'numeric' },
+): string {
+  const date = value instanceof Date ? value : new Date(value);
+  if (Number.isNaN(date.getTime())) return '';
+  return new Intl.DateTimeFormat(canonicalThemeLocale(locale), options).format(date);
+}
+
+function normalizeMoneyCurrency(value: unknown): string {
+  return typeof value === 'string' && /^[A-Za-z]{3}$/.test(value.trim())
+    ? value.trim().toUpperCase()
+    : 'NGN';
+}
+
+/** Locale-aware currency formatting keyed by the active locale (unknown → English). */
+export function formatThemeMoney(
+  amount: number,
+  currency: unknown,
+  locale?: string | null,
+  options?: Omit<Intl.NumberFormatOptions, 'style' | 'currency'>,
+): string {
+  return new Intl.NumberFormat(canonicalThemeLocale(locale), {
+    ...options,
+    style: 'currency',
+    currency: normalizeMoneyCurrency(currency),
+  }).format(amount);
+}

package/tests/theme-strings-client.test.tsx

@@ -0,0 +1,182 @@
+import { renderToStaticMarkup } from 'react-dom/server';
+import { describe, expect, it } from 'vitest';
+import type { JSX, ReactNode } from 'react';
+import { StorefrontProvider, useThemeStrings } from '../provider';
+import { ThemeMount } from '../theme-mount';
+import { DefaultCartShell } from '../components/cart/default-cart-shell';
+import { defaultThemeStrings, t as translate, type ThemeStringsDictionary } from '../strings/theme-strings';
+import type { CartItem } from '../types/cart';
+import type { ThemeModule } from '../types/theme';
+
+const FR_STRINGS: ThemeStringsDictionary = {
+  cart: {
+    title: 'Votre panier',
+    empty: { message: 'Votre panier est vide.', browse: 'Voir les produits' },
+    summary: { title: 'Résumé de commande' },
+  },
+};
+
+function render(
+  children: ReactNode,
+  options?: { locale?: string | null; strings?: ThemeStringsDictionary | ThemeStringsDictionary[] | null },
+): string {
+  return renderToStaticMarkup(
+    <StorefrontProvider
+      vendor={{ id: 'v1', slug: 'kili-foods', name: 'Kili Foods' } as never}
+      config={{} as never}
+      menus={[]}
+      {...(options?.locale !== undefined ? { locale: options.locale } : {})}
+      {...(options?.strings !== undefined ? { strings: options.strings } : {})}
+    >
+      {children}
+    </StorefrontProvider>,
+  );
+}
+
+function Title(): JSX.Element {
+  const t = useThemeStrings();
+  return <h1>{t('cart.title')}</h1>;
+}
+
+describe('client surface: StorefrontProvider strings + useThemeStrings (decision 4b)', () => {
+  it('renders the active locale through the hook', () => {
+    expect(render(<Title />, { locale: 'fr', strings: FR_STRINGS })).toContain('<h1>Votre panier</h1>');
+  });
+
+  it('falls back per key to the English default VALUE', () => {
+    // `cart.checkout.action` is absent from the FR pack: English value, never the key.
+    function Action(): JSX.Element {
+      const t = useThemeStrings();
+      return <span>{t('cart.checkout.action')}</span>;
+    }
+    const html = render(<Action />, { locale: 'fr', strings: FR_STRINGS });
+    expect(html).toContain('<span>Checkout</span>');
+    expect(html).not.toContain('cart.checkout.action');
+  });
+
+  it('is a no-op when the prop is absent (backward compat: English as today)', () => {
+    expect(render(<Title />)).toContain('<h1>Your cart</h1>');
+  });
+
+  it('matches explicit English defaults exactly (prop changes nothing when absent)', () => {
+    const implicit = render(<Title />);
+    const explicit = render(<Title />, { strings: defaultThemeStrings });
+    expect(implicit).toBe(explicit);
+  });
+
+  it('throws outside a provider, like every other kit hook', () => {
+    expect(() => renderToStaticMarkup(<Title />)).toThrow(
+      'useThemeStrings must be used within StorefrontProvider',
+    );
+  });
+});
+
+describe('client surface through ThemeMount', () => {
+  function Header(): JSX.Element {
+    const t = useThemeStrings();
+    return <header>{t('cart.title')}</header>;
+  }
+
+  const stubTheme = {
+    Layout: ({ children }: { children: ReactNode }) => <div>{children}</div>,
+    Header,
+    Footer: () => <footer />,
+    blocks: {},
+    getHeader: () => Header,
+    getFooter: () => (() => <footer />),
+    getBlock: () => (() => null),
+    pages: {},
+    manifest: { name: 'stub', slug: 'stub', description: '', version: '0' },
+  } as unknown as ThemeModule;
+
+  it('reaches themes mounted by ThemeMount', () => {
+    const html = render(
+      <ThemeMount
+        theme={stubTheme}
+        headerProps={{ menu: [], announcement: null }}
+        footerProps={{}}
+      >
+        <p>page</p>
+      </ThemeMount>,
+      { locale: 'fr', strings: FR_STRINGS },
+    );
+    expect(html).toContain('<header>Votre panier</header>');
+  });
+});
+
+describe('migrated DefaultCartShell (identical English output)', () => {
+  const item: CartItem = {
+    id: 'li-1',
+    product_id: 'p-1',
+    shop_id: 's-1',
+    title: 'Egusi Soup',
+    image: null,
+    unit_price: 5000,
+    quantity: 2,
+    addons: [],
+  };
+
+  const noop = (): void => {};
+
+  it('empty state renders the legacy literals with no strings prop', () => {
+    const html = render(
+      <DefaultCartShell
+        items={[]}
+        currency="NGN"
+        total={0}
+        empty
+        onIncrease={noop}
+        onDecrease={noop}
+        onRemove={noop}
+      />,
+    );
+    expect(html).toContain('Your cart</h1>');
+    expect(html).toContain('Your cart is empty.');
+    expect(html).toContain('Browse products');
+  });
+
+  it('populated state interpolates through t() with identical text', () => {
+    const html = render(
+      <DefaultCartShell
+        items={[item]}
+        currency="NGN"
+        total={10000}
+        empty={false}
+        onIncrease={noop}
+        onDecrease={noop}
+        onRemove={noop}
+      />,
+    );
+    expect(html).toContain('each</span>');
+    expect(html).toContain('aria-label="Decrease Egusi Soup"');
+    expect(html).toContain('aria-label="Increase Egusi Soup"');
+    expect(html).toContain('aria-label="Remove Egusi Soup"');
+    expect(html).toContain('Order summary');
+    expect(html).toContain('Add order note');
+    // The note textarea (with its placeholder) renders only after the toggle
+    // opens it, so its key is asserted directly: same dictionary, same output.
+    expect(translate([defaultThemeStrings], 'cart.note.toggle')).toBe('Add order note');
+    expect(translate([defaultThemeStrings], 'cart.note.placeholder')).toBe('Order instructions (optional)');
+    expect(html).toContain('Subtotal:');
+    expect(html).toContain('terms and refund policy');
+    expect(html).toContain('Continue shopping');
+  });
+
+  it('renders French when the provider carries the active locale', () => {
+    const html = render(
+      <DefaultCartShell
+        items={[]}
+        currency="NGN"
+        total={0}
+        empty
+        onIncrease={noop}
+        onDecrease={noop}
+        onRemove={noop}
+      />,
+      { locale: 'fr', strings: FR_STRINGS },
+    );
+    expect(html).toContain('Votre panier</h1>');
+    expect(html).toContain('Votre panier est vide.');
+    expect(html).toContain('Voir les produits');
+  });
+});