@vtex/faststore 0.0.7 → 0.0.10

package/dist/core/dist/define-component.d.ts

@@ -9,7 +9,7 @@ export interface EditorMetadata {
   description?: string;
   icon?: string;
 }
-export type PropType = 'string' | 'number' | 'boolean' | 'object' | 'array' | readonly string[];
+export type PropType = 'string' | 'number' | 'boolean' | 'object' | 'array' | 'link' | readonly string[];
 export type PropSchemaField = {
   /**
    * Prop type keyword. The catalog wire value `"icon"` is a sukima convention (collected at
@@ -23,10 +23,20 @@ export type PropSchemaField = {
    */
   items?: readonly string[];
   default?: unknown;
+  /**
+   * The route params the component supplies when it navigates, honored only when `type === 'link'`
+   * (e.g. `{ type: 'link', default: { standard: 'order-placed' }, fills: ['orderGroup'] }`).
+   */
+  fills?: readonly string[];
   label?: string;
 };
 export type PropSchema = Record<string, PropSchemaField>;
-export type FetchStrategy = 'static' | 'lazy' | 'reactive' | 'reactive-list-item';
+export type FetchStrategy = 'static' | 'lazy' | 'reactive' | 'reactive-list-item' |
+/**
+ * The component's data is fetched by the client when the element mounts, in its own operation:
+ * never in the page query, and absent from the server HTML. Meant for a conditional branch.
+ */
+'lazy-on-mount';
 /**
  * How one fragment variable reads the element's configuration when the by-name convention cannot
  * express it (config-sourced fragment variables RFC). By convention `$first` reads the content-model

package/dist/docs/account-access-gate.md

@@ -21,7 +21,7 @@ The image is the source of truth for layout, and this component is not in any la
 
 - On an individual account section, to repeat the rule → the layout already made it. A second gate is a second decision to keep in agreement with the first.
 - To show or hide a subtree by session state, with nothing else riding on it → use `SessionGuard`, which is the declarative show/hide. This component navigates, remembers, and is meant to own a whole page.
-- On the `/login` route → that route is [[sign-in-redirect]], and this component redirects *to* it. Gating it closes a loop the shopper cannot leave.
+- On the sign-in page → that page is [[sign-in-redirect]], and this component redirects *to* it. Gating it closes a loop the shopper cannot leave.
 - To decide whether a shopper may read *this particular order* or *that address* → the gate answers "is anyone signed in", never "is this record theirs". Record-level authorization belongs to the resolver.
 
 ---
@@ -64,7 +64,7 @@ Content model (`account-access-gate`) fields, edited in the CMS — the same fou
 
 **`identified` counts as signed out.** A shopper the platform recognizes but has not authenticated cannot reach their account, which is the same reading [[account-entry-point]] applies to its own label.
 
-**A visitor who arrived signed out is sent, not told.** The redirect replaces the history entry rather than pushing one, carrying the page they were trying to reach as the return, query string included — so back from the platform's login reaches the page they were reading rather than the first page of it, and never bounces off the gate again.
+**A visitor who arrived signed out is sent, not told.** The redirect replaces the history entry rather than pushing one, carrying the page they were trying to reach as the return, query string included, as a logical path the sign-in page prefixes on the way back — so back from the platform's login reaches the page they were reading rather than the first page of it, and never bounces off the gate again.
 
 **A session that ended mid-visit is told, not sent.** Past a redirect there is no surface left to say anything on, so the gate keeps the page and renders the notice with a sign-in link the shopper may take. This is a deliberate departure from "redirect whenever signed out", and it applies only when the gate has already rendered the account for this shopper.
 
@@ -113,7 +113,7 @@ Bound to a CMS entry, the element authors no messages at all — the entry suppl
 
 - **`AccountGate`, `AuthGuard`, `RequireLogin`, `ProtectedRoute`.** The correct name is `AccountAccessGate`.
 - **Repeating it per account section.** It belongs once in the layout, wrapping the body. Two gates are two decisions that can disagree.
-- **Putting [[sign-in-redirect]] under it.** The gate redirects to `/login`; a gated `/login` redirects to itself.
+- **Putting [[sign-in-redirect]] under it.** The gate redirects to the sign-in page `{ standard: 'sign-in' }`; a gated sign-in page redirects to itself.
 - **Placing it outside `SessionRoot`.** It declares `requiresContext: 'session'` and has nothing to read without one.
 - **Reaching for `SessionGuard when={['loggedIn']}` instead.** That expresses one of the five outcomes. It cannot redirect, cannot carry a return, cannot tell an arrival from an expiry, and renders nothing while the session is still resolving.
 - **Expecting it to redirect an expired session.** It renders a notice on purpose — see above.
@@ -148,6 +148,6 @@ Styling the gate's swatch reaches the loading part and both notices, which is us
 
 ## Related
 
-- [[sign-in-redirect]] — the `/login` route this component sends a signed-out visitor to, and which reads back the return this one encoded. Never place it under the gate.
+- [[sign-in-redirect]] — the sign-in page this component sends a signed-out visitor to, and which reads back the return this one encoded. Never place it under the gate.
 - [[account-entry-point]] — the header control that offers sign-in to a shopper who chose to go there. It asks; this one insists.
 - [[session]] — the context both read. `SessionGuard`, in the same group, is the declarative show/hide for a subtree with no navigation, no memory, and no loading state of its own.

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.