makersclaw 0.1.0 → 0.3.0

package/registry/blocks/data-table/data-table.jsx

@@ -0,0 +1,1164 @@
+"use client";
+
+import { isValidElement, useEffect, useId, useMemo, useState } from "react";
+import { isSample } from "../../parts";
+import {
+  Button,
+  Checkbox,
+  Combobox,
+  Empty,
+  Icon,
+  IconButton,
+  InputGroup,
+  Menu,
+  Notice,
+  Pagination,
+  Skeleton,
+  Table,
+  TableBody,
+  TableCell,
+  TableFooter,
+  TableHead,
+  TableHeader,
+  TableRow,
+  Tooltip,
+  cx,
+} from "../../ui";
+import { facetOptions, groupKeyOf, groupRows, groupValueOf, nextSort, processRows, useControllable } from "./model";
+
+// DataTable — records as a table the founder can work: sort by a column
+// (shift for more than one), search every column, narrow by facets with
+// counts, pick which columns show, select rows and act on them together,
+// act on one from its menu, open one with a click, move a page at a
+// time. Client-side over `rows` by default; with `manual` the rows are
+// already the page a server chose, and the table only reports what the
+// founder asked for. Every piece of state (search, filters, sort,
+// selection, page, page size, hidden columns) is controlled when its
+// value prop is given and the table's own otherwise.
+//
+// The block owns the behaviour a hand-drawn table gets wrong: a sort that
+// keeps blanks last, a select-all that means this page, a page that goes
+// back to 1 when the filter changes, "no matches" told apart from "no
+// rows", a bulk action that can fail and says so, examples that are
+// never acted on, and a 390px window where the table scrolls inside
+// itself (or turns into cards). The surface owns what a cell says
+// (`cell`), what a row can do (`rowActions`, `bulkActions`) and how a row
+// is painted (`rowTone`, `rowClassName`).
+//
+//   <DataTable rows={invoices} columns={COLUMNS}
+//              facets={[{ key: "status", label: "Status" }]}
+//              bulkActions={[{ label: "Mark paid", onSelect: markPaid }]}
+//              rowActions={(r) => [{ label: "Open", onSelect: () => open(r) }]}
+//              onRowClick={open} />
+//
+// Opt-in on top: a row's first actions as buttons in the row
+// (`inlineActions`), rows that open under themselves (`renderExpanded`), rows
+// filed under group headings with a subtotal each (`groupBy`,
+// `groupSummary`, `groupFooter`), an aligned totals row (`totals`), arrow
+// keys over the rows (`keyboard`) and a first column that stays put while
+// a wide table scrolls sideways (`stickyFirstColumn`).
+//
+// README.md beside this file lists every prop.
+
+const TONES = {
+  success: "bg-success/10 [tr:hover>&]:bg-success/15",
+  info: "bg-info/10 [tr:hover>&]:bg-info/15",
+  warning: "bg-warning/10 [tr:hover>&]:bg-warning/15",
+  danger: "bg-destructive/10 [tr:hover>&]:bg-destructive/15",
+  highlighted: "bg-primary/5 [tr:hover>&]:bg-primary/10",
+};
+const CARD_TONES = {
+  success: "border-success/40 bg-success/10",
+  info: "border-info/40 bg-info/10",
+  warning: "border-warning/50 bg-warning/10",
+  danger: "border-destructive/50 bg-destructive/10",
+  highlighted: "border-primary/40 bg-primary/5",
+};
+// A highlighted row (a pinned or best row, not a status) carries a bar
+// at its leading edge as well as the tint.
+const BAR = "shadow-[inset_3px_0_0_var(--color-primary)]";
+// A sticky cell is opaque (the columns scroll under it), so a tone is a
+// flat gradient layered over the card instead of a see-through fill.
+const STICKY_TONES = {
+  success: "bg-linear-to-r from-success/10 to-success/10 [tr:hover>&]:from-success/15 [tr:hover>&]:to-success/15",
+  info: "bg-linear-to-r from-info/10 to-info/10 [tr:hover>&]:from-info/15 [tr:hover>&]:to-info/15",
+  warning: "bg-linear-to-r from-warning/10 to-warning/10 [tr:hover>&]:from-warning/15 [tr:hover>&]:to-warning/15",
+  danger: "bg-linear-to-r from-destructive/10 to-destructive/10 [tr:hover>&]:from-destructive/15 [tr:hover>&]:to-destructive/15",
+  highlighted: "bg-linear-to-r from-primary/5 to-primary/5 [tr:hover>&]:from-primary/10 [tr:hover>&]:to-primary/10",
+};
+const STICKY_HOVER = "[tr:hover>&]:bg-linear-to-r [tr:hover>&]:from-muted/50 [tr:hover>&]:to-muted/50";
+const STICKY_EDGE = "shadow-[inset_-1px_0_0_var(--color-border)]";
+const BAR_EDGE = "shadow-[inset_3px_0_0_var(--color-primary),inset_-1px_0_0_var(--color-border)]";
+// The leading columns' widths, so a sticky first column knows its offset.
+const EXPANDER_W = 2.5; // rem — w-10
+const SELECT_W = 3; // rem — w-12
+const INTERACTIVE = "button, a, input, select, textarea, label, [role=menuitem], [role=menu], [popover]";
+const NO_FILTERS = {};
+const NONE = [];
+
+function humanize(key) {
+  const text = String(key ?? "").replace(/[_-]+/g, " ").trim();
+  return text ? text.charAt(0).toUpperCase() + text.slice(1) : "";
+}
+
+function plural(n, one, many = `${one}s`) {
+  return `${n.toLocaleString()} ${n === 1 ? one : many}`;
+}
+
+// A per-column map ({ amount: "$4,200" }) rather than one node.
+const isColumnMap = (v) => Boolean(v) && typeof v === "object" && !Array.isArray(v) && !isValidElement(v);
+const domId = (s) => String(s).replace(/[^\w-]/g, "_");
+
+export function DataTable({
+  rows,
+  columns,
+  idColumn = "id",
+  label = "Table",
+  // search
+  searchable = true,
+  searchPlaceholder = "Search…",
+  search,
+  defaultSearch = "",
+  onSearchChange,
+  // facets
+  facets,
+  filters,
+  defaultFilters = NO_FILTERS,
+  onFiltersChange,
+  // sort
+  sort,
+  defaultSort = NONE,
+  onSortChange,
+  multiSort = true,
+  // selection
+  selectable,
+  selection,
+  defaultSelection = NONE,
+  onSelectionChange,
+  bulkActions,
+  // columns
+  hiddenColumns,
+  defaultHiddenColumns,
+  onHiddenColumnsChange,
+  // pagination
+  page,
+  defaultPage = 1,
+  onPageChange,
+  pageSize,
+  defaultPageSize = 10,
+  onPageSizeChange,
+  pageSizes = [10, 25, 50, 100],
+  paginate = true,
+  // server mode
+  manual = false,
+  rowCount,
+  // rows
+  rowActions,
+  inlineActions,
+  onRowClick,
+  rowTone,
+  rowClassName,
+  // expandable rows
+  renderExpanded,
+  canExpand,
+  expanded,
+  defaultExpanded = NONE,
+  onExpandedChange,
+  // groups
+  groupBy,
+  groupOrder,
+  groupLabel,
+  groupSummary,
+  groupFooter,
+  // totals
+  totals,
+  totalsLabel = "Total",
+  // keyboard and layout
+  keyboard = false,
+  stickyFirstColumn = false,
+  // slots and states
+  toolbar,
+  footer,
+  loading = false,
+  error,
+  emptyTitle = "Nothing here yet",
+  emptyBody,
+  emptyAction,
+  emptyIcon = "inbox",
+  noun = "row",
+  mobile = "scroll",
+  cardTitle,
+  variant = "outline",
+  className,
+}) {
+  const uid = useId().replace(/[^\w-]/g, "");
+  const all = rows ?? NONE;
+  const cols = useMemo(() => (columns ?? []).map((c) => ({ ...c, key: String(c.key), header: c.header ?? humanize(c.key) })), [columns]);
+  const facetList = useMemo(
+    () =>
+      (facets ?? []).map((f) => {
+        const col = cols.find((c) => c.key === String(f.key));
+        return { ...f, key: String(f.key), label: f.label ?? (typeof col?.header === "string" ? col.header : humanize(f.key)) };
+      }),
+    [facets, cols],
+  );
+  const keyOf = (row) => String(row?.[idColumn]);
+
+  const [query, setQuery] = useControllable(search, defaultSearch, onSearchChange);
+  const [chosen, setChosen] = useControllable(filters, defaultFilters, onFiltersChange);
+  const [order, setOrder] = useControllable(sort, defaultSort, onSortChange);
+  const [picked, setPicked] = useControllable(selection, defaultSelection, onSelectionChange);
+  const [hidden, setHidden] = useControllable(
+    hiddenColumns,
+    defaultHiddenColumns ?? cols.filter((c) => c.hidden).map((c) => c.key),
+    onHiddenColumnsChange,
+  );
+  const [current, setPage] = useControllable(page, defaultPage, onPageChange);
+  const [size, setSize] = useControllable(pageSize, defaultPageSize, onPageSizeChange);
+  const [bulkError, setBulkError] = useState(null);
+  const [bulkNote, setBulkNote] = useState(null);
+  const [running, setRunning] = useState(null);
+  const [announce, setAnnounce] = useState("");
+  const [openIds, setOpenIds] = useControllable(expanded, defaultExpanded, onExpandedChange);
+  const [activeId, setActiveId] = useState(null);
+  const [rowBusy, setRowBusy] = useState(null);
+  const [rowError, setRowError] = useState(null);
+
+  const canSelect = selectable ?? Boolean(bulkActions || onSelectionChange || selection);
+  const hiddenSet = useMemo(() => new Set((hidden ?? NONE).map(String)), [hidden]);
+  const shown = cols.filter((c) => !hiddenSet.has(c.key));
+  const pickedSet = useMemo(() => new Set((picked ?? NONE).map(String)), [picked]);
+  const filterState = chosen ?? NO_FILTERS;
+  const activeFilters = facetList.filter((f) => (filterState[f.key] ?? []).length > 0).length;
+  const narrowed = Boolean(String(query ?? "").trim()) || activeFilters > 0;
+
+  // Client mode: search, facets, sort, then a page. Manual: the rows are
+  // the page already, and `rowCount` is how many the server has.
+  const matched = useMemo(
+    () => (manual ? all : processRows(all, { query, filters: filterState, facets: facetList, sort: order, columns: cols })),
+    [manual, all, query, filterState, facetList, order, cols],
+  );
+  const total = manual ? rowCount ?? all.length : matched.length;
+  const per = paginate ? Math.max(1, Number(size) || 10) : Math.max(1, total);
+  const pageCount = Math.max(1, Math.ceil(total / per));
+  const pageNow = Math.min(Math.max(1, Number(current) || 1), pageCount);
+  // Groups: sort first, then file each row under its group, so a sort
+  // orders rows within their groups. Groups keep their place (`groupOrder`,
+  // else the order they first appear in `rows`) whatever the sort.
+  const grouped = groupBy !== undefined && groupBy !== null && groupBy !== false;
+  const groups = useMemo(() => {
+    if (!grouped) return null;
+    const seen = all.map((r) => groupKeyOf(groupValueOf(groupBy, r)));
+    const order = typeof groupOrder === "function" ? groupOrder : [...(Array.isArray(groupOrder) ? groupOrder : NONE), ...seen];
+    return groupRows(matched, groupBy, order);
+  }, [grouped, groupBy, groupOrder, matched, all]);
+  const arranged = useMemo(() => (groups ? groups.flatMap((g) => g.rows) : matched), [groups, matched]);
+  const visible = manual || !paginate ? arranged : arranged.slice((pageNow - 1) * per, pageNow * per);
+
+  // A page past the end (the filter narrowed the rows) goes back to the last.
+  useEffect(() => {
+    if (!loading && Number(current) > pageCount) setPage(pageCount);
+  }, [current, pageCount, loading]); // eslint-disable-line react-hooks/exhaustive-deps
+
+  useEffect(() => {
+    if (!loading && narrowed) setAnnounce(total === 0 ? "No matches" : `${plural(total, noun)} match`);
+  }, [total, narrowed, loading, noun]);
+
+  // ---- changes that move back to page 1 ---------------------------------
+
+  function changeQuery(v) {
+    setQuery(v);
+    if (pageNow !== 1) setPage(1);
+  }
+  function changeFacet(key, values) {
+    setChosen((f) => {
+      const next = { ...(f ?? {}) };
+      if (values.length) next[key] = values;
+      else delete next[key];
+      return next;
+    });
+    if (pageNow !== 1) setPage(1);
+  }
+  function clearFilters() {
+    setQuery("");
+    setChosen({});
+    if (pageNow !== 1) setPage(1);
+  }
+  function pressSort(e, key) {
+    setOrder((s) => nextSort(s, key, multiSort && e?.shiftKey));
+    if (pageNow !== 1) setPage(1);
+  }
+
+  // ---- selection ---------------------------------------------------------
+
+  const pageIds = visible.map(keyOf);
+  const pagePicked = pageIds.filter((id) => pickedSet.has(id)).length;
+  const allOnPage = pageIds.length > 0 && pagePicked === pageIds.length;
+  const someOnPage = pagePicked > 0 && !allOnPage;
+
+  function toggleRow(row) {
+    const id = keyOf(row);
+    setPicked((p) => {
+      const list = (p ?? []).map(String);
+      return list.includes(id) ? list.filter((x) => x !== id) : [...list, id];
+    });
+  }
+  function togglePage() {
+    setPicked((p) => {
+      const list = (p ?? []).map(String);
+      if (allOnPage) return list.filter((id) => !pageIds.includes(id));
+      return [...list, ...pageIds.filter((id) => !list.includes(id))];
+    });
+  }
+  function selectAllMatches() {
+    setPicked((p) => [...new Set([...(p ?? []).map(String), ...matched.map(keyOf)])]);
+  }
+  function clearSelection() {
+    setPicked([]);
+    setBulkNote(null);
+  }
+
+  // ---- expandable rows ---------------------------------------------------
+
+  const expanding = typeof renderExpanded === "function";
+  const openSet = useMemo(() => new Set((openIds ?? NONE).map(String)), [openIds]);
+  const expandable = (row) => expanding && (canExpand ? Boolean(canExpand(row)) : true);
+  function toggleOpen(id, force) {
+    setOpenIds((o) => {
+      const list = (o ?? []).map(String);
+      const on = force ?? !list.includes(id);
+      if (on === list.includes(id)) return list;
+      return on ? [...list, id] : list.filter((x) => x !== id);
+    });
+  }
+
+  const selectedRows = useMemo(() => all.filter((r) => pickedSet.has(keyOf(r))), [all, pickedSet]); // eslint-disable-line react-hooks/exhaustive-deps
+  const count = manual ? pickedSet.size : selectedRows.length;
+  const bulkItems = (typeof bulkActions === "function" ? bulkActions(selectedRows) : bulkActions ?? NONE).filter(Boolean);
+
+  async function runBulk(action) {
+    // Examples are shown, never acted on: they are not rows.
+    const real = selectedRows.filter((r) => !isSample(r));
+    setBulkError(null);
+    setBulkNote(null);
+    if (real.length === 0 && selectedRows.length > 0) {
+      setBulkNote("These are examples. Nothing was changed.");
+      return;
+    }
+    setRunning(action.label);
+    let result;
+    try {
+      result = await action.onSelect?.(real, manual ? [...pickedSet] : real.map(keyOf));
+    } catch (e) {
+      result = { ok: false, error: e?.message ?? String(e) };
+    }
+    setRunning(null);
+    if (result && result.ok === false) {
+      setBulkError(`${action.label} failed: ${result.error ?? "nothing was changed"}`);
+      return;
+    }
+    if (action.keepSelection !== true) setPicked([]);
+    setAnnounce(`${action.label}: done for ${plural(real.length, noun)}`);
+  }
+
+  // ---- drawing -----------------------------------------------------------
+
+  const toneOf = (row) => (rowTone ? rowTone(row) : null);
+  const hasActions = typeof rowActions === "function";
+  // Inline buttons widen the actions column past the menu's w-12.
+  const inlining = hasActions && Boolean(inlineActions);
+  // A click opens the row (`onRowClick`); with no onRowClick, a row that
+  // expands opens its details instead.
+  const activate = typeof onRowClick === "function" ? onRowClick : expanding ? (row) => expandable(row) && toggleOpen(keyOf(row)) : null;
+  const clickable = Boolean(activate);
+  const lead = (expanding ? 1 : 0) + (canSelect ? 1 : 0);
+  const width = lead + shown.length + (hasActions ? 1 : 0);
+  const titleOf = (row) => {
+    if (cardTitle) return cardTitle(row);
+    const first = shown[0];
+    return first ? (first.cell ? first.cell(row) : row?.[first.key]) : keyOf(row);
+  };
+  const nameOf = (row) => {
+    const first = shown[0];
+    const v = first ? row?.[first.key] : null;
+    return typeof v === "string" || typeof v === "number" ? String(v) : keyOf(row);
+  };
+
+  function onRowActivate(e, row) {
+    if (!clickable) return;
+    if (e.target.closest?.(INTERACTIVE)) return;
+    if (e.type === "keydown") {
+      if (e.key !== "Enter" && e.key !== " ") return;
+      if (e.target !== e.currentTarget) return;
+      // With the keyboard grid, Space selects (the grid's handler does it).
+      if (e.key === " " && keyboard && canSelect) return;
+      e.preventDefault();
+    }
+    activate(row);
+  }
+
+  // ---- keyboard grid -------------------------------------------------------
+  // One row is in the tab order at a time (roving tabindex): the last one
+  // focused, else the first. Arrows, Home and End move it; Space selects;
+  // Enter opens (as a click does); → and ← open and close a row's details;
+  // Esc clears the selection.
+
+  const byId = new Map(visible.map((r) => [keyOf(r), r]));
+  const tabStop = keyboard ? (activeId !== null && byId.has(activeId) ? activeId : visible.length ? keyOf(visible[0]) : null) : null;
+
+  function onGridKey(e) {
+    if (!keyboard) return;
+    if (e.target.closest?.("[role=menu], [popover], input:not([type=checkbox]), textarea, select")) return;
+    if (e.key === "Escape") {
+      if (canSelect && count > 0) {
+        e.preventDefault();
+        clearSelection();
+        setAnnounce("Selection cleared");
+      }
+      return;
+    }
+    const el = e.target.closest?.("[data-row]");
+    if (!el || el !== e.target) return;
+    const list = [...e.currentTarget.querySelectorAll("[data-row]")];
+    const at = list.indexOf(el);
+    const row = byId.get(el.dataset.row);
+    let to = null;
+    if (e.key === "ArrowDown") to = at + 1;
+    else if (e.key === "ArrowUp") to = at - 1;
+    else if (e.key === "Home") to = 0;
+    else if (e.key === "End") to = list.length - 1;
+    else if (e.key === " " && canSelect && row) {
+      e.preventDefault();
+      const on = !pickedSet.has(el.dataset.row);
+      toggleRow(row);
+      setAnnounce(`${nameOf(row)} ${on ? "selected" : "deselected"}`);
+      return;
+    } else if ((e.key === "ArrowRight" || e.key === "ArrowLeft") && row && expandable(row)) {
+      e.preventDefault();
+      toggleOpen(el.dataset.row, e.key === "ArrowRight");
+      return;
+    }
+    if (to === null) return;
+    e.preventDefault();
+    const next = list[Math.max(0, Math.min(list.length - 1, to))];
+    if (next) {
+      next.focus();
+      setActiveId(next.dataset.row);
+    }
+  }
+
+  // What a row (or card) needs to be clicked, focused and moved through.
+  function rowProps(row, id) {
+    return {
+      tabIndex: keyboard ? (id === tabStop ? 0 : -1) : clickable ? 0 : undefined,
+      onClick: clickable ? (e) => onRowActivate(e, row) : undefined,
+      onKeyDown: clickable ? (e) => onRowActivate(e, row) : undefined,
+      onFocus: keyboard ? (e) => e.target === e.currentTarget && setActiveId(id) : undefined,
+    };
+  }
+  // The ring is a layer over the whole row, above sticky cells (an outline
+  // on the row would be painted under them).
+  const focusRing =
+    "relative outline-hidden focus-visible:after:pointer-events-none focus-visible:after:absolute focus-visible:after:inset-0 focus-visible:after:z-[3] focus-visible:after:ring-2 focus-visible:after:ring-inset focus-visible:after:ring-ring";
+
+  // ---- sticky first column -------------------------------------------------
+
+  const stickyBg = variant === "plain" ? "bg-background" : "bg-card";
+  const offsets = { expander: 0, select: expanding ? EXPANDER_W : 0, first: (expanding ? EXPANDER_W : 0) + (canSelect ? SELECT_W : 0) };
+  // Classes and style for a cell in a leading slot ("expander" | "select" |
+  // "first"). `layer` is what the cell paints: "head", "foot", "body".
+  function stick(slot, layer, { tone, selected, bar } = {}) {
+    if (!stickyFirstColumn) return { className: undefined, style: undefined };
+    const edge = slot === "first";
+    const paint =
+      layer === "head"
+        ? stickyBg
+        : layer === "foot"
+          ? cx(stickyBg, "bg-linear-to-r from-muted/50 to-muted/50")
+          : layer === "sub"
+            ? "bg-muted"
+            : cx(selected ? "bg-muted" : stickyBg, tone && STICKY_TONES[tone] ? STICKY_TONES[tone] : !selected && STICKY_HOVER);
+    return {
+      className: cx("sticky", layer === "head" ? "z-[2]" : "z-[1]", paint, edge && (bar ? BAR_EDGE : STICKY_EDGE)),
+      style: { left: `${offsets[slot]}rem` },
+    };
+  }
+
+  function checkbox(row) {
+    return (
+      <Checkbox
+        checked={pickedSet.has(keyOf(row))}
+        onChange={() => toggleRow(row)}
+        aria-label={`Select ${nameOf(row)}`}
+        className="px-1"
+      />
+    );
+  }
+
+  // A row's actions, split: the ones drawn as buttons in the row
+  // (`inlineActions` of them from the front, or any with `inline: true`)
+  // and the rest, which stay in the "…" menu. Separators and labels stay
+  // in the menu, tidied so none leads, trails or doubles.
+  function splitActions(row) {
+    const items = (hasActions ? rowActions(row) ?? NONE : NONE).filter(Boolean);
+    let left = inlineActions === true ? Infinity : Math.max(0, Number(inlineActions) || 0);
+    const inline = [];
+    const menu = [];
+    for (const a of items) {
+      const plain = a.type === undefined || a.type === "item";
+      const pick = plain && a.inline !== false && (a.inline === true || left > 0);
+      if (pick) {
+        inline.push(a);
+        if (a.inline !== true) left--;
+      } else menu.push(a);
+    }
+    const tidy = menu.filter((a, i, all) => {
+      if (a.type !== "separator") return true;
+      const prev = all.slice(0, i).filter((x) => x.type !== "separator").length;
+      const next = all[i + 1];
+      return prev > 0 && next && next.type !== "separator";
+    });
+    return { inline, menu: inline.length ? tidy : items };
+  }
+
+  // An inline action may be async: its button spins, the row's other
+  // buttons wait, and { ok: false, error } (or a throw) is said above the
+  // table. The menu's items keep their own behaviour.
+  async function runRowAction(row, action) {
+    const id = keyOf(row);
+    setRowError(null);
+    setRowBusy({ id, label: action.label });
+    let result;
+    try {
+      result = await action.onSelect?.(row);
+    } catch (e) {
+      result = { ok: false, error: e?.message ?? String(e) };
+    }
+    setRowBusy(null);
+    if (result && result.ok === false) {
+      setRowError(`${action.label} failed for ${nameOf(row)}: ${result.error ?? "nothing was changed"}`);
+      return;
+    }
+    setAnnounce(`${action.label}: done for ${nameOf(row)}`);
+  }
+
+  function inlineButton(row, a, card) {
+    const id = keyOf(row);
+    const busy = rowBusy?.id === id;
+    const props = {
+      variant: a.tone === "danger" ? "danger" : "secondary",
+      loading: busy && rowBusy.label === a.label,
+      disabled: (busy && rowBusy.label !== a.label) || a.disabled,
+      onClick: () => runRowAction(row, a),
+    };
+    // On a card there is room for the words; in a row, the glyph and a tip.
+    if (card || !a.icon) {
+      return (
+        <Button key={a.label} {...props} size="md" icon={a.icon}>
+          {a.label}
+        </Button>
+      );
+    }
+    return (
+      <Tooltip key={a.label} label={a.label}>
+        <IconButton {...props} icon={a.icon} label={`${a.label}: ${nameOf(row)}`} size="md" />
+      </Tooltip>
+    );
+  }
+
+  function rowMenu(row, split = splitActions(row)) {
+    return <Menu items={split.menu} label={`Actions for ${nameOf(row)}`} size="md" />;
+  }
+
+  function actionsCell(row) {
+    const split = splitActions(row);
+    if (!split.inline.length) return rowMenu(row, split);
+    return (
+      <div className="flex items-center justify-end gap-1.5">
+        {split.inline.map((a) => inlineButton(row, a, false))}
+        {rowMenu(row, split)}
+      </div>
+    );
+  }
+
+  const empty = !loading && (manual ? total === 0 && !narrowed : all.length === 0) ? (
+    <Empty icon={emptyIcon} title={emptyTitle} body={emptyBody} action={emptyAction} />
+  ) : null;
+  const noMatches = !loading && !empty && visible.length === 0 ? (
+    <Empty
+      icon="search"
+      title="No matches"
+      body={narrowed ? "Nothing matches the search and filters." : `No ${noun}s on this page.`}
+      action={
+        narrowed ? (
+          <Button size="sm" icon="x" onClick={clearFilters}>
+            Clear filters
+          </Button>
+        ) : null
+      }
+    />
+  ) : null;
+
+  const skeletonRows = Array.from({ length: Math.min(per, 8) }, (_, i) => i);
+
+  // The rows on this page, in runs of one group each (one run, no heading,
+  // when the table is not grouped). A group's summary and subtotal are
+  // over all of its rows, not only this page's; its subtotal shows on the
+  // page where the group ends.
+  const groupByKey = useMemo(() => new Map((groups ?? NONE).map((g) => [g.key, g])), [groups]);
+  const runs = [];
+  for (const row of visible) {
+    const k = grouped ? groupKeyOf(groupValueOf(groupBy, row)) : null;
+    let run = runs[runs.length - 1];
+    if (!run || run.key !== k) runs.push((run = { key: k, group: groupByKey.get(k), rows: [] }));
+    run.rows.push(row);
+  }
+  const labelOf = (g) => (groupLabel ? groupLabel(g.value, g.rows) : g.key === "" ? "None" : g.key);
+  const totalsMap = typeof totals === "function" ? totals(manual ? all : matched) : totals;
+  const showTotals = isColumnMap(totalsMap) && !loading && visible.length > 0;
+
+  // One aligned row of per-column values (a subtotal, the totals): blank
+  // under the leading and trailing controls, the label in the first
+  // column when the map has nothing for it.
+  function alignedCells(map, labelText, layer) {
+    return (
+      <>
+        {expanding ? <TableCell className={cx("w-10 px-1", stick("expander", layer).className)} style={stick("expander", layer).style} /> : null}
+        {canSelect ? <TableCell className={cx("w-12", stick("select", layer).className)} style={stick("select", layer).style} /> : null}
+        {shown.map((c, j) => {
+          const s = j === 0 ? stick("first", layer) : {};
+          const has = Object.prototype.hasOwnProperty.call(map, c.key);
+          return (
+            <TableCell key={c.key} numeric={c.align === "end" || c.numeric} className={cx(s.className, c.className)} style={s.style}>
+              {has ? map[c.key] : j === 0 ? labelText : null}
+            </TableCell>
+          );
+        })}
+        {hasActions ? <TableCell className="w-12" /> : null}
+      </>
+    );
+  }
+
+  function dataRow(row) {
+    const id = keyOf(row);
+    const tone = toneOf(row);
+    const tint = tone ? TONES[tone] : null;
+    const selected = pickedSet.has(id);
+    const canOpen = expandable(row);
+    const open = canOpen && openSet.has(id);
+    const xid = `${uid}-x-${domId(id)}`;
+    const sx = stick("expander", "body", { tone, selected });
+    const ss = stick("select", "body", { tone, selected });
+    const sf = stick("first", "body", { tone, selected, bar: tone === "highlighted" && lead === 0 });
+    const barFirst = tone === "highlighted" && lead === 0;
+    const out = [
+      <TableRow
+        key={id}
+        data-row={id}
+        data-tone={tone && tone !== "default" ? tone : undefined}
+        data-open={open ? "" : undefined}
+        selected={selected}
+        {...rowProps(row, id)}
+        className={cx(
+          clickable && "cursor-pointer",
+          (clickable || keyboard) && cx(focusRing, "focus-visible:bg-muted"),
+          open && "border-b-0",
+          rowClassName?.(row),
+        )}
+      >
+        {expanding ? (
+          <TableCell className={cx("w-10 px-1 py-0", stickyFirstColumn ? sx.className : tint, tone === "highlighted" && BAR)} style={sx.style}>
+            {canOpen ? (
+              // raw: a bare icon toggle whose glyph turns; no kit Button draws a rotating icon.
+              <button
+                type="button"
+                aria-expanded={open}
+                aria-controls={open ? xid : undefined}
+                aria-label={`Details for ${nameOf(row)}`}
+                onClick={() => toggleOpen(id)}
+                className="inline-flex size-8 items-center justify-center rounded-md text-muted-foreground outline-none hover:bg-accent hover:text-foreground focus-visible:ring-2 focus-visible:ring-ring"
+              >
+                <Icon name="chevron-right" className={cx("transition-transform duration-150", open && "rotate-90")} />
+              </button>
+            ) : null}
+          </TableCell>
+        ) : null}
+        {canSelect ? (
+          <TableCell className={cx("w-12 py-0", stickyFirstColumn ? ss.className : tint, tone === "highlighted" && !expanding && BAR)} style={ss.style}>
+            {checkbox(row)}
+          </TableCell>
+        ) : null}
+        {shown.map((c, j) => {
+          const s = j === 0 ? sf : {};
+          return (
+            <TableCell
+              key={c.key}
+              numeric={c.align === "end" || c.numeric}
+              className={cx(j === 0 && stickyFirstColumn ? s.className : tint, barFirst && j === 0 && !stickyFirstColumn && BAR, c.className)}
+              style={s.style}
+            >
+              {c.cell ? c.cell(row) : row?.[c.key] ?? ""}
+            </TableCell>
+          );
+        })}
+        {hasActions ? <TableCell className={cx(inlining ? "whitespace-nowrap py-1.5" : "w-12 py-0", "text-right", tint)}>{actionsCell(row)}</TableCell> : null}
+      </TableRow>,
+    ];
+    if (open) {
+      out.push(
+        <TableRow key={`${id}-x`} className="hover:bg-transparent">
+          {/* raw: a bare cell — TableCell's padding would widen the table past the box. */}
+          <td id={xid} colSpan={width} className="bg-muted/30 p-0 align-top">
+            <div className={cx("sticky left-0 w-[100cqw] px-4 py-3", expanding && "sm:pl-12")}>{renderExpanded(row)}</div>
+          </td>
+        </TableRow>,
+      );
+    }
+    return out;
+  }
+
+  function groupHead(run, i) {
+    const g = run.group ?? { key: run.key, value: run.key, rows: run.rows };
+    const summary = groupSummary ? groupSummary(g.rows) : null;
+    return (
+      <TableRow key={`${run.key}-h`} data-group={run.key} className={cx("bg-muted/40 hover:bg-muted/40", i > 0 && "border-t")}>
+        <th scope="rowgroup" colSpan={width} className="h-10 px-3 text-left align-middle text-sm font-normal">
+          <div className="sticky left-3 flex w-[calc(100cqw-1.5rem)] items-center justify-between gap-3">
+            <span className="flex min-w-0 items-center gap-2">
+              <span className="font-semibold text-foreground">{labelOf(g)}</span>
+              <span data-nums className="text-xs text-muted-foreground">
+                {g.rows.length.toLocaleString()}
+              </span>
+            </span>
+            {summary !== null && summary !== undefined && summary !== false ? (
+              <span data-nums className="shrink-0 whitespace-nowrap text-muted-foreground">
+                {summary}
+              </span>
+            ) : null}
+          </div>
+        </th>
+      </TableRow>
+    );
+  }
+
+  function groupFoot(run) {
+    const g = run.group;
+    if (!groupFooter || !g || run.rows[run.rows.length - 1] !== g.rows[g.rows.length - 1]) return null;
+    const content = groupFooter(g.rows);
+    if (content === null || content === undefined || content === false) return null;
+    return (
+      <TableRow key={`${run.key}-f`} data-subtotal={run.key} className="bg-muted font-semibold hover:bg-muted">
+        {isColumnMap(content) ? (
+          alignedCells(content, "Subtotal", "sub")
+        ) : (
+          <TableCell colSpan={width} className="text-right">
+            {content}
+          </TableCell>
+        )}
+      </TableRow>
+    );
+  }
+
+  // The table's scroll box is a size container: a details row or a group
+  // heading spans the whole (maybe wider) table but is drawn at the width
+  // you can see (100cqw), pinned to its left edge.
+  const table = (
+    <div className="min-w-0 max-w-full" onKeyDown={keyboard ? onGridKey : undefined}>
+      <Table variant={variant} aria-label={label} aria-busy={loading || undefined} className="@container">
+        <TableHeader>
+          <TableRow>
+            {expanding ? (
+              <TableHead className={cx("w-10 px-1", stick("expander", "head").className)} style={stick("expander", "head").style}>
+                <span className="sr-only">Details</span>
+              </TableHead>
+            ) : null}
+            {canSelect ? (
+              <TableHead className={cx("w-12 py-0", stick("select", "head").className)} style={stick("select", "head").style}>
+                <Checkbox
+                  checked={allOnPage}
+                  ref={(el) => {
+                    if (el) el.indeterminate = someOnPage;
+                  }}
+                  disabled={loading || visible.length === 0}
+                  onChange={togglePage}
+                  aria-label={allOnPage ? "Deselect this page" : "Select this page"}
+                  className="px-1"
+                />
+              </TableHead>
+            ) : null}
+            {shown.map((c, j) => {
+              const at = (order ?? NONE).findIndex((s) => s.key === c.key);
+              const dir = at >= 0 ? order[at].dir : "none";
+              const s = j === 0 ? stick("first", "head") : {};
+              return (
+                <TableHead
+                  key={c.key}
+                  numeric={c.align === "end" || c.numeric}
+                  sort={c.sortable ? dir : undefined}
+                  onSort={c.sortable ? (e) => pressSort(e, c.key) : undefined}
+                  style={c.width || s.style ? { ...(c.width ? { width: c.width } : null), ...s.style } : undefined}
+                  sortIndex={c.sortable && at >= 0 && order.length > 1 ? at + 1 : undefined}
+                  className={cx(s.className, c.headerClassName)}
+                  title={c.sortable && multiSort ? "Shift-click to sort by more than one column" : undefined}
+                >
+                  {c.header}
+                </TableHead>
+              );
+            })}
+            {hasActions ? (
+              <TableHead className={inlining ? "text-right" : "w-12"}>
+                <span className="sr-only">Actions</span>
+              </TableHead>
+            ) : null}
+          </TableRow>
+        </TableHeader>
+        {loading ? (
+          <TableBody>
+            {skeletonRows.map((i) => (
+              <TableRow key={`s${i}`}>
+                {expanding ? <TableCell className="w-10 px-1" /> : null}
+                {canSelect ? (
+                  <TableCell className="py-0">
+                    <Skeleton shape="rect" className="ml-1 size-4 rounded-sm" />
+                  </TableCell>
+                ) : null}
+                {shown.map((c, j) => (
+                  <TableCell key={c.key} numeric={c.align === "end" || c.numeric}>
+                    <Skeleton className={cx("h-4", c.align === "end" || c.numeric ? "ml-auto w-16" : j === 0 ? "w-32" : "w-24")} />
+                  </TableCell>
+                ))}
+                {hasActions ? <TableCell /> : null}
+              </TableRow>
+            ))}
+          </TableBody>
+        ) : grouped ? (
+          // One <tbody> per group: its heading is a rowgroup header.
+          runs.map((run, i) => (
+            <TableBody key={run.key}>
+              {groupHead(run, i)}
+              {run.rows.flatMap(dataRow)}
+              {groupFoot(run)}
+            </TableBody>
+          ))
+        ) : (
+          <TableBody>{visible.flatMap(dataRow)}</TableBody>
+        )}
+        {showTotals ? (
+          <TableFooter>
+            <TableRow data-totals="" className="font-semibold hover:bg-transparent">
+              {alignedCells(totalsMap, totalsLabel, "foot")}
+            </TableRow>
+          </TableFooter>
+        ) : null}
+      </Table>
+    </div>
+  );
+
+  // Phone cards: the same rows, one card each, below 640px. Group headings
+  // and subtotals, a row's details and the totals come along.
+  function pairs(map) {
+    return shown
+      .filter((c) => Object.prototype.hasOwnProperty.call(map, c.key))
+      .map((c) => (
+        <div key={c.key} className="min-w-0">
+          <dt className="text-xs font-normal text-muted-foreground">{c.header}</dt>
+          <dd data-nums className="truncate">
+            {map[c.key]}
+          </dd>
+        </div>
+      ));
+  }
+
+  function card(row) {
+    const id = keyOf(row);
+    const tone = toneOf(row);
+    const rest = cardTitle ? shown : shown.slice(1);
+    const canOpen = expandable(row);
+    const open = canOpen && openSet.has(id);
+    const xid = `${uid}-cx-${domId(id)}`;
+    const split = hasActions ? splitActions(row) : { inline: NONE, menu: NONE };
+    return (
+      <li
+        key={id}
+        data-row={id}
+        data-tone={tone && tone !== "default" ? tone : undefined}
+        data-selected={pickedSet.has(id) ? "" : undefined}
+        {...rowProps(row, id)}
+        className={cx(
+          "rounded-lg border border-border bg-card p-3 text-sm text-card-foreground data-[selected]:ring-2 data-[selected]:ring-ring",
+          tone && CARD_TONES[tone],
+          clickable && "cursor-pointer",
+          (clickable || keyboard) && "outline-none focus-visible:ring-2 focus-visible:ring-ring",
+          rowClassName?.(row),
+        )}
+      >
+        <div className="flex items-start gap-1">
+          {canSelect ? <div className="-my-2 -ml-1 shrink-0">{checkbox(row)}</div> : null}
+          <div className="min-w-0 flex-1 font-medium">{titleOf(row)}</div>
+          {canOpen ? (
+            // raw: the same details toggle, on a card.
+            <button
+              type="button"
+              aria-expanded={open}
+              aria-controls={open ? xid : undefined}
+              aria-label={`Details for ${nameOf(row)}`}
+              onClick={() => toggleOpen(id)}
+              className="-my-1 inline-flex size-8 shrink-0 items-center justify-center rounded-md text-muted-foreground outline-none hover:bg-accent hover:text-foreground focus-visible:ring-2 focus-visible:ring-ring"
+            >
+              <Icon name="chevron-down" className={cx("transition-transform duration-150", open && "rotate-180")} />
+            </button>
+          ) : null}
+          {hasActions ? <div className="-my-1 -mr-1 shrink-0">{rowMenu(row, split)}</div> : null}
+        </div>
+        {rest.length ? (
+          <dl className="mt-2 grid grid-cols-2 gap-x-3 gap-y-2">
+            {rest.map((c) => (
+              <div key={c.key} className="min-w-0">
+                <dt className="text-xs text-muted-foreground">{c.header}</dt>
+                <dd className="truncate">{c.cell ? c.cell(row) : row?.[c.key] ?? ""}</dd>
+              </div>
+            ))}
+          </dl>
+        ) : null}
+        {split.inline.length ? <div className="mt-3 flex flex-wrap gap-2">{split.inline.map((a) => inlineButton(row, a, true))}</div> : null}
+        {open ? (
+          <div id={xid} className="mt-3 border-t border-border pt-3">
+            {renderExpanded(row)}
+          </div>
+        ) : null}
+      </li>
+    );
+  }
+
+  const cards = (
+    <ul className="grid gap-2" aria-label={label} aria-busy={loading || undefined} onKeyDown={keyboard ? onGridKey : undefined}>
+      {loading
+        ? skeletonRows.slice(0, 4).map((i) => (
+            <li key={`s${i}`} className="grid gap-2 rounded-lg border border-border bg-card p-3">
+              <Skeleton className="h-4 w-1/2" />
+              <Skeleton className="h-3 w-3/4" />
+              <Skeleton className="h-3 w-2/3" />
+            </li>
+          ))
+        : runs.flatMap((run) => {
+            if (!grouped) return run.rows.map(card);
+            const g = run.group ?? { key: run.key, value: run.key, rows: run.rows };
+            const summary = groupSummary ? groupSummary(g.rows) : null;
+            const ends = run.group && run.rows[run.rows.length - 1] === g.rows[g.rows.length - 1];
+            const foot = groupFooter && ends ? groupFooter(g.rows) : null;
+            return [
+              <li key={`${run.key}-h`} data-group={run.key} className="flex items-baseline justify-between gap-3 px-1 pt-2 text-sm">
+                <span className="flex min-w-0 items-baseline gap-2">
+                  <span className="truncate font-semibold">{labelOf(g)}</span>
+                  <span data-nums className="text-xs text-muted-foreground">
+                    {g.rows.length.toLocaleString()}
+                  </span>
+                </span>
+                {summary !== null && summary !== undefined && summary !== false ? (
+                  <span data-nums className="shrink-0 text-muted-foreground">
+                    {summary}
+                  </span>
+                ) : null}
+              </li>,
+              ...run.rows.map(card),
+              foot !== null && foot !== undefined && foot !== false ? (
+                <li key={`${run.key}-f`} data-subtotal={run.key} className="rounded-lg bg-muted px-3 py-2 text-sm font-semibold">
+                  {isColumnMap(foot) ? <dl className="grid grid-cols-2 gap-x-3 gap-y-1">{pairs(foot)}</dl> : foot}
+                </li>
+              ) : null,
+            ];
+          })}
+      {showTotals ? (
+        <li data-totals="" className="rounded-lg border border-border bg-muted/50 px-3 py-2 text-sm font-semibold">
+          {totalsLabel ? <p className="mb-1">{totalsLabel}</p> : null}
+          <dl className="grid grid-cols-2 gap-x-3 gap-y-1">{pairs(totalsMap)}</dl>
+        </li>
+      ) : null}
+    </ul>
+  );
+
+  const body = empty ?? noMatches;
+  const hideable = cols.filter((c) => c.hideable !== false);
+  const from = total === 0 ? 0 : (pageNow - 1) * per + 1;
+  const to = Math.min(total, pageNow * per);
+
+  return (
+    <div className={cx("grid min-w-0 max-w-full gap-3", className)}>
+      {error ? <Notice tone="danger">{error}</Notice> : null}
+
+      {/* The toolbar: search, facets, the surface's own, the columns menu. */}
+      <div className="flex min-w-0 flex-wrap items-center gap-2">
+        {searchable ? (
+          <div className="w-full sm:w-64">
+            <InputGroup
+              icon="search"
+              type="search"
+              value={query ?? ""}
+              onChange={(e) => changeQuery(e.target.value)}
+              placeholder={searchPlaceholder}
+              aria-label={`Search ${label}`}
+              disabled={!manual && all.length === 0 && !loading}
+            />
+          </div>
+        ) : null}
+        {facetList.map((f) => {
+          const options = facetOptions(f, all, filterState, facetList, query, cols);
+          return (
+            <div key={f.key} className="min-w-0 flex-1 basis-40 sm:w-52 sm:flex-none">
+              <Combobox
+                multiple
+                searchable={options.length > 7}
+                options={options}
+                value={(filterState[f.key] ?? NONE).map(String)}
+                onValueChange={(values) => changeFacet(f.key, values)}
+                placeholder={f.label}
+                label={f.label}
+                disabled={!manual && all.length === 0}
+              />
+            </div>
+          );
+        })}
+        {narrowed ? (
+          <Button variant="quiet" size="sm" icon="x" onClick={clearFilters}>
+            Reset
+          </Button>
+        ) : null}
+        <div className="ml-auto flex flex-wrap items-center gap-2">
+          {toolbar}
+          {hideable.length > 1 ? (
+            <Menu
+              label="Columns, show or hide"
+              size="md"
+              trigger={
+                <>
+                  <Icon name="eye" />
+                  <span>Columns</span>
+                </>
+              }
+              className="border border-border"
+              items={[
+                { type: "label", label: "Show columns" },
+                ...hideable.map((c) => {
+                  const on = !hiddenSet.has(c.key);
+                  return {
+                    type: "checkbox",
+                    label: typeof c.header === "string" ? c.header : humanize(c.key),
+                    checked: on,
+                    // The last one shown stays: a table of no columns is nothing.
+                    disabled: on && shown.length <= 1,
+                    onCheckedChange: (next) =>
+                      setHidden((h) => {
+                        const list = (h ?? []).map(String);
+                        return next ? list.filter((k) => k !== c.key) : [...list, c.key];
+                      }),
+                  };
+                }),
+              ]}
+            />
+          ) : null}
+        </div>
+      </div>
+
+      {/* The bulk bar: what is selected, and what can be done to it. */}
+      {canSelect && count > 0 ? (
+        <div
+          role="region"
+          aria-label="Selected rows"
+          className="flex flex-wrap items-center gap-2 rounded-lg border border-border bg-muted px-3 py-2 text-sm"
+        >
+          <span data-nums className="font-medium">
+            {count.toLocaleString()} selected
+          </span>
+          {!manual && allOnPage && count < total ? (
+            <Button variant="link" size="sm" onClick={selectAllMatches}>
+              Select all {total.toLocaleString()}
+            </Button>
+          ) : null}
+          <Button variant="quiet" size="sm" onClick={clearSelection}>
+            Clear
+          </Button>
+          <div className="ml-auto flex flex-wrap items-center gap-2">
+            {bulkItems.map((a) => (
+              <Button
+                key={a.label}
+                size="sm"
+                icon={a.icon}
+                variant={a.tone === "danger" ? "danger" : "secondary"}
+                loading={running === a.label}
+                disabled={Boolean(running && running !== a.label) || a.disabled}
+                onClick={() => runBulk(a)}
+              >
+                {a.label}
+              </Button>
+            ))}
+          </div>
+        </div>
+      ) : null}
+      {bulkError ? (
+        <Notice tone="danger" onDismiss={() => setBulkError(null)}>
+          {bulkError}
+        </Notice>
+      ) : null}
+      {rowError ? (
+        <Notice tone="danger" onDismiss={() => setRowError(null)}>
+          {rowError}
+        </Notice>
+      ) : null}
+      {bulkNote ? (
+        <Notice tone="info" onDismiss={() => setBulkNote(null)}>
+          {bulkNote}
+        </Notice>
+      ) : null}
+
+      {body ?? (mobile === "cards" ? (
+        <>
+          <div className="grid gap-1 sm:hidden">
+            {canSelect && !loading && visible.length ? (
+              <Checkbox
+                checked={allOnPage}
+                ref={(el) => {
+                  if (el) el.indeterminate = someOnPage;
+                }}
+                onChange={togglePage}
+                label="Select this page"
+                className="px-1 text-muted-foreground"
+              />
+            ) : null}
+            {cards}
+          </div>
+          <div className="hidden sm:block">{table}</div>
+        </>
+      ) : (
+        table
+      ))}
+
+      {footer}
+
+      {paginate && !body && (total > 0 || loading) ? (
+        <div className="flex flex-wrap items-center gap-x-4 gap-y-2">
+          <p data-nums className="w-full text-sm text-muted-foreground sm:w-auto" id={`${uid}-range`}>
+            {loading ? "Loading…" : `${from.toLocaleString()}–${to.toLocaleString()} of ${plural(total, noun)}`}
+          </p>
+          <Pagination
+            page={pageNow}
+            pageCount={pageCount}
+            onPageChange={setPage}
+            pageSize={per}
+            pageSizes={pageSizes}
+            onPageSizeChange={(n) => {
+              setSize(n);
+              if (pageNow !== 1) setPage(1);
+            }}
+            size="sm"
+            label={`${label} pages`}
+            className="min-w-0 flex-1"
+          />
+        </div>
+      ) : null}
+
+      <p aria-live="polite" className="sr-only">
+        {announce}
+      </p>
+    </div>
+  );
+}