torch-glare 2.4.0 → 2.4.2

package/docs/components/chart-block-tool.md

@@ -0,0 +1,129 @@
+---
+title: ChartBlockTool
+description: An Editor.js block tool that renders an editable chart.js chart (bar, line, pie, doughnut, radar, polar area) inside the TORCH Glare TextEditor
+group: Advanced
+keywords: [chart-block-tool, editorjs, chart, chartjs, text-editor, block-tool, advanced]
+---
+
+# ChartBlockTool
+
+> An advanced, non-visual module: a custom [Editor.js](https://editorjs.io) **block tool**
+> that renders and edits a [chart.js](https://www.chartjs.org) chart inside the TORCH Glare
+> [TextEditor](./text-editor.md). It is not a React component — it is a block-tool class you
+> register in an Editor.js `tools` config. TextEditor wires it up for you; add it directly only
+> when you build a custom Editor.js instance.
+
+## Installation
+
+TORCH Glare is a copy-in library: the CLI copies this module's source into your project
+(you do **not** install it from the npm package). Run `init` once, then `add`:
+
+```bash
+npx torch-glare@latest init
+npx torch-glare@latest add TextEditor
+```
+
+`ChartBlockTool` ships as part of the `TextEditor` folder, so `add TextEditor` copies it in.
+It depends on the `chart.js` npm package (installed automatically by the CLI).
+
+## Import
+
+```typescript
+import { ChartBlockTool, type ChartBlockData } from "@/components/TextEditor";
+```
+
+## Quick Examples
+
+### Register it in an Editor.js instance
+
+```typescript
+import EditorJS from "@editorjs/editorjs";
+import { ChartBlockTool } from "@/components/TextEditor";
+
+const editor = new EditorJS({
+  holder: "editor",
+  tools: {
+    chart: {
+      class: ChartBlockTool,
+    },
+  },
+});
+```
+
+Once registered, the tool appears in the Editor.js toolbox (title "Chart"). Selecting it
+inserts an editable chart block: a title field, a chart-type selector, and label/dataset
+editors. The block persists as `ChartBlockData` in the editor's saved output.
+
+### The saved data shape
+
+```typescript
+import type { ChartBlockData } from "@/components/TextEditor";
+
+const block: ChartBlockData = {
+  chartType: "bar",
+  title: "Quarterly revenue",
+  labels: ["Q1", "Q2", "Q3", "Q4"],
+  datasets: [
+    {
+      label: "2024",
+      data: [12, 19, 8, 15],
+      backgroundColor: "#3b82f6",
+      borderColor: "#1d4ed8",
+    },
+  ],
+};
+```
+
+## API Reference
+
+`ChartBlockTool` implements the Editor.js `BlockTool` interface. You register the **class**;
+Editor.js constructs and calls it. Its public surface:
+
+### Props
+
+| Member | Type | Description |
+|--------|------|-------------|
+| `default export` | `class ChartBlockTool` | The block-tool class to pass as `tools.chart.class`. |
+| `static toolbox` | `{ title: string; icon: string }` | Toolbox entry (title "Chart" + icon) shown in the Editor.js block menu. |
+| `static isReadOnlySupported` | `boolean` | `true` — the block renders in read-only editors. |
+| `constructor` | `({ data, api, readOnly }) => ChartBlockTool` | Called by Editor.js with the saved `data` (`Partial<ChartBlockData>`), the editor `api`, and the `readOnly` flag. |
+| `render()` | `() => HTMLElement` | Returns the block's DOM (editor UI or read-only chart). |
+| `save()` | `() => ChartBlockData` | Returns the block's current data for persistence. |
+
+### TypeScript
+
+```typescript
+export interface ChartBlockData {
+  chartType: "bar" | "line" | "pie" | "doughnut" | "radar" | "polarArea";
+  title: string;
+  labels: string[];
+  datasets: Array<{
+    label: string;
+    data: number[];
+    backgroundColor: string;
+    borderColor: string;
+  }>;
+}
+
+export default class ChartBlockTool {
+  static get isReadOnlySupported(): boolean;
+  static get toolbox(): { title: string; icon: string };
+  constructor(options: { data: Partial<ChartBlockData>; api: any; readOnly: boolean });
+  render(): HTMLElement;
+  save(): ChartBlockData;
+}
+```
+
+## Common Patterns
+
+- **Use via TextEditor:** most apps should use [TextEditor](./text-editor.md), which registers
+  this tool for you — you rarely construct it directly.
+- **Custom Editor.js:** when building your own Editor.js instance, register the class under a
+  `tools` key; Editor.js handles construction and lifecycle.
+- **Supported chart types:** `bar`, `line`, `pie`, `doughnut`, `radar`, `polarArea` (from
+  `ChartBlockData["chartType"]`).
+
+## Related Components
+
+- [TextEditor](./text-editor.md) — the rich-text editor that hosts this block tool.
+- [TableDnDWrapper](./table-dnd-wrapper.md) — another internal Editor.js tool module.

package/docs/components/checkbox.md

@@ -1,6 +1,6 @@
 ---
 name: Checkbox
-version: 1.1.15
+version: 2.4.0
 status: stable
 category: components/forms
 tags: [form, checkbox, selection, radix-ui, accessible, controlled]
@@ -17,14 +17,22 @@ dependencies:
 
 ## Installation
 
+TORCH Glare is a copy-in library: the CLI copies this component's source into your project
+(you do **not** install it from the npm package). Run `init` once, then `add`:
+
 ```bash
-npm install torch-glare
+npx torch-glare@latest init
+npx torch-glare@latest add Checkbox
 ```
 
+`add` also copies any components, hooks, and utilities that `Checkbox` depends on.
+
 ## Import
 
-```typescript
-import { Checkbox } from 'torch-glare/lib/components/Checkbox'
+Import from your project's local path — the alias configured in `glare.json` (e.g. `@/*`):
+
+```tsx
+import { Checkbox } from "@/components/Checkbox";
 ```
 
 ## Quick Examples
@@ -32,7 +40,7 @@ import { Checkbox } from 'torch-glare/lib/components/Checkbox'
 ### Basic Usage
 
 ```typescript
-import { Checkbox } from 'torch-glare/lib/components/Checkbox'
+import { Checkbox } from '@/components/Checkbox'
 
 function Example() {
   const [checked, setChecked] = useState(false)
@@ -402,7 +410,7 @@ function FilterPanel() {
 
 ```typescript
 import { render, screen, fireEvent } from '@testing-library/react'
-import { Checkbox } from 'torch-glare/lib/components/Checkbox'
+import { Checkbox } from '@/components/Checkbox'
 
 describe('Checkbox', () => {
   it('handles checked state changes', () => {
@@ -609,10 +617,10 @@ Radix UI automatically handles ARIA attributes:
 ```diff
 // Import path changed
 - import Checkbox from 'torch-glare/Checkbox'
-+ import { Checkbox } from 'torch-glare/lib/components/Checkbox'
++ import { Checkbox } from '@/components/Checkbox'
 
 // Size prop values changed
-- <Checkbox size="small" />
+- <Checkbox size="M" />
 + <Checkbox size="S" />
 ```
 

package/docs/components/cn-layout.md

@@ -12,10 +12,16 @@ A complete layout system for building dashboard and admin panel interfaces. Feat
 
 ## Installation
 
+TORCH Glare is a copy-in library: the CLI copies this component's source into your project
+(you do **not** install it from the npm package). Run `init` once, then `add`:
+
 ```bash
-npx torch-cli add cn-layout
+npx torch-glare@latest init
+npx torch-glare@latest add CnLayout
 ```
 
+`add` also copies any components, hooks, and utilities that `CnLayout` depends on.
+
 ## Imports
 
 ```typescript

package/docs/components/color-picker.md

@@ -0,0 +1,101 @@
+---
+title: ColorPicker
+description: A full Figma-style color picker with a saturation/value area, hue and opacity sliders, an eyedropper, switchable HEX/RGB/HSL inputs, and preset swatches
+group: Forms
+keywords: [color-picker, color, palette, hex, rgb, hsl, hsv, opacity, alpha, eyedropper, swatch]
+---
+
+# ColorPicker
+
+> A full Figma-style color palette opened from **a trigger you supply**: a draggable
+> saturation/value area, a hue slider, an optional opacity slider, an eyedropper (where the
+> browser supports it), switchable **HEX / RGB / HSL** numeric inputs, and preset swatches.
+> The value is always a hex string.
+
+## Installation
+
+```bash
+npx torch-glare@latest init
+npx torch-glare@latest add ColorPicker
+```
+
+`add` also copies its dependencies — `utils/color` (the pure hex/RGB/HSV/HSL math), plus the
+`Popover` and `Input` components.
+
+## Import
+
+```tsx
+import { ColorPicker } from "@/components/ColorPicker";
+```
+
+## Usage
+
+ColorPicker renders **no trigger of its own** — you pass one as its child (rendered via `asChild`,
+so it must forward ref/props to a DOM node). The current color is handed to that child based on
+what it is:
+
+| Child | Receives |
+|---|---|
+| an **input** — native `<input>`/`<textarea>`, or any element already given a `value` prop | the hex as **`value`** (plus an `onChange` that commits a typed hex, if you didn't supply one) |
+| **anything else** | the hex as **`children`** — unless it already has children, which are left untouched |
+
+```tsx
+const [color, setColor] = useState("#3B82F6");
+
+// input child → gets `value={color}`
+<ColorPicker value={color} onChange={setColor}>
+  <input className="…" />
+</ColorPicker>
+
+// non-input child → gets the hex as its content
+<ColorPicker value={color} onChange={setColor}>
+  <Button variant="BorderStyle" />
+</ColorPicker>
+
+// a child with its own content keeps it — render the value yourself
+<ColorPicker value={color} onChange={setColor}>
+  <button type="button">
+    <span style={{ backgroundColor: color }} />
+    {color}
+  </button>
+</ColorPicker>
+```
+
+With presets and opacity disabled (always emits `#rrggbb`):
+
+```tsx
+<ColorPicker
+  value={color}
+  onChange={setColor}
+  alpha={false}
+  presets={["#005ECC", "#047854", "#E30C30", "#F5A623"]}
+>
+  <Button variant="BorderStyle" />
+</ColorPicker>
+```
+
+## Props
+
+| Prop        | Type                       | Default       | Description                                                                 |
+| ----------- | -------------------------- | ------------- | --------------------------------------------------------------------------- |
+| `children`  | `ReactElement`             | — (required)  | The trigger. Gets the hex as `value` if it's an input, else as `children`.   |
+| `value`     | `string`                   | `"#000000"`   | Current color as a hex string (`#rrggbb` or `#rrggbbaa`).                    |
+| `onChange`  | `(hex: string) => void`    | —             | Called on every change. Emits `#rrggbbaa` only when opacity < 100%.         |
+| `presets`   | `string[]`                 | —             | Quick-pick swatches shown at the bottom of the panel.                       |
+| `alpha`     | `boolean`                  | `true`        | Show the opacity slider + input and allow 8-digit output.                    |
+| `disabled`  | `boolean`                  | `false`       | Disable the trigger and all controls.                                       |
+| `theme`     | `"dark" \| "light" \| "default"` | —       | Applied as `data-theme`.                                                     |
+
+## Value format
+
+The value stays `#rrggbb` while fully opaque (backward-compatible with plain hex fields) and is
+promoted to `#rrggbbaa` only when opacity drops below 100%. Feeding a 3-, 6-, or 8-digit hex
+(with or without `#`) back in via `value` is always accepted.
+
+## Notes
+
+- The **eyedropper** button appears only where the native [`EyeDropper` API](https://developer.mozilla.org/docs/Web/API/EyeDropper)
+  is available (Chromium/Edge); it is hidden on Firefox/Safari.
+- Used by `FormBuilder.Color` — see [form-builder.md](./form-builder.md).
+- Color math lives in `utils/color` (`parseHex`, `formatHex`, `rgbToHsv`, `hsvToRgb`,
+  `rgbToHsl`, `hslToRgb`) and is reusable on its own.

package/docs/components/conclusion-header.md

@@ -0,0 +1,80 @@
+---
+title: ConclusionHeader
+description: A clickable section header with a chevron toggle — white-alpha hover surfaces, chevron down when open and sideways when closed, and a "Disabled" badge when disabled. Direction-aware (LTR/RTL). Used for each FormSummary group title.
+component: true
+group: Layout & Containers
+keywords: [conclusion-header, collapsible, header, disclosure, accordion, toggle, chevron, expand, collapse, section]
+---
+
+# ConclusionHeader
+
+A clickable **section header** that toggles a collapsible region, per the
+*Conclusion-Header-2.0* design. Its surfaces are **button overlays** (not an input field): at
+rest the label stands alone, and on hover it gains a `Button/ContStyle-Hover` pill while the
+chevron gains a `Button/Secondary` box. The chevron is hidden at rest while open, shows
+**sideways** when closed (left in LTR, right in RTL), and flips to **down** on hover. When
+`disabled` the label greys out, truncates at 120px, and a gray-subtle `Badge` replaces the
+chevron.
+
+It renders only the header — you own the collapsible body. It works **uncontrolled**
+(manages its own open state) or **controlled** (pass `open` + `onOpenChange`):
+
+```tsx
+// Uncontrolled — reflect the state with onOpenChange
+const [open, setOpen] = useState(true)
+
+<ConclusionHeader label="Invoice" defaultOpen onOpenChange={setOpen} />
+{open && <section>…body…</section>}
+
+// Controlled — you drive `open`
+<ConclusionHeader label="Invoice" open={open} onOpenChange={setOpen} />
+```
+
+## Installation
+
+```bash
+npx torch-glare@latest init
+npx torch-glare@latest add ConclusionHeader
+```
+
+## Imports
+
+```tsx
+import { ConclusionHeader } from '@/components/ConclusionHeader'
+```
+
+## Props
+
+| Prop | Type | Default | Notes |
+|---|---|---|---|
+| `label` | `ReactNode` | — | The header text. |
+| `open` | `boolean` | — | **Controlled** open state. Omit to let the header manage its own. |
+| `defaultOpen` | `boolean` | `true` | Initial open state when **uncontrolled**. |
+| `onOpenChange` | `(open: boolean) => void` | — | Called with the next open state on click. |
+| `disabled` | `boolean` | `false` | Greys the label and shows a `Badge` instead of the chevron. |
+| `disabledLabel` | `string` | `"Disabled"` | Badge text when `disabled`. |
+| `theme` | `'dark' \| 'light' \| 'default'` | — | Theme override; otherwise inherits the nearest `data-theme`. |
+
+Extra props spread to the underlying `<button>`, which is what the header renders — so it is
+focusable, toggles on <kbd>Enter</kbd>/<kbd>Space</kbd>, and exposes `aria-expanded` for
+free. A `ref` is forwarded to that `HTMLButtonElement`.
+
+## Behaviour
+
+- **Open** (rest): label only — no surface, no chevron.
+- **Open hover**: `Button/ContStyle-Hover` pill (label inset 4px) + `Button/Secondary`
+  chevron box with a **down** chevron.
+- **Closed** (rest): label + a bare **sideways** chevron (`<` LTR / `>` RTL), no box.
+- **Closed hover**: same surfaces as open hover; the chevron flips to down.
+- **Disabled**: greyed label truncated at 120px + a `● Disabled` badge sitting beside it
+  (not at the row's end); not clickable.
+
+Direction is inherited from the ambient `dir` — the design's RTL variants are the LTR ones
+mirrored, which the component's logical properties produce automatically.
+
+## Composition
+
+Uses the design-system tokens directly (`Button/Secondary`, `Button/ContStyle-Hover`) rather
+than the input/button components, and reuses [Badge](./badge.md) for the disabled state.
+[FormSummary](./form-summary.md) uses it as each **group** title, so every group of totals
+collapses independently.

package/docs/components/context-menu.md

@@ -11,29 +11,22 @@ keywords: [context-menu, right-click, menu, radix-ui, submenu, checkbox, context
 
 ## Installation
 
+TORCH Glare is a copy-in library: the CLI copies this component's source into your project
+(you do **not** install it from the npm package). Run `init` once, then `add`:
+
 ```bash
-npm install @radix-ui/react-context-menu
+npx torch-glare@latest init
+npx torch-glare@latest add ContextMenu
 ```
 
+`add` also copies any components, hooks, and utilities that `ContextMenu` depends on.
+
 ## Import
 
-```typescript
-import {
-  ContextMenu,
-  ContextMenuTrigger,
-  ContextMenuContent,
-  ContextMenuItem,
-  ContextMenuGroup,
-  ContextMenuRadioGroup,
-  ContextMenuCheckboxItem,
-  ContextMenuRadioItem,
-  ContextMenuLabel,
-  ContextMenuShortcut,
-  ContextMenuSub,
-  ContextMenuSubTrigger,
-  ContextMenuSubContent,
-  ContextMenuPortal,
-} from '@torch-ui/components'
+Import from your project's local path — the alias configured in `glare.json` (e.g. `@/*`):
+
+```tsx
+import { ContextMenu } from "@/components/ContextMenu";
 ```
 
 ## Quick Examples
@@ -43,7 +36,7 @@ import {
 Wrap the right-click zone in `ContextMenuTrigger`. The menu opens at the pointer.
 
 ```typescript
-import { ContextMenu, ContextMenuTrigger, ContextMenuContent, ContextMenuItem } from '@torch-ui/components'
+import { ContextMenu, ContextMenuTrigger, ContextMenuContent, ContextMenuItem } from "@/components/ContextMenu";
 
 function Example() {
   return (
@@ -66,7 +59,7 @@ function Example() {
 ### With Icons, Shortcuts, and a Negative Item
 
 ```typescript
-import { ContextMenu, ContextMenuTrigger, ContextMenuContent, ContextMenuItem, ContextMenuShortcut } from '@torch-ui/components'
+import { ContextMenu, ContextMenuTrigger, ContextMenuContent, ContextMenuItem, ContextMenuShortcut } from "@/components/ContextMenu";
 
 function ActionsMenu() {
   return (
@@ -103,7 +96,7 @@ function ActionsMenu() {
 > Clicking a checkbox item keeps the menu open — `onSelect` calls `preventDefault()` internally so Radix does not auto-close. Toggle several options without the menu dismissing.
 
 ```typescript
-import { ContextMenu, ContextMenuTrigger, ContextMenuContent, ContextMenuCheckboxItem } from '@torch-ui/components'
+import { ContextMenu, ContextMenuTrigger, ContextMenuContent, ContextMenuCheckboxItem } from "@/components/ContextMenu";
 import { useState } from 'react'
 
 function CheckboxMenu() {
@@ -148,7 +141,7 @@ function CheckboxMenu() {
 > Like checkboxes, selecting a radio item keeps the menu open (`onSelect` `preventDefault` is built in).
 
 ```typescript
-import { ContextMenu, ContextMenuTrigger, ContextMenuContent, ContextMenuRadioGroup, ContextMenuRadioItem } from '@torch-ui/components'
+import { ContextMenu, ContextMenuTrigger, ContextMenuContent, ContextMenuRadioGroup, ContextMenuRadioItem } from "@/components/ContextMenu";
 import { useState } from 'react'
 
 function RadioMenu() {
@@ -176,7 +169,7 @@ function RadioMenu() {
 ### With Submenu
 
 ```typescript
-import { ContextMenu, ContextMenuTrigger, ContextMenuContent, ContextMenuItem, ContextMenuSub, ContextMenuSubTrigger, ContextMenuSubContent } from '@torch-ui/components'
+import { ContextMenu, ContextMenuTrigger, ContextMenuContent, ContextMenuItem, ContextMenuSub, ContextMenuSubTrigger, ContextMenuSubContent } from "@/components/ContextMenu";
 
 function SubmenuExample() {
   return (
@@ -211,7 +204,7 @@ function SubmenuExample() {
 Set `dir="rtl"` on the Root and the menu, items, and submenu arrows mirror automatically.
 
 ```typescript
-import { ContextMenu, ContextMenuTrigger, ContextMenuContent, ContextMenuItem, ContextMenuShortcut } from '@torch-ui/components'
+import { ContextMenu, ContextMenuTrigger, ContextMenuContent, ContextMenuItem, ContextMenuShortcut } from "@/components/ContextMenu";
 
 function RtlMenu() {
   return (
@@ -238,7 +231,7 @@ function RtlMenu() {
 Tall menus scroll instead of overflowing off-screen. The surface caps at `maxHeight` (default `320`px) and never exceeds the space available after collision handling. Pass `maxHeight` to change the cap.
 
 ```typescript
-import { ContextMenu, ContextMenuTrigger, ContextMenuContent, ContextMenuItem, ContextMenuLabel } from '@torch-ui/components'
+import { ContextMenu, ContextMenuTrigger, ContextMenuContent, ContextMenuItem, ContextMenuLabel } from "@/components/ContextMenu";
 
 function LongMenu() {
   return (

package/docs/components/count-badge.md

@@ -12,10 +12,16 @@ A compact circular badge component designed specifically for displaying numeric
 
 ## Installation
 
+TORCH Glare is a copy-in library: the CLI copies this component's source into your project
+(you do **not** install it from the npm package). Run `init` once, then `add`:
+
 ```bash
-npx torch-cli add count-badge
+npx torch-glare@latest init
+npx torch-glare@latest add CountBadge
 ```
 
+`add` also copies any components, hooks, and utilities that `CountBadge` depends on.
+
 ## Imports
 
 ```typescript