@vtex/faststore 0.0.7 → 0.0.8

package/dist/docs/order-list-views.md

@@ -0,0 +1,97 @@
+# OrderListViews
+
+**Category:** navigation
+**Purpose:** Four links that ask the orders page for every order, or only the ongoing, completed, or cancelled ones.
+
+---
+
+## Visual cues (how to identify in an image)
+
+- A short row of four text choices, one of them visually current.
+- The words name groups of orders (all, ongoing, completed, cancelled), not individual status codes such as "Payment denied" or "Invoiced".
+- Each choice is its own link. The row is not a set of tabs with a panel of orders inside it.
+
+The image is the source of truth for layout.
+
+## When to use
+
+- On the orders page, as the control that switches the list among the four views.
+
+## When NOT to use
+
+- For the rows, the empty sentences, or the page controls → those belong to the list, which reads the params this switch writes.
+- For the search field and the placed-date range → those are a separate control that writes `search`, `placedFrom`, and `placedTo`.
+- For a filter of individual order statuses → this switch has exactly four choices.
+- For tabbed content whose panel lives inside the control → use [[tabs]].
+
+---
+
+## Composition
+
+`OrderListViews` is a leaf element in the PageSchema. It renders its own four links and takes no children. The list is a sibling on the page, not a child of this element.
+
+```text
+OrderListViews
+```
+
+## Components
+
+### OrderListViews
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| `label` | string | `Order views` | Accessible name of the navigation landmark. |
+| `allLabel` | string | `All orders` | Visible name of the all-orders choice. |
+| `ongoingLabel` | string | `Ongoing` | Visible name of the ongoing choice. |
+| `completedLabel` | string | `Completed` | Visible name of the completed choice. |
+| `cancelledLabel` | string | `Cancelled` | Visible name of the cancelled choice. |
+
+Content model (`order-list-views`) fields, edited in the CMS. A non-blank field wins over the matching prop. A blank field falls through to the prop, then to the default. A blank field does not remove a choice.
+
+| Field | Type | Required | Notes |
+|-------|------|----------|-------|
+| `label` | string | no | Accessible name. Maps to `label`. |
+| `all` | string | no | Maps to `allLabel`. |
+| `ongoing` | string | no | Maps to `ongoingLabel`. |
+| `completed` | string | no | Maps to `completedLabel`. |
+| `cancelled` | string | no | Maps to `cancelledLabel`. |
+
+**The href values are fixed.** All orders omits `view`. The other three set `view` to `ongoing`, `completed`, or `cancelled`. Renaming a label does not change the param. The switch also deletes `after` and keeps every other search param, including `search`, `placedFrom`, and `placedTo`.
+
+**An unrecognized `view` shows all orders as current.** The component does not add a fifth choice and does not replace the URL on render.
+
+**No fragment.** This matter does not read `customerOrders` and does not decide which orders belong in a view.
+
+---
+
+## Canonical schema example
+
+```json
+{
+  "order-views": {
+    "type": "OrderListViews",
+    "props": {
+      "label": "Order views",
+      "allLabel": "All orders",
+      "ongoingLabel": "Ongoing",
+      "completedLabel": "Completed",
+      "cancelledLabel": "Cancelled"
+    },
+    "children": [],
+    "style": ["flex flex-wrap gap-[8px]"]
+  }
+}
+```
+
+## Common mistakes
+
+- Composing `TabsRoot` with a panel of orders inside this element. The list is a sibling. Choosing a view loads the page again.
+- Authoring one link per OMS status. The set is the four views.
+- Putting the order number, or a search term, into a label. Labels are the view names. The param values stay the four constants.
+- Filtering the orders already rendered in the browser. Ongoing is computed on the server.
+
+## Styling
+
+No CSS file. The landmark carries `data-fs-order-list-views` and `data-fs-order-list-views-current` (`all`, `ongoing`, `completed`, or `cancelled`). Each link carries `data-fs-order-list-views-choice` set to the same value. The current link also carries `data-fs-order-list-views-choice-current`.
+
+A row of choices is `flex flex-wrap gap-[8px]` on the landmark. The current choice is typically `font-semibold` with a bottom border, targeted with `data-[fs-order-list-views-choice-current]:font-semibold`.

package/dist/docs/order-list.md

@@ -0,0 +1,94 @@
+# OrderList
+
+**Category:** content
+**Purpose:** One page of the signed-in shopper's orders, with a count, a way to the next page, and a sentence for each kind of empty page.
+
+---
+
+## Visual cues (how to identify in an image)
+
+- A vertical list of order rows. Each row is one clickable unit carrying an order number, a date, a money amount, a count, and a short status label.
+- A line above the rows such as "3 of 40", then a column header for the order number, the placed date, the total, the item count, the status, and the estimate.
+- A text link after the rows such as "Next page" or "Load more".
+- An empty page is a sentence, sometimes with the search term still visible and a "Clear search" or "Start shopping" link.
+
+The image is the source of truth for layout.
+
+## When to use
+
+- The orders page, for the page of orders itself.
+
+## When NOT to use
+
+- For the four view links → use `OrderListViews`.
+- For the order-number field and the placed-date range → use `OrderListSearch`.
+- For one order's full detail → use the order page, not this list.
+- For the status sentence alone → use `OrderStatusBadge`.
+
+---
+
+## Composition
+
+`OrderList` is a leaf in the page schema. It renders each `OrderListRow` itself. Do not place `OrderListRow` as a child.
+
+```text
+OrderList
+```
+
+Child order is not applicable. The row order is the order of the connection.
+
+## Components
+
+### OrderList
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| label | string | `Orders` | Accessible name of the region |
+| advance | `pages` \| `load-more` | `pages` | Label of the control that asks for the next cursor. Both modes load the page again |
+| startShoppingHref | link | `{ standard: 'home' }` | Link offered when the account has no orders. An unsafe string falls back to the home page |
+| orderHref | link | `{ standard: 'order' }` | The order page each row links to. The row fills `orderId`, so the store's order page must take `[orderId]`; a string is the path the orders live under, and the row appends the encoded id |
+
+Page size is not a prop. The fragment always reads 25.
+
+### OrderListRow
+
+No schema props. The list passes one order. Do not place this component in a page schema.
+
+## Data
+
+The fragment reads `customerOrders(first: 25)`. `after`, `view`, `search`, `placedFrom`, and `placedTo` come from the page URL. Each row reads `id`, `placedAt`, `total`, `itemCount`, `completion`, and the two shipping estimate instants. The OMS status string is not selected.
+
+## Styling
+
+Style the region, the count, each fact, and the links through their hooks. Inline classes only.
+
+- `data-fs-order-list` — the region. `flex flex-col gap-[16px]`.
+- `data-fs-order-list-advance` — `pages` or `load-more`.
+- `data-fs-order-list-count` — the count sentence. `text-[14px] text-[#4B5563]`.
+- `data-fs-order-list-columns` — the column header, shown when the page has rows. Each label is `data-fs-order-list-column` (`id`, `placed`, `total`, `items`, `status`, `estimate`).
+- `data-fs-order-list-row` — one order. `flex flex-col gap-[4px] rounded-[8px] border border-[#E5E7EB] p-[16px]`.
+- `data-fs-order-list-row-state` — `ongoing`, `completed`, or `cancelled`.
+- `data-fs-order-list-row-id` — the order number. `text-[16px] font-medium text-[#111827]`.
+- `data-fs-order-list-row-placed`, `data-fs-order-list-row-total`, `data-fs-order-list-row-count` — the facts. `text-[14px] text-[#374151]`.
+- `data-fs-order-list-row-estimate` — the delivery estimate on an ongoing row. `text-[14px] text-[#1D4ED8]`.
+- `data-fs-order-list-empty` — `account`, `view`, `search`, `past-end`, or `walk-stopped`.
+- `data-fs-order-list-error` — the failed read.
+- `data-fs-order-list-next`, `data-fs-order-list-first`, `data-fs-order-list-clear`, `data-fs-order-list-retry`, `data-fs-order-list-start` — the links. `text-[14px] font-medium text-[#1D4ED8]`.
+
+## Canonical schema
+
+```json
+{
+  "orders": {
+    "type": "OrderList",
+    "props": {
+      "label": "Orders",
+      "advance": "pages"
+    },
+    "style": {
+      "default": "flex flex-col gap-[16px]"
+    },
+    "children": []
+  }
+}
+```

package/dist/docs/order-payment.md

@@ -0,0 +1,94 @@
+# OrderPayment
+
+**Category:** content
+**Purpose:** The payments recorded on one of the signed-in shopper's orders: method, amount, installments, gift-card code, bank-invoice number, and the print link while the order can still be cancelled.
+
+---
+
+## Visual cues (how to identify in an image)
+
+- A titled block on an order page, usually "Payment", listing one or more payment rows.
+- Each row shows a payment method name, often with a small card or wallet brand mark, and a money amount.
+- A row may add a short installment sentence such as "3x R$ 100,00", a labeled gift-card code, or a labeled bank-invoice number.
+- A text link such as "Print bank invoice" appears next to a bank-invoice row only while the order is still open.
+
+The image is the source of truth for layout.
+
+## When to use
+
+- The order details page, for the section that shows how the order was paid.
+
+## When NOT to use
+
+- For the totals card (subtotal, shipping, discounts, total) → use the order summary.
+- For the payment recap on the post-checkout confirmation page → use `OrderPlacedPaymentSummary`.
+- For the strip of accepted payment brands → use `PaymentMethodBadges` or `AcceptedPaymentMethodBadges`.
+
+---
+
+## Composition
+
+`OrderPayment` is a leaf in the page schema. It renders every payment row itself.
+
+```text
+OrderPayment
+```
+
+Child order is not applicable. The row order is the order of the read.
+
+## Components
+
+### OrderPayment
+
+No schema props. The heading and the bank-invoice method name are content.
+
+| Content field | Description |
+|---|---|
+| heading | Section heading. Blank falls back to the catalogue sentence |
+| bankInvoiceName | Method name shown on a payment that carries a bank-invoice number or print URL |
+| empty | Sentence when the order has no payment |
+| methodPlaceholder | Sentence when the method name is missing |
+| installments | Installment line. Keep `{count}` and `{amount}` |
+| redemptionCode | Label of the gift-card code |
+| bankInvoiceNumber | Label of the bank-invoice number |
+| bankInvoicePrint | Print-link sentence |
+
+A blank field keeps the catalogue sentence. Amounts, recorded method names, and the last four digits stay data.
+
+## Data
+
+The fragment reads `customerOrder(id: $orderId)`: `allowCancellation` and, for each payment, `methodName`, `lastDigits`, `amount`, `installments`, `redemptionCode`, `bankInvoiceNumber`, and `bankInvoicePrintUrl`. The last four digits render after the method name when present. No transaction identifier, card BIN, or document is selected.
+
+## Styling
+
+Style the region, the heading, each row, and each fact through their hooks. Inline classes only.
+
+- `data-fs-order-payment` — the region. `flex flex-col gap-[12px]`.
+- `data-fs-order-payment-heading` — the heading. `text-[18px] font-semibold text-[#111827]`.
+- `data-fs-order-payment-empty` — the sentence shown when the order has no payment.
+- `data-fs-order-payment-list` — the list of rows. `flex flex-col gap-[8px]`.
+- `data-fs-order-payment-item` — one payment. `flex flex-wrap items-center gap-[8px] rounded-[8px] border border-[#E5E7EB] p-[12px]`.
+- `data-fs-order-payment-item-bank-invoice` — present on a bank-invoice row.
+- `data-fs-order-payment-method` — the icon and the name. `flex items-center gap-[8px]`.
+- `data-fs-order-payment-icon` — the brand mark, only for a known method. `h-[24px] w-[36px]`.
+- `data-fs-order-payment-method-name` — the method name. `text-[14px] font-medium text-[#111827]`.
+- `data-fs-order-payment-amount` — the full amount. `text-[14px] text-[#374151]`.
+- `data-fs-order-payment-installments` — the installment sentence. `text-[14px] text-[#6B7280]`.
+- `data-fs-order-payment-redemption-code`, `data-fs-order-payment-bank-invoice-number` — a labeled fact. Inside each, `data-fs-order-payment-label` and `data-fs-order-payment-value`. `text-[14px] text-[#374151]`.
+- `data-fs-order-payment-print` — the print link. `text-[14px] font-medium text-[#1D4ED8]`.
+- `data-fs-order-payment-skeleton`, `data-fs-order-payment-skeleton-row` — the loading placeholder.
+
+## Canonical schema
+
+```json
+{
+  "payment": {
+    "type": "OrderPayment",
+    "props": {},
+    "style": {
+      "default": "flex flex-col gap-[12px]"
+    },
+    "children": []
+  }
+}
+```

package/dist/docs/order-placed-date.md

@@ -0,0 +1,49 @@
+# OrderPlacedDate
+
+**Category:** content
+**Purpose:** The date and time one order was placed, formatted for the page locale.
+
+---
+
+## Visual cues (how to identify in an image)
+
+- A short label ("Order placed") beside or above one date with a time.
+- No status, no money, no product. Usually sits under the first stage of the order progress or in the order header.
+
+The image is the source of truth for layout.
+
+## When to use
+
+- On the order details page, wherever the merchant wants the placed date. It can be placed more than once; every position shows the same value.
+
+## When NOT to use
+
+- For a list of orders → `OrderListRow` already shows each order's placed date.
+- For a delivery estimate → that belongs to the delivery group.
+
+---
+
+## Composition
+
+Standalone. Place it anywhere under the order details page.
+
+```text
+OrderPlacedDate
+```
+
+## Data
+
+Fragment on `Query`: `customerOrder(id: $orderId) { id placedAt }`. The generator binds `$data` to that root field, so the prop is the order itself. When `placedAt` is missing the component renders nothing.
+
+## Components
+
+### OrderPlacedDate
+
+No schema props. The label is content (`order-placed-date`). A blank field keeps `fs/order.placed-at`.
+
+## Styling
+
+- `data-fs-order-placed-date` — the root. `flex flex-col gap-[4px]`.
+- `data-fs-order-placed-date-label` — the label. `text-[12px] uppercase text-[#6B7280]`.
+- `data-fs-order-placed-date-value` — the `time` element. `text-[14px] font-medium`.
+- `data-fs-order-placed-date-skeleton`, `data-fs-order-placed-date-skeleton-fact` — the loading placeholder.

package/dist/docs/order-placed-payment-summary.md

@@ -11,11 +11,13 @@ Use these signals to detect that an OrderPlacedPaymentSummary block is present.
 
 An OrderPlacedPaymentSummary block, on an order-confirmation / "thank you" screen, contains any ONE of:
 
-- A short **line naming a card network** (e.g. "Visa", "Mastercard") optionally followed by **masked last four digits** (e.g. "•••• 1111"), optionally with a **custom card label/nickname** line below it (e.g. "Meu cartão pessoal").
+- A short **line naming a card network** (e.g. "Visa", "Mastercard") optionally followed by **masked last four digits** (e.g. "•••• 1111").
 - A **non-card method's own name** (e.g. "Boleto Bancário"), with no masked digits at all.
-- An **inline alert/notice line** (visually a warning or error banner) saying the payment details could not be loaded, or that the order was split across sellers.
+- An **inline alert/notice line** (visually a warning or error banner) saying the payment details could not be loaded.
 - An **informational line** (visually plain, not a warning) saying no payment record is available.
 
+The order system sends no card label or nickname, so a saved card's nickname never appears in this block.
+
 No copy is baked into this block beyond those lines — any surrounding "Payment" heading is host-page chrome, not part of this component.
 
 If the image shows this recap on an **in-checkout** surface (Order Review, still-live cart) instead, this is not the component — see [When NOT to use](#when-not-to-use).
@@ -55,20 +57,18 @@ It requires no ancestor context and provides none — composable standalone on a
 | Prop | Type | Default | Notes |
 |------|------|---------|-------|
 | `lastFourTemplate` | string | `"•••• {lastFour}"` | Rendered whenever the projection carries a last four digit — for both a saved and a freshly-entered card. |
-| `noPaymentRecordLabel` | string | `"Payment method not available"` | Shown when the order resolves but carries no projectable payment record (all of network/last-four/label are null). Informational — not an alert. |
+| `noPaymentRecordLabel` | string | `"Payment method not available"` | Shown when the order resolves but carries no projectable payment record (network and last four are both null). Informational — not an alert. |
 | `unresolvedOrderLabel` | string | `"Could not load the payment details"` | Shown, as an inline `role="alert"`, when the order group does not resolve to a settled order. |
-| `multiSellerNotice` | string | `"This order was split across {count} sellers; the payment summary does not cover split orders"` | Shown, as an inline `role="alert"`, for a split (multi-seller) order; `{count}` placeholder, omitted (token dropped, no literal "undefined"/"NaN") when the seller count is unknown. |
 | `installmentTemplate` | string | `"{count}x of {total}"` | Rendered whenever the projection carries an `installment` (count always present when it does); `{count}`/`{total}` placeholders — when the source carries the count but not enough to build a settled total from, everything between `{count}`'s own glued suffix (if any) and `{total}` is dropped together with the token itself (e.g. " of " in the shipped default), so the line reads "6x" rather than ending mid-sentence. A run glued directly to `{count}`, with no separating whitespace, is that count's own suffix rather than a connector, and is kept: `"{count}x {total}"` and `"{count}x{total}"` both degrade to "6x", never to a bare "6" or an empty line. This applies to the WHOLE run between the glued suffix and `{total}`, not just one word — a self-contained unit noun with no glued suffix (e.g. `"{count} parcelas de {total}"`) degrades to a bare "6", the same as a dangling preposition would, because no algorithm can tell the two apart (T31). Never a per-installment amount or interest rate — the source carries neither (see [When NOT to use](#when-not-to-use)). |
 
-**Data:** declares its own `fragment OrderPlacedPaymentSummaryData on Query` selecting `Query.order(orderGroup: $orderGroup)` — `network`, `lastFourDigits`, `label`, `installment { count total { amount currencyCode } }`. `$orderGroup` is resolved by the compiler from a route segment or page search param, never passed as a prop. `fetchStrategy: 'reactive'` — required so the compiler hoists the `PageReactiveDataRoot` this component reads the multi-seller signal through.
+**Data:** declares its own `fragment OrderPlacedPaymentSummaryData on Query` selecting `Query.order(orderGroup: $orderGroup)` — `network`, `lastFourDigits`, `installment { count total { amount currencyCode } }`. `$orderGroup` is resolved by the compiler from a route segment or page search param, never passed as a prop. `fetchStrategy: 'reactive'` — required so the compiler hoists the `PageReactiveDataRoot` this component reads its loading state through.
 
-**Resolution:** exactly one of five states renders, in this fixed precedence:
+**Resolution:** exactly one of four states renders, in this fixed precedence. A purchase split across sellers is read whole, so no error has a state of its own: a failed read leaves `order: null` and renders the unresolved notice.
 
-1. **Multi-seller** — the reactive root's query error carries `extensions.code === 'UNSUPPORTED_MULTI_SELLER_ORDER'`. Wins over everything else, including a resolved recap, because a split order's one-seller card would otherwise be shown as if it were the whole payment.
-2. **In flight** — `loading` is true and no data has resolved yet. Renders nothing; never flashes an alert on first paint.
-3. **Unresolved** — the order group does not resolve (`order: null`) and the query is no longer in flight. Inline `role="alert"`.
-4. **No payment record** — the order resolves but `network`, `lastFourDigits`, and `label` are all null. Informational line, not an alert — `Query.order` treats this as a legitimate resolved state. Unchanged by the installment widening: an order carrying only an installment still renders this state, never a recap with just the installment line.
-5. **Recap** — the network (and last four, whenever present, and the saved-card label, whenever set, and the installment count + settled total, whenever the settled record reports one).
+1. **In flight** — `loading` is true and no data has resolved yet. Renders nothing; never flashes an alert on first paint.
+2. **Unresolved** — the order group does not resolve (`order: null`) and the query is no longer in flight. Inline `role="alert"`.
+3. **No payment record** — the order resolves but `network` and `lastFourDigits` are both null. Informational line, not an alert — `Query.order` treats this as a legitimate resolved state. Unchanged by the installment widening: an order carrying only an installment still renders this state, never a recap with just the installment line.
+4. **Recap** — the network (and last four, whenever present, and the installment count + settled total, whenever the settled record reports one).
 
 ---
 
@@ -92,24 +92,22 @@ There is no surface-specific prop or variant — the same element renders the sa
 - **Using this component on an in-checkout surface (Order Review).** Its data source is the settled order, keyed on an order group that does not exist until the order is placed. No component renders a payment recap in checkout.
 - **Adding a per-installment amount or interest rate.** The settled-order source carries neither; only the installment count and settled total are shown.
 - **Treating "no payment record" the same as "unresolved".** They are visually and semantically distinct: the former is informational (the order is real, it just has nothing to project), the latter is an alert (the order group itself did not resolve).
-- **Aggregating a multi-seller order's cards.** A split order always renders the notice, never a per-seller breakdown.
+- **Expecting every payment of the purchase.** The recap shows the purchase's first payment; `Order.payments` lists them all, and no component renders that list yet.
 - **Expecting a full card number or CVV field.** The fragment structurally selects neither.
 
 ---
 
 ## Styling
 
-Single DOM root, with up to three text lines beneath it for the recap state (method, label, installment), or a single text line for every other visible state.
+Single DOM root, with up to two text lines beneath it for the recap state (method, installment), or a single text line for every other visible state.
 
 | Component | What you style | Plausible classes |
 |---|---|---|
 | `OrderPlacedPaymentSummary` (root `div`) | Stacks the recap lines | `flex flex-col gap-[2px]` |
 | Method line (`data-fs-order-placed-payment-summary-method`) | The primary recap line — network + masked last four | `text-[14px] font-medium text-[#1A1A1A]` |
-| Label line (`data-fs-order-placed-payment-summary-label`) | Shopper-assigned card nickname — quieter, secondary | `text-[12px] text-[#666666]` |
 | Installment line (`data-fs-order-placed-payment-summary-installment`) | Installment count + settled total, whenever the settled record reports one | `text-[12px] text-[#666666]` |
 | No-record line (`data-fs-order-placed-payment-summary-no-record`) | Informational, not a warning | `text-[13px] text-[#666666]` |
 | Unresolved notice (`data-fs-order-placed-payment-summary-unresolved`, `role="alert"`) | Warning-toned notice | `text-[13px] font-medium text-[#B00020]` |
-| Multi-seller notice (`data-fs-order-placed-payment-summary-multi-seller`, `role="alert"`) | Warning-toned notice | `text-[13px] font-medium text-[#B00020]` |
 
 Styled example:
 

package/dist/docs/order-placed.md

@@ -0,0 +1,225 @@
+# OrderPlaced
+
+**Category:** commerce
+**Purpose:** The order confirmation's owner and its purchase blocks. `OrderPlacedRoot` reads the placed order (`Query.order`) once and shares it; `OrderPlacedStatus`, `OrderPlacedReference`, `OrderPlacedCustomer` and `OrderPlacedTotals` show the payment outcome, the reference support recognizes, the customer and the totals. `OrderPlacedDeliveryList`, `OrderPlacedDeliveryGroup`, `OrderPlacedItemRow` and `OrderPlacedItemCompositions` show the items grouped by delivery, each item as the cart presented it. All of it comes from the order's own record.
+
+---
+
+## Visual cues (how to identify in an image)
+
+These blocks appear on an order confirmation ("thank you") screen, after the purchase. Any ONE of these signals one of them:
+
+- A **banner** with a title and a message stating the payment outcome: confirmed, being confirmed, or not approved. Usually tinted by tone.
+- A **short line with the order number** (e.g. "Order #1234567890123").
+- **Label/value rows about the buyer**: name, email, phone, document.
+- **Label/value rows of money**: subtotal, discounts, shipping, tax, then a total.
+- **One box per delivery**: a shipping method, a promise ("Arrives by Oct 23, 2026" or "in 2 business days"), an item count, an address or a pickup point, and the items under it with image, name, variant, quantity and price, add-ons nested under their item.
+- In place of all of them, **one alert line** saying the order cannot be shown or could not be loaded.
+
+Section titles ("Customer information", "Summary") and the boxes around the blocks are page chrome: a `Text` and a `Container`, not part of these components.
+
+---
+
+## When to use
+
+- The order confirmation page, keyed on the order group from the route (`/checkout/order-placed/[orderGroup]`).
+- Under `OrderPlacedRoot`, any block that reads the placed order: the blocks below and the payment recap.
+
+## When NOT to use
+
+- **In checkout, before the order is placed** → there is no order group yet. The review step reads the cart: `CartTotalizerLine`, `IdentitySummary*`.
+- **To show the live cart or profile** → these blocks read the order as it was placed, on purpose. A cart that changes after the purchase never changes this page.
+- **To show the payment method** → `OrderPlacedPaymentSummary`, composed under the root.
+- **To group the items by seller** (formats B, C, D) → not shipped yet; this page groups by delivery only.
+
+---
+
+## Composition
+
+```
+OrderPlacedRoot                 fragment on Query.order; provides order-placed
+├─ OrderPlacedStatus            ctx order-placed → status; authored copy
+├─ OrderPlacedReference         ctx order-placed → reference
+├─ OrderPlacedCustomer          its own fragment → customer; requires order-placed
+├─ OrderPlacedTotals            ctx order-placed → totals, total
+├─ OrderPlacedDeliveryList      its own fragment → deliveries; provides order-delivery per delivery
+│  └─ OrderPlacedDeliveryGroup  ctx order-delivery; provides address-summary
+│     ├─ AddressSummaryRecipient, -Street, -Locality
+│     └─ OrderPlacedItemRow     per item: the cart's CartItemRoot; provides cart-item-data, order-placed-item
+│        ├─ CartItemImage, -Name, -Variant, -QuantityValue, -LineTotal, … (the cart's leaves)
+│        └─ OrderPlacedItemCompositions
+└─ OrderPlacedPaymentSummary    its own fragment
+```
+
+`OrderPlacedDeliveryList` takes one group and renders it once per delivery; `OrderPlacedItemRow` takes the item leaves and renders them once per item.
+
+The compiler merges every fragment on `Query.order` into one request. `OrderPlacedCustomer` and `OrderPlacedDeliveryList` select personal data (the customer, the delivery addresses) through their own fragments, so a page with neither fetches none. The children can be wrapped in `Container` and `Text` for boxes and titles.
+
+---
+
+## Components
+
+### OrderPlacedRoot
+
+Reads the order and renders exactly one state, in this order:
+
+| State | When | Renders |
+| --- | --- | --- |
+| Refused | The API refused the read (`UNAUTHORIZED`): after 15 minutes, or from another browser | `refusedOrderLabel`, `role="alert"` |
+| Loading | The read is in flight with no order | `OrderPlacedRootSkeleton` |
+| Unresolved | The read settled with no order: an upstream or network error, or no order for the group | `unresolvedOrderLabel`, `role="alert"` |
+| Order | The order resolved | Its children |
+
+A refusal also arrives with `order: null`, which is why it is checked first. Neither message retries; a reload reads the order again. The server render and the first browser render show the skeleton: the browser always reads the order with the shopper's cookies.
+
+| Prop | Default |
+| --- | --- |
+| `refusedOrderLabel` | "This order can no longer be shown here" |
+| `unresolvedOrderLabel` | "Could not load this order" |
+
+`useOrderPlaced()` returns `{ order, loading, error }` and throws outside the root.
+
+### OrderPlacedStatus
+
+The payment outcome. `APPROVED`, `PENDING` and `DENIED` render a title and a message; `UNKNOWN` renders nothing, so the page shows the order without asserting an outcome. A payment under anti-fraud review reads as pending. Each title and message is a prop authored in the page; a blank value leaves its line out. The banner declares no content model, so a page in a CMS-bound store needs no content entry for it: a content model would require a `content.entryId` seeded with `sukima cms publish`. It can return, for editing from the CMS admin, once the page has a seeded entry. An `Icon` child renders on every outcome, so never compose one that implies success.
+
+| Prop | Default |
+| --- | --- |
+| `approvedTitle` / `approvedMessage` | "Your order is confirmed" / "Your payment was approved." |
+| `pendingTitle` / `pendingMessage` | "We're confirming your payment" / "Your order was placed, and its payment is still being processed or reviewed." |
+| `deniedTitle` / `deniedMessage` | "Your payment was not approved" / "This purchase did not go through. You can place a new order with another payment method." |
+
+### OrderPlacedReference
+
+The order group, one per purchase even when it was split across sellers, under `template` ("Order #{reference}"). Plain text, so it can be selected and copied.
+
+### OrderPlacedCustomer
+
+The customer as the order recorded them: name (first and last name), email, phone and document, one row each, a row left out when its value is empty. Renders nothing when the order has no customer. Values show as the order system returns them, masked included (`J*** D***`). Labels: `nameLabel`, `emailLabel`, `phoneLabel`, `documentLabel`.
+
+### OrderPlacedTotals
+
+One row per money line in the order the API returns them, then the total row, each formatted in the line's own currency and the storefront locale.
+
+- `Items`, `Shipping`, `Discounts` and `Tax` take `itemsLabel`, `shippingLabel`, `discountsLabel` and `taxLabel`; any other line (a custom tax) shows its own name.
+- A zero discount line is left out; a discount shows as returned, negative.
+- `shippingZeroLabel` (e.g. "Free") replaces a zero shipping value.
+- No total row when the order has no total, rather than a partial sum.
+
+### OrderPlacedDeliveryList
+
+Renders its child, one `OrderPlacedDeliveryGroup`, once per delivery of the order, in the order the API returns them, and nothing when the order has none. A delivery groups the items that share a shipping method, channel and estimate, across sellers. `useOrderDelivery()` returns the nearest delivery and throws outside the list.
+
+### OrderPlacedDeliveryGroup
+
+One delivery:
+
+- **Method**: the shipping option's name; left out when the order system sent none.
+- **Promise**: `dateTemplate` ("Arrives by {date}") with the date in the storefront locale and the store's timezone, when the order system dated the delivery. Otherwise the sentence the checkout's delivery step showed for the estimate ("in 2 business days", "arrives today"), from the message catalog.
+- **Item count**: `itemCountOneTemplate` ("{count} item") or `itemCountTemplate` ("{count} items"). It counts lines, one per item, as the API does.
+- **Pickup point**: `pickupPointTemplate` ("Pickup at {name}") for a pickup.
+- **Address**: provided to the `AddressSummary*` children: the shipping address, or the pickup point's for a pickup, masked as the order system returns it. A delivery without one renders no address, and its items still render.
+
+### OrderPlacedItemRow
+
+Renders the cart's own `CartItemRoot` once per item of the delivery, so the cart's leaves composed under it present the item as the cart did. Compose the read-only leaves: `CartItemImage`, `-ProductLink`, `-Name`, `-Variant`, `-Sku`, `-Price`, `-ListPrice`, `-DiscountPercentage`, `-LineTotal`, `-OwnTotal`, `-AggregateTotal`, `-QuantityValue`, `-Gift`. Outside a delivery it renders nothing. `useOrderPlacedItem()` returns the nearest item.
+
+### OrderPlacedItemCompositions
+
+An item's add-on services nested under it, with the cart's own composition markup: name, quantity, unit price, customizations, children by depth. Nothing when the item has none, as every item of a purchase split across sellers.
+
+---
+
+## Canonical schema example
+
+```json
+{
+  "order-placed-root": {
+    "type": "OrderPlacedRoot",
+    "props": {
+      "refusedOrderLabel": "This order can no longer be shown here",
+      "unresolvedOrderLabel": "Could not load this order"
+    },
+    "children": ["order-status", "order-reference", "deliveries", "order-customer", "order-totals", "order-payment"]
+  },
+  "order-status": { "type": "OrderPlacedStatus" },
+  "order-reference": { "type": "OrderPlacedReference", "props": { "template": "Order #{reference}" } },
+  "order-customer": { "type": "OrderPlacedCustomer" },
+  "order-totals": { "type": "OrderPlacedTotals", "props": { "shippingZeroLabel": "Free" } },
+  "deliveries": { "type": "OrderPlacedDeliveryList", "children": ["delivery-group"] },
+  "delivery-group": {
+    "type": "OrderPlacedDeliveryGroup",
+    "props": { "dateTemplate": "Arrives by {date}" },
+    "children": ["address-recipient", "address-street", "address-locality", "item-row"]
+  },
+  "address-recipient": { "type": "AddressSummaryRecipient" },
+  "address-street": { "type": "AddressSummaryStreet" },
+  "address-locality": { "type": "AddressSummaryLocality" },
+  "item-row": {
+    "type": "OrderPlacedItemRow",
+    "children": ["item-image", "item-name", "item-variant", "item-quantity", "item-total", "item-compositions"]
+  },
+  "item-image": { "type": "CartItemImage" },
+  "item-name": { "type": "CartItemName" },
+  "item-variant": { "type": "CartItemVariant" },
+  "item-quantity": { "type": "CartItemQuantityValue" },
+  "item-total": { "type": "CartItemLineTotal" },
+  "item-compositions": { "type": "OrderPlacedItemCompositions" },
+  "order-payment": { "type": "OrderPlacedPaymentSummary" }
+}
+```
+
+---
+
+## Common mistakes
+
+- **Composing a leaf outside `OrderPlacedRoot`** → it throws. Every block here requires the `order-placed` context.
+- **Composing `CartTotalizerLine` or `IdentitySummary*` on this page** → they read the cart and the live profile, not the placed order.
+- **An `Icon` that implies success under `OrderPlacedStatus`** → it also shows on a denied payment.
+- **Expecting a message per block on a refused read** → the root replaces every child with one message.
+- **Composing `CartItemQuantity`, `CartItemRemove`, `CartItemVariations`, `CartItemAvailable` or `CartItemUnavailable` under `OrderPlacedItemRow`** → they read or change the live cart. Use `CartItemQuantityValue` and `CartItemVariant`.
+- **Composing `CartItemCompositions` instead of `OrderPlacedItemCompositions`** → it adds a read of the live cart to the page.
+- **Composing `AddressSummaryRoot` in the page** → the delivery group renders it with the delivery's address; compose only its leaves.
+
+---
+
+## Styling
+
+| Hook | Element |
+| --- | --- |
+| `data-fs-order-placed-root` | The root's wrapper |
+| `data-fs-order-placed-root-skeleton` | The loading placeholder (`aria-hidden`) |
+| `data-fs-order-placed-root-refused`, `data-fs-order-placed-root-unresolved` | The two messages |
+| `data-fs-order-placed-status` | The banner, an `<output>` (implicit `status` role) |
+| `data-fs-order-placed-status-approved`, `-pending`, `-denied` | The banner's tone |
+| `data-fs-order-placed-status-title`, `-message` | The banner's lines |
+| `data-fs-order-placed-reference` | The reference line |
+| `data-fs-order-placed-customer` | The customer `dl` |
+| `data-fs-order-placed-customer-term`, `-value` | Each row's `dt` and `dd` |
+| `data-fs-order-placed-totals` | The totals `dl` |
+| `data-fs-order-placed-totals-line` | A money line's row, set to the line's id (`Items`, `Discounts`, …) |
+| `data-fs-order-placed-totals-total` | The total row |
+| `data-fs-order-placed-totals-term`, `-value` | Each row's `dt` and `dd` |
+| `data-fs-order-placed-delivery-list` | The deliveries' wrapper |
+| `data-fs-order-placed-delivery-group` | One delivery |
+| `data-fs-order-placed-delivery-group-channel` | The delivery's channel: `delivery`, `pickup` or `unknown` |
+| `data-fs-order-placed-delivery-group-method`, `-date`, `-count`, `-pickup-point` | The delivery's lines |
+| `data-fs-order-placed-item-row` | Each item's `CartItemRoot`, beside the cart's own `data-fs-cart-item-root` |
+| `data-fs-cart-item-composition*` | The add-ons, with the cart's own hooks |
+
+Each row of the customer and the totals is a `div` holding one `dt` and one `dd`. Style the tones under the `OrderPlacedStatus` type, for example `data-[fs-order-placed-status-denied]:bg-red-50`.
+
+---
+
+## Testing
+
+`order-placed.test.tsx` covers the root's four states and their precedence, each outcome and its authored copy, the reference template, the customer rows and the totals' labels, zero lines and null total.
+
+`order-placed-deliveries.test.tsx` covers one group per delivery and every item exactly once, the dated and relative promises in the store's timezone, the channel, the pickup point and a missing address, every shipped cart leaf against the same cart line, the nested add-ons, and two checks that keep the list's fragment in step with the cart's.
+
+---
+
+## Related
+
+- `OrderPlacedPaymentSummary` — the payment recap, composed under the root.
+- `docs/features/order-placed/rfc-particles.md` — the design of the page's parts.