@usequeek/theme-kit 0.1.20 → 0.1.22

package/strings/theme-strings.ts

@@ -1,12 +1,13 @@
 /**
- * Theme strings — the kit's Shopify-shaped UI-string mechanism (slice K0).
+ * Theme strings — the kit's UI-string mechanism: dotted keys, `{var}`
+ * interpolation, CLDR plurals and per-locale dictionaries.
  *
  * 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):
+ * Two surfaces:
  *  - 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
@@ -15,18 +16,24 @@
  *    `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
+ * Fallback: 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.
+ * Merchant overrides are stored as `<theme-slug>.<key>` in a 64-character
+ * field, so 40 for 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 +80,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 US date order (`February 15, 2026`) for English stores.
+ * Formatters must route through `resolveIntlLocale` (en* → en-NG) instead.
+ *
+ * Unknown/unparseable codes become English, mirroring `parseLocaleCode` (and
+ * the API'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 +331,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 +380,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 +398,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.
+ *
+ * `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.
+ */
+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);
+  });
+});

package/tests/currency-contract.test.ts

@@ -6,13 +6,12 @@ import { extractProducts, normalizeProduct } from '../utils/product-normalizer';
 import { useCartStore } from '../stores/cart-store';
 
 /**
- * Slice 2 of api-currency-contract-fix: client readers off `meta.currency`.
- * List-level `meta.currency` stamps the PLATFORM default (NGN) even on
+ * Client readers do not use `meta.currency`. List-level `meta.currency` stamps the PLATFORM default (NGN) even on
  * non-NGN stores, so the item's own `currency` code is the source and the
  * vendor's currency is the store-wide source. Missing codes fall back to the
  * platform default as a LAST resort, in exactly one place.
  */
-describe('currency contract (Slice 2)', () => {
+describe('currency resolution', () => {
   it('exposes NGN as the platform default last resort', () => {
     expect(PLATFORM_DEFAULT_CURRENCY).toBe('NGN');
   });