torch-glare 2.4.1 → 2.4.3

package/docs/components/searchable-select.md

@@ -168,70 +168,73 @@ function ArabicPicker({ options, value, onValueChange }) {
 
 ### SearchableSelect
 
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `options` | `SearchableSelectOption[]` | Required | The list of selectable options. In server mode (`filterClientSide={false}`) these are rendered as-is. |
-| `value` | `string \| null` | - | Controlled selected value. The matching option's label is shown as solid text in the input. |
-| `onValueChange` | `(value: string, option: SearchableSelectOption) => void` | - | Called when an option is selected. Receives the value and the full option object. |
-| `placeholder` | `string` | `'Search…'` | Placeholder text for the search input. |
-| `size` | `'XS' \| 'S' \| 'M'` | `'M'` | Field size. |
-| `variant` | `'PresentationStyle'` | `'PresentationStyle'` | Visual style variant for the field and dropdown surface. |
-| `icon` | `ReactNode` | - | Optional leading icon rendered inside the field. |
-| `theme` | `'dark' \| 'light' \| 'default'` | - | Theme variant, applied via `data-theme`. |
-| `dir` | `string` | - | Text direction (e.g. `'rtl'`) for the field and dropdown. |
-| `className` | `string` | - | Additional CSS classes for the field group. |
-| `filterClientSide` | `boolean` | `true` | When `true`, filters `options` locally by label. Set `false` for server-side search — `options` are rendered as-is and refetched via `onSearchChange`. |
-| `onSearchChange` | `(query: string) => void` | - | Called (debounced) with the trimmed query as the user types. Refetch your data here for server-side search. |
-| `searchDebounceMs` | `number` | `300` | Debounce delay (ms) before `onSearchChange` fires. |
-| `hasMore` | `boolean` | `false` | Whether more pages are available; gates the infinite-scroll loader. |
-| `loading` | `boolean` | `false` | Whether a fetch is in flight; shows a loading row and blocks `onLoadMore`. |
-| `onLoadMore` | `() => void` | - | Called when the scroll viewport nears the bottom and `hasMore && !loading`. |
-| `maxVisibleItems` | `number` | `5` | Maximum rows visible before the list scrolls internally. |
+| Prop               | Type                                                      | Default               | Description                                                                                                                                            |
+| ------------------ | --------------------------------------------------------- | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `options`          | `SearchableSelectOption[]`                                | Required              | The list of selectable options. In server mode (`filterClientSide={false}`) these are rendered as-is.                                                  |
+| `value`            | `string \| null`                                          | -                     | Controlled selected value. The matching option's label is shown as solid text in the input.                                                            |
+| `onValueChange`    | `(value: string, option: SearchableSelectOption) => void` | -                     | Called when an option is selected. Receives the value and the full option object.                                                                      |
+| `placeholder`      | `string`                                                  | `'Search…'`           | Placeholder text for the search input.                                                                                                                 |
+| `size`             | `'XS' \| 'S' \| 'M'`                                      | `'M'`                 | Field size.                                                                                                                                            |
+| `variant`          | `'PresentationStyle'`                                     | `'PresentationStyle'` | Visual style variant for the field and dropdown surface.                                                                                               |
+| `icon`             | `ReactNode`                                               | -                     | Optional leading icon rendered inside the field.                                                                                                       |
+| `theme`            | `'dark' \| 'light' \| 'default'`                          | -                     | Theme variant, applied via `data-theme`.                                                                                                               |
+| `dir`              | `string`                                                  | -                     | Text direction (e.g. `'rtl'`) for the field and dropdown.                                                                                              |
+| `className`        | `string`                                                  | -                     | Additional CSS classes for the field group.                                                                                                            |
+| `filterClientSide` | `boolean`                                                 | `true`                | When `true`, filters `options` locally by label. Set `false` for server-side search — `options` are rendered as-is and refetched via `onSearchChange`. |
+| `onSearchChange`   | `(query: string) => void`                                 | -                     | Called (debounced) with the trimmed query as the user types. Refetch your data here for server-side search.                                            |
+| `searchDebounceMs` | `number`                                                  | `300`                 | Debounce delay (ms) before `onSearchChange` fires.                                                                                                     |
+| `hasMore`          | `boolean`                                                 | `false`               | Whether more pages are available; gates the infinite-scroll loader.                                                                                    |
+| `loading`          | `boolean`                                                 | `false`               | Whether a fetch is in flight; shows a loading row and blocks `onLoadMore`.                                                                             |
+| `onLoadMore`       | `() => void`                                              | -                     | Called when the scroll viewport nears the bottom and `hasMore && !loading`.                                                                            |
+| `maxVisibleItems`  | `number`                                                  | `5`                   | Maximum rows visible before the list scrolls internally.                                                                                               |
 
 ### SearchableSelectOption
 
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `value` | `string` | Required | Unique value for the option; matched against the `value` prop. |
-| `label` | `string` | Required | Display text; also used for client-side label filtering. |
-| `icon` | `ReactNode` | - | Optional leading icon rendered in the row. |
+| Prop         | Type        | Default  | Description                                                                                                                                                                      |
+| ------------ | ----------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `value`      | `string`    | Required | Unique value for the option; matched against the `value` prop.                                                                                                                   |
+| `label`      | `string`    | Required | Display text; also the default target for client-side filtering.                                                                                                                 |
+| `icon`       | `ReactNode` | -        | Optional leading icon rendered in the row.                                                                                                                                       |
+| `searchText` | `string`    | `label`  | Text used for client-side filtering. Set it to match on a **subset** of the label — e.g. a country name when the label also shows a dial code, so typing the dial doesn't match. |
 
 ## TypeScript
 
 ### Type Definitions
 
 ```typescript
-import { ReactNode } from 'react'
+import { ReactNode } from "react";
 
 export interface SearchableSelectOption {
-  value: string
-  label: string
-  icon?: ReactNode
+  value: string;
+  label: string;
+  icon?: ReactNode;
+  /** Text used for client-side filtering. Defaults to `label`. */
+  searchText?: string;
 }
 
 interface SearchableSelectProps {
-  options: SearchableSelectOption[]
-  value?: string | null
-  onValueChange?: (value: string, option: SearchableSelectOption) => void
-  placeholder?: string
-  size?: 'XS' | 'S' | 'M'
-  variant?: 'PresentationStyle'
-  icon?: ReactNode
-  theme?: 'dark' | 'light' | 'default'
-  dir?: string
-  className?: string
+  options: SearchableSelectOption[];
+  value?: string | null;
+  onValueChange?: (value: string, option: SearchableSelectOption) => void;
+  placeholder?: string;
+  size?: "XS" | "S" | "M";
+  variant?: "PresentationStyle";
+  icon?: ReactNode;
+  theme?: "dark" | "light" | "default";
+  dir?: string;
+  className?: string;
 
   // Async / backend pagination (all optional; static `options` still work)
-  filterClientSide?: boolean
-  onSearchChange?: (query: string) => void
-  searchDebounceMs?: number
-  hasMore?: boolean
-  loading?: boolean
-  onLoadMore?: () => void
-  maxVisibleItems?: number
+  filterClientSide?: boolean;
+  onSearchChange?: (query: string) => void;
+  searchDebounceMs?: number;
+  hasMore?: boolean;
+  loading?: boolean;
+  onLoadMore?: () => void;
+  maxVisibleItems?: number;
 }
 
-export function SearchableSelect(props: SearchableSelectProps): JSX.Element
+export function SearchableSelect(props: SearchableSelectProps): JSX.Element;
 ```
 
 ## Common Patterns
@@ -340,6 +343,7 @@ function UserPicker() {
 ## Best Practices
 
 1. **Always control `value`** — pass `value` and `onValueChange` so the input can display the selected label.
+
    ```typescript
    <SearchableSelect value={value} onValueChange={setValue} options={options} />
    ```

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">