@vtex/faststore 0.0.4 → 0.0.6

package/dist/docs/cardholder-document.md

@@ -0,0 +1,142 @@
+# CardholderDocument
+
+**Category:** commerce
+**Purpose:** A single tax-document input (CPF) for the checkout payment step, shown or hidden and marked required by the currently selected payment method's server-driven configuration.
+
+---
+
+## Visual cues (how to identify in an image)
+
+Use these signals to detect that a CardholderDocument block is present. Position on the page is irrelevant for detection — it typically sits near the card-entry fields in a payment/checkout step. The image is the source of truth for layout.
+
+A CardholderDocument block is:
+
+- A **single labeled text input**, formatted with dots and a dash like `123.456.789-01` (the CPF mask).
+- Labeled **"CPF"** or a similar tax-document label — never "Card number", "Expiration", or "CVV".
+- Not accompanied by a network icon, a "•••• 1234" masked number, or any card-brand logo — those belong to `CardEntry` or `SavedCards`, not this block.
+- Sometimes marked with a required indicator (an asterisk or similar) next to its label; sometimes not — both are valid, since requiredness is server-driven per payment method.
+
+If the image shows a **card-entry form with one extra plain text field formatted like a Brazilian tax ID**, use `CardholderDocument`. Do not use it for the shopper's account/profile document field — that is a different, identity-step component this block never composes with or reads from.
+
+---
+
+## When to use
+
+- The checkout/payment step, as a sibling of the card-entry fields, for a store whose selected payment method requires (or offers) a cardholder tax document.
+
+## When NOT to use
+
+- The shopper's saved profile/identity document (a client-identity or user-profile field) → use the identity-step document component instead. `CardholderDocument` is a payment-time value, deliberately separate — it never reads or writes the stored profile document, because the epic's RFC records that the two may differ.
+- A generic, data-agnostic tax-document input with no server-driven presence/requiredness → use the `DocumentField` particle directly instead; `CardholderDocument` exists specifically to wire that particle to the selected payment method's validator.
+- More than one document type or country → out of scope today. Only CPF renders; see this component's own spec for the recorded deferral.
+
+---
+
+## Composition
+
+`CardholderDocument` is a leaf and must be a descendant of `PaymentSectionRoot` or `PaymentSectionController`. It takes no children and is placed as a **sibling** of `CardEntry`, `SavedCards`, `Installments`, and the other payment leaves — never nested inside any of them.
+
+```
+PaymentSectionRoot (or PaymentSectionController)
+├── PaymentMethodList
+├── CardEntry                 (sibling — new-card fields)
+├── CardholderDocument         (sibling — this block)
+├── Installments
+└── SavedCards
+```
+
+Child order reflects visual order. There is no parent/child relationship for this component to define — it is a single, independently placeable field.
+
+**Composition rules:**
+
+- Must be inside `PaymentSectionRoot` or `PaymentSectionController`. Outside either, it throws.
+- Renders `null` (no DOM at all) when the selected payment method's validator does not mark a document displayable, or when no method is selected yet. This is normal, not an error — most methods most of the time render nothing here.
+- Also renders `null` 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]]) — whatever that method's own validator says. When the card comes back, the field re-seeds from the value already typed.
+- Takes no children; passing any is a no-op.
+
+---
+
+## Components
+
+### CardholderDocument
+
+The field itself. Renders the `DocumentField` particle for CPF, with presence and requiredness resolved from `usePayment().selectedMethod.validator` (`documentDisplayable` / `documentRequired`) rather than from any prop.
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| `label` | `string` | `'CPF'` | The field's visible label. |
+| `placeholder` | `string` | `'000.000.000-00'` | Shown in the empty input as a format hint. |
+| `errorMessage` | `string` | `'Invalid CPF'` | Shown inline when the typed value fails CPF check-digit validation on blur. |
+| `disabled` | `boolean` | `false` | Disables the input without hiding it — independent of the data-driven presence gate. |
+
+No `documentType` prop — this build supports CPF only. No `required` prop — requiredness is always read from the selected method's validator, never authored.
+
+**Data:** declares no `fragment` of its own. It reads `selectedMethod`, `draft`, and `setDraftDocument` off the ambient `payment` context that `PaymentSectionRoot` / `PaymentSectionController` already fetches for.
+
+---
+
+## Canonical schema example
+
+```json
+{
+  "payment-section": {
+    "type": "PaymentSectionRoot",
+    "children": ["payment-method-list", "card-entry", "cardholder-document", "installments"]
+  },
+  "payment-method-list": { "type": "PaymentMethodList" },
+  "card-entry": { "type": "CardEntry" },
+  "cardholder-document": {
+    "type": "CardholderDocument",
+    "props": { "label": "CPF", "placeholder": "000.000.000-00" }
+  },
+  "installments": { "type": "Installments" }
+}
+```
+
+---
+
+## Common mistakes
+
+- **Nesting `CardholderDocument` inside `CardEntry`.** It is a sibling under the same `PaymentSectionRoot`, never a child — `CardEntry` does not accept children.
+- **Passing a `documentType`, `required`, `countryCode`, or `document` prop.** None exist. Document type is fixed to CPF; requiredness and presence are always read from the selected method's validator, never authored; the typed value is not a prop at all — it flows into the shared payment draft internally.
+- **Using this component for the shopper's saved profile document.** That is a different, identity-step field this component never reads from or writes to — the two are intentionally separate, even for the same shopper.
+- **Expecting it to render outside a `PaymentSectionRoot` / `PaymentSectionController`.** It throws — the same requirement every other payment leaf (`CardEntry`, `Installments`, `SavedCards`, …) has.
+- **Treating a blank render as broken.** Most of the time, for most payment methods, this component correctly renders nothing — that is the "not displayable" state, not a bug.
+
+---
+
+## Known limitations
+
+- **CPF only.** The underlying read model carries no document-type or country signal (see this component's own spec for the full, measured deferral) — a store outside Brazil cannot get a different document type from this component today.
+- **Server-driven requiredness renders the field correctly and is also enforced at submit time — but not by this component or by `CardEntry`.** This component marks the field required when the validator says so; a required-but-blank or malformed value (whether or not required) blocks Place Order client-side, before any transaction opens, **while the selected method's validator also says the document is displayable**. That gate lives in `matter/payment/use-payment-submit-gate.ts` (T24) and is consumed by `PlaceOrder`, not by this component or by `CardEntry`'s own `validateDraft` — this component's only job stays publishing `draft.document` via `setDraftDocument`. When the *currently* selected method's validator says `documentDisplayable: false`, the gate treats `draft.document` as inert either way (fix pass, findings R1/S4/S5): there is no field on screen for the shopper to read a leftover value from or correct it in, whether that value is left over from a previously selected, displayable method or simply blank. See `specs/cardholder-document-submit-gate.md` for the gate's full contract.
+
+---
+
+## Styling
+
+`CardholderDocument`'s single root is the composed `DocumentField` particle — style it exactly like any other text field in the payment section.
+
+| Component | What you style | Plausible classes |
+|---|---|---|
+| `CardholderDocument` | The field's own label, input box, and inline error — same shape as a `Field.Root` | `flex flex-col gap-[4px] w-full` on the root; `text-[14px] font-medium text-[#1A1A1A]` for the label; `border border-[#CCCCCC] rounded-[6px] px-[12px] py-[8px] text-[14px]` for the input |
+| Placing (`data-fs-cardholder-document-placing`) | Present while an order-placement sequence is in flight (T28); the field is also `inert` and `aria-disabled` at that point | `opacity-60 cursor-not-allowed` |
+
+Styled example:
+
+```json
+{
+  "cardholder-document": {
+    "type": "CardholderDocument",
+    "props": { "label": "CPF" },
+    "style": ["flex", "flex-col", "gap-[4px]", "w-full"]
+  }
+}
+```
+
+---
+
+## Related
+
+- [[payment]] — `PaymentSectionRoot` / `PaymentMethodList`: the required ancestor and the method picker. `CardholderDocument` cannot render outside a `PaymentSectionRoot` (or `PaymentSectionController`).
+- `CardEntry` — the sibling new-card entry fields (number, holder name, expiration, CVV); a different task's deliverable, always a sibling, never a parent of this block.
+- `DocumentField` — the underlying data-agnostic particle this component wraps. Use it directly only outside the payment context, where server-driven presence/requiredness do not apply.

package/dist/docs/cart.md

@@ -3,7 +3,7 @@
 **Category:** commerce
 **Purpose:** Cart **read** layer for the store. `CartRoot` loads the active cart and exposes it (and the cart query error) to descendants, keeping them in sync as the cart changes. It is **hosted by the layout** (shared shell), wrapping the page slot — so every page, including PDPs, consumes its context without declaring it.
 
-Cart **writes** (add / remove / quantity) no longer flow through `CartRoot`. A component declares the cart methods it needs as an `actions: { cart: [...] }` selector on its definition and dispatches through the compiler-injected `$actions.cart.*` prop — the write-side mirror of `fragment` → `$data`. Cart writes are **context-free**: an add-to-cart button works on a PDP, a product card, a search result, or the header with **no `CartRoot` ancestor** (specs/actions.md, ADR-0010).
+Cart **writes** (add / remove / quantity) no longer flow through `CartRoot`. A component declares the cart methods it needs as an `actions: { cart: [...] }` selector on its definition and dispatches through the compiler-injected `$actions.cart.*` prop — the write-side mirror of `fragment` → `$data`. Cart writes are **context-free**: an add-to-cart button works on a PDP, a product card, a search result, or the header with **no `CartRoot` ancestor** (docs/storefront-core/reference-free-particle-model.md § Write side — actions, ADR-0010).
 
 This doc covers `CartRoot` — hosted in the layout, never emitted in page schemas — plus the **mini-cart footer checkout CTA** ([below](#mini-cart-footer-checkout-cta)), the composition of `CartCheckoutGuard` → (`CartTotal` + `CartGoCheckout`). The remaining cart line-item and summary particles (`CartList`, `CartItem*`, `CartCount`, `CartError`) exist in the catalog and will be documented when the full cart page enters scope.
 

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

@@ -0,0 +1,148 @@
+# ClientPreferencesFieldset
+
+**Category:** identity
+**Purpose:** The composable, one-Save write of the `ClientPreferences` entity — the same two consent flags `ClientPreferencesRoot` already writes on toggle, given a second, batched write timing. Registers itself with the enclosing `FormRoot` under the `clientPreferences` namespace and dispatches at most one `identity.clientPreferencesUpdate` when the shopper presses that form's submit. Two bound controls — newsletter, save-personal-data — compose freely inside it.
+
+---
+
+## Two write timings for one entity — read this before composing a control
+
+`ClientPreferencesRoot` and `ClientPreferencesFieldset` both read and write the same `ClientPreferences` entity (`optinNewsLetter`, `savePersonalData`). They differ only in *when* a toggle writes:
+
+- **`ClientPreferencesRoot`** (`matter/client-preferences/client-preferences.tsx`) — self-persisting. Its Controls (`NewsletterOptInControl`, `SavePersonalDataOptInControl`) write the moment the shopper toggles them. Provides context `client-preferences-toggle`.
+- **`ClientPreferencesFieldset`** (this matter) — batched. Its Controls (`ClientPreferencesNewsletterControl`, `ClientPreferencesSavePersonalDataControl`) write nothing themselves; they register with the enclosing `FormRoot` and wait for that form's submit. Provides context `client-preferences`.
+
+The two context names are deliberately different, on purpose: reusing one name for both would let an on-toggle control compile inside the batched fieldset (or vice versa) and write at the wrong moment with no warning. Composing a Root's control under the other's provider fails the build instead — the compiler's `context-constraint-violation` diagnostic names the missing context.
+
+---
+
+## Visual cues (how to identify in an image)
+
+- One or two consent checkboxes ("email me with news and offers", "save my information for next time") inside a page that also shows a **single submit button somewhere else on the page** — not one owned by this fieldset.
+- If the checkbox instead writes the instant it is toggled (no surrounding Save button gates it), that is `ClientPreferencesRoot` + `NewsletterOptInControl` / `SavePersonalDataOptInControl` — a different matter with the same visible checkboxes. The image alone cannot always distinguish the two; the surrounding form structure is the signal.
+
+---
+
+## When to use
+
+- A page that wants the two consent flags to submit together with other fieldsets (e.g. `ClientProfileFieldset`, `ShippingAddressFieldset`) behind one shared `FormRoot` submit.
+- Anywhere the store wants the write timing (batched, on submit) legible from the schema, rather than immediate.
+
+## When NOT to use
+
+- A standalone opt-in checkbox that should persist itself the instant it's toggled — use `ClientPreferencesRoot` + `NewsletterOptInControl` / `SavePersonalDataOptInControl` instead.
+- Placing `NewsletterOptInControl` or `SavePersonalDataOptInControl` inside this fieldset, or `ClientPreferencesNewsletterControl` / `ClientPreferencesSavePersonalDataControl` inside `ClientPreferencesRoot` — neither compiles; see *Two write timings* above.
+
+---
+
+## Composition
+
+```
+SessionRoot                                (required ancestor; session tri-state + canEditData)
+└── FormRoot                               (the only <form> it dispatches from; owns useForm() and the registry)
+    ├── ClientPreferencesFieldset          (data-fs-client-preferences-fieldset; registers namespace "clientPreferences")
+    │     ├── ClientPreferencesNewsletterControl
+    │     └── ClientPreferencesSavePersonalDataControl
+    ├── (any other fieldset — e.g. ClientProfileFieldset — as a sibling, same FormRoot)
+    ├── FormError
+    └── FormSubmit
+```
+
+`ClientPreferencesFieldset` renders one `Fieldset.Root` and no `<form>` of its own. Every control `requiresContext: 'client-preferences'`; a control placed outside it (or under `ClientPreferencesRoot` instead) is rejected by the context-constraint walk at build time.
+
+---
+
+## Components
+
+### ClientPreferencesFieldset
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| `skeletonCount` | number | `2` | Placeholder rows drawn while the preferences resolve. Set it to the number of controls composed. |
+| `loadingLabel` | string | `'Loading your preferences'` | Announced politely while the preferences resolve. Blank means no announcement. |
+| `loadedLabel` | string | `'Your preferences are ready'` | Announced politely once the controls mount. Blank means no announcement. |
+
+Declares `requiresContext: ['form', 'session']` (needs both a `FormRoot` and a `SessionRoot` ancestor), `providesContext: 'client-preferences'`, `actions: { identity: ['clientPreferencesUpdate'] }`, and its own fragment on `Query.clientPreferences`. Renders `Fieldset.Root` with `disabled={readOnly}`; carries `-pending` until its entity resolves, and `-readonly` when the session reports `canEditData: false`.
+
+**Loading:** the controls mount once, after the entity has resolved; until then the fieldset renders `ClientPreferencesFieldsetSkeleton` itself, in their place. Each checkbox hands its saved value to react-hook-form as a field-level `defaultValue`, re-applied on every render for as long as the checkbox stays clean — mounting before the answer arrives would seed unchecked, and a shopper who toggles it before the answer lands makes the checkbox dirty on that seed, permanently locking their saved preference out of it; even a shopper who does not toggle it sees the checkbox flash to the saved value. Resolution is the page query settling, latched: once the controls are up a later refetch never takes them down, so nothing the shopper toggled is lost.
+
+The definition also declares that same component as its `skeleton`, which is the shape the repo's skeleton-with-fragment rule asks for, but nothing reads it today: the compiler wires `skeleton` into a Suspense fallback only on the `lazy` path, and this definition is `reactive`. The generator still emits the import, so a generated page carries an unused `ClientPreferencesFieldsetSkeleton` symbol.
+
+`skeletonCount` sizes the wait. The skeleton draws two rows by default, one per consent flag in the full anatomy; a page that composes one sets `skeletonCount: 1`, or the form jumps by a row when the controls take the skeleton's place. The skeleton is `aria-hidden` — the wait is spoken instead by a polite live region the fieldset keeps mounted in both states, carrying `loadingLabel` and then `loadedLabel`, with `aria-busy` on the `<fieldset>` for as long as it lasts.
+
+### ClientPreferencesNewsletterControl / ClientPreferencesSavePersonalDataControl
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| `label` | string | `'Email me with news and offers'` / `'Save my information for next time'` | |
+
+Childless, renders `Field.Root > Field.Label > Field.Checkbox` (with the checkmark icon), the label text following. Composed children replace that default anatomy and still bind to the same field. Defaults to unchecked (opt-in, not opt-out) — a `null` saved value reads as `false`.
+
+---
+
+## Canonical schema example
+
+```json
+{
+  "session": { "type": "SessionRoot", "children": ["form"] },
+  "form": {
+    "type": "FormRoot",
+    "children": ["preferences-fieldset", "form-error", "form-submit"]
+  },
+  "preferences-fieldset": {
+    "type": "ClientPreferencesFieldset",
+    "children": ["newsletter", "save-personal-data"]
+  },
+  "newsletter": {
+    "type": "ClientPreferencesNewsletterControl",
+    "props": { "label": "Sign me up for the newsletter" },
+    "children": []
+  },
+  "save-personal-data": {
+    "type": "ClientPreferencesSavePersonalDataControl",
+    "children": []
+  },
+  "form-error": { "type": "FormError", "children": [] },
+  "form-submit": { "type": "FormSubmit", "children": [] }
+}
+```
+
+(Omitting `save-personal-data` above drops that flag entirely — its default stays untouched server-side, with no CSS hack.)
+
+---
+
+## FormClear coerces booleans
+
+`FormClear` empties every registered field to `''`. `ClientPreferencesFieldset`'s own `toPayload` runs `Boolean()` over each flag present in the namespace snapshot, so a cleared field dispatches `false` on the following submit — never the raw string `''`.
+
+---
+
+## Common mistakes
+
+- **Confusing this fieldset's controls with `NewsletterOptInControl` / `SavePersonalDataOptInControl`.** See *Two write timings* above — they require different contexts and neither compiles under the other's provider.
+- **Composing this fieldset without a `FormRoot` ancestor.** It requires both `form` and `session`; a `SessionRoot` alone is not enough.
+- **Expecting a submit button from this fieldset.** It renders none — compose `FormSubmit` once, anywhere inside the enclosing `FormRoot`.
+- **Composing `ClientPreferencesNewsletterControl` (or the other control) outside `ClientPreferencesFieldset`.** Every control `requiresContext: 'client-preferences'` and throws otherwise.
+
+---
+
+## Styling
+
+| Component | What you style | Plausible classes |
+|---|---|---|
+| `ClientPreferencesFieldset` | The `data-fs-client-preferences-fieldset` root; carries `-pending`/`-readonly` presence attributes | `flex flex-col gap-2` |
+| `ClientPreferencesFieldsetSkeleton` | `data-fs-client-preferences-fieldset-skeleton` and its `-skeleton-field` rows | `flex flex-col gap-2`, rows `h-5 rounded bg-gray-100 animate-pulse` |
+| Announcement | `data-fs-client-preferences-fieldset-announcement` reaches the live region carrying `loadingLabel`/`loadedLabel`. Hide it with a clipping technique, never `display:none` — that drops it from the accessibility tree and defeats the announcement | `sr-only` |
+| Control wrapper | `data-fs-client-preferences-fieldset-field="newsletter\|save-personal-data"` | `flex items-center gap-2` |
+
+Checkbox-level visuals (the indicator, the checked state) are owned by the composed `checkbox`/`field` particles' own swatches and are not redefined here.
+
+---
+
+## Related
+
+- [[client-preferences]] — the self-persisting Root and Controls this fieldset shares an entity with; see *Two write timings* above.
+- [[client-profile-fieldset]] — the sibling fieldset for the other entity a checkout identity step commonly needs; composes into the same `FormRoot`.
+- [[session]] — provides the identification tri-state and the required `SessionRoot` ancestor.
+- [[form]] — `FormRoot`/`FormSubmit`/`FormError`/`FormClear`/`FormReset`, the enclosing form this fieldset registers with.
+- [[field]], [[fieldset]], [[checkbox]] — the particles this matter composes directly.

package/dist/docs/client-preferences.md

@@ -50,7 +50,7 @@ SessionRoot                          (provides the session tri-state; required a
 
 ### 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`.
+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`. Provides context `client-preferences-toggle` — a different name from the batched `ClientPreferencesFieldset` (context `client-preferences`), so the two write timings for the same entity cannot compile into each other's container. See [[client-preferences-fieldset]] for the one-Save alternative.
 
 **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.
 
@@ -179,6 +179,7 @@ Styled example:
 ## Related
 
 - [[email-identification]] — sibling identity control; reads/writes `clientProfile.email` and moves the session `anonymous → identified`. Same `SessionRoot` requirement.
+- [[client-preferences-fieldset]] — the batched, one-Save alternative for the same two flags; requires a `FormRoot` and a different context (`client-preferences`), so it cannot compile alongside `NewsletterOptInControl` / `SavePersonalDataOptInControl` in the same container.
 - [[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-fieldset.md

@@ -0,0 +1,184 @@
+# ClientProfileFieldset
+
+**Category:** identity
+**Purpose:** The composable, one-Save write of the `ClientProfile` entity. Registers itself with the enclosing `FormRoot` under the `clientProfile` namespace and dispatches at most one `identity.clientProfileUpdate` when the shopper presses that form's submit. Four bound controls — first name, last name, phone, document — compose freely inside it, in any order or subset.
+
+---
+
+## Naming collision — read this before composing the phone control
+
+Two phone controls exist for the same entity, with different write timings, and their names are easy to swap by accident:
+
+- **`ClientProfileFieldsetPhoneControl`** (this matter) — the batched control. It writes nothing on its own; it registers `clientProfile.phone` with the enclosing `FormRoot` and waits for that form's submit.
+- **`ClientProfilePhoneControl`** (`matter/client-profile/client-profile.tsx`) — the on-blur control. It writes `clientProfileUpdate({ phone })` itself, the moment the field loses focus.
+
+Neither compiles inside the other's container: `ClientProfileFieldsetPhoneControl` requires `client-profile-fieldset` context (provided only by `ClientProfileFieldset`), and `ClientProfilePhoneControl` requires `client-profile` context (provided only by `ClientProfileRoot`). Composing one under the other's Root fails the build — the compiler's `context-constraint-violation` diagnostic names the missing context.
+
+---
+
+## Visual cues (how to identify in an image)
+
+- A group of shopper-profile inputs (first name, last name, a country-masked phone field, an optional tax-document field) inside a page that also shows a **single submit button somewhere else on the page**, not one owned by this fieldset.
+- No visible Save/Continue button belongs to this block by itself — the nearest `FormSubmit` (composed by `FormRoot`) is what dispatches it.
+- The image is the source of truth for layout.
+
+Use `ClientProfileFieldset` (not the standalone `ClientProfilePhoneControl`) whenever the profile fields are meant to submit together with other fieldsets on the same page, behind one shared button.
+
+---
+
+## When to use
+
+- A page that wants the shopper's profile fields (name, phone, document) to write behind a shared `FormRoot` submit, alongside other fieldsets (e.g. `ShippingAddressFieldset`, `ClientPreferencesFieldset`) — the RFC's "compose a profile write and an address write behind one submit" scenario.
+- Anywhere the store wants one entity, one action, one namespace, with the write timing (batched, on submit) legible from the schema.
+
+## When NOT to use
+
+- A single phone field that should persist itself on blur — use `ClientProfilePhoneControl` (`matter/client-profile`).
+- Editing the email — that's `EmailIdentificationControl`'s job; no control in this fieldset touches it.
+- Consent flags (newsletter, save-personal-data) — those belong to `ClientPreferencesFieldset`, a sibling namespace in the same `FormRoot`.
+
+---
+
+## Composition
+
+```
+SessionRoot                              (required ancestor; session tri-state + canEditData)
+└── FormRoot                             (the only <form> it dispatches from; owns useForm() and the registry)
+    ├── ClientProfileFieldset            (data-fs-client-profile-fieldset; registers namespace "clientProfile")
+    │     ├── ClientProfileFirstNameControl
+    │     ├── ClientProfileLastNameControl
+    │     ├── ClientProfileFieldsetPhoneControl   (country/requirement/errors as props)
+    │     └── ClientProfileDocumentControl         (renders nothing when documentType is unsupported)
+    ├── (any other fieldset — e.g. ClientPreferencesFieldset — as a sibling, same FormRoot)
+    ├── FormError
+    └── FormSubmit
+```
+
+`ClientProfileFieldset` renders one `Fieldset.Root` and no `<form>` of its own — `FormRoot` owns the only one. Every control `requiresContext: 'client-profile-fieldset'`; a control placed outside `ClientProfileFieldset` (or under `ClientProfileRoot` instead) is rejected by the context-constraint walk at build time.
+
+---
+
+## Components
+
+### ClientProfileFieldset
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| `country` | `'US' \| 'BR'` | `'US'` | Phone mask/validation country, provided to the phone control via context. |
+| `documentType` | string | — | e.g. `'CPF'`. The document control renders only when supported. |
+| `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. |
+
+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`.
+
+**Loading:** the controls mount once, after the entity has resolved; until then the fieldset renders `ClientProfileFieldsetSkeleton` itself, in their place. Each control hands its saved value to react-hook-form as a field-level `defaultValue`, re-applied on every render for as long as the field stays clean — mounting before the answer arrives would seed `''`, and a shopper who starts typing before it lands makes the field dirty on that empty seed, permanently locking their saved value out of it; even a shopper who does not type sees the field flash from `''` to the real data. Resolution is the page query settling, latched: once the controls are up a later refetch never takes them down, so nothing the shopper typed is lost.
+
+The definition also declares that same component as its `skeleton`, which is the shape the repo's skeleton-with-fragment rule asks for, but nothing reads it today: the compiler wires `skeleton` into a Suspense fallback only on the `lazy` path, and this definition is `reactive`. The generator still emits the import, so a generated page carries an unused `ClientProfileFieldsetSkeleton` symbol.
+
+`skeletonCount` sizes the wait. The skeleton draws four rows by default, one per control in the full anatomy; a page that composes three sets `skeletonCount: 3`, or the form jumps by a row when the controls take the skeleton's place. The skeleton is `aria-hidden` — the wait is spoken instead by a polite live region the fieldset keeps mounted in both states, carrying `loadingLabel` and then `loadedLabel`, with `aria-busy` on the `<fieldset>` for as long as it lasts.
+
+### ClientProfileFirstNameControl / ClientProfileLastNameControl
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| `label` | string | `'First name'` / `'Last name'` | |
+| `placeholder` | string | — | |
+
+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'` | |
+| `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'` | |
+
+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
+order and text. To switch the phone field off, omit this element from the page — `requirement` never
+governs visibility (see *Switching the phone field off* below).
+
+### ClientProfileDocumentControl
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| `label` | string | `'CPF'` | |
+| `placeholder` | string | — | |
+| `errorMessage` | string | — | |
+
+Renders nothing, and registers no field name, when the fieldset's `documentType` is unsupported. Composes
+the `DocumentField` particle. Recomposable (RFC:503): given children, they replace `DocumentField`'s
+default `Field.Label` + `DocumentFieldInput` + `Field.Error` anatomy, in any order; childless keeps
+today's order and text.
+
+---
+
+## Canonical schema example
+
+```json
+{
+  "session": { "type": "SessionRoot", "children": ["form"] },
+  "form": {
+    "type": "FormRoot",
+    "children": ["profile-fieldset", "form-error", "form-submit"]
+  },
+  "profile-fieldset": {
+    "type": "ClientProfileFieldset",
+    "props": { "country": "BR", "documentType": "CPF" },
+    "children": ["first-name", "last-name", "phone", "document"]
+  },
+  "first-name": { "type": "ClientProfileFirstNameControl", "children": [] },
+  "last-name": { "type": "ClientProfileLastNameControl", "children": [] },
+  "phone": { "type": "ClientProfileFieldsetPhoneControl", "children": [] },
+  "document": { "type": "ClientProfileDocumentControl", "children": [] },
+  "form-error": { "type": "FormError", "children": [] },
+  "form-submit": { "type": "FormSubmit", "children": [] }
+}
+```
+
+Adding a second fieldset (e.g. `ClientPreferencesFieldset`) as another child of `form`, alongside `profile-fieldset`, is what puts both entities behind the one `form-submit` button — the RFC's core composition.
+
+---
+
+## Switching the phone field off
+
+`requirement` accepts only `'mandatory'` and `'optional'`, and left out it raises nothing — it governs required validation, never visibility. There is no prop value that hides the phone field: a store that does not want it omits `ClientProfileFieldsetPhoneControl` from the page entirely, which also means `clientProfile.phone` is never registered and can never block a submit. A stale `page.json` still carrying `"requirement": "hidden"` fails the generated store's own `next build` with a `TS2322` type error naming the attribute — it is not a schema-validation failure, and no diagnostic fires at `sukima build`.
+
+No control in this fieldset ever puts `required` (or any other `RegisterOptions` key react-hook-form evaluates before `validate`) into its field contract, so the fieldset declares no baseline at all. Requiredness on the phone control rides only on its own `requirement` prop, which `PhoneField` passes to `useBoundField` as a raise: mandatory-and-empty means blocked, optional means clean. Because the baseline is empty here, the raise is the whole of it — where a fieldset does declare a baseline, `'optional'` could not lower it. A first-name or last-name control can never be required today — only the phone control has a `requirement` prop, because only `PhoneField` implements one.
+
+---
+
+## Common mistakes
+
+- **Confusing `ClientProfileFieldsetPhoneControl` with `ClientProfilePhoneControl`.** See *Naming collision* above — they require different contexts and neither compiles under the other's Root.
+- **Composing this fieldset without a `FormRoot` ancestor.** It requires both `form` and `session`; a `SessionRoot` alone is not enough.
+- **Expecting a submit button from this fieldset.** It renders none — compose `FormSubmit` once, anywhere inside the enclosing `FormRoot`.
+- **Adding a `required` prop to a text control.** There is none — the fieldset never blocks a submit on requiredness for a field it did not choose to gate. See *Switching the phone field off*.
+- **Setting `requirement="hidden"` to hide the phone field.** The value does not exist; TypeScript rejects it and a generated store fails `next build`. Omit `ClientProfileFieldsetPhoneControl` from the page instead.
+- **Composing `ClientProfileFirstNameControl` (or any control here) outside `ClientProfileFieldset`.** Every control `requiresContext: 'client-profile-fieldset'` and throws otherwise.
+
+---
+
+## Styling
+
+| Component | What you style | Plausible classes |
+|---|---|---|
+| `ClientProfileFieldset` | The `data-fs-client-profile-fieldset` root; carries `-pending`/`-readonly` presence attributes | `flex flex-col gap-4` |
+| Control wrapper | `data-fs-client-profile-fieldset-field="first-name\|last-name\|phone\|document"` | `flex flex-col gap-1` |
+| `ClientProfileFieldsetSkeleton` | `data-fs-client-profile-fieldset-skeleton` and its `-skeleton-field` rows | `flex flex-col gap-4`, rows `h-11 rounded-lg bg-gray-100 animate-pulse` |
+| Announcement | `data-fs-client-profile-fieldset-announcement` reaches the live region carrying `loadingLabel`/`loadedLabel`. Hide it with a clipping technique, never `display:none` — that drops it from the accessibility tree and defeats the announcement | `sr-only` |
+
+Field-level visuals (borders, focus rings, error color) are owned by the composed particles' own swatches (`field`, `phone-field`, `document-field`) and are not redefined here.
+
+---
+
+## Related
+
+- [[client-profile]] — the standalone, on-blur phone binding; see *Naming collision* above.
+- [[client-preferences-fieldset]] — the sibling fieldset for the other entity a checkout identity step commonly needs; composes into the same `FormRoot`.
+- [[session]] — provides the identification tri-state and the required `SessionRoot` ancestor.
+- [[form]] — `FormRoot`/`FormSubmit`/`FormError`/`FormClear`/`FormReset`, the enclosing form this fieldset registers with.
+- [[phone-field]], [[document-field]], [[field]], [[fieldset]] — the particles this matter composes directly.

package/dist/docs/client-profile.md

@@ -58,7 +58,7 @@ Binds the reusable `PhoneField` particle to the profile. Reads the saved phone f
 |------|------|---------|-------|
 | `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. |
+| `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). |

package/dist/docs/document-field.md

@@ -28,15 +28,24 @@ If the image shows a checkout identification step with a tax-document field, use
 
 ## Composition
 
-`DocumentField` is a single leaf particle. Internally it renders:
+`DocumentField` provides `document-field` context and, childless, renders:
 
 ```
-DocumentField              (data-fs-document-field + inherited data-fs-field-root)
+DocumentField              (data-fs-document-field + data-fs-field-root)
 ├── Field.Label            (data-fs-field-label; the `label` prop)
-├── Field.Control          (data-fs-field-control; native <input inputmode="numeric">)
+├── DocumentFieldInput     (data-fs-field-control; native <input inputmode="numeric">)
 └── Field.Error            (data-fs-field-error; the `errorMessage`, shown when invalid)
 ```
 
+**Recomposable (RFC:503):** given children, `DocumentField` renders them in place of the three parts
+above, in any order. `DocumentFieldInput` is the one catalogued part that requires `document-field`
+context — it reads the masked value, the composed ref and the particle's own `onChange`/`onBlur` from
+`DocumentField` itself, so it must sit inside it; it carries the same `data-fs-field-control` hook the
+default anatomy always used, so a recomposed page keeps its existing CSS. A composed childless
+`Field.Label` / `Field.Error` (the generic parts from the `field` particle) works exactly as it does under
+any other bound Control; a composed generic `Field.Control` instead re-registers the field with
+react-hook-form and loses the mask — unsupported, the RFC's named double-binder hole.
+
 ---
 
 ## Props
@@ -52,9 +61,11 @@ DocumentField              (data-fs-document-field + inherited data-fs-field-roo
 | `label` | string | — | Accessible label. |
 | `placeholder` | string | — | Input placeholder. |
 | `disabled` | boolean | `false` | Disables the input (e.g. while a write is in flight). |
-| `required` | boolean | `false` | CPF is Optional by Recommendation — default false (unlike email). |
+| `requirement` | `'mandatory' \| 'optional'` | — | Raises the field to required, announced as `aria-required` (never the native attribute). Unset is no opinion, which is what keeps CPF Optional by Recommendation, unlike email. Bound to a fieldset whose rule already says required, `'optional'` does not lower it. |
 | `name` | string | `'document'` | Field/input name. |
 | `documentType` | `'CPF'` | `'CPF'` | Selects the mask + validator + digit-only input mode. |
+| `ref` | `Ref<HTMLInputElement>` | — | Lands on the `<input>` `Field.Control` renders — **not on the wrapper `<div>`, as it did before** (a deliberate, source-breaking change). Composed with react-hook-form's own ref on the bound path — a caller ref and react-hook-form's ref are both honoured. |
+| `children` | `ReactNode` | — | Given, replaces the default `Field.Label` + `DocumentFieldInput` + `Field.Error` anatomy, in any order (RFC:503). |
 
 **Masking:** applied progressively on every change; input is never blocked. Digit-only masks (CPF) strip non-digits and hint `inputMode="numeric"`.
 
@@ -62,6 +73,49 @@ DocumentField              (data-fs-document-field + inherited data-fs-field-roo
 
 ---
 
+## Bound behaviour
+
+`DocumentField` reads the field contract through `useField()` and binds through `useController` when both
+a field contract (`FieldBinding`) and a react-hook-form `FormProvider` are present above it; otherwise it
+runs the plain, unbound behaviour documented above, unaltered.
+
+- **What the contract supplies**: `label` and `placeholder`, when the particle's own prop is omitted (an
+  explicit prop always wins); `defaultValue`, seeded into `useController`; and `rule`, merged with the
+  particle's own check-digit validator (below).
+- **What stays the particle's**: the CPF mask, `documentType`, and the `errorMessage` copy.
+- **Single binder, real contract for the read-only parts (RFC:503)**: the composite remains the sole
+  binder for its field — `useController` is called once, here. Its default (and a recomposed) anatomy's
+  input is `DocumentFieldInput`, which renders the raw Base UI `Field.Control` directly rather than this
+  package's own bound-aware wrapper, so it never independently re-registers the name and overwrites the
+  composite's masked value. `Field.Label` / `Field.Error` composed by an author, by contrast, do read the
+  real (non-empty) re-provided contract — carrying the *resolved* `name`/`label`/`placeholder` — so a
+  composed childless `Field.Label` renders real text; a composed childless `Field.Error` renders
+  react-hook-form's real message only when one exists — when `errorMessage` is unset the check-digit
+  validator reports failure with a bare `false`, react-hook-form's message is empty, and `Field.Error`
+  renders nothing, exactly like the default anatomy below. An earlier design (`FieldContractBoundary`)
+  pushed an empty contract instead, which is why a composed childless label used to render nothing; that
+  mechanism is gone.
+- **Value shape stored in react-hook-form**: the same **masked** string the unbound particle emits
+  through `onValueChange` (e.g. `111.444.777-35`), matching the asymmetry with `PhoneField`'s unmasked
+  storage — pre-existing and preserved on purpose.
+- **Validation**: when the contract's `rule` carries no `validate` of its own, the composite installs its
+  own check-digit validator as the rule's `validate`, returning `errorMessage` on failure (or a bare
+  `false` when `errorMessage` is unset) — reproducing today's behaviour exactly: the field goes invalid,
+  and inline text renders only when `errorMessage` is supplied. A contract-supplied `validate` always wins
+  over the particle's own. An empty value still passes (today's optional-field rule).
+- **Focus**: the `ref` lands on the `<input>` `DocumentFieldInput` renders, so a failed submit moves focus
+  to it — in the default anatomy and in a recomposed one, since the composed ref threads through
+  regardless of where the author places the part.
+- **Explicit `invalid`/`errorMessage` props still surface** on the default (childless) anatomy
+  unconditionally — it renders the raw Base UI `Field.Label`/`Field.Error` primitives directly, so it
+  never gates on react-hook-form's own error state the way a composed childless `Field.Error` intentionally
+  does (above).
+- `DocumentFieldDefinition` gains no `requiresContext` — the particle stays placeable outside any form. It
+  does declare `providesContext: 'document-field'` — that is what makes `DocumentFieldInput` a legal
+  child.
+
+---
+
 ## Accessibility
 
 The label is associated with the input and the error is linked via `aria-describedby` automatically by the Base UI `Field` primitive (WCAG 2.1 AA). Standard text-input keyboard editing; masking/validation never blocks typing.