@usequeek/theme-kit 0.1.20 → 0.1.22

package/utils/locale.ts

@@ -1,10 +1,9 @@
 /**
- * Storefront locale transport — the kit side of the translations plan.
+ * Storefront locale transport.
  *
- * Contract (translations-core.md, decisions closed): the backend accepts
- * `?locale=<code>` on every customer-facing read and answers translated text
- * (unknown/unpublished locale → source text, no error). The storefront proxy
- * sets `x-queek-locale` on the incoming request for published NON-primary
+ * The API accepts `?locale=<code>` on every customer-facing read and answers
+ * translated text (unknown/unpublished locale → source text, no error). The
+ * storefront proxy sets `x-queek-locale` on the incoming request for published NON-primary
  * locales only — the header is ABSENT on the primary locale — and suffixes
  * revalidation tags as `<tag>:locale:<code>`.
  *
@@ -19,6 +18,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`, on
+ * Node 22 with full ICU). `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: the shopper's locale,
+ * with English in the British/Nigerian style ("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/menu-link.ts

@@ -17,7 +17,7 @@ export function menuItemToHref(item: MenuItem, basePath: string = ''): string {
       const href = `${basePath}/${item.ref}`;
       const anchor = item.meta?.anchor;
       // href may already end in "/" (the home page's ref is normalized to
-      // "/" — see MenuResource::normalizeHomeRefs) — never emit a doubled
+      // "/") — never emit a doubled
       // slash before the fragment.
       return anchor ? `${href.replace(/\/$/, '')}#${anchor}` : href;
     }

package/utils/product-media.ts

@@ -14,7 +14,7 @@ export interface MediaFrame {
 
 /**
  * Picks the largest tier a PDP hero should ever request. `view` is capped at
- * 1600px (queek_backend config/media.php) which covers every theme's hero box
+ * 1600px, which covers every theme's hero box
  * at DPR2 — the raw `original` is uncapped and unoptimized.
  */
 function heroUrl(variants: ImageVariants | null | undefined): string | null {

package/utils/product-normalizer.ts

@@ -37,8 +37,8 @@ function toBool(value: unknown, fallback = false): boolean {
 
 /**
  * Same base/sale/compare-at shape as normalizePricing(), but a variant's own price lives on
- * FLAT fields (price/discount_price/compare_at_price/discount_amount — see
- * ProductResource::resolveShopVariants on the backend), never nested under a `pricing` key.
+ * FLAT fields (price/discount_price/compare_at_price/discount_amount), never nested
+ * under a `pricing` key.
  * Reading `variant.pricing?.sale_amount` (as this used to) is always undefined, so every
  * variant silently fell back to the base product's price — picking Denim vs Taupe never
  * changed what was shown, even though the backend had already computed the right number.

package/utils/vendor-host.ts

@@ -1,14 +1,11 @@
 /**
  * Vendor resolution from a hostname: which store is this request for?
  *
- * Lived at `app/middleware.ts` until core needed it — `lib/core/api/products.ts`
- * and `lib/core/sdk/server-store-client.ts` both import from here, which meant
- * core depended on the app. Nothing here is app-specific: it reads env and
- * resolves a slug. (The actual Next middleware is `proxy.ts`; the old filename
- * suggested otherwise and was never that.)
+ * Nothing here is app-specific: it reads env and resolves a slug, so the kit's
+ * server fetchers and a host app's proxy can both import it.
  */
 
-// Mirrors backend config/storefront.php `reserved_slugs`. Keep in sync.
+// Mirrors the API's reserved store slugs. Keep in sync.
 // These are subdomains the storefront proxy must NOT treat as vendor slugs.
 export const RESERVED_VENDOR_SLUGS = new Set([
   // Live platform subdomains
@@ -24,11 +21,10 @@ export const RESERVED_VENDOR_SLUGS = new Set([
   'staff', 'team', 'queek', 'merchant', 'vendor', 'rider', 'customer',
 ]);
 
-// Every sluggable backend model (Vendor, Product, Category, Region, Service —
-// app/Models/*.php `getSlugOptions()`) is Spatie Sluggable output: lowercase
-// alphanumeric, optionally hyphen-separated, never a dot/underscore/uppercase.
-// Anything else cannot be a real slug of any kind, so reject it before any
-// backend round-trip instead of burning calls that all 404. This is what stops
+// Every sluggable API model (Vendor, Product, Category, Region, Service)
+// produces lowercase alphanumeric slugs, optionally hyphen-separated, never a
+// dot/underscore/uppercase. Anything else cannot be a real slug of any kind, so
+// reject it before any API round-trip instead of burning calls that all 404. This is what stops
 // scanners probing `.env`, `.ssh`, `docker-compose.yaml`, `*.php` etc —
 // RESERVED_VENDOR_SLUGS alone only covers known words, not the infinite space
 // of file-extension guesses.