@contraagent/elements 0.0.0-stage → 0.2.0

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/code.ts

@@ -0,0 +1,28 @@
+// Code: a hand-written script, numbered from line 12, two of its lines marked; and
+// the same element on a text too long to show whole.
+import '@contraagent/elements/code/define';
+
+const script = `def build(target: str, jobs: int = 4) -> bool:
+    """Build one target; True when it passed."""
+    result = run(["make", f"-j{jobs}", target])
+    if result.returncode != 0:
+        log.error("build of %s failed", target)  # the log names the target
+        return False
+    return True
+`;
+
+export function mount(host: HTMLElement): void {
+  const code = document.createElement('cae-code');
+  code.code = script;
+  code.language = 'python';
+  code.path = 'ci/build.py';
+  code.start = 12;
+  code.highlight = [15, [16, 17]];
+
+  const long = document.createElement('cae-code');
+  long.code = Array.from({ length: 40 }, (_, i) => `step ${i + 1}: ok`).join('\n');
+  long.path = 'logs/steps.txt';
+  long.maxLines = 6;
+  long.style.marginTop = '12px';
+  host.replaceChildren(code, long);
+}

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);
+}

package/docs/examples/matrix.ts

@@ -0,0 +1,56 @@
+// A mark matrix: a hand-written week of nightly checks, a row per service, a column
+// per check under a group per night. The host sorts the rows and keeps the selection.
+import '@contraagent/elements/matrix/define';
+import type { MarkMatrixInput, MatrixRowInput } from '@contraagent/elements/matrix';
+import type { StateStyles } from '@contraagent/elements/primitives';
+
+const states: StateStyles = {
+  pass: { label: 'pass', tone: 'done', shape: 'round', rank: 0 },
+  fail: { label: 'fail', tone: 'failed', shape: 'square', rank: 2 },
+  skip: { label: 'skip', tone: 'muted', shape: 'round', rank: 1 },
+};
+
+const nights = ['Mon', 'Tue'];
+const checks = ['lint', 'unit'];
+const results: Record<string, string[]> = { api: ['pass', 'pass', 'pass', 'fail'], web: ['pass', 'skip', 'pass', 'pass'], worker: ['fail', 'fail', 'pass', 'pass'] };
+
+const rows: MatrixRowInput[] = Object.entries(results).map(([service, rs]) => ({
+  id: service,
+  label: service,
+  value: rs.filter((r) => r === 'fail').length,
+  strong: rs.includes('fail'),
+  cells: rs.map((state, i) => {
+    const at = `${nights[Math.floor(i / 2)]} ${checks[i % 2]}`;
+    return { id: `${service}|${i}`, state, label: `${service} | ${at} | ${state}`, tip: `${service}, ${at}` };
+  }),
+}));
+
+const byFailures = (rs: readonly MatrixRowInput[]) => [...rs].sort((a, b) => Number(b.value) - Number(a.value));
+
+const matrix = (sort: string): MarkMatrixInput => ({
+  caption: 'Nightly checks',
+  label: 'Nightly checks by service',
+  facts: ['2 nights', '3 services'],
+  head: [
+    nights.map((n) => ({ id: n, label: n, span: 2, rows: 1, type: 'group' as const })),
+    nights.flatMap((n) => checks.map((c) => ({ id: `${n}|${c}`, label: c, span: 1, rows: 1, type: 'column' as const }))),
+  ],
+  columns: nights.flatMap((n) => checks.map((c) => ({ id: `${n}|${c}`, groups: [n] }))),
+  rows: sort === 'failures' ? byFailures(rows) : rows,
+  value: { label: 'Failures' },
+  sorts: [
+    { id: 'name', label: 'Name' },
+    { id: 'failures', label: 'Failures' },
+  ],
+  sort,
+});
+
+export function mount(host: HTMLElement): void {
+  const el = document.createElement('cae-mark-matrix');
+  el.matrix = matrix('name');
+  el.states = states;
+  el.strings = { rowsHeader: 'Service' };
+  el.addEventListener('cae-sort', (e) => (el.matrix = matrix(e.detail.id)));
+  el.addEventListener('cae-select', (e) => (el.selected = e.detail.id));
+  host.replaceChildren(el);
+}

package/docs/examples/page.css

@@ -0,0 +1,34 @@
+/* A page of your own in its elements' theme. With <html data-ca-theme="nord">
+   and the themes' rules in the document (adoptThemes(document)), the page's own
+   CSS reads the same --ca-* properties as the elements. */
+body {
+  margin: 0;
+  color-scheme: var(--ca-color-scheme);
+  background: var(--ca-bg);
+  color: var(--ca-text);
+  font: 13px/1.5 system-ui, sans-serif;
+}
+.card {
+  background: var(--ca-card);
+  border: 1px solid var(--ca-line);
+  border-radius: 8px;
+  padding: 16px;
+}
+.caption {
+  color: var(--ca-text-secondary);
+}
+.unit {
+  color: var(--ca-text-muted);
+}
+a {
+  color: var(--ca-accent);
+}
+:focus-visible {
+  outline: var(--ca-focus-width) solid var(--ca-focus);
+}
+/* A property with one default for every theme (a tint, a type size) has its
+   value only inside the elements: compute it the way the elements do. */
+.failed-badge {
+  color: var(--ca-status-failed);
+  background: color-mix(in srgb, var(--ca-status-failed) var(--ca-tint), transparent);
+}

package/docs/examples/segmented.ts

@@ -0,0 +1,18 @@
+// A segmented control: one choice among a few. The host holds the value and
+// answers `cae-change`; the words are the host's.
+import '@contraagent/elements/segmented/define';
+
+export function mount(host: HTMLElement): void {
+  const control = document.createElement('cae-segmented');
+  control.label = 'Period';
+  control.options = [
+    { value: 'day', label: 'Day' },
+    { value: 'week', label: 'Week' },
+    { value: 'month', label: 'Month', title: 'The last 30 days' },
+  ];
+  control.value = 'week';
+  const shown = document.createElement('p');
+  shown.textContent = `Showing: ${control.value}`;
+  control.addEventListener('cae-change', (e) => (shown.textContent = `Showing: ${e.detail.value}`));
+  host.replaceChildren(control, shown);
+}

package/docs/examples/status.ts

@@ -0,0 +1,30 @@
+// Statuses, a legend and a row of facts, drawn by the primitives into an element
+// of your own: its styles start from `base` (the tokens and the status rules),
+// plus `legendStyles` for the legend.
+import { base, factLine, legend, legendStyles, pill, statusWord } from '@contraagent/elements';
+import { LitElement, html } from 'lit';
+
+class BuildSummary extends LitElement {
+  static override styles = [base, legendStyles];
+
+  override render() {
+    return html`<p>
+        ${pill({ text: 'passed', tone: 'done' })} ${pill({ text: 'failed', tone: 'failed', title: 'exit code 2' })}
+        ${pill({ text: 'running', tone: 'running' })} ${statusWord({ text: 'queued', tone: 'attention' })}
+      </p>
+      <p class="meta words">${factLine(['12 jobs', { text: '1 failed', tone: 'failed' }, '4m 05s'])}</p>
+      ${legend(
+        [
+          { label: 'passed', tone: 'done', shape: 'round' },
+          { label: 'failed', tone: 'failed', shape: 'square' },
+          { label: 'queued', tone: 'attention', shape: 'ring' },
+        ],
+        { label: 'Job states' },
+      )}`;
+  }
+}
+
+export function mount(host: HTMLElement): void {
+  if (!customElements.get('build-summary')) customElements.define('build-summary', BuildSummary);
+  host.replaceChildren(document.createElement('build-summary'));
+}

package/docs/examples/theme.css

@@ -0,0 +1,54 @@
+/* A theme of your own: Solarized Light (https://ethanschoonover.com/solarized/,
+   MIT, (c) Ethan Schoonover), built the way the built-in themes are.
+   Every colour is a --ca-* property, inherited through the elements' shadow
+   roots; one set here overrides the built-in theme's value, token by token.
+
+   Surfaces and text come from the palette's base tones, the accent is its blue,
+   the statuses its red, yellow, green and cyan, the code colours its syntax
+   colours. Solarized's accents are mid-tones: where one reads under 4.5:1 on
+   these surfaces, it is darkened in lightness only, with its hue kept. */
+.solarized-light {
+  --ca-color-scheme: light;
+  /* surfaces and text: base3, base2 and base02 to base01 */
+  --ca-backdrop: #eee8d5;
+  --ca-bg: #eee8d5;
+  --ca-card: #fdf6e3;
+  --ca-panel: #fdf6e3;
+  --ca-panel2: #fdf6e3;
+  --ca-raise: #eee8d5;
+  --ca-well: #f5efdc;
+  --ca-track: #e4ddc8;
+  --ca-line: #e4ddc8;
+  --ca-line2: #93a1a1;
+  --ca-shadow: #586e7533;
+  --ca-text: #073642;
+  --ca-text-secondary: #365059;
+  --ca-text-muted: #4b6068;
+  /* interaction: blue */
+  --ca-accent: #02629b;
+  --ca-focus: #268bd2;
+  --ca-selection: #268bd233;
+  /* status: red, yellow, green, cyan, base01 */
+  --ca-status-failed: #bd0112;
+  --ca-status-attention: #7a5b01;
+  --ca-status-done: #586604;
+  --ca-status-running: #046b64;
+  --ca-status-muted: #4e646c;
+  --ca-tint: 10%;
+  /* identity: violet, and the token bars */
+  --ca-agent: #5a5eaf;
+  --ca-meter: #93a1a1;
+  --ca-tok-input: #268bd2;
+  --ca-tok-cache-read: #e4ddc8;
+  --ca-tok-cache-write: #93a1a1;
+  --ca-tok-output: #6c71c4;
+  /* code */
+  --ca-code-keyword: #657402;
+  --ca-code-string: #077a73;
+  --ca-code-number: #c82979;
+  --ca-code-constant: #c14204;
+  --ca-code-comment: #626f6f;
+  --ca-code-function: #0071b3;
+  --ca-code-type: #896705;
+  --ca-code-name: #0071b3;
+}

package/docs/examples/tiles.ts

@@ -0,0 +1,27 @@
+// Stat tiles: hand-written figures, one with a tone and a link. The host holds
+// the figures and answers `cae-action`.
+import '@contraagent/elements/tiles/define';
+import type { StatTile } from '@contraagent/elements/tiles';
+
+const tiles: StatTile[] = [
+  { id: 'jobs', label: 'Jobs', value: 24, sub: [[{ text: '22 passed' }, { text: '2 failed', tone: 'failed' }]] },
+  {
+    id: 'failed',
+    label: 'Failed jobs',
+    value: 2,
+    tone: 'failed',
+    sub: [['Unit tests', 'Lint']],
+    action: { id: 'list', label: 'Failed jobs in the log' },
+  },
+  { id: 'time', label: 'Build time', value: '14m 05s', sub: [['Longest: Unit tests']], tip: 'Sum over all jobs' },
+  { id: 'queued', label: 'Queued', value: 0, sub: [['No jobs waiting']] },
+];
+
+export function mount(host: HTMLElement): void {
+  const grid = document.createElement('cae-stat-tiles');
+  grid.columns = 4;
+  grid.tiles = tiles;
+  const shown = document.createElement('p');
+  grid.addEventListener('cae-action', (e) => (shown.textContent = `Action: ${e.detail.action} of ${e.detail.id}`));
+  host.replaceChildren(grid, shown);
+}