@gemboss/ui 0.10.0 → 0.13.0

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";

package/src/kit-plain.css

@@ -22,8 +22,7 @@
 
    Key-value list: `<dl class="ui-kv"><dt>Owner</dt><dd>Lily</dd>…</dl>` — label column sized to
    its longest label, value column takes the rest and wraps long keys and URLs. */
-.ui-btn--icon { flex: none; width: var(--ui-control-h); padding: 0; }
-.ui-btn--icon.ui-btn--sm { width: 28px; }
+.ui-btn--icon { flex: none; width: var(--ui-btn-h); padding: 0; }
 .ui-btn--icon svg { width: 18px; height: 18px; }
 /* Menu: the SURFACE is the shell's `gemboss-popover-surface` and the rows are the account menu's row (shell.css
    declares `.gemboss-account-menu-item, .ui-menu__item` together), so a kit menu and the account menu on one page
@@ -89,7 +88,23 @@
 .ui-link:focus-visible,
 .ui-prose :where(a:not([class])):focus-visible { outline: 2px solid var(--ui-focus, #5661f5); outline-offset: 2px; border-radius: 2px; }
 
-.ui-card--media { padding: 0; overflow: hidden; display: flex; flex-direction: column; }
+.ui-card--media { position: relative; padding: 0; overflow: hidden; display: flex; flex-direction: column; }
+/* 0.13.0 (README "Collections", card grid): the title is the card's link and its overlay covers the card
+   (`a.ui-card__link`; the picture link is aria-hidden, out of the tab order); `.ui-card__menu` (a ⋯ ui-menu) sits in the
+   picture's corner above it, and the card stops clipping so the open menu is not cut off; `data-ratio="4/3"` for a theme
+   or a page. */
+.ui-card__link { display: -webkit-box; -webkit-box-orient: vertical; -webkit-line-clamp: 2; line-clamp: 2; overflow: hidden; color: var(--ui-text); font-size: var(--ui-fs-body); line-height: 20px; font-weight: 650; text-decoration: none; overflow-wrap: anywhere; }
+.ui-card__link::after { content: ""; position: absolute; inset: 0; z-index: 0; }
+.ui-card__link:focus-visible { outline: none; }
+.ui-card--media:has(.ui-card__link) { cursor: pointer; }
+.ui-card--media:has(.ui-card__link:hover) { border-color: var(--ui-text-muted); }
+.ui-card--media:has(.ui-card__link:focus-visible) { outline: 2px solid var(--ui-focus); outline-offset: 1px; }
+.ui-card--media :is(.ui-card__foot button, .ui-card__foot a, .ui-card__body a:not(.ui-card__link), .ui-card__body button, select, input, summary) { position: relative; z-index: 1; }
+.ui-card__menu { position: absolute; top: 8px; right: 8px; z-index: 2; }
+.ui-card--media:has(> .ui-card__menu) { overflow: visible; }
+.ui-card--media:has(> .ui-card__menu) > .ui-card__media { border-radius: inherit; border-bottom-left-radius: 0; border-bottom-right-radius: 0; }
+.ui-card__meta { color: var(--ui-text-muted); font-size: var(--ui-fs-caption); line-height: 16px; }
+.ui-card--media[data-ratio="4/3"] > .ui-card__media { aspect-ratio: 4 / 3; }
 .ui-card__media {
   display: block; width: 100%; aspect-ratio: 16 / 10; margin: 0; padding: 0; border: 0;
   border-bottom: 1px solid var(--ui-border); background: var(--ui-surface-2); overflow: hidden; color: inherit;
@@ -114,8 +129,6 @@ button.ui-card__media, a.ui-card__media { cursor: pointer; }
    </div><div class="ui-modal__actions"><button class="ui-btn">Copy</button></div><button class="ui-modal__close">…` */
 .ui-modal__subtitle { display: block; margin-top: 2px; font-size: var(--ui-fs-caption); line-height: 16px; font-weight: 450; color: var(--ui-text-muted); overflow-wrap: anywhere; }
 .ui-modal__actions { flex: none; display: flex; flex-wrap: wrap; align-items: center; gap: var(--ui-space-2); }
-/* An icon button in the popup's head or foot is square at the popup's 28 (ui.css gives those buttons 0/12 padding). */
-:is(.ui-modal__head, .ui-modal__foot) .ui-btn--icon { width: 28px; padding: 0; }
 /* A popup taller than the screen: the body scrolls, the head and foot stay, so the actions are always reachable
    (320×568 with a long form put Huỷ/Xoá below the fold, unreachable under the locked page; review #3633). */
 .ui-overlay > .ui-modal { display: flex; flex-direction: column; max-height: calc(100dvh - 40px); }
@@ -151,8 +164,8 @@ button.ui-card__media, a.ui-card__media { cursor: pointer; }
    dưới cùng (delta + so với gì). */
 .ui-metrics--grid { display: grid; grid-template-columns: repeat(auto-fit, minmax(min(180px, 100%), 1fr)); gap: var(--ui-space-3); margin: 0; }
 .ui-metric--lg { gap: 4px; padding: var(--ui-space-3) var(--ui-space-4); }
-.ui-metric--lg .ui-metric__val { font-size: var(--gemboss-fs-h1, 24px); line-height: 1.1; }
-.ui-metric--lg .ui-metric__lbl { order: -1; font-size: var(--gemboss-fs-body, 14px); }
+.ui-metric--lg .ui-metric__val { font-size: 24px; line-height: 32px; } /* Polaris headingXl, as the admin's analytics cards */
+.ui-metric--lg .ui-metric__lbl { order: -1; font-size: var(--ui-fs-body); } /* bodyMd 13 (0.12: was 14) */
 .ui-metric__foot { display: flex; flex-wrap: wrap; align-items: baseline; gap: 4px 8px; font-size: var(--gemboss-fs-caption); color: var(--ui-text-muted); }
 @media (max-width: 520px) { .ui-metrics--grid { grid-template-columns: repeat(2, minmax(0, 1fr)); } }
 
@@ -200,7 +213,7 @@ button.ui-card__media, a.ui-card__media { cursor: pointer; }
    sau bước đầu mang `__rate` = tỉ lệ đi tiếp từ bước NGAY TRƯỚC (bề mặt tính). Ngang ở khổ rộng, dọc ở ≤ 520px. */
 .ui-funnel { display: grid; grid-auto-flow: column; grid-auto-columns: minmax(0, 1fr); gap: var(--ui-space-2); margin: 0; padding: 0; list-style: none; }
 .ui-funnel > li { position: relative; display: flex; flex-direction: column; gap: 2px; padding: var(--ui-space-3); border-radius: var(--ui-radius-md); background: var(--ui-surface-2); min-width: 0; }
-.ui-funnel__val { font-size: var(--gemboss-fs-h2, 20px); font-weight: 700; color: var(--ui-text); font-variant-numeric: tabular-nums; line-height: 1.15; }
+.ui-funnel__val { font-size: 20px; font-weight: 700; color: var(--ui-text); font-variant-numeric: tabular-nums; line-height: 24px; } /* Polaris headingLg */
 .ui-funnel__lbl { font-size: var(--gemboss-fs-caption); color: var(--ui-text-muted); overflow-wrap: anywhere; }
 .ui-funnel__rate { order: -1; font-size: var(--gemboss-fs-caption); font-weight: 600; color: var(--ui-series-1); font-variant-numeric: tabular-nums; }
 @media (max-width: 520px) { .ui-funnel { grid-auto-flow: row; } }
@@ -215,7 +228,7 @@ button.ui-card__media, a.ui-card__media { cursor: pointer; }
 @media (max-width: 960px) { .ui-grid--2 { grid-template-columns: minmax(0, 1fr); } }
 @media (max-width: 720px) { .ui-grid--3 { grid-template-columns: minmax(0, 1fr); } }
 .ui-section-head { margin: var(--ui-space-4) 0 0; }
-.ui-section-head > h2 { margin: 0; font-size: var(--gemboss-fs-h3, 16px); font-weight: 650; color: var(--ui-text); }
+.ui-section-head > h2 { margin: 0; font-size: 14px; line-height: 20px; font-weight: 650; color: var(--ui-text); } /* Polaris headingMd (0.12: was 16) */
 .ui-section-head > p { margin: 2px 0 0; font-size: var(--gemboss-fs-caption); color: var(--ui-text-muted); }
 
 /* Nhóm nút CHỮ không bao giờ bẻ chữ (03/10/2026, thanh lọc của gemnews ở 390px: "Mọi ngôn ngữ" thành hai dòng, "中文"
@@ -464,3 +477,23 @@ button.ui-metric:focus-visible { outline: 2px solid var(--ui-focus); outline-off
 @media (pointer: coarse), (max-width: 47.9975em) { .ui-pager > a, .ui-pager > [aria-disabled="true"] { min-width: 44px; min-height: 44px; } }
 /* Phone: 11 targets of 44px wrapped into 3-4 rows at 320 (measured). Keep Previous · current · Next; the range wraps under. */
 @media (max-width: 35.9975em) { .ui-pager > a:not([rel]):not([aria-current]):not([aria-disabled]), .ui-pager__gap { display: none; } }
+
+/* 0.12.0: filter chip and card stack, both drawn by hand on every surface the 05/10/2026 density audit read.
+   Filter chip: `<div class="ui-chips"><button type="button" class="ui-chip" aria-pressed="true">Shopify Plus</button>
+   <a class="ui-chip" href="?country=us" aria-current="page">US</a></div>`. Polaris FilterPill's shape (radius 8, a 1px line,
+   dashed until applied) at the Button's density: 28px, 12px/550, so a filter row and a button row are one height.
+   Applied = `aria-pressed="true"` (in place) or `aria-current="page"` (a URL), solid line and the selected tint. */
+.ui-chip {
+  display: inline-flex; align-items: center; justify-content: center; gap: 4px; box-sizing: border-box;
+  height: var(--ui-btn-h, 28px); padding: 0 12px; border: 1px dashed var(--ui-border); border-radius: var(--ui-radius-md);
+  background: var(--ui-surface); color: var(--ui-text); font: inherit; font-size: var(--ui-fs-caption); font-weight: 550;
+  line-height: 16px; white-space: nowrap; text-decoration: none; cursor: pointer;
+}
+.ui-chip:hover { border-style: solid; background: var(--ui-surface-2); }
+.ui-chip:focus-visible { outline: 2px solid var(--ui-focus); outline-offset: 1px; }
+.ui-chip:is([aria-pressed="true"], [aria-current="page"], [aria-current="true"]) { border-style: solid; border-color: var(--ui-accent); background: var(--ui-accent-soft); color: var(--ui-accent-strong); }
+@media (pointer: coarse), (max-width: 47.9975em) { .ui-chip { height: auto; min-height: 44px; min-width: 44px; } }
+/* Card stack: `<div class="ui-stack"><div class="ui-card">…</div><div class="ui-card">…</div></div>`. 16px between blocks,
+   Polaris BlockStack gap 400, the admin's spacing between cards on a page. `--tight` is 8 (inside a card). */
+.ui-stack { display: grid; grid-template-columns: minmax(0, 1fr); gap: var(--ui-space-4); }
+.ui-stack--tight { gap: var(--ui-space-2); }

package/src/kit-plain.js

@@ -17,6 +17,8 @@
      initPasswordFields();              // .gb-auth-pw-toggle reveal; resetPasswordFields() on sign-out
      initSearch();                      // TopbarSearch: ⌘K / Ctrl+K and "/" focus the box, Escape leaves it
      // initNav() runs by itself (0.10.0): a followed rail link shows a spinner, a rested-on link is prefetched
+     // initCollections() runs by itself (0.13.0): rows with data-href open on a click, .ui-index selection + bulk bar,
+     // client sort; gembossUI.selection(root) → the selected ids (README "Collections")
 */
 (function (g) {
   "use strict";
@@ -434,7 +436,140 @@
   }
   initNav();
 
+  /* Collections (0.13.0), for the markup in README "Collections" (collections.css). Runs by itself when the script loads,
+     delegated on the document, so rows rendered later are covered; `initCollections()` is idempotent.
+     - Row links: a row with `data-href` (an index-table `tr`, or any element) opens on a click anywhere that is not a
+       control of its own (ROW_CONTROLS: a link, button, checkbox, select, menu, `data-row-ignore`) and does not end a
+       text selection. It follows the row's own link to that href (so a client router, `target` and the nav spinner all
+       apply); Cmd / Ctrl / Shift / middle click opens a new tab. No such link: location.assign. A React IndexTable
+       handles its own rows (`.is-linked`, no data-href), so the two never both fire.
+     - Selection: in a `.ui-index`, `input[data-gb-select]` (value = the row's id) and `input[data-gb-select-all]` (the
+       header's and the bulk bar's). The row gets `is-selected` + aria-selected, select-all goes indeterminate, the
+       `.ui-bulkbar` shows with `[data-gb-count]` filled from its own template ("{n} selected"), Shift+click selects a
+       range, Escape clears. The page reads `gembossUI.selection(root)` (ids) or listens for `gb:selection`.
+     - Sort, only in a table with `data-gb-sort` (a React table owns its own buttons): `="client"` sorts its rows when a
+       `button.ui-table__sort` is pressed (by each cell's `data-sort-value`, else its text; numbers as numbers) and sets
+       aria-sort; `="event"` fires `gb:sort` ({ key: th.dataset.key, direction }) for the page. A server sort is a link
+       (`a.ui-table__sort`) and needs nothing. */
+  var 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';
+  var ESCAPE_OWNERS = 'details[open], dialog, [role="dialog"], [role="menu"]';
+  var collOn = false, lastBox = null;
+  function rowLink(row) {
+    var href = row.getAttribute("data-href"), links = row.querySelectorAll("a[href]");
+    for (var i = 0; i < links.length; i++) if (links[i].getAttribute("href") === href) return links[i];
+    return null;
+  }
+  function onRowClick(e) {
+    if (e.defaultPrevented || e.button > 1 || !e.target.closest) return;
+    var row = e.target.closest("[data-href]");
+    if (!row) return;
+    var hit = e.target.closest(ROW_CONTROLS);
+    if (hit && row.contains(hit)) return;
+    var sel = g.getSelection ? g.getSelection() : null;
+    if (sel && !sel.isCollapsed && sel.anchorNode && row.contains(sel.anchorNode)) return;
+    var a = rowLink(row), href = a ? a.href : new URL(row.getAttribute("data-href"), location.href).href;
+    if (e.metaKey || e.ctrlKey || e.shiftKey || e.button === 1) { g.open(href, "_blank", "noopener"); return; }
+    if (a) a.click(); else location.assign(href);
+  }
+  function selectionIn(root) {
+    var out = [];
+    root.querySelectorAll("input[data-gb-select]").forEach(function (b) { if (b.checked) out.push(b.value); });
+    return out;
+  }
+  function syncSelection(root) {
+    var boxes = root.querySelectorAll("input[data-gb-select]"), n = 0;
+    boxes.forEach(function (b) {
+      var row = b.closest("tr, .ui-list__item, [data-href]");
+      if (b.checked) n++;
+      if (row) { row.classList.toggle("is-selected", b.checked); row.setAttribute("aria-selected", b.checked ? "true" : "false"); }
+    });
+    root.querySelectorAll("input[data-gb-select-all]").forEach(function (b) { b.checked = n > 0 && n === boxes.length; b.indeterminate = n > 0 && n < boxes.length; });
+    var bar = root.querySelector(".ui-bulkbar");
+    if (bar) bar.hidden = n === 0;
+    var c = root.querySelector("[data-gb-count]");
+    if (c) c.textContent = (c.getAttribute("data-gb-count") || "{n} selected").replace("{n}", n);
+    root.dispatchEvent(new CustomEvent("gb:selection", { bubbles: true, detail: { ids: selectionIn(root), total: boxes.length } }));
+  }
+  function clearSelection(root) {
+    root.querySelectorAll("input[data-gb-select]").forEach(function (b) { b.checked = false; });
+    syncSelection(root);
+  }
+  function sortValue(td) {
+    if (!td) return "";
+    var v = td.getAttribute("data-sort-value");
+    return v != null ? v : td.textContent.trim();
+  }
+  function onSortClick(btn) {
+    var th = btn.closest("th"), table = btn.closest("table");
+    if (!th || !table) return;
+    var dir = th.getAttribute("aria-sort") === "ascending" ? "descending" : "ascending";
+    table.querySelectorAll("thead th[aria-sort]").forEach(function (x) { if (x !== th) x.setAttribute("aria-sort", "none"); });
+    th.setAttribute("aria-sort", dir);
+    if (table.getAttribute("data-gb-sort") !== "client") {
+      table.dispatchEvent(new CustomEvent("gb:sort", { bubbles: true, detail: { key: th.getAttribute("data-key"), direction: dir } }));
+      return;
+    }
+    var col = Array.prototype.indexOf.call(th.parentElement.children, th), body = table.tBodies[0];
+    if (!body) return;
+    var rows = Array.prototype.slice.call(body.rows), sign = dir === "ascending" ? 1 : -1;
+    var num = function (s) { var x = String(s).replace(/[\s,%$€£¥]/g, ""); return x !== "" && !isNaN(+x) ? +x : null; };
+    rows.sort(function (r1, r2) {
+      var a = sortValue(r1.cells[col]), b = sortValue(r2.cells[col]), na = num(a), nb = num(b);
+      return sign * (na != null && nb != null ? na - nb : String(a).localeCompare(String(b), undefined, { numeric: true, sensitivity: "base" }));
+    });
+    rows.forEach(function (r) { body.appendChild(r); });
+  }
+  function initCollections() {
+    if (collOn || typeof document === "undefined") return;
+    collOn = true;
+    document.addEventListener("click", function (e) {
+      var t = e.target;
+      if (!t || !t.closest) return;
+      // Only a table that asked for it (data-gb-sort): a React DataTable / IndexTable owns its own sort buttons.
+      var sb = t.closest("table[data-gb-sort] button.ui-table__sort");
+      if (sb) { onSortClick(sb); return; }
+      // A click in the checkbox cell around the box (40px cell, 24px box) selects, it does not open the row.
+      var cc = t.closest("td.ui-table__check, th.ui-table__check");
+      // Only the plain contract's boxes: a React IndexTable toggles its own cell (both would undo each other).
+      if (cc && t === cc) { var ib = cc.querySelector("input[data-gb-select], input[data-gb-select-all]"); if (ib) { ib.click(); return; } }
+      // Shift+click on a row box: remember it for the range (the change event carries no shiftKey).
+      var box = t.closest("input[data-gb-select]");
+      if (box) {
+        var root = box.closest(".ui-index");
+        if (root && e.shiftKey && lastBox && lastBox !== box && root.contains(lastBox)) {
+          var all = Array.prototype.slice.call(root.querySelectorAll("input[data-gb-select]"));
+          var i = all.indexOf(lastBox), j = all.indexOf(box), on = box.checked;
+          for (var k = Math.min(i, j); k <= Math.max(i, j); k++) all[k].checked = on;
+          syncSelection(root);
+        }
+        lastBox = box;
+        return;
+      }
+      onRowClick(e);
+    });
+    document.addEventListener("auxclick", function (e) { if (e.button === 1) onRowClick(e); });
+    document.addEventListener("change", function (e) {
+      var t = e.target;
+      if (!t || !t.matches) return;
+      var root = t.closest(".ui-index");
+      if (!root) return;
+      if (t.matches("input[data-gb-select-all]")) {
+        root.querySelectorAll("input[data-gb-select]").forEach(function (b) { b.checked = t.checked; });
+        syncSelection(root);
+      } else if (t.matches("input[data-gb-select]")) syncSelection(root);
+    });
+    document.addEventListener("keydown", function (e) {
+      if (e.key !== "Escape" || e.defaultPrevented || MODALS.length) return;
+      var root = document.activeElement && document.activeElement.closest ? document.activeElement.closest(".ui-index") : null;
+      // An open ⋯ menu or a dialog in the table takes this Escape (initMenus closes it), not the selection.
+      if (root && (document.activeElement.closest(ESCAPE_OWNERS) || root.querySelector(ESCAPE_OWNERS))) return;
+      if (root && root.querySelector("input[data-gb-select]:checked")) clearSelection(root);
+    });
+  }
+  initCollections();
+
   g.gembossUI = { openModal: openModal, toast: toast, confirm: confirm, initMenus: initMenus, closeMenus: closeMenus,
     initSearch: initSearch, initShell: initShell, initPasswordFields: initPasswordFields, resetPasswordFields: resetPasswordFields,
-    initNav: initNav, openModals: function () { return MODALS.length; } };
+    initNav: initNav, openModals: function () { return MODALS.length; },
+    initCollections: initCollections, selection: selectionIn, clearSelection: clearSelection, syncSelection: syncSelection };
 })(globalThis);

package/src/theme-dark.css

@@ -56,6 +56,7 @@
   --gemboss-danger-border: #5c2a24;
   --ui-accent-fg: #0d0d12;
   --ui-warning-fg: #e8c063;
+  --ui-card-shadow: none; /* a dark drop under a dark card is noise */
   --gb-brand-ink: #f2f3f5;
 }
 /* Avatar initials in dark: the tone's light end, so the text clears 4.5:1 on its tinted disc. */