@vtex/faststore 0.0.8 → 0.0.11

package/dist/docs/account-saved-cards.md

@@ -0,0 +1,306 @@
+# Account Saved Cards
+
+**Category:** identity
+**Purpose:** The signed-in shopper's saved cards in their account: a list of card summaries, or a statement that there are none, with loading and failure states, and a confirmed removal for each card. Needs no cart.
+
+---
+
+## Visual cues (how to identify in an image)
+
+- A section heading such as "Saved cards", "Payment methods", or "My cards" inside an account page.
+- A vertical list of rows, each a card-network logo, a network name, and `•••• 1234`, with a line such as "Expires 05/28" under it.
+- A dimmed row reading "Expired 05/24" or "This card can't be used".
+- A "Remove" link or button in each row, opening a confirmation such as "Remove this card?" with Cancel and "Remove card".
+- Or a single sentence such as "You have no saved cards yet." where the list would be.
+- Usually beside the account's side navigation, never inside a checkout step.
+
+The image is the source of truth for layout.
+
+## When to use
+
+- Showing the shopper the cards saved to their account, outside any purchase: the account's Payments page, or a block inside another account page.
+
+## When NOT to use
+
+- Picking a saved card to pay with during checkout → [[saved-cards]] (`SavedCards`, cart-scoped, with CVV entry).
+- Describing one card on its own → [[card-summary]].
+- The store's accepted payment methods as a strip of logos → [[payment-methods]].
+
+---
+
+## Composition
+
+```
+AccountSavedCardsRoot             ← requires 'session'; provides 'account-saved-cards'; declares savedCard.remove
+├── AccountSavedCardsHeading
+├── AccountSavedCardsRemoveFeedback
+├── AccountSavedCardsLoading
+├── AccountSavedCardsError
+├── AccountSavedCardsEmpty
+└── AccountSavedCardsList         ← provides 'account-saved-card'
+    └── AccountSavedCardItem      ← one row per card; provides 'card-summary', 'account-saved-card-data'
+        ├── CardSummary
+        ├── AccountSavedCardExpiry
+        └── AccountSavedCardRemove ← provides 'account-saved-card-remove'
+            └── AlertDialogRoot
+                ├── AccountSavedCardRemoveTrigger
+                └── AlertDialogPortal > AlertDialogBackdrop + AlertDialogViewport > AlertDialogPopup
+                    ├── AccountSavedCardRemoveTitle
+                    ├── AccountSavedCardRemoveDescription
+                    ├── AccountSavedCardRemoveCancel
+                    └── AccountSavedCardRemoveConfirm
+```
+
+The Root renders nothing unless the session is `loggedIn`, and no chrome: no navigation, no page title, no landmark. It derives one state and exposes it on `data-fs-account-saved-cards-state`:
+
+| State | When | Renders |
+|---|---|---|
+| `loading` | No cards yet and the read is in flight | `AccountSavedCardsLoading` |
+| `error` | No cards and the read failed | `AccountSavedCardsError` |
+| `empty` | The read resolved with no card | `AccountSavedCardsEmpty` |
+| `ready` | The read resolved with cards | `AccountSavedCardsList` |
+| `idle` | No cards and nothing in flight | Nothing but the heading |
+
+The heading and the removal feedback render in every state. Every part except the Item must be inside the Root; the Item must be inside the List; the CardSummary parts, `AccountSavedCardExpiry`, and `AccountSavedCardRemove` inside the Item; and the five prompt parts inside `AccountSavedCardRemove`. A part outside its provider fails the build with a `ContextConstraintError`.
+
+---
+
+## Components
+
+### AccountSavedCardsRoot
+
+Reads the card ids (`customerSavedCards`, reactive) and publishes the section state. No schema props.
+
+It also holds the section's removal: which card is being removed (one at a time) and how the last removal ended. It declares `actions: { savedCard: ['remove'] }`, so every remove control inside reaches the action.
+
+### AccountSavedCardsHeading
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| `as` | `'h2' \| 'h3' \| 'h4' \| 'h5' \| 'h6'` | `h2` | No `h1`: the page title belongs to the page shell. |
+
+### AccountSavedCardsLoading
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| `skeletonCount` | number | `2` | Placeholder rows (`data-fs-account-saved-cards-loading-row`), hidden from assistive technology. |
+
+A polite live region (`data-fs-account-saved-cards-loading-announcement`) stays mounted and announces the wait.
+
+### AccountSavedCardsError
+
+An alert. An expired session (`UNAUTHORIZED`) says so and links to sign-in (`data-fs-account-saved-cards-sign-in`), returning the shopper to the current page; any other failure says the cards could not be loaded. `data-fs-account-saved-cards-error-code` is `unauthorized` or `failed`. The server's message never renders. Children replace the message for every failure and drop the link.
+
+### AccountSavedCardsEmpty
+
+The statement that no card is saved. Renders only once the read resolved with none.
+
+### AccountSavedCardsList
+
+A `<ul>` repeating its child once per card.
+
+### AccountSavedCardItem
+
+A `<li>` that provides its card to the CardSummary parts, `AccountSavedCardExpiry`, and `AccountSavedCardRemove`. It renders only its children; with none, the row is empty. It shows no label: the account's read does not return one.
+
+An expired card's row carries `data-fs-account-saved-card-expired`, and an unusable one's `data-fs-account-saved-card-unusable`, so a swatch can dim it. A working card's row carries neither. While its card is being removed, the row carries `data-fs-account-saved-card-removing`. Compose `CardSummary`, `AccountSavedCardExpiry` and `AccountSavedCardRemove` as children, in the order the row needs. Leave `AccountSavedCardRemove` out only for a read-only list.
+
+### AccountSavedCardExpiry
+
+The line that says when the card expires, from the API's `status` and `expiry`. No schema props and no children.
+
+| Card | Line | `data-fs-account-saved-card-expiry-status` |
+|---|---|---|
+| Working, with a date | "Expires 05/28" | `usable` |
+| Expired, with a date | "Expired 05/24" | `expired` |
+| Expired, no date | "Expired" | `expired` |
+| Unusable (any other status) | "This card can't be used", never a date | `unusable` |
+| Working, no date | Nothing | — |
+
+The label is in `data-fs-account-saved-card-expiry-label`, the `MM/YY` date in `data-fs-account-saved-card-expiry-date` (a `<time>`). The short date is hidden from assistive technology; a visually hidden span reads the month and year in full ("May 2028") in the store's locale. A month outside 1–12 or a year outside four digits counts as no date.
+
+### AccountSavedCardRemove
+
+The controller for one row's removal prompt. It owns the prompt's open state and passes it to its single `AlertDialogRoot` child; the schema never sets `open`. With no children it renders nothing. No schema props.
+
+Opening the prompt dispatches nothing. Confirm dispatches `savedCard.remove` with the row's card id. The prompt then stays open until the server answers, and Escape and Cancel cannot close it meanwhile. On success the row leaves the list, and the prompt goes with it. On failure the prompt closes, focus returns to the trigger, and the row stays. An expired or unusable card is removed like any other.
+
+### AccountSavedCardRemoveTrigger
+
+The row's control that opens the prompt. Its visible text is short ("Remove"); a visually hidden span adds the card ("Visa ending in 1234"), so each trigger has its own accessible name. Disabled while any removal in the section is pending.
+
+### AccountSavedCardRemoveTitle, AccountSavedCardRemoveDescription
+
+The prompt's title and accessible description. With no children, the description renders the card's `CardSummary` before its text, so the prompt names the card it removes; that `CardSummary` reads the description's `cardEndingIn` message as its `endingIn`.
+
+### AccountSavedCardRemoveCancel
+
+Closes the prompt and keeps the card. Opened with a mouse or the keyboard, the prompt focuses it first, so the safe action is the default; opened by touch, the popup takes focus itself. Disabled while the removal is pending.
+
+### AccountSavedCardRemoveConfirm
+
+Removes the card. While the removal is pending it carries `aria-disabled="true"`, `aria-busy="true"`, and `data-fs-account-saved-card-remove-confirm-pending`, and shows its pending text ("Removing…"). It stays focusable, so focus does not leave the prompt.
+
+### AccountSavedCardsRemoveFeedback
+
+Tells the shopper how the last removal ended. Place it once in the Root, outside the list, because a removed card's row unmounts. No schema props and no children.
+
+| Outcome | Renders | `data-fs-account-saved-cards-remove-feedback-outcome` |
+|---|---|---|
+| Removed | "The card was removed." in a polite status region, which takes focus | `removed` |
+| Session expired (`UNAUTHORIZED`) | An alert saying so, with a sign-in link (`data-fs-account-saved-cards-remove-feedback-sign-in`) that returns to the page | `unauthorized` |
+| Any other failure | An alert: "We couldn't remove the card. Please try again." | `failed` |
+| None yet, or a new removal started | Nothing | — |
+
+The status region stays mounted so screen readers announce it. No message disappears on its own, and the server's message never renders.
+
+## Text
+
+Every text is `children` or else the part's own message field (`$content`). A missing message, absent or blank, renders empty and logs an error; no part falls back to other text.
+
+| Part | Message fields |
+|---|---|
+| `AccountSavedCardsHeading` | `text` |
+| `AccountSavedCardsEmpty` | `text` |
+| `AccountSavedCardsLoading` | `text` |
+| `AccountSavedCardsError` | `text`, `sessionExpiredText`, `signInLabel` |
+| `AccountSavedCardExpiry` | `expiresLabel`, `expiredLabel`, `expiredText`, `unusableText` |
+| `CardSummary` | `endingIn` (`lastDigits`) |
+| `AccountSavedCardRemoveTrigger` | `text`, `cardEndingIn` (`lastDigits`) |
+| `AccountSavedCardRemoveTitle` | `text` |
+| `AccountSavedCardRemoveDescription` | `text`, `cardEndingIn` (`lastDigits`) |
+| `AccountSavedCardRemoveCancel` | `text` |
+| `AccountSavedCardRemoveConfirm` | `text`, `pendingText` |
+| `AccountSavedCardsRemoveFeedback` | `successText`, `failureText`, `sessionExpiredText`, `signInLabel` |
+
+Every field is an ICU message (`format: 'icu-message'`). The trigger's hidden card name is the card's name followed by its `cardEndingIn` message.
+
+`AccountSavedCardExpiry` and `AccountSavedCardsRemoveFeedback` take no children. `expiresLabel` and `expiredLabel` precede the date, which the component always places; `expiredText` and `unusableText` stand alone. The trigger's hidden card name follows its text whatever the source. Children on the Confirm replace only its idle label. Only a part placed in the schema has `$content`, so the Item and `AccountSavedCardRemove` have no default parts. The `CardSummary` that `AccountSavedCardRemoveDescription` renders with no children is the exception: the description passes it its own `cardEndingIn` message.
+
+## Canonical schema example
+
+```json
+{
+  "saved-cards": {
+    "type": "AccountSavedCardsRoot",
+    "children": [
+      "saved-cards-heading",
+      "saved-cards-remove-feedback",
+      "saved-cards-loading",
+      "saved-cards-error",
+      "saved-cards-empty",
+      "saved-cards-list"
+    ]
+  },
+  "saved-cards-heading": { "type": "AccountSavedCardsHeading" },
+  "saved-cards-remove-feedback": { "type": "AccountSavedCardsRemoveFeedback" },
+  "saved-cards-loading": { "type": "AccountSavedCardsLoading" },
+  "saved-cards-error": { "type": "AccountSavedCardsError" },
+  "saved-cards-empty": { "type": "AccountSavedCardsEmpty" },
+  "saved-cards-list": { "type": "AccountSavedCardsList", "children": ["saved-card-item"] }
+}
+```
+
+Nested inside another account page, with a lower heading:
+
+```json
+{
+  "saved-cards-heading": { "type": "AccountSavedCardsHeading", "props": { "as": "h3" } }
+}
+```
+
+The row, composed part by part, since the Item and `AccountSavedCardRemove` render only their children:
+
+```json
+{
+  "saved-card-item": {
+    "type": "AccountSavedCardItem",
+    "children": ["saved-card-summary", "saved-card-expiry", "saved-card-remove"]
+  },
+  "saved-card-summary": { "type": "CardSummary" },
+  "saved-card-expiry": { "type": "AccountSavedCardExpiry" },
+  "saved-card-remove": { "type": "AccountSavedCardRemove", "children": ["saved-card-remove-dialog"] },
+  "saved-card-remove-dialog": {
+    "type": "AlertDialogRoot",
+    "children": ["saved-card-remove-trigger", "saved-card-remove-portal"]
+  },
+  "saved-card-remove-trigger": { "type": "AccountSavedCardRemoveTrigger" },
+  "saved-card-remove-portal": {
+    "type": "AlertDialogPortal",
+    "children": ["saved-card-remove-backdrop", "saved-card-remove-viewport"]
+  },
+  "saved-card-remove-backdrop": { "type": "AlertDialogBackdrop" },
+  "saved-card-remove-viewport": { "type": "AlertDialogViewport", "children": ["saved-card-remove-popup"] },
+  "saved-card-remove-popup": {
+    "type": "AlertDialogPopup",
+    "children": [
+      "saved-card-remove-title",
+      "saved-card-remove-description",
+      "saved-card-remove-cancel",
+      "saved-card-remove-confirm"
+    ]
+  },
+  "saved-card-remove-title": { "type": "AccountSavedCardRemoveTitle" },
+  "saved-card-remove-description": { "type": "AccountSavedCardRemoveDescription" },
+  "saved-card-remove-cancel": { "type": "AccountSavedCardRemoveCancel" },
+  "saved-card-remove-confirm": { "type": "AccountSavedCardRemoveConfirm" }
+}
+```
+
+## Common mistakes
+
+- **`AccountSavedCards`, `SavedCardsList`, `MyCards`.** The Root is `AccountSavedCardsRoot`; the list is `AccountSavedCardsList`.
+- **Using `SavedCards` or `SavedCardOption` in the account.** Those are the checkout's cart-scoped picker and need a payment section.
+- **Using `AccountSavedCardRemove` or its parts in the checkout's saved-card list.** They need `AccountSavedCardsRoot` and read the `CustomerSavedCard` entity, which a checkout row is not. The checkout removes an expired card with `SavedCardRemove` inside `SavedCardOption` (see [[saved-cards]]), which calls the same `savedCard.remove` action with the account-side id.
+- **Placing `AccountSavedCardItem` directly in the Root.** It must be inside `AccountSavedCardsList`.
+- **Composing `AccountSavedCardsEmpty` as the only state part.** Compose Loading and Error too, or a slow or failed read shows nothing under the heading.
+- **Setting `as: "h1"`.** Not accepted; the page title belongs to the page shell.
+- **Leaving a message field blank.** Nothing falls back: the part renders that text empty and logs an error.
+- **Placing the Root outside the `my-account` layout.** It requires `session`; without a `SessionRoot` the build fails.
+- **Giving the Item custom children without `AccountSavedCardExpiry`.** The row then hides when the card expires and whether it can be used.
+- **Leaving an Item or `AccountSavedCardRemove` with no children.** Neither has a default: the row renders empty and the prompt never appears. Place `CardSummary`, `AccountSavedCardExpiry` and the `AccountSavedCardRemove` composition explicitly.
+- **Giving the Item custom children without `AccountSavedCardRemove`.** The shopper can no longer remove the card. Do it only for a read-only list.
+- **Leaving out `AccountSavedCardsRemoveFeedback`.** A removal then ends with no message: a success only drops the row, and a failure says nothing.
+- **Placing the feedback inside the Item.** A removed card's row unmounts, taking the message with it.
+- **Setting `open` on the `AlertDialogRoot` inside `AccountSavedCardRemove`.** The controller owns it.
+- **Adding a plain button as the confirm control.** Only `AccountSavedCardRemoveConfirm` dispatches the removal.
+
+---
+
+## Styling
+
+| Component | What you style | Plausible classes |
+|---|---|---|
+| `AccountSavedCardsRoot` | Section spacing | `flex flex-col gap-[16px]` |
+| `AccountSavedCardsHeading` | Heading typography | `text-[20px] font-semibold text-[#1F1F1F]` |
+| `AccountSavedCardsList` | Row stack | `flex flex-col gap-[8px]` |
+| `AccountSavedCardItem` | Row box; dim expired and unusable rows | `rounded-[8px] border border-[var(--color-border)] p-[12px] data-[fs-account-saved-card-expired]:opacity-60 data-[fs-account-saved-card-unusable]:opacity-60` |
+| `AccountSavedCardExpiry` | Line typography; color by state | `mt-[4px] text-[13px] text-[var(--color-text-muted)] data-[fs-account-saved-card-expiry-status=expired]:text-[var(--color-feedback-danger)] data-[fs-account-saved-card-expiry-status=unusable]:text-[var(--color-feedback-danger)]` |
+| `AccountSavedCardsEmpty` | Statement typography | `text-[14px] text-[var(--color-text-muted)]` |
+| `AccountSavedCardsLoading` | Placeholder stack; rows via `[&_[data-fs-account-saved-cards-loading-row]]` | `flex flex-col gap-[8px] [&_[data-fs-account-saved-cards-loading-row]]:h-[48px] [&_[data-fs-account-saved-cards-loading-row]]:rounded-[8px] [&_[data-fs-account-saved-cards-loading-row]]:bg-[#F0F0F0]` |
+| `AccountSavedCardsError` | Alert box and link | `rounded-[8px] bg-[#FDECEC] p-[12px] text-[14px] text-[var(--color-feedback-danger)] [&_a]:underline` |
+| `AccountSavedCardItem` (removing) | Fade the row while it is removed | `data-[fs-account-saved-card-removing]:opacity-60` |
+| `AccountSavedCardRemoveTrigger` | Link-like control | `mt-[8px] text-[13px] text-[var(--color-feedback-danger)] underline disabled:opacity-50` |
+| `AlertDialogPopup` | Prompt box (style the AlertDialog parts directly) | `w-full max-w-[420px] rounded-[12px] bg-white p-[24px] shadow-xl` |
+| `AccountSavedCardRemoveConfirm` | Destructive button; dim while pending | `rounded-[6px] bg-[var(--color-feedback-danger)] px-[16px] py-[8px] text-white aria-disabled:opacity-70` |
+| `AccountSavedCardsRemoveFeedback` | Message typography; alert color | `text-[14px] [&_[role=alert]]:text-[var(--color-feedback-danger)] [&_a]:underline` |
+
+```json
+{
+  "saved-cards": { "type": "AccountSavedCardsRoot", "style": ["flex", "flex-col", "gap-[16px]"] },
+  "saved-card-item": { "type": "AccountSavedCardItem", "style": ["rounded-[8px]", "border", "border-[var(--color-border)]", "p-[12px]"] }
+}
+```
+
+The role colors above are the foundation's `visualIdentity` roles (`--color-feedback-danger`), so they follow the store when it changes them.
+
+The colors that several elements share are variables of the page or layout `theme`, which declares them: `{"--color-border": "#E5E5E5", "--color-text-muted": "#6B6B6B"}`. A color used once stays a hex.
+
+---
+
+## Related
+
+- [[card-summary]]: the card description each row renders.
+- [[alert-dialog]]: the overlay the removal prompt is built on.
+- [[saved-cards]]: the checkout's saved-card picker; cart-scoped.
+- [[my-account-profile]]: the account's other session-scoped matter.

package/dist/docs/alert-dialog.md

@@ -185,7 +185,7 @@ A delete-address confirmation. The confirm `Button` is inert here: in a store, t
 
 | Component | What you style | Plausible classes |
 |---|---|---|
-| `AlertDialogTrigger` | The button that opens the prompt | `px-[16px] py-[8px] text-[14px] font-medium text-[#B42318] border border-[#FDA29B] rounded-[6px]` |
+| `AlertDialogTrigger` | The button that opens the prompt | `px-[16px] py-[8px] text-[14px] font-medium text-[var(--color-feedback-danger)] border border-[#FDA29B] rounded-[6px]` |
 | `AlertDialogBackdrop` | The dimmed layer over the page | `fixed inset-0 bg-black/40` |
 | `AlertDialogViewport` | Fixed positioning and centering of the popup | `fixed inset-0 flex items-center justify-center p-[16px]` |
 | `AlertDialogPopup` | The card: layout, background, radius, shadow, and its enter and exit | `flex flex-col gap-[8px] w-full max-w-[448px] p-[24px] bg-white rounded-[12px] shadow-xl data-[starting-style]:opacity-0 data-[ending-style]:opacity-0` |
@@ -195,6 +195,8 @@ A delete-address confirmation. The confirm `Button` is inert here: in a store, t
 
 `AlertDialogRoot` and `AlertDialogPortal` have no styling surface. Base UI sets `data-open`, `data-closed`, `data-starting-style`, and `data-ending-style` on the popup and the backdrop, so enter and exit animations key on those attributes.
 
+The role colors above are the foundation's `visualIdentity` roles (`--color-feedback-danger`), so they follow the store when it changes them.
+
 ---
 
 ## Related

package/dist/docs/avatar.md

@@ -77,7 +77,7 @@ The fallback shows whenever there is no image, the image is still loading, or it
 
 | Component | What you style | Plausible classes |
 |---|---|---|
-| `Avatar` | `data-fs-avatar` is the circle: size, shape, background, and the initials' type | `inline-flex size-10 shrink-0 items-center justify-center overflow-hidden rounded-full bg-[#E5E7EB] text-[14px] font-medium` |
+| `Avatar` | `data-fs-avatar` is the circle: size, shape, background, and the initials' type | `inline-flex size-10 shrink-0 items-center justify-center overflow-hidden rounded-full bg-[var(--color-surface-strong)] text-[14px] font-medium` |
 | Image | `data-fs-avatar-image` is the `<img>` once loaded | `size-full object-cover` |
 | Initials | `data-fs-avatar-fallback` is the initials span | `uppercase` |
 
@@ -88,12 +88,14 @@ The fallback shows whenever there is no image, the image is still loading, or it
     "props": { "name": "Jane Doe", "alt": "Jane Doe" },
     "style": [
       "inline-flex", "size-10", "shrink-0", "items-center", "justify-center", "overflow-hidden",
-      "rounded-full", "bg-[#E5E7EB]", "text-[14px]", "font-medium", "[&_img]:size-full", "[&_img]:object-cover"
+      "rounded-full", "bg-[var(--color-surface-strong)]", "text-[14px]", "font-medium", "[&_img]:size-full", "[&_img]:object-cover"
     ]
   }
 }
 ```
 
+The colors that several elements share are variables of the page or layout `theme`, which declares them: `{"--color-surface-strong": "#E5E7EB"}`. A color used once stays a hex.
+
 ---
 
 ## Related

package/dist/docs/billing-address.md

@@ -90,27 +90,37 @@ a form the shopper cannot see.
 
 | Prop | Type | Default | Notes |
 |------|------|---------|-------|
-| `sameAsDeliveryLabel` | string | `"Billing address same as delivery address"` | The toggle's own label text. |
-| `defaultCountry` | string | `"BRA"` | Initial country selected when the custom form first mounts. |
-| `countryLabel` | string | `"Country"` | Label for the country selector inside the custom form. |
-| `recipientNameLabel` | string | `"Recipient's name"` | Label for the recipient-name descriptor field. Not rendered by the custom-address form today — the write contract has no matching input slot — kept for parity with the other seven field labels. |
-| `streetLabel` | string | `"Street"` | Label for the street descriptor field. |
-| `numberLabel` | string | `"Number"` | Label for the street-number descriptor field. |
-| `complementLabel` | string | `"Complement (optional)"` | Label for the complement descriptor field. Its "(optional)" suffix is the only signal that the field is not required — the actual `required` attribute is driven independently, so authoring this without the suffix loses the visual cue, not the behavior. |
-| `neighborhoodLabel` | string | `"Neighborhood"` | Label for the neighborhood descriptor field. Unused when the active country's descriptor has no `neighborhood` field (e.g. USA). |
-| `cityLabel` | string | `"City"` | Label for the city descriptor field. |
-| `stateLabel` | string | `"State"` | Label for the state descriptor field. |
-| `postalCodeLabel` | string | `"Postal code"` | Label for the postal-code descriptor field. |
-| `submitLabel` | string | `"Save billing address"` | Label for the button that persists a custom address. |
-| `submitPendingLabel` | string | `"Saving..."` | Submit button's label while the write is in flight. |
-| `requiredNoticeLabel` | string | `"This payment method requires a billing address."` | Shown when the selected method's validator marks a billing address required. |
-| `unsavedAddressNoticeLabel` | string | `"No billing address has been saved yet — the delivery address will be used unless you save one below."` | Shown, `role="status"`, while the custom-address form is open and no address has been persisted yet. |
-| `billingMatchNoticeLabel` | string | `"Your billing address must match the one on your card or bank statement, or your bank may decline the order."` | Always-on billing-match disclaimer. Gated only by this prop and `billingMatchNoticeVisible` — unlike the two notices above, it never changes with the toggle, the form, `billingAddressRequired`, or a saved address. |
-| `billingMatchNoticeVisible` | boolean | `true` | Switches the billing-match disclaimer above on or off. A blank `billingMatchNoticeLabel` also renders nothing, even while this is `true` — the two rules never combine into an empty element. |
-| `fieldRequiredMessage` | string | `"This field is required."` | Shown as an inline field error under a required, blank address field once it has been touched (T38) — see Accessibility Contract below. One prop, not one per field: every rendered field but `complement` shares the same rule. An authored empty or whitespace-only string falls back to this default. |
-| `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. |
+| `defaultCountry` | string | `"BRA"` | Initial country selected when the custom form first mounts: `BRA`, `USA`, `CAN` or `MEX`. The store authors it; the form does not follow the store's own country. A code with no descriptor falls back to the first available country (`BRA`); `CAN` and `MEX` are kept while their descriptor is still loading, and the form shows the country and no fields until it arrives. |
+| `billingMatchNoticeVisible` | boolean | `true` | Switches the billing-match disclaimer on or off. A blank `billingMatchNoticeLabel` message also renders nothing, even while this is `true` — the two rules never combine into an empty element. |
 | `disabled` | boolean | `false` | Disables the toggle, every form field, the country selector, and the submit button. |
 
+**Content (`billing-address`):** every word of the form is a message field the store authors in `$content`; a missing or blank one renders empty and logs `message.missing`. Country names in the selector are not copy: they come from `Intl.DisplayNames` in the store locale ("Brazil" in `en-US`, "Brasil" in `pt-BR`).
+
+| Field | Source (English) | Notes |
+|-------|------------------|-------|
+| `sameAsDeliveryLabel` | `Billing address same as delivery address` | The toggle's own label text. |
+| `countryLabel` | `Country` | Label for the country selector inside the custom form. |
+| `recipientNameLabel` | `Recipient's name` | Label for the recipient-name descriptor field. Not rendered by the custom-address form today — the write contract has no matching input slot — kept for parity with the other seven field labels. |
+| `streetLabel` | `Street` | Label for the street descriptor field. |
+| `numberLabel` | `Number` | Label for the street-number descriptor field. |
+| `complementLabel` | `Complement (optional)` | Label for the complement descriptor field. Its "(optional)" suffix is the only signal that the field is not required — the actual `required` attribute is driven independently, so authoring this without the suffix loses the visual cue, not the behavior. |
+| `neighborhoodLabel` | `Neighborhood` | Label for the neighborhood descriptor field. Unused when the active country's descriptor has no `neighborhood` field (e.g. USA or Canada). |
+| `cityLabel` | `City` | Label for the city descriptor field. |
+| `stateLabel` | `State` | Label for the state descriptor field. |
+| `postalCodeLabel` | `Postal code` | Label for the postal-code descriptor field. |
+| `submitLabel` | `Save billing address` | Label for the button that persists a custom address. |
+| `submitPendingLabel` | `Saving...` | Submit button's label while the write is in flight. |
+| `requiredNoticeLabel` | `This payment method requires a billing address.` | Shown when the selected method's validator marks a billing address required. |
+| `unsavedAddressNoticeLabel` | `No billing address has been saved yet — the delivery address will be used unless you save one below.` | Shown, `role="status"`, while the custom-address form is open and no address has been persisted yet. |
+| `billingMatchNoticeLabel` | `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 message and `billingMatchNoticeVisible` — unlike the two notices above, it never changes with the toggle, the form, `billingAddressRequired`, or a saved address. |
+| `fieldRequiredMessage` | `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 field, not one per address field: every rendered field but `complement` shares the same rule. |
+| `postalCodeInvalidMessage` | `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 it. A blank postal code reads `fieldRequiredMessage` instead, never this. The message never contains the typed value. |
+| `missingFieldsMessage` | `Fill in the postal code and the country of your billing address.` | Inline alert when the server refuses the address without a postal code or country (`MISSING_BILLING_ADDRESS_FIELDS`). |
+| `invalidCountryMessage` | `Choose a valid country for your billing address.` | Inline alert when the server refuses the country (`INVALID_COUNTRY_CODE`). |
+| `genericErrorMessage` | `Unable to save your billing address. Please try again.` | Inline alert for `MISSING_CART_CONTEXT`, `CART_NOT_FOUND` and `NETWORK_ERROR`. A code the package does not know (one a newer server added) shows it too and logs `message.unknown-code`. |
+
+A field a library-backed descriptor adds with no label field here shows its canonical field name.
+
 **Data:** declares no fragment and no `fetchStrategy`, so it fetches no shopper data. It reads only the
 payment context (`requiresContext: 'payment'`): the selected method's validator and the shared payment
 draft. **Nothing prefills the custom-address form** — there is no server field that echoes back an
@@ -147,7 +157,7 @@ the blocking themselves; both stay exactly as advisory as described above.
 **A third notice, `billingMatchNoticeLabel`, is configuration-driven, not state-driven like the two
 above.** The required-note and the unsaved-notice each appear and disappear by runtime state (the
 selected method's validator; the form being open with nothing saved yet). This one does not: its
-presence is a pure function of `billingMatchNoticeLabel` and `billingMatchNoticeVisible` alone, and it
+presence is a pure function of the `billingMatchNoticeLabel` message and `billingMatchNoticeVisible` alone, and it
 renders before the toggle field on every render — including the default state, where "same as delivery"
 stays checked and the shopper never opens the form. It never reacts to the toggle, to
 `billingAddressRequired`, to a saved address, or to order placement; a merchant switches it off with
@@ -158,10 +168,49 @@ 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. 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.
+address step uses: Brazil shows a neighborhood/bairro field, the United States and Canada do not, Mexico
+shows a neighborhood and a number, 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. Brazil and the United
+States are written in the descriptor table; Canada and Mexico are read from `@vtex/country-forms` when
+the form mounts, so the selector lists them (Brazil, United States, Canada, Mexico) once they have
+loaded. The postal code's format is the same data: the descriptor's `rule` (a pattern for Brazil and the
+United States, the library's own verdict for Canada and Mexico) gates the submit button and the field
+error, so a country's format is defined once for both forms. A Canadian or Mexican postal code is
+submitted in the library's stored form (`K1A 0B1`), not as typed.
+
+### Countries and postal codes
+
+The selector lists the same countries for every store. It is not filtered by the countries the store ships
+to, because a card's billing country does not depend on where the store delivers.
+
+Canada and Mexico take their field set and required flags from `@vtex/country-forms` (the pinned 1.14.0),
+and the repository holds no regular expression, list or mask for either. Only the English copy is written
+in `packages/faststore/src/matter/shipping-address/library-country-descriptors.ts`. Canada has no number
+or neighborhood field, so a Canadian shopper types the house number inside the street. Mexico adds both,
+and the neighborhood is required: every rendered field except the complement is, so a Mexican shopper
+without one cannot save. The state is free text for both countries, although the library lists 13
+provinces and 32 states.
+
+The postal code rules are the library's. Canada refuses a first letter of D, F, I, O, Q, U or W and
+ignores case and the space, but accepts a Z in first position and D, F, I, O, Q or U later in the code, so
+it is looser than Canada Post's alphabet. Mexico takes five digits and refuses a value below `01000`.
+Both judge the trimmed value, so ` 06600 ` passes. The Brazilian and US patterns test the raw value, so a
+leading or trailing space fails them. The US pattern accepts a ZIP+4 with or without the hyphen
+(`021011234`), and a Brazilian or US postal code is submitted exactly as typed.
+
+Other countries need more than a data entry. The library covers `ARG`, `CHL`, `COL`, `ECU` and `PER` with a
+select whose options depend on another field (a city or neighborhood chosen by state), which a descriptor
+cannot express. A country with a flat field list joins by adding its ISO code to `LIBRARY_COUNTRIES` with a
+copy row there.
+
+If a country's chunk fails to load, it is left out of the selector, the form keeps working with the others,
+nothing is shown about it, and the next mount retries it.
+
+The server does not back the client rule. `paymentBillingAddressUpdate` checks only that `postalCode` and
+`country` are present and that the country is three capital letters, so this verdict is the only postal
+code guard for billing. Two answers were not measured on a live Canadian or Mexican account: which `state`
+value the Checkout expects (`ON` or `Ontario`, `CMX` or `Ciudad de México`), and whether a card issuer's
+address check wants the Canadian postal code with or without the space.
 
 ---
 
@@ -175,7 +224,25 @@ gates the submit button and the field error, so a country's format is defined on
   },
   "billing-address": {
     "type": "BillingAddress",
-    "props": { "sameAsDeliveryLabel": "Billing address same as delivery address" },
+    "props": {
+      "sameAsDeliveryLabel": "Billing address same as delivery address",
+      "countryLabel": "Country",
+      "streetLabel": "Street",
+      "numberLabel": "Number",
+      "complementLabel": "Complement (optional)",
+      "neighborhoodLabel": "Neighborhood",
+      "cityLabel": "City",
+      "stateLabel": "State",
+      "postalCodeLabel": "Postal code",
+      "recipientNameLabel": "Recipient's name",
+      "submitLabel": "Save billing address",
+      "submitPendingLabel": "Saving...",
+      "requiredNoticeLabel": "This payment method requires a billing address.",
+      "unsavedAddressNoticeLabel": "No billing address has been saved yet — the delivery address will be used unless you save one below.",
+      "billingMatchNoticeLabel": "Your billing address must match the one on your card or bank statement, or your bank may decline the order.",
+      "fieldRequiredMessage": "This field is required.",
+      "postalCodeInvalidMessage": "Enter a valid postal code."
+    },
     "style": ["flex", "flex-col", "gap-3"]
   }
 }
@@ -229,13 +296,15 @@ while the box is unchecked, and an optional inline error.
 | Same as delivery (`data-fs-billing-address-same-as-delivery`) | Present on the root while the box is checked, absent while it is unchecked. It sits on the node the style array styles, so target it as `data-[fs-billing-address-same-as-delivery]:…`, never with a descendant variant | `data-[fs-billing-address-same-as-delivery]:gap-[8px]` |
 | Panel (`data-fs-billing-address-panel`) | Always present, right after the toggle field, and the toggle's `aria-controls` target. `hidden` and empty while the box is checked; holds the custom-form wrapper while unchecked. Never give it a display utility (`flex`, `grid`, `block`, …): one defeats `hidden` | none — style the form inside it |
 | Custom-form wrapper (`data-fs-billing-address-form`), inside the panel | Field grid | `grid grid-cols-2 gap-[8px]` |
-| Required-billing-address note (`data-fs-billing-address-required-note`) | De-emphasized helper text | `text-[12px] text-[#666666]` |
-| Unsaved-address notice (`data-fs-billing-address-unsaved-notice`) | De-emphasized, non-error helper text | `text-[12px] text-[#666666]` |
-| Billing-match disclaimer (`data-fs-billing-address-match-notice`) | De-emphasized helper text, first child of the root | `text-[12px] text-[#666666]` |
-| Field error (`data-fs-field-error`) | Per-field validation message, shown once a 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]` |
+| Required-billing-address note (`data-fs-billing-address-required-note`) | De-emphasized helper text | `text-[12px] text-[color-mix(in_srgb,var(--color-ink)_60%,transparent)]` |
+| Unsaved-address notice (`data-fs-billing-address-unsaved-notice`) | De-emphasized, non-error helper text | `text-[12px] text-[color-mix(in_srgb,var(--color-ink)_60%,transparent)]` |
+| Billing-match disclaimer (`data-fs-billing-address-match-notice`) | De-emphasized helper text, first child of the root | `text-[12px] text-[color-mix(in_srgb,var(--color-ink)_60%,transparent)]` |
+| 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` |
+| Inline error (`data-fs-billing-address-error`) | Warning-toned alert text | `text-[12px] font-medium` |
 | 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` |
 
+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 example:
 
 ```json