@thorprovider/storefront 0.3.1 → 0.4.0-mvp.2

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

@@ -2,16 +2,19 @@
 // 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 { entitySeoExtractors } from './spec/seo'
+import { getSiteUrl } from './store-context'
 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,
+  entitySeo: { siteUrl: getSiteUrl(), extract: entitySeoExtractors },
 })
 
-export type { LoaderFn }
+export type { StorefrontLoaderFn }

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

@@ -0,0 +1,136 @@
+// Generated by Thor Commerce storefront (template: assets/templates/app/lib/__STOREFRONT__/schema.ts)
+// Zod contracts for the shell-level base components. Single source shared by
+// the server-side catalog (catalog.ts) and the client-side registry
+// (registry.tsx) — json-render does not validate props against the catalog at
+// render time, so the registry parses here.
+
+import { z } from 'zod'
+
+export const ctaSchema = z.object({
+  label: z.string(),
+  href: z.string().optional(),
+})
+
+export const navLinkSchema = z.object({
+  label: z.string(),
+  href: z.string().optional(),
+})
+
+const footerLinkSchema = z.object({
+  label: z.string(),
+  href: z.string().optional(),
+})
+
+const footerLinkColumnSchema = z.object({
+  title: z.string(),
+  links: z.array(footerLinkSchema),
+})
+
+// Declared locally so the scaffold's zod version is the only one in play.
+// Cross-major schema assignment (@thorprovider/blocks ships zod v3) breaks the
+// defineCatalog contract, so the block contract is mirrored here instead.
+export const shellProductSchema = z.object({
+  id: z.union([z.string(), z.number()]),
+  title: z.string(),
+  price: z.number(),
+  originalPrice: z.number().optional(),
+  // Required: the ProductCard1 block contract demands `image: string`, and the
+  // runtime's card projection always fills it (PRODUCT_IMAGE_FALLBACK).
+  image: z.string(),
+  badge: z.string().optional(),
+})
+
+export const navbarPropsSchema = z.object({
+  navLinks: z.array(navLinkSchema),
+  logoText: z.string(),
+  logoHref: z.string().optional(),
+  currentPath: z.string().optional(),
+  signIn: ctaSchema.optional(),
+  cta: ctaSchema.optional(),
+  cartCount: z.number().optional(),
+})
+
+// Mirrors the StorefrontNavbar block contract in this scaffold. `storeCategories`
+// is bound to /navCategories and `items` is derived from /cart in the registry,
+// so only the static chrome is declared here.
+export const navCategorySchema = z.object({
+  label: z.string(),
+  href: z.string(),
+  children: z.array(z.object({ label: z.string(), href: z.string() })).optional(),
+  emphasis: z.boolean().optional(),
+})
+
+// Optional brand seam mirroring the Navbar4 / FooterSection1 accent props and
+// the StorefrontHero1 editorial image. Declared locally (see shellProductSchema)
+// so the scaffold's zod version is the only one in play.
+export const shellAccentSchema = z.object({
+  text: z.string(),
+  className: z.string().optional(),
+})
+
+export const storefrontNavbarPropsSchema = z.object({
+  storeCategories: z.array(navCategorySchema),
+  shippingNote: z.string().optional(),
+  utilityLinks: z.array(z.object({ label: z.string(), href: z.string() })),
+  logoText: z.string(),
+  logoHref: z.string().optional(),
+  logoAccent: shellAccentSchema.optional(),
+  className: z.string().optional(),
+  accountHref: z.string().optional(),
+  // Held global search (E2 task 5.4): the generated shell opts out of the
+  // navbar search control while no verified global search contract exists.
+  showSearch: z.boolean().optional(),
+})
+
+export const bannerPropsSchema = z.object({
+  badge: z.string().optional(),
+  message: z.string(),
+  href: z.string(),
+  linkLabel: z.string(),
+  avatars: z.array(z.string()).optional(),
+})
+
+export const productCardPropsSchema = z.object({
+  products: z.array(shellProductSchema),
+  heading: z.string().optional(),
+  maxItems: z.number().optional(),
+})
+
+export const footerPropsSchema = z.object({
+  brandName: z.string(),
+  brandAccent: shellAccentSchema.optional(),
+  brandDescription: z.string().optional(),
+  linkColumns: z.array(footerLinkColumnSchema),
+  className: z.string().optional(),
+  newsletter: z
+    .object({ placeholder: z.string().optional(), buttonLabel: z.string().optional() })
+    .optional(),
+})
+
+// Navigability chrome contracts, mirrored from @thorprovider/blocks so the
+// shell catalog/registry share the scaffold's zod version.
+export const skipToContentPropsSchema = z.object({
+  targetId: z.string(),
+  label: z.string().optional(),
+  className: z.string().optional(),
+})
+
+export const backToTopPropsSchema = z.object({
+  threshold: z.number().optional(),
+  label: z.string().optional(),
+  className: z.string().optional(),
+})
+
+export const mobileBottomNavItemSchema = z.object({
+  id: z.string().optional(),
+  label: z.string(),
+  href: z.string(),
+  icon: z.string().optional(),
+})
+
+export const mobileBottomNavPropsSchema = z.object({
+  items: z.array(mobileBottomNavItemSchema),
+  currentHref: z.string().optional(),
+  ariaLabel: z.string().optional(),
+  className: z.string().optional(),
+})

package/assets/templates/app/lib/__STOREFRONT__/section-observation.ts

@@ -0,0 +1,182 @@
+'use client'
+
+// Generated by Thor Commerce storefront (host: section observation)
+//
+// Optional, host-owned merchandising observation. DISABLED BY DEFAULT: nothing is
+// observed, transmitted, or stored until the host registers an adapter through
+// `configureSectionObservation`. The pure controller (validation, impression
+// dedupe, conservative lineage) lives in @thorprovider/runtime/contracts; this
+// module only adds the browser glue (visibility, per-view-visit identity) and the
+// adapter seam. Adapter failures never interrupt navigation, cart, or checkout.
+
+import { useEffect, useRef, useState } from 'react'
+import {
+  createInMemoryRecorder,
+  createObservationController,
+  type ConfirmedEvent,
+  type ObservationContext,
+  type ObservationController,
+  type SectionObservationAdapter,
+} from '@thorprovider/runtime/contracts'
+
+let controller: ObservationController | null = null
+let viewVisitId: string | null = null
+let viewVisitSeq = 0
+
+function nextViewVisitId(): string {
+  viewVisitSeq += 1
+  return `${Date.now().toString(36)}-${viewVisitSeq}`
+}
+
+/** Stable for one view visit (page load). */
+function getViewVisitId(): string {
+  if (!viewVisitId) viewVisitId = nextViewVisitId()
+  return viewVisitId
+}
+
+function reportFailure(scope: string, error: unknown): void {
+  console.error(
+    `[storefront/observation] ${scope} failed`,
+    error instanceof Error ? error.message : error,
+  )
+}
+
+/** Register (or clear) the host adapter. Null disables observation entirely. */
+export function configureSectionObservation(adapter: SectionObservationAdapter | null): void {
+  controller = adapter
+    ? createObservationController({
+        adapter,
+        onError: (error) => reportFailure('adapter', error),
+      })
+    : null
+}
+
+export function isSectionObservationEnabled(): boolean {
+  return controller !== null
+}
+
+export function getSectionObservationController(): ObservationController | null {
+  return controller
+}
+
+/** An in-memory recorder for verification/tests (never a production sink). */
+export function createInMemorySectionRecorder(): ReturnType<typeof createInMemoryRecorder> {
+  return createInMemoryRecorder()
+}
+
+export function setSectionObservationContext(context?: ObservationContext): void {
+  try {
+    controller?.setContext(context)
+  } catch (error) {
+    reportFailure('setContext', error)
+  }
+}
+
+/**
+ * Observe a confirmed host transition. Only recorded when a section origin
+ * exists for the current session/context; otherwise it stays unattributed.
+ */
+export function recordConfirmedTransition(
+  event: ConfirmedEvent,
+  input?: { productHandle?: string; destination?: string },
+): void {
+  try {
+    controller?.noteConfirmed(event, input)
+  } catch (error) {
+    reportFailure(event, error)
+  }
+}
+
+export interface UseSectionObservationInput {
+  sectionId: string
+  sectionType: string
+  sectionVariant?: string
+  objective?: string
+  context?: ObservationContext
+}
+
+/**
+ * Observe a section's exposure and product clicks. When observation is disabled
+ * no IntersectionObserver is attached and the returned callback is a no-op.
+ */
+export function useSectionObservation(input: UseSectionObservationInput) {
+  const enabled = isSectionObservationEnabled() && input.sectionId.length > 0
+  const containerRef = useRef<HTMLDivElement | null>(null)
+  const [inView, setInView] = useState(false)
+  const { sectionId, sectionType, sectionVariant, objective, context } = input
+
+  useEffect(() => {
+    if (!enabled) return
+    const element = containerRef.current
+    if (!element || typeof IntersectionObserver === 'undefined') return
+    const observer = new IntersectionObserver(
+      (entries) => {
+        for (const entry of entries) {
+          if (entry.intersectionRatio >= 0.5) setInView(true)
+        }
+      },
+      { threshold: [0.5] },
+    )
+    observer.observe(element)
+    return () => observer.disconnect()
+  }, [enabled])
+
+  useEffect(() => {
+    if (!enabled || !inView) return
+    const timer = setTimeout(() => {
+      controller?.observeImpression({
+        viewVisitId: getViewVisitId(),
+        sectionId,
+        sectionType,
+        ...(sectionVariant ? { sectionVariant } : {}),
+        ...(objective ? { objective } : {}),
+        ...(context ? { context } : {}),
+      })
+    }, 1000)
+    return () => clearTimeout(timer)
+  }, [enabled, inView, sectionId, sectionType, sectionVariant, objective, context])
+
+  const noteProductClick = (product: { id: string | number; href?: string }): void => {
+    if (!enabled) return
+    try {
+      controller?.noteClick({
+        viewVisitId: getViewVisitId(),
+        sectionId,
+        sectionType,
+        ...(sectionVariant ? { sectionVariant } : {}),
+        ...(objective ? { objective } : {}),
+        ...(context ? { context } : {}),
+        productHandle: String(product.id),
+        ...(product.href ? { destination: product.href } : {}),
+      })
+    } catch (error) {
+      reportFailure('noteClick', error)
+    }
+  }
+
+  return { containerRef, noteProductClick, enabled }
+}
+
+/**
+ * Observe a successfully rendered product destination. Recorded only when it
+ * matches the current section origin; otherwise it stays unattributed.
+ */
+export function useProductVisitObservation(
+  productHandle: string | null | undefined,
+  destination?: string,
+): void {
+  const enabled = isSectionObservationEnabled()
+
+  useEffect(() => {
+    if (!enabled || !productHandle) return
+    try {
+      controller?.noteProductVisit({
+        viewVisitId: getViewVisitId(),
+        productHandle: String(productHandle),
+        ...(destination ? { destination } : {}),
+      })
+    } catch (error) {
+      reportFailure('noteProductVisit', error)
+    }
+  }, [enabled, productHandle, destination])
+}

package/assets/templates/app/lib/__STOREFRONT__/section-sources.ts

@@ -0,0 +1,130 @@
+// Derived host helper: per-instance resolution for data-bound sections.
+//
+// A data-bound section (for example `products`) keeps its *selection* in a
+// user-owned, per-instance config keyed by the section's stable id
+// (`views/<view>/data.ts` -> `sectionSources`). This module is the single host
+// boundary that turns that config into resolved, validated view state:
+//
+//   * it validates each source with the canonical `sectionSourceSchema` (an
+//     invalid or missing source yields an `unconfigured` state, never a guess);
+//   * it resolves each selection through the existing canonical catalog bridge
+//     (`getCatalogResults`), so equal queries share request-local work, differing
+//     store/channel/region/currency contexts stay isolated, and unsupported
+//     criteria are reported rather than dropped;
+//   * it maps each canonical product to the shared presentation contract via the
+//     host mapper, so an unresolved price stays truthful instead of becoming $0;
+//   * it returns one discriminated state per section id, so a failing section
+//     never erases its siblings and a real failure is never replaced by mock data.
+//
+// Orphan sources (ids no longer referenced by the composition) are ignored.
+
+import { getCatalogResults } from '@thorprovider/runtime/commerce'
+import {
+  MERCHANDISING_SECTION_MAX_ITEMS,
+  sectionSourceSchema,
+} from '@thorprovider/runtime/contracts'
+import {
+  PRODUCT_IMAGE_FALLBACK,
+  isCompleteFiniteDecimal,
+  type ProductPresentation,
+} from '@thorprovider/blocks'
+import type { Product, StoreContext } from '@thorprovider/types'
+
+/** Per-instance section selection config, keyed by the section's stable id. */
+export type SectionSources = Record<string, unknown>
+
+/**
+ * Canonical `Product` (unified provider output) → `ProductPresentation` for the
+ * merchandising product sections. Unlike the card mapper, this NEVER drops a
+ * product with an unresolved price: the canonical `Money` is passed through and
+ * the block renders a truthful "unavailable" state instead of inventing `$0`.
+ * Optional fields (image alt, rating, badge) are omitted — never `""` or a
+ * fabricated value — and a missing image falls back to the shared placeholder so
+ * no `<img>` is rendered without a `src`.
+ *
+ * This lives in the derived host helper (not the user-owned mappers module) so an
+ * upgraded home whose `mappers.ts` predates this capability still compiles.
+ */
+export function toProductPresentation(product: Product): ProductPresentation {
+  const min = product.priceRange?.minVariantPrice
+  const compareAt = product.variants.find(
+    (variant) => variant.compareAtPrice && isCompleteFiniteDecimal(variant.compareAtPrice.amount),
+  )?.compareAtPrice
+  const image = product.featuredImage?.url || product.images[0]?.url || PRODUCT_IMAGE_FALLBACK
+  const imageAlt = product.featuredImage?.altText || undefined
+  return {
+    id: product.handle,
+    title: product.title,
+    image,
+    imageAlt,
+    href: `/products/${product.handle}`,
+    price: min ?? { amount: '', currencyCode: '' },
+    compareAtPrice: compareAt,
+    rating: undefined,
+    badge: undefined,
+  }
+}
+
+/** The resolved state the view state model carries for one data-bound section. */
+export interface SectionViewState {
+  status:
+    | 'unconfigured'
+    | 'ready'
+    | 'empty'
+    | 'invalid-query'
+    | 'unsupported-query'
+    | 'unmounted-capability'
+    | 'data-error'
+  products: ProductPresentation[]
+}
+
+/**
+ * Read the optional `sectionSources` export from a user-owned data module
+ * without hard-importing it, so a home scaffolded before this capability (whose
+ * `data.ts` has no such export) still compiles and simply renders every
+ * data-bound section as `unconfigured`.
+ */
+export function resolveSectionSources(module: unknown): SectionSources {
+  const candidate = (module as { sectionSources?: unknown } | null | undefined)?.sectionSources
+  return candidate && typeof candidate === 'object' ? (candidate as SectionSources) : {}
+}
+
+/**
+ * Resolve the state for every referenced data-bound section id. Sections resolve
+ * concurrently and independently; each entry is always present so the registry
+ * can render a truthful state for its section.
+ */
+export async function resolveSectionViewStates(
+  ids: readonly string[],
+  sources: SectionSources,
+  context: StoreContext,
+): Promise<Record<string, SectionViewState>> {
+  const states: Record<string, SectionViewState> = {}
+  await Promise.all(
+    ids.map(async (id) => {
+      const parsed = sectionSourceSchema.safeParse(sources[id])
+      if (!parsed.success) {
+        states[id] = { status: 'unconfigured', products: [] }
+        return
+      }
+      const source = parsed.data
+      try {
+        const outcome = await getCatalogResults(source.query, context)
+        if (!outcome.ok) {
+          states[id] = { status: outcome.error.code, products: [] }
+          return
+        }
+        const maxItems = source.maxItems ?? MERCHANDISING_SECTION_MAX_ITEMS
+        const products = outcome.results.products
+          .slice(0, maxItems)
+          .map(toProductPresentation)
+        states[id] = { status: products.length > 0 ? 'ready' : 'empty', products }
+      } catch {
+        // A transport/provider failure is surfaced as a per-section data error,
+        // never as fabricated or mock products, and never discards siblings.
+        states[id] = { status: 'data-error', products: [] }
+      }
+    }),
+  )
+  return states
+}