@thorprovider/storefront 0.7.0 → 0.9.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.
- package/README.md +22 -2
- package/assets/templates/AGENTS.md +14 -2
- package/assets/templates/app/app/[[...slug]]/page.tsx +9 -2
- package/assets/templates/app/lib/__STOREFRONT__/account-address.ts +129 -0
- package/assets/templates/app/lib/__STOREFRONT__/account-lifecycle.client.tsx +2 -2
- package/assets/templates/app/lib/__STOREFRONT__/account-private.core.ts +143 -0
- package/assets/templates/app/lib/__STOREFRONT__/account-profile.ts +220 -0
- package/assets/templates/app/lib/__STOREFRONT__/actions.ts +621 -80
- package/assets/templates/app/lib/__STOREFRONT__/addresses-port.ts +107 -0
- package/assets/templates/app/lib/__STOREFRONT__/commerce.ts +346 -38
- package/assets/templates/app/lib/__STOREFRONT__/confirmation.core.ts +240 -0
- package/assets/templates/app/lib/__STOREFRONT__/customer-profile-port.ts +103 -0
- package/assets/templates/app/lib/__STOREFRONT__/order-detail-port.ts +26 -0
- package/assets/templates/app/lib/__STOREFRONT__/orders-port.ts +30 -0
- package/assets/templates/app/lib/__STOREFRONT__/ports.ts +18 -0
- package/assets/templates/app/lib/__STOREFRONT__/projection-ownership.client.tsx +4 -4
- package/assets/templates/app/lib/__STOREFRONT__/session.ts +24 -6
- package/assets/templates/app/lib/__STOREFRONT__/state.core.ts +21 -0
- package/assets/templates/app/lib/__STOREFRONT__/views/sections/address-book-advanced.client.tsx +29 -0
- package/assets/templates/app/lib/__STOREFRONT__/views/sections/checkout-commerce-v1.client.tsx +19 -0
- package/assets/templates/app/lib/__STOREFRONT__/views/sections/checkout-commerce-v1.tsx +16 -0
- package/assets/templates/app/lib/__STOREFRONT__/views/sections/customer-profile.client.tsx +27 -0
- package/assets/templates/app/lib/__STOREFRONT__/views/sections/index.ts +4 -1
- package/assets/templates/app/lib/__STOREFRONT__/views/sections/mega-menu-universal.client.tsx +19 -0
- package/assets/templates/app/lib/__STOREFRONT__/views/sections/mega-menu-universal.tsx +16 -0
- package/assets/templates/app/lib/__STOREFRONT__/views/sections/schema.address-book-advanced.ts +437 -0
- package/assets/templates/app/lib/__STOREFRONT__/views/sections/schema.checkout-commerce-v1.ts +398 -0
- package/assets/templates/app/lib/__STOREFRONT__/views/sections/schema.customer-profile.ts +138 -0
- package/assets/templates/app/lib/__STOREFRONT__/views/sections/schema.mega-menu-universal.ts +76 -0
- package/assets/templates/app/lib/__STOREFRONT__/views/sections/schema.universal-banner.ts +217 -0
- package/assets/templates/app/lib/__STOREFRONT__/views/sections/universal-banner.client.tsx +24 -0
- package/assets/templates/app/lib/__STOREFRONT__/views/sections/universal-banner.tsx +16 -0
- package/assets/templates/features/checkout/handlers.ts +24 -4
- package/assets/templates/features/customer-addresses/handlers.ts +11 -0
- package/assets/templates/features/customer-addresses/state.ts +33 -0
- package/assets/templates/features/customer-auth/state.ts +10 -0
- package/assets/templates/features/customer-profile/handlers.ts +11 -0
- package/assets/templates/features/customer-profile/state.ts +18 -0
- package/assets/templates/views/account/address-book-advanced.defaults.ts +534 -0
- package/assets/templates/views/account/assembly/assembly.json +41 -0
- package/assets/templates/views/account/assembly/index.skeleton.tsx +229 -0
- package/assets/templates/views/account/assembly/registry.skeleton.tsx +1116 -0
- package/assets/templates/views/account/assembly/slots/addresses/AddressBookAdvanced/binding.json +5 -0
- package/assets/templates/views/account/assembly/slots/addresses/AddressBookAdvanced/catalog.part +4 -0
- package/assets/templates/views/account/assembly/slots/addresses/AddressBookAdvanced/element.part +5 -0
- package/assets/templates/views/account/assembly/slots/addresses/AddressBookAdvanced/registry.part +1 -0
- package/assets/templates/views/account/assembly/slots/addresses/cards/catalog.part +5 -0
- package/assets/templates/views/account/assembly/slots/addresses/cards/element.part +10 -0
- package/assets/templates/views/account/assembly/slots/addresses/cards/registry.part +1 -0
- package/assets/templates/views/account/assembly/slots/boot/AccountBoot/catalog.part +5 -0
- package/assets/templates/views/account/assembly/slots/boot/AccountBoot/element.part +5 -0
- package/assets/templates/views/account/assembly/slots/boot/AccountBoot/registry.part +1 -0
- package/assets/templates/views/account/assembly/slots/login/card/catalog.part +4 -0
- package/assets/templates/views/account/assembly/slots/login/card/element.part +13 -0
- package/assets/templates/views/account/assembly/slots/login/card/registry.part +1 -0
- package/assets/templates/views/account/assembly/slots/orders/OrderHistory/catalog.part +5 -0
- package/assets/templates/views/account/assembly/slots/orders/OrderHistory/element.part +5 -0
- package/assets/templates/views/account/assembly/slots/orders/OrderHistory/registry.part +2 -0
- package/assets/templates/views/account/assembly/slots/orders/OrderHistoryAdvanced/binding.json +5 -0
- package/assets/templates/views/account/assembly/slots/orders/OrderHistoryAdvanced/catalog.part +5 -0
- package/assets/templates/views/account/assembly/slots/orders/OrderHistoryAdvanced/element.part +5 -0
- package/assets/templates/views/account/assembly/slots/orders/OrderHistoryAdvanced/registry.part +1 -0
- package/assets/templates/views/account/assembly/slots/profile/CustomerProfileAdvanced/binding.json +5 -0
- package/assets/templates/views/account/assembly/slots/profile/CustomerProfileAdvanced/catalog.part +4 -0
- package/assets/templates/views/account/assembly/slots/profile/CustomerProfileAdvanced/element.part +5 -0
- package/assets/templates/views/account/assembly/slots/profile/CustomerProfileAdvanced/registry.part +1 -0
- package/assets/templates/views/account/assembly/slots/profile/form/catalog.part +5 -0
- package/assets/templates/views/account/assembly/slots/profile/form/element.part +10 -0
- package/assets/templates/views/account/assembly/slots/profile/form/registry.part +1 -0
- package/assets/templates/views/account/assembly/slots/register/SignUpPage1/catalog.part +4 -0
- package/assets/templates/views/account/assembly/slots/register/SignUpPage1/element.part +13 -0
- package/assets/templates/views/account/assembly/slots/register/SignUpPage1/registry.part +1 -0
- package/assets/templates/views/account/assembly/slots/summary/stack/catalog.part +5 -0
- package/assets/templates/views/account/assembly/slots/summary/stack/element.part +5 -0
- package/assets/templates/views/account/assembly/slots/summary/stack/registry.part +1 -0
- package/assets/templates/views/account/assembly/slots/summary/tabs/catalog.part +5 -0
- package/assets/templates/views/account/assembly/slots/summary/tabs/element.part +5 -0
- package/assets/templates/views/account/assembly/slots/summary/tabs/registry.part +1 -0
- package/assets/templates/views/account/content.ts +326 -0
- package/assets/templates/views/account/customer-profile.defaults.ts +136 -0
- package/assets/templates/views/account/index.tsx +218 -35
- package/assets/templates/views/account/order-detail.client.tsx +35 -0
- package/assets/templates/views/account/order-detail.defaults.ts +457 -0
- package/assets/templates/views/account/orders-advanced.client.tsx +166 -0
- package/assets/templates/views/account/orders-advanced.defaults.ts +230 -0
- package/assets/templates/views/account/registry.tsx +944 -369
- package/assets/templates/views/account/schema.ts +50 -0
- package/assets/templates/views/account/sections-data.ts +2 -0
- package/assets/templates/views/cart/content.ts +1 -0
- package/assets/templates/views/category/assembly/index.skeleton.tsx +1 -0
- package/assets/templates/views/category/assembly/slots/filter/CategoryListing/element.part +1 -0
- package/assets/templates/views/category/content.ts +2 -0
- package/assets/templates/views/category/index.tsx +2 -0
- package/assets/templates/views/category/sections-data.ts +2 -0
- package/assets/templates/views/checkout/checkout-commerce-hosted.tsx +1089 -0
- package/assets/templates/views/checkout/content.ts +51 -0
- package/assets/templates/views/checkout/index.tsx +1 -1
- package/assets/templates/views/checkout/props.ts +10 -2
- package/assets/templates/views/checkout/registry.tsx +104 -42
- package/assets/templates/views/checkout/schema.ts +76 -1
- package/assets/templates/views/home/assembly/assembly.json +22 -1
- package/assets/templates/views/home/assembly/index.skeleton.tsx +1 -0
- package/assets/templates/views/home/content.ts +2 -0
- package/assets/templates/views/home/index.tsx +1 -0
- package/assets/templates/views/home/sections-data.ts +2 -0
- package/assets/templates/views/product/content.ts +1 -0
- package/assets/templates/views/static/content.ts +1 -0
- package/bin/storefront.js +343 -13
- package/package.json +2 -1
- package/recipes/adapter-surface.json +158 -0
- package/recipes/archetypes.json +38 -3
- package/recipes/catalog.json +138 -1
- package/recipes/feature.schema.json +9 -0
- package/recipes/features.json +72 -1
- package/recipes/manifest.schema.json +5 -0
- package/recipes/recipe.schema.json +13 -1
- package/recipes/recipes.json +34 -5
- package/recipes/section.schema.json +112 -0
- package/recipes/sections.json +281 -4
- package/recipes/validate.mjs +83 -1
- package/scripts/adapter-surface.mjs +41 -0
- package/scripts/agent-blocks.mjs +700 -0
- package/scripts/block-validator.mjs +45 -0
- package/scripts/candidate.mjs +5 -4
- package/scripts/composers.mjs +7 -2
- package/scripts/default-sections.mjs +78 -0
- package/scripts/file-classes.mjs +14 -0
- package/scripts/generate-adapter-surface.mjs +148 -0
- package/scripts/operations.mjs +100 -0
- package/scripts/reconcile.mjs +67 -39
- package/scripts/section-configure.mjs +316 -0
- package/scripts/sync-assets.mjs +1 -0
- package/scripts/view-assembly.mjs +101 -14
- package/skills/sf-feature/SKILL.md +19 -0
- package/skills/sf-view-gen/SKILL.md +73 -7
- package/skills/sf-view-gen/assets/recipes/archetypes.json +38 -3
- package/skills/sf-view-gen/assets/recipes/catalog.json +138 -1
- package/skills/sf-view-gen/assets/recipes/features.json +72 -1
- package/skills/sf-view-gen/assets/recipes/recipes.json +34 -5
- package/skills/sf-view-gen/assets/recipes/section.schema.json +112 -0
- package/skills/sf-view-gen/assets/recipes/sections.json +281 -4
- package/skills/sf-view-gen/assets/templates/views/sections/checkout-commerce-v1.client.tsx +19 -0
- package/skills/sf-view-gen/assets/templates/views/sections/checkout-commerce-v1.tsx +16 -0
- package/skills/sf-view-gen/assets/templates/views/sections/mega-menu-universal.client.tsx +19 -0
- package/skills/sf-view-gen/assets/templates/views/sections/mega-menu-universal.tsx +16 -0
- package/skills/sf-view-gen/assets/templates/views/sections/schema.checkout-commerce-v1.ts +398 -0
- package/skills/sf-view-gen/assets/templates/views/sections/schema.mega-menu-universal.ts +76 -0
- package/skills/sf-view-gen/assets/templates/views/sections/schema.universal-banner.ts +217 -0
- package/skills/sf-view-gen/assets/templates/views/sections/universal-banner.client.tsx +24 -0
- package/skills/sf-view-gen/assets/templates/views/sections/universal-banner.tsx +16 -0
- package/skills/sf-view-gen/scripts/validate.mjs +83 -1
package/recipes/sections.json
CHANGED
|
@@ -20,7 +20,16 @@
|
|
|
20
20
|
"variants": ["FaqBlock1"],
|
|
21
21
|
"defaultVariant": "FaqBlock1",
|
|
22
22
|
"propsHint": "title, description, items[] (question, answer)",
|
|
23
|
-
"status": "executable"
|
|
23
|
+
"status": "executable",
|
|
24
|
+
"agent": {
|
|
25
|
+
"status": "pending",
|
|
26
|
+
"section": "faq",
|
|
27
|
+
"elementType": "Faq",
|
|
28
|
+
"variants": ["FaqBlock1"],
|
|
29
|
+
"kind": "pending-card",
|
|
30
|
+
"reason": "FAQ content is executable, but its question and answer authoring contract has not yet been reviewed for agent-guided configuration.",
|
|
31
|
+
"owner": "Wave 1 — editorial cards"
|
|
32
|
+
}
|
|
24
33
|
},
|
|
25
34
|
{
|
|
26
35
|
"name": "cta",
|
|
@@ -29,7 +38,16 @@
|
|
|
29
38
|
"variants": ["CtaSection1"],
|
|
30
39
|
"defaultVariant": "CtaSection1",
|
|
31
40
|
"propsHint": "badgeText, title, description, primaryCta/secondaryCta (label, href)",
|
|
32
|
-
"status": "executable"
|
|
41
|
+
"status": "executable",
|
|
42
|
+
"agent": {
|
|
43
|
+
"status": "pending",
|
|
44
|
+
"section": "cta",
|
|
45
|
+
"elementType": "Cta",
|
|
46
|
+
"variants": ["CtaSection1"],
|
|
47
|
+
"kind": "pending-card",
|
|
48
|
+
"reason": "CTA section fields and safe destination guidance need a dedicated editorial card before agent configuration is enabled.",
|
|
49
|
+
"owner": "Wave 1 — editorial cards"
|
|
50
|
+
}
|
|
33
51
|
},
|
|
34
52
|
{
|
|
35
53
|
"name": "products",
|
|
@@ -39,7 +57,16 @@
|
|
|
39
57
|
"defaultVariant": "ProductGrid",
|
|
40
58
|
"dataBound": true,
|
|
41
59
|
"propsHint": "per-instance selection configured in views/<view>/data.ts sectionSources[id] (canonical category/collection/search/ordering query); heading, description, objective, ctaLabel/ctaHref are editorial content",
|
|
42
|
-
"status": "executable"
|
|
60
|
+
"status": "executable",
|
|
61
|
+
"agent": {
|
|
62
|
+
"status": "pending",
|
|
63
|
+
"section": "products",
|
|
64
|
+
"elementType": "Products",
|
|
65
|
+
"variants": ["ProductGrid", "ProductShowcase1"],
|
|
66
|
+
"kind": "pending-card",
|
|
67
|
+
"reason": "Product sections require coordinated editorial copy and host-owned catalog query configuration; that combined card is deferred.",
|
|
68
|
+
"owner": "Wave 1 — editorial cards"
|
|
69
|
+
}
|
|
43
70
|
},
|
|
44
71
|
{
|
|
45
72
|
"name": "statistics",
|
|
@@ -78,7 +105,257 @@
|
|
|
78
105
|
"variants": ["MarketplaceProductCard"],
|
|
79
106
|
"defaultVariant": "MarketplaceProductCard",
|
|
80
107
|
"propsHint": "data (product, labels, glyphs)",
|
|
81
|
-
"status": "executable"
|
|
108
|
+
"status": "executable",
|
|
109
|
+
"agent": {
|
|
110
|
+
"status": "pending",
|
|
111
|
+
"section": "marketplace-product-card",
|
|
112
|
+
"elementType": "MarketplaceProductCard",
|
|
113
|
+
"variants": ["MarketplaceProductCard"],
|
|
114
|
+
"kind": "pending-card",
|
|
115
|
+
"reason": "Marketplace product data, merchandising labels, and action bindings need a commerce-specific authoring card before selection.",
|
|
116
|
+
"owner": "Wave 2 — commerce surfaces"
|
|
117
|
+
}
|
|
118
|
+
},
|
|
119
|
+
{
|
|
120
|
+
"name": "checkout-commerce-v1",
|
|
121
|
+
"description": "CheckoutCommerceV1 presentation section (delivery checkout-commerce-v1).",
|
|
122
|
+
"elementType": "CheckoutCommerceV1",
|
|
123
|
+
"variants": ["CheckoutCommerceV1"],
|
|
124
|
+
"defaultVariant": "CheckoutCommerceV1",
|
|
125
|
+
"propsHint": "data (meta, labels, coupons[], paymentMethods[], countries[], scenarios[])",
|
|
126
|
+
"status": "executable",
|
|
127
|
+
"agent": {
|
|
128
|
+
"status": "ready",
|
|
129
|
+
"section": "checkout-commerce-v1",
|
|
130
|
+
"elementType": "CheckoutCommerceV1",
|
|
131
|
+
"variants": ["CheckoutCommerceV1"],
|
|
132
|
+
"label": "Hosted checkout route",
|
|
133
|
+
"purpose": "Explain the host-driven shopper checkout route at /checkout without moving transactional state into editorial content.",
|
|
134
|
+
"useWhen": [
|
|
135
|
+
"Use this route when grouped delivery choices must reflect the backend state for each fulfillment group.",
|
|
136
|
+
"Use this checkout route when customizing the host-driven checkout experience owned by the checkout feature.",
|
|
137
|
+
"Use this route when the designer order confirmation must follow backend-confirmed state."
|
|
138
|
+
],
|
|
139
|
+
"avoidWhen": [
|
|
140
|
+
"Do not use this route card to add an editorial hero or banner section.",
|
|
141
|
+
"Do not use this route card to configure a product card or product section.",
|
|
142
|
+
"Do not configure checkout as a per-view editorial section; the checkout feature owns the route.",
|
|
143
|
+
"Do not add a second checkout page or route."
|
|
144
|
+
],
|
|
145
|
+
"surfaces": [
|
|
146
|
+
{ "kind": "route", "hosts": ["/checkout"] }
|
|
147
|
+
],
|
|
148
|
+
"editable": false,
|
|
149
|
+
"fields": [
|
|
150
|
+
{ "path": "cart", "type": "array", "required": true, "description": "Backend-authoritative cart lines and totals displayed by the route; do not serialize or edit them as agent-authored section data." },
|
|
151
|
+
{ "path": "contact", "type": "object", "required": true, "description": "Host-owned shopper contact state displayed by checkout." },
|
|
152
|
+
{ "path": "addresses", "type": "array", "required": true, "description": "Host-owned shipping and billing addresses displayed by checkout." },
|
|
153
|
+
{ "path": "shippingGroups", "type": "array", "required": true, "description": "Backend grouped delivery options and selections, preserving each fulfillment group." },
|
|
154
|
+
{ "path": "paymentMethods", "type": "array", "required": true, "description": "Host-provided payment methods and current selection; no payment data is authored by the agent." }
|
|
155
|
+
],
|
|
156
|
+
"hostOnly": [
|
|
157
|
+
{ "path": "cart.linesAndTotals", "reason": "Transactional cart contents and totals come from canonical host state and must never be serialized by the agent." },
|
|
158
|
+
{ "path": "contactAndAddresses", "reason": "Shopper identity and address state are host-owned; the agent may discuss the user-owned checkout presentation files only." },
|
|
159
|
+
{ "path": "shippingGroupsAndSelection", "reason": "Fulfillment groups, delivery options, and selections come from backend state and are not editorial configuration." },
|
|
160
|
+
{ "path": "paymentMethodsAndSelection", "reason": "Payment methods and selection are host-owned transactional state; no payment data is serialized by the agent." },
|
|
161
|
+
{ "path": "checkoutActionsAndConfirmation", "reason": "Actions and confirmation are bound to host handlers and backend-confirmed order state; never invent or serialize them." }
|
|
162
|
+
],
|
|
163
|
+
"examples": [
|
|
164
|
+
{
|
|
165
|
+
"name": "Grouped delivery checkout route",
|
|
166
|
+
"description": "A prompt about grouped fulfillment routes to the existing host-driven checkout feature rather than a section configuration.",
|
|
167
|
+
"data": {
|
|
168
|
+
"prompt": "Make sure the checkout route shows grouped delivery from backend state.",
|
|
169
|
+
"agentAction": "Explain that /checkout is owned by the checkout feature, inspect the route card, and discuss only user-owned checkout files; do not serialize cart, address, fulfillment, payment, action, or confirmation state."
|
|
170
|
+
}
|
|
171
|
+
},
|
|
172
|
+
{
|
|
173
|
+
"name": "Designer checkout confirmation",
|
|
174
|
+
"description": "A request about the order confirmation remains in the checkout route and follows host-confirmed state.",
|
|
175
|
+
"data": {
|
|
176
|
+
"prompt": "Keep the checkout route's order confirmation on the designer screen.",
|
|
177
|
+
"agentAction": "Explain that the designer confirmation follows the backend-confirmed order, including reload/reconcile; do not create an editorial section or a second checkout page."
|
|
178
|
+
}
|
|
179
|
+
}
|
|
180
|
+
]
|
|
181
|
+
}
|
|
182
|
+
},
|
|
183
|
+
{
|
|
184
|
+
"name": "mega-menu-universal",
|
|
185
|
+
"description": "MegaMenuUniversal presentation section (delivery mega-menu-universal).",
|
|
186
|
+
"elementType": "MegaMenuUniversal",
|
|
187
|
+
"variants": ["MegaMenuUniversal"],
|
|
188
|
+
"defaultVariant": "MegaMenuUniversal",
|
|
189
|
+
"propsHint": "data (categories[], labels, config, promotions[])",
|
|
190
|
+
"status": "executable",
|
|
191
|
+
"agent": {
|
|
192
|
+
"status": "exempt",
|
|
193
|
+
"section": "mega-menu-universal",
|
|
194
|
+
"elementType": "MegaMenuUniversal",
|
|
195
|
+
"variants": ["MegaMenuUniversal"],
|
|
196
|
+
"kind": "host-only",
|
|
197
|
+
"reason": "Mega-menu data and placement are storefront-shell concerns, so this section must be configured by the host rather than selected as page content.",
|
|
198
|
+
"owner": "Wave 1 — storefront shell"
|
|
199
|
+
}
|
|
200
|
+
},
|
|
201
|
+
{
|
|
202
|
+
"name": "universal-banner",
|
|
203
|
+
"description": "UniversalBanner presentation section (delivery universal-banner).",
|
|
204
|
+
"elementType": "UniversalBanner",
|
|
205
|
+
"variants": ["UniversalBanner"],
|
|
206
|
+
"defaultVariant": "UniversalBanner",
|
|
207
|
+
"propsHint": "data (campaign, config, now, banner)",
|
|
208
|
+
"status": "executable",
|
|
209
|
+
"agent": {
|
|
210
|
+
"status": "ready",
|
|
211
|
+
"section": "universal-banner",
|
|
212
|
+
"elementType": "UniversalBanner",
|
|
213
|
+
"variants": ["UniversalBanner"],
|
|
214
|
+
"label": "Campaign banner",
|
|
215
|
+
"purpose": "Announce a time-bounded campaign such as Black Friday with focused copy and clear calls to action.",
|
|
216
|
+
"useWhen": [
|
|
217
|
+
"Announce a seasonal campaign or promotion on the home page.",
|
|
218
|
+
"Run a Black Friday campaign with an explicit schedule and destination.",
|
|
219
|
+
"Present one campaign message with calls to action that lead to its offer."
|
|
220
|
+
],
|
|
221
|
+
"avoidWhen": [
|
|
222
|
+
"Do not use this for a product listing or product catalog grid.",
|
|
223
|
+
"Do not use this for the site header or navigation.",
|
|
224
|
+
"Do not use this for checkout steps, payment, or order completion.",
|
|
225
|
+
"Do not use this for account, sign-in, or profile content."
|
|
226
|
+
],
|
|
227
|
+
"surfaces": [
|
|
228
|
+
{ "kind": "section", "hosts": ["home"] }
|
|
229
|
+
],
|
|
230
|
+
"editable": true,
|
|
231
|
+
"fields": [
|
|
232
|
+
{ "path": "campaign.campaignId", "type": "string", "required": true, "description": "Stable identity for this campaign." },
|
|
233
|
+
{ "path": "campaign.banners", "type": "array", "required": true, "description": "Campaign banners; keep one banner for a focused announcement." },
|
|
234
|
+
{ "path": "campaign.banners[].content.title", "type": "string", "required": false, "description": "Short campaign headline." },
|
|
235
|
+
{ "path": "campaign.banners[].content.ctas", "type": "array", "required": true, "description": "Calls to action with labels, destinations, and visual tones." },
|
|
236
|
+
{ "path": "campaign.banners[].media", "type": "object", "required": true, "description": "Non-empty responsive image URLs for the campaign banner." },
|
|
237
|
+
{ "path": "campaign.banners[].schedule", "type": "object", "required": true, "description": "Campaign start and end in the declared timezone." },
|
|
238
|
+
{ "path": "config.presentation", "type": "enum", "required": true, "description": "Banner collection presentation." },
|
|
239
|
+
{ "path": "now", "type": "string", "required": true, "description": "Required serializable ISO timestamp fallback for the initial render; the generated view refreshes it at mount. It remains required for deterministic validation and preview." },
|
|
240
|
+
{ "path": "banner", "type": "object", "required": true, "description": "Localized accessible labels for banner controls." }
|
|
241
|
+
],
|
|
242
|
+
"hostOnly": [
|
|
243
|
+
{ "path": "onBannerClick", "reason": "The host binds this analytics callback; agents configure serializable campaign data instead." },
|
|
244
|
+
{ "path": "onCtaClick", "reason": "The host binds this analytics callback; agents configure serializable campaign data instead." }
|
|
245
|
+
],
|
|
246
|
+
"examples": [
|
|
247
|
+
{
|
|
248
|
+
"name": "Black Friday home campaign",
|
|
249
|
+
"description": "A single scheduled Black Friday banner with two explicit campaign calls to action.",
|
|
250
|
+
"data": {
|
|
251
|
+
"campaign": {
|
|
252
|
+
"schemaVersion": 1,
|
|
253
|
+
"campaignId": "black-friday-2026",
|
|
254
|
+
"banners": [
|
|
255
|
+
{
|
|
256
|
+
"id": "black-friday-home",
|
|
257
|
+
"campaignId": "black-friday-2026",
|
|
258
|
+
"content": {
|
|
259
|
+
"name": "Black Friday home campaign",
|
|
260
|
+
"alt": "Black Friday offers across a selection of products",
|
|
261
|
+
"title": "Black Friday starts now",
|
|
262
|
+
"subtitle": "Save on selected favorites",
|
|
263
|
+
"description": "Discover this week’s limited-time offers.",
|
|
264
|
+
"badge": "Limited time",
|
|
265
|
+
"target": { "kind": "collection", "id": "black-friday" },
|
|
266
|
+
"ctas": [
|
|
267
|
+
{
|
|
268
|
+
"id": "shop-black-friday",
|
|
269
|
+
"label": "Shop Black Friday deals",
|
|
270
|
+
"target": { "kind": "collection", "id": "black-friday" },
|
|
271
|
+
"tone": "primary"
|
|
272
|
+
},
|
|
273
|
+
{
|
|
274
|
+
"id": "view-offers",
|
|
275
|
+
"label": "View all offers",
|
|
276
|
+
"target": { "kind": "page", "slug": "offers" },
|
|
277
|
+
"tone": "secondary"
|
|
278
|
+
}
|
|
279
|
+
]
|
|
280
|
+
},
|
|
281
|
+
"media": {
|
|
282
|
+
"desktop": "data:image/svg+xml;charset=utf-8,%3Csvg%20xmlns%3D%22http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg%22%20width%3D%221600%22%20height%3D%22600%22%20viewBox%3D%220%200%201600%20600%22%3E%3Cdefs%3E%3ClinearGradient%20id%3D%22banner-gradient%22%20x1%3D%220%25%22%20y1%3D%220%25%22%20x2%3D%22100%25%22%20y2%3D%220%25%22%3E%3Cstop%20offset%3D%220%25%22%20stop-color%3D%22%23111827%22%2F%3E%3Cstop%20offset%3D%22100%25%22%20stop-color%3D%22%23b45309%22%2F%3E%3C%2FlinearGradient%3E%3C%2Fdefs%3E%3Crect%20width%3D%22100%25%22%20height%3D%22100%25%22%20fill%3D%22url(%23banner-gradient)%22%2F%3E%3C%2Fsvg%3E",
|
|
283
|
+
"tablet": "data:image/svg+xml;charset=utf-8,%3Csvg%20xmlns%3D%22http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg%22%20width%3D%221024%22%20height%3D%22768%22%20viewBox%3D%220%200%201024%20768%22%3E%3Cdefs%3E%3ClinearGradient%20id%3D%22banner-gradient%22%20x1%3D%220%25%22%20y1%3D%220%25%22%20x2%3D%22100%25%22%20y2%3D%220%25%22%3E%3Cstop%20offset%3D%220%25%22%20stop-color%3D%22%23111827%22%2F%3E%3Cstop%20offset%3D%22100%25%22%20stop-color%3D%22%23b45309%22%2F%3E%3C%2FlinearGradient%3E%3C%2Fdefs%3E%3Crect%20width%3D%22100%25%22%20height%3D%22100%25%22%20fill%3D%22url(%23banner-gradient)%22%2F%3E%3C%2Fsvg%3E",
|
|
284
|
+
"mobile": "data:image/svg+xml;charset=utf-8,%3Csvg%20xmlns%3D%22http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg%22%20width%3D%22640%22%20height%3D%22800%22%20viewBox%3D%220%200%20640%20800%22%3E%3Cdefs%3E%3ClinearGradient%20id%3D%22banner-gradient%22%20x1%3D%220%25%22%20y1%3D%220%25%22%20x2%3D%22100%25%22%20y2%3D%220%25%22%3E%3Cstop%20offset%3D%220%25%22%20stop-color%3D%22%23111827%22%2F%3E%3Cstop%20offset%3D%22100%25%22%20stop-color%3D%22%23b45309%22%2F%3E%3C%2FlinearGradient%3E%3C%2Fdefs%3E%3Crect%20width%3D%22100%25%22%20height%3D%22100%25%22%20fill%3D%22url(%23banner-gradient)%22%2F%3E%3C%2Fsvg%3E"
|
|
285
|
+
},
|
|
286
|
+
"presentation": {
|
|
287
|
+
"mode": "overlay",
|
|
288
|
+
"width": "full",
|
|
289
|
+
"height": "auto",
|
|
290
|
+
"aspect": "wide",
|
|
291
|
+
"fit": "cover",
|
|
292
|
+
"focal": "center",
|
|
293
|
+
"align": "start",
|
|
294
|
+
"radius": "lg",
|
|
295
|
+
"surface": "card",
|
|
296
|
+
"overlay": "gradient",
|
|
297
|
+
"overlayOpacity": "medium",
|
|
298
|
+
"padding": "lg",
|
|
299
|
+
"textScale": "lg"
|
|
300
|
+
},
|
|
301
|
+
"schedule": {
|
|
302
|
+
"from": "2026-11-01T00:00:00.000Z",
|
|
303
|
+
"to": "2026-11-30T23:59:59.000Z",
|
|
304
|
+
"timezone": "UTC"
|
|
305
|
+
},
|
|
306
|
+
"visible": true
|
|
307
|
+
}
|
|
308
|
+
]
|
|
309
|
+
},
|
|
310
|
+
"config": {
|
|
311
|
+
"schemaVersion": 1,
|
|
312
|
+
"blockId": "home-black-friday",
|
|
313
|
+
"name": "Black Friday home campaign",
|
|
314
|
+
"visible": true,
|
|
315
|
+
"scheduleAware": true,
|
|
316
|
+
"responsiveEnabled": true,
|
|
317
|
+
"presentation": "single",
|
|
318
|
+
"preset": "one",
|
|
319
|
+
"refs": [{ "bannerId": "black-friday-home" }],
|
|
320
|
+
"layout": {
|
|
321
|
+
"gapX": "md",
|
|
322
|
+
"gapY": "md",
|
|
323
|
+
"maxWidth": "full",
|
|
324
|
+
"maxHeight": "lg",
|
|
325
|
+
"align": "center",
|
|
326
|
+
"radius": "lg"
|
|
327
|
+
},
|
|
328
|
+
"carousel": {
|
|
329
|
+
"visible": { "base": 1, "md": 1, "2xl": 1 },
|
|
330
|
+
"autoplay": false,
|
|
331
|
+
"intervalMs": 6000,
|
|
332
|
+
"loop": false,
|
|
333
|
+
"indicators": false,
|
|
334
|
+
"carouselOnMobile": false,
|
|
335
|
+
"peek": false,
|
|
336
|
+
"story": false
|
|
337
|
+
},
|
|
338
|
+
"rules": {
|
|
339
|
+
"emptyLabel": "No banners available",
|
|
340
|
+
"inactiveLabel": "This campaign is not active",
|
|
341
|
+
"danglingLabel": "This banner is unavailable"
|
|
342
|
+
}
|
|
343
|
+
},
|
|
344
|
+
"now": "2026-11-06T12:00:00.000Z",
|
|
345
|
+
"banner": {
|
|
346
|
+
"carouselPrevious": "Previous banner",
|
|
347
|
+
"carouselNext": "Next banner",
|
|
348
|
+
"carouselStatus": "Banner {current} of {total}",
|
|
349
|
+
"carouselRole": "carousel",
|
|
350
|
+
"storyPrevious": "Previous story",
|
|
351
|
+
"storyNext": "Next story",
|
|
352
|
+
"storyRole": "stories"
|
|
353
|
+
}
|
|
354
|
+
}
|
|
355
|
+
}
|
|
356
|
+
],
|
|
357
|
+
"validator": { "export": "validateUniversalBannerData" }
|
|
358
|
+
}
|
|
82
359
|
}
|
|
83
360
|
]
|
|
84
361
|
}
|
package/recipes/validate.mjs
CHANGED
|
@@ -506,6 +506,88 @@ export function isCuratedFeature(name) {
|
|
|
506
506
|
return getFeature(name)?.mvp === true
|
|
507
507
|
}
|
|
508
508
|
|
|
509
|
+
/**
|
|
510
|
+
* The feature's declared lifecycle status. Absent status defaults to
|
|
511
|
+
* `executable` for a curated feature and `held` for a non-curated one, so an
|
|
512
|
+
* older registry keeps its previous meaning without a migration pass.
|
|
513
|
+
*/
|
|
514
|
+
export function featureStatus(name) {
|
|
515
|
+
const feature = getFeature(name)
|
|
516
|
+
if (!feature) return null
|
|
517
|
+
if (feature.status === 'executable' || feature.status === 'gated' || feature.status === 'held') {
|
|
518
|
+
return feature.status
|
|
519
|
+
}
|
|
520
|
+
return feature.mvp === true ? 'executable' : 'held'
|
|
521
|
+
}
|
|
522
|
+
|
|
523
|
+
const FEATURE_STATUSES = new Set(['executable', 'gated', 'held'])
|
|
524
|
+
const FEATURE_LIST_FIELDS = ['requires', 'backendCapabilities']
|
|
525
|
+
|
|
526
|
+
/**
|
|
527
|
+
* Validate the feature registry's lifecycle declarations. The published JSON
|
|
528
|
+
* schema covers shape; this covers the cross-entry invariants the schema cannot
|
|
529
|
+
* express (held needs a reason and an owner, status and `mvp` agree, a
|
|
530
|
+
* dependency names a real feature, and no feature depends on itself).
|
|
531
|
+
*
|
|
532
|
+
* Returns `{ ok, errors }`; the registry is read-only input.
|
|
533
|
+
*/
|
|
534
|
+
export function validateFeatureRegistry(registry = features) {
|
|
535
|
+
const errors = []
|
|
536
|
+
const list = Array.isArray(registry?.features) ? registry.features : []
|
|
537
|
+
const names = new Set()
|
|
538
|
+
|
|
539
|
+
for (const feature of list) {
|
|
540
|
+
if (!isPlainObject(feature) || typeof feature.name !== 'string' || feature.name === '') {
|
|
541
|
+
errors.push('Every feature entry needs a non-empty string "name".')
|
|
542
|
+
continue
|
|
543
|
+
}
|
|
544
|
+
const { name } = feature
|
|
545
|
+
if (names.has(name)) errors.push(`Feature "${name}" is declared more than once.`)
|
|
546
|
+
names.add(name)
|
|
547
|
+
|
|
548
|
+
const status = feature.status ?? (feature.mvp === true ? 'executable' : 'held')
|
|
549
|
+
if (!FEATURE_STATUSES.has(status)) {
|
|
550
|
+
errors.push(
|
|
551
|
+
`Feature "${name}" declares unknown status "${String(feature.status)}". Allowed: executable, gated, held.`
|
|
552
|
+
)
|
|
553
|
+
}
|
|
554
|
+
if (status === 'held') {
|
|
555
|
+
if (feature.mvp === true) {
|
|
556
|
+
errors.push(`Feature "${name}" is held and must not declare mvp: true.`)
|
|
557
|
+
}
|
|
558
|
+
if (typeof feature.reason !== 'string' || feature.reason.trim() === '') {
|
|
559
|
+
errors.push(`Held feature "${name}" must declare a non-empty "reason".`)
|
|
560
|
+
}
|
|
561
|
+
if (typeof feature.owner !== 'string' || feature.owner.trim() === '') {
|
|
562
|
+
errors.push(`Held feature "${name}" must declare a non-empty "owner".`)
|
|
563
|
+
}
|
|
564
|
+
} else if (feature.mvp !== true) {
|
|
565
|
+
errors.push(`Feature "${name}" is "${status}" and must declare mvp: true.`)
|
|
566
|
+
}
|
|
567
|
+
for (const field of FEATURE_LIST_FIELDS) {
|
|
568
|
+
if (!hasOwn(feature, field)) continue
|
|
569
|
+
const value = feature[field]
|
|
570
|
+
if (!Array.isArray(value) || value.some((item) => typeof item !== 'string' || item === '')) {
|
|
571
|
+
errors.push(`Feature "${name}" field "${field}" must be an array of non-empty strings.`)
|
|
572
|
+
}
|
|
573
|
+
}
|
|
574
|
+
}
|
|
575
|
+
|
|
576
|
+
for (const feature of list) {
|
|
577
|
+
if (!isPlainObject(feature) || typeof feature.name !== 'string') continue
|
|
578
|
+
const requires = Array.isArray(feature.requires) ? feature.requires : []
|
|
579
|
+
for (const dependency of requires) {
|
|
580
|
+
if (dependency === feature.name) {
|
|
581
|
+
errors.push(`Feature "${feature.name}" must not require itself.`)
|
|
582
|
+
} else if (!names.has(dependency)) {
|
|
583
|
+
errors.push(`Feature "${feature.name}" requires unknown feature "${dependency}".`)
|
|
584
|
+
}
|
|
585
|
+
}
|
|
586
|
+
}
|
|
587
|
+
|
|
588
|
+
return { ok: errors.length === 0, errors }
|
|
589
|
+
}
|
|
590
|
+
|
|
509
591
|
/**
|
|
510
592
|
* The starter composition: every curated (installable) feature plus every
|
|
511
593
|
* curated view no installed curated feature owns. A feature-owned view (for
|
|
@@ -523,7 +605,7 @@ export function starterComposition(registries = {}) {
|
|
|
523
605
|
const recipeSource = registries.recipes ?? recipes
|
|
524
606
|
const featureSource = registries.features ?? features
|
|
525
607
|
const featureNames = featureSource.features
|
|
526
|
-
.filter((f) => f.mvp === true)
|
|
608
|
+
.filter((f) => f.mvp === true && f.starter !== false)
|
|
527
609
|
.map((f) => f.name)
|
|
528
610
|
const ownedViews = new Set()
|
|
529
611
|
for (const name of featureNames) {
|
|
@@ -0,0 +1,41 @@
|
|
|
1
|
+
// Read-only access to `recipes/adapter-surface.json`: the callables a generated
|
|
2
|
+
// storefront may import from the adapter/commerce contract. The manifest is
|
|
3
|
+
// generated from the real sources by `scripts/generate-adapter-surface.mjs` and
|
|
4
|
+
// shipped with the package, so the CLI can validate a feature's declared needs
|
|
5
|
+
// without importing TypeScript or reading a consumer's installed packages.
|
|
6
|
+
|
|
7
|
+
import { existsSync, readFileSync } from 'node:fs'
|
|
8
|
+
import { dirname, join } from 'node:path'
|
|
9
|
+
import { fileURLToPath } from 'node:url'
|
|
10
|
+
|
|
11
|
+
const here = dirname(fileURLToPath(import.meta.url))
|
|
12
|
+
const SURFACE_FILE = join(here, '..', 'recipes', 'adapter-surface.json')
|
|
13
|
+
|
|
14
|
+
let cached = null
|
|
15
|
+
|
|
16
|
+
function readSurface() {
|
|
17
|
+
if (cached) return cached
|
|
18
|
+
if (!existsSync(SURFACE_FILE)) {
|
|
19
|
+
throw new Error(
|
|
20
|
+
`adapter surface manifest is missing at ${SURFACE_FILE}. Run node scripts/generate-adapter-surface.mjs before packaging.`,
|
|
21
|
+
)
|
|
22
|
+
}
|
|
23
|
+
cached = JSON.parse(readFileSync(SURFACE_FILE, 'utf8'))
|
|
24
|
+
return cached
|
|
25
|
+
}
|
|
26
|
+
|
|
27
|
+
/** Every callable name the surface allows, across provider and runtime lists. */
|
|
28
|
+
export function surfaceNames() {
|
|
29
|
+
const surface = readSurface()
|
|
30
|
+
return new Set([
|
|
31
|
+
...(Array.isArray(surface.commerce) ? surface.commerce : []),
|
|
32
|
+
...(Array.isArray(surface.auth) ? surface.auth : []),
|
|
33
|
+
...(Array.isArray(surface.runtime) ? surface.runtime : []),
|
|
34
|
+
])
|
|
35
|
+
}
|
|
36
|
+
|
|
37
|
+
/** The declared needs that the surface does not contain, in declaration order. */
|
|
38
|
+
export function unknownNeeds(needs) {
|
|
39
|
+
const names = surfaceNames()
|
|
40
|
+
return (Array.isArray(needs) ? needs : []).filter((need) => !names.has(need))
|
|
41
|
+
}
|