torch-glare 2.5.5 → 2.6.0

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

@@ -1,307 +0,0 @@
----
-title: DataViews example — Filters
-description: Every filter control, presets, custom filters and the summary.
-group: examples
-component: DataViews
-keywords: [data-views, example, examples, filters]
----
-
-# DataViews example — Filters
-
-Every filter control, presets, custom filters and the summary.
-
-Complete and runnable — this is the page itself, not an excerpt. In the monorepo it lives at `apps/app/data-views/filters/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,
-  FilterState,
-  FilterValue,
-  Row,
-} from "@/utils/dataViews/types";
-
-// ─── Data ─────────────────────────────────────────────────────────────────────
-
-interface Order extends Row {
-  id: number;
-  customer: { name: string };
-  status: "Pending" | "Shipped" | "Delivered";
-  priority: "High" | "Medium" | "Low";
-  total: number;
-  items: 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: "items", label: "Items", type: "number" },
-  { path: "total", label: "Total", type: "currency", currency: "USD" },
-  { path: "createdAt", label: "Created", type: "date-format", dateFormat: "YYYY-MM-DD" },
-];
-
-/**
- * The options each control offers. Supplied — DataViews never scans the dataset to find them, and
- * in a real app they come from the same endpoint that does the filtering.
- */
-/** 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 STATUS_OPTIONS = [
-  { label: "Pending", value: "Pending" },
-  { label: "Shipped", value: "Shipped" },
-  { label: "Delivered", value: "Delivered" },
-];
-
-const PRIORITY_OPTIONS = [
-  { label: "High", value: "High" },
-  { label: "Medium", value: "Medium" },
-  { label: "Low", value: "Low" },
-];
-
-/** Buckets for the custom control below — DataViews has no built-in for this. */
-/**
- * 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 buckets this picker offers. What each one *means* — which item counts fall in it — is the
- * endpoint's business, in `app/api/orders/route.ts`. The page sends the label; the server decides.
- */
-const BUCKETS = ["1–3", "4–10", "10+"];
-
-/** `Filters.Custom` renders whatever you like against this path's slot in `FilterState`. */
-function ItemsPicker({
-  value,
-  setValue,
-}: {
-  value: FilterValue | undefined;
-  setValue: (v: FilterValue | undefined) => void;
-}) {
-  const selected = Array.isArray(value) ? value : [];
-  return (
-    <div className="flex gap-1">
-      {BUCKETS.map((bucket) => (
-        <button
-          key={bucket}
-          type="button"
-          onClick={() => {
-            const next = selected.includes(bucket)
-              ? selected.filter((b) => b !== bucket)
-              : [...selected, bucket];
-            setValue(next.length ? next : undefined);
-          }}
-          className={[
-            "typography-body-small-regular rounded-[6px] border px-2 py-1 transition-colors",
-            selected.includes(bucket)
-              ? "border-transparent bg-background-presentation-action-selected text-content-presentation-global-primary"
-              : "border-border-presentation-global-primary text-content-presentation-global-secondary",
-          ].join(" ")}
-        >
-          {bucket}
-        </button>
-      ))}
-    </div>
-  );
-}
-
-// ─── Page ─────────────────────────────────────────────────────────────────────
-
-/**
- * The controls are real FormBuilder fields — `Select`, `MultiSelect`, `Slider`, `DateRange` — in
- * `CellContext`'s `"bare"` mode: no label row, no table borders. One set of inputs across the
- * design system.
- *
- * Three behaviours worth knowing:
- *
- * - **A slider at its bounds emits nothing.** Drag *Total* away from 0–15,000 and a `total` key
- *   appears; drag it back and the key vanishes, because "the whole range" and "no constraint" are
- *   the same query. The cost is that a filter genuinely meaning "0 to 15,000" is inexpressible —
- *   use `Filters.Custom` if you need that distinction.
- * - **Dates are local, not UTC.** You get the day you clicked; `toISOString()` would hand back the
- *   previous day for anyone east of Greenwich.
- * - **A parent may rewrite what it is handed.** Turn on *Normalising*: every emitted array comes
- *   back sorted. Because `Filters` debounces and compares before emitting, the rewritten value
- *   settles instead of ping-ponging — a control that echoed immediately would loop and eat every
- *   keystroke.
- *
- * The custom `items` key is owned by no declared control, and survives anyway: the built-in
- * controls merge over the paths in `fields` and leave everything else alone.
- */
-export default function FiltersExample() {
-  // Controlled, because this page starts with a filter no control owns and then rewrites what it
-  // is handed. Everywhere else `onQueryChange` alone is enough.
-  const [query, setQuery] = useState<DataViewsQuery>({
-    ...emptyQuery(),
-    filters: { items: ["10+"] },
-  });
-  const [saved, setSaved] = useState<SavedView[]>([]);
-  const [normalise, setNormalise] = useState(false);
-
-  /**
-   * A parent may rewrite what it is handed. With normalising on, every emitted list comes back
-   * sorted — and it settles rather than ping-ponging, because `Filters` debounces and compares
-   * before emitting again. A control that echoed immediately would loop and eat every keystroke.
-   */
-  const onQueryChange = (next: DataViewsQuery) => {
-    if (!normalise) return setQuery(next);
-    const filters: FilterState = {};
-    for (const [path, value] of Object.entries(next.filters)) {
-      filters[path] = Array.isArray(value) ? [...value].sort() : value;
-    }
-    setQuery({ ...next, filters });
-  };
-
-  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: ["filters-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;
-    },
-  });
-
-  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}
-        query={query}
-        onQueryChange={onQueryChange}
-        className="h-full"
-      >
-        <DataViews.Header title="Orders">
-          <DataViews.ViewSwitch />
-          <DataViews.Search />
-          <DataViews.Actions>
-            <Button variant="BluColStyle"
-              size="M"
-              onClick={() => setNormalise((v) => !v)}
-            >
-              {normalise ? "Normalising on" : "Normalising off"}
-            </Button>
-            <Button
-              variant="BluColStyle"
-              size="M"
-              onClick={() => setQuery({ ...emptyQuery(), filters: { items: ["10+"] } })}
-            >
-              Reset
-            </Button>
-          </DataViews.Actions>
-          <DataViews.PanelToggle />
-        </DataViews.Header>
-
-        {/* The active query, as removable chips — including the search term. */}
-        <div className="border-border-presentation-global-primary border-b px-4 py-2 empty:hidden">
-        </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. */}
-            <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 />}>
-            {/* Every kind of control, written as the FormBuilder fields they are. The
-                <FormBuilder> itself lives inside Filters — you supply its fields and nothing
-                else, 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"
-            >
-              {/* ① FIXED set, multi-pick → a checkbox list. The four statuses are fixed by the
-                  model; an org cannot add a fifth without a release. */}
-              <FormBuilder.CheckboxGroup name="status" label="Status" options={STATUS_OPTIONS} />
-
-              {/* ② FIXED set, single-pick → radios. High/Medium/Low are mutually exclusive, so
-                  picking two would be meaningless. Writes a one-element array. */}
-              <FormBuilder.RadioList name="priority" label="Priority" options={PRIORITY_OPTIONS} />
-
-              {/* ③ DYNAMIC set, single-pick → a searchable combobox. Customers are data-fed, so
-                  the list grows; one record has one customer, so one at a time is the natural pick. */}
-              <FormBuilder.SearchableSelect
-                name="customer.name"
-                label="Customer"
-                options={CUSTOMER_OPTIONS}
-              />
-
-              {/* ④ DYNAMIC set, multi-pick → BadgeField: search *and* several values, as chips.
-                  This is the control the enhancement request asked for; `MultiSelect` and `Tags`
-                  are the same field and both render it. */}
-              <FormBuilder.MultiSelect name="brand.name" label="Brand" options={BRAND_OPTIONS} />
-              <FormBuilder.Slider name="total" label="Total" range min={0} max={15000} step={100} />
-              <DataViews.Filters.Presets
-                for="total"
-                items={[
-                  { label: "Under $500", max: 500 },
-                  { label: "$5k+", min: 5000 },
-                ]}
-              />
-              <FormBuilder.DateRange name="createdAt" label="Created" />
-              <DataViews.Filters.Presets
-                for="createdAt"
-                items={[{ label: "September", from: "2025-09-01", to: "2025-09-30" }]}
-              />
-              <DataViews.Filters.Custom
-                path="items"
-                label="Item count"
-                render={({ value, setValue }) => <ItemsPicker value={value} setValue={setValue} />}
-              />
-            </DataViews.Filters>
-          </DataViews.Panel.Tab>
-        </DataViews.Panel>
-      </DataViews>
-    </div>
-  );
-}
-```

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

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

@@ -1,29 +0,0 @@
----
-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).