@contraagent/elements 0.0.0-stage → 0.2.0

package/src/charts/state-grid.ts

@@ -0,0 +1,245 @@
+import { css, html, nothing, svg, type TemplateResult } from 'lit';
+import { property } from 'lit/decorators.js';
+import type { Tone } from '../core/tone.js';
+import type { LegendItem } from '../primitives/legend.js';
+import { ChartElement } from './base.js';
+import { LABEL_GAP, labelStride } from './scale.js';
+
+/** One cell of a state grid: its state in words, the tone that colours it, and a fact of its own for the tooltip. */
+export interface StateCell {
+  label: string;
+  tone: Tone;
+  tip?: string | null;
+}
+
+const CELL_H = 22;
+const GAP = 2;
+const M = { top: 2, right: 2, bottom: 22 };
+/** The narrowest cell that still holds its mark. */
+const MARK_MIN = 14;
+
+/**
+ * A tone's fill: a failure and what needs attention stand out, a cell that ended well
+ * stays quiet, so the exceptions are what the eye finds first.
+ */
+export function stateFill(tone: Tone): string {
+  switch (tone) {
+    case 'failed':
+      return 'color-mix(in srgb, var(--status-failed) 72%, var(--card))';
+    case 'attention':
+      return 'color-mix(in srgb, var(--status-attention) 68%, var(--card))';
+    case 'running':
+      return 'color-mix(in srgb, var(--status-running) 60%, var(--card))';
+    case 'done':
+      return 'color-mix(in srgb, var(--status-done) 30%, var(--card))';
+    case 'muted':
+      return 'color-mix(in srgb, var(--text-muted) 26%, var(--card))';
+    default:
+      return 'color-mix(in srgb, var(--text) 12%, var(--card))';
+  }
+}
+
+/** The mark a tone takes in a cell, beside its colour: ✓ done, ✕ failed, ◌ attention; none for the others. */
+export function stateMark(tone: Tone): string {
+  return tone === 'done' ? '✓' : tone === 'failed' ? '✕' : tone === 'attention' ? '◌' : '';
+}
+
+/** The order of the tones in a legend: the exceptions first, what ended well after. */
+const TONE_ORDER: readonly Tone[] = ['failed', 'attention', 'running', 'done', 'muted', 'neutral'];
+
+/** The textures that tell the states of one tone apart, after the first (plain): stripes, dots, crosshatch, lines. */
+export const TEXTURES = ['', 'stripes', 'dots', 'cross', 'lines'] as const;
+export type Texture = (typeof TEXTURES)[number];
+
+/** Each state's texture, by `tone` and `label`: the first state of a tone plain, the next ones in `TEXTURES` order (again from the start past the fifth). */
+export function texturesOf(states: readonly StateCell[]): Map<string, Texture> {
+  const n = new Map<Tone, number>();
+  const out = new Map<string, Texture>();
+  for (const s of states) {
+    const i = n.get(s.tone) ?? 0;
+    n.set(s.tone, i + 1);
+    out.set(stateKey(s), TEXTURES[i % TEXTURES.length]!);
+  }
+  return out;
+}
+
+const stateKey = (c: StateCell): string => `${c.tone}\u0000${c.label}`;
+
+/** A texture as a CSS background over a legend key's fill. */
+function textureCss(t: Texture): string {
+  const ink = 'color-mix(in srgb, var(--text) 45%, transparent)';
+  switch (t) {
+    case 'stripes':
+      return `repeating-linear-gradient(45deg, ${ink} 0 1.5px, transparent 1.5px 4px)`;
+    case 'dots':
+      return `radial-gradient(${ink} 1px, transparent 1.3px) 0 0 / 4px 4px`;
+    case 'cross':
+      return `repeating-linear-gradient(45deg, ${ink} 0 1px, transparent 1px 4px), repeating-linear-gradient(-45deg, ${ink} 0 1px, transparent 1px 4px)`;
+    case 'lines':
+      return `repeating-linear-gradient(0deg, ${ink} 0 1.5px, transparent 1.5px 4px)`;
+    default:
+      return '';
+  }
+}
+
+/** Each state of the cells once: by tone (failed, attention, running, done, muted, neutral), then in the order the cells first give it. */
+export function statesOf(cells: readonly (readonly (StateCell | null | undefined)[])[]): StateCell[] {
+  const seen = new Map<string, StateCell>();
+  for (const row of cells) for (const c of row) if (c && !seen.has(stateKey(c))) seen.set(stateKey(c), c);
+  return [...seen.values()].sort((a, b) => TONE_ORDER.indexOf(a.tone) - TONE_ORDER.indexOf(b.tone));
+}
+
+/**
+ * A state per row (`y`) and column (`x`), each cell coloured by its tone
+ * (`cells[row][column]`; a null cell is left empty): the states of hourly runs by day,
+ * say. The colour is never alone: a cell wide enough holds its tone's mark (✓ ✕ ◌), the
+ * states of one tone differ by a texture (the first plain, then stripes, dots,
+ * crosshatch, lines), the legend names every state with its texture, and pointing at a cell, or moving to it with the arrow keys
+ * (up and down by a row), shows its row, column, state and fact; the switch shows them
+ * all as a table of words.
+ *
+ * @tagname cae-state-grid
+ * @csspart plot - the grid
+ * @csspart table - the table of its states
+ * @csspart switch - the button between the two
+ * @csspart empty - what it shows with no cells
+ * @csspart legend - the legend
+ */
+export class CaeStateGrid extends ChartElement {
+  static override styles = [
+    ...ChartElement.styles,
+    css`
+      .mark { font-size: 11px; font-weight: 700; fill: var(--text); pointer-events: none; }
+      /* a cell that ended well keeps its mark, quietly: the exceptions are what the eye finds */
+      .mark.quiet { font-weight: 400; fill: var(--text-muted); }
+      .legend .key { display: inline-grid; place-items: center; width: 14px; height: 14px; margin-right: 6px; border-radius: 3px;
+        font-size: 9.5px; font-weight: 700; color: var(--text); vertical-align: -2px; }
+    `,
+  ];
+
+  @property({ attribute: false }) x: readonly string[] = [];
+  @property({ attribute: false }) y: readonly string[] = [];
+  @property({ attribute: false }) cells: readonly (readonly (StateCell | null)[])[] = [];
+
+  protected hasValues(): boolean {
+    return this.x.length > 0 && this.y.length > 0 && this.cells.some((r) => r.some((c) => !!c));
+  }
+
+  protected legendItems(): LegendItem[] {
+    const states = statesOf(this.cells);
+    const textures = texturesOf(states);
+    return states.map((s) => {
+      const t = textureCss(textures.get(stateKey(s)) ?? '');
+      return {
+        label: s.label,
+        icon: html`<span class="key" aria-hidden="true" data-texture=${textures.get(stateKey(s)) || nothing}
+          style="background: ${t ? `${t}, ` : ''}${stateFill(s.tone)}">${stateMark(s.tone)}</span>`,
+      };
+    });
+  }
+
+  protected itemCount(): number {
+    return this.x.length * this.y.length;
+  }
+
+  protected override rowLength(): number {
+    return this.x.length;
+  }
+
+  protected plot(): TemplateResult {
+    const nx = this.x.length;
+    const ny = this.y.length;
+    const left = Math.max(...this.y.map((s) => this.labelWidth(s))) + 2;
+    const w = this.plotWidth;
+    const pw = w - left - M.right;
+    const cw = pw / nx;
+    const h = M.top + ny * CELL_H + M.bottom;
+    const stride = labelStride(nx, pw, Math.max(...this.x.map((s) => this.labelWidth(s))) + LABEL_GAP);
+    const a = this.active;
+    const marked = cw - GAP >= MARK_MIN;
+    const textures = texturesOf(statesOf(this.cells));
+    const cells: TemplateResult[] = [];
+    for (let r = 0; r < ny; r++)
+      for (let c = 0; c < nx; c++) {
+        const cell = this.cells[r]?.[c];
+        const x = left + c * cw;
+        const y = M.top + r * CELL_H;
+        const i = r * nx + c;
+        const box = { x: x + GAP / 2, y: y + GAP / 2, w: Math.max(1, cw - GAP), h: CELL_H - GAP };
+        if (!cell) {
+          cells.push(svg`<rect x=${box.x} y=${box.y} width=${box.w} height=${box.h} rx="2" fill="none" stroke="var(--line)"
+            @mouseenter=${() => (this.active = i)}></rect>`);
+          continue;
+        }
+        const mark = marked ? stateMark(cell.tone) : '';
+        const texture = textures.get(stateKey(cell)) ?? '';
+        cells.push(svg`<g @mouseenter=${() => (this.active = i)}>
+          <rect x=${box.x} y=${box.y} width=${box.w} height=${box.h} rx="2" fill=${stateFill(cell.tone)}
+            stroke=${a === i ? 'var(--text)' : 'none'} stroke-width="1.5"></rect>
+          ${texture ? svg`<rect class="texture" data-texture=${texture} x=${box.x} y=${box.y} width=${box.w} height=${box.h} rx="2" fill=${`url(#${this.patternId(texture)})`} pointer-events="none"></rect>` : nothing}
+          ${mark ? svg`<text class=${cell.tone === 'done' ? 'mark quiet' : 'mark'} x=${box.x + box.w / 2} y=${box.y + box.h / 2} dy="0.35em" text-anchor="middle" aria-hidden="true">${mark}</text>` : nothing}
+        </g>`);
+      }
+    const at = a !== null && a < nx * ny ? { r: Math.floor(a / nx), c: a % nx } : null;
+    return html`<svg width=${w} height=${h} role="img" aria-label=${this.label || nothing}>
+        ${this.patterns(new Set(textures.values()))}
+        ${this.y.map((label, r) => svg`<text class="axis" x=${left - 6} y=${M.top + r * CELL_H + CELL_H / 2} dy="0.32em" text-anchor="end">${label}</text>`)}
+        ${cells}
+        ${this.x.map((label, c) =>
+          c % stride === 0 ? svg`<text class="axis" x=${left + c * cw + cw / 2} y=${h - 6} text-anchor="middle">${label}</text>` : nothing,
+        )}
+      </svg>
+      ${at ? this.tip(left + at.c * cw + cw / 2, M.top + (at.r + 1) * CELL_H, this.tipBody(at.r, at.c)) : nothing}`;
+  }
+
+  /** One id per element and texture: two grids in a page keep their own patterns. */
+  private readonly uid = `sg${Math.random().toString(36).slice(2, 8)}`;
+
+  private patternId(t: Texture): string {
+    return `${this.uid}-${t}`;
+  }
+
+  /** The SVG patterns of the textures in use, drawn in the text's colour over a cell's fill. */
+  private patterns(used: ReadonlySet<Texture>): TemplateResult {
+    const line = (d: string) => svg`<path d=${d} stroke="var(--text)" stroke-opacity="0.45" stroke-width="1.2"></path>`;
+    const body = (t: Texture) =>
+      t === 'stripes'
+        ? line('M-1 1 L1 -1 M0 5 L5 0 M4 6 L6 4')
+        : t === 'dots'
+          ? svg`<circle cx="2.5" cy="2.5" r="0.9" fill="var(--text)" fill-opacity="0.5"></circle>`
+          : t === 'cross'
+            ? line('M0 0 L5 5 M5 0 L0 5')
+            : line('M0 2.5 L5 2.5');
+    return svg`<defs>${[...used].filter((t) => t).map(
+      (t) => svg`<pattern id=${this.patternId(t)} width="5" height="5" patternUnits="userSpaceOnUse">${body(t)}</pattern>`,
+    )}</defs>`;
+  }
+
+  private tipBody(r: number, c: number): TemplateResult {
+    const cell = this.cells[r]?.[c];
+    return html`<b>${this.y[r]} | ${this.x[c]}</b>
+      <div class="row">${cell
+        ? html`<i style="background: ${stateFill(cell.tone)}"></i><span>${cell.label}</span>`
+        : html`<span>${this.words.none}</span>`}</div>
+      ${cell?.tip ? html`<div class="row"><span>${cell.tip}</span></div>` : nothing}`;
+  }
+
+  protected table(): TemplateResult {
+    const none = this.words.none;
+    return html`<table aria-label=${this.label || nothing}>
+      <thead><tr><th scope="col">${this.words.label}</th>${this.x.map((l) => html`<th scope="col">${l}</th>`)}</tr></thead>
+      <tbody>${this.y.map(
+        (label, r) => html`<tr><th scope="row">${label}</th>${this.x.map((_, c) => {
+          const cell = this.cells[r]?.[c];
+          return html`<td title=${cell?.tip || nothing}>${cell ? cell.label : none}</td>`;
+        })}</tr>`,
+      )}</tbody>
+    </table>`;
+  }
+}
+
+declare global {
+  interface HTMLElementTagNameMap {
+    'cae-state-grid': CaeStateGrid;
+  }
+}

package/src/charts/types.ts

@@ -0,0 +1,48 @@
+// What the charts take: plain series of numbers, and their words.
+import type { Tone } from '../core/tone.js';
+
+/** One series: a value per label of the chart's `x`, in that order; null where it has none. */
+export interface ChartSeries {
+  name: string;
+  values: readonly (number | null)[];
+}
+
+/** One horizontal bar: its label and value; `tone` gives it a status colour. */
+export interface ChartBar {
+  label: string;
+  value: number;
+  tone?: Tone;
+}
+
+/** A number in words (`$1.20`, `42%`, `2m 05s`): the host's format for the chart's unit. */
+export type ValueText = (value: number) => string;
+
+/** The words of a chart. */
+export interface ChartStrings {
+  /** What a chart with nothing to draw says. */
+  empty: string;
+  /** The button that shows the values as a table, and the one that shows the chart again. */
+  showTable: string;
+  showChart: string;
+  /** The column of a table view that holds the labels of `x` (or of the bars). */
+  label: string;
+  /** The name of the series past the sixth, folded into one. */
+  other: string;
+  /** The sum of a label's stacked series. */
+  total: string;
+  /** A value a series has not (null). */
+  none: string;
+  /** The heatmap's colour scale: its lowest and highest value. */
+  scale: (low: string, high: string) => string;
+}
+
+export const DEFAULT_CHART_STRINGS: ChartStrings = {
+  empty: 'No values',
+  showTable: 'Show table',
+  showChart: 'Show chart',
+  label: 'Label',
+  other: 'Other',
+  total: 'Total',
+  none: '—',
+  scale: (low, high) => `${low} to ${high}`,
+};

package/src/checks/check-table.ts

@@ -0,0 +1,85 @@
+import { LitElement, html, nothing, type TemplateResult } from 'lit';
+import { property } from 'lit/decorators.js';
+import { withDefaults } from '../core/strings.js';
+import { base } from '../styles/index.js';
+import { checkTableStyles, verdictStyles } from './styles.js';
+import { DEFAULT_CHECK_TABLE_STRINGS, type CheckRow, type CheckTableStrings, type Verdict } from './types.js';
+
+/**
+ * A verdict in words (`.verdict`, `data-verdict`; `verdictStyles`): ✓ before a
+ * pass, ✕ before a failure, hidden from screen readers, which read the word.
+ * Nothing for `none` without a word.
+ */
+export function verdict(v: Verdict, label: string, tip = ''): TemplateResult | typeof nothing {
+  if (v === 'none' && !label) return nothing;
+  const mark = v === 'pass' ? '✓' : v === 'fail' ? '✕' : '';
+  return html`<span class="verdict" part="verdict" data-verdict=${v} title=${tip || nothing}>${mark
+    ? html`<span aria-hidden="true">${mark}</span> `
+    : nothing}${label}</span>`;
+}
+
+const cut = (s: string, n: number) => (s.length > n ? `${s.slice(0, n)}…` : s);
+
+/** A value in a line: a string quoted and cut, a list's length and first items, an object's first keys. */
+function shortValue(v: unknown, s: CheckTableStrings): TemplateResult {
+  if (v === undefined) return html`<span class="jdim">—</span>`;
+  if (typeof v === 'string') return html`<span class="js" title=${v}>"${cut(v, 90)}"</span>`;
+  if (Array.isArray(v)) {
+    const head = v
+      .slice(0, 3)
+      .map((x) => (typeof x === 'string' ? `"${cut(x, 28)}"` : JSON.stringify(x)))
+      .join(', ');
+    return html`<span class="jn">${s.items(v.length)}</span>
+      <span class="jdim">${head}${v.length > 3 ? ', …' : ''}</span>`;
+  }
+  if (v !== null && typeof v === 'object') return html`<span class="jn">${s.object}</span> <span class="jdim">${Object.keys(v).slice(0, 4).join(', ')}</span>`;
+  return html`<span class="jn">${JSON.stringify(v)}</span>`;
+}
+
+/**
+ * Named values checked one by one: a row per name, with what it must be, what
+ * it is and the verdict. Without `showValues`, only the names and what each
+ * must be (nothing to check them against).
+ *
+ * @tagname cae-check-table
+ * @csspart table - the `<table>`
+ * @csspart row - each row of a name
+ * @csspart verdict - each verdict
+ */
+export class CaeCheckTable extends LitElement {
+  static override styles = [base, verdictStyles, checkTableStyles];
+
+  @property({ attribute: false }) rows: readonly CheckRow[] = [];
+  /** Show the values and the verdicts. */
+  @property({ type: Boolean }) showValues = true;
+  @property({ attribute: false }) strings: Partial<CheckTableStrings> = {};
+
+  override render() {
+    const s = withDefaults(DEFAULT_CHECK_TABLE_STRINGS, this.strings);
+    const all = this.showValues;
+    return html`<table part="table">
+      <thead><tr>
+        <th scope="col">${s.name}</th><th scope="col">${s.expected}</th>
+        ${all ? html`<th scope="col">${s.actual}</th><th scope="col">${s.verdict}</th>` : nothing}
+      </tr></thead>
+      <tbody>
+        ${this.rows.map(
+          (r) => html`<tr part="row">
+            <td class="jmono">${r.name}</td>
+            <td class=${r.extra ? 'jdim' : 'jmono jdim'}>${r.expected}${r.optional ? html` <i>${s.optional}</i>` : nothing}</td>
+            ${all
+              ? html`<td class="value">${shortValue(r.hasValue ? r.value : undefined, s)}</td>
+                  <td>${verdict(r.verdict, r.verdictLabel, r.tip)}</td>`
+              : nothing}
+          </tr>`,
+        )}
+      </tbody>
+    </table>`;
+  }
+}
+
+declare global {
+  interface HTMLElementTagNameMap {
+    'cae-check-table': CaeCheckTable;
+  }
+}

package/src/checks/index.ts

@@ -0,0 +1,5 @@
+// Values checked one by one: `@contraagent/elements/check-table`.
+// `CaeCheckTable` is registered by `@contraagent/elements/check-table/define`.
+export * from './types.js';
+export * from './styles.js';
+export * from './check-table.js';

package/src/checks/styles.ts

@@ -0,0 +1,31 @@
+// The look of `<cae-check-table>`, and of a verdict (`verdict()`) wherever a
+// host shows one.
+import { css } from 'lit';
+
+/** A verdict: ✓ and its word quiet, ✕ and its word in the failed tone, a warning in the attention tone. */
+export const verdictStyles = css`
+  .verdict { font-size: 12px; }
+  .verdict[data-verdict='pass'] { color: var(--text-2); }
+  .verdict[data-verdict='pass'] > [aria-hidden] { color: var(--status-done); font-weight: 700; }
+  .verdict[data-verdict='fail'] { color: var(--status-failed); font-weight: 600; }
+  .verdict[data-verdict='warn'] { color: var(--status-attention); }
+  .verdict[data-verdict='none'] { color: var(--text-muted); }
+`;
+
+/** Sized to its content, so a verdict sits next to the value it judges; a long value wraps. */
+export const checkTableStyles = css`
+  :host { display: block; max-width: 100%; }
+  table { width: auto; max-width: 100%; border-collapse: collapse; }
+  th { text-align: left; font-size: 11.5px; color: var(--text-muted);
+    font-weight: 600; padding: 4px 20px 4px 0; border-bottom: 1px solid var(--line); }
+  td { padding: 5px 20px 5px 0; border: 0; border-bottom: 1px solid var(--line); vertical-align: baseline; font-size: 12.5px; }
+  th:last-child, td:last-child { padding-right: 0; }
+  td.value { overflow-wrap: anywhere; }
+  tbody tr:last-child td { border-bottom: 0; }
+  /* a name stays on one line while the table has the room, and breaks where it must */
+  td:first-child { font-weight: 600; overflow-wrap: anywhere; }
+  td:last-child { white-space: nowrap; }
+  i { font-style: normal; color: var(--text-muted); font-size: 11px; margin-left: 4px; }
+  .js { color: var(--code-string); }
+  .jn { color: var(--code-number); }
+`;

package/src/checks/types.ts

@@ -0,0 +1,48 @@
+// What `<cae-check-table>` shows: a row per named value, what it must be, what
+// it is, and the verdict.
+
+/** A check's result: passed, failed, a warning, or no verdict (a word may still say why). */
+export type Verdict = 'pass' | 'fail' | 'warn' | 'none';
+
+export interface CheckRow {
+  /** What is checked: a field's name. */
+  name: string;
+  /** What it must be: a type, in code; with `extra`, a phrase. */
+  expected: string;
+  /** It may be absent: "optional" follows `expected`. */
+  optional?: boolean;
+  /** Not one of the expected names: `expected` is a phrase, not code. */
+  extra?: boolean;
+  /** The value was found (`value`, possibly undefined or null); else "—". */
+  hasValue: boolean;
+  value?: unknown;
+  verdict: Verdict;
+  /** The verdict in words; '' with `none` for an empty cell. */
+  verdictLabel: string;
+  /** The verdict's tooltip. */
+  tip?: string;
+}
+
+export interface CheckTableStrings {
+  /** The header of the names. */
+  name: string;
+  expected: string;
+  /** The header of the values. */
+  actual: string;
+  verdict: string;
+  optional: string;
+  /** A list's length. */
+  items: (n: number) => string;
+  /** An object's summary, before its first keys. */
+  object: string;
+}
+
+export const DEFAULT_CHECK_TABLE_STRINGS: CheckTableStrings = {
+  name: 'Name',
+  expected: 'Expected',
+  actual: 'Value',
+  verdict: 'Check',
+  optional: 'optional',
+  items: (n) => (n === 1 ? '1 item' : `${n} items`),
+  object: 'object',
+};

package/src/code/code.ts

@@ -0,0 +1,199 @@
+import { LitElement, css, html, nothing, type PropertyValues } from 'lit';
+import { property, state } from 'lit/decorators.js';
+import { unsafeHTML } from 'lit/directives/unsafe-html.js';
+import { withDefaults } from '../core/strings.js';
+import { base, prose } from '../styles/index.js';
+import { languageOf, tokenLines, tokenize, tokensHtml } from './highlight.js';
+
+/** A line marked in a text: its number, or the first and the last of a range, both included. */
+export type LineMark = number | readonly [number, number];
+
+export interface CodeStrings {
+  /** The button that copies the whole text. */
+  copy: string;
+  /** What the copy button says for a moment after the text was copied. */
+  copied: string;
+  /** The switch between long lines wrapped and scrolled sideways. */
+  wrap: string;
+  /** What a text with no characters shows. */
+  empty: string;
+  /** The note under a text cut short: the lines shown of all its lines. */
+  cut: (shown: number, total: number) => string;
+}
+
+export const DEFAULT_CODE_STRINGS: Readonly<CodeStrings> = {
+  copy: 'Copy',
+  copied: 'Copied',
+  wrap: 'Wrap lines',
+  empty: 'No text',
+  cut: (shown, total) => `First ${shown.toLocaleString('en')} of ${total.toLocaleString('en')} lines`,
+};
+
+/** What of a text is shown. */
+export interface ShownText {
+  /** The text shown: its first lines. */
+  shown: string;
+  /** The number of lines shown. */
+  lines: number;
+  /** The number of lines of the whole text (a last line break ends the last line). */
+  total: number;
+  /** Less than the whole text is shown. */
+  cut: boolean;
+}
+
+/**
+ * The first lines of `text`: at most `maxLines` lines and `maxCharacters` characters, cut
+ * at the end of a line (a first line longer than that is cut inside it).
+ */
+export function shownText(text: string, maxLines: number, maxCharacters: number): ShownText {
+  const all = text.endsWith('\n') ? text.slice(0, -1) : text;
+  let total = all || text ? 1 : 0;
+  for (let i = all.indexOf('\n'); i >= 0; i = all.indexOf('\n', i + 1)) total++;
+  let end = 0;
+  let lines = 0;
+  while (lines < Math.max(1, maxLines)) {
+    const next = all.indexOf('\n', end);
+    const stop = next < 0 ? all.length : next;
+    if (lines > 0 && stop > maxCharacters) break;
+    lines++;
+    if (next < 0) {
+      end = all.length;
+      break;
+    }
+    end = next + 1;
+  }
+  let shown = lines >= total ? all : all.slice(0, end - 1);
+  if (shown.length > maxCharacters) shown = shown.slice(0, maxCharacters);
+  return { shown, lines: total ? lines : 0, total, cut: shown.length < all.length };
+}
+
+/** Whether line `n` is in one of `marks`. */
+export function isMarked(marks: readonly LineMark[], n: number): boolean {
+  return marks.some((m) => (typeof m === 'number' ? m === n : n >= m[0] && n <= m[1]));
+}
+
+/**
+ * A text shown as code: highlighted by its `language` (`LANGUAGES`, another name of one
+ * or a file name; anything else is plain), each line numbered from `start`, the lines of
+ * `highlight` marked (a bar beside the number and a tint). Long lines scroll sideways,
+ * or wrap with `wrap` or the reader's switch. A text of more than `maxLines` lines or
+ * `maxCharacters` characters shows its first lines and says how many it has; the copy
+ * button copies the whole text. The line numbers are not part of a selection.
+ *
+ * @tagname cae-code
+ * @csspart header - the path, the language and the buttons
+ * @csspart code - the lines, which scroll
+ * @csspart cut - the note under a text cut short
+ */
+export class CaeCode extends LitElement {
+  static override styles = [
+    base,
+    prose,
+    css`
+      :host { display: block; border: 1px solid var(--line); border-radius: var(--radius-md); background: var(--well); overflow: hidden; }
+      .head { display: flex; flex-wrap: wrap; align-items: center; gap: 4px 8px; padding: 4px 6px 4px 10px; border-bottom: 1px solid var(--line); font-size: var(--font-size-sm); color: var(--text-2); }
+      .path { font-family: var(--mono); overflow: hidden; text-overflow: ellipsis; white-space: nowrap; min-width: 0; }
+      .lang { color: var(--text-muted); }
+      .tools { margin-left: auto; display: flex; gap: 4px; flex: none; }
+      .tools button { font-size: var(--font-size-sm); color: var(--text-2); border: 1px solid var(--line2); border-radius: var(--radius-pill); padding: 0 9px; cursor: pointer; background: none; }
+      .tools button[aria-pressed='true'] { background: var(--raise); color: var(--text); }
+      .scroll { overflow: auto; max-height: var(--cae-code-max-height, 70vh); font-family: var(--mono); font-size: var(--font-size-md); line-height: 1.5; }
+      .lines { display: block; min-width: max-content; padding: 4px 0; }
+      .wrap .lines { min-width: 0; }
+      .ln { display: flex; }
+      /* the number is the line's own: drawn by CSS, so a selection of lines copies no numbers */
+      .ln::before { content: attr(data-n); position: sticky; left: 0; flex: none; box-sizing: border-box; width: calc(var(--digits) * 1ch + 22px);
+        padding: 0 10px 0 8px; text-align: right; color: var(--text-muted); background: var(--well); border-left: 3px solid transparent; }
+      .t { flex: 1; white-space: pre; padding-right: 12px; }
+      .t:empty::after { content: ' '; }
+      .wrap .t { white-space: pre-wrap; overflow-wrap: anywhere; }
+      .ln[data-mark] { background: color-mix(in srgb, var(--accent) 6%, transparent); }
+      .hl-doc { opacity: 1; }
+      .ln[data-mark]::before { border-left-color: var(--accent); color: var(--text); background: color-mix(in srgb, var(--accent) 14%, var(--well)); }
+      .cut, .empty { padding: 4px 10px; font-size: var(--font-size-sm); color: var(--text-muted); border-top: 1px solid var(--line); }
+      .empty { border-top: 0; }
+    `,
+  ];
+
+  /** The text. */
+  @property() code = '';
+  /** Its language: a name of `LANGUAGES`, another name of one, or a file name; anything else is plain text. */
+  @property() language = '';
+  /** The number of the first line. */
+  @property({ type: Number }) start = 1;
+  /** The lines marked, in the numbers shown. */
+  @property({ attribute: false }) highlight: readonly LineMark[] = [];
+  /** The file the text is, named over it. */
+  @property() path = '';
+  /** What the lines are named to a screen reader (default: the path). */
+  @property() label = '';
+  /** Long lines wrap at first; the reader's switch changes it. */
+  @property({ type: Boolean }) wrap = false;
+  /** The most lines shown. */
+  @property({ type: Number }) maxLines = 5000;
+  /** The most characters shown, at the end of a line. */
+  @property({ type: Number }) maxCharacters = 500_000;
+  /** The visible words; English by default. */
+  @property({ attribute: false }) strings: Partial<CodeStrings> = {};
+
+  @state() private wrapped = false;
+  @state() private copied = false;
+  private copiedTimer: ReturnType<typeof setTimeout> | undefined;
+
+  override willUpdate(changed: PropertyValues<this>): void {
+    if (changed.has('wrap')) this.wrapped = this.wrap;
+    if (changed.has('code')) this.copied = false;
+  }
+
+  override disconnectedCallback(): void {
+    super.disconnectedCallback();
+    clearTimeout(this.copiedTimer);
+  }
+
+  private async copy(): Promise<void> {
+    try {
+      await navigator.clipboard.writeText(this.code);
+    } catch {
+      return;
+    }
+    this.copied = true;
+    clearTimeout(this.copiedTimer);
+    this.copiedTimer = setTimeout(() => (this.copied = false), 1500);
+  }
+
+  override render() {
+    const s = withDefaults(DEFAULT_CODE_STRINGS, this.strings);
+    const lang = languageOf(this.language);
+    const { shown, lines, total, cut } = shownText(this.code, this.maxLines, this.maxCharacters);
+    const last = this.start + Math.max(lines, 1) - 1;
+    const rows = tokenLines(tokenize(shown, lang))
+      .map((line, i) => {
+        const n = this.start + i;
+        return `<div class="ln" data-n="${n}"${isMarked(this.highlight, n) ? ' data-mark=""' : ''}><span class="t">${tokensHtml(line)}</span></div>`;
+      })
+      .join('');
+    return html`<div class="head" part="header">
+        ${this.path ? html`<span class="path" title=${this.path}>${this.path}</span>` : nothing}
+        ${lang ? html`<span class="lang">${lang}</span>` : nothing}
+        <span class="tools">
+          <button type="button" aria-pressed=${this.wrapped ? 'true' : 'false'} @click=${() => (this.wrapped = !this.wrapped)}>${s.wrap}</button>
+          <button type="button" ?disabled=${!this.code} @click=${() => void this.copy()}>${this.copied ? s.copied : s.copy}</button>
+        </span>
+        <span class="sr" role="status">${this.copied ? s.copied : ''}</span>
+      </div>
+      ${this.code
+        ? html`<div class="scroll ${this.wrapped ? 'wrap' : ''}" part="code" data-scroll=${this.wrapped ? 'y' : 'x'} tabindex="0" role=${this.label || this.path ? 'region' : nothing}
+              aria-label=${this.label || this.path || nothing}
+              style="--digits: ${String(last).length}">
+              <code class="lines hl">${unsafeHTML(rows)}</code>
+            </div>
+            ${cut ? html`<div class="cut" part="cut">${s.cut(lines, total)}</div>` : nothing}`
+        : html`<div class="empty">${s.empty}</div>`}`;
+  }
+}
+
+declare global {
+  interface HTMLElementTagNameMap {
+    'cae-code': CaeCode;
+  }
+}