@thorprovider/storefront 0.14.0 → 0.15.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (112) hide show
  1. package/README.md +28 -12
  2. package/assets/templates/app/app/[[...slug]]/page.tsx +6 -0
  3. package/assets/templates/app/app/layout.tsx +2 -2
  4. package/assets/templates/app/lib/__STOREFRONT__/commerce.ts +11 -4
  5. package/assets/templates/app/lib/__STOREFRONT__/confirmation.core.ts +7 -4
  6. package/assets/templates/app/lib/__STOREFRONT__/mappers.ts +18 -3
  7. package/assets/templates/app/lib/__STOREFRONT__/registry.tsx +10 -0
  8. package/assets/templates/app/lib/__STOREFRONT__/state.core.ts +8 -0
  9. package/assets/templates/app/lib/__STOREFRONT__/store-context.ts +84 -18
  10. package/assets/templates/app/lib/__STOREFRONT__/views/sections/schema.universal-main-menu.ts +3 -1
  11. package/assets/templates/app/public/images/README.md +43 -0
  12. package/assets/templates/app/public/images/banners/banner-aurora-deal.webp +0 -0
  13. package/assets/templates/app/public/images/banners/banner-guia-regalo.webp +0 -0
  14. package/assets/templates/app/public/images/banners/banner-mesa-decor.webp +0 -0
  15. package/assets/templates/app/public/images/banners/banner-nuevas-llegadas.webp +0 -0
  16. package/assets/templates/app/public/images/banners/banner-salon-oferta.webp +0 -0
  17. package/assets/templates/app/public/images/categories/accessories.webp +0 -0
  18. package/assets/templates/app/public/images/categories/dresses.webp +0 -0
  19. package/assets/templates/app/public/images/categories/furniture.webp +0 -0
  20. package/assets/templates/app/public/images/categories/home.webp +0 -0
  21. package/assets/templates/app/public/images/categories/jackets.webp +0 -0
  22. package/assets/templates/app/public/images/editorial/studio.webp +0 -0
  23. package/assets/templates/app/public/images/products/alpine-jacket.webp +0 -0
  24. package/assets/templates/app/public/images/products/amber-dress.webp +0 -0
  25. package/assets/templates/app/public/images/products/atlas-lamp.webp +0 -0
  26. package/assets/templates/app/public/images/products/atlas-sofa.webp +0 -0
  27. package/assets/templates/app/public/images/products/aurora-jacket.webp +0 -0
  28. package/assets/templates/app/public/images/products/boreal-jacket.webp +0 -0
  29. package/assets/templates/app/public/images/products/camille-dress.webp +0 -0
  30. package/assets/templates/app/public/images/products/ceramic-table-lamp.webp +0 -0
  31. package/assets/templates/app/public/images/products/cinder-jacket.webp +0 -0
  32. package/assets/templates/app/public/images/products/copper-lamp.webp +0 -0
  33. package/assets/templates/app/public/images/products/cove-bag.webp +0 -0
  34. package/assets/templates/app/public/images/products/dahlia-dress.webp +0 -0
  35. package/assets/templates/app/public/images/products/drift-jacket.webp +0 -0
  36. package/assets/templates/app/public/images/products/dune-lamp.webp +0 -0
  37. package/assets/templates/app/public/images/products/elara-dress.webp +0 -0
  38. package/assets/templates/app/public/images/products/ember-jacket.webp +0 -0
  39. package/assets/templates/app/public/images/products/fable-bag.webp +0 -0
  40. package/assets/templates/app/public/images/products/fjord-jacket.webp +0 -0
  41. package/assets/templates/app/public/images/products/floor-cushion.webp +0 -0
  42. package/assets/templates/app/public/images/products/harbor-jacket.webp +0 -0
  43. package/assets/templates/app/public/images/products/helios-lamp.webp +0 -0
  44. package/assets/templates/app/public/images/products/iris-dress.webp +0 -0
  45. package/assets/templates/app/public/images/products/juniper-bag.webp +0 -0
  46. package/assets/templates/app/public/images/products/kestrel-bag.webp +0 -0
  47. package/assets/templates/app/public/images/products/linen-armchair.webp +0 -0
  48. package/assets/templates/app/public/images/products/lumen-dress.webp +0 -0
  49. package/assets/templates/app/public/images/products/luna-bag.webp +0 -0
  50. package/assets/templates/app/public/images/products/marble-coffee-table.webp +0 -0
  51. package/assets/templates/app/public/images/products/marlowe-bag.webp +0 -0
  52. package/assets/templates/app/public/images/products/meridian-jacket.webp +0 -0
  53. package/assets/templates/app/public/images/products/nomad-jacket.webp +0 -0
  54. package/assets/templates/app/public/images/products/nova-dress.webp +0 -0
  55. package/assets/templates/app/public/images/products/oak-dining-table.webp +0 -0
  56. package/assets/templates/app/public/images/products/onyx-lamp.webp +0 -0
  57. package/assets/templates/app/public/images/products/piper-bag.webp +0 -0
  58. package/assets/templates/app/public/images/products/quill-lamp.webp +0 -0
  59. package/assets/templates/app/public/images/products/rosalind-dress.webp +0 -0
  60. package/assets/templates/app/public/images/products/rune-bag.webp +0 -0
  61. package/assets/templates/app/public/images/products/side-table.webp +0 -0
  62. package/assets/templates/app/public/images/products/slate-lamp.webp +0 -0
  63. package/assets/templates/app/public/images/products/solis-dress.webp +0 -0
  64. package/assets/templates/app/public/images/products/storage-shelf.webp +0 -0
  65. package/assets/templates/app/public/images/products/terra-lamp.webp +0 -0
  66. package/assets/templates/app/public/images/products/tundra-jacket.webp +0 -0
  67. package/assets/templates/app/public/images/products/vantage-jacket.webp +0 -0
  68. package/assets/templates/app/public/images/products/vera-dress.webp +0 -0
  69. package/assets/templates/app/public/images/products/verdant-lamp.webp +0 -0
  70. package/assets/templates/app/public/images/products/wall-mirror.webp +0 -0
  71. package/assets/templates/app/public/images/products/wool-rug.webp +0 -0
  72. package/assets/templates/views/account/address-book-advanced.defaults.ts +1 -1
  73. package/assets/templates/views/cart/registry.tsx +9 -0
  74. package/assets/templates/views/checkout/checkout-commerce-hosted.tsx +5 -1
  75. package/assets/templates/views/home/assembly/assembly.json +0 -1
  76. package/assets/templates/views/home/assembly/index.skeleton.tsx +3 -7
  77. package/assets/templates/views/home/assembly/registry.skeleton.tsx +0 -3
  78. package/assets/templates/views/home/content.ts +34 -80
  79. package/assets/templates/views/home/data.ts +12 -0
  80. package/assets/templates/views/home/index.tsx +4 -21
  81. package/assets/templates/views/home/props.ts +1 -7
  82. package/assets/templates/views/home/registry.tsx +0 -35
  83. package/assets/templates/views/home/schema.ts +0 -36
  84. package/bin/storefront.js +12 -27
  85. package/package.json +3 -2
  86. package/recipes/archetypes.json +0 -21
  87. package/recipes/catalog.json +0 -22
  88. package/recipes/features.json +0 -2
  89. package/recipes/recipe.schema.json +5 -0
  90. package/recipes/recipes.json +19 -16
  91. package/recipes/validate.mjs +7 -0
  92. package/scripts/candidate.mjs +3 -3
  93. package/scripts/default-sections.mjs +1 -0
  94. package/scripts/env-file.mjs +10 -0
  95. package/scripts/file-classes.mjs +3 -0
  96. package/scripts/generate-demo-images.mjs +507 -0
  97. package/scripts/reconcile.mjs +32 -1
  98. package/scripts/render-templates.mjs +13 -1
  99. package/scripts/section-compat.mjs +10 -1
  100. package/scripts/section-operations.mjs +3 -0
  101. package/scripts/starter.mjs +25 -1
  102. package/scripts/theme/starter-theme.mjs +118 -0
  103. package/skills/sf-view-gen/assets/recipes/archetypes.json +0 -21
  104. package/skills/sf-view-gen/assets/recipes/catalog.json +0 -22
  105. package/skills/sf-view-gen/assets/recipes/features.json +0 -2
  106. package/skills/sf-view-gen/assets/recipes/recipes.json +19 -16
  107. package/skills/sf-view-gen/assets/templates/views/sections/schema.universal-main-menu.ts +3 -1
  108. package/skills/sf-view-gen/scripts/validate.mjs +7 -0
  109. package/assets/templates/views/home/assembly/slots/categories/CategoryGrid/binding.json +0 -5
  110. package/assets/templates/views/home/assembly/slots/categories/CategoryGrid/catalog.part +0 -8
  111. package/assets/templates/views/home/assembly/slots/categories/CategoryGrid/element.part +0 -5
  112. package/assets/templates/views/home/assembly/slots/categories/CategoryGrid/registry.part +0 -31
package/README.md CHANGED
@@ -110,9 +110,17 @@ storefront create my-shop \
110
110
  | `--site-name <name>` | human site name (`__SITE_NAME__`) | Title Case of `<name>` (`my-shop` → `My Shop`) |
111
111
  | `--preset <preset>` | visual preset: `maia`, `nova`, `vega`, `luma`, `lyra`, `mira` | prompted in the wizard (Maia preselected) |
112
112
  | `--starter` | seed the full curated composition — every curated view and feature — instead of the minimal `home`+`cart` baseline | off |
113
- | `--brand <color>` | named brand color (`orange`, `blue`, …) applied as a chromatic primary family (primary/foreground/ring/nav) over the preset tokens (never prompted) | none |
113
+ | `--brand <color>` | named brand color (`orange`, `blue`, …) applied as a chromatic primary family (primary/foreground/ring/nav) over the starter theme (never prompted) | none |
114
114
  | `--force`, `-f` | overwrite files that already exist | off |
115
115
 
116
+ Every scaffold ships a **marketplace starter theme** before any brand override:
117
+ an orange call-to-action with dark text on it, navy chrome, a grey page field with
118
+ white cards, and `0.25rem` corners — every color pair clears WCAG AA in both
119
+ modes. It is applied through the same theme plan as `storefront theme --set`
120
+ (`scripts/theme/starter-theme.mjs`), so a starter palette and a hand-applied one
121
+ cannot drift; `--brand` is applied last and still wins for the primary family. A
122
+ later `sync` never reverts a theme change.
123
+
116
124
  The pipeline runs: preconditions → Next.js base (files only) → `.yarnrc.yml`
117
125
  (`nodeLinker: node-modules`) → shadcn base with the preset → dependency install →
118
126
  template copy + placeholder substitution → mock `.env.local` + theme → suite install.
@@ -188,10 +196,15 @@ scopes the store, `MEDUSA_REGION_ID` supplies currency, countries, and shipping,
188
196
 
189
197
  `THOR_DATA_SOURCE` selects the mode **explicitly** and is never inferred from a failure.
190
198
  `mock` renders labelled demo data and resolves a fixture store context in code (channel
191
- `mock-sales-channel`, region `mock-region-us`, currency `USD`), so no context variables
192
- are required. `medusa` uses the real backend: a missing provider or invalid config is a
193
- **visible error** — never a silent fallback to demo data. Run `storefront setup`, then
194
- restart `yarn dev`.
199
+ `mock-sales-channel`, region `mock-region-uy`, currency `UYU`, locale `es-UY`), so no
200
+ context variables are required. `medusa` uses the real backend: a missing provider or
201
+ invalid config is a **visible error** — never a silent fallback to demo data. Run
202
+ `storefront setup`, then restart `yarn dev`.
203
+
204
+ `THOR_STORE_LOCALE` (BCP-47, e.g. `es-UY`) is the store's single shopper locale: it
205
+ governs `<html lang>` and every monetary surface — cart, cart sheet, checkout summary
206
+ and order confirmation all format with it. Optional; unset or blank falls back to
207
+ `es-UY`, matching the mock Uruguay region.
195
208
 
196
209
  ### Feature capability gating
197
210
 
@@ -206,13 +219,16 @@ storefront feature add customer-addresses # refused when the backend lacks man
206
219
 
207
220
  A failed probe records no list (unknown), so capability-gated features stay
208
221
  uninstallable until `storefront setup` succeeds again. In **mock mode** there is no
209
- endpoint to probe, so `setup` records the mock provider's own flags: the modules the
210
- mock genuinely supports (profile updates, address book, order history) install, and the
211
- ones it refuses truthfully (email change, password change, saved payment methods) stay
212
- out. `storefront doctor` re-probes and reports an installed feature whose capability the
213
- backend no longer advertises. Features also declare `requires` (a module needs its host
214
- feature) and `adapter.needs` (callables checked against the adapter/commerce surface),
215
- and a held feature is inspectable with `storefront features --json` but never installable.
222
+ endpoint to probe, so both `create` and `setup` record the mock provider's own flags:
223
+ a freshly scaffolded store installs the modules the mock genuinely supports (profile
224
+ updates, address book, order history), and the ones it refuses truthfully (email
225
+ change, password change, saved payment methods) stay out. `create` writes that list
226
+ because it always leaves the store in mock mode; `setup` replaces it with the live
227
+ probe when a real backend is connected. `storefront doctor` re-probes and reports an
228
+ installed feature whose capability the backend no longer advertises. Features also
229
+ declare `requires` (a module needs its host feature) and `adapter.needs` (callables
230
+ checked against the adapter/commerce surface), and a held feature is inspectable with
231
+ `storefront features --json` but never installable.
216
232
 
217
233
  The guest flow is backend-authoritative end to end: the signed host cookie binds a
218
234
  persistent backend cart; the PDP adds the explicitly selected variant; the cart and
@@ -8,6 +8,7 @@ import { readCartStateForRender } from '@/lib/__STOREFRONT__/cart-state'
8
8
  import { readAccountSession } from '@/lib/__STOREFRONT__/account-session'
9
9
  import { toAccountInitialState } from '@/lib/__STOREFRONT__/account-session.core'
10
10
  import { mountedFeatureNames, backendCapabilities } from '@/lib/__STOREFRONT__/composition'
11
+ import { getStoreLocale } from '@/lib/__STOREFRONT__/store-context'
11
12
  import { StorefrontRenderer } from './renderer'
12
13
 
13
14
  export const { generateMetadata, generateStaticParams } = __STOREFRONT_CAMEL__App
@@ -59,6 +60,11 @@ export default async function Page({
59
60
  const initialState = {
60
61
  ...(data.initialState ?? {}),
61
62
  navCategories,
63
+ // The shopper locale is resolved server-side (env-backed) and seeded for
64
+ // every route so the client registries build the same money formatter the
65
+ // shell's `<html lang>` uses. `getStoreLocale` never throws, so a
66
+ // misconfigured context still renders its visible cart/config error.
67
+ storeLocale: getStoreLocale(),
62
68
  ...cartState,
63
69
  ...accountState,
64
70
  }
@@ -5,7 +5,7 @@ import { Geist } from 'next/font/google'
5
5
  import { ThemeProvider } from 'next-themes'
6
6
  import { StorefrontProvider } from '@thorprovider/runtime/host-glue/providers'
7
7
  import { registry } from '@/lib/__STOREFRONT__/registry'
8
- import { getSiteUrl } from '@/lib/__STOREFRONT__/store-context'
8
+ import { getSiteUrl, getStoreLocale } from '@/lib/__STOREFRONT__/store-context'
9
9
  import './globals.css'
10
10
 
11
11
  const geist = Geist({
@@ -32,7 +32,7 @@ export default function RootLayout({
32
32
  children,
33
33
  }: Readonly<{ children: React.ReactNode }>) {
34
34
  return (
35
- <html lang="es" className={geist.variable} suppressHydrationWarning>
35
+ <html lang={getStoreLocale()} className={geist.variable} suppressHydrationWarning>
36
36
  <body className="font-sans antialiased">
37
37
  <ThemeProvider attribute="class" defaultTheme="__STOREFRONT_MODE__" enableSystem>
38
38
  <StorefrontProvider registry={registry}>
@@ -99,7 +99,7 @@ import type {
99
99
  StorefrontOrder,
100
100
  StorefrontOrderLineView,
101
101
  } from './state.core'
102
- import { assertBackendConfigured, getDataSource, getStoreContext, type StoreDataSource } from './store-context'
102
+ import { assertBackendConfigured, getDataSource, getStoreContext, getStoreLocale, type StoreDataSource } from './store-context'
103
103
  // The query engine is imported through its server-safe subpath: the package
104
104
  // root is a client entry (`'use client'`), so a Server Action cannot call a
105
105
  // function exported from it (React refuses a client function on the server).
@@ -294,14 +294,21 @@ export function toCheckoutFieldErrors(errors: CheckoutFieldError[]): CheckoutFie
294
294
  return grouped
295
295
  }
296
296
 
297
- /** Map the runtime's discriminated completion to the host result union. */
298
- export function toPlaceOrderResult(result: CartCompletionResult): PlaceOrderResult {
297
+ /**
298
+ * Map the runtime's discriminated completion to the host result union. The
299
+ * confirmation carries the store's shopper locale; callers may pass it
300
+ * explicitly, otherwise it resolves from the host environment (server-side).
301
+ */
302
+ export function toPlaceOrderResult(
303
+ result: CartCompletionResult,
304
+ locale: string = getStoreLocale(),
305
+ ): PlaceOrderResult {
299
306
  if (result.type === 'order') {
300
307
  return {
301
308
  status: 'order',
302
309
  order: toStorefrontOrder(result.order),
303
310
  lines: toOrderLines(result.order),
304
- confirmation: toStorefrontConfirmation(result.order),
311
+ confirmation: toStorefrontConfirmation(result.order, locale),
305
312
  ...(result.paymentSummary ? { paymentSummary: result.paymentSummary } : {}),
306
313
  }
307
314
  }
@@ -122,8 +122,11 @@ function normalizeImageUrl(url: string | null | undefined): string | undefined {
122
122
  * Build the designer confirmation from the host-confirmed order. The order is
123
123
  * the single source: addresses, delivery method, payment label and totals are
124
124
  * only included when the backend reports them; the view omits what is absent.
125
+ * The caller supplies the store's shopper locale so the confirmation formats
126
+ * money identically to the cart and checkout (design D4) — never a hardcoded
127
+ * presentation locale.
125
128
  */
126
- export function toStorefrontConfirmation(order: Order): StorefrontConfirmation {
129
+ export function toStorefrontConfirmation(order: Order, locale: string): StorefrontConfirmation {
127
130
  const shippingAddress = order.shippingAddress
128
131
  const recipient = shippingAddress
129
132
  ? `${shippingAddress.firstName} ${shippingAddress.lastName}`.trim()
@@ -267,9 +270,9 @@ export function toStorefrontConfirmation(order: Order): StorefrontConfirmation {
267
270
  billingDetail: billing ? addressDetail(billing) : '',
268
271
  customerName,
269
272
  customerEmail: order.email,
270
- // The storefront's money presentation uses the design's en-US dollar
271
- // format; copy stays in the store language.
272
- locale: 'en-US',
273
+ // The store's shopper locale, supplied by the host from the store context;
274
+ // copy stays in the store language.
275
+ locale,
273
276
  currencyCode: order.total.currencyCode,
274
277
  }
275
278
  }
@@ -5,6 +5,21 @@
5
5
 
6
6
  import type { CardProduct, FeaturedProduct, ProductCategoryItem, StoreCategory } from '@thorprovider/blocks'
7
7
 
8
+ /** Base of the starter's local demo imagery (see `public/images/README.md`). */
9
+ const CATEGORY_IMAGE_BASE = '/images/categories'
10
+
11
+ /**
12
+ * Category shot for a `StoreCategory`. The category URL is `/categories/<handle>`
13
+ * and the starter ships one shot per handle, so the handle is the file name: a
14
+ * swapped photo needs no mapper change. The runtime projection carries no image,
15
+ * so the local asset is the source here; `CATEGORY_IMAGE_FALLBACK` covers a
16
+ * category without a shipped file (e.g. a real backend's own taxonomy).
17
+ */
18
+ export function categoryImage(href: string): string {
19
+ const handle = href.split('/').filter(Boolean).pop()
20
+ return handle ? `${CATEGORY_IMAGE_BASE}/${handle}.webp` : CATEGORY_IMAGE_FALLBACK
21
+ }
22
+
8
23
  export const CATEGORY_IMAGE_FALLBACK =
9
24
  "data:image/svg+xml;charset=utf-8," +
10
25
  encodeURIComponent(
@@ -38,15 +53,15 @@ export function toFeaturedProduct(card: CardProduct): FeaturedProduct {
38
53
  * carries no product count, so `itemCount` is unknown here: it is OMITTED (the
39
54
  * block then renders no count) rather than fabricated as `0`. A genuine `0`
40
55
  * supplied by a richer source is preserved because `itemCount` is optional.
41
- * `image` seeds the storefront's editorial category imagery — the brand overlay
42
- * rekeys it by backend handle; the block also supplies a neutral placeholder. */
56
+ * `image` is the shipped shot for the category's handle (see `categoryImage`),
57
+ * so a category tile never renders the neutral block placeholder by default. */
43
58
  export function toCategoryCard(category: StoreCategory): ProductCategoryItem {
44
59
  return {
45
60
  id: category.label,
46
61
  handle: category.href,
47
62
  name: category.label,
48
63
  description: '',
49
- image: CATEGORY_IMAGE_FALLBACK,
64
+ image: categoryImage(category.href),
50
65
  trending: false,
51
66
  }
52
67
  }
@@ -25,6 +25,7 @@ import { isAvailableMoney } from '@thorprovider/blocks/contracts'
25
25
  import type { Money } from '@thorprovider/types'
26
26
  import { catalog } from './catalog'
27
27
  import type { CartLineState, CartTotalsState } from './state'
28
+ import { createStoreMoneyFormatter, DEFAULT_STORE_LOCALE } from './store-context'
28
29
  import { useStorefrontHandlers } from './handlers'
29
30
  import { cartViewAvailable, checkoutAvailable, mountedFeatureNames } from './composition'
30
31
  import { accountStoreUser } from './account-user.core'
@@ -165,6 +166,14 @@ const baseComponents = {
165
166
  ) as AccountResolution | 'unresolved'
166
167
  const cart = (state.cart ?? []) as CartLineState[]
167
168
  const totals = state.cartTotals as CartTotalsState | null
169
+ // One money formatter for the whole shell, built from the shopper locale
170
+ // the catch-all host seeded (the same locale as `<html lang>`). The navbar
171
+ // forwards it to the cart sheet, so every chrome money surface agrees.
172
+ const storeLocale =
173
+ typeof state.storeLocale === 'string' && state.storeLocale.trim() !== ''
174
+ ? state.storeLocale
175
+ : DEFAULT_STORE_LOCALE
176
+ const formatMoney = createStoreMoneyFormatter(storeLocale)
168
177
  const cartError = typeof state.cartError === 'string' ? state.cartError : undefined
169
178
  const readError = typeof state.cartReadError === 'string' ? state.cartReadError : undefined
170
179
  const errorLabel = cartError ?? readError
@@ -215,6 +224,7 @@ const baseComponents = {
215
224
  showSearch={parsed.showSearch ?? false}
216
225
  items={toNavCartItems(cart)}
217
226
  subtotal={totals?.subtotal}
227
+ formatMoney={formatMoney}
218
228
  // One shared lateral: visibility is driven by the shared `cartOpen`
219
229
  // state (a successful add opens it; navigation dismisses it). The
220
230
  // canonical line amounts and lifecycle states come from the same cart
@@ -14,6 +14,7 @@ import type {
14
14
  ProductDetailProduct,
15
15
  } from '@thorprovider/blocks'
16
16
  import type { Money, PaymentMethod } from '@thorprovider/types'
17
+ import { DEFAULT_STORE_LOCALE } from './store-context'
17
18
 
18
19
  /** Real review, rendered only when the backend supplies it. */
19
20
  export interface ProductReview {
@@ -208,6 +209,12 @@ export interface StorefrontCoreState {
208
209
  dataNoticeDismissed: boolean
209
210
  /** Explicit data source; `'mock'` is always labelled as demo data. */
210
211
  dataSource: 'mock' | 'medusa'
212
+ /**
213
+ * The store's shopper locale (BCP-47). Seeded by the catch-all host from the
214
+ * store context so every client surface formats money with the same locale
215
+ * the server rendered `<html lang>` with; the default matches the scaffold.
216
+ */
217
+ storeLocale: string
211
218
  /** Visible real-mode failure; null when the data loaded. */
212
219
  dataError: string | null
213
220
  cartOpen: boolean
@@ -269,6 +276,7 @@ export const storefrontCoreState: StorefrontCoreState = {
269
276
  bannerDismissed: false,
270
277
  dataNoticeDismissed: false,
271
278
  dataSource: 'mock',
279
+ storeLocale: DEFAULT_STORE_LOCALE,
272
280
  dataError: null,
273
281
  cartOpen: false,
274
282
  cart: [],
@@ -5,8 +5,11 @@
5
5
  // any commerce call, so an incomplete or invalid configuration fails visibly
6
6
  // instead of silently falling back to demo data.
7
7
  //
8
- // Boundary: this module is server-only and reads no Next.js or React API. It
9
- // owns the environment contract; the commerce bridge owns the backend calls.
8
+ // Boundary: the environment-reading functions are server-only and read no
9
+ // Next.js or React API. This module owns the environment contract; the
10
+ // commerce bridge owns the backend calls. The pure exports (locale default,
11
+ // `createStoreMoneyFormatter`) carry no env reads and are safe in the client
12
+ // registries, which receive the resolved locale through the seeded state.
10
13
  //
11
14
  // The values are the multitenancy seam: a future tenancy layer varies
12
15
  // storeId/channel/region/currency without redefining the commerce shapes. In
@@ -14,7 +17,7 @@
14
17
  // environment; mock mode resolves a labelled fixture context so the store runs
15
18
  // with no environment configured at all.
16
19
 
17
- import type { StoreContext } from '@thorprovider/types'
20
+ import type { Money, StoreContext } from '@thorprovider/types'
18
21
  import { storeContextSchema } from '@thorprovider/runtime/contracts'
19
22
 
20
23
  /** Data source selected explicitly by the host; never inferred from a failure. */
@@ -44,6 +47,66 @@ export const DATA_SOURCE_ENV = 'THOR_DATA_SOURCE'
44
47
  */
45
48
  export const SITE_URL_ENV = 'THOR_SITE_URL'
46
49
 
50
+ /**
51
+ * Host environment variable with the shopper locale (BCP-47, e.g. `es-UY`).
52
+ * One locale governs `<html lang>` and every monetary surface. Optional: when
53
+ * unset or blank the store falls back to `DEFAULT_STORE_LOCALE`.
54
+ */
55
+ export const LOCALE_ENV = 'THOR_STORE_LOCALE'
56
+
57
+ /**
58
+ * The scaffold's default shopper locale: the generated starter is a Spanish
59
+ * shop for a Uruguayan merchant, matching the mock Uruguay region (design D4).
60
+ */
61
+ export const DEFAULT_STORE_LOCALE = 'es-UY'
62
+
63
+ /**
64
+ * The store's shopper locale (BCP-47). Pure env read with a safe default; it
65
+ * never throws, so a missing override degrades to the scaffold default instead
66
+ * of failing the render.
67
+ */
68
+ export function getStoreLocale(): string {
69
+ const value = process.env[LOCALE_ENV]?.trim()
70
+ return value ? value : DEFAULT_STORE_LOCALE
71
+ }
72
+
73
+ /**
74
+ * The generated store's context: the shared validated `StoreContext` plus the
75
+ * shopper locale. The locale is a presentation concern owned by the host, so
76
+ * it extends the shared commerce shape here rather than in the backend
77
+ * contract.
78
+ */
79
+ export interface StorefrontStoreContext extends StoreContext {
80
+ /** BCP-47 shopper locale governing the document language and money. */
81
+ locale: string
82
+ }
83
+
84
+ /**
85
+ * Build the store's single money formatter from a locale. Pure and total, so
86
+ * the client registries can build the identical formatter from the locale the
87
+ * server seeded into the state store; `formatStoreMoney` below is the
88
+ * server-side convenience that resolves the locale itself. The currency always
89
+ * comes from the `Money` value — never hardcoded.
90
+ */
91
+ export function createStoreMoneyFormatter(locale: string): (value: Money) => string {
92
+ return (value) =>
93
+ new Intl.NumberFormat(locale, {
94
+ style: 'currency',
95
+ currency: value.currencyCode,
96
+ }).format(Number(value.amount))
97
+ }
98
+
99
+ /**
100
+ * Format a `Money` with the store's shopper locale. Server-side surfaces use
101
+ * this directly; client surfaces receive the same rendering through
102
+ * `createStoreMoneyFormatter(state.storeLocale)`. Callers gate availability
103
+ * first (the blocks' `formatMoney` safety gate) — this helper formats the
104
+ * canonical `Money` it is given.
105
+ */
106
+ export function formatStoreMoney(value: Money): string {
107
+ return createStoreMoneyFormatter(getStoreContext().locale)(value)
108
+ }
109
+
47
110
  /**
48
111
  * Visible configuration failure. Thrown before commerce so a missing or invalid
49
112
  * store context surfaces as an error instead of fictional data.
@@ -94,15 +157,17 @@ export function getSiteUrl(): string | undefined {
94
157
 
95
158
  /**
96
159
  * Fixture context resolved in mock mode. It satisfies `storeContextSchema` and
97
- * mirrors the values the bundled mock provider serves, so a store with no
98
- * environment configured still has a valid context to render and operate its
99
- * cart against. It is a labelled fixture, never a real backend identity.
160
+ * mirrors the values the bundled mock provider serves — the Uruguay region in
161
+ * UYU with the `es-UY` shopper locale — so a store with no environment
162
+ * configured still has a valid context whose country and currency agree with
163
+ * the commerce data. It is a labelled fixture, never a real backend identity.
100
164
  */
101
- export const MOCK_STORE_CONTEXT: StoreContext = {
165
+ export const MOCK_STORE_CONTEXT: StorefrontStoreContext = {
102
166
  storeId: 'mock-store',
103
167
  salesChannelId: 'mock-sales-channel',
104
- regionId: 'mock-region-us',
105
- currencyCode: 'USD',
168
+ regionId: 'mock-region-uy',
169
+ currencyCode: 'UYU',
170
+ locale: DEFAULT_STORE_LOCALE,
106
171
  }
107
172
 
108
173
  function requireEnv(name: string): string {
@@ -118,15 +183,16 @@ function requireEnv(name: string): string {
118
183
  /**
119
184
  * Resolve and validate the single-store context.
120
185
  *
121
- * Mock mode returns the labelled fixture context and reads no environment
122
- * variables, so a created store runs with no configuration. Real mode resolves
123
- * the four variables from the host environment and validates them through the
124
- * shared runtime schema, so an invalid context is rejected before any commerce
125
- * call. Throws `StoreConfigError` naming the missing variable — never a secret
126
- * value.
186
+ * Mock mode returns the labelled fixture context and reads none of the four
187
+ * backend variables, so a created store runs with no configuration; only the
188
+ * optional shopper-locale override (`THOR_STORE_LOCALE`) is honoured. Real mode
189
+ * resolves the four variables from the host environment and validates them
190
+ * through the shared runtime schema, so an invalid context is rejected before
191
+ * any commerce call. The shopper locale is attached in both modes. Throws
192
+ * `StoreConfigError` naming the missing variable — never a secret value.
127
193
  */
128
- export function getStoreContext(): StoreContext {
129
- if (!isRealMode()) return MOCK_STORE_CONTEXT
194
+ export function getStoreContext(): StorefrontStoreContext {
195
+ if (!isRealMode()) return { ...MOCK_STORE_CONTEXT, locale: getStoreLocale() }
130
196
  const candidate = {
131
197
  storeId: requireEnv(STORE_CONTEXT_ENV.storeId),
132
198
  salesChannelId: requireEnv(STORE_CONTEXT_ENV.salesChannelId),
@@ -140,7 +206,7 @@ export function getStoreContext(): StoreContext {
140
206
  .join('; ')
141
207
  throw new StoreConfigError(`Invalid store context: ${issues}`)
142
208
  }
143
- return parsed.data
209
+ return { ...parsed.data, locale: getStoreLocale() }
144
210
  }
145
211
 
146
212
  /**
@@ -1,5 +1,5 @@
1
1
  // Optional section fragment: universal-main-menu (mirrors recipes/sections.json) — shared contract.
2
- // Zod mirror of the UniversalMainMenu block contract (delivery universal-main-menu, contract version 4.3.2),
2
+ // Zod mirror of the UniversalMainMenu block contract (delivery universal-main-menu, contract version 4.6.1),
3
3
  // shared by the server catalog (universal-main-menu.tsx) and the client registry (universal-main-menu.client.tsx).
4
4
  // The React-only callbacks (onNavigate, onOpenChange) are intentionally excluded.
5
5
 
@@ -79,6 +79,8 @@ export const universalMainMenuDataSchema = z.object({
79
79
  }),
80
80
  behavior: z.object({
81
81
  platform: z.string().optional(),
82
+ anchor: z.string().optional(),
83
+ trigger: z.string().optional(),
82
84
  mobilePattern: z.string().optional(),
83
85
  openOnHover: z.boolean().optional(),
84
86
  openDelayMs: z.number().optional(),
@@ -0,0 +1,43 @@
1
+ # Demo imagery
2
+
3
+ Local static images the starter ships so a generated store looks like a shop
4
+ without a network call. Everything here is served from `public/`, so these are
5
+ plain files, not a CDN and not remote URLs.
6
+
7
+ Replace any file with your own shot **at the same path** — no code change, no
8
+ manifest, no rebuild step. Delete a file and the block falls back to its own
9
+ placeholder.
10
+
11
+ | Path | Size | Used by |
12
+ | --- | --- | --- |
13
+ | `products/<handle>.webp` | 1200×1200 (square) | product cards in the grid and the sliders, product gallery |
14
+ | `categories/<handle>.webp` | 900×900 (square) | category tiles |
15
+ | `banners/<banner-id>.webp` | 1800×1000 (landscape) | campaign banners on the home view |
16
+ | `editorial/studio.webp` | 1600×1200 | the benefits section (rendered in grayscale) |
17
+
18
+ The file name is the contract: `<handle>` is the product or category handle in
19
+ your catalog, `<banner-id>` is the id of the banner in `views/home/content.ts`.
20
+ Serving a new banner is a new file plus its id in the content; serving a new
21
+ product is a new file named after the product.
22
+
23
+ ## How the mock catalog finds these
24
+
25
+ Mock mode resolves `<base>/products/<handle>.webp` and
26
+ `<base>/categories/<handle>.webp`, where `<base>` is `THOR_MOCK_ASSETS` from
27
+ `.env.local` (`/images` in a generated store). Unset the variable and the mock
28
+ provider draws its own SVG placeholders instead, so the store still renders
29
+ with no assets at all.
30
+
31
+ Real mode (Medusa) ignores this folder entirely — the backend serves its own
32
+ product images.
33
+
34
+ ## Regenerating the shipped art
35
+
36
+ ```bash
37
+ yarn workspace @thorprovider/storefront demo:images --force
38
+ ```
39
+
40
+ The script (`scripts/generate-demo-images.mjs`) renders deterministic SVG
41
+ through `sharp`. The shipped art is illustration, not photography: it exists to
42
+ show the composition a real shot belongs in. Swap in photography for a
43
+ production store.