torch-glare 2.4.4 → 2.5.0

package/apps/lib/utils/dataViews/path.ts

@@ -0,0 +1,67 @@
+import type { Path, Row } from "./types";
+
+/**
+ * Split cache. Bounded on purpose — the previous implementation used an unbounded module-level
+ * `Map`, which in a long-lived app grows for every distinct path string it ever sees. Paths come
+ * from a fixed field config in practice, so a small cap costs nothing and removes the leak.
+ */
+const CACHE_LIMIT = 512;
+const cache = new Map<string, string[]>();
+
+function split(path: Path): string[] {
+  const hit = cache.get(path);
+  if (hit) return hit;
+  const parts = path.split(".");
+  if (cache.size >= CACHE_LIMIT) cache.clear();
+  cache.set(path, parts);
+  return parts;
+}
+
+/** Read a dotted path off a row. Returns `undefined` for any missing link in the chain. */
+export function getByPath(obj: unknown, path: Path | undefined | null): unknown {
+  if (obj == null || path == null || path === "") return undefined;
+  if (typeof obj !== "object") return undefined;
+  let cur: unknown = obj;
+  for (const key of split(path)) {
+    if (cur == null) return undefined;
+    cur = (cur as Record<string, unknown>)[key];
+  }
+  return cur;
+}
+
+/** Read a path and coerce to string for display/compare. `undefined`/`null` become `""`. */
+export function getString(obj: unknown, path: Path | undefined | null): string {
+  const v = getByPath(obj, path);
+  return v == null ? "" : String(v);
+}
+
+/** `"created_at"` / `"createdAt"` → `"Created At"`. Uses the last segment of a dotted path. */
+export function formatPathLabel(path: Path): string {
+  if (!path) return "";
+  const tail = path.includes(".") ? path.split(".").pop()! : path;
+
+  if (tail.includes("_")) {
+    return tail
+      .split("_")
+      .filter(Boolean)
+      .map((w) => w.charAt(0).toUpperCase() + w.slice(1))
+      .join(" ");
+  }
+
+  return tail
+    .replace(/([A-Z])/g, " $1")
+    .replace(/^./, (s) => s.toUpperCase())
+    .trim();
+}
+
+/**
+ * The default row identity: the first of `row.id`, `row._id`, `row.uuid`, else the array index.
+ *
+ * The previous implementation fell back through three candidates ending in the array index, so
+ * selection and drag-and-drop both broke the moment rows were reordered. Pass `getRowId` when
+ * your id lives elsewhere.
+ */
+export function defaultGetRowId(row: Row, index: number): string {
+  const id = row.id ?? row._id ?? row.uuid;
+  return id == null ? String(index) : String(id);
+}

package/apps/lib/utils/dataViews/query.ts

@@ -0,0 +1,73 @@
+import type { DataViewsQuery, FilterState, Sort } from "./types";
+
+/**
+ * The wire format for a `DataViewsQuery`, both directions.
+ *
+ * A query is written in the browser and read on the server, and the two have to agree exactly.
+ * Keeping the encoder and the decoder in one file is what makes that true by construction —
+ * split across a page and a route handler, they drift the first time either side gains a field.
+ *
+ * No React here, like its neighbours `path.ts` and `types.ts`, so a route handler can import it.
+ */
+
+/** A query nobody has touched yet: everything, first page. */
+export function emptyQuery(overrides?: Partial<DataViewsQuery>): DataViewsQuery {
+  return { search: "", filters: {}, sort: null, page: 1, pageSize: 10, ...overrides };
+}
+
+/**
+ * Browser → wire.
+ *
+ * `filters` goes as JSON because it is a nested structure, not a flat list of values. `sort` goes
+ * as `total:desc` — one parameter rather than two, since neither half means anything alone.
+ *
+ * Extra parameters an endpoint of your own needs are yours to append:
+ *
+ * ```ts
+ * const params = queryToParams(query);
+ * params.set("shape", "wide");
+ * ```
+ */
+export function queryToParams(query: DataViewsQuery): URLSearchParams {
+  return new URLSearchParams({
+    search: query.search,
+    filters: JSON.stringify(query.filters),
+    sort: query.sort ? `${query.sort.path}:${query.sort.direction}` : "",
+    page: String(query.page),
+    pageSize: String(query.pageSize),
+  });
+}
+
+/**
+ * Wire → server.
+ *
+ * Malformed `filters` is treated as "no filters" rather than a 400: a filter you cannot parse
+ * should not take the page down. `pageSize` is clamped, because it arrives from the client and a
+ * request for a million rows is a request to fall over.
+ */
+export function parseQuery(url: URL): DataViewsQuery {
+  const params = url.searchParams;
+
+  let filters: FilterState = {};
+  const raw = params.get("filters");
+  if (raw) {
+    try {
+      filters = JSON.parse(raw) as FilterState;
+    } catch {
+      filters = {};
+    }
+  }
+
+  const [sortPath, sortDir] = (params.get("sort") ?? "").split(":");
+  const sort: Sort = sortPath
+    ? { path: sortPath, direction: sortDir === "desc" ? "desc" : "asc" }
+    : null;
+
+  return {
+    search: params.get("search") ?? "",
+    filters,
+    sort,
+    page: Math.max(1, Number(params.get("page")) || 1),
+    pageSize: Math.min(500, Math.max(1, Number(params.get("pageSize")) || 10)),
+  };
+}

package/apps/lib/utils/dataViews/types.ts

@@ -0,0 +1,187 @@
+/**
+ * The vocabulary DataViews speaks — nothing more.
+ *
+ * DataViews does no data work: it never filters, searches, sorts, groups, or infers a schema.
+ * Those are the app's job, almost always server-side. What is described here is only what the
+ * component needs in order to **paint** rows and to **emit intent** back to you:
+ * `FilterState` and `Sort` are things it hands you so you can go and query, not things it applies.
+ *
+ * These types live in the utils layer so the dependency runs one way — the component imports its
+ * vocabulary from here, and nothing here imports React or any component.
+ */
+
+import type { ReactNode } from "react";
+
+/** A row is any record. DataViews never assumes a shape beyond the id resolved by `getRowId`. */
+export type Row = Record<string, unknown>;
+
+/** A dotted accessor into a row, e.g. `"customer.name"`. */
+export type Path = string;
+
+export type FieldType =
+  | "text"
+  | "number"
+  | "date"
+  | "boolean"
+  | "hidden"
+  | "enum-badge"
+  | "badge-array"
+  | "currency"
+  | "number-format"
+  | "progress-bar"
+  | "star-rating"
+  | "icon-text"
+  | "two-line"
+  | "avatar"
+  | "link"
+  | "image"
+  | "date-format";
+
+export type BadgeVariant =
+  | "green"
+  | "greenLight"
+  | "cocktailGreen"
+  | "yellow"
+  | "redOrange"
+  | "redLight"
+  | "rose"
+  | "purple"
+  | "bluePurple"
+  | "blue"
+  | "navy"
+  | "gray"
+  | "highlight";
+
+/** Palette keys for a board column pill. */
+export type ColumnColor = "gray" | "purple" | "orange" | "blue" | "green" | "red";
+
+export type CurrencyOptions = {
+  symbol?: string;
+  locale?: string;
+  decimals?: number;
+  code?: string;
+};
+
+/** How one field is read and painted. You author these — nothing is inferred from the data. */
+export type FieldConfig = {
+  path: Path;
+  label?: string;
+  type?: FieldType;
+  visible?: boolean;
+
+  /** Value → badge colour, for `enum-badge` / `badge-array`. */
+  variants?: Record<string, BadgeVariant>;
+  defaultVariant?: BadgeVariant;
+  variant?: BadgeVariant;
+
+  limit?: number;
+  currency?: string | CurrencyOptions;
+  format?: Intl.NumberFormatOptions;
+  thresholds?: [number, number];
+  max?: number;
+  icon?: string;
+  iconPosition?: "before" | "after";
+  secondaryPath?: Path;
+  linkType?: "mailto" | "tel" | "url";
+  fallbackPath?: Path;
+  dateFormat?: string | Intl.DateTimeFormatOptions;
+  trueLabel?: string;
+  falseLabel?: string;
+  trueVariant?: BadgeVariant;
+  falseVariant?: BadgeVariant;
+
+  /** Paint this field yourself. Wins over `type`. */
+  render?: (value: unknown, row: Row) => ReactNode;
+};
+
+/** A column as the user has arranged it — the projection the config panel edits. */
+export type ColumnState = {
+  path: Path;
+  label: string;
+  visible: boolean;
+};
+
+type SortDirection = "asc" | "desc";
+/** Which column the header shows as sorted. Emitted on click; the component never re-orders rows. */
+export type Sort = { path: Path; direction: SortDirection } | null;
+
+type NumericRange = { kind: "number"; min?: number; max?: number };
+type DateRange = { kind: "date"; from?: string; to?: string };
+type RangeValue = NumericRange | DateRange;
+/** A categorical selection, or a range. */
+export type FilterValue = string[] | RangeValue;
+/** Keyed by field path. */
+export type FilterState = Record<Path, FilterValue>;
+
+/** A one-click shortcut on a numeric filter, e.g. "Under 500". */
+export type NumberPreset = { label: string; min?: number; max?: number };
+/** A one-click shortcut on a date filter, e.g. "Last 30 days". */
+export type DatePreset = { label: string; from?: string; to?: string };
+/** `Filters.Presets` takes both shapes; each control renders the ones it understands. */
+export type Preset = NumberPreset | DatePreset;
+
+/**
+ * Everything the user asked for, in one object.
+ *
+ * This is the whole contract between `DataViews` and your data layer. The component collects it —
+ * a search typed in the header, filters set in the rail, a column header clicked, a page turned —
+ * and hands it over whole; going and fetching the matching rows is your half.
+ *
+ * It is one object rather than five callbacks because it is one question. A query with a new
+ * filter and a stale page number is not a query anyone meant to ask, and keeping the parts
+ * together is what lets the component keep them consistent — changing a filter resets `page` to 1,
+ * because a different result set has no page 4 to stay on.
+ */
+export interface DataViewsQuery {
+  search: string;
+  filters: FilterState;
+  sort: Sort;
+  /** 1-based. */
+  page: number;
+  pageSize: number;
+}
+
+/** How a filter maps between its control's value and `FilterState`. */
+type FilterKind = "choice" | "number" | "date" | "text";
+
+/**
+ * What `DataViews.Filters` learned about one of its children.
+ *
+ * You never write these: filters are authored as `FormBuilder` fields, and `Filters` reads each
+ * child's `name`, `label` and bounds off the element to build this. It exists because the mapping
+ * to `FilterState` needs to know a slider from a multi-select — a `[0, 500]` is a numeric range,
+ * while `["a", "b"]` is a selection, and the two are indistinguishable once they are just values.
+ */
+export type FilterFieldDescriptor = {
+  path: Path;
+  label?: string;
+  kind: FilterKind;
+  /** Single-valued choice (`FormBuilder.Select`) rather than multi (`.MultiSelect`). */
+  single?: boolean;
+  /** Slider bounds, read from the child. A slider resting on them emits no filter at all. */
+  min?: number;
+  max?: number;
+};
+
+export type TreeNode = {
+  id: string;
+  row: Row;
+  children: TreeNode[];
+  depth: number;
+};
+
+/** Emitted by a board or tree drag. The component never applies it. */
+export type MoveIntent = {
+  id: string;
+  from: string | null;
+  to: string | null;
+  index?: number;
+};
+
+/** A pre-grouped column for the board view. You build these; the component only paints them. */
+export type RowGroup = {
+  id: string;
+  label: string;
+  color?: ColumnColor;
+  rows: Row[];
+};

package/docs/components/breadcrumb.md

@@ -1,6 +1,6 @@
 ---
 name: Breadcrumb
-version: 2.4.0
+version: 2.4.5
 status: stable
 category: components/navigation
 tags: [navigation, breadcrumb, wayfinding, compound, accessible, rtl]

package/docs/components/button-group.md

@@ -1,6 +1,6 @@
 ---
 name: ButtonGroup
-version: 2.4.0
+version: 2.4.5
 status: stable
 category: components/buttons
 tags: [toggle-group, button-group, selection, radix-ui, accessible, compound]

package/docs/components/button.md

@@ -1,6 +1,6 @@
 ---
 name: Button
-version: 2.4.0
+version: 2.4.5
 status: stable
 category: components/buttons
 tags: [interactive, form, action, accessible, polymorphic]

package/docs/components/card.md

@@ -1,6 +1,6 @@
 ---
 name: Card
-version: 2.4.0
+version: 2.4.5
 status: stable
 category: components/layout
 tags: [container, layout, card, content, polymorphic]

package/docs/components/checkbox.md

@@ -1,6 +1,6 @@
 ---
 name: Checkbox
-version: 2.4.0
+version: 2.4.5
 status: stable
 category: components/forms
 tags: [form, checkbox, selection, radix-ui, accessible, controlled]

package/docs/components/data-views/backend-response.md

@@ -0,0 +1,324 @@
+---
+title: Render a backend response with DataViews
+description: Recipes for turning common backend JSON shapes into a DataViews screen — flat lists, status fields, nested objects, hierarchies, message shapes, and server-driven filtering and paging.
+group: how-to
+keywords: [data-views, dataviews, recipes, backend, json, api, flat, nested, hierarchy, inbox, board, kanban, server-side, filtering, pagination, how-to]
+---
+
+# Render a backend response with DataViews
+
+[`DataViews`](./index.md) shows one dataset as a table, a kanban board, an inbox or
+a tree. This guide maps the JSON you get back from an API to what you render.
+
+One rule governs every recipe below, so it is worth stating first: **DataViews never reshapes your
+data.** It does not group rows into columns, build a hierarchy, infer a schema, filter, sort or
+page. It paints the `rows` you hand it, in the order you hand them, using the `fields` you describe.
+Anything shaped — `groups`, `nodes` — you build. That is what makes a failed save leave the screen
+showing the truth.
+
+## TL;DR
+
+```tsx
+const { data } = useQuery({ queryKey: ["records"], queryFn: () => api.get("/records") });
+
+<DataViews rows={data?.rows ?? []} total={data?.total ?? 0} fields={FIELDS}>
+  <DataViews.Header title="Records">
+    <DataViews.ViewSwitch />
+    <DataViews.Search />
+    <DataViews.PanelToggle />
+  </DataViews.Header>
+  <DataViews.Table />
+</DataViews>
+```
+
+`fields` is the one thing with no default — DataViews will not guess your columns:
+
+```ts
+const FIELDS: FieldConfig[] = [
+  { path: "id", label: "ID", type: "number" },
+  { path: "name", label: "Name" },
+  { path: "createdAt", label: "Created", type: "date-format", dateFormat: "YYYY-MM-DD" },
+];
+```
+
+## Recipe 1 — A flat list of objects
+
+The common case. Every field you list becomes a column, in the order you list it.
+
+```json
+[{ "id": 1, "name": "Acme", "total": 1240, "createdAt": "2025-09-10" }]
+```
+
+```tsx
+const FIELDS: FieldConfig[] = [
+  { path: "id", label: "Order #", type: "number" },
+  { path: "name", label: "Customer" },
+  { path: "total", label: "Total", type: "currency", currency: "USD" },
+  { path: "createdAt", label: "Created", type: "date-format", dateFormat: "YYYY-MM-DD" },
+];
+
+<DataViews rows={rows} total={rows.length} fields={FIELDS}>
+  <DataViews.Header title="Orders"><DataViews.ViewSwitch /></DataViews.Header>
+  <DataViews.Table selectable />
+</DataViews>
+```
+
+If your rows have no `id`, tell the component what identity is — selection, drag and the open row
+all key off it:
+
+```tsx
+<DataViews rows={rows} fields={FIELDS} getRowId={(row) => String(row.sku)}>
+```
+
+## Recipe 2 — A status field → a board
+
+The board takes **columns you built**. Grouping is a decision (which statuses exist, in what order,
+what an empty column means) that only you can make correctly.
+
+```json
+[{ "id": 1, "status": "Pending" }, { "id": 2, "status": "Shipped" }]
+```
+
+```tsx
+const STATUSES = ["Pending", "Shipped", "Delivered", "Cancelled"] as const;
+
+const groups = useMemo<RowGroup[]>(
+  () =>
+    STATUSES.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),
+    })),
+  [rows],
+);
+
+<DataViews.Board
+  groups={groups}
+  titlePath="name"
+  onRowMove={(intent) => {
+    if (intent.to) move.mutate({ id: Number(intent.id), status: intent.to });
+  }}
+/>
+```
+
+`onRowMove` reports **intent**. The card settles where it landed only once your refetched rows
+agree — which is exactly why a rejected move snaps back on its own.
+
+Paint the same field as a coloured chip in the table by giving it a type:
+
+```ts
+{ path: "status", label: "Status", type: "enum-badge",
+  variants: { Pending: "yellow", Shipped: "blue", Delivered: "green" } }
+```
+
+## Recipe 3 — Nested objects → dotted paths
+
+No flattening step. A `path` reads as deep as you need.
+
+```json
+[{ "id": 1, "customer": { "name": "Acme", "email": "a@acme.com" }, "brand": { "name": "Bosch" } }]
+```
+
+```ts
+const FIELDS: FieldConfig[] = [
+  { path: "customer.name", label: "Customer" },
+  { path: "customer.email", label: "Email", type: "link", linkType: "mailto" },
+  { path: "brand.name", label: "Brand" },
+];
+```
+
+Dotted paths work anywhere a path is taken — `titlePath`, `datePath`, `labelPath`, `sort.path` and
+the keys of `filters`.
+
+> **The one place `.` is special.** `DataViews.Filters` builds its controls with `FormBuilder`, and
+> react-hook-form reads `.` as object nesting — so a filter on `customer.name` registers as
+> `customer__name`. You still write the real path; only a hand-rolled `setValue` needs the escaped
+> name.
+
+## Recipe 4 — A hierarchy → `nodes`
+
+Nested `children[]` or a flat `parentId` list both become `TreeNode[]`, and **you** do the
+conversion: which field is the parent key, whether orphans become roots and how cycles are handled
+are decisions the component cannot make for you.
+
+```json
+[{ "id": "1", "name": "Tools", "children": [{ "id": "2", "name": "Drills", "children": [] }] }]
+```
+
+```tsx
+const toNodes = (items: ApiCategory[], depth = 0): TreeNode[] =>
+  items.map((item) => ({
+    id: item.id,
+    row: item as Row,
+    depth,
+    children: toNodes(item.children ?? [], depth + 1),
+  }));
+```
+
+From a flat `parentId` list:
+
+```tsx
+const toNodes = (items: ApiCategory[]): TreeNode[] => {
+  const byId = new Map(items.map((i) => [i.id, { id: i.id, row: i as Row, depth: 0, children: [] as TreeNode[] }]));
+  const roots: TreeNode[] = [];
+  for (const item of items) {
+    const node = byId.get(item.id)!;
+    const parent = item.parentId ? byId.get(item.parentId) : undefined;
+    // An orphan becoming a root is a decision — make it deliberately.
+    (parent ? parent.children : roots).push(node);
+  }
+  return roots;
+};
+```
+
+Then render the tree, and say what its pane shows — **the pane's tabs are children, and passing
+none means there is no pane at all**:
+
+```tsx
+<DataViews.Tree nodes={nodes} labelPath="name">
+  <DataViews.Tree.Table selectable />
+  <DataViews.Tree.Cards />
+</DataViews.Tree>
+```
+
+When the tree holds one kind of thing and the pane must list another — categories in the rail,
+items in the pane — that is `paneRows`:
+
+```tsx
+<DataViews.Tree nodes={categories} paneRows={(node) => itemsInCategory(node.id)}>
+  <DataViews.Tree.Table />
+</DataViews.Tree>
+```
+
+## Recipe 5 — A message shape → the inbox
+
+```json
+[{ "id": 1, "subject": "Delivery delayed", "from": "ops@acme.com", "createdAt": "2025-09-10" }]
+```
+
+```tsx
+<DataViews.Inbox titlePath="subject" datePath="createdAt">
+  <DataViews.Detail />
+</DataViews.Inbox>
+```
+
+`DataViews.Detail` renders every visible field of the open row. For anything richer, the pane is
+`children` and `useActiveRow()` resolves what is open.
+
+If the open message should be a **URL** — a back button, a shareable link — make the items links:
+
+```tsx
+<DataViews.Inbox titlePath="subject" datePath="createdAt"
+                 itemHref={(row, id) => `/inbox/${id}`} linkComponent={Link} />
+```
+
+## Recipe 6 — Server-driven filtering, sorting and paging
+
+Everything the user can ask for arrives as one object, because a query with a new filter and a
+stale page number is not a query anyone meant to ask.
+
+```tsx
+const [query, setQuery] = useState(emptyQuery());
+const { data, isPending } = useQuery({
+  queryKey: ["orders", query],
+  queryFn: () => fetch(`/api/orders?${queryToParams(query)}`).then((r) => r.json()),
+});
+
+<DataViews
+  rows={data?.rows ?? []}
+  total={data?.total ?? 0}
+  fields={FIELDS}
+  loading={isPending}
+  onQueryChange={setQuery}
+>
+```
+
+The route handler decodes with `parseQuery`, so the encoder and the decoder cannot drift:
+
+```ts
+// app/api/orders/route.ts
+import { parseQuery } from "@/components/DataViews";
+
+export async function GET(request: Request) {
+  const { search, filters, sort, page, pageSize } = parseQuery(new URL(request.url));
+  // your matcher, your ORM
+  return Response.json({ rows, total });
+}
+```
+
+`filters` is `Record<path, string[] | { kind: "number", min?, max? } | { kind: "date", from?, to? }>`.
+How the constraints combine — AND across fields, OR within one, fuzzy or exact — is your matcher's
+business. The component reports what was chosen and nothing more.
+
+**Paging is scrolling.** There is no pager: hand over `onLoadMore` and **append** each page.
+Whether there is more is derived from `rows.length < total`, so there is no flag to keep in sync.
+
+```tsx
+const { data, fetchNextPage, isPending, isFetchingNextPage } = useInfiniteQuery({
+  queryKey: ["orders", { ...query, page: undefined }],   // not `page` — pageParam drives that
+  initialPageParam: 1,
+  queryFn: ({ pageParam }) =>
+    fetch(`/api/orders?${queryToParams({ ...query, page: pageParam })}`).then((r) => r.json()),
+  getNextPageParam: (last, pages) => {
+    const loaded = pages.reduce((n, p) => n + p.rows.length, 0);
+    return loaded < last.total ? pages.length + 1 : undefined;
+  },
+});
+
+<DataViews
+  rows={data?.pages.flatMap((p) => p.rows) ?? []}
+  total={data?.pages[0]?.total ?? 0}
+  loading={isPending}
+  onLoadMore={fetchNextPage}
+  loadingMore={isFetchingNextPage}
+  fields={FIELDS}
+  onQueryChange={setQuery}
+/>
+```
+
+## Recipe 7 — A response nothing built-in fits
+
+Two seams, in increasing order of commitment.
+
+**Repaint a field** — the narrowest, and it applies in every view at once:
+
+```ts
+{ path: "health", label: "Health", render: (value, row) => <HealthPill value={Number(value)} row={row} /> }
+```
+
+**Add a view of your own.** `markView` registers it in the switcher beside the built-in four; it
+reads the same context, loading state included:
+
+```tsx
+const GalleryView = markView(function GalleryView() {
+  const { rows, visibleFields, loading, getRowId } = useDataViewsData();
+  if (loading) return <SkeletonBar className="h-40" />;
+  return <div className="grid grid-cols-3 gap-3">{rows.map((row, i) => <Tile key={getRowId(row, i)} row={row} />)}</div>;
+}, { defaultId: "gallery", defaultLabel: "Gallery" });
+
+<DataViews …>
+  <DataViews.Table />
+  <GalleryView icon={<i className="ri-layout-grid-line" />} />
+</DataViews>
+```
+
+## Gotchas
+
+- **Nothing filters itself.** If the rows do not change, nothing on screen changes. That is the
+  contract, not a bug.
+- **`total` is the server's count**, not `rows.length`. Scroll loading stops when
+  `rows.length >= total`, so a wrong `total` either stops early or loops.
+- **Append, never replace**, when paging — replacing resets the list and the sentinel fires again.
+- **Memoize `groups` and `nodes`.** They are rebuilt on every render otherwise, and both are
+  diffed.
+- **A part exists because you rendered it.** There is no `views={{ … }}` map; wrap a view in a
+  condition to hide it, and the component switches away if it was open.
+- **Booleans have no filter section.** Use a Yes/No `RadioList`, or `Filters.Custom`.
+
+## Related
+
+- [`DataViews` component reference](./index.md) — every part, prop and type
+- [Build a DataViews screen](./guide.md) — the same ground as scenarios, start to finish
+- [Migrating to the DataViews component](./migration.md) — if you are coming from
+  `DataViewsLayout`