@usequeek/theme-kit 0.1.19 → 0.1.21

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)}`;
   }
 }
 

package/utils/locale.ts

@@ -19,6 +19,58 @@
  * byte-identical to before.
  */
 
+/**
+ * English display locale — the ONE Intl tag every English shopper sees dates,
+ * numbers and money in. `en-NG`, not `en-GB`: both print dates identically
+ * ("2 October 2026", "14 Feb 2026"), but only `en-NG` renders NGN with the
+ * naira sign the stores already show (`₦12,500` vs `en-GB`'s `NGN 12,500` —
+ * verified on Node 22, full ICU, 2/10/26). `DISPLAY_LOCALE` in
+ * `utils/format.ts` aliases this, so the value lives in exactly one place.
+ */
+export const ENGLISH_DISPLAY_LOCALE = 'en-NG';
+
+/**
+ * THE single canonical mapping from a storefront locale code to the Intl
+ * locale dates/numbers/relative time are formatted in (founder 2/10/26:
+ * shopper's locale, English in the British/Nigerian style so English stores
+ * do not change visibly — "2 October 2026", never US "October 2, 2026").
+ *
+ * - Missing/invalid/unknown-structure codes and EVERY English variant (`en`,
+ *   `en-GB`, `en-NG`, `en-US`, …) become `ENGLISH_DISPLAY_LOCALE`. In
+ *   particular bare `en` must never reach Intl directly: `en` formats US
+ *   order ("October 2, 2026").
+ * - Every other well-formed code passes through unchanged (`fr`, `ar`,
+ *   `pt-BR`, `zh-CN`, `yo`, `ha`, `sw`, …).
+ *
+ * Pure (no `next/*`, no React) like the rest of this module. Never throws.
+ * Pair with `resolveSupportedLocale` when the runtime's ICU may lack the
+ * locale — this function maps, it does not probe.
+ */
+export function resolveIntlLocale(locale: string | null | undefined): string {
+  const code = parseLocaleCode(locale);
+  if (!code) return ENGLISH_DISPLAY_LOCALE;
+  if ((code.split('-')[0] ?? '').toLowerCase() === 'en') return ENGLISH_DISPLAY_LOCALE;
+  return code;
+}
+
+/**
+ * Graceful ICU fallback for one formatting call: the candidate when this
+ * Node's ICU formats it natively, `ENGLISH_DISPLAY_LOCALE` otherwise (a
+ * minimal-ICU build with no French data still renders English, never an
+ * exception). Never throws — pass any Intl constructor's
+ * `supportedLocalesOf`, e.g. `(l) => Intl.DateTimeFormat.supportedLocalesOf(l)`.
+ */
+export function resolveSupportedLocale(
+  candidate: string,
+  supportedLocalesOf: (locales: string[]) => readonly string[],
+): string {
+  try {
+    return supportedLocalesOf([candidate]).length > 0 ? candidate : ENGLISH_DISPLAY_LOCALE;
+  } catch {
+    return ENGLISH_DISPLAY_LOCALE;
+  }
+}
+
 /** Request header the proxy sets for published non-primary locales. */
 export const LOCALE_CODE_HEADER = 'x-queek-locale';
 

package/utils/powered-by.ts

@@ -0,0 +1,31 @@
+/**
+ * The one place the "Powered by Queek" destination is built, so every theme's
+ * footer link carries the same attribution and the affiliate/referral program
+ * can trace a signup back to the store it came from.
+ */
+export const POWERED_BY_QUEEK_URL = 'https://usequeek.com/business';
+
+export const POWERED_BY_UTM_SOURCE = 'powered_by';
+export const POWERED_BY_UTM_MEDIUM = 'storefront';
+
+/**
+ * `campaign` is the store's public slug (never an internal UUID) so signups
+ * are attributable per store. Existing query parameters on the base
+ * URL are kept; the `utm_*` keys are always ours. A blank campaign omits
+ * `utm_campaign` rather than sending an empty value.
+ */
+export function poweredByQueekUrl(campaign?: string | null, base: string = POWERED_BY_QUEEK_URL): string {
+  const url = new URL(base);
+
+  url.searchParams.set('utm_source', POWERED_BY_UTM_SOURCE);
+  url.searchParams.set('utm_medium', POWERED_BY_UTM_MEDIUM);
+
+  const trimmed = campaign?.trim();
+  if (trimmed) {
+    url.searchParams.set('utm_campaign', trimmed);
+  } else {
+    url.searchParams.delete('utm_campaign');
+  }
+
+  return url.toString();
+}