@vtex/faststore 0.0.8 → 0.0.11

package/dist/docs/carousel.md

@@ -35,7 +35,8 @@
 | `variant` | `'slide' \| 'scroll'` | `'slide'` | Transform slide vs. native overflow scroll |
 | `itemsPerPage` | number | `1` | How many children are visible per page |
 | `defaultPage` | number | `0` | Page selected on first render |
-| `label` | string | `'Carousel'` | `aria-label` for the carousel region |
+
+The region's `aria-label` comes from the `$content` field `label` (content type `carousel-root`).
 
 ### CarouselTrack
 
@@ -43,16 +44,16 @@ Lays out and counts the children. No props beyond standard `div` attributes. Pla
 
 ### CarouselPrevious / CarouselNext
 
-Buttons that move one page. No props beyond standard `button` attributes; accept any children (Icon, text). Disabled at the respective end when `infiniteMode` is off.
+Buttons that move one page. No props beyond standard `button` attributes; accept any children (Icon, text). Disabled at the respective end when `infiniteMode` is off. Their `aria-label` comes from the `$content` field `label` (content types `carousel-previous` and `carousel-next`).
 
 ### CarouselBullets
 
 | Prop | Type | Default | Notes |
 |------|------|---------|-------|
-| `ariaLabel` | string | `'Choose page'` | Label for the bullets group |
-| `bulletLabel` | string | `'Go to page {page}'` | Per-bullet label; `{page}` is the 1-based page number |
 | `hideWhenSingle` | boolean | `true` | Render nothing when there is a single page |
 
+The labels come from `$content` (content type `carousel-bullets`): `ariaLabel` names the bullets group, and `bulletLabel` names each bullet, an ICU message whose `{page}` argument is the 1-based page number.
+
 Bullets support `ArrowLeft` / `ArrowRight` / `Home` / `End` keyboard navigation and mark the active page with `data-fs-carousel-bullet-selected="true"` and `aria-current`.
 
 ---

package/dist/docs/cart-destination.md

@@ -0,0 +1,251 @@
+# CartDestination
+
+**Category:** content
+**Purpose:** The Cart page's delivery location. `CartDestinationRoot` reads where the cart is delivered and writes a new destination from a postal code alone, so the free-shipping bar beside it follows. It has two modes: read ("Entregando em 01310-100 · São Paulo, SP" plus a change link) and edit (a postal code field with "Atualizar" and "Cancelar").
+
+---
+
+## Visual cues (how to identify in an image)
+
+Look in the **top of the cart page's main column**, above the free-shipping bar and the line items:
+
+- A single line reading **"Entregando em"** (or "Delivering to") followed by a **postal code and city, state**, beside a link such as **"Trocar localização?"**.
+- With no destination yet, the bar shows just a prompt such as **"Informe seu CEP"**, often with a pin icon. Pressing it opens the field.
+- Pressing the link (or the prompt) swaps the line for **one postal code field**, an **"Atualizar"** button and a **"Cancelar"** button.
+
+The image is the source of truth for layout.
+
+A postal code control in the **site header** is not this component: that is `RegionRoot`.
+
+---
+
+## When to use
+
+- On the **Cart page**, once, where the design shows where the cart is delivered and lets the shopper change it.
+
+## When NOT to use
+
+- **In the header** — that is `Region`, which only sets a cookie and never touches the cart.
+- **For the full delivery address on checkout** — that is `ShippingAddressFieldset`.
+- **For a shipping-cost quote on a product page or in the cart drawer** — that is `ShippingSimulator`; it quotes and writes nothing.
+- More than once per page: two roots mean two drafts over the same destination.
+
+---
+
+## Composition
+
+`CartDestinationRoot` provides the `'cartDestination'` context; every other part declares `requiresContext: 'cartDestination'`.
+
+```
+CartDestinationRoot                      (provides 'cartDestination'; starts in read mode)
+├── CartDestinationRead                  (read mode only)
+│   ├── CartDestinationValue             (the destination, once set)
+│   ├── CartDestinationUnset             (button: the invitation, while none is set; opens edit mode)
+│   │   ├── Icon                         (optional pin)
+│   │   └── Text                         ("Informe seu CEP")
+│   └── CartDestinationChange            (opens edit mode)
+└── CartDestinationForm                  (edit mode only)
+    ├── CartDestinationPostalCodeControl
+    ├── CartDestinationSubmit
+    ├── CartDestinationCancel
+    └── CartDestinationError
+```
+
+Child order reflects visual order. The store cannot open edit mode from outside: the mode is local to the root, and the destination shown always comes from the cart, never from what was typed.
+
+---
+
+## Components
+
+### CartDestinationRoot
+
+Reads the cart destination reactively and broadcasts it, the edit-mode flag, the draft and the write state. Starts in read mode, also with no destination.
+
+**Data:** declares `fragment CartDestinationData on Query` (`shipping { id address { postalCode country city state } }`) with `fetchStrategy: 'reactive'`. It selects no name and no street.
+
+**Write:** declares `actions: { shipping: ['setAddress'] }`. A submit sends `{ postalCode, country }` and nothing else; the cart keeps its recipient name. The response updates the destination and the free-shipping bar through the cache.
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| `defaultCountry` | string | `"BRA"` | Used while the cart has no address; the address country wins |
+
+### CartDestinationRead
+
+Renders its children only in read mode. No props.
+
+### CartDestinationValue
+
+The destination as prefix, postal code, city and state, each in its own element. Renders nothing while loading or when none is set.
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| `prefix` | string | — | For example `"Entregando em"`; authored content wins |
+
+**Content model** (`cart-destination-value`): `prefix`.
+
+### CartDestinationUnset
+
+A button that opens edit mode, with `aria-expanded` tied to the mode, exactly like `CartDestinationChange`. It renders only once the destination resolved and none is set. Its children are the invitation content (a `Text`, an `Icon`). Place it within `CartDestinationRead`. Its props are the props of a button; a consumer `onClick` runs before edit mode opens. When edit mode closes with no destination set, focus returns to this button. It ships no style of its own: like the change link, the store gives it a pointer cursor and an underline so it reads as clickable.
+
+### CartDestinationChange
+
+Button that opens edit mode, with `aria-expanded` tied to the mode. Styled as a link by the store.
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| `label` | string | — | For example `"Trocar localização?"`; authored content wins |
+
+**Content model** (`cart-destination-change`): `label`.
+
+### CartDestinationForm
+
+Renders only in edit mode. Enter in the field runs the submit, which flags an incomplete or unchanged draft instead of sending it. Opening it focuses the field; leaving it focuses `CartDestinationChange`.
+
+### CartDestinationPostalCodeControl
+
+A plain text field bound to the draft, empty every time edit mode opens. Its limits (`maxLength`, `inputMode`) and its placeholder, the country's example postal code (`01310-100` for BRA), come from the postal code rules of the cart's country (`@vtex/country-forms`), which load when edit mode opens. There is no input mask: the shopper types the code as they know it, and Submit validates it against the country's rules.
+
+While the rules load, the field and `CartDestinationSubmit` are disabled, and the field takes focus once it is enabled. If the load fails, the field is enabled as free text and nothing validates it. A country the rules do not cover (anything but ARG, BRA, CAN, CHL, COL, DEU, ECU, ESP, FRA, GBR, IRL, ITA, MEX, PER and USA) is free text too: no mask, no limit and no validation beyond a non-blank value.
+
+The component keeps no mask table and does not read the shared country descriptors that `BillingAddress` and `ShippingAddress` use, so a Canadian or Mexican cart address is judged by the library's own rules for those countries and never by the Brazilian `99999-999` mask. For `CAN` the field takes at most 7 characters, shows the example `K1A 0A9`, accepts `k1a0b1` and writes it as `K1A 0B1`; the library refuses a first letter of D, F, I, O, Q, U or W and is looser than Canada Post elsewhere (`Z1A 0A9` passes). For `MEX` the field takes at most 5 characters on a numeric keyboard and refuses `00999` and `6600`; there is no mask. No case in `cart-destination.test.tsx` uses `CAN` or `MEX`: the behaviour comes from the same `@vtex/country-forms` rules and `sdk/address` functions the billing and shipping suites pin for those countries.
+
+Because the rules come from the library, the cart can disagree with the other two forms where their descriptor patterns differ from the library. A US ZIP+4 typed without the hyphen (`021011234`) is refused here (`cart-destination.test.tsx` pins it) and accepted by billing and shipping.
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| `label` | string | — | Field label |
+| `placeholder` | string | the country's example postal code | Field placeholder; wins over the example the rules give |
+| `invalidMessage` | string | — | Shown for a typed code the country's rules refuse, once the field loses focus or Submit is attempted |
+
+### CartDestinationSubmit
+
+Writes the typed postal code. Disabled until the country's rules have loaded, the draft passes the country's postal code validation (any non-blank text when the rules failed to load or the country is not covered) and differs from the current postal code, and while a write is pending (`aria-busy`). The write sends the code in the country's own form (`04538132` becomes `04538-132`). A pending write also waits for any cart line write in flight.
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| `label` | string | — | For example `"Atualizar"` |
+| `pendingLabel` | string | — | Shown while the write is in flight |
+
+**Content model** (`cart-destination-submit`): `label`, `pendingLabel`.
+
+### CartDestinationCancel
+
+Closes edit mode, discards the draft and any error, and writes nothing. Disabled while a write is pending.
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| `label` | string | — | For example `"Cancelar"` |
+
+**Content model** (`cart-destination-cancel`): `label`.
+
+### CartDestinationError
+
+An alert announcing a failed write; renders nothing otherwise. It words the error's `code` from its own content and never shows the server's text. A code it does not know (a newer server) shows `genericMessage` and logs `message.unknown-code`.
+
+| Code | Message field |
+|------|---------------|
+| `INVALID_POSTAL_CODE` | `invalidPostalCodeMessage` |
+| `NETWORK_ERROR` and every other `ShippingAddressUpdateErrorCode` | `genericMessage` |
+
+A postal code the platform refuses upstream reaches the client as `NETWORK_ERROR` today, so write `genericMessage` to cover it.
+
+**Content model** (`cart-destination-error`): `genericMessage`, `invalidPostalCodeMessage` (messages, no arguments).
+
+---
+
+## Canonical schema example
+
+```json
+{
+  "cart-destination": {
+    "type": "CartDestinationRoot",
+    "style": ["flex", "flex-col", "gap-2", "text-sm"],
+    "children": ["cart-destination-read", "cart-destination-form"]
+  },
+  "cart-destination-read": {
+    "type": "CartDestinationRead",
+    "style": ["flex", "items-center", "gap-2"],
+    "children": ["cart-destination-value", "cart-destination-unset", "cart-destination-change"]
+  },
+  "cart-destination-value": { "type": "CartDestinationValue", "props": { "prefix": "Entregando em" }, "style": ["flex", "gap-1"] },
+  "cart-destination-unset": {
+    "type": "CartDestinationUnset",
+    "style": ["flex", "items-center", "gap-1", "cursor-pointer", "underline"],
+    "children": ["cart-destination-unset-icon", "cart-destination-invitation"]
+  },
+  "cart-destination-unset-icon": { "type": "Icon", "props": { "name": "map-pin" } },
+  "cart-destination-invitation": { "type": "Text", "props": { "as": "span", "children": "Informe seu CEP" } },
+  "cart-destination-change": {
+    "type": "CartDestinationChange",
+    "props": { "label": "Trocar localização?" },
+    "style": ["text-[#2563eb]", "font-medium", "cursor-pointer"]
+  },
+  "cart-destination-form": {
+    "type": "CartDestinationForm",
+    "style": ["flex", "flex-col", "gap-2"],
+    "children": [
+      "cart-destination-control",
+      "cart-destination-submit",
+      "cart-destination-cancel",
+      "cart-destination-error"
+    ]
+  },
+  "cart-destination-control": { "type": "CartDestinationPostalCodeControl", "props": { "label": "CEP" } },
+  "cart-destination-submit": { "type": "CartDestinationSubmit", "props": { "label": "Atualizar", "pendingLabel": "Atualizando…" } },
+  "cart-destination-cancel": { "type": "CartDestinationCancel", "props": { "label": "Cancelar" } },
+  "cart-destination-error": {
+    "type": "CartDestinationError",
+    "props": {
+      "genericMessage": "Não foi possível usar esse CEP. Confira o número e tente de novo.",
+      "invalidPostalCodeMessage": "CEP inválido. Confira o número e tente de novo."
+    },
+    "style": ["text-sm", "text-red-700"]
+  }
+}
+```
+
+---
+
+## Styling hooks
+
+| Attribute | On | Present when |
+|---|---|---|
+| `data-fs-cart-destination` | `CartDestinationRoot` | Always |
+| `data-fs-cart-destination-editing` | `CartDestinationRoot` | Edit mode is open |
+| `data-fs-cart-destination-pending` | `CartDestinationRoot` | A write is in flight |
+| `data-fs-cart-destination-read` | `CartDestinationRead` | Read mode |
+| `data-fs-cart-destination-value` | `CartDestinationValue` | A destination is set |
+| `data-fs-cart-destination-value-prefix`, `-postal-code`, `-city`, `-state` | The piece's element | The piece exists |
+| `data-fs-cart-destination-unset` | `CartDestinationUnset` (a button) | No destination is set |
+| `data-fs-cart-destination-change` | `CartDestinationChange` | Always |
+| `data-fs-cart-destination-form` | `CartDestinationForm` | Edit mode |
+| `data-fs-cart-destination-postal-code-control` | `CartDestinationPostalCodeControl` | Always |
+| `data-fs-cart-destination-submit`, `-submit-pending` | `CartDestinationSubmit` | Always, and while a write is in flight |
+| `data-fs-cart-destination-cancel` | `CartDestinationCancel` | Always |
+| `data-fs-cart-destination-error` | `CartDestinationError` | The latest write failed |
+
+No part ships CSS of its own. Spacing, the link look of the change control and the two modes' boxes are swatch decisions; use `data-fs-cart-destination-editing` to style them apart.
+
+---
+
+## Common mistakes
+
+- **Inventing `CartDestination` (without `Root`).** The provider is `CartDestinationRoot`.
+- **Using `RegionRoot` on the cart page.** `Region` only sets the header cookie; it never changes the cart destination, so the free-shipping bar never moves.
+- **Placing `CartDestinationValue` or `CartDestinationChange` outside `CartDestinationRead`.** They stay on screen while the form is open.
+- **Placing the postal code control, `CartDestinationSubmit` or `CartDestinationCancel` outside `CartDestinationForm`.** Only the form is bound to edit mode: outside it they render in read mode too, and Enter in the field no longer reaches the submit.
+- **Looking for an `open` prop or a controller.** The root owns edit mode; nothing outside it can open it.
+- **Omitting `CartDestinationUnset`.** With no destination the page then shows only the change link and no invitation.
+- **Leaving `CartDestinationUnset` unstyled.** It is a button with no style of its own, so without a pointer cursor and an underline the invitation does not read as clickable. Give it the same look as `CartDestinationChange`.
+- **Placing `CartDestinationChange` inside `CartDestinationUnset`.** The invitation is already a button, and a button cannot hold another. With no destination the regular change link repeats the invitation, so the store usually hides it while unset (for example with a `[&:has([data-fs-cart-destination-unset])>[data-fs-cart-destination-change]]:hidden` rule on `CartDestinationRead`).
+- **Expecting the Value to show what the shopper just typed.** It shows what the cart confirms.
+- **Passing a `mask` to the postal code control.** There is none: the field is plain text and the country's rules validate it.
+- **Authoring only `invalidPostalCodeMessage` for "CEP não encontrado".** A postal code the platform refuses upstream reaches the client as a network failure today, so `genericMessage` must cover it too.
+
+---
+
+## Related
+
+- [[../free-shipping-progress/free-shipping-progress]] — the bar beside this component; it follows the destination write through the cache with no wiring.
+- [[../region/region]] — the header's region control; it keeps the masked postal code field and sets a cookie, with no cart write.
+- [[../shipping-address/shipping-address]] — the full delivery address on checkout, which this component's write shares with.

package/dist/docs/cart-item.md

@@ -15,10 +15,11 @@ A **cart line** — a repeated row in a cart or mini-cart list: a product thumbn
 
 ## Composition
 
-**`CartItemRoot` wraps the line-item template inside `CartList`.** The nesting is always:
+**`CartItemRoot` wraps the line-item template inside `CartList`, `CartAvailableItems` or `CartUnavailableItems`.** The nesting is always:
 
 ```text
-CartList              (iterator — renders its children once per cart line)
+CartList              (iterator — renders its children once per cart line; CartAvailableItems and
+                       CartUnavailableItems iterate the purchasable and the unavailable lines the same way)
   └─ CartItemRoot     (per-line data provider — owns the core slice)
        ├─ CartItemImage             (optionally wrapped in CartItemProductLink; see below)
        ├─ CartItemName
@@ -37,7 +38,16 @@ CartList              (iterator — renders its children once per cart line)
 ```
 
 - **`CartItemRoot` is required.** Every `CartItem*` core particle reads its data from the nearest `CartItemRoot` (build-time `requiresContext: 'cart-item-data'`). Placing a core particle directly inside `CartList` with no `CartItemRoot` between them is a build error. When authoring a cart or mini-cart line template, always insert a `CartItemRoot` between the `CartList` and the row's particles — it carries no visible styling of its own, so put the row layout classes on it (or on a `Container` inside it).
-- **`CartItemRoot` must be inside `CartList`.** It requires the `cart-item` iteration context that `CartList` provides.
+- **`CartItemRoot` must be inside `CartList`, `CartAvailableItems` or `CartUnavailableItems`.** It requires the `cart-item` iteration context that each of the three provides.
+
+## Image placeholder
+
+`CartItemImage` renders the `<img>` while the line has a usable image. It renders a placeholder `span` in the same slot when:
+
+- the line has no image, or its URL is blank; or
+- the image fails to load, including a failure that happened before hydration (an image already settled with no pixels at mount is treated as failed).
+
+The placeholder carries `data-fs-cart-item-image` and `data-fs-cart-item-image-broken`, and not `data-fs-image` because it is not an image element. It takes the image's `className` and `style`, so the slot keeps its size. It is hidden from assistive technology (`aria-hidden`, no role or name), so only a loaded image is announced. It has no built-in look: style it with a swatch keyed on the hook, for example `data-[fs-cart-item-image-broken]:bg-gray-100`. The placeholder keeps the image's display (`inline-block`, set inline) so the sizing classes keep working with no extra utility; a swatch overrides it only with an important utility, and the look stays the swatch's. A failure is remembered only for the URL that failed, so a line whose URL changes tries the new one. A consumer `onError` still runs when the browser delivers the `error` event; a failure found at mount is not reported through it. A `ref` reaches the `<img>` only.
 
 ## PDP link composition
 
@@ -46,18 +56,18 @@ CartList              (iterator — renders its children once per cart line)
 ```text
 CartItemRoot
   └─ CartItemProductLink        (anchor to this line's product page)
-       └─ CartItemImage         (unchanged — its alt text names the link)
+       └─ CartItemImage         (the link names itself with aria-label; see below)
 ```
 
-**Placing it is the switch.** There is no prop to turn the link on or off: a mini-cart line composes it, a checkout line omits it. That is why `CartItemImage` on its own still renders a plain `<img>` with no anchor, exactly as before.
+**Placing it is the switch.** There is no prop to turn the link on or off: a mini-cart line composes it, a checkout line omits it. That is why `CartItemImage` on its own renders the `<img>` (or, with no usable image, the placeholder described below) and never an anchor.
 
-**It names itself from what it wraps.** The link adds no `aria-label`, so its accessible name is the image's alt text (`image.altText ?? variant.name`). On a line whose `variant.image` is `null` the leaf renders its children unwrapped instead of wrapping nothing, because an anchor with no content is a keyboard focus stop with no accessible name.
+**It names itself.** The link sets `aria-label` to the image's alt text (`image.altText ?? variant.name`, trimmed), so it keeps that name when the wrapped image is replaced by the hidden placeholder (a load error, or a blank URL). A loaded image gives the same name as before. An `aria-label` passed to the link wins over it. On a line whose `variant.image` is `null`, or whose name is blank, the leaf still renders its children unwrapped instead of wrapping nothing, because an anchor with no accessible name is a keyboard focus stop.
 
 **No usable product URL, no link.** The leaf runs `detailUrl` through `resolveSafeHref`, the same allowlist the navigation particle applies to CMS-authored destinations, and renders its children unwrapped when the destination is blank or refused: `javascript:`, `data:`, protocol-relative, or malformed. A safe `detailUrl` is a logical path: `NavigationLink` prefixes it for the current binding. The particle gates only `$content.href`, so a platform URL arriving on the `href` prop is this leaf's to validate. Either way the image still shows: the leaf never self-hides, unlike the data-bearing leaves below, because hiding a wrapper would take its content with it. A refusal logs its reason and never the value and still renders the children unwrapped; a blank URL is ordinary and stays quiet.
 
 Navigation is client-side through the `NavigationLink` particle, which also owns `rel` hardening. The link is same-tab, and `target` is omitted from the props type rather than merely left out of the schema, because an image-only link cannot carry the "(opens in new tab)" cue a `_blank` destination needs.
 
-**Known gap:** a mini-cart drawer does **not** dismiss itself when a client-side navigation leaves it, so the overlay stays open over the product page. This is not specific to this leaf — `CartGoCheckout` behaves the same way — and it belongs to the drawer composition, not to a line leaf.
+**Known gap:** a mini-cart drawer does **not** dismiss itself when a client-side navigation leaves it, so the overlay stays open over the product page. The product link behaves that way, and it belongs to the drawer composition, not to a line leaf. `CartGoCheckout` closes the drawer itself when it leaves for the checkout.
 
 Renders `a[data-fs-cart-item-product-link]`, which also carries the particle's `data-fs-navigation-link`.
 
@@ -72,10 +82,19 @@ CartItemRoot
        └─ CartItemRemove        (removes this line from within its alert)
 ```
 
-**Label-vs-children nuance:** passing children to `CartItemUnavailable` **replaces** its built-in state label (`children ?? unavailableLabel(availability)`). A remove-on-alert composition therefore renders the label as an explicit child (e.g. a `Text`) next to the `CartItemRemove`; nesting the remove control alone leaves the alert without a label. The whole subtree is availability-gated: when the line is `AVAILABLE`, neither the label nor the nested remove control renders.
+**Label-vs-children nuance:** passing children to `CartItemUnavailable` **replaces** its state label, which is one `$content` message per state (`outOfStockLabel` for `OUT_OF_STOCK`, `cannotBeDeliveredLabel` for `UNAVAILABLE`, `unavailableLabel` for any other state; content type `cart-item-unavailable`), formatted only when no children are given. A remove-on-alert composition therefore renders the label as an explicit child (e.g. a `Text`) next to the `CartItemRemove`; nesting the remove control alone leaves the alert without a label. The whole subtree is availability-gated: when the line is `AVAILABLE`, neither the label nor the nested remove control renders.
 
 For the cart-level counterparts (the "N items unavailable" summary and the bulk "remove all unavailable" button), see `cart.md` — Unavailable-item recovery.
 
+## Removal feedback
+
+`CartItemRemove` awaits the removal and tells the shopper when it went through:
+
+- **Disabled while pending.** The button carries the native `disabled` attribute from the click until `removeItem` settles, so a second click sends no second request. A caller-passed `disabled` is kept.
+- **Toast on a clean result only.** When `removeItem` resolves with an empty `userErrors` list, the button raises one `success` toast titled by the `removedMessage` message (content type `cart-item-remove`). A non-empty list, a missing `removeItem`, or a rejection raises no toast; failures keep surfacing through `CartError`.
+- **`removedMessage`** is a `$content` field, not a prop. The toast carries the title alone: no description, no action.
+- **Needs a `ToastProvider`.** The toast shows through the layout's `ToastList`. Without a `ToastProvider` above the line, no toast shows and the removal still works.
+
 ## Gift lines
 
 A promotion can add a line the shopper never chose. `CartItem.gift` marks it, and three things follow from that one flag — none of them requiring a different template, because `CartList` renders the same children for every row:
@@ -83,17 +102,29 @@ A promotion can add a line the shopper never chose. `CartItem.gift` marks it, an
 ```text
 CartItemRoot                    (row carries data-fs-cart-item-gift-line on a gift line)
   ├─ CartItemListPrice          (renders: a gift's sellingPrice is 0, so listPrice > sellingPrice)
-  ├─ CartItemGift               (renders "Free")
+  ├─ CartItemGift               (renders its label message)
   └─ CartItemRemove             (renders nothing)
 ```
 
-- **`CartItemGift`** is the free marker: a `span[data-fs-cart-item-gift][data-fs-text]` that renders **only** on a gift line, with the built-in English label `Free`. Passing children **replaces** the label (`children ?? 'Free'`), the same nuance `CartItemUnavailable` has. It is an **inline marker, not a wrapper** — its children are the label, so do not nest a block subtree in it. Place it beside `CartItemPrice`/`CartItemListPrice`.
+- **`CartItemGift`** is the free marker: a `span[data-fs-cart-item-gift][data-fs-text]` that renders **only** on a gift line, with the `label` message (content type `cart-item-gift`). Passing children **replaces** the label, which is then not formatted, the same nuance `CartItemUnavailable` has. It is an **inline marker, not a wrapper** — its children are the label, so do not nest a block subtree in it. Place it beside `CartItemPrice`/`CartItemListPrice`.
 - **`CartItemRemove` suppresses itself** on a gift line. A gift is not the shopper's to discard in this phase, and since one template serves every row, the rule lives in the component rather than in the composition. This covers the remove-on-alert composition too: an unavailable gift renders its alert with no remove control, and recovery is the cart-level `CartRemoveUnavailable` batch (which still batches gift lines) plus server-side cart validation.
 - **`CartItemQuantity` suppresses itself** on a gift line too, the same way `CartItemRemove` does: a gift's quantity is promotion-controlled, and a `removeOnDecrement` stepper would otherwise let a shopper discard the gift by stepping it below the minimum — the one path the remove-control suppression did not cover. A store showing a gift's fixed quantity composes the read-only `CartItemQuantityValue`, which dispatches nothing.
 - **The row is marked** with `data-fs-cart-item-gift-line`, so a swatch can restyle a gift row without a component per variation — that is how a store hides the `R$ 0,00` selling price on a gift row.
 
 A gift whose `listPrice` is also 0 renders no list price (`CartItemListPrice`'s existing `listPrice <= sellingPrice` rule) and the marker carries the row alone.
 
+## Copy
+
+Every copy-bearing leaf reads its text only from its own `$content`, whose fields are ICU messages. An unauthored message renders empty and logs `message.missing`. A store without CMS authors the fields on the element; a CMS-bound store keeps them in content.
+
+| Component | Content type | Fields |
+|---|---|---|
+| `CartItemDiscountPercentage` | `cart-item-discount-percentage` | `template` (`percentage`, the integer percent) |
+| `CartItemQuantity` | `cart-item-quantity` | `validationMessage` (`value`, the corrected amount) |
+| `CartItemRemove` | `cart-item-remove` | `removedMessage` |
+| `CartItemUnavailable` | `cart-item-unavailable` | `outOfStockLabel`, `cannotBeDeliveredLabel`, `unavailableLabel` |
+| `CartItemGift` | `cart-item-gift` | `label` |
+
 ## Owned data
 
 `CartItemRoot`'s core fragment owns each line's `id`, `quantity`, `price`/`listPrice`/`sellingPrice`, `gift`, `ownTotal`/`total`, `variant { variantId, sku, name, image, availability }`, and the `product` core. `variant.availability` stays here (not a sub-matter) because it is read cross-cuttingly: `CartItemAvailable`/`CartItemUnavailable` gate on it, and `CartCheckoutGuard` reads it across all lines. `gift` stays here for the same reason — `CartItemGift`, `CartItemRemove`'s suppression, and the row's state hook all read it.
@@ -119,7 +150,9 @@ The stepper shows the line's quantity **in the unit the merchant sells in**, not
 
 Enforcement happens **on commit** — blur after typing, pointer release on the buttons, or a keyboard interaction — not per keystroke. A committed amount that is out of bounds or off the multiplier grid is clamped and snapped to the nearest valid amount (ties round up), then the remaining delta is dispatched as `increaseQuantity` / `decreaseQuantity` in purchasable units. No non-integer quantity can reach a mutation. Nothing is corrected at render time: a quantity already outside the authored bounds is displayed as-is and fires no write.
 
-A snap renders a notice as the last child of the stepper: `div[role="alert"][data-fs-cart-item-quantity-validation]`, carrying the `validationMessage` prop, whose `{value}` placeholder is replaced with the corrected displayed amount (default `Quantity adjusted to {value}.`). The root also carries `data-fs-cart-item-quantity-adjusted` plus `data-fs-cart-item-quantity-adjusted-reason="min" | "max" | "multiple"` for per-reason styling, and `data-fs-cart-item-quantity-multiplier="<value>"` whenever the multiplier is not `1`, so a measured line can be styled differently from a counted one.
+A snap renders a notice as the last child of the stepper: `div[role="alert"][data-fs-cart-item-quantity-validation]`, carrying the `validationMessage` message (content type `cart-item-quantity`), whose `value` argument is the corrected displayed amount, formatted in the locale. The root also carries `data-fs-cart-item-quantity-adjusted` plus `data-fs-cart-item-quantity-adjusted-reason="min" | "max" | "multiple" | "platform"` for per-reason styling, and `data-fs-cart-item-quantity-multiplier="<value>"` whenever the multiplier is not `1`, so a measured line can be styled differently from a counted one.
+
+`"platform"` appears when the line lands below the amount the stepper asked for, after the write succeeds: the platform stores the quantity it has in stock (or the per-item limit) instead of the one requested. The notice reuses the `validationMessage` message and reports the quantity the line holds, replaces a local snap from the same commit, and goes away when the shopper types again, commits again, or the line reaches the requested amount. A write that fails (`userErrors`) raises no platform notice, though a local snap from the same commit still shows. The stepper remembers the requested amount until the next commit or typing, so a line the platform lowers on cart load shows none, but a line that later drops below an amount this stepper already asked for shows the notice again.
 
 `removeOnDecrement`: a committed amount below the configured minimum removes the line instead of clamping, and no notice is raised. In that mode the decrement control is **not** disabled at the minimum — removal is the intended outcome there — and `data-fs-cart-item-at-min` still keys off the purchasable count. This never applies to a gift line: the stepper renders nothing there, so `removeOnDecrement` cannot discard a gift.
 
@@ -133,7 +166,7 @@ The measurement unit itself (`kg`, `un`) is not fetched, so a measured line rend
 
 `CartItemDiscounts` is another **optional** per-line data owner: it owns the line's `discounts` subtree via its own `reactive-list-item` fragment and requires only `cart-item`, so its data is fetched **only** on pages that place it. It renders one labeled row per featured promotion applied to the current cart line — the promotion `name` plus its amount (e.g. `Black Friday −R$ 20,00`, `Cupom −10%`) — so a shopper sees *which* promotion took *how much* off *this* item. It is the itemized companion to the aggregated `Discounts` totalizer line in the footer.
 
-Each row branches on `isPercentual`: a currency discount (`false`) formats the amount from the active storefront context; a percentual discount (`true`) renders `−N%` and is **not** currency-formatted. Every amount carries a presentational leading `−` — the source `value` is a positive amount. It **renders null when the line has no discounts** (empty or unresolved), so it appears only where a promotion actually fired. Place it under the line, near the price area. Must be inside `CartList`.
+Each row branches on `isPercentual`: a currency discount (`false`) formats the amount from the active storefront context; a percentual discount (`true`) renders `−N%` and is **not** currency-formatted. Every amount carries a presentational leading `−` — the source `value` is a positive amount. It **renders null when the line has no discounts** (empty or unresolved), so it appears only where a promotion actually fired. Place it under the line, near the price area. Must be inside `CartList`, `CartAvailableItems` or `CartUnavailableItems`.
 
 **Distinct from `CartItemDiscountPercentage`.** `CartItemDiscountPercentage` is a single derived `−N%` **badge** computed from `listPrice`/`sellingPrice` with **no** promotion name; `CartItemDiscounts` is the **named list** of promotions sourced from the line's `discounts` field. They cover different concerns and may coexist on a line — the badge next to the price, the named list beneath it.
 
@@ -141,7 +174,7 @@ Renders a `div[data-fs-cart-item-discounts]` container with one `span[data-fs-ca
 
 ### CartItemCustomizations
 
-`CartItemCustomizations` is an **optional** per-line data owner: it owns the line's `customizations` subtree via its own `reactive-list-item` fragment and requires only `cart-item`, so its data is fetched **only** on pages that place it. It renders the form-based personalization a shopper applied to the line — engraving text, a size selection, an uploaded file's URL — as one group per assembly, each group listing its `entries` as `name` / `value` rows (e.g. `Text: MARIA`). It **renders null when the line has no customizations** (empty or unresolved). Must be inside `CartList`.
+`CartItemCustomizations` is an **optional** per-line data owner: it owns the line's `customizations` subtree via its own `reactive-list-item` fragment and requires only `cart-item`, so its data is fetched **only** on pages that place it. It renders the form-based personalization a shopper applied to the line — engraving text, a size selection, an uploaded file's URL — as one group per assembly, each group listing its `entries` as `name` / `value` rows (e.g. `Text: MARIA`). It **renders null when the line has no customizations** (empty or unresolved). Must be inside `CartList`, `CartAvailableItems` or `CartUnavailableItems`.
 
 The group heading is the raw assembly `id` (e.g. `Engraving`); pretty display names are deferred (836 Decision 2). An uploaded-file value surfaces as its URL string and is rendered verbatim — there is no file-preview/download widget in v0 (836 exposes no file metadata; at parity with fastcheckout).
 
@@ -149,7 +182,7 @@ Renders a `div[data-fs-cart-item-customizations]` container with one `div[data-f
 
 ### CartItemCompositions
 
-`CartItemCompositions` is an **optional** per-line data owner: it owns the line's `compositions` subtree via its own `reactive-list-item` fragment and requires only `cart-item`, so its data is fetched **only** on pages that place it. It renders the nested bundle/assembly tree a shopper built under the line — each child row shows the child's `name`, `quantity` (`×N`), and formatted unit `price`. It **renders null when the line has no compositions** (empty or unresolved). Must be inside `CartList`.
+`CartItemCompositions` is an **optional** per-line data owner: it owns the line's `compositions` subtree via its own `reactive-list-item` fragment and requires only `cart-item`, so its data is fetched **only** on pages that place it. It renders the nested bundle/assembly tree a shopper built under the line — each child row shows the child's `name`, `quantity` (`×N`), and formatted unit `price`. It **renders null when the line has no compositions** (empty or unresolved). Must be inside `CartList`, `CartAvailableItems` or `CartUnavailableItems`.
 
 **Recursion.** A composition child is itself an order-form line, so it can carry its own nested `compositions` (a sub-bundle) and its own `customizations` (836 Decision 8). The matter recurses over the in-slice `compositions` array with an internal render function: each node renders its row, its own customization groups (using the same `name`/`value` anatomy as `CartItemCustomizations`, so one swatch styles both), then its nested children at `depth + 1`. Recursion is over finite data — the server guarantees acyclic compositions (836 visited-index) and depth is bounded by the assembly config. React keys use the node `id`.
 
@@ -157,6 +190,6 @@ Renders a `div[data-fs-cart-item-compositions]` container with one `div[data-fs-
 
 ### CartItemVariations
 
-`CartItemVariations` is another **optional** per-line data owner: it owns the line's `variant.selectedOptions` subtree via its own `reactive-list-item` fragment and requires only `cart-item`, so its data is fetched **only** on pages that place it. It renders one labeled row per variation selected on the current cart line (e.g. `Cor: Vermelho`, `Tamanho: M`), so a shopper can tell two lines of the same product apart. It **renders null when the line has no selected options** (empty or unresolved), so it appears only where the SKU actually has variations. Place it near the product name. Must be inside `CartList`.
+`CartItemVariations` is another **optional** per-line data owner: it owns the line's `variant.selectedOptions` subtree via its own `reactive-list-item` fragment and requires only `cart-item`, so its data is fetched **only** on pages that place it. It renders one labeled row per variation selected on the current cart line (e.g. `Cor: Vermelho`, `Tamanho: M`), so a shopper can tell two lines of the same product apart. It **renders null when the line has no selected options** (empty or unresolved), so it appears only where the SKU actually has variations. Place it near the product name. Must be inside `CartList`, `CartAvailableItems` or `CartUnavailableItems`.
 
 Renders a `div[data-fs-cart-item-variations]` container with one `span[data-fs-cart-item-variation]` per option; each row wraps a `span[data-fs-cart-item-variation-name]` (e.g. `Cor`), a `span[data-fs-cart-item-variation-separator]` holding the `": "` delimiter, and a `span[data-fs-cart-item-variation-value]` (e.g. `Vermelho`). The separator is a hook of its own so a store can restyle or hide the delimiter without the punctuation riding along with the label; with no swatch applied a row still reads `Cor: Vermelho`. No props beyond the standard `div` attributes; the list is data-driven and `children` is not used to override it.

package/dist/docs/cart-totalizer.md

@@ -49,9 +49,9 @@ CartTotalizerRoot          ← reactive data provider (totalizers + total)
 | Component | Props | Notes |
 |---|---|---|
 | `CartTotalizerRoot` | `$data` | Provides `CartTotalizerContext` and `CartTotalValueContext`; lines format from the active storefront context |
-| `CartTotalizerLine` | `totalizerId`, `label?`, `variant?`, `zeroLabel?` | `variant="discount"` auto-hides when `amount === 0` |
-| `CartDiscountLine` | `otherLabel?` | Itemized discount breakdown: one line per promotion/coupon plus the residual. Self-hides when empty. Owns its own `Cart.discounts` slice |
-| `CartMarkdownLine` | `label?` | Aggregate item-level catalog markdown (`Σ listPrice − price`): a single negative line, self-hides at zero. Distinct money from the `Discounts` totalizer / `CartDiscountLine` — may be shown alongside them. Owns its own `Cart.itemMarkdownTotal` slice |
+| `CartTotalizerLine` | `totalizerId`, `label?`, `variant?`, `zeroLabel?` | `variant="discount"` auto-hides when the amount is numerically zero, whatever its wire form (`0`, `"0.00"`, `"-0.00"`); in any variant the line renders nothing when the amount is not a finite number |
+| `CartDiscountLine` | `$content.otherLabel` | Itemized discount breakdown: one line per promotion/coupon plus the residual. Self-hides when empty. Owns its own `Cart.discounts` slice |
+| `CartMarkdownLine` | `$content.label` | Aggregate item-level catalog markdown (`Σ listPrice − price`): a single negative line, self-hides at zero. Distinct money from the `Discounts` totalizer / `CartDiscountLine` — may be shown alongside them. Owns its own `Cart.itemMarkdownTotal` slice |
 | `CartTotal` | `label?` | The single root-agnostic grand total; reads `CartTotalValueContext` provided by either root. Set `label` to render a labeled total row (e.g. "Total") |
 
 ---
@@ -75,8 +75,9 @@ storefront context wherever it renders.
 single "Discounts" figure is enough.
 
 The `name` a promotion or coupon carries comes from the platform; the API leaves the residual (and any
-unnamed promotion) without a name, so `otherLabel` supplies the label for those (default
-`"Other discounts"`, override per store).
+unnamed promotion) without a name, so the `otherLabel` message (content type `cart-discount-line`)
+supplies the label for those. It reads only from `$content`: an unauthored message renders empty and logs
+`message.missing`. A store without CMS authors it on the element, as below.
 
 Style hooks: `data-fs-cart-discount-lines` on the group, and per row
 `data-fs-cart-discount-line` (with `data-fs-cart-discount-line-kind` = `promotion` / `coupon` / `other`),
@@ -125,7 +126,8 @@ from the running total. What you must not do is interleave it as a plain negativ
 subtotal and the total, because it is not part of that sum. The `ItemMarkdown` story shows the
 list-price framing.
 
-The `label` prop words the row (default `"Item discounts"`, override per store).
+The `label` message (content type `cart-markdown-line`) words the row. It reads only from `$content`: an
+unauthored message renders empty and logs `message.missing`.
 
 Style hooks: `data-fs-cart-markdown-line` on the row (also `data-fs-text`), with
 `data-fs-cart-markdown-line-label` and `data-fs-cart-markdown-line-value`.