@thorprovider/storefront 0.7.0 → 0.10.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (164) hide show
  1. package/README.md +22 -2
  2. package/assets/templates/AGENTS.md +14 -2
  3. package/assets/templates/app/app/[[...slug]]/page.tsx +9 -2
  4. package/assets/templates/app/lib/__STOREFRONT__/account-address.ts +129 -0
  5. package/assets/templates/app/lib/__STOREFRONT__/account-lifecycle.client.tsx +2 -2
  6. package/assets/templates/app/lib/__STOREFRONT__/account-private.core.ts +143 -0
  7. package/assets/templates/app/lib/__STOREFRONT__/account-profile.ts +220 -0
  8. package/assets/templates/app/lib/__STOREFRONT__/actions.ts +677 -80
  9. package/assets/templates/app/lib/__STOREFRONT__/addresses-port.ts +107 -0
  10. package/assets/templates/app/lib/__STOREFRONT__/commerce.ts +477 -38
  11. package/assets/templates/app/lib/__STOREFRONT__/confirmation.core.ts +240 -0
  12. package/assets/templates/app/lib/__STOREFRONT__/customer-profile-port.ts +103 -0
  13. package/assets/templates/app/lib/__STOREFRONT__/fulfillment-evidence-port.ts +31 -0
  14. package/assets/templates/app/lib/__STOREFRONT__/handlers.core.ts +21 -4
  15. package/assets/templates/app/lib/__STOREFRONT__/mappers.ts +6 -2
  16. package/assets/templates/app/lib/__STOREFRONT__/order-detail-mapper.ts +642 -0
  17. package/assets/templates/app/lib/__STOREFRONT__/order-detail-port.ts +25 -0
  18. package/assets/templates/app/lib/__STOREFRONT__/orders-port.ts +30 -0
  19. package/assets/templates/app/lib/__STOREFRONT__/ports.ts +28 -0
  20. package/assets/templates/app/lib/__STOREFRONT__/projection-ownership.client.tsx +4 -4
  21. package/assets/templates/app/lib/__STOREFRONT__/session.ts +24 -6
  22. package/assets/templates/app/lib/__STOREFRONT__/state.core.ts +21 -0
  23. package/assets/templates/app/lib/__STOREFRONT__/views/sections/address-book-advanced.client.tsx +29 -0
  24. package/assets/templates/app/lib/__STOREFRONT__/views/sections/checkout-commerce-v1.client.tsx +19 -0
  25. package/assets/templates/app/lib/__STOREFRONT__/views/sections/checkout-commerce-v1.tsx +16 -0
  26. package/assets/templates/app/lib/__STOREFRONT__/views/sections/customer-profile.client.tsx +27 -0
  27. package/assets/templates/app/lib/__STOREFRONT__/views/sections/index.ts +4 -1
  28. package/assets/templates/app/lib/__STOREFRONT__/views/sections/mega-menu-universal.client.tsx +19 -0
  29. package/assets/templates/app/lib/__STOREFRONT__/views/sections/mega-menu-universal.tsx +16 -0
  30. package/assets/templates/app/lib/__STOREFRONT__/views/sections/schema.address-book-advanced.ts +437 -0
  31. package/assets/templates/app/lib/__STOREFRONT__/views/sections/schema.checkout-commerce-v1.ts +398 -0
  32. package/assets/templates/app/lib/__STOREFRONT__/views/sections/schema.customer-profile.ts +138 -0
  33. package/assets/templates/app/lib/__STOREFRONT__/views/sections/schema.mega-menu-universal.ts +76 -0
  34. package/assets/templates/app/lib/__STOREFRONT__/views/sections/schema.universal-banner.ts +217 -0
  35. package/assets/templates/app/lib/__STOREFRONT__/views/sections/universal-banner.client.tsx +24 -0
  36. package/assets/templates/app/lib/__STOREFRONT__/views/sections/universal-banner.tsx +16 -0
  37. package/assets/templates/features/checkout/handlers.ts +24 -4
  38. package/assets/templates/features/customer-addresses/handlers.ts +11 -0
  39. package/assets/templates/features/customer-addresses/state.ts +33 -0
  40. package/assets/templates/features/customer-auth/state.ts +10 -0
  41. package/assets/templates/features/customer-profile/handlers.ts +11 -0
  42. package/assets/templates/features/customer-profile/state.ts +18 -0
  43. package/assets/templates/views/account/address-book-advanced.defaults.ts +534 -0
  44. package/assets/templates/views/account/assembly/assembly.json +36 -0
  45. package/assets/templates/views/account/assembly/index.skeleton.tsx +277 -0
  46. package/assets/templates/views/account/assembly/registry.skeleton.tsx +1057 -0
  47. package/assets/templates/views/account/assembly/slots/addresses/AddressBookAdvanced/binding.json +5 -0
  48. package/assets/templates/views/account/assembly/slots/addresses/AddressBookAdvanced/catalog.part +4 -0
  49. package/assets/templates/views/account/assembly/slots/addresses/AddressBookAdvanced/element.part +5 -0
  50. package/assets/templates/views/account/assembly/slots/addresses/AddressBookAdvanced/registry.part +1 -0
  51. package/assets/templates/views/account/assembly/slots/addresses/cards/catalog.part +5 -0
  52. package/assets/templates/views/account/assembly/slots/addresses/cards/element.part +10 -0
  53. package/assets/templates/views/account/assembly/slots/addresses/cards/registry.part +1 -0
  54. package/assets/templates/views/account/assembly/slots/login/card/catalog.part +4 -0
  55. package/assets/templates/views/account/assembly/slots/login/card/element.part +13 -0
  56. package/assets/templates/views/account/assembly/slots/login/card/registry.part +1 -0
  57. package/assets/templates/views/account/assembly/slots/orders/OrderHistory/catalog.part +5 -0
  58. package/assets/templates/views/account/assembly/slots/orders/OrderHistory/element.part +5 -0
  59. package/assets/templates/views/account/assembly/slots/orders/OrderHistory/registry.part +2 -0
  60. package/assets/templates/views/account/assembly/slots/orders/OrderHistoryAdvanced/binding.json +5 -0
  61. package/assets/templates/views/account/assembly/slots/orders/OrderHistoryAdvanced/catalog.part +5 -0
  62. package/assets/templates/views/account/assembly/slots/orders/OrderHistoryAdvanced/element.part +5 -0
  63. package/assets/templates/views/account/assembly/slots/orders/OrderHistoryAdvanced/registry.part +1 -0
  64. package/assets/templates/views/account/assembly/slots/profile/CustomerProfileAdvanced/binding.json +5 -0
  65. package/assets/templates/views/account/assembly/slots/profile/CustomerProfileAdvanced/catalog.part +4 -0
  66. package/assets/templates/views/account/assembly/slots/profile/CustomerProfileAdvanced/element.part +5 -0
  67. package/assets/templates/views/account/assembly/slots/profile/CustomerProfileAdvanced/registry.part +1 -0
  68. package/assets/templates/views/account/assembly/slots/profile/form/catalog.part +5 -0
  69. package/assets/templates/views/account/assembly/slots/profile/form/element.part +10 -0
  70. package/assets/templates/views/account/assembly/slots/profile/form/registry.part +1 -0
  71. package/assets/templates/views/account/assembly/slots/register/SignUpPage1/catalog.part +4 -0
  72. package/assets/templates/views/account/assembly/slots/register/SignUpPage1/element.part +13 -0
  73. package/assets/templates/views/account/assembly/slots/register/SignUpPage1/registry.part +1 -0
  74. package/assets/templates/views/account/assembly/slots/summary/stack/catalog.part +5 -0
  75. package/assets/templates/views/account/assembly/slots/summary/stack/element.part +5 -0
  76. package/assets/templates/views/account/assembly/slots/summary/stack/registry.part +1 -0
  77. package/assets/templates/views/account/assembly/slots/summary/tabs/catalog.part +5 -0
  78. package/assets/templates/views/account/assembly/slots/summary/tabs/element.part +5 -0
  79. package/assets/templates/views/account/assembly/slots/summary/tabs/registry.part +1 -0
  80. package/assets/templates/views/account/content.ts +326 -0
  81. package/assets/templates/views/account/customer-profile.defaults.ts +136 -0
  82. package/assets/templates/views/account/fulfillment-evidence.client.tsx +34 -0
  83. package/assets/templates/views/account/fulfillment-evidence.defaults.ts +145 -0
  84. package/assets/templates/views/account/fulfillment-evidence.schema.ts +15 -0
  85. package/assets/templates/views/account/index.tsx +259 -38
  86. package/assets/templates/views/account/order-detail.client.tsx +35 -0
  87. package/assets/templates/views/account/order-detail.defaults.ts +457 -0
  88. package/assets/templates/views/account/orders-advanced.client.tsx +77 -0
  89. package/assets/templates/views/account/orders-advanced.defaults.ts +230 -0
  90. package/assets/templates/views/account/registry.tsx +935 -420
  91. package/assets/templates/views/account/schema.ts +50 -0
  92. package/assets/templates/views/account/sections-data.ts +2 -0
  93. package/assets/templates/views/cart/content.ts +1 -0
  94. package/assets/templates/views/category/assembly/index.skeleton.tsx +1 -0
  95. package/assets/templates/views/category/assembly/slots/filter/CategoryListing/element.part +1 -0
  96. package/assets/templates/views/category/content.ts +2 -0
  97. package/assets/templates/views/category/index.tsx +2 -0
  98. package/assets/templates/views/category/sections-data.ts +2 -0
  99. package/assets/templates/views/checkout/checkout-commerce-hosted.tsx +1089 -0
  100. package/assets/templates/views/checkout/content.ts +51 -0
  101. package/assets/templates/views/checkout/index.tsx +1 -1
  102. package/assets/templates/views/checkout/props.ts +10 -2
  103. package/assets/templates/views/checkout/registry.tsx +104 -42
  104. package/assets/templates/views/checkout/schema.ts +76 -1
  105. package/assets/templates/views/home/assembly/assembly.json +23 -2
  106. package/assets/templates/views/home/assembly/index.skeleton.tsx +4 -1
  107. package/assets/templates/views/home/assembly/registry.skeleton.tsx +1 -0
  108. package/assets/templates/views/home/assembly/slots/hero/UniversalBanner/binding.json +5 -0
  109. package/assets/templates/views/home/assembly/slots/hero/UniversalBanner/catalog.part +4 -0
  110. package/assets/templates/views/home/assembly/slots/hero/UniversalBanner/element.part +4 -0
  111. package/assets/templates/views/home/assembly/slots/hero/UniversalBanner/registry.part +10 -0
  112. package/assets/templates/views/home/content.ts +247 -1
  113. package/assets/templates/views/home/data.ts +10 -1
  114. package/assets/templates/views/home/index.tsx +8 -6
  115. package/assets/templates/views/home/props.ts +7 -1
  116. package/assets/templates/views/home/registry.tsx +11 -28
  117. package/assets/templates/views/home/schema.ts +163 -0
  118. package/assets/templates/views/home/sections-data.ts +2 -0
  119. package/assets/templates/views/product/content.ts +1 -0
  120. package/assets/templates/views/static/content.ts +1 -0
  121. package/bin/storefront.js +356 -27
  122. package/package.json +2 -1
  123. package/recipes/adapter-surface.json +159 -0
  124. package/recipes/archetypes.json +43 -4
  125. package/recipes/catalog.json +147 -2
  126. package/recipes/feature.schema.json +9 -0
  127. package/recipes/features.json +72 -1
  128. package/recipes/manifest.schema.json +5 -0
  129. package/recipes/recipe.schema.json +13 -1
  130. package/recipes/recipes.json +37 -7
  131. package/recipes/section.schema.json +112 -0
  132. package/recipes/sections.json +281 -4
  133. package/recipes/validate.mjs +83 -1
  134. package/scripts/adapter-surface.mjs +41 -0
  135. package/scripts/agent-blocks.mjs +700 -0
  136. package/scripts/block-validator.mjs +45 -0
  137. package/scripts/candidate.mjs +56 -14
  138. package/scripts/composers.mjs +7 -2
  139. package/scripts/default-sections.mjs +78 -0
  140. package/scripts/file-classes.mjs +18 -0
  141. package/scripts/generate-adapter-surface.mjs +148 -0
  142. package/scripts/operations.mjs +100 -0
  143. package/scripts/reconcile.mjs +67 -39
  144. package/scripts/section-configure.mjs +316 -0
  145. package/scripts/sync-assets.mjs +1 -0
  146. package/scripts/view-assembly.mjs +101 -14
  147. package/skills/sf-feature/SKILL.md +19 -0
  148. package/skills/sf-view-gen/SKILL.md +73 -7
  149. package/skills/sf-view-gen/assets/recipes/archetypes.json +43 -4
  150. package/skills/sf-view-gen/assets/recipes/catalog.json +147 -2
  151. package/skills/sf-view-gen/assets/recipes/features.json +72 -1
  152. package/skills/sf-view-gen/assets/recipes/recipes.json +37 -7
  153. package/skills/sf-view-gen/assets/recipes/section.schema.json +112 -0
  154. package/skills/sf-view-gen/assets/recipes/sections.json +281 -4
  155. package/skills/sf-view-gen/assets/templates/views/sections/checkout-commerce-v1.client.tsx +19 -0
  156. package/skills/sf-view-gen/assets/templates/views/sections/checkout-commerce-v1.tsx +16 -0
  157. package/skills/sf-view-gen/assets/templates/views/sections/mega-menu-universal.client.tsx +19 -0
  158. package/skills/sf-view-gen/assets/templates/views/sections/mega-menu-universal.tsx +16 -0
  159. package/skills/sf-view-gen/assets/templates/views/sections/schema.checkout-commerce-v1.ts +398 -0
  160. package/skills/sf-view-gen/assets/templates/views/sections/schema.mega-menu-universal.ts +76 -0
  161. package/skills/sf-view-gen/assets/templates/views/sections/schema.universal-banner.ts +217 -0
  162. package/skills/sf-view-gen/assets/templates/views/sections/universal-banner.client.tsx +24 -0
  163. package/skills/sf-view-gen/assets/templates/views/sections/universal-banner.tsx +16 -0
  164. package/skills/sf-view-gen/scripts/validate.mjs +83 -1
@@ -17,10 +17,10 @@
17
17
  // selectable set is exactly the fragment set, which a parity test pins to the
18
18
  // semantic catalog's `executable` entries.
19
19
 
20
- import { existsSync, readFileSync, readdirSync } from 'node:fs'
20
+ import { existsSync, lstatSync, readFileSync, readdirSync } from 'node:fs'
21
21
  import { mkdir, writeFile } from 'node:fs/promises'
22
22
  import path from 'node:path'
23
- import { isSlotSectionEntry } from './section-compat.mjs'
23
+ import { isEditorialSectionEntry, isSlotSectionEntry } from './section-compat.mjs'
24
24
  import { resolveLegacyVariant } from '../recipes/validate.mjs'
25
25
 
26
26
  export const ASSEMBLY_DIRNAME = 'assembly'
@@ -124,8 +124,7 @@ function renderBlockImports(bindings) {
124
124
 
125
125
  // The import line that lets an editorial element read its user-owned instance
126
126
  // content from the view's `content.ts` (`sectionContent[id]`). Emitted only when
127
- // the ordered composition contains at least one editorial instance, so the
128
- // default (slot-only) composition keeps its exact output.
127
+ // the ordered composition contains at least one editorial instance.
129
128
  function renderSectionImports(modules) {
130
129
  const lines = [...modules]
131
130
  .sort((a, b) => a.localeCompare(b))
@@ -144,6 +143,17 @@ function renderSectionRegistryImports(byModule) {
144
143
 
145
144
  const SECTION_CONTENT_EXPORT = 'sectionContent'
146
145
 
146
+ // JSON string contents safely escape backslashes, quotes, and control chars.
147
+ // Keep the surrounding single quotes so ordinary generated output is unchanged.
148
+ function tsStringLiteral(value) {
149
+ const contents = JSON.stringify(value)
150
+ .slice(1, -1)
151
+ .replace(/'/g, "\\'")
152
+ .replace(/\u2028/g, '\\u2028')
153
+ .replace(/\u2029/g, '\\u2029')
154
+ return `'${contents}'`
155
+ }
156
+
147
157
  // One editorial instance's element: a persisted instance id, the section's
148
158
  // registered element type, and its props read from the view's user-owned
149
159
  // `content.ts` by id (falling back to the section fragment's declared neutral
@@ -151,8 +161,9 @@ const SECTION_CONTENT_EXPORT = 'sectionContent'
151
161
  function renderEditorialElement(entry, def) {
152
162
  const fallback =
153
163
  typeof def.defaultProps === 'string' && def.defaultProps.length > 0 ? def.defaultProps : '{}'
154
- const props = `${SECTION_CONTENT_EXPORT}['${entry.id}'] ?? ${fallback}`
155
- return ` '${entry.id}': {\n type: '${def.elementType}',\n props: ${props},\n },`
164
+ const id = tsStringLiteral(entry.id)
165
+ const props = `sectionData[${id}] ?? ${SECTION_CONTENT_EXPORT}[${id}] ?? ${fallback}`
166
+ return ` ${id}: {\n type: '${def.elementType}',\n props: ${props},\n },`
156
167
  }
157
168
 
158
169
  // One editorial instance's client registry binding: the section element type
@@ -177,16 +188,17 @@ function renderDataBoundElement(entry, def) {
177
188
  `Data-bound section "${entry.type}" instance "${entry.id}" has no variant and no declared defaultVariant.`,
178
189
  )
179
190
  }
191
+ const id = tsStringLiteral(entry.id)
180
192
  return [
181
- ` '${entry.id}': {`,
193
+ ` ${id}: {`,
182
194
  ` type: '${def.elementType}',`,
183
195
  ` props: {`,
184
- ` ...(${SECTION_CONTENT_EXPORT}['${entry.id}'] ?? {}),`,
185
- ` sectionId: '${entry.id}',`,
196
+ ` ...(${SECTION_CONTENT_EXPORT}[${id}] ?? {}),`,
197
+ ` sectionId: ${id},`,
186
198
  ` sectionType: '${entry.type}',`,
187
199
  ` variant: '${variant}',`,
188
- ` products: { $state: '/sections/${entry.id}/products' },`,
189
- ` status: { $state: '/sections/${entry.id}/status' },`,
200
+ ` products: { $state: ${tsStringLiteral(`/sections/${entry.id}/products`)} },`,
201
+ ` status: { $state: ${tsStringLiteral(`/sections/${entry.id}/status`)} },`,
190
202
  ` },`,
191
203
  ` on: { addClickedToCart: { action: 'addClickedToCart' }, openProduct: { action: 'openProduct' } },`,
192
204
  ` },`,
@@ -264,7 +276,7 @@ export function assembleView(templateDir, selection = {}, sections = null) {
264
276
  if (existsSync(bindingPath)) {
265
277
  bindings.push(JSON.parse(readFileSync(bindingPath, 'utf8')))
266
278
  }
267
- slotIds.push(`'${slot.id}'`)
279
+ slotIds.push(tsStringLiteral(slot.id))
268
280
  continue
269
281
  }
270
282
  const def = sectionMeta[entry.type]
@@ -285,10 +297,10 @@ export function assembleView(templateDir, selection = {}, sections = null) {
285
297
  // duplicate object keys in the derived `registry.tsx`.
286
298
  if (registryTypes.has(def.elementType)) registry.pop()
287
299
  else registryTypes.add(def.elementType)
288
- slotIds.push(`'${entry.id}'`)
300
+ slotIds.push(tsStringLiteral(entry.id))
289
301
  sectionPropsModules.add(def.propsModule ?? './content')
290
302
  sectionRegistryImports.set(def.registryModule, def.registryExport)
291
- if (def.dataBound === true) dataBoundIds.push(`'${entry.id}'`)
303
+ if (def.dataBound === true) dataBoundIds.push(tsStringLiteral(entry.id))
292
304
  }
293
305
 
294
306
  const indexSkeleton = readFileSync(path.join(assemblyDir(templateDir), 'index.skeleton.tsx'), 'utf8')
@@ -343,3 +355,78 @@ export async function writeViewAssembly({
343
355
  }
344
356
  return changed
345
357
  }
358
+
359
+ function safeSidecarId(id) {
360
+ return (
361
+ typeof id === 'string' &&
362
+ id.trim().length > 0 &&
363
+ id !== '.' &&
364
+ id !== '..' &&
365
+ !id.includes('..') &&
366
+ !id.includes('/') &&
367
+ !id.includes('\\') &&
368
+ !id.includes('\0') &&
369
+ !id.startsWith('slot:')
370
+ )
371
+ }
372
+
373
+ function renderSectionsData(imports) {
374
+ const lines = ['// Generated by @thorprovider/storefront. Do not edit directly.']
375
+ for (const entry of imports) {
376
+ lines.push(`import sectionData${entry.index} from ${tsStringLiteral(entry.module)}`)
377
+ }
378
+ if (imports.length === 0) {
379
+ lines.push('export const sectionData: Record<string, Record<string, unknown>> = {}', '')
380
+ return lines.join('\n')
381
+ }
382
+ lines.push('', 'export const sectionData: Record<string, Record<string, unknown>> = {')
383
+ for (const entry of imports) {
384
+ lines.push(` ${tsStringLiteral(entry.id)}: sectionData${entry.index} as Record<string, unknown>,`)
385
+ }
386
+ lines.push('}', '')
387
+ return lines.join('\n')
388
+ }
389
+
390
+ /**
391
+ * Generate the derived data map for editorial sidecars belonging to the
392
+ * manifest's ordered normalized sections. Sidecars are retained when an
393
+ * instance is removed; only current safe ids with regular files are imported.
394
+ */
395
+ export async function writeSectionsData({ viewDir, sections = [], dryRun = false } = {}) {
396
+ const sectionsDir = path.join(viewDir, 'sections')
397
+ const imports = []
398
+ const sectionsDirIsDirectory = existsSync(sectionsDir) && lstatSync(sectionsDir).isDirectory()
399
+
400
+ if (sectionsDirIsDirectory && Array.isArray(sections)) {
401
+ for (const entry of sections) {
402
+ if (!isEditorialSectionEntry(entry) || !safeSidecarId(entry.id)) continue
403
+ const sidecarPath = path.join(sectionsDir, `${entry.id}.json`)
404
+ const relativePath = path.relative(sectionsDir, sidecarPath)
405
+ if (
406
+ relativePath === '' ||
407
+ relativePath.startsWith(`..${path.sep}`) ||
408
+ relativePath === '..' ||
409
+ path.isAbsolute(relativePath) ||
410
+ !existsSync(sidecarPath) ||
411
+ !lstatSync(sidecarPath).isFile()
412
+ ) {
413
+ continue
414
+ }
415
+ imports.push({
416
+ id: entry.id,
417
+ index: imports.length,
418
+ module: `./sections/${entry.id}.json`,
419
+ })
420
+ }
421
+ }
422
+
423
+ const dest = path.join(viewDir, 'sections-data.ts')
424
+ const next = renderSectionsData(imports)
425
+ const prev = existsSync(dest) ? readFileSync(dest, 'utf8') : null
426
+ if (prev === next) return []
427
+ if (!dryRun) {
428
+ await mkdir(path.dirname(dest), { recursive: true })
429
+ await writeFile(dest, next)
430
+ }
431
+ return [dest]
432
+ }
@@ -40,6 +40,25 @@ not read the JSON files directly; they are an implementation detail.
40
40
  - **Held feature** — `mvp: false`. The CLI rejects it before any write; report it
41
41
  as not available rather than trying to install it.
42
42
 
43
+ ## Checkout route requests
44
+
45
+ Checkout requests stay with the checkout feature: it owns the hosted `/checkout`
46
+ route. The agent does not select an editorial section for checkout requests. Do
47
+ not use `view add checkout` or create a second checkout page. When useful,
48
+ explain that the host-driven checkout renders host-owned
49
+ cart/contact/address state, backend grouped delivery, payment methods,
50
+ and designer order confirmation; `blocks show checkout-commerce-v1 --json`
51
+ describes that route surface, not an editorial section to configure.
52
+
53
+ For checkout customization, discuss or edit only user-owned checkout files:
54
+ `views/checkout/{content,props,data,schema}.ts`, under the project's declared
55
+ ownership rules. Generated checkout files (route, registry, adapter, state, and
56
+ handler wiring) remain CLI-owned and must not be edited by the agent.
57
+ Transactional data and actions are host-owned: never serialize or author cart
58
+ contents/totals, shopper identity or addresses, fulfillment groups/selections,
59
+ payment methods/selections, order actions, or confirmation as agent-side data.
60
+ Use the normal `feature add|remove checkout` CLI workflow for structural changes.
61
+
43
62
  ## Add a feature
44
63
 
45
64
  ```bash
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: sf-view-gen
3
- description: Add or remove a Thor Commerce storefront view, compose and reorder a view's executable sections, or customize a view's user-owned files. Use when the user asks to add or remove a view (home, category, product, cart, account, static), add/remove/reorder a section (faq, cta, products), change a variant, or change a view's content, props, or data. Delegates every structural write to the `storefront` CLI.
3
+ description: Add or remove a Thor Commerce storefront view, compose and reorder a view's executable sections, choose or customize an editorial section from its purpose, or customize a view's user-owned files. Use when the user describes an outcome for an editorial section, asks to add or remove a view or section, change a variant, or change a view's content, props, or data. Delegates every structural write to the `storefront` CLI.
4
4
  ---
5
5
 
6
6
  # sf-view-gen
@@ -83,7 +83,7 @@ natural language and never types a command.
83
83
  `sections --json` installed-instance list as the set of available types.
84
84
  2. Only `executable` types may be composed; a `held` type is refused with the
85
85
  `reason` the registry reports — relay that reason, never invent one. A
86
- `dataBound` `products` instance is configured separately by the developer in
86
+ `dataBound` instance is configured separately by the developer in
87
87
  `views/<view>/data.ts` → `sectionSources[id]` (a canonical query — not a sales
88
88
  ranking); its variant only changes presentation, and until the selection is set
89
89
  the instance renders a truthful "needs configuration" state that `doctor`
@@ -123,17 +123,83 @@ through the CLI (`view add`/`remove` with `--variant`, or a `section.add` /
123
123
  `index.tsx` or registry to swap an import identifier. Variant changes go through
124
124
  the CLI plan/apply path so the manifest and the derived files stay in sync.
125
125
 
126
+ ## Choose and configure an editorial block
127
+
128
+ Route wrong surfaces before considering an editorial section: navigation or a
129
+ header belongs to the shell/view procedure; a product listing belongs to its
130
+ owning product view or feature procedure; checkout and account behavior belong
131
+ to their owning `sf-feature` procedures. Do not select an editorial section for
132
+ any of these requests.
133
+
134
+ 1. Read the installed-only catalog from the storefront project root:
135
+
136
+ ```bash
137
+ npx @thorprovider/storefront blocks list --json
138
+ ```
139
+
140
+ 2. Choose by each ready card's `purpose`, `useWhen`, and `avoidWhen`, not by its
141
+ name. If two cards plausibly match the described outcome, ask one clarifying
142
+ question before choosing. If no ready card matches, or the closest card is
143
+ pending or exempt, explain the unavailable capability and do not configure
144
+ it.
145
+ 3. Read the full card for the selected `<type>`:
146
+
147
+ ```bash
148
+ npx @thorprovider/storefront blocks show <type> --json
149
+ ```
150
+
151
+ Use this output for the complete example, editable fields, host-only fields,
152
+ validator, and installed instance ids. Configure only an instance id listed
153
+ for the target view.
154
+ 4. Start from a complete example returned by `show`. Adapt only the user's
155
+ content values in its user-owned data fields; preserve the example's shape,
156
+ never invent fields, and do not supply host-only fields.
157
+ 5. Save the candidate data as JSON and validate it without writing:
158
+
159
+ ```bash
160
+ npx @thorprovider/storefront section configure <view> <id> --data <file|-> --dry-run --json
161
+ ```
162
+
163
+ Repair only the reported data paths, then repeat the dry run until valid.
164
+ 6. Run the same command without `--dry-run` to write the validated configuration:
165
+
166
+ ```bash
167
+ npx @thorprovider/storefront section configure <view> <id> --data <file|-> --json
168
+ ```
169
+
170
+ 7. Regenerate and verify:
171
+
172
+ ```bash
173
+ npx @thorprovider/storefront sync
174
+ npx @thorprovider/storefront doctor
175
+ ```
176
+
177
+ 8. Explain the block's purpose and when not to use it. Describe which fields
178
+ customize content, media, composition, scheduling, and responsiveness, and
179
+ distinguish user-editable fields from host-only fields.
180
+
126
181
  ## Customize a view
127
182
 
128
- Only **user-owned** files may be edited by hand. They are consumed by thin
129
- derived wrappers, so `sync` regenerates the wrappers around your edits.
183
+ Only the listed user-owned files may be edited by hand. `content.ts` is
184
+ user-owned and may be edited for view-level content that is not section-instance
185
+ configuration. For section-instance content, use `section configure`; never
186
+ hand-edit the `sectionContent` map in `content.ts`, a `sections/<id>.json`
187
+ sidecar, or derived files. A configured sidecar wins over
188
+ `sectionContent[id]`, which remains the fallback when no sidecar exists.
130
189
 
131
- User-owned (edit these): `lib/<name>/views/<view>/content.ts`, `props.ts`,
132
- `data.ts`, `schema.ts`, and `lib/<name>/mappers.ts`.
190
+ User-owned (edit these): `lib/<name>/views/<view>/content.ts` (non-section view
191
+ content), `props.ts`, `data.ts`, `schema.ts`, and `lib/<name>/mappers.ts`.
133
192
 
134
193
  Derived (never edit; the CLI regenerates them): `index.tsx`, `registry.tsx`,
135
194
  `lib/<name>/views/index.ts`, `lib/<name>/views/registry.ts`, `catalog.ts`,
136
- `runtime.ts`, `spec/index.ts`, `state.ts`, `handlers.ts`.
195
+ `runtime.ts`, `spec/index.ts`, `state.ts`, `handlers.ts`, and
196
+ `lib/<name>/views/<view>/sections-data.ts`.
197
+
198
+ The CLI writes `sections/<id>.json` only through `section configure`; never
199
+ hand-edit that sidecar or the derived `sections-data.ts`. Keep `content.ts` as a
200
+ hand-edit target for non-section view content, but do not customize section
201
+ instances through its `sectionContent` map. For an instance with a sidecar, its
202
+ data wins over the `content.ts` fallback.
137
203
 
138
204
  1. Read the current user-owned files for the view.
139
205
  2. Apply the requested change there. Preserve exported names, element ids, and
@@ -4,8 +4,12 @@
4
4
  "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.",
5
5
  "slots": {
6
6
  "home.hero": {
7
- "default": "compact",
7
+ "default": "campaign",
8
8
  "intents": {
9
+ "campaign": {
10
+ "variant": "UniversalBanner",
11
+ "when": "A deal-forward multi-banner campaign wall grounded in the connected catalog (universal-banner family)."
12
+ },
9
13
  "compact": {
10
14
  "variant": "StorefrontHero",
11
15
  "when": "A simple, text-forward hero with a single call to action (canonical `presentation: 'compact'`)."
@@ -146,15 +150,50 @@
146
150
  }
147
151
  },
148
152
  "account.orders": {
149
- "default": "cards",
153
+ "default": "advanced",
150
154
  "intents": {
155
+ "advanced": {
156
+ "variant": "OrderHistoryAdvanced",
157
+ "when": "The signed-in shopper's full order history: search, quick filters, sort, counts and order cards driven by the host `OrdersPort` (the default surface)."
158
+ },
151
159
  "cards": {
152
160
  "variant": "OrderHistory",
153
- "when": "A signed-in shopper's order history with one card per order and details on demand (canonical `presentation: 'cards'`)."
161
+ "when": "A minimal order history rendered by the canonical `OrderHistory` block with one summary card per order and no query controls."
154
162
  },
155
163
  "rows": {
156
164
  "variant": "OrderHistory",
157
- "when": "A compact, list-first order history with one bordered row per order (canonical `presentation: 'rows'`)."
165
+ "when": "A minimal, list-first order history rendered by the canonical `OrderHistory` block in its `rows` presentation."
166
+ }
167
+ }
168
+ },
169
+ "account.summary": {
170
+ "default": "stack",
171
+ "intents": {
172
+ "stack": {
173
+ "variant": "stack",
174
+ "when": "A single scrolling account page: identity, then every installed module in order, with in-page navigation (canonical `presentation: 'stack'`)."
175
+ },
176
+ "tabs": {
177
+ "variant": "tabs",
178
+ "when": "One module visible at a time behind a tablist (canonical `presentation: 'tabs'`)."
179
+ }
180
+ }
181
+ },
182
+ "account.profile": {
183
+ "default": "form",
184
+ "intents": {
185
+ "form": {
186
+ "variant": "form",
187
+ "when": "The shopper's editable profile fields, with the email control present only when the backend supports changing it."
188
+ }
189
+ }
190
+ },
191
+ "account.addresses": {
192
+ "default": "cards",
193
+ "intents": {
194
+ "cards": {
195
+ "variant": "cards",
196
+ "when": "The shopper's saved addresses as cards, with create, edit, delete, and default-address actions."
158
197
  }
159
198
  }
160
199
  }
@@ -4,7 +4,7 @@
4
4
  "description": "Initial semantic executable catalog (E1 tasks 1.2-1.3), classified by source-shape inspection of the @thorprovider/blocks prop contracts and the view templates. Scope: every slot the curated MVP views (home, product, category, checkout, account) render by default, covering both the selectable archetype slots declared by recipes/archetypes.json and the nested default slots that have no archetype (category.productCard, checkout.confirmation) so no legacy default support is dropped. The account view declares canonical LoginPage card/social presentations and SignUpPage1; legacy LoginPage1/LoginPage2 names resolve to card/social through legacyAliases, with social remaining held pending verified account lifecycle wiring. A variant is `executable` only when the slot's canonical data shape can feed its block props without a prop bridge and without inventing data; every other non-default variant is `held` with the specific reason. The one non-default structural choice is home.benefits, which selects between the two bounded presentations (`cards`, `split`) of the single canonical `Feature` block (identical item contract, no bridge); the retired numbered names `Feature1`/`Feature2` resolve through the slot's `legacyAliases`. E2 task 6.1 declares the base listing slot category.filter CategoryFilter2 as the single controlled listing (dataShape `CatalogQuery & CatalogResults`, state controlled) with the search/filter controls contributed by the logical mounts category.search / category.filters (no second block). Source-shape compatibility is not end-to-end backend behavior proof: the render is executable, but the category.search.apply / category.filter.apply actions remain held under the capability catalog (owner: storefront-catalog-search-filters, E2) until a real runtime proof. The `capabilities` map declares those operational capabilities with their requirements and verification state; E1 declares the held category.filter.apply action, E2 adds the held category.search.apply action and the held category.price.range capability that gates the category-filters showPrice option; no capability is claimed verified. The home.hero variants of the retired numbered family (StorefrontHero1/2/5/6) resolve through the slot's `legacyAliases` to the single canonical `StorefrontHero`, whose bounded presentation options (`compact`, `showcase`, `editorial`, `promotional`) preserve the four structural identities; the extended editorial/promotional sections render only from host-supplied data and are omitted otherwise. The category.productCard slot's retired numbered family (ProductCard1/2/3/5) and the previous `ProductCard` variant resolve through the slot's `legacyAliases` to the single canonical `ProductGrid` listing, which renders `ProductCard` item cells with bounded presentation options (`classic`, `minimal`, `rich`) that preserve the three structural identities; the rich presentation's wishlist and view-similar affordances are host-owned and optional, evidence (rating, badge, compare-at) renders only from host-supplied data, and the comparison-table variant `ProductCard5` was discarded as a listing controller, not a card presentation.",
5
5
  "slots": {
6
6
  "home.hero": {
7
- "default": "StorefrontHero",
7
+ "default": "UniversalBanner",
8
8
  "legacyAliases": {
9
9
  "StorefrontHero1": "StorefrontHero",
10
10
  "StorefrontHero2": "StorefrontHero",
@@ -31,6 +31,14 @@
31
31
  "requirements": [
32
32
  "heroProducts"
33
33
  ]
34
+ },
35
+ "UniversalBanner": {
36
+ "status": "executable",
37
+ "block": "UniversalBanner",
38
+ "dataShape": "UniversalBannerData",
39
+ "events": [],
40
+ "state": "uncontrolled",
41
+ "requirements": []
34
42
  }
35
43
  }
36
44
  },
@@ -329,7 +337,7 @@
329
337
  }
330
338
  },
331
339
  "account.orders": {
332
- "default": "OrderHistory",
340
+ "default": "OrderHistoryAdvanced",
333
341
  "variants": {
334
342
  "OrderHistory": {
335
343
  "status": "executable",
@@ -343,12 +351,149 @@
343
351
  "accountCustomer",
344
352
  "accountAuthenticated"
345
353
  ]
354
+ },
355
+ "OrderHistoryAdvanced": {
356
+ "status": "executable",
357
+ "block": "OrderHistoryAdvanced",
358
+ "dataShape": "OrdersPage (host OrdersPort; B2C MVP)",
359
+ "events": [
360
+ "viewOrder",
361
+ "queryChange",
362
+ "presentationChange",
363
+ "orderAction",
364
+ "bulkAction"
365
+ ],
366
+ "state": "uncontrolled",
367
+ "requirements": [
368
+ "accountAuthenticated",
369
+ "ordersPort"
370
+ ]
346
371
  }
347
372
  },
348
373
  "legacyAliases": {
349
374
  "OrderHistory2": "OrderHistory"
350
375
  }
351
376
  },
377
+ "account.summary": {
378
+ "default": "stack",
379
+ "variants": {
380
+ "stack": {
381
+ "status": "executable",
382
+ "block": "AccountFrame",
383
+ "dataShape": "Customer & AccountModule[]",
384
+ "events": [
385
+ "selectModule"
386
+ ],
387
+ "state": "controlled",
388
+ "requirements": [
389
+ "accountCustomer",
390
+ "accountAuthenticated"
391
+ ]
392
+ },
393
+ "tabs": {
394
+ "status": "executable",
395
+ "block": "AccountFrame",
396
+ "dataShape": "Customer & AccountModule[]",
397
+ "events": [
398
+ "selectModule"
399
+ ],
400
+ "state": "controlled",
401
+ "requirements": [
402
+ "accountCustomer",
403
+ "accountAuthenticated"
404
+ ]
405
+ },
406
+ "sidebar": {
407
+ "status": "held",
408
+ "reason": "A dashboard sidebar nests the account navigation inside the storefront chrome and needs a layout the generated storefront does not provide yet.",
409
+ "block": "AccountFrame",
410
+ "dataShape": "Customer & AccountModule[]",
411
+ "events": [
412
+ "selectModule"
413
+ ],
414
+ "state": "controlled",
415
+ "requirements": [
416
+ "accountCustomer",
417
+ "accountAuthenticated"
418
+ ]
419
+ }
420
+ }
421
+ },
422
+ "account.profile": {
423
+ "default": "CustomerProfileAdvanced",
424
+ "variants": {
425
+ "form": {
426
+ "status": "executable",
427
+ "block": "ProfileForm",
428
+ "dataShape": "ProfileField[] & ProfileFormLabels",
429
+ "events": [
430
+ "submit"
431
+ ],
432
+ "state": "controlled",
433
+ "requirements": [
434
+ "accountCustomer",
435
+ "accountAuthenticated",
436
+ "accountProfileAvailable"
437
+ ]
438
+ },
439
+ "CustomerProfileAdvanced": {
440
+ "status": "executable",
441
+ "block": "CustomerProfile",
442
+ "dataShape": "CustomerProfileSnapshot (host CustomerProfilePort)",
443
+ "events": [
444
+ "manageOrganization",
445
+ "requestVerification",
446
+ "retry"
447
+ ],
448
+ "state": "controlled",
449
+ "requirements": [
450
+ "accountAuthenticated",
451
+ "customerProfilePort"
452
+ ]
453
+ }
454
+ }
455
+ },
456
+ "account.addresses": {
457
+ "default": "AddressBookAdvanced",
458
+ "variants": {
459
+ "cards": {
460
+ "status": "executable",
461
+ "block": "AddressBook",
462
+ "dataShape": "AccountAddressView[] & AddressBookLabels",
463
+ "events": [
464
+ "create",
465
+ "edit",
466
+ "delete",
467
+ "setDefaultShipping",
468
+ "setDefaultBilling"
469
+ ],
470
+ "state": "controlled",
471
+ "requirements": [
472
+ "accountCustomer",
473
+ "accountAuthenticated",
474
+ "accountAddressesAvailable"
475
+ ]
476
+ },
477
+ "AddressBookAdvanced": {
478
+ "status": "executable",
479
+ "block": "AddressBookAdvanced",
480
+ "dataShape": "AddressListResult (host AddressBookPort)",
481
+ "events": [
482
+ "create",
483
+ "edit",
484
+ "delete",
485
+ "setDefault",
486
+ "select"
487
+ ],
488
+ "state": "controlled",
489
+ "requirements": [
490
+ "accountAuthenticated",
491
+ "accountAddressesAvailable",
492
+ "addressesPort"
493
+ ]
494
+ }
495
+ }
496
+ },
352
497
  "category.breadcrumb": {
353
498
  "default": "Breadcrumb",
354
499
  "variants": {