@thorprovider/storefront 0.3.1

package/skills/sf-view-gen/assets/templates/views/user-panel/index.tsx

@@ -0,0 +1,168 @@
+// Thor Commerce view module: user-panel
+// 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 -> "user-panel".
+
+import { getCatalog } from '@thorprovider/runtime/commerce'
+import { z } from 'zod'
+import { pageRoot } from '../../spec/page-root'
+import type { StorefrontElement } from '../../spec/types'
+import type { ViewModule } from '../types'
+import { registry } from './registry'
+
+const elements: Record<string, StorefrontElement> = {
+  'userPanel.shell': {
+    type: 'AppShell',
+    props: {
+      brandName: '__SITE_NAME__',
+      navGroupLabel: 'Mi cuenta',
+      navItems: [
+        { label: 'Mis pedidos', href: '/cuenta', icon: 'package', active: true },
+        { label: 'Mi perfil', href: '/cuenta/perfil', icon: 'user' },
+        { label: 'Ajustes', href: '/cuenta/ajustes', icon: 'settings' },
+      ],
+      user: {
+        name: 'Cliente Demo',
+        email: 'cliente@ejemplo.com',
+        initials: 'CD',
+      },
+      breadcrumb: [
+        { label: 'Inicio', href: '/' },
+        { label: 'Mi cuenta' },
+      ],
+      pageTitle: 'Mi cuenta',
+      pageDescription: 'Consulta tus pedidos recientes y gestiona tu cuenta.',
+      action: { label: 'Seguir comprando', href: '/' },
+      stats: [
+        { label: 'Pedidos', value: '1' },
+        { label: 'Estado', value: 'Confirmado' },
+      ],
+    },
+    children: ['userPanel.orderHistory'],
+  },
+  'userPanel.orderHistory': {
+    type: 'OrderHistory',
+    props: {
+      orders: { $state: '/lastOrderLines' },
+      title: 'Historial de pedidos',
+      description: 'Tus compras recientes y su estado.',
+    },
+    on: {
+      viewOrder: { action: 'viewOrder' },
+      downloadInvoice: { action: 'downloadInvoice' },
+    },
+  },
+}
+
+const ctaSchema = z.object({ label: z.string(), href: z.string().optional() })
+
+const appShellNavItemSchema = z.object({
+  label: z.string(),
+  href: z.string(),
+  icon: z.enum([
+    'layout-dashboard',
+    'package',
+    'user',
+    'settings',
+    'home',
+    'shopping-cart',
+    'bar-chart-3',
+    'users',
+    'folder-kanban',
+  ]),
+  active: z.boolean().optional(),
+})
+
+const appShellUserSchema = z.object({
+  name: z.string(),
+  email: z.string(),
+  initials: z.string(),
+})
+
+const breadcrumbItemSchema = z.object({
+  label: z.string(),
+  href: z.string().optional(),
+})
+
+const statSchema = z.object({
+  label: z.string(),
+  value: z.string(),
+})
+
+const orderLineSchema = z.object({
+  name: z.string(),
+  image: z.string(),
+  color: z.string(),
+  size: z.string(),
+  quantity: z.number(),
+  price: z.number(),
+  orderDate: z.string(),
+})
+
+const catalog = {
+  AppShell: {
+    props: z.object({
+      brandName: z.string().optional(),
+      navGroupLabel: z.string().optional(),
+      navItems: z.array(appShellNavItemSchema).optional(),
+      user: appShellUserSchema.optional(),
+      breadcrumb: z.array(breadcrumbItemSchema).optional(),
+      pageTitle: z.string().optional(),
+      pageDescription: z.string().optional(),
+      action: ctaSchema.optional(),
+      stats: z.array(statSchema).optional(),
+    }),
+    slots: ['default'],
+    description: 'Panel de cuenta con navegación lateral, cabecera y área de contenido.',
+  },
+  OrderHistory: {
+    props: z.object({
+      orders: z.array(orderLineSchema),
+      title: z.string().optional(),
+      description: z.string().optional(),
+    }),
+    description: 'Historial de pedidos del cliente.',
+  },
+}
+
+export const userPanel: ViewModule = {
+  name: 'user-panel',
+  elements,
+  catalog,
+  registry,
+  route: {
+    path: '/cuenta',
+    loaderName: 'userPanel',
+    layout: 'default',
+    metadata: {
+      title: 'Mi cuenta',
+      description: 'Consulta tu historial de pedidos y gestiona tu cuenta.',
+    },
+    entry: pageRoot('userPanel', ['userPanel.shell'], elements),
+  },
+  loader: {
+    userPanel: async () => {
+      const { products } = await getCatalog()
+      const placedAt = new Date()
+      const orderDate = placedAt.toISOString().slice(0, 10)
+      const lastOrderLines = products.slice(0, 3).map((product, index) => ({
+        name: product.title,
+        image: product.image,
+        color: 'Estándar',
+        size: 'Único',
+        quantity: index + 1,
+        price: product.price,
+        orderDate,
+      }))
+      const lastOrder = {
+        number: `TC-${placedAt.getFullYear()}0001`,
+        placedAt: placedAt.toISOString(),
+        email: 'cliente@ejemplo.com',
+        status: 'Confirmado',
+        total: lastOrderLines.reduce((sum, line) => sum + line.price * line.quantity, 0),
+      }
+      return { lastOrder, lastOrderLines, orderPlaced: lastOrderLines.length > 0 }
+    },
+  },
+}

package/skills/sf-view-gen/assets/templates/views/user-panel/registry.tsx

@@ -0,0 +1,49 @@
+'use client'
+
+// Thor Commerce view registry fragment: user-panel
+// Client boundary for the user-panel view. Imports value bindings from
+// @json-render/react and components from @thorprovider/blocks — both must stay
+// on the client side of the RSC graph. Kept separate from index.tsx so the view
+// spec (elements/catalog/route/loader) stays a pure Server Component module.
+
+import {
+  AppShell1 as AppShellBlock,
+  OrderHistory1 as OrderHistoryBlock,
+} from '@thorprovider/blocks'
+import { useStateStore } from '@json-render/react'
+import type { ViewRegistry } from '../types'
+
+export const registry: ViewRegistry = {
+  AppShell: ({ props, children }) => (
+    <AppShellBlock
+      brandName={props.brandName as string}
+      navGroupLabel={props.navGroupLabel as string}
+      navItems={props.navItems as never}
+      user={props.user as never}
+      breadcrumb={props.breadcrumb as never}
+      pageTitle={props.pageTitle as string}
+      pageDescription={props.pageDescription as string}
+      action={props.action as never}
+      stats={props.stats as never}
+    >
+      {children}
+    </AppShellBlock>
+  ),
+  OrderHistory: ({ props, emit }) => {
+    const { set } = useStateStore()
+    return (
+      <OrderHistoryBlock
+        orders={props.orders as never}
+        title={props.title as string}
+        description={props.description as string}
+        onViewDetails={() => {
+          set('/orderDetailsOpen', true)
+          emit('viewOrder')
+        }}
+        onDownloadInvoice={() => {
+          emit('downloadInvoice')
+        }}
+      />
+    )
+  },
+}

package/skills/sf-view-gen/references/views.md

@@ -0,0 +1,69 @@
+# View templates
+
+Each folder here is a self-contained view module. `npx @thorprovider/storefront create`
+copies `home/` at init; `/sf-add-view` copies one folder per added view.
+
+## Module shape
+
+Each view is the **two-file split** (RSC):
+
+- `views/<view>/index.tsx` — pure Server Component module: name, elements,
+  zod catalog, route, loader. Never imports values from `@json-render/react`
+  or `@thorprovider/blocks`.
+- `views/<view>/registry.tsx` — `'use client'`: exports
+  `registry: ViewRegistry`, the component mappings
+  (`Record<string, (ctx: BaseComponentProps<Record<string, unknown>>) => ReactNode>`).
+
+`index.tsx` imports `registry` from `./registry` as data and exports a single
+`ViewModule`:
+
+```ts
+export const <view>: ViewModule = {
+  name,
+  elements,   // Record<string, StorefrontElement>
+  catalog,    // Record<string, ViewCatalogEntry>
+  registry,   // ViewRegistry — imported from './registry' ('use client')
+  route,      // { path, loaderName, layout, metadata, entry }
+  loader,     // Record<string, LoaderFn>
+}
+```
+
+`@json-render/react` calls `createContext` at module scope; importing its main
+entry as a value anywhere on the RSC server graph raises
+`createContext is not a function`. That is why value imports only ever live in
+`'use client'` files.
+
+Shared files (`catalog.ts`, `registry.tsx`, `runtime.ts`, `spec/index.ts`)
+compose whatever `views/index.ts` exports. They never name a view, so adding a
+view never edits them.
+
+## Registering a view
+
+Add **one import and one entry** to `lib/<name>/views/index.ts`:
+
+```ts
+import { home } from './home'
+import { product } from './product'
+
+export const views: ViewModule[] = [home, product]
+```
+
+## Variant substitution convention
+
+Every slot imports its block variant under a **stable alias** and ships the
+recipe's default variant:
+
+```ts
+import { ProductOverview1 as ProductOverviewBlock } from '@thorprovider/blocks'
+```
+
+To apply a different (recipe-allowed) variant, replace **only the imported
+identifier** — never the alias, never the props:
+
+```ts
+import { ProductOverview5 as ProductOverviewBlock } from '@thorprovider/blocks'
+```
+
+The alias is the element type's contract; the identifier is the presentation
+choice. Keeping props identical across variants is why the catalog declares the
+stable subset of each element's props.

package/skills/sf-view-gen/scripts/validate.mjs

@@ -0,0 +1,190 @@
+#!/usr/bin/env node
+import { readFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const here = dirname(fileURLToPath(import.meta.url))
+
+const recipes = JSON.parse(readFileSync(join(here, 'recipes.json'), 'utf8'))
+const sections = JSON.parse(readFileSync(join(here, 'sections.json'), 'utf8'))
+const archetypes = JSON.parse(readFileSync(join(here, 'archetypes.json'), 'utf8'))
+
+export function loadRecipes() {
+  return recipes
+}
+
+export function loadArchetypes() {
+  return archetypes
+}
+
+/**
+ * Resolve a slot id ("<view>.<slot>") to its archetype definition, or null.
+ */
+export function getSlotArchetype(viewName, slot) {
+  return archetypes.slots[`${viewName}.${slot}`] ?? null
+}
+
+/**
+ * Resolve an intent name to its block variant for a given view + slot.
+ * Returns { ok, variant } or { ok: false, errors }.
+ */
+export function resolveIntent(viewName, slot, intentName) {
+  const errors = []
+  const slotArchetype = getSlotArchetype(viewName, slot)
+  if (!slotArchetype) {
+    errors.push(`Slot "${slot}" has no archetype for view "${viewName}".`)
+    return { ok: false, errors }
+  }
+  const intent = slotArchetype.intents[intentName]
+  if (!intent) {
+    errors.push(
+      `Unknown intent "${intentName}" for slot "${slot}" in view "${viewName}". Allowed intents: ${Object.keys(slotArchetype.intents).join(', ')}.`
+    )
+    return { ok: false, errors }
+  }
+  if (!isAllowedVariant(viewName, slot, intent.variant)) {
+    const allowed = getRecipe(viewName)?.allowedVariants[slot] ?? []
+    errors.push(
+      `Intent "${intentName}" resolves to variant "${intent.variant}", which is not allowed for slot "${slot}" in view "${viewName}". Allowed variants: ${allowed.join(', ') || '(none)'}.`
+    )
+    return { ok: false, errors }
+  }
+  return { ok: true, variant: intent.variant }
+}
+
+export function loadSections() {
+  return sections
+}
+
+export function getRecipe(name) {
+  return recipes.views.find((v) => v.name === name) ?? null
+}
+
+export function allowedViewNames() {
+  return recipes.views.map((v) => v.name)
+}
+
+export function isAllowedVariant(viewName, slot, variant) {
+  const recipe = getRecipe(viewName)
+  if (!recipe) return false
+  const allowed = recipe.allowedVariants[slot]
+  if (!allowed) return false
+  return allowed.includes(variant)
+}
+
+export function isAllowedSection(viewName, sectionName) {
+  const recipe = getRecipe(viewName)
+  if (!recipe) return false
+  if (!recipe.optionalSections.includes(sectionName)) return false
+  return sections.sections.some((s) => s.name === sectionName)
+}
+
+/**
+ * Validate a view composition against its recipe.
+ * composition: { view: string, variants?: {slot: variant}, intents?: {slot: intentName}, sections?: [{name, variant}] }
+ * Throws on any undeclared view, variant, intent, or section.
+ */
+export function validateComposition(composition) {
+  const errors = []
+  const recipe = getRecipe(composition.view)
+  if (!recipe) {
+    errors.push(
+      `Unknown view "${composition.view}". Allowed views: ${allowedViewNames().join(', ')}.`
+    )
+    return { ok: false, errors }
+  }
+
+  for (const [slot, intentName] of Object.entries(composition.intents ?? {})) {
+    const resolved = resolveIntent(composition.view, slot, intentName)
+    if (!resolved.ok) errors.push(...resolved.errors)
+  }
+
+  for (const [slot, variant] of Object.entries(composition.variants ?? {})) {
+    if (!isAllowedVariant(composition.view, slot, variant)) {
+      const allowed = recipe.allowedVariants[slot] ?? []
+      errors.push(
+        `Variant "${variant}" is not allowed for slot "${slot}" in view "${composition.view}". Allowed: ${allowed.join(', ') || '(none)'}.`
+      )
+    }
+  }
+
+  for (const section of composition.sections ?? []) {
+    if (!isAllowedSection(composition.view, section.name)) {
+      errors.push(
+        `Section "${section.name}" is not allowed in view "${composition.view}". Allowed: ${recipe.optionalSections.join(', ') || '(none)'}.`
+      )
+      continue
+    }
+    if (section.variant) {
+      const def = sections.sections.find((s) => s.name === section.name)
+      if (def && !def.variants.includes(section.variant)) {
+        errors.push(
+          `Section variant "${section.variant}" is not allowed for section "${section.name}". Allowed: ${def.variants.join(', ')}.`
+        )
+      }
+    }
+  }
+
+  return { ok: errors.length === 0, errors }
+}
+
+function main() {
+  const [, , command, ...rest] = process.argv
+
+  if (command === 'list') {
+    console.log(allowedViewNames().join('\n'))
+    return
+  }
+
+  if (command === 'show') {
+    const recipe = getRecipe(rest[0])
+    if (!recipe) {
+      console.error(`Unknown view "${rest[0]}". Allowed: ${allowedViewNames().join(', ')}`)
+      process.exit(1)
+    }
+    console.log(JSON.stringify(recipe, null, 2))
+    return
+  }
+
+  if (command === 'validate') {
+    const arg = rest.join(' ').trim()
+    const payload = arg.startsWith('{')
+      ? JSON.parse(arg)
+      : arg
+        ? JSON.parse(readFileSync(arg, 'utf8'))
+        : {}
+    const result = validateComposition(payload)
+    if (!result.ok) {
+      console.error(result.errors.join('\n'))
+      process.exit(1)
+    }
+    console.log('OK')
+    return
+  }
+
+  if (command === 'resolve') {
+    // Usage: resolve <view> <slot> <intent>
+    const [viewName, slot, intentName] = rest
+    const resolved = resolveIntent(viewName, slot, intentName)
+    if (!resolved.ok) {
+      console.error(resolved.errors.join('\n'))
+      process.exit(1)
+    }
+    console.log(resolved.variant)
+    return
+  }
+
+  if (command === 'archetypes') {
+    console.log(JSON.stringify(archetypes.slots, null, 2))
+    return
+  }
+
+  console.error(
+    'Usage: validate.mjs list | show <view> | validate <composition.json> | resolve <view> <slot> <intent> | archetypes'
+  )
+  process.exit(1)
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  main()
+}