@contraagent/elements 0.0.0-stage → 0.2.0

package/docs/transcript.md

@@ -0,0 +1,73 @@
+# Transcript
+
+`<cae-transcript>` shows a conversation with an agent: chat bubbles for the
+prompts, the answers and the model's reasoning, lines of the agent's own log,
+and a card per tool call that opens on its command and output. A web search
+lists the pages it returned as links; a page read shows its URL. Register it
+with `@contraagent/elements/transcript/define`; the types are in
+`@contraagent/elements/transcript`.
+
+![A transcript of two sessions: an API request sent again, a web search with 2 results, a log line, and the assistant's answer](images/transcript.webp)
+
+<!-- not on the site -->
+Live on this topic's page of the documentation site (`pnpm run docs` in `web/`).
+
+::code{file="examples/transcript.ts"}
+
+## Sections and items
+
+The conversation comes in sections, one per session with the agent. Above two
+sections, a picker shows one at a time; each section names itself (`title`),
+can add short facts after its name (a model) and a mark of how it ended
+(`verdict`: ✓ with the tone `done`, ✕ otherwise). A section's head shows its
+`tags` (who ran it) and its `details`: folded texts, code (a command line) or
+prose (a prompt). A `footer` after the items says how the section ended, with
+a list (errors) or a note.
+
+::code{file="../src/transcript/types.ts" from="export interface TranscriptSection {" to="/** Where the reader was in a transcript. */"}
+
+An item is a prompt, a message or reasoning (markdown), an event (a glyph, a
+title and a detail), a notice, or a tool card:
+
+::code{file="../src/transcript/types.ts" from="/** One tool call:" to="/** A labelled value in a section's head (who ran it). */"}
+
+## Following and reading
+
+`shown` picks a section (0-based); null follows the latest. While the reader
+is at the bottom, new content scrolls into view. Once they scroll up, it stays
+where they are, and a button counts what arrived below: `count` is how much
+the transcript holds (by default its sections and items), so a host that
+counts events sets it. A section that starts while the reader is scrolled up
+in the latest one keeps the one they read on screen. `live` shows the agent
+working, and a tool call with no result as running; without it, such a call
+was interrupted.
+
+A host that loads a transcript in pages sets `loading` until the first page
+has arrived, and `earlier` to the number of lines before it that are not
+loaded: a button then asks for them with `cae-load-earlier`, and the next
+`sections` it gets is the content from further back, which keeps the reader's
+place. For another transcript, give it a new element.
+
+`memory` keeps what the reader opened and where they were: `isOpen` and
+`setOpen` for the tool cards, `scroll` and `setScroll` for the position, which
+is restored once the content has arrived. Without it, both last as long as the
+element. `reveal(id)` opens a tool card and scrolls it into view once its
+section is shown; it returns that section's index for the host to show.
+
+## Events
+
+- `cae-section-change` with `{index}`: the reader picked a section (null: the
+  latest). The host sets `shown`.
+- `cae-section-shown` with `{index}`: the section on screen changed (-1: none),
+  also when a new section keeps the one being read.
+- `cae-load-earlier`: the reader asked for the content before `earlier`.
+
+## Look and words
+
+Markdown is turned into HTML by `markdown` (`md` of
+`@contraagent/elements/markdown` escapes the text); without it, answers and
+reasoning show as plain text. `renderDetail` draws an open prose detail. The
+parts are `picker`, `section`, `tag`, `bubble`, `notice`, `tool`, `tool-body`
+and `verdict`; `tagChips` and `tagStyles` draw tags elsewhere in the same
+look. The words are `strings` ([Strings](strings.md)): the picker's name and
+tooltip, the bubbles' heads, the tool cards' statuses, the counts.

package/docs/tree.md

@@ -0,0 +1,44 @@
+# Tree
+
+`<cae-tree>` shows items in a tree, the children of each under it, folded and
+opened by the reader: files and directories, say. Register it with
+`@contraagent/elements/tree/define`; the types are in
+`@contraagent/elements/tree`.
+
+<!-- not on the site -->
+Live on this topic's page of the documentation site (`pnpm run docs` in `web/`).
+
+::code{file="examples/tree.ts"}
+
+## Items
+
+An item is a `TreeItem`: an `id` unique in the tree, a `name` and its
+`children`. Its icon is a directory for an item with children and a file for one
+without, unless `icon` names one. A `badge` is a word beside the name in the
+colour of its `tone`, with the tone's mark (✓ done, ✕ failed, ◌ attention).
+`open: false` folds an item at first.
+
+::code{file="../src/tree/tree.ts" from="/** One item of a tree" to="export interface TreeStrings"}
+
+## Selection
+
+`selected` is the selected item's id; the element shows it and opens its
+ancestors, and the host sets it. A click, Enter or Space on a selectable item
+sends `cae-select` with its id: by default an item with no children is
+selectable, and an item with children opens and closes instead. The toggle
+before an item with children, Right and Left open and close it and send
+`cae-toggle`. A host pairs a tree with `<cae-code>` by showing the selected
+file's text beside it ([Code](code.md)).
+
+## Keyboard
+
+The tree is one tab stop, on the selected item or else the first. Up and Down
+move between the items shown, Right opens an item and then moves to its first
+child, Left closes it or moves to its parent, Home and End go to the first and
+the last item, and a letter moves to the next item whose name starts with it. A
+screen reader hears each item's level, its place among its siblings, and whether
+it is open and selected.
+
+## Look
+
+The parts are `tree`, `item` (with `data-id`) and `empty`.

package/docs/tsconfig.json

@@ -0,0 +1,20 @@
+{
+  // The examples are documentation: they compile against the package as it is.
+  "extends": "../../../tsconfig.base.json",
+  "compilerOptions": {
+    "noEmit": true,
+    "paths": {
+      "@contraagent/elements": ["../src/index.ts"],
+      "@contraagent/elements/segmented/define": ["../src/define/segmented.ts"],
+      "@contraagent/elements/data-table": ["../src/table/index.ts"],
+      "@contraagent/elements/data-table/define": ["../src/define/data-table.ts"],
+      "@contraagent/elements/tiles": ["../src/tiles/index.ts"],
+      "@contraagent/elements/tiles/define": ["../src/define/tiles.ts"],
+      "@contraagent/elements/lanes": ["../src/lanes/index.ts"],
+      "@contraagent/elements/lanes/define": ["../src/define/lanes.ts"],
+      "@contraagent/elements/check-table": ["../src/checks/index.ts"],
+      "@contraagent/elements/check-table/define": ["../src/define/check-table.ts"]
+    }
+  },
+  "include": ["examples/**/*.ts"]
+}

package/package.json

@@ -1,6 +1,179 @@
 {
   "name": "@contraagent/elements",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "Generic web components (Lit) and their parts: design tokens, themes, status pills, legends, a segmented control, a data table, a layered graph, a mark matrix, stat tiles, time lanes, charts (columns, lines, a heatmap, horizontal bars), a check table, a transcript, a JSON tree, markdown, highlighted code, a tree of items and counters. No contraagent data, no localization library",
+  "license": "MIT",
+  "keywords": [
+    "web-components",
+    "lit",
+    "custom-elements",
+    "charts",
+    "data-table",
+    "design-tokens"
+  ],
+  "homepage": "https://t-tani.github.io/contraagent/",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/t-tani/contraagent.git",
+    "directory": "web/packages/elements"
+  },
+  "bugs": {
+    "url": "https://github.com/t-tani/contraagent/issues"
+  },
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./primitives": {
+      "types": "./dist/primitives/index.d.ts",
+      "default": "./dist/primitives/index.js"
+    },
+    "./styles": {
+      "types": "./dist/styles/index.d.ts",
+      "default": "./dist/styles/index.js"
+    },
+    "./themes": {
+      "types": "./dist/themes/index.d.ts",
+      "default": "./dist/themes/index.js"
+    },
+    "./json-tree": {
+      "types": "./dist/json/index.d.ts",
+      "default": "./dist/json/index.js"
+    },
+    "./markdown": {
+      "types": "./dist/markdown/index.d.ts",
+      "default": "./dist/markdown/index.js"
+    },
+    "./code": {
+      "types": "./dist/code/index.d.ts",
+      "default": "./dist/code/index.js"
+    },
+    "./tree": {
+      "types": "./dist/tree/index.d.ts",
+      "default": "./dist/tree/index.js"
+    },
+    "./count": {
+      "types": "./dist/count/index.d.ts",
+      "default": "./dist/count/index.js"
+    },
+    "./data-table": {
+      "types": "./dist/table/index.d.ts",
+      "default": "./dist/table/index.js"
+    },
+    "./graph": {
+      "types": "./dist/graph/index.d.ts",
+      "default": "./dist/graph/index.js"
+    },
+    "./matrix": {
+      "types": "./dist/matrix/index.d.ts",
+      "default": "./dist/matrix/index.js"
+    },
+    "./tiles": {
+      "types": "./dist/tiles/index.d.ts",
+      "default": "./dist/tiles/index.js"
+    },
+    "./lanes": {
+      "types": "./dist/lanes/index.d.ts",
+      "default": "./dist/lanes/index.js"
+    },
+    "./charts": {
+      "types": "./dist/charts/index.d.ts",
+      "default": "./dist/charts/index.js"
+    },
+    "./check-table": {
+      "types": "./dist/checks/index.d.ts",
+      "default": "./dist/checks/index.js"
+    },
+    "./transcript": {
+      "types": "./dist/transcript/index.d.ts",
+      "default": "./dist/transcript/index.js"
+    },
+    "./define": {
+      "types": "./dist/define/all.d.ts",
+      "default": "./dist/define/all.js"
+    },
+    "./json-tree/define": {
+      "types": "./dist/define/json-tree.d.ts",
+      "default": "./dist/define/json-tree.js"
+    },
+    "./markdown/define": {
+      "types": "./dist/define/markdown.d.ts",
+      "default": "./dist/define/markdown.js"
+    },
+    "./code/define": {
+      "types": "./dist/define/code.d.ts",
+      "default": "./dist/define/code.js"
+    },
+    "./tree/define": {
+      "types": "./dist/define/tree.d.ts",
+      "default": "./dist/define/tree.js"
+    },
+    "./count/define": {
+      "types": "./dist/define/count.d.ts",
+      "default": "./dist/define/count.js"
+    },
+    "./segmented/define": {
+      "types": "./dist/define/segmented.d.ts",
+      "default": "./dist/define/segmented.js"
+    },
+    "./data-table/define": {
+      "types": "./dist/define/data-table.d.ts",
+      "default": "./dist/define/data-table.js"
+    },
+    "./graph/define": {
+      "types": "./dist/define/graph.d.ts",
+      "default": "./dist/define/graph.js"
+    },
+    "./matrix/define": {
+      "types": "./dist/define/matrix.d.ts",
+      "default": "./dist/define/matrix.js"
+    },
+    "./tiles/define": {
+      "types": "./dist/define/tiles.d.ts",
+      "default": "./dist/define/tiles.js"
+    },
+    "./lanes/define": {
+      "types": "./dist/define/lanes.d.ts",
+      "default": "./dist/define/lanes.js"
+    },
+    "./charts/define": {
+      "types": "./dist/define/charts.d.ts",
+      "default": "./dist/define/charts.js"
+    },
+    "./check-table/define": {
+      "types": "./dist/define/check-table.d.ts",
+      "default": "./dist/define/check-table.js"
+    },
+    "./transcript/define": {
+      "types": "./dist/define/transcript.d.ts",
+      "default": "./dist/define/transcript.js"
+    },
+    "./custom-elements.json": "./custom-elements.json"
+  },
+  "customElements": "custom-elements.json",
+  "files": [
+    "dist",
+    "src",
+    "!src/**/*.test.ts",
+    "!src/**/__snapshots__",
+    "docs",
+    "!docs/images",
+    "custom-elements.json"
+  ],
+  "sideEffects": [
+    "./dist/define/*.js"
+  ],
+  "peerDependencies": {
+    "lit": "^3.3.3"
+  },
+  "devDependencies": {
+    "@custom-elements-manifest/analyzer": "^0.11.0",
+    "lit": "^3.3.3"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json && cem analyze --litelement --globs 'src/*/{segmented,data-table,layered-graph,mark-matrix,stat-tiles,lanes,column-chart,line-chart,heatmap,bar-chart,check-table,transcript,json-tree,cae-markdown,code,tree,count,elapsed}.ts'",
+    "typecheck": "tsc -p tsconfig.json --noEmit && tsc -p docs"
+  }
+}

package/src/charts/bar-chart.ts

@@ -0,0 +1,74 @@
+import { css, html, nothing, type TemplateResult } from 'lit';
+import { property } from 'lit/decorators.js';
+import { toneAttr } from '../core/tone.js';
+import type { LegendItem } from '../primitives/legend.js';
+import { ChartElement } from './base.js';
+import type { ChartBar } from './types.js';
+
+/**
+ * Horizontal bars, one per label, in the order given (a funnel's stages, a ranking):
+ * each its label, a bar as long as its value against the longest, and the value in
+ * words. A bar with a `tone` takes that status colour, the others one colour. Every
+ * value is written beside its bar, so no tooltip is needed; the switch shows them as
+ * a table.
+ *
+ * @tagname cae-bar-chart
+ * @csspart plot - the bars
+ * @csspart table - the table of its values
+ * @csspart switch - the button between the two
+ * @csspart empty - what it shows with no values
+ */
+export class CaeBarChart extends ChartElement {
+  static override styles = [
+    ...ChartElement.styles,
+    css`
+      .bars { display: grid; grid-template-columns: minmax(80px, max-content) minmax(0, 1fr) max-content; gap: 6px 12px; align-items: center;
+        font-size: var(--font-size-sm); }
+      .bars .r { display: contents; }
+      .bars .l { color: var(--text-2); overflow: hidden; text-overflow: ellipsis; white-space: nowrap; max-width: 34ch; }
+      .bars .track { display: block; height: 12px; }
+      .bars .bar { display: block; height: 100%; min-width: 2px; border-radius: 1px 4px 4px 1px; background: var(--series-1); }
+      .bars .bar[data-tone] { background: var(--tone); }
+      .bars .v { color: var(--text-2); font-variant-numeric: tabular-nums; text-align: right; }
+    `,
+  ];
+
+  @property({ attribute: false }) bars: readonly ChartBar[] = [];
+
+  protected hasValues(): boolean {
+    return this.bars.length > 0;
+  }
+
+  protected legendItems(): LegendItem[] {
+    return [];
+  }
+
+  protected itemCount(): number {
+    return 0;
+  }
+
+  protected plot(): TemplateResult {
+    const top = Math.max(0, ...this.bars.map((b) => b.value));
+    return html`<div class="bars" role="list" aria-label=${this.label || nothing}>
+      ${this.bars.map(
+        (b) => html`<div class="r" role="listitem" aria-label="${b.label} | ${this.format(b.value)}">
+          <span class="l" aria-hidden="true" title=${b.label}>${b.label}</span>
+          <span class="track" aria-hidden="true"><span class="bar" data-tone=${toneAttr(b.tone)}
+            style="width: ${top > 0 ? (100 * Math.max(0, b.value)) / top : 0}%"></span></span>
+          <span class="v" aria-hidden="true">${this.format(b.value)}</span></div>`,
+      )}
+    </div>`;
+  }
+
+  protected table(): TemplateResult {
+    return html`<table aria-label=${this.label || nothing}>
+      <tbody>${this.bars.map((b) => html`<tr><th scope="row">${b.label}</th><td>${this.format(b.value)}</td></tr>`)}</tbody>
+    </table>`;
+  }
+}
+
+declare global {
+  interface HTMLElementTagNameMap {
+    'cae-bar-chart': CaeBarChart;
+  }
+}

package/src/charts/base.ts

@@ -0,0 +1,188 @@
+// What every chart shares: its width, its words, a legend, the switch to a table of
+// its values, and the tooltip of the item the reader points at or moves to.
+import { LitElement, css, html, nothing, type TemplateResult } from 'lit';
+import { property, state } from 'lit/decorators.js';
+import { withDefaults } from '../core/strings.js';
+import { legend, legendStyles, type LegendItem } from '../primitives/legend.js';
+import { base } from '../styles/index.js';
+import { plainNumber } from './scale.js';
+import { DEFAULT_CHART_STRINGS, type ChartStrings, type ValueText } from './types.js';
+
+/** The size of the axis labels, in px. */
+const AXIS_PX = 10.5;
+/** The room beside a label, in px, so that labels side by side do not touch. */
+const LABEL_ROOM = 6;
+
+let measurer: CanvasRenderingContext2D | null | undefined;
+const measured = new Map<string, number>();
+
+/** `text`'s width in px in the CSS font `font`; where there is no canvas to measure it, an estimate. */
+function measureText(text: string, font: string): number {
+  measurer ??= typeof document === 'undefined' ? null : document.createElement('canvas').getContext('2d');
+  if (!measurer) return text.length * AXIS_PX * 0.62;
+  const key = `${font}\n${text}`;
+  let w = measured.get(key);
+  if (w === undefined) {
+    measurer.font = font;
+    w = measurer.measureText(text).width;
+    measured.set(key, w);
+  }
+  return w;
+}
+
+export abstract class ChartElement extends LitElement {
+  static override styles = [
+    base,
+    legendStyles,
+    css`
+      :host { display: block; min-width: 0; }
+      .head { display: flex; align-items: flex-start; gap: 12px; margin-bottom: 8px; min-height: 22px; }
+      .head .legend { flex: 1; min-width: 0; }
+      .head .legend span { color: var(--text-2); }
+      .switch { margin-left: auto; flex: none; background: none; border: 1px solid var(--line); border-radius: 999px; padding: 2px 10px;
+        font: inherit; font-size: var(--font-size-sm); color: var(--text-muted); cursor: pointer; }
+      .switch:hover, .switch:focus-visible { color: var(--text); border-color: var(--line2); }
+      .plot { position: relative; outline-offset: 2px; }
+      .plot:focus-visible { outline: 2px solid var(--accent); border-radius: var(--radius-sm); }
+      svg { display: block; overflow: visible; }
+      .axis { font-size: ${AXIS_PX}px; fill: var(--text-muted); font-variant-numeric: tabular-nums; }
+      .grid { stroke: var(--line); stroke-width: 1; shape-rendering: crispEdges; }
+      .base { stroke: var(--line2); stroke-width: 1; shape-rendering: crispEdges; }
+      .hit { fill: transparent; }
+      .band { fill: var(--text); opacity: 0.05; }
+      .tip { position: absolute; z-index: 2; pointer-events: none; padding: 6px 9px; border-radius: var(--radius-sm); background: var(--raise);
+        border: 1px solid var(--line2); box-shadow: 0 4px 14px var(--shadow); color: var(--text); font-size: var(--font-size-sm);
+        white-space: nowrap; line-height: 1.45; }
+      .tip b { font-weight: 600; }
+      .tip .row { display: flex; align-items: center; gap: 6px; }
+      .tip .row i { width: 9px; height: 9px; border-radius: 2px; flex: none; }
+      .tip .row .v { margin-left: auto; padding-left: 12px; font-variant-numeric: tabular-nums; }
+      .scale { display: inline-flex; gap: 1px; margin-right: 6px; vertical-align: -1px; }
+      .legend .scale i { width: 12px; height: 10px; margin: 0; border-radius: 2px; }
+      .empty { padding: 18px 0; color: var(--text-muted); font-size: var(--font-size-sm); }
+      table { border-collapse: collapse; font-size: var(--font-size-sm); font-variant-numeric: tabular-nums; }
+      .tbl { overflow-x: auto; max-width: 100%; }
+      th, td { padding: 4px 12px 4px 0; text-align: right; white-space: nowrap; border-bottom: 1px solid var(--line); }
+      th { color: var(--text-muted); font-weight: 500; }
+      th:first-child, td:first-child { text-align: left; }
+      td { color: var(--text-2); }
+    `,
+  ];
+
+  /** The chart's accessible name (its title, or what it shows). */
+  @property() label = '';
+  /** A value in words: the host's format for the chart's unit. */
+  @property({ attribute: false }) format: ValueText = plainNumber;
+  @property({ attribute: false }) strings: Partial<ChartStrings> = {};
+  /** The plot's height in px (the axis included). */
+  @property({ type: Number }) height = 200;
+
+  /** The width the chart has, in px. */
+  @state() protected width = 0;
+  /** The values shown as a table instead of the chart. */
+  @state() protected asTable = false;
+  /** The item the reader points at or moved to with the keys; null: none. */
+  @state() protected active: number | null = null;
+
+  private resized: ResizeObserver | null = null;
+
+  protected get words(): ChartStrings {
+    return withDefaults(DEFAULT_CHART_STRINGS, this.strings);
+  }
+
+  override connectedCallback(): void {
+    super.connectedCallback();
+    if (typeof ResizeObserver === 'undefined') return;
+    this.resized ??= new ResizeObserver((entries) => {
+      const w = Math.floor(entries[0]?.contentRect.width ?? 0);
+      if (w && Math.abs(w - this.width) >= 1) this.width = w;
+    });
+    this.resized.observe(this);
+    document.fonts?.addEventListener('loadingdone', this.fontsLoaded);
+  }
+
+  override disconnectedCallback(): void {
+    super.disconnectedCallback();
+    this.resized?.disconnect();
+    document.fonts?.removeEventListener('loadingdone', this.fontsLoaded);
+  }
+
+  /** A font that loads late changes the labels' widths: they are measured again. */
+  private readonly fontsLoaded = (): void => {
+    measured.clear();
+    this.requestUpdate();
+  };
+
+  /** An axis label's width in px, as the chart draws it, with room beside it: measured in the chart's font. */
+  protected labelWidth(text: string): number {
+    const cs = getComputedStyle(this);
+    return Math.ceil(measureText(text, `${cs.fontStyle} ${cs.fontWeight} ${AXIS_PX}px ${cs.fontFamily}`)) + LABEL_ROOM;
+  }
+
+  protected override firstUpdated(): void {
+    if (!this.width) this.width = Math.floor(this.getBoundingClientRect().width) || 600;
+  }
+
+  /** The plot area's width: the element's, never less than a narrow screen's. */
+  protected get plotWidth(): number {
+    return Math.max(240, this.width || 600);
+  }
+
+  /** Whether there is anything to draw. */
+  protected abstract hasValues(): boolean;
+  /** The legend's entries: none for a single series, whose title names it. */
+  protected abstract legendItems(): LegendItem[];
+  /** How many items the keys move between. */
+  protected abstract itemCount(): number;
+  /** How many items the up and down keys move by: a row of a grid; 1 for a row of items. */
+  protected rowLength(): number {
+    return 1;
+  }
+  protected abstract plot(): TemplateResult;
+  protected abstract table(): TemplateResult;
+
+  override render() {
+    const s = this.words;
+    if (!this.hasValues()) return html`<div class="empty" part="empty">${s.empty}</div>`;
+    const items = this.legendItems();
+    return html`<div class="head">
+        ${items.length ? legend(items, { label: this.label }) : html`<span class="legend"></span>`}
+        <button type="button" class="switch" part="switch" aria-pressed=${this.asTable}
+          @click=${() => ((this.asTable = !this.asTable), (this.active = null))}>${this.asTable ? s.showChart : s.showTable}</button>
+      </div>
+      ${this.asTable
+        ? html`<div class="tbl" part="table">${this.table()}</div>`
+        : html`<div class="plot" part="plot" tabindex=${this.itemCount() ? 0 : nothing} role="group" aria-label=${this.label || nothing}
+            @keydown=${this.onKey} @blur=${() => (this.active = null)} @mouseleave=${() => (this.active = null)}>${this.plot()}</div>`}`;
+  }
+
+  /** The arrow keys move between the items (up and down by a row of a grid), Home and End to the first and the last; Escape hides the tooltip. */
+  private readonly onKey = (e: KeyboardEvent): void => {
+    const n = this.itemCount();
+    if (!n) return;
+    const at = this.active;
+    let next: number | null = at;
+    const row = this.rowLength();
+    const by = e.key === 'ArrowRight' ? 1 : e.key === 'ArrowLeft' ? -1 : e.key === 'ArrowDown' ? row : e.key === 'ArrowUp' ? -row : 0;
+    if (by) next = at === null ? (by > 0 ? 0 : n - 1) : Math.min(n - 1, Math.max(0, at + by));
+    else if (e.key === 'Home') next = 0;
+    else if (e.key === 'End') next = n - 1;
+    else if (e.key === 'Escape') next = null;
+    else return;
+    e.preventDefault();
+    this.active = next;
+  };
+
+  /** A tooltip at `left` px (its middle) and `top` px of the plot, kept inside it. */
+  protected tip(left: number, top: number, body: TemplateResult): TemplateResult {
+    const w = this.plotWidth;
+    const side = left > w * 0.6 ? 'right' : 'left';
+    const x = side === 'left' ? Math.max(0, left + 12) : Math.max(0, w - left + 12);
+    return html`<div class="tip" role="status" style="${side}: ${x}px; top: ${Math.max(0, top)}px">${body}</div>`;
+  }
+
+  /** One line of a tooltip: a swatch, a name and its value. */
+  protected tipRow(colour: string | null, name: string, value: string): TemplateResult {
+    return html`<div class="row">${colour ? html`<i style="background: ${colour}"></i>` : nothing}<span>${name}</span><span class="v">${value}</span></div>`;
+  }
+}