torch-glare 2.1.4 → 2.1.5

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

@@ -7,6 +7,7 @@ import {
   useMemo,
   useRef,
   useState,
+  type ElementType,
   type ReactNode,
 } from "react";
 import { List, LayoutGrid, Inbox as InboxIcon, Network } from "lucide-react";
@@ -61,6 +62,12 @@ export type DataViewsLayoutProps = {
   addNewLabel?: string;
 
   inboxItemHref?: (item: DynamicRecord, id: any) => string;
+  /**
+   * Component used to render inbox item links when `inboxItemHref` is set.
+   * Defaults to a plain `<a>` (full-page navigation). Pass your router's link
+   * (e.g. Next.js `Link`, React Router `Link`) for client-side navigation.
+   */
+  inboxLinkComponent?: ElementType;
   inboxSelectedId?: any;
   inboxRenderDetail?: (item: DynamicRecord | null) => ReactNode;
 
@@ -108,6 +115,7 @@ export const DataViewsLayout = forwardRef<HTMLDivElement, DataViewsLayoutProps>(
       onAddNew,
       addNewLabel,
       inboxItemHref,
+      inboxLinkComponent,
       inboxSelectedId,
       inboxRenderDetail,
       searchValue,
@@ -276,6 +284,7 @@ export const DataViewsLayout = forwardRef<HTMLDivElement, DataViewsLayoutProps>(
                     onFilterChange={setFilterState}
                     showFilters={false}
                     itemHref={inboxItemHref}
+                    linkComponent={inboxLinkComponent}
                     selectedItemId={inboxSelectedId}
                     renderDetail={inboxRenderDetail}
                   />

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

@@ -222,7 +222,8 @@ export function FilterPanel({
               <Badge
                 {...countBadge}
                 label={String(totalFilters)}
-                className="h-5 min-w-[20px] rounded-full p-0 text-xs"
+                showIcon={false}
+                className="h-5 w-5 min-w-0 justify-center rounded-full p-0 text-xs"
                 size="XS"
               />
             )}
@@ -270,9 +271,9 @@ export function FilterPanel({
             <Badge
               {...countBadge}
               label={String(totalFilters)}
-              className="h-5 min-w-[20px] rounded-full p-0 text-xs"
+              showIcon={false}
+              className="h-5 w-5 min-w-0 justify-center rounded-full p-0 text-xs"
               size="XS"
-
             />
           )}
         </div>

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

@@ -1,6 +1,12 @@
 "use client";
 
-import { useEffect, useMemo, useState, type ReactNode } from "react";
+import {
+  useEffect,
+  useMemo,
+  useState,
+  type ElementType,
+  type ReactNode,
+} from "react";
 import { Badge } from "../Badge";
 import { FilterPanel } from "./FilterPanel";
 import {
@@ -57,6 +63,12 @@ export type InboxViewProps = {
   onFilterChange?: (filters: FilterState) => void;
   showFilters?: boolean;
   itemHref?: (item: DynamicRecord, id: any) => string;
+  /**
+   * Component used to render each item's link when `itemHref` is set. Defaults
+   * to a plain `<a>` (full-page navigation). Pass your router's link
+   * (e.g. Next.js `Link`, React Router `Link`) for client-side navigation.
+   */
+  linkComponent?: ElementType;
   selectedItemId?: any;
   renderDetail?: (item: DynamicRecord | null) => ReactNode;
 };
@@ -100,6 +112,7 @@ export function InboxView({
   onFilterChange,
   showFilters = true,
   itemHref,
+  linkComponent,
   selectedItemId,
   renderDetail,
 }: InboxViewProps) {
@@ -350,6 +363,7 @@ export function InboxView({
                 selected={selected}
                 onSelect={() => handleSelectItem(item)}
                 href={itemHref?.(item, itemId)}
+                linkComponent={linkComponent}
               />
             );
           })}

package/docs/components/data-views-layout.md

@@ -140,6 +140,8 @@ Inbox auto-detects `isRead`, `isStarred`, `hasAttachment`, `priority`. Override
 | `views` | `ViewVisibility` | all on (tree auto) | Per-view toggle: `{ table?, kanban?, inbox?, tree? }`. Omitted keys default to `true` (Tree auto-hides without hierarchy). |
 | `kanbanGroupBy` | `string` | `"status"` | Dot-path to the field used for Kanban columns. |
 | `inboxConfig` | `InboxConfig` | auto-detected | Map of starred/read/attachment/priority field paths for Inbox. |
+| `inboxItemHref` | `(item, id) => string` | — | When set, each Inbox row becomes a link to the returned href. |
+| `inboxLinkComponent` | `ElementType` | `"a"` | Component used to render Inbox item links when `inboxItemHref` is set. Pass your router's link (Next.js `Link`, React Router `Link`) for client-side navigation; defaults to a plain `<a>` (full-page nav). |
 | `treeConfig` | `TreeConfig` | auto-detected | `childrenField`, `parentField`, `idField`, `nodeLabel`, `defaultExpanded`. |
 | `filterState` | `FilterState` | uncontrolled | Controlled filter state. Pair with `onFilterChange`. |
 | `onFilterChange` | `(state: FilterState) => void` | — | Fires when any filter changes. When provided, the layout is controlled. |

package/docs/components/inbox-view.md

@@ -0,0 +1,159 @@
+---
+title: InboxView
+description: Standalone inbox/list view for DataViews — a master list with read/starred/priority states and an optional detail pane. Use inside DataViewsLayout (tab mode) or directly in Composable Mode.
+group: Data Display
+keywords: [data-views, inbox-view, inbox, list, master-detail, read, starred, priority, attachment, composable, dynamic-data]
+---
+
+# InboxView
+
+> The inbox renderer behind `DataViewsLayout`'s "Inbox" tab. It renders records as a scannable list with read / starred / priority / attachment affordances, plus an optional detail pane. In tab mode the layout renders it for you; 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 depends on the shared `Badge`, `Button`, `Avatar`, `Card`, `Divider`, and `TabFormItem` components plus `lucide-react`.
+
+## Import
+
+```tsx
+import { InboxView, useDataViewsState } from "torch-glare"
+import type { InboxViewProps, InboxConfig, FieldConfig } from "torch-glare"
+```
+
+## When to use it directly
+
+| Situation | Use |
+|---|---|
+| You want the standard tabbed multi-view UI | `DataViewsLayout` with `views={{ inbox: true }}` — it mounts `InboxView` for you. |
+| You want a custom master-detail layout | Render `InboxView` directly with state from `useDataViewsState`, and supply `renderDetail`. |
+
+## Field auto-detection
+
+InboxView auto-detects these record fields and maps them to UI affordances.
+Override any of them with `inboxConfig`.
+
+| Detected field | Affordance |
+|---|---|
+| `isRead` | Read/unread weight |
+| `isStarred` | Star toggle |
+| `hasAttachment` | Paperclip icon |
+| `priority` | Priority flag |
+
+## Composable Mode example
+
+```tsx
+import { InboxView, useDataViewsState } from "torch-glare"
+import type { FieldConfig, InboxConfig } from "torch-glare"
+
+const messages = [
+  { id: 1, subject: "Welcome", from: { name: "Ada" }, isRead: false, isStarred: true, sentAt: "2024-06-01" },
+  { id: 2, subject: "Invoice", from: { name: "Billing" }, isRead: true, hasAttachment: true, sentAt: "2024-06-02" },
+]
+
+const fields: FieldConfig[] = [
+  { path: "subject", type: "text" },
+  { path: "from.name", label: "From", type: "text" },
+  { path: "sentAt", type: "date-format", dateFormat: "YYYY-MM-DD" },
+]
+
+const inboxConfig: InboxConfig = {
+  titlePath: "subject",
+  previewPath: "from.name",
+  dateField: "sentAt",
+}
+
+function Mailbox() {
+  const state = useDataViewsState({ data: messages, fields })
+  const [selectedId, setSelectedId] = useState<number | null>(null)
+  return (
+    <InboxView
+      data={state.flatItems}
+      fields={state.resolvedFields}
+      config={state.config}
+      inboxConfig={inboxConfig}
+      selectedItemId={selectedId}
+      renderDetail={(item) =>
+        item ? <MessageDetail message={item} /> : <Empty />
+      }
+    />
+  )
+}
+```
+
+### Link rows to routes (framework-agnostic)
+
+`itemHref` turns each row into a link. By default the card renders a plain `<a>`
+(full-page navigation), so it works in any framework. For client-side routing,
+pass your router's link via `linkComponent` — this is what makes navigation
+behave consistently across environments. Without it you get a normal `<a>`.
+
+```tsx
+// Next.js
+import Link from "next/link"
+
+<InboxView
+  data={state.flatItems}
+  fields={state.resolvedFields}
+  config={state.config}
+  itemHref={(item, id) => `/messages/${id}`}
+  linkComponent={Link}        // React Router users pass their <Link> the same way
+/>
+```
+
+> Via `DataViewsLayout` (tab mode) the same prop is named `inboxLinkComponent`.
+
+## API Reference
+
+### `InboxViewProps`
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `data` | `DynamicRecord[]` | — (required) | Records to render as list items. Pass `state.flatItems`. |
+| `fields` | `FieldConfig[]` | — (required) | Field map controlling list-item content. Pass `state.resolvedFields`. |
+| `config` | `ViewConfig` | — (required) | View config from `useDataViewsState`. |
+| `inboxConfig` | `InboxConfig` | auto-detected | Overrides for which record paths map to title/preview/avatar/date/read/starred/attachment/priority. |
+| `columns` | `DynamicColumnConfig[]` | `undefined` | Explicit column overrides. Usually derived from `fields`. |
+| `onDataUpdate` | `(data: DynamicRecord[]) => void` | `undefined` | Called when item data changes (e.g. toggling read/starred). |
+| `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. |
+| `itemHref` | `(item: DynamicRecord, id: any) => string` | `undefined` | When set, each row becomes a link to the returned href. |
+| `linkComponent` | `ElementType` | `"a"` | Component used to render each item's link when `itemHref` is set. Pass your router's link (Next.js `Link`, React Router `Link`) for client-side navigation. Defaults to a plain `<a>` (full-page nav). |
+| `selectedItemId` | `any` | `undefined` | Id of the currently selected row (drives the detail pane + highlight). |
+| `renderDetail` | `(item: DynamicRecord \| null) => ReactNode` | `undefined` | Renders the right-hand detail pane for the selected item. |
+
+### `InboxConfig`
+
+```ts
+type InboxConfig = {
+  starredField?: string
+  readField?: string
+  attachmentField?: string
+  priorityField?: string
+  titlePath?: string
+  previewPath?: string
+  avatarPath?: string
+  dateField?: string
+}
+```
+
+See [`DataViewsLayout`](./data-views-layout.md#fieldconfig) for `FieldConfig`,
+`FilterState`, and related shapes.
+
+## Accessibility
+
+- The all/starred/priority switcher uses [`TabFormItem`](./tab-form-item.md) (full keyboard support).
+- Star/archive/delete actions are real `<button>`s with accessible labels.
+- Avatars fall back to initials via [`Avatar`](./avatar.md).
+
+## 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) · [`TreeView`](./tree-view.md) — sibling views
+- [How-to: Render a backend response with DataViews](../how-to/data-views-from-backend-response.md)

package/docs/components/kanban-view.md

@@ -0,0 +1,125 @@
+---
+title: KanbanView
+description: Standalone kanban board view for DataViews — groups records into columns by a field and renders each as a card. Use inside DataViewsLayout (tab mode) or directly in Composable Mode.
+group: Data Display
+keywords: [data-views, kanban-view, kanban, board, columns, group-by, cards, composable, dynamic-data, fields]
+---
+
+# KanbanView
+
+> The board renderer behind `DataViewsLayout`'s "Board" tab. It groups records into columns by `groupByField` and renders each record as a card. In tab mode the layout renders it for you; 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 depends on the shared `Button` component, the `DataViewCard` layout, and `lucide-react`.
+
+## Import
+
+```tsx
+import { KanbanView, useDataViewsState } from "torch-glare"
+import type { KanbanViewProps, FieldConfig } from "torch-glare"
+```
+
+## When to use it directly
+
+| Situation | Use |
+|---|---|
+| You want the standard tabbed multi-view UI | `DataViewsLayout` with `views={{ kanban: true }}` — it mounts `KanbanView` for you. |
+| You want a custom layout (e.g. kanban beside a table) | Render `KanbanView` directly with state from `useDataViewsState`. |
+
+## Composable Mode example
+
+`KanbanView` groups by the `groupByField` path — every distinct value becomes a
+column. Column colors are assigned deterministically, or per-value via the
+field's `kanbanVariants`.
+
+```tsx
+import { KanbanView, useDataViewsState } from "torch-glare"
+import type { FieldConfig } from "torch-glare"
+
+const tasks = [
+  { id: 1, title: "Spec API", status: "Todo", assignee: "Ada" },
+  { id: 2, title: "Build UI", status: "In Progress", assignee: "Linus" },
+  { id: 3, title: "Ship", status: "Done", assignee: "Grace" },
+]
+
+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" },
+    },
+  },
+  { path: "assignee", type: "text" },
+]
+
+function TaskBoard() {
+  const state = useDataViewsState({ data: tasks, fields })
+  return (
+    <KanbanView
+      data={state.flatItems}
+      fields={state.resolvedFields}
+      config={state.config}
+      groupByField="status"
+      titleField="title"
+    />
+  )
+}
+```
+
+### Column header actions
+
+Pass `onColumnAction` to show an overflow (⋯) button on each column header. When
+omitted the button is hidden.
+
+```tsx
+<KanbanView
+  data={state.flatItems}
+  fields={state.resolvedFields}
+  config={state.config}
+  groupByField="status"
+  onColumnAction={(columnId) => openColumnMenu(columnId)}
+/>
+```
+
+## API Reference
+
+### `KanbanViewProps`
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `data` | `DynamicRecord[]` | — (required) | Records to group into columns. Pass `state.flatItems` in composable mode. |
+| `fields` | `FieldConfig[]` | — (required) | Field map controlling card content. Pass `state.resolvedFields`. |
+| `config` | `ViewConfig` | — (required) | View config from `useDataViewsState`. |
+| `groupByField` | `string` | `"status"` | Dot-path to the field whose distinct values become columns. |
+| `titleField` | `string` | first visible non-group field | Dot-path of the field rendered as the card title. |
+| `columns` | `DynamicColumnConfig[]` | `undefined` | Explicit column overrides. Usually derived from `fields`. |
+| `onDataUpdate` | `(data: DynamicRecord[]) => void` | `undefined` | Called when a card moves between columns (updates the group-by value). |
+| `onColumnAction` | `(columnId: string) => void` | `undefined` | Click handler for the column header overflow button. When omitted, the button is hidden. |
+
+Per-column colors come from each field's `kanbanVariants` map
+(`{ [value]: { label?, color? } }`). Available `color` keys: `gray`, `purple`,
+`orange`, `blue`, `green`, `red`. See
+[`DataViewsLayout`](./data-views-layout.md#fieldconfig) for the full
+`FieldConfig` shape.
+
+## Accessibility
+
+- Cards are keyboard-focusable; the column overflow button is a real `<button>`.
+- Card titles use semantic heading markup within each [`DataViewCard`](./card.md).
+
+## Theming
+
+Uses `*-presentation-*` tokens plus a small set of deeply-saturated column-header
+fills matched to `glare-torch-mode` raw 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) · [`InboxView`](./inbox-view.md) · [`TreeView`](./tree-view.md) — sibling views
+- [How-to: Render a backend response with DataViews](../how-to/data-views-from-backend-response.md)

package/docs/components/table-view.md

@@ -0,0 +1,131 @@
+---
+title: TableView
+description: Standalone table view for DataViews — sortable columns, row selection, and an integrated filter panel. Use inside DataViewsLayout (tab mode) or directly in Composable Mode.
+group: Data Display
+keywords: [data-views, table-view, table, sortable, columns, selection, filter, composable, dynamic-data, fields]
+---
+
+# TableView
+
+> The table renderer behind `DataViewsLayout`'s "List" tab. In tab mode the layout renders it for you. Render it directly only in **Composable Mode** (custom layouts), wiring it with `useDataViewsState`.
+
+## Installation
+
+Part of `torch-glare`. Ships with the `DataViews` folder when you run `npx torch-glare add DataViews` — no separate install. It depends on the shared `Card`, `Checkbox`, and `Table` components plus the colocated `FilterPanel`.
+
+## Import
+
+```tsx
+import { TableView, useDataViewsState } from "torch-glare"
+import type { TableViewProps, FieldConfig } from "torch-glare"
+```
+
+## When to use it directly
+
+| Situation | Use |
+|---|---|
+| You want the standard tabbed multi-view UI | `DataViewsLayout` — it mounts `TableView` for you. Don't render this yourself. |
+| You want a custom layout (e.g. table beside a kanban) | Render `TableView` directly with state from `useDataViewsState`. |
+| You only ever need a table and nothing else | Render `TableView` directly, or just use the simpler [`Table`](./table.md) / [`DataTable`](./data-table.md). |
+
+## Composable Mode example
+
+`TableView` is controlled — it does not own field detection or config. Pull those from `useDataViewsState` (which auto-detects fields and columns from your data) and pass them down.
+
+```tsx
+import { TableView, useDataViewsState } from "torch-glare"
+import type { FieldConfig } from "torch-glare"
+
+const employees = [
+  { id: 1, name: "Ada Lovelace", role: "Engineer", salary: 120000, joinDate: "2024-04-12" },
+  { id: 2, name: "Linus Torvalds", role: "Engineer", salary: 145000, joinDate: "2023-09-01" },
+]
+
+const fields: FieldConfig[] = [
+  { path: "name", label: "Name", type: "text" },
+  { path: "role", type: "text", filterable: true },
+  { path: "salary", type: "currency", currency: "USD" },
+  { path: "joinDate", type: "date-format", dateFormat: "YYYY-MM-DD" },
+]
+
+function EmployeesTable() {
+  const state = useDataViewsState({ data: employees, fields })
+  return (
+    <TableView
+      data={state.flatItems}
+      fields={state.resolvedFields}
+      config={state.config}
+      onSortChange={(sortBy, sortOrder) =>
+        state.setConfig({ ...state.config, sortBy, sortOrder })
+      }
+      filterState={state.filterState}
+      onFilterChange={state.setFilterState}
+    />
+  )
+}
+```
+
+### Hide the inline filter panel
+
+```tsx
+<TableView
+  data={state.flatItems}
+  fields={state.resolvedFields}
+  config={state.config}
+  showFilters={false}
+/>
+```
+
+### Controlled sorting
+
+`TableView` does not sort internally — it calls `onSortChange` and reads the
+active sort from `config.sortBy` / `config.sortOrder`. Wire it to your config
+state (or your backend) to make headers interactive.
+
+```tsx
+<TableView
+  data={rows}
+  fields={fields}
+  config={{ defaultView: "table", sortBy: "name", sortOrder: "asc" }}
+  onSortChange={(sortBy, sortOrder) => refetch({ sortBy, sortOrder })}
+/>
+```
+
+## API Reference
+
+### `TableViewProps`
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `data` | `DynamicRecord[]` | — (required) | Flat array of rows to render. In composable mode pass `state.flatItems`. |
+| `fields` | `FieldConfig[]` | — (required) | Field map controlling which columns render and how cells format. Pass `state.resolvedFields` for auto-detected fields. |
+| `config` | `ViewConfig` | — (required) | View config. `sortBy` / `sortOrder` drive the active sort indicator. |
+| `columns` | `DynamicColumnConfig[]` | `undefined` | Explicit column overrides (visibility/order). Usually derived from `fields`. |
+| `onDataUpdate` | `(data: DynamicRecord[]) => void` | `undefined` | Called when row data changes (e.g. inline selection). |
+| `onSortChange` | `(sortBy: string, sortOrder: "asc" \| "desc") => void` | `undefined` | Fires on header click. When omitted, headers are not sortable. |
+| `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. When provided, the view is controlled. |
+| `showFilters` | `boolean` | `true` | Show the integrated filter panel. |
+
+`DynamicColumnConfig`, `DynamicFilterConfig`, `FilterState`, and `FieldConfig`
+share the same shapes documented in
+[`DataViewsLayout`](./data-views-layout.md#api-reference).
+
+## Accessibility
+
+- Built on the accessible [`Table`](./table.md) primitive (semantic `<table>` markup, sortable headers).
+- Row selection uses `TableCheckbox` with proper labelling.
+- Filter checkboxes carry labels and `htmlFor` linkage.
+
+## Theming
+
+Uses only `*-presentation-*` design tokens. Wrap with `ThemeProvider` or pass a
+`theme` to the parent `DataViewsLayout` to control the color scheme.
+
+## Related
+
+- [`DataViewsLayout`](./data-views-layout.md) — the tabbed multi-view container that renders this for you
+- [`KanbanView`](./kanban-view.md) · [`InboxView`](./inbox-view.md) · [`TreeView`](./tree-view.md) — the sibling views
+- [`Table`](./table.md) / [`DataTable`](./data-table.md) — lower-level table components
+- [How-to: Render a backend response with DataViews](../how-to/data-views-from-backend-response.md)

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.4",
+  "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"

package/apps/lib/components/DataViews/ARCHITECTURE.md

@@ -1,439 +0,0 @@
-# DataViews — Architecture & Component Map
-
-Internal reference for the DataViews feature. Use this when changing UI, debugging, or syncing with the designer.
-
-**Demo route:** `/data-views` (in `apps/app/data-views/page.tsx`)
-**Library root:** `apps/lib/components/DataViews/`
-
----
-
-## 1. What is DataViews?
-
-A composable multi-view layout. One backend response (array of records) renders as any combination of **Table**, **Kanban**, **Inbox**, **Tree** — chosen per-screen via a `views` prop. Filters and the settings cog are togglable.
-
-```tsx
-<DataViewsLayout
-  title="Orders"
-  data={orders}
-  fields={[
-    { path: "status", type: "enum-badge", variants: { Pending: "yellow", Shipped: "blue" }, filterable: true },
-    { path: "total",  type: "currency", currency: "USD", filterable: true },
-  ]}
-  views={{ table: true, kanban: true }}   // only these tabs render
-  showFilters
-  showSettings
-/>
-```
-
----
-
-## 2. Layout vs. Components vs. Built-ins
-
-### 🟦 The Layout — `DataViewsLayout`
-
-The **frame**. Orchestrator, not a UI piece on its own.
-
-Owns:
-- Page header (title + description)
-- View-switcher tab bar
-- Settings cog button
-- Decision of which view to render
-- Decision of whether to show filter panel / settings panel
-
-Does **not** render the filter panel or settings panel directly — it passes `showFilters` down to each view, and toggles `SettingsPanel` on the side.
-
-### 🟩 The DataViews Components (new — 6 total)
-
-| Component | File | Role |
-|---|---|---|
-| `DataViewsLayout` | `DataViewsLayout.tsx` | The frame (header + tabs + settings toggle) |
-| `TableView` | `TableView.tsx` | Sortable table + search + optional filter panel |
-| `KanbanView` | `KanbanView.tsx` | Drag-and-drop board grouped by an enum-badge field |
-| `InboxView` | `InboxView.tsx` | Three-pane mail-style list (filters \| list \| detail) |
-| `TreeView` | `TreeView.tsx` | Two-pane explorer (tree sidebar + right pane) |
-| `FilterPanel` | `FilterPanel.tsx` | Left-sidebar filter panel (used by Table/Inbox/Tree) |
-| `SettingsPanel` | `SettingsPanel.tsx` | Right-sidebar configurator (column toggles + sort + view-specific settings) |
-
-### 🟨 Built-ins (existing torch-glare components, reused)
-
-These already exist in glare and were not modified for this feature:
-
-- `Badge` — status/priority chips (uses `color` + `badgeStyle: "solid" | "subtle"`)
-- `Button` — Settings cog, action buttons, drawer trigger
-- `Card`, `CardHeader`, `CardContent` — Kanban cards, Inbox detail pane
-- `Checkbox` — table row select + filter list checkboxes
-- `InputField` — the search bar
-- `Avatar`, `AvatarFallback`, `AvatarImage` — inbox sender avatars
-- `Switch` — settings panel toggles (column visibility, show filters)
-- `Divider` — separators in panels (was `Separator` in source)
-- `Label` — filter / setting labels
-- `RadioGroup`, `Radio` — Kanban groupBy picker in settings
-- `Table`, `TableHeader`, `TableBody`, `TableHead`, `TableRow`, `TableCell`, `TableCheckbox` — the actual `<table>` primitive
-- `TabFormItem` — view-switcher tabs (top variant) + inbox sidebar chips (side variant)
-- `Tooltip` — *(available, not currently mounted)*
-- `Drawer` (from `vaul`) — mobile tree drawer
-- Radix `Popover` — date-range filter popover
-- Radix `Slider` — numeric range filter
-
----
-
-## 3. The Layout Structure
-
-```
-┌──────────────────────────────────────────────────────────────────────┐
-│ DataViewsLayout root <div class="bg-body-primary"> (theme-aware)     │
-├──────────────────────────────────────────────────────────────────────┤
-│ Header (showTitle)                                                   │
-│  ├── Title + description (left)                                      │
-│  └── View tabs (TabFormItem×N) + Settings button   (right)           │
-├──────────────────────────────────────────────────────────────────────┤
-│ main (flex row, overflow-hidden)                                     │
-│  ├── Active view (one of):                                           │
-│  │    ├── TableView      [FilterPanel | table+search]                │
-│  │    ├── KanbanView     [columns of cards]                          │
-│  │    ├── InboxView      [filter+sidebar | list | detail pane]       │
-│  │    └── TreeView       [tree sidebar | FilterPanel | right pane]   │
-│  │                                                                   │
-│  └── SettingsPanel (slides in from right when cog clicked)           │
-└──────────────────────────────────────────────────────────────────────┘
-```
-
-### Why filters live **inside** each view, not in the layout
-
-- **Kanban** intentionally has no filter panel (boards rarely do)
-- **Tree** puts the filter panel **between** the tree sidebar and the right pane
-- **Inbox** puts the filter panel **inside** its own left sidebar (mixed with starred/unread/priority chips)
-- **Table** puts the filter panel at the far left, like a standard list page
-
-Each view decides where filters go in its own internal grid. The layout just passes down `showFilters` as a boolean. Per-view `showFilters` prop also exists on each view component for composable mode.
-
----
-
-## 4. Composable mode (no tabs)
-
-When you want a custom layout (e.g. Table on the left, Kanban on the right), bypass `DataViewsLayout` and compose the views directly using the shared state hook:
-
-```tsx
-import { TableView, KanbanView, FilterPanel, useDataViewsState } from "@/components/DataViews"
-
-const state = useDataViewsState({ data, fields })
-
-return (
-  <div className="grid grid-cols-2 gap-4 h-screen">
-    <TableView   {...state} showFilters={false} />
-    <KanbanView  {...state} groupByField="status" />
-  </div>
-)
-```
-
-`useDataViewsState` (`apps/lib/hooks/useDataViewsState.ts`) owns: filter state, sort state, field detection, column visibility config, tree shape detection, enabled-views resolution.
-
----
-
-## 5. Data flow
-
-```
-Backend → data: DynamicRecord[] (array of plain objects)
-           │
-           ▼
-       FieldConfig[] (declarative field map, optional)
-           │
-           ▼
-   useDataViewsState ──► detectFields() ─► merges with user fields
-           │                                          │
-           ▼                                          ▼
-     flatItems (tree → flat for non-tree views)  resolvedFields
-           │
-           ▼
-       active view ──► FilterPanel (if enabled)
-           │            └─► filterState (controlled or internal)
-           ▼
-       renderField() per cell → torch-glare Badge / Avatar / etc.
-```
-
-### Where state lives
-
-| State | Owner | Notes |
-|---|---|---|
-| `currentView` | `useDataViewsState` | View tab selection |
-| `config` (sort, columns, kanbanGroupBy) | `useDataViewsState` | Single source of truth for sort + column visibility |
-| `items` | `useDataViewsState` | Mutable copy of `data` (kanban drag-drop edits this) |
-| `filterState` | `useDataViewsState` OR consumer | Controlled when `onFilterChange` is passed |
-| `selectedItem` | Per view | Inbox + Tree pick their own |
-| `expanded`, `selectedId` | TreeView | Tree-only |
-| `searchQuery` | TableView / InboxView | Local |
-| `showSettingsPanel` | `DataViewsLayout` | Toggled by cog button |
-
----
-
-## 6. Utility files
-
-Located in `apps/lib/utils/dataViews/`. Pure data — no React UI imports.
-
-| File | Purpose |
-|---|---|
-| `pathUtils.ts` | `getByPath`, `setByPath`, `matchesFilterValues`, `formatPathLabel` — dot-path traversal & filter matching |
-| `fieldUtils.ts` | `detectFields`, `mergeFields`, `inferFieldType`, `resolveInboxConfig`, `visibleFields` — declarative field API |
-| `columnUtils.ts` | `detectColumns`, `mergeColumns` — legacy column config (kept for back-compat) |
-| `rangeUtils.ts` | `computeNumericExtremes`, `inferStep`, `presetToFilterValue`, `resolvePresets` — numeric/date range filters |
-| `treeUtils.ts` | `autoDetectTreeShape`, `buildTree`, `pruneTree`, `flattenAll` — hierarchy primitives |
-| `nestedDataUtils.tsx` | `renderDetailView`, `renderNestedObject`, `isPlainObject`, `isCurrencyField` — nested-object detail rendering |
-
-The only non-pure one is `nestedDataUtils.tsx` because it returns JSX for the inbox detail pane.
-
----
-
-## 7. Types (`types.ts`)
-
-Key types exported from `apps/lib/components/DataViews/types.ts`:
-
-| Type | Shape |
-|---|---|
-| `DynamicRecord` | `Record<string, any>` — any backend object |
-| `ViewType` | `"table" \| "kanban" \| "inbox" \| "tree"` |
-| `ViewVisibility` | `{ table?, kanban?, inbox?, tree?: boolean }` |
-| `FieldConfig` | The declarative field definition (path, type, variants, filterable, etc.) |
-| `FieldType` | 17 renderer keys (text, number, enum-badge, currency, progress-bar, …) |
-| `BadgeVariant` | Internal dataviews badge palette — translated by `badgeAdapter.ts` |
-| `FilterState` | `Record<string, FilterValue>` |
-| `FilterValue` | `string[] \| { kind: "number", min?, max? } \| { kind: "date", from?, to? }` |
-| `ViewConfig` | `defaultView, tableColumns, kanbanGroupBy, showFilters, showPreviewPane, sortBy, sortOrder` |
-| `InboxConfig` | `starredField, readField, attachmentField, priorityField, titlePath, previewPath` |
-| `TreeConfig` | `childrenField, parentField, idField, nodeLabel, defaultExpanded, defaultRightPane` |
-
----
-
-## 8. Field types (renderers)
-
-Defined in `fieldRenderers.tsx`. Map of `FieldType` → JSX renderer:
-
-| `type` | What it renders | Key field config props |
-|---|---|---|
-| `text` | Plain string | — |
-| `number` | Tabular numeric | — |
-| `date` | Raw date string | — |
-| `date-format` | `Intl.DateTimeFormat`-style or token-based | `dateFormat: "YYYY-MM-DD"` or `Intl.DateTimeFormatOptions` |
-| `boolean` | Yes/No Badge | `trueVariant`, `falseVariant`, `trueLabel`, `falseLabel` |
-| `currency` | `Intl.NumberFormat` currency | `currency: "USD"` or `{ symbol, locale, decimals, code }` |
-| `number-format` | `Intl.NumberFormat` formatted | `format: Intl.NumberFormatOptions` |
-| `enum-badge` | Single colored badge | `variants: { Value: "green" \| "yellow" \| ... }` |
-| `badge-array` | Row of badges with overflow `+N` | `variant`, `limit` |
-| `progress-bar` | Horizontal bar with % | `thresholds: [warn, ok]` |
-| `star-rating` | Filled-star row | `max` (default 5) |
-| `icon-text` | Icon + text | `icon` (lucide name or emoji), `iconPosition` |
-| `two-line` | Bold primary + small secondary | `secondaryPath` (dot-path) |
-| `avatar` | torch-glare Avatar | `fallbackPath` (for initials) |
-| `link` | `<a>` with mailto/tel/url | `linkType` |
-| `image` | `<img>` thumbnail | — |
-| `hidden` | Renders nothing | — |
-
-Auto-inference rules live in `inferFieldType()` (fieldUtils.ts):
-- `status` / `priority` keys → `enum-badge`
-- `email` / `phone` / `url` / `website` → `link`
-- `tags` / `labels` → `badge-array`
-- `date` / `time` suffixes → `date-format`
-- `salary` / `price` / `cost` / `amount` / `pay` / `fee` (or value smells like currency) → `currency`
-- `rating` / `score` (and value ≤ 5) → `star-rating`
-- ISO date strings → `date-format`
-- Arrays → `badge-array`
-- Booleans → `boolean`
-
-The escape hatch: `field.render = (value, row) => <YourJSX />` always wins.
-
----
-
-## 9. Badge adapter (`badgeAdapter.ts`)
-
-The dataviews source used its own `BadgeVariant` enum (`green`, `greenLight`, `redOrange`, `bluePurple`, `navy`, etc.) that pre-dates torch-glare's current Badge API.
-
-torch-glare Badge uses `color` (gray/slate/red/orange/yellow/green/ocean/blue/purple/rose) + `badgeStyle` (solid/subtle).
-
-`resolveBadgeVariant(variant)` translates between the two. **Default style is `subtle`** to match glare's library default. Variants ending in `Light` or `navy` / `bluePurple` / `cocktailGreen` explicitly request solid.
-
-Want to change badge defaults globally? → edit `badgeAdapter.ts`.
-Want per-field control? → it could be exposed on `FieldConfig` as a new `badgeStyle?: "solid" | "subtle"` field (not done yet — propose it before adding).
-
----
-
-## 10. Styling & theming
-
-### Background tokens used
-
-| Surface | Token | Dark | Light |
-|---|---|---|---|
-| Page | `bg-background-presentation-body-primary` | `#252729` | `#F0F0F0` |
-| Side panels / Kanban column headers | `bg-background-presentation-body-overlay-primary` | `#1C1D1F` | `#F0F0F0` |
-| Subtle fills (chips, drop zones) | `bg-background-presentation-form-field-primary` | `#1C1D1F` | white-ish |
-
-**Do not use `bg-background-presentation-global-*`** — those tokens don't exist in this design system. They were inherited from the original data-views source and resolve to nothing. The Tailwind classes still validate but render as transparent. We swapped them all out; if you see one come back, it's a regression.
-
-### Borders / text
-
-| Token | Use |
-|---|---|
-| `border-border-presentation-global-primary` | Panel borders, dividers |
-| `text-content-presentation-global-primary` | Primary text |
-| `text-content-presentation-global-secondary` | Secondary text |
-| `text-content-presentation-global-tertiary` | Muted labels |
-| `text-content-presentation-action-primary` | Active state text |
-| `bg-content-presentation-action-primary` | Active-tab + slider track + selected-mode bg |
-
-These `content-presentation-global-*` tokens **do exist** for text/borders — only the `background-*-global-*` family is missing.
-
-### Theme switching
-
-`DataViewsLayout` accepts `theme?: "dark" | "light" | "default"` and applies it via `data-theme={theme}`. Without it, the component inherits the nearest ancestor's `data-theme` (set by `ThemeProvider`).
-
----
-
-## 11. Tree view internals
-
-`TreeView.tsx` has the most complex layout. Worth a separate note.
-
-**Three columns** in desktop mode:
-1. **Tree sidebar** (`TreeSidebar`) — the tree itself
-2. **Filter panel** (`FilterPanel`) — only when `showFilters && hasFilterableFields`
-3. **Right pane** — toggles between two modes via the toolbar:
-   - **Table mode** (default) — `<TableView>` over the selected node + descendants
-   - **Details mode** — single-record detail view with nested-object rendering
-
-The tree owns the filter state; the embedded `TableView` is told `showFilters={false}` so it doesn't render its own filter panel.
-
-**Mobile** collapses the tree sidebar into a left-edge drawer (`TreeDrawer` via `vaul`). The right pane gets a hamburger trigger.
-
-**Auto-detection**: if neither `treeConfig.childrenField` nor `treeConfig.parentField` is set, the view inspects the first record:
-- nested: `children`, `items`, `kids`, `subItems`, `nodes`
-- flat: `parentId`, `parent_id`, `parent`, `managerId`, `manager`
-
-If nothing matches and no `views.tree` override, the Tree tab auto-hides.
-
----
-
-## 12. Filter panel rules
-
-A field becomes filterable when any of:
-1. `field.filterable === true` (explicit opt-in)
-2. `type` is `enum-badge`, `boolean`, `badge-array`, or `icon-text` (auto)
-3. type is text with ≤10 unique values (heuristic fallback)
-
-Numeric / date fields **require explicit `filterable: true`** — they get range sliders / date pickers respectively.
-
-The panel renders three filter kinds:
-- **Categorical** — checkbox list (multi-select OR semantics)
-- **Numeric range** — Radix slider + min/max inputs + preset chips
-- **Date range** — Radix popover with `react-day-picker` + preset chips (`Today`, `Last 7 days`, `Last 30 days`, `This year`)
-
-Filter state shape:
-```ts
-type FilterValue =
-  | string[]                                          // categorical
-  | { kind: "number"; min?: number; max?: number }    // numeric range
-  | { kind: "date";   from?: string;  to?: string }   // date range, ISO YYYY-MM-DD
-```
-
----
-
-## 13. Settings panel sections
-
-`SettingsPanel.tsx` renders sections conditionally based on `currentView`:
-
-| Section | When | What it controls |
-|---|---|---|
-| General → Show Filters | always | `config.showFilters` |
-| Table Columns | `currentView === "table"` | Column visibility (Switch) + reorder (HTML5 DnD) |
-| Kanban Grouping | `currentView === "kanban"` | Radio over enum-badge fields → `kanbanGroupBy` |
-| Inbox Layout → Show Preview Pane | `currentView === "inbox"` | `config.showPreviewPane` |
-| Sort | always (if columns exist) | Per-column three-state: none/asc/desc |
-
----
-
-## 14. CLI distribution
-
-The DataViews folder + utils folder + hooks are **not yet** distributable via `torch-glare add <Component>` — the existing CLI scans top-level `.tsx` files only. Adding `DataViews/` as a unit requires extending the CLI to recognize folder-based components and copy:
-- `apps/lib/components/DataViews/` (whole folder)
-- `apps/lib/utils/dataViews/` (whole folder)
-- `apps/lib/hooks/useDataViewsState.ts`
-- `apps/lib/hooks/useIsMobile.ts`
-
-…plus running `getDependenciesAndInstallNestedComponents` recursively across all those files to install any missing peer deps (`@radix-ui/react-slider`, `react-day-picker`, `vaul`).
-
----
-
-## 15. MCP documentation
-
-Public-facing docs live in `mcp/docs/`:
-
-- `mcp/docs/components/data-views-layout.md` — main API reference
-- `mcp/docs/components/table-view.md`
-- `mcp/docs/components/kanban-view.md`
-- `mcp/docs/components/inbox-view.md`
-- `mcp/docs/components/tree-view.md`
-- `mcp/docs/how-to/data-views-from-backend-response.md` — recipe guide for consumers
-
-Registered in `mcp/docs/llms-manifest.json` under `components.dataDisplay`. Update versions there when bumping.
-
----
-
-## 16. Common change checklist
-
-When updating UI on this feature, touch in this order:
-
-1. **Token swap** — never use `*-global-*` backgrounds. Check the table in §10.
-2. **Badge** — use `resolveBadgeVariant()` in the adapter, don't bypass it. If you need a new variant, add it to both `BadgeVariant` type (types.ts) and the switch in `badgeAdapter.ts`.
-3. **Field renderer** — add new field types in `fieldRenderers.tsx` + register in the `RENDERERS` lookup table at the bottom + extend `FieldType` in types.ts.
-4. **Layout change** — if it touches all four views, update each view's root container individually; the layout doesn't own view chrome.
-5. **State change** — extend `useDataViewsState` first, then thread the new field through `DataViewsLayout` props.
-6. **Docs** — update the relevant `.md` in `mcp/docs/components/` AND `mcp/docs/how-to/data-views-from-backend-response.md` if it changes the consumer-facing API.
-
----
-
-## 17. File inventory (quick reference)
-
-```
-apps/lib/components/DataViews/
-├── ARCHITECTURE.md          ← this file
-├── DataViewsLayout.tsx      ← the frame
-├── TableView.tsx
-├── KanbanView.tsx
-├── InboxView.tsx
-├── TreeView.tsx
-├── FilterPanel.tsx
-├── SettingsPanel.tsx
-├── fieldRenderers.tsx       ← per-type JSX
-├── badgeAdapter.ts          ← BadgeVariant → glare Badge props
-├── types.ts                 ← all shared types
-├── index.ts                 ← public barrel
-├── filters/
-│   ├── DateRangePopover.tsx
-│   ├── PresetChips.tsx
-│   └── RangeSliderWithInputs.tsx
-└── tree/
-    ├── TreeDrawer.tsx
-    ├── TreeNodeRow.tsx
-    └── TreeSidebar.tsx
-
-apps/lib/utils/dataViews/
-├── pathUtils.ts
-├── fieldUtils.ts
-├── columnUtils.ts
-├── rangeUtils.ts
-├── treeUtils.ts
-└── nestedDataUtils.tsx
-
-apps/lib/hooks/
-├── useDataViewsState.ts     ← shared state machine for composable mode
-└── useIsMobile.ts           ← <768px detection
-
-apps/app/data-views/
-└── page.tsx                 ← demo page, /data-views route
-
-mcp/docs/components/
-├── data-views-layout.md
-├── table-view.md
-├── kanban-view.md
-├── inbox-view.md
-└── tree-view.md
-
-mcp/docs/how-to/
-└── data-views-from-backend-response.md
-```