@vtex/faststore 0.0.1

package/dist/docs/shipping-address.md

@@ -0,0 +1,390 @@
+# 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.
+
+---
+
+## Visual cues (how to identify in an image)
+
+Use these signals to detect that a ShippingAddress block is present. Position on the page is irrelevant for detection — it can appear anywhere, in any orientation. The image is the source of truth for layout.
+
+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.").
+
+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.
+
+---
+
+## 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.
+
+## 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.
+- 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`.
+
+---
+
+## 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.
+
+```
+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)
+```
+
+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`).
+- `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.
+
+---
+
+## Components
+
+### ShippingAddressRoot
+
+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'] }`.
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| `defaultCountry` | string | `"BRA"` | ISO alpha-3 country code used when no address exists yet |
+
+**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.
+
+| 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.
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| `children` | ReactNode | — | Required. A single `DrawerRoot` element; other elements are passed through unchanged. |
+
+**Composition rules:**
+
+- 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
+
+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.
+
+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
+
+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`.
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| `label` | string | `"editar"` | Button label shown when no children are composed |
+
+### CancelButton
+
+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.
+
+| 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 |
+
+**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.
+
+### Error
+
+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`.
+
+---
+
+## Canonical schema example
+
+A full delivery-address step with saved addresses, all field Controls, and the error/submit pair:
+
+```json
+{
+  "shipping-address": {
+    "type": "ShippingAddressRoot",
+    "props": { "defaultCountry": "BRA" },
+    "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"
+    ]
+  },
+  "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" }
+  }
+}
+```
+
+### Minimal variant (manual entry only, no saved addresses visible)
+
+```json
+{
+  "shipping-address": {
+    "type": "ShippingAddressRoot",
+    "children": [
+      "shipping-address-recipient",
+      "shipping-address-street",
+      "shipping-address-postal-code",
+      "shipping-address-submit"
+    ]
+  },
+  "shipping-address-recipient": { "type": "ShippingAddressRecipientNameControl" },
+  "shipping-address-street": { "type": "ShippingAddressStreetControl" },
+  "shipping-address-postal-code": { "type": "ShippingAddressPostalCodeControl" },
+  "shipping-address-submit": { "type": "ShippingAddressSubmit" }
+}
+```
+
+---
+
+## 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.
+- **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`.
+
+---
+
+## 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.
+
+| 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]` |
+
+Styled minimal example (recipient name + street + submit):
+
+```json
+{
+  "shipping-address": {
+    "type": "ShippingAddressRoot",
+    "children": ["shipping-address-recipient", "shipping-address-street", "shipping-address-submit"],
+    "style": ["flex", "flex-col", "gap-[16px]", "w-full"]
+  },
+  "shipping-address-recipient": {
+    "type": "ShippingAddressRecipientNameControl",
+    "style": ["flex", "flex-col", "gap-[6px]"]
+  },
+  "shipping-address-street": {
+    "type": "ShippingAddressStreetControl",
+    "style": ["flex", "flex-col", "gap-[6px]"]
+  },
+  "shipping-address-submit": {
+    "type": "ShippingAddressSubmit",
+    "props": { "label": "Save address" },
+    "style": ["px-[16px]", "py-[10px]", "bg-[#1D4ED8]", "text-white", "font-semibold", "rounded-[6px]"]
+  }
+}
+```
+
+---
+
+## 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.
+
+- **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.
+
+## Related
+
+- [[client-profile-form]] — collects identity fields (first name, phone, email) 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/docs/shipping-simulator.md

@@ -0,0 +1,147 @@
+# ShippingSimulator
+
+**Category:** commerce
+**Purpose:** A postal-code (CEP) driven shipping calculator. The shopper types a destination and sees the available shipping options — name, delivery estimate, and price — for either **one product** (on a PDP) or the **whole cart** (in a cart/mini-cart). Two Roots back the same presentational leaves: `ShippingSimulatorRoot` (per-product, PDP) and `CartShippingSimulatorRoot` (whole-cart). Every leaf below the Root is shared and reads from the same context, so the two Roots differ only in what they query.
+
+---
+
+## Visual cues (how to identify in an image)
+
+Look for a **CEP / postal-code input with a "Calculate" button**, and — after submitting — a short list of shipping options each showing a carrier name, an ETA, and a price. Examples:
+
+- On a **product page**, below the price / buy button: a "Calcule o frete" block with a CEP field and a list of delivery options for that product.
+- In a **mini-cart drawer footer**, between the coupon block and the order summary: a CEP field that returns the delivery options for the whole cart, each with a summed price.
+- A "no delivery available" message when a submitted CEP returns no options.
+
+---
+
+## When to use
+
+There are two contexts, one Root each. Pick by what the calculator ships.
+
+### 1. Product shipping preview on a PDP — `ShippingSimulatorRoot`
+
+Use on a **product detail page** to preview how *one product* ships to a CEP. `ShippingSimulatorRoot` carries a product fragment (`productBySlug(slug: $slug)`) and `fetchStrategy: 'reactive'`, resolves the variant + seller from that fragment, and submits a per-variant `shippingSimulation`. It therefore requires a page with a `$slug` variable (a PDP). Compose it as `ShippingSimulatorRoot > Form > … > Options > Option > …`.
+
+### 2. Whole-cart shipping calculator in the cart/mini-cart — `CartShippingSimulatorRoot`
+
+Use in a **cart or mini-cart drawer footer** to calculate shipping for the *whole cart*. `CartShippingSimulatorRoot` has **no fragment** and **no `fetchStrategy`**: it selects nothing on `Query`, takes only a destination, and submits `cartShippingSimulation({ postalCode, country })`. The cart's items are sourced server-side from the `x-order-form-id` context, so the Root needs **no `CartRoot` ancestor** and no product context — it composes in any layout. The API returns the options common to every item with prices summed across items. Compose it as `CartShippingSimulatorRoot > Form > … > Options > Option > … > Empty`; the sub-components are the same shared leaves, re-exported under the `CartShippingSimulator` namespace.
+
+## When NOT to use
+
+- `ShippingSimulatorRoot` in a cart/mini-cart layout — there is no `$slug`, so its fragment cannot compose. Use `CartShippingSimulatorRoot`.
+- `CartShippingSimulatorRoot` on a PDP to answer "how does *this product* ship?" — it ships the whole cart, not the viewed product. Use `ShippingSimulatorRoot`.
+- Do not wrap `CartShippingSimulatorRoot` in a `CartRoot` to "provide the cart" — cart identity travels in the transport header, not through React context.
+
+---
+
+## The Empty sub-component and the idle-vs-empty distinction
+
+`ShippingSimulatorEmpty` is a shared, self-hiding leaf that shows a friendly message when a simulation ran and returned **no** shipping options (for a cart, this is the "no carrier common to all items" case). It is available in both namespaces.
+
+The context distinguishes three states via `shippingOptions`:
+
+- **`null`** — idle (before the first submit) or loading. `Options`, `Empty`, and `Error` all render nothing.
+- **`[]`** — a simulation ran and returned an empty list. `Empty` renders its message; `Options` renders nothing.
+- **`[...]`** — options available. `Options` renders one `Option` per row; `Empty` renders nothing.
+
+`ShippingSimulatorError` shows the first `userError`'s message. A transport failure has no upstream message, so the component supplies `fs/shipping.calculation-failed` from the catalog — built in the `.catch()` handler, where only a string fits.
+
+`Empty` renders **only** for `[]` with no `userErrors` — so it never flashes on first paint, and an error path defers to `ShippingSimulatorError`. Its copy comes from the message catalog (`fs/shipping.no-options`), per locale, and `children` overrides it. It renders a polite live region (an `<output aria-live="polite">`, matching `Loading`), so it is announced when it appears.
+
+---
+
+## Composition
+
+```text
+CartShippingSimulatorRoot          ← whole-cart calculator (no fragment, no CartRoot needed)
+├── ShippingSimulatorForm          ← wraps input + submit
+│   ├── ShippingSimulatorInput       props: format (auto-hyphenate CEP)
+│   └── ShippingSimulatorSubmit      children: "Calcular"
+├── ShippingSimulatorLoading       ← shows while a simulation is pending (`fs/shipping.calculating`)
+├── ShippingSimulatorError         ← shows a validation/transport error
+├── ShippingSimulatorOptions       ← renders one Option per available option
+│   │   props: sortBy ("price" | "estimate"), maxOptions
+│   └── ShippingSimulatorOption
+│       ├── ShippingSimulatorOptionName
+│       ├── ShippingSimulatorOptionEstimate   ← one whole sentence per unit, from the catalog
+│       └── ShippingSimulatorOptionPrice       ← "Grátis" from the catalog when the amount is 0
+└── ShippingSimulatorEmpty         ← shows only when a simulation returned []
+```
+
+The PDP composition is identical, with `ShippingSimulatorRoot` in place of `CartShippingSimulatorRoot` (and no need for `Empty`, though it may be added there too).
+
+### Key components
+
+| Component | Props | Notes |
+|---|---|---|
+| `ShippingSimulatorRoot` | `country`, `quantity` | PDP Root; carries a product fragment + `fetchStrategy: 'reactive'`; needs a `$slug` page |
+| `CartShippingSimulatorRoot` | `country` | Cart Root; no fragment, no `fetchStrategy`, no `CartRoot` ancestor; submits `{ postalCode, country }` only |
+| `ShippingSimulatorInput` | `format` | `format` auto-hyphenates the CEP (01310-100). The placeholder and the default `aria-label` come from the message catalog (`fs/shipping.postal-code.*`); `aria-label` stays a DOM pass-through, so a store can still set its own |
+| `ShippingSimulatorOptions` | `sortBy`, `maxOptions` | Both optional; omitted = every option in API order. `sortBy="price"` orders cheapest first, `"estimate"` fastest first (business days weigh as calendar days); `maxOptions` caps the rendered rows — `sortBy="price"` + `maxOptions=1` shows only the cheapest option. Works identically under either Root |
+| `ShippingSimulatorOptionEstimate` | — | One whole sentence per unit (`fs/shipping.estimate.in-*`), so the plural agrees with the locale; a zero value reads `fs/shipping.estimate.today` |
+| `ShippingSimulatorOptionPrice` | — | Renders `fs/shipping.free-price` when the amount is 0; otherwise formats via `Intl` from the active storefront context |
+| `ShippingSimulatorEmpty` | — | Renders only for a simulated-empty result (`fs/shipping.no-options`); `children` overrides it |
+
+Prices format from the **active storefront context's currency** (not the payload `currencyCode`); the binding's currency must match the payload currency.
+
+---
+
+## Schema
+
+### Mini-cart drawer footer (whole-cart, `cart-filled` only)
+
+Place the calculator inside `cart-filled` (an empty cart has nothing to ship), between the coupon block and the order summary.
+
+```json
+{
+  "cart-shipping": {
+    "type": "CartShippingSimulatorRoot",
+    "props": { "country": "BRA" },
+    "children": [
+      "cart-shipping-form",
+      "cart-shipping-loading",
+      "cart-shipping-error",
+      "cart-shipping-options",
+      "cart-shipping-empty"
+    ]
+  },
+  "cart-shipping-form": {
+    "type": "ShippingSimulatorForm",
+    "children": ["cart-shipping-input", "cart-shipping-submit"]
+  },
+  "cart-shipping-input": {
+    "type": "ShippingSimulatorInput",
+    "props": { "format": true }
+  },
+  "cart-shipping-submit": { "type": "ShippingSimulatorSubmit", "props": { "children": "Calcular" } },
+  "cart-shipping-loading": { "type": "ShippingSimulatorLoading" },
+  "cart-shipping-error": { "type": "ShippingSimulatorError" },
+  "cart-shipping-options": {
+    "type": "ShippingSimulatorOptions",
+    "children": ["cart-shipping-option"]
+  },
+  "cart-shipping-option": {
+    "type": "ShippingSimulatorOption",
+    "children": ["cart-shipping-option-name", "cart-shipping-option-estimate", "cart-shipping-option-price"]
+  },
+  "cart-shipping-option-name": { "type": "ShippingSimulatorOptionName" },
+  "cart-shipping-option-estimate": { "type": "ShippingSimulatorOptionEstimate" },
+  "cart-shipping-option-price": { "type": "ShippingSimulatorOptionPrice" },
+  "cart-shipping-empty": { "type": "ShippingSimulatorEmpty" }
+}
+```
+
+### Product page preview (single product)
+
+Identical shape, with `ShippingSimulatorRoot` as the Root and `quantity` available as a prop. It lives on a PDP where a `$slug` variable resolves the product fragment.
+
+```json
+{
+  "pdp-shipping": {
+    "type": "ShippingSimulatorRoot",
+    "props": { "country": "BRA", "quantity": 1 },
+    "children": ["pdp-shipping-form", "pdp-shipping-loading", "pdp-shipping-error", "pdp-shipping-options"]
+  }
+}
+```