@vtex/faststore 0.0.4 → 0.0.6

package/dist/docs/billing-address.md

@@ -0,0 +1,284 @@
+# BillingAddress
+
+**Category:** commerce
+**Purpose:** Lets a shopper confirm their billing address matches delivery (the default) or provide a different, country-specific billing address for their card. Persists the choice via a dedicated action; publishes only a differs/does-not-differ flag onto the shared payment state, never the address itself.
+
+---
+
+## Visual cues (how to identify in an image)
+
+Use these signals to detect that a BillingAddress block is present. Position on the page is irrelevant
+for detection — it can appear anywhere inside a payment section. The image is the source of truth for
+layout.
+
+A BillingAddress block contains any combination of:
+
+- A short **disclaimer sentence above the checkbox**, stating the billing address must match the one
+  on the card or bank statement or the bank may decline the order. It renders by default
+  (`billingMatchNoticeVisible: true`) — treat it as part of this block, not a separate `Text` element,
+  even when the image shows it as the first line in the region.
+- A single **checkbox with a label reading something like "Billing address same as delivery address"**,
+  sitting inside (or directly beside) a credit-card entry form.
+- When shown **checked** in the image: nothing renders below it — no address and no inputs.
+- When shown **unchecked** in the image: a **full address form** appears below it — a country
+  dropdown, then a variable set of text fields (street, number, complement, neighborhood/bairro, city,
+  state, postal code — the exact set varies by the selected country), plus a save/submit button
+  distinct from the page's main "Place order" button.
+- This block always sits **inside a checkout payment section**, near card-number fields, a saved-cards
+  list, or a save-card checkbox — never on a product page, cart page, or the delivery/shipping address
+  step itself (that is a separate, visually similar but distinct block — see When NOT to use).
+
+If the image shows a same-as-delivery-style toggle specifically inside the **payment**/card area with a
+country-adaptive address form gated behind it, use `BillingAddress`. If the toggle or form instead
+governs the **delivery** address (usually appears earlier in the checkout flow, before payment, and
+often includes a saved-addresses list or a "use this saved address" picker), that is
+`ShippingAddress`, not this component.
+
+---
+
+## When to use
+
+- Inside a checkout's payment section, as a sibling of the card-entry fields, the saved-cards list,
+  the installment selector, and the save-card control, so a shopper can confirm or override the
+  billing address used for their card.
+
+## When NOT to use
+
+- The delivery/shipping address step, including its own saved-address list and country form → use
+  `ShippingAddress` instead. That component owns the address the order ships to; `BillingAddress` never
+  writes to it and never reads its saved-addresses list.
+- A general "same address for everything" single toggle spanning both shipping and billing in one
+  control → not supported. `BillingAddress` is its own independent toggle scoped to billing only.
+- Collecting the shopper's name/document for the card itself → use `CardEntry` (holder name) or
+  `CardholderDocument` (tax document). `BillingAddress` never renders those fields.
+- Anywhere outside a payment section → `BillingAddress` requires a `PaymentSectionRoot`/
+  `PaymentSectionController` ancestor (it reads the selected method's validator and the shared payment
+  draft). Placing it without one is a build/runtime error, not a silent no-op.
+
+---
+
+## Composition
+
+`BillingAddress` is a single leaf — no root, no required children, no sub-components:
+
+```
+PaymentSectionRoot (or PaymentSectionController)
+├── CardEntry             (sibling — new-card fields)
+├── SavedCards             (sibling — saved-card picker)
+├── Installments            (sibling — installment selector)
+├── SaveCard                 (sibling — save-this-card toggle)
+├── BillingAddress             (sibling — this component)
+└── PlaceOrder                  (sibling — the submit CTA)
+```
+
+Place it as a **sibling** of `CardEntry`, `SavedCards`, `Installments`, `SaveCard`, and `PlaceOrder`,
+never nested inside any of them — the same convention `Installments`/`SaveCard` already follow. It
+does not require a `SessionRoot` — unlike `SaveCard`, billing address applies to guest and
+authenticated shoppers alike.
+
+It renders nothing while the card payment is collapsed — the persisted selection is a method that is
+not a card, or one the section does not serve, and a composed `PaymentMethodList` can bring the card
+form back (see [[payment]]). It stays mounted, so an open form keeps what the shopper typed for when the
+card comes back, and while collapsed it publishes no unsaved address: Place Order is never refused over
+a form the shopper cannot see.
+
+---
+
+## Components
+
+### BillingAddress
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| `sameAsDeliveryLabel` | string | `"Billing address same as delivery address"` | The toggle's own label text. |
+| `defaultCountry` | string | `"BRA"` | Initial country selected when the custom form first mounts. |
+| `countryLabel` | string | `"Country"` | Label for the country selector inside the custom form. |
+| `recipientNameLabel` | string | `"Recipient's name"` | Label for the recipient-name descriptor field. Not rendered by the custom-address form today — the write contract has no matching input slot — kept for parity with the other seven field labels. |
+| `streetLabel` | string | `"Street"` | Label for the street descriptor field. |
+| `numberLabel` | string | `"Number"` | Label for the street-number descriptor field. |
+| `complementLabel` | string | `"Complement (optional)"` | Label for the complement descriptor field. Its "(optional)" suffix is the only signal that the field is not required — the actual `required` attribute is driven independently, so authoring this without the suffix loses the visual cue, not the behavior. |
+| `neighborhoodLabel` | string | `"Neighborhood"` | Label for the neighborhood descriptor field. Unused when the active country's descriptor has no `neighborhood` field (e.g. USA). |
+| `cityLabel` | string | `"City"` | Label for the city descriptor field. |
+| `stateLabel` | string | `"State"` | Label for the state descriptor field. |
+| `postalCodeLabel` | string | `"Postal code"` | Label for the postal-code descriptor field. |
+| `submitLabel` | string | `"Save billing address"` | Label for the button that persists a custom address. |
+| `submitPendingLabel` | string | `"Saving..."` | Submit button's label while the write is in flight. |
+| `requiredNoticeLabel` | string | `"This payment method requires a billing address."` | Shown when the selected method's validator marks a billing address required. |
+| `unsavedAddressNoticeLabel` | string | `"No billing address has been saved yet — the delivery address will be used unless you save one below."` | Shown, `role="status"`, while the custom-address form is open and no address has been persisted yet. |
+| `billingMatchNoticeLabel` | string | `"Your billing address must match the one on your card or bank statement, or your bank may decline the order."` | Always-on billing-match disclaimer. Gated only by this prop and `billingMatchNoticeVisible` — unlike the two notices above, it never changes with the toggle, the form, `billingAddressRequired`, or a saved address. |
+| `billingMatchNoticeVisible` | boolean | `true` | Switches the billing-match disclaimer above on or off. A blank `billingMatchNoticeLabel` also renders nothing, even while this is `true` — the two rules never combine into an empty element. |
+| `fieldRequiredMessage` | string | `"This field is required."` | Shown as an inline field error under a required, blank address field once it has been touched (T38) — see Accessibility Contract below. One prop, not one per field: every rendered field but `complement` shares the same rule. An authored empty or whitespace-only string falls back to this default. |
+| `disabled` | boolean | `false` | Disables the toggle, every form field, the country selector, and the submit button. |
+
+**Data:** declares no fragment and no `fetchStrategy`, so it fetches no shopper data. It reads only the
+payment context (`requiresContext: 'payment'`): the selected method's validator and the shared payment
+draft. **Nothing prefills the custom-address form** — there is no server field that echoes back an
+already-persisted billing address, so the custom form always starts blank.
+
+**The toggle defaults to checked** (same as delivery) and stays that way until the shopper
+un-checks it. Un-checking reveals a blank, country-specific form, as this component's own local UI
+state — nothing is sent to the server until the shopper fills it in and clicks the submit button.
+**Re-checking the toggle only tells the server to fall back to the delivery address if a custom address
+was actually saved before** (`draft.billingAddressDifferent === true`); otherwise re-checking is a local
+no-op — there is nothing on the server to revert. This is deliberate: the published fact this component
+shares with the rest of the payment section only ever claims "different" once an address has actually
+been persisted, never merely because the shopper opened the form.
+
+**⚠ While the form is open and nothing has been saved yet, an inline `role="status"` notice
+(`unsavedAddressNoticeLabel`) warns that the delivery address will be used unless an address is saved.**
+This notice itself is advisory only, not a submit gate: a shopper can still fill the whole form without
+ever pressing this component's own submit button, and the native `required` attribute on the form's own
+fields does not prevent that either — there is no `<form>` element anywhere in this component, so
+`required` is real for assistive technology but not wired to anything that blocks a click on a
+different button in a different component. Since T38 each rendered field (all but `complement`) does
+announce its own validity once touched — see Accessibility Contract below — but that announcement is
+driven by a local blur-tracked state, never by `required`'s own native validity, and it still does not
+gate the submit control; the submit gate is `isBillingAddressFormValid`, read at the submit button's
+own `disabled`.
+
+**The hard block itself lives elsewhere.** This component also publishes the exact same fact the notice
+renders from onto the shared payment draft (`billingAddressUnsaved`), and T24's submit gate
+(`usePaymentSubmitGate()`, consumed by `PlaceOrder`) refuses placement client-side while that fact is
+true — so a shopper who declines "same as delivery" and never saves an address cannot place the order,
+even without ever touching this component's own submit button. Neither `required` nor the notice does
+the blocking themselves; both stay exactly as advisory as described above.
+
+**A third notice, `billingMatchNoticeLabel`, is configuration-driven, not state-driven like the two
+above.** The required-note and the unsaved-notice each appear and disappear by runtime state (the
+selected method's validator; the form being open with nothing saved yet). This one does not: its
+presence is a pure function of `billingMatchNoticeLabel` and `billingMatchNoticeVisible` alone, and it
+renders before the toggle field on every render — including the default state, where "same as delivery"
+stays checked and the shopper never opens the form. It never reacts to the toggle, to
+`billingAddressRequired`, to a saved address, or to order placement; a merchant switches it off with
+`billingMatchNoticeVisible: false`, never by anything happening at runtime. It carries its own hook,
+`data-fs-billing-address-match-notice`, and renders as a plain paragraph with no ARIA role — it is a
+static disclaimer, not a live region reacting to an event.
+
+**Country adaptivity is entirely data-driven**, reusing the same country descriptors the delivery
+address step uses: Brazil shows a neighborhood/bairro field, the United States does not, and adding a
+new country anywhere in this codebase is a data-only change that this component picks up automatically
+— never a code change here.
+
+---
+
+## Canonical schema example
+
+```json
+{
+  "payment-section": {
+    "type": "PaymentSectionRoot",
+    "children": ["card-entry", "saved-cards", "installments", "save-card", "billing-address", "place-order"]
+  },
+  "billing-address": {
+    "type": "BillingAddress",
+    "props": { "sameAsDeliveryLabel": "Billing address same as delivery address" },
+    "style": ["flex", "flex-col", "gap-3"]
+  }
+}
+```
+
+---
+
+## Common mistakes
+
+- **Inventing `BillingAddressToggle` or `SameAsDeliveryControl`.** The component is `BillingAddress`.
+- **Nesting `BillingAddress` inside `ShippingAddress`, `CardEntry`, or `SavedCards`.** It must be a
+  sibling of all of them under the same `PaymentSectionRoot`, exactly like `Installments`/`SaveCard`.
+- **Expecting the custom form to pre-fill from the delivery address.** It always starts blank — there
+  is no read model that echoes a previously persisted billing address (see the `.tsx` doc comment,
+  Decision 3, for the measured reason).
+- **Expecting the toggle to dispatch on every keystroke.** It dispatches at, at most, two points: the
+  toggle's transition back to "same as delivery" (only when an address was actually saved — otherwise
+  it's a local no-op), and the custom form's explicit submit button — never per field edit.
+- **Reaching for a `recipientName` field in the custom form.** Deliberately absent — the billing-address
+  write action has no such field, unlike the delivery address's own form.
+- **Requiring a `SessionRoot` ancestor.** Not needed — unlike `SaveCard`, this component has no
+  authentication gate.
+- **Assuming the `required` attribute or the unsaved-address notice itself blocks Place Order.** Neither
+  does — there is no `<form>` in this component and no submission gate wired to either directly. Place
+  Order *is* refused while the notice's exact condition holds, but that block runs in T24's submit gate
+  (`usePaymentSubmitGate()`, consumed by `PlaceOrder`), which reads the fact this component publishes
+  (`billingAddressUnsaved`) rather than either of those two elements.
+- **Rendering more than one `BillingAddress` under the same `PaymentSectionRoot`/`PaymentSectionController`.**
+  Not forbidden mechanically. Every instance re-syncs its own toggle state whenever the one shared
+  draft's `billingAddressDifferent` changes, so all instances converge once any of them actually persists
+  or reverts an address — but a purely local transition (unchecking, or re-checking with nothing yet
+  persisted) never touches the draft, so two instances can briefly disagree on-screen without
+  misinforming the gateway (nothing is sent to the server until a submit succeeds either way). The
+  submit gate's own fact (`billingAddressUnsaved`) is tracked per instance internally (each instance's
+  own `useId()`), specifically so one instance unmounting — an accordion collapsing, a tab switching, a
+  responsive layout branch — never clears a *second*, still-open, still-unsaved instance's own block
+  (fix pass, findings R2/S2). Nothing in this codebase composes it that way regardless — treat it as a
+  single, sibling-placed leaf per payment section, matching every other sibling in the Composition
+  diagram above.
+
+---
+
+## Styling
+
+Single DOM root wrapping the toggle field, an always-mounted panel that holds the country-specific form
+while the box is unchecked, and an optional inline error.
+
+| Component | What you style | Plausible classes |
+|---|---|---|
+| `BillingAddress` (root `div`) | Stacks the toggle, the panel, and the error | `flex flex-col gap-[12px]` |
+| Same as delivery (`data-fs-billing-address-same-as-delivery`) | Present on the root while the box is checked, absent while it is unchecked. It sits on the node the style array styles, so target it as `data-[fs-billing-address-same-as-delivery]:…`, never with a descendant variant | `data-[fs-billing-address-same-as-delivery]:gap-[8px]` |
+| Panel (`data-fs-billing-address-panel`) | Always present, right after the toggle field, and the toggle's `aria-controls` target. `hidden` and empty while the box is checked; holds the custom-form wrapper while unchecked. Never give it a display utility (`flex`, `grid`, `block`, …): one defeats `hidden` | none — style the form inside it |
+| Custom-form wrapper (`data-fs-billing-address-form`), inside the panel | Field grid | `grid grid-cols-2 gap-[8px]` |
+| Required-billing-address note (`data-fs-billing-address-required-note`) | De-emphasized helper text | `text-[12px] text-[#666666]` |
+| Unsaved-address notice (`data-fs-billing-address-unsaved-notice`) | De-emphasized, non-error helper text | `text-[12px] text-[#666666]` |
+| Billing-match disclaimer (`data-fs-billing-address-match-notice`) | De-emphasized helper text, first child of the root | `text-[12px] text-[#666666]` |
+| Field error (`data-fs-field-error`) | Per-field validation message, shown once a required field is touched and left blank (T38) | `text-[12px] font-medium text-[#B00020]` |
+| Inline error (`data-fs-billing-address-error`) | Warning-toned alert text | `text-[12px] font-medium text-[#B00020]` |
+| Placing (`data-fs-billing-address-placing`) | Present while an order-placement sequence is in flight (T28) — distinct from `data-fs-billing-address-pending`, which this component already emits for its own local submit dispatch; the root is also `inert` and `aria-disabled` while placing | `opacity-60 cursor-not-allowed` |
+
+Styled example:
+
+```json
+{
+  "billing-address": {
+    "type": "BillingAddress",
+    "style": ["flex", "flex-col", "gap-3"]
+  }
+}
+```
+
+There is no per-field styling hook beyond the particles' own `data-fs-checkbox-*` / `data-fs-field-*` /
+`data-fs-select-*` attributes — style the checked state via Base UI's own `data-checked` on
+`Checkbox.Root`, per the `style-components` skill.
+
+---
+
+## Accessibility Contract
+
+**What the platform promises:** every rendered custom-address field (all but `complement`) announces
+its own validity once the shopper has touched it — focus, type nothing, and blur a required field, and
+it carries `aria-invalid="true"` plus an error message (`fieldRequiredMessage`) associated through
+`aria-describedby`; nothing is marked invalid before it is touched, and `complement` — the one optional
+field — is never marked invalid. This mirrors `CardEntry`'s own field-level validity mechanism exactly.
+Each field also carries its own `Field.Label`, authorable per field. A default `:focus-visible` outline
+is painted from the platform's own stylesheet on every field in this component.
+
+The "same as delivery" toggle references the panel below it through `aria-controls` in both states. The
+panel is always mounted, so the reference never dangles: it is `hidden` and empty while the box is
+checked, and it holds the custom-address form while the box is unchecked.
+
+**What the platform does not promise:** colour contrast. `BillingAddress` (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
+
+- [[shipping-address]] — the delivery-address step this component's own country descriptors are
+  imported from; a separate composition entirely, never a parent or child of `BillingAddress`.
+- [[save-card]] — the closest structural sibling authored the same way: a single leaf requiring
+  `PaymentSectionRoot`, action-dispatch-with-pending-state. Unlike this component, it also declares its
+  own fragment.
+- [[cardholder-document]] — the closest sibling for reading a per-method validator flag
+  (`documentRequired`/`documentDisplayable`) the same way this component reads
+  `billingAddressRequired`.
+- [[installments]] — another single-leaf sibling requiring only `PaymentSectionRoot`, no Root/leaf
+  split, sibling placement under the same section.

package/dist/docs/buy-button.md

@@ -35,7 +35,7 @@ BuyButtonRoot
 └── BuyButtonButton
 ```
 
-`BuyButtonButton` dispatches the cart `addItem` action through the compiler-injected `$actions.cart.addItem` prop. The add-to-cart write is **context-free** — it reads and writes the Apollo cache directly — so `BuyButton` needs **no `CartRoot` ancestor** (specs/actions.md, ADR-0010). Drop it on a PDP, a product card, a shelf, or the header alike.
+`BuyButtonButton` dispatches the cart `addItem` action through the compiler-injected `$actions.cart.addItem` prop. The add-to-cart write is **context-free** — it reads and writes the Apollo cache directly — so `BuyButton` needs **no `CartRoot` ancestor** (docs/storefront-core/reference-free-particle-model.md § Write side — actions, ADR-0010). Drop it on a PDP, a product card, a shelf, or the header alike.
 
 Child order reflects visual order.
 

package/dist/docs/card-entry.md

@@ -0,0 +1,250 @@
+# CardEntry
+
+**Category:** commerce
+**Purpose:** New-card entry for checkout payment: a masked card number with live network detection, holder name, expiration, and CVV. Masks, presence, and required-ness are driven by the selected payment method's server-side validator config, never hardcoded. Owns and answers the new-card submission itself — it never hands the card number or CVV to any other component.
+
+---
+
+## Visual cues (how to identify in an image)
+
+Use these signals to detect that a card-entry block is present. Position on the page is irrelevant for detection. The image is the source of truth for layout.
+
+A card-entry block contains any combination of:
+
+- A **card number input**, often showing a placeholder like `0000 0000 0000 0000` and grouped in blocks of four digits.
+- A **single recognized-network mark** (Visa, Mastercard, Amex, Elo, Diners, …) sitting **inside** the number field's own box, usually at its trailing edge. It is absent until the typed digits identify exactly one network, and there is never more than one at a time — this is "the network I just typed", not "the networks this store accepts". A network whose name has no mapped icon shows its name as text in the same slot. For "every method this store accepts", shown before anything is typed, the component is `AcceptedPaymentMethodBadges`, not this one.
+- A **cardholder name input**, usually labeled "Nome no cartão" / "Name on card".
+- An **expiration input**, labeled "Validade" / "Expiry", showing `MM/AA` or `MM/YY`.
+- A **CVV / security-code input**, labeled "CVV" / "Código de segurança", usually 3–4 digits, often placed beside the expiration field, usually with a short helper line underneath it explaining where to find the code. Its digits render **obscured** (dots), same visual family as a password field, even though it is not one under the hood (see Composition for why).
+- The four fields are **grouped visually** (a bordered fieldset, a card-shaped panel, or simple vertical/grid stacking) as one unit, distinct from the payment-method picker above it and the installment selector below it.
+
+If the image shows a checkout payment step with these four fields together, use `CardEntry`. If it shows only a masked recap like *"Visa •••• 4242"* with no editable inputs, that is a read-only summary, not this component.
+
+---
+
+## When to use
+
+- The "enter a new card" step of a credit-card checkout payment section.
+- Anywhere a shopper types a fresh card's number, holder name, expiration, and CVV.
+
+## When NOT to use
+
+- A read-only recap of an already-selected card (*"Visa •••• 4242"*) → use a payment summary component; this component always renders editable inputs.
+- Re-entering only the CVV for a previously saved card → a distinct saved-cards component; do not reuse `CardEntry` for that flow.
+- The cardholder's tax document (CPF, etc.) → a separate document field, not part of this component.
+- Choosing an installment plan → a separate installments component.
+- The "save this card" toggle → a separate save-card control.
+- A billing address form → a separate billing-address component.
+- The "place order" button → a separate CTA component; `CardEntry` never renders a submit button.
+
+---
+
+## Composition
+
+`CardEntry` is a single self-contained leaf — it has no sub-component family. It must be placed inside a provider of the `card-capture` context, which hands it the accepted networks and decides where the card goes. At checkout that provider is the payment section root (`PaymentSectionRoot` or `PaymentSectionController`), which also feeds it the current selection and sends the card through `sendPayments`. The account's add-card root will provide the same context with its own target.
+
+```
+PaymentSectionRoot                  (or PaymentSectionController)
+├── PaymentMethodList                (optional; picks a method by hand)
+├── CardEntry                        (this component — always a direct or nested child, never a root)
+├── … other payment leaves (installments, save-card, billing, place-order)
+```
+
+`CardEntry` renders its own four fields internally (number, holder name, expiration, CVV) — none of them are separately placeable schema elements. Holder name, expiration, and CVV each render conditionally, based on the detected payment method's validator config; the number field always renders. The CVV field is `type="text"`, same as the others, but carries an inline `-webkit-text-security: disc` style that renders its digits as dots — from the keystroke that completes the code, not from the first one. "Complete" is the detected method's own `cvvMask` length: three digits for most networks, four for Amex. Where that mask is pipe-delimited — one method id covering a 3-and-4-digit family — it is the *shortest* alternative, not the longest the field accepts: a shopper holding the 3-digit card of such a family never reaches a fourth digit, so the longer length would leave their complete, valid code legible for the rest of the flow. Below it the digits render in the clear, so a shopper can read back what they just typed and catch a typo; at it, the mask engages on that same render, never on blur and never after a delay, so a paste that delivers every digit in one event opens no legible window. The mask is derived from the value on every render rather than latched once, so backspacing below the length reveals what is left, and a network switch that widens the expectation (a 3-digit code against a newly detected Amex) reveals the code again until its fourth digit. `type="password"` was tried first and reverted: a real Chrome browser offered to save the security code to its password manager (synced to the signed-in account) the instant the field carried that type — pairing the expiration field as a fake "username" — which PCI-DSS forbids for a value that must not be retained past authorization. The CSS property obscures the digits without tripping that heuristic, since it never touches `type`. It is supported in Chromium and WebKit (and, per T70's spec, Firefox 114+ — unverified on this branch); an engine without it renders the digits in the clear, exactly what shipped before this mechanism existed — not a regression. The declaration is an inline style, which outranks a class-based rule from a compound swatch at normal importance — but not one that reaches for Tailwind's `!` important modifier: swatch tokens reach `className` verbatim with no validation, so a store that authors an arbitrary-property utility ending in `!` can still unmask the field. Nothing in this package closes that hole; it is accepted rather than fixed (masking spec, OQ-1). A helper line (`cvvDescription`) renders under the field by default, telling the shopper where to find the code; an empty string suppresses it (see Components below).
+
+**Composition rules:**
+
+- Must be a descendant of a `card-capture` provider — `PaymentSectionRoot` or `PaymentSectionController` at checkout. Placed anywhere else, it throws at render time.
+- Never nest another `CardEntry` inside it.
+- Does not require `PaymentMethodList` as a sibling — network detection resolves the method on its own from the typed number.
+
+---
+
+## Reveal and collapse
+
+`CardEntry` reads the section's card-payment collapse and hides itself — never unmounts — while it holds (T191): a method is persisted that this section does not serve (a selection outside the section's configured `group`) **or** that is not a card (in neither card group, with no card-number pattern — e.g. Promissory or Customer Credit admitted through `group`), card mode is not holding the form open, **and** a `PaymentMethodList` composed under the same root can bring the form back (fix pass, finding R2). The last condition matters: collapsing only when something else on the page can un-hide the form. A composition with no picker at all — e.g. `SavedCards` + `CardEntry` — has no such escape hatch once collapsed, since typing a new card number is the one thing a hidden, inert form cannot do. In that composition the form stays visible instead, and typing a new number is itself the way back. A composed picker can always bring the form back when it renders the card option: it dispatches the method its candidate rule names (the sole in-scope method, else the sole credit-group one), and when it names none — a store with Visa and Mastercard — it puts the section in card mode instead, which reveals the form without sending anything. Without a card option, only a row bound to a card method can bring it back. Collapsed, the styled root carries `inert` and `data-fs-card-entry-collapsed=""`; the actual hide is a `hidden` attribute one level up, on a plain wrapper this component never assigns a `className` to (see Styling below) — out of the accessibility tree and out of the tab order, not merely visually hidden. It stays visible whenever nothing is persisted at all — the shopper still needs to be able to type a number for this component's own network detection to produce a selection in the first place.
+
+When card mode is what brings the form back, a card number already in the field is sent again, once — `{ methodId, bin }` for its detected network, with its eight-digit BIN — so the selection follows the card the shopper sees without a retype. With fewer than eight digits nothing is sent until the eighth. When the form comes back because a method was dispatched instead (the card option's candidate, or a card row), the next keystroke re-sends the card, as before.
+
+While collapsed, `CardEntry` still answers a place-order attempt: it keeps its submission registration and refuses immediately with a client-synthesized `CARD_ENTRY_COLLAPSED` code, silently — no field error, no focus move, since there is no visible field to point at. A visible form refuses the same way, once its card is valid, while the persisted selection is a method this section does not serve or one that is not a card — in card mode before the card's own selection reaches the order form, or with no picker composed — and an incomplete card still gets its field errors and focus first. It refuses the same way while the persisted selection is a card of another network than the one detected from the typed number: the card's own selection was refused or failed, or the card option or a row picked another network after the card was typed. The next edit of the number sends the card's own selection again. So a card the shopper already typed is never posted for a method the section is not on, nor under another network's method, in any composition. The collapsed fieldset is also natively `disabled`, so a store that ever wraps these fields in a real `<form>` does not get them serialized from a form the shopper cannot see (fix pass, finding S-F6) — this is separate from the authored `disabled` prop below and carries no styling hook of its own.
+
+Collapsing clears the security code field, and only the security code. The card number, holder name, and expiration survive, so a shopper who switches method and switches back finds what they typed — no credit-card component in this package retains a security code across a visibility change.
+
+The authored `disabled` prop is independent of this: a store that freezes the form with `disabled` sees no change, and a collapsed form may also be `disabled` — neither implies the other.
+
+---
+
+## Store setup: network icon declaration
+
+`CardEntry` renders the detected card network's icon at runtime, once the typed number matches a configured payment method's `validator.numberRegex` — the icon name is computed in component code, not read from a schema prop, so the compiler's prop-type-driven icon collection never sees it.
+
+**Any store composing `CardEntry` (or `SavedCards` / `SavedCardOption`) must declare the five network icon names in `global.icons.include`:**
+
+```json
+{
+  "icons": {
+    "include": ["amex", "diners", "elo-card", "mastercard", "visa"]
+  }
+}
+```
+
+**If the store's `global.json` already has an `icons` object, extend it — do not replace it.** A store that already sets `"collection"` (or `"aliases"` / `"collections"`) must keep that key alongside the new `include`:
+
+```json
+{
+  "icons": {
+    "collection": "ph",
+    "include": ["amex", "diners", "elo-card", "mastercard", "visa"]
+  }
+}
+```
+
+Copying the first snippet verbatim over an existing `icons` object silently drops `collection`, and every other icon in that store re-resolves through the fallback default instead — with no build error and no console error to flag it.
+
+Omitting `include` entirely is silent too. The network icon renders as an empty 24×24 box instead of the card mark.
+
+---
+
+## Components
+
+### CardEntry
+
+The only component. No internal sub-parts are separately schema-addressable.
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| `legend` | string | `"Card details"` | Fieldset legend/title. |
+| `numberLabel` | string | `"Card number"` | Card-number field label. |
+| `numberPlaceholder` | string | — | Card-number field placeholder. |
+| `holderNameLabel` | string | `"Cardholder name"` | Holder-name field label. Same noun as `holderNameRequiredMessage`, deliberately. |
+| `holderNamePlaceholder` | string | — | Holder-name field placeholder. |
+| `expirationLabel` | string | `"Expiration date"` | Expiration field label. |
+| `expirationPlaceholder` | string | `"MM/YY"` | Expiration field placeholder. |
+| `cvvLabel` | string | `"Security code"` | CVV field label. |
+| `cvvPlaceholder` | string | — | CVV field placeholder. |
+| `cvvDescription` | string | `"The 3-4 digit number on your card"` | Helper text under the CVV field. Empty string renders nothing. |
+| `numberRequiredMessage` | string | `"Card number is required"` | Shown when the card-number field is left blank. |
+| `numberInvalidMessage` | string | `"Enter a valid card number"` | Shown for a Luhn-invalid number, or one that matches no configured method — the same string covers both. |
+| `holderNameRequiredMessage` | string | `"Cardholder name is required"` | Shown when the holder-name field is left blank and the detected method requires it. |
+| `expirationRequiredMessage` | string | `"Expiration date is required"` | Shown when the expiration field is left blank and the detected method requires it. |
+| `expirationInvalidMessage` | string | `"Enter a valid expiration date"` | Shown for a structurally malformed `MM/YY`. |
+| `expirationExpiredMessage` | string | `"This card has expired"` | Shown for a structurally valid `MM/YY` that has already passed. |
+| `cvvRequiredMessage` | string | `"Security code is required"` | Shown when the CVV field is left blank and the detected method requires it. |
+| `cvvInvalidMessage` | string | `"Enter a valid security code"` | Shown for a CVV that fails the detected method's format. |
+| `disabled` | boolean | `false` | Disables every field. |
+
+**Data:** declares no fragment and no actions. Card masks, required-ness, and network regexes come from the `card-capture` context — at checkout, the payment section's own methods. It reads no cart, so it works where no purchase is underway; the `add_payment_info` event and the cart total it needs belong to the payment section root.
+
+**Never a schema prop:** the card number and CVV. They exist only in this component's local state, for the lifetime of the mounted instance, and are never exposed as a bindable prop, a fragment field, or a value another component can read.
+
+**Validation timing:** the draft is validated before the place-order sequence opens a transaction, not only when the order is submitted — an invalid number, holder name, expiration, or CVV refuses with an inline field message before anything is charged or opened. The submission itself re-validates the same way, so the two can never disagree.
+
+**Selection timing:** network detection, the network mark, and the number's grouping follow every keystroke, but the detected method and the card's BIN (its first eight digits) reach the server only once the number field holds eight digits — never as a shorter prefix. Below eight digits nothing is sent, so the installments control and the persisted selection keep whatever was last recorded. The first digit typed off the new-card path does record that path, locally and with nothing sent, so a saved card that was checked stops being the selection as soon as the shopper starts a new number.
+
+---
+
+## Canonical schema example
+
+```json
+{
+  "payment-section": {
+    "type": "PaymentSectionRoot",
+    "props": { "group": "creditCardPaymentGroup" },
+    "children": ["method-list", "card-entry"]
+  },
+  "method-list": { "type": "PaymentMethodList" },
+  "card-entry": {
+    "type": "CardEntry",
+    "props": {
+      "legend": "Card details",
+      "numberLabel": "Card number",
+      "holderNameLabel": "Cardholder name",
+      "expirationLabel": "Expiration date",
+      "cvvLabel": "Security code"
+    }
+  }
+}
+```
+
+### Minimal variant (defaults only)
+
+```json
+{
+  "payment-section": {
+    "type": "PaymentSectionRoot",
+    "children": ["card-entry"]
+  },
+  "card-entry": { "type": "CardEntry" }
+}
+```
+
+---
+
+## Common mistakes
+
+- **Inventing `CreditCardForm` or `CardForm`.** The component is `CardEntry`.
+- **Splitting the four fields into separate schema elements** (`CardNumberField`, `CardCvvField`, …). They do not exist as separate components — `CardEntry` renders all four fields itself as one unit.
+- **Passing `cardNumber` or `cvv` as props.** `CardEntry` reads no such prop; the card number and CVV live only in its own local state, never bound from the schema.
+- **Placing `CardEntry` outside a `card-capture` provider** (`PaymentSectionRoot` / `PaymentSectionController` at checkout). It requires that context and throws otherwise.
+- **Adding a submit/place-order button inside `CardEntry`.** Placing the order is a separate CTA component; `CardEntry` never renders one.
+- **Reusing `CardEntry` for a saved card's CVV-only re-entry.** That is a distinct component; `CardEntry` always shows all four new-card fields.
+- **Expecting a `network` or `cardType` prop.** The network is detected automatically from the typed number against the payment section's configured methods — there is no prop to preset it.
+
+---
+
+## Styling
+
+Style `CardEntry`'s root as a vertical stack of fields, matching a typical card form. The recognized-network mark belongs **inside** the number input's own box rather than beside it: make the number field's wrapper the positioning context, take the mark out of flow at the input's trailing edge, and pad the input on that side so the digits never run underneath it. The wrapper is a plain ancestor of both the `<input>` and the mark, so this is a pure CSS arrangement — the field particle exposes no adornment slot.
+
+| Component | What you style | Plausible classes |
+|---|---|---|
+| `CardEntry` root | Stacks the four fields | `flex flex-col gap-[16px] w-full` |
+| Number field wrapper (`data-fs-card-entry-number-control`) | The positioning context the mark is placed against; also holds the `<input>` | `relative` |
+| Network mark slot (`data-fs-card-entry-networks`) | Positions the single mark inside the input's box; absent entirely until a network is recognized | `absolute right-[12px] top-1/2 -translate-y-1/2 flex items-center` |
+| Network mark (`data-fs-card-entry-network`) | The recognized network itself — **at most one**, never a row. Carries `data-fs-card-entry-network-id` with the detected method's id | `flex items-center justify-center` |
+| Network icon (`data-fs-card-entry-network-icon`) | The icon, when the recognized network's name maps to one | `w-[20px] h-[20px]` |
+| Network fallback text (`data-fs-card-entry-network-fallback`) | The recognized network's name as text, when it maps to no icon; mutually exclusive with the icon | `text-[13px] font-medium text-[#333333]` |
+| Field labels (`data-fs-field-label`) | Small, muted label above each input | `text-[13px] font-medium text-[#333333] mb-[4px] block` |
+| Field inputs (`data-fs-field-control`) | The bordered text input | `border border-[#CCCCCC] rounded-[6px] px-[12px] py-[10px] text-[15px] w-full` |
+| Field errors (`data-fs-field-error`) | Inline validation message, small and red | `text-[12px] text-[#C8102E] mt-[4px] block` |
+| CVV helper text (`data-fs-card-entry-cvv-description`) | Small muted line under the CVV field | `text-[12px] text-[#666666] mt-[4px] block` |
+| Placing (`data-fs-card-entry-placing`) | Present while an order-placement sequence is in flight (T28); the whole root is also `inert` and `aria-disabled` at that point, so style this hook rather than relying on pointer events alone | `opacity-60 cursor-not-allowed` |
+| Collapsed (`data-fs-card-entry-collapsed`) | Present on the styled root while the card payment is collapsed — the persisted selection is a method this section does not serve or one that is not a card, and a picker is composed to un-hide it (see Reveal and collapse); the root is also `inert`. **No transition or animation can run on it**: the actual hide is a `hidden` attribute one level up, on an unstyled wrapper this node cannot reach with any class, and an ancestor's `display:none` removes the whole subtree from rendering the instant it applies, before any transition on a descendant could ever paint. Use this hook only for one-shot conditional styling of the (already-unrendered) subtree, never for an entrance/exit animation | `opacity-60` |
+
+Styled minimal example:
+
+```json
+{
+  "card-entry": {
+    "type": "CardEntry",
+    "style": ["flex", "flex-col", "gap-[16px]", "w-full"]
+  }
+}
+```
+
+`CardEntry` renders no separately-styleable schema elements below the root — its internal fields are not independently placeable, so per-field styling is done via the `data-fs-*` hooks above rather than a `style` array on a sub-element.
+
+---
+
+## Accessibility Contract
+
+**What the platform promises:** the four fields sit inside a native `<fieldset>`/`<legend>` pair
+(`legend`, default `"Card details"`) — the pattern every other grouped payment control now follows
+(T38, Decision 1). Each field carries its own `Field.Label`, `aria-invalid`, and an error message
+associated through `aria-describedby` once it fails validation; the CVV field's helper text
+(`cvvDescription`) is linked the same way. There is no composite keyboard widget here — every rendered
+field keeps its own Tab stop, reachable in DOM order. A default `:focus-visible` outline is painted from
+the platform's own stylesheet on every field.
+
+**What the platform does not promise:** colour contrast. `CardEntry` (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
+
+- [[document-field]] — the particle whose progressive-mask engine `CardEntry`'s own masking generalizes; a sibling leaf for the cardholder's tax document, not part of this component.
+- [[client-profile-form]] — the batched-form pattern (`validateDraft` + first-invalid focus) `CardEntry`'s validation reuses.
+- [[pricing]] — shows *advertised* installment plans on a PDP; unrelated to entering a card at checkout.