@usequeek/theme-kit 0.1.20 → 0.1.21

package/tests/theme-hook-placement.test.tsx

@@ -0,0 +1,179 @@
+/**
+ * Hook-placement rule (checkout / auth / blog slice) — S2 enforcement.
+ *
+ * Rule: every `useThemeStrings()` call must sit at the top level of a
+ * PascalCase component or a `use*` hook: no enclosing if / ternary / loop /
+ * try / switch / && / ||, no early return before it, and never nested inside
+ * another function (e.g. a `.map` callback). Violations break the Rules of
+ * Hooks and silently untranslate strings, so this test FAILS when broken.
+ */
+import { readdirSync, readFileSync, statSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { describe, expect, it } from 'vitest';
+import ts from 'typescript';
+
+const kitRoot = join(dirname(fileURLToPath(import.meta.url)), '..');
+
+// Files this slice migrated: each must call useThemeStrings() exactly once.
+const EXPECTED_FILES = [
+  'components/checkout/checkout-contact.tsx',
+  'components/checkout/default-checkout-shell.tsx',
+  'components/checkout/policy-links.tsx',
+  'components/auth/auth-email-login-step.tsx',
+  'components/auth/auth-email-otp-step.tsx',
+  'components/auth/auth-email-otp-verify-step.tsx',
+  'components/auth/auth-email-register-step.tsx',
+  'components/auth/auth-signup-step.tsx',
+  'components/blog/category-filter.tsx',
+  'components/blog/pagination.tsx',
+  'components/blog/post-meta.tsx',
+  'components/blog/related-posts.tsx',
+  'components/blog/share-buttons.tsx',
+  'hooks/use-auth-flow.tsx',
+];
+
+function listTsx(dir: string): string[] {
+  const out: string[] = [];
+  for (const entry of readdirSync(dir)) {
+    const full = join(dir, entry);
+    if (statSync(full).isDirectory()) out.push(...listTsx(full));
+    else if (entry.endsWith('.tsx')) out.push(full);
+  }
+  return out;
+}
+
+const NAME_RE = /^[A-Z][A-Za-z0-9]*$|^use[A-Z]/;
+
+interface CallSite {
+  file: string;
+  line: number;
+  problems: string[];
+}
+
+function enclosingName(fn: ts.Node): string | null {
+  if (ts.isFunctionDeclaration(fn)) return fn.name?.text ?? null;
+  if (ts.isMethodDeclaration(fn)) return ts.isIdentifier(fn.name) ? fn.name.text : null;
+  if ((ts.isArrowFunction(fn) || ts.isFunctionExpression(fn)) && ts.isVariableDeclaration(fn.parent)) {
+    return fn.parent.name.getText();
+  }
+  return null;
+}
+
+function isTopLevelFunction(fn: ts.Node): boolean {
+  if (ts.isFunctionDeclaration(fn)) return ts.isSourceFile(fn.parent);
+  if (ts.isArrowFunction(fn) || ts.isFunctionExpression(fn)) {
+    return (
+      ts.isVariableDeclaration(fn.parent) &&
+      ts.isVariableDeclarationList(fn.parent.parent) &&
+      ts.isVariableStatement(fn.parent.parent.parent) &&
+      ts.isSourceFile(fn.parent.parent.parent.parent)
+    );
+  }
+  return false;
+}
+
+function checkFile(rel: string): CallSite[] {
+  const src = readFileSync(join(kitRoot, rel), 'utf8');
+  const sf = ts.createSourceFile(rel, src, ts.ScriptTarget.Latest, true, ts.ScriptKind.TSX);
+  const sites: CallSite[] = [];
+  const stack: ts.Node[] = [];
+
+  function pushFn(node: ts.Node): void {
+    stack.push(node);
+    ts.forEachChild(node, visit);
+    stack.pop();
+  }
+
+  function visit(node: ts.Node): void {
+    if (
+      ts.isFunctionDeclaration(node) ||
+      ts.isFunctionExpression(node) ||
+      ts.isArrowFunction(node) ||
+      ts.isMethodDeclaration(node)
+    ) {
+      pushFn(node);
+      return;
+    }
+    if (
+      ts.isCallExpression(node) &&
+      ts.isIdentifier(node.expression) &&
+      node.expression.text === 'useThemeStrings'
+    ) {
+      const problems: string[] = [];
+      const enclosing = stack.length > 0 ? stack[stack.length - 1] : null;
+      if (!enclosing || stack.length !== 1) {
+        problems.push('not directly inside one top-level function (nested callback?)');
+      } else {
+        const name = enclosingName(enclosing);
+        if (!name || !NAME_RE.test(name)) problems.push(`enclosing function '${name ?? '<anonymous>'}' is not a PascalCase component or use* hook`);
+        if (!isTopLevelFunction(enclosing)) problems.push('enclosing function is not a module top-level declaration');
+        let p: ts.Node = node.parent;
+        while (p && p !== enclosing) {
+          if (
+            ts.isIfStatement(p) ||
+            ts.isConditionalExpression(p) ||
+            ts.isForStatement(p) ||
+            ts.isForInStatement(p) ||
+            ts.isForOfStatement(p) ||
+            ts.isWhileStatement(p) ||
+            ts.isDoStatement(p) ||
+            ts.isTryStatement(p) ||
+            ts.isCatchClause(p) ||
+            ts.isSwitchStatement(p) ||
+            ts.isCaseClause(p) ||
+            ts.isDefaultClause(p) ||
+            (ts.isBinaryExpression(p) &&
+              (p.operatorToken.kind === ts.SyntaxKind.AmpersandAmpersandToken ||
+                p.operatorToken.kind === ts.SyntaxKind.BarBarToken))
+          ) {
+            problems.push(`conditionally enclosed by ${ts.SyntaxKind[p.kind]}`);
+            break;
+          }
+          p = p.parent;
+        }
+        const body = (enclosing as ts.FunctionLikeDeclaration).body;
+        if (body && ts.isBlock(body)) {
+          let host: ts.Node = node;
+          while (host.parent && host.parent !== body) host = host.parent;
+          for (const stmt of body.statements) {
+            if (stmt === host) break;
+            if (ts.isReturnStatement(stmt)) {
+              problems.push('an early return precedes the hook call');
+              break;
+            }
+          }
+        }
+      }
+      const { line } = sf.getLineAndCharacterOfPosition(node.getStart(sf));
+      sites.push({ file: rel, line: line + 1, problems });
+      return;
+    }
+    ts.forEachChild(node, visit);
+  }
+
+  visit(sf);
+  return sites;
+}
+
+const scopeFiles = listTsx(join(kitRoot, 'components'))
+  .concat(listTsx(join(kitRoot, 'hooks')))
+  .map((f) => f.slice(kitRoot.length + 1));
+
+describe('useThemeStrings() placement (Rules of Hooks)', () => {
+  it('every migrated file calls useThemeStrings() exactly once', () => {
+    for (const rel of EXPECTED_FILES) {
+      expect(checkFile(rel).length, `${rel}: expected exactly one call`).toBe(1);
+    }
+  });
+
+  it('every call in components/ + hooks/ is top-level in a component or hook', () => {
+    const bad: string[] = [];
+    for (const rel of scopeFiles) {
+      for (const site of checkFile(rel)) {
+        for (const problem of site.problems) bad.push(`${site.file}:${site.line}: ${problem}`);
+      }
+    }
+    expect(bad, bad.join('\n')).toEqual([]);
+  });
+});

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

@@ -0,0 +1,171 @@
+import { renderToStaticMarkup } from 'react-dom/server';
+import type { JSX, ReactNode } from 'react';
+import { describe, expect, it } from 'vitest';
+import enDefault from '../locales/en.default.json';
+import { StorefrontProvider, useThemeStrings } from '../provider';
+import { defaultThemeStrings, t, type ThemeStringsDictionary } from '../strings/theme-strings';
+import {
+  assertNoEnglishLeak,
+  findEnglishLeaks,
+  isPseudoLocalized,
+  pseudoLocalize,
+  pseudoLocalizeText,
+} from '../strings/pseudo-locale';
+
+const EN = enDefault as unknown as ThemeStringsDictionary;
+
+function render(children: ReactNode, strings: ThemeStringsDictionary | null): string {
+  return renderToStaticMarkup(
+    <StorefrontProvider
+      vendor={{ id: 'v1', slug: 'kili-foods', name: 'Kili Foods' } as never}
+      config={{} as never}
+      menus={[]}
+      {...(strings ? { strings } : {})}
+    >
+      {children}
+    </StorefrontProvider>,
+  );
+}
+
+function Title(): JSX.Element {
+  const t = useThemeStrings();
+  return <h1>{t('cart.title')}</h1>;
+}
+
+describe('pseudoLocalize (pure dictionary transform)', () => {
+  it('accent-maps, expands ~30% and wraps in markers', () => {
+    expect(pseudoLocalizeText('Your cart')).toBe('[!! Ÿòùŕ çàŕţ~~~ !!]');
+  });
+
+  it('preserves {placeholders} byte-for-byte and still interpolates', () => {
+    const pseudo = pseudoLocalizeText('{count} items');
+    expect(pseudo).toBe('[!! {count} ìţèṁš~~~~ !!]');
+    expect(pseudo).toContain('{count}');
+    expect(t([{ v: pseudo }], 'v', { count: 3 }, 'en')).toBe('[!! 3 ìţèṁš~~~~ !!]');
+  });
+
+  it('preserves `{{` / `}}` escapes (structure survives, literal is pseudo)', () => {
+    const pseudo = pseudoLocalizeText('a {{b}} c');
+    expect(pseudo).toContain('{{');
+    expect(pseudo).toContain('}}');
+    // Same interpolation behaviour as the source: escapes still escape.
+    expect(t([{ v: pseudo }], 'v', {}, 'en')).toBe('[!! à {ƀ} ç~~~ !!]');
+  });
+
+  it('keeps plural-map shape (one key, every form pseudo)', () => {
+    const dict: ThemeStringsDictionary = {
+      items: { count: { one: '{count} item', other: '{count} items' } },
+    };
+    const pseudo = pseudoLocalize(dict);
+    expect(Object.keys((pseudo['items'] as Record<string, unknown>)['count'] as object)).toEqual([
+      'one',
+      'other',
+    ]);
+    const forms = (pseudo['items'] as { count: { one: string; other: string } }).count;
+    expect(forms.one).toContain('{count}');
+    expect(isPseudoLocalized(forms.one)).toBe(true);
+    expect(isPseudoLocalized(forms.other)).toBe(true);
+    // t() still selects forms from the pseudo dictionary.
+    expect(t([pseudo], 'items.count', { count: 1 }, 'en')).toContain('1');
+    expect(t([pseudo], 'items.count', { count: 5 }, 'en')).toContain('5');
+  });
+
+  it('recurses nested objects and never touches keys (incl. flat dotted keys)', () => {
+    const dict = {
+      cart: { title: 'Your cart', empty: { message: 'Your cart is empty.' } },
+      'flat.key': 'Flat value',
+    } as unknown as ThemeStringsDictionary;
+    const pseudo = pseudoLocalize(dict);
+    expect(Object.keys(pseudo).sort()).toEqual(['cart', 'flat.key']);
+    expect(Object.keys(pseudo['cart'] as object).sort()).toEqual(['empty', 'title']);
+    expect(t([pseudo], 'flat.key')).toBe(pseudoLocalizeText('Flat value'));
+  });
+
+  it('leaves empty values empty (an intentional empty renders no node)', () => {
+    expect(pseudoLocalizeText('')).toBe('');
+    const pseudo = pseudoLocalize({ hidden: { label: '' } });
+    expect((pseudo['hidden'] as { label: string }).label).toBe('');
+  });
+
+  it('expands very long values by ~30% (1000-char budget value)', () => {
+    const long = 'a'.repeat(1000);
+    const pseudo = pseudoLocalizeText(long);
+    const core = pseudo.slice('[!! '.length, -' !!]'.length);
+    expect(core.length).toBe(1000 + Math.round(1000 * 0.3));
+  });
+
+  it('leaves unicode (non-Latin, emoji) intact, wrapped', () => {
+    const pseudo = pseudoLocalizeText('こんにちは世界 🛒');
+    expect(pseudo).toContain('こんにちは世界');
+    expect(pseudo).toContain('🛒');
+    expect(isPseudoLocalized(pseudo)).toBe(true);
+  });
+
+  it('rtl option wraps the core in U+202B … U+202C', () => {
+    const pseudo = pseudoLocalizeText('Your cart', { rtl: true });
+    expect(pseudo.includes('\u202B')).toBe(true);
+    expect(pseudo.includes('\u202C')).toBe(true);
+    expect(isPseudoLocalized(pseudo)).toBe(true);
+  });
+
+  it('custom markers are honoured by the scan', () => {
+    const pseudo = pseudoLocalizeText('Your cart', { prefix: '‹', suffix: '›' });
+    expect(pseudo.startsWith('‹')).toBe(true);
+    expect(isPseudoLocalized(pseudo)).toBe(false);
+    expect(isPseudoLocalized(pseudo, { prefix: '‹', suffix: '›' })).toBe(true);
+    expect(findEnglishLeaks(`<h1>${pseudo}</h1>`, { pseudo: { prefix: '‹', suffix: '›' } })).toEqual(
+      [],
+    );
+  });
+});
+
+describe('English leak scan (reusable theme-test primitive)', () => {
+  it('a fully pseudo render is clean', () => {
+    const html = render(<Title />, pseudoLocalize(EN));
+    expect(html).not.toContain('Your cart');
+    expect(findEnglishLeaks(html)).toEqual([]);
+    expect(() => assertNoEnglishLeak(html)).not.toThrow();
+  });
+
+  it('a hard-coded English string is reported (the control that proves the scan fails)', () => {
+    function Leaky(): JSX.Element {
+      const t = useThemeStrings();
+      return (
+        <main>
+          <h1>{t('cart.title')}</h1>
+          <p>Hard-coded checkout copy</p>
+        </main>
+      );
+    }
+    const html = render(<Leaky />, pseudoLocalize(EN));
+    expect(findEnglishLeaks(html)).toEqual(['Hard-coded checkout copy']);
+    expect(() => assertNoEnglishLeak(html)).toThrow(/Hard-coded checkout copy/);
+  });
+
+  it('flags hard-coded user-visible attributes (aria-label, placeholder)', () => {
+    const html = `<button aria-label="Close dialog">×</button><input placeholder="Search products" />`;
+    expect(findEnglishLeaks(html)).toEqual(['Close dialog', 'Search products']);
+    expect(findEnglishLeaks(html, { includeAttributes: false })).toEqual([]);
+  });
+
+  it('ignores numbers, symbols and pseudo-wrapped attributes', () => {
+    const html = render(<Title />, pseudoLocalize(EN));
+    expect(findEnglishLeaks(`<span>₦5,000</span><span>2 / 5</span>${html}`)).toEqual([]);
+  });
+
+  it('allowlists brand names and codes', () => {
+    const html = `<footer><span>${pseudoLocalizeText('Powered by')}</span><span>Queek</span></footer>`;
+    expect(findEnglishLeaks(html)).toEqual(['Queek']);
+    expect(findEnglishLeaks(html, { allowlist: ['Queek'] })).toEqual([]);
+    expect(findEnglishLeaks(html, { allowlist: [/^Q/] })).toEqual([]);
+  });
+
+  it('pseudo of the real English default keeps every key (renamed-key drift fails here)', () => {
+    const pseudo = pseudoLocalize(EN);
+    expect(Object.keys(pseudo).sort()).toEqual(Object.keys(EN).sort());
+    // Spot values still resolve through t() — a changed English default that
+    // was not rebuilt into pseudo expectations fails loudly, never silently.
+    expect(t([pseudo], 'cart.title')).toBe(pseudoLocalizeText('Your cart'));
+    expect(t([defaultThemeStrings], 'cart.title')).toBe('Your cart');
+  });
+});

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

@@ -0,0 +1,97 @@
+import { renderToStaticMarkup } from 'react-dom/server';
+import type { JSX } from 'react';
+import { describe, expect, it } from 'vitest';
+import enDefault from '../locales/en.default.json';
+import {
+  createThemeT,
+  defaultThemeStrings,
+  t,
+  type ThemeStringKey,
+  type ThemeStringsDictionary,
+} from '../strings/theme-strings';
+import { StorefrontProvider, useThemeStrings } from '../provider';
+
+/** Small theme-shaped dictionary exercising nesting, plurals and flat keys. */
+const THEME_EN = {
+  cart: {
+    title: 'Your cart',
+    empty: { message: 'Your cart is empty.' },
+  },
+  items: {
+    count: { one: '{count} item', other: '{count} items' },
+  },
+  'flat.key': 'Flat value',
+  greet: 'Hello {name}!',
+} as const;
+
+describe('typed keys: createThemeT (additive, opt-in)', () => {
+  it('delegates to the wrapped t (values, vars, plurals identical)', () => {
+    const dict = THEME_EN as unknown as ThemeStringsDictionary;
+    const tt = createThemeT<typeof THEME_EN>((key, vars, locale) => t([dict], key, vars, locale));
+
+    expect(tt('cart.title')).toBe('Your cart');
+    expect(tt('greet', { name: 'Ada' })).toBe('Hello Ada!');
+    expect(tt('items.count', { count: 1 })).toBe('1 item');
+    expect(tt('items.count', { count: 5 })).toBe('5 items');
+    expect(tt('flat.key')).toBe('Flat value');
+  });
+
+  it('wraps the client useThemeStrings() hook result', () => {
+    function Title(): JSX.Element {
+      const tUntyped = useThemeStrings();
+      const tt = createThemeT<typeof THEME_EN>(tUntyped);
+      return <h1>{tt('cart.title')}</h1>;
+    }
+    const html = renderToStaticMarkup(
+      <StorefrontProvider
+        vendor={{ id: 'v1', slug: 's', name: 'S' } as never}
+        config={{} as never}
+        menus={[]}
+        strings={THEME_EN as unknown as ThemeStringsDictionary}
+      >
+        <Title />
+      </StorefrontProvider>,
+    );
+    expect(html).toContain('<h1>Your cart</h1>');
+  });
+
+  it('accepts every real en.default.json key (valid keys pass)', () => {
+    const tt = createThemeT<typeof enDefault>((key, vars, locale) =>
+      t([defaultThemeStrings], key, vars, locale),
+    );
+    // A sample across nesting depths — each must compile AND render English.
+    expect(tt('cart.title')).toBe('Your cart');
+    expect(tt('cart.empty.message')).toBe('Your cart is empty.');
+    expect(tt('checkout.contact.label')).toBe('Contact');
+    expect(tt('auth.login.title')).toBe('Sign in');
+    expect(tt('blog.share.copy')).toBe('Copy link');
+  });
+
+  it('existing untyped t(key) callers keep compiling (key: string)', () => {
+    const anyKey: string = `cart.title`;
+    // A dynamic string — not a literal — still flows through the untyped fn.
+    expect(t([defaultThemeStrings], anyKey)).toBe('Your cart');
+    // A broad dictionary collapses the typed helper back to `string` (untyped).
+    const loose = createThemeT<ThemeStringsDictionary>((key, vars, locale) =>
+      t([defaultThemeStrings], key, vars, locale),
+    );
+    expect(loose(anyKey)).toBe('Your cart');
+  });
+
+  it('drifts with the dictionary: the union is exactly the flattened keys', () => {
+    // Compile-time proof (positive direction; the negative direction — typos
+    // fail — lives in tests/theme-typed-keys.fixture.ts via @ts-expect-error
+    // so `npm run typecheck` stays green).
+    const keys: Array<ThemeStringKey<typeof THEME_EN>> = [
+      'cart.title',
+      'cart.empty.message',
+      'items.count',
+      'flat.key',
+      'greet',
+    ];
+    expect(keys).toHaveLength(5);
+    // Renaming/removing a key above breaks this file AND the fixture: a
+    // renamed English key is a contract change, not a silent drift.
+    expect(keys).toContain('cart.title');
+  });
+});

package/tests/theme-strings.test.tsx

@@ -239,9 +239,15 @@ describe('default English dictionary budget (backend varchar(64))', () => {
   const pairs: Array<[string, string]> = [];
   flatten(enDefault, '', pairs);
 
-  it('ships the ~75-string core skeleton', () => {
+  it('ships the ~106-string core dictionary (intentional growth, still budgeted)', () => {
+    // Dictionary budget: the checkout/auth/blog shopper-chrome slice added 31
+    // keys and removed 1 orphaned pre-existing key (auth.code.sent, 0 usages,
+    // superseded by auth.code.lead): 76 -> 106, commit 5cb67dd + orphan removal.
+    // The ceiling stays tight (+9 headroom): any further growth must bump it
+    // here deliberately with its own justification, which keeps guarding
+    // against uncontrolled growth (backend varchar(64) per-key budget below).
     expect(pairs.length).toBeGreaterThanOrEqual(70);
-    expect(pairs.length).toBeLessThan(100);
+    expect(pairs.length).toBeLessThanOrEqual(115);
   });
 
   it('every key fits the dotted-lowercase grammar and the 40-char budget', () => {

package/tests/theme-typed-keys.fixture.ts

@@ -0,0 +1,76 @@
+/**
+ * Type-level test (tsd-style via tsc): a typo key FAILS and a valid key
+ * PASSES. This file must stay green under `npm run typecheck` — every
+ * `@ts-expect-error` below is consumed only if the marked line is a type
+ * error, so deleting the error (or breaking the helper) fails the gate.
+ *
+ * NOTE: intentionally self-contained (no `locales/*.json` import) so the
+ * per-locale bundle gate keeps counting exactly one static locale importer
+ * (`strings/theme-strings.ts`).
+ */
+import {
+  createThemeT,
+  t,
+  type ThemeStringKey,
+  type ThemeStringsDictionary,
+} from '../strings/theme-strings';
+
+const strings = {
+  cart: {
+    title: 'Your cart',
+    empty: { message: 'Your cart is empty.' },
+  },
+  items: {
+    count: { one: '{count} item', other: '{count} items' },
+  },
+  'flat.key': 'Flat value',
+} as const;
+
+type K = ThemeStringKey<typeof strings>;
+
+// The union is EXACTLY the flattened keys (mutual assignability proves it:
+// adding or dropping a key on either side breaks this file).
+type Expected = 'cart.title' | 'cart.empty.message' | 'items.count' | 'flat.key';
+const exact1: Expected = null as unknown as K;
+const exact2: K = null as unknown as Expected;
+void exact1;
+void exact2;
+
+// Valid keys pass …
+const okTitle: K = 'cart.title';
+const okNested: K = 'cart.empty.message';
+const okPlural: K = 'items.count';
+const okFlat: K = 'flat.key';
+void okTitle;
+void okNested;
+void okPlural;
+void okFlat;
+
+// … and plural sub-forms are NOT keys (the map is one key) …
+ // @ts-expect-error - 'items.count.one' is a form, not a key
+const badForm: K = 'items.count.one';
+void badForm;
+
+// … a typo key fails …
+ // @ts-expect-error - typo: 'cart.titl' is not a key
+const badTypo: K = 'cart.titl';
+void badTypo;
+
+// … and an unknown key fails.
+ // @ts-expect-error - 'no.such.key' is not a key
+const badUnknown: K = 'no.such.key';
+void badUnknown;
+
+// The typed binding enforces the same at the call site.
+const dict = strings as unknown as ThemeStringsDictionary;
+const tt = createThemeT<typeof strings>((key, vars, locale) => t([dict], key, vars, locale));
+tt('cart.title');
+tt('items.count', { count: 2 });
+// @ts-expect-error - typo key fails through createThemeT too
+tt('cart.titl');
+
+// A broad dictionary stays untyped (existing dynamic-key callers compile).
+declare const anyKey: string;
+const loose = createThemeT<ThemeStringsDictionary>((key, vars, locale) => t([dict], key, vars, locale));
+loose(anyKey);
+t([dict], anyKey);

package/utils/format.ts

@@ -15,6 +15,12 @@
  * shows decimals only when the amount genuinely has them — ₦5,000 stays
  * ₦5,000, ₦0.28 now correctly shows as ₦0.28.
  */
+import {
+  ENGLISH_DISPLAY_LOCALE,
+  resolveIntlLocale,
+  resolveSupportedLocale,
+} from './locale';
+
 /**
  * The locale and zone every date/number the kit DISPLAYS is formatted in.
  * Fixed on purpose: storefront pages render on the server first, and a runtime
@@ -22,11 +28,33 @@
  * browser (Africa/Lagos, en-NG/en-GB) — "Feb 14, 2026" vs "14 Feb 2026". React
  * then fails hydration and re-renders the whole page on the client. Queek's
  * stores and shoppers are Nigerian, so that is the one answer both sides give.
+ *
+ * Aliases `ENGLISH_DISPLAY_LOCALE` (`utils/locale.ts`) — the value lives in
+ * exactly one place. `resolveIntlLocale` maps every English storefront code
+ * here, so English output is byte-identical with or without a locale.
  */
-export const DISPLAY_LOCALE = 'en-NG';
+export const DISPLAY_LOCALE: string = ENGLISH_DISPLAY_LOCALE;
 export const DISPLAY_TIME_ZONE = 'Africa/Lagos';
 
-/** A date for display (default "14 Feb 2026"), identical on server and browser. '' if unparseable. */
+/**
+ * Pick the Intl tag for one formatting call: the storefront locale through
+ * the canonical mapping, or English when the runtime's ICU lacks the locale.
+ * Never throws.
+ */
+function displayTagFor(
+  locale: string | null | undefined,
+  supportedLocalesOf: (locales: string[]) => readonly string[],
+): string {
+  return resolveSupportedLocale(resolveIntlLocale(locale), supportedLocalesOf);
+}
+
+/**
+ * A date for display (default "14 Feb 2026"), identical on server and browser.
+ * '' if unparseable. The locale parameter is routed through the canonical
+ * mapping (founder 2/10/26: English is British/Nigerian order, never US
+ * order), so even an explicit 'en'/'en-US' renders "15 February 2026" — no
+ * exported formatter lets an 'en*' tag reach Intl unmapped.
+ */
 export function formatDisplayDate(
   value: string | number | Date,
   options: Intl.DateTimeFormatOptions = { day: 'numeric', month: 'short', year: 'numeric' },
@@ -34,12 +62,66 @@ export function formatDisplayDate(
 ): string {
   const date = value instanceof Date ? value : new Date(value);
   if (Number.isNaN(date.getTime())) return '';
-  return date.toLocaleDateString(locale, { ...options, timeZone: DISPLAY_TIME_ZONE });
+  return date.toLocaleDateString(resolveIntlLocale(locale), {
+    ...options,
+    timeZone: DISPLAY_TIME_ZONE,
+  });
+}
+
+/**
+ * A date for display in the SHOPPER's locale: `formatDisplayDate` with the
+ * storefront locale (from `useStorefrontLocale()`) already resolved through
+ * the canonical mapping. English renders exactly as `formatDisplayDate`
+ * ("14 Feb 2026"); `fr` renders "14 févr. 2026", and so on. Time zone and
+ * invalid-date handling are `formatDisplayDate`'s. Never throws.
+ */
+export function formatShopperDate(
+  value: string | number | Date,
+  locale: string | null | undefined,
+  options: Intl.DateTimeFormatOptions = { day: 'numeric', month: 'short', year: 'numeric' },
+): string {
+  return formatDisplayDate(
+    value,
+    options,
+    displayTagFor(locale, (l) => Intl.DateTimeFormat.supportedLocalesOf(l)),
+  );
 }
 
 /** A count for display ("1,234"), identical on server and browser. */
-export function formatCount(value: number): string {
-  return value.toLocaleString(DISPLAY_LOCALE);
+export function formatCount(value: number, locale?: string | null): string {
+  const tag = displayTagFor(locale, (l) => Intl.NumberFormat.supportedLocalesOf(l));
+  try {
+    return value.toLocaleString(tag);
+  } catch {
+    return value.toLocaleString(DISPLAY_LOCALE);
+  }
+}
+
+/**
+ * Relative time for display ("yesterday", "il y a 3 jours") in the shopper's
+ * locale — `numeric: 'auto'` so whole days read as words where the language
+ * has them. Falls back to English on a missing ICU locale or a bad unit;
+ * never throws.
+ */
+export function formatRelativeTime(
+  value: number,
+  unit: Intl.RelativeTimeFormatUnit = 'day',
+  locale?: string | null,
+  options?: Intl.RelativeTimeFormatOptions,
+): string {
+  const tag = displayTagFor(locale, (l) => Intl.RelativeTimeFormat.supportedLocalesOf(l));
+  try {
+    return new Intl.RelativeTimeFormat(tag, { numeric: 'auto', ...options }).format(value, unit);
+  } catch {
+    try {
+      return new Intl.RelativeTimeFormat(DISPLAY_LOCALE, { numeric: 'auto', ...options }).format(
+        value,
+        unit,
+      );
+    } catch {
+      return `${value} ${unit}`;
+    }
+  }
 }
 
 /**
@@ -64,16 +146,22 @@ export function normalizeCurrencyCode(value: unknown, fallback: string = PLATFOR
   return /^[A-Z]{3}$/.test(cleanFallback) ? cleanFallback : PLATFORM_DEFAULT_CURRENCY;
 }
 
-export function formatMoney(amount: number, currency = PLATFORM_DEFAULT_CURRENCY): string {
+export function formatMoney(
+  amount: number,
+  currency = PLATFORM_DEFAULT_CURRENCY,
+  locale?: string | null,
+): string {
+  const code = normalizeCurrencyCode(currency);
+  const tag = displayTagFor(locale, (l) => Intl.NumberFormat.supportedLocalesOf(l));
   try {
-    return new Intl.NumberFormat('en-NG', {
+    return new Intl.NumberFormat(tag, {
       style: 'currency',
-      currency,
+      currency: code,
       minimumFractionDigits: 0,
       maximumFractionDigits: 2,
     }).format(amount);
   } catch {
-    return `${currency} ${amount.toLocaleString(DISPLAY_LOCALE)}`;
+    return `${code} ${amount.toLocaleString(DISPLAY_LOCALE)}`;
   }
 }