@usequeek/theme-kit 0.1.20 → 0.1.21

package/strings/pseudo-locale.ts

@@ -0,0 +1,264 @@
+/**
+ * Pseudo-locale QA (slice: typed keys + pseudo-locale QA helper).
+ *
+ * PURE AND SERVER-SAFE: this module imports nothing from `next/*` and nothing
+ * from React, so server components, Node tooling (theme-check), tests and the
+ * browser all share it (precedent: `utils/locale.ts`, `strings/theme-strings.ts`).
+ * Keep it that way.
+ *
+ * What it is: `pseudoLocalize(dictionary, options?)` returns a pseudo
+ * dictionary with the SAME keys and the SAME plural-map shape, where every
+ * string value is accent-mapped, ~30% longer, and wrapped in markers like
+ * `[!! … !!]`. `{placeholders}` and `{{`/`}}` escapes pass through
+ * untouched, keys are never touched.
+ *
+ * Two uses (both documented in the README):
+ *  - Dev-only locale: mount the app with the pseudo dictionary as the
+ *    `strings` prop. Every string that went through `t()` renders pseudo;
+ *    any text that remains plain English next to pseudo text is a hard-coded
+ *    (un-wrapped) string. Never ship pseudo to shoppers.
+ *  - Tests: render a component with the pseudo dictionary, then run the
+ *    English-leak scan (`findEnglishLeaks` / `assertNoEnglishLeak`) over the
+ *    HTML. That scan is the reusable primitive theme tests (and the
+ *    storefront, and theme-tools) import.
+ *
+ * English safety: this module never changes an English value — pseudo
+ * dictionaries are built on demand in dev/test and never enter a bundle.
+ */
+
+import type { ThemeStringsDictionary, ThemeStringsValue } from './theme-strings';
+
+export interface PseudoLocalizeOptions {
+  /** Marker prepended to every value. Default `'[!! '`. */
+  prefix?: string;
+  /** Marker appended to every value. Default `' !!]'`. */
+  suffix?: string;
+  /** Fraction of extra padding appended inside the markers. Default `0.3`. */
+  expansionRatio?: number;
+  /** Padding character. Default `'~'`. */
+  expansionChar?: string;
+  /**
+   * Wrap the core in U+202B … U+202C (RTL embedding) for a visual RTL check.
+   * Default `false`. This is a spot-check aid, not bidi-correct output.
+   */
+  rtl?: boolean;
+}
+
+export const PSEUDO_PREFIX = '[!! ';
+export const PSEUDO_SUFFIX = ' !!]';
+export const PSEUDO_EXPANSION_RATIO = 0.3;
+export const PSEUDO_EXPANSION_CHAR = '~';
+
+const ACCENT_MAP: Record<string, string> = {
+  a: 'à', A: 'À', b: 'ƀ', B: 'Ɓ', c: 'ç', C: 'Ç', d: 'ď', D: 'Ď',
+  e: 'è', E: 'È', f: 'ƒ', F: 'Ƒ', g: 'ĝ', G: 'Ĝ', h: 'ĥ', H: 'Ĥ',
+  i: 'ì', I: 'Ì', j: 'ĵ', J: 'Ĵ', k: 'ķ', K: 'Ķ', l: 'ŀ', L: 'Ŀ',
+  m: 'ṁ', M: 'Ṁ', n: 'ñ', N: 'Ñ', o: 'ò', O: 'Ò', p: 'ṗ', P: 'Ṗ',
+  q: 'ǫ', Q: 'Ǫ', r: 'ŕ', R: 'Ŕ', s: 'š', S: 'Š', t: 'ţ', T: 'Ţ',
+  u: 'ù', U: 'Ù', v: 'ṽ', V: 'Ṽ', w: 'ŵ', W: 'Ŵ', x: 'ẋ', X: 'Ẋ',
+  y: 'ÿ', Y: 'Ÿ', z: 'ž', Z: 'Ž',
+};
+
+const PLURAL_FORMS = ['one', 'two', 'few', 'many', 'other'];
+
+/** Same leaf rule as `t()`'s runtime: all keys are plural forms, all values strings. */
+function isPluralMapValue(value: unknown): value is Record<string, string> {
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) return false;
+  const keys = Object.keys(value);
+  return (
+    keys.length > 0 &&
+    keys.every((k) => PLURAL_FORMS.includes(k)) &&
+    keys.every((k) => typeof (value as Record<string, unknown>)[k] === 'string')
+  );
+}
+
+function isPlaceholderName(name: string): boolean {
+  return /^[A-Za-z0-9_]+$/.test(name);
+}
+
+/**
+ * Pseudo-localize one string value. `{placeholder}` interpolations and
+ * `{{`/`}}` escapes are preserved byte-for-byte; only plain-text letters are
+ * accent-mapped. `''` stays `''` (an intentional empty renders nothing, so
+ * there is no node to mark).
+ */
+export function pseudoLocalizeText(value: string, options?: PseudoLocalizeOptions): string {
+  if (value === '') return '';
+  const prefix = options?.prefix ?? PSEUDO_PREFIX;
+  const suffix = options?.suffix ?? PSEUDO_SUFFIX;
+  const ratio = options?.expansionRatio ?? PSEUDO_EXPANSION_RATIO;
+  const expansionChar = options?.expansionChar ?? PSEUDO_EXPANSION_CHAR;
+  const rtl = options?.rtl ?? false;
+
+  let core = '';
+  let i = 0;
+  while (i < value.length) {
+    const ch = value[i];
+    if (ch === '{' && value[i + 1] === '{') {
+      core += '{{';
+      i += 2;
+      continue;
+    }
+    if (ch === '}' && value[i + 1] === '}') {
+      core += '}}';
+      i += 2;
+      continue;
+    }
+    if (ch === '{') {
+      const close = value.indexOf('}', i + 1);
+      const name = close === -1 ? '' : value.slice(i + 1, close);
+      if (close !== -1 && isPlaceholderName(name)) {
+        core += value.slice(i, close + 1);
+        i = close + 1;
+        continue;
+      }
+      core += ACCENT_MAP[ch] ?? ch;
+      i += 1;
+      continue;
+    }
+    core += /[A-Za-z]/.test(ch) ? (ACCENT_MAP[ch] ?? ch) : ch;
+    i += 1;
+  }
+
+  const padLength = Math.max(0, Math.round(core.length * ratio));
+  const expanded = core + expansionChar.repeat(padLength);
+  const inner = rtl ? '\u202B' + expanded + '\u202C' : expanded;
+  return `${prefix}${inner}${suffix}`;
+}
+
+function pseudoLocalizeValue(value: ThemeStringsValue, options?: PseudoLocalizeOptions): ThemeStringsValue {
+  if (typeof value === 'string') return pseudoLocalizeText(value, options);
+  if (isPluralMapValue(value)) {
+    const out: Record<string, string> = {};
+    for (const [form, template] of Object.entries(value)) {
+      out[form] = pseudoLocalizeText(template, options);
+    }
+    return out as ThemeStringsValue;
+  }
+  if (typeof value === 'object' && value !== null) {
+    const out: ThemeStringsDictionary = {};
+    for (const [k, v] of Object.entries(value as ThemeStringsDictionary)) {
+      out[k] = pseudoLocalizeValue(v, options);
+    }
+    return out;
+  }
+  return value;
+}
+
+/**
+ * Pseudo-localize a whole dictionary. Keys (including flat literal dotted
+ * keys) are copied verbatim; nested objects recurse; plural maps keep their
+ * exact form keys with each template pseudo-localized.
+ */
+export function pseudoLocalize(
+  dictionary: ThemeStringsDictionary,
+  options?: PseudoLocalizeOptions,
+): ThemeStringsDictionary {
+  const out: ThemeStringsDictionary = {};
+  for (const [key, value] of Object.entries(dictionary)) {
+    out[key] = pseudoLocalizeValue(value, options);
+  }
+  return out;
+}
+
+/** True when the rendered text carries this run's pseudo markers. */
+export function isPseudoLocalized(text: string, options?: PseudoLocalizeOptions): boolean {
+  const prefix = options?.prefix ?? PSEUDO_PREFIX;
+  const suffix = options?.suffix ?? PSEUDO_SUFFIX;
+  const trimmed = text.trim();
+  return (
+    trimmed.length >= prefix.length + suffix.length &&
+    trimmed.startsWith(prefix) &&
+    trimmed.endsWith(suffix)
+  );
+}
+
+export interface EnglishLeakScanOptions {
+  /**
+   * Visible strings that are English by design (brand names, codes) and must
+   * not be reported. Exact strings or patterns, matched against the trimmed
+   * node text.
+   */
+  allowlist?: Array<string | RegExp>;
+  /**
+   * Also scan user-visible attributes (`aria-label`, `aria-valuetext`,
+   * `placeholder`, `title`, `alt`). Default `true` — hard-coded aria copy is
+   * the same bug class as hard-coded text nodes.
+   */
+  includeAttributes?: boolean;
+  /** Marker options used for the pseudo run being scanned. */
+  pseudo?: PseudoLocalizeOptions;
+}
+
+function decodeEntities(value: string): string {
+  return value
+    .replace(/&amp;/g, '&')
+    .replace(/&lt;/g, '<')
+    .replace(/&gt;/g, '>')
+    .replace(/&quot;/g, '"')
+    .replace(/&#39;|&#x27;/g, "'")
+    .replace(/&nbsp;/g, ' ');
+}
+
+function visibleTexts(html: string, includeAttributes: boolean): string[] {
+  const found: string[] = [];
+  let text = html
+    .replace(/<script[\s\S]*?<\/script>/gi, ' ')
+    .replace(/<style[\s\S]*?<\/style>/gi, ' ')
+    .replace(/<!--[\s\S]*?-->/g, ' ');
+  if (includeAttributes) {
+    for (const match of text.matchAll(
+      /(?:aria-label|aria-valuetext|placeholder|title|alt)\s*=\s*"([^"]*)"/gi,
+    )) {
+      const attr = decodeEntities(match[1] ?? '').trim().replace(/\s+/g, ' ');
+      if (attr) found.push(attr);
+    }
+    for (const match of text.matchAll(
+      /(?:aria-label|aria-valuetext|placeholder|title|alt)\s*=\s*'([^']*)'/gi,
+    )) {
+      const attr = decodeEntities(match[1] ?? '').trim().replace(/\s+/g, ' ');
+      if (attr) found.push(attr);
+    }
+  }
+  const stripped = text.replace(/<[^>]*>/g, '\u0000');
+  for (const part of stripped.split('\u0000')) {
+    const node = decodeEntities(part).trim().replace(/\s+/g, ' ');
+    if (node) found.push(node);
+  }
+  return found;
+}
+
+/**
+ * The English-leak scan primitive: every visible text node of the rendered
+ * HTML that is NOT pseudo-localized (and not allowlisted, and containing at
+ * least one ASCII letter so numbers/symbols never report) is a hard-coded
+ * English string. Returns the offending node texts (trimmed, in document
+ * order). Pure — theme tests render with the pseudo dictionary, then call
+ * this (or `assertNoEnglishLeak`).
+ */
+export function findEnglishLeaks(html: string, options?: EnglishLeakScanOptions): string[] {
+  const allowlist = options?.allowlist ?? [];
+  const includeAttributes = options?.includeAttributes ?? true;
+  return visibleTexts(html, includeAttributes).filter((node) => {
+    if (isPseudoLocalized(node, options?.pseudo)) return false;
+    if (!/[A-Za-z]/.test(node)) return false;
+    if (allowlist.some((rule) => (typeof rule === 'string' ? rule === node : rule.test(node)))) {
+      return false;
+    }
+    return true;
+  });
+}
+
+/** Throw listing every leaked node, or return silently when the render is clean. */
+export function assertNoEnglishLeak(html: string, options?: EnglishLeakScanOptions): void {
+  const leaks = findEnglishLeaks(html, options);
+  if (leaks.length > 0) {
+    throw new Error(
+      `[theme-kit] English leak: ${leaks.length} visible string(s) are not pseudo-localized:\n` +
+        leaks
+          .slice(0, 20)
+          .map((leak) => ` - ${JSON.stringify(leak)}`)
+          .join('\n'),
+    );
+  }
+}

package/strings/theme-strings.ts

@@ -26,7 +26,12 @@
  * the key leaves 23 for the slug plus the dot separator. Values <= 1000 chars.
  */
 
-import { parseLocaleCode } from '../utils/locale';
+import {
+  ENGLISH_DISPLAY_LOCALE,
+  parseLocaleCode,
+  resolveIntlLocale,
+  resolveSupportedLocale,
+} from '../utils/locale';
 import enDefault from '../locales/en.default.json';
 
 /** Interpolation variables: `{name}` in a value. `count` drives plurals. */
@@ -73,10 +78,19 @@ 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.
+ * Canonical locale for PLURAL SELECTION ONLY (used by `t()`).
+ *
+ * This returns a bare `'en'` tag for unknown codes, and bare `'en'` is a
+ * US-order Intl tag (`February 15, 2026`). NEVER pass its result to
+ * `Intl.DateTimeFormat` / `Intl.NumberFormat` / `Intl.RelativeTimeFormat`,
+ * `toLocale*`, or any date/number/money/relative-time formatter — that would
+ * reintroduce the US-order defect the founder banned for English stores.
+ * Formatters must route through `resolveIntlLocale` (en* → en-NG) instead.
+ *
+ * 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';
@@ -315,16 +329,48 @@ export async function createThemeStrings(options?: {
   };
 }
 
-/** Locale-aware number formatting keyed by the active locale (unknown → English). */
+/**
+ * Pick the Intl tag for one theme formatting call: the storefront locale
+ * through the single canonical mapping (`resolveIntlLocale` — English lands
+ * on `ENGLISH_DISPLAY_LOCALE`, never bare `en` with its US order), or
+ * English when the runtime's ICU lacks the locale. Never throws.
+ */
+function themeFormatTag(
+  locale: string | null | undefined,
+  supportedLocalesOf: (locales: string[]) => readonly string[],
+): string {
+  return resolveSupportedLocale(resolveIntlLocale(locale), supportedLocalesOf);
+}
+
+/** Locale-aware number formatting keyed by the active locale (unknown → English). Never throws. */
 export function formatThemeNumber(
   value: number,
   locale?: string | null,
   options?: Intl.NumberFormatOptions,
 ): string {
-  return new Intl.NumberFormat(canonicalThemeLocale(locale), options).format(value);
+  const tag = themeFormatTag(locale, (l) => Intl.NumberFormat.supportedLocalesOf(l));
+  try {
+    return new Intl.NumberFormat(tag, options).format(value);
+  } catch {
+    try {
+      return new Intl.NumberFormat(ENGLISH_DISPLAY_LOCALE, options).format(value);
+    } catch {
+      return String(value);
+    }
+  }
 }
 
-/** Locale-aware date formatting keyed by the active locale (unknown → English). `''` if unparseable. */
+/**
+ * Locale-aware date formatting keyed by the active locale (unknown →
+ * English). `''` if unparseable. Never throws.
+ *
+ * THE helper themes call instead of hardcoding 'en-GB' in their own date
+ * formatting: pass the storefront locale (client: `useStorefrontLocale()`; server: the
+ * request locale the host already holds) and the same Intl options — English
+ * shoppers see the unchanged British/Nigerian order ("2 October 2026"),
+ * other shoppers see their own locale. A Node whose ICU lacks the locale
+ * falls back to English, never an exception.
+ */
 export function formatThemeDate(
   value: string | number | Date,
   locale?: string | null,
@@ -332,7 +378,16 @@ export function formatThemeDate(
 ): 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);
+  const tag = themeFormatTag(locale, (l) => Intl.DateTimeFormat.supportedLocalesOf(l));
+  try {
+    return new Intl.DateTimeFormat(tag, options).format(date);
+  } catch {
+    try {
+      return new Intl.DateTimeFormat(ENGLISH_DISPLAY_LOCALE, options).format(date);
+    } catch {
+      return '';
+    }
+  }
 }
 
 function normalizeMoneyCurrency(value: unknown): string {
@@ -341,16 +396,124 @@ function normalizeMoneyCurrency(value: unknown): string {
     : 'NGN';
 }
 
-/** Locale-aware currency formatting keyed by the active locale (unknown → English). */
+/**
+ * OPTIONAL typed keys (additive — the untyped `t(key: string, …)` above is
+ * untouched, so every existing caller keeps compiling).
+ *
+ * `ThemeStringKey<typeof strings>` derives the key union from a theme's
+ * English dictionary object: nested objects flatten to dotted keys
+ * (`{ cart: { title: '…' } }` → `'cart.title'`), a plural map
+ * (`{ one, …, other }`) counts as ONE key (`'items.count'`, never
+ * `'items.count.one'`), and a flat literal dotted key (`'a.b.c'`) stays one
+ * key. A broad `ThemeStringsDictionary` (index signature) collapses to
+ * `string` — i.e. untyped — by design.
+ *
+ * Pair with `createThemeT` for a drop-in typed binding:
+ *
+ * ```ts
+ * import enDefault from './locales/en.default.json';
+ * const { t } = await createThemeStrings({ locale });
+ * const tt = createThemeT<typeof enDefault>(t);
+ * tt('cart.title'); // ok
+ * // tt('cart.titl'); // type error: typo key fails
+ * ```
+ */
+export type ThemePluralForm = 'one' | 'two' | 'few' | 'many' | 'other';
+
+type IsThemePluralMap<V> = V extends { other: string }
+  ? Exclude<keyof V, ThemePluralForm> extends never
+    ? true
+    : false
+  : false;
+
+export type ThemeStringKey<T, Prefix extends string = ''> = string extends Extract<
+  keyof T,
+  string
+>
+  ? string
+  : {
+      [K in Extract<keyof T, string>]: T[K] extends string
+        ? `${Prefix}${K}`
+        : IsThemePluralMap<T[K]> extends true
+          ? `${Prefix}${K}`
+          : T[K] extends Record<string, unknown>
+            ? ThemeStringKey<T[K], `${Prefix}${K}.`>
+            : `${Prefix}${K}`;
+    }[Extract<keyof T, string>];
+
+/** The typed binding `createThemeT` hands out: same call shape as `t`. */
+export type TypedThemeStringsFn<TKey extends string = string> = (
+  key: TKey,
+  vars?: ThemeStringsVars,
+  locale?: string | null,
+) => string;
+
+/**
+ * Wrap any bound `t` (server `createThemeStrings` or client
+ * `useThemeStrings()`) so only keys of `TDictionary` compile. Pass the
+ * theme's English dictionary type explicitly:
+ * `createThemeT<typeof enDefault>(t)`. Pass a broad
+ * `ThemeStringsDictionary` and the result stays `(key: string, …)` — the
+ * untyped behaviour, unchanged.
+ */
+export function createThemeT<TDictionary>(
+  translate: ThemeStringsFn,
+): TypedThemeStringsFn<ThemeStringKey<TDictionary>> {
+  return translate as TypedThemeStringsFn<ThemeStringKey<TDictionary>>;
+}
+
+/** Locale-aware currency formatting keyed by the active locale (unknown → English). Never throws. */
 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);
+  const code = normalizeMoneyCurrency(currency);
+  const tag = themeFormatTag(locale, (l) => Intl.NumberFormat.supportedLocalesOf(l));
+  try {
+    return new Intl.NumberFormat(tag, {
+      ...options,
+      style: 'currency',
+      currency: code,
+    }).format(amount);
+  } catch {
+    try {
+      return new Intl.NumberFormat(ENGLISH_DISPLAY_LOCALE, {
+        ...options,
+        style: 'currency',
+        currency: code,
+      }).format(amount);
+    } catch {
+      return `${code} ${amount}`;
+    }
+  }
+}
+
+/**
+ * Locale-aware relative time keyed by the active locale (unknown → English):
+ * `formatThemeRelativeTime(-1, 'day', 'fr')` → `"hier"`. `numeric: 'auto'`
+ * by default so whole days read as words where the language has them. Never
+ * throws — a missing ICU locale falls back to English, a bad unit to
+ * `"<value> <unit>"`.
+ */
+export function formatThemeRelativeTime(
+  value: number,
+  unit: Intl.RelativeTimeFormatUnit = 'day',
+  locale?: string | null,
+  options?: Intl.RelativeTimeFormatOptions,
+): string {
+  const tag = themeFormatTag(locale, (l) => Intl.RelativeTimeFormat.supportedLocalesOf(l));
+  try {
+    return new Intl.RelativeTimeFormat(tag, { numeric: 'auto', ...options }).format(value, unit);
+  } catch {
+    try {
+      return new Intl.RelativeTimeFormat(ENGLISH_DISPLAY_LOCALE, {
+        numeric: 'auto',
+        ...options,
+      }).format(value, unit);
+    } catch {
+      return `${value} ${unit}`;
+    }
+  }
 }

package/tests/auth-email-errors.test.tsx

@@ -0,0 +1,55 @@
+/**
+ * Auth error English pins (checkout / auth slice) — S4 drift guard.
+ *
+ * `mapEmailError` maps SDK failure codes to `t('auth.error.*')` strings, and
+ * three more error keys are set directly in the provider. Every English value
+ * below is resolved through the REAL default dictionary, so renaming a key or
+ * changing any English value fails here. S7 proof included.
+ */
+import { describe, expect, it } from 'vitest';
+import { QueekSdkError } from '@queekai/client-sdk';
+import { t, defaultThemeStrings } from '../strings/theme-strings';
+import { mapEmailError } from '../hooks/use-auth-flow';
+
+const tt = (key: string): string => t(defaultThemeStrings, key);
+
+function sdkError(code: string, message: string): QueekSdkError {
+  return new QueekSdkError(message, code, 400);
+}
+
+describe('mapEmailError code -> English pins', () => {
+  it.each([
+    ['invalid_credentials', 'Wrong email or password. Please try again.'],
+    ['login_mode_mismatch', 'This account uses a different sign-in method (Google or phone).'],
+    ['account_already_exists', 'Email already registered. Please sign in instead.'],
+    ['phone_already_exists', 'Phone number already in use.'],
+    ['otp_resend_too_soon', 'Please wait before requesting another code.'],
+    ['invalid_otp', 'Incorrect code. Please try again.'],
+  ] as Array<[string, string]>)('code %s maps to its exact English', (code, english) => {
+    expect(mapEmailError(sdkError(code, 'server message'), tt)).toBe(english);
+  });
+
+  it('passes an unknown-code server message through untouched', () => {
+    expect(mapEmailError(sdkError('something_else', 'Server says no.'), tt)).toBe('Server says no.');
+  });
+
+  it('falls back to generic English when the server message is empty', () => {
+    expect(mapEmailError(sdkError('something_else', ''), tt)).toBe('Something went wrong. Please try again.');
+  });
+
+  it('falls back to generic English for non-SDK failures', () => {
+    expect(mapEmailError(new Error('boom'), tt)).toBe('Something went wrong. Please try again.');
+    expect(mapEmailError('boom', tt)).toBe('Something went wrong. Please try again.');
+  });
+});
+
+describe('direct-set auth.error.* English pins', () => {
+  it.each([
+    ['auth.error.firstname', 'Please enter your first name.'],
+    ['auth.error.register', 'Registration failed. Try again.'],
+    ['auth.error.google', 'Could not connect to Google sign-in. Please try again.'],
+    ['auth.error.generic', 'Something went wrong. Please try again.'],
+  ] as Array<[string, string]>)('%s resolves to its exact English', (key, english) => {
+    expect(tt(key)).toBe(english);
+  });
+});