@vtex/faststore 0.0.6 → 0.0.8

package/dist/docs/navigation-link-list.md

@@ -67,7 +67,7 @@ layout-header
 
 | Prop | Type | Required | Notes |
 |-------|------|----------|-------|
-| `links` | array | no | Authored fallback list of `{ label, href, target? }`. Ignored when a CMS entry supplies `links` |
+| `links` | array | no | Authored fallback list of `{ label, href, target? }`. An item `href` may be a page reference or a logical path. Ignored when a CMS entry supplies `links` |
 
 Content model (`navigation-link-list`) fields, edited in the CMS:
 
@@ -75,7 +75,7 @@ Content model (`navigation-link-list`) fields, edited in the CMS:
 |-------|------|----------|-------|
 | `links` | array | no | Ordered links. Adding, removing or reordering here changes the navigation with no deployment. Optional so an unfilled entry falls back to the authored list |
 | `links[].label` | string | yes | Link text. A blank label drops that link — an anchor with no name is unusable |
-| `links[].href` | string | yes | Destination. `http:`, `https:`, `mailto:`, `tel:`, or a path starting with a single `/` |
+| `links[].href` | string | yes | A `uri-reference` string: `http:`, `https:`, `mailto:`, `tel:`, or a path starting with a single `/`. The binding prefix is applied at render |
 | `links[].target` | `_self` \| `_blank` | no | `_blank` opens a new tab and adds `rel="noopener noreferrer"` automatically. Write an "(opens in new tab)" cue into the label — the component announces nothing on its own |
 
 ---

package/dist/docs/navigation-link.md

@@ -1,7 +1,7 @@
 # NavigationLink
 
 **Category:** navigation
-**Purpose:** Client-side navigation link built on Next.js Link. Renders a single `<a>` and moves the shopper between routes without a full-page reload. Carries no commerce data of its own.
+**Purpose:** Client-side navigation link that renders `StorefrontLink`. `href` is a page reference or a logical path. Renders a single `<a>` and moves the shopper between routes without a full-page reload. Carries no commerce data of its own.
 
 ---
 
@@ -57,7 +57,7 @@ Sibling links share the same `children` array on the parent, and their order ref
 
 | Prop | Type | Default | Notes |
 |------|------|---------|-------|
-| `href` | `string` | — | Destination. An internal path (`/collection/sale`) keeps client-side navigation; an absolute URL (`https://…`) leaves the store. |
+| `href` | page reference or string | — | A page reference (`{ page }` or `{ standard }`) or a logical path (`/collection/sale`). An absolute URL (`https://…`) leaves the store. The binding prefix is applied at render. |
 | `target` | `_self` \| `_blank` | `_self` | `_blank` opens the destination in a new tab. The component then adds `noopener` and `noreferrer` to the anchor's `rel` on its own. |
 | `children` | `string` | — | The link text. This is also the link's accessible name, so it has to describe the destination on its own. |
 
@@ -68,7 +68,7 @@ Content model (`navigation-link`) fields, edited in the CMS:
 | Field | Type | Required | Notes |
 |-------|------|----------|-------|
 | `text` | string | yes | The link label |
-| `href` | string | no | Cleared, absent, or outside the allowlist keeps the authored `href` |
+| `href` | string | no | A `uri-reference` string. Cleared, absent, or outside the allowlist keeps the authored `href`. A safe string receives the binding prefix at render |
 | `target` | `_self` \| `_blank` | no | Absent keeps the authored `target` |
 
 **Props and content both work.** The props stay the authoring surface, and a CMS entry overrides them field by field, so a merchant can retitle a link or repoint it without a deploy. A store with no CMS binding receives no `$content` and renders from the props alone. The safety `rel` follows the *resolved* target, so a `_blank` that arrives from the CMS is defended exactly like an authored one — but the "(opens in new tab)" cue lives in the label, which means a merchant who switches a link to `_blank` has to write that cue into `text` themselves.

package/dist/docs/order-cancel.md

@@ -0,0 +1,52 @@
+# OrderCancel
+
+**Category:** action
+**Purpose:** Confirms and cancels one eligible order.
+
+---
+
+## Visual cues (how to identify in an image)
+
+- A "Cancel order" button on the order page.
+- A confirmation dialog with a reason list, an Other entry, and confirm and dismiss actions.
+- After a successful cancel, the button is gone and a short confirmation sentence remains.
+
+The image is the source of truth for layout.
+
+## When to use
+
+- On the order details page, for a shopper who may cancel that order.
+
+## When NOT to use
+
+- For a toast or a dialog that closes on an outside click.
+- For cancelling a single item.
+
+---
+
+## Composition
+
+```text
+OrderCancel
+```
+
+The dialog, the reason list, and the acknowledgement are inside this matter.
+
+## Components
+
+### OrderCancel
+
+No authoring props. The page query passes the order. Reasons and sentences come from the `order-cancel` content model.
+
+## Styling
+
+- `data-fs-order-cancel` — the root. `data-fs-order-cancel-outcome` is `idle`, `success`, or `failure`.
+- `data-fs-order-cancel-action` — the button that opens the dialog.
+- `data-fs-alert-dialog-backdrop`, `data-fs-alert-dialog-viewport`, `data-fs-alert-dialog-popup`, `data-fs-alert-dialog-title`, `data-fs-alert-dialog-description` — the overlay. It portals into this root so these hooks stay reachable.
+- `data-fs-order-cancel-reasons` — the reason list. `data-fs-radio-root`, `data-fs-radio-indicator`, and `data-fs-order-cancel-mark` are one option.
+- `data-fs-order-cancel-actions` — the confirm and dismiss row.
+- `data-fs-order-cancel-other` — the free-text field, only while Other is selected.
+- `data-fs-order-cancel-confirm` — the confirm button. Disabled while the write is in flight.
+- `data-fs-order-cancel-dismiss` — the dismiss button.
+- `data-fs-order-cancel-message` — the success or failure acknowledgement.
+- `data-fs-order-cancel-skeleton` — the loading placeholder.

package/dist/docs/order-delivery-address.md

@@ -0,0 +1,63 @@
+# OrderDeliveryAddress
+
+**Category:** content
+**Purpose:** The address the order recorded for one delivery option, inside its delivery group.
+
+---
+
+## Visual cues (how to identify in an image)
+
+- A short address block under the products of a delivery group on an order details page. It starts with a caption such as "Delivery address" or "Store address".
+- Under a delivery caption, a person's name comes first, then street, number, complement, neighborhood, reference, city, state, postal code, and country code. Fields the order did not store are absent.
+- Under a store caption there is no person's name: the block is the pickup point's address.
+
+The image is the source of truth for layout.
+
+## When to use
+
+- The order details page, inside each `OrderDeliveryGroup`, after the product rows.
+
+## When NOT to use
+
+- For the products of each delivery → use `OrderDeliveryGroup`.
+- For the shopper's saved addresses or an address form → use the address book components.
+- For the billing address of a payment → use the payment components.
+
+---
+
+## Composition
+
+`OrderDeliveryAddress` is a leaf. Place it as a child of `OrderDeliveryGroup`; the group renders it once per delivery option and tells it which option it sits in. Outside a group it renders one block per option that has an address.
+
+```text
+OrderDeliveryGroup
+└── OrderDeliveryAddress
+```
+
+## Components
+
+### OrderDeliveryAddress
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| deliveryLabel | string | catalogue `fs/order-delivery-address.delivery` | Caption above a delivery address |
+| storeLabel | string | catalogue `fs/order-delivery-address.store` | Caption above a pickup store address |
+
+Content model `order-delivery-address` with `deliveryLabel` and `storeLabel`. Content wins over the prop, and the prop wins over the catalogue. A blank value falls through.
+
+## Data
+
+The fragment reads `customerOrder(id: $orderId).deliveryOptions` with `addressId`, `deliveryChannel`, and `address`. `$orderId` is the `orderId` route segment. The address carries `receiverName`, `street`, `number`, `complement`, `neighborhood`, `reference`, `city`, `state`, `postalCode`, and `country`.
+
+A pickup is an option whose `deliveryChannel` is `pickup-in-point`: it shows the store caption and no recipient. Everything else is a delivery: it shows the delivery caption and the recipient when the order stored one. The values are the order record. The component does not format them with country rules and shows the country as the code the order stored.
+
+## Styling
+
+- `data-fs-order-delivery-address` — one address block (an `address` element). `flex flex-wrap gap-x-[4px] gap-y-[2px] px-[16px] pb-[16px] text-[14px] not-italic`.
+- `data-fs-order-delivery-address-channel` — `delivery` or `pickup-in-point`.
+- `data-fs-order-delivery-address-option` — the index of the delivery option.
+- `data-fs-order-delivery-address-label` — the caption. `basis-full font-medium text-[#666666]`.
+- `data-fs-order-delivery-address-recipient` — the recipient name. `basis-full`.
+- `data-fs-order-delivery-address-street`, `-number`, `-complement`, `-neighborhood`, `-reference`, `-city`, `-state`, `-postal-code`, `-country` — one field each, in that order.
+- `data-fs-order-delivery-address-list` — the wrapper when the component renders outside a group. `flex flex-col gap-[16px]`.
+- `data-fs-order-delivery-address-skeleton`, `data-fs-order-delivery-address-skeleton-line` — the pending look.

package/dist/docs/order-delivery-group.md

@@ -0,0 +1,83 @@
+# OrderDeliveryGroup
+
+**Category:** content
+**Purpose:** The products of one order grouped by delivery option, one collapsible group per option.
+
+---
+
+## Visual cues (how to identify in an image)
+
+- One or more collapsible rows on an order details page. Each row header carries a delivery name such as "Normal" or "Pickup", a delivery estimate when the order has one, a count such as "3 items", and a money amount labeled "Subtotal".
+- An open row lists products: a small image, the name, sometimes a detail such as "Size M" next to the name, a quantity, a unit price, sometimes a struck list price, a line tax when the order recorded one, and a line total.
+- When the page shows a single delivery, the row arrives open. Two or more arrive closed.
+
+The image is the source of truth for layout.
+
+## When to use
+
+- The order details page, for the products of the order.
+
+## When NOT to use
+
+- For the address of each delivery → use `OrderDeliveryAddress`.
+- For the order total, discounts, and shipping lines → use the order summary.
+- For a generic collapsible section → use `Accordion`.
+- For the live cart → use `CartItem`.
+
+---
+
+## Composition
+
+`OrderDeliveryGroup` renders the accordion and the rows itself. Do not place `Accordion` or product rows as children. Its children render once per option, after that option's rows, inside the `order-delivery-option` context that carries the option index. `OrderDeliveryAddress` is the child that reads it.
+
+```text
+OrderDeliveryGroup
+└── OrderDeliveryAddress
+```
+
+The group order is the order of `deliveryOptions`.
+
+## Components
+
+### OrderDeliveryGroup
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| label | string | content, then catalogue `fs/order-delivery-group.label` | Accessible name of the section. The other fixed labels are content too (`order-delivery-group`). Item counts keep `{count}`. |
+
+The initial open state is not a prop. One option opens; two or more start closed.
+
+## Data
+
+The fragment reads `customerOrder(id: $orderId).deliveryOptions`. `$orderId` is the `orderId` route segment. Each option reads `selectedSla`, `deliveryChannel`, `shippingEstimateDate`, and its `items` with `id`, `name`, `quantity`, `image`, `sellingPrice`, `listPrice`, `total`, `tax`, and `customFields`. The address is not selected. The header shows the estimate when the instant is valid, and nothing when it is missing. A row shows `tax` when the line recorded one, including zero, and omits it when the value is absent.
+
+The header count is the sum of the item quantities. The subtotal is the sum of the line totals the order carries. The component never multiplies a price by a quantity.
+
+## Styling
+
+- `data-fs-order-delivery-group` — the section. `flex flex-col gap-[16px]`.
+- `data-fs-order-delivery-group-count` — the number of options.
+- `data-fs-order-delivery-group-option` — one group. `rounded-[8px] border border-[#E5E5E5]`.
+- `data-fs-order-delivery-group-option-channel` — `delivery` or `pickup-in-point`.
+- `data-fs-order-delivery-group-option-header`, `data-fs-order-delivery-group-option-trigger` — the group header and its button. `flex items-center justify-between p-[16px]`.
+- `data-fs-order-delivery-group-option-panel` — the collapsible body.
+- `data-fs-order-delivery-group-option-name` — the delivery name. `text-[16px] font-medium`.
+- `data-fs-order-delivery-group-option-estimate-label`, `data-fs-order-delivery-group-option-estimate` — the delivery estimate caption and instant. The value is a `time`.
+- `data-fs-order-delivery-group-option-items` — the count sentence. `text-[14px] text-[#666666]`.
+- `data-fs-order-delivery-group-option-subtotal-label`, `data-fs-order-delivery-group-option-subtotal` — the subtotal caption and amount.
+- `data-fs-order-delivery-group-rows` — the list of products. `flex flex-col gap-[12px] p-[16px]`.
+- `data-fs-order-delivery-group-row` — one product. `grid grid-cols-[64px_1fr_auto] gap-[12px]`.
+- `data-fs-order-delivery-group-row-image` — the product image. `size-[64px] object-contain`.
+- `data-fs-order-delivery-group-row-details` — the name and the facts under it.
+- `data-fs-order-delivery-group-row-name` — the product name.
+- `data-fs-order-delivery-group-row-fact` — one fact line (quantity, unit price, list price, or tax).
+- `data-fs-order-delivery-group-row-custom-field`, `-custom-field-name`, `-custom-field-value` — a custom value next to the name.
+- `data-fs-order-delivery-group-row-quantity-label`, `data-fs-order-delivery-group-row-quantity` — the quantity caption and value.
+- `data-fs-order-delivery-group-row-unit-price-label`, `data-fs-order-delivery-group-row-unit-price` — the unit price.
+- `data-fs-order-delivery-group-row-list-price-label`, `data-fs-order-delivery-group-row-list-price` — the list price, only when it differs. `line-through`.
+- `data-fs-order-delivery-group-row-tax-label`, `data-fs-order-delivery-group-row-tax` — the line tax, only when the order recorded one.
+- `data-fs-order-delivery-group-row-aside` — the line total, aligned to the end of the row.
+- `data-fs-order-delivery-group-row-total-label`, `data-fs-order-delivery-group-row-total` — the line total.
+- `data-fs-order-delivery-group-skeleton`, `data-fs-order-delivery-group-skeleton-option` — the pending look.
+
+The accordion particle adds `data-fs-accordion-*` and Base UI adds `data-open` and `data-closed`.

package/dist/docs/order-details-back.md

@@ -0,0 +1,41 @@
+# OrderDetailsBack
+
+**Category:** action
+**Purpose:** Returns from one order to the order list.
+
+---
+
+## Visual cues (how to identify in an image)
+
+A single text link above the order heading, reading as a return to the orders list. The image is the source of truth for layout.
+
+## When to use
+
+The first element of an order details page whose account layout does not already show a breadcrumb.
+
+## When NOT to use
+
+- A layout that already composes the account breadcrumb. Leave this element out of that page.
+- The order list itself.
+
+---
+
+## Composition
+
+```
+OrderDetailsBack
+```
+
+`OrderDetailsBack` is one element. It has no schema props and no children.
+
+## Components
+
+### OrderDetailsBack
+
+| Prop | Type | Default | Purpose |
+|---|---|---|---|
+| — | — | — | No schema props. The label is content (`order-details-back`); a blank field keeps `fs/order.back-to-orders`. The href is `/pvt/orders`. |
+
+## Styling hooks
+
+`data-fs-order-details-back`.

package/dist/docs/order-details-header.md

@@ -0,0 +1,48 @@
+# OrderDetailsHeader
+
+**Category:** content
+**Purpose:** The top of an order page: the order number, a copy action for that number, and the status badge.
+
+---
+
+## Visual cues (how to identify in an image)
+
+A page heading with a short prefix and an order number, a copy action beside it, and a status badge. The image is the source of truth for layout.
+
+## When to use
+
+The first section of an order details page, once.
+
+## When NOT to use
+
+- Building the copy control. Compose `CopyText`.
+- Building the status sentence. Compose `OrderStatusBadge`.
+- Mapping an OMS status code. The header reads `completion` from the order.
+
+---
+
+## Composition
+
+```
+OrderDetailsHeader
+├── heading (prefix + number)
+├── CopyText
+└── OrderStatusBadge
+```
+
+## Components
+
+### OrderDetailsHeader
+
+| Prop | Type | Default | Purpose |
+|---|---|---|---|
+| `$data` | `{ id, completion } \| null` | — | The `customerOrder` the generator passes. Null renders nothing. |
+| `prefix` | string | `Order #` | Copy before the number. Content wins. An empty string, with no content, omits the prefix. |
+| `copyLabel` | string | `Copy` | Visible label of the copy action. Content wins. |
+| `copyAccessibleName` | string | `Copy order number` | Accessible name of the copy action. Content wins. |
+
+Content id `order-details-header` also carries the copy acknowledgement (`copyCopied`, `copyFailure`, `copyDismiss`) and one field per status sentence (`statusInProgress`, `statusCancellationRequested`, `statusCancelled`, `statusDelivered`, `statusShipped`, `statusReadyForPickup`, `statusCollected`, `statusPlaceholder`). A blank field keeps the catalogue. The list page does not read this entry.
+
+## Styling hooks
+
+`data-fs-order-details-header`, `data-fs-order-details-header-heading`, `data-fs-order-details-header-prefix`, `data-fs-order-details-header-number`, `data-fs-order-details-header-copy`, `data-fs-order-details-header-status`.

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

@@ -0,0 +1,46 @@
+# OrderListRow
+
+**Category:** content
+**Purpose:** One order in the list, as a link to that order.
+
+---
+
+## Visual cues (how to identify in an image)
+
+- One clickable row with an order number, a date, a money amount, a small count, and a status label.
+- An ongoing row may also show a delivery date. A completed or cancelled row does not.
+
+The image is the source of truth for layout.
+
+## When to use
+
+- Inside `OrderList`, which renders one row per order. Do not place this component in a page schema.
+
+## When NOT to use
+
+- For the whole page of orders → use `OrderList`.
+- For the status sentence alone → use `OrderStatusBadge`.
+
+---
+
+## Composition
+
+`OrderList` owns the rows. There is no page-schema child relationship.
+
+```text
+OrderList
+```
+
+## Components
+
+### OrderListRow
+
+No props. The list passes the order.
+
+## Styling
+
+- `data-fs-order-list-row` — the link. `flex flex-col gap-[4px]`.
+- `data-fs-order-list-row-state` — `ongoing`, `completed`, or `cancelled`.
+- `data-fs-order-list-row-id` — the order number. `text-[16px] font-medium`.
+- `data-fs-order-list-row-placed`, `data-fs-order-list-row-total`, `data-fs-order-list-row-count` — the facts.
+- `data-fs-order-list-row-estimate` — the delivery estimate, only while the order is ongoing.

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

@@ -0,0 +1,101 @@
+# OrderListSearch
+
+**Category:** action
+**Purpose:** A text field and a placed-date range that ask the orders page for a term and a period.
+
+---
+
+## Visual cues (how to identify in an image)
+
+- A text field whose label names the order number.
+- Two date fields, a start and an end, for the date the order was placed.
+- A submit button, and a clear link when a term or a date is already in the URL.
+
+The image is the source of truth for layout.
+
+## When to use
+
+- On the orders page, as the control that narrows the list by a term and by the dates an order was placed.
+
+## When NOT to use
+
+- For the rows, the empty sentences, or the page controls → those belong to the list, which reads the params this form writes.
+- For the four view choices → that is `OrderListViews`, which writes `view`.
+- For a filter of the orders already on screen → this form loads the page again.
+- For a product search of its own → the term is the route's text search.
+
+---
+
+## Composition
+
+`OrderListSearch` is a leaf element in the PageSchema. It renders its own fields and takes no children. The list is a sibling on the page, not a child of this element.
+
+```text
+OrderListSearch
+```
+
+## Components
+
+### OrderListSearch
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| `label` | string | `Order number` | Visible label of the text field. |
+| `fromLabel` | string | `Placed from` | Visible label of the from day. |
+| `toLabel` | string | `Placed to` | Visible label of the to day. |
+| `submitLabel` | string | `Search` | Submit button. |
+| `clearLabel` | string | `Clear search` | Clear link. Rendered only when the URL already has a criterion. |
+| `invalidRangeMessage` | string | `The start date is after the end date.` | Shown when the from day is after the to day. |
+
+Content model (`order-list-search`) 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 control.
+
+| Field | Type | Required | Notes |
+|-------|------|----------|-------|
+| `label` | string | no | Maps to `label`. |
+| `from` | string | no | Maps to `fromLabel`. |
+| `to` | string | no | Maps to `toLabel`. |
+| `submit` | string | no | Maps to `submitLabel`. |
+| `clear` | string | no | Maps to `clearLabel`. |
+| `invalidRange` | string | no | Maps to `invalidRangeMessage`. |
+
+**The param keys are fixed.** The term is `search`. The days are `placedFrom` and `placedTo`, as RFC 3339 UTC instants of the local start and the local end of the picked days. Renaming a label does not change the keys. Submit and clear delete `after` and keep `view`.
+
+**An inverted range is not written.** The message is shown and the URL stays. One empty day is an open range. Render does not replace the URL. A `YYYY-MM-DD` value in `placedFrom` or `placedTo` is not an instant, so that input stays empty.
+
+**No fragment.** This matter does not read `customerOrders` and does not decide which orders match.
+
+---
+
+## Canonical schema example
+
+```json
+{
+  "order-search": {
+    "type": "OrderListSearch",
+    "props": {
+      "label": "Order number",
+      "fromLabel": "Placed from",
+      "toLabel": "Placed to",
+      "submitLabel": "Search",
+      "clearLabel": "Clear search",
+      "invalidRangeMessage": "The start date is after the end date."
+    },
+    "children": [],
+    "style": ["flex flex-wrap items-end gap-[12px]"]
+  }
+}
+```
+
+## Common mistakes
+
+- Filtering the orders already rendered in the browser. The route narrows the list.
+- Sending the calendar day `YYYY-MM-DD` as `placedFrom`. The value is the local start of that day, as an RFC 3339 instant.
+- Dropping `view` on submit. A search narrows the view the shopper already chose.
+- Keeping `after`. A new term or range starts at the first page.
+- Building the empty sentence here. The list says that nothing matched. This form shows the criteria and clears them.
+
+## Styling
+
+No CSS file. The form carries `data-fs-order-list-search`. While the range is invalid it also carries `data-fs-order-list-search-invalid`. The text field carries `data-fs-order-list-search-term`. The days carry `data-fs-order-list-search-from` and `data-fs-order-list-search-to`. The clear link carries `data-fs-order-list-search-clear`.
+
+A row of the field, the two days, and the button is `flex flex-wrap items-end gap-[12px]` on the form. The invalid message is typically `text-[14px]` on the paragraph.

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`.