src/enhance/types.ts

Functions

None: it only declares types or values.

Imports

It imports no other module of this repo. Imported by src/enhance/chart.ts, src/enhance/index.ts.

Source

1/** The enhancement layer's public types and the events it fires. */
2
3/** Detail of the `enarratio:select` event, fired when a reader selects or clears a filter. */
4export interface SelectDetail {
5  /** The figure's `id`, or null when the chart was rendered without one. */
6  readonly chartId: string | null;
7  /** The data field the filter applies to, e.g. `"type"`. */
8  readonly field: string;
9  /** The value selected, e.g. `"Publications"`; null when the filter was cleared. */
10  readonly value: string | null;
11  /** The category of the mark selected, when a mark (not a legend entry) was used. */
12  readonly x?: string;
13}
14
15/** Detail of the `enarratio:brush` event, fired when a reader picks or clears a range. */
16export interface BrushDetail {
17  readonly chartId: string | null;
18  /**
19   * The range in data units, low then high: numbers, or milliseconds since the epoch on a time
20   * axis. Null when the range was cleared.
21   */
22  readonly range: readonly [number, number] | null;
23  /** Whether the axis is time, so the range holds epoch milliseconds. */
24  readonly time: boolean;
25}
26
27declare global {
28  interface HTMLElementEventMap {
29    "enarratio:select": CustomEvent<SelectDetail>;
30    "enarratio:brush": CustomEvent<BrushDetail>;
31  }
32}
33
34/** Options for {@link enhance}. Every feature is on unless turned off. */
35export interface EnhanceOptions {
36  /** Show a hover and focus tooltip with each mark's details. */
37  readonly tooltips?: boolean;
38  /** Let a click, Enter or Space on a mark or legend entry filter by its value. */
39  readonly filter?: boolean;
40  /** Let a drag, or Shift with arrow keys, pick a range on charts with a continuous x axis. */
41  readonly brush?: boolean;
42  /** Animate charts in the first time they scroll into view. */
43  readonly entrance?: boolean;
44}
45
46/** A chart the enhancement layer is attached to. */
47export interface EnhancedChart {
48  readonly figure: HTMLElement;
49  /** The options the chart was enhanced with, every default filled in. */
50  readonly options: Readonly<Required<EnhanceOptions>>;
51  /**
52   * Replaces the chart with new server-rendered markup for the same chart, animating marks that
53   * share a key from their old shape to their new one. The filter, the tab stop and keyboard
54   * focus stay on the mark with the same key, or the nearest one if it is gone.
55   *
56   * The markup should come from Enarratio. It is parsed inertly and sanitized before it touches
57   * the page: only the elements and attributes Enarratio emits are kept, and event handlers,
58   * scripts and unsafe links are dropped (F11).
59   */
60  update(markup: string): void;
61  /**
62   * Shows a filter the page chose (from its own controls, or a URL) without firing
63   * `enarratio:select`: the page already knows. A filter on the series field emphasizes that
64   * series even where clicks filter by x. `null` clears it.
65   */
66  setFilter(filter: { readonly field: string; readonly value: string } | null): void;
67  /**
68   * Clears any filter and range the page wants gone, without firing events. A reader pressing
69   * Escape clears them too, and that does fire events.
70   */
71  clear(): void;
72  /** Removes every listener and element the layer added, leaving the server markup. */
73  destroy(): void;
74}