torch-glare 2.1.7 → 2.2.1

package/docs/components/dropdown-menu.md

@@ -1,13 +1,13 @@
 ---
 title: DropdownMenu
-description: Comprehensive dropdown menu component with rich features including sub-menus, checkboxes, radio groups, and keyboard navigation
+description: Comprehensive dropdown menu component with rich features including sub-menus, checkboxes, radio groups, auto-grouping, and keyboard navigation
 group: Overlays & Dialogs
-keywords: [dropdown-menu, menu, context-menu, radix-ui, submenu, checkbox]
+keywords: [dropdown-menu, menu, radix-ui, submenu, checkbox, radio, auto-group]
 ---
 
 # DropdownMenu
 
-> A feature-rich dropdown menu component with support for nested submenus, checkbox items, radio groups, separators, and keyboard shortcuts. Perfect for application menus, context menus, and complex action lists.
+> A feature-rich dropdown menu component with support for nested submenus, checkbox items, radio groups, auto-grouped boxed sections, and keyboard shortcuts. Perfect for application menus and complex action lists. For right-click menus, see [ContextMenu](./context-menu.md).
 
 ## Installation
 
@@ -27,15 +27,17 @@ import {
   DropdownMenuRadioGroup,
   DropdownMenuRadioItem,
   DropdownMenuLabel,
-  DropdownMenuSeparator,
   DropdownMenuShortcut,
   DropdownMenuSub,
   DropdownMenuSubTrigger,
   DropdownMenuSubContent,
   DropdownMenuGroup,
+  DropdownMenuPortal,
 } from '@torch-ui/components'
 ```
 
+> **Auto-grouping:** Loose items placed directly in `DropdownMenuContent` (or `DropdownMenuSubContent`) are automatically wrapped in a boxed group, so they render inside a rounded container without you writing `DropdownMenuGroup` yourself. A `DropdownMenuLabel`, an explicit `DropdownMenuGroup`, or a `DropdownMenuRadioGroup` acts as a boundary that starts a new box. Disable this with `autoGroup={false}` on the content. (There is no `DropdownMenuSeparator` — separation comes from labels and the boxed groups.)
+
 ## Quick Examples
 
 ### Basic Menu
@@ -122,10 +124,12 @@ function ShortcutMenu() {
 }
 ```
 
-### With Labels and Separators
+### With Labels and Grouping
+
+Labels act as section boundaries. The loose items between labels are automatically wrapped in boxed groups — no separator component needed.
 
 ```typescript
-import { DropdownMenu, DropdownMenuTrigger, DropdownMenuContent, DropdownMenuItem, DropdownMenuLabel, DropdownMenuSeparator } from '@torch-ui/components'
+import { DropdownMenu, DropdownMenuTrigger, DropdownMenuContent, DropdownMenuItem, DropdownMenuLabel } from '@torch-ui/components'
 
 function OrganizedMenu() {
   return (
@@ -138,14 +142,10 @@ function OrganizedMenu() {
         <DropdownMenuItem>Profile</DropdownMenuItem>
         <DropdownMenuItem>Billing</DropdownMenuItem>
 
-        <DropdownMenuSeparator />
-
         <DropdownMenuLabel>Settings</DropdownMenuLabel>
         <DropdownMenuItem>Preferences</DropdownMenuItem>
         <DropdownMenuItem>Keyboard Shortcuts</DropdownMenuItem>
 
-        <DropdownMenuSeparator />
-
         <DropdownMenuItem variant="Negative">Logout</DropdownMenuItem>
       </DropdownMenuContent>
     </DropdownMenu>
@@ -155,8 +155,10 @@ function OrganizedMenu() {
 
 ### With Checkboxes
 
+Checkbox and radio items keep the menu **open** when toggled (the built-in `onSelect` calls `preventDefault`), so users can change several options without the menu closing each time.
+
 ```typescript
-import { DropdownMenu, DropdownMenuTrigger, DropdownMenuContent, DropdownMenuCheckboxItem, DropdownMenuSeparator } from '@torch-ui/components'
+import { DropdownMenu, DropdownMenuTrigger, DropdownMenuContent, DropdownMenuCheckboxItem } from '@torch-ui/components'
 import { useState } from 'react'
 
 function CheckboxMenu() {
@@ -274,47 +276,25 @@ function DisabledMenu() {
 }
 ```
 
-### SystemStyle Variant
+### Right-click Menu
 
-```typescript
-import { DropdownMenu, DropdownMenuTrigger, DropdownMenuContent, DropdownMenuItem } from '@torch-ui/components'
-
-function SystemMenu() {
-  return (
-    <DropdownMenu>
-      <DropdownMenuTrigger asChild>
-        <button>System</button>
-      </DropdownMenuTrigger>
-      <DropdownMenuContent variant="SystemStyle">
-        <DropdownMenuItem variant="SystemStyle">Settings</DropdownMenuItem>
-        <DropdownMenuItem variant="SystemStyle">About</DropdownMenuItem>
-        <DropdownMenuItem variant="SystemStyle">Help</DropdownMenuItem>
-      </DropdownMenuContent>
-    </DropdownMenu>
-  )
-}
-```
-
-### Context Menu Pattern
+For a true right-click (context) menu, use the dedicated [ContextMenu](./context-menu.md) component instead of DropdownMenu — it opens at the pointer on right-click / long-press.
 
 ```typescript
-import { DropdownMenu, DropdownMenuTrigger, DropdownMenuContent, DropdownMenuItem, DropdownMenuSeparator } from '@torch-ui/components'
+import { ContextMenu, ContextMenuTrigger, ContextMenuContent, ContextMenuItem } from '@torch-ui/components'
 
-function ContextMenu({ x, y }: { x: number; y: number }) {
+function Example() {
   return (
-    <DropdownMenu>
-      <DropdownMenuTrigger asChild>
-        <div onContextMenu={(e) => e.preventDefault()}>
-          Right-click me
-        </div>
-      </DropdownMenuTrigger>
-      <DropdownMenuContent>
-        <DropdownMenuItem>View</DropdownMenuItem>
-        <DropdownMenuItem>Edit</DropdownMenuItem>
-        <DropdownMenuSeparator />
-        <DropdownMenuItem>Properties</DropdownMenuItem>
-      </DropdownMenuContent>
-    </DropdownMenu>
+    <ContextMenu>
+      <ContextMenuTrigger className="rounded-md border border-dashed p-8">
+        Right-click here
+      </ContextMenuTrigger>
+      <ContextMenuContent>
+        <ContextMenuItem>View</ContextMenuItem>
+        <ContextMenuItem>Edit</ContextMenuItem>
+        <ContextMenuItem variant="Negative">Delete</ContextMenuItem>
+      </ContextMenuContent>
+    </ContextMenu>
   )
 }
 ```
@@ -340,18 +320,21 @@ function ContextMenu({ x, y }: { x: number; y: number }) {
 
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
-| `variant` | `'SystemStyle' \| 'PresentationStyle'` | `'PresentationStyle'` | Visual style variant |
+| `variant` | `'PresentationStyle'` | `'PresentationStyle'` | Visual style variant |
 | `theme` | `'dark' \| 'light' \| 'default'` | - | Theme variant |
 | `className` | `string` | - | Additional CSS classes |
 | `sideOffset` | `number` | `4` | Distance from trigger |
-| `align` | `'start' \| 'center' \| 'end'` | `'start'` | Alignment |
+| `collisionPadding` | `number` | `8` | Gap kept from viewport edges when flipping/shifting |
+| `align` | `'start' \| 'center' \| 'end'` | `'center'` | Alignment (inherited from Radix) |
+| `autoGroup` | `boolean` | `true` | Auto-wrap loose items in boxed groups |
 
 ### DropdownMenuItem
 
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
-| `variant` | `'Default' \| 'Warning' \| 'Negative' \| 'SystemStyle'` | `'Default'` | Item style variant |
+| `variant` | `'Default' \| 'info' \| 'Negative'` | `'Default'` | Item style variant |
 | `size` | `'S' \| 'M'` | `'M'` | Item size |
+| `inset` | `boolean` | `false` | Add left padding to align with items that have icons |
 | `disabled` | `boolean` | `false` | Disabled state |
 | `active` | `boolean` | `false` | Active state |
 | `onSelect` | `(event) => void` | - | Select handler |
@@ -362,7 +345,8 @@ function ContextMenu({ x, y }: { x: number; y: number }) {
 |------|------|---------|-------------|
 | `checked` | `boolean \| 'indeterminate'` | `false` | Checked state |
 | `onCheckedChange` | `(checked: boolean) => void` | - | Change handler |
-| `variant` | `'Default' \| 'Warning' \| 'Negative' \| 'SystemStyle'` | `'Default'` | Style variant |
+| `variant` | `'Default' \| 'info' \| 'Negative'` | `'Default'` | Style variant |
+| `size` | `'S' \| 'M'` | `'M'` | Item size |
 
 ### DropdownMenuRadioGroup
 
@@ -376,18 +360,38 @@ function ContextMenu({ x, y }: { x: number; y: number }) {
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
 | `value` | `string` | Required | Radio option value |
-| `variant` | `'Default' \| 'Warning' \| 'Negative' \| 'SystemStyle'` | `'Default'` | Style variant |
+| `variant` | `'Default' \| 'info' \| 'Negative'` | `'Default'` | Style variant |
+| `size` | `'S' \| 'M'` | `'M'` | Item size |
+
+### DropdownMenuSubTrigger
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `variant` | `'Default' \| 'info' \| 'Negative'` | `'Default'` | Style variant |
+| `size` | `'S' \| 'M'` | `'M'` | Item size |
+| `inset` | `boolean` | `false` | Add left padding to align with items that have icons |
+| `className` | `string` | - | Additional CSS classes |
+
+### DropdownMenuSubContent
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `variant` | `'PresentationStyle'` | `'PresentationStyle'` | Visual style variant |
+| `autoGroup` | `boolean` | `true` | Auto-wrap loose items in boxed groups |
+| `className` | `string` | - | Additional CSS classes |
 
 ### DropdownMenuLabel
 
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
+| `inset` | `boolean` | `false` | Add left padding to align with items that have icons |
 | `className` | `string` | - | Additional CSS classes |
 
-### DropdownMenuSeparator
+### DropdownMenuGroup
 
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
+| `variant` | `'Boxed' \| 'Plain'` | `'Boxed'` | Boxed renders a bordered container; Plain is semantic-only |
 | `className` | `string` | - | Additional CSS classes |
 
 ### DropdownMenuShortcut
@@ -416,19 +420,22 @@ export const DropdownMenu: React.FC<DropdownMenuProps>
 
 // Content
 interface DropdownMenuContentProps {
-  variant?: 'SystemStyle' | 'PresentationStyle'
+  variant?: 'PresentationStyle'
   theme?: 'dark' | 'light' | 'default'
   className?: string
   sideOffset?: number
+  collisionPadding?: number
   align?: 'start' | 'center' | 'end'
+  autoGroup?: boolean
 }
 
 export const DropdownMenuContent: React.ForwardRefExoticComponent<DropdownMenuContentProps>
 
 // Item
 interface DropdownMenuItemProps {
-  variant?: 'Default' | 'Warning' | 'Negative' | 'SystemStyle'
+  variant?: 'Default' | 'info' | 'Negative'
   size?: 'S' | 'M'
+  inset?: boolean
   disabled?: boolean
   active?: boolean
   onSelect?: (event: Event) => void
@@ -440,7 +447,8 @@ export const DropdownMenuItem: React.ForwardRefExoticComponent<DropdownMenuItemP
 interface DropdownMenuCheckboxItemProps {
   checked?: boolean | 'indeterminate'
   onCheckedChange?: (checked: boolean) => void
-  variant?: 'Default' | 'Warning' | 'Negative' | 'SystemStyle'
+  variant?: 'Default' | 'info' | 'Negative'
+  size?: 'S' | 'M'
 }
 
 export const DropdownMenuCheckboxItem: React.ForwardRefExoticComponent<DropdownMenuCheckboxItemProps>
@@ -448,7 +456,9 @@ export const DropdownMenuCheckboxItem: React.ForwardRefExoticComponent<DropdownM
 // RadioItem
 interface DropdownMenuRadioItemProps {
   value: string
-  variant?: 'Default' | 'Warning' | 'Negative' | 'SystemStyle'
+  variant?: 'Default' | 'info' | 'Negative'
+  size?: 'S' | 'M'
+  onSelect?: (event: Event) => void
 }
 
 export const DropdownMenuRadioItem: React.ForwardRefExoticComponent<DropdownMenuRadioItemProps>
@@ -595,7 +605,7 @@ describe('DropdownMenu', () => {
 | Bundle size (minified) | ~8kb |
 | Bundle size (gzipped) | ~3kb |
 | Dependencies | @radix-ui/react-dropdown-menu (~15kb) |
-| Max height | 200px (scrollable) |
+| Max height | Radix available height (scrollable) |
 | Tree-shakeable | ✅ |
 
 ## Best Practices

package/docs/components/searchable-select.md

@@ -0,0 +1,359 @@
+---
+title: SearchableSelect
+description: Searchable single-select combobox with focus-to-open, client or server-side filtering, and infinite-scroll pagination
+group: Inputs
+keywords: [searchable-select, combobox, select, search, async, infinite-scroll, pagination]
+---
+
+# SearchableSelect
+
+> A searchable single-select combobox that opens on focus and filters options as you type. Renders DropdownMenu-style rows on a Popover surface so the input keeps focus while filtering. Supports static options with local filtering, or server-side search with debounced queries and infinite-scroll pagination.
+
+## Installation
+
+```bash
+npm install @radix-ui/react-popover
+```
+
+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`.
+
+## Import
+
+```typescript
+import { SearchableSelect } from '@torch-ui/components'
+import type { SearchableSelectOption } from '@torch-ui/components'
+```
+
+## Quick Examples
+
+### Basic (static options)
+
+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 { useState } from 'react'
+
+const options: SearchableSelectOption[] = [
+  { value: 'react', label: 'React', icon: <i className="ri-reactjs-line" /> },
+  { value: 'vue', label: 'Vue', icon: <i className="ri-vuejs-line" /> },
+  { value: 'svelte', label: 'Svelte', icon: <i className="ri-svelte-line" /> },
+  { value: 'angular', label: 'Angular', icon: <i className="ri-angularjs-line" /> },
+]
+
+function FrameworkPicker() {
+  const [value, setValue] = useState<string | null>(null)
+
+  return (
+    <SearchableSelect
+      options={options}
+      value={value}
+      onValueChange={(next) => setValue(next)}
+      placeholder="Search frameworks…"
+      icon={<i className="ri-search-line" />}
+    />
+  )
+}
+```
+
+### Async server search + infinite scroll
+
+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 { useEffect, useState } from 'react'
+
+const PAGE_SIZE = 20
+
+function UserPicker() {
+  const [value, setValue] = useState<string | null>(null)
+  const [options, setOptions] = useState<SearchableSelectOption[]>([])
+  const [query, setQuery] = useState('')
+  const [page, setPage] = useState(1)
+  const [hasMore, setHasMore] = useState(true)
+  const [loading, setLoading] = useState(false)
+
+  // Fetch whenever the query or page changes.
+  useEffect(() => {
+    let cancelled = false
+    setLoading(true)
+
+    fetch(`/api/users?q=${encodeURIComponent(query)}&page=${page}&size=${PAGE_SIZE}`)
+      .then((res) => res.json())
+      .then((data: { id: string; name: string }[]) => {
+        if (cancelled) return
+        const next = data.map((u) => ({ value: u.id, label: u.name }))
+        // Replace on a fresh query (page 1), append on subsequent pages.
+        setOptions((prev) => (page === 1 ? next : [...prev, ...next]))
+        setHasMore(data.length === PAGE_SIZE)
+      })
+      .finally(() => {
+        if (!cancelled) setLoading(false)
+      })
+
+    return () => {
+      cancelled = true
+    }
+  }, [query, page])
+
+  return (
+    <SearchableSelect
+      options={options}
+      value={value}
+      onValueChange={(next) => setValue(next)}
+      placeholder="Search users…"
+      filterClientSide={false}
+      onSearchChange={(q) => {
+        // New search: reset to the first page.
+        setQuery(q)
+        setPage(1)
+      }}
+      hasMore={hasMore}
+      loading={loading}
+      onLoadMore={() => setPage((p) => p + 1)}
+      searchDebounceMs={300}
+    />
+  )
+}
+```
+
+### Capping visible rows (`maxVisibleItems`)
+
+The list shows up to `maxVisibleItems` rows (default `5`) before it scrolls internally.
+
+```typescript
+import { SearchableSelect } from '@torch-ui/components'
+
+function CompactList({ options, value, onValueChange }) {
+  return (
+    <SearchableSelect
+      options={options}
+      value={value}
+      onValueChange={onValueChange}
+      maxVisibleItems={3}
+    />
+  )
+}
+```
+
+### RTL support
+
+Pass `dir="rtl"` to lay out the input, chevron, and dropdown right-to-left.
+
+```typescript
+import { SearchableSelect } from '@torch-ui/components'
+
+function ArabicPicker({ options, value, onValueChange }) {
+  return (
+    <SearchableSelect
+      dir="rtl"
+      options={options}
+      value={value}
+      onValueChange={onValueChange}
+      placeholder="ابحث…"
+    />
+  )
+}
+```
+
+## API Reference
+
+### SearchableSelect
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `options` | `SearchableSelectOption[]` | Required | The list of selectable options. In server mode (`filterClientSide={false}`) these are rendered as-is. |
+| `value` | `string \| null` | - | Controlled selected value. The matching option's label is shown as solid text in the input. |
+| `onValueChange` | `(value: string, option: SearchableSelectOption) => void` | - | Called when an option is selected. Receives the value and the full option object. |
+| `placeholder` | `string` | `'Search…'` | Placeholder text for the search input. |
+| `size` | `'XS' \| 'S' \| 'M'` | `'M'` | Field size. |
+| `variant` | `'PresentationStyle'` | `'PresentationStyle'` | Visual style variant for the field and dropdown surface. |
+| `icon` | `ReactNode` | - | Optional leading icon rendered inside the field. |
+| `theme` | `'dark' \| 'light' \| 'default'` | - | Theme variant, applied via `data-theme`. |
+| `dir` | `string` | - | Text direction (e.g. `'rtl'`) for the field and dropdown. |
+| `className` | `string` | - | Additional CSS classes for the field group. |
+| `filterClientSide` | `boolean` | `true` | When `true`, filters `options` locally by label. Set `false` for server-side search — `options` are rendered as-is and refetched via `onSearchChange`. |
+| `onSearchChange` | `(query: string) => void` | - | Called (debounced) with the trimmed query as the user types. Refetch your data here for server-side search. |
+| `searchDebounceMs` | `number` | `300` | Debounce delay (ms) before `onSearchChange` fires. |
+| `hasMore` | `boolean` | `false` | Whether more pages are available; gates the infinite-scroll loader. |
+| `loading` | `boolean` | `false` | Whether a fetch is in flight; shows a loading row and blocks `onLoadMore`. |
+| `onLoadMore` | `() => void` | - | Called when the scroll viewport nears the bottom and `hasMore && !loading`. |
+| `maxVisibleItems` | `number` | `5` | Maximum rows visible before the list scrolls internally. |
+
+### SearchableSelectOption
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `value` | `string` | Required | Unique value for the option; matched against the `value` prop. |
+| `label` | `string` | Required | Display text; also used for client-side label filtering. |
+| `icon` | `ReactNode` | - | Optional leading icon rendered in the row. |
+
+## TypeScript
+
+### Type Definitions
+
+```typescript
+import { ReactNode } from 'react'
+
+export interface SearchableSelectOption {
+  value: string
+  label: string
+  icon?: ReactNode
+}
+
+interface SearchableSelectProps {
+  options: SearchableSelectOption[]
+  value?: string | null
+  onValueChange?: (value: string, option: SearchableSelectOption) => void
+  placeholder?: string
+  size?: 'XS' | 'S' | 'M'
+  variant?: 'PresentationStyle'
+  icon?: ReactNode
+  theme?: 'dark' | 'light' | 'default'
+  dir?: string
+  className?: string
+
+  // Async / backend pagination (all optional; static `options` still work)
+  filterClientSide?: boolean
+  onSearchChange?: (query: string) => void
+  searchDebounceMs?: number
+  hasMore?: boolean
+  loading?: boolean
+  onLoadMore?: () => void
+  maxVisibleItems?: number
+}
+
+export function SearchableSelect(props: SearchableSelectProps): JSX.Element
+```
+
+## Common Patterns
+
+### With React Query (`useInfiniteQuery`)
+
+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 { useInfiniteQuery } from '@tanstack/react-query'
+import { useMemo, useState } from 'react'
+
+function UserPicker() {
+  const [value, setValue] = useState<string | null>(null)
+  const [query, setQuery] = useState('')
+
+  const { data, fetchNextPage, hasNextPage, isFetching } = useInfiniteQuery({
+    queryKey: ['users', query],
+    queryFn: ({ pageParam = 1 }) =>
+      fetch(`/api/users?q=${query}&page=${pageParam}`).then((r) => r.json()),
+    getNextPageParam: (lastPage, pages) =>
+      lastPage.length ? pages.length + 1 : undefined,
+    initialPageParam: 1,
+  })
+
+  const options: SearchableSelectOption[] = useMemo(
+    () =>
+      (data?.pages.flat() ?? []).map((u: { id: string; name: string }) => ({
+        value: u.id,
+        label: u.name,
+      })),
+    [data]
+  )
+
+  return (
+    <SearchableSelect
+      options={options}
+      value={value}
+      onValueChange={setValue}
+      filterClientSide={false}
+      onSearchChange={setQuery}
+      hasMore={Boolean(hasNextPage)}
+      loading={isFetching}
+      onLoadMore={() => fetchNextPage()}
+    />
+  )
+}
+```
+
+### With SWR (`useSWRInfinite`)
+
+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 useSWRInfinite from 'swr/infinite'
+import { useState } from 'react'
+
+const PAGE_SIZE = 20
+
+function UserPicker() {
+  const [value, setValue] = useState<string | null>(null)
+  const [query, setQuery] = useState('')
+
+  const { data, size, setSize, isValidating } = useSWRInfinite(
+    (index) => `/api/users?q=${query}&page=${index + 1}&size=${PAGE_SIZE}`,
+    (url) => fetch(url).then((r) => r.json())
+  )
+
+  const pages = data ?? []
+  const options = pages
+    .flat()
+    .map((u: { id: string; name: string }) => ({ value: u.id, label: u.name }))
+  const hasMore = pages.length > 0 && pages[pages.length - 1].length === PAGE_SIZE
+
+  return (
+    <SearchableSelect
+      options={options}
+      value={value}
+      onValueChange={setValue}
+      filterClientSide={false}
+      onSearchChange={(q) => {
+        setQuery(q)
+        setSize(1)
+      }}
+      hasMore={hasMore}
+      loading={isValidating}
+      onLoadMore={() => setSize(size + 1)}
+    />
+  )
+}
+```
+
+## Accessibility
+
+- **Focus opens the dropdown**: focusing the input opens the list and clears any in-progress search so the user can type freely.
+- **Type to filter**: typing updates the query. With `filterClientSide={true}` (default) options filter locally by label; otherwise the debounced `onSearchChange` drives a server refetch.
+- **Chevron toggle**: a boxed icon `Button` toggles the dropdown open/closed and flips (rotates 180°) to reflect state. It is `tabIndex={-1}` and exposes a dynamic `aria-label` of `"Open"` / `"Close"`.
+- **Single-select**: clicking a row selects it, closes the dropdown, and shows the option's label as solid text in the input. The selected row is marked with a check icon and `data-highlighted`.
+- **Infinite scroll**: the scroll viewport calls `onLoadMore` when it nears the bottom (within ~80px) and `hasMore && !loading`. A `LoadingIcon` row is shown while `loading` is true.
+- **Empty state**: when no options match and nothing is loading, a "No results found" message is shown.
+- **Rows match DropdownMenu items**: option rows reuse `MenuItemStyles`, so they look and behave like `DropdownMenuItem` entries.
+
+## Best Practices
+
+1. **Always control `value`** — pass `value` and `onValueChange` so the input can display the selected label.
+   ```typescript
+   <SearchableSelect value={value} onValueChange={setValue} options={options} />
+   ```
+
+2. **Disable client filtering for server search** — set `filterClientSide={false}` whenever you refetch in `onSearchChange`, otherwise local filtering will hide server results.
+
+3. **Reset to the first page on a new query** — in `onSearchChange`, set your page back to `1` (or `setSize(1)`) before refetching so paginated results don't mix searches.
+
+4. **Report `loading` accurately** — `onLoadMore` is blocked while `loading` is `true`, which prevents duplicate page fetches during scroll.
+
+5. **Gate pagination with `hasMore`** — only set `hasMore` when the backend confirms another page exists, so the loader stops at the end of the list.
+
+6. **Tune `searchDebounceMs`** — increase it for expensive endpoints to reduce request volume; lower it for snappy local-backed APIs.
+
+7. **Cap the visible list with `maxVisibleItems`** — keep the dropdown compact for long lists; the rest scrolls internally.
+
+## Related Components
+
+- [Select](./select.md) - Standard form select field
+- [SearchableTable](./searchable-table.md) - Searchable table with the same focus-to-open behavior
+- [DropdownMenu](./dropdown-menu.md) - Menu surface and item styling reused by the rows
+- [BadgeField](./badge-field.md) - Multi-value tag/badge input field