@gemboss/ui 0.12.0 → 0.21.0

package/src/collections.tsx

@@ -0,0 +1,543 @@
+/**
+ * Collections (0.13.0): five of the six patterns Chris settled on 05/10/2026, as thin components over the classes of
+ * `@gemboss/ui/collections.css` (load it beside gemboss-ui.css). The sixth, `IndexTable`, keeps selection state and is
+ * in ./index-table (a client module). README "Collections" says which pattern to use when.
+ *
+ *   DataTable     compare values across items, column by column (reports, logs). Polaris DataTable.
+ *   ResourceList  read item by item: small media, a title, one or two lines, badges, one action. Polaris ResourceList.
+ *   CompactList   one line per item (a side rail, a popup, "needs attention"); `variant="activity"` is the timeline.
+ *   CardGrid      the picture is the content; auto-fill at 200 / 240 / 320, 16 apart. With MediaCard.
+ *   Board         items moving through fixed states; 12 cards a column, then "Show 24 more".
+ *   CollectionState / CollectionSkeleton   empty, no match, error, loading (in the shape of the pattern).
+ *
+ * A plain module: no hooks, no "use client", so a server component renders every one of these with any props (render
+ * functions included), and nothing the admin imports pulls it into its first load (the admin draws tables with
+ * Polaris; same reasoning as ./page). The markup is the same as the plain-HTML contract in the catalog, so a surface
+ * without React writes these classes by hand and gets the same thing.
+ */
+import React from "react";
+import { attachBoardMove } from "./board-move";
+
+const cx = (...c: Array<string | false | null | undefined>) => c.filter(Boolean).join(" ");
+
+export type SortDirection = "ascending" | "descending";
+export type CollectionSort = { key: string; direction: SortDirection };
+
+/** A column of a DataTable or an IndexTable. Every field is plain data, so a server component can build it. */
+export type CollectionColumn = {
+  key: string;
+  header: React.ReactNode;
+  /** Right-aligned tabular figures, header included (`is-num`). */
+  numeric?: boolean;
+  /** Where clicking the header goes to sort by this column (the order lives in the URL). */
+  sortHref?: string;
+  /** Sortable through `onSort` (a client parent) instead of a link. */
+  sortable?: boolean;
+  /** IndexTable below 768: "hide" leaves the cell out of the folded row; default shows it on the second line. */
+  condensed?: "sub" | "hide";
+  /** IndexTable below 768: the words in front of the value on the folded line ("Score"). */
+  label?: string;
+  /** Cap the cell at this width with an ellipsis (the whole text belongs in the cell's `title`). */
+  truncate?: number | string;
+  /** DataTable (0.16.0): the column is never narrower than this, for cells that wrap (a title + a sub line, a note), so
+   *  a narrow frame scrolls instead of squeezing them to a word a line. Polaris `firstColumnMinWidth`, for any column.
+   *  A row header's column has a floor of its own (9.0625rem, Polaris's first column) that this replaces: `0` removes
+   *  it for a row header that is always short (a date, an id). */
+  minWidth?: number | string;
+};
+
+export type CollectionRow = { id: string; cells: Record<string, React.ReactNode> };
+
+/** `aria-sort` for a column header: only on a sortable column; "none" when it is not the current sort. */
+export function ariaSort(col: CollectionColumn, sort?: CollectionSort | null): React.AriaAttributes["aria-sort"] {
+  if (!col.sortHref && !col.sortable) return undefined;
+  return sort && sort.key === col.key ? sort.direction : "none";
+}
+
+/** Extra props for every sort link (0.16.0), passed to `linkAs`: `{ scroll: false }` for a Next `Link` keeps the page
+ *  where it is, since a sort is the same page in another order. Plain data, so a server component can pass it. */
+export type SortLinkProps = Record<string, unknown>;
+
+/** The header cell's contents: the label, as a link (`sortHref`) or a button (`onSort`) when the column sorts. The link
+ *  is `linkAs` (0.16.0; default `<a>`), the same element as the rows' titles: a router link sorts without reloading the page. */
+export function SortHeader({ col, sort, onSort, linkAs: Link = "a", linkProps }: { col: CollectionColumn; sort?: CollectionSort | null; onSort?: (key: string, direction: SortDirection) => void;
+  linkAs?: React.ElementType; linkProps?: SortLinkProps }) {
+  const next: SortDirection = sort && sort.key === col.key && sort.direction === "ascending" ? "descending" : "ascending";
+  if (col.sortHref) return <Link {...linkProps} className="ui-table__sort" href={col.sortHref}>{col.header}</Link>;
+  if (col.sortable && onSort) return <button type="button" className="ui-table__sort" onClick={() => onSort(col.key, next)}>{col.header}</button>;
+  return <>{col.header}</>;
+}
+
+const truncStyle = (t: CollectionColumn["truncate"]): React.CSSProperties | undefined =>
+  t == null ? undefined : ({ ["--ui-trunc" as string]: typeof t === "number" ? `${t}px` : t } as React.CSSProperties);
+const minStyle = (w: CollectionColumn["minWidth"]): React.CSSProperties | undefined => (w == null ? undefined : { minWidth: w });
+
+export function Truncate({ children, title, width }: { children: React.ReactNode; title?: string; width?: number | string }) {
+  return <span className="ui-trunc" title={title} style={truncStyle(width)}>{children}</span>;
+}
+
+// ── 1 · DataTable ──────────────────────────────────────────────────────────────────────────────────────────────────
+
+export type DataTableProps = {
+  columns: CollectionColumn[];
+  rows: CollectionRow[];
+  /** Names the table for a screen reader (a visually hidden caption). */
+  label: string;
+  sort?: CollectionSort | null;
+  onSort?: (key: string, direction: SortDirection) => void;
+  /** The link element for the sort links (`sortHref`): a Next `Link` from a client module, so a sort does not reload the
+   *  page (0.16.0). Default `<a>`. */
+  linkAs?: React.ElementType;
+  /** Extra props for those links, e.g. `{ scroll: false }` for a Next `Link` (0.16.0). */
+  sortLinkProps?: SortLinkProps;
+  /** The first column stays put while the table scrolls sideways (what a data table does below 768). */
+  stickyFirstColumn?: boolean;
+  /** Rows 32 instead of 36: only for more than 20 rows. */
+  density?: "default" | "compact";
+  /** The first cell of every row is its header (`th scope="row"`). Default true: a data table's first column names the row. */
+  rowHeaders?: boolean;
+  totals?: Record<string, React.ReactNode>;
+  footer?: React.ReactNode;
+  /** loading → the skeleton in this table's shape; busy → the rows stay, dimmed; empty / no-match / error → `stateSlot`. */
+  state?: "ready" | "loading" | "busy" | "empty" | "no-match" | "error";
+  /** What to show for empty / no-match / error: a `CollectionState`. The header stays above it. */
+  stateSlot?: React.ReactNode;
+  className?: string;
+};
+
+export function DataTable({ columns, rows, label, sort, onSort, linkAs, sortLinkProps, stickyFirstColumn, density = "default", rowHeaders = true, totals, footer, state = "ready", stateSlot, className }: DataTableProps) {
+  if (state === "loading") return <CollectionSkeleton pattern="table" columns={columns} label={label} />;
+  const showRows = state === "ready" || state === "busy";
+  return (
+    <div className={cx("ui-table-wrap", className)} aria-busy={state === "busy" ? true : undefined}>
+      <table className={cx("ui-table", stickyFirstColumn && "ui-table--sticky-first", density === "compact" && "ui-table--compact")}>
+        <caption className="ui-sr-only">{label}</caption>
+        <thead>
+          <tr>{columns.map((c) => <th key={c.key} scope="col" className={c.numeric ? "is-num" : undefined} style={minStyle(c.minWidth)} aria-sort={ariaSort(c, sort)}><SortHeader col={c} sort={sort} onSort={onSort} linkAs={linkAs} linkProps={sortLinkProps} /></th>)}</tr>
+        </thead>
+        {showRows ? (
+          <tbody>
+            {rows.map((r) => (
+              <tr key={r.id}>
+                {columns.map((c, i) => {
+                  const body = c.truncate != null ? <span className="ui-trunc" style={truncStyle(c.truncate)}>{r.cells[c.key]}</span> : r.cells[c.key];
+                  return i === 0 && rowHeaders
+                    ? <th key={c.key} scope="row" className={c.numeric ? "ui-table__rowhead is-num" : "ui-table__rowhead"} style={minStyle(c.minWidth)}>{body}</th>
+                    : <td key={c.key} className={c.numeric ? "is-num" : undefined}>{body}</td>;
+                })}
+              </tr>
+            ))}
+          </tbody>
+        ) : null}
+        {totals && showRows ? (
+          <tfoot className="ui-table__totals"><tr>{columns.map((c) => <td key={c.key} className={c.numeric ? "is-num" : undefined}>{totals[c.key]}</td>)}</tr></tfoot>
+        ) : null}
+      </table>
+      {!showRows ? stateSlot : null}
+      {footer && showRows ? <div className="ui-table__footer">{footer}</div> : null}
+    </div>
+  );
+}
+
+// ── 3 · ResourceList / ResourceItem ────────────────────────────────────────────────────────────────────────────────
+
+export type ResourceItemProps = {
+  title: React.ReactNode;
+  /** The detail page. The WHOLE row then opens it; the title stays a real link. */
+  href?: string;
+  /** The link element: a Next `Link`, a router link. Default `<a>`. */
+  linkAs?: React.ElementType;
+  /** The full title, when it may be cut by the ellipsis. */
+  titleText?: string;
+  media?: React.ReactNode;
+  subtitle?: React.ReactNode;
+  meta?: React.ReactNode;
+  /** At most three are shown; the rest become "+N". */
+  badges?: React.ReactNode[];
+  aside?: React.ReactNode;
+  /** One button and/or a ⋯ `Menu`. Never more than one visible button. */
+  actions?: React.ReactNode;
+  selected?: boolean;
+  id?: string;
+  /** The selection checkbox, first in the media slot (as Polaris ResourceItem's). `SelectableResourceList` fills it. */
+  check?: React.ReactNode;
+};
+
+export function ResourceItem({ title, href, linkAs: Link = "a", titleText, media, subtitle, meta, badges, aside, actions, selected, id, check }: ResourceItemProps) {
+  const shown = (badges || []).slice(0, 3), more = (badges || []).length - shown.length;
+  return (
+    // Not aria-selected: a listitem does not take it (jsx-a11y role-supports-aria-props). With a checkbox the box says
+    // it; without one, `selected` marks the item open beside the list (master-detail): aria-current.
+    <li className={cx("ui-list__item", selected && "is-selected")} id={id} aria-current={selected && !check ? "true" : undefined}>
+      {media || check ? <div className="ui-list__media">{check}{media}</div> : null}
+      <div className="ui-list__body">
+        {href ? <Link className="ui-list__title" href={href} title={titleText}>{title}</Link> : <span className="ui-list__title" title={titleText}>{title}</span>}
+        {subtitle ? <p className="ui-list__sub">{subtitle}</p> : null}
+        {meta ? <p className="ui-list__meta">{meta}</p> : null}
+        {shown.length ? <div className="ui-list__badges">{shown.map((b, i) => <React.Fragment key={i}>{b}</React.Fragment>)}{more > 0 ? <span className="ui-badge">+{more}</span> : null}</div> : null}
+      </div>
+      {aside != null ? <div className="ui-list__aside">{aside}</div> : null}
+      {actions ? <div className="ui-list__actions">{actions}</div> : null}
+    </li>
+  );
+}
+
+export type ResourceListProps = {
+  label: string;
+  children?: React.ReactNode;
+  /** Inside a card that is already the frame: no border, no shadow. */
+  flush?: boolean;
+  state?: "ready" | "loading" | "busy" | "empty" | "no-match" | "error";
+  stateSlot?: React.ReactNode;
+  /** How many placeholder rows while loading (the number expected, at most 10). */
+  loadingRows?: number;
+  /** The media shape of the loading rows. */
+  loadingMedia?: "avatar" | "thumbnail" | "none";
+  className?: string;
+};
+
+export function ResourceList({ label, children, flush, state = "ready", stateSlot, loadingRows = 5, loadingMedia = "thumbnail", className }: ResourceListProps) {
+  if (state === "loading") return <CollectionSkeleton pattern="list" rows={loadingRows} media={loadingMedia} label={label} flush={flush} />;
+  if (state === "empty" || state === "no-match" || state === "error") {
+    return <div className={cx("ui-list", flush && "ui-list--flush", className)} role="region" aria-label={label}>{stateSlot}</div>;
+  }
+  return <ul className={cx("ui-list", flush && "ui-list--flush", className)} aria-label={label} aria-busy={state === "busy" ? true : undefined}>{children}</ul>;
+}
+
+// ── 4 · CompactList ────────────────────────────────────────────────────────────────────────────────────────────────
+
+export type CompactItem = {
+  id: string;
+  label: React.ReactNode;
+  href?: string;
+  onClick?: () => void;
+  icon?: React.ReactNode;
+  meta?: React.ReactNode;
+  current?: boolean;
+  /** The full label as text, for `title` when the label can be cut (not under `wrap`, where it is all on screen). */
+  labelText?: string;
+  /** activity: the line under the label, and the dot's tone. */
+  detail?: React.ReactNode;
+  /** activity (0.15.0): the event's own text under the label and the detail (a summary, a note, a post): body size,
+   *  wraps, never cut (`.ui-list__content`). Paragraphs as `<p>`. Not drawn by the one-line variant. */
+  body?: React.ReactNode;
+  time?: React.ReactNode;
+  dateTime?: string;
+  tone?: "success" | "warning" | "critical" | "info";
+};
+
+export type CompactListProps = {
+  items: CompactItem[];
+  label: string;
+  variant?: "activity";
+  linkAs?: React.ElementType;
+  flush?: boolean;
+  /** 0.15.0: the label (and an activity's detail) wrap instead of ending in "…" (`ui-list--wrap`). For a list whose
+   *  label carries data a finger must be able to read (a company, a colleague, who wrote it): `title` is mouse-only. */
+  wrap?: boolean;
+  className?: string;
+};
+
+export function CompactList({ items, label, variant, linkAs: Link = "a", flush, wrap, className }: CompactListProps) {
+  const activity = variant === "activity";
+  return (
+    <ul className={cx("ui-list ui-list--compact", activity && "ui-list--activity", wrap && "ui-list--wrap", flush && "ui-list--flush", className)} aria-label={label}>
+      {items.map((it) => activity ? (
+        <li key={it.id} className="ui-list__item">
+          <span className={cx("ui-list__dot", it.tone && `ui-list__dot--${it.tone}`)} aria-hidden="true" />
+          <div>
+            {it.href ? <Link className="ui-list__label" href={it.href} title={wrap ? undefined : it.labelText}>{it.label}</Link> : <span className="ui-list__label" title={wrap ? undefined : it.labelText}>{it.label}</span>}
+            {it.detail ? <span className="ui-list__detail">{it.detail}</span> : null}
+            {it.body ? <div className="ui-list__content">{it.body}</div> : null}
+          </div>
+          {it.time ? <time className="ui-list__time" dateTime={it.dateTime}>{it.time}</time> : <span />}
+        </li>
+      ) : (
+        <li key={it.id} className="ui-list__item">
+          {React.createElement(it.href ? Link : it.onClick ? "button" : "div", {
+            className: cx("ui-list__row", it.current && "is-selected"),
+            ...(it.href ? { href: it.href, "aria-current": it.current ? "page" : undefined } : it.onClick ? { type: "button", onClick: it.onClick } : {}),
+          }, <>
+            {it.icon ? <span className="ui-list__icon" aria-hidden="true">{it.icon}</span> : null}
+            <span className="ui-list__label" title={wrap ? undefined : it.labelText}>{it.label}</span>
+            {it.meta != null ? <span className="ui-list__meta">{it.meta}</span> : null}
+          </>)}
+        </li>
+      ))}
+    </ul>
+  );
+}
+
+// ── 5 · CardGrid / MediaCard ───────────────────────────────────────────────────────────────────────────────────────
+
+export type CardGridMin = 200 | 240 | 320;
+
+export function CardGrid({ min = 240, label, children, className }: { min?: CardGridMin; label?: string; children?: React.ReactNode; className?: string }) {
+  return <div className={cx("ui-cardgrid", className)} data-min={min === 240 ? undefined : min} role={label ? "list" : undefined} aria-label={label}>{children}</div>;
+}
+
+export type MediaCardProps = {
+  title: React.ReactNode;
+  href?: string;
+  linkAs?: React.ElementType;
+  /** The picture (an `<img alt="">`): the title names it. null on a board card without one. */
+  media?: React.ReactNode;
+  meta?: React.ReactNode;
+  badges?: React.ReactNode[];
+  /** The ⋯ menu, in the picture's corner. */
+  menu?: React.ReactNode;
+  foot?: React.ReactNode;
+  /** 16/10 by default; 4/3 for a theme or a page; 1/1 (0.18.0) for a square picture: a moodboard, a product shot, a
+   *  social post. These three only (no free ratio: a grid of mixed shapes loses its rows); any other value draws 16/10. */
+  ratio?: "16/10" | "4/3" | "1/1";
+  /** Inside CardGrid with a `label`, each card is a list item. */
+  listItem?: boolean;
+};
+
+export function MediaCard({ title, href, linkAs: Link = "a", media, meta, badges, menu, foot, ratio = "16/10", listItem }: MediaCardProps) {
+  return (
+    <article className="ui-card ui-card--media" data-ratio={ratio === "4/3" || ratio === "1/1" ? ratio : undefined} role={listItem ? "listitem" : undefined}>
+      {media == null ? null : href ? <Link className="ui-card__media" href={href} tabIndex={-1} aria-hidden="true">{media}</Link> : <div className="ui-card__media">{media}</div>}
+      {menu ? <div className="ui-card__menu">{menu}</div> : null}
+      <div className="ui-card__body">
+        {href ? <Link className="ui-card__link" href={href}>{title}</Link> : <span className="ui-card__link">{title}</span>}
+        {meta ? <span className="ui-card__meta">{meta}</span> : null}
+        {badges && badges.length ? <div className="ui-list__badges">{badges.slice(0, 3).map((b, i) => <React.Fragment key={i}>{b}</React.Fragment>)}</div> : null}
+      </div>
+      {foot ? <div className="ui-card__foot">{foot}</div> : null}
+    </article>
+  );
+}
+
+// ── 6 · Board ──────────────────────────────────────────────────────────────────────────────────────────────────────
+
+/** A card with its id (0.18.0): what a move reports and what server paging de-duplicates by. `name` is what the live
+ *  region says ("Moved <name> to Review"); default the card's title text. */
+export type BoardCard = { id: string; card: React.ReactNode; name?: string };
+
+export type BoardColumn = {
+  id: string;
+  title: React.ReactNode;
+  tone?: "success" | "warning" | "critical" | "info";
+  /** The cards, already rendered (MediaCard, or a `ui-card ui-card--media` without a picture). */
+  cards?: React.ReactNode[];
+  /** 0.18.0: the cards with their ids, instead of `cards`. Needed for `onMove` and for server paging. */
+  items?: BoardCard[];
+  /** The total when the column holds more than it was given (a server that sent the first page). */
+  count?: number;
+  empty?: React.ReactNode;
+  /** 0.18.0, server paging: the server has more cards for this column than it sent. The column then shows every card
+   *  it was given (the server already cut it: `boardShown(page)` cards, 12 then 24 more a page) and ends in ONE
+   *  "Show N more" that asks the server, instead of the nested `<details>` that need every card in the HTML. Default:
+   *  true when `moreHref` is set; `false` on the last page. */
+  hasMore?: boolean;
+  /** The URL of this page with this column showing one more page (`?col=ideas&page=2`): the position lives in the URL
+   *  like `ui-pager`'s, so it works with no script, Back and a sent link keep it. kit-plain.js fetches it and appends the
+   *  new cards in place (`data-gb-more`); in React it is `linkAs` (a Next `Link` re-renders the server page). */
+  moreHref?: string;
+  /** A request for the next page is under way (`onLoadMore`): the button becomes a spinner + "Loading…". */
+  loading?: boolean;
+};
+
+/** Cards a server-paged column shows at `page` (1-based): 12, then 24 more each page (Chris 05/10/2026). */
+export function boardShown(page: number, pageSize = 12, step = 24): number {
+  // A page read from a query string that is missing or not a number (NaN) is the first page, not an empty column.
+  const p = Number.isFinite(page) ? Math.max(1, Math.floor(page)) : 1;
+  return pageSize + (p - 1) * step;
+}
+
+export type BoardProps = {
+  columns: BoardColumn[];
+  label: string;
+  /** The board's DOM id, and the prefix of the ids inside (column headings, the move help). Set it when a page has two
+   *  boards: kit-plain.js reads a fetched page's column from the board with the same id. */
+  id?: string;
+  pageSize?: number;
+  step?: number;
+  moreLabel?: (n: number) => React.ReactNode;
+  emptyLabel?: React.ReactNode;
+  /** 0.18.0: server paging from a client parent: "Show N more" calls this with the column's id (with `moreHref` too,
+   *  the link keeps its href for a new tab). The parent appends the cards and sets `loading` meanwhile. */
+  onLoadMore?: (columnId: string) => void;
+  /** The element for the "Show more" links (`moreHref`): a Next `Link` keeps the page in the app. Default `<a>`. */
+  linkAs?: React.ElementType;
+  /** Extra props for those links, e.g. `{ scroll: false }` for a Next `Link` (the page stays where it was). */
+  moreLinkProps?: Record<string, unknown>;
+  /** The page is plain HTML driven by kit-plain.js (React only renders it, nothing hydrates: GemFactory): the "Show more"
+   *  links get `data-gb-more`, so kit-plain.js fetches the next page and appends it in place. Never on a board React
+   *  owns: kit-plain.js would put foreign nodes in React's lists. */
+  fetchMore?: boolean;
+  /** 0.18.0: cards move between columns, by dragging or with the keyboard (Space, arrows, Space; board-move.ts). Called
+   *  once per drop with the card's id, the target column's id and its index there (0 = top, counted without the card).
+   *  Only cards given as `items` move. Without it the board is read-only, as before. */
+  onMove?: (cardId: string, toColumn: string, toIndex: number) => void;
+  className?: string;
+};
+
+/** The words a screen reader hears on a movable card (aria-describedby), and the plain-HTML contract's `<p hidden>`. */
+export const BOARD_MOVE_HELP = "Press Space to pick the card up, arrow keys to move it, Space to drop it, Escape to cancel.";
+
+/** 12 cards a column, then "Show 24 more" (nested `<details>`, no script): the GemFactory rule, now everyone's. With
+ *  `hasMore` (0.18.0) the server pages instead; with `onMove` cards move between columns. */
+export function Board({ columns, label, id, pageSize = 12, step = 24, moreLabel = (n) => `Show ${n} more`, emptyLabel = "Nothing here",
+  onLoadMore, linkAs: Link = "a", moreLinkProps, fetchMore, onMove, className }: BoardProps) {
+  const movable = !!onMove;
+  const prefix = id ?? "ui-board";
+  const help = `${prefix}-move-help`;
+  // A callback ref, not an effect: this module stays plain (a server component renders the board; refs do not run
+  // there). attachBoardMove wires the element once and reads the latest onMove at drop time.
+  const ref = movable ? (el: HTMLDivElement | null) => { if (el) attachBoardMove(el, (cardId, to, index) => onMove!(cardId, to, index)); } : undefined;
+  const entries = (col: BoardColumn): BoardCard[] => col.items ?? (col.cards || []).map((card, i) => ({ id: "", card, name: String(i) }));
+  const li = (c: BoardCard, key: React.Key) => c.id
+    ? <li key={c.id} data-id={c.id} data-name={c.name} {...(movable ? { tabIndex: 0, draggable: true, "aria-describedby": help } : {})}>{c.card}</li>
+    : <li key={key}>{c.card}</li>;
+  const rest = (cards: BoardCard[], from: number): React.ReactNode => {
+    if (from >= cards.length) return null;
+    const n = Math.min(step, cards.length - from);
+    return (
+      <details className="ui-board__more">
+        <summary className="ui-btn ui-btn--sm">{moreLabel(n)}</summary>
+        <ol className="ui-board__list">{cards.slice(from, from + n).map((c, i) => li(c, from + i))}</ol>
+        {rest(cards, from + n)}
+      </details>
+    );
+  };
+  const next = (col: BoardColumn, shown: number): React.ReactNode => {
+    if (!(col.hasMore ?? col.moreHref != null)) return null;
+    const n = col.count != null ? Math.min(step, Math.max(col.count - shown, 0)) : step;
+    if (col.loading) return <div className="ui-more ui-board__next" aria-busy="true"><span className="ui-spinner" aria-hidden="true" /><span role="status">Loading…</span></div>;
+    const words = n > 0 ? moreLabel(n) : "Show more";
+    const ask = onLoadMore ? (e: React.MouseEvent) => { if (e.metaKey || e.ctrlKey || e.shiftKey || e.button === 1) return; e.preventDefault(); onLoadMore(col.id); } : undefined;
+    return (
+      <div className="ui-more ui-board__next">
+        {col.moreHref
+          ? <Link {...moreLinkProps} className="ui-btn ui-btn--sm" href={col.moreHref} data-gb-more={fetchMore ? "" : undefined} onClick={ask}>{words}</Link>
+          : <button type="button" className="ui-btn ui-btn--sm" onClick={ask} disabled={!onLoadMore}>{words}</button>}
+      </div>
+    );
+  };
+  return (
+    <div className={cx("ui-board", className)} id={id} role="region" aria-label={label} ref={ref} data-gb-move={movable ? "" : undefined}>
+      {movable ? <p id={help} hidden>{BOARD_MOVE_HELP}</p> : null}
+      {movable ? <div className="ui-sr-only" aria-live="assertive" data-gb-live="" /> : null}
+      {columns.map((col) => {
+        const cards = entries(col);
+        const server = col.hasMore != null || col.moreHref != null;
+        return (
+          <section key={col.id} className="ui-board__col" data-col={col.id} aria-labelledby={`${prefix}-${col.id}`}>
+            <header className="ui-board__head">
+              <span className={cx("ui-board__dot", col.tone && `ui-board__dot--${col.tone}`)} aria-hidden="true" />
+              <span className="ui-board__name" id={`${prefix}-${col.id}`}>{col.title}</span>
+              <span className="ui-board__count">{col.count ?? cards.length}</span>
+            </header>
+            {cards.length ? (
+              server
+                ? <ol className="ui-board__list">{cards.map((c, i) => li(c, i))}</ol>
+                : <><ol className="ui-board__list">{cards.slice(0, pageSize).map((c, i) => li(c, i))}</ol>{rest(cards, pageSize)}</>
+            ) : <p className="ui-board__empty">{col.empty ?? emptyLabel}</p>}
+            {server ? next(col, cards.length) : null}
+          </section>
+        );
+      })}
+    </div>
+  );
+}
+
+// ── States ─────────────────────────────────────────────────────────────────────────────────────────────────────────
+
+export type CollectionStateProps = {
+  kind: "empty" | "no-match" | "error";
+  title: React.ReactNode;
+  body?: React.ReactNode;
+  /** empty: the ONE thing to do next (create, connect, run). no-match: "Clear filters". error: "Try again". */
+  action?: React.ReactNode;
+  /** error with data still on screen: when that data is from ("as of 14:05"). */
+  staleNote?: React.ReactNode;
+};
+
+/** Empty (nothing yet), no match (filters found nothing: the header and the filters stay), error (never an empty list). */
+export function CollectionState({ kind, title, body, action, staleNote }: CollectionStateProps) {
+  if (kind === "error") {
+    return (
+      <div className="ui-notice ui-notice--danger ui-coll-error" role="alert">
+        <div><b>{title}</b>{body ? <> {body}</> : null}{staleNote ? <span className="ui-muted"> {staleNote}</span> : null}</div>
+        {action}
+      </div>
+    );
+  }
+  return (
+    <div className={cx("ui-empty", kind === "no-match" && "ui-empty--no-match")}>
+      <p className="ui-empty__title">{title}</p>
+      {body ? <p className="ui-empty__body">{body}</p> : null}
+      {action}
+    </div>
+  );
+}
+
+export type SkeletonPattern = "table" | "index" | "list" | "compact" | "grid" | "board";
+
+/**
+ * A placeholder in the shape of the pattern: a table keeps its real header and gets 8px bars in the cells, a list a
+ * media box and two bars, a grid a picture and two bars. `rows` = the number of rows expected (at most 10). The bars'
+ * sheen stops under prefers-reduced-motion (ui.css). The whole block is one status for a screen reader.
+ */
+export function CollectionSkeleton({ pattern, rows = 5, columns = [], media = "thumbnail", label = "Loading", flush, loadingText = "Loading…", check, actions }:
+  { pattern: SkeletonPattern; rows?: number; columns?: CollectionColumn[]; media?: "avatar" | "thumbnail" | "none"; label?: string; flush?: boolean; loadingText?: string;
+    /** index: the checkbox and actions columns the real table will have; list (0.16.0): each row's box before its
+     *  media. So nothing moves when rows arrive. */ check?: boolean; actions?: boolean }) {
+  const n = Math.max(1, Math.min(10, rows));
+  const line = (w?: string) => <span className="ui-skeleton__line" style={w ? { width: w } : undefined} />;
+  const status = <span className="ui-sr-only" role="status">{loadingText}</span>;
+  if (pattern === "table" || pattern === "index") {
+    const cols = columns.length ? columns : [{ key: "a", header: "" }, { key: "b", header: "" }, { key: "c", header: "" }];
+    return (
+      <div className={cx("ui-table-wrap ui-skeleton--table", pattern === "index" && "ui-index")} aria-busy="true">
+        {status}
+        <table className={cx("ui-table", pattern === "index" && "ui-table--index")} aria-hidden="true">
+          <thead><tr>{check ? <th className="ui-table__check"><span className="ui-table__checkbox" /></th> : null}{cols.map((c) => <th key={c.key} className={c.numeric ? "is-num" : undefined}>{c.header}</th>)}{actions ? <th className="ui-table__actions" /> : null}</tr></thead>
+          <tbody>{Array.from({ length: n }, (_, i) => <tr key={i}>{check ? <td className="ui-table__check"><span className="ui-table__checkbox" /></td> : null}{cols.map((c) => <td key={c.key}>{line()}</td>)}{actions ? <td className="ui-table__actions">{line("40px")}</td> : null}</tr>)}</tbody>
+        </table>
+      </div>
+    );
+  }
+  if (pattern === "list" || pattern === "compact") {
+    return (
+      <div aria-busy="true">
+        {status}
+        <ul className={cx("ui-list", pattern === "list" ? "ui-skeleton--list" : "ui-list--compact ui-skeleton--compact", flush && "ui-list--flush")} aria-hidden="true">
+          {Array.from({ length: n }, (_, i) => pattern === "list" ? (
+            <li key={i} className="ui-list__item">
+              {check ? <span className="ui-list__media"><span className="ui-list__check" />{media !== "none" ? <span className={cx("ui-skeleton__block", media === "avatar" && "ui-skeleton__block--round")} /> : null}</span>
+                : media !== "none" ? <span className={cx("ui-skeleton__block", media === "avatar" && "ui-skeleton__block--round")} /> : null}
+              <span className="ui-list__body">{line()}{line()}</span>
+            </li>
+          ) : (
+            <li key={i} className="ui-list__item"><span className="ui-list__row"><span className="ui-skeleton__block" style={{ width: 16, height: 16 }} />{line()}</span></li>
+          ))}
+        </ul>
+      </div>
+    );
+  }
+  if (pattern === "grid") {
+    return (
+      <div aria-busy="true">
+        {status}
+        <div className="ui-cardgrid ui-skeleton--grid" aria-hidden="true">
+          {Array.from({ length: n }, (_, i) => (
+            <div key={i} className="ui-card ui-card--media"><span className="ui-card__media" /><span className="ui-card__body">{line()}{line()}</span></div>
+          ))}
+        </div>
+      </div>
+    );
+  }
+  return (
+    <div aria-busy="true">
+      {status}
+      <div className="ui-board ui-skeleton--board" aria-hidden="true">
+        {Array.from({ length: Math.min(n, 6) }, (_, i) => (
+          <div key={i} className="ui-board__col"><span className="ui-board__head">{line("40%")}</span><ol className="ui-board__list"><li /><li /><li /></ol></div>
+        ))}
+      </div>
+    </div>
+  );
+}