@thorprovider/storefront 0.3.1 → 0.4.0-mvp.2

package/assets/templates/app/lib/__STOREFRONT__/views/sections/pricing.tsx

@@ -3,31 +3,49 @@
 import { PricingSection1 as PricingBlock } from '@thorprovider/blocks'
 import { z } from 'zod'
 
+// Mirrors the PricingTier/PricingSection1Props block contracts.
+const pricingTierSchema = z.object({
+  id: z.string(),
+  name: z.string(),
+  description: z.string(),
+  // Precio sin símbolo de moneda; el símbolo se pasa aparte en `currencySymbol`.
+  price: z.string(),
+  // Frecuencia de facturación, p. ej. '/mes'.
+  frequency: z.string(),
+  features: z.array(z.string()),
+  popular: z.boolean().optional(),
+})
+
+const pricingPropsSchema = z.object({
+  sectionTitle: z.string().optional(),
+  sectionLabel: z.string().optional(),
+  currencySymbol: z.string().optional(),
+  popularBadgeLabel: z.string().optional(),
+  getStartedLabel: z.string().optional(),
+  tiers: z.array(pricingTierSchema),
+})
+
 export const pricingSection = {
   elementType: 'Pricing',
   catalog: {
     Pricing: {
-      props: z.object({
-        sectionTitle: z.string().optional(),
-        sectionLabel: z.string().optional(),
-        currencySymbol: z.string().optional(),
-        popularBadgeLabel: z.string().optional(),
-        getStartedLabel: z.string().optional(),
-        tiers: z.array(z.record(z.string(), z.unknown())),
-      }),
+      props: pricingPropsSchema,
       description: 'Pricing tiers or plans.',
     },
   },
   registry: {
-    Pricing: ({ props }: { props: Record<string, unknown> }) => (
-      <PricingBlock
-        sectionTitle={(props.sectionTitle as string) ?? 'Planes y precios'}
-        sectionLabel={props.sectionLabel as string}
-        currencySymbol={props.currencySymbol as string}
-        popularBadgeLabel={(props.popularBadgeLabel as string) ?? 'Popular'}
-        getStartedLabel={(props.getStartedLabel as string) ?? 'Empezar'}
-        tiers={props.tiers as never}
-      />
-    ),
+    Pricing: ({ props }: { props: Record<string, unknown> }) => {
+      const parsed = pricingPropsSchema.parse(props)
+      return (
+        <PricingBlock
+          sectionTitle={parsed.sectionTitle ?? 'Planes y precios'}
+          sectionLabel={parsed.sectionLabel}
+          currencySymbol={parsed.currencySymbol}
+          popularBadgeLabel={parsed.popularBadgeLabel ?? 'Popular'}
+          getStartedLabel={parsed.getStartedLabel ?? 'Empezar'}
+          tiers={parsed.tiers}
+        />
+      )
+    },
   },
 }

package/assets/templates/app/lib/__STOREFRONT__/views/sections/products.client.tsx

@@ -0,0 +1,100 @@
+'use client'
+
+// Optional section fragment: products (mirrors recipes/sections.json) — client registry.
+// The matching server-side catalog lives in products.tsx. A data-bound section
+// renders one of two verified presentations (ProductCard1 grid, or the combined
+// grid-and-carousel ProductShowcase1) chosen by the resolved `variant`. The
+// selection and resolved products arrive through the view state; this boundary
+// only validates them and wires navigation/purchase callbacks.
+
+import {
+  ProductCard1 as ProductCard1Block,
+  ProductShowcase1 as ProductShowcase1Block,
+  type ProductCard1Product,
+} from '@thorprovider/blocks'
+import { useStateStore } from '@json-render/react'
+import { useSectionObservation } from '../../section-observation'
+import { productsPropsSchema, type ProductsStatus } from './schema.products'
+import type { ViewRegistry } from '../types'
+
+// Truthful, actionable messages for the non-`ready` states. A failed or
+// unconfigured section never fabricates products.
+function sectionStatusMessage(status: ProductsStatus): string {
+  switch (status) {
+    case 'unconfigured':
+      return 'Esta sección de productos aún no tiene una selección configurada.'
+    case 'empty':
+      return 'Esta selección no tiene productos disponibles por ahora.'
+    case 'invalid-query':
+      return 'La selección de productos de esta sección no es válida.'
+    case 'unsupported-query':
+      return 'Esta selección usa criterios que el catálogo no admite.'
+    case 'unmounted-capability':
+      return 'Esta selección requiere una capacidad que este catálogo no tiene montada.'
+    case 'data-error':
+      return 'No se pudieron cargar los productos de esta sección.'
+    default:
+      return ''
+  }
+}
+
+export const productsRegistry: ViewRegistry = {
+  Products: ({ props, emit }) => {
+    const { set } = useStateStore()
+    const parsed = productsPropsSchema.parse(props)
+    const { containerRef, noteProductClick } = useSectionObservation({
+      sectionId: parsed.sectionId ?? '',
+      sectionType: parsed.sectionType ?? 'products',
+      ...(parsed.variant ? { sectionVariant: parsed.variant } : {}),
+      ...(parsed.objective ? { objective: parsed.objective } : {}),
+    })
+
+    if (parsed.status !== 'ready') {
+      return (
+        <section
+          aria-label={parsed.heading ?? 'Productos'}
+          className="mx-auto w-full max-w-7xl px-4 py-12"
+        >
+          {parsed.heading ? (
+            <h2 className="mb-2 text-2xl font-semibold tracking-tight">{parsed.heading}</h2>
+          ) : null}
+          <p className="text-sm text-muted-foreground">{sectionStatusMessage(parsed.status)}</p>
+        </section>
+      )
+    }
+
+    // The detail affordance opens the product so a variant is chosen explicitly.
+    // It is also the section's observation origin (disabled by default).
+    const openProduct = (product: ProductCard1Product) => {
+      noteProductClick(product)
+      set('/lastClicked', product)
+      emit('openProduct')
+    }
+
+    // Product-card shortcut: the add affordance adds the product's first
+    // purchasable variant (resolved server-side from the product id), then opens
+    // the mini-cart. It is not the section's observation origin.
+    const addToCart = (product: ProductCard1Product) => {
+      set('/lastClicked', product)
+      emit('addClickedToCart')
+    }
+
+    const shared = {
+      products: parsed.products,
+      heading: parsed.heading,
+      description: parsed.description,
+      onAddToCart: addToCart,
+      onProductClick: openProduct,
+    }
+
+    return (
+      <div ref={containerRef}>
+        {parsed.variant === 'ProductShowcase1' ? (
+          <ProductShowcase1Block {...shared} />
+        ) : (
+          <ProductCard1Block {...shared} />
+        )}
+      </div>
+    )
+  },
+}

package/assets/templates/app/lib/__STOREFRONT__/views/sections/products.tsx

@@ -0,0 +1,19 @@
+// Optional section fragment: products (mirrors recipes/sections.json)
+// Server-side part: element type + zod catalog entry. The component mappings
+// live in products.client.tsx ('use client'). Unlike the stateless editorial
+// fragments (faq/cta), the products section is data-bound: its per-instance
+// selection is resolved by the host loader and delivered through the view state,
+// so this catalog entry describes the *resolved* props shape.
+
+import { productsPropsSchema } from './schema.products'
+
+export const productsSection = {
+  elementType: 'Products',
+  catalog: {
+    Products: {
+      props: productsPropsSchema,
+      description: 'Data-bound product presentation (grid or combined grid-and-carousel).',
+    },
+  },
+  registryModule: './products.client',
+}

package/assets/templates/app/lib/__STOREFRONT__/views/sections/schema.cta.ts

@@ -0,0 +1,19 @@
+// Optional section fragment: cta (mirrors recipes/sections.json) — shared contract.
+// Zod mirror of the Cta/CtaSection1Props block contracts, shared by the server
+// catalog (cta.tsx) and the client registry (cta.client.tsx). The React-only
+// callbacks (onPrimaryClick/onSecondaryClick) are intentionally excluded.
+
+import { z } from 'zod'
+
+export const ctaSchema = z.object({
+  label: z.string(),
+  href: z.string().optional(),
+})
+
+export const ctaSection1PropsSchema = z.object({
+  badgeText: z.string().optional(),
+  title: z.string().optional(),
+  description: z.string().optional(),
+  primaryCta: ctaSchema.optional(),
+  secondaryCta: ctaSchema.optional(),
+})

package/assets/templates/app/lib/__STOREFRONT__/views/sections/schema.faq.ts

@@ -0,0 +1,18 @@
+// Optional section fragment: faq (mirrors recipes/sections.json) — shared contract.
+// Zod mirror of the FaqItem/FaqBlock1Props block contracts, shared by the server
+// catalog (faq.tsx) and the client registry (faq.client.tsx).
+
+import { z } from 'zod'
+
+export const faqItemSchema = z.object({
+  value: z.string(),
+  question: z.string(),
+  answer: z.string(),
+})
+
+export const faqPropsSchema = z.object({
+  title: z.string().optional(),
+  description: z.string().optional(),
+  items: z.array(faqItemSchema),
+  accordionType: z.enum(['single', 'multiple']).optional(),
+})

package/assets/templates/app/lib/__STOREFRONT__/views/sections/schema.products.ts

@@ -0,0 +1,39 @@
+// Optional section fragment: products (mirrors recipes/sections.json) — shared contract.
+// Zod mirror of the resolved Products section props, shared by the server catalog
+// (products.tsx) and the client registry (products.client.tsx). The product list
+// reuses the canonical presentation contract owned by @thorprovider/blocks so the
+// section renders exactly what the host mapped from the catalog result.
+
+import { z } from 'zod'
+import { productPresentationSchema } from '@thorprovider/blocks'
+
+// The per-instance resolution status the host loader computes for a data-bound
+// section. `ready`/`empty` carry resolved products; the remaining states carry no
+// products and render an actionable, truthful message instead.
+export const productsStatusSchema = z.enum([
+  'unconfigured',
+  'ready',
+  'empty',
+  'invalid-query',
+  'unsupported-query',
+  'unmounted-capability',
+  'data-error',
+])
+
+export const productsPropsSchema = z.object({
+  sectionId: z.string().min(1).optional(),
+  sectionType: z.string().min(1).optional(),
+  variant: z.string().optional(),
+  // Defensive defaults: a missing resolved state (e.g. the view loader could not
+  // run) degrades to a truthful error instead of crashing the render.
+  status: productsStatusSchema.default('data-error'),
+  products: z.array(productPresentationSchema).default([]),
+  heading: z.string().optional(),
+  description: z.string().optional(),
+  objective: z.string().optional(),
+  ctaLabel: z.string().optional(),
+  ctaHref: z.string().optional(),
+})
+
+export type ProductsProps = z.infer<typeof productsPropsSchema>
+export type ProductsStatus = z.infer<typeof productsStatusSchema>

package/assets/templates/app/lib/__STOREFRONT__/views/sections/statistics.tsx

@@ -2,28 +2,49 @@
 
 import { Statistic1 as StatisticBlock } from '@thorprovider/blocks'
 import { z } from 'zod'
+import { resolveIcon } from '../../icon-map'
+
+// Mirrors the StatisticItem/Statistic1Props block contracts. The block expects
+// `icon` as a Lucide component; specs ship the icon NAME, resolved here.
+const statisticItemSchema = z.object({
+  id: z.string(),
+  title: z.string(),
+  value: z.string(),
+  description: z.string(),
+  progress: z.number(),
+  progressLabel: z.string(),
+  icon: z.string().optional(),
+})
+
+const statisticsPropsSchema = z.object({
+  title: z.string().optional(),
+  badge: z.string().optional(),
+  description: z.string().optional(),
+  items: z.array(statisticItemSchema),
+})
 
 export const statisticsSection = {
   elementType: 'Statistics',
   catalog: {
     Statistics: {
-      props: z.object({
-        title: z.string().optional(),
-        badge: z.string().optional(),
-        description: z.string().optional(),
-        items: z.array(z.record(z.string(), z.unknown())),
-      }),
+      props: statisticsPropsSchema,
       description: 'Key metrics or trust statistics.',
     },
   },
   registry: {
-    Statistics: ({ props }: { props: Record<string, unknown> }) => (
-      <StatisticBlock
-        badge={props.badge as string}
-        title={(props.title as string) ?? 'Números que nos respaldan'}
-        description={props.description as string}
-        items={props.items as never}
-      />
-    ),
+    Statistics: ({ props }: { props: Record<string, unknown> }) => {
+      const parsed = statisticsPropsSchema.parse(props)
+      return (
+        <StatisticBlock
+          badge={parsed.badge}
+          title={parsed.title ?? 'Números que nos respaldan'}
+          description={parsed.description}
+          items={parsed.items.map((item) => ({
+            ...item,
+            icon: resolveIcon(item.icon),
+          }))}
+        />
+      )
+    },
   },
 }

package/assets/templates/app/lib/__STOREFRONT__/views/sections/testimonials.tsx

@@ -3,26 +3,44 @@
 import { Testimonial1 as TestimonialBlock } from '@thorprovider/blocks'
 import { z } from 'zod'
 
+// Mirrors the Testimonial1Item/Testimonial1Props block contracts.
+const testimonialItemSchema = z.object({
+  id: z.string(),
+  name: z.string(),
+  role: z.string(),
+  avatar: z.string(),
+  content: z.string(),
+  rating: z.number(),
+})
+
+const testimonialsPropsSchema = z.object({
+  title: z.string().optional(),
+  prevLabel: z.string().optional(),
+  nextLabel: z.string().optional(),
+  slideAriaLabel: z.string().optional(),
+  items: z.array(testimonialItemSchema),
+})
+
 export const testimonialsSection = {
   elementType: 'Testimonials',
   catalog: {
     Testimonials: {
-      props: z.object({
-        title: z.string().optional(),
-        items: z.array(z.record(z.string(), z.unknown())),
-      }),
+      props: testimonialsPropsSchema,
       description: 'Customer testimonials or social proof.',
     },
   },
   registry: {
-    Testimonials: ({ props }: { props: Record<string, unknown> }) => (
-      <TestimonialBlock
-        title={(props.title as string) ?? 'Lo que dicen nuestros clientes'}
-        items={props.items as never}
-        prevLabel={(props.prevLabel as string) ?? 'Anterior'}
-        nextLabel={(props.nextLabel as string) ?? 'Siguiente'}
-        slideAriaLabel={(props.slideAriaLabel as string) ?? 'Testimonio'}
-      />
-    ),
+    Testimonials: ({ props }: { props: Record<string, unknown> }) => {
+      const parsed = testimonialsPropsSchema.parse(props)
+      return (
+        <TestimonialBlock
+          title={parsed.title ?? 'Lo que dicen nuestros clientes'}
+          items={parsed.items}
+          prevLabel={parsed.prevLabel ?? 'Anterior'}
+          nextLabel={parsed.nextLabel ?? 'Siguiente'}
+          slideAriaLabel={parsed.slideAriaLabel ?? 'Testimonio'}
+        />
+      )
+    },
   },
 }

package/assets/templates/app/lib/__STOREFRONT__/views/types.ts

@@ -5,7 +5,7 @@
 
 import type { ReactNode } from 'react'
 import type { BaseComponentProps } from '@json-render/react'
-import type { LoaderFn } from '@json-render/next'
+import type { StorefrontLoaderFn } from '@thorprovider/runtime/render-core/app'
 import type { ZodType } from 'zod'
 import type { StorefrontElement } from '../spec/types'
 
@@ -41,6 +41,8 @@ export interface ViewModule {
   elements: Record<string, StorefrontElement>
   catalog: Record<string, ViewCatalogEntry>
   registry: ViewRegistry
-  route: ViewRoute
-  loader: Record<string, LoaderFn>
+  // A view may contribute one route or several (a content-driven view declares
+  // one fixed route per page). The spec barrel normalises and flattens them.
+  route: ViewRoute | ViewRoute[]
+  loader: Record<string, StorefrontLoaderFn>
 }

package/assets/templates/features/checkout/handlers.ts

@@ -0,0 +1,159 @@
+'use client'
+
+// Generated by Thor Commerce storefront (feature: checkout — handlers)
+// The checkout capability's action handlers. Installed only when the feature is
+// in the manifest; the handlers composer calls this hook. Every mutation goes
+// through a Server Action; the backend stays authoritative for totals.
+
+import { useEffect } from 'react'
+import { useActions, useStateStore } from '@json-render/react'
+import { useNextApp } from '@json-render/next'
+import {
+  placeOrderAction,
+  reconcileReceiptAction,
+  selectShippingMethodAction,
+  syncCheckoutAddressAction,
+} from '../../actions'
+import type { CartStatePatch, PlaceOrderResult } from '../../commerce'
+import { recordConfirmedTransition } from '../../section-observation'
+
+// The always-required core of an address. Optional fields (province, phone,
+// postal code) are left to the runtime validator so the host does not impose a
+// stricter contract than the backend; the validator returns structured errors.
+const REQUIRED_ADDRESS_FIELDS = ['email', 'firstName', 'lastName', 'city', 'country'] as const
+
+function addressComplete(values: Record<string, unknown>): boolean {
+  return REQUIRED_ADDRESS_FIELDS.every(
+    (field) => typeof values[field] === 'string' && (values[field] as string).trim() !== '',
+  )
+}
+
+export function useCheckoutHandlers() {
+  const { get, set } = useStateStore()
+  const { navigate } = useNextApp()
+  const { registerHandler } = useActions()
+
+  useEffect(() => {
+    const applyCart = (patch: CartStatePatch) => {
+      set('/cart', patch.cart)
+      set('/cartTotals', patch.cartTotals)
+      set('/cartId', patch.cartId)
+      set('/cartQuantity', patch.cartQuantity)
+      set('/cartCompleted', patch.cartCompleted)
+      set('/cartSelectedShippingOptionId', patch.cartSelectedShippingOptionId)
+      // Rehydrate the checkout selection from the backend cart so a reload or
+      // an applyCart restores the highlighted shipping option.
+      set('/checkoutSelectedShippingOptionId', patch.cartSelectedShippingOptionId)
+      set('/cartReadError', null)
+    }
+
+    const applyResult = (result: PlaceOrderResult) => {
+      set('/checkoutPending', false)
+      if (result.status === 'order') {
+        // A confirmed, persisted order — observed only on a genuine order result
+        // (not captured funds) and only when a section origin exists.
+        recordConfirmedTransition('order_confirmed')
+        // ONE atomic write carries the order and its backend lines.
+        set('/lastReceipt', { order: result.order, lines: result.lines })
+        set('/orderStatus', 'complete')
+        set('/checkoutError', null)
+        set('/checkoutErrorKind', null)
+        set('/cartNotice', null)
+        // The active cart is cleared by the session action; mirror it in state.
+        set('/cart', [])
+        set('/cartTotals', null)
+        set('/cartId', null)
+        set('/cartQuantity', 0)
+        set('/cartCompleted', true)
+        set('/checkoutSelectedShippingOptionId', null)
+        return
+      }
+      // error | cart-error | unresolved. `orderStatus` only carries the UI
+      // states; the native discriminator is preserved in `checkoutErrorKind`.
+      // The active cart is NEVER cleared here, so a cart-with-error keeps its
+      // inputs and lines.
+      set('/orderStatus', result.status === 'cart-error' ? 'error' : result.status)
+      set('/checkoutErrorKind', result.status)
+      set('/checkoutError', result.message)
+      set(
+        '/cartNotice',
+        result.status === 'unresolved'
+          ? 'El pedido pudo haberse registrado. Usa "Reconciliar" para recuperar el comprobante; no lo reenvíes.'
+          : null,
+      )
+    }
+
+    // A rejected Server Action (network/RPC) must clear pending and surface a
+    // message; never swallow it. Only a non-secret context line is logged.
+    const onError = (scope: string) => (error: unknown) => {
+      console.error(
+        `[storefront/checkout] ${scope} failed`,
+        error instanceof Error ? error.message : error,
+      )
+      set('/checkoutPending', false)
+      set('/checkoutError', 'No se pudo completar la operación. Inténtalo de nuevo.')
+      set('/checkoutErrorKind', 'error')
+    }
+
+    const handlers: Record<string, () => void> = {
+      goToCheckout: () => {
+        // A confirmed checkout transition (the shopper started checkout).
+        recordConfirmedTransition('checkout_started')
+        set('/cartOpen', false)
+        navigate('/checkout')
+      },
+      continueShopping: () => navigate('/'),
+      placeOrder: () => {
+        set('/checkoutPending', true)
+        set('/checkoutError', null)
+        set('/cartNotice', null)
+        void placeOrderAction().then(applyResult).catch(onError('placeOrder'))
+      },
+      reconcileOrder: () => {
+        set('/checkoutPending', true)
+        set('/checkoutError', null)
+        void reconcileReceiptAction().then(applyResult).catch(onError('reconcileOrder'))
+      },
+      syncCheckoutAddress: () => {
+        const values = (get('/checkout') ?? {}) as Record<string, unknown>
+        if (!addressComplete(values)) return
+        set('/checkoutPending', true)
+        void syncCheckoutAddressAction(values)
+          .then((result) => {
+            set('/checkoutPending', false)
+            if (result.ok) {
+              applyCart(result.cart)
+              if (result.shippingOptions) set('/checkoutShippingOptions', result.shippingOptions)
+              set('/checkoutFieldErrors', result.fieldErrors ?? {})
+              set('/checkoutError', null)
+            } else {
+              set('/checkoutError', result.error)
+              set('/checkoutFieldErrors', result.fieldErrors ?? {})
+            }
+          })
+          .catch(onError('syncCheckoutAddress'))
+      },
+      selectShippingMethod: () => {
+        const methodId = get('/checkoutSelectedShippingOptionId') as string | null
+        if (!methodId) return
+        set('/checkoutPending', true)
+        void selectShippingMethodAction({ methodId })
+          .then((result) => {
+            set('/checkoutPending', false)
+            if (result.ok) {
+              applyCart(result.cart)
+              set('/checkoutError', null)
+            } else {
+              set('/checkoutError', result.error)
+            }
+          })
+          .catch(onError('selectShippingMethod'))
+      },
+    }
+
+    for (const [name, handler] of Object.entries(handlers)) {
+      registerHandler(name, handler)
+    }
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [])
+}

package/assets/templates/features/checkout/state.ts

@@ -0,0 +1,61 @@
+// Generated by Thor Commerce storefront (feature: checkout — state slice)
+// The checkout capability's state. Installed only when the feature is in the
+// manifest; the state composer spreads it over the core state.
+
+import type {
+  CheckoutFieldErrors,
+  CheckoutFormData,
+  CheckoutShippingOption,
+  OrderStatus,
+  StorefrontReceipt,
+} from '../../state.core'
+import type { PaymentMethod } from '@thorprovider/types'
+
+const checkoutFormDefaults: CheckoutFormData = {
+  email: '',
+  firstName: '',
+  lastName: '',
+  phone: '',
+  address: '',
+  city: '',
+  state: '',
+  zipCode: '',
+  country: '',
+  paymentMethod: '',
+  cardNumber: '',
+  expiryDate: '',
+  cvv: '',
+  cardName: '',
+  saveInfo: false,
+  sameAsBilling: false,
+  newsletter: false,
+  promoCode: '',
+}
+
+export interface CheckoutState {
+  checkout: CheckoutFormData
+  checkoutCountries: { value: string; label: string }[]
+  checkoutPaymentMethods: PaymentMethod[]
+  checkoutShippingOptions: CheckoutShippingOption[]
+  checkoutSelectedShippingOptionId: string | null
+  checkoutFieldErrors: CheckoutFieldErrors
+  checkoutPending: boolean
+  checkoutError: string | null
+  checkoutErrorKind: 'error' | 'cart-error' | 'unresolved' | null
+  lastReceipt: StorefrontReceipt | null
+  orderStatus: OrderStatus
+}
+
+export const checkoutState: CheckoutState = {
+  checkout: checkoutFormDefaults,
+  checkoutCountries: [],
+  checkoutPaymentMethods: [],
+  checkoutShippingOptions: [],
+  checkoutSelectedShippingOptionId: null,
+  checkoutFieldErrors: {},
+  checkoutPending: false,
+  checkoutError: null,
+  checkoutErrorKind: null,
+  lastReceipt: null,
+  orderStatus: 'idle',
+}