torch-glare 2.4.0 → 2.4.1

package/docs/components/searchable-tree-dialog.md

@@ -0,0 +1,190 @@
+---
+title: SearchableTreeDialog
+description: Searchable tree-select presented in a modal dialog — a trigger opens a dialog containing a searchable hierarchical tree, with client or server-side search
+group: Inputs
+keywords: [searchable-tree-dialog, tree, tree-select, dialog, modal, hierarchy, search, async]
+---
+
+# SearchableTreeDialog
+
+> A searchable tree-select that opens in a modal **Dialog** instead of a popover. A trigger
+> field opens a dialog containing a search input and a hierarchical tree of nodes, filtered as
+> you type. Accepts nested data (via `getNodeChildren`) or a flat list it nests for you (via
+> `parentIdKey`). Supports local filtering or debounced server-side search, optional folder
+> selection, and controlled selection. Use it instead of [SearchableTree](./searchable-tree.md)
+> when the tree is large or you want a focused, full-screen-friendly selection surface.
+
+## 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-glare@latest init
+npx torch-glare@latest add SearchableTreeDialog
+```
+
+The CLI also copies its internal dependencies: `Button`, `Dialog`, `Input`, and the
+`cn`/`types` utils.
+
+## Import
+
+```typescript
+import { SearchableTreeDialog } from "@/components/SearchableTreeDialog";
+```
+
+## Quick Examples
+
+### Basic Usage (nested data)
+
+```tsx
+import { SearchableTreeDialog } from "@/components/SearchableTreeDialog";
+
+type Node = { id: string; name: string; children?: Node[] };
+
+const data: Node[] = [
+  {
+    id: "eng",
+    name: "Engineering",
+    children: [
+      { id: "fe", name: "Frontend" },
+      { id: "be", name: "Backend" },
+    ],
+  },
+  { id: "design", name: "Design" },
+];
+
+export function DepartmentPicker() {
+  const [value, setValue] = useState<Node | null>(null);
+
+  return (
+    <SearchableTreeDialog
+      nodes={data}
+      getNodeId={(n) => n.id}
+      getNodeLabel={(n) => n.name}
+      getNodeChildren={(n) => n.children}
+      value={value}
+      onSelect={setValue}
+      placeholder="Select a department"
+      searchPlaceholder="Search departments…"
+      title="Departments"
+      size="M"
+    />
+  );
+}
+```
+
+### Flat data (built from a parent id)
+
+```tsx
+type Row = { id: string; label: string; parentId: string | null };
+
+const rows: Row[] = [
+  { id: "1", label: "Company", parentId: null },
+  { id: "2", label: "Sales", parentId: "1" },
+  { id: "3", label: "EMEA", parentId: "2" },
+];
+
+<SearchableTreeDialog
+  nodes={rows}
+  parentIdKey="parentId"
+  getNodeId={(r) => r.id}
+  getNodeLabel={(r) => r.label}
+  onSelect={(r) => console.log(r.id)}
+/>;
+```
+
+### Server-side search
+
+```tsx
+<SearchableTreeDialog
+  nodes={results}
+  getNodeId={(n) => n.id}
+  getNodeLabel={(n) => n.name}
+  getNodeChildren={(n) => n.children}
+  filterClientSide={false}
+  onSearchChange={(query) => fetchNodes(query)}
+  loading={isFetching}
+  searchDebounceMs={300}
+/>
+```
+
+## API Reference
+
+### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `nodes` | `T[]` | — | Tree data. Nested by default; treated as a flat list when `parentIdKey` is set. |
+| `getNodeId` | `(node: T) => string` | — | Returns a stable unique id for a node. |
+| `getNodeLabel` | `(node: T) => ReactNode` | — | Returns a node's display label. |
+| `getNodeChildren` | `(node: T) => T[] \| undefined` | — | Returns a node's children (nested mode). Ignored when `parentIdKey` is set. |
+| `parentIdKey` | `keyof T & string` | — | When set, `nodes` is a FLAT list and the tree is built from this parent-id key. |
+| `value` | `T \| null` | — | Controlled selected node. |
+| `onSelect` | `(node: T) => void` | — | Called when a node is selected. |
+| `getSearchText` | `(node: T) => string` | `String(getNodeLabel(node))` | Plain text used for search matching. |
+| `placeholder` | `string` | — | Trigger placeholder shown until a node is selected. |
+| `searchPlaceholder` | `string` | — | Placeholder for the search input inside the dialog. |
+| `title` | `string` | — | Label shown on the dialog's search field. |
+| `size` | `"XS" \| "S" \| "M"` | `"M"` | Trigger size. |
+| `variant` | `"SystemStyle" \| "PresentationStyle"` | `"PresentationStyle"` | Visual style. `SystemStyle` is reserved for internal library system surfaces. |
+| `icon` | `ReactNode` | — | Leading icon in the trigger. |
+| `theme` | `Themes` | — | `"dark" \| "light" \| "default"`. |
+| `dir` | `string` | — | Text direction. |
+| `className` | `string` | — | Extra classes for the trigger. |
+| `defaultExpanded` | `boolean` | `true` | Expand every node when the dialog opens. |
+| `selectableFolders` | `boolean` | `false` | When true, folder nodes are selectable too; otherwise folders only expand/collapse. |
+| `filterClientSide` | `boolean` | `true` | Filter locally. Set `false` for server-side search. |
+| `onSearchChange` | `(query: string) => void` | — | Debounced as the user types — refetch your data here (server search). |
+| `searchDebounceMs` | `number` | `300` | Debounce for `onSearchChange`. |
+| `loading` | `boolean` | `false` | Whether a fetch is in flight; shows a loading indicator. |
+
+### TypeScript
+
+```typescript
+import { ReactNode } from "react";
+import { Themes } from "@/utils/types";
+
+interface SearchableTreeDialogProps<T> {
+  nodes: T[];
+  getNodeId: (node: T) => string;
+  getNodeLabel: (node: T) => ReactNode;
+  getNodeChildren?: (node: T) => T[] | undefined;
+  parentIdKey?: keyof T & string;
+  value?: T | null;
+  onSelect?: (node: T) => void;
+  getSearchText?: (node: T) => string;
+  placeholder?: string;
+  searchPlaceholder?: string;
+  title?: string;
+  size?: "XS" | "S" | "M";
+  variant?: "SystemStyle" | "PresentationStyle";
+  icon?: ReactNode;
+  theme?: Themes;
+  dir?: string;
+  className?: string;
+  defaultExpanded?: boolean;
+  selectableFolders?: boolean;
+  filterClientSide?: boolean;
+  onSearchChange?: (query: string) => void;
+  searchDebounceMs?: number;
+  loading?: boolean;
+}
+
+export function SearchableTreeDialog<T>(props: SearchableTreeDialogProps<T>): JSX.Element;
+```
+
+## Common Patterns
+
+- **Dialog vs popover:** use `SearchableTreeDialog` for large trees or a focused modal
+  selection; use [SearchableTree](./searchable-tree.md) for an inline popover field.
+- **Nested vs flat data:** provide `getNodeChildren` for nested data, or `parentIdKey` to nest
+  a flat list. Do not use both.
+- **Async search:** set `filterClientSide={false}`, handle `onSearchChange` to fetch, and pass
+  `loading` while the request is in flight.
+
+## Related Components
+
+- [SearchableTree](./searchable-tree.md) — the same tree-select on an inline Popover.
+- [SearchableSelect](./searchable-select.md) — flat searchable single-select combobox.
+- [Dialog](./dialog.md) — the modal surface this component builds on.

package/docs/components/searchable-tree.md

@@ -0,0 +1,200 @@
+---
+title: SearchableTree
+description: Searchable tree-select that opens on focus and filters hierarchical nodes as you type, on a Popover surface, with client or server-side search
+group: Inputs
+keywords: [searchable-tree, tree, tree-select, hierarchy, search, combobox, async, popover]
+---
+
+# SearchableTree
+
+> A searchable tree-select. It renders a field that opens a Popover containing a hierarchical
+> tree of nodes and filters them as you type. Accepts either nested data (via `getNodeChildren`)
+> or a flat list that it nests for you (via `parentIdKey`). Supports local filtering or
+> debounced server-side search, optional folder selection, and controlled selection.
+
+## 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-glare@latest init
+npx torch-glare@latest add SearchableTree
+```
+
+The CLI also copies its internal dependencies: `Button`, `Input`, `Popover`, the
+`useClickOutside` hook, and the `cn`/`types` utils.
+
+## Import
+
+```typescript
+import { SearchableTree } from "@/components/SearchableTree";
+```
+
+## Quick Examples
+
+### Basic Usage (nested data)
+
+```tsx
+import { SearchableTree } from "@/components/SearchableTree";
+
+type Node = { id: string; name: string; children?: Node[] };
+
+const data: Node[] = [
+  {
+    id: "eng",
+    name: "Engineering",
+    children: [
+      { id: "fe", name: "Frontend" },
+      { id: "be", name: "Backend" },
+    ],
+  },
+  { id: "design", name: "Design" },
+];
+
+export function DepartmentPicker() {
+  const [value, setValue] = useState<Node | null>(null);
+
+  return (
+    <SearchableTree
+      nodes={data}
+      getNodeId={(n) => n.id}
+      getNodeLabel={(n) => n.name}
+      getNodeChildren={(n) => n.children}
+      value={value}
+      onSelect={setValue}
+      placeholder="Select a department"
+      title="Departments"
+      size="M"
+    />
+  );
+}
+```
+
+### Flat data (built from a parent id)
+
+```tsx
+type Row = { id: string; label: string; parentId: string | null };
+
+const rows: Row[] = [
+  { id: "1", label: "Company", parentId: null },
+  { id: "2", label: "Sales", parentId: "1" },
+  { id: "3", label: "EMEA", parentId: "2" },
+];
+
+<SearchableTree
+  nodes={rows}
+  parentIdKey="parentId"
+  getNodeId={(r) => r.id}
+  getNodeLabel={(r) => r.label}
+  onSelect={(r) => console.log(r.id)}
+/>;
+```
+
+### Server-side search
+
+```tsx
+<SearchableTree
+  nodes={results}
+  getNodeId={(n) => n.id}
+  getNodeLabel={(n) => n.name}
+  getNodeChildren={(n) => n.children}
+  filterClientSide={false}
+  onSearchChange={(query) => fetchNodes(query)}
+  loading={isFetching}
+  searchDebounceMs={300}
+/>
+```
+
+### Selectable folders
+
+```tsx
+<SearchableTree
+  nodes={data}
+  getNodeId={(n) => n.id}
+  getNodeLabel={(n) => n.name}
+  getNodeChildren={(n) => n.children}
+  selectableFolders
+  onSelect={(n) => console.log(n.id)}
+/>
+```
+
+## API Reference
+
+### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `nodes` | `T[]` | — | Tree data. Nested by default; treated as a flat list when `parentIdKey` is set. |
+| `getNodeId` | `(node: T) => string` | — | Returns a stable unique id for a node. |
+| `getNodeLabel` | `(node: T) => ReactNode` | — | Returns a node's display label. |
+| `getNodeChildren` | `(node: T) => T[] \| undefined` | — | Returns a node's children (nested mode). Ignored when `parentIdKey` is set. |
+| `parentIdKey` | `keyof T & string` | — | When set, `nodes` is a FLAT list and the tree is built from this parent-id key. |
+| `value` | `T \| null` | — | Controlled selected node. |
+| `onSelect` | `(node: T) => void` | — | Called when a node is selected. |
+| `getSearchText` | `(node: T) => string` | `String(getNodeLabel(node))` | Plain text used for search matching. |
+| `placeholder` | `string` | `"Select…"` | Field placeholder shown when nothing is selected. |
+| `title` | `string` | `"Select an item"` | Section heading above the tree rows in the dropdown. |
+| `size` | `"XS" \| "S" \| "M"` | `"M"` | Field size. |
+| `variant` | `"SystemStyle" \| "PresentationStyle"` | `"PresentationStyle"` | Visual style. `SystemStyle` is reserved for internal library system surfaces. |
+| `icon` | `ReactNode` | — | Leading icon in the field. |
+| `theme` | `Themes` | — | `"dark" \| "light" \| "default"`. |
+| `dir` | `string` | — | Text direction. |
+| `className` | `string` | — | Extra classes for the field. |
+| `defaultExpanded` | `boolean` | `true` | Expand every node when the dropdown opens. |
+| `selectableFolders` | `boolean` | `false` | When true, folder nodes are selectable too; otherwise folders only expand/collapse. |
+| `maxBodyHeight` | `number` | `320` | Max height (px) of the scrollable tree body before it scrolls. |
+| `filterClientSide` | `boolean` | `true` | Filter locally. Set `false` for server-side search. |
+| `onSearchChange` | `(query: string) => void` | — | Debounced as the user types — refetch your data here (server search). |
+| `searchDebounceMs` | `number` | `300` | Debounce for `onSearchChange`. |
+| `loading` | `boolean` | `false` | Whether a fetch is in flight; shows a loading indicator. |
+
+### TypeScript
+
+```typescript
+import { ReactNode } from "react";
+import { Themes } from "@/utils/types";
+
+interface SearchableTreeProps<T> {
+  nodes: T[];
+  getNodeId: (node: T) => string;
+  getNodeLabel: (node: T) => ReactNode;
+  getNodeChildren?: (node: T) => T[] | undefined;
+  parentIdKey?: keyof T & string;
+  value?: T | null;
+  onSelect?: (node: T) => void;
+  getSearchText?: (node: T) => string;
+  placeholder?: string;
+  title?: string;
+  size?: "XS" | "S" | "M";
+  variant?: "SystemStyle" | "PresentationStyle";
+  icon?: ReactNode;
+  theme?: Themes;
+  dir?: string;
+  className?: string;
+  defaultExpanded?: boolean;
+  selectableFolders?: boolean;
+  maxBodyHeight?: number;
+  filterClientSide?: boolean;
+  onSearchChange?: (query: string) => void;
+  searchDebounceMs?: number;
+  loading?: boolean;
+}
+
+export function SearchableTree<T>(props: SearchableTreeProps<T>): JSX.Element;
+```
+
+## Common Patterns
+
+- **Nested vs flat data:** provide `getNodeChildren` for already-nested data, or `parentIdKey`
+  to let the component nest a flat list for you. Do not use both.
+- **Async search:** set `filterClientSide={false}` and handle `onSearchChange` to fetch from a
+  backend; pass `loading` while the request is in flight.
+- **Folder selection:** by default only leaf nodes are selectable. Set `selectableFolders` to
+  allow selecting a folder node (clicking any node selects it and closes the dropdown).
+
+## Related Components
+
+- [SearchableTreeDialog](./searchable-tree-dialog.md) — the same tree-select in a modal dialog.
+- [SearchableSelect](./searchable-select.md) — flat searchable single-select combobox.
+- [TreeDropDown](./tree-drop-down.md) — dropdown tree without search.

package/docs/components/section-block.md

@@ -6,7 +6,7 @@ category: layout
 group: Layout & Containers
 tags: [layout, card, section, container, form, group]
 status: stable
-version: 1.1.22
+version: 2.4.0
 dependencies:
   - "class-variance-authority": "^0.7.0"
 ---
@@ -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
-npx torch-glare add SectionBlock
+npx torch-glare@latest init
+npx torch-glare@latest add SectionBlock
 ```
 
+`add` also copies any components, hooks, and utilities that `SectionBlock` depends on.
+
 ## Import
 
-```typescript
-import { SectionBlock, type SectionColor } from "@/components/SectionBlock";
+Import from your project's local path — the alias configured in `glare.json` (e.g. `@/*`):
+
+```tsx
+import { SectionBlock } from "@/components/SectionBlock";
 ```
 
 ## Basic Usage

package/docs/components/select.md

@@ -1,6 +1,6 @@
 ---
 name: Select
-version: 1.1.15
+version: 2.4.0
 status: stable
 category: components/forms
 tags: [form, select, dropdown, accessible, radix-ui]
@@ -17,23 +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 Select
 ```
 
+`add` also copies any components, hooks, and utilities that `Select` depends on.
+
 ## Import
 
-```typescript
-import {
-  Select,
-  SelectTrigger,
-  SelectContent,
-  SelectItem,
-  SelectValue,
-  SelectGroup,
-  SelectLabel,
-  SelectSeparator
-} from 'torch-glare/lib/components/Select'
+Import from your project's local path — the alias configured in `glare.json` (e.g. `@/*`):
+
+```tsx
+import { Select } from "@/components/Select";
 ```
 
 ## Quick Examples
@@ -47,7 +46,7 @@ import {
   SelectContent,
   SelectItem,
   SelectValue
-} from 'torch-glare/lib/components/Select'
+} from '@/components/Select'
 
 function Example() {
   const [value, setValue] = useState('')
@@ -265,6 +264,9 @@ function Uncontrolled() {
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
 | `value` | `string` | - | Item value (required) |
+| `variant` | `'Default' \| 'Warning' \| 'Negative' \| 'SystemStyle'` | `'Default'` | Visual variant |
+| `size` | `'S' \| 'M'` | `'M'` | Item size |
+| `active` | `boolean` | `false` | Renders the item in its selected/active style |
 | `disabled` | `boolean` | `false` | Disable item |
 | `className` | `string` | - | Additional CSS classes |
 | `children` | `React.ReactNode` | - | Item content |
@@ -272,7 +274,7 @@ function Uncontrolled() {
 ### TypeScript
 
 ```typescript
-import type { Themes } from 'torch-glare/lib/utils/types'
+import type { Themes } from '@/utils/types'
 
 // Select component types
 interface SelectProps {
@@ -316,6 +318,9 @@ interface SelectContentProps {
 // Item types
 interface SelectItemProps {
   value: string
+  variant?: 'Default' | 'Warning' | 'Negative' | 'SystemStyle'
+  size?: 'S' | 'M'
+  active?: boolean
   disabled?: boolean
   className?: string
   children: React.ReactNode
@@ -363,8 +368,8 @@ function CountrySelect() {
 ### Form Integration
 
 ```typescript
-import { Form } from 'torch-glare/lib/components/Form'
-import { Label } from 'torch-glare/lib/components/Label'
+import { Form } from '@/components/Form'
+import { Label } from '@/components/Label'
 
 function FormSelect() {
   const [formData, setFormData] = useState({
@@ -464,7 +469,7 @@ function DynamicSelect() {
 
 ```typescript
 import { render, screen, fireEvent } from '@testing-library/react'
-import { Select, SelectTrigger, SelectContent, SelectItem, SelectValue } from 'torch-glare/lib/components/Select'
+import { Select, SelectTrigger, SelectContent, SelectItem, SelectValue } from '@/components/Select'
 
 describe('Select', () => {
   it('opens dropdown on trigger click', () => {

package/docs/components/simple-select.md

@@ -1,6 +1,6 @@
 ---
 name: SimpleSelect
-version: 1.1.15
+version: 2.4.0
 status: stable
 category: components/forms
 tags: [form, select, dropdown, custom, system-style, accessible]
@@ -17,18 +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 SimpleSelect
 ```
 
+`add` also copies any components, hooks, and utilities that `SimpleSelect` depends on.
+
 ## Import
 
-```typescript
-import {
-  SimpleSelectValue,
-  SimpleSelectItem,
-  SimpleSelectDropDown
-} from 'torch-glare/lib/components/SimpleSelect'
+Import from your project's local path — the alias configured in `glare.json` (e.g. `@/*`):
+
+```tsx
+import { SimpleSelect } from "@/components/SimpleSelect";
 ```
 
 ## Quick Examples
@@ -36,7 +40,7 @@ import {
 ### Basic Usage
 
 ```typescript
-import { SimpleSelectValue, SimpleSelectItem } from 'torch-glare/lib/components/SimpleSelect'
+import { SimpleSelectValue, SimpleSelectItem } from '@/components/SimpleSelect'
 
 function Example() {
   const [value, setValue] = useState('option1')
@@ -470,7 +474,7 @@ function DynamicSelect() {
 
 ```typescript
 import { render, screen, fireEvent } from '@testing-library/react'
-import { SimpleSelectValue, SimpleSelectItem } from 'torch-glare/lib/components/SimpleSelect'
+import { SimpleSelectValue, SimpleSelectItem } from '@/components/SimpleSelect'
 
 describe('SimpleSelect', () => {
   it('opens dropdown on click', () => {