torch-glare 2.1.4 → 2.1.7

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)