@thorprovider/storefront 0.3.1 → 0.4.0-mvp.0

package/assets/templates/views/home/index.tsx

@@ -5,115 +5,50 @@
 // on the server. Registered by importing it in ../index.ts. Recipe: recipes.json -> "home".
 
 import { getCatalog } from '@thorprovider/runtime/commerce'
-import { z } from 'zod'
+import { getDataSource } from '../../store-context'
 import { pageRoot } from '../../spec/page-root'
 import type { StorefrontElement } from '../../spec/types'
 import type { ViewModule } from '../types'
 import { registry } from './registry'
-import { toFeaturedProduct } from '../../mappers'
+import { benefitsProps, categoriesProps, heroProps } from './props'
+import { selectHeroProducts, toNavCategories } from './data'
+import { toCategoryCard, toFeaturedProduct } from '../../mappers'
+import {
+  categoryCardsPropsSchema,
+  featurePropsSchema,
+  storefrontHeroPropsSchema,
+} from './schema'
 
+// The element tree is derived wiring; the rendered props come from the
+// user-owned ./props.ts module so they survive sync and unit removal.
 const elements: Record<string, StorefrontElement> = {
   'home.hero': {
     type: 'StorefrontHero',
-    props: {
-      badge: 'Bienvenido',
-      title: '__SITE_NAME__',
-      titleAccent: 'para cada proyecto',
-      description: 'Productos seleccionados con precios justos y entrega a tu puerta.',
-      products: { $state: '/heroProducts' },
-      primaryCta: { label: 'Comprar ahora' },
-      secondaryCta: { label: 'Ver categorías' },
-    },
+    props: heroProps,
     on: { addToCart: { action: 'addToCart' }, openProduct: { action: 'openProduct' } },
   },
   'home.benefits': {
     type: 'Feature',
-    props: {
-      badge: '__SITE_NAME__',
-      title: 'Compra con confianza',
-      description: 'Beneficios pensados para que tu compra llegue segura y a tiempo.',
-      items: [
-        {
-          id: 'entrega',
-          title: 'Entrega segura',
-          description: 'Seguimiento de tu pedido hasta la puerta de tu casa.',
-          icon: 'truck',
-        },
-        {
-          id: 'pago',
-          title: 'Pago protegido',
-          description: 'Compra con confianza, múltiples opciones de pago.',
-          icon: 'shield-check',
-        },
-        {
-          id: 'soporte',
-          title: 'Soporte local',
-          description: 'Atención personalizada en todo el país.',
-          icon: 'headphones',
-        },
-      ],
-    },
+    props: benefitsProps,
   },
   'home.categories': {
     type: 'CategoryCards',
-    props: {
-      title: 'Compra por categoría',
-      description: 'Explora nuestro catálogo completo.',
-      categories: { $state: '/categories' },
-    },
+    props: categoriesProps,
     on: { openCategory: { action: 'openCategory' } },
   },
 }
 
-const ctaSchema = z.object({ label: z.string(), href: z.string().optional() })
-
-// Mirrors the StorefrontHero block contract (FeaturedProduct) so a product-shape
-// mismatch is a type error at the catalog boundary, not a runtime crash. The
-// block requires every field — including `colors` — to be defined at render.
-const featuredProductSchema = z.object({
-  id: z.string(),
-  name: z.string(),
-  brand: z.string(),
-  price: z.number(),
-  originalPrice: z.number(),
-  rating: z.number(),
-  reviewCount: z.number(),
-  inStock: z.boolean(),
-  isNew: z.boolean(),
-  isOnSale: z.boolean(),
-  image: z.string(),
-  colors: z.array(z.string()),
-})
-
 const catalog = {
   StorefrontHero: {
-    props: z.object({
-      title: z.string(),
-      description: z.string(),
-      titleAccent: z.string().optional(),
-      badge: z.string().optional(),
-      products: z.array(featuredProductSchema),
-      primaryCta: ctaSchema.optional(),
-      secondaryCta: ctaSchema.optional(),
-    }),
+    props: storefrontHeroPropsSchema,
     description: 'Landing hero.',
   },
   Feature: {
-    props: z.object({
-      items: z.array(z.record(z.string(), z.unknown())),
-      badge: z.string().optional(),
-      title: z.string().optional(),
-      description: z.string().optional(),
-    }),
+    props: featurePropsSchema,
     description: 'Benefit highlights.',
   },
   CategoryCards: {
-    props: z.object({
-      title: z.string().optional(),
-      description: z.string().optional(),
-      categories: z.array(z.record(z.string(), z.unknown())),
-      cta: ctaSchema.optional(),
-    }),
+    props: categoryCardsPropsSchema,
     description: 'Category grid.',
   },
 }
@@ -135,8 +70,27 @@ export const home: ViewModule = {
   },
   loader: {
     home: async () => {
-      const { products, categories } = await getCatalog()
-      return { heroProducts: products.slice(0, 4).map(toFeaturedProduct), categories }
+      try {
+        const { products, categories, source } = await getCatalog()
+        return {
+          heroProducts: selectHeroProducts(products).map(toFeaturedProduct),
+          categories: categories.map(toCategoryCard),
+          navCategories: toNavCategories(categories),
+          dataSource: source,
+          dataError: null,
+        }
+      } catch (error) {
+        // A real-mode failure is surfaced as a visible error, never as fictional
+        // data. Mock mode is labelled by `dataSource`.
+        return {
+          heroProducts: [],
+          categories: [],
+          navCategories: [],
+          dataSource: getDataSource(),
+          dataError:
+            error instanceof Error ? error.message : 'No se pudo cargar el catálogo.',
+        }
+      }
     },
   },
 }

package/assets/templates/views/home/props.ts

@@ -0,0 +1,22 @@
+// Thor Commerce view props: home
+// User-owned element props for the home view. Reconcile seeds this file once and
+// never rewrites it; the derived view module (./index.tsx) imports these objects
+// and binds them into the element tree, so edits here survive `storefront sync`
+// and unit removal. Plain data only: no React and no server imports.
+
+import { benefitsContent, categoriesContent, heroContent, heroImage } from './content'
+
+export const heroProps = {
+  ...heroContent,
+  products: { $state: '/heroProducts' },
+  heroImage,
+}
+
+export const benefitsProps = {
+  ...benefitsContent,
+}
+
+export const categoriesProps = {
+  ...categoriesContent,
+  categories: { $state: '/categories' },
+}

package/assets/templates/views/home/registry.tsx

@@ -5,31 +5,43 @@
 // @json-render/react and components from @thorprovider/blocks — both must stay
 // on the client side of the RSC graph. Kept separate from index.tsx so the view
 // spec (elements/catalog/route/loader) stays a pure Server Component module.
+//
+// Props arrive as untyped spec data: every entry parses them through the view's
+// schema (./schema.ts) before binding, so a contract mismatch fails loudly at
+// the boundary instead of rendering undefined fields or literal icon tags.
 
 import {
   Feature1 as FeatureBlock,
   ProductCategory2 as CategoryCardsBlock,
   StorefrontHero1 as StorefrontHeroBlock,
 } from '@thorprovider/blocks'
-import type { FeaturedProduct } from '@thorprovider/blocks'
 import { useStateStore } from '@json-render/react'
+import { resolveIcon } from '../../icon-map'
 import type { ViewRegistry } from '../types'
+import {
+  categoryCardsPropsSchema,
+  featurePropsSchema,
+  storefrontHeroPropsSchema,
+} from './schema'
 
 export const registry: ViewRegistry = {
   StorefrontHero: ({ props, emit }) => {
     const { set } = useStateStore()
+    const hero = storefrontHeroPropsSchema.parse(props)
     return (
       <StorefrontHeroBlock
-        title={props.title as string}
-        description={props.description as string}
-        products={props.products as FeaturedProduct[]}
-        titleAccent={props.titleAccent as string}
-        badge={props.badge as string}
-        primaryCta={props.primaryCta as never}
-        secondaryCta={props.secondaryCta as never}
+        title={hero.title}
+        description={hero.description}
+        products={hero.products}
+        titleAccent={hero.titleAccent}
+        badge={hero.badge}
+        primaryCta={hero.primaryCta}
+        secondaryCta={hero.secondaryCta}
+        heroImage={hero.heroImage}
         onAddToCart={(product) => {
+          // No first-variant shortcut: open the detail so a variant is chosen.
           set('/lastClicked', product)
-          emit('addToCart')
+          emit('openProduct')
         }}
         onBuyNow={(product) => {
           set('/lastClicked', product)
@@ -39,24 +51,28 @@ export const registry: ViewRegistry = {
       />
     )
   },
-  Feature: ({ props }) => (
-    <FeatureBlock
-      items={props.items as never}
-      badge={props.badge as string}
-      title={props.title as string}
-      description={props.description as string}
-    />
-  ),
+  Feature: ({ props }) => {
+    const feature = featurePropsSchema.parse(props)
+    return (
+      <FeatureBlock
+        items={feature.items.map((item) => ({ ...item, icon: resolveIcon(item.icon) }))}
+        badge={feature.badge}
+        title={feature.title}
+        description={feature.description}
+      />
+    )
+  },
   CategoryCards: ({ props, emit }) => {
     const { set } = useStateStore()
+    const cards = categoryCardsPropsSchema.parse(props)
     return (
       <CategoryCardsBlock
-        title={props.title as string}
-        description={props.description as string}
-        categories={props.categories as never}
-        cta={props.cta as never}
+        title={cards.title}
+        description={cards.description}
+        categories={cards.categories}
+        cta={cards.cta}
         onBrowse={(category) => {
-          set('/lastCategory', (category.handle as string) ?? String(category.id))
+          set('/lastCategory', category.handle ?? String(category.id))
           emit('openCategory')
         }}
       />

package/assets/templates/views/home/schema.ts

@@ -0,0 +1,93 @@
+// Thor Commerce view schema fragment: home
+// Zod mirrors of the block contracts for this view — the single source for the
+// catalog entries and the client-side registry parsing (json-render does not
+// validate props against the catalog itself, so the registry parses here).
+// Kept free of React and server imports so the Server Component module and the
+// 'use client' registry can share one contract.
+
+import { z } from 'zod'
+
+export const ctaSchema = z.object({
+  label: z.string(),
+  href: z.string().optional(),
+})
+
+// Mirrors the StorefrontHero block contract (FeaturedProduct): the block
+// requires every field — including `colors` — to be defined at render.
+export const featuredProductSchema = z.object({
+  id: z.string(),
+  name: z.string(),
+  brand: z.string(),
+  price: z.number(),
+  originalPrice: z.number(),
+  rating: z.number(),
+  reviewCount: z.number(),
+  inStock: z.boolean(),
+  isNew: z.boolean(),
+  isOnSale: z.boolean(),
+  image: z.string(),
+  colors: z.array(z.string()),
+})
+
+// Mirrors the Feature1 block contract; `icon` is a NAME here and only becomes
+// a component when the registry resolves it through the shared icon map.
+export const featureItemSchema = z.object({
+  id: z.string(),
+  title: z.string(),
+  description: z.string(),
+  icon: z.string(),
+})
+
+// Mirrors the ProductCategory2 block contract (ProductCategory2Category).
+// `itemCount` is optional: when the backend count is unknown the projection
+// omits it (the block renders no count) rather than fabricating a `0`. A real
+// `0` is preserved.
+export const categoryCardSchema = z.object({
+  id: z.string(),
+  handle: z.string().optional(),
+  name: z.string(),
+  description: z.string(),
+  itemCount: z.number().optional(),
+  image: z.string(),
+  trending: z.boolean(),
+})
+
+// Optional editorial hero image (mirrors the StorefrontHero block contract).
+// Rendered as a native `<img>` only when `src` is a non-empty string; omitted
+// entirely when absent, so a blank `src` is never emitted.
+export const heroImageSchema = z.object({
+  src: z.string(),
+  alt: z.string(),
+})
+
+export const storefrontHeroPropsSchema = z.object({
+  title: z.string(),
+  description: z.string(),
+  titleAccent: z.string().optional(),
+  badge: z.string().optional(),
+  products: z.array(featuredProductSchema),
+  primaryCta: ctaSchema.optional(),
+  secondaryCta: ctaSchema.optional(),
+  heroImage: heroImageSchema.optional(),
+})
+
+export const featurePropsSchema = z.object({
+  items: z.array(featureItemSchema),
+  badge: z.string().optional(),
+  title: z.string().optional(),
+  description: z.string().optional(),
+})
+
+export const categoryCardsPropsSchema = z.object({
+  title: z.string().optional(),
+  description: z.string().optional(),
+  categories: z.array(categoryCardSchema),
+  cta: ctaSchema.optional(),
+})
+
+export type FeaturedProduct = z.infer<typeof featuredProductSchema>
+export type FeatureItem = z.infer<typeof featureItemSchema>
+export type CategoryCard = z.infer<typeof categoryCardSchema>
+export type StorefrontHeroProps = z.infer<typeof storefrontHeroPropsSchema>
+export type FeatureProps = z.infer<typeof featurePropsSchema>
+export type CategoryCardsProps = z.infer<typeof categoryCardsPropsSchema>

package/assets/templates/views/product/content.ts

@@ -0,0 +1,25 @@
+// Thor Commerce view content: product
+// User-owned view content — the labels rendered by the product overview. No
+// reviews are seeded: reviews are rendered only when the backend supplies real
+// ones, so this file must never carry fabricated review data. Reconcile seeds
+// this file once and never rewrites it; the derived view module (./index.tsx)
+// imports it and wires it into the element tree, so your edits here survive
+// `storefront sync` and unit removal. Plain data only: no React and no server
+// imports.
+
+export const productLabels = {
+  sizesLabel: 'Variantes',
+  variantLabel: 'Variante',
+  reviewsLabel: 'Reseñas',
+  addToCartLabel: 'Agregar al carrito',
+  outOfStockLabel: 'Agotado',
+  unavailablePriceLabel: 'Precio no disponible',
+  selectVariantLabel: 'Selecciona una variante',
+  quantityLabel: 'Cantidad',
+}
+
+// Copy for the reviews region. It renders only when the backend supplies real
+// reviews (`/hasProductReviews`); the list itself is never seeded here.
+export const reviewsCopy = {
+  pageTitle: 'Opiniones de clientes',
+}

package/assets/templates/views/product/data.ts

@@ -0,0 +1,48 @@
+// Thor Commerce view data: product
+// User-owned loader shaping for the product view. Reconcile seeds this file once
+// and never rewrites it; the derived view module (./index.tsx) imports these
+// helpers and calls them from its loader, so edits here survive `storefront sync`
+// and unit removal. Pure functions only: no React and no server imports.
+
+import type { CatalogProductDetail } from '@thorprovider/runtime/commerce'
+import type { ProductDetailProduct } from '@thorprovider/blocks'
+
+/**
+ * Map the runtime's canonical product detail (real variants, options,
+ * availability, Money) to the ProductOverview1 block contract.
+ *
+ * Price availability is preserved, not collapsed: a variant whose backend price
+ * is unresolved carries `price: null` (the block treats that as unavailable and
+ * disables purchase), while a backend-resolved valid zero stays `"0"`.
+ */
+export function buildSelectedProduct(
+  detail: CatalogProductDetail | null | undefined,
+): ProductDetailProduct | null {
+  if (!detail) return null
+  return {
+    id: detail.id,
+    handle: detail.handle,
+    title: detail.title,
+    description: detail.description,
+    options: detail.options,
+    variants: detail.variants.map((variant) => ({
+      id: variant.id,
+      title: variant.title,
+      sku: variant.sku,
+      availableForSale: variant.availableForSale,
+      selectedOptions: variant.options,
+      price: variant.price.status === 'available' ? variant.price.money : null,
+      image: variant.image,
+    })),
+    images: detail.images,
+    featuredImage: detail.featuredImage,
+  }
+}
+
+/**
+ * No first-variant shortcut: nothing is selected until the shopper explicitly
+ * chooses a variant, so `onAddToCart` can never silently add the first one.
+ */
+export function initialSelectedVariantId(): string | null {
+  return null
+}

package/assets/templates/views/product/index.tsx

@@ -0,0 +1,104 @@
+// Thor Commerce view module: product
+// Server Component module: elements + catalog entries + route + loader only.
+// The client-side component mappings live in ./registry.tsx ('use client'); this
+// module imports them as data so the RSC graph never evaluates @json-render/react
+// on the server. Registered by importing it in ../index.ts. Recipe: recipes.json -> "product".
+
+import { notFound } from 'next/navigation'
+import { loadProductDetail } from '../../commerce'
+import { getDataSource } from '../../store-context'
+import { pageRoot } from '../../spec/page-root'
+import type { StorefrontElement } from '../../spec/types'
+import type { ViewModule } from '../types'
+import { registry } from './registry'
+import { productOverviewProps, productReviewsProps } from './props'
+import { buildSelectedProduct, initialSelectedVariantId } from './data'
+import { productOverviewPropsSchema, reviewsPropsSchema } from './schema'
+
+// The element tree is derived wiring; the rendered props come from the
+// user-owned ./props.ts module so they survive sync and unit removal.
+const elements: Record<string, StorefrontElement> = {
+  'product.overview': {
+    type: 'ProductOverview',
+    visible: { $state: '/selectedProduct' },
+    props: productOverviewProps,
+    on: { addToCart: { action: 'addToCart' } },
+  },
+  // Rendered only when the backend supplies real reviews; the list is never
+  // seeded, so an unsupplied review is not shown and no placeholder is invented.
+  'product.reviews': {
+    type: 'Reviews',
+    visible: { $state: '/hasProductReviews' },
+    props: productReviewsProps,
+    on: {
+      submitReview: { action: 'submitReview' },
+      toggleReviewLike: { action: 'toggleReviewLike' },
+    },
+  },
+}
+
+const catalog = {
+  ProductOverview: {
+    props: productOverviewPropsSchema,
+    description: 'Detalle de producto: galería, precio, variantes y añadir al carrito.',
+  },
+  Reviews: {
+    props: reviewsPropsSchema,
+    description: 'Opiniones de clientes con resumen de valoración.',
+  },
+}
+
+export const product: ViewModule = {
+  name: 'product',
+  elements,
+  catalog,
+  registry,
+  route: {
+    path: '/productos/[id]',
+    loaderName: 'product',
+    layout: 'default',
+    metadata: {
+      title: 'Producto',
+      description: 'Detalles del producto seleccionado.',
+    },
+    entry: pageRoot('product', ['product.overview', 'product.reviews'], elements),
+  },
+  loader: {
+    product: async (params) => {
+      const handle = Array.isArray(params.id) ? params.id[0] : params.id
+      const dataSource = getDataSource()
+
+      let result: Awaited<ReturnType<typeof loadProductDetail>>
+      try {
+        result = await loadProductDetail(String(handle))
+      } catch (error) {
+        // A real data-source failure is surfaced visibly (never demo data).
+        return {
+          selectedProduct: null,
+          selectedVariantId: null,
+          productQuantity: 1,
+          productReviews: [],
+          hasProductReviews: false,
+          dataSource,
+          dataError:
+            error instanceof Error ? error.message : 'No se pudo cargar el producto.',
+        }
+      }
+
+      // An unknown handle is a real 404 (the catch-all page renders not-found);
+      // it is never a demo product.
+      if (!result.detail) notFound()
+
+      return {
+        selectedProduct: buildSelectedProduct(result.detail),
+        // No first-variant shortcut: the shopper must select explicitly.
+        selectedVariantId: initialSelectedVariantId(),
+        productQuantity: 1,
+        productReviews: [],
+        hasProductReviews: false,
+        dataSource: result.source,
+        dataError: null,
+      }
+    },
+  },
+}

package/assets/templates/views/product/props.ts

@@ -0,0 +1,20 @@
+// Thor Commerce view props: product
+// User-owned element props for the product view. Reconcile seeds this file once
+// and never rewrites it; the derived view module (./index.tsx) imports these
+// objects and binds them into the element tree, so edits here survive
+// `storefront sync` and unit removal. Plain data only: no React and no server
+// imports.
+
+import { productLabels, reviewsCopy } from './content'
+
+export const productOverviewProps = {
+  ...productLabels,
+  product: { $state: '/selectedProduct' },
+  selectedVariantId: { $state: '/selectedVariantId' },
+  quantity: { $state: '/productQuantity' },
+}
+
+export const productReviewsProps = {
+  ...reviewsCopy,
+  reviews: { $state: '/productReviews' },
+}

package/assets/templates/views/product/registry.tsx

@@ -0,0 +1,78 @@
+'use client'
+
+// Thor Commerce view registry fragment: product
+// Client boundary for the product view. Imports value bindings from
+// @json-render/react and components from @thorprovider/blocks — both must stay
+// on the client side of the RSC graph. Kept separate from index.tsx so the view
+// spec (elements/catalog/route/loader) stays a pure Server Component module.
+
+import {
+  ProductOverview1 as ProductOverviewBlock,
+  ReviewRating1 as ReviewsBlock,
+} from '@thorprovider/blocks'
+import { isAvailableMoney } from '@thorprovider/blocks/contracts'
+import { useStateStore } from '@json-render/react'
+import type { ViewRegistry } from '../types'
+import { productOverviewPropsSchema, reviewsPropsSchema } from './schema'
+
+export const registry: ViewRegistry = {
+  ProductOverview: ({ props, emit }) => {
+    const { set } = useStateStore()
+    const parsed = productOverviewPropsSchema.parse(props)
+    return (
+      <ProductOverviewBlock
+        product={parsed.product}
+        selectedVariantId={parsed.selectedVariantId ?? null}
+        quantity={parsed.quantity}
+        sizesLabel={parsed.sizesLabel}
+        variantLabel={parsed.variantLabel}
+        reviewsLabel={parsed.reviewsLabel}
+        addToCartLabel={parsed.addToCartLabel}
+        outOfStockLabel={parsed.outOfStockLabel}
+        unavailablePriceLabel={parsed.unavailablePriceLabel}
+        selectVariantLabel={parsed.selectVariantLabel}
+        quantityLabel={parsed.quantityLabel}
+        onSelectVariant={(variantId) => {
+          set('/selectedVariantId', variantId)
+        }}
+        onQuantityChange={(quantity) => {
+          set('/productQuantity', quantity)
+        }}
+        onAddToCart={(variantId, quantity) => {
+          // Preserve the selected backend variant id and quantity the block
+          // emits — the handler must never drop them or substitute the SKU.
+          const variant = parsed.product.variants.find((candidate) => candidate.id === variantId)
+          const price = isAvailableMoney(variant?.price) ? Number(variant.price.amount) : 0
+          set('/lastAddToCart', {
+            variantId,
+            quantity,
+            name: parsed.product.title,
+            variant: variant?.title ?? '',
+            price,
+            image: variant?.image?.url ?? parsed.product.featuredImage?.url,
+          })
+          emit('addToCart')
+        }}
+        onToggleWishlist={() => {}}
+      />
+    )
+  },
+  Reviews: ({ props, emit }) => {
+    const parsed = reviewsPropsSchema.parse(props)
+    return (
+      <ReviewsBlock
+        pageTitle={parsed.pageTitle}
+        pageDescription={parsed.pageDescription}
+        reviews={parsed.reviews}
+        form={parsed.form}
+        reviewsPerPage={parsed.reviewsPerPage}
+        onToggleReviewLike={() => {
+          emit('toggleReviewLike')
+        }}
+        onSubmitReview={() => {
+          emit('submitReview')
+        }}
+      />
+    )
+  },
+}