@contraagent/elements 0.0.0-stage → 0.1.0

package/docs/charts.md

@@ -0,0 +1,58 @@
+# Charts
+
+Five charts of plain series: `<cae-column-chart>` (vertical bars, stacked or
+side by side), `<cae-line-chart>`, `<cae-heatmap>`, `<cae-state-grid>` (a state
+per row and column) and `<cae-bar-chart>` (horizontal bars). Register them with
+`@contraagent/elements/charts/define`; the types and the arithmetic they share
+are in `@contraagent/elements/charts`.
+
+![Five charts of a CI pipeline: minutes by day as stacked columns, queue time as two lines, builds by weekday and hour as a heatmap, nightly builds as a state grid, and a test funnel as horizontal bars](images/charts.webp)
+
+::code{file="examples/charts.ts"}
+
+## Series and values
+
+A chart takes labels (`x`) and series, each a name and a value per label; a
+null value is a value the series has not: no bar, a break in a line, an empty
+cell. A heatmap takes its rows (`y`), its columns (`x`) and `values[row][column]`;
+a state grid the same rows and columns and `cells[row][column]`, each a state's
+`label`, its `tone` and an optional `tip` (null: no cell); a bar chart takes
+`bars`, each a label, a value and an optional `tone`.
+
+::code{file="../src/charts/types.ts" from="/** One series" to="/** The words of a chart"}
+
+`format` writes a value in words (`$1.20`, `42%`, `2m 05s`): on the axis, in the
+tooltip and in the table. It is the host's, since the chart does not know the
+unit.
+
+## Colour
+
+The series take the series colours (`--ca-series-1` to `--ca-series-6`) in
+their order, so a series keeps its colour whatever its values and its rank. A
+chart never makes up a seventh colour: past six series, a column chart sums the
+sixth and later into one series, `strings.other`, in the neutral `--ca-meter`;
+a line chart draws them in that colour and names each in the legend and the
+tooltip. A heatmap uses one hue, light to dark in five steps between its lowest
+and highest value. A state grid colours a cell by its tone, so a failure and
+what needs attention stand out and a cell that ended well stays quiet; the
+colour is never alone: a cell wide enough holds its tone's mark (✓ done,
+✕ failed, ◌ attention; a done cell's mark is quieter), the legend names each
+state once, failures and what needs attention first, and the tooltip and the
+table say the state in words. A bar
+with a `tone` takes that status colour; a status colour is never a series.
+
+## Reading it
+
+Two or more series have a legend; one series has none, since the chart's title
+names it. Pointing at a label, or moving to it with the arrow keys once the
+chart has the focus (up and down by a row in a heatmap and a state grid, Home and End to the
+ends, Escape to close), shows its values in a tooltip. Every chart has a switch
+to a table of the same values (`strings.showTable`, `strings.showChart`), which
+is also how a screen reader reads it. A bar chart writes each value beside its
+bar.
+
+## Look
+
+`height` sets a column or line chart's height in px (200 by default; the rows of
+a heatmap and of a state grid are 22px each). The parts are `plot`, `table`, `switch`, `legend` and
+`empty`.

package/docs/check-table.md

@@ -0,0 +1,40 @@
+# Check table
+
+`<cae-check-table>` shows named values checked one by one: a row per name,
+with what it must be, what it is and the verdict. Register it with
+`@contraagent/elements/check-table/define`; the types, `verdict` and
+`verdictStyles` are in `@contraagent/elements/check-table`.
+
+![A check table of five fields: what each must be, what the file holds, and the verdict (passed, wrong type, absent, extra field)](images/check-table.webp)
+
+<!-- not on the site -->
+Live on this topic's page of the documentation site (`pnpm run docs` in `web/`).
+
+::code{file="examples/check-table.ts"}
+
+## Rows
+
+A row is a `CheckRow`. The host judges each value; the table shows the
+verdict: `pass` (✓ and its word), `fail` (✕ and its word, in the failed
+tone), `warn` (its word, in the attention tone) or `none` (its word, muted, or
+an empty cell without one). The marks are hidden from screen readers, which
+read the word.
+
+::code{file="../src/checks/types.ts" from="export interface CheckRow" to="export interface CheckTableStrings"}
+
+A value is shown in one line: a string quoted and cut, a list's length and its
+first items, an object's first keys. A row with `extra` names a value that is
+not expected: its `expected` is a phrase, not code. Without `showValues`, the
+table shows only the names and what each must be.
+
+## Verdicts elsewhere
+
+`verdict(v, label, tip)` draws a verdict as the table does, for a host that
+shows one outside a table; add `verdictStyles` to the host's styles.
+
+## Look
+
+The table is as wide as its content, so each verdict sits next to the value it
+judges; a long value wraps. The parts are `table`, `row` and `verdict`. The
+words are `strings` ([Strings](strings.md)): the headers, `optional`, and the
+summaries of a list (`items`) and an object.

package/docs/data-table.md

@@ -0,0 +1,57 @@
+# Data table
+
+`<cae-data-table>` shows rows of data in a real `<table>`: a header cell per
+column, and the first `rowHeader` column as the header of its row, so a screen
+reader names each cell by its column and its row. Register it with
+`@contraagent/elements/data-table/define`; the types and `sortRows` are in
+`@contraagent/elements/data-table`.
+
+![A data table of three jobs with their minutes and their state: done, failed, running](images/data-table.webp)
+
+<!-- not on the site -->
+Live on this topic's page of the documentation site (`pnpm run docs` in `web/`).
+
+::code{file="examples/data-table.ts"}
+
+## Columns
+
+A column is a `DataColumn`: its header, a CSS grid track as its width, and a
+function that draws its cell for a row (a template, a string or a number).
+Every row is a grid of the columns' tracks, so the rows line up with the header.
+
+::code{file="../src/table/types.ts" from="/** A column:" to="/** The column the rows are ordered by. */"}
+
+## Keyboard and events
+
+The rows are one tab stop. The arrow keys move between rows, and Home and End
+move to the first and the last row. Enter or a click on a row sends
+`cae-activate` with the row's id (`rowKey`). With `activatable` off, they choose
+the row as the selection and send `cae-select`; the selected row has the part
+`row-selected`. A click on a button or a link inside a cell is that control's.
+
+A column with `compare` (or `sortable`) has a header button that sends
+`cae-sort` with the column and the direction. The table does not reorder the
+rows: the host sets `sort` and the rows, ordered by `sortRows` or its own way.
+`sortRows` orders by the column's `compare`, else its `text`, else its cell when
+the cell is a string or a number: a column of plain values needs only `sortable`.
+
+## Long lists
+
+Above `windowAt` rows (200), the table draws only the rows on screen and a
+spacer for the rows above and below them, so the scroll height stays that of
+the whole list. The rows' height is measured; `rowHeight` is the first
+estimate. The table finds the element that scrolls it, across shadow roots, or
+the window.
+
+## Look
+
+`--cae-data-table-gap` sets the space between the columns and
+`--cae-data-table-row-padding` a row's padding. The parts are `table`,
+`caption`, `head`, `header-cell`, `row`, `row-selected`, `cell` and `empty`;
+`rowTone` gives a row a tone (`data-tone`) and `rowAttrs` more attributes. What
+the cells draw lives in the table's shadow root: `cellStyles` adds styles there,
+after the table's own (the rows are `tr`, the cells `th` and `td`, each with
+`data-col` set to its column's id).
+
+The words are `strings` ([Strings](strings.md)): `empty` with no rows (or the
+`empty` slot), and the sort buttons' tooltips.

package/docs/examples/charts.ts

@@ -0,0 +1,61 @@
+// Charts: a CI pipeline's minutes by day and stage (stacked columns), its queue
+// time (lines), its builds by weekday and hour (a heatmap), how its nightly builds
+// ended (a state grid) and its test funnel (horizontal bars). The host gives each
+// chart its unit's format.
+import '@contraagent/elements/charts/define';
+import type { ChartSeries } from '@contraagent/elements/charts';
+
+const days = ['10-08', '10-09', '10-10', '10-11', '10-12', '10-13', '10-14'];
+const minutes: ChartSeries[] = [
+  { name: 'build', values: [42, 38, 51, 12, 9, 47, 44] },
+  { name: 'test', values: [65, 70, 58, 20, null, 61, 66] },
+  { name: 'deploy', values: [8, 8, 9, 2, 2, 10, 8] },
+];
+
+export function mount(host: HTMLElement): void {
+  const columns = document.createElement('cae-column-chart');
+  columns.label = 'Minutes by day';
+  columns.x = days;
+  columns.series = minutes;
+  columns.stacked = true;
+  columns.format = (v) => `${v} min`;
+
+  const lines = document.createElement('cae-line-chart');
+  lines.label = 'Queue time';
+  lines.x = days;
+  lines.series = [
+    { name: 'median', values: [1.2, 1.4, 0.9, 0.3, 0.2, 1.8, 1.1] },
+    { name: 'slowest', values: [6, 9, 4, 1, 1, 12, 7] },
+  ];
+  lines.format = (v) => `${v} min`;
+
+  const heat = document.createElement('cae-heatmap');
+  heat.label = 'Builds by weekday and hour';
+  heat.x = ['9', '10', '11', '12', '13', '14', '15', '16', '17'];
+  heat.y = ['Mon', 'Tue', 'Wed', 'Thu', 'Fri'];
+  // A count per weekday and hour; Wednesday at 13 has no record (null: an empty cell).
+  heat.values = heat.y.map((_, r) => heat.x.map((_, c) => (r === 2 && c === 4 ? null : (r * 7 + c * 3) % 9)));
+  heat.strings = { scale: (low, high) => `${low} to ${high} builds` };
+
+  const bars = document.createElement('cae-bar-chart');
+  bars.label = 'Tests this week';
+  bars.bars = [
+    { label: 'written', value: 1240 },
+    { label: 'run', value: 1180 },
+    { label: 'passed', value: 1162 },
+    { label: 'flaky', value: 18, tone: 'attention' },
+  ];
+
+  const nightly = document.createElement('cae-state-grid');
+  nightly.label = 'Nightly builds by weekday and hour';
+  nightly.x = ['0', '1', '2', '3'];
+  nightly.y = ['Mon', 'Tue'];
+  const passed = { label: 'passed', tone: 'done' as const };
+  // A state per weekday and hour: its word, its tone, and a fact for the tooltip; null: no build.
+  nightly.cells = [
+    [passed, { label: 'failed', tone: 'failed', tip: 'build 4127' }, passed, null],
+    [passed, passed, { label: 'skipped', tone: 'muted' }, passed],
+  ];
+
+  host.replaceChildren(columns, lines, heat, nightly, bars);
+}

package/docs/examples/check-table.ts

@@ -0,0 +1,19 @@
+// A check table: hand-written fields of a settings file, each checked against
+// what it must be. The host judges the values; the table shows the verdicts.
+import '@contraagent/elements/check-table/define';
+import type { CheckRow } from '@contraagent/elements/check-table';
+
+const rows: CheckRow[] = [
+  { name: 'name', expected: 'string', hasValue: true, value: 'release-build', verdict: 'pass', verdictLabel: 'passed' },
+  { name: 'retries', expected: 'integer', hasValue: true, value: '3', verdict: 'fail', verdictLabel: 'wrong type', tip: 'Expected integer' },
+  { name: 'targets', expected: 'list[str]', hasValue: true, value: ['linux', 'macos', 'windows', 'wasm'], verdict: 'pass', verdictLabel: 'passed' },
+  { name: 'cache', expected: 'object', optional: true, hasValue: false, verdict: 'none', verdictLabel: 'absent (optional)' },
+  { name: 'colour', expected: 'not in the schema', extra: true, hasValue: true, value: 'blue', verdict: 'warn', verdictLabel: 'extra field' },
+];
+
+export function mount(host: HTMLElement): void {
+  const table = document.createElement('cae-check-table');
+  table.rows = rows;
+  table.strings = { name: 'Field', actual: 'In the file' };
+  host.replaceChildren(table);
+}

package/docs/examples/ci-pipeline.ts

@@ -0,0 +1,271 @@
+// A whole page from the generic elements: one run of a made-up CI pipeline.
+// A theme switch, stat tiles, a sortable table of jobs, and a layered graph of
+// the steps (a shard is a series; the end-to-end tests repeat in a retry loop),
+// with a detail panel of the page's own beside them. The page holds the data
+// and the state (the theme, the selection, the order), and answers the events.
+import '@contraagent/elements/segmented/define'; // <cae-segmented>
+import '@contraagent/elements/tiles/define'; // <cae-stat-tiles>
+import '@contraagent/elements/data-table/define'; // <cae-data-table>
+import '@contraagent/elements/graph/define'; // <cae-layered-graph>
+import { adoptThemes } from '@contraagent/elements/themes';
+import { fmtDur, pill, type StateStyles } from '@contraagent/elements';
+import { sortRows, type CaeDataTable, type DataColumn } from '@contraagent/elements/data-table';
+import type { GraphInput, GraphMark, GraphNodeInput } from '@contraagent/elements/graph';
+import type { StatTile } from '@contraagent/elements/tiles';
+
+// ---- The data: a step is a node, a job is one run of a step (or of one shard of it).
+
+type State = 'done' | 'failed' | 'running' | 'queued';
+
+interface Job {
+  id: string;
+  step: string;
+  /** The shard ('1' to '3'), or null for a step that runs once. */
+  shard: string | null;
+  /** The pass of the retry loop it ran in (1 outside the loop). */
+  pass: number;
+  state: State;
+  seconds: number;
+  runner: string;
+}
+
+const steps = [
+  { id: 'lint', label: 'lint', loop: false },
+  { id: 'unit', label: 'unit tests', loop: false },
+  { id: 'build', label: 'build', loop: false },
+  { id: 'e2e', label: 'e2e tests', loop: true },
+  { id: 'triage', label: 'triage failures', loop: true },
+  { id: 'deploy', label: 'deploy preview', loop: false },
+];
+const shards = ['1', '2', '3'];
+
+const job = (step: string, shard: string | null, pass: number, state: State, seconds: number, runner: string): Job => ({
+  id: `${step}${shard ? `/${shard}` : ''}#${pass}`,
+  step,
+  shard,
+  pass,
+  state,
+  seconds,
+  runner,
+});
+
+const jobs: Job[] = [
+  job('lint', null, 1, 'done', 41, 'small-1'),
+  job('unit', '1', 1, 'done', 188, 'large-1'),
+  job('unit', '2', 1, 'done', 203, 'large-2'),
+  job('unit', '3', 1, 'done', 176, 'large-3'),
+  job('build', null, 1, 'done', 315, 'large-1'),
+  job('e2e', '1', 1, 'done', 402, 'large-2'),
+  job('e2e', '2', 1, 'failed', 377, 'large-3'),
+  job('e2e', '3', 1, 'done', 395, 'large-1'),
+  job('triage', null, 1, 'done', 12, 'small-1'),
+  job('e2e', '2', 2, 'done', 381, 'large-2'),
+  job('triage', null, 2, 'done', 9, 'small-1'),
+  job('deploy', null, 1, 'running', 74, 'deploy-1'),
+];
+
+// ---- What each state looks like: a word, a tone, a shape (the legend follows this order).
+
+const states: StateStyles = {
+  done: { label: 'done', tone: 'done', shape: 'round', rank: 0 },
+  queued: { label: 'queued', tone: 'muted', shape: 'ring', rank: 1 },
+  running: { label: 'running', tone: 'running', shape: 'round', rank: 2 },
+  failed: { label: 'failed', tone: 'failed', shape: 'square', rank: 3 },
+};
+const toneOf = (s: State) => states[s]!.tone;
+const jobName = (j: Job) => `${steps.find((s) => s.id === j.step)!.label}${j.shard ? ` shard ${j.shard}` : ''}`;
+
+// ---- The graph: a mark per shard (or one loose mark), the last pass's state, the passes as a badge.
+
+/** The id of a mark: a step's shard, or the step's single job. */
+const markId = (j: Job) => `${j.step}/${j.shard ?? '-'}`;
+
+function mark(runs: Job[]): GraphMark {
+  const last = runs[runs.length - 1]!;
+  const passes = runs.length > 1 ? `${runs.length} passes` : '1 pass';
+  return { id: markId(last), state: last.state, label: `${jobName(last)} | ${last.state} | ${passes}`, tip: jobName(last), badge: runs.length > 1 ? String(runs.length) : undefined };
+}
+
+function node(step: (typeof steps)[number]): GraphNodeInput {
+  const own = jobs.filter((j) => j.step === step.id);
+  const runsOf = (shard: string | null) => own.filter((j) => j.shard === shard);
+  const sharded = own.some((j) => j.shard);
+  const marks = sharded ? shards.map((s) => (runsOf(s).length ? mark(runsOf(s)) : null)) : [];
+  const loose = sharded ? [] : [mark(runsOf(null))];
+  // `counts` and `progress` ("2/3") default to what the marks say.
+  // A job that failed in an earlier pass is not in the marks: the line under them names it.
+  const failed = own.filter((j) => j.state === 'failed').length;
+  return {
+    id: step.id,
+    label: step.label,
+    cluster: step.loop ? 'retry' : null,
+    marks,
+    loose,
+    notes: failed ? [{ text: `${failed} failed ${failed === 1 ? 'job' : 'jobs'}`, tone: 'failed' }] : [],
+  };
+}
+
+const graph: GraphInput = {
+  series: shards,
+  nodes: steps.map(node),
+  clusters: [{ id: 'retry', parent: null, label: 'retry loop', note: 'up to 3 passes', cycle: true }],
+  edges: [
+    { from: 'lint', to: 'build', style: 'solid', weight: 1, ranks: true },
+    { from: 'unit', to: 'build', style: 'solid', weight: 3, ranks: true },
+    { from: 'build', to: 'e2e', style: 'solid', weight: 3, ranks: true },
+    { from: 'e2e', to: 'triage', style: 'solid', weight: 3, ranks: true },
+    // The next pass: from triage back to the tests. It does not set the layers.
+    { from: 'triage', to: 'e2e', style: 'solid', weight: 1, ranks: false },
+    { from: 'triage', to: 'deploy', style: 'solid', weight: 1, ranks: true },
+  ],
+  stubs: [{ id: 'push', label: 'push to main', to: 'lint', style: 'solid', weight: 1 }],
+};
+
+// ---- The table: a row per job; every column sorts.
+
+const columns: DataColumn<Job>[] = [
+  { id: 'job', header: 'Job', rowHeader: true, cell: jobName, sortable: true },
+  { id: 'pass', header: 'Pass', align: 'end', width: '72px', cell: (j) => j.pass, compare: (a, b) => a.pass - b.pass },
+  { id: 'state', header: 'State', width: '120px', cell: (j) => pill({ text: j.state, tone: toneOf(j.state) }), compare: (a, b) => states[a.state]!.rank - states[b.state]!.rank },
+  { id: 'time', header: 'Time', align: 'end', width: '96px', cell: (j) => fmtDur(j.seconds), compare: (a, b) => a.seconds - b.seconds },
+  { id: 'runner', header: 'Runner', width: '120px', cell: (j) => j.runner, sortable: true },
+];
+
+// ---- The tiles.
+
+const failed = jobs.filter((j) => j.state === 'failed');
+const passes = Math.max(...jobs.map((j) => j.pass));
+const count = (s: State) => jobs.filter((j) => j.state === s).length;
+const tiles: StatTile[] = [
+  { id: 'jobs', label: 'Jobs', value: jobs.length, sub: [[`${count('done')} done`, `${count('running')} running`]] },
+  { id: 'failed', label: 'Failed jobs', value: failed.length, tone: failed.length ? 'failed' : undefined, sub: [failed.length ? failed.map((j) => `${jobName(j)}, pass ${j.pass}`) : ['All jobs passed']] },
+  { id: 'passes', label: 'Passes of the retry loop', value: passes, sub: [['Up to 3']] },
+  { id: 'time', label: 'Job time', value: fmtDur(jobs.reduce((t, j) => t + j.seconds, 0)), tip: 'Sum over all jobs' },
+];
+
+// ---- The page's own styles. Its colours are the theme's, so the page changes with the switch.
+
+const css = `
+.ci-page {
+  background: var(--ca-bg);
+  color: var(--ca-text);
+  font: 14px/1.45 system-ui, sans-serif;
+  padding: 16px;
+  display: grid;
+  gap: 16px;
+  container-type: inline-size;
+}
+.ci-page header { display: flex; align-items: center; gap: 16px; flex-wrap: wrap; }
+.ci-page h2 { font-size: 18px; margin: 0; flex: 1; color: var(--ca-text); }
+.ci-page h3 { font-size: 13px; font-weight: 600; margin: 0 0 8px; color: var(--ca-text-secondary); }
+.ci-page .body { display: grid; gap: 16px; grid-template-columns: minmax(0, 1fr) 260px; align-items: start; }
+.ci-page .main { display: grid; gap: 16px; min-width: 0; }
+.ci-page aside { background: var(--ca-card); border: 1px solid var(--ca-line); border-radius: 8px; padding: 12px; position: sticky; top: 0; }
+.ci-page dl { display: grid; grid-template-columns: auto 1fr; gap: 4px 12px; margin: 0; }
+.ci-page dt { color: var(--ca-text-muted); }
+.ci-page dd { margin: 0; }
+@container (max-width: 760px) { .ci-page .body { grid-template-columns: minmax(0, 1fr); } }
+`;
+
+// ---- The page: build it, then answer the events.
+
+export function mount(host: HTMLElement): void {
+  adoptThemes(document);
+  host.dataset['caTheme'] = 'contraagent-dark';
+
+  const page = document.createElement('div');
+  page.className = 'ci-page';
+  page.innerHTML = `<style>${css}</style>
+    <header><h2>web-app | pipeline 482 | main</h2></header>
+    <div class="body">
+      <div class="main">
+        <section><h3>Pipeline</h3></section>
+        <section></section>
+      </div>
+      <aside aria-live="polite"><h3>Selected</h3><div class="detail">No selection</div></aside>
+    </div>`;
+  const [graphBox, tableBox] = page.querySelectorAll('section');
+  const detail = page.querySelector<HTMLElement>('.detail')!;
+
+  // The theme: `data-ca-theme` on the box that holds the page.
+  const theme = document.createElement('cae-segmented');
+  theme.label = 'Theme';
+  theme.options = [
+    { value: 'contraagent-dark', label: 'Dark' },
+    { value: 'contraagent-light', label: 'Light' },
+    { value: 'high-contrast', label: 'High contrast' },
+  ];
+  theme.value = 'contraagent-dark';
+  theme.addEventListener('cae-change', (e) => {
+    theme.value = e.detail.value;
+    host.dataset['caTheme'] = e.detail.value;
+  });
+  page.querySelector('header')!.append(theme);
+
+  const stats = document.createElement('cae-stat-tiles');
+  stats.columns = 4;
+  stats.tiles = tiles;
+  page.querySelector('header')!.after(stats);
+
+  const table = document.createElement('cae-data-table') as CaeDataTable<Job>;
+  table.caption = 'Jobs of pipeline 482';
+  table.columns = columns;
+  table.rowKey = (j) => j.id;
+  table.rows = jobs;
+  table.addEventListener('cae-sort', (e) => {
+    table.sort = e.detail;
+    table.rows = sortRows(jobs, columns, e.detail);
+  });
+  tableBox!.append(table);
+
+  const view = document.createElement('cae-layered-graph');
+  view.key = 'pipeline-482'; // a new key is a new graph: the frame shows all of it again
+  view.graph = graph;
+  view.states = states;
+  view.strings = { cycle: 'next pass', badge: 'number of passes' };
+  graphBox!.append(view);
+
+  /** The selection: the graph shows it, the panel describes it. */
+  const select = (id: string | null) => {
+    view.selected = id;
+    detail.replaceChildren(describe(id));
+  };
+  view.addEventListener('cae-select', (e) => select(e.detail.id));
+  // A row of the table selects its job's mark in the graph.
+  table.addEventListener('cae-activate', (e) => select(markId(jobs.find((j) => j.id === e.detail.id)!)));
+
+  host.replaceChildren(page);
+}
+
+/** The panel's content for a mark, a node or the loop. */
+function describe(id: string | null): Node {
+  const runs = jobs.filter((j) => markId(j) === id);
+  const step = steps.find((s) => s.id === id);
+  let title = 'No selection';
+  let rows: [string, string][] = [];
+  if (runs.length) {
+    const last = runs[runs.length - 1]!;
+    title = jobName(last);
+    rows = [['State', last.state], ['Passes', String(runs.length)], ...runs.map((j): [string, string] => [`Pass ${j.pass}`, `${j.state} | ${fmtDur(j.seconds)} | ${j.runner}`])];
+  } else if (step) {
+    const own = jobs.filter((j) => j.step === step.id);
+    title = step.label;
+    rows = [['Jobs', String(own.length)], ['Failed', String(own.filter((j) => j.state === 'failed').length)], ['Time', fmtDur(own.reduce((t, j) => t + j.seconds, 0))]];
+  } else if (id === 'retry') {
+    title = 'retry loop';
+    rows = [['Passes', `${passes} of up to 3`], ['Rerun', jobs.filter((j) => j.pass > 1 && j.shard).map(jobName).join(', ')]];
+  }
+  const box = document.createElement('div');
+  const h = document.createElement('strong');
+  h.textContent = title;
+  const dl = document.createElement('dl');
+  for (const [k, v] of rows) {
+    const dt = document.createElement('dt');
+    const dd = document.createElement('dd');
+    dt.textContent = k;
+    dd.textContent = v;
+    dl.append(dt, dd);
+  }
+  box.append(h, dl);
+  return box;
+}

package/docs/examples/data-table.ts

@@ -0,0 +1,39 @@
+// A data table: hand-written rows, one sortable column, a row's action. The
+// host holds the rows and the order, and answers the events.
+import '@contraagent/elements/data-table/define';
+import { sortRows, type CaeDataTable, type DataColumn } from '@contraagent/elements/data-table';
+import { pill } from '@contraagent/elements';
+
+interface Job {
+  id: string;
+  name: string;
+  minutes: number;
+  state: 'done' | 'failed' | 'running';
+}
+
+const jobs: Job[] = [
+  { id: 'j1', name: 'Build', minutes: 4, state: 'done' },
+  { id: 'j2', name: 'Unit tests', minutes: 11, state: 'failed' },
+  { id: 'j3', name: 'Deploy preview', minutes: 2, state: 'running' },
+];
+
+const columns: DataColumn<Job>[] = [
+  { id: 'name', header: 'Job', rowHeader: true, cell: (j) => j.name },
+  { id: 'minutes', header: 'Minutes', align: 'end', width: '96px', cell: (j) => j.minutes, compare: (a, b) => a.minutes - b.minutes },
+  { id: 'state', header: 'State', width: '120px', cell: (j) => pill({ text: j.state, tone: j.state }) },
+];
+
+export function mount(host: HTMLElement): void {
+  const table = document.createElement('cae-data-table') as CaeDataTable<Job>;
+  table.caption = 'Jobs';
+  table.columns = columns;
+  table.rowKey = (j) => j.id;
+  table.rows = jobs;
+  table.addEventListener('cae-sort', (e) => {
+    table.sort = e.detail;
+    table.rows = sortRows(jobs, columns, e.detail);
+  });
+  const shown = document.createElement('p');
+  table.addEventListener('cae-activate', (e) => (shown.textContent = `Opened: ${e.detail.id}`));
+  host.replaceChildren(table, shown);
+}

package/docs/examples/graph.ts

@@ -0,0 +1,57 @@
+// A layered graph: a hand-written build pipeline of three steps, the last two in a
+// cluster that repeats (a retry loop), one mark per service in each step. The host
+// keeps the selection and the order, and answers the events.
+import '@contraagent/elements/graph/define';
+import type { GraphInput, GraphMark, GraphNodeInput } from '@contraagent/elements/graph';
+import type { StateStyles } from '@contraagent/elements/primitives';
+
+const states: StateStyles = {
+  ok: { label: 'ok', tone: 'done', shape: 'round', rank: 0 },
+  busy: { label: 'busy', tone: 'running', shape: 'round', rank: 2 },
+  broken: { label: 'broken', tone: 'failed', shape: 'square', rank: 3 },
+  queued: { label: 'queued', tone: 'neutral', shape: 'ring', rank: 1 },
+};
+
+const services = ['api', 'web', 'worker'];
+
+/** One mark per service: its id is unique in the graph, so it is what the graph selects. */
+const marks = (step: string, looks: string[]): GraphMark[] =>
+  services.map((s, i) => ({ id: `${step}#${s}`, state: looks[i] ?? 'queued', label: `${step} · ${s} | ${looks[i] ?? 'queued'}`, tip: `${step} · ${s}` }));
+
+/** A step: its counts and its header's count ("2/3") come from its marks. */
+const node = (id: string, label: string, looks: string[], cluster: string | null): GraphNodeInput => ({ id, label, cluster, marks: marks(id, looks) });
+
+const graph: GraphInput = {
+  series: services,
+  nodes: [
+    node('build', 'build', ['ok', 'ok', 'ok'], null),
+    node('test', 'test', ['ok', 'broken', 'ok'], 'retry'),
+    node('deploy', 'deploy', ['busy', 'queued', 'ok'], 'retry'),
+  ],
+  clusters: [{ id: 'retry', parent: null, label: 'retry', note: 'up to 3 rounds', cycle: true }],
+  edges: [
+    { from: 'build', to: 'test', style: 'solid', weight: 3, ranks: true },
+    { from: 'test', to: 'deploy', style: 'solid', weight: 3, ranks: true },
+    // The next round: back from deploy to test; it does not set the layers.
+    { from: 'deploy', to: 'test', style: 'solid', weight: 1, ranks: false },
+  ],
+  stubs: [{ id: 'commit', label: 'commit', to: 'build', style: 'solid', weight: 1 }],
+};
+
+export function mount(host: HTMLElement): void {
+  const el = document.createElement('cae-layered-graph');
+  el.graph = graph;
+  el.states = states;
+  el.key = 'pipeline';
+  el.strings = { cycle: 'next round' };
+  const card = document.createElement('div');
+  card.slot = 'inspector';
+  el.append(card);
+  const shown = document.createElement('p');
+  el.addEventListener('cae-select', (e) => {
+    el.selected = e.detail.id;
+    card.innerHTML = e.detail.id ? `<h4>${e.detail.id}</h4>` : '';
+  });
+  el.addEventListener('cae-activate', (e) => (shown.textContent = `Opened: ${e.detail.id}`));
+  host.replaceChildren(el, shown);
+}

package/docs/examples/lanes.ts

@@ -0,0 +1,40 @@
+// Lanes: hand-written jobs on a time axis, a lane per stage, one job running.
+// The host names the looks of the bars; their labels are the legend.
+import '@contraagent/elements/lanes/define';
+import type { Lane, LaneStyle } from '@contraagent/elements/lanes';
+
+const barStyles: Record<string, LaneStyle> = {
+  passed: { label: 'passed', color: 'var(--ca-status-done)' },
+  failed: { label: 'failed', color: 'var(--ca-status-failed)', pattern: 'hatched' },
+  running: { label: 'running', color: 'var(--ca-status-running)', pattern: 'striped' },
+};
+
+export function mount(host: HTMLElement): void {
+  const now = Date.now();
+  const min = 60e3;
+  const lanes: Lane[] = [
+    {
+      id: 'build',
+      label: 'Build',
+      bars: [
+        { id: 'b1', start: now - 9 * min, end: now - 6 * min, style: 'failed', label: 'Build #1\nfailed' },
+        { id: 'b2', start: now - 6 * min, end: now - 3 * min, style: 'passed', label: 'Build #2\npassed' },
+      ],
+    },
+    {
+      id: 'test',
+      label: 'Test',
+      bars: [
+        { id: 't1', start: now - 3 * min, end: null, style: 'running', label: 'Unit tests\nrunning' },
+        { id: 't2', start: now - 2.5 * min, end: now - 1 * min, style: 'passed', label: 'Lint\npassed' },
+      ],
+    },
+  ];
+  const el = document.createElement('cae-lanes');
+  el.lanes = lanes;
+  el.barStyles = barStyles;
+  el.live = true;
+  el.omitted = 3;
+  el.strings = { omitted: (n) => `${n} older jobs not shown` };
+  host.replaceChildren(el);
+}