@thorprovider/storefront 0.3.1 → 0.4.0-mvp.0

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

@@ -0,0 +1,105 @@
+// Thor Commerce view content: checkout
+// User-owned view content — checkout copy, field validation rules, field
+// descriptions, and the confirmation fulfilment timeline. 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 checkoutContent = {
+  title: 'Finalizar compra',
+  description: 'Completa tus datos para recibir tu pedido.',
+  validation: {
+    email: {
+      validateOn: 'blur',
+      checks: [
+        { type: 'required', message: 'Ingresa tu correo electrónico.' },
+        { type: 'email', message: 'Ingresa un correo válido.' },
+      ],
+    },
+    firstName: {
+      checks: [{ type: 'required', message: 'Ingresa tu nombre.' }],
+    },
+    lastName: {
+      checks: [{ type: 'required', message: 'Ingresa tus apellidos.' }],
+    },
+    phone: {
+      checks: [
+        {
+          type: 'pattern',
+          args: { pattern: '^[+]?[0-9]{7,15}$' },
+          message: 'Ingresa un teléfono válido.',
+        },
+      ],
+    },
+    address: {
+      checks: [{ type: 'required', message: 'Ingresa tu dirección.' }],
+    },
+    city: {
+      checks: [{ type: 'required', message: 'Ingresa la ciudad.' }],
+    },
+    state: {
+      checks: [{ type: 'required', message: 'Ingresa la provincia.' }],
+    },
+    country: {
+      checks: [{ type: 'required', message: 'Selecciona tu país.' }],
+    },
+    zipCode: {
+      checks: [
+        { type: 'required', message: 'Ingresa el código postal.' },
+        {
+          type: 'pattern',
+          args: { pattern: '^[0-9]{4,5}$' },
+          message: 'Código postal inválido.',
+        },
+      ],
+    },
+    paymentMethod: {
+      checks: [{ type: 'required', message: 'Selecciona un método de pago.' }],
+    },
+  },
+  fieldDescriptions: {
+    email: 'Usaremos este correo para el seguimiento del pedido.',
+    phone: 'Te contactaremos para coordinar la entrega.',
+    promoCode: 'Aplica códigos promocionales válidos.',
+  },
+}
+
+export const confirmationContent = {
+  // Neutral default copy. The launch flow must not claim a delivery, a shipping
+  // promise, or that an email was sent: the backend order may be pending, and
+  // no email is guaranteed. The email line only shows the contact the backend
+  // actually supplied (`{email}` is filled only when `order.email` is present).
+  titleLabel: 'Pedido registrado',
+  orderPlacedLabel: 'Pedido {number} · {date} · Correo de contacto: {email}',
+  orderPlacedNoEmailLabel: 'Pedido {number} · {date}',
+  itemsLabel: 'Comprobante del pedido',
+  // Stage descriptions are generic expectations, rendered only when the backend
+  // reports a fulfilment stage; `at: null` keeps them as expectations, not facts.
+  fulfilmentDetails: {
+    Confirmed: {
+      stage: 'Confirmed',
+      summary: 'Pedido registrado en el sistema.',
+      location: 'Tienda',
+      at: null,
+    },
+    Packed: {
+      stage: 'Packed',
+      summary: 'Preparación del pedido.',
+      location: 'Almacén',
+      at: null,
+    },
+    Shipped: {
+      stage: 'Shipped',
+      summary: 'Pedido despachado.',
+      location: 'En tránsito',
+      at: null,
+    },
+    Delivered: {
+      stage: 'Delivered',
+      summary: 'Pedido entregado.',
+      location: 'Destino',
+      at: null,
+    },
+  },
+}

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

@@ -0,0 +1,23 @@
+// Thor Commerce view data: checkout
+// User-owned loader shaping for the checkout 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 buildCheckoutData(input: {
+  countries: readonly { code: string; name: string }[]
+  paymentMethods: readonly unknown[]
+  source: 'mock' | 'medusa'
+}) {
+  return {
+    checkoutCountries: input.countries.map((country) => ({
+      value: country.code,
+      label: country.name,
+    })),
+    checkoutPaymentMethods: input.paymentMethods,
+    // The explicit data source: a configured mock is labelled mock; a real-mode
+    // failure is surfaced separately through `dataError`, never hidden.
+    dataSource: input.source,
+    dataError: null,
+  }
+}

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

@@ -0,0 +1,111 @@
+// Thor Commerce view module: checkout
+// 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 -> "checkout".
+//
+// The initial render does NOT read cookies here (this module is part of the
+// client catalog graph). The catch-all page injects the read-only cart state;
+// `CheckoutBoot` then loads the checkout data or reconciles a completed receipt
+// through Server Actions.
+
+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 { checkoutConfirmationProps, checkoutViewProps } from './props'
+import {
+  checkoutConfirmationPropsSchema,
+  checkoutEmptyPropsSchema,
+  checkoutPropsSchema,
+} from './schema'
+
+// The element tree is derived wiring; the rendered props and validation rules
+// come from the user-owned ./props.ts module so they survive sync and removal.
+// Four states: bootstrap (headless), confirmation (order), empty cart, or form.
+const elements: Record<string, StorefrontElement> = {
+  'checkout.boot': {
+    type: 'CheckoutBoot',
+    props: {},
+  },
+  'checkout.confirmation': {
+    type: 'CheckoutConfirmation',
+    visible: { $state: '/lastReceipt' },
+    props: checkoutConfirmationProps,
+    on: { continueShopping: { action: 'continueShopping' } },
+  },
+  'checkout.empty': {
+    type: 'CheckoutEmpty',
+    visible: {
+      $and: [
+        { $state: '/lastReceipt', not: true },
+        { $state: '/cartQuantity', eq: 0 },
+        // Show the empty state when there is no active cart and no receipt to
+        // recover, or when an active cart exists (even empty). A signed receipt
+        // with no active cart is reconciled by the boot, not shown as empty.
+        {
+          $or: [{ $state: '/receiptAvailable', not: true }, { $state: '/cartId' }],
+        },
+      ],
+    },
+    props: {},
+    on: { continueShopping: { action: 'continueShopping' } },
+  },
+  'checkout.view': {
+    type: 'Checkout',
+    visible: {
+      $and: [{ $state: '/lastReceipt', not: true }, { $state: '/cartQuantity', gt: 0 }],
+    },
+    props: checkoutViewProps,
+    on: {
+      placeOrder: { action: 'placeOrder' },
+      reconcileOrder: { action: 'reconcileOrder' },
+      syncCheckoutAddress: { action: 'syncCheckoutAddress' },
+      selectShippingMethod: { action: 'selectShippingMethod' },
+    },
+  },
+}
+
+const catalog = {
+  CheckoutBoot: {
+    props: checkoutEmptyPropsSchema,
+    description: 'Headless checkout bootstrap: loads form data or reconciles a receipt.',
+  },
+  Checkout: {
+    props: checkoutPropsSchema,
+    description: 'Checkout form with order summary, shipping and payment steps.',
+  },
+  CheckoutEmpty: {
+    props: checkoutEmptyPropsSchema,
+    description: 'Empty-cart state for the checkout route.',
+  },
+  CheckoutConfirmation: {
+    props: checkoutConfirmationPropsSchema,
+    description: 'Order confirmation with fulfilment progress.',
+  },
+}
+
+export const checkout: ViewModule = {
+  name: 'checkout',
+  elements,
+  catalog,
+  registry,
+  route: {
+    path: '/checkout',
+    loaderName: 'checkout',
+    layout: 'default',
+    metadata: {
+      title: 'Finalizar compra',
+      description: 'Completa tus datos de envío y pago para recibir tu pedido.',
+    },
+    entry: pageRoot(
+      'checkout',
+      ['checkout.boot', 'checkout.confirmation', 'checkout.empty', 'checkout.view'],
+      elements,
+    ),
+  },
+  loader: {
+    checkout: async () => ({ dataSource: getDataSource(), dataError: null }),
+  },
+}

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

@@ -0,0 +1,49 @@
+// Thor Commerce view props: checkout
+// User-owned element props for the checkout 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 { checkoutContent, confirmationContent } from './content'
+
+export const checkoutViewProps = {
+  ...checkoutContent,
+  // Backend-authoritative summary: line totals and cart totals come from the
+  // backend cart state, never computed here.
+  orderSummary: {
+    items: { $state: '/cart' },
+    totals: { $state: '/cartTotals' },
+  },
+  countries: { $state: '/checkoutCountries' },
+  shippingOptions: { $state: '/checkoutShippingOptions' },
+  selectedShippingOptionId: { $state: '/checkoutSelectedShippingOptionId' },
+  paymentMethods: { $state: '/checkoutPaymentMethods' },
+  fieldErrors: { $state: '/checkoutFieldErrors' },
+  values: {
+    email: { $state: '/checkout/email' },
+    firstName: { $state: '/checkout/firstName' },
+    lastName: { $state: '/checkout/lastName' },
+    phone: { $state: '/checkout/phone' },
+    address: { $state: '/checkout/address' },
+    city: { $state: '/checkout/city' },
+    state: { $state: '/checkout/state' },
+    zipCode: { $state: '/checkout/zipCode' },
+    country: { $state: '/checkout/country' },
+    paymentMethod: { $state: '/checkout/paymentMethod' },
+    cardNumber: { $state: '/checkout/cardNumber' },
+    expiryDate: { $state: '/checkout/expiryDate' },
+    cvv: { $state: '/checkout/cvv' },
+    cardName: { $state: '/checkout/cardName' },
+    saveInfo: { $state: '/checkout/saveInfo' },
+    sameAsBilling: { $state: '/checkout/sameAsBilling' },
+    newsletter: { $state: '/checkout/newsletter' },
+    promoCode: { $state: '/checkout/promoCode' },
+  },
+}
+
+export const checkoutConfirmationProps = {
+  // One atomic state path carries the order and its backend lines together.
+  receipt: { $state: '/lastReceipt' },
+  ...confirmationContent,
+}

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

@@ -0,0 +1,217 @@
+'use client'
+
+// Thor Commerce view registry fragment: checkout
+// Client boundary for the checkout 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 { useEffect, useRef } from 'react'
+import {
+  Button,
+  CheckoutForm1 as CheckoutBlock,
+  CheckoutConfirmation as CheckoutConfirmationBlock,
+} from '@thorprovider/blocks'
+import { useStateStore } from '@json-render/react'
+import { loadCheckoutAction, reconcileReceiptAction } from '../../actions'
+import type { CartStatePatch, PlaceOrderResult } from '../../commerce'
+import type { ViewRegistry } from '../types'
+import { checkoutConfirmationPropsSchema, checkoutPropsSchema } from './schema'
+
+// Address fields whose change can complete the address; when the full address
+// is present the handler syncs it to the backend and loads eligible shipping.
+const ADDRESS_FIELDS = new Set([
+  'email',
+  'firstName',
+  'lastName',
+  'phone',
+  'address',
+  'city',
+  'state',
+  'zipCode',
+  'country',
+])
+
+export const registry: ViewRegistry = {
+  /**
+   * Headless bootstrap rendered on the checkout route. It loads the checkout
+   * data (countries/payment methods/cart) for an active cart, or reconciles a
+   * completed receipt through the cookie-authorized Server Action. It never
+   * reads a bare order/cart id.
+   */
+  CheckoutBoot: () => {
+    const { state, set } = useStateStore()
+    const booted = useRef(false)
+    useEffect(() => {
+      if (booted.current) return
+      booted.current = true
+
+      const applyResult = (result: PlaceOrderResult) => {
+        set('/checkoutPending', false)
+        if (result.status === 'order') {
+          // ONE atomic write carries the order and its backend lines, so an SSR
+          // refresh cannot drop the lines.
+          set('/lastReceipt', { order: result.order, lines: result.lines })
+          set('/orderStatus', 'complete')
+          set('/checkoutError', null)
+          set('/checkoutErrorKind', null)
+          set('/cart', [])
+          set('/cartTotals', null)
+          set('/cartId', null)
+          set('/cartQuantity', 0)
+          set('/cartCompleted', true)
+          set('/checkoutSelectedShippingOptionId', null)
+          return
+        }
+        set('/orderStatus', result.status === 'cart-error' ? 'error' : result.status)
+        set('/checkoutErrorKind', result.status)
+        set('/checkoutError', result.message)
+      }
+
+      const bootError = (scope: string) => (error: unknown) => {
+        // Never swallow: log a non-secret context line and surface a message.
+        console.error(
+          `[storefront/checkout] ${scope} failed`,
+          error instanceof Error ? error.message : error,
+        )
+        set('/checkoutPending', false)
+        set('/checkoutError', 'No se pudo cargar el checkout. Inténtalo de nuevo.')
+        set('/checkoutErrorKind', 'error')
+      }
+
+      // 1. An active cart the backend already committed is an unresolved
+      //    completion: reconcile IT first (never a blind retry).
+      // 2. Otherwise ANY active cart (even empty) loads the checkout form; the
+      //    signed receipt is NOT auto-recovered while an active cart exists.
+      // 3. Only with no active cart does a signed receipt proof recover the
+      //    completed order.
+      if (state.cartId && state.cartCompleted) {
+        set('/checkoutPending', true)
+        void reconcileReceiptAction().then(applyResult).catch(bootError('reconcileReceipt'))
+        return
+      }
+      if (state.cartId) {
+        set('/checkoutPending', true)
+        void loadCheckoutAction()
+          .then((result) => {
+            set('/checkoutPending', false)
+            if (!result.ok) {
+              set('/checkoutError', result.error)
+              set('/checkoutErrorKind', 'error')
+              return
+            }
+            const cart = result.cart as CartStatePatch
+            set('/cart', cart.cart)
+            set('/cartTotals', cart.cartTotals)
+            set('/cartId', cart.cartId)
+            set('/cartQuantity', cart.cartQuantity)
+            set('/cartSelectedShippingOptionId', cart.cartSelectedShippingOptionId)
+            set('/checkoutSelectedShippingOptionId', cart.cartSelectedShippingOptionId)
+            if (result.countries) set('/checkoutCountries', result.countries)
+            if (result.paymentMethods) set('/checkoutPaymentMethods', result.paymentMethods)
+            if (result.shippingOptions) set('/checkoutShippingOptions', result.shippingOptions)
+            set('/checkoutError', null)
+          })
+          .catch(bootError('loadCheckout'))
+        return
+      }
+      if (state.receiptAvailable) {
+        set('/checkoutPending', true)
+        void reconcileReceiptAction().then(applyResult).catch(bootError('reconcileReceipt'))
+      }
+    }, [])
+    return null
+  },
+  Checkout: ({ props, emit }) => {
+    const { state, set } = useStateStore()
+    const parsed = checkoutPropsSchema.parse(props)
+    const unresolved = state.checkoutErrorKind === 'unresolved'
+    const cartError = typeof state.cartError === 'string' ? state.cartError : undefined
+    const checkoutError = typeof state.checkoutError === 'string' ? state.checkoutError : undefined
+    return (
+      <CheckoutBlock
+        title={parsed.title}
+        description={parsed.description}
+        orderSummary={parsed.orderSummary}
+        totalsState={state.cartPending ? 'pending' : cartError ? 'error' : 'idle'}
+        totalsErrorLabel={cartError}
+        onRetryTotals={() => emit('syncCheckoutAddress')}
+        countries={parsed.countries}
+        shippingOptions={parsed.shippingOptions}
+        selectedShippingOptionId={parsed.selectedShippingOptionId ?? undefined}
+        onSelectShippingOption={(id) => {
+          set('/checkoutSelectedShippingOptionId', id)
+          emit('selectShippingMethod')
+        }}
+        paymentMethods={parsed.paymentMethods}
+        values={parsed.values}
+        fieldErrors={parsed.fieldErrors}
+        fieldDescriptions={parsed.fieldDescriptions}
+        collectCardFields={false}
+        onChange={(field, value) => {
+          set(`/checkout/${field}`, value)
+          if (ADDRESS_FIELDS.has(field)) emit('syncCheckoutAddress')
+        }}
+        onSubmit={() => emit('placeOrder')}
+        submitting={Boolean(state.checkoutPending)}
+        submitError={checkoutError}
+        // An ambiguous completion offers RECONCILE only; a definite failure
+        // (cart-with-error or pre-completion error) offers a controlled retry.
+        onRetrySubmit={unresolved ? () => emit('reconcileOrder') : () => emit('placeOrder')}
+        submitErrorActionLabel={unresolved ? 'Reconciliar' : 'Reintentar'}
+      />
+    )
+  },
+  CheckoutEmpty: ({ emit }) => (
+    <div className="mx-auto max-w-md px-4 py-16 text-center">
+      <h1 className="text-2xl font-bold">Tu carrito está vacío</h1>
+      <p className="text-muted-foreground mt-2 text-sm">
+        Agrega productos para finalizar la compra.
+      </p>
+      <Button className="mt-6" onClick={() => emit('continueShopping')}>
+        Seguir comprando
+      </Button>
+    </div>
+  ),
+  CheckoutConfirmation: ({ props, emit }) => {
+    const parsed = checkoutConfirmationPropsSchema.parse(props)
+    // Forward every neutral label from user-owned content to the block, so the
+    // curated flow never falls back to the block's non-neutral defaults.
+    return (
+      <CheckoutConfirmationBlock
+        order={parsed.receipt.order}
+        orderLines={parsed.receipt.lines}
+        fulfilmentDetails={parsed.fulfilmentDetails}
+        titleLabel={parsed.titleLabel}
+        orderPlacedLabel={parsed.orderPlacedLabel}
+        orderPlacedNoEmailLabel={parsed.orderPlacedNoEmailLabel}
+        itemsLabel={parsed.itemsLabel}
+        quantityLabel={parsed.quantityLabel}
+        subtotalLabel={parsed.subtotalLabel}
+        discountLabel={parsed.discountLabel}
+        shippingLabel={parsed.shippingLabel}
+        taxLabel={parsed.taxLabel}
+        totalLabel={parsed.totalLabel}
+        freeLabel={parsed.freeLabel}
+        amountUnavailableLabel={parsed.amountUnavailableLabel}
+        shippingAddressLabel={parsed.shippingAddressLabel}
+        billingAddressLabel={parsed.billingAddressLabel}
+        continueShoppingLabel={parsed.continueShoppingLabel}
+        contactSupportLabel={parsed.contactSupportLabel}
+        supportLabel={parsed.supportLabel}
+        progressLabel={parsed.progressLabel}
+        estimatedDeliveryLabel={parsed.estimatedDeliveryLabel}
+        currentStageLabel={parsed.currentStageLabel}
+        inProgressLabel={parsed.inProgressLabel}
+        expectedByLabel={parsed.expectedByLabel}
+        completedLabel={parsed.completedLabel}
+        statusLabel={parsed.statusLabel}
+        locationLabel={parsed.locationLabel}
+        trackOrderLabel={parsed.trackOrderLabel}
+        continueShoppingHref={parsed.continueShoppingHref ?? '#'}
+        supportHref={parsed.supportHref}
+        onContinueShopping={() => emit('continueShopping')}
+      />
+    )
+  },
+}