@contraagent/elements 0.0.0-stage → 0.2.0

package/dist/tree/tree.d.ts

@@ -0,0 +1,83 @@
+import { LitElement, type PropertyValues, type TemplateResult } from 'lit';
+import type { Tone } from '../core/tone.js';
+/** One item of a tree: its name, the items under it, and how it looks. */
+export interface TreeItem {
+    /** Its id, unique in the tree. */
+    id: string;
+    name: string;
+    /** Its icon: a directory for an item with children, a file for one without, unless given. */
+    icon?: 'file' | 'directory' | null;
+    /** A word beside the name, coloured by `tone` (with its mark: ✓ done, ✕ failed, ◌ attention). */
+    badge?: string | null;
+    tone?: Tone | null;
+    /** Its children are shown at first (default: true). */
+    open?: boolean | null;
+    children?: readonly TreeItem[] | null;
+    /** A click or Enter selects it (`cae-select`); default: an item with no children. An item with children that is not selectable opens and closes instead. */
+    selectable?: boolean | null;
+}
+export interface TreeStrings {
+    /** What a tree with no items shows. */
+    empty: string;
+}
+export declare const DEFAULT_TREE_STRINGS: Readonly<TreeStrings>;
+/** An item where the tree shows it: its depth (1 at the top), its parent, and its place among its siblings. */
+export interface TreeRow {
+    item: TreeItem;
+    level: number;
+    parent: string | null;
+    index: number;
+    siblings: number;
+}
+/** The items shown, top to bottom: every item whose ancestors are all open (`isOpen`). */
+export declare function visibleRows(items: readonly TreeItem[], isOpen: (t: TreeItem) => boolean): TreeRow[];
+/** The ids of the ancestors of item `id`, outermost first; null when no item has that id. */
+export declare function ancestorsOf(items: readonly TreeItem[], id: string): string[] | null;
+/** The first item, depth first, that `match` accepts. */
+export declare function findItem(items: readonly TreeItem[], match: (t: TreeItem) => boolean): TreeItem | null;
+/**
+ * Items in a tree, the children of each under it, folded and opened by the reader: files
+ * and directories, say. It is one tab stop: Up and Down move between the items shown,
+ * Right opens an item (then moves to its first child), Left closes it (or moves to its
+ * parent), Home and End go to the first and the last, a letter to the next item of
+ * that initial; Enter, Space or a click selects a selectable item (`cae-select`) and
+ * opens or closes any other. The toggle before an item with children opens and closes
+ * it (`cae-toggle`). The ancestors of `selected` are always open.
+ *
+ * @tagname cae-tree
+ * @fires cae-select - `{id}`: an item was chosen with a click, Enter or Space
+ * @fires cae-toggle - `{id, open}`: the reader opened or closed an item
+ * @csspart tree - the list of items
+ * @csspart item - an item's row
+ * @csspart empty - what it shows with no items
+ */
+export declare class CaeTree extends LitElement {
+    static styles: (import("lit").CSSResult | import("lit").CSSResult[])[];
+    items: readonly TreeItem[];
+    /** The selected item's id, or null. */
+    selected: string | null;
+    /** What the tree is named to a screen reader. */
+    label: string;
+    /** The visible words; English by default. */
+    strings: Partial<TreeStrings>;
+    /** The reader's choice of open and closed items, by id, over each item's `open`. */
+    private opened;
+    /** The item that holds the tab stop. */
+    private focusId;
+    private readonly isOpen;
+    willUpdate(changed: PropertyValues<this>): void;
+    updated(changed: PropertyValues<this>): void;
+    private rowOf;
+    private setOpen;
+    private choose;
+    private moveTo;
+    private onKey;
+    render(): TemplateResult<1>;
+    private row;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'cae-tree': CaeTree;
+    }
+}
+//# sourceMappingURL=tree.d.ts.map

package/dist/tree/tree.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tree.d.ts","sourceRoot":"","sources":["../../src/tree/tree.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAA2B,KAAK,cAAc,EAAE,KAAK,cAAc,EAAE,MAAM,KAAK,CAAC;AAIpG,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,iBAAiB,CAAC;AAI5C,0EAA0E;AAC1E,MAAM,WAAW,QAAQ;IACvB,kCAAkC;IAClC,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,6FAA6F;IAC7F,IAAI,CAAC,EAAE,MAAM,GAAG,WAAW,GAAG,IAAI,CAAC;IACnC,iGAAiG;IACjG,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,IAAI,CAAC,EAAE,IAAI,GAAG,IAAI,CAAC;IACnB,uDAAuD;IACvD,IAAI,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;IACtB,QAAQ,CAAC,EAAE,SAAS,QAAQ,EAAE,GAAG,IAAI,CAAC;IACtC,4JAA4J;IAC5J,UAAU,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;CAC7B;AAED,MAAM,WAAW,WAAW;IAC1B,uCAAuC;IACvC,KAAK,EAAE,MAAM,CAAC;CACf;AAED,eAAO,MAAM,oBAAoB,EAAE,QAAQ,CAAC,WAAW,CAAyB,CAAC;AAEjF,+GAA+G;AAC/G,MAAM,WAAW,OAAO;IACtB,IAAI,EAAE,QAAQ,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;CAClB;AAKD,0FAA0F;AAC1F,wBAAgB,WAAW,CAAC,KAAK,EAAE,SAAS,QAAQ,EAAE,EAAE,MAAM,EAAE,CAAC,CAAC,EAAE,QAAQ,KAAK,OAAO,GAAG,OAAO,EAAE,CASnG;AAED,6FAA6F;AAC7F,wBAAgB,WAAW,CAAC,KAAK,EAAE,SAAS,QAAQ,EAAE,EAAE,EAAE,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,IAAI,CAOnF;AAED,yDAAyD;AACzD,wBAAgB,QAAQ,CAAC,KAAK,EAAE,SAAS,QAAQ,EAAE,EAAE,KAAK,EAAE,CAAC,CAAC,EAAE,QAAQ,KAAK,OAAO,GAAG,QAAQ,GAAG,IAAI,CAOrG;AAKD;;;;;;;;;;;;;;;GAeG;AACH,qBAAa,OAAQ,SAAQ,UAAU;IACrC,OAAgB,MAAM,0DAsBpB;IAE8B,KAAK,EAAE,SAAS,QAAQ,EAAE,CAAM;IAChE,uCAAuC;IACP,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAQ;IAC/D,iDAAiD;IACrC,KAAK,SAAM;IACvB,6CAA6C;IACb,OAAO,EAAE,OAAO,CAAC,WAAW,CAAC,CAAM;IAEnE,oFAAoF;IAC3E,OAAO,CAAC,MAAM,CAA8B;IACrD,wCAAwC;IAC/B,OAAO,CAAC,OAAO,CAAuB;IAE/C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAqE;IAEnF,UAAU,CAAC,OAAO,EAAE,cAAc,CAAC,IAAI,CAAC,GAAG,IAAI;IAW/C,OAAO,CAAC,OAAO,EAAE,cAAc,CAAC,IAAI,CAAC,GAAG,IAAI;IAMrD,OAAO,CAAC,KAAK;IAIb,OAAO,CAAC,OAAO;IAMf,OAAO,CAAC,MAAM;YAMA,MAAM;IAMpB,OAAO,CAAC,KAAK;IAyCJ,MAAM;IASf,OAAO,CAAC,GAAG;CAgCZ;AAED,OAAO,CAAC,MAAM,CAAC;IACb,UAAU,qBAAqB;QAC7B,UAAU,EAAE,OAAO,CAAC;KACrB;CACF"}

package/dist/tree/tree.js

@@ -0,0 +1,251 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+import { LitElement, css, html, nothing, svg } from 'lit';
+import { property, state } from 'lit/decorators.js';
+import { emit } from '../core/events.js';
+import { withDefaults } from '../core/strings.js';
+import { statusChip } from '../primitives/pill.js';
+import { base } from '../styles/index.js';
+export const DEFAULT_TREE_STRINGS = { empty: 'No items' };
+const hasChildren = (t) => !!t.children?.length;
+const selectable = (t) => t.selectable ?? !hasChildren(t);
+/** The items shown, top to bottom: every item whose ancestors are all open (`isOpen`). */
+export function visibleRows(items, isOpen) {
+    const out = [];
+    const walk = (list, level, parent) => list.forEach((item, index) => {
+        out.push({ item, level, parent, index, siblings: list.length });
+        if (hasChildren(item) && isOpen(item))
+            walk(item.children, level + 1, item.id);
+    });
+    walk(items, 1, null);
+    return out;
+}
+/** The ids of the ancestors of item `id`, outermost first; null when no item has that id. */
+export function ancestorsOf(items, id) {
+    for (const t of items) {
+        if (t.id === id)
+            return [];
+        const below = t.children ? ancestorsOf(t.children, id) : null;
+        if (below)
+            return [t.id, ...below];
+    }
+    return null;
+}
+/** The first item, depth first, that `match` accepts. */
+export function findItem(items, match) {
+    for (const t of items) {
+        if (match(t))
+            return t;
+        const below = t.children ? findItem(t.children, match) : null;
+        if (below)
+            return below;
+    }
+    return null;
+}
+const FOLDER = svg `<path d="M1.5 3.5h4l1.5 1.5h7.5v8h-13z" fill="none" stroke="currentColor" stroke-width="1.2" stroke-linejoin="round"></path>`;
+const FILE = svg `<path d="M3.5 1.5h6l3 3v10h-9z M9.5 1.5v3h3" fill="none" stroke="currentColor" stroke-width="1.2" stroke-linejoin="round"></path>`;
+/**
+ * Items in a tree, the children of each under it, folded and opened by the reader: files
+ * and directories, say. It is one tab stop: Up and Down move between the items shown,
+ * Right opens an item (then moves to its first child), Left closes it (or moves to its
+ * parent), Home and End go to the first and the last, a letter to the next item of
+ * that initial; Enter, Space or a click selects a selectable item (`cae-select`) and
+ * opens or closes any other. The toggle before an item with children opens and closes
+ * it (`cae-toggle`). The ancestors of `selected` are always open.
+ *
+ * @tagname cae-tree
+ * @fires cae-select - `{id}`: an item was chosen with a click, Enter or Space
+ * @fires cae-toggle - `{id, open}`: the reader opened or closed an item
+ * @csspart tree - the list of items
+ * @csspart item - an item's row
+ * @csspart empty - what it shows with no items
+ */
+export class CaeTree extends LitElement {
+    constructor() {
+        super(...arguments);
+        this.items = [];
+        /** The selected item's id, or null. */
+        this.selected = null;
+        /** What the tree is named to a screen reader. */
+        this.label = '';
+        /** The visible words; English by default. */
+        this.strings = {};
+        /** The reader's choice of open and closed items, by id, over each item's `open`. */
+        this.opened = new Map();
+        /** The item that holds the tab stop. */
+        this.focusId = null;
+        this.isOpen = (t) => this.opened.get(t.id) ?? t.open ?? true;
+    }
+    static { this.styles = [
+        base,
+        css `
+      :host { display: block; font-size: var(--font-size-md); }
+      .tree { margin: 0; padding: 2px 0; }
+      .row { display: flex; align-items: center; gap: 4px; min-height: 24px; padding: 0 8px 0 calc((var(--level) - 1) * 14px + 4px);
+        border-radius: var(--radius-sm); cursor: pointer; white-space: nowrap; color: var(--text-2); }
+      .row:hover { background: var(--raise); }
+      .row[aria-selected='true'] { background: color-mix(in srgb, var(--accent) 16%, transparent); color: var(--text); box-shadow: inset 2px 0 0 var(--accent); }
+      .row:focus-visible { outline-offset: -2px; }
+      .twist { flex: none; display: inline-grid; place-items: center; width: 16px; height: 16px; color: var(--text-muted); border-radius: var(--radius-sm); }
+      .twist svg { transition: transform 0.12s ease; }
+      [aria-expanded='true'] > .twist svg { transform: rotate(90deg); }
+      .twist:hover { color: var(--text); }
+      .icon { flex: none; width: 16px; height: 16px; color: var(--text-muted); }
+      .name { overflow: hidden; text-overflow: ellipsis; min-width: 0; }
+      .badge { flex: none; margin-left: 6px; font-size: 11px; padding: 0 6px; border-radius: var(--radius-pill); background: var(--raise); color: var(--text-2); }
+      .badge[data-tone] { background: var(--tone-bg); color: var(--tone); }
+      .badge[data-tone='done'] { background: none; color: var(--text-2); }
+      .empty { color: var(--text-muted); font-size: var(--font-size-sm); padding: 4px 8px; }
+      @media (prefers-reduced-motion: reduce) { .twist svg { transition: none; } }
+    `,
+    ]; }
+    willUpdate(changed) {
+        if (changed.has('selected') && this.selected) {
+            const up = ancestorsOf(this.items, this.selected);
+            if (up?.some((id) => this.opened.get(id) !== true)) {
+                const next = new Map(this.opened);
+                for (const id of up)
+                    next.set(id, true);
+                this.opened = next;
+            }
+        }
+    }
+    updated(changed) {
+        if (changed.has('selected') && this.selected && !this.matches(':focus-within')) {
+            this.rowOf(this.selected)?.scrollIntoView?.({ block: 'nearest' });
+        }
+    }
+    rowOf(id) {
+        return this.renderRoot.querySelector(`[data-id="${CSS.escape(id)}"]`);
+    }
+    setOpen(t, open) {
+        if (!hasChildren(t) || this.isOpen(t) === open)
+            return;
+        this.opened = new Map(this.opened).set(t.id, open);
+        emit(this, 'cae-toggle', { id: t.id, open });
+    }
+    choose(t) {
+        this.focusId = t.id;
+        if (selectable(t))
+            emit(this, 'cae-select', { id: t.id });
+        else
+            this.setOpen(t, !this.isOpen(t));
+    }
+    async moveTo(id) {
+        this.focusId = id;
+        await this.updateComplete;
+        this.rowOf(id)?.focus();
+    }
+    onKey(e, rows, i) {
+        const row = rows[i];
+        const t = row.item;
+        let to;
+        switch (e.key) {
+            case 'ArrowDown':
+                to = rows[i + 1];
+                break;
+            case 'ArrowUp':
+                to = rows[i - 1];
+                break;
+            case 'Home':
+                to = rows[0];
+                break;
+            case 'End':
+                to = rows[rows.length - 1];
+                break;
+            case 'ArrowRight':
+                if (hasChildren(t) && !this.isOpen(t))
+                    this.setOpen(t, true);
+                else if (hasChildren(t))
+                    to = rows[i + 1];
+                break;
+            case 'ArrowLeft':
+                if (hasChildren(t) && this.isOpen(t))
+                    this.setOpen(t, false);
+                else if (row.parent)
+                    to = rows.find((r) => r.item.id === row.parent);
+                break;
+            case 'Enter':
+            case ' ':
+                this.choose(t);
+                break;
+            default: {
+                if (e.key.length !== 1 || e.ctrlKey || e.metaKey || e.altKey || !/\S/.test(e.key))
+                    return;
+                const k = e.key.toLowerCase();
+                const order = [...rows.slice(i + 1), ...rows.slice(0, i)];
+                to = order.find((r) => r.item.name.toLowerCase().startsWith(k));
+                if (!to)
+                    return;
+            }
+        }
+        e.preventDefault();
+        if (to)
+            void this.moveTo(to.item.id);
+    }
+    render() {
+        if (!this.items.length)
+            return html `<div class="empty" part="empty">${withDefaults(DEFAULT_TREE_STRINGS, this.strings).empty}</div>`;
+        const rows = visibleRows(this.items, this.isOpen);
+        const stop = rows.find((r) => r.item.id === this.focusId) ?? rows.find((r) => r.item.id === this.selected) ?? rows[0];
+        return html `<div class="tree" role="tree" part="tree" aria-label=${this.label || nothing}>
+      ${rows.map((r, i) => this.row(r, i, rows, r === stop))}
+    </div>`;
+    }
+    row(r, i, rows, stop) {
+        const t = r.item;
+        const parent = hasChildren(t);
+        const open = parent && this.isOpen(t);
+        const directory = (t.icon ?? (parent ? 'directory' : 'file')) === 'directory';
+        return html `<div
+      class="row"
+      part="item"
+      role="treeitem"
+      data-id=${t.id}
+      tabindex=${stop ? 0 : -1}
+      style="--level: ${r.level}"
+      aria-level=${r.level}
+      aria-setsize=${r.siblings}
+      aria-posinset=${r.index + 1}
+      aria-expanded=${parent ? String(open) : nothing}
+      aria-selected=${selectable(t) ? String(t.id === this.selected) : nothing}
+      @click=${() => this.choose(t)}
+      @focus=${() => (this.focusId = t.id)}
+      @keydown=${(e) => this.onKey(e, rows, i)}
+    >
+      <span class="twist" aria-hidden="true" @click=${(e) => {
+            if (!parent)
+                return;
+            e.stopPropagation();
+            this.focusId = t.id;
+            this.setOpen(t, !open);
+        }}>${parent ? html `<svg width="10" height="10" viewBox="0 0 10 10"><path d="M3 1.5 7 5 3 8.5" fill="none" stroke="currentColor" stroke-width="1.5"></path></svg>` : nothing}</span>
+      <svg class="icon" viewBox="0 0 16 16" aria-hidden="true">${directory ? FOLDER : FILE}</svg>
+      <span class="name">${t.name}</span>
+      ${t.badge ? statusChip('badge', { text: t.badge, tone: t.tone ?? 'neutral' }) : nothing}
+    </div>`;
+    }
+}
+__decorate([
+    property({ attribute: false })
+], CaeTree.prototype, "items", void 0);
+__decorate([
+    property({ attribute: false })
+], CaeTree.prototype, "selected", void 0);
+__decorate([
+    property()
+], CaeTree.prototype, "label", void 0);
+__decorate([
+    property({ attribute: false })
+], CaeTree.prototype, "strings", void 0);
+__decorate([
+    state()
+], CaeTree.prototype, "opened", void 0);
+__decorate([
+    state()
+], CaeTree.prototype, "focusId", void 0);
+//# sourceMappingURL=tree.js.map

package/dist/tree/tree.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tree.js","sourceRoot":"","sources":["../../src/tree/tree.ts"],"names":[],"mappings":"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"}

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

@@ -0,0 +1,55 @@
+# Code
+
+`<cae-code>` shows a text as code: highlighted by its language, each line
+numbered, some lines marked, with a switch between long lines wrapped and
+scrolled sideways and a button that copies the whole text. Register it with
+`@contraagent/elements/code/define`; the element, the tokenizer it is drawn with
+and the languages it reads are in `@contraagent/elements/code`.
+
+<!-- not on the site -->
+Live on this topic's page of the documentation site (`pnpm run docs` in `web/`).
+
+::code{file="examples/code.ts"}
+
+## The text
+
+`code` is the text and `language` its language: a name of `LANGUAGES`, another
+name of one (`py`, `ts`, `sh`, `yml`) or a file name (`src/main.rs`); any other
+is shown as plain text. `start` is the number of the first line (1), and
+`highlight` marks lines in those numbers: a number for one line, a pair for the
+lines from the first to the last. A marked line has a bar beside its number and
+a tint. `path` names the file in the header; `label` names the lines to a screen
+reader (default: the path).
+
+A long text costs time to draw, so the element shows at most `maxLines` lines
+(5,000) and `maxCharacters` characters (500,000), cut at the end of a line, and
+says under them how many lines the text has (`strings.cut`). The copy button
+copies the whole text all the same.
+
+## Highlighting
+
+The highlighter is a small tokenizer of the package: each language is a few
+regular expressions and its words, so it needs no library and no request. It
+reads Python, JSON, JavaScript, TypeScript, C, C++, Java, Go, Rust, shell, TOML
+(and INI), YAML, SQL, XML (and HTML and SVG) and diffs. It marks comments,
+strings, numbers, keywords, constants, built-in names, the names a function or a
+type is given where it is defined, and a language's own parts (keys, tags,
+attributes, added and removed lines); it does not parse, so a rare construct may
+take the colour of a simpler one. `tokenize(code, language)` returns the tokens,
+`highlight(code, language)` escaped HTML; markdown's code blocks use the same
+(`@contraagent/elements/markdown`). The colours are the theme's `--ca-code-*`
+tokens ([Theming](theming.md)).
+
+::code{file="../src/code/highlight.ts" from="/** What a token is" to="/** The languages highlighted"}
+
+## Reading it
+
+The lines are one tab stop that scrolls with the arrow keys. The numbers are
+drawn beside the lines and are not part of a selection, so selected lines copy
+without them. `wrap` wraps long lines at first; the reader's switch
+(`strings.wrap`) changes it.
+
+## Look
+
+`--cae-code-max-height` sets the most the lines grow to before they scroll (70vh).
+The parts are `header`, `code` and `cut`.

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