expressive-charts 0.1.0 → 0.3.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 (36) hide show
  1. package/CHANGELOG.md +47 -0
  2. package/README.md +14 -13
  3. package/dist/{chunk-N5IF2RO2.js → chunk-7A7LXXT4.js} +6 -2
  4. package/dist/chunk-7A7LXXT4.js.map +1 -0
  5. package/dist/{chunk-ZIGBM4NY.js → chunk-CJUQHEX6.js} +92 -28
  6. package/dist/chunk-CJUQHEX6.js.map +1 -0
  7. package/dist/{chunk-CVXP2L2J.js → chunk-N2BLUETM.js} +17 -5
  8. package/dist/chunk-N2BLUETM.js.map +1 -0
  9. package/dist/{drawing-Du6DAgrW.d.cts → drawing-CdTgixMY.d.cts} +20 -2
  10. package/dist/{drawing-Du6DAgrW.d.ts → drawing-CdTgixMY.d.ts} +20 -2
  11. package/dist/{effect-dPmXiWlL.d.cts → effect-Bu3MHHeg.d.ts} +4 -2
  12. package/dist/{effect-OcyvtfZi.d.ts → effect-D4vmdYP4.d.cts} +4 -2
  13. package/dist/expressive-charts.css +11 -6
  14. package/dist/expressive-charts.css.d.cts +2 -0
  15. package/dist/expressive-charts.css.d.ts +2 -0
  16. package/dist/expressive-charts.global.js +29 -24
  17. package/dist/expressive-charts.global.js.map +1 -1
  18. package/dist/icons/sport.cjs +5 -1
  19. package/dist/icons/sport.cjs.map +1 -1
  20. package/dist/icons/sport.js +2 -2
  21. package/dist/index.cjs +1610 -669
  22. package/dist/index.cjs.map +1 -1
  23. package/dist/index.d.cts +143 -18
  24. package/dist/index.d.ts +143 -18
  25. package/dist/index.js +1448 -591
  26. package/dist/index.js.map +1 -1
  27. package/dist/testing.cjs +93 -42
  28. package/dist/testing.cjs.map +1 -1
  29. package/dist/testing.d.cts +2 -2
  30. package/dist/testing.d.ts +2 -2
  31. package/dist/testing.js +6 -8
  32. package/dist/testing.js.map +1 -1
  33. package/package.json +16 -4
  34. package/dist/chunk-CVXP2L2J.js.map +0 -1
  35. package/dist/chunk-N5IF2RO2.js.map +0 -1
  36. package/dist/chunk-ZIGBM4NY.js.map +0 -1
package/dist/index.d.cts CHANGED
@@ -1,7 +1,7 @@
1
- import { T as Timing, E as Easing, a as TweenResult, M as MotionEnv, b as MarkEffect, S as Sample, c as MarkData, d as Motion, e as MotionMode, f as TransitionEffect, G as GeometryEffect, D as DataEffect, A as AnyMarkEffect, C as Combined, g as EffectContext } from './effect-dPmXiWlL.cjs';
2
- export { h as Clock, F as FrameSource, i as ManualClock, j as MotionOptions, k as MotionView, R as ReducedMotionSource, l as ScalingOverrides, m as ScalingRule, n as ScalingTable, o as TransitionContext, p as Tween, q as TweenOptions, r as createClock, s as createMotion, t as defaultClock, u as defaultScaling, v as easeInOutCubic, w as easeOutCubic, x as linear, y as manualClock, z as mediaReducedMotion, B as motion, H as scaleDuration, I as tween } from './effect-dPmXiWlL.cjs';
3
- import { P as Point, M as MarkGeometry, a as Matrix, C as Color, I as Icon } from './drawing-Du6DAgrW.cjs';
4
- export { b as IconHandle, c as IconShape, d as IconSource, L as Layer, e as MarkHandle, f as MarkStyle, O as Outline, g as Paint, h as PathHandle, R as Rect, T as TextHandle, i as TextStyle } from './drawing-Du6DAgrW.cjs';
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
5
 
6
6
  /** Builds a function that blends `from` into `to` as t goes from 0 to 1. */
7
7
  type Interpolator<T> = (from: T, to: T) => (t: number) => T;
@@ -124,6 +124,8 @@ interface ArcSpec {
124
124
  /** Radians, 0 at 12 o'clock, clockwise: the d3.pie() convention. end < start walks anticlockwise. */
125
125
  readonly start: number;
126
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[];
127
129
  }
128
130
  /**
129
131
  * The walk runs along the mid-radius arc from the start angle to the end angle, so for a slice
@@ -160,6 +162,8 @@ interface BarSpec {
160
162
  * before is shorter. Default 0.
161
163
  */
162
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[];
163
167
  }
164
168
  /**
165
169
  * The walk runs along the centre line from the middle of the baseline edge to the middle of the
@@ -172,10 +176,22 @@ interface LineSpec {
172
176
  readonly series?: string;
173
177
  /** At least one point, in chart px. */
174
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[];
175
185
  /** Stroke width in px. Default 1, SVG's default. */
176
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[];
177
189
  }
178
- /** The walk is the line itself, first point to last. Its outline is open: the stroke. */
190
+ /**
191
+ * The walk is the line itself, first point to last, running straight across each break. Its outline
192
+ * is open: the stroke, with the breaks left out. A break between two points in the same place leaves
193
+ * no gap, since there's nothing between them to leave out.
194
+ */
179
195
  declare function describeLine(spec: LineSpec): MarkGeometry;
180
196
 
181
197
  interface PointSpec {
@@ -185,6 +201,8 @@ interface PointSpec {
185
201
  readonly y: number;
186
202
  /** Radius in px. */
187
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[];
188
206
  }
189
207
  /**
190
208
  * Length 0, with start = end = centre, so travel does nothing while wiggle, pulse and flash still
@@ -228,7 +246,9 @@ interface SamplePoint {
228
246
  /**
229
247
  * Projects each point onto the nearest point of the mark's walk and returns the samples in `t` order
230
248
  * (points at the same `t` keep their order). A point on the walk, such as a vertex of the polyline it
231
- * drew, lands exactly where it is. Throws a RangeError on a point whose x, y or value isn't finite.
249
+ * drew, lands exactly where it is. Where the mark has gaps, the first sample past each gap's middle
250
+ * has `gapBefore`, so a data effect doesn't join it to the one before. Throws a RangeError on a point
251
+ * whose x, y or value isn't finite.
232
252
  */
233
253
  declare function samplesAlong(mark: MarkGeometry, points: readonly SamplePoint[]): Sample[];
234
254
 
@@ -267,8 +287,9 @@ interface MarkEvents<D> {
267
287
  readonly from: MarkGeometry;
268
288
  };
269
289
  exit: MarkEvent<D>;
290
+ /** `source` "linked": hovered by `link()`, because a mark in another chart with its linking value was. */
270
291
  hover: MarkEvent<D> & {
271
- readonly source: "pointer" | "keyboard" | "touch";
292
+ readonly source: "pointer" | "keyboard" | "touch" | "linked";
272
293
  readonly segment?: string;
273
294
  };
274
295
  leave: MarkEvent<D>;
@@ -438,6 +459,12 @@ interface BarChartOptions<D> extends ChartOptions<D> {
438
459
  * colour in both; the legend lists the categories. It needs one series: on a stack it throws.
439
460
  */
440
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;
441
468
  }
442
469
  /** 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. */
443
470
  interface SliceSummary extends MarkSummary {
@@ -494,9 +521,11 @@ interface LineChartOptions<D> extends ChartOptions<D> {
494
521
  readonly xFormat?: (x: Date | number) => string;
495
522
  /**
496
523
  * The numeric fields drawn as lines, in order. Each is a line mark keyed by its field, plus a point
497
- * mark per row keyed "<series>@<row key>" ("goals@12"). A missing or non-finite value throws.
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.
498
527
  */
499
- readonly series: readonly NumericKey<D>[];
528
+ readonly series: readonly KeyOfType<D, number | null | undefined>[];
500
529
  /**
501
530
  * The label at each line's end, in the right margin: by default its value in `format` with its
502
531
  * series' label ("52 goals"), counting between values while a change or a reveal plays. `false`
@@ -763,6 +792,37 @@ interface VegaAttachment<D> extends Omit<Attachment<D>, "refresh"> {
763
792
  refresh(): void;
764
793
  }
765
794
 
795
+ /** What a link takes: a chart (barChart, donutChart, lineChart) or an attachment (expressive, fromVegaView), with rows D. */
796
+ interface LinkSource<D> {
797
+ on(type: "hover", listener: (event: MarkEvents<D>["hover"]) => void): () => void;
798
+ marks(): readonly MarkGeometry[];
799
+ }
800
+ /** The rows of the sources in S: each chart's and attachment's, as a union. */
801
+ type RowsOf<S> = S extends LinkSource<infer D> ? D : never;
802
+ 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;
812
+ }
813
+ 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;
816
+ }
817
+ /**
818
+ * Links hover across `sources`: when one is hovered by the pointer, touch or the keyboard, every other
819
+ * hovers its targets with that linking value (a line chart its x, a bar chart its bar), as `source:
820
+ * "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.
823
+ */
824
+ declare function link<S extends LinkSource<unknown>>(sources: readonly S[], options?: LinkOptions<RowsOf<S>>): Link;
825
+
766
826
  /**
767
827
  * What a chart switch uses of each view's chart. A reference chart's handle has all of it: its
768
828
  * `<svg>` (which takes `ec-morphing` while its marks morph in the switch's overlay), its marks and
@@ -940,6 +1000,11 @@ interface TravelOptions {
940
1000
  * Moves an icon along the walk, or along one segment, inset by the icon's footprint so it stays
941
1001
  * inside the mark. Its end state is the icon resting at the end. An icon given by name is looked up
942
1002
  * in `ctx.icons` when it runs, and an unknown name throws there.
1003
+ *
1004
+ * Across a gap in the walk it jumps: it's inset from each part's ends as from the walk's, and goes
1005
+ * from one part to the next at once, so it's never drawn over a gap. The trip's time counts only the
1006
+ * parts it's drawn on, and a part shorter than the icon is skipped, unless it's the last: the icon
1007
+ * rests there, at the last value.
943
1008
  */
944
1009
  declare function travel(icon: Icon | string, options?: TravelOptions): GeometryEffect;
945
1010
 
@@ -992,6 +1057,63 @@ interface PulseOptions {
992
1057
  */
993
1058
  declare function pulse(options?: PulseOptions): GeometryEffect;
994
1059
 
1060
+ 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;
1069
+ }
1070
+ /**
1071
+ * Draws an overlay stroke along the mark's walk, from its start to its end, eased in and out over
1072
+ * `duration`, with round caps. On a stack it runs the whole walk, across every segment. A walk under
1073
+ * 0.5 px (a point) draws nothing, and a run on one finishes at once.
1074
+ *
1075
+ * The stroke stays, and follows `onChange`, so it keeps to the mark through a transition or a
1076
+ * resize. Its end state is the whole stroke, so reduced motion shows what a full run ends with.
1077
+ */
1078
+ declare function trace(options?: TraceOptions): GeometryEffect;
1079
+
1080
+ 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;
1087
+ }
1088
+ /**
1089
+ * The change since the last update, `value(data) − value(data.previous)`, as text past the end of the
1090
+ * mark: 10 px past the end of its walk, or 6 px past the farthest of its own labels its heading meets.
1091
+ * It rises 8 px into place and fades in over 400 ms base, then stays until the next update clears it,
1092
+ * following the mark as it moves. Its end state is the text in place, so reduced motion shows the
1093
+ * change. With no `previous`, or no change, it draws nothing.
1094
+ *
1095
+ * The text is in the overlay, which screen readers don't read: a page that relies on it says the same
1096
+ * in its table or its announcement.
1097
+ */
1098
+ declare function delta<D = unknown>(options?: DeltaOptions<D>): DataEffect<D>;
1099
+
1100
+ interface LabelOptions {
1101
+ /** A theme token or any CSS colour. Default "text", never the series' colour. */
1102
+ readonly color?: Color;
1103
+ }
1104
+ /**
1105
+ * Text from `text(data, mark)` past the end of the mark: 10 px past the end of its walk, or 6 px
1106
+ * past the farthest of its own labels its heading meets. `text` returns the words, or undefined or
1107
+ * "" for none. It's typed by the rows it reads, so a label written for one kind of row is a type
1108
+ * error on a chart of another.
1109
+ *
1110
+ * It rises 8 px into place and fades in over 400 ms base, as delta does, then follows every change,
1111
+ * its text worked out again from the new data. Its end state is the text in place. The text is in
1112
+ * the overlay, which screen readers don't read: a page that relies on it says the same in its table
1113
+ * or its announcement.
1114
+ */
1115
+ declare function label<D = unknown>(text: (data: MarkData<D>, mark: MarkGeometry) => string | undefined, options?: LabelOptions): DataEffect<D>;
1116
+
995
1117
  interface ThresholdOptions {
996
1118
  /**
997
1119
  * The reference: a constant, or the name of a related series ("xg"), which goes in `needs.related`
@@ -1015,6 +1137,8 @@ interface ThresholdOptions {
1015
1137
  * samples, where it bends), so they're exact where the walk is straight between samples: our lines,
1016
1138
  * and a host polyline sampled at its vertices. Along a curve they're approximate; denser samples
1017
1139
  * narrow the error.
1140
+ * - **Gaps.** Nothing is interpolated across a sample with `gapBefore`, the mark's or the reference's:
1141
+ * where either has no value, nothing is coloured. `slice()` leaves the mark's own gaps out too.
1018
1142
  *
1019
1143
  * It draws at once, with no animation, and redraws on every `onChange`, so it follows a line as it's
1020
1144
  * revealed. Its end state is the same picture, so the colour shows with motion off.
@@ -1142,12 +1266,13 @@ declare function defineIcon(spec: IconSpec): Icon;
1142
1266
  type SvgIconSpec = Omit<IconSpec, "shapes" | "box">;
1143
1267
  /**
1144
1268
  * Converts `path`, `circle`, `rect`, `ellipse`, `line`, `polyline` and `polygon` elements into shapes,
1145
- * with their fill, stroke, stroke width, line caps and joins (as attributes or in `style`, inherited
1146
- * from `<g>`) and transforms applied. `currentColor` becomes the theme's `text` colour, so an icon
1147
- * from an icon set follows the chart's theme. Everything else is dropped: scripts, event handlers,
1148
- * `<use>`, text, images, and what's inside `<defs>`, `<clipPath>` and the like. Gradients, patterns,
1149
- * opacity, fill rules and CSS classes aren't kept; a shape painted with a gradient or pattern falls
1150
- * back to its inherited colour.
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.
1151
1276
  */
1152
1277
  declare function iconFromSvg(markup: string, spec: SvgIconSpec): Icon;
1153
1278
 
@@ -1174,7 +1299,7 @@ declare function registerIcons(icons: readonly Icon[]): void;
1174
1299
  */
1175
1300
  declare function configure(options: StyleOptions): void;
1176
1301
 
1177
- declare const VERSION = "0.1.0";
1302
+ declare const VERSION = "0.3.0";
1178
1303
 
1179
1304
  /**
1180
1305
  * A bar chart in `target` (an element or a selector). The axis whose values aren't numbers is the
@@ -1221,5 +1346,5 @@ declare function fromVegaView<D = Record<string, unknown>>(view: VegaViewLike, o
1221
1346
  */
1222
1347
  declare function motionSwitch(target: string | Element, motion?: Motion, options?: MotionSwitchOptions): MotionSwitch;
1223
1348
 
1224
- export { AnyMarkEffect, Color, Combined, DataEffect, Easing, EffectContext, GeometryEffect, Icon, MarkData, MarkEffect, MarkGeometry, Matrix, Motion, MotionEnv, MotionMode, Point, Sample, Timing, TransitionEffect, TweenResult, VERSION, animated, barChart, chartSwitch, colorAssignment, configure, defineDataEffect, defineEffect, defineIcon, describe, donutChart, expressive, flash, fromVegaView, gaits, iconFromSvg, icons, interpolateNumber, interpolatePoint, interpolateRecord, lineChart, matrix, morph, motionSwitch, offset, only, parallel, playButton, playback, pulse, registerIcon, registerIcons, registerPreset, samplesAlong, sequence, stagger, threshold, travel, wiggle };
1225
- 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, DonutChart, DonutChartOptions, EffectOption, EffectSlot, EffectSlots, ExpressiveOptions, FlashOptions, Gait, GaitName, GaitPose, GaitState, GeometryEffectSpec, HostMark, IconSpec, Interpolator, KeyOfType, LegendEntry, LegendOptions, LineChart, LineChartOptions, LineSpec, 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, TravelOptions, VegaAttachment, VegaItem, VegaMark, VegaOptions, VegaSample, VegaViewLike, WiggleOptions };
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 };
package/dist/index.d.ts CHANGED
@@ -1,7 +1,7 @@
1
- import { T as Timing, E as Easing, a as TweenResult, M as MotionEnv, b as MarkEffect, S as Sample, c as MarkData, d as Motion, e as MotionMode, f as TransitionEffect, G as GeometryEffect, D as DataEffect, A as AnyMarkEffect, C as Combined, g as EffectContext } from './effect-OcyvtfZi.js';
2
- export { h as Clock, F as FrameSource, i as ManualClock, j as MotionOptions, k as MotionView, R as ReducedMotionSource, l as ScalingOverrides, m as ScalingRule, n as ScalingTable, o as TransitionContext, p as Tween, q as TweenOptions, r as createClock, s as createMotion, t as defaultClock, u as defaultScaling, v as easeInOutCubic, w as easeOutCubic, x as linear, y as manualClock, z as mediaReducedMotion, B as motion, H as scaleDuration, I as tween } from './effect-OcyvtfZi.js';
3
- import { P as Point, M as MarkGeometry, a as Matrix, C as Color, I as Icon } from './drawing-Du6DAgrW.js';
4
- export { b as IconHandle, c as IconShape, d as IconSource, L as Layer, e as MarkHandle, f as MarkStyle, O as Outline, g as Paint, h as PathHandle, R as Rect, T as TextHandle, i as TextStyle } from './drawing-Du6DAgrW.js';
1
+ import { d as Timing, e as Easing, f as TweenResult, g as MotionEnv, h as MarkEffect, i as Sample, M as MarkData, a as Motion, c as MotionMode, T as TransitionEffect, G as GeometryEffect, D as DataEffect, A as AnyMarkEffect, C as Combined, E as EffectContext } from './effect-Bu3MHHeg.js';
2
+ export { j as Clock, F as FrameSource, b as ManualClock, k as MotionOptions, l as MotionView, R as ReducedMotionSource, S as ScalingOverrides, m as ScalingRule, n as ScalingTable, o as TransitionContext, p as Tween, q as TweenOptions, r as createClock, s as createMotion, t as defaultClock, u as defaultScaling, v as easeInOutCubic, w as easeOutCubic, x as linear, y as manualClock, z as mediaReducedMotion, B as motion, H as scaleDuration, I as tween } from './effect-Bu3MHHeg.js';
3
+ import { e as Point, R as Rect, M as MarkGeometry, a as Matrix, C as Color, I as Icon } from './drawing-CdTgixMY.js';
4
+ export { f as IconHandle, g as IconShape, d as IconSource, L as Layer, c as MarkHandle, b as MarkStyle, O as Outline, P as Paint, h as PathHandle, i as TextHandle, T as TextStyle } from './drawing-CdTgixMY.js';
5
5
 
6
6
  /** Builds a function that blends `from` into `to` as t goes from 0 to 1. */
7
7
  type Interpolator<T> = (from: T, to: T) => (t: number) => T;
@@ -124,6 +124,8 @@ interface ArcSpec {
124
124
  /** Radians, 0 at 12 o'clock, clockwise: the d3.pie() convention. end < start walks anticlockwise. */
125
125
  readonly start: number;
126
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[];
127
129
  }
128
130
  /**
129
131
  * The walk runs along the mid-radius arc from the start angle to the end angle, so for a slice
@@ -160,6 +162,8 @@ interface BarSpec {
160
162
  * before is shorter. Default 0.
161
163
  */
162
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[];
163
167
  }
164
168
  /**
165
169
  * The walk runs along the centre line from the middle of the baseline edge to the middle of the
@@ -172,10 +176,22 @@ interface LineSpec {
172
176
  readonly series?: string;
173
177
  /** At least one point, in chart px. */
174
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[];
175
185
  /** Stroke width in px. Default 1, SVG's default. */
176
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[];
177
189
  }
178
- /** The walk is the line itself, first point to last. Its outline is open: the stroke. */
190
+ /**
191
+ * The walk is the line itself, first point to last, running straight across each break. Its outline
192
+ * is open: the stroke, with the breaks left out. A break between two points in the same place leaves
193
+ * no gap, since there's nothing between them to leave out.
194
+ */
179
195
  declare function describeLine(spec: LineSpec): MarkGeometry;
180
196
 
181
197
  interface PointSpec {
@@ -185,6 +201,8 @@ interface PointSpec {
185
201
  readonly y: number;
186
202
  /** Radius in px. */
187
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[];
188
206
  }
189
207
  /**
190
208
  * Length 0, with start = end = centre, so travel does nothing while wiggle, pulse and flash still
@@ -228,7 +246,9 @@ interface SamplePoint {
228
246
  /**
229
247
  * Projects each point onto the nearest point of the mark's walk and returns the samples in `t` order
230
248
  * (points at the same `t` keep their order). A point on the walk, such as a vertex of the polyline it
231
- * drew, lands exactly where it is. Throws a RangeError on a point whose x, y or value isn't finite.
249
+ * drew, lands exactly where it is. Where the mark has gaps, the first sample past each gap's middle
250
+ * has `gapBefore`, so a data effect doesn't join it to the one before. Throws a RangeError on a point
251
+ * whose x, y or value isn't finite.
232
252
  */
233
253
  declare function samplesAlong(mark: MarkGeometry, points: readonly SamplePoint[]): Sample[];
234
254
 
@@ -267,8 +287,9 @@ interface MarkEvents<D> {
267
287
  readonly from: MarkGeometry;
268
288
  };
269
289
  exit: MarkEvent<D>;
290
+ /** `source` "linked": hovered by `link()`, because a mark in another chart with its linking value was. */
270
291
  hover: MarkEvent<D> & {
271
- readonly source: "pointer" | "keyboard" | "touch";
292
+ readonly source: "pointer" | "keyboard" | "touch" | "linked";
272
293
  readonly segment?: string;
273
294
  };
274
295
  leave: MarkEvent<D>;
@@ -438,6 +459,12 @@ interface BarChartOptions<D> extends ChartOptions<D> {
438
459
  * colour in both; the legend lists the categories. It needs one series: on a stack it throws.
439
460
  */
440
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;
441
468
  }
442
469
  /** 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. */
443
470
  interface SliceSummary extends MarkSummary {
@@ -494,9 +521,11 @@ interface LineChartOptions<D> extends ChartOptions<D> {
494
521
  readonly xFormat?: (x: Date | number) => string;
495
522
  /**
496
523
  * The numeric fields drawn as lines, in order. Each is a line mark keyed by its field, plus a point
497
- * mark per row keyed "<series>@<row key>" ("goals@12"). A missing or non-finite value throws.
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.
498
527
  */
499
- readonly series: readonly NumericKey<D>[];
528
+ readonly series: readonly KeyOfType<D, number | null | undefined>[];
500
529
  /**
501
530
  * The label at each line's end, in the right margin: by default its value in `format` with its
502
531
  * series' label ("52 goals"), counting between values while a change or a reveal plays. `false`
@@ -763,6 +792,37 @@ interface VegaAttachment<D> extends Omit<Attachment<D>, "refresh"> {
763
792
  refresh(): void;
764
793
  }
765
794
 
795
+ /** What a link takes: a chart (barChart, donutChart, lineChart) or an attachment (expressive, fromVegaView), with rows D. */
796
+ interface LinkSource<D> {
797
+ on(type: "hover", listener: (event: MarkEvents<D>["hover"]) => void): () => void;
798
+ marks(): readonly MarkGeometry[];
799
+ }
800
+ /** The rows of the sources in S: each chart's and attachment's, as a union. */
801
+ type RowsOf<S> = S extends LinkSource<infer D> ? D : never;
802
+ 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;
812
+ }
813
+ 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;
816
+ }
817
+ /**
818
+ * Links hover across `sources`: when one is hovered by the pointer, touch or the keyboard, every other
819
+ * hovers its targets with that linking value (a line chart its x, a bar chart its bar), as `source:
820
+ * "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.
823
+ */
824
+ declare function link<S extends LinkSource<unknown>>(sources: readonly S[], options?: LinkOptions<RowsOf<S>>): Link;
825
+
766
826
  /**
767
827
  * What a chart switch uses of each view's chart. A reference chart's handle has all of it: its
768
828
  * `<svg>` (which takes `ec-morphing` while its marks morph in the switch's overlay), its marks and
@@ -940,6 +1000,11 @@ interface TravelOptions {
940
1000
  * Moves an icon along the walk, or along one segment, inset by the icon's footprint so it stays
941
1001
  * inside the mark. Its end state is the icon resting at the end. An icon given by name is looked up
942
1002
  * in `ctx.icons` when it runs, and an unknown name throws there.
1003
+ *
1004
+ * Across a gap in the walk it jumps: it's inset from each part's ends as from the walk's, and goes
1005
+ * from one part to the next at once, so it's never drawn over a gap. The trip's time counts only the
1006
+ * parts it's drawn on, and a part shorter than the icon is skipped, unless it's the last: the icon
1007
+ * rests there, at the last value.
943
1008
  */
944
1009
  declare function travel(icon: Icon | string, options?: TravelOptions): GeometryEffect;
945
1010
 
@@ -992,6 +1057,63 @@ interface PulseOptions {
992
1057
  */
993
1058
  declare function pulse(options?: PulseOptions): GeometryEffect;
994
1059
 
1060
+ 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;
1069
+ }
1070
+ /**
1071
+ * Draws an overlay stroke along the mark's walk, from its start to its end, eased in and out over
1072
+ * `duration`, with round caps. On a stack it runs the whole walk, across every segment. A walk under
1073
+ * 0.5 px (a point) draws nothing, and a run on one finishes at once.
1074
+ *
1075
+ * The stroke stays, and follows `onChange`, so it keeps to the mark through a transition or a
1076
+ * resize. Its end state is the whole stroke, so reduced motion shows what a full run ends with.
1077
+ */
1078
+ declare function trace(options?: TraceOptions): GeometryEffect;
1079
+
1080
+ 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;
1087
+ }
1088
+ /**
1089
+ * The change since the last update, `value(data) − value(data.previous)`, as text past the end of the
1090
+ * mark: 10 px past the end of its walk, or 6 px past the farthest of its own labels its heading meets.
1091
+ * It rises 8 px into place and fades in over 400 ms base, then stays until the next update clears it,
1092
+ * following the mark as it moves. Its end state is the text in place, so reduced motion shows the
1093
+ * change. With no `previous`, or no change, it draws nothing.
1094
+ *
1095
+ * The text is in the overlay, which screen readers don't read: a page that relies on it says the same
1096
+ * in its table or its announcement.
1097
+ */
1098
+ declare function delta<D = unknown>(options?: DeltaOptions<D>): DataEffect<D>;
1099
+
1100
+ interface LabelOptions {
1101
+ /** A theme token or any CSS colour. Default "text", never the series' colour. */
1102
+ readonly color?: Color;
1103
+ }
1104
+ /**
1105
+ * Text from `text(data, mark)` past the end of the mark: 10 px past the end of its walk, or 6 px
1106
+ * past the farthest of its own labels its heading meets. `text` returns the words, or undefined or
1107
+ * "" for none. It's typed by the rows it reads, so a label written for one kind of row is a type
1108
+ * error on a chart of another.
1109
+ *
1110
+ * It rises 8 px into place and fades in over 400 ms base, as delta does, then follows every change,
1111
+ * its text worked out again from the new data. Its end state is the text in place. The text is in
1112
+ * the overlay, which screen readers don't read: a page that relies on it says the same in its table
1113
+ * or its announcement.
1114
+ */
1115
+ declare function label<D = unknown>(text: (data: MarkData<D>, mark: MarkGeometry) => string | undefined, options?: LabelOptions): DataEffect<D>;
1116
+
995
1117
  interface ThresholdOptions {
996
1118
  /**
997
1119
  * The reference: a constant, or the name of a related series ("xg"), which goes in `needs.related`
@@ -1015,6 +1137,8 @@ interface ThresholdOptions {
1015
1137
  * samples, where it bends), so they're exact where the walk is straight between samples: our lines,
1016
1138
  * and a host polyline sampled at its vertices. Along a curve they're approximate; denser samples
1017
1139
  * narrow the error.
1140
+ * - **Gaps.** Nothing is interpolated across a sample with `gapBefore`, the mark's or the reference's:
1141
+ * where either has no value, nothing is coloured. `slice()` leaves the mark's own gaps out too.
1018
1142
  *
1019
1143
  * It draws at once, with no animation, and redraws on every `onChange`, so it follows a line as it's
1020
1144
  * revealed. Its end state is the same picture, so the colour shows with motion off.
@@ -1142,12 +1266,13 @@ declare function defineIcon(spec: IconSpec): Icon;
1142
1266
  type SvgIconSpec = Omit<IconSpec, "shapes" | "box">;
1143
1267
  /**
1144
1268
  * Converts `path`, `circle`, `rect`, `ellipse`, `line`, `polyline` and `polygon` elements into shapes,
1145
- * with their fill, stroke, stroke width, line caps and joins (as attributes or in `style`, inherited
1146
- * from `<g>`) and transforms applied. `currentColor` becomes the theme's `text` colour, so an icon
1147
- * from an icon set follows the chart's theme. Everything else is dropped: scripts, event handlers,
1148
- * `<use>`, text, images, and what's inside `<defs>`, `<clipPath>` and the like. Gradients, patterns,
1149
- * opacity, fill rules and CSS classes aren't kept; a shape painted with a gradient or pattern falls
1150
- * back to its inherited colour.
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.
1151
1276
  */
1152
1277
  declare function iconFromSvg(markup: string, spec: SvgIconSpec): Icon;
1153
1278
 
@@ -1174,7 +1299,7 @@ declare function registerIcons(icons: readonly Icon[]): void;
1174
1299
  */
1175
1300
  declare function configure(options: StyleOptions): void;
1176
1301
 
1177
- declare const VERSION = "0.1.0";
1302
+ declare const VERSION = "0.3.0";
1178
1303
 
1179
1304
  /**
1180
1305
  * A bar chart in `target` (an element or a selector). The axis whose values aren't numbers is the
@@ -1221,5 +1346,5 @@ declare function fromVegaView<D = Record<string, unknown>>(view: VegaViewLike, o
1221
1346
  */
1222
1347
  declare function motionSwitch(target: string | Element, motion?: Motion, options?: MotionSwitchOptions): MotionSwitch;
1223
1348
 
1224
- export { AnyMarkEffect, Color, Combined, DataEffect, Easing, EffectContext, GeometryEffect, Icon, MarkData, MarkEffect, MarkGeometry, Matrix, Motion, MotionEnv, MotionMode, Point, Sample, Timing, TransitionEffect, TweenResult, VERSION, animated, barChart, chartSwitch, colorAssignment, configure, defineDataEffect, defineEffect, defineIcon, describe, donutChart, expressive, flash, fromVegaView, gaits, iconFromSvg, icons, interpolateNumber, interpolatePoint, interpolateRecord, lineChart, matrix, morph, motionSwitch, offset, only, parallel, playButton, playback, pulse, registerIcon, registerIcons, registerPreset, samplesAlong, sequence, stagger, threshold, travel, wiggle };
1225
- 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, DonutChart, DonutChartOptions, EffectOption, EffectSlot, EffectSlots, ExpressiveOptions, FlashOptions, Gait, GaitName, GaitPose, GaitState, GeometryEffectSpec, HostMark, IconSpec, Interpolator, KeyOfType, LegendEntry, LegendOptions, LineChart, LineChartOptions, LineSpec, 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, TravelOptions, VegaAttachment, VegaItem, VegaMark, VegaOptions, VegaSample, VegaViewLike, WiggleOptions };
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 };