torch-glare 2.1.3 → 2.1.5

package/docs/components/tree-view.md

@@ -0,0 +1,136 @@
+---
+title: TreeView
+description: Standalone hierarchical tree view for DataViews — a sidebar tree of nodes with a right pane (table or card) for the selected node. Use inside DataViewsLayout (tab mode) or directly in Composable Mode.
+group: Data Display
+keywords: [data-views, tree-view, tree, hierarchy, nested, sidebar, parent-child, children, composable, dynamic-data]
+---
+
+# TreeView
+
+> The tree renderer behind `DataViewsLayout`'s "Tree" tab. It builds a hierarchy from your records (via a `children[]` array or a `parentId` reference) and shows a sidebar tree with a right pane for the selected node. In tab mode the layout renders it for you — and auto-hides the Tree tab when no hierarchy is detected. Render it directly only in **Composable Mode**.
+
+## Installation
+
+Part of `torch-glare`. Ships with the `DataViews` folder when you run `npx torch-glare add DataViews` — no separate install. It reuses the sibling `TableView`, the `Card` component, a colocated tree sidebar/drawer, and `lucide-react`.
+
+## Import
+
+```tsx
+import { TreeView, useDataViewsState } from "torch-glare"
+import type { TreeViewProps, TreeConfig, FieldConfig } from "torch-glare"
+```
+
+## When to use it directly
+
+| Situation | Use |
+|---|---|
+| You want the standard tabbed multi-view UI | `DataViewsLayout` — the Tree tab appears automatically when hierarchy is detected. |
+| You want a custom layout with an always-on tree | Render `TreeView` directly with state from `useDataViewsState`. |
+| You want a file/folder tree without the data-grid pane | Use [`TreeFolder`](./tree-drop-down.md) or [`TreeSubLayout`](./tree-sub-layout.md) instead. |
+
+## Hierarchy detection
+
+`TreeView` auto-detects shape from your data. Override with `treeConfig`:
+
+- **Nested** — each record carries a `children: []` array.
+- **Flat / adjacency list** — each record carries a `parentId` (or similar) pointing at its parent's id.
+
+```tsx
+// nested
+const departments = [
+  { id: 1, name: "Engineering", children: [
+    { id: 2, name: "Platform" },
+    { id: 3, name: "Product" },
+  ]},
+]
+
+// flat
+const rows = [
+  { id: 1, name: "Engineering", parentId: null },
+  { id: 2, name: "Platform", parentId: 1 },
+]
+```
+
+## Composable Mode example
+
+```tsx
+import { TreeView, useDataViewsState } from "torch-glare"
+import type { FieldConfig, TreeConfig } from "torch-glare"
+
+const fields: FieldConfig[] = [
+  { path: "name", type: "text" },
+  { path: "headcount", type: "number" },
+]
+
+const treeConfig: TreeConfig = {
+  childrenField: "children",
+  nodeLabel: "name",
+  defaultExpanded: "roots",      // "all" | "roots" | "none"
+  defaultRightPane: "table",     // "table" | "card"
+}
+
+function OrgTree() {
+  const state = useDataViewsState({ data: departments, fields, treeConfig })
+  return (
+    <TreeView
+      data={state.items}
+      fields={state.resolvedFields}
+      config={state.config}
+      treeConfig={treeConfig}
+    />
+  )
+}
+```
+
+## API Reference
+
+### `TreeViewProps`
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `data` | `DynamicRecord[]` | — (required) | Records to build the hierarchy from. Pass `state.items` (nested) in composable mode. |
+| `fields` | `FieldConfig[]` | — (required) | Field map for the right-pane table/card. Pass `state.resolvedFields`. |
+| `config` | `ViewConfig` | — (required) | View config from `useDataViewsState`. |
+| `treeConfig` | `TreeConfig` | auto-detected | Hierarchy + expansion + right-pane config (see below). |
+| `columns` | `DynamicColumnConfig[]` | `undefined` | Explicit column overrides for the right-pane table. |
+| `onDataUpdate` | `(data: DynamicRecord[]) => void` | `undefined` | Called when nodes move (drag-and-drop reparent), if `dndEnabled`. |
+| `filters` | `DynamicFilterConfig[]` | `undefined` | Explicit filter definitions. Usually inferred from `filterable` fields. |
+| `filterState` | `FilterState` | uncontrolled | Controlled filter state. Pair with `onFilterChange`. |
+| `onFilterChange` | `(filters: FilterState) => void` | `undefined` | Fires when a filter changes. |
+| `showFilters` | `boolean` | `true` | Show the integrated filter panel. |
+
+### `TreeConfig`
+
+```ts
+type TreeConfig = {
+  childrenField?: string      // nested mode: array property holding children
+  parentField?: string        // flat mode: property pointing at the parent id
+  idField?: string            // id property (default "id")
+  orderField?: string         // optional ordering within siblings
+  nodeLabel?: string          // which field labels each tree node
+  defaultExpanded?: "all" | "roots" | "none"
+  defaultRightPane?: "table" | "card"   // "details" accepted as a deprecated alias of "card"
+  dndEnabled?: boolean        // enable drag-and-drop reparenting
+}
+```
+
+See [`DataViewsLayout`](./data-views-layout.md#fieldconfig) for `FieldConfig`,
+`FilterState`, and related shapes.
+
+## Accessibility
+
+- Tree rows expose `role="treeitem"` with `aria-expanded` and `aria-selected`.
+- On mobile the sidebar collapses into a drawer with a labelled trigger.
+- The right-pane table inherits [`TableView`](./table-view.md)'s accessibility.
+
+## Theming
+
+Uses only `*-presentation-*` design tokens. Control the scheme via the parent
+`DataViewsLayout`'s `theme`.
+
+## Related
+
+- [`DataViewsLayout`](./data-views-layout.md) — the tabbed container that renders this for you
+- [`TableView`](./table-view.md) · [`KanbanView`](./kanban-view.md) · [`InboxView`](./inbox-view.md) — sibling views
+- [`TreeFolder`](./tree-drop-down.md) / [`TreeSubLayout`](./tree-sub-layout.md) — non-grid tree navigation
+- [How-to: Render a backend response with DataViews](../how-to/data-views-from-backend-response.md)

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

@@ -0,0 +1,191 @@
+---
+title: Render a backend response with DataViews
+description: Recipes for turning common backend JSON shapes into a DataViewsLayout — flat lists, nested hierarchies, inbox/message shapes, and server-driven filtering.
+group: how-to
+keywords: [data-views, recipes, backend, json, api, flat, nested, hierarchy, inbox, server-side, filtering, pagination, how-to]
+---
+
+# Render a backend response with DataViews
+
+The goal of [`DataViewsLayout`](../components/data-views-layout.md) is "one
+backend response → many UI shapes." This guide maps the JSON shapes you get
+back from an API to the props that turn them into a working view.
+
+## TL;DR
+
+```tsx
+import { DataViewsLayout } from "torch-glare"
+
+// the simplest possible case — just pass the array
+<DataViewsLayout title="Records" data={await api.get("/records")} />
+```
+
+Everything below is about refining that default for specific shapes.
+
+## Recipe 1 — Flat list of objects
+
+The most common API response. Pass it straight in; every primitive field
+becomes a column and the Table/Kanban/Inbox tabs all work. The Tree tab
+auto-hides because there's no hierarchy.
+
+```tsx
+// GET /employees → [{ id, name, role, salary, joinDate }, ...]
+<DataViewsLayout title="Employees" data={employees} />
+```
+
+Add a declarative `fields` map when you want typed rendering (currencies,
+badges, dates) and filters:
+
+```tsx
+import type { FieldConfig } from "torch-glare"
+
+const fields: FieldConfig[] = [
+  { path: "name", label: "Name", type: "text" },
+  { path: "role", type: "text", filterable: true },
+  { path: "salary", type: "currency", currency: "USD", filterable: true },
+  { path: "joinDate", type: "date-format", dateFormat: "YYYY-MM-DD" },
+]
+
+<DataViewsLayout title="Employees" data={employees} fields={fields} />
+```
+
+## Recipe 2 — Status field → Kanban board
+
+When a record has a status-like field, group it into a board. Use
+`enum-badge` + `kanbanVariants` to color each column.
+
+```tsx
+// GET /tasks → [{ id, title, status: "Todo" | "In Progress" | "Done" }, ...]
+const fields: FieldConfig[] = [
+  { path: "title", type: "text" },
+  {
+    path: "status",
+    type: "enum-badge",
+    kanbanVariants: {
+      Todo: { label: "To Do", color: "gray" },
+      "In Progress": { label: "In Progress", color: "blue" },
+      Done: { label: "Done", color: "green" },
+    },
+  },
+]
+
+<DataViewsLayout
+  title="Tasks"
+  data={tasks}
+  fields={fields}
+  views={{ table: true, kanban: true }}
+  kanbanGroupBy="status"
+/>
+```
+
+## Recipe 3 — Nested objects (dot-paths)
+
+APIs often nest related data. Reference it with dot-paths — no flattening
+needed.
+
+```tsx
+// GET /orders → [{ id, total, customer: { name, email } }, ...]
+const fields: FieldConfig[] = [
+  { path: "id", label: "Order #", type: "number" },
+  { path: "customer.name", label: "Customer", type: "text" },
+  { path: "customer.email", label: "Email", type: "link", linkType: "mailto" },
+  { path: "total", type: "currency", currency: "USD" },
+]
+
+<DataViewsLayout title="Orders" data={orders} fields={fields} />
+```
+
+## Recipe 4 — Hierarchy (nested `children[]` or flat `parentId`)
+
+When records form a tree, the Tree tab appears automatically. Both shapes work:
+
+```tsx
+// Nested: GET /departments → [{ id, name, children: [...] }]
+<DataViewsLayout
+  data={departments}
+  treeConfig={{ childrenField: "children", nodeLabel: "name", defaultExpanded: "roots" }}
+/>
+
+// Flat / adjacency list: GET /nodes → [{ id, name, parentId }]
+<DataViewsLayout
+  data={nodes}
+  treeConfig={{ parentField: "parentId", idField: "id", nodeLabel: "name" }}
+/>
+```
+
+## Recipe 5 — Message/inbox shape
+
+For mailbox-like data, the Inbox view auto-detects `isRead`, `isStarred`,
+`hasAttachment`, and `priority`. Map title/preview/date with `inboxConfig`.
+
+```tsx
+// GET /messages → [{ id, subject, from: { name }, isRead, isStarred, sentAt }]
+<DataViewsLayout
+  data={messages}
+  views={{ inbox: true }}
+  inboxConfig={{ titlePath: "subject", previewPath: "from.name", dateField: "sentAt" }}
+/>
+```
+
+## Recipe 6 — Server-driven filtering & pagination
+
+Make the layout controlled: hold `filterState` yourself and refetch when it
+changes. This keeps the URL/server as the source of truth.
+
+```tsx
+import { useState, useEffect } from "react"
+import type { FilterState } from "torch-glare"
+
+function ServerDriven() {
+  const [rows, setRows] = useState([])
+  const [filterState, setFilterState] = useState<FilterState>({})
+
+  useEffect(() => {
+    api.get("/records", { params: { filters: filterState } }).then(setRows)
+  }, [filterState])
+
+  return (
+    <DataViewsLayout
+      data={rows}
+      fields={fields}
+      filterState={filterState}
+      onFilterChange={setFilterState}
+    />
+  )
+}
+```
+
+## Recipe 7 — Custom layout (composable mode)
+
+When tabs aren't what you want — e.g. a table beside a kanban — bypass
+`DataViewsLayout` and compose the views with `useDataViewsState`.
+
+```tsx
+import { TableView, KanbanView, useDataViewsState } from "torch-glare"
+
+function SplitScreen({ data, fields }) {
+  const state = useDataViewsState({ data, fields })
+  return (
+    <div className="grid grid-cols-2 gap-4 h-screen">
+      <TableView data={state.flatItems} fields={state.resolvedFields} config={state.config} showFilters={false} />
+      <KanbanView data={state.flatItems} fields={state.resolvedFields} config={state.config} groupByField="status" />
+    </div>
+  )
+}
+```
+
+See each view's reference: [TableView](../components/table-view.md) ·
+[KanbanView](../components/kanban-view.md) ·
+[InboxView](../components/inbox-view.md) ·
+[TreeView](../components/tree-view.md).
+
+## Gotchas
+
+- **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`.
+- **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
+
+- [`DataViewsLayout`](../components/data-views-layout.md) — full prop reference
+- [`DataViewsConfigPanel`](../components/data-views-config-panel.md) — settings/filters panel

package/package.json

@@ -1,13 +1,14 @@
 {
   "name": "torch-glare",
-  "version": "2.1.3",
+  "version": "2.1.5",
   "type": "module",
   "license": "MIT",
   "files": [
     "dist",
     "apps/lib",
     "docs",
-    "!**/*-dev.*"
+    "!**/*-dev.*",
+    "!apps/lib/components/**/*.md"
   ],
   "bin": {
     "torch-glare": "dist/bin/index.js"