torch-glare 2.5.6 → 2.6.0

package/docs/components/searchable-tree.md

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

@@ -1,483 +0,0 @@
----
-name: SectionBlock
-title: SectionBlock
-description: Sectioned card container with a colored title badge for grouping related content like forms, tables, or lists.
-category: layout
-group: Layout & Containers
-tags: [layout, card, section, container, form, group]
-status: stable
-version: 2.4.5
-dependencies:
-  - "class-variance-authority": "^0.7.0"
----
-
-# SectionBlock
-
-> A card container with an optional colored title badge. Use it to group related content — custom field forms, tables, settings groups — under a clear, color-coded heading.
-
-## 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 SectionBlock
-```
-
-`add` also copies any components, hooks, and utilities that `SectionBlock` depends on.
-
-## Import
-
-Import from your project's local path — the alias configured in `glare.json` (e.g. `@/*`):
-
-```tsx
-import { SectionBlock } from "@/components/SectionBlock";
-```
-
-## Basic Usage
-
-```tsx
-import { SectionBlock } from "@/components/SectionBlock";
-
-export function Example() {
-  return (
-    <SectionBlock color="Blue" title="Project details">
-      <p className="text-content-presentation-action-light-primary py-4">
-        Card body content goes here.
-      </p>
-    </SectionBlock>
-  );
-}
-```
-
-## API Reference
-
-### Props
-
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `color` | `SectionColor` | `"Blue"` | Color of the title badge. One of `Blue`, `Yellow`, `Green`, `Red`, `Orange`, `Purple`, `Pink`, `Gray`. |
-| `title` | `ReactNode` | — | Title rendered inside the colored badge. Optional — when omitted, the header is hidden entirely. Accepts any ReactNode (string, JSX with icons, links, etc.). |
-| `icon` | `ReactNode` | — | Rendered inside the badge, to the left of `title`. |
-| `action` | `ReactNode` | — | Right-aligned content on the title row — typically action buttons. |
-| `variant` | `SectionVariant` | `"Default"` | `"Default"` is the padded form card. `"Table"` is the full-bleed table shell: no body padding, a rule under the header, no bottom padding, and the card clipped to its radius. See [Table Variant](#table-variant). |
-| `containerClassName` | `string` | — | Class name applied to the outer container (alongside `className`). |
-| `headerClassName` | `string` | — | Class name applied to the header wrapper around the title badge. |
-| `bodyClassName` | `string` | — | Class name applied to the body wrapper holding `children`. |
-| `className` | `string` | — | Standard React class name on the outer container. |
-| `children` | `ReactNode` | — | Body content. |
-| `...rest` | `HTMLAttributes<HTMLDivElement>` | — | All standard div props except `title` (which is overridden). |
-
-### TypeScript
-
-```typescript
-export type SectionColor =
-  | "Blue"
-  | "Yellow"
-  | "Green"
-  | "Red"
-  | "Orange"
-  | "Purple"
-  | "Pink"
-  | "Gray";
-
-export type SectionVariant = "Default" | "Table";
-
-export interface SectionBlockProps
-  extends Omit<HTMLAttributes<HTMLDivElement>, "title"> {
-  color?: SectionColor;
-  variant?: SectionVariant;
-  title?: ReactNode;
-  icon?: ReactNode;
-  action?: ReactNode;
-  containerClassName?: string;
-  headerClassName?: string;
-  bodyClassName?: string;
-}
-```
-
-The component is a `forwardRef<HTMLDivElement, SectionBlockProps>`.
-
-## Examples
-
-### All Colors
-
-```tsx
-import { SectionBlock, type SectionColor } from "@/components/SectionBlock";
-
-const COLORS: SectionColor[] = [
-  "Blue",
-  "Yellow",
-  "Green",
-  "Red",
-  "Orange",
-  "Purple",
-  "Pink",
-  "Gray",
-];
-
-export function AllColors() {
-  return (
-    <div className="flex flex-col gap-[24px]">
-      {COLORS.map((color) => (
-        <SectionBlock key={color} color={color} title={`${color} section`}>
-          <p className="text-content-presentation-action-light-primary py-4">
-            This is a {color.toLowerCase()} sectioned card.
-          </p>
-        </SectionBlock>
-      ))}
-    </div>
-  );
-}
-```
-
-### No Title
-
-When `title` is omitted, the header is hidden but the body padding remains.
-
-```tsx
-<SectionBlock>
-  <p className="text-content-presentation-action-light-primary py-4">
-    A SectionBlock without a title — header is hidden, body still padded.
-  </p>
-</SectionBlock>
-```
-
-### Rich Title with Icon
-
-`title` accepts any ReactNode, so you can pass JSX with icons, counts, links, etc.
-
-```tsx
-<SectionBlock
-  color="Purple"
-  title={
-    <span className="flex items-center gap-[6px]">
-      <i className="ri-magic-line" />
-      Rich title with icon
-    </span>
-  }
->
-  <p className="text-content-presentation-action-light-primary py-4">
-    The title prop is fully customizable.
-  </p>
-</SectionBlock>
-```
-
-### Custom Fields Form
-
-A common pattern: pair `SectionBlock` with a row layout to build labeled-field forms.
-
-```tsx
-import { type ReactNode } from "react";
-import { SectionBlock } from "@/components/SectionBlock";
-import { InputField } from "@/components/InputField";
-import { ActionButton } from "@/components/ActionButton";
-
-export function CustomFieldsForm() {
-  return (
-    <SectionBlock
-      color="Blue"
-      title={
-        <span className="flex items-center gap-[6px]">
-          <i className="ri-edit-box-line" />
-          Custom fields
-        </span>
-      }
-    >
-      <FieldRow
-        label="Name"
-        required
-        right={
-          <div className="flex flex-1 items-center gap-[12px]">
-            <InputField placeholder="First Name*" className="flex-1" />
-            <InputField placeholder="Last Name*" className="flex-1" />
-          </div>
-        }
-      />
-
-      <RowDivider />
-
-      <FieldRow
-        label="Department"
-        right={<InputField placeholder="Write Hint Here" className="flex-1" />}
-      />
-
-      <RowDivider />
-
-      <FieldRow
-        label="Alias names"
-        right={
-          <InputField
-            placeholder="Write Hint Here"
-            className="flex-1"
-            childrenSide={
-              <ActionButton aria-label="Add alias name">
-                <i className="ri-add-line" />
-              </ActionButton>
-            }
-          />
-        }
-      />
-    </SectionBlock>
-  );
-}
-
-interface FieldRowProps {
-  label: string;
-  required?: boolean;
-  right: ReactNode;
-}
-
-function FieldRow({ label, required, right }: FieldRowProps) {
-  return (
-    <div className="flex items-center gap-[24px] py-[18px]">
-      <div className="flex w-[220px] 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">
-            (Required)
-          </span>
-        )}
-      </div>
-      <div className="flex flex-1 items-center">{right}</div>
-    </div>
-  );
-}
-
-function RowDivider() {
-  return <div className="h-px w-full bg-border-presentation-global-primary" />;
-}
-```
-
-### 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" />;
-}
-```
-
-### Table Variant
-
-`variant="Table"` swaps the padded form body for the full-bleed table shell: the body loses
-its `px-[42px]` gutter, gains a rule under the header, and the card is clipped to its 16px
-radius with no bottom padding — so an end-action row meets the card edge.
-
-The layout has three stacked parts, and the order matters. Only the **scroller** scrolls
-horizontally; the header actions above it and the end-action below it stay put, which is
-what keeps `Add New` reachable on a wide table.
-
-The section body is itself the horizontal scrollport, so a table wider than the card scrolls
-**inside** it rather than being clipped or widening the page. One consequence worth knowing: a
-scrollport is the containing block for `position: sticky`, so a `Table`'s sticky header inside a
-section now resolves against a box that never scrolls vertically — i.e. it stops sticking. If you
-need a sticky header, give the table its own vertical scroller.
-
-```tsx
-import { SectionBlock } from "@/components/SectionBlock";
-import { Button } from "@/components/Button";
-import {
-  Table,
-  TableBody,
-  TableCell,
-  TableEndAction,
-  TableHead,
-  TableHeader,
-  TableRow,
-  TableScroller,
-} from "@/components/Table";
-
-<SectionBlock
-  variant="Table"
-  color="Purple"
-  title="Items Table"
-  icon={<i className="ri-box-3-line text-[18px]" />}
-  action={
-    <>
-      <Button type="button" size="M" variant="BorderStyle" disabled>
-        Delete Row
-      </Button>
-      <Button type="button" size="M" variant="BluColStyle">
-        Add New
-      </Button>
-    </>
-  }
->
-  <TableScroller>
-    <Table className="min-w-full">
-      <TableHeader>
-        <TableRow>
-          <TableHead style={{ width: 200 }}>Items</TableHead>
-          <TableHead style={{ width: 200 }}>Label</TableHead>
-        </TableRow>
-      </TableHeader>
-      <TableBody>
-        <TableRow>
-          <TableCell minWidth={0}>Product name</TableCell>
-          <TableCell minWidth={0}>Label</TableCell>
-        </TableRow>
-      </TableBody>
-    </Table>
-  </TableScroller>
-
-  <TableEndAction>
-    <i className="ri-add-line" />
-    Add New
-  </TableEndAction>
-</SectionBlock>
-```
-
-For a table that edits form values, don't hand-compose this — use
-[`FormBuilder.Table`](./form-builder.md#field-components), which renders exactly this shell
-and wires rows to `react-hook-form`.
-
-### Custom Layout (override defaults)
-
-Use `containerClassName`, `headerClassName`, and `bodyClassName` to override the built-in spacing and width without losing the title/body structure.
-
-```tsx
-<SectionBlock
-  color="Green"
-  title="Compact card"
-  containerClassName="w-[600px] pt-[4px] pb-[16px]"
-  bodyClassName="px-[24px]"
->
-  <p className="text-content-presentation-action-light-primary py-2">
-    Tighter, narrower variant.
-  </p>
-</SectionBlock>
-```
-
-## Patterns
-
-- **Color coding**: Use distinct colors to help users scan a page of multiple sections (e.g., Blue for primary forms, Yellow for warnings, Red for destructive zones).
-- **No-title sections**: Drop the `title` prop entirely when the section's purpose is obvious from context — keeps the body padding without the visual weight of a header.
-- **Composing with form fields**: `SectionBlock` does not impose any inner layout — pair it with helpers like the `FieldRow` pattern above, or with `InputField`, `Form`, or `FieldSection` for more structured forms.
-- **Width**: The component is `w-full` — it fills its parent. Constrain it from the outside, or with `containerClassName="max-w-[1100px]"`.
-
-## Accessibility
-
-- The container is a plain `<div>`. If the section represents a distinct landmark, add `role="region"` and an `aria-label` (or use `aria-labelledby` pointing at the title).
-- The title is rendered as styled text inside a badge `<div>`, not as a heading element. If the section needs a heading semantically, wrap your `title` content in an appropriate `<h2>`/`<h3>` and reset its margin via Tailwind classes.
-
-## Troubleshooting
-
-| Issue | Fix |
-|-------|-----|
-| Card overflows on small screens | The card is `w-full`; the overflow is coming from its content. Give the content `min-w-0`, or cap the card with `containerClassName="max-w-[…]"`. |
-| Title not showing | The `title` prop is optional — omitting it hides the entire header. Pass any non-null `ReactNode` to render it. |
-| Badge color looks wrong | `color` only accepts the predefined `SectionColor` values. For custom badge colors, override via `headerClassName` and a custom child node. |
-| Need a different background | The body uses `bg-background-presentation-form-base`. Override via `containerClassName` (your class wins via `cn()` merging). |