@vtex/faststore 0.0.7 → 0.0.8

package/dist/docs/logo.md

@@ -40,7 +40,7 @@ Logo
 |------|------|---------|-------|
 | `src` | string | — | Brand logo asset URL. Optional, so an element can be authored from the CMS alone. |
 | `alt` | string | — | Accessible alt text for the logo image. Optional for the same reason. |
-| `href` | string | `/` | Navigation destination (configured home). |
+| `href` | page reference or string | `{ "standard": "home" }` | A page reference or a logical path. The default names the home page. A store whose home page declares no `standard` authors `{ "page": "home" }`. |
 | `loading` | `'lazy' \| 'eager'` | `'eager'` | Set `lazy` below the fold; the default suits the header. |
 
 Content model (`logo`) fields, edited in the CMS:
@@ -49,13 +49,13 @@ Content model (`logo`) fields, edited in the CMS:
 |-------|------|----------|-------|
 | `src` | string | no | Picked via the media gallery widget. Cleared or absent keeps the authored `src` |
 | `alt` | string | yes | Accessible alt text |
-| `href` | string | no | Cleared or absent keeps the authored `href` |
+| `href` | string | no | A `uri-reference` string. Cleared or absent keeps the authored `href`. A safe string receives the binding prefix at render |
 
 **Props and content both work.** The props stay the authoring surface, and a CMS entry overrides them field by field, so a merchant can swap the brand mark for a campaign without a deploy. A store with no CMS binding receives no `$content` and renders from the props alone. The `logo` model puts no `format` on `src`, because a store's logo is usually a root-relative path served from `public/` (`/logo.svg`), which JSON Schema's `uri` format rejects. `href` carries `uri-reference` and the same destination pattern the link-bearing footer models declare, which admits a root-relative path.
 
 **Nothing renders without a resolved `src` and `alt`.** Both props are optional and only `alt` is required in the model, so an element can author nothing and take everything from the CMS. Presence is enforced once, at render, on the resolved values: an unconfigured logo renders no element at all rather than a broken image. An optional field that arrives blank reads as unauthored and falls through to the prop; a blank `alt` renders nothing, since an unnamed link is worse than no link.
 
-**A destination that is not a plain web address is dropped.** The resolved `href` is checked at render, and only `http:`, `https:`, `mailto:`, `tel:`, and single-slash site-relative paths are kept. Anything else — a `javascript:` URL, a protocol-relative `//host`, a scheme-less relative path — renders the image with no link around it and logs the reason. No read-time validator enforces a URL pattern, so this is the only gate on a destination the CMS supplied.
+**A string destination that is not a plain web address is dropped.** A CMS `href` is a `uri-reference` string. It is checked at render, and a safe one receives the binding's base path. A page reference, including the default `{ "standard": "home" }`, is not checked as a string. Only `http:`, `https:`, `mailto:`, `tel:`, and single-slash site-relative paths are kept. Anything else — a `javascript:` URL, a protocol-relative `//host`, a scheme-less relative path — renders the image with no link around it and logs the reason, and does not fall back to the prop. No read-time validator enforces a URL pattern, so this is the only gate on a destination the CMS supplied.
 
 ---
 
@@ -68,7 +68,7 @@ Content model (`logo`) fields, edited in the CMS:
     "props": {
       "src": "https://store.example/logo.svg",
       "alt": "Acme Store",
-      "href": "/"
+      "href": { "standard": "home" }
     },
     "style": ["$logo"]
   }
@@ -110,7 +110,7 @@ Bound to a CMS entry, the element authors no content props at all — the entry
 {
   "header-logo": {
     "type": "Logo",
-    "props": { "src": "https://store.example/logo.svg", "alt": "Acme Store", "href": "/" },
+    "props": { "src": "https://store.example/logo.svg", "alt": "Acme Store", "href": { "standard": "home" } },
     "style": ["w-[140px]", "md:w-[220px]"]
   }
 }

package/dist/docs/my-account-profile.md

@@ -78,7 +78,7 @@ A field Control is absent from the composition means absent from both states and
 
 **`.PhoneControl`** — `field` (`'homePhone' | 'mobilePhone'`, default `'mobilePhone'`; compose the Control twice to expose both numbers), `country` (`'US' | 'BR'`, default `'US'`), `label`, `invalidMessage`.
 
-**`.TaxIdControl`** — `label` (default `'National tax ID'`), `invalidMessage`, `lockedReason` (the inline copy shown beside the disabled input when a CPF is already saved).
+**`.TaxIdControl`** — `label` (default `'National tax ID'`), `invalidMessage`, `lockedReason` (the inline copy shown beside the disabled input when a document is already saved). The control masks, validates and normalizes with the active document type: CPF, SSN, SIN or RFC. It sends `document` only (never `documentType`): digits for CPF, SSN and SIN, letters kept for RFC.
 
 **`.BirthDateControl`** — `label` (default `'Birth date'`).
 
@@ -93,8 +93,8 @@ Each Control is a thin binding over an existing presentational particle — it a
 - **Registration**: in a mount effect, a Control calls `registerField({ key, validate?, normalize? })` and returns the unregister function from the effect. `firstName`/`lastName` register a validator that rejects an empty draft value; every other Control either registers a format-only validator (a present value must be well-formed; empty is always valid) or no validator at all.
 - **Rendering**: `mode === 'view'` renders `savedValues[key]` as plain text (empty, never a placeholder, when the key was never saved); `mode === 'edit'` renders the bound particle over `draft[key]`, writing through `setField(key, value)`.
 - **Normalization**: `PhoneControl` registers `normalize = (v) => v ? toE164(v, country) : v`; `BirthDateControl` registers the native `yyyy-mm-dd` ↔ stored-format identity map. Normalization runs once, on Save, only for a field the shopper actually changed.
-- **The locked tax ID**: when a saved CPF exists, `TaxIdControl`'s edit branch renders a **disabled** input carrying the saved (masked) value, a `data-fs-my-account-profile-tax-id-readonly` hook, and `lockedReason` — never plain text, never omitted. It registers no validator in this branch and is never dirty. With no saved document, it renders an editable, optional `DocumentField` instead.
-- **Self-gate**: `TaxIdControl` renders nothing when the Root's `activeDocumentType` is undefined or unsupported (V0 supports CPF only).
+- **The locked tax ID**: when a saved document exists, `TaxIdControl`'s edit branch renders a **disabled** input carrying the saved (masked) value, a `data-fs-my-account-profile-tax-id-readonly` hook, and `lockedReason` — never plain text, never omitted. It registers no validator in this branch and is never dirty. With no saved document, it renders an editable, optional `DocumentField` instead.
+- **Self-gate**: `TaxIdControl` renders nothing when the Root's `activeDocumentType` is undefined or unsupported. The supported types are CPF, SSN, SIN and RFC; a saved `documentType` of any of them (any casing) wins over the Root's `documentType` prop.
 - **One phone Control, two bindings**: `PhoneControl`'s `field` prop selects which draft key an instance binds; composing it twice (once per `field` value) exposes both `homePhone` and `mobilePhone` as independent, independently-erasable fields.
 
 ---
@@ -172,7 +172,7 @@ Add each field Control id to `profile-root`'s `children` array for the fields th
 - **Reading `draft` in the view state, or `savedValues` in the edit state.** Each Control must branch on `mode` itself (Decision 2); the Root does not hide this for you.
 - **Rendering a frame part or field Control outside `MyAccountProfileRoot`.** Every part except `Skeleton` `requiresContext: 'my-account-profile'` and throws otherwise.
 - **Giving a required Control's native input a `required` HTML attribute.** Requiredness is expressed only through the registered `validate` function (Decision 2 of SFS-3288/3289/3290); a native `required` attribute makes the browser block the form's `submit` event before the Root's own validation and focus logic ever runs.
-- **Hiding the `TaxIdControl` in the edit state when a CPF is already saved.** It must render a disabled, locked input instead — a field disappearing between view and edit reads as a bug (product-confirmed, 2026-09-03).
+- **Hiding the `TaxIdControl` in the edit state when a document is already saved.** It must render a disabled, locked input instead — a field disappearing between view and edit reads as a bug (product-confirmed, 2026-09-03).
 - **Composing only the `mobilePhone` Control on a store whose shoppers check out.** The checkout reads its phone from `homePhone`, and it treats a profile without one as incomplete: a new cart imports only the email and drops the shopper's saved addresses. Compose a `PhoneControl` with `field: "homePhone"` whenever the store sells, alongside the mobile one if the page shows both.
 - **Adding a `showPhone`/`visible` boolean prop to a Control.** Presence is composition; a boolean visibility prop contradicts compose-or-omit and is out of scope for every Control in this group.
 

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.