@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,53 @@
1
+ // Thor Commerce view: cart
2
+ // The standalone cart review route. Its data comes from the shared host cart
3
+ // state injected on every route (readCartStateForRender), so the loader only
4
+ // reports the data source — no dedicated cart fetch happens here.
5
+
6
+ import { getDataSource } from '../../store-context'
7
+ import { pageRoot } from '../../spec/page-root'
8
+ import type { StorefrontElement } from '../../spec/types'
9
+ import type { ViewModule } from '../types'
10
+ import { cartViewProps } from './props'
11
+ import { registry } from './registry'
12
+ import { cartViewPropsSchema } from './schema'
13
+
14
+ const elements: Record<string, StorefrontElement> = {
15
+ 'cart.view': {
16
+ type: 'CartView',
17
+ props: cartViewProps,
18
+ on: {
19
+ refreshCart: { action: 'refreshCart' },
20
+ updateQuantity: { action: 'updateQuantity' },
21
+ removeFromCart: { action: 'removeFromCart' },
22
+ goToCheckout: { action: 'goToCheckout' },
23
+ goHome: { action: 'goHome' },
24
+ },
25
+ },
26
+ }
27
+
28
+ const catalog = {
29
+ CartView: {
30
+ props: cartViewPropsSchema,
31
+ description: 'Standalone cart review page with backend-authoritative totals.',
32
+ },
33
+ }
34
+
35
+ export const cart: ViewModule = {
36
+ name: 'cart',
37
+ elements,
38
+ catalog,
39
+ registry,
40
+ route: {
41
+ path: '/cart',
42
+ loaderName: 'cart',
43
+ layout: 'default',
44
+ metadata: {
45
+ title: 'Carrito',
46
+ description: 'Revisa los artículos de tu carrito antes de finalizar la compra.',
47
+ },
48
+ entry: pageRoot('cart', ['cart.view'], elements),
49
+ },
50
+ loader: {
51
+ cart: async () => ({ dataSource: getDataSource(), dataError: null }),
52
+ },
53
+ }
@@ -0,0 +1,12 @@
1
+ // Thor Commerce view props: cart (user-owned)
2
+ // Element props for the cart review view. The cart lines and backend-authoritative
3
+ // totals are read from the shared host state (injected for every route), so this
4
+ // view needs no dedicated data fetch.
5
+
6
+ import { cartContent } from './content'
7
+
8
+ export const cartViewProps = {
9
+ ...cartContent,
10
+ items: { $state: '/cart' },
11
+ totals: { $state: '/cartTotals' },
12
+ }
@@ -0,0 +1,82 @@
1
+ 'use client'
2
+
3
+ // Thor Commerce view registry: cart
4
+ // Renders the standalone cart review page (page-mode ShoppingCart) from the
5
+ // shared host cart state. Quantity updates use the ABSOLUTE line quantity keyed
6
+ // by backend line id; removal uses the same line id. Checkout is only offered
7
+ // when the checkout capability is installed and the cart is ready.
8
+
9
+ import { Button } from '@thorprovider/blocks/ui/button'
10
+ import ShoppingCart from '@thorprovider/blocks/blocks/e-commerce/shopping-carts/shopping-cart'
11
+ import { isAvailableMoney } from '@thorprovider/blocks/contracts'
12
+ import { useStateStore } from '@json-render/react'
13
+ import { checkoutAvailable } from '../../composition'
14
+ import type { ViewRegistry } from '../types'
15
+ import { toCartViewItems } from './data'
16
+ import { cartViewPropsSchema } from './schema'
17
+
18
+ export const registry: ViewRegistry = {
19
+ CartView: ({ props, emit }) => {
20
+ const { state, set } = useStateStore()
21
+ const parsed = cartViewPropsSchema.parse(props)
22
+ const cart = parsed.items
23
+ const cartError = typeof state.cartError === 'string' ? state.cartError : undefined
24
+ const readError = typeof state.cartReadError === 'string' ? state.cartReadError : undefined
25
+ const isPending = state.cartPending === true
26
+ const errorLabel = cartError ?? readError
27
+ const totalsState = isPending ? 'pending' : errorLabel ? 'error' : 'idle'
28
+ // Checkout is offered only when the required backend amounts are present and
29
+ // valid: a missing/malformed subtotal, total, or line amount blocks it, while
30
+ // an undetermined shipping amount does not (AC-CART-4.4 / UC-CART-7).
31
+ const amountsValid =
32
+ cart.every((line) => isAvailableMoney(line.lineTotal)) &&
33
+ parsed.totals != null &&
34
+ isAvailableMoney(parsed.totals.subtotal) &&
35
+ isAvailableMoney(parsed.totals.total)
36
+
37
+ // A read failure with no confirmed lines is not an empty cart: surface it as
38
+ // a recoverable error rather than the empty state.
39
+ if (readError && cart.length === 0) {
40
+ return (
41
+ <section className='mx-auto max-w-3xl px-4 py-8'>
42
+ <div role='alert' className='flex flex-col items-start gap-3'>
43
+ <p className='text-destructive text-sm'>{parsed.readErrorLabel ?? readError}</p>
44
+ <Button variant='outline' size='sm' onClick={() => emit('refreshCart')}>
45
+ Reintentar
46
+ </Button>
47
+ </div>
48
+ </section>
49
+ )
50
+ }
51
+
52
+ return (
53
+ <ShoppingCart
54
+ presentation='page'
55
+ items={toCartViewItems(cart)}
56
+ promotions={[]}
57
+ totals={parsed.totals ?? undefined}
58
+ totalsState={totalsState}
59
+ totalsErrorLabel={errorLabel}
60
+ titleLabel={parsed.titleLabel}
61
+ checkoutLabel={parsed.checkoutLabel}
62
+ continueShoppingLabel={parsed.continueShoppingLabel}
63
+ emptyLabel={parsed.emptyLabel}
64
+ onRetryTotals={() => emit('refreshCart')}
65
+ onQuantityChange={(id, quantity) => {
66
+ const line = cart.find(item => item.id === id)
67
+ if (!line) return
68
+ set('/qtyUpdate', { id, merchandiseId: line.merchandiseId, quantity })
69
+ emit('updateQuantity')
70
+ }}
71
+ onRemove={id => {
72
+ set('/lastRemoved', id)
73
+ emit('removeFromCart')
74
+ }}
75
+ onCheckout={() => emit('goToCheckout')}
76
+ onContinueShopping={() => emit('goHome')}
77
+ checkoutUnavailable={!checkoutAvailable}
78
+ checkoutDisabled={isPending || Boolean(errorLabel) || cart.length === 0 || !amountsValid}
79
+ />
80
+ )
81
+ },
82
+ }
@@ -0,0 +1,52 @@
1
+ // Thor Commerce view schema fragment: cart
2
+ // Zod mirrors of the block contracts for this view — the single source for the
3
+ // catalog entry and the client-side registry parsing (json-render does not
4
+ // validate props against the catalog itself, so the registry parses here).
5
+ // Kept free of React and server imports so the Server Component module and the
6
+ // 'use client' registry can share one contract. Block zod contracts are
7
+ // mirrored, not imported: @thorprovider/blocks ships zod v3 while the scaffold
8
+ // runs zod v4 and cross-major schema assignment breaks the catalog contract.
9
+
10
+ import { z } from 'zod'
11
+
12
+ // Canonical Money: a decimal string in major units ("69.99"), never cents.
13
+ const moneySchema = z.object({
14
+ amount: z.string(),
15
+ currencyCode: z.string(),
16
+ })
17
+
18
+ // Mirrors CartLineState: `id` is the backend line-item id used for absolute
19
+ // updates and removal; `lineTotal`/`unitPrice` are the authoritative backend
20
+ // amounts. An absent image stays absent (never serialized as "").
21
+ export const cartLineSchema = z.object({
22
+ id: z.string(),
23
+ merchandiseId: z.string(),
24
+ name: z.string(),
25
+ variant: z.string().optional(),
26
+ quantity: z.number(),
27
+ lineTotal: moneySchema,
28
+ unitPrice: moneySchema.optional(),
29
+ image: z.string().optional(),
30
+ handle: z.string().optional(),
31
+ })
32
+
33
+ // Mirrors CartTotalsState: backend-authoritative totals rendered verbatim.
34
+ export const cartTotalsSchema = z.object({
35
+ subtotal: moneySchema,
36
+ discount: moneySchema.optional(),
37
+ tax: moneySchema.optional(),
38
+ shipping: moneySchema.optional(),
39
+ total: moneySchema,
40
+ })
41
+
42
+ export const cartViewPropsSchema = z.object({
43
+ items: z.array(cartLineSchema),
44
+ totals: cartTotalsSchema.nullish(),
45
+ titleLabel: z.string().optional(),
46
+ checkoutLabel: z.string().optional(),
47
+ continueShoppingLabel: z.string().optional(),
48
+ emptyLabel: z.string().optional(),
49
+ readErrorLabel: z.string().optional(),
50
+ })
51
+
52
+ export type CartViewProps = z.infer<typeof cartViewPropsSchema>
@@ -1,11 +1,12 @@
1
1
  {
2
2
  "view": "category",
3
3
  "slots": [
4
+ { "id": "category.breadcrumb", "slot": "breadcrumb", "default": "Breadcrumb" },
4
5
  { "id": "category.filter", "slot": "filter", "default": "CategoryFilter2" },
5
6
  {
6
7
  "id": "category.productCard",
7
8
  "slot": "productCard",
8
- "default": "ProductCard1",
9
+ "default": "ProductGrid",
9
10
  "nested": true
10
11
  }
11
12
  ],
@@ -24,13 +24,13 @@ import {
24
24
  mapCatalogResultsToFilterProps,
25
25
  } from '@thorprovider/runtime/commerce'
26
26
  import { getDataSource, getStoreContext, isRealMode } from '../../store-context'
27
- import { mountedFeatures, mountedFeatureConfigs } from '../../composition'
27
+ import { mountedFeatureConfigs, mountedFeatureNames, mountedFeatures } from '../../composition'
28
28
  import { pageRoot } from '../../spec/page-root'
29
29
  import type { StorefrontElement } from '../../spec/types'
30
30
  import type { ViewModule } from '../types'
31
31
  import { registry } from './registry'
32
- import { categoryFilterProps } from './props'
33
- import { categoryFilterPropsSchema } from './schema'@@SECTION_IMPORTS@@
32
+ import { categoryBreadcrumbProps, categoryFilterProps } from './props'
33
+ import { breadcrumbPropsSchema, categoryFilterPropsSchema } from './schema'@@SECTION_IMPORTS@@
34
34
 
35
35
  // The single controlled `CategoryFilter2` base listing. The search/filter
36
36
  // controls are shown only when the matching feature is installed; the base
@@ -38,6 +38,10 @@ import { categoryFilterPropsSchema } from './schema'@@SECTION_IMPORTS@@
38
38
  // and pagination.
39
39
  const hasSearch = mountedFeatures.includes('catalog-search')
40
40
  const hasFilters = mountedFeatures.includes('category-filters')
41
+ // The navigability feature contributes the entity-derived breadcrumb trail. When
42
+ // it is not installed the trail is empty and the Breadcrumb block renders
43
+ // nothing, so removal leaves no dangling navigation aid.
44
+ const hasNavigability = mountedFeatureNames.includes('navigability')
41
45
  const searchConfig = (mountedFeatureConfigs['catalog-search'] ?? {}) as { placeholder?: string }
42
46
  const filtersConfig = (mountedFeatureConfigs['category-filters'] ?? {}) as {
43
47
  filterSet?: string[]
@@ -75,15 +79,67 @@ const emptyFilterState = () => ({
75
79
  categoryFilterCategories: [],
76
80
  categoryFilterCollections: [],
77
81
  categoryFilterPriceRange: undefined,
82
+ breadcrumbItems: [] as { label: string; href?: string }[],
78
83
  })
79
84
 
85
+ /**
86
+ * The real category entity for the current route scope, resolved from the
87
+ * backend catalog. Entity SEO reads this; an unknown/absent scope yields no
88
+ * entity (no metadata or structured data is fabricated).
89
+ */
90
+ function resolveCategoryEntity(
91
+ slug: string | undefined,
92
+ catalog: Awaited<ReturnType<typeof getCatalog>>,
93
+ ): { handle: string; name: string; description?: string } | undefined {
94
+ if (!slug) return undefined
95
+ const match = catalog.categoriesRaw.find((entry) => entry.handle === slug)
96
+ if (!match) return undefined
97
+ const description =
98
+ typeof match.description === 'string' && match.description.trim() !== ''
99
+ ? match.description
100
+ : undefined
101
+ return {
102
+ handle: match.handle,
103
+ name: match.name,
104
+ ...(description !== undefined ? { description } : {}),
105
+ }
106
+ }
107
+
108
+ /**
109
+ * Entity-derived breadcrumb trail for the current category scope: Home, the
110
+ * real ancestor chain (root -> leaf), and the current category. Derived from
111
+ * the backend category hierarchy (`parentCategoryId`); no level is fabricated,
112
+ * a cycle cannot loop forever, and no trail is produced when the navigability
113
+ * feature is not installed or the scope is unknown.
114
+ */
115
+ function resolveBreadcrumbItems(
116
+ slug: string | undefined,
117
+ catalog: Awaited<ReturnType<typeof getCatalog>>,
118
+ ): { label: string; href?: string }[] {
119
+ if (!hasNavigability || !slug) return []
120
+ const byHandle = new Map(catalog.categoriesRaw.map((entry) => [entry.handle, entry]))
121
+ const byId = new Map(catalog.categoriesRaw.map((entry) => [entry.id, entry]))
122
+ const chain: { label: string; href: string }[] = []
123
+ const visited = new Set<string>()
124
+ let current = byHandle.get(slug)
125
+ while (current && !visited.has(current.handle)) {
126
+ visited.add(current.handle)
127
+ chain.unshift({ label: current.name, href: `/categories/${current.handle}` })
128
+ current = current.parentCategoryId ? byId.get(current.parentCategoryId) : undefined
129
+ }
130
+ if (chain.length === 0) return []
131
+ const leaf = chain[chain.length - 1]
132
+ // The current (leaf) item is not a link; only ancestors are navigable.
133
+ return [{ label: 'Inicio', href: '/' }, ...chain.slice(0, -1), { label: leaf.label }]
134
+ }
135
+
80
136
  export const category: ViewModule = {
81
137
  name: 'category',
82
138
  elements,
83
139
  catalog,
84
140
  registry,
85
141
  route: {
86
- path: '/categorias/[[...slug]]',
142
+ path: '/categories/[[...slug]]',
87
143
  loaderName: 'category',
88
144
  layout: 'default',
89
145
  metadata: {
@@ -144,13 +200,13 @@ export const category: ViewModule = {
144
200
  const presentation = mapCatalogResultsToFilterProps({
145
201
  query: listing.query,
146
202
  results: listing.results,
147
- // A scoped listing (`/categorias/<handle>`) must not offer the
203
+ // A scoped listing (`/categories/<handle>`) must not offer the
148
204
  // category facet: the scope already fixes the category. The root
149
205
  // catalog passes no scope and keeps it.
150
206
  ...(slug ? { categoryScope: slug } : {}),
151
207
  // Product links point at the product-detail route. The runtime stays
152
208
  // route-agnostic, so this view supplies the href builder.
153
- productHref: (handle: string) => `/productos/${handle}`,
209
+ productHref: (handle: string) => `/products/${handle}`,
154
210
  ...(categories ? { categories } : {}),
155
211
  ...(collections ? { collections } : {}),
156
212
  sortOptions,
@@ -162,6 +218,8 @@ export const category: ViewModule = {
162
218
 
163
219
  return {
164
220
  storeCategories: catalog.categories,
221
+ categoryEntity: resolveCategoryEntity(slug, catalog),
222
+ breadcrumbItems: resolveBreadcrumbItems(slug, catalog),
165
223
  dataSource: catalog.source,
166
224
  dataError: null,
167
225
  categoryFilterProducts: presentation.products,
@@ -9,12 +9,13 @@
9
9
  // the client. The search and filter controls are only present because the
10
10
  // installed manifest enabled them; the block never adds a second listing.
11
11
 
12
- import {
13
- CategoryFilter2 as CategoryFilter2Block,
14
- type CategoryFilter2ActiveFilter,
15
- type CategoryFilter2Filters,
16
- type CategoryFilter2Props,
17
- } from '@thorprovider/blocks'@@BLOCK_IMPORTS@@@@SECTION_REGISTRY_IMPORTS@@
12
+ import CategoryFilter2Block from '@thorprovider/blocks/blocks/e-commerce/category-filters/category-filter-2'
13
+ import type {
14
+ CategoryFilter2ActiveFilter,
15
+ CategoryFilter2Filters,
16
+ CategoryFilter2Props,
17
+ } from '@thorprovider/blocks/blocks/e-commerce/category-filters/category-filter-2'
18
+ @@BLOCK_IMPORTS@@@@SECTION_REGISTRY_IMPORTS@@
18
19
  import { buildCategoryQueryHref, catalogHistoryMode, type CategoryQueryChange } from '@thorprovider/runtime/commerce'
19
20
  import type { CatalogFeatureName } from '@thorprovider/runtime/contracts'
20
21
  import { useStateStore } from '@json-render/react'
@@ -0,0 +1,5 @@
1
+ {
2
+ "module": "@thorprovider/blocks/blocks/e-commerce/navigation/breadcrumb",
3
+ "import": "Breadcrumb",
4
+ "as": "BreadcrumbBlock"
5
+ }
@@ -0,0 +1,4 @@
1
+ Breadcrumb: {
2
+ props: breadcrumbPropsSchema,
3
+ description: 'Migas de pan derivadas de la jerarquía real de categorías.',
4
+ },
@@ -0,0 +1,7 @@
1
+ 'category.breadcrumb': {
2
+ type: 'Breadcrumb',
3
+ props: {
4
+ ...categoryBreadcrumbProps,
5
+ items: { $state: '/breadcrumbItems' },
6
+ },
7
+ },
@@ -0,0 +1,18 @@
1
+ Breadcrumb: ({ props }) => {
2
+ const p = props as {
3
+ items: { label: string; href?: string }[]
4
+ maxItems?: number
5
+ ariaLabel?: string
6
+ backLabel?: string
7
+ className?: string
8
+ }
9
+ return (
10
+ <BreadcrumbBlock
11
+ items={p.items}
12
+ maxItems={p.maxItems}
13
+ ariaLabel={p.ariaLabel}
14
+ backLabel={p.backLabel}
15
+ className={p.className}
16
+ />
17
+ )
18
+ },
@@ -24,13 +24,13 @@ import {
24
24
  mapCatalogResultsToFilterProps,
25
25
  } from '@thorprovider/runtime/commerce'
26
26
  import { getDataSource, getStoreContext, isRealMode } from '../../store-context'
27
- import { mountedFeatures, mountedFeatureConfigs } from '../../composition'
27
+ import { mountedFeatureConfigs, mountedFeatureNames, mountedFeatures } from '../../composition'
28
28
  import { pageRoot } from '../../spec/page-root'
29
29
  import type { StorefrontElement } from '../../spec/types'
30
30
  import type { ViewModule } from '../types'
31
31
  import { registry } from './registry'
32
- import { categoryFilterProps } from './props'
33
- import { categoryFilterPropsSchema } from './schema'
32
+ import { categoryBreadcrumbProps, categoryFilterProps } from './props'
33
+ import { breadcrumbPropsSchema, categoryFilterPropsSchema } from './schema'
34
34
 
35
35
  // The single controlled `CategoryFilter2` base listing. The search/filter
36
36
  // controls are shown only when the matching feature is installed; the base
@@ -38,6 +38,10 @@ import { categoryFilterPropsSchema } from './schema'
38
38
  // and pagination.
39
39
  const hasSearch = mountedFeatures.includes('catalog-search')
40
40
  const hasFilters = mountedFeatures.includes('category-filters')
41
+ // The navigability feature contributes the entity-derived breadcrumb trail. When
42
+ // it is not installed the trail is empty and the Breadcrumb block renders
43
+ // nothing, so removal leaves no dangling navigation aid.
44
+ const hasNavigability = mountedFeatureNames.includes('navigability')
41
45
  const searchConfig = (mountedFeatureConfigs['catalog-search'] ?? {}) as { placeholder?: string }
42
46
  const filtersConfig = (mountedFeatureConfigs['category-filters'] ?? {}) as {
43
47
  filterSet?: string[]
@@ -53,6 +57,13 @@ const SORT_LABELS: Record<string, string> = {
53
57
  }
54
58
 
55
59
  const elements: Record<string, StorefrontElement> = {
60
+ 'category.breadcrumb': {
61
+ type: 'Breadcrumb',
62
+ props: {
63
+ ...categoryBreadcrumbProps,
64
+ items: { $state: '/breadcrumbItems' },
65
+ },
66
+ },
56
67
  'category.filter': {
57
68
  type: 'CategoryFilter2',
58
69
  props: {
@@ -90,6 +101,10 @@ const elements: Record<string, StorefrontElement> = {
90
101
  }
91
102
 
92
103
  const catalog = {
104
+ Breadcrumb: {
105
+ props: breadcrumbPropsSchema,
106
+ description: 'Migas de pan derivadas de la jerarquía real de categorías.',
107
+ },
93
108
  CategoryFilter2: {
94
109
  props: categoryFilterPropsSchema,
95
110
  description:
@@ -112,22 +127,74 @@ const emptyFilterState = () => ({
112
127
  categoryFilterCategories: [],
113
128
  categoryFilterCollections: [],
114
129
  categoryFilterPriceRange: undefined,
130
+ breadcrumbItems: [] as { label: string; href?: string }[],
115
131
  })
116
132
 
133
+ /**
134
+ * The real category entity for the current route scope, resolved from the
135
+ * backend catalog. Entity SEO reads this; an unknown/absent scope yields no
136
+ * entity (no metadata or structured data is fabricated).
137
+ */
138
+ function resolveCategoryEntity(
139
+ slug: string | undefined,
140
+ catalog: Awaited<ReturnType<typeof getCatalog>>,
141
+ ): { handle: string; name: string; description?: string } | undefined {
142
+ if (!slug) return undefined
143
+ const match = catalog.categoriesRaw.find((entry) => entry.handle === slug)
144
+ if (!match) return undefined
145
+ const description =
146
+ typeof match.description === 'string' && match.description.trim() !== ''
147
+ ? match.description
148
+ : undefined
149
+ return {
150
+ handle: match.handle,
151
+ name: match.name,
152
+ ...(description !== undefined ? { description } : {}),
153
+ }
154
+ }
155
+
156
+ /**
157
+ * Entity-derived breadcrumb trail for the current category scope: Home, the
158
+ * real ancestor chain (root -> leaf), and the current category. Derived from
159
+ * the backend category hierarchy (`parentCategoryId`); no level is fabricated,
160
+ * a cycle cannot loop forever, and no trail is produced when the navigability
161
+ * feature is not installed or the scope is unknown.
162
+ */
163
+ function resolveBreadcrumbItems(
164
+ slug: string | undefined,
165
+ catalog: Awaited<ReturnType<typeof getCatalog>>,
166
+ ): { label: string; href?: string }[] {
167
+ if (!hasNavigability || !slug) return []
168
+ const byHandle = new Map(catalog.categoriesRaw.map((entry) => [entry.handle, entry]))
169
+ const byId = new Map(catalog.categoriesRaw.map((entry) => [entry.id, entry]))
170
+ const chain: { label: string; href: string }[] = []
171
+ const visited = new Set<string>()
172
+ let current = byHandle.get(slug)
173
+ while (current && !visited.has(current.handle)) {
174
+ visited.add(current.handle)
175
+ chain.unshift({ label: current.name, href: `/categories/${current.handle}` })
176
+ current = current.parentCategoryId ? byId.get(current.parentCategoryId) : undefined
177
+ }
178
+ if (chain.length === 0) return []
179
+ const leaf = chain[chain.length - 1]
180
+ // The current (leaf) item is not a link; only ancestors are navigable.
181
+ return [{ label: 'Inicio', href: '/' }, ...chain.slice(0, -1), { label: leaf.label }]
182
+ }
183
+
117
184
  export const category: ViewModule = {
118
185
  name: 'category',
119
186
  elements,
120
187
  catalog,
121
188
  registry,
122
189
  route: {
123
- path: '/categorias/[[...slug]]',
190
+ path: '/categories/[[...slug]]',
124
191
  loaderName: 'category',
125
192
  layout: 'default',
126
193
  metadata: {
127
194
  title: 'Categoría',
128
195
  description: 'Explora los productos de esta categoría en __SITE_NAME__.',
129
196
  },
130
- entry: pageRoot('category', ['category.filter'], elements),
197
+ entry: pageRoot('category', ['category.breadcrumb', 'category.filter'], elements),
131
198
  },
132
199
  loader: {
133
200
  category: async (params, searchParams) => {
@@ -181,13 +248,13 @@ export const category: ViewModule = {
181
248
  const presentation = mapCatalogResultsToFilterProps({
182
249
  query: listing.query,
183
250
  results: listing.results,
184
- // A scoped listing (`/categorias/<handle>`) must not offer the
251
+ // A scoped listing (`/categories/<handle>`) must not offer the
185
252
  // category facet: the scope already fixes the category. The root
186
253
  // catalog passes no scope and keeps it.
187
254
  ...(slug ? { categoryScope: slug } : {}),
188
255
  // Product links point at the product-detail route. The runtime stays
189
256
  // route-agnostic, so this view supplies the href builder.
190
- productHref: (handle: string) => `/productos/${handle}`,
257
+ productHref: (handle: string) => `/products/${handle}`,
191
258
  ...(categories ? { categories } : {}),
192
259
  ...(collections ? { collections } : {}),
193
260
  sortOptions,
@@ -199,6 +266,8 @@ export const category: ViewModule = {
199
266
 
200
267
  return {
201
268
  storeCategories: catalog.categories,
269
+ categoryEntity: resolveCategoryEntity(slug, catalog),
270
+ breadcrumbItems: resolveBreadcrumbItems(slug, catalog),
202
271
  dataSource: catalog.source,
203
272
  dataError: null,
204
273
  categoryFilterProducts: presentation.products,
@@ -14,3 +14,10 @@ import { filterContent } from './content'
14
14
  export const categoryFilterProps = {
15
15
  ...filterContent,
16
16
  }
17
+
18
+ // Presentational defaults for the breadcrumb; the trail itself is bound to
19
+ // `$state` from the loader (entity-derived, never invented).
20
+ export const categoryBreadcrumbProps = {
21
+ ariaLabel: 'Migas de pan',
22
+ backLabel: 'Volver',
23
+ }
@@ -9,12 +9,13 @@
9
9
  // the client. The search and filter controls are only present because the
10
10
  // installed manifest enabled them; the block never adds a second listing.
11
11
 
12
- import {
13
- CategoryFilter2 as CategoryFilter2Block,
14
- type CategoryFilter2ActiveFilter,
15
- type CategoryFilter2Filters,
16
- type CategoryFilter2Props,
17
- } from '@thorprovider/blocks'
12
+ import CategoryFilter2Block from '@thorprovider/blocks/blocks/e-commerce/category-filters/category-filter-2'
13
+ import type {
14
+ CategoryFilter2ActiveFilter,
15
+ CategoryFilter2Filters,
16
+ CategoryFilter2Props,
17
+ } from '@thorprovider/blocks/blocks/e-commerce/category-filters/category-filter-2'
18
+ import { Breadcrumb as BreadcrumbBlock } from '@thorprovider/blocks/blocks/e-commerce/navigation/breadcrumb'
18
19
  import { buildCategoryQueryHref, catalogHistoryMode, type CategoryQueryChange } from '@thorprovider/runtime/commerce'
19
20
  import type { CatalogFeatureName } from '@thorprovider/runtime/contracts'
20
21
  import { useStateStore } from '@json-render/react'
@@ -29,6 +30,24 @@ type CategoryFilter2RegistryProps = CategoryFilter2Props & {
29
30
  }
30
31
 
31
32
  export const registry: ViewRegistry = {
33
+ Breadcrumb: ({ props }) => {
34
+ const p = props as {
35
+ items: { label: string; href?: string }[]
36
+ maxItems?: number
37
+ ariaLabel?: string
38
+ backLabel?: string
39
+ className?: string
40
+ }
41
+ return (
42
+ <BreadcrumbBlock
43
+ items={p.items}
44
+ maxItems={p.maxItems}
45
+ ariaLabel={p.ariaLabel}
46
+ backLabel={p.backLabel}
47
+ className={p.className}
48
+ />
49
+ )
50
+ },
32
51
  CategoryFilter2: ({ props, emit }) => {
33
52
  const router = useRouter()
34
53
  const pathname = usePathname()
@@ -75,4 +75,17 @@ export const categoryFilterPropsSchema = z
75
75
  })
76
76
  .catchall(z.unknown())
77
77
 
78
+ export const breadcrumbItemSchema = z.object({
79
+ label: z.string(),
80
+ href: z.string().optional(),
81
+ })
82
+
83
+ export const breadcrumbPropsSchema = z.object({
84
+ items: z.array(breadcrumbItemSchema),
85
+ maxItems: z.number().int().min(2).optional(),
86
+ ariaLabel: z.string().optional(),
87
+ backLabel: z.string().optional(),
88
+ className: z.string().optional(),
89
+ })
90
+
78
91
  export type CategoryFilterProps = z.infer<typeof categoryFilterPropsSchema>
@@ -7,11 +7,9 @@
7
7
  // spec (elements/catalog/route/loader) stays a pure Server Component module.
8
8
 
9
9
  import { useEffect, useRef } from 'react'
10
- import {
11
- Button,
12
- CheckoutForm1 as CheckoutBlock,
13
- CheckoutConfirmation as CheckoutConfirmationBlock,
14
- } from '@thorprovider/blocks'
10
+ import { Button } from '@thorprovider/blocks/ui/button'
11
+ import CheckoutBlock from '@thorprovider/blocks/blocks/e-commerce/checkout-forms/checkout-form-1'
12
+ import CheckoutConfirmationBlock from '@thorprovider/blocks/blocks/e-commerce/checkout-forms/checkout-confirmation'
15
13
  import { useStateStore } from '@json-render/react'
16
14
  import { loadCheckoutAction, reconcileReceiptAction } from '../../actions'
17
15
  import type { CartStatePatch, PlaceOrderResult } from '../../commerce'