@vtex/faststore 0.0.5 → 0.0.7

package/dist/docs/saved-cards.md

@@ -0,0 +1,218 @@
+# SavedCards
+
+**Category:** commerce
+**Purpose:** Renders the checkout payment step's saved-card picker — a radio list of a shopper's stored cards (network, last four digits, label), with expired cards shown but disabled, and a CVV field that appears once a card is selected.
+
+---
+
+## Visual cues (how to identify in an image)
+
+Use these signals to detect that a SavedCards block is present. Position on the page is irrelevant for detection — it can appear anywhere in a payment/checkout step. The image is the source of truth for layout.
+
+A SavedCards block contains any combination of:
+
+- A **list of radio rows**, each showing a **card network name or logo** (Visa, Mastercard, …) plus a **masked number** like `•••• 4242` or `**** 4242`.
+- A **custom label** next to a row, e.g. *"Meu cartão"* / *"Personal card"* — shopper-assigned, not always present.
+- A row rendered **visually muted or with a "expired" tag**, still present in the list but not clickable.
+- A **short numeric input appearing next to or below the selected row**, typically labeled *"CVV"* / *"Security code"* / *"CVC"* — this appears only once a row is checked. Its digits render **obscured** (dots), same visual family as a password field, even though it is not one under the hood (see Components below, `SavedCardCvvField`, for why).
+- A **"pay with a new card" link or button** rendered as a sibling entry, not a row inside this list — that sibling is a different component (`CardEntry`), not part of this block.
+
+If the image shows a **radio list of masked card numbers with network names**, use `SavedCards`. Do not use it for a single card-entry form (no radio choice) — that is `CardEntry`.
+
+---
+
+## When to use
+
+- The checkout/payment step, for an authenticated shopper with one or more stored cards.
+- Anywhere a shopper picks among previously saved payment methods before completing a purchase.
+
+## When NOT to use
+
+- A blank new-card entry form (number, expiry, holder name fields) → use `CardEntry` instead; `SavedCards` never renders those fields.
+- A payment-method picker across networks/methods (Visa vs. Pix vs. Cash) → use `PaymentMethodList`, the sibling method-level picker under the same `PaymentSectionRoot`. `SavedCards` only distinguishes stored *cards*, not payment *methods*.
+- An address book / saved shipping addresses list → use the equivalent shipping-address components; visually similar (a radio list of saved records) but a different domain.
+
+---
+
+## Composition
+
+`SavedCards` is the list root and must be a descendant of `PaymentSectionRoot` or `PaymentSectionController`. `SavedCardOption` is the per-card row template placed directly inside it. `SavedCardCvvField` is placed inside `SavedCardOption` so the CVV appears once that row is selected.
+
+```
+PaymentSectionRoot (or PaymentSectionController)
+├── PaymentMethodList                (sibling — network/method picker)
+├── SavedCards
+│   └── SavedCardOption              (per-card template, repeated once per stored card)
+│       └── SavedCardCvvField        (appears only for the selected, CVV-required row)
+└── CardEntry                        (sibling — "use a new card", not a child of SavedCards)
+```
+
+Child order reflects visual order. `SavedCardOption` and `SavedCardCvvField` are the only two valid parent/child pairs this block defines; everything else (`PaymentMethodList`, `CardEntry`) is a sibling under the same `PaymentSectionRoot`, never nested inside `SavedCards`.
+
+**Composition rules:**
+
+- `SavedCards` must be inside `PaymentSectionRoot` or `PaymentSectionController`. Outside either, it throws.
+- `SavedCardOption` must be a direct child of `SavedCards`. It renders `null` when its row's data has not resolved.
+- `SavedCardCvvField` must be inside `SavedCardOption`. Outside it, it throws. Omitting it means a shopper can select that card but never submit a payment with it — always include it.
+- `CardEntry` ("use a new card") is a **sibling** of `SavedCards`, never a child or a row inside it — there is no "toggle" prop that switches this list into new-card mode.
+
+---
+
+## Components
+
+### SavedCards
+
+List root. Renders a radio group of the shopper's saved cards. Renders its container even when the list is empty or still loading (a hooked, not zero-height, region). It renders nothing at all 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]]). Its rows' CVV fields unmount with it, which clears any code typed there. To reach a saved card from a method that is not a card, the shopper chooses the card option first, which brings the list back.
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| `legend` | string | `"Saved cards"` | The radio group's accessible name, rendered as a visible fieldset legend above the rows (T38). An authored empty or whitespace-only string falls back to this default rather than rendering a nameless group. |
+
+Which cards exist is always real data (`Query.payment.savedCards`) — never author them as props.
+
+**Data:** declares `fragment SavedCardsListData on Query`. The compiler merges it into the page query — no explicit `dataSources` entry needed.
+
+### SavedCardOption
+
+One saved card as a radio row: network name, masked last four (`•••• 4242`), and the shopper's own label when set. Disabled (not selectable) when the card is expired — the row still renders so the shopper knows the card exists.
+
+No props beyond standard container attributes (`className`, `children`). Must be a direct child of `SavedCards`.
+
+**Data:** declares `fragment SavedCardOptionData on Query`, independently resolved per row (a write to one saved card only re-renders that row, not the whole list).
+
+### SavedCardCvvField
+
+The CVV re-entry field for its row. Renders nothing until that specific row is selected and the card requires a CVV; then renders a numeric input (digits only, capped at 4 characters) whose digits render **obscured** (dots) via an inline `-webkit-text-security: disc` style once the code is fully typed, with a helper line underneath it (`securityCodeDescription`, defaulting to "The 3-4 digit number on your card"; an empty string renders nothing). Wires the direct-to-gateway payment submission for the saved-card path the moment it is composed — the CVV is never sent to the storefront's own backend. A blank or under-three-digit code refuses before the place-order sequence opens a transaction, moving focus back to this input; the message reaches the shopper through the place-order CTA's own alert, not an inline field error here.
+
+The mask engages on the third digit and stays on for a fourth. Three, because a saved card carries no per-network security-code length — the row's data has a display network name, not a `cvvMask` — so there is no signal here that tells a 3-digit network apart from Amex's 4, and the field's own accept-either floor is the only length available. Masking at the floor never leaves a complete code legible on either kind of card; a 4-digit code is simply already masked when its last digit arrives. Below three digits the code renders in the clear, so a shopper can read back what they just typed, and backspacing below three reveals what is left. Same rule and same shared predicate as `CardEntry`'s CVV field, which resolves its length from the detected method instead.
+
+`type="password"` was tried first and reverted: a real Chrome browser offered to save the security code to its password manager (synced to the signed-in account) the instant the field carried that type, which PCI-DSS forbids for a value that must not be retained past authorization. The input stays `type="text"`, and no caller-passed `type` can override that. The CSS property above obscures the digits without tripping that heuristic, since it never touches `type`; a caller-passed `style` cannot remove it either — once the code is complete the mask always merges in last, so no caller can hold it off past that point. Supported in Chromium and WebKit (and, per T70's spec, Firefox 114+ — unverified on this branch); an engine without it renders the digits in the clear, same as before this mechanism existed — not a regression. The declaration is an inline style, which outranks a class-based rule from a compound swatch at normal importance — but not one that reaches for Tailwind's `!` important modifier: swatch tokens reach `className` verbatim with no validation, so a store that authors an arbitrary-property utility ending in `!` can still unmask the field. Nothing in this package closes that hole; it is accepted rather than fixed (masking spec, OQ-1).
+
+No props beyond standard input attributes (`className`), `securityCodeLabel` (accessible name), and `securityCodeDescription` (helper text). Must be inside `SavedCardOption`.
+
+---
+
+## Canonical schema example
+
+```json
+{
+  "saved-cards": {
+    "type": "SavedCards",
+    "children": ["saved-card-option"]
+  },
+  "saved-card-option": {
+    "type": "SavedCardOption",
+    "children": ["saved-card-cvv"]
+  },
+  "saved-card-cvv": { "type": "SavedCardCvvField" }
+}
+```
+
+### In context (inside a payment section, alongside the method picker and "use a new card")
+
+```json
+{
+  "payment-section": {
+    "type": "PaymentSectionRoot",
+    "children": ["payment-method-list", "saved-cards", "card-entry"]
+  },
+  "payment-method-list": { "type": "PaymentMethodList" },
+  "saved-cards": {
+    "type": "SavedCards",
+    "children": ["saved-card-option"]
+  },
+  "saved-card-option": {
+    "type": "SavedCardOption",
+    "children": ["saved-card-cvv"]
+  },
+  "saved-card-cvv": { "type": "SavedCardCvvField" },
+  "card-entry": { "type": "CardEntry" }
+}
+```
+
+---
+
+## Common mistakes
+
+- **Nesting `CardEntry` ("use a new card") inside `SavedCards`.** It is a sibling under the same `PaymentSectionRoot`, never a row or a child of this list.
+- **Inventing a `mode` or `showNewCard` prop on `SavedCards` to switch to new-card entry.** There is no such prop — "use a new card" is a separate component composed alongside this one, not a display mode of it.
+- **Omitting `SavedCardCvvField` inside `SavedCardOption`.** Without it, a shopper can select a saved card but the place-order flow has nothing to submit with — always include it.
+- **Placing `SavedCardOption` or `SavedCardCvvField` outside their required ancestor.** `SavedCardOption` must be inside `SavedCards`; `SavedCardCvvField` must be inside `SavedCardOption`. Only `SavedCardCvvField` throws when misplaced. A misplaced `SavedCardOption` does **not** throw — it silently renders `null` (no ancestry check of its own; it just has no resolved row data to show), so a page can ship with a silently empty saved-cards list. This is an authoring convention, not a compiler or runtime guarantee: `requiresContext` is satisfied by *any* ancestor providing that context at *any* depth, not specifically a direct parent, and there is no mechanism that forbids a given ancestor either.
+- **Passing a `savedCards` prop, a card list, or a `cvv` value as an authored prop.** Every field here is real data from `Query.payment.savedCards` or shopper-typed local state — never a schema-bindable prop. Neither component in this block declares a `cvv`, `cardNumber`, or `bin` prop of any kind.
+- **Using `SavedCards` for the network/method picker.** That is `PaymentMethodList` — a sibling under the same root, distinguishing payment *methods* (Visa vs. Pix), not stored *cards*.
+- **Wrapping `SavedCards` in a page with no `PaymentSectionRoot` ancestor.** It requires the payment context; use only inside a composed payment section.
+
+---
+
+## Known limitations
+
+- **A saved card with `cvvRequired: false` can be selected but never paid with — open item, not fixed in this pass.** `SavedCardCvvField` renders nothing when `cvvRequired` is `false`, and it is the only component that registers the `'saved-card'` submission continuation. For such a card, today: the row renders selected (`data-fs-saved-card-option-selected` present, `aria-checked="true"`), but `usePaymentSubmission().resolve('saved-card')` returns `null`, so `usePlaceOrder` resolves `MISSING_PAYMENT_SUBMISSION` and Place Order fails — with no CVV field ever offered and no way for the shopper to proceed. This is data-driven (`SavedCard.cvvRequired` passes through the account's own `useCvvForAuthorization`), not an authoring mistake, and it is deliberately left open rather than guessed at: the fix depends on whether the payment gateway's direct-to-gateway POST accepts `fields.validationCode: ''` for a `useCvvForAuthorization: false` account, or whether that account type needs the legacy's separate no-CVV mutation instead — a payments question this repository cannot answer on its own. See `specs/saved-cards.md`'s Open Questions and Assumptions for the full record.
+
+---
+
+## Styling
+
+Style `SavedCards` as a vertical stack of rows, each row as a horizontal line (radio indicator, network, last four, label), and the CVV field as a small, short numeric input that appears inline with the selected row.
+
+| Component | What you style | Plausible classes |
+|---|---|---|
+| `SavedCards` | Stacks the rows | `flex flex-col gap-[8px] w-full` |
+| Fieldset (`data-fs-saved-cards-fieldset`, native `<fieldset>`) | Wraps the legend and the radio rows (T38) — gives the group its visible, accessible name | usually left unstyled; a merchant border/padding choice |
+| Legend (`data-fs-fieldset-legend`, native `<legend>`) | The group's visible name, from `legend` | `text-[14px] font-medium text-[#1A1A1A]` |
+| `SavedCardOption` | One row — indicator, network, last four, label in a line; muted/dashed when expired | `flex items-center gap-[8px] p-[12px] border border-[#E0E0E0] rounded-[8px] data-[fs-saved-card-option-expired]:opacity-50 data-[fs-saved-card-option-selected]:border-[#000000]` |
+| `SavedCardCvvField` | The short CVV input | `w-[64px] text-[14px] px-[8px] py-[6px] border border-[#CCCCCC] rounded-[4px]` |
+| CVV helper text (`data-fs-saved-card-cvv-description`) | Small muted line next to/under the CVV input | `text-[12px] text-[#666666]` |
+| Placing (`data-fs-saved-cards-placing`) | Present on `SavedCards`' own root while an order-placement sequence is in flight (T28); the whole list — including every `SavedCardOption` row and its `SavedCardCvvField` — is `inert` and `aria-disabled` at that point, transitively, with no attribute of their own | `opacity-60 cursor-not-allowed` |
+
+Styled example:
+
+```json
+{
+  "saved-cards": {
+    "type": "SavedCards",
+    "children": ["saved-card-option"],
+    "style": ["flex", "flex-col", "gap-[8px]", "w-full"]
+  },
+  "saved-card-option": {
+    "type": "SavedCardOption",
+    "children": ["saved-card-cvv"],
+    "style": [
+      "flex", "items-center", "gap-[8px]", "p-[12px]",
+      "border", "border-[#E0E0E0]", "rounded-[8px]",
+      "data-[fs-saved-card-option-expired]:opacity-50",
+      "data-[fs-saved-card-option-selected]:border-[#000000]"
+    ]
+  },
+  "saved-card-cvv": {
+    "type": "SavedCardCvvField",
+    "style": ["w-[64px]", "text-[14px]", "px-[8px]", "py-[6px]", "border", "border-[#CCCCCC]", "rounded-[4px]"]
+  }
+}
+```
+
+---
+
+## Accessibility Contract
+
+**What the platform promises:** `SavedCards`' radio group carries a visible, programmatic accessible
+name (`legend`, default `"Saved cards"`) — a screen-reader user hears these rows are a choice between
+stored cards, not payment methods. An authored empty or whitespace-only `legend` falls back to the
+default rather than shipping a nameless group. Each row keeps its own accessible name from its network
+and masked last four; the CVV re-entry field carries its own `securityCodeLabel` as an `aria-label`
+and, when `securityCodeDescription` is set, an `aria-describedby` association to the helper text. The
+group is a native `<fieldset>`/`<legend>` pair, not only `aria-label`. Keyboard: the group is one Tab
+stop — Tab lands on the checked row, and the arrow keys move the checked row and change the selection.
+A default `:focus-visible` outline is painted from the platform's own stylesheet.
+
+**What the platform does not promise:** colour contrast. `SavedCards` (and every other payment
+component) exposes `data-fs-*` hooks so a merchant can author contrast-compliant swatches, but no
+component in this package measures or guarantees any contrast ratio — that is the merchant's theme, not
+this platform.
+
+---
+
+## Related
+
+- [[payment]] — `PaymentSectionRoot` / `PaymentMethodList`: the required ancestor and the sibling network/method picker. `SavedCards` cannot render outside a `PaymentSectionRoot` (or `PaymentSectionController`).
+- `CardEntry` — the "use a new card" entry point (new-card capture, a different task's deliverable). Always a sibling of `SavedCards`, never nested inside it.
+- [[shipping-address]] — its saved-address list is the closest visual precedent (a radio list of stored records with an expired/non-selectable-style state), from a different domain (addresses, not cards).