torch-glare 2.4.4 → 2.5.0

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

@@ -0,0 +1,405 @@
+---
+title: Build a screen with DataViews
+description: The canonical way to build a list screen in TORCH Glare. One dataset as a table, board, inbox or tree behind a shared header, filters and settings rail — with scroll loading, drag and drop, custom cells, custom pane tabs and a view of your own.
+group: how-to
+keywords:
+  [
+    data-views,
+    dataviews,
+    table,
+    board,
+    kanban,
+    inbox,
+    tree,
+    pane,
+    views,
+    filters,
+    panel,
+    saved-views,
+    columns,
+    sort,
+    search,
+    infinite-scroll,
+    virtualization,
+    drag-drop,
+    server-side,
+    query,
+    custom-view,
+    markView,
+  ]
+---
+
+# Build a screen with DataViews
+
+`DataViews` is how a list screen is built in this library: one dataset, several ways to look at it,
+behind a shared header, filter set and settings rail. This guide goes from the smallest useful
+screen to every seam the component has, in the order you are likely to need them.
+
+Every snippet below is lifted from a complete, runnable page, linked at the end of each section —
+so you can read the whole file rather than a fragment. Those pages ship with the docs; see the
+[example index](./examples/index.md).
+
+**Three rules govern everything here.** They are worth reading once before the code.
+
+1. **A part exists because you rendered it.** There is no `views={{ table: true }}` map and no
+   `showFilters` flag. Render `<DataViews.Board/>` and a Board tab appears; wrap it in a condition
+   and it disappears, switching away if it was open.
+2. **It is pure UI.** DataViews never filters, searches, sorts, groups, paginates, builds a tree or
+   mutates a row. It paints the `rows` you hand it, in the order you hand them. Nothing on screen
+   moves until you hand back different data.
+3. **Only the query leaves.** Search, filters, sort, page and page size are one object, reported
+   through `onQueryChange`. Everything else the user can change — which view is showing, what is
+   selected, how columns are arranged — changes nothing but the picture, so the component keeps it.
+
+## 1. The smallest screen
+
+Rows, fields, a header and a table.
+
+```tsx
+"use client";
+
+import { useState } from "react";
+import { useQuery } from "@tanstack/react-query";
+import { DataViews, emptyQuery, queryToParams } from "@/components/DataViews";
+import type { FieldConfig } from "@/components/DataViews";
+
+const FIELDS: FieldConfig[] = [
+  { path: "id", label: "Order #", type: "number" },
+  { path: "customer.name", label: "Customer" },
+  { path: "status", label: "Status", type: "enum-badge",
+    variants: { Pending: "yellow", Shipped: "blue", Delivered: "green" } },
+  { path: "total", label: "Total", type: "currency", currency: "USD" },
+  { path: "createdAt", label: "Created", type: "date-format", dateFormat: "YYYY-MM-DD" },
+];
+
+export default function Orders() {
+  const [query, setQuery] = useState(emptyQuery());
+  const { data, isPending } = useQuery({
+    queryKey: ["orders", query],
+    queryFn: () => fetch(`/api/orders?${queryToParams(query)}`).then((r) => r.json()),
+  });
+
+  return (
+    <div className="h-full p-4">
+      <DataViews
+        rows={data?.rows ?? []}
+        total={data?.total ?? 0}
+        fields={FIELDS}
+        loading={isPending}
+        onQueryChange={setQuery}
+        className="h-full"
+      >
+        <DataViews.Header title="Orders">
+          <DataViews.ViewSwitch />
+          <DataViews.Search />
+          <DataViews.PanelToggle />
+        </DataViews.Header>
+
+        <DataViews.Table selectable />
+      </DataViews>
+    </div>
+  );
+}
+```
+
+Three things are already true: typing in the search box reports a new query and you refetch; the
+table has no empty state, because nothing to show is shown as nothing; and while `loading` is set
+it paints a skeleton in the table's own shape.
+
+→ [the full page](./examples/overview.md)
+
+## 2. Four views over one dataset
+
+Add views by rendering them. The switcher builds itself.
+
+```tsx
+<DataViews.Table selectable onRowClick={(row, id) => open(id)} />
+<DataViews.Board groups={groups} titlePath="customer.name" onRowMove={move} />
+<DataViews.Inbox titlePath="customer.name" datePath="createdAt">
+  <DataViews.Detail />
+</DataViews.Inbox>
+<DataViews.Tree nodes={nodes} labelPath="customer.name">
+  <DataViews.Tree.Table />
+  <DataViews.Tree.Cards />
+</DataViews.Tree>
+```
+
+`groups` and `nodes` are yours to build, and worth memoizing:
+
+```tsx
+const groups = useMemo<RowGroup[]>(
+  () => STATUSES.map((status) => ({
+    id: status, label: status, rows: rows.filter((r) => r.status === status),
+  })),
+  [rows],
+);
+```
+
+Register the same view twice with different data by giving each an `id` and `label`:
+
+```tsx
+<DataViews.Board id="by-status" label="Status" groups={byStatus} />
+<DataViews.Board id="by-owner"  label="Owner"  groups={byOwner} />
+```
+
+→ [the full page](./examples/views.md)
+
+## 3. Filters — they are FormBuilder fields
+
+`DataViews.Filters` takes **the fields themselves**, one JSX child each, exactly as any form in this
+library is written. The `<FormBuilder>` is inside; you write only its fields. What each child means
+comes from the field, not from a config: a `MultiSelect` becomes a list of values, a `Slider` a
+numeric range, a `DateRange` a date range.
+
+```tsx
+<DataViews.Panel>
+  <DataViews.Panel.Tab value="filters" label="Filters" icon={<Filter />}>
+    <DataViews.Filters title={null} className="border-b-0 p-0">
+      <FormBuilder.CheckboxGroup name="status" label="Status" options={STATUS_OPTIONS} />
+      <FormBuilder.RadioList name="priority" label="Priority" options={PRIORITY_OPTIONS} />
+      <FormBuilder.SearchableSelect name="customer.name" label="Customer" options={CUSTOMERS} />
+      <FormBuilder.MultiSelect name="brand.name" label="Brand" options={BRANDS} />
+      <FormBuilder.Slider name="total" label="Total" range min={0} max={15000} step={100} />
+      <FormBuilder.DateRange name="createdAt" label="Created" />
+      <DataViews.Filters.Presets for="total" items={[{ label: "Under $500", max: 500 }]} />
+    </DataViews.Filters>
+  </DataViews.Panel.Tab>
+</DataViews.Panel>
+```
+
+Which control to reach for is two questions — can the option set grow, and can the user pick more
+than one:
+
+| | Single | Multiple |
+| --- | --- | --- |
+| **Fixed, short list** | `RadioList` | `CheckboxGroup` |
+| **Dynamic or long** | `SearchableSelect` | `MultiSelect` |
+
+`Filters` does not filter. It reports into the query, you fetch, and the rows change when you hand
+back different ones. Two things to know: a control at its neutral position emits **no key at all**,
+so a slider dragged back to `[min, max]` removes its filter rather than sending "everything"; and
+booleans have no filter section — use a Yes/No `RadioList` or `Filters.Custom`.
+
+→ [the full page](./examples/filters.md)
+
+## 4. The settings rail
+
+The rail is `DataViews.Panel`, opened by the `PanelToggle` in the header. Its tabs are children,
+like everything else.
+
+```tsx
+<DataViews.Panel>
+  <DataViews.Panel.Tab value="config" label="Config." icon={<Settings />}>
+    <DataViews.Panel.SavedViews
+      views={saved}
+      onSave={(snapshot) => setSaved((prev) => [...prev, { id: crypto.randomUUID(), label: `View ${prev.length + 1}`, snapshot }])}
+    />
+    <DataViews.Panel.Columns />
+    <DataViews.Panel.Sort />
+  </DataViews.Panel.Tab>
+
+  <DataViews.Panel.Tab value="filters" label="Filters" icon={<Filter />}>
+    …
+  </DataViews.Panel.Tab>
+</DataViews.Panel>
+```
+
+Saving a view is yours — a view outlives the component. Restoring is not: hand the snapshot back
+and picking it puts filters, sort and columns back internally.
+
+→ [the full page](./examples/panel.md)
+
+## 5. Large datasets — scroll, don't page
+
+There is no pager. Hand over `onLoadMore` and **append** each page; whether there is more is derived
+from `rows.length < total`, so there is no flag to keep in sync.
+
+```tsx
+const { data, fetchNextPage, isPending, isFetchingNextPage } = useInfiniteQuery({
+  queryKey: ["orders", { ...query, page: undefined }],   // not `page` — pageParam drives that
+  initialPageParam: 1,
+  queryFn: ({ pageParam }) =>
+    fetch(`/api/orders?${queryToParams({ ...query, page: pageParam })}`).then((r) => r.json()),
+  getNextPageParam: (last, pages) => {
+    const loaded = pages.reduce((n, p) => n + p.rows.length, 0);
+    return loaded < last.total ? pages.length + 1 : undefined;
+  },
+});
+
+<DataViews
+  rows={data?.pages.flatMap((p) => p.rows) ?? []}
+  total={data?.pages[0]?.total ?? 0}
+  loading={isPending}
+  onLoadMore={fetchNextPage}
+  loadingMore={isFetchingNextPage}
+  fields={FIELDS}
+  onQueryChange={setQuery}
+/>
+```
+
+The table also **virtualizes past 300 rows**, so the DOM stays small however many are loaded. Below
+that it renders every row, which is what keeps row drag and column resize simple. The board and
+inbox load on scroll but do not virtualize; the tree does neither.
+
+→ [the full page](./examples/scale.md)
+
+## 6. Server-side, end to end
+
+The query goes out through `queryToParams` and comes back in through `parseQuery` — one encoder,
+one decoder, imported from the same module so they cannot drift.
+
+```ts
+// app/api/orders/route.ts
+import { parseQuery } from "@/components/DataViews";
+
+export async function GET(request: Request) {
+  const { search, filters, sort, page, pageSize } = parseQuery(new URL(request.url));
+
+  let rows = ALL.filter((row) => matches(row, search, filters));
+  if (sort) rows = [...rows].sort(by(sort));
+  const total = rows.length;
+  return Response.json({ rows: rows.slice((page - 1) * pageSize, page * pageSize), total });
+}
+```
+
+`filters` is `Record<path, string[] | { kind: "number", min?, max? } | { kind: "date", from?, to? }>`.
+How constraints combine is your matcher's business.
+
+→ [the full page](./examples/server-side.md)
+
+## 7. Drag and drop
+
+Four surfaces drag — board cards, table rows, tree nodes and the rail's column list — and each is
+**opt-in by passing the handler**. All of them report intent and move nothing themselves:
+
+```tsx
+<DataViews.Table onRowMove={(intent) => reorder.mutate(intent)} />
+<DataViews.Board groups={groups} onRowMove={({ id, to }) => to && move.mutate({ id: Number(id), status: to })} />
+<DataViews.Tree nodes={nodes} onNodeMove={(intent) => reparent.mutate(intent)} />
+```
+
+A card settles where it landed only once your refetched rows agree — which is what makes a rejected
+move snap back with no rollback code. Touch drags activate on a 200ms hold so a swipe still scrolls,
+and every surface is keyboard-operable: Space, arrows, Space.
+
+## 8. Custom cells, cards and rows
+
+Each seam hands you `{ row, id, index, fields }` — `fields` being what the panel left visible, in
+order — and `Cell` paints one the way every other view paints it.
+
+```tsx
+// one field, everywhere it appears
+{ path: "health", label: "Health", render: (value) => <HealthPill value={Number(value)} /> }
+
+// one cell, table only — return `undefined` to fall through to the default
+<DataViews.Table renderCell={({ field, row }) =>
+  field.path === "total" ? <TotalBar value={Number(row.total)} /> : undefined
+} />
+
+// the board's card
+<DataViews.Board groups={groups} renderCard={({ row, isDragging }) => <OrderCard row={row} dim={isDragging} />} />
+
+// the inbox row
+<DataViews.Inbox renderItem={({ row, isActive }) => <MailRow row={row} active={isActive} />} />
+
+// a tree node — parts, not markup: TreeFolder owns the row
+<DataViews.Tree nodes={nodes} renderNode={({ row }) => ({ meta: <Badge label={String(row.status)} color="blue" /> })} />
+```
+
+→ [the full page](./examples/fields.md)
+
+## 9. The tree's pane, and a tab of your own
+
+The tree's `children` are its **pane tabs**, on the same bargain as everything else: a tab exists
+because you rendered it, the switch shows exactly what you passed, one tab draws no switch, and
+**no tabs means no pane at all** — the rail then takes the full width.
+
+```tsx
+<DataViews.Tree
+  nodes={nodes}
+  labelPath="brand.name"
+  paneRows={(node) => node.children.map((child) => child.row)}
+  paneActions={<Button variant="BluColStyle" size="M">New order</Button>}
+>
+  <DataViews.Tree.Table selectable renderCell={cell} />
+  <DataViews.Tree.Cards renderCard={({ row }) => <OrderCard row={row} />} />
+  <DataViews.Tree.Tab value="timeline" label="Timeline" icon={<Clock />}>
+    <Timeline />
+  </DataViews.Tree.Tab>
+</DataViews.Tree>
+```
+
+`Tree.Table` **is** `DataViews.Table`, rendered over the selected node's rows — sortable headers,
+selection, `renderCell`, the grip, `+ Add New` and virtualization all come with it.
+
+A tab of your own reads the node's rows from the same context every other part uses, because the
+pane scopes them:
+
+```tsx
+function Timeline() {
+  const { rows } = useDataViewsData();   // the selected node's rows, narrowed by `paneRows`
+  return <ol>{rows.map((row) => <li key={String(row.id)}>{String(row.createdAt)}</li>)}</ol>;
+}
+```
+
+And when none of that fits, anything in `children` that is **not** a tab *is* the pane — header,
+switch and all.
+
+→ [the full page](./examples/tree-custom.md)
+
+## 10. A view of your own
+
+`markView` registers a component in the switcher beside the built-in four. It reads the same
+context, so it gets the rows, the visible fields, the loading state and scroll loading for free.
+
+```tsx
+const GalleryView = markView(
+  function GalleryView() {
+    const { rows, visibleFields, loading, getRowId } = useDataViewsData();
+    if (loading) return <div className="grid grid-cols-3 gap-3 p-4">{skeletonKeys(6).map((k) => <SkeletonBar key={k} className="h-40" />)}</div>;
+
+    return (
+      <div className="grid grid-cols-3 gap-3 p-4">
+        {rows.map((row, i) => (
+          <article key={getRowId(row, i)} className="rounded-[12px] border p-4">
+            {visibleFields.map((field, n) => <Cell key={`${field.path}-${n}`} field={field} row={row} />)}
+          </article>
+        ))}
+      </div>
+    );
+  },
+  { defaultId: "gallery", defaultLabel: "Gallery" },
+);
+
+<DataViews …>
+  <DataViews.Table />
+  <GalleryView icon={<i className="ri-layout-grid-line" />} />
+</DataViews>
+```
+
+Wrapping a **built-in** part in a component of your own hides the marker the root recognises it by,
+so the wrapper carries the marker itself — `markPanel`, `markHeader`, `markView`.
+
+→ [the full page](./examples/view-registry.md)
+
+## Gotchas
+
+- **Nothing filters, sorts or pages itself.** If the rows do not change, the screen does not change.
+- **Append pages, never replace** — replacing resets the list and the sentinel fires again.
+- **Exclude `page` from your query key** with `useInfiniteQuery`, or every page refetches the lot.
+- **Memoize `groups` and `nodes`**; `data?.rows ?? []` is a new array every render.
+- **`total` is the server's count.** Scroll loading stops at `rows.length >= total`.
+- **A filter on `customer.name` registers as `customer__name`** inside the form — you write the real
+  path, but a hand-rolled `setValue` needs the escaped one.
+- **The chrome is always dark**; `theme` themes the content. Never use `system` tokens or
+  `variant="SystemStyle"` — use the `presentation` equivalents.
+- **`DataViews.Detail` is row-keyed.** In a tree it fills in only when the node's id is also a row
+  id; a synthetic grouping node has no row, so it renders nothing.
+
+## Related
+
+- [`DataViews` component reference](./index.md) — every part, prop and type
+- [Render a backend response with DataViews](./backend-response.md) — JSON shape →
+  what to render
+- [Forms with FormBuilder](../../how-to/forms-with-form-builder.md) — the fields `DataViews.Filters` takes
+- [Migrating to the DataViews component](./migration.md)