@thorprovider/storefront 0.6.2 → 0.7.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 (30) hide show
  1. package/assets/templates/app/lib/__STOREFRONT__/actions.ts +649 -31
  2. package/assets/templates/app/lib/__STOREFRONT__/checkout-shipping.core.ts +37 -0
  3. package/assets/templates/app/lib/__STOREFRONT__/commerce.ts +117 -0
  4. package/assets/templates/app/lib/__STOREFRONT__/state.core.ts +7 -1
  5. package/assets/templates/app/lib/__STOREFRONT__/views/sections/index.ts +2 -1
  6. package/assets/templates/app/lib/__STOREFRONT__/views/sections/marketplace-product-card.client.tsx +19 -0
  7. package/assets/templates/app/lib/__STOREFRONT__/views/sections/marketplace-product-card.tsx +16 -0
  8. package/assets/templates/app/lib/__STOREFRONT__/views/sections/schema.marketplace-product-card.ts +67 -0
  9. package/assets/templates/features/checkout/handlers.ts +326 -31
  10. package/assets/templates/features/checkout/state.ts +79 -3
  11. package/assets/templates/views/checkout/content.ts +63 -2
  12. package/assets/templates/views/checkout/index.tsx +6 -0
  13. package/assets/templates/views/checkout/props.ts +61 -21
  14. package/assets/templates/views/checkout/registry.tsx +300 -33
  15. package/assets/templates/views/checkout/schema.ts +184 -8
  16. package/assets/templates/views/home/assembly/assembly.json +7 -0
  17. package/package.json +1 -1
  18. package/recipes/recipe.schema.json +1 -1
  19. package/recipes/recipes.json +2 -1
  20. package/recipes/sections.json +9 -0
  21. package/scripts/candidate.mjs +1 -1
  22. package/scripts/file-classes.mjs +1 -0
  23. package/skills/sf-view-gen/SKILL.md +6 -0
  24. package/skills/sf-view-gen/assets/recipes/recipes.json +2 -1
  25. package/skills/sf-view-gen/assets/recipes/sections.json +9 -0
  26. package/skills/sf-view-gen/assets/templates/views/sections/marketplace-product-card.client.tsx +19 -0
  27. package/skills/sf-view-gen/assets/templates/views/sections/marketplace-product-card.tsx +16 -0
  28. package/skills/sf-view-gen/assets/templates/views/sections/schema.marketplace-product-card.ts +67 -0
  29. package/skills/storefront-workflow/SKILL.md +5 -0
  30. package/skills/storefront-workflow/references/mobile-responsiveness.md +1 -1
@@ -105,23 +105,199 @@ export const paymentMethodSchema = z.object({
105
105
  .optional(),
106
106
  })
107
107
 
108
+ const checkoutReadStateSchema = z.enum(['idle', 'pending', 'error', 'unavailable'])
109
+ const checkoutAddressOptionSchema = z.object({ value: z.string(), label: z.string() })
110
+ const checkoutAddressLevelSchema = z.enum(['countries', 'provinces', 'cities'])
111
+ const checkoutLocationOptionsSchema = z.object({
112
+ countries: z.array(checkoutAddressOptionSchema),
113
+ provinces: z.array(checkoutAddressOptionSchema),
114
+ cities: z.array(checkoutAddressOptionSchema),
115
+ countriesState: checkoutReadStateSchema.optional(),
116
+ provincesState: checkoutReadStateSchema.optional(),
117
+ citiesState: checkoutReadStateSchema.optional(),
118
+ countriesError: z.string().optional(),
119
+ provincesError: z.string().optional(),
120
+ citiesError: z.string().optional(),
121
+ })
122
+ const checkoutAddressValuesSchema = z.object({
123
+ firstName: z.string(),
124
+ lastName: z.string(),
125
+ address1: z.string(),
126
+ address2: z.string().optional(),
127
+ company: z.string().optional(),
128
+ city: z.string(),
129
+ province: z.string().optional(),
130
+ postalCode: z.string().optional(),
131
+ countryCode: z.string(),
132
+ phone: z.string().optional(),
133
+ })
134
+ const checkoutContactValuesSchema = z.object({
135
+ email: z.string(),
136
+ firstName: z.string(),
137
+ lastName: z.string(),
138
+ phone: z.string(),
139
+ })
140
+ const checkoutCustomerIdentitySchema = z.object({
141
+ id: z.string(),
142
+ email: z.string(),
143
+ firstName: z.string().optional(),
144
+ lastName: z.string().optional(),
145
+ })
146
+ const checkoutSavedAddressSchema = z.object({
147
+ id: z.string(),
148
+ label: z.string().optional(),
149
+ address: checkoutAddressValuesSchema,
150
+ isDefaultShipping: z.boolean().optional(),
151
+ isDefaultBilling: z.boolean().optional(),
152
+ })
153
+ const checkoutSavedAddressStateSchema = z.object({
154
+ pendingId: z.string().optional(),
155
+ error: z
156
+ .object({
157
+ id: z.string().optional(),
158
+ message: z.string(),
159
+ })
160
+ .optional(),
161
+ lastSavedId: z.string().optional(),
162
+ lastAction: z.enum(['saved', 'deleted']).optional(),
163
+ })
164
+ const checkoutShippingOptionSchema = z.object({
165
+ id: z.string(),
166
+ name: z.string(),
167
+ price: moneySchema.optional(),
168
+ description: z.string().optional(),
169
+ estimatedDays: z.string().optional(),
170
+ pickup: z.boolean().optional(),
171
+ locationName: z.string().optional(),
172
+ disabled: z.boolean().optional(),
173
+ disabledReason: z.string().optional(),
174
+ })
175
+ const checkoutShippingGroupSchema = z.object({
176
+ id: z.string(),
177
+ label: z.string().optional(),
178
+ // Mirrors `CheckoutShippingGroupItem`: backend line membership, present only
179
+ // when the host mapped every backend variant to one cart line.
180
+ items: z
181
+ .array(z.object({ lineId: z.string(), quantity: z.number().optional() }))
182
+ .optional(),
183
+ itemCount: z.number().optional(),
184
+ options: z.array(checkoutShippingOptionSchema),
185
+ selectedOptionId: z.string().optional(),
186
+ unavailableReason: z.string().optional(),
187
+ })
188
+ const checkoutAdjustmentPaymentSchema = z.object({
189
+ id: z.string(),
190
+ kind: z.enum(['gift-card', 'store-credit']),
191
+ label: z.string(),
192
+ amount: moneySchema,
193
+ })
194
+ const checkoutInterruptionSchema = z.object({
195
+ kind: z.enum([
196
+ 'totals-changed',
197
+ 'price-changed',
198
+ 'stock-reduced',
199
+ 'item-unavailable',
200
+ 'session-expired',
201
+ 'payment-failed',
202
+ ]),
203
+ severity: z.enum(['info', 'blocking']),
204
+ title: z.string(),
205
+ message: z.string(),
206
+ changes: z
207
+ .array(
208
+ z.object({
209
+ lineId: z.string().optional(),
210
+ label: z.string(),
211
+ previous: z.string().optional(),
212
+ next: z.string().optional(),
213
+ }),
214
+ )
215
+ .optional(),
216
+ actions: z.array(z.enum(['acknowledge', 'refresh', 'return-to-cart', 'retry'])),
217
+ })
218
+ const checkoutAvailabilitySchema = z.object({
219
+ status: z.enum(['available', 'empty', 'unavailable', 'error']),
220
+ reason: z.string().optional(),
221
+ actionLabel: z.string().optional(),
222
+ })
223
+
108
224
  export const checkoutPropsSchema = z.object({
109
225
  title: z.string().optional(),
110
226
  description: z.string().optional(),
111
- presentation: z.enum(['single-page', 'stepper']).optional(),
227
+ presentation: z.enum(['single-page', 'accordion', 'stepper']).optional(),
112
228
  showReviewStep: z.boolean().optional(),
229
+ requireContactPhone: z.boolean().optional(),
230
+ requireShippingPhone: z.boolean().optional(),
113
231
  labels: z.record(z.string(), z.string()).optional(),
114
- orderSummary: orderSummarySchema.optional(),
115
- countries: z.array(countryOptionSchema).optional(),
116
- shippingOptions: z.array(shippingOptionSchema).optional(),
117
- // Nullable: the state initializes to `null` and the block prop is optional.
118
- selectedShippingOptionId: z.string().nullable().optional(),
232
+ contact: checkoutContactValuesSchema,
233
+ shippingAddress: checkoutAddressValuesSchema,
234
+ billingAddress: checkoutAddressValuesSchema.optional(),
235
+ sameAsShipping: z.boolean(),
236
+ paymentMethod: z.string(),
237
+ customer: checkoutCustomerIdentitySchema.nullish(),
238
+ savedAddresses: z.array(checkoutSavedAddressSchema).optional(),
239
+ savedAddressState: checkoutSavedAddressStateSchema.optional(),
240
+ shippingLocations: checkoutLocationOptionsSchema.optional(),
241
+ billingLocations: checkoutLocationOptionsSchema.optional(),
242
+ shippingGroups: z.array(checkoutShippingGroupSchema).optional(),
243
+ shippingState: checkoutReadStateSchema.optional(),
244
+ paymentState: checkoutReadStateSchema.optional(),
119
245
  paymentMethods: z.array(paymentMethodSchema).optional(),
120
- values: checkoutFormDataSchema,
121
- fieldErrors: checkoutFieldErrorsSchema.optional(),
246
+ adjustmentPayments: z.array(checkoutAdjustmentPaymentSchema).optional(),
247
+ orderSummary: orderSummarySchema.optional(),
248
+ totalsState: z.enum(['idle', 'pending', 'error']).optional(),
249
+ promoCode: z.string().optional(),
250
+ fieldErrors: z.record(z.string(), z.unknown()).optional(),
122
251
  fieldDescriptions: z.record(z.string(), z.string()).optional(),
252
+ availability: checkoutAvailabilitySchema.optional(),
253
+ interruption: checkoutInterruptionSchema.optional(),
123
254
  })
124
255
 
256
+ /**
257
+ * Local step gate for the shipping address. The backend remains authoritative;
258
+ * this keeps a missing first street line from advancing or submitting before the
259
+ * server sync can reject it.
260
+ */
261
+ export function validateCheckoutShippingAddress(address: {
262
+ firstName: string
263
+ lastName: string
264
+ address1: string
265
+ city: string
266
+ countryCode: string
267
+ phone?: string
268
+ }, requirePhone = false): Record<string, Array<{ message: string }>> {
269
+ const errors: Record<string, Array<{ message: string }>> = {}
270
+ if (!address.firstName.trim()) {
271
+ errors.firstName = [{ message: 'El nombre es obligatorio.' }]
272
+ }
273
+ if (!address.lastName.trim()) {
274
+ errors.lastName = [{ message: 'Los apellidos son obligatorios.' }]
275
+ }
276
+ if (!address.address1.trim()) {
277
+ errors.address1 = [{ message: 'La línea 1 de dirección es obligatoria.' }]
278
+ }
279
+ if (!address.city.trim()) {
280
+ errors.city = [{ message: 'La ciudad es obligatoria.' }]
281
+ }
282
+ if (!address.countryCode.trim()) {
283
+ errors.countryCode = [{ message: 'El país es obligatorio.' }]
284
+ }
285
+ if (requirePhone && !address.phone?.trim()) {
286
+ errors.phone = [{ message: 'El teléfono es obligatorio.' }]
287
+ }
288
+ return errors
289
+ }
290
+
291
+ export function validateCheckoutContactPhone(
292
+ contact: { phone: string },
293
+ requirePhone: boolean,
294
+ ): Record<string, Array<{ message: string }>> {
295
+ if (requirePhone && !contact.phone.trim()) {
296
+ return { phone: [{ message: 'El teléfono es obligatorio.' }] }
297
+ }
298
+ return {}
299
+ }
300
+
125
301
  // The empty-cart surface has no props; declared so the catalog is complete.
126
302
  export const checkoutEmptyPropsSchema = z.object({})
127
303
 
@@ -28,6 +28,13 @@
28
28
  "defaultProps": "{}",
29
29
  "dataBound": true,
30
30
  "defaultVariant": "ProductGrid"
31
+ },
32
+ "marketplace-product-card": {
33
+ "elementType": "MarketplaceProductCard",
34
+ "registryModule": "../sections/marketplace-product-card.client",
35
+ "registryExport": "marketplaceProductCardRegistry",
36
+ "propsModule": "./content",
37
+ "defaultProps": "{}"
31
38
  }
32
39
  }
33
40
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@thorprovider/storefront",
3
- "version": "0.6.2",
3
+ "version": "0.7.0",
4
4
  "description": "Deterministic storefront scaffolder and installable OpenCode skill suite for Thor Commerce (Next.js, @thorprovider/blocks, @thorprovider/adapters, Medusa)",
5
5
  "type": "module",
6
6
  "bin": "bin/storefront.js",
@@ -58,7 +58,7 @@
58
58
  },
59
59
  "allowedSections": {
60
60
  "type": "array",
61
- "items": { "type": "string", "enum": ["faq", "cta"] }
61
+ "items": { "type": "string" }
62
62
  },
63
63
  "maxSections": { "type": "number" }
64
64
  }
@@ -47,7 +47,8 @@
47
47
  "allowedSections": [
48
48
  "faq",
49
49
  "cta",
50
- "products"
50
+ "products",
51
+ "marketplace-product-card"
51
52
  ],
52
53
  "maxSections": 4
53
54
  },
@@ -70,6 +70,15 @@
70
70
  "propsHint": "title, description, tiers[] (name, price, features, cta)",
71
71
  "status": "held",
72
72
  "reason": "bounded curation: no verified backend/data source for pricing tiers and no verified presentation bridge/provenance in the current composition"
73
+ },
74
+ {
75
+ "name": "marketplace-product-card",
76
+ "description": "MarketplaceProductCard presentation section (delivery marketplace-product-card).",
77
+ "elementType": "MarketplaceProductCard",
78
+ "variants": ["MarketplaceProductCard"],
79
+ "defaultVariant": "MarketplaceProductCard",
80
+ "propsHint": "data (product, labels, glyphs)",
81
+ "status": "executable"
73
82
  }
74
83
  ]
75
84
  }
@@ -46,7 +46,7 @@ export const CANDIDATE_TOOLSET = Object.freeze({
46
46
  '@thorprovider/blocks': '3.0.2',
47
47
  '@thorprovider/adapters': '5.2.2',
48
48
  '@thorprovider/runtime': '0.4.2',
49
- '@thorprovider/types': '7.0.0',
49
+ '@thorprovider/types': '7.1.0',
50
50
  }),
51
51
  })
52
52
 
@@ -66,6 +66,7 @@ const RULES = [
66
66
  'app/lib/*/store-context.ts',
67
67
  'app/lib/*/commerce.ts',
68
68
  'app/lib/*/cart-state.ts',
69
+ 'app/lib/*/checkout-shipping.core.ts',
69
70
  'app/lib/*/actions.ts',
70
71
  'app/lib/*/catalog.ts',
71
72
  'app/lib/*/section-sources.ts',
@@ -28,6 +28,12 @@ list in this skill**: `views --json` reports the authoritative curated set
28
28
  `static`) annotated with `installed` and `supported`, so a view added to or
29
29
  removed from the registry is reflected without editing this text.
30
30
 
31
+ The checkout view schema and user-owned props must mirror the canonical
32
+ structured `Checkout` contract: controlled `contact`, `shippingAddress`,
33
+ `billingAddress`, `sameAsShipping`, `paymentMethod`, host-supplied location
34
+ options and shipping groups. The block never fetches or prefills; keep the
35
+ customer/address read in the host.
36
+
31
37
  `views --json` and `recipes --json` also report, per view, `registeredSlots` (the
32
38
  non-removable core slots), `allowedSections` (the section types the view may
33
39
  host), and `maxSections` (the editorial-instance bound), plus a top-level
@@ -47,7 +47,8 @@
47
47
  "allowedSections": [
48
48
  "faq",
49
49
  "cta",
50
- "products"
50
+ "products",
51
+ "marketplace-product-card"
51
52
  ],
52
53
  "maxSections": 4
53
54
  },
@@ -70,6 +70,15 @@
70
70
  "propsHint": "title, description, tiers[] (name, price, features, cta)",
71
71
  "status": "held",
72
72
  "reason": "bounded curation: no verified backend/data source for pricing tiers and no verified presentation bridge/provenance in the current composition"
73
+ },
74
+ {
75
+ "name": "marketplace-product-card",
76
+ "description": "MarketplaceProductCard presentation section (delivery marketplace-product-card).",
77
+ "elementType": "MarketplaceProductCard",
78
+ "variants": ["MarketplaceProductCard"],
79
+ "defaultVariant": "MarketplaceProductCard",
80
+ "propsHint": "data (product, labels, glyphs)",
81
+ "status": "executable"
73
82
  }
74
83
  ]
75
84
  }
@@ -0,0 +1,19 @@
1
+ 'use client'
2
+
3
+ // Optional section fragment: marketplace-product-card (mirrors recipes/sections.json) — client registry.
4
+ // The matching server-side catalog lives in marketplace-product-card.tsx. @thorprovider/blocks ships a
5
+ // 'use client' boundary, but this fragment keeps the explicit client boundary so
6
+ // the section composes identically in any consumer graph.
7
+
8
+ import { MarketplaceProductCard } from '@thorprovider/blocks'
9
+ import { marketplaceProductCardPropsSchema } from './schema.marketplace-product-card'
10
+ import type { ViewRegistry } from '../types'
11
+
12
+ export const marketplaceProductCardRegistry: ViewRegistry = {
13
+ MarketplaceProductCard: ({ props }) => {
14
+ const parsed = marketplaceProductCardPropsSchema.parse(props)
15
+ return (
16
+ <MarketplaceProductCard data={parsed.data} />
17
+ )
18
+ },
19
+ }
@@ -0,0 +1,16 @@
1
+ // Optional section fragment: marketplace-product-card (mirrors recipes/sections.json)
2
+ // Server-side part: element type + zod catalog entry. The component mappings
3
+ // live in marketplace-product-card.client.tsx ('use client') and are composed via composeSections.
4
+
5
+ import { marketplaceProductCardPropsSchema } from './schema.marketplace-product-card'
6
+
7
+ export const marketplaceProductCardSection = {
8
+ elementType: 'MarketplaceProductCard',
9
+ catalog: {
10
+ MarketplaceProductCard: {
11
+ props: marketplaceProductCardPropsSchema,
12
+ description: 'MarketplaceProductCard presentation section (delivery marketplace-product-card).',
13
+ },
14
+ },
15
+ registryModule: './marketplace-product-card.client',
16
+ }
@@ -0,0 +1,67 @@
1
+ // Optional section fragment: marketplace-product-card (mirrors recipes/sections.json) — shared contract.
2
+ // Zod mirror of the MarketplaceProductCard block contract (delivery marketplace-product-card, contract version 3.0.2),
3
+ // shared by the server catalog (marketplace-product-card.tsx) and the client registry (marketplace-product-card.client.tsx).
4
+ // The React-only callbacks (onAddToCart, onToggleWishlist) are intentionally excluded.
5
+
6
+ import { z } from 'zod'
7
+ import { moneySchema } from '@thorprovider/blocks/contracts'
8
+
9
+ export const marketplaceProductCardDataSchema = z.object({
10
+ product: z.object({
11
+ id: z.string(),
12
+ brand: z.string(),
13
+ title: z.string(),
14
+ badge: z.string(),
15
+ rating: z.number(),
16
+ reviewCount: z.number(),
17
+ ratingLabel: z.string(),
18
+ soldLabel: z.string(),
19
+ shippingLabel: z.string(),
20
+ deliveryLabel: z.string(),
21
+ currency: z.string(),
22
+ locale: z.string(),
23
+ image: z.string(),
24
+ options: z.array(z.object({
25
+ id: z.string(),
26
+ name: z.string(),
27
+ kind: z.enum(["image", "text"]),
28
+ values: z.array(z.object({
29
+ id: z.string(),
30
+ label: z.string(),
31
+ image: z.string().optional(),
32
+ imageAlt: z.string().optional(),
33
+ })),
34
+ })),
35
+ variants: z.array(z.object({
36
+ id: z.string(),
37
+ optionValueIds: z.object({
38
+ colour: z.string(),
39
+ size: z.string(),
40
+ }),
41
+ price: moneySchema,
42
+ compareAtPrice: moneySchema.optional(),
43
+ available: z.boolean(),
44
+ stockLabel: z.string(),
45
+ stockTone: z.enum(["success", "attention", "destructive"]),
46
+ })),
47
+ }),
48
+ labels: z.object({
49
+ addToCart: z.string(),
50
+ wishlistAdd: z.string(),
51
+ wishlistRemove: z.string(),
52
+ unavailableOption: z.string(),
53
+ unavailablePrice: z.string(),
54
+ outOfStock: z.string(),
55
+ optionSeparator: z.string(),
56
+ }),
57
+ glyphs: z.object({
58
+ fullStar: z.string(),
59
+ emptyStar: z.string(),
60
+ heart: z.string(),
61
+ heartFilled: z.string(),
62
+ }),
63
+ })
64
+
65
+ export const marketplaceProductCardPropsSchema = z.object({
66
+ data: marketplaceProductCardDataSchema,
67
+ })
@@ -168,6 +168,11 @@ customization cannot invent a canonical.
168
168
  - The `checkout` feature ships structural wiring only; the purchase flow is
169
169
  owned by the separate `single-tenant-commerce-mvp` change. A generated
170
170
  storefront is not a complete commerce implementation on its own.
171
+ - The canonical `Checkout` block is controlled and structured: contact,
172
+ shipping/billing addresses, `sameAsShipping`, payment, shipping groups, and
173
+ totals are host state. Country, province/state, and city are host-supplied
174
+ selectors; authenticated customer profile/address prefill is host-owned. Do
175
+ not add fetch or prefill logic to the block.
171
176
 
172
177
  ## References
173
178
 
@@ -98,7 +98,7 @@ Over 60% of ecommerce traffic is mobile. Mobile-first design is essential for co
98
98
  - 44-48px input height minimum
99
99
  - Proper keyboard types (`inputMode="email"`, `"numeric"`, `"tel"`)
100
100
  - Autocomplete attributes for autofill (`autocomplete="email"`, `"name"`, `"address-line1"`)
101
- - Consider single-page layout over multi-step (less friction on mobile)
101
+ - Consider the single-page layout over a step-by-step flow when it reduces mobile friction. Checkout also has an `accordion` presentation: all step headers stay visible while one section is open. The consumer chooses among `single-page`, `accordion`, and `stepper` rather than switching layouts automatically by viewport.
102
102
 
103
103
  ## Touch-Friendly Interactions
104
104