@vtex/faststore 0.0.5 → 0.0.7

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 /pvt/account 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.
@@ -58,11 +60,11 @@ Content model (`account-menu`) fields, edited in the CMS:
 | `items[].href` | string | yes | Its destination; `http(s)`, `mailto:`, `tel:`, or a 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, at `/pvt/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 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 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. `/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 `/pvt/account` 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/address-summary.md

@@ -17,6 +17,9 @@
 |-----------|-------|-------|
 | `AddressSummaryRoot` | `address: AddressSummaryFields` (required), `children?: ReactNode` | Provides the address to descendant components via context (no business coupling). Must wrap `AddressSummary` or another presentation component. |
 | `AddressSummary` | `className?: string`, `children?: ReactNode` | Read-only formatted display: recipient name, street/number/complement, neighborhood/city/state/postal code. Lines with no content are omitted. Composed `children` render inside the container in place of the default lines. Must be a descendant of `AddressSummaryRoot`. |
+| `AddressSummaryName` | `className?: string` | The shopper's own label for the address, or nothing when there is none. Not part of the default composition. Must be a descendant of `AddressSummaryRoot`. |
+| `AddressSummaryCountry` | `className?: string` | The address's country, shown exactly as provided, or nothing when there is none. Not part of the default composition. Must be a descendant of `AddressSummaryRoot`. |
+| `AddressSummaryField` | `field: AddressSummaryFieldKey` (required), `className?: string` | One address field, rendered inline (`<span>`), or nothing when it is empty. `field` is one of `recipientName`, `name`, `street`, `number`, `complement`, `neighborhood`, `city`, `state`, `postalCode`, `country`, `reference`. Compose several to build a line in a country's own order, e.g. number before street. Not part of the default composition. Must be a descendant of `AddressSummaryRoot`. |
 
 ---
 
@@ -32,6 +35,21 @@ or only one of them, composes the leaves instead:
 | `AddressSummaryStreet` | street, number, complement | all three absent |
 | `AddressSummaryLocality` | neighborhood, city, state, postal code | all absent |
 
+Three more parts compose beside these, none of which join the default: `AddressSummaryName` and
+`AddressSummaryCountry` are whole lines like the leaves above, and `AddressSummaryField` renders a single
+field inline so a consumer can assemble a line in another order — a United States address writes its number
+before its street, which no whole-line part can produce.
+
+| Part | Renders | Nothing when |
+|---|---|---|
+| `AddressSummaryName` | the shopper's own label for the address | no name |
+| `AddressSummaryCountry` | the country, exactly as provided | no country |
+| `AddressSummaryField` | one field, inline (`<span data-fs-address-summary-field="<key>">`) | that field is absent |
+
+`AddressSummaryCountry` shows whatever value it is given. The checkout's address stores an ISO alpha-3 code
+(e.g. `BRA`), and `Intl.DisplayNames` rejects alpha-3 codes, so a consumer that wants a country name rather
+than a code converts it before providing the address — this particle has no locale dependency of its own.
+
 ## Known gaps
 
 Found by review and deliberately left for the dedicated revision of these components.
@@ -41,9 +59,12 @@ Found by review and deliberately left for the dedicated revision of these compon
   outside an `AddressSummaryRoot` renders an empty styled block instead of failing loudly, while the
   definition still declares `requiresContext: 'address-summary'` — the declared contract and the runtime
   check no longer agree.
-- **`AddressSummaryRecipient`, `AddressSummaryStreet` and `AddressSummaryLocality` have no stories and no
-  test file of their own.** They are registered in the catalog but covered only indirectly, from
-  `shipping-address.test.tsx`. The `create-base-component` contract asks for both.
+- **`AddressSummaryRecipient`, `AddressSummaryStreet`, `AddressSummaryLocality`, `AddressSummaryName`,
+  `AddressSummaryCountry` and `AddressSummaryField` have no story of their own.** Each is registered in the
+  catalog and covered by `address-summary.test.tsx` (the first three also indirectly through
+  `shipping-address.test.tsx`), and the three new ones also appear inside `NamedWithCountry` and
+  `UsFieldOrder`, but none has the isolated, one-component-per-story coverage the `create-base-component`
+  contract asks for.
 
 ## Extensibility
 

package/dist/docs/alert-dialog.md

@@ -0,0 +1,204 @@
+# AlertDialog
+
+**Category:** layout
+**Purpose:** Confirmation prompt for an irreversible action. Wraps Base UI's Alert Dialog to give an overlay with the `alertdialog` role that is always modal and never closes on an outside click, so a stray click cannot answer the question. Composed like `Dialog`; the confirm control is a separate `Button`.
+
+---
+
+## Visual cues (how to identify in an image)
+
+An AlertDialog is present only when the image shows a **prompt that is already open**: the page behind it is **dimmed**, and a **small centered card** sits over it holding a **question as its heading** (for example "Delete this address?"), **one sentence of consequence**, and **two buttons** side by side, a plain **Cancel** and a **destructive confirm** that is often red.
+
+It is an overlay that appears after a click, not a region of the page. A static screenshot of a page rarely contains one, so do not add it "just in case". Compose it only when the image shows the open prompt, or when a design note names a confirmation step.
+
+Tell it apart from a `Dialog` by the question: an AlertDialog asks for an answer about something that cannot be undone, and offers no close icon in the corner and no way out except its own buttons. The image is the source of truth for layout.
+
+---
+
+## When to use
+
+- Confirming an **irreversible or destructive** action: deleting a saved address, removing a saved payment method, cancelling an order.
+- Any prompt where **accidentally dismissing it must not count as an answer**: the shopper has to choose Cancel or Confirm, or press Escape on purpose.
+
+## When NOT to use
+
+- **An informational overlay, a form, or a prompt that a click outside may safely close** — use `Dialog`.
+- **A side panel such as the mini-cart or the mobile menu** — use `Drawer`.
+- **A reversible action** — apply it and offer undo; a confirmation for something that can be undone is friction.
+- **A non-blocking tip or a small anchored panel** — use `Popover` or a non-modal `Dialog`.
+
+---
+
+## Composition
+
+`AlertDialogRoot` provides the open state to its descendants. The trigger and the portal are its two children; everything visible lives under the portal.
+
+```text
+AlertDialogRoot
+├── AlertDialogTrigger              (sibling of the portal, not inside it)
+└── AlertDialogPortal               (teleports its children to <body>)
+    ├── AlertDialogBackdrop         (before the viewport)
+    └── AlertDialogViewport         (positions the popup)
+        └── AlertDialogPopup        (the visible prompt, role alertdialog)
+            ├── AlertDialogTitle        (required)
+            ├── AlertDialogDescription  (the consequence)
+            ├── AlertDialogClose        (Cancel)
+            └── Button                  (the confirm control)
+```
+
+**Composition rules:**
+
+- `AlertDialogBackdrop` comes before `AlertDialogViewport`, both as direct children of the portal.
+- `AlertDialogTitle` is required: it is the prompt's accessible name.
+- **Focus starts on the first focusable element in the popup, except on touch.** Put the Cancel control first among the popup's children so the safe action is the default for a mouse or the keyboard. When the prompt is opened by touch, Base UI focuses the popup itself instead, which keeps the virtual keyboard from opening on Android. Cancel is not focused there, and neither is a destructive control. A schema cannot change that: only code can pass `initialFocus`, which gives Cancel the focus for every kind of interaction. Focus order follows the children order; the layout classes decide where each button appears.
+- The confirm control is a plain `Button`. The particle has no confirm part and runs no action: whatever the confirmation does is wired by the component that owns the prompt, not by the schema.
+- Child order reflects visual order, apart from the focus rule above.
+
+---
+
+## Components
+
+### AlertDialogRoot
+
+Provides the open state. Context-only: it renders no element of its own and takes no `className`, so it has no styling surface.
+
+No schema props. Components that open the prompt from code can control it with `open`, `defaultOpen`, and `onOpenChange` (the same signature as `Dialog`). There is **no `modal` prop**: an alert dialog is always modal.
+
+### AlertDialogTrigger
+
+The button that opens the prompt. Direct child of `AlertDialogRoot`. Accepts any children.
+
+No props.
+
+### AlertDialogPortal
+
+Teleports its children to `<body>`. Context-only: no element of its own and no `className`.
+
+No props.
+
+### AlertDialogBackdrop
+
+The dimmed layer behind the popup. Clicking it does **not** close the prompt.
+
+No props.
+
+### AlertDialogViewport
+
+A positioning container for the popup. Where the fixed positioning and centering go.
+
+No props.
+
+### AlertDialogPopup
+
+The visible prompt, with `role="alertdialog"`. Holds the title, the description, the cancel control, and the confirm control.
+
+No schema props. Code can pass `initialFocus` and `finalFocus` (a ref, a boolean, or a function) to choose where focus lands on open and on close. `initialFocus` is the only way to put focus on Cancel when the prompt is opened by touch, since the default there is the popup itself. Both take a ref, so a schema cannot express them: put Cancel first among the children, which covers a mouse and the keyboard.
+
+### AlertDialogTitle
+
+The prompt's heading, an `<h2>`. Required for the accessible name. State the question.
+
+No props.
+
+### AlertDialogDescription
+
+A paragraph read out with the prompt. State the consequence of confirming.
+
+No props.
+
+### AlertDialogClose
+
+Closes the prompt. Use it for the Cancel control. Several can appear.
+
+No props.
+
+---
+
+## Canonical schema example
+
+A delete-address confirmation. The confirm `Button` is inert here: in a store, the matter that owns the destructive action wires it.
+
+```json
+{
+  "delete-prompt": { "type": "AlertDialogRoot", "children": ["delete-trigger", "delete-portal"] },
+  "delete-trigger": {
+    "type": "AlertDialogTrigger",
+    "props": { "children": "Delete address" },
+    "style": ["px-[16px]", "py-[8px]", "text-[14px]", "font-medium", "text-[#B42318]", "border", "border-[#FDA29B]", "rounded-[6px]"]
+  },
+  "delete-portal": { "type": "AlertDialogPortal", "children": ["delete-backdrop", "delete-viewport"] },
+  "delete-backdrop": { "type": "AlertDialogBackdrop", "style": ["fixed", "inset-0", "bg-black/40"] },
+  "delete-viewport": {
+    "type": "AlertDialogViewport",
+    "style": ["fixed", "inset-0", "flex", "items-center", "justify-center", "p-[16px]"],
+    "children": ["delete-popup"]
+  },
+  "delete-popup": {
+    "type": "AlertDialogPopup",
+    "style": ["flex", "flex-col", "gap-[8px]", "w-full", "max-w-[448px]", "p-[24px]", "bg-white", "rounded-[12px]", "shadow-xl"],
+    "children": ["delete-title", "delete-description", "delete-actions"]
+  },
+  "delete-title": {
+    "type": "AlertDialogTitle",
+    "props": { "children": "Delete this address?" },
+    "style": ["text-[18px]", "font-semibold", "text-[#101828]"]
+  },
+  "delete-description": {
+    "type": "AlertDialogDescription",
+    "props": { "children": "It stops being offered at checkout. This cannot be undone." },
+    "style": ["text-[14px]", "text-[#667085]"]
+  },
+  "delete-actions": {
+    "type": "Container",
+    "style": ["flex", "justify-end", "gap-[12px]", "mt-[16px]"],
+    "children": ["delete-cancel", "delete-confirm"]
+  },
+  "delete-cancel": {
+    "type": "AlertDialogClose",
+    "props": { "children": "Cancel" },
+    "style": ["px-[16px]", "py-[8px]", "text-[14px]", "font-medium", "text-[#344054]", "border", "border-[#D0D5DD]", "rounded-[6px]"]
+  },
+  "delete-confirm": {
+    "type": "Button",
+    "props": { "children": "Delete" },
+    "style": ["px-[16px]", "py-[8px]", "text-[14px]", "font-medium", "text-white", "bg-[#D92D20]", "rounded-[6px]"]
+  }
+}
+```
+
+---
+
+## Common mistakes
+
+- **`AlertDialogContent`, `AlertDialogHeader`, `AlertDialogFooter`, `AlertDialogAction`, or `AlertDialogCancel`.** None exist. The prompt is `AlertDialogPopup`, Cancel is `AlertDialogClose`, and the confirm control is a plain `Button`.
+- **Looking for a `modal` prop, or a way to close on a backdrop click.** An alert dialog is always modal and ignores outside clicks. Use `Dialog` if the overlay should close on one.
+- **Leaving out `AlertDialogTitle`.** The prompt then has no accessible name.
+- **Putting the confirm `Button` first.** With a mouse or the keyboard, focus starts on the first focusable element, so a destructive control first makes Delete the default. Put Cancel first. On touch, focus starts on the popup itself either way.
+- **Putting `AlertDialogTrigger` inside `AlertDialogPortal`.** The trigger is a child of the root, beside the portal.
+- **Styling `AlertDialogRoot` or `AlertDialogPortal`.** They render no element and take no `style`. Style the backdrop, the viewport, and the popup.
+- **Expecting the schema to run the deletion.** A `Button` in a schema is inert; the owning component wires the confirm action.
+- **Using it for anything reversible or merely informational.** That is a `Dialog`.
+
+---
+
+## Styling
+
+| Component | What you style | Plausible classes |
+|---|---|---|
+| `AlertDialogTrigger` | The button that opens the prompt | `px-[16px] py-[8px] text-[14px] font-medium text-[#B42318] border border-[#FDA29B] rounded-[6px]` |
+| `AlertDialogBackdrop` | The dimmed layer over the page | `fixed inset-0 bg-black/40` |
+| `AlertDialogViewport` | Fixed positioning and centering of the popup | `fixed inset-0 flex items-center justify-center p-[16px]` |
+| `AlertDialogPopup` | The card: layout, background, radius, shadow, and its enter and exit | `flex flex-col gap-[8px] w-full max-w-[448px] p-[24px] bg-white rounded-[12px] shadow-xl data-[starting-style]:opacity-0 data-[ending-style]:opacity-0` |
+| `AlertDialogTitle` | The question | `text-[18px] font-semibold text-[#101828]` |
+| `AlertDialogDescription` | The consequence line | `text-[14px] text-[#667085]` |
+| `AlertDialogClose` | The Cancel control | `px-[16px] py-[8px] text-[14px] font-medium text-[#344054] border border-[#D0D5DD] rounded-[6px]` |
+
+`AlertDialogRoot` and `AlertDialogPortal` have no styling surface. Base UI sets `data-open`, `data-closed`, `data-starting-style`, and `data-ending-style` on the popup and the backdrop, so enter and exit animations key on those attributes.
+
+---
+
+## Related
+
+- `Dialog` — the general overlay, which a click outside may close. Use it for forms and information; use AlertDialog when the answer matters.
+- `Drawer` — a side panel for the mini-cart and the mobile menu, not a confirmation.
+- `Button` — the confirm control inside the popup.

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