@vtex/faststore 0.0.7 → 0.0.8

package/dist/docs/billing-address.md

@@ -108,6 +108,7 @@ a form the shopper cannot see.
 | `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. |
+| `postalCodeInvalidMessage` | string | `"Enter a valid postal code."` | Shown as an inline field error under a touched, non-blank postal code that does not match the selected country's format (the descriptor's `rule.pattern`, the same one the delivery form enforces). Only the postal code reads this prop; the English default matches every other default on this form, so an author localises it with the rest. A blank postal code reads `fieldRequiredMessage` instead, never this. The message never contains the typed value. 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
@@ -132,9 +133,9 @@ fields does not prevent that either — there is no `<form>` element anywhere in
 `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`.
+driven by a local touched-field state (blur, or a refused submit focusing the field), 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
@@ -154,10 +155,13 @@ stays checked and the shopper never opens the form. It never reacts to the toggl
 `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.
 
+**Focus on refusal:** while the custom-address form is open, it registers itself so that when `PlaceOrder` refuses an order because the address was never saved, keyboard focus moves into the form: to the first rendered required field that is still blank; if none is blank, to the first rendered field whose value fails its country's format (a postal code `123` for BRA); and only when every field is filled and well-formed, to the submit control. The field the focus lands on, blank or malformed, is marked touched, so its message (`required` for a blank field, `format` for a malformed one) shows with the focus and no blur is needed. The country selector is never the target, and a disabled field or a disabled submit control (for example while saving) takes no focus. The reason stays in `PlaceOrder`'s existing alert and this component's unsaved-address notice. Focus moves only on the refused click.
+
 **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.
+— never a code change here. The postal code's format is the same data: the descriptor's `rule.pattern`
+gates the submit button and the field error, so a country's format is defined once for both forms.
 
 ---
 
@@ -228,7 +232,7 @@ while the box is unchecked, and an optional inline error.
 | 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]` |
+| Field error (`data-fs-field-error`) | Per-field validation message, shown once a field is touched: a blank required field, or a non-blank postal code that fails the country's format (T38); a refused submit that focuses the field touches it without a blur | `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` |
 
@@ -252,10 +256,14 @@ There is no per-field styling hook beyond the particles' own `data-fs-checkbox-*
 ## 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.
+its own validity once the shopper has touched it. A field is touched when the shopper blurs it, or when a
+refused submit moves focus to it (no blur ever comes there). 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. A postal code that is non-blank but not in the selected country's format
+is marked the same way, with `postalCodeInvalidMessage` as its error; switching country re-judges the
+typed value at once. Blank wins over format: a blank postal code reads `fieldRequiredMessage`, never the
+format message. 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.
 

package/dist/docs/card-entry.md

@@ -70,7 +70,9 @@ While collapsed, `CardEntry` still answers a place-order attempt: it keeps its s
 
 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.
+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.
 
 ---
 
@@ -78,12 +80,12 @@ The authored `disabled` prop is independent of this: a store that freezes the fo
 
 `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`:**
+**Any store composing `CardEntry` (or `SavedCards` / `SavedCardOption`) must declare the six network icon names in `global.icons.include`:**
 
 ```json
 {
   "icons": {
-    "include": ["amex", "diners", "elo-card", "mastercard", "visa"]
+    "include": ["amex", "diners", "discover", "elo-card", "mastercard", "visa"]
   }
 }
 ```
@@ -94,7 +96,7 @@ The authored `disabled` prop is independent of this: a store that freezes the fo
 {
   "icons": {
     "collection": "ph",
-    "include": ["amex", "diners", "elo-card", "mastercard", "visa"]
+    "include": ["amex", "diners", "discover", "elo-card", "mastercard", "visa"]
   }
 }
 ```
@@ -103,6 +105,34 @@ Copying the first snippet verbatim over an existing `icons` object silently drop
 
 Omitting `include` entirely is silent too. The network icon renders as an empty 24×24 box instead of the card mark.
 
+## 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`.
+
+```json
+{
+  "responseHeaders": [
+    {
+      "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'",
+        "Referrer-Policy": "strict-origin-when-cross-origin"
+      }
+    }
+  ]
+}
+```
+
+- **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.
+- **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.
+- **`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`.
+
+To check a served page, run `node scripts/assert-payment-page-headers.mjs --url <page url> --vault-host https://<account>.vtexvault.com`.
+
 ---
 
 ## Components
@@ -124,7 +154,8 @@ The only component. No internal sub-parts are separately schema-addressable.
 | `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. |
+| `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`. |
@@ -208,7 +239,7 @@ Style `CardEntry`'s root as a vertical stack of fields, matching a typical card
 | 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` |
+| 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` |
 
 Styled minimal example:

package/dist/docs/cardholder-document.md

@@ -1,7 +1,7 @@
 # CardholderDocument
 
 **Category:** commerce
-**Purpose:** A single tax-document input (CPF) for the checkout payment step, shown or hidden and marked required by the currently selected payment method's server-driven configuration.
+**Purpose:** A single tax-document input for the checkout payment step. The store's country picks the document (SSN for the United States, CPF for Brazil, SIN for Canada, RFC for Mexico); the currently selected payment method's server-driven configuration shows or hides it and marks it required.
 
 ---
 
@@ -11,12 +11,12 @@ Use these signals to detect that a CardholderDocument block is present. Position
 
 A CardholderDocument block is:
 
-- A **single labeled text input**, formatted with dots and a dash like `123.456.789-01` (the CPF mask).
-- Labeled **"CPF"** or a similar tax-document label — never "Card number", "Expiration", or "CVV".
+- A **single labeled text input**, formatted like `123.456.789-01` (CPF), `123-45-6789` (SSN), `046-454-286` (SIN) or `ABCD010101AB1` (RFC).
+- Labeled **"CPF"**, **"SSN"**, **"SIN"**, **"RFC"** or a similar tax-document label — never "Card number", "Expiration", or "CVV".
 - Not accompanied by a network icon, a "•••• 1234" masked number, or any card-brand logo — those belong to `CardEntry` or `SavedCards`, not this block.
 - Sometimes marked with a required indicator (an asterisk or similar) next to its label; sometimes not — both are valid, since requiredness is server-driven per payment method.
 
-If the image shows a **card-entry form with one extra plain text field formatted like a Brazilian tax ID**, use `CardholderDocument`. Do not use it for the shopper's account/profile document field — that is a different, identity-step component this block never composes with or reads from.
+If the image shows a **card-entry form with one extra plain text field formatted like a tax ID (CPF, SSN, SIN or RFC)**, use `CardholderDocument`. Do not use it for the shopper's account/profile document field — that is a different, identity-step component this block never composes with or reads from.
 
 ---
 
@@ -28,7 +28,7 @@ If the image shows a **card-entry form with one extra plain text field formatted
 
 - The shopper's saved profile/identity document (a client-identity or user-profile field) → use the identity-step document component instead. `CardholderDocument` is a payment-time value, deliberately separate — it never reads or writes the stored profile document, because the epic's RFC records that the two may differ.
 - A generic, data-agnostic tax-document input with no server-driven presence/requiredness → use the `DocumentField` particle directly instead; `CardholderDocument` exists specifically to wire that particle to the selected payment method's validator.
-- More than one document type or country → out of scope today. Only CPF renders; see this component's own spec for the recorded deferral.
+- A business document (CNPJ, EIN, BN, the corporate RFC) → not offered; only the four person documents render.
 
 ---
 
@@ -50,7 +50,7 @@ Child order reflects visual order. There is no parent/child relationship for thi
 **Composition rules:**
 
 - Must be inside `PaymentSectionRoot` or `PaymentSectionController`. Outside either, it throws.
-- Renders `null` (no DOM at all) when the selected payment method's validator does not mark a document displayable, or when no method is selected yet. This is normal, not an error — most methods most of the time render nothing here.
+- Renders `null` (no DOM at all) when the selected payment method's validator does not mark a document displayable, when no method is selected yet, or when the store's country has no document type (an unlisted country, or no country data). This is normal, not an error — most methods most of the time render nothing here.
 - Also renders `null` 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]]) — whatever that method's own validator says. When the card comes back, the field re-seeds from the value already typed.
 - Takes no children; passing any is a no-op.
 
@@ -60,18 +60,20 @@ Child order reflects visual order. There is no parent/child relationship for thi
 
 ### CardholderDocument
 
-The field itself. Renders the `DocumentField` particle for CPF, with presence and requiredness resolved from `usePayment().selectedMethod.validator` (`documentDisplayable` / `documentRequired`) rather than from any prop.
+The field itself. Renders the `DocumentField` particle for the type `usePayment().countryDocumentType` resolves (`USA` SSN, `BRA` CPF, `CAN` SIN, `MEX` RFC), with presence and requiredness resolved from `usePayment().selectedMethod.validator` (`documentDisplayable` / `documentRequired`) rather than from any prop.
 
 | Prop | Type | Default | Notes |
 |------|------|---------|-------|
-| `label` | `string` | `'CPF'` | The field's visible label. |
-| `placeholder` | `string` | `'000.000.000-00'` | Shown in the empty input as a format hint. |
-| `errorMessage` | `string` | `'Invalid CPF'` | Shown inline when the typed value fails CPF check-digit validation on blur. |
+| `label` | `string` | the type's name (`SSN`, `CPF`, `SIN`, `RFC`) | The field's visible label. |
+| `placeholder` | `string` | the type's own (`000-00-0000`, `000.000.000-00`, `000-000-000`, `AAAA000000AAA`) | Shown in the empty input as a format hint. |
+| `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. |
 
-No `documentType` prop — this build supports CPF only. No `required` prop — requiredness is always read from the selected method's validator, never authored.
+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`, `draft`, and `setDraftDocument` off the ambient `payment` context that `PaymentSectionRoot` / `PaymentSectionController` already fetches for.
+**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.
+
+**Focus on refusal:** while the field is on screen and not `disabled`, it registers itself so that when `PlaceOrder` refuses an order because the document is missing or malformed, keyboard focus moves to the `<input>`. The reason stays in `PlaceOrder`'s existing alert. Focus moves only on the refused click, and never for a refusal the gateway returned. With the field absent or `disabled`, nothing moves.
 
 ---
 
@@ -98,7 +100,7 @@ No `documentType` prop — this build supports CPF only. No `required` prop —
 ## Common mistakes
 
 - **Nesting `CardholderDocument` inside `CardEntry`.** It is a sibling under the same `PaymentSectionRoot`, never a child — `CardEntry` does not accept children.
-- **Passing a `documentType`, `required`, `countryCode`, or `document` prop.** None exist. Document type is fixed to CPF; requiredness and presence are always read from the selected method's validator, never authored; the typed value is not a prop at all — it flows into the shared payment draft internally.
+- **Passing a `documentType`, `required`, `countryCode`, or `document` prop.** None exist. The document type follows the store's country; requiredness and presence are always read from the selected method's validator, never authored; the typed value is not a prop at all — it flows into the shared payment draft internally.
 - **Using this component for the shopper's saved profile document.** That is a different, identity-step field this component never reads from or writes to — the two are intentionally separate, even for the same shopper.
 - **Expecting it to render outside a `PaymentSectionRoot` / `PaymentSectionController`.** It throws — the same requirement every other payment leaf (`CardEntry`, `Installments`, `SavedCards`, …) has.
 - **Treating a blank render as broken.** Most of the time, for most payment methods, this component correctly renders nothing — that is the "not displayable" state, not a bug.
@@ -107,7 +109,7 @@ No `documentType` prop — this build supports CPF only. No `required` prop —
 
 ## Known limitations
 
-- **CPF only.** The underlying read model carries no document-type or country signal (see this component's own spec for the full, measured deferral) — a store outside Brazil cannot get a different document type from this component today.
+- **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.
 
 ---

package/dist/docs/cart-item.md

@@ -53,7 +53,7 @@ CartItemRoot
 
 **It names itself from what it wraps.** The link adds no `aria-label`, so its accessible name is the image's alt text (`image.altText ?? variant.name`). On a line whose `variant.image` is `null` the leaf renders its children unwrapped instead of wrapping nothing, because an anchor with no content is a keyboard focus stop with no accessible name.
 
-**No usable product URL, no link.** The leaf runs `detailUrl` through `resolveSafeHref`, the same allowlist the navigation particle applies to CMS-authored destinations, and renders its children unwrapped when the destination is blank or refused: `javascript:`, `data:`, protocol-relative, or malformed. The particle gates only `$content.href`, so a platform URL arriving on the `href` prop is this leaf's to validate. Either way the image still shows: the leaf never self-hides, unlike the data-bearing leaves below, because hiding a wrapper would take its content with it. A refusal logs its reason and never the value; a blank URL is ordinary and stays quiet.
+**No usable product URL, no link.** The leaf runs `detailUrl` through `resolveSafeHref`, the same allowlist the navigation particle applies to CMS-authored destinations, and renders its children unwrapped when the destination is blank or refused: `javascript:`, `data:`, protocol-relative, or malformed. A safe `detailUrl` is a logical path: `NavigationLink` prefixes it for the current binding. The particle gates only `$content.href`, so a platform URL arriving on the `href` prop is this leaf's to validate. Either way the image still shows: the leaf never self-hides, unlike the data-bearing leaves below, because hiding a wrapper would take its content with it. A refusal logs its reason and never the value and still renders the children unwrapped; a blank URL is ordinary and stays quiet.
 
 Navigation is client-side through the `NavigationLink` particle, which also owns `rel` hardening. The link is same-tab, and `target` is omitted from the props type rather than merely left out of the schema, because an image-only link cannot carry the "(opens in new tab)" cue a `_blank` destination needs.
 

package/dist/docs/cart.md

@@ -65,7 +65,7 @@ What happens after a successful add to cart is a **per-store choice made by comp
 
 - **Mini-cart store → `CartOpenOnAdd`.** When the store has a mini-cart drawer, compose `CartOpenOnAdd` as the **parent of the mini-cart `DrawerRoot`** (its single child). It opens the drawer automatically on each successful add, with the new item visible and the count updated. It controls the drawer internally, so **do not set raw `open` / `onOpenChange` on `DrawerRoot`** — those are not authorable props, and the header `DrawerTrigger` plus manual close (Escape / backdrop / close button) keep working through the encapsulated wiring.
 
-- **No-mini-cart store → `CartRedirectOnAdd`.** When the store has **no** mini-cart and adding a product should send the shopper straight to checkout, compose `CartRedirectOnAdd` (and omit the drawer entirely). It navigates to `href` (default `/checkout`) after each successful add. It renders no UI of its own; place it once in the layout.
+- **No-mini-cart store → `CartRedirectOnAdd`.** When the store has **no** mini-cart and adding a product should send the shopper straight to checkout, compose `CartRedirectOnAdd` (and omit the drawer entirely). It navigates to `href` (default the checkout page, `{ "standard": "checkout" }`) after each successful add. It renders no UI of its own; place it once in the layout.
 
 The two are **mutually exclusive — compose exactly one**. A store with a mini-cart uses `CartOpenOnAdd` and never `CartRedirectOnAdd`; a store without one uses `CartRedirectOnAdd` and omits the drawer. Both react only to a **successful** add (a failed add or one returning user errors triggers neither).
 
@@ -87,7 +87,7 @@ CartRoot (layout)
 ```
 CartRoot (layout)
 ├── Header (add-to-cart CTAs elsewhere; no drawer)
-└── CartRedirectOnAdd          ← navigates to /checkout on a successful add
+└── CartRedirectOnAdd          ← navigates to the checkout page on a successful add
 ```
 
 ---
@@ -230,7 +230,7 @@ Neither leaf renders a wrapper or carries spacing, so **order, grouping, and any
 Continue-shopping is a **non-mutating** control, not a cart action. Which control depends on the surface:
 
 - **Inside the mini-cart drawer**, use `CartContinueShopping` — it closes the drawer through the drawer's own contract and dispatches no cart write.
-- **On a cart or checkout page** (no drawer to close), use a storefront `NavigationLink` (e.g. `href="/"`) back to browsing. Do **not** place `CartContinueShopping` there: it is a drawer close, and without a `DrawerRoot` ancestor the render fails.
+- **On a cart or checkout page** (no drawer to close), use a storefront `NavigationLink` (e.g. `href={{ page: 'home' }}`) back to browsing. Do **not** place `CartContinueShopping` there: it is a drawer close, and without a `DrawerRoot` ancestor the render fails.
 
 ```text
 CartRoot (layout)
@@ -259,7 +259,7 @@ CartRoot (layout)
   "popup-body": { "type": "CartList", "children": ["cart-item-template"] },
   "subtotal-row": { "type": "CartTotal", "props": { "label": "subtotal" } },
   "total-row": { "type": "CartTotal", "props": { "label": "total" } },
-  "checkout-btn": { "type": "CartGoCheckout", "props": { "href": "/checkout", "children": "continuar" } },
+  "checkout-btn": { "type": "CartGoCheckout", "props": { "href": { "standard": "checkout" }, "children": "continuar" } },
 
   "cart-empty": { "type": "CartEmpty", "children": ["empty-illustration", "empty-msg", "empty-footer"] },
   "empty-illustration": { "type": "Icon", "props": { "name": "shopping-bag" } },
@@ -275,7 +275,7 @@ On a cart/checkout page there is no drawer to close, so the empty branch keeps `
 {
   "cart-empty": { "type": "CartEmpty", "children": ["empty-msg", "keep-shopping-link"] },
   "empty-msg": { "type": "CartEmptyMessage", "props": { "text": "sua cesta está vazia" } },
-  "keep-shopping-link": { "type": "NavigationLink", "props": { "href": "/", "children": "continuar comprando" } }
+  "keep-shopping-link": { "type": "NavigationLink", "props": { "href": { "page": "home" }, "children": "continuar comprando" } }
 }
 ```
 
@@ -307,7 +307,7 @@ The mini-cart drawer (the layout composition described on `CartRoot`) ends in a
 
 - **`CartCheckoutGuard`** is the outer wrapper. It reads cart availability and, while any line item is not `AVAILABLE`, makes its whole subtree non-interactive (`inert` + `aria-disabled`) and exposes `data-fs-cart-checkout-blocked` for styling the disabled state. The shopper cannot proceed with an undeliverable item. It updates reactively from cache — no refetch, no reload — so the block clears the moment the offending line is removed or becomes available.
 - **`CartTotal`** sits inside the guard, on or next to the button, so the grand total the shopper is about to pay is visible at the CTA. It reads the nearest `CartRoot`/`CartTotalizerRoot` and reformats reactively on every cart change.
-- **`CartGoCheckout`** is the link to checkout (default `href` `/checkout`). During a **client-side** route transition it surfaces a loading state on its content wrapper — `aria-busy` plus `data-fs-cart-go-checkout-pending` — so the shopper sees the click registered. There is **no built-in spinner**: opt into one by styling that attribute (or composing a `Spinner` on it). For an **external or hard** checkout navigation (a non-Next route, a different origin, or a full page load — common for the real VTEX checkout) there is no client-side transition window, so the loading state simply does not show. That is the documented, graceful no-op, not a bug.
+- **`CartGoCheckout`** is the link to checkout (default `href` the checkout page, `{ "standard": "checkout" }`). During a **client-side** route transition it surfaces a loading state on its content wrapper — `aria-busy` plus `data-fs-cart-go-checkout-pending` — so the shopper sees the click registered. There is **no built-in spinner**: opt into one by styling that attribute (or composing a `Spinner` on it). For an **external or hard** checkout navigation (a non-Next route, a different origin, or a full page load — common for the real VTEX checkout) there is no client-side transition window, so the loading state simply does not show. That is the documented, graceful no-op, not a bug.
 
 **The button wording is CMS content.** It resolves in a fixed order: the `cart-checkout-label` entry, then the `label` prop, then `children`, then the package default `"Checkout"`. So a merchant rewords the CTA — `"Finalizar compra"`, `"Ir para o pagamento"` — with a CMS save and no deployment, while a store with no CMS binding renders its authored value. `children` stays supported because that is where stores labelled the button before `label` existed; a CMS entry overrides it with no schema edit. A blank or whitespace-only entry value counts as unconfigured and falls through. Non-compiler hosts (Storybook, tests) pass a typed `$content` fixture directly.
 
@@ -315,7 +315,7 @@ The mini-cart drawer (the layout composition described on `CartRoot`) ends in a
 
 | Prop | Type | Required | Notes |
 |-------|------|----------|-------|
-| `href` | string | no | Checkout destination, default `/checkout`. Never content-editable |
+| `href` | page reference or string | no | Checkout destination, default `{ "standard": "checkout" }`. A string is a logical path or an off-site URL. Never content-editable |
 | `label` | string | no | Authored fallback for the wording. Ignored when an entry supplies a label |
 | `children` | node | no | Legacy label channel, still honoured. Element children are replaced when an entry supplies a label |
 
@@ -332,7 +332,7 @@ Schema shape (inside the `DrawerPopup` footer `Container`):
   "popup-footer": { "type": "Container", "children": ["checkout-cta"] },
   "checkout-cta": { "type": "CartCheckoutGuard", "children": ["checkout-total", "checkout-btn"] },
   "checkout-total": { "type": "CartTotal", "props": { "label": "Total" } },
-  "checkout-btn": { "type": "CartGoCheckout", "props": { "href": "/checkout", "label": "Finalizar compra" } }
+  "checkout-btn": { "type": "CartGoCheckout", "props": { "href": { "standard": "checkout" }, "label": "Finalizar compra" } }
 }
 ```
 

package/dist/docs/client-profile-fieldset.md

@@ -1,7 +1,7 @@
 # ClientProfileFieldset
 
 **Category:** identity
-**Purpose:** The composable, one-Save write of the `ClientProfile` entity. Registers itself with the enclosing `FormRoot` under the `clientProfile` namespace and dispatches at most one `identity.clientProfileUpdate` when the shopper presses that form's submit. Four bound controls — first name, last name, phone, document — compose freely inside it, in any order or subset.
+**Purpose:** The composable, one-Save write of the `ClientProfile` entity. Registers itself with the enclosing `FormRoot` under the `clientProfile` namespace and dispatches at most one `identity.clientProfileUpdate` when the shopper presses that form's submit. Four bound controls — first name, last name, phone, document (CPF, SSN, SIN or RFC) — compose freely inside it, in any order or subset.
 
 ---
 
@@ -65,7 +65,7 @@ SessionRoot                              (required ancestor; session tri-state +
 | Prop | Type | Default | Notes |
 |------|------|---------|-------|
 | `country` | `'US' \| 'BR'` | `'US'` | Phone mask/validation country, provided to the phone control via context. |
-| `documentType` | string | — | e.g. `'CPF'`. The document control renders only when supported. |
+| `documentType` | string | — | One of `'CPF'`, `'SSN'`, `'SIN'` or `'RFC'` (upper case). The document control renders only when supported, and the payload carries `document` only for a supported type. |
 | `skeletonCount` | number | `4` | Placeholder rows drawn while the profile resolves. Set it to the number of controls composed. |
 | `loadingLabel` | string | `'Loading your details'` | Announced politely while the profile resolves. Blank means no announcement. |
 | `loadedLabel` | string | `'Your details are ready'` | Announced politely once the controls mount. Blank means no announcement. |
@@ -105,12 +105,14 @@ governs visibility (see *Switching the phone field off* below).
 
 | Prop | Type | Default | Notes |
 |------|------|---------|-------|
-| `label` | string | `'CPF'` | |
+| `label` | string | the document type's name (`'CPF'`, `'SSN'`, `'SIN'` or `'RFC'`) | |
 | `placeholder` | string | — | |
 | `errorMessage` | string | — | |
 
-Renders nothing, and registers no field name, when the fieldset's `documentType` is unsupported. Composes
-the `DocumentField` particle. Recomposable (RFC:503): given children, they replace `DocumentField`'s
+Renders nothing, and registers no field name, when the fieldset's `documentType` is unsupported. The mask,
+the validation and the `autocomplete` hint (`off` for SSN and SIN) come from the document type; the saved
+`document` string is the type's sanitised value (digits for CPF, SSN and SIN, letters kept for RFC), the
+same string the card form sends. Composes the `DocumentField` particle. Recomposable (RFC:503): given children, they replace `DocumentField`'s
 default `Field.Label` + `DocumentFieldInput` + `Field.Error` anatomy, in any order; childless keeps
 today's order and text.
 

package/dist/docs/copy-text.md

@@ -0,0 +1,84 @@
+# CopyText
+
+**Category:** action
+**Purpose:** Copies one string the caller supplies and confirms the result inline.
+
+---
+
+## Visual cues (how to identify in an image)
+
+A small action beside an identifier, with a short confirmation that appears after the action and can be dismissed. The image is the source of truth for layout.
+
+## When to use
+
+Any screen that needs one action to copy a single string, such as an order number.
+
+## When NOT to use
+
+- Rendering the identifier itself. Pass the string in; do not ask `CopyText` to display the heading.
+- A toast or a page-level notification. The confirmation stays with the action.
+
+---
+
+## Composition
+
+```
+CopyText
+```
+
+`CopyText` is one element. The caller passes the visible label or icon as `children`.
+
+## Components
+
+### CopyText
+
+| Prop | Type | Default | Purpose |
+|---|---|---|---|
+| `accessibleName` | string | `Copy` | Accessible name of the action |
+| `successMessage` | string | `Copied` | Announced after a successful copy |
+| `failureMessage` | string | `Could not copy` | Announced when the clipboard rejects the write |
+| `dismissLabel` | string | `Dismiss` | Accessible name of the dismiss control |
+
+`text` is required and is not a schema prop. The caller supplies the exact string to copy. `children` is the visible label or icon, and it is not a schema prop either.
+
+---
+
+## Canonical schema example
+
+```json
+{
+  "copy-identifier": {
+    "type": "CopyText",
+    "props": {
+      "accessibleName": "Copy order number",
+      "successMessage": "Copied",
+      "failureMessage": "Could not copy",
+      "dismissLabel": "Dismiss"
+    },
+    "children": []
+  }
+}
+```
+
+The screen that owns the identifier passes `text` and `children` at runtime. Do not author the identifier in the page.
+
+## Common mistakes
+
+- **OrderDetailsHeader** renders the number. `CopyText` only copies the string it is given.
+- Passing the heading, including a prefix such as "Order #", copies that whole string. Pass the identifier alone.
+
+---
+
+## Styling
+
+| Component | What to style | Plausible classes |
+|---|---|---|
+| `CopyText` | The action and the inline confirmation | `inline-flex items-center gap-[8px] text-[14px]` |
+
+Style the hooks `data-fs-copy-text`, `data-fs-copy-text-action`, `data-fs-copy-text-message`, and `data-fs-copy-text-outcome`. The component ships no CSS.
+
+---
+
+## Related
+
+- [[button]] — the action primitive this control composes.

package/dist/docs/document-field.md

@@ -1,14 +1,14 @@
 # DocumentField
 
 **Category:** content
-**Purpose:** A presentational tax-document input that composes the `Field` particle (label + native `<input>` + inline error). It applies a locale-specific mask on every change (e.g. CPF `###.###.###-##`) and runs check-digit validation on blur/submit. It is data-agnostic — value flows through props; it consumes no GraphQL and no domain context.
+**Purpose:** A presentational tax-document input that composes the `Field` particle (label + native `<input>` + inline error). It applies the mask of its document type on every change (CPF `###.###.###-##`, SSN `###-##-####`, SIN `###-###-###`, or RFC, thirteen upper-case letters and digits) and runs that type's validation on blur/submit. It is data-agnostic — value flows through props; it consumes no GraphQL and no domain context.
 
 ---
 
 ## Visual cues (how to identify in an image)
 
-- A single-line text input labelled **"CPF"** (or another tax-document name), usually on a checkout identification step, near the email/phone fields.
-- Shows a masked placeholder like `000.000.000-00` and formats digits as they are typed.
+- A single-line text input labelled **"CPF"**, **"SSN"**, **"SIN"** or **"RFC"** (or another tax-document name), usually on a checkout identification step, near the email/phone fields.
+- Shows a masked placeholder like `000.000.000-00` (CPF), `000-00-0000` (SSN), `000-000-000` (SIN) or `AAAA000000AAA` (RFC) and formats characters as they are typed.
 - When invalid, an inline error below the input (e.g. *"Enter a valid CPF."*).
 
 If the image shows a checkout identification step with a tax-document field, use `DocumentField`.
@@ -61,15 +61,15 @@ react-hook-form and loses the mask — unsupported, the RFC's named double-binde
 | `label` | string | — | Accessible label. |
 | `placeholder` | string | — | Input placeholder. |
 | `disabled` | boolean | `false` | Disables the input (e.g. while a write is in flight). |
-| `requirement` | `'mandatory' \| 'optional'` | — | Raises the field to required, announced as `aria-required` (never the native attribute). Unset is no opinion, which is what keeps CPF Optional by Recommendation, unlike email. Bound to a fieldset whose rule already says required, `'optional'` does not lower it. |
+| `requirement` | `'mandatory' \| 'optional'` | — | Raises the field to required, announced as `aria-required` (never the native attribute). Unset is no opinion, which is what keeps the document Optional by Recommendation, unlike email. Bound to a fieldset whose rule already says required, `'optional'` does not lower it. |
 | `name` | string | `'document'` | Field/input name. |
-| `documentType` | `'CPF'` | `'CPF'` | Selects the mask + validator + digit-only input mode. |
+| `documentType` | `'CPF' \| 'SSN' \| 'SIN' \| 'RFC'` | `'CPF'` | Selects the mask, sanitiser, validator, digit-only input mode and `autocomplete`. `DOCUMENTS` holds one entry per type; the API's lower-case ids (`cpf`, `ssn`, `sin`, `rfc`) go through `documentTypeFromId`. |
 | `ref` | `Ref<HTMLInputElement>` | — | Lands on the `<input>` `Field.Control` renders — **not on the wrapper `<div>`, as it did before** (a deliberate, source-breaking change). Composed with react-hook-form's own ref on the bound path — a caller ref and react-hook-form's ref are both honoured. |
 | `children` | `ReactNode` | — | Given, replaces the default `Field.Label` + `DocumentFieldInput` + `Field.Error` anatomy, in any order (RFC:503). |
 
-**Masking:** applied progressively on every change; input is never blocked. Digit-only masks (CPF) strip non-digits and hint `inputMode="numeric"`.
+**Masking:** applied progressively on every change; input is never blocked. The type's sanitiser runs first: digit-only types (CPF, SSN, SIN) strip non-digits and hint `inputMode="numeric"`; RFC upper-cases and keeps only `A-Z` and `0-9`, and carries no `inputMode`. SSN and SIN inputs carry `autocomplete="off"` so the browser does not offer the number back; CPF and RFC carry no `autocomplete` attribute. The attribute is a request, not a guarantee.
 
-**Validation:** the check digit is checked on blur/submit only — never per keystroke. An **empty** value is valid (the field is optional). A prior error clears while the shopper edits and is re-evaluated on the next blur.
+**Validation:** the type's rule (CPF check digits; SSN area, group and serial ranges; SIN Luhn check; RFC structure with a plausible month and day) is checked on blur/submit only — never per keystroke. An **empty** value is valid (the field is optional). A prior error clears while the shopper edits and is re-evaluated on the next blur.
 
 ---
 
@@ -82,7 +82,7 @@ runs the plain, unbound behaviour documented above, unaltered.
 - **What the contract supplies**: `label` and `placeholder`, when the particle's own prop is omitted (an
   explicit prop always wins); `defaultValue`, seeded into `useController`; and `rule`, merged with the
   particle's own check-digit validator (below).
-- **What stays the particle's**: the CPF mask, `documentType`, and the `errorMessage` copy.
+- **What stays the particle's**: the mask of the `documentType`, the `documentType` itself, and the `errorMessage` copy.
 - **Single binder, real contract for the read-only parts (RFC:503)**: the composite remains the sole
   binder for its field — `useController` is called once, here. Its default (and a recomposed) anatomy's
   input is `DocumentFieldInput`, which renders the raw Base UI `Field.Control` directly rather than this

package/dist/docs/footer-link-group.md

@@ -58,7 +58,7 @@ It renders **both responsive forms at once**, each under its own hook: an accord
 | Prop | Type | Required | Notes |
 |-------|------|----------|-------|
 | `heading` | string | no | Authored fallback. Ignored when a CMS entry supplies a heading |
-| `links` | array | no | Authored fallback list of `{ label, href, target? }`. Ignored when a CMS entry supplies `links` |
+| `links` | array | no | Authored fallback list of `{ label, href, target? }`. An item `href` may be a page reference or a logical path. Ignored when a CMS entry supplies `links` |
 
 Content model (`footer-link-group`) fields, edited in the CMS:
 
@@ -67,7 +67,7 @@ Content model (`footer-link-group`) fields, edited in the CMS:
 | `heading` | string | no | The group heading and the accordion trigger's accessible name. Optional so a links-only entry falls back to the authored heading instead of omitting the group. A group with no heading resolved from either channel renders nothing |
 | `links` | array | no | Ordered links. Reordering here reorders the rendered list with no deployment. Optional so a heading-only entry falls back to the authored list instead of omitting the group |
 | `links[].label` | string | yes | Link text. A blank label drops that link — an anchor with no name is unusable |
-| `links[].href` | string | yes | Destination. `http:`, `https:`, `mailto:`, `tel:`, or a path starting with a single `/` |
+| `links[].href` | string | yes | A `uri-reference` string: `http:`, `https:`, `mailto:`, `tel:`, or a path starting with a single `/`. The binding prefix is applied at render |
 | `links[].target` | `_self` \| `_blank` | no | `_blank` opens a new tab and adds `rel="noopener noreferrer"` automatically |
 
 ---

package/dist/docs/header-root.md

@@ -80,7 +80,7 @@ A layout whose root holds a `HeaderRoot` and the page `Slot` beside it, with a l
   },
   "header-logo": {
     "type": "Logo",
-    "props": { "src": "/logo.svg", "alt": "Loja XYZ", "href": "/" }
+    "props": { "src": "/logo.svg", "alt": "Loja XYZ", "href": { "page": "home" } }
   },
   "header-nav": {
     "type": "NavigationMenuRoot",

package/dist/docs/incentives.md

@@ -64,7 +64,7 @@ FooterRoot
 
 | Prop | Type | Required | Notes |
 |-------|------|----------|-------|
-| `items` | array | no | Authored fallback list of `{ title, firstLineText?, secondLineText?, href?, icon?, iconUrl?, alt? }`. Ignored when a CMS entry supplies `items` |
+| `items` | array | no | Authored fallback list of `{ title, firstLineText?, secondLineText?, href?, icon?, iconUrl?, alt? }`. An item `href` may be a page reference or a logical path. Ignored when a CMS entry supplies `items` |
 
 Content model (`incentives`) fields, edited in the CMS:
 
@@ -74,7 +74,7 @@ Content model (`incentives`) fields, edited in the CMS:
 | `items[].title` | string | yes | The benefit's short bold label. The only required field per item; a blank one drops that item |
 | `items[].firstLineText` | string | no | The first line of supporting copy. Optional, so a title-only item is legal; a blank one renders no line |
 | `items[].secondLineText` | string | no | The second line. Absent or blank renders no element, so an item shows zero, one, or two lines |
-| `items[].href` | string | no | The block's destination. Optional, because a benefit strip links nowhere and a shortcut row links everywhere. Wraps the whole block — glyph included — in a same-tab link. Absent or blank renders the item unlinked; a value the render-time allowlist refuses also renders it unlinked, keeping the glyph and copy |
+| `items[].href` | string | no | A `uri-reference` string. Optional, because a benefit strip links nowhere and a shortcut row links everywhere. Wraps the whole block — glyph included — in a same-tab link. Absent or blank renders the item unlinked; a value the render-time allowlist refuses also renders it unlinked, keeping the glyph and copy. A safe string receives the binding prefix at render |
 | `items[].icon` | enum | no | One of `truck`, `calendar`, `gift`, `store`, `shield-check`. Renders the collection glyph, decorative |
 | `items[].iconUrl` | string | no | An uploaded image, for a benefit the predefined set has no glyph for. Wins over `icon` when both are set |
 | `items[].alt` | string | no | Alt text for an uploaded image. Defaults to empty, keeping the image decorative — the visible title beside it is already the item's accessible content, so repeating it would announce the same words twice |