torch-glare 2.4.4 → 2.5.0

package/docs/components/data-views/examples/inbox-routing.md

@@ -0,0 +1,218 @@
+---
+title: DataViews example — Inbox → route
+description: `itemHref` + `linkComponent` — the detail pane driven by the URL.
+group: examples
+component: DataViews
+keywords: [data-views, example, examples, inbox, routing]
+---
+
+# DataViews example — Inbox → route
+
+`itemHref` + `linkComponent` — the detail pane driven by the URL.
+
+Complete and runnable — this is the page itself, not an excerpt. In the monorepo it lives at `apps/app/data-views/inbox-routing/page.tsx` and `apps/app/data-views/inbox-routing/[id]/page.tsx`.
+
+See the [component reference](../index.md) for what each prop does, or the [guide](../guide.md) for the same ground as scenarios.
+
+## `apps/app/data-views/inbox-routing/page.tsx`
+
+```tsx
+"use client";
+
+import { useMemo, useState } from "react";
+import Link from "next/link";
+import { useInfiniteQuery } from "@tanstack/react-query";
+import { Filter, Settings } from "lucide-react";
+import { DataViews, emptyQuery, queryToParams, type SavedView } from "@/components/DataViews";
+import { FormBuilder } from "@/components/FormBuilder";
+import type {
+  DataViewsQuery,
+  FieldConfig,
+  Row,
+} from "@/utils/dataViews/types";
+
+// ─── Data ─────────────────────────────────────────────────────────────────────
+
+interface Message extends Row {
+  id: string;
+  subject: string;
+  from: string;
+  preview?: string;
+  receivedAt?: string;
+}
+
+const FIELDS: FieldConfig[] = [
+  { path: "subject", label: "Subject", type: "text" },
+  { path: "from", label: "From", type: "text" },
+  { path: "preview", label: "Preview", type: "text" },
+  { path: "receivedAt", label: "Received", type: "date-format", dateFormat: "DD MMM" },
+];
+
+const FROM_OPTIONS = [
+  { label: "logistics@acme.test", value: "logistics@acme.test" },
+  { label: "ap@initech.test", value: "ap@initech.test" },
+  { label: "supply@umbrella.test", value: "supply@umbrella.test" },
+  { label: "procurement@hooli.test", value: "procurement@hooli.test" },
+  { label: "ops@cyberdyne.test", value: "ops@cyberdyne.test" },
+];
+
+/**
+ * The request this page makes. The querying happens in `app/api/messages/route.ts`.
+ */
+async function fetchMessages(q: DataViewsQuery): Promise<{ rows: Message[]; total: number }> {
+  const params = queryToParams(q);
+  const res = await fetch(`/api/messages?${params}`);
+  if (!res.ok) throw new Error(`${res.status} ${res.statusText}`);
+  return res.json();
+}
+
+// ─── Page ─────────────────────────────────────────────────────────────────────
+
+/**
+ * `itemHref` turns each row into a link and `linkComponent` swaps the plain anchor for the
+ * router's, so navigation stays client-side.
+ *
+ * Following one unmounts this page — the App Router replaces pages while keeping layouts — so the
+ * detail route has to stand on its own. Keeping the list beside the detail would mean hoisting
+ * `<DataViews>` into `inbox-routing/layout.tsx` and letting each page supply only the pane.
+ */
+export default function InboxRoutingExample() {
+  const [query, setQuery] = useState(emptyQuery());
+  const [saved, setSaved] = useState<SavedView[]>([]);
+
+
+  const { data, isPending, fetchNextPage, isFetchingNextPage } = useInfiniteQuery({
+    queryKey: ["messages", { ...query, page: undefined }],
+    queryFn: ({ pageParam }) => fetchMessages({ ...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;
+    },
+  });
+
+  const rows = useMemo(() => data?.pages.flatMap((page) => page.rows) ?? [], [data]);
+  const total = data?.pages[0]?.total ?? 0;
+
+  return (
+    <div className="flex h-full min-h-0 flex-col p-4">
+      <DataViews
+        rows={rows}
+        fields={FIELDS}
+        total={total}
+        loading={isPending}
+        onLoadMore={fetchNextPage}
+        loadingMore={isFetchingNextPage}
+        onQueryChange={setQuery}
+        className="h-full"
+      >
+        <DataViews.Header title="Inbox">
+          <DataViews.ViewSwitch />
+          <DataViews.Search />
+          <DataViews.PanelToggle />
+        </DataViews.Header>
+
+        <DataViews.Inbox
+          titlePath="subject"
+          datePath="receivedAt"
+          itemHref={(_row, id) => `/data-views/inbox-routing/${id}`}
+          linkComponent={Link}
+          placeholder={
+            <div className="typography-body-medium-regular text-content-presentation-global-secondary flex h-full items-center justify-center p-8">
+              Click a message to navigate to its own page.
+            </div>
+          }
+        />
+
+        <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. The <FormBuilder> itself lives inside Filters; you write only
+                its fields, and Filters reads each one's name, label and bounds to learn what
+                it is. */}
+            <DataViews.Filters
+              title={null}
+              className="border-b-0 p-0"
+            >
+              {/* A message carries no enum, no numeric field and one date, so only the
+                  searchable single-select, the date range and the text match have data to bind
+                  to. A checkbox list over a field that does not exist would filter to nothing. */}
+              <FormBuilder.Text name="subject" label="Subject contains" />
+              <FormBuilder.SearchableSelect name="from" label="From" options={FROM_OPTIONS} />
+              <FormBuilder.DateRange name="receivedAt" label="Received" />
+            </DataViews.Filters>
+          </DataViews.Panel.Tab>
+        </DataViews.Panel>
+      </DataViews>
+    </div>
+  );
+}
+```
+
+## `apps/app/data-views/inbox-routing/[id]/page.tsx`
+
+```tsx
+import Link from "next/link";
+import { notFound } from "next/navigation";
+import { MESSAGES } from "../../../api/_lib/messages";
+
+/**
+ * Where `itemHref` lands. A plain server-rendered page — no `DataViews` involved, because by this
+ * point the inbox has unmounted.
+ *
+ * This route is scoped to the one example that needs it. A `[id]` directly under `data-views/`
+ * would swallow every mistyped example slug and render a "detail" page instead of a 404.
+ *
+ * It reads the same store `/api/messages` serves rather than fetching from it: this already runs
+ * on the server, and a server component calling its own HTTP endpoint pays for a round trip to
+ * itself. The list page fetches because it runs in the browser.
+ */
+
+export default async function MessageDetailPage({ params }: { params: Promise<{ id: string }> }) {
+  const { id } = await params;
+  const message = MESSAGES.find((m) => m.id === id);
+  if (!message) notFound();
+
+  return (
+    <div className="flex h-full flex-col gap-4 overflow-y-auto p-8">
+      <Link
+        href="/data-views/inbox-routing"
+        className="typography-body-small-regular text-content-presentation-action-link flex w-fit items-center gap-1"
+      >
+        <i className="ri-arrow-left-line" aria-hidden />
+        Back to the inbox
+      </Link>
+
+      <article className="flex flex-col gap-3">
+        <h1 className="typography-headers-medium-medium text-content-presentation-global-primary">
+          {message.subject}
+        </h1>
+        <p className="typography-body-small-regular text-content-presentation-global-secondary">
+          {message.from}
+          {message.receivedAt ? ` · ${message.receivedAt}` : " · no date"}
+        </p>
+        <p className="typography-body-medium-regular text-content-presentation-global-primary max-w-[65ch]">
+          {message.preview ?? "This message has no preview text."}
+        </p>
+      </article>
+    </div>
+  );
+}
+```

package/docs/components/data-views/examples/index.md

@@ -0,0 +1,29 @@
+---
+title: DataViews examples
+description: Every runnable DataViews example page, as shipped documentation.
+group: examples
+component: DataViews
+keywords: [data-views, example, examples, index]
+---
+
+# DataViews examples
+
+Each page below is complete and runnable. They ship with the package, so the code an agent is pointed at is code it can actually read.
+
+| Example | Shows |
+| --- | --- |
+| [Views](./views.md) | All four views over one dataset, with drag round-trips. |
+| [Inbox → route](./inbox-routing.md) | `itemHref` + `linkComponent` — the detail pane driven by the URL. |
+| [Tree → custom UI](./tree-custom.md) | Every custom-UI seam of the tree: `renderNode`, `paneRows`, a custom cell, card and tab, `paneActions`, and a whole-pane override. |
+| [Fields](./fields.md) | The field types, painted. |
+| [Filters](./filters.md) | Every filter control, presets, custom filters and the summary. |
+| [Server-side](./server-side.md) | `queryToParams` on the way out, `parseQuery` on the way in. |
+| [Panel](./panel.md) | The settings rail: saved views, columns, sort — and the pane-mode round trip. |
+| [State](./state.md) | Controlled versus uncontrolled query. |
+| [View registry](./view-registry.md) | A view of your own via `markView`, beside the built-in four. |
+| [Scale](./scale.md) | Virtualization and scroll loading at size. |
+| [Keyboard & RTL](./a11y-rtl.md) | Keyboard paths and the RTL mirror. |
+| [Everything at once](./overview.md) | Every part at once — the fastest way to see the whole shape. |
+| [The endpoint these examples call](./api-orders-route.md) | The route handler every DataViews example fetches from — and the only worked example of `parseQuery` on the server. |
+
+See the [component reference](../index.md) and the [guide](../guide.md).

package/docs/components/data-views/examples/overview.md

@@ -0,0 +1,244 @@
+---
+title: DataViews example — Everything at once
+description: Every part at once — the fastest way to see the whole shape.
+group: examples
+component: DataViews
+keywords: [data-views, example, examples, overview]
+---
+
+# DataViews example — Everything at once
+
+Every part at once — the fastest way to see the whole shape.
+
+Complete and runnable — this is the page itself, not an excerpt. In the monorepo it lives at `apps/app/data-views/overview/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 { useMutation, useInfiniteQuery, useQueryClient } 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";
+
+// ─── Data ─────────────────────────────────────────────────────────────────────
+
+interface Order extends Row {
+  id: number;
+  customer: { name: string };
+  status: "Pending" | "Shipped" | "Delivered";
+  priority: "High" | "Medium" | "Low";
+  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: "priority", label: "Priority", type: "enum-badge", variants: { High: "redOrange", Medium: "purple", Low: "gray" } },
+  { path: "total", label: "Total", type: "currency", currency: "USD" },
+  { path: "createdAt", label: "Created", 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();
+}
+
+/** The other half of `onRowMove`: the board emits intent, this is what persists it. */
+async function moveOrder(body: { id?: number; status?: string; reset?: boolean }) {
+  const res = await fetch("/api/orders", {
+    method: "PATCH",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify(body),
+  });
+  if (!res.ok) throw new Error(`${res.status} ${res.statusText}`);
+  return res.json();
+}
+
+const groupByStatus = (rows: readonly Order[]): RowGroup[] =>
+  (["Pending", "Shipped", "Delivered", "Cancelled"] as const).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),
+  }));
+
+/** Every node is a real row here, so the detail pane fills whichever one you select. */
+const nodesFromRows = (rows: readonly Order[]): TreeNode[] => {
+  const [first, ...rest] = rows;
+  if (!first) return [];
+  return [
+    {
+      id: String(first.id),
+      row: first,
+      depth: 0,
+      children: rest.slice(0, 4).map((row) => ({ id: String(row.id), row, depth: 1, children: [] })),
+    },
+    ...rest.slice(4).map((row) => ({ id: String(row.id), row, depth: 0, children: [] })),
+  ];
+};
+
+// ─── Page ─────────────────────────────────────────────────────────────────────
+
+/** Every part at once: four views, the rail, filters, an empty state and a drag round-trip. */
+export default function OverviewExample() {
+  const queryClient = useQueryClient();
+  const [query, setQuery] = useState(emptyQuery());
+  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: ["overview-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]);
+
+  // Dropping a card emits intent; this is what persists it. The card settles where it landed
+  // only once the refetched rows agree.
+  const move = useMutation({
+    mutationFn: moveOrder,
+    onSuccess: () => queryClient.invalidateQueries({ queryKey: ["overview-orders"] }),
+  });
+
+  return (
+    <div className="flex h-full min-h-0 flex-col p-4">
+      <DataViews
+        rows={rows}
+        fields={FIELDS}
+        total={total}
+        loading={isPending}
+        onLoadMore={fetchNextPage}
+        loadingMore={isFetchingNextPage}
+        onQueryChange={setQuery}
+        className="h-full"
+      >
+        <DataViews.Header title="Orders">
+          <DataViews.ViewSwitch />
+          <DataViews.Search />
+          <DataViews.Actions>
+            <Button variant="BluColStyle" size="M">New order</Button>
+            <Button variant="BluColStyle" size="M" onClick={() => move.mutate({ reset: true })}>
+              Reset
+            </Button>
+          </DataViews.Actions>
+          <DataViews.PanelToggle />
+        </DataViews.Header>
+
+        <DataViews.Table selectable />
+        <DataViews.Board
+          groups={groups}
+          titlePath="customer.name"
+          // A drop outside any column has nowhere to go, so there is nothing to persist.
+          onRowMove={(intent) => {
+            if (intent.to) move.mutate({ id: Number(intent.id), status: intent.to });
+          }}
+        />
+        <DataViews.Inbox
+          titlePath="customer.name"
+          datePath="createdAt"
+        >
+          <DataViews.Detail />
+        </DataViews.Inbox>
+        {/* 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. The <FormBuilder> itself lives inside Filters; you write only
+                its fields, and Filters reads each one's name, label and bounds to learn what
+                it is. */}
+            <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>
+  );
+}
+```