torch-glare 2.4.1 → 2.4.2

package/docs/components/form-builder.md

@@ -0,0 +1,270 @@
+---
+title: FormBuilder
+description: A compound, composition-based form. Author forms as JSX children (FormBuilder.Text, FormBuilder.Select, …) with steps-as-components, a drawer wrapper, edit + read-only view modes, and any react-hook-form resolver.
+component: true
+group: Forms
+keywords:
+  [
+    form-builder,
+    form,
+    compound,
+    composition,
+    react-hook-form,
+    resolver,
+    stepper,
+    drawer,
+    fields,
+    view-mode,
+  ]
+---
+
+# 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, the drawer is a wrapper, and the same markup renders
+editable or read-only.
+
+```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>
+```
+
+> 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).
+
+## 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.                                                            |
+| `mode`           | `'edit' \| 'view'`                  | `'view'` renders every field read-only.                                                                                    |
+| `loading`        | `boolean`                           | Submit shows a spinner; inputs disable.                                                                                    |
+| `fieldDirection` | `'horizontal' \| 'vertical'`        | Row layout (auto-vertical inside a drawer).                                                                                |
+| `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.                            |
+| `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.             |
+
+**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.
+
+## Field components
+
+Each is a JSX child taking at least `name`, plus `label`, `placeholder`,
+`description`, `required`, `disabled`, `hidden`, `fullWidth`.
+
+| 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` / `.SearchableSelect` (`options`, async props)         | `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`, `formatView`)                               | 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 **inside a
+`SectionBlock`**, so place it as a **top-level child** of the form (not inside a `FormBuilder.Section`).
+Each column pairs a `header` with a `cell(rowName, index)` renderer — name the cell's field
+`${rowName}.<key>`. The section header carries the actions: a **Add New** button (also repeated as the
+bottom footer) and a **Delete Row** button that's disabled until rows are checkbox-selected. Rows support
+**checkbox selection** (+ select-all), **drag-drop reordering**, and — per column, via `sortKey` — a
+sort toggle in the header. Everything hides in `mode="view"`, where cells render read-only. 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.
+
+```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.
+
+`FormBuilder.Section` (props `title`, `color`, `icon`) groups fields in a Glare
+`SectionBlock`. `FormBuilder.Submit` is a loading-aware submit button (hidden in view mode). 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); defaults from `mode`
+  (view → `detail`). `children` are the action buttons; `FormBuilder.Submit` submits
+  the form (it auto-associates with it, even though the header sits outside `<form>`)
+  and auto-hides in view mode.
+
+## Stepper (steps are components)
+
+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). Put the **Submit** in the `FormBuilder.Header` (or the
+`FormRenderer` `actions`) — it submits every step's fields at once, from any step.
+
+```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>
+```
+
+> **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"`.
+
+## 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.
+
+## Edit & view modes
+
+- **Edit**: 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.
+- **View**: `mode="view"` renders the same children read-only (label + formatted value)
+  with no submit — one markup drives both edit and detail views.
+
+```tsx
+<FormBuilder mode="view" values={entity} onSubmit={() => {}} 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

@@ -0,0 +1,228 @@
+---
+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.
+component: true
+group: Forms
+keywords: [form-renderer, form, drawer, header, display, view-mode, 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:
+
+- **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.
+
+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}
+  resolver={zodResolver(schema)}
+  defaultValues={d}
+  header={{ title: "Item", variant: "new" }}
+  actions={<FormBuilder.Submit>Save</FormBuilder.Submit>}
+>
+  <FormBuilder.Section title="Identity" color="Blue">
+    <FormBuilder.Text name="name" label="Name" required />
+    <FormBuilder.Currency name="price" label="Price" currencySymbol="$" />
+  </FormBuilder.Section>
+</FormRenderer>
+```
+
+## 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 — `FormBuilder.Section` / field / `FormBuilder.Stepper` JSX.                                                                                                                                                                                                       |
+| `onSubmit` / `onInvalid`                                       | fns                           | Submit / validation-fail callbacks.                                                                                                                                                                                                                                              |
+| `resolver`                                                     | `Resolver`                    | Any react-hook-form resolver, e.g. `zodResolver(schema)`.                                                                                                                                                                                                                        |
+| `defaultValues` / `values`                                     | `DefaultValues` / `T`         | Initial values; `values` re-syncs on change (edit).                                                                                                                                                                                                                              |
+| `mode`                                                         | `'edit' \| 'view'`            | `'view'` renders read-only, no Submit.                                                                                                                                                                                                                                           |
+| `loading` / `resetOnSuccess`                                   | `boolean`                     | Forwarded to `FormBuilder`.                                                                                                                                                                                                                                                      |
+| `fieldDirection`                                               | `'horizontal' \| 'vertical'`  | Defaults to vertical inside a drawer.                                                                                                                                                                                                                                            |
+| `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.                                                                 |
+| `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. |
+| `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 & view
+
+```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>
+
+// read-only view — same children, omit `actions` (a view has no Save)
+<FormRenderer mode="view" values={entity} onSubmit={() => {}}>
+  {fields}
+</FormRenderer>
+```
+
+## Stepper
+
+Drop a `FormBuilder.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).
+
+```tsx
+<FormRenderer
+  onSubmit={save}
+  resolver={r}
+  defaultValues={d}
+  header={{ title: "New item", variant: "new" }}
+  actions={<FormBuilder.Submit>Save</FormBuilder.Submit>}
+>
+  <FormBuilder.Stepper>
+    <FormBuilder.Step title="Basics">
+      <FormBuilder.Text name="name" label="Name" required />
+    </FormBuilder.Step>
+  </FormBuilder.Stepper>
+</FormRenderer>
+```
+
+## 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 `summary`. It still works.
+
+`FormRenderer` does **not** forward `summary` — use `FormDrawer` directly when you need one.

package/docs/components/form-summary.md

@@ -0,0 +1,123 @@
+---
+title: FormSummary
+description: A read-only calculation panel displayed beside a form. Each row declares a compute(values) that runs against the live form values, so totals recalculate as the user types.
+component: true
+group: Forms
+keywords: [form-summary, summary, totals, calculation, invoice, panel, react-hook-form, useWatch]
+---
+
+# FormSummary
+
+A read-only **calculation panel** that sits **beside a form** — the invoice-summary
+look: grouped rows of computed totals, right-aligned, in Glare's dark `SystemStyle`
+fields.
+
+Each `FormSummary.Row` declares a **`compute(values)`** that runs against the **live**
+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:
+
+```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>
+  </FormBuilder>
+
+  <FormSummary form={form} title="Invoice" subtitle="Summary">
+    <FormSummary.Group title="Total">
+      <FormSummary.Row label="Total Discount" compute={totalDiscount} />
+      <FormSummary.Row label="Overall Total" emphasized compute={overallTotal} />
+      <FormSummary.Row label="Overall Total" currency="IQD" tone="success"
+        compute={v => overallTotal(v) * v.iqdRate} decimals={0} />
+      <FormSummary.Row label="Overall Total" currency="USD" tone="info" compute={overallTotal} />
+    </FormSummary.Group>
+  </FormSummary>
+</div>
+```
+
+`FormBuilder` stays purely an input renderer — it knows nothing about the panel, and
+**you** own the side-by-side layout. Passing `form` to `FormBuilder` makes it use that
+instance instead of creating its own.
+
+### Height
+
+The panel is `h-full` and fills whatever height its parent gives it, scrolling its groups
+(header pinned) once they outrun it. That means **the parent has to have a height** — the
+usual mistake is `items-start` on the flex row, which collapses the panel to its content
+instead. Leave the row at its default `items-stretch`, as above.
+
+To make the panel own the viewport rather than grow with the form, bound the row:
+
+```tsx
+<div className="flex h-[calc(100vh-2rem)] gap-4">
+  <FormBuilder … className="min-w-0 flex-1 overflow-y-auto" />
+  <FormSummary … />
+</div>
+```
+
+> Hoisting the form means a remount `key` no longer resets it. Call `form.reset(defaults)`
+> instead (e.g. when opening a drawer).
+
+## Installation
+
+```bash
+npx torch-glare@latest init
+npx torch-glare@latest add FormSummary
+```
+
+## Imports
+
+```tsx
+import { FormSummary } from '@/components/FormSummary'
+```
+
+## `FormSummary` props
+
+| Prop | Type | Notes |
+|---|---|---|
+| `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>`. |
+| `width` | `number \| string` | Panel width; default `228`. |
+| `children` | `ReactNode` | `FormSummary.Group` children. |
+
+## `FormSummary.Group` props
+
+| Prop | Type | Notes |
+|---|---|---|
+| `title` | `ReactNode` | The group heading (Customer / Total / Tax / …). Groups are separated by a divider. |
+| `collapsible` | `boolean` | When titled, the heading is a [ConclusionHeader](./conclusion-header.md) that opens/closes **this group's** rows; default `true`. |
+| `defaultOpen` | `boolean` | Initial open state when collapsible; default `true`. |
+
+The main panel title is a plain header — collapsing happens **per group**, not on the whole panel.
+
+## `FormSummary.Row` props
+
+| Prop | Type | Notes |
+|---|---|---|
+| `label` | `ReactNode` | Row label, above the value. |
+| `compute` | `(values) => number \| string` | **The calculation** — receives the live form values. |
+| `value` | `number \| string` | Static value, when there's nothing to compute. |
+| `currency` | `ReactNode` | Currency code, e.g. `"IQD"` — rendered **inside** the field's trailing edge. |
+| `tone` | `'neutral' \| 'success' \| 'info'` | Color of the currency code (green / blue). |
+| `emphasized` | `boolean` | The primary result — lighter, emphasized border. |
+| `decimals` | `number` | Decimal places; default `2` (→ `0.00`). |
+| `action` | `ReactNode` | Trailing slot inside the field, e.g. an `ActionButton`. Shares the slot with `currency`. |
+| `format` | `(value) => string` | Override the default number formatting. |
+
+## Computing totals
+
+`compute` is a plain function of the form values — keep the maths outside the JSX:
+
+```tsx
+const subTotal      = v => v.items.reduce((s, i) => s + i.qty * i.price, 0)
+const totalDiscount = v => v.items.reduce((s, i) => s + i.discount, 0)
+const taxable       = v => Math.max(0, subTotal(v) - totalDiscount(v))
+const totalTax      = v => taxable(v) * (v.taxRate / 100)
+const overallTotal  = v => taxable(v) + totalTax(v)
+```
+
+The panel is **read-only** — it contributes nothing to the submitted values.

package/docs/components/image-attachment.md

@@ -875,10 +875,16 @@ describe('AttachmentImagePreview', () => {
 
 ### Default Styling
 
-- Drop Zone: 200px min-width, 65px height, dashed border
-- Preview: 180px max-width, 65px height, rounded corners
-- Active State: Background and border color change
-- Hover: Expand button overlay with icon
+Matches the *Attachment-Field-1.0 / Pic-Container-1.0* design:
+
+- **Field box** (`ImageAttachment`): a `#f9f9f9` (`background-presentation-form-field-primary`)
+  rounded container holding an optional preview and the drop zone, `gap-[10px]`.
+- **Drop zone**: fills the box (`flex-1`), 65px tall, transparent with a dashed
+  `border-presentation-action-borderstyle` border; drag-active tints it gray.
+- **Preview thumbnail** (`ExpandableImage`): a fixed **65×65** square, `object-cover`, rounded.
+- **Placeholder** (no image): ocean fill (`badge-ocean-subtle`) + dashed `blue-purple-300`
+  border + paperclip icon; on hover it goes gray (`badge-gray-subtle` / `badge-gray`).
+- **Hover (has image)**: a `black/50` overlay with a fullscreen icon + the `expandLabel`.
 
 ## Best Practices