@gemboss/ui 0.12.0 → 0.13.0

package/src/collections.tsx

@@ -0,0 +1,414 @@
+/**
+ * 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";
+
+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;
+};
+
+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";
+}
+
+/** The header cell's contents: the label, as a link (`sortHref`) or a button (`onSort`) when the column sorts. */
+export function SortHeader({ col, sort, onSort }: { col: CollectionColumn; sort?: CollectionSort | null; onSort?: (key: string, direction: SortDirection) => void }) {
+  const next: SortDirection = sort && sort.key === col.key && sort.direction === "ascending" ? "descending" : "ascending";
+  if (col.sortHref) return <a className="ui-table__sort" href={col.sortHref}>{col.header}</a>;
+  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);
+
+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 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, 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} aria-sort={ariaSort(c, sort)}><SortHeader col={c} sort={sort} onSort={onSort} /></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"}>{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;
+};
+
+export function ResourceItem({ title, href, linkAs: Link = "a", titleText, media, subtitle, meta, badges, aside, actions, selected, id }: ResourceItemProps) {
+  const shown = (badges || []).slice(0, 3), more = (badges || []).length - shown.length;
+  return (
+    <li className={cx("ui-list__item", selected && "is-selected")} id={id} aria-selected={selected ? true : undefined}>
+      {media ? <div className="ui-list__media">{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;
+  /** activity: the line under the label, and the dot's tone. */
+  detail?: React.ReactNode;
+  time?: React.ReactNode;
+  dateTime?: string;
+  tone?: "success" | "warning" | "critical" | "info";
+};
+
+export function CompactList({ items, label, variant, linkAs: Link = "a", flush, className }: { items: CompactItem[]; label: string; variant?: "activity"; linkAs?: React.ElementType; flush?: boolean; className?: string }) {
+  const activity = variant === "activity";
+  return (
+    <ul className={cx("ui-list ui-list--compact", activity && "ui-list--activity", 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}>{it.label}</Link> : <span className="ui-list__label">{it.label}</span>}
+            {it.detail ? <span className="ui-list__detail">{it.detail}</span> : 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">{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. */
+  ratio?: "16/10" | "4/3";
+  /** 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" ? "4/3" : 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 ──────────────────────────────────────────────────────────────────────────────────────────────────────
+
+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[];
+  /** The total when the column holds more than it was given (a server that sent the first page). */
+  count?: number;
+  empty?: React.ReactNode;
+};
+
+/** 12 cards a column, then "Show 24 more" (nested `<details>`, no script): the GemFactory rule, now everyone's. */
+export function Board({ columns, label, pageSize = 12, step = 24, moreLabel = (n) => `Show ${n} more`, emptyLabel = "Nothing here", className }:
+  { columns: BoardColumn[]; label: string; pageSize?: number; step?: number; moreLabel?: (n: number) => React.ReactNode; emptyLabel?: React.ReactNode; className?: string }) {
+  const rest = (cards: React.ReactNode[], 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 key={from + i}>{c}</li>)}</ol>
+        {rest(cards, from + n)}
+      </details>
+    );
+  };
+  return (
+    <div className={cx("ui-board", className)} role="region" aria-label={label}>
+      {columns.map((col) => (
+        <section key={col.id} className="ui-board__col" aria-labelledby={`ui-board-${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={`ui-board-${col.id}`}>{col.title}</span>
+            <span className="ui-board__count">{col.count ?? col.cards.length}</span>
+          </header>
+          {col.cards.length ? (
+            <>
+              <ol className="ui-board__list">{col.cards.slice(0, pageSize).map((c, i) => <li key={i}>{c}</li>)}</ol>
+              {rest(col.cards, pageSize)}
+            </>
+          ) : <p className="ui-board__empty">{col.empty ?? emptyLabel}</p>}
+        </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, so no column 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">
+              {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>
+  );
+}

package/src/index-table.tsx

@@ -0,0 +1,216 @@
+"use client";
+/**
+ * IndexTable (0.13.0): a list of entities people open, compare and act on in bulk. Polaris IndexTable's shape on the
+ * classes of `@gemboss/ui/collections.css` (README "Collections").
+ *
+ * - The WHOLE row opens the item (Chris 05/10/2026): a click anywhere that is not a control follows the row's title link
+ *   (`a.ui-table__title`), which stays a real link, so Cmd-click, middle-click and a screen reader all work. A click on
+ *   a checkbox, a button, a menu, a select or another link does what that control does and nothing else; so does a
+ *   click that ends a text selection. A row with two or more in-place editing controls should not be linked (`href`
+ *   off; link only its title by putting the link in `title` yourself).
+ * - Selection only with bulk actions: a checkbox column with nothing to do with the selection is inert (Artifacts and
+ *   GemCRM shipped exactly that). The bulk bar takes the header's place, carries its own select-all box (the folded list
+ *   has no header), and Escape clears the selection.
+ * - Below 768 of ITS container the table folds into a list (collections.css): the title line, then the other cells on
+ *   one caption line (`label` prefixes a value; `condensed: "hide"` leaves a cell out), checkbox and actions kept.
+ *
+ * Every prop that describes the table is plain data (rows of rendered cells, `sortHref` strings), so a server
+ * component can render it; the callbacks (`onSort`, `onSelectionChange`, bulk `onAction`) need a client parent.
+ * Its own module, "use client": nothing the admin imports pulls it in (first-load budget).
+ */
+import React, { useCallback, useEffect, useRef, useState } from "react";
+import { ariaSort, SortHeader, CollectionSkeleton, type CollectionColumn, type CollectionSort, type SortDirection } from "./collections";
+
+const cx = (...c: Array<string | false | null | undefined>) => c.filter(Boolean).join(" ");
+
+export type IndexTableRow = {
+  id: string;
+  /** The row's main text. With `href` the table makes it the row's link; without, pass your own `<a className="ui-table__title">` or leave the row unlinked. */
+  title: React.ReactNode;
+  /** The whole title for a screen tip when the ellipsis cuts it. */
+  titleText?: string;
+  href?: string;
+  /** "_blank" for a row that opens somewhere else (the row follows the same link). */
+  target?: string;
+  /** One line under the title (`ui-sub`). */
+  sub?: React.ReactNode;
+  /** Avatar 24/32 or a `ui-thumb` (40), left of the title. One size for the whole table. */
+  media?: React.ReactNode;
+  /** The other columns, by column key. */
+  cells: Record<string, React.ReactNode>;
+  /** One button and/or a ⋯ menu, at the end of the row. Never more than one visible button. */
+  actions?: React.ReactNode;
+};
+
+export type BulkAction = { content: React.ReactNode; onAction: (ids: string[]) => void; tone?: "critical" };
+
+export type IndexTableProps = {
+  /** The first column is the primary one (title, sub, media); the rest map to `row.cells[key]`. */
+  columns: CollectionColumn[];
+  rows: IndexTableRow[];
+  /** Names the table for a screen reader. */
+  label: string;
+  sort?: CollectionSort | null;
+  onSort?: (key: string, direction: SortDirection) => void;
+  /** Turns the checkbox column on. Only together with `bulkActions`. */
+  bulkActions?: BulkAction[];
+  /** Controlled selection; leave both out and the table keeps it. */
+  selected?: string[];
+  onSelectionChange?: (ids: string[]) => void;
+  /** "12 selected": `(n) => …`. */
+  selectedLabel?: (n: number) => React.ReactNode;
+  selectAllLabel?: string;
+  /** The link element for titles (a Next `Link` from a client parent). Default `<a>`. */
+  linkAs?: React.ElementType;
+  /** Below 768 the header is gone: these chips sort instead. Default: one per sortable column. */
+  sortLabel?: React.ReactNode;
+  state?: "ready" | "loading" | "busy" | "empty" | "no-match" | "error";
+  /** For empty / no-match / error: a `CollectionState`. The header stays above it. */
+  stateSlot?: React.ReactNode;
+  loadingRows?: number;
+  /** Whether the loading skeleton has an actions column (default: any row has actions). */
+  actionsColumn?: boolean;
+  className?: string;
+};
+
+/** Anything in a row that is a control of its own: a click on it is not a click on the row. */
+export const ROW_CONTROLS = 'a[href], button, input, select, textarea, label, summary, details, dialog, [role="dialog"], [role="menu"], [role="button"], [role="menuitem"], [role="checkbox"], [contenteditable="true"], [contenteditable=""], [data-row-ignore], .ui-table__check';
+/** Escape belongs to these first (a ⋯ menu, a dialog in the row): it closes them, not the selection. */
+export const ESCAPE_OWNERS = 'details[open], dialog, [role="dialog"], [role="menu"]';
+
+/** The click on a row, minus controls and text selection; follows the row's title link. Shared with kit-plain.js in spirit (same rules). */
+export function followRow(e: React.MouseEvent<HTMLElement>): void {
+  const row = e.currentTarget;
+  const t = e.target as Element;
+  if (e.defaultPrevented || e.button > 1) return;
+  // A portal (a popover rendered elsewhere) still bubbles React events through the row: not a click on the row.
+  if (!(t instanceof Node) || !row.contains(t)) return;
+  const hit = t.closest ? t.closest(ROW_CONTROLS) : null;
+  if (hit && row.contains(hit)) return;
+  const sel = typeof window !== "undefined" ? window.getSelection() : null;
+  if (sel && !sel.isCollapsed && sel.anchorNode && row.contains(sel.anchorNode)) return;
+  const a = row.querySelector<HTMLAnchorElement>("a.ui-table__title[href]");
+  if (!a) return;
+  if (e.metaKey || e.ctrlKey || e.shiftKey || e.button === 1) { window.open(a.href, "_blank", "noopener"); return; }
+  a.click();
+}
+
+export function IndexTable({ columns, rows, label, sort, onSort, bulkActions, selected: selectedProp, onSelectionChange, selectedLabel = (n) => `${n} selected`,
+  selectAllLabel = "Select all", linkAs: Link = "a", sortLabel = "Sort", state = "ready", stateSlot, loadingRows = 5, actionsColumn, className }: IndexTableProps) {
+  const selectable = !!(bulkActions && bulkActions.length);
+  const [own, setOwn] = useState<string[]>([]);
+  const selected = selectedProp ?? own;
+  const setSelected = useCallback((ids: string[]) => { if (!selectedProp) setOwn(ids); onSelectionChange?.(ids); }, [selectedProp, onSelectionChange]);
+  const rootRef = useRef<HTMLDivElement>(null);
+  const anchorRef = useRef<string | null>(null); // Shift+click range anchor: an id, so a re-sort cannot move it
+  const ids = rows.map((r) => r.id);
+  const idSet = new Set(ids), selSet = new Set(selected);
+  const n = selected.filter((id) => idSet.has(id)).length;
+  const hasActions = rows.some((r) => r.actions);
+  const all = n > 0 && n === ids.length, some = n > 0 && !all;
+  const headBox = useRef<HTMLInputElement>(null), barBox = useRef<HTMLInputElement>(null);
+  useEffect(() => { for (const b of [headBox.current, barBox.current]) if (b) b.indeterminate = some; }, [some]);
+  // Escape clears the selection while focus is in the table (a menu open inside it closes first: it stops the key).
+  useEffect(() => {
+    const root = rootRef.current;
+    if (!root || !selectable) return;
+    const onKey = (e: KeyboardEvent) => {
+      if (e.key !== "Escape" || e.defaultPrevented || n === 0) return;
+      // A ⋯ menu or a dialog open in the table takes this Escape (it closes), not the selection.
+      if ((e.target as Element).closest?.(ESCAPE_OWNERS) || root.querySelector(ESCAPE_OWNERS)) return;
+      setSelected([]);
+    };
+    root.addEventListener("keydown", onKey);
+    return () => root.removeEventListener("keydown", onKey);
+  }, [n, selectable, setSelected]);
+
+  if (state === "loading") return <CollectionSkeleton pattern="index" columns={columns} rows={loadingRows} label={label} check={selectable} actions={actionsColumn ?? hasActions} />;
+  const showRows = state === "ready" || state === "busy";
+  const [primary, ...rest] = columns;
+  const toggleAll = (on: boolean) => { anchorRef.current = null; setSelected(on ? ids : []); };
+  const toggle = (i: number, on: boolean, shift: boolean) => {
+    const id = ids[i];
+    const next = new Set(selected);
+    const from = anchorRef.current ? ids.indexOf(anchorRef.current) : -1; // -1 when the anchor left the rows (filter, page)
+    if (shift && from > -1) {
+      for (let k = Math.min(from, i); k <= Math.max(from, i); k++) on ? next.add(ids[k]) : next.delete(ids[k]);
+    } else if (on) next.add(id); else next.delete(id);
+    anchorRef.current = id;
+    setSelected(ids.filter((x) => next.has(x)));
+  };
+  const sortable = columns.filter((c) => c.sortHref || (c.sortable && onSort));
+
+  return (
+    <div className={cx("ui-index", className)} ref={rootRef} aria-busy={state === "busy" ? true : undefined}>
+      {sortable.length && showRows ? (
+        <div className="ui-index__sortbar" role="group" aria-label={typeof sortLabel === "string" ? sortLabel : "Sort"}>
+          <span aria-hidden="true">{sortLabel}</span>
+          {sortable.map((c) => {
+            const on = sort?.key === c.key;
+            const arrow = on ? (sort!.direction === "ascending" ? " ↑" : " ↓") : "";
+            return c.sortHref
+              ? <a key={c.key} className="ui-chip" href={c.sortHref} aria-current={on ? "true" : undefined}>{c.header}{arrow}</a>
+              : <button key={c.key} type="button" className="ui-chip" aria-pressed={on} onClick={() => onSort!(c.key, on && sort!.direction === "ascending" ? "descending" : "ascending")}>{c.header}{arrow}</button>;
+          })}
+        </div>
+      ) : null}
+      {selectable ? (
+        <div className="ui-bulkbar" hidden={n === 0}>
+          <label className="ui-table__checkbox"><input ref={barBox} type="checkbox" checked={all} aria-label={selectAllLabel} onChange={(e) => toggleAll(e.target.checked)} /></label>
+          <span className="ui-bulkbar__count" aria-live="polite">{selectedLabel(n)}</span>
+          <span className="ui-bulkbar__actions">
+            {bulkActions!.map((b, i) => (
+              <button key={i} type="button" className={cx("ui-btn ui-btn--sm", b.tone === "critical" && "ui-btn--critical")} onClick={() => b.onAction(ids.filter((x) => selSet.has(x)))}>{b.content}</button>
+            ))}
+          </span>
+        </div>
+      ) : null}
+      <div className="ui-table-wrap">
+        <table className="ui-table ui-table--index">
+          <caption className="ui-sr-only">{label}</caption>
+          <thead>
+            <tr>
+              {selectable ? <th className="ui-table__check" scope="col"><label className="ui-table__checkbox"><input ref={headBox} type="checkbox" checked={all} aria-label={selectAllLabel} onChange={(e) => toggleAll(e.target.checked)} disabled={!showRows || !rows.length} /></label></th> : null}
+              <th className="ui-table__primary" scope="col" aria-sort={ariaSort(primary, sort)}><SortHeader col={primary} sort={sort} onSort={onSort} /></th>
+              {rest.map((c) => <th key={c.key} scope="col" className={c.numeric ? "is-num" : undefined} aria-sort={ariaSort(c, sort)}><SortHeader col={c} sort={sort} onSort={onSort} /></th>)}
+              {hasActions ? <th className="ui-table__actions" scope="col"><span className="ui-sr-only">Actions</span></th> : null}
+            </tr>
+          </thead>
+          {showRows ? (
+            <tbody>
+              {rows.map((r, i) => {
+                const isSel = selSet.has(r.id);
+                const title = r.href
+                  ? <Link className="ui-table__title" href={r.href} target={r.target} rel={r.target === "_blank" ? "noopener" : undefined} title={r.titleText}>{r.title}</Link>
+                  : r.title;
+                return (
+                  <tr key={r.id} className={cx(r.href && "is-linked", isSel && "is-selected")} aria-selected={selectable ? isSel : undefined} onClick={r.href ? followRow : undefined} onAuxClick={r.href ? followRow : undefined}>
+                    {selectable ? (
+                      <td className="ui-table__check" onClick={(e) => { if (e.target === e.currentTarget) (e.currentTarget.querySelector("input") as HTMLInputElement | null)?.click(); }}>
+                        <label className="ui-table__checkbox">
+                          <input type="checkbox" checked={isSel} aria-label={`Select ${r.titleText ?? (typeof r.title === "string" ? r.title : r.id)}`}
+                            onChange={(e) => toggle(i, e.target.checked, (e.nativeEvent as MouseEvent).shiftKey)} />
+                        </label>
+                      </td>
+                    ) : null}
+                    <td className="ui-table__primary" style={primary.truncate != null ? ({ ["--ui-trunc" as string]: typeof primary.truncate === "number" ? `${primary.truncate}px` : primary.truncate } as React.CSSProperties) : undefined}>
+                      {r.media ? <div className="ui-table__primary-inner">{r.media}<div className="ui-table__primary-text">{title}{r.sub ? <span className="ui-sub">{r.sub}</span> : null}</div></div>
+                        : <>{title}{r.sub ? <span className="ui-sub">{r.sub}</span> : null}</>}
+                    </td>
+                    {rest.map((c) => (
+                      <td key={c.key} className={c.numeric ? "is-num" : undefined} data-label={c.label} data-condensed={c.condensed === "hide" ? "hide" : undefined}>
+                        {c.truncate != null ? <span className="ui-trunc" style={{ ["--ui-trunc" as string]: typeof c.truncate === "number" ? `${c.truncate}px` : c.truncate } as React.CSSProperties}>{r.cells[c.key]}</span> : r.cells[c.key]}
+                      </td>
+                    ))}
+                    {hasActions ? <td className="ui-table__actions">{r.actions ? <span className="ui-row-actions">{r.actions}</span> : null}</td> : null}
+                  </tr>
+                );
+              })}
+            </tbody>
+          ) : null}
+        </table>
+        {!showRows ? stateSlot : null}
+      </div>
+    </div>
+  );
+}

package/src/index.ts

@@ -7,6 +7,17 @@ export { PageContainer, pageWidthClass } from "./page";
 export type { PageWidth } from "./page";
 // The loading boundary every route group under @gemboss/ui/next needs (0.10.0). Plain module, like ./page.
 export { RouteCover, RouteHolding } from "./route-holding";
+// Collections (0.13.0): tables, lists, grids, boards. Their own modules, like ./page: nothing the admin imports pulls them in
+// (it draws tables with Polaris). ./collections is plain (a server component renders it); ./index-table is "use client".
+export {
+  Board, CardGrid, CollectionSkeleton, CollectionState, CompactList, DataTable, MediaCard, ResourceItem, ResourceList, SortHeader, Truncate, ariaSort,
+} from "./collections";
+export type {
+  BoardColumn, CardGridMin, CollectionColumn, CollectionRow, CollectionSort, CollectionStateProps, CompactItem, DataTableProps, MediaCardProps,
+  ResourceItemProps, ResourceListProps, SkeletonPattern, SortDirection,
+} from "./collections";
+export { IndexTable, followRow, ROW_CONTROLS } from "./index-table";
+export type { BulkAction, IndexTableProps, IndexTableRow } from "./index-table";
 export { GemMark } from "./GemMark";
 export { AuthError, AuthField, AuthFoot, AuthForm, AuthHelp, AuthLayout, PasswordField, AuthSubmit } from "./auth";
 export { BrandLockup } from "./brand";