expressive-charts 0.3.0 → 0.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (46) hide show
  1. package/CHANGELOG.md +73 -1
  2. package/README.md +7 -7
  3. package/dist/define-DeZLs1h7.js +95 -0
  4. package/dist/define-DeZLs1h7.js.map +1 -0
  5. package/dist/drawing-Ypmq-2h6.d.cts +214 -0
  6. package/dist/drawing-Ypmq-2h6.d.ts +214 -0
  7. package/dist/effect-C786hGyJ.d.cts +232 -0
  8. package/dist/effect-CMo-2gPf.d.ts +232 -0
  9. package/dist/expressive-charts.css +5 -2
  10. package/dist/expressive-charts.css.d.cts +1 -2
  11. package/dist/expressive-charts.css.d.ts +1 -2
  12. package/dist/expressive-charts.global.js +47 -48
  13. package/dist/expressive-charts.global.js.map +1 -1
  14. package/dist/icons/sport.cjs +211 -156
  15. package/dist/icons/sport.cjs.map +1 -1
  16. package/dist/icons/sport.d.cts +5 -7
  17. package/dist/icons/sport.d.ts +5 -7
  18. package/dist/icons/sport.js +122 -71
  19. package/dist/icons/sport.js.map +1 -1
  20. package/dist/index.cjs +13203 -9982
  21. package/dist/index.cjs.map +1 -1
  22. package/dist/index.d.cts +953 -871
  23. package/dist/index.d.ts +953 -871
  24. package/dist/index.js +11000 -8234
  25. package/dist/index.js.map +1 -1
  26. package/dist/path-data-DnEckjY8.js +123 -0
  27. package/dist/path-data-DnEckjY8.js.map +1 -0
  28. package/dist/testing.cjs +2047 -1255
  29. package/dist/testing.cjs.map +1 -1
  30. package/dist/testing.d.cts +135 -139
  31. package/dist/testing.d.ts +135 -139
  32. package/dist/testing.js +696 -499
  33. package/dist/testing.js.map +1 -1
  34. package/dist/transition-Bu1NsQor.js +2067 -0
  35. package/dist/transition-Bu1NsQor.js.map +1 -0
  36. package/package.json +6 -6
  37. package/dist/chunk-7A7LXXT4.js +0 -70
  38. package/dist/chunk-7A7LXXT4.js.map +0 -1
  39. package/dist/chunk-CJUQHEX6.js +0 -618
  40. package/dist/chunk-CJUQHEX6.js.map +0 -1
  41. package/dist/chunk-N2BLUETM.js +0 -1194
  42. package/dist/chunk-N2BLUETM.js.map +0 -1
  43. package/dist/drawing-CdTgixMY.d.cts +0 -206
  44. package/dist/drawing-CdTgixMY.d.ts +0 -206
  45. package/dist/effect-Bu3MHHeg.d.ts +0 -247
  46. package/dist/effect-D4vmdYP4.d.cts +0 -247
package/dist/index.d.ts CHANGED
@@ -1,83 +1,79 @@
1
- import { d as Timing, e as Easing, f as TweenResult, g as MotionEnv, h as MarkEffect, i as Sample, M as MarkData, a as Motion, c as MotionMode, T as TransitionEffect, G as GeometryEffect, D as DataEffect, A as AnyMarkEffect, C as Combined, E as EffectContext } from './effect-Bu3MHHeg.js';
2
- export { j as Clock, F as FrameSource, b as ManualClock, k as MotionOptions, l as MotionView, R as ReducedMotionSource, S as ScalingOverrides, m as ScalingRule, n as ScalingTable, o as TransitionContext, p as Tween, q as TweenOptions, r as createClock, s as createMotion, t as defaultClock, u as defaultScaling, v as easeInOutCubic, w as easeOutCubic, x as linear, y as manualClock, z as mediaReducedMotion, B as motion, H as scaleDuration, I as tween } from './effect-Bu3MHHeg.js';
3
- import { e as Point, R as Rect, M as MarkGeometry, a as Matrix, C as Color, I as Icon } from './drawing-CdTgixMY.js';
4
- export { f as IconHandle, g as IconShape, d as IconSource, L as Layer, c as MarkHandle, b as MarkStyle, O as Outline, P as Paint, h as PathHandle, i as TextHandle, T as TextStyle } from './drawing-CdTgixMY.js';
5
-
1
+ import { A as Easing, C as ScalingTable, D as mediaReducedMotion, E as defaultScaling, F as FrameSource, I as ManualClock, L as createClock, M as easeOutCubic, N as linear, O as motion, P as Clock, R as defaultClock, S as ScalingRule, T as createMotion, _ as MotionMode, a as GeometryEffect, b as ReducedMotionSource, c as TransitionEffect, d as MotionEnv, f as Tween, g as Motion, h as tween, i as EffectContext, j as easeInOutCubic, k as scaleDuration, l as MarkData, m as TweenResult, n as Combined, o as MarkEffect, p as TweenOptions, r as DataEffect, s as TransitionContext, t as AnyMarkEffect, u as Sample, v as MotionOptions, w as Timing, x as ScalingOverrides, y as MotionView, z as manualClock } from "./effect-CMo-2gPf.js";
2
+ import { _ as Rect, a as MarkStyle, c as PathHandle, d as Icon, f as IconShape, g as Point, h as Outline, i as MarkHandle, l as TextHandle, m as MarkGeometry, n as IconHandle, o as Matrix, p as IconSource, r as Layer, s as Paint, t as Color, u as TextStyle } from "./drawing-Ypmq-2h6.js";
6
3
  /** Builds a function that blends `from` into `to` as t goes from 0 to 1. */
7
4
  type Interpolator<T> = (from: T, to: T) => (t: number) => T;
8
5
  /** Exact at both ends, so a finished animation lands on its target. */
9
- declare const interpolateNumber: Interpolator<number>;
10
- declare const interpolatePoint: Interpolator<Point>;
6
+ export declare const interpolateNumber: Interpolator<number>;
7
+ export declare const interpolatePoint: Interpolator<Point>;
11
8
  /**
12
9
  * Blends every key. A key missing on one side counts as 0 there, so a series
13
10
  * that appears grows from 0, and one that disappears shrinks to 0 and is gone at t = 1.
14
11
  */
15
- declare function interpolateRecord<K extends string>(a: Readonly<Record<K, number>>, b: Readonly<Record<K, number>>): (t: number) => Record<K, number>;
12
+ export declare function interpolateRecord<K extends string>(a: Readonly<Record<K, number>>, b: Readonly<Record<K, number>>): (t: number) => Record<K, number>;
16
13
  interface AnimateOptions {
17
- /** Base duration in ms, scaled by the motion mode. */
18
- readonly duration: number;
19
- /** Default "transition". */
20
- readonly timing?: Timing;
21
- /** Default easeInOutCubic, or easeOutCubic when this interrupts a moving value and starts at once (no delay). */
22
- readonly ease?: Easing;
23
- readonly delay?: number;
24
- readonly signal?: AbortSignal;
14
+ /** Base duration in ms, scaled by the motion mode. */
15
+ readonly duration: number;
16
+ /** Default "transition". */
17
+ readonly timing?: Timing;
18
+ /** Default easeInOutCubic, or easeOutCubic when this interrupts a moving value and starts at once (no delay). */
19
+ readonly ease?: Easing;
20
+ readonly delay?: number;
21
+ readonly signal?: AbortSignal;
25
22
  }
26
23
  interface AnimatedOptions<T> extends Partial<MotionEnv> {
27
- /** Called whenever the value changes, including every animation frame. */
28
- readonly onChange?: (value: T) => void;
24
+ /** Called whenever the value changes, including every animation frame. */
25
+ readonly onChange?: (value: T) => void;
29
26
  }
30
27
  /** A value that can be retargeted mid-flight. */
31
28
  interface Animated<T> {
32
- /** The current value, in between while animating. */
33
- readonly value: T;
34
- /** Where the value is heading (equal to `value` when at rest). */
35
- readonly target: T;
36
- readonly animating: boolean;
37
- /** Animate from the current value, cancelling any animation already running. */
38
- to(target: T, options: AnimateOptions): Promise<TweenResult>;
39
- /** Jump to a value, cancelling any running animation. */
40
- set(value: T): void;
41
- /** Stop where it is; the current value becomes the target. */
42
- stop(): void;
43
- }
44
- declare function animated<T>(initial: T, interpolate: Interpolator<T>, options?: AnimatedOptions<T>): Animated<T>;
45
-
29
+ /** The current value, in between while animating. */
30
+ readonly value: T;
31
+ /** Where the value is heading (equal to `value` when at rest). */
32
+ readonly target: T;
33
+ readonly animating: boolean;
34
+ /** Animate from the current value, cancelling any animation already running. */
35
+ to(target: T, options: AnimateOptions): Promise<TweenResult>;
36
+ /** Jump to a value, cancelling any running animation. */
37
+ set(value: T): void;
38
+ /** Stop where it is; the current value becomes the target. */
39
+ stop(): void;
40
+ }
41
+ export declare function animated<T>(initial: T, interpolate: Interpolator<T>, options?: AnimatedOptions<T>): Animated<T>;
46
42
  interface PlaybackOptions extends Partial<MotionEnv> {
47
- /** Where a play starts again once it's at the end. */
48
- readonly from: number;
49
- /** Where a play ends. The playback starts here, at rest, as a chart shows all its data until something reveals less. */
50
- readonly to: number;
51
- /** Base ms for a play from `from` to `to`, scaled by `timing`. A play from part way takes its share, so the speed stays the same. */
52
- readonly duration: number;
53
- /** How a play moves. Default linear: constant speed. Seeks ease on their own. */
54
- readonly ease?: Easing;
55
- /** Default "playback": ×1 in Presentation, ×0.3 in Analysis, a jump in Off. */
56
- readonly timing?: Timing;
57
- /** Draws a position. Called whenever the position changes: every frame of a play or a seek, and every jump. */
58
- readonly onFrame: (position: number) => void;
43
+ /** Where a play starts again once it's at the end. */
44
+ readonly from: number;
45
+ /** Where a play ends. The playback starts here, at rest, as a chart shows all its data until something reveals less. */
46
+ readonly to: number;
47
+ /** Base ms for a play from `from` to `to`, scaled by `timing`. A play from part way takes its share, so the speed stays the same. */
48
+ readonly duration: number;
49
+ /** How a play moves. Default linear: constant speed. Seeks ease on their own. */
50
+ readonly ease?: Easing;
51
+ /** Default "playback": ×1 in Presentation, ×0.3 in Analysis, a jump in Off. */
52
+ readonly timing?: Timing;
53
+ /** Draws a position. Called whenever the position changes: every frame of a play or a seek, and every jump. */
54
+ readonly onFrame: (position: number) => void;
59
55
  }
60
56
  /** What `subscribe` hears. Frames go to `onFrame` instead. */
61
57
  type PlaybackEvent = "play" | "pause" | "end" | "seek";
62
58
  interface SeekOptions {
63
- /** Default true: move over 350 ms base transition timing (at most 200 ms in Analysis, a jump in Off). false jumps. */
64
- readonly animate?: boolean;
59
+ /** Default true: move over 350 ms base transition timing (at most 200 ms in Analysis, a jump in Off). false jumps. */
60
+ readonly animate?: boolean;
65
61
  }
66
62
  interface Playback {
67
- /** Plays on from where it is to `to`, or from `from` when it's at the end. Does nothing while playing. */
68
- play(): void;
69
- /** Stops a play where it is. Does nothing unless it's playing, so a seek on its way still lands. */
70
- pause(): void;
71
- /** Pauses, and moves to `x`, clamped to the range. A seek while it's moving starts from where it is. */
72
- seek(x: number, options?: SeekOptions): void;
73
- /** Where it is now, in between while it moves. */
74
- readonly position: number;
75
- /** True from `play()` until a pause, a seek or the end. */
76
- readonly playing: boolean;
77
- /** Hears play, pause, the end and seeks, not every frame. Returns a function that stops listening. */
78
- subscribe(listener: (event: PlaybackEvent) => void): () => void;
79
- /** Pauses it, if it's playing, and stops it for good: later calls do nothing. */
80
- destroy(): void;
63
+ /** Plays on from where it is to `to`, or from `from` when it's at the end. Does nothing while playing. */
64
+ play(): void;
65
+ /** Stops a play where it is. Does nothing unless it's playing, so a seek on its way still lands. */
66
+ pause(): void;
67
+ /** Pauses, and moves to `x`, clamped to the range. A seek while it's moving starts from where it is. */
68
+ seek(x: number, options?: SeekOptions): void;
69
+ /** Where it is now, in between while it moves. */
70
+ readonly position: number;
71
+ /** True from `play()` until a pause, a seek or the end. */
72
+ readonly playing: boolean;
73
+ /** Hears play, pause, the end and seeks, not every frame. Returns a function that stops listening. */
74
+ subscribe(listener: (event: PlaybackEvent) => void): () => void;
75
+ /** Pauses it, if it's playing, and stops it for good: later calls do nothing. */
76
+ destroy(): void;
81
77
  }
82
78
  /**
83
79
  * A playback through `from`…`to`. `play()` moves the position at constant speed (with the default
@@ -85,8 +81,7 @@ interface Playback {
85
81
  * off, a play jumps to the end, and motion turning off mid-play jumps there too, as tweens do. Nothing
86
82
  * plays by itself. Uses the page-wide motion and clock unless given its own.
87
83
  */
88
- declare function playback(options: PlaybackOptions): Playback;
89
-
84
+ export declare function playback(options: PlaybackOptions): Playback;
90
85
  /** The events effects attach to. */
91
86
  type EffectSlot = "hover" | "enter" | "update" | "exit" | "decorate";
92
87
  /**
@@ -100,92 +95,95 @@ type EffectOption<D> = MarkEffect<D> | PresetName;
100
95
  * effect such as threshold() can't widen the chart's row type to unknown.
101
96
  */
102
97
  interface EffectSlots<D> {
103
- /** On pointer hover or keyboard focus; cleared on leave, replayed after a data transition. */
104
- readonly hover?: EffectOption<D>;
105
- /** When a mark appears. */
106
- readonly enter?: EffectOption<D>;
107
- /** When a mark's values change (not on a re-sort alone). */
108
- readonly update?: EffectOption<D>;
109
- /** Before a mark is removed; removal waits for it. */
110
- readonly exit?: EffectOption<D>;
111
- /** From enter until exit, following every geometry change. */
112
- readonly decorate?: EffectOption<D>;
113
- }
114
-
98
+ /** On pointer hover or keyboard focus; cleared on leave, replayed after a data transition. */
99
+ readonly hover?: EffectOption<D>;
100
+ /** When a mark appears. */
101
+ readonly enter?: EffectOption<D>;
102
+ /** When a mark's values change (not on a re-sort alone). */
103
+ readonly update?: EffectOption<D>;
104
+ /** Before a mark is removed; removal waits for it. */
105
+ readonly exit?: EffectOption<D>;
106
+ /** From enter until exit, following every geometry change. */
107
+ readonly decorate?: EffectOption<D>;
108
+ }
115
109
  interface ArcSpec {
116
- readonly key: string;
117
- readonly series?: string;
118
- /** The donut's centre. */
119
- readonly cx: number;
120
- readonly cy: number;
121
- /** Radii in px; 0 inner makes a pie slice. They're swapped if inner > outer, as d3.arc() does. */
122
- readonly inner: number;
123
- readonly outer: number;
124
- /** Radians, 0 at 12 o'clock, clockwise: the d3.pie() convention. end < start walks anticlockwise. */
125
- readonly start: number;
126
- readonly end: number;
127
- /** The boxes of the text drawn for the mark, in the same px: passed through as `labelBounds`. */
128
- readonly labelBounds?: readonly Rect[];
110
+ readonly key: string;
111
+ readonly series?: string;
112
+ /** The donut's centre. */
113
+ readonly cx: number;
114
+ readonly cy: number;
115
+ /** Radii in px; 0 inner makes a pie slice. They're swapped if inner > outer, as d3.arc() does. */
116
+ readonly inner: number;
117
+ readonly outer: number;
118
+ /** Radians, 0 at 12 o'clock, clockwise: the d3.pie() convention. end < start walks anticlockwise. */
119
+ readonly start: number;
120
+ readonly end: number;
121
+ /** The boxes of the text drawn for the mark, in the same px: passed through as `labelBounds`. */
122
+ readonly labelBounds?: readonly Rect[];
123
+ /** The boxes of other marks' text near it, in the same px: passed through as `nearbyLabels`. */
124
+ readonly nearbyLabels?: readonly Rect[];
129
125
  }
130
126
  /**
131
127
  * The walk runs along the mid-radius arc from the start angle to the end angle, so for a slice
132
128
  * walked clockwise "up" is outward. The angle of travel equals the d3 angle (normalised).
133
129
  */
134
130
  declare function describeArc(spec: ArcSpec): MarkGeometry;
135
-
136
131
  /** The edge a bar grows from. */
137
132
  type Baseline = "left" | "right" | "top" | "bottom";
138
133
  interface BarSegmentSpec {
139
- readonly series: string;
140
- /** Px along the walk, gap included. */
141
- readonly size: number;
134
+ readonly series: string;
135
+ /** Px along the walk, gap included. */
136
+ readonly size: number;
142
137
  }
143
138
  interface BarSpec {
144
- readonly key: string;
145
- readonly series?: string;
146
- /** The whole bar's rectangle, in chart px. */
147
- readonly x: number;
148
- readonly y: number;
149
- readonly width: number;
150
- readonly height: number;
151
- readonly baseline: Baseline;
152
- /** Corner radius at the tip. The baseline end stays square. Default 0. */
153
- readonly radius?: number;
154
- /**
155
- * Ordered parts, from the baseline. Default: one segment named after `series`, covering the bar.
156
- * Sizes normally add up to the bar's length; anything past the tip is cut off.
157
- */
158
- readonly segments?: readonly BarSegmentSpec[];
159
- /**
160
- * Px left empty between segments (the prototype uses 2). It comes out of the start of the later
161
- * segment, so every segment still ends at its value, and it shrinks to fit when what comes
162
- * before is shorter. Default 0.
163
- */
164
- readonly gap?: number;
165
- /** The boxes of the text drawn for the bar, its segments having none, in the same px: passed through as `labelBounds`. */
166
- readonly labelBounds?: readonly Rect[];
139
+ readonly key: string;
140
+ readonly series?: string;
141
+ /** The whole bar's rectangle, in chart px. */
142
+ readonly x: number;
143
+ readonly y: number;
144
+ readonly width: number;
145
+ readonly height: number;
146
+ readonly baseline: Baseline;
147
+ /** Corner radius at the tip. The baseline end stays square. Default 0. */
148
+ readonly radius?: number;
149
+ /**
150
+ * Ordered parts, from the baseline. Default: one segment named after `series`, covering the bar.
151
+ * Sizes normally add up to the bar's length; anything past the tip is cut off.
152
+ */
153
+ readonly segments?: readonly BarSegmentSpec[];
154
+ /**
155
+ * Px left empty between segments (the prototype uses 2). It comes out of the start of the later
156
+ * segment, so every segment still ends at its value, and it shrinks to fit when what comes
157
+ * before is shorter. Default 0.
158
+ */
159
+ readonly gap?: number;
160
+ /** The boxes of the text drawn for the bar, its segments having none, in the same px: passed through as `labelBounds`. */
161
+ readonly labelBounds?: readonly Rect[];
162
+ /** The boxes of other marks' text near the bar, its segments having none, in the same px: passed through as `nearbyLabels`. */
163
+ readonly nearbyLabels?: readonly Rect[];
167
164
  }
168
165
  /**
169
166
  * The walk runs along the centre line from the middle of the baseline edge to the middle of the
170
167
  * tip. A plain bar has one segment, so `travel(…, { along: "goals" })` works stacked or not.
171
168
  */
172
169
  declare function describeBar(spec: BarSpec): MarkGeometry;
173
-
174
170
  interface LineSpec {
175
- readonly key: string;
176
- readonly series?: string;
177
- /** At least one point, in chart px. */
178
- readonly points: readonly Point[];
179
- /**
180
- * The indices of the points that start a new run, so there's a gap from `points[i - 1]` to
181
- * `points[i]`: each a whole number from 1 to the last index, in order, with no repeats. A line
182
- * drawn with d3's `.defined()` is described by its defined points and where they break. Default none.
183
- */
184
- readonly breaks?: readonly number[];
185
- /** Stroke width in px. Default 1, SVG's default. */
186
- readonly width?: number;
187
- /** The boxes of the text drawn for the mark, in the same px: passed through as `labelBounds`. */
188
- readonly labelBounds?: readonly Rect[];
171
+ readonly key: string;
172
+ readonly series?: string;
173
+ /** At least one point, in chart px. */
174
+ readonly points: readonly Point[];
175
+ /**
176
+ * The indices of the points that start a new run, so there's a gap from `points[i - 1]` to
177
+ * `points[i]`: each a whole number from 1 to the last index, in order, with no repeats. A line
178
+ * drawn with d3's `.defined()` is described by its defined points and where they break. Default none.
179
+ */
180
+ readonly breaks?: readonly number[];
181
+ /** Stroke width in px. Default 1, SVG's default. */
182
+ readonly width?: number;
183
+ /** The boxes of the text drawn for the mark, in the same px: passed through as `labelBounds`. */
184
+ readonly labelBounds?: readonly Rect[];
185
+ /** The boxes of other marks' text near it, in the same px: passed through as `nearbyLabels`. */
186
+ readonly nearbyLabels?: readonly Rect[];
189
187
  }
190
188
  /**
191
189
  * The walk is the line itself, first point to last, running straight across each break. Its outline
@@ -193,30 +191,62 @@ interface LineSpec {
193
191
  * no gap, since there's nothing between them to leave out.
194
192
  */
195
193
  declare function describeLine(spec: LineSpec): MarkGeometry;
196
-
197
194
  interface PointSpec {
198
- readonly key: string;
199
- readonly series?: string;
200
- readonly x: number;
201
- readonly y: number;
202
- /** Radius in px. */
203
- readonly r: number;
204
- /** The boxes of the text drawn for the mark, in the same px: passed through as `labelBounds`. */
205
- readonly labelBounds?: readonly Rect[];
195
+ readonly key: string;
196
+ readonly series?: string;
197
+ readonly x: number;
198
+ readonly y: number;
199
+ /** Radius in px. */
200
+ readonly r: number;
201
+ /** The boxes of the text drawn for the mark, in the same px: passed through as `labelBounds`. */
202
+ readonly labelBounds?: readonly Rect[];
203
+ /** The boxes of other marks' text near it, in the same px: passed through as `nearbyLabels`. */
204
+ readonly nearbyLabels?: readonly Rect[];
206
205
  }
207
206
  /**
208
207
  * Length 0, with start = end = centre, so travel does nothing while wiggle, pulse and flash still
209
208
  * work. Faces +x: the outline's sides are the quarter circles top, right, bottom and left.
210
209
  */
211
210
  declare function describePoint(spec: PointSpec): MarkGeometry;
212
-
213
- declare const describe: {
214
- bar: typeof describeBar;
215
- arc: typeof describeArc;
216
- line: typeof describeLine;
217
- point: typeof describePoint;
211
+ interface ShapeSpec {
212
+ readonly key: string;
213
+ readonly series?: string;
214
+ /**
215
+ * SVG path data in the shape's own px, read as SVG reads it, up to its first error. A shape is
216
+ * closed when every subpath ends with Z, or where it started, and otherwise open, a line.
217
+ */
218
+ readonly d: string;
219
+ /** Moves the shape into the marks' px, as an element's transform does, arcs too. Default none. */
220
+ readonly matrix?: Matrix;
221
+ /** An open shape's stroke width in px, more than 0. Default 1, SVG's default. */
222
+ readonly width?: number;
223
+ /** The boxes of the text drawn for the mark, in the marks' px: passed through as `labelBounds`. */
224
+ readonly labelBounds?: readonly Rect[];
225
+ /** The boxes of other marks' text near it, in the marks' px: passed through as `nearbyLabels`. */
226
+ readonly nearbyLabels?: readonly Rect[];
227
+ }
228
+ /**
229
+ * Path data, flattened: straight pieces and circular arcs stay as they are, and Béziers and other
230
+ * arcs become straight pieces within 0.1 px of the curve.
231
+ * - An open shape is a line. Its walk runs along the path from its first point, and each later move
232
+ * starts a new run after a gap. Its outline is the stroke, less the gaps, and its thickness,
233
+ * bounds, centre and pivot are as `describe.line`'s.
234
+ * - A closed shape has no direction: its walk is its bounds' centre, with length 0. Its outline's
235
+ * `d` is the whole path, holes too, and `sample(n)` goes round its longest subpath, clockwise in
236
+ * four quarters of equal length from its upper left. Its thickness is the smaller of its width and
237
+ * height.
238
+ * A subpath that ends where it started is closed too, as d3.arc() draws a full ring's outer edge.
239
+ * A path whose subpaths are all closed but have no length, as d3 draws a value alone, is open: a line
240
+ * with nothing to stroke.
241
+ */
242
+ declare function describeShape(spec: ShapeSpec): MarkGeometry;
243
+ export declare const describe: {
244
+ bar: typeof describeBar;
245
+ arc: typeof describeArc;
246
+ line: typeof describeLine;
247
+ point: typeof describePoint;
248
+ shape: typeof describeShape;
218
249
  };
219
-
220
250
  declare function translate(x: number, y: number): Matrix;
221
251
  /** Positive radians turn clockwise on screen, like SVG's rotate(). */
222
252
  declare function rotate(radians: number, about?: Point): Matrix;
@@ -226,22 +256,21 @@ declare function multiply(...matrices: Matrix[]): Matrix;
226
256
  /** Where the transform takes a point. */
227
257
  declare function apply(m: Matrix, point: Point): Point;
228
258
  /** Builds and applies 2D transforms in SVG order, for `mark.set({ transform })` and `IconHandle.place()`. */
229
- declare const matrix: {
230
- translate: typeof translate;
231
- rotate: typeof rotate;
232
- scale: typeof scale;
233
- multiply: typeof multiply;
234
- apply: typeof apply;
259
+ export declare const matrix: {
260
+ translate: typeof translate;
261
+ rotate: typeof rotate;
262
+ scale: typeof scale;
263
+ multiply: typeof multiply;
264
+ apply: typeof apply;
235
265
  };
236
266
  /** A point `distance` px from `point` in direction `angle` (screen radians). */
237
- declare function offset(point: Point, angle: number, distance: number): Point;
238
-
267
+ export declare function offset(point: Point, angle: number, distance: number): Point;
239
268
  /** A data point in the mark's coordinates, with its value and, optionally, the x value behind it. */
240
269
  interface SamplePoint {
241
- readonly x: number;
242
- readonly y: number;
243
- readonly value: number;
244
- readonly at?: string | number | Date;
270
+ readonly x: number;
271
+ readonly y: number;
272
+ readonly value: number;
273
+ readonly at?: string | number | Date;
245
274
  }
246
275
  /**
247
276
  * Projects each point onto the nearest point of the mark's walk and returns the samples in `t` order
@@ -250,31 +279,27 @@ interface SamplePoint {
250
279
  * has `gapBefore`, so a data effect doesn't join it to the one before. Throws a RangeError on a point
251
280
  * whose x, y or value isn't finite.
252
281
  */
253
- declare function samplesAlong(mark: MarkGeometry, points: readonly SamplePoint[]): Sample[];
254
-
282
+ export declare function samplesAlong(mark: MarkGeometry, points: readonly SamplePoint[]): Sample[];
255
283
  interface ColorAssignment {
256
- /** The palette slot (1–8) for a key: its pinned slot, or the next free one the first time it's seen. Never reassigned. */
257
- slot(key: string): number;
284
+ /** The palette slot (1–8) for a key: its pinned slot, or the next free one the first time it's seen. Never reassigned. */
285
+ slot(key: string): number;
258
286
  }
259
287
  /** `fixed` pins slots, as in the prototype's `{ goals: 1, assists: 4 }`. Other keys take free slots in the order they're first seen. */
260
- declare function colorAssignment(fixed?: Readonly<Record<string, number>>): ColorAssignment;
261
-
288
+ export declare function colorAssignment(fixed?: Readonly<Record<string, number>>): ColorAssignment;
262
289
  /** Field names of D whose values are T. */
263
- type KeyOfType<D, T> = {
264
- [K in keyof D]-?: D[K] extends T ? K : never;
265
- }[keyof D] & string;
290
+ type KeyOfType<D, T> = { [K in keyof D]-?: D[K] extends T ? K : never; }[keyof D] & string;
266
291
  /** A field name whose values are T, or a function returning T. */
267
292
  type Accessor<D, T> = KeyOfType<D, T> | ((d: D, i: number) => T);
268
293
  /** Field names whose values are numbers, so `stack: ["name"]` is a type error. */
269
294
  type NumericKey<D> = KeyOfType<D, number>;
270
295
  interface MarkEvent<D> {
271
- readonly mark: MarkGeometry;
272
- readonly data: MarkData<D>;
273
- /** The mark's position among the marks in this event, for stagger. */
274
- readonly batch: {
275
- readonly index: number;
276
- readonly count: number;
277
- };
296
+ readonly mark: MarkGeometry;
297
+ readonly data: MarkData<D>;
298
+ /** The mark's position among the marks in this event, for stagger. */
299
+ readonly batch: {
300
+ readonly index: number;
301
+ readonly count: number;
302
+ };
278
303
  }
279
304
  /**
280
305
  * Effect slots and `chart.on()` consume the same events. Data events fire when a change starts: enter
@@ -282,330 +307,357 @@ interface MarkEvent<D> {
282
307
  * geometry on screen too, part way to the new one while a change plays.
283
308
  */
284
309
  interface MarkEvents<D> {
285
- enter: MarkEvent<D>;
286
- update: MarkEvent<D> & {
287
- readonly from: MarkGeometry;
288
- };
289
- exit: MarkEvent<D>;
290
- /** `source` "linked": hovered by `link()`, because a mark in another chart with its linking value was. */
291
- hover: MarkEvent<D> & {
292
- readonly source: "pointer" | "keyboard" | "touch" | "linked";
293
- readonly segment?: string;
294
- };
295
- leave: MarkEvent<D>;
310
+ enter: MarkEvent<D>;
311
+ update: MarkEvent<D> & {
312
+ readonly from: MarkGeometry;
313
+ };
314
+ exit: MarkEvent<D>;
315
+ /** `source` "linked": hovered by `link()`, because a mark in another chart with its linking value was. */
316
+ hover: MarkEvent<D> & {
317
+ readonly source: "pointer" | "keyboard" | "touch" | "linked";
318
+ readonly segment?: string;
319
+ };
320
+ leave: MarkEvent<D>;
296
321
  }
297
322
  interface ChartOptions<D> {
298
- readonly data: readonly D[];
299
- /** Accessible name; required. */
300
- readonly label: string;
301
- readonly description?: string;
302
- /** A string or numeric field (numeric IDs are converted with String()), or a function. Default: the category. Duplicate keys throw. */
303
- readonly key?: Accessor<D, string | number>;
304
- /**
305
- * Default: the page-wide `motion`. A mode is this chart's author default: the viewer's choice on the
306
- * page-wide motion and the device's reduced-motion setting still win, as they do over setMode().
307
- */
308
- readonly motion?: Motion | MotionMode;
309
- /** NoInfer: a generic data effect such as threshold() must not widen D to unknown. */
310
- readonly on?: EffectSlots<NoInfer<D>>;
311
- /** Formats values and axis ticks. */
312
- readonly format?: (value: number) => string;
313
- /** Palette slots (1–8) by series, pinned or shared. Colours follow the entity, never its rank. */
314
- readonly colors?: ColorAssignment | Readonly<Record<string, number>>;
315
- /**
316
- * Names for people, by series (its field, or "value" for a value read by a function): { goals:
317
- * "Goals", xg: "Expected goals" }. Used as given wherever the chart names a series: the legend, the
318
- * table's headers, the default tooltip and mark names ("16 Goals"), and announcements. A series
319
- * without one goes by its own name. Labels for series the chart doesn't show are kept for when it does.
320
- */
321
- readonly seriesLabels?: Readonly<Record<string, string>>;
322
- /** Fixed width in px. Default: the container's width, followed with a ResizeObserver. */
323
- readonly width?: number;
324
- readonly height?: number;
325
- /** Dim the other marks while one is hovered (to --ec-dim-opacity). Default true. The hovered mark's emphasis stays either way. */
326
- readonly dim?: boolean;
327
- /**
328
- * A swatch and a name for each series or, on a donut, each category, above the chart. Default true.
329
- * Bars list their series when more than one shows. An object's `entries` come after the chart's
330
- * own, for colours its effects draw, which the chart can't know: { label: "Goals below xG", color:
331
- * "negative" }. With entries, a single series is listed too, so its colour is named beside theirs.
332
- */
333
- readonly legend?: boolean | LegendOptions;
334
- /**
335
- * A box beside the hovered or focused mark. Default true: the category, each series' value in
336
- * `format`, and the total of a stack. A function gives a row's text instead ("\n" breaks a line; an
337
- * empty string shows none); it's set as text, never as HTML. The box itself is aria-hidden, so it
338
- * isn't read twice, but a function's text also becomes the mark's accessible description
339
- * (aria-describedby), so what it adds beyond the values (a player's position) reaches screen readers.
340
- */
341
- readonly tooltip?: boolean | ((d: NoInfer<D>) => string);
342
- /**
343
- * Words each mark's accessible name (its aria-label), which by default is the category and each
344
- * series' value in `format`: "Okafor: 16 goals, 4 assists". Given the row and the mark as it's
345
- * heading, with the series it shows, the chart's `format` and the default `text`, so a page can say
346
- * "1 goal". An empty string, or a throw (reported), keeps the default: a mark is never left unnamed.
347
- */
348
- readonly markLabel?: (d: NoInfer<D>, mark: MarkSummary) => string;
349
- /**
350
- * Each mark's accessible description (aria-describedby): what its name doesn't already say. Default:
351
- * a tooltip function's text, so a custom tooltip's extra facts reach screen readers. When that text
352
- * repeats the values the name already says, give only the extra facts here ("Forward"), so nothing
353
- * is read twice. `false` describes nothing; so do an empty string and a throw (reported).
354
- */
355
- readonly markDescription?: false | ((d: NoInfer<D>) => string);
356
- /**
357
- * The data table: the fallback every screen reader can read. Default true: a closed <details>
358
- * "Data table" after the chart, listing the rows in the chart's order with the category, each series
359
- * and, for a stack, the total, in `format`. "hidden": visually hidden but still read. An object adds
360
- * columns or changes its text.
361
- */
362
- readonly table?: boolean | "hidden" | TableOptions<NoInfer<D>>;
363
- /**
364
- * A polite live region that sums up each update for screen readers ("Sorted A to Z", "Okafor and
365
- * Tanaka changed"). Default false. A function is given the change and returns the text to announce
366
- * instead; "" or undefined announces nothing.
367
- */
368
- readonly announce?: boolean | ((change: ChartChange) => string | undefined);
323
+ readonly data: readonly D[];
324
+ /** Accessible name; required. */
325
+ readonly label: string;
326
+ readonly description?: string;
327
+ /** A string or numeric field (numeric IDs are converted with String()), or a function. Default: the category. Duplicate keys throw. */
328
+ readonly key?: Accessor<D, string | number>;
329
+ /**
330
+ * Default: the page-wide `motion`. A mode is this chart's author default: the viewer's choice on the
331
+ * page-wide motion and the device's reduced-motion setting still win, as they do over setMode().
332
+ */
333
+ readonly motion?: Motion | MotionMode;
334
+ /** NoInfer: a generic data effect such as threshold() must not widen D to unknown. */
335
+ readonly on?: EffectSlots<NoInfer<D>>;
336
+ /** Formats values and axis ticks. */
337
+ readonly format?: (value: number) => string;
338
+ /** Palette slots (1–8) by series, pinned or shared. Colours follow the entity, never its rank. */
339
+ readonly colors?: ColorAssignment | Readonly<Record<string, number>>;
340
+ /**
341
+ * Names for people, by series (its field, or "value" for a value read by a function): { goals:
342
+ * "Goals", xg: "Expected goals" }. Used as given wherever the chart names a series: the legend, the
343
+ * table's headers, the default tooltip and mark names ("16 Goals"), and announcements. A series
344
+ * without one goes by its own name. Labels for series the chart doesn't show are kept for when it does.
345
+ */
346
+ readonly seriesLabels?: Readonly<Record<string, string>>;
347
+ /** Fixed width in px. Default: the container's width, followed with a ResizeObserver. */
348
+ readonly width?: number;
349
+ readonly height?: number;
350
+ /** Dim the other marks while one is hovered (to --ec-dim-opacity). Default true. The hovered mark's emphasis stays either way. */
351
+ readonly dim?: boolean;
352
+ /**
353
+ * A swatch and a name for each series or, on a donut, each category, above the chart. Default true.
354
+ * Bars list their series when more than one shows. An object's `entries` come after the chart's
355
+ * own, for colours its effects draw, which the chart can't know: { label: "Goals below xG", color:
356
+ * "negative" }. With entries, a single series is listed too, so its colour is named beside theirs.
357
+ */
358
+ readonly legend?: boolean | LegendOptions;
359
+ /**
360
+ * A box beside the hovered or focused mark. Default true: the category, each series' value in
361
+ * `format`, and the total of a stack. A function gives a row's text instead ("\n" breaks a line; an
362
+ * empty string shows none); it's set as text, never as HTML. The box itself is aria-hidden, so it
363
+ * isn't read twice, but a function's text also becomes the mark's accessible description
364
+ * (aria-describedby), so what it adds beyond the values (a player's position) reaches screen readers.
365
+ */
366
+ readonly tooltip?: boolean | ((d: NoInfer<D>) => string);
367
+ /**
368
+ * Words each mark's accessible name (its aria-label), which by default is the category and each
369
+ * series' value in `format`: "Okafor: 16 goals, 4 assists". Given the row and the mark as it's
370
+ * heading, with the series it shows, the chart's `format` and the default `text`, so a page can say
371
+ * "1 goal". An empty string, or a throw (reported), keeps the default: a mark is never left unnamed.
372
+ */
373
+ readonly markLabel?: (d: NoInfer<D>, mark: MarkSummary) => string;
374
+ /**
375
+ * Each mark's accessible description (aria-describedby): what its name doesn't already say. Default:
376
+ * a tooltip function's text, so a custom tooltip's extra facts reach screen readers. When that text
377
+ * repeats the values the name already says, give only the extra facts here ("Forward"), so nothing
378
+ * is read twice. `false` describes nothing; so do an empty string and a throw (reported).
379
+ */
380
+ readonly markDescription?: false | ((d: NoInfer<D>) => string);
381
+ /**
382
+ * The data table: the fallback every screen reader can read. Default true: a closed <details>
383
+ * "Data table" after the chart, listing the rows in the chart's order with the category, each series
384
+ * and, for a stack, the total, in `format`. "hidden": visually hidden but still read. An object adds
385
+ * columns or changes its text.
386
+ */
387
+ readonly table?: boolean | "hidden" | TableOptions<NoInfer<D>>;
388
+ /**
389
+ * A polite live region that sums up each update for screen readers ("Sorted A to Z", "Okafor and
390
+ * Tanaka changed"). Default false. A function is given the change and returns the text to announce
391
+ * instead; "" or undefined announces nothing.
392
+ */
393
+ readonly announce?: boolean | ((change: ChartChange) => string | undefined);
369
394
  }
370
395
  interface LegendOptions {
371
- /** Entries after the chart's own, in order. */
372
- readonly entries?: readonly LegendEntry[];
396
+ /** Entries after the chart's own, in order. */
397
+ readonly entries?: readonly LegendEntry[];
373
398
  }
374
399
  /** A legend entry the page adds: a swatch in `color`, named by `label` in the theme's text colour. */
375
400
  interface LegendEntry {
376
- readonly label: string;
377
- /** A theme token ("negative", "series-3") or a CSS colour. Not "mark" or "mark-strong": an entry has no mark. */
378
- readonly color: Color;
401
+ readonly label: string;
402
+ /** A theme token ("negative", "series-3") or a CSS colour. Not "mark" or "mark-strong": an entry has no mark. */
403
+ readonly color: Color;
379
404
  }
380
405
  interface TableOptions<D> {
381
- /** Visually hidden, but still read by screen readers, as with `table: "hidden"`. Default false. */
382
- readonly hidden?: boolean;
383
- /** Extra columns, after the category's (the prototype's player position, say) or, with `after: "values"`, after the chart's values. */
384
- readonly columns?: readonly TableColumn<D>[];
385
- /** The category column's header. Default: the category's field name, or "Category" when a function reads it. */
386
- readonly category?: string;
387
- /** The header of a stack's total column, or of a donut's total row. Default "Total". */
388
- readonly total?: string;
389
- /** A donut's share column's header. Default "Share". */
390
- readonly share?: string;
391
- /**
392
- * Each series' column header, by series (its field, or "value" for a value read by a function):
393
- * { shots: "Shots" }. Default: its `seriesLabels` name, or the series itself. Only the table's
394
- * headers change; the legend, names and tooltip keep `seriesLabels`.
395
- */
396
- readonly series?: Readonly<Record<string, string>>;
397
- /** The text of the <summary> that opens the table. Default "Data table". */
398
- readonly summary?: string;
406
+ /** Visually hidden, but still read by screen readers, as with `table: "hidden"`. Default false. */
407
+ readonly hidden?: boolean;
408
+ /** Extra columns, after the category's (the prototype's player position, say) or, with `after: "values"`, after the chart's values. */
409
+ readonly columns?: readonly TableColumn<D>[];
410
+ /** The category column's header. Default: the category's field name, or "Category" when a function reads it. */
411
+ readonly category?: string;
412
+ /** The header of a stack's total column, or of a donut's total row. Default "Total". */
413
+ readonly total?: string;
414
+ /** A donut's share column's header. Default "Share". */
415
+ readonly share?: string;
416
+ /**
417
+ * Each series' column header, by series (its field, or "value" for a value read by a function):
418
+ * { shots: "Shots" }. Default: its `seriesLabels` name, or the series itself. Only the table's
419
+ * headers change; the legend, names and tooltip keep `seriesLabels`.
420
+ */
421
+ readonly series?: Readonly<Record<string, string>>;
422
+ /** The text of the <summary> that opens the table. Default "Data table". */
423
+ readonly summary?: string;
399
424
  }
400
425
  interface TableColumn<D> {
401
- /** Its header. */
402
- readonly label: string;
403
- /** A field of the row, or a function of the row and its index in `data`. */
404
- readonly field: Accessor<D, unknown>;
405
- /** Default: numbers in the chart's `format`, anything else as text, and nothing for null or undefined. */
406
- readonly format?: (value: unknown) => string;
407
- /**
408
- * Where it goes. Default "category": just after the category, before the values. "values": last,
409
- * after every column of the chart's own (the series, a total, a share), as a Difference column is.
410
- */
411
- readonly after?: "category" | "values";
426
+ /** Its header. */
427
+ readonly label: string;
428
+ /** A field of the row, or a function of the row and its index in `data`. */
429
+ readonly field: Accessor<D, unknown>;
430
+ /** Default: numbers in the chart's `format`, anything else as text, and nothing for null or undefined. */
431
+ readonly format?: (value: unknown) => string;
432
+ /**
433
+ * Where it goes. Default "category": just after the category, before the values. "values": last,
434
+ * after every column of the chart's own (the series, a total, a share), as a Difference column is.
435
+ */
436
+ readonly after?: "category" | "values";
412
437
  }
413
438
  /** What `markLabel` is given beside the row: the mark as it's heading, in the chart's terms. */
414
439
  interface MarkSummary {
415
- readonly key: string;
416
- /** The category, as the axis shows it. */
417
- readonly category: string;
418
- /**
419
- * Each series the mark shows, from the baseline, with its name for people (from `seriesLabels`, or
420
- * the series itself) and its signed value. A lone value read by a function is the series "value".
421
- */
422
- readonly values: readonly {
423
- readonly series: string;
424
- readonly label: string;
425
- readonly value: number;
426
- }[];
427
- /** The values added up. */
428
- readonly total: number;
429
- /** The chart's `format`, or its default. */
430
- readonly format: (value: number) => string;
431
- /** The name the chart gives by default: "Okafor: 16 goals, 4 assists". */
432
- readonly text: string;
440
+ readonly key: string;
441
+ /** The category, as the axis shows it. */
442
+ readonly category: string;
443
+ /**
444
+ * Each series the mark shows, from the baseline, with its name for people (from `seriesLabels`, or
445
+ * the series itself) and its signed value. A lone value read by a function is the series "value".
446
+ */
447
+ readonly values: readonly {
448
+ readonly series: string;
449
+ readonly label: string;
450
+ readonly value: number;
451
+ }[];
452
+ /** The values added up. */
453
+ readonly total: number;
454
+ /** The chart's `format`, or its default. */
455
+ readonly format: (value: number) => string;
456
+ /** The name the chart gives by default: "Okafor: 16 goals, 4 assists". */
457
+ readonly text: string;
433
458
  }
434
459
  /** What `announce` is given: the chart's own summary of an update, and the marks it changed. */
435
460
  interface ChartChange {
436
- /** What the chart announces by default: "Sorted A to Z. Okafor and Tanaka changed". "" when it would say nothing. */
437
- readonly text: string;
438
- /** Keys of the marks whose values changed, in visual order. */
439
- readonly changed: readonly string[];
440
- /** Keys of the marks that appeared, in visual order. */
441
- readonly added: readonly string[];
442
- /** Keys of the marks that left. */
443
- readonly removed: readonly string[];
461
+ /** What the chart announces by default: "Sorted A to Z. Okafor and Tanaka changed". "" when it would say nothing. */
462
+ readonly text: string;
463
+ /** Keys of the marks whose values changed, in visual order. */
464
+ readonly changed: readonly string[];
465
+ /** Keys of the marks that appeared, in visual order. */
466
+ readonly added: readonly string[];
467
+ /** Keys of the marks that left. */
468
+ readonly removed: readonly string[];
444
469
  }
445
470
  interface BarChartOptions<D> extends ChartOptions<D> {
446
- /** The axis whose values aren't numbers is the category; `orientation` can force it. */
447
- readonly x?: Accessor<D, number | string>;
448
- readonly y?: Accessor<D, number | string>;
449
- /** Numeric fields stacked from the baseline, in order. Used instead of the value axis; each is a segment named after its field. */
450
- readonly stack?: readonly NumericKey<D>[];
451
- /** Default "none": data order. "value": the largest total first. "key": keys A–Z, with numbers in numeric order. */
452
- readonly sort?: "value" | "key" | "none" | ((a: D, b: D) => number);
453
- /** "horizontal": bars, categories along y. "vertical": columns, categories along x. */
454
- readonly orientation?: "horizontal" | "vertical";
455
- /**
456
- * Default "series": each segment takes its series' slot through `colors`, and the legend lists the
457
- * series. "category": each bar takes its own slot, by its key (its category unless `key` is given),
458
- * as a donut's slice does, so one `colors` assignment shared with a donut keeps each category's
459
- * colour in both; the legend lists the categories. It needs one series: on a stack it throws.
460
- */
461
- readonly colorBy?: "series" | "category";
462
- /**
463
- * Px the layout keeps clear past the labels at each end of the value axis that bars reach, for text
464
- * an effect draws there: a `delta` past a bar's value label, or past a negative bar's name. Default
465
- * 0. At 320 px, 28 keeps a `delta` inside the chart.
466
- */
467
- readonly room?: number;
471
+ /** The axis whose values aren't numbers is the category; `orientation` can force it. */
472
+ readonly x?: Accessor<D, number | string>;
473
+ readonly y?: Accessor<D, number | string>;
474
+ /** Numeric fields stacked from the baseline, in order. Used instead of the value axis; each is a segment named after its field. */
475
+ readonly stack?: readonly NumericKey<D>[];
476
+ /** Default "none": data order. "value": the largest total first. "key": keys A–Z, with numbers in numeric order. */
477
+ readonly sort?: "value" | "key" | "none" | ((a: D, b: D) => number);
478
+ /** "horizontal": bars, categories along y. "vertical": columns, categories along x. */
479
+ readonly orientation?: "horizontal" | "vertical";
480
+ /**
481
+ * Default "series": each segment takes its series' slot through `colors`, and the legend lists the
482
+ * series. "category": each bar takes its own slot, by its key (its category unless `key` is given),
483
+ * as a donut's slice does, so one `colors` assignment shared with a donut keeps each category's
484
+ * colour in both; the legend lists the categories. It needs one series: on a stack it throws.
485
+ */
486
+ readonly colorBy?: "series" | "category";
487
+ /**
488
+ * Px the layout keeps clear past the labels at each end of the value axis that bars reach, for text
489
+ * an effect draws there: a `delta` past a bar's value label, or past a negative bar's name. Default
490
+ * 0. At 320 px, 28 keeps a `delta` inside the chart.
491
+ */
492
+ readonly room?: number;
468
493
  }
469
494
  /** What a donut's `markLabel` is given beside the row: the slice as it's heading, as a bar's `MarkSummary` says it, and its share. */
470
495
  interface SliceSummary extends MarkSummary {
471
- /** The slice's share of the total, from 0 to 1. */
472
- readonly share: number;
496
+ /** The slice's share of the total, from 0 to 1. */
497
+ readonly share: number;
473
498
  }
474
499
  interface DonutChartOptions<D> extends Omit<ChartOptions<D>, "colors" | "markLabel"> {
475
- /** Names each slice: a field or a function. It's the slice's key too, unless `key` is given. */
476
- readonly category: Accessor<D, string | number>;
477
- /**
478
- * Sizes each slice: a numeric field or a function. A missing value counts as 0, and a negative or
479
- * non-finite one throws. The slices' series is the field's name ("shots"), or "value" for a function.
480
- */
481
- readonly value: Accessor<D, number | null | undefined>;
482
- /** Default "none": data order. "value": the largest first. Either way from 12 o'clock, clockwise. */
483
- readonly sort?: "none" | "value";
484
- /**
485
- * The text in the hole, for the total: "\n" breaks a line, and the first line is drawn large. Default
486
- * the total in `format` over the value's series label: "406" over "shots". `false` shows none. It's
487
- * aria-hidden, and its text is added to the chart's description.
488
- */
489
- readonly center?: false | ((total: number, format: (value: number) => string) => string);
490
- /** Palette slots (1–8) by slice: its key, which is its category unless `key` is given. Pinned or shared. */
491
- readonly colors?: ColorAssignment | Readonly<Record<string, number>>;
492
- /**
493
- * Words each slice's accessible name, which by default is its category, its value in `format` with
494
- * its series' label, and its share as a whole percent: "Saved: 112 shots, 28%". Given the row and the
495
- * slice as it's heading, with its share. An empty string, or a throw (reported), keeps the default.
496
- */
497
- readonly markLabel?: (d: NoInfer<D>, mark: SliceSummary) => string;
500
+ /** Names each slice: a field or a function. It's the slice's key too, unless `key` is given. */
501
+ readonly category: Accessor<D, string | number>;
502
+ /**
503
+ * Sizes each slice: a numeric field or a function. A missing value counts as 0, and a negative or
504
+ * non-finite one throws. The slices' series is the field's name ("shots"), or "value" for a function.
505
+ */
506
+ readonly value: Accessor<D, number | null | undefined>;
507
+ /** Default "none": data order. "value": the largest first. Either way from 12 o'clock, clockwise. */
508
+ readonly sort?: "none" | "value";
509
+ /**
510
+ * The text in the hole, for the total: "\n" breaks a line, and the first line is drawn large. Default
511
+ * the total in `format` over the value's series label: "406" over "shots". `false` shows none. It's
512
+ * aria-hidden, and its text is added to the chart's description.
513
+ */
514
+ readonly center?: false | ((total: number, format: (value: number) => string) => string);
515
+ /** Palette slots (1–8) by slice: its key, which is its category unless `key` is given. Pinned or shared. */
516
+ readonly colors?: ColorAssignment | Readonly<Record<string, number>>;
517
+ /**
518
+ * Words each slice's accessible name, which by default is its category, its value in `format` with
519
+ * its series' label, and its share as a whole percent: "Saved: 112 shots, 28%". Given the row and the
520
+ * slice as it's heading, with its share. An empty string, or a throw (reported), keeps the default.
521
+ */
522
+ readonly markLabel?: (d: NoInfer<D>, mark: SliceSummary) => string;
498
523
  }
499
524
  interface LineChartOptions<D> extends ChartOptions<D> {
500
- /**
501
- * Each row's x: a field or a function giving a number or a Date. Dates make a time axis, in
502
- * `timeZone`. Every row's x must be the same kind: numbers and Dates together throw a TypeError,
503
- * and so does an invalid Date. There's one row per x, drawn in ascending x, and x values must be
504
- * unique (Dates by their time) whatever the keys, since each x is one focus stop, one hit column
505
- * and one place to reveal to. `key` defaults to x: a number with String(), a Date's toISOString().
506
- */
507
- readonly x: Accessor<D, number | Date>;
508
- /**
509
- * A time axis's zone: "UTC" (the default) or "local", the viewer's clock. Ticks fall on day, month
510
- * and year boundaries in it, and the names, the tooltip and the table say times in it. A date-only
511
- * value such as new Date("2026-01-05") is UTC midnight, so in UTC it's 5 January on every machine.
512
- */
513
- readonly timeZone?: "UTC" | "local";
514
- /**
515
- * Words an x for people instead of the default: in each x's name, the tooltip's title, the table's
516
- * row headers and the announcements, and as `markLabel`'s `category`. Given the x as the data has it,
517
- * a Date on a time axis or a number. Default: a time axis's medium date in the page's locale ("Jan 5,
518
- * 2026"), with the time when any x has one; a number as given. The ticks keep their own wording. A
519
- * throw makes the chart throw and update() reject, as `format`'s does.
520
- */
521
- readonly xFormat?: (x: Date | number) => string;
522
- /**
523
- * The numeric fields drawn as lines, in order. Each is a line mark keyed by its field, plus a point
524
- * mark per row keyed "<series>@<row key>" ("goals@12"). A missing value, null or undefined, is a gap
525
- * in its line, with no point; the x is still a stop, whose name, tooltip and table row say the
526
- * series is missing there. NaN and the infinities throw.
527
- */
528
- readonly series: readonly KeyOfType<D, number | null | undefined>[];
529
- /**
530
- * The label at each line's end, in the right margin: by default its value in `format` with its
531
- * series' label ("52 goals"), counting between values while a change or a reveal plays. `false`
532
- * turns them off. A function words them, given the value (rounded as it counts), the series and
533
- * the chart's `format`; an empty string shows none, and a throw (reported) keeps the default.
534
- */
535
- readonly labels?: false | ((value: number, series: string, format: (value: number) => string) => string);
525
+ /**
526
+ * Each row's x: a field or a function giving a number or a Date. Dates make a time axis, in
527
+ * `timeZone`. Every row's x must be the same kind: numbers and Dates together throw a TypeError,
528
+ * and so does an invalid Date. There's one row per x, drawn in ascending x, and x values must be
529
+ * unique (Dates by their time) whatever the keys, since each x is one focus stop, one hit column
530
+ * and one place to reveal to. `key` defaults to x: a number with String(), a Date's toISOString().
531
+ */
532
+ readonly x: Accessor<D, number | Date>;
533
+ /**
534
+ * A time axis's zone: "UTC" (the default) or "local", the viewer's clock. Ticks fall on day, month
535
+ * and year boundaries in it, and the names, the tooltip and the table say times in it. A date-only
536
+ * value such as new Date("2026-01-05") is UTC midnight, so in UTC it's 5 January on every machine.
537
+ */
538
+ readonly timeZone?: "UTC" | "local";
539
+ /**
540
+ * Words an x for people instead of the default: in each x's name, the tooltip's title, the table's
541
+ * row headers and the announcements, and as `markLabel`'s `category`. Given the x as the data has it,
542
+ * a Date on a time axis or a number. Default: a time axis's medium date in the page's locale ("Jan 5,
543
+ * 2026"), with the time when any x has one; a number as given. The ticks keep their own wording. A
544
+ * throw makes the chart throw and update() reject, as `format`'s does.
545
+ */
546
+ readonly xFormat?: (x: Date | number) => string;
547
+ /**
548
+ * The numeric fields drawn as lines, in order. Each is a line mark keyed by its field, plus a point
549
+ * mark per row keyed "<series>@<row key>" ("goals@12"). A missing value, null or undefined, is a gap
550
+ * in its line, with no point; the x is still a stop, whose name, tooltip and table row say the
551
+ * series is missing there. NaN and the infinities throw.
552
+ */
553
+ readonly series: readonly KeyOfType<D, number | null | undefined>[];
554
+ /**
555
+ * The label at each line's end, in the right margin: by default its value in `format` with its
556
+ * series' label ("52 goals"), counting between values while a change or a reveal plays. `false`
557
+ * turns them off. A function words them, given the value (rounded as it counts), the series and
558
+ * the chart's `format`; an empty string shows none, and a throw (reported) keeps the default.
559
+ */
560
+ readonly labels?: false | ((value: number, series: string, format: (value: number) => string) => string);
561
+ /**
562
+ * How each line runs between its values. "linear", the default, is straight from value to value.
563
+ * "monotone" is d3's curveMonotoneX: a smooth curve through every value that's flat between two
564
+ * equal ones and never goes above or below the values either side, so it shows no value the data
565
+ * doesn't have. Each run between gaps is curved on its own, and a run of two values is straight. A
566
+ * curved line's samples are its rows' and one at each bend between them, so `threshold` changes
567
+ * colour where the drawn lines cross. A change of curve plays as a change; anything else throws a
568
+ * TypeError, and update() rejects it.
569
+ */
570
+ readonly curve?: "linear" | "monotone";
571
+ /**
572
+ * What the pointer, touch and the keys hover. "x", the default: every series' point at the nearest
573
+ * x, with a crosshair, nothing dimmed, and the x's as focus stops. "point": the revealed point nearest
574
+ * the pointer, by distance, anywhere over the plot (of two as near, the series first in `series`),
575
+ * alone. Its line stays at full strength and every other line and point dims, unless `dim` is false;
576
+ * there's no crosshair, and the tooltip sits above the point. The points are the focus stops: Left
577
+ * and Right go along the line, Up and Down to the point above or below. Links still go by x. Anything
578
+ * else throws a TypeError. update({ hover }) changes it at once: a held hover ends, and focus moves
579
+ * to the nearest stop of the new kind.
580
+ */
581
+ readonly hover?: "x" | "point";
582
+ /**
583
+ * A box beside the hovered or focused x or point, as on every chart. A function is given the row
584
+ * and, with `hover: "point"`, the point's series as a second argument: (d, { series }) => text. With
585
+ * "x" it's given the row alone.
586
+ */
587
+ readonly tooltip?: boolean | ((d: NoInfer<D>, point?: {
588
+ readonly series: string;
589
+ }) => string);
536
590
  }
537
591
  interface LineChart<D> extends Chart<D, LineChartOptions<D>> {
538
- /**
539
- * Shows the data up to `x`, at once: a view, not a data change, so it fires no events. Each line
540
- * ends at x (part way between two rows when x falls between them) and its decorations follow it, as
541
- * playback drives it frame by frame. Points past x are hidden, can't be hovered or focused, and
542
- * aren't in `marks()`; focus on one moves to the nearest revealed x. The scales, the table, the
543
- * names and the announcements cover all the data. Clamped to the rows' range, and kept across
544
- * `update()`: the default, `reveal(Infinity)`, shows everything, rows added later included. On a
545
- * time axis, x is a Date or its time in ms, which is what playback() plays.
546
- */
547
- reveal(x: number | Date): void;
592
+ /**
593
+ * Shows the data up to `x`, at once: a view, not a data change, so it fires no events. Each line
594
+ * ends at x (part way between two rows when x falls between them) and its decorations follow it, as
595
+ * playback drives it frame by frame. Points past x are hidden, can't be hovered or focused, and
596
+ * aren't in `marks()`; focus on one moves to the nearest revealed x. The scales, the table, the
597
+ * names and the announcements cover all the data. Clamped to the rows' range, and kept across
598
+ * `update()`: the default, `reveal(Infinity)`, shows everything, rows added later included. On a
599
+ * time axis, x is a Date or its time in ms, which is what playback() plays.
600
+ */
601
+ reveal(x: number | Date): void;
548
602
  }
549
603
  /** A mark's label as the chart draws it now: what a chart's `labels()` gives. */
550
604
  interface ChartLabel {
551
- /** The mark's key. */
552
- readonly key: string;
553
- /** "category": the mark's name (a bar's category, a slice's outside label). "value": its value (a bar's total, a slice's share, a line's end label). */
554
- readonly role: "category" | "value";
555
- readonly text: string;
556
- /** Where its baseline's anchor point sits, in the chart's <svg> units (its viewBox), and how it's anchored there. */
557
- readonly x: number;
558
- readonly y: number;
559
- readonly anchor: "start" | "middle" | "end";
560
- /** The <text> as drawn, with the chart's classes, so a copy keeps the stylesheet's styling. */
561
- readonly element: SVGTextElement;
605
+ /** The mark's key. */
606
+ readonly key: string;
607
+ /** "category": the mark's name (a bar's category, a slice's outside label). "value": its value (a bar's total, a slice's share, a line's end label). */
608
+ readonly role: "category" | "value";
609
+ readonly text: string;
610
+ /** Where its baseline's anchor point sits, in the chart's <svg> units (its viewBox), and how it's anchored there. */
611
+ readonly x: number;
612
+ readonly y: number;
613
+ readonly anchor: "start" | "middle" | "end";
614
+ /** The <text> as drawn, with the chart's classes, so a copy keeps the stylesheet's styling. */
615
+ readonly element: SVGTextElement;
562
616
  }
563
617
  interface Chart<D, O> {
564
- /**
565
- * Changes options and animates to the new state, by the motion mode. Resolves when the change has
566
- * settled and the marks it removed are gone (their exit effects done), or as soon as another
567
- * update() supersedes it. Rejects, changing nothing, on options it can't draw, or an `on` it can't
568
- * resolve (an unknown preset name). `motion` can't change yet.
569
- *
570
- * A new `on` swaps the effects of the slots it changes; a slot given the same effect or preset name
571
- * keeps its runs. A changed slot's runs are cleared and the new effect starts where they were:
572
- * `decorate` again on every mark, and a held hover replays with the new hover effect once the
573
- * change settles. `enter`, `update` and `exit` draw the new effect's end state where theirs were,
574
- * so nothing enters again. Focus stays on its mark.
575
- */
576
- update(next: Partial<O>): Promise<void>;
577
- /** Listens for mark events; returns the unsubscribe. */
578
- on<K extends keyof MarkEvents<D>>(type: K, listener: (event: MarkEvents<D>[K]) => void): () => void;
579
- /** The marks now on screen, in visual order (leaving marks excluded): part way there while a change plays. */
580
- marks(): readonly MarkGeometry[];
581
- /**
582
- * Moves focus to the mark `key` as a key press would, whatever the last input was: the focus ring
583
- * shows and its hover plays. On a line chart it's the x's focus stop: `key` is the x's key, or one
584
- * of its points'. A key that isn't on screen (unknown, leaving, or past a line's reveal) does nothing.
585
- */
586
- focus(key: string): void;
587
- /**
588
- * Ends the hover, pointer or keyboard, as the viewer moving away would: the emphasis, the dimming,
589
- * the tooltip and the hover effects end, and `leave` fires for each mark that was hovered. Focus
590
- * stays where it is, with its ring, as after Escape. Does nothing when nothing is hovered.
591
- */
592
- leave(): void;
593
- /**
594
- * Each mark's labels as drawn now, in the marks' visual order (leaving marks excluded): a bar's
595
- * category and value, a slice's category and share outside the ring, a line's end label as its value.
596
- * Labels that aren't shown (a slice's label dropped for room, a line's with `labels: false`) and empty
597
- * ones are left out.
598
- */
599
- labels(): readonly ChartLabel[];
600
- readonly element: SVGSVGElement;
601
- /** Clears every effect and removes the chart. */
602
- destroy(): void;
603
- }
604
-
618
+ /**
619
+ * Changes options and animates to the new state, by the motion mode. Resolves when the change has
620
+ * settled and the marks it removed are gone (their exit effects done), or as soon as another
621
+ * update() supersedes it. Rejects, changing nothing, on options it can't draw, or an `on` it can't
622
+ * resolve (an unknown preset name). `motion` can't change yet.
623
+ *
624
+ * A new `on` swaps the effects of the slots it changes; a slot given the same effect or preset name
625
+ * keeps its runs. A changed slot's runs are cleared and the new effect starts where they were:
626
+ * `decorate` again on every mark, and a held hover replays with the new hover effect once the
627
+ * change settles. `enter`, `update` and `exit` draw the new effect's end state where theirs were,
628
+ * so nothing enters again. Focus stays on its mark.
629
+ */
630
+ update(next: Partial<O>): Promise<void>;
631
+ /** Listens for mark events; returns the unsubscribe. */
632
+ on<K extends keyof MarkEvents<D>>(type: K, listener: (event: MarkEvents<D>[K]) => void): () => void;
633
+ /** The marks now on screen, in visual order (leaving marks excluded): part way there while a change plays. */
634
+ marks(): readonly MarkGeometry[];
635
+ /**
636
+ * Moves focus to the mark `key` as a key press would, whatever the last input was: the focus ring
637
+ * shows and its hover plays. On a line chart it's the x's focus stop: `key` is the x's key, or one
638
+ * of its points'. With `hover: "point"` it's the point's: its own key, or an x's, for its first
639
+ * series' point there. A key that isn't on screen (unknown, leaving, or past a line's reveal) does nothing.
640
+ */
641
+ focus(key: string): void;
642
+ /**
643
+ * Ends the hover, pointer or keyboard, as the viewer moving away would: the emphasis, the dimming,
644
+ * the tooltip and the hover effects end, and `leave` fires for each mark that was hovered. Focus
645
+ * stays where it is, with its ring, as after Escape. Does nothing when nothing is hovered.
646
+ */
647
+ leave(): void;
648
+ /**
649
+ * Each mark's labels as drawn now, in the marks' visual order (leaving marks excluded): a bar's
650
+ * category and value, a slice's category and share outside the ring, a line's end label as its value.
651
+ * Labels that aren't shown (a slice's label dropped for room, a line's with `labels: false`) and empty
652
+ * ones are left out.
653
+ */
654
+ labels(): readonly ChartLabel[];
655
+ readonly element: SVGSVGElement;
656
+ /** Clears every effect and removes the chart. */
657
+ destroy(): void;
658
+ }
605
659
  type BarChart<D> = Chart<D, BarChartOptions<D>>;
606
-
607
660
  type DonutChart<D> = Chart<D, DonutChartOptions<D>>;
608
-
609
661
  /**
610
662
  * A CSS selector, an element, a list of elements (a NodeList, an array), or anything shaped like a D3
611
663
  * selection, whose `data()` types the callbacks. `each` is only there for the types: a D3
@@ -613,228 +665,264 @@ type DonutChart<D> = Chart<D, DonutChartOptions<D>>;
613
665
  * data, so the row type is found through `each` instead. The adapter never calls it.
614
666
  */
615
667
  type MarkSource<D> = string | Element | ArrayLike<Element> | {
616
- nodes(): Element[];
617
- data(): D[];
618
- each?(callback: (datum: D) => void): unknown;
668
+ nodes(): Element[];
669
+ data(): D[];
670
+ each?(callback: (datum: D) => void): unknown;
619
671
  };
620
672
  interface ExpressiveOptions<D> {
621
- /**
622
- * The mark's identity, which effects and refresh() follow. Numbers are converted with String().
623
- * Elements that share a key are one mark; name each part with `segment`.
624
- */
625
- readonly key: (datum: D, element: Element) => string | number;
626
- /**
627
- * The element's row. Default: the source's `data()` for a selection, otherwise `element.__data__`
628
- * (the D3 convention). Observable Plot binds the row's index instead: `(el) => rows[el.__data__]`.
629
- */
630
- readonly datum?: (element: Element) => D;
631
- /** Names the parts of a mark that share a key: a stack's series. Segments are ordered from the baseline. */
632
- readonly segment?: (datum: D, element: Element) => string;
633
- /**
634
- * The value an element shows, so refresh() can tell a change in values from a re-layout. Given, an
635
- * update means a part's value changed or the mark gained or lost a segment, as on our charts: a resize
636
- * or a new axis maximum only moves marks. Without it, an update means a length changed. Called for
637
- * every element, like `key`. Return a number or a string (a date's getTime(), or several values
638
- * joined), since objects would compare by identity.
639
- */
640
- readonly value?: (datum: D, element: Element) => number | string | boolean | null | undefined;
641
- /**
642
- * Describes a mark yourself, for shapes the adapter can't read (anything but a `<rect>`). Called once
643
- * per mark, with its first element in document order, in the coordinates of the marks' nearest
644
- * common ancestor. Build it with `describe` and give it the key passed in.
645
- */
646
- readonly geometry?: (element: Element, datum: D, key: string) => MarkGeometry;
647
- /**
648
- * Data effects' samples: values along the mark's walk, `{ t, value, at? }`, with `t` in [0, 1] and
649
- * never decreasing, and finite values. Called on every read for each mark, with its row (its first
650
- * part's) and its geometry, and for each of its named segments, with that part's row and the
651
- * segment's geometry. They're checked when read: bad samples throw, changing nothing.
652
- * `samplesAlong(mark, points)` gives a line its samples from the points that drew it. Default: rects
653
- * with a numeric `value` get the bar chart's samples (from 0 at the baseline to their total, each
654
- * segment over its own range); other marks get none.
655
- */
656
- readonly samples?: (datum: D, mark: MarkGeometry) => readonly Sample[];
657
- /**
658
- * The edge rects grow from. Default "auto": the line every mark has an edge on, so bars sharing
659
- * their left edge grow right; a bar whose other edge is on the line grows the other way, like a
660
- * negative bar.
661
- */
662
- readonly baseline?: Baseline | "auto";
663
- /**
664
- * Default: the page-wide `motion`. A mode is this attachment's author default: the viewer's choice
665
- * on the page-wide motion and the device's reduced-motion setting still win.
666
- */
667
- readonly motion?: Motion | MotionMode;
668
- /** NoInfer: a generic data effect such as threshold() must not widen D to unknown. */
669
- readonly on?: EffectSlots<NoInfer<D>>;
670
- /**
671
- * Makes marks focusable with a roving tabindex: Tab reaches one mark, the arrow keys, Home and End
672
- * move between them in the order `marks()` gives (around a pie, clockwise from 12 o'clock), and
673
- * focus plays the hover effects. Escape or leaving the chart stops them.
674
- */
675
- readonly keyboard?: boolean;
676
- /**
677
- * Dim the other marks while one is hovered (to --ec-dim-opacity), and give the hovered one its strong
678
- * colour, as our charts do: its fill, or its stroke when the fill is none (a line), stepped toward the
679
- * text colour, so darker in the light theme and lighter in the dark. Default false: the host owns its styling.
680
- */
681
- readonly dim?: boolean;
682
- /**
683
- * Names each mark for screen readers, as one item: "Okafor: 16 goals, 4 assists". The element that
684
- * takes the mark's focus (its first part) becomes `role="img"` with this as its aria-label, and the
685
- * mark's other parts are hidden (`aria-hidden`), so a stack isn't read in pieces. Unnamed host groups
686
- * around them lose a role that would be read in their place (`img`, `graphics-symbol` or
687
- * `graphics-object`, as Vega gives them). Given the mark's row (its first part's) and the mark.
688
- * Called for every mark on each read, never per frame. An empty result, or a throw (reported), leaves
689
- * that mark's ARIA as the host drew it. Default: the adapter writes no ARIA, and the host names its
690
- * own marks.
691
- */
692
- readonly markLabel?: (datum: D, mark: HostMark<D>) => string;
693
- /**
694
- * Follows the host's own transitions, frame by frame, without refresh(): a MutationObserver notes
695
- * changes to the marks' geometry attributes (d, x, y, width, height, cx, cy, r, points, transform),
696
- * and to transform and style on their ancestors up to the root <svg>. Once a frame, on the clock,
697
- * the marks that changed are read again (their rows, geometry and samples) and their effects follow,
698
- * with no events. Values, colours, names and the elements themselves stay as the last refresh() read
699
- * them: call refresh() when the host joins new data. `geometry` should read the element, or a row the
700
- * host updates each frame; one that reads a transition's target row sees only the end. Default false.
701
- */
702
- readonly watch?: boolean;
673
+ /**
674
+ * The mark's identity, which effects and refresh() follow. Numbers are converted with String().
675
+ * Rects that share a key are one mark; name each part with `segment`. A circle or another shape is
676
+ * a mark of its own, so its key is its alone: one it shares with another element throws.
677
+ */
678
+ readonly key: (datum: D, element: Element) => string | number;
679
+ /**
680
+ * The element's row. Default: the source's `data()` for a selection, otherwise `element.__data__`
681
+ * (the D3 convention). Observable Plot binds the row's index instead: `(el) => rows[el.__data__]`.
682
+ */
683
+ readonly datum?: (element: Element) => D;
684
+ /**
685
+ * Names the parts of a mark that share a key: a stack's series. Segments are ordered from the
686
+ * baseline. On a circle or another shape, a mark of its own, it names the mark's series, as
687
+ * `describe`'s `series` does, so a data effect can read that mark through `related`.
688
+ */
689
+ readonly segment?: (datum: D, element: Element) => string;
690
+ /**
691
+ * The value an element shows, so refresh() can tell a change in values from a re-layout. Given, an
692
+ * update means a part's value changed or the mark gained or lost a segment, as on our charts: a resize
693
+ * or a new axis maximum only moves marks. Without it, an update means a length changed. Called for
694
+ * every element, like `key`. Return a number or a string (a date's getTime(), or several values
695
+ * joined), since objects would compare by identity.
696
+ */
697
+ readonly value?: (datum: D, element: Element) => number | string | boolean | null | undefined;
698
+ /**
699
+ * Describes every mark yourself, instead of the adapter reading them. Without it, a `<rect>` is a
700
+ * bar (rects that share a key are its segments), a `<circle>` a point (an ellipse under a transform
701
+ * that stretches it unevenly or skews it), and a `<path>`, `<line>`, `<polyline>`, `<polygon>` or
702
+ * `<ellipse>` a shape, read with `describe.shape` from its outline, an open one with its stroke
703
+ * width as drawn. Each is read through its transforms, and a shape SVG wouldn't draw (a path with no
704
+ * path data) isn't a mark until it draws something. Any other element (`<text>`, `<g>`, `<use>`,
705
+ * `<image>`) throws, naming its tag. Use this for those, or to say more than an element
706
+ * shows: a pie's slice as `describe.arc`, which goes round the pie's centre, or a line by its points.
707
+ * Called once per mark, with its first element in document order, in the coordinates of the marks'
708
+ * nearest common ancestor. Build it with `describe` and give it the key passed in.
709
+ */
710
+ readonly geometry?: (element: Element, datum: D, key: string) => MarkGeometry;
711
+ /**
712
+ * Data effects' samples: values along the mark's walk, `{ t, value, at? }`, with `t` in [0, 1] and
713
+ * never decreasing, and finite values. Called on every read for each mark, with its row (its first
714
+ * part's) and its geometry, and for each of its named segments, with that part's row and the
715
+ * segment's geometry. They're checked when read: bad samples throw, changing nothing.
716
+ * `samplesAlong(mark, points)` gives a line its samples from the points that drew it. Default: rects
717
+ * with a numeric `value` get the bar chart's samples (from 0 at the baseline to their total, each
718
+ * segment over its own range), and circles with one get it as their one sample, `{ t: 0, value }`;
719
+ * other marks get none.
720
+ */
721
+ readonly samples?: (datum: D, mark: MarkGeometry) => readonly Sample[];
722
+ /**
723
+ * The edge rects grow from. Default "auto": the line every mark has an edge on, so bars sharing
724
+ * their left edge grow right; a bar whose other edge is on the line grows the other way, like a
725
+ * negative bar.
726
+ */
727
+ readonly baseline?: Baseline | "auto";
728
+ /**
729
+ * Default: the page-wide `motion`. A mode is this attachment's author default: the viewer's choice
730
+ * on the page-wide motion and the device's reduced-motion setting still win.
731
+ */
732
+ readonly motion?: Motion | MotionMode;
733
+ /** NoInfer: a generic data effect such as threshold() must not widen D to unknown. */
734
+ readonly on?: EffectSlots<NoInfer<D>>;
735
+ /**
736
+ * Makes marks focusable with a roving tabindex: Tab reaches one mark, the arrow keys, Home and End
737
+ * move between them in the order `marks()` gives (around a pie, clockwise from 12 o'clock), and
738
+ * focus plays the hover effects. Escape or leaving the chart stops them.
739
+ */
740
+ readonly keyboard?: boolean;
741
+ /**
742
+ * Dim the other marks while one is hovered (to --ec-dim-opacity), and give the hovered one its strong
743
+ * colour, as our charts do: its fill, or its stroke when the fill is none (a line), stepped toward the
744
+ * text colour, so darker in the light theme and lighter in the dark. Default false: the host owns its styling.
745
+ */
746
+ readonly dim?: boolean;
747
+ /**
748
+ * Names each mark for screen readers, as one item: "Okafor: 16 goals, 4 assists". The element that
749
+ * takes the mark's focus (its first part) becomes `role="img"` with this as its aria-label, and the
750
+ * mark's other parts are hidden (`aria-hidden`), so a stack isn't read in pieces. Unnamed host groups
751
+ * around them lose a role that would be read in their place (`img`, `graphics-symbol` or
752
+ * `graphics-object`, as Vega gives them). Given the mark's row (its first part's) and the mark.
753
+ * Called for every mark on each read, never per frame. An empty result, or a throw (reported), leaves
754
+ * that mark's ARIA as the host drew it. Default: the adapter writes no ARIA, and the host names its
755
+ * own marks.
756
+ */
757
+ readonly markLabel?: (datum: D, mark: HostMark<D>) => string;
758
+ /**
759
+ * Follows the host's own transitions, frame by frame, without refresh(): a MutationObserver notes
760
+ * changes to the marks' geometry attributes (d, x, y, width, height, cx, cy, r, rx, ry, x1, y1, x2,
761
+ * y2, points, transform), and to transform and style on their ancestors up to the root <svg>. Once a
762
+ * frame, on the clock, the marks that changed are read again (their rows, geometry and samples) and
763
+ * their effects follow, with no events. Values, colours, stroke widths, names and the elements
764
+ * themselves stay as the last refresh() read them: call refresh() when the host joins new data. `geometry` should read the element, or a row the
765
+ * host updates each frame; one that reads a transition's target row sees only the end. Default false.
766
+ */
767
+ readonly watch?: boolean;
703
768
  }
704
769
  /** What `markLabel` is given beside the row: the mark's key and its parts. */
705
770
  interface HostMark<D> {
706
- readonly key: string;
707
- /** From the baseline, or in document order for marks described with `geometry`. `series` is the part's `segment`. */
708
- readonly parts: readonly {
709
- readonly series: string | undefined;
710
- readonly datum: D;
711
- }[];
771
+ readonly key: string;
772
+ /** From the baseline, or in document order for marks described with `geometry`. `series` is the part's `segment`. */
773
+ readonly parts: readonly {
774
+ readonly series: string | undefined;
775
+ readonly datum: D;
776
+ }[];
712
777
  }
713
778
  interface Attachment<D> {
714
- /**
715
- * Call after the host re-renders: re-reads the marks (from `source` if given, and from then on) and
716
- * fires enter, update and exit by key. An update means a part's `value` changed, or without `value`
717
- * the mark's length; either way, gaining or losing a segment. A mark that only moved follows without
718
- * one. Throws, changing nothing, on marks it can't read.
719
- */
720
- refresh(source?: MarkSource<D>): void;
721
- /** Listens for mark events; returns the unsubscribe. */
722
- on<K extends keyof MarkEvents<D>>(type: K, listener: (event: MarkEvents<D>[K]) => void): () => void;
723
- /**
724
- * The marks now attached, in visual order (leaving marks excluded): bars top to bottom and columns
725
- * left to right. Marks described with `geometry` that go round one pivot (a pie's slices: each
726
- * pivot within 0.5 px of the first, and each mark's `start`, `center` and `end` the same distance
727
- * from it, more than 0.5 px away) go clockwise from 12 o'clock, by the angle of each mark's
728
- * `center` about it. Other `geometry` marks keep document order, lines that start at one point too.
729
- */
730
- marks(): readonly MarkGeometry[];
731
- /** With `keyboard: true`, moves focus to the mark, which plays its hover effects. Does nothing for an unknown key. */
732
- focus(key: string): void;
733
- /** Clears every effect and removes everything the adapter added, leaving the host's DOM as it was. */
734
- destroy(): void;
735
- }
736
-
779
+ /**
780
+ * Call after the host re-renders: re-reads the marks (from `source` if given, and from then on) and
781
+ * fires enter, update and exit by key. An update means a part's `value` changed, or without `value`
782
+ * the mark's length; either way, gaining or losing a segment. A mark that only moved follows without
783
+ * one. Throws, changing nothing, on marks it can't read.
784
+ */
785
+ refresh(source?: MarkSource<D>): void;
786
+ /**
787
+ * Swaps the effects for a new `on`, as a chart's update({ on }) does, and resolves once that's done:
788
+ * at once, since an attachment has no change to settle. A slot given the same effect or preset name
789
+ * keeps its runs, and a slot left out is cleared. A changed slot's runs are cleared and the new effect
790
+ * starts where they were: `decorate` again on every mark, and a held hover replays with the new hover
791
+ * effect. `enter`, `update` and `exit` draw the new effect's end state where theirs were, so nothing
792
+ * enters again. Focus stays on its mark, and the tab stop where it was. A data effect finds the series
793
+ * it reads (`needs`), so it follows a mark of that series as before. Rejects, changing nothing, on an
794
+ * `on` it can't resolve (an unknown preset name), a series a data effect needs that the marks don't
795
+ * have, or any other option, which can't change yet.
796
+ */
797
+ update(next: {
798
+ readonly on?: EffectSlots<D>;
799
+ }): Promise<void>;
800
+ /** Listens for mark events; returns the unsubscribe. */
801
+ on<K extends keyof MarkEvents<D>>(type: K, listener: (event: MarkEvents<D>[K]) => void): () => void;
802
+ /**
803
+ * The marks now attached, in visual order (leaving marks excluded): bars top to bottom and columns
804
+ * left to right. Other marks (circles, shapes, marks described with `geometry`, and bars among
805
+ * circles or shapes) keep document order, but marks that go round one pivot (a pie's slices: each
806
+ * pivot within 0.5 px of the first, and each mark's `start`, `center` and `end` the same distance
807
+ * from it, more than 0.5 px away) go clockwise from 12 o'clock, by the angle of each mark's
808
+ * `center` about it. Lines that start at one point keep document order.
809
+ */
810
+ marks(): readonly MarkGeometry[];
811
+ /** With `keyboard: true`, moves focus to the mark, which plays its hover effects. Does nothing for an unknown key. */
812
+ focus(key: string): void;
813
+ /**
814
+ * Ends the hover, pointer or keyboard, as the viewer moving away would: the emphasis, the dimming and
815
+ * the hover effects end, and `leave` fires for each mark that was hovered. A link's hover shown here
816
+ * ends too. Focus stays where it is, with its ring, as after Escape; the pointer hovers again when it
817
+ * next moves onto a mark. Does nothing when nothing is hovered.
818
+ */
819
+ leave(): void;
820
+ /** Clears every effect and removes everything the adapter added, leaving the host's DOM as it was. */
821
+ destroy(): void;
822
+ }
737
823
  /**
738
824
  * What fromVegaView() uses of a Vega View: its renderer, its scenegraph and the element it renders
739
825
  * into. The scenegraph is read as `{ root }` (what Vega returns) or as the root mark itself (what
740
826
  * vega-typings declare), so a View fits whichever the types say.
741
827
  */
742
828
  interface VegaViewLike {
743
- renderer(): string;
744
- scenegraph(): object;
745
- container(): Element | null;
829
+ renderer(): string;
830
+ scenegraph(): object;
831
+ container(): Element | null;
746
832
  }
747
833
  /** A mark in Vega's scenegraph: its type, its name, and its items. */
748
834
  interface VegaMark {
749
- readonly marktype?: string;
750
- readonly name?: string;
751
- readonly items?: readonly VegaItem[];
835
+ readonly marktype?: string;
836
+ readonly name?: string;
837
+ readonly items?: readonly VegaItem[];
752
838
  }
753
839
  /** An item of a Vega mark, as its encoders left it. A group's items hold the marks inside it. */
754
840
  interface VegaItem {
755
- readonly mark?: VegaMark;
756
- readonly datum?: unknown;
757
- readonly items?: readonly VegaMark[];
758
- readonly x?: number;
759
- readonly y?: number;
760
- readonly width?: number;
761
- readonly height?: number;
762
- readonly startAngle?: number;
763
- readonly endAngle?: number;
764
- readonly innerRadius?: number;
765
- readonly outerRadius?: number;
766
- readonly size?: number;
767
- readonly strokeWidth?: number;
768
- readonly cornerRadius?: number;
769
- readonly defined?: boolean;
770
- /** How a line is drawn between its points: only "linear" (or unset) can be read. */
771
- readonly interpolate?: string;
841
+ readonly mark?: VegaMark;
842
+ readonly datum?: unknown;
843
+ readonly items?: readonly VegaMark[];
844
+ readonly x?: number;
845
+ readonly y?: number;
846
+ readonly width?: number;
847
+ readonly height?: number;
848
+ readonly startAngle?: number;
849
+ readonly endAngle?: number;
850
+ readonly innerRadius?: number;
851
+ readonly outerRadius?: number;
852
+ readonly size?: number;
853
+ readonly strokeWidth?: number;
854
+ readonly cornerRadius?: number;
855
+ /** False for a line's point Vega leaves out, which breaks the line there. */
856
+ readonly defined?: boolean;
857
+ /** How a line is drawn between its points: "linear" (or unset) is read from the items, any other curve from the path Vega draws. */
858
+ readonly interpolate?: string;
772
859
  }
773
860
  /** A value for data effects: alone, or with where it is along x (`at`), which threshold matches series by. */
774
861
  type VegaSample = number | {
775
- readonly value: number;
776
- readonly at?: string | number | Date;
862
+ readonly value: number;
863
+ readonly at?: string | number | Date;
777
864
  };
778
865
  interface VegaOptions<D> extends Omit<ExpressiveOptions<D>, "datum" | "geometry" | "watch"> {
779
- /** The Vega mark to read, by name. Default "marks", the name Vega-Lite gives a chart's data mark. */
780
- readonly mark?: string;
781
- /**
782
- * For data effects: the value an item's row shows, and optionally where it is along x. A line gets a
783
- * sample at each of its points, a bar from 0 at its baseline to its value (a stack's segments each over
784
- * their own range), a slice from 0 to its value, and a point its value. `samples` replaces this.
785
- * Unless `value` is given, it's also what each element shows (a line: every point's), so a re-render
786
- * that only moves marks, such as a resize, isn't an update.
787
- */
788
- readonly sample?: (row: D) => VegaSample;
866
+ /** The Vega mark to read, by name. Default "marks", the name Vega-Lite gives a chart's data mark. */
867
+ readonly mark?: string;
868
+ /**
869
+ * For data effects: the value an item's row shows, and optionally where it is along x. A line gets a
870
+ * sample at each of its points, a bar from 0 at its baseline to its value (a stack's segments each over
871
+ * their own range), a slice from 0 to its value, and a point its value. `samples` replaces this.
872
+ * Unless `value` is given, it's also what each element shows (a line: every point's), so a re-render
873
+ * that only moves marks, such as a resize, isn't an update.
874
+ */
875
+ readonly sample?: (row: D) => VegaSample;
789
876
  }
790
877
  /** fromVegaView()'s attachment: refresh() reads the View again (it refreshes itself after each render too). */
791
878
  interface VegaAttachment<D> extends Omit<Attachment<D>, "refresh"> {
792
- refresh(): void;
879
+ refresh(): void;
793
880
  }
794
-
795
- /** What a link takes: a chart (barChart, donutChart, lineChart) or an attachment (expressive, fromVegaView), with rows D. */
881
+ /** What a link takes: a chart (barChart, donutChart, lineChart), a chartSwitch or an attachment (expressive, fromVegaView), with rows D. */
796
882
  interface LinkSource<D> {
797
- on(type: "hover", listener: (event: MarkEvents<D>["hover"]) => void): () => void;
798
- marks(): readonly MarkGeometry[];
883
+ on(type: "hover", listener: (event: MarkEvents<D>["hover"]) => void): () => void;
884
+ marks(): readonly MarkGeometry[];
799
885
  }
800
- /** The rows of the sources in S: each chart's and attachment's, as a union. */
886
+ /** The rows of the sources in S: each chart's, switch's and attachment's, as a union. */
801
887
  type RowsOf<S> = S extends LinkSource<infer D> ? D : never;
802
888
  interface LinkOptions<D> {
803
- /**
804
- * A mark's linking value, given the mark and its data as a hover event has them. Default: its last
805
- * sample's `at` if it has one (a line point's x), else its key (a bar's or a slice's category).
806
- * Values are compared as strings, a Date by its ISO string, as keys are. Undefined or null links
807
- * nothing, and so does a throw (reported).
808
- */
809
- readonly by?: (event: Pick<MarkEvent<D>, "mark" | "data">) => unknown;
810
- /** Whether linked marks play their chart's hover effect. Default true; false keeps them to emphasis and dimming. */
811
- readonly effects?: boolean;
889
+ /**
890
+ * A mark's linking value, given the mark and its data as a hover event has them. Default: its last
891
+ * sample's `at` if it has one (a line point's x), else its key (a bar's or a slice's category).
892
+ * Values are compared as strings, a Date by its ISO string, as keys are. Undefined or null links
893
+ * nothing, and so does a throw (reported).
894
+ */
895
+ readonly by?: (event: Pick<MarkEvent<D>, "mark" | "data">) => unknown;
896
+ /** Whether linked marks play their chart's hover effect. Default true; false keeps them to emphasis and dimming. */
897
+ readonly effects?: boolean;
812
898
  }
813
899
  interface Link {
814
- /** Ends the link: linked hovers end, and each source can be linked again. The sources' own hovers go on. */
815
- destroy(): void;
900
+ /** Ends the link: linked hovers end, and each source can be linked again. The sources' own hovers go on. */
901
+ destroy(): void;
816
902
  }
817
903
  /**
818
904
  * Links hover across `sources`: when one is hovered by the pointer, touch or the keyboard, every other
819
905
  * hovers its targets with that linking value (a line chart its x, a bar chart its bar), as `source:
820
906
  * "linked"`, and leaves them when it leaves. The newest hover anywhere in the link is the one shown.
821
- * Throws a TypeError, linking nothing, on a source that isn't a chart or an attachment, or one that's
822
- * in a link already. A destroyed source drops out.
907
+ * A chart switch takes part through its view on show. Throws a TypeError, linking nothing, on a source
908
+ * that isn't a chart, a chart switch or an attachment, or one that's in a link already, a switch's
909
+ * views' charts going with it. A destroyed source drops out.
823
910
  */
824
- declare function link<S extends LinkSource<unknown>>(sources: readonly S[], options?: LinkOptions<RowsOf<S>>): Link;
825
-
911
+ export declare function link<S extends LinkSource<unknown>>(sources: readonly S[], options?: LinkOptions<RowsOf<S>>): Link;
826
912
  /**
827
913
  * What a chart switch uses of each view's chart. A reference chart's handle has all of it: its
828
914
  * `<svg>` (which takes `ec-morphing` while its marks morph in the switch's overlay), its marks and
829
- * labels as drawn, focus by key, leave() to end its hover, and destroy().
915
+ * labels as drawn, focus by key, leave() to end its hover, and destroy(). A reference chart also
916
+ * has on(), which the switch's on() hears, and a hover a link can drive; a view without them isn't
917
+ * heard and isn't linked.
830
918
  */
831
919
  interface ChartSwitchView {
832
- readonly element: SVGSVGElement;
833
- marks(): readonly MarkGeometry[];
834
- labels(): readonly ChartLabel[];
835
- focus(key: string): void;
836
- leave(): void;
837
- destroy(): void;
920
+ readonly element: SVGSVGElement;
921
+ marks(): readonly MarkGeometry[];
922
+ labels(): readonly ChartLabel[];
923
+ focus(key: string): void;
924
+ leave(): void;
925
+ destroy(): void;
838
926
  }
839
927
  /**
840
928
  * Draws one view's chart in `container` and returns it. `colors` is the switch's assignment: pass it
@@ -845,80 +933,94 @@ type ChartSwitchViewFactory = (container: HTMLElement, colors: ColorAssignment)
845
933
  type ChartSwitchViews = Readonly<Record<string, ChartSwitchViewFactory>>;
846
934
  /** A view's name. */
847
935
  type ChartSwitchViewName<T extends ChartSwitchViews> = keyof T & string;
936
+ /** The rows of the views' charts, as a union: what the switch's events carry, and what a link's `by` reads. A view that may be left out counts when it's there. */
937
+ type ViewRows<T extends ChartSwitchViews> = RowsOf<ReturnType<NonNullable<T[ChartSwitchViewName<T>]>>>;
848
938
  interface ChartSwitchOptions<T extends ChartSwitchViews> {
849
- /** The views by name. Each is drawn once, when the switch is created, in a container of its own; they share one grid cell. */
850
- readonly views: T;
851
- /** The view shown first. */
852
- readonly initial: NoInfer<ChartSwitchViewName<T>>;
853
- /**
854
- * Plays each pair of marks, matched by key. Default: morph(). The switch draws the labels and the
855
- * fades, and starts a reverse, on morph's schedule: 950 ms base with transition timing, eased in
856
- * and out (easeInOutCubic), and from `start` the rest of a full run's time. A transition effect
857
- * can't report how far its shapes have got, so one with other timing still plays, but its shapes
858
- * drift from the labels and a switch back can jump.
859
- */
860
- readonly transition?: TransitionEffect;
861
- /** Palette slots by key, shared by every view (each view's function is given it). Default: a new assignment. */
862
- readonly colors?: ColorAssignment | Readonly<Record<string, number>>;
863
- /** A polite live region that says the new view's label (its chart's `label`) after each switch. Default false. */
864
- readonly announce?: boolean;
939
+ /** The views by name. Each is drawn once, when the switch is created, in a container of its own; they share one grid cell. */
940
+ readonly views: T;
941
+ /** The view shown first. */
942
+ readonly initial: NoInfer<ChartSwitchViewName<T>>;
943
+ /**
944
+ * Plays each pair of marks, matched by key. Default: morph(). The switch draws the labels and the
945
+ * fades, and starts a reverse, on morph's schedule: 950 ms base with transition timing, eased in
946
+ * and out (easeInOutCubic), and from `start` the rest of a full run's time. A transition effect
947
+ * can't report how far its shapes have got, so one with other timing still plays, but its shapes
948
+ * drift from the labels and a switch back can jump.
949
+ */
950
+ readonly transition?: TransitionEffect;
951
+ /** Palette slots by key, shared by every view (each view's function is given it). Default: a new assignment. */
952
+ readonly colors?: ColorAssignment | Readonly<Record<string, number>>;
953
+ /** A polite live region that says the new view's label (its chart's `label`) after each switch. Default false. */
954
+ readonly announce?: boolean;
865
955
  }
866
956
  interface ChartSwitch<T extends ChartSwitchViews> {
867
- /** The view shown, or the one a switch is heading for. */
868
- readonly current: ChartSwitchViewName<T>;
869
- /**
870
- * Switches to `view`: each mark morphs into the mark with its key, by the motion mode. Resolves
871
- * when the switch has landed, or as soon as another show() replaces it. A show() back to the view
872
- * a switch is leaving reverses it from where the shapes are; one to a third view lands the switch
873
- * first. With motion off, the switch has landed when show() returns. Rejects for an unknown view.
874
- */
875
- show(view: ChartSwitchViewName<T>): Promise<void>;
876
- /** The chart a view's function returned: for update(), on() and the rest. */
877
- chart<K extends ChartSwitchViewName<T>>(view: K): ReturnType<T[K]>;
878
- /** Ends any switch, destroys every view's chart and removes everything the switch added. */
879
- destroy(): void;
880
- }
881
-
957
+ /** The view shown, or the one a switch is heading for. */
958
+ readonly current: ChartSwitchViewName<T>;
959
+ /**
960
+ * Switches to `view`: each mark morphs into the mark with its key, by the motion mode. Resolves
961
+ * when the switch has landed, or as soon as another show() replaces it. A show() back to the view
962
+ * a switch is leaving reverses it from where the shapes are; one to a third view lands the switch
963
+ * first. With motion off, the switch has landed when show() returns. Rejects for an unknown view.
964
+ * One a `leave` listener calls as the old view's hover ends runs once the switch has begun.
965
+ */
966
+ show(view: ChartSwitchViewName<T>): Promise<void>;
967
+ /** The chart a view's function returned: for update(), on() and the rest. */
968
+ chart<K extends ChartSwitchViewName<T>>(view: K): ReturnType<T[K]>;
969
+ /**
970
+ * Listens for the mark events of the view on show (`current`), as its chart's on() does; returns
971
+ * the unsubscribe. The other views' events aren't heard. A switch makes the view it's heading for
972
+ * the one heard once the old view's hover has ended, so that hover's leave is heard too.
973
+ */
974
+ on<K extends keyof MarkEvents<ViewRows<T>>>(type: K, listener: (event: MarkEvents<ViewRows<T>>[K]) => void): () => void;
975
+ /** The marks of the view on show (`current`), as its chart's marks() gives them: while a switch plays, the view it's heading for's. */
976
+ marks(): readonly MarkGeometry[];
977
+ /**
978
+ * Ends the hover of the view on show (`current`), as its chart's leave() does: its own, or a
979
+ * link's. A link's hover then shows in the switch again with the link's next hover, not when a
980
+ * switch lands.
981
+ */
982
+ leave(): void;
983
+ /** Ends any switch, destroys every view's chart and removes everything the switch added. */
984
+ destroy(): void;
985
+ }
882
986
  /** How the stylesheet reaches the page. */
883
987
  interface StyleOptions {
884
- /** Set on the injected `<style>`, for a Content-Security-Policy that allows styles by nonce. */
885
- readonly nonce?: string | undefined;
886
- /** false: inject nothing; the page loads expressive-charts/style.css itself. Default true. */
887
- readonly injectStyles?: boolean | undefined;
988
+ /** Set on the injected `<style>`, for a Content-Security-Policy that allows styles by nonce. */
989
+ readonly nonce?: string | undefined;
990
+ /** false: inject nothing; the page loads expressive-charts/style.css itself. Default true. */
991
+ readonly injectStyles?: boolean | undefined;
888
992
  }
889
-
890
993
  interface MotionSwitchOptions {
891
- /** The group's visible label, which is also its accessible name. Default "Motion". */
892
- readonly label?: string;
893
- /** Button text by mode. Default "Presentation", "Analysis", "Off". */
894
- readonly labels?: Partial<Readonly<Record<MotionMode, string>>>;
895
- /**
896
- * The note beside the buttons, by effective mode, and `reduced` for while the device asks for
897
- * reduced motion and the viewer hasn't picked a mode.
898
- */
899
- readonly hints?: Partial<Readonly<Record<MotionMode | "reduced", string>>>;
900
- /**
901
- * A localStorage key. Opt-in: the viewer's choice is saved under it, and restored when the switch
902
- * is made, so it carries across pages and visits. Storage that's blocked or full is ignored.
903
- */
904
- readonly persist?: string;
994
+ /** The group's visible label, which is also its accessible name. Default "Motion". */
995
+ readonly label?: string;
996
+ /** Button text by mode. Default "Presentation", "Analysis", "Off". */
997
+ readonly labels?: Partial<Readonly<Record<MotionMode, string>>>;
998
+ /**
999
+ * The note beside the buttons, by effective mode, and `reduced` for while the device asks for
1000
+ * reduced motion and the viewer hasn't picked a mode.
1001
+ */
1002
+ readonly hints?: Partial<Readonly<Record<MotionMode | "reduced", string>>>;
1003
+ /**
1004
+ * A localStorage key. Opt-in: the viewer's choice is saved under it, and restored when the switch
1005
+ * is made, so it carries across pages and visits. Storage that's blocked or full is ignored.
1006
+ */
1007
+ readonly persist?: string;
905
1008
  }
906
1009
  interface MotionSwitch {
907
- /** The switch's root, a `role="group"` element appended to the target. */
908
- readonly element: HTMLElement;
909
- /** Removes the switch and stops following the motion. The viewer's choice stays. */
910
- destroy(): void;
1010
+ /** The switch's root, a `role="group"` element appended to the target. */
1011
+ readonly element: HTMLElement;
1012
+ /** Removes the switch and stops following the motion. The viewer's choice stays. */
1013
+ destroy(): void;
911
1014
  }
912
-
913
1015
  interface PlayButtonOptions {
914
- /** The button's text, which is its accessible name, by what a click does. Default "Play" and "Pause". */
915
- readonly labels?: Partial<Readonly<Record<"play" | "pause", string>>>;
1016
+ /** The button's text, which is its accessible name, by what a click does. Default "Play" and "Pause". */
1017
+ readonly labels?: Partial<Readonly<Record<"play" | "pause", string>>>;
916
1018
  }
917
1019
  interface PlayButton {
918
- /** The `<button type="button">` appended to the target. */
919
- readonly element: HTMLButtonElement;
920
- /** Removes the button and stops following the playback, which carries on as it is. */
921
- destroy(): void;
1020
+ /** The `<button type="button">` appended to the target. */
1021
+ readonly element: HTMLButtonElement;
1022
+ /** Removes the button and stops following the playback, which carries on as it is. */
1023
+ destroy(): void;
922
1024
  }
923
1025
  /**
924
1026
  * Builds a Play/Pause button in `target` (an element or a selector) for `playback`. A click plays or
@@ -926,42 +1028,41 @@ interface PlayButton {
926
1028
  * follows `playback.subscribe`, so it stays right whoever drives the playback, and it's the same
927
1029
  * element throughout, so focus stays on it.
928
1030
  */
929
- declare function playButton(target: string | Element, playback: Playback, options?: PlayButtonOptions): PlayButton;
930
-
1031
+ export declare function playButton(target: string | Element, playback: Playback, options?: PlayButtonOptions): PlayButton;
931
1032
  /** Where the icon is on its trip. Distances are in the icon's own units (px at its natural size), so a gait looks the same at any size. */
932
1033
  interface GaitState {
933
- /** How far the icon has gone. */
934
- readonly distance: number;
935
- /** The whole trip; 0 when the icon doesn't move. */
936
- readonly length: number;
937
- /** distance ÷ length, 0 to 1 (1 for a trip of length 0). */
938
- readonly progress: number;
939
- /** The icon's rolling radius. */
940
- readonly radius: number;
1034
+ /** How far the icon has gone. */
1035
+ readonly distance: number;
1036
+ /** The whole trip; 0 when the icon doesn't move. */
1037
+ readonly length: number;
1038
+ /** distance ÷ length, 0 to 1 (1 for a trip of length 0). */
1039
+ readonly progress: number;
1040
+ /** The icon's rolling radius. */
1041
+ readonly radius: number;
941
1042
  }
942
1043
  /** How the icon is held, relative to its place on the walk. */
943
1044
  interface GaitPose {
944
- /** Raised this far towards the icon's up side, in icon units. */
945
- readonly lift: number;
946
- /** Rolling rotation about the icon's pivot, in radians; positive rolls forward (clockwise when facing +x). */
947
- readonly spin: number;
948
- /** Rocking rotation about the icon's pivot, in radians; positive raises the front. */
949
- readonly tilt: number;
1045
+ /** Raised this far towards the icon's up side, in icon units. */
1046
+ readonly lift: number;
1047
+ /** Rolling rotation about the icon's pivot, in radians; positive rolls forward (clockwise when facing +x). */
1048
+ readonly spin: number;
1049
+ /** Rocking rotation about the icon's pivot, in radians; positive raises the front. */
1050
+ readonly tilt: number;
950
1051
  }
951
1052
  interface Gait {
952
- (state: GaitState): GaitPose;
953
- /** The trip's easing. Default easeOutCubic. */
954
- readonly ease?: Easing;
955
- /** Multiplies the trip's duration. Default 1. */
956
- readonly pace?: number;
1053
+ (state: GaitState): GaitPose;
1054
+ /** The trip's easing. Default easeOutCubic. */
1055
+ readonly ease?: Easing;
1056
+ /** Multiplies the trip's duration. Default 1. */
1057
+ readonly pace?: number;
957
1058
  }
958
1059
  interface StepOptions {
959
- /** Distance per step, in icon units. Default 42. */
960
- readonly stride?: number;
961
- /** Height of each step, in icon units. Default 3.2. */
962
- readonly lift?: number;
963
- /** Most the front is raised during a step, in degrees. Default 9. */
964
- readonly tilt?: number;
1060
+ /** Distance per step, in icon units. Default 42. */
1061
+ readonly stride?: number;
1062
+ /** Height of each step, in icon units. Default 3.2. */
1063
+ readonly lift?: number;
1064
+ /** Most the front is raised during a step, in degrees. Default 9. */
1065
+ readonly tilt?: number;
965
1066
  }
966
1067
  /** Rolls without slipping: the spin is the distance over the radius. */
967
1068
  declare function roll(): Gait;
@@ -973,28 +1074,27 @@ declare function roll(): Gait;
973
1074
  declare function step(options?: StepOptions): Gait;
974
1075
  /** Slides along without turning. */
975
1076
  declare function slide(): Gait;
976
- declare const gaits: {
977
- roll: typeof roll;
978
- step: typeof step;
979
- slide: typeof slide;
1077
+ export declare const gaits: {
1078
+ roll: typeof roll;
1079
+ step: typeof step;
1080
+ slide: typeof slide;
980
1081
  };
981
1082
  /** The gaits icons and options name. */
982
1083
  type GaitName = keyof typeof gaits;
983
-
984
1084
  interface TravelOptions {
985
- /**
986
- * A segment's series ("goals"); the whole walk if omitted. A mark with no segments counts as its
987
- * own one segment. A missing segment, or one shorter than 0.5 px, makes travel a no-op.
988
- */
989
- readonly along?: string;
990
- /** How the icon moves. Default: the icon's own gait, else "slide". */
991
- readonly gait?: Gait | GaitName;
992
- /** Length along the walk in px, or "fit": scaled so the icon is 85% of the mark's thickness across. Default: the icon's own size. */
993
- readonly size?: number | "fit";
994
- /** "follow" turns with the walk, "level" never turns, "auto" (default) follows but mirrors an upright icon instead of turning it upside down. */
995
- readonly orient?: "auto" | "follow" | "level";
996
- /** "center" (default) puts the icon's anchor on the walk; "on" sits the icon on top of it (a ball riding a line). */
997
- readonly ride?: "center" | "on";
1085
+ /**
1086
+ * A segment's series ("goals"); the whole walk if omitted. A mark with no segments counts as its
1087
+ * own one segment. A missing segment, or one shorter than 0.5 px, makes travel a no-op.
1088
+ */
1089
+ readonly along?: string;
1090
+ /** How the icon moves. Default: the icon's own gait, else "slide". */
1091
+ readonly gait?: Gait | GaitName;
1092
+ /** Length along the walk in px, or "fit": scaled so the icon is 85% of the mark's thickness across. Default: the icon's own size. */
1093
+ readonly size?: number | "fit";
1094
+ /** "follow" turns with the walk, "level" never turns, "auto" (default) follows but mirrors an upright icon instead of turning it upside down. */
1095
+ readonly orient?: "auto" | "follow" | "level";
1096
+ /** "center" (default) puts the icon's anchor on the walk; "on" sits the icon on top of it (a ball riding a line). */
1097
+ readonly ride?: "center" | "on";
998
1098
  }
999
1099
  /**
1000
1100
  * Moves an icon along the walk, or along one segment, inset by the icon's footprint so it stays
@@ -1006,15 +1106,14 @@ interface TravelOptions {
1006
1106
  * parts it's drawn on, and a part shorter than the icon is skipped, unless it's the last: the icon
1007
1107
  * rests there, at the last value.
1008
1108
  */
1009
- declare function travel(icon: Icon | string, options?: TravelOptions): GeometryEffect;
1010
-
1109
+ export declare function travel(icon: Icon | string, options?: TravelOptions): GeometryEffect;
1011
1110
  interface FlashOptions {
1012
- /** The halo's widest stroke, px; half of it shows outside the mark. Default 8, as in the prototype. */
1013
- readonly width?: number;
1014
- /** Default 0.35. */
1015
- readonly opacity?: number;
1016
- /** A theme token or any CSS colour. Default: the mark's own colour. */
1017
- readonly color?: Color;
1111
+ /** The halo's widest stroke, px; half of it shows outside the mark. Default 8, as in the prototype. */
1112
+ readonly width?: number;
1113
+ /** Default 0.35. */
1114
+ readonly opacity?: number;
1115
+ /** A theme token or any CSS colour. Default: the mark's own colour. */
1116
+ readonly color?: Color;
1018
1117
  }
1019
1118
  /**
1020
1119
  * One blink of a halo along the mark's outline: the stroke grows from 0 to `width` and back over a
@@ -1024,11 +1123,10 @@ interface FlashOptions {
1024
1123
  * at (the bar's new length, its new value label) stays on the chart, so with motion off or reduced
1025
1124
  * the viewer still sees everything the flash would have drawn attention to.
1026
1125
  */
1027
- declare function flash(options?: FlashOptions): GeometryEffect;
1028
-
1126
+ export declare function flash(options?: FlashOptions): GeometryEffect;
1029
1127
  interface WiggleOptions {
1030
- /** How far the point of the mark farthest from its pivot may move, px: more than 0, at most 3. Default 3. */
1031
- readonly swing?: number;
1128
+ /** How far the point of the mark farthest from its pivot may move, px: more than 0, at most 3. Default 3. */
1129
+ readonly swing?: number;
1032
1130
  }
1033
1131
  /**
1034
1132
  * Rocks the mark about `mark.pivot` in three decaying half-swings over a 450 ms base. The angle is
@@ -1037,15 +1135,14 @@ interface WiggleOptions {
1037
1135
  *
1038
1136
  * Its end state is no transform: the mark rests where the chart drew it.
1039
1137
  */
1040
- declare function wiggle(options?: WiggleOptions): GeometryEffect;
1041
-
1138
+ export declare function wiggle(options?: WiggleOptions): GeometryEffect;
1042
1139
  interface PulseOptions {
1043
- /** How many pulses, a whole number from 1 to 6. Fewer play if they wouldn't finish within 5 s. Default 2. */
1044
- readonly times?: number;
1045
- /** The halo's widest stroke, px; half of it shows outside the mark. Default 12. */
1046
- readonly width?: number;
1047
- /** A theme token or any CSS colour. Default: the mark's own colour. */
1048
- readonly color?: Color;
1140
+ /** How many pulses, a whole number from 1 to 6. Fewer play if they wouldn't finish within 5 s. Default 2. */
1141
+ readonly times?: number;
1142
+ /** The halo's widest stroke, px; half of it shows outside the mark. Default 12. */
1143
+ readonly width?: number;
1144
+ /** A theme token or any CSS colour. Default: the mark's own colour. */
1145
+ readonly color?: Color;
1049
1146
  }
1050
1147
  /**
1051
1148
  * Halos that widen from 0 to `width` while fading from 40% to nothing, 600 ms base each, `times`
@@ -1055,17 +1152,16 @@ interface PulseOptions {
1055
1152
  * It never changes the mark's size, so a value never looks bigger than it is. Its end state is
1056
1153
  * nothing: a pulse draws attention, and what it points at stays on the chart.
1057
1154
  */
1058
- declare function pulse(options?: PulseOptions): GeometryEffect;
1059
-
1155
+ export declare function pulse(options?: PulseOptions): GeometryEffect;
1060
1156
  interface TraceOptions {
1061
- /** A theme token or any CSS colour. Default "mark", the mark's own colour (a stack's first segment's). */
1062
- readonly color?: Color;
1063
- /** The stroke's width, px. Default 3. */
1064
- readonly width?: number;
1065
- /** From 0 to 1. Default 0.5. */
1066
- readonly opacity?: number;
1067
- /** Base ms to draw the stroke, before the motion mode scales it, with effect timing. Default 500. */
1068
- readonly duration?: number;
1157
+ /** A theme token or any CSS colour. Default "mark", the mark's own colour (a stack's first segment's). */
1158
+ readonly color?: Color;
1159
+ /** The stroke's width, px. Default 3. */
1160
+ readonly width?: number;
1161
+ /** From 0 to 1. Default 0.5. */
1162
+ readonly opacity?: number;
1163
+ /** Base ms to draw the stroke, before the motion mode scales it, with effect timing. Default 500. */
1164
+ readonly duration?: number;
1069
1165
  }
1070
1166
  /**
1071
1167
  * Draws an overlay stroke along the mark's walk, from its start to its end, eased in and out over
@@ -1075,15 +1171,14 @@ interface TraceOptions {
1075
1171
  * The stroke stays, and follows `onChange`, so it keeps to the mark through a transition or a
1076
1172
  * resize. Its end state is the whole stroke, so reduced motion shows what a full run ends with.
1077
1173
  */
1078
- declare function trace(options?: TraceOptions): GeometryEffect;
1079
-
1174
+ export declare function trace(options?: TraceOptions): GeometryEffect;
1080
1175
  interface DeltaOptions<D = unknown> {
1081
- /** The mark's value. Default: its last sample's, so a bar's total, a line's value at its revealed end, a slice's share. */
1082
- readonly value?: (data: MarkData<D>) => number;
1083
- /** Words the change. Default: the page's locale, with its sign and at most two decimals ("+2", "-0.3"). */
1084
- readonly format?: (change: number) => string;
1085
- /** A theme token or any CSS colour. Default "text", never the series' colour. */
1086
- readonly color?: Color;
1176
+ /** The mark's value. Default: its last sample's, so a bar's total, a line's value at its revealed end, a slice's share. */
1177
+ readonly value?: (data: MarkData<D>) => number;
1178
+ /** Words the change. Default: the page's locale, with its sign and at most two decimals ("+2", "-0.3"). */
1179
+ readonly format?: (change: number) => string;
1180
+ /** A theme token or any CSS colour. Default "text", never the series' colour. */
1181
+ readonly color?: Color;
1087
1182
  }
1088
1183
  /**
1089
1184
  * The change since the last update, `value(data) − value(data.previous)`, as text past the end of the
@@ -1095,11 +1190,10 @@ interface DeltaOptions<D = unknown> {
1095
1190
  * The text is in the overlay, which screen readers don't read: a page that relies on it says the same
1096
1191
  * in its table or its announcement.
1097
1192
  */
1098
- declare function delta<D = unknown>(options?: DeltaOptions<D>): DataEffect<D>;
1099
-
1193
+ export declare function delta<D = unknown>(options?: DeltaOptions<D>): DataEffect<D>;
1100
1194
  interface LabelOptions {
1101
- /** A theme token or any CSS colour. Default "text", never the series' colour. */
1102
- readonly color?: Color;
1195
+ /** A theme token or any CSS colour. Default "text", never the series' colour. */
1196
+ readonly color?: Color;
1103
1197
  }
1104
1198
  /**
1105
1199
  * Text from `text(data, mark)` past the end of the mark: 10 px past the end of its walk, or 6 px
@@ -1112,18 +1206,17 @@ interface LabelOptions {
1112
1206
  * the overlay, which screen readers don't read: a page that relies on it says the same in its table
1113
1207
  * or its announcement.
1114
1208
  */
1115
- declare function label<D = unknown>(text: (data: MarkData<D>, mark: MarkGeometry) => string | undefined, options?: LabelOptions): DataEffect<D>;
1116
-
1209
+ export declare function label<D = unknown>(text: (data: MarkData<D>, mark: MarkGeometry) => string | undefined, options?: LabelOptions): DataEffect<D>;
1117
1210
  interface ThresholdOptions {
1118
- /**
1119
- * The reference: a constant, or the name of a related series ("xg"), which goes in `needs.related`
1120
- * so a chart without that series throws when it's created.
1121
- */
1122
- readonly compareTo: number | string;
1123
- /** Colour where the mark's values are "below" the reference (default) or "above" it. Equal values aren't coloured. */
1124
- readonly when?: "below" | "above";
1125
- /** A theme token or any CSS colour. Default "negative". */
1126
- readonly color?: Color;
1211
+ /**
1212
+ * The reference: a constant, or the name of a related series ("xg"), which goes in `needs.related`
1213
+ * so a chart without that series throws when it's created.
1214
+ */
1215
+ readonly compareTo: number | string;
1216
+ /** Colour where the mark's values are "below" the reference (default) or "above" it. Equal values aren't coloured. */
1217
+ readonly when?: "below" | "above";
1218
+ /** A theme token or any CSS colour. Default "negative". */
1219
+ readonly color?: Color;
1127
1220
  }
1128
1221
  /**
1129
1222
  * Colours the parts of the walk where the mark's values are below `compareTo` (or above it, with
@@ -1143,23 +1236,22 @@ interface ThresholdOptions {
1143
1236
  * It draws at once, with no animation, and redraws on every `onChange`, so it follows a line as it's
1144
1237
  * revealed. Its end state is the same picture, so the colour shows with motion off.
1145
1238
  */
1146
- declare function threshold(options: ThresholdOptions): DataEffect;
1147
-
1239
+ export declare function threshold(options: ThresholdOptions): DataEffect;
1148
1240
  /** How two closed outlines' sides are matched. */
1149
1241
  type MorphAlign = "unroll" | "drop";
1150
1242
  interface MorphOptions {
1151
- /** Points sampled on each outline, a whole multiple of 4 (a quarter on each side of a closed one). Default 160, the lab's 40 a side. */
1152
- readonly points?: number;
1153
- /**
1154
- * How two closed outlines' sides are matched:
1155
- * - "unroll" matches each side with the same side. A slice's walk becomes a column's, so the slice
1156
- * stands up: its outer arc becomes the column's left side, and the angle it spans its height.
1157
- * - "drop" turns the matching by one side, as the lab does: a slice's outer arc becomes a column's
1158
- * top, so it settles onto the baseline.
1159
- *
1160
- * Default "unroll", picked over "drop" by comparing the two in the morph demo (demo/morph.html).
1161
- */
1162
- readonly align?: MorphAlign;
1243
+ /** Points sampled on each outline, a whole multiple of 4 (a quarter on each side of a closed one). Default 160, the lab's 40 a side. */
1244
+ readonly points?: number;
1245
+ /**
1246
+ * How two closed outlines' sides are matched:
1247
+ * - "unroll" matches each side with the same side. A slice's walk becomes a column's, so the slice
1248
+ * stands up: its outer arc becomes the column's left side, and the angle it spans its height.
1249
+ * - "drop" turns the matching by one side, as the lab does: a slice's outer arc becomes a column's
1250
+ * top, so it settles onto the baseline.
1251
+ *
1252
+ * Default "unroll", picked over "drop" by comparing the two in the morph demo (demo/morph.html).
1253
+ */
1254
+ readonly align?: MorphAlign;
1163
1255
  }
1164
1256
  /**
1165
1257
  * Morphs `from` into `to` over 950 ms base (`transition` timing: at most 200 ms in Analysis, a jump
@@ -1177,8 +1269,7 @@ interface MorphOptions {
1177
1269
  * A run from `ctx.start` begins with the shapes there, in their eased progress, and takes the rest
1178
1270
  * of the time a full run would. The end state is the target's own outline.
1179
1271
  */
1180
- declare function morph(options?: MorphOptions): TransitionEffect;
1181
-
1272
+ export declare function morph(options?: MorphOptions): TransitionEffect;
1182
1273
  /**
1183
1274
  * Runs the parts one after another, each on the geometry and data as they are when it starts, since
1184
1275
  * the mark may move while an earlier part runs (a transition, a line being revealed). An abort stops
@@ -1186,19 +1277,19 @@ declare function morph(options?: MorphOptions): TransitionEffect;
1186
1277
  * along a missing segment) finishes at once, so one sequence tells the whole story whatever the chart
1187
1278
  * shows.
1188
1279
  */
1189
- declare function sequence<E extends readonly AnyMarkEffect[]>(...effects: E): Combined<E>;
1280
+ export declare function sequence<E extends readonly AnyMarkEffect[]>(...effects: E): Combined<E>;
1190
1281
  /** Runs the parts together and finishes when they all have. `end()` draws every part's end state, in order. */
1191
- declare function parallel<E extends readonly AnyMarkEffect[]>(...effects: E): Combined<E>;
1282
+ export declare function parallel<E extends readonly AnyMarkEffect[]>(...effects: E): Combined<E>;
1192
1283
  /**
1193
1284
  * What `only` and `stagger` return: a new effect of the same kind, needing the same rows. Only the
1194
1285
  * effect interface is kept, not any other members the effect has.
1195
1286
  */
1196
1287
  type Filtered<E extends AnyMarkEffect> = E extends DataEffect<infer D> ? DataEffect<D> : GeometryEffect;
1197
1288
  /** Runs the effect only on matching marks: a key, a series name, or a predicate. Elsewhere it does nothing. */
1198
- declare function only<E extends AnyMarkEffect>(filter: string | ((mark: MarkGeometry) => boolean), effect: E): Filtered<E>;
1289
+ export declare function only<E extends AnyMarkEffect>(filter: string | ((mark: MarkGeometry) => boolean), effect: E): Filtered<E>;
1199
1290
  interface StaggerOptions {
1200
- /** Base ms between one mark's start and the next's, 0 or more. Default 50. */
1201
- readonly delay?: number;
1291
+ /** Base ms between one mark's start and the next's, 0 or more. Default 50. */
1292
+ readonly delay?: number;
1202
1293
  }
1203
1294
  /**
1204
1295
  * Starts each mark of a batch a little after the one before: mark i waits `i × delay` (base ms,
@@ -1208,16 +1299,15 @@ interface StaggerOptions {
1208
1299
  * Never a default: research finds little benefit in staggering, and it can hurt. It keeps the
1209
1300
  * effect's kind and `needs`, and `end()` draws the effect's end state at once.
1210
1301
  */
1211
- declare function stagger<E extends AnyMarkEffect>(effect: E, options?: StaggerOptions): Filtered<E>;
1212
-
1302
+ export declare function stagger<E extends AnyMarkEffect>(effect: E, options?: StaggerOptions): Filtered<E>;
1213
1303
  /** What defineEffect takes: a geometry effect without its `kind`, `clear()` optional. */
1214
1304
  interface GeometryEffectSpec {
1215
- /** Animates the mark; resolves when done or cancelled (ctx.signal aborted). */
1216
- run(mark: MarkGeometry, ctx: EffectContext): Promise<void>;
1217
- /** Draws the state a full run ends in, at once. Reduced motion shows only this. */
1218
- end(mark: MarkGeometry, ctx: EffectContext): void;
1219
- /** Cleanup beyond the runner's own (it empties the layer and resets the mark anyway). */
1220
- clear?(ctx: EffectContext): void;
1305
+ /** Animates the mark; resolves when done or cancelled (ctx.signal aborted). */
1306
+ run(mark: MarkGeometry, ctx: EffectContext): Promise<void>;
1307
+ /** Draws the state a full run ends in, at once. Reduced motion shows only this. */
1308
+ end(mark: MarkGeometry, ctx: EffectContext): void;
1309
+ /** Cleanup beyond the runner's own (it empties the layer and resets the mark anyway). */
1310
+ clear?(ctx: EffectContext): void;
1221
1311
  }
1222
1312
  /**
1223
1313
  * What defineDataEffect takes: a data effect without its `kind`, `clear()` optional. As on
@@ -1225,13 +1315,13 @@ interface GeometryEffectSpec {
1225
1315
  * methods would let a spec that reads fields `D` doesn't have through.
1226
1316
  */
1227
1317
  interface DataEffectSpec<D> {
1228
- /** Series the effect reads through data.related(), checked when a chart is created. */
1229
- readonly needs?: {
1230
- readonly related?: readonly string[];
1231
- };
1232
- readonly run: (mark: MarkGeometry, data: MarkData<D>, ctx: EffectContext) => Promise<void>;
1233
- readonly end: (mark: MarkGeometry, data: MarkData<D>, ctx: EffectContext) => void;
1234
- readonly clear?: (ctx: EffectContext) => void;
1318
+ /** Series the effect reads through data.related(), checked when a chart is created. */
1319
+ readonly needs?: {
1320
+ readonly related?: readonly string[];
1321
+ };
1322
+ readonly run: (mark: MarkGeometry, data: MarkData<D>, ctx: EffectContext) => Promise<void>;
1323
+ readonly end: (mark: MarkGeometry, data: MarkData<D>, ctx: EffectContext) => void;
1324
+ readonly clear?: (ctx: EffectContext) => void;
1235
1325
  }
1236
1326
  /**
1237
1327
  * A geometry effect from its `run` and `end`: `kind` is filled in and `clear` defaults to doing
@@ -1239,15 +1329,14 @@ interface DataEffectSpec<D> {
1239
1329
  * `end` functions throws a TypeError: every effect needs an end state, since reduced motion shows
1240
1330
  * only that.
1241
1331
  */
1242
- declare function defineEffect(spec: GeometryEffectSpec): GeometryEffect;
1332
+ export declare function defineEffect(spec: GeometryEffectSpec): GeometryEffect;
1243
1333
  /**
1244
1334
  * A data effect from its `run` and `end`, which also get the mark's data (`MarkData<D>`): its row,
1245
1335
  * values along the walk, related series and the values before an update. `needs.related` lists the
1246
1336
  * series it reads through `data.related()`, so a chart without them throws when it's created.
1247
1337
  * Otherwise as defineEffect.
1248
1338
  */
1249
- declare function defineDataEffect<D = unknown>(spec: DataEffectSpec<D>): DataEffect<D>;
1250
-
1339
+ export declare function defineDataEffect<D = unknown>(spec: DataEffectSpec<D>): DataEffect<D>;
1251
1340
  /** What defineIcon takes: an Icon whose pivot, footprint and size are optional. */
1252
1341
  type IconSpec = Omit<Icon, "footprint" | "pivot" | "size"> & Partial<Pick<Icon, "footprint" | "pivot" | "size">>;
1253
1342
  /**
@@ -1256,8 +1345,7 @@ type IconSpec = Omit<Icon, "footprint" | "pivot" | "size"> & Partial<Pick<Icon,
1256
1345
  * edges, `size` is the box's width and `radius` half its height. Bad input throws a RangeError
1257
1346
  * naming the field. The icon and its parts are frozen, since one icon is shared by every run.
1258
1347
  */
1259
- declare function defineIcon(spec: IconSpec): Icon;
1260
-
1348
+ export declare function defineIcon(spec: IconSpec): Icon;
1261
1349
  /**
1262
1350
  * What iconFromSvg takes besides the markup. `anchor`, `pivot`, `footprint` and `radius` are in the
1263
1351
  * SVG's own units (its viewBox). `size` is the natural length in px: the whole icon is scaled so its
@@ -1266,29 +1354,26 @@ declare function defineIcon(spec: IconSpec): Icon;
1266
1354
  type SvgIconSpec = Omit<IconSpec, "shapes" | "box">;
1267
1355
  /**
1268
1356
  * Converts `path`, `circle`, `rect`, `ellipse`, `line`, `polyline` and `polygon` elements into shapes,
1269
- * with their fill, stroke, stroke width, line caps and joins, fill rule and opacity (as attributes or in
1270
- * `style`, inherited from `<g>`, a group's opacity multiplied into its shapes') and transforms applied.
1271
- * `currentColor` becomes the theme's `text` colour, so an icon from an icon set follows the chart's
1272
- * theme. Everything else is dropped: scripts, event handlers, `<use>`, text, images, what's inside
1273
- * `<defs>`, `<clipPath>` and the like, and shapes with an opacity of 0. Gradients, patterns, `fill-opacity`,
1274
- * `stroke-opacity` and CSS classes aren't kept; a shape painted with a gradient or pattern falls back to
1275
- * its inherited colour.
1357
+ * with their fill, stroke, stroke width, line caps and joins, fill rule, opacity, fill opacity and stroke
1358
+ * opacity (as attributes or in `style`, inherited from `<g>`, a group's opacity multiplied into its
1359
+ * shapes') and transforms applied. `currentColor` becomes the theme's `text` colour, so an icon from an
1360
+ * icon set follows the chart's theme. Everything else is dropped: scripts, event handlers, `<use>`, text,
1361
+ * images, what's inside `<defs>`, `<clipPath>` and the like, shapes with an opacity of 0, and fills and
1362
+ * strokes with one of 0. Gradients, patterns and CSS classes aren't kept; a shape painted with a gradient
1363
+ * or pattern falls back to its inherited colour.
1276
1364
  */
1277
- declare function iconFromSvg(markup: string, spec: SvgIconSpec): Icon;
1278
-
1365
+ export declare function iconFromSvg(markup: string, spec: SvgIconSpec): Icon;
1279
1366
  /** The built-in icons, registered by name in every chart: `travel("arrow")` or `travel(icons.arrow)`. */
1280
- declare const icons: {
1281
- readonly dot: Icon;
1282
- readonly arrow: Icon;
1283
- readonly chevron: Icon;
1367
+ export declare const icons: {
1368
+ readonly dot: Icon;
1369
+ readonly arrow: Icon;
1370
+ readonly chevron: Icon;
1284
1371
  };
1285
-
1286
1372
  /** Makes `name` usable in any chart's `on` slots, e.g. `on: { hover: "nudge" }`. A later registration replaces an earlier one. */
1287
- declare function registerPreset(name: string, factory: () => MarkEffect): void;
1373
+ export declare function registerPreset(name: string, factory: () => MarkEffect): void;
1288
1374
  /** Makes an icon usable by name, e.g. `travel("cleat")`. A later icon with the same name replaces an earlier one. */
1289
- declare function registerIcon(icon: Icon): void;
1290
- declare function registerIcons(icons: readonly Icon[]): void;
1291
-
1375
+ export declare function registerIcon(icon: Icon): void;
1376
+ export declare function registerIcons(icons: readonly Icon[]): void;
1292
1377
  /**
1293
1378
  * Sets how charts, adapters and controls get their stylesheet, page-wide. Call it before creating
1294
1379
  * any: the stylesheet is injected once, by the first one. Options left out keep their current value.
@@ -1297,54 +1382,51 @@ declare function registerIcons(icons: readonly Icon[]): void;
1297
1382
  * - `injectStyles: false`: inject nothing; the page loads `expressive-charts/style.css` itself, which
1298
1383
  * has the same rules. For a CSP that allows no inline styles at all.
1299
1384
  */
1300
- declare function configure(options: StyleOptions): void;
1301
-
1302
- declare const VERSION = "0.3.0";
1303
-
1385
+ export declare function configure(options: StyleOptions): void;
1386
+ export declare const VERSION = "0.5.0";
1304
1387
  /**
1305
1388
  * A bar chart in `target` (an element or a selector). The axis whose values aren't numbers is the
1306
1389
  * category; `stack` stacks numeric fields; `on` attaches effects by slot.
1307
1390
  */
1308
- declare function barChart<D>(target: string | Element, options: BarChartOptions<D>): BarChart<D>;
1391
+ export declare function barChart<D>(target: string | Element, options: BarChartOptions<D>): BarChart<D>;
1309
1392
  /**
1310
1393
  * A donut chart in `target` (an element or a selector). `category` names each slice and `value` sizes
1311
1394
  * it; slices go clockwise from 12 o'clock, in data order or largest first with `sort: "value"`; `on`
1312
1395
  * attaches effects by slot.
1313
1396
  */
1314
- declare function donutChart<D>(target: string | Element, options: DonutChartOptions<D>): DonutChart<D>;
1397
+ export declare function donutChart<D>(target: string | Element, options: DonutChartOptions<D>): DonutChart<D>;
1315
1398
  /**
1316
1399
  * A line chart in `target` (an element or a selector): one row per `x`, a number or a Date, a line
1317
1400
  * per field in `series`, with a point per row and series that shows where its x is hovered or
1318
1401
  * focused. `reveal(x)` shows the data up to x, as `playback()` drives it; `on` attaches effects by slot.
1319
1402
  */
1320
- declare function lineChart<D>(target: string | Element, options: LineChartOptions<D>): LineChart<D>;
1403
+ export declare function lineChart<D>(target: string | Element, options: LineChartOptions<D>): LineChart<D>;
1321
1404
  /**
1322
1405
  * Views of the same data in `target` (an element or a selector), one shown at a time: `show(view)`
1323
1406
  * turns each mark into the mark with its key in the other view with `transition`, morph() by default,
1324
1407
  * while the labels move and swap their text. Each view's function draws its chart in the container
1325
1408
  * it's given; pass it the `colors` it's given too, so a key keeps its colour from view to view.
1326
1409
  */
1327
- declare function chartSwitch<T extends ChartSwitchViews>(target: string | Element, options: ChartSwitchOptions<T>): ChartSwitch<T>;
1410
+ export declare function chartSwitch<T extends ChartSwitchViews>(target: string | Element, options: ChartSwitchOptions<T>): ChartSwitch<T>;
1328
1411
  /**
1329
1412
  * Adds effects to SVG marks drawn by other code: a selector, elements, or a D3 selection (whose data
1330
1413
  * types the callbacks). `key` is required; `on` attaches effects by slot, as on the charts. Call
1331
1414
  * `refresh()` after the host re-renders.
1332
1415
  */
1333
- declare function expressive<D = unknown>(target: MarkSource<D>, options: ExpressiveOptions<D>): Attachment<D>;
1416
+ export declare function expressive<D = unknown>(target: MarkSource<D>, options: ExpressiveOptions<D>): Attachment<D>;
1334
1417
  /**
1335
1418
  * Adds effects to a Vega or Vega-Lite chart rendered as SVG (vega-embed's default): the View's mark
1336
1419
  * named `mark` ("marks", Vega-Lite's data mark, by default), read from its scenegraph. Rects are bars,
1337
1420
  * arcs slices, symbols points and lines lines; `sample` gives data effects their values. It follows
1338
1421
  * the View's own renders, so there's no refresh() to call. `key` is required, as for expressive().
1339
1422
  */
1340
- declare function fromVegaView<D = Record<string, unknown>>(view: VegaViewLike, options: VegaOptions<D>): VegaAttachment<D>;
1423
+ export declare function fromVegaView<D = Record<string, unknown>>(view: VegaViewLike, options: VegaOptions<D>): VegaAttachment<D>;
1341
1424
  /**
1342
1425
  * The viewer's motion control in `target` (an element or a selector): Presentation, Analysis and Off
1343
1426
  * as buttons with `aria-pressed`, and a note on what the mode does. A click is the viewer's own
1344
1427
  * choice (`motion.chooseMode()`), so it overrides the device's reduced-motion setting. Default: the
1345
1428
  * page-wide `motion`. `persist: "key"` saves the choice in localStorage.
1346
1429
  */
1347
- declare function motionSwitch(target: string | Element, motion?: Motion, options?: MotionSwitchOptions): MotionSwitch;
1348
-
1349
- export { AnyMarkEffect, Color, Combined, DataEffect, Easing, EffectContext, GeometryEffect, Icon, MarkData, MarkEffect, MarkGeometry, Matrix, Motion, MotionEnv, MotionMode, Point, Rect, Sample, Timing, TransitionEffect, TweenResult, VERSION, animated, barChart, chartSwitch, colorAssignment, configure, defineDataEffect, defineEffect, defineIcon, delta, describe, donutChart, expressive, flash, fromVegaView, gaits, iconFromSvg, icons, interpolateNumber, interpolatePoint, interpolateRecord, label, lineChart, link, matrix, morph, motionSwitch, offset, only, parallel, playButton, playback, pulse, registerIcon, registerIcons, registerPreset, samplesAlong, sequence, stagger, threshold, trace, travel, wiggle };
1350
- export type { Accessor, AnimateOptions, Animated, AnimatedOptions, ArcSpec, Attachment, BarChart, BarChartOptions, BarSegmentSpec, BarSpec, Baseline, Chart, ChartChange, ChartLabel, ChartOptions, ChartSwitch, ChartSwitchOptions, ChartSwitchView, ChartSwitchViewFactory, ChartSwitchViewName, ChartSwitchViews, ColorAssignment, DataEffectSpec, DeltaOptions, DonutChart, DonutChartOptions, EffectOption, EffectSlot, EffectSlots, ExpressiveOptions, FlashOptions, Gait, GaitName, GaitPose, GaitState, GeometryEffectSpec, HostMark, IconSpec, Interpolator, KeyOfType, LabelOptions, LegendEntry, LegendOptions, LineChart, LineChartOptions, LineSpec, Link, LinkOptions, LinkSource, MarkEvent, MarkEvents, MarkSource, MarkSummary, MorphAlign, MorphOptions, MotionSwitch, MotionSwitchOptions, NumericKey, PlayButton, PlayButtonOptions, Playback, PlaybackEvent, PlaybackOptions, PointSpec, PresetName, PulseOptions, SamplePoint, SeekOptions, SliceSummary, StaggerOptions, StepOptions, StyleOptions, SvgIconSpec, TableColumn, TableOptions, ThresholdOptions, TraceOptions, TravelOptions, VegaAttachment, VegaItem, VegaMark, VegaOptions, VegaSample, VegaViewLike, WiggleOptions };
1430
+ export declare function motionSwitch(target: string | Element, motion?: Motion, options?: MotionSwitchOptions): MotionSwitch;
1431
+ export { type Accessor, type AnimateOptions, type Animated, type AnimatedOptions, type AnyMarkEffect, type ArcSpec, type Attachment, type BarChart, type BarChartOptions, type BarSegmentSpec, type BarSpec, type Baseline, type Chart, type ChartChange, type ChartLabel, type ChartOptions, type ChartSwitch, type ChartSwitchOptions, type ChartSwitchView, type ChartSwitchViewFactory, type ChartSwitchViewName, type ChartSwitchViews, type Clock, type Color, type ColorAssignment, type Combined, type DataEffect, type DataEffectSpec, type DeltaOptions, type DonutChart, type DonutChartOptions, type Easing, type EffectContext, type EffectOption, type EffectSlot, type EffectSlots, type ExpressiveOptions, type FlashOptions, type FrameSource, type Gait, type GaitName, type GaitPose, type GaitState, type GeometryEffect, type GeometryEffectSpec, type HostMark, type Icon, type IconHandle, type IconShape, type IconSource, type IconSpec, type Interpolator, type KeyOfType, type LabelOptions, type Layer, type LegendEntry, type LegendOptions, type LineChart, type LineChartOptions, type LineSpec, type Link, type LinkOptions, type LinkSource, type ManualClock, type MarkData, type MarkEffect, type MarkEvent, type MarkEvents, type MarkGeometry, type MarkHandle, type MarkSource, type MarkStyle, type MarkSummary, type Matrix, type MorphAlign, type MorphOptions, type Motion, type MotionEnv, type MotionMode, type MotionOptions, type MotionSwitch, type MotionSwitchOptions, type MotionView, type NumericKey, type Outline, type Paint, type PathHandle, type PlayButton, type PlayButtonOptions, type Playback, type PlaybackEvent, type PlaybackOptions, type Point, type PointSpec, type PresetName, type PulseOptions, type Rect, type ReducedMotionSource, type Sample, type SamplePoint, type ScalingOverrides, type ScalingRule, type ScalingTable, type SeekOptions, type ShapeSpec, type SliceSummary, type StaggerOptions, type StepOptions, type StyleOptions, type SvgIconSpec, type TableColumn, type TableOptions, type TextHandle, type TextStyle, type ThresholdOptions, type Timing, type TraceOptions, type TransitionContext, type TransitionEffect, type TravelOptions, type Tween, type TweenOptions, type TweenResult, type VegaAttachment, type VegaItem, type VegaMark, type VegaOptions, type VegaSample, type VegaViewLike, type WiggleOptions, createClock, createMotion, defaultClock, defaultScaling, easeInOutCubic, easeOutCubic, linear, manualClock, mediaReducedMotion, motion, scaleDuration, tween };
1432
+ //# sourceMappingURL=index.d.ts.map