torch-glare 2.5.5 → 2.6.0

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

@@ -1,324 +0,0 @@
----
-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

@@ -1,250 +0,0 @@
----
-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>
-  );
-}
-```