@thorprovider/storefront 0.3.1

package/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/recipes/recipe.schema.json

@@ -0,0 +1,59 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://thorcommerce.dev/storefront/recipe.schema.json",
+  "title": "Thor Commerce Storefront View Recipe",
+  "type": "object",
+  "required": ["version", "views"],
+  "properties": {
+    "version": { "type": "string" },
+    "views": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": [
+          "name",
+          "description",
+          "route",
+          "loader",
+          "requiredDataKeys",
+          "defaultVariants",
+          "allowedVariants",
+          "optionalSections"
+        ],
+        "properties": {
+          "name": {
+            "type": "string",
+            "enum": ["home", "product", "category", "checkout", "user-panel"]
+          },
+          "description": { "type": "string" },
+          "route": { "type": "string" },
+          "loader": { "type": "string" },
+          "requiredDataKeys": {
+            "type": "array",
+            "items": { "type": "string" },
+            "minItems": 1
+          },
+          "defaultVariants": {
+            "type": "object",
+            "additionalProperties": { "type": "string" }
+          },
+          "allowedVariants": {
+            "type": "object",
+            "additionalProperties": {
+              "type": "array",
+              "items": { "type": "string" },
+              "minItems": 1
+            }
+          },
+          "optionalSections": {
+            "type": "array",
+            "items": {
+              "type": "string",
+              "enum": ["testimonials", "faq", "statistics", "logoCloud", "pricing"]
+            }
+          }
+        }
+      }
+    }
+  }
+}

package/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/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/recipes/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()
+}