expressive-charts 0.2.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 +29 -0
  2. package/README.md +8 -8
  3. package/dist/{chunk-N5IF2RO2.js → chunk-7A7LXXT4.js} +6 -2
  4. package/dist/chunk-7A7LXXT4.js.map +1 -0
  5. package/dist/{chunk-V5IUTXRW.js → chunk-CJUQHEX6.js} +70 -23
  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-DWZIXIeR.d.cts → drawing-CdTgixMY.d.cts} +14 -2
  10. package/dist/{drawing-DWZIXIeR.d.ts → drawing-CdTgixMY.d.ts} +14 -2
  11. package/dist/{effect-CcGdU41j.d.cts → effect-Bu3MHHeg.d.ts} +4 -2
  12. package/dist/{effect-CZUckY0l.d.ts → effect-D4vmdYP4.d.cts} +4 -2
  13. package/dist/expressive-charts.css +6 -1
  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 +51 -46
  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 +839 -358
  22. package/dist/index.cjs.map +1 -1
  23. package/dist/index.d.cts +43 -15
  24. package/dist/index.d.ts +43 -15
  25. package/dist/index.js +700 -282
  26. package/dist/index.js.map +1 -1
  27. package/dist/testing.cjs +71 -37
  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-V5IUTXRW.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-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';
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;
@@ -176,12 +176,22 @@ interface LineSpec {
176
176
  readonly series?: string;
177
177
  /** At least one point, in chart px. */
178
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[];
179
185
  /** Stroke width in px. Default 1, SVG's default. */
180
186
  readonly width?: number;
181
187
  /** The boxes of the text drawn for the mark, in the same px: passed through as `labelBounds`. */
182
188
  readonly labelBounds?: readonly Rect[];
183
189
  }
184
- /** 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
+ */
185
195
  declare function describeLine(spec: LineSpec): MarkGeometry;
186
196
 
187
197
  interface PointSpec {
@@ -236,7 +246,9 @@ interface SamplePoint {
236
246
  /**
237
247
  * Projects each point onto the nearest point of the mark's walk and returns the samples in `t` order
238
248
  * (points at the same `t` keep their order). A point on the walk, such as a vertex of the polyline it
239
- * 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.
240
252
  */
241
253
  declare function samplesAlong(mark: MarkGeometry, points: readonly SamplePoint[]): Sample[];
242
254
 
@@ -447,6 +459,12 @@ interface BarChartOptions<D> extends ChartOptions<D> {
447
459
  * colour in both; the legend lists the categories. It needs one series: on a stack it throws.
448
460
  */
449
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;
450
468
  }
451
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. */
452
470
  interface SliceSummary extends MarkSummary {
@@ -503,9 +521,11 @@ interface LineChartOptions<D> extends ChartOptions<D> {
503
521
  readonly xFormat?: (x: Date | number) => string;
504
522
  /**
505
523
  * The numeric fields drawn as lines, in order. Each is a line mark keyed by its field, plus a point
506
- * 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.
507
527
  */
508
- readonly series: readonly NumericKey<D>[];
528
+ readonly series: readonly KeyOfType<D, number | null | undefined>[];
509
529
  /**
510
530
  * The label at each line's end, in the right margin: by default its value in `format` with its
511
531
  * series' label ("52 goals"), counting between values while a change or a reveal plays. `false`
@@ -980,6 +1000,11 @@ interface TravelOptions {
980
1000
  * Moves an icon along the walk, or along one segment, inset by the icon's footprint so it stays
981
1001
  * inside the mark. Its end state is the icon resting at the end. An icon given by name is looked up
982
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.
983
1008
  */
984
1009
  declare function travel(icon: Icon | string, options?: TravelOptions): GeometryEffect;
985
1010
 
@@ -1112,6 +1137,8 @@ interface ThresholdOptions {
1112
1137
  * samples, where it bends), so they're exact where the walk is straight between samples: our lines,
1113
1138
  * and a host polyline sampled at its vertices. Along a curve they're approximate; denser samples
1114
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.
1115
1142
  *
1116
1143
  * It draws at once, with no animation, and redraws on every `onChange`, so it follows a line as it's
1117
1144
  * revealed. Its end state is the same picture, so the colour shows with motion off.
@@ -1239,12 +1266,13 @@ declare function defineIcon(spec: IconSpec): Icon;
1239
1266
  type SvgIconSpec = Omit<IconSpec, "shapes" | "box">;
1240
1267
  /**
1241
1268
  * Converts `path`, `circle`, `rect`, `ellipse`, `line`, `polyline` and `polygon` elements into shapes,
1242
- * with their fill, stroke, stroke width, line caps and joins (as attributes or in `style`, inherited
1243
- * from `<g>`) and transforms applied. `currentColor` becomes the theme's `text` colour, so an icon
1244
- * from an icon set follows the chart's theme. Everything else is dropped: scripts, event handlers,
1245
- * `<use>`, text, images, and what's inside `<defs>`, `<clipPath>` and the like. Gradients, patterns,
1246
- * opacity, fill rules and CSS classes aren't kept; a shape painted with a gradient or pattern falls
1247
- * 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.
1248
1276
  */
1249
1277
  declare function iconFromSvg(markup: string, spec: SvgIconSpec): Icon;
1250
1278
 
@@ -1271,7 +1299,7 @@ declare function registerIcons(icons: readonly Icon[]): void;
1271
1299
  */
1272
1300
  declare function configure(options: StyleOptions): void;
1273
1301
 
1274
- declare const VERSION = "0.2.0";
1302
+ declare const VERSION = "0.3.0";
1275
1303
 
1276
1304
  /**
1277
1305
  * A bar chart in `target` (an element or a selector). The axis whose values aren't numbers is the
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-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';
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;
@@ -176,12 +176,22 @@ interface LineSpec {
176
176
  readonly series?: string;
177
177
  /** At least one point, in chart px. */
178
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[];
179
185
  /** Stroke width in px. Default 1, SVG's default. */
180
186
  readonly width?: number;
181
187
  /** The boxes of the text drawn for the mark, in the same px: passed through as `labelBounds`. */
182
188
  readonly labelBounds?: readonly Rect[];
183
189
  }
184
- /** 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
+ */
185
195
  declare function describeLine(spec: LineSpec): MarkGeometry;
186
196
 
187
197
  interface PointSpec {
@@ -236,7 +246,9 @@ interface SamplePoint {
236
246
  /**
237
247
  * Projects each point onto the nearest point of the mark's walk and returns the samples in `t` order
238
248
  * (points at the same `t` keep their order). A point on the walk, such as a vertex of the polyline it
239
- * 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.
240
252
  */
241
253
  declare function samplesAlong(mark: MarkGeometry, points: readonly SamplePoint[]): Sample[];
242
254
 
@@ -447,6 +459,12 @@ interface BarChartOptions<D> extends ChartOptions<D> {
447
459
  * colour in both; the legend lists the categories. It needs one series: on a stack it throws.
448
460
  */
449
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;
450
468
  }
451
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. */
452
470
  interface SliceSummary extends MarkSummary {
@@ -503,9 +521,11 @@ interface LineChartOptions<D> extends ChartOptions<D> {
503
521
  readonly xFormat?: (x: Date | number) => string;
504
522
  /**
505
523
  * The numeric fields drawn as lines, in order. Each is a line mark keyed by its field, plus a point
506
- * 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.
507
527
  */
508
- readonly series: readonly NumericKey<D>[];
528
+ readonly series: readonly KeyOfType<D, number | null | undefined>[];
509
529
  /**
510
530
  * The label at each line's end, in the right margin: by default its value in `format` with its
511
531
  * series' label ("52 goals"), counting between values while a change or a reveal plays. `false`
@@ -980,6 +1000,11 @@ interface TravelOptions {
980
1000
  * Moves an icon along the walk, or along one segment, inset by the icon's footprint so it stays
981
1001
  * inside the mark. Its end state is the icon resting at the end. An icon given by name is looked up
982
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.
983
1008
  */
984
1009
  declare function travel(icon: Icon | string, options?: TravelOptions): GeometryEffect;
985
1010
 
@@ -1112,6 +1137,8 @@ interface ThresholdOptions {
1112
1137
  * samples, where it bends), so they're exact where the walk is straight between samples: our lines,
1113
1138
  * and a host polyline sampled at its vertices. Along a curve they're approximate; denser samples
1114
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.
1115
1142
  *
1116
1143
  * It draws at once, with no animation, and redraws on every `onChange`, so it follows a line as it's
1117
1144
  * revealed. Its end state is the same picture, so the colour shows with motion off.
@@ -1239,12 +1266,13 @@ declare function defineIcon(spec: IconSpec): Icon;
1239
1266
  type SvgIconSpec = Omit<IconSpec, "shapes" | "box">;
1240
1267
  /**
1241
1268
  * Converts `path`, `circle`, `rect`, `ellipse`, `line`, `polyline` and `polygon` elements into shapes,
1242
- * with their fill, stroke, stroke width, line caps and joins (as attributes or in `style`, inherited
1243
- * from `<g>`) and transforms applied. `currentColor` becomes the theme's `text` colour, so an icon
1244
- * from an icon set follows the chart's theme. Everything else is dropped: scripts, event handlers,
1245
- * `<use>`, text, images, and what's inside `<defs>`, `<clipPath>` and the like. Gradients, patterns,
1246
- * opacity, fill rules and CSS classes aren't kept; a shape painted with a gradient or pattern falls
1247
- * 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.
1248
1276
  */
1249
1277
  declare function iconFromSvg(markup: string, spec: SvgIconSpec): Icon;
1250
1278
 
@@ -1271,7 +1299,7 @@ declare function registerIcons(icons: readonly Icon[]): void;
1271
1299
  */
1272
1300
  declare function configure(options: StyleOptions): void;
1273
1301
 
1274
- declare const VERSION = "0.2.0";
1302
+ declare const VERSION = "0.3.0";
1275
1303
 
1276
1304
  /**
1277
1305
  * A bar chart in `target` (an element or a selector). The axis whose values aren't numbers is the