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