@thorprovider/storefront 0.3.1 → 0.4.0-mvp.0

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/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,153 @@
+'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'
+
+// 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') {
+        // 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: () => {
+        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',
+}

package/assets/templates/features/customer-auth/handlers.ts

@@ -0,0 +1,59 @@
+'use client'
+
+// Generated by Thor Commerce storefront (feature: customer-auth — handlers)
+// The customer-auth capability's action handlers. Installed only when the
+// feature is in the manifest; the handlers composer calls this hook. Login and
+// registration are invoked directly by the view registry (their credential
+// payload must never enter the state store); these handlers own the non-secret
+// state transitions: the sign-in / sign-up toggle and logout.
+
+import { useEffect } from 'react'
+import { useActions, useStateStore } from '@json-render/react'
+import { logoutAction } from '../../actions'
+
+export function useCustomerAuthHandlers() {
+  const { set } = useStateStore()
+  const { registerHandler } = useActions()
+
+  useEffect(() => {
+    const handlers: Record<string, () => void> = {
+      showRegister: () => {
+        set('/accountError', null)
+        set('/accountMode', 'register')
+      },
+      showLogin: () => {
+        set('/accountError', null)
+        set('/accountMode', 'login')
+      },
+      logout: () => {
+        set('/accountPending', true)
+        set('/accountError', null)
+        void logoutAction()
+          .then((result) => {
+            set('/accountPending', false)
+            if (result.ok) {
+              set('/accountCustomer', null)
+              set('/accountAuthenticated', false)
+              set('/accountMode', 'login')
+              return
+            }
+            set('/accountError', result.error)
+          })
+          .catch((error) => {
+            // Never swallow: log a non-secret context line and surface a message.
+            console.error(
+              '[storefront/account] logout failed',
+              error instanceof Error ? error.message : error,
+            )
+            set('/accountPending', false)
+            set('/accountError', 'No se pudo cerrar la sesión. Inténtalo de nuevo.')
+          })
+      },
+    }
+
+    for (const [name, handler] of Object.entries(handlers)) {
+      registerHandler(name, handler)
+    }
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [])
+}

package/assets/templates/features/customer-auth/state.ts

@@ -0,0 +1,36 @@
+// Generated by Thor Commerce storefront (feature: customer-auth — state slice)
+// The customer-auth capability's state. Installed only when the feature is in
+// the manifest; the state composer spreads it over the core state.
+
+import type { Customer } from '@thorprovider/types'
+import type { AccountOrderView } from '../../state.core'
+
+export interface CustomerAuthState {
+  /** The resolved customer, or null when unauthenticated. Never a token. */
+  accountCustomer: Customer | null
+  accountAuthenticated: boolean
+  /** Which auth surface is mounted: the sign-in page or the registration page. */
+  accountMode: 'login' | 'register'
+  accountPending: boolean
+  accountError: string | null
+  /** The customer's fetched order-history rows; empty until (or without) a load. */
+  accountOrders: AccountOrderView[]
+  /** True while the order history is being loaded. */
+  accountOrdersPending: boolean
+  /** The order-history load failure, or null when it loaded. */
+  accountOrdersError: string | null
+  /** The order number selected for the inline detail; null when none is open. */
+  accountSelectedOrderId: string | null
+}
+
+export const customerAuthState: CustomerAuthState = {
+  accountCustomer: null,
+  accountAuthenticated: false,
+  accountMode: 'login',
+  accountPending: false,
+  accountError: null,
+  accountOrders: [],
+  accountOrdersPending: false,
+  accountOrdersError: null,
+  accountSelectedOrderId: null,
+}

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

@@ -0,0 +1,11 @@
+// Generated by Thor Commerce storefront (feature: recommendations — state slice)
+// The recommendations capability's state. Installed only when the feature is in
+// the manifest; the state composer spreads it over the core state.
+
+export interface RecommendationsState {
+  recommendedProducts: unknown[]
+}
+
+export const recommendationsState: RecommendationsState = {
+  recommendedProducts: [],
+}

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

@@ -0,0 +1,35 @@
+// Thor Commerce view content: account
+// User-owned view content — account copy for the sign-in and registration
+// surfaces. 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 accountContent = {
+  login: {
+    logoText: '__SITE_NAME__',
+    welcomeTitleLabel: 'Bienvenido de nuevo',
+    welcomeDescriptionLabel: 'Inicia sesión para gestionar tu cuenta.',
+    emailLabel: 'Correo electrónico',
+    passwordLabel: 'Contraseña',
+    signInLabel: 'Iniciar sesión',
+    createAccountLabel: 'Crea una cuenta',
+  },
+  register: {
+    logoText: '__SITE_NAME__',
+    createAccountTitleLabel: 'Crea tu cuenta',
+    createAccountDescriptionLabel: 'Regístrate para gestionar tus pedidos.',
+    fullNameLabel: 'Nombre completo',
+    emailLabel: 'Correo electrónico',
+    passwordLabel: 'Contraseña',
+    createAccountLabel: 'Crear cuenta',
+    signInLabel: 'Inicia sesión',
+  },
+  orders: {
+    titleLabel: 'Mis pedidos',
+    descriptionLabel: 'Consulta tus pedidos anteriores',
+    emptyLabel: 'Aún no tienes pedidos.',
+    errorLabel: 'No se pudieron cargar tus pedidos.',
+    loadingLabel: 'Cargando pedidos…',
+  },
+}

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

@@ -0,0 +1,114 @@
+// Thor Commerce view module: account
+// 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 -> "account".
+//
+// The initial render does NOT read the auth cookie here (this module is part of
+// the client catalog graph). The catch-all page mounts the route and the
+// headless `AccountBoot` resolves the current customer through the
+// cookie-authorized Server Action, so the token never reaches this module.
+
+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 { accountContent } from './content'
+import {
+  accountEmptyPropsSchema,
+  accountLoginPropsSchema,
+  accountOrdersPropsSchema,
+  accountRegisterPropsSchema,
+} from './schema'
+
+// Four surfaces: bootstrap (headless), sign-in, registration, and the signed-in
+// panel. The sign-in and registration surfaces are toggled by the `/accountMode`
+// state; the panel shows only when `/accountAuthenticated` is true.
+const elements: Record<string, StorefrontElement> = {
+  'account.boot': {
+    type: 'AccountBoot',
+    props: {},
+  },
+  'account.login': {
+    type: 'AccountLogin',
+    visible: {
+      $and: [
+        { $state: '/accountAuthenticated', not: true },
+        { $state: '/accountMode', eq: 'login' },
+      ],
+    },
+    props: accountContent.login,
+    on: { showRegister: { action: 'showRegister' } },
+  },
+  'account.register': {
+    type: 'AccountRegister',
+    visible: {
+      $and: [
+        { $state: '/accountAuthenticated', not: true },
+        { $state: '/accountMode', eq: 'register' },
+      ],
+    },
+    props: accountContent.register,
+    on: { showLogin: { action: 'showLogin' } },
+  },
+  'account.panel': {
+    type: 'AccountPanel',
+    visible: { $state: '/accountAuthenticated' },
+    props: {},
+    on: { logout: { action: 'logout' } },
+  },
+  'account.orders': {
+    type: 'AccountOrders',
+    visible: { $state: '/accountAuthenticated' },
+    props: accountContent.orders,
+  },
+}
+
+const catalog = {
+  AccountBoot: {
+    props: accountEmptyPropsSchema,
+    description: 'Headless account bootstrap: resolves the current customer from the auth cookie.',
+  },
+  AccountLogin: {
+    props: accountLoginPropsSchema,
+    description: 'Sign-in page with email and password and a link to create an account.',
+  },
+  AccountRegister: {
+    props: accountRegisterPropsSchema,
+    description: 'Registration page with name, email, and password and a link to sign in.',
+  },
+  AccountPanel: {
+    props: accountEmptyPropsSchema,
+    description: 'Minimal signed-in state with the customer name and a logout control.',
+  },
+  AccountOrders: {
+    props: accountOrdersPropsSchema,
+    description:
+      "Signed-in customer's order history rendered by OrderHistory2, with loading, empty, and error states and an inline order detail.",
+  },
+}
+
+export const account: ViewModule = {
+  name: 'account',
+  elements,
+  catalog,
+  registry,
+  route: {
+    path: '/cuenta',
+    loaderName: 'account',
+    layout: 'default',
+    metadata: {
+      title: 'Mi cuenta',
+      description: 'Inicia sesión o crea una cuenta para gestionar tu cuenta.',
+    },
+    entry: pageRoot(
+      'account',
+      ['account.boot', 'account.login', 'account.register', 'account.panel', 'account.orders'],
+      elements,
+    ),
+  },
+  loader: {
+    account: async () => ({ dataSource: getDataSource(), dataError: null }),
+  },
+}