torch-glare 2.5.5 → 2.6.0

package/docs/components/form-builder.md

@@ -1,276 +0,0 @@
----
-title: FormBuilder
-description: The fields. A compound, composition-based form — author fields as JSX children (FormBuilder.Text, FormBuilder.Select, …) wired to any react-hook-form resolver. All chrome around the fields lives in FormRenderer.
-component: true
-group: Forms
-keywords:
-  [
-    form-builder,
-    form,
-    compound,
-    composition,
-    react-hook-form,
-    resolver,
-    fields,
-    validation,
-    table,
-    field-array,
-    submit,
-  ]
----
-
-# FormBuilder
-
-A **compound, composition-based** form. You author a form as JSX children — each
-field is a `FormBuilder.*` component wired to [react-hook-form](https://react-hook-form.com/)
-for you.
-
-```tsx
-<FormBuilder onSubmit={save} resolver={zodResolver(schema)} defaultValues={d}>
-  <FormBuilder.Text name="name" label="Name" required />
-  <FormBuilder.Currency name="price" label="Price" currencySymbol="$" />
-</FormBuilder>
-```
-
-## FormBuilder is the fields — nothing else
-
-FormBuilder renders a `<form>`, its react-hook-form context, and your fields. Each field draws
-its own row (label, required marker, hint). Beyond that it draws **no frame at all**: no titled
-section cards, no page gutters, no scroll shell, no title header, no stepper rail, no summary
-column. Rendered bare it simply fills its container — which is what an embedded form wants (a
-settings rail, a `DataViews` filter panel).
-
-Everything drawn *around* the fields lives in **[FormRenderer](./form-renderer.md)**:
-
-| You want                              | Use                                                  |
-| ------------------------------------- | ---------------------------------------------------- |
-| A titled card grouping fields         | `FormRenderer.Section`                               |
-| A page title header + Save action bar | `FormRenderer`'s `header` and `actions` props        |
-| A wizard                              | `FormRenderer.Stepper` + `FormRenderer.Step`         |
-| A drawer                              | `FormRenderer` with `display="drawer"`               |
-| Live totals beside the form           | `FormRenderer`'s `summary` prop + [FormSummary](./form-summary.md) |
-| A read-only detail page               | `FormRenderer.Sidebar` + `FormRenderer.Tab`          |
-
-> **For real forms, reach for [FormRenderer](./form-renderer.md), not raw FormBuilder.** You still
-> author the fields as `FormBuilder.*` children — FormRenderer just wraps them.
-
-`FormBuilder.Submit` is the one non-field part that stays here — see
-[Field components](#field-components) for what it does. It renders the **primary action**: the blue
-filled button. There is deliberately no `variant` prop — a form has one primary action, and letting
-each call site pick a style is how that stops being true.
-
-## Installation
-
-TORCH Glare is a copy-in library: the CLI copies this component's source into your project.
-
-```bash
-npx torch-glare@latest init
-npx torch-glare@latest add FormBuilder
-```
-
-## Imports
-
-```tsx
-import { FormBuilder } from "@/components/FormBuilder";
-```
-
-## Root props
-
-| Prop             | Type                                | Notes                                                                                                                      |
-| ---------------- | ----------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
-| `onSubmit`       | `(values) => void \| Promise<void>` | Called on a valid submit.                                                                                                  |
-| `onInvalid`      | `(errors) => void`                  | Called when validation fails.                                                                                              |
-| `resolver`       | `Resolver`                          | Any react-hook-form resolver, e.g. `zodResolver(schema)`.                                                                  |
-| `defaultValues`  | `DefaultValues`                     | Initial values (create).                                                                                                   |
-| `values`         | `T`                                 | Controlled values (edit) — the form re-syncs when this changes.                                                            |
-| `loading`        | `boolean`                           | Submit shows a spinner; inputs disable.                                                                                    |
-| `fieldDirection` | `'horizontal' \| 'vertical' \| 'flexible'` | Row layout. Unset is responsive; a `FormRenderer` drawer pins `'vertical'`, and `'flexible'` asks for the responsive layout back.                                                                                |
-| `resetOnSuccess` | `boolean`                           | Reset to defaults after a successful submit.                                                                               |
-| `form`           | `UseFormReturn`                     | A hoisted `useForm` to bind to — pass when something outside the form must read the same values.                           |
-| `id`             | `string`                            | Sets the underlying `<form id>`, so a button outside the form can submit it via `form={id}` (e.g. a drawer header's Save). |
-| `className`      | `string`                            | Lands on the `<form>` element itself — e.g. `"min-w-0 flex-1"` to fill a flex parent.                                      |
-
-There is no `layout` prop and no `conclusion` prop: the fields always fill their container, and a
-panel beside the form is `FormRenderer`'s `summary`.
-
-## Field components
-
-Each is a JSX child taking at least `name`, plus `label`, `placeholder`,
-`description`, `required`, `disabled`, `hidden`, `fullWidth`, `hints`.
-
-### Hints
-
-`hints` stacks alerts under a field — helper text, a caveat, a confirmation. Each entry mirrors
-`FieldHint`: `label`, an optional `state` of `info` (default) / `warning` / `error` / `success`, and
-an optional `icon`.
-
-```tsx
-<FormBuilder.Text
-  name="sku"
-  label="SKU"
-  required
-  hints={[
-    { state: "info", label: "Must be unique across the catalogue." },
-    { state: "warning", label: "Changing this breaks existing links." },
-  ]}
-/>
-```
-
-The validation error is not one of these — it is rendered automatically and always comes **first**,
-because it is the actionable message; your hints follow in the order given. A field with no `hints`
-renders exactly as before.
-
-Hints are ignored inside a `FormBuilder.Table` cell (and any other `bare` context): there errors
-surface as a tooltip on the control so a row stays one line tall, and stacking alerts would defeat
-that.
-
-| Component                                                                   | Input                                                                                 | Value                                                        |
-| --------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- | ------------------------------------------------------------ |
-| `FormBuilder.Text` / `.Email` / `.Password`                                 | `InputField`                                                                          | `string`                                                     |
-| `FormBuilder.Number`                                                        | numeric `InputField`                                                                  | `number`                                                     |
-| `FormBuilder.Currency` (`currencySymbol`)                                   | `InputField` + symbol                                                                 | `number`                                                     |
-| `FormBuilder.Textarea`                                                      | `Textarea`                                                                            | `string`                                                     |
-| `FormBuilder.Slider` (`min,max,step,range`)                                 | `@radix-ui/react-slider`                                                              | `number` / `[number,number]`                                 |
-| `FormBuilder.Color` (`presets`, `alpha`)                                    | `ColorPicker` (full palette: SV area, hue, opacity, eyedropper, HEX/RGB/HSL, presets) | hex `string` (`#rrggbb`, or `#rrggbbaa` when opacity < 100%) |
-| `FormBuilder.Phone` (`defaultCountry`)                                      | `SearchableSelect` + `InputField`                                                     | `string`                                                     |
-| `FormBuilder.Select` (`options`)                                            | `Select`                                                                              | `string`                                                     |
-| `FormBuilder.SearchableSelect` (`options`, async: `onSearchChange`/`onLoadMore`/`hasMore`) | `SearchableSelect`                                                      | `string`                                                     |
-| `FormBuilder.MultiSelect` / `.Tags` (`options`)                             | `BadgeField`                                                                          | `string[]`                                                   |
-| `FormBuilder.RadioList` (`options`, each with optional `description`)       | boxed radio list                                                                      | `string`                                                     |
-| `FormBuilder.CheckboxGroup` (`options`, each with optional `description`)   | boxed checkbox list                                                                   | `string[]`                                                   |
-| `FormBuilder.RadioCards` (`options` with `description`)                     | `RadioCard`                                                                           | `string`                                                     |
-| `FormBuilder.Checkbox` (`subLabel`)                                         | `Checkbox` + inline label                                                             | `boolean`                                                    |
-| `FormBuilder.SwitchBox` (`subLabel`)                                        | `Switch` in a `#f9f9f9` box                                                           | `boolean`                                                    |
-| `FormBuilder.Otp` (`length`)                                                | `InputOTP`                                                                            | `string`                                                     |
-| `FormBuilder.Date`                                                          | `DatePicker`                                                                          | `Date`                                                       |
-| `FormBuilder.DateRange`                                                     | `DatePicker` (range)                                                                  | `{from,to}`                                                  |
-| `FormBuilder.DateMultiple`                                                  | `DatePicker` (multiple)                                                               | `Date[]`                                                     |
-| `FormBuilder.DateTime`                                                      | `DatePicker` (timePicker)                                                             | `Date`                                                       |
-| `FormBuilder.TreeSelect` (`nodes`, `getNodeId`, `getNodeLabel`, …)          | `SearchableTree`                                                                      | node id (`string`)                                           |
-| `FormBuilder.File` / `.Image` (`accept`, `multiple`)                        | `ImageAttachment`                                                                     | `File \| File[]`                                             |
-| `FormBuilder.RichText`                                                      | `TextEditor` (EditorJS)                                                               | `OutputData`                                                 |
-| `FormBuilder.Signature` (`penColor`)                                        | canvas pad                                                                            | PNG data-URL `string`                                        |
-| `FormBuilder.FieldArray` (`children` render fn, `defaultItem`)              | RHF `useFieldArray`                                                                   | `object[]`                                                   |
-| `FormBuilder.Table` (`columns`, `selectable`, `reorderable`, `defaultItem`) | editable grid in a `SectionBlock`                                                     | `object[]`                                                   |
-| `FormBuilder.Custom` (`render`)                                             | your control                                                                          | anything                                                     |
-
-`FormBuilder.Password` accepts `strengthMeter` (shows a `PasswordLevel` meter). `FormBuilder.FieldArray`
-renders a repeating list — its `children` is a render fn `(rowName, index, remove) => …` and sub-fields
-are named `${rowName}.field`.
-
-`FormBuilder.Table` is the **table-shaped** counterpart of `FieldArray` (value `object[]`): an editable
-grid where each row is a record and each column cell is any `FormBuilder.*` field. It renders its own
-`SectionBlock` (`variant="Table"` — the full-bleed table shell), so place it as a **top-level child** of
-the form, **not** inside a `FormRenderer.Section` — nesting produces a card inside a card. When you need a
-table that isn't a form field, compose the shell yourself with `SectionBlock variant="Table"` (see
-[SectionBlock → Table Variant](./section-block.md#table-variant)).
-
-Each column pairs a `header` with a `cell(rowName, index)` renderer — name the cell's field
-`${rowName}.<key>`. Set `width` to size a column; it is applied to both the header and the body cells.
-The section header carries the actions: an **Add New** button and a **Delete Row** button that's disabled
-until rows are checkbox-selected. A second **＋ Add New** sits below the grid. Both live *outside* the
-horizontal scroll container, so they stay put when a wide table is scrolled sideways. Rows support
-**checkbox selection** (+ select-all), **drag-drop reordering**, and — per column, via `sortKey` — a
-sort toggle in the header. Cells render
-"bare" (control only) with validation errors shown as a tooltip on the control, so a row stays one line
-tall, and each field passes `onTable` so it's borderless and blends into the grid. Practical cell fields
-are the compact ones — `Text`, `Number`, `Currency`, `Select`, `SearchableSelect`, `Date`, `Phone`,
-`Checkbox`, `SwitchBox`; wide fields (`RichText`, `Signature`, `File`) work but aren't suited to a cell.
-`FormBuilder.Phone` collapses to a **plain number input** in a cell — two controls in one cell is not a
-table column, so add a separate column (e.g. a `FormBuilder.Select` of dial codes) if you need the
-country code.
-
-```tsx
-<FormBuilder.Table
-  name="items"
-  title="Items"
-  color="Green"
-  addLabel="Add item"
-  defaultItem={{ item: "", category: "hardware", qty: 1, price: 0 }}
-  columns={[
-    {
-      header: "Item",
-      width: 200,
-      cell: (row) => <FormBuilder.Text name={`${row}.item`} required />,
-    },
-    {
-      header: "Category",
-      cell: (row) => <FormBuilder.Select name={`${row}.category`} options={CATEGORY} required />,
-    },
-    {
-      header: "Qty",
-      width: 110,
-      cell: (row) => <FormBuilder.Number name={`${row}.qty`} required />,
-    },
-    {
-      header: "Price",
-      width: 140,
-      cell: (row) => <FormBuilder.Currency name={`${row}.price`} currencySymbol="$" required />,
-    },
-  ]}
-/>
-```
-
-`FormBuilder.RadioList` (single-select, `string`) and `FormBuilder.CheckboxGroup` (multi-select,
-`string[]`) render their `options` as a boxed, divided list — control on the left, primary
-label, and an optional per-option `description` shown as a secondary label. The whole row is
-clickable. Multi-select is also available as `.MultiSelect` / `.Tags` (a tag-chip picker).
-
-`FormBuilder.SwitchBox` (value `boolean`) is a switch wrapped in a `#f9f9f9` field box. It
-renders like any other field — the `label` sits in the normal label column — and the box holds
-an optional inline `subLabel`, a vertical divider, and the switch.
-
-To group fields into a titled card, use [`FormRenderer.Section`](./form-renderer.md) — it is
-presentation, so it lives there.
-
-`FormBuilder.Submit` is a loading-aware submit button. It **auto-associates with the enclosing
-form** (via context), so it submits even when placed in a header / action bar that renders
-_outside_ the `<form>` — no manual `form={id}` wiring.
-
-## Moved to FormRenderer
-
-These all used to live here. They are chrome, so they now live on
-[FormRenderer](./form-renderer.md):
-
-| Was | Now |
-| --- | --- |
-| `FormBuilder.Section` | `FormRenderer.Section` |
-| `FormBuilder.Stepper` / `.Step` / `.Back` / `.Next` | `FormRenderer.Stepper` / `.Step` / `.Back` / `.Next` |
-| `FormBuilder.Header` | `FormRenderer`'s `header` prop |
-| the `layout` prop | gone — the fields always fill their container |
-| the `conclusion` prop | `FormRenderer`'s `summary` prop |
-
-See [the migration note](../migration/form-builder-2.5.2.md) for the full upgrade path.
-
-## Calculation panel
-
-To show computed totals **beside** the form, render a [FormSummary](./form-summary.md)
-next to it (not inside it) and share one hoisted form via the `form` prop:
-
-```tsx
-const form = useForm({ resolver: r, defaultValues: d })
-
-<div className="flex items-start gap-4">
-  <FormBuilder form={form} onSubmit={save} className="min-w-0 flex-1">…fields…</FormBuilder>
-  <FormSummary form={form} title="Invoice">…rows…</FormSummary>
-</div>
-```
-
-`form` makes FormBuilder use an existing react-hook-form instance instead of creating its
-own — that's what lets something outside the form read the same live values.
-
-## Editing a record
-
-Pass `values` (not just `defaultValues`); the form repopulates when the data loads. Use a
-remount `key` so initial-only inputs (date, rich text) re-seed.
-
-```tsx
-<FormBuilder key={entity.id} values={entity} onSubmit={save} resolver={r} defaultValues={d}>
-  …the same fields…
-</FormBuilder>
-```
-
-## Validation
-
-Resolver-agnostic — pass any react-hook-form `resolver` (`zodResolver`, a plain
-resolver function, etc.). The library never depends on zod.

package/docs/components/form-renderer.md

@@ -1,326 +0,0 @@
----
-title: FormRenderer
-description: The chrome around a FormBuilder. Author fields as JSX children; FormRenderer owns page-vs-drawer display, the title header, the actions bar, titled Sections, the stepper, and the summary panel. Prefer it over raw FormBuilder for real forms.
-component: true
-group: Forms
-keywords:
-  [form-renderer, form, drawer, header, display, actions, section, stepper, summary, react-hook-form]
----
-
-# FormRenderer
-
-The **chrome** around a [FormBuilder](./form-builder.md). You author the fields as **JSX
-children** (`FormBuilder.Text`, `FormBuilder.Select`, …); `FormRenderer` draws everything
-around them:
-
-- **page vs drawer** display (`display="drawer"` hosts the form in a `FormDrawer`),
-- the **absolute title header** + `actions` bar,
-- **`FormRenderer.Section`** — the titled cards that group fields,
-- the **stepper** (`FormRenderer.Stepper` / `.Step`) and its nav rail,
-- the **`summary`** panel beside the form,
-- the page gutters and scroll shell, and **vertical field layout** inside a drawer.
-
-`FormBuilder` on its own is the fields and nothing else — no card, no header, no frame — so it
-fills whatever it is placed in. **For real forms, use `FormRenderer`**; reach for bare
-`FormBuilder` only when you are embedding fields inside something that already provides its own
-chrome (a settings rail, a filter panel).
-
-FormRenderer has **two modes**: a **form** (author fields as children, as below), or a display-only
-**detail page** — give it `FormRenderer.Sidebar` + `FormRenderer.Tab` children instead of fields and the
-sidebar swaps `FormRenderer.Tab` panels, whose content is `FormRenderer.Section` blocks (no `<form>`,
-no submit — see [Detail tabs](#detail-tabs-sidebar)).
-
-FormRenderer never manufactures a Submit — **you compose the Save and hand it to `actions`**.
-It renders in the form's header action pill (page) or the drawer header (drawer), and a bare
-`<FormBuilder.Submit>` auto-targets this form (even though the header sits outside the `<form>`).
-
-```tsx
-<FormRenderer
-  onSubmit={save}
-  resolver={zodResolver(schema)}
-  defaultValues={d}
-  header={{ title: "Item", variant: "new" }}
-  actions={<FormBuilder.Submit>Save</FormBuilder.Submit>}
->
-  <FormRenderer.Section title="Identity" color="Blue">
-    <FormBuilder.Text name="name" label="Name" required />
-    <FormBuilder.Currency name="price" label="Price" currencySymbol="$" />
-  </FormRenderer.Section>
-</FormRenderer>
-```
-
-## Compound parts
-
-| Part                                        | What it is                                                                     |
-| ------------------------------------------- | ------------------------------------------------------------------------------ |
-| `FormRenderer.Section`                      | A titled `SectionBlock` card grouping fields (or display rows).                 |
-| `FormRenderer.Stepper` / `.Step`            | The wizard — see [Stepper](#stepper).                                          |
-| `FormRenderer.Back` / `.Next`               | Chevron step controls. The header's action bar prepends them for you.           |
-| `FormRenderer.Sidebar` / `.Tab`             | The display-only [detail-tabs](#detail-tabs-sidebar) view.                     |
-| `FormRenderer.Grid` / `.Row`                | Read-only display cells inside a detail tab.                                    |
-
-### `FormRenderer.Section`
-
-Props `title`, `color`, `icon`, `action`, `variant`. It groups fields in a Glare `SectionBlock`:
-`color` is one of `Blue`, `Yellow`, `Green`, `Red`, `Orange`, `Purple`, `Pink`, `Gray`; `action`
-puts buttons on the title row; `variant="Table"` switches to the full-bleed table shell (what
-`FormBuilder.Table` uses internally).
-
-It holds no form state, which is why it lives here and not on `FormBuilder` — the same component
-groups editable fields on a form and read-only `FormRenderer.Row` cells on a detail page.
-
-Because it reads no context, it also works **outside** `<FormRenderer>` — e.g. wrapping fields in a
-bare `<FormBuilder>` that you are laying out yourself. It is the one compound part that does.
-
-> Not to be confused with `FieldSection`, the per-field row layout (label · control) that every
-> field draws for itself. That one stays inside FormBuilder.
-
-## Installation
-
-```bash
-npx torch-glare@latest init
-npx torch-glare@latest add FormRenderer
-```
-
-`add` also pulls in `FormBuilder`, which FormRenderer renders through.
-
-## Imports
-
-```tsx
-import { FormRenderer, FormDrawer } from "@/components/FormRenderer";
-import { FormBuilder } from "@/components/FormBuilder";
-```
-
-## Props
-
-| Prop                                                           | Type                          | Notes                                                                                                                                                                                                                                                                            |
-| -------------------------------------------------------------- | ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `children`                                                     | `ReactNode`                   | The form body — `FormRenderer.Section` / field / `FormRenderer.Stepper` JSX.                                                                                                                                                                                                       |
-| `onSubmit?` / `onInvalid?`                                     | fns                           | Submit / validation-fail callbacks. Optional — a detail-tabs view has no form, so omit them there.                                                                                                                                                                               |
-| `resolver`                                                     | `Resolver`                    | Any react-hook-form resolver, e.g. `zodResolver(schema)`.                                                                                                                                                                                                                        |
-| `defaultValues` / `values`                                     | `DefaultValues` / `T`         | Initial values; `values` re-syncs on change (edit).                                                                                                                                                                                                                              |
-| `loading` / `resetOnSuccess`                                   | `boolean`                     | Forwarded to `FormBuilder`.                                                                                                                                                                                                                                                      |
-| `fieldDirection`                                               | `'horizontal' \| 'vertical' \| 'flexible'`  | Unset means responsive: stacked, then label-beside-control once the field row passes the container `md` breakpoint. A drawer defaults to `'vertical'` — pass `'flexible'` there to get the responsive layout back.                                                                                                                                                                                                                                            |
-| `form`                                                         | `UseFormReturn<T>`            | A hoisted `useForm` to bind to — pass when a sibling (e.g. a `summary` `FormSummary`) must read the same live values; the caller owns `resolver`/`defaultValues` on it. Omit to let FormRenderer create its own.                                                                 |
-| `className`                                                    | `string`                      | Lands on FormRenderer's outermost element (page display) — e.g. `"min-h-0 flex-1"` to fill a flex column. Note this is the page frame, not the `<form>`; `FormBuilder`'s own `className` lands on the `<form>` element itself.                                                    |
-| `display`                                                      | `'page' \| 'drawer'`          | `'drawer'` wraps the form in `FormDrawer`.                                                                                                                                                                                                                                       |
-| `header`                                                       | `{ title; label?; variant? }` | Absolute title header + action bar (page display); `actions` render in it.                                                                                                                                                                                                       |
-| `summary`                                                      | `ReactNode`                   | A live panel (typically `FormSummary`) rendered beside the form (page) or in the drawer tray (drawer). Give the same hoisted `form` so it reads live values. On a page, a `summary` **plus** a `FormRenderer.Stepper` lays out as three columns — stepper nav · fields · summary. |
-| `actions`                                                      | `ReactNode`                   | The form's action bar — rendered in the header action pill (page) or drawer header (drawer). Put the Save here: `actions={<FormBuilder.Submit>Save</FormBuilder.Submit>}`. A bare `FormBuilder.Submit` auto-targets this form.                                                   |
-| `id`                                                           | `string`                      | `id` on the underlying `<form>`. Optional — FormRenderer generates and wires one otherwise.                                                                                                                                                                                      |
-| `open` / `onOpenChange` / `title` / `badge` / `onOpenInNewTab` | —                             | Drawer control (when `display="drawer"`). `title` / `badge` are strings that override `header.title` / `header.label`.                                                                                                                                                           |
-
-## Drawer
-
-```tsx
-// drawer — pass the Save via `actions`; it renders in the drawer header
-<FormRenderer
-  display="drawer"
-  open={open}
-  onOpenChange={setOpen}
-  title="New item"
-  badge="New"
-  onSubmit={save}
-  resolver={r}
-  defaultValues={d}
-  actions={<FormBuilder.Submit>Save</FormBuilder.Submit>}
->
-  {fields}
-</FormRenderer>
-```
-
-## Stepper
-
-Drop a `FormRenderer.Stepper` in as the child. The Save lives in the header `actions` and
-submits every step's registered fields at once (steps stay mounted, so the whole form is live).
-
-For a stepper, FormRenderer **automatically prepends chevron Back/Next nav + a divider** before
-your Submit, so the action bar reads `[◀] [▶] │ Save`. Back is disabled on the first step; Next
-validates the current step, then advances (disabled on the last step). A step that passes
-validation **stays checked** in the rail — even after you navigate back — while a live validation
-error overrides it to red. You still pass just the Submit; the nav is wired for you:
-
-```tsx
-<FormRenderer
-  onSubmit={save}
-  resolver={r}
-  defaultValues={d}
-  header={{ title: "New item", variant: "new" }}
-  actions={<FormBuilder.Submit>Save</FormBuilder.Submit>}
->
-  <FormRenderer.Stepper>
-    <FormRenderer.Step title="Basics">
-      <FormBuilder.Text name="name" label="Name" required />
-    </FormRenderer.Step>
-  </FormRenderer.Stepper>
-</FormRenderer>
-```
-
-## Detail tabs (sidebar)
-
-Give FormRenderer `FormRenderer.Sidebar` + `FormRenderer.Tab` children (instead of fields) and it
-switches to a **display-only detail page**: a left **sidebar** where each item swaps in its matching
-tab panel — no `<form>`, no submit. The sidebar sits **where a stepper's rail would**, and only the
-active panel shows (built on the same Radix Tabs primitive shadcn uses, so it's keyboard-accessible).
-Pair it with `header` (`variant="detail"` → a "View" badge) + `actions` (Print / Approve / …).
-
-Each `Tab` holds read-only `FormRenderer.Section` blocks; `FormRenderer.Grid` + `FormRenderer.Row` lay
-out the label/value display cells (the display counterpart of form fields).
-
-```tsx
-<FormRenderer
-  header={{ title: "Order DE-344", variant: "detail" }}
-  actions={<Button variant="BorderStyle">Print</Button>}
->
-  {/* The rail — one Item per tab, tied to a Tab by `value`. */}
-  <FormRenderer.Sidebar>
-    <FormRenderer.Sidebar.Item value="overview" icon={<i className="ri-layout-grid-line" />}>
-      Overview
-    </FormRenderer.Sidebar.Item>
-    <FormRenderer.Sidebar.Item value="items" icon={<i className="ri-table-line" />}>
-      Items Table
-    </FormRenderer.Sidebar.Item>
-  </FormRenderer.Sidebar>
-
-  {/* One panel per tab — read-only Section blocks. */}
-  <FormRenderer.Tab value="overview">
-    <FormRenderer.Section title="Main Information" color="Blue">
-      <FormRenderer.Grid>
-        <FormRenderer.Row label="PO Number" value="PO-000123" />
-        <FormRenderer.Row label="Status" value={<Badge label="Submitted" color="yellow" />} />
-      </FormRenderer.Grid>
-    </FormRenderer.Section>
-  </FormRenderer.Tab>
-
-  <FormRenderer.Tab value="items">…</FormRenderer.Tab>
-</FormRenderer>
-```
-
-| Component      | Props                      | Renders                                                            |
-| -------------- | -------------------------- | ------------------------------------------------------------------ |
-| `Sidebar`      | `children`                 | The tab rail (a Radix `Tabs.List`), fixed at the stepper's place.  |
-| `Sidebar.Item` | `value`, `icon?`, children | A rail nav row (a `Tabs.Trigger`); the active one is a black pill. |
-| `Tab`          | `value`, children          | A content panel (a `Tabs.Content`) shown when its tab is active.   |
-| `Grid`         | `columns?` (1–3), children | A padded grid of display `Row`s (default 2 columns).               |
-| `Row`          | `label`, `value`           | A read-only label/value display cell.                              |
-
-The first `Tab` is active by default. Only the active panel is visible; the rail stays fixed while the
-content column scrolls.
-
-## Summary panel
-
-Pass a hoisted `useForm` as `form` and a `FormSummary` as `summary` — FormRenderer binds
-the form to that instance and lays the panel beside the form (page) or in the drawer tray
-(drawer), so it recomputes live as fields change.
-
-```tsx
-const form = useForm<Invoice>({ resolver, defaultValues })
-
-<FormRenderer
-  form={form}
-  onSubmit={save}
-  header={{ title: 'Invoice', variant: 'new' }}
-  actions={<FormBuilder.Submit>Save invoice</FormBuilder.Submit>}
-  summary={
-    <FormSummary form={form} title="Invoice" subtitle="Summary">
-      <FormSummary.Group title="Total">
-        <FormSummary.Row label="Overall Total" emphasized compute={overallTotal} />
-      </FormSummary.Group>
-    </FormSummary>
-  }
->
-  {fields}
-</FormRenderer>
-```
-
-Works with `display="drawer"` too — the summary moves into the drawer's tray.
-
-## `FormDrawer` — the drawer wrapper
-
-`FormRenderer` uses `FormDrawer` internally for `display: 'drawer'`. It's also exported
-so you can put a hand-composed `FormBuilder` in a drawer directly. Since the header sits
-outside the `<form>`, wire the Save button to the form via `id` / `form={id}`:
-
-```tsx
-<FormDrawer
-  open={open}
-  onOpenChange={setOpen}
-  title="New item"
-  badge="New"
-  actions={
-    <Button type="submit" form="item-form" is_loading={saving}>
-      Save
-    </Button>
-  }
->
-  <FormBuilder
-    id="item-form"
-    onSubmit={save}
-    resolver={r}
-    defaultValues={d}
-    fieldDirection="vertical"
-  >
-    …fields…
-  </FormBuilder>
-</FormDrawer>
-```
-
-`FormDrawer` props: `open`, `onOpenChange`, `title`, `badge`, `variant`, `actions`,
-`onOpenInNewTab`, `children`, `summary`. It owns no form state.
-
-### The title
-
-The drawer renders the **same floating header as the page form** — a [HeaderBar](./header-bar.md)
-title pill on the left, a dark action pill on the right — so a form's title looks identical in
-either display. `title` is the plain (uppercased) text, `badge` the colored emphasis pill, and
-`variant` (`new` / `edit` / `detail`) picks the badge colors; `badge` defaults from it
-(New / Edit / View).
-
-```tsx
-<FormDrawer title="Sales Invoice" badge="New" variant="new" … />
-```
-
-Driving it through `FormRenderer`, the `header` prop feeds both displays — including
-`header.variant`, which the drawer previously ignored:
-
-```tsx
-<FormRenderer display="drawer" header={{ title: "Sales Invoice", variant: "edit" }} … />
-```
-
-`title` and `badge` are **plain strings** (they were `ReactNode` before this shared-header
-change) because they render through `HeaderBar`'s uppercase text treatment.
-
-### A summary beside the form
-
-`summary` renders a conclusion panel — typically a [FormSummary](./form-summary.md) — _beside_
-the form rather than inside its scrollable body. `FormDrawer` puts the form in a
-[`DrawerPanel`](./drawer.md#drawerpanel) (the light surface) and the summary next to it with a
-6px gutter; the tray paints nothing, so the summary keeps its own dark background and full
-height, scrolling internally when it outruns the drawer.
-
-Hoist the form so both read the same instance:
-
-```tsx
-const form = useForm({ resolver, defaultValues })
-
-<FormDrawer
-  open={open} onOpenChange={setOpen} title="New item" badge="New"
-  summary={
-    <FormSummary form={form} title="Item" subtitle="Summary">
-      <FormSummary.Group title="Pricing">…rows…</FormSummary.Group>
-    </FormSummary>
-  }
->
-  <FormBuilder form={form} id="item-form" onSubmit={save} fieldDirection="vertical">
-    …fields…
-  </FormBuilder>
-</FormDrawer>
-```
-
-> `childrenOutside` is the deprecated former name for `FormDrawer`'s `summary`. It still
-> works — it long predates the FormBuilder/FormRenderer split and is unrelated to it (that
-> move ships no aliases; see the
-> [migration note](../migration/form-builder-2.5.2.md)).
-
-`FormRenderer` forwards `summary` straight into the drawer tray, so you rarely need
-`FormDrawer` directly — reach for it only when you want the drawer without a form.