@contraagent/elements 0.0.0-stage → 0.1.0

package/src/matrix/mark-matrix.ts

@@ -0,0 +1,285 @@
+// A mark matrix: a row per series, a column per item, nested groups of columns
+// above them; only the rows in view above `windowAt` rows.
+import { LitElement, adoptStyles, html, nothing, type CSSResult, type PropertyValues } from 'lit';
+import { repeat } from 'lit/directives/repeat.js';
+import { emit } from '../core/events.js';
+import { withDefaults } from '../core/strings.js';
+import { toneAttr } from '../core/tone.js';
+import { icon } from '../primitives/icon.js';
+import type { StateStyles } from '../primitives/states.js';
+import { base, markStyles } from '../styles/index.js';
+import { gridStep } from './grid-step.js';
+import { ROW_H, matrixStyles } from './styles.js';
+import { DEFAULT_MARK_MATRIX_STRINGS, type MarkMatrixInput, type MarkMatrixStrings, type MatrixHeadCell, type MatrixMark, type MatrixRowInput } from './types.js';
+
+/** The rows drawn around those in view, when windowed. */
+const OVERSCAN = 30;
+
+const EMPTY: MarkMatrixInput = { caption: '', label: '', head: [], columns: [], rows: [] };
+
+/**
+ * A table of marks: a row per series (its label, then a value), a column per item,
+ * the columns under nested groups (a border where a group starts). A mark is
+ * drawn in its state's look (`states`). A click selects a mark (`cae-select`);
+ * a double click or Enter is its action (`cae-activate`, or `cae-drill` for a mark
+ * with an inner view). The arrow keys, Home, End, Page Up and Page Down move
+ * between the marks (Ctrl with Home and End: the first and the last row). The
+ * hovered, focused or selected mark's row is highlighted, else `highlight`'s. The
+ * host sorts the rows: the sort control sends `cae-sort`. Above `windowAt` rows,
+ * only the rows in view are drawn.
+ *
+ * @tagname cae-mark-matrix
+ * @fires cae-select - `{id}`: a mark was clicked or focused
+ * @fires cae-activate - `{id}`: a mark's action (a double click or Enter)
+ * @fires cae-drill - `{id}`: a mark's inner view (a double click or Enter on a mark with `drill`)
+ * @fires cae-sort - `{id, direction: 'asc'}`: an order was chosen
+ * @csspart matrix - the `<table>`
+ * @csspart head-cell - each header cell
+ * @csspart row-header - each row's label
+ * @csspart mark - each mark
+ * @csspart sort - the sort control
+ */
+export class CaeMarkMatrix extends LitElement {
+  static override styles = [base, markStyles, matrixStyles];
+  static override properties = {
+    matrix: { attribute: false },
+    states: { attribute: false },
+    selected: { attribute: false },
+    highlight: { attribute: false },
+    key: {},
+    windowAt: { type: Number },
+    strings: { attribute: false },
+    renderIcon: { attribute: false },
+    iconStyles: { attribute: false },
+    hover: { state: true },
+    scrollRow: { state: true },
+  };
+
+  matrix: MarkMatrixInput = EMPTY;
+  states: StateStyles = {};
+  /** The selected mark's id, or null. */
+  selected: string | null = null;
+  /** The row highlighted while no mark is hovered, focused or selected. */
+  highlight: string | null = null;
+  /** The matrix's identity: a new key is a new matrix (the scroll and the focused mark start over). */
+  key = '';
+  /** Above this many rows, only the rows in view are drawn. */
+  windowAt = 150;
+  strings: Partial<MarkMatrixStrings> = {};
+  /** Draws an icon of a header cell; default: `icon(name)`. */
+  renderIcon: (name: string) => unknown = (name) => icon(name);
+  /** Styles for what `renderIcon` draws, added to the element's own. */
+  iconStyles: readonly CSSResult[] = [];
+
+  /** The row (or a mark without one) under the pointer or focus. */
+  private hover: string | null = null;
+  /** The first row in view, and the focused cell (row, column). */
+  private scrollRow = 0;
+  private cell: [number, number] | null = null;
+
+  protected override willUpdate(changed: PropertyValues<this>): void {
+    if (changed.has('key') && changed.get('key') !== undefined) {
+      this.scrollRow = 0;
+      this.cell = null;
+    }
+  }
+
+  protected override updated(changed: PropertyValues<this>): void {
+    if (changed.has('iconStyles') && this.renderRoot instanceof ShadowRoot)
+      adoptStyles(this.renderRoot, [...(this.constructor as typeof LitElement).elementStyles, ...this.iconStyles]);
+  }
+
+  /** The highlighted row: the one hovered or focused, else the selected mark's, else `highlight`. */
+  private lit(): string | null {
+    if (this.hover !== null) return this.hover;
+    const row = this.selected ? this.matrix.rows.find((r) => r.cells.some((m) => m?.id === this.selected)) : undefined;
+    return row ? row.id || this.selected : this.highlight;
+  }
+
+  private select(id: string): void {
+    if (id !== this.selected) emit(this, 'cae-select', { id });
+  }
+
+  private act(m: MatrixMark): void {
+    if (m.drill) emit(this, 'cae-drill', { id: m.id });
+    else emit(this, 'cae-activate', { id: m.id });
+  }
+
+  override render() {
+    const mx = this.matrix;
+    const w = withDefaults(DEFAULT_MARK_MATRIX_STRINGS, this.strings);
+    const rows = mx.rows;
+    const cols = mx.columns;
+    const hl = this.lit();
+    // Where a group of columns starts: 0 at an outermost group, 1 at a group in it, ...
+    const starts = cols.map((c, i) => {
+      const p = cols[i - 1]?.groups;
+      if (!p) return -1;
+      const k = c.groups.findIndex((x, j) => x !== p[j]);
+      return k < 0 ? (c.groups.length !== p.length ? Math.min(c.groups.length, p.length) : -1) : k;
+    });
+    const groupCls = (ci: number) => (starts[ci] === 0 ? 'g0' : (starts[ci] ?? -1) > 0 ? 'g1' : '');
+    const headRows = mx.head.length;
+    const value = !!mx.value;
+    const lead = value ? 2 : 1;
+    // The rows in view (all of them up to `windowAt`).
+    const many = rows.length > this.windowAt;
+    const from = many ? Math.max(0, this.scrollRow - OVERSCAN) : 0;
+    const to = many ? Math.min(rows.length, this.scrollRow + 2 * OVERSCAN + 20) : rows.length;
+    const cur = this.cell && this.cell[0] < rows.length ? this.cell : firstCell(rows);
+    // A header cell's class: where a group of columns starts.
+    const headCls = (col: number) => (col === 0 || starts[col] === 0 ? 'g0' : (starts[col] ?? -1) > 0 ? 'g1' : '');
+    const headCell = (hd: MatrixHeadCell, col: number, level: number) => {
+      const style = `top:${level * 22}px`;
+      if (hd.type === 'group')
+        return html`<th scope="colgroup" part="head-cell" colspan=${hd.span} class="group ${hd.code ? 'code' : ''} ${headCls(col)}" style=${style}
+          title=${hd.tip ?? nothing} aria-label=${hd.summary ?? nothing}>${hd.label}</th>`;
+      return html`<th scope="col" part="head-cell" rowspan=${hd.rows} class="nh ${headCls(col)}" style=${style}
+        title=${hd.tip ?? nothing} aria-label=${hd.summary ?? nothing}>${(hd.icons ?? []).map((n) => this.renderIcon(n))}${hd.label}</th>`;
+    };
+    // The column each cell of a header row starts at: a cell under one that spans down starts after it.
+    const firstCols = (level: number) => {
+      const out: number[] = [];
+      let c = 0;
+      for (const hd of mx.head[level] ?? []) {
+        while (spannedAt(mx.head, level, c)) c++;
+        out.push(c);
+        c += hd.span;
+      }
+      return out;
+    };
+    const facts = (mx.facts ?? []).filter((f) => (typeof f === 'string' ? f : f.text));
+    return html`<div class="mxblock view">
+      <div class="mxbar">
+        <span class="cap" title=${mx.captionTip ?? nothing}>${mx.caption}</span>
+        ${mx.sorts?.length
+          ? html`<label>${w.sortBy}
+              <select part="sort" @change=${(e: Event) => emit(this, 'cae-sort', { id: (e.target as HTMLSelectElement).value, direction: 'asc' })}>
+                ${mx.sorts.map((s) => html`<option value=${s.id} ?selected=${mx.sort === s.id}>${s.label}</option>`)}
+              </select>
+            </label>`
+          : nothing}
+        <span class="sum">${facts.map(
+          (f, i) =>
+            html`${i ? html`<span class="sep"> | </span>` : nothing}${typeof f === 'string'
+              ? html`<span class="f">${f}</span>`
+              : html`<span class="f tone-text" data-tone=${toneAttr(f.tone)}>${f.text}</span>`}`,
+        )}</span>
+      </div>
+      <div class="mx ${hl ? 'hl' : ''}" @scroll=${this.onScroll} @mouseleave=${() => (this.hover = null)}>
+        <table class="matrix big" part="matrix" role="grid" aria-rowcount=${rows.length + headRows} aria-colcount=${cols.length + lead} aria-label=${mx.label}>
+          <thead>
+            ${mx.head.map((hr, level) => {
+              const fc = firstCols(level);
+              return html`<tr>
+                ${level === 0
+                  ? html`<th scope="col" rowspan=${headRows} class="uh" style="top:0">${w.rowsHeader}</th>
+                      ${value ? html`<th scope="col" rowspan=${headRows} class="pn" style="top:0" title=${mx.value?.tip ?? nothing}>${mx.value?.label}</th>` : nothing}`
+                  : nothing}
+                ${hr.map((hd, i) => headCell(hd, fc[i] ?? 0, level))}
+              </tr>`;
+            })}
+          </thead>
+          <tbody @keydown=${(e: KeyboardEvent) => this.onKey(e, rows)}>
+            ${from > 0 ? html`<tr class="gap" aria-hidden="true"><td colspan=${cols.length + lead} style="height:${from * ROW_H}px"></td></tr>` : nothing}
+            ${repeat(
+              rows.slice(from, to),
+              (r) => r.id,
+              (r, k) => {
+                const ri = from + k;
+                return html`<tr class=${r.id && r.id === hl ? 'on' : ''} aria-rowindex=${ri + headRows + 1}>
+                  <th scope="row" part="row-header" class=${r.muted ? 'none' : nothing} title=${r.tip ?? r.label}>${r.label}</th>
+                  ${value ? html`<td class="pn ${r.strong ? 'many' : ''}">${r.value}</td>` : nothing}
+                  ${r.cells.map((m, ci) => {
+                    const focusable = !!m && cur !== null && cur[0] === ri && cur[1] === ci;
+                    return html`<td class="c ${groupCls(ci)}" role="gridcell">${m ? this.mark(r, m, ri, ci, focusable, hl) : nothing}</td>`;
+                  })}
+                </tr>`;
+              },
+            )}
+            ${to < rows.length
+              ? html`<tr class="gap" aria-hidden="true"><td colspan=${cols.length + lead} style="height:${(rows.length - to) * ROW_H}px"></td></tr>`
+              : nothing}
+          </tbody>
+        </table>
+      </div>
+    </div>`;
+  }
+
+  private mark(r: MatrixRowInput, m: MatrixMark, ri: number, ci: number, tabStop: boolean, hl: string | null) {
+    const look = this.states[m.state];
+    const hlKey = r.id || m.id;
+    const sel = this.selected === m.id;
+    return html`<button type="button" part="mark" class="mark ${r.id && r.id === hl ? 'on' : ''} ${sel ? 'sel' : ''}"
+      data-tone=${toneAttr(look?.tone)} data-shape=${look?.shape ?? nothing} data-r=${ri} data-c=${ci} tabindex=${tabStop ? 0 : -1}
+      title=${m.tip ?? nothing} aria-label=${m.label} aria-pressed=${sel}
+      @mouseenter=${() => (this.hover = hlKey)}
+      @focus=${() => {
+        this.hover = hlKey;
+        this.cell = [ri, ci];
+        this.select(m.id);
+      }}
+      @blur=${() => (this.hover = null)}
+      @click=${() => this.select(m.id)}
+      @dblclick=${() => this.act(m)}></button>`;
+  }
+
+  private readonly onScroll = (e: Event): void => {
+    const top = Math.floor((e.currentTarget as HTMLElement).scrollTop / ROW_H);
+    if (Math.abs(top - this.scrollRow) >= OVERSCAN / 2) this.scrollRow = top;
+  };
+
+  private onKey(e: KeyboardEvent, rows: readonly MatrixRowInput[]): void {
+    const t = e.target as HTMLElement;
+    if (!t.classList.contains('mark')) return;
+    const r = Number(t.dataset['r']);
+    const c = Number(t.dataset['c']);
+    if (e.key === 'Enter') {
+      const m = rows[r]?.cells[c];
+      e.preventDefault();
+      if (m) this.act(m);
+      return;
+    }
+    const has = rows.map((row) => row.cells.map((x) => x !== null));
+    const next = gridStep(has, r, c, e.key, e.ctrlKey || e.metaKey);
+    if (!next) return;
+    e.preventDefault();
+    this.cell = next;
+    const box = this.renderRoot.querySelector<HTMLElement>('.mx');
+    if (box && rows.length > this.windowAt) {
+      // Bring the row into view first: only the rows in view are drawn.
+      const y = next[0] * ROW_H;
+      if (y < box.scrollTop + ROW_H * 2 || y > box.scrollTop + box.clientHeight - ROW_H * 3) box.scrollTop = Math.max(0, y - box.clientHeight / 2);
+      this.scrollRow = Math.floor(box.scrollTop / ROW_H);
+    }
+    this.requestUpdate();
+    void this.updateComplete.then(() => this.renderRoot.querySelector<HTMLElement>(`.matrix .mark[data-r="${next[0]}"][data-c="${next[1]}"]`)?.focus());
+  }
+}
+
+/** The first mark of the rows, as (row, column). */
+function firstCell(rows: readonly MatrixRowInput[]): [number, number] | null {
+  for (let i = 0; i < rows.length; i++) {
+    const j = rows[i]?.cells.findIndex((c) => c !== null) ?? -1;
+    if (j >= 0) return [i, j];
+  }
+  return null;
+}
+
+/** A header row's column `c` is under a cell of an earlier row that spans down past it. */
+function spannedAt(head: readonly (readonly MatrixHeadCell[])[], level: number, c: number): boolean {
+  for (let l = 0; l < level; l++) {
+    let x = 0;
+    for (const hd of head[l] ?? []) {
+      if (c >= x && c < x + hd.span && l + hd.rows > level) return true;
+      x += hd.span;
+    }
+  }
+  return false;
+}
+
+declare global {
+  interface HTMLElementTagNameMap {
+    'cae-mark-matrix': CaeMarkMatrix;
+  }
+}

package/src/matrix/styles.ts

@@ -0,0 +1,48 @@
+// A mark matrix's styles: the line above it, the table, its sticky headers and its marks.
+import { css, unsafeCSS } from 'lit';
+import { FRAME_MIN, FRAME_SHARE } from '../core/frame.js';
+
+/** A row's height, in px: what the windowing counts in. */
+export const ROW_H = 24;
+
+export const matrixStyles = css`
+  /* The block is the box: it lays out where the host is placed. */
+  :host { display: contents; }
+  /* At least wide enough for the caption and the sort beside it: a narrower table is stretched to it. */
+  .mxblock { display: flex; flex-direction: column; width: fit-content; max-width: 100%; min-width: min(100%, 27rem);
+    animation: view-in 0.1s var(--ease) both; }
+  @keyframes view-in { from { opacity: 0; } }
+  @media (prefers-reduced-motion: reduce) { .mxblock { animation: none; } }
+  .mxbar { display: flex; flex-wrap: wrap; align-items: center; gap: 4px 14px; margin-bottom: 8px; font-size: 12px; color: var(--text-2);
+    width: 0; min-width: 100%; box-sizing: border-box; }
+  .mxbar .cap { color: var(--text); font-weight: 600; }
+  .mxbar .sum { flex: 1 0 100%; min-width: 0; }
+  .mxbar .f { white-space: nowrap; }
+  .sep { color: var(--text-muted); }
+  .mxbar label { display: inline-flex; align-items: center; gap: 6px; margin-left: auto; color: var(--text-muted); font-size: 11.5px; white-space: nowrap; }
+  .mxbar select { font: inherit; font-size: 11.5px; color: var(--text); background: var(--card); border: 1px solid var(--line); border-radius: 6px; padding: 2px 6px; }
+  .mxbar select:focus-visible { outline: var(--focus-width) solid var(--focus); outline-offset: 1px; }
+  .mx { overflow: auto; max-width: 100%; max-height: max(${FRAME_MIN}px, ${unsafeCSS(FRAME_SHARE * 100)}vh); border-radius: 6px; border: 1px solid var(--line); }
+  table.matrix { border-collapse: separate; border-spacing: 0; font-size: 11px; width: 100%; min-width: max-content; }
+  .matrix th, .matrix td { padding: 0 6px; height: ${ROW_H}px; border-bottom: 1px solid var(--line); white-space: nowrap; }
+  .matrix thead th { position: sticky; z-index: 2; background: var(--panel2); color: var(--text-muted); font-weight: 500; text-align: center; height: 22px; }
+  .matrix thead th.nh { font-family: var(--mono); color: var(--text-2); font-weight: 600; max-width: 110px; overflow: hidden; text-overflow: ellipsis; }
+  .matrix thead th.group { color: var(--text-2); }
+  .matrix thead th.group.code { font-family: var(--mono); color: var(--text-muted); }
+  .matrix .uh, .matrix tbody th { position: sticky; left: 0; z-index: 1; background: var(--panel); text-align: left; }
+  .matrix thead .uh { z-index: 3; }
+  .matrix thead .uh, .matrix thead .pn { background: var(--panel2); }
+  .matrix tbody th { font-family: var(--mono); font-weight: 600; color: var(--text); max-width: 220px; overflow: hidden; text-overflow: ellipsis; }
+  .matrix tbody th.none { font-family: var(--sans); font-weight: 500; color: var(--text-muted); }
+  .matrix .pn { text-align: right; color: var(--text-muted); font-variant-numeric: tabular-nums; }
+  .matrix .pn.many { color: var(--text); font-weight: 600; }
+  .matrix td.c { text-align: center; --m: 12px; }
+  .matrix td.c .mark { vertical-align: middle; }
+  .matrix .g0 { border-left: 1px solid var(--line2); }
+  .matrix .g1 { border-left: 1px dashed var(--line); }
+  .matrix tbody tr:hover td, .matrix tbody tr:hover th { background-color: color-mix(in srgb, var(--text-muted) 8%, transparent); }
+  .matrix tbody tr.on td, .matrix tbody tr.on th { background-color: var(--accent-bg); }
+  .matrix .gap td { padding: 0; border: 0; }
+  .mx.hl .mark:not(.on) { opacity: 0.4; }
+  .mx.hl .mark.on { transform: scale(1.2); }
+`;

package/src/matrix/types.ts

@@ -0,0 +1,83 @@
+// A mark matrix's model: rows of marks under nested groups of columns.
+import type { Fact } from '../primitives/fact-line.js';
+
+/** One mark of a matrix cell (the same shape as a graph's mark). */
+export interface MatrixMark {
+  /** Unique in the matrix: the selection id. */
+  id: string;
+  /** A key of `StateStyles`. */
+  state: string;
+  /** The accessible name. */
+  label: string;
+  tip?: string;
+  /** The mark opens an inner view: Enter and a double click send `cae-drill`, not `cae-activate`. */
+  drill?: boolean;
+}
+
+/** A header cell: a group of columns (`group`), or a column's own (`column`, spanning down to the last header row). */
+export interface MatrixHeadCell {
+  id: string;
+  label: string;
+  tip?: string;
+  /** The accessible name; default: `label`. */
+  summary?: string;
+  /** Icon names (`registerIcon`) before its label. */
+  icons?: readonly string[];
+  /** The label is a name in code: drawn in the monospace font. */
+  code?: boolean;
+  span: number;
+  rows: number;
+  type: 'group' | 'column';
+}
+
+export interface MatrixColumnInput {
+  id: string;
+  /** The ids of the groups it is under, outermost first: a border marks where a group starts. */
+  groups: readonly string[];
+}
+
+export interface MatrixRowInput {
+  /** Its id: what the matrix highlights (the series of the selected or hovered mark). */
+  id: string;
+  label: string;
+  tip?: string;
+  /** Its label in the plain, muted face (a row that stands for no item of its own). */
+  muted?: boolean;
+  /** The value column's cell, and whether it stands out. */
+  value?: string | number;
+  strong?: boolean;
+  /** One per column: its mark, or null. */
+  cells: readonly (MatrixMark | null)[];
+}
+
+export interface MarkMatrixInput {
+  /** The line above the table, and its tooltip. */
+  caption: string;
+  captionTip?: string;
+  /** The table's accessible name. */
+  label: string;
+  /** Facts beside the caption. */
+  facts?: readonly (string | Fact)[];
+  /** The header rows, outermost first. */
+  head: readonly (readonly MatrixHeadCell[])[];
+  columns: readonly MatrixColumnInput[];
+  /** Already in the order chosen (`sort`): the host sorts them. */
+  rows: readonly MatrixRowInput[];
+  /** A column of one value per row, after the rows' labels, and its header. */
+  value?: { label: string; tip?: string };
+  /** The orders the reader may choose, and the one chosen. */
+  sorts?: readonly { id: string; label: string }[];
+  sort?: string;
+}
+
+export interface MarkMatrixStrings {
+  /** The label of the sort control. */
+  sortBy: string;
+  /** The header of the rows' labels. */
+  rowsHeader: string;
+}
+
+export const DEFAULT_MARK_MATRIX_STRINGS: Readonly<MarkMatrixStrings> = {
+  sortBy: 'Sort',
+  rowsHeader: 'Row',
+};

package/src/primitives/fact-line.ts

@@ -0,0 +1,26 @@
+// A row of facts ("6 tasks", "6 attempts") in a narrow box: each fact is kept
+// whole, and the line breaks between facts. Use it inside `.words`.
+import { html, nothing, type TemplateResult } from 'lit';
+import { toneAttr, type Tone } from '../core/tone.js';
+
+/** A fact in a row of facts; a status fact has a tone. */
+export interface Fact {
+  text: string;
+  tone?: Tone;
+}
+
+/**
+ * `facts`, each in a `.f` span that does not break inside unless it is wider than
+ * the box, separated by `sep`. A fact with a tone is in its status colour
+ * (`.tone-text`); an empty fact is left out.
+ */
+export function factLine(facts: readonly (string | Fact)[], sep = ' | '): TemplateResult | typeof nothing {
+  const shown = facts.filter((f) => (typeof f === 'string' ? f : f.text));
+  return shown.length
+    ? html`${shown.map((f, i) =>
+        typeof f === 'string'
+          ? html`${i ? sep : ''}<span class="f">${f}</span>`
+          : html`${i ? sep : ''}<span class="f tone-text" data-tone=${toneAttr(f.tone)}>${f.text}</span>`,
+      )}`
+    : nothing;
+}

package/src/primitives/icon.ts

@@ -0,0 +1,26 @@
+// Small icons: a glyph or a template, registered by name.
+import { html, nothing, type TemplateResult } from 'lit';
+
+const icons = new Map<string, TemplateResult | string>();
+
+/** Registers an icon under `name` (a later registration replaces it). */
+export function registerIcon(name: string, template: TemplateResult | string): void {
+  icons.set(name, template);
+}
+
+export interface IconOptions {
+  /** Classes on the icon's element. */
+  cls?: string;
+}
+
+/**
+ * The icon `name` (the name itself when nothing is registered under it, so a
+ * glyph works as its own name). Without a label it is hidden from screen
+ * readers; with one, the label is its tooltip and what a screen reader reads.
+ */
+export function icon(name: string, label?: string | null, o: IconOptions = {}): TemplateResult {
+  const glyph = icons.get(name) ?? name;
+  return label
+    ? html`<span class=${o.cls || nothing} part="icon" title=${label}><span aria-hidden="true">${glyph}</span><span class="sr">${label}</span></span>`
+    : html`<span class=${o.cls || nothing} part="icon" aria-hidden="true">${glyph}</span>`;
+}

package/src/primitives/index.ts

@@ -0,0 +1,12 @@
+// The parts every element is built from: `@contraagent/elements/primitives`.
+// Template functions and controllers; `CaeSegmented` is registered by
+// `@contraagent/elements/segmented/define`.
+export * from './pill.js';
+export * from './legend.js';
+export * from './share-bar.js';
+export * from './states.js';
+export * from './fact-line.js';
+export * from './icon.js';
+export * from './roving-focus.js';
+export * from './window.js';
+export * from './segmented.js';

package/src/primitives/legend.ts

@@ -0,0 +1,56 @@
+// A legend: a swatch and a word per entry.
+import { css, html, nothing, type TemplateResult } from 'lit';
+import { styleMap } from 'lit/directives/style-map.js';
+import { toneAttr, type Tone } from '../core/tone.js';
+
+/** The shape of a status mark: done round, failed square, not started hatched, waiting a ring, partly done a round with its lower half filled. */
+export type MarkShape = 'round' | 'square' | 'hatched' | 'ring' | 'half';
+
+export interface LegendItem {
+  label: string;
+  /** The swatch's colour: a CSS colour or `var(...)`. */
+  swatch?: string;
+  /** The swatch's status colour (instead of `swatch`). */
+  tone?: Tone;
+  shape?: MarkShape;
+  /** Classes on the swatch (`<i>`), for a swatch the host's styles draw. */
+  cls?: string;
+  /** What to draw instead of the swatch: an icon, a mark, a line. */
+  icon?: unknown;
+  /** Hidden from screen readers: the item names what the reader reaches another way. */
+  decorative?: boolean;
+}
+
+export interface LegendOptions {
+  /** The legend's accessible name. */
+  label?: string;
+  /** More classes on the legend. */
+  cls?: string;
+}
+
+/** The swatch of an entry; none for an entry that is only a word (a note at the end). */
+const swatch = (it: LegendItem): unknown =>
+  it.icon ??
+  (it.swatch || it.tone || it.shape || it.cls
+    ? html`<i class=${it.cls || nothing} data-tone=${toneAttr(it.tone)} data-shape=${it.shape ?? nothing}
+        style=${it.swatch ? styleMap({ background: it.swatch }) : nothing}></i>`
+    : nothing);
+
+/** A row of entries (`.legend`, part `legend`), each its swatch and its word, as a list. */
+export function legend(items: readonly LegendItem[], o: LegendOptions = {}): TemplateResult {
+  return html`<div class="legend ${o.cls ?? ''}" part="legend" role="list" aria-label=${o.label || nothing}>
+    ${items.map((it) => html`<span role="listitem" aria-hidden=${it.decorative ? 'true' : nothing}>${swatch(it)}${it.label}</span>`)}
+  </div>`;
+}
+
+export const legendStyles = css`
+  .legend { display: flex; gap: 14px; flex-wrap: wrap; font-size: var(--font-size-sm); color: var(--text-muted); }
+  .legend > span { white-space: nowrap; }
+  .legend i { display: inline-block; width: 10px; height: 10px; border-radius: 3px; margin-right: 5px; vertical-align: -1px; }
+  .legend i[data-tone] { background: var(--tone); }
+  .legend i[data-shape='round'] { border-radius: 50%; }
+  .legend i[data-shape='square'] { border-radius: 2px; }
+  .legend i[data-shape='ring'] { background: none; border-radius: 50%; box-shadow: inset 0 0 0 1.5px var(--tone, var(--line2)); }
+  .legend i[data-shape='half'] { border-radius: 50%; background: linear-gradient(0deg, var(--tone, var(--line2)) 50%, transparent 50%); box-shadow: inset 0 0 0 1.5px var(--tone, var(--line2)); }
+  .legend i[data-shape='hatched'] { border-radius: 2px; background: repeating-linear-gradient(135deg, transparent 0 2px, var(--tone, var(--line2)) 2px 3px); }
+`;

package/src/primitives/pill.ts

@@ -0,0 +1,58 @@
+// A status shown as a pill or as a word: the word, its tone (`data-tone`) and,
+// where a mark belongs, its mark (`data-mark`: ✓ done, ✕ failed, ◌ pending).
+// The look of each is in `styles/status.ts`; the mark is drawn by CSS and hidden
+// from screen readers, which read the word.
+import { html, nothing, type TemplateResult } from 'lit';
+import { toneAttr, type Tone } from '../core/tone.js';
+
+/** The shape before a status word. */
+export type Mark = 'done' | 'failed' | 'pending';
+
+/** The mark a tone takes by default: ✓ done, ✕ failed, ◌ attention; none for running, muted or neutral. */
+export function markOf(tone: Tone): Mark | null {
+  switch (tone) {
+    case 'done':
+      return 'done';
+    case 'failed':
+      return 'failed';
+    case 'attention':
+      return 'pending';
+    default:
+      return null;
+  }
+}
+
+export interface PillSpec {
+  /** The word (a template may add a count after it). */
+  text: unknown;
+  tone?: Tone;
+  /** The mark: `markOf(tone)` when not given (or true); false or null for none. */
+  mark?: Mark | boolean | null;
+  title?: string | null;
+  /** More classes on the element. */
+  cls?: string;
+}
+
+/** The `data-mark` of a spec. */
+const markAttr = (p: PillSpec): Mark | typeof nothing => {
+  const m = p.mark === undefined || p.mark === true ? markOf(p.tone ?? 'neutral') : p.mark || null;
+  return m ?? nothing;
+};
+
+/** A status as a pill (`.pill`, part `pill tone-<tone>`): tinted by its tone, a done pill quiet with its ✓. */
+export function pill(p: PillSpec): TemplateResult {
+  const tone = p.tone ?? 'neutral';
+  return html`<span class="pill ${p.cls ?? ''}" part="pill tone-${tone}" data-tone=${toneAttr(tone)} data-mark=${markAttr(p)} title=${p.title || nothing}>${p.text}</span>`;
+}
+
+/** A status as a word in a row (`.jstop`, part `status tone-<tone>`): coloured for a problem, done quiet with its ✓. */
+export function statusWord(p: PillSpec): TemplateResult {
+  const tone = p.tone ?? 'neutral';
+  return html`<span class="jstop ${p.cls ?? ''}" part="status tone-${tone}" data-tone=${toneAttr(tone)} data-mark=${markAttr(p)} title=${p.title || nothing}>${p.text}</span>`;
+}
+
+/** A status as a chip of the class `cls` (an element styles it): the tone and the mark, as on a pill. */
+export function statusChip(cls: string, p: PillSpec): TemplateResult {
+  const tone = p.tone ?? 'neutral';
+  return html`<span class="${cls} ${p.cls ?? ''}" data-tone=${toneAttr(tone)} data-mark=${markAttr(p)} title=${p.title || nothing}>${p.text}</span>`;
+}