@vtex/faststore 0.0.1

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

@@ -0,0 +1,117 @@
+# 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`.
+
+---
+
+## 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.
+
+Use `SignInForm` (not a bare `EmailField` + `PasswordField` pair) 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.
+
+## When NOT to use
+
+- Passwordless / access-code (two-step) sign-in → a separate component (FSPG-872), not a variant of this one.
+- 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.
+
+---
+
+## 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)
+```
+
+`SignInForm` **must** have a `SessionRoot` ancestor — `useSession()` throws otherwise.
+
+---
+
+## Props
+
+| 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. |
+| `$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).
+
+**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`.
+
+---
+
+## 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.
+
+---
+
+## Canonical schema example
+
+```json
+{
+  "type": "SessionRoot",
+  "children": [
+    {
+      "type": "SignInForm",
+      "props": {
+        "emailLabel": "Email",
+        "passwordLabel": "Password",
+        "submitLabel": "Sign In",
+        "invalidCredentialsMessage": "Incorrect email or password. Please try again."
+      }
+    }
+  ]
+}
+```
+
+---
+
+## Common mistakes
+
+- **Rendering it outside `SessionRoot`.** `useSession()` throws; every identity page must host a `SessionRoot`.
+- **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.
+
+---
+
+## 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.
+- [[session]] — provides the identification tri-state and the required `SessionRoot` ancestor.

package/dist/docs/tabs.md

@@ -0,0 +1,176 @@
+# Tabs
+
+**Category:** layout
+**Purpose:** Generic tabbed UI primitive. Groups a row of tab buttons with matching content panels and lets the shopper switch between them with mouse, touch, or keyboard. Wraps Base UI's Tabs.
+
+---
+
+## Visual cues (how to identify in an image)
+
+A Tabs block is present when you see:
+
+- A **row of labels** (often underlined or pill-shaped) at the top of a section, with one label visually highlighted as **active** (different color, underline, filled background, indicator bar).
+- A **content area** below the labels that changes when the shopper clicks a different label.
+
+Common storefront uses:
+
+- Product detail sections (Description / Specs / Reviews / Shipping / FAQ).
+- Account pages (Profile / Orders / Addresses / Saved Items).
+- Cart drawer sections (Cart Items / Saved for Later).
+- Payment-methods disclosure with **tabs per method** (see [[pricing]] for the Pricing-aware composition).
+
+The image is the source of truth for layout. The labels can be horizontal or vertical.
+
+---
+
+## When to use
+
+- Two or more peer content sections that share screen space and are mutually exclusive (one visible at a time).
+- A disclosure panel that already groups data by category (e.g. payment methods, return policies by region).
+
+## When NOT to use
+
+- Sequential steps in a flow (use a stepper / wizard pattern instead).
+- A single content section — use a plain container.
+- Navigation between routes — use links (`NavigationLink` / `BreadcrumbLink`).
+- Always-visible content that does not need a selector — render the sections directly.
+
+---
+
+## Composition
+
+`TabsRoot` is the entry point. Each `TabsTab` must have a matching `TabsPanel` with the same `value`.
+
+```
+TabsRoot
+├── TabsList
+│   ├── TabsTab            (one per panel; unique `value`)
+│   └── TabsIndicator      (optional; animated highlight for the active tab)
+└── TabsPanel              (one per tab; `value` matches a TabsTab)
+```
+
+**Composition rules:**
+
+- `TabsList` and `TabsPanel` are both children of `TabsRoot`. They are **siblings**, not nested in each other.
+- `TabsTab` must be inside `TabsList`.
+- `TabsTab.value` and `TabsPanel.value` must match exactly to pair a tab with its panel.
+- Set `TabsRoot.defaultValue` to the `value` of the tab that should be active on first render. Without it, the first tab is selected.
+- `TabsIndicator` is optional. When present, place it inside `TabsList`; Base UI exposes the active tab position via CSS custom properties for animation.
+
+Child order reflects visual order.
+
+---
+
+## Components
+
+### TabsRoot
+
+Root container. Manages the active tab state and the orientation.
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| `defaultValue` | string | — | Value of the tab active on first render (uncontrolled mode) |
+| `orientation` | `'horizontal' \| 'vertical'` | `"horizontal"` | Controls arrow-key axis (Left/Right vs. Up/Down) |
+
+`value` / `onValueChange` are also accepted for controlled mode but are not exposed as schema props.
+
+### TabsList
+
+Tab buttons container. Owns roving `tabindex` and arrow-key navigation.
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| `loopFocus` | boolean | `true` | Wraps focus from last → first tab (and vice-versa) |
+| `activateOnFocus` | boolean | `false` | Activate a tab as soon as it receives keyboard focus |
+
+### TabsTab
+
+Individual tab button. Requires a unique `value` within the enclosing `TabsRoot`.
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| `value` | string | (required) | Identifier matched against `TabsPanel.value` |
+| `disabled` | boolean | `false` | Disabled tab cannot be selected; keyboard navigation skips it |
+
+Base UI sets `aria-selected`, `aria-controls`, `data-active=""` (on the active tab), and `data-disabled=""` (when disabled) automatically. Style the active state via the `data-[active]` CSS attribute selector.
+
+### TabsPanel
+
+Content panel matched to a tab by `value`.
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| `value` | string | (required) | Identifier matched against `TabsTab.value` |
+| `keepMounted` | boolean | `false` | Keep the panel in the DOM even when hidden (useful for forms that need to preserve state) |
+
+When `keepMounted=false` (default), inactive panels are unmounted entirely. When `true`, they stay in the DOM with a `hidden` attribute.
+
+### TabsIndicator
+
+Optional `<span>` that visually marks the active tab (animated underline, pill background, etc.). Base UI exposes CSS variables for the active tab's position and size. No props.
+
+---
+
+## Canonical schema example
+
+Product detail sections (Description / Specs / Reviews):
+
+```json
+{
+  "tabs": {
+    "component": "TabsRoot",
+    "props": { "defaultValue": "description" },
+    "children": ["tabs-list", "panel-description", "panel-specs", "panel-reviews"]
+  },
+  "tabs-list": {
+    "component": "TabsList",
+    "children": ["tab-description", "tab-specs", "tab-reviews"]
+  },
+  "tab-description": { "component": "TabsTab", "props": { "value": "description", "children": "Description" } },
+  "tab-specs":       { "component": "TabsTab", "props": { "value": "specs", "children": "Specs" } },
+  "tab-reviews":     { "component": "TabsTab", "props": { "value": "reviews", "children": "Reviews" } },
+  "panel-description": { "component": "TabsPanel", "props": { "value": "description" }, "children": ["text-description"] },
+  "panel-specs":       { "component": "TabsPanel", "props": { "value": "specs" },       "children": ["text-specs"] },
+  "panel-reviews":     { "component": "TabsPanel", "props": { "value": "reviews" },     "children": ["text-reviews"] }
+}
+```
+
+### Minimal variant (two tabs)
+
+```json
+{
+  "tabs": {
+    "component": "TabsRoot",
+    "props": { "defaultValue": "items" },
+    "children": ["tabs-list", "panel-items", "panel-saved"]
+  },
+  "tabs-list": {
+    "component": "TabsList",
+    "children": ["tab-items", "tab-saved"]
+  },
+  "tab-items":   { "component": "TabsTab", "props": { "value": "items", "children": "Cart" } },
+  "tab-saved":   { "component": "TabsTab", "props": { "value": "saved", "children": "Saved" } },
+  "panel-items": { "component": "TabsPanel", "props": { "value": "items" } },
+  "panel-saved": { "component": "TabsPanel", "props": { "value": "saved" } }
+}
+```
+
+---
+
+## Common mistakes
+
+- **Putting `TabsTab` outside `TabsList`.** Base UI looks up the composite root on `TabsList`; tabs placed elsewhere do not receive keyboard navigation.
+- **Mismatched `value` between tab and panel.** A tab with `value="reviews"` only activates a panel with `value="reviews"`. Typos silently hide the panel.
+- **Duplicate `value` on tabs inside the same `TabsRoot`.** Selecting one activates both; behavior is undefined. Each tab needs a unique `value`.
+- **Nesting `TabsPanel` inside `TabsList`.** They are siblings under `TabsRoot`, not parent/child.
+- **Forgetting `defaultValue` and expecting "no tab active".** Without `defaultValue` or `value`, Base UI selects the first tab. To start with no selection, pass `value={null}` in controlled mode (advanced).
+- **Using `Tabs` for sequential steps.** A stepper / wizard has order semantics and progress; Tabs is mutually-exclusive content of equal weight. Use a stepper component for ordered flows.
+- **Inventing `Tab`, `TabPanel`, or `TabsContent`.** The names are `TabsTab` and `TabsPanel`. There is no `TabsContent`.
+
+---
+
+## Related
+
+- [[accordion]] — alternative pattern when multiple sections can be open at the same time, or when vertical stacking and find-in-page support matter more than tabbed UI.
+- [[pricing]] — uses Tabs inside the payment-methods disclosure to group plans by method (Cartão de Crédito / Pix / etc.).
+- [[popover]] — common host for a Tabs composition when the tabs live inside a disclosure panel.

package/dist/docs/toast.md

@@ -0,0 +1,124 @@
+# Toast
+
+**Category:** layout / action
+**Purpose:** Ephemeral, non-blocking feedback ("Saved", "Added to cart", "Undo") queued from anywhere in the tree and rendered in a single fixed-position stack, without blocking the page.
+
+---
+
+## When to use
+
+- Confirming an action succeeded or failed without interrupting the shopper's flow (save confirmations, cart mutations, form submission results).
+- Offering a short, reversible undo window after a destructive action (e.g. "Removed from cart — Undo").
+- Any transient system message that should announce itself to screen readers (`aria-live`) and disappear on its own.
+
+## When NOT to use
+
+- **Blocking confirmations that require a decision** (e.g. "Delete this address?") — use `[[dialog]]` instead. A toast auto-dismisses; it cannot wait for a yes/no.
+- **Persistent inline validation** on a form field (e.g. "Email is required") — that is field-level error text, not a toast.
+- **Content a merchant edits in the page schema** (a promo banner, a announcement bar) — a toast is triggered imperatively from code (`useToast().add(...)`), not composed as a static page element with editorial copy.
+
+---
+
+## Composition
+
+`Toast` is not authored as a static PageSchema tree the way most components are. Only the **stack scaffolding** is mounted once, near the layout root:
+
+```
+ToastProvider
+└── ToastPortal
+    └── ToastViewport
+```
+
+Every `ToastRoot` inside `ToastViewport` is rendered **imperatively** by mapping over `useToast().toasts` — it does not appear as a `children` entry in any page schema. A typical per-toast render tree (authored in application code, not in a schema):
+
+```
+ToastRoot                    ← one per queued toast, keyed by toast.id
+├── ToastTitle                (optional — auto-renders toast.title with no children)
+├── ToastDescription          (optional — auto-renders toast.description with no children)
+├── ToastAction (optional)    ← reversible action, e.g. "Undo"
+└── ToastClose (optional)
+```
+
+`Icon` (existing particle) may be composed as a plain sibling of `ToastTitle`/`ToastDescription` inside `ToastRoot` — there is no dedicated status-icon sub-component. Wrap it in a plain `<span data-fs-toast-icon-container="">` at the call site for a tinted background; `ToastRoot` does not inject this wrapper itself, since it renders `children` verbatim. Style both hooks off `data-fs-toast-root-type`.
+
+## Components
+
+### ToastProvider
+
+Mounts the queue. Not styleable — context-only, no host element.
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| `limit` | `number` | `3` | Max concurrent toasts; the oldest is marked `data-fs-toast-root-limited` (not removed) past the limit. |
+| `timeout` | `number` | `5000` | Default auto-dismiss delay in ms. `0` disables auto-dismiss. |
+| `toastManager` | `ToastManager` | — | External manager for triggering toasts outside React (e.g. a non-component module). Rarely set from a schema. |
+
+### ToastPortal
+
+Renders `ToastViewport` into `document.body`. No props, context-only.
+
+### ToastViewport
+
+The fixed-position stack container. Renders a `<div>` — style it directly.
+
+No props beyond standard `className`/HTML attributes.
+
+### ToastRoot
+
+One instance per active toast.
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| `toast` | `ToastObject` | — | Required. One entry from `useToast().toasts`. |
+| `swipeDirection` | `'up' \| 'down' \| 'left' \| 'right'` or an array of those | `['down', 'right']` | Directions the shopper can swipe to dismiss. |
+
+### ToastTitle / ToastDescription
+
+No props beyond standard HTML attributes. Render `toast.title` / `toast.description` automatically when composed with no children; pass explicit children to override.
+
+### ToastAction / ToastClose
+
+No props beyond standard HTML attributes. `ToastAction` auto-renders `toast.actionProps.children` and forwards `toast.actionProps.onClick` when composed with no children. `ToastClose` dismisses the nearest ancestor `ToastRoot` on click.
+
+---
+
+## Triggering a toast
+
+```tsx
+import { useToast } from '@vtex/faststore/components';
+
+function SaveProfileButton() {
+  const { add } = useToast();
+  return (
+    <button onClick={() => add({ title: 'Saved', description: 'Your changes were saved.', type: 'success' })}>
+      Save
+    </button>
+  );
+}
+```
+
+`useToast()` is Base UI's `useToastManager()` re-exported under the FastStore name — `toasts`, `add`, `close`, `update`, and `promise` all behave exactly as documented at [base-ui.com/react/components/toast](https://base-ui.com/react/components/toast).
+
+---
+
+## Styling
+
+| Component | What you style | Plausible classes |
+|---|---|---|
+| `ToastViewport` | Positions the stack on the screen | `fixed bottom-4 right-4 flex flex-col gap-2 w-[320px]` |
+| `ToastRoot` | The toast card's surface; key off `data-fs-toast-root-type` for status color | `rounded-lg px-4 py-3 shadow-lg data-[fs-toast-root-type=error]:bg-red-50` |
+| `ToastTitle` | Toast heading typography | `text-sm font-semibold` |
+| `ToastDescription` | Toast body typography | `text-sm text-gray-600` |
+| `ToastAction` | The reversible-action control (e.g. "Undo") | `text-sm font-semibold underline` |
+| `ToastClose` | The dismiss control | `text-sm opacity-60 hover:opacity-100` |
+
+`ToastProvider` and `ToastPortal` are context-only — they render no host element, so there is nothing to style directly on them.
+
+`data-fs-toast-root` mirrors Base UI's own `data-swiping` (mid-drag) as `data-fs-toast-root-swiping`, and `data-limited` as `data-fs-toast-root-limited`, so a swatch can react to either without depending on Base UI's raw attribute names.
+
+---
+
+## Related
+
+- [[dialog]] — blocking, modal confirmation; use instead of Toast when a decision is required before the shopper can continue.
+- [[drawer]] — persistent side panel for browsing content (e.g. a mini cart); not for transient feedback.