@vtex/faststore 0.0.10 → 0.0.11

package/dist/docs/sign-in-disclosure.md

@@ -0,0 +1,176 @@
+# SignInDisclosure (Root + Trigger + ModalPanel)
+
+**Category:** identity
+**Purpose:** Opens the sign-in surface in place, as a modal, and closes it by itself when the shopper signs in. `SignInDisclosureRoot` owns whether the modal is showing and shares it as the `sign-in-disclosure` context; it renders no element of its own. `SignInDisclosureTrigger` is the login button — any number may be composed, and every one opens the same panel. `SignInModalPanel` is the modal: a labelled dialog with a close control, holding the sign-in parts as its children. None of the three reads data; the account configuration reaches them through `SignInRoot`.
+
+---
+
+## Visual cues (how to identify in an image)
+
+- A **login button** ("Entrar", "Sign in") in a header, or beside the step that needs an account, that does not navigate away — this is `SignInDisclosureTrigger`. The same button may appear in more than one place.
+- A **centered card over a dimmed page**, titled "Entrar" or similar, with a close control ("Fechar", an X) in its top corner and the email field and a code or password step inside — this is `SignInModalPanel` open.
+- A **grey rounded bar** where the login button will be, shown briefly while the account configuration loads — the trigger's skeleton.
+- **No login button at all** for a signed-in shopper, and none in a store whose account enables no sign-in method.
+
+---
+
+## When to use
+
+- A login button that must be available from more than one point of a page or layout, opening sign-in over the current step instead of navigating to `/login`.
+- A sign-in surface whose modal should return the shopper to the step they were on, and close without a click when the session becomes signed in.
+
+## When NOT to use
+
+- A plain link to the `/login` page → `AccountEntryPoint`, which adapts to the session and navigates.
+- A modal for anything other than sign-in → compose the `Dialog` particles. A merchant-composed `DialogRoot` cannot be told to close when the shopper signs in (see Common mistakes).
+- A page with no `SignInRoot` and no `SessionRoot` above → `SignInDisclosureRoot` throws until both are present.
+
+---
+
+## Composition
+
+```
+SessionRoot                                  (required ancestor of SignInRoot)
+└── SignInRoot                               (required ancestor: reads the account's enabled methods once)
+    └── SignInDisclosureRoot                 (renders no element; owns the open state)
+        ├── SignInDisclosureTrigger          (any number, anywhere below the Root)
+        ├── SignInDisclosureTrigger
+        └── SignInModalPanel                 (exactly one; portalled, kept mounted while closed)
+            ├── SignInEmailControl
+            ├── SignInMethodSwitch / SignInMethodOption
+            └── AccessCodeSignInRoot / SignInForm …
+```
+
+Hosted in a layout, the Root wraps the header **and** the `Slot`: a page then composes a `SignInDisclosureTrigger` of its own and no root, and the layout's panel answers it.
+
+`SignInDisclosureRoot` **must** have a `SignInRoot` ancestor — `useSignIn() must be used inside a <SignInRoot> subtree.` otherwise. `SignInDisclosureTrigger` and `SignInModalPanel` **must** be descendants of `SignInDisclosureRoot` — `useSignInDisclosure() must be used inside a <SignInDisclosureRoot> subtree.` otherwise (runtime guards, not compiler-checked beyond context ancestry).
+
+---
+
+## Props
+
+### `SignInDisclosureRoot`
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| `children` | `ReactNode` | — | Always rendered, in every session state and for every account configuration. |
+
+No schema props. It declares no fragment, no `fetchStrategy` and no `$data`.
+
+### `SignInDisclosureTrigger`
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| `label` | string | — | The button's text. |
+
+Extends `ComponentPropsWithRef<'button'>`. The rendered element is always a `<button type="button">`; a `type` passed in is overridden so the trigger never submits an enclosing form. A caller's `onClick` runs first and may call `preventDefault()` to keep the panel shut.
+
+### `SignInModalPanel`
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| `title` | string | — | The dialog's accessible name, drawn in the header. Author it: without it the dialog has no name. |
+| `closeLabel` | string | — | The close control's text and accessible name. |
+| `signedInFocusLabel` | string | — | Written into the focus anchor when the session becomes signed in while the page is open, so a screen reader announces that the modal closed because sign-in succeeded. A shopper who was already signed in when the page loaded is told nothing. The anchor is clipped, so the text is never drawn. No default. |
+
+Extends `ComponentPropsWithRef<'div'>`, spread onto the dialog element, except `hidden`, `tabIndex`, `aria-label` and `aria-labelledby`: the panel owns those (closed means `hidden`; the title names the dialog), so the type omits them and a value that gets past it is discarded. There is **no** `open`, `defaultOpen` or `onOpenChange`: whether the panel is showing is state, never a prop.
+
+No prop in this family carries a default: copy is the merchant's own message, so no English fallback ships.
+
+---
+
+## Behavior
+
+- **One panel, many triggers.** Each trigger sets the one open state; the panel needs no trigger at all (`useSignInDisclosure().setOpen(true)` opens it).
+- **Resolved before enabled.** The trigger checks `useSignIn().resolved` before it reads a flag. While the account configuration has not arrived it draws a silent placeholder (`data-fs-sign-in-disclosure-trigger-skeleton`, `aria-hidden="true"`, no role, not focusable); once resolved with no method enabled it renders nothing.
+- **Signed in renders no trigger.** For a `loggedIn` session the trigger renders nothing — no button and no placeholder. The panel stays in the document, closed.
+- **The close is derived.** The published `open` is `localOpen && state !== 'loggedIn'`, so no committed render shows an open panel to a signed-in shopper. The panel closes the moment the session reaches `loggedIn`, with no event and no prop. `setOpen(true)` made while signed in does nothing, and a later sign-out does not reopen the panel.
+- **Kept mounted.** The panel renders Base UI's `Dialog` with the portal kept mounted, so its children are mounted before the first open and survive every close: a shopper who steps out to read an emailed code returns to the same access-code step with the same token, and the email they typed. A typed password is the exception: `SignInForm` empties it, and its errors, when the panel closes, so a credential the shopper never submitted does not wait in the hidden subtree for the next person at the page. Closed, the dialog element carries `hidden`, which takes it out of the accessibility tree and the tab order.
+- **Dismissal.** Escape, a press on the overlay and the close control each close it. Page scroll is locked and focus is trapped while it is open.
+- **Focus.** Opening moves focus into the panel. A shopper-driven close returns focus to the trigger that opened it. A self-close removes that trigger, so focus goes to the panel's in-flow focus anchor (`role="status"`, `tabindex="-1"`, empty until the session changes while the page is open) instead of `document.body`, and the anchor then carries `signedInFocusLabel`. The anchor sits in the layout's flow, outside the panel, so the panel's `style` does not reach it: it ships clipped (still in the accessibility tree, never drawn).
+- **No actions.** Nothing in this family dispatches a mutation. The session change that closes the panel is produced by the method components inside it.
+
+### Hooks
+
+| Hook | Notes |
+|------|-------|
+| `useSignInDisclosure()` | `{ open, setOpen }`. Throws outside a `SignInDisclosureRoot`. |
+
+---
+
+## `data-fs-*` hooks
+
+| Attribute | Element | Meaning |
+|---|---|---|
+| `data-fs-sign-in-disclosure-trigger` | trigger button | The login button is offered |
+| `data-fs-sign-in-disclosure-trigger-skeleton` | trigger placeholder | The account configuration has not arrived |
+| `data-fs-sign-in-state` | trigger and placeholder | `ready` or `loading` |
+| `data-fs-sign-in-modal-panel` | dialog element | The panel. Base UI adds `data-open` or `data-closed`; closed also carries `hidden` |
+| `data-fs-sign-in-modal-backdrop` | overlay | The overlay behind the panel |
+| `data-fs-sign-in-modal-header` | header row | Holds the title and the close control |
+| `data-fs-sign-in-modal-title` | heading | The dialog's accessible name |
+| `data-fs-sign-in-modal-close` | close button | Closes the panel |
+| `data-fs-sign-in-modal-focus-anchor` | in-flow div | Where focus lands after a self-close; clipped, empty until the shopper signs in while the page is open |
+
+The panel carries no `data-fs-dialog-*` hooks: it renders Base UI's `Dialog` directly and styles through its own hooks. Position the panel through the `style` array on `SignInModalPanel` (it lands on the dialog element); the overlay is a separate portalled sibling.
+
+---
+
+## Canonical schema example
+
+A layout hosting the surface, with a header trigger and the panel; a page adds its own trigger and no root:
+
+```json
+{
+  "type": "SessionRoot",
+  "children": [
+    {
+      "type": "SignInRoot",
+      "children": [
+        {
+          "type": "SignInDisclosureRoot",
+          "children": [
+            { "type": "Container", "children": [
+              { "type": "SignInDisclosureTrigger", "props": { "label": "entrar" } },
+              { "type": "Slot" }
+            ] },
+            {
+              "type": "SignInModalPanel",
+              "props": { "title": "Entrar", "closeLabel": "Fechar", "signedInFocusLabel": "Você entrou na sua conta." },
+              "children": [
+                { "type": "SignInEmailControl", "props": { "label": "e-mail" } },
+                { "type": "AccessCodeSignInRoot", "children": [
+                  { "type": "AccessCodeRequestControl", "props": { "label": "solicitar código de acesso" } },
+                  { "type": "AccessCodeValidateControl", "props": { "label": "código recebido por e-mail", "submitLabel": "entrar" } }
+                ] }
+              ]
+            }
+          ]
+        }
+      ]
+    }
+  ]
+}
+```
+
+---
+
+## Common mistakes
+
+- **Composing a bare `DialogRoot` around the sign-in parts.** A merchant-composed `DialogRoot` cannot close itself: schema composition wires no callbacks, so after a successful sign-in it sits open over a panel whose every part has already rendered nothing. Use `SignInModalPanel`, which closes on the session change.
+- **Omitting `title`.** The dialog is named by its title and by nothing else; without it the dialog has no accessible name.
+- **Omitting `closeLabel`.** No default ships, so the close control then has no accessible name. Escape and an overlay press still dismiss the panel, but a screen-reader shopper meets an unnamed button inside a focus-trapped dialog. Author it.
+- **Passing `hidden`, `tabIndex`, `aria-label` or `aria-labelledby` to the panel.** They are discarded: the panel keeps itself hidden while closed and named by its title.
+- **Composing a second `SignInModalPanel` under one Root.** Both would open. Context ancestry is validated, arity is not.
+- **Composing a trigger or the panel outside `SignInDisclosureRoot`.** Both throw, naming the Root to add.
+- **Expecting an `open` prop.** There is none, by design: the open state is not authorable and cannot be faked.
+
+---
+
+## Related
+
+- [[sign-in]] — provides the required `SignInRoot` ancestor; the trigger gates on its `resolved` and `anyMethodEnabled`.
+- [[session]] — provides the `loggedIn` state that closes the panel and removes the triggers.
+- [[access-code-sign-in]] — the access-code method family, composed inside the panel.
+- [[sign-in-form]] — the password method family, composed inside the panel.
+- [[account-entry-point]] — the header link that navigates to `/login`, which this family does not replace.

package/dist/docs/sign-in-form.md

@@ -1,28 +1,29 @@
 # SignInForm
 
 **Category:** identity
-**Purpose:** Composes `EmailField` + `PasswordField` under one submit and dispatches `$actions.session.loginWithPassword({ email, password })`. It pre-fills the email from `clientProfile.email`, blocks the dispatch on client-side email/password validation, maps the resolved `userErrors` to one inline form-level message, and self-gates to `null` once `useSession()` reports `loggedIn`. It must sit inside a `SessionRoot`.
+**Purpose:** The password method of the sign-in surface. It sits under `SignInRoot`, which reads the account's enabled methods once and owns the one email draft every method shares; `SignInEmailControl` is the email field. `SignInForm` is a password field and a submit that dispatches `$actions.session.loginWithPassword({ email, password })` with that shared draft. It renders nothing until the account configuration has arrived, when the account disables passwords, while another sign-in method is the active one, and once `useSession()` reports `loggedIn`. It renders no email field of its own.
 
 ---
 
 ## Visual cues (how to identify in an image)
 
-- A **combined email + password login form** inside a checkout User Identity / sign-in step, with a single submit button (e.g. "Sign In").
-- Distinct from `EmailIdentificationControl` (email-only, no password, no submit button) — `SignInForm` always has both fields and one submit.
-- A form-level error banner (`role="alert"`) below the fields, separate from any per-field inline error — that banner is this component's own `data-fs-sign-in-form-error` region, not a page-level failure gate.
+- A **password input with a show/hide toggle and one submit button** (e.g. "Sign In"), sitting under the sign-in step's email field — the email field is `SignInEmailControl`, not part of this component.
+- Distinct from `EmailIdentificationControl` (email-only, no password, no submit button) and from `AccessCodeSignIn.*` (an emailed one-time code, no password).
+- A rejected password shows its message **under the password input**; any other failure shows a form-level banner (`role="alert"`) below it — that banner is this component's own `data-fs-sign-in-form-error` region, not a page-level failure gate.
 
-Use `SignInForm` (not a bare `EmailField` + `PasswordField` pair) whenever the shopper must authenticate with an existing password.
+Use `SignInForm` whenever the shopper must authenticate with an existing password.
 
 ---
 
 ## When to use
 
-- The password sign-in step of the checkout User Identity flow, for a shopper who is `anonymous` or `identified` but not yet `loggedIn`.
-- Anywhere a combined email+password credential submit is needed that writes through the `session` action namespace.
+- The password sign-in step of the checkout User Identity flow, for a shopper who is `anonymous` or `identified` but not yet `loggedIn`, as one of the sign-in methods composed under a `SignInRoot`.
+- The signed-out branch of a page that must follow the account's configuration (for example My Account), composed under a `SignInRoot` like any other method.
 
 ## When NOT to use
 
-- Passwordless / access-code (two-step) sign-in → a separate component (FSPG-872), not a variant of this one.
+- Passwordless / access-code (two-step) sign-in → `AccessCodeSignIn.*`, a separate family composed beside this one under the same `SignInRoot`.
+- Rendering outside a `SignInRoot` → there is no standalone use; the page fails the build (see Composition).
 - Email-only pre-fill/identification with no password → use `EmailIdentificationControl`.
 - Logged-in summary, sign-out, or profile editing → out of scope (FSPG-867); `SignInForm` only self-gates to `null` once logged in, it renders no logged-in UI.
 - Password recovery ("Forgot password?") → out of scope for this component; deferred.
@@ -32,15 +33,18 @@ Use `SignInForm` (not a bare `EmailField` + `PasswordField` pair) whenever the s
 ## Composition
 
 ```
-SessionRoot                (provides the session tri-state; required ancestor)
-└── SignInForm              (data-fs-sign-in-form)
-    ├── EmailField          (pre-filled from clientProfile.email; own inline format error)
-    ├── PasswordField       (presence-only validation owned by SignInForm)
-    ├── form-level error    (data-fs-sign-in-form-error, role="alert")
-    └── Button (submit)     (data-fs-sign-in-form-submit)
+SessionRoot                       (provides the session tri-state; required ancestor of SignInRoot)
+└── SignInRoot                    (reads the account once; owns the shared email draft and the active method; required ancestor)
+    ├── SignInEmailControl        (the one email field, for every method)
+    └── SignInForm                (data-fs-sign-in-form; renders only while password is the active, enabled, resolved method)
+        ├── PasswordField         (presence check owned by SignInForm; carries INVALID_CREDENTIALS)
+        ├── form-level error      (data-fs-sign-in-form-error, role="alert")
+        └── Button (submit)       (data-fs-sign-in-form-submit)
 ```
 
-`SignInForm` **must** have a `SessionRoot` ancestor — `useSession()` throws otherwise.
+`SignInForm` **must** be a descendant of `SignInRoot`, which itself needs a `SessionRoot` ancestor. A schema that composes `SignInForm` without a `SignInRoot` ancestor fails the **build**: `sukima generate` rejects it with the diagnostic code `context-constraint-violation`, because the matter `requiresContext: 'sign-in'`. Rendering it directly in TSX (a story or a test) with no `SignInRoot` throws `useSignIn() must be used inside a <SignInRoot> subtree.`
+
+`SignInEmailControl` sits **above** `SignInForm`, as its sibling, so the email stays anchored while the method below it swaps. The compiler does not require it, but a page that omits it has no email input anywhere and the submit stays disabled. To offer another method beside this one, compose `SignInMethodSwitch` or `SignInMethodOption` under the same Root; see [[sign-in]] and [[access-code-sign-in]].
 
 ---
 
@@ -48,33 +52,44 @@ SessionRoot                (provides the session tri-state; required ancestor)
 
 | Prop | Type | Default | Notes |
 |------|------|---------|-------|
-| `emailLabel` / `emailPlaceholder` | string | `'Email'` / `'you@example.com'` | Passed to `EmailField`. |
-| `passwordLabel` / `passwordPlaceholder` | string | `'Password'` / `''` | Passed to `PasswordField`. |
-| `showPasswordLabel` / `hidePasswordLabel` | string | `'Show password'` / `'Hide password'` | Passed to `PasswordField`'s reveal toggle. |
-| `submitLabel` | string | `'Sign In'` | Submit button text. |
-| `invalidEmailMessage` | string | `'Enter a valid email address.'` | Shown on `EmailField` when the pre-submit format check fails. |
-| `passwordRequiredMessage` | string | `'Enter your password.'` | Shown on `PasswordField` when submitted empty. |
-| `invalidCredentialsMessage` | string | `'Incorrect email or password. Please try again.'` | Form-level error for `INVALID_CREDENTIALS`. |
-| `blockedMessage` | string | `'This account has been blocked. Please contact support.'` | Form-level error for `BLOCKED`. |
-| `networkErrorMessage` | string | `'Unable to complete the request. Please try again.'` | Form-level error for the synthetic `NETWORK_ERROR`. |
-| `genericErrorMessage` | string | `'Unable to sign in. Please try again.'` | Fallback for any other/unrecognized `SessionErrorCode`. |
-| `$data` | `{ email?: string \| null } \| null` | injected | `clientProfile` slice from the reactive runtime. Not authored in schema. |
+| `passwordPlaceholder` | string | `''` | Passed to `PasswordField`. |
+| `$content` | `ContentValue<typeof SignInFormContent>` | — | The labels and error messages below. |
 | `$actions` | injected | — | Carries `session.loginWithPassword` (compiler-injected). |
 
-**Data:** declares a colocated `fragment SignInFormData on Query { clientProfile { __typename id email } }` with `fetchStrategy: 'reactive'` — the minimal slice this matter owns (only `email`, for pre-fill).
+Content type `sign-in-form`. Every field is a message with no arguments; an unauthored one renders empty and logs `message.missing`.
+
+| Content field | Source (en) | Notes |
+|---|---|---|
+| `passwordLabel` | Password | `PasswordField` label. |
+| `showPasswordLabel` / `hidePasswordLabel` | Show password / Hide password | `PasswordField`'s reveal toggle; `SignInForm` formats them and passes the strings down. |
+| `submitLabel` | Sign In | Submit button text. |
+| `passwordRequiredMessage` | Enter your password. | Shown on `PasswordField` when submitted empty. |
+| `invalidCredentialsMessage` | Incorrect email or password. Please try again. | Shown on `PasswordField` for `INVALID_CREDENTIALS`. Names neither half, because the platform returns the same code for a wrong password and an unknown account. |
+| `blockedMessage` | Access to this account is temporarily blocked. Please try again later. | Form-level error for `BLOCKED`. |
+| `networkErrorMessage` | Unable to complete the request. Please try again. | Form-level error for the synthetic `NETWORK_ERROR`. |
+| `genericErrorMessage` | Unable to sign in. Please try again. | Form-level fallback for any other/unrecognized `SessionErrorCode`. |
+
+The email's label, placeholder and invalid-format message are `SignInEmailControl`'s props, not this component's. The component renders no email field.
+
+**Data:** none. The matter declares **no fragment** and no `fetchStrategy`, and takes no data prop: it reads the `sign-in` context through `useSignIn()` (`email`, `method`, `passwordEnabled`, `resolved`) and the session tri-state through `useSession()`. It never reads which methods the account enables itself — `SignInRoot` is the one reader.
+
+**Write:** declares `actions: { session: ['loginWithPassword'] }`. The write is **pessimistic/async** — it awaits the resolved `userErrors` before doing anything. While in flight, the password input and submit button are disabled and the root carries `data-fs-sign-in-form-pending`, so a checkout-CTA guard can block on it the same way it does for `EmailIdentificationControl`. A second submit that arrives while one is in flight is ignored, even in the same event batch. The shared email input is not disabled.
 
-**Write:** declares `actions: { session: ['loginWithPassword'] }`. The write is **pessimistic/async** — it awaits the resolved `userErrors` before doing anything. While in flight, the fields and submit button are disabled and the root carries `data-fs-sign-in-form-pending`, so a checkout-CTA guard can block on it the same way it does for `EmailIdentificationControl`.
+**Gate:** renders its form only when **all four** hold: `useSession().state !== 'loggedIn'`, and, from `useSignIn()`, `resolved`, `passwordEnabled` and `method === 'password'`. Otherwise it returns `null` rather than unmounting, so a half-typed password survives a method switch.
 
 ---
 
 ## Behavior
 
-- **Pre-fill:** the email field shows `clientProfile.email` (empty when unset) and remains editable; it re-syncs if the pre-fill resolves or changes later.
-- **Client-side validation:** an invalid email format or an empty password blocks the dispatch entirely — no network round trip, the offending field shows its own inline error.
-- **Happy path:** dispatches `$actions.session.loginWithPassword({ email, password })` exactly once; on `userErrors: []`, no local "logged in" flag is set — the next render reads the already-flipped `useSession().state` and self-gates to `null`.
-- **Login errors:** a non-empty `userErrors[0]` maps through `mapSessionErrorMessage` to one of `invalidCredentialsMessage` / `blockedMessage` / `networkErrorMessage` / `genericErrorMessage`, rendered in the single `data-fs-sign-in-form-error` region — structurally distinct from any ancestor `UNAUTHORIZED` gate.
-- **Retry:** after a failed attempt the password is cleared (credential hygiene) but the email is kept; a fresh submit clears the prior form-level error.
-- **Self-gating:** renders the form for `anonymous`/`identified`, returns `null` for `loggedIn` — derived from `useSession()` on every render, never stored locally.
+- **Gating:** see the four conditions above. A store whose account disables passwords never shows the form, and neither does one whose configuration has not arrived yet; once it arrives the form appears. With both methods enabled the access code is the default, and the form appears when the shopper selects the password method.
+- **Shared email:** the dispatch's `email` is the `SignInRoot` draft, read at submit time and trimmed. The submit is disabled while the draft is not a valid address, and while a dispatch is in flight.
+- **Presence check:** submitting with an empty password blocks the dispatch and shows `passwordRequiredMessage` on the `PasswordField`; typing clears it.
+- **Happy path:** dispatches `$actions.session.loginWithPassword({ email, password })` exactly once; on `userErrors: []`, no local "logged in" flag is set — the next render reads the already-flipped `useSession().state` and returns `null`.
+- **Login errors:** the first `userErrors` entry maps through `mapSessionErrorField` to the message that words it. `INVALID_CREDENTIALS` renders as the `PasswordField`'s inline error (the field is marked invalid); `BLOCKED`, `NETWORK_ERROR` and any other code render in the single `data-fs-sign-in-form-error` region — structurally distinct from any ancestor `UNAUTHORIZED` gate.
+- **Retry:** once a dispatch has been sent the password is cleared, accepted or rejected (credential hygiene), but the shared email is kept; a fresh submit clears the prior errors, and an edit made in `SignInEmailControl` reaches the next dispatch.
+- **Credential pair:** the password input carries `autocomplete="current-password"` and `SignInEmailControl`'s input carries `autocomplete="username"` by default, so a browser that resolves the username hint document-wide saves and fills the address and the password as one credential. The pairing is **not** complete: `SignInRoot` renders no form element, so the email input is a sibling of `<form data-fs-sign-in-form>` rather than inside it, and a browser that scopes the username search to the form owner still saves the credential against no username. Closing that needs a `form=` association the components do not set yet. Overriding `autoComplete` on `SignInEmailControl` breaks what pairing there is.
+- **Session change:** when the session reaches `loggedIn` the password and both error states are cleared, so a credential never outlives the session it was typed for.
+- **Panel close:** inside a `SignInModalPanel`, closing the panel clears the password and both error states the same way. The panel keeps its children mounted, so without this an unsubmitted password would sit in the hidden subtree for the life of the page; the shared email stays. Outside a disclosure nothing closes, so nothing is cleared.
 
 ---
 
@@ -85,13 +100,25 @@ SessionRoot                (provides the session tri-state; required ancestor)
   "type": "SessionRoot",
   "children": [
     {
-      "type": "SignInForm",
-      "props": {
-        "emailLabel": "Email",
-        "passwordLabel": "Password",
-        "submitLabel": "Sign In",
-        "invalidCredentialsMessage": "Incorrect email or password. Please try again."
-      }
+      "type": "SignInRoot",
+      "children": [
+        { "type": "SignInEmailControl", "props": { "label": "Email", "placeholder": "you@example.com" } },
+        {
+          "type": "SignInForm",
+          "props": {
+            "passwordLabel": "Password",
+            "showPasswordLabel": "Show password",
+            "hidePasswordLabel": "Hide password",
+            "submitLabel": "Sign In",
+            "passwordRequiredMessage": "Enter your password.",
+            "invalidCredentialsMessage": "Incorrect email or password. Please try again.",
+            "blockedMessage": "Access to this account is temporarily blocked. Please try again later.",
+            "networkErrorMessage": "Unable to complete the request. Please try again.",
+            "genericErrorMessage": "Unable to sign in. Please try again."
+          }
+        },
+        { "type": "SignInMethodOption", "props": { "method": "accessCode", "label": "Use a code instead" } }
+      ]
     }
   ]
 }
@@ -101,17 +128,21 @@ SessionRoot                (provides the session tri-state; required ancestor)
 
 ## Common mistakes
 
-- **Rendering it outside `SessionRoot`.** `useSession()` throws; every identity page must host a `SessionRoot`.
+- **Composing it without a `SignInRoot` ancestor.** The build fails with `context-constraint-violation`; the Root is also what makes the form follow the account's configuration.
+- **Composing it without a `SignInEmailControl`.** The form has no email field of its own, so the shopper has nowhere to type the address and the submit stays disabled.
+- **Expecting an email label, placeholder or invalid-format message on it.** Those belong to `SignInEmailControl`; this component has no email field to label or style.
+- **Expecting it to read data or pre-fill the email.** It declares no fragment and takes no data prop; the Root seeds the shared draft from the shopper's profile.
 - **Conflating the form-level error with the top-level `UNAUTHORIZED` gate.** They are different error classes (ADR-00007) rendered in different places; `SignInForm` never reads or reacts to the top-level gate.
 - **Computing the logged-in state locally.** Read it from `useSession()`; `SignInForm` holds no local "am I logged in" flag.
-- **Adding a second submit or a two-step email-then-password flow.** The password method is one combined form with a single submit; a two-step flow is the separate access-code component (FSPG-872).
-- **Retaining the password after a failed attempt.** It is cleared from state immediately; only the email survives a failed attempt.
+- **Reading the account's enabled methods in a custom part.** Read `useSignIn()`; `SignInRoot` is the one reader of `sessionAuthProviders`.
+- **Adding a second submit or a two-step email-then-password flow.** The password method is one form with a single submit; a two-step flow is the separate access-code family.
+- **Retaining the password after a failed attempt.** It is cleared from state as soon as the dispatch answers; only the shared email survives a failed attempt.
 
 ---
 
 ## Related
 
-- [[email-field]] — the presentational particle this composes for the email input.
-- [[password-field]] — the presentational particle this composes for the password input; `SignInForm` owns its presence check.
-- [[email-identification]] — the sibling matter this mirrors in shape (colocated fragment, `pending` convention), without a password or submit step.
+- [[sign-in]] — provides the shared email draft, the active method and the account's enabled-method flags this form reads.
+- [[access-code-sign-in]] — the sibling method composed beside this one under the same `SignInRoot`.
+- [[password-field]] — the presentational particle this composes for the password input; `SignInForm` owns its presence check and its rejected-credentials message.
 - [[session]] — provides the identification tri-state and the required `SessionRoot` ancestor.

package/dist/docs/sign-in-redirect.md

@@ -101,7 +101,7 @@ Bound to a CMS entry, the element authors no `loadingLabel` at all — the entry
 
 | Component | What you style | Plausible classes |
 |---|---|---|
-| `SignInRedirect` | The one element the route renders, which is the waiting message. Style it as a centered full-page state rather than as an inline label | `flex min-h-[420px] items-center justify-center text-[14px] font-medium text-[#6B7280]` |
+| `SignInRedirect` | The one element the route renders, which is the waiting message. Style it as a centered full-page state rather than as an inline label | `flex min-h-[420px] items-center justify-center text-[14px] font-medium text-[var(--color-text-muted)]` |
 
 That element carries both hooks: `data-fs-sign-in-redirect` is the component's identity, and `data-fs-sign-in-redirect-loading` is the waiting look. They are the same element here, so either reaches it — use the identity for the page state and the loading hook when a rule has to survive the part being rendered on its own.
 
@@ -113,7 +113,7 @@ That element carries both hooks: `data-fs-sign-in-redirect` is the component's i
       "platformLoginUrl": "/api/io/login",
       "loadingLabel": "Redirecionando para o login…"
     },
-    "style": ["flex", "min-h-[420px]", "items-center", "justify-center", "text-[14px]", "text-[#6B7280]"]
+    "style": ["flex", "min-h-[420px]", "items-center", "justify-center", "text-[14px]", "text-[var(--color-text-muted)]"]
   }
 }
 ```
@@ -128,6 +128,8 @@ A spinner beside the text is a decoration the component does not render. Draw it
 }
 ```
 
+The colors that several elements share are variables of the page or layout `theme`, which declares them: `{"--color-text-muted": "#6B7280"}`. A color used once stays a hex.
+
 ---
 
 ## Related

package/dist/docs/sign-in.md

@@ -0,0 +1,173 @@
+# SignIn (Root + EmailControl + MethodSwitch + MethodOption)
+
+**Category:** identity
+**Purpose:** The shared surface under every sign-in method. `SignInRoot` reads the account's enabled methods once (`sessionAuthProviders { __typename id passwordAuthentication accessKeyAuthentication }`), owns the one email draft and the active method, and publishes them as the `sign-in` context; it renders no element of its own and always renders its children. `SignInEmailControl` is the one email field. `SignInMethodSwitch` and `SignInMethodOption` move the active method: the first as a single toggle, the second as one selectable option per method. Each part gates itself, so a single-method store needs no authoring decision.
+
+---
+
+## Visual cues (how to identify in an image)
+
+- **One email field**, with the sign-in method drawn below it and no second email field further down — this is `SignInEmailControl` over whichever method the page composed.
+- A **single link-like button** that flips between "sign in with a code" and "sign in with a password" under the email field — `SignInMethodSwitch`.
+- **Two side-by-side choices** ("Receive a code" / "Use my password"), one of them marked as the current one — a `SignInMethodOption` per method.
+- **One default method plus a "use password instead" link** — a single `SignInMethodOption` beside the default method's form.
+- A **grey placeholder bar** where the email field will be, shown briefly while the account configuration loads — the email control's skeleton.
+
+---
+
+## When to use
+
+- The checkout User Identity step, whenever more than one sign-in method (password, access code) shares an email address.
+- As the single place a page learns which methods the account enables: compose the method families under this Root instead of letting each read the account on its own.
+
+## When NOT to use
+
+- A page with exactly one sign-in method and no shared email → use that method's own family directly.
+- Collecting an email that is written to the cart → `EmailIdentificationControl` is the cart-writing path. `SignInEmailControl` never writes anywhere; its value is only the draft the method families sign in with.
+- Placing the Root where a `SessionRoot` is not an ancestor → `useSession()` throws.
+
+---
+
+## Composition
+
+```
+SessionRoot                              (provides the session tri-state; required ancestor)
+└── SignInRoot                           (renders no element; reads the account once; owns the email draft and the active method)
+    ├── SignInEmailControl               (data-fs-sign-in-email; skeleton while unresolved)
+    ├── SignInMethodSwitch               (presentation 1)
+    ├── SignInMethodOption method="accessCode"   (presentations 2 and 3)
+    ├── SignInMethodOption method="password"     (presentation 2)
+    ├── SignInForm                       (the password method; see sign-in-form.md)
+    └── AccessCodeSignInRoot             (the access-code method; see access-code-sign-in.md)
+```
+
+The two method families bind to this Root rather than reading the account themselves: `SignInForm`
+and `AccessCodeSignInRoot` each render only while their own method is the active one, and both take
+the email from `SignInEmailControl` instead of carrying a field of their own.
+
+Compose the switch **or** the options, not both. Three presentations, each a reading of "present one sign-in option per enabled method":
+
+| Presentation | Composition | What the shopper sees |
+|---|---|---|
+| 1. One toggle | `SignInMethodSwitch` alone | The active method and one button that moves to the other. Renders only when both methods are enabled |
+| 2. One option per enabled method | one `SignInMethodOption` per method (`method="password"` and `method="accessCode"`) | Every enabled method visible at once, the active one marked selected. A single-method store renders exactly one, because the other option gates itself out |
+| 3. Default method plus one escape hatch | the default method's form, beside a single `SignInMethodOption` for the other | The default method (access code when both are enabled) with the other one click away |
+
+`SignInRoot` **must** have a `SessionRoot` ancestor. `SignInEmailControl`, `SignInMethodSwitch` and `SignInMethodOption` **must** be descendants of `SignInRoot` — `useSignIn()` throws `useSignIn() must be used inside a <SignInRoot> subtree.` otherwise (runtime guard, not compiler-checked).
+
+`SignInEmailControl` is not required by the compiler, but a page that omits it has no email input anywhere. Composing two `SignInMethodOption` elements with the same `method` makes both claim the selected state; nothing catches it.
+
+---
+
+## Props
+
+### `SignInRoot`
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| `$data` | `{ clientProfile: { email } \| null, sessionAuthProviders: { passwordAuthentication, accessKeyAuthentication } \| null } \| null` | injected | Colocated `on Query` fragment slice. |
+| `children` | `ReactNode` | — | Always rendered, in every session state and for every flag combination. |
+
+**Data:** declares `fragment SignInData on Query { clientProfile { __typename id email } sessionAuthProviders { __typename id passwordAuthentication accessKeyAuthentication } }` with `fetchStrategy: 'reactive'`, `requiresContext: 'session'` and `providesContext: 'sign-in'`. It declares no actions.
+
+### `SignInEmailControl`
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| `label` | string | — | Passed to `EmailField`. |
+| `placeholder` | string | — | Passed to `EmailField`. |
+| `invalidEmailMessage` | string | — | `EmailField`'s inline error text, shown on blur of a non-empty, malformed address. Omitted, no inline error text renders. |
+| `name` | string | `'email'` | Passed to `EmailField`; the input's `name`. |
+| `autoComplete` | string | `'username'` | Passed to `EmailField`; the input's `autocomplete` token. The default marks the input as the username half of the credential the password step submits, so a browser's password manager saves the address with the password and fills both on the next visit. |
+
+### `SignInMethodSwitch`
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| `toAccessCodeLabel` | string | — | Button text while the password is the active method. |
+| `toPasswordLabel` | string | — | Button text while the access code is the active method. |
+
+### `SignInMethodOption`
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| `method` | `'password' \| 'accessCode'` | required | Which method this option selects. The option renders nothing when the account disables that method. |
+| `label` | string | — | The option's button text. |
+
+No label prop in this family carries a default: labels are the merchant's own message, so no English
+fallback ships. The two defaults above are `SignInEmailControl`'s `name` and `autoComplete`, which are
+HTML attribute tokens rather than copy.
+
+---
+
+## Behavior
+
+- **Resolved before enabled.** The Root derives `resolved` from three signals: the reactive page has settled, the entity slice is the cache's own answer, and `sessionAuthProviders` is present. Every part checks `resolved` before it reads a flag, so "the configuration has not arrived" is never mistaken for "the account enables nothing". Only `SignInEmailControl` draws something meanwhile — its skeleton (`data-fs-sign-in-email-skeleton`, `aria-hidden="true"`).
+- **Signed in renders nothing.** When `useSession().state` is `loggedIn`, the email control, switch and options render nothing; the Root keeps rendering its other children.
+- **No method enabled renders nothing.** With both flags `false`, the email control, switch and options all render nothing.
+- **Active method.** The shopper's choice if they made one; otherwise the access code when it is enabled, otherwise the password. The default is derived, so a choice made before the configuration resolved cannot pin a stale default, and a shopper's choice survives a rerender. Once the configuration has resolved, a choice for a method the account no longer enables falls back to the default, so `method` never names a disabled method; while it is unresolved the choice is kept.
+- **One email draft.** Owned by the Root, seeded from `clientProfile.email` while the shopper has not edited it, and never re-seeded after an edit. It survives a method change. When the session becomes `loggedIn` the shopper's edit is dropped and the draft falls back to the profile email, so the Root, which never unmounts, does not carry a typed address to the next shopper. It is never written to the cart.
+- **Selected state.** A `SignInMethodOption` carries `data-fs-sign-in-method-option-selected` and an `aria-pressed="true"` button only while its method is the active one. Activating the selected option changes nothing.
+- **No actions.** The family dispatches no mutation; the switch, the options and the draft are local state.
+
+### Hooks
+
+| Hook | Notes |
+|------|-------|
+| `useSignIn()` | `{ email, setEmail, method, setMethod, passwordEnabled, accessCodeEnabled, anyMethodEnabled, bothMethodsEnabled, resolved }`. Throws outside a `SignInRoot`. |
+
+---
+
+## `data-fs-*` hooks
+
+| Attribute | Element | Meaning |
+|---|---|---|
+| `data-fs-sign-in-email` | email wrapper | The email field is present and the configuration resolved |
+| `data-fs-sign-in-email-skeleton`, `data-fs-sign-in-email-skeleton-line` | skeleton | The configuration has not arrived |
+| `data-fs-sign-in-method-switch` | switch wrapper | Both methods are enabled |
+| `data-fs-sign-in-method` | switch wrapper | `password` or `accessCode`: the active method |
+| `data-fs-sign-in-method-switch-button` | switch button | The control that moves the method |
+| `data-fs-sign-in-method-option` | option wrapper | Value is the method this option selects |
+| `data-fs-sign-in-method-option-selected` | option wrapper | Present only while this option's method is active |
+| `data-fs-sign-in-method-option-button` | option button | The control that activates this option's method |
+
+---
+
+## Canonical schema example
+
+Presentation 2, one option per enabled method:
+
+```json
+{
+  "type": "SessionRoot",
+  "children": [
+    {
+      "type": "SignInRoot",
+      "children": [
+        { "type": "SignInEmailControl", "props": { "label": "E-mail", "placeholder": "voce@exemplo.com" } },
+        { "type": "SignInMethodOption", "props": { "method": "accessCode", "label": "Receber um código" } },
+        { "type": "SignInMethodOption", "props": { "method": "password", "label": "Usar minha senha" } }
+      ]
+    }
+  ]
+}
+```
+
+---
+
+## Common mistakes
+
+- **Composing a method part outside `SignInRoot`.** `useSignIn()` throws immediately.
+- **Composing both `SignInMethodSwitch` and `SignInMethodOption`.** Pick one presentation; the two together offer the same choice twice.
+- **Omitting `method` on `SignInMethodOption`.** An option that does not say which method it selects has no meaning.
+- **Expecting a `null` `$data` at runtime for an unresolved read.** A reactive `$data` is never `null`; only `sessionAuthProviders` is absent. `$data={null}` is the component-test equivalent.
+- **Adding a second `SessionRoot`, or reading `sessionAuthProviders` in a method family of your own.** This Root is the one place the account's methods are read.
+
+---
+
+## Related
+
+- [[session]] — provides the required `SessionRoot` ancestor and the `loggedIn` state that empties every part.
+- [[email-field]] — the particle `SignInEmailControl` composes.
+- [[access-code-sign-in]] — the access-code method family, which composes under this Root.
+- [[sign-in-form]] — the password method family, which composes under this Root.

package/dist/docs/toast.md

@@ -61,11 +61,22 @@ Renders `ToastViewport` into `document.body`. No props, context-only.
 
 The fixed-position stack container. Renders a `<div>` — style it directly.
 
-- **No children:** renders one default toast per active toast, in queue order: `ToastRoot` > `ToastTitle` + `ToastDescription` + `ToastAction` + `ToastClose`. Each part renders nothing when the toast has no matching text or `actionProps`, so a reversible toast shows its action between the text and the close button. The close button is named from the message catalog (`fs/toast.dismiss`); its `×` glyph is hidden from assistive technology. The default toast has no status icon and adds no `data-fs-*` hook beyond the existing ones.
-- **With children:** renders exactly those children and no default toast. `null`, `false` and `undefined` count as no children.
-- **Region name:** every viewport gets `aria-label` from the message catalog (`fs/toast.region`, "Notifications") unless you pass your own `aria-label`.
+- **No children:** renders one default toast per active toast, in queue order: `ToastRoot` > `ToastTitle` + `ToastDescription` + `ToastAction` + `ToastClose`. Each part renders nothing when the toast has no matching text or `actionProps`, so a reversible toast shows its action between the text and the close button. The close button is named by the `dismissLabel` message; its `×` glyph is hidden from assistive technology. The default toast has no status icon and adds no `data-fs-*` hook beyond the existing ones.
+- **With children:** renders exactly those children and no default toast, and does not read `dismissLabel`. `null`, `false` and `undefined` count as no children.
+- **Region name:** every viewport's `aria-label` is the `regionLabel` message. A missing message renders an empty name and logs `message.missing`.
 
-No props beyond standard `className`/HTML attributes. It reads the message catalog, so it needs an intl provider ancestor (a generated app's root layout provides one).
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| `$content` | `ContentValue<typeof ToastViewportContent>` | — | The viewport's messages (below). |
+
+Other props are standard `className`/HTML attributes, except `aria-label`, which comes from `regionLabel`. It formats its messages in the storefront locale, so it needs a `StorefrontContextProvider` ancestor (a generated app's root layout provides one).
+
+Content type `toast-viewport`:
+
+| Content field | Description |
+|---|---|
+| regionLabel | The viewport's accessible name |
+| dismissLabel | The default toast's close button name |
 
 ### ToastList