torch-glare 2.4.4 → 2.5.0

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>
+  );
+}
+```

package/docs/components/data-views/examples/api-orders-route.md

@@ -0,0 +1,130 @@
+---
+title: DataViews example — The endpoint these examples call
+description: The route handler every DataViews example fetches from — and the only worked example of `parseQuery` on the server.
+group: examples
+component: DataViews
+keywords: [data-views, example, examples, api, orders, route]
+---
+
+# DataViews example — The endpoint these examples call
+
+The route handler every DataViews example fetches from — and the only worked example of `parseQuery` on the server.
+
+Complete and runnable — this is the page itself, not an excerpt. In the monorepo it lives at `apps/app/api/orders/route.ts`.
+
+See the [component reference](../index.md) for what each prop does, or the [guide](../guide.md) for the same ground as scenarios.
+
+```ts
+import { NextResponse } from "next/server";
+import type { Row } from "@/utils/dataViews/types";
+import { parseQuery } from "@/utils/dataViews/query";
+import { latency, runQuery } from "../_lib/query";
+
+/**
+ * `GET /api/orders` — the orders table most of the examples read.
+ *
+ * ```
+ * /api/orders?search=acme&filters={"status":["Pending"]}&sort=total:desc&page=1&pageSize=10
+ * → { rows, total, page, pageSize }
+ * ```
+ *
+ * `?fail=1` returns a 502, which is what the server-side example's failure toggle asks for.
+ */
+
+export interface Order extends Row {
+  id: number;
+  customer: { name: string };
+  /** Org-configurable master data — the annex's Type ④ example (dynamic, multi-pick). */
+  brand: { name: string };
+  status: "Pending" | "Shipped" | "Delivered";
+  priority: "High" | "Medium" | "Low";
+  total: number;
+  items: number;
+  createdAt: string;
+}
+
+/**
+ * Eight rows, three of them `Pending`. Small on purpose: every behaviour these examples
+ * demonstrate is visible at eight rows, and a filter that leaves three is easy to check at a
+ * glance. The scale endpoint is where volume is the point.
+ */
+const ORDERS: Order[] = [
+  { id: 1, brand: { name: "Bosch" }, customer: { name: "Acme Inc." }, status: "Pending", priority: "High", total: 1240, items: 4, createdAt: "2025-09-10" },
+  { id: 2, brand: { name: "Makita" }, customer: { name: "Globex Corp." }, status: "Shipped", priority: "Medium", total: 480, items: 2, createdAt: "2025-09-12" },
+  { id: 3, brand: { name: "DeWalt" }, customer: { name: "Initech" }, status: "Delivered", priority: "Low", total: 99, items: 1, createdAt: "2025-09-15" },
+  { id: 4, brand: { name: "Bosch" }, customer: { name: "Umbrella" }, status: "Pending", priority: "High", total: 2890, items: 9, createdAt: "2025-09-18" },
+  { id: 5, brand: { name: "Hilti" }, customer: { name: "Hooli" }, status: "Shipped", priority: "Medium", total: 740, items: 3, createdAt: "2025-09-20" },
+  { id: 6, brand: { name: "Makita" }, customer: { name: "Stark Industries" }, status: "Pending", priority: "High", total: 12400, items: 21, createdAt: "2025-09-22" },
+  { id: 7, brand: { name: "DeWalt" }, customer: { name: "Wayne Enterprises" }, status: "Delivered", priority: "Medium", total: 5300, items: 12, createdAt: "2025-09-25" },
+  { id: 8, brand: { name: "Hilti" }, customer: { name: "Cyberdyne" }, status: "Shipped", priority: "Low", total: 220, items: 1, createdAt: "2025-09-28" },
+];
+
+/**
+ * What each order's status was before anyone dragged it. Captured once at module load so the
+ * board examples have something to reset to — this array *is* the mutable store.
+ */
+const ORIGINAL_STATUS = ORDERS.map((row) => row.status);
+
+/**
+ * `items` is filtered by a bucket picker the filters example builds with `Filters.Custom`, so its
+ * value is a label rather than a stored value. A filter no field produces still has to be a filter
+ * the endpoint understands — that is the whole point of the escape hatch.
+ */
+const IN_BUCKET: Record<string, (n: number) => boolean> = {
+  "1–3": (n) => n <= 3,
+  "4–10": (n) => n > 3 && n <= 10,
+  "10+": (n) => n > 10,
+};
+
+/**
+ * `PATCH /api/orders` — move an order to another status, or put them all back.
+ *
+ * This is the other half of `onRowMove`: the board emits an intent and nothing moves until the
+ * data says so. Persisting it here is what makes the card stay put after the refetch — and what
+ * makes "Ignoring moves" visibly different from "Applying moves".
+ *
+ * ```
+ * PATCH { id: 4, status: "Shipped" }
+ * PATCH { reset: true }
+ * ```
+ */
+export async function PATCH(request: Request) {
+  const body = (await request.json()) as { id?: number; status?: Order["status"]; reset?: boolean };
+  await latency(150);
+
+  if (body.reset) {
+    ORDERS.forEach((row, i) => (row.status = ORIGINAL_STATUS[i]));
+    return NextResponse.json({ ok: true });
+  }
+
+  const order = ORDERS.find((row) => row.id === Number(body.id));
+  if (!order) return NextResponse.json({ error: "Not found" }, { status: 404 });
+  if (body.status) order.status = body.status;
+
+  return NextResponse.json(order);
+}
+
+export async function GET(request: Request) {
+  const url = new URL(request.url);
+  await latency();
+
+  if (url.searchParams.get("fail") === "1") {
+    return NextResponse.json({ error: "Bad Gateway" }, { status: 502 });
+  }
+
+  const query = parseQuery(url);
+
+  // Pull the bucket filter out and apply it here; the rest is the generic path.
+  const { items, ...rest } = query.filters;
+  const buckets = Array.isArray(items) ? items : [];
+  const source = buckets.length
+    ? ORDERS.filter((row) => buckets.some((bucket) => IN_BUCKET[bucket]?.(row.items)))
+    : ORDERS;
+
+  return NextResponse.json(
+    runQuery(source, { ...query, filters: rest }, {
+      searchPaths: ["customer.name", "status", "priority"],
+    }),
+  );
+}
+```