@thorprovider/storefront 0.3.1 → 0.4.0-mvp.0

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

@@ -0,0 +1,165 @@
+'use client'
+
+// Generated by Thor Commerce storefront (composition core: handlers)
+// Core json-render action handlers, independent of any feature. Installed
+// features register their own handlers; `handlers.ts` (the composer) calls both.
+//
+// Cart handlers call the Server Actions (never mutate the cart locally) and
+// write the backend-authoritative snapshot back into state. Payloads the blocks
+// emit are preserved: adds carry the selected backend variant id and quantity,
+// cart updates/removals carry the backend line-item id, and the Navbar delta is
+// normalized against the authoritative line in the action.
+
+import { useEffect } from 'react'
+import { useActions, useStateStore } from '@json-render/react'
+import { useNextApp } from '@json-render/next'
+import {
+  addToCartAction,
+  applyQuantityDeltaAction,
+  ensureCartAction,
+  loadCartStateAction,
+  removeLineAction,
+  setLineQuantityAction,
+} from './actions'
+import type { CartStatePatch } from './commerce'
+
+/** A product-like object the views leave in `/lastClicked` (card/hero shortcut). */
+interface ClickedProduct {
+  id?: string | number
+}
+
+/** The explicit add-to-cart payload the product overview emits. */
+interface AddToCartPayload {
+  variantId: string
+  quantity: number
+}
+
+export function useCoreHandlers() {
+  const { get, set } = useStateStore()
+  const { navigate } = useNextApp()
+  const { registerHandler } = useActions()
+
+  useEffect(() => {
+    const applyCart = (patch: CartStatePatch) => {
+      set('/cart', patch.cart)
+      set('/cartTotals', patch.cartTotals)
+      set('/cartId', patch.cartId)
+      set('/cartQuantity', patch.cartQuantity)
+      set('/cartCompleted', patch.cartCompleted)
+      set('/cartSelectedShippingOptionId', patch.cartSelectedShippingOptionId)
+      set('/checkoutSelectedShippingOptionId', patch.cartSelectedShippingOptionId)
+      set('/cartError', null)
+      set('/cartReadError', null)
+      set('/cartPending', false)
+    }
+    const fail = (error: string) => {
+      set('/cartError', error)
+      set('/cartPending', false)
+    }
+    const begin = () => {
+      set('/cartPending', true)
+      set('/cartError', null)
+      set('/cartNotice', null)
+    }
+    // A rejected Server Action (network/RPC) must clear pending and surface a
+    // message; never swallow it. Only a non-secret context line is logged.
+    const onError = (scope: string) => (error: unknown) => {
+      console.error(
+        `[storefront/handlers] ${scope} failed`,
+        error instanceof Error ? error.message : error,
+      )
+      fail('No se pudo completar la operación. Inténtalo de nuevo.')
+    }
+
+    const handlers: Record<string, () => void> = {
+      addToCart: () => {
+        const payload = get('/lastAddToCart') as AddToCartPayload | null
+        if (!payload?.variantId) return
+        begin()
+        void addToCartAction({ variantId: payload.variantId, quantity: payload.quantity })
+          .then((result) => {
+            if (result.ok) {
+              applyCart(result.cart)
+              set('/cartOpen', true)
+            } else fail(result.error)
+          })
+          .catch(onError('addToCart'))
+      },
+      ensureCart: () => {
+        begin()
+        void ensureCartAction()
+          .then((result) => {
+            if (result.ok) applyCart(result.cart)
+            else fail(result.error)
+          })
+          .catch(onError('ensureCart'))
+      },
+      refreshCart: () => {
+        void loadCartStateAction().then(applyCart).catch(onError('refreshCart'))
+      },
+      updateQuantity: () => {
+        const { id, merchandiseId, quantity } = (get('/qtyUpdate') ?? {}) as {
+          id?: string
+          merchandiseId?: string
+          quantity?: number
+        }
+        if (!id || !merchandiseId || quantity == null) return
+        begin()
+        void setLineQuantityAction({ lineId: id, merchandiseId, quantity })
+          .then((result) => {
+            if (result.ok) applyCart(result.cart)
+            else fail(result.error)
+          })
+          .catch(onError('updateQuantity'))
+      },
+      applyQuantityDelta: () => {
+        const { id, delta } = (get('/qtyDelta') ?? {}) as { id?: string; delta?: number }
+        if (!id || delta == null) return
+        begin()
+        void applyQuantityDeltaAction({ lineId: id, delta })
+          .then((result) => {
+            if (result.ok) applyCart(result.cart)
+            else fail(result.error)
+          })
+          .catch(onError('applyQuantityDelta'))
+      },
+      removeFromCart: () => {
+        const id = get('/lastRemoved') as string | null
+        if (!id) return
+        begin()
+        void removeLineAction({ lineId: id })
+          .then((result) => {
+            if (result.ok) applyCart(result.cart)
+            else fail(result.error)
+          })
+          .catch(onError('removeFromCart'))
+      },
+      openCart: () => set('/cartOpen', true),
+      closeCart: () => set('/cartOpen', false),
+      dismissBanner: () => set('/bannerDismissed', true),
+      dismissDataNotice: () => set('/dataNoticeDismissed', true),
+      openProduct: () => {
+        const product = get('/lastClicked') as ClickedProduct | null
+        if (!product?.id) return
+        navigate(`/productos/${product.id}`)
+      },
+      openCategory: () => {
+        const handle = get('/lastCategory') as string | null
+        navigate(handle ? `/categorias/${handle}` : '/categorias')
+      },
+      goHome: () => {
+        set('/cartOpen', false)
+        navigate('/')
+      },
+      goToCart: () => set('/cartOpen', true),
+      submitReview: () => {},
+      toggleReviewLike: () => {},
+    }
+
+    for (const [name, handler] of Object.entries(handlers)) {
+      registerHandler(name, handler)
+    }
+    // registerHandler uses functional state updates; store/navigate captured once.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [])
+}

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

@@ -1,42 +1,11 @@
 'use client'
 
-// Generated by Thor Commerce storefront (template: assets/templates/app/lib/__STOREFRONT__/handlers.ts)
-// Registers json-render action handlers. Recipe-added views extend this file.
+// Generated by Thor Commerce storefront (composition composer: handlers).
+// Do not edit by hand — the manifest is the source of truth; run `storefront sync`.
+// Installed features contribute their handlers below.
 
-import { useEffect } from 'react'
-import { useActions, useStateStore } from '@json-render/react'
-import { useNextApp } from '@json-render/next'
+import { useCoreHandlers } from './handlers.core'
 
 export function useStorefrontHandlers() {
-  const { set } = useStateStore()
-  const { navigate } = useNextApp()
-  const { registerHandler } = useActions()
-
-  useEffect(() => {
-    const handlers: Record<string, () => void> = {
-      addToCart: () => {},
-      openCart: () => {},
-      openProduct: () => navigate('/productos'),
-      openCategory: () => {
-        const handle = ''
-        navigate(handle ? `/categorias/${handle}` : '/categorias')
-      },
-      goHome: () => navigate('/'),
-      applyFilters: () => {},
-      placeOrder: () => navigate('/checkout'),
-      continueShopping: () => navigate('/'),
-      viewOrder: () => {},
-      downloadInvoice: () => {},
-      submitReview: () => {},
-      toggleReviewLike: () => {},
-      newsletterSubmit: () => {},
-    }
-
-    for (const [name, handler] of Object.entries(handlers)) {
-      registerHandler(name, handler)
-    }
-    void set
-    // registerHandler uses functional state updates; store/navigate captured once.
-    // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [])
+  useCoreHandlers()
 }

package/assets/templates/app/lib/__STOREFRONT__/icon-map.ts

@@ -0,0 +1,27 @@
+// Generated by Thor Commerce storefront (template: assets/templates/app/lib/__STOREFRONT__/icon-map.ts)
+// Static icon-name → lucide component map. View specs reference icons by
+// kebab-case name (they are data, serialized through state/spec); view
+// registries resolve them here so blocks receive real components — never raw
+// strings, which React renders as unknown HTML tags. Extend this map when a
+// view introduces a new icon name.
+
+import type { LucideIcon } from 'lucide-react'
+import { Circle, Gift, Headphones, Percent, ShieldCheck, Star, Truck, Zap } from 'lucide-react'
+
+/** Neutral fallback rendered for names not present in the map. */
+export const FALLBACK_ICON: LucideIcon = Circle
+
+export const iconMap: Record<string, LucideIcon> = {
+  gift: Gift,
+  headphones: Headphones,
+  percent: Percent,
+  'shield-check': ShieldCheck,
+  star: Star,
+  truck: Truck,
+  zap: Zap,
+}
+
+/** Resolve a spec icon name to a lucide component, falling back safely. */
+export function resolveIcon(name: string | undefined): LucideIcon {
+  return (name && iconMap[name]) || FALLBACK_ICON
+}

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

@@ -3,8 +3,7 @@
 // Kept out of the views so a view module stays a pure server spec; mappers are
 // data-only and imported where the loader builds block props.
 
-import type { CardProduct, FeaturedProduct, ProductCategory2Category } from '@thorprovider/blocks'
-import type { ProductCategory } from '@thorprovider/types'
+import type { CardProduct, FeaturedProduct, ProductCategory2Category, StoreCategory } from '@thorprovider/blocks'
 
 export const CATEGORY_IMAGE_FALLBACK =
   "data:image/svg+xml;charset=utf-8," +
@@ -32,16 +31,19 @@ export function toFeaturedProduct(card: CardProduct): FeaturedProduct {
   }
 }
 
-/** ProductCategory (types canon) → ProductCategory2Category (block), with
- *  fallbacks for description, image, and itemCount the backend may omit. */
-export function toCategoryCard(category: ProductCategory): ProductCategory2Category {
+/** StoreCategory (what @thorprovider/runtime/commerce's getCatalog returns) →
+ *  ProductCategory2Category (block), with fallbacks for description and image.
+ *  The runtime projection keeps only label/href and carries no product count, so
+ *  `itemCount` is unknown here: it is OMITTED (the block then renders no count)
+ *  rather than fabricated as `0`. A genuine `0` supplied by a richer source is
+ *  preserved because `itemCount` is optional, not defaulted. */
+export function toCategoryCard(category: StoreCategory): ProductCategory2Category {
   return {
-    id: category.id,
-    handle: category.handle,
-    name: category.name,
-    description: category.description ?? '',
-    itemCount: category.productCount ?? 0,
-    image: category.image ?? category.metadata?.image ?? CATEGORY_IMAGE_FALLBACK,
+    id: category.label,
+    handle: category.href,
+    name: category.label,
+    description: '',
+    image: CATEGORY_IMAGE_FALLBACK,
     trending: false,
   }
 }

package/assets/templates/app/lib/__STOREFRONT__/registry.tsx

@@ -2,31 +2,218 @@
 
 // Generated by Thor Commerce storefront (template: assets/templates/app/lib/__STOREFRONT__/registry.tsx)
 // Base registry for the app shell plus every registered view's registry fragment.
+//
+// The shell renders the live backend cart: the Navbar mini-cart and the cart
+// drawer read the authoritative cart state and dispatch cart mutations to the
+// Server Actions. Add-to-cart from a listing navigates to the product detail so
+// a variant is chosen explicitly (there is no first-variant shortcut).
 
-import type { Components } from '@json-render/react'
 import { defineRegistry, useStateStore } from '@json-render/react'
-import { Navbar1, ProductCard1 } from '@thorprovider/blocks'
+import {
+  Banner1,
+  FooterSection1,
+  Navbar1,
+  Navbar4,
+  ProductCard1,
+  ShoppingCart4,
+} from '@thorprovider/blocks'
 import { catalog } from './catalog'
+import type { CartLineState, CartTotalsState } from './state'
 import { useStorefrontHandlers } from './handlers'
-import { views } from './views'
+import { resolveIcon } from './icon-map'
+import {
+  bannerPropsSchema,
+  cartDrawerPropsSchema,
+  footerPropsSchema,
+  navbarPropsSchema,
+  productCardPropsSchema,
+  storefrontNavbarPropsSchema,
+} from './schema'
+import { viewRegistries } from './views/registry'
+
+// Navbar4 accepts its own mini-cart line shape (`qty`), distinct from the block
+// `CartItem` contract (`quantity`). Types are local so the asymmetry is explicit.
+interface NavCartItem {
+  id: string
+  name: string
+  variant?: string
+  price: number
+  qty: number
+  image?: string
+}
+
+/** CartLineState -> Navbar4 cart line. `price` is legacy; the authoritative
+ *  subtotal is passed separately, so it is never computed from the line. */
+function toNavCartItems(cart: CartLineState[]): NavCartItem[] {
+  return cart.map((line) => ({
+    id: line.id,
+    name: line.name,
+    variant: line.variant,
+    price: 0,
+    qty: line.quantity,
+    image: line.image,
+  }))
+}
 
 const baseComponents = {
-  Layout: ({ children }: { children?: React.ReactNode }) => {
+  Layout: ({ children, slots }: { children?: React.ReactNode; slots?: Record<string, React.ReactNode> }) => {
     useStorefrontHandlers()
-    return <div className="flex min-h-screen flex-col">{children}</div>
+    return (
+      <div className="flex min-h-screen flex-col">
+        {slots?.notices}
+        <header className="sticky top-0 z-40 bg-background/95 backdrop-blur supports-[backdrop-filter]:bg-background/60">
+          {slots?.header}
+        </header>
+        <main className="flex-1">{children}</main>
+        <footer>{slots?.footer}</footer>
+      </div>
+    )
+  },
+  // Neutral page root: renders the route page without shell chrome. Using it
+  // instead of `Layout` keeps the shell from mounting twice per page.
+  Page: ({ children }: { children?: React.ReactNode }) => <>{children}</>,
+  // Reserved top region for system/status messages. Self-gates on state and
+  // collapses to nothing when there is no notice. A configured mock is labelled
+  // as demo data; a real-mode failure is surfaced visibly, never hidden.
+  SystemNotice: () => {
+    const { state, set } = useStateStore()
+    if (state.dataNoticeDismissed) return null
+    const cartError = typeof state.cartReadError === 'string' ? state.cartReadError : null
+    const error = cartError ?? (typeof state.dataError === 'string' ? state.dataError : null)
+    const isMock = state.dataSource === 'mock'
+    if (!error && !isMock) return null
+    const destructive = Boolean(error)
+    return (
+      <div
+        role="alert"
+        className={
+          destructive
+            ? 'flex items-center justify-between gap-4 border-b border-destructive/40 bg-destructive/10 px-4 py-2 text-sm text-destructive'
+            : 'flex items-center justify-between gap-4 border-b border-border bg-muted px-4 py-2 text-sm text-muted-foreground'
+        }
+      >
+        <span>
+          {error ??
+            'Datos de demostración (mock): no hay un backend real configurado.'}
+        </span>
+        <button
+          type="button"
+          aria-label="Cerrar aviso"
+          onClick={() => set('/dataNoticeDismissed', true)}
+          className="shrink-0 rounded p-1 hover:bg-destructive/20"
+        >
+          X
+        </button>
+      </div>
+    )
+  },
+  StorefrontNavbar: ({ props, emit }: { props: Record<string, unknown>; emit: (event: string) => void }) => {
+    const parsed = storefrontNavbarPropsSchema.parse(props)
+    const { state, set } = useStateStore()
+    const cart = (state.cart ?? []) as CartLineState[]
+    const totals = state.cartTotals as CartTotalsState | null
+    return (
+      <Navbar4
+        storeCategories={parsed.storeCategories}
+        shippingNote={parsed.shippingNote}
+        utilityLinks={parsed.utilityLinks}
+        logoText={parsed.logoText}
+        logoHref={parsed.logoHref}
+        logoAccent={parsed.logoAccent}
+        className={parsed.className}
+        accountHref={parsed.accountHref}
+        // Held global search (E2 task 5.4): default to hidden so no global
+        // search is presented while the contract is unverified; the user-owned
+        // shell seam may opt in with `showSearch: true`.
+        showSearch={parsed.showSearch ?? false}
+        items={toNavCartItems(cart)}
+        subtotal={totals?.subtotal}
+        onViewCart={() => emit('openCart')}
+        onCheckout={() => emit('goToCheckout')}
+        onQtyChange={(id, delta) => {
+          set('/qtyDelta', { id, delta })
+          emit('applyQuantityDelta')
+        }}
+        onRemove={(id) => {
+          set('/lastRemoved', id)
+          emit('removeFromCart')
+        }}
+      />
+    )
+  },
+  CartDrawer: ({ props, emit }: { props: Record<string, unknown>; emit: (event: string) => void }) => {
+    const parsed = cartDrawerPropsSchema.parse(props)
+    const { state, set } = useStateStore()
+    const cart = (state.cart ?? []) as CartLineState[]
+    const totals = state.cartTotals as CartTotalsState | null
+    const cartError = typeof state.cartError === 'string' ? state.cartError : undefined
+    return (
+      <ShoppingCart4
+        items={cart.map((line) => ({
+          id: line.id,
+          name: line.name,
+          price: 0,
+          quantity: line.quantity,
+          image: line.image,
+          variant: line.variant,
+          lineTotal: line.lineTotal,
+          unitPrice: line.unitPrice,
+        }))}
+        promotions={parsed.promotions.map((promo) => ({
+          threshold: promo.threshold,
+          reward: promo.reward,
+          icon: resolveIcon(promo.icon),
+        }))}
+        totals={totals ?? undefined}
+        totalsState={state.cartPending ? 'pending' : cartError ? 'error' : 'idle'}
+        totalsErrorLabel={cartError}
+        onRetryTotals={() => emit('refreshCart')}
+        onQuantityChange={(id, quantity) => {
+          const line = cart.find((candidate) => candidate.id === id)
+          if (!line) return
+          set('/qtyUpdate', { id, merchandiseId: line.merchandiseId, quantity })
+          emit('updateQuantity')
+        }}
+        onRemove={(id) => {
+          set('/lastRemoved', id)
+          emit('removeFromCart')
+        }}
+        onCheckout={() => emit('goToCheckout')}
+      />
+    )
+  },
+  Banner: ({ props, emit }: { props: Record<string, unknown>; emit: (event: string) => void }) => {
+    const parsed = bannerPropsSchema.parse(props)
+    const { set } = useStateStore()
+    return (
+      <Banner1
+        badge={parsed.badge}
+        message={parsed.message}
+        href={parsed.href}
+        linkLabel={parsed.linkLabel}
+        avatars={parsed.avatars}
+        onDismiss={() => {
+          set('/bannerDismissed', true)
+          emit('dismissBanner')
+        }}
+      />
+    )
+  },
+  Navbar: ({ props, emit }: { props: Record<string, unknown>; emit: (event: string) => void }) => {
+    const parsed = navbarPropsSchema.parse(props)
+    return (
+      <Navbar1
+        navLinks={parsed.navLinks}
+        logoText={parsed.logoText}
+        logoHref={parsed.logoHref}
+        currentPath={parsed.currentPath}
+        signIn={parsed.signIn}
+        cta={parsed.cta}
+        cartCount={parsed.cartCount}
+        onOpenCart={() => emit('openCart')}
+      />
+    )
   },
-  Navbar: ({ props, emit }: { props: Record<string, unknown>; emit: (event: string) => void }) => (
-    <Navbar1
-      navLinks={props.navLinks as never}
-      logoText={props.logoText as string}
-      logoHref={props.logoHref as string}
-      currentPath={props.currentPath as string}
-      signIn={props.signIn as never}
-      cta={props.cta as never}
-      cartCount={props.cartCount as number}
-      onOpenCart={() => emit('openCart')}
-    />
-  ),
   ProductCard: ({
     props,
     emit,
@@ -34,18 +221,20 @@ const baseComponents = {
     props: Record<string, unknown>
     emit: (event: string) => void
   }) => {
+    const parsed = productCardPropsSchema.parse(props)
     const { set } = useStateStore()
     const select = (product: unknown) => {
       set('/lastClicked', product)
     }
     return (
       <ProductCard1
-        products={props.products as never}
-        heading={props.heading as string}
-        maxItems={props.maxItems as number}
+        products={parsed.products}
+        heading={parsed.heading}
+        maxItems={parsed.maxItems}
+        // No first-variant shortcut: open the detail so a variant is chosen.
         onAddToCart={(product) => {
           select(product)
-          emit('addToCart')
+          emit('openProduct')
         }}
         onProductClick={(product) => {
           select(product)
@@ -55,44 +244,36 @@ const baseComponents = {
     )
   },
   Footer: ({ props }: { props: Record<string, unknown> }) => {
-    const brandName = props.brandName as string
-    const brandDescription = props.brandDescription as string | undefined
-    const linkColumns =
-      (props.linkColumns as { title: string; links: { label: string; href?: string }[] }[]) ?? []
+    const parsed = footerPropsSchema.parse(props)
     return (
-      <footer className="mt-auto border-t bg-background">
-        <div className="mx-auto grid max-w-6xl gap-8 px-4 py-12 sm:grid-cols-2 lg:grid-cols-4">
-          <div className="space-y-2">
-            <p className="text-lg font-semibold">{brandName}</p>
-            {brandDescription ? (
-              <p className="text-sm text-muted-foreground">{brandDescription}</p>
-            ) : null}
-          </div>
-          {linkColumns.map((column) => (
-            <div key={column.title} className="space-y-2">
-              <p className="text-sm font-medium">{column.title}</p>
-              <ul className="space-y-1">
-                {column.links.map((link) => (
-                  <li key={link.label}>
-                    <a className="text-sm text-muted-foreground hover:text-foreground" href={link.href ?? '#'}>
-                      {link.label}
-                    </a>
-                  </li>
-                ))}
-              </ul>
-            </div>
-          ))}
-        </div>
-      </footer>
+      <FooterSection1
+        brandName={parsed.brandName}
+        brandAccent={parsed.brandAccent}
+        brandDescription={parsed.brandDescription}
+        linkColumns={parsed.linkColumns}
+        className={parsed.className}
+        // The scaffold ships no newsletter submit callback. The seam's
+        // `newsletter` is content only, so the block swallows it and renders no
+        // form. Wiring a real host callback (which would enable the form) is an
+        // external integration, out of scope for the scaffold.
+        newsletter={
+          parsed.newsletter
+            ? {
+                placeholder: parsed.newsletter.placeholder,
+                buttonLabel: parsed.newsletter.buttonLabel ?? 'Suscribirme',
+              }
+            : undefined
+        }
+      />
     )
   },
 }
 
-const viewComponents = Object.assign({}, ...views.map((view) => view.registry))
+const viewComponents = Object.assign({}, ...viewRegistries)
 
 export const { registry } = defineRegistry(catalog, {
   components: {
     ...baseComponents,
     ...viewComponents,
-  } as unknown as Components<typeof catalog>,
+  },
 })

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

@@ -2,16 +2,16 @@
 // Wires the json-render app to the Medusa backend via @thorprovider/adapters
 // (through @thorprovider/runtime/commerce). Loaders come from each view module.
 
-import type { LoaderFn } from '@json-render/next'
+import type { StorefrontLoaderFn } from '@thorprovider/runtime/render-core/app'
 import { createStorefrontApp } from '@thorprovider/runtime/render-core/app'
 import { __STOREFRONT_CAMEL__Spec } from './spec'
 import { views } from './views'
 
-const loaders: Record<string, LoaderFn> = Object.assign({}, ...views.map((view) => view.loader))
+const loaders: Record<string, StorefrontLoaderFn> = Object.assign({}, ...views.map((view) => view.loader))
 
 export const __STOREFRONT_CAMEL__App = createStorefrontApp({
   spec: __STOREFRONT_CAMEL__Spec,
   loaders,
 })
 
-export type { LoaderFn }
+export type { StorefrontLoaderFn }