@acronis-platform/ui-react 3.0.0 → 4.0.0

package/dist/llms/filter-search.md

@@ -0,0 +1,512 @@
+# FilterSearch
+
+> A composable toolbar for data tables: arranges a search field, optional filters button, optional tenant/scope switcher, and trailing action buttons in a single horizontal row. Pure layout — no dedicated token tier; child components (Search, ButtonMenu, Select) bring their own tokens. `FilterSearchFilters` (the filter popover: trigger + form + Reset/Cancel/ Apply) is still a design-pending addition — no Figma node yet, unlike the FilterSearch node itself (see `figma:` below, which covers only the root toolbar layout). `FilterSearchAppliedFilters` (the removable-chip row + top-level "Reset filters") is the data-driven wrapper over `FilterChips`, which owns that row's design — see the FilterChips spec.
+
+**Status:** ready · **Category:** layout · **Since:** v0.55.0
+
+## Import
+
+```tsx
+import { FilterSearch, FilterSearchActions, FilterSearchFilters, FilterSearchAppliedFilters, useFilterSearchFilters } from '@acronis-platform/ui-react'
+```
+
+## Quick example
+
+```tsx
+function StatusField() {
+  const { filters, setFilter } = useFilterSearchFilters();
+  return (
+    <InputSelect
+      value={(filters.status as string) ?? null}
+      onValueChange={(v) => setFilter('status', v)}
+    >
+      {/* … */}
+    </InputSelect>
+  );
+}
+
+function Toolbar() {
+  const [filters, setFilters] = React.useState<Record<string, unknown>>({});
+  return (
+    <div className="flex flex-col gap-3">
+      <FilterSearch>
+        <Search placeholder="Search table" aria-label="Search" className="w-56" />
+        <FilterSearchFilters value={filters} onValueChange={setFilters} label="Table filters">
+          <StatusField />
+        </FilterSearchFilters>
+        <FilterSearchActions>
+          <Button>Export</Button>
+        </FilterSearchActions>
+      </FilterSearch>
+      <FilterSearchAppliedFilters filters={filters} onValueChange={setFilters} />
+    </div>
+  );
+}
+```
+
+A composable toolbar for data tables that arranges a search field, optional
+filter controls, an optional scope/tenant switcher, and trailing action buttons
+in a single horizontal row.
+
+`FilterSearchFilters` (the filter popover — trigger + form + Reset/Cancel/
+Apply) and `FilterSearchAppliedFilters` (the removable-chip row + a top-level
+"Reset filters" that clears immediately) are the real, functioning filter
+building blocks — compose `FilterSearchFilters` in place of a plain filter
+trigger, and render `FilterSearchAppliedFilters` as a sibling row below
+`FilterSearch`. Ported from the standalone `MultiSearch` component (retired in
+favor of living here, next to the toolbar it always appeared alongside).
+
+> **Design-pending.** Unlike `FilterSearch`/`FilterSearchActions` (which have a
+> real Figma node — see `figma:` in `index.yaml`), `FilterSearchFilters` and
+> `FilterSearchAppliedFilters` have no Figma node yet. They theme entirely from
+> shared semantic tokens plus their composed components' own tiers (Button,
+> Chip, Popover) — no new component token tier. Reconcile against the real
+> design later with `/figma-component FilterSearchFilters <url> --update`.
+
+## When to Use
+
+- Above a data table to provide search, filtering, and bulk action controls.
+- When the table needs a consistent toolbar layout across views.
+
+## When NOT to Use
+
+- **Form layouts** — use a form component, not a toolbar.
+- **Navigation bars** — use a dedicated nav component.
+
+## Related Components
+
+- **DataTableToolbar** — a differently-designed toolbar that is part of the
+  `DataTable` compound component. Use `FilterSearch` when you need a standalone
+  toolbar above any data table; use `DataTableToolbar` when working within the
+  `DataTable` composition.
+
+## Filter fields via the context hook
+
+Filter fields are **plain children** (no render prop). Each field wires its
+own value/onChange to the popover draft through the `useFilterSearchFilters()`
+context hook, which returns the current draft `filters` map and a per-key
+`setFilter` setter. Apply commits the draft; Cancel / dismiss reverts it.
+
+```tsx
+import {
+  FilterSearchFilters,
+  useFilterSearchFilters,
+} from '@acronis-platform/ui-react';
+
+function StatusField() {
+  const { filters, setFilter } = useFilterSearchFilters();
+  return (
+    <InputSelect
+      value={(filters.status as string) ?? null}
+      onValueChange={(v) => setFilter('status', v)}
+    >
+      {/* … */}
+    </InputSelect>
+  );
+}
+```
+
+Group fields with a `Separator` between them as a layout convention.
+
+## Parts
+
+| Part                         | Element / component             | Role                                                       |
+| ---------------------------- | ------------------------------- | ---------------------------------------------------------- |
+| `FilterSearch`               | `<div>`                         | Root flex container (16px gap, center-aligned)             |
+| `FilterSearchActions`        | `<div>`                         | Right-aligned area for action buttons                      |
+| `FilterSearchFilters`        | `Popover` + `Button` trigger    | The filter popover: fields + Reset/Cancel/Apply footer     |
+| `FilterSearchAppliedFilters` | `<div>` with `Chip`s + `Button` | Removable applied-filter chips + a top-level Reset filters |
+
+## Behavior at a glance
+
+- Opening `FilterSearchFilters`'s popover snapshots `value` into an editable draft.
+- **Apply** commits the draft → `onValueChange` (+ `onApply`) and closes.
+  Disabled until the draft differs from the last-applied `value`.
+- **Cancel**, outside-press, and **Escape** revert the draft and close.
+- The footer's **Reset filters** clears the draft to empty (disabled when already empty).
+- `FilterSearchAppliedFilters` renders nothing when `filters` is empty; its own
+  **Reset filters** clears all filters immediately (no popover involved).
+- `FilterSearchFilters`'s popover is a `Popover`/`PopoverContent` under the
+  hood, so it inherits that component's constrained-container behavior: for
+  an isolated portal container (e.g. a shadow root), pass `portalContainer`
+  so the popup inherits that scope's styles and switches to `fixed`
+  positioning so it isn't clipped at the container's own edge. See
+  `Popover`'s own spec for details.
+
+## Quick Examples
+
+### React
+
+```tsx
+import {
+  FilterSearch,
+  FilterSearchActions,
+  FilterSearchFilters,
+  FilterSearchAppliedFilters,
+  useFilterSearchFilters,
+} from '@acronis-platform/ui-react';
+import { Search, Button } from '@acronis-platform/ui-react';
+
+function StatusField() {
+  const { filters, setFilter } = useFilterSearchFilters();
+  return (
+    <InputSelect
+      value={(filters.status as string) ?? null}
+      onValueChange={(v) => setFilter('status', v)}
+    >
+      {/* … */}
+    </InputSelect>
+  );
+}
+
+function TableToolbar() {
+  const [filters, setFilters] = React.useState<Record<string, unknown>>({});
+  return (
+    <div className="flex flex-col gap-3">
+      <FilterSearch>
+        <Search
+          placeholder="Search table"
+          aria-label="Search"
+          className="w-56"
+        />
+        <FilterSearchFilters
+          value={filters}
+          onValueChange={setFilters}
+          label="Table filters"
+        >
+          <StatusField />
+        </FilterSearchFilters>
+        <FilterSearchActions>
+          <Button>Export</Button>
+        </FilterSearchActions>
+      </FilterSearch>
+      <FilterSearchAppliedFilters
+        filters={filters}
+        onValueChange={setFilters}
+      />
+    </div>
+  );
+}
+```
+
+### With tenant switcher
+
+```tsx
+<FilterSearch>
+  <Select defaultValue="all">
+    <SelectTrigger className="w-56">
+      <SelectValue placeholder="All customers" />
+    </SelectTrigger>
+    <SelectContent>
+      <SelectItem value="all">All customers</SelectItem>
+    </SelectContent>
+  </Select>
+  <Search placeholder="Search table" aria-label="Search" className="w-56" />
+  <FilterSearchFilters value={filters} onValueChange={setFilters}>
+    <StatusField />
+  </FilterSearchFilters>
+</FilterSearch>
+```
+
+## Spec Files
+
+| File               | Contents                                                        |
+| ------------------ | --------------------------------------------------------------- |
+| `index.yaml`       | Identity, status, category, dependencies, Figma link            |
+| `anatomy.yaml`     | Root, parts, layout, prop + internal states                     |
+| `api.yaml`         | Framework-agnostic contract + framework adapters                |
+| `tokens.yaml`      | Directly-referenced `--ui-*` token references                   |
+| `behavior.md`      | Given/When/Then behavior scenarios                              |
+| `accessibility.md` | ARIA guidance (delegated to child components; own popover a11y) |
+
+## Props
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| `className` | `string` | `undefined` | no | Additional CSS classes. On `FilterSearch` and `FilterSearchAppliedFilters`, the root container; on `FilterSearchFilters`, the trigger button. |
+| `value` | `Record<string, unknown>` | — | yes | `FilterSearchFilters` only. The applied filter values, keyed by an arbitrary consumer-chosen id. |
+| `onValueChange` | `(next: Record<string, unknown>) => void` | — | yes | `FilterSearchFilters` only. Called with the committed filters when Apply is pressed. `FilterSearchAppliedFilters` also has an `onValueChange` — called with the remaining filters when a chip is removed or "Reset filters" clears all. |
+| `onApply` | `(filters: Record<string, unknown>) => void` | `undefined` | no | `FilterSearchFilters` only. Called with the newly applied filters when Apply is pressed (fires alongside `onValueChange`). Synchronous — no loading/applying state in v1. |
+| `label` | `ReactNode` | `'Filters'` | no | `FilterSearchFilters` only. Label for the filter trigger button. |
+| `resetFiltersLabel` | `ReactNode` | `'Reset filters'` | no | `FilterSearchFilters` and `FilterSearchAppliedFilters`. Label for the "Reset filters" action (the popover footer action on `FilterSearchFilters`; the top-level clear-all action on `FilterSearchAppliedFilters`). Override to localize. |
+| `cancelLabel` | `ReactNode` | `'Cancel'` | no | `FilterSearchFilters` only. Label for the popover footer's "Cancel" action. Override to localize. |
+| `applyLabel` | `ReactNode` | `'Apply'` | no | `FilterSearchFilters` only. Label for the popover footer's "Apply" action. Override to localize. |
+| `contentClassName` | `string` | `undefined` | no | `FilterSearchFilters` only. Additional CSS classes for the popover content. |
+| `side` | `'top' | 'bottom' | 'left' | 'right' | 'inline-start' | 'inline-end'` | `'bottom'` | no | `FilterSearchFilters` only. Which side of the trigger to render the popover on. |
+| `align` | `'start' | 'center' | 'end'` | `'start'` | no | `FilterSearchFilters` only. Alignment of the popover along the chosen side. |
+| `sideOffset` | `number` | `4` | no | `FilterSearchFilters` only. Distance in px between the trigger and the popover. |
+| `portalContainer` | `Element | ShadowRoot | null | RefObject<Element | ShadowRoot | null>` | `undefined` | no | `FilterSearchFilters` only. React/DOM escape hatch, not part of the framework-agnostic contract (see the `react` adapter below). Forwarded to the underlying `Popover`'s `PopoverContent`; defaults to the nearest `PortalContainerProvider`, or `document.body` if none is set. |
+| `collisionBoundary` | `Element | Element[] | Rect | 'clipping-ancestors'` | `undefined` | no | `FilterSearchFilters` only. React/DOM escape hatch, not part of the framework-agnostic contract (see the `react` adapter below). Forwarded to `PopoverContent`; left at the platform default (clipping ancestors) unless overridden. |
+| `positionMethod` | `'absolute' | 'fixed'` | `undefined` | no | `FilterSearchFilters` only. React/DOM escape hatch, not part of the framework-agnostic contract (see the `react` adapter below). Forwarded to `PopoverContent`; defaults to `'fixed'` whenever a custom `portalContainer` is resolved, so the popover isn't clipped at a constrained MFE/Shadow DOM container's own edge. |
+| `filters` | `Record<string, unknown>` | — | yes | `FilterSearchAppliedFilters` only. The currently applied filter values, keyed by an arbitrary consumer-chosen id. Renders nothing when empty. |
+| `getFilterChipLabel` | `(key: string, value: unknown) => ReactNode` | `defaults to "<key>: <value>"` | no | `FilterSearchAppliedFilters` only. Format an applied-filter chip's label. Defaults to `"<key>: <value>"` (array values joined with ", "). |
+| `getRemoveFilterLabel` | `(key: string) => string` | `defaults to "Remove <key> filter"` | no | `FilterSearchAppliedFilters` only. Format a filter chip's remove-button accessible label. Override to localize. |
+
+## Content slots
+
+| Slot | Description |
+|------|-------------|
+| `default` | The composed toolbar. Place Search, Select, FilterSearchFilters, and FilterSearchActions as direct children. The order of children determines the visual order. |
+| `FilterSearchFilters children` | Filter field children rendered inside `FilterSearchFilters`'s popover form. Plain children — wire each field to the draft via `useFilterSearchFilters`. Group fields with a `Separator` as a layout convention if desired. |
+
+## Behavior
+
+### Structure
+
+#### Renders a horizontal toolbar
+
+**Given** a FilterSearch wrapping child components
+**When** the component renders
+**Then** the root is a `<div>` with a horizontal flex layout and 16px gap
+**And** children are vertically centered
+
+#### Renders with search only
+
+**Given** a FilterSearch containing only a Search component
+**When** it renders
+**Then** only the search field is shown in the toolbar
+
+#### Renders with tenant switcher and filters
+
+**Given** a FilterSearch containing a Select, Search, and ButtonMenu
+**When** it renders
+**Then** all three appear in order: select, search, filters button
+
+---
+
+### Actions Area
+
+#### Pushes action buttons to the trailing edge
+
+**Given** a FilterSearch with a FilterSearchActions containing buttons
+**When** it renders
+**Then** the actions area takes remaining space (`flex-1`)
+**And** its content is right-aligned
+
+#### Renders without actions
+
+**Given** a FilterSearch with no FilterSearchActions
+**When** it renders
+**Then** children are laid out from the leading edge with no trailing spacer
+
+---
+
+### Composition
+
+#### Supports arbitrary children
+
+**Given** a FilterSearch with custom children (not just Search/Select/ButtonMenu)
+**When** it renders
+**Then** all children appear in source order within the flex container
+
+#### Merges custom className
+
+**Given** a FilterSearch with a custom className
+**When** it renders
+**Then** the custom class is merged onto the root element
+
+---
+
+### FilterSearchFilters (the filter popover)
+
+#### Opens the popover from the trigger
+
+**Given** a FilterSearchFilters whose popover is closed
+**When** the filter trigger is clicked
+**Then** the popover opens showing the field children and the footer (Reset filters / Cancel / Apply)
+**And** the trigger is visually highlighted while open
+
+#### Applies the drafted filters on Apply
+
+**Given** the popover is open and a field child has set a draft value (e.g. `status: "active"`)
+**When** Apply is pressed
+**Then** `onValueChange` fires with the committed filters (`{ status: "active" }`)
+**And** `onApply` fires with the same applied filters
+**And** the popover closes
+
+#### Reverts the draft on Cancel without applying
+
+**Given** the popover is open and a field child has changed the draft
+**When** Cancel is pressed
+**Then** `onValueChange` does **not** fire
+**And** the popover closes
+**And** reopening the popover shows a reverted (last-applied) draft
+
+> Dismissing the popover by outside-press or Escape reverts the draft the same
+> way Cancel does — an un-applied edit never leaks out.
+
+#### Reset filters clears the draft (disabled when empty)
+
+**Given** the popover is open with applied filters present
+**When** the footer's "Reset filters" is pressed
+**Then** the draft is cleared to empty
+
+**Given** the popover is open with no filters set
+**When** it renders
+**Then** the footer's "Reset filters" is disabled
+
+#### Apply is disabled until the draft actually changes
+
+**Given** the popover is opened fresh (no edits made)
+**When** it renders
+**Then** "Apply" is disabled, since the draft equals the last-applied `value`
+
+**Given** a field child changes the draft to a value different from `value`
+**When** it renders
+**Then** "Apply" becomes enabled
+
+#### Fields scroll once they exceed the popover's max height
+
+**Given** more filter field children than fit in the popover's height
+**When** the popover is open
+**Then** the fields region scrolls internally (`max-h-80 overflow-y-auto`)
+**And** the footer stays pinned below it
+
+#### Footer action labels are overridable
+
+**Given** a FilterSearchFilters rendered with `resetFiltersLabel`, `cancelLabel`,
+and/or `applyLabel`
+**When** the popover is open
+**Then** the footer renders the given labels instead of the English defaults
+("Reset filters" / "Cancel" / "Apply")
+
+#### The popover renders inside a constrained portal container without clipping
+
+**Given** a FilterSearchFilters rendered inside a `PortalContainerProvider`
+whose `container` is a small or offset element (e.g. an MFE/Shadow DOM mount)
+**When** the filter trigger is clicked
+**Then** the popover content mounts inside that container
+**And** it is not clipped at the container's own edge — it switches to `fixed`
+positioning by default, which (for a plain overflow-clipping container) keeps
+the platform's own collision boundary resolved against the real viewport
+
+**Given** the same constrained-container setup
+**When** a consumer passes an explicit `collisionBoundary`, `positionMethod`,
+`side`, `align`, `sideOffset`, `portalContainer`, or `contentClassName`
+**Then** that value overrides the computed default and is forwarded to the
+underlying popover
+
+---
+
+### FilterSearchAppliedFilters (the applied-filter chip row)
+
+#### Renders nothing when there are no applied filters
+
+**Given** a FilterSearchAppliedFilters with an empty `filters` object
+**When** it renders
+**Then** nothing is rendered
+
+#### Renders one removable chip per applied filter plus a Reset filters action
+
+**Given** a FilterSearchAppliedFilters with applied filters (e.g. `status: "active"`, `type: "server"`)
+**When** it renders
+**Then** one removable chip is shown per applied filter (`"status: active"`, `"type: server"`)
+**And** a "Reset filters" action is shown alongside the chips
+
+> Chip labels default to `"<key>: <value>"`; a `getFilterChipLabel(key, value)`
+> callback overrides the label.
+
+#### Removes a single filter when its chip is removed
+
+**Given** a FilterSearchAppliedFilters with applied filters
+**When** a chip's remove control is clicked (e.g. "Remove status filter")
+**Then** `onValueChange` fires with that key dropped
+
+#### The remove-filter label is overridable
+
+**Given** a FilterSearchAppliedFilters rendered with a `getRemoveFilterLabel`
+**When** it renders
+**Then** each chip's remove control uses the given label instead of the
+English default `"Remove <key> filter"`
+
+#### Clears all filters when Reset filters is pressed
+
+**Given** a FilterSearchAppliedFilters with one or more applied filters
+**When** its "Reset filters" action is pressed
+**Then** `onValueChange` fires with an empty filters object — immediately, with no popover involved
+
+#### The Reset filters label is overridable
+
+**Given** a FilterSearchAppliedFilters rendered with a `resetFiltersLabel`
+**When** it renders
+**Then** the clear-all action shows the given label instead of the English
+default "Reset filters"
+
+## Accessibility
+
+`FilterSearch` itself is a pure layout wrapper — accessibility concerns are
+delegated to its composed children (Search, ButtonMenu, Select, Button).
+`FilterSearchFilters` and `FilterSearchAppliedFilters` own their own
+interaction and are covered below.
+
+## ARIA Roles and Attributes
+
+### Root (`div`)
+
+The root element has **no semantic role** — it is a presentational flex
+container. If the consumer needs a landmark, they can add `role="toolbar"`
+and an `aria-label` via props.
+
+| Attribute    | Value    | Reason                                          |
+| ------------ | -------- | ----------------------------------------------- |
+| No `role`    | —        | Pure layout; no inherent semantics              |
+| `aria-label` | (opt-in) | Consumer may set this if using `role="toolbar"` |
+
+---
+
+## Keyboard Navigation
+
+Keyboard interaction is handled by the child components:
+
+| Component                    | Key         | Action                                        |
+| ---------------------------- | ----------- | --------------------------------------------- |
+| Search                       | Tab         | Focuses the search input                      |
+| ButtonMenu                   | Enter       | Opens/closes the filter menu                  |
+| Select                       | Enter       | Opens the select dropdown                     |
+| Button                       | Enter       | Activates the action                          |
+| `FilterSearchFilters`        | Enter/Space | Opens/closes the filter popover               |
+| `FilterSearchFilters`        | Escape      | Closes the popover and reverts the draft      |
+| `FilterSearchAppliedFilters` | Tab         | Moves between chips' remove buttons and Reset |
+
+The toolbar itself does not manage focus — children follow their own focus
+patterns. If `role="toolbar"` is applied, arrow-key navigation between
+children is the consumer's responsibility.
+
+`FilterSearchFilters`'s popover uses Base UI's `Popover` primitive, which
+provides standard dialog-like focus trapping and restores focus to the
+trigger on close (Apply, Cancel, outside-press, or Escape).
+
+---
+
+## Screen Reader Requirements
+
+1. Each child component announces itself according to its own spec.
+2. The search field should have an `aria-label` (e.g. "Search table").
+3. Action buttons should have descriptive labels.
+4. `FilterSearchFilters`'s trigger announces its expanded state
+   (`aria-haspopup`/`aria-expanded`, from Base UI's `PopoverTrigger`).
+5. Each removable chip's remove control has an explicit `aria-label`
+   (`"Remove <key> filter"` by default, overridable via
+   `getRemoveFilterLabel(key)`), so a screen reader announces which filter a
+   given remove button drops.
+
+---
+
+## Color and Contrast
+
+All contrast requirements are owned by the child components and their
+respective token tiers, including `Button`, `Chip`, and `Popover`'s own specs
+for `FilterSearchFilters`/`FilterSearchAppliedFilters`.
+
+---
+
+## Testing Checklist
+
+- [ ] Root renders as a `<div>` with no unexpected ARIA roles
+- [ ] All child components are reachable via Tab
+- [ ] Search field has an accessible label
+- [ ] ButtonMenu announces its label and expanded state
+- [ ] Action buttons have accessible names
+- [ ] `FilterSearchFilters`'s trigger announces expanded state and toggles via Enter/Space
+- [ ] Escape closes the open popover and reverts the draft
+- [ ] Each applied-filter chip's remove control has a descriptive `aria-label`

package/dist/llms/form.md

@@ -0,0 +1,154 @@
+# Form
+
+> A native form element with consolidated validation, built on Base UI's Form. It collects values by each Field's name, runs the Fields' validation on submit (or per validationMode), surfaces server errors keyed by field name, and calls onFormSubmit with the values when every field is valid. Ported from the legacy shadcn-uikit `form` (which wrapped react-hook-form); this version drops that dependency and composes the ui-react Field directly.
+
+**Status:** draft · **Category:** forms · **Since:** v0.48.0
+
+## Import
+
+```tsx
+import { Form } from '@acronis-platform/ui-react'
+```
+
+## Quick example
+
+```tsx
+<Form onFormSubmit={(values) => save(values)} errors={serverErrors}>
+  <Field name="email">
+    <FieldLabel>Email</FieldLabel>
+    <FieldControl render={<InputBox type="email" required />} />
+    <FieldError />
+  </Field>
+  <Button type="submit">Save</Button>
+</Form>
+```
+
+A native `<form>` with consolidated validation, built on
+[Base UI's Form](https://base-ui.com/react/components/form). It collects values by
+each `Field`'s `name`, validates the fields on submit (or per `validationMode`),
+surfaces server `errors` keyed by field name, and calls `onFormSubmit(values)`
+when every field is valid.
+
+> **Design-pending v1.** Ported from the legacy shadcn-uikit `form`, which wrapped
+> [react-hook-form](https://react-hook-form.com). This version **drops that
+> dependency** and composes the ui-react `Field` directly on Base UI's validation.
+> If you need react-hook-form / TanStack Form, use them around plain `Field`s —
+> Form is the lightweight, dependency-free default.
+
+## When to use
+
+- Any short-to-medium form where Base UI's built-in validation is enough.
+- You want native submit semantics with per-field errors and no extra form-state
+  library.
+
+## When not to use
+
+- Complex form state (arrays, wizards, cross-field logic) better served by a
+  dedicated form library — compose that with the `Field` parts directly.
+
+## Parts
+
+Form is a single component. Compose it with the `Field` family:
+
+| Export | Purpose                                                          |
+| ------ | ---------------------------------------------------------------- |
+| `Form` | The `<form>` wrapper that coordinates validation and submission. |
+
+## Example
+
+```tsx
+import {
+  Form,
+  Field,
+  FieldLabel,
+  FieldControl,
+  FieldError,
+  InputBox,
+  Button,
+} from '@acronis-platform/ui-react';
+
+<Form onFormSubmit={(values) => save(values)} errors={serverErrors}>
+  <Field name="email">
+    <FieldLabel>Email</FieldLabel>
+    <FieldControl render={<InputBox type="email" required />} />
+    <FieldError />
+  </Field>
+  <Button type="submit">Save</Button>
+</Form>;
+```
+
+## Props
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| `validationMode` | `'onSubmit' | 'onBlur' | 'onChange'` | `'onSubmit'` | no | When the fields validate. A Field's own validationMode takes precedence. |
+| `errors` | `Record<string, string | string[]>` | — | no | Externally supplied errors (e.g. from a server) keyed by each Field's name. Shown on the matching field's FieldError. |
+| `actionsRef` | `RefObject<{ validate: (fieldName?: string) => void }>` | — | no | Imperative handle to validate all fields (or one) on demand. |
+
+## Events
+
+| Event | Payload | Description |
+|-------|---------|-------------|
+| `onFormSubmit` | `(values: Record<string, unknown>, details) => void` | Fired on submit once every field is valid; receives the collected field values keyed by name. preventDefault is called on the native event. |
+
+## Behavior
+
+Form is built on Base UI's Form. It coordinates the ui-react `Field`s it contains
+— no react-hook-form. Each Field carries a `name`; Form collects their values by
+that name, validates them, and reports errors.
+
+```gherkin
+Scenario: Submit collects values by field name
+  Given a Form with Fields named "email" and "password"
+  And the user fills them in
+  When the form is submitted
+  Then onFormSubmit is called once with { email, password }
+  And the native submit event is preventDefault-ed
+```
+
+```gherkin
+Scenario: Validation gates submit
+  Given a Field with a required control left empty
+  When the form is submitted
+  Then onFormSubmit is NOT called
+  And the field is marked invalid (aria-invalid) and shows its FieldError
+```
+
+```gherkin
+Scenario: Validation mode
+  Given validationMode="onChange"
+  Then each field validates on every change instead of only on submit
+```
+
+```gherkin
+Scenario: Server errors
+  Given errors={{ email: "That email is taken." }} (e.g. after a failed submit)
+  Then the Field named "email" shows that message in its FieldError
+  And the field is marked invalid
+```
+
+```gherkin
+Scenario: Imperative validation
+  Given an actionsRef on the Form
+  When actionsRef.current.validate() is called
+  Then all fields validate (or a single field when a name is passed)
+```
+
+## Accessibility
+
+- Renders a native `<form>`, so browser submit semantics (Enter to submit, the
+  submit button, native required validation) work as expected.
+- Accessibility of the individual controls is owned by `Field` — label
+  associations, `aria-describedby`, and `aria-invalid` are wired there. Form's job
+  is to coordinate validation and surface errors on the right field.
+- On a failed submit, focus management and the per-field `FieldError`
+  (`role="alert"` semantics) announce what went wrong; don't rely on color alone —
+  the error text states the problem.
+- Give the form an accessible name when there are multiple forms on a page
+  (`aria-label` / `aria-labelledby` referencing a heading).
+
+## Contrast
+
+Form adds no color of its own; contrast is governed by the Fields and controls it
+composes (see the Field spec). Error text there uses `--ui-text-on-status-danger`,
+which meets contrast in light and dark.