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