expressive-charts 0.1.0 → 0.2.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,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 { T as Timing, E as Easing, a as TweenResult, M as MotionEnv, b as MarkEffect, S as Sample, c as MarkData, d as Motion, e as MotionMode, f as TransitionEffect, G as GeometryEffect, D as DataEffect, A as AnyMarkEffect, C as Combined, g as EffectContext } from './effect-CcGdU41j.cjs';
2
+ export { h as Clock, F as FrameSource, i as ManualClock, j as MotionOptions, k as MotionView, R as ReducedMotionSource, l as ScalingOverrides, m as ScalingRule, n as ScalingTable, o as TransitionContext, p as Tween, q as TweenOptions, r as createClock, s as createMotion, t as defaultClock, u as defaultScaling, v as easeInOutCubic, w as easeOutCubic, x as linear, y as manualClock, z as mediaReducedMotion, B as motion, H as scaleDuration, I as tween } from './effect-CcGdU41j.cjs';
3
+ import { P as Point, R as Rect, M as MarkGeometry, a as Matrix, C as Color, I as Icon } from './drawing-DWZIXIeR.cjs';
4
+ export { b as IconHandle, c as IconShape, d as IconSource, L as Layer, e as MarkHandle, f as MarkStyle, O as Outline, g as Paint, h as PathHandle, T as TextHandle, i as TextStyle } from './drawing-DWZIXIeR.cjs';
5
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
@@ -174,6 +178,8 @@ interface LineSpec {
174
178
  readonly points: readonly Point[];
175
179
  /** Stroke width in px. Default 1, SVG's default. */
176
180
  readonly width?: number;
181
+ /** The boxes of the text drawn for the mark, in the same px: passed through as `labelBounds`. */
182
+ readonly labelBounds?: readonly Rect[];
177
183
  }
178
184
  /** The walk is the line itself, first point to last. Its outline is open: the stroke. */
179
185
  declare function describeLine(spec: LineSpec): MarkGeometry;
@@ -185,6 +191,8 @@ interface PointSpec {
185
191
  readonly y: number;
186
192
  /** Radius in px. */
187
193
  readonly r: number;
194
+ /** The boxes of the text drawn for the mark, in the same px: passed through as `labelBounds`. */
195
+ readonly labelBounds?: readonly Rect[];
188
196
  }
189
197
  /**
190
198
  * Length 0, with start = end = centre, so travel does nothing while wiggle, pulse and flash still
@@ -267,8 +275,9 @@ interface MarkEvents<D> {
267
275
  readonly from: MarkGeometry;
268
276
  };
269
277
  exit: MarkEvent<D>;
278
+ /** `source` "linked": hovered by `link()`, because a mark in another chart with its linking value was. */
270
279
  hover: MarkEvent<D> & {
271
- readonly source: "pointer" | "keyboard" | "touch";
280
+ readonly source: "pointer" | "keyboard" | "touch" | "linked";
272
281
  readonly segment?: string;
273
282
  };
274
283
  leave: MarkEvent<D>;
@@ -763,6 +772,37 @@ interface VegaAttachment<D> extends Omit<Attachment<D>, "refresh"> {
763
772
  refresh(): void;
764
773
  }
765
774
 
775
+ /** What a link takes: a chart (barChart, donutChart, lineChart) or an attachment (expressive, fromVegaView), with rows D. */
776
+ interface LinkSource<D> {
777
+ on(type: "hover", listener: (event: MarkEvents<D>["hover"]) => void): () => void;
778
+ marks(): readonly MarkGeometry[];
779
+ }
780
+ /** The rows of the sources in S: each chart's and attachment's, as a union. */
781
+ type RowsOf<S> = S extends LinkSource<infer D> ? D : never;
782
+ interface LinkOptions<D> {
783
+ /**
784
+ * A mark's linking value, given the mark and its data as a hover event has them. Default: its last
785
+ * sample's `at` if it has one (a line point's x), else its key (a bar's or a slice's category).
786
+ * Values are compared as strings, a Date by its ISO string, as keys are. Undefined or null links
787
+ * nothing, and so does a throw (reported).
788
+ */
789
+ readonly by?: (event: Pick<MarkEvent<D>, "mark" | "data">) => unknown;
790
+ /** Whether linked marks play their chart's hover effect. Default true; false keeps them to emphasis and dimming. */
791
+ readonly effects?: boolean;
792
+ }
793
+ interface Link {
794
+ /** Ends the link: linked hovers end, and each source can be linked again. The sources' own hovers go on. */
795
+ destroy(): void;
796
+ }
797
+ /**
798
+ * Links hover across `sources`: when one is hovered by the pointer, touch or the keyboard, every other
799
+ * hovers its targets with that linking value (a line chart its x, a bar chart its bar), as `source:
800
+ * "linked"`, and leaves them when it leaves. The newest hover anywhere in the link is the one shown.
801
+ * Throws a TypeError, linking nothing, on a source that isn't a chart or an attachment, or one that's
802
+ * in a link already. A destroyed source drops out.
803
+ */
804
+ declare function link<S extends LinkSource<unknown>>(sources: readonly S[], options?: LinkOptions<RowsOf<S>>): Link;
805
+
766
806
  /**
767
807
  * What a chart switch uses of each view's chart. A reference chart's handle has all of it: its
768
808
  * `<svg>` (which takes `ec-morphing` while its marks morph in the switch's overlay), its marks and
@@ -992,6 +1032,63 @@ interface PulseOptions {
992
1032
  */
993
1033
  declare function pulse(options?: PulseOptions): GeometryEffect;
994
1034
 
1035
+ interface TraceOptions {
1036
+ /** A theme token or any CSS colour. Default "mark", the mark's own colour (a stack's first segment's). */
1037
+ readonly color?: Color;
1038
+ /** The stroke's width, px. Default 3. */
1039
+ readonly width?: number;
1040
+ /** From 0 to 1. Default 0.5. */
1041
+ readonly opacity?: number;
1042
+ /** Base ms to draw the stroke, before the motion mode scales it, with effect timing. Default 500. */
1043
+ readonly duration?: number;
1044
+ }
1045
+ /**
1046
+ * Draws an overlay stroke along the mark's walk, from its start to its end, eased in and out over
1047
+ * `duration`, with round caps. On a stack it runs the whole walk, across every segment. A walk under
1048
+ * 0.5 px (a point) draws nothing, and a run on one finishes at once.
1049
+ *
1050
+ * The stroke stays, and follows `onChange`, so it keeps to the mark through a transition or a
1051
+ * resize. Its end state is the whole stroke, so reduced motion shows what a full run ends with.
1052
+ */
1053
+ declare function trace(options?: TraceOptions): GeometryEffect;
1054
+
1055
+ interface DeltaOptions<D = unknown> {
1056
+ /** The mark's value. Default: its last sample's, so a bar's total, a line's value at its revealed end, a slice's share. */
1057
+ readonly value?: (data: MarkData<D>) => number;
1058
+ /** Words the change. Default: the page's locale, with its sign and at most two decimals ("+2", "-0.3"). */
1059
+ readonly format?: (change: number) => string;
1060
+ /** A theme token or any CSS colour. Default "text", never the series' colour. */
1061
+ readonly color?: Color;
1062
+ }
1063
+ /**
1064
+ * The change since the last update, `value(data) − value(data.previous)`, as text past the end of the
1065
+ * mark: 10 px past the end of its walk, or 6 px past the farthest of its own labels its heading meets.
1066
+ * It rises 8 px into place and fades in over 400 ms base, then stays until the next update clears it,
1067
+ * following the mark as it moves. Its end state is the text in place, so reduced motion shows the
1068
+ * change. With no `previous`, or no change, it draws nothing.
1069
+ *
1070
+ * The text is in the overlay, which screen readers don't read: a page that relies on it says the same
1071
+ * in its table or its announcement.
1072
+ */
1073
+ declare function delta<D = unknown>(options?: DeltaOptions<D>): DataEffect<D>;
1074
+
1075
+ interface LabelOptions {
1076
+ /** A theme token or any CSS colour. Default "text", never the series' colour. */
1077
+ readonly color?: Color;
1078
+ }
1079
+ /**
1080
+ * Text from `text(data, mark)` past the end of the mark: 10 px past the end of its walk, or 6 px
1081
+ * past the farthest of its own labels its heading meets. `text` returns the words, or undefined or
1082
+ * "" for none. It's typed by the rows it reads, so a label written for one kind of row is a type
1083
+ * error on a chart of another.
1084
+ *
1085
+ * It rises 8 px into place and fades in over 400 ms base, as delta does, then follows every change,
1086
+ * its text worked out again from the new data. Its end state is the text in place. The text is in
1087
+ * the overlay, which screen readers don't read: a page that relies on it says the same in its table
1088
+ * or its announcement.
1089
+ */
1090
+ declare function label<D = unknown>(text: (data: MarkData<D>, mark: MarkGeometry) => string | undefined, options?: LabelOptions): DataEffect<D>;
1091
+
995
1092
  interface ThresholdOptions {
996
1093
  /**
997
1094
  * The reference: a constant, or the name of a related series ("xg"), which goes in `needs.related`
@@ -1174,7 +1271,7 @@ declare function registerIcons(icons: readonly Icon[]): void;
1174
1271
  */
1175
1272
  declare function configure(options: StyleOptions): void;
1176
1273
 
1177
- declare const VERSION = "0.1.0";
1274
+ declare const VERSION = "0.2.0";
1178
1275
 
1179
1276
  /**
1180
1277
  * A bar chart in `target` (an element or a selector). The axis whose values aren't numbers is the
@@ -1221,5 +1318,5 @@ declare function fromVegaView<D = Record<string, unknown>>(view: VegaViewLike, o
1221
1318
  */
1222
1319
  declare function motionSwitch(target: string | Element, motion?: Motion, options?: MotionSwitchOptions): MotionSwitch;
1223
1320
 
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 };
1321
+ export { AnyMarkEffect, Color, Combined, DataEffect, Easing, EffectContext, GeometryEffect, Icon, MarkData, MarkEffect, MarkGeometry, Matrix, Motion, MotionEnv, MotionMode, Point, Rect, Sample, Timing, TransitionEffect, TweenResult, VERSION, animated, barChart, chartSwitch, colorAssignment, configure, defineDataEffect, defineEffect, defineIcon, delta, describe, donutChart, expressive, flash, fromVegaView, gaits, iconFromSvg, icons, interpolateNumber, interpolatePoint, interpolateRecord, label, lineChart, link, matrix, morph, motionSwitch, offset, only, parallel, playButton, playback, pulse, registerIcon, registerIcons, registerPreset, samplesAlong, sequence, stagger, threshold, trace, travel, wiggle };
1322
+ export type { Accessor, AnimateOptions, Animated, AnimatedOptions, ArcSpec, Attachment, BarChart, BarChartOptions, BarSegmentSpec, BarSpec, Baseline, Chart, ChartChange, ChartLabel, ChartOptions, ChartSwitch, ChartSwitchOptions, ChartSwitchView, ChartSwitchViewFactory, ChartSwitchViewName, ChartSwitchViews, ColorAssignment, DataEffectSpec, DeltaOptions, DonutChart, DonutChartOptions, EffectOption, EffectSlot, EffectSlots, ExpressiveOptions, FlashOptions, Gait, GaitName, GaitPose, GaitState, GeometryEffectSpec, HostMark, IconSpec, Interpolator, KeyOfType, LabelOptions, LegendEntry, LegendOptions, LineChart, LineChartOptions, LineSpec, Link, LinkOptions, LinkSource, MarkEvent, MarkEvents, MarkSource, MarkSummary, MorphAlign, MorphOptions, MotionSwitch, MotionSwitchOptions, NumericKey, PlayButton, PlayButtonOptions, Playback, PlaybackEvent, PlaybackOptions, PointSpec, PresetName, PulseOptions, SamplePoint, SeekOptions, SliceSummary, StaggerOptions, StepOptions, StyleOptions, SvgIconSpec, TableColumn, TableOptions, ThresholdOptions, TraceOptions, TravelOptions, VegaAttachment, VegaItem, VegaMark, VegaOptions, VegaSample, VegaViewLike, WiggleOptions };
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 { 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-CZUckY0l.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-CZUckY0l.js';
3
+ import { P as Point, R as Rect, M as MarkGeometry, a as Matrix, C as Color, I as Icon } from './drawing-DWZIXIeR.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, T as TextHandle, i as TextStyle } from './drawing-DWZIXIeR.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
@@ -174,6 +178,8 @@ interface LineSpec {
174
178
  readonly points: readonly Point[];
175
179
  /** Stroke width in px. Default 1, SVG's default. */
176
180
  readonly width?: number;
181
+ /** The boxes of the text drawn for the mark, in the same px: passed through as `labelBounds`. */
182
+ readonly labelBounds?: readonly Rect[];
177
183
  }
178
184
  /** The walk is the line itself, first point to last. Its outline is open: the stroke. */
179
185
  declare function describeLine(spec: LineSpec): MarkGeometry;
@@ -185,6 +191,8 @@ interface PointSpec {
185
191
  readonly y: number;
186
192
  /** Radius in px. */
187
193
  readonly r: number;
194
+ /** The boxes of the text drawn for the mark, in the same px: passed through as `labelBounds`. */
195
+ readonly labelBounds?: readonly Rect[];
188
196
  }
189
197
  /**
190
198
  * Length 0, with start = end = centre, so travel does nothing while wiggle, pulse and flash still
@@ -267,8 +275,9 @@ interface MarkEvents<D> {
267
275
  readonly from: MarkGeometry;
268
276
  };
269
277
  exit: MarkEvent<D>;
278
+ /** `source` "linked": hovered by `link()`, because a mark in another chart with its linking value was. */
270
279
  hover: MarkEvent<D> & {
271
- readonly source: "pointer" | "keyboard" | "touch";
280
+ readonly source: "pointer" | "keyboard" | "touch" | "linked";
272
281
  readonly segment?: string;
273
282
  };
274
283
  leave: MarkEvent<D>;
@@ -763,6 +772,37 @@ interface VegaAttachment<D> extends Omit<Attachment<D>, "refresh"> {
763
772
  refresh(): void;
764
773
  }
765
774
 
775
+ /** What a link takes: a chart (barChart, donutChart, lineChart) or an attachment (expressive, fromVegaView), with rows D. */
776
+ interface LinkSource<D> {
777
+ on(type: "hover", listener: (event: MarkEvents<D>["hover"]) => void): () => void;
778
+ marks(): readonly MarkGeometry[];
779
+ }
780
+ /** The rows of the sources in S: each chart's and attachment's, as a union. */
781
+ type RowsOf<S> = S extends LinkSource<infer D> ? D : never;
782
+ interface LinkOptions<D> {
783
+ /**
784
+ * A mark's linking value, given the mark and its data as a hover event has them. Default: its last
785
+ * sample's `at` if it has one (a line point's x), else its key (a bar's or a slice's category).
786
+ * Values are compared as strings, a Date by its ISO string, as keys are. Undefined or null links
787
+ * nothing, and so does a throw (reported).
788
+ */
789
+ readonly by?: (event: Pick<MarkEvent<D>, "mark" | "data">) => unknown;
790
+ /** Whether linked marks play their chart's hover effect. Default true; false keeps them to emphasis and dimming. */
791
+ readonly effects?: boolean;
792
+ }
793
+ interface Link {
794
+ /** Ends the link: linked hovers end, and each source can be linked again. The sources' own hovers go on. */
795
+ destroy(): void;
796
+ }
797
+ /**
798
+ * Links hover across `sources`: when one is hovered by the pointer, touch or the keyboard, every other
799
+ * hovers its targets with that linking value (a line chart its x, a bar chart its bar), as `source:
800
+ * "linked"`, and leaves them when it leaves. The newest hover anywhere in the link is the one shown.
801
+ * Throws a TypeError, linking nothing, on a source that isn't a chart or an attachment, or one that's
802
+ * in a link already. A destroyed source drops out.
803
+ */
804
+ declare function link<S extends LinkSource<unknown>>(sources: readonly S[], options?: LinkOptions<RowsOf<S>>): Link;
805
+
766
806
  /**
767
807
  * What a chart switch uses of each view's chart. A reference chart's handle has all of it: its
768
808
  * `<svg>` (which takes `ec-morphing` while its marks morph in the switch's overlay), its marks and
@@ -992,6 +1032,63 @@ interface PulseOptions {
992
1032
  */
993
1033
  declare function pulse(options?: PulseOptions): GeometryEffect;
994
1034
 
1035
+ interface TraceOptions {
1036
+ /** A theme token or any CSS colour. Default "mark", the mark's own colour (a stack's first segment's). */
1037
+ readonly color?: Color;
1038
+ /** The stroke's width, px. Default 3. */
1039
+ readonly width?: number;
1040
+ /** From 0 to 1. Default 0.5. */
1041
+ readonly opacity?: number;
1042
+ /** Base ms to draw the stroke, before the motion mode scales it, with effect timing. Default 500. */
1043
+ readonly duration?: number;
1044
+ }
1045
+ /**
1046
+ * Draws an overlay stroke along the mark's walk, from its start to its end, eased in and out over
1047
+ * `duration`, with round caps. On a stack it runs the whole walk, across every segment. A walk under
1048
+ * 0.5 px (a point) draws nothing, and a run on one finishes at once.
1049
+ *
1050
+ * The stroke stays, and follows `onChange`, so it keeps to the mark through a transition or a
1051
+ * resize. Its end state is the whole stroke, so reduced motion shows what a full run ends with.
1052
+ */
1053
+ declare function trace(options?: TraceOptions): GeometryEffect;
1054
+
1055
+ interface DeltaOptions<D = unknown> {
1056
+ /** The mark's value. Default: its last sample's, so a bar's total, a line's value at its revealed end, a slice's share. */
1057
+ readonly value?: (data: MarkData<D>) => number;
1058
+ /** Words the change. Default: the page's locale, with its sign and at most two decimals ("+2", "-0.3"). */
1059
+ readonly format?: (change: number) => string;
1060
+ /** A theme token or any CSS colour. Default "text", never the series' colour. */
1061
+ readonly color?: Color;
1062
+ }
1063
+ /**
1064
+ * The change since the last update, `value(data) − value(data.previous)`, as text past the end of the
1065
+ * mark: 10 px past the end of its walk, or 6 px past the farthest of its own labels its heading meets.
1066
+ * It rises 8 px into place and fades in over 400 ms base, then stays until the next update clears it,
1067
+ * following the mark as it moves. Its end state is the text in place, so reduced motion shows the
1068
+ * change. With no `previous`, or no change, it draws nothing.
1069
+ *
1070
+ * The text is in the overlay, which screen readers don't read: a page that relies on it says the same
1071
+ * in its table or its announcement.
1072
+ */
1073
+ declare function delta<D = unknown>(options?: DeltaOptions<D>): DataEffect<D>;
1074
+
1075
+ interface LabelOptions {
1076
+ /** A theme token or any CSS colour. Default "text", never the series' colour. */
1077
+ readonly color?: Color;
1078
+ }
1079
+ /**
1080
+ * Text from `text(data, mark)` past the end of the mark: 10 px past the end of its walk, or 6 px
1081
+ * past the farthest of its own labels its heading meets. `text` returns the words, or undefined or
1082
+ * "" for none. It's typed by the rows it reads, so a label written for one kind of row is a type
1083
+ * error on a chart of another.
1084
+ *
1085
+ * It rises 8 px into place and fades in over 400 ms base, as delta does, then follows every change,
1086
+ * its text worked out again from the new data. Its end state is the text in place. The text is in
1087
+ * the overlay, which screen readers don't read: a page that relies on it says the same in its table
1088
+ * or its announcement.
1089
+ */
1090
+ declare function label<D = unknown>(text: (data: MarkData<D>, mark: MarkGeometry) => string | undefined, options?: LabelOptions): DataEffect<D>;
1091
+
995
1092
  interface ThresholdOptions {
996
1093
  /**
997
1094
  * The reference: a constant, or the name of a related series ("xg"), which goes in `needs.related`
@@ -1174,7 +1271,7 @@ declare function registerIcons(icons: readonly Icon[]): void;
1174
1271
  */
1175
1272
  declare function configure(options: StyleOptions): void;
1176
1273
 
1177
- declare const VERSION = "0.1.0";
1274
+ declare const VERSION = "0.2.0";
1178
1275
 
1179
1276
  /**
1180
1277
  * A bar chart in `target` (an element or a selector). The axis whose values aren't numbers is the
@@ -1221,5 +1318,5 @@ declare function fromVegaView<D = Record<string, unknown>>(view: VegaViewLike, o
1221
1318
  */
1222
1319
  declare function motionSwitch(target: string | Element, motion?: Motion, options?: MotionSwitchOptions): MotionSwitch;
1223
1320
 
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 };
1321
+ export { AnyMarkEffect, Color, Combined, DataEffect, Easing, EffectContext, GeometryEffect, Icon, MarkData, MarkEffect, MarkGeometry, Matrix, Motion, MotionEnv, MotionMode, Point, Rect, Sample, Timing, TransitionEffect, TweenResult, VERSION, animated, barChart, chartSwitch, colorAssignment, configure, defineDataEffect, defineEffect, defineIcon, delta, describe, donutChart, expressive, flash, fromVegaView, gaits, iconFromSvg, icons, interpolateNumber, interpolatePoint, interpolateRecord, label, lineChart, link, matrix, morph, motionSwitch, offset, only, parallel, playButton, playback, pulse, registerIcon, registerIcons, registerPreset, samplesAlong, sequence, stagger, threshold, trace, travel, wiggle };
1322
+ export type { Accessor, AnimateOptions, Animated, AnimatedOptions, ArcSpec, Attachment, BarChart, BarChartOptions, BarSegmentSpec, BarSpec, Baseline, Chart, ChartChange, ChartLabel, ChartOptions, ChartSwitch, ChartSwitchOptions, ChartSwitchView, ChartSwitchViewFactory, ChartSwitchViewName, ChartSwitchViews, ColorAssignment, DataEffectSpec, DeltaOptions, DonutChart, DonutChartOptions, EffectOption, EffectSlot, EffectSlots, ExpressiveOptions, FlashOptions, Gait, GaitName, GaitPose, GaitState, GeometryEffectSpec, HostMark, IconSpec, Interpolator, KeyOfType, LabelOptions, LegendEntry, LegendOptions, LineChart, LineChartOptions, LineSpec, Link, LinkOptions, LinkSource, MarkEvent, MarkEvents, MarkSource, MarkSummary, MorphAlign, MorphOptions, MotionSwitch, MotionSwitchOptions, NumericKey, PlayButton, PlayButtonOptions, Playback, PlaybackEvent, PlaybackOptions, PointSpec, PresetName, PulseOptions, SamplePoint, SeekOptions, SliceSummary, StaggerOptions, StepOptions, StyleOptions, SvgIconSpec, TableColumn, TableOptions, ThresholdOptions, TraceOptions, TravelOptions, VegaAttachment, VegaItem, VegaMark, VegaOptions, VegaSample, VegaViewLike, WiggleOptions };