@vtex/faststore 0.0.7 → 0.0.8

package/dist/docs/account-address-book.md

@@ -0,0 +1,519 @@
+# AccountAddressBook
+
+**Category:** identity
+**Purpose:** The My Account > Addresses surface — every address the signed-in shopper saved, each written in its own country's format, with loading, empty, and error states, an optional notice that explains when the checkout will not offer these addresses, and the form that adds an address or corrects a saved one.
+
+---
+
+## Visual cues (how to identify in an image)
+
+- A My Account page listing the shopper's saved addresses as a stack of entries, one per address.
+- Each entry starts with the recipient's name, then the street lines, then the country's name on the last line.
+- Entries from different countries break their lines differently: a Brazilian entry shows the neighborhood on its own line and `city - state`; a US entry shows `number street` and `city, state ZIP`.
+- A short "no saved addresses" message in place of the list, a "couldn't load your addresses" message with a "Try again" button, or a skeleton of three grey lines while loading.
+- Optionally, a notice above or below the list telling the shopper to complete their profile (add a phone number) with a link to the profile page.
+- An "Add address" button, and an "Edit" button on each entry.
+- Optionally, a short line inside an entry saying the store does not deliver to that address's country ("We don't deliver to this country at the moment."), on the entries it applies to and not the others.
+- A form with a "Country" list on top (or the country written as plain text), then a recipient name, then the fields that country asks for (a Brazilian form has a CEP, street, number, neighborhood, a state list, and a city list), then an optional reference, then "Save" and "Cancel". It opens under the list or in a dialog. After a country change, a line under the list can say which fields stay behind.
+
+The image is the source of truth for layout.
+
+Use `AccountAddressBook` and `AccountAddressForm` (not `ShippingAddress` or `BillingAddress`) when the image shows the shopper's saved addresses, or the form that adds or corrects one, on an account page.
+
+---
+
+## When to use
+
+- The My Account > Addresses page: the list of saved addresses, the form that adds or corrects one, and the confirmation that deletes one.
+- Any page that needs to display the shopper's saved addresses and has no checkout form around them.
+
+## When NOT to use
+
+- Changing the country of a saved address — an edit keeps its country.
+- Giving an address a name of its own — a saved address has no name field. The SDK's field model (`AccountFieldName`, `fs/address.field.name`) still lists `name`, so adding it later does not change the model, but no component renders or saves it.
+- The address a shopper picks or types during checkout — use `ShippingAddress` / `BillingAddress`.
+- A single address summary with no saved list behind it — compose `AddressSummary` directly.
+- The signed-out prompt — compose `SignInForm` next to a `SessionGuard`. The root renders nothing for a shopper who is not logged in.
+
+---
+
+## Composition
+
+Every part except `AccountAddressBookProfileNotice` must sit inside `AccountAddressBookRoot`. The notice has its own data and needs only a `SessionRoot` ancestor. `AccountAddressFormRoot` and `AccountAddressBookDeleteConfirm` also need a `ToastProvider` ancestor, because a save and a delete show a toast.
+
+```
+SessionRoot                                   (required ancestor; must resolve to loggedIn)
+├── AccountAddressBookProfileNotice           (optional; own data; renders nothing when the profile is complete)
+└── AccountAddressBookRoot                    (own data; owns the state)
+    ├── AccountAddressBookLoading             (visible only while loading)
+    ├── AccountAddressBookError               (visible on error and while its retry loads; retry button inside)
+    ├── AccountAddressBookEmpty               (visible only when the book has no addresses)
+    └── AccountAddressBookList                (visible only when the book has addresses)
+        └── AccountAddressBookItem            (repeated once per address)
+            ├── AddressSummaryRecipient       (optional; default entry already has it)
+            ├── AccountAddressBookItemLines   (the address lines in the country's format)
+            ├── AddressSummaryCountry
+            ├── AccountAddressBookItemDeliverability (optional; own data; marks an address in a country the store does not ship to)
+            ├── AccountAddressBookEditTrigger (optional; opens the form in edit mode for this entry)
+            └── AccountAddressBookDeleteTrigger (optional; asks to delete this entry's address)
+
+    ├── AccountAddressBookDeleteConfirm       (optional; the one alert dialog every delete trigger opens)
+    ├── AccountAddressBookAddTrigger          (optional; opens the form in add mode; shown in every state)
+    └── AccountAddressBookFormSlot            (or AccountAddressBookFormDialog; shows the form while one is open)
+        └── AccountAddressFormRoot            (the form; with no children it renders the parts below in this order)
+            ├── AddressCountryControl         (own data; the country list, or the country as text)
+            ├── AccountAddressCountryNotice   (what a country change left behind)
+            ├── AccountAddressFormRecipientName
+            ├── AccountAddressFormFields      (one field per field the country asks for)
+            ├── AccountAddressFormReference
+            ├── AccountAddressFormError       (the error about the whole form)
+            ├── AccountAddressFormSubmit
+            └── AccountAddressFormCancel
+```
+
+**On its own page**, the same form needs no book. The add page places `AccountAddressFormRoot` directly under `SessionRoot`. The edit page's route ends in `[id]`, and the form sits inside an `AccountAddressRecord`:
+
+```
+SessionRoot
+└── AccountAddressRecord                      (route /pvt/address/[id]; reads the one address the route names)
+    ├── AccountAddressRecordError             (optional; visible only when the read failed)
+    └── AccountAddressFormRoot                (opens in edit mode, seeded with the address)
+```
+
+Compose all four state parts as **siblings** inside the root. Each one decides for itself whether to render, so the schema never switches between them. Child order reflects visual order.
+
+`AccountAddressBookItem` with no children already renders the default entry (recipient, lines, country). Give it children only to reorder or restyle the entry, or to add the edit trigger; when you do, compose the summary yourself inside an `AddressSummary`. Put the `AddressSummary*` parts and `AccountAddressBookItemLines` inside it, never outside. `AccountAddressBookItemDeliverability` also sits inside the item, beside the summary, because it reads the entry's country: it is not part of the default entry, so compose the summary yourself when you add it.
+
+The form opens where you place it. `AccountAddressBookFormSlot` shows it in place under the list; `AccountAddressBookFormDialog` shows it in a modal dialog. Place one of them, not both. No prop picks the layout.
+
+Deleting needs two parts: an `AccountAddressBookDeleteTrigger` inside each entry, and one `AccountAddressBookDeleteConfirm` under the root. The confirmation is an alert dialog, so wherever you place it, it shows over the page.
+
+To let the shopper choose the country of a new address, compose `AddressCountryControl` explicitly under `AccountAddressFormRoot`, with `AccountAddressCountryNotice` right after it. The control reads where the store ships through its own fragment, and that fragment joins the page query only when the control is in the schema. In the root's default composition the control gets no list, so it shows the root's `defaultCountry` as text.
+
+---
+
+## Behavior
+
+- **One state at a time.** The root reads the book, the loading flag, and the error: a resolved book is `empty` (no addresses) or `ready`; no book while loading is `loading`; no book, not loading, with an error is `error`; anything else renders nothing. The state is exposed as `data-fs-account-address-book-state`.
+- **The loading part stays mounted.** It is a polite live region (`<output aria-live="polite">`) with content only while loading, so a screen reader announces the change. The message is `sr-only`, so it is announced but not seen; the skeleton is the visible placeholder.
+- **Country order.** The lines follow the country's own convention (BRA, USA, and the other registered countries). A field the address does not have drops its separator instead of leaving a stray comma or dash.
+- **Country name.** The address stores a three-letter code (`BRA`). The entry shows the country's name in the shopper's language (`Brasil`, `Brazil`). An unregistered code is shown as it is; an empty one shows nothing.
+- **Retry loads the book again in place.** The retry button re-runs the page query through the page root, so the shopper stays on the page. While it runs, the error stays on screen beside the loading part, and the button stays mounted with `aria-disabled` and `aria-busy`, so focus stays on it and a second press sends nothing. If the read fails again, the same button is enabled again. When the list or the empty message replaces it, focus moves to the book, unless the shopper moved focus elsewhere meanwhile. Under a root that offers no `refetch`, it reloads the page.
+- **Self-gate.** The root and the form render nothing unless the session is `loggedIn`.
+- **Deliverability marker.** The marker shows on an address only when the store's own shipping countries are known (`PLATFORM`) and the address's country, trimmed and upper-cased, is not among them. It renders nothing under the single-country fallback, when the shipping-country read failed, when the page does not carry it, or when the address has no country, so it never flags an address on a guess. It is plain text read with the address, not a live region. Marked or not, the entry's edit and delete controls work the same.
+- **A failed shipping-country read costs only the marker.** The list keeps its state and its addresses.
+- **Notice rule.** The notice shows only when the profile has resolved and has no home phone, because the checkout drops saved addresses for a profile without one.
+- **One form at a time.** The book's root holds which form is open. A trigger opens it and replaces any open one; closing it returns focus to the trigger that opened it. If the save removed that trigger (the address no longer existed), focus moves to the book.
+- **A new draft each time.** Every open starts from the saved address, or from nothing for an add. Cancel, Escape, and a saved form drop the draft.
+- **The country's rules decide the fields.** The form shows the fields, labels, limits, and lists of the address's country, in that country's order. A country the rules library does not cover gets a street field alone. A list can depend on another: Brazil's city list follows its state, and changing the state clears the city. Fields show once the country's rules have loaded, and saving stays disabled until then.
+- **A new address picks a country the store ships to.** `AddressCountryControl` lists the store's shipping countries by name, in the shopper's language and sorted for it. The form starts on the root's `defaultCountry` (`BRA` unless set) when the store ships there, and otherwise on the first country of the list. With one country there is no choice: the control renders nothing and the address takes that country. Only the shown country's rules load.
+- **The country is text when there is nothing to choose.** A saved address keeps its own country, shown as text. When the list could not be read, or the control is not in the page query, a new address takes `defaultCountry`, shown as text, and saving still works; the server refuses a country the store does not ship to.
+- **Changing the country keeps what fits.** The recipient, the reference, and every value the new country takes stay. The rest is kept for the old country and comes back on switching back to it, also after a third country; a value typed meanwhile in the same field wins. While the new country's rules load, the old fields stay editable, Save is disabled, the form is `aria-busy`, and only the last pick applies. Picking the current country again cancels the change. A change that fails to load keeps everything as it was and shows an error; the next pick retries.
+- **The notice says what stayed behind.** After a change, `AccountAddressCountryNotice` names the fields the new country left out, with the labels the old country showed, and says they come back on switching back. It is a polite live region that stays mounted, and it is empty when the change carried everything. It changes only with the next country change, never on typing or a blocked save.
+- **The whole address is checked on every save.** The server checks the whole record, so an untouched gap in a saved address blocks the save too. A saved address with gaps shows them when the form opens, without moving focus.
+- **A blocked save names the fields.** The form marks each field in error, moves focus to the first one in form order, keeps what was typed, and announces "Address not saved" and how many fields need attention through a polite status region that stays mounted.
+- **The server's refusal lands on the field it names.** Its message is never shown; the field shows the catalog message for its code (`This field is required.` or `Check this field.`). A refusal that names a field the form does not show, no field at all, or a country, shows an error about the whole form, so a save never fails silently. Each of `NOT_FOUND`, `UNAUTHORIZED`, `UNSUPPORTED_COUNTRY` (the store does not deliver to the country), and the rest has its own message.
+- **What is sent.** An add sends the country and every field on screen that has text; the values kept for another country are never sent. An edit sends the address id and only the fields that changed; a field the shopper cleared goes as an empty string, which erases it. An edit with no change closes without a call. A second submit while one is in flight does nothing.
+- **Only Save submits.** Enter in a text field does not save, so a shopper who presses it mid-address is not sent a half-typed one. Enter on the Save button still saves.
+- **On success.** A toast confirms, the form closes, and the list shows the result with no reload.
+- **On its own page, leaving navigates.** With no book above it, a save, a save with no changes, and Cancel all go to `returnHref` (default: the store's `address` page). Under a book the form closes and `returnHref` is not used. A `returnHref` given as a string that is not site-relative is refused: the shopper stays on the form and a console warning names the value. A save has already happened by then, so its toast still shows.
+- **The toast has to outlive the navigation.** Mount the `ToastProvider` in the layout, not in the page, or the confirmation disappears with the form.
+- **Delete asks first.** The trigger only asks. The confirmation opens as an alert dialog that names the address, puts focus on Cancel, and closes only on Cancel or Escape: a click outside does not answer it. Declining changes nothing and returns focus to the trigger.
+- **Deleting waits for the server.** Confirming sends one removal. While it runs, the Delete button is disabled and `aria-busy`, Cancel is disabled, and Escape does nothing, so the outcome always lands in front of the shopper. The entry leaves the list only once the server says so.
+- **A refused delete keeps the address.** The dialog stays open with an alert that says the address was not deleted (or that the session expired), and Delete works again to try once more. The server's message is never shown. An address the server no longer has counts as deleted.
+- **After a delete.** A toast confirms, the dialog closes, and focus moves to the book, because the trigger left with its entry. Deleting the last address leaves the book `empty`, so compose an `AccountAddressBookEmpty`. An open edit form for the deleted address closes with it; a form for another address stays open.
+
+---
+
+## Components
+
+### AccountAddressBookRoot
+
+No props beyond `className`. Fetches `customerAddressBook` (the address ids) with `fetchStrategy: 'reactive'`, requires `session`, provides `account-address-book`, and declares a skeleton.
+
+### AccountAddressBookList
+
+No props beyond `className`. Renders a `<ul>` with one `<li>` per address and repeats its children inside each `<li>`.
+
+### AccountAddressBookItem
+
+No props beyond `className` and `children`. Fetches the address fields with `fetchStrategy: 'reactive-list-item'`, provides `account-address-book-item` and `address-summary`.
+
+### AccountAddressBookItemLines
+
+No props beyond `className`. Renders one `<p>` per address line.
+
+### AccountAddressBookLoading
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| `message` | string | catalog copy | Loading message. A blank value falls back to the catalog. |
+
+### AccountAddressBookEmpty
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| `message` | string | catalog copy | Empty message. A blank value falls back to the catalog. |
+
+### AccountAddressBookError
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| `message` | string | catalog copy | Error message. A blank value falls back to the catalog. |
+| `retryLabel` | string | catalog copy | Retry button label. A blank value falls back to the catalog. |
+
+### AccountAddressBookAddTrigger
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| `label` | string | catalog copy | Button text. A blank value falls back to the catalog. |
+
+A button that opens the form in add mode. It shows in every state of the book, the empty one too.
+
+### AccountAddressBookEditTrigger
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| `label` | string | catalog copy | Visible text. A blank value falls back to the catalog. |
+
+A button inside `AccountAddressBookItem` that opens the form in edit mode for that entry. Its accessible name is the visible text followed by the address's first line, so each button in a list is told apart.
+
+### AccountAddressBookFormSlot
+
+No props of its own; `className` and the other `div` attributes land on its element. Shows its children in place while a form is open, and nothing otherwise. Each open starts a new draft.
+
+### AccountAddressBookFormDialog
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| `title` | string | catalog copy for the mode | Dialog title. A blank value falls back to the catalog. |
+| `className` | string | none | Goes on the dialog's popup. The dialog renders in a portal outside the page, so this is the element a store sizes and places. |
+
+Shows its children in a modal dialog while a form is open. Escape and the close button cancel the form.
+
+### AccountAddressBookDeleteTrigger
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| `label` | string | catalog copy | Visible text. A blank value falls back to the catalog. |
+
+A button inside `AccountAddressBookItem` that asks to delete that entry's address. It deletes nothing by itself. Its accessible name is the visible text followed by the address's first line, so each button in a list is told apart.
+
+### AccountAddressBookDeleteConfirm
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| `title` | string | catalog copy | The question. |
+| `description` | string | catalog copy | What deleting means. The address's first line always shows before it. |
+| `cancelLabel` | string | catalog copy | The control that backs out. |
+| `confirmLabel` | string | catalog copy | The control that deletes. |
+| `deletedMessage` | string | catalog copy | Toast after the address is deleted. |
+| `failedMessage` | string | catalog copy | Shown in the dialog when the address was not deleted. |
+| `unauthorizedMessage` | string | catalog copy | Shown in the dialog when the session expired. |
+| `className` | string | none | Goes on the dialog's popup. The dialog renders in a portal outside the page, so this is the element a store sizes and places. |
+
+One per address book, under `AccountAddressBookRoot`. It opens for the entry whose trigger was activated, and it needs a `ToastProvider` ancestor.
+
+### AccountAddressFormRoot
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| `defaultCountry` | string | `BRA` | ISO 3166-1 alpha-3 code of the country a new address prefers: taken when the store ships there or its list is unknown. A blank value falls back to `BRA`. |
+| `addedMessage` | string | catalog copy | Toast after an address is added. |
+| `savedMessage` | string | catalog copy | Toast after an address is saved. |
+| `blockedMessage` | string | catalog copy | What the status region announces when a save is blocked. |
+| `returnHref` | link | `{ standard: 'address' }` | Where leaving the form goes on its own page: a page reference, or a site-relative string (an off-site string is refused). Ignored under an address book. |
+
+Requires `session`, provides `account-address-form`, and declares `actions: { address: ['create', 'update'] }`. Needs a `ToastProvider` ancestor. With no children it renders its parts in the default order.
+
+The address to edit comes from the book's open edit form, else from an `AccountAddressRecord` above it, else the form opens empty to add.
+
+It renders the shared `FormRoot` and registers itself as the form's only fieldset, so react-hook-form holds the draft. Each field part registers under the `accountAddress` namespace while it is on screen. The address rules still decide what is valid and what is sent: the root checks the draft with the country's rules on Save and never hands a rule to react-hook-form. The form particle's `FormClear`, `FormReset` and `FormError` are not part of this anatomy; `AccountAddressFormCancel` and `AccountAddressFormError` cover them.
+
+### AccountAddressRecord
+
+The one saved address a page's route names. Place it on a page whose route ends in `[id]`; the segment feeds `customerAddress(id: $id)`. It has no props. Requires `session`, provides `account-address-record`, and renders nothing unless the session is `loggedIn`.
+
+An id that is not the shopper's and an id that never existed are the same response: the server answers `null` for both, the page returns 404, and the layout's not-found page renders. This component never sees that case. While no address has resolved, an `AccountAddressFormRoot` beneath it renders nothing, so it never falls back to adding.
+
+### AccountAddressRecordError
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| `message` | string | catalog copy | Shown when the address could not be read. |
+| `retryLabel` | string | catalog copy | The retry control's text. Retry reloads the page. |
+
+Visible only when the read failed and no address resolved, as an alert. Must be inside `AccountAddressRecord`.
+
+### AddressCountryControl
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| `label` | string | catalog copy | The list's label. A blank value falls back to the catalog. |
+
+Fetches `shippingCountries` (`countries` and `source`) with `fetchStrategy: 'reactive'`, requires `account-address-form`, and declares a skeleton. In add mode with two or more countries it renders a list; with one it renders nothing; in edit mode, or with no list, it renders the country as text.
+
+### AccountAddressCountryNotice
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| `message` | string | catalog copy | Replaces the whole sentence. Takes the ICU arguments `count`, `country`, `previous`, and `fields`. A blank or malformed value falls back to the catalog. |
+
+Requires `account-address-form`. An `<output aria-live="polite">` that stays mounted, empty until a country change leaves fields behind.
+
+### AccountAddressFormRecipientName and AccountAddressFormReference
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| `label` | string | catalog copy | Field label. A blank value falls back to the catalog. |
+
+The recipient name is required for every country. The reference is optional.
+
+### AccountAddressFormFields
+
+No props beyond `className`, which goes on every field's wrapper. One field per field the country asks for, in the country's order.
+
+### AccountAddressFormError
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| `unrenderedFieldMessage` | string | catalog copy | A refusal on a field the form does not show. |
+| `notFoundMessage` | string | catalog copy | The address no longer exists. |
+| `unauthorizedMessage` | string | catalog copy | The session expired. |
+| `saveFailedMessage` | string | catalog copy | The save failed for any other reason. |
+| `rulesFailedMessage` | string | catalog copy | The country's rules did not load. |
+| `countrySwitchFailedMessage` | string | catalog copy | A country change could not load. |
+| `unsupportedCountryMessage` | string | catalog copy | The store does not deliver to the country. |
+
+An alert for the whole form. Renders nothing when there is no error.
+
+### AccountAddressFormSubmit and AccountAddressFormCancel
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| `label` | string | catalog copy | Button text. A blank value falls back to the catalog. |
+
+Submit is disabled until the rules load, while a country change loads, and while a save is in flight, and is marked busy then. Cancel closes the form, or, on its own page, goes to the form root's `returnHref`. Cancel is disabled while a save is in flight, and under a book's `AccountAddressBookFormDialog` Escape and the close control wait for the save to settle, so a refusal is never lost.
+
+### AccountAddressBookProfileNotice
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| `href` | link | `{ standard: 'profile' }` | Where the link goes: a page reference, or a site-relative string. |
+| `message` | string | catalog copy | Notice text. |
+| `linkLabel` | string | catalog copy | Link label. |
+
+Fetches `customerProfile` with `fetchStrategy: 'reactive'` and requires `session`.
+
+### AccountAddressBookItemDeliverability
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| `message` | string | catalog copy | Marker text. A blank value falls back to the catalog. |
+
+Fetches `shippingCountries` with `fetchStrategy: 'reactive'` and requires `account-address-book-item`. Renders one `<p>` when it marks an address, and nothing otherwise.
+
+---
+
+## Canonical schema example
+
+```json
+{
+  "session": { "type": "SessionRoot", "children": ["profile-notice", "address-book"] },
+  "profile-notice": { "type": "AccountAddressBookProfileNotice", "children": [] },
+  "address-book": {
+    "type": "AccountAddressBookRoot",
+    "children": ["address-loading", "address-error", "address-empty", "address-list"]
+  },
+  "address-loading": { "type": "AccountAddressBookLoading", "children": [] },
+  "address-error": { "type": "AccountAddressBookError", "children": [] },
+  "address-empty": { "type": "AccountAddressBookEmpty", "children": [] },
+  "address-list": { "type": "AccountAddressBookList", "children": ["address-item"] },
+  "address-item": { "type": "AccountAddressBookItem", "children": [] }
+}
+```
+
+`address-item` appears once in the schema and renders once per saved address. Do not repeat it.
+
+With the form, the same book adds an add trigger, an edit trigger inside the item, and a slot holding the form root. A root with no children renders the default form:
+
+```json
+{
+  "session": { "type": "SessionRoot", "children": ["address-book"] },
+  "address-book": {
+    "type": "AccountAddressBookRoot",
+    "children": ["address-add", "address-list", "address-form-slot"]
+  },
+  "address-add": { "type": "AccountAddressBookAddTrigger", "children": [] },
+  "address-list": { "type": "AccountAddressBookList", "children": ["address-item"] },
+  "address-item": { "type": "AccountAddressBookItem", "children": ["address-summary", "address-edit"] },
+  "address-summary": {
+    "type": "AddressSummary",
+    "children": ["address-recipient", "address-lines", "address-country"]
+  },
+  "address-recipient": { "type": "AddressSummaryRecipient", "children": [] },
+  "address-lines": { "type": "AccountAddressBookItemLines", "children": [] },
+  "address-country": { "type": "AddressSummaryCountry", "children": [] },
+  "address-edit": { "type": "AccountAddressBookEditTrigger", "children": [] },
+  "address-form-slot": { "type": "AccountAddressBookFormSlot", "children": ["address-form"] },
+  "address-form": { "type": "AccountAddressFormRoot", "props": { "defaultCountry": "BRA" }, "children": [] }
+}
+```
+
+To open the form in a dialog, swap `AccountAddressBookFormSlot` for `AccountAddressBookFormDialog`. The page needs a `ToastProvider` above it.
+
+To offer the country choice, give the form root its parts, with the control first:
+
+```json
+{
+  "address-form": {
+    "type": "AccountAddressFormRoot",
+    "props": { "defaultCountry": "BRA" },
+    "children": [
+      "form-country",
+      "form-country-notice",
+      "form-recipient",
+      "form-fields",
+      "form-reference",
+      "form-error",
+      "form-submit",
+      "form-cancel"
+    ]
+  },
+  "form-country": { "type": "AddressCountryControl", "children": [] },
+  "form-country-notice": { "type": "AccountAddressCountryNotice", "children": [] },
+  "form-recipient": { "type": "AccountAddressFormRecipientName", "children": [] },
+  "form-fields": { "type": "AccountAddressFormFields", "children": [] },
+  "form-reference": { "type": "AccountAddressFormReference", "children": [] },
+  "form-error": { "type": "AccountAddressFormError", "children": [] },
+  "form-submit": { "type": "AccountAddressFormSubmit", "children": [] },
+  "form-cancel": { "type": "AccountAddressFormCancel", "children": [] }
+}
+```
+
+To delete, add an `AccountAddressBookDeleteTrigger` to the item's children, and one `AccountAddressBookDeleteConfirm` to the root's:
+
+```json
+{
+  "address-book": {
+    "type": "AccountAddressBookRoot",
+    "children": ["address-empty", "address-list", "address-delete-confirm"]
+  },
+  "address-item": { "type": "AccountAddressBookItem", "children": ["address-summary", "address-delete"] },
+  "address-delete": { "type": "AccountAddressBookDeleteTrigger", "children": [] },
+  "address-delete-confirm": { "type": "AccountAddressBookDeleteConfirm", "children": [] }
+}
+```
+
+To mark the addresses the store does not ship to, add an `AccountAddressBookItemDeliverability` to the item's children. The item then composes its own summary, because children replace the default entry:
+
+```json
+{
+  "address-item": {
+    "type": "AccountAddressBookItem",
+    "children": ["address-summary", "address-deliverability"]
+  },
+  "address-summary": {
+    "type": "AddressSummary",
+    "children": ["address-recipient", "address-lines", "address-country"]
+  },
+  "address-recipient": { "type": "AddressSummaryRecipient", "children": [] },
+  "address-lines": { "type": "AccountAddressBookItemLines", "children": [] },
+  "address-country": { "type": "AddressSummaryCountry", "children": [] },
+  "address-deliverability": { "type": "AccountAddressBookItemDeliverability", "children": [] }
+}
+```
+
+---
+
+## Common mistakes
+
+- **Using `ShippingAddress` or `BillingAddress` for a saved-address list.** Those are checkout forms. The list is `AccountAddressBookRoot` with `AccountAddressBookList`.
+- **Switching between the state parts in the schema.** Compose loading, error, empty, and list together as siblings. Each renders only in its own state.
+- **Repeating `AccountAddressBookItem` once per address in the schema.** Compose it once inside `AccountAddressBookList`. The list repeats it.
+- **Rendering `AccountAddressBookItem` outside `AccountAddressBookList`.** It needs the address that the list hands it.
+- **Putting `AccountAddressBookProfileNotice` inside `AccountAddressBookRoot` for data reasons.** It needs nothing from the root; place it anywhere under `SessionRoot`.
+- **Rendering any part outside `SessionRoot`.** The session hook throws.
+- **Styling the loading message with `display: none`.** It is already visually hidden with `sr-only`; `display: none` would stop the live region from announcing it.
+- **Placing `AccountAddressBookDeleteTrigger` without an `AccountAddressBookDeleteConfirm`.** The trigger only asks; with no confirmation under the root, nothing opens and nothing is deleted.
+- **Placing a confirmation per entry.** Place one `AccountAddressBookDeleteConfirm` under the root. Every trigger opens it.
+- **Placing `AccountAddressBookDeleteTrigger` outside `AccountAddressBookItem`.** It needs the address that the entry hands it.
+- **Rendering the confirmation without a `ToastProvider`.** A delete shows a toast, and the toast hook throws without a provider.
+- **Closing the confirmation on a click outside.** It is an alert dialog on purpose: a stray click must not answer it. Do not swap in a `Dialog`.
+- **Placing the form outside the slot or the dialog.** The form shows only where a placement part puts it. Place `AccountAddressFormRoot` inside `AccountAddressBookFormSlot` or `AccountAddressBookFormDialog`, and place one of them, not both.
+- **Placing `AccountAddressBookEditTrigger` outside `AccountAddressBookItem`.** It needs the address that the entry hands it.
+- **Giving `AccountAddressBookItem` children and dropping the summary.** Children replace the default entry. Compose the `AddressSummary` parts yourself next to the edit trigger.
+- **Rendering the form without a `ToastProvider`.** Saving shows a toast, and the toast hook throws without a provider.
+- **Placing `AccountAddressBookItemDeliverability` outside `AccountAddressBookItem`.** It needs the country that the entry hands it, and throws without it.
+- **Expecting the marker to appear when the store ships to one country.** Under the single-country fallback it renders nothing on purpose: one guessed country cannot tell a deliverable address from an undeliverable one.
+- **Listing the form's fields in the schema.** `AccountAddressFormFields` renders the ones the country asks for. Do not compose a field per country.
+- **Expecting the default form to offer a country choice.** A childless `AccountAddressFormRoot` shows `defaultCountry` as text. Compose `AddressCountryControl` explicitly to offer the countries the store ships to.
+- **Placing `AddressCountryControl` or `AccountAddressCountryNotice` outside `AccountAddressFormRoot`.** Both need the form; the hook throws without it.
+- **Using `ShippingAddress*` for the account form.** Those parts are the checkout form.
+
+---
+
+## Styling
+
+| Component | What you style | Plausible classes |
+|---|---|---|
+| `AccountAddressBookRoot` | `[data-fs-account-address-book]`; carries `-state` | `flex flex-col gap-4` |
+| `AccountAddressBookList` | `[data-fs-account-address-book-list]`, items via `[data-fs-account-address-book-list-item]` | `flex flex-col gap-4` |
+| `AccountAddressBookItem` | `[data-fs-account-address-book-item]` | `flex flex-col gap-1 rounded-md border border-[#D4D4D4] p-4` |
+| `AccountAddressBookItemLines` | each line `[data-fs-account-address-book-line]` | `text-[14px] text-[#404040]` |
+| `AccountAddressBookLoading` | `[data-fs-account-address-book-loading]`, message via `-loading-message` | Leave the message as is: it is already `sr-only` |
+| `AccountAddressBookSkeleton` | `[data-fs-account-address-book-skeleton]`, lines via `-skeleton-line` | `animate-pulse` |
+| `AccountAddressBookEmpty` | `[data-fs-account-address-book-empty]` | `text-[14px] text-[#737373]` |
+| `AccountAddressBookError` | `[data-fs-account-address-book-error]`, message via `-error-message`, button via `[data-fs-account-address-book-retry]` | `flex flex-col gap-2 text-[#B91C1C]` |
+| `AccountAddressBookAddTrigger` | `[data-fs-account-address-book-add]` | `rounded-md bg-[#2563EB] px-4 py-2 font-semibold text-white` |
+| `AccountAddressBookEditTrigger` | `[data-fs-account-address-book-edit]` | `text-[14px] font-semibold text-[#2563EB]` |
+| `AccountAddressBookFormSlot` | `[data-fs-account-address-book-form-slot]` | `rounded-md border border-[#D4D4D4] p-4` |
+| `AccountAddressBookFormDialog` | popup via `[data-fs-account-address-book-form-dialog]`, with the `Dialog` particle's own `data-fs-dialog-*` attributes | `w-full max-w-md rounded-md bg-white p-6` |
+| `AccountAddressBookDeleteTrigger` | `[data-fs-account-address-book-delete]` | `text-[14px] font-semibold text-[#B91C1C]` |
+| `AccountAddressBookDeleteConfirm` | popup via `[data-fs-account-address-book-delete-confirm]`, with the `AlertDialog` particle's own `data-fs-alert-dialog-*` attributes; the address via `-delete-address`; the refusal via `-delete-error`; the confirming button via `-delete-submit` | `w-full max-w-md rounded-md bg-white p-6` |
+| `AccountAddressFormRoot` | `[data-fs-account-address-form]`, with the form particle's own `data-fs-form` and `data-fs-form-pending`; carries `-mode` (`add` or `edit`); status region via `-status` | `flex flex-col gap-3` |
+| `AddressCountryControl` | `[data-fs-address-country-control]`; carries `-mode` (`select` or `text`) and `-pending` while a change loads; the text via `-text`; the list's trigger via `[data-fs-account-address-form-control]` | `flex flex-col gap-1 text-[14px] text-[#404040]` |
+| `AccountAddressCountryNotice` | `[data-fs-account-address-country-notice]` | `text-[14px] text-[#404040]` |
+| `AccountAddressFormRecipientName`, `AccountAddressFormFields`, `AccountAddressFormReference` | each field's wrapper `[data-fs-account-address-form-field="<name>"]`; a list field's error via `-field-error` | `flex flex-col gap-1` |
+| `AccountAddressFormError` | `[data-fs-account-address-form-error]`, whose value is the kind of error | `text-[14px] text-[#B91C1C]` |
+| `AccountAddressFormSubmit` | `[data-fs-account-address-form-submit]` | `rounded-md bg-[#2563EB] px-4 py-2 font-semibold text-white` |
+| `AccountAddressFormCancel` | `[data-fs-account-address-form-cancel]` | `rounded-md border border-[#D4D4D4] px-4 py-2` |
+| `AccountAddressBookProfileNotice` | `[data-fs-account-address-book-profile-notice]`, text via `-message`, link via `-link` | `rounded-md border border-[#FBBF24] bg-[#FFFBEB] p-3 text-[14px]` |
+| `AccountAddressBookItemDeliverability` | `[data-fs-account-address-book-item-deliverability]` | `text-[14px] text-[#B45309]` |
+
+```json
+{
+  "address-list": {
+    "type": "AccountAddressBookList",
+    "style": ["flex", "flex-col", "gap-[16px]"],
+    "children": ["address-item"]
+  },
+  "address-item": {
+    "type": "AccountAddressBookItem",
+    "style": ["flex", "flex-col", "gap-[4px]", "rounded-[6px]", "border", "border-[#D4D4D4]", "p-[16px]"],
+    "children": []
+  }
+}
+```
+
+---
+
+## Known gaps
+
+- **A failed profile read fails the whole book.** The notice and the book share one page query, and both roots are non-null. If the profile read fails, the list also goes to its error state. The same limit applies to any later part that joins the page query.
+- **The deliverability marker reads the store's shipping countries when the page loads.** It does not refresh until the page loads again, and it stays silent if that first read failed.
+- **The default form offers no country choice.** A childless form root shows `defaultCountry` as text, because only a control placed in the schema joins the page query. Compose `AddressCountryControl` to offer the choice.
+- **The shipping countries are read once per page.** The list comes with the page; a store that changes where it ships shows the change on the next page load.
+- **The postal code has no mask.** It is a plain text field. After the shopper stops typing for 400 ms, a complete code fills the state, city, neighborhood and street the country shows (Argentina, Brazil, Canada, France, Mexico, Spain and the United States). A field the shopper typed or saved is never changed, and a select the shopper's own city depends on is left alone. A field an earlier code filled and the new code does not cover is cleared. A reply for a code or country that changed meanwhile is dropped. A code the platform does not know and a lookup that fails change nothing and say nothing. The merchant cannot turn the fill off.
+- **The fill remembers only the last code asked.** Typing the same code again after another one asks again.
+- **The form does not see another tab's change.** An open edit submits what the shopper sees; if the address was removed meanwhile, the save says it no longer exists.
+
+---
+
+## Related
+
+- [[address-summary]] — the presentational parts an entry composes; an entry renders its recipient, lines, and country through it.
+- [[shipping-address]] — the checkout form for choosing or typing an address; do not use it for the saved list.
+- [[session]] — provides the required `SessionRoot` ancestor.
+- [[toast]] — the particle the form's confirmation uses; the page needs its provider.
+- [[navigation-link]] — the particle the profile notice renders its link with.

package/dist/docs/account-entry-point.md

@@ -60,7 +60,7 @@ Content model (`account-entry-point`) fields, edited in the CMS:
 
 **One element, two links, chosen by the session.** `loggedIn` renders the signed-in link; `anonymous` and `identified` both render the signed-out one, because an identified but unauthenticated shopper cannot reach their account yet. There is no prop that selects between them — the merchant authors one element and the session decides.
 
-**The destinations are not authored.** Sign in goes to `/login`, carrying a `returnUrl` with the current path so the shopper returns where they started; the account link goes to the storefront's own `/pvt/account`. Both are fixed constants, so no schema edit and no CMS entry can misroute the auth flow. The sign-in destination comes from the shared `resolveSignInHref` (`utils/safe-href.ts`) rather than from this component, so any other surface that has to send a signed-out shopper to sign in reaches the same place by the same rule. The `returnUrl` value is constrained to a same-origin relative path, which keeps the sign-in route from being turned into an open redirect; a path the narrowing refuses drops the parameter, and so does a router reporting no path, leaving a bare `/login` rather than a broken link. That is the sender's half of the guarantee. Nothing stops a hand-crafted link, so the receiving half — narrowing the parameter through `resolveSiteRelativeHref` on arrival — belongs to the route that will serve `/login`. The signed-out link also opts out of Next.js prefetching: a header control is always in the viewport, and the destination is an auth route rather than a page, so it can set a cookie or redirect and the default would fire that request on every page view.
+**The destinations are not authored.** Sign in goes to the sign-in page `{ standard: 'sign-in' }`, carrying a `returnUrl` with the current logical path so the shopper returns where they started; the sign-in page prefixes it on the way back. The account link goes to the account page `{ standard: 'account' }`. The route map resolves both for the current binding, for example `/pt-BR/login` and `/pt-BR/pvt/account`. Both are fixed constants, so no schema edit and no CMS entry can misroute the auth flow. The sign-in destination comes from the shared `signInTarget` (`utils/safe-href.ts`) rather than from this component, so any other surface that has to send a signed-out shopper to sign in reaches the same place by the same rule. The `returnUrl` value is constrained to a same-origin relative path, which keeps the sign-in route from being turned into an open redirect; a path the narrowing refuses drops the parameter, and so does a router reporting no path, leaving a bare sign-in page rather than a broken link. That is the sender's half of the guarantee. Nothing stops a hand-crafted link, so the receiving half — narrowing the parameter through `resolveSiteRelativeHref` on arrival — belongs to the route that serves the sign-in page. The signed-out link also opts out of Next.js prefetching: a header control is always in the viewport, and the destination is an auth route rather than a page, so it can set a cookie or redirect and the default would fire that request on every page view.
 
 **`returnUrl` carries the path only — not the query string, not the hash.** A shopper signing in from `/s?q=tenis` or a filtered listing returns to the bare path. This is a deliberate narrowing rather than a limitation of the router: recovering the query would mean reading it through `useSearchParams()` and wrapping the header in a Suspense boundary, and the hash never leaves the browser at all. Search and filter state is cheap to re-apply and the sign-in round trip is rare, so the entry point keeps the simpler shape. Revisit it if merchants report losing filters across sign-in.
 

package/dist/docs/account-menu.md

@@ -35,7 +35,7 @@ AccountMenuRoot
 ├── AccountMenuList
 ├── AccountMenuSignOut   ← beside the list, outside the landmark
 └── Slot                 ← the section's own page
-    └── AccountMenuIndexRedirect   ← on /pvt/account only
+    └── 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.
@@ -57,12 +57,12 @@ 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 `/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 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. `/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.
+**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 `/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.
 
@@ -181,7 +181,7 @@ The account root's page, whose only content is the redirect:
 - **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, and says so.
-- **Placing `AccountMenuIndexRedirect` on a section's page.** It navigates away from whatever page hosts it; it belongs on `/pvt/account` alone.
+- **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.

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