torch-glare 2.3.0 → 2.4.1

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

@@ -0,0 +1,128 @@
+---
+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 ChartBlockTool
+```
+
+It depends on the `chart.js` npm package (installed automatically by the CLI).
+
+## Import
+
+```typescript
+import ChartBlockTool, { ChartBlockData } from "@/components/ChartBlockTool";
+```
+
+## Quick Examples
+
+### Register it in an Editor.js instance
+
+```typescript
+import EditorJS from "@editorjs/editorjs";
+import ChartBlockTool from "@/components/ChartBlockTool";
+
+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 { ChartBlockData } from "@/components/ChartBlockTool";
+
+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/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 (
@@ -233,6 +226,33 @@ function RtlMenu() {
 }
 ```
 
+### Long Menu (max height + scroll)
+
+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 "@/components/ContextMenu";
+
+function LongMenu() {
+  return (
+    <ContextMenu>
+      <ContextMenuTrigger asChild>
+        <div className="flex h-40 w-72 items-center justify-center rounded-md border border-dashed">
+          Right-click here
+        </div>
+      </ContextMenuTrigger>
+      {/* Cap the surface at 220px — the rest scrolls. */}
+      <ContextMenuContent maxHeight={220}>
+        <ContextMenuLabel>Jump to section</ContextMenuLabel>
+        {Array.from({ length: 20 }, (_, i) => (
+          <ContextMenuItem key={i}>Section {i + 1}</ContextMenuItem>
+        ))}
+      </ContextMenuContent>
+    </ContextMenu>
+  )
+}
+```
+
 ## API Reference
 
 ### ContextMenu (Root)
@@ -264,6 +284,7 @@ The right-click zone. Wrap it around the element the menu should open from.
 | `theme` | `'dark' \| 'light' \| 'default'` | - | Theme variant (applied as `data-theme`) |
 | `className` | `string` | - | Additional CSS classes |
 | `collisionPadding` | `number` | `8` | Min distance kept from the viewport edge |
+| `maxHeight` | `number` | `320` | Max height (px) of the surface before it scrolls. Capped at `min(maxHeight, available-height)` so the menu never overflows off-screen |
 | `autoGroup` | `boolean` | `true` | Auto-wrap loose items in a Boxed group (see Behavior notes) |
 
 ### ContextMenuItem
@@ -353,6 +374,7 @@ interface ContextMenuContentProps {
   theme?: 'dark' | 'light' | 'default'
   className?: string
   collisionPadding?: number // default 8
+  maxHeight?: number         // default 320 — surface scrolls past this
   autoGroup?: boolean        // default true
 }
 
@@ -403,6 +425,7 @@ export const ContextMenuRadioItem: React.ForwardRefExoticComponent<ContextMenuRa
 - **Opens at the pointer**: the menu opens on right-click (`contextmenu`) at the exact cursor position, not anchored to a fixed trigger button.
 - **Second right-click closes it**: the Root is made controlled and tracks `open` in context. The Trigger listens in the capture phase, and when the menu is already open it `preventDefault()` / `stopPropagation()` and closes — so a second right-click dismisses instead of re-anchoring (which Radix handles unreliably).
 - **Auto-grouping**: by default (`autoGroup` on `ContextMenuContent`, default `true`) consecutive loose items (`ContextMenuItem`, `ContextMenuCheckboxItem`, `ContextMenuRadioItem`, and `ContextMenuSub`) are automatically wrapped in a `Boxed` `ContextMenuGroup`, so they render inside a boxed container like DropdownMenu even when you do not write a group. Labels and explicit groups act as boundaries and pass through unchanged. Set `autoGroup={false}` to render children verbatim.
+- **Max height & scrolling**: the surface caps its height at `min(maxHeight, available-height)` (where `maxHeight` defaults to `320`px and `available-height` is the space Radix has after collision handling). A taller menu scrolls vertically instead of overflowing off-screen — items and groups keep their full height rather than squishing. Pass `maxHeight={N}` to change the cap.
 - **Checkbox / radio keep the menu open**: `ContextMenuCheckboxItem` and `ContextMenuRadioItem` call `event.preventDefault()` inside `onSelect`, stopping Radix's default auto-close so users can toggle multiple options in one pass.
 - **Open-only animation**: only the open (enter) state animates (`fade-in`). There is intentionally no exit animation — holding the old DOM node during close breaks close/reposition on a second right-click, so it is omitted to keep repositioning reliable.
 - **Submenus and RTL**: nested `ContextMenuSub` / `ContextMenuSubTrigger` / `ContextMenuSubContent` are supported, and `dir="rtl"` on the Root mirrors the layout (including the submenu chevron).

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

package/docs/components/data-table.md

@@ -11,15 +11,22 @@ keywords: [table, datatable, grid, sorting, selection, drag-drop, reorder, pagin
 
 ## 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 @tanstack/react-table @dnd-kit/core @dnd-kit/sortable @dnd-kit/utilities
+npx torch-glare@latest init
+npx torch-glare@latest add DataTable
 ```
 
+`add` also copies any components, hooks, and utilities that `DataTable` depends on.
+
 ## Import
 
-```typescript
-import { DataTable } from '@torch-ui/components'
-import { ColumnDef } from '@tanstack/react-table'
+Import from your project's local path — the alias configured in `glare.json` (e.g. `@/*`):
+
+```tsx
+import { DataTable } from "@/components/DataTable";
 ```
 
 ## Quick Examples
@@ -27,7 +34,7 @@ import { ColumnDef } from '@tanstack/react-table'
 ### Basic Usage
 
 ```typescript
-import { DataTable } from '@torch-ui/components'
+import { DataTable } from "@/components/DataTable";
 import { ColumnDef } from '@tanstack/react-table'
 
 interface User {
@@ -66,7 +73,7 @@ function Example() {
 ### With Row Reordering
 
 ```typescript
-import { DataTable } from '@torch-ui/components'
+import { DataTable } from "@/components/DataTable";
 import { useState } from 'react'
 
 function ReorderableTable() {
@@ -97,8 +104,8 @@ function ReorderableTable() {
 ### With Custom Cell Rendering
 
 ```typescript
-import { DataTable } from '@torch-ui/components'
-import { Badge } from '@torch-ui/components'
+import { DataTable } from "@/components/DataTable";
+import { Badge } from "@/components/Badge";
 import { ColumnDef } from '@tanstack/react-table'
 
 interface Task {
@@ -124,7 +131,7 @@ const columns: ColumnDef<Task>[] = [
         completed: 'green',
       }[status]
 
-      return <Badge variant={variant} label={status} />
+      return <Badge color={variant} label={status} />
     },
   },
   {
@@ -147,7 +154,7 @@ function TaskTable() {
 ### With Sortable Columns
 
 ```typescript
-import { DataTable } from '@torch-ui/components'
+import { DataTable } from "@/components/DataTable";
 import { ColumnDef } from '@tanstack/react-table'
 
 interface Product {
@@ -190,8 +197,8 @@ function ProductTable() {
 ### With Actions Column
 
 ```typescript
-import { DataTable } from '@torch-ui/components'
-import { ActionButton } from '@torch-ui/components'
+import { DataTable } from "@/components/DataTable";
+import { ActionButton } from "@/components/ActionButton";
 import { ColumnDef } from '@tanstack/react-table'
 
 interface User {
@@ -246,7 +253,7 @@ function UserTable() {
 ### With Selection Handling
 
 ```typescript
-import { DataTable } from '@torch-ui/components'
+import { DataTable } from "@/components/DataTable";
 import { useState } from 'react'
 
 function SelectableTable() {
@@ -280,7 +287,7 @@ function SelectableTable() {
 ### Dark Theme
 
 ```typescript
-import { DataTable } from '@torch-ui/components'
+import { DataTable } from "@/components/DataTable";
 
 function DarkTable() {
   const columns = [
@@ -300,7 +307,7 @@ function DarkTable() {
 ### Complex Data with Nested Objects
 
 ```typescript
-import { DataTable } from '@torch-ui/components'
+import { DataTable } from "@/components/DataTable";
 import { ColumnDef } from '@tanstack/react-table'
 
 interface Order {
@@ -363,7 +370,7 @@ function OrderTable() {
 ### Empty State
 
 ```typescript
-import { DataTable } from '@torch-ui/components'
+import { DataTable } from "@/components/DataTable";
 
 function EmptyTable() {
   const columns = [
@@ -468,7 +475,7 @@ DataTable<TData extends { id: string | number }, TValue>
 ### Controlled Row Selection
 
 ```typescript
-import { DataTable } from '@torch-ui/components'
+import { DataTable } from "@/components/DataTable";
 import { useState } from 'react'
 
 function ControlledSelectionTable() {
@@ -495,8 +502,8 @@ function ControlledSelectionTable() {
 ### With Search/Filter
 
 ```typescript
-import { DataTable } from '@torch-ui/components'
-import { Input } from '@torch-ui/components'
+import { DataTable } from "@/components/DataTable";
+import { Input } from "@/components/Input";
 import { useState, useMemo } from 'react'
 
 function SearchableTable() {
@@ -536,7 +543,7 @@ function SearchableTable() {
 ### Persisting Row Order
 
 ```typescript
-import { DataTable } from '@torch-ui/components'
+import { DataTable } from "@/components/DataTable";
 import { useState, useEffect } from 'react'
 
 function PersistentOrderTable() {
@@ -569,16 +576,21 @@ function PersistentOrderTable() {
 
 ## Features
 
-### Built-in Capabilities
+The component's props are `columns`, `data`, `theme`, and `onRowReorder` — see the API
+Reference. Its built-in, rendered capabilities are:
+
+- **Row Selection**: Multi-row selection checkboxes (select all / select individual) are
+  rendered and tracked internally. Selection state persists through reordering. Note: the
+  component does not expose a selection-change prop — selection is internal visual state.
+- **Drag & Drop**: Reorder rows by dragging; `onRowReorder` returns the new data array
+  (keyboard drag supported via dnd-kit).
+- **Column Sorting**: Click headers to sort ascending/descending.
+- **Custom Cells**: Full control over cell rendering via each column's `cell`.
+- **Type Safety**: Full TypeScript support with generics.
 
-- **Row Selection**: Multi-row selection with checkboxes (select all, select individual)
-- **Drag & Drop**: Reorder rows by dragging (maintains selection state)
-- **Column Sorting**: Click headers to sort ascending/descending
-- **Pagination**: Built-in pagination support (via TanStack Table)
-- **Filtering**: Client-side filtering capabilities
-- **Custom Cells**: Full control over cell rendering
-- **Keyboard Navigation**: Drag-and-drop with keyboard support
-- **Type Safety**: Full TypeScript support with generics
+> The TanStack pagination and filtering **row models** are enabled internally, but the
+> component renders **no** pagination or filter controls and exposes no page/filter props.
+> To paginate or filter, wrap the data yourself or compose your own controls around it.
 
 ### Drag-and-Drop Behavior
 
@@ -601,7 +613,7 @@ function PersistentOrderTable() {
 
 ```typescript
 import { render, screen, fireEvent } from '@testing-library/react'
-import { DataTable } from '@torch-ui/components'
+import { DataTable } from "@/components/DataTable";
 import { ColumnDef } from '@tanstack/react-table'
 
 const mockData = [
@@ -651,7 +663,7 @@ describe('DataTable', () => {
 
 ```typescript
 import { render, screen, fireEvent } from '@testing-library/react'
-import { DataTable } from '@torch-ui/components'
+import { DataTable } from "@/components/DataTable";
 
 test('row selection works correctly', () => {
   const columns = [{ accessorKey: 'name', header: 'Name' }]
@@ -767,7 +779,7 @@ const columns: ColumnDef<User>[] = [
 
 ```diff
 - import { DataGrid } from '@mui/x-data-grid'
-+ import { DataTable } from '@torch-ui/components'
++ import { DataTable } from "@/components/DataTable";
 + import { ColumnDef } from '@tanstack/react-table'
 
 - <DataGrid rows={data} columns={columns} />
@@ -778,7 +790,7 @@ const columns: ColumnDef<User>[] = [
 
 ```diff
 - import { useTable } from 'react-table'
-+ import { DataTable } from '@torch-ui/components'
++ import { DataTable } from "@/components/DataTable";
 + import { ColumnDef } from '@tanstack/react-table'
 
 - const { getTableProps, rows } = useTable({ columns, data })

package/docs/components/data-views-config-panel.md

@@ -13,16 +13,22 @@ keywords: [data-views, config panel, config-panel, settings panel, saved view, s
 
 ## Installation
 
-Part of `torch-glare`. Ships with the `DataViews` folder when you run
-`npx torch-glare add DataViews` — no separate install. It depends on the
-shared `Radio`, `Switch`, `Label`, `FilterPanel`, and a colocated internal
-`PanelControls` file (see "Internal: PanelControls" below).
+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-glare@latest init
+npx torch-glare@latest add DataViewsConfigPanel
+```
+
+`add` also copies any components, hooks, and utilities that `DataViewsConfigPanel` depends on.
 
 ## Import
 
+Import from your project's local path — the alias configured in `glare.json` (e.g. `@/*`):
+
 ```tsx
-import { DataViewsConfigPanel } from "torch-glare"
-import type { DataViewsConfigPanelProps } from "torch-glare"
+import { DataViewsConfigPanel } from "@/components/DataViewsConfigPanel";
 ```
 
 ## When to use it directly
@@ -36,11 +42,9 @@ import type { DataViewsConfigPanelProps } from "torch-glare"
 ## Standalone Example (composable mode)
 
 ```tsx
-import {
-  DataViewsConfigPanel,
-  TableView,
-  useDataViewsState,
-} from "torch-glare"
+import { DataViewsConfigPanel } from "@/components/DataViewsConfigPanel";
+import { TableView } from "@/components/TableView";
+import { useDataViewsState } from "@/hooks/useDataViewsState";
 import { useState } from "react"
 
 function CustomScreen({ data, fields }) {
@@ -148,7 +152,7 @@ render `DataViewsConfigPanel` yourself (example above) or extend the layout
 | Saved View | `savedViews` / `activeSavedView` | Radio list + "Save a New View" button. |
 | Table Columns | `config.tableColumns` | Green `Switch` per column toggles `visible`; rows are drag-reorderable (HTML5 DnD) and patch `order`. |
 | Default Sort | `config.sortBy` | Single-choice radio; selecting sets `sortBy`. Direction stays on `config.sortOrder`. |
-| Filters tab | `filterState` + `fields` | Renders `FilterPanel` restyled full-width/transparent. |
+| Filters tab | `filterState` + `fields` | Renders `FilterPanel` restyled full-width/transparent. Categorical fields render as checkbox/radio lists, or a `SearchableSelect` dropdown when a field sets `filterVariant: "searchable-select"`. |
 
 ## Internal: PanelControls
 
@@ -173,8 +177,8 @@ Common changes and where to make them:
 |---|---|
 | Make Saved View work through `DataViewsLayout` | Add `savedViews` / `activeSavedView` / `onSavedViewChange` / `onSaveNewView` to `DataViewsLayoutProps`, hold them in layout state (or accept from the host), and forward them to `<DataViewsConfigPanel>` at its render site in `DataViewsLayout.tsx`. |
 | Add a new Config section | Add a new block inside the Config. tab in `DataViewsConfigPanel.tsx`, backed by a `config.*` field so `onConfigChange` persists it. |
-| Restyle a radio/toggle | Edit `PanelControls.tsx`. Keep values matching the Figma spec; do not swap in the shared `Radio`/`Label` (they impose theming/layout that fights the dark panel — this was deliberate). |
-| Change the dark chrome | The root forces `data-theme="dark"` and uses hardcoded hex (`#1C1D1F`, `#252729`, `#005ECC`, `#626467`, `#0AC713`). These are intentional Figma values, not tokens. |
+| Restyle a radio/toggle | Edit the radio ring in `DataViewRadio.tsx` (the `RadioRow` in `PanelControls.tsx` just wraps it) or the switch in `PanelControls.tsx`. Keep the hardcoded hex matching the Figma spec; do not swap in the shared `Radio`/`Label` (they impose theming/layout that fights the dark panel — this was deliberate). |
+| Change the dark chrome | The root forces `data-theme="dark"` and uses hardcoded hex (`#1C1D1F`, `#252729`, `#005ECC`, `#0075FF`, `#626467`, `#0AC713`). These are intentional Figma values, not tokens — the radio/checkbox rings hardcode them (`#626467` border, `rgba(255,255,255,0.05)` fill, `#0075FF` selected) so the panel always renders dark regardless of host `data-theme`. |
 
 After any change to the panel docs or component, update this file and rebuild
 the MCP server (`cd mcp && pnpm build`) so the docs the server serves stay in