@vtex/faststore 0.0.10 → 0.0.12

package/dist/docs/installments.md

@@ -58,7 +58,7 @@ PaymentSectionRoot (or PaymentSectionController)
 
 Either component must be a descendant of `PaymentSectionRoot` or `PaymentSectionController` — each reads the shopper's in-progress card draft (`draft.bin`) and the currently selected method from that context. Place it as a **sibling** of `CardEntry` and `SavedCards`, never nested inside either: one instance serves both the new-card and saved-card paths, matched automatically from the same context data.
 
-Both self-gate to an empty state when nothing is selected yet, and to a loading state before their data resolves — safe to include speculatively inside any payment section, but for image-to-schema work only include one when the image actually shows a selectable installment control, and pick the variant (list vs. dropdown) the image actually shows.
+Both render nothing until the shopper can act on them: for a new card, once the entry passes length, Luhn, expiration and security code (`CardEntry` publishes that verdict as a boolean; the holder name is not part of it); for a saved card, as soon as it is the selection. The new-card verdict is local state on the `payment` context (`draft.entryValid`). It comes from the same validation the blur and place-order checks run, changes only when the verdict changes, sends no request, and resets to false when `CardEntry` unmounts, so a selector does not outlive the form it describes (`card-entry.test.tsx`, `setDraftEntryValid`). Only the boolean crosses to this component; the card values stay in `CardEntry`. Once the data has resolved they also render nothing when no payment method the store offers carries a tier above 1x — a store without installments shows no selector, not a one-row group. The check is store-wide: a card whose own option is 1x-only still sees a one-row group while another method offers more. Before the data resolves, and with the entry valid, they render a loading wrapper. Past those two gates they self-gate to an empty state when nothing matches the current selection. Safe to include speculatively inside any payment section, but for image-to-schema work only include one when the image actually shows a selectable installment control, and pick the variant (list vs. dropdown) the image actually shows.
 
 Both render nothing while the card payment is collapsed — the persisted selection is a method that is not a card, or one the section does not serve, and a composed `PaymentMethodList` can bring the card form back (see [[payment]]) — and come back with it. A method's own installment options apply only when it is a card: over a persisted non-card method, card mode included, both read `empty` until a card is recorded, never that method's own tiers.
 
@@ -68,12 +68,15 @@ Both render nothing while the card payment is collapsed — the persisted select
 
 ### Installments
 
-| Prop | Type | Default | Notes |
-|------|------|---------|-------|
-| `installmentTemplate` | string | `"{count}x of {value}"` | Placeholders `{count}` / `{value}`, matching `PricingInstallment`'s convention. |
-| `interestFreeLabel` | string | `"interest-free"` | Appended when a row's interest rate is `0`. |
-| `interestTemplate` | string | `"{rate}% interest"` | Appended instead of `interestFreeLabel` when a row's interest rate is above `0`. `{rate}` is the order form's `interestRate`, which is in hundredths of a percent, divided by 100 and locale-formatted: `100` renders `1`. |
-| `legend` | string | `"Installments"` | The radio group's accessible name, rendered as a visible fieldset legend above the rows (T38). An authored empty or whitespace-only string falls back to this default rather than rendering a nameless group. |
+No copy props.
+
+**Content model** (`installments`):
+
+- `installmentTemplate`: ICU message with `count` and `value` (the currency-formatted per-installment value) arguments, matching `PricingInstallment`'s convention.
+- `interestFreeLabel`: appended when the API marks a row `interestFree`.
+- `interestTemplate`: ICU message with a `rate` argument, appended instead of `interestFreeLabel` when the API marks a row not `interestFree`. A row whose rate the order form did not state (`interestRate` and `interestFree` both `null`) gets neither: just the count and the per-installment value. `{rate}` is the order form's `interestRate`, which is in hundredths of a percent, divided by 100 and locale-formatted: `100` renders `1`.
+- `legend`: the radio group's accessible name, rendered as a visible fieldset legend above the rows (T38).
+- `invalidInstallmentMessage`, `missingMethodMessage`, `genericErrorMessage`: the inline alert for a refused pick, keyed on its code. `INVALID_INSTALLMENT_COUNT` reads the first, `MISSING_PAYMENT_METHOD_SELECTION` the second, and `MISSING_CART_CONTEXT`, `CART_NOT_FOUND` and `NETWORK_ERROR` the generic one. A code the package does not know (one a newer server added) also shows `genericErrorMessage` and logs `message.unknown-code`.
 
 **Data:** declares its own `fragment InstallmentsData on Query` (selects `Query.payment.installmentOptions` and `Query.payment.selectedInstallment` — the compiler merges it into the page query alongside `PaymentSectionRoot`'s own, smaller `payment` selection; no explicit `dataSources` entry needed). `fetchStrategy: 'reactive'` — the option list updates live from the cache, no refetch.
 
@@ -81,19 +84,20 @@ Both render nothing while the card payment is collapsed — the persisted select
 
 **The 1x option:** the component renders exactly the tiers the matched option's own data carries. The API guarantees a `count: 1` tier is present in every projected `installmentOptions` entry — passed through untouched (including its interest rate) when upstream supplies one, synthesized from the option's own `value` with no interest when it does not — so a 1x row is always shown and selectable.
 
-**Selecting a row** dispatches the installment write action; on success the order total (interest-inclusive) updates elsewhere on the page with no further action from this component. On rejection, the first error message renders inline.
+**Selecting a row** dispatches the installment write action. The mutation returns the cart, and the cart's `total` is the greater of the order form's value and the selected payment's value, so it includes the picked tier's interest; a `CartTotal` on the page reads it from the normalized cache. The rule lives in one place, `mapOrderFormToGqlCart` in the checkout module's `mappers.ts`, so every cart read and every mutation payload agrees, and the cart page shows the interest-inclusive total too. It gives the same answer whether or not upstream already folds interest into the order form's value, and it equals the value the order will be charged at. `installments-total-propagation.test.tsx` proves the path through a real Apollo cache, with an order value that differs from the tier's total. The totalizer lines do not include an interest line, so they may not add up to that total while an interest tier is selected. If the entry turns invalid after a pick, the selector disappears but the pick, and the total that includes its interest, stay until the entry is valid again. On rejection, the first error renders inline, worded from its code.
 
 ### InstallmentsSelect
 
-The collapsed sibling: same tiers, same matching, same write path, same `installmentTemplate`/`interestFreeLabel`/`interestTemplate` defaults as `Installments`, and the same formatting locale — the storefront context's, since neither component takes a `locale` prop — only the control itself differs (a Base UI Select instead of a radio group), plus two extra copy props for the closed control's own text.
+The collapsed sibling: same tiers, same matching, same write path, same `installmentTemplate`/`interestFreeLabel`/`interestTemplate` messages as `Installments`, and the same formatting locale — the storefront context's, since neither component takes a `locale` prop — only the control itself differs (a Base UI Select instead of a radio group), plus two extra messages for the closed control's own text. No copy props.
+
+**Content model** (`installments-select`):
 
-| Prop | Type | Default | Notes |
-|------|------|---------|-------|
-| `installmentTemplate` | string | `"{count}x of {value}"` | Same as `Installments`. |
-| `interestFreeLabel` | string | `"interest-free"` | Same as `Installments`. |
-| `interestTemplate` | string | `"{rate}% interest"` | Same as `Installments`: `{rate}` is the order form's hundredths-of-a-percent `interestRate` divided by 100. |
-| `label` | string | `"Installments"` | Accessible name for the control, rendered as the particle's own label element. Always renders — there is no mode that hides it; a store that already has its own heading suppresses it visually via its own `data-fs-installments-label` hook. An authored empty or whitespace-only string falls back to this default (T38) rather than rendering a nameless combobox. |
-| `placeholder` | string | `"Select an installment plan"` | Shown on the closed control when the bound count matches no tier in the currently matched option (a stale selection — see below). As of T31, every copy prop across both `Installments` and `InstallmentsSelect` defaults to en-US, while values and interest rates format in the storefront context's locale, which no prop overrides. A pt-BR store now authors every copy prop explicitly, not just these two. |
+- `installmentTemplate`, `interestFreeLabel`, `interestTemplate`: same as `Installments`.
+- `label`: accessible name for the control, rendered as the particle's own label element. Always renders — there is no mode that hides it; a store that already has its own heading suppresses it visually via its own `data-fs-installments-label` hook.
+- `placeholder`: shown on the closed control when the bound count matches no tier in the currently matched option (a stale selection — see below).
+- `invalidInstallmentMessage`, `missingMethodMessage`, `genericErrorMessage`: same as `Installments`.
+
+Every message of both components is read only from `$content`; values and interest rates format in the storefront context's locale. A missing message renders empty and logs `message.missing`.
 
 **Data:** declares its own `fragment InstallmentsSelectData on Query`, with a selection set identical to `InstallmentsData` under a distinct name (two registered components on one page must not share a fragment name). Same `fetchStrategy: 'reactive'`.
 
@@ -134,7 +138,13 @@ Collapsed dropdown — same payment section, `InstallmentsSelect` in place of `I
   },
   "installments-select": {
     "type": "InstallmentsSelect",
-    "props": { "label": "Parcelamento", "placeholder": "Selecione o parcelamento" }
+    "props": {
+      "installmentTemplate": "{count}x de {value}",
+      "interestFreeLabel": "sem juros",
+      "interestTemplate": "{rate}% de juros",
+      "label": "Parcelamento",
+      "placeholder": "Selecione o parcelamento"
+    }
   }
 }
 ```
@@ -149,7 +159,7 @@ Collapsed dropdown — same payment section, `InstallmentsSelect` in place of `I
 - **Using either component on a PDP.** A PDP's advertised plans are `Pricing`'s `PricingInstallments` / `PricingInstallmentPlans` — different data source, display-only, not reusable here.
 - **Using either component for a read-only recap.** A recap of the already-chosen installment (e.g. Order Review) is not `Installments` or `InstallmentsSelect`; both are selectors.
 - **Placing either component outside a payment section.** Both require a `PaymentSectionRoot`/`PaymentSectionController` ancestor and throw without one.
-- **Expecting a rendered order total.** Neither component ever shows a total — selecting an option updates the cart total elsewhere on the page through the normalized cache.
+- **Expecting a rendered order total.** Neither component ever shows a total — selecting an option returns the cart, whose `total` includes the tier's interest, and `CartTotal` reads it from the normalized cache.
 - **Expecting a full card number or CVV field.** Both fragments structurally select neither — only installment counts, values, and interest rates.
 - **Expecting `InstallmentsSelect`'s option list to be styleable from the page's `style` array.** Its popup is portalled to `<body>` — see [Styling](#styling).
 
@@ -165,14 +175,16 @@ Single DOM root wrapping a list of selectable rows.
 |---|---|---|
 | `Installments` (root `div`) | Stacks the option rows | `flex flex-col gap-2` |
 | Fieldset (`data-fs-installments-fieldset`, native `<fieldset>`) | Wraps the legend and the radio rows (T38) — gives the group its visible, accessible name | usually left unstyled; a merchant border/padding choice |
-| Legend (`data-fs-fieldset-legend`, native `<legend>`) | The group's visible name, from `legend` | `text-[14px] font-medium text-[#1A1A1A]` |
-| Empty state (`data-fs-installments-state="empty"`) | Neutral placeholder sizing | `min-h-12 border border-dashed border-[#CCCCCC]` |
-| Loading state (`data-fs-installments-state="loading"`) | Skeleton affordance | `min-h-12 animate-pulse bg-[#F5F5F5]` |
+| Legend (`data-fs-fieldset-legend`, native `<legend>`) | The group's visible name, from `legend` | `text-[14px] font-medium text-[var(--color-ink)]` |
+| Empty state (`data-fs-installments-state="empty"`) | Neutral placeholder sizing | `min-h-12 border border-dashed border-[color-mix(in_srgb,var(--color-ink)_20%,transparent)]` |
+| Loading state (`data-fs-installments-state="loading"`) | Skeleton affordance | `min-h-12 animate-pulse bg-[color-mix(in_srgb,var(--color-ink)_8%,transparent)]` |
 | Pending state (`data-fs-installments-state="pending"`) | Rows visible but disabled while the persisted BIN settles | `opacity-50 pointer-events-none` |
-| Inline error (`data-fs-installments-error`) | Warning-toned alert text | `text-[12px] font-medium text-[#B00020]` |
-| Option row label (`data-fs-installments-option-label`) | Row text | `text-[14px] text-[#1A1A1A]` |
+| Inline error (`data-fs-installments-error`) | Warning-toned alert text | `text-[12px] font-medium` |
+| Option row label (`data-fs-installments-option-label`) | Row text | `text-[14px] text-[var(--color-ink)]` |
 | Placing (`data-fs-installments-placing`) | Present while an order-placement sequence is in flight (T28) — distinct from the `pending` state above, which is this component's own BIN-confirmation wait; the root is also `inert` and `aria-disabled` at that point | `opacity-60 cursor-not-allowed` |
 
+A status color is a `visualIdentity` feedback role of the foundation: when the store declares them, color the error row `text-[var(--color-feedback-danger)]`, the success row `text-[var(--color-feedback-success)]` and the notice row `text-[var(--color-feedback-warning)]`, never with a hex.
+
 Styled example:
 
 ```json
@@ -194,17 +206,19 @@ Root `div` plus a Base UI Select. Only the parts that stay inside the component
 |---|---|---|---|
 | `InstallmentsSelect` (root `div`, `data-fs-installments`) | Yes | Positions the label + trigger | `flex flex-col gap-1` |
 | `data-fs-installments-control="select"` | Yes | Discriminates this surface from the radio one when a store styles both from one shared selector | — |
-| Empty / loading state (`data-fs-installments-state`) | Yes | Same neutral/skeleton treatment as `Installments` | `min-h-12 border border-dashed border-[#CCCCCC]` / `min-h-12 animate-pulse bg-[#F5F5F5]` |
+| Empty / loading state (`data-fs-installments-state`) | Yes | Same neutral/skeleton treatment as `Installments` | `min-h-12 border border-dashed border-[color-mix(in_srgb,var(--color-ink)_20%,transparent)]` / `min-h-12 animate-pulse bg-[color-mix(in_srgb,var(--color-ink)_8%,transparent)]` |
 | Pending state (`data-fs-installments-state="pending"`) | Yes | Trigger visible but disabled while the persisted BIN settles | `opacity-50 pointer-events-none` |
-| Inline error (`data-fs-installments-error`) | Yes | Warning-toned alert text | `text-[12px] font-medium text-[#B00020]` |
-| Label (`data-fs-installments-label`) | Yes | The accessible-name text above the trigger | `text-[12px] text-[#666666]`, or `sr-only` to hide it visually |
-| Trigger (`data-fs-installments-trigger`) | Yes | The closed control's own box | `flex items-center justify-between border border-[#CCCCCC] rounded px-3 py-2` |
-| Value (`data-fs-installments-value`) | Yes | The selected label / placeholder text | `text-[14px] text-[#1A1A1A]` |
-| Icon (`data-fs-installments-icon`) | Yes | The `▾` glyph | `text-[#666666]` |
+| Inline error (`data-fs-installments-error`) | Yes | Warning-toned alert text | `text-[12px] font-medium` |
+| Label (`data-fs-installments-label`) | Yes | The accessible-name text above the trigger | `text-[12px] text-[color-mix(in_srgb,var(--color-ink)_60%,transparent)]`, or `sr-only` to hide it visually |
+| Trigger (`data-fs-installments-trigger`) | Yes | The closed control's own box | `flex items-center justify-between border border-[color-mix(in_srgb,var(--color-ink)_20%,transparent)] rounded px-3 py-2` |
+| Value (`data-fs-installments-value`) | Yes | The selected label / placeholder text | `text-[14px] text-[var(--color-ink)]` |
+| Icon (`data-fs-installments-icon`) | Yes | The `▾` glyph | `text-[color-mix(in_srgb,var(--color-ink)_60%,transparent)]` |
 | Option (`data-fs-installments-option`) | **No — portalled** | One row inside the open popup | not authorable from this page's `style` array today |
 | Option label (`data-fs-installments-option-label`) | **No — portalled** | An option's text | not authorable from this page's `style` array today |
 | Placing (`data-fs-installments-placing`) | Yes | Present while an order-placement sequence is in flight (T28) — the same hook and presence attribute name `Installments` uses (both surfaces read the shared engine's own `placing`); the root is also `inert` and `aria-disabled` at that point | `opacity-60 cursor-not-allowed` |
 
+A status color is a `visualIdentity` feedback role of the foundation: when the store declares them, color the error row `text-[var(--color-feedback-danger)]`, the success row `text-[var(--color-feedback-success)]` and the notice row `text-[var(--color-feedback-warning)]`, never with a hex.
+
 Styled example (only the reachable parts):
 
 ```json
@@ -223,9 +237,9 @@ The popup's own visual defaults (spacing, hover, the selected-row treatment) com
 ## Accessibility Contract
 
 **What the platform promises:** `Installments`' radio group and `InstallmentsSelect`'s combobox each
-carry a visible, programmatic accessible name (`legend`/`label`, both defaulting to `"Installments"`) —
-a screen-reader user hears what the rows are a choice *between*. An authored empty or whitespace-only
-value on either falls back to the default rather than shipping a nameless control. Each tier keeps its
+carry a visible, programmatic accessible name (the `legend`/`label` messages) — a screen-reader user
+hears what the rows are a choice *between*. A store that leaves either message unauthored ships a
+nameless control, and the formatter logs `message.missing`. Each tier keeps its
 own accessible name/text from `installmentLabel`. `Installments`' group is a native `<fieldset>`/
 `<legend>` pair, visible to sighted and low-vision shoppers, not only `aria-label`. Keyboard:
 `Installments`' group is one Tab stop — Tab lands on the checked row, and the arrow keys move the

package/dist/docs/my-account-profile.md

@@ -23,7 +23,7 @@ Use `MyAccountProfile` (not a hand-assembled combination of ad-hoc state) whenev
 ## When NOT to use
 
 - Rendering an individual profile field's presentation or input directly on the Root — that is each field Control's job. This Root owns no field's formatting or masking; the Controls delegate that to the `Field`, `PhoneField`, `DocumentField`, `Input`, and `Select` particles.
-- The signed-out prompt — compose the existing `SignInForm` alongside a `SessionGuard` in the store topology; this Root renders nothing for that audience.
+- The signed-out prompt — compose the sign-in surface (`SignInRoot` with `SignInEmailControl` and the method components under it) inside a `SessionGuard` in the store topology; this Root renders nothing for that audience.
 - Editing the email — it is the login identifier and is read-only by construction; there is no edit-state rendering for it.
 
 ---
@@ -58,31 +58,35 @@ A field Control is absent from the composition means absent from both states and
 - **Field registration, not enumeration**: a Control calls `registerField({ key, validate?, normalize? })` in an effect on mount and unregisters on cleanup. The Root validates, batches, and focuses only over the live registry — it never names a field itself (Decision 1).
 - **Dirty is value comparison, not a touched flag**: `dirty(key) === draft[key] !== savedValues[key]`. Retyping a field back to its saved value makes Save a no-op for it, for free.
 - **Absent and empty are different instructions**: a dirty field cleared to `''` erases upstream; a field the shopper never touched is omitted from the payload entirely.
-- **Save order**: compute dirtiness first → nothing dirty raises the saved toast without dispatching → otherwise validate only the dirty registered fields' current draft values (Decision 9) → any error blocks the dispatch and focuses the first invalid field in rendered DOM order → otherwise normalize dirty values and dispatch one `$actions.identity.customerProfileUpdate` → a `userError` raises an error toast and keeps the edit state with the draft intact → success returns to the view state and raises a success toast (Decision 10). A field the shopper never touched is neither validated nor sent.
+- **Save order**: compute dirtiness first → nothing dirty raises the saved toast without dispatching → otherwise validate only the dirty registered fields' current draft values (Decision 9) → any error blocks the dispatch and focuses the first invalid field in rendered DOM order → otherwise normalize dirty values and dispatch one `$actions.identity.customerProfileUpdate` → a `userError` raises an error toast worded by its `code` and keeps the edit state with the draft intact → success returns to the view state and raises a success toast (Decision 10). A field the shopper never touched is neither validated nor sent.
 - **Edit always opens from the latest saved values**: pressing Edit re-seeds the draft from `savedValues` before switching modes, so a value the server normalized on a previous save (not this task's concern, but a sibling Control's) is what the shopper sees, not a stale local draft.
 - **Background re-delivery**: when `$data` delivers new values while editing, a field re-seeds only if its draft still equals the previously saved value; a dirty field is never clobbered.
 - **Self-gate**: renders nothing outside `state === 'loggedIn'`, even if the topology's `SessionGuard` is missing. Renders `MyAccountProfileSkeleton` while `$data` is unresolved and the shopper is logged in — never an empty summary. `customerProfile` is nullable, so `$data` is also `null` for an anonymous session (the self-gate renders nothing) and for a logged-in shopper whose read failed (the skeleton stays).
-- **PII**: no profile value appears in any log line. A write that throws (rather than resolving `userErrors`) logs only the error's name; the message shown to the shopper is the `saveFailedMessage` schema prop.
+- **PII**: no profile value appears in any log line. A write that throws (rather than resolving `userErrors`) logs only the error's name; the message shown to the shopper is the `saveFailedMessage` message.
 
 ---
 
 ## Props
 
-**`MyAccountProfile.Root`** — `documentType` (string, e.g. `'CPF'`; the store-configured fallback used when the saved `documentType` is not a registered type), `savedMessage` (string, default `'Your profile has been saved.'`; the toast title on a successful Save), `saveFailedMessage` (string, default `'Unable to save your profile. Please try again.'`; the toast title on a failed Save). Declares `actions: { identity: ['customerProfileUpdate'] }`, `requiresContext: 'session'`, `providesContext: 'my-account-profile'`, `fetchStrategy: 'reactive'`.
+Every message below is an ICU message field on the part's own content type (`my-account-profile-root`,
+`-edit`, `-save`, `-cancel`, `-first-name`, `-last-name`, `-phone`, `-tax-id`, `-birth-date`, `-gender`),
+with no package default: an unauthored one renders empty and logs `message.missing`.
 
-**`.EditButton` / `.SaveButton` / `.CancelButton`** — `label` (sensible default) or composed `children`.
+**`MyAccountProfile.Root`** — `documentType` (string, e.g. `'CPF'`; the store-configured fallback used when the saved `documentType` is not a registered type), and the messages `savedMessage` (source `Your profile has been saved.`; the toast title on a successful Save) and `saveFailedMessage` (source `Unable to save your profile. Please try again.`; the toast title on a failed Save). A refused Save's toast title is keyed on the refusal's `code`: `INVALID_VALUE` → `invalidValueMessage` (source `Some of your details were not accepted. Check them and try again.`; the account names no field), `UNAUTHORIZED` → `sessionExpiredMessage` (source `Your session has expired. Please sign in again.`), and `NETWORK_ERROR`, a write that throws or a missing action → `saveFailedMessage`. A code none of these words (one a newer server added) shows `saveFailedMessage` and logs `message.unknown-code`; a blank field raises an empty toast and logs `message.missing`. Declares `actions: { identity: ['customerProfileUpdate'] }`, `requiresContext: 'session'`, `providesContext: 'my-account-profile'`, `fetchStrategy: 'reactive'`.
+
+**`.EditButton` / `.SaveButton` / `.CancelButton`** — the `label` message (source `Edit` / `Save` / `Cancel`) or composed `children`.
 
 **`.Email` / `.Skeleton`** — no props beyond `className`.
 
-**`.FirstNameControl` / `.LastNameControl`** — `label` (default `'First name'` / `'Last name'`), `requiredMessage` (shown when Save is blocked on an empty value).
+**`.FirstNameControl` / `.LastNameControl`** — the messages `label` (source `First name` / `Last name`) and `requiredMessage` (source `First name is required.` / `Last name is required.`; shown when Save is blocked on an empty value).
 
-**`.PhoneControl`** — `field` (`'homePhone' | 'mobilePhone'`, default `'mobilePhone'`; compose the Control twice to expose both numbers), `country` (`'US' | 'BR'`, default `'US'`), `label`, `invalidMessage`.
+**`.PhoneControl`** — `field` (`'homePhone' | 'mobilePhone'`, default `'mobilePhone'`; compose the Control twice to expose both numbers), `country` (`'US' | 'BR'`, default `'US'`), and the messages `label` (source `Phone`) and `invalidMessage` (source `Invalid phone number`), which it formats and hands to `PhoneField`.
 
-**`.TaxIdControl`** — `label` (default `'National tax ID'`), `invalidMessage`, `lockedReason` (the inline copy shown beside the disabled input when a document is already saved). The control masks, validates and normalizes with the active document type: CPF, SSN, SIN or RFC. It sends `document` only (never `documentType`): digits for CPF, SSN and SIN, letters kept for RFC.
+**`.TaxIdControl`** — the messages `label` (source `National tax ID`), `invalidMessage` (source `Invalid document number.`), `lockedReason` (source `Your document ID can't be edited.`; the inline copy shown beside the disabled input when a document is already saved). The control masks, validates and normalizes with the active document type: CPF, SSN, SIN or RFC. It sends `document` only (never `documentType`): digits for CPF, SSN and SIN, letters kept for RFC.
 
-**`.BirthDateControl`** — `label` (default `'Birth date'`).
+**`.BirthDateControl`** — the `label` message (source `Birth date`).
 
-**`.GenderControl`** — `label` (default `'Gender'`), `placeholder`, `clearLabel` (default `'Clear'`; the button shown once a draft value is set, since the Select itself offers no way back to empty), `options` (`{ value, label }[]`, defaults to a sensible set: female / male / other / prefer not to say).
+**`.GenderControl`** — the messages `label` (source `Gender`), `placeholder` (source `Select`), `clearLabel` (source `Clear`; the button shown once a draft value is set, since the Select itself offers no way back to empty), `options` (`{ value, label }[]`; an authored list keeps its own labels. Unset, the control offers female / male / other / prefer not to say, labelled by the messages `femaleLabel`, `maleLabel`, `otherLabel` and `preferNotToSayLabel`, sources `Female`, `Male`, `Other`, `Prefer not to say`).
 
 ---
 
@@ -159,13 +163,14 @@ The `data-fs-my-account-profile-field="<key>"` attribute on each Control's own w
 }
 ```
 
-Add each field Control id to `profile-root`'s `children` array for the fields the store exposes. A sibling `SignInForm`, gated by a `SessionGuard` with `when: ["anonymous", "identified"]`, composes next to `profile-guard` for the signed-out audience.
+Add each field Control id to `profile-root`'s `children` array for the fields the store exposes. For the signed-out audience, a sibling `SessionGuard` with `when: ["anonymous", "identified"]` composes next to `profile-guard` and holds a `SignInRoot` with `SignInEmailControl` and the method components (`SignInForm`, the access-code family) under it, so the branch follows the account's enabled sign-in methods; a store that hosts `SignInRoot` in its shared layout needs only the guard and the method components.
 
 ---
 
 ## Common mistakes
 
 - **Rendering `MyAccountProfile.Root` outside `SessionRoot`.** `useSession()` throws; the page must host a `SessionRoot`.
+- **Composing `SignInForm` in the signed-out branch without a `SignInRoot` ancestor.** The page fails the **build**, not the render: sukima rejects it with the diagnostic code `context-constraint-violation`, because `SignInForm` `requiresContext: 'sign-in'` and nothing above it provides it. Compose `SignInRoot` (with `SignInEmailControl`) around the method components in the branch, unless the store's shared layout already hosts it.
 - **Rendering `MyAccountProfile.Root` outside a `ToastProvider`.** Save calls `useToast()` (Decision 10); without a `ToastProvider` ancestor that call throws.
 - **Expecting the email to be editable.** It is always read-only; there is no edit-state rendering for it anywhere in this compound.
 - **Composing a field Control without an unmount cleanup on its `registerField` effect.** A Control that never unregisters leaks a stale validator into the registry after it stops rendering — every shipped Control returns the unregister function from its effect; keep that pattern in a custom Control.

package/dist/docs/navigation-link.md

@@ -126,7 +126,7 @@ When you author `target: "_blank"`, write the "(opens in new tab)" cue into `chi
 
 | Component | What you style | Plausible classes |
 |---|---|---|
-| `NavigationLink` | The label — typography, color, and hover affordance | `text-[14px] leading-[1.4] font-medium text-[#1A1A1A] no-underline hover:underline` |
+| `NavigationLink` | The label — typography, color, and hover affordance | `text-[14px] leading-[1.4] font-medium text-[var(--color-text)] no-underline hover:underline` |
 
 The spacing between links belongs to the parent that groups them, not to the link. Give that parent the `flex` and `gap-[*]` classes and keep each link to typography and color.
 
@@ -142,16 +142,18 @@ Styled example of a row of links:
   "nav-sale": {
     "type": "NavigationLink",
     "props": { "href": "/collection/sale", "children": "Sale" },
-    "style": ["text-[14px]", "leading-[1.4]", "font-medium", "text-[#1A1A1A]", "no-underline", "hover:underline"]
+    "style": ["text-[14px]", "leading-[1.4]", "font-medium", "text-[var(--color-text)]", "no-underline", "hover:underline"]
   },
   "nav-new": {
     "type": "NavigationLink",
     "props": { "href": "/collection/new-in", "children": "New in" },
-    "style": ["text-[14px]", "leading-[1.4]", "font-medium", "text-[#1A1A1A]", "no-underline", "hover:underline"]
+    "style": ["text-[14px]", "leading-[1.4]", "font-medium", "text-[var(--color-text)]", "no-underline", "hover:underline"]
   }
 }
 ```
 
+The colors that several elements share are variables of the page or layout `theme`, which declares them: `{"--color-text": "#1A1A1A"}`. A color used once stays a hex.
+
 ---
 
 ## Related

package/dist/docs/order-cancel.md

@@ -36,7 +36,9 @@ The dialog, the reason list, and the acknowledgement are inside this matter.
 
 ### OrderCancel
 
-No authoring props. The page query passes the order. Reasons and sentences come from the `order-cancel` content model.
+No authoring props. The page query passes the order. Reasons and sentences come from the `order-cancel` content model. Its sentences are ICU messages; a missing one renders empty and logs. Without authored `reasons`, the dialog offers `reasonChangedMind`, `reasonBoughtByMistake`, `reasonBetterPrice`, and `reasonSlowDelivery`, in that order. Authored `reasons` replace them, and their labels stay plain text.
+
+A refused cancellation is worded from content by its code: `ORDER_NOT_CANCELLABLE` shows `notCancellableMessage`, `NOT_FOUND` shows `notFoundMessage`, and a transport failure (`NETWORK_ERROR`) shows `failure`. A code this component does not know, one a newer server added, also shows `failure` and logs `message.unknown-code`.
 
 ## Styling
 

package/dist/docs/order-delivery-address.md

@@ -38,12 +38,14 @@ OrderDeliveryGroup
 
 ### OrderDeliveryAddress
 
-| Prop | Type | Default | Description |
-|---|---|---|---|
-| deliveryLabel | string | catalogue `fs/order-delivery-address.delivery` | Caption above a delivery address |
-| storeLabel | string | catalogue `fs/order-delivery-address.store` | Caption above a pickup store address |
+No schema props. The captions are ICU messages in content (`order-delivery-address`):
 
-Content model `order-delivery-address` with `deliveryLabel` and `storeLabel`. Content wins over the prop, and the prop wins over the catalogue. A blank value falls through.
+| Content field | Description |
+|---|---|
+| deliveryLabel | Caption above a delivery address |
+| storeLabel | Caption above a pickup store address |
+
+A missing message renders empty and logs.
 
 ## Data
 

package/dist/docs/order-delivery-group.md

@@ -41,9 +41,7 @@ The group order is the order of `deliveryOptions`.
 
 ### OrderDeliveryGroup
 
-| Prop | Type | Default | Description |
-|---|---|---|---|
-| label | string | content, then catalogue `fs/order-delivery-group.label` | Accessible name of the section. The other fixed labels are content too (`order-delivery-group`). Item counts keep `{count}`. |
+No schema props. The accessible name of the section (`label`) and the other fixed labels are ICU messages in content (`order-delivery-group`). The item count `items` takes a `count` argument (`{count, plural, one {# item} other {# items}}`). A missing message renders empty and logs.
 
 The initial open state is not a prop. One option opens; two or more start closed.
 

package/dist/docs/order-details-back.md

@@ -34,7 +34,7 @@ OrderDetailsBack
 
 | Prop | Type | Default | Purpose |
 |---|---|---|---|
-| — | — | — | No schema props. The label is content (`order-details-back`); a blank field keeps `fs/order.back-to-orders`. The href is `/pvt/orders`. |
+| — | — | — | No schema props. The label is an ICU message in content (`order-details-back.label`); a missing one renders empty and logs. The href is `/pvt/orders`. |
 
 ## Styling hooks
 

package/dist/docs/order-details-header.md

@@ -37,11 +37,8 @@ OrderDetailsHeader
 | Prop | Type | Default | Purpose |
 |---|---|---|---|
 | `$data` | `{ id, completion } \| null` | — | The `customerOrder` the generator passes. Null renders nothing. |
-| `prefix` | string | `Order #` | Copy before the number. Content wins. An empty string, with no content, omits the prefix. |
-| `copyLabel` | string | `Copy` | Visible label of the copy action. Content wins. |
-| `copyAccessibleName` | string | `Copy order number` | Accessible name of the copy action. Content wins. |
 
-Content id `order-details-header` also carries the copy acknowledgement (`copyCopied`, `copyFailure`, `copyDismiss`) and one field per status sentence (`statusInProgress`, `statusCancellationRequested`, `statusCancelled`, `statusDelivered`, `statusShipped`, `statusReadyForPickup`, `statusCollected`, `statusPlaceholder`). A blank field keeps the catalogue. The list page does not read this entry.
+No schema props. Content id `order-details-header` carries the copy before the number (`prefix`), the copy action (`copyLabel`, `copyAccessibleName`), its acknowledgement (`copyCopied`, `copyFailure`, `copyDismiss`), and one field per status sentence (`statusInProgress`, `statusCancellationRequested`, `statusCancelled`, `statusDelivered`, `statusShipped`, `statusReadyForPickup`, `statusCollected`, `statusPlaceholder`). Every field is an ICU message. The header formats them and passes them to `CopyText` and `OrderStatusBadge`. A missing message renders empty and logs; a missing `prefix` also omits the prefix element. The list page does not read this entry.
 
 ## Styling hooks
 

package/dist/docs/order-invoice-download.md

@@ -0,0 +1,60 @@
+# OrderInvoiceDownload
+
+**Category:** action
+**Purpose:** Offers every invoice file the order kept, so the shopper can download them.
+
+---
+
+## Visual cues (how to identify in an image)
+
+- A "Download invoice" button on the order page, usually beside the cancel action.
+- With several files, the button opens a dialog with a short sentence and one entry per invoice ("Invoice 1 of 2").
+- No status, no money, no product.
+
+The image is the source of truth for layout.
+
+## When to use
+
+- On the order details page, for an order the merchant has invoiced.
+
+## When NOT to use
+
+- For a printable bank slip → `OrderPayment` owns that action.
+- For the order list → each row has no invoice control.
+
+---
+
+## Composition
+
+Standalone. Place it anywhere under the order details page. It does not choose its place.
+
+```text
+OrderInvoiceDownload
+```
+
+The dialog and the invoice list are inside this matter. The dialog portals into this root so its styling hooks stay reachable.
+
+## Data
+
+Fragment on `Query`: `customerOrder(id: $orderId) { progress { cancelled } invoices { url issuedAt kind } }`. The generator binds `$data` to that root field.
+
+- One file navigates to the merchant address. No dialog opens.
+- Several files open a dialog. The list stays mounted until the browser leaves the page, so it stays open only when the merchant serves the file as an attachment.
+- An address the browser would execute (`javascript:`) is dropped before the one-or-many choice.
+- The component renders nothing when the order is cancelled or no file remains.
+
+## Components
+
+### OrderInvoiceDownload
+
+No schema props. Every label is an ICU message in the `order-invoice-download` content model: `downloadLabel`, `entryLabel` (arguments `n` and `total`), `description`, and `closeLabel`. A missing one renders empty and logs.
+
+## Styling
+
+- `data-fs-order-invoice-download` — the root.
+- `data-fs-order-invoice-download-control` — the button that downloads, or opens the dialog.
+- `data-fs-dialog-backdrop`, `data-fs-dialog-viewport`, `data-fs-dialog-popup`, `data-fs-dialog-title`, `data-fs-dialog-description` — the overlay.
+- `data-fs-order-invoice-download-header` — the title and close row. `data-fs-order-invoice-download-dismiss` is the close mark.
+- `data-fs-order-invoice-download-list` — the invoice list.
+- `data-fs-order-invoice-download-entry` — one invoice button.
+- `data-fs-order-invoice-download-skeleton` — the loading placeholder.

package/dist/docs/order-list-row.md

@@ -35,7 +35,7 @@ OrderList
 
 ### OrderListRow
 
-No props. The list passes the order.
+No schema props. The list passes the order and `statusMessages`, the status sentences it formats from its own `status*` messages. The row has no content of its own.
 
 ## Styling
 

package/dist/docs/order-list-search.md

@@ -38,25 +38,18 @@ OrderListSearch
 
 ### OrderListSearch
 
-| Prop | Type | Default | Notes |
-|------|------|---------|-------|
-| `label` | string | `Order number` | Visible label of the text field. |
-| `fromLabel` | string | `Placed from` | Visible label of the from day. |
-| `toLabel` | string | `Placed to` | Visible label of the to day. |
-| `submitLabel` | string | `Search` | Submit button. |
-| `clearLabel` | string | `Clear search` | Clear link. Rendered only when the URL already has a criterion. |
-| `invalidRangeMessage` | string | `The start date is after the end date.` | Shown when the from day is after the to day. |
+No props of its own.
 
-Content model (`order-list-search`) fields, edited in the CMS. A non-blank field wins over the matching prop. A blank field falls through to the prop, then to the default. A blank field does not remove a control.
+Content model (`order-list-search`) fields, all ICU messages. A store without CMS authors them on the element; a CMS-bound store keeps them in content. An unauthored field renders empty and logs `message.missing`; it does not remove a control.
 
 | Field | Type | Required | Notes |
 |-------|------|----------|-------|
-| `label` | string | no | Maps to `label`. |
-| `from` | string | no | Maps to `fromLabel`. |
-| `to` | string | no | Maps to `toLabel`. |
-| `submit` | string | no | Maps to `submitLabel`. |
-| `clear` | string | no | Maps to `clearLabel`. |
-| `invalidRange` | string | no | Maps to `invalidRangeMessage`. |
+| `label` | string | no | Visible label of the text field. Source: `Order number`. |
+| `from` | string | no | Visible label of the from day. Source: `Placed from`. |
+| `to` | string | no | Visible label of the to day. Source: `Placed to`. |
+| `submit` | string | no | Submit button. Source: `Search`. |
+| `clear` | string | no | Clear link, rendered only when the URL already has a criterion. Source: `Clear search`. |
+| `invalidRange` | string | no | Shown when the from day is after the to day. Source: `The start date is after the end date.` |
 
 **The param keys are fixed.** The term is `search`. The days are `placedFrom` and `placedTo`, as RFC 3339 UTC instants of the local start and the local end of the picked days. Renaming a label does not change the keys. Submit and clear delete `after` and keep `view`.
 
@@ -74,11 +67,11 @@ Content model (`order-list-search`) fields, edited in the CMS. A non-blank field
     "type": "OrderListSearch",
     "props": {
       "label": "Order number",
-      "fromLabel": "Placed from",
-      "toLabel": "Placed to",
-      "submitLabel": "Search",
-      "clearLabel": "Clear search",
-      "invalidRangeMessage": "The start date is after the end date."
+      "from": "Placed from",
+      "to": "Placed to",
+      "submit": "Search",
+      "clear": "Clear search",
+      "invalidRange": "The start date is after the end date."
     },
     "children": [],
     "style": ["flex flex-wrap items-end gap-[12px]"]

package/dist/docs/order-list-views.md

@@ -38,23 +38,17 @@ OrderListViews
 
 ### OrderListViews
 
-| Prop | Type | Default | Notes |
-|------|------|---------|-------|
-| `label` | string | `Order views` | Accessible name of the navigation landmark. |
-| `allLabel` | string | `All orders` | Visible name of the all-orders choice. |
-| `ongoingLabel` | string | `Ongoing` | Visible name of the ongoing choice. |
-| `completedLabel` | string | `Completed` | Visible name of the completed choice. |
-| `cancelledLabel` | string | `Cancelled` | Visible name of the cancelled choice. |
+No props of its own.
 
-Content model (`order-list-views`) fields, edited in the CMS. A non-blank field wins over the matching prop. A blank field falls through to the prop, then to the default. A blank field does not remove a choice.
+Content model (`order-list-views`) fields, all ICU messages. A store without CMS authors them on the element; a CMS-bound store keeps them in content. An unauthored field renders empty and logs `message.missing`; it does not remove a choice.
 
 | Field | Type | Required | Notes |
 |-------|------|----------|-------|
-| `label` | string | no | Accessible name. Maps to `label`. |
-| `all` | string | no | Maps to `allLabel`. |
-| `ongoing` | string | no | Maps to `ongoingLabel`. |
-| `completed` | string | no | Maps to `completedLabel`. |
-| `cancelled` | string | no | Maps to `cancelledLabel`. |
+| `label` | string | no | Accessible name of the navigation landmark. Source: `Order views`. |
+| `all` | string | no | Name of the all-orders choice. Source: `All orders`. |
+| `ongoing` | string | no | Name of the ongoing choice. Source: `Ongoing`. |
+| `completed` | string | no | Name of the completed choice. Source: `Completed`. |
+| `cancelled` | string | no | Name of the cancelled choice. Source: `Cancelled`. |
 
 **The href values are fixed.** All orders omits `view`. The other three set `view` to `ongoing`, `completed`, or `cancelled`. Renaming a label does not change the param. The switch also deletes `after` and keeps every other search param, including `search`, `placedFrom`, and `placedTo`.
 
@@ -72,10 +66,10 @@ Content model (`order-list-views`) fields, edited in the CMS. A non-blank field
     "type": "OrderListViews",
     "props": {
       "label": "Order views",
-      "allLabel": "All orders",
-      "ongoingLabel": "Ongoing",
-      "completedLabel": "Completed",
-      "cancelledLabel": "Cancelled"
+      "all": "All orders",
+      "ongoing": "Ongoing",
+      "completed": "Completed",
+      "cancelled": "Cancelled"
     },
     "children": [],
     "style": ["flex flex-wrap gap-[8px]"]

package/dist/docs/order-list.md

@@ -43,16 +43,17 @@ Child order is not applicable. The row order is the order of the connection.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
-| label | string | `Orders` | Accessible name of the region |
 | advance | `pages` \| `load-more` | `pages` | Label of the control that asks for the next cursor. Both modes load the page again |
 | startShoppingHref | link | `{ standard: 'home' }` | Link offered when the account has no orders. An unsafe string falls back to the home page |
 | orderHref | link | `{ standard: 'order' }` | The order page each row links to. The row fills `orderId`, so the store's order page must take `[orderId]`; a string is the path the orders live under, and the row appends the encoded id |
 
 Page size is not a prop. The fragment always reads 25.
 
+Content model `order-list` declares every sentence as an ICU message: the region's accessible name (`label`), the empty, error and advance sentences and their links (`emptyAccount`, `emptyView`, `emptySearch`, `pastEnd`, `walkStopped`, `error`, `retry`, `next`, `loadMore`, `firstPage`, `clear`, `startShopping`), the count sentences (`count`, `countIncomplete`, with `count` and `total`), the column headers (`columnId`, `columnPlaced`, `columnTotal`, `columnItems`, `columnStatus`, `columnEstimate`) and the row status labels (`statusInProgress`, `statusCancellationRequested`, `statusCancelled`, `statusDelivered`, `statusShipped`, `statusReadyForPickup`, `statusCollected`, `statusPlaceholder`) as ICU messages. The list formats them once and passes the headers to its column row and the status sentences to each `OrderListRow`. A missing message renders empty and logs; only `count` and `countIncomplete` still fall back to their English source. A store without CMS authors the messages on the element.
+
 ### OrderListRow
 
-No schema props. The list passes one order. Do not place this component in a page schema.
+No schema props. The list passes one order and its formatted status sentences. Do not place this component in a page schema.
 
 ## Data
 
@@ -70,10 +71,12 @@ Style the region, the count, each fact, and the links through their hooks. Inlin
 - `data-fs-order-list-row-state` — `ongoing`, `completed`, or `cancelled`.
 - `data-fs-order-list-row-id` — the order number. `text-[16px] font-medium text-[#111827]`.
 - `data-fs-order-list-row-placed`, `data-fs-order-list-row-total`, `data-fs-order-list-row-count` — the facts. `text-[14px] text-[#374151]`.
-- `data-fs-order-list-row-estimate` — the delivery estimate on an ongoing row. `text-[14px] text-[#1D4ED8]`.
+- `data-fs-order-list-row-estimate` — the delivery estimate on an ongoing row. `text-[14px] text-[var(--color-blue)]`.
 - `data-fs-order-list-empty` — `account`, `view`, `search`, `past-end`, or `walk-stopped`.
 - `data-fs-order-list-error` — the failed read.
-- `data-fs-order-list-next`, `data-fs-order-list-first`, `data-fs-order-list-clear`, `data-fs-order-list-retry`, `data-fs-order-list-start` — the links. `text-[14px] font-medium text-[#1D4ED8]`.
+- `data-fs-order-list-next`, `data-fs-order-list-first`, `data-fs-order-list-clear`, `data-fs-order-list-retry`, `data-fs-order-list-start` — the links. `text-[14px] font-medium text-[var(--color-blue)]`.
+
+The colors that several elements share are variables of the page or layout `theme`, which declares them: `{"--color-blue": "#1D4ED8"}`. A color used once stays a hex.
 
 ## Canonical schema
 
@@ -82,8 +85,12 @@ Style the region, the count, each fact, and the links through their hooks. Inlin
   "orders": {
     "type": "OrderList",
     "props": {
+      "advance": "pages",
       "label": "Orders",
-      "advance": "pages"
+      "emptyAccount": "You have no orders yet",
+      "error": "Could not load orders",
+      "retry": "Try again",
+      "next": "Next page"
     },
     "style": {
       "default": "flex flex-col gap-[16px]"