torch-glare 2.3.0 → 2.4.1

package/docs/components/searchable-tree.md

@@ -0,0 +1,200 @@
+---
+title: SearchableTree
+description: Searchable tree-select that opens on focus and filters hierarchical nodes as you type, on a Popover surface, with client or server-side search
+group: Inputs
+keywords: [searchable-tree, tree, tree-select, hierarchy, search, combobox, async, popover]
+---
+
+# SearchableTree
+
+> A searchable tree-select. It renders a field that opens a Popover containing a hierarchical
+> tree of nodes and filters them as you type. Accepts either nested data (via `getNodeChildren`)
+> or a flat list that it nests for you (via `parentIdKey`). Supports local filtering or
+> debounced server-side search, optional folder selection, and controlled selection.
+
+## 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 SearchableTree
+```
+
+The CLI also copies its internal dependencies: `Button`, `Input`, `Popover`, the
+`useClickOutside` hook, and the `cn`/`types` utils.
+
+## Import
+
+```typescript
+import { SearchableTree } from "@/components/SearchableTree";
+```
+
+## Quick Examples
+
+### Basic Usage (nested data)
+
+```tsx
+import { SearchableTree } from "@/components/SearchableTree";
+
+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 (
+    <SearchableTree
+      nodes={data}
+      getNodeId={(n) => n.id}
+      getNodeLabel={(n) => n.name}
+      getNodeChildren={(n) => n.children}
+      value={value}
+      onSelect={setValue}
+      placeholder="Select a department"
+      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" },
+];
+
+<SearchableTree
+  nodes={rows}
+  parentIdKey="parentId"
+  getNodeId={(r) => r.id}
+  getNodeLabel={(r) => r.label}
+  onSelect={(r) => console.log(r.id)}
+/>;
+```
+
+### Server-side search
+
+```tsx
+<SearchableTree
+  nodes={results}
+  getNodeId={(n) => n.id}
+  getNodeLabel={(n) => n.name}
+  getNodeChildren={(n) => n.children}
+  filterClientSide={false}
+  onSearchChange={(query) => fetchNodes(query)}
+  loading={isFetching}
+  searchDebounceMs={300}
+/>
+```
+
+### Selectable folders
+
+```tsx
+<SearchableTree
+  nodes={data}
+  getNodeId={(n) => n.id}
+  getNodeLabel={(n) => n.name}
+  getNodeChildren={(n) => n.children}
+  selectableFolders
+  onSelect={(n) => console.log(n.id)}
+/>
+```
+
+## 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` | `"Select…"` | Field placeholder shown when nothing is selected. |
+| `title` | `string` | `"Select an item"` | Section heading above the tree rows in the dropdown. |
+| `size` | `"XS" \| "S" \| "M"` | `"M"` | Field size. |
+| `variant` | `"SystemStyle" \| "PresentationStyle"` | `"PresentationStyle"` | Visual style. `SystemStyle` is reserved for internal library system surfaces. |
+| `icon` | `ReactNode` | — | Leading icon in the field. |
+| `theme` | `Themes` | — | `"dark" \| "light" \| "default"`. |
+| `dir` | `string` | — | Text direction. |
+| `className` | `string` | — | Extra classes for the field. |
+| `defaultExpanded` | `boolean` | `true` | Expand every node when the dropdown opens. |
+| `selectableFolders` | `boolean` | `false` | When true, folder nodes are selectable too; otherwise folders only expand/collapse. |
+| `maxBodyHeight` | `number` | `320` | Max height (px) of the scrollable tree body before it scrolls. |
+| `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 SearchableTreeProps<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;
+  title?: string;
+  size?: "XS" | "S" | "M";
+  variant?: "SystemStyle" | "PresentationStyle";
+  icon?: ReactNode;
+  theme?: Themes;
+  dir?: string;
+  className?: string;
+  defaultExpanded?: boolean;
+  selectableFolders?: boolean;
+  maxBodyHeight?: number;
+  filterClientSide?: boolean;
+  onSearchChange?: (query: string) => void;
+  searchDebounceMs?: number;
+  loading?: boolean;
+}
+
+export function SearchableTree<T>(props: SearchableTreeProps<T>): JSX.Element;
+```
+
+## Common Patterns
+
+- **Nested vs flat data:** provide `getNodeChildren` for already-nested data, or `parentIdKey`
+  to let the component nest a flat list for you. Do not use both.
+- **Async search:** set `filterClientSide={false}` and handle `onSearchChange` to fetch from a
+  backend; pass `loading` while the request is in flight.
+- **Folder selection:** by default only leaf nodes are selectable. Set `selectableFolders` to
+  allow selecting a folder node (clicking any node selects it and closes the dropdown).
+
+## Related Components
+
+- [SearchableTreeDialog](./searchable-tree-dialog.md) — the same tree-select in a modal dialog.
+- [SearchableSelect](./searchable-select.md) — flat searchable single-select combobox.
+- [TreeDropDown](./tree-drop-down.md) — dropdown tree without search.

package/docs/components/section-block.md

@@ -6,7 +6,7 @@ category: layout
 group: Layout & Containers
 tags: [layout, card, section, container, form, group]
 status: stable
-version: 1.1.22
+version: 2.4.0
 dependencies:
   - "class-variance-authority": "^0.7.0"
 ---
@@ -17,14 +17,22 @@ dependencies:
 
 ## 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 add SectionBlock
+npx torch-glare@latest init
+npx torch-glare@latest add SectionBlock
 ```
 
+`add` also copies any components, hooks, and utilities that `SectionBlock` depends on.
+
 ## Import
 
-```typescript
-import { SectionBlock, type SectionColor } from "@/components/SectionBlock";
+Import from your project's local path — the alias configured in `glare.json` (e.g. `@/*`):
+
+```tsx
+import { SectionBlock } from "@/components/SectionBlock";
 ```
 
 ## Basic Usage
@@ -236,6 +244,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/select.md

@@ -1,6 +1,6 @@
 ---
 name: Select
-version: 1.1.15
+version: 2.4.0
 status: stable
 category: components/forms
 tags: [form, select, dropdown, accessible, radix-ui]
@@ -17,23 +17,22 @@ dependencies:
 
 ## Installation
 
+TORCH Glare is a copy-in library: the CLI copies this component's source into your project
+(you do **not** install it from the npm package). Run `init` once, then `add`:
+
 ```bash
-npm install torch-glare
+npx torch-glare@latest init
+npx torch-glare@latest add Select
 ```
 
+`add` also copies any components, hooks, and utilities that `Select` depends on.
+
 ## Import
 
-```typescript
-import {
-  Select,
-  SelectTrigger,
-  SelectContent,
-  SelectItem,
-  SelectValue,
-  SelectGroup,
-  SelectLabel,
-  SelectSeparator
-} from 'torch-glare/lib/components/Select'
+Import from your project's local path — the alias configured in `glare.json` (e.g. `@/*`):
+
+```tsx
+import { Select } from "@/components/Select";
 ```
 
 ## Quick Examples
@@ -47,7 +46,7 @@ import {
   SelectContent,
   SelectItem,
   SelectValue
-} from 'torch-glare/lib/components/Select'
+} from '@/components/Select'
 
 function Example() {
   const [value, setValue] = useState('')
@@ -265,6 +264,9 @@ function Uncontrolled() {
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
 | `value` | `string` | - | Item value (required) |
+| `variant` | `'Default' \| 'Warning' \| 'Negative' \| 'SystemStyle'` | `'Default'` | Visual variant |
+| `size` | `'S' \| 'M'` | `'M'` | Item size |
+| `active` | `boolean` | `false` | Renders the item in its selected/active style |
 | `disabled` | `boolean` | `false` | Disable item |
 | `className` | `string` | - | Additional CSS classes |
 | `children` | `React.ReactNode` | - | Item content |
@@ -272,7 +274,7 @@ function Uncontrolled() {
 ### TypeScript
 
 ```typescript
-import type { Themes } from 'torch-glare/lib/utils/types'
+import type { Themes } from '@/utils/types'
 
 // Select component types
 interface SelectProps {
@@ -316,6 +318,9 @@ interface SelectContentProps {
 // Item types
 interface SelectItemProps {
   value: string
+  variant?: 'Default' | 'Warning' | 'Negative' | 'SystemStyle'
+  size?: 'S' | 'M'
+  active?: boolean
   disabled?: boolean
   className?: string
   children: React.ReactNode
@@ -363,8 +368,8 @@ function CountrySelect() {
 ### Form Integration
 
 ```typescript
-import { Form } from 'torch-glare/lib/components/Form'
-import { Label } from 'torch-glare/lib/components/Label'
+import { Form } from '@/components/Form'
+import { Label } from '@/components/Label'
 
 function FormSelect() {
   const [formData, setFormData] = useState({
@@ -464,7 +469,7 @@ function DynamicSelect() {
 
 ```typescript
 import { render, screen, fireEvent } from '@testing-library/react'
-import { Select, SelectTrigger, SelectContent, SelectItem, SelectValue } from 'torch-glare/lib/components/Select'
+import { Select, SelectTrigger, SelectContent, SelectItem, SelectValue } from '@/components/Select'
 
 describe('Select', () => {
   it('opens dropdown on trigger click', () => {

package/docs/components/simple-select.md

@@ -1,6 +1,6 @@
 ---
 name: SimpleSelect
-version: 1.1.15
+version: 2.4.0
 status: stable
 category: components/forms
 tags: [form, select, dropdown, custom, system-style, accessible]
@@ -17,18 +17,22 @@ dependencies:
 
 ## Installation
 
+TORCH Glare is a copy-in library: the CLI copies this component's source into your project
+(you do **not** install it from the npm package). Run `init` once, then `add`:
+
 ```bash
-npm install torch-glare
+npx torch-glare@latest init
+npx torch-glare@latest add SimpleSelect
 ```
 
+`add` also copies any components, hooks, and utilities that `SimpleSelect` depends on.
+
 ## Import
 
-```typescript
-import {
-  SimpleSelectValue,
-  SimpleSelectItem,
-  SimpleSelectDropDown
-} from 'torch-glare/lib/components/SimpleSelect'
+Import from your project's local path — the alias configured in `glare.json` (e.g. `@/*`):
+
+```tsx
+import { SimpleSelect } from "@/components/SimpleSelect";
 ```
 
 ## Quick Examples
@@ -36,7 +40,7 @@ import {
 ### Basic Usage
 
 ```typescript
-import { SimpleSelectValue, SimpleSelectItem } from 'torch-glare/lib/components/SimpleSelect'
+import { SimpleSelectValue, SimpleSelectItem } from '@/components/SimpleSelect'
 
 function Example() {
   const [value, setValue] = useState('option1')
@@ -470,7 +474,7 @@ function DynamicSelect() {
 
 ```typescript
 import { render, screen, fireEvent } from '@testing-library/react'
-import { SimpleSelectValue, SimpleSelectItem } from 'torch-glare/lib/components/SimpleSelect'
+import { SimpleSelectValue, SimpleSelectItem } from '@/components/SimpleSelect'
 
 describe('SimpleSelect', () => {
   it('opens dropdown on click', () => {