@thorprovider/storefront 0.3.1 → 0.4.0-mvp.2

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

@@ -0,0 +1,52 @@
+// Thor Commerce view schema fragment: cart
+// Zod mirrors of the block contracts for this view — the single 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'
+
+// Canonical Money: a decimal string in major units ("69.99"), never cents.
+const moneySchema = z.object({
+  amount: z.string(),
+  currencyCode: z.string(),
+})
+
+// Mirrors CartLineState: `id` is the backend line-item id used for absolute
+// updates and removal; `lineTotal`/`unitPrice` are the authoritative backend
+// amounts. An absent image stays absent (never serialized as "").
+export const cartLineSchema = z.object({
+  id: z.string(),
+  merchandiseId: z.string(),
+  name: z.string(),
+  variant: z.string().optional(),
+  quantity: z.number(),
+  lineTotal: moneySchema,
+  unitPrice: moneySchema.optional(),
+  image: z.string().optional(),
+  handle: z.string().optional(),
+})
+
+// Mirrors CartTotalsState: backend-authoritative totals rendered verbatim.
+export const cartTotalsSchema = z.object({
+  subtotal: moneySchema,
+  discount: moneySchema.optional(),
+  tax: moneySchema.optional(),
+  shipping: moneySchema.optional(),
+  total: moneySchema,
+})
+
+export const cartViewPropsSchema = z.object({
+  items: z.array(cartLineSchema),
+  totals: cartTotalsSchema.nullish(),
+  titleLabel: z.string().optional(),
+  checkoutLabel: z.string().optional(),
+  continueShoppingLabel: z.string().optional(),
+  emptyLabel: z.string().optional(),
+  readErrorLabel: z.string().optional(),
+})
+
+export type CartViewProps = z.infer<typeof cartViewPropsSchema>

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

@@ -0,0 +1,29 @@
+{
+  "view": "category",
+  "slots": [
+    { "id": "category.breadcrumb", "slot": "breadcrumb", "default": "Breadcrumb" },
+    { "id": "category.filter", "slot": "filter", "default": "CategoryFilter2" },
+    {
+      "id": "category.productCard",
+      "slot": "productCard",
+      "default": "ProductCard1",
+      "nested": true
+    }
+  ],
+  "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/category/assembly/index.skeleton.tsx

@@ -0,0 +1,251 @@
+// 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'@@SECTION_IMPORTS@@
+
+// 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> = {
+@@ELEMENTS@@
+}
+
+const catalog = {
+@@CATALOG@@
+}
+
+/** 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', [@@SLOT_IDS@@], 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/assembly/registry.skeleton.tsx

@@ -0,0 +1,34 @@
+'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'
+@@BLOCK_IMPORTS@@@@SECTION_REGISTRY_IMPORTS@@
+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 = {
+@@REGISTRY@@
+}

package/assets/templates/views/category/assembly/slots/breadcrumb/Breadcrumb/binding.json

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

package/assets/templates/views/category/assembly/slots/breadcrumb/Breadcrumb/catalog.part

@@ -0,0 +1,4 @@
+  Breadcrumb: {
+    props: breadcrumbPropsSchema,
+    description: 'Migas de pan derivadas de la jerarquía real de categorías.',
+  },

package/assets/templates/views/category/assembly/slots/breadcrumb/Breadcrumb/element.part

@@ -0,0 +1,7 @@
+  'category.breadcrumb': {
+    type: 'Breadcrumb',
+    props: {
+      ...categoryBreadcrumbProps,
+      items: { $state: '/breadcrumbItems' },
+    },
+  },

package/assets/templates/views/category/assembly/slots/breadcrumb/Breadcrumb/registry.part

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

package/assets/templates/views/category/assembly/slots/filter/CategoryFilter2/catalog.part

@@ -0,0 +1,5 @@
+  CategoryFilter2: {
+    props: categoryFilterPropsSchema,
+    description:
+      'Listado de categoría: una sola presentación controlada CategoryFilter2 con productos, paginación, búsqueda y filtros opcionales.',
+  },

package/assets/templates/views/category/assembly/slots/filter/CategoryFilter2/element.part

@@ -0,0 +1,34 @@
+  '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' },
+    },
+  },

package/assets/templates/views/category/assembly/slots/filter/CategoryFilter2/registry.part

@@ -0,0 +1,71 @@
+  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/content.ts

@@ -0,0 +1,30 @@
+// Thor Commerce view content: category
+// User-owned view content — listing copy for the single controlled
+// `CategoryFilter2`. 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.
+//
+// The sort OPTIONS are not listed here: they come from the adapter-advertised
+// set (`getCatalogSortKeys`), never from assumed global price sorts.
+
+export const filterContent = {
+  filtersTitle: 'Filtros',
+  searchLabel: 'Buscar',
+  searchPlaceholder: 'Buscar productos',
+  sortPlaceholder: 'Ordenar por',
+  productsTitle: 'Productos',
+  emptyTitle: 'Sin resultados',
+  emptyDescription: 'Ningún producto coincide con los filtros activos.',
+  clearFiltersLabel: 'Limpiar filtros',
+}
+
+/**
+ * Editorial section instance content, keyed by the section instance id the
+ * manifest persists (`views[].sections[].id`, e.g. `category-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/category/data.ts

@@ -0,0 +1,12 @@
+// Thor Commerce view data: category
+// User-owned loader shaping for the category 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 selectCategoryProducts<T>(
+  all: readonly T[],
+  scoped: readonly T[] | null,
+): T[] {
+  return scoped ? [...scoped] : [...all]
+}