torch-glare 2.4.5 → 2.5.1

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

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

@@ -0,0 +1,212 @@
+---
+title: DataViews example — Panel
+description: The settings rail: saved views, columns, sort — and the pane-mode round trip.
+group: examples
+component: DataViews
+keywords: [data-views, example, examples, panel]
+---
+
+# DataViews example — Panel
+
+The settings rail: saved views, columns, sort — and the pane-mode round trip.
+
+Complete and runnable — this is the page itself, not an excerpt. In the monorepo it lives at `apps/app/data-views/panel/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 { DataViews, emptyQuery, queryToParams, type SavedView } from "@/components/DataViews";
+import { FormBuilder } from "@/components/FormBuilder";
+import type {
+  DataViewsQuery,
+  FieldConfig,
+  Row,
+  RowGroup,
+  TreeNode,
+} from "@/utils/dataViews/types";
+
+// ─── How the rows are painted ─────────────────────────────────────────────────
+
+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 happens in `app/api/orders/route.ts`. */
+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 ─────────────────────────────────────────────────────────────────────
+
+/**
+ * The rail: columns, sort and saved views, in tabs that exist because they are rendered.
+ *
+ * **None of what the rail edits is this page's business.** Column order and visibility, which tab
+ * is open, whether the rail is open at all — those change the picture and nothing else, so the
+ * component holds them. That is why there are two `useState`s here: the query, and the saved views
+ * the app persists.
+ *
+ * Hiding `Customer` retitles the board's cards and the tree's nodes too: `columns` resolves to the
+ * ordered `visibleFields` every view paints from, so it is shared by construction.
+ *
+ * **Saved views are the exception that proves the rule.** Persisting one is the app's job — it
+ * outlives the component — so `onSave` hands over a snapshot to store. Restoring is *not*: hand the
+ * snapshot back in `views` and selecting it puts the columns, sort and filters back internally. The
+ * blob is opaque here on purpose.
+ */
+export default function PanelExample() {
+  const [query, setQuery] = useState(emptyQuery());
+  const [saved, setSaved] = useState<SavedView[]>([]);
+
+  // The tree pane's shape, seeded from storage and written back on every switch. `defaultPaneMode`
+  // is read once — the view holds the mode from then on — so this reads the store lazily rather
+  // than in an effect, which would seed `"table"` for a frame and then flip.
+  const [paneMode] = useState<"table" | "cards">(() =>
+    (typeof window !== "undefined" && localStorage.getItem("panel-pane-mode")) === "cards"
+      ? "cards"
+      : "table",
+  );
+
+  const { data, isPending, fetchNextPage, isFetchingNextPage } = useInfiniteQuery({
+    queryKey: ["panel-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 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}
+        defaultPanelOpen
+        className="h-full"
+      >
+        <DataViews.Header title="Orders">
+          <DataViews.ViewSwitch />
+          <DataViews.Search />
+          <DataViews.PanelToggle />
+        </DataViews.Header>
+
+        <DataViews.Table />
+        <DataViews.Board groups={groups} titlePath="customer.name" />
+        <DataViews.Tree
+          nodes={nodes}
+          labelPath="customer.name"
+          defaultPaneMode={paneMode}
+          onPaneModeChange={(mode) => localStorage.setItem("panel-pane-mode", mode)}
+        >
+          <DataViews.Tree.Table />
+          <DataViews.Tree.Cards />
+        </DataViews.Tree>
+
+        <DataViews.Panel>
+          <DataViews.Panel.Tab value="config" label="Config." icon={<Settings />}>
+            <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 />}>
+            <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>
+
+          {/* Not inside a Tab, so it renders under whichever one is open. */}
+          <div className="border-border-presentation-global-primary mt-auto border-t pt-2">
+            <span className="typography-body-small-regular text-content-presentation-global-secondary">
+              Shown on every tab.
+            </span>
+          </div>
+        </DataViews.Panel>
+      </DataViews>
+    </div>
+  );
+}
+```