@vtex/faststore 0.0.8 → 0.0.10

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

@@ -0,0 +1,301 @@
+# 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           (default when the row has no children)
+        ├── AccountSavedCardExpiry (default when the row has no children)
+        └── AccountSavedCardRemove (default when the row has no children) ← provides 'account-saved-card-remove'
+            └── AlertDialogRoot
+                ├── AccountSavedCardRemoveTrigger
+                └── AlertDialogPortal > AlertDialogBackdrop + AlertDialogViewport > AlertDialogPopup
+                    ├── AccountSavedCardRemoveTitle
+                    ├── AccountSavedCardRemoveDescription
+                    ├── AccountSavedCardRemoveCancel
+                    └── AccountSavedCardRemoveConfirm
+```
+
+`AccountSavedCardRemove` with no children renders the prompt shown under it.
+
+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, including the one a bare Item renders.
+
+### 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`. With no children it renders `CardSummary`'s default (mark, network name, mask, last four digits), then `AccountSavedCardExpiry`, then `AccountSavedCardRemove`. 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 the three parts as children to rearrange the row or to reword it from the CMS. 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 the default prompt. 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.
+
+### 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 resolves in this order: `children`, then the part's CMS entry (`$content`, a blank field counts as unset), then the catalog message in the store's locale.
+
+| Part | CMS fields | Catalog ids |
+|---|---|---|
+| `AccountSavedCardsHeading` | `text` | `fs/saved-cards.heading` |
+| `AccountSavedCardsEmpty` | `text` | `fs/saved-cards.empty` |
+| `AccountSavedCardsLoading` | `text` | `fs/saved-cards.loading` |
+| `AccountSavedCardsError` | `text`, `sessionExpiredText`, `signInLabel` | `fs/saved-cards.load-failed`, `fs/saved-cards.session-expired`, `fs/saved-cards.sign-in` |
+| `AccountSavedCardExpiry` | `expiresLabel`, `expiredLabel`, `expiredText`, `unusableText` | `fs/saved-cards.expires`, `fs/saved-cards.expired`, `fs/saved-cards.expired-no-date`, `fs/saved-cards.unusable` |
+| `AccountSavedCardRemoveTrigger` | `text` | `fs/saved-cards.remove.trigger` |
+| `AccountSavedCardRemoveTitle` | `text` | `fs/saved-cards.remove.title` |
+| `AccountSavedCardRemoveDescription` | `text` | `fs/saved-cards.remove.description` |
+| `AccountSavedCardRemoveCancel` | `text` | `fs/saved-cards.remove.cancel` |
+| `AccountSavedCardRemoveConfirm` | `text`, `pendingText` | `fs/saved-cards.remove.confirm`, `fs/saved-cards.remove.pending` |
+| `AccountSavedCardsRemoveFeedback` | `successText`, `failureText`, `sessionExpiredText`, `signInLabel` | `fs/saved-cards.remove.success`, `fs/saved-cards.remove.failed`, `fs/saved-cards.session-expired`, `fs/saved-cards.sign-in` |
+
+`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 reads its CMS entry: the expiry line and the prompt an Item renders by default always show the catalog wording.
+
+## 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"] },
+  "saved-card-item": { "type": "AccountSavedCardItem" }
+}
+```
+
+Nested inside another account page, with a lower heading:
+
+```json
+{
+  "saved-cards-heading": { "type": "AccountSavedCardsHeading", "props": { "as": "h3" } }
+}
+```
+
+With the row composed, so the expiry line and the removal prompt can be reworded from the CMS:
+
+```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.
+- **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.
+- **Passing `text` as a schema prop.** Text comes from children, the CMS entry, or the catalog.
+- **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.
+- **Expecting CMS wording on an Item with no children.** Its default expiry line and removal prompt are not in the schema, so they read only the catalog; place `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-[#E5E5E5] 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-[#6B6B6B] data-[fs-account-saved-card-expiry-status=expired]:text-[#B42318] data-[fs-account-saved-card-expiry-status=unusable]:text-[#B42318]` |
+| `AccountSavedCardsEmpty` | Statement typography | `text-[14px] text-[#6B6B6B]` |
+| `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-[#B42318] [&_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-[#B42318] 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-[#B42318] px-[16px] py-[8px] text-white aria-disabled:opacity-70` |
+| `AccountSavedCardsRemoveFeedback` | Message typography; alert color | `text-[14px] [&_[role=alert]]:text-[#B42318] [&_a]:underline` |
+
+```json
+{
+  "saved-cards": { "type": "AccountSavedCardsRoot", "style": ["flex", "flex-col", "gap-[16px]"] },
+  "saved-card-item": { "type": "AccountSavedCardItem", "style": ["rounded-[8px]", "border", "border-[#E5E5E5]", "p-[12px]"] }
+}
+```
+
+---
+
+## 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/binding-switcher.md

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

package/dist/docs/card-entry.md

@@ -90,7 +90,7 @@ In the checkout, the card number, holder name, expiration, and security code are
 }
 ```
 
-**If the store's `global.json` already has an `icons` object, extend it — do not replace it.** A store that already sets `"collection"` (or `"aliases"` / `"collections"`) must keep that key alongside the new `include`:
+**If the store's `foundation.json` already has an `icons` object, extend it — do not replace it.** A store that already sets `"collection"` (or `"aliases"` / `"collections"`) must keep that key alongside the new `include`:
 
 ```json
 {
@@ -107,7 +107,7 @@ Omitting `include` entirely is silent too. The network icon renders as an empty
 
 ## Store setup: response headers
 
-The card number and security code are typed into `CardEntry`'s raw fields and POSTed from the browser straight to the VTEX payment gateway, so the page that composes it needs a policy that names the vault host the card is POSTed to, forbids framing the page, and narrows what the page may load and call. The generator ships no default: the store declares it in `global.json` under `responseHeaders`, scoped by `routes` to the page that composes `CardEntry`.
+The card number and security code are typed into `CardEntry`'s raw fields and POSTed from the browser straight to the VTEX payment gateway, so the page that composes it needs a policy that names the vault host the card is POSTed to, forbids framing the page, and narrows what the page may load and call. The generator ships no default: the store declares it in `foundation.json` under `responseHeaders`, scoped by `routes` to the page that composes `CardEntry`.
 
 ```json
 {
@@ -123,7 +123,7 @@ The card number and security code are typed into `CardEntry`'s raw fields and PO
 }
 ```
 
-- **The vault host in `connect-src` is `https://{account}.vtexvault.com`, for the account the store serves.** That is the `NEXT_PUBLIC_ACCOUNT` the store is built with, which is not always `account.name` in `global.json`. Write the served account, with no wildcard: `https://*.vtexvault.com` would let a compromised script send the card to any tenant's vault.
+- **The vault host in `connect-src` is `https://{account}.vtexvault.com`, for the account the store serves.** That is the `NEXT_PUBLIC_ACCOUNT` the store is built with, which is not always `store.account` in `foundation.json`. Write the served account, with no wildcard: `https://*.vtexvault.com` would let a compromised script send the card to any tenant's vault.
 - **A policy that names the legacy payments host (`vtexpayments.com.br`) makes the browser block the card POST.** The order cannot be placed and nothing else on the page reports why. The generated app calls its own GraphQL at the relative `/api/graphql`, so `'self'` covers it; a store built with an absolute `NEXT_PUBLIC_STOREFRONT_API_URL` must add that origin.
 - **A rule's `routes` must name the page that composes `CardEntry`**, as the page's `route` spells it (`/checkout`, `/reserva/checkout/payment`). Renaming that page fails the compile instead of dropping the policy. A page added later that composes `CardEntry` carries nothing until its route is added to the rule.
 - **`script-src 'unsafe-inline'` is a known limit, and the policy does not stop injected script from sending the card off the page.** A static header cannot carry a nonce, so the inline scripts Next.js emits need it, and script injected into the page runs with the same rights. `connect-src` closes only `fetch`, XHR, beacons and WebSocket. The policy still leaves three channels open to any https host: an image request (`img-src https:`, which the page needs for catalog images), a form submission (no `form-action`) and a navigation (CSP cannot restrict one). What today's ruled policy does give is the vault origin pinned, no `'unsafe-eval'`, a page no other site can frame (`frame-ancestors 'none'`) and no `http:` or wildcard source. It does not replace keeping untrusted script off the payment page.

package/dist/docs/card-summary.md

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