torch-glare 2.5.5 → 2.6.0

package/docs/components/searchable-table.md

@@ -1,438 +0,0 @@
----
-title: SearchableTable
-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, dialog, table, search, async, infinite-scroll, pagination, select, picker]
----
-
-# SearchableTable
-
-> 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
-
-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 SearchableTable
-```
-
-`add` also copies any components, hooks, and utilities that `SearchableTable` depends on.
-
-## Import
-
-Import from your project's local path — the alias configured in `glare.json` (e.g. `@/*`):
-
-```tsx
-import { SearchableTable } from "@/components/SearchableTable";
-```
-
-## Quick Examples
-
-### Basic (static rows)
-
-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 "@/components/SearchableTable";
-import type { SearchableTableColumn } from "@/components/SearchableTable";
-import { useState } from 'react'
-
-type User = { id: string; name: string; role: string; email: string }
-
-const users: User[] = [
-  { id: '1', name: 'Ada Lovelace', role: 'Engineer', email: 'ada@torch.dev' },
-  { id: '2', name: 'Alan Turing', role: 'Researcher', email: 'alan@torch.dev' },
-  { id: '3', name: 'Grace Hopper', role: 'Admiral', email: 'grace@torch.dev' },
-]
-
-const columns: SearchableTableColumn<User>[] = [
-  { key: 'name', header: 'Name' },
-  { key: 'role', header: 'Role' },
-  { key: 'email', header: 'Email' },
-]
-
-function Example() {
-  const [selected, setSelected] = useState<User | null>(null)
-
-  return (
-    <SearchableTable<User>
-      columns={columns}
-      rows={users}
-      value={selected}
-      onSelect={setSelected}
-      getLabel={(row) => row.name}
-      getRowId={(row) => row.id}
-      icon={<i className="ri-user-line" />}
-      placeholder="Select a user…"
-      title="Select a user"
-    />
-  )
-}
-```
-
-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
-
-Use a column's `render` to control how a cell is displayed. When omitted, the cell falls back to `String(row[key])`.
-
-```typescript
-const columns: SearchableTableColumn<User>[] = [
-  { key: 'name', header: 'Name' },
-  {
-    key: 'role',
-    header: 'Role',
-    render: (row) => (
-      <span className="rounded bg-white-alpha-20 px-2 py-0.5">{row.role}</span>
-    ),
-  },
-  {
-    key: 'email',
-    header: 'Contact',
-    render: (row) => <a href={`mailto:${row.email}`}>{row.email}</a>,
-  },
-]
-```
-
-### Async server search + infinite scroll
-
-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 "@/components/SearchableTable";
-import type { SearchableTableColumn } from "@/components/SearchableTable";
-import { useEffect, useState } from 'react'
-
-type User = { id: string; name: string; role: string; email: string }
-
-const columns: SearchableTableColumn<User>[] = [
-  { key: 'name', header: 'Name' },
-  { key: 'role', header: 'Role' },
-  { key: 'email', header: 'Email' },
-]
-
-async function fetchUsers(query: string, page: number) {
-  const res = await fetch(`/api/users?q=${encodeURIComponent(query)}&page=${page}`)
-  return res.json() as Promise<{ items: User[]; hasMore: boolean }>
-}
-
-function AsyncExample() {
-  const [rows, setRows] = useState<User[]>([])
-  const [query, setQuery] = useState('')
-  const [page, setPage] = useState(1)
-  const [hasMore, setHasMore] = useState(true)
-  const [loading, setLoading] = useState(false)
-  const [selected, setSelected] = useState<User | null>(null)
-
-  // Refetch from page 1 whenever the debounced query changes.
-  useEffect(() => {
-    let cancelled = false
-    setLoading(true)
-    fetchUsers(query, 1).then(({ items, hasMore }) => {
-      if (cancelled) return
-      setRows(items)
-      setHasMore(hasMore)
-      setPage(1)
-      setLoading(false)
-    })
-    return () => {
-      cancelled = true
-    }
-  }, [query])
-
-  const loadMore = async () => {
-    const next = page + 1
-    setLoading(true)
-    const { items, hasMore } = await fetchUsers(query, next)
-    setRows((prev) => [...prev, ...items])
-    setHasMore(hasMore)
-    setPage(next)
-    setLoading(false)
-  }
-
-  return (
-    <SearchableTable<User>
-      columns={columns}
-      rows={rows}
-      value={selected}
-      onSelect={setSelected}
-      getRowId={(row) => row.id}
-      getLabel={(row) => row.name}
-      filterClientSide={false}
-      onSearchChange={setQuery}
-      hasMore={hasMore}
-      loading={loading}
-      onLoadMore={loadMore}
-      icon={<i className="ri-user-line" />}
-      placeholder="Select a user…"
-      title="Select a user"
-      searchPlaceholder="Search users… (scroll to load more)"
-    />
-  )
-}
-```
-
-### Dialog labels (trigger, title, search)
-
-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}
-  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;
-
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `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 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` | `'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 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`. |
-
-### SearchableTableColumn&lt;T&gt;
-
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `key` | `keyof T & string` | Required | Property on the row used for default rendering and search. |
-| `header` | `ReactNode` | Required | Column header content. |
-| `render` | `(row: T) => ReactNode` | `String(row[key])` | Custom cell renderer. |
-
-## TypeScript
-
-### SearchableTableColumn
-
-```typescript
-export interface SearchableTableColumn<T> {
-  /** Property on the row used for default rendering and search. */
-  key: keyof T & string
-  header: React.ReactNode
-  /** Custom cell renderer; defaults to String(row[key]). */
-  render?: (row: T) => React.ReactNode
-}
-```
-
-### Component signature
-
-```typescript
-import { Themes } from "@/utils/types";
-
-interface SearchableTableProps<T> {
-  columns: SearchableTableColumn<T>[]
-  rows: T[]
-  value?: T | null
-  onSelect?: (row: T) => void
-  getLabel?: (row: T) => string
-  getRowId?: (row: T) => string
-  searchKeys?: (keyof T & 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
-  theme?: Themes
-  dir?: string
-  className?: string
-  // Async / backend pagination
-  filterClientSide?: boolean
-  onSearchChange?: (query: string) => void
-  searchDebounceMs?: number
-  hasMore?: boolean
-  loading?: boolean
-  onLoadMore?: () => void
-}
-
-// Generic function component, constrained so rows are object-shaped:
-export function SearchableTable<T extends Record<string, unknown>>(
-  props: SearchableTableProps<T>
-): JSX.Element
-```
-
-Always pass the type argument explicitly (`<SearchableTable<User> … />`) so `columns`, `value`, and the callbacks are fully type-checked against your row shape.
-
-## Common Patterns
-
-### React Query — `useInfiniteQuery`
-
-Wire pagination through `useInfiniteQuery`, flatten the pages into `rows`, and map the query's state onto `hasMore` / `loading` / `onLoadMore`.
-
-```typescript
-import { SearchableTable } from "@/components/SearchableTable";
-import type { SearchableTableColumn } from "@/components/SearchableTable";
-import { useInfiniteQuery } from '@tanstack/react-query'
-import { useState } from 'react'
-
-type User = { id: string; name: string; role: string; email: string }
-
-const columns: SearchableTableColumn<User>[] = [
-  { key: 'name', header: 'Name' },
-  { key: 'role', header: 'Role' },
-  { key: 'email', header: 'Email' },
-]
-
-function UserPicker() {
-  const [query, setQuery] = useState('')
-  const [selected, setSelected] = useState<User | null>(null)
-
-  const {
-    data,
-    fetchNextPage,
-    hasNextPage,
-    isFetching,
-  } = useInfiniteQuery({
-    queryKey: ['users', query],
-    queryFn: async ({ pageParam = 1 }) => {
-      const res = await fetch(`/api/users?q=${query}&page=${pageParam}`)
-      // API row -> T mapping happens here.
-      const json = await res.json()
-      return {
-        items: json.results.map(
-          (r: any): User => ({
-            id: String(r.user_id),
-            name: r.full_name,
-            role: r.role_title,
-            email: r.email_address,
-          })
-        ),
-        nextPage: json.has_more ? pageParam + 1 : undefined,
-      }
-    },
-    initialPageParam: 1,
-    getNextPageParam: (last) => last.nextPage,
-  })
-
-  const rows = data?.pages.flatMap((p) => p.items) ?? []
-
-  return (
-    <SearchableTable<User>
-      columns={columns}
-      rows={rows}
-      value={selected}
-      onSelect={setSelected}
-      getRowId={(row) => row.id}
-      getLabel={(row) => row.name}
-      filterClientSide={false}
-      onSearchChange={setQuery}
-      hasMore={hasNextPage}
-      loading={isFetching}
-      onLoadMore={() => fetchNextPage()}
-    />
-  )
-}
-```
-
-### SWR — `useSWRInfinite`
-
-```typescript
-import { SearchableTable } from "@/components/SearchableTable";
-import useSWRInfinite from 'swr/infinite'
-import { useState } from 'react'
-
-const PAGE_SIZE = 20
-
-function UserPicker() {
-  const [query, setQuery] = useState('')
-  const [selected, setSelected] = useState<User | null>(null)
-
-  const getKey = (index: number, prev: { items: User[] } | null) => {
-    if (prev && prev.items.length < PAGE_SIZE) return null // reached the end
-    return `/api/users?q=${query}&page=${index + 1}`
-  }
-
-  const { data, size, setSize, isValidating } = useSWRInfinite(getKey, fetcher)
-
-  const rows = data?.flatMap((p) => p.items) ?? []
-  const hasMore = !!data && data[data.length - 1]?.items.length === PAGE_SIZE
-
-  return (
-    <SearchableTable<User>
-      columns={columns}
-      rows={rows}
-      value={selected}
-      onSelect={setSelected}
-      getRowId={(row) => row.id}
-      filterClientSide={false}
-      onSearchChange={setQuery}
-      hasMore={hasMore}
-      loading={isValidating}
-      onLoadMore={() => setSize(size + 1)}
-    />
-  )
-}
-```
-
-### Mapping API rows to `T`
-
-Normalize the backend shape into your row type at the fetch boundary so that `columns`, `getLabel`, `getRowId`, and `searchKeys` all operate on consistent, typed fields:
-
-```typescript
-function toUser(api: ApiUser): User {
-  return {
-    id: String(api.user_id),
-    name: `${api.first_name} ${api.last_name}`,
-    role: api.role ?? '—',
-    email: api.email,
-  }
-}
-```
-
-## Accessibility
-
-- 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 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 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 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

@@ -1,190 +0,0 @@
----
-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.