@vtex/faststore 0.0.10 → 0.0.11

package/dist/docs/client-preferences.md

@@ -61,8 +61,17 @@ The bound newsletter checkbox (`optinNewsLetter`). Inlines `Field` + `Checkbox`
 | Prop | Type | Default | Notes |
 |------|------|---------|-------|
 | `label` | string | — | The text shown beside the checkbox. |
+| `$content` | `ContentValue<typeof NewsletterOptInControlContent>` | — | The inline message for a refused save. |
 | `$actions` | injected | — | Carries `identity.clientPreferencesUpdate` (compiler-injected). |
 
+Content type `newsletter-opt-in-control`, keyed on the refusal's `code`:
+
+| Content field | Codes | Source (en) |
+|---|---|---|
+| genericErrorMessage | `NETWORK_ERROR`, `MISSING_CART_CONTEXT`, `CART_NOT_FOUND`, `NO_PREFERENCE_PROVIDED` | Unable to save your preference. Please try again. |
+
+None of these is something the shopper can fix by toggling again. A code the map does not know (one a newer server added) shows `genericErrorMessage` and logs `message.unknown-code`; a blank field renders an empty error and logs `message.missing`.
+
 **Write:** declares `actions: { identity: ['clientPreferencesUpdate'] }`. The write is pessimistic/async — while in flight the checkbox is disabled and the Control carries `data-fs-newsletter-opt-in-pending`. Server `userErrors` surface inline under this checkbox only.
 
 ### SavePersonalDataOptInControl
@@ -72,9 +81,12 @@ The bound save-personal-data checkbox (`savePersonalData`). Same shape as `Newsl
 | Prop | Type | Default | Notes |
 |------|------|---------|-------|
 | `label` | string | — | The text shown beside the checkbox. |
+| `$content` | `ContentValue<typeof SavePersonalDataOptInControlContent>` | — | The inline message for a refused save. |
 | `$actions` | injected | — | Carries `identity.clientPreferencesUpdate` (compiler-injected). |
 
-Both Controls share one internal `OptInControl` implementation; each registered Control only fixes its `fieldKey` and `data-fs-*` attributes.
+Content type `save-personal-data-opt-in-control` has the same `genericErrorMessage` field, for the same codes.
+
+Both Controls share one internal `OptInControl` implementation; each registered Control only fixes its `fieldKey`, its `data-fs-*` attributes and its content type.
 
 ---
 
@@ -83,7 +95,7 @@ Both Controls share one internal `OptInControl` implementation; each registered
 - **Pre-fill:** each checkbox reflects its `clientPreferences` value; a `null` (shopper has not chosen) reads as unchecked.
 - **Toggle → persist:** dispatches `$actions.identity.clientPreferencesUpdate` with **only** the toggled field; the other flag is left untouched.
 - **In flight:** the toggled checkbox is disabled and its Control carries its `*-pending` attribute; the other Control is unaffected (per-field pending).
-- **Server `userErrors`:** surfaced inline under the Control that produced them (per-field error).
+- **Server `userErrors`:** surfaced inline under the Control that produced them (per-field error), worded by that Control's `genericErrorMessage`.
 - **Read-only session:** when `useSession()` reports `canEditData: false` (identified but unauthenticated claimed profile — VTEX refuses the write server-side), both checkboxes render disabled and each Control carries its `*-readonly` attribute (`data-fs-newsletter-opt-in-readonly`, `data-fs-save-personal-data-opt-in-readonly`), mirroring `EmailIdentificationControl`.
 
 ---
@@ -102,11 +114,17 @@ Both Controls share one internal `OptInControl` implementation; each registered
   },
   "newsletter-opt-in": {
     "type": "NewsletterOptInControl",
-    "props": { "label": "Quero receber novidades e ofertas por e-mail" }
+    "props": {
+      "label": "Quero receber novidades e ofertas por e-mail",
+      "genericErrorMessage": "Não foi possível salvar sua preferência. Tente novamente."
+    }
   },
   "save-data-opt-in": {
     "type": "SavePersonalDataOptInControl",
-    "props": { "label": "Salvar minhas informações para a próxima compra" }
+    "props": {
+      "label": "Salvar minhas informações para a próxima compra",
+      "genericErrorMessage": "Não foi possível salvar sua preferência. Tente novamente."
+    }
   }
 }
 ```
@@ -125,7 +143,10 @@ Both Controls share one internal `OptInControl` implementation; each registered
   },
   "newsletter-opt-in": {
     "type": "NewsletterOptInControl",
-    "props": { "label": "Sign me up for the newsletter" }
+    "props": {
+      "label": "Sign me up for the newsletter",
+      "genericErrorMessage": "Unable to save your preference. Please try again."
+    }
   }
 }
 ```
@@ -150,7 +171,7 @@ Both Controls share one internal `OptInControl` implementation; each registered
 | Component | What you style | Plausible classes |
 |---|---|---|
 | `ClientPreferencesRoot` | Stacks the opt-in rows | `flex flex-col gap-[8px]` |
-| `NewsletterOptInControl` / `SavePersonalDataOptInControl` | The checkbox + label row | `flex items-center gap-[8px] text-[14px] text-[#333333]` |
+| `NewsletterOptInControl` / `SavePersonalDataOptInControl` | The checkbox + label row | `flex items-center gap-[8px] text-[14px] text-[var(--color-text)]` |
 
 Styled example:
 
@@ -164,16 +185,18 @@ Styled example:
   "newsletter-opt-in": {
     "type": "NewsletterOptInControl",
     "props": { "label": "Quero receber novidades e ofertas por e-mail" },
-    "style": ["flex", "items-center", "gap-[8px]", "text-[14px]", "text-[#333333]"]
+    "style": ["flex", "items-center", "gap-[8px]", "text-[14px]", "text-[var(--color-text)]"]
   },
   "save-data-opt-in": {
     "type": "SavePersonalDataOptInControl",
     "props": { "label": "Salvar minhas informações para a próxima compra" },
-    "style": ["flex", "items-center", "gap-[8px]", "text-[14px]", "text-[#333333]"]
+    "style": ["flex", "items-center", "gap-[8px]", "text-[14px]", "text-[var(--color-text)]"]
   }
 }
 ```
 
+The colors that several elements share are variables of the page or layout `theme`, which declares them: `{"--color-text": "#333333"}`. A color used once stays a hex.
+
 ---
 
 ## Related

package/dist/docs/client-profile-fieldset.md

@@ -67,8 +67,15 @@ SessionRoot                              (required ancestor; session tri-state +
 | `country` | `'US' \| 'BR'` | `'US'` | Phone mask/validation country, provided to the phone control via context. |
 | `documentType` | string | — | One of `'CPF'`, `'SSN'`, `'SIN'` or `'RFC'` (upper case). The document control renders only when supported, and the payload carries `document` only for a supported type. |
 | `skeletonCount` | number | `4` | Placeholder rows drawn while the profile resolves. Set it to the number of controls composed. |
-| `loadingLabel` | string | `'Loading your details'` | Announced politely while the profile resolves. Blank means no announcement. |
-| `loadedLabel` | string | `'Your details are ready'` | Announced politely once the controls mount. Blank means no announcement. |
+
+Content model (`client-profile-fieldset`), ICU message fields with no package default; an unauthored one renders empty and logs `message.missing`:
+
+| Field | Source (English) | Notes |
+|-------|------------------|-------|
+| `loadingLabel` | `Loading your details` | Announced politely while the profile resolves. |
+| `loadedLabel` | `Your details are ready` | Announced politely once the controls mount. |
+| `groupLabel` | `Your details` | Accessible name of the `<fieldset>` group; unauthored, no `aria-label` is emitted. |
+| `genericErrorMessage` | `Unable to save your details. Please try again.` | Shown by `FormError` for every refusal of the write (`MISSING_CART_CONTEXT`, `CART_NOT_FOUND`, `NO_PROFILE_FIELD_PROVIDED`) and for a network failure; none is one the shopper can fix. A code this fieldset does not know shows it too and logs `message.unknown-code`. |
 
 Declares `requiresContext: ['form', 'session']` (needs both a `FormRoot` and a `SessionRoot` ancestor), `providesContext: 'client-profile-fieldset'`, `actions: { identity: ['clientProfileUpdate'] }`, and its own fragment on `Query.clientProfile`. Renders `Fieldset.Root` with `disabled={readOnly}`; carries `-pending` until its entity resolves, and `-readonly` when the session reports `canEditData: false`.
 
@@ -82,19 +89,26 @@ The definition also declares that same component as its `skeleton`, which is the
 
 | Prop | Type | Default | Notes |
 |------|------|---------|-------|
-| `label` | string | `'First name'` / `'Last name'` | |
 | `placeholder` | string | — | |
 
+Content models `client-profile-first-name` / `client-profile-last-name`, one ICU message field each with no package default: `label` (source `First name` / `Last name`).
+
 Childless, renders `Field.Root > Field.Label + Field.Control + Field.Error`. Composed children replace that default anatomy and still bind to the same field.
 
 ### ClientProfileFieldsetPhoneControl
 
 | Prop | Type | Default | Notes |
 |------|------|---------|-------|
-| `label` | string | `'Phone'` | |
+| `placeholder` | string | — | |
 | `requirement` | `'mandatory' \| 'optional'` | — | Requiredness only — the only source of it for this control, since the fieldset publishes no baseline. Unset raises nothing, so the phone is optional. A field the store does not want is omitted from the page, not switched off by a prop value. |
-| `errorInvalid` | string | `'Invalid phone number'` | |
-| `errorRequired` | string | `'Phone number is required'` | |
+
+Content model (`client-profile-fieldset-phone`), ICU message fields with no package default. The control formats them and hands the strings to `PhoneField`:
+
+| Field | Source (English) |
+|-------|------------------|
+| `label` | `Phone` |
+| `errorInvalid` | `Invalid phone number` |
+| `errorRequired` | `Phone number is required` |
 
 Composes the `PhoneField` particle. Recomposable (RFC:503): given children, they replace `PhoneField`'s
 default `Field.Label` + `PhoneFieldInput` + `Field.Error` anatomy, in any order; childless keeps today's

package/dist/docs/client-profile.md

@@ -56,13 +56,19 @@ Binds the reusable `PhoneField` particle to the profile. Reads the saved phone f
 
 | Prop | Type | Default | Notes |
 |------|------|---------|-------|
-| `label` | string | `'Phone'` | Visible field label. |
 | `country` | `'US' \| 'BR'` | `'US'` | Selects the phone mask and validation rule. |
 | `requirement` | `'mandatory' \| 'optional'` | `'mandatory'` | Controls required validation. A field the store does not want is omitted from the page rather than hidden by a prop. |
-| `errorInvalid` | string | `'Invalid phone number'` | Inline error for an invalid format. |
-| `errorRequired` | string | `'Phone number is required'` | Inline error when a mandatory field is empty. |
 | `$actions` | injected | — | Carries `identity.clientProfileUpdate` (compiler-injected). |
 
+Content model (`client-profile-phone-control`), ICU message fields with no package default. The control formats them and hands the strings to `PhoneField`:
+
+| Field | Source (English) | Notes |
+|-------|------------------|-------|
+| `label` | `Phone` | Visible field label. |
+| `errorInvalid` | `Invalid phone number` | Inline error for an invalid format. |
+| `errorRequired` | `Phone number is required` | Inline error when a mandatory field is empty. |
+| `genericErrorMessage` | `Unable to save your details. Please try again.` | Inline error for a refused save: `NETWORK_ERROR`, `MISSING_CART_CONTEXT`, `CART_NOT_FOUND` and `NO_PROFILE_FIELD_PROVIDED`, none of which the shopper can fix by editing the phone. A code it does not know (one a newer server added) shows it too and logs `message.unknown-code`. |
+
 **Write:** declares `actions: { identity: ['clientProfileUpdate'] }`. No write when the value is unchanged, empty-and-mandatory, or client-side invalid.
 
 ---
@@ -80,6 +86,9 @@ Binds the reusable `PhoneField` particle to the profile. Reads the saved phone f
           "type": "ClientProfilePhoneControl",
           "props": {
             "label": "Phone",
+            "errorInvalid": "Invalid phone number",
+            "errorRequired": "Phone number is required",
+            "genericErrorMessage": "Unable to save your details. Please try again.",
             "country": "US",
             "requirement": "mandatory"
           }

package/dist/docs/copy-text.md

@@ -26,18 +26,20 @@ Any screen that needs one action to copy a single string, such as an order numbe
 CopyText
 ```
 
-`CopyText` is one element. The caller passes the visible label or icon as `children`.
+`CopyText` is one element. The caller passes the visible label or icon as `children`. It has no content of its own: the component that owns the copy formats it and passes it as props. The order details header passes its `copyAccessibleName`, `copyCopied`, `copyFailure` and `copyDismiss` message fields.
 
 ## Components
 
 ### CopyText
 
-| Prop | Type | Default | Purpose |
-|---|---|---|---|
-| `accessibleName` | string | `Copy` | Accessible name of the action |
-| `successMessage` | string | `Copied` | Announced after a successful copy |
-| `failureMessage` | string | `Could not copy` | Announced when the clipboard rejects the write |
-| `dismissLabel` | string | `Dismiss` | Accessible name of the dismiss control |
+| Prop | Type | Purpose |
+|---|---|---|
+| `accessibleName` | string | Accessible name of the action |
+| `successMessage` | string | Announced after a successful copy |
+| `failureMessage` | string | Announced when the clipboard rejects the write |
+| `dismissLabel` | string | Accessible name of the dismiss control |
+
+None has a default. An omitted prop renders nothing: there is no fallback copy, so the owner formats and passes every one.
 
 `text` is required and is not a schema prop. The caller supplies the exact string to copy. `children` is the visible label or icon, and it is not a schema prop either.
 

package/dist/docs/document-field.md

@@ -141,7 +141,7 @@ The label is associated with the input and the error is linked via `aria-describ
 - **Blocking input during masking.** The mask is applied progressively and never rejects a keystroke.
 - **Treating an empty value as invalid.** The document is optional — blank is valid.
 - **Wiring GraphQL into this particle.** It is data-agnostic; the host form owns the profile read/write.
-- **Localizing via a message id.** There is no `react-intl`; pass `label` / `placeholder` / `errorMessage` as strings.
+- **Localizing via a message id.** Labels are plain strings; pass `label` / `placeholder` / `errorMessage` directly.
 
 ---
 

package/dist/docs/email-field.md

@@ -55,6 +55,7 @@ EmailField                 (data-fs-email-field + inherited data-fs-field-root)
 | `disabled` | boolean | `false` | Disables the input (e.g. while a write is in flight). |
 | `required` | boolean | `true` | Email is Always Mandatory at the identity step. |
 | `name` | string | `'email'` | Field/input name. |
+| `autoComplete` | string | — | The input's `autocomplete` token. Omitted, the attribute is not rendered. Set `"username"` when the field is the identifier half of a credential pair, so a password manager saves and fills it with its password. |
 
 **Validation:** format is checked on blur/submit only — never per keystroke. A prior format error clears while the shopper edits and is re-evaluated on the next blur.
 
@@ -83,7 +84,7 @@ The label is associated with the input and the error is linked via `aria-describ
 
 - **Validating on every keystroke.** Format validation runs on blur/submit only.
 - **Wiring GraphQL into this particle.** It is data-agnostic; use `EmailIdentificationControl` for the checkout-bound binding.
-- **Localizing via a message id.** There is no `react-intl`; pass `label` / `placeholder` / `errorMessage` as strings.
+- **Localizing via a message id.** Labels are plain strings; pass `label` / `placeholder` / `errorMessage` directly.
 
 ---
 

package/dist/docs/email-identification.md

@@ -46,9 +46,18 @@ SessionRoot                          (provides the session tri-state; required a
 | `label` | string | — | Passed to `EmailField`. |
 | `placeholder` | string | — | Passed to `EmailField`. |
 | `invalidEmailMessage` | string | — | Inline error text for an invalid email format. |
+| `$content` | `ContentValue<typeof EmailIdentificationControlContent>` | — | The inline message for a refused save. |
 | `$data` | `{ email?: string \| null } \| null` | injected | `clientProfile` slice from the reactive runtime. Not authored in schema. |
 | `$actions` | injected | — | Carries `identity.clientProfileUpdate` (compiler-injected). |
 
+Content type `email-identification-control`, keyed on the refusal's `code`:
+
+| Content field | Codes | Source (en) |
+|---|---|---|
+| genericErrorMessage | `NETWORK_ERROR`, `MISSING_CART_CONTEXT`, `CART_NOT_FOUND`, `NO_PROFILE_FIELD_PROVIDED` | Unable to save your details. Please try again. |
+
+None of these is something the shopper can fix by editing the email. A code the map does not know (one a newer server added) shows `genericErrorMessage` and logs `message.unknown-code`; a blank field renders an empty error and logs `message.missing`.
+
 **Data:** declares a colocated `fragment EmailIdentificationData on Query { clientProfile { email } }` with `fetchStrategy: 'reactive'`. The compiler merges it into the page query — no explicit `dataSources` entry needed.
 
 **Write:** declares `actions: { identity: ['clientProfileUpdate'] }`. The write is **pessimistic/async** — it awaits the persisted result. While in flight the field is disabled and the root carries `data-fs-email-identification-pending`, so a `CartCheckoutGuard`-style guard can block the checkout CTA.
@@ -63,7 +72,7 @@ SessionRoot                          (provides the session tri-state; required a
 - **Invalid format:** the field shows its inline error; no write, no step advance.
 - **Cleared field:** blurring an emptied field re-fills the saved email; no write. Clearing must not visually "un-identify" — changing email (= switching user) is a deliberate act done by typing a new one.
 - **`canEditData: false`:** the field renders **disabled** and the root carries `data-fs-email-identification-readonly`. VTEX refuses profile edits for an identified-but-unauthenticated claimed profile, so the control never offers a write that is doomed server-side.
-- **Server `userErrors`:** surfaced inline; the session is left unchanged.
+- **Server `userErrors`:** surfaced inline, worded by `genericErrorMessage`; the session is left unchanged.
 
 ---
 
@@ -78,7 +87,8 @@ SessionRoot                          (provides the session tri-state; required a
       "props": {
         "label": "Email",
         "placeholder": "you@example.com",
-        "invalidEmailMessage": "Enter a valid email address."
+        "invalidEmailMessage": "Enter a valid email address.",
+        "genericErrorMessage": "Unable to save your details. Please try again."
       }
     }
   ]

package/dist/docs/footer-copyright.md

@@ -90,7 +90,7 @@ The element id is the content key, so name it for the section rather than its st
 
 | Component | What you style | Plausible classes |
 |---|---|---|
-| `FooterCopyright` | The legal notice line | `text-[12px] leading-[1.5] text-[#666666] text-center py-[16px]` |
+| `FooterCopyright` | The legal notice line | `text-[12px] leading-[1.5] text-[var(--color-text-muted)] text-center py-[16px]` |
 
 Styled example:
 
@@ -98,11 +98,13 @@ Styled example:
 {
   "footer-copyright": {
     "type": "FooterCopyright",
-    "style": ["text-[12px]", "leading-[1.5]", "text-[#666666]", "text-center", "py-[16px]"]
+    "style": ["text-[12px]", "leading-[1.5]", "text-[var(--color-text-muted)]", "text-center", "py-[16px]"]
   }
 }
 ```
 
+The colors that several elements share are variables of the page or layout `theme`, which declares them: `{"--color-text-muted": "#666666"}`. A color used once stays a hex.
+
 ---
 
 ## Related

package/dist/docs/form.md

@@ -124,6 +124,8 @@ cancels it, because the built-in guard's own `preventDefault()` runs after the a
 
 ## Components
 
+Each button part reads its text only from its own `$content`, whose `label` field is an ICU message, unless it has `children`; no part takes a copy prop. A missing message renders an empty button and logs `message.missing`.
+
 ### FormRoot
 
 The only `<form>` in a composition. Renders `noValidate`, wires
@@ -137,49 +139,65 @@ No props beyond the native `<form>` attributes (`onSubmit` is owned internally a
 
 | Prop | Type | Default | Notes |
 |------|------|---------|-------|
-| `label` | string | — | Rendered when there are no `children`. Falls through to the message catalog (`fs/form.submit`) when unset. |
-| `children` | ReactNode | — | Wins over `label` when present. |
-
-Text resolves `children ?? label ?? formatMessage({ id: 'fs/form.submit' })` — there is no hard-coded
-English default. An author who wants copy other than the catalog's own must set `label` or `children`
-explicitly.
+| `$content` | `ContentValue<typeof FormSubmitContent>` | — | Its `label` message is the button text when there are no `children`. |
+| `children` | ReactNode | — | Wins over `$content` when present; the message is then not read. |
 
 A `type="submit"` `Button`, disabled while `formState.isSubmitting`. Pressing it validates every
 registered field first; only once every field is valid does it skip untouched fieldsets, dispatch the
 dirty ones in registration order, and collect what failed. Pressing Enter in a text input does *not*
 submit — see *Implicit submission* above and `FormEnterSubmit` below for a form where it does.
 
+Content type `form-submit`:
+
+| Content field | Description |
+|---|---|
+| label | Button text |
+
 ### FormEnterSubmit
 
 | Prop | Type | Default | Notes |
 |------|------|---------|-------|
-| `label` | string | — | Rendered when there are no `children`. Falls through to the message catalog (`fs/form.submit`) when unset. |
-| `children` | ReactNode | — | Wins over `label` when present. |
+| `$content` | `ContentValue<typeof FormSubmitContent>` | — | Its `label` message is the button text when there are no `children`. |
+| `children` | ReactNode | — | Wins over `$content` when present; the message is then not read. |
 
-Renders the same button as `FormSubmit`, sharing its text resolution (the same `fs/form.submit` id —
-there is no separate id for the Enter variant, since both parts render the same word) and its
+Renders the same button as `FormSubmit`, sharing its content type (`form-submit` — there is no
+separate one for the Enter variant, since both parts render the same word) and its
 `data-fs-form-submit`/`data-fs-form-submit-pending` hooks — there is no separate styling hook for this
 part. While mounted, it additionally allows Enter to
 submit the enclosing `FormRoot` from any of its text-entry inputs (see *Implicit submission* above for
 the form-wide blast radius and the IME carve-out).
 
+Content type `form-submit`, shared with `FormSubmit`.
+
 ### FormError
 
 | Prop | Type | Default | Notes |
 |------|------|---------|-------|
-| `fallbackMessage` | string | `'Something went wrong. Please try again.'` | Shown for a fieldset whose write threw rather than resolving `userErrors`. |
+| `$content` | `ContentValue<typeof FormErrorContent>` | — | Its `fallbackMessage` message is shown for a fieldset whose write threw rather than resolving `userErrors`. |
 
 Renders nothing when the last submit produced no failures. Otherwise, one group per failing fieldset,
 carrying `data-fs-form-error-item={label}` — a styling/selector hook, never rendered as text. The visible
-text inside each group is each failing `userError`'s own `message`, or `fallbackMessage` when the dispatch
-rejected or never settled.
+text inside each group is each failing `userError`'s `message`, or the `fallbackMessage` message when
+the dispatch rejected or never settled. An unauthored `fallbackMessage` renders empty and logs
+`message.missing`.
+
+Those messages are the fieldsets' own copy: a fieldset's `dispatch` maps each refusal's `code` to a message
+field of its own `$content` and resolves `{ code, message }` with the formatted text. `FormError` words
+nothing itself. A fieldset never passes the server's `message` through: for a code it has no message field
+for, one a newer server added, it hands over its generic message and logs `message.unknown-code`.
+
+Content type `form-error`:
+
+| Content field | Description |
+|---|---|
+| fallbackMessage | Shown for a write that failed without `userErrors` |
 
 ### FormClear
 
 | Prop | Type | Default | Notes |
 |------|------|---------|-------|
-| `label` | string | — | Rendered when there are no `children`. Falls through to the message catalog (`fs/form.clear`) when unset. |
-| `children` | ReactNode | — | Wins over `label` when present. |
+| `$content` | `ContentValue<typeof FormClearContent>` | — | Its `label` message is the button text when there are no `children`. |
+| `children` | ReactNode | — | Wins over `$content` when present; the message is then not read. |
 
 A `type="button"` `Button` that empties every field registered by every fieldset inside the enclosing
 `FormRoot` — not only the fieldset nearest to it in the tree. Each bound part registers how its own
@@ -189,18 +207,30 @@ no bound part currently mounted is left alone. The following submit dispatches a
 fieldset that had something to clear, and nothing for one where clearing was a no-op. There is no prop
 to scope it to one fieldset; place it only where clearing the whole form is the intended action.
 
+Content type `form-clear`:
+
+| Content field | Description |
+|---|---|
+| label | Button text |
+
 ### FormReset
 
 | Prop | Type | Default | Notes |
 |------|------|---------|-------|
-| `label` | string | — | Rendered when there are no `children`. Falls through to the message catalog (`fs/form.reset`) when unset. |
-| `children` | ReactNode | — | Wins over `label` when present. |
+| `$content` | `ContentValue<typeof FormResetContent>` | — | Its `label` message is the button text when there are no `children`. |
+| `children` | ReactNode | — | Wins over `$content` when present; the message is then not read. |
 
 A `type="button"` `Button` that returns every registered field name to react-hook-form's baseline for
 that name, and clears its dirty/touched state. Before a fieldset's first successful write, that
 baseline is whatever the field's own seed resolves to; it becomes "what was last written" only after a
 successful submit.
 
+Content type `form-reset`:
+
+| Content field | Description |
+|---|---|
+| label | Button text |
+
 ---
 
 ## Canonical schema example
@@ -216,11 +246,17 @@ schema can author the form's boundary and its actions around wherever a fieldset
     "style": ["flex", "flex-col", "gap-4"],
     "children": ["shipping-address-fieldset", "step-error", "step-submit"]
   },
-  "step-error": { "type": "FormError" },
+  "step-error": {
+    "type": "FormError",
+    "props": { "fallbackMessage": "We couldn't save your details. Please try again." }
+  },
   "step-submit": { "type": "FormSubmit", "props": { "label": "Save and continue" } }
 }
 ```
 
+`fallbackMessage` on `step-error` and `label` on `step-submit` are messages, not props: a store without `store.cmsStoreId` compiles it into
+the element's `$content`, and a CMS-bound store authors it in the Content Platform instead.
+
 `shipping-address-fieldset` is a matter component (shipped by a later task) that renders its own
 fields and calls `registerFieldset` internally — it is placed in the schema like any other
 component, but nothing about its internals is schema-authorable.

package/dist/docs/free-shipping-progress.md

@@ -1,7 +1,7 @@
 # FreeShippingProgress
 
 **Category:** commerce
-**Purpose:** Reactive progress bar for the cart's nearest free-shipping goal. Reads `cart.freeShippingProgress` and the cart's `Items` totalizer (the amount the server measures, so shipping and discounts do not count), then renders one of three states: below-threshold ("faltam {value} para frete grátis" + a partially filled bar), earned ("você ganhou frete grátis!" + a full bar), or absent (renders nothing). Composed at the **top of a cart / mini-cart drawer** to nudge the shopper to add a bit more.
+**Purpose:** Reactive progress bar for the cart's nearest free-shipping goal. Reads `cart.freeShippingProgress` and the cart's `Items` totalizer (the amount the server measures, so shipping and discounts do not count), then renders one of three states: below-threshold (the `label` message, e.g. "faltam {value} para frete grátis", + a partially filled bar), earned (the `qualifiedLabel` message + a full bar), or absent (renders nothing). Composed at the **top of a cart / mini-cart drawer** to nudge the shopper to add a bit more.
 
 ---
 
@@ -63,10 +63,10 @@ FreeShippingProgressRoot        ← reactive provider; self-hides on null/loadin
 | Component | Props | Notes |
 |---|---|---|
 | `FreeShippingProgressRoot` | `threshold?`, `remaining?`, `qualified?`, `itemsTotal?`, `$data` | Provides `FreeShippingProgressContext`; the copy formats from the active storefront context; renders nothing when the field is `null` |
-| `FreeShippingProgressMessage` | `label?`, `qualifiedLabel?` | `label` is a `{value}`-token template (default `"faltam {value} para frete grátis"`); `qualifiedLabel` default `"você ganhou frete grátis!"`; `children` overrides the text |
-| `FreeShippingProgressBar` | — | Renders a `Meter` bar; `aria-valuetext` mirrors the visible copy |
+| `FreeShippingProgressMessage` | `$content` | Content type `free-shipping-progress-message`: `label` is an ICU message whose `value` argument is the formatted remaining amount; `qualifiedLabel` is the earned message. Both read only from `$content`: an unauthored message renders empty and logs `message.missing`. `children` replaces the text, and then no message is formatted |
+| `FreeShippingProgressBar` | — | Renders a `Meter` bar; `aria-valuetext` is its `valueText` message (`{value}` = the formatted remaining amount) or, once earned, `qualifiedValueText` (content type `free-shipping-progress-bar`) |
 
-Copy is front-localized and front-formatted from the Root's `locale`/`currency` (default `pt-BR`/`BRL`), not the payload `currencyCode`.
+Copy is front-localized and front-formatted from the active storefront context's `locale`/`currency`, not the payload `currencyCode`. A store without CMS authors the message fields on the element, as below; a CMS-bound store keeps them in content.
 
 ---
 
@@ -83,7 +83,8 @@ Copy is front-localized and front-formatted from the Root's `locale`/`currency`
     "props": { "label": "faltam {value} para frete grátis", "qualifiedLabel": "você ganhou frete grátis!" }
   },
   "free-shipping-progress-bar": {
-    "type": "FreeShippingProgressBar"
+    "type": "FreeShippingProgressBar",
+    "props": { "valueText": "{value} restantes para frete grátis", "qualifiedValueText": "frete grátis conquistado" }
   }
 }
 ```

package/dist/docs/identity-edit.md

@@ -42,10 +42,16 @@ resolution error rather than a silently dead branch that blanks the section.
 
 | Prop | Type | Default | Notes |
 |---|---|---|---|
-| `label` | string | `'editar'` / `'cancelar'` | Text shown when no children are composed. |
-| `children` | ReactNode | — | Custom content, e.g. an `Icon` plus text; falls back to `label`. |
+| `children` | ReactNode | — | Custom content, e.g. an `Icon` plus text; falls back to the `label` message. |
 | `className` | string | — | |
 
+Content models `identity-edit-button` and `identity-edit-cancel-button`, one ICU message field each, with
+no package default:
+
+| Field | Source (English) | Notes |
+|---|---|---|
+| `label` | `Edit` / `Cancel` | Text shown when no children are composed. |
+
 ## Behavior
 
 - Starts on the summary. Unlike the delivery section, nothing about the profile data decides this: the

package/dist/docs/identity-summary.md

@@ -35,11 +35,13 @@ anonymous state, so anything that must survive that state — the section headin
   The stored phone is E.164; the phone leaf's `country` (US/BR) selects the display mask, so the summary
   matches the edit form's masking, and a number belonging to another country renders as stored rather
   than being reformatted as a local one. Compose custom `children` to replace the default presentation —
-  the leaves then carry their own props. `SelectedSummary`'s own `country` and badge-label props apply to
-  the default composition only, and are not offered in the schema for that reason.
+  the leaves then carry their own props. `SelectedSummary`'s own `country` prop applies to the default
+  composition only, and is not offered in the schema for that reason. Its default badge has no labels of
+  its own: compose `IdentitySummaryBadge` and author its labels to show one.
 - **SignOutButton** — async/pessimistic: `data-fs-identity-summary-pending` is present while the
   mutation is in flight, the button is disabled to prevent double-dispatch, and any returned
-  `userErrors` surface via `Error`. Renders composed `children` (e.g. an `Icon` + text) or `label`.
+  `userErrors` surface via `Error`. Renders composed `children` (e.g. an `Icon` + text) or its `label`
+  message.
 - **Summary/form swap** — `IdentityEditController` with its guards and triggers. The edit and cancel
   buttons are `IdentityEditButton` and `IdentityEditCancelButton`; a leading icon composes as their children.
   The controller moves only on those buttons — saving does not collapse the section — so neither this
@@ -49,8 +51,8 @@ anonymous state, so anything that must survive that state — the section headin
 
 `IdentitySummarySelectedSummary` is a **shortcut**: it renders the default order (badge, name, e-mail,
 phone, document) so a page wanting exactly that composes one element. It is not the only way, and it
-offers no props to the schema — configure the leaf, not the wrapper. Its `country` and badge-label props
-reach the default composition only, so composing children silently replaces whatever they would have set.
+offers no props to the schema — configure the leaf, not the wrapper. Its `country` prop reaches the
+default composition only, so composing children silently replaces whatever it would have set.
 
 Each line is its own component reading the same `IdentitySummaryRoot` context, so the order, the presence
 and anything interleaved between them are the page's decision (ADR-0011):
@@ -70,6 +72,17 @@ IdentitySummaryRoot
 └─ IdentitySummaryPhone country="BR"
 ```
 
+## Messages
+
+ICU message fields, authored per element, with no package default. An unauthored field renders empty and
+logs `message.missing`.
+
+| Content type | Field | Source (English) |
+|---|---|---|
+| `identity-summary-root` | `signOutErrorMessage` | `Unable to sign out. Please try again.` — shown for every logout refusal (each `SessionErrorCode` and `NETWORK_ERROR`, none of which the shopper can act on) and for a logout that throws. A code it does not know (one a newer server added) shows it too and logs `message.unknown-code`; a blank message renders an empty alert and logs `message.missing` |
+| `identity-summary-badge` | `identifiedLabel`, `loggedInLabel` | `Guest`, `Signed in` |
+| `identity-summary-sign-out-button` | `label` | `Sign out` |
+
 ## Data attributes
 
 | Attribute | Element | When |