expressive-charts 0.9.0 → 0.11.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.
@@ -0,0 +1,752 @@
1
+ /** Where frames come from. The default uses requestAnimationFrame, or a 16 ms timer outside the browser. */
2
+ interface FrameSource {
3
+ now(): number;
4
+ /** Ask for one callback on the next frame. Returns a function that cancels it. */
5
+ request(callback: (now: number) => void): () => void;
6
+ }
7
+ interface Clock {
8
+ now(): number;
9
+ /** Call `callback` on every frame until the returned function is called. */
10
+ onFrame(callback: (now: number) => void): () => void;
11
+ }
12
+ /** A clock that only moves when told to. For tests. */
13
+ interface ManualClock extends Clock {
14
+ /** Move time forward by `ms` and run one frame at the new time. */
15
+ advance(ms: number): void;
16
+ /** True when nothing is waiting for a frame. */
17
+ readonly idle: boolean;
18
+ }
19
+ /**
20
+ * One shared frame loop. It requests a frame only while something is
21
+ * subscribed, so an idle page costs nothing.
22
+ */
23
+ declare function createClock(source?: FrameSource): Clock;
24
+ declare function manualClock(start?: number): ManualClock;
25
+ /** The page-wide clock every tween uses unless given another. */
26
+ declare const defaultClock: Clock;
27
+ /** Maps linear progress (0–1) to eased progress. Any function of this shape works. */
28
+ type Easing = (t: number) => number;
29
+ /** For playback, where speed should stay constant. */
30
+ declare const linear: Easing;
31
+ /** For data transitions: starts and ends gently. */
32
+ declare const easeInOutCubic: Easing;
33
+ /** For travel, and for animations retargeted mid-flight: starts at speed, settles gently. */
34
+ declare const easeOutCubic: Easing;
35
+ type MotionMode = "presentation" | "analysis" | "off";
36
+ /** What a duration is for. Each kind scales differently by mode. */
37
+ type Timing = "feedback" | "transition" | "effect" | "playback" | "stagger";
38
+ /** Base ms × factor, clamped to [min(base, min), max]. A floor never makes an animation longer than its base. */
39
+ interface ScalingRule {
40
+ readonly factor: number;
41
+ readonly min?: number;
42
+ readonly max?: number;
43
+ }
44
+ type ScaledMode = Exclude<MotionMode, "off">;
45
+ type ScalingTable = { readonly [M in ScaledMode]: { readonly [T in Timing]: ScalingRule; }; };
46
+ type ScalingOverrides = { readonly [M in ScaledMode]?: { readonly [T in Timing]?: ScalingRule; }; };
47
+ /** Starting values from the prototype; tuned in the demos. Off is always 0. */
48
+ declare const defaultScaling: ScalingTable;
49
+ /** What charts and effects need from the motion system. */
50
+ interface MotionView {
51
+ /** The effective mode, after the reduced-motion rule. */
52
+ readonly mode: MotionMode;
53
+ /** True only in presentation: split data changes into stages. */
54
+ readonly staged: boolean;
55
+ /** Scale a base duration (ms) for the current mode. 0 means "jump to the end". */
56
+ duration(base: number, timing?: Timing): number;
57
+ }
58
+ interface Motion extends MotionView {
59
+ /** The mode the page author asked for. */
60
+ readonly requested: MotionMode;
61
+ /** The mode the viewer picked in an on-page control, if any. */
62
+ readonly viewerChoice: MotionMode | undefined;
63
+ /** Live value of `prefers-reduced-motion: reduce`. */
64
+ readonly prefersReduced: boolean;
65
+ /** The author's default. Never overrides reduced motion. */
66
+ setMode(mode: MotionMode): void;
67
+ /** The viewer's explicit choice from an on-page control. Overrides reduced motion. */
68
+ chooseMode(mode: MotionMode): void;
69
+ /** Forget the viewer's choice and follow the author's mode and the device setting again. */
70
+ clearChoice(): void;
71
+ /** Called whenever the mode, the viewer's choice or the device setting changes. */
72
+ subscribe(listener: () => void): () => void;
73
+ }
74
+ /** A live reduced-motion preference. */
75
+ interface ReducedMotionSource {
76
+ readonly matches: boolean;
77
+ subscribe(listener: () => void): () => void;
78
+ }
79
+ interface MotionOptions {
80
+ /** The author's mode. Default "presentation". */
81
+ readonly mode?: MotionMode;
82
+ readonly scaling?: ScalingOverrides;
83
+ /** Default: the `prefers-reduced-motion` media query. */
84
+ readonly reducedMotion?: ReducedMotionSource;
85
+ }
86
+ declare function createMotion(options?: MotionOptions): Motion;
87
+ declare function scaleDuration(base: number, rule: ScalingRule): number;
88
+ /** Reads `prefers-reduced-motion` lazily: nothing touches the DOM until `matches` is read or someone subscribes. */
89
+ declare function mediaReducedMotion(query?: string): ReducedMotionSource;
90
+ /** The page-wide motion every chart follows unless given its own. */
91
+ declare const motion: Motion;
92
+ /** The clock and motion settings an animation runs against. */
93
+ interface MotionEnv {
94
+ readonly clock: Clock;
95
+ readonly motion: MotionView;
96
+ }
97
+ interface TweenOptions {
98
+ /** Base duration in ms, scaled by the motion mode. */
99
+ readonly duration: number;
100
+ /** Default "transition". */
101
+ readonly timing?: Timing;
102
+ /** Default easeInOutCubic. */
103
+ readonly ease?: Easing;
104
+ /** Base delay in ms before progress starts, scaled like the duration. */
105
+ readonly delay?: number;
106
+ /** Called with eased progress: once with ease(0) at the start, then every frame, then with ease(1) at the end. */
107
+ readonly update: (progress: number) => void;
108
+ readonly signal?: AbortSignal;
109
+ }
110
+ type TweenResult = "done" | "cancelled";
111
+ interface Tween {
112
+ /** Resolves when the tween ends. Never rejects. */
113
+ readonly finished: Promise<TweenResult>;
114
+ readonly state: "running" | TweenResult;
115
+ /** Stop where it is. */
116
+ cancel(): void;
117
+ /** Jump to the end now. */
118
+ finish(): void;
119
+ }
120
+ /**
121
+ * Animate progress from 0 to 1. If the motion mode scales the duration to 0,
122
+ * `update(ease(1))` runs synchronously, before `tween` returns. If the mode
123
+ * turns off while the tween runs, it jumps to the end on the next frame.
124
+ */
125
+ declare function tween(options: TweenOptions, env?: Partial<MotionEnv>): Tween;
126
+ interface Point {
127
+ readonly x: number;
128
+ readonly y: number;
129
+ }
130
+ interface Rect {
131
+ readonly x: number;
132
+ readonly y: number;
133
+ readonly width: number;
134
+ readonly height: number;
135
+ }
136
+ interface Outline {
137
+ /** SVG path data in the mark's coordinate space. */
138
+ readonly d: string;
139
+ /** True for areas (bars, slices, markers), false for strokes (lines). */
140
+ readonly closed: boolean;
141
+ /**
142
+ * Closed outlines: n points (n a multiple of 4), walking clockwise on screen from the start-left
143
+ * corner, n/4 per side in the order left, end, right, start, evenly spaced along each side. The
144
+ * corners are at indices 0, n/4, n/2 and 3n/4. Open outlines: n points along the stroke, from
145
+ * start to end inclusive. Morph depends on this.
146
+ */
147
+ sample(n: number): readonly Point[];
148
+ }
149
+ interface MarkGeometry {
150
+ /** Stable identity across updates. Segments are keyed "<mark key>/<series>". */
151
+ readonly key: string;
152
+ /** The series this mark or segment belongs to, if any ("goals", "xg"). */
153
+ readonly series?: string;
154
+ /** Equals path(0). */
155
+ readonly start: Point;
156
+ /** Equals path(1). */
157
+ readonly end: Point;
158
+ /** Length of the walk in px; 0 for marks with no direction (a scatter dot). */
159
+ readonly length: number;
160
+ /** t in [0, 1], proportional to distance along the walk. Values outside are clamped. */
161
+ path(t: number): Point;
162
+ /** Direction of travel in radians, in (-PI, PI]; the mark's "up" side is angle - PI/2. */
163
+ angle(t: number): number;
164
+ /** SVG path data for the part of the walk between t0 and t1, in either order. It leaves out the gaps. */
165
+ slice(t0: number, t1: number): string;
166
+ /**
167
+ * The stretches of the walk with no data, as [from, to] values of t, in order and apart: each with
168
+ * 0 ≤ from < to ≤ 1, ending at or before the next starts. A line that skips a value has one, from
169
+ * the value before to the value after. The walk runs straight across a gap, so `path` and `angle`
170
+ * work as on any walk, and `outline.sample(n)` runs along it all; `slice()` and an open outline's
171
+ * `d` leave the gaps out, with a moveto across each. Unset means none.
172
+ */
173
+ readonly gaps?: readonly (readonly [from: number, to: number])[];
174
+ /** Px across the walk: bar height, ring width, stroke width, marker diameter. */
175
+ readonly thickness: number;
176
+ readonly outline: Outline;
177
+ readonly bounds: Rect;
178
+ /** Visual centre: tooltips, focus rings, labels. */
179
+ readonly center: Point;
180
+ /** Where the mark is attached to the chart: a bar's baseline, a donut's centre. */
181
+ readonly pivot: Point;
182
+ /**
183
+ * The boxes of the text the chart draws for this mark, so an effect's text can keep clear of
184
+ * them: a bar's category and value labels, a slice's label outside the ring, a line's end label.
185
+ * Unset when nothing says where they are (segments, points, and marks the library didn't draw).
186
+ */
187
+ readonly labelBounds?: readonly Rect[];
188
+ /**
189
+ * The boxes of other marks' text near this one, which an effect's text should keep clear of too:
190
+ * a line's are the other lines' end labels, a slice's its neighbours' labels either side. Unset
191
+ * when none is known (bars, segments, points, and marks the library didn't draw).
192
+ */
193
+ readonly nearbyLabels?: readonly Rect[];
194
+ /** Ordered parts, from the baseline (goals, then assists). Every bar has at least one. */
195
+ readonly segments?: readonly MarkGeometry[];
196
+ }
197
+ /** Builds a function that blends `from` into `to` as t goes from 0 to 1. */
198
+ type Interpolator<T> = (from: T, to: T) => (t: number) => T;
199
+ /** Exact at both ends, so a finished animation lands on its target. */
200
+ declare const interpolateNumber: Interpolator<number>;
201
+ declare const interpolatePoint: Interpolator<Point>;
202
+ /**
203
+ * Blends every key. A key missing on one side counts as 0 there, so a series
204
+ * that appears grows from 0, and one that disappears shrinks to 0 and is gone at t = 1.
205
+ */
206
+ declare function interpolateRecord<K extends string>(a: Readonly<Record<K, number>>, b: Readonly<Record<K, number>>): (t: number) => Record<K, number>;
207
+ interface AnimateOptions {
208
+ /** Base duration in ms, scaled by the motion mode. */
209
+ readonly duration: number;
210
+ /** Default "transition". */
211
+ readonly timing?: Timing;
212
+ /** Default easeInOutCubic, or easeOutCubic when this interrupts a moving value and starts at once (no delay). */
213
+ readonly ease?: Easing;
214
+ readonly delay?: number;
215
+ readonly signal?: AbortSignal;
216
+ }
217
+ interface AnimatedOptions<T> extends Partial<MotionEnv> {
218
+ /** Called whenever the value changes, including every animation frame. */
219
+ readonly onChange?: (value: T) => void;
220
+ }
221
+ /** A value that can be retargeted mid-flight. */
222
+ interface Animated<T> {
223
+ /** The current value, in between while animating. */
224
+ readonly value: T;
225
+ /** Where the value is heading (equal to `value` when at rest). */
226
+ readonly target: T;
227
+ readonly animating: boolean;
228
+ /** Animate from the current value, cancelling any animation already running. */
229
+ to(target: T, options: AnimateOptions): Promise<TweenResult>;
230
+ /** Jump to a value, cancelling any running animation. */
231
+ set(value: T): void;
232
+ /** Stop where it is; the current value becomes the target. */
233
+ stop(): void;
234
+ }
235
+ declare function animated<T>(initial: T, interpolate: Interpolator<T>, options?: AnimatedOptions<T>): Animated<T>;
236
+ interface PlaybackOptions extends Partial<MotionEnv> {
237
+ /** Where a play starts again once it's at the end. */
238
+ readonly from: number;
239
+ /** Where a play ends. The playback starts here, at rest, as a chart shows all its data until something reveals less. */
240
+ readonly to: number;
241
+ /** 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. */
242
+ readonly duration: number;
243
+ /** How a play moves. Default linear: constant speed. Seeks ease on their own. */
244
+ readonly ease?: Easing;
245
+ /** Default "playback": ×1 in Presentation, ×0.3 in Analysis, a jump in Off. */
246
+ readonly timing?: Timing;
247
+ /** Draws a position. Called whenever the position changes: every frame of a play or a seek, and every jump. */
248
+ readonly onFrame: (position: number) => void;
249
+ }
250
+ /** What `subscribe` hears. Frames go to `onFrame` instead. */
251
+ type PlaybackEvent = "play" | "pause" | "end" | "seek";
252
+ interface SeekOptions {
253
+ /** Default true: move over 350 ms base transition timing (at most 200 ms in Analysis, a jump in Off). false jumps. */
254
+ readonly animate?: boolean;
255
+ }
256
+ interface Playback {
257
+ /** Plays on from where it is to `to`, or from `from` when it's at the end. Does nothing while playing. */
258
+ play(): void;
259
+ /** Stops a play where it is. Does nothing unless it's playing, so a seek on its way still lands. */
260
+ pause(): void;
261
+ /** Pauses, and moves to `x`, clamped to the range. A seek while it's moving starts from where it is. */
262
+ seek(x: number, options?: SeekOptions): void;
263
+ /** Where it is now, in between while it moves. */
264
+ readonly position: number;
265
+ /** True from `play()` until a pause, a seek or the end. */
266
+ readonly playing: boolean;
267
+ /** Hears play, pause, the end and seeks, not every frame. Returns a function that stops listening. */
268
+ subscribe(listener: (event: PlaybackEvent) => void): () => void;
269
+ /** Pauses it, if it's playing, and stops it for good: later calls do nothing. */
270
+ destroy(): void;
271
+ }
272
+ /**
273
+ * A playback through `from`…`to`. `play()` moves the position at constant speed (with the default
274
+ * `linear`), over `duration` scaled by the motion mode, and `onFrame` draws each position. With motion
275
+ * off, a play jumps to the end, and motion turning off mid-play jumps there too, as tweens do. Nothing
276
+ * plays by itself. Uses the page-wide motion and clock unless given its own.
277
+ */
278
+ declare function playback(options: PlaybackOptions): Playback;
279
+ interface Sample {
280
+ /** Where along the walk, in [0, 1]. */
281
+ readonly t: number;
282
+ readonly value: number;
283
+ /** The x value or label behind the sample (a week, a date). */
284
+ readonly at?: string | number | Date;
285
+ /** True on the first sample after a gap in the data, so a data effect doesn't join it to the one before. */
286
+ readonly gapBefore?: boolean;
287
+ }
288
+ interface MarkData<D = unknown> {
289
+ /**
290
+ * The row behind the mark: a bar's or a slice's row, a line point's row. A line's is the row at its
291
+ * revealed end; its other rows' values are in `samples`.
292
+ */
293
+ readonly datum: D;
294
+ /** Data values along the walk, t ascending. */
295
+ readonly samples: readonly Sample[];
296
+ /** Another series in the same chart, if it exists. */
297
+ related(series: string): MarkData<D> | undefined;
298
+ /** The values before this update, for update effects that show change. */
299
+ readonly previous?: MarkData<D>;
300
+ }
301
+ /** One path of an icon, drawn in order (the first is at the bottom). */
302
+ interface IconShape {
303
+ /** Path data in icon units. */
304
+ readonly d: string;
305
+ /** Unset draws no fill (unlike SVG, where it's black). */
306
+ readonly fill?: Color;
307
+ /** Unset draws no stroke. */
308
+ readonly stroke?: Color;
309
+ /** Stroke width in icon units, so it scales with the icon. Default 1. */
310
+ readonly width?: number;
311
+ /** Default "butt". */
312
+ readonly linecap?: "butt" | "round";
313
+ /** Default "miter". */
314
+ readonly linejoin?: "miter" | "round";
315
+ /** Path data, in icon units, that clips this shape (the ball's panel pattern). */
316
+ readonly clip?: string;
317
+ /** Default "nonzero". "evenodd" leaves a hole where the path's parts overlap, as solid icon sets draw them. */
318
+ readonly fillRule?: "nonzero" | "evenodd";
319
+ /** From 0 to 1, for the whole shape, fill and stroke together (a duotone set's lighter part). Default 1. */
320
+ readonly opacity?: number;
321
+ /** From 0 to 1, the fill's own, inside `opacity` (a set that fades only a part's fill). Default 1. */
322
+ readonly fillOpacity?: number;
323
+ /** From 0 to 1, the stroke's own, inside `opacity`. Default 1. */
324
+ readonly strokeOpacity?: number;
325
+ }
326
+ /**
327
+ * Build one with defineIcon() or iconFromSvg(), which fill the defaults and check it. Icon units
328
+ * are px at the icon's natural size: `layer.icon(icon, { size })` scales it by size / icon.size
329
+ * about its anchor before `place()`.
330
+ */
331
+ interface Icon {
332
+ readonly name: string;
333
+ /** Drawn facing +x, with its up side towards −y, in icon units. */
334
+ readonly shapes: readonly IconShape[];
335
+ /** Icon-space bounds. */
336
+ readonly box: Rect;
337
+ /** The natural length along the walk, in px (and icon units). */
338
+ readonly size: number;
339
+ /** The icon-space point that sits on the walk. */
340
+ readonly anchor: Point;
341
+ /** What it spins or tilts around. */
342
+ readonly pivot: Point;
343
+ /** Extent along +x from the anchor, which travel keeps inside the mark. */
344
+ readonly footprint: readonly [behind: number, ahead: number];
345
+ /** The gait travel uses unless it's given one. */
346
+ readonly gait?: "roll" | "step" | "slide";
347
+ /** Rolling radius; default box height / 2. */
348
+ readonly radius?: number;
349
+ /** Mirror instead of turning upside down (a boot keeps its sole down). */
350
+ readonly upright?: boolean;
351
+ }
352
+ /** Resolves icon names; the composition root fills it from the icon registry. */
353
+ interface IconSource {
354
+ get(name: string): Icon | undefined;
355
+ }
356
+ /**
357
+ * A theme token or any CSS colour. Tokens: "text", "text-muted", "surface", "grid", "axis", "focus",
358
+ * "negative", "series-N" and "series-N-strong" (palette slots 1–8), and "mark" / "mark-strong", the
359
+ * colours of the mark a run belongs to (its first segment's, for a stack, or in a paint with `part`,
360
+ * that segment's).
361
+ */
362
+ type Color = string;
363
+ /**
364
+ * A 2D affine transform in SVG order: x' = a·x + c·y + e, y' = b·x + d·y + f.
365
+ * Build one with the `matrix` helpers.
366
+ */
367
+ type Matrix = readonly [a: number, b: number, c: number, d: number, e: number, f: number];
368
+ interface Paint {
369
+ readonly fill?: Color;
370
+ readonly stroke?: Color;
371
+ readonly width?: number;
372
+ readonly opacity?: number;
373
+ readonly linecap?: "butt" | "round";
374
+ /**
375
+ * The key of one of the mark's segments (`segment.key`). In this paint, "mark" and "mark-strong"
376
+ * are that segment's colours. Unset, or a key the mark hasn't, they're the mark's own, as without it.
377
+ */
378
+ readonly part?: string;
379
+ }
380
+ interface MarkStyle {
381
+ /** In chart space. Moves the mark's body; its labels and pointer target stay put. */
382
+ readonly transform?: Matrix;
383
+ readonly opacity?: number;
384
+ /** 0–1 toward the series' strong colour. */
385
+ readonly emphasis?: number;
386
+ /**
387
+ * A stroke along the outline, behind the mark. `width` is the stroke width, so half of it shows
388
+ * outside the mark (the prototype's flash peaks at 8). Default colour: the mark's own.
389
+ */
390
+ readonly halo?: {
391
+ readonly width: number;
392
+ readonly opacity: number;
393
+ readonly color?: Color;
394
+ };
395
+ }
396
+ /** Restyles the mark itself. The runner resets it when the run is cleared. */
397
+ interface MarkHandle {
398
+ /** Changes only the fields given, so parallel effects don't undo each other. A field given as undefined goes back to its default. */
399
+ set(style: MarkStyle): void;
400
+ /** Back to the mark's own style. */
401
+ reset(): void;
402
+ }
403
+ interface IconHandle {
404
+ /** Moves the icon: a transform from icon space into chart space. The icon is hidden until first placed. */
405
+ place(transform: Matrix): void;
406
+ remove(): void;
407
+ }
408
+ interface PathHandle {
409
+ /** Replaces the path data; paint fields given are merged into the current paint. */
410
+ update(d: string, paint?: Partial<Paint>): void;
411
+ remove(): void;
412
+ }
413
+ /** Effects that label a change ("+2") need text, drawn in theme text colours by default. */
414
+ interface TextStyle {
415
+ /** The anchor point, on the text's baseline. */
416
+ readonly at: Point;
417
+ readonly anchor?: "start" | "middle" | "end";
418
+ /** Default "text". Series colours are allowed only for swatches, never for words. */
419
+ readonly color?: Color;
420
+ readonly opacity?: number;
421
+ }
422
+ interface TextHandle {
423
+ /** Style fields given are merged into the current style; content is replaced if given. */
424
+ update(style: Partial<TextStyle>, content?: string): void;
425
+ remove(): void;
426
+ }
427
+ /** One run's own overlay group, above the marks, in chart coordinates. The runner empties it when the run is cleared. */
428
+ interface Layer {
429
+ /**
430
+ * Draws an icon, hidden until its first `place()`.
431
+ *
432
+ * Size rule: with `size`, the icon is scaled by `size / icon.size` about its anchor, in icon space,
433
+ * before the `place()` transform. So effects build the transform as if the icon were its natural
434
+ * size, and the anchor still lands where the transform puts it. Icon-space lengths (footprint,
435
+ * radius, the pivot's offset from the anchor) scale by the same factor. A negative size throws.
436
+ *
437
+ * Each shape is one path, in order (the first at the bottom). An unset `fill` or `stroke` draws
438
+ * none; `width` is in icon units (default 1), so it scales with the icon. `clip` is path data in
439
+ * icon space.
440
+ */
441
+ icon(icon: Icon, options?: {
442
+ readonly size?: number;
443
+ }): IconHandle;
444
+ /** Draws an overlay path, unfilled unless `paint.fill` is given. */
445
+ path(d: string, paint: Paint): PathHandle;
446
+ text(content: string, style: TextStyle): TextHandle;
447
+ }
448
+ /**
449
+ * Where effects' text sits on one chart or attachment: one space for every run on its runner, so an
450
+ * effect's text can keep clear of other effects' text. Runs start in the chart's mark order, so text
451
+ * goes past the text of the runs before it, and never moves for the runs after it.
452
+ */
453
+ interface TextSpace {
454
+ /**
455
+ * The box `content` takes drawn with `style`, at the overlay's text size, measured as the chart
456
+ * measures its own text (estimated where there's no layout). Its digits are measured as 0s.
457
+ */
458
+ box(content: string, style: TextStyle): Rect;
459
+ /** The boxes the runs on this runner that started before this one hold now. */
460
+ held(): readonly Rect[];
461
+ /**
462
+ * This run's text is at `box` from now on, until it holds another, holds undefined, or the run is
463
+ * cleared. When it moves, the runs after it that are placed against it hear `onChange` again.
464
+ */
465
+ hold(box: Rect | undefined): void;
466
+ }
467
+ interface EffectContext {
468
+ /** Aborted on leave, re-trigger, data update or destroy. */
469
+ readonly signal: AbortSignal;
470
+ readonly motion: MotionView;
471
+ /** A tween with the clock, motion and signal already bound. */
472
+ tween(options: TweenOptions): Tween;
473
+ /** Restyles the mark itself; reset by the runner on clear. */
474
+ readonly mark: MarkHandle;
475
+ /** This run's own overlay group, above the marks; emptied on clear. */
476
+ readonly layer: Layer;
477
+ readonly icons: IconSource;
478
+ /** Position in a multi-mark event, for stagger. */
479
+ readonly batch: {
480
+ readonly index: number;
481
+ readonly count: number;
482
+ };
483
+ /**
484
+ * Called when the geometry moves (transitions, resizes, line reveals), and when text held before
485
+ * this run's moved after it was placed (`texts`); unsubscribed on clear.
486
+ */
487
+ onChange(listener: (mark: MarkGeometry, data?: MarkData) => void): void;
488
+ /** The mark's geometry before this update, on update events. */
489
+ readonly previous?: MarkGeometry;
490
+ /** Where effects' text sits on this chart or attachment. Unset means no other text is known. */
491
+ readonly texts?: TextSpace;
492
+ }
493
+ interface GeometryEffect {
494
+ readonly kind: "geometry";
495
+ /** Resolves when done or cancelled. */
496
+ run(mark: MarkGeometry, ctx: EffectContext): Promise<void>;
497
+ /** Draws the final state immediately, on a fresh context. Used when the effective mode is off. */
498
+ end(mark: MarkGeometry, ctx: EffectContext): void;
499
+ /** Extra cleanup beyond what the runner does. */
500
+ clear(ctx: EffectContext): void;
501
+ }
502
+ /**
503
+ * `run` and `end` are function-typed properties, not methods, on purpose: TypeScript checks method
504
+ * parameters loosely in both directions, which would let an effect that needs more fields than a
505
+ * chart's rows have (DataEffect<Row & { target: number }> on a chart of Row) slip through.
506
+ */
507
+ interface DataEffect<D = unknown> {
508
+ readonly kind: "data";
509
+ /** Checked when the chart is created, so a missing series throws instead of drawing nothing. */
510
+ readonly needs?: {
511
+ readonly related?: readonly string[];
512
+ };
513
+ readonly run: (mark: MarkGeometry, data: MarkData<D>, ctx: EffectContext) => Promise<void>;
514
+ readonly end: (mark: MarkGeometry, data: MarkData<D>, ctx: EffectContext) => void;
515
+ readonly clear: (ctx: EffectContext) => void;
516
+ }
517
+ /**
518
+ * A transition run's context. While a transition plays, both views' marks are hidden, so `mark` does
519
+ * nothing and `onChange` never fires: a resize lands the transition instead.
520
+ */
521
+ interface TransitionContext extends EffectContext {
522
+ /**
523
+ * Where the run begins, from 0 to 1, in the effect's own progress (morph's is the shapes' eased
524
+ * progress). 0 plays it all. A switch back mid-way plays the reverse pair from 1 minus the progress
525
+ * the first had reached, so an effect that honours it retraces; one that ignores it replays from its
526
+ * beginning.
527
+ */
528
+ readonly start: number;
529
+ }
530
+ /** Morph and future chart-to-chart transitions: from one geometry to another. */
531
+ interface TransitionEffect {
532
+ readonly kind: "transition";
533
+ /** Resolves when done or cancelled, leaving `to`'s end state drawn until cleared. */
534
+ run(from: MarkGeometry, to: MarkGeometry, ctx: TransitionContext): Promise<void>;
535
+ /** Draws the final state immediately, on a fresh context. Used when the effective mode is off. */
536
+ end(from: MarkGeometry, to: MarkGeometry, ctx: TransitionContext): void;
537
+ /** Extra cleanup beyond what the player does. */
538
+ clear(ctx: TransitionContext): void;
539
+ }
540
+ /** What combinators accept: any mark effect, whatever rows it reads. */
541
+ type AnyMarkEffect = GeometryEffect | DataEffect<any>;
542
+ type MarkEffect<D = unknown> = GeometryEffect | DataEffect<D>;
543
+ /** The row type a single effect needs; geometry effects need nothing (unknown). */
544
+ type RowNeeds<E> = E extends DataEffect<infer D> ? D : unknown;
545
+ /**
546
+ * The rows a combination needs: every part's needs at once (an intersection, not a union, so a
547
+ * generic part such as threshold() can't widen a typed part's needs back to unknown).
548
+ */
549
+ type AllRowNeeds<E extends readonly unknown[]> = E extends readonly [] ? unknown : E extends readonly [infer First, ...infer Rest] ? RowNeeds<First> & AllRowNeeds<Rest> : E extends readonly (infer Item)[] ? RowNeeds<Item> : unknown;
550
+ /** What `sequence` and `parallel` return: a data effect if any part is one. */
551
+ type Combined<E extends readonly AnyMarkEffect[]> = [Extract<E[number], {
552
+ kind: "data";
553
+ }>] extends [never] ? GeometryEffect : DataEffect<AllRowNeeds<E>>;
554
+ /** The events effects attach to. */
555
+ type EffectSlot = "hover" | "enter" | "update" | "exit" | "decorate";
556
+ /**
557
+ * A registered preset's name. The built-in names autocomplete; custom names (registerPreset) are
558
+ * allowed too, so a misspelled name isn't a type error: the chart throws when it's created.
559
+ */
560
+ type PresetName = "wiggle" | "pulse" | "flash" | (string & {});
561
+ type EffectOption<D> = MarkEffect<D> | PresetName;
562
+ /**
563
+ * The `on` option of charts and adapters. Use it as `EffectSlots<NoInfer<D>>`, so a generic data
564
+ * effect such as threshold() can't widen the chart's row type to unknown.
565
+ */
566
+ interface EffectSlots<D> {
567
+ /** On pointer hover or keyboard focus; cleared on leave, replayed after a data transition. */
568
+ readonly hover?: EffectOption<D>;
569
+ /** When a mark appears. */
570
+ readonly enter?: EffectOption<D>;
571
+ /** When a mark's values change (not on a re-sort alone). */
572
+ readonly update?: EffectOption<D>;
573
+ /** Before a mark is removed; removal waits for it. */
574
+ readonly exit?: EffectOption<D>;
575
+ /** From enter until exit, following every geometry change. */
576
+ readonly decorate?: EffectOption<D>;
577
+ }
578
+ interface ArcSpec {
579
+ readonly key: string;
580
+ readonly series?: string;
581
+ /** The donut's centre. */
582
+ readonly cx: number;
583
+ readonly cy: number;
584
+ /** Radii in px; 0 inner makes a pie slice. They're swapped if inner > outer, as d3.arc() does. */
585
+ readonly inner: number;
586
+ readonly outer: number;
587
+ /** Radians, 0 at 12 o'clock, clockwise: the d3.pie() convention. end < start walks anticlockwise. */
588
+ readonly start: number;
589
+ readonly end: number;
590
+ /** The boxes of the text drawn for the mark, in the same px: passed through as `labelBounds`. */
591
+ readonly labelBounds?: readonly Rect[];
592
+ /** The boxes of other marks' text near it, in the same px: passed through as `nearbyLabels`. */
593
+ readonly nearbyLabels?: readonly Rect[];
594
+ }
595
+ /**
596
+ * The walk runs along the mid-radius arc from the start angle to the end angle, so for a slice
597
+ * walked clockwise "up" is outward. The angle of travel equals the d3 angle (normalised).
598
+ */
599
+ declare function describeArc(spec: ArcSpec): MarkGeometry;
600
+ /** The edge a bar grows from. */
601
+ type Baseline = "left" | "right" | "top" | "bottom";
602
+ interface BarSegmentSpec {
603
+ readonly series: string;
604
+ /** Px along the walk, gap included. */
605
+ readonly size: number;
606
+ }
607
+ interface BarSpec {
608
+ readonly key: string;
609
+ readonly series?: string;
610
+ /** The whole bar's rectangle, in chart px. */
611
+ readonly x: number;
612
+ readonly y: number;
613
+ readonly width: number;
614
+ readonly height: number;
615
+ readonly baseline: Baseline;
616
+ /** Corner radius at the tip. The baseline end stays square. Default 0. */
617
+ readonly radius?: number;
618
+ /**
619
+ * Ordered parts, from the baseline. Default: one segment named after `series`, covering the bar.
620
+ * Sizes normally add up to the bar's length; anything past the tip is cut off.
621
+ */
622
+ readonly segments?: readonly BarSegmentSpec[];
623
+ /**
624
+ * Px left empty between segments (the prototype uses 2). It comes out of the start of the later
625
+ * segment, so every segment still ends at its value, and it shrinks to fit when what comes
626
+ * before is shorter. Default 0.
627
+ */
628
+ readonly gap?: number;
629
+ /** The boxes of the text drawn for the bar, its segments having none, in the same px: passed through as `labelBounds`. */
630
+ readonly labelBounds?: readonly Rect[];
631
+ /** The boxes of other marks' text near the bar, its segments having none, in the same px: passed through as `nearbyLabels`. */
632
+ readonly nearbyLabels?: readonly Rect[];
633
+ }
634
+ /**
635
+ * The walk runs along the centre line from the middle of the baseline edge to the middle of the
636
+ * tip. A plain bar has one segment, so `travel(…, { along: "goals" })` works stacked or not.
637
+ */
638
+ declare function describeBar(spec: BarSpec): MarkGeometry;
639
+ interface LineSpec {
640
+ readonly key: string;
641
+ readonly series?: string;
642
+ /** At least one point, in chart px. */
643
+ readonly points: readonly Point[];
644
+ /**
645
+ * The indices of the points that start a new run, so there's a gap from `points[i - 1]` to
646
+ * `points[i]`: each a whole number from 1 to the last index, in order, with no repeats. A line
647
+ * drawn with d3's `.defined()` is described by its defined points and where they break. Default none.
648
+ */
649
+ readonly breaks?: readonly number[];
650
+ /** Stroke width in px. Default 1, SVG's default. */
651
+ readonly width?: number;
652
+ /** The boxes of the text drawn for the mark, in the same px: passed through as `labelBounds`. */
653
+ readonly labelBounds?: readonly Rect[];
654
+ /** The boxes of other marks' text near it, in the same px: passed through as `nearbyLabels`. */
655
+ readonly nearbyLabels?: readonly Rect[];
656
+ }
657
+ /**
658
+ * The walk is the line itself, first point to last, running straight across each break. Its outline
659
+ * is open: the stroke, with the breaks left out. A break between two points in the same place leaves
660
+ * no gap, since there's nothing between them to leave out.
661
+ */
662
+ declare function describeLine(spec: LineSpec): MarkGeometry;
663
+ interface PointSpec {
664
+ readonly key: string;
665
+ readonly series?: string;
666
+ readonly x: number;
667
+ readonly y: number;
668
+ /** Radius in px. */
669
+ readonly r: number;
670
+ /** The boxes of the text drawn for the mark, in the same px: passed through as `labelBounds`. */
671
+ readonly labelBounds?: readonly Rect[];
672
+ /** The boxes of other marks' text near it, in the same px: passed through as `nearbyLabels`. */
673
+ readonly nearbyLabels?: readonly Rect[];
674
+ }
675
+ /**
676
+ * Length 0, with start = end = centre, so travel does nothing while wiggle, pulse and flash still
677
+ * work. Faces +x: the outline's sides are the quarter circles top, right, bottom and left.
678
+ */
679
+ declare function describePoint(spec: PointSpec): MarkGeometry;
680
+ interface ShapeSpec {
681
+ readonly key: string;
682
+ readonly series?: string;
683
+ /**
684
+ * SVG path data in the shape's own px, read as SVG reads it, up to its first error. A shape is
685
+ * closed when every subpath ends with Z, or where it started, and otherwise open, a line.
686
+ */
687
+ readonly d: string;
688
+ /** Moves the shape into the marks' px, as an element's transform does, arcs too. Default none. */
689
+ readonly matrix?: Matrix;
690
+ /** An open shape's stroke width in px, more than 0. Default 1, SVG's default. */
691
+ readonly width?: number;
692
+ /** The boxes of the text drawn for the mark, in the marks' px: passed through as `labelBounds`. */
693
+ readonly labelBounds?: readonly Rect[];
694
+ /** The boxes of other marks' text near it, in the marks' px: passed through as `nearbyLabels`. */
695
+ readonly nearbyLabels?: readonly Rect[];
696
+ }
697
+ /**
698
+ * Path data, flattened: straight pieces and circular arcs stay as they are, and Béziers and other
699
+ * arcs become straight pieces within 0.1 px of the curve.
700
+ * - An open shape is a line. Its walk runs along the path from its first point, and each later move
701
+ * starts a new run after a gap. Its outline is the stroke, less the gaps, and its thickness,
702
+ * bounds, centre and pivot are as `describe.line`'s.
703
+ * - A closed shape has no direction: its walk is its bounds' centre, with length 0. Its outline's
704
+ * `d` is the whole path, holes too, and `sample(n)` goes round its longest subpath, clockwise in
705
+ * four quarters of equal length from its upper left. Its thickness is the smaller of its width and
706
+ * height.
707
+ * A subpath that ends where it started is closed too, as d3.arc() draws a full ring's outer edge.
708
+ * A path whose subpaths are all closed but have no length, as d3 draws a value alone, is open: a line
709
+ * with nothing to stroke.
710
+ */
711
+ declare function describeShape(spec: ShapeSpec): MarkGeometry;
712
+ declare const describe: {
713
+ bar: typeof describeBar;
714
+ arc: typeof describeArc;
715
+ line: typeof describeLine;
716
+ point: typeof describePoint;
717
+ shape: typeof describeShape;
718
+ };
719
+ declare function translate(x: number, y: number): Matrix;
720
+ /** Positive radians turn clockwise on screen, like SVG's rotate(). */
721
+ declare function rotate(radians: number, about?: Point): Matrix;
722
+ declare function scale(sx: number, sy?: number, about?: Point): Matrix;
723
+ /** Composes like an SVG transform list: multiply(a, b) applies b first, then a. No arguments gives the identity. */
724
+ declare function multiply(...matrices: Matrix[]): Matrix;
725
+ /** Where the transform takes a point. */
726
+ declare function apply(m: Matrix, point: Point): Point;
727
+ /** Builds and applies 2D transforms in SVG order, for `mark.set({ transform })` and `IconHandle.place()`. */
728
+ declare const matrix: {
729
+ translate: typeof translate;
730
+ rotate: typeof rotate;
731
+ scale: typeof scale;
732
+ multiply: typeof multiply;
733
+ apply: typeof apply;
734
+ };
735
+ /** A point `distance` px from `point` in direction `angle` (screen radians). */
736
+ declare function offset(point: Point, angle: number, distance: number): Point;
737
+ /** A data point in the mark's coordinates, with its value and, optionally, the x value behind it. */
738
+ interface SamplePoint {
739
+ readonly x: number;
740
+ readonly y: number;
741
+ readonly value: number;
742
+ readonly at?: string | number | Date;
743
+ }
744
+ /**
745
+ * Projects each point onto the nearest point of the mark's walk and returns the samples in `t` order
746
+ * (points at the same `t` keep their order). A point on the walk, such as a vertex of the polyline it
747
+ * drew, lands exactly where it is. Where the mark has gaps, the first sample past each gap's middle
748
+ * has `gapBefore`, so a data effect doesn't join it to the one before. Throws a RangeError on a point
749
+ * whose x, y or value isn't finite.
750
+ */
751
+ declare function samplesAlong(mark: MarkGeometry, points: readonly SamplePoint[]): Sample[];
752
+ export { interpolateRecord as $, MarkStyle as A, createClock as At, Sample as B, TextSpace as C, Easing as Ct, IconHandle as D, Clock as Dt, Color as E, linear as Et, TextStyle as F, playback as G, PlaybackEvent as H, Icon as I, AnimatedOptions as J, AnimateOptions as K, IconShape as L, Paint as M, manualClock as Mt, PathHandle as N, Layer as O, FrameSource as Ot, TextHandle as P, interpolatePoint as Q, IconSource as R, MarkEffect as S, scaleDuration as St, TransitionEffect as T, easeOutCubic as Tt, PlaybackOptions as U, Playback as V, SeekOptions as W, animated as X, Interpolator as Y, interpolateNumber as Z, AnyMarkEffect as _, Timing as _t, describe as a, Tween as at, EffectContext as b, mediaReducedMotion as bt, LineSpec as c, tween as ct, Baseline as d, MotionOptions as dt, MarkGeometry as et, ArcSpec as f, MotionView as ft, PresetName as g, ScalingTable as gt, EffectSlots as h, ScalingRule as ht, offset as i, MotionEnv as it, Matrix as j, defaultClock as jt, MarkHandle as k, ManualClock as kt, BarSegmentSpec as l, Motion as lt, EffectSlot as m, ScalingOverrides as mt, samplesAlong as n, Point as nt, ShapeSpec as o, TweenOptions as ot, EffectOption as p, ReducedMotionSource as pt, Animated as q, matrix as r, Rect as rt, PointSpec as s, TweenResult as st, SamplePoint as t, Outline as tt, BarSpec as u, MotionMode as ut, Combined as v, createMotion as vt, TransitionContext as w, easeInOutCubic as wt, GeometryEffect as x, motion as xt, DataEffect as y, defaultScaling as yt, MarkData as z };