expressive-charts 0.8.0 → 0.10.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.
package/dist/index.d.cts CHANGED
@@ -1,285 +1,5 @@
1
- import { A as scaleDuration, B as manualClock, C as ScalingRule, D as defaultScaling, E as createMotion, F as Clock, I as FrameSource, L as ManualClock, M as easeInOutCubic, N as easeOutCubic, O as mediaReducedMotion, P as linear, R as createClock, S as ScalingOverrides, T as Timing, _ as Motion, a as GeometryEffect, b as MotionView, c as TransitionContext, d as Sample, f as MotionEnv, g as tween, h as TweenResult, i as EffectContext, j as Easing, k as motion, l as TransitionEffect, m as TweenOptions, n as Combined, o as MarkEffect, p as Tween, r as DataEffect, s as TextSpace, t as AnyMarkEffect, u as MarkData, v as MotionMode, w as ScalingTable, x as ReducedMotionSource, y as MotionOptions, z as defaultClock } from "./effect-DYCLY_6e.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-OmQV-0BB.cjs";
3
- /** Builds a function that blends `from` into `to` as t goes from 0 to 1. */
4
- type Interpolator<T> = (from: T, to: T) => (t: number) => T;
5
- /** Exact at both ends, so a finished animation lands on its target. */
6
- export declare const interpolateNumber: Interpolator<number>;
7
- export declare const interpolatePoint: Interpolator<Point>;
8
- /**
9
- * Blends every key. A key missing on one side counts as 0 there, so a series
10
- * that appears grows from 0, and one that disappears shrinks to 0 and is gone at t = 1.
11
- */
12
- export declare function interpolateRecord<K extends string>(a: Readonly<Record<K, number>>, b: Readonly<Record<K, number>>): (t: number) => Record<K, number>;
13
- interface AnimateOptions {
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;
22
- }
23
- interface AnimatedOptions<T> extends Partial<MotionEnv> {
24
- /** Called whenever the value changes, including every animation frame. */
25
- readonly onChange?: (value: T) => void;
26
- }
27
- /** A value that can be retargeted mid-flight. */
28
- interface Animated<T> {
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>;
42
- interface PlaybackOptions extends Partial<MotionEnv> {
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;
55
- }
56
- /** What `subscribe` hears. Frames go to `onFrame` instead. */
57
- type PlaybackEvent = "play" | "pause" | "end" | "seek";
58
- interface SeekOptions {
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;
61
- }
62
- interface Playback {
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;
77
- }
78
- /**
79
- * A playback through `from`…`to`. `play()` moves the position at constant speed (with the default
80
- * `linear`), over `duration` scaled by the motion mode, and `onFrame` draws each position. With motion
81
- * off, a play jumps to the end, and motion turning off mid-play jumps there too, as tweens do. Nothing
82
- * plays by itself. Uses the page-wide motion and clock unless given its own.
83
- */
84
- export declare function playback(options: PlaybackOptions): Playback;
85
- /** The events effects attach to. */
86
- type EffectSlot = "hover" | "enter" | "update" | "exit" | "decorate";
87
- /**
88
- * A registered preset's name. The built-in names autocomplete; custom names (registerPreset) are
89
- * allowed too, so a misspelled name isn't a type error: the chart throws when it's created.
90
- */
91
- type PresetName = "wiggle" | "pulse" | "flash" | (string & {});
92
- type EffectOption<D> = MarkEffect<D> | PresetName;
93
- /**
94
- * The `on` option of charts and adapters. Use it as `EffectSlots<NoInfer<D>>`, so a generic data
95
- * effect such as threshold() can't widen the chart's row type to unknown.
96
- */
97
- interface EffectSlots<D> {
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
- }
109
- interface ArcSpec {
110
- readonly key: string;
111
- readonly series?: string;
112
- /** The donut's centre. */
113
- readonly cx: number;
114
- readonly cy: number;
115
- /** Radii in px; 0 inner makes a pie slice. They're swapped if inner > outer, as d3.arc() does. */
116
- readonly inner: number;
117
- readonly outer: number;
118
- /** Radians, 0 at 12 o'clock, clockwise: the d3.pie() convention. end < start walks anticlockwise. */
119
- readonly start: number;
120
- readonly end: number;
121
- /** The boxes of the text drawn for the mark, in the same px: passed through as `labelBounds`. */
122
- readonly labelBounds?: readonly Rect[];
123
- /** The boxes of other marks' text near it, in the same px: passed through as `nearbyLabels`. */
124
- readonly nearbyLabels?: readonly Rect[];
125
- }
126
- /**
127
- * The walk runs along the mid-radius arc from the start angle to the end angle, so for a slice
128
- * walked clockwise "up" is outward. The angle of travel equals the d3 angle (normalised).
129
- */
130
- declare function describeArc(spec: ArcSpec): MarkGeometry;
131
- /** The edge a bar grows from. */
132
- type Baseline = "left" | "right" | "top" | "bottom";
133
- interface BarSegmentSpec {
134
- readonly series: string;
135
- /** Px along the walk, gap included. */
136
- readonly size: number;
137
- }
138
- interface BarSpec {
139
- readonly key: string;
140
- readonly series?: string;
141
- /** The whole bar's rectangle, in chart px. */
142
- readonly x: number;
143
- readonly y: number;
144
- readonly width: number;
145
- readonly height: number;
146
- readonly baseline: Baseline;
147
- /** Corner radius at the tip. The baseline end stays square. Default 0. */
148
- readonly radius?: number;
149
- /**
150
- * Ordered parts, from the baseline. Default: one segment named after `series`, covering the bar.
151
- * Sizes normally add up to the bar's length; anything past the tip is cut off.
152
- */
153
- readonly segments?: readonly BarSegmentSpec[];
154
- /**
155
- * Px left empty between segments (the prototype uses 2). It comes out of the start of the later
156
- * segment, so every segment still ends at its value, and it shrinks to fit when what comes
157
- * before is shorter. Default 0.
158
- */
159
- readonly gap?: number;
160
- /** The boxes of the text drawn for the bar, its segments having none, in the same px: passed through as `labelBounds`. */
161
- readonly labelBounds?: readonly Rect[];
162
- /** The boxes of other marks' text near the bar, its segments having none, in the same px: passed through as `nearbyLabels`. */
163
- readonly nearbyLabels?: readonly Rect[];
164
- }
165
- /**
166
- * The walk runs along the centre line from the middle of the baseline edge to the middle of the
167
- * tip. A plain bar has one segment, so `travel(…, { along: "goals" })` works stacked or not.
168
- */
169
- declare function describeBar(spec: BarSpec): MarkGeometry;
170
- interface LineSpec {
171
- readonly key: string;
172
- readonly series?: string;
173
- /** At least one point, in chart px. */
174
- readonly points: readonly Point[];
175
- /**
176
- * The indices of the points that start a new run, so there's a gap from `points[i - 1]` to
177
- * `points[i]`: each a whole number from 1 to the last index, in order, with no repeats. A line
178
- * drawn with d3's `.defined()` is described by its defined points and where they break. Default none.
179
- */
180
- readonly breaks?: readonly number[];
181
- /** Stroke width in px. Default 1, SVG's default. */
182
- readonly width?: number;
183
- /** The boxes of the text drawn for the mark, in the same px: passed through as `labelBounds`. */
184
- readonly labelBounds?: readonly Rect[];
185
- /** The boxes of other marks' text near it, in the same px: passed through as `nearbyLabels`. */
186
- readonly nearbyLabels?: readonly Rect[];
187
- }
188
- /**
189
- * The walk is the line itself, first point to last, running straight across each break. Its outline
190
- * is open: the stroke, with the breaks left out. A break between two points in the same place leaves
191
- * no gap, since there's nothing between them to leave out.
192
- */
193
- declare function describeLine(spec: LineSpec): MarkGeometry;
194
- interface PointSpec {
195
- readonly key: string;
196
- readonly series?: string;
197
- readonly x: number;
198
- readonly y: number;
199
- /** Radius in px. */
200
- readonly r: number;
201
- /** The boxes of the text drawn for the mark, in the same px: passed through as `labelBounds`. */
202
- readonly labelBounds?: readonly Rect[];
203
- /** The boxes of other marks' text near it, in the same px: passed through as `nearbyLabels`. */
204
- readonly nearbyLabels?: readonly Rect[];
205
- }
206
- /**
207
- * Length 0, with start = end = centre, so travel does nothing while wiggle, pulse and flash still
208
- * work. Faces +x: the outline's sides are the quarter circles top, right, bottom and left.
209
- */
210
- declare function describePoint(spec: PointSpec): MarkGeometry;
211
- interface ShapeSpec {
212
- readonly key: string;
213
- readonly series?: string;
214
- /**
215
- * SVG path data in the shape's own px, read as SVG reads it, up to its first error. A shape is
216
- * closed when every subpath ends with Z, or where it started, and otherwise open, a line.
217
- */
218
- readonly d: string;
219
- /** Moves the shape into the marks' px, as an element's transform does, arcs too. Default none. */
220
- readonly matrix?: Matrix;
221
- /** An open shape's stroke width in px, more than 0. Default 1, SVG's default. */
222
- readonly width?: number;
223
- /** The boxes of the text drawn for the mark, in the marks' px: passed through as `labelBounds`. */
224
- readonly labelBounds?: readonly Rect[];
225
- /** The boxes of other marks' text near it, in the marks' px: passed through as `nearbyLabels`. */
226
- readonly nearbyLabels?: readonly Rect[];
227
- }
228
- /**
229
- * Path data, flattened: straight pieces and circular arcs stay as they are, and Béziers and other
230
- * arcs become straight pieces within 0.1 px of the curve.
231
- * - An open shape is a line. Its walk runs along the path from its first point, and each later move
232
- * starts a new run after a gap. Its outline is the stroke, less the gaps, and its thickness,
233
- * bounds, centre and pivot are as `describe.line`'s.
234
- * - A closed shape has no direction: its walk is its bounds' centre, with length 0. Its outline's
235
- * `d` is the whole path, holes too, and `sample(n)` goes round its longest subpath, clockwise in
236
- * four quarters of equal length from its upper left. Its thickness is the smaller of its width and
237
- * height.
238
- * A subpath that ends where it started is closed too, as d3.arc() draws a full ring's outer edge.
239
- * A path whose subpaths are all closed but have no length, as d3 draws a value alone, is open: a line
240
- * with nothing to stroke.
241
- */
242
- declare function describeShape(spec: ShapeSpec): MarkGeometry;
243
- export declare const describe: {
244
- bar: typeof describeBar;
245
- arc: typeof describeArc;
246
- line: typeof describeLine;
247
- point: typeof describePoint;
248
- shape: typeof describeShape;
249
- };
250
- declare function translate(x: number, y: number): Matrix;
251
- /** Positive radians turn clockwise on screen, like SVG's rotate(). */
252
- declare function rotate(radians: number, about?: Point): Matrix;
253
- declare function scale(sx: number, sy?: number, about?: Point): Matrix;
254
- /** Composes like an SVG transform list: multiply(a, b) applies b first, then a. No arguments gives the identity. */
255
- declare function multiply(...matrices: Matrix[]): Matrix;
256
- /** Where the transform takes a point. */
257
- declare function apply(m: Matrix, point: Point): Point;
258
- /** Builds and applies 2D transforms in SVG order, for `mark.set({ transform })` and `IconHandle.place()`. */
259
- export declare const matrix: {
260
- translate: typeof translate;
261
- rotate: typeof rotate;
262
- scale: typeof scale;
263
- multiply: typeof multiply;
264
- apply: typeof apply;
265
- };
266
- /** A point `distance` px from `point` in direction `angle` (screen radians). */
267
- export declare function offset(point: Point, angle: number, distance: number): Point;
268
- /** A data point in the mark's coordinates, with its value and, optionally, the x value behind it. */
269
- interface SamplePoint {
270
- readonly x: number;
271
- readonly y: number;
272
- readonly value: number;
273
- readonly at?: string | number | Date;
274
- }
275
- /**
276
- * Projects each point onto the nearest point of the mark's walk and returns the samples in `t` order
277
- * (points at the same `t` keep their order). A point on the walk, such as a vertex of the polyline it
278
- * drew, lands exactly where it is. Where the mark has gaps, the first sample past each gap's middle
279
- * has `gapBefore`, so a data effect doesn't join it to the one before. Throws a RangeError on a point
280
- * whose x, y or value isn't finite.
281
- */
282
- export declare function samplesAlong(mark: MarkGeometry, points: readonly SamplePoint[]): Sample[];
1
+ import { $ as interpolateRecord, A as MarkStyle, At as createClock, B as Sample, C as TextSpace, Ct as Easing, D as IconHandle, Dt as Clock, E as Color, Et as linear, F as TextStyle, G as playback, H as PlaybackEvent, I as Icon, J as AnimatedOptions, K as AnimateOptions, L as IconShape, M as Paint, Mt as manualClock, N as PathHandle, O as Layer, Ot as FrameSource, P as TextHandle, Q as interpolatePoint, R as IconSource, S as MarkEffect, St as scaleDuration, T as TransitionEffect, Tt as easeOutCubic, U as PlaybackOptions, V as Playback, W as SeekOptions, X as animated, Y as Interpolator, Z as interpolateNumber, _ as AnyMarkEffect, _t as Timing, a as describe, at as Tween, b as EffectContext, bt as mediaReducedMotion, c as LineSpec, ct as tween, d as Baseline, dt as MotionOptions, et as MarkGeometry, f as ArcSpec, ft as MotionView, g as PresetName, gt as ScalingTable, h as EffectSlots, ht as ScalingRule, i as offset, it as MotionEnv, j as Matrix, jt as defaultClock, k as MarkHandle, kt as ManualClock, l as BarSegmentSpec, lt as Motion, m as EffectSlot, mt as ScalingOverrides, n as samplesAlong, nt as Point, o as ShapeSpec, ot as TweenOptions, p as EffectOption, pt as ReducedMotionSource, q as Animated, r as matrix, rt as Rect, s as PointSpec, st as TweenResult, t as SamplePoint, tt as Outline, u as BarSpec, ut as MotionMode, v as Combined, vt as createMotion, w as TransitionContext, wt as easeInOutCubic, x as GeometryEffect, xt as motion, y as DataEffect, yt as defaultScaling, z as MarkData } from "./index-CmnxlWkB.cjs";
2
+ import "./runner-C87v9F_y.cjs";
283
3
  interface ColorAssignment {
284
4
  /** The palette slot (1–8) for a key: its pinned slot, or the next free one the first time it's seen. Never reassigned. */
285
5
  slot(key: string): number;
@@ -680,6 +400,39 @@ interface Chart<D, O> {
680
400
  }
681
401
  type BarChart<D> = Chart<D, BarChartOptions<D>>;
682
402
  type DonutChart<D> = Chart<D, DonutChartOptions<D>>;
403
+ /** What a link takes: a chart (barChart, donutChart, lineChart), a chartSwitch or an attachment (expressive, fromVegaView), with rows D. */
404
+ interface LinkSource<D> {
405
+ on(type: "hover", listener: (event: MarkEvents<D>["hover"]) => void): () => void;
406
+ marks(): readonly MarkGeometry[];
407
+ }
408
+ /** The rows of the sources in S: each chart's, switch's and attachment's, as a union. */
409
+ type RowsOf<S> = S extends LinkSource<infer D> ? D : never;
410
+ interface LinkOptions<D> {
411
+ /**
412
+ * A mark's linking value, given the mark and its data as a hover event has them. Default: its last
413
+ * sample's `at` if it has one (a line point's x), else its key (a bar's or a slice's category).
414
+ * Values are compared as strings, a Date by its ISO string, as keys are. Undefined or null links
415
+ * nothing, and so does a throw (reported). A line chart's x with every value missing has no point,
416
+ * so it's given a stand-in for one, keyed by the x, with the row and a sample at the x, whose value
417
+ * is NaN.
418
+ */
419
+ readonly by?: (event: Pick<MarkEvent<D>, "mark" | "data">) => unknown;
420
+ /** Whether linked marks play their chart's hover effect. Default true; false keeps them to emphasis and dimming. */
421
+ readonly effects?: boolean;
422
+ }
423
+ interface Link {
424
+ /** Ends the link: linked hovers end, and each source can be linked again. The sources' own hovers go on. */
425
+ destroy(): void;
426
+ }
427
+ /**
428
+ * Links hover across `sources`: when one is hovered by the pointer, touch or the keyboard, every other
429
+ * hovers its targets with that linking value (a line chart its x, a bar chart its bar), as `source:
430
+ * "linked"`, and leaves them when it leaves. The newest hover anywhere in the link is the one shown.
431
+ * A chart switch takes part through its view on show. Throws a TypeError, linking nothing, on a source
432
+ * that isn't a chart, a chart switch or an attachment, or one that's in a link already, a switch's
433
+ * views' charts going with it. A destroyed source drops out.
434
+ */
435
+ export declare function link<S extends LinkSource<unknown>>(sources: readonly S[], options?: LinkOptions<RowsOf<S>>): Link;
683
436
  /**
684
437
  * A CSS selector, an element, a list of elements (a NodeList, an array), or anything shaped like a D3
685
438
  * selection, whose `data()` types the callbacks. `each` is only there for the types: a D3
@@ -844,104 +597,15 @@ interface Attachment<D> {
844
597
  /** Clears every effect and removes everything the adapter added, leaving the host's DOM as it was. */
845
598
  destroy(): void;
846
599
  }
847
- /**
848
- * What fromVegaView() uses of a Vega View: its renderer, its scenegraph and the element it renders
849
- * into. The scenegraph is read as `{ root }` (what Vega returns) or as the root mark itself (what
850
- * vega-typings declare), so a View fits whichever the types say.
851
- */
852
- interface VegaViewLike {
853
- renderer(): string;
854
- scenegraph(): object;
855
- container(): Element | null;
856
- }
857
- /** A mark in Vega's scenegraph: its type, its name, and its items. */
858
- interface VegaMark {
859
- readonly marktype?: string;
860
- readonly name?: string;
861
- readonly items?: readonly VegaItem[];
862
- }
863
- /** An item of a Vega mark, as its encoders left it. A group's items hold the marks inside it. */
864
- interface VegaItem {
865
- readonly mark?: VegaMark;
866
- readonly datum?: unknown;
867
- readonly items?: readonly VegaMark[];
868
- readonly x?: number;
869
- readonly y?: number;
870
- readonly width?: number;
871
- readonly height?: number;
872
- readonly startAngle?: number;
873
- readonly endAngle?: number;
874
- readonly innerRadius?: number;
875
- readonly outerRadius?: number;
876
- readonly size?: number;
877
- readonly strokeWidth?: number;
878
- readonly cornerRadius?: number;
879
- /** False for a line's point Vega leaves out, which breaks the line there. */
880
- readonly defined?: boolean;
881
- /** How a line is drawn between its points: "linear" (or unset) is read from the items, any other curve from the path Vega draws. */
882
- readonly interpolate?: string;
883
- }
884
- /** A value for data effects: alone, or with where it is along x (`at`), which threshold matches series by. */
885
- type VegaSample = number | {
886
- readonly value: number;
887
- readonly at?: string | number | Date;
888
- };
889
- interface VegaOptions<D> extends Omit<ExpressiveOptions<D>, "datum" | "geometry" | "watch"> {
890
- /** The Vega mark to read, by name. Default "marks", the name Vega-Lite gives a chart's data mark. */
891
- readonly mark?: string;
892
- /**
893
- * For data effects: the value an item's row shows, and optionally where it is along x. A line gets a
894
- * sample at each of its points, a bar from 0 at its baseline to its value (a stack's segments each over
895
- * their own range), a slice from 0 to its value, and a point its value. `samples` replaces this.
896
- * Unless `value` is given, it's also what each element shows (a line: every point's), so a re-render
897
- * that only moves marks, such as a resize, isn't an update.
898
- */
899
- readonly sample?: (row: D) => VegaSample;
900
- }
901
- /** fromVegaView()'s attachment: refresh() reads the View again (it refreshes itself after each render too). */
902
- interface VegaAttachment<D> extends Omit<Attachment<D>, "refresh"> {
903
- refresh(): void;
904
- }
905
- /** What a link takes: a chart (barChart, donutChart, lineChart), a chartSwitch or an attachment (expressive, fromVegaView), with rows D. */
906
- interface LinkSource<D> {
907
- on(type: "hover", listener: (event: MarkEvents<D>["hover"]) => void): () => void;
908
- marks(): readonly MarkGeometry[];
909
- }
910
- /** The rows of the sources in S: each chart's, switch's and attachment's, as a union. */
911
- type RowsOf<S> = S extends LinkSource<infer D> ? D : never;
912
- interface LinkOptions<D> {
913
- /**
914
- * A mark's linking value, given the mark and its data as a hover event has them. Default: its last
915
- * sample's `at` if it has one (a line point's x), else its key (a bar's or a slice's category).
916
- * Values are compared as strings, a Date by its ISO string, as keys are. Undefined or null links
917
- * nothing, and so does a throw (reported). A line chart's x with every value missing has no point,
918
- * so it's given a stand-in for one, keyed by the x, with the row and a sample at the x, whose value
919
- * is NaN.
920
- */
921
- readonly by?: (event: Pick<MarkEvent<D>, "mark" | "data">) => unknown;
922
- /** Whether linked marks play their chart's hover effect. Default true; false keeps them to emphasis and dimming. */
923
- readonly effects?: boolean;
924
- }
925
- interface Link {
926
- /** Ends the link: linked hovers end, and each source can be linked again. The sources' own hovers go on. */
927
- destroy(): void;
928
- }
929
- /**
930
- * Links hover across `sources`: when one is hovered by the pointer, touch or the keyboard, every other
931
- * hovers its targets with that linking value (a line chart its x, a bar chart its bar), as `source:
932
- * "linked"`, and leaves them when it leaves. The newest hover anywhere in the link is the one shown.
933
- * A chart switch takes part through its view on show. Throws a TypeError, linking nothing, on a source
934
- * that isn't a chart, a chart switch or an attachment, or one that's in a link already, a switch's
935
- * views' charts going with it. A destroyed source drops out.
936
- */
937
- export declare function link<S extends LinkSource<unknown>>(sources: readonly S[], options?: LinkOptions<RowsOf<S>>): Link;
938
600
  /**
939
601
  * What a chart switch uses of each view's chart. A reference chart's handle has all of it: its
940
602
  * `<svg>` (which takes `ec-morphing` while its marks morph in the switch's overlay), its marks and
941
603
  * labels as drawn, focus by key, leave() to end its hover, and destroy(); how it paints each mark
942
604
  * (paintOf), a line chart's what its focus stops stand for (standsFor), and its tab stop moved
943
605
  * without focus (moveTabStop). A reference chart also has on(), which the switch's on() hears, and a
944
- * hover a link can drive; a view without them isn't heard and isn't linked.
606
+ * hover a link can drive; a view without them isn't heard and isn't linked. hostView() makes a view
607
+ * of an attachment, which hides its own marks (morphing), finds a mark's key from its elements
608
+ * (keyOf), paints each in the host's colour, and gives its marks in their common ancestor's space.
945
609
  */
946
610
  interface ChartSwitchView {
947
611
  readonly element: SVGSVGElement;
@@ -968,11 +632,31 @@ interface ChartSwitchView {
968
632
  * Without it, a view keeps its own tab stop.
969
633
  */
970
634
  moveTabStop?(key: string): boolean;
635
+ /**
636
+ * The key of the mark `element` belongs to, which the switch asks first when it remembers where
637
+ * focus was, before the element's closest `[data-key]`: a host chart's marks have none.
638
+ */
639
+ keyOf?(element: Element): string | undefined;
640
+ /**
641
+ * Hides (true) or shows again (false) the marks and labels the switch draws in its overlay, while
642
+ * a switch plays: called as `element` takes `ec-morphing`, and as it loses it or the switch is
643
+ * destroyed mid-way. A host chart's marks don't have the class that hides a chart's. Without it,
644
+ * the class hides them.
645
+ */
646
+ morphing?(on: boolean): void;
647
+ /**
648
+ * The element whose user space marks() and labels() are in, when it isn't `element`: an attachment's
649
+ * marks' common ancestor. Its labels' text is sized in it too, so their copies scale into the overlay
650
+ * with the marks, as a chart's, sized by the stylesheet, don't.
651
+ */
652
+ readonly space?: Element;
971
653
  }
972
654
  /** How a view's chart paints one of its marks: what a switch draws it in. */
973
655
  interface ChartSwitchPaint {
974
656
  /** The name its colour comes from in the switch's assignment (`colors.slot(color)`): a line's or a point's series, a bar's key or first series, a slice's key. */
975
657
  readonly color: string;
658
+ /** The colour itself, any CSS colour, drawn in place of `color`'s slot: a host chart's own. */
659
+ readonly cssColor?: string;
976
660
  /** Whether the chart draws it at rest. A line chart's points aren't, but for a value alone between gaps; a mark that isn't starts or ends a switch as a dot of no size at its centre, with no end dot or ring. */
977
661
  readonly drawn: boolean;
978
662
  /** The radius of the dot the chart draws at the end of the mark's walk, in its `<svg>`'s units: a line chart's line has one of 4.5. Unset: no dot. */
@@ -1009,8 +693,18 @@ interface ChartSwitchOptions<T extends ChartSwitchViews> {
1009
693
  /** A polite live region that says the new view's label (its chart's `label`) after each switch. Default false. */
1010
694
  readonly announce?: boolean;
1011
695
  }
696
+ /** How show() switches. */
697
+ interface ChartSwitchShowOptions<T extends ChartSwitchViews> {
698
+ /**
699
+ * A view to stage the jump through. In Presentation (`motion.staged`), the switch plays from the
700
+ * view on show to `via`, then from `via` to the view, each a full switch, and lands once: focus
701
+ * follows its key into the view, and the view alone is announced. In Analysis and Off, and when
702
+ * `via` is the view on show or the view itself, it switches straight there. Rejects for an unknown view.
703
+ */
704
+ readonly via?: ChartSwitchViewName<T>;
705
+ }
1012
706
  interface ChartSwitch<T extends ChartSwitchViews> {
1013
- /** The view shown, or the one a switch is heading for. */
707
+ /** The view shown, or the one a switch is heading for: a staged jump's view from its start. */
1014
708
  readonly current: ChartSwitchViewName<T>;
1015
709
  /**
1016
710
  * Switches to `view`: each mark morphs into the mark with its key, by the motion mode. Resolves
@@ -1018,8 +712,15 @@ interface ChartSwitch<T extends ChartSwitchViews> {
1018
712
  * a switch is leaving reverses it from where the shapes are; one to a third view lands the switch
1019
713
  * first. With motion off, the switch has landed when show() returns. Rejects for an unknown view.
1020
714
  * One a `leave` listener calls as the old view's hover ends runs once the switch has begun.
1021
- */
1022
- show(view: ChartSwitchViewName<T>): Promise<void>;
715
+ *
716
+ * With `via`, in Presentation, the jump is staged through that view, and `current` is `view` from
717
+ * the start. A show() for `view` plays on. One in the first leg drops the leg still to come and acts
718
+ * on the one playing, as on any switch: back to the view it began in, it reverses; to `via`, it plays
719
+ * on and stops there; to another view, it lands on `via` and switches on from there, by that show()'s
720
+ * own `via`. The second leg is a switch from `via` to `view`, as any other. Motion turning off, or a
721
+ * resize, lands the jump on `view` at once.
722
+ */
723
+ show(view: ChartSwitchViewName<T>, options?: ChartSwitchShowOptions<T>): Promise<void>;
1023
724
  /** The chart a view's function returned: for update(), on() and the rest. */
1024
725
  chart<K extends ChartSwitchViewName<T>>(view: K): ReturnType<T[K]>;
1025
726
  /**
@@ -1039,6 +740,104 @@ interface ChartSwitch<T extends ChartSwitchViews> {
1039
740
  /** Ends any switch, destroys every view's chart and removes everything the switch added. */
1040
741
  destroy(): void;
1041
742
  }
743
+ /** A host's `<text>` that names a mark or gives its value, which a chart switch moves and swaps as a chart's labels. */
744
+ interface HostLabel {
745
+ readonly element: SVGTextElement;
746
+ /** The mark's key. */
747
+ readonly key: string;
748
+ /** "category": the mark's name (a slice's outside label, a column's name). "value": its value. */
749
+ readonly role: "category" | "value";
750
+ }
751
+ interface HostViewOptions {
752
+ /**
753
+ * The host's labels, each a `<text>` in its `<svg>` with its mark's key and its role, read as each
754
+ * switch starts. Each moves to the label with its key and role in the next view, as a chart's labels
755
+ * do, and swaps its text half way; one with no partner fades. A label whose key is no mark's is left
756
+ * out, and so is everything if it throws (reported). The host's other text fades with its view.
757
+ * Default: none.
758
+ */
759
+ readonly labels?: () => Iterable<HostLabel>;
760
+ }
761
+ /** An attachment as a chart switch's view: the attachment's own methods, with the view's. */
762
+ interface HostView<D> extends Attachment<D>, ChartSwitchView {
763
+ /** The host's root `<svg>`. Its `aria-label` is what a switch's `announce` says. */
764
+ readonly element: SVGSVGElement;
765
+ /** The marks' nearest common ancestor, whose space marks() and labels() are in. */
766
+ readonly space: Element;
767
+ /** The labels `labels` gives, as a switch draws them: at their anchor, in the host text's computed font and fill. */
768
+ labels(): readonly ChartLabel[];
769
+ /** The host's colour for the mark, its fill or its stroke on a line, as its first part draws it. */
770
+ paintOf(key: string): ChartSwitchPaint | undefined;
771
+ keyOf(element: Element): string | undefined;
772
+ moveTabStop(key: string): boolean;
773
+ morphing(on: boolean): void;
774
+ }
775
+ /**
776
+ * Makes an attachment that expressive() or fromVegaView() returned a view for chartSwitch: a view's
777
+ * function attaches to the chart it draws in its container and returns hostView(attachment). The
778
+ * host's marks hide while a switch plays and morph in its colours, the labels it's given move and
779
+ * swap, its other parts fade, and with `keyboard: true` focus follows its key. Throws a TypeError on
780
+ * anything else, or on an attachment with no marks yet, which has no `<svg>`.
781
+ */
782
+ export declare function hostView<D>(attachment: Attachment<D>, options?: HostViewOptions): HostView<D>;
783
+ /**
784
+ * What fromVegaView() uses of a Vega View: its renderer, its scenegraph and the element it renders
785
+ * into. The scenegraph is read as `{ root }` (what Vega returns) or as the root mark itself (what
786
+ * vega-typings declare), so a View fits whichever the types say.
787
+ */
788
+ interface VegaViewLike {
789
+ renderer(): string;
790
+ scenegraph(): object;
791
+ container(): Element | null;
792
+ }
793
+ /** A mark in Vega's scenegraph: its type, its name, and its items. */
794
+ interface VegaMark {
795
+ readonly marktype?: string;
796
+ readonly name?: string;
797
+ readonly items?: readonly VegaItem[];
798
+ }
799
+ /** An item of a Vega mark, as its encoders left it. A group's items hold the marks inside it. */
800
+ interface VegaItem {
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: "linear" (or unset) is read from the items, any other curve from the path Vega draws. */
818
+ readonly interpolate?: string;
819
+ }
820
+ /** A value for data effects: alone, or with where it is along x (`at`), which threshold matches series by. */
821
+ type VegaSample = number | {
822
+ readonly value: number;
823
+ readonly at?: string | number | Date;
824
+ };
825
+ interface VegaOptions<D> extends Omit<ExpressiveOptions<D>, "datum" | "geometry" | "watch"> {
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;
836
+ }
837
+ /** fromVegaView()'s attachment: refresh() reads the View again (it refreshes itself after each render too). */
838
+ interface VegaAttachment<D> extends Omit<Attachment<D>, "refresh"> {
839
+ refresh(): void;
840
+ }
1042
841
  /** How the stylesheet reaches the page. */
1043
842
  interface StyleOptions {
1044
843
  /** Set on the injected `<style>`, for a Content-Security-Policy that allows styles by nonce. */
@@ -1349,6 +1148,14 @@ interface MorphOptions {
1349
1148
  * where that place is outside it or near its edge. Where it would leave the shape on the way, it
1350
1149
  * closes sooner, as soon as a sixteenth of the way. Each is written the other way round from the
1351
1150
  * outside, so it stays a hole under either fill rule.
1151
+ * - **Two bands across the same x's** (closed outlines whose longest loop, with no arc, splits at its
1152
+ * leftmost and rightmost points into an upper run and a lower run, each going one way across x in
1153
+ * two straight pieces or more, as d3.area() draws an area; the two bands' leftmost x's within
1154
+ * 0.01 px, and their rightmost) pair by x: upper run with upper and lower with lower, each as two
1155
+ * lines across x pair, by share of its span, with stops at `points` shares and at each vertex of
1156
+ * either run. So two areas over the same weeks keep each week's x on every frame, corners pair with
1157
+ * corners, and the edges at each end join the runs as they move. `align` doesn't turn them. Holes
1158
+ * morph as above. A rectangle's top and base are a piece each, so bars aren't bands.
1352
1159
  * - **Two lines that each run one way across x** (every vertex's x more than the one before, or
1353
1160
  * every one less, the same way for both) pair by x: the point a share of the way across one
1354
1161
  * line's x span moves to the point that share across the other's. They're sampled at `points`
@@ -1479,7 +1286,7 @@ export declare function registerIcons(icons: readonly Icon[]): void;
1479
1286
  * has the same rules. For a CSP that allows no inline styles at all.
1480
1287
  */
1481
1288
  export declare function configure(options: StyleOptions): void;
1482
- export declare const VERSION = "0.8.0";
1289
+ export declare const VERSION = "0.10.0";
1483
1290
  /**
1484
1291
  * A bar chart in `target` (an element or a selector). The axis whose values aren't numbers is the
1485
1292
  * category; `stack` stacks numeric fields; `on` attaches effects by slot.
@@ -1500,8 +1307,9 @@ export declare function lineChart<D>(target: string | Element, options: LineChar
1500
1307
  /**
1501
1308
  * Views of the same data in `target` (an element or a selector), one shown at a time: `show(view)`
1502
1309
  * turns each mark into the mark with its key in the other view with `transition`, morph() by default,
1503
- * while the labels move and swap their text. Each view's function draws its chart in the container
1504
- * it's given; pass it the `colors` it's given too, so a key keeps its colour from view to view.
1310
+ * while the labels move and swap their text, and `show(view, { via })` stages a jump through a third
1311
+ * view in Presentation. Each view's function draws its chart in the container it's given; pass it the
1312
+ * `colors` it's given too, so a key keeps its colour from view to view.
1505
1313
  */
1506
1314
  export declare function chartSwitch<T extends ChartSwitchViews>(target: string | Element, options: ChartSwitchOptions<T>): ChartSwitch<T>;
1507
1315
  /**
@@ -1524,5 +1332,4 @@ export declare function fromVegaView<D = Record<string, unknown>>(view: VegaView
1524
1332
  * page-wide `motion`. `persist: "key"` saves the choice in localStorage.
1525
1333
  */
1526
1334
  export declare function motionSwitch(target: string | Element, motion?: Motion, options?: MotionSwitchOptions): MotionSwitch;
1527
- 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 ChartSwitchPaint, 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 DrawInOptions, 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 TextSpace, 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 };
1528
- //# sourceMappingURL=index.d.cts.map
1335
+ 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 ChartSwitchPaint, type ChartSwitchShowOptions, 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 DrawInOptions, 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 HostLabel, type HostMark, type HostView, type HostViewOptions, 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 TextSpace, 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, animated, createClock, createMotion, defaultClock, defaultScaling, describe, easeInOutCubic, easeOutCubic, interpolateNumber, interpolatePoint, interpolateRecord, linear, manualClock, matrix, mediaReducedMotion, motion, offset, playback, samplesAlong, scaleDuration, tween };