@vtex/faststore 0.0.4 → 0.0.6

package/dist/docs/account-menu.md

@@ -0,0 +1,164 @@
+# AccountMenu
+
+**Category:** navigation
+**Purpose:** The account's section list — a navigation landmark listing the sections a merchant configured, with the one the shopper is reading announced.
+
+---
+
+## Visual cues (how to identify in an image)
+
+- A column of text links down the left of an account page, beside the section's own content.
+- One entry stands out — heavier weight, a filled row, a rule down one edge — and it is the section the page is showing.
+- On a narrow screen the same entries read as a single horizontal row of pills above the content, scrolling sideways rather than collapsing behind a control.
+- Five entries is the untouched default; a different count or a different order is the merchant's configuration, not a different component.
+
+The image is the source of truth for layout.
+
+## When to use
+
+- For the account's persistent section navigation, composed once in the `my-account` layout.
+
+## When NOT to use
+
+- For a general navigation list with no current-section marking → use [[navigation-link-list]].
+- For the trail down to a deep page → use `BreadcrumbRoot`, which keeps the "current page" claim.
+- For the header's sign-in / account control → use [[account-entry-point]].
+
+---
+
+## Composition
+
+Two parts, and the split is the point. `AccountMenuRoot` is the provider and `AccountMenuList` is the landmark.
+
+```text
+AccountMenuRoot
+├── AccountMenuList
+└── Slot                 ← the section's own page
+```
+
+**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.
+
+The sidebar still renders visually beside the section. That is the swatches' business, not the tree's.
+
+## Components
+
+### AccountMenuRoot
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| `items` | `{ label, href, external? }[]` | the library's five | Authored fallback, used when no CMS entry supplies a list. |
+| `children` | ReactNode | — | The landmark and the section's slot. |
+
+Content model (`account-menu`) fields, edited in the CMS:
+
+| Field | Type | Required | Notes |
+|-------|------|----------|-------|
+| `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[].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 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.
+
+**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.
+
+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.
+
+**V0 assumes the store's public paths carry no binding prefix.** The generated tree lives under a binding segment and a rewrite carries the unprefixed path inward, so the path the component reads matches the destination the merchant published. A store whose public base path *is* its binding id makes the prefixed URL canonical, and then no entry meets a segment boundary and nothing is current. The shipped `AccountEntryPoint` has the same exposure, so this is pre-existing rather than introduced here.
+
+### AccountMenuList
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| `label` | string | `'Account'` | Accessible name of the navigation landmark. |
+
+It takes no children: one `<li>` per resolved section is what it renders. With no sections to render it renders nothing at all, rather than an empty landmark for a screen-reader user to land in.
+
+**The current item is brought into view when the list scrolls.** A horizontally scrolling row can start with the current item outside the viewport — the fifth section of five leaves the shopper opening the page with no idea which one they are in. So on mount and on every route change, a current item in an overflowing list is scrolled into view. It is a no-op when the item is already visible, and it does not run at all when the list fits, since an unconditional scroll would move the page instead.
+
+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.
+
+### 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.
+
+---
+
+## Canonical schema example
+
+```json
+{
+  "account-menu": {
+    "type": "AccountMenuRoot",
+    "children": ["account-menu-list", "account-slot"],
+    "style": ["$account-menu"]
+  },
+  "account-menu-list": {
+    "type": "AccountMenuList",
+    "props": { "label": "Minha conta" },
+    "style": ["$account-menu-list"]
+  }
+}
+```
+
+Bound to a CMS entry, the Root authors no `items` at all — the entry supplies the whole list.
+
+## 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.
+- **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.
+
+---
+
+## Styling
+
+| Component | What you style | Plausible classes |
+|---|---|---|
+| `AccountMenuRoot` | `data-fs-account-menu` is the wrapper holding the sidebar and the section side by side | `flex gap-8 md:flex-row flex-col` |
+| `AccountMenuList` | `data-fs-account-menu-list` is the landmark; size the sidebar here | `w-56 shrink-0` |
+| Items | `data-fs-account-menu-items` is the `<ul>`, and the scroll container at narrow viewports | `flex flex-col gap-1` |
+| Item | `data-fs-account-menu-item` is one row | `list-none` |
+| 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` |
+
+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`:
+
+```json
+{
+  "AccountMenuRoot": {
+    "account-menu": [
+      "flex",
+      "flex-col",
+      "gap-6",
+      "md:flex-row",
+      "md:gap-8",
+      "[&_[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"
+    ]
+  }
+}
+```
+
+The current-item look reaches the anchor through the row, since the hook is on the `<li>` and the anchor is its child.
+
+---
+
+## Related
+
+- [[account-entry-point]] — the header control that links into the account.
+- [[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.