torch-glare 2.2.1 → 2.4.0

package/docs/components/searchable-table.md

@@ -1,20 +1,20 @@
 ---
 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.
+`SearchableTable` is part of the TORCH Glare component library. It composes the [Dialog](./dialog.md) (built on Radix Dialog) and the [Table](./table.md) component internally, so both must be available — they ship with the library.
 
 ```bash
-npm install @torch-ui/components @radix-ui/react-popover
+npm install @torch-ui/components @radix-ui/react-dialog
 ```
 
 ## Import
@@ -60,13 +60,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
 
@@ -159,26 +161,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 +199,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;
 
@@ -242,7 +254,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 +270,6 @@ interface SearchableTableProps<T> {
   hasMore?: boolean
   loading?: boolean
   onLoadMore?: () => void
-  maxVisibleRows?: number
 }
 
 // Generic function component, constrained so rows are object-shaped:
@@ -395,25 +408,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/section-block.md

@@ -236,6 +236,124 @@ function RowDivider() {
 }
 ```
 
+### Bilingual Form with Language Switch (EN / AR)
+
+A real-world pattern: a `SectionBlock` form with an EN/AR language switcher in the header. The colored title badge and the `TabSwitch` stay LTR; only the field rows flip to RTL when Arabic is selected, and all labels/placeholders are translated.
+
+Key points:
+
+- Put the `TabSwitch` in a `relative` wrapper and position it `absolute top-2 right-2` so it sits at the header's top-right **outside** the colored title badge (the badge wraps the entire `title` node).
+- Apply `dir` to each field **row**, not to the `SectionBlock` root — otherwise the header (badge + switch) flips too.
+- Drive copy through a tiny `t(en, ar)` helper keyed off the selected language.
+
+```tsx
+import { type ReactNode, useState } from "react";
+import { SectionBlock } from "@/components/SectionBlock";
+import { InputField } from "@/components/InputField";
+import { ActionButton } from "@/components/ActionButton";
+import { TabSwitch } from "@/components/TabSwitch";
+
+export function BilingualFieldsForm() {
+  const [language, setLanguage] = useState<"ar" | "en">("en");
+  const isAr = language === "ar";
+  const t = (en: string, ar: string) => (isAr ? ar : en);
+
+  return (
+    <div className="relative">
+      <SectionBlock
+        color="Blue"
+        title={
+          <span className="flex items-center gap-[6px]">
+            <i className="ri-edit-box-line" />
+            {t("Custom fields", "حقول مخصصة")}
+          </span>
+        }
+      >
+        <FieldRow
+          dir={isAr ? "rtl" : "ltr"}
+          label={t("Name", "الاسم")}
+          required
+          requiredLabel={t("(Required)", "(مطلوب)")}
+          right={
+            <div className="flex flex-1 items-center gap-[12px] min-w-0">
+              <InputField placeholder={t("First Name*", "الاسم الأول*")} className="flex-1 min-w-0" />
+              <InputField placeholder={t("Last Name*", "اسم العائلة*")} className="flex-1 min-w-0" />
+            </div>
+          }
+        />
+
+        <RowDivider />
+
+        <FieldRow
+          dir={isAr ? "rtl" : "ltr"}
+          label={t("Department", "القسم")}
+          right={<InputField placeholder={t("Write Hint Here", "اكتب التلميح هنا")} className="flex-1" />}
+        />
+
+        <RowDivider />
+
+        <FieldRow
+          dir={isAr ? "rtl" : "ltr"}
+          label={t("Alias names", "الأسماء المستعارة")}
+          right={
+            <InputField
+              placeholder={t("Write Hint Here", "اكتب التلميح هنا")}
+              className="flex-1"
+              childrenSide={
+                <ActionButton aria-label={t("Add alias name", "إضافة اسم مستعار")}>
+                  <i className="ri-add-line" />
+                </ActionButton>
+              }
+            />
+          }
+        />
+      </SectionBlock>
+
+      <TabSwitch
+        className="absolute top-2 right-2 z-10"
+        size="S"
+        value={language}
+        onValueChange={setLanguage}
+        options={[
+          { value: "en", label: "English" },
+          { value: "ar", label: "العربية" },
+        ]}
+      />
+    </div>
+  );
+}
+
+interface FieldRowProps {
+  label: string;
+  required?: boolean;
+  requiredLabel?: string;
+  right: ReactNode;
+  dir?: "ltr" | "rtl";
+}
+
+function FieldRow({ label, required, requiredLabel = "(Required)", right, dir }: FieldRowProps) {
+  return (
+    <div dir={dir} className="flex items-center gap-[24px] py-[18px]">
+      <div className="flex w-[140px] shrink-0 items-center gap-[6px]">
+        <span className="typography-body-medium-regular text-content-presentation-action-light-primary">
+          {label}
+        </span>
+        {required && (
+          <span className="typography-body-small-medium text-content-presentation-state-negative">
+            {requiredLabel}
+          </span>
+        )}
+      </div>
+      <div className="flex flex-1 items-center min-w-0">{right}</div>
+    </div>
+  );
+}
+
+function RowDivider() {
+  return <div className="h-px w-full bg-border-presentation-global-primary" />;
+}
+```
+
 ### Custom Layout (override defaults)
 
 Use `containerClassName`, `headerClassName`, and `bodyClassName` to override the built-in spacing and width without losing the title/body structure.

package/docs/components/tab-switch.md

@@ -0,0 +1,163 @@
+---
+name: TabSwitch
+version: 1.0.0
+status: stable
+category: components/navigation
+tags: [tab-switch, segmented-control, view-switcher, toggle, list-cards, pills]
+last-reviewed: 2026-06-15
+bundle-size: 2.0kb
+dependencies:
+  - "class-variance-authority": "^0.7.0"
+---
+
+# TabSwitch
+
+> A segmented control for picking one option from a small set — the classic List / Cards style pill switcher. The active option renders as a solid raised white pill; thin dividers sit between adjacent inactive options (never flanking the active pill). Controlled, generic over the option value, supports optional per-option icons, three sizes, and theme-aware track/labels. This is the switcher used in the DataViews header to flip between Table / Kanban / Inbox / Tree.
+
+## Installation
+
+```bash
+npm install torch-glare
+```
+
+## Import
+
+```typescript
+import { TabSwitch } from 'torch-glare/lib/components/TabSwitch'
+import type { TabSwitchOption } from 'torch-glare/lib/components/TabSwitch'
+```
+
+## Quick Examples
+
+### Basic Usage (List / Cards)
+
+```typescript
+import { TabSwitch } from 'torch-glare/lib/components/TabSwitch'
+import { useState } from 'react'
+
+function Example() {
+  const [view, setView] = useState('list')
+
+  return (
+    <TabSwitch
+      value={view}
+      onValueChange={setView}
+      options={[
+        { value: 'list', label: 'List', icon: <i className="ri-layout-grid-line" /> },
+        { value: 'cards', label: 'Cards', icon: <i className="ri-grid-fill" /> },
+      ]}
+    />
+  )
+}
+```
+
+### Sizes
+
+```typescript
+<TabSwitch size="S" value={view} onValueChange={setView} options={options} />
+<TabSwitch size="M" value={view} onValueChange={setView} options={options} /> {/* default */}
+<TabSwitch size="L" value={view} onValueChange={setView} options={options} />
+```
+
+### Icons Only
+
+Omit `label` to render an icon-only switcher.
+
+```typescript
+<TabSwitch
+  value={view}
+  onValueChange={setView}
+  options={[
+    { value: 'list', icon: <i className="ri-layout-grid-line" /> },
+    { value: 'cards', icon: <i className="ri-grid-fill" /> },
+    { value: 'board', icon: <i className="ri-layout-column-line" /> },
+  ]}
+/>
+```
+
+### On a dark surface
+
+The active pill is always a solid white pill with dark text, so it stays visible on dark bars. The track and inactive labels follow the theme — pass `theme="dark"` (or render inside a `data-theme="dark"` scope) so they resolve dark-theme tokens. This is how the DataViews header uses it.
+
+```typescript
+<div data-theme="dark" className="bg-black p-2">
+  <TabSwitch theme="dark" value={view} onValueChange={setView} options={options} />
+</div>
+```
+
+### Disabled
+
+```typescript
+{/* whole control */}
+<TabSwitch disabled value={view} onValueChange={setView} options={options} />
+
+{/* a single option */}
+<TabSwitch
+  value={view}
+  onValueChange={setView}
+  options={[
+    { value: 'list', label: 'List' },
+    { value: 'cards', label: 'Cards', disabled: true },
+  ]}
+/>
+```
+
+## API Reference
+
+### TabSwitch
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `options` | `TabSwitchOption[]` | — (required) | The selectable options rendered as segments. |
+| `value` | `string` | — | The currently selected option value (controlled). |
+| `onValueChange` | `(value: string) => void` | — | Called with the option value when a segment is selected. |
+| `size` | `'S' \| 'M' \| 'L'` | `'M'` | Size of the control. |
+| `disabled` | `boolean` | `false` | Disables the whole control. |
+| `theme` | `'dark' \| 'light' \| 'default'` | — | Applies a fixed theme to the track and inactive labels (the active pill stays white). |
+| `className` | `string` | — | Additional classes merged onto the track. |
+
+`TabSwitch` is generic over the option value: `TabSwitch<T extends string>` infers `T` from `options`, so `value` and `onValueChange` are typed to your union (e.g. `'list' | 'cards'`).
+
+### TabSwitchOption
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `value` | `string` | — | Unique value for the option. |
+| `label` | `ReactNode` | `undefined` | Text or node shown for the option. Omit for an icon-only segment. |
+| `icon` | `ReactNode` | `undefined` | Optional leading icon rendered before the label. |
+| `disabled` | `boolean` | `false` | Disables this individual option. |
+
+## Accessibility
+
+- The track is a `role="tablist"`; each option is a `role="tab"` with `aria-selected` reflecting the active state.
+- Options are real `<button>` elements, so they are keyboard-focusable and activate on Enter/Space.
+
+## Notes
+
+- The active pill is intentionally a solid white pill with dark text in every theme (not derived from the per-theme selected-tab tokens), so it reads correctly on the always-dark DataViews header as well as on light surfaces.
+- TabSwitch is a controlled component — always pass both `value` and `onValueChange`.
+
+## TypeScript
+
+```typescript
+interface TabSwitchOption<T extends string = string> {
+  value: T
+  label?: React.ReactNode
+  icon?: React.ReactNode
+  disabled?: boolean
+}
+
+interface TabSwitchProps<T extends string = string>
+  extends Omit<React.HTMLAttributes<HTMLDivElement>, 'onChange'> {
+  options: TabSwitchOption<T>[]
+  value: T
+  onValueChange: (value: T) => void
+  size?: 'S' | 'M' | 'L'
+  theme?: 'dark' | 'light' | 'default'
+  disabled?: boolean
+}
+
+declare function TabSwitch<T extends string = string>(
+  props: TabSwitchProps<T> & { ref?: React.ForwardedRef<HTMLDivElement> }
+): React.ReactElement
+```

package/docs/how-to/data-views-from-backend-response.md

@@ -183,6 +183,7 @@ See each view's reference: [TableView](../components/table-view.md) ·
 
 - **Empty `data`** → all views render their empty state; pass `isLoading` upstream if you fetch async.
 - **Tree tab missing?** No hierarchy was detected. Supply `treeConfig` explicitly or check your `childrenField` / `parentField`.
+- **Unwanted filters?** The panel auto-detects filterable text fields with few unique values (e.g. `id`, `name`). Set `filterable: false` on a field to exclude it. For a field with many options, set `filterVariant: "searchable-select"` to render a searchable dropdown instead of a long checkbox list.
 - **Saved Views don't persist** in tab mode — that's a known limitation documented in [`DataViewsConfigPanel`](../components/data-views-config-panel.md). Use composable mode for real persistence.
 
 ## Related

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "torch-glare",
-  "version": "2.2.1",
+  "version": "2.4.0",
   "type": "module",
   "license": "MIT",
   "files": [