@thorprovider/storefront 0.3.1 → 0.4.0-mvp.2

package/assets/templates/app/lib/__STOREFRONT__/state.core.ts

@@ -0,0 +1,257 @@
+// Generated by Thor Commerce storefront (composition core: state)
+// Shared, feature-independent storefront state. Installed features add their
+// own slices; `state.ts` (the composer) spreads them over `storefrontCoreState`.
+//
+// The cart slice mirrors the backend-authoritative projection: line totals and
+// cart totals are canonical `Money` from the backend, never locally computed.
+
+import type {
+  CardProduct,
+  FeaturedProduct,
+  ProductCategory2Category,
+  ProductDetailProduct,
+} from '@thorprovider/blocks'
+import type { Money, PaymentMethod } from '@thorprovider/types'
+
+/** Real review, rendered only when the backend supplies it. */
+export interface ProductReview {
+  id: number
+  userName: string
+  userAvatar?: string
+  date: string
+  rating: number
+  content: string
+  likes?: number
+  comments?: number
+}
+
+/** A cart line projected from the backend cart. */
+export interface CartLineState {
+  /** Backend cart line-item id — the update/removal identity. */
+  id: string
+  /** Backend variant id — the add identity (carried for line updates). */
+  merchandiseId: string
+  name: string
+  variant?: string
+  quantity: number
+  /** Backend line total; rendered verbatim, never `unit × qty` locally. */
+  lineTotal: Money
+  /** Backend unit price, when supplied; never derived from `lineTotal / qty`. */
+  unitPrice?: Money
+  /** Normalized optional image; omitted when the backend supplies none. */
+  image?: string
+  handle?: string
+}
+
+/** Backend-authoritative cart totals. */
+export interface CartTotalsState {
+  subtotal: Money
+  discount?: Money
+  tax?: Money
+  shipping?: Money
+  total: Money
+}
+
+/** Mirrors the CheckoutForm1FormData block contract (card fields stay unused). */
+export interface CheckoutFormData {
+  email: string
+  firstName: string
+  lastName: string
+  phone: string
+  address: string
+  city: string
+  state: string
+  zipCode: string
+  country: string
+  paymentMethod: string
+  cardNumber: string
+  expiryDate: string
+  cvv: string
+  cardName: string
+  saveInfo: boolean
+  sameAsBilling: boolean
+  newsletter: boolean
+  promoCode: string
+}
+
+/** An eligible backend shipping option. */
+export interface CheckoutShippingOption {
+  id: string
+  name: string
+  price?: Money
+  description?: string
+  estimatedDays?: string
+}
+
+/** Structured per-field checkout errors, mirroring the block contract. */
+export type CheckoutFieldErrors = Record<string, { message?: string }[]>
+
+/** Confirmation order, mirroring the CheckoutConfirmation block contract. */
+export interface StorefrontOrder {
+  number: string
+  placedAt: string
+  email?: string
+  currentStage?: 'Confirmed' | 'Packed' | 'Shipped' | 'Delivered'
+  estimatedDelivery?: string | null
+  trackingHref?: string
+  shipping?: { name: string; lines: string[]; method?: string }
+  billing?: { name: string; lines: string[]; method?: string }
+  totals: { subtotal?: Money; discount?: Money; shipping?: Money; tax?: Money; total?: Money }
+}
+
+/** Confirmation line: backend Money line total, optional image omitted when absent. */
+export interface StorefrontOrderLineView {
+  id: string
+  name: string
+  variant?: string
+  quantity: number
+  lineTotal: Money
+  unitPrice?: Money
+  image?: string
+}
+
+/** A single line of a customer order-history row (display strings, no Money). */
+export interface AccountOrderItemView {
+  id: string
+  name: string
+  variant?: string
+  quantity: number
+  lineTotal: string
+  image?: string
+}
+
+/**
+ * A customer order-history row, mapped from the backend order for the account
+ * view. Money is formatted to a display string from the order's own currency;
+ * an optional field the backend omits is omitted, never invented.
+ */
+export interface AccountOrderView {
+  id: string
+  number: string
+  date: string
+  status: string
+  total: string
+  subtotal?: string
+  tax?: string
+  shipping?: string
+  address?: string
+  items: AccountOrderItemView[]
+}
+
+/**
+ * The completed-order receipt as ONE atomic value.
+ *
+ * Order and its backend lines live together so a single state write carries
+ * them, and the SSR initial value is a stable `null`. json-render's
+ * StateProvider re-applies the SSR `initialState` on every RSC refresh and
+ * updates any key whose flattened initial value changed by reference; a
+ * separate `lastOrderLines: []` array would be reset to a fresh empty array
+ * after a Server Action, dropping the backend lines. A single nullable object
+ * keeps the receipt out of that re-apply.
+ */
+export interface StorefrontReceipt {
+  order: StorefrontOrder
+  lines: StorefrontOrderLineView[]
+}
+
+export interface NavCategory {
+  label: string
+  href: string
+  children?: { label: string; href: string }[]
+  emphasis?: boolean
+}
+
+export type OrderStatus = 'idle' | 'pending' | 'error' | 'unresolved' | 'complete'
+
+export interface StorefrontCoreState {
+  heroProducts: FeaturedProduct[]
+  categories: ProductCategory2Category[]
+  navCategories: NavCategory[]
+  categoryProducts: CardProduct[]
+  /** Canonical product detail: real variants, options, availability, and Money. */
+  selectedProduct: ProductDetailProduct | null
+  /** Explicitly selected backend variant id; null until the shopper selects one. */
+  selectedVariantId: string | null
+  /** Requested add-to-cart quantity for the selected variant. */
+  productQuantity: number
+  /** Real reviews, supplied by the backend only. */
+  productReviews: ProductReview[]
+  hasProductReviews: boolean
+  lastClicked: CardProduct | null
+  lastCategory: string | null
+  bannerDismissed: boolean
+  /** True when the explicit data-source / error notice has been dismissed. */
+  dataNoticeDismissed: boolean
+  /** Explicit data source; `'mock'` is always labelled as demo data. */
+  dataSource: 'mock' | 'medusa'
+  /** Visible real-mode failure; null when the data loaded. */
+  dataError: string | null
+  cartOpen: boolean
+  // ---- cart (backend-authoritative) ----
+  cart: CartLineState[]
+  cartTotals: CartTotalsState | null
+  cartId: string | null
+  cartQuantity: number
+  cartCompleted: boolean
+  /** True when the verified session carries a completed receipt to recover. */
+  receiptAvailable: boolean
+  cartPending: boolean
+  cartError: string | null
+  /** Recovery/notice message (for example an unresolved completion). */
+  cartNotice: string | null
+  /** Shipping OPTION id (`so_`) the checkout UI selects/highlights. */
+  cartSelectedShippingOptionId: string | null
+  /** Visible backend cart-read failure; null when the cart read succeeded. */
+  cartReadError: string | null
+}
+
+/** Full storefront state: core plus the checkout feature's slice. */
+export interface StorefrontState extends StorefrontCoreState {
+  checkout: CheckoutFormData
+  checkoutCountries: { value: string; label: string }[]
+  checkoutPaymentMethods: PaymentMethod[]
+  checkoutShippingOptions: CheckoutShippingOption[]
+  checkoutSelectedShippingOptionId: string | null
+  checkoutFieldErrors: CheckoutFieldErrors
+  checkoutPending: boolean
+  checkoutError: string | null
+  /**
+   * The completion discriminator behind `checkoutError`, preserved separately
+   * from `orderStatus`: a native cart-with-error (`cart-error`), a definite
+   * pre-completion failure (`error`), or an ambiguous completion (`unresolved`).
+   */
+  checkoutErrorKind: 'error' | 'cart-error' | 'unresolved' | null
+  /** Atomic completed-order receipt (order + backend lines), stable-null initial. */
+  lastReceipt: StorefrontReceipt | null
+  orderStatus: OrderStatus
+}
+
+export const storefrontCoreState: StorefrontCoreState = {
+  heroProducts: [],
+  categories: [],
+  navCategories: [],
+  categoryProducts: [],
+  selectedProduct: null,
+  selectedVariantId: null,
+  productQuantity: 1,
+  productReviews: [],
+  hasProductReviews: false,
+  lastClicked: null,
+  lastCategory: null,
+  bannerDismissed: false,
+  dataNoticeDismissed: false,
+  dataSource: 'mock',
+  dataError: null,
+  cartOpen: false,
+  cart: [],
+  cartTotals: null,
+  cartId: null,
+  cartQuantity: 0,
+  cartCompleted: false,
+  receiptAvailable: false,
+  cartPending: false,
+  cartError: null,
+  cartNotice: null,
+  cartSelectedShippingOptionId: null,
+  cartReadError: null,
+}

package/assets/templates/app/lib/__STOREFRONT__/state.ts

@@ -1,35 +1,11 @@
-// Generated by Thor Commerce storefront (template: assets/templates/app/lib/__STOREFRONT__/state.ts)
-// Initial storefront state. Extended by recipes as views are added.
+// Generated by Thor Commerce storefront (composition composer: state).
+// Do not edit by hand — the manifest is the source of truth; run `storefront sync`.
+// Installed features contribute their state slices below.
 
-import type { CardProduct, ProductCategory2Category } from '@thorprovider/blocks'
+import { storefrontCoreState } from './state.core'
 
-export interface StoreOverviewProduct {
-  id: string
-  brand: string
-  name: string
-  description: string
-  price: number
-  currency: string
-  rating: number
-  images: { id: number; src: string; alt: string }[]
-  sizes: number[]
-  colors: { name: string; value: string }[]
-}
-
-export interface StorefrontState {
-  heroProducts: CardProduct[]
-  categories: ProductCategory2Category[]
-  selectedProduct: StoreOverviewProduct | null
-  lastClicked: CardProduct | null
-  lastCategory: string | null
-  bannerDismissed: boolean
-}
+export * from './state.core'
 
-export const storefrontInitialState: StorefrontState = {
-  heroProducts: [],
-  categories: [],
-  selectedProduct: null,
-  lastClicked: null,
-  lastCategory: null,
-  bannerDismissed: false,
+export const storefrontInitialState = {
+  ...storefrontCoreState,
 }

package/assets/templates/app/lib/__STOREFRONT__/store-context.ts

@@ -0,0 +1,161 @@
+// Generated by Thor Commerce storefront (template: assets/templates/app/lib/__STOREFRONT__/store-context.ts)
+//
+// Host store context — the explicit single-store configuration the generated
+// store runs on. It is resolved and validated from the host environment BEFORE
+// any commerce call, so an incomplete or invalid configuration fails visibly
+// instead of silently falling back to demo data.
+//
+// Boundary: this module is server-only and reads no Next.js or React API. It
+// owns the environment contract; the commerce bridge owns the backend calls.
+//
+// The values are the multitenancy seam: a future tenancy layer varies
+// storeId/channel/region/currency without redefining the commerce shapes. In
+// real mode the currency is NEVER hardcoded — it comes from the host
+// environment; mock mode resolves a labelled fixture context so the store runs
+// with no environment configured at all.
+
+import type { StoreContext } from '@thorprovider/types'
+import { storeContextSchema } from '@thorprovider/runtime/contracts'
+
+/** Data source selected explicitly by the host; never inferred from a failure. */
+export type StoreDataSource = 'mock' | 'medusa'
+
+/** Host environment variable names that make up the store context. */
+export const STORE_CONTEXT_ENV = {
+  storeId: 'THOR_STORE_ID',
+  salesChannelId: 'MEDUSA_SALES_CHANNEL_ID',
+  regionId: 'MEDUSA_REGION_ID',
+  currencyCode: 'MEDUSA_CURRENCY_CODE',
+} as const
+
+/** Real-mode backend configuration required before any provider call. */
+export const BACKEND_ENV = {
+  baseUrl: 'MEDUSA_BASE_URL',
+  publishableKey: 'MEDUSA_PUBLISHABLE_KEY',
+} as const
+
+/** Host environment variable that selects mock vs real mode. */
+export const DATA_SOURCE_ENV = 'THOR_DATA_SOURCE'
+
+/**
+ * Host environment variable with the canonical public origin of the store
+ * (used for `metadataBase`, `robots.txt`, and `sitemap.xml`). Optional: when
+ * unset or invalid no absolute URL is invented.
+ */
+export const SITE_URL_ENV = 'THOR_SITE_URL'
+
+/**
+ * Visible configuration failure. Thrown before commerce so a missing or invalid
+ * store context surfaces as an error instead of fictional data.
+ */
+export class StoreConfigError extends Error {
+  readonly code = 'STOREFRONT_CONFIG_ERROR'
+  constructor(message: string) {
+    super(message)
+    this.name = 'StoreConfigError'
+  }
+}
+
+/**
+ * The explicitly selected data source. Defaults to `mock` (the safe, offline,
+ * explicitly labelled mode) so a store never silently talks to a half-configured
+ * backend; real mode must be selected on purpose.
+ */
+export function getDataSource(): StoreDataSource {
+  return process.env[DATA_SOURCE_ENV] === 'medusa' ? 'medusa' : 'mock'
+}
+
+/** True when the host explicitly selected real (Medusa) mode. */
+export function isRealMode(): boolean {
+  return getDataSource() === 'medusa'
+}
+
+/**
+ * Normalise a configured site URL to its origin (`https://example.com`), or
+ * `undefined` when it is absent, blank, not a valid URL, or not http(s). Pure
+ * and total: it never throws, so an invalid value degrades to "no site URL"
+ * instead of failing the build.
+ */
+export function parseSiteUrl(value: string | undefined): string | undefined {
+  if (typeof value !== 'string' || value.trim() === '') return undefined
+  try {
+    const url = new URL(value)
+    if (url.protocol !== 'http:' && url.protocol !== 'https:') return undefined
+    return url.origin
+  } catch {
+    return undefined
+  }
+}
+
+/** The canonical public origin from the host environment, or `undefined`. */
+export function getSiteUrl(): string | undefined {
+  return parseSiteUrl(process.env[SITE_URL_ENV])
+}
+
+/**
+ * Fixture context resolved in mock mode. It satisfies `storeContextSchema` and
+ * mirrors the values the bundled mock provider serves, so a store with no
+ * environment configured still has a valid context to render and operate its
+ * cart against. It is a labelled fixture, never a real backend identity.
+ */
+export const MOCK_STORE_CONTEXT: StoreContext = {
+  storeId: 'mock-store',
+  salesChannelId: 'mock-sales-channel',
+  regionId: 'mock-region-us',
+  currencyCode: 'USD',
+}
+
+function requireEnv(name: string): string {
+  const value = process.env[name]
+  if (typeof value !== 'string' || value.trim() === '') {
+    throw new StoreConfigError(
+      `Missing required environment variable ${name}. Set it in the host environment before the store can resolve its context.`,
+    )
+  }
+  return value
+}
+
+/**
+ * Resolve and validate the single-store context.
+ *
+ * Mock mode returns the labelled fixture context and reads no environment
+ * variables, so a created store runs with no configuration. Real mode resolves
+ * the four variables from the host environment and validates them through the
+ * shared runtime schema, so an invalid context is rejected before any commerce
+ * call. Throws `StoreConfigError` naming the missing variable — never a secret
+ * value.
+ */
+export function getStoreContext(): StoreContext {
+  if (!isRealMode()) return MOCK_STORE_CONTEXT
+  const candidate = {
+    storeId: requireEnv(STORE_CONTEXT_ENV.storeId),
+    salesChannelId: requireEnv(STORE_CONTEXT_ENV.salesChannelId),
+    regionId: requireEnv(STORE_CONTEXT_ENV.regionId),
+    currencyCode: requireEnv(STORE_CONTEXT_ENV.currencyCode),
+  }
+  const parsed = storeContextSchema.safeParse(candidate)
+  if (!parsed.success) {
+    const issues = parsed.error.issues
+      .map((issue) => `${issue.path.join('.') || 'context'}: ${issue.message}`)
+      .join('; ')
+    throw new StoreConfigError(`Invalid store context: ${issues}`)
+  }
+  return parsed.data
+}
+
+/**
+ * Assert that real-mode backend configuration is present before any provider
+ * call. Mock mode needs no backend. Throws `StoreConfigError` (never printing a
+ * key value) so a misconfigured real store fails visibly.
+ */
+export function assertBackendConfigured(source: StoreDataSource = getDataSource()): void {
+  if (source !== 'medusa') return
+  const missing: string[] = []
+  if (!process.env[BACKEND_ENV.baseUrl]?.trim()) missing.push(BACKEND_ENV.baseUrl)
+  if (!process.env[BACKEND_ENV.publishableKey]?.trim()) missing.push(BACKEND_ENV.publishableKey)
+  if (missing.length > 0) {
+    throw new StoreConfigError(
+      `THOR_DATA_SOURCE=medusa requires ${missing.join(', ')}. Configure the backend or select THOR_DATA_SOURCE=mock explicitly.`,
+    )
+  }
+}

package/assets/templates/app/lib/__STOREFRONT__/views/sections/cta.client.tsx

@@ -0,0 +1,25 @@
+'use client'
+
+// Optional section fragment: cta (mirrors recipes/sections.json) — client registry.
+// The matching server-side catalog lives in cta.tsx. @thorprovider/blocks ships a
+// 'use client' boundary, but this fragment keeps the explicit client boundary so
+// the section composes identically in any consumer graph.
+
+import { CtaSection1 as CtaBlock } from '@thorprovider/blocks'
+import { ctaSection1PropsSchema } from './schema.cta'
+import type { ViewRegistry } from '../types'
+
+export const ctaRegistry: ViewRegistry = {
+  Cta: ({ props }) => {
+    const parsed = ctaSection1PropsSchema.parse(props)
+    return (
+      <CtaBlock
+        badgeText={parsed.badgeText}
+        title={parsed.title}
+        description={parsed.description}
+        primaryCta={parsed.primaryCta}
+        secondaryCta={parsed.secondaryCta}
+      />
+    )
+  },
+}

package/assets/templates/app/lib/__STOREFRONT__/views/sections/cta.tsx

@@ -0,0 +1,16 @@
+// Optional section fragment: cta (mirrors recipes/sections.json)
+// Server-side part: element type + zod catalog entry. The component mappings
+// live in cta.client.tsx ('use client') and are composed via composeSections.
+
+import { ctaSection1PropsSchema } from './schema.cta'
+
+export const ctaSection = {
+  elementType: 'Cta',
+  catalog: {
+    Cta: {
+      props: ctaSection1PropsSchema,
+      description: 'Call-to-action banner with optional primary and secondary links.',
+    },
+  },
+  registryModule: './cta.client',
+}

package/assets/templates/app/lib/__STOREFRONT__/views/sections/faq.client.tsx

@@ -0,0 +1,24 @@
+'use client'
+
+// Optional section fragment: faq (mirrors recipes/sections.json) — client registry.
+// The matching server-side catalog lives in faq.tsx. @thorprovider/blocks ships a
+// 'use client' boundary, but this fragment keeps the explicit client boundary so
+// the section composes identically in any consumer graph.
+
+import { FaqBlock1 as FaqBlock } from '@thorprovider/blocks'
+import { faqPropsSchema } from './schema.faq'
+import type { ViewRegistry } from '../types'
+
+export const faqRegistry: ViewRegistry = {
+  Faq: ({ props }) => {
+    const parsed = faqPropsSchema.parse(props)
+    return (
+      <FaqBlock
+        title={parsed.title ?? 'Preguntas frecuentes'}
+        description={parsed.description}
+        items={parsed.items}
+        accordionType={parsed.accordionType ?? 'single'}
+      />
+    )
+  },
+}

package/assets/templates/app/lib/__STOREFRONT__/views/sections/faq.tsx

@@ -1,29 +1,16 @@
 // Optional section fragment: faq (mirrors recipes/sections.json)
+// Server-side part: element type + zod catalog entry. The component mappings
+// live in faq.client.tsx ('use client') and are composed via composeSections.
 
-import { FaqBlock1 as FaqBlock } from '@thorprovider/blocks'
-import { z } from 'zod'
+import { faqPropsSchema } from './schema.faq'
 
 export const faqSection = {
   elementType: 'Faq',
   catalog: {
     Faq: {
-      props: z.object({
-        title: z.string().optional(),
-        description: z.string().optional(),
-        items: z.array(z.record(z.string(), z.unknown())),
-        accordionType: z.enum(['single', 'multiple']).optional(),
-      }),
+      props: faqPropsSchema,
       description: 'Frequently asked questions accordion.',
     },
   },
-  registry: {
-    Faq: ({ props }: { props: Record<string, unknown> }) => (
-      <FaqBlock
-        title={(props.title as string) ?? 'Preguntas frecuentes'}
-        description={props.description as string}
-        items={props.items as never}
-        accordionType={(props.accordionType as 'single' | 'multiple') ?? 'single'}
-      />
-    ),
-  },
+  registryModule: './faq.client',
 }

package/assets/templates/app/lib/__STOREFRONT__/views/sections/index.ts

@@ -0,0 +1,18 @@
+// Section catalog composition. Each section fragment is a server-side part
+// (element type + zod catalog entry); this module merges their catalogs the same
+// way `catalog.ts` merges view catalogs, so the generated storefront catalog can
+// advertise the editorial element types. A fragment's client registry is
+// addressed by its `registryModule` and never imported here, so the server
+// catalog never pulls the React graph.
+
+import type { ViewCatalogEntry } from '../types'
+import { ctaSection } from './cta'
+import { faqSection } from './faq'
+import { productsSection } from './products'
+
+export const sectionModules = [faqSection, ctaSection, productsSection] as const
+
+export const sectionCatalog: Record<string, ViewCatalogEntry> = Object.assign(
+  {},
+  ...sectionModules.map((section) => section.catalog),
+)

package/assets/templates/app/lib/__STOREFRONT__/views/sections/logoCloud.tsx

@@ -3,27 +3,39 @@
 import { LogoCloud1 as LogoCloudBlock } from '@thorprovider/blocks'
 import { z } from 'zod'
 
+// Mirrors the LogoCloud1Platform/LogoCloud1Props block contracts. `id` is a
+// simple-icons slug resolved internally by the block.
+const logoCloudPlatformSchema = z.object({
+  name: z.string(),
+  id: z.string(),
+})
+
+const logoCloudPropsSchema = z.object({
+  title: z.string().optional(),
+  description: z.string().optional(),
+  moreLabel: z.string().optional(),
+  platforms: z.array(logoCloudPlatformSchema),
+})
+
 export const logoCloudSection = {
   elementType: 'LogoCloud',
   catalog: {
     LogoCloud: {
-      props: z.object({
-        title: z.string().optional(),
-        description: z.string().optional(),
-        moreLabel: z.string().optional(),
-        platforms: z.array(z.record(z.string(), z.unknown())),
-      }),
+      props: logoCloudPropsSchema,
       description: 'Brand or partner logo strip.',
     },
   },
   registry: {
-    LogoCloud: ({ props }: { props: Record<string, unknown> }) => (
-      <LogoCloudBlock
-        title={(props.title as string) ?? 'Marcas que confían en nosotros'}
-        description={props.description as string}
-        moreLabel={props.moreLabel as string}
-        platforms={props.platforms as never}
-      />
-    ),
+    LogoCloud: ({ props }: { props: Record<string, unknown> }) => {
+      const parsed = logoCloudPropsSchema.parse(props)
+      return (
+        <LogoCloudBlock
+          title={parsed.title ?? 'Marcas que confían en nosotros'}
+          description={parsed.description}
+          moreLabel={parsed.moreLabel}
+          platforms={parsed.platforms}
+        />
+      )
+    },
   },
 }