torch-glare 2.4.4 → 2.5.0

package/docs/components/tree-folder.md

@@ -0,0 +1,110 @@
+---
+title: TreeFolder
+description: Hierarchical tree with connector lines, multi-level expand/collapse, breadcrumb, keyboard navigation and touch-capable drag-and-drop reparenting.
+group: Data Display
+keywords: [tree, folder, hierarchy, file-explorer, expand, collapse, breadcrumb, drag-drop, reparent, nested, navigation]
+---
+
+# TreeFolder
+
+> A file-explorer style tree: nested nodes with connector lines, selection that highlights the
+> whole subtree, a breadcrumb of the current path, and drag-and-drop that can reparent a node.
+
+## 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 TreeFolder
+```
+
+`TreeFolder` is a folder component — the CLI copies the whole directory, plus the `useDragDrop`
+hook and the `cn` utility it depends on.
+
+## Import
+
+Import from your project's local path — the alias configured in `glare.json` (e.g. `@/*`):
+
+```tsx
+import { TreeFolder } from "@/components/TreeFolder";
+```
+
+## Usage
+
+```tsx
+const data = [
+  {
+    id: "src",
+    name: "src",
+    children: [
+      { id: "app", name: "app", children: [{ id: "page", name: "page.tsx", children: [] }] },
+      { id: "lib", name: "lib", children: [] },
+    ],
+  },
+];
+
+<TreeFolder
+  data={data}
+  defaultExpanded="roots"
+  onSelectionChange={(id) => setSelected(id)}
+/>
+```
+
+## Nodes
+
+A node is `{ id, name, children }` plus optional presentation and permission flags:
+
+| Field | Meaning |
+| --- | --- |
+| `id` | stable identity — selection, expansion and drag all key off it |
+| `name` | the label, as text (the row owns its own layout) |
+| `children` | nested nodes; a node with a non-empty array is *internal* (a folder) |
+| `icon` | overrides the resolved icon for this node |
+| `meta` | trailing content on the row — a count, a badge |
+| `disabled` | greyed out and non-interactive |
+| `draggable` / `droppable` | opt this node out of being picked up, or dropped into |
+| `data` | anything of yours; the component never reads it |
+
+## Props
+
+| Prop | Type | Notes |
+| --- | --- | --- |
+| `data` | `TreeFolderNode[]` | the hierarchy |
+| `selectedId` / `defaultSelectedId` | `string \| null` | controlled or uncontrolled selection |
+| `onSelectionChange` | `(id: string \| null) => void` | |
+| `expandedIds` / `defaultExpanded` | `string[]` · `"all" \| "roots" \| "none"` | |
+| `onExpandedChange` | `(ids: string[]) => void` | |
+| `dndEnabled` | `boolean` | turns dragging on |
+| `onMove` | `(args: { dragIds, parentId, index }) => void` | reports the drop; moves nothing |
+| `onDataChange` | `(next: TreeFolderNode[]) => void` | the tree applied the move for you |
+| `iconFor` | resolver | per-node icon from `{ isOpen, isInternal, isSelected }` |
+| `title` · `showHeader` · `showBreadcrumb` · `headerAccessory` | | the chrome above the rows |
+| `highlightAncestors` · `highlightSubtree` | `boolean` | how far a selection tints |
+| `rowHeight` · `indent` · `contentMinWidth` | `number` | 28 and 14 by default |
+| `emptyState` | `ReactNode` | |
+
+An imperative handle exposes `selectId`, `expandAll`, `collapseAll` and `scrollToId`.
+
+## Dragging
+
+Set `dndEnabled` and handle `onMove`. A drop is reported as **which nodes, into which parent, at
+which index** — the tree does not rearrange itself unless you also pass `onDataChange`, which hands
+back an already-moved copy for the uncontrolled case.
+
+Where a drop lands depends on where in the row it happens: the top and bottom quarters mean
+*beside* the target (reordering among its siblings), the middle means *inside* it (reparenting). A
+leaf has no inside, so its whole row reads as before-or-after. A node can never be dropped into its
+own descendant — that would detach the branch from the root — and the guard is enforced before
+`onMove` fires.
+
+It works with a finger and with the keyboard: hold to pick up and swipe to scroll, or Space, arrows,
+Space. Auto-scroll near the edges is handled for you.
+
+## Notes
+
+`DataViews.Tree` composes this component — the row height, indent, connector lines, selection band
+and drag grip all come from here, which is why a tree inside DataViews looks like every other tree
+in the product. `renderNode` there returns `{ name, icon, meta }` rather than markup, because this
+component owns the row.

package/docs/how-to/forms-with-form-builder.md

@@ -116,7 +116,9 @@ export function ItemForm({
 ```
 
 `FormBuilder.Section` groups fields in a `SectionBlock` (`color` is one of `Blue`, `Yellow`,
-`Green`, `Red`, `Orange`, `Purple`, `Pink`, `Gray`). Pass the Save via `actions` — a
+`Green`, `Red`, `Orange`, `Purple`, `Pink`, `Gray`). It also takes `icon`, `action`
+(right-aligned buttons on the title row) and `variant` — `variant="Table"` switches to the
+full-bleed table shell that `FormBuilder.Table` uses internally. Pass the Save via `actions` — a
 `FormBuilder.Submit`, which is loading-aware; it renders in the header action pill. (With raw
 `FormBuilder`, put the same `FormBuilder.Submit` in a `FormBuilder.Header`.)
 
@@ -140,7 +142,7 @@ Every field, its underlying control, and the value your `onSubmit` receives:
 | `.Otp` (`length`)                                                | `string`                                                       |
 | `.Slider` (`min`, `max`, `step`, `range`, `suffix`)              | `number` (or `[number, number]` with `range`)                  |
 | `.Color` (`presets`, `alpha`)                                    | hex `string`                                                   |
-| `.Phone` (`defaultCountry`, defaults to `+964`)                  | `string` (`"+<dial> <number>"`)                                |
+| `.Phone` (`defaultCountry`, defaults to `+964`)                  | `string` (`"+<dial> <number>"`) — collapses to a plain number input inside a `.Table` cell, where `defaultCountry` does not apply |
 | `.Date`                                                          | `Date`                                                         |
 | `.DateRange`                                                     | `{ from, to }`                                                 |
 | `.DateMultiple`                                                  | `Date[]`                                                       |
@@ -151,7 +153,7 @@ Every field, its underlying control, and the value your `onSubmit` receives:
 | `.Signature` (`penColor`)                                        | PNG data-URL `string`                                          |
 | `.FieldArray` (`children` render fn, `defaultItem`)              | `object[]`                                                     |
 | `.Table` (`columns`, `selectable`, `reorderable`, `defaultItem`) | `object[]` — editable grid; top-level child (not in a Section) |
-| `.Custom` (`render`, `formatView`)                               | anything                                                       |
+| `.Custom` (`render`)                                             | anything                                                       |
 
 See the [FormBuilder](../components/form-builder.md) doc for the full prop tables.
 
@@ -373,7 +375,7 @@ drawer's tray, beside the form:
   onOpenChange={setOpen}
   form={form}
   onSubmit={save}
-  header={{ title: "New item", badge: "New", variant: "new" }}
+  header={{ title: "New item", label: "New", variant: "new" }}
   summary={
     <FormSummary form={form} title="Item" subtitle="Summary">
       <FormSummary.Group title="Pricing">

package/docs/reference/components.md

@@ -14,7 +14,7 @@ Complete reference index of all 53 components in the TORCH Glare Components Libr
 - [Forms & Inputs (17)](#forms--inputs)
 - [Buttons & Actions (3)](#buttons--actions)
 - [Layout & Containers (7)](#layout--containers)
-- [Data Display (8)](#data-display)
+- [Data Display (9)](#data-display)
 - [Overlays & Dialogs (7)](#overlays--dialogs)
 - [Date & Time (3)](#date--time)
 - [Feedback & Status (4)](#feedback--status)
@@ -68,7 +68,7 @@ Selectable checkbox component with multiple states.
 ### LabeledCheckBox
 Checkbox with integrated label and description.
 
-- **File**: [labeled-checkbox.md](../components/labeled-checkbox.md)
+- **File**: [labeled-check-box.md](../components/labeled-check-box.md)
 - **Props**: `label`, `description`, `checked`, `onChange`
 - **Features**: Built-in label, optional description
 - **Use Cases**: Terms acceptance, preferences, options
@@ -253,6 +253,16 @@ Grouped action buttons.
 
 ## Data Display
 
+### DataViews
+One dataset shown as a table, kanban board, inbox or tree, behind a shared header, filters and settings rail.
+
+- **File**: [data-views.md](../components/data-views/index.md)
+- **Guide**: [Build a screen with DataViews](../components/data-views/guide.md)
+- **Parts**: `Header` · `ViewSwitch` · `Search` · `Actions` · `PanelToggle` · `Table` · `Board` · `Inbox` · `Tree` (+ `Tree.Table`, `Tree.Cards`, `Tree.Tab`) · `Detail` · `Panel` (+ `Tab`, `Section`, `Columns`, `Sort`, `SavedViews`) · `Filters` (+ `Presets`, `Custom`, `Summary`)
+- **Props**: `rows`, `fields`, `total`, `loading`, `onQueryChange`, `onLoadMore`, `getRowId`, `defaultView`
+- **Features**: Scroll loading, table virtualization past 300 rows, drag and drop on four surfaces (touch + keyboard), filters authored as FormBuilder fields, saved views
+- **Use Cases**: Any list screen where the server owns the query
+
 ### Badge
 Small status or label indicator.
 
@@ -305,7 +315,7 @@ Advanced table with features.
 ### TreeDropDown
 Hierarchical dropdown menu.
 
-- **File**: [tree-dropdown.md](../components/tree-dropdown.md)
+- **File**: [tree-drop-down.md](../components/tree-drop-down.md)
 - **Props**: `tree`, `value`, `onChange`
 - **Features**: Nested items, expand/collapse
 - **Use Cases**: Category selection, file trees
@@ -537,9 +547,9 @@ All components are fully typed with TypeScript. Import types from the library:
 
 ```typescript
 import type { ButtonProps } from "@/components/Button";
-import type { InputProps } from "@/components/InputProps";
-import type { ButtonProps } from "@/components/LoginButton";
-import type { SelectProps } from "@/components/SelectProps";
+import type { InputProps } from "@/components/Input";
+import type { LoginButtonProps } from "@/components/LoginButton";
+import type { SelectProps } from "@/components/Select";
 ```
 
 ---

package/docs/tutorials/component-composition.md

@@ -391,8 +391,7 @@ import { useState } from 'react';
 import { Button } from "@/components/Button";
 import { Dialog, DialogTrigger, DialogContent, DialogHeader, DialogTitle, DialogDescription } from "@/components/Dialog";
 import { LabelField } from "@/components/LabelField";
-import { Select } from "@/components/Select";
-import { SimpleOption } from "@/components/SimpleOption";
+import { Select, SelectItem } from "@/components/Select";
 import { TextArea } from "@/components/TextArea";
 import { toast } from "@/components/Toast";
 
@@ -460,10 +459,10 @@ export default function CreateProjectModal() {
               value={formData.category}
               onValueChange={(value) => setFormData({...formData, category: value})}
             >
-              <SimpleOption value="web">Web Development</SimpleOption>
-              <SimpleOption value="mobile">Mobile App</SimpleOption>
-              <SimpleOption value="design">Design</SimpleOption>
-              <SimpleOption value="other">Other</SimpleOption>
+              <SelectItem value="web">Web Development</SelectItem>
+              <SelectItem value="mobile">Mobile App</SelectItem>
+              <SelectItem value="design">Design</SelectItem>
+              <SelectItem value="other">Other</SelectItem>
             </Select>
           </div>
 
@@ -500,8 +499,7 @@ import { useState } from 'react';
 import { Badge } from "@/components/Badge";
 import { Button } from "@/components/Button";
 import { InputField } from "@/components/InputField";
-import { Select } from "@/components/Select";
-import { SimpleOption } from "@/components/SimpleOption";
+import { Select, SelectItem } from "@/components/Select";
 import { Table } from "@/components/Table";
 
 interface TableRow {
@@ -560,10 +558,10 @@ export default function DataTableWithFilters() {
               value={statusFilter}
               onValueChange={setStatusFilter}
             >
-              <SimpleOption value="all">All Status</SimpleOption>
-              <SimpleOption value="active">Active</SimpleOption>
-              <SimpleOption value="pending">Pending</SimpleOption>
-              <SimpleOption value="inactive">Inactive</SimpleOption>
+              <SelectItem value="all">All Status</SelectItem>
+              <SelectItem value="active">Active</SelectItem>
+              <SelectItem value="pending">Pending</SelectItem>
+              <SelectItem value="inactive">Inactive</SelectItem>
             </Select>
           </div>
         </div>
@@ -876,7 +874,7 @@ You now understand component composition! Continue learning:
 
 1. **[Component Documentation](../components/)** - Explore all components
 2. **[Hooks Reference](../reference/hooks.md)** - Custom hooks for common patterns
-3. **[Best Practices Guide](../how-to/best-practices.md)** - Advanced patterns
+3. **[Best Practices Guide](../how-to/guides.md)** - Advanced patterns
 
 ## Additional Resources
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "torch-glare",
-  "version": "2.4.4",
+  "version": "2.5.0",
   "type": "module",
   "license": "MIT",
   "description": "A copy-in React component library (TypeScript + Radix UI + Tailwind CSS). Its CLI copies component source directly into your project — you own the code.",
@@ -37,6 +37,7 @@
   "scripts": {
     "build": "tsc -b",
     "registry": "node scripts/bin/generateRegistry/index.js",
+    "examples": "node scripts/bin/generateExampleDocs/index.js",
     "docs:fix": "node scripts/bin/fixDocs/index.js",
     "check:ai-docs": "node scripts/bin/checkAiDocs/index.js",
     "typecheck": "pnpm -C apps run typecheck",
@@ -46,7 +47,7 @@
     "test": "pnpm -C apps run test",
     "mcp:build": "pnpm -C mcp install && pnpm -C mcp run build",
     "prepare": "pnpm -C mcp install && pnpm -C mcp run build",
-    "deploy": "pnpm run registry && npx tsc --build --force && npm publish --access public"
+    "deploy": "pnpm run registry && pnpm run examples && pnpm run check:ai-docs && npx tsc --build --force && npm publish --access public"
   },
   "dependencies": {
     "commander": "^13.1.0",

package/apps/lib/components/DataViews/DataViewRadio.tsx

@@ -1,49 +0,0 @@
-"use client";
-
-import { type ReactNode } from "react";
-import * as RadioGroupPrimitive from "@radix-ui/react-radio-group";
-import { cn } from "../../utils/cn";
-
-export interface DataViewRadioProps {
-  value: string;
-  label?: string;
-  children?: ReactNode;
-  className?: string;
-}
-
-export function DataViewRadio({ value, label, children, className }: DataViewRadioProps) {
-  return (
-    <RadioGroupPrimitive.Item
-      value={value}
-      className={cn(
-        "group flex w-full items-center gap-1.5 py-1 ps-2 h-[32px]",
-        "cursor-pointer rounded-[8px] text-left outline-none transition-colors",
-        "hover:bg-background-presentation-action-contstyle-hover focus-visible:bg-background-presentation-action-contstyle-hover",
-        className,
-      )}
-    >
-      <span
-        className={cn(
-          "flex h-[14px] w-[14px] shrink-0 items-center justify-center rounded-full",
-          // Hardcoded literals so the indicator always renders dark inside the
-          // DataView regardless of the host app's data-theme (matches the
-          // always-dark panel chrome convention). Unselected ring = the spec
-          // CheckBox-Primary border (#626467) + BorderStyle fill
-          // (rgba(255,255,255,0.05)); same tokens the shared Checkbox uses.
-          "border border-[#626467] bg-white/5 transition-colors",
-          "group-data-[state=checked]:border-transparent",
-          // #0075FF = the previous selected-fill value (border-presentation-state-focus),
-          // now literal so the blue is theme-independent and visually unchanged.
-          "group-data-[state=checked]:bg-[#0075FF]",
-        )}
-      >
-        <RadioGroupPrimitive.Indicator className="flex items-center justify-center">
-          <span className="h-[6px] w-[6px] rounded-full bg-white" />
-        </RadioGroupPrimitive.Indicator>
-      </span>
-      <span className="flex-1 typography-body-medium-regular text-content-presentation-global-primary">
-        {children ?? label}
-      </span>
-    </RadioGroupPrimitive.Item>
-  );
-}