@contraagent/elements 0.0.0-stage → 0.1.0

package/src/charts/state-grid.ts

@@ -0,0 +1,245 @@
+import { css, html, nothing, svg, type TemplateResult } from 'lit';
+import { property } from 'lit/decorators.js';
+import type { Tone } from '../core/tone.js';
+import type { LegendItem } from '../primitives/legend.js';
+import { ChartElement } from './base.js';
+import { LABEL_GAP, labelStride } from './scale.js';
+
+/** One cell of a state grid: its state in words, the tone that colours it, and a fact of its own for the tooltip. */
+export interface StateCell {
+  label: string;
+  tone: Tone;
+  tip?: string | null;
+}
+
+const CELL_H = 22;
+const GAP = 2;
+const M = { top: 2, right: 2, bottom: 22 };
+/** The narrowest cell that still holds its mark. */
+const MARK_MIN = 14;
+
+/**
+ * A tone's fill: a failure and what needs attention stand out, a cell that ended well
+ * stays quiet, so the exceptions are what the eye finds first.
+ */
+export function stateFill(tone: Tone): string {
+  switch (tone) {
+    case 'failed':
+      return 'color-mix(in srgb, var(--status-failed) 72%, var(--card))';
+    case 'attention':
+      return 'color-mix(in srgb, var(--status-attention) 68%, var(--card))';
+    case 'running':
+      return 'color-mix(in srgb, var(--status-running) 60%, var(--card))';
+    case 'done':
+      return 'color-mix(in srgb, var(--status-done) 30%, var(--card))';
+    case 'muted':
+      return 'color-mix(in srgb, var(--text-muted) 26%, var(--card))';
+    default:
+      return 'color-mix(in srgb, var(--text) 12%, var(--card))';
+  }
+}
+
+/** The mark a tone takes in a cell, beside its colour: ✓ done, ✕ failed, ◌ attention; none for the others. */
+export function stateMark(tone: Tone): string {
+  return tone === 'done' ? '✓' : tone === 'failed' ? '✕' : tone === 'attention' ? '◌' : '';
+}
+
+/** The order of the tones in a legend: the exceptions first, what ended well after. */
+const TONE_ORDER: readonly Tone[] = ['failed', 'attention', 'running', 'done', 'muted', 'neutral'];
+
+/** The textures that tell the states of one tone apart, after the first (plain): stripes, dots, crosshatch, lines. */
+export const TEXTURES = ['', 'stripes', 'dots', 'cross', 'lines'] as const;
+export type Texture = (typeof TEXTURES)[number];
+
+/** Each state's texture, by `tone` and `label`: the first state of a tone plain, the next ones in `TEXTURES` order (again from the start past the fifth). */
+export function texturesOf(states: readonly StateCell[]): Map<string, Texture> {
+  const n = new Map<Tone, number>();
+  const out = new Map<string, Texture>();
+  for (const s of states) {
+    const i = n.get(s.tone) ?? 0;
+    n.set(s.tone, i + 1);
+    out.set(stateKey(s), TEXTURES[i % TEXTURES.length]!);
+  }
+  return out;
+}
+
+const stateKey = (c: StateCell): string => `${c.tone}\u0000${c.label}`;
+
+/** A texture as a CSS background over a legend key's fill. */
+function textureCss(t: Texture): string {
+  const ink = 'color-mix(in srgb, var(--text) 45%, transparent)';
+  switch (t) {
+    case 'stripes':
+      return `repeating-linear-gradient(45deg, ${ink} 0 1.5px, transparent 1.5px 4px)`;
+    case 'dots':
+      return `radial-gradient(${ink} 1px, transparent 1.3px) 0 0 / 4px 4px`;
+    case 'cross':
+      return `repeating-linear-gradient(45deg, ${ink} 0 1px, transparent 1px 4px), repeating-linear-gradient(-45deg, ${ink} 0 1px, transparent 1px 4px)`;
+    case 'lines':
+      return `repeating-linear-gradient(0deg, ${ink} 0 1.5px, transparent 1.5px 4px)`;
+    default:
+      return '';
+  }
+}
+
+/** Each state of the cells once: by tone (failed, attention, running, done, muted, neutral), then in the order the cells first give it. */
+export function statesOf(cells: readonly (readonly (StateCell | null | undefined)[])[]): StateCell[] {
+  const seen = new Map<string, StateCell>();
+  for (const row of cells) for (const c of row) if (c && !seen.has(stateKey(c))) seen.set(stateKey(c), c);
+  return [...seen.values()].sort((a, b) => TONE_ORDER.indexOf(a.tone) - TONE_ORDER.indexOf(b.tone));
+}
+
+/**
+ * A state per row (`y`) and column (`x`), each cell coloured by its tone
+ * (`cells[row][column]`; a null cell is left empty): the states of hourly runs by day,
+ * say. The colour is never alone: a cell wide enough holds its tone's mark (✓ ✕ ◌), the
+ * states of one tone differ by a texture (the first plain, then stripes, dots,
+ * crosshatch, lines), the legend names every state with its texture, and pointing at a cell, or moving to it with the arrow keys
+ * (up and down by a row), shows its row, column, state and fact; the switch shows them
+ * all as a table of words.
+ *
+ * @tagname cae-state-grid
+ * @csspart plot - the grid
+ * @csspart table - the table of its states
+ * @csspart switch - the button between the two
+ * @csspart empty - what it shows with no cells
+ * @csspart legend - the legend
+ */
+export class CaeStateGrid extends ChartElement {
+  static override styles = [
+    ...ChartElement.styles,
+    css`
+      .mark { font-size: 11px; font-weight: 700; fill: var(--text); pointer-events: none; }
+      /* a cell that ended well keeps its mark, quietly: the exceptions are what the eye finds */
+      .mark.quiet { font-weight: 400; fill: var(--text-muted); }
+      .legend .key { display: inline-grid; place-items: center; width: 14px; height: 14px; margin-right: 6px; border-radius: 3px;
+        font-size: 9.5px; font-weight: 700; color: var(--text); vertical-align: -2px; }
+    `,
+  ];
+
+  @property({ attribute: false }) x: readonly string[] = [];
+  @property({ attribute: false }) y: readonly string[] = [];
+  @property({ attribute: false }) cells: readonly (readonly (StateCell | null)[])[] = [];
+
+  protected hasValues(): boolean {
+    return this.x.length > 0 && this.y.length > 0 && this.cells.some((r) => r.some((c) => !!c));
+  }
+
+  protected legendItems(): LegendItem[] {
+    const states = statesOf(this.cells);
+    const textures = texturesOf(states);
+    return states.map((s) => {
+      const t = textureCss(textures.get(stateKey(s)) ?? '');
+      return {
+        label: s.label,
+        icon: html`<span class="key" aria-hidden="true" data-texture=${textures.get(stateKey(s)) || nothing}
+          style="background: ${t ? `${t}, ` : ''}${stateFill(s.tone)}">${stateMark(s.tone)}</span>`,
+      };
+    });
+  }
+
+  protected itemCount(): number {
+    return this.x.length * this.y.length;
+  }
+
+  protected override rowLength(): number {
+    return this.x.length;
+  }
+
+  protected plot(): TemplateResult {
+    const nx = this.x.length;
+    const ny = this.y.length;
+    const left = Math.max(...this.y.map((s) => this.labelWidth(s))) + 2;
+    const w = this.plotWidth;
+    const pw = w - left - M.right;
+    const cw = pw / nx;
+    const h = M.top + ny * CELL_H + M.bottom;
+    const stride = labelStride(nx, pw, Math.max(...this.x.map((s) => this.labelWidth(s))) + LABEL_GAP);
+    const a = this.active;
+    const marked = cw - GAP >= MARK_MIN;
+    const textures = texturesOf(statesOf(this.cells));
+    const cells: TemplateResult[] = [];
+    for (let r = 0; r < ny; r++)
+      for (let c = 0; c < nx; c++) {
+        const cell = this.cells[r]?.[c];
+        const x = left + c * cw;
+        const y = M.top + r * CELL_H;
+        const i = r * nx + c;
+        const box = { x: x + GAP / 2, y: y + GAP / 2, w: Math.max(1, cw - GAP), h: CELL_H - GAP };
+        if (!cell) {
+          cells.push(svg`<rect x=${box.x} y=${box.y} width=${box.w} height=${box.h} rx="2" fill="none" stroke="var(--line)"
+            @mouseenter=${() => (this.active = i)}></rect>`);
+          continue;
+        }
+        const mark = marked ? stateMark(cell.tone) : '';
+        const texture = textures.get(stateKey(cell)) ?? '';
+        cells.push(svg`<g @mouseenter=${() => (this.active = i)}>
+          <rect x=${box.x} y=${box.y} width=${box.w} height=${box.h} rx="2" fill=${stateFill(cell.tone)}
+            stroke=${a === i ? 'var(--text)' : 'none'} stroke-width="1.5"></rect>
+          ${texture ? svg`<rect class="texture" data-texture=${texture} x=${box.x} y=${box.y} width=${box.w} height=${box.h} rx="2" fill=${`url(#${this.patternId(texture)})`} pointer-events="none"></rect>` : nothing}
+          ${mark ? svg`<text class=${cell.tone === 'done' ? 'mark quiet' : 'mark'} x=${box.x + box.w / 2} y=${box.y + box.h / 2} dy="0.35em" text-anchor="middle" aria-hidden="true">${mark}</text>` : nothing}
+        </g>`);
+      }
+    const at = a !== null && a < nx * ny ? { r: Math.floor(a / nx), c: a % nx } : null;
+    return html`<svg width=${w} height=${h} role="img" aria-label=${this.label || nothing}>
+        ${this.patterns(new Set(textures.values()))}
+        ${this.y.map((label, r) => svg`<text class="axis" x=${left - 6} y=${M.top + r * CELL_H + CELL_H / 2} dy="0.32em" text-anchor="end">${label}</text>`)}
+        ${cells}
+        ${this.x.map((label, c) =>
+          c % stride === 0 ? svg`<text class="axis" x=${left + c * cw + cw / 2} y=${h - 6} text-anchor="middle">${label}</text>` : nothing,
+        )}
+      </svg>
+      ${at ? this.tip(left + at.c * cw + cw / 2, M.top + (at.r + 1) * CELL_H, this.tipBody(at.r, at.c)) : nothing}`;
+  }
+
+  /** One id per element and texture: two grids in a page keep their own patterns. */
+  private readonly uid = `sg${Math.random().toString(36).slice(2, 8)}`;
+
+  private patternId(t: Texture): string {
+    return `${this.uid}-${t}`;
+  }
+
+  /** The SVG patterns of the textures in use, drawn in the text's colour over a cell's fill. */
+  private patterns(used: ReadonlySet<Texture>): TemplateResult {
+    const line = (d: string) => svg`<path d=${d} stroke="var(--text)" stroke-opacity="0.45" stroke-width="1.2"></path>`;
+    const body = (t: Texture) =>
+      t === 'stripes'
+        ? line('M-1 1 L1 -1 M0 5 L5 0 M4 6 L6 4')
+        : t === 'dots'
+          ? svg`<circle cx="2.5" cy="2.5" r="0.9" fill="var(--text)" fill-opacity="0.5"></circle>`
+          : t === 'cross'
+            ? line('M0 0 L5 5 M5 0 L0 5')
+            : line('M0 2.5 L5 2.5');
+    return svg`<defs>${[...used].filter((t) => t).map(
+      (t) => svg`<pattern id=${this.patternId(t)} width="5" height="5" patternUnits="userSpaceOnUse">${body(t)}</pattern>`,
+    )}</defs>`;
+  }
+
+  private tipBody(r: number, c: number): TemplateResult {
+    const cell = this.cells[r]?.[c];
+    return html`<b>${this.y[r]} | ${this.x[c]}</b>
+      <div class="row">${cell
+        ? html`<i style="background: ${stateFill(cell.tone)}"></i><span>${cell.label}</span>`
+        : html`<span>${this.words.none}</span>`}</div>
+      ${cell?.tip ? html`<div class="row"><span>${cell.tip}</span></div>` : nothing}`;
+  }
+
+  protected table(): TemplateResult {
+    const none = this.words.none;
+    return html`<table aria-label=${this.label || nothing}>
+      <thead><tr><th scope="col">${this.words.label}</th>${this.x.map((l) => html`<th scope="col">${l}</th>`)}</tr></thead>
+      <tbody>${this.y.map(
+        (label, r) => html`<tr><th scope="row">${label}</th>${this.x.map((_, c) => {
+          const cell = this.cells[r]?.[c];
+          return html`<td title=${cell?.tip || nothing}>${cell ? cell.label : none}</td>`;
+        })}</tr>`,
+      )}</tbody>
+    </table>`;
+  }
+}
+
+declare global {
+  interface HTMLElementTagNameMap {
+    'cae-state-grid': CaeStateGrid;
+  }
+}

package/src/charts/types.ts

@@ -0,0 +1,48 @@
+// What the charts take: plain series of numbers, and their words.
+import type { Tone } from '../core/tone.js';
+
+/** One series: a value per label of the chart's `x`, in that order; null where it has none. */
+export interface ChartSeries {
+  name: string;
+  values: readonly (number | null)[];
+}
+
+/** One horizontal bar: its label and value; `tone` gives it a status colour. */
+export interface ChartBar {
+  label: string;
+  value: number;
+  tone?: Tone;
+}
+
+/** A number in words (`$1.20`, `42%`, `2m 05s`): the host's format for the chart's unit. */
+export type ValueText = (value: number) => string;
+
+/** The words of a chart. */
+export interface ChartStrings {
+  /** What a chart with nothing to draw says. */
+  empty: string;
+  /** The button that shows the values as a table, and the one that shows the chart again. */
+  showTable: string;
+  showChart: string;
+  /** The column of a table view that holds the labels of `x` (or of the bars). */
+  label: string;
+  /** The name of the series past the sixth, folded into one. */
+  other: string;
+  /** The sum of a label's stacked series. */
+  total: string;
+  /** A value a series has not (null). */
+  none: string;
+  /** The heatmap's colour scale: its lowest and highest value. */
+  scale: (low: string, high: string) => string;
+}
+
+export const DEFAULT_CHART_STRINGS: ChartStrings = {
+  empty: 'No values',
+  showTable: 'Show table',
+  showChart: 'Show chart',
+  label: 'Label',
+  other: 'Other',
+  total: 'Total',
+  none: '—',
+  scale: (low, high) => `${low} to ${high}`,
+};

package/src/checks/check-table.ts

@@ -0,0 +1,85 @@
+import { LitElement, html, nothing, type TemplateResult } from 'lit';
+import { property } from 'lit/decorators.js';
+import { withDefaults } from '../core/strings.js';
+import { base } from '../styles/index.js';
+import { checkTableStyles, verdictStyles } from './styles.js';
+import { DEFAULT_CHECK_TABLE_STRINGS, type CheckRow, type CheckTableStrings, type Verdict } from './types.js';
+
+/**
+ * A verdict in words (`.verdict`, `data-verdict`; `verdictStyles`): ✓ before a
+ * pass, ✕ before a failure, hidden from screen readers, which read the word.
+ * Nothing for `none` without a word.
+ */
+export function verdict(v: Verdict, label: string, tip = ''): TemplateResult | typeof nothing {
+  if (v === 'none' && !label) return nothing;
+  const mark = v === 'pass' ? '✓' : v === 'fail' ? '✕' : '';
+  return html`<span class="verdict" part="verdict" data-verdict=${v} title=${tip || nothing}>${mark
+    ? html`<span aria-hidden="true">${mark}</span> `
+    : nothing}${label}</span>`;
+}
+
+const cut = (s: string, n: number) => (s.length > n ? `${s.slice(0, n)}…` : s);
+
+/** A value in a line: a string quoted and cut, a list's length and first items, an object's first keys. */
+function shortValue(v: unknown, s: CheckTableStrings): TemplateResult {
+  if (v === undefined) return html`<span class="jdim">—</span>`;
+  if (typeof v === 'string') return html`<span class="js" title=${v}>"${cut(v, 90)}"</span>`;
+  if (Array.isArray(v)) {
+    const head = v
+      .slice(0, 3)
+      .map((x) => (typeof x === 'string' ? `"${cut(x, 28)}"` : JSON.stringify(x)))
+      .join(', ');
+    return html`<span class="jn">${s.items(v.length)}</span>
+      <span class="jdim">${head}${v.length > 3 ? ', …' : ''}</span>`;
+  }
+  if (v !== null && typeof v === 'object') return html`<span class="jn">${s.object}</span> <span class="jdim">${Object.keys(v).slice(0, 4).join(', ')}</span>`;
+  return html`<span class="jn">${JSON.stringify(v)}</span>`;
+}
+
+/**
+ * Named values checked one by one: a row per name, with what it must be, what
+ * it is and the verdict. Without `showValues`, only the names and what each
+ * must be (nothing to check them against).
+ *
+ * @tagname cae-check-table
+ * @csspart table - the `<table>`
+ * @csspart row - each row of a name
+ * @csspart verdict - each verdict
+ */
+export class CaeCheckTable extends LitElement {
+  static override styles = [base, verdictStyles, checkTableStyles];
+
+  @property({ attribute: false }) rows: readonly CheckRow[] = [];
+  /** Show the values and the verdicts. */
+  @property({ type: Boolean }) showValues = true;
+  @property({ attribute: false }) strings: Partial<CheckTableStrings> = {};
+
+  override render() {
+    const s = withDefaults(DEFAULT_CHECK_TABLE_STRINGS, this.strings);
+    const all = this.showValues;
+    return html`<table part="table">
+      <thead><tr>
+        <th scope="col">${s.name}</th><th scope="col">${s.expected}</th>
+        ${all ? html`<th scope="col">${s.actual}</th><th scope="col">${s.verdict}</th>` : nothing}
+      </tr></thead>
+      <tbody>
+        ${this.rows.map(
+          (r) => html`<tr part="row">
+            <td class="jmono">${r.name}</td>
+            <td class=${r.extra ? 'jdim' : 'jmono jdim'}>${r.expected}${r.optional ? html` <i>${s.optional}</i>` : nothing}</td>
+            ${all
+              ? html`<td class="value">${shortValue(r.hasValue ? r.value : undefined, s)}</td>
+                  <td>${verdict(r.verdict, r.verdictLabel, r.tip)}</td>`
+              : nothing}
+          </tr>`,
+        )}
+      </tbody>
+    </table>`;
+  }
+}
+
+declare global {
+  interface HTMLElementTagNameMap {
+    'cae-check-table': CaeCheckTable;
+  }
+}

package/src/checks/index.ts

@@ -0,0 +1,5 @@
+// Values checked one by one: `@contraagent/elements/check-table`.
+// `CaeCheckTable` is registered by `@contraagent/elements/check-table/define`.
+export * from './types.js';
+export * from './styles.js';
+export * from './check-table.js';

package/src/checks/styles.ts

@@ -0,0 +1,31 @@
+// The look of `<cae-check-table>`, and of a verdict (`verdict()`) wherever a
+// host shows one.
+import { css } from 'lit';
+
+/** A verdict: ✓ and its word quiet, ✕ and its word in the failed tone, a warning in the attention tone. */
+export const verdictStyles = css`
+  .verdict { font-size: 12px; }
+  .verdict[data-verdict='pass'] { color: var(--text-2); }
+  .verdict[data-verdict='pass'] > [aria-hidden] { color: var(--status-done); font-weight: 700; }
+  .verdict[data-verdict='fail'] { color: var(--status-failed); font-weight: 600; }
+  .verdict[data-verdict='warn'] { color: var(--status-attention); }
+  .verdict[data-verdict='none'] { color: var(--text-muted); }
+`;
+
+/** Sized to its content, so a verdict sits next to the value it judges; a long value wraps. */
+export const checkTableStyles = css`
+  :host { display: block; max-width: 100%; }
+  table { width: auto; max-width: 100%; border-collapse: collapse; }
+  th { text-align: left; font-size: 11.5px; color: var(--text-muted);
+    font-weight: 600; padding: 4px 20px 4px 0; border-bottom: 1px solid var(--line); }
+  td { padding: 5px 20px 5px 0; border: 0; border-bottom: 1px solid var(--line); vertical-align: baseline; font-size: 12.5px; }
+  th:last-child, td:last-child { padding-right: 0; }
+  td.value { overflow-wrap: anywhere; }
+  tbody tr:last-child td { border-bottom: 0; }
+  /* a name stays on one line while the table has the room, and breaks where it must */
+  td:first-child { font-weight: 600; overflow-wrap: anywhere; }
+  td:last-child { white-space: nowrap; }
+  i { font-style: normal; color: var(--text-muted); font-size: 11px; margin-left: 4px; }
+  .js { color: var(--code-string); }
+  .jn { color: var(--code-number); }
+`;

package/src/checks/types.ts

@@ -0,0 +1,48 @@
+// What `<cae-check-table>` shows: a row per named value, what it must be, what
+// it is, and the verdict.
+
+/** A check's result: passed, failed, a warning, or no verdict (a word may still say why). */
+export type Verdict = 'pass' | 'fail' | 'warn' | 'none';
+
+export interface CheckRow {
+  /** What is checked: a field's name. */
+  name: string;
+  /** What it must be: a type, in code; with `extra`, a phrase. */
+  expected: string;
+  /** It may be absent: "optional" follows `expected`. */
+  optional?: boolean;
+  /** Not one of the expected names: `expected` is a phrase, not code. */
+  extra?: boolean;
+  /** The value was found (`value`, possibly undefined or null); else "—". */
+  hasValue: boolean;
+  value?: unknown;
+  verdict: Verdict;
+  /** The verdict in words; '' with `none` for an empty cell. */
+  verdictLabel: string;
+  /** The verdict's tooltip. */
+  tip?: string;
+}
+
+export interface CheckTableStrings {
+  /** The header of the names. */
+  name: string;
+  expected: string;
+  /** The header of the values. */
+  actual: string;
+  verdict: string;
+  optional: string;
+  /** A list's length. */
+  items: (n: number) => string;
+  /** An object's summary, before its first keys. */
+  object: string;
+}
+
+export const DEFAULT_CHECK_TABLE_STRINGS: CheckTableStrings = {
+  name: 'Name',
+  expected: 'Expected',
+  actual: 'Value',
+  verdict: 'Check',
+  optional: 'optional',
+  items: (n) => (n === 1 ? '1 item' : `${n} items`),
+  object: 'object',
+};

package/src/core/clock.ts

@@ -0,0 +1,46 @@
+// One shared once-a-second tick for every element that shows a running clock.
+import type { ReactiveController, ReactiveControllerHost } from 'lit';
+
+const hosts = new Set<ReactiveControllerHost>();
+let timer: ReturnType<typeof setInterval> | null = null;
+
+function tick(): void {
+  for (const h of hosts) h.requestUpdate();
+}
+
+/** Re-renders its host every second while it is connected. */
+export class ClockController implements ReactiveController {
+  constructor(private readonly host: ReactiveControllerHost) {
+    host.addController(this);
+  }
+  hostConnected(): void {
+    hosts.add(this.host);
+    timer ??= setInterval(tick, 1000);
+  }
+  hostDisconnected(): void {
+    hosts.delete(this.host);
+    if (!hosts.size && timer) {
+      clearInterval(timer);
+      timer = null;
+    }
+  }
+}
+
+/**
+ * Start times that stay put. A process reports its age in whole seconds, so
+ * `now - age` jitters by a second between updates; the first value seen for an
+ * id is kept while later ones stay within a few seconds of it.
+ */
+export class StableStarts {
+  private readonly seen = new Map<string, number>();
+  at(id: string, ageS: number, now = Date.now()): number {
+    const t0 = Math.round(now - ageS * 1000);
+    const prev = this.seen.get(id);
+    if (prev !== undefined && Math.abs(prev - t0) < 5000) return prev;
+    this.seen.set(id, t0);
+    return t0;
+  }
+}
+
+/** Shared by every view, so the same process shows the same start everywhere. */
+export const starts = new StableStarts();

package/src/core/define.ts

@@ -0,0 +1,7 @@
+// Registration. The element classes are plain classes: a `define/` module (or
+// the host, under a tag name of its own) registers them.
+
+/** Registers `cls` as `tag`, unless the tag is already registered. */
+export function defineElement(tag: string, cls: CustomElementConstructor): void {
+  if (!customElements.get(tag)) customElements.define(tag, cls);
+}

package/src/core/events.ts

@@ -0,0 +1,89 @@
+// The events the generic elements send. Each bubbles and crosses shadow roots
+// (`composed`), so a host listens on any ancestor. An element states what the
+// reader did; its host decides what happens.
+
+/** A control's value changed (a segmented control). */
+export interface ChangeDetail {
+  value: string;
+}
+
+/** An item, by its id (a row's key). */
+export interface ItemDetail {
+  id: string;
+}
+
+/** An item opened (`open`) or closed. */
+export interface ToggleDetail {
+  id: string;
+  open: boolean;
+}
+
+/** The item chosen as the selection; null when the selection was cleared. */
+export interface SelectDetail {
+  id: string | null;
+}
+
+/** A column to order the items by, and the direction. */
+export interface SortDetail {
+  id: string;
+  direction: 'asc' | 'desc';
+}
+
+/** A view of the same data: a drawing, or a table. */
+export interface ViewDetail {
+  view: 'graph' | 'table';
+}
+
+/** A named action of an item (a tile's link): the item's id and the action's id. */
+export interface ActionDetail {
+  id: string;
+  action: string;
+}
+
+/** A section of a list of sections (a transcript's), by its 0-based index; null: the latest. */
+export interface SectionDetail {
+  index: number | null;
+}
+
+/** Every `cae-*` event and its detail. */
+export interface CaeEventMap {
+  'cae-change': ChangeDetail;
+  /** The item's primary action (a click or Enter on an item that has one). */
+  'cae-activate': ItemDetail;
+  'cae-select': SelectDetail;
+  'cae-sort': SortDetail;
+  'cae-action': ActionDetail;
+  /** Enter an item's inner view (a cluster, a node or a mark that has one). */
+  'cae-drill': ItemDetail;
+  /** The reader opened or closed an item (`open`: it is to be drawn open). */
+  'cae-toggle': ToggleDetail;
+  /** The reader chose another view. */
+  'cae-view-change': ViewDetail;
+  /** The reader picked a section (null: follow the latest). */
+  'cae-section-change': SectionDetail;
+  /** The section on screen changed (-1: none). */
+  'cae-section-shown': { index: number };
+  /** The reader asked for the content before what is loaded. */
+  'cae-load-earlier': Record<string, never>;
+}
+
+declare global {
+  interface HTMLElementEventMap {
+    'cae-change': CustomEvent<ChangeDetail>;
+    'cae-activate': CustomEvent<ItemDetail>;
+    'cae-select': CustomEvent<SelectDetail>;
+    'cae-sort': CustomEvent<SortDetail>;
+    'cae-action': CustomEvent<ActionDetail>;
+    'cae-drill': CustomEvent<ItemDetail>;
+    'cae-toggle': CustomEvent<ToggleDetail>;
+    'cae-view-change': CustomEvent<ViewDetail>;
+    'cae-section-change': CustomEvent<SectionDetail>;
+    'cae-section-shown': CustomEvent<{ index: number }>;
+    'cae-load-earlier': CustomEvent<Record<string, never>>;
+  }
+}
+
+/** Sends a `cae-*` event from `el`: bubbling and composed. */
+export function emit<K extends keyof CaeEventMap>(el: EventTarget, name: K, detail: CaeEventMap[K]): boolean {
+  return el.dispatchEvent(new CustomEvent(name, { detail, bubbles: true, composed: true }));
+}

package/src/core/format.ts

@@ -0,0 +1,25 @@
+// Formats that read the same in every language: a duration, and HTML escaping
+// for the few places that build markup as a string.
+
+/**
+ * A duration in seconds, in one format: `<0.1s`, `4.2s`, `37s`, `2m 05s`,
+ * `1h 02m`; '—' when unknown.
+ */
+export function fmtDur(s: number | null | undefined): string {
+  if (s === null || s === undefined || Number.isNaN(s)) return '—';
+  const v = Math.max(0, s);
+  if (v < 0.05) return '<0.1s';
+  if (v < 9.95) return `${v.toFixed(1)}s`;
+  const r = Math.round(v);
+  if (r < 60) return `${r}s`;
+  if (r < 3600) return `${Math.floor(r / 60)}m ${String(r % 60).padStart(2, '0')}s`;
+  return `${Math.floor(r / 3600)}h ${String(Math.floor((r % 3600) / 60)).padStart(2, '0')}m`;
+}
+
+/** HTML-escape a text for the few places that build markup as a string (markdown, highlighting). */
+export const esc = (s: string | number | null | undefined): string =>
+  String(s ?? '')
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;');

package/src/core/frame.ts

@@ -0,0 +1,5 @@
+// The frame a drawing is shown in: how tall it may grow.
+
+/** A frame is at most this share of the window's height, and at least `FRAME_MIN` px. */
+export const FRAME_SHARE = 0.7;
+export const FRAME_MIN = 360;

package/src/core/strings.ts

@@ -0,0 +1,11 @@
+// An element's visible words. Each element takes `strings: Partial<XStrings>`
+// and falls back to its English defaults (`DEFAULT_X_STRINGS`) for a word it is
+// not given; a word with a number is a function, so plural rules and word order
+// belong to the host.
+
+/** `given` over `defaults`: a word left out (or undefined) keeps its default. */
+export function withDefaults<T extends object>(defaults: Readonly<T>, given: Partial<T> | null | undefined): T {
+  const out = { ...defaults };
+  if (given) for (const [k, v] of Object.entries(given)) if (v !== undefined) (out as Record<string, unknown>)[k] = v;
+  return out;
+}

package/src/core/tone.ts

@@ -0,0 +1,14 @@
+// A tone: the status colour a value takes. The names are the token names
+// (`--ca-status-<tone>`); `neutral` is the text colour, with no `data-tone`.
+// An element shows a tone as `data-tone` (styles/status.ts draws it).
+import { nothing } from 'lit';
+
+/** A status colour, or `neutral` for the text colour. */
+export type Tone = 'failed' | 'attention' | 'done' | 'running' | 'muted' | 'neutral';
+
+/** Every tone with a status colour (a `data-tone` value): each but `neutral`. */
+export const TONES: readonly Exclude<Tone, 'neutral'>[] = ['failed', 'attention', 'done', 'running', 'muted'];
+
+/** The `data-tone` attribute of a tone: none for `neutral` (or no tone). */
+export const toneAttr = (tone: Tone | null | undefined): Exclude<Tone, 'neutral'> | typeof nothing =>
+  tone && tone !== 'neutral' ? tone : nothing;