@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
@@ -12,25 +12,33 @@ export const ctaSchema = z.object({
12
12
  href: z.string().optional(),
13
13
  })
14
14
 
15
- // Mirrors the StorefrontHero block contract (FeaturedProduct): the block
16
- // requires every field — including `colors` — to be defined at render.
15
+ // Mirrors the canonical StorefrontHero block contract (FeaturedProduct,
16
+ // @thorprovider/blocks). Every popularity, review, or availability field is
17
+ // host-supplied evidence: omitted fields render nothing (honest omission)
18
+ // instead of fabricated defaults.
17
19
  export const featuredProductSchema = z.object({
18
20
  id: z.string(),
19
21
  name: z.string(),
20
- brand: z.string(),
21
22
  price: z.number(),
22
- originalPrice: z.number(),
23
- rating: z.number(),
24
- reviewCount: z.number(),
25
- inStock: z.boolean(),
26
- isNew: z.boolean(),
27
- isOnSale: z.boolean(),
28
- image: z.string(),
29
- colors: z.array(z.string()),
23
+ // Real compare-at price. Discount treatments render only from a real
24
+ // `originalPrice > price` pair — never fabricated when the backend lacks one.
25
+ originalPrice: z.number().optional(),
26
+ image: z.string().optional(),
27
+ imageAlt: z.string().optional(),
28
+ brand: z.string().optional(),
29
+ colors: z.array(z.string()).optional(),
30
+ rating: z.number().optional(),
31
+ reviewCount: z.number().optional(),
32
+ inStock: z.boolean().optional(),
33
+ isNew: z.boolean().optional(),
34
+ tag: z.string().optional(),
30
35
  })
31
36
 
32
- // Mirrors the Feature1 block contract; `icon` is a NAME here and only becomes
33
- // a component when the registry resolves it through the shared icon map.
37
+ // Mirrors the canonical Feature block contract (@thorprovider/blocks
38
+ // featurePropsSchema); `icon` is a NAME here and only becomes a component when
39
+ // the registry resolves it through the shared icon map. The presentation
40
+ // selects the bounded cards/split surface; CTA/learn-more are cards-only
41
+ // labels, the image a split-only column.
34
42
  export const featureItemSchema = z.object({
35
43
  id: z.string(),
36
44
  title: z.string(),
@@ -38,18 +46,22 @@ export const featureItemSchema = z.object({
38
46
  icon: z.string(),
39
47
  })
40
48
 
41
- // Mirrors the ProductCategory2 block contract (ProductCategory2Category).
42
- // `itemCount` is optional: when the backend count is unknown the projection
43
- // omits it (the block renders no count) rather than fabricating a `0`. A real
44
- // `0` is preserved.
49
+ // Mirrors the canonical category item contract (@thorprovider/blocks
50
+ // productCategoryItemSchema). `itemCount` is optional: when the backend count is
51
+ // unknown the projection omits it (the block renders no count) rather than
52
+ // fabricating a `0`; a real `0` is preserved. `icon` is a serializable icon-key
53
+ // resolved by the block; `subcategories`/`featured` feed the `list` reading.
45
54
  export const categoryCardSchema = z.object({
46
55
  id: z.string(),
47
56
  handle: z.string().optional(),
48
57
  name: z.string(),
49
- description: z.string(),
58
+ description: z.string().optional(),
50
59
  itemCount: z.number().optional(),
51
- image: z.string(),
52
- trending: z.boolean(),
60
+ image: z.string().optional(),
61
+ trending: z.boolean().optional(),
62
+ icon: z.string().optional(),
63
+ subcategories: z.array(z.string()).optional(),
64
+ featured: z.boolean().optional(),
53
65
  })
54
66
 
55
67
  // Optional editorial hero image (mirrors the StorefrontHero block contract).
@@ -60,34 +72,139 @@ export const heroImageSchema = z.object({
60
72
  alt: z.string(),
61
73
  })
62
74
 
75
+ // Mirrors the canonical StorefrontHero block contract
76
+ // (storefrontHeroPropsSchema, @thorprovider/blocks). The bounded presentation
77
+ // option reuses the registry's archetype intent vocabulary. Callbacks are
78
+ // consumer bindings, not serializable props, so they are bound in registry.tsx
79
+ // and deliberately absent here.
80
+ export const heroDepartmentSchema = z.object({
81
+ id: z.string(),
82
+ name: z.string(),
83
+ image: z.string().optional(),
84
+ imageAlt: z.string().optional(),
85
+ count: z.string().optional(),
86
+ href: z.string().optional(),
87
+ })
88
+
89
+ export const heroFeaturedDealSchema = z.object({
90
+ id: z.string(),
91
+ name: z.string(),
92
+ description: z.string().optional(),
93
+ image: z.string().optional(),
94
+ imageAlt: z.string().optional(),
95
+ price: z.number(),
96
+ originalPrice: z.number().optional(),
97
+ cta: ctaSchema.optional(),
98
+ })
99
+
100
+ export const heroStoreLocatorSchema = z.object({
101
+ title: z.string(),
102
+ description: z.string(),
103
+ ctaLabel: z.string(),
104
+ ctaHref: z.string().optional(),
105
+ })
106
+
107
+ export const heroDealSchema = z.object({
108
+ id: z.string(),
109
+ title: z.string(),
110
+ discount: z.string().optional(),
111
+ endTime: z.string().optional(),
112
+ })
113
+
114
+ export const heroCategorySchema = z.object({
115
+ id: z.string(),
116
+ name: z.string(),
117
+ image: z.string().optional(),
118
+ imageAlt: z.string().optional(),
119
+ count: z.string().optional(),
120
+ href: z.string().optional(),
121
+ })
122
+
63
123
  export const storefrontHeroPropsSchema = z.object({
64
124
  title: z.string(),
65
125
  description: z.string(),
66
- titleAccent: z.string().optional(),
126
+ presentation: z.enum(['compact', 'showcase', 'editorial', 'promotional']).optional(),
127
+ currency: z.string().optional(),
67
128
  badge: z.string().optional(),
129
+ titleAccent: z.string().optional(),
68
130
  products: z.array(featuredProductSchema),
69
131
  primaryCta: ctaSchema.optional(),
70
132
  secondaryCta: ctaSchema.optional(),
71
133
  heroImage: heroImageSchema.optional(),
134
+ departments: z.array(heroDepartmentSchema).optional(),
135
+ featuredDeals: z.array(heroFeaturedDealSchema).optional(),
136
+ storeLocator: heroStoreLocatorSchema.optional(),
137
+ shippingInfo: z.string().optional(),
138
+ deals: z.array(heroDealSchema).optional(),
139
+ categories: z.array(heroCategorySchema).optional(),
140
+ rotationInterval: z.number().optional(),
72
141
  })
73
142
 
74
- export const featurePropsSchema = z.object({
143
+ export const featureCardsSpecSchema = z.object({
75
144
  items: z.array(featureItemSchema),
145
+ presentation: z.literal('cards').optional(),
76
146
  badge: z.string().optional(),
77
147
  title: z.string().optional(),
78
148
  description: z.string().optional(),
149
+ ctaLabel: z.string().optional(),
150
+ learnMoreLabel: z.string().optional(),
79
151
  })
80
152
 
81
- export const categoryCardsPropsSchema = z.object({
153
+ export const featureSplitSpecSchema = z.object({
154
+ items: z.array(featureItemSchema),
155
+ presentation: z.literal('split'),
82
156
  title: z.string().optional(),
83
157
  description: z.string().optional(),
158
+ image: z.object({ src: z.string().trim().min(1), alt: z.string() }),
159
+ })
160
+
161
+ export const featurePropsSchema = z.union([featureSplitSpecSchema, featureCardsSpecSchema])
162
+
163
+ export const categoryCardPropsSchema = z.object({
164
+ category: categoryCardSchema,
165
+ presentation: z.enum(['grid', 'icons', 'list']).optional(),
166
+ browseLabel: z.string().optional(),
167
+ itemsLabel: z.string().optional(),
168
+ trendingLabel: z.string().optional(),
169
+ featuredLabel: z.string().optional(),
170
+ imageFallback: z.string().optional(),
171
+ })
172
+
173
+ export const categoryGridPropsSchema = z.object({
174
+ title: z.string().optional(),
175
+ description: z.string().optional(),
176
+ badge: z.string().optional(),
177
+ presentation: z.enum(['grid', 'icons', 'list']).optional(),
84
178
  categories: z.array(categoryCardSchema),
85
179
  cta: ctaSchema.optional(),
180
+ query: z.string().optional(),
181
+ searchPlaceholder: z.string().optional(),
182
+ searchLabel: z.string().optional(),
183
+ emptyLabel: z.string().optional(),
184
+ noResultsLabel: z.string().optional(),
185
+ browseLabel: z.string().optional(),
186
+ viewAllLabel: z.string().optional(),
187
+ trendingLabel: z.string().optional(),
188
+ featuredLabel: z.string().optional(),
189
+ itemsLabel: z.string().optional(),
190
+ imageFallback: z.string().optional(),
191
+ className: z.string().optional(),
192
+ maxItems: z.number().int().positive().optional(),
193
+ loading: z.boolean().optional(),
194
+ skeletonCount: z.number().int().positive().optional(),
86
195
  })
87
196
 
88
197
  export type FeaturedProduct = z.infer<typeof featuredProductSchema>
89
198
  export type FeatureItem = z.infer<typeof featureItemSchema>
90
199
  export type CategoryCard = z.infer<typeof categoryCardSchema>
200
+ export type HeroDepartment = z.infer<typeof heroDepartmentSchema>
201
+ export type HeroFeaturedDeal = z.infer<typeof heroFeaturedDealSchema>
202
+ export type HeroStoreLocator = z.infer<typeof heroStoreLocatorSchema>
203
+ export type HeroDeal = z.infer<typeof heroDealSchema>
204
+ export type HeroCategory = z.infer<typeof heroCategorySchema>
91
205
  export type StorefrontHeroProps = z.infer<typeof storefrontHeroPropsSchema>
92
206
  export type FeatureProps = z.infer<typeof featurePropsSchema>
93
- export type CategoryCardsProps = z.infer<typeof categoryCardsPropsSchema>
207
+ export type FeatureCardsSpecProps = z.infer<typeof featureCardsSpecSchema>
208
+ export type FeatureSplitSpecProps = z.infer<typeof featureSplitSpecSchema>
209
+ export type CategoryCardProps = z.infer<typeof categoryCardPropsSchema>
210
+ export type CategoryGridProps = z.infer<typeof categoryGridPropsSchema>
@@ -9,7 +9,7 @@ import type { ProductDetailProduct } from '@thorprovider/blocks'
9
9
 
10
10
  /**
11
11
  * Map the runtime's canonical product detail (real variants, options,
12
- * availability, Money) to the ProductOverview1 block contract.
12
+ * availability, Money) to the canonical ProductOverview block contract.
13
13
  *
14
14
  * Price availability is preserved, not collapsed: a variant whose backend price
15
15
  * is unresolved carries `price: null` (the block treats that as unavailable and
@@ -40,8 +40,10 @@ export function buildSelectedProduct(
40
40
  }
41
41
 
42
42
  /**
43
- * No first-variant shortcut: nothing is selected until the shopper explicitly
44
- * chooses a variant, so `onAddToCart` can never silently add the first one.
43
+ * No first-variant shortcut on the product detail surface: nothing is selected
44
+ * until the shopper explicitly chooses a variant, so the detail's `onAddToCart`
45
+ * can never silently add the first one. Listing cards use the separate
46
+ * first-purchasable-variant shortcut instead.
45
47
  */
46
48
  export function initialSelectedVariantId(): string | null {
47
49
  return null
@@ -7,17 +7,29 @@
7
7
  import { notFound } from 'next/navigation'
8
8
  import { loadProductDetail } from '../../commerce'
9
9
  import { getDataSource } from '../../store-context'
10
+ import { mountedFeatureNames } from '../../composition'
10
11
  import { pageRoot } from '../../spec/page-root'
11
12
  import type { StorefrontElement } from '../../spec/types'
12
13
  import type { ViewModule } from '../types'
13
14
  import { registry } from './registry'
14
- import { productOverviewProps, productReviewsProps } from './props'
15
+ import { productBreadcrumbProps, productOverviewProps, productReviewsProps } from './props'
15
16
  import { buildSelectedProduct, initialSelectedVariantId } from './data'
16
- import { productOverviewPropsSchema, reviewsPropsSchema } from './schema'
17
+ import { breadcrumbPropsSchema, productOverviewPropsSchema, reviewsPropsSchema } from './schema'
17
18
 
18
19
  // The element tree is derived wiring; the rendered props come from the
19
20
  // user-owned ./props.ts module so they survive sync and unit removal.
20
21
  const elements: Record<string, StorefrontElement> = {
22
+ // The navigability feature contributes the entity-derived breadcrumb trail.
23
+ // The element is always wired; the loader returns an empty trail when the
24
+ // feature is not installed or the backend supplies no category, so the block
25
+ // renders nothing and removal leaves no dangling navigation aid.
26
+ 'product.breadcrumb': {
27
+ type: 'Breadcrumb',
28
+ props: {
29
+ ...productBreadcrumbProps,
30
+ items: { $state: '/breadcrumbItems' },
31
+ },
32
+ },
21
33
  'product.overview': {
22
34
  type: 'ProductOverview',
23
35
  visible: { $state: '/selectedProduct' },
@@ -38,6 +50,10 @@ const elements: Record<string, StorefrontElement> = {
38
50
  }
39
51
 
40
52
  const catalog = {
53
+ Breadcrumb: {
54
+ props: breadcrumbPropsSchema,
55
+ description: 'Migas de pan derivadas de la jerarquía real de categorías del producto.',
56
+ },
41
57
  ProductOverview: {
42
58
  props: productOverviewPropsSchema,
43
59
  description: 'Detalle de producto: galería, precio, variantes y añadir al carrito.',
@@ -48,20 +64,42 @@ const catalog = {
48
64
  },
49
65
  }
50
66
 
67
+ const hasNavigability = mountedFeatureNames.includes('navigability')
68
+
69
+ // Entity-derived trail only: the product's real ancestor categories. When the
70
+ // feature is absent or the backend supplies no category, the trail is empty and
71
+ // the Breadcrumb block renders nothing (no level is ever invented).
72
+ function resolveProductBreadcrumbItems(
73
+ title: string,
74
+ categoryPath: { handle: string; name: string }[] | undefined,
75
+ ): { label: string; href?: string }[] {
76
+ if (!hasNavigability || !categoryPath || categoryPath.length === 0) return []
77
+ const chain = categoryPath.map((entry) => ({
78
+ label: entry.name,
79
+ href: `/categories/${entry.handle}`,
80
+ }))
81
+ // Home > ancestor categories (links) > the product itself (current page).
82
+ return [{ label: 'Inicio', href: '/' }, ...chain, { label: title }]
83
+ }
84
+
51
85
  export const product: ViewModule = {
52
86
  name: 'product',
53
87
  elements,
54
88
  catalog,
55
89
  registry,
56
90
  route: {
57
- path: '/productos/[id]',
91
+ path: '/products/[id]',
58
92
  loaderName: 'product',
59
93
  layout: 'default',
60
94
  metadata: {
61
95
  title: 'Producto',
62
96
  description: 'Detalles del producto seleccionado.',
63
97
  },
64
- entry: pageRoot('product', ['product.overview', 'product.reviews'], elements),
98
+ entry: pageRoot(
99
+ 'product',
100
+ ['product.breadcrumb', 'product.overview', 'product.reviews'],
101
+ elements,
102
+ ),
65
103
  },
66
104
  loader: {
67
105
  product: async (params) => {
@@ -79,6 +117,7 @@ export const product: ViewModule = {
79
117
  productQuantity: 1,
80
118
  productReviews: [],
81
119
  hasProductReviews: false,
120
+ breadcrumbItems: [],
82
121
  dataSource,
83
122
  dataError:
84
123
  error instanceof Error ? error.message : 'No se pudo cargar el producto.',
@@ -91,11 +130,16 @@ export const product: ViewModule = {
91
130
 
92
131
  return {
93
132
  selectedProduct: buildSelectedProduct(result.detail),
94
- // No first-variant shortcut: the shopper must select explicitly.
133
+ // No first-variant shortcut on the detail surface: the shopper must
134
+ // select explicitly (listing cards use the card shortcut instead).
95
135
  selectedVariantId: initialSelectedVariantId(),
96
136
  productQuantity: 1,
97
137
  productReviews: [],
98
138
  hasProductReviews: false,
139
+ breadcrumbItems: resolveProductBreadcrumbItems(
140
+ result.detail.title,
141
+ result.detail.categoryPath,
142
+ ),
99
143
  dataSource: result.source,
100
144
  dataError: null,
101
145
  }
@@ -18,3 +18,10 @@ export const productReviewsProps = {
18
18
  ...reviewsCopy,
19
19
  reviews: { $state: '/productReviews' },
20
20
  }
21
+
22
+ // Presentational defaults only; the entity-derived trail is bound to
23
+ // `$state: '/productBreadcrumbItems'` in the element tree, never invented here.
24
+ export const productBreadcrumbProps = {
25
+ ariaLabel: 'Migas de pan',
26
+ backLabel: 'Volver',
27
+ }
@@ -6,24 +6,54 @@
6
6
  // on the client side of the RSC graph. Kept separate from index.tsx so the view
7
7
  // spec (elements/catalog/route/loader) stays a pure Server Component module.
8
8
 
9
- import {
10
- ProductOverview1 as ProductOverviewBlock,
11
- ReviewRating1 as ReviewsBlock,
12
- } from '@thorprovider/blocks'
9
+ import { Breadcrumb as BreadcrumbBlock } from '@thorprovider/blocks/blocks/e-commerce/navigation/breadcrumb'
10
+ import ProductOverviewBlock from '@thorprovider/blocks/blocks/e-commerce/product-overview/product-overview'
11
+ import ReviewsBlock from '@thorprovider/blocks/blocks/e-commerce/reviews/review-rating-1'
13
12
  import { isAvailableMoney } from '@thorprovider/blocks/contracts'
14
13
  import { useStateStore } from '@json-render/react'
14
+ import { useProductVisitObservation } from '../../section-observation'
15
15
  import type { ViewRegistry } from '../types'
16
16
  import { productOverviewPropsSchema, reviewsPropsSchema } from './schema'
17
17
 
18
18
  export const registry: ViewRegistry = {
19
+ Breadcrumb: ({ props }) => {
20
+ const p = props as {
21
+ items: { label: string; href?: string }[]
22
+ maxItems?: number
23
+ ariaLabel?: string
24
+ backLabel?: string
25
+ className?: string
26
+ }
27
+ return (
28
+ <BreadcrumbBlock
29
+ items={p.items}
30
+ maxItems={p.maxItems}
31
+ ariaLabel={p.ariaLabel}
32
+ backLabel={p.backLabel}
33
+ className={p.className}
34
+ />
35
+ )
36
+ },
19
37
  ProductOverview: ({ props, emit }) => {
20
38
  const { set } = useStateStore()
21
39
  const parsed = productOverviewPropsSchema.parse(props)
40
+ // A successfully rendered product destination: recorded only when it matches
41
+ // the section origin (disabled by default; never attributes a guess). The
42
+ // stable public identity is the handle, which is what section clicks record.
43
+ const productHandle = parsed.product.handle ?? parsed.product.id
44
+ useProductVisitObservation(productHandle, `/products/${productHandle}`)
22
45
  return (
23
46
  <ProductOverviewBlock
24
47
  product={parsed.product}
48
+ presentation={parsed.presentation}
25
49
  selectedVariantId={parsed.selectedVariantId ?? null}
26
50
  quantity={parsed.quantity}
51
+ rating={parsed.rating}
52
+ deliveryEstimate={parsed.deliveryEstimate}
53
+ shipping={parsed.shipping}
54
+ specifications={parsed.specifications}
55
+ features={parsed.features}
56
+ reviews={parsed.reviews}
27
57
  sizesLabel={parsed.sizesLabel}
28
58
  variantLabel={parsed.variantLabel}
29
59
  reviewsLabel={parsed.reviewsLabel}
@@ -53,7 +83,6 @@ export const registry: ViewRegistry = {
53
83
  })
54
84
  emit('addToCart')
55
85
  }}
56
- onToggleWishlist={() => {}}
57
86
  />
58
87
  )
59
88
  },
@@ -41,7 +41,7 @@ const productDetailVariantSchema = z.object({
41
41
  image: imageSchema.optional(),
42
42
  })
43
43
 
44
- // Mirrors ProductDetailProduct (the ProductOverview1 block contract).
44
+ // Mirrors ProductDetailProduct (the canonical ProductOverview block contract).
45
45
  export const productDetailProductSchema = z.object({
46
46
  id: z.string(),
47
47
  handle: z.string().optional(),
@@ -54,10 +54,27 @@ export const productDetailProductSchema = z.object({
54
54
  featuredImage: imageSchema.optional(),
55
55
  })
56
56
 
57
+ // Mirrors the canonical ProductOverview review item (rich presentation only).
58
+ export const productOverviewReviewSchema = z.object({
59
+ id: z.number(),
60
+ author: z.string(),
61
+ rating: z.number(),
62
+ comment: z.string(),
63
+ date: z.string(),
64
+ helpful: z.number().optional(),
65
+ })
66
+
57
67
  export const productOverviewPropsSchema = z.object({
58
68
  product: productDetailProductSchema,
69
+ presentation: z.enum(['standard', 'gallery', 'rich']).optional(),
59
70
  selectedVariantId: z.string().nullable().optional(),
60
71
  quantity: z.number().optional(),
72
+ rating: z.object({ value: z.number(), count: z.number() }).optional(),
73
+ deliveryEstimate: z.string().optional(),
74
+ shipping: moneySchema.optional(),
75
+ specifications: z.record(z.string(), z.string()).optional(),
76
+ features: z.array(z.string()).optional(),
77
+ reviews: z.array(productOverviewReviewSchema).optional(),
61
78
  sizesLabel: z.string().optional(),
62
79
  variantLabel: z.string().optional(),
63
80
  reviewsLabel: z.string().optional(),
@@ -66,6 +83,24 @@ export const productOverviewPropsSchema = z.object({
66
83
  unavailablePriceLabel: z.string().optional(),
67
84
  selectVariantLabel: z.string().optional(),
68
85
  quantityLabel: z.string().optional(),
86
+ deliveryEstimateLabel: z.string().optional(),
87
+ shippingLabel: z.string().optional(),
88
+ badgeLabel: z.string().optional(),
89
+ availabilityLabel: z.string().optional(),
90
+ skuLabel: z.string().optional(),
91
+ overviewLabel: z.string().optional(),
92
+ specsLabel: z.string().optional(),
93
+ featuresLabel: z.string().optional(),
94
+ specificationsLabel: z.string().optional(),
95
+ galleryLabel: z.string().optional(),
96
+ photosLabel: z.string().optional(),
97
+ saveLabel: z.string().optional(),
98
+ savedLabel: z.string().optional(),
99
+ shareLabel: z.string().optional(),
100
+ basedOnReviewsLabel: z.string().optional(),
101
+ foundHelpfulLabel: z.string().optional(),
102
+ ofCounterLabel: z.string().optional(),
103
+ freeDeliveryLabel: z.string().optional(),
69
104
  })
70
105
 
71
106
  // Mirrors ReviewRating1Review (real reviews only; never seeded).
@@ -101,6 +136,19 @@ export const reviewsPropsSchema = z.object({
101
136
  reviewsPerPage: z.number().optional(),
102
137
  })
103
138
 
139
+ export const breadcrumbItemSchema = z.object({
140
+ label: z.string(),
141
+ href: z.string().optional(),
142
+ })
143
+
144
+ export const breadcrumbPropsSchema = z.object({
145
+ items: z.array(breadcrumbItemSchema),
146
+ maxItems: z.number().int().min(2).optional(),
147
+ ariaLabel: z.string().optional(),
148
+ backLabel: z.string().optional(),
149
+ className: z.string().optional(),
150
+ })
151
+
104
152
  export type ProductDetailProductSpec = z.infer<typeof productDetailProductSchema>
105
153
  export type ProductOverviewProps = z.infer<typeof productOverviewPropsSchema>
106
154
  export type Review = z.infer<typeof reviewSchema>
@@ -13,7 +13,7 @@ import type { StaticPageContent } from './schema'
13
13
 
14
14
  export const staticPagesContent: StaticPageContent[] = [
15
15
  {
16
- path: '/contacto',
16
+ path: '/contact',
17
17
  title: 'Contacto',
18
18
  description: 'Cómo comunicarte con la tienda.',
19
19
  sections: [
@@ -33,7 +33,7 @@ export const staticPagesContent: StaticPageContent[] = [
33
33
  ],
34
34
  },
35
35
  {
36
- path: '/terminos',
36
+ path: '/terms',
37
37
  title: 'Términos y condiciones',
38
38
  description: 'Condiciones de uso de la tienda en línea.',
39
39
  sections: [
@@ -57,7 +57,7 @@ export const staticPagesContent: StaticPageContent[] = [
57
57
  ],
58
58
  },
59
59
  {
60
- path: '/privacidad',
60
+ path: '/privacy',
61
61
  title: 'Política de privacidad',
62
62
  description: 'Cómo se tratan los datos en la tienda en línea.',
63
63
  sections: [
@@ -81,7 +81,7 @@ export const staticPagesContent: StaticPageContent[] = [
81
81
  ],
82
82
  },
83
83
  {
84
- path: '/sobre-nosotros',
84
+ path: '/about',
85
85
  title: 'Sobre nosotros',
86
86
  description: 'Información sobre la tienda.',
87
87
  sections: [
@@ -33,7 +33,7 @@ const catalog = {
33
33
  },
34
34
  }
35
35
 
36
- // A stable, unique root id per page: `/contacto` -> `static-contacto`,
36
+ // A stable, unique root id per page: `/contact` -> `static-contact`,
37
37
  // `/` -> `static-index`.
38
38
  const pageRootId = (path: string): string =>
39
39
  `static-${path.replace(/^\//, '').replace(/\//g, '-') || 'index'}`