@vtex/faststore 0.0.7 → 0.0.8

package/dist/docs/order-progress.md

@@ -0,0 +1,88 @@
+# OrderProgress
+
+**Category:** content
+**Purpose:** Four stages of one order on the order page, placed, payment, processing, and shipping, with a line up to the stage the order is in.
+
+---
+
+## Visual cues (how to identify in an image)
+
+- A horizontal row of four short labels such as "Order placed", "Payment", "Processing", "Shipping", each with a small marker (dot, check, or cross) and a line joining the markers.
+- The line is filled up to one marker and faint after it. One stage reads as the current one.
+- A denied payment shows a cross on the second marker. A cancelled order shows a cross on the second marker and faint markers everywhere else.
+- No tracking number, carrier, or date sits on this row.
+
+The image is the source of truth for layout.
+
+## When to use
+
+- The order page, to show how far the order has moved.
+
+## When NOT to use
+
+- For the status sentence alone → use `OrderStatusBadge`.
+- For the placed date → use `OrderPlacedDate`.
+- For a step indicator outside an order → there is no generic stepper; this matter owns its line.
+- For an approval step → this matter has none. A B2C order never enters approval.
+
+---
+
+## Composition
+
+`OrderProgress` is a leaf in the page schema. It renders the four stages and the connectors itself.
+
+```text
+OrderProgress
+```
+
+Child order is not applicable. The stage order is fixed.
+
+## Components
+
+### OrderProgress
+
+No schema props. Stage names, state sentences, and the accessible name are content (`order-progress`). A blank field keeps the message catalogue. `failed` and `not-applicable` render no sentence.
+
+## Data
+
+The fragment reads `customerOrder(id: $orderId)` and selects `completion { view label }` and `progress { stage paymentFailed cancelled }`. `$orderId` is the route param of `/pvt/orders/[orderId]`. The OMS status string is not selected and the matter maps no status code.
+
+State per stage, in order:
+
+- `cancelled` → payment is `failed`, the other three are `not-applicable`.
+- Before the current stage → `done`. After it → `pending`.
+- The current stage → `failed` when `paymentFailed`, `done` when `completion.view` is `COMPLETED`, otherwise `current`.
+
+`$data` is the order itself. A null order renders nothing.
+
+## Styling
+
+Style the list, each stage, its marker, its label, its state sentence, and the connectors through their hooks. Inline classes only; use arbitrary variants to reach the children from the root class.
+
+- `data-fs-order-progress` — the list. `flex w-full items-start list-none p-0`. The stages share the row; a gap here breaks the connector.
+- `data-fs-order-progress-current` — `placed`, `payment`, `processing`, or `shipping`.
+- `data-fs-order-progress-cancelled` — present when the order is cancelled or a cancellation was requested.
+- `data-fs-order-progress-stage` — one stage, `placed`, `payment`, `processing`, or `shipping`. `relative flex min-w-0 flex-1 flex-col items-center gap-[4px] text-center`.
+- `data-fs-order-progress-stage-state` — `done`, `current`, `failed`, `not-applicable`, or `pending`. The `current` stage also carries `aria-current="step"`.
+- `data-fs-order-progress-track` — the marker row. `relative flex w-full items-center justify-center`.
+- `data-fs-order-progress-marker` — the icon slot, empty and `aria-hidden`. `relative z-10 size-[24px] rounded-full border-2 border-[#D1D5DB] bg-white`; fill it per state.
+- `data-fs-order-progress-line` — the connector into this stage, `aria-hidden`, absent on the first stage. It is taken out of flow and runs from the previous marker to this one: `absolute top-1/2 z-0 h-[2px] w-[calc(100%-24px)] -translate-y-1/2 -left-[calc(50%-12px)] bg-[#E5E7EB]`.
+- `data-fs-order-progress-line-state` — `done`, `pending`, or `not-applicable`.
+- `data-fs-order-progress-label` — the stage label. `text-[14px] font-medium text-[#111827]`.
+- `data-fs-order-progress-status` — the state sentence for `done`, `current`, and `pending`. Absent on `failed` and `not-applicable`. `text-[12px] text-[#6B7280]`, or `sr-only` when the marker already says it.
+- `data-fs-order-progress-skeleton` and `data-fs-order-progress-skeleton-stage` — the loading look.
+
+## Canonical schema
+
+```json
+{
+  "progress": {
+    "type": "OrderProgress",
+    "props": {},
+    "style": {
+      "default": "flex gap-[24px] list-none p-0"
+    },
+    "children": []
+  }
+}
+```

package/dist/docs/order-status-badge.md

@@ -0,0 +1,91 @@
+# OrderStatusBadge
+
+**Category:** content
+**Purpose:** Shopper-facing order status sentence, with a tone the caller supplies.
+
+---
+
+## Visual cues (how to identify in an image)
+
+- A short status sentence inside a compact label, such as "Delivered" or "In progress".
+- The label has one of four tones: neutral, progress, success, or danger.
+- The sentence is always visible. The color does not stand alone.
+
+The image is the source of truth for layout.
+
+## When to use
+
+- To show the completion label of one order, on the order page or in the order list.
+
+## When NOT to use
+
+- For a generic count or tag with no order label → use [[badge]] and pass the text as children.
+- For the four-stage progress of an order → use the order progress matter when it exists. This particle is the sentence, not the stages.
+
+---
+
+## Composition
+
+`OrderStatusBadge` is a leaf. It renders one sentence and takes no children. A `messages` entry replaces the catalogue sentence for that label. The order details header fills `messages` from its content entry. The order list passes none, so it stays on the catalogue.
+
+```text
+OrderStatusBadge
+```
+
+## Components
+
+### OrderStatusBadge
+
+No schema props. The caller passes these at runtime:
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| `state` | `'ongoing' \| 'completed' \| 'cancelled'` | — | Completion view. Sets `data-fs-order-status-badge-state`. Does not select the sentence. |
+| `label` | string | — | Completion label id. Selects the catalogue sentence. Any other string renders the placeholder. |
+| `tone` | `'neutral' \| 'progress' \| 'success' \| 'danger'` | — | Sets `data-fs-order-status-badge-tone`. Does not select the sentence. |
+
+The catalogue ids are `fs/order-status.cancelled`, `fs/order-status.cancellation-requested`, `fs/order-status.in-progress`, `fs/order-status.delivered`, `fs/order-status.shipped`, `fs/order-status.ready-for-pickup`, `fs/order-status.collected`, and `fs/order-status.placeholder`.
+
+---
+
+## Canonical schema example
+
+```json
+{
+  "order-status": {
+    "type": "OrderStatusBadge",
+    "props": {
+      "state": "completed",
+      "label": "delivered",
+      "tone": "success"
+    },
+    "style": [
+      "inline-flex items-center rounded-full px-[8px] py-[2px] text-[12px] font-medium bg-[#DCFCE7] text-[#14532D]"
+    ]
+  }
+}
+```
+
+## Common mistakes
+
+- **`StatusBadge`.** The correct name is `OrderStatusBadge`.
+- **Passing an OMS code or `statusDescription` as the text.** Pass `label` as a completion label id. The catalogue supplies the sentence.
+- **Nesting a label inside `OrderStatusBadge`.** It does not render children.
+
+---
+
+## Styling
+
+The particle sets `data-fs-badge`, `data-fs-order-status-badge`, `data-fs-order-status-badge-state`, and `data-fs-order-status-badge-tone`. It ships no color.
+
+| Component | What you style | Plausible classes |
+|---|---|---|
+| `OrderStatusBadge` | Pill label. Pick the background and text from the tone. | `inline-flex items-center rounded-full px-[8px] py-[2px] text-[12px] font-medium bg-[#DCFCE7] text-[#14532D]` |
+
+Tone pairs that meet WCAG AA: neutral `bg-[#F3F4F6] text-[#1F2937]`, progress `bg-[#DBEAFE] text-[#1E3A8A]`, success `bg-[#DCFCE7] text-[#14532D]`, danger `bg-[#FEE2E2] text-[#7F1D1D]`.
+
+---
+
+## Related
+
+- [[badge]] — generic label. `OrderStatusBadge` composes it and replaces children with the catalogue sentence.

package/dist/docs/order-summary.md

@@ -0,0 +1,53 @@
+# OrderSummary
+
+**Category:** content
+**Purpose:** The total lines of one placed order and the grand total the API returns.
+
+---
+
+## Visual cues (how to identify in an image)
+
+- A short two-column list near the bottom of an order page: a label on the left, a money amount on the right.
+- Three or more rows such as items, shipping, and discounts, then one emphasized total row.
+- A discount row may show a negative amount. A shipping row may show zero.
+
+The image is the source of truth for layout.
+
+## When to use
+
+- On `/pvt/orders/[orderId]`, where the page query reads `customerOrder`.
+
+## When NOT to use
+
+- For the cart or checkout totals → use `CartTotalizerRoot` and `CartTotalizerLine`.
+- For how the order was paid → use `OrderPayment`.
+- For the post-checkout recap → use `OrderPlacedPaymentSummary`.
+
+---
+
+## Composition
+
+Standalone. The page places it; it has no children.
+
+```text
+OrderSummary
+```
+
+## Components
+
+### OrderSummary
+
+No schema props. Every line the order carries renders, in the order the API returned them. The total row is the API's `total`; the component does not add the lines up. The heading, the grand total, and the labels for `Items`, `Shipping`, `Discounts`, `Tax`, `Change`, and `Interest` are content (`order-summary`). A blank field keeps the message catalogue. Any other id shows its upstream `name`. Interest is a total the read appends, not a line this component calculates.
+
+## Styling
+
+- `data-fs-order-summary` — the region. `flex flex-col gap-[8px]`.
+- `data-fs-order-summary-heading` — the visible title. Content wins; a blank field keeps `fs/order.totals.heading`.
+- `data-fs-order-summary-lines` — the description list.
+- `data-fs-order-summary-line` — one total row. `flex justify-between`.
+- `data-fs-order-summary-line-id` — the total id (`Items`, `Shipping`, `Discounts`, …), for styling one row.
+- `data-fs-order-summary-line-sign` — `negative`, `zero`, or `positive`.
+- `data-fs-order-summary-label`, `data-fs-order-summary-value` — the label and the amount of every row, the total included.
+- `data-fs-order-summary-total` — the total row. `font-semibold border-t pt-[8px]`.
+- `data-fs-order-summary-total-label`, `data-fs-order-summary-total-value` — the total row's own label and amount.
+- `data-fs-order-summary-skeleton`, `data-fs-order-summary-skeleton-line`, `data-fs-order-summary-skeleton-total` — the loading placeholder.

package/dist/docs/payment-method-badges.md

@@ -94,13 +94,24 @@ compiler's prop-type-driven icon collection never sees it. Same mechanism, same
 detected-network icon (see its `.md`, "Store setup: network icon declaration").
 
 **Any store composing `PaymentMethodBadges` or `AcceptedPaymentMethodBadges` must declare every name a
-configured method can resolve to in `global.icons.include`.** Either strip can resolve up to nine
-base-dialect names — `CardEntry`'s five networks plus four wallet glyphs this component adds:
+configured method can resolve to in `global.icons.include`.** Either strip can resolve up to ten
+base-dialect names — `CardEntry`'s six networks plus four wallet glyphs this component adds:
 
 ```json
 {
   "icons": {
-    "include": ["amex", "diners", "elo-card", "mastercard", "visa", "paypal", "google-pay", "pix", "stripe"]
+    "include": [
+      "amex",
+      "diners",
+      "discover",
+      "elo-card",
+      "mastercard",
+      "visa",
+      "paypal",
+      "google-pay",
+      "pix",
+      "stripe"
+    ]
   }
 }
 ```

package/dist/docs/place-order.md

@@ -1,7 +1,7 @@
 # PlaceOrder
 
 **Category:** commerce
-**Purpose:** The checkout's place-order CTA. Runs the three-call payment sequence (start transaction, the holder's direct-to-gateway submission, gateway callback), blocks interaction while it runs, and renders one inline outcome — an error message or a success confirmation — once it settles.
+**Purpose:** The checkout's place-order CTA. Runs the three-call payment sequence (start transaction, the holder's direct-to-gateway submission, gateway callback), blocks interaction while it runs, and renders one inline outcome — an error message or a success confirmation — once it settles, plus an optional status message while it runs.
 
 ---
 
@@ -51,12 +51,13 @@ Child order reflects visual order. `PlaceOrder` composes under **either** paymen
 
 ### PlaceOrder
 
-No sub-components. Renders a button and, once the sequence has settled, one inline outcome region (error or success).
+No sub-components. Renders a button, an optional status region while the sequence runs (only when `placingMessage` is authored), and, once the sequence has settled, one inline outcome region (error or success).
 
 | Prop | Type | Default | Notes |
 |------|------|---------|-------|
 | `label` | string | `"Place order"` | Button label while idle. |
 | `placingLabel` | string | `"Placing order..."` | Button label while the sequence is in flight. |
+| `placingMessage` | string | *(none)* | Status message in its own `role="status"` region beside the button while the order is being placed. Absent or blank renders nothing. The button text while placing stays `placingLabel`. |
 | `resumeLabel` | string | `"Complete your order"` | Button label while a surviving attempt offers a resume — the card already left the browser (or its fate is unknown) and the next click finalizes it instead of running the full sequence again. |
 | `successMessage` | string | `"Order placed successfully."` | Shown once the sequence settles with no errors. |
 | `missingSubmissionMessage` | string | `"Enter your payment details before placing the order."` | Shown when `placeOrder()` is invoked with no registered submission for the current path (e.g. the shopper never finished entering a card). |
@@ -68,11 +69,12 @@ No sub-components. Renders a button and, once the sequence has settled, one inli
 | `unavailableMethodMessage` | string | `"Choose another payment method before placing the order."` | Shown instead of the two document messages above when the selected method calls for a cardholder document the page is not showing — a method the card form cannot pay with, or one outside the payment root's `group` — so the shopper has to choose another payment method. |
 | `unsavedBillingAddressMessage` | string | `"Save your billing address before placing the order."` | Shown when the shopper declined "same as delivery" but never saved a custom billing address. |
 | `invalidCardDataMessage` | string | `"Enter valid card details before placing the order."` | Shown when the new-card draft itself fails validation before ever reaching the gateway. |
+| `unsupportedNetworkMessage` | string | `"This card is not from a network the store accepts. Use another card or choose another payment method."` | Shown when the typed card number is well-formed but no network the store accepts claims it, whether or not a payment method is selected. |
 | `invalidSecurityCodeMessage` | string | `"Enter a valid security code before placing the order."` | Shown when a saved-card submission is refused for a missing or invalid CVV. |
 | `gatewayErrorMessage` | string | `"Unable to complete the payment. Please try again."` | Shown when the payment gateway itself refuses the submitted card. |
 | `inFlightMessage` | string | `"This order is already being placed. Please wait."` | Shown when a click lands on an order-placement attempt whose own sequence is still running — a transaction this instance did not open, and which nothing here may finalize or re-run. |
 | `unconfirmedMessage` | string | `"We could not confirm your order yet. Your payment may still be processing, so please do not pay again."` | Shown when the payment was handed to the gateway but the order could not be confirmed, so it may still be processing. Renders in its own `role="status"` node, never in the error alert. |
-| `successHref` | string | *(none)* | Route **template** navigated to after a successful placement. The literal `{orderGroup}` is replaced with the placed order's group, percent-encoded. **Opt-in and success-gated**: no default is provided on purpose, so an absent prop keeps today's behavior byte-for-byte, and the navigation is requested only once an attempt settles with no errors and a non-null order group — never on a refusal. |
+| `successHref` | page reference or string | `{ "standard": "order-placed" }` | Page navigated to after a successful placement. A page reference gets the placed order's group as its `orderGroup` param, percent-encoded. A string is a logical path of this store, navigated as written under the binding's base path. **Success-gated**: the navigation is requested only once an attempt settles with no errors and a non-null order group — never on a refusal. |
 
 Every message prop above is resolved by the `code` of the client-synthesized `PaymentUserError` this CTA renders — in its alert, or in its status node for `unconfirmedMessage` — never by which component produced the error. A `PaymentUserError` whose code this component does not author (a server-returned code) renders that error's own `message` unchanged.
 
@@ -96,13 +98,13 @@ Every message prop above is resolved by the `code` of the client-synthesized `Pa
       "label": "Place order",
       "placingLabel": "Placing order...",
       "successMessage": "Order placed successfully.",
-      "successHref": "/checkout/order-placed/{orderGroup}"
+      "successHref": { "standard": "order-placed" }
     }
   }
 }
 ```
 
-`successHref` is shown here for reference only — it is opt-in (see the props table above), and no store composes it today. It must be a path on the store's own origin (root-relative, like the example above, or an absolute URL on the same origin) — an absolute URL on a different origin, a protocol-relative URL, or a non-http(s) scheme is refused rather than navigated to.
+`successHref` is shown here with its default value. A string must be a logical path of this store, such as `/obrigado`; an absolute URL, a protocol-relative URL, or a non-http(s) scheme is refused rather than navigated to.
 
 ---
 
@@ -118,11 +120,12 @@ Every message prop above is resolved by the `code` of the client-synthesized `Pa
 ## Known limitations
 
 - **A remount reads the surviving attempt instead of losing it — but the attempt itself does not survive a page reload.** T29 (`specs/make-an-order-attempt-survive-a.md`) gave the place-order sequence an identity-and-phase record on the payment context, above this component's own mount, alongside `placing`. Closing and reopening a `Dialog`/`Drawer` popup with no `keepMounted` no longer resets it: a settled attempt renders disabled with no further calls (`succeeded` is derived from the record, not only from this instance's own `attempted`/`userErrors`), and an attempt whose card already reached the gateway before the remount offers a resume (`resumeLabel`) that finalizes the same transaction — never a fresh `startTransaction` or a second card submission. This closes the case this bullet used to attribute to "a settled-order read model that outlives the overlay (T16/T17)": both are merged, and the limitation still stood, because neither one ever touched this component's own mount-scoped guard, which is what actually caused the duplicate-order risk. What is still not covered: a full page reload loses the attempt (no `sessionStorage` or equivalent persists it today — T29's own OQ-3), and the direct-to-gateway POST's abort budget (30s, `sdk/payment/gateway.ts`) is an unconfirmed placeholder pending a number from payments (OQ-7).
+- **A refusal raised before the card POST leaves the CTA on `label`, not `resumeLabel`.** A card form that refuses after the transaction opened but before any request was issued (a missing `sendPayments` action, an origin the gateway builder will not post to, its own draft check) reports `reachedGateway: false`, so the attempt is recorded as refused: nothing was paid, the button keeps its `label`, and the next click opens a fresh transaction. A request that reached the gateway, or that cannot be shown not to have (a rejected request, a holder that throws or resolves a malformed result), stays resume-only and reads `resumeLabel`.
+- **A failed `gatewayCallback` stays on `resumeLabel` today; the retry rule is in place but dormant.** Once the card POST was accepted, the hook only frees the next click for a callback error whose server code is neither `REDIRECT_REQUIRED` nor `MISSING_TRANSACTION_COOKIES` and that carries no `orderId`. The server sends no such code yet (task T225 will), so every callback failure that exists today (a timeout, a network failure, an unreadable result, a bank challenge, a lapsed transaction cookie) stays on `resumeLabel` and only re-issues the callback. A shopper whose card was refused still cannot enter another card without a reload until T225 lands.
 - **Sibling placement (never nested inside `CardEntry`/`SavedCards`) is a convention, not something the compiler enforces.** `requiresContext: 'payment'` only fails a build with no payment-providing ancestor at any depth; it cannot detect that this component was nested one level too deep. Getting this wrong compiles clean and still leaves the other entry path with no CTA at all (see `specs/place-order.md`'s Open items).
-- **`successHref` navigates with `router.replace`, not `router.push`.** The payment step is removed from the history stack, so the Back button from the confirmation page returns to whatever preceded payment, not to the payment step itself — deliberate (placing an order is terminal, and a live place-order CTA one Back press away risks a duplicate transaction), but a divergence from this package's other redirect-on-success component, `CartRedirectOnAdd`, which uses `push`.
-- **A `successHref` authored without the literal `{orderGroup}` placeholder fails closed.** The component refuses to navigate rather than sending every shopper to the same unresolvable URL, and logs a `console.warn` outside production. This is a store-authoring mistake to fix in the template, not a runtime condition to handle.
-- **A `successHref` that resolves off the store's own origin also fails closed.** An absolute URL on a different origin, a protocol-relative URL (`//host/...`), or a non-http(s) scheme is refused rather than navigated to, with the same dev-only `console.warn`. This keeps a store schema from turning the CTA into a redirect off the storefront right after a real purchase.
-- **`successHref` is inert until a store authors it.** As of this writing no store composes it — see `specs/navigate-the-shopper-to-the-order.md` for the follow-up that wires Reserva's payment page to it, gated on the confirmation page's read path being fixed first.
+- **`successHref` navigates with `replace`, not `push`.** The payment step is removed from the history stack, so the Back button from the confirmation page returns to whatever preceded payment, not to the payment step itself — deliberate (placing an order is terminal, and a live place-order CTA one Back press away risks a duplicate transaction), but a divergence from this package's other redirect-on-success component, `CartRedirectOnAdd`, which uses `push`.
+- **A string `successHref` that is not a path of this store fails closed.** An absolute URL, a protocol-relative URL (`//host/...`), or a non-http(s) scheme is refused rather than navigated to, with a dev-only `console.warn`. This keeps a store schema from turning the CTA into a redirect off the storefront right after a real purchase. A store without a confirmation page in its route map also stays on the payment page.
+- **Focus moves on a refused click only, never for a result the gateway returned.** When a click is refused because the cardholder document is missing or malformed, or the custom billing address was never saved, `PlaceOrder` asks the payment root to move keyboard focus to that field or form. This applies to any result that did not reach the gateway (`reachedGateway: false`) whose first error carries one of those three codes, including a code a registered submission returned itself after the transaction opened. A refusal carrying any other code, and any result that reached the gateway (a decline included, whatever its code), moves nothing, and neither does a re-render or a remount. The reason stays in the existing outcome alert.
 
 ## Styling
 
@@ -130,6 +133,7 @@ Every message prop above is resolved by the `code` of the client-synthesized `Pa
 |---|---|---|
 | `PlaceOrder` (root `div`) | Layout wrapper stacking the button and the outcome region | `flex flex-col gap-[8px] items-start` |
 | Button (`data-fs-place-order-button`) | The CTA itself — full-width pill, disabled/busy states | `inline-flex items-center justify-center w-full h-[44px] px-[20px] bg-[#C8102E] text-white rounded-[4px] text-[14px] font-bold uppercase cursor-pointer disabled:opacity-50 disabled:cursor-not-allowed` |
+| Placing (`data-fs-place-order-placing`) | The status region, present only while this CTA's own sequence runs and only when `placingMessage` is authored. Every payment leaf is `inert` for as long as it exists. | `text-[13px] text-[#666666]` |
 | Error (`data-fs-place-order-error`) | Inline error line, `role="alert"` | `text-[13px] text-[#C0392B]` |
 | Unconfirmed (`data-fs-place-order-unconfirmed`) | Inline notice that the order could not be confirmed yet, `role="status"` | `text-[13px] text-[#8A6D3B]` |
 | Success (`data-fs-place-order-success`) | Inline success line, `role="status"` | `text-[13px] text-[#1E8E3E]` |

package/dist/docs/saved-cards.md

@@ -82,7 +82,7 @@ No props beyond standard container attributes (`className`, `children`). Must be
 
 ### 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 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 typed code is cleared when the submission settles, by any route except that format refusal (which keeps it for the shopper to fix).
 
 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.
 
@@ -162,7 +162,7 @@ Style `SavedCards` as a vertical stack of rows, each row as a horizontal line (r
 | `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` |
+| Placing (`data-fs-saved-cards-placing`) | Present on `SavedCards`' own root while an order-placement sequence is in flight (T28), and while the order attempt is resume-only (its card may already have been sent, so the fields do not accept input) until the attempt is freed; the whole 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:
 

package/dist/docs/select.md

@@ -197,21 +197,34 @@ Positions the popup relative to the trigger.
 | Prop | Type | Default | Notes |
 |------|------|---------|-------|
 | `side` | `'top' \| 'bottom' \| 'left' \| 'right'` | `'bottom'` | |
-| `align` | `'start' \| 'center' \| 'end'` | `'center'` | |
+| `align` | `'start' \| 'center' \| 'end'` | `'start'` | Starts the popup at the trigger's start edge, so a popup wider than the trigger overhangs only the far side. |
 | `sideOffset` | number | `0` | |
-| `alignItemWithTrigger` | boolean | `true` | Overlaps the selected item visually with the trigger. |
+| `alignItemWithTrigger` | boolean | `false` | `true` makes the popup cover the trigger so the selected item sits on it. |
+
+By default the popup opens below the trigger and leaves the trigger and its label readable. When there is no room
+below, Base UI falls back to the top of the trigger by itself. The positioner exposes `--anchor-width`, so a popup can
+match the trigger's width with `min-width: var(--anchor-width)`.
 
 ### SelectPopup
 
 Visible container for the list. Style background, border, shadow here.
 
+The base stylesheet bounds it to the viewport: `max-height: var(--available-height)` (Base UI publishes
+`--available-height` on the positioner) and a column flex layout, so the list takes the leftover height; Tailwind's
+preflight already makes the popup `border-box`, so its border counts inside the bound. The bound lives in the
+stylesheet, not inline, so a utility such as `max-h-60` overrides it. `overflow-hidden` on the popup is harmless and
+worth keeping: the list is the scroll container, so the popup only clips what pokes past its rounded corners (a
+highlighted row's background).
+
 ### SelectArrow
 
 Pointing arrow attached to the popup. Optional — omit when the design has no anchor arrow.
 
 ### SelectList
 
-Scrollable container for `SelectItem`s (and, when grouped, `SelectGroup`s).
+Scrollable container for `SelectItem`s (and, when grouped, `SelectGroup`s). It is the scroll container: the base
+stylesheet gives it `min-height: 0` and `overflow-y: auto`, so it scrolls inside the popup's bound. A utility such as
+`overflow-visible` overrides it.
 
 ### SelectItem
 
@@ -419,7 +432,7 @@ do.
 | `SelectValue` | The chosen label / placeholder text | `flex-1 text-left` (target `data-placeholder:text-gray-400` for the empty state) |
 | `SelectIcon` | The trailing glyph | `text-gray-400` |
 | `SelectPopup` | The floating panel | `bg-white border border-gray-200 rounded-md shadow-lg overflow-hidden` |
-| `SelectList` | The scrollable list | `py-1 max-h-60 overflow-auto` |
+| `SelectList` | The list (scrolls on its own) | `py-1 max-h-60` |
 | `SelectItem` | One option row | `flex items-center gap-2 px-3 py-2 text-sm cursor-default hover:bg-blue-50 data-highlighted:bg-blue-50 data-selected:text-blue-600` |
 | `SelectGroupLabel` | A group heading inside the list | `px-3 py-1 text-xs font-semibold text-gray-500 uppercase tracking-wide` |
 | `SelectSeparator` | The divider between groups | `my-1 border-t border-gray-100` |
@@ -429,7 +442,7 @@ The four `FieldSelect.*` parts render alongside their generic counterpart's own
 class names above; the bound `data-fs-field-select-*` attributes exist for a brand that specifically
 needs to target *the bound select* without touching every generic select in the app.
 
-Styled bound example (the `BoundRecomposed` story):
+Styled bound example (the `FieldSelect.Root` of the `BoundRecomposed` story, verbatim):
 
 ```tsx
 <FieldSelect.Root>
@@ -440,7 +453,7 @@ Styled bound example (the `BoundRecomposed` story):
   <SelectPortal>
     <SelectPositioner>
       <SelectPopup className="bg-white border border-gray-200 rounded-md shadow-lg overflow-hidden">
-        <SelectList className="py-1 max-h-60 overflow-auto">
+        <SelectList className="py-1 max-h-60">
           <FieldSelect.Options className="flex items-center gap-2 px-3 py-2 text-sm cursor-default hover:bg-blue-50 data-highlighted:bg-blue-50 data-selected:text-blue-600">
             <SelectItemIndicator className="w-4 text-blue-600">✓</SelectItemIndicator>
           </FieldSelect.Options>

package/dist/docs/session.md

@@ -101,7 +101,7 @@ Shared layout with `SessionRoot` as the root, above both the header and the `Slo
       "props": { "when": ["identified", "loggedIn"] },
       "children": ["orders-link"]
     },
-    "orders-link": { "type": "NavigationLink", "props": { "href": "/orders", "children": "Meus pedidos" } },
+    "orders-link": { "type": "NavigationLink", "props": { "href": { "standard": "orders" }, "children": "Meus pedidos" } },
     "slot": { "type": "Slot", "props": {}, "children": [] }
   }
 }

package/dist/docs/shipping-address.md

@@ -93,7 +93,7 @@ Registers under the `shippingAddress` namespace with an ancestor `FormRoot`; ren
 - Compose `FormSubmit` and `FormError` as siblings, not children — the fieldset renders no submit or error part.
 - Only one `ShippingAddressFieldset` per `FormRoot`; a second one under the same `shippingAddress` namespace throws at mount.
 
-**Overriding a control's text:** every field Control also takes optional `label` and `placeholder` props. Absence means the platform's value — the active country descriptor's label where one exists (e.g. "cidade" for `CityControl`), the control's own copy where none does (`CountryControl`'s "país"). Neither has a schema default, so an author only sets one when the platform copy is wrong for their store.
+**Overriding a control's text:** every field Control also takes optional `label` and `placeholder` props. Absence means the platform's value — the active country descriptor's label where one exists (e.g. "cidade" for `CityControl`), and for `CountryControl` the descriptor's `countryLabel` ("país" for Brazil, "country" for the United States). The required message follows the same rule: `<label> <requiredSuffix>` with the descriptor's suffix ("é obrigatório", "is required"), so an authored `label` renames the field in its message too. Neither has a schema default, so an author only sets one when the platform copy is wrong for their store.
 
 **Recomposing a control's anatomy:** every field Control declares `providesContext: 'field'` (RFC:503), so a `Field.*` part composed inside one is not a context-constraint-violation. Given children, a field Control renders them in place of its default `Field.Label` / `Field.Control` / `Field.Error` (or, for `CountryControl`, `Field.Label` / `FieldSelect.Root` / `Field.Error`) — useful to reorder the label against the input or insert an icon. The binding underneath is unchanged either way.
 

package/dist/docs/sign-in-redirect.md

@@ -1,7 +1,7 @@
 # SignInRedirect
 
 **Category:** identity
-**Purpose:** The whole of the `/login` route — hands the document over to the account's platform login, carrying the shopper's way back.
+**Purpose:** The whole of the sign-in page — hands the document over to the account's platform login, carrying the shopper's way back.
 
 ---
 
@@ -13,7 +13,7 @@ The image is the source of truth for layout, and this component is not in any la
 
 ## When to use
 
-- On the `/login` page, as its only element, when the store's account lives on the VTEX platform's login rather than on the storefront.
+- On the sign-in page (`{ standard: 'sign-in' }`), as its only element, when the store's account lives on the VTEX platform's login rather than on the storefront.
 
 ## When NOT to use
 
@@ -32,7 +32,7 @@ The image is the source of truth for layout, and this component is not in any la
 SignInRedirect
 ```
 
-It requires no `SessionRoot` and declares no context: it reads nothing of the shopper's. `/login` deliberately sits outside the account layout, so a shopper who is already signed in still makes the hop.
+It requires no `SessionRoot` and declares no context: it reads nothing of the shopper's. The sign-in page deliberately sits outside the account layout, so a shopper who is already signed in still makes the hop.
 
 ## Components
 
@@ -40,7 +40,7 @@ It requires no `SessionRoot` and declares no context: it reads nothing of the sh
 
 | Prop | Type | Default | Notes |
 |------|------|---------|-------|
-| `platformLoginUrl` | string | — | The account's platform login. An absolute URL (`https://account.example.net/api/io/login`) or a site-relative path (`/api/io/login`). The storefront's own `/login` is refused, whichever way it is spelled. Required in practice: with no usable value the component renders nothing. |
+| `platformLoginUrl` | string | — | The account's platform login. An absolute URL (`https://account.example.net/api/io/login`) or a site-relative path (`/api/io/login`). The storefront's own sign-in page is refused, whichever way it is spelled. Required in practice: with no usable value the component renders nothing. |
 | `loadingLabel` | string | — | Text shown while the handover is pending. Absent renders the element with no text. |
 
 ### SignInRedirectLoading
@@ -57,7 +57,7 @@ Content model (`sign-in-redirect`) fields, edited in the CMS:
 
 **Only the return parameter crosses.** The component reads exactly one parameter from the incoming URL, `returnUrl`, and composes the destination from the authored address. Every other parameter on the incoming URL is dropped rather than forwarded into an auth URL; every parameter already on the authored address survives, because the destination is built from it.
 
-**The return is revalidated on arrival, not trusted.** `/login` is reachable by a hand-crafted link, so the value is treated as shopper-supplied whoever produced it. A return that leaves the site, is protocol-relative, or points back at `/login` itself is dropped — never rewritten into a working one — and a bounded warning names the reason. Refusing a self-referential return is what keeps a shopper who just authenticated from being handed to the platform a second time.
+**The return is revalidated on arrival, not trusted.** `returnUrl` is a logical path, without the binding's base path, and this component prefixes it before the handover, so a shopper on `/pt-BR` returns to `/pt-BR/pvt/profile`. The sign-in page is reachable by a hand-crafted link, so the value is treated as shopper-supplied whoever produced it. A return that leaves the site, is protocol-relative, or points back at the sign-in page itself is dropped — never rewritten into a working one — and a bounded warning names the reason. Refusing a self-referential return is what keeps a shopper who just authenticated from being handed to the platform a second time.
 
 **The return's form follows the address's origin.** A path alone cannot say which origin it belongs to, and the store author is the one who decides whether the receiver shares the storefront's. A same-origin address gets the site-relative path exactly as it arrived; a cross-origin one would resolve that path against its own domain, so the value is absolutized first — always against the storefront's origin, never the address's.
 
@@ -92,7 +92,7 @@ Bound to a CMS entry, the element authors no `loadingLabel` at all — the entry
 - **Expecting it to skip the hop for a signed-in shopper.** It reads no session by design, so every visitor is handed over.
 - **Authoring `$content` in the schema.** `$content` is compiler-injected from the page's content entry; naming it in `props` fails the build.
 - **Authoring `returnUrl` on `platformLoginUrl`.** The shopper's return overwrites it; author the address's other parameters instead.
-- **Pointing `platformLoginUrl` at the storefront's own `/login`.** That is this route handed to itself, which would reload the page forever; the address is refused instead. Another host's `/login` is the platform's page and is fine.
+- **Pointing `platformLoginUrl` at the storefront's own sign-in page.** That is this page handed to itself, which would reload the page forever; the address is refused instead. Another host's `/login` is the platform's page and is fine.
 - **Selecting it from a screenshot.** It has no visual identity — a sign-in screen in an image is the platform's page, not this one.
 
 ---

package/dist/docs/toast.md

@@ -21,7 +21,7 @@
 
 ## Composition
 
-`Toast` is not authored as a static PageSchema tree the way most components are. Only the **stack scaffolding** is mounted once, near the layout root:
+`Toast` is not authored as a per-toast PageSchema tree. Only the **stack scaffolding** is mounted once, near the layout root, and a `ToastViewport` with no children renders every toast itself:
 
 ```
 ToastProvider
@@ -29,7 +29,7 @@ ToastProvider
     └── ToastViewport
 ```
 
-Every `ToastRoot` inside `ToastViewport` is rendered **imperatively** by mapping over `useToast().toasts` — it does not appear as a `children` entry in any page schema. A typical per-toast render tree (authored in application code, not in a schema):
+A `ToastViewport` with no children renders one default toast per entry of `useToast().toasts` (see below), so a page schema never lists a toast. To control the markup, pass children: map over `useToast().toasts` and render a `ToastRoot` for each. A typical per-toast render tree (authored in application code, not in a schema):
 
 ```
 ToastRoot                    ← one per queued toast, keyed by toast.id
@@ -61,7 +61,11 @@ Renders `ToastViewport` into `document.body`. No props, context-only.
 
 The fixed-position stack container. Renders a `<div>` — style it directly.
 
-No props beyond standard `className`/HTML attributes.
+- **No children:** renders one default toast per active toast, in queue order: `ToastRoot` > `ToastTitle` + `ToastDescription` + `ToastAction` + `ToastClose`. Each part renders nothing when the toast has no matching text or `actionProps`, so a reversible toast shows its action between the text and the close button. The close button is named from the message catalog (`fs/toast.dismiss`); its `×` glyph is hidden from assistive technology. The default toast has no status icon and adds no `data-fs-*` hook beyond the existing ones.
+- **With children:** renders exactly those children and no default toast. `null`, `false` and `undefined` count as no children.
+- **Region name:** every viewport gets `aria-label` from the message catalog (`fs/toast.region`, "Notifications") unless you pass your own `aria-label`.
+
+No props beyond standard `className`/HTML attributes. It reads the message catalog, so it needs an intl provider ancestor (a generated app's root layout provides one).
 
 ### ToastRoot
 

package/dist/index.d.ts

@@ -4,12 +4,15 @@ import { JsonValue, StorefrontContext } from "./core/dist/schema/generated/schem
 import { ContentArraySchema, ContentNestedObjectShape, ContentObjectPropertySchema, ContentObjectSchema, ContentPropertySchema, ContentPropertyType, ContentScalarSchema, ContentScalarType, ContentTypeDefinition, ContentValue, defineContentType } from "./core/dist/define-content-type.js";
 import { ComponentDefinition, EditorMetadata, FetchStrategy, PropSchema, PropSchemaField, PropType, VariableBinding, VariableBindings, defineComponent } from "./core/dist/define-component.js";
 import "./core/dist/index.js";
+import { PageRef, ResolveHrefReason, ResolveHrefResult, RouteIdentity, RouteKind, RouteMap, RouteMapEntry, StandardName } from "./sdk/navigation/types.js";
 import { CartUserError } from "./sdk/cart/operations.js";
 import { AddItemPayload, CartActions, CartCouponPayload, CartLinePayload, CartLinesPayload, CartQuantityPayload } from "./sdk/cart/use-cart-actions.js";
 import { ClientPreferenceKey, ClientProfileUserError, CustomerProfileUserError } from "./sdk/identity/operations.js";
 import { ClientPreferencesUpdatePayload, ClientProfileUpdatePayload, CustomerProfileUpdatePayload, IdentityActions } from "./sdk/identity/use-identity-actions.js";
+import { OrderCancelOrder, OrderCancelUserError } from "./sdk/orders/order-operations.js";
+import { OrderActions, OrderCancelInput, OrderCancelResult } from "./sdk/orders/use-order-actions.js";
 import { PaymentBillingAddressUpdateInput, PaymentMethodSelectInput, PaymentMoney, PaymentUserError } from "./sdk/payment/operations.js";
-import { PaymentGatewayCard, PaymentGatewayNewCard, PaymentGatewaySavedCard, PaymentGatewayTransaction, SendPaymentsRequest } from "./sdk/payment/gateway.js";
+import { PaymentGatewayCard, PaymentGatewayNewCard, PaymentGatewayResult, PaymentGatewaySavedCard, PaymentGatewayTransaction, SendPaymentsRequest } from "./sdk/payment/gateway.js";
 import { PaymentActions, PaymentGatewayCallbackResult, PaymentStartTransactionResult } from "./sdk/payment/use-payment-actions.js";
 import { RegionUserError } from "./sdk/region/region-operations.js";
 import { RegionActions } from "./sdk/region/use-region-actions.js";
@@ -19,4 +22,5 @@ import { ShippingOptionSelectUserError } from "./sdk/shipping/option-select-oper
 import { ShippingAddressInput, ShippingAddressUpdateErrorEntity } from "./sdk/shipping/shipping-operations.js";
 import { ShippingActions } from "./sdk/shipping/use-shipping-actions.js";
 import { ComponentActions } from "./sdk/actions/types.js";
-export { type ActionSelector, type AddItemPayload, type CartActions, type CartCouponPayload, type CartLinePayload, type CartLinesPayload, type CartQuantityPayload, type CartUserError, type ClientPreferenceKey, type ClientPreferencesUpdatePayload, type ClientProfileUpdatePayload, type ClientProfileUserError, type ComponentActions, type ComponentDefinition, type ContentArraySchema, type ContentNestedObjectShape, type ContentObjectPropertySchema, type ContentObjectSchema, type ContentPropertySchema, type ContentPropertyType, type ContentScalarSchema, type ContentScalarType, type ContentTypeDefinition, type ContentValue, type CustomerProfileUpdatePayload, type CustomerProfileUserError, type EditorMetadata, type FetchStrategy, type IdentityActions, type JsonValue, type MockActions, type PaymentActions, type PaymentBillingAddressUpdateInput, type PaymentGatewayCallbackResult, type PaymentGatewayCard, type PaymentGatewayNewCard, type PaymentGatewaySavedCard, type PaymentGatewayTransaction, type PaymentMethodSelectInput, type PaymentMoney, type PaymentStartTransactionResult, type PaymentUserError, type PropSchema, type PropSchemaField, type PropType, type RegionActions, type RegionUserError, type SendPaymentsRequest, type SessionAccessCodeRequestResult, type SessionActions, type SessionPasswordLoginPayload, type SessionRequestAccessCodePayload, type SessionUserError, type SessionValidateAccessCodePayload, type ShippingActions, type ShippingAddressInput, type ShippingAddressUpdateErrorEntity, type ShippingOptionSelectUserError, type StorefrontContext, type VariableBinding, type VariableBindings, defineComponent, defineContentType, mockAction };
+import { resolveStorefrontHref } from "./sdk/navigation/resolve-storefront-href.js";
+export { type ActionSelector, type AddItemPayload, type CartActions, type CartCouponPayload, type CartLinePayload, type CartLinesPayload, type CartQuantityPayload, type CartUserError, type ClientPreferenceKey, type ClientPreferencesUpdatePayload, type ClientProfileUpdatePayload, type ClientProfileUserError, type ComponentActions, type ComponentDefinition, type ContentArraySchema, type ContentNestedObjectShape, type ContentObjectPropertySchema, type ContentObjectSchema, type ContentPropertySchema, type ContentPropertyType, type ContentScalarSchema, type ContentScalarType, type ContentTypeDefinition, type ContentValue, type CustomerProfileUpdatePayload, type CustomerProfileUserError, type EditorMetadata, type FetchStrategy, type IdentityActions, type JsonValue, type MockActions, type OrderActions, type OrderCancelInput, type OrderCancelOrder, type OrderCancelResult, type OrderCancelUserError, type PageRef, type PaymentActions, type PaymentBillingAddressUpdateInput, type PaymentGatewayCallbackResult, type PaymentGatewayCard, type PaymentGatewayNewCard, type PaymentGatewayResult, type PaymentGatewaySavedCard, type PaymentGatewayTransaction, type PaymentMethodSelectInput, type PaymentMoney, type PaymentStartTransactionResult, type PaymentUserError, type PropSchema, type PropSchemaField, type PropType, type RegionActions, type RegionUserError, type ResolveHrefReason, type ResolveHrefResult, type RouteIdentity, type RouteKind, type RouteMap, type RouteMapEntry, type SendPaymentsRequest, type SessionAccessCodeRequestResult, type SessionActions, type SessionPasswordLoginPayload, type SessionRequestAccessCodePayload, type SessionUserError, type SessionValidateAccessCodePayload, type ShippingActions, type ShippingAddressInput, type ShippingAddressUpdateErrorEntity, type ShippingOptionSelectUserError, type StandardName, type StorefrontContext, type VariableBinding, type VariableBindings, defineComponent, defineContentType, mockAction, resolveStorefrontHref };

package/dist/index.js

@@ -2,4 +2,5 @@ import { mockAction } from "./core/dist/actions/mock-action.js";
 import { defineComponent } from "./core/dist/define-component.js";
 import { defineContentType } from "./core/dist/define-content-type.js";
 import "./core/dist/index.js";
-export { defineComponent, defineContentType, mockAction };
+import { resolveStorefrontHref } from "./sdk/navigation/resolve-storefront-href.js";
+export { defineComponent, defineContentType, mockAction, resolveStorefrontHref };