@thorprovider/storefront 0.3.1 → 0.4.0-mvp.0

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

@@ -0,0 +1,229 @@
+// Thor Commerce view schema fragment: checkout
+// 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. Block zod contracts are
+// mirrored, not imported: @thorprovider/blocks ships zod v3 while the scaffold
+// runs zod v4 and cross-major schema assignment breaks the catalog contract.
+
+import { z } from 'zod'
+
+// Canonical Money: a decimal string in major units, never cents.
+const moneySchema = z.object({
+  amount: z.string(),
+  currencyCode: z.string(),
+})
+
+// Mirrors the CheckoutForm1FormData block contract. Card fields stay in the
+// shape (the block requires every key) but are never collected at launch.
+export const checkoutFormDataSchema = z.object({
+  email: z.string(),
+  firstName: z.string(),
+  lastName: z.string(),
+  phone: z.string(),
+  address: z.string(),
+  city: z.string(),
+  state: z.string(),
+  zipCode: z.string(),
+  country: z.string(),
+  paymentMethod: z.string(),
+  cardNumber: z.string(),
+  expiryDate: z.string(),
+  cvv: z.string(),
+  cardName: z.string(),
+  saveInfo: z.boolean(),
+  sameAsBilling: z.boolean(),
+  newsletter: z.boolean(),
+  promoCode: z.string(),
+})
+
+// Mirrors CheckoutForm1OrderSummaryItem: backend line total preferred, legacy
+// numeric price accepted only as a fallback; optional image omitted when absent.
+export const orderSummaryItemSchema = z.object({
+  id: z.union([z.string(), z.number()]),
+  name: z.string(),
+  variant: z.string().optional(),
+  quantity: z.number(),
+  lineTotal: moneySchema.optional(),
+  price: z.number().optional(),
+  image: z.string().optional(),
+})
+
+// Mirrors CheckoutForm1Totals (backend-authoritative).
+export const checkoutTotalsSchema = z.object({
+  subtotal: moneySchema,
+  discount: moneySchema.optional(),
+  tax: moneySchema.optional(),
+  shipping: moneySchema.optional(),
+  total: moneySchema,
+})
+
+export const orderSummarySchema = z.object({
+  items: z.array(orderSummaryItemSchema),
+  totals: checkoutTotalsSchema.optional(),
+  shipping: z.number().optional(),
+  tax: z.number().optional(),
+  discount: z.number().optional(),
+  promoDiscount: z.number().optional(),
+})
+
+export const countryOptionSchema = z.object({
+  value: z.string(),
+  label: z.string(),
+})
+
+// Mirrors CheckoutForm1ShippingOption (backend shipping method id).
+export const shippingOptionSchema = z.object({
+  id: z.string(),
+  name: z.string(),
+  price: moneySchema.optional(),
+  description: z.string().optional(),
+  estimatedDays: z.string().optional(),
+})
+
+// Mirrors CheckoutFieldErrors: per-field structured messages.
+export const checkoutFieldErrorsSchema = z.record(
+  z.string(),
+  z.array(z.object({ message: z.string().optional() })),
+)
+
+// Mirrors the PaymentMethod contract from @thorprovider/types.
+export const paymentMethodSchema = z.object({
+  id: z.string(),
+  name: z.string(),
+  type: z.enum([
+    'card',
+    'wallet',
+    'bank_transfer',
+    'buy_now_pay_later',
+    'cash_on_delivery',
+    'crypto',
+    'other',
+  ]),
+  isEnabled: z.boolean(),
+  requiresSetup: z.boolean(),
+  description: z.string().optional(),
+  metadata: z.record(z.string(), z.unknown()).optional(),
+  features: z
+    .object({
+      saveForLater: z.boolean().optional(),
+      installmentPayment: z.boolean().optional(),
+      recurring: z.boolean().optional(),
+    })
+    .optional(),
+})
+
+export const checkoutPropsSchema = z.object({
+  title: z.string().optional(),
+  description: z.string().optional(),
+  orderSummary: orderSummarySchema.optional(),
+  countries: z.array(countryOptionSchema).optional(),
+  shippingOptions: z.array(shippingOptionSchema).optional(),
+  // Nullable: the state initializes to `null` and the block prop is optional.
+  selectedShippingOptionId: z.string().nullable().optional(),
+  paymentMethods: z.array(paymentMethodSchema).optional(),
+  values: checkoutFormDataSchema,
+  fieldErrors: checkoutFieldErrorsSchema.optional(),
+  fieldDescriptions: z.record(z.string(), z.string()).optional(),
+})
+
+// The empty-cart surface has no props; declared so the catalog is complete.
+export const checkoutEmptyPropsSchema = z.object({})
+
+export const fulfilmentStageSchema = z.enum(['Confirmed', 'Packed', 'Shipped', 'Delivered'])
+
+const orderAddressSchema = z.object({
+  name: z.string(),
+  lines: z.array(z.string()),
+  method: z.string().optional(),
+})
+
+const orderTotalsSchema = z.object({
+  subtotal: moneySchema.optional(),
+  discount: moneySchema.optional(),
+  shipping: moneySchema.optional(),
+  tax: moneySchema.optional(),
+  total: moneySchema.optional(),
+})
+
+// Mirrors the CheckoutConfirmation Order block contract: backend Money totals,
+// optional fields rendered only when the backend supplies them (no fabricated
+// estimate or stage).
+export const storefrontOrderSchema = z.object({
+  number: z.string(),
+  placedAt: z.string(),
+  email: z.string().optional(),
+  currentStage: fulfilmentStageSchema.optional(),
+  estimatedDelivery: z.string().nullable().optional(),
+  trackingHref: z.string().optional(),
+  shipping: orderAddressSchema.optional(),
+  billing: orderAddressSchema.optional(),
+  totals: orderTotalsSchema,
+})
+
+export const orderLineSchema = z.object({
+  id: z.string(),
+  name: z.string(),
+  variant: z.string().optional(),
+  quantity: z.number(),
+  lineTotal: moneySchema,
+  unitPrice: moneySchema.optional(),
+  image: z.string().optional(),
+})
+
+export const fulfilmentStageDetailSchema = z.object({
+  stage: fulfilmentStageSchema,
+  summary: z.string(),
+  location: z.string(),
+  at: z.string().nullable(),
+})
+
+// The atomic receipt: the order and its backend lines arrive together.
+export const receiptSchema = z.object({
+  order: storefrontOrderSchema,
+  lines: z.array(orderLineSchema),
+})
+
+// Mirrors the CheckoutConfirmation props, including every neutral label the
+// host forwards. Labels are declared here so `z.object` does not strip them;
+// the registry forwards them to the block instead of relying on its defaults.
+export const checkoutConfirmationPropsSchema = z.object({
+  receipt: receiptSchema,
+  fulfilmentDetails: z.record(z.string(), fulfilmentStageDetailSchema).optional(),
+  titleLabel: z.string().optional(),
+  orderPlacedLabel: z.string().optional(),
+  orderPlacedNoEmailLabel: z.string().optional(),
+  itemsLabel: z.string().optional(),
+  quantityLabel: z.string().optional(),
+  subtotalLabel: z.string().optional(),
+  discountLabel: z.string().optional(),
+  shippingLabel: z.string().optional(),
+  taxLabel: z.string().optional(),
+  totalLabel: z.string().optional(),
+  freeLabel: z.string().optional(),
+  amountUnavailableLabel: z.string().optional(),
+  shippingAddressLabel: z.string().optional(),
+  billingAddressLabel: z.string().optional(),
+  continueShoppingLabel: z.string().optional(),
+  contactSupportLabel: z.string().optional(),
+  supportLabel: z.string().optional(),
+  progressLabel: z.string().optional(),
+  estimatedDeliveryLabel: z.string().optional(),
+  currentStageLabel: z.string().optional(),
+  inProgressLabel: z.string().optional(),
+  expectedByLabel: z.string().optional(),
+  completedLabel: z.string().optional(),
+  statusLabel: z.string().optional(),
+  locationLabel: z.string().optional(),
+  trackOrderLabel: z.string().optional(),
+  continueShoppingHref: z.string().optional(),
+  supportHref: z.string().optional(),
+})
+
+export type CheckoutFormData = z.infer<typeof checkoutFormDataSchema>
+export type OrderSummary = z.infer<typeof orderSummarySchema>
+export type CheckoutProps = z.infer<typeof checkoutPropsSchema>
+export type StorefrontOrder = z.infer<typeof storefrontOrderSchema>
+export type OrderLine = z.infer<typeof orderLineSchema>
+export type CheckoutConfirmationProps = z.infer<typeof checkoutConfirmationPropsSchema>

package/assets/templates/views/home/assembly/assembly.json

@@ -0,0 +1,24 @@
+{
+  "view": "home",
+  "slots": [
+    { "id": "home.hero", "slot": "hero", "default": "StorefrontHero1" },
+    { "id": "home.benefits", "slot": "benefits", "default": "Feature1" },
+    { "id": "home.categories", "slot": "categories", "default": "ProductCategory2" }
+  ],
+  "sections": {
+    "faq": {
+      "elementType": "Faq",
+      "registryModule": "../sections/faq.client",
+      "registryExport": "faqRegistry",
+      "propsModule": "./content",
+      "defaultProps": "{ items: [] }"
+    },
+    "cta": {
+      "elementType": "Cta",
+      "registryModule": "../sections/cta.client",
+      "registryExport": "ctaRegistry",
+      "propsModule": "./content",
+      "defaultProps": "{}"
+    }
+  }
+}

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

@@ -0,0 +1,72 @@
+// Thor Commerce view module: home
+// 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 -> "home".
+
+import { getCatalog } from '@thorprovider/runtime/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 { benefitsProps, categoriesProps, heroProps } from './props'
+import { selectHeroProducts, toNavCategories } from './data'
+import { toCategoryCard, toFeaturedProduct } from '../../mappers'
+import {
+  categoryCardsPropsSchema,
+  featurePropsSchema,
+  storefrontHeroPropsSchema,
+} from './schema'@@SECTION_IMPORTS@@
+
+// 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> = {
+@@ELEMENTS@@
+}
+
+const catalog = {
+@@CATALOG@@
+}
+
+export const home: ViewModule = {
+  name: 'home',
+  elements,
+  catalog,
+  registry,
+  route: {
+    path: '/',
+    loaderName: 'home',
+    layout: 'default',
+    metadata: {
+      title: 'Inicio',
+      description: 'Descubre los productos de __SITE_NAME__.',
+    },
+    entry: pageRoot('home', [@@SLOT_IDS@@], elements),
+  },
+  loader: {
+    home: async () => {
+      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/assembly/registry.skeleton.tsx

@@ -0,0 +1,25 @@
+'use client'
+
+// Thor Commerce view registry fragment: home
+// Client boundary for the home 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.
+//
+// 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.
+
+@@BLOCK_IMPORTS@@@@SECTION_REGISTRY_IMPORTS@@
+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 = {
+@@REGISTRY@@
+}

package/assets/templates/views/home/assembly/slots/benefits/Feature1/binding.json

@@ -0,0 +1,5 @@
+{
+  "module": "@thorprovider/blocks",
+  "import": "Feature1",
+  "as": "FeatureBlock"
+}

package/assets/templates/views/home/assembly/slots/benefits/Feature1/catalog.part

@@ -0,0 +1,4 @@
+  Feature: {
+    props: featurePropsSchema,
+    description: 'Benefit highlights.',
+  },

package/assets/templates/views/home/assembly/slots/benefits/Feature1/element.part

@@ -0,0 +1,4 @@
+  'home.benefits': {
+    type: 'Feature',
+    props: benefitsProps,
+  },

package/assets/templates/views/home/assembly/slots/benefits/Feature1/registry.part

@@ -0,0 +1,11 @@
+  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}
+      />
+    )
+  },

package/assets/templates/views/home/assembly/slots/benefits/Feature2/binding.json

@@ -0,0 +1,5 @@
+{
+  "module": "@thorprovider/blocks",
+  "import": "Feature2",
+  "as": "FeatureBlock"
+}

package/assets/templates/views/home/assembly/slots/benefits/Feature2/catalog.part

@@ -0,0 +1,4 @@
+  Feature: {
+    props: featurePropsSchema,
+    description: 'Benefit highlights.',
+  },

package/assets/templates/views/home/assembly/slots/benefits/Feature2/element.part

@@ -0,0 +1,4 @@
+  'home.benefits': {
+    type: 'Feature',
+    props: benefitsProps,
+  },

package/assets/templates/views/home/assembly/slots/benefits/Feature2/registry.part

@@ -0,0 +1,10 @@
+  Feature: ({ props }) => {
+    const feature = featurePropsSchema.parse(props)
+    return (
+      <FeatureBlock
+        items={feature.items.map((item) => ({ ...item, icon: resolveIcon(item.icon) }))}
+        title={feature.title}
+        description={feature.description}
+      />
+    )
+  },

package/assets/templates/views/home/assembly/slots/categories/ProductCategory2/binding.json

@@ -0,0 +1,5 @@
+{
+  "module": "@thorprovider/blocks",
+  "import": "ProductCategory2",
+  "as": "CategoryCardsBlock"
+}

package/assets/templates/views/home/assembly/slots/categories/ProductCategory2/catalog.part

@@ -0,0 +1,4 @@
+  CategoryCards: {
+    props: categoryCardsPropsSchema,
+    description: 'Category grid.',
+  },

package/assets/templates/views/home/assembly/slots/categories/ProductCategory2/element.part

@@ -0,0 +1,5 @@
+  'home.categories': {
+    type: 'CategoryCards',
+    props: categoriesProps,
+    on: { openCategory: { action: 'openCategory' } },
+  },

package/assets/templates/views/home/assembly/slots/categories/ProductCategory2/registry.part

@@ -0,0 +1,16 @@
+  CategoryCards: ({ props, emit }) => {
+    const { set } = useStateStore()
+    const cards = categoryCardsPropsSchema.parse(props)
+    return (
+      <CategoryCardsBlock
+        title={cards.title}
+        description={cards.description}
+        categories={cards.categories}
+        cta={cards.cta}
+        onBrowse={(category) => {
+          set('/lastCategory', category.handle ?? String(category.id))
+          emit('openCategory')
+        }}
+      />
+    )
+  },

package/assets/templates/views/home/assembly/slots/hero/StorefrontHero1/binding.json

@@ -0,0 +1,5 @@
+{
+  "module": "@thorprovider/blocks",
+  "import": "StorefrontHero1",
+  "as": "StorefrontHeroBlock"
+}

package/assets/templates/views/home/assembly/slots/hero/StorefrontHero1/catalog.part

@@ -0,0 +1,4 @@
+  StorefrontHero: {
+    props: storefrontHeroPropsSchema,
+    description: 'Landing hero.',
+  },

package/assets/templates/views/home/assembly/slots/hero/StorefrontHero1/element.part

@@ -0,0 +1,5 @@
+  'home.hero': {
+    type: 'StorefrontHero',
+    props: heroProps,
+    on: { addToCart: { action: 'addToCart' }, openProduct: { action: 'openProduct' } },
+  },

package/assets/templates/views/home/assembly/slots/hero/StorefrontHero1/registry.part

@@ -0,0 +1,26 @@
+  StorefrontHero: ({ props, emit }) => {
+    const { set } = useStateStore()
+    const hero = storefrontHeroPropsSchema.parse(props)
+    return (
+      <StorefrontHeroBlock
+        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('openProduct')
+        }}
+        onBuyNow={(product) => {
+          set('/lastClicked', product)
+          emit('openProduct')
+        }}
+        onSelectColor={() => {}}
+      />
+    )
+  },

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

@@ -0,0 +1,70 @@
+// Thor Commerce view content: home
+// User-owned view content — the copy, CTA labels, and feature items rendered by
+// this view. 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 interface HeroImageContent {
+  src: string
+  alt: string
+}
+
+/**
+ * Optional editorial hero image. Leave `undefined` to render no image; never
+ * set a blank `src`. This is static editorial imagery only — never a product
+ * image or backend data.
+ */
+export const heroImage: HeroImageContent | undefined = undefined
+
+export const heroContent = {
+  badge: 'Bienvenido',
+  title: '__SITE_NAME__',
+  titleAccent: 'para cada proyecto',
+  // Neutral: no delivery/shipping promise.
+  description: 'Productos seleccionados con precios claros y compra sencilla.',
+  primaryCta: { label: 'Comprar ahora' },
+  secondaryCta: { label: 'Ver categorías' },
+}
+
+export const benefitsContent = {
+  badge: '__SITE_NAME__',
+  title: 'Compra con confianza',
+  // Neutral: no delivery/shipping promise.
+  description: 'Ventajas pensadas para una compra clara y segura.',
+  items: [
+    {
+      id: 'pago',
+      title: 'Pago protegido',
+      description: 'Compra con confianza, múltiples opciones de pago.',
+      icon: 'shield-check',
+    },
+    {
+      id: 'catalogo',
+      title: 'Catálogo variado',
+      description: 'Productos para tu hogar y tu negocio.',
+      icon: 'star',
+    },
+    {
+      id: 'soporte',
+      title: 'Soporte local',
+      description: 'Atención personalizada en todo el país.',
+      icon: 'headphones',
+    },
+  ],
+}
+
+export const categoriesContent = {
+  title: 'Compra por categoría',
+  description: 'Explora nuestro catálogo completo.',
+}
+
+/**
+ * Editorial section instance content, keyed by the section instance id the
+ * manifest persists (`views[].sections[].id`, e.g. `home-faq-1`). The derived
+ * view module reads `sectionContent[id]`, so adding, reordering, or removing a
+ * section never rewrites this file and your copy survives `storefront sync`.
+ * Plain data only, matching the section fragment's props; an unset id renders
+ * the section's neutral default.
+ */
+export const sectionContent: Record<string, Record<string, unknown>> = {}

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

@@ -0,0 +1,15 @@
+// Thor Commerce view data: home
+// User-owned loader shaping for the home 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.
+
+export function selectHeroProducts<T>(products: readonly T[]): T[] {
+  return products.slice(0, 4)
+}
+
+export function toNavCategories(
+  categories: readonly { label: string; href: string }[],
+): { label: string; href: string }[] {
+  return categories.map((category) => ({ label: category.label, href: category.href }))
+}