@vtex/faststore 0.0.5 → 0.0.6

package/dist/docs/shipping-address.md

@@ -1,7 +1,7 @@
 # ShippingAddress
 
 **Category:** commerce
-**Purpose:** Country-adaptive single-address delivery form. Batches all address fields and writes them once via `shipping.setAddress`; optionally lets a logged-in shopper pick a saved address instead of typing one.
+**Purpose:** Country-adaptive single-address delivery form. Batches all address fields and dispatches them once, at form-submit time, via `shipping.setAddress`.
 
 ---
 
@@ -12,309 +12,164 @@ Use these signals to detect that a ShippingAddress block is present. Position on
 A ShippingAddress block contains any combination of:
 
 - A **country dropdown** listing country names (e.g. "Brazil", "United States").
-- An optional **"select a saved address"** button (drawer trigger) — shown only for logged-in shoppers; opens a drawer listing saved addresses to select quickly without typing the full form.
-- A list of **saved-address options** above or alongside the form, each rendered as a radio button or selectable card showing a street + number summary — shown only for logged-in shoppers (in the drawer or inline).
 - Labeled **input fields** for street, number, city, state, and postal code.
 - A **recipient name** field, often showing a pre-filled name as its value.
 - An optional **"Complement"** field (apartment, suite, unit).
 - A **"Neighborhood"** field — present only for Brazil-shaped forms, absent for US-shaped forms.
-- A **"Save address"** (or similar) submit button, possibly showing a "Saving..." pending label.
-- An **error banner** with either a specific validation message (e.g. "Saved address is no longer available") or a generic retry message (e.g. "We couldn't save this address. Please review and retry.").
+- A **submit button** shared with the rest of the page's form, possibly showing a pending label while a write is in flight.
+- An **error banner** showing domain validation messages or a generic failure state.
 
-If the image shows **any one** of the above, use `ShippingAddressRoot`. Pick only the sub-components that match what's visible — never include a sub-component for data that isn't shown.
+If the image shows **any one** of the above, use `ShippingAddressFieldset` inside a `FormRoot`. Pick only the sub-components that match what's visible — never include a sub-component for data that isn't shown.
 
 ---
 
 ## When to use
 
 - The delivery/shipping step of checkout where a shopper enters or confirms a single delivery address for the whole order.
-- Anywhere a shopper needs to choose between a saved address and a manually-entered one before proceeding to delivery-option selection.
+- Composed alongside other entities (e.g. the shopper's profile) behind one shared submit button.
 
 ## When NOT to use
 
 - Address autocomplete, postal-code lookup, or search-as-you-type flows — this form is manual entry only; no lookup provider is wired in.
-- Profile management screens (editing a shopper's saved addresses in account settings) — this form is order-scoped; selecting or editing a saved address here never writes back to the saved profile.
+- Profile management screens (editing a shopper's saved addresses in account settings) — this form is order-scoped.
 - Per-item / per-line delivery address selection — this component addresses the whole cart with one address, not split shipments.
 - The delivery-options (shipping method) selection step → that is a separate section that extends the same `shipping` action namespace with `selectOption`.
+- Letting a logged-in shopper pick from a list of saved addresses — there is no saved-address UI in this catalog; every address is typed into the form.
 
 ---
 
 ## Composition
 
-`ShippingAddressRoot` is the only entry point. All Controls, the saved-address list, the submit, and the error banner must be descendants of it.
-
-The **summary/form toggle** (`EditController`, `SummaryView`, `EditForm`, `EditButton`) is an optional composable layer that splits the Controls and SelectedSummary into a summary branch and a form branch, letting a shopper review a saved address before deciding to edit it. There is one component per state rather than one component taking a state name, so a page cannot misspell the state it means. See the dedicated section below.
+`ShippingAddressFieldset` is the only entry point, and it must be a descendant of `FormRoot`. Compose `FormSubmit`/`FormError` as siblings of the fieldset, not inside it — the fieldset renders no submit or error part of its own.
 
 ```
-ShippingAddressRoot
-├── EditController                          (optional; owns the summary/form state; compose its two panels inside)
-│   ├── SummaryView                         (optional; renders only while the section shows the summary)
-│   │   ├── SelectedSummary                 (read-only formatted address)
-│   │   └── EditButton                      (CTA to open the form)
-│   └── EditForm                            (optional; renders only while the section shows the form)
-│       ├── [form controls/submit/error]
-│       └── CancelButton                    (returns to the summary without writing)
-├── CountryControl                          (selector; lists only countries with a descriptor)
-├── SavedAddressDrawerController            (optional; wraps a DrawerRoot for the saved-address selection drawer — US-8)
-│   └── DrawerRoot                          (generic Drawer particle; composed directly, no wrapper)
-│       ├── DrawerTrigger                   (button labeled "selecione um endereço salvo", etc.)
-│       └── DrawerPortal
-│           ├── DrawerBackdrop
-│           └── DrawerPopup
-│               ├── DrawerTitle
-│               ├── DrawerClose
-│               ├── SavedList               (renders only when savedAddresses is non-empty)
-│               │   └── SavedOption         (one per saved address; id required; isCurrent variant marks current address)
-│               ├── Error
-│               └── SavedAddressSubmit      (dispatches drawer submit; no-op if reselecting current address — US-8)
-├── RecipientNameControl                    (required; defaults from ClientProfile)
-├── StreetControl
-├── NumberControl
-├── ComplementControl
-├── NeighborhoodControl                     (renders only for countries whose descriptor includes it, e.g. Brazil)
-├── CityControl
-├── StateControl
-├── PostalCodeControl
-├── SavedList                               (optional; renders only when savedAddresses is non-empty)
-│   └── SavedOption                         (one per saved address; id required)
-├── Submit                                  (dispatches the batched write; exposes pending state)
-├── SelectedSummary                         (optional; read-only formatted current address; self-gates to null when there is none)
-└── Error                                   (domain userErrors inline, or a generic upstream-error state)
+FormRoot
+├── ShippingAddressFieldset
+│   ├── CountryControl                  (selector; lists only countries with a descriptor)
+│   ├── RecipientNameControl            (required; defaults from ClientProfile)
+│   ├── StreetControl
+│   ├── NumberControl
+│   ├── ComplementControl
+│   ├── NeighborhoodControl             (renders only for countries whose descriptor includes it, e.g. Brazil)
+│   ├── CityControl
+│   └── StateControl / PostalCodeControl
+├── FormError                            (sibling of the fieldset, not a child)
+└── FormSubmit                           (sibling of the fieldset, not a child)
 ```
 
 Child order reflects visual order — place Controls in the same sequence they appear in the image. The country descriptor also governs field order (see Common mistakes for what happens when a field is descriptor-less for the active country).
 
 **Composition rules:**
 
-- Every Control, `SavedList`, `Submit`, `SelectedSummary`, and `Error` must be a descendant of `ShippingAddressRoot` — each throws if rendered outside it.
-- `SavedAddressDrawerController` (optional, US-8) wraps a `DrawerRoot` and must be a descendant of `ShippingAddressRoot`. The drawer trigger and popup (including `SavedList`, `SavedAddressSubmit`, and error/state) are `DrawerRoot` descendants inside `SavedAddressDrawerController`.
-- `SavedOption` must be a descendant of `SavedList` (which itself renders only when `savedAddresses` is non-empty).
-- `SavedAddressSubmit` (US-8) must be a descendant of the `SavedAddressDrawerController`'s `DrawerRoot` (typically inside `DrawerPopup`).
+- Every Control must be a descendant of `ShippingAddressFieldset` — each throws if rendered outside it.
+- `ShippingAddressFieldset` must be a descendant of `FormRoot` — it throws its own named error otherwise.
 - `NeighborhoodControl` renders `null` when the active country's descriptor omits it (e.g. United States in v1) — safe to include speculatively, but only place it in the schema if the target country is expected to show it.
-- Only one `ShippingAddressRoot` per section; do not nest a second one inside it.
+- Only one `ShippingAddressFieldset` per `FormRoot`; a second one under the same `shippingAddress` namespace throws at mount.
 
 ---
 
 ## Components
 
-### ShippingAddressRoot
+### ShippingAddressFieldset
 
-Root container. Owns the batched draft state (keyed by canonical field name, not by descriptor), the current country descriptor, saved-address list, submit/error state, and provides context to all descendants. Declares `actions: { shipping: ['setAddress'] }`.
+Registers under the `shippingAddress` namespace with an ancestor `FormRoot`; renders one `<fieldset>` and no submit or error part of its own — compose `FormSubmit`/`FormError` as siblings of the fieldset instead of inside it. Declares `actions: { shipping: ['setAddress'] }`.
 
 | Prop | Type | Default | Notes |
 |------|------|---------|-------|
 | `defaultCountry` | string | `"BRA"` | ISO alpha-3 country code used when no address exists yet |
+| `skeletonCount` | number | `9` | Placeholder rows drawn while the address resolves. Set it to the number of Controls composed. |
+| `loadingLabel` | string | `"Loading your delivery address"` | Announced politely while the address resolves. Blank means no announcement. |
+| `loadedLabel` | string | `"Your delivery address is ready"` | Announced politely once the Controls mount. Blank means no announcement. |
+| `groupLabel` | string | `"Your delivery address"` | Accessible name of the `<fieldset>` group. Blank means no name is exposed. |
 
-**Data:** declares `fragment ShippingAddressData on Query` (`shipping { address savedAddresses }` + `clientProfile { firstName lastName }`), `fetchStrategy: 'reactive'`. The compiler merges it into the page query — no explicit `dataSources` entry needed.
-
-### RecipientNameControl
-
-The recipient-name input. The only client-validated field: submit is blocked while it is blank. Defaults from `clientProfile.firstName`/`lastName` (joined) as a real, editable value — not a placeholder hint — whenever the address (current or a selected saved address) has no recipient name yet; degrades to an empty required field when the profile has neither part. No props beyond `className`.
-
-### StreetControl / NumberControl / CityControl / StateControl / PostalCodeControl / ComplementControl
-
-Thin field Controls; each renders `null` when the active country's descriptor omits that field. No props beyond `className`.
-
-### NeighborhoodControl
-
-Same shape as the other field Controls. Renders only for countries whose descriptor includes a neighborhood field (Brazil in v1); renders `null` for others (United States in v1). Its draft value is retained (not cleared) when hidden, so it reappears with the same value if the shopper switches back to a country that shows it.
-
-### CountryControl
-
-Country selector. Lists only countries with an implemented descriptor (Brazil and United States in v1) — a descriptor-less country is unreachable. Switching country preserves the values of fields the two descriptors share (keyed by canonical field name) and only adds/removes country-specific fields. Disabled while a submit is in flight. No props beyond `className`.
-
-### SavedList
-
-Container for saved-address options. Renders only when `savedAddresses` is non-empty — this is the logged-in signal; anonymous shoppers get an empty list and the container renders nothing. No props beyond `className`.
-
-### SavedOption
-
-A single selectable saved address. Selecting it populates the batched draft (still editable before submit) and retains its ID through submit so VTEX maintains the saved-address reference for this order.
-
-Renders the saved address using the same formatted display as `SelectedSummary` — both compose the `AddressSummary` particle (recipient, street/number/complement, neighborhood/city/state/postal code) via its own `AddressSummaryRoot` context provider, so they share one formatting implementation without code duplication. Falls back to a generic "Endereço {id}" label only when the saved record has no recognizable content (no recipient name, street, city, or neighborhood).
-
-Includes an `isCurrent` state: when the saved address's ID matches `currentAddressId` (the current cart address), it renders the `data-fs-shipping-address-saved-option-current` attribute, signaling that this is the already-selected delivery address. The component renders no default visual styling for this state itself — it's a pure styling hook, left to the merchant/page to style (or not) via that attribute.
+**Data:** declares `fragment ShippingAddressFieldsetData on Query` (`shipping { address }` + `clientProfile { id firstName lastName }`), `fetchStrategy: 'reactive'`. The compiler merges it into the page query — no explicit `dataSources` entry needed.
 
-| Prop | Type | Default | Notes |
-|------|------|---------|-------|
-| `id` | string | — | Required. The saved address's ID; must match an entry in `savedAddresses` |
-
-### SavedAddressDrawerController
-
-Wraps a single `DrawerRoot` child (the saved-address selection drawer) and makes it controlled by a dedicated drawer-flow context, kept separate from the main `ShippingAddressContext` that every field Control reads (so the Root's data/actions context stays unaware of this one downstream UI surface). Open state and blocked dismissal while submitting are handled here. Do not set raw `open` or `onOpenChange` on the wrapped `DrawerRoot` — pass them through `SavedAddressDrawerController` instead (the same pattern as `CartOpenOnAdd` in the mini-cart).
-
-Blocks drawer dismissal (Escape, backdrop click, close button) while a drawer submit is in flight (`drawerSubmitting` is true) to prevent accidental loss of an in-flight submission.
+**Loading:** the Controls mount once, after the entity has resolved; until then the `<fieldset>` carries `data-fs-shipping-address-fieldset-pending` and renders `ShippingAddressFieldsetSkeleton` itself, in their place. Each Control hands its seed to react-hook-form as a field-level `defaultValue`, re-applied on every render for as long as the field stays clean — mounting before the answer arrives would seed `''`, and a shopper who starts typing before it lands makes the field dirty on that empty seed, permanently locking their saved address out of it; even a shopper who does not type sees the field flash from `''` to the real data. Resolution is the page query settling, latched, and this entity actually resolving: a later refetch never takes the Controls down, so nothing the shopper typed is lost, but if the entity itself stops resolving the fieldset returns to its skeleton and dispatches nothing until it resolves again.
 
-| Prop | Type | Default | Notes |
-|------|------|---------|-------|
-| `children` | ReactNode | — | Required. A single `DrawerRoot` element; other elements are passed through unchanged. |
+`skeletonCount` sizes the wait. The skeleton draws nine rows by default, one per Control in the full anatomy, and it cannot do better on its own — it renders before any address exists, so there is no descriptor to read, and the composed Controls are opaque children. A page composing the eight BRA fields sets `skeletonCount: 8`, or the form jumps by a row when the Controls take the skeleton's place. The skeleton is `aria-hidden` — the wait is spoken instead by a polite live region the fieldset keeps mounted in both states, carrying `loadingLabel` and then `loadedLabel`, with `aria-busy` on the `<fieldset>` for as long as it lasts.
 
 **Composition rules:**
+- Must be a descendant of `FormRoot`; throws its own named error otherwise.
+- Compose `FormSubmit` and `FormError` as siblings, not children — the fieldset renders no submit or error part.
+- Only one `ShippingAddressFieldset` per `FormRoot`; a second one under the same `shippingAddress` namespace throws at mount.
 
-- Must be a descendant of `ShippingAddressRoot`.
-- Must be the parent of `DrawerRoot` (the drawer trigger and popup are `DrawerRoot` descendants).
-- The wrapped `DrawerRoot` must have `DrawerTrigger`, `DrawerPortal`, `DrawerBackdrop`, `DrawerPopup`, `DrawerTitle`, and `DrawerClose` descendants inside it, using the standard `Drawer` particle architecture.
-
-### SavedAddressSubmit
-
-The drawer's "selecionar" (select) submit button; independent submitting state from the main form's `Submit` button (Decision 7 in the spec). Dispatches the drawer submit via `handleDrawerSubmit`.
-
-**Special behavior (Decision 8 in the spec):** when a saved address is selected and submitted, if it is already the current cart address (its ID matches `currentAddressId`), the drawer closes silently with no action — reselecting the current address is a no-op.
-
-**Special behavior (Decision 9 in the spec):** when the selected saved address has a blank `recipientName`, no mutation is dispatched either — the drawer closes and the main form (already populated with that address's fields, since selecting a saved option always seeds the draft) is left for the shopper to add the missing name and submit themselves, rather than auto-submitting into a guaranteed `MISSING_RECIPIENT_NAME` rejection.
-
-| Prop | Type | Default | Notes |
-|------|------|---------|-------|
-| `label` | string | `"selecionar"` | Button label shown when not submitting |
-| `pendingLabel` | string | `"selecionando..."` | Button label shown while the drawer submit is in flight |
-
-### Submit
-
-Dispatches the batched write through `shipping.setAddress` exactly once per click, including when the shopper changed nothing: the component cannot tell whether the stored address would be accepted, so it lets the server decide rather than deciding on its behalf. Disabled while the recipient name is blank or a submit is already in flight; shows a pending label/attribute while in flight, and re-enables once the write resolves.
-
-| Prop | Type | Default | Notes |
-|------|------|---------|-------|
-| `label` | string | `"salvar endereço"` | Button label shown when not submitting |
-| `pendingLabel` | string | `"salvando..."` | Button label shown while the submit is in flight |
-
-### SelectedSummary
+**Overriding a control's text:** every field Control also takes optional `label` and `placeholder` props. Absence means the platform's value — the active country descriptor's label where one exists (e.g. "cidade" for `CityControl`), the control's own copy where none does (`CountryControl`'s "país"). Neither has a schema default, so an author only sets one when the platform copy is wrong for their store.
 
-Provides the current delivery address to the generic `AddressSummary` particle via `AddressSummaryRoot` context, and renders it by default. Self-gates to `null` when there is none yet (e.g. a first-time order with an empty `Shipping.address`), rather than an empty provider.
+**Recomposing a control's anatomy:** every field Control declares `providesContext: 'field'` (RFC:503), so a `Field.*` part composed inside one is not a context-constraint-violation. Given children, a field Control renders them in place of its default `Field.Label` / `Field.Control` / `Field.Error` (or, for `CountryControl`, `Field.Label` / `FieldSelect.Root` / `Field.Error`) — useful to reorder the label against the input or insert an icon. The binding underneath is unchanged either way.
 
-The `AddressSummary` particle it composes displays the address in read-only format (recipient name, street/number/complement, neighborhood/city/state/postal code). `SavedOption` uses the same `AddressSummary` particle (with its own `AddressSummaryRoot`) so both the "current address" display and each saved-address option in the list/drawer share one formatting implementation without duplication.
-
-A future alternative presentation component (e.g., `LeanAddressSummary`) could read the same `AddressSummaryRoot` context and be composed as a child, without any change to this component — exemplifying the Free Particle Model.
-
-| Prop | Type | Default | Notes |
-|------|------|---------|-------|
-| `className` | string | — | Optional CSS classes applied to the `AddressSummary` container, whether the lines are the default ones or composed |
-| `children` | ReactNode | — | Optional line composition, rendered *inside* the `AddressSummary` container in place of its default lines. Must be a descendant of the provided `AddressSummaryRoot` context. |
-
-### EditController
-
-Optional composable component that owns the summary/form toggle. Opens on the summary when a current address exists, on the form otherwise. When a successful `setAddress` completes (via the main form's `Submit` or the drawer's `SavedAddressSubmit`), it returns to the summary on its own without either submit component needing to know this section collapses around it (mirrors the `cartLastAddVar` pulse-signal pattern in the mini-cart). Everything it does it decides from its own data and the shopper's own presses; it reports to nothing, so finishing it opens no other section, and no other section opens it.
-
-Once a shopper explicitly opens the form (via `EditButton`), the explicit choice takes over until either a successful submit or a press of `CancelButton` returns the section to the summary. Does not render any DOM itself; wraps children and provides the `shipping-address-section` context to descendant `SummaryView`, `EditForm`, `EditButton` and `CancelButton` components.
-
-| Prop | Type | Default | Notes |
-|------|------|---------|-------|
-| `children` | ReactNode | — | Required. Typically holds a `SummaryView` and an `EditForm`. |
-
-**Composition rules:**
-- Must be a descendant of `ShippingAddressRoot`.
-- Typically wraps the whole delivery-address section (all form Controls, Submit, Error, SelectedSummary) so all of it can be split between the two panels.
-- Compose `SummaryView` and `EditForm` children to place the parts that belong to each state.
-
-### SummaryView / EditForm
-
-The section's two panels. `SummaryView` renders its children only while the section shows the saved-address summary; `EditForm` only while it shows the editable form. Neither takes a state prop — which state it gates is which component it is, so a page cannot name a state that has no branch and blank the section.
-
-| Prop | Type | Default | Notes |
-|------|------|---------|-------|
-| `children` | ReactNode | — | Rendered only while the section is in this component's state. |
-
-**Composition rules:**
-- Both must be descendants of `EditController`.
-- Typically, `SummaryView` holds `SelectedSummary` + `EditButton` (read-only branch) and `EditForm` holds the form Controls, Submit, Error, and `CancelButton`.
-
-### EditButton
+### RecipientNameControl
 
-CTA that opens the form. Has no knowledge of why the section might currently be on the summary (a current address exists, or a just-completed submit returned to it) — it only writes the state forward. Usually placed inside a `SummaryView`, next to `SelectedSummary`.
+The recipient-name input. The only required field: submit is blocked while it is blank. Defaults from `clientProfile.firstName`/`lastName` (joined) as a real, editable value — not a placeholder hint — whenever the stored address has no recipient name yet; degrades to an empty required field when the profile has neither part. No props beyond `className`, `label`, `placeholder`.
 
-| Prop | Type | Default | Notes |
-|------|------|---------|-------|
-| `label` | string | `"editar"` | Button label shown when no children are composed |
-
-### CancelButton
+### StreetControl / NumberControl / CityControl / StateControl / PostalCodeControl / ComplementControl
 
-Returns the section to its summary without writing. Compose it inside the `EditForm` whenever the
-`EditButton` is reachable: a shopper who opens the form otherwise has no way back except a successful
-`setAddress`, and blanking the recipient name disables Submit, which strands them on a form covering the
-summary they came from.
+Thin field Controls; each renders `null` when the active country's descriptor omits that field. `PostalCodeControl` is additionally client-validated against the active country's format (CEP for Brazil, ZIP/ZIP+4 for the United States) — a malformed value blocks submit even though the field is not required. No props beyond `className`, `label`, `placeholder`.
 
-| Prop | Type | Default | Notes |
-|------|------|---------|-------|
-| `label` | string | `"cancelar"` | Button label shown when no children are composed |
-| `children` | ReactNode | — | Custom content, e.g. an `Icon` plus text; falls back to `label` |
-| `className` | string | — | Optional CSS classes |
+### NeighborhoodControl
 
-**Composition rules:**
-- Must be a descendant of `EditController`.
-- Compose it inside the `EditForm`. Inside a `SummaryView` it renders only while the form is closed,
-  which is precisely when there is nothing to cancel.
+Same shape as the other field Controls. Renders only for countries whose descriptor includes a neighborhood field (Brazil in v1); renders `null` for others (United States in v1). Its draft value is retained (not cleared) when hidden, so it reappears with the same value if the shopper switches back to a country that shows it.
 
-### Error
+### CountryControl
 
-Renders domain `userErrors` returned by `setAddress` (e.g. `MISSING_RECIPIENT_NAME`, `INVALID_SAVED_ADDRESS_ID`) as an inline list, or a single generic message when the mutation throws (surfaced as a synthetic upstream/network error). Form values are retained in either case. No props beyond `className`.
+Country selector. Lists only countries with an implemented descriptor (Brazil and United States in v1) — a descriptor-less country is unreachable. Switching country preserves the values of fields the two descriptors share (keyed by canonical field name) and only adds/removes country-specific fields. No props beyond `className`, `label`, `placeholder`.
 
 ---
 
 ## Canonical schema example
 
-A full delivery-address step with saved addresses, all field Controls, and the error/submit pair:
+The nine field Controls, batched behind a form-level submit:
 
 ```json
 {
-  "shipping-address": {
-    "type": "ShippingAddressRoot",
-    "props": { "defaultCountry": "BRA" },
+  "checkout-form": {
+    "type": "FormRoot",
+    "children": ["shipping-address-fieldset", "form-error", "form-submit"]
+  },
+  "shipping-address-fieldset": {
+    "type": "ShippingAddressFieldset",
     "children": [
-      "shipping-address-saved-list",
-      "shipping-address-country",
-      "shipping-address-recipient",
-      "shipping-address-street",
-      "shipping-address-number",
-      "shipping-address-complement",
-      "shipping-address-neighborhood",
-      "shipping-address-city",
-      "shipping-address-state",
-      "shipping-address-postal-code",
-      "shipping-address-error",
-      "shipping-address-submit"
+      "fieldset-country",
+      "fieldset-recipient",
+      "fieldset-street",
+      "fieldset-number",
+      "fieldset-complement",
+      "fieldset-neighborhood",
+      "fieldset-city",
+      "fieldset-state",
+      "fieldset-postal-code"
     ]
   },
-  "shipping-address-saved-list": {
-    "type": "ShippingAddressSavedList",
-    "children": ["shipping-address-saved-option"]
-  },
-  "shipping-address-saved-option": {
-    "type": "ShippingAddressSavedOption",
-    "props": { "id": "addr-1" }
-  },
-  "shipping-address-country": { "type": "ShippingAddressCountryControl" },
-  "shipping-address-recipient": { "type": "ShippingAddressRecipientNameControl" },
-  "shipping-address-street": { "type": "ShippingAddressStreetControl" },
-  "shipping-address-number": { "type": "ShippingAddressNumberControl" },
-  "shipping-address-complement": { "type": "ShippingAddressComplementControl" },
-  "shipping-address-neighborhood": { "type": "ShippingAddressNeighborhoodControl" },
-  "shipping-address-city": { "type": "ShippingAddressCityControl" },
-  "shipping-address-state": { "type": "ShippingAddressStateControl" },
-  "shipping-address-postal-code": { "type": "ShippingAddressPostalCodeControl" },
-  "shipping-address-error": { "type": "ShippingAddressError" },
-  "shipping-address-submit": {
-    "type": "ShippingAddressSubmit",
-    "props": { "label": "Save address" }
-  }
+  "fieldset-country": { "type": "ShippingAddressCountryControl" },
+  "fieldset-recipient": { "type": "ShippingAddressRecipientNameControl" },
+  "fieldset-street": { "type": "ShippingAddressStreetControl" },
+  "fieldset-number": { "type": "ShippingAddressNumberControl" },
+  "fieldset-complement": { "type": "ShippingAddressComplementControl" },
+  "fieldset-neighborhood": { "type": "ShippingAddressNeighborhoodControl" },
+  "fieldset-city": { "type": "ShippingAddressCityControl" },
+  "fieldset-state": { "type": "ShippingAddressStateControl" },
+  "fieldset-postal-code": { "type": "ShippingAddressPostalCodeControl" },
+  "form-error": { "type": "FormError" },
+  "form-submit": { "type": "FormSubmit", "props": { "label": "Continue" } }
 }
 ```
 
-### Minimal variant (manual entry only, no saved addresses visible)
+### Minimal variant (manual entry only)
 
 ```json
 {
-  "shipping-address": {
-    "type": "ShippingAddressRoot",
-    "children": [
-      "shipping-address-recipient",
-      "shipping-address-street",
-      "shipping-address-postal-code",
-      "shipping-address-submit"
-    ]
+  "checkout-form": {
+    "type": "FormRoot",
+    "children": ["shipping-address-fieldset", "form-submit"]
   },
-  "shipping-address-recipient": { "type": "ShippingAddressRecipientNameControl" },
-  "shipping-address-street": { "type": "ShippingAddressStreetControl" },
-  "shipping-address-postal-code": { "type": "ShippingAddressPostalCodeControl" },
-  "shipping-address-submit": { "type": "ShippingAddressSubmit" }
+  "shipping-address-fieldset": {
+    "type": "ShippingAddressFieldset",
+    "props": { "skeletonCount": 3 },
+    "children": ["fieldset-recipient", "fieldset-street", "fieldset-postal-code"]
+  },
+  "fieldset-recipient": { "type": "ShippingAddressRecipientNameControl" },
+  "fieldset-street": { "type": "ShippingAddressStreetControl" },
+  "fieldset-postal-code": { "type": "ShippingAddressPostalCodeControl" },
+  "form-submit": { "type": "FormSubmit" }
 }
 ```
 
@@ -322,37 +177,40 @@ A full delivery-address step with saved addresses, all field Controls, and the e
 
 ## Common mistakes
 
-- **Inventing `ShippingAddressSaveOption`.** The correct name is `ShippingAddressSavedOption`.
-- **Inventing `ShippingAddressForm`.** There is no separate `Form` sub-component — `ShippingAddressRoot` is the form container.
-- **Putting `SavedOption` directly under `ShippingAddressRoot`.** It must be inside `SavedList`, which itself only renders when `savedAddresses` is non-empty.
+- **Inventing a `ShippingAddressRoot`, `ShippingAddressSubmit` or `ShippingAddressError`.** There is no standalone root or submit/error part for this entity — `ShippingAddressFieldset` is the only entry point, and the shared `FormSubmit`/`FormError` cover submit and errors.
+- **Inventing a saved-address list or drawer.** There is no saved-address UI in this catalog; every address is typed into the form.
 - **Including `NeighborhoodControl` for a form that only ever shows US fields.** It renders `null` for countries without a neighborhood field, but including it still signals wrong intent when the image never shows it.
-- **Assuming this form writes back to the shopper's saved-address book.** It never does — edits, including edits to a selected saved address, apply to this order only.
-- **Using this component for address autocomplete or postal-code-only entry.** No lookup provider is wired in; all fields are manual, and field-format validation is deferred to the backend.
-- **Placing field Controls outside `ShippingAddressRoot`.** Every Control throws if rendered without an ancestor `ShippingAddressRoot`.
+- **Assuming this form writes back to the shopper's saved-address book.** It never does — it writes the order's own address only.
+- **Using this component for address autocomplete or postal-code-only entry.** No lookup provider is wired in; all fields are manual, and the postal code's format is validated on the client against the active country's descriptor — it is not deferred to the backend.
+- **Placing field Controls outside `ShippingAddressFieldset`.** Every Control throws if rendered without an ancestor `ShippingAddressFieldset`.
+- **Composing `ShippingAddressFieldset` outside a `FormRoot`.** It throws its own named error at mount rather than rendering an inert form region.
+- **Composing `FormSubmit`/`FormError` inside `ShippingAddressFieldset`.** They are siblings of the fieldset, not children — the fieldset renders no submit or error part of its own.
 
 ---
 
 ## Styling
 
-Style `ShippingAddressRoot` as a vertical form stack; field Controls each pair a label above an input. Saved-address options read as a short selectable list above the manual-entry fields.
+Field Controls each pair a label above an input.
 
 | Component | What you style | Plausible classes |
 |---|---|---|
-| `ShippingAddressRoot` | Stacks the whole form vertically | `flex flex-col gap-[16px] w-full` |
 | Field Controls (`RecipientNameControl`, `StreetControl`, `NumberControl`, `CityControl`, `StateControl`, `PostalCodeControl`, `ComplementControl`, `NeighborhoodControl`, `CountryControl`) | Label-above-input field wrapper | `flex flex-col gap-[6px]` |
-| `ShippingAddressSavedList` | Stacks saved-address options with spacing between them | `flex flex-col gap-[8px] mb-[16px]` |
-| `ShippingAddressSavedOption` | A single selectable row: radio + summary label | `flex items-center gap-[8px] rounded-[6px] border border-[#E2E2E2] p-[12px]` |
-| `ShippingAddressSubmit` | The primary call-to-action button | `px-[16px] py-[10px] bg-[#1D4ED8] text-white font-semibold rounded-[6px] disabled:opacity-50` |
-| `ShippingAddressError` | Inline error/alert banner | `rounded-[6px] border border-[#FCA5A5] bg-[#FEF2F2] p-[12px] text-[13px] text-[#991B1B]` |
+| `ShippingAddressFieldsetSkeleton` | `data-fs-shipping-address-fieldset-skeleton` and its `-skeleton-field` rows, `skeletonCount` of them | `flex flex-col gap-[16px]`, rows `h-[44px] rounded-[6px] bg-[#F0F0F0] animate-pulse` |
+| Fieldset announcement | `data-fs-shipping-address-fieldset-announcement` reaches the live region carrying `loadingLabel`/`loadedLabel`. Hide it with a clipping technique, never `display:none` — that drops it from the accessibility tree and defeats the announcement | `sr-only` |
 
-Styled minimal example (recipient name + street + submit):
+Styled minimal example (recipient name + street, shared submit):
 
 ```json
 {
-  "shipping-address": {
-    "type": "ShippingAddressRoot",
-    "children": ["shipping-address-recipient", "shipping-address-street", "shipping-address-submit"],
-    "style": ["flex", "flex-col", "gap-[16px]", "w-full"]
+  "checkout-form": {
+    "type": "FormRoot",
+    "children": ["shipping-address-fieldset", "form-submit"]
+  },
+  "shipping-address-fieldset": {
+    "type": "ShippingAddressFieldset",
+    "props": { "skeletonCount": 2 },
+    "style": ["flex", "flex-col", "gap-[16px]", "w-full"],
+    "children": ["shipping-address-recipient", "shipping-address-street"]
   },
   "shipping-address-recipient": {
     "type": "ShippingAddressRecipientNameControl",
@@ -362,8 +220,8 @@ Styled minimal example (recipient name + street + submit):
     "type": "ShippingAddressStreetControl",
     "style": ["flex", "flex-col", "gap-[6px]"]
   },
-  "shipping-address-submit": {
-    "type": "ShippingAddressSubmit",
+  "form-submit": {
+    "type": "FormSubmit",
     "props": { "label": "Save address" },
     "style": ["px-[16px]", "py-[10px]", "bg-[#1D4ED8]", "text-white", "font-semibold", "rounded-[6px]"]
   }
@@ -374,17 +232,11 @@ Styled minimal example (recipient name + street + submit):
 
 ## Known gaps
 
-Found by review and deliberately left for the dedicated revision of these components, rather than patched
-here. Read this before assuming a behaviour is intentional.
+Found by review and deliberately left for the dedicated revision of these components, rather than patched here. Read this before assuming a behaviour is intentional.
 
-- **The controller and the summary disagree about what "has an address" means.** `EditController` derives its
-  initial mode from `address.id` alone, while `SelectedSummary` gates on the formatted address object. An
-  address carrying an `id` but almost no content — the shape a postcode-only shipping simulation returns —
-  therefore opens on the summary and renders a near-empty one, with no form and no way to complete it. The
-  inverse also fails: an address object with `id: null` holds the section in `edit` forever, so a successful
-  save never collapses it.
+- **There is no view/edit toggle for this section.** A page that wants a summary-first delivery section, reviewed before the shopper commits to editing it, has no composable component here for that — the fieldset always renders its form.
 
 ## Related
 
-- [[client-profile-form]] — collects identity fields (first name, phone, email) that feed the recipient-name default here. Distinct block; do not nest.
+- [[client-profile-fieldset]] — collects identity fields (first name, phone) that feed the recipient-name default here. Distinct block; do not nest.
 - [[shipping-simulator]] — a separate delivery-estimate/rate lookup surface keyed by postal code, used before an address is saved. `ShippingAddress` persists the full address for the order; `ShippingSimulator` only estimates rates for a candidate postal code.

package/dist/index.d.ts

@@ -8,6 +8,9 @@ import { CartUserError } from "./sdk/cart/operations.js";
 import { AddItemPayload, CartActions, CartCouponPayload, CartLinePayload, CartLinesPayload, CartQuantityPayload } from "./sdk/cart/use-cart-actions.js";
 import { ClientPreferenceKey, ClientProfileUserError, CustomerProfileUserError } from "./sdk/identity/operations.js";
 import { ClientPreferencesUpdatePayload, ClientProfileUpdatePayload, CustomerProfileUpdatePayload, IdentityActions } from "./sdk/identity/use-identity-actions.js";
+import { PaymentBillingAddressUpdateInput, PaymentMethodSelectInput, PaymentMoney, PaymentUserError } from "./sdk/payment/operations.js";
+import { PaymentGatewayCard, PaymentGatewayNewCard, PaymentGatewaySavedCard, PaymentGatewayTransaction, SendPaymentsRequest } from "./sdk/payment/gateway.js";
+import { PaymentActions, PaymentGatewayCallbackResult, PaymentStartTransactionResult } from "./sdk/payment/use-payment-actions.js";
 import { RegionUserError } from "./sdk/region/region-operations.js";
 import { RegionActions } from "./sdk/region/use-region-actions.js";
 import { SessionAccessCodeRequestResult, SessionPasswordLoginPayload, SessionRequestAccessCodePayload, SessionUserError, SessionValidateAccessCodePayload } from "./sdk/session/auth-operations.js";
@@ -16,4 +19,4 @@ import { ShippingOptionSelectUserError } from "./sdk/shipping/option-select-oper
 import { ShippingAddressInput, ShippingAddressUpdateErrorEntity } from "./sdk/shipping/shipping-operations.js";
 import { ShippingActions } from "./sdk/shipping/use-shipping-actions.js";
 import { ComponentActions } from "./sdk/actions/types.js";
-export { type ActionSelector, type AddItemPayload, type CartActions, type CartCouponPayload, type CartLinePayload, type CartLinesPayload, type CartQuantityPayload, type CartUserError, type ClientPreferenceKey, type ClientPreferencesUpdatePayload, type ClientProfileUpdatePayload, type ClientProfileUserError, type ComponentActions, type ComponentDefinition, type ContentArraySchema, type ContentNestedObjectShape, type ContentObjectPropertySchema, type ContentObjectSchema, type ContentPropertySchema, type ContentPropertyType, type ContentScalarSchema, type ContentScalarType, type ContentTypeDefinition, type ContentValue, type CustomerProfileUpdatePayload, type CustomerProfileUserError, type EditorMetadata, type FetchStrategy, type IdentityActions, type JsonValue, type MockActions, type PropSchema, type PropSchemaField, type PropType, type RegionActions, type RegionUserError, type SessionAccessCodeRequestResult, type SessionActions, type SessionPasswordLoginPayload, type SessionRequestAccessCodePayload, type SessionUserError, type SessionValidateAccessCodePayload, type ShippingActions, type ShippingAddressInput, type ShippingAddressUpdateErrorEntity, type ShippingOptionSelectUserError, type StorefrontContext, defineComponent, defineContentType, mockAction };
+export { type ActionSelector, type AddItemPayload, type CartActions, type CartCouponPayload, type CartLinePayload, type CartLinesPayload, type CartQuantityPayload, type CartUserError, type ClientPreferenceKey, type ClientPreferencesUpdatePayload, type ClientProfileUpdatePayload, type ClientProfileUserError, type ComponentActions, type ComponentDefinition, type ContentArraySchema, type ContentNestedObjectShape, type ContentObjectPropertySchema, type ContentObjectSchema, type ContentPropertySchema, type ContentPropertyType, type ContentScalarSchema, type ContentScalarType, type ContentTypeDefinition, type ContentValue, type CustomerProfileUpdatePayload, type CustomerProfileUserError, type EditorMetadata, type FetchStrategy, type IdentityActions, type JsonValue, type MockActions, type PaymentActions, type PaymentBillingAddressUpdateInput, type PaymentGatewayCallbackResult, type PaymentGatewayCard, type PaymentGatewayNewCard, type PaymentGatewaySavedCard, type PaymentGatewayTransaction, type PaymentMethodSelectInput, type PaymentMoney, type PaymentStartTransactionResult, type PaymentUserError, type PropSchema, type PropSchemaField, type PropType, type RegionActions, type RegionUserError, type SendPaymentsRequest, type SessionAccessCodeRequestResult, type SessionActions, type SessionPasswordLoginPayload, type SessionRequestAccessCodePayload, type SessionUserError, type SessionValidateAccessCodePayload, type ShippingActions, type ShippingAddressInput, type ShippingAddressUpdateErrorEntity, type ShippingOptionSelectUserError, type StorefrontContext, defineComponent, defineContentType, mockAction };

package/dist/internal/client.d.ts

@@ -1,8 +1,10 @@
 import { MessageId, Messages } from "../sdk/i18n/locales.js";
 import "../sdk/i18n/client.js";
 import { gql } from "../sdk/graphql-tag.js";
+import { AnalyticsActionProvider, AnalyticsActionProviderProps } from "../sdk/actions/analytics-action-provider.js";
 import { CartActionProvider, CartActionProviderProps } from "../sdk/actions/cart-action-provider.js";
 import { IdentityActionProvider, IdentityActionProviderProps } from "../sdk/actions/identity-action-provider.js";
+import { PaymentActionProvider, PaymentActionProviderProps } from "../sdk/actions/payment-action-provider.js";
 import { RegionActionProvider, RegionActionProviderProps } from "../sdk/actions/region-action-provider.js";
 import { SessionActionProvider, SessionActionProviderProps } from "../sdk/actions/session-action-provider.js";
 import { ShippingActionProvider, ShippingActionProviderProps } from "../sdk/actions/shipping-action-provider.js";
@@ -21,4 +23,4 @@ import { StorefrontProvider, StorefrontProviderProps } from "../sdk/provider/sto
 import "../sdk/provider/index.js";
 import { cartCouponErrorsVar, cartLastAddVar, cartUserErrorsVar, miniCartOpenVar, orderFormIdVar } from "../sdk/state/cart.js";
 import { SelectedVariant, publishedVariantIdFor, selectedVariantVar } from "../sdk/state/variant-selector.js";
-export { CartActionProvider, type CartActionProviderProps, type ClientVariablesMap, DataOverrideContext, HotDataProvider, type HotDataProviderProps, IdentityActionProvider, type IdentityActionProviderProps, type ListItemRef, ListItemRefContext, type MessageId, type Messages, MultipleReactiveDataProvider, type MultipleReactiveDataProviderEntity, type MultipleReactiveDataProviderProps, PageReactiveDataRoot, type PageReactiveDataRootProps, ReactiveDataProvider, type ReactiveDataProviderProps, ReactiveListItemDataProvider, type ReactiveListItemDataProviderProps, ReactiveRootContext, type ReactiveRootContextValue, RegionActionProvider, type RegionActionProviderProps, type SelectedVariant, SessionActionProvider, type SessionActionProviderProps, ShippingActionProvider, type ShippingActionProviderProps, StorefrontProvider, type StorefrontProviderProps, buildOptimisticDecrease, buildOptimisticIncrease, buildOptimisticRemove, buildStorefrontContextHeaders, cartCouponErrorsVar, cartLastAddVar, cartUserErrorsVar, gql, miniCartOpenVar, orderFormIdVar, publishedVariantIdFor, selectedVariantVar, useDataOverride, useListItemRef };
+export { AnalyticsActionProvider, type AnalyticsActionProviderProps, CartActionProvider, type CartActionProviderProps, type ClientVariablesMap, DataOverrideContext, HotDataProvider, type HotDataProviderProps, IdentityActionProvider, type IdentityActionProviderProps, type ListItemRef, ListItemRefContext, type MessageId, type Messages, MultipleReactiveDataProvider, type MultipleReactiveDataProviderEntity, type MultipleReactiveDataProviderProps, PageReactiveDataRoot, type PageReactiveDataRootProps, PaymentActionProvider, type PaymentActionProviderProps, ReactiveDataProvider, type ReactiveDataProviderProps, ReactiveListItemDataProvider, type ReactiveListItemDataProviderProps, ReactiveRootContext, type ReactiveRootContextValue, RegionActionProvider, type RegionActionProviderProps, type SelectedVariant, SessionActionProvider, type SessionActionProviderProps, ShippingActionProvider, type ShippingActionProviderProps, StorefrontProvider, type StorefrontProviderProps, buildOptimisticDecrease, buildOptimisticIncrease, buildOptimisticRemove, buildStorefrontContextHeaders, cartCouponErrorsVar, cartLastAddVar, cartUserErrorsVar, gql, miniCartOpenVar, orderFormIdVar, publishedVariantIdFor, selectedVariantVar, useDataOverride, useListItemRef };

package/dist/internal/client.js

@@ -6,8 +6,10 @@ import { cartCouponErrorsVar, cartLastAddVar, cartUserErrorsVar, miniCartOpenVar
 import { buildOptimisticDecrease, buildOptimisticIncrease, buildOptimisticRemove } from "../sdk/cart/optimistic.js";
 import { ListItemRefContext, useListItemRef } from "../sdk/data/list-item-ref-context.js";
 import { PageReactiveDataRoot, ReactiveRootContext } from "../sdk/data/page-reactive-data-root.js";
+import { AnalyticsActionProvider } from "../sdk/actions/analytics-action-provider.js";
 import { CartActionProvider } from "../sdk/actions/cart-action-provider.js";
 import { IdentityActionProvider } from "../sdk/actions/identity-action-provider.js";
+import { PaymentActionProvider } from "../sdk/actions/payment-action-provider.js";
 import { RegionActionProvider } from "../sdk/actions/region-action-provider.js";
 import { SessionActionProvider } from "../sdk/actions/session-action-provider.js";
 import { ShippingActionProvider } from "../sdk/actions/shipping-action-provider.js";
@@ -20,4 +22,4 @@ import "../sdk/data/index.js";
 import { StorefrontProvider } from "../sdk/provider/storefront-provider.js";
 import "../sdk/provider/index.js";
 import "../sdk/state/index.js";
-export { CartActionProvider, DataOverrideContext, HotDataProvider, IdentityActionProvider, ListItemRefContext, MultipleReactiveDataProvider, PageReactiveDataRoot, ReactiveDataProvider, ReactiveListItemDataProvider, ReactiveRootContext, RegionActionProvider, SessionActionProvider, ShippingActionProvider, StorefrontProvider, buildOptimisticDecrease, buildOptimisticIncrease, buildOptimisticRemove, buildStorefrontContextHeaders, cartCouponErrorsVar, cartLastAddVar, cartUserErrorsVar, gql, miniCartOpenVar, orderFormIdVar, publishedVariantIdFor, selectedVariantVar, useDataOverride, useListItemRef };
+export { AnalyticsActionProvider, CartActionProvider, DataOverrideContext, HotDataProvider, IdentityActionProvider, ListItemRefContext, MultipleReactiveDataProvider, PageReactiveDataRoot, PaymentActionProvider, ReactiveDataProvider, ReactiveListItemDataProvider, ReactiveRootContext, RegionActionProvider, SessionActionProvider, ShippingActionProvider, StorefrontProvider, buildOptimisticDecrease, buildOptimisticIncrease, buildOptimisticRemove, buildStorefrontContextHeaders, cartCouponErrorsVar, cartLastAddVar, cartUserErrorsVar, gql, miniCartOpenVar, orderFormIdVar, publishedVariantIdFor, selectedVariantVar, useDataOverride, useListItemRef };