@thorprovider/storefront 0.3.1

package/skills/sf-view-gen/SKILL.md

@@ -0,0 +1,116 @@
+---
+name: sf-view-gen
+description: Add a new view or modify an existing view in a Thor Commerce storefront, selecting block variants and optional sections from this package's recipes
+---
+
+# sf-view-gen
+
+Generate or modify a single view, driven by the **recipe registry inside this skill's own directory**, so storefronts are not identical.
+
+## Source of truth
+
+The workflow uses only the assets in this skill directory. There is no external project to consult and no package to locate: the recipes and templates it reads live under `assets/`, and the validator under `scripts/`. When a required choice is not determined by those files, ask the user.
+
+## Inputs (the only target-project facts this skill reads)
+
+- the existence of the target project's `package.json`
+- the existence of `lib/<name>/`
+- the existence of the project's `.opencode/`
+- the values returned by the wizard (view name, description of what the view should contain or emphasize)
+
+## Outputs (what this skill produces)
+
+- generated files: the view module under `lib/<name>/views/<view>/` and one barrel entry in `lib/<name>/views/index.ts`
+- declared setup commands: the typecheck command it reports
+- a summary listing every file created and every command run
+
+## Assets (inside this skill)
+
+- `assets/recipes/recipes.json` — per view: `route`, `loader`, `requiredDataKeys`, `defaultVariants`, `allowedVariants`, `optionalSections`
+- `assets/recipes/sections.json` — optional sections → `elementType`, `variants`, `defaultVariant`, `propsHint`
+- `assets/recipes/archetypes.json` — the **archetype (intent) layer**: per slot (`<view>.<slot>`) a set of named **intents**, each with a `variant` and a `when` usage hint, plus the slot `default` intent
+- `assets/templates/views/<view>/` — the view modules it copies
+- `assets/templates/views/sections/` — the optional-section fragments
+- `scripts/validate.mjs` — the validator
+- `references/views.md` — the view composition contract
+- `../json-render-core/` — vendored catalog/schema/spec reference
+- `../json-render-react/` — vendored registry/action reference
+
+Paths are relative to this `SKILL.md`. Run the validator from here:
+```bash
+node scripts/validate.mjs list
+node scripts/validate.mjs show <view>
+node scripts/validate.mjs archetypes
+node scripts/validate.mjs resolve <view> <slot> <intent>
+node scripts/validate.mjs validate '<composition-json>'
+```
+
+## Allowed views
+`home`, `product`, `category`, `checkout`, `user-panel`
+
+Reject any other name with the full allowed list.
+
+## json-render references (consult when authoring element types)
+
+When adding a view you register new element `type`s in the view module: the zod
+catalog entry in `views/<view>/index.tsx` and the component mapping in
+`views/<view>/registry.tsx` ('use client'). Consult the vendored references
+instead of working from memory:
+
+- `../json-render-core/` — catalog/schema/spec authoring (the shape of a catalog entry and a spec element)
+- `../json-render-react/` — registry mapping and action wiring (`defineRegistry`, `Renderer`, `useStateStore`)
+
+**Selection rule:** choose an **intent by meaning** from the user's description (never a raw variant ordinal), then resolve the intent to its variant via `assets/recipes/archetypes.json`. The resolved variant must be allowed by the recipe for that slot. Choose optional sections the same way. Never invent an intent, variant, or component. If the description is silent, use the archetype slot `default`.
+
+```bash
+node scripts/validate.mjs resolve home hero showcase   # -> StorefrontHero2
+```
+
+## Stack constraints
+- UI: only `@thorprovider/blocks`
+- Data: only `@thorprovider/adapters` + `@thorprovider/runtime/commerce`
+- Never `@thorprovider/medusa-extended`
+- No custom blocks without explicit user authorization
+- **Two-file view split (RSC):** `index.tsx` is a pure Server Component module (name, elements, zod catalog, route, loader) and imports `registry` from the sibling `registry.tsx` as data. `registry.tsx` is the **`'use client'`** module and is the only place that imports values from `@json-render/react` or `@thorprovider/blocks`. Never add those imports to `index.tsx` — `@json-render/react` calls `createContext` at module scope, which breaks the RSC server graph.
+- Every element `type` used in a spec MUST be registered in the view's zod catalog (`index.tsx`) AND its client registry (`registry.tsx`); the shared `catalog.ts` / `registry.tsx` compose both through the barrel and are never hand-edited
+
+## Add-view workflow
+
+1. Parse `$ARGUMENTS` → view name (+ optional description). Validate name. Confirm `lib/<name>/` exists (else run `npx @thorprovider/storefront create` to scaffold it).
+2. `node scripts/validate.mjs show <view>` — read slots, allowed variants + sections. `node scripts/validate.mjs archetypes` — read slots with their named intents.
+3. Choose an intent per slot by meaning from the description (defaults if silent), resolve each with `node scripts/validate.mjs resolve <view> <slot> <intent>`, choose optional sections the same way, then validate the full composition with `node scripts/validate.mjs validate '<json>'` **before writing anything**. On failure → stop, show the allowed options.
+4. Copy the view template: `assets/templates/views/<view>/` → `lib/<name>/views/<view>/`. Each template is the two-file split: `index.tsx` (server spec) + `registry.tsx` ('use client' component mappings).
+5. Register it in the barrel `lib/<name>/views/index.ts` — ONE import and ONE array entry:
+   ```ts
+   import { <view> } from './<view>'
+   export const views: ViewModule[] = [home, <view>]
+   ```
+6. Substitute variants: each slot's block is imported under a stable alias (e.g. `ProductOverview1 as ProductOverviewBlock`), shipping the recipe default. Replace **only the imported identifier** with the resolved variant — never the alias, never the props:
+   ```ts
+   import { ProductOverview5 as ProductOverviewBlock } from '@thorprovider/blocks'
+   ```
+7. Include any chosen optional section — fragments live at `assets/templates/views/sections/` as a two-file split:
+   - `<section>.tsx` (server): exports the section object with `elementType`, the zod `catalog` entry, and `registryModule: './<section>.client'`.
+   - `<section>.client.tsx` ('use client'): exports `registry: ViewRegistry` with the component mapping.
+   Import the section object from `<section>` into `index.tsx` and merge its elements/catalog into the view; put the component mapping from `<section>.client` into the view's `registry.tsx` (re-exporting the fragment's registry).
+8. Verify: `yarn typecheck`. Do NOT hand-edit `catalog.ts`, `registry.tsx`, `runtime.ts`, or `spec/index.ts` — they compose whatever the barrel exports.
+
+## Modify workflow (`/sf-view`)
+
+1. Parse view name + change. Validate name.
+2. Read `lib/<name>/views/<view>/index.tsx` (server spec) and `registry.tsx` (client mappings) fully.
+3. Apply ONLY the change. Preserve ids, `type`, untouched `props`, `$state`, `on` wiring, route/loader, and the barrel entry.
+4. If new blocks are needed, choose intents from `archetypes.json`, resolve to allowed variants, and validate before writing.
+5. Re-run `yarn typecheck`.
+
+## Generation headers
+Every generated/edited file gets:
+```
+// Generated by @thorprovider/storefront (sf-view-gen) from recipes/<view>
+```
+
+## Error handling
+- Unknown view → error + allowed list, stop.
+- Missing `lib/<name>/` → run `npx @thorprovider/storefront create`, stop.
+- Undeclared variant/section → reject via `recipes/validate.mjs`, show allowed options.
+- Type errors → fix before finishing; never leave broken specs.

package/skills/sf-view-gen/assets/recipes/archetypes.json

@@ -0,0 +1,148 @@
+{
+  "$schema": "./archetype.schema.json",
+  "version": "1.0.0",
+  "description": "Archetype (intent) layer. Maps a slot to named intents so selection is by meaning, not by variant ordinal. Each intent resolves to a variant that MUST be allowed by the recipe for that slot.",
+  "slots": {
+    "home.hero": {
+      "default": "showcase",
+      "intents": {
+        "compact": {
+          "variant": "StorefrontHero1",
+          "when": "A simple, text-forward hero with a single call to action and no product showcase."
+        },
+        "showcase": {
+          "variant": "StorefrontHero2",
+          "when": "A product-led hero that displays featured products alongside the headline."
+        },
+        "editorial": {
+          "variant": "StorefrontHero5",
+          "when": "A storytelling or brand-editorial hero with strong imagery and a narrative tone."
+        },
+        "promotional": {
+          "variant": "StorefrontHero6",
+          "when": "A campaign hero built around an offer, discount, or seasonal promotion."
+        }
+      }
+    },
+    "home.benefits": {
+      "default": "compact",
+      "intents": {
+        "compact": {
+          "variant": "Feature1",
+          "when": "A short list of benefits with icons and one-line descriptions."
+        },
+        "detailed": {
+          "variant": "Feature2",
+          "when": "Benefits that need longer explanations, richer layout, or supporting media."
+        }
+      }
+    },
+    "home.categories": {
+      "default": "standard",
+      "intents": {
+        "standard": {
+          "variant": "ProductCategory2",
+          "when": "A balanced grid of category cards with image and label."
+        },
+        "iconGrid": {
+          "variant": "ProductCategory1",
+          "when": "A compact icon-based category grid for many small categories."
+        },
+        "featured": {
+          "variant": "ProductCategory4",
+          "when": "Few, large featured category tiles that act as primary navigation."
+        },
+        "editorial": {
+          "variant": "ProductCategory5",
+          "when": "Category tiles presented as editorial imagery blocks."
+        }
+      }
+    },
+    "product.overview": {
+      "default": "standard",
+      "intents": {
+        "standard": {
+          "variant": "ProductOverview1",
+          "when": "A straightforward product detail layout: gallery, title, price, add to cart."
+        },
+        "gallery": {
+          "variant": "ProductOverview2",
+          "when": "The product needs emphasis on a large image gallery with thumbnails."
+        },
+        "rich": {
+          "variant": "ProductOverview5",
+          "when": "A detailed product page with tabs, specs, and extensive structured information."
+        }
+      }
+    },
+    "product.reviews": {
+      "default": "list",
+      "intents": {
+        "list": {
+          "variant": "ReviewRating1",
+          "when": "A simple list of customer reviews with star ratings."
+        },
+        "summary": {
+          "variant": "ReviewRating2",
+          "when": "Reviews led by an aggregate rating summary and distribution."
+        }
+      }
+    },
+    "category.filter": {
+      "default": "sidebar",
+      "intents": {
+        "inline": {
+          "variant": "CategoryFilter1",
+          "when": "A compact inline filter bar above the product grid."
+        },
+        "sidebar": {
+          "variant": "CategoryFilter2",
+          "when": "A left sidebar with facets, price range, and sort controls."
+        },
+        "rich": {
+          "variant": "CategoryFilter4",
+          "when": "Advanced faceted filtering with multiple facet groups and active-filter chips."
+        }
+      }
+    },
+    "checkout.checkout": {
+      "default": "singlePage",
+      "intents": {
+        "singlePage": {
+          "variant": "CheckoutForm1",
+          "when": "A single-page checkout combining contact, shipping, and payment."
+        },
+        "multiStep": {
+          "variant": "CheckoutForm2",
+          "when": "A stepper checkout split into address, delivery, and payment steps."
+        },
+        "compact": {
+          "variant": "CheckoutForm3",
+          "when": "A minimal one-column checkout for fast, low-friction purchase."
+        }
+      }
+    },
+    "user-panel.shell": {
+      "default": "standard",
+      "intents": {
+        "standard": {
+          "variant": "AppShell1",
+          "when": "A standard account shell with side navigation and content area."
+        }
+      }
+    },
+    "user-panel.orderHistory": {
+      "default": "compact",
+      "intents": {
+        "compact": {
+          "variant": "OrderHistory1",
+          "when": "A concise list of past orders with status and totals."
+        },
+        "detailed": {
+          "variant": "OrderHistory2",
+          "when": "Order history with line-item detail, tracking, and reorder actions."
+        }
+      }
+    }
+  }
+}

package/skills/sf-view-gen/assets/recipes/recipes.json

@@ -0,0 +1,90 @@
+{
+  "$schema": "./recipe.schema.json",
+  "version": "1.0.0",
+  "views": [
+    {
+      "name": "home",
+      "description": "Storefront landing page with hero, benefits, and category highlights",
+      "route": "/",
+      "loader": "home",
+      "requiredDataKeys": ["heroProducts", "categories"],
+      "defaultVariants": {
+        "hero": "StorefrontHero1",
+        "benefits": "Feature1",
+        "categories": "ProductCategory2"
+      },
+      "allowedVariants": {
+        "hero": ["StorefrontHero1", "StorefrontHero2", "StorefrontHero5", "StorefrontHero6"],
+        "benefits": ["Feature1", "Feature2"],
+        "categories": ["ProductCategory1", "ProductCategory2", "ProductCategory4", "ProductCategory5"],
+        "productCard": ["ProductCard1", "ProductCard2", "ProductCard3", "ProductCard5"]
+      },
+      "optionalSections": ["testimonials", "faq", "statistics", "logoCloud", "pricing"]
+    },
+    {
+      "name": "product",
+      "description": "Single product detail page with overview, gallery, and reviews",
+      "route": "/productos/[id]",
+      "loader": "product",
+      "requiredDataKeys": ["selectedProduct"],
+      "defaultVariants": {
+        "overview": "ProductOverview1",
+        "reviews": "ReviewRating1"
+      },
+      "allowedVariants": {
+        "overview": ["ProductOverview1", "ProductOverview2", "ProductOverview5"],
+        "reviews": ["ReviewRating1", "ReviewRating2"],
+        "productCard": ["ProductCard1", "ProductCard2", "ProductCard3", "ProductCard5"]
+      },
+      "optionalSections": ["testimonials", "faq", "statistics"]
+    },
+    {
+      "name": "category",
+      "description": "Product listing filtered by category with filters and sorting",
+      "route": "/categorias/[[...slug]]",
+      "loader": "category",
+      "requiredDataKeys": ["categoryProducts", "storeCategories"],
+      "defaultVariants": {
+        "filter": "CategoryFilter2",
+        "productCard": "ProductCard1"
+      },
+      "allowedVariants": {
+        "filter": ["CategoryFilter1", "CategoryFilter2", "CategoryFilter4"],
+        "productCard": ["ProductCard1", "ProductCard2", "ProductCard3", "ProductCard5"]
+      },
+      "optionalSections": ["logoCloud", "testimonials"]
+    },
+    {
+      "name": "checkout",
+      "description": "Multi-step checkout with cart summary, shipping, and payment",
+      "route": "/checkout",
+      "loader": "checkout",
+      "requiredDataKeys": ["checkoutCountries", "checkoutPaymentMethods"],
+      "defaultVariants": {
+        "checkout": "CheckoutForm1",
+        "confirmation": "CheckoutConfirmation"
+      },
+      "allowedVariants": {
+        "checkout": ["CheckoutForm1", "CheckoutForm2", "CheckoutForm3"],
+        "confirmation": ["CheckoutConfirmation"]
+      },
+      "optionalSections": []
+    },
+    {
+      "name": "user-panel",
+      "description": "Customer account area with order history and account navigation",
+      "route": "/cuenta",
+      "loader": "userPanel",
+      "requiredDataKeys": ["lastOrder", "lastOrderLines", "orderPlaced"],
+      "defaultVariants": {
+        "shell": "AppShell1",
+        "orderHistory": "OrderHistory1"
+      },
+      "allowedVariants": {
+        "shell": ["AppShell1"],
+        "orderHistory": ["OrderHistory1", "OrderHistory2"]
+      },
+      "optionalSections": []
+    }
+  ]
+}

package/skills/sf-view-gen/assets/recipes/sections.json

@@ -0,0 +1,46 @@
+{
+  "$schema": "./section.schema.json",
+  "version": "1.0.0",
+  "sections": [
+    {
+      "name": "testimonials",
+      "description": "Customer testimonials or social proof",
+      "elementType": "Testimonials",
+      "variants": ["Testimonial1", "Testimonial2"],
+      "defaultVariant": "Testimonial1",
+      "propsHint": "title, badge, items[] (quote, author, role, avatar)"
+    },
+    {
+      "name": "faq",
+      "description": "Frequently asked questions accordion",
+      "elementType": "Faq",
+      "variants": ["FaqBlock1"],
+      "defaultVariant": "FaqBlock1",
+      "propsHint": "title, description, items[] (question, answer)"
+    },
+    {
+      "name": "statistics",
+      "description": "Key metrics or trust statistics",
+      "elementType": "Statistics",
+      "variants": ["Statistic1"],
+      "defaultVariant": "Statistic1",
+      "propsHint": "title, items[] (value, label)"
+    },
+    {
+      "name": "logoCloud",
+      "description": "Brand or partner logo strip",
+      "elementType": "LogoCloud",
+      "variants": ["LogoCloud1"],
+      "defaultVariant": "LogoCloud1",
+      "propsHint": "title, platforms[]/logos[] (name, src)"
+    },
+    {
+      "name": "pricing",
+      "description": "Pricing tiers or plans",
+      "elementType": "Pricing",
+      "variants": ["PricingSection1"],
+      "defaultVariant": "PricingSection1",
+      "propsHint": "title, description, tiers[] (name, price, features, cta)"
+    }
+  ]
+}

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

@@ -0,0 +1,86 @@
+// 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".
+
+import {
+  getCatalog,
+  getCategoryProductsByHandleWithSource,
+} 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> = {
+  'category.filter': {
+    type: 'CategoryFilter',
+    props: {
+      products: { $state: '/categoryProducts' },
+      sortOptions: [
+        { value: 'newest', label: 'Más recientes' },
+        { value: 'price-asc', label: 'Precio: de menor a mayor' },
+        { value: 'price-desc', label: 'Precio: de mayor a menor' },
+      ],
+    },
+    on: {
+      openProduct: { action: 'openProduct' },
+      applyFilters: { action: 'applyFilters' },
+    },
+  },
+  'category.grid': {
+    type: 'ProductCard',
+    props: {
+      heading: 'Productos',
+      products: { $state: '/categoryProducts' },
+    },
+    on: {
+      addToCart: { action: 'addToCart' },
+      openProduct: { action: 'openProduct' },
+    },
+  },
+}
+
+const catalog = {
+  CategoryFilter: {
+    props: z.object({
+      products: z.array(z.record(z.string(), z.unknown())),
+      sortOptions: z
+        .array(z.object({ value: z.string(), label: z.string() }))
+        .optional(),
+      categories: z.array(z.record(z.string(), z.unknown())).optional(),
+      pagination: z.array(z.union([z.number(), z.string()])).optional(),
+    }),
+    description: 'Product listing filters, sorting, and results.',
+  },
+}
+
+export const category: ViewModule = {
+  name: 'category',
+  elements,
+  catalog,
+  registry,
+  route: {
+    path: '/categorias/[[...slug]]',
+    loaderName: 'category',
+    layout: 'default',
+    metadata: {
+      title: 'Categoría',
+      description: 'Explora los productos de esta categoría en __SITE_NAME__.',
+    },
+    entry: pageRoot('category', ['category.filter', 'category.grid'], elements),
+  },
+  loader: {
+    category: async (params) => {
+      const slug = Array.isArray(params.slug) ? params.slug[0] : params.slug
+      const { products, categories } = await getCatalog()
+      const categoryResult = slug
+        ? await getCategoryProductsByHandleWithSource(slug)
+        : null
+      const categoryProducts = categoryResult ? categoryResult.products : products
+      return { categoryProducts, storeCategories: categories }
+    },
+  },
+}

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

@@ -0,0 +1,48 @@
+'use client'
+
+// Thor Commerce view registry fragment: category
+// Client boundary for the category 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 { CategoryFilter2 as CategoryFilterBlock } from '@thorprovider/blocks'
+import type { CardProduct, CategoryFilter2Filters, FilterProduct } from '@thorprovider/blocks'
+import { useStateStore } from '@json-render/react'
+import type { ViewRegistry } from '../types'
+
+export const registry: ViewRegistry = {
+  CategoryFilter: ({ props, emit }) => {
+    const { set } = useStateStore()
+    const products: FilterProduct[] = ((props.products ?? []) as CardProduct[]).map(
+      (p) => ({
+        id: String(p.id),
+        name: p.title,
+        price: `$${p.price.toFixed(2)}`,
+        image: p.image,
+      }),
+    )
+    return (
+      <CategoryFilterBlock
+        products={products}
+        sortOptions={props.sortOptions as never}
+        categories={props.categories as never}
+        pagination={props.pagination as never}
+        onProductClick={(product) => {
+          set('/lastClicked', product)
+          emit('openProduct')
+        }}
+        onPageChange={(page) => {
+          set('/categoryPage', page)
+        }}
+        onSortChange={(sort) => {
+          set('/categorySort', sort)
+        }}
+        onFilterChange={(filters: CategoryFilter2Filters) => {
+          set('/filters', filters)
+          emit('applyFilters')
+        }}
+      />
+    )
+  },
+}