@vtex/faststore 0.0.1

package/dist/docs/cart.md

@@ -0,0 +1,495 @@
+# Cart
+
+**Category:** commerce
+**Purpose:** Cart **read** layer for the store. `CartRoot` loads the active cart and exposes it (and the cart query error) to descendants, keeping them in sync as the cart changes. It is **hosted by the layout** (shared shell), wrapping the page slot — so every page, including PDPs, consumes its context without declaring it.
+
+Cart **writes** (add / remove / quantity) no longer flow through `CartRoot`. A component declares the cart methods it needs as an `actions: { cart: [...] }` selector on its definition and dispatches through the compiler-injected `$actions.cart.*` prop — the write-side mirror of `fragment` → `$data`. Cart writes are **context-free**: an add-to-cart button works on a PDP, a product card, a search result, or the header with **no `CartRoot` ancestor** (specs/actions.md, ADR-0010).
+
+This doc covers `CartRoot` — hosted in the layout, never emitted in page schemas — plus the **mini-cart footer checkout CTA** ([below](#mini-cart-footer-checkout-cta)), the composition of `CartCheckoutGuard` → (`CartTotal` + `CartGoCheckout`). The remaining cart line-item and summary particles (`CartList`, `CartItem*`, `CartCount`, `CartError`) exist in the catalog and will be documented when the full cart page enters scope.
+
+---
+
+## Visual cues (how to identify in an image)
+
+`CartRoot` is a data provider, not a visible widget — you do not see it directly. The image is the source of truth for layout. The cart-aware element that requires it is a **cart read**:
+
+- A **mini-cart count, total, or line-item list** anywhere on the page reads cart state and needs a `CartRoot` ancestor.
+- An **empty cart panel** — a drawer or panel with no line items showing a short "your cart is empty" line and a "continue shopping" button, often paired with an illustration — is the `CartEmpty` branch: compose `CartEmptyMessage` for the sentence and `CartContinueShopping` for the button, never a plain `Text` plus `DrawerClose`.
+
+An **add-to-cart CTA** ("Comprar", "Adicionar ao carrinho") does **not** require `CartRoot`: it writes through `$actions.cart.addItem`, which reads and writes the cache directly (context-free).
+
+When the image shows a cart read, the page must render under a layout that hosts `CartRoot` — the default layout already does. **Do not add `CartRoot` to the page schema**: the layout's instance wraps the page slot, so the ancestor requirement is already satisfied.
+
+---
+
+## When to use
+
+- In the **layout** (shared shell), as the root element wrapping header, page slot, and footer — the canonical and only standard placement. Every page under that layout (PDP, category, checkout) consumes its context.
+- On a dedicated cart/mini-cart page **only when its layout does not already host `CartRoot`** (rare, custom shells) — then it wraps the cart line items and summary.
+
+## When NOT to use
+
+- **In a page schema whose layout already hosts `CartRoot`** — that duplicates the provider (one per tree, never two), triggers the nested-reactive-root warning (AD-D8), and moves the cart query into the server-side page fetch, where no user cookie exists — the server mints a throwaway cart on every render.
+- As a generic layout wrapper for centering content — that is `Container`. `CartRoot` is specifically the cart data provider.
+- Around only the buy button — cart context comes from the layout; the buy button needs no local wrapper.
+
+---
+
+## Composition
+
+`CartRoot` is the cart **read** context provider. It declares a GraphQL fragment for the active cart (the server resolves it from the session cookie) and uses a reactive fetch strategy so cache writes propagate to descendants without a refetch. It lives in the layout, wrapping the page slot:
+
+```
+Layout
+└── CartRoot
+    ├── Header (mini-cart count, drawer)
+    ├── Slot ← page content renders here
+    │   └── Container (PDP page schema — no CartRoot)
+    │       ├── ProductGalleryRoot
+    │       ├── ProductInformationRoot
+    │       ├── PricingRoot
+    │       └── BuyButtonRoot
+    │           └── BuyButtonButton
+    └── Footer
+```
+
+Cart **read** particles (`CartCount`, `CartTotal`, `CartList`, and the `CartItem*` line-item particles) read from `CartRoot` via the `useCart()` hook and throw at render time if no `CartRoot` ancestor exists. The layout's instance satisfies that requirement for every page it hosts — a provider declared on the layout satisfies a consumer declared on the page.
+
+Cart **write** consumers (`BuyButtonButton`, `ProductCardAddToCart`, `CartItemQuantity`, `CartItemRemove`) declare `actions: { cart: [...] }` and dispatch via `$actions.cart.*`. They need no `CartRoot` ancestor; the compiler wraps each one with a provider that supplies the handlers. `CartError` surfaces cart write errors from a module-level reactive var, so it too works without reading the cart context.
+
+---
+
+## Post-add behavior (open the mini-cart vs. redirect to checkout)
+
+What happens after a successful add to cart is a **per-store choice made by composition**, not a config flag. The store composes exactly one of two behavior components — there is no `global.json` switch deciding it.
+
+- **Mini-cart store → `CartOpenOnAdd`.** When the store has a mini-cart drawer, compose `CartOpenOnAdd` as the **parent of the mini-cart `DrawerRoot`** (its single child). It opens the drawer automatically on each successful add, with the new item visible and the count updated. It controls the drawer internally, so **do not set raw `open` / `onOpenChange` on `DrawerRoot`** — those are not authorable props, and the header `DrawerTrigger` plus manual close (Escape / backdrop / close button) keep working through the encapsulated wiring.
+
+- **No-mini-cart store → `CartRedirectOnAdd`.** When the store has **no** mini-cart and adding a product should send the shopper straight to checkout, compose `CartRedirectOnAdd` (and omit the drawer entirely). It navigates to `href` (default `/checkout`) after each successful add. It renders no UI of its own; place it once in the layout.
+
+The two are **mutually exclusive — compose exactly one**. A store with a mini-cart uses `CartOpenOnAdd` and never `CartRedirectOnAdd`; a store without one uses `CartRedirectOnAdd` and omits the drawer. Both react only to a **successful** add (a failed add or one returning user errors triggers neither).
+
+### Composition — `CartOpenOnAdd` around the mini-cart drawer
+
+```
+CartRoot (layout)
+└── Header
+    └── CartOpenOnAdd          ← post-add behavior; controls the drawer below
+        └── DrawerRoot         ← no raw open/onOpenChange props
+            ├── DrawerTrigger (CartCount badge — "minha cesta")
+            └── DrawerPortal
+                ├── DrawerBackdrop
+                └── DrawerPopup (CartList body + CartTotal / CartGoCheckout footer + DrawerClose)
+```
+
+### Composition — `CartRedirectOnAdd` in a no-mini-cart store
+
+```
+CartRoot (layout)
+├── Header (add-to-cart CTAs elsewhere; no drawer)
+└── CartRedirectOnAdd          ← navigates to /checkout on a successful add
+```
+
+---
+
+## Components
+
+### CartRoot
+
+Top-level cart **read** wrapper and data provider. Loads the active cart and exposes it (and the cart query error) to all descendants. Writes are dispatched through `$actions.cart.*`, not this provider.
+
+Cart prices and the total are formatted from the active storefront context (the resolved binding's
+locale and currency), not from props — there is nothing to author here.
+
+**Data:** declares `fragment CartData on Query` for the active cart and uses a reactive fetch strategy — cache writes from the `cart` action re-render every descendant particle without a refetch.
+
+---
+
+### CartItemDiscountPercentage
+
+Per-line discount badge. Renders the integer discount percentage of the current cart line — the `listPrice`-vs-`sellingPrice` difference (e.g. `-20%`) — so a shopper sees how deep each line's promotion is. It reads the line from the surrounding `CartList` item context and **renders null when the line has no discount** (`sellingPrice >= listPrice`), so it only ever appears on promotional lines. Place it alongside `CartItemPrice` and `CartItemListPrice` in the line-item template. Must be inside `CartList`.
+
+The percentage matches the PDP `PricingDiscount` badge for the same product — both round with `Math.round` — so a 19.5% discount shows `-20%` on both surfaces.
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| `template` | string | `"-{percentage}%"` | Output format; `{percentage}` is replaced by the integer percent (e.g. `"{percentage}% OFF"`) |
+
+---
+
+### CartEmptyMessage
+
+The empty-cart message, rendered as a paragraph (`data-fs-cart-empty-message`, plus the `data-fs-text` identity). Place it inside `CartEmpty`. The wording is **merchant-editable**: a published CMS entry for the element wins over the `text` prop, and blank copy (an empty or whitespace-only string, from either source) renders nothing. It carries **no layout** — group and space it with `Container`.
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| `text` | string | `"Your cart is empty"` | Non-CMS fallback. A CMS entry's `text` wins over it |
+
+**Content:** declares the `cart-empty-message` content model (one `text` property), so the copy can change without a deploy.
+
+---
+
+### CartContinueShopping
+
+The control that returns the shopper to browsing, rendered as a button (`data-fs-cart-continue-shopping`, alongside `data-fs-drawer-close` and `data-fs-button`). It **dismisses the overlay and dispatches no cart write**. Composed children replace the label, which is how an icon goes inside the button.
+
+It is the drawer's own close control, so it **requires a `DrawerRoot` ancestor** — on a cart page with no drawer, compose a `NavigationLink` back to browsing instead. Placing it outside a drawer fails the render rather than degrading.
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| `label` | string | `"Continue shopping"` | Non-CMS fallback. A CMS entry's `label` wins over it; composed children win over both |
+
+**Content:** declares the `cart-continue-shopping` content model (one `label` property). Authored independently of the message, so publishing one does not require restating the other.
+
+---
+
+## Coupon
+
+Four root-agnostic components wire up the cart coupon flow — apply a code, list the applied coupons, remove one, and surface apply/remove errors. They read `useCart()` (for the applied list) and dispatch through `$actions.cart.applyCoupon` / `$actions.cart.removeCoupon`, so they compose anywhere inside a `CartRoot` subtree. In a mini-cart they sit in the `DrawerPopup` footer, above the totals.
+
+The applied coupons are a **list of chips (1..N)**, not a single-coupon slot — forward-compatible with multi-coupon stores. The server recomputes totals on every apply/remove and returns the updated cart, so `CartTotal` and the totalizer rows update automatically; no optimistic state is used.
+
+| Component | Element | Purpose | Notes |
+|-----------|---------|---------|-------|
+| `CartCouponForm` | `form` | Coupon code input + apply button | Dispatches `$actions.cart.applyCoupon`. Disables input + button and exposes `data-fs-cart-coupon-pending` while an apply is in flight; clears the input on success. |
+| `CartAppliedCoupons` | `div` | Renders one chip per applied coupon | Reads `cart.appliedCoupons`; renders nothing when empty (no container). Each chip shows the `code` inline and a `CartCouponRemove`. An applied-but-no-discount coupon (`isUnmatchedCondition`) is exposed via the `data-fs-cart-coupon-unmatched` hook for the store to style/label (no baked copy). |
+| `CartCouponRemove` | `button` | The per-chip remove control (the X) | Dispatches `$actions.cart.removeCoupon` for the chip's code. Use inside a `CartAppliedCoupons` chip, which supplies the code via context. |
+| `CartCouponError` | `div` (`role="alert"`) | Inline coupon error banner | Reads a **dedicated** coupon error channel, separate from `CartError` (which carries item-write errors). Renders the first error, or nothing when there are none. |
+
+`CartAppliedCoupons` repeats its `children` once per applied coupon (like `CartList` repeats per item): place the chip template — an optional code element plus a `CartCouponRemove` — as its children, and it is cloned per coupon with the coupon supplied via context. Omit `children` to get a built-in chip (code inline + a remove X).
+
+**Errors:** coupon apply/remove `userErrors` (e.g. `COUPON_NOT_FOUND`, `COUPON_EXPIRED`) publish to a dedicated reactive var that only `CartCouponError` reads, so coupon feedback never collides with item-write errors shown by `CartError`. On a single-coupon store, a rejected second code surfaces here as a normal apply error.
+
+**Styling split:** these components own behaviour and the `data-fs-*` hooks (`data-fs-cart-coupon-form`, `-input`, `-apply`, `-pending`, `data-fs-cart-applied-coupons`, `data-fs-cart-coupon`, `-code`, `-unmatched`, `data-fs-cart-coupon-remove`, `data-fs-cart-coupon-error`). Chip and X **visuals (swatch values) are authored by the styling pipeline**, not these components.
+
+Coupon block inside a mini-cart `DrawerPopup` footer, at the top of the footer above the totals and checkout CTA (the footer lives inside the `CartFilled` branch — coupons only matter for a non-empty cart):
+
+```json
+{
+  "popup-footer": { "type": "Container", "children": ["coupon-block", "footer-summary", "checkout-cta", "footer-keep-shopping"] },
+  "coupon-block": { "type": "Container", "children": ["coupon-form", "applied-coupons", "coupon-error"] },
+  "coupon-form": { "type": "CartCouponForm", "props": { "placeholder": "Coupon code", "applyLabel": "Apply" } },
+  "applied-coupons": { "type": "CartAppliedCoupons", "children": ["coupon-remove"] },
+  "coupon-remove": { "type": "CartCouponRemove" },
+  "coupon-error": { "type": "CartCouponError" }
+}
+```
+
+---
+
+## Canonical schema example
+
+Layout hosting `CartRoot` as its root, wrapping the page slot:
+
+```json
+{
+  "root": { "type": "CartRoot", "children": ["header", "main", "footer"] },
+  "header": { "type": "Container", "children": ["mini-cart-count"] },
+  "mini-cart-count": { "type": "CartCount" },
+  "main":   { "type": "Container", "children": ["slot"] },
+  "slot":   { "type": "Slot" },
+  "footer": { "type": "Container" }
+}
+```
+
+PDP page schema under that layout — **no `CartRoot`**; the buy button consumes the layout's context:
+
+```json
+{
+  "root": { "type": "Container", "children": ["gallery", "product-info", "pricing", "buy-button"] },
+  "gallery":      { "type": "ProductGalleryRoot" },
+  "product-info": { "type": "ProductInformationRoot", "children": ["title", "description"] },
+  "title":        { "type": "ProductInformationTitle" },
+  "description":  { "type": "ProductInformationDescription" },
+  "pricing":      { "type": "PricingRoot", "children": ["pricing-selling"] },
+  "pricing-selling": { "type": "PricingSellingPrice" },
+  "buy-button":   { "type": "BuyButtonRoot", "children": ["buy-button-action"] },
+  "buy-button-action": { "type": "BuyButtonButton", "props": { "availableLabel": "Comprar", "unavailableLabel": "Indisponível" } }
+}
+```
+
+---
+
+## Mini-cart loading / empty / filled state
+
+A mini-cart (or any cart surface) must show a different surface in each of three states. While the reactive cart is still loading it shows a skeleton placeholder. Once it resolves with items, it shows the line-item list, the order summary, and the checkout CTA. Resolved-empty, it shows a short message and a way back to browsing — and it must **not** show a "R$ 0,00" total or a checkout button that leads nowhere.
+
+This is pure composition with three mutually-exclusive self-hide branches — `CartLoading`, `CartEmpty`, `CartFilled`. All read the cart from `CartRoot` and render their children only for their case; **exactly one renders at a time** (loading → empty → filled):
+
+- **`CartLoading`** renders its children only while the cart has **not** resolved (`cart == null`, the initial reactive load). It carries **no content of its own** — supply a skeleton placeholder as its child so the drawer body shows a skeleton during load instead of a blank surface. Do **not** put `CartList` here — `CartList` lives inside `CartFilled` and renders its own skeleton window when used standalone; reusing it under `CartLoading` would double-compose. Use simple placeholder rows (a few `Container`/`Text` skeleton blocks) instead.
+- **`CartFilled`** renders its children only when the cart has resolved with one or more items. Wrap the `CartList`, the `CartTotal` rows, and `CartGoCheckout` in it — `CartTotal` falls back to "R$ 0,00" and `CartGoCheckout` still routes to checkout on their own, so wrapping them in `CartFilled` is what hides them when the cart is empty.
+- **`CartEmpty`** renders its children only when the cart has resolved and is empty (zero items). It never shows while the cart is loading (`CartLoading` owns that window), so the empty message does not flash before the cart resolves. It carries **no copy of its own** — compose `CartEmptyMessage` and `CartContinueShopping` inside it.
+
+The empty panel's copy lives in two leaves, one string each, so the panel is a composition rather than a configured block:
+
+- **`CartEmptyMessage`** renders the message as a paragraph (`data-fs-cart-empty-message`). The wording is merchant-editable: a CMS entry wins over the `text` prop, which defaults to "Your cart is empty"; blank copy renders nothing.
+- **`CartContinueShopping`** renders the control that returns the shopper to browsing (`data-fs-cart-continue-shopping`). Its `label` is merchant-editable the same way, and composed children replace the label when you want an icon inside the button.
+
+Neither leaf renders a wrapper or carries spacing, so **order, grouping, and any illustration are yours**: put an `Icon` above the message, wrap the pair in a `Container`, pin the control to a footer `Container`. Both self-hide independently, so composing only one is valid.
+
+Continue-shopping is a **non-mutating** control, not a cart action. Which control depends on the surface:
+
+- **Inside the mini-cart drawer**, use `CartContinueShopping` — it closes the drawer through the drawer's own contract and dispatches no cart write.
+- **On a cart or checkout page** (no drawer to close), use a storefront `NavigationLink` (e.g. `href="/"`) back to browsing. Do **not** place `CartContinueShopping` there: it is a drawer close, and without a `DrawerRoot` ancestor the render fails.
+
+```text
+CartRoot (layout)
+└── DrawerPopup body + footer
+    ├── CartLoading           ← only while cart == null (initial load)
+    │   └── skeleton placeholder rows
+    ├── CartFilled            ← only when items.length > 0
+    │   ├── CartList          ← line-item template
+    │   ├── CartTotal (subtotal)
+    │   ├── CartTotal (total)
+    │   └── CartGoCheckout
+    └── CartEmpty             ← only when the cart resolved to 0 items
+        ├── Icon                    ← optional illustration (any particle, any position)
+        ├── CartEmptyMessage        ← "sua cesta está vazia" (CMS copy + prop fallback)
+        └── Container               ← the store's footer grouping
+            └── CartContinueShopping ← "continuar comprando" (closes the drawer; no cart action)
+```
+
+```json
+{
+  "cart-loading": { "type": "CartLoading", "children": ["skeleton-row-1", "skeleton-row-2"] },
+  "skeleton-row-1": { "type": "Container", "style": ["h-16", "animate-pulse", "rounded", "bg-gray-200"] },
+  "skeleton-row-2": { "type": "Container", "style": ["h-16", "animate-pulse", "rounded", "bg-gray-200"] },
+
+  "cart-filled": { "type": "CartFilled", "children": ["popup-body", "subtotal-row", "total-row", "checkout-btn"] },
+  "popup-body": { "type": "CartList", "children": ["cart-item-template"] },
+  "subtotal-row": { "type": "CartTotal", "props": { "label": "subtotal" } },
+  "total-row": { "type": "CartTotal", "props": { "label": "total" } },
+  "checkout-btn": { "type": "CartGoCheckout", "props": { "href": "/checkout", "children": "continuar" } },
+
+  "cart-empty": { "type": "CartEmpty", "children": ["empty-illustration", "empty-msg", "empty-footer"] },
+  "empty-illustration": { "type": "Icon", "props": { "name": "shopping-bag" } },
+  "empty-msg": { "type": "CartEmptyMessage", "props": { "text": "sua cesta está vazia" } },
+  "empty-footer": { "type": "Container", "children": ["keep-shopping-btn"] },
+  "keep-shopping-btn": { "type": "CartContinueShopping", "props": { "label": "continuar comprando" } }
+}
+```
+
+On a cart/checkout page there is no drawer to close, so the empty branch keeps `CartEmptyMessage` and swaps `CartContinueShopping` for a storefront `NavigationLink`:
+
+```json
+{
+  "cart-empty": { "type": "CartEmpty", "children": ["empty-msg", "keep-shopping-link"] },
+  "empty-msg": { "type": "CartEmptyMessage", "props": { "text": "sua cesta está vazia" } },
+  "keep-shopping-link": { "type": "NavigationLink", "props": { "href": "/", "children": "continuar comprando" } }
+}
+```
+
+The `text` and `label` props are the non-CMS fallback. When the store publishes a content entry for the element, that entry's copy wins — the two elements are authored independently, so publishing the message does not force you to restate the label.
+
+---
+
+## Common mistakes
+
+- **Adding `CartRoot` to a PDP / standard page schema.** The layout already hosts it wrapping the slot — a page-level instance duplicates the provider and runs the cart query in the server-side page fetch (no user cookie → throwaway cart minted per render).
+- **Nesting two `CartRoot` elements.** There must be exactly one per tree — the layout's.
+- **Using `CartRoot` as a layout box.** For centering and grouping, use `Container`.
+- **Inventing `Cart` (without `Root`).** The entry point is `CartRoot`.
+- **Placing `CartTotal` / `CartGoCheckout` outside `CartFilled`.** They do not self-hide — outside `CartFilled` they render "R$ 0,00" and a dead checkout button over an empty cart. Wrap the list, summary, and checkout in `CartFilled`.
+- **Dropping the loading branch.** Because `CartFilled` (which owns `CartList`) returns null while the cart is loading, the skeleton window only shows if you add a `CartLoading` branch with a skeleton placeholder child. Without it the drawer body is blank until the cart resolves.
+- **Reusing `CartList` inside `CartLoading`.** `CartList` already renders its own skeletons during load — nesting it under `CartLoading` double-composes. Put simple placeholder rows under `CartLoading` instead.
+- **Making continue-shopping a cart action.** It is drawer dismissal, not a mutation — use `CartContinueShopping` inside a drawer and a storefront `NavigationLink` on a page. Never a `$actions.cart.*` call.
+- **Putting the empty message inside `CartEmpty` as a component prop.** `CartEmpty` is copy-free; the copy belongs to the `CartEmptyMessage` leaf composed inside it.
+- **Placing `CartContinueShopping` outside a drawer.** It is the drawer's close control, so a cart page without a `DrawerRoot` ancestor fails to render — compose a `NavigationLink` there instead.
+- **Wrapping the empty copy to get spacing you expect the leaves to provide.** Neither leaf ships layout by design; use `Container` and swatches.
+- **Hard-coding the checkout wording when a CMS is bound.** `CartGoCheckout`'s `label` (and the older `children`) is the fallback; content editors expect the `cart-checkout-label` entry to win.
+- **Expecting a CMS entry to change where checkout goes.** The content channel is the label alone. `href` stays an authored prop.
+
+---
+
+## Mini-cart footer checkout CTA
+
+The mini-cart drawer (the layout composition described on `CartRoot`) ends in a `DrawerPopup` footer that holds the **enriched checkout CTA**: `CartCheckoutGuard` wrapping `CartTotal` and `CartGoCheckout`. Three existing components, composed — there is no `MiniCart` or `CartCheckoutCTA` component to place.
+
+- **`CartCheckoutGuard`** is the outer wrapper. It reads cart availability and, while any line item is not `AVAILABLE`, makes its whole subtree non-interactive (`inert` + `aria-disabled`) and exposes `data-fs-cart-checkout-blocked` for styling the disabled state. The shopper cannot proceed with an undeliverable item. It updates reactively from cache — no refetch, no reload — so the block clears the moment the offending line is removed or becomes available.
+- **`CartTotal`** sits inside the guard, on or next to the button, so the grand total the shopper is about to pay is visible at the CTA. It reads the nearest `CartRoot`/`CartTotalizerRoot` and reformats reactively on every cart change.
+- **`CartGoCheckout`** is the link to checkout (default `href` `/checkout`). During a **client-side** route transition it surfaces a loading state on its content wrapper — `aria-busy` plus `data-fs-cart-go-checkout-pending` — so the shopper sees the click registered. There is **no built-in spinner**: opt into one by styling that attribute (or composing a `Spinner` on it). For an **external or hard** checkout navigation (a non-Next route, a different origin, or a full page load — common for the real VTEX checkout) there is no client-side transition window, so the loading state simply does not show. That is the documented, graceful no-op, not a bug.
+
+**The button wording is CMS content.** It resolves in a fixed order: the `cart-checkout-label` entry, then the `label` prop, then `children`, then the package default `"Checkout"`. So a merchant rewords the CTA — `"Finalizar compra"`, `"Ir para o pagamento"` — with a CMS save and no deployment, while a store with no CMS binding renders its authored value. `children` stays supported because that is where stores labelled the button before `label` existed; a CMS entry overrides it with no schema edit. A blank or whitespace-only entry value counts as unconfigured and falls through. Non-compiler hosts (Storybook, tests) pass a typed `$content` fixture directly.
+
+**The destination is not content-editable.** `href` is an authored prop only. The content channel carries the label alone, so a content editor can change what the button says but never where it goes.
+
+| Prop | Type | Required | Notes |
+|-------|------|----------|-------|
+| `href` | string | no | Checkout destination, default `/checkout`. Never content-editable |
+| `label` | string | no | Authored fallback for the wording. Ignored when an entry supplies a label |
+| `children` | node | no | Legacy label channel, still honoured. Element children are replaced when an entry supplies a label |
+
+Content model (`cart-checkout-label`) fields, edited in the CMS:
+
+| Field | Type | Required | Notes |
+|-------|------|----------|-------|
+| `label` | string | yes | The button wording, rendered verbatim |
+
+Schema shape (inside the `DrawerPopup` footer `Container`):
+
+```json
+{
+  "popup-footer": { "type": "Container", "children": ["checkout-cta"] },
+  "checkout-cta": { "type": "CartCheckoutGuard", "children": ["checkout-total", "checkout-btn"] },
+  "checkout-total": { "type": "CartTotal", "props": { "label": "Total" } },
+  "checkout-btn": { "type": "CartGoCheckout", "props": { "href": "/checkout", "label": "Finalizar compra" } }
+}
+```
+
+The element id is the CTA's content key — its slot inside the scope's one content entry — so name it for the region rather than its styling. Renaming it orphans the merchant's wording: the copy stays in the Content Platform while the component reads a key nobody writes.
+
+Everything stays a layout composition: the guard, total, and link are independently reusable and the mini-cart adds no dedicated component type. To render a visible spinner while the CTA is pending, style `data-fs-cart-go-checkout-pending` or compose a `Spinner` on it; the attribute is the contract.
+
+---
+
+## Unavailable-item recovery
+
+`CartCheckoutGuard` blocks checkout while any line is not `AVAILABLE`; the recovery affordances let the shopper resolve the block from inside the cart. Three pieces, all reading the availability already on the cart:
+
+- **`CartUnavailableCount`** — cart-level summary of how many lines are unavailable (e.g. "2 items unavailable"). Renders a `<span data-fs-cart-unavailable-count>` with a `template` prop (`{count}` is replaced by the integer count; default `'{count} items unavailable'`; children override the text). **Self-hides** (`null`) when every line is available — including while the cart is still loading — so it never shows a false "0 items unavailable". Must be inside `CartRoot`.
+- **`CartRemoveUnavailable`** — the bulk "remove all unavailable" button (`<button data-fs-cart-remove-unavailable>`). On click it dispatches **one** `$actions.cart.removeItems({ ids })` call carrying every unavailable line id: one mutation, one upstream write, one cache update — no per-line flicker. **Self-hides** when there is nothing to remove. Children are the label (default "Remove unavailable items"). Must be inside `CartRoot` (it reads the cart for the ids; the write itself is context-free).
+- **Per-item remove-on-alert** — a `CartItemRemove` nested inside `CartItemUnavailable` in the line-item template, so each unavailable alert carries its own remove control. Composition only, no new component — see `cart-item.md` (including the label-vs-children nuance: children replace the built-in label).
+
+Both cart-level components update reactively: removing the last unavailable line hides them and clears the `CartCheckoutGuard` block with no refetch. Mutation errors surface through the existing `CartError` banner.
+
+Schema shape (mini-cart footer, above the checkout CTA):
+
+```json
+{
+  "popup-footer": { "type": "Container", "children": ["unavailable-summary", "remove-unavailable", "checkout-cta"] },
+  "unavailable-summary": { "type": "CartUnavailableCount", "props": { "template": "{count} items unavailable" } },
+  "remove-unavailable": { "type": "CartRemoveUnavailable", "props": { "children": "Remove unavailable items" } },
+  "checkout-cta": { "type": "CartCheckoutGuard", "children": ["checkout-total", "checkout-btn"] }
+}
+```
+
+---
+
+## Merchant alert banner
+
+`CartAlertRoot` + `CartAlertIcon` + `CartAlertText` carry the **merchant's own** message inside the overlay — a minimum order, a running promotion, a policy note. The copy is CMS-editable, so changing it needs no schema edit and no deploy.
+
+It is a **family, not a single component**: the arrangement is the composition. Compose the two parts in the order the design wants; there is no `iconPosition` prop and never will be.
+
+```text
+DrawerPopup
+├── CartAlertRoot          ← resolves the copy + glyph, self-hides, provides `cart-alert` context
+│   ├── CartAlertIcon      ← the glyph (uploaded image, or predefined sprite name)
+│   └── CartAlertText      ← the message
+├── Container (mini-cart body)
+└── …
+```
+
+Swap the two children and the glyph renders after the copy. Omit `CartAlertIcon` and no glyph renders at all, even when the merchant configured one — composition decides what *can* appear, state decides what *does*. Compose `CartAlertRoot` with **no** children and it falls back to the built-in arrangement (glyph then copy), so the simplest placement is one element.
+
+### Which message surface is this?
+
+| Component | Source | Appears when |
+|---|---|---|
+| `CartAlert*` | **Merchant-authored** (CMS entry, or props) | Always, while a message is configured |
+| `CartError` | Cart mutation `userErrors` | A write failed |
+| `CartCouponError` | Coupon apply/remove errors | A coupon write failed |
+| `CartUnavailableCount` | Cart data (`variant.availability`) | A line cannot be delivered |
+| `cart.messages` | Platform order-form messages | *Not rendered by any component today* |
+
+Do not route merchant copy through `CartError`, and do not route write errors through `CartAlert*`.
+
+### Components
+
+#### CartAlertRoot
+
+Owns **all** resolution and provides `cart-alert` context. The message resolves CMS-first, prop-second. The glyph resolves as a whole channel: a glyph configured in the CMS (an uploaded image or a sprite name) wins over any glyph set through the props, so a merchant who picks an icon in the CMS is never overridden by a developer's fallback `iconUrl` prop. **Self-hides** (`null`) when no non-blank message resolves — an unconfigured banner leaves no empty box, and because the parts are its children, nothing downstream renders either.
+
+Reads **no cart data**: no `CartRoot` ancestor is required, and it adds nothing to the cart query. It is also cart-state agnostic — place it inside `CartFilled` if the banner should disappear on an empty cart.
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| `text` | string | — | Fallback message. No default on purpose: an invented one would ship copy no merchant wrote |
+| `icon` | icon | — | Fallback sprite name. **Unbounded** — the compiler collects the literal and fails the build on a name it cannot resolve |
+| `iconUrl` | string | — | Fallback uploaded glyph; wins over `icon` when both resolve |
+| `iconAlt` | string | `""` | Alt text for the uploaded glyph |
+
+**Content model** — `cart-alert`: `text`, `icon`, `iconUrl`, `iconAlt`. Nothing is `required`, deliberately: a page's or layout's content lives in **one composite entry**, validated as a whole at read time, so a required property would let one blank field invalidate the entry and drop every other content-backed component in that layout with it.
+
+#### CartAlertIcon
+
+The glyph. Prefers the uploaded `iconUrl` (an `<img>`) and falls back to the sprite `icon` name (an `<svg>`); renders nothing when neither resolves. One hook, `data-fs-cart-alert-icon`, covers both element types — so a swatch that sizes it must cover both. Decorative: the message carries the meaning. Must be inside `CartAlertRoot`.
+
+#### CartAlertText
+
+The message, as `<span data-fs-cart-alert-text data-fs-text>`. Copy comes from the Root, so `children` here are a **display override**, not an authoring channel — composing literal copy inside it while the Root has no message renders nothing, because the Root self-hides first. Must be inside `CartAlertRoot`.
+
+### The `icons.include` obligation
+
+`Icon` resolves names against a **compile-time** sprite with no runtime fallback. An `icon` **prop** is a literal the compiler can see, so it is collected automatically. A **CMS-chosen** name does not exist at build time, so a store whose merchants pick the icon must register the admitted names in `global.json`:
+
+```json
+{ "icons": { "include": ["bell", "bell-ringing", "tag", "shopping-cart", "map-pin", "star"] } }
+```
+
+Import `CART_ALERT_ICON_NAMES` rather than retyping the list — it is read off the content model, so the two cannot drift. **Skip this and a merchant-chosen glyph renders as an empty `<svg>`: no build error, no console message.** The uploaded-icon channel has no such obligation; it is an `Image` and never touches the sprite.
+
+Every admitted name is a base-dialect icon, so each resolves in any store regardless of its configured collection. A value outside the set arriving from a stale entry is dropped rather than passed to the sprite lookup.
+
+Schema shape (top of the mini-cart popup):
+
+```json
+{
+  "popup": { "type": "DrawerPopup", "children": ["minicart-alert", "minicart-body", "popup-footer"] },
+  "minicart-alert": { "type": "CartAlertRoot", "props": { "text": "frete grátis acima de R$ 199", "icon": "tag" }, "children": ["minicart-alert-icon", "minicart-alert-text"] },
+  "minicart-alert-icon": { "type": "CartAlertIcon" },
+  "minicart-alert-text": { "type": "CartAlertText" }
+}
+```
+
+Copy first, glyph second — the same components, reordered in `children`, no prop and no component change:
+
+```json
+{
+  "minicart-alert": { "type": "CartAlertRoot", "props": { "text": "pedido mínimo de R$ 50", "icon": "bell" }, "children": ["minicart-alert-text", "minicart-alert-icon"] },
+  "minicart-alert-text": { "type": "CartAlertText" },
+  "minicart-alert-icon": { "type": "CartAlertIcon" }
+}
+```
+---
+
+## Merchant disclaimer
+
+`CartDisclaimer` is the merchant's plain-text notice before the shopper commits — conditions, purchase limits, or legal wording. It renders a `<p data-fs-cart-disclaimer data-fs-text>` and nothing else: no icon, no dismissal, no rich text, and no inline links.
+
+**Two gates, in order.** It renders only when the cart has **resolved with items**, so it stays out of the empty state and out of the loading window on its own — the rule belongs to the component, not to where it is placed, so a disclaimer composed outside `CartFilled` still never appears on an empty overlay. Then the copy must be non-blank: a whitespace-only CMS value counts as **unconfigured**, not as an empty paragraph. Trimming decides whether to render, never what to render — the authored value reaches the DOM verbatim.
+
+**Copy comes from the CMS, with the prop as the fallback.** The component declares the `cart-disclaimer` content model, so `$content.text` wins whenever a content entry supplies it; the `text` prop is the fallback in a non-CMS store, which issues no content read at all. **Neither carries a default**, so a leaf composed before anyone authors copy renders nothing — a package-written disclaimer would assert conditions no merchant agreed to.
+
+**Composed `children` are the highest-precedence override.** As with the other cart leaves (`CartTotal`, `CartCount`, `CartError`), passing `children` in JSX renders them in place of both copy channels — full precedence is `children ?? $content?.text ?? text`. The blank-copy gate only applies to the resolved text; supplied `children` render even when no `text` or content entry exists (the items gate still applies).
+
+**Placement is composition order.** There is no position prop: place it inside `CartFilled`, either below the order summary or immediately above the checkout CTA. Both of those satisfy the design; pick one and order the children accordingly. Must be inside `CartRoot` — it reads the cart to gate itself, and throws without that ancestor like every other cart read component.
+
+Because the mini-cart is a **layout** composition, a disclaimer placed there keys into the **layout's** composite content entry, so its copy is store-wide — the right scope for standing conditions. A store that also wants a different disclaimer on its full cart page places a second instance in that page's schema, which keys into the page's own entry and is authored independently.
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| `text` | string | — | Authored fallback, rendered when no CMS entry supplies the notice |
+
+Schema shape (mini-cart footer, between the summary and the checkout CTA):
+
+```json
+{
+  "popup-footer": { "type": "Container", "children": ["footer-total", "footer-disclaimer", "checkout-cta"] },
+  "footer-total": { "type": "CartTotal", "props": { "label": "Total" } },
+  "footer-disclaimer": { "type": "CartDisclaimer", "props": { "text": "Prices and delivery estimates are confirmed at checkout." } },
+  "checkout-cta": { "type": "CartCheckoutGuard", "children": ["checkout-btn"] }
+}
+```
+
+`$content` is never authored in a schema — it is compiler-reserved and injected from the entry. The `text` prop above is what a pre-CMS store ships; once the store is CMS-bound, a merchant edits the entry and the prop stays as the fallback.
+
+---
+
+## Related
+
+- [[container]] — layout wrapper that usually sits directly under `CartRoot` to group the page blocks.
+- [[buy-button]] — purchase CTA whose `BuyButtonButton` dispatches `$actions.cart.addItem` (context-free; no `CartRoot` needed).
+- [[drawer]] — overlay primitive the mini-cart composes; `CartOpenOnAdd` wraps the `DrawerRoot` to open it on a successful add.
+- [[pricing]] — price block shown alongside the buy button; reads product offer data, not cart data.
+- [[product-information]] — title/description block on the same PDP.