# Form

**Maturity:** experimental

Lay out a settings-style screen as sections of related controls, each with an optional heading and explanatory footnote — "Profile" (name, theme), "Preferences" (notifications, volume) — without hand-building the grouped-card chrome per screen.

## Import

```tsx
import { Form } from "@liquidify/react/form"
```

## Props

- `children`: `ReactNode` (required). The Section stack (SwiftUI `Form(content:)` `{ … }` content closure). children role: `items` (charter §8) — {@link Section} / {@link Form.Body} / {@link Form.Header} / {@link Form.Footer} are the only documented direct slots. Strict, but non-destructive: any other direct child — including a `Fragment` wrapping otherwise-valid slots, which `Children.toArray` does NOT unwrap, mirroring `SegmentedControl`'s identical Fragment posture — is a dev-mode `console.error` and still renders verbatim (pass-through — `Form` never filters, unlike `SegmentedControl`'s `.Item`-only filtering) so a production build never throws or drops content. Spread `Section`/ `Form.Body`/`Form.Header`/`Form.Footer` as direct top-level children rather than wrapping them in a `Fragment`.
- `className`: `string | undefined`. Optional additional CSS class merged into the glass surface class. The supported per-instance customisation seam: override any `--lq-*` custom property from this class's CSS — the token cascade the engine reads (ADR-0004). No raw inline style is involved, so this stays ADR-0003 clean.
- `ref`: `Ref<HTMLDivElement> | undefined`. Forwarded ref to the rendered element — the component's native root (or the merged child element on a component that opts into {@link SlottableProps}). Generic over `E` (charter `docs/api-conventions.md` §4 rule 1, default `HTMLElement`) so a component with a polymorphic root (Link's navigation / action mode union, Text's `as`) can instantiate the concrete element per variant instead of leaving every consumer with a widened `Ref<HTMLElement>`. A component that does not narrow simply inherits the `HTMLElement` default — source-compatible with every pre-existing non-generic `extends ControlProps`.

## SwiftUI mapping

- ``Form(content:)`` → ``children: ReactNode` (required)` (direct): **children role: `items`** (charter §8) — `Section` / `Form.Body` / `Form.Header` / `Form.Footer` only. Strict direct-slot semantics: any other direct child — including a `Fragment` wrapping otherwise-valid slots, which `Children.toArray` does NOT unwrap — is a dev-mode `console.error` (still rendered — pass-through, mirroring `SegmentedControl`'s identical fragment/wrapper diagnostic, audit §7); production builds render silently. Spread slot elements as direct top-level children rather than wrapping them in a `Fragment`.
- ``.scrollContentBackground(.hidden)`` → `—` (direct): `Form`'s root is always transparent (v1 has no page-fill prop); matches the demo's exercised `.scrollContentBackground(.hidden)` shape unconditionally.
- ``.frame(height:)`` → `—` (direct): Demo-local layout, not a component prop.
- ``Form(_ configuration:)` / `FormStyle` protocol` → `— (out of scope v1)` (direct): Only the default grouped style is exercised; no custom-style plumbing.
- ``controlSize` / `.tint(_:)`` → `—` (direct): Non-sizable; `Form` has no tint surface.