@vtex/faststore 0.0.1

package/dist/docs/client-preferences.md

@@ -0,0 +1,184 @@
+# ClientPreferences
+
+**Category:** identity
+**Purpose:** The consent opt-in section of a checkout User Identity step. A `ClientPreferencesRoot` reads both opt-in flags — newsletter (`optinNewsLetter`) and save-personal-data (`savePersonalData`) — from the shopper's `ClientPreferences` entity (a sibling of `Cart`, via `Query.clientPreferences`) and publishes them to its Controls. Each Control is a bound checkbox that persists its own flag via `$actions.identity.clientPreferencesUpdate`. It reads session state from `useSession()` and must sit inside a `SessionRoot`.
+
+---
+
+## Visual cues (how to identify in an image)
+
+Use these signals to detect that a consent opt-in section is present. Position on the page is irrelevant for detection. The image is the source of truth for layout.
+
+- One or two **checkboxes with a text label**, typically below the email/profile fields of a checkout identity step.
+- A **newsletter opt-in** — a checkbox labelled like *"Quero receber novidades e ofertas por e-mail"* / *"Sign me up for the newsletter"*.
+- A **save-my-data opt-in** — a checkbox labelled like *"Salvar minhas informações para a próxima compra"* / *"Save my information for next time"*.
+- The checkboxes are **unchecked by default** (opt-in, not opt-out).
+
+Use `ClientPreferencesRoot` + the matching Control(s) whenever the checkbox must read from and write to the shopper's stored preferences — not for a purely presentational checkbox.
+
+---
+
+## When to use
+
+- The consent / preferences step of the checkout User Identity flow.
+- Anywhere the shopper's newsletter or save-personal-data preference must be read (pre-fill) and written (persisted on toggle).
+
+## When NOT to use
+
+- A purely presentational checkbox with host-owned state → use the `Checkbox` particle (optionally wrapped with `Field`) directly.
+- Email / name / phone / document identity fields → out of scope (separate identity components; email is `EmailIdentificationControl`).
+- Terms-and-conditions or order-review checkboxes unrelated to `ClientPreferences` → not this matter.
+
+---
+
+## Composition
+
+```
+SessionRoot                          (provides the session tri-state; required ancestor)
+└── ClientPreferencesRoot            (data-fs-client-preferences-root; reads both opt-ins)
+    ├── NewsletterOptInControl       (data-fs-newsletter-opt-in; bound to optinNewsLetter)
+    └── SavePersonalDataOptInControl (data-fs-save-personal-data-opt-in; bound to savePersonalData)
+```
+
+- `ClientPreferencesRoot` **must** have a `SessionRoot` ancestor — `useSession()` throws otherwise.
+- Both Controls **must** be descendants of `ClientPreferencesRoot` — each throws *"A client-preferences Control must be used inside a ClientPreferencesRoot."* otherwise.
+- The two Controls are **siblings** in the same `children` array — a single Root owns both opt-ins (one data owner = one Root, per ADR-0011). Include only the Control(s) whose checkbox is visible; child order reflects visual order.
+
+---
+
+## Components
+
+### ClientPreferencesRoot
+
+Binding provider for the section. Reads both opt-in values from `Query.clientPreferences`, seeds each Control, and tracks per-field pending/error. Renders a `<div data-fs-client-preferences-root>` wrapper. No merchant-facing props beyond `className`.
+
+**Data:** declares a colocated `fragment ClientPreferencesData on Query { clientPreferences { optinNewsLetter savePersonalData } }` with `fetchStrategy: 'reactive'`. The compiler merges it into the page query — no explicit `dataSources` entry needed.
+
+### NewsletterOptInControl
+
+The bound newsletter checkbox (`optinNewsLetter`). Inlines `Field` + `Checkbox` + `Icon` (no `CheckboxField` particle). Toggling dispatches `$actions.identity.clientPreferencesUpdate({ optinNewsLetter })`. Defaults to unchecked.
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| `label` | string | — | The text shown beside the checkbox. |
+| `$actions` | injected | — | Carries `identity.clientPreferencesUpdate` (compiler-injected). |
+
+**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
+
+The bound save-personal-data checkbox (`savePersonalData`). Same shape as `NewsletterOptInControl` — toggling dispatches `$actions.identity.clientPreferencesUpdate({ savePersonalData })`, carries `data-fs-save-personal-data-opt-in-pending` while in flight, and surfaces its own `userErrors`. Defaults to unchecked.
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| `label` | string | — | The text shown beside the checkbox. |
+| `$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.
+
+---
+
+## Behavior
+
+- **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).
+- **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`.
+
+---
+
+## Canonical schema example
+
+```json
+{
+  "session": {
+    "type": "SessionRoot",
+    "children": ["client-preferences"]
+  },
+  "client-preferences": {
+    "type": "ClientPreferencesRoot",
+    "children": ["newsletter-opt-in", "save-data-opt-in"]
+  },
+  "newsletter-opt-in": {
+    "type": "NewsletterOptInControl",
+    "props": { "label": "Quero receber novidades e ofertas por e-mail" }
+  },
+  "save-data-opt-in": {
+    "type": "SavePersonalDataOptInControl",
+    "props": { "label": "Salvar minhas informações para a próxima compra" }
+  }
+}
+```
+
+### Minimal variant (only the newsletter opt-in visible)
+
+```json
+{
+  "session": {
+    "type": "SessionRoot",
+    "children": ["client-preferences"]
+  },
+  "client-preferences": {
+    "type": "ClientPreferencesRoot",
+    "children": ["newsletter-opt-in"]
+  },
+  "newsletter-opt-in": {
+    "type": "NewsletterOptInControl",
+    "props": { "label": "Sign me up for the newsletter" }
+  }
+}
+```
+
+---
+
+## Common mistakes
+
+- **Rendering a Control outside `ClientPreferencesRoot`.** Each Control reads the section context and throws otherwise.
+- **Rendering `ClientPreferencesRoot` outside `SessionRoot`.** `useSession()` throws; every identity page must host a `SessionRoot`.
+- **Inventing a `CheckboxField` particle.** The Controls deliberately inline `Field` + `Checkbox` + `Icon`; there is no `CheckboxField`.
+- **Nesting one Control inside the other.** `NewsletterOptInControl` and `SavePersonalDataOptInControl` are siblings under one `ClientPreferencesRoot`, not parent/child.
+- **Adding a second `ClientPreferencesRoot` for the second checkbox.** One Root owns both opt-ins; add the two Controls as siblings.
+- **Defaulting to checked.** These are opt-ins — unchecked by default. A `null` preference is unchecked, not checked.
+
+---
+
+## Styling
+
+`ClientPreferencesRoot` stacks the checkboxes; each Control is a checkbox-plus-label row. Read spacing and text color off the image.
+
+| 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]` |
+
+Styled example:
+
+```json
+{
+  "client-preferences": {
+    "type": "ClientPreferencesRoot",
+    "children": ["newsletter-opt-in", "save-data-opt-in"],
+    "style": ["flex", "flex-col", "gap-[8px]"]
+  },
+  "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]"]
+  },
+  "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]"]
+  }
+}
+```
+
+---
+
+## Related
+
+- [[email-identification]] — sibling identity control; reads/writes `clientProfile.email` and moves the session `anonymous → identified`. Same `SessionRoot` requirement.
+- [[session]] — provides the identification tri-state and the required `SessionRoot` ancestor.
+- [[checkbox]] — the presentational particle each Control wraps.
+- [[field]] — provides the label/error wrapper each Control inlines.

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

@@ -0,0 +1,192 @@
+# ClientProfileForm
+
+**Category:** identity
+**Purpose:** The batched customer-information form for the checkout identity step — the `InformationFormUSA` replacement. Pre-fills first/last name, phone, document, and both consent opt-ins from the shopper's saved profile and preferences; displays the email read-only. A single Save / Continue action validates the draft and dispatches at most one `clientProfileUpdate` and one `clientPreferencesUpdate`, each carrying only the fields the shopper edited, with pending/confirmation/error feedback.
+
+---
+
+## Visual cues (how to identify in an image)
+
+- A single form block on a checkout identity step titled "Your information" (or similar), grouping: a read-only email display, first name, last name, a country-masked phone field, an optional tax-document field (e.g. CPF for Brazil), and two checkboxes ("email me with news and offers", "save my information for next time").
+- One visible primary button at the bottom labelled "Save and continue" (or similar) — not a hidden submit.
+- Pre-filled values for a returning/identified shopper; blank, still-editable fields for a guest or an incomplete profile.
+- An inline error banner on failure, or a confirmation line on success, appearing near the button.
+
+Use `ClientProfileForm` (not a hand-assembled combination of `Field`/`PhoneField`/`DocumentField`) whenever the image shows this whole batched-save customer-information block.
+
+---
+
+## When to use
+
+- The customer-information section of the checkout identity step, for both returning/identified shoppers (pre-fill + edit) and guests (fill from empty).
+- Anywhere name, phone, document, and consent opt-ins must be collected together and persisted in one explicit action.
+
+## When NOT to use
+
+- Editing the email — that is `EmailIdentificationControl`'s job; this form only displays it.
+- A single standalone phone or opt-in field with its own save-on-blur behavior — use `ClientProfilePhoneControl` / `NewsletterOptInControl` / `SavePersonalDataOptInControl` instead. **Never place a standalone per-field identity Control and this form for the same field on the same view** — both would write the field, racing each other.
+- Address fields — those belong to Delivery, not this form.
+
+---
+
+## Composition
+
+`ClientProfileForm` is a **compound**: `Root` owns the data + mechanics; the field/fieldset/feedback
+parts are composed freely (any order, any subset). The schema author decides which fields render — a
+merchant whose platform config drops a field (or whose account can't persist one, e.g. an unsupported
+`savePersonalData`) simply does not compose that part.
+
+```
+SessionRoot                                 (required ancestor; session tri-state + canEditData)
+└── ClientProfileForm.Root                  (data-fs-client-profile-form; own fragment/data root; owns draft + Save)
+    ├── ClientProfileForm.Fieldset section="profile" [legend]
+    │     ├── .EmailField                    (read-only)
+    │     ├── .FirstNameField / .LastNameField
+    │     ├── .PhoneField                    (uses country from Root)
+    │     └── .DocumentField                 (self-gates on documentType)
+    ├── ClientProfileForm.Fieldset section="preferences" [legend]
+    │     ├── .NewsletterCheckbox
+    │     └── .SavePersonalDataCheckbox       (omit to drop the field entirely — no CSS hack)
+    ├── .Error / .Confirmation
+    └── .SubmitButton
+```
+
+`Root` is self-contained: it declares the colocated fragment over `clientProfile` + `clientPreferences`
+and must not be nested inside `ClientProfileRoot` / `ClientPreferencesRoot` (those self-persist per
+field on blur, double-writing against this form's batched Save). Every part `requiresContext:
+'client-profile-form'`; a custom/derived field declares its own additional `requiresContext`.
+
+---
+
+## Behavior
+
+- **Sections**: compose `ClientProfileForm.Fieldset` blocks with a `section` name → `data-fs-client-profile-form-section="<name>"`, and an optional `legend`. Not hard-coded — the author groups fields however the design needs.
+- **Pre-fill**: every field seeds from `$data` on mount; missing profile fields render empty and stay editable.
+- **Draft & dirty tracking**: edits are tracked locally per field; only touched fields are dispatched. Background `$data` refreshes re-seed untouched fields only — an in-progress edit is never clobbered.
+- **Save**: validates **field format only** — phone mask and document check-digit, each blocking Save when the field is non-empty and malformed. It does not enforce requiredness: the parts are composed freely by the schema, so a required check here could fire for a field the page never mounted. Which fields a shopper must fill is a business rule, waiting on the composable entity forms RFC (#572) to decide where it belongs. The format checks carry the same composition hazard in a narrower form, and it is still open: they key off the Root's `country` and `documentType` rather than off which leaves were composed, so a store that sets `documentType` without composing `DocumentField` can block Save with no field to render the error in and nowhere to move focus. Closing it properly means the leaves registering themselves with the Root, which is that same RFC's territory. The phone case is wider than the document one and needs no merchant configuration at all — see Known gaps below. On Save it dispatches at most one `clientProfileUpdate` (dirty profile fields) and one `clientPreferencesUpdate` (dirty consent flags) in parallel; a Save with nothing dirty dispatches nothing and shows the confirmation, so the press still answers.
+- **Document erase**: clearing a previously-saved document and pressing Save sends `document: ''` — an explicit erase, not an omission.
+- **Feedback**: `data-fs-client-profile-form-pending` while a write is in flight (fieldset disabled, Save not re-triggerable); an inline `role="alert"` region on `userErrors`; an `<output>` confirmation on success, cleared on the next edit.
+- **Read-only**: `session.canEditData === false` renders `data-fs-client-profile-form-readonly`, disables every field, and omits the Save button entirely.
+- **The form announces nothing**: a completed Save shows the confirmation and stops there. It publishes no signal, so nothing elsewhere collapses, advances or reacts. Whether finishing this form should move a section or a wizard is a sequencing question, and the mechanism for it is being designed in the flow-of-steps RFC (#611) rather than assumed here.
+- **The form never learns who listens.** It reports nothing at all, so `IdentityEditController` cannot react to it: that section moves only on its own buttons. Compose the swap around this form: an `IdentityEditController` holding an `IdentitySummaryView` with the summary, an `IdentityEditForm` with `ClientProfileForm.Root`, an `IdentityEditButton` in the heading, and an `IdentityEditCancelButton` as cancel next to the form. The same form therefore works unchanged inside a collapsing section or on a page of its own.
+
+---
+
+## Props
+
+**`ClientProfileForm.Root`** — `country` (`'US' | 'BR'`, default `'US'`; provided to the phone leaf via
+context), `documentType` (string, e.g. `'CPF'`; the document leaf renders only when supported).
+Declares `actions: { identity: ['clientProfileUpdate', 'clientPreferencesUpdate'] }`,
+`requiresContext: 'session'`, `providesContext: 'client-profile-form'`.
+
+**`ClientProfileForm.Fieldset`** — `legend` (optional visible title), `section` (name → `data-fs-*-section`).
+
+**Field parts** (`.EmailField`, `.FirstNameField`, `.LastNameField`, `.PhoneField`, `.DocumentField`,
+`.NewsletterCheckbox`, `.SavePersonalDataCheckbox`) — each takes an optional `label` (sensible default).
+**`.Confirmation`** — `message` (default `'Your information has been saved.'`). **`.SubmitButton`** —
+`label` (default `'Save and continue'`) or composed `children`.
+
+---
+
+## Canonical schema example
+
+```json
+{
+  "session": {
+    "type": "SessionRoot",
+    "children": ["email-identification", "profile-form"]
+  },
+  "email-identification": {
+    "type": "EmailIdentificationControl",
+    "children": []
+  },
+  "profile-form": {
+    "type": "ClientProfileFormRoot",
+    "props": { "country": "BR", "documentType": "CPF" },
+    "children": ["profile-fieldset", "preferences-fieldset", "form-error", "form-confirmation", "form-submit"]
+  },
+  "profile-fieldset": {
+    "type": "ClientProfileFormFieldset",
+    "props": { "section": "profile", "legend": "Your information" },
+    "children": ["email", "first-name", "last-name", "phone", "document"]
+  },
+  "email": { "type": "ClientProfileFormEmailField", "children": [] },
+  "first-name": { "type": "ClientProfileFormFirstNameField", "children": [] },
+  "last-name": { "type": "ClientProfileFormLastNameField", "children": [] },
+  "phone": { "type": "ClientProfileFormPhoneField", "children": [] },
+  "document": { "type": "ClientProfileFormDocumentField", "children": [] },
+  "preferences-fieldset": {
+    "type": "ClientProfileFormFieldset",
+    "props": { "section": "preferences" },
+    "children": ["newsletter"]
+  },
+  "newsletter": { "type": "ClientProfileFormNewsletterCheckbox", "children": [] },
+  "form-error": { "type": "ClientProfileFormError", "children": [] },
+  "form-confirmation": { "type": "ClientProfileFormConfirmation", "children": [] },
+  "form-submit": { "type": "ClientProfileFormSubmitButton", "children": [] }
+}
+```
+
+Both fieldsets are children of the Root, not siblings of it: every part declares
+`requiresContext: 'client-profile-form'`, so a fieldset placed outside is rejected by the
+context-constraint walk at build time.
+
+(Omitting `ClientProfileFormSavePersonalDataCheckbox` above drops that field entirely — the intended
+way to exclude a field the account can't persist, with no CSS hack and no shared-component change.)
+
+---
+
+## Common mistakes
+
+- **Rendering `ClientProfileForm` outside `SessionRoot`.** `useSession()` throws; every identity page must host a `SessionRoot`.
+- **Nesting it inside `ClientProfileRoot` / `ClientPreferencesRoot`, or placing a standalone Control for the same field alongside it.** The form is its own data root and its own write surface — double-nesting or double-placing creates a double-write race.
+- **Expecting the email to be editable.** It is always read-only here; email changes go through `EmailIdentificationControl`.
+- **Expecting per-keystroke or per-blur saves.** All fields are form-bound; only pressing Save dispatches a write.
+- **Expecting the form to enforce required fields.** It validates format only. A blank field saves, because the form cannot know which of its freely-composed parts the page actually mounted.
+- **Rendering a field part outside `ClientProfileForm.Root`.** Every part `requiresContext: 'client-profile-form'` and throws otherwise.
+
+---
+
+## Styling
+
+| Component | What you style | Plausible classes |
+|---|---|---|
+| `ClientProfileForm` | The `data-fs-client-profile-form` root; carries `-pending`/`-readonly`/`-saved` presence attributes | `flex flex-col gap-10` |
+| Section | `data-fs-client-profile-form-section="profile\|preferences"` — the two entity-anchored fieldsets | `flex flex-col gap-4` |
+| Field wrapper | `data-fs-client-profile-form-field="email\|first-name\|last-name\|phone\|document\|newsletter\|save-personal-data"` | `flex flex-col gap-4` |
+| Error / confirmation | `[data-fs-client-profile-form-error]` / `[data-fs-client-profile-form-confirmation]` | `text-sm text-red-600` / `text-sm text-green-600` |
+
+Field-level visuals (borders, focus rings, error color) are owned by the composed particles' own swatches (`field`, `phone-field`, `document-field`, `checkbox`, `button`) and are not redefined here.
+
+---
+
+## Known gaps
+
+Found by review and deliberately left for the dedicated revision of these components, rather than patched
+here. The first is the widest.
+
+- **Format validation runs against fields the page may never have composed, and the phone case needs no
+  merchant configuration at all.** `country` defaults to `'US'`, so the phone check always runs. A store
+  composing `Root` + name fields + `SubmitButton`, serving a shopper whose stored phone is a legacy
+  malformed value, gets a Save that sets `errors.phone`, finds no phone input to focus, renders no message
+  because `PhoneField` is not mounted, and returns — dead on every press, button still enabled. The
+  `documentType` variant of the same hole at least requires the merchant to have set a Root prop. Closing
+  both properly means the leaves registering themselves with the Root; see the composable entity forms RFC
+  (#572).
+- **Two other early returns leave Save silent.** A missing `$actions.identity`, or a dirty field with no
+  matching write function, returns without touching `pending`, `serverError` or `saved` — the same dead
+  press the pristine branch above was changed to avoid.
+- **`VALIDATION_ORDER` is a hard-coded `['phone', 'document']`,** but the leaves are now composed in any
+  order. With both fields malformed, focus jumps to the phone input even when the document error is the one
+  the shopper can see first. The order should come from DOM position now that the fixed template is gone.
+- **The re-seed of untouched fields mutates a ref during render** and queues its `setDraft` in the same
+  pass. A discarded render keeps the ref but loses the update, so pristine fields can hold stale values
+  after `$data` arrives.
+
+## Related
+
+- [[email-identification]] — the sibling identification control this form's email display defers to.
+- [[client-profile]] — the standalone, per-field-blur phone binding; do not compose alongside this form for the same field.
+- [[client-preferences]] — the standalone, per-field-blur consent Controls; do not compose alongside this form for the same field.
+- [[session]] — provides the identification tri-state and the required `SessionRoot` ancestor.
+- [[phone-field]], [[document-field]], [[field]], [[fieldset]], [[checkbox]] — the particles this matter composes directly.

package/dist/docs/client-profile.md

@@ -0,0 +1,117 @@
+# ClientProfile
+
+**Category:** identity
+**Purpose:** The shopper-profile section of a checkout User Identity step. `ClientProfileRoot` reads the `ClientProfile` sibling entity (`Query.clientProfile`) and publishes its fields to descendant Controls; `ClientProfilePhoneControl` binds a `PhoneField` to `clientProfile.phone`, pre-filling from the entity and persisting on blur via `$actions.identity.clientProfileUpdate`. The Root reads `useSession()` and must sit inside a `SessionRoot`.
+
+---
+
+## Visual cues (how to identify in an image)
+
+- A shopper-profile block on a checkout identification step — today a single **phone number** field labelled "Phone" / "Telefone", masked per country (`(123) 456-7890` for US, `(11) 99999-9999` for BR).
+- The value is pre-filled for a returning/identified shopper and editing it persists the new number to the profile.
+- When invalid, an inline error appears below the input.
+
+The image is the source of truth for layout. Use the `ClientProfile` Root + Control (not a bare `PhoneField`) whenever the phone must read from and write to the shopper profile.
+
+---
+
+## When to use
+
+- The profile-fields section of the checkout User Identity flow.
+- Anywhere the shopper's profile phone must be read (pre-fill) and written (persisted to `clientProfileData`).
+
+## When NOT to use
+
+- A purely presentational phone input with host-owned state → use the `PhoneField` particle directly.
+- The email identification field → use `EmailIdentificationControl`.
+- Name / document / opt-in fields → out of scope (separate future Controls on the same Root).
+
+---
+
+## Composition
+
+```
+SessionRoot                        (provides the session tri-state; required ancestor)
+└── ClientProfileRoot              (data-fs-client-profile-root; provides context 'client-profile')
+    └── ClientProfilePhoneControl  (bound phone field; requires context 'client-profile')
+```
+
+- `ClientProfileRoot` **must** have a `SessionRoot` ancestor — `useSession()` throws otherwise.
+- `ClientProfilePhoneControl` **must** be a descendant of `ClientProfileRoot` — it throws otherwise.
+- Child order reflects visual order. Future profile Controls are siblings of `ClientProfilePhoneControl` under the same Root.
+
+---
+
+## Components
+
+### ClientProfileRoot
+
+Section provider. Declares a colocated reactive fragment `ClientProfilePhoneData on Query { clientProfile { phone } }` (`fetchStrategy: 'reactive'`) — the compiler merges it into the page query, no explicit `dataSources` entry needed. Seeds the profile values and publishes the `client-profile` context.
+
+No props (the `$data` slice and `className` are injected / host-supplied, not authored in schema).
+
+### ClientProfilePhoneControl
+
+Binds the reusable `PhoneField` particle to the profile. Reads the saved phone from context; on a **changed, client-valid** value persists only `phone` through `$actions.identity.clientProfileUpdate({ phone })` on blur (pessimistic — awaits the mutation). The field is disabled while the write is in flight and server `userErrors` surface inline.
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| `label` | string | `'Phone'` | Visible field label. |
+| `country` | `'US' \| 'BR'` | `'US'` | Selects the phone mask and validation rule. |
+| `requirement` | `'mandatory' \| 'optional' \| 'hidden'` | `'mandatory'` | Controls visibility and required validation. |
+| `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). |
+
+**Write:** declares `actions: { identity: ['clientProfileUpdate'] }`. No write when the value is unchanged, empty-and-mandatory, or client-side invalid.
+
+---
+
+## Canonical schema example
+
+```json
+{
+  "type": "SessionRoot",
+  "children": [
+    {
+      "type": "ClientProfileRoot",
+      "children": [
+        {
+          "type": "ClientProfilePhoneControl",
+          "props": {
+            "label": "Phone",
+            "country": "US",
+            "requirement": "mandatory"
+          }
+        }
+      ]
+    }
+  ]
+}
+```
+
+---
+
+## Common mistakes
+
+- **Rendering `ClientProfileRoot` outside `SessionRoot`.** `useSession()` throws; every identity page must host a `SessionRoot`.
+- **Using a bare `PhoneField` for the profile phone.** The correct binding is `ClientProfilePhoneControl`, which reads and writes `clientProfile.phone`.
+- **Putting `ClientProfilePhoneControl` outside `ClientProfileRoot`.** It must be a descendant; the context throws otherwise.
+- **Expecting the write on every keystroke.** The persist runs on blur, only for a changed and valid value.
+
+---
+
+## Styling
+
+| Component | What you style | Plausible classes |
+|---|---|---|
+| `ClientProfileRoot` | Stacks the profile fields | `flex flex-col gap-4` |
+| `ClientProfilePhoneControl` | The control wrapper (`data-fs-client-profile-phone-control`, receives `className`; carries `data-fs-client-profile-phone-pending` while the write is in flight and `data-fs-client-profile-phone-readonly` when the session's `canEditData` is false); target the inner `data-fs-phone-field-*` attributes | `flex flex-col gap-1 [&_[data-fs-phone-field-input]]:border [&_[data-fs-phone-field-input]]:rounded-md [&_[data-fs-phone-field-input]]:px-3 [&_[data-fs-phone-field-input]]:py-2 [&_[data-fs-phone-field-error]]:text-xs [&_[data-fs-phone-field-error]]:text-red-500` |
+
+---
+
+## Related
+
+- [[phone-field]] — the presentational particle this binds to the shopper `ClientProfile`.
+- [[email-identification]] — the sibling identity control that binds the email and flips `Session.isIdentified`.
+- [[session]] — provides the identification tri-state and the required `SessionRoot` ancestor.

package/dist/docs/container.md

@@ -0,0 +1,97 @@
+# Container
+
+**Category:** layout
+**Purpose:** Generic layout wrapper. Centers its content and applies a responsive max-width. Has no commerce data of its own — it groups other blocks (gallery, product info, pricing, buy button) into a page section.
+
+---
+
+## Visual cues (how to identify in an image)
+
+Container is a layout primitive, not a visible widget — you rarely "see" it directly. Infer one when the image shows several blocks sharing a centered column with consistent side margins. The image is the source of truth for layout.
+
+Reach for `Container` when:
+
+- The page content sits in a **centered column** with empty gutters on both sides, rather than spanning edge to edge.
+- Multiple distinct blocks (gallery, title, price, CTA) are **visually grouped** inside that column.
+
+Do not add a `Container` for a single isolated element that needs no grouping.
+
+---
+
+## When to use
+
+- As the layout wrapper that holds the main blocks of a PDP (gallery, product info, pricing, buy button) inside one centered column.
+- Any time several sibling blocks need to share the same max-width and centering.
+
+## When NOT to use
+
+- As the cart data provider — that is `CartRoot`. `Container` carries no cart context.
+- As a styled box with custom padding/background unrelated to the centered-column layout — use a plain element with a class instead.
+- To wrap a single element that already lays out fine on its own — extra nesting only bloats the schema.
+
+---
+
+## Composition
+
+`Container` is a passthrough wrapper: it renders a `<div>` and places its children inside. It has no required parent and no required children — anything valid in the schema can be a child. On a PDP it typically sits just under `CartRoot` and groups the page's main blocks.
+
+```
+CartRoot
+└── Container
+    ├── ProductGalleryRoot
+    ├── ProductInformationRoot
+    ├── PricingRoot
+    └── BuyButtonRoot
+```
+
+Children are siblings sharing the same `children` array; child order reflects visual order. `Container` does not provide any data context, so cart-aware blocks (`BuyButtonRoot`, cart particles) still need a `CartRoot` ancestor above it.
+
+---
+
+## Components
+
+### Container
+
+Centered, max-width layout wrapper. No props — it accepts only standard `<div>` attributes (e.g. `className`).
+
+---
+
+## Canonical schema example
+
+`Container` grouping the main PDP blocks under a page-level `CartRoot`:
+
+```json
+{
+  "root": { "type": "CartRoot", "children": ["layout"] },
+  "layout": {
+    "type": "Container",
+    "children": ["gallery", "product-info", "pricing", "buy-button"]
+  },
+  "gallery":      { "type": "ProductGalleryRoot" },
+  "product-info": { "type": "ProductInformationRoot", "children": ["title", "description"] },
+  "title":        { "type": "ProductInformationTitle" },
+  "description":  { "type": "ProductInformationDescription" },
+  "pricing":      { "type": "PricingRoot", "children": ["pricing-selling"] },
+  "pricing-selling": { "type": "PricingSellingPrice" },
+  "buy-button":   { "type": "BuyButtonRoot", "children": ["buy-button-action"] },
+  "buy-button-action": { "type": "BuyButtonButton" }
+}
+```
+
+---
+
+## Common mistakes
+
+- **Using `Container` as the page root on a PDP with a buy button.** The root must be `CartRoot` so cart-aware blocks have their context; `Container` goes underneath it.
+- **Expecting `Container` to provide product or cart data.** It is a pure layout `<div>` — data comes from `CartRoot`, `PricingRoot`, etc.
+- **Inventing `Section`, `Box`, `Wrapper`, or `Layout`.** The layout primitive is `Container`.
+- **Nesting a `Container` for every block.** One `Container` grouping the sibling blocks is enough; per-block wrappers add depth without purpose.
+
+---
+
+## Related
+
+- [[cart]] — `CartRoot`, the page-level data provider that usually wraps `Container` on a PDP.
+- [[buy-button]] — purchase CTA placed as a child block inside `Container`; requires the `CartRoot` ancestor.
+- [[pricing]] — price block placed as a sibling inside `Container`.
+- [[product-information]] — title/description block placed as a sibling inside `Container`.