@thorprovider/storefront 0.4.0-mvp.0 → 0.4.0

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 (225) hide show
  1. package/README.md +174 -156
  2. package/VENDOR.md +69 -0
  3. package/assets/openspec/config.yaml +38 -0
  4. package/assets/templates/AGENTS.md +76 -0
  5. package/assets/templates/app/app/[[...slug]]/page.tsx +56 -2
  6. package/assets/templates/app/app/[[...slug]]/renderer.tsx +44 -2
  7. package/assets/templates/app/app/globals.css +5 -8
  8. package/assets/templates/app/app/layout.tsx +1 -5
  9. package/assets/templates/app/app/robots.ts +9 -3
  10. package/assets/templates/app/app/sitemap.ts +64 -5
  11. package/assets/templates/app/lib/__STOREFRONT__/account-boundary.client.tsx +76 -0
  12. package/assets/templates/app/lib/__STOREFRONT__/account-lifecycle.client.tsx +461 -0
  13. package/assets/templates/app/lib/__STOREFRONT__/account-mutation.client.ts +46 -0
  14. package/assets/templates/app/lib/__STOREFRONT__/account-private.core.ts +103 -0
  15. package/assets/templates/app/lib/__STOREFRONT__/account-reconcile.client.ts +465 -0
  16. package/assets/templates/app/lib/__STOREFRONT__/account-session.core.ts +177 -0
  17. package/assets/templates/app/lib/__STOREFRONT__/account-session.ts +44 -0
  18. package/assets/templates/app/lib/__STOREFRONT__/account-user.core.ts +65 -0
  19. package/assets/templates/app/lib/__STOREFRONT__/actions.ts +135 -16
  20. package/assets/templates/app/lib/__STOREFRONT__/catalog.ts +19 -9
  21. package/assets/templates/app/lib/__STOREFRONT__/commerce.ts +61 -0
  22. package/assets/templates/app/lib/__STOREFRONT__/composition.ts +26 -0
  23. package/assets/templates/app/lib/__STOREFRONT__/handlers.core.ts +36 -4
  24. package/assets/templates/app/lib/__STOREFRONT__/mappers.ts +17 -18
  25. package/assets/templates/app/lib/__STOREFRONT__/projection-ownership.client.tsx +209 -0
  26. package/assets/templates/app/lib/__STOREFRONT__/projection-ownership.ts +247 -0
  27. package/assets/templates/app/lib/__STOREFRONT__/registry.tsx +123 -62
  28. package/assets/templates/app/lib/__STOREFRONT__/runtime.ts +3 -0
  29. package/assets/templates/app/lib/__STOREFRONT__/schema.ts +78 -25
  30. package/assets/templates/app/lib/__STOREFRONT__/section-observation.ts +182 -0
  31. package/assets/templates/app/lib/__STOREFRONT__/section-sources.ts +128 -0
  32. package/assets/templates/app/lib/__STOREFRONT__/shell/content.ts +31 -7
  33. package/assets/templates/app/lib/__STOREFRONT__/shell/props.ts +4 -0
  34. package/assets/templates/app/lib/__STOREFRONT__/spec/index.ts +81 -26
  35. package/assets/templates/app/lib/__STOREFRONT__/spec/seo.ts +165 -0
  36. package/assets/templates/app/lib/__STOREFRONT__/state.core.ts +4 -2
  37. package/assets/templates/app/lib/__STOREFRONT__/store-context.ts +26 -7
  38. package/assets/templates/app/lib/__STOREFRONT__/views/sections/cta.client.tsx +1 -1
  39. package/assets/templates/app/lib/__STOREFRONT__/views/sections/faq.client.tsx +1 -1
  40. package/assets/templates/app/lib/__STOREFRONT__/views/sections/index.ts +2 -1
  41. package/assets/templates/app/lib/__STOREFRONT__/views/sections/logoCloud.tsx +1 -1
  42. package/assets/templates/app/lib/__STOREFRONT__/views/sections/pricing.tsx +1 -1
  43. package/assets/templates/app/lib/__STOREFRONT__/views/sections/products.client.tsx +100 -0
  44. package/assets/templates/app/lib/__STOREFRONT__/views/sections/products.tsx +19 -0
  45. package/assets/templates/app/lib/__STOREFRONT__/views/sections/schema.products.ts +39 -0
  46. package/assets/templates/app/lib/__STOREFRONT__/views/sections/statistics.tsx +1 -1
  47. package/assets/templates/app/lib/__STOREFRONT__/views/sections/testimonials.tsx +1 -1
  48. package/assets/templates/features/checkout/handlers.ts +6 -0
  49. package/assets/templates/features/customer-auth/handlers.ts +19 -23
  50. package/assets/templates/features/customer-auth/state.ts +31 -1
  51. package/assets/templates/views/account/index.tsx +20 -8
  52. package/assets/templates/views/account/registry.tsx +294 -154
  53. package/assets/templates/views/account/schema.ts +1 -0
  54. package/assets/templates/views/cart/content.ts +11 -0
  55. package/assets/templates/views/cart/data.ts +23 -0
  56. package/assets/templates/views/cart/index.tsx +53 -0
  57. package/assets/templates/views/cart/props.ts +12 -0
  58. package/assets/templates/views/cart/registry.tsx +82 -0
  59. package/assets/templates/views/cart/schema.ts +52 -0
  60. package/assets/templates/views/category/assembly/assembly.json +2 -1
  61. package/assets/templates/views/category/assembly/index.skeleton.tsx +64 -6
  62. package/assets/templates/views/category/assembly/registry.skeleton.tsx +7 -6
  63. package/assets/templates/views/category/assembly/slots/breadcrumb/Breadcrumb/binding.json +5 -0
  64. package/assets/templates/views/category/assembly/slots/breadcrumb/Breadcrumb/catalog.part +4 -0
  65. package/assets/templates/views/category/assembly/slots/breadcrumb/Breadcrumb/element.part +7 -0
  66. package/assets/templates/views/category/assembly/slots/breadcrumb/Breadcrumb/registry.part +18 -0
  67. package/assets/templates/views/category/index.tsx +76 -7
  68. package/assets/templates/views/category/props.ts +7 -0
  69. package/assets/templates/views/category/registry.tsx +25 -6
  70. package/assets/templates/views/category/schema.ts +13 -0
  71. package/assets/templates/views/checkout/registry.tsx +3 -5
  72. package/assets/templates/views/home/assembly/assembly.json +12 -3
  73. package/assets/templates/views/home/assembly/index.skeleton.tsx +24 -5
  74. package/assets/templates/views/home/assembly/registry.skeleton.tsx +4 -1
  75. package/assets/templates/views/home/assembly/slots/benefits/cards/binding.json +5 -0
  76. package/assets/templates/views/home/assembly/slots/benefits/cards/registry.part +17 -0
  77. package/assets/templates/views/home/assembly/slots/benefits/split/binding.json +5 -0
  78. package/assets/templates/views/home/assembly/slots/benefits/{Feature1 → split}/registry.part +6 -2
  79. package/assets/templates/views/home/assembly/slots/categories/CategoryGrid/binding.json +5 -0
  80. package/assets/templates/views/home/assembly/slots/categories/CategoryGrid/catalog.part +8 -0
  81. package/assets/templates/views/home/assembly/slots/categories/{ProductCategory2 → CategoryGrid}/element.part +1 -1
  82. package/assets/templates/views/home/assembly/slots/categories/CategoryGrid/registry.part +31 -0
  83. package/assets/templates/views/home/assembly/slots/hero/StorefrontHero/binding.json +5 -0
  84. package/assets/templates/views/home/assembly/slots/hero/StorefrontHero/catalog.part +4 -0
  85. package/assets/templates/views/home/assembly/slots/hero/StorefrontHero/element.part +5 -0
  86. package/assets/templates/views/home/assembly/slots/hero/{StorefrontHero1 → StorefrontHero}/registry.part +5 -3
  87. package/assets/templates/views/home/content.ts +22 -0
  88. package/assets/templates/views/home/data.ts +9 -0
  89. package/assets/templates/views/home/index.tsx +34 -11
  90. package/assets/templates/views/home/props.ts +1 -0
  91. package/assets/templates/views/home/registry.tsx +41 -17
  92. package/assets/templates/views/home/schema.ts +141 -24
  93. package/assets/templates/views/product/data.ts +5 -3
  94. package/assets/templates/views/product/index.tsx +49 -5
  95. package/assets/templates/views/product/props.ts +7 -0
  96. package/assets/templates/views/product/registry.tsx +34 -5
  97. package/assets/templates/views/product/schema.ts +49 -1
  98. package/assets/templates/views/static/content.ts +4 -4
  99. package/assets/templates/views/static/index.tsx +1 -1
  100. package/bin/storefront.js +1231 -154
  101. package/examples/merchandising/category-led.json +37 -0
  102. package/examples/merchandising/collection-led.json +37 -0
  103. package/package.json +10 -7
  104. package/recipes/archetypes.json +33 -46
  105. package/recipes/catalog.json +245 -153
  106. package/recipes/catalog.mjs +10 -0
  107. package/recipes/catalog.schema.json +4 -0
  108. package/recipes/features.json +28 -5
  109. package/recipes/recipe.schema.json +1 -1
  110. package/recipes/recipes.json +159 -59
  111. package/recipes/sections.json +10 -0
  112. package/recipes/validate.mjs +75 -4
  113. package/scripts/candidate.mjs +4 -4
  114. package/scripts/composers.mjs +25 -5
  115. package/scripts/env-file.mjs +86 -0
  116. package/scripts/file-classes.mjs +15 -0
  117. package/scripts/migrate-english-routes.mjs +276 -0
  118. package/scripts/ownership-conflict.mjs +5 -2
  119. package/scripts/pinning.mjs +74 -5
  120. package/scripts/plan-apply.mjs +149 -5
  121. package/scripts/reconcile.mjs +49 -11
  122. package/scripts/render-templates.mjs +97 -44
  123. package/scripts/section-config.mjs +253 -0
  124. package/scripts/starter.mjs +17 -0
  125. package/scripts/theme/color.mjs +185 -0
  126. package/scripts/theme/css-theme.mjs +233 -0
  127. package/scripts/theme/fonts.mjs +123 -0
  128. package/scripts/theme/import-export.mjs +125 -0
  129. package/scripts/theme/preset.mjs +93 -0
  130. package/scripts/theme/theme-plan.mjs +292 -0
  131. package/scripts/theme/tokens.mjs +137 -0
  132. package/scripts/view-assembly.mjs +57 -3
  133. package/scripts/view-selection.mjs +1 -1
  134. package/skills/sf-feature/SKILL.md +32 -19
  135. package/skills/sf-setup/SKILL.md +79 -0
  136. package/skills/sf-theme-gen/SKILL.md +99 -36
  137. package/skills/sf-theme-gen/references/shadcn-theming.md +87 -0
  138. package/skills/{shadcn-theming/references/templates → sf-theme-gen/references}/theme-setup.md +15 -19
  139. package/skills/{shadcn-theming → sf-theme-gen}/references/theming-guide.md +6 -11
  140. package/skills/sf-view-gen/SKILL.md +63 -40
  141. package/skills/sf-view-gen/assets/recipes/archetypes.json +33 -46
  142. package/skills/sf-view-gen/assets/recipes/catalog.json +245 -153
  143. package/skills/sf-view-gen/assets/recipes/catalog.schema.json +4 -0
  144. package/skills/sf-view-gen/assets/recipes/features.json +28 -5
  145. package/skills/sf-view-gen/assets/recipes/recipes.json +159 -59
  146. package/skills/sf-view-gen/assets/recipes/sections.json +10 -0
  147. package/skills/sf-view-gen/assets/templates/views/sections/cta.client.tsx +1 -1
  148. package/skills/sf-view-gen/assets/templates/views/sections/faq.client.tsx +1 -1
  149. package/skills/sf-view-gen/assets/templates/views/sections/logoCloud.client.tsx +1 -1
  150. package/skills/sf-view-gen/assets/templates/views/sections/pricing.client.tsx +1 -1
  151. package/skills/sf-view-gen/assets/templates/views/sections/products.client.tsx +100 -0
  152. package/skills/sf-view-gen/assets/templates/views/sections/products.tsx +19 -0
  153. package/skills/sf-view-gen/assets/templates/views/sections/schema.products.ts +39 -0
  154. package/skills/sf-view-gen/assets/templates/views/sections/statistics.client.tsx +1 -1
  155. package/skills/sf-view-gen/assets/templates/views/sections/testimonials.client.tsx +1 -1
  156. package/skills/{json-render-core/SKILL.md → sf-view-gen/references/json-render-core.md} +4 -27
  157. package/skills/{json-render-next/SKILL.md → sf-view-gen/references/json-render-next.md} +5 -8
  158. package/skills/{json-render-react/SKILL.md → sf-view-gen/references/json-render-react.md} +3 -5
  159. package/skills/{json-render-shadcn/SKILL.md → sf-view-gen/references/json-render-shadcn.md} +3 -5
  160. package/skills/sf-view-gen/references/views.md +28 -37
  161. package/skills/sf-view-gen/scripts/catalog.mjs +10 -0
  162. package/skills/sf-view-gen/scripts/validate.mjs +75 -4
  163. package/skills/storefront-workflow/SKILL.md +94 -31
  164. package/skills/{storefront-best-practices/reference/design.md → storefront-workflow/references/design-consistency.md} +13 -29
  165. package/CHANGELOG.md +0 -84
  166. package/assets/templates/views/home/assembly/slots/benefits/Feature1/binding.json +0 -5
  167. package/assets/templates/views/home/assembly/slots/benefits/Feature2/binding.json +0 -5
  168. package/assets/templates/views/home/assembly/slots/benefits/Feature2/registry.part +0 -10
  169. package/assets/templates/views/home/assembly/slots/categories/ProductCategory2/binding.json +0 -5
  170. package/assets/templates/views/home/assembly/slots/categories/ProductCategory2/catalog.part +0 -4
  171. package/assets/templates/views/home/assembly/slots/categories/ProductCategory2/registry.part +0 -16
  172. package/assets/templates/views/home/assembly/slots/hero/StorefrontHero1/binding.json +0 -5
  173. package/assets/templates/views/home/assembly/slots/hero/StorefrontHero1/catalog.part +0 -4
  174. package/assets/templates/views/home/assembly/slots/hero/StorefrontHero1/element.part +0 -5
  175. package/assets/templates/views/user-panel/index.tsx +0 -106
  176. package/assets/templates/views/user-panel/registry.tsx +0 -54
  177. package/assets/templates/views/user-panel/schema.ts +0 -79
  178. package/commands/sf-add-view.md +0 -57
  179. package/commands/sf-feature.md +0 -28
  180. package/commands/sf-theme.md +0 -26
  181. package/commands/sf-view.md +0 -67
  182. package/skills/building-storefronts/SKILL.md +0 -178
  183. package/skills/building-storefronts/references/frontend-integration.md +0 -229
  184. package/skills/json-render-remotion/SKILL.md +0 -111
  185. package/skills/json-render-solid/SKILL.md +0 -204
  186. package/skills/nextjs-shadcn/SKILL.md +0 -367
  187. package/skills/nextjs-shadcn/references/architecture.md +0 -499
  188. package/skills/nextjs-shadcn/references/project-setup.md +0 -162
  189. package/skills/nextjs-shadcn/references/shadcn-platform.md +0 -261
  190. package/skills/nextjs-shadcn/references/sidebar.md +0 -274
  191. package/skills/nextjs-shadcn/references/styling.md +0 -555
  192. package/skills/shadcn-component-discovery/SKILL.md +0 -273
  193. package/skills/shadcn-component-discovery/references/registries.md +0 -226
  194. package/skills/shadcn-theming/SKILL.md +0 -104
  195. package/skills/storefront-best-practices/SKILL.md +0 -421
  196. package/skills/storefront-best-practices/reference/components/breadcrumbs.md +0 -123
  197. package/skills/storefront-best-practices/reference/components/cart-popup.md +0 -189
  198. package/skills/storefront-best-practices/reference/components/country-selector.md +0 -298
  199. package/skills/storefront-best-practices/reference/components/footer.md +0 -112
  200. package/skills/storefront-best-practices/reference/components/hero.md +0 -241
  201. package/skills/storefront-best-practices/reference/components/megamenu.md +0 -239
  202. package/skills/storefront-best-practices/reference/components/navbar.md +0 -397
  203. package/skills/storefront-best-practices/reference/components/popups.md +0 -221
  204. package/skills/storefront-best-practices/reference/components/product-card.md +0 -125
  205. package/skills/storefront-best-practices/reference/components/product-reviews.md +0 -217
  206. package/skills/storefront-best-practices/reference/components/product-slider.md +0 -174
  207. package/skills/storefront-best-practices/reference/components/search.md +0 -101
  208. package/skills/storefront-best-practices/reference/connecting-to-backend.md +0 -391
  209. package/skills/storefront-best-practices/reference/features/promotions.md +0 -307
  210. package/skills/storefront-best-practices/reference/features/wishlist.md +0 -230
  211. package/skills/storefront-best-practices/reference/layouts/account.md +0 -380
  212. package/skills/storefront-best-practices/reference/layouts/cart.md +0 -316
  213. package/skills/storefront-best-practices/reference/layouts/checkout.md +0 -486
  214. package/skills/storefront-best-practices/reference/layouts/home-page.md +0 -264
  215. package/skills/storefront-best-practices/reference/layouts/order-confirmation.md +0 -231
  216. package/skills/storefront-best-practices/reference/layouts/product-details.md +0 -527
  217. package/skills/storefront-best-practices/reference/layouts/product-listing.md +0 -520
  218. package/skills/storefront-best-practices/reference/layouts/static-pages.md +0 -356
  219. package/skills/storefront-best-practices/reference/medusa.md +0 -307
  220. /package/assets/templates/views/home/assembly/slots/benefits/{Feature1 → cards}/catalog.part +0 -0
  221. /package/assets/templates/views/home/assembly/slots/benefits/{Feature1 → cards}/element.part +0 -0
  222. /package/assets/templates/views/home/assembly/slots/benefits/{Feature2 → split}/catalog.part +0 -0
  223. /package/assets/templates/views/home/assembly/slots/benefits/{Feature2 → split}/element.part +0 -0
  224. /package/skills/{storefront-best-practices/reference → storefront-workflow/references}/mobile-responsiveness.md +0 -0
  225. /package/skills/{storefront-best-practices/reference → storefront-workflow/references}/seo.md +0 -0
@@ -0,0 +1,128 @@
1
+ // Derived host helper: per-instance resolution for data-bound sections.
2
+ //
3
+ // A data-bound section (for example `products`) keeps its *selection* in a
4
+ // user-owned, per-instance config keyed by the section's stable id
5
+ // (`views/<view>/data.ts` -> `sectionSources`). This module is the single host
6
+ // boundary that turns that config into resolved, validated view state:
7
+ //
8
+ // * it validates each source with the canonical `sectionSourceSchema` (an
9
+ // invalid or missing source yields an `unconfigured` state, never a guess);
10
+ // * it resolves each selection through the existing canonical catalog bridge
11
+ // (`getCatalogResults`), so equal queries share request-local work, differing
12
+ // store/channel/region/currency contexts stay isolated, and unsupported
13
+ // criteria are reported rather than dropped;
14
+ // * it maps each canonical product to the shared presentation contract via the
15
+ // host mapper, so an unresolved price stays truthful instead of becoming $0;
16
+ // * it returns one discriminated state per section id, so a failing section
17
+ // never erases its siblings and a real failure is never replaced by mock data.
18
+ //
19
+ // Orphan sources (ids no longer referenced by the composition) are ignored.
20
+
21
+ import { getCatalogResults } from '@thorprovider/runtime/commerce'
22
+ import {
23
+ MERCHANDISING_SECTION_MAX_ITEMS,
24
+ sectionSourceSchema,
25
+ } from '@thorprovider/runtime/contracts'
26
+ import { PRODUCT_IMAGE_FALLBACK } from '@thorprovider/blocks/contracts'
27
+ import { isCompleteFiniteDecimal } from '@thorprovider/blocks/lib/money'
28
+ import type { ProductPresentation } from '@thorprovider/blocks/contracts'
29
+ import type { Product, StoreContext } from '@thorprovider/types'
30
+
31
+ /** Per-instance section selection config, keyed by the section's stable id. */
32
+ export type SectionSources = Record<string, unknown>
33
+
34
+ /**
35
+ * Canonical `Product` (unified provider output) → `ProductPresentation` for the
36
+ * merchandising product sections. Unlike the card mapper, this NEVER drops a
37
+ * product with an unresolved price: the canonical `Money` is passed through and
38
+ * the block renders a truthful "unavailable" state instead of inventing `$0`.
39
+ * Optional fields (image alt, rating, badge) are omitted — never `""` or a
40
+ * fabricated value — and a missing image falls back to the shared placeholder so
41
+ * no `<img>` is rendered without a `src`.
42
+ *
43
+ * This lives in the derived host helper (not the user-owned mappers module) so an
44
+ * upgraded home whose `mappers.ts` predates this capability still compiles.
45
+ */
46
+ export function toProductPresentation(product: Product): ProductPresentation {
47
+ const min = product.priceRange?.minVariantPrice
48
+ const compareAt = product.variants.find(
49
+ (variant) => variant.compareAtPrice && isCompleteFiniteDecimal(variant.compareAtPrice.amount),
50
+ )?.compareAtPrice
51
+ const image = product.featuredImage?.url || product.images[0]?.url || PRODUCT_IMAGE_FALLBACK
52
+ const imageAlt = product.featuredImage?.altText || undefined
53
+ return {
54
+ id: product.handle,
55
+ title: product.title,
56
+ image,
57
+ imageAlt,
58
+ href: `/products/${product.handle}`,
59
+ price: min ?? { amount: '', currencyCode: '' },
60
+ compareAtPrice: compareAt,
61
+ rating: undefined,
62
+ badge: undefined,
63
+ }
64
+ }
65
+
66
+ /** The resolved state the view state model carries for one data-bound section. */
67
+ export interface SectionViewState {
68
+ status:
69
+ | 'unconfigured'
70
+ | 'ready'
71
+ | 'empty'
72
+ | 'invalid-query'
73
+ | 'unsupported-query'
74
+ | 'unmounted-capability'
75
+ | 'data-error'
76
+ products: ProductPresentation[]
77
+ }
78
+
79
+ /**
80
+ * Read the optional `sectionSources` export from a user-owned data module
81
+ * without hard-importing it, so a home scaffolded before this capability (whose
82
+ * `data.ts` has no such export) still compiles and simply renders every
83
+ * data-bound section as `unconfigured`.
84
+ */
85
+ export function resolveSectionSources(module: unknown): SectionSources {
86
+ const candidate = (module as { sectionSources?: unknown } | null | undefined)?.sectionSources
87
+ return candidate && typeof candidate === 'object' ? (candidate as SectionSources) : {}
88
+ }
89
+
90
+ /**
91
+ * Resolve the state for every referenced data-bound section id. Sections resolve
92
+ * concurrently and independently; each entry is always present so the registry
93
+ * can render a truthful state for its section.
94
+ */
95
+ export async function resolveSectionViewStates(
96
+ ids: readonly string[],
97
+ sources: SectionSources,
98
+ context: StoreContext,
99
+ ): Promise<Record<string, SectionViewState>> {
100
+ const states: Record<string, SectionViewState> = {}
101
+ await Promise.all(
102
+ ids.map(async (id) => {
103
+ const parsed = sectionSourceSchema.safeParse(sources[id])
104
+ if (!parsed.success) {
105
+ states[id] = { status: 'unconfigured', products: [] }
106
+ return
107
+ }
108
+ const source = parsed.data
109
+ try {
110
+ const outcome = await getCatalogResults(source.query, context)
111
+ if (!outcome.ok) {
112
+ states[id] = { status: outcome.error.code, products: [] }
113
+ return
114
+ }
115
+ const maxItems = source.maxItems ?? MERCHANDISING_SECTION_MAX_ITEMS
116
+ const products = outcome.results.products
117
+ .slice(0, maxItems)
118
+ .map(toProductPresentation)
119
+ states[id] = { status: products.length > 0 ? 'ready' : 'empty', products }
120
+ } catch {
121
+ // A transport/provider failure is surfaced as a per-section data error,
122
+ // never as fabricated or mock products, and never discards siblings.
123
+ states[id] = { status: 'data-error', products: [] }
124
+ }
125
+ }),
126
+ )
127
+ return states
128
+ }
@@ -6,8 +6,8 @@
6
6
  //
7
7
  // Neutral defaults only: no delivery, shipping, or promo promise is made here,
8
8
  // and footer links point only at routes the generated storefront actually
9
- // serves (`/`, `/categorias`, `/checkout`, and the static pages `/contacto`,
10
- // `/sobre-nosotros`, `/terminos`, `/privacidad`). Brand colors and copy belong
9
+ // serves (`/`, `/categories`, `/checkout`, and the static pages `/contact`,
10
+ // `/about`, `/terms`, `/privacy`). Brand colors and copy belong
11
11
  // in your own content, never in the package.
12
12
  //
13
13
  // The scaffold ships no newsletter submit callback, so the footer newsletter is
@@ -67,23 +67,31 @@ export const footerClassName: string | undefined = undefined
67
67
  export const brandDescription: string =
68
68
  'Catálogo en línea de productos para tu hogar y tu negocio.'
69
69
 
70
+ /**
71
+ * Optional navbar utility-strip note (e.g. `'Nuevo horario de atención de 9 a
72
+ * 18 h'`). Empty by default: while it is empty and there are no utility links,
73
+ * the strip is not rendered, so a fresh storefront shows no note. Set a real
74
+ * note here to display it.
75
+ */
76
+ export const shippingNote: string = ''
77
+
70
78
  /** Neutral footer links — only routes the storefront serves; no dead `#` links. */
71
79
  export const linkColumns: ShellLinkColumn[] = [
72
80
  {
73
81
  title: 'Comprar',
74
82
  links: [
75
83
  { label: 'Inicio', href: '/' },
76
- { label: 'Todas las categorías', href: '/categorias' },
84
+ { label: 'Todas las categorías', href: '/categories' },
77
85
  { label: 'Finalizar compra', href: '/checkout' },
78
86
  ],
79
87
  },
80
88
  {
81
89
  title: 'Información',
82
90
  links: [
83
- { label: 'Contacto', href: '/contacto' },
84
- { label: 'Sobre nosotros', href: '/sobre-nosotros' },
85
- { label: 'Términos y condiciones', href: '/terminos' },
86
- { label: 'Política de privacidad', href: '/privacidad' },
91
+ { label: 'Contacto', href: '/contact' },
92
+ { label: 'Sobre nosotros', href: '/about' },
93
+ { label: 'Términos y condiciones', href: '/terms' },
94
+ { label: 'Política de privacidad', href: '/privacy' },
87
95
  ],
88
96
  },
89
97
  ]
@@ -94,3 +102,19 @@ export const linkColumns: ShellLinkColumn[] = [
94
102
  * renders no form — never a fake one.
95
103
  */
96
104
  export const newsletter: false | ShellNewsletter = false
105
+
106
+ // Primary destinations for the mobile bottom navigation. Only routes the
107
+ // storefront actually serves; the icons come from the shared category icon set.
108
+ export interface ShellBottomNavItem {
109
+ id?: string
110
+ label: string
111
+ href: string
112
+ icon?: string
113
+ }
114
+
115
+ export const mobileBottomNavItems: ShellBottomNavItem[] = [
116
+ { id: 'home', label: 'Inicio', href: '/', icon: 'home' },
117
+ { id: 'categories', label: 'Categorías', href: '/categories', icon: 'store' },
118
+ { id: 'cart', label: 'Carrito', href: '/cart', icon: 'boxes' },
119
+ { id: 'account', label: 'Cuenta', href: '/account', icon: 'shield' },
120
+ ]
@@ -12,11 +12,15 @@ import {
12
12
  logoAccent,
13
13
  navbarClassName,
14
14
  newsletter,
15
+ shippingNote,
15
16
  } from './content'
16
17
 
17
18
  export const navbarShellProps = {
18
19
  logoAccent,
19
20
  className: navbarClassName,
21
+ // Optional utility-strip note. Empty by default, so the strip renders only
22
+ // once a real note (or a utility link) is configured.
23
+ shippingNote,
20
24
  // Global navigation search is held until a verified backend search contract
21
25
  // exists (E2 task 5.4), so the generated storefront presents NO search
22
26
  // control. A merchant may set this to `true` to opt in once the contract is
@@ -6,6 +6,8 @@ import type { NextAppSpec } from '@json-render/next'
6
6
  import { storefrontInitialState } from '../state'
7
7
  import { views } from '../views'
8
8
  import { footerShellProps, navbarShellProps } from '../shell/props'
9
+ import { mobileBottomNavItems } from '../shell/content'
10
+ import { mountedFeatureConfigs, mountedFeatureNames } from '../composition'
9
11
  import type { StorefrontElement } from './types'
10
12
 
11
13
  export type { StorefrontElement }
@@ -34,12 +36,59 @@ const routes = Object.fromEntries(
34
36
 
35
37
  // The default layout is the storefront chrome shared by every page: the
36
38
  // system notice region sits in the notices slot (always first, above the
37
- // header), the announcement banner and navbar live in the header slot, the
38
- // footer in the footer slot, and the cart drawer is a page-level child of
39
- // Layout (rendered outside the slots so it can overlay the whole shell). This
39
+ // header), the announcement banner and navbar live in the header slot, and the
40
+ // footer in the footer slot. The cart is a lateral panel owned by the navbar
41
+ // (opened by the navbar icon or a successful add), never an inline element of
42
+ // the shell, so page content is never followed by a duplicated cart. This
40
43
  // mirrors the reference app so a fresh scaffold ships a real storefront, not a
41
44
  // bare page.
45
+ // The navigability feature contributes its chrome only when it is installed.
46
+ // `mountedFeatureNames` is the general presence seam (unfiltered by the catalog
47
+ // boundary), so a removed feature leaves no dangling skip link, back-to-top, or
48
+ // bottom navigation behind.
49
+ const hasNavigability = mountedFeatureNames.includes('navigability')
50
+ const navigabilityConfig = (mountedFeatureConfigs['navigability'] ?? {}) as {
51
+ showBackToTop?: boolean
52
+ }
53
+ const showBackToTop = navigabilityConfig.showBackToTop !== false
54
+
55
+ // Account chrome is contributed only when customer-auth is mounted. The default
56
+ // account menu is DERIVED and minimal — the account surface only, with a real
57
+ // link (no dead `#`); extra account destinations are a deferred, per-storefront
58
+ // concern. A user-owned shell may override the destination/items via
59
+ // `navbarShellProps` (spread last).
60
+ const authMounted = mountedFeatureNames.includes('customer-auth')
61
+ const DEFAULT_ACCOUNT_MENU_ITEMS = [
62
+ { label: 'Pedidos', href: '/account', icon: 'orders' as const },
63
+ ]
64
+
42
65
  const shellElements: Record<string, StorefrontElement> = {
66
+ // Navigability chrome, present only when the feature is installed. The skip
67
+ // link is the first focusable element (rendered before the notices); the
68
+ // back-to-top and mobile bottom navigation are fixed-position aids.
69
+ ...(hasNavigability
70
+ ? {
71
+ skipToContent: {
72
+ type: 'SkipToContent',
73
+ props: { targetId: 'main-content' },
74
+ },
75
+ ...(showBackToTop
76
+ ? {
77
+ backToTop: {
78
+ type: 'BackToTop',
79
+ props: { label: 'Volver arriba' },
80
+ },
81
+ }
82
+ : {}),
83
+ mobileBottomNav: {
84
+ type: 'MobileBottomNav',
85
+ props: {
86
+ items: mobileBottomNavItems,
87
+ ariaLabel: 'Navegación principal',
88
+ },
89
+ },
90
+ }
91
+ : {}),
43
92
  // Reserved top region for system/status messages. Only the shell layout
44
93
  // references it, so it renders once and always as the first element.
45
94
  notice: {
@@ -51,7 +100,7 @@ const shellElements: Record<string, StorefrontElement> = {
51
100
  props: {
52
101
  badge: 'Novedades',
53
102
  message: 'Descubre el catálogo de __SITE_NAME__.',
54
- href: '/categorias',
103
+ href: '/categories',
55
104
  linkLabel: 'Ver catálogo',
56
105
  },
57
106
  visible: { $state: '/bannerDismissed', not: true },
@@ -61,38 +110,37 @@ const shellElements: Record<string, StorefrontElement> = {
61
110
  type: 'StorefrontNavbar',
62
111
  props: {
63
112
  storeCategories: { $state: '/navCategories' },
64
- // Neutral store info: no delivery/COD/shipping promise is made by default.
65
- shippingNote: 'Catálogo en línea',
113
+ // No shipping/delivery/COD note is shipped by default; the note comes
114
+ // from the user-owned shell seam (`...navbarShellProps` below) and is
115
+ // empty unless the merchant sets one, so no placeholder strip renders.
66
116
  utilityLinks: [],
67
117
  logoText: '__SITE_NAME__',
68
118
  logoHref: '/',
119
+ // Gated account defaults, injected BEFORE the shell spread so an authored
120
+ // `accountHref`/`accountMenuItems` in the user-owned shell wins. A
121
+ // non-adopter passes neither and keeps its baseline chrome exactly.
122
+ ...(authMounted
123
+ ? { accountHref: '/account', accountMenuItems: DEFAULT_ACCOUNT_MENU_ITEMS }
124
+ : {}),
69
125
  // Optional wordmark accent and surface classes, configured in the
70
126
  // user-owned shell seam. Spread last so merchant edits win.
71
127
  ...navbarShellProps,
72
128
  },
73
129
  on: {
74
130
  openCart: { action: 'openCart' },
131
+ goToCart: { action: 'goToCart' },
75
132
  goToCheckout: { action: 'goToCheckout' },
76
133
  applyQuantityDelta: { action: 'applyQuantityDelta' },
77
134
  removeFromCart: { action: 'removeFromCart' },
78
- },
79
- },
80
- 'cart.drawer': {
81
- type: 'CartDrawer',
82
- props: {
83
- // No fabricated free-shipping threshold or reward: the backend is the only
84
- // source of shipping amounts, and a promotion promise is not supported by
85
- // the default fixture. A merchant may add promotions as customization.
86
- promotions: [],
87
- taxRate: 0.0,
88
- },
89
- visible: { $state: '/cartOpen', eq: true },
90
- on: {
91
- updateQuantity: { action: 'updateQuantity' },
92
- removeFromCart: { action: 'removeFromCart' },
93
- goToCheckout: { action: 'goToCheckout' },
94
- closeCart: { action: 'closeCart' },
95
- refreshCart: { action: 'refreshCart' },
135
+ // The account sign-out and retry reuse customer-auth's existing `logout`
136
+ // and `retryAccountSession` actions (the latter is what the account
137
+ // boundary emits too); wired only while the capability is mounted.
138
+ ...(authMounted
139
+ ? {
140
+ logout: { action: 'logout' },
141
+ retryAccountSession: { action: 'retryAccountSession' },
142
+ }
143
+ : {}),
96
144
  },
97
145
  },
98
146
  footer: {
@@ -123,8 +171,15 @@ export const __STOREFRONT_CAMEL__Spec: NextAppSpec = {
123
171
  layout: {
124
172
  type: 'Layout',
125
173
  props: {},
126
- slots: { notices: ['notice'], header: ['banner', 'navbar'], footer: ['footer'] },
127
- children: ['slot', 'cart.drawer'],
174
+ slots: {
175
+ ...(hasNavigability
176
+ ? { chrome: ['skipToContent', 'backToTop', 'mobileBottomNav'] }
177
+ : {}),
178
+ notices: ['notice'],
179
+ header: ['banner', 'navbar'],
180
+ footer: ['footer'],
181
+ },
182
+ children: ['slot'],
128
183
  },
129
184
  // The page content is injected at the Slot element by @json-render/next.
130
185
  // Without it the rendered layout drops the page and the store looks empty.
@@ -3,6 +3,12 @@
3
3
  // host files. Kept free of Next.js, React, and env imports so the logic is
4
4
  // testable at the source and the host files stay thin.
5
5
 
6
+ import type { EntitySeo } from '@thorprovider/runtime/contracts'
7
+ import {
8
+ mapCategoryEntityToSeo,
9
+ mapProductEntityToSeo,
10
+ } from '@thorprovider/runtime/contracts'
11
+
6
12
  /** The routes the storefront can serve as fixed pages (no dynamic `[` segment). */
7
13
  export function fixedRoutePaths(routes: Record<string, unknown>): string[] {
8
14
  return Object.keys(routes).filter((path) => !path.includes('['))
@@ -24,3 +30,162 @@ export function sitemapUrls(
24
30
  export function robotsSitemapUrl(siteUrl: string | undefined): string | undefined {
25
31
  return siteUrl ? new URL('/sitemap.xml', siteUrl).toString() : undefined
26
32
  }
33
+
34
+ /**
35
+ * Surfaces that are never public: they require a shopper session or hold
36
+ * checkout state and must not be indexed or listed in the sitemap.
37
+ */
38
+ export const PRIVATE_ROUTE_PREFIXES = ['/account', '/checkout'] as const
39
+
40
+ /** True when a path is (or is nested under) a private surface. */
41
+ export function isPrivatePath(path: string): boolean {
42
+ return PRIVATE_ROUTE_PREFIXES.some(
43
+ (prefix) => path === prefix || path.startsWith(`${prefix}/`),
44
+ )
45
+ }
46
+
47
+ /**
48
+ * The paths `robots.txt` disallows: the fixed private surfaces plus any private
49
+ * path the known route set declares. Public routes are never returned.
50
+ */
51
+ export function robotsDisallowPaths(routes: Record<string, unknown>): string[] {
52
+ const paths = new Set<string>(PRIVATE_ROUTE_PREFIXES)
53
+ for (const path of Object.keys(routes)) {
54
+ if (isPrivatePath(path)) paths.add(path)
55
+ }
56
+ return [...paths]
57
+ }
58
+
59
+ /**
60
+ * Per-route entity-SEO extractors keyed by the route's loader name. Each runs
61
+ * after the same request-scoped loader as the page and maps the real loaded
62
+ * entity through the pure `@thorprovider/runtime/contracts` mappers. The route
63
+ * prefix is supplied here because the runtime stays route-agnostic.
64
+ */
65
+ export const entitySeoExtractors: Record<
66
+ string,
67
+ (data: Record<string, unknown>) => EntitySeo | undefined
68
+ > = {
69
+ product: (data) =>
70
+ mapProductEntityToSeo(data.selectedProduct, { pathPrefix: '/products' }),
71
+ category: (data) =>
72
+ mapCategoryEntityToSeo(data.categoryEntity, { pathPrefix: '/categories' }),
73
+ }
74
+
75
+ /** A public catalog entity referenced by its stable id and public path. */
76
+ export interface PublicEntityRef {
77
+ id: string
78
+ path: string
79
+ }
80
+
81
+ /** One page of public entities plus the cursor for the next page, if any. */
82
+ export interface PublicEntityPage {
83
+ items: PublicEntityRef[]
84
+ nextCursor?: string
85
+ }
86
+
87
+ /** A page-fetching callback for the bounded entity enumeration. */
88
+ export type PublicEntityPageFetcher = (
89
+ cursor: string | undefined,
90
+ ) => Promise<PublicEntityPage>
91
+
92
+ /** Explicit reason an enumeration did not complete. */
93
+ export type SitemapEnumerationFailure =
94
+ | { kind: 'enumeration'; message: string }
95
+ | { kind: 'bound'; maxPages: number }
96
+ | { kind: 'cycle'; id: string }
97
+
98
+ export type SitemapEnumerationResult =
99
+ | { ok: true; entities: PublicEntityRef[] }
100
+ | { ok: false; failure: SitemapEnumerationFailure }
101
+
102
+ /** The traversal bound: an enumeration that exceeds it fails, never truncates. */
103
+ export const DEFAULT_SITEMAP_MAX_PAGES = 100
104
+
105
+ /**
106
+ * Enumerate public entities across pagination, de-duplicated by id, with a
107
+ * visited-id cycle guard and a maximum-page bound. A fetch failure, a bound hit,
108
+ * or a repeated id/cursor returns an explicit typed failure instead of an
109
+ * apparently-complete or truncated list.
110
+ */
111
+ export async function enumeratePublicEntities(
112
+ fetchPage: PublicEntityPageFetcher,
113
+ options: { maxPages?: number } = {},
114
+ ): Promise<SitemapEnumerationResult> {
115
+ const maxPages = options.maxPages ?? DEFAULT_SITEMAP_MAX_PAGES
116
+ const seenIds = new Set<string>()
117
+ const seenCursors = new Set<string>()
118
+ const entities: PublicEntityRef[] = []
119
+ let cursor: string | undefined
120
+
121
+ for (let pages = 0; ; pages += 1) {
122
+ if (pages >= maxPages) {
123
+ return { ok: false, failure: { kind: 'bound', maxPages } }
124
+ }
125
+
126
+ let page: PublicEntityPage
127
+ try {
128
+ page = await fetchPage(cursor)
129
+ } catch (error) {
130
+ return {
131
+ ok: false,
132
+ failure: {
133
+ kind: 'enumeration',
134
+ message: error instanceof Error ? error.message : String(error),
135
+ },
136
+ }
137
+ }
138
+
139
+ for (const item of page.items) {
140
+ if (seenIds.has(item.id)) {
141
+ return { ok: false, failure: { kind: 'cycle', id: item.id } }
142
+ }
143
+ seenIds.add(item.id)
144
+ entities.push(item)
145
+ }
146
+
147
+ const next = page.nextCursor
148
+ if (next === undefined || next === '') {
149
+ return { ok: true, entities }
150
+ }
151
+ if (seenCursors.has(next)) {
152
+ return { ok: false, failure: { kind: 'cycle', id: next } }
153
+ }
154
+ seenCursors.add(next)
155
+ cursor = next
156
+ }
157
+ }
158
+
159
+ /**
160
+ * Raised by `app/sitemap.ts` when enumeration fails, so the route responds with
161
+ * a non-success instead of an apparently-complete sitemap.
162
+ */
163
+ export class SitemapEnumerationError extends Error {
164
+ readonly failure: SitemapEnumerationFailure
165
+ constructor(failure: SitemapEnumerationFailure) {
166
+ super(`Sitemap enumeration failed (${failure.kind})`)
167
+ this.name = 'SitemapEnumerationError'
168
+ this.failure = failure
169
+ }
170
+ }
171
+
172
+ /**
173
+ * Combine the fixed public routes with the enumerated public entities into
174
+ * de-duplicated absolute sitemap entries. Private surfaces are never listed.
175
+ */
176
+ export function buildSitemapEntries(input: {
177
+ routes: Record<string, unknown>
178
+ siteUrl: string
179
+ entities: readonly PublicEntityRef[]
180
+ }): { url: string }[] {
181
+ const urls = new Set<string>()
182
+ for (const path of fixedRoutePaths(input.routes)) {
183
+ if (!isPrivatePath(path)) urls.add(new URL(path, input.siteUrl).toString())
184
+ }
185
+ for (const entity of input.entities) {
186
+ if (!isPrivatePath(entity.path)) {
187
+ urls.add(new URL(entity.path, input.siteUrl).toString())
188
+ }
189
+ }
190
+ return [...urls].map((url) => ({ url }))
191
+ }
@@ -8,7 +8,7 @@
8
8
  import type {
9
9
  CardProduct,
10
10
  FeaturedProduct,
11
- ProductCategory2Category,
11
+ ProductCategoryItem,
12
12
  ProductDetailProduct,
13
13
  } from '@thorprovider/blocks'
14
14
  import type { Money, PaymentMethod } from '@thorprovider/types'
@@ -165,7 +165,8 @@ export type OrderStatus = 'idle' | 'pending' | 'error' | 'unresolved' | 'complet
165
165
 
166
166
  export interface StorefrontCoreState {
167
167
  heroProducts: FeaturedProduct[]
168
- categories: ProductCategory2Category[]
168
+ categories: ProductCategoryItem[]
169
+ categoryQuery: string
169
170
  navCategories: NavCategory[]
170
171
  categoryProducts: CardProduct[]
171
172
  /** Canonical product detail: real variants, options, availability, and Money. */
@@ -229,6 +230,7 @@ export interface StorefrontState extends StorefrontCoreState {
229
230
  export const storefrontCoreState: StorefrontCoreState = {
230
231
  heroProducts: [],
231
232
  categories: [],
233
+ categoryQuery: '',
232
234
  navCategories: [],
233
235
  categoryProducts: [],
234
236
  selectedProduct: null,
@@ -9,8 +9,10 @@
9
9
  // owns the environment contract; the commerce bridge owns the backend calls.
10
10
  //
11
11
  // The values are the multitenancy seam: a future tenancy layer varies
12
- // storeId/channel/region/currency without redefining the commerce shapes. The
13
- // currency is NEVER hardcoded — it always comes from the host environment.
12
+ // storeId/channel/region/currency without redefining the commerce shapes. In
13
+ // real mode the currency is NEVER hardcoded — it comes from the host
14
+ // environment; mock mode resolves a labelled fixture context so the store runs
15
+ // with no environment configured at all.
14
16
 
15
17
  import type { StoreContext } from '@thorprovider/types'
16
18
  import { storeContextSchema } from '@thorprovider/runtime/contracts'
@@ -23,7 +25,7 @@ export const STORE_CONTEXT_ENV = {
23
25
  storeId: 'THOR_STORE_ID',
24
26
  salesChannelId: 'MEDUSA_SALES_CHANNEL_ID',
25
27
  regionId: 'MEDUSA_REGION_ID',
26
- currencyCode: 'THOR_CURRENCY_CODE',
28
+ currencyCode: 'MEDUSA_CURRENCY_CODE',
27
29
  } as const
28
30
 
29
31
  /** Real-mode backend configuration required before any provider call. */
@@ -90,6 +92,19 @@ export function getSiteUrl(): string | undefined {
90
92
  return parseSiteUrl(process.env[SITE_URL_ENV])
91
93
  }
92
94
 
95
+ /**
96
+ * 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.
100
+ */
101
+ export const MOCK_STORE_CONTEXT: StoreContext = {
102
+ storeId: 'mock-store',
103
+ salesChannelId: 'mock-sales-channel',
104
+ regionId: 'mock-region-us',
105
+ currencyCode: 'USD',
106
+ }
107
+
93
108
  function requireEnv(name: string): string {
94
109
  const value = process.env[name]
95
110
  if (typeof value !== 'string' || value.trim() === '') {
@@ -101,13 +116,17 @@ function requireEnv(name: string): string {
101
116
  }
102
117
 
103
118
  /**
104
- * Resolve and validate the single-store context from the host environment.
119
+ * Resolve and validate the single-store context.
105
120
  *
106
- * Validated through the shared runtime schema, so an invalid context is rejected
107
- * before any commerce call. Throws `StoreConfigError` naming the missing
108
- * variable — never a secret value.
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.
109
127
  */
110
128
  export function getStoreContext(): StoreContext {
129
+ if (!isRealMode()) return MOCK_STORE_CONTEXT
111
130
  const candidate = {
112
131
  storeId: requireEnv(STORE_CONTEXT_ENV.storeId),
113
132
  salesChannelId: requireEnv(STORE_CONTEXT_ENV.salesChannelId),
@@ -5,7 +5,7 @@
5
5
  // 'use client' boundary, but this fragment keeps the explicit client boundary so
6
6
  // the section composes identically in any consumer graph.
7
7
 
8
- import { CtaSection1 as CtaBlock } from '@thorprovider/blocks'
8
+ import CtaBlock from '@thorprovider/blocks/blocks/marketing/cta/cta-section-1'
9
9
  import { ctaSection1PropsSchema } from './schema.cta'
10
10
  import type { ViewRegistry } from '../types'
11
11
 
@@ -5,7 +5,7 @@
5
5
  // 'use client' boundary, but this fragment keeps the explicit client boundary so
6
6
  // the section composes identically in any consumer graph.
7
7
 
8
- import { FaqBlock1 as FaqBlock } from '@thorprovider/blocks'
8
+ import FaqBlock from '@thorprovider/blocks/blocks/marketing/faq/faq-block-1'
9
9
  import { faqPropsSchema } from './schema.faq'
10
10
  import type { ViewRegistry } from '../types'
11
11
 
@@ -8,8 +8,9 @@
8
8
  import type { ViewCatalogEntry } from '../types'
9
9
  import { ctaSection } from './cta'
10
10
  import { faqSection } from './faq'
11
+ import { productsSection } from './products'
11
12
 
12
- export const sectionModules = [faqSection, ctaSection] as const
13
+ export const sectionModules = [faqSection, ctaSection, productsSection] as const
13
14
 
14
15
  export const sectionCatalog: Record<string, ViewCatalogEntry> = Object.assign(
15
16
  {},