@contraagent/elements 0.0.0-stage → 0.1.0

package/src/styles/status.ts

@@ -0,0 +1,52 @@
+// A status, by tone (core/tone.ts, primitives/pill.ts): one rule per tone, and
+// the status elements that take it (a mark, a pill, a word, a dot, a spinner).
+import { css } from 'lit';
+
+export const statusStyles = css`
+  /*
+   * data-tone names its status colour, which each kind of status element below takes as
+   * --tone (the colour) and --tone-bg (its tint). No data-tone: neutral.
+   */
+  [data-tone='failed'] { --tone: var(--status-failed); --tone-bg: var(--status-failed-bg); }
+  [data-tone='attention'] { --tone: var(--status-attention); --tone-bg: var(--status-attention-bg); }
+  [data-tone='done'] { --tone: var(--status-done); --tone-bg: var(--status-done-bg); }
+  [data-tone='running'] { --tone: var(--status-running); --tone-bg: var(--status-running-bg); }
+  [data-tone='muted'] { --tone: var(--status-muted); --tone-bg: var(--status-muted-bg); }
+
+  /*
+   * A status mark before a status word (data-mark): ✓ done, ✕ failed, ◌ not started or waiting.
+   * The shape keeps the meaning without colour; screen readers read the word only.
+   */
+  [data-mark]::before { margin-right: 0.35em; font-weight: 700; }
+  [data-mark='done']::before { content: '✓'; content: '✓' / ''; color: var(--status-done); }
+  [data-mark='failed']::before { content: '✕'; content: '✕' / ''; }
+  [data-mark='pending']::before { content: '◌'; content: '◌' / ''; }
+
+  /* text in a status colour: only on a status that applies (a count above 0 of a problem, a status word) */
+  .tone-text[data-tone] { color: var(--tone); }
+
+  /*
+   * A status as a pill, always with its word. A problem is tinted and marked (✕ failed, ◌ not started);
+   * done is quiet (a ✓ and the word): it is the usual case, and the problems are what stand out.
+   */
+  .pill { border-radius: var(--radius-pill); padding: 1px 10px; font-size: var(--font-size-sm); font-weight: 500; background: var(--raise); color: var(--text-2); white-space: nowrap; }
+  .pill[data-tone] { background: var(--tone-bg); color: var(--tone); }
+  .pill[data-tone='done'] { background: none; padding-left: 2px; color: var(--text-2); }
+
+  /* a status as a word in a row (History, Problems, Outputs): coloured for a problem, done quiet with its ✓ */
+  .jstop { font-weight: 600; }
+  .jstop[data-tone='failed'], .jstop[data-tone='attention'] { color: var(--tone); }
+  .jstop[data-tone='done'] { color: var(--text-2); font-weight: 500; }
+
+  /*
+   * A status as a dot (a run in the header and the run list). The shape carries it too:
+   * round done, square failed, diamond attention, a breathing ring running.
+   */
+  .dot { width: 8px; height: 8px; border-radius: 50%; background: var(--line2); flex: none; display: inline-block; }
+  .dot[data-tone] { background: var(--tone); }
+  .dot[data-tone='running'] { animation: breathe 1.8s ease-in-out infinite; }
+  .dot[data-tone='attention'] { border-radius: 1px; transform: rotate(45deg) scale(0.86); }
+  .dot[data-tone='failed'] { border-radius: 1.5px; }
+  .spin { width: 14px; height: 14px; border-radius: 50%; border: 2px solid var(--status-running-bg);
+    border-top-color: var(--status-running); animation: turn 0.9s linear infinite; flex: none; display: inline-block; }
+`;

package/src/styles/text.ts

@@ -0,0 +1,21 @@
+// Text: code, captions, words read only by screen readers, line breaks in a
+// tight box, links.
+import { css } from 'lit';
+
+export const textStyles = css`
+  .jmono, code, .mono { font-family: var(--mono); }
+  /* read by screen readers, not shown: the word beside a status mark or an icon */
+  .sr { position: absolute; width: 1px; height: 1px; padding: 0; margin: -1px; overflow: hidden; clip: rect(0 0 0 0); white-space: nowrap; border: 0; }
+  .jmono { font-size: 11.5px; }
+  .meta { color: var(--text-muted); font-size: var(--font-size-sm); }
+  /* a label in a tight box: it wraps at spaces and between phrases, never inside a word (Japanese included) */
+  .words { word-break: keep-all; overflow-wrap: break-word; line-break: strict; }
+  /* one fact of a row in .words (factLine): the line breaks between facts first, inside one only when it is wider than the box */
+  .words .f { display: inline-block; max-width: 100%; }
+  @supports (word-break: auto-phrase) {
+    .words:lang(ja) { word-break: auto-phrase; }
+  }
+  .mut, .jdim { color: var(--text-muted); }
+  a.lnk { color: var(--accent); cursor: pointer; text-decoration: none; }
+  a.lnk:hover { text-decoration: underline; }
+`;

package/src/styles/tokens.ts

@@ -0,0 +1,35 @@
+// The design tokens as an element's custom properties: each reads its `--ca-*`
+// property, which `data-ca-theme` on an ancestor sets (themes/data.ts) and a
+// `--ca-*` property of the page's own, set on the element or nearer to it,
+// overrides.
+import { css, unsafeCSS } from 'lit';
+import { DEFAULT_THEME, THEMES, type ThemeToken } from '../themes/data.js';
+import { TOKENS } from '../themes/tokens-list.js';
+
+const fallback = THEMES[DEFAULT_THEME].tokens as Record<string, string>;
+
+/** One token: its `--ca-*` property (a theme's value or the page's own), else the default theme's (or its derivation). */
+const declaration = (t: (typeof TOKENS)[number]): string =>
+  t.derive
+    ? `--${t.name}: var(${t.prop}, ${t.derive});`
+    : `--${t.name}: var(${t.prop}, ${fallback[t.name as ThemeToken]});`;
+
+/**
+ * The design tokens (`TOKENS` in themes/tokens-list.ts, with their meanings). A
+ * colour means one thing: text and surfaces are neutral, a status colour marks a
+ * status (only where it applies), the accent marks what can be clicked or is
+ * selected, and identity colours are small cues (an icon, a thin edge, a legend).
+ */
+export const tokenStyles = css`
+  :host {
+    ${unsafeCSS(TOKENS.map(declaration).join('\n    '))}
+    --sans: var(--ca-sans, system-ui, -apple-system, 'Segoe UI', Roboto, 'Helvetica Neue', Arial, sans-serif);
+    --mono: var(--ca-mono, ui-monospace, SFMono-Regular, Menlo, Consolas, 'Liberation Mono', monospace);
+    --ease: cubic-bezier(0.2, 0.8, 0.2, 1);
+    color-scheme: var(--ca-color-scheme, ${unsafeCSS(THEMES[DEFAULT_THEME].scheme)});
+    color: var(--text);
+  }
+  :host([hidden]) {
+    display: none !important;
+  }
+`;

package/src/table/data-table.ts

@@ -0,0 +1,367 @@
+import { LitElement, adoptStyles, html, nothing, type CSSResult, type PropertyValues, type TemplateResult } from 'lit';
+import { property, state } from 'lit/decorators.js';
+import { Directive, directive, PartType, type ElementPart, type PartInfo } from 'lit/directive.js';
+import { repeat } from 'lit/directives/repeat.js';
+import { emit } from '../core/events.js';
+import { withDefaults } from '../core/strings.js';
+import { toneAttr, type Tone } from '../core/tone.js';
+import { RovingFocusController } from '../primitives/roving-focus.js';
+import { rowOffsets, windowRowsAt, type RowWindow } from '../primitives/window.js';
+import { base } from '../styles/index.js';
+import { dataTableStyles } from './styles.js';
+import { DEFAULT_DATA_TABLE_STRINGS, isSortable, type DataColumn, type DataTableStrings, type SortState } from './types.js';
+
+/** Sets the attributes of a map on an element, and removes those it set before that the map no longer has. */
+class AttrsDirective extends Directive {
+  private names: string[] = [];
+
+  constructor(part: PartInfo) {
+    super(part);
+    if (part.type !== PartType.ELEMENT) throw new Error('attrs() goes on an element');
+  }
+
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars -- the argument update() reads
+  render(_map: Readonly<Record<string, string>> | undefined) {
+    return nothing;
+  }
+
+  override update(part: ElementPart, [map]: [Readonly<Record<string, string>> | undefined]) {
+    const el = part.element;
+    const next = Object.keys(map ?? {});
+    for (const n of this.names) if (!next.includes(n)) el.removeAttribute(n);
+    for (const n of next) if (el.getAttribute(n) !== map![n]) el.setAttribute(n, map![n]!);
+    this.names = next;
+    return nothing;
+  }
+}
+const attrs = directive(AttrsDirective);
+
+/** Interactive content inside a cell: a click on it is its own, not the row's. */
+const INTERACTIVE = new Set(['A', 'BUTTON', 'INPUT', 'SELECT', 'TEXTAREA', 'SUMMARY', 'LABEL']);
+
+/** The rows drawn before the first measure of the viewport. */
+const FIRST_ROWS = 60;
+
+/**
+ * A table of rows, one per item, in a real `<table>`: a header cell per column
+ * (`scope="col"`), the first `rowHeader` column as the row's header. The rows
+ * are one tab stop: the arrow keys, Home and End move between them, and Enter or
+ * a click is the row's primary action (`cae-activate`), or chooses it as the
+ * selection when the table is not `activatable` (`cae-select`). A sortable
+ * header sends `cae-sort`; the host orders the rows (`sortRows`) and sets them.
+ * Above `windowAt` rows, only the rows on screen are drawn, and a spacer stands
+ * for the others: as high as those rows were when drawn, or, for a row not drawn
+ * yet, as the rows drawn are on average. Rows may differ in height.
+ *
+ * Its look: `--cae-data-table-gap` (between the columns), `--cae-data-table-row-padding`,
+ * the parts, and `cellStyles` (styles for what the cells draw, added to the
+ * table's own).
+ *
+ * @tagname cae-data-table
+ * @fires cae-activate - `{id}`: a row's primary action (a click or Enter, when `activatable`)
+ * @fires cae-select - `{id}`: a row chosen as the selection (a click or Enter, when not `activatable`)
+ * @fires cae-sort - `{id, direction}`: a sortable header was clicked
+ * @csspart table - the `<table>`
+ * @csspart caption - the caption
+ * @csspart head - the header row's group
+ * @csspart header-cell - each header cell
+ * @csspart row - each row
+ * @csspart row-selected - the selected row
+ * @csspart cell - each cell
+ * @csspart empty - the cell that stands for no rows
+ * @slot caption - the caption, instead of `caption`
+ * @slot empty - what the table shows with no rows, instead of `strings.empty`
+ */
+export class CaeDataTable<R = unknown> extends LitElement {
+  static override styles = [base, dataTableStyles];
+
+  @property({ attribute: false }) columns: readonly DataColumn<R>[] = [];
+  @property({ attribute: false }) rows: readonly R[] = [];
+  /** A row's id: unique among the rows (`data-key`, the `id` of the events). By default its `id`. */
+  @property({ attribute: false }) rowKey: (row: R) => string = (row) => {
+    const id = (row as { id?: unknown }).id;
+    return typeof id === 'string' || typeof id === 'number' ? String(id) : '';
+  };
+  /** A row's tone (`data-tone` on the row). */
+  @property({ attribute: false }) rowTone?: (row: R) => Tone | undefined;
+  /** More attributes on a row (`data-*`), for the host's styles and tests. */
+  @property({ attribute: false }) rowAttrs?: (row: R) => Readonly<Record<string, string>>;
+  /** A click or Enter on a row is its primary action (`cae-activate`); otherwise it selects the row (`cae-select`). */
+  @property({ type: Boolean }) activatable = true;
+  /** The id of the selected row. */
+  @property() selected: string | null = null;
+  /** The column the rows are ordered by: shown in its header (`aria-sort`). The host orders the rows. */
+  @property({ attribute: false }) sort: SortState | null = null;
+  /** Above this many rows, only the rows on screen are drawn. */
+  @property({ type: Number }) windowAt = 200;
+  /** A row's height in px, until rows are measured. */
+  @property({ type: Number }) rowHeight = 32;
+  /** The table's caption (its accessible name). */
+  @property() caption = '';
+  @property({ attribute: false }) strings: Partial<DataTableStrings> = {};
+  /** Styles for what the cells draw, added after the table's own (the rows are `tr`, the cells `th` and `td`). */
+  @property({ attribute: false }) cellStyles: readonly CSSResult[] = [];
+
+  /** The rows drawn, when windowed. */
+  @state() private range: { from: number; to: number } = { from: 0, to: FIRST_ROWS };
+  /** Each drawn row's height, by its key: what stands for it while it is not drawn. */
+  private heights = new Map<string, number>();
+  /** Where each row starts (`rowOffsets`), for the rows as they are; null: to work out again. */
+  private offsets: number[] | null = null;
+  /** The row that holds the tab stop. */
+  private focusKey: string | null = null;
+  private scroller: HTMLElement | Window | null = null;
+  private resized: ResizeObserver | null = null;
+  private frame = 0;
+  /** The next update keeps `range` as set (Home and End set it before the scroller reports). */
+  private held = false;
+
+  private readonly roving = new RovingFocusController(this, {
+    items: () => [...this.renderRoot.querySelectorAll<HTMLElement>('tbody tr[data-key]')],
+    layout: 'vertical',
+    onMove: (el) => (this.focusKey = el.dataset['key'] ?? null),
+  });
+
+  private get windowed(): boolean {
+    return this.rows.length > this.windowAt;
+  }
+
+  override disconnectedCallback(): void {
+    super.disconnectedCallback();
+    this.unwatch();
+  }
+
+  /** Where each row starts: its measured height, else the drawn rows' average. */
+  private rowStarts(): number[] {
+    if (this.offsets) return this.offsets;
+    let sum = 0;
+    for (const h of this.heights.values()) sum += h;
+    const typical = this.heights.size ? sum / this.heights.size : this.rowHeight;
+    return (this.offsets = rowOffsets(this.rows.length, (i) => this.heights.get(this.rowKey(this.rows[i]!)) ?? typical));
+  }
+
+  /** The rows on screen, from where the table's body is in its scroller. */
+  private visible(): RowWindow {
+    const starts = this.rowStarts();
+    const body = this.renderRoot.querySelector('tbody');
+    // Before the first measure of the view: the first rows, about FIRST_ROWS of them.
+    if (!body || !this.scroller) return windowRowsAt(starts, 0, (starts.at(-1)! / Math.max(1, this.rows.length)) * FIRST_ROWS, 0);
+    const view =
+      this.scroller instanceof HTMLElement
+        ? { top: this.scroller.getBoundingClientRect().top, height: this.scroller.clientHeight }
+        : { top: 0, height: this.scroller.innerHeight };
+    return windowRowsAt(starts, view.top - body.getBoundingClientRect().top, view.height);
+  }
+
+  /** Scrolls the body's first row (or its last, `last`) into the scroller's view. */
+  private scrollToEnd(last: boolean): void {
+    const body = this.renderRoot.querySelector('tbody');
+    const s = this.scroller;
+    if (!body || !s) return;
+    const r = body.getBoundingClientRect();
+    const view = s instanceof HTMLElement ? s.getBoundingClientRect() : { top: 0, bottom: s.innerHeight };
+    const by = last ? r.bottom - view.bottom : r.top - view.top;
+    if (s instanceof HTMLElement) s.scrollTop += by;
+    else s.scrollBy(0, by);
+  }
+
+  private reframe(): void {
+    const w = this.visible();
+    if (w.from !== this.range.from || w.to !== this.range.to) this.range = { from: w.from, to: w.to };
+  }
+
+  private readonly onScroll = (): void => {
+    if (this.frame) return;
+    this.frame = requestAnimationFrame(() => {
+      this.frame = 0;
+      this.reframe();
+    });
+  };
+
+  /** The nearest ancestor that scrolls the table vertically, across shadow roots; the window when none does. */
+  private findScroller(): HTMLElement | Window {
+    let n: Node | null = this.parentNode;
+    while (n) {
+      if (n instanceof HTMLElement) {
+        const o = getComputedStyle(n).overflowY;
+        if ((o === 'auto' || o === 'scroll' || o === 'overlay') && n.scrollHeight > n.clientHeight + 1) return n;
+      }
+      n = n instanceof ShadowRoot ? n.host : n.parentNode;
+    }
+    return window;
+  }
+
+  private watch(): void {
+    if (this.scroller) return;
+    this.scroller = this.findScroller();
+    this.scroller.addEventListener('scroll', this.onScroll, { passive: true });
+    // Its height decides how many rows show: the window's when the page scrolls, else the scroller's own.
+    if (!(this.scroller instanceof HTMLElement)) window.addEventListener('resize', this.onScroll, { passive: true });
+    else if (typeof ResizeObserver !== 'undefined') (this.resized ??= new ResizeObserver(this.onScroll)).observe(this.scroller);
+  }
+
+  private unwatch(): void {
+    cancelAnimationFrame(this.frame);
+    this.frame = 0;
+    this.scroller?.removeEventListener('scroll', this.onScroll);
+    window.removeEventListener('resize', this.onScroll);
+    this.resized?.disconnect();
+    this.scroller = null;
+  }
+
+  override willUpdate(changed: PropertyValues<this>): void {
+    if (changed.has('rows') || changed.has('rowHeight')) this.offsets = null;
+    if (changed.has('rows') || changed.has('windowAt')) {
+      if (this.windowed && this.hasUpdated) {
+        const w = this.visible();
+        this.range = { from: w.from, to: w.to };
+      } else if (!this.windowed) this.unwatch();
+    }
+    // The tab stop stays on its row while the rows drawn change.
+    const keys = this.shown().map(this.rowKey);
+    const i = this.focusKey === null ? -1 : keys.indexOf(this.focusKey);
+    this.roving.current = Math.max(0, i);
+  }
+
+  override updated(changed: PropertyValues<this>): void {
+    if (changed.has('cellStyles') && this.renderRoot instanceof ShadowRoot)
+      adoptStyles(this.renderRoot, [...(this.constructor as typeof LitElement).elementStyles, ...this.cellStyles]);
+    if (!this.windowed) return;
+    this.watch();
+    // Measure the drawn rows: each stands for itself while it is not drawn. A row keeps its
+    // height, so the spacers settle as the rows are drawn once each.
+    let moved = false;
+    for (const tr of this.renderRoot.querySelectorAll<HTMLElement>('tbody tr[data-key]')) {
+      const h = tr.getBoundingClientRect().height;
+      const key = tr.dataset['key']!;
+      if (h > 0 && Math.abs(h - (this.heights.get(key) ?? -1)) > 0.5) {
+        this.heights.set(key, h);
+        moved = true;
+      }
+    }
+    if (moved) this.offsets = null;
+    if (this.held) this.held = false;
+    // On the next frame, never in this update: a window that changes the measures and so
+    // the window again then gives the page a frame, and the reader's input, each time.
+    else this.onScroll();
+  }
+
+  /** The rows drawn now. */
+  private shown(): readonly R[] {
+    if (!this.windowed) return this.rows;
+    return this.rows.slice(this.range.from, Math.min(this.rows.length, this.range.to));
+  }
+
+  /** The row of an event, and its id. */
+  private rowOf(e: Event): { tr: HTMLElement; id: string } | null {
+    for (const t of e.composedPath()) {
+      if (!(t instanceof HTMLElement)) continue;
+      if (INTERACTIVE.has(t.tagName)) return null;
+      if (t.tagName === 'TR' && t.dataset['key'] !== undefined) return { tr: t, id: t.dataset['key'] };
+      if (t === this) break;
+    }
+    return null;
+  }
+
+  private act(id: string): void {
+    if (this.activatable) {
+      emit(this, 'cae-activate', { id });
+      return;
+    }
+    this.selected = id;
+    emit(this, 'cae-select', { id });
+  }
+
+  private readonly onClick = (e: MouseEvent): void => {
+    const r = this.rowOf(e);
+    if (r) this.act(r.id);
+  };
+
+  private readonly onFocusIn = (e: FocusEvent): void => {
+    const r = this.rowOf(e);
+    if (r) this.focusKey = r.id;
+  };
+
+  private readonly onKey = (e: KeyboardEvent): void => {
+    const t = e.composedPath()[0];
+    if (!(t instanceof HTMLElement) || t.tagName !== 'TR' || t.dataset['key'] === undefined) return;
+    if (e.key === 'Enter') {
+      e.preventDefault();
+      this.act(t.dataset['key']);
+      return;
+    }
+    // Windowed, the first and last rows may not be drawn: draw them, then move there.
+    if (this.windowed && (e.key === 'Home' || e.key === 'End')) {
+      e.preventDefault();
+      e.stopPropagation();
+      const last = e.key === 'End';
+      const row = this.rows[last ? this.rows.length - 1 : 0];
+      if (row === undefined) return;
+      this.focusKey = this.rowKey(row);
+      const n = this.rows.length;
+      const span = Math.max(1, this.range.to - this.range.from);
+      this.scrollToEnd(last);
+      // Drawn at once, before the scroll reports where the view is.
+      this.range = last ? { from: Math.max(0, n - span), to: n } : { from: 0, to: span };
+      this.held = true;
+      void this.updateComplete.then(() => this.renderRoot.querySelector<HTMLElement>(`tbody tr[data-key="${CSS.escape(this.focusKey ?? '')}"]`)?.focus());
+    }
+  };
+
+  private header(c: DataColumn<R>, s: DataTableStrings): TemplateResult {
+    const on = this.sort?.id === c.id ? this.sort.direction : null;
+    const sort = on === 'asc' ? 'ascending' : on === 'desc' ? 'descending' : nothing;
+    const label = isSortable(c)
+      ? html`<button type="button" class="sort" title=${on === 'asc' ? s.sortDescending : s.sortAscending}
+          @click=${() => emit(this, 'cae-sort', { id: c.id, direction: on === 'asc' ? 'desc' : 'asc' })}>${c.header}${on
+            ? html`<span class="arrow" aria-hidden="true">${on === 'asc' ? '▲' : '▼'}</span>`
+            : nothing}</button>`
+      : c.header;
+    return html`<th scope="col" role="columnheader" part="header-cell" data-col=${c.id} data-align=${c.align ?? nothing} aria-sort=${sort}
+      title=${c.tip || nothing}>${label}</th>`;
+  }
+
+  private row(r: R, index: number, head: string | undefined): TemplateResult {
+    const id = this.rowKey(r);
+    const sel = this.selected !== null && this.selected === id;
+    return html`<tr role="row" part=${sel ? 'row row-selected' : 'row'} data-key=${id} data-tone=${toneAttr(this.rowTone?.(r))}
+      aria-current=${sel ? 'true' : nothing} aria-rowindex=${this.windowed ? index + 2 : nothing} ${attrs(this.rowAttrs?.(r))}>
+      ${this.columns.map((c) =>
+        c.id === head
+          ? html`<th scope="row" role="rowheader" part="cell" data-col=${c.id} data-align=${c.align ?? nothing}>${c.cell(r, index)}</th>`
+          : html`<td role="cell" part="cell" data-col=${c.id} data-align=${c.align ?? nothing}>${c.cell(r, index)}</td>`,
+      )}
+    </tr>`;
+  }
+
+  override render() {
+    const s = withDefaults(DEFAULT_DATA_TABLE_STRINGS, this.strings);
+    const n = this.rows.length;
+    const tracks = this.columns.map((c) => c.width ?? 'minmax(0, 1fr)').join(' ');
+    const head = this.columns.find((c) => c.rowHeader)?.id;
+    const from = this.windowed ? this.range.from : 0;
+    const shown = this.shown();
+    const starts = this.windowed ? this.rowStarts() : null;
+    const padTop = starts ? starts[from]! : 0;
+    const padBottom = starts ? starts[n]! - starts[from + shown.length]! : 0;
+    return html`<table part="table" data-scroll="x" role="table" class=${this.activatable ? '' : 'passive'} style="--cae-data-table-columns: ${tracks}"
+      aria-rowcount=${this.windowed ? n + 1 : nothing}>
+      <caption part="caption"><slot name="caption">${this.caption}</slot></caption>
+      <thead part="head" role="rowgroup"><tr role="row">${this.columns.map((c) => this.header(c, s))}</tr></thead>
+      <tbody role="rowgroup" @click=${this.onClick} @keydown=${this.onKey} @focusin=${this.onFocusIn}>
+        ${padTop > 0 ? html`<tr class="spacer" aria-hidden="true" style="height: ${padTop}px"></tr>` : nothing}
+        ${repeat(shown, this.rowKey, (r, i) => this.row(r, from + i, head))}
+        ${padBottom > 0 ? html`<tr class="spacer" aria-hidden="true" style="height: ${padBottom}px"></tr>` : nothing}
+        ${n
+          ? nothing
+          : html`<tr class="empty" role="row"><td part="empty" role="cell" colspan=${this.columns.length || 1}><slot name="empty">${s.empty}</slot></td></tr>`}
+      </tbody>
+    </table>`;
+  }
+}
+
+declare global {
+  interface HTMLElementTagNameMap {
+    'cae-data-table': CaeDataTable;
+  }
+}

package/src/table/index.ts

@@ -0,0 +1,5 @@
+// A table of rows: `@contraagent/elements/data-table`. `CaeDataTable` is
+// registered by `@contraagent/elements/data-table/define`.
+export * from './types.js';
+export * from './styles.js';
+export * from './data-table.js';

package/src/table/styles.ts

@@ -0,0 +1,32 @@
+// The look of `<cae-data-table>`. A row is a grid of the columns' tracks
+// (`--cae-data-table-columns`, set from the columns' widths), so every row
+// lines up with the header without a table layout pass. Rows wider than the
+// host scroll sideways inside the table; the host is a container, so the
+// host's `cellStyles` can drop or narrow columns by its width (`@container`).
+import { css } from 'lit';
+
+export const dataTableStyles = css`
+  :host { display: block; container-type: inline-size; }
+  table { display: block; width: 100%; border-collapse: collapse; overflow-x: auto; }
+  caption { display: block; text-align: start; }
+  thead, tbody { display: block; }
+  tr { display: grid; grid-template-columns: var(--cae-data-table-columns); column-gap: var(--cae-data-table-gap, 12px);
+    align-items: center; padding: var(--cae-data-table-row-padding, 6px 12px); }
+  th, td { display: block; min-width: 0; padding: 0; text-align: start; font-weight: inherit; }
+  [data-align='end'] { text-align: end; font-variant-numeric: tabular-nums; }
+  thead tr { color: var(--text-muted); font-size: var(--font-size-sm); border-bottom: 1px solid var(--line); }
+  tbody tr { border-bottom: 1px solid var(--line); }
+  tbody tr[data-key] { cursor: pointer; }
+  table.passive tbody tr[data-key] { cursor: default; }
+  tbody tr[data-key]:hover { background: var(--raise); }
+  tbody tr[data-key]:focus-visible { outline-offset: -2px; }
+  tbody tr[aria-current='true'] { background: var(--accent-bg); }
+  tbody tr[data-tone='running'] { background: var(--status-running-bg); }
+  tbody tr[data-tone='failed'] { background: color-mix(in srgb, var(--status-failed) 6%, transparent); box-shadow: inset 3px 0 0 var(--status-failed); }
+  tr.spacer { display: block; padding: 0; border: 0; }
+  tr.empty { display: block; border: 0; padding: 0; }
+  tr.empty td { color: var(--text-muted); padding: 8px; }
+  .sort { display: inline-flex; align-items: center; gap: 4px; padding: 0; border: 0; background: none; color: inherit; font: inherit; cursor: pointer; }
+  .sort:hover { color: var(--text); }
+  .arrow { font-size: 0.85em; }
+`;

package/src/table/types.ts

@@ -0,0 +1,73 @@
+// The data a `<cae-data-table>` shows: its columns, each a function of a row,
+// and its words.
+
+/** A column: its header, its width, and what a cell shows for a row. */
+export interface DataColumn<R> {
+  /** Unique among the columns: `data-col` on its cells, the `id` of `cae-sort`. */
+  id: string;
+  header: string;
+  /** The header's tooltip. */
+  tip?: string;
+  /** `end` for numbers: right-aligned, tabular figures. */
+  align?: 'start' | 'end';
+  /** A CSS grid track: '72px', 'minmax(0, 1fr)' (the default). */
+  width?: string;
+  /** The cell: a template, a string or a number. */
+  cell: (row: R, index: number) => unknown;
+  /** The cell as plain text: what `sortRows` orders by when the column has no `compare`. */
+  text?: (row: R) => string;
+  /** The order of two rows by this column, ascending. */
+  compare?: (a: R, b: R) => number;
+  /**
+   * The header is a button that sends `cae-sort` (true when the column has `compare`).
+   * Without `compare` and `text`, `sortRows` orders by the cell when it is a string or a number.
+   */
+  sortable?: boolean;
+  /** The cell names its row (`<th scope="row">`): the first such column does. */
+  rowHeader?: boolean;
+}
+
+/** The column the rows are ordered by. */
+export interface SortState {
+  id: string;
+  direction: 'asc' | 'desc';
+}
+
+export interface DataTableStrings {
+  /** The table has no rows. */
+  empty: string;
+  /** A sortable header's tooltip: the click orders the rows ascending. */
+  sortAscending: string;
+  /** A sortable header's tooltip: the click orders the rows descending. */
+  sortDescending: string;
+}
+
+export const DEFAULT_DATA_TABLE_STRINGS: Readonly<DataTableStrings> = {
+  empty: 'No rows',
+  sortAscending: 'Sort ascending',
+  sortDescending: 'Sort descending',
+};
+
+/** Whether a column's header sorts. */
+export const isSortable = <R>(c: DataColumn<R>): boolean => c.sortable ?? !!c.compare;
+
+/**
+ * `rows` ordered by the column `sort` names: by its `compare`, else its `text`, else
+ * its cell when that is a string or a number; equal rows keep their order. The rows
+ * as they are when no column matches.
+ */
+export function sortRows<R>(rows: readonly R[], columns: readonly DataColumn<R>[], sort: SortState | null): R[] {
+  const c = sort && columns.find((x) => x.id === sort.id);
+  if (!sort || !c) return [...rows];
+  const sign = sort.direction === 'desc' ? -1 : 1;
+  const { compare, text } = c;
+  // A cell that is neither a string nor a number (a template) keeps its place.
+  const value = (r: R, i: number) => {
+    const v = text ? text(r) : c.cell(r, i);
+    return typeof v === 'number' || typeof v === 'string' ? v : '';
+  };
+  const keyed = rows.map((r, i) => ({ r, i, v: compare ? 0 : value(r, i) }));
+  const cmp = (a: (typeof keyed)[number], b: (typeof keyed)[number]) =>
+    compare ? compare(a.r, b.r) : typeof a.v === 'number' && typeof b.v === 'number' ? a.v - b.v : String(a.v).localeCompare(String(b.v), undefined, { numeric: true });
+  return keyed.sort((a, b) => sign * cmp(a, b) || a.i - b.i).map((x) => x.r);
+}

package/src/themes/boot.ts

@@ -0,0 +1,14 @@
+// The page's theme before the first paint.
+import { THEME_STORE_KEY } from './choice.js';
+import { DEFAULT_THEME, SYSTEM_THEMES, THEME_CHOICES, THEME_NAMES } from './data.js';
+
+/**
+ * A script for a page's `<head>`: it sets `data-ca-theme` on `<html>` from the
+ * reader's choice before the first paint, as `resolveTheme(preferredTheme(), prefersLight())`
+ * does. With `themeRules` in a `<style>` beside it, the page opens in its theme.
+ */
+export const themeBootScript = `(function(){var c=null;try{c=localStorage.getItem(${JSON.stringify(THEME_STORE_KEY)})}catch(e){}
+var names=${JSON.stringify(THEME_NAMES)},choices=${JSON.stringify(THEME_CHOICES)};
+if(choices.indexOf(c)<0)c=${JSON.stringify(DEFAULT_THEME)};
+if(c==="system")c=window.matchMedia&&matchMedia("(prefers-color-scheme: light)").matches?${JSON.stringify(SYSTEM_THEMES.light)}:${JSON.stringify(SYSTEM_THEMES.dark)};
+if(names.indexOf(c)>=0)document.documentElement.setAttribute("data-ca-theme",c);})();`;

package/src/themes/choice.ts

@@ -0,0 +1,47 @@
+// The reader's choice of a theme: which theme it shows, and remembering it in
+// this browser.
+import { DEFAULT_THEME, SYSTEM_THEMES, THEME_CHOICES, THEME_NAMES, type ThemeChoice, type ThemeName } from './data.js';
+
+export const isThemeName = (x: unknown): x is ThemeName => (THEME_NAMES as readonly unknown[]).includes(x);
+export const isThemeChoice = (x: unknown): x is ThemeChoice => (THEME_CHOICES as readonly unknown[]).includes(x);
+
+/** The theme a choice shows: `system` by the system's colour scheme; anything else not a theme, the default. */
+export function resolveTheme(choice: unknown, prefersLight: boolean): ThemeName {
+  if (choice === 'system') return prefersLight ? SYSTEM_THEMES.light : SYSTEM_THEMES.dark;
+  return isThemeName(choice) ? choice : DEFAULT_THEME;
+}
+
+/** Where the reader's choice is kept (this browser only). */
+export const THEME_STORE_KEY = 'contraagent:theme';
+
+type Store = Pick<Storage, 'getItem' | 'setItem'>;
+const storage = (): Store | undefined => {
+  try {
+    return globalThis.localStorage;
+  } catch {
+    return undefined;
+  }
+};
+
+/** The reader's choice from an earlier visit, else the default theme. */
+export function preferredTheme(store: Store | undefined = storage()): ThemeChoice {
+  try {
+    const saved = store?.getItem(THEME_STORE_KEY);
+    if (isThemeChoice(saved)) return saved;
+  } catch {
+    /* storage blocked: the default */
+  }
+  return DEFAULT_THEME;
+}
+
+/** Remember the reader's choice for the next visit. */
+export function rememberTheme(choice: ThemeChoice, store: Store | undefined = storage()): void {
+  try {
+    store?.setItem(THEME_STORE_KEY, choice);
+  } catch {
+    /* storage blocked: the choice lasts for this page */
+  }
+}
+
+/** Whether the system asks for a light colour scheme. */
+export const prefersLight = (): boolean => globalThis.matchMedia?.('(prefers-color-scheme: light)').matches ?? false;