torch-glare 2.4.1 → 2.4.2

package/docs/components/table-dnd-wrapper.md

@@ -27,13 +27,15 @@ TORCH Glare is a copy-in library: the CLI copies this module's source into your
 
 ```bash
 npx torch-glare@latest init
-npx torch-glare@latest add TableDnDWrapper
+npx torch-glare@latest add TextEditor
 ```
 
+`createTableDnDClass` ships as part of the `TextEditor` folder, so `add TextEditor` copies it in.
+
 ## Import
 
 ```typescript
-import createTableDnDClass from "@/components/TableDnDWrapper";
+import { createTableDnDClass } from "@/components/TextEditor";
 ```
 
 ## Quick Examples
@@ -43,7 +45,7 @@ import createTableDnDClass from "@/components/TableDnDWrapper";
 ```typescript
 import EditorJS from "@editorjs/editorjs";
 import Table from "@editorjs/table";
-import createTableDnDClass from "@/components/TableDnDWrapper";
+import { createTableDnDClass } from "@/components/TextEditor";
 
 // Wrap the original table tool to add row/column drag-and-drop.
 const TableWithDnD = createTableDnDClass(Table);

package/docs/components/text-editor.md

@@ -260,8 +260,26 @@ function MarkdownEditor() {
 | `tools` | `Record<string, any>` | Default 18+ tools | Override the Editor.js tools configuration |
 | `minHeight` | `number` | - | Custom min-height in pixels (overrides size) |
 | `disabled` | `boolean` | `false` | Disables interaction with reduced opacity |
+| `toolbar` | `boolean` | `true` | Show the fixed formatting toolbar. Auto-hidden when `readOnly`/`disabled`. |
 | `className` | `string` | - | Additional CSS classes |
 
+### Formatting toolbar
+
+A fixed, sticky toolbar sits at the top of the editor (shown by default; pass `toolbar={false}`
+to hide it, and it is automatically hidden in `readOnly`/`disabled` editors). It drives the
+underlying Editor.js instance and offers:
+
+- **History** — undo / redo (via `editorjs-undo`; also bound to `Ctrl/⌘+Z` / `Ctrl/⌘+Y`).
+- **Block type** — a dropdown to switch between Normal text and Heading 1–3 (`blocks.convert`).
+- **Alignment** — left / center / right (a block tune persisted on each block).
+- **Text color** — a swatch palette.
+- **Inline** — bold, italic, underline, strikethrough, clear formatting.
+- **Lists** — bullet and ordered.
+- **Insert image** — from a local file (inserted as an `image` block).
+
+Strikethrough and color are backed by small custom inline tools whose `sanitize` allowlists let
+that markup survive `save()`; alignment persists as a block tune.
+
 ### Ref Methods (TextEditorRef)
 
 | Method | Signature | Description |

package/docs/how-to/form-and-list-recipes.md

@@ -10,6 +10,13 @@ Battle-tested layouts and component combinations from production frontend work.
 Use these as the starting point for create dialogs, list/filter pages,
 line-item grids, and login flows.
 
+> **For actual forms, reach for [`FormBuilder`](../components/form-builder.md) first.** The
+> multi-column form rows below are a layout escape hatch for the rare case that needs bespoke
+> positioning — they are **not** the default way to build a form. A normal create/edit form is
+> `FormBuilder` fields as JSX children with a resolver; see the
+> [Forms with FormBuilder](./forms-with-form-builder.md) guide. Don't hand-wire `FormField` /
+> `InputField` rows or hold field state in `useState` when `FormBuilder` would do it.
+
 > All examples use the `presentation` color tokens. Never substitute
 > `*-system-*` tokens or `variant="SystemStyle"` — see the rules banner at
 > the top of every doc response.
@@ -76,7 +83,9 @@ the same filter bar — a search input + one or more select filters above a
 data table.
 
 ```tsx
-{/* Filter bar */}
+{
+  /* Filter bar */
+}
 <div className="flex items-center gap-3">
   <div className="flex-1 max-w-sm">
     <InputField
@@ -99,9 +108,11 @@ data table.
     ]}
     placeholder="All Statuses"
   />
-</div>
+</div>;
 
-{/* Data table */}
+{
+  /* Data table */
+}
 <Card className="p-0 overflow-hidden">
   <CardContent className="p-0 overflow-x-auto">
     <Table className="w-full">
@@ -122,9 +133,7 @@ data table.
             >
               <i className="ri-inbox-line text-4xl opacity-60" />
               <p className="typography-body-medium-regular">No vouchers</p>
-              <p className="typography-body-small-regular opacity-80">
-                Try adjusting your filters
-              </p>
+              <p className="typography-body-small-regular opacity-80">Try adjusting your filters</p>
             </TableCell>
           </TableRow>
         ) : (
@@ -144,7 +153,7 @@ data table.
       </TableBody>
     </Table>
   </CardContent>
-</Card>
+</Card>;
 ```
 
 Key rules:
@@ -263,15 +272,15 @@ hierarchy. Adding a relevant icon makes dialogs instantly recognizable.
 
 Pick an icon that matches the entity:
 
-| Entity | Icon |
-|---|---|
-| Account | `ri-bank-line` |
-| Fiscal period / year | `ri-calendar-line` |
-| Voucher / journal | `ri-receipt-line` |
-| Number series | `ri-hashtag` |
-| Posting rule | `ri-settings-3-line` |
-| Exchange rate | `ri-exchange-line` |
-| Bank / cash account | `ri-bank-card-line` |
+| Entity               | Icon                 |
+| -------------------- | -------------------- |
+| Account              | `ri-bank-line`       |
+| Fiscal period / year | `ri-calendar-line`   |
+| Voucher / journal    | `ri-receipt-line`    |
+| Number series        | `ri-hashtag`         |
+| Posting rule         | `ri-settings-3-line` |
+| Exchange rate        | `ri-exchange-line`   |
+| Bank / cash account  | `ri-bank-card-line`  |
 
 ---
 
@@ -297,9 +306,7 @@ export function LoginPage() {
           "to-background-presentation-state-information/10",
         ].join(" ")}
       >
-        <h1 className="typography-headers-large-medium">
-          Welcome to Torch Finance
-        </h1>
+        <h1 className="typography-headers-large-medium">Welcome to Torch Finance</h1>
         <ul className="flex flex-col gap-3">
           {features.map((f) => (
             <li key={f.title} className="flex items-start gap-3">

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

@@ -0,0 +1,408 @@
+---
+title: Forms with FormBuilder, FormRenderer & FormSummary
+description: The canonical way to build forms in TORCH Glare. Author fields as JSX with FormBuilder, add page/drawer chrome with FormRenderer, and show live computed totals with FormSummary. Covers single, stepper, drawer, edit/view, and a full invoice example combining all three.
+keywords:
+  [
+    form,
+    forms,
+    formbuilder,
+    formrenderer,
+    formsummary,
+    form-builder,
+    form-renderer,
+    form-summary,
+    validation,
+    zod,
+    resolver,
+    stepper,
+    drawer,
+    totals,
+    invoice,
+    calculation,
+    react-hook-form,
+  ]
+---
+
+# Forms with FormBuilder, FormRenderer & FormSummary
+
+**This is the way to build forms in TORCH Glare.** Do not hand-wire
+`FormField` → `FormItem` → `FormControl` → `InputField` rows, and never track field state
+with `useState` — that boilerplate is exactly what `FormBuilder` exists to remove.
+
+Three components, layered:
+
+| Component          | Use it for                                                                                                                             | When                                            |
+| ------------------ | -------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------- |
+| **`FormBuilder`**  | The form itself — fields authored as JSX children. Owns react-hook-form, validation, edit/view, 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`.  |
+| **`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
+(`zodResolver(schema)` is typical). The library never depends on zod.
+
+---
+
+## 1. A single-page form
+
+Each `FormBuilder.*` field is one JSX child taking at least a `name`, plus `label`,
+`placeholder`, `required`, `disabled`, `hidden`, `fullWidth`. Wrap them in `FormRenderer`,
+give it a `header` for the title bar, and pass the Save via `actions`.
+
+```tsx
+"use client";
+
+import { z } from "zod";
+import { zodResolver } from "@hookform/resolvers/zod";
+import { FormBuilder } from "@/components/FormBuilder";
+import { FormRenderer } from "@/components/FormRenderer";
+
+const schema = z.object({
+  name: z.string().min(1, "Name is required"),
+  description: z.string(),
+  category: z.string().min(1, "Pick a category"),
+  price: z.number().positive("Must be positive").optional(),
+  active: z.boolean(),
+  agree: z.boolean().refine((v) => v === true, "You must agree to continue"),
+});
+type Values = z.infer<typeof schema>;
+
+const DEFAULTS: Values = {
+  name: "",
+  description: "",
+  category: "",
+  price: undefined,
+  active: true,
+  agree: false,
+};
+
+const CATEGORY = [
+  { label: "Hardware", value: "hardware" },
+  { label: "Software", value: "software" },
+];
+
+export function ItemForm({
+  onSave,
+  saving,
+}: {
+  onSave: (v: Values) => Promise<void>;
+  saving?: boolean;
+}) {
+  return (
+    <FormRenderer<Values>
+      onSubmit={onSave}
+      loading={saving}
+      resolver={zodResolver(schema)}
+      defaultValues={DEFAULTS}
+      header={{ title: "New item", variant: "new" }}
+      actions={<FormBuilder.Submit>Save</FormBuilder.Submit>}
+    >
+      <FormBuilder.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>
+
+      <FormBuilder.Section title="Classification" color="Red">
+        <FormBuilder.Select name="category" label="Category" required options={CATEGORY} />
+        <FormBuilder.Currency name="price" label="Base price" currencySymbol="$" />
+      </FormBuilder.Section>
+
+      <FormBuilder.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>
+  );
+}
+```
+
+`FormBuilder.Section` groups fields in a `SectionBlock` (`color` is one of `Blue`, `Yellow`,
+`Green`, `Red`, `Orange`, `Purple`, `Pink`, `Gray`). Pass the Save via `actions` — a
+`FormBuilder.Submit`, which is loading-aware and auto-hides in view mode; it renders in the
+header action pill. (With raw `FormBuilder`, put the same `FormBuilder.Submit` in a
+`FormBuilder.Header`.)
+
+### Field types
+
+Every field, its underlying control, and the value your `onSubmit` receives:
+
+| Component                                                        | Value                                                          |
+| ---------------------------------------------------------------- | -------------------------------------------------------------- |
+| `.Text` / `.Email` / `.Password` (`strengthMeter`)               | `string`                                                       |
+| `.Number`                                                        | `number`                                                       |
+| `.Currency` (`currencySymbol`)                                   | `number`                                                       |
+| `.Textarea`                                                      | `string`                                                       |
+| `.Select` / `.SearchableSelect` (`options`)                      | `string`                                                       |
+| `.MultiSelect` / `.Tags` (`options`)                             | `string[]`                                                     |
+| `.RadioList` (`options`, optional per-option `description`)      | `string`                                                       |
+| `.CheckboxGroup` (`options`)                                     | `string[]`                                                     |
+| `.RadioCards` (`options` with `description`)                     | `string`                                                       |
+| `.Checkbox` (`subLabel`)                                         | `boolean`                                                      |
+| `.SwitchBox` (`subLabel`)                                        | `boolean`                                                      |
+| `.Otp` (`length`)                                                | `string`                                                       |
+| `.Slider` (`min`, `max`, `step`, `range`, `suffix`)              | `number` (or `[number, number]` with `range`)                  |
+| `.Color` (`presets`, `alpha`)                                    | hex `string`                                                   |
+| `.Phone` (`defaultCountry`, defaults to `+964`)                  | `string` (`"+<dial> <number>"`)                                |
+| `.Date`                                                          | `Date`                                                         |
+| `.DateRange`                                                     | `{ from, to }`                                                 |
+| `.DateMultiple`                                                  | `Date[]`                                                       |
+| `.DateTime`                                                      | `Date`                                                         |
+| `.TreeSelect` (`nodes`, `getNodeId`, `getNodeLabel`)             | node id (`string`)                                             |
+| `.File` / `.Image` (`accept`, `multiple`)                        | `File \| File[]`                                               |
+| `.RichText`                                                      | EditorJS `OutputData`                                          |
+| `.Signature` (`penColor`)                                        | PNG data-URL `string`                                          |
+| `.FieldArray` (`children` render fn, `defaultItem`)              | `object[]`                                                     |
+| `.Table` (`columns`, `selectable`, `reorderable`, `defaultItem`) | `object[]` — editable grid; top-level child (not in a Section) |
+| `.Custom` (`render`, `formatView`)                               | anything                                                       |
+
+See the [FormBuilder](../components/form-builder.md) doc for the full prop tables.
+
+---
+
+## 2. Title header + action bar
+
+`FormRenderer`'s `header` prop renders a title pill on the left: `header={{ title: 'Acme Widget
+Pro', variant: 'edit' }}` (variants: `new`, `edit`, `detail`). The **action pill** on the right is
+whatever you pass to `actions` — put the Save there:
+`actions={<FormBuilder.Submit>Save invoice</FormBuilder.Submit>}`. A bare `FormBuilder.Submit`
+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.
+
+---
+
+## 3. Stepper (steps are components)
+
+Every step's fields stay **mounted and registered** — the whole form is live regardless of
+which step shows; the stepper only toggles visibility. **Navigation is the step buttons
+themselves**: backward is free, clicking forward validates the steps in between and stops at
+the first one with errors. The Save is the header `actions` — it submits every step's fields at
+once, from any step.
+
+```tsx
+<FormRenderer<Values>
+  onSubmit={save}
+  resolver={zodResolver(schema)}
+  defaultValues={DEFAULTS}
+  header={{ title: "New item", variant: "new" }}
+  actions={<FormBuilder.Submit>Save</FormBuilder.Submit>}
+>
+  <FormBuilder.Stepper>
+    <FormBuilder.Step title="Identity">
+      <FormBuilder.Section title="Identity" color="Blue">
+        <FormBuilder.Text name="name" label="Name" required />
+      </FormBuilder.Section>
+    </FormBuilder.Step>
+
+    <FormBuilder.Step title="Classification">
+      <FormBuilder.Section title="Classification" color="Red">
+        <FormBuilder.Select name="category" label="Category" required options={CATEGORY} />
+      </FormBuilder.Section>
+    </FormBuilder.Step>
+  </FormBuilder.Stepper>
+</FormRenderer>
+```
+
+---
+
+## 4. Edit and read-only view — one markup, both modes
+
+- **Edit**: pass `values` (not just `defaultValues`) — the form repopulates when the data
+  loads. Add a remount `key` so initial-only inputs (date, rich text) re-seed.
+- **View**: `mode="view"` renders the same children read-only, with no Submit.
+
+```tsx
+<FormRenderer<Values>
+  key={record?.id ?? "new"}
+  mode={mode} // 'edit' | 'view'
+  values={record} // arrives async
+  onSubmit={save}
+  resolver={zodResolver(schema)}
+  defaultValues={DEFAULTS}
+  header={{ title: record?.name ?? "New", variant: mode === "view" ? "detail" : "edit" }}
+>
+  …the same fields…
+</FormRenderer>
+```
+
+---
+
+## 5. A form in a drawer
+
+Set `display="drawer"` and drive it with `open` / `onOpenChange`. Pass the Save via `actions` —
+it renders in the drawer header, with no manual `id` / `form={id}` wiring:
+
+```tsx
+<FormRenderer<Values>
+  display="drawer"
+  open={open}
+  onOpenChange={setOpen}
+  header={{ title: "New item", label: "New", variant: "new" }}
+  onSubmit={save}
+  resolver={zodResolver(schema)}
+  defaultValues={DEFAULTS}
+  actions={<FormBuilder.Submit>Save</FormBuilder.Submit>}
+>
+  <FormBuilder.Section title="Identity" color="Blue">
+    …
+  </FormBuilder.Section>
+</FormRenderer>
+```
+
+Inside a drawer the fields default to a vertical (narrow) layout automatically.
+
+---
+
+## 6. The conclusion panel — live totals beside the form
+
+`FormSummary` is a read-only panel of computed rows. Each `FormSummary.Row` declares a
+**`compute(values)`** that runs against the **live** form values, so totals recalculate as the
+user types. Pass it to `FormRenderer`'s `summary` prop.
+
+Both the form and the panel must read the same values, so **hoist `useForm`** and hand the
+instance to `FormRenderer` **and** `FormSummary` via their `form` prop:
+
+```tsx
+"use client";
+
+import { useForm } from "react-hook-form";
+import { zodResolver } from "@hookform/resolvers/zod";
+import { FormBuilder } from "@/components/FormBuilder";
+import { FormRenderer } from "@/components/FormRenderer";
+import { FormSummary } from "@/components/FormSummary";
+
+// The calculations — plain functions of the form values. Keep them out of the JSX.
+const subTotal = (v: Invoice) => v.items.reduce((s, i) => s + (i.qty ?? 0) * (i.price ?? 0), 0);
+const totalDiscount = (v: Invoice) => v.items.reduce((s, i) => s + (i.discount ?? 0), 0);
+const taxable = (v: Invoice) => Math.max(0, subTotal(v) - totalDiscount(v));
+const totalTax = (v: Invoice) => taxable(v) * ((v.taxRate ?? 0) / 100);
+const overallTotal = (v: Invoice) => taxable(v) + totalTax(v);
+
+export function InvoiceForm({ save }: { save: (v: Invoice) => Promise<void> }) {
+  // Hoisted so both the form and the summary beside it share the same values.
+  const form = useForm<Invoice>({ resolver: zodResolver(schema), defaultValues: DEFAULTS });
+
+  return (
+    <FormRenderer<Invoice>
+      form={form}
+      onSubmit={save}
+      fieldDirection="vertical"
+      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="Total Discount" compute={totalDiscount} />
+            <FormSummary.Row label="Overall Total" emphasized compute={overallTotal} />
+            <FormSummary.Row
+              label="Overall Total"
+              currency="IQD"
+              tone="success"
+              decimals={0}
+              compute={(v) => overallTotal(v) * (v.iqdRate ?? 0)}
+            />
+            <FormSummary.Row
+              label="Overall Total"
+              currency="USD"
+              tone="info"
+              compute={overallTotal}
+            />
+          </FormSummary.Group>
+
+          <FormSummary.Group title="Tax">
+            <FormSummary.Row label="Sub Total" compute={subTotal} />
+            <FormSummary.Row label="Total Tax" compute={totalTax} />
+          </FormSummary.Group>
+        </FormSummary>
+      }
+    >
+      <FormBuilder.Section title="Line items" color="Green">
+        <FormBuilder.FieldArray
+          name="items"
+          label="Items"
+          addLabel="Add item"
+          defaultItem={{ name: "", qty: 1, price: 0, discount: 0 }}
+        >
+          {(rowName) => (
+            <>
+              <FormBuilder.Text name={`${rowName}.name`} label="Item" />
+              <FormBuilder.Number name={`${rowName}.qty`} label="Qty" />
+              <FormBuilder.Currency name={`${rowName}.price`} label="Price" currencySymbol="$" />
+              <FormBuilder.Currency
+                name={`${rowName}.discount`}
+                label="Discount"
+                currencySymbol="$"
+              />
+            </>
+          )}
+        </FormBuilder.FieldArray>
+      </FormBuilder.Section>
+
+      <FormBuilder.Section title="Rates" color="Purple">
+        <FormBuilder.Number name="taxRate" label="Tax rate (%)" />
+        <FormBuilder.Number name="iqdRate" label="USD → IQD rate" />
+      </FormBuilder.Section>
+    </FormRenderer>
+  );
+}
+```
+
+Row options: `emphasized` (the primary result), `currency` + `tone`
+(`'neutral' | 'success' | 'info'`), `decimals` (default `2` → `0.00`), `action` (a trailing
+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 ·
+fields · summary).
+
+---
+
+## 7. Conclusion panel + drawer
+
+The same `summary` prop works with `display="drawer"` — `FormRenderer` moves the panel into the
+drawer's tray, beside the form:
+
+```tsx
+<FormRenderer<Invoice>
+  display="drawer"
+  open={open}
+  onOpenChange={setOpen}
+  form={form}
+  onSubmit={save}
+  header={{ title: "New item", badge: "New", variant: "new" }}
+  summary={
+    <FormSummary form={form} title="Item" subtitle="Summary">
+      <FormSummary.Group title="Pricing">
+        <FormSummary.Row label="Base price" compute={basePrice} />
+        <FormSummary.Row label="Overall Total" emphasized compute={overallTotal} />
+      </FormSummary.Group>
+    </FormSummary>
+  }
+>
+  <FormBuilder.Section title="Identity" color="Blue">
+    …
+  </FormBuilder.Section>
+</FormRenderer>
+```
+
+---
+
+## Gotchas
+
+- **Hoisting `useForm` disables the remount-`key` reset.** Once the form instance lives in
+  your component, a changing `key` no longer resets it. Call `form.reset(DEFAULTS)` instead
+  (e.g. when opening a drawer).
+- **`FormSummary` needs the same hoisted `form`** — that's the react-hook-form context it reads
+  live values from. Pass the identical instance to `FormRenderer` and `FormSummary`.
+- **Number/currency values are real numbers**, not strings — `onSubmit` receives
+  `price: 1299`, not `"1299"`.
+- **`required` is cosmetic.** It renders the "(Required)" tag; actual enforcement is your
+  resolver — keep the two in sync.
+- **Never use `variant="SystemStyle"` or `*-system-*` tokens** in app code.
+
+## Related
+
+- [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