torch-glare 2.4.4 → 2.5.0

package/docs/components/data-views-config-panel.md

@@ -1,208 +0,0 @@
----
-title: DataViewsConfigPanel
-description: Slide-in side panel for DataViews — Saved View list, show/hide & drag-reorder columns, default sort, and a Filters tab. Used automatically by DataViewsLayout, or rendered standalone in composable mode.
-group: Data Display
-keywords: [data-views, config panel, config-panel, settings panel, saved view, saved-view, column visibility, reorder columns, default sort, filters tab, side panel, dark panel]
----
-
-# DataViewsConfigPanel
-
-> The settings/filters side panel for DataViews. In tab mode `DataViewsLayout`
-> mounts and animates this for you. Render it yourself only in composable mode
-> (custom layouts) or when you need real Saved View persistence.
-
-## 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 DataViewsConfigPanel
-```
-
-`add` also copies any components, hooks, and utilities that `DataViewsConfigPanel` depends on.
-
-## Import
-
-Import from your project's local path — the alias configured in `glare.json` (e.g. `@/*`):
-
-```tsx
-import { DataViewsConfigPanel } from "@/components/DataViewsConfigPanel";
-```
-
-## When to use it directly
-
-| Situation | Use |
-|---|---|
-| Standard tabbed dashboard | **Don't.** Use `DataViewsLayout` — it renders this panel for you via the header settings cog. |
-| Custom composed layout (e.g. Table + Kanban side by side) | Render `DataViewsConfigPanel` yourself alongside `useDataViewsState`. |
-| You need working Saved View persistence | Render it yourself and pass `savedViews` + `onSavedViewChange` + `onSaveNewView` wired to your store. (Not possible through `DataViewsLayout` today — see "Saved View status".) |
-
-## Standalone Example (composable mode)
-
-```tsx
-import { DataViewsConfigPanel } from "@/components/DataViewsConfigPanel";
-import { TableView } from "@/components/TableView";
-import { useDataViewsState } from "@/hooks/useDataViewsState";
-import { useState } from "react"
-
-function CustomScreen({ data, fields }) {
-  const s = useDataViewsState({ data, fields })
-  const [panelOpen, setPanelOpen] = useState(true)
-
-  // Your own saved-view persistence:
-  const [savedViews] = useState([
-    { id: "all", label: "All Records" },
-    { id: "mine", label: "Assigned to Me" },
-  ])
-  const [activeView, setActiveView] = useState("all")
-
-  return (
-    <div className="flex h-screen gap-2 bg-black p-2">
-      <div className="min-w-0 flex-1">
-        <TableView
-          data={s.flatItems}
-          fields={s.resolvedFields}
-          config={s.config}
-          filterState={s.filterState}
-          onFilterChange={s.setFilterState}
-          showFilters={false}
-        />
-      </div>
-
-      {panelOpen && (
-        <DataViewsConfigPanel
-          state="open"
-          config={s.config}
-          onConfigChange={s.setConfig}
-          onClose={() => setPanelOpen(false)}
-          currentView={s.currentView}
-          fields={s.resolvedFields}
-          data={s.flatItems}
-          filterState={s.filterState}
-          onFilterChange={s.setFilterState}
-          savedViews={savedViews}
-          activeSavedView={activeView}
-          onSavedViewChange={setActiveView}
-          onSaveNewView={() => {
-            /* open your "name this view" modal, then persist */
-          }}
-        />
-      )}
-    </div>
-  )
-}
-```
-
-## API Reference
-
-### `DataViewsConfigPanelProps`
-
-| Prop | Type | Required | Description |
-|---|---|---|---|
-| `config` | `ViewConfig` | ✅ | Current view config. `tableColumns` drives the column list; `sortBy`/`sortOrder` drive Default Sort. |
-| `onConfigChange` | `(config: Partial<ViewConfig>) => void` | ✅ | Called with a partial patch when columns are toggled/reordered or a sort field is picked. Merge it into your config state. |
-| `onClose` | `() => void` | ✅ | Fires when the panel's close (X) button is pressed. |
-| `currentView` | `ViewType` | ✅ | **Currently unused inside the panel body** (declared on the prop type but not read). Still required by the type; pass the active view for forward-compatibility. |
-| `fields` | `FieldConfig[]` | ✅ | Same field map you pass to the views. Drives the Filters tab and the column labels. |
-| `data` | `DynamicRecord[]` | ✅ | Flat records — passed to the Filters tab (`FilterPanel`) to compute filter options. |
-| `filterState` | `FilterState` | ✅ | Current filter values. The Filters tab reads/writes this. |
-| `onFilterChange` | `(filters: FilterState) => void` | ✅ | Called with the full next filter object on any filter change (and on "Clear all" → `{}`). |
-| `filterConfig` | `DynamicFilterConfig[]` | — | Optional explicit filter config forwarded to `FilterPanel`. |
-| `savedViews` | `{ id: string; label: string }[]` | — | Saved View radio list. Defaults to a single `{ id: "default", label: "Default View" }`. |
-| `activeSavedView` | `string` | — | Controlled selected saved-view id. If supplied, the panel is controlled (see "Controlled vs uncontrolled"). |
-| `onSavedViewChange` | `(id: string) => void` | — | Called when a saved-view radio is selected. Required for controlled behaviour. |
-| `onSaveNewView` | `() => void` | — | Called when "Save a New View" is clicked. No-op if omitted. |
-| `state` | `"open" \| "closed"` | — | Drives the slide/opacity animation. Default `"open"`. Keep the panel mounted through the close animation, then unmount. |
-
-> Note: `DataViewsConfigPanelProps` is a plain `type` (not extending HTML
-> attributes). There is no `className`/`theme` passthrough — the panel is
-> intentionally always-dark chrome (see "Theming").
-
-### Controlled vs uncontrolled Saved View
-
-The Saved View list follows the standard controlled/uncontrolled pattern:
-
-- **Controlled** — pass both `activeSavedView` and `onSavedViewChange`. You own
-  the selected id; the panel reflects it.
-- **Uncontrolled** — omit them. The panel keeps internal state (initialised to
-  `savedViews[0]?.id`) so the radios are still interactive, but nothing
-  persists and it resets on unmount.
-
-```tsx
-// Controlled
-<DataViewsConfigPanel activeSavedView={id} onSavedViewChange={setId} ... />
-
-// Uncontrolled (still clickable, local only)
-<DataViewsConfigPanel savedViews={views} ... />
-```
-
-### Saved View status
-
-Through `DataViewsLayout` (tab mode) the four `savedView*` props are **not
-forwarded**, so Saved View there is presentational only. To get real behaviour,
-render `DataViewsConfigPanel` yourself (example above) or extend the layout
-(below).
-
-## Sections
-
-| Section | Backed by | Behaviour |
-|---|---|---|
-| Saved View | `savedViews` / `activeSavedView` | Radio list + "Save a New View" button. |
-| Table Columns | `config.tableColumns` | Green `Switch` per column toggles `visible`; rows are drag-reorderable (HTML5 DnD) and patch `order`. |
-| Default Sort | `config.sortBy` | Single-choice radio; selecting sets `sortBy`. Direction stays on `config.sortOrder`. |
-| Filters tab | `filterState` + `fields` | Renders `FilterPanel` restyled full-width/transparent. Categorical fields render as checkbox/radio lists, or a `SearchableSelect` dropdown when a field sets `filterVariant: "searchable-select"`. |
-
-## Internal: PanelControls
-
-The panel's radio rows and column toggle are a colocated, **non-exported**
-file: `DataViews/PanelControls.tsx` (`RadioRow`, `DataViewsSwitch`). They are
-deliberately **not** shared library components — the panel chrome is always
-dark and hardcodes Figma hex values, which conflicts with the design-system
-token / `data-theme` convention used by public components.
-
-You normally never import these. They ship automatically because the CLI
-copies the entire `DataViews/` folder recursively, so the relative import
-`./PanelControls` resolves in the consumer's copy with no registry wiring.
-
-If you need a themed radio elsewhere, use the shared `Radio` component instead
-— not `PanelControls`.
-
-## Extending the panel
-
-Common changes and where to make them:
-
-| You want to… | Do this |
-|---|---|
-| Make Saved View work through `DataViewsLayout` | Add `savedViews` / `activeSavedView` / `onSavedViewChange` / `onSaveNewView` to `DataViewsLayoutProps`, hold them in layout state (or accept from the host), and forward them to `<DataViewsConfigPanel>` at its render site in `DataViewsLayout.tsx`. |
-| Add a new Config section | Add a new block inside the Config. tab in `DataViewsConfigPanel.tsx`, backed by a `config.*` field so `onConfigChange` persists it. |
-| Restyle a radio/toggle | Edit the radio ring in `DataViewRadio.tsx` (the `RadioRow` in `PanelControls.tsx` just wraps it) or the switch in `PanelControls.tsx`. Keep the hardcoded hex matching the Figma spec; do not swap in the shared `Radio`/`Label` (they impose theming/layout that fights the dark panel — this was deliberate). |
-| Change the dark chrome | The root forces `data-theme="dark"` and uses hardcoded hex (`#1C1D1F`, `#252729`, `#005ECC`, `#0075FF`, `#626467`, `#0AC713`). These are intentional Figma values, not tokens — the radio/checkbox rings hardcode them (`#626467` border, `rgba(255,255,255,0.05)` fill, `#0075FF` selected) so the panel always renders dark regardless of host `data-theme`. |
-
-After any change to the panel docs or component, update this file and rebuild
-the MCP server (`cd mcp && pnpm build`) so the docs the server serves stay in
-sync.
-
-## Accessibility
-
-- Saved View / Default Sort use Radix `RadioGroup`; the whole row is the click
-  target with keyboard support.
-- Column toggles are accessible `Switch`es; reorder is pointer-based HTML5 DnD
-  (provide a non-DnD path if your audience needs keyboard reordering).
-- The close button has `aria-label="Close panel"`; tab buttons expose
-  `aria-pressed`.
-
-## Theming
-
-Intentionally **always dark**. The root sets `data-theme="dark"` so child
-themed components resolve dark tokens even when the host app runs light, and
-the panel-specific chrome uses hardcoded Figma hex values rather than design
-tokens. There is no `theme` prop — this is by design to match the Figma
-"Cun" (#000000) panel spec.
-
-## Related
-
-- [`DataViewsLayout`](./data-views-layout.md) — renders this panel for you in tab mode
-- [`Radio`](./radio.md) — the themed radio to use **outside** this panel
-- [`Switch`](./switch.md) — the shared switch the column toggles wrap

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

@@ -1,291 +0,0 @@
----
-title: DataViewsLayout
-description: Composable multi-view layout that renders any backend response as Table, Kanban, Inbox, and/or Tree, with per-screen selection of which views to show.
-group: Data Display
-keywords: [data-views, layout, table, kanban, inbox, tree, multi-view, filter, switcher, dashboard, dynamic-data, fields]
----
-
-# DataViewsLayout
-
-> One backend response → many UI shapes. Pass an array of records plus a declarative list of fields, then pick which views the screen needs (`{ table: true, kanban: true }`, etc.). Filters and the settings cog are togglable per-screen.
-
-## 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 DataViewsLayout
-```
-
-`add` also copies any components, hooks, and utilities that `DataViewsLayout` depends on.
-
-## Import
-
-Import from your project's local path — the alias configured in `glare.json` (e.g. `@/*`):
-
-```tsx
-import { DataViewsLayout } from "@/components/DataViewsLayout";
-```
-
-## Quick Examples
-
-### 1. All views, auto-detected
-
-Just pass `data` — every primitive field becomes a column, all four views appear, the Tree tab auto-hides if no `children`/`parentId` is found.
-
-```tsx
-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" },
-]
-
-<DataViewsLayout title="Employees" data={employees} />
-```
-
-### 2. Pick specific views only
-
-Use `views` to enable only what this screen needs. Tabs for the others are hidden.
-
-```tsx
-<DataViewsLayout
-  title="Orders"
-  data={orders}
-  views={{ table: true, kanban: true }}   // only Table + Kanban tabs render
-  kanbanGroupBy="status"
-/>
-```
-
-### 3. Declarative fields with badges and filters
-
-```tsx
-const fields: FieldConfig[] = [
-  { path: "id", label: "Order #", type: "number" },
-  { path: "customer", type: "text" },
-  {
-    path: "status",
-    type: "enum-badge",
-    variants: { Pending: "yellow", Shipped: "blue", Delivered: "green" },
-    filterable: true,
-  },
-  { path: "total", type: "currency", currency: "USD", filterable: true },
-  { path: "createdAt", type: "date-format", dateFormat: "YYYY-MM-DD", filterable: true },
-]
-
-<DataViewsLayout
-  title="Orders"
-  data={orders}
-  fields={fields}
-  views={{ table: true, kanban: true }}
-  kanbanGroupBy="status"
-/>
-```
-
-### 4. Disable filters and the settings cog
-
-```tsx
-<DataViewsLayout
-  data={orders}
-  fields={fields}
-  views={{ table: true }}
-  showFilters={false}
-  showSettings={false}
-/>
-```
-
-### 5. Controlled filter state (wire to backend pagination)
-
-```tsx
-const [filterState, setFilterState] = useState<FilterState>({})
-
-useEffect(() => {
-  fetchFromBackend({ filters: filterState }).then(setRows)
-}, [filterState])
-
-<DataViewsLayout
-  data={rows}
-  fields={fields}
-  filterState={filterState}
-  onFilterChange={setFilterState}
-/>
-```
-
-### 6. Hierarchical data
-
-When records carry a `children: []` array (or a `parentId` reference), the Tree tab auto-appears. Override the detection with `treeConfig`.
-
-```tsx
-<DataViewsLayout
-  data={departments}                            // each has children[]
-  treeConfig={{ childrenField: "children", nodeLabel: "name", defaultExpanded: "roots" }}
-  fields={fields}
-/>
-```
-
-### 7. Inbox shape (read/starred/priority)
-
-Inbox auto-detects `isRead`, `isStarred`, `hasAttachment`, `priority`. Override with `inboxConfig`.
-
-```tsx
-<DataViewsLayout
-  data={messages}
-  fields={fields}
-  views={{ inbox: true }}
-  inboxConfig={{ titlePath: "subject", previewPath: "from.name" }}
-/>
-```
-
-## API Reference
-
-### `DataViewsLayoutProps`
-
-| Prop | Type | Default | Description |
-|---|---|---|---|
-| `data` | `DynamicRecord[]` | `[]` | Array of records of any shape. Fields are auto-detected from the first records. |
-| `fields` | `FieldConfig[]` | auto-detected | Declarative field map: `path`, `type`, `filterable`, `variants`, `currency`, etc. |
-| `title` | `string` | `"Data Views"` | Header title (hidden when `showTitle={false}`). |
-| `description` | `string` | `"Unified data visualization across multiple views"` | Subtitle under the title. |
-| `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. |
-| `showFilters` | `boolean` | `true` | Hide the filter panel inside every view. |
-| `showSettings` | `boolean` | `true` | Hide the settings cog + side panel. |
-| `showTitle` | `boolean` | `true` | Hide the header bar entirely. Useful when embedding. |
-| `config` | `Partial<ViewConfig>` | — | Initial config: `defaultView`, `sortBy`, `sortOrder`, etc. |
-| `className` | `string` | — | Forwarded to the root `<div>`. |
-| `theme` | `"dark" \| "light" \| "default"` | — | Applied as `data-theme` on the root. |
-
-### `FieldConfig`
-
-| Prop | Type | Description |
-|---|---|---|
-| `path` | `string` | Dot-path into the record (`"contact.email"`). |
-| `label` | `string` | Display label. Auto-formatted from path tail if omitted. |
-| `type` | `FieldType` | Renderer key (see below). Auto-inferred if omitted. |
-| `visible` | `boolean` | Show in cells. Default `true`. |
-| `order` | `number` | Display order. |
-| `filterable` | `boolean` | Surface this field in the filter panel. The control adapts to the field `type`: categorical fields render checkboxes/radios (or a searchable dropdown via `filterVariant`), numeric fields a range slider, and **date / date-format fields a From + To pair of Glare `DatePicker`s** (two single-date pickers bounding the range). Set `false` to explicitly exclude a field the panel would otherwise auto-detect (e.g. an `id` or `name` with few unique values). |
-| `filterLabel` | `string` | Override the label shown above this field's filter (defaults to `label`). |
-| `filterMode` | `"single" \| "multi"` | Categorical selection mode. `"multi"` (default) renders checkboxes; `"single"` renders radios. |
-| `filterVariant` | `"checkbox" \| "searchable-select"` | Categorical control style. `"checkbox"` (default) is the inline checkbox/radio list; `"searchable-select"` renders a single-select `SearchableSelect` dropdown — useful when a field has many options. Implies single-select. |
-| `filterOptions` | `string[] \| { label: string; value: string }[]` | Explicit option list for the categorical filter (otherwise options are collected from the data). |
-| `variants` | `Record<string, BadgeVariant>` | For `enum-badge`: per-value color map. |
-| `currency` | `string \| CurrencyOptions` | For `currency`: ISO code or `{ symbol, locale, decimals, code }`. |
-| `thresholds` | `[number, number]` | For `progress-bar`: warning/ok thresholds. |
-| `max` | `number` | For `star-rating`: stars displayed. |
-| `dateFormat` | `string \| Intl.DateTimeFormatOptions` | For `date-format`: token like `"YYYY-MM-DD"` or Intl options. |
-| `render` | `(value, row) => ReactNode` | Escape hatch for custom JSX. |
-
-### `FieldType` (built-in renderers)
-
-`text` · `number` · `date` · `date-format` · `boolean` · `currency` · `number-format` · `enum-badge` · `badge-array` · `progress-bar` · `star-rating` · `icon-text` · `two-line` · `avatar` · `link` · `image` · `hidden`
-
-> **`hidden` vs `filterable: false`** — use `type: "hidden"` to drop a field from the UI **entirely** (no column, no column-toggle in the config panel, no filter) while it stays in the data for row identity — e.g. an `id` you key rows by but never want shown. Use `filterable: false` to keep a field as a **column** but remove only its **filter**.
-
-### `BadgeVariant`
-
-`green` · `greenLight` · `cocktailGreen` · `yellow` · `redOrange` · `redLight` · `rose` · `purple` · `bluePurple` · `blue` · `navy` · `gray` · `highlight`
-
-### `ViewVisibility`
-
-```ts
-type ViewVisibility = {
-  table?: boolean
-  kanban?: boolean
-  inbox?: boolean
-  tree?: boolean
-}
-```
-
-## Config & Filters Panel
-
-The settings cog in the header (shown unless `showSettings={false}`) opens a
-slide-in side panel — [`DataViewsConfigPanel`](./data-views-config-panel.md).
-`DataViewsLayout` mounts and animates it for you; you do not render it yourself
-in tab mode. It has two tabs:
-
-| Tab | Section | What it does | Wired through `DataViewsLayout`? |
-|---|---|---|---|
-| **Config.** | Saved View | Radio list of named views + "Save a New View" button. | ❌ **Presentational only.** The layout does not pass `savedViews` / `onSavedViewChange` / `onSaveNewView`, so the panel shows a single fallback "Default View" and selection is local-state only (it does not persist or change `config`). See "Saved View status" below. |
-| **Config.** | Table Columns | Show/hide each column (green `Switch`) and drag-reorder them. | ✅ Reads/writes `config.tableColumns` via the layout's internal config state. |
-| **Config.** | Default Sort | Single-choice radio list that sets `config.sortBy`. | ✅ Writes `config.sortBy` (sort direction stays on `config.sortOrder`). |
-| **Filters** | — | Delegates to `FilterPanel` for the same `fields` you passed. | ✅ Reads/writes the layout's `filterState` (and your `onFilterChange` if controlled). |
-
-### Saved View status (read this before relying on it)
-
-Saved View is currently a **presentational shell**. The props exist on
-`DataViewsConfigPanel` (`savedViews`, `activeSavedView`, `onSavedViewChange`,
-`onSaveNewView`) but `DataViewsLayout` does **not** thread them through. In tab
-mode you therefore cannot supply or persist saved views today — clicking a row
-updates the panel's internal state only and resets on unmount.
-
-To get real saved-view behaviour you have two options:
-
-1. Use **Composable Mode** (below) and render `DataViewsConfigPanel` yourself,
-   passing `savedViews` + `onSavedViewChange` wired to your own persistence.
-2. Extend `DataViewsLayout` to forward the four `savedView*` props down to the
-   panel (see "Extending the panel" in the
-   [`DataViewsConfigPanel` doc](./data-views-config-panel.md)).
-
-This limitation is documented honestly so an agent does not generate code that
-passes `savedViews` to `DataViewsLayout` expecting it to work.
-
-## 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.
-
-```tsx
-import { FilterPanel } from "@/components/FilterPanel";
-import { KanbanView } from "@/components/KanbanView";
-import { TableView } from "@/components/TableView";
-import { useDataViewsState } from "@/hooks/useDataViewsState";
-
-function CustomScreen({ data, fields }: Props) {
-  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}
-        filterState={state.filterState}
-        onFilterChange={state.setFilterState}
-        showFilters={false}
-      />
-      <KanbanView
-        data={state.flatItems}
-        fields={state.resolvedFields}
-        config={state.config}
-        groupByField="status"
-      />
-    </div>
-  )
-}
-```
-
-## Accessibility
-
-- The view-switcher uses [`TabSwitch`](./tab-switch.md) — a segmented `role="tablist"` control (each view a `role="tab"` button, full keyboard support via Tab/Enter/Space). Installing DataViews pulls in `TabSwitch` automatically.
-- Tree rows expose `role="treeitem"` with `aria-expanded` and `aria-selected`.
-- Filter checkboxes carry labels and `htmlFor` linkage.
-- Settings panel buttons have `aria-pressed` for sort direction.
-
-## Theming
-
-The component uses only `*-presentation-*` design tokens. Wrap with `ThemeProvider` or pass `theme="dark" | "light" | "default"` to control color scheme.
-
-## Related
-
-- [`DataViewsConfigPanel`](./data-views-config-panel.md) — the settings/filters side panel (Saved View, columns, sort)
-- [`TableView`](./table-view.md) — standalone table
-- [`KanbanView`](./kanban-view.md) — standalone kanban
-- [`InboxView`](./inbox-view.md) — standalone inbox
-- [`TreeView`](./tree-view.md) — standalone tree
-- [`TabSwitch`](./tab-switch.md) — the segmented view-switcher in the header (reusable on its own)
-- [How-to: Render a backend response with DataViews](../how-to/data-views-from-backend-response.md) — recipes by data shape.

package/docs/components/inbox-view.md

@@ -1,170 +0,0 @@
----
-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
-
-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 InboxView
-```
-
-`add` also copies any components, hooks, and utilities that `InboxView` depends on.
-
-## Import
-
-Import from your project's local path — the alias configured in `glare.json` (e.g. `@/*`):
-
-```tsx
-import { InboxView } from "@/components/InboxView";
-```
-
-## 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 } from "@/components/InboxView";
-import { useDataViewsState } from "@/hooks/useDataViewsState";
-import type { FieldConfig } from "@/components/FieldConfig";
-import type { InboxConfig } from "@/components/InboxConfig";
-
-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)