torch-glare 2.5.1 → 2.5.3

package/docs/how-to/forms-with-form-builder.md

@@ -33,8 +33,8 @@ Three components, layered:
 
 | Component          | Use it for                                                                                                                             | When                                            |
 | ------------------ | -------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------- |
-| **`FormBuilder`**  | The form itself — fields authored as JSX children. Owns react-hook-form, validation, sections, steppers.                               | Always. This is the base.                       |
-| **`FormRenderer`** | Wraps `FormBuilder` to add **chrome**: page-vs-drawer display, the title header, an `actions` slot for the Save, and a `summary` slot. | Real forms — prefer it over raw `FormBuilder`.  |
+| **`FormBuilder`**  | The fields themselves, authored as JSX children. Owns react-hook-form and validation — and nothing else: no cards, no header, no frame. | Always. This is the base.                       |
+| **`FormRenderer`** | All the **chrome**: page-vs-drawer display, the title header, an `actions` slot for the Save, the titled `Section` cards, the stepper, and a `summary` slot. | Real forms — prefer it over raw `FormBuilder`.  |
 | **`FormSummary`**  | A read-only **calculation panel beside the form** — totals that recompute live as the user types.                                      | Invoices, orders, anything with a "conclusion". |
 
 Validation is **resolver-agnostic**: pass any react-hook-form resolver
@@ -96,31 +96,34 @@ export function ItemForm({
       header={{ title: "New 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 placeholder="e.g. Acme Widget" />
         <FormBuilder.Textarea name="description" label="Description" fullWidth />
-      </FormBuilder.Section>
+      </FormRenderer.Section>
 
-      <FormBuilder.Section title="Classification" color="Red">
+      <FormRenderer.Section title="Classification" color="Red">
         <FormBuilder.Select name="category" label="Category" required options={CATEGORY} />
         <FormBuilder.Currency name="price" label="Base price" currencySymbol="$" />
-      </FormBuilder.Section>
+      </FormRenderer.Section>
 
-      <FormBuilder.Section title="Settings" color="Purple">
+      <FormRenderer.Section title="Settings" color="Purple">
         <FormBuilder.SwitchBox name="active" label="Active" subLabel="Enabled" />
         <FormBuilder.Checkbox name="agree" label="I agree to the terms" required />
-      </FormBuilder.Section>
+      </FormRenderer.Section>
     </FormRenderer>
   );
 }
 ```
 
-`FormBuilder.Section` groups fields in a `SectionBlock` (`color` is one of `Blue`, `Yellow`,
+`FormRenderer.Section` groups fields in a `SectionBlock` (`color` is one of `Blue`, `Yellow`,
 `Green`, `Red`, `Orange`, `Purple`, `Pink`, `Gray`). It also takes `icon`, `action`
 (right-aligned buttons on the title row) and `variant` — `variant="Table"` switches to the
 full-bleed table shell that `FormBuilder.Table` uses internally. Pass the Save via `actions` — a
-`FormBuilder.Submit`, which is loading-aware; it renders in the header action pill. (With raw
-`FormBuilder`, put the same `FormBuilder.Submit` in a `FormBuilder.Header`.)
+`FormBuilder.Submit`, which is loading-aware; it renders in the header action pill.
+
+> The section card belongs to `FormRenderer`, not `FormBuilder`: it is presentation, and it groups
+> read-only detail rows just as happily as fields. A bare `<FormBuilder>` renders its fields with
+> no card around them.
 
 ### Field types
 
@@ -168,8 +171,7 @@ whatever you pass to `actions` — put the Save there:
 auto-targets the form (via a form-id context), so it submits even though the header renders
 _outside_ the `<form>`.
 
-If you use raw `FormBuilder`, the same bar is `FormBuilder.Header` with a `FormBuilder.Submit`
-child.
+There is no header on raw `FormBuilder` — the title bar is FormRenderer's.
 
 ---
 
@@ -194,19 +196,19 @@ checked** in the rail even after you navigate back — a live error still shows
   header={{ title: "New item", variant: "new" }}
   actions={<FormBuilder.Submit>Save</FormBuilder.Submit>}
 >
-  <FormBuilder.Stepper>
-    <FormBuilder.Step title="Identity">
-      <FormBuilder.Section title="Identity" color="Blue">
+  <FormRenderer.Stepper>
+    <FormRenderer.Step title="Identity">
+      <FormRenderer.Section title="Identity" color="Blue">
         <FormBuilder.Text name="name" label="Name" required />
-      </FormBuilder.Section>
-    </FormBuilder.Step>
+      </FormRenderer.Section>
+    </FormRenderer.Step>
 
-    <FormBuilder.Step title="Classification">
-      <FormBuilder.Section title="Classification" color="Red">
+    <FormRenderer.Step title="Classification">
+      <FormRenderer.Section title="Classification" color="Red">
         <FormBuilder.Select name="category" label="Category" required options={CATEGORY} />
-      </FormBuilder.Section>
-    </FormBuilder.Step>
-  </FormBuilder.Stepper>
+      </FormRenderer.Section>
+    </FormRenderer.Step>
+  </FormRenderer.Stepper>
 </FormRenderer>
 ```
 
@@ -249,13 +251,15 @@ it renders in the drawer header, with no manual `id` / `form={id}` wiring:
   defaultValues={DEFAULTS}
   actions={<FormBuilder.Submit>Save</FormBuilder.Submit>}
 >
-  <FormBuilder.Section title="Identity" color="Blue">
+  <FormRenderer.Section title="Identity" color="Blue">
     …
-  </FormBuilder.Section>
+  </FormRenderer.Section>
 </FormRenderer>
 ```
 
-Inside a drawer the fields default to a vertical (narrow) layout automatically.
+Inside a drawer the fields default to a vertical (narrow) layout automatically. A drawer can be
+wide, though — pass `fieldDirection="flexible"` to hand the decision back to the container query,
+which goes label-beside-control once a field row passes the container `md` breakpoint.
 
 ---
 
@@ -322,7 +326,7 @@ export function InvoiceForm({ save }: { save: (v: Invoice) => Promise<void> }) {
         </FormSummary>
       }
     >
-      <FormBuilder.Section title="Line items" color="Green">
+      <FormRenderer.Section title="Line items" color="Green">
         <FormBuilder.FieldArray
           name="items"
           label="Items"
@@ -342,12 +346,12 @@ export function InvoiceForm({ save }: { save: (v: Invoice) => Promise<void> }) {
             </>
           )}
         </FormBuilder.FieldArray>
-      </FormBuilder.Section>
+      </FormRenderer.Section>
 
-      <FormBuilder.Section title="Rates" color="Purple">
+      <FormRenderer.Section title="Rates" color="Purple">
         <FormBuilder.Number name="taxRate" label="Tax rate (%)" />
         <FormBuilder.Number name="iqdRate" label="USD → IQD rate" />
-      </FormBuilder.Section>
+      </FormRenderer.Section>
     </FormRenderer>
   );
 }
@@ -358,7 +362,7 @@ Row options: `emphasized` (the primary result), `currency` + `tone`
 button), `format` (override the number formatting), `value` (a static row).
 
 The panel is **read-only** — it contributes nothing to the submitted values. On a page it sits
-beside the form (a `summary` **plus** a `FormBuilder.Stepper` becomes three columns: nav ·
+beside the form (a `summary` **plus** a `FormRenderer.Stepper` becomes three columns: nav ·
 fields · summary).
 
 ---
@@ -385,9 +389,9 @@ drawer's tray, beside the form:
     </FormSummary>
   }
 >
-  <FormBuilder.Section title="Identity" color="Blue">
+  <FormRenderer.Section title="Identity" color="Blue">
     …
-  </FormBuilder.Section>
+  </FormRenderer.Section>
 </FormRenderer>
 ```
 
@@ -396,12 +400,11 @@ drawer's tray, beside the form:
 ## 8. A detail (view) page — sidebar tabs, not a form
 
 Sometimes you want to **display** a record, not edit it. 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; only the active panel shows.
 
-- `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; only the active panel shows.
-
-**Every tab's content is `FormBuilder.Section` blocks.** Inside a Section, use the default
+**Every tab's content is `FormRenderer.Section` blocks.** Inside a Section, use the default
 `FormRenderer.Grid` + `FormRenderer.Row` display cells (the read-only counterpart of form fields), or
 render **your own component** — anything goes inside a Section.
 
@@ -422,19 +425,19 @@ render **your own component** — anything goes inside a Section.
 
   {/* Default display cells */}
   <FormRenderer.Tab value="overview">
-    <FormBuilder.Section title="Main Information" color="Blue">
+    <FormRenderer.Section title="Main Information" color="Blue">
       <FormRenderer.Grid columns={2}>
         <FormRenderer.Row label="PO Number" value={record.poNumber} />
         <FormRenderer.Row label="Status" value={<Badge label="Submitted" color="yellow" />} />
       </FormRenderer.Grid>
-    </FormBuilder.Section>
+    </FormRenderer.Section>
   </FormRenderer.Tab>
 
   {/* Or bring your own component — still inside a Section */}
   <FormRenderer.Tab value="activity">
-    <FormBuilder.Section title="Activity log" color="Green">
+    <FormRenderer.Section title="Activity log" color="Green">
       <YourTimeline items={record.activity} />
-    </FormBuilder.Section>
+    </FormRenderer.Section>
   </FormRenderer.Tab>
 </FormRenderer>
 ```
@@ -465,3 +468,5 @@ takes `label` + `value` (any node). The first `Tab` is active by default.
 - [FormBuilder](../components/form-builder.md) — every field type and its value shape
 - [FormRenderer](../components/form-renderer.md) — display, header, `actions`, `summary`
 - [FormSummary](../components/form-summary.md) — the calculation panel
+- [FormBuilder 2.5.2 migration](../migration/form-builder-2.5.2.md) — what moved from
+  `FormBuilder` to `FormRenderer`, and the rename table

package/docs/migration/changelog.md

@@ -26,6 +26,9 @@ npx torch-glare@latest add Button
 
 ## Release notes
 
+- **v2.5.2** — **breaking**: `FormBuilder` now holds only the fields; the section cards, title
+  header and stepper moved to `FormRenderer`. See
+  [FormBuilder 2.5.2](./form-builder-2.5.2.md) for the rename table.
 - **v1.1.16** — see [CHANGELOG-1.1.16.md](../CHANGELOG-1.1.16.md) (adds `TextEditor`,
   `ChartBlockTool`, and related components).
 

package/docs/migration/form-builder-2.5.2.md

@@ -0,0 +1,113 @@
+---
+title: FormBuilder 2.5.2 — the chrome moved to FormRenderer
+description: FormBuilder now holds only the fields. The section cards, title header and stepper moved to FormRenderer. What to rename, and why.
+group: migration
+keywords:
+  [migration, breaking, form-builder, form-renderer, section, stepper, header, 2.5.2, upgrade]
+---
+
+# FormBuilder 2.5.2 — the chrome moved to FormRenderer
+
+**`FormBuilder` is now the fields and nothing else.** Everything drawn *around* the fields —
+titled section cards, the page title header, the stepper and its rail, the page gutters, the
+scroll shell, the summary column — now lives on [`FormRenderer`](../components/form-renderer.md).
+
+## Why
+
+The split was already documented this way; the code just did not honour it. `FormBuilder` owned a
+`rounded-2xl` page shell, a title header that a *child element* switched on, a stepper rail, and a
+`conclusion` panel rendered outside its own `<form>` — while its own doc comment described it as
+"drawer-unaware". The tell was the `layout="bare"` prop: page framing had been baked in, and
+anything embedding a form (a 260px settings rail, a `DataViews` filter panel) needed an escape
+hatch to turn it off.
+
+Now there is nothing to escape. A bare `<FormBuilder>` renders a `<form>` and your fields, and
+fills whatever it is placed in. `FormRenderer` draws the page.
+
+## What to rename
+
+| Before                  | After                    |
+| ----------------------- | ------------------------ |
+| `FormBuilder.Section`   | `FormRenderer.Section`   |
+| `FormBuilder.Stepper`   | `FormRenderer.Stepper`   |
+| `FormBuilder.Step`      | `FormRenderer.Step`      |
+| `FormBuilder.Back`      | `FormRenderer.Back`      |
+| `FormBuilder.Next`      | `FormRenderer.Next`      |
+| `FormBuilder.Header`    | `FormRenderer`'s `header` prop (see below) |
+
+**`FormBuilder.Submit` does not move.** It is the form's own submit button and still
+auto-associates with the `<form>` by id, so it works from the header action bar as before.
+
+### Two root props are gone
+
+| Removed                     | Replacement                                                        |
+| --------------------------- | ------------------------------------------------------------------ |
+| `layout="page" \| "bare"`    | Nothing — bare is the only behaviour. The 1100px cap and 48px gutters are `FormRenderer`'s. Delete the prop. |
+| `conclusion={<FormSummary/>}` | `FormRenderer`'s `summary` prop.                                   |
+
+`className` now lands on the `<form>` element itself rather than an outer page wrapper. On
+`FormRenderer` it still lands on the outermost element, so `className="min-h-0 flex-1"` behaves
+exactly as before.
+
+### `FormBuilder.Header` → the `header` prop
+
+The header was a child that silently reconfigured the root into a scroll-shell layout. It is now
+a prop, so a child can no longer change the page around it:
+
+```tsx
+// Before
+<FormBuilder onSubmit={save} resolver={r} defaultValues={d}>
+  <FormBuilder.Header title="Item" variant="new">
+    <FormBuilder.Submit>Save</FormBuilder.Submit>
+  </FormBuilder.Header>
+  <FormBuilder.Section title="Identity" color="Blue">
+    <FormBuilder.Text name="name" label="Name" required />
+  </FormBuilder.Section>
+</FormBuilder>
+
+// After
+<FormRenderer
+  onSubmit={save}
+  resolver={r}
+  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 />
+  </FormRenderer.Section>
+</FormRenderer>
+```
+
+## Doing the upgrade
+
+There is no compatibility shim: the removed parts are gone, so **TypeScript finds every call site
+for you**. Re-run the CLI, then let the compiler drive:
+
+```bash
+npx torch-glare@latest add FormBuilder FormRenderer --force
+npx tsc --noEmit
+```
+
+Each error is one of the renames in the table above. If a form used raw `FormBuilder` for a real
+page, wrap it in `FormRenderer` — that is where its header, gutters and section cards now come
+from.
+
+### Field layout is unchanged
+
+`FieldSection` — the per-field row (label · control · hint) that every field draws for itself — did
+**not** move, and no field component changed. After the rename, fields land on exactly the same
+pixels; only the `<form>` element's own box changed, because the gutters that used to sit inside it
+now sit outside it.
+
+## Installing
+
+`FormRenderer` still depends on `FormBuilder`, never the reverse — `add FormRenderer` pulls both.
+
+The registry moved to match. `FormBuilder` **dropped** `FormStepper` and `HeaderBar`, so
+`add FormBuilder` on its own now installs a smaller tree: the fields, and no chrome. `FormRenderer`
+**gained** those two plus `SectionBlock` and `Button`.
+
+Note that `FormBuilder` **keeps** its `SectionBlock` dependency even though `FormRenderer.Section`
+moved away — `FormBuilder.Table` renders a `SectionBlock variant="Table"` shell of its own, so a
+standalone `add FormBuilder` still gets a working table field.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "torch-glare",
-  "version": "2.5.1",
+  "version": "2.5.3",
   "type": "module",
   "license": "MIT",
   "description": "A copy-in React component library (TypeScript + Radix UI + Tailwind CSS). Its CLI copies component source directly into your project — you own the code.",