@vtex/faststore 0.0.7 → 0.0.10

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"
+    ]
   }
 }
 ```
@@ -113,7 +124,7 @@ verbatim can still resolve to a declared key — `"WH Google Pay"` resolves to `
 set of names a strip can produce is wider than the store's literal method labels and has to be read off this
 list, not off the payment configuration's screen.
 
-**If the store's `global.json` already has an `icons` object, extend it — do not replace it**, for the same
+**If the store's `foundation.json` already has an `icons` object, extend it — do not replace it**, for the same
 reason `card-entry.md` gives: replacing it silently drops `collection` (or any existing `include` entries),
 and every other icon in that store re-resolves through the fallback default with no error to flag it.
 
@@ -191,7 +202,7 @@ and every other icon in that store re-resolves through the fallback default with
 
 ## Styling
 
-`PaymentMethodBadges` and `AcceptedPaymentMethodBadges` render one root you style directly, plus per-part hooks — the identical set for both, since both are produced by the same internal render path. Each carries its own catalog name, so each gets its own independent swatch entry in `global.json`'s `styles` key even though the two emit the same hooks; style each surface separately if it needs to look different.
+`PaymentMethodBadges` and `AcceptedPaymentMethodBadges` render one root you style directly, plus per-part hooks — the identical set for both, since both are produced by the same internal render path. Each carries its own catalog name, so each gets its own independent swatch entry in `foundation.json`'s `styles` key even though the two emit the same hooks; style each surface separately if it needs to look different.
 
 | Component | What you style | Plausible classes |
 |---|---|---|

package/dist/docs/payment-methods.md

@@ -48,7 +48,7 @@ FooterRoot
 
 **Nothing in the model is required, so a half-filled entry still renders.** An entry with only a heading keeps the authored `methods` prop under the merchant's heading, and vice versa. What the component drops is per item, never the whole strip: an item is skipped when its label is blank, or when it carries neither a `method` nor an `iconUrl` — an icon nobody can name is the one thing this must not ship.
 
-**Every predefined name must be registered.** A `method` resolves to a sprite symbol the store's build has to include; the store's `global.json` writes the names out under `icons.include` — it is JSON, so it cannot import `PAYMENT_METHOD_NAMES`, and a test that derives the expected set from the exported constant is what keeps the two in step. A name the store never registered renders an empty `<svg>` — no build error and no runtime error, just a missing flag.
+**Every predefined name must be registered.** A `method` resolves to a sprite symbol the store's build has to include; the store's `foundation.json` writes the names out under `icons.include` — it is JSON, so it cannot import `PAYMENT_METHOD_NAMES`, and a test that derives the expected set from the exported constant is what keeps the two in step. A name the store never registered renders an empty `<svg>` — no build error and no runtime error, just a missing flag.
 
 ---
 

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/product-information.md

@@ -96,7 +96,7 @@ Renders the product description, optionally collapsed behind a "show more" toggl
 | `moreLabel` | string | `'Show more'` | Trigger label shown when the panel is collapsed. Localize per storefront (e.g. `'mais informações'` for pt-BR). |
 | `lessLabel` | string | `'Show less'` | Trigger label shown when the panel is expanded (e.g. `'menos informações'`). |
 
-The wrapper element follows from the resolved branch: plain text renders as `<p>` (semantic body-text exposure for screen-reader paragraph navigation and SEO); rich HTML renders as `<div>` so block-level markup inside `descriptionHtml` (`<p>`, `<ul>`, headings) stays valid DOM. The element that hosts the rendered description text carries `data-fs-text=""` so project-level `Text` typography defined in `global.json` cascades to the description automatically — no need to repeat font, size, color, leading, or tracking classes inline on every description node. With `collapse: 'none'` that element is the wrapper itself; with `collapse: 'showMore'` or `'section'` it is the panel (the `Collapsible.Root` and the trigger `<button>` deliberately do not carry it so body typography does not cascade onto the trigger label).
+The wrapper element follows from the resolved branch: plain text renders as `<p>` (semantic body-text exposure for screen-reader paragraph navigation and SEO); rich HTML renders as `<div>` so block-level markup inside `descriptionHtml` (`<p>`, `<ul>`, headings) stays valid DOM. The element that hosts the rendered description text carries `data-fs-text=""` so project-level `Text` typography defined in `foundation.json` cascades to the description automatically — no need to repeat font, size, color, leading, or tracking classes inline on every description node. With `collapse: 'none'` that element is the wrapper itself; with `collapse: 'showMore'` or `'section'` it is the panel (the `Collapsible.Root` and the trigger `<button>` deliberately do not carry it so body typography does not cascade onto the trigger label).
 
 Rich HTML is rendered via `dangerouslySetInnerHTML`; Storefront API Core sanitizes `descriptionHtml` upstream, so this is safe for first-party catalogs.
 
@@ -253,7 +253,7 @@ The main heading — large and bold. Typical: `text-[20px] leading-[1.3] font-se
 
 ### ProductInformationDescription
 
-Body copy — smaller, lighter, comfortable line height. Typical: `text-[14px] leading-[1.6] font-normal text-[#666666]`. The element that hosts the text carries `data-fs-text=""` in every collapse mode (the wrapper itself for `collapse: 'none'`, the panel for `'showMore'` and `'section'`), so if the project's `global.json` defines `Text.base` with the body-text typography (font, size, leading, weight, color), those styles cascade to the description automatically and no inline typography classes are needed on the description node.
+Body copy — smaller, lighter, comfortable line height. Typical: `text-[14px] leading-[1.6] font-normal text-[#666666]`. The element that hosts the text carries `data-fs-text=""` in every collapse mode (the wrapper itself for `collapse: 'none'`, the panel for `'showMore'` and `'section'`), so if the project's `foundation.json` defines `Text.base` with the body-text typography (font, size, leading, weight, color), those styles cascade to the description automatically and no inline typography classes are needed on the description node.
 
 When `collapse` is `'showMore'` or `'section'`, the trigger element is a real `<button>` rendered as a sibling of the panel inside the Collapsible root. Style it via the `data-fs-product-information-description-trigger` attribute hook so the trigger inherits the description's flex container without being centered or stretched. Typical: `[&_[data-fs-product-information-description-trigger]]:self-start [&_[data-fs-product-information-description-trigger]]:text-[14px] [&_[data-fs-product-information-description-trigger]]:font-medium [&_[data-fs-product-information-description-trigger]]:underline`. Pair with the brand's link color via an arbitrary hex (e.g. `[&_[data-fs-product-information-description-trigger]]:text-[#e60014]`).
 

package/dist/docs/product-shelf.md

@@ -26,11 +26,14 @@ The image is the source of truth for the heading text, `first`/`itemsPerPage`, a
 
 - A cross-sell / discovery shelf on the PDP (Related Products), PLP, or Search Results: a facet-scoped, navigable carousel of product cards configured entirely in the VTEX Studio.
 
+- A shelf inside a conditional branch that is often not shown, such as the empty state of the cart: use `ProductShelfOnMountRoot`. It is the same shelf, but its data is fetched by the client when the element mounts and never reaches the server HTML or the page query.
+
 ## When NOT to use
 
 - A full-page product listing driven by the route/search → use `ProductListRoot` (prop-driven) with the PLP grid.
 - PDP single-product pricing → use `PricingRoot` (it fetches one `productBySlug`; it cannot price a per-card item in a list).
 - A generic non-product track of children → use the `Carousel` particle directly.
+- `ProductShelfOnMountRoot` above the fold, or anywhere the products must be in the server HTML → use `ProductShelfRoot`.
 
 ---
 
@@ -66,6 +69,10 @@ The image is the source of truth for the heading text, `first`/`itemsPerPage`, a
 | `$data` | slice | — | Compiler-injected fragment result |
 | `products` | `ProductShelfItem[]` | — | Pre-shaped items (stories/tests; bypasses `$data`). Rendered as given: `first` does not limit them |
 
+### ProductShelfOnMountRoot
+
+`ProductShelfRoot` with `fetchStrategy: 'lazy-on-mount'`. It renders `ProductShelfRoot` and reuses its fragment, `variables` block and props (all of the table above except `$content` and `$data`). The difference is delivery: the page query never selects its `products` field, and the client sends the request, in its own operation, only when the element mounts. The generated page wraps it in a `HotDataProvider` with a `null` fallback, so until the response arrives, and when the request fails or returns no products, it renders nothing (no skeleton). Without that provider and without a `products` prop it has no source and renders the loading skeleton permanently; pass `products` outside a generated page. It has no content model, so its variables come from props only. Place it inside a conditional branch (for example `CartEmpty`), never above the fold; a layout cannot compose it.
+
 ### Content model `product-shelf`
 
 `ProductShelfContent` declares the merchant-facing fields: `first` (number, minimum 1), `sort` (the eight members above), `categoryId`, `brandId`, `collectionId`, `searchTerm` (string) and `availableOnly` (boolean). None is required. In a store with a `cms` binding the merchant fills them in the Content Platform entry keyed by the element id, and the shelf re-queries on the next request with no deploy; an empty field falls to the prop, and an empty facet relaxes the filter.

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

@@ -26,10 +26,9 @@ Signals that distinguish it from other controls:
 - A **country/region selector** (ISO codes resolved to display names), a **sort-order dropdown**, or a
   **quantity/unit picker** are the most common PDP/checkout uses.
 
-This particle currently has no `store-editor` knowledge-base row: it is a leaf control with no
-distinct visual region of its own, and the bound `FieldSelect.*` parts cannot be generated from a
-screenshot without the bound Control that consumes them (`ShippingAddressCountryControl`). This section documents the
-visual pattern for a human reader; it is not wired into image→schema detection.
+This particle is a leaf control with no distinct visual region of its own, and the bound `FieldSelect.*`
+parts cannot be generated from a screenshot without the bound Control that consumes them
+(`ShippingAddressCountryControl`). This section documents the visual pattern for a human reader.
 
 ---
 
@@ -197,21 +196,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 +431,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 +441,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 +452,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.