@usequeek/theme-kit 0.1.17 → 0.1.19

package/README.md

@@ -42,6 +42,57 @@ Theme CSS ships with the package: `@usequeek/theme-kit/shared-blocks/core-blocks
 (framework-owned blocks), plus per-component CSS next to its component
 (`components/variant-picker.css`, `apps/apps.css`).
 
+## Theme strings
+
+The kit's Shopify-shaped UI-string mechanism (`strings/theme-strings.ts`,
+pure: no `next/*`, no React). Additive and backward-compatible — a theme or
+provider that passes nothing renders exactly as today, in English.
+
+- **Authoring contract.** `t(dictionaries, key, vars?, locale?)`: dot-path
+  lookup (`cart.title`), `{var}` interpolation (`{{`/`}}` escape to literal
+  braces; a missing var keeps its `{placeholder}`), CLDR plurals via
+  `Intl.PluralRules` — a key holding `{ one, two, few, many, other }`
+  (nested, or flat `key.one` … `key.other` suffix keys) selects by
+  `vars.count`, defaulting to `other`. Locale-aware `formatThemeNumber`,
+  `formatThemeDate` and `formatThemeMoney` replace hardcoded `en-GB`
+  formatting; an unknown locale falls back to English. Keys are dotted
+  lowercase `scope.thing.state`, max **40 chars**; values max **1000 chars**:
+  the backend overlay stores `<theme-slug>.<key>` in a varchar(64), so the
+  key budget leaves 23 chars for the slug plus the dot.
+- **Two surfaces.** Server (provider-free): the host supplies per-locale
+  loaders and calls
+  `createThemeStrings({ locale, loaders })` — `{ override, theme, core }`,
+  each `(locale) => Promise<dict | null>` — usually a per-locale dynamic
+  `import()` with a try/catch returning null when the file is absent — then
+  passes the bound `t` via props/closure. A throwing loader simply drops
+  out of the chain.
+  Client: `<StorefrontProvider strings={…}>` (optional, no-op when absent)
+  plus `useThemeStrings()` returning the same bound `t`; works inside
+  `ThemeMount`. The kit ships `locales/en.default.json` (cart, checkout,
+  auth, blog) as the last-resort English default.
+- **Fallback.** Ordered dictionaries (merchant override → host-loaded
+  locale dictionaries → `manifest.strings` → kit core English default);
+  first hit wins. The last fallback is the English default *value* —
+  never the raw key, never "translation missing". Absent everywhere
+  renders `""` (and warns once per key in development only — an empty
+  string would otherwise leak internal key names into the UI).
+- **Theme English travels with the theme.** A theme ships its own English
+  defaults in its manifest: `import strings from './locales/en.default.json'`
+  inside the theme, then `manifest: { …, strings }` (`ThemeManifest.strings`,
+  ENGLISH ONLY — never other locales). `useThemeStrings()` layers it
+  between the host's `strings` prop and the kit core English, so hosts that
+  mount a theme with no `strings` (e.g. theme previews) still render the
+  theme's English with zero host cooperation. Host dictionaries always win
+  where present; keys missing there fall back to manifest English, never
+  to `""`.
+- **Per-locale loading.** `createThemeStrings` reads ONLY the active
+  locale's dictionaries, and the host passes ONLY that locale to the
+  provider — other `{lang}.json` files never enter the client bundle.
+  Only `locales/en.default.json` may be statically imported (by
+  `strings/theme-strings.ts` itself); every other locale arrives via the
+  host's dynamic `import()` per locale. `tests/theme-strings.test.tsx`
+  gates this: any other static locale import fails the suite.
+
 ## Consumers
 
 - **The Queek storefront** (`usequeek/queek-storefront`) installs this package

package/components/cart/default-cart-shell.tsx

@@ -5,6 +5,7 @@ import { useRef, useState } from 'react';
 import Link from 'next/link';
 import type { CartShellProps } from '../../types/theme';
 import { useHref } from '../../hooks/use-href';
+import { useThemeStrings } from '../../provider';
 import { useCheckoutStore } from '../../stores/checkout-store';
 import { useRelatedProducts } from '../../hooks/use-related-products';
 import { useCart } from '../../hooks/use-cart';
@@ -27,6 +28,7 @@ export function DefaultCartShell({
   onRemove,
 }: CartShellProps): JSX.Element {
   const href = useHref();
+  const t = useThemeStrings();
   const { addProduct } = useCart();
   const vendorNote = useCheckoutStore((s) => s.vendorNote);
   const setVendorNote = useCheckoutStore((s) => s.setVendorNote);
@@ -48,10 +50,10 @@ export function DefaultCartShell({
   if (empty) {
     return (
       <div className="core-cart-page">
-        <h1 className="core-cart-page__title">Your cart</h1>
+        <h1 className="core-cart-page__title">{t('cart.title')}</h1>
         <div className="core-cart-page__empty">
-          <p>Your cart is empty.</p>
-          <Link href={href('/')} className="core-checkout__back-link">Browse products</Link>
+          <p>{t('cart.empty.message')}</p>
+          <Link href={href('/')} className="core-checkout__back-link">{t('cart.empty.browse')}</Link>
         </div>
       </div>
     );
@@ -59,7 +61,7 @@ export function DefaultCartShell({
 
   return (
     <div className="core-cart-page">
-      <h1 className="core-cart-page__title">Your cart</h1>
+      <h1 className="core-cart-page__title">{t('cart.title')}</h1>
 
       <div className="core-cart-page__grid">
         <div className="core-cart-page__main">
@@ -74,19 +76,19 @@ export function DefaultCartShell({
                   )}
                   <div className="core-cart-page__item-info">
                     <span className="core-cart-page__item-title">{item.title}</span>
-                    <span className="core-cart-page__item-price">{formatMoney(item.unit_price, currency)} each</span>
+                    <span className="core-cart-page__item-price">{t('cart.item.each', { price: formatMoney(item.unit_price, currency) })}</span>
                   </div>
                   <div className="core-cart-page__item-qty">
-                    <button type="button" onClick={() => onDecrease(item.id, item.shop_id)} aria-label={`Decrease ${item.title}`}>
+                    <button type="button" onClick={() => onDecrease(item.id, item.shop_id)} aria-label={t('cart.item.decrease', { title: item.title })}>
                       <svg width="10" height="10" viewBox="0 0 12 12" fill="none" aria-hidden="true"><path d="M2 6h8" stroke="currentColor" strokeWidth="1.8" strokeLinecap="round" /></svg>
                     </button>
                     <span>{item.quantity}</span>
-                    <button type="button" onClick={() => onIncrease(item.id, item.shop_id)} aria-label={`Increase ${item.title}`}>
+                    <button type="button" onClick={() => onIncrease(item.id, item.shop_id)} aria-label={t('cart.item.increase', { title: item.title })}>
                       <svg width="10" height="10" viewBox="0 0 12 12" fill="none" aria-hidden="true"><path d="M6 2v8M2 6h8" stroke="currentColor" strokeWidth="1.8" strokeLinecap="round" /></svg>
                     </button>
                   </div>
                   <span className="core-cart-page__item-total">{formatMoney(item.unit_price * item.quantity, currency)}</span>
-                  <button type="button" className="core-cart-page__item-remove" onClick={() => onRemove(item.id, item.shop_id)} aria-label={`Remove ${item.title}`}>
+                  <button type="button" className="core-cart-page__item-remove" onClick={() => onRemove(item.id, item.shop_id)} aria-label={t('cart.item.remove', { title: item.title })}>
                     <svg width="16" height="16" viewBox="0 0 20 20" fill="none" aria-hidden="true">
                       <path d="M4 6h12M8 6V4.5A1.5 1.5 0 019.5 3h1A1.5 1.5 0 0112 4.5V6m-6 0v9.5A1.5 1.5 0 007.5 17h5a1.5 1.5 0 001.5-1.5V6" stroke="currentColor" strokeWidth="1.4" strokeLinecap="round" strokeLinejoin="round" />
                     </svg>
@@ -99,12 +101,12 @@ export function DefaultCartShell({
           {related.length > 0 ? (
             <section className="core-cart-page__related">
               <div className="core-cart-page__related-head">
-                <h2>You may also like</h2>
+                <h2>{t('cart.related.title')}</h2>
                 <div className="core-cart-page__related-nav">
-                  <button type="button" onClick={() => scrollRelated(-1)} aria-label="Previous">
+                  <button type="button" onClick={() => scrollRelated(-1)} aria-label={t('cart.related.prev')}>
                     <svg width="16" height="16" viewBox="0 0 16 16" fill="none" aria-hidden="true"><path d="M10 13L5 8l5-5" stroke="currentColor" strokeWidth="1.5" strokeLinecap="round" strokeLinejoin="round" /></svg>
                   </button>
-                  <button type="button" onClick={() => scrollRelated(1)} aria-label="Next">
+                  <button type="button" onClick={() => scrollRelated(1)} aria-label={t('cart.related.next')}>
                     <svg width="16" height="16" viewBox="0 0 16 16" fill="none" aria-hidden="true"><path d="M6 3l5 5-5 5" stroke="currentColor" strokeWidth="1.5" strokeLinecap="round" strokeLinejoin="round" /></svg>
                   </button>
                 </div>
@@ -125,13 +127,13 @@ export function DefaultCartShell({
                     )}
                     <div className="core-cart-page__related-info">
                       <span className="core-cart-page__related-title">{product.title}</span>
-                      <span className="core-cart-page__related-price">{product.pricing.is_price_from ? 'From ' : ''}{formatMoney(product.pricing.sale_amount, currency)}</span>
+                      <span className="core-cart-page__related-price">{product.pricing.is_price_from ? t('cart.related.from', { price: formatMoney(product.pricing.sale_amount, currency) }) : formatMoney(product.pricing.sale_amount, currency)}</span>
                     </div>
                     {productRequiresVariant(product) ? (
                       <Link
                         className="core-cart-page__related-add"
                         href={href(`/products/${product.slug}`)}
-                        aria-label={`Choose options for ${product.title}`}
+                        aria-label={t('cart.related.choose', { title: product.title })}
                       >
                         <svg width="16" height="16" viewBox="0 0 20 20" fill="none" aria-hidden="true">
                           <path d="M7 4l6 6-6 6" stroke="currentColor" strokeWidth="1.5" strokeLinecap="round" strokeLinejoin="round" />
@@ -141,7 +143,7 @@ export function DefaultCartShell({
                     <button
                       type="button"
                       className="core-cart-page__related-add"
-                      aria-label={`Add ${product.title} to cart`}
+                      aria-label={t('cart.related.add', { title: product.title })}
                       onClick={() => addProduct(product)}
                     >
                       <svg width="16" height="16" viewBox="0 0 20 20" fill="none" aria-hidden="true">
@@ -160,10 +162,10 @@ export function DefaultCartShell({
 
         <div className="core-cart-page__summary">
           <div className="core-cart-page__summary-card">
-            <h2 className="core-cart-page__summary-title">Order summary</h2>
+            <h2 className="core-cart-page__summary-title">{t('cart.summary.title')}</h2>
 
             <button type="button" className="core-cart-page__note-toggle" onClick={() => setNoteOpen((v) => !v)}>
-              Add order note
+              {t('cart.note.toggle')}
               <span aria-hidden="true">{noteOpen ? '−' : '+'}</span>
             </button>
             {noteOpen ? (
@@ -172,18 +174,18 @@ export function DefaultCartShell({
                 rows={3}
                 value={vendorNote}
                 onChange={(event) => setVendorNote(event.target.value)}
-                placeholder="Order instructions (optional)"
+                placeholder={t('cart.note.placeholder')}
               />
             ) : null}
 
             <div className="core-cart-page__subtotal">
-              <span>Subtotal:</span>
+              <span>{t('cart.summary.subtotal')}</span>
               <strong>{formatMoney(total, currency)} {currency}</strong>
             </div>
 
             <label className="core-cart-page__terms">
               <input type="checkbox" checked={agreed} onChange={(event) => setAgreed(event.target.checked)} />
-              <span>I agree to the <Link href={href('/policies')}>terms and refund policy</Link></span>
+              <span>{t('cart.terms.agree')}<Link href={href('/policies')}>{t('cart.terms.policy')}</Link></span>
             </label>
 
             <Link
@@ -197,9 +199,9 @@ export function DefaultCartShell({
                 <circle cx="8" cy="17" r="1" fill="currentColor" />
                 <circle cx="14" cy="17" r="1" fill="currentColor" />
               </svg>
-              Checkout
+              {t('cart.checkout.action')}
             </Link>
-            <Link href={href('/')} className="core-cart-page__continue-link">Continue shopping</Link>
+            <Link href={href('/')} className="core-cart-page__continue-link">{t('cart.summary.continue')}</Link>
           </div>
         </div>
       </div>

package/index.ts

@@ -49,5 +49,8 @@ export * from './utils/video-embed';
 export * from './utils/match-variant';
 export * from './utils/announcement';
 
+// Theme strings — the pure/server-safe i18n core (no next/*, no React).
+export * from './strings/theme-strings';
+
 // Rendering a theme's own demo.json — what makes local preview possible.
 export * from './demo';

package/locales/en.default.json

@@ -0,0 +1,138 @@
+{
+  "cart": {
+    "title": "Your cart",
+    "empty": {
+      "message": "Your cart is empty.",
+      "browse": "Browse products"
+    },
+    "item": {
+      "each": "{price} each",
+      "decrease": "Decrease {title}",
+      "increase": "Increase {title}",
+      "remove": "Remove {title}"
+    },
+    "related": {
+      "title": "You may also like",
+      "prev": "Previous",
+      "next": "Next",
+      "choose": "Choose options for {title}",
+      "add": "Add {title} to cart",
+      "from": "From {price}"
+    },
+    "summary": {
+      "title": "Order summary",
+      "subtotal": "Subtotal:",
+      "continue": "Continue shopping"
+    },
+    "note": {
+      "toggle": "Add order note",
+      "placeholder": "Order instructions (optional)"
+    },
+    "terms": {
+      "agree": "I agree to the ",
+      "policy": "terms and refund policy"
+    },
+    "checkout": {
+      "action": "Checkout"
+    }
+  },
+  "checkout": {
+    "empty": {
+      "message": "Your cart is empty.",
+      "browse": "Browse products"
+    },
+    "page": {
+      "back": "Continue shopping"
+    },
+    "contact": {
+      "label": "Contact",
+      "signin": "Sign in",
+      "signout": "Sign out",
+      "options": "Account options"
+    },
+    "delivery": {
+      "title": "How you'll get it"
+    },
+    "zone": {
+      "title": "Shipping zone"
+    },
+    "address": {
+      "title": "Delivery address"
+    },
+    "schedule": {
+      "title": "Schedule"
+    },
+    "payment": {
+      "title": "Payment",
+      "secure": "All transactions are secure and encrypted."
+    },
+    "summary": {
+      "title": "Order summary",
+      "empty": "Your cart is empty",
+      "subtotal": "Subtotal",
+      "proceed": "Proceed to checkout"
+    },
+    "tabs": {
+      "summary": "Summary",
+      "checkout": "Checkout"
+    },
+    "policy": {
+      "close": "Close",
+      "view": "View full page",
+      "list": "Store policies"
+    }
+  },
+  "auth": {
+    "login": {
+      "title": "Sign in",
+      "subtitle": "Enter your email and password",
+      "email": "Email address",
+      "password": "Password"
+    },
+    "email": {
+      "title": "Sign in",
+      "subtitle": "Enter your email to continue",
+      "or": "or",
+      "placeholder": "your@email.com"
+    },
+    "code": {
+      "title": "Enter code",
+      "sent": "{length}-digit code sent to {email}",
+      "digit": "Digit {index}"
+    },
+    "register": {
+      "title": "Create account",
+      "subtitle": "Fill in your details to get started",
+      "first": "First name",
+      "last": "Last name (optional)",
+      "email": "Email address",
+      "password": "Password (min 8 characters)"
+    },
+    "signup": {
+      "title": "Create your account",
+      "subtitle": "Just a few details to get you started",
+      "first": "First name",
+      "last": "Last name (optional)"
+    }
+  },
+  "blog": {
+    "pagination": {
+      "prev": "← Previous",
+      "next": "Next →",
+      "nav": "Blog pagination",
+      "page": "Page {current}"
+    },
+    "filter": {
+      "all": "All",
+      "nav": "Blog categories"
+    },
+    "share": {
+      "label": "Share",
+      "action": "Share",
+      "x": "Share on X",
+      "facebook": "Share on Facebook",
+      "whatsapp": "Share on WhatsApp",
+      "copy": "Copy link"
+    }
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@usequeek/theme-kit",
-  "version": "0.1.17",
+  "version": "0.1.19",
   "private": false,
   "license": "MIT",
   "description": "The framework a Queek storefront theme is built against.",
@@ -23,6 +23,7 @@
     "**/*.ts",
     "**/*.tsx",
     "**/*.css",
+    "locales/*.json",
     "README.md",
     "LICENSE"
   ],

package/provider.tsx

@@ -9,7 +9,15 @@ import type { Product } from './types/product';
 import type { StorefrontConfig, VendorProfile } from './types/vendor';
 import { getBrandCssVariables } from './utils/brand';
 import { parseLocaleCode } from './utils/locale';
+import {
+  defaultThemeStrings,
+  t as translateThemeStrings,
+  type ThemeStringsDictionary,
+  type ThemeStringsFn,
+  type ThemeStringsVars,
+} from './strings/theme-strings';
 import { DesignTokenPreviewListener } from './design-token-preview';
+import { useOptionalTheme } from './theme-context';
 
 export interface StorefrontPreviewData {
   products?: Product[];
@@ -40,6 +48,11 @@ interface StorefrontContextValue {
   /** Validated request locale (null = primary). Browser hooks read it via
    * `useStorefrontLocale()` and send `?locale=` when it is set. */
   locale: string | null;
+  /** Active locale's dictionaries (override, theme, core — the host merges and
+   * passes ONLY the active locale). Empty or omitted = English defaults only.
+   * Optional so hand-built context values (storefront scripts, tests) keep
+   * compiling without it. */
+  strings?: ThemeStringsDictionary[];
 }
 
 export const StorefrontContext = createContext<StorefrontContextValue | null>(null);
@@ -52,6 +65,7 @@ export function StorefrontProvider({
   basePath,
   pagesChrome,
   locale,
+  strings,
   children,
 }: {
   vendor: VendorProfile;
@@ -67,10 +81,27 @@ export function StorefrontProvider({
    * the host owns it, like `basePath`.
    */
   locale?: string | null;
+  /**
+   * Active locale's theme-string dictionaries (merchant override, theme
+   * locale, kit core locale — the host merges and passes ONLY the active
+   * locale, loaded per-locale so no other language ships to the client).
+   * Optional — absent means English defaults, and every kit component
+   * renders exactly as before. Existing props are untouched.
+   */
+  strings?: ThemeStringsDictionary | ThemeStringsDictionary[] | null;
   children: ReactNode;
 }): JSX.Element {
   const resolvedBasePath = basePath ?? `/${vendor.slug ?? ''}`;
   const resolvedLocale = parseLocaleCode(locale);
+  const resolvedStrings = useMemo(
+    () =>
+      !strings
+        ? []
+        : (Array.isArray(strings) ? strings : [strings]).filter(
+            (d): d is ThemeStringsDictionary => !!d,
+          ),
+    [strings],
+  );
   const value = useMemo(
     () => ({
       vendor,
@@ -80,8 +111,9 @@ export function StorefrontProvider({
       basePath: resolvedBasePath,
       pagesChrome: pagesChrome ?? {},
       locale: resolvedLocale,
+      strings: resolvedStrings,
     }),
-    [config, menus, previewData, vendor, resolvedBasePath, pagesChrome, resolvedLocale],
+    [config, menus, previewData, vendor, resolvedBasePath, pagesChrome, resolvedLocale, resolvedStrings],
   );
   const brandRootRef = useRef<HTMLDivElement>(null);
 
@@ -120,3 +152,37 @@ export function useStorefrontLocale(): string | null {
 
   return context.locale ?? null;
 }
+
+/**
+ * The client theme-string surface: the bound `t` for the active locale.
+ * Chain order: merchant/host override dictionaries (`strings` prop), then
+ * the mounted theme's `manifest.strings` (theme English — travels WITH the
+ * theme, so preview hosts that pass no `strings` still render English),
+ * then the kit core English default — never the raw key. Works in themes
+ * mounted by `ThemeMount` and in hosts that provide the theme directly
+ * (both expose it through the theme context). No `strings` prop and no
+ * manifest → the English defaults, so kit components render exactly as
+ * before and third-party themes keep working untranslated.
+ */
+export function useThemeStrings(): ThemeStringsFn {
+  const context = useContext(StorefrontContext);
+
+  if (!context) {
+    throw new Error('useThemeStrings must be used within StorefrontProvider');
+  }
+
+  const theme = useOptionalTheme();
+  const manifestStrings = theme?.manifest?.strings ?? null;
+  const { strings, locale } = context;
+  return useMemo(
+    () =>
+      (key: string, vars?: ThemeStringsVars, overrideLocale?: string | null) =>
+        translateThemeStrings(
+          [...(strings ?? []), ...(manifestStrings ? [manifestStrings] : []), defaultThemeStrings],
+          key,
+          vars,
+          overrideLocale ?? locale ?? undefined,
+        ),
+    [strings, manifestStrings, locale],
+  );
+}