torch-glare 2.5.1 → 2.5.3

package/docs/components/data-views/index.md

@@ -188,6 +188,13 @@ Each takes `id`, `label` and `icon` to control how it appears in the switcher, s
 be registered twice with different data. Full props are under
 [API Reference](#api-reference) — one heading per part.
 
+Two things `DataViews.Table` does for you that you would otherwise wire by hand: its column header
+**stays put while the rows scroll under it**, and the view draws **its own border and radius**, so it
+reads as a separated surface like the inbox and tree panels rather than filling the shell edge to
+edge. Long column labels truncate with an ellipsis instead of wrapping the header row onto a second
+line. Inside `DataViews.Tree`, the same table drops that border — the tree's pane already draws one,
+and two would nest a pixel apart.
+
 ### The tree's pane
 
 Pick a node and the pane beside it lists what that node holds. Its header names the selected node

package/docs/components/form-builder.md

@@ -1,31 +1,63 @@
 ---
 title: FormBuilder
-description: A compound, composition-based form. Author forms as JSX children (FormBuilder.Text, FormBuilder.Select, …) with steps-as-components, a drawer wrapper, and any react-hook-form resolver.
+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, stepper, drawer, fields]
+  [
+    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. Steps are components and the drawer is a wrapper.
+for you.
 
 ```tsx
 <FormBuilder onSubmit={save} resolver={zodResolver(schema)} defaultValues={d}>
-  <FormBuilder.Section title="Identity" color="Blue">
-    <FormBuilder.Text name="name" label="Name" required />
-    <FormBuilder.Currency name="price" label="Price" currencySymbol="$" />
-  </FormBuilder.Section>
-  <FormBuilder.Submit>Save</FormBuilder.Submit>
+  <FormBuilder.Text name="name" label="Name" required />
+  <FormBuilder.Currency name="price" label="Price" currencySymbol="$" />
 </FormBuilder>
 ```
 
-> Need the same form to render as a page _or_ a drawer, with a title header and an
-> `actions` slot for the Save? Wrap these same children in
-> [FormRenderer](./form-renderer.md).
+## 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
 
@@ -52,20 +84,14 @@ import { FormBuilder } from "@/components/FormBuilder";
 | `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'`        | Row layout (auto-vertical inside a drawer).                                                                                |
+| `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 a `conclusion` panel must read the same values.                                 |
-| `conclusion`     | `ReactNode`                         | A live panel (e.g. `FormSummary`) rendered **outside** the `<form>` as the grid's right column.                            |
+| `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's outermost element — e.g. `"min-w-0 flex-1"` to fill the space beside a `conclusion` panel.             |
+| `className`      | `string`                            | Lands on the `<form>` element itself — e.g. `"min-w-0 flex-1"` to fill a flex parent.                                      |
 
-**Adaptive layout.** FormBuilder lays out responsively: a `FormBuilder.Stepper` puts its nav rail in
-a **left** column beside the fields (both inside the form surface, under the title header), and a
-`conclusion` renders as its own panel **outside** the form surface, beside it — the same structure
-`FormDrawer` uses in the drawer tray (6px gutter). So a stepper + conclusion reads as three columns
-(nav · fields · conclusion), a conclusion alone as two, and a plain form as one. The fields column
-caps at 1100px and centers. The conclusion is outside the `<form>` and reads values via its own
-`form` prop.
+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
 
@@ -109,7 +135,7 @@ 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 `FormBuilder.Section` — nesting produces a card inside a card. When you need a
+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)).
 
@@ -168,77 +194,27 @@ clickable. Multi-select is also available as `.MultiSelect` / `.Tags` (a tag-chi
 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.
 
-`FormBuilder.Section` (props `title`, `color`, `icon`, `action`, `variant`) groups fields in a Glare
-`SectionBlock`. `action` puts buttons on the title row; `variant="Table"` switches to the
-full-bleed table shell (what `FormBuilder.Table` uses internally). `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.
-
-## Title header + action bar
-
-`FormBuilder.Header` renders a **title pill** (Glare `HeaderBar`) on the left and an
-**action bar** (your buttons) on the right, **absolutely positioned** over a
-scrollable form body — the products-services item-edit look. Place it as a direct
-child of `<FormBuilder>`; the root then switches to the scroll-shell layout.
-
-```tsx
-<FormBuilder onSubmit={save} resolver={r} defaultValues={d}>
-  <FormBuilder.Header title="Item" variant="new">
-    <FormBuilder.Submit>Save</FormBuilder.Submit>
-    {/* add more actions, e.g. a "Save as draft" Button */}
-  </FormBuilder.Header>
-
-  <FormBuilder.Section title="Identity" color="Blue">
-    <FormBuilder.Text name="name" label="Name" required />
-  </FormBuilder.Section>
-</FormBuilder>
-```
-
-- `title` — plain text (uppercased). `label` — badge text (defaults from `variant`).
-- `variant` — `"new" | "edit" | "detail"` (badge color; default `"new"`). `children` are
-  the action buttons; `FormBuilder.Submit` submits the form (it auto-associates with it, even
-  though the header sits outside `<form>`).
+To group fields into a titled card, use [`FormRenderer.Section`](./form-renderer.md) — it is
+presentation, so it lives there.
 
-## Stepper (steps are components)
+`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.
 
-Wrap steps in `FormBuilder.Stepper`; each `FormBuilder.Step` holds a step's fields.
-**Every step's fields are always mounted and registered** — the whole form is live
-regardless of which step is showing; the stepper only toggles _visibility_.
-**Navigation is the step buttons themselves**: click a step to go there. Backward is
-free; clicking forward validates the steps in between and stops at the first one with
-errors (shown with a red indicator). A step that **passes validation stays checked** even
-after you navigate back to it. Put the **Submit** in the `FormBuilder.Header` (or the
-`FormRenderer` `actions`) — it submits every step's fields at once, from any step.
+## Moved to FormRenderer
 
-`FormBuilder.Back` / `FormBuilder.Next` are **chevron step-nav buttons** (previous / next,
-disabled at the ends; `Next` validates the current step first). Place them in a
-`FormBuilder.Header`, or use `FormRenderer` — it prepends them before your Submit for a stepper
-automatically.
-
-```tsx
-<FormBuilder onSubmit={save} resolver={r} defaultValues={d}>
-  <FormBuilder.Header title="Item" variant="new">
-    <FormBuilder.Submit>Save</FormBuilder.Submit>
-  </FormBuilder.Header>
-
-  <FormBuilder.Stepper>
-    <FormBuilder.Step title="Basics">
-      <FormBuilder.Text name="name" label="Name" required />
-    </FormBuilder.Step>
-    <FormBuilder.Step title="Details">
-      <FormBuilder.Select name="category" label="Category" required options={cats} />
-    </FormBuilder.Step>
-  </FormBuilder.Stepper>
-</FormBuilder>
-```
+These all used to live here. They are chrome, so they now live on
+[FormRenderer](./form-renderer.md):
 
-> **In a drawer?** `FormBuilder` is drawer-unaware — it only displays inputs. To
-> show a form in a drawer, wrap it in `FormDrawer` from
-> [FormRenderer](./form-renderer.md) (pass `fieldDirection="vertical"` to the
-> form), or use `FormRenderer` with `display="drawer"`.
+| 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 |
 
-> Building a **detail page** with a sidebar of tabs (not a form)? That lives on `FormRenderer`
-> (`FormRenderer.Sidebar` / `.Tab`) — see the FormRenderer docs. `FormBuilder` itself stays form-only.
+See [the migration note](../migration/form-builder-2.5.2.md) for the full upgrade path.
 
 ## Calculation panel
 

package/docs/components/form-renderer.md

@@ -1,33 +1,39 @@
 ---
 title: FormRenderer
-description: A thin wrapper around FormBuilder. Author fields as JSX children; FormRenderer owns page-vs-drawer display, the absolute title header, and drawer field layout. You compose the Save and pass it via the actions prop.
+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, react-hook-form]
+keywords:
+  [form-renderer, form, drawer, header, display, actions, section, stepper, summary, react-hook-form]
 ---
 
 # FormRenderer
 
-A thin wrapper around the compound [FormBuilder](./form-builder.md). You author the
-fields as **JSX children** exactly as you would with `FormBuilder`; `FormRenderer`
-takes care of the surrounding concerns:
+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** + action bar (page display),
-- **vertical field layout** inside a drawer.
+- 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 `FormBuilder.Section` panels (no `<form>`, no submit — see [Detail tabs](#detail-tabs-sidebar)).
+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>`).
 
-Reach for `FormBuilder` directly when you just want the form. Reach for
-`FormRenderer` when you want the same form to render as a page _or_ a drawer with
-the standard chrome.
-
 ```tsx
 <FormRenderer
   onSubmit={save}
@@ -36,13 +42,39 @@ the standard chrome.
   header={{ title: "Item", variant: "new" }}
   actions={<FormBuilder.Submit>Save</FormBuilder.Submit>}
 >
-  <FormBuilder.Section title="Identity" color="Blue">
+  <FormRenderer.Section title="Identity" color="Blue">
     <FormBuilder.Text name="name" label="Name" required />
     <FormBuilder.Currency name="price" label="Price" currencySymbol="$" />
-  </FormBuilder.Section>
+  </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
@@ -63,16 +95,17 @@ import { FormBuilder } from "@/components/FormBuilder";
 
 | Prop                                                           | Type                          | Notes                                                                                                                                                                                                                                                                            |
 | -------------------------------------------------------------- | ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `children`                                                     | `ReactNode`                   | The form body — `FormBuilder.Section` / field / `FormBuilder.Stepper` JSX.                                                                                                                                                                                                       |
+| `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'`  | Defaults to vertical inside a drawer.                                                                                                                                                                                                                                            |
+| `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 `FormBuilder.Stepper` lays out as three columns — stepper nav · fields · summary. |
+| `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`.                                                                                                                                                           |
@@ -98,7 +131,7 @@ import { FormBuilder } from "@/components/FormBuilder";
 
 ## Stepper
 
-Drop a `FormBuilder.Stepper` in as the child. The Save lives in the header `actions` and
+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
@@ -115,11 +148,11 @@ error overrides it to red. You still pass just the Submit; the nav is wired for
   header={{ title: "New item", variant: "new" }}
   actions={<FormBuilder.Submit>Save</FormBuilder.Submit>}
 >
-  <FormBuilder.Stepper>
-    <FormBuilder.Step title="Basics">
+  <FormRenderer.Stepper>
+    <FormRenderer.Step title="Basics">
       <FormBuilder.Text name="name" label="Name" required />
-    </FormBuilder.Step>
-  </FormBuilder.Stepper>
+    </FormRenderer.Step>
+  </FormRenderer.Stepper>
 </FormRenderer>
 ```
 
@@ -131,7 +164,7 @@ tab panel — no `<form>`, no submit. The sidebar sits **where a stepper's rail
 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 `FormBuilder.Section` blocks; `FormRenderer.Grid` + `FormRenderer.Row` lay
+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
@@ -151,12 +184,12 @@ out the label/value display cells (the display counterpart of form fields).
 
   {/* One panel per tab — read-only Section blocks. */}
   <FormRenderer.Tab value="overview">
-    <FormBuilder.Section title="Main Information" color="Blue">
+    <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>
-    </FormBuilder.Section>
+    </FormRenderer.Section>
   </FormRenderer.Tab>
 
   <FormRenderer.Tab value="items">…</FormRenderer.Tab>
@@ -284,7 +317,10 @@ const form = useForm({ resolver, defaultValues })
 </FormDrawer>
 ```
 
-> `childrenOutside` is the deprecated former name for `summary`. It still works.
+> `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.

package/docs/components/form-summary.md

@@ -16,14 +16,19 @@ Each `FormSummary.Row` declares a **`compute(values)`** that runs against the **
 form values, so every total recalculates as the user types.
 
 The panel renders **outside** the form, beside it. Both read the same form, so
-**hoist `useForm`** and hand the instance to each:
+**hoist `useForm`** and hand the instance to each.
+
+> **Normally you do not lay this out by hand.** Pass the panel to
+> [`FormRenderer`](./form-renderer.md)'s `summary` prop and it places it for you — beside the form
+> on a page, in the tray in a drawer. The manual version below is what `summary` does, and is what
+> you want only when you are composing a bare `<FormBuilder>` yourself.
 
 ```tsx
 const form = useForm({ resolver: zodResolver(schema), defaultValues })
 
 <div className="flex gap-4">
   <FormBuilder form={form} onSubmit={save} className="min-w-0 flex-1">
-    <FormBuilder.Section title="Line items">…fields…</FormBuilder.Section>
+    <FormRenderer.Section title="Line items">…fields…</FormRenderer.Section>
   </FormBuilder>
 
   <FormSummary form={form} title="Invoice" subtitle="Summary">
@@ -71,6 +76,10 @@ npx torch-glare@latest add FormSummary
 ## Imports
 
 ```tsx
+import { useForm } from 'react-hook-form'
+
+import { FormBuilder } from '@/components/FormBuilder'
+import { FormRenderer } from '@/components/FormRenderer'
 import { FormSummary } from '@/components/FormSummary'
 ```
 
@@ -80,7 +89,7 @@ import { FormSummary } from '@/components/FormSummary'
 |---|---|---|
 | `title` | `ReactNode` | Panel title, e.g. `"Invoice"`. |
 | `subtitle` | `ReactNode` | Muted text beside the title, e.g. `"Summary"`. |
-| `form` | `UseFormReturn` | The form to read values from — required when rendered outside the `<FormBuilder>`. |
+| `form` | `UseFormReturn` | The form to read values from. The panel always renders outside the `<form>`, so pass the same hoisted instance you gave `FormRenderer` / `FormBuilder`. |
 | `width` | `number \| string` | Panel width; default `228`. |
 | `children` | `ReactNode` | `FormSummary.Group` children. |
 
@@ -121,3 +130,9 @@ const overallTotal  = v => taxable(v) + totalTax(v)
 ```
 
 The panel is **read-only** — it contributes nothing to the submitted values.
+
+## Related
+
+- [FormRenderer](./form-renderer.md) — its `summary` prop places this panel for you
+- [FormBuilder](./form-builder.md) — the fields the totals read from
+- [ConclusionHeader](./conclusion-header.md) — the header this panel uses

package/docs/components/section-block.md

@@ -435,7 +435,7 @@ import {
 ```
 
 For a table that edits form values, don't hand-compose this — use
-[`FormBuilder.Table`](./form-builder.md#formbuildertable), which renders exactly this shell
+[`FormBuilder.Table`](./form-builder.md#field-components), which renders exactly this shell
 and wires rows to `react-hook-form`.
 
 ### Custom Layout (override defaults)

package/docs/components/table.md

@@ -363,6 +363,39 @@ function ResizableTable() {
 | `className` | `string` | - | Additional CSS classes |
 | `children` | `React.ReactNode` | - | Header rows |
 
+#### Sticky header
+
+`TableHeader` carries `position: sticky; top: 0`, so a table inside a vertically scrolling container
+can keep its header in view while the rows move under it. Sticky keeps the element in normal flow,
+so it changes nothing in a table that does not scroll.
+
+It needs two things from you.
+
+**Pass `overflow-visible`.** Sticky resolves against the **nearest scrollport**, and `Table` defaults
+to `overflow-hidden` — which makes the table itself a scrollport, so the header pins to a box that
+never scrolls and appears not to stick. Turning that clipping off binds it to your scroller instead.
+
+Only do this when your scroller is `min-w-0` (or otherwise width-constrained). That default clipping
+is also what stops a `w-auto` table wider than its container from pushing the whole page wide, so
+opting out without a constrained scroller trades a sticky header for a horizontal scrollbar.
+
+**Give the header an opaque background** — see below.
+
+```tsx
+{/* `min-w-0` so a wide table scrolls in here rather than widening the layout */}
+<div className="min-w-0 max-h-[400px] overflow-auto">
+  <Table className="w-full overflow-visible">
+    <TableHeader className="bg-background-presentation-form-base">
+      ...
+```
+
+The default header background is translucent, which was fine when nothing ever passed beneath it.
+Once rows scroll under a stuck header they read through it, so give
+the header the opaque colour of whatever surface it sits on — `Table` cannot pick one for you,
+since forcing a surface would recolour every table not on it. `DataViews`' table view is the worked
+example: it paints the surface token as the background colour and re-applies the header tint as a
+`background-image`, which stacks above it, landing on the exact colour the header always had.
+
 ### TableBody Props
 
 | Prop | Type | Default | Description |