Data Table

1'use client';
2 
3import * as React from 'react';
4 
5// @interlace/data-table v1.0.0 — Interlace design system.
6// Docs, props and live preview: https://ds.interlace.tools/c/data-table
7// What changed since: https://ds.interlace.tools/c/data-table#history
8// Generated banner — keep it, the upgrade diff reads this version.
9 
10/**
11 * @interlace/ui — DataTable
12 *
13 * Columns, sorting, row selection, pagination, and the three states a table
14 * spends most of its life in (loading / empty / error). It composes
15 * primitives — Checkbox, Pagination, Skeleton, Button — so it is a pattern,
16 * not a primitive.
17 *
18 * ## It is a real `<table>`
19 *
20 * Not a grid of divs. `<caption>` names it, `<th scope="col">` names each
21 * column, and one column per row is a `<th scope="row">` that names the row
22 * (`rowHeader` on the column, defaulting to the first). That triple is what
23 * makes a screen reader announce "Revenue, March, 41,200" instead of
24 * "41,200" — a bare number in a bare cell is unreadable by anyone not
25 * looking at the screen, and no amount of `aria-label` on the wrapper fixes
26 * it. It is the same contract `charts/series-table.tsx` exists to honour for
27 * the chart layer.
28 *
29 * ## State is the caller's
30 *
31 * `sort` / `onSortChange` and `selected` / `onSelectionChange` are props, not
32 * `useState`. The table renders `rows` in the order it received them and
33 * highlights the keys it was handed.
34 *
35 * That is not purity for its own sake — it is the only shape that satisfies
36 * URL_PHILOSOPHY / DEEP_LINKING_PHILOSOPHY. Table state belongs in the query
37 * string (`?sort=createdAt&dir=desc&page=3`) so a filtered, sorted, paged
38 * view survives a refresh and can be pasted to a colleague. A table holding
39 * its own sort state cannot put it there, and the "controlled OR uncontrolled"
40 * compromise is worse: it makes the URL an optional feature, which means it
41 * is the feature nobody wires up. It also means the SORT ITSELF is the
42 * caller's — server-side for anything real; `sortRows` from
43 * `./data-table-model.js` for the small in-memory case.
44 *
45 * Selection is keyed by row ID (`rowKey`), never by index, so it survives
46 * both sorting and pagination.
47 *
48 * ## MIN_VIEWPORT — 320
49 *
50 * The table scrolls horizontally inside its own container; the page never
51 * does. The pager and the selection bar sit OUTSIDE that container, so they
52 * stay put while the columns scroll under them.
53 *
54// … truncated