torch-glare 2.3.0 → 2.4.0

package/docs/components/header-bar.md

@@ -0,0 +1,181 @@
+---
+title: HeaderBar
+description: Variant-driven page/form header chip pairing a colored emphasis pill with a plain title.
+component: true
+group: Layout
+keywords: [header, headerbar, page-header, form-header, title, badge, label, layout]
+---
+
+# HeaderBar
+
+A presentational header chip used at the top of a form, page, or drawer to communicate the current record context — for example "NEW sales invoice", "EDIT sales invoice", or "ORDER de-344". It pairs a colored emphasis pill (the `label`) with a plain `title`, and the `variant` controls both the pill color and which side the pill sits on. The surface is always a fixed dark container, and the component is non-interactive.
+
+## Installation
+
+```bash
+npx torch-glare@latest add HeaderBar
+```
+
+## Imports
+
+```typescript
+import HeaderBar from '@/components/HeaderBar'
+```
+
+```typescript
+import { HeaderBar } from '@/components/HeaderBar'
+```
+
+Both the default export and the named export resolve to the same component. The website convention is the default import.
+
+## Basic Usage
+
+```tsx
+import HeaderBar from '@/components/HeaderBar'
+
+export function BasicHeaderBar() {
+  return (
+    <HeaderBar
+      variant="new"
+      label="New"
+      title="sales iNVOICE"
+    />
+  )
+}
+```
+
+## Examples
+
+### New Invoice Header
+
+The `new` variant renders a blue emphasis pill on the left followed by the plain title on the right. Use it on create screens.
+
+```tsx
+import HeaderBar from '@/components/HeaderBar'
+
+export function NewInvoiceHeader() {
+  return (
+    <HeaderBar
+      variant="new"
+      label="New"
+      title="sales iNVOICE"
+    />
+  )
+}
+```
+
+### Edit Header
+
+The `edit` variant shares the exact same layout as `new` (pill left, title right) but uses an orange emphasis pill. Use it on edit screens.
+
+```tsx
+import HeaderBar from '@/components/HeaderBar'
+
+export function EditInvoiceHeader() {
+  return (
+    <HeaderBar
+      variant="edit"
+      label="edit"
+      title="sales iNVOICE"
+    />
+  )
+}
+```
+
+### Detail Header
+
+The `detail` variant swaps the positions: the plain title renders on the left and the colored (white-alpha) pill renders on the right. Use it for read-only record context such as an order reference.
+
+```tsx
+import HeaderBar from '@/components/HeaderBar'
+
+export function OrderDetailHeader() {
+  // Renders as:  SALES INVOICE  [ de-344 ]
+  // plain title on the LEFT, badge on the RIGHT
+  return (
+    <HeaderBar
+      variant="detail"
+      label="de-344"
+      title="sales iNVOICE"
+    />
+  )
+}
+```
+
+### Themed
+
+HeaderBar accepts a `theme` prop applied via `data-theme`. The surface is always a dark chip, so theming is most useful for keeping the component consistent with the surrounding `data-theme` scope.
+
+```tsx
+import HeaderBar from '@/components/HeaderBar'
+
+export function ThemedHeaderBars() {
+  return (
+    <div className="flex flex-col gap-4">
+      <HeaderBar variant="new" label="New" title="sales iNVOICE" theme="dark" />
+      <HeaderBar variant="edit" label="edit" title="sales iNVOICE" theme="light" />
+      <HeaderBar variant="detail" label="de-344" title="sales iNVOICE" theme="default" />
+    </div>
+  )
+}
+```
+
+## API Reference
+
+### HeaderBar Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| variant | `'new' \| 'edit' \| 'detail'` | `'new'` | Controls both the pill color and which side the pill sits on |
+| label | `string` | — (required) | Text rendered inside the colored emphasis pill |
+| title | `string` | — (required) | Plain text rendered alongside the pill |
+| theme | `Themes` | — | Theme variant applied via `data-theme` (`'dark' \| 'light' \| 'default'`) |
+| className | `string` | — | Additional CSS classes merged onto the root element |
+
+All standard `HTMLAttributes<HTMLDivElement>` (for example `id`, `aria-*`, `data-*`, `style`, `onClick`) pass through to the root `div`.
+
+## Variants
+
+| Variant | Pill color | Pill text | Layout (left → right) |
+|---------|-----------|-----------|------------------------|
+| `new` | `bg-blue-sparkle-alpha-50` | `text-blue-sparkle-200` | pill (`label`) → title |
+| `edit` | `bg-orange-alpha-50` | `text-orange-200` | pill (`label`) → title |
+| `detail` | `bg-white-alpha-30` | `text-white-00` | title → pill (`label`) — positions swapped |
+
+## Styling
+
+- **Fixed dark container**: `rounded-[14px]`, `border-black-600`, `bg-black-1000`, `p-1.5`, with a double soft shadow. The surface is always dark regardless of theme.
+- **Layout**: the root is `inline-flex`, so the chip hugs its content rather than stretching to fill its parent.
+- **Typography**: 28px, weight 510, uppercase, SF Pro with the `cv05` stylistic set. Both `label` and `title` render uppercase.
+- **Emphasis pill**: the colored badge background and text color are driven entirely by `variant` (see the Variants table). For `detail`, the pill also moves to the right side.
+
+## TypeScript Types
+
+```typescript
+import { HTMLAttributes } from 'react'
+import { Themes } from '@/utils/types'
+
+interface HeaderBarProps extends HTMLAttributes<HTMLDivElement> {
+  variant?: 'new' | 'edit' | 'detail'
+  label: string
+  title: string
+  theme?: Themes
+  className?: string
+}
+```
+
+## Accessibility
+
+- HeaderBar is purely presentational — it has no interactive behavior and is intended to label the surrounding content visually.
+- Because the text is rendered uppercase via styling (not the source string), screen readers receive the original casing of `label` and `title`.
+- Pass any `aria-*` attributes through the standard prop spread when the chip needs an explicit accessible role or label in its context.
+- HeaderBar does not render an HTML heading element. When this chip represents the page or section heading, ensure proper heading semantics exist in the surrounding layout (for example an `<h1>` / `<h2>` for the page) so document structure remains navigable.
+
+## Best Practices
+
+1. **Match the variant to the screen mode**: use `new` for create screens, `edit` for edit screens, and `detail` for read-only record context.
+2. **Keep `label` short**: it is the emphasis pill, so a concise token (a mode word like "New" / "edit" or a record reference like "de-344") reads best — text renders UPPERCASE automatically.
+3. **Use `title` for the record type**: the plain side should name the entity (for example "sales invoice", "Order"), not duplicate the label.
+4. **Expect the detail swap**: for `variant="detail"` the pill moves to the right and the title to the left — author content with that ordering in mind.
+5. **Don't rely on it for interactivity**: HeaderBar is a label, not a control; place buttons or actions in a separate toolbar.
+6. **Let it hug its content**: the chip is `inline-flex`; avoid forcing it to full width and keep it at the top of the form, page, or drawer it describes.

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/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.3.0",
+  "version": "2.4.0",
   "type": "module",
   "license": "MIT",
   "files": [