torch-glare 2.4.5 → 2.5.1

package/docs/components/data-views/backend-response.md

@@ -0,0 +1,324 @@
+---
+title: Render a backend response with DataViews
+description: Recipes for turning common backend JSON shapes into a DataViews screen — flat lists, status fields, nested objects, hierarchies, message shapes, and server-driven filtering and paging.
+group: how-to
+keywords: [data-views, dataviews, recipes, backend, json, api, flat, nested, hierarchy, inbox, board, kanban, server-side, filtering, pagination, how-to]
+---
+
+# Render a backend response with DataViews
+
+[`DataViews`](./index.md) shows one dataset as a table, a kanban board, an inbox or
+a tree. This guide maps the JSON you get back from an API to what you render.
+
+One rule governs every recipe below, so it is worth stating first: **DataViews never reshapes your
+data.** It does not group rows into columns, build a hierarchy, infer a schema, filter, sort or
+page. It paints the `rows` you hand it, in the order you hand them, using the `fields` you describe.
+Anything shaped — `groups`, `nodes` — you build. That is what makes a failed save leave the screen
+showing the truth.
+
+## TL;DR
+
+```tsx
+const { data } = useQuery({ queryKey: ["records"], queryFn: () => api.get("/records") });
+
+<DataViews rows={data?.rows ?? []} total={data?.total ?? 0} fields={FIELDS}>
+  <DataViews.Header title="Records">
+    <DataViews.ViewSwitch />
+    <DataViews.Search />
+    <DataViews.PanelToggle />
+  </DataViews.Header>
+  <DataViews.Table />
+</DataViews>
+```
+
+`fields` is the one thing with no default — DataViews will not guess your columns:
+
+```ts
+const FIELDS: FieldConfig[] = [
+  { path: "id", label: "ID", type: "number" },
+  { path: "name", label: "Name" },
+  { path: "createdAt", label: "Created", type: "date-format", dateFormat: "YYYY-MM-DD" },
+];
+```
+
+## Recipe 1 — A flat list of objects
+
+The common case. Every field you list becomes a column, in the order you list it.
+
+```json
+[{ "id": 1, "name": "Acme", "total": 1240, "createdAt": "2025-09-10" }]
+```
+
+```tsx
+const FIELDS: FieldConfig[] = [
+  { path: "id", label: "Order #", type: "number" },
+  { path: "name", label: "Customer" },
+  { path: "total", label: "Total", type: "currency", currency: "USD" },
+  { path: "createdAt", label: "Created", type: "date-format", dateFormat: "YYYY-MM-DD" },
+];
+
+<DataViews rows={rows} total={rows.length} fields={FIELDS}>
+  <DataViews.Header title="Orders"><DataViews.ViewSwitch /></DataViews.Header>
+  <DataViews.Table selectable />
+</DataViews>
+```
+
+If your rows have no `id`, tell the component what identity is — selection, drag and the open row
+all key off it:
+
+```tsx
+<DataViews rows={rows} fields={FIELDS} getRowId={(row) => String(row.sku)}>
+```
+
+## Recipe 2 — A status field → a board
+
+The board takes **columns you built**. Grouping is a decision (which statuses exist, in what order,
+what an empty column means) that only you can make correctly.
+
+```json
+[{ "id": 1, "status": "Pending" }, { "id": 2, "status": "Shipped" }]
+```
+
+```tsx
+const STATUSES = ["Pending", "Shipped", "Delivered", "Cancelled"] as const;
+
+const groups = useMemo<RowGroup[]>(
+  () =>
+    STATUSES.map((status) => ({
+      id: status,
+      label: status,
+      color: ({ Pending: "gray", Shipped: "blue", Delivered: "green", Cancelled: "red" } as const)[status],
+      rows: rows.filter((row) => row.status === status),
+    })),
+  [rows],
+);
+
+<DataViews.Board
+  groups={groups}
+  titlePath="name"
+  onRowMove={(intent) => {
+    if (intent.to) move.mutate({ id: Number(intent.id), status: intent.to });
+  }}
+/>
+```
+
+`onRowMove` reports **intent**. The card settles where it landed only once your refetched rows
+agree — which is exactly why a rejected move snaps back on its own.
+
+Paint the same field as a coloured chip in the table by giving it a type:
+
+```ts
+{ path: "status", label: "Status", type: "enum-badge",
+  variants: { Pending: "yellow", Shipped: "blue", Delivered: "green" } }
+```
+
+## Recipe 3 — Nested objects → dotted paths
+
+No flattening step. A `path` reads as deep as you need.
+
+```json
+[{ "id": 1, "customer": { "name": "Acme", "email": "a@acme.com" }, "brand": { "name": "Bosch" } }]
+```
+
+```ts
+const FIELDS: FieldConfig[] = [
+  { path: "customer.name", label: "Customer" },
+  { path: "customer.email", label: "Email", type: "link", linkType: "mailto" },
+  { path: "brand.name", label: "Brand" },
+];
+```
+
+Dotted paths work anywhere a path is taken — `titlePath`, `datePath`, `labelPath`, `sort.path` and
+the keys of `filters`.
+
+> **The one place `.` is special.** `DataViews.Filters` builds its controls with `FormBuilder`, and
+> react-hook-form reads `.` as object nesting — so a filter on `customer.name` registers as
+> `customer__name`. You still write the real path; only a hand-rolled `setValue` needs the escaped
+> name.
+
+## Recipe 4 — A hierarchy → `nodes`
+
+Nested `children[]` or a flat `parentId` list both become `TreeNode[]`, and **you** do the
+conversion: which field is the parent key, whether orphans become roots and how cycles are handled
+are decisions the component cannot make for you.
+
+```json
+[{ "id": "1", "name": "Tools", "children": [{ "id": "2", "name": "Drills", "children": [] }] }]
+```
+
+```tsx
+const toNodes = (items: ApiCategory[], depth = 0): TreeNode[] =>
+  items.map((item) => ({
+    id: item.id,
+    row: item as Row,
+    depth,
+    children: toNodes(item.children ?? [], depth + 1),
+  }));
+```
+
+From a flat `parentId` list:
+
+```tsx
+const toNodes = (items: ApiCategory[]): TreeNode[] => {
+  const byId = new Map(items.map((i) => [i.id, { id: i.id, row: i as Row, depth: 0, children: [] as TreeNode[] }]));
+  const roots: TreeNode[] = [];
+  for (const item of items) {
+    const node = byId.get(item.id)!;
+    const parent = item.parentId ? byId.get(item.parentId) : undefined;
+    // An orphan becoming a root is a decision — make it deliberately.
+    (parent ? parent.children : roots).push(node);
+  }
+  return roots;
+};
+```
+
+Then render the tree, and say what its pane shows — **the pane's tabs are children, and passing
+none means there is no pane at all**:
+
+```tsx
+<DataViews.Tree nodes={nodes} labelPath="name">
+  <DataViews.Tree.Table selectable />
+  <DataViews.Tree.Cards />
+</DataViews.Tree>
+```
+
+When the tree holds one kind of thing and the pane must list another — categories in the rail,
+items in the pane — that is `paneRows`:
+
+```tsx
+<DataViews.Tree nodes={categories} paneRows={(node) => itemsInCategory(node.id)}>
+  <DataViews.Tree.Table />
+</DataViews.Tree>
+```
+
+## Recipe 5 — A message shape → the inbox
+
+```json
+[{ "id": 1, "subject": "Delivery delayed", "from": "ops@acme.com", "createdAt": "2025-09-10" }]
+```
+
+```tsx
+<DataViews.Inbox titlePath="subject" datePath="createdAt">
+  <DataViews.Detail />
+</DataViews.Inbox>
+```
+
+`DataViews.Detail` renders every visible field of the open row. For anything richer, the pane is
+`children` and `useActiveRow()` resolves what is open.
+
+If the open message should be a **URL** — a back button, a shareable link — make the items links:
+
+```tsx
+<DataViews.Inbox titlePath="subject" datePath="createdAt"
+                 itemHref={(row, id) => `/inbox/${id}`} linkComponent={Link} />
+```
+
+## Recipe 6 — Server-driven filtering, sorting and paging
+
+Everything the user can ask for arrives as one object, because a query with a new filter and a
+stale page number is not a query anyone meant to ask.
+
+```tsx
+const [query, setQuery] = useState(emptyQuery());
+const { data, isPending } = useQuery({
+  queryKey: ["orders", query],
+  queryFn: () => fetch(`/api/orders?${queryToParams(query)}`).then((r) => r.json()),
+});
+
+<DataViews
+  rows={data?.rows ?? []}
+  total={data?.total ?? 0}
+  fields={FIELDS}
+  loading={isPending}
+  onQueryChange={setQuery}
+>
+```
+
+The route handler decodes with `parseQuery`, so the encoder and the decoder 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));
+  // your matcher, your ORM
+  return Response.json({ rows, total });
+}
+```
+
+`filters` is `Record<path, string[] | { kind: "number", min?, max? } | { kind: "date", from?, to? }>`.
+How the constraints combine — AND across fields, OR within one, fuzzy or exact — is your matcher's
+business. The component reports what was chosen and nothing more.
+
+**Paging is scrolling.** 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}
+/>
+```
+
+## Recipe 7 — A response nothing built-in fits
+
+Two seams, in increasing order of commitment.
+
+**Repaint a field** — the narrowest, and it applies in every view at once:
+
+```ts
+{ path: "health", label: "Health", render: (value, row) => <HealthPill value={Number(value)} row={row} /> }
+```
+
+**Add a view of your own.** `markView` registers it in the switcher beside the built-in four; it
+reads the same context, loading state included:
+
+```tsx
+const GalleryView = markView(function GalleryView() {
+  const { rows, visibleFields, loading, getRowId } = useDataViewsData();
+  if (loading) return <SkeletonBar className="h-40" />;
+  return <div className="grid grid-cols-3 gap-3">{rows.map((row, i) => <Tile key={getRowId(row, i)} row={row} />)}</div>;
+}, { defaultId: "gallery", defaultLabel: "Gallery" });
+
+<DataViews …>
+  <DataViews.Table />
+  <GalleryView icon={<i className="ri-layout-grid-line" />} />
+</DataViews>
+```
+
+## Gotchas
+
+- **Nothing filters itself.** If the rows do not change, nothing on screen changes. That is the
+  contract, not a bug.
+- **`total` is the server's count**, not `rows.length`. Scroll loading stops when
+  `rows.length >= total`, so a wrong `total` either stops early or loops.
+- **Append, never replace**, when paging — replacing resets the list and the sentinel fires again.
+- **Memoize `groups` and `nodes`.** They are rebuilt on every render otherwise, and both are
+  diffed.
+- **A part exists because you rendered it.** There is no `views={{ … }}` map; wrap a view in a
+  condition to hide it, and the component switches away if it was open.
+- **Booleans have no filter section.** Use a Yes/No `RadioList`, or `Filters.Custom`.
+
+## Related
+
+- [`DataViews` component reference](./index.md) — every part, prop and type
+- [Build a DataViews screen](./guide.md) — the same ground as scenarios, start to finish
+- [Migrating to the DataViews component](./migration.md) — if you are coming from
+  `DataViewsLayout`

package/docs/components/data-views/examples/a11y-rtl.md

@@ -0,0 +1,250 @@
+---
+title: DataViews example — Keyboard & RTL
+description: Keyboard paths and the RTL mirror.
+group: examples
+component: DataViews
+keywords: [data-views, example, examples, a11y, rtl]
+---
+
+# DataViews example — Keyboard & RTL
+
+Keyboard paths and the RTL mirror.
+
+Complete and runnable — this is the page itself, not an excerpt. In the monorepo it lives at `apps/app/data-views/a11y-rtl/page.tsx`.
+
+See the [component reference](../index.md) for what each prop does, or the [guide](../guide.md) for the same ground as scenarios.
+
+```tsx
+"use client";
+
+import { useMemo, useState } from "react";
+import { useInfiniteQuery } from "@tanstack/react-query";
+import { Filter, Settings } from "lucide-react";
+import { Button } from "@/components/Button";
+import { DataViews, emptyQuery, queryToParams, type SavedView } from "@/components/DataViews";
+import { FormBuilder } from "@/components/FormBuilder";
+import type {
+  DataViewsQuery,
+  FieldConfig,
+  Row,
+  RowGroup,
+  TreeNode,
+} from "@/utils/dataViews/types";
+import type { Themes } from "@/utils/types";
+
+// ─── Data ─────────────────────────────────────────────────────────────────────
+
+interface Order extends Row {
+  id: number;
+  customer: { name: string };
+  status: "Pending" | "Shipped" | "Delivered";
+  total: number;
+  createdAt: string;
+}
+
+const FIELDS: FieldConfig[] = [
+  { path: "id", label: "Order #", type: "number" },
+  { path: "customer.name", label: "Customer", type: "text" },
+  { path: "brand.name", label: "Brand", type: "text" },
+  { 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" },
+];
+
+/** Arabic labels, so a right-to-left layout is legible rather than mirrored English. */
+const ARABIC_FIELDS: FieldConfig[] = [
+  { path: "id", label: "رقم الطلب", type: "number" },
+  { path: "customer.name", label: "العميل", type: "text" },
+  { path: "status", label: "الحالة", type: "enum-badge", variants: { Pending: "yellow", Shipped: "blue", Delivered: "green" } },
+  { path: "total", label: "المجموع", type: "currency", currency: "USD" },
+  { path: "createdAt", label: "التاريخ", type: "date-format", dateFormat: "YYYY-MM-DD" },
+];
+
+/** Dynamic sets — in a real app these come from the endpoint that also does the filtering. */
+const CUSTOMER_OPTIONS = [
+  "Acme Inc.", "Globex Corp.", "Initech", "Umbrella",
+  "Hooli", "Stark Industries", "Wayne Enterprises", "Cyberdyne",
+].map((v) => ({ label: v, value: v }));
+
+const BRAND_OPTIONS = ["Bosch", "Makita", "DeWalt", "Hilti"].map((v) => ({ label: v, value: v }));
+
+const PRIORITY_OPTIONS = ["High", "Medium", "Low"].map((v) => ({ label: v, value: v }));
+
+const STATUS_OPTIONS = [
+  { label: "Pending", value: "Pending" },
+  { label: "Shipped", value: "Shipped" },
+  { label: "Delivered", value: "Delivered" },
+];
+
+/**
+ * The request this page makes. The querying itself happens in `app/api/orders/route.ts` —
+ * nothing on this page filters, sorts or pages anything, which is the split DataViews is built
+ * around.
+ */
+async function fetchOrders(q: DataViewsQuery): Promise<{ rows: Order[]; total: number }> {
+  const params = queryToParams(q);
+  const res = await fetch(`/api/orders?${params}`);
+  if (!res.ok) throw new Error(`${res.status} ${res.statusText}`);
+  return res.json();
+}
+
+const groupByStatus = (rows: readonly Order[]): RowGroup[] =>
+  (["Pending", "Shipped", "Delivered"] as const).map((status) => ({
+    id: status,
+    label: status,
+    color: ({ Pending: "gray", Shipped: "blue", Delivered: "green" } as const)[status],
+    rows: rows.filter((row) => row.status === status),
+  }));
+
+const nodesFromRows = (rows: readonly Order[]): TreeNode[] =>
+  rows.map((row) => ({ id: String(row.id), row, depth: 0, children: [] }));
+
+// ─── Page ─────────────────────────────────────────────────────────────────────
+
+/**
+ * Keyboard: tab through it with the mouse down. A row with `onRowClick` takes a `tabIndex`, a
+ * button role and Enter/Space handling — press Enter on one and it selects. Without the handler a
+ * row stays a plain row and is skipped, which is right: a row that does nothing is not a tab stop.
+ *
+ * The tree handles `←`/`→` and Enter but not yet `↑`/`↓`, `Home`/`End` or roving tabindex, so
+ * every node is its own tab stop. Drag-and-drop has no keyboard equivalent at all — if moving
+ * records matters, give people a menu action that emits the same intent.
+ *
+ * Direction comes from the DOM, not a prop: the component is built from logical properties, so
+ * `dir="rtl"` moves the rail left and aligns the table to the start edge. `theme` sets
+ * `data-theme` — but the filter dropdowns and the date calendar portal to `document.body`, so
+ * they follow the *page's* theme rather than this one.
+ */
+export default function AccessibilityExample() {
+  const [rtl, setRtl] = useState(false);
+  const [theme, setTheme] = useState<Themes>("default");
+
+  const [query, setQuery] = useState(emptyQuery());
+  const [activated, setActivated] = useState<string | null>(null);
+  const [saved, setSaved] = useState<SavedView[]>([]);
+
+
+  const { data, isPending, fetchNextPage, isFetchingNextPage } = useInfiniteQuery({
+    // The key *is* the query: touch any part of it and TanStack refetches, and a response that
+    // has been superseded is discarded rather than landing on top of a newer one.
+    queryKey: ["a11y-orders", { ...query, page: undefined }],
+    queryFn: ({ pageParam }) => fetchOrders({ ...query, page: pageParam }),
+    initialPageParam: 1,
+    // Undefined means "no more" — which is what the component's `hasMore` resolves to.
+    getNextPageParam: (last, pages) => {
+      const loaded = pages.reduce((n, page) => n + page.rows.length, 0);
+      return loaded < last.total ? pages.length + 1 : undefined;
+    },
+  });
+
+  // Memoised because `data?.rows ?? []` is a new array on every render, which would make the
+  // `groups`/`nodes` memos below miss every time and hand the board a new array to diff.
+  const rows = useMemo(() => data?.pages.flatMap((page) => page.rows) ?? [], [data]);
+  const total = data?.pages[0]?.total ?? 0;
+  const groups = useMemo(() => groupByStatus(rows), [rows]);
+  const nodes = useMemo(() => nodesFromRows(rows), [rows]);
+
+  return (
+    <div dir={rtl ? "rtl" : "ltr"} className="flex h-full min-h-0 flex-col p-4">
+      <DataViews
+        key={rtl ? "rtl" : "ltr"}
+        rows={rows}
+        fields={rtl ? ARABIC_FIELDS : FIELDS}
+        theme={theme}
+        total={total}
+        loading={isPending}
+        onLoadMore={fetchNextPage}
+        loadingMore={isFetchingNextPage}
+        onQueryChange={setQuery}
+        className="h-full"
+      >
+        <DataViews.Header title={rtl ? "الطلبات" : "Orders"}>
+          <DataViews.ViewSwitch />
+          <DataViews.Search />
+          <DataViews.Actions>
+            {/* Proof the keyboard path works: Enter on a focused row fires `onRowClick`. */}
+            <span
+              data-testid="activated"
+              className="typography-body-small-regular text-content-presentation-global-secondary"
+            >
+              {activated ? `row ${activated}` : "no row activated"}
+            </span>
+            {/* Two buttons rather than one toggle: a single button labelled with the current
+                direction is ambiguous — it reads as either the state or the action. */}
+            <Button variant="BluColStyle" size="M" onClick={() => setRtl(false)}>
+              LTR
+            </Button>
+            <Button variant="BluColStyle" size="M" onClick={() => setRtl(true)}>
+              RTL
+            </Button>
+            {(["default", "dark", "light"] as const).map((t) => (
+              <Button variant="BluColStyle"
+                size="M"
+                key={t}
+                onClick={() => setTheme(t)}
+              >
+                {t}
+              </Button>
+            ))}
+          </DataViews.Actions>
+          <DataViews.PanelToggle />
+        </DataViews.Header>
+
+        {/* Enter on a focused row fires `onRowClick` — the visible proof the row is reachable
+            without a mouse. What to do about it is the app's call; here it is a readout. */}
+        <DataViews.Table selectable onRowClick={(_row, id) => setActivated(id)} />
+        <DataViews.Board
+          groups={groups}
+          titlePath="customer.name"
+        />
+        {/* The pane's tabs are children, like every other part: pass none and there is no pane. */}
+        <DataViews.Tree nodes={nodes} labelPath="customer.name">
+          <DataViews.Tree.Table />
+          <DataViews.Tree.Cards />
+        </DataViews.Tree>
+
+        <DataViews.Panel>
+          <DataViews.Panel.Tab value="config" label="Config." icon={<Settings />}>
+            {/* Saving is the app's job — a view outlives the component. Restoring is not:
+                hand the snapshot back and selecting it puts everything back internally. */}
+            <DataViews.Panel.SavedViews
+              views={saved}
+              onSave={(snapshot) =>
+                setSaved((prev) => [
+                  ...prev,
+                  { id: `view-${prev.length + 1}`, label: `View ${prev.length + 1}`, snapshot },
+                ])
+              }
+            />
+            <DataViews.Panel.Columns />
+            <DataViews.Panel.Sort />
+          </DataViews.Panel.Tab>
+
+          <DataViews.Panel.Tab value="filters" label="Filters" icon={<Filter />}>
+            {/* The controls are FormBuilder fields — the same Select and Slider any form in
+                this library uses. Filters reads each child's name, label and bounds to learn
+                what it is; there is no second description of the form. */}
+            <DataViews.Filters
+              title={null}
+              className="border-b-0 p-0"
+            >
+              {/* One control per section type. Which one a field gets is decided by the data:
+                  can the option set grow, and can the user pick more than one. */}
+              <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={CUSTOMER_OPTIONS}
+              />
+              <FormBuilder.MultiSelect name="brand.name" label="Brand" options={BRAND_OPTIONS} />
+              <FormBuilder.Slider name="total" label="Total" range min={0} max={15000} step={100} />
+              <FormBuilder.DateRange name="createdAt" label="Created" />
+            </DataViews.Filters>
+          </DataViews.Panel.Tab>
+        </DataViews.Panel>
+      </DataViews>
+    </div>
+  );
+}
+```