src/enhance/chart.ts

Functions

Imports

It imports src/enhance/marks.ts, src/enhance/motion.ts, src/enhance/sanitize.ts, src/enhance/targets.ts, src/enhance/types.ts. Imported by src/enhance/index.ts.

Source

1/** One enhanced chart: tooltips, keyboard navigation, filters, the range brush and updates. */
2
3import {
4  center,
5  invert,
6  label,
7  MARK,
8  parseScale,
9  place,
10  readingOrder,
11  SVG_NS,
12  shape,
13  svgPoint,
14} from "./marks.js";
15import { animateFrom, geometry, reducedMotion } from "./motion.js";
16import { sanitize } from "./sanitize.js";
17import { focusRing, hitArea } from "./targets.js";
18import type { BrushDetail, EnhancedChart, EnhanceOptions, SelectDetail } from "./types.js";
19
20/** How far a pointer moves, in SVG units, before a press becomes a drag (the brush). */
21const DRAG_THRESHOLD = 3;
22/** How long the entrance attribute stays on: longer than the slowest default animation (800ms). */
23const ENTRANCE_MS = 1000;
24/** How much of a chart must be on screen before it animates in. */
25const ENTRANCE_VISIBLE = 0.25;
26/** How long the tooltip waits for the pointer to reach it before hiding (WCAG 1.4.13, F6). */
27const HIDE_DELAY_MS = 300;
28/** The tooltip's gap from its mark and from the viewport edge, in CSS pixels. */
29const TIP_GAP = 8;
30
31export class Chart implements EnhancedChart {
32  readonly figure: HTMLElement;
33  readonly options: Required<EnhanceOptions>;
34  private readonly cleanup: (() => void)[] = [];
35  private tooltip: HTMLElement | null = null;
36  private live: HTMLElement | null = null;
37  private marks: SVGGraphicsElement[] = [];
38  private focusIndex = 0;
39  private anchorIndex: number | null = null;
40  private selected: { field: string; value: string } | null = null;
41  private brushRect: SVGRectElement | null = null;
42  /** The SVG's role as the server rendered it, restored by destroy(). */
43  private serverRole: string | null = null;
44  /** A wide frame whose tab stop attach() removed, given back by destroy(). */
45  private untabbedFrame: HTMLElement | null = null;
46  private ring: SVGGElement | null = null;
47  private hideTimer: ReturnType<typeof setTimeout> | undefined;
48  /** The first end of a range picked by clicking twice (A4). */
49  private rangeStart: number | null = null;
50
51  constructor(figure: HTMLElement, options: Required<EnhanceOptions>) {
52    this.figure = figure;
53    this.options = options;
54    this.attach();
55  }
56
57  private get svg(): SVGSVGElement | null {
58    return this.figure.querySelector("svg");
59  }
60
61  private get chartId(): string | null {
62    return this.figure.id || null;
63  }
64
65  private listen(target: EventTarget, type: string, handler: (event: Event) => void): void {
66    target.addEventListener(type, handler);
67    this.cleanup.push(() => target.removeEventListener(type, handler));
68  }
69
70  private attach(): void {
71    const svg = this.svg;
72    if (!svg) return;
73    this.figure.setAttribute("data-enarratio-enhanced", "");
74    if (this.options.filter) this.figure.setAttribute("data-enarratio-interactive", "");
75
76    const live = document.createElement("p");
77    live.className = "enarratio-visually-hidden";
78    live.setAttribute("aria-live", "polite");
79    this.figure.append(live);
80    this.live = live;
81
82    this.marks = readingOrder([...svg.querySelectorAll<SVGGraphicsElement>(MARK)]);
83    // With interactive marks inside, the SVG is a group of named buttons, not one opaque image.
84    this.serverRole ??= svg.getAttribute("role");
85    svg.setAttribute("role", "group");
86    svg.setAttribute("aria-roledescription", "chart");
87    this.marks.forEach((mark, i) => {
88      const text = label(mark);
89      mark.querySelector("title")?.remove();
90      // A bar that is a link without script becomes a filter button with it; the page can read the
91      // link from data-enarratio-href and follow it on enarratio:select if it wants to.
92      const href = mark.getAttribute("href");
93      if (href !== null) {
94        mark.setAttribute("data-enarratio-href", href);
95        mark.removeAttribute("href");
96      }
97      mark.setAttribute("aria-label", text);
98      const filterable = this.options.filter && mark.hasAttribute("data-enarratio-field");
99      mark.setAttribute("role", filterable ? "button" : "img");
100      if (filterable) mark.setAttribute("aria-pressed", "false");
101      mark.setAttribute("tabindex", i === 0 ? "0" : "-1");
102    });
103    // A focused mark scrolls the frame into view itself, so the frame's own tab stop (A13) would
104    // be a second, empty stop before the data.
105    const frame = this.figure.querySelector<HTMLElement>(":scope > .enarratio-frame");
106    if (this.marks.length > 0 && frame?.getAttribute("tabindex") === "0") {
107      frame.removeAttribute("tabindex");
108      this.untabbedFrame = frame;
109    }
110
111    if (this.options.tooltips) {
112      const tip = document.createElement("div");
113      tip.className = "enarratio-tooltip";
114      tip.hidden = true;
115      tip.setAttribute("aria-hidden", "true");
116      document.body.append(tip);
117      this.tooltip = tip;
118      // The pointer can move onto the tooltip without it vanishing (WCAG 1.4.13, F6).
119      this.listen(tip, "pointerenter", () => clearTimeout(this.hideTimer));
120      this.listen(tip, "pointerleave", () => this.hideTip());
121    }
122
123    for (const mark of this.marks) {
124      const targets: Element[] = [mark];
125      const hit = hitArea(mark);
126      if (hit) {
127        targets.push(hit);
128        this.cleanup.push(() => hit.remove());
129      }
130      for (const target of targets) {
131        this.listen(target, "pointerenter", () => this.showTip(mark));
132        this.listen(target, "pointerleave", () => this.scheduleHide());
133        if (this.options.filter) this.listen(target, "click", () => this.toggleMark(mark));
134      }
135      this.listen(mark, "focus", () => {
136        this.focusIndex = this.marks.indexOf(mark);
137        this.showTip(mark);
138        this.drawRing(mark);
139      });
140      this.listen(mark, "blur", () => {
141        this.hideTip();
142        this.ring?.remove();
143        this.ring = null;
144      });
145    }
146    this.listen(svg, "keydown", (e) => this.onKey(e as KeyboardEvent));
147
148    if (this.options.filter) this.attachLegend();
149    if (this.options.brush && parseScale(this.figure)) this.attachBrush(svg);
150    if (this.options.entrance) this.attachEntrance();
151  }
152
153  /** Draws the focus ring around a mark, replacing the last one. */
154  private drawRing(mark: SVGGraphicsElement): void {
155    this.ring?.remove();
156    this.ring = focusRing(mark);
157  }
158
159  private attachLegend(): void {
160    const field = this.figure.getAttribute("data-enarratio-series-field");
161    if (!field) return;
162    for (const item of this.figure.querySelectorAll<HTMLElement>(".enarratio-legend li")) {
163      const value = item.getAttribute("data-enarratio-series") ?? "";
164      const button = document.createElement("button");
165      button.type = "button";
166      button.setAttribute("aria-pressed", "false");
167      button.append(...item.childNodes);
168      item.append(button);
169      this.listen(button, "click", () => this.toggle(field, value));
170      this.cleanup.push(() => item.replaceChildren(...button.childNodes));
171    }
172  }
173
174  private attachBrush(svg: SVGSVGElement): void {
175    const scale = parseScale(this.figure);
176    if (!scale) return;
177    const [r0, r1] = scale.range as [number, number];
178    const view = svg.viewBox.baseVal;
179    let start: number | null = null;
180    const rect = document.createElementNS(SVG_NS, "rect");
181    rect.setAttribute("class", "enarratio-brush");
182    rect.setAttribute("y", "0");
183    rect.setAttribute("height", String(view.height || svg.height.baseVal.value));
184    rect.setAttribute("aria-hidden", "true");
185    rect.style.display = "none";
186    svg.prepend(rect);
187    this.brushRect = rect;
188    this.cleanup.push(() => rect.remove());
189
190    const clampX = (x: number): number => Math.min(Math.max(x, Math.min(r0, r1)), Math.max(r0, r1));
191    let dragging = false;
192    let dragged = false;
193    this.listen(svg, "pointerdown", (e) => {
194      const event = e as PointerEvent;
195      if (event.button !== 0) return;
196      start = clampX(svgPoint(svg, event).x);
197      dragging = false;
198    });
199    this.listen(svg, "pointermove", (e) => {
200      const event = e as PointerEvent;
201      if (start === null) return;
202      const x = clampX(svgPoint(svg, event).x);
203      if (!dragging) {
204        if (Math.abs(x - start) < DRAG_THRESHOLD) return;
205        // Capture only once this is a drag: capturing on pointerdown sent every click to the
206        // SVG instead of the mark under the pointer, so marks on these charts could not be
207        // clicked (F1).
208        dragging = true;
209        svg.setPointerCapture(event.pointerId);
210      }
211      this.drawBrush(start, x);
212    });
213    this.listen(svg, "pointerup", (e) => {
214      if (start === null) return;
215      const from = start;
216      start = null;
217      if (!dragging) return; // A click: the mark under the pointer, or the plot, handles it.
218      dragging = false;
219      dragged = true;
220      const end = clampX(svgPoint(svg, e as PointerEvent).x);
221      this.drawBrush(from, end);
222      this.emitBrush([invert(scale, Math.min(from, end)), invert(scale, Math.max(from, end))]);
223    });
224    // A range without dragging (WCAG 2.2 SC 2.5.7, A4): click the plot once for one end and again
225    // for the other. Clicks on marks filter instead.
226    this.listen(svg, "click", (e) => {
227      const event = e as MouseEvent;
228      if (dragged) {
229        dragged = false;
230        return;
231      }
232      const target = event.target as Element | null;
233      if (target?.closest(`${MARK}, .enarratio-hit`)) return;
234      const x = svgPoint(svg, event).x;
235      if (x < Math.min(r0, r1) || x > Math.max(r0, r1)) return;
236      if (this.rangeStart === null) {
237        this.rangeStart = x;
238        this.drawBrush(x, x + 1);
239        this.announce("Range start set; click again to set the end");
240        return;
241      }
242      const from = this.rangeStart;
243      this.rangeStart = null;
244      this.drawBrush(from, x);
245      this.emitBrush([invert(scale, Math.min(from, x)), invert(scale, Math.max(from, x))]);
246    });
247  }
248
249  private drawBrush(a: number, b: number): void {
250    if (!this.brushRect) return;
251    this.brushRect.style.display = "";
252    this.brushRect.setAttribute("x", String(Math.min(a, b)));
253    this.brushRect.setAttribute("width", String(Math.abs(b - a)));
254  }
255
256  private emitBrush(range: [number, number] | null): void {
257    const scale = parseScale(this.figure);
258    const time = scale?.type === "utc" || scale?.type === "time";
259    if (!range && this.brushRect) this.brushRect.style.display = "none";
260    const format = (n: number): string =>
261      time ? new Date(n).toISOString().slice(0, 10) : String(Math.round(n * 1000) / 1000);
262    this.announce(
263      range ? `Range selected: ${format(range[0])} to ${format(range[1])}` : "Range cleared",
264    );
265    this.figure.dispatchEvent(
266      new CustomEvent<BrushDetail>("enarratio:brush", {
267        bubbles: true,
268        detail: { chartId: this.chartId, range, time },
269      }),
270    );
271  }
272
273  private attachEntrance(): void {
274    if (reducedMotion() || typeof IntersectionObserver !== "function") return;
275    const svg = this.svg;
276    if (!svg) return;
277    for (const path of svg.querySelectorAll<SVGPathElement>(
278      '[data-enarratio-mark="line"] > path',
279    )) {
280      path.style.setProperty("--enarratio-length", String(Math.ceil(path.getTotalLength())));
281    }
282    const observer = new IntersectionObserver(
283      (entries) => {
284        if (!entries.some((entry) => entry.isIntersecting)) return;
285        observer.disconnect();
286        this.figure.setAttribute("data-enarratio-entering", "");
287        const done = setTimeout(
288          () => this.figure.removeAttribute("data-enarratio-entering"),
289          ENTRANCE_MS,
290        );
291        this.cleanup.push(() => clearTimeout(done));
292      },
293      { threshold: ENTRANCE_VISIBLE },
294    );
295    observer.observe(this.figure);
296    this.cleanup.push(() => observer.disconnect());
297  }
298
299  private showTip(mark: SVGGraphicsElement): void {
300    const tip = this.tooltip;
301    if (!tip) return;
302    clearTimeout(this.hideTimer);
303    tip.textContent = label(mark);
304    tip.hidden = false;
305    const box = mark.getBoundingClientRect();
306    const tipBox = tip.getBoundingClientRect();
307    const left = Math.min(
308      Math.max(TIP_GAP, box.left + box.width / 2 - tipBox.width / 2),
309      document.documentElement.clientWidth - tipBox.width - TIP_GAP,
310    );
311    const above = box.top - tipBox.height - TIP_GAP;
312    tip.style.left = `${left + scrollX}px`;
313    tip.style.top = `${(above > 0 ? above : box.bottom + TIP_GAP) + scrollY}px`;
314  }
315
316  private hideTip(): void {
317    clearTimeout(this.hideTimer);
318    if (this.tooltip) this.tooltip.hidden = true;
319  }
320
321  /** Hides the tooltip shortly, unless the pointer reaches it first. */
322  private scheduleHide(): void {
323    clearTimeout(this.hideTimer);
324    this.hideTimer = setTimeout(() => this.hideTip(), HIDE_DELAY_MS);
325  }
326
327  private onKey(event: KeyboardEvent): void {
328    if (this.marks.length === 0) return;
329    const current = this.marks[this.focusIndex];
330    let next = this.focusIndex;
331    switch (event.key) {
332      case "ArrowRight":
333      case "ArrowLeft":
334        next = this.column(event.key === "ArrowRight" ? 1 : -1);
335        break;
336      case "ArrowUp":
337      case "ArrowDown":
338        next = this.stack(event.key === "ArrowUp" ? 1 : -1);
339        break;
340      case "Home":
341        next = 0;
342        break;
343      case "End":
344        next = this.marks.length - 1;
345        break;
346      case "Enter":
347      case " ":
348        if (current && this.options.filter) this.toggleMark(current);
349        event.preventDefault();
350        return;
351      case "Escape":
352        // Dismisses the tooltip (WCAG 1.4.13, F6) and clears the filter and range.
353        this.hideTip();
354        this.clearAll(true);
355        return;
356      default:
357        return;
358    }
359    event.preventDefault();
360    if (event.shiftKey && this.brushRect) {
361      this.anchorIndex ??= this.focusIndex;
362    } else {
363      this.anchorIndex = null;
364    }
365    this.moveFocus(next);
366    if (this.anchorIndex !== null) this.brushBetween(this.anchorIndex, next);
367  }
368
369  private columnOf(index: number): number | null {
370    const mark = this.marks[index];
371    return mark ? place(mark).column : null;
372  }
373
374  /** The first mark in the next or previous column, so arrows step category by category. */
375  private column(step: 1 | -1): number {
376    const here = this.columnOf(this.focusIndex);
377    if (here === null) return this.focusIndex;
378    for (let i = this.focusIndex + step; i >= 0 && i < this.marks.length; i += step) {
379      const col = this.columnOf(i);
380      if (col !== null && col !== here) {
381        if (step === 1) return i;
382        // Moving left lands on the bottom of the column, as moving right does.
383        let first = i;
384        while (first > 0 && this.columnOf(first - 1) === col) first -= 1;
385        return first;
386      }
387    }
388    return this.focusIndex;
389  }
390
391  /** The mark above or below in the same column (a stack), or the current one at its end. */
392  private stack(step: 1 | -1): number {
393    const here = this.columnOf(this.focusIndex);
394    const there = this.columnOf(this.focusIndex + step);
395    return here !== null && there === here ? this.focusIndex + step : this.focusIndex;
396  }
397
398  private moveFocus(index: number, focus = true): void {
399    const from = this.marks[this.focusIndex];
400    const to = this.marks[index];
401    if (!to) return;
402    from?.setAttribute("tabindex", "-1");
403    to.setAttribute("tabindex", "0");
404    this.focusIndex = index;
405    if (focus) to.focus();
406  }
407
408  /**
409   * The mark to carry the tab stop after an update: the same key if it still exists, else the
410   * first mark in the same category, else the mark at the nearest position in reading order.
411   */
412  private successor(key: string, x: string | null, index: number): number {
413    const same = this.marks.findIndex((m) => m.getAttribute("data-enarratio-key") === key);
414    if (same !== -1) return same;
415    const column =
416      x === null ? -1 : this.marks.findIndex((m) => m.getAttribute("data-enarratio-x") === x);
417    if (column !== -1) return column;
418    return Math.min(index, this.marks.length - 1);
419  }
420
421  private brushBetween(a: number, b: number): void {
422    const scale = parseScale(this.figure);
423    const ma = this.marks[a];
424    const mb = this.marks[b];
425    if (!scale || !ma || !mb) return;
426    const xa = center(ma).x;
427    const xb = center(mb).x;
428    this.drawBrush(xa, xb);
429    this.emitBrush([invert(scale, Math.min(xa, xb)), invert(scale, Math.max(xa, xb))]);
430  }
431
432  private toggleMark(mark: Element): void {
433    const field = mark.getAttribute("data-enarratio-field");
434    const value = mark.getAttribute("data-enarratio-value");
435    if (field === null || value === null) return;
436    this.toggle(field, value, mark.getAttribute("data-enarratio-x") ?? undefined);
437  }
438
439  private toggle(field: string, value: string, x?: string): void {
440    const same = this.selected?.field === field && this.selected.value === value;
441    this.select(same ? null : { field, value }, true, x);
442  }
443
444  private select(next: { field: string; value: string } | null, notify: boolean, x?: string): void {
445    const previous = this.selected;
446    this.selected = next;
447    const seriesField = this.figure.getAttribute("data-enarratio-series-field");
448    // A filter on the series field matches by series even where a click filters by x, so a
449    // legend entry or setFilter can emphasize one series on a chart that selects years.
450    const bySeries = next !== null && next.field === seriesField;
451    for (const mark of this.marks) {
452      const match =
453        next !== null &&
454        (bySeries
455          ? mark.getAttribute("data-enarratio-series") === next.value
456          : mark.getAttribute("data-enarratio-field") === next.field &&
457            mark.getAttribute("data-enarratio-value") === next.value);
458      mark.toggleAttribute("data-enarratio-dimmed", next !== null && !match);
459      if (mark.hasAttribute("aria-pressed")) mark.setAttribute("aria-pressed", String(match));
460    }
461    for (const button of this.figure.querySelectorAll<HTMLButtonElement>(
462      ".enarratio-legend button",
463    )) {
464      const value = button.parentElement?.getAttribute("data-enarratio-series");
465      button.setAttribute("aria-pressed", String(bySeries && value === next?.value));
466    }
467    const field = next?.field ?? previous?.field;
468    if (field === undefined || !notify) return;
469    this.announce(next ? `Filtered to ${next.value}` : "Filter cleared");
470    this.figure.dispatchEvent(
471      new CustomEvent<SelectDetail>("enarratio:select", {
472        bubbles: true,
473        detail: {
474          chartId: this.chartId,
475          field,
476          value: next?.value ?? null,
477          ...(x === undefined ? {} : { x }),
478        },
479      }),
480    );
481  }
482
483  private announce(message: string): void {
484    if (this.live) this.live.textContent = message;
485  }
486
487  setFilter(filter: { readonly field: string; readonly value: string } | null): void {
488    this.select(filter ? { field: filter.field, value: filter.value } : null, false);
489  }
490
491  clear(): void {
492    this.clearAll(false);
493  }
494
495  private clearAll(notify: boolean): void {
496    this.rangeStart = null;
497    if (this.selected) this.select(null, notify);
498    if (this.brushRect && this.brushRect.style.display !== "none") {
499      if (notify) this.emitBrush(null);
500      else this.brushRect.style.display = "none";
501    }
502    this.anchorIndex = null;
503  }
504
505  update(markup: string): void {
506    // DOMParser builds an inert document: nothing in it loads or runs while it is checked.
507    const parsed = new DOMParser().parseFromString(markup.trim(), "text/html");
508    const candidate = parsed.body.firstElementChild;
509    if (!candidate?.matches("figure.enarratio")) {
510      throw new Error("update() needs the markup of one Enarratio figure");
511    }
512    sanitize(candidate);
513    const incoming = document.importNode(candidate, true);
514    const before = geometry(this.figure);
515    const selected = this.selected;
516    // The tab stop (and focus, if a reader is in the chart) moves to the same mark after the swap.
517    const stop = this.marks[this.focusIndex];
518    const stopKey = stop?.getAttribute("data-enarratio-key") ?? null;
519    const stopX = stop?.getAttribute("data-enarratio-x") ?? null;
520    const stopIndex = this.focusIndex;
521    const hadFocus = stop !== undefined && document.activeElement === stop;
522    this.teardown();
523    for (const name of this.figure.getAttributeNames()) this.figure.removeAttribute(name);
524    for (const name of incoming.getAttributeNames()) {
525      this.figure.setAttribute(name, incoming.getAttribute(name) ?? "");
526    }
527    this.figure.replaceChildren(...incoming.childNodes);
528    this.attach();
529    // Restoring the page's own selection is not news to the page, so it fires nothing.
530    if (selected) this.select(selected, false);
531    if (stopKey !== null && this.marks.length > 0) {
532      this.moveFocus(this.successor(stopKey, stopX, stopIndex), hadFocus);
533    }
534    if (!reducedMotion()) animateFrom(this.figure, before);
535  }
536
537  private teardown(): void {
538    for (const undo of this.cleanup.splice(0)) undo();
539    clearTimeout(this.hideTimer);
540    this.ring?.remove();
541    this.ring = null;
542    this.rangeStart = null;
543    this.tooltip?.remove();
544    this.tooltip = null;
545    this.live?.remove();
546    this.live = null;
547    this.brushRect = null;
548    this.marks = [];
549    this.focusIndex = 0;
550    this.anchorIndex = null;
551  }
552
553  destroy(): void {
554    this.teardown();
555    const svg = this.svg;
556    if (svg) {
557      svg.setAttribute("role", this.serverRole ?? "img");
558      if (this.serverRole !== "group") svg.removeAttribute("aria-roledescription");
559      for (const mark of svg.querySelectorAll(MARK)) {
560        const text = mark.getAttribute("aria-label");
561        const href = mark.getAttribute("data-enarratio-href");
562        if (href !== null) {
563          mark.setAttribute("href", href);
564          mark.removeAttribute("data-enarratio-href");
565        }
566        for (const name of ["role", "aria-pressed", "tabindex", "data-enarratio-dimmed"]) {
567          mark.removeAttribute(name);
568        }
569        // Links keep their name, as the server rendered them; other marks get their title back.
570        if (href === null) mark.removeAttribute("aria-label");
571        if (text) {
572          const title = document.createElementNS(SVG_NS, "title");
573          title.textContent = text;
574          shape(mark).append(title);
575        }
576      }
577    }
578    this.untabbedFrame?.setAttribute("tabindex", "0");
579    this.untabbedFrame = null;
580    for (const name of [
581      "data-enarratio-enhanced",
582      "data-enarratio-interactive",
583      "data-enarratio-entering",
584    ]) {
585      this.figure.removeAttribute(name);
586    }
587    enhanced.delete(this.figure);
588  }
589}
590
591export const enhanced = new WeakMap<HTMLElement, Chart>();