@contraagent/elements 0.0.0-stage → 0.1.0

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

package/docs/examples/transcript.ts

@@ -0,0 +1,59 @@
+// A conversation with a support bot in two sessions: the first ended with a
+// failed lookup, the second answered. The host holds the sections and decides
+// what a reader's pick means: here the picked session is simply shown.
+import '@contraagent/elements/transcript/define';
+import { md } from '@contraagent/elements/markdown';
+import type { TranscriptSection } from '@contraagent/elements/transcript';
+
+const sections: TranscriptSection[] = [
+  {
+    id: 's1',
+    title: 'Session 1',
+    verdict: { tone: 'failed', text: 'failed', tip: 'The order service did not answer' },
+    tags: [
+      { label: 'bot', value: 'helpdesk' },
+      { label: 'model', value: 'small-2', look: 'mono' },
+    ],
+    items: [
+      { type: 'prompt', id: 'p1', text: 'Where is order 1042?' },
+      { type: 'reasoning', id: 'r1', text: 'Look the order up first, then answer with its **status**.' },
+      { type: 'tool', id: 't1', name: 'orders.get', icon: 'read', summary: 'order 1042', output: 'timeout after 30s', status: 'error' },
+    ],
+    footer: { tone: 'failed', title: 'The order service did not answer' },
+  },
+  {
+    id: 's2',
+    title: 'Session 2',
+    facts: ['small-2'],
+    verdict: { tone: 'done', text: 'answered' },
+    items: [
+      { type: 'event', id: 'e1', icon: '↻', title: 'Request sent again', text: 'after a timeout' },
+      {
+        type: 'tool',
+        id: 't2',
+        name: 'web_search',
+        icon: 'search',
+        summary: 'carrier tracking 1042',
+        query: 'carrier tracking 1042',
+        links: [
+          { title: 'Track a parcel', url: 'https://example.com/track' },
+          { title: 'Delivery times', url: 'https://example.org/delivery' },
+        ],
+        output: 'Track a parcel https://example.com/track\nDelivery times https://example.org/delivery',
+        status: 'ok',
+      },
+      { type: 'notice', id: 'n1', text: 'cache hit: orders/1042' },
+      { type: 'message', id: 'm1', text: 'Order **1042** left the warehouse on Monday and arrives on *Thursday*.' },
+    ],
+  },
+];
+
+export function mount(host: HTMLElement): void {
+  const t = document.createElement('cae-transcript');
+  t.sections = sections;
+  t.markdown = md;
+  t.strings = { sections: 'Sessions', sectionsTip: 'One session per conversation with the bot' };
+  t.style.height = '420px';
+  t.addEventListener('cae-section-change', (e) => (t.shown = e.detail.index));
+  host.replaceChildren(t);
+}

package/docs/graph.md

@@ -0,0 +1,112 @@
+# Layered graph
+
+`<cae-layered-graph>` draws nodes in layers, joined by edges, inside clusters: a
+pipeline, a build, any flow of steps. Each node holds a group of marks, one per
+series id, at the same place in every node, so one series can be followed across
+the graph. Register it with `@contraagent/elements/graph/define` (it registers
+`<cae-mark-matrix>` and `<cae-segmented>` too); the types, `arrange` and
+`layoutGraph` are in `@contraagent/elements/graph`.
+
+![A layered graph: commit, then build, then a retry loop of test and deploy, a mark per series in each node, and the legend](images/graph.webp)
+
+<!-- not on the site -->
+Live on this topic's page of the documentation site (`pnpm run docs` in `web/`).
+
+::code{file="examples/graph.ts"}
+
+## The model
+
+A `GraphInput` names the series, the nodes, the clusters, the edges and the stubs
+(edges from outside the graph). A state is any id: `states` (`StateStyles`) gives
+each its word, its tone and its shape, and its key order is the legend's.
+
+A mark is in a series when the same item has a mark in several nodes: a service
+built, tested and deployed is a series, and its marks line up across the steps.
+A mark of one node only (a job of one CI step) is in that node's `loose`.
+
+A node's `counts` (the bar of a node with many marks) and `progress` (the count
+in its header, "2/3") default to what its marks say: its marks by state, and its
+marks whose state has the tone `done` of all its marks, in the words of
+`strings.progress`. Give them when a node stands for more items than it has marks.
+
+::code{file="../src/graph/types.ts" from="export interface GraphNodeInput {" to="/** A node as the graph draws it"}
+
+A cluster is a box of nodes (and of other clusters). A cluster that `cycle`s draws
+a return from its last layer to its first; an edge with `ranks: false` closes that
+cycle: it never sets the layers and is not drawn. An edge may join items in
+different clusters, at any depth: it leaves and enters each box on its way.
+
+An item the host can draw open or closed carries `toggle`: a node with `toggle:
+'closed'` draws a control in its header (`strings.open`, "Show inside") and a
+cluster with `toggle: 'open'` one in its corner (`strings.close`); either sends
+`cae-toggle` with the item's id and whether it is to be open, and the host draws
+the graph again. A cluster named by a `path` of parts shows them as "a › b › c":
+the first part is its name, and each later part sends `cae-drill` with that part's
+id. `focusToggle(id)` puts the focus on an item's control once it is drawn again.
+
+`key` is the graph's identity. A new `key` is a new graph: the frame shows all of
+it again, and the focused mark of each node is forgotten. Keep the `key` while the
+same graph changes (a run in progress), so the reader's zoom and pan stay.
+
+## Order and drawing
+
+`arrange` gives each item its layer by the longest path to it, orders each layer to
+reduce crossings, and gives each edge its edge path: a point on every layer it crosses.
+The order depends on the structure only. Give the element the `order` of an earlier
+drawing of the same graph to keep its items in place: an item that appears later is
+added at the end of its layer. `layoutGraph` places everything from the measured
+sizes; the element measures its nodes itself. Below 640 px of width, `direction:
+'auto'` draws top to bottom. `extentOf(arrangement)` gives a drawing's shape before
+it is measured: the layers it spans along the flow and the items it stacks across
+it at most, a cluster counted as what it holds; a host can choose the direction,
+or how much to draw, from it.
+
+## Size
+
+The element is as wide as its container. Without a height, the frame is as tall
+as the whole drawing at that width (never scaled up), up to 70% of the window's
+height or 360 px, whichever is more; top to bottom, as tall as the drawing. With a
+height set on the element (or given by a flex or grid container), the `crumbs`
+slot and the row under the frame keep their height, and the frame takes the rest,
+with the whole drawing fitted and centred in it.
+
+## Selection and events
+
+A click selects a mark, a node or a cluster and sends `cae-select`; the element
+does not select by itself: the host sets `selected`. Enter or a double click sends
+`cae-activate`, or `cae-drill` for an item with `drill` (an inner view). "Graph |
+Table" sends `cae-view-change`: the table is a row per node with the nodes it is
+joined to. With `matrix`, the frame shows a [mark matrix](matrix.md) as the table.
+
+The card of the selected item is the host's content in the `inspector` slot,
+beside the item in the frame; its first heading and its `[data-status]` element
+name the item to a screen reader. With nothing in the slot when the element
+draws (a new `selected` draws it), there is no card: a page that shows the
+selection elsewhere leaves the slot empty.
+
+Hovering, focusing or selecting a mark highlights its series; `related` names more
+marks to light (a mark's id, or a series id, to the ids of the marks it lights).
+
+The line under the legend holds the key hints. It keeps its height at all times,
+and shows its words while the graph has the focus. On a screen with touch alone
+(no fine pointer) there is no line; `::part(keys) { display: none; }` removes it
+everywhere.
+
+## Look
+
+The words are `strings` ([Strings](strings.md)). `renderIcon` draws the icons a
+node names (`icons`), and `iconStyles` adds styles for them. A mark has the state's
+look as `data-tone` and `data-shape`. The parts, for `::part()`:
+
+| Part | What it is |
+|---|---|
+| `frame` | the frame every view is drawn in |
+| `stage` | what pans and zooms |
+| `node`, `node-header`, `node-name` | each node, its first line, its name |
+| `mark` | each mark |
+| `cluster`, `cluster-label` | each cluster, its header |
+| `edge`, `stub` | each edge, each stub |
+| `legend` | the legend |
+| `keys` | the line of key hints |
+| `inspector` | the selected item's card |
+| `table`, `row` | the node table, each of its rows |

package/docs/lanes.md

@@ -0,0 +1,48 @@
+# Lanes
+
+`<cae-lanes>` shows bars on a time axis, a lane per group: each bar as long as
+the thing it stands for took. Register it with
+`@contraagent/elements/lanes/define`; the types and the placement functions are
+in `@contraagent/elements/lanes`.
+
+![Lanes on a time axis: a build that failed then passed, a test still running, and a line at now](images/lanes.webp)
+
+<!-- not on the site -->
+Live on this topic's page of the documentation site (`pnpm run docs` in `web/`).
+
+::code{file="examples/lanes.ts"}
+
+## Lanes and bars
+
+A lane is a `Lane`, a bar a `LaneBar`: a start and an end in epoch
+milliseconds, the key of its look and its tooltip. A bar with no end is
+running: it grows until now, and a line marks now. Set `live` while a bar runs,
+so the element draws again every second.
+
+::code{file="../src/lanes/types.ts" from="/** Something that took time" to="/** A row of bars"}
+
+The overlapping bars of a lane are stacked, each on the first row whose last
+bar has ended (`stack`), so no bar hides another. The bars grow in when they
+are first drawn.
+
+## Looks and the legend
+
+`barStyles` maps each key to a `LaneStyle`: a label, a colour, and a pattern
+(`solid`, `hatched`, `striped`, which moves on a bar, or `outline`). Give a
+status a pattern besides its colour, so it does not depend on colour alone. The
+labels are the legend, a row per `group`, in key order; `omitted` adds a note
+of the bars the host left out (`strings.omitted`).
+
+## The axis
+
+By default the axis fits the bars (`fitRange`): from the first start to the
+last end; with a running bar, to now plus 20 seconds, rounded up to the minute.
+Set `range` to fix it. The axis shows five times, with seconds when it spans
+less than 10 minutes, in `locale` (by default the page's `lang`).
+
+## Look
+
+`--cae-lanes-label-width` sets the width of the lanes' labels (112px, 78px when
+the element is narrower than 760 px). The parts are `axis`, `lane`, `lane-label`, `track`, `bar`,
+`now`, `legend` and `empty`; with no bars the element shows `strings.empty`, or
+the `empty` slot.

package/docs/matrix.md

@@ -0,0 +1,34 @@
+# Mark matrix
+
+`<cae-mark-matrix>` shows marks in a table: a row per series (its label, then a
+value), a column per item, the columns under nested groups. Register it with
+`@contraagent/elements/matrix/define`; the types are in
+`@contraagent/elements/matrix`.
+
+![A mark matrix of nightly checks: a row per service with its failures, a column per check under each night](images/matrix.webp)
+
+<!-- not on the site -->
+Live on this topic's page of the documentation site (`pnpm run docs` in `web/`).
+
+::code{file="examples/matrix.ts"}
+
+## The model
+
+A `MarkMatrixInput` holds the header rows (outermost first), the columns, the rows
+and the line above the table. A column names the groups it is under: a border marks
+where a group starts. A mark is drawn in its state's look (`states`, as in the
+[layered graph](graph.md)).
+
+::code{file="../src/matrix/types.ts" from="export interface MatrixRowInput {" to="export interface MarkMatrixStrings {"}
+
+## Keyboard and events
+
+The marks are one tab stop. The arrow keys, Home, End, Page Up and Page Down move
+between them (Ctrl with Home and End: the first and the last row). A click or the
+focus sends `cae-select`; Enter or a double click sends `cae-activate`, or
+`cae-drill` for a mark with `drill`. The sort control sends `cae-sort`: the host
+sorts the rows and sets `sort`. Above `windowAt` rows (150), only the rows in view
+are drawn.
+
+The words are `strings` ([Strings](strings.md)): the sort control's label and the
+header of the rows' labels.

package/docs/page.md

@@ -0,0 +1,87 @@
+# Building a page
+
+A page made of several elements: one run of a made-up CI pipeline, with a theme
+switch, stat tiles, a sortable table of jobs, and a layered graph of the steps
+beside a detail panel of the page's own. The whole example is
+`docs/examples/ci-pipeline.ts`; it uses only the package's public entry points,
+and `mount(host)` builds the page in any element.
+
+![A CI pipeline's page in the light theme: a theme switch, stat tiles, the layered graph of its steps beside a detail panel, and a table of its jobs](images/page.webp)
+
+<!-- not on the site -->
+Live on this topic's page of the documentation site (`pnpm run docs` in `web/`).
+
+## What the page holds
+
+The elements keep no state of their own that the page needs: each one draws
+what its properties give it and sends a `cae-*` event for what the reader did.
+The page holds the data, the theme, the selection and the order of the table,
+and sets them back on the elements.
+
+| The reader | The element sends | The page sets |
+|---|---|---|
+| picks a theme | `cae-change` from `<cae-segmented>` | `data-ca-theme` on the page's box, and the control's `value` |
+| sorts a column | `cae-sort` from `<cae-data-table>` | the table's `sort`, and its `rows` in that order (`sortRows`) |
+| opens a row | `cae-activate` from `<cae-data-table>` | the graph's `selected`, and the panel |
+| selects a mark, a node or the loop | `cae-select` from `<cae-layered-graph>` | the graph's `selected`, and the panel |
+
+## Registering and theming
+
+Each `define` entry registers its elements; `adoptThemes(document)` adds the
+themes' rules once, and `data-ca-theme` on any ancestor then picks a theme
+([Theming](theming.md)).
+
+::code{file="examples/ci-pipeline.ts" from="import '@contraagent/elements/segmented/define'" to="// ---- The data"}
+
+## Widths
+
+Each element is as wide as its container and lays itself out by its own width,
+not the window's: its host is a CSS container (`container-type: inline-size`),
+so the same element fits a sidebar, a column or a whole page. Its width does
+not come from its content: in a flex row, give it a width or `flex: 1`. A table
+wider than its element scrolls inside its own box. This page's two columns
+become one below 760 px of the page's own width (`@container` in its stylesheet).
+
+## The data
+
+A step is a node of the graph and a job is one run of it, or of one of its
+shards. The steps `e2e` and `triage` repeat in a retry loop.
+
+::code{file="examples/ci-pipeline.ts" from="// ---- The data" to="// ---- What each state"}
+
+## States
+
+A state is the page's own word: `StateStyles` gives each one a tone, a shape
+and a rank, and the legend follows its key order.
+
+::code{file="examples/ci-pipeline.ts" from="// ---- What each state" to="// ---- The graph"}
+
+## The graph
+
+The shards are the graph's `series`, so shard 2 is at the same place in every
+node that has shards; a step that runs once has one mark in `loose`. Each mark
+shows the last pass of its job, and the number of passes as its `badge`. The
+loop is a cluster that `cycle`s, closed by an edge with `ranks: false`. A
+node's `counts` and `progress` follow from its marks. The page puts nothing in
+the graph's `inspector` slot, so the graph draws no card beside the selection:
+the panel beside the graph describes it.
+
+::code{file="examples/ci-pipeline.ts" from="// ---- The graph" to="// ---- The table"}
+
+## The table and the tiles
+
+A column with `compare` sorts by it; a column with `sortable` and no `compare`
+sorts by its cell, a string or a number.
+
+::code{file="examples/ci-pipeline.ts" from="// ---- The table" to="// ---- The page's own styles"}
+
+## The page's styles
+
+The page's own text and boxes take the theme's colours (`--ca-*`), so they
+change with the switch.
+
+::code{file="examples/ci-pipeline.ts" from="// ---- The page's own styles" to="// ---- The page: build it"}
+
+## The page
+
+::code{file="examples/ci-pipeline.ts" from="// ---- The page: build it"}

package/docs/primitives.md

@@ -0,0 +1,57 @@
+# Primitives
+
+The parts every element is built from, in `@contraagent/elements/primitives`.
+Most are template functions that a Lit element calls in its `render()`; their
+look comes from the element's styles, which start from `base`
+(`@contraagent/elements/styles`: the tokens, the status rules, chips, layout
+and motion).
+
+![Status pills (passed, failed, running, queued), a row of facts, and a legend](images/primitives.webp)
+
+## Tones
+
+A tone is the status colour a value takes: `failed`, `attention`, `done`,
+`running`, `muted`, or `neutral` (the text colour). The names are the token
+names (`--ca-status-<tone>`, [Theming](theming.md)). An element shows a tone as
+`data-tone`, and `neutral` as no attribute (`toneAttr`).
+
+::code{file="../src/core/tone.ts" from="/** A status colour" to="export const TONES"}
+
+## Statuses, legends and facts
+
+`pill` draws a status as a pill, `statusWord` as a word in a row, and
+`statusChip` in a class the element styles. Each sets `data-tone` and, where a
+mark belongs, `data-mark` (✓ done, ✕ failed, ◌ pending): the mark is drawn by
+CSS and hidden from screen readers, which read the word. A pill also has the
+parts `pill` and `tone-<tone>`.
+
+`legend` draws a list of entries, each a swatch (a colour, a tone and a shape,
+a class, or an icon of its own) and its word; add `legendStyles` to the
+element's styles. `factLine` draws a row of facts separated by ` | ` that
+breaks between facts, never inside one; a fact with a tone is in its status
+colour.
+
+::code{file="examples/status.ts"}
+
+## Icons
+
+`icon(name, label)` draws a glyph, or a template registered under `name` with
+`registerIcon`. Without a label it is hidden from screen readers; with one, the
+label is its tooltip and what a screen reader reads.
+
+## The segmented control
+
+`<cae-segmented>` is one choice among a few: a radio group, one tab stop, the
+arrow keys, Home and End to choose. It sends `cae-change` with the chosen
+value; the host keeps `value`.
+
+::code{file="examples/segmented.ts"}
+
+## Keyboard and long lists
+
+`RovingFocusController` gives a group of items one tab stop and moves the
+focus with the arrow keys, in a row, a column or a grid (`rovingStep` is the
+rule). `windowRows` is the arithmetic for drawing only the rows of a long list
+that are on screen.
+
+::code{file="../src/primitives/window.ts" from="/**" to="export function windowRows"}

package/docs/strings.md

@@ -0,0 +1,16 @@
+# Strings
+
+An element shows words: a button's name, an empty state, a count. It takes
+them from its `strings` property, a partial set of its `XStrings` interface,
+and uses its English default (`DEFAULT_X_STRINGS`) for each word it is not
+given. A word with a number is a function of the number, so the host decides
+plural forms and word order. Nothing here depends on a localization library:
+the host translates.
+
+::code{file="../src/markdown/cae-markdown.ts" from="export interface MarkdownStrings" to="export const DEFAULT_MARKDOWN_STRINGS"}
+
+```ts
+markdown.strings = { showRendered: 'プレビューを表示', showSource: 'ソースを表示' };
+```
+
+`withDefaults(defaults, given)` merges the two, as each element does.