@vtex/faststore 0.0.6 → 0.0.8

package/dist/docs/account-menu-identity.md

@@ -0,0 +1,160 @@
+# AccountMenuIdentity
+
+**Category:** identity
+**Purpose:** The signed-in shopper's name and initials avatar, shown beside the account's section list so they can confirm whose account they are looking at.
+
+---
+
+## Visual cues (how to identify in an image)
+
+- A small circle with one or two capital letters (`JD`) next to a person's full name, above or beside a column of account section links.
+- It is shown only where the section list is a vertical column. On a narrow screen, where the same sections read as a horizontal row of pills, it is absent.
+- A name only, never an email address, phone number, or edit control next to it (unless the account has no saved name, when the email stands in for it).
+
+The image is the source of truth for layout.
+
+## When to use
+
+- In the account's shared layout, beside the section list, to show whose account it is.
+
+## When NOT to use
+
+- For a profile form or any editable field → use `MyAccountProfileRoot` and its controls.
+- For a read-only identity card with e-mail, phone, and document → use `IdentitySummaryRoot`.
+- For the header's sign-in or account control → use [[account-entry-point]].
+- For a bare avatar with no account data → use [[avatar]].
+
+---
+
+## Composition
+
+`AccountMenuIdentity` is a leaf that declares its own data read. It needs a `SessionRoot` ancestor and nothing else: it reads nothing from the menu, so it is valid anywhere under a session. In the `my-account` layout it is placed under `AccountAccessGate`, inside `AccountMenuRoot`, beside `AccountMenuList`.
+
+```
+SessionRoot
+└── AccountAccessGate
+    └── AccountMenuRoot
+        ├── AccountMenuIdentity    ← beside the list, never inside it
+        ├── AccountMenuList
+        └── Slot                   ← the section's own page
+```
+
+**Place it in the layout, never on a page.** It is `reactive`: its fragment joins the layout's query, which runs in the browser where the shopper's cookie is, and the profile is fetched once and reused as the shopper moves between sections.
+
+**A missing profile costs only this block.** `customerProfile` is nullable. It answers `null` with no error for an anonymous visitor, and `null` with an error at its own path (`UNAUTHORIZED`, `UPSTREAM_ERROR`) when the read fails. The rest of the layout query, the session included, resolves as usual, so the gate and the menu are unaffected.
+
+**Keep it outside `AccountMenuList`.** The list is the navigation landmark and surrounds its items alone; the identity block is not navigation.
+
+The profile is optional to the menu, so it lives in its own component with its own fragment. A store that does not compose this block does not fetch the profile for the menu.
+
+---
+
+## Components
+
+### AccountMenuIdentity
+
+No props in the schema. It accepts standard `<div>` attributes (`className`, `id`), and takes no children.
+
+The block renders:
+
+| State | What renders |
+|---|---|
+| Session not `loggedIn`, or still loading | Nothing |
+| `loggedIn`, layout query pending | An `aria-hidden` skeleton (`data-fs-account-menu-identity-skeleton`) |
+| `loggedIn`, `customerProfile` is `null` | Nothing |
+| `loggedIn`, profile has neither a name nor an email | Nothing |
+| `loggedIn`, profile resolved | The avatar and the name |
+
+**The name** is the first and last names, each trimmed, joined with a space. With neither, the trimmed email stands in for it. **The avatar** shows initials derived from that same name: the first letters of the first and last words, or one letter for a single word. It shows initials only, because the profile has no photo field.
+
+The avatar is hidden from assistive technology, so the name is announced once, as text.
+
+### AccountMenuIdentitySkeleton
+
+The loading placeholder `AccountMenuIdentity` renders while the profile read is pending. No props. It needs no context.
+
+---
+
+## Canonical schema example
+
+The my-account layout, with the identity block beside the section list:
+
+```json
+{
+  "account-session": { "type": "SessionRoot", "children": ["account-gate"] },
+  "account-gate": { "type": "AccountAccessGate", "children": ["account-menu"] },
+  "account-menu": {
+    "type": "AccountMenuRoot",
+    "children": ["account-sidebar", "account-slot"]
+  },
+  "account-sidebar": {
+    "type": "Container",
+    "children": ["account-identity", "account-menu-list"]
+  },
+  "account-identity": {
+    "type": "AccountMenuIdentity",
+    "style": ["$account-menu-identity"]
+  },
+  "account-menu-list": { "type": "AccountMenuList", "props": { "label": "Account" } },
+  "account-slot": { "type": "Slot" }
+}
+```
+
+## Common mistakes
+
+- **Putting it inside `AccountMenuList`.** The list takes no children; the block sits beside it, outside the landmark.
+- **Composing it on a page instead of the layout.** A page-scoped query runs on the server; the layout's runs in the browser with the shopper's cookie and is reused across sections.
+- **Omitting `SessionRoot`.** The block reads the session and throws without one.
+- **Expecting a photo.** It shows initials only. The profile has no photo field, so there is nothing to pass.
+- **Reaching for `IdentitySummaryRoot`.** That is checkout's order-form identity card and needs a cart. The account sidebar reads the persistent profile.
+- **Hiding it with a component prop.** There is none. Hide it below `md` through the swatch (`max-md:hidden`).
+
+---
+
+## Styling
+
+| Component | What you style | Plausible classes |
+|---|---|---|
+| `AccountMenuIdentity` | `data-fs-account-menu-identity` is the block: lays the avatar beside the name and hides it on narrow screens | `max-md:hidden flex items-center gap-3` |
+| Avatar | `data-fs-avatar`, with `data-fs-account-menu-identity-avatar`, is the circle | `size-10 rounded-full bg-gray-200 text-sm font-medium` |
+| Name | `data-fs-account-menu-identity-name` is the name text | `m-0 truncate font-semibold` |
+| Skeleton | `data-fs-account-menu-identity-skeleton`, with `-avatar` and `-line` parts, holds the block's place | `flex items-center gap-3` |
+
+The avatar is composed inside the block, so it is not a schema element a swatch can name. Its look reaches it through descendant selectors on the block's hooks, as a store's swatch does:
+
+```json
+{
+  "AccountMenuIdentity": {
+    "account-menu-identity": [
+      "max-md:hidden",
+      "flex",
+      "items-center",
+      "gap-3",
+      "[&_[data-fs-avatar]]:inline-flex",
+      "[&_[data-fs-avatar]]:size-10",
+      "[&_[data-fs-avatar]]:shrink-0",
+      "[&_[data-fs-avatar]]:items-center",
+      "[&_[data-fs-avatar]]:justify-center",
+      "[&_[data-fs-avatar]]:overflow-hidden",
+      "[&_[data-fs-avatar]]:rounded-full",
+      "[&_[data-fs-avatar]]:bg-gray-200",
+      "[&_[data-fs-avatar]]:text-sm",
+      "[&_[data-fs-avatar]]:font-medium",
+      "[&_[data-fs-account-menu-identity-name]]:m-0",
+      "[&_[data-fs-account-menu-identity-name]]:truncate",
+      "[&_[data-fs-account-menu-identity-name]]:font-semibold"
+    ]
+  }
+}
+```
+
+`max-md:hidden` is `display: none` below the `md` breakpoint, which removes the block from the layout and from the accessibility tree.
+
+---
+
+## Related
+
+- [[avatar]] — the particle the block composes for its initials circle.
+- [[account-menu]] — the section list the block sits beside.
+- [[account-access-gate]] — the gate the layout places above both.
+- `IdentitySummaryRoot` — checkout's read-only identity card, which reads the order form rather than the persistent profile.

package/dist/docs/account-menu.md

@@ -28,12 +28,14 @@ The image is the source of truth for layout.
 
 ## Composition
 
-Two parts, and the split is the point. `AccountMenuRoot` is the provider and `AccountMenuList` is the landmark.
+Two parts, and the split is the point. `AccountMenuRoot` is the provider and `AccountMenuList` is the landmark. A third, `AccountMenuIndexRedirect`, is the account root's only content and lives inside the slot. A fourth, `AccountMenuSignOut`, is the sidebar's way out and sits beside the list.
 
 ```text
 AccountMenuRoot
 ├── AccountMenuList
+├── AccountMenuSignOut   ← beside the list, outside the landmark
 └── Slot                 ← the section's own page
+    └── AccountMenuIndexRedirect   ← on the account page only
 ```
 
 **The Root wraps the section's content; the landmark does not.** The Root's context has to reach consumers that live inside the slot — the account root's redirect, the sibling breadcrumb — and a context reaches only its descendants. A `<nav>` stretched that far would put every section's content inside a navigation region: a screen reader would announce the page as navigation and "skip to navigation" would skip nothing. So the Root wraps, and the `<nav>` stays around the items alone.
@@ -55,14 +57,14 @@ Content model (`account-menu`) fields, edited in the CMS:
 |-------|------|----------|-------|
 | `items` | array | no | One entry per section, in the order they should appear |
 | `items[].label` | string | yes | The section's name |
-| `items[].href` | string | yes | Its destination; `http(s)`, `mailto:`, `tel:`, or a site-relative path |
+| `items[].href` | page reference or string | yes | Its destination; a page reference such as `{ "page": "orders" }`, or `http(s)`, `mailto:`, `tel:`, or a logical site-relative path |
 | `items[].external` | boolean | no | The entry leaves the account; it is never marked current |
 
-**The list comes from three channels, in order: a published entry, the authored `items` prop, then the library's five.** The default is Profile, Orders, Address, Payments, and Security, at `/account/profile` and its siblings — the set the PRD names. Presence decides, not emptiness: a channel supplying an empty list resolves to empty rather than falling through, because a merchant who cleared the list cleared it and the defaults must not override a deliberate publication.
+**The list comes from three channels, in order: a published entry, the authored `items` prop, then the library's five.** The default is Profile, Orders, Address, Payments, and Security, the page references `{ standard: 'profile' }` and its siblings — the set the PRD names. The route map resolves each one for the current binding, for example `/pt-BR/pvt/profile`. Presence decides, not emptiness: a channel supplying an empty list resolves to empty rather than falling through, because a merchant who cleared the list cleared it and the defaults must not override a deliberate publication.
 
-**The current section is derived, never authored.** The component reads the current path and matches each entry's destination on segment boundaries. At most one entry is current: among the matches, the one with the longest destination wins, which makes an exact match beat every ancestor without a second rule. `/account/order` is not a match for `/account/orders` — a prefix that does not land on a segment boundary is not a match at all.
+**The current section is derived, never authored.** The component reads the current logical path, without the binding's base path, and matches each entry's logical destination on segment boundaries. At most one entry is current: among the matches, the one with the longest destination wins, which makes an exact match beat every ancestor without a second rule. `/pvt/order` is not a match for `/pvt/orders` — a prefix that does not land on a segment boundary is not a match at all.
 
-**An exact match announces `aria-current="page"`; an ancestor match announces `aria-current="true"`.** Inside `/account/orders/123`, Orders is the current item of its set but not the current page. That claim belongs to the breadcrumb's deep entry, and two surfaces announcing "current page" for two different things is worse than the menu claiming only its set.
+**An exact match announces `aria-current="page"`; an ancestor match announces `aria-current="true"`.** Inside `/pvt/orders/123`, Orders is the current item of its set but not the current page. That claim belongs to the breadcrumb's deep entry, and two surfaces announcing "current page" for two different things is worse than the menu claiming only its set.
 
 Two kinds of entry are excluded from the match entirely: one marked `external`, and one whose destination is not site-relative. A destination of `/` is excluded from ancestor matching alone — a root destination is an ancestor of every account path, so a merchant listing the storefront's home beside the sections would otherwise see it current on every page. It still matches the path `/` exactly.
 
@@ -80,6 +82,58 @@ It takes no children: one `<li>` per resolved section is what it renders. With n
 
 A refused destination keeps its label and loses its anchor, rendering as text under `data-fs-account-menu-text`. A blank label drops the entry outright: an anchor with no accessible name is a WCAG failure.
 
+### AccountMenuIndexRedirect
+
+Exposed as `AccountMenu.IndexRedirect`. The account's root has no section of its own, and which section is first is the merchant's call, so the root is a page holding this part alone.
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| `loadingLabel` | string | — | Announced while the first section opens. |
+| `emptyMessage` | string | `'No account section is configured.'` | What the root says when there is no section to open. |
+| `className` | string | — | Applied to whichever element renders. |
+
+Content model (`account-menu-index-redirect`) fields, edited in the CMS, each winning over its prop when published; a blank field falls through:
+
+| Field | Type | Required | Notes |
+|-------|------|----------|-------|
+| `loadingLabel` | string | no | The waiting announcement |
+| `emptyMessage` | string | no | The no-section message |
+
+**It replaces the current history entry with the first section that stays in the account.** It reads the Root's resolved list and skips, in order: an entry marked `external`, a destination the allowlist refused, a destination that is not site-relative even though the merchant did not flag it, and the root itself in any spelling that matches it. Replace, never push: back from the section leaves the account instead of bouncing through its root.
+
+**While a destination exists it renders the access gate's loading look**, `AccountAccessGateLoading`, with `data-fs-account-menu-index-redirect` beside the part's own hook. The list itself never loads — the Root resolves it synchronously — so what the look covers is the navigation: the frame before the replace is issued and the time the section takes to land. In the `my-account` layout the gate's own wait for the session comes first, so the shopper sees one look throughout.
+
+**With nothing to open, the root is terminal.** A published empty list, or one holding external entries only, navigates nowhere and renders the message instead, under `data-fs-account-menu-index-redirect-empty`. The shell and the sidebar stay. The library's five defaults do not come back: the Root's presence rule is what keeps a published empty list empty, and this part reads the Root's result rather than choosing a channel of its own.
+
+It inherits the menu's V0 assumption that public paths carry no binding prefix. Where a store's public base path is its binding id, the root's own entry is not recognized as the current page and the replace targets an unprefixed destination.
+
+### AccountMenuSignOut
+
+Exposed as `AccountMenu.SignOut`. A button that ends the session and leaves the account for the home page. It reads nothing from the Root, so it works anywhere under the `my-account` layout's gate; the sidebar is where shoppers look for it.
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| `label` | string | `'Sign out'` | The button's text. |
+| `errorMessage` | string | `"We couldn't sign you out. Please try again."` | Shown when the sign-out did not happen. |
+| `className` | string | — | Applied to the wrapper. |
+
+Content model (`account-menu-sign-out`) fields, edited in the CMS, each winning over its prop when published; a blank field falls through:
+
+| Field | Type | Required | Notes |
+|-------|------|----------|-------|
+| `label` | string | no | The button's text |
+| `errorMessage` | string | no | The failure message |
+
+The component declares `actions: { session: ['logout'] }` and writes only through `$actions.session.logout()`.
+
+**It declares the sign-out intent before it awaits the logout.** The logout's payload flips the session to signed out in place, before any navigation can start. A gate that saw that session with no intent would read it as an expired session and send the shopper to sign in for the account they just left. With the intent declared first, the gate stands down — it renders nothing — from the click until the document is gone. The shopper sees the page empty while the request runs; that is the gate's look, not this part's.
+
+**Success is a document load of `/`.** It uses `location.assign`, not the router, so no client cache keeps the account behind the back control. What the browser's back-forward cache restores is the gate's to revalidate: it withdraws the intent on a restored page and re-reads the session. This part adds no `pageshow` handling of its own.
+
+**Failure keeps the shopper where they are.** When the logout reports any error, rejects, or has no handler to run, the part withdraws the intent, the gate brings the account back, and the message renders under `role="alert"`. A logout that reports an error is a sign-out that did not happen, so the shopper is never sent home still signed in. The failure is held outside the component, because the gate unmounts the part for the length of the attempt and mounts it anew on withdrawal. The next click clears it.
+
+**One activation, one logout.** While an attempt runs, a second click neither declares again nor dispatches a second mutation. The button is also disabled and `aria-busy` while any sign-out intent stands, so a second sign-out control on the page stops too.
+
 ### useAccountMenu()
 
 Returns `{ items, current }` — the resolved sections and the current one as `{ index, match }`. It throws outside an `AccountMenuRoot`. This is the contract the account root's redirect and the sibling breadcrumb read, so the two surfaces cannot disagree about which section is current.
@@ -92,26 +146,45 @@ Returns `{ items, current }` — the resolved sections and the current one as `{
 {
   "account-menu": {
     "type": "AccountMenuRoot",
-    "children": ["account-menu-list", "account-slot"],
-    "style": ["$account-menu"]
+    "children": ["account-menu-list", "account-menu-sign-out", "account-slot"]
   },
   "account-menu-list": {
     "type": "AccountMenuList",
-    "props": { "label": "Minha conta" },
-    "style": ["$account-menu-list"]
+    "props": { "label": "Minha conta" }
+  },
+  "account-menu-sign-out": {
+    "type": "AccountMenuSignOut",
+    "props": { "label": "Sair", "errorMessage": "Não conseguimos encerrar sua sessão. Tente novamente." }
   }
 }
 ```
 
 Bound to a CMS entry, the Root authors no `items` at all — the entry supplies the whole list.
 
+No part carries a `style` reference: each takes its type's `base` swatch from `global.json → styles` on its own. Reference a named swatch only when the store defines one, since a `$name` the store does not define expands to nothing, without an error.
+
+The account root's page, whose only content is the redirect:
+
+```json
+{
+  "account-index-redirect": {
+    "type": "AccountMenuIndexRedirect",
+    "props": { "loadingLabel": "Abrindo sua conta…", "emptyMessage": "Nenhuma seção configurada." }
+  }
+}
+```
+
 ## Common mistakes
 
 - **Placing the Root beside the slot instead of around it.** The layout's own consumers would be satisfied and the page's would not: a context reaches only descendants. Context-constraint validation reports it as a build error rather than as an empty menu at runtime.
 - **Putting the `<nav>` around the section's content.** That is what the two-part split exists to prevent; do not wrap the slot in `AccountMenuList`.
 - **Leaving `label` unauthored.** The default is `Account`; a store with its own wording should say so, because a landmark's name is how a screen-reader user tells it from every other one.
 - **Styling the current item and nothing else.** The hook exists beside `aria-current`, never instead of it. Removing the programmatic signal leaves position conveyed by appearance alone.
-- **Publishing an empty list and expecting the defaults.** Empty is a configuration, not an absence. The account's root then has no section to open.
+- **Publishing an empty list and expecting the defaults.** Empty is a configuration, not an absence. The account's root then has no section to open, and says so.
+- **Placing `AccountMenuIndexRedirect` on a section's page.** It navigates away from whatever page hosts it; it belongs on the account page alone.
+- **Putting an external entry first and expecting the root to follow it.** It is skipped, as is an absolute destination left unflagged; the root opens the first section that stays in the account.
+- **Placing `AccountMenuSignOut` outside the gate.** Nothing stands down while the logout runs, so the page shows the signed-out session for the moment before it leaves. Compose it under the `my-account` layout's gate.
+- **Signing out with the router, or adding `pageshow` handling to the control.** The document load is what keeps the account off the back control, and the gate owns the back-forward cache.
 - **Authoring `$content` in the schema.** `$content` is compiler-injected from the page's or layout's content entry; naming it in `props` fails the build.
 - **Expecting the default five to resolve.** Their routes exist only in a store that authored the account's route family; until then the default is correct in the example store alone.
 
@@ -128,37 +201,47 @@ Bound to a CMS entry, the Root authors no `items` at all — the entry supplies
 | Current item | `data-fs-account-menu-item-current` marks the current row | `font-semibold` |
 | Link | `data-fs-account-menu-link` is the anchor | `block rounded-md px-3 py-2 text-sm` |
 | Refused text | `data-fs-account-menu-text` replaces the anchor for a refused destination | `block px-3 py-2 text-gray-400` |
+| `AccountMenuIndexRedirect` | `data-fs-account-menu-index-redirect` is on both of its looks; the wait also carries the gate's `data-fs-account-access-gate-loading` | `text-sm text-gray-600` |
+| No-section message | `data-fs-account-menu-index-redirect-empty` marks the terminal state | `flex-1 p-6` |
+| `AccountMenuSignOut` | `data-fs-account-menu-sign-out` is the wrapper; `data-fs-account-menu-sign-out-pending` is on it while a sign-out runs | `flex flex-col gap-2 px-3` |
+| Sign-out button | `data-fs-account-menu-sign-out-button` is the `<button>`; style `:disabled` for the wait | `text-left text-sm underline` |
+| Sign-out failure | `data-fs-account-menu-sign-out-error` is the alert | `text-sm text-red-600` |
 
-The vertical-to-horizontal switch and the scroll affordance are one DOM styled two ways, authored as the `AccountMenu` swatch set in `global.json → styles`:
+The vertical-to-horizontal switch and the scroll affordance are one DOM styled two ways, in CSS alone. A store authors them as `AccountMenuList.base` in `global.json → styles`, abridged here:
 
 ```json
 {
-  "AccountMenuRoot": {
-    "account-menu": [
-      "flex",
-      "flex-col",
-      "gap-6",
-      "md:flex-row",
-      "md:gap-8",
+  "AccountMenuList": {
+    "base": [
       "[&_[data-fs-account-menu-items]]:flex",
-      "[&_[data-fs-account-menu-items]]:gap-2",
-      "[&_[data-fs-account-menu-items]]:overflow-x-auto",
       "md:[&_[data-fs-account-menu-items]]:flex-col",
-      "md:[&_[data-fs-account-menu-items]]:overflow-visible",
-      "[&_[data-fs-account-menu-item-current]_[data-fs-account-menu-link]]:bg-gray-100",
-      "[&_[data-fs-account-menu-item-current]_[data-fs-account-menu-link]]:font-semibold"
+      "max-md:[&_[data-fs-account-menu-items]]:overflow-x-auto",
+      "max-md:[&_[data-fs-account-menu-items]]:scroll-pe-[32px]",
+      "max-md:[&_[data-fs-account-menu-items]]:mask-[linear-gradient(to_right,#000_calc(100%-32px),transparent)]",
+      "max-md:[&_[data-fs-account-menu-item]:last-child]:pe-[32px]",
+      "[&_[data-fs-account-menu-item]]:shrink-0",
+      "[&_[data-fs-account-menu-link]]:whitespace-nowrap",
+      "[&_[data-fs-account-menu-link]]:border-transparent",
+      "max-md:[&_[data-fs-account-menu-link]]:border-b-2",
+      "md:[&_[data-fs-account-menu-link]]:border-l-2",
+      "[&_[data-fs-account-menu-item-current]_[data-fs-account-menu-link]]:border-gray-900"
     ]
   }
 }
 ```
 
-The current-item look reaches the anchor through the row, since the hook is on the `<li>` and the anchor is its child.
+- **The masked edge needs space as wide as its fade.** Give the last item a trailing padding and the `<ul>` a `scroll-padding-inline-end` equal to the fade width. Without the padding, a row scrolled to its end leaves the last label under the fade. Without the scroll padding, bringing a current last item into view parks it there.
+- **Reserve the current rule on every link in `transparent`.** Becoming current then changes a color, never a width, so the row does not shift on a route change.
+- **The current-item look reaches the anchor through the row**, since the hook is on the `<li>` and the anchor is its child.
+- **Keep the list's rules off the Root.** The Root wraps the section's content, so a descendant rule there reaches into every page. The Root's own classes and the layout's wrappers place the sidebar beside the section.
 
 ---
 
 ## Related
 
 - [[account-entry-point]] — the header control that links into the account.
+- [[account-access-gate]] — the loading look the root's redirect reuses, and the gate it runs under.
+- [[account-menu-identity]] — the shopper's name and avatar, composed beside the list inside the Root.
 - [[navigation-link]] — the client-side link each item composes.
 - [[navigation-link-list]] — the general-purpose CMS-driven list this one is patterned on.
 - `BreadcrumbRoot` — the sibling trail that keeps the "current page" claim for the deep page.

package/dist/docs/alert-dialog.md

@@ -72,9 +72,9 @@ No props.
 
 ### AlertDialogPortal
 
-Teleports its children to `<body>`. Context-only: no element of its own and no `className`.
+Teleports its children. With no `container`, they go to `<body>`. Pass `container` when a parent swatch has to reach the overlay.
 
-No props.
+No `className`.
 
 ### AlertDialogBackdrop
 

package/dist/docs/avatar.md

@@ -0,0 +1,103 @@
+# Avatar
+
+**Category:** content
+**Purpose:** A person or account marker: an image with an initials fallback derived from a name. It carries no account data of its own.
+
+---
+
+## Visual cues (how to identify in an image)
+
+- A small circle, usually 32–48px, holding one or two capital letters — `JD`, `A` — on a flat tinted background.
+- Or the same circle holding a round photo of a person.
+- It sits beside a person's name, in a comment, a profile header, or an account sidebar.
+
+The image is the source of truth for layout.
+
+## When to use
+
+- Wherever a person or account needs a compact visual marker beside their name.
+- When there may be no photo: the initials are the fallback, not a separate component.
+
+## When NOT to use
+
+- For a product or content image → use `Image`.
+- For a status or count label → use `Badge`.
+- For a logo → use `Logo`.
+
+---
+
+## Composition
+
+`Avatar` is a leaf. It renders one `<span>` holding the image, when there is one, and the initials fallback. It has no children and requires no ancestor.
+
+```
+Container
+└── Avatar
+```
+
+---
+
+## Components
+
+### Avatar
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| `name` | string | — | Whose avatar this is. The initials derive from it: the first letters of the first and last words, or one letter for a single word. |
+| `src` | string | — | Image URL. Absent or empty, the initials show. |
+| `alt` | string | — | Accessible name. Without it the avatar is decorative and hidden from assistive technology. |
+
+The fallback shows whenever there is no image, the image is still loading, or it failed to load. The image replaces it only once it has loaded.
+
+---
+
+## Canonical schema example
+
+```json
+{
+  "shopper-avatar": {
+    "type": "Avatar",
+    "props": { "name": "Jane Doe", "alt": "Jane Doe" },
+    "style": ["inline-flex", "size-10", "items-center", "justify-center", "rounded-full", "bg-gray-200", "text-sm", "font-medium"]
+  }
+}
+```
+
+## Common mistakes
+
+- **Leaving `alt` off a standalone avatar.** Without `alt` it is hidden from assistive technology, which is right beside text that already names the person and wrong anywhere else. Give it an `alt`.
+- **Giving it an `alt` beside the person's name.** The name is then announced twice.
+- **Expecting a photo from `name` alone.** `name` only derives initials; a photo needs `src`.
+- **Inventing `ProfilePicture` or `UserIcon`.** The component is `Avatar`.
+- **Styling without a size and shape.** The particle ships no look: give it a size, `rounded-full`, and overflow hidden, or the image and initials render unconstrained.
+
+---
+
+## Styling
+
+| Component | What you style | Plausible classes |
+|---|---|---|
+| `Avatar` | `data-fs-avatar` is the circle: size, shape, background, and the initials' type | `inline-flex size-10 shrink-0 items-center justify-center overflow-hidden rounded-full bg-[#E5E7EB] text-[14px] font-medium` |
+| Image | `data-fs-avatar-image` is the `<img>` once loaded | `size-full object-cover` |
+| Initials | `data-fs-avatar-fallback` is the initials span | `uppercase` |
+
+```json
+{
+  "shopper-avatar": {
+    "type": "Avatar",
+    "props": { "name": "Jane Doe", "alt": "Jane Doe" },
+    "style": [
+      "inline-flex", "size-10", "shrink-0", "items-center", "justify-center", "overflow-hidden",
+      "rounded-full", "bg-[#E5E7EB]", "text-[14px]", "font-medium", "[&_img]:size-full", "[&_img]:object-cover"
+    ]
+  }
+}
+```
+
+---
+
+## Related
+
+- [[badge]] — a status or count label; distinct from a person marker.
+- `Image` — a content image with no fallback or initials.
+- [[account-menu-identity]] — the account sidebar's name-and-avatar block, which composes `Avatar`.

package/dist/docs/billing-address.md

@@ -108,6 +108,7 @@ a form the shopper cannot see.
 | `billingMatchNoticeLabel` | string | `"Your billing address must match the one on your card or bank statement, or your bank may decline the order."` | Always-on billing-match disclaimer. Gated only by this prop and `billingMatchNoticeVisible` — unlike the two notices above, it never changes with the toggle, the form, `billingAddressRequired`, or a saved address. |
 | `billingMatchNoticeVisible` | boolean | `true` | Switches the billing-match disclaimer above on or off. A blank `billingMatchNoticeLabel` also renders nothing, even while this is `true` — the two rules never combine into an empty element. |
 | `fieldRequiredMessage` | string | `"This field is required."` | Shown as an inline field error under a required, blank address field once it has been touched (T38) — see Accessibility Contract below. One prop, not one per field: every rendered field but `complement` shares the same rule. An authored empty or whitespace-only string falls back to this default. |
+| `postalCodeInvalidMessage` | string | `"Enter a valid postal code."` | Shown as an inline field error under a touched, non-blank postal code that does not match the selected country's format (the descriptor's `rule.pattern`, the same one the delivery form enforces). Only the postal code reads this prop; the English default matches every other default on this form, so an author localises it with the rest. A blank postal code reads `fieldRequiredMessage` instead, never this. The message never contains the typed value. An authored empty or whitespace-only string falls back to this default. |
 | `disabled` | boolean | `false` | Disables the toggle, every form field, the country selector, and the submit button. |
 
 **Data:** declares no fragment and no `fetchStrategy`, so it fetches no shopper data. It reads only the
@@ -132,9 +133,9 @@ fields does not prevent that either — there is no `<form>` element anywhere in
 `required` is real for assistive technology but not wired to anything that blocks a click on a
 different button in a different component. Since T38 each rendered field (all but `complement`) does
 announce its own validity once touched — see Accessibility Contract below — but that announcement is
-driven by a local blur-tracked state, never by `required`'s own native validity, and it still does not
-gate the submit control; the submit gate is `isBillingAddressFormValid`, read at the submit button's
-own `disabled`.
+driven by a local touched-field state (blur, or a refused submit focusing the field), never by
+`required`'s own native validity, and it still does not gate the submit control; the submit gate is
+`isBillingAddressFormValid`, read at the submit button's own `disabled`.
 
 **The hard block itself lives elsewhere.** This component also publishes the exact same fact the notice
 renders from onto the shared payment draft (`billingAddressUnsaved`), and T24's submit gate
@@ -154,10 +155,13 @@ stays checked and the shopper never opens the form. It never reacts to the toggl
 `data-fs-billing-address-match-notice`, and renders as a plain paragraph with no ARIA role — it is a
 static disclaimer, not a live region reacting to an event.
 
+**Focus on refusal:** while the custom-address form is open, it registers itself so that when `PlaceOrder` refuses an order because the address was never saved, keyboard focus moves into the form: to the first rendered required field that is still blank; if none is blank, to the first rendered field whose value fails its country's format (a postal code `123` for BRA); and only when every field is filled and well-formed, to the submit control. The field the focus lands on, blank or malformed, is marked touched, so its message (`required` for a blank field, `format` for a malformed one) shows with the focus and no blur is needed. The country selector is never the target, and a disabled field or a disabled submit control (for example while saving) takes no focus. The reason stays in `PlaceOrder`'s existing alert and this component's unsaved-address notice. Focus moves only on the refused click.
+
 **Country adaptivity is entirely data-driven**, reusing the same country descriptors the delivery
 address step uses: Brazil shows a neighborhood/bairro field, the United States does not, and adding a
 new country anywhere in this codebase is a data-only change that this component picks up automatically
-— never a code change here.
+— never a code change here. The postal code's format is the same data: the descriptor's `rule.pattern`
+gates the submit button and the field error, so a country's format is defined once for both forms.
 
 ---
 
@@ -228,7 +232,7 @@ while the box is unchecked, and an optional inline error.
 | Required-billing-address note (`data-fs-billing-address-required-note`) | De-emphasized helper text | `text-[12px] text-[#666666]` |
 | Unsaved-address notice (`data-fs-billing-address-unsaved-notice`) | De-emphasized, non-error helper text | `text-[12px] text-[#666666]` |
 | Billing-match disclaimer (`data-fs-billing-address-match-notice`) | De-emphasized helper text, first child of the root | `text-[12px] text-[#666666]` |
-| Field error (`data-fs-field-error`) | Per-field validation message, shown once a required field is touched and left blank (T38) | `text-[12px] font-medium text-[#B00020]` |
+| Field error (`data-fs-field-error`) | Per-field validation message, shown once a field is touched: a blank required field, or a non-blank postal code that fails the country's format (T38); a refused submit that focuses the field touches it without a blur | `text-[12px] font-medium text-[#B00020]` |
 | Inline error (`data-fs-billing-address-error`) | Warning-toned alert text | `text-[12px] font-medium text-[#B00020]` |
 | Placing (`data-fs-billing-address-placing`) | Present while an order-placement sequence is in flight (T28) — distinct from `data-fs-billing-address-pending`, which this component already emits for its own local submit dispatch; the root is also `inert` and `aria-disabled` while placing | `opacity-60 cursor-not-allowed` |
 
@@ -252,10 +256,14 @@ There is no per-field styling hook beyond the particles' own `data-fs-checkbox-*
 ## Accessibility Contract
 
 **What the platform promises:** every rendered custom-address field (all but `complement`) announces
-its own validity once the shopper has touched it — focus, type nothing, and blur a required field, and
-it carries `aria-invalid="true"` plus an error message (`fieldRequiredMessage`) associated through
-`aria-describedby`; nothing is marked invalid before it is touched, and `complement` — the one optional
-field — is never marked invalid. This mirrors `CardEntry`'s own field-level validity mechanism exactly.
+its own validity once the shopper has touched it. A field is touched when the shopper blurs it, or when a
+refused submit moves focus to it (no blur ever comes there). Focus, type nothing, and blur a required
+field, and it carries `aria-invalid="true"` plus an error message (`fieldRequiredMessage`) associated
+through `aria-describedby`; nothing is marked invalid before it is touched, and `complement` — the one
+optional field — is never marked invalid. A postal code that is non-blank but not in the selected country's format
+is marked the same way, with `postalCodeInvalidMessage` as its error; switching country re-judges the
+typed value at once. Blank wins over format: a blank postal code reads `fieldRequiredMessage`, never the
+format message. This mirrors `CardEntry`'s own field-level validity mechanism exactly.
 Each field also carries its own `Field.Label`, authorable per field. A default `:focus-visible` outline
 is painted from the platform's own stylesheet on every field in this component.