@thorprovider/storefront 0.3.1 → 0.4.0-mvp.2

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

@@ -0,0 +1,299 @@
+// Thor Commerce view module: category
+// 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 -> "category".
+//
+// E2 task 6.1: the category listing is ONE controlled `CategoryFilter2` — the
+// base listing slot `category.filter`, always present. The optional
+// `catalog-search` / `category-filters` features are control contributions to
+// that single block (logical mounts `category.search` / `category.filters`),
+// never a second listing/controller. Their visibility and config are read from
+// the installed manifest (`mountedFeatures` / `mountedFeatureConfigs`) that
+// `sync` derives from `storefront.config.json`; no loader is hand-edited to add
+// or remove them.
+
+import { z } from 'zod'
+import {
+  buildActiveFilterChips,
+  getCatalog,
+  getCatalogSortKeys,
+  getCollectionOptions,
+  loadCategoryListing,
+  mapCatalogOutcomeToStatus,
+  mapCatalogResultsToFilterProps,
+} from '@thorprovider/runtime/commerce'
+import { getDataSource, getStoreContext, isRealMode } from '../../store-context'
+import { mountedFeatureConfigs, mountedFeatureNames, mountedFeatures } from '../../composition'
+import { pageRoot } from '../../spec/page-root'
+import type { StorefrontElement } from '../../spec/types'
+import type { ViewModule } from '../types'
+import { registry } from './registry'
+import { categoryBreadcrumbProps, categoryFilterProps } from './props'
+import { breadcrumbPropsSchema, categoryFilterPropsSchema } from './schema'
+
+// The single controlled `CategoryFilter2` base listing. The search/filter
+// controls are shown only when the matching feature is installed; the base
+// listing always owns the route scope, `sort`, `page`, `pageSize`, the products,
+// and pagination.
+const hasSearch = mountedFeatures.includes('catalog-search')
+const hasFilters = mountedFeatures.includes('category-filters')
+// The navigability feature contributes the entity-derived breadcrumb trail. When
+// it is not installed the trail is empty and the Breadcrumb block renders
+// nothing, so removal leaves no dangling navigation aid.
+const hasNavigability = mountedFeatureNames.includes('navigability')
+const searchConfig = (mountedFeatureConfigs['catalog-search'] ?? {}) as { placeholder?: string }
+const filtersConfig = (mountedFeatureConfigs['category-filters'] ?? {}) as {
+  filterSet?: string[]
+  showPrice?: boolean
+}
+
+// UI labels for the adapter-advertised sort keys. The keys themselves come from
+// the provider (`getCatalogSortKeys`); no global price sort is ever assumed.
+const SORT_LABELS: Record<string, string> = {
+  featured: 'Destacados',
+  name: 'Nombre',
+  newest: 'Más recientes',
+}
+
+const elements: Record<string, StorefrontElement> = {
+  'category.breadcrumb': {
+    type: 'Breadcrumb',
+    props: {
+      ...categoryBreadcrumbProps,
+      items: { $state: '/breadcrumbItems' },
+    },
+  },
+  'category.filter': {
+    type: 'CategoryFilter2',
+    props: {
+      // User-owned copy first, so a customization can be overridden by the
+      // feature config (search placeholder) and the derived state bindings.
+      ...categoryFilterProps,
+      showSearch: hasSearch,
+      showFilters: hasFilters,
+      showSort: true,
+      showPrice: filtersConfig.showPrice === true,
+      ...(hasSearch && searchConfig.placeholder
+        ? { searchPlaceholder: searchConfig.placeholder }
+        : {}),
+      // Composition context for generated navigation (task 4.11): the client
+      // registry drops a removed feature's owned orphan parameters on a UI
+      // action. Read separately from the block props; never a `CategoryFilter2`
+      // prop and never bound to state.
+      mountedFeatures,
+      products: { $state: '/categoryFilterProducts' },
+      pagination: { $state: '/categoryFilterPagination' },
+      status: { $state: '/categoryFilterStatus' },
+      activeFilters: { $state: '/categoryFilterActiveFilters' },
+      searchValue: { $state: '/categoryFilterSearchValue' },
+      selectedCategories: { $state: '/categoryFilterSelectedCategories' },
+      selectedCollections: { $state: '/categoryFilterSelectedCollections' },
+      selectedSort: { $state: '/categoryFilterSelectedSort' },
+      selectedPage: { $state: '/categoryFilterSelectedPage' },
+      selectedPageSize: { $state: '/categoryFilterSelectedPageSize' },
+      sortOptions: { $state: '/categoryFilterSortOptions' },
+      categories: { $state: '/categoryFilterCategories' },
+      collections: { $state: '/categoryFilterCollections' },
+      priceRange: { $state: '/categoryFilterPriceRange' },
+    },
+  },
+}
+
+const catalog = {
+  Breadcrumb: {
+    props: breadcrumbPropsSchema,
+    description: 'Migas de pan derivadas de la jerarquía real de categorías.',
+  },
+  CategoryFilter2: {
+    props: categoryFilterPropsSchema,
+    description:
+      'Listado de categoría: una sola presentación controlada CategoryFilter2 con productos, paginación, búsqueda y filtros opcionales.',
+  },
+}
+
+/** Empty state for the single listing, used on every failure path. */
+const emptyFilterState = () => ({
+  categoryFilterProducts: [],
+  categoryFilterPagination: [] as (number | string)[],
+  categoryFilterActiveFilters: [],
+  categoryFilterSearchValue: '',
+  categoryFilterSelectedCategories: [] as string[],
+  categoryFilterSelectedCollections: [] as string[],
+  categoryFilterSelectedSort: 'featured',
+  categoryFilterSelectedPage: 1,
+  categoryFilterSelectedPageSize: 50,
+  categoryFilterSortOptions: [],
+  categoryFilterCategories: [],
+  categoryFilterCollections: [],
+  categoryFilterPriceRange: undefined,
+  breadcrumbItems: [] as { label: string; href?: string }[],
+})
+
+/**
+ * The real category entity for the current route scope, resolved from the
+ * backend catalog. Entity SEO reads this; an unknown/absent scope yields no
+ * entity (no metadata or structured data is fabricated).
+ */
+function resolveCategoryEntity(
+  slug: string | undefined,
+  catalog: Awaited<ReturnType<typeof getCatalog>>,
+): { handle: string; name: string; description?: string } | undefined {
+  if (!slug) return undefined
+  const match = catalog.categoriesRaw.find((entry) => entry.handle === slug)
+  if (!match) return undefined
+  const description =
+    typeof match.description === 'string' && match.description.trim() !== ''
+      ? match.description
+      : undefined
+  return {
+    handle: match.handle,
+    name: match.name,
+    ...(description !== undefined ? { description } : {}),
+  }
+}
+
+/**
+ * Entity-derived breadcrumb trail for the current category scope: Home, the
+ * real ancestor chain (root -> leaf), and the current category. Derived from
+ * the backend category hierarchy (`parentCategoryId`); no level is fabricated,
+ * a cycle cannot loop forever, and no trail is produced when the navigability
+ * feature is not installed or the scope is unknown.
+ */
+function resolveBreadcrumbItems(
+  slug: string | undefined,
+  catalog: Awaited<ReturnType<typeof getCatalog>>,
+): { label: string; href?: string }[] {
+  if (!hasNavigability || !slug) return []
+  const byHandle = new Map(catalog.categoriesRaw.map((entry) => [entry.handle, entry]))
+  const byId = new Map(catalog.categoriesRaw.map((entry) => [entry.id, entry]))
+  const chain: { label: string; href: string }[] = []
+  const visited = new Set<string>()
+  let current = byHandle.get(slug)
+  while (current && !visited.has(current.handle)) {
+    visited.add(current.handle)
+    chain.unshift({ label: current.name, href: `/categories/${current.handle}` })
+    current = current.parentCategoryId ? byId.get(current.parentCategoryId) : undefined
+  }
+  if (chain.length === 0) return []
+  const leaf = chain[chain.length - 1]
+  // The current (leaf) item is not a link; only ancestors are navigable.
+  return [{ label: 'Inicio', href: '/' }, ...chain.slice(0, -1), { label: leaf.label }]
+}
+
+export const category: ViewModule = {
+  name: 'category',
+  elements,
+  catalog,
+  registry,
+  route: {
+    path: '/categories/[[...slug]]',
+    loaderName: 'category',
+    layout: 'default',
+    metadata: {
+      title: 'Categoría',
+      description: 'Explora los productos de esta categoría en __SITE_NAME__.',
+    },
+    entry: pageRoot('category', ['category.breadcrumb', 'category.filter'], elements),
+  },
+  loader: {
+    category: async (params, searchParams) => {
+      const slug = Array.isArray(params.slug) ? params.slug[0] : params.slug
+      try {
+        // Validate the raw URL through the pure boundary before any commerce
+        // call. An invalid, repeated, or unknown parameter — or one owned by a
+        // feature that is not installed — returns a typed error with zero
+        // provider resolution, not even the sidebar catalog (E2 task 5.1/6.1).
+        const listing = await loadCategoryListing({
+          searchParams: searchParams ?? {},
+          ...(slug ? { categoryScope: slug } : {}),
+          mountedFeatures,
+          ...(isRealMode() ? { context: getStoreContext() } : {}),
+        })
+
+        if (!listing.ok) {
+          return {
+            storeCategories: [],
+            dataSource: getDataSource(),
+            dataError: null,
+            ...emptyFilterState(),
+            categoryFilterStatus: mapCatalogOutcomeToStatus({ ok: false, error: listing.error }),
+          }
+        }
+
+        const catalog = await getCatalog()
+        const advertisedSortKeys = await getCatalogSortKeys()
+        const sortOptions = advertisedSortKeys.map((key) => ({
+          value: key,
+          label: SORT_LABELS[key] ?? key,
+        }))
+        // Real adapter category options (handle + name). No fake counts/ranges.
+        const allCategories = catalog.categoriesRaw.map((entry) => ({
+          id: entry.handle,
+          label: entry.name,
+        }))
+        const filterSet = filtersConfig.filterSet ?? ['categories', 'collections']
+        const categories = filterSet.includes('categories') ? allCategories : undefined
+        // Real, backend-scoped collection options (handle + title), fetched only
+        // when `category-filters` is installed and owns the collections control.
+        // An empty backend list omits the control; no option is ever fabricated.
+        const showCollections = hasFilters && filterSet.includes('collections')
+        const allCollections = showCollections
+          ? (await getCollectionOptions()).map((entry) => ({
+              id: entry.id,
+              label: entry.label,
+            }))
+          : []
+        const collections = allCollections.length > 0 ? allCollections : undefined
+        const presentation = mapCatalogResultsToFilterProps({
+          query: listing.query,
+          results: listing.results,
+          // A scoped listing (`/categories/<handle>`) must not offer the
+          // category facet: the scope already fixes the category. The root
+          // catalog passes no scope and keeps it.
+          ...(slug ? { categoryScope: slug } : {}),
+          // Product links point at the product-detail route. The runtime stays
+          // route-agnostic, so this view supplies the href builder.
+          productHref: (handle: string) => `/products/${handle}`,
+          ...(categories ? { categories } : {}),
+          ...(collections ? { collections } : {}),
+          sortOptions,
+        })
+        const activeFilters = buildActiveFilterChips(listing.query, {
+          categories: Object.fromEntries(allCategories.map((entry) => [entry.id, entry.label])),
+          collections: Object.fromEntries(allCollections.map((entry) => [entry.id, entry.label])),
+        })
+
+        return {
+          storeCategories: catalog.categories,
+          categoryEntity: resolveCategoryEntity(slug, catalog),
+          breadcrumbItems: resolveBreadcrumbItems(slug, catalog),
+          dataSource: catalog.source,
+          dataError: null,
+          categoryFilterProducts: presentation.products,
+          categoryFilterPagination: presentation.pagination,
+          categoryFilterStatus: mapCatalogOutcomeToStatus({ ok: true, results: listing.results }),
+          categoryFilterActiveFilters: activeFilters,
+          categoryFilterSearchValue: presentation.searchValue,
+          categoryFilterSelectedCategories: presentation.selectedCategories,
+          categoryFilterSelectedCollections: presentation.selectedCollections,
+          categoryFilterSelectedSort: presentation.selectedSort,
+          categoryFilterSelectedPage: presentation.selectedPage,
+          categoryFilterSelectedPageSize: presentation.selectedPageSize,
+          categoryFilterSortOptions: presentation.sortOptions ?? [],
+          categoryFilterCategories: presentation.categories ?? [],
+          categoryFilterCollections: presentation.collections ?? [],
+          categoryFilterPriceRange: presentation.priceRange,
+        }
+      } catch (error) {
+        return {
+          storeCategories: [],
+          dataSource: getDataSource(),
+          dataError: error instanceof Error ? error.message : 'No se pudo cargar la categoría.',
+          ...emptyFilterState(),
+          categoryFilterStatus: { state: 'error' as const },
+        }
+      }
+    },
+  },
+}

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

@@ -0,0 +1,23 @@
+// Thor Commerce view props: category
+// User-owned element props for the category 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.
+//
+// The listing state (products, pagination, selected query values, status) is
+// derived wiring, not copy: it is bound to `$state` in ./index.tsx from the
+// URL-backed loader. Only presentation copy lives here.
+
+import { filterContent } from './content'
+
+export const categoryFilterProps = {
+  ...filterContent,
+}
+
+// Presentational defaults for the breadcrumb; the trail itself is bound to
+// `$state` from the loader (entity-derived, never invented).
+export const categoryBreadcrumbProps = {
+  ariaLabel: 'Migas de pan',
+  backLabel: 'Volver',
+}

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

@@ -0,0 +1,122 @@
+'use client'
+
+// Thor Commerce view registry fragment: category
+// The category view's single client boundary: one controlled `CategoryFilter2`
+// (the base listing slot `category.filter`). Search/filters/sort/pagination are
+// URL-backed: the block emits a change, this registry rewrites the URL through
+// the pure `buildCategoryQueryHref` seam, and the server loader re-seeds the
+// controlled props from the new URL. No fetch and no provider call happens on
+// the client. The search and filter controls are only present because the
+// installed manifest enabled them; the block never adds a second listing.
+
+import {
+  CategoryFilter2 as CategoryFilter2Block,
+  type CategoryFilter2ActiveFilter,
+  type CategoryFilter2Filters,
+  type CategoryFilter2Props,
+} from '@thorprovider/blocks'
+import { Breadcrumb as BreadcrumbBlock } from '@thorprovider/blocks'
+import { buildCategoryQueryHref, catalogHistoryMode, type CategoryQueryChange } from '@thorprovider/runtime/commerce'
+import type { CatalogFeatureName } from '@thorprovider/runtime/contracts'
+import { useStateStore } from '@json-render/react'
+import { usePathname, useRouter } from 'next/navigation'
+import type { ViewRegistry } from '../types'
+
+// The generated view module injects the installed-feature context as an element
+// prop (task 4.11); it is composition context, not a `CategoryFilter2` prop, so
+// it is read separately from the block props.
+type CategoryFilter2RegistryProps = CategoryFilter2Props & {
+  mountedFeatures?: readonly CatalogFeatureName[]
+}
+
+export const registry: ViewRegistry = {
+  Breadcrumb: ({ props }) => {
+    const p = props as {
+      items: { label: string; href?: string }[]
+      maxItems?: number
+      ariaLabel?: string
+      backLabel?: string
+      className?: string
+    }
+    return (
+      <BreadcrumbBlock
+        items={p.items}
+        maxItems={p.maxItems}
+        ariaLabel={p.ariaLabel}
+        backLabel={p.backLabel}
+        className={p.className}
+      />
+    )
+  },
+  CategoryFilter2: ({ props, emit }) => {
+    const router = useRouter()
+    const pathname = usePathname()
+    const { set } = useStateStore()
+    const p = props as unknown as CategoryFilter2RegistryProps
+
+    // Minimal `updateURL` seam (task 6.1; task 5.2 verified the criterion and is
+    // complete): apply one change to the current browser URL and let the server
+    // loader rebuild the listing. The page reset rules live in the pure helper,
+    // not here. The installed-feature context is passed so generated navigation
+    // drops a removed feature's owned orphan parameters (task 4.11) while never
+    // dropping the base listing's route scope, `sort`, `page`, or `pageSize`.
+    //
+    // History policy (task 5.3): an intentional filter/sort/page/pageSize commit
+    // pushes a history entry so reload and back/forward restore the previous
+    // query and products; repair and the immediate per-keystroke search replace
+    // the current entry (no per-keystroke history explosion). The choice is the
+    // pure `catalogHistoryMode` seam, not ad-hoc logic here.
+    const apply = (change: CategoryQueryChange) => {
+      const search = typeof window === 'undefined' ? '' : window.location.search
+      const href = buildCategoryQueryHref(pathname, search, change, p.mountedFeatures)
+      if (catalogHistoryMode(change) === 'push') router.push(href)
+      else router.replace(href)
+    }
+
+    return (
+      <CategoryFilter2Block
+        products={p.products}
+        categories={p.categories}
+        collections={p.collections}
+        sortOptions={p.sortOptions}
+        pagination={p.pagination}
+        priceRange={p.priceRange}
+        showSearch={p.showSearch}
+        showFilters={p.showFilters}
+        showSort={p.showSort}
+        showPrice={p.showPrice}
+        searchValue={p.searchValue}
+        selectedCategories={p.selectedCategories}
+        selectedCollections={p.selectedCollections}
+        selectedSort={p.selectedSort}
+        selectedPage={p.selectedPage}
+        selectedPageSize={p.selectedPageSize}
+        selectedPriceRange={p.selectedPriceRange}
+        status={p.status}
+        activeFilters={p.activeFilters}
+        filtersTitle={p.filtersTitle}
+        searchLabel={p.searchLabel}
+        searchPlaceholder={p.searchPlaceholder}
+        sortPlaceholder={p.sortPlaceholder}
+        productsTitle={p.productsTitle}
+        onSearchChange={(text) => apply({ kind: 'search', text })}
+        onSortChange={(sort) => apply({ kind: 'sort', sort })}
+        onPageChange={(page) => apply({ kind: 'page', page })}
+        onPageSizeChange={(size) => apply({ kind: 'pageSize', pageSize: size })}
+        onFilterChange={(filters: CategoryFilter2Filters) =>
+          apply({ kind: 'filters', categories: filters.categories, collections: filters.collections ?? [] })
+        }
+        onClearFilters={() => apply({ kind: 'clearFilters' })}
+        onRepair={(remove) => apply({ kind: 'repair', remove })}
+        onRetry={() => router.refresh()}
+        onRemoveFilter={(filter: CategoryFilter2ActiveFilter) =>
+          apply({ kind: 'removeFilter', filter })
+        }
+        onProductClick={(product) => {
+          set('/lastClicked', { id: product.id })
+          emit('openProduct')
+        }}
+      />
+    )
+  },
+}

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

@@ -0,0 +1,91 @@
+// Thor Commerce view schema fragment: category
+// Zod mirror of the single controlled `CategoryFilter2` prop contract for this
+// view — the source for the catalog entry 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'
+
+export const filterProductSchema = z.object({
+  id: z.string(),
+  name: z.string(),
+  price: z.string(),
+  image: z.string().optional(),
+  // Product-detail link supplied by the presentation layer; when absent the
+  // block falls back to its onClick path.
+  href: z.string().optional(),
+})
+
+export const categoryFilterSortOptionSchema = z.object({
+  value: z.string(),
+  label: z.string(),
+})
+
+export const categoryFilterOptionSchema = z.object({
+  id: z.string(),
+  label: z.string(),
+})
+
+export const categoryFilterActiveFilterSchema = z.object({
+  id: z.string(),
+  kind: z.string(),
+  label: z.string(),
+  params: z.array(z.string()),
+  value: z.string().optional(),
+})
+
+export const categoryFilterPriceRangeSchema = z.object({
+  min: z.number(),
+  max: z.number(),
+  step: z.number(),
+})
+
+export const categoryFilterStatusSchema = z.object({ state: z.string() }).catchall(z.unknown())
+
+export const categoryFilterPropsSchema = z
+  .object({
+    products: z.array(filterProductSchema),
+    pagination: z.array(z.union([z.number(), z.string()])),
+    status: categoryFilterStatusSchema,
+    activeFilters: z.array(categoryFilterActiveFilterSchema),
+    searchValue: z.string(),
+    selectedCategories: z.array(z.string()),
+    selectedCollections: z.array(z.string()),
+    selectedSort: z.string(),
+    selectedPage: z.union([z.number(), z.string()]),
+    selectedPageSize: z.union([z.number(), z.string()]),
+    selectedPriceRange: z.array(z.number()).optional(),
+    sortOptions: z.array(categoryFilterSortOptionSchema),
+    categories: z.array(categoryFilterOptionSchema),
+    collections: z.array(categoryFilterOptionSchema),
+    priceRange: categoryFilterPriceRangeSchema.optional(),
+    showSearch: z.boolean(),
+    showFilters: z.boolean(),
+    showSort: z.boolean(),
+    showPrice: z.boolean().optional(),
+    filtersTitle: z.string().optional(),
+    searchLabel: z.string().optional(),
+    searchPlaceholder: z.string().optional(),
+    sortPlaceholder: z.string().optional(),
+    productsTitle: z.string().optional(),
+  })
+  .catchall(z.unknown())
+
+export const breadcrumbItemSchema = z.object({
+  label: z.string(),
+  href: z.string().optional(),
+})
+
+export const breadcrumbPropsSchema = z.object({
+  items: z.array(breadcrumbItemSchema),
+  maxItems: z.number().int().min(2).optional(),
+  ariaLabel: z.string().optional(),
+  backLabel: z.string().optional(),
+  className: z.string().optional(),
+})
+
+export type CategoryFilterProps = z.infer<typeof categoryFilterPropsSchema>

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,
+  }
+}