torch-glare 2.5.5 → 2.6.0

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

@@ -1,231 +0,0 @@
----
-title: DataViews example — Scale
-description: Virtualization and scroll loading at size.
-group: examples
-component: DataViews
-keywords: [data-views, example, examples, scale]
----
-
-# DataViews example — Scale
-
-Virtualization and scroll loading at size.
-
-Complete and runnable — this is the page itself, not an excerpt. In the monorepo it lives at `apps/app/data-views/scale/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,
-} from "@/utils/dataViews/types";
-
-// ─── How the two datasets are painted ─────────────────────────────────────────
-
-/**
- * The rows themselves are generated and paged by `app/api/scale/route.ts`. What stays here is how
- * to paint them — that is presentation, and it is the same whether one row comes back or a
- * thousand.
- */
-const ROW_FIELDS: FieldConfig[] = [
-  { path: "reference", label: "Reference", type: "text" },
-  { path: "customer", label: "Customer", 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: "items", label: "Items", type: "number" },
-  { path: "progress", label: "Progress", type: "progress-bar", max: 100, thresholds: [30, 80] },
-  { path: "createdAt", label: "Created", type: "date-format", dateFormat: "YYYY-MM-DD" },
-];
-
-/** Forty columns, generated — hand-writing them guarantees one ends up subtly different. */
-const WIDE_FIELDS: FieldConfig[] = Array.from({ length: 40 }, (_, i) => ({
-  path: `col${i}`,
-  label: i % 5 === 0 ? `Column ${i} with a deliberately long header label` : `Column ${i}`,
-  type: "text" as const,
-}));
-
-/** Generated data, so the option sets are the generator's own vocabulary. */
-const PRIORITY_OPTIONS = ["High", "Medium", "Low"].map((v) => ({ label: v, value: v }));
-const CUSTOMER_OPTIONS = ["Acme", "Globex", "Initech", "Umbrella", "Hooli", "Soylent", "Stark", "Wayne", "Cyberdyne"]
-  .flatMap((c) => ["Inc.", "Ltd", "SA", "GmbH", "BV"].map((sfx) => `${c} ${sfx}`))
-  .map((v) => ({ label: v, value: v }));
-
-const STATUS_OPTIONS = [
-  { label: "Pending", value: "Pending" },
-  { label: "Shipped", value: "Shipped" },
-  { label: "Delivered", value: "Delivered" },
-];
-
-// ─── The request ──────────────────────────────────────────────────────────────
-
-/**
- * The request this page makes. Generating, filtering, sorting and paging all happen in
- * `app/api/scale/route.ts`.
- *
- * This is the case where the two large-dataset answers both show up. Rows arrive a page at a time
- * as you scroll — `useInfiniteQuery` accumulates them and the component only ever paints what it
- * was handed — and once enough have accumulated the table virtualises, so the DOM holds a window
- * of rows rather than all of them.
- */
-async function fetchScale(q: DataViewsQuery & {
-  shape: "rows" | "wide";
-  count: number;
-}): Promise<{ rows: Row[]; total: number }> {
-  const params = queryToParams(q);
-  params.set("shape", q.shape);
-  params.set("count", String(q.count));
-  const res = await fetch(`/api/scale?${params}`);
-  if (!res.ok) throw new Error(`${res.status} ${res.statusText}`);
-  return res.json();
-}
-
-/**
- * This example starts bigger than the default ten, and a hundred at a time is enough that a few
- * scrolls carry it past the table's virtualization threshold — which is the thing this page is
- * here to exercise. The same object seeds the page's state and the component's, because two
- * literals saying "100" is precisely how they come to disagree.
- */
-const INITIAL_QUERY = emptyQuery({ pageSize: 100 });
-
-// ─── Page ─────────────────────────────────────────────────────────────────────
-
-/**
- * The two axes that hurt.
- *
- * **Rows.** There is no virtualisation: every row handed in is rendered. With the endpoint paging,
- * that is fifty at a time no matter how large the table gets — which is what the component was
- * built for. Set the page size to 500 and you can feel the difference the paging was making.
- *
- * **Columns.** Forty of them scroll inside the view rather than growing the page, cells do not
- * truncate, and the rail's column list carries all forty. Paging does nothing for this axis.
- */
-export default function ScaleExample() {
-  const [kase, setCase] = useState<"rows" | "columns">("rows");
-  const [count, setCount] = useState(1000);
-  const [narrow, setNarrow] = useState(false);
-
-  const [query, setQuery] = useState(INITIAL_QUERY);
-  const [saved, setSaved] = useState<SavedView[]>([]);
-
-  const wideCase = kase === "columns";
-  const shape = wideCase ? "wide" : "rows";
-
-  const { data, isPending, fetchNextPage, isFetchingNextPage } = useInfiniteQuery({
-    // `shape` and `count` are part of the question, so switching case or size refetches rather
-    // than handing back a cached answer to a different one. `page` is deliberately *not* in the
-    // key — it is what `pageParam` drives, and keying on it would throw the accumulation away on
-    // every load.
-    queryKey: ["scale", { ...query, page: undefined, shape, count }],
-    initialPageParam: 1,
-    queryFn: ({ pageParam }) => fetchScale({ ...query, page: pageParam, shape, count }),
-    // Undefined means "no more", which is what `hasMore` on the component resolves to.
-    getNextPageParam: (last, pages) => {
-      const loaded = pages.reduce((n, page) => n + page.rows.length, 0);
-      return loaded < last.total ? pages.length + 1 : undefined;
-    },
-  });
-
-  // The component is handed every row loaded so far, in order. Accumulating is the app's job —
-  // DataViews paints what it is given and asks for more when the user reaches the end.
-  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">
-      <div className={narrow && wideCase ? "flex min-h-0 w-[320px] flex-1" : "flex min-h-0 flex-1"}>
-        <DataViews
-          // Remounting per case keeps columns and filters from leaking between datasets.
-          key={kase}
-          rows={rows}
-          fields={wideCase ? WIDE_FIELDS : ROW_FIELDS}
-          total={total}
-          loading={isPending}
-          onLoadMore={fetchNextPage}
-          loadingMore={isFetchingNextPage}
-          onQueryChange={setQuery}
-          defaultQuery={INITIAL_QUERY}
-          className="h-full"
-        >
-          <DataViews.Header title={wideCase ? "Wide" : `${total.toLocaleString("en-US")} rows`}>
-            <DataViews.ViewSwitch />
-            <DataViews.Search />
-            <DataViews.Actions>
-              <Button variant="BluColStyle" size="M" onClick={() => setCase("rows")}>
-                1,000 rows
-              </Button>
-              <Button variant="BluColStyle" size="M" onClick={() => setCase("columns")}>
-                40 columns
-              </Button>
-              {!wideCase &&
-                [100, 1000].map((n) => (
-                  <Button variant="BluColStyle"
-                    size="M"
-                    key={n}
-                    onClick={() => setCount(n)}
-                  >
-                    {n.toLocaleString("en-US")}
-                  </Button>
-                ))}
-              {wideCase && (
-                <Button variant="BluColStyle" size="M" onClick={() => setNarrow((v) => !v)}>
-                  {narrow ? "Full width" : "Squeeze"}
-                </Button>
-              )}
-            </DataViews.Actions>
-            <DataViews.PanelToggle />
-          </DataViews.Header>
-
-          <DataViews.Table />
-
-          {/* `total` is the filtered count from the endpoint — the component holds fifty rows and
-              could not work out that there are 1,000. */}
-
-          <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 two cases offer different columns, so they offer different filters. */}
-              <DataViews.Filters
-                title={null}
-                className="border-b-0 p-0"
-              >
-              {/* The same section types, over this page's own fields. There is no second dynamic
-                  categorical here, so the searchable single-select has nothing to bind to. */}
-              <FormBuilder.CheckboxGroup name="status" label="Status" options={STATUS_OPTIONS} />
-              <FormBuilder.RadioList name="priority" label="Priority" options={PRIORITY_OPTIONS} />
-              <FormBuilder.MultiSelect name="customer" label="Customer" options={CUSTOMER_OPTIONS} />
-              <FormBuilder.Slider name="total" label="Total" range min={0} max={25000} step={500} />
-              <FormBuilder.DateRange name="createdAt" label="Created" />
-              </DataViews.Filters>
-            </DataViews.Panel.Tab>
-          </DataViews.Panel>
-        </DataViews>
-      </div>
-    </div>
-  );
-}
-```

package/docs/components/data-views/examples/server-side.md

@@ -1,210 +0,0 @@
----
-title: DataViews example — Server-side
-description: `queryToParams` on the way out, `parseQuery` on the way in.
-group: examples
-component: DataViews
-keywords: [data-views, example, examples, server, side]
----
-
-# DataViews example — Server-side
-
-`queryToParams` on the way out, `parseQuery` on the way in.
-
-Complete and runnable — this is the page itself, not an excerpt. In the monorepo it lives at `apps/app/data-views/server-side/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,
-} from "@/utils/dataViews/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" },
-];
-
-/** 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 & { fail: boolean }): Promise<{ rows: Order[]; total: number }> {
-  const params = queryToParams(q);
-  // The endpoint answers 502 for this — the failure is server-side, as it would be.
-  if (q.fail) params.set("fail", "1");
-  const res = await fetch(`/api/orders?${params}`);
-  if (!res.ok) throw new Error(`${res.status} ${res.statusText}`);
-  return res.json();
-}
-
-// ─── Page ─────────────────────────────────────────────────────────────────────
-
-/**
- * The shape the component is built for: filters, search and sort are three callbacks that trigger
- * one query, and nothing on screen changes until the response lands.
- *
- * The query key carries the whole query, so TanStack refetches when any part of it changes and
- * discards a response that has been superseded — the out-of-order problem you would otherwise
- * solve by hand with a request counter.
- *
- * `    keepPreviousData` is what makes it feel right: the previous rows stay while
- * the next query runs, instead of the table emptying on every keystroke. `isPending` is true only
- * for the very first load, which is why the skeletons appear once and not on every refetch.
- *
- * There is no `DataViews.Error` — an error is an ordinary child, rendered above the view so the
- * header and rail stay usable while the request is broken. Filter changes are already debounced
- * ~200ms inside `Filters`; sorting and searching are not, so add your own if the endpoint is
- * expensive.
- */
-export default function ServerSideExample() {
-  const [query, setQuery] = useState(emptyQuery());
-  const [saved, setSaved] = useState<SavedView[]>([]);
-
-  const [failNext, setFailNext] = useState(false);
-
-
-  const { data, isPending, error, fetchNextPage, isFetchingNextPage } = useInfiniteQuery({
-    // `failNext` belongs in the key: flipping it asks a different question of the endpoint, and
-    // without it the cached answer would come straight back unchanged.
-    queryKey: ["server-side-orders", { ...query, page: undefined, failNext }],
-    queryFn: ({ pageParam }) => fetchOrders({ ...query, page: pageParam, fail: failNext }),
-    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;
-    },
-    // A 502 here is the point of the example, not a blip to paper over.
-    retry: false,
-  });
-
-  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="Orders">
-          <DataViews.ViewSwitch />
-          <DataViews.Search />
-          <DataViews.Actions>
-            <Button variant="BluColStyle"
-              size="M"
-              onClick={() => setFailNext((v) => !v)}
-            >
-              {failNext ? "Stop failing" : "Make it fail"}
-            </Button>
-          </DataViews.Actions>
-          <DataViews.PanelToggle />
-        </DataViews.Header>
-
-        {error && (
-          <div
-            data-testid="error"
-            className="typography-body-small-regular border-border-presentation-state-negative bg-background-presentation-state-negative-secondary text-content-presentation-global-primary m-4 flex items-center gap-2 rounded-[8px] border px-3 py-2"
-          >
-            <i className="ri-error-warning-line" aria-hidden />
-            Could not load orders — {error.message}
-          </div>
-        )}
-
-        <DataViews.Table />
-
-        <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. */}
-            {/* 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>
-  );
-}
-```