torch-glare 2.1.2 → 2.1.3

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

@@ -0,0 +1,204 @@
+---
+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
+
+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 `Radio`, `Switch`, `Label`, `FilterPanel`, and a colocated internal
+`PanelControls` file (see "Internal: PanelControls" below).
+
+## Import
+
+```tsx
+import { DataViewsConfigPanel } from "torch-glare"
+import type { DataViewsConfigPanelProps } from "torch-glare"
+```
+
+## 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,
+  TableView,
+  useDataViewsState,
+} from "torch-glare"
+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. |
+
+## 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 `PanelControls.tsx`. Keep values 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`, `#626467`, `#0AC713`). These are intentional Figma values, not tokens. |
+
+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

@@ -0,0 +1,270 @@
+---
+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
+
+The component is part of `torch-glare`. It depends on `@radix-ui/react-slider`, `react-day-picker`, `lucide-react`, and `vaul` (all already vendored by the library). No extra install needed.
+
+## Import
+
+```tsx
+import { DataViewsLayout } from "torch-glare"
+import type { FieldConfig, ViewVisibility } from "torch-glare"
+```
+
+## 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. |
+| `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. |
+| `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`
+
+### `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 { TableView, KanbanView, FilterPanel, useDataViewsState } from "torch-glare"
+
+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 `TabFormItem` (button-based, full keyboard support via Tab/Enter/Space).
+- 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
+- [How-to: Render a backend response with DataViews](../how-to/data-views-from-backend-response.md) — recipes by data shape.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "torch-glare",
-  "version": "2.1.2",
+  "version": "2.1.3",
   "type": "module",
   "license": "MIT",
   "files": [