@thorprovider/blocks 3.0.2 → 4.1.0

package/README.md

@@ -15,6 +15,7 @@ Reusable storefront UI blocks for Thor Commerce, built from [ShadcnStore](https:
 - **Single source of primitives.** The vendored shadcn primitives under `src/ui/` are the only copy; consumers import them from this package instead of installing their own.
 - **No over-abstraction.** Values are split into props vs internal detail with judgment. A prop is added only when the value is genuinely content or configuration; layout and decoration stay internal.
 - **Shared contracts only when reused.** A type like `CTA` is promoted to `src/lib/types.ts` only once two blocks share it.
+- **Consistent motion.** State transitions use the shared motion scale and honor reduced-motion preferences; see the [block motion standard](docs/standards/motion.md).
 
 ## Structure
 
@@ -62,7 +63,7 @@ Blocks follow `src/blocks/<category>/<section>/<block>.tsx`. Each block co-locat
 | `ProductCategory` | E-commerce | Canonical category block; bounded `presentation` `grid` (image cards) / `icons` (compact icon grid) / `list` (rows with subcategory chips and optional controlled search) |
 | `CategoryListing` | E-commerce | Canonical category listing (results + pagination) with a controlled query and bounded `presentation` `sidebar` (persistent desktop panel + mobile sheet) / `toolbar` (sticky mobile toolbar + drawers); generic facet groups render only from real metadata |
 | `ShoppingCart` | E-commerce | Canonical cart; backend-authoritative `Money` totals and item lines, optional promo entry and recently-viewed suggestions; `presentation` `compact` (collapsible card) or `page` (full-width review) |
-| `Checkout` | E-commerce | Canonical page-level checkout; controlled values, backend-authoritative `Money` totals, `PaymentMethod[]` data with no raw card input; `presentation` `single-page` or `stepper`, optional `showReviewStep` |
+| `Checkout` | E-commerce | Canonical page-level checkout; controlled values, backend-authoritative `Money` totals, `PaymentMethod[]` data with no raw card input; `presentation` `single-page`, `accordion`, or `stepper`, optional `showReviewStep` |
 | `CheckoutConfirmation` | E-commerce | Order confirmation with fulfilment timeline |
 | `OrderHistory` | E-commerce | Canonical order-history collection; `presentation` `cards` or `rows`, order-level `Money` totals rendered verbatim, status as data, host-owned pagination and actions |
 | `OrderLine` | E-commerce | Canonical order-line item cell (`name`, optional image/details, quantity, `Money` line total) used inside `OrderHistory` |
@@ -317,32 +318,51 @@ with Spanish defaults (`Agregar al carrito`, `Precio no disponible`, …).
 
 ## Checkout block (page-level, controlled)
 
-`Checkout` is the single public checkout surface; it replaces the numbered `CheckoutForm1`, `CheckoutForm2`, and `CheckoutForm3` blocks. It is a **controlled component**: field values arrive through `values` and every edit is reported through `onChange`, so the host owns all commercial state. The block owns only the ephemeral step index of the `stepper` presentation.
-
-- `presentation: 'single-page' | 'stepper'` (required) — `single-page` renders every section visible at once (summary first in DOM order on mobile); `stepper` shows one step at a time with an accessible progress indicator. Both accept the same props and emit the same callbacks.
-- `showReviewStep?: boolean` — appends a confirmation step (`stepper`) or section (`single-page`) before submission.
-- `values: CheckoutValues` — `email`, `firstName`, `lastName`, `phone`, `address`, `city`, `state`, `zipCode`, `country`, `paymentMethod`, `saveInfo`, `newsletter`, `promoCode`. There are no card fields.
-- `onChange: (field, value) => void` — reported per edit. The block holds no private copy of the form data and applies no masking.
-- `orderSummary?: { items, totals? }` — line identity, name, quantity, optional variant/image, optional canonical `Money` `lineTotal` and `unitPrice`, plus backend `totals` (`subtotal`, optional `discount`/`tax`/`shipping`, `total`). Amounts render verbatim; required totals that are absent or malformed render as unavailable with the retry action, never as zero. No local arithmetic, tax rate, shipping cost, threshold, or hardcoded currency.
-- `totalsState?: 'idle' | 'pending' | 'error'` and `onRetryTotals?` — controlled reads; pending and failed states render status/alert copy without inventing amounts.
-- `countries?: { value, label }[]`, `shippingOptions?`, `selectedShippingOptionId?`, `onSelectShippingOption?` — host-owned options and selection. With no country list the block renders a text input; with no shipping options it renders no method section; nothing is pre-selected.
-- `paymentMethods?: PaymentMethod[]` — payment methods as data (canonical `@thorprovider/types`). One option per method, the selected method's description, an empty state for an empty list, and a non-selectable rendering for `isEnabled === false`. The block renders **no raw card fields**: card collection belongs to the host payment-provider surface.
-- `labels?: Partial<CheckoutLabels>` and `formatMoney?: (money: Money) => string` — every user-facing string is overridable (neutral English defaults) and amounts format through canonical `Money` with no hardcoded symbol.
-- `fieldErrors?` / `fieldDescriptions?` — per-field messages and helper text, rendered with `role="alert"` and `aria-invalid`/`aria-describedby` wiring.
-- `validateStep?: (step: CheckoutStepId) => boolean` and `onStepChange?` — the block consults `validateStep` before advancing and for every applicable step before submitting; `onStepChange` is a notification only, never a controlled value. Without the callback the block advances and leaves submit protection to the host.
-- `onSubmit?`, `submitting?`, `submitError?`, `onRetrySubmit?` — submission is reported, with a pending guard and a recoverable error state; the block never creates an order, clears a cart, or claims success.
+`Checkout` is the single public checkout surface; it replaces the numbered `CheckoutForm1`, `CheckoutForm2`, and `CheckoutForm3` blocks. It is a **controlled component**: contact, shipping, billing, selections, and totals arrive as props; edits are reported through callbacks. The block owns only ephemeral UI state (step index, gift-card input, saved-address create mode and delete confirmation). It performs no HTTP, reads no session/customer/address book, computes no totals, and never creates an order.
+
+- `presentation: 'single-page' | 'accordion' | 'stepper'` and `showReviewStep?` — all three presentations accept the same data and emit the same callbacks; the summary is first in DOM order on `single-page`.
+  - `single-page` keeps every numbered folio section visible and includes an in-page index that reports the section in view, not completion.
+  - `accordion` keeps every step header visible with one section expanded. Closed headers show supplied-value summaries when available, never a completion check; header navigation is not gated by validation.
+  - `stepper` shows one step at a time with a compact progress indicator and Continue/Back actions.
+- `contact: CheckoutContactValues`, `onContactChange`, `customer?`, `onSignIn?`, `onSignOut?` — guest email or a host-supplied authenticated identity. No password, token, or credential fields are rendered.
+- `shippingAddress`, `billingAddress?`, `sameAsShipping`, `onShippingAddressChange`, `onBillingAddressChange?`, `onSameAsShippingChange` — structured addresses. `billingAddress` may be supplied while `sameAsShipping` is true; it is rendered only when the shopper unchecks it.
+- `savedAddresses?`, `onSelectSavedAddress?`, `onCreateSavedAddress?`, `onUpdateSavedAddress?`, `onDeleteSavedAddress?`, `onStartNewAddress?`, `onCancelNewAddress?`, `savedAddressState?` — saved addresses are host data. The shipping picker reports the selection and shows contextual create/update/delete actions only when the corresponding callbacks are supplied; the host mutates and returns the refreshed list. `savedAddressState` carries `pendingId`, `error`, `lastSavedId`, and `lastAction` so the block can render per-entry pending/error states and politely announce saved/deleted results. `CheckoutSavedAddress` carries both `isDefaultShipping` and `isDefaultBilling`. Billing saved-address management is out of scope.
+- `shippingLocations?`, `billingLocations?`, `onRetryLocations?` — host-supplied country, province/state, and city options with per-level loading/error/unavailable states. The block disables a child until its parent is selected. There is no free-text fallback.
+- `shippingGroups?`, `shippingState?`, `onSelectShippingOption?`, `onRetryShipping?` — opaque delivery groups with one selection per group and explicit unavailable groups. The MVP may supply one group. Each group may carry optional `items: CheckoutShippingGroupItem[]` (`{ lineId, quantity? }`) for the review projection. With two or more groups, the review renders one card per group with the selected method, the host-formatted estimate, the per-group price, and the group items; with one group it keeps the compact delivery row and the flat lines list. Group item lists render only when every group item resolves to an order line and every line's quantity is assigned exactly once; otherwise the review falls back to the flat lines list. Prices and estimates are host-supplied and rendered verbatim; the block never sums group prices, allocates the shipping total, or formats dates.
+- `paymentMethods?`, `paymentState?`, `paymentMethod`, `onSelectPaymentMethod`, `onRetryPayment?` — payment methods as data. No raw card fields.
+- `adjustmentPayments?`, `onApplyGiftCard?`, `giftCardState?`, `giftCardMessage?`, `onRemoveAdjustment?`, `storeCredit?` — optional host-wired gift card and store credit. Applied amounts render verbatim; the block never computes a remaining balance.
+- `orderSummary?`, `totalsState?`, `onRetryTotals?`, `promoCode?`, `onPromoCodeChange?`, `onApplyPromo?`, `promoPending?`, `trustNotes?` — backend-authoritative lines and `Money` totals, rendered verbatim. Required totals that are absent or malformed render unavailable, never zero.
+- `labels?`, `formatMoney?`, `fieldErrors?`, `fieldDescriptions?` — every user-facing string is overridable and amounts format through canonical `Money` with no hardcoded symbol. Errors use structured nested maps for `contact`, `shippingAddress`, `billingAddress`, and `paymentMethod`. Delivery-group copy uses `reviewDeliveryGroupsLabel`, `reviewGroupLabel` (`{n}`/`{total}` placeholders), and `reviewGroupItemsLabel`.
+- `validateStep?`, `onStepChange?`, `availability?`, `interruption?`, `onInterruptionAction?`, `submitting?`, `submitError?`, `onRetrySubmit?`, `onSubmit?` — the block consults injected validation before advancing and submitting, renders host-classified availability/interruption states, reports one submission, and never declares success. `onSubmit` receives a `CheckoutSubmission` snapshot.
+
+In `single-page`, every visible step begins with a numbered folio heading (`01`,
+`02`, …) and a hairline separator. The number sits in a desktop gutter while the
+heading, description, and fields share one aligned content column; the form stays
+one continuous surface rather than nesting a card for each step. All sections
+remain expanded, so the ordinal communicates sequence without implying that a
+section is complete.
+
+The shipping form groups the **recipient** first: `firstName`, `lastName`, `company`, and `phone` sit under `recipientHeading` with `recipientDescription`. These fields identify the person receiving the order, not necessarily the signed-in buyer, and are independent of the `contact` identity. The delivery address follows in this order: `address1` (required, labelled “Address line 1”), `address2` (optional, labelled “Address line 2 (optional)”), `countryCode`, `province`, `city`, and `postalCode`; country therefore sits immediately above state/province. Billing reuses the same fields under its own heading without the recipient legend.
+
+Phone labels follow the same copy convention as other checkout fields: optional phones append `optionalIndicatorLabel` (default “optional”), while required phones have no suffix and set `aria-required`. Buyer/contact and recipient/shipping phone requirements are declared independently with `requireContactPhone` and `requireShippingPhone`; the block does not enforce phone presence.
+
+Prefill is host-owned. The host reads the authenticated customer's profile and default addresses, fills only empty fields, and never overwrites cart or shopper-entered values; guests receive no customer prefill. The block receives the mapped `customer`, `savedAddresses`, and controlled values and does not fetch or choose defaults.
 
 Validation itself is **not** implemented in the block. Declare checks in your store spec's validation configuration (built-in `required`/`email`/`pattern`/`minLength`/`maxLength`/cross-field `requiredIf`/`equalTo`/`lessThan`/`greaterThan`, plus catalog-registered custom functions) and evaluate them with the renderer; the messages live in the spec so they are per-store and per-language.
 
 The order summary is an internal projection of `Checkout`, not a separate block. Order receipt and fulfilment progress remain `CheckoutConfirmation`.
 
-### Migrating from the numbered checkout blocks
+### Migrating to the structured checkout contract
 
-| Retired | Replacement |
-| --- | --- |
-| `CheckoutForm1` | `<Checkout presentation="stepper" />` — same controlled values minus `cardNumber`/`expiryDate`/`cvv`/`cardName`/`sameAsBilling`; `validateStep` now receives a `CheckoutStepId` (`'contact' \| 'shipping' \| 'payment' \| 'review'`) instead of a number |
-| `CheckoutForm2` | `<Checkout presentation="single-page" />` — the host supplies `Money` totals; the block no longer computes tax, shipping, or free-shipping thresholds |
-| `CheckoutForm3` | `<Checkout presentation="stepper" showReviewStep />` — values become controlled; `apartment`, card fields, per-step icons, and internal `isStepComplete` state are gone |
+This is a **breaking major** for `@thorprovider/blocks`. The flat `CheckoutValues` contract is replaced.
+
+- Replace `values` + `onChange` with `contact` + `onContactChange`, `shippingAddress` + `onShippingAddressChange`, `billingAddress` + `onBillingAddressChange`, and `sameAsShipping` + `onSameAsShippingChange`.
+- Replace the flat address fields (`address`, `state`, `zipCode`, `country`) with `CheckoutAddressValues` (`address1`, `address2`, `company`, `city`, `province`, `postalCode`, `countryCode`, `phone`).
+- Replace `countries` with `shippingLocations` / `billingLocations`; country, province/state, and city are selectors, never free-text inputs.
+- Replace `shippingOptions` / `selectedShippingOptionId` / `onSelectShippingOption(id)` with `shippingGroups` / `onSelectShippingOption(groupId, optionId)`.
+- Add `customer`, `savedAddresses`, `paymentState`, `shippingState`, `availability`, `interruption`, `fieldErrors`, and the new labels as needed.
+- `validateStep` still receives a `CheckoutStepId` (`'contact' | 'shipping' | 'payment' | 'review'`); `onSubmit` now receives a `CheckoutSubmission` snapshot instead of the flat values.
+- Update the storefront template, showcase consumers, and every fixture in the same change; publish a major changeset.
 
 
 ## Order history (canonical)
@@ -478,6 +498,26 @@ yarn workspace @thorprovider/blocks build    # dist/ with .d.ts
 
 The `'use client'` banner is injected at build time (tsup `banner`) so the bundled library is consumed correctly by Next.js.
 
+## Block audit
+
+`audit/` renders a public block directly in Chromium through Vitest Browser Mode
+with a typed fixture. No Next.js app, showcase, storefront, or Storybook is
+required.
+
+```bash
+yarn workspace @thorprovider/blocks audit --block ProductCard
+yarn workspace @thorprovider/blocks workflow status ProductCard
+```
+
+Fixtures live in `audit/fixtures/` and are keyed by the public export name. A
+block without a fixture is reported as unauditable, not silently skipped.
+Findings and screenshots are written to `.blocks-audit/<Block>/` (gitignored).
+The repo-level `blocks-audit` skill documents the audit -> propose -> fix ->
+review workflow, its two approval gates, and the coordinator/worker execution
+contract. Screenshots use a deterministic system font stack and are
+illustrative; pixel baselines and the committed accepted-findings baseline are
+deferred. The pilot is report-only.
+
 ## Adding a new block
 
 1. Install the raw block as a seed: `npx shadcn@latest add @shadcnstore/<block> --cwd packages/blocks`

package/dist/blocks/designs/checkout-commerce-v1/block.d.ts

@@ -0,0 +1,49 @@
+import type { CheckoutCommerceV1Data } from '../../../lib/contracts/checkout-commerce-v1';
+type AssociatePayload = {
+    associateId: string;
+    parentLineId: string;
+    lineId: string;
+    groupId: string;
+    quantity: number;
+    unitCents: number;
+};
+type AddressData = {
+    id: string;
+    label: string;
+    recipient: string;
+    line1: string;
+    line2: string;
+    city: string;
+    province: string;
+    postalCode: string;
+    phone: string;
+    isDefault: boolean;
+};
+type CreatedAddressPayload = AddressData & {
+    saveToAccount: boolean;
+};
+type GuestContact = {
+    name: string;
+    email: string;
+    phone: string;
+};
+type OrderSnapshot = {
+    reference: string;
+    totalCents: number;
+    paymentId: string;
+    groupIds: string[];
+};
+export type CheckoutCommerceV1Props = {
+    data: CheckoutCommerceV1Data;
+    onQuantityChange?: (lineId: string, quantity: number) => void;
+    onRemoveItem?: (lineId: string) => void;
+    onSelectAddress?: (addressId: string) => void;
+    onCreateAddress?: (payload: CreatedAddressPayload) => void;
+    onStartRegistration?: (contact: GuestContact) => void;
+    onAddAssociate?: (payload: AssociatePayload) => void;
+    onConfirmOrder?: (snapshot: OrderSnapshot) => void;
+    onContinueShopping?: () => void;
+};
+export default function CheckoutCommerceV1({ data, ...props }: CheckoutCommerceV1Props): import("react").JSX.Element;
+export {};
+//# sourceMappingURL=block.d.ts.map

package/dist/blocks/designs/checkout-commerce-v1/block.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"block.d.ts","sourceRoot":"","sources":["../../../../src/blocks/designs/checkout-commerce-v1/block.tsx"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,6CAA6C,CAAA;AAwBzF,KAAK,gBAAgB,GAAG;IACtB,WAAW,EAAE,MAAM,CAAA;IACnB,YAAY,EAAE,MAAM,CAAA;IACpB,MAAM,EAAE,MAAM,CAAA;IACd,OAAO,EAAE,MAAM,CAAA;IACf,QAAQ,EAAE,MAAM,CAAA;IAChB,SAAS,EAAE,MAAM,CAAA;CAClB,CAAA;AAED,KAAK,WAAW,GAAG;IACjB,EAAE,EAAE,MAAM,CAAA;IACV,KAAK,EAAE,MAAM,CAAA;IACb,SAAS,EAAE,MAAM,CAAA;IACjB,KAAK,EAAE,MAAM,CAAA;IACb,KAAK,EAAE,MAAM,CAAA;IACb,IAAI,EAAE,MAAM,CAAA;IACZ,QAAQ,EAAE,MAAM,CAAA;IAChB,UAAU,EAAE,MAAM,CAAA;IAClB,KAAK,EAAE,MAAM,CAAA;IACb,SAAS,EAAE,OAAO,CAAA;CACnB,CAAA;AAiCD,KAAK,qBAAqB,GAAG,WAAW,GAAG;IAAE,aAAa,EAAE,OAAO,CAAA;CAAE,CAAA;AAErE,KAAK,YAAY,GAAG;IAClB,IAAI,EAAE,MAAM,CAAA;IACZ,KAAK,EAAE,MAAM,CAAA;IACb,KAAK,EAAE,MAAM,CAAA;CACd,CAAA;AAED,KAAK,aAAa,GAAG;IACnB,SAAS,EAAE,MAAM,CAAA;IACjB,UAAU,EAAE,MAAM,CAAA;IAClB,SAAS,EAAE,MAAM,CAAA;IACjB,QAAQ,EAAE,MAAM,EAAE,CAAA;CACnB,CAAA;AAkCD,MAAM,MAAM,uBAAuB,GAAG;IACpC,IAAI,EAAE,sBAAsB,CAAC;IAC7B,gBAAgB,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,KAAK,IAAI,CAAA;IAC7D,YAAY,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,IAAI,CAAA;IACvC,eAAe,CAAC,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,IAAI,CAAA;IAC7C,eAAe,CAAC,EAAE,CAAC,OAAO,EAAE,qBAAqB,KAAK,IAAI,CAAA;IAC1D,mBAAmB,CAAC,EAAE,CAAC,OAAO,EAAE,YAAY,KAAK,IAAI,CAAA;IACrD,cAAc,CAAC,EAAE,CAAC,OAAO,EAAE,gBAAgB,KAAK,IAAI,CAAA;IACpD,cAAc,CAAC,EAAE,CAAC,QAAQ,EAAE,aAAa,KAAK,IAAI,CAAA;IAClD,kBAAkB,CAAC,EAAE,MAAM,IAAI,CAAA;CAChC,CAAA;AAugGD,MAAM,CAAC,OAAO,UAAU,kBAAkB,CAAC,EAAE,IAAI,EAAE,GAAG,KAAK,EAAE,EAAE,uBAAuB,+BAMrF"}