torch-glare 2.3.0 → 2.4.1

package/docs/components/searchable-select.md

@@ -11,17 +11,22 @@ keywords: [searchable-select, combobox, select, search, async, infinite-scroll,
 
 ## 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-popover
+npx torch-glare@latest init
+npx torch-glare@latest add SearchableSelect
 ```
 
-SearchableSelect is built on the TORCH `Popover` component (which wraps `@radix-ui/react-popover`) and reuses the `Input`, `Button`, and `DropdownMenu` item styles. All imports come from `@torch-ui/components`.
+`add` also copies any components, hooks, and utilities that `SearchableSelect` depends on.
 
 ## Import
 
-```typescript
-import { SearchableSelect } from '@torch-ui/components'
-import type { SearchableSelectOption } from '@torch-ui/components'
+Import from your project's local path — the alias configured in `glare.json` (e.g. `@/*`):
+
+```tsx
+import { SearchableSelect } from "@/components/SearchableSelect";
 ```
 
 ## Quick Examples
@@ -31,8 +36,8 @@ import type { SearchableSelectOption } from '@torch-ui/components'
 Pass a static `options` array and control the selection with `value` / `onValueChange`. Options may include an `icon`. Filtering happens locally by default.
 
 ```typescript
-import { SearchableSelect } from '@torch-ui/components'
-import type { SearchableSelectOption } from '@torch-ui/components'
+import { SearchableSelect } from "@/components/SearchableSelect";
+import type { SearchableSelectOption } from "@/components/SearchableSelect";
 import { useState } from 'react'
 
 const options: SearchableSelectOption[] = [
@@ -62,8 +67,8 @@ function FrameworkPicker() {
 For large or remote datasets, set `filterClientSide={false}` and drive everything from controlled props: refetch in `onSearchChange` (debounced), append pages in `onLoadMore`, and report `hasMore` / `loading`. Options are rendered as-is — the component does not filter them locally in this mode.
 
 ```typescript
-import { SearchableSelect } from '@torch-ui/components'
-import type { SearchableSelectOption } from '@torch-ui/components'
+import { SearchableSelect } from "@/components/SearchableSelect";
+import type { SearchableSelectOption } from "@/components/SearchableSelect";
 import { useEffect, useState } from 'react'
 
 const PAGE_SIZE = 20
@@ -125,7 +130,7 @@ function UserPicker() {
 The list shows up to `maxVisibleItems` rows (default `5`) before it scrolls internally.
 
 ```typescript
-import { SearchableSelect } from '@torch-ui/components'
+import { SearchableSelect } from "@/components/SearchableSelect";
 
 function CompactList({ options, value, onValueChange }) {
   return (
@@ -144,7 +149,7 @@ function CompactList({ options, value, onValueChange }) {
 Pass `dir="rtl"` to lay out the input, chevron, and dropdown right-to-left.
 
 ```typescript
-import { SearchableSelect } from '@torch-ui/components'
+import { SearchableSelect } from "@/components/SearchableSelect";
 
 function ArabicPicker({ options, value, onValueChange }) {
   return (
@@ -236,8 +241,8 @@ export function SearchableSelect(props: SearchableSelectProps): JSX.Element
 React Query's `useInfiniteQuery` maps cleanly onto the controlled async props. Track the debounced query in state, flatten pages into `options`, and wire `fetchNextPage`/`hasNextPage`/`isFetching` to `onLoadMore`/`hasMore`/`loading`.
 
 ```typescript
-import { SearchableSelect } from '@torch-ui/components'
-import type { SearchableSelectOption } from '@torch-ui/components'
+import { SearchableSelect } from "@/components/SearchableSelect";
+import type { SearchableSelectOption } from "@/components/SearchableSelect";
 import { useInfiniteQuery } from '@tanstack/react-query'
 import { useMemo, useState } from 'react'
 
@@ -283,7 +288,7 @@ function UserPicker() {
 The same shape works with SWR's `useSWRInfinite` — increment `size` in `onLoadMore`, flatten the page array into `options`, and derive `hasMore` from the last page length.
 
 ```typescript
-import { SearchableSelect } from '@torch-ui/components'
+import { SearchableSelect } from "@/components/SearchableSelect";
 import useSWRInfinite from 'swr/infinite'
 import { useState } from 'react'
 

package/docs/components/searchable-table.md

@@ -1,27 +1,32 @@
 ---
 title: SearchableTable
-description: A searchable combobox whose dropdown renders a real Table, with single-select, client- or server-side search, and infinite-scroll pagination
+description: A field that opens a modal dialog to pick a row from a real Table, with single-select, client- or server-side search, and infinite-scroll pagination
 group: Inputs
-keywords: [searchable-table, combobox, table, search, async, infinite-scroll, pagination, select]
+keywords: [searchable-table, dialog, table, search, async, infinite-scroll, pagination, select, picker]
 ---
 
 # SearchableTable
 
-> A searchable combobox that renders its options as a real, multi-column `Table` inside a `Popover`. Type to filter rows (client-side) or refetch them from a backend (server-side), click a row to single-select it, and scroll to the bottom to lazy-load more pages. Generic over your row type `T`.
+> A field that opens a modal `Dialog` to pick a row from a real, multi-column `Table`. The trigger shows a placeholder until something is selected, then the selected row's label. Click it to open the dialog (a search input + the data table); type to filter rows (client-side) or refetch them from a backend (server-side), click a row to single-select it and close the dialog, and scroll to the bottom to lazy-load more pages. Generic over your row type `T`.
 
 ## Installation
 
-`SearchableTable` is part of the TORCH Glare component library. It composes the [Popover](./popover.md) (built on Radix Popover) and the [Table](./table.md) component internally, so both must be available — they ship with the library.
+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-ui/components @radix-ui/react-popover
+npx torch-glare@latest init
+npx torch-glare@latest add SearchableTable
 ```
 
+`add` also copies any components, hooks, and utilities that `SearchableTable` depends on.
+
 ## Import
 
-```typescript
-import { SearchableTable } from '@torch-ui/components'
-import type { SearchableTableColumn } from '@torch-ui/components'
+Import from your project's local path — the alias configured in `glare.json` (e.g. `@/*`):
+
+```tsx
+import { SearchableTable } from "@/components/SearchableTable";
 ```
 
 ## Quick Examples
@@ -31,8 +36,8 @@ import type { SearchableTableColumn } from '@torch-ui/components'
 Provide a `columns` config and a `rows` array. Single-select is controlled via `value` / `onSelect`. Use `getLabel` to control the text shown in the input after selection, and `getRowId` to give each row a stable key.
 
 ```typescript
-import { SearchableTable } from '@torch-ui/components'
-import type { SearchableTableColumn } from '@torch-ui/components'
+import { SearchableTable } from "@/components/SearchableTable";
+import type { SearchableTableColumn } from "@/components/SearchableTable";
 import { useState } from 'react'
 
 type User = { id: string; name: string; role: string; email: string }
@@ -60,13 +65,15 @@ function Example() {
       onSelect={setSelected}
       getLabel={(row) => row.name}
       getRowId={(row) => row.id}
-      placeholder="Search users…"
+      icon={<i className="ri-user-line" />}
+      placeholder="Select a user…"
+      title="Select a user"
     />
   )
 }
 ```
 
-The input opens its dropdown on focus. As you type, rows are filtered locally by every column key. Clicking a row selects it (single-select), closes the dropdown, and shows `getLabel(row)` in the input.
+Clicking the field opens a modal dialog with a search input and the data table. As you type, rows are filtered locally by every column key. Clicking a row selects it (single-select), closes the dialog, and shows `getLabel(row)` on the trigger. Use `placeholder` for the trigger text, `searchPlaceholder` for the in-dialog search input, and `title` for the dialog's search-field label (also the accessible dialog title).
 
 ### Custom cell rendering
 
@@ -95,8 +102,8 @@ const columns: SearchableTableColumn<User>[] = [
 Set `filterClientSide={false}` and treat `rows` as already-filtered server data. `onSearchChange` fires (debounced by `searchDebounceMs`, default 300ms) whenever the query settles — refetch there. As the list nears the bottom, `onLoadMore` fires while `hasMore && !loading`; a loading row renders whenever `loading` is true.
 
 ```typescript
-import { SearchableTable } from '@torch-ui/components'
-import type { SearchableTableColumn } from '@torch-ui/components'
+import { SearchableTable } from "@/components/SearchableTable";
+import type { SearchableTableColumn } from "@/components/SearchableTable";
 import { useEffect, useState } from 'react'
 
 type User = { id: string; name: string; role: string; email: string }
@@ -159,26 +166,35 @@ function AsyncExample() {
       hasMore={hasMore}
       loading={loading}
       onLoadMore={loadMore}
-      placeholder="Search users…"
+      icon={<i className="ri-user-line" />}
+      placeholder="Select a user…"
+      title="Select a user"
+      searchPlaceholder="Search users… (scroll to load more)"
     />
   )
 }
 ```
 
-### Capping the visible height
+### Dialog labels (trigger, title, search)
 
-`maxVisibleRows` (default `6`) caps how many rows are visible before the dropdown scrolls vertically. The remaining rows stay reachable via scroll, which is also what drives infinite-scroll loading.
+Three props control the dialog's text. `placeholder` is the trigger text shown until a row is selected; `title` labels the dialog's search field (and is the accessible dialog title); `searchPlaceholder` is the placeholder of the in-dialog search input.
 
 ```typescript
 <SearchableTable<User>
   columns={columns}
   rows={users}
+  value={selected}
   onSelect={setSelected}
   getRowId={(row) => row.id}
-  maxVisibleRows={4}
+  icon={<i className="ri-user-line" />}
+  placeholder="Select a user…"
+  title="Select a user"
+  searchPlaceholder="Search by name or role…"
 />
 ```
 
+The data table inside the dialog scrolls vertically once it exceeds `~55vh`; the remaining rows stay reachable via scroll, which is also what drives infinite-scroll loading.
+
 ## API Reference
 
 ### SearchableTable&lt;T&gt;
@@ -188,24 +204,25 @@ function AsyncExample() {
 | `columns` | `SearchableTableColumn<T>[]` | Required | Column config — header, the row key to read, and an optional cell renderer. |
 | `rows` | `T[]` | Required | The data rows. In server mode these are rendered as-is (already filtered upstream). |
 | `value` | `T \| null` | - | Controlled selected row. The matching row is highlighted in the table. |
-| `onSelect` | `(row: T) => void` | - | Called when a row is clicked. The dropdown closes and the input shows the row's label. |
-| `getLabel` | `(row: T) => string` | First column's value | Text shown in the input after selection. |
+| `onSelect` | `(row: T) => void` | - | Called when a row is clicked. The dialog closes and the trigger shows the row's label. |
+| `getLabel` | `(row: T) => string` | First column's value | Text shown on the trigger after selection. |
 | `getRowId` | `(row: T) => string` | `JSON.stringify(row)` | Stable id/key per row, used for keys and selection matching. |
 | `searchKeys` | `(keyof T & string)[]` | Every column `key` | Which fields client-side search matches against. |
-| `placeholder` | `string` | `'Search…'` | Input placeholder text. |
-| `size` | `'XS' \| 'S' \| 'M'` | `'M'` | Input size. (`XS` maps the underlying Group to `S` with a tighter input height.) |
-| `variant` | `'PresentationStyle'` | `'PresentationStyle'` | Visual style of the input and dropdown surface. |
-| `icon` | `ReactNode` | - | Optional leading icon rendered inside the input. |
+| `placeholder` | `string` | `'Select…'` | Trigger placeholder shown until a row is selected. |
+| `searchPlaceholder` | `string` | `'Search…'` | Placeholder for the search input inside the dialog. |
+| `title` | `string` | `'Select an item'` | Label shown on the dialog's search field (also used as the accessible dialog title). |
+| `size` | `'XS' \| 'S' \| 'M'` | `'M'` | Trigger size. (`XS` maps the underlying Group to `S` with a tighter input height.) |
+| `variant` | `'PresentationStyle'` | `'PresentationStyle'` | Visual style of the trigger field. |
+| `icon` | `ReactNode` | - | Optional leading icon rendered inside the trigger. |
 | `theme` | `'dark' \| 'light' \| 'default'` | - | Theme variant, applied via `data-theme`. |
-| `dir` | `string` | - | Text direction (e.g. `'rtl'`), applied to the input group and dropdown. |
-| `className` | `string` | - | Additional classes merged onto the input group. |
+| `dir` | `string` | - | Text direction (e.g. `'rtl'`), applied to the trigger and dialog. |
+| `className` | `string` | - | Additional classes merged onto the trigger group. |
 | `filterClientSide` | `boolean` | `true` | When `true`, filter `rows` locally by `searchKeys`. Set `false` for server-side search. |
 | `onSearchChange` | `(query: string) => void` | - | Debounced query callback — refetch your data here in server mode. |
 | `searchDebounceMs` | `number` | `300` | Debounce delay (ms) for `onSearchChange`. |
 | `hasMore` | `boolean` | `false` | Whether more pages are available; gates the infinite-scroll loader. |
 | `loading` | `boolean` | `false` | Whether a fetch is in flight; renders a loading row and blocks `onLoadMore`. |
 | `onLoadMore` | `() => void` | - | Called when the list nears the bottom and `hasMore && !loading`. |
-| `maxVisibleRows` | `number` | `6` | Max rows visible before the list scrolls vertically. |
 
 ### SearchableTableColumn&lt;T&gt;
 
@@ -232,7 +249,7 @@ export interface SearchableTableColumn<T> {
 ### Component signature
 
 ```typescript
-import { Themes } from '@torch-ui/components'
+import { Themes } from "@/utils/types";
 
 interface SearchableTableProps<T> {
   columns: SearchableTableColumn<T>[]
@@ -242,7 +259,9 @@ interface SearchableTableProps<T> {
   getLabel?: (row: T) => string
   getRowId?: (row: T) => string
   searchKeys?: (keyof T & string)[]
-  placeholder?: string
+  placeholder?: string       // trigger text until selection (default 'Select…')
+  searchPlaceholder?: string // in-dialog search input (default 'Search…')
+  title?: string             // dialog search-field label / a11y title (default 'Select an item')
   size?: 'XS' | 'S' | 'M'
   variant?: 'PresentationStyle'
   icon?: React.ReactNode
@@ -256,7 +275,6 @@ interface SearchableTableProps<T> {
   hasMore?: boolean
   loading?: boolean
   onLoadMore?: () => void
-  maxVisibleRows?: number
 }
 
 // Generic function component, constrained so rows are object-shaped:
@@ -274,8 +292,8 @@ Always pass the type argument explicitly (`<SearchableTable<User> … />`) so `c
 Wire pagination through `useInfiniteQuery`, flatten the pages into `rows`, and map the query's state onto `hasMore` / `loading` / `onLoadMore`.
 
 ```typescript
-import { SearchableTable } from '@torch-ui/components'
-import type { SearchableTableColumn } from '@torch-ui/components'
+import { SearchableTable } from "@/components/SearchableTable";
+import type { SearchableTableColumn } from "@/components/SearchableTable";
 import { useInfiniteQuery } from '@tanstack/react-query'
 import { useState } from 'react'
 
@@ -341,7 +359,7 @@ function UserPicker() {
 ### SWR — `useSWRInfinite`
 
 ```typescript
-import { SearchableTable } from '@torch-ui/components'
+import { SearchableTable } from "@/components/SearchableTable";
 import useSWRInfinite from 'swr/infinite'
 import { useState } from 'react'
 
@@ -395,25 +413,26 @@ function toUser(api: ApiUser): User {
 
 ## Accessibility
 
-- The trigger is a standard text `<input>`, so it is focusable and typeable by keyboard. Focusing it opens the dropdown and starts a fresh search.
-- The chevron is a boxed icon button with `aria-label` toggling between `"Open"` and `"Close"`; it is `tabIndex={-1}` so keyboard focus stays on the input, and it uses `onMouseDown` with `preventDefault` to avoid the input blur/focus race.
-- Clicking outside the input group or the dropdown closes it (handled via `useClickOutside`).
-- The dropdown surface does not steal focus on open (`onOpenAutoFocus` is prevented), keeping the caret in the input while results update.
-- Provide a descriptive `placeholder` and a meaningful `getLabel` so screen-reader users hear a clear value after selection. Prefer human-readable headers in `columns`.
+- The trigger is a focusable group with `role="button"` and `tabIndex={0}`; activating it opens a modal dialog (Radix Dialog), which traps focus and closes on `Esc` or outside click.
+- On open, focus moves to the in-dialog search input (`onOpenAutoFocus` is intercepted to focus the search field rather than the first row), so users can type to filter immediately.
+- The dialog always renders a `DialogTitle` (visually hidden, sourced from `title`) so the modal has an accessible name even though the heading is not shown.
+- Clicking a row selects it and closes the dialog; the selected row is marked with the Table's `state="selected"`.
+- Provide a descriptive `placeholder`, a meaningful `title`, and a `getLabel` so screen-reader users hear a clear value after selection. Prefer human-readable headers in `columns`.
 
 ## Best Practices
 
 1. **Always supply `getRowId`.** The default key is `JSON.stringify(row)`, which is slow and brittle for large or nested rows. A stable id keeps keys and selection matching cheap.
-2. **Set `getLabel` for the selected display.** Otherwise the input shows the first column's raw value, which may not be the most descriptive field.
+2. **Set `getLabel` for the selected display.** Otherwise the trigger shows the first column's raw value, which may not be the most descriptive field.
 3. **Pick the right search mode.** Keep `filterClientSide` (default) for small, in-memory datasets. Switch to `filterClientSide={false}` + `onSearchChange` for backend-driven search so you never filter a partial page.
 4. **Gate pagination correctly.** `onLoadMore` only fires while `hasMore && !loading` — keep `loading` accurate so a single scroll doesn't trigger duplicate fetches, and flip `hasMore` to `false` on the last page.
-5. **The table scrolls in both directions.** Columns keep their natural width, so wide tables scroll horizontally inside the dropdown, while `maxVisibleRows` caps the vertical height and the rest scrolls vertically (which is what drives infinite scroll). Keep column count and content reasonable so horizontal scroll stays usable.
+5. **The table scrolls in both directions.** Columns keep their natural width, so wide tables scroll horizontally inside the dialog, while the table caps its vertical height (~`55vh`) and the rest scrolls vertically (which is what drives infinite scroll). Keep column count and content reasonable so horizontal scroll stays usable.
 6. **Tune `searchDebounceMs` to your backend.** The 300ms default suits most APIs; raise it for slow or rate-limited endpoints.
 7. **Match `searchKeys` to visible columns.** In client mode, search defaults to every column key — narrow `searchKeys` if some columns hold non-searchable data (ids, formatted dates).
 
 ## Related Components
 
 - [SearchableSelect](./searchable-select.md) - Single-column searchable combobox
-- [Table](./table.md) - The table primitive rendered inside the dropdown
+- [Table](./table.md) - The table primitive rendered inside the dialog
+- [Dialog](./dialog.md) - The modal surface the picker opens in
 - [DataTable](./data-table.md) - Full-featured data grid for page-level tables
 - [Select](./select.md) - Standard form select field

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.