@contraagent/elements 0.0.0-stage → 0.2.0

package/src/charts/column-chart.ts

@@ -0,0 +1,153 @@
+import { html, nothing, svg, type TemplateResult } from 'lit';
+import { property } from 'lit/decorators.js';
+import type { LegendItem } from '../primitives/legend.js';
+import { ChartElement } from './base.js';
+import { foldSeries, LABEL_GAP, labelStride, niceAxis, type DrawnSeries } from './scale.js';
+import type { ChartSeries } from './types.js';
+
+/** The plot's margins: the value axis on the left, the labels under it. */
+const M = { top: 8, right: 4, bottom: 22 };
+/** A bar's top: rounded, the end anchored to the axis square. */
+const RADIUS = 4;
+/** The gap between the stacked parts of a bar, and between the bars of a group. */
+const GAP = 2;
+
+/** A bar from the axis up, its top corners rounded when `round`. */
+export function barPath(x: number, y: number, w: number, h: number, round: boolean): string {
+  if (h <= 0 || w <= 0) return '';
+  const r = round ? Math.min(RADIUS, w / 2, h) : 0;
+  return `M${x},${y + h}V${y + r}${r ? `Q${x},${y} ${x + r},${y}` : ''}H${x + w - r}${r ? `Q${x + w},${y} ${x + w},${y + r}` : ''}V${y + h}Z`;
+}
+
+/**
+ * Vertical bars, one group per label of `x`: a bar per series side by side, or with
+ * `stacked`, the series of a label on one bar. Six series take the series colours in
+ * their order; past six, the sixth and later are one bar part, "other". A legend
+ * names the series when there are two or more. Pointing at a label, or moving to it
+ * with the arrow keys, shows its values; the switch shows them all as a table.
+ *
+ * @tagname cae-column-chart
+ * @csspart plot - the chart
+ * @csspart table - the table of its values
+ * @csspart switch - the button between the two
+ * @csspart empty - what it shows with no values
+ * @csspart legend - the legend
+ */
+export class CaeColumnChart extends ChartElement {
+  /** A label per group of bars, in order. */
+  @property({ attribute: false }) x: readonly string[] = [];
+  @property({ attribute: false }) series: readonly ChartSeries[] = [];
+  /** The series of a label on one bar, instead of side by side. */
+  @property({ type: Boolean }) stacked = false;
+
+  private get drawn(): DrawnSeries[] {
+    return foldSeries(this.series, this.words.other);
+  }
+
+  protected hasValues(): boolean {
+    return this.x.length > 0 && this.series.some((s) => s.values.some((v) => v !== null && v !== undefined));
+  }
+
+  protected legendItems(): LegendItem[] {
+    const d = this.drawn;
+    return d.length > 1 ? d.map((s) => ({ label: s.name, swatch: s.colour })) : [];
+  }
+
+  protected itemCount(): number {
+    return this.x.length;
+  }
+
+  /** The total of label `j` (the stacked bar's height). */
+  private total(j: number): number {
+    return this.drawn.reduce((a, s) => a + Math.max(0, s.values[j] ?? 0), 0);
+  }
+
+  protected plot(): TemplateResult {
+    const d = this.drawn;
+    const n = this.x.length;
+    const values = d.flatMap((s) => s.values.filter((v): v is number => v !== null && v !== undefined));
+    const high = this.stacked ? Math.max(0, ...this.x.map((_, j) => this.total(j))) : Math.max(0, ...values);
+    const axis = niceAxis(Math.min(0, ...values), high);
+    const left = Math.max(...axis.ticks.map((t) => this.labelWidth(this.format(t)))) + 4;
+    const w = this.plotWidth;
+    const h = this.height;
+    const pw = w - left - M.right;
+    const ph = h - M.top - M.bottom;
+    const y = (v: number) => M.top + ph - ((v - axis.min) / (axis.max - axis.min)) * ph;
+    const band = pw / n;
+    const barW = Math.max(2, Math.min(40, band * (this.stacked || d.length === 1 ? 0.62 : 0.8)));
+    const stride = labelStride(n, pw, Math.max(...this.x.map((s) => this.labelWidth(s))) + LABEL_GAP);
+    const bars: TemplateResult[] = [];
+    for (let j = 0; j < n; j++) {
+      const x0 = left + j * band + (band - barW) / 2;
+      if (this.stacked) {
+        let at = 0;
+        const parts = d.map((s) => ({ s, v: Math.max(0, s.values[j] ?? 0) })).filter((p) => p.v > 0);
+        parts.forEach((p, k) => {
+          const top = y(at + p.v);
+          const bottom = y(at);
+          // Each part is 2px shorter than its share, so the surface shows between the parts.
+          const hgt = bottom - top - (k > 0 ? GAP : 0);
+          bars.push(svg`<path d=${barPath(x0, top, barW, Math.max(0, hgt), k === parts.length - 1)} fill=${p.s.colour}></path>`);
+          at += p.v;
+        });
+      } else {
+        const each = (barW - GAP * (d.length - 1)) / d.length;
+        d.forEach((s, k) => {
+          const v = s.values[j];
+          if (v === null || v === undefined || v === 0) return;
+          const top = y(Math.max(0, v));
+          const bottom = y(Math.min(0, v));
+          bars.push(svg`<path d=${barPath(x0 + k * (each + GAP), top, Math.max(1, each), bottom - top, v > 0)} fill=${s.colour}></path>`);
+        });
+      }
+    }
+    const a = this.active;
+    return html`<svg width=${w} height=${h} role="img" aria-label=${this.label || nothing}>
+        ${axis.ticks.map(
+          (t) => svg`<line class=${t === 0 ? 'base' : 'grid'} x1=${left} x2=${w - M.right} y1=${y(t)} y2=${y(t)}></line>
+            <text class="axis" x=${left - 6} y=${y(t)} dy="0.32em" text-anchor="end">${this.format(t)}</text>`,
+        )}
+        ${a !== null ? svg`<rect class="band" x=${left + a * band} y=${M.top} width=${band} height=${ph}></rect>` : nothing}
+        ${bars}
+        ${this.x.map((label, j) =>
+          j % stride === 0
+            ? svg`<text class="axis" x=${left + j * band + band / 2} y=${h - 6} text-anchor="middle">${label}</text>`
+            : nothing,
+        )}
+        ${this.x.map(
+          (_, j) => svg`<rect class="hit" x=${left + j * band} y=${M.top} width=${band} height=${ph + M.bottom}
+            @mouseenter=${() => (this.active = j)}></rect>`,
+        )}
+      </svg>
+      ${a !== null && a < n ? this.tip(left + a * band + band / 2, M.top, this.tipBody(a)) : nothing}`;
+  }
+
+  private tipBody(j: number): TemplateResult {
+    const d = this.drawn;
+    const none = this.words.none;
+    return html`<b>${this.x[j]}</b>
+      ${[...d].reverse().map((s) => this.tipRow(s.colour, s.name, s.values[j] === null || s.values[j] === undefined ? none : this.format(s.values[j])))}
+      ${this.stacked && d.length > 1 ? this.tipRow(null, this.words.total, this.format(this.total(j))) : nothing}`;
+  }
+
+  protected table(): TemplateResult {
+    const d = this.drawn;
+    const none = this.words.none;
+    const sum = this.stacked && d.length > 1;
+    return html`<table aria-label=${this.label || nothing}>
+      <thead><tr><th scope="col">${this.words.label}</th>${d.map((s) => html`<th scope="col">${s.name}</th>`)}${sum ? html`<th scope="col">${this.words.total}</th>` : nothing}</tr></thead>
+      <tbody>${this.x.map(
+        (label, j) => html`<tr><th scope="row">${label}</th>${d.map((s) => html`<td>${s.values[j] === null || s.values[j] === undefined ? none : this.format(s.values[j])}</td>`)}${
+          sum ? html`<td>${this.format(this.total(j))}</td>` : nothing
+        }</tr>`,
+      )}</tbody>
+    </table>`;
+  }
+}
+
+declare global {
+  interface HTMLElementTagNameMap {
+    'cae-column-chart': CaeColumnChart;
+  }
+}

package/src/charts/heatmap.ts

@@ -0,0 +1,129 @@
+import { html, nothing, svg, type TemplateResult } from 'lit';
+import { property } from 'lit/decorators.js';
+import type { LegendItem } from '../primitives/legend.js';
+import { ChartElement } from './base.js';
+import { LABEL_GAP, labelStride } from './scale.js';
+
+/** One hue, light to dark: a value's share of the colour, by its step of five. */
+export const HEAT_STEPS = [16, 34, 52, 72, 92] as const;
+/** The hue of the scale. */
+const HUE = 'var(--series-1)';
+const CELL_H = 22;
+const GAP = 2;
+const M = { top: 2, right: 2, bottom: 22 };
+
+/** A colour of the scale: `pct` percent of its hue over the card. */
+export const heatColour = (pct: number): string => `color-mix(in srgb, ${HUE} ${pct}%, var(--card))`;
+
+/** The step (0..4) of `v` between `low` and `high`. */
+export function heatStep(v: number, low: number, high: number): number {
+  if (!(high > low)) return HEAT_STEPS.length - 1;
+  const t = (v - low) / (high - low);
+  return Math.min(HEAT_STEPS.length - 1, Math.max(0, Math.floor(t * HEAT_STEPS.length)));
+}
+
+/**
+ * A value per row (`y`) and column (`x`), each a cell coloured on one scale, light to
+ * dark (`values[row][column]`; a null cell is left empty, a 0 is the lightest step).
+ * The legend gives the scale's lowest and highest value. Pointing at a cell, or moving
+ * to it with the arrow keys (up and down by a row), shows its row, column and value;
+ * the switch shows them all as a table.
+ *
+ * @tagname cae-heatmap
+ * @csspart plot - the chart
+ * @csspart table - the table of its values
+ * @csspart switch - the button between the two
+ * @csspart empty - what it shows with no values
+ * @csspart legend - the legend
+ */
+export class CaeHeatmap extends ChartElement {
+  @property({ attribute: false }) x: readonly string[] = [];
+  @property({ attribute: false }) y: readonly string[] = [];
+  @property({ attribute: false }) values: readonly (readonly (number | null)[])[] = [];
+
+  private get range(): [number, number] {
+    const all = this.values.flat().filter((v): v is number => v !== null && v !== undefined);
+    return all.length ? [Math.min(0, ...all), Math.max(...all)] : [0, 0];
+  }
+
+  protected hasValues(): boolean {
+    return this.x.length > 0 && this.y.length > 0 && this.values.some((r) => r.some((v) => v !== null && v !== undefined));
+  }
+
+  protected legendItems(): LegendItem[] {
+    const [low, high] = this.range;
+    const strip = html`<span class="scale" aria-hidden="true">${HEAT_STEPS.map((p) => html`<i style="background: ${heatColour(p)}"></i>`)}</span>`;
+    return [{ label: this.words.scale(this.format(low), this.format(high)), icon: strip }];
+  }
+
+  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 [low, high] = this.range;
+    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 cells: TemplateResult[] = [];
+    for (let r = 0; r < ny; r++)
+      for (let c = 0; c < nx; c++) {
+        const v = this.values[r]?.[c];
+        const x = left + c * cw;
+        const y = M.top + r * CELL_H;
+        const i = r * nx + c;
+        cells.push(
+          v === null || v === undefined
+            ? svg`<rect x=${x + GAP / 2} y=${y + GAP / 2} width=${Math.max(1, cw - GAP)} height=${CELL_H - GAP} rx="2" fill="none" stroke="var(--line)"
+                @mouseenter=${() => (this.active = i)}></rect>`
+            : svg`<rect x=${x + GAP / 2} y=${y + GAP / 2} width=${Math.max(1, cw - GAP)} height=${CELL_H - GAP} rx="2"
+                fill=${heatColour(HEAT_STEPS[heatStep(v, low, high)] ?? 92)} stroke=${a === i ? 'var(--text)' : 'none'} stroke-width="1.5"
+                @mouseenter=${() => (this.active = i)}></rect>`,
+        );
+      }
+    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.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}`;
+  }
+
+  private tipBody(r: number, c: number): TemplateResult {
+    const v = this.values[r]?.[c];
+    return html`<b>${this.y[r]} | ${this.x[c]}</b>
+      <div class="row"><span>${v === null || v === undefined ? this.words.none : this.format(v)}</span></div>`;
+  }
+
+  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 v = this.values[r]?.[c];
+          return html`<td>${v === null || v === undefined ? none : this.format(v)}</td>`;
+        })}</tr>`,
+      )}</tbody>
+    </table>`;
+  }
+}
+
+declare global {
+  interface HTMLElementTagNameMap {
+    'cae-heatmap': CaeHeatmap;
+  }
+}

package/src/charts/index.ts

@@ -0,0 +1,10 @@
+// Charts of plain series: `@contraagent/elements/charts`. The elements are registered
+// by `@contraagent/elements/charts/define`.
+export * from './types.js';
+export * from './scale.js';
+export * from './base.js';
+export * from './column-chart.js';
+export * from './line-chart.js';
+export * from './heatmap.js';
+export * from './state-grid.js';
+export * from './bar-chart.js';

package/src/charts/line-chart.ts

@@ -0,0 +1,128 @@
+import { html, nothing, svg, type TemplateResult } from 'lit';
+import { property } from 'lit/decorators.js';
+import type { LegendItem } from '../primitives/legend.js';
+import { ChartElement } from './base.js';
+import { LABEL_GAP, labelStride, niceAxis, seriesColour } from './scale.js';
+import type { ChartSeries } from './types.js';
+
+const M = { top: 8, right: 10, bottom: 22 };
+
+/** The path of a series: a line through its values, broken where a value is null. */
+export function linePath(points: readonly ([number, number] | null)[]): string {
+  let d = '';
+  let open = false;
+  for (const p of points) {
+    if (!p) {
+      open = false;
+      continue;
+    }
+    d += `${open ? 'L' : 'M'}${p[0].toFixed(1)},${p[1].toFixed(1)}`;
+    open = true;
+  }
+  return d;
+}
+
+/**
+ * Lines over the labels of `x`, one per series (a value per label; null breaks the
+ * line). Six series take the series colours in their order; any past six are drawn in
+ * the colour of "other" and named in the legend and the tooltip. Pointing at a label,
+ * or moving to it with the arrow keys, marks it with a rule and shows every series'
+ * value there; the switch shows them all as a table.
+ *
+ * @tagname cae-line-chart
+ * @csspart plot - the chart
+ * @csspart table - the table of its values
+ * @csspart switch - the button between the two
+ * @csspart empty - what it shows with no values
+ * @csspart legend - the legend
+ */
+export class CaeLineChart extends ChartElement {
+  @property({ attribute: false }) x: readonly string[] = [];
+  @property({ attribute: false }) series: readonly ChartSeries[] = [];
+
+  protected hasValues(): boolean {
+    return this.x.length > 0 && this.series.some((s) => s.values.some((v) => v !== null && v !== undefined));
+  }
+
+  protected legendItems(): LegendItem[] {
+    return this.series.length > 1 ? this.series.map((s, i) => ({ label: s.name, swatch: seriesColour(i) })) : [];
+  }
+
+  protected itemCount(): number {
+    return this.x.length;
+  }
+
+  protected plot(): TemplateResult {
+    const n = this.x.length;
+    const values = this.series.flatMap((s) => s.values.filter((v): v is number => v !== null && v !== undefined));
+    const axis = niceAxis(Math.min(0, ...values), Math.max(0, ...values));
+    const left = Math.max(...axis.ticks.map((t) => this.labelWidth(this.format(t)))) + 4;
+    const w = this.plotWidth;
+    const h = this.height;
+    const pw = w - left - M.right;
+    const ph = h - M.top - M.bottom;
+    const step = n > 1 ? pw / (n - 1) : 0;
+    const px = (j: number) => (n > 1 ? left + j * step : left + pw / 2);
+    const py = (v: number) => M.top + ph - ((v - axis.min) / (axis.max - axis.min)) * ph;
+    const stride = labelStride(n, pw, Math.max(...this.x.map((s) => this.labelWidth(s))) + LABEL_GAP);
+    const a = this.active;
+    const hitW = n > 1 ? step : pw;
+    return html`<svg width=${w} height=${h} role="img" aria-label=${this.label || nothing}>
+        ${axis.ticks.map(
+          (t) => svg`<line class=${t === 0 ? 'base' : 'grid'} x1=${left} x2=${w - M.right} y1=${py(t)} y2=${py(t)}></line>
+            <text class="axis" x=${left - 6} y=${py(t)} dy="0.32em" text-anchor="end">${this.format(t)}</text>`,
+        )}
+        ${a !== null ? svg`<line class="base" x1=${px(a)} x2=${px(a)} y1=${M.top} y2=${M.top + ph}></line>` : nothing}
+        ${this.series.map((s, i) => {
+          const pts = this.x.map((_, j) => {
+            const v = s.values[j];
+            return v === null || v === undefined ? null : ([px(j), py(v)] as [number, number]);
+          });
+          const lone = pts.filter((p, j) => p && !pts[j - 1] && !pts[j + 1]) as [number, number][];
+          return svg`<path d=${linePath(pts)} fill="none" stroke=${seriesColour(i)} stroke-width="2" stroke-linejoin="round" stroke-linecap="round"></path>
+            ${lone.map((p) => svg`<circle cx=${p[0]} cy=${p[1]} r="2.5" fill=${seriesColour(i)}></circle>`)}`;
+        })}
+        ${a !== null
+          ? this.series.map((s, i) => {
+              const v = s.values[a];
+              return v === null || v === undefined
+                ? nothing
+                : svg`<circle cx=${px(a)} cy=${py(v)} r="4.5" fill=${seriesColour(i)} stroke="var(--card)" stroke-width="2"></circle>`;
+            })
+          : nothing}
+        ${this.x.map((label, j) =>
+          j % stride === 0
+            ? svg`<text class="axis" x=${px(j)} y=${h - 6} text-anchor=${n > 1 && j === 0 ? 'start' : n > 1 && j === n - 1 ? 'end' : 'middle'}>${label}</text>`
+            : nothing,
+        )}
+        ${this.x.map(
+          (_, j) => svg`<rect class="hit" x=${px(j) - hitW / 2} y=${M.top} width=${hitW} height=${ph + M.bottom}
+            @mouseenter=${() => (this.active = j)}></rect>`,
+        )}
+      </svg>
+      ${a !== null && a < n ? this.tip(px(a), M.top, this.tipBody(a)) : nothing}`;
+  }
+
+  private tipBody(j: number): TemplateResult {
+    const none = this.words.none;
+    return html`<b>${this.x[j]}</b>
+      ${this.series.map((s, i) => this.tipRow(seriesColour(i), s.name, s.values[j] === null || s.values[j] === undefined ? none : this.format(s.values[j])))}`;
+  }
+
+  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.series.map((s) => html`<th scope="col">${s.name}</th>`)}</tr></thead>
+      <tbody>${this.x.map(
+        (label, j) =>
+          html`<tr><th scope="row">${label}</th>${this.series.map((s) => html`<td>${s.values[j] === null || s.values[j] === undefined ? none : this.format(s.values[j])}</td>`)}</tr>`,
+      )}</tbody>
+    </table>`;
+  }
+}
+
+declare global {
+  interface HTMLElementTagNameMap {
+    'cae-line-chart': CaeLineChart;
+  }
+}

package/src/charts/scale.ts

@@ -0,0 +1,61 @@
+// The arithmetic the charts share: an axis of round numbers, the colours of the series.
+import type { ChartSeries } from './types.js';
+
+/** The series colours (`--series-1` ...), in their fixed order. */
+export const SERIES_COLOURS = 6;
+/** The colour of the series folded past the sixth, and of anything that is not a series. */
+export const OTHER_COLOUR = 'var(--meter)';
+
+/** Series `i`'s colour: the series colours in order, then the colour of "other". */
+export const seriesColour = (i: number): string => (i < SERIES_COLOURS ? `var(--series-${i + 1})` : OTHER_COLOUR);
+
+/** A series with its colour. */
+export interface DrawnSeries extends ChartSeries {
+  colour: string;
+  /** It stands for several series, folded into one. */
+  folded?: readonly string[];
+}
+
+/**
+ * The series as drawn: the first six each in its own colour, by their order (a series
+ * keeps its colour whatever its values); with more than six, the sixth and later are
+ * summed into one series named `other`, so no colour is ever made up.
+ */
+export function foldSeries(series: readonly ChartSeries[], other: string): DrawnSeries[] {
+  if (series.length <= SERIES_COLOURS) return series.map((s, i) => ({ ...s, colour: seriesColour(i) }));
+  const own = series.slice(0, SERIES_COLOURS - 1).map((s, i) => ({ ...s, colour: seriesColour(i) }));
+  const rest = series.slice(SERIES_COLOURS - 1);
+  const n = Math.max(...rest.map((s) => s.values.length));
+  const values = Array.from({ length: n }, (_, j) => {
+    const vs = rest.map((s) => s.values[j]).filter((v): v is number => v !== null && v !== undefined);
+    return vs.length ? vs.reduce((a, v) => a + v, 0) : null;
+  });
+  return [...own, { name: other, values, colour: OTHER_COLOUR, folded: rest.map((s) => s.name) }];
+}
+
+/** An axis from `low` (0 or below) to a round number at or above `high`, and its ticks (`count` or so). */
+export function niceAxis(low: number, high: number, count = 4): { min: number; max: number; ticks: number[] } {
+  const lo = Math.min(0, low);
+  const hi = Math.max(0, high);
+  if (!(hi > lo)) return { min: 0, max: 1, ticks: [0, 1] };
+  const raw = (hi - lo) / count;
+  const mag = 10 ** Math.floor(Math.log10(raw));
+  const step = [1, 2, 2.5, 5, 10].map((m) => m * mag).find((s) => s >= raw) ?? 10 * mag;
+  const min = Math.floor(lo / step) * step;
+  const max = Math.ceil(hi / step) * step;
+  const ticks: number[] = [];
+  for (let v = min; v <= max + step / 2; v += step) ticks.push(Math.round(v / step) * step);
+  return { min, max, ticks };
+}
+
+/** The space kept between two labels of an axis, in px. */
+export const LABEL_GAP = 12;
+
+/** Every `k`-th label of `n` fits in `width` px when a label is `labelWidth` px wide: the smallest such `k`. */
+export function labelStride(n: number, width: number, labelWidth: number): number {
+  if (n <= 0 || width <= 0) return 1;
+  return Math.max(1, Math.ceil((n * labelWidth) / width));
+}
+
+/** A number as written when the host gives no format: up to two decimals. */
+export const plainNumber = (v: number): string => String(Math.round(v * 100) / 100);