@vtex/faststore 0.0.8 → 0.0.11

package/dist/docs/binding-switcher.md

@@ -0,0 +1,157 @@
+# BindingSwitcher
+
+**Category:** action
+**Purpose:** Lists the store's bindings and starts a binding switch (locale, currency, and sales channel) through `locale.set`.
+
+---
+
+## Visual cues (how to identify in an image)
+
+A closed dropdown whose visible value is a language name, a chevron, and sometimes one short sentence in a status line. The image is the source of truth for layout.
+
+---
+
+## When to use
+
+A store that declares two or more bindings and wants the shopper to switch the whole binding. Pass `bindings` as `$data.Global.localization.bindings`. With fewer than two counted bindings the component renders nothing.
+
+## When NOT to use
+
+- A country list, a currency picker, or a CMS language field.
+- A store with one binding. It renders nothing and should not reserve an empty control.
+
+---
+
+## Composition
+
+The schema tree is one node. `BindingSwitcher` has no children. The `Select` parts are internal and are not schema children.
+
+```
+BindingSwitcher
+```
+
+---
+
+## Components
+
+### BindingSwitcher
+
+Renders a host `div` (`data-fs-binding-switcher`). No fragment. Declares `actions: { locale: ['set'] }`. Choosing another binding calls `$actions.locale.set({ bindingId })`.
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| `bindings` | object | — | `foundation.json` `localization.bindings`, keyed by binding id. No library default. The store passes `$data.Global.localization.bindings`. |
+
+Copy comes from `$content` (content type `binding-switcher`):
+
+- **`label`:** the accessible name, rendered as the select label.
+- **`notice`:** shown when the page loaded with `fs_notice=no-equivalent`. Inline `<output>` (implicit `status` role).
+
+---
+
+## Canonical schema example
+
+```json
+{
+  "binding-switcher": {
+    "type": "BindingSwitcher",
+    "props": {
+      "bindings": "$data.Global.localization.bindings"
+    },
+    "style": [
+      "flex",
+      "flex-col",
+      "gap-2",
+      "text-[14px]",
+      "[&_[data-fs-binding-switcher-notice]]:text-[13px]",
+      "[&_[data-fs-select-trigger]]:inline-flex",
+      "[&_[data-fs-select-trigger]]:items-center",
+      "[&_[data-fs-select-trigger]]:gap-2",
+      "[&_[data-fs-select-trigger]]:rounded-md",
+      "[&_[data-fs-select-trigger]]:border",
+      "[&_[data-fs-select-trigger]]:border-neutral-300",
+      "[&_[data-fs-select-trigger]]:bg-white",
+      "[&_[data-fs-select-trigger]]:px-3",
+      "[&_[data-fs-select-trigger]]:py-1.5",
+      "[&_[data-fs-select-positioner]]:z-50",
+      "[&_[data-fs-select-popup]]:min-w-[var(--anchor-width)]",
+      "[&_[data-fs-select-popup]]:overflow-hidden",
+      "[&_[data-fs-select-popup]]:rounded-md",
+      "[&_[data-fs-select-popup]]:border",
+      "[&_[data-fs-select-popup]]:border-neutral-200",
+      "[&_[data-fs-select-popup]]:bg-white",
+      "[&_[data-fs-select-popup]]:shadow-lg",
+      "[&_[data-fs-select-list]]:py-1",
+      "[&_[data-fs-select-item]]:cursor-pointer",
+      "[&_[data-fs-select-item]]:px-3",
+      "[&_[data-fs-select-item]]:py-2",
+      "[&_[data-fs-select-item][data-highlighted]]:bg-neutral-100"
+    ]
+  }
+}
+```
+
+---
+
+## Common mistakes
+
+- **LocaleSelector** or **LanguagePicker.** The name is `BindingSwitcher`.
+- **A toast for the notice.** The notice is an inline `<output>`.
+- **A default bindings list.** The store passes `$data.Global.localization.bindings`.
+- **Children that rebuild Select.** The schema element has no children.
+
+---
+
+## Styling
+
+The host stacks the notice above the control. The popup stays in the host and opens below the trigger, 4px clear of it, so the element `style` reaches `[data-fs-select-popup]`. Give that popup an opaque surface. A parent locked to a fixed height lets the notice paint outside the bar; `min-h-16` on that parent keeps the notice inside it.
+
+| Component | What you style | Plausible classes |
+|---|---|---|
+| `BindingSwitcher` | Stacks the notice and the control. The notice line is `text-[13px]`. The popup is `[data-fs-select-popup]`. | `flex flex-col gap-2 text-[14px] [&_[data-fs-binding-switcher-notice]]:text-[13px] [&_[data-fs-select-popup]]:bg-white [&_[data-fs-select-popup]]:border [&_[data-fs-select-popup]]:border-neutral-200 [&_[data-fs-select-popup]]:rounded-md [&_[data-fs-select-popup]]:shadow-lg` |
+
+```json
+{
+  "binding-switcher": {
+    "type": "BindingSwitcher",
+    "props": {
+      "bindings": "$data.Global.localization.bindings"
+    },
+    "style": [
+      "flex",
+      "flex-col",
+      "gap-2",
+      "text-[14px]",
+      "[&_[data-fs-binding-switcher-notice]]:text-[13px]",
+      "[&_[data-fs-select-trigger]]:inline-flex",
+      "[&_[data-fs-select-trigger]]:items-center",
+      "[&_[data-fs-select-trigger]]:gap-2",
+      "[&_[data-fs-select-trigger]]:rounded-md",
+      "[&_[data-fs-select-trigger]]:border",
+      "[&_[data-fs-select-trigger]]:border-neutral-300",
+      "[&_[data-fs-select-trigger]]:bg-white",
+      "[&_[data-fs-select-trigger]]:px-3",
+      "[&_[data-fs-select-trigger]]:py-1.5",
+      "[&_[data-fs-select-positioner]]:z-50",
+      "[&_[data-fs-select-popup]]:min-w-[var(--anchor-width)]",
+      "[&_[data-fs-select-popup]]:overflow-hidden",
+      "[&_[data-fs-select-popup]]:rounded-md",
+      "[&_[data-fs-select-popup]]:border",
+      "[&_[data-fs-select-popup]]:border-neutral-200",
+      "[&_[data-fs-select-popup]]:bg-white",
+      "[&_[data-fs-select-popup]]:shadow-lg",
+      "[&_[data-fs-select-list]]:py-1",
+      "[&_[data-fs-select-item]]:cursor-pointer",
+      "[&_[data-fs-select-item]]:px-3",
+      "[&_[data-fs-select-item]]:py-2",
+      "[&_[data-fs-select-item][data-highlighted]]:bg-neutral-100"
+    ]
+  }
+}
+```
+
+---
+
+## Related
+
+- [[select]] — the empty dropdown this component composes. `Select` does not know about bindings.

package/dist/docs/buy-button.md

@@ -75,12 +75,9 @@ Root data provider. Declares the GraphQL fragment and exposes product/variant co
 
 ### BuyButtonButton
 
-The rendered button. Dispatches `$actions.cart.addItem(...)` on click.
+The rendered button. Dispatches `$actions.cart.addItem(...)` on click. No props.
 
-| Prop | Type | Default | Notes |
-|------|------|---------|-------|
-| `availableLabel` | string | `"Comprar"` | Label shown when the variant is available for sale |
-| `unavailableLabel` | string | `"Indisponivel"` | Label shown when the variant is not available |
+**Content model** (`buy-button-labels`): `availableLabel` (shown when the variant is available for sale) and `unavailableLabel` (shown when it is not), both ICU messages read only from `$content`. A missing message renders empty and logs `message.missing`. `children` replaces the label, and then no message is formatted.
 
 **Actions:** declares `actions: { cart: ['addItem'] }`; the compiler threads the `addItem` handler in via `$actions.cart`. Renders `null` when `BuyButtonRoot` has no valid variant data. Disabled (and `aria-busy`) while the add is in-flight (the button tracks its own pending state). Must be a descendant of `BuyButtonRoot`.
 
@@ -132,9 +129,9 @@ Fill each element's `style` array with Tailwind classes read off the image. Typi
 | Component | What you style | Plausible classes |
 |---|---|---|
 | `BuyButtonRoot` | Layout wrapper only — it renders no box of its own | `block w-full mt-[8px]` |
-| `BuyButtonButton` | The CTA: full-width pill in the brand color, with hover and disabled states | `inline-flex items-center justify-center w-full h-[44px] px-[20px] bg-[#C8102E] text-white rounded-[4px] text-[14px] font-bold uppercase cursor-pointer transition-colors hover:bg-[#A50D26] disabled:opacity-50 disabled:cursor-not-allowed` |
+| `BuyButtonButton` | The CTA: full-width pill in the brand color, with hover and disabled states | `inline-flex items-center justify-center w-full h-[44px] px-[20px] bg-[var(--color-primary)] text-white rounded-[4px] text-[14px] font-bold uppercase cursor-pointer transition-colors hover:bg-[var(--color-primary-hover)] disabled:opacity-50 disabled:cursor-not-allowed` |
 
-Read the button's fill color straight off the image as an arbitrary hex (`bg-[#C8102E]`); derive the hover shade as a slightly darker value. Always include `disabled:` styling — the button auto-disables when the variant is unavailable. Do not invent a swatch or token for the brand color; inline hex only.
+The button's fill is the brand color, so write it as the role's variable (`bg-[var(--color-primary)]`), never as the hex read off the image. Its hover and active shades are slightly darker values that several elements of the page share, so declare them in the page or layout `theme` (`--color-primary-hover`, `--color-primary-active`). Always include `disabled:` styling — the button auto-disables when the variant is unavailable.
 
 Styled example:
 
@@ -148,11 +145,13 @@ Styled example:
   "buy-button-action": {
     "type": "BuyButtonButton",
     "props": { "availableLabel": "Comprar", "unavailableLabel": "Indisponível" },
-    "style": ["inline-flex", "items-center", "justify-center", "w-full", "h-[44px]", "px-[20px]", "bg-[#C8102E]", "text-white", "rounded-[4px]", "text-[14px]", "font-bold", "tracking-[0.06em]", "uppercase", "cursor-pointer", "transition-colors", "duration-150", "hover:bg-[#A50D26]", "active:bg-[#8A0B20]", "disabled:opacity-50", "disabled:cursor-not-allowed"]
+    "style": ["inline-flex", "items-center", "justify-center", "w-full", "h-[44px]", "px-[20px]", "bg-[var(--color-primary)]", "text-white", "rounded-[4px]", "text-[14px]", "font-bold", "tracking-[0.06em]", "uppercase", "cursor-pointer", "transition-colors", "duration-150", "hover:bg-[var(--color-primary-hover)]", "active:bg-[var(--color-primary-active)]", "disabled:opacity-50", "disabled:cursor-not-allowed"]
   }
 }
 ```
 
+The page or layout `theme` that declares the shades: `{"--color-primary-hover": "#A50D26", "--color-primary-active": "#8A0B20"}`.
+
 ---
 
 ## Related

package/dist/docs/card-entry.md

@@ -50,7 +50,7 @@ PaymentSectionRoot                  (or PaymentSectionController)
 ├── … 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).
+`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 while the field does not have focus: readable while the shopper is in the field, so they can read back what they just typed and catch a typo, and obscured the moment focus leaves it, with no length involved — a partial code is hidden on blur like a full one. Re-focusing a hidden code reveals it again, so a typo can be read and corrected. A disabled field counts as unfocused, because a browser fires no `blur` when a focused input becomes disabled; the focus flag is also reset when the card form collapses and when the input unmounts. The style is derived from the value and the focus flag on every render, never from an effect or a timer, so a paste or a browser autofill that delivers every digit while the field is unfocused, and the blur itself, open no legible window. The trade-off is deliberate: while the field has focus, a code the shopper just typed is on screen in the clear. `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 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. 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:**
 
@@ -72,7 +72,7 @@ Collapsing clears the security code field, and only the security code. The card
 
 The authored `disabled` prop is independent of the collapse: a store that freezes the form with `disabled` sees no change, and a collapsed form may also be `disabled` — neither implies the other.
 
-In the checkout, the card number, holder name, expiration, and security code are cleared after every outcome in which the card target ran: the card POST resolved clean, resolved with errors or threw, or the target refused before any request. They are kept when the submission was refused before the target ran (the form's own check, a refused or untrusted transaction, the submit gate, no method selected) so the shopper can fix them.
+In the checkout, the card number, holder name, expiration, and security code are cleared after every outcome in which the card target ran: the card POST resolved clean, resolved with errors or threw, or the target refused before any request. They are kept when the submission was refused before the target ran (the form's own check, a refused or untrusted transaction, the submit gate, no method selected) so the shopper can fix them. The values stay while the card request is open and clear as soon as it settles, ahead of the confirmation callback, so a callback error or timeout finds the form already empty. While the order attempt is resume-only the form accepts no input, so a card cannot be typed into a form that the next click would ignore.
 
 ---
 
@@ -90,7 +90,7 @@ In the checkout, the card number, holder name, expiration, and security code are
 }
 ```
 
-**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`:
+**If the store's `foundation.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
 {
@@ -107,7 +107,7 @@ Omitting `include` entirely is silent too. The network icon renders as an empty
 
 ## Store setup: response headers
 
-The card number and security code are typed into `CardEntry`'s raw fields and POSTed from the browser straight to the VTEX payment gateway, so the page that composes it needs a policy that names the vault host the card is POSTed to, forbids framing the page, and narrows what the page may load and call. The generator ships no default: the store declares it in `global.json` under `responseHeaders`, scoped by `routes` to the page that composes `CardEntry`.
+The card number and security code are typed into `CardEntry`'s raw fields and POSTed from the browser straight to the VTEX payment gateway, so the page that composes it needs a policy that names the vault host the card is POSTed to, forbids framing the page, and narrows what the page may load and call. The generator ships no default: the store declares it in `foundation.json` under `responseHeaders`, scoped by `routes` to the page that composes `CardEntry`.
 
 ```json
 {
@@ -115,7 +115,7 @@ The card number and security code are typed into `CardEntry`'s raw fields and PO
     {
       "routes": ["/checkout"],
       "headers": {
-        "Content-Security-Policy": "default-src 'self'; script-src 'self' 'unsafe-inline'; style-src 'self' 'unsafe-inline'; img-src 'self' data: https:; font-src 'self' data:; connect-src 'self' https://acme.vtexvault.com; frame-ancestors 'none'; base-uri 'self'; object-src 'none'",
+        "Content-Security-Policy": "default-src 'self'; script-src 'self' 'unsafe-inline'; style-src 'self' 'unsafe-inline'; img-src 'self' data: https://acme.vtexassets.com; font-src 'self' data:; connect-src 'self' https://acme.vtexvault.com; form-action 'self'; frame-ancestors 'none'; base-uri 'self'; object-src 'none'",
         "Referrer-Policy": "strict-origin-when-cross-origin"
       }
     }
@@ -123,10 +123,10 @@ The card number and security code are typed into `CardEntry`'s raw fields and PO
 }
 ```
 
-- **The vault host in `connect-src` is `https://{account}.vtexvault.com`, for the account the store serves.** That is the `NEXT_PUBLIC_ACCOUNT` the store is built with, which is not always `account.name` in `global.json`. Write the served account, with no wildcard: `https://*.vtexvault.com` would let a compromised script send the card to any tenant's vault.
+- **The vault host in `connect-src` is `https://{account}.vtexvault.com`, for the account the store serves.** That is the `NEXT_PUBLIC_ACCOUNT` the store is built with, which is not always `store.account` in `foundation.json`. Write the served account, with no wildcard: `https://*.vtexvault.com` would let a compromised script send the card to any tenant's vault.
 - **A policy that names the legacy payments host (`vtexpayments.com.br`) makes the browser block the card POST.** The order cannot be placed and nothing else on the page reports why. The generated app calls its own GraphQL at the relative `/api/graphql`, so `'self'` covers it; a store built with an absolute `NEXT_PUBLIC_STOREFRONT_API_URL` must add that origin.
 - **A rule's `routes` must name the page that composes `CardEntry`**, as the page's `route` spells it (`/checkout`, `/reserva/checkout/payment`). Renaming that page fails the compile instead of dropping the policy. A page added later that composes `CardEntry` carries nothing until its route is added to the rule.
-- **`script-src 'unsafe-inline'` is a known limit, and the policy does not stop injected script from sending the card off the page.** A static header cannot carry a nonce, so the inline scripts Next.js emits need it, and script injected into the page runs with the same rights. `connect-src` closes only `fetch`, XHR, beacons and WebSocket. The policy still leaves three channels open to any https host: an image request (`img-src https:`, which the page needs for catalog images), a form submission (no `form-action`) and a navigation (CSP cannot restrict one). What today's ruled policy does give is the vault origin pinned, no `'unsafe-eval'`, a page no other site can frame (`frame-ancestors 'none'`) and no `http:` or wildcard source. It does not replace keeping untrusted script off the payment page.
+- **`script-src 'unsafe-inline'` is a known limit, and the policy does not stop injected script from sending the card off the page.** A static header cannot carry a nonce, so the inline scripts Next.js emits need it, and script injected into the page runs with the same rights. `connect-src` closes only `fetch`, XHR, beacons and WebSocket. The policy still leaves one channel open to any https host: a navigation (CSP cannot restrict one). The image and form-post channels are closed: `img-src` names exactly one image origin, `https://{account}.vtexassets.com`, so a store whose page loads images from another origin must list that origin exactly (a bare `https:` fails the header check), and `form-action 'self'` stops a form from posting to another origin (the check accepts `'self'` or `'none'` and nothing else). What today's ruled policy does give is the vault origin pinned, no `'unsafe-eval'`, a page no other site can frame (`frame-ancestors 'none'`) and no `http:` or wildcard source. It does not replace keeping untrusted script off the payment page.
 - **`frame-ancestors 'none'`** blanks the page inside any iframe, including an editor preview.
 - **reCAPTCHA needs the anti-bot origins, and the ruled policy above does not declare them yet.** The challenge frame and script come from `https://www.google.com` and `https://www.gstatic.com`, the origins `sdk/anti-bot` declares. The frame is blocked by `default-src 'self'` (no `frame-src`) and the script by `script-src 'self' 'unsafe-inline'`, so both need the anti-bot origins. The stores add them together with whoever wires `getAntiBotToken`; the header check accepts a `frame-src` that names only those two origins and rejects any other.
 - **Under `next dev` the served `script-src` also carries `'unsafe-eval'`; production does not.** React Refresh evaluates code in the browser, so the generated `next.config.ts` adds `'unsafe-eval'` to the `script-src` of every Content-Security-Policy it serves only when `NODE_ENV` is `development` (what `next dev` sets), which is what `pnpm dev:example` runs. Any build whose `NODE_ENV` is not `development` (the default for `next build` and `next start`) serves the declared policy byte for byte, so the live header check still runs against them: a dev response shows a `script-src` the store never declared, which `scripts/assert-payment-page-headers.mjs` rejects by design, so run that script against `next start`.
@@ -143,33 +143,44 @@ 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 a configured network claims only as a prefix (the wrong length, or two networks at once). |
-| `networkNotAcceptedMessage` | string | `"This card is not from a network the store accepts"` | Shown for a Luhn-valid number that no configured network claims at all. |
-| `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. |
 
+**Content model** (`card-entry`), every field read only from `$content` (a missing message renders empty and logs `message.missing`):
+
+| Field | Source copy | Notes |
+|-------|-------------|-------|
+| `legend` | "Card details" | Fieldset legend/title. |
+| `numberLabel` | "Card number" | Card-number field label. |
+| `holderNameLabel` | "Cardholder name" | Holder-name field label. Same noun as `holderNameRequiredMessage`, deliberately. |
+| `expirationLabel` | "Expiration date" | Expiration field label. |
+| `expirationPlaceholder` | "MM/YY" | Expiration field placeholder. |
+| `cvvLabel` | "Security code" | CVV field label. |
+| `cvvDescription` | "The 3-4 digit number on your card" | Helper text under the CVV field. A blank message renders nothing. |
+| `numberRequiredMessage` | "Card number is required" | Shown when the card-number field is left blank. |
+| `numberInvalidMessage` | "Enter a valid card number" | Shown for a Luhn-invalid number, or one a configured network claims only as a prefix (the wrong length, or two networks at once). |
+| `networkNotAcceptedMessage` | "This card is not from a network the store accepts" | Shown for a Luhn-valid number that no configured network claims at all. |
+| `holderNameRequiredMessage` | "Cardholder name is required" | Shown when the holder-name field is left blank and the detected method requires it. |
+| `expirationRequiredMessage` | "Expiration date is required" | Shown when the expiration field is left blank and the detected method requires it. |
+| `expirationInvalidMessage` | "Enter a valid expiration date" | Shown for a structurally malformed `MM/YY`. |
+| `expirationExpiredMessage` | "This card has expired" | Shown for a structurally valid `MM/YY` that has already passed. |
+| `cvvRequiredMessage` | "Security code is required" | Shown when the CVV field is left blank and the detected method requires it. |
+| `cvvInvalidMessage` | "Enter a valid security code" | Shown for a CVV that fails the detected method's format. |
+
 **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.
 
+**Field timing:** each field validates when the shopper leaves it. A blur writes or clears only that field's error, and editing a field clears its own error. A blur never moves focus: pulling focus back to a half-typed expiration would trap a shopper who tabs away. The first invalid field takes focus only when Place order refuses the draft.
+
+**Keyboard hint:** the number, expiration, and security code inputs carry `inputmode="numeric"`; the holder name input carries none. The attribute is advisory, so a keyboard that ignores it still shows letters.
+
+**A card from a network the store does not accept:** a Luhn-valid number that no configured network claims, exactly or as a prefix, is told apart from a malformed one. The number field shows `networkNotAcceptedMessage` when the shopper leaves it, and Place order refuses with the code `UNSUPPORTED_CARD_NETWORK`, rendered through `PlaceOrder`'s `unsupportedNetworkMessage`, whether or not a payment method is selected. The refusal comes before any transaction opens. With no method selected, the form gives the place-order sequence a side-effect-free explanation, asked only at the missing-method step, so the order of the checks (path, method, submit gate, card check) does not change; that click sets no field error and moves no focus, because the blur message is already on the field. With a method selected, the card check itself refuses with the same code, shows the field error, and focuses the number. A prefix claimed at the wrong length, a prefix two networks both claim, a Luhn-invalid number, and a blank number keep their existing refusals, and so does a store whose methods carry no number pattern, where detection never ran. The code and both messages are fixed copy: nothing derived from the typed number appears in them or in a log line.
+
 **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.
 
 ---
@@ -234,14 +245,16 @@ Style `CardEntry`'s root as a vertical stack of fields, matching a typical card
 | 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` |
+| 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-[var(--color-ink)]` |
+| Field labels (`data-fs-field-label`) | Small, muted label above each input | `text-[13px] font-medium text-[var(--color-ink)] mb-[4px] block` |
+| Field inputs (`data-fs-field-control`) | The bordered text input | `border border-[color-mix(in_srgb,var(--color-ink)_20%,transparent)] rounded-[var(--radius-base)] px-[12px] py-[10px] text-[15px] w-full` |
+| Field errors (`data-fs-field-error`) | Inline validation message, small | `text-[12px] mt-[4px] block` |
+| CVV helper text (`data-fs-card-entry-cvv-description`) | Small muted line under the CVV field | `text-[12px] text-[color-mix(in_srgb,var(--color-ink)_60%,transparent)] mt-[4px] block` |
 | Placing (`data-fs-card-entry-placing`) | Present while an order-placement sequence is in flight (T28), and while the order attempt is resume-only (its card may already have been sent, so the fields do not accept input) until the attempt is freed; 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` |
 
+A status color is a `visualIdentity` feedback role of the foundation: when the store declares them, color the error row `text-[var(--color-feedback-danger)]`, the success row `text-[var(--color-feedback-success)]` and the notice row `text-[var(--color-feedback-warning)]`, never with a hex.
+
 Styled minimal example:
 
 ```json
@@ -260,7 +273,7 @@ Styled minimal example:
 ## 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
+(the `legend` message) — 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

package/dist/docs/card-summary.md

@@ -0,0 +1,185 @@
+# Card Summary
+
+**Category:** content
+**Purpose:** A saved card's identity: its network's mark, its label or else its network name, a mask, and its last four digits, as parts the schema arranges.
+
+---
+
+## Visual cues (how to identify in an image)
+
+- A card-network logo (Visa, Mastercard, American Express, Diners, Elo) beside a short text.
+- A name such as `Visa` or a shopper's own label such as `Company card`.
+- A masking symbol (`••••`, `****`) followed by four digits: `•••• 1234`.
+- Usually one line per card, repeated in a list or inside a selectable row.
+
+The image is the source of truth for layout.
+
+## When to use
+
+- Describing one saved card wherever it appears: the account's saved-cards list, a removal confirmation, the checkout's saved-card row.
+
+## When NOT to use
+
+- The store's accepted payment methods as a strip of logos → [[payment-methods]].
+- Typing a new card → the checkout's card entry; this particle never takes a full number or a security code.
+- A card's expiry or usability state → the row that owns the card renders it beside this particle.
+
+---
+
+## Composition
+
+```
+<row that provides 'card-summary'>   ← e.g. AccountSavedCardItem
+└── CardSummary
+    ├── CardSummaryMark      (default)
+    ├── CardSummaryName      (default)
+    ├── CardSummaryMask      (default)
+    └── CardSummaryDigits    (default)
+```
+
+`CardSummary` with no children renders the four parts in that order. Composing children replaces the default: any order, any subset. Child order is the visual order and the screen-reader order. The parts can also sit directly in the providing row, without the `CardSummary` wrapper.
+
+Every part requires the `card-summary` context, and only a matter row that owns card data provides it in a schema. The row wraps its children in `CardSummaryRoot` in code and declares `'card-summary'` in its own `providesContext`, so the schema composes the parts directly in the row. Context matching is by contract, not by component name. Stories, tests, and hand-written JSX render `CardSummaryRoot` themselves.
+
+A part outside any provider fails the build with a `ContextConstraintError`, and throws at runtime outside the compiler.
+
+---
+
+## Components
+
+### CardSummaryRoot
+
+Code only: it has no catalog entry and is never placed in a schema, because a schema cannot supply the card. Renders no element. Publishes the card to the parts. Keeps only the trailing four digit characters of `lastDigits`; the raw value never reaches a part.
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| `network` | string | — | The network's display name from the platform, e.g. `Visa`. Data, not a schema prop. |
+| `lastDigits` | string | — | The card's last digits. Only four ever render. Data, not a schema prop. |
+| `label` | string \| null | — | The shopper's own name for the card. Shown in place of the network name when non-blank. Data, not a schema prop. |
+
+### CardSummary
+
+The wrapper, `<span data-fs-card-summary>`. Carries `data-fs-card-summary-network="<icon>"` when the network has a mark and `data-fs-card-summary-labeled` when a label is present. No props besides `$content`.
+
+It formats its `endingIn` message and hands it to the `CardSummaryDigits` inside it. A missing message logs an error, and the digits are then read bare. A `CardSummary` has `$content` only when the store places it or a parent forwards a message to it, as `AccountSavedCardRemoveDescription` forwards its `cardEndingIn`.
+
+Content type `card-summary`:
+
+| Content field | Description |
+|---|---|
+| endingIn | The last digits as read to assistive technology, with the `lastDigits` argument |
+
+### CardSummaryMark
+
+The network's mark. No props. Decided by the data, never by which other parts are composed:
+
+| Card | Renders |
+|---|---|
+| Mapped network, no label | The glyph, decorative (the name says the network). |
+| Mapped network, labelled | The glyph plus the network name as screen-reader text. |
+| Unmapped network, no label | Nothing. |
+| Unmapped network, labelled | The network name as visible text (`data-fs-card-summary-network-name`), never another network's glyph. |
+
+So a labelled card still tells a sighted shopper and a screen reader its network, even when the schema drops `CardSummaryName`. An unlabelled card does not: its glyph is decorative and `CardSummaryName` is what announces the network, so the network is announced exactly once in the default composition.
+
+### CardSummaryName
+
+The label, or else the network name. Nothing when both are blank. Read-only. No props.
+
+### CardSummaryMask
+
+Decoration for the hidden digits, always `aria-hidden`. Nothing when empty or when the card has no digits.
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| `mask` | string | `••••` | The masking symbol. An empty string renders nothing. |
+
+`children` replace `mask`, e.g. an `Icon`. Keep them inline: the particle sits inside labels and paragraphs.
+
+### CardSummaryDigits
+
+The last four digits. Screen readers hear the `endingIn` message of the `CardSummary` around them, such as "ending in 1234"; the visible digits are hidden from them. Outside a `CardSummary`, or with its message missing, screen readers hear the bare digits. Nothing when the card has no digits. No props.
+
+---
+
+## Networks and the `icons.include` obligation
+
+The mark comes from `CARD_NETWORK_ICON_BY_KEY` in `card-network.ts`, the one map every card surface shares. A network name matches after lowercasing and removing every character outside `a-z`: `Visa`, `Mastercard`, `Amex`, `American Express`, `Diners`, `Diners Club`, and `Elo` have marks. Matching is exact, so `Visa Electron` or `Elo Debit` render by name, without a mark. `cardNetworkIcon(name)` returns the icon name or `null`.
+
+**Every mapped name must be registered.** The network comes from data, so the compiler cannot see which glyphs a route needs. A store that renders `CardSummaryMark` lists the names under `icons.include` in its `foundation.json`; it is JSON, so it cannot import `CARD_NETWORK_ICON_NAMES`, and the names are written out:
+
+```json
+{ "icons": { "include": ["visa", "mastercard", "amex", "diners", "elo-card"] } }
+```
+
+A name the store never registered renders an empty `<svg>`: no build error and no runtime error, just a missing mark. All five are base-dialect names, so they resolve in any store whatever its icon collection.
+
+---
+
+## Canonical schema example
+
+The account's row provides the context; the schema arranges the parts:
+
+```json
+{
+  "saved-card-item": { "type": "AccountSavedCardItem", "children": ["card-summary"] },
+  "card-summary": { "type": "CardSummary", "style": ["inline-flex", "items-center", "gap-[8px]"] }
+}
+```
+
+Digits first, with another mask:
+
+```json
+{
+  "saved-card-item": { "type": "AccountSavedCardItem", "children": ["card-digits", "card-mask", "card-mark", "card-name"] },
+  "card-digits": { "type": "CardSummaryDigits" },
+  "card-mask": { "type": "CardSummaryMask", "props": { "mask": "****" } },
+  "card-mark": { "type": "CardSummaryMark" },
+  "card-name": { "type": "CardSummaryName" }
+}
+```
+
+## Common mistakes
+
+- **`CardSummaryNumber`, `CardSummaryLastFour`.** The correct name is `CardSummaryDigits`.
+- **`CardSummaryBrand`, `CardSummaryFlag`, `CardSummaryIcon`.** The correct name is `CardSummaryMark`.
+- **`CardSummaryLabel`.** The correct name is `CardSummaryName`; it shows the label or else the network name.
+- **Writing the bullets inside `CardSummaryDigits`.** The mask is its own part, `CardSummaryMask`.
+- **Placing `CardSummaryRoot` in a schema, or passing `network`, `lastDigits`, or `label` as schema props.** The card is data from the row that provides `card-summary`; the Root is not in the catalog.
+- **Composing a part outside a row that provides `card-summary`.** It fails the build.
+- **Dropping `CardSummaryMark` or `CardSummaryDigits` from a custom composition.** The PRD requires both beside a card; only the default composition guarantees them.
+- **Composing `CardSummaryMark` without `CardSummaryName`.** On an unlabelled card the glyph is decorative and the name is what announces the network, so a screen reader hears only "ending in 1234". Keep `CardSummaryName` whenever `CardSummaryMark` is composed.
+
+---
+
+## Styling
+
+| Component | What you style | Plausible classes |
+|---|---|---|
+| `CardSummary` | Lines the parts up | `inline-flex items-center gap-[8px]` |
+| `CardSummaryMark` | Mark box; size the glyph through it | `inline-flex items-center [&_svg]:h-[24px] [&_svg]:w-[32px]` |
+| `CardSummaryName` | Name typography | `text-[14px] font-medium text-[var(--color-text)]` |
+| `CardSummaryMask` | Mask color and spacing | `text-[14px] tracking-[2px] text-[var(--color-text-muted)]` |
+| `CardSummaryDigits` | Digit typography | `text-[14px] tabular-nums text-[var(--color-text)]` |
+
+`CardSummaryRoot` renders no element and is not styled.
+
+```json
+{
+  "card-summary": { "type": "CardSummary", "style": ["inline-flex", "items-center", "gap-[8px]"], "children": ["card-mark", "card-name", "card-mask", "card-digits"] },
+  "card-mark": { "type": "CardSummaryMark", "style": ["inline-flex", "items-center", "[&_svg]:h-[24px]", "[&_svg]:w-[32px]"] },
+  "card-name": { "type": "CardSummaryName", "style": ["text-[14px]", "font-medium", "text-[var(--color-text)]"] },
+  "card-mask": { "type": "CardSummaryMask", "style": ["text-[14px]", "tracking-[2px]", "text-[var(--color-text-muted)]"] },
+  "card-digits": { "type": "CardSummaryDigits", "style": ["text-[14px]", "tabular-nums", "text-[var(--color-text)]"] }
+}
+```
+
+The colors that several elements share are variables of the page or layout `theme`, which declares them: `{"--color-text": "#1F1F1F", "--color-text-muted": "#6B6B6B"}`. A color used once stays a hex.
+
+---
+
+## Related
+
+- [[payment-methods]]: the store's accepted payment methods as a strip of logos; not a saved card.
+- [[address-summary]]: the same Root-plus-parts shape, for a postal address.
+- [[icon]]: renders the mark from the base icon dialect.

package/dist/docs/cardholder-document.md

@@ -69,6 +69,8 @@ The field itself. Renders the `DocumentField` particle for the type `usePayment(
 | `errorMessage` | `string` | `'Invalid '` + the type's name | Shown inline when the typed value fails the type's validation on blur. |
 | `disabled` | `boolean` | `false` | Disables the input without hiding it — independent of the data-driven presence gate. |
 
+The method decides whether the field shows and whether it is mandatory; the store's country decides which document it is. The type is the first displayable document the store's country row lists that this build knows, and a country row's own `required` flag is read by nobody. The SSN and SIN inputs carry `autocomplete="off"` so a browser does not offer them for autofill; the CPF and RFC inputs carry no `autocomplete` attribute, and every type stays `type="text"`.
+
 No `documentType` prop — the store's country decides it. No `required` prop — requiredness is always read from the selected method's validator, never authored.
 
 **Data:** declares no `fragment` of its own. It reads `selectedMethod`, `countryDocumentType`, `draft`, and `setDraftDocument` off the ambient `payment` context that `PaymentSectionRoot` / `PaymentSectionController` already fetches for.
@@ -109,8 +111,8 @@ No `documentType` prop — the store's country decides it. No `required` prop
 
 ## Known limitations
 
-- **Four person documents, by store country.** The country comes from `Payment.storeCountryCode` and `Payment.countries`. A store whose country resolves to no document type shows no field, refuses nothing and sends no document. A document typed while the field was shown is posted only while the selected method still asks for one and the country still resolves a type; the draft itself is not cleared. `label`, `placeholder` and `errorMessage` have no catalog default (the right copy depends on the country), so leave them unset unless the store serves one country.
-- **Server-driven requiredness renders the field correctly and is also enforced at submit time — but not by this component or by `CardEntry`.** This component marks the field required when the validator says so; a required-but-blank or malformed value (whether or not required) blocks Place Order client-side, before any transaction opens, **while the selected method's validator also says the document is displayable**. That gate lives in `matter/payment/use-payment-submit-gate.ts` (T24) and is consumed by `PlaceOrder`, not by this component or by `CardEntry`'s own `validateDraft` — this component's only job stays publishing `draft.document` via `setDraftDocument`. When the *currently* selected method's validator says `documentDisplayable: false`, the gate treats `draft.document` as inert either way (fix pass, findings R1/S4/S5): there is no field on screen for the shopper to read a leftover value from or correct it in, whether that value is left over from a previously selected, displayable method or simply blank. See `specs/cardholder-document-submit-gate.md` for the gate's full contract.
+- **Four person documents, by store country.** The country comes from `Payment.storeCountryCode` and `Payment.countries`. A store whose country resolves to no document type shows no field, refuses nothing and sends no document, even when the selected method says a document is required, so the order is not refused client-side for it. A document typed while the field was shown is posted only while the selected method still asks for one and the country still resolves a type; the draft itself is not cleared. `label`, `placeholder` and `errorMessage` have no catalog default (the right copy depends on the country), so leave them unset unless the store serves one country.
+- **Server-driven requiredness renders the field correctly and is also enforced at submit time — but not by this component or by `CardEntry`.** This component marks the field required when the validator says so; a required-but-blank or malformed value (whether or not required) blocks Place Order client-side, before any transaction opens, **while the selected method's validator also says the document is displayable**. That gate lives in `matter/payment/use-payment-submit-gate.ts` (T24) and is consumed by `PlaceOrder`, not by this component or by `CardEntry`'s own `validateDraft` — this component's only job stays publishing `draft.document` via `setDraftDocument`. The gate checks the value against the same country-resolved type the field shows. When the *currently* selected method's validator says `documentDisplayable: false`, the gate treats `draft.document` as inert either way (fix pass, findings R1/S4/S5): there is no field on screen for the shopper to read a leftover value from or correct it in, whether that value is left over from a previously selected, displayable method or simply blank.
 
 ---
 
@@ -120,7 +122,7 @@ No `documentType` prop — the store's country decides it. No `required` prop
 
 | Component | What you style | Plausible classes |
 |---|---|---|
-| `CardholderDocument` | The field's own label, input box, and inline error — same shape as a `Field.Root` | `flex flex-col gap-[4px] w-full` on the root; `text-[14px] font-medium text-[#1A1A1A]` for the label; `border border-[#CCCCCC] rounded-[6px] px-[12px] py-[8px] text-[14px]` for the input |
+| `CardholderDocument` | The field's own label, input box, and inline error — same shape as a `Field.Root` | `flex flex-col gap-[4px] w-full` on the root; `text-[14px] font-medium text-[var(--color-ink)]` for the label; `border border-[color-mix(in_srgb,var(--color-ink)_20%,transparent)] rounded-[var(--radius-base)] px-[12px] py-[8px] text-[14px]` for the input |
 | Placing (`data-fs-cardholder-document-placing`) | Present while an order-placement sequence is in flight (T28); the field is also `inert` and `aria-disabled` at that point | `opacity-60 cursor-not-allowed` |
 
 Styled example: