@vtex/faststore 0.0.4 → 0.0.6

package/dist/docs/payment-method-badges.md

@@ -0,0 +1,232 @@
+# PaymentMethodBadges
+
+**Category:** commerce
+**Purpose:** A read-only strip of one badge per payment method the store currently accepts. Derived from the live order form on every render — never authored, never CMS content — so it reflects a method being enabled or disabled with no content edit and no deployment. Ships as **two** components sharing one render contract: `PaymentMethodBadges`, for the checkout payment step, requires a payment-section ancestor; `AcceptedPaymentMethodBadges`, for any other surface — the cart order summary above all — requires none, reading its own `Query.payment` fragment instead. See [Choose between the two](#choose-between-the-two).
+
+---
+
+## Choose between the two
+
+| Surface | Component | Ancestor required |
+|---|---|---|
+| Checkout payment step, alongside the method picker and the card form | `PaymentMethodBadges` | `PaymentSectionRoot` or `PaymentSectionController` |
+| Cart order summary, or any other surface outside a payment section | `AcceptedPaymentMethodBadges` | None — owns its own `Query.payment` fragment |
+
+Both render the identical DOM (the same `data-fs-payment-method-badge*` hooks) from the identical, unfiltered method list, produced by one shared internal render path — so the two surfaces cannot drift apart, and a store styles either one from the same documented hooks (see [Styling](#styling)). Composing both on the same page is legal — they normalize onto the same `Payment` entity — but redundant; pick one per surface.
+
+Neither is one of these three look-alikes:
+
+- **`PaymentMethods`** (`particles/payment-methods/`) — the CMS-authored **footer** strip. Its set is authored content and never reacts to a method being enabled or disabled in the payment configuration; both badge components here read live order-form data and do.
+- **`PaymentMethodList`** — the **selectable** radio picker. Both badge strips are read-only reassurance and dispatch no action.
+- **`CardEntry`'s own detected-network mark** — a single mark (0 or 1), shown only once a network is recognized from typed digits, positioned inside the card-number field's own box and scoped to the card group only. It cannot be placed independently and cannot carry a wallet method.
+
+---
+
+## Visual cues (how to identify in an image)
+
+The image is the source of truth for layout. A `PaymentMethodBadges` strip is present when you see:
+
+- A **horizontal row of small payment-brand flags** (Visa, Mastercard, PayPal, Pix, …) **on the checkout payment step itself** — not in a footer band.
+- Often a **short heading above or beside it**: *Aceitamos*, *We accept*, *Formas de pagamento*.
+- The row sits alongside other payment controls — a card form, a method picker, an installment control — as reassurance, not as one of them: no radio dot, no checkbox, no focus ring on any flag.
+- A flag whose brand has no glyph renders as **plain text naming the method** in the same row — never a blank box for that reason. A *mapped* glyph the store never declared under `icons.include` is a separate, unclosable failure mode — see [Store setup: icon declaration](#store-setup-icon-declaration).
+
+If the same-looking row sits in a **footer band** instead, that is `PaymentMethods`, not this component — see [When NOT to use](#when-not-to-use).
+
+The identical-looking row can also sit in a **cart order summary** — near the subtotal/total block, before checkout, not inside a payment step at all. That is `AcceptedPaymentMethodBadges`, not `PaymentMethodBadges` — see [Choose between the two](#choose-between-the-two).
+
+---
+
+## When to use
+
+- The checkout payment step needs a non-interactive statement of every method the store currently accepts, wallets included, alongside the picker and the card form.
+- One instance per payment step.
+- **A cart order summary** needs the same statement, before the shopper ever reaches checkout → use `AcceptedPaymentMethodBadges` instead (same look, no payment-section ancestor required) — see [Choose between the two](#choose-between-the-two).
+
+## When NOT to use
+
+- A **footer band** of accepted-brand flags, editable in the CMS → use `PaymentMethods`. Its set is authored content and does not react to a method being enabled or disabled in the payment configuration; this component reads real order-form data and does.
+- The **card-number field's own detected-network mark** — a single icon (or name) for the network just recognized from typed digits, scoped to the card group → that is `CardEntry`'s own mark, built into the number field's own box. It cannot be placed independently and cannot carry a wallet method.
+- A **selectable list** of payment methods, with radio controls → use `PaymentMethodList`. This strip dispatches no action and selects nothing.
+- The shopper's **saved cards** → that is `SavedCards`, a different list with different data.
+- **A cart order summary, or any surface with no payment section on the page** → use `AcceptedPaymentMethodBadges`. This component throws when rendered outside a `PaymentSectionRoot` / `PaymentSectionController`; it is not meant to be placed on a cart page.
+
+---
+
+## Composition
+
+`PaymentMethodBadges` is a leaf: it takes no children and renders its own row from `usePayment()`. It requires a payment-section ancestor and declares no fragment of its own — `PaymentSectionRoot` / `PaymentSectionController` already selected the data it reads.
+
+```
+PaymentSectionRoot
+├─ PaymentMethodBadges  ← this strip, reads the section's unfiltered method list
+├─ PaymentMethodList    ← the selectable picker, a sibling — reads a group-scoped subset
+├─ CardEntry
+└─ …
+```
+
+Also composes, unchanged, inside `PaymentSectionController`'s popup — same context, same contract.
+
+`AcceptedPaymentMethodBadges` is also a leaf, but requires **no** ancestor at all: it owns its own `Query.payment` fragment and reads `$data` directly, so it drops independently into either shipped store's own, very different cart-summary composition:
+
+```
+CartRoot                              Container (bare — no totalizer at all)
+├─ CartTotalizerRoot                  ├─ Text
+│    ├─ CartTotalizerLine             ├─ CartTotal
+│    └─ CartTotal                     ├─ AcceptedPaymentMethodBadges  ← this strip, no ancestor needed
+├─ AcceptedPaymentMethodBadges        └─ CartGoCheckout
+└─ CartGoCheckout
+```
+
+No `PaymentSectionRoot`, `PaymentSectionController`, `CartTotalizerRoot`, or any other specific ancestor is required — the compiler resolves and injects its `$data` from a page-level query regardless of what else the page composes.
+
+---
+
+## Store setup: icon declaration
+
+This obligation applies identically to **both** components — they resolve icons through the same frozen
+`PAYMENT_METHOD_ICON_BY_KEY` map and the same shared render path, so there is nothing to declare twice or
+differently for `AcceptedPaymentMethodBadges` versus `PaymentMethodBadges`.
+
+`PaymentMethodBadges` renders each badge's glyph from a name computed in component code — the method's
+store-configured `name`, matched against `PAYMENT_METHOD_ICON_BY_KEY` — never from a schema prop, so the
+compiler's prop-type-driven icon collection never sees it. Same mechanism, same risk, as `CardEntry`'s own
+detected-network icon (see its `.md`, "Store setup: network icon declaration").
+
+**Any store composing `PaymentMethodBadges` or `AcceptedPaymentMethodBadges` must declare every name a
+configured method can resolve to in `global.icons.include`.** Either strip can resolve up to nine
+base-dialect names — `CardEntry`'s five networks plus four wallet glyphs this component adds:
+
+```json
+{
+  "icons": {
+    "include": ["amex", "diners", "elo-card", "mastercard", "visa", "paypal", "google-pay", "pix", "stripe"]
+  }
+}
+```
+
+Declare only the names the store actually configures as payment methods — an unresolved name renders no
+glyph at all, so an unused `include` entry costs nothing, but a store with PayPal enabled and no `paypal`
+entry ships a blank 24×24 box with no build error and no console error. The matching is **token-based, not
+exact-string** (see the component's own `paymentMethodIconName` doc comment), so a name the store never typed
+verbatim can still resolve to a declared key — `"WH Google Pay"` resolves to `google-pay` — which means the
+set of names a strip can produce is wider than the store's literal method labels and has to be read off this
+list, not off the payment configuration's screen.
+
+**If the store's `global.json` already has an `icons` object, extend it — do not replace it**, for the same
+reason `card-entry.md` gives: replacing it silently drops `collection` (or any existing `include` entries),
+and every other icon in that store re-resolves through the fallback default with no error to flag it.
+
+---
+
+## Components
+
+### PaymentMethodBadges
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| `heading` | string | *(none)* | Names the strip and its list for assistive tech. Absent or blank renders no heading element and leaves the list unnamed — never an invented English default |
+
+**Data:** reads `usePayment()`'s method list; declares no fragment of its own. Reads the section's **unfiltered** list — every method the store returns, regardless of the section's `group` — not the group-scoped list `PaymentMethodList` and `CardEntry` read. A wallet method outside the default credit-card group still shows here, which is why this strip and the picker can show different sets on the same page.
+
+**Writes:** none. No action, no selection, no draft.
+
+### AcceptedPaymentMethodBadges
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| `heading` | string | *(none)* | Names the strip and its list for assistive tech. Absent or blank renders no heading element and leaves the list unnamed — never an invented English default |
+
+**Data:** owns its own `Query.payment` fragment (`payment { methods { id name } }`) and reads it via `$data` — no context, no `usePayment()`. Reads the **unfiltered** `Payment.methods` list, the identical field `PaymentMethodBadges` reads through `allMethods` — same set, different plumbing. Renders the container in every case (`loading` while `$data` is unresolved, `empty` once resolved with zero methods — including a partial slice with no `methods` key at all — `ready` otherwise); never throws for lack of a payment-section ancestor, which is the one thing `PaymentMethodBadges` cannot do.
+
+**Writes:** none. No action, no selection, no draft.
+
+---
+
+## Canonical schema example
+
+```json
+{
+  "payment-section": {
+    "type": "PaymentSectionRoot",
+    "children": ["payment-method-badges", "payment-method-list", "payment-card-entry", "payment-place-order"]
+  },
+  "payment-method-badges": { "type": "PaymentMethodBadges" }
+}
+```
+
+`AcceptedPaymentMethodBadges` in a cart order summary, composed as a sibling under `CartRoot` — no payment section anywhere on the page:
+
+```json
+{
+  "cart-root": {
+    "type": "CartRoot",
+    "children": ["cart-summary", "cart-accepted-methods", "cart-go-checkout"]
+  },
+  "cart-summary": {
+    "type": "CartTotalizerRoot",
+    "children": ["cart-total-line", "cart-total"]
+  },
+  "cart-total-line": { "type": "CartTotalizerLine" },
+  "cart-total": { "type": "CartTotal" },
+  "cart-accepted-methods": { "type": "AcceptedPaymentMethodBadges", "props": { "heading": "Aceitamos" } },
+  "cart-go-checkout": { "type": "CartGoCheckout" }
+}
+```
+
+---
+
+## Common mistakes
+
+- **`PaymentBadges`, `PaymentFlags`, `CartPaymentMethodBadges`.** The correct names are `PaymentMethodBadges` (payment step) and `AcceptedPaymentMethodBadges` (everywhere else).
+- **Confusing either one with `PaymentMethods`.** That one is the CMS-authored footer strip. Both badge components here are data-driven and react live to the payment configuration.
+- **Confusing either one with `PaymentMethodList`.** That one is the selectable radio picker. Both badge strips are read-only reassurance; neither dispatches anything.
+- **Authoring a `methods` prop, or expecting a default `heading`, on either component.** There is no `methods` prop on either one — the list is always real order-form data — and `heading` ships with no default on either; an unnamed strip is a valid, intentional state.
+- **Placing `PaymentMethodBadges` outside a payment root.** Like every payment leaf, it requires a `PaymentSectionRoot` or `PaymentSectionController` ancestor and fails the build otherwise. Placing it on a cart page is exactly this mistake — use `AcceptedPaymentMethodBadges` there instead.
+- **Adding a `PaymentSectionRoot` to a cart page just to host `PaymentMethodBadges` there.** Don't — that drags in a submission provider and a write action namespace that do not belong on a cart page. `AcceptedPaymentMethodBadges` needs no such root at all.
+- **Expecting `group`/`groupName` scoping on `AcceptedPaymentMethodBadges`.** There is no such prop on either component — both read the section's/read-model's unfiltered list, on purpose (a scoped strip could never show that a wallet method was enabled or disabled).
+- **Expecting brand-accurate multicolor marks.** The glyphs are single-colour sprite symbols that inherit `currentColor`; literal brand colours are not reachable through either component (see Styling).
+
+---
+
+## Styling
+
+`PaymentMethodBadges` and `AcceptedPaymentMethodBadges` render one root you style directly, plus per-part hooks — the identical set for both, since both are produced by the same internal render path. Each carries its own catalog name, so each gets its own independent swatch entry in `global.json`'s `styles` key even though the two emit the same hooks; style each surface separately if it needs to look different.
+
+| Component | What you style | Plausible classes |
+|---|---|---|
+| `PaymentMethodBadges` / `AcceptedPaymentMethodBadges` (root `div`) | Stacks the heading over the strip | `flex flex-col gap-[12px]` |
+| `data-fs-payment-method-badges-heading` | The strip heading | `text-[14px] font-bold uppercase text-[#1a1a1a]` |
+| `data-fs-payment-method-badges-list` | The badge row, wrapping on narrow screens | `flex flex-wrap items-center gap-[8px] list-none p-0 m-0` |
+| `data-fs-payment-method-badge` | The box one badge occupies | `flex items-center` |
+| `data-fs-payment-method-badge-icon` | The glyph, sized consistently across the row | `w-[32px] h-[20px] text-[#1a1a1a]` |
+
+State hooks worth styling:
+
+- `data-fs-payment-method-badges-state="loading"` / `="empty"` / `="ready"` — always present. Give `loading` and `empty` a `min-h-*` so the strip does not collapse to zero height while resolving or when the store has no method configured.
+
+The list carries an explicit `role="list"`. Keep it: WebKit drops the implicit list role from a `<ul>` whose computed `list-style` is `none`, and `list-none` is exactly what the strip needs.
+
+A method whose name maps to no glyph renders its name as plain text in place of the icon — style that case through `data-fs-payment-method-badge` itself (font, colour); there is no separate icon hook on a text-only badge.
+
+Styled example:
+
+```json
+{
+  "payment-method-badges": {
+    "type": "PaymentMethodBadges",
+    "style": ["flex", "flex-col", "gap-[12px]"],
+    "props": { "heading": "Aceitamos" }
+  }
+}
+```
+
+---
+
+## Related
+
+- [[payment]] — `PaymentSectionRoot` / `PaymentMethodList`: the required ancestor and the sibling method picker. `PaymentMethodBadges` cannot render outside a `PaymentSectionRoot` (or `PaymentSectionController`); `AcceptedPaymentMethodBadges` needs none of it.
+- [[payment-methods]] — the CMS-authored footer strip with the same look; neither badge component is ever interchangeable with it — see [When NOT to use](#when-not-to-use).
+- [[cart-totalizer]] — `CartTotalizerRoot` / `CartTotalizerLine` / `CartTotal`: one of the two shipped shapes a cart order summary can take. This doc's canonical example composes `AcceptedPaymentMethodBadges` as `CartTotalizerRoot`'s sibling, under `CartRoot` (see [Canonical schema example](#canonical-schema-example)). Nothing in the component enforces that position — `CartTotalizerRoot` renders its own `children` through unchanged, so nesting the strip inside them also renders correctly; the sibling placement above is the documented convention, not a requirement.
+- `CardEntry` — owns its own single detected-network mark (0 or 1, never a standing row of every accepted network), scoped to the card group and built into the number field. A different task's deliverable, always a sibling, never a parent of either badge component.
+- `Icon` — the particle each mapped glyph renders. It carries no `.md` of its own; read its schema from `catalog.json`.

package/dist/docs/payment-methods.md

@@ -23,6 +23,7 @@ The image is the source of truth for layout. A PaymentMethods strip is present w
 
 ## When NOT to use
 
+- The **checkout payment step's** own accepted-method strip, which must update the moment a method is enabled or disabled → use `PaymentMethodBadges` (`matter/payment/`). This component's set is CMS content edited by a merchant and does not react to the payment configuration; that one reads the live order form and never needs a content edit.
 - A product's **installment plan or "in 12× of R$ 9,90"** copy → use `PricingPaymentMethodsList`, which reads commerce data for one product rather than store-level configuration.
 - The shopper's **saved cards or payment selection** in checkout → that is a form, not this display strip.
 - A row of **social network icons** → use [[footer-social]]; different content model and different glyph set, and every glyph is a link.

package/dist/docs/payment.md

@@ -0,0 +1,218 @@
+# PaymentSection
+
+**Category:** commerce
+**Purpose:** The checkout payment section: owns the payment-method list and the current selection from the order form, and provides the `payment` context every payment leaf (card entry, cardholder document, installments, save-card, billing address, saved cards, place-order) reads. Ships as two interchangeable providers — an always-visible section (`PaymentSectionRoot`) and a state-only controller for a collapsed drawer/modal (`PaymentSectionController`) — plus the method picker (`PaymentMethodList`).
+
+---
+
+## Visual cues (how to identify in an image)
+
+Use these signals to detect that a payment section is present. Position on the page is irrelevant for detection.
+
+A payment section block contains any combination of:
+
+- A **group of payment-option rows with radio controls** — one card option (e.g. "Pay with Credit / Debit Card"), plus a row for any non-card option the store offers (e.g. "Pix") — one selectable at a time → `PaymentMethodList`. A picker showing one row per card *network* ("Visa", "Mastercard", "Amex") is still this component: it renders one card option instead, because the network comes from the number the shopper types.
+- A **card form** (number, holder name, expiration, CVV) → its own component, placed inside the section.
+- An **installment select or radio list** ("3x de R$ 33,33 sem juros") → its own component, inside the section.
+- A **saved-card list** with masked digits and a "use a new card" entry → its own component, inside the section.
+- A **place-order button** at the bottom of the block.
+
+If the image shows any two or more of those together, they belong inside **one** payment section — wrap them in `PaymentSectionRoot`, never side by side as unrelated blocks.
+
+If the image shows only a **short read-only recap** of the chosen card ("Visa •••• 4242, 3x de R$ 33,33") with no control to change it, that is not this section, and no component renders it in checkout.
+
+If the payment choice is shown as a **summary row that opens a drawer or modal**, use `PaymentSectionController` with the overlay particles, and put a static label (`Text`) inside the trigger — no component echoes the current choice there.
+
+---
+
+## When to use
+
+- The checkout payment step, as the container for every payment control.
+- A compact checkout where payment lives in a drawer or modal (`PaymentSectionController`).
+
+## When NOT to use
+
+- A read-only recap of the chosen card and installment — no component renders one in checkout.
+- A PDP's *advertised* installment plans (display only, no selection) → use `Pricing` / `PricingInstallments`.
+- A post-purchase order-confirmation page. The section reads the *active* order form, which no longer resolves once the order is placed.
+- As a wrapper around non-payment checkout content. The section provides one context and one container; delivery, identity, and cart have their own roots.
+
+---
+
+## Composition
+
+One of the two providers wraps everything payment-related:
+
+```
+PaymentSectionRoot                  ← always-visible section
+├── PaymentMethodList
+├── SavedCards
+├── CardEntry
+├── CardholderDocument
+├── Installments
+├── SaveCard
+├── BillingAddress
+└── PlaceOrder
+```
+
+```
+PaymentSectionController            ← collapsed section; renders no markup of its own
+└── DrawerRoot | DialogRoot         ← receives its open state from the controller
+    ├── DrawerTrigger
+    │   └── Text                    ← the trigger's static label; nothing echoes the current choice
+    └── DrawerPortal
+        ├── DrawerBackdrop
+        └── DrawerPopup
+            ├── PaymentMethodList
+            └── … the same leaves
+```
+
+Both providers declare `providesContext: ['payment', 'card-capture']`. Every leaf declares `requiresContext: 'payment'` except `CardEntry`, which requires only `card-capture`, so the two providers are interchangeable with no change to the children. A leaf placed with **no** payment-section ancestor fails the build with a `ContextConstraintError` — the compiler checks this before emitting any file.
+
+`PaymentSectionController` must wrap **exactly one** overlay `Root` (a `DialogRoot` or `DrawerRoot`) as its child. Anything else is returned untouched and provides no context.
+
+---
+
+## Components
+
+### PaymentSectionRoot
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| `group` | string, or array of strings | `["creditCardPaymentGroup", "debitCardPaymentGroup"]` | Scopes the method list to a set of payment groups — a method renders when its `groupName` is a member. A single string still scopes to exactly that one group. Set to `""` (the empty **string**) to show every method the store offers. An empty **array** (`[]`) is not a second spelling of that opt-out — it matches no group, so every method is scoped out and the list renders empty. It only *filters* — it never supplies methods. |
+
+**Data:** declares `fragment PaymentSectionData on Query`, which selects two root fields: `Query.payment` (the method list with its validator config, plus `selectedMethodId` / `selectedAccountId` / `selectedBin`) and `Query.cart.total`, for the `add_payment_info` event. The compiler merges it into the page query — no `dataSources` entry needed — and, because it has two root fields, delivers `$data` keyed as `{ payment, cart }` (ADR-0015). `fetchStrategy: 'reactive'` — picking a method re-renders the whole section from the cache, no refetch.
+
+**Writes:** `actions: { payment: ['setMethod', 'sendPayments'], analytics: ['track'] }`. Selecting a method dispatches `setMethod`. The root also provides `card-capture` to `CardEntry`: when the place-order sequence runs the `new-card` submission, `CardEntry` builds the card and the root folds in the draft's document, label, and save flag and sends it through `sendPayments`. Once a `CardEntry` is mounted and the cart total has resolved, the root fires `add_payment_info` once.
+
+Renders one container `div` and its children. No heading, no copy, no layout — those belong to the composing schema.
+
+### PaymentSectionController
+
+Same props, same fragment shape, same action. Renders **no element at all**: it holds the overlay's open state and hands it to its single overlay child. Unlike the delivery-options controller, a successful method selection does **not** close the surface — the shopper still has a card to type — so close it from a `DrawerClose` / `DialogClose` particle or from the leaf that finishes the flow.
+
+### PaymentMethodList
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| `legend` | string | `"Payment method"` | The radio group's accessible name, rendered as a visible fieldset legend above the rows (T38). An authored empty or whitespace-only string falls back to this default rather than rendering a nameless group. |
+| `cardLabel` | string | `"Pay with Credit / Debit Card"` | The card option's own name (T171). One control stands for every in-scope credit and debit method at once, so it cannot be labelled from one method's name — this is the copy instead. An authored empty or whitespace-only string falls back to this default rather than rendering a nameless control. |
+
+Renders the inline selection error (`role="alert"`) and the payment options, inside a fieldset named by `legend`. Requires a payment-section ancestor.
+
+**Every in-scope credit and debit method is one option**, named by `cardLabel` — not one row per network. Which card network the shopper is paying with comes from the number they type into the card form, which is the only mechanism that can be right: a shopper who picked "Visa" and then typed a Mastercard number had their pick silently overwritten. Every other in-scope method (e.g. Pix) keeps its own row, labelled with the method's name from the order form and bound to that method's own id, exactly as before. Only the two card groups fold into the card option — a card-like custom method in another group keeps a row of its own. Set `group` to `""` on the root to switch the folding off entirely and get one row per method; the card form still hides for a non-card row and comes back for a card row (see below).
+
+The card option reads as checked while the persisted selection is one of the methods it stands for, **and while nothing is persisted at all** — the card option is the default — and while the section is in card mode (below). It is not bound to any single method id, so activating it dispatches the same candidate the preselection rule would choose (the sole in-scope method, else the sole method in the credit group). When neither is singular — a store with Visa and Mastercard — it dispatches nothing and puts the section in **card mode** instead: the card form comes back at once, the option reads checked, and the method arrives from the typed number. No made-up `"card"` method id is ever sent: the only ids that reach `payment.setMethod` are ids the order form offered.
+
+The container always carries `data-fs-payment-method-list-state` — `"loading"`, `"empty"`, or `"ready"` — so a row-less list is still something a swatch can see. Style at least the `empty` case: with no rows the container has no content, and under a `flex flex-col gap-2` swatch that is a zero-height element the shopper cannot tell apart from a missing component. `empty` means the order form resolved and no method's `groupName` matched the scope; `loading` means it has not resolved yet.
+
+**Keep it composed.** It is the only element that surfaces a rejected method selection, and the only control that can recover a selection this section does not serve: omit it and a shopper whose persisted method sits outside `group` has no reachable way back at all. It also now answers for an action taken elsewhere — a rejection triggered by typing a card number appears in *this* component's `role="alert"`, once per detected network, so place it where a shopper typing into the card form can see it.
+
+### Preselection and the card-payment collapse
+
+When the order form carries no persisted selection and the scoped method list resolves to exactly one method, the section preselects it automatically — one silent `payment.setMethod` dispatch, keyed on that method's id, never on row position. When the scoped list holds more than one method, the section falls back to the sole method in the credit group, if there is exactly one — so a store offering one credit and one debit method keeps preselecting the credit one, the same method it preselected before debit was admitted. **"The credit group" here is always the fixed name `creditCardPaymentGroup`, not whichever member of `group` the store authored** — a store that renamed its credit payment group and listed the new name in `group` gets that method rendered and selectable, but not preselected, and its `add_payment_info` `payment_type` stays unset once picked, because both derive from this same hardcoded name rather than from the store's authored scope. Every other shape preselects nothing. Nothing is preselected while loading, while an order-placement sequence is in flight, when a method or saved-card account is already persisted (in scope or out of it), once a candidate id has already been attempted once, or when `group` is `""` (fix pass, finding R4). Preselection takes no card expression: under `group=""` it stays off even for a single card method, and naming the credit group for the tiebreak never runs there at all. A failed preselection is logged, never shown as `role="alert"` — the shopper never asked for that dispatch.
+
+The rule lives in the shared selection engine, not in `PaymentMethodList`: it fires even when no picker is composed, and before a `PaymentSectionController`'s overlay is ever opened.
+
+The same engine derives the one collapse fact every card leaf reads (T191). **The card payment collapses** while the persisted selection is a method this section does not serve — an id that does not resolve inside the scoped list — or a method that is **not a card**: one in neither card group (`creditCardPaymentGroup`, `debitCardPaymentGroup`) whose validator carries no card-number pattern. A store's card-like custom method, in another group but with a number pattern, is a card and hides nothing. While collapsed, `CardEntry` hides itself and stays mounted, and `SavedCards`, `CardholderDocument`, `Installments`, `InstallmentsSelect`, `SaveCard` and `BillingAddress` render nothing; `PlaceOrder`, `PaymentMethodList` and `PaymentMethodBadges` stay. See each leaf's own doc for what it keeps for the way back.
+
+**The card option brings them back**, with or without a method it can name. With one, it dispatches it, and the leaves return once the order form confirms the selection. With none, it puts the section in card mode, locally — nothing is sent — and the leaves return at once; a card number already typed with at least eight digits is then sent again, once, for its own network. Card mode ends when another method that is not a card is picked and the order form accepts it; a refused pick leaves the shopper on the card, with the refusal in this component's `role="alert"`. Card mode is not persisted: a reload starts over from the order form's selection. Under `group=""` the collapse classifies the same way: a non-card row hides the leaves and a card row brings them back.
+
+Hiding is also conditioned on a composed `PaymentMethodList` being able to bring the card form back (fix pass, finding R2): a leaf must not hide the only remaining way a shopper has to pay by card. A rendered card option always can. Without one, only a row bound to a card method can — a list of non-card rows alone offers no card to pay with. A composition with no picker at all — e.g. `SavedCards` + `CardEntry` — never collapses, whatever the persisted selection is, and typing a new card number stays the way back. Even visible, `CardEntry` never posts a card while the persisted selection is a method it cannot pay (see its own doc).
+
+---
+
+## Canonical schema example
+
+```json
+{
+  "payment-section": {
+    "type": "PaymentSectionRoot",
+    "children": ["payment-method-list", "payment-card-entry", "payment-installments", "payment-place-order"]
+  },
+  "payment-method-list": { "type": "PaymentMethodList" }
+}
+```
+
+---
+
+## Common mistakes
+
+- **Authoring the payment methods as props.** There is no `methods`, `options`, or `labels` prop. Which methods exist is real order-form data. `group` only narrows it, whether given as one group name or a set of them.
+- **Inventing `PaymentSection`, `PaymentRoot`, or `PaymentMethodSelector`.** The components are `PaymentSectionRoot`, `PaymentSectionController`, and `PaymentMethodList`.
+- **Placing a payment leaf outside the section.** Every payment leaf requires the `payment` context; a leaf with no `PaymentSectionRoot` / `PaymentSectionController` ancestor fails the build.
+- **Using both providers on one page for the same section.** Pick one: the always-visible root, or the collapsed controller.
+- **Giving the controller more than one child, or a plain string.** It controls exactly one overlay `Root`.
+- **Adding a `collapsed` or `variant` prop to switch between the two.** There is none — compose the provider that matches the look.
+- **Expecting a card number or CVV anywhere.** No prop, no fragment field, and no context field carries either; they exist only inside the card-entry component's own state.
+- **Styling the section with a `padding`/`gap` prop.** There is none; use swatches on the element.
+
+---
+
+## Styling
+
+`PaymentSectionRoot` and `PaymentMethodList` each render one element and forward `className`. `PaymentSectionController` renders nothing to style — style the overlay particles as their own schema elements instead. This asymmetry reaches T28's `data-fs-payment-section-placing` too: a store built on `PaymentSectionController` has every entry leaf's own `-placing` hook (each leaf renders its own element regardless of which root provides the context) but no section-level one to style, since the controller has no container of its own to carry it.
+
+| Component | What you style | Plausible classes |
+|---|---|---|
+| `PaymentSectionRoot` (root `div`) | Stacks the section's parts | `flex flex-col gap-6` |
+| `PaymentMethodList` (root `div`) | Stacks the payment options and the error | `flex flex-col gap-2` |
+| Fieldset (`data-fs-payment-method-list-fieldset`, native `<fieldset>`) | Wraps the legend and the radio rows (T38) — gives the group its visible, accessible name | usually left unstyled; a merchant border/padding choice |
+| Legend (`data-fs-fieldset-legend`, native `<legend>`) | The group's visible name, from `legend` | `text-[14px] font-medium text-[#1A1A1A]` |
+| Empty / loading picker (`data-fs-payment-method-list-state`) | Keeps the row-less container visible | `data-[fs-payment-method-list-state=empty]:min-h-12` |
+| Option row (`data-fs-radio-root`) | Each selectable option — the card option and any standalone method row alike | `flex items-center gap-3 border border-[#E0E0E0] p-3` |
+| Indicator (`data-fs-payment-method-indicator`) | The selected dot. Present on the card option too | `size-2 rounded-full bg-[#1A1A1A]` |
+| Method name (`data-fs-payment-method-name`) | The option's label — `cardLabel` on the card option, `method.name` on a standalone row | `text-[14px] text-[#1A1A1A]` |
+| Error (`data-fs-payment-method-list-error`) | Rejected-selection message | `text-[12px] text-[#B00020]` |
+| Placing, section (`data-fs-payment-section-placing`) | Present on `PaymentSectionRoot`'s own container while an order-placement sequence is in flight (T28) — presence only; this container is never made `inert` (see the warning below) | `opacity-90` |
+| Placing, method list (`data-fs-payment-method-list-placing`) | Present on `PaymentMethodList`'s own root while placing; the picker is also `inert` and `aria-disabled` at that point | `opacity-60 cursor-not-allowed` |
+
+State hooks worth styling:
+
+- `data-fs-payment-section-path="new-card"` / `="saved-card"` on the section container — present only once a path resolves, so a swatch can emphasize the active half of the section.
+- `data-fs-payment-method-list-state="loading"` / `="empty"` / `="ready"` on the picker container — always present. Give `empty` (and usually `loading`) a `min-h-*`, a border, or a placeholder: without one, a list with no rows collapses to zero height and the picker looks absent rather than empty. A store whose credit or debit group is named something other than the two defaults lands exactly here.
+- `data-checked` on each row, set by the radio particle.
+- `data-fs-payment-section-placing` — **never** style this hook with `pointer-events-none` (or any rule that blocks interaction with a descendant). `PaymentSectionRoot`'s container deliberately stays interactive while placing (T28, Decision 5) because `PlaceOrder` composes as its child: the CTA's own `role="alert"`/`role="status"` outcome regions must stay reachable so the shopper is told what is happening. Blocking pointer events at the section level would freeze the CTA too, reintroducing the exact defect the per-leaf `inert` hooks (`data-fs-payment-method-list-placing` above, and each entry leaf's own `-placing` hook) exist to avoid. Style this hook for a dimming/overlay *look* only — the actual freeze is each leaf's own `inert`.
+
+Styled example:
+
+```json
+{
+  "payment-section": {
+    "type": "PaymentSectionRoot",
+    "style": ["flex", "flex-col", "gap-6"],
+    "children": ["payment-method-list"]
+  },
+  "payment-method-list": {
+    "type": "PaymentMethodList",
+    "style": ["flex", "flex-col", "gap-2"]
+  }
+}
+```
+
+---
+
+## Accessibility Contract
+
+**What the platform promises:** `PaymentMethodList`'s radio group carries a visible, programmatic
+accessible name (`legend`, default `"Payment method"`) — a screen-reader user hears what the rows are
+a choice *between*, not just "radio button, 1 of 3." An authored empty or whitespace-only `legend`
+falls back to the default rather than shipping a nameless group. Each row keeps its own accessible name
+from the method's own display name. The group is a native `<fieldset>`/`<legend>` pair (not `aria-label`
+on a `<div>`), so it is also visible to sighted and low-vision shoppers and reachable by page-level
+translation tooling. Keyboard: the group is one Tab stop — Tab lands on the checked row, and the arrow
+keys move the checked row and change the selection. A default `:focus-visible` outline is painted from
+the platform's own stylesheet on the checked row itself — the selector is a descendant combinator, so
+it cannot match the list root or the fieldset it wraps, since neither is a focusable element.
+
+**What the platform does not promise:** colour contrast. `PaymentMethodList` (and every other payment
+component) exposes `data-fs-*` hooks so a merchant can author contrast-compliant swatches, but no
+component in this package measures or guarantees any contrast ratio — that is the merchant's theme, not
+this platform.
+
+---
+
+## Related
+
+- [[delivery-options]] — the pattern this section mirrors: one shared selection hook, a presentation variant, and a state-only controller that injects open/close into an overlay child.
+- [[session]] — the closest precedent for a reactive root that broadcasts state through a guarded context hook.

package/dist/docs/phone-field.md

@@ -30,16 +30,22 @@ The image is the source of truth for layout. If the input is the profile phone o
 
 ## Composition
 
-`PhoneField` is a single leaf particle. Internally it renders:
+`PhoneField` provides `phone-field` context and, childless, renders:
 
 ```
 PhoneField                 (data-fs-phone-field-root + data-fs-phone-field-root-country)
 ├── Field.Label            (data-fs-phone-field-label; the `label` prop)
-├── Input                  (data-fs-phone-field-input; masked <input type="tel" inputMode="numeric">)
+├── PhoneFieldInput        (data-fs-phone-field-input; masked <input type="tel" inputMode="numeric">)
 └── Field.Error            (data-fs-phone-field-error; shown when invalid)
 ```
 
-With `requirement: 'hidden'` the particle renders `null` — no DOM node is emitted.
+**Recomposable (RFC:503):** given children, `PhoneField` renders them in place of the three parts above,
+in any order. `PhoneFieldInput` is the one catalogued part that requires `phone-field` context — it reads
+the masked value, the composed ref and the particle's own `onChange`/`onBlur` from `PhoneField` itself, so
+it must sit inside it. A composed childless `Field.Label` / `Field.Error` (the generic parts from the
+`field` particle) works exactly as it does under any other bound Control; a composed generic
+`Field.Control` instead re-registers the field with react-hook-form and loses the mask — unsupported, the
+RFC's named double-binder hole.
 
 ---
 
@@ -58,8 +64,10 @@ With `requirement: 'hidden'` the particle renders `null` — no DOM node is emit
 | `error` | string | — | Host-supplied error text; overrides the internal error string when set. |
 | `errorInvalid` | string | `'Invalid phone number'` | Inline error for an invalid format. |
 | `errorRequired` | string | `'Phone number is required'` | Inline error when a mandatory field is empty. |
-| `requirement` | `'mandatory' \| 'optional' \| 'hidden'` | `'mandatory'` | `mandatory`: empty blocks; `optional`: empty allowed, format still checked when present; `hidden`: renders `null`. |
+| `requirement` | `'mandatory' \| 'optional'` | — | `mandatory`: empty blocks; `optional`: empty allowed, format still checked when present. Unset is no opinion, so a phone with no fieldset baseline is optional. It only ever raises — bound to a fieldset whose rule already says required, `'optional'` does not lower it. There is no value that suppresses the field: a store that does not want it removes the particle from the page instead (`rfc-user-identity.md` F9). |
 | `onBlur` | `() => void` | — | Fires on blur, after validation runs. |
+| `ref` | `Ref<HTMLInputElement>` | — | Lands on the masked `<input type="tel">`. Composed with react-hook-form's own ref on the bound path — a caller ref and react-hook-form's ref are both honoured. |
+| `children` | `ReactNode` | — | Given, replaces the default `Field.Label` + `PhoneFieldInput` + `Field.Error` anatomy, in any order (RFC:503). |
 
 **Validation:** the number is checked on blur/submit only — never per keystroke. A prior error clears while the shopper edits and is re-evaluated on the next blur. Changing `country` resets the local validation state.
 
@@ -70,6 +78,46 @@ With `requirement: 'hidden'` the particle renders `null` — no DOM node is emit
 
 ---
 
+## Bound behaviour
+
+`PhoneField` reads the field contract through `useField()` and binds through `useController` when both a
+field contract (`FieldBinding`) and a react-hook-form `FormProvider` are present above it; otherwise it
+runs the plain, unbound behaviour documented above, unaltered.
+
+- **What the contract supplies**: `label` and `placeholder`, when the particle's own prop is omitted
+  (an explicit prop always wins); `defaultValue`, seeded into `useController`; and `rule`, merged with the
+  particle's own format validator (below).
+- **What stays the particle's**: the US/BR mask, `country`, `requirement`, and the format/required error
+  copy (`errorInvalid`/`errorRequired`).
+- **Value shape stored in react-hook-form**: the same **unmasked** string the unbound particle emits
+  through `onValueChange` — not the masked display value. A fieldset's `toPayload` reads exactly what a
+  non-form caller reads today; E.164 normalisation for persistence is a separate step (`toE164`), not
+  applied here.
+- **Validation**: the composite composes its own format check (using `errorInvalid`) alongside whatever
+  the contract's `rule` validates, never instead of it. Requiredness is not decided here: the particle
+  passes `requirement === 'mandatory'` as a raise, and `useBoundField` resolves it against the contract's
+  own `rule.required`, carrying `errorRequired` as the copy when the raise is what makes the field
+  required. A contract that omits `required` still behaves as the unbound particle does.
+- **Focus**: the `ref` lands on the masked `<input type="tel">`, so a failed submit moves focus to it.
+- **Explicit `invalid`/`error` props still win** over react-hook-form's own error state — a host-forced
+  error renders even when react-hook-form holds none for the name. This is unconditional on the default
+  (childless) anatomy, which renders the raw Base UI `Field.Label`/`Field.Error` primitives directly
+  rather than this package's own bound-aware `Field.*` wrapper, so it never gates on react-hook-form's
+  own error state the way a composed childless `Field.Error` intentionally does (below).
+- `PhoneFieldDefinition` gains no `requiresContext` — the particle stays placeable outside any form. It
+  does declare `providesContext: 'phone-field'` — that is what makes `PhoneFieldInput` a legal child.
+- **Recomposition (RFC:503):** when bound, `PhoneField` re-provides the field contract with the
+  *resolved* `name`/`label`/`placeholder` (the values above, after the particle's own prop/contract
+  fallback chain) so a composed childless `Field.Label` renders real text and a composed childless
+  `Field.Error` renders react-hook-form's real message for the field, instead of the empty contract an
+  earlier design (`FieldContractBoundary`) used to push. `useController` above remains the sole binder for
+  the name either way — the re-provided contract is read-only-safe, not a second registration.
+- **Focus stays composed-safe:** the composed ref threads through to `PhoneFieldInput` regardless of
+  where the author places it, so focus-on-failed-submit lands on the masked input in a recomposed anatomy
+  too, not only the default one.
+
+---
+
 ## Accessibility
 
 The label is associated with the input and the error is linked via `aria-describedby` automatically by the Base UI `Field` primitive (WCAG 2.1 AA). The input uses `type="tel"` and `inputMode="numeric"` for a numeric mobile keypad. Validation never blocks typing.
@@ -88,6 +136,12 @@ The label is associated with the input and the error is linked via `aria-describ
 | `data-fs-phone-field-input` | The input box; use `data-invalid:` for the error border. |
 | `data-fs-phone-field-error` | The inline error text (small, red). |
 
+`data-fs-phone-field-input` stays on `PhoneFieldInput` in both the default and a recomposed anatomy — it
+is the one catalogued part, so there is exactly one place that hook lives. A recomposed anatomy's
+author-supplied `Field.Label` / `Field.Error` (the generic parts, not the default branch's own) carry
+only `data-fs-field-label` / `data-fs-field-error`, not the phone-specific hooks above — a documented
+trade of Decision 4; widen store CSS keyed on the specific hooks if it must also match a recomposed page.
+
 ---
 
 ## Common mistakes