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/CHANGELOG.md CHANGED
@@ -25,6 +25,53 @@ From 0.1.0:
25
25
 
26
26
  Everything else can still change in a minor release while the library is 0.x: the motion core (`motion`, `createMotion`, the clocks, `tween`, `animated`, `playback`, and the types the list doesn't name), the charts, the adapters, the built-in effects and the controls. Those changes are listed here too. [docs/effects-guide.md](https://github.com/Deaversbp/expressive-charts/blob/main/docs/effects-guide.md) is the guide to the author API.
27
27
 
28
+ ## 0.3.0 (27 October 2026)
29
+
30
+ A tooltip that can be hovered, change labels that hold up, lines that skip missing values, long axes, and more of the icon sets' SVG. In the effect-author API, `gaps` on `MarkGeometry`, `gapBefore` on `Sample`, `breaks` on `LineSpec`, and `fillRule` and `opacity` on `IconShape` are additions. Its one change is the `"gapped line"` fixture, with its migration note under Changed. The other changes are outside the promise, and each says what to write instead, if anything.
31
+
32
+ ### Added
33
+
34
+ - **`fillRule` and `opacity` on `IconShape`**, under the 0.x promise. `fillRule` is `"nonzero"` (the default) or `"evenodd"`, which leaves a hole where the path's parts overlap. `opacity`, from 0 to 1 (default 1), fades the whole shape, its fill and stroke together. `defineIcon` checks them, with a `RangeError` naming the shape and the field, and the SVG layer draws them. They're optional fields: code that builds an `IconShape` needs no change.
35
+ - **`gaps` on `MarkGeometry`**, under the 0.x promise: the stretches of a mark's walk with no data, as `[from, to]` values of `t`, in order and apart. A line that skips a value has one, from the value before to the value after. The walk runs straight across a gap, so `start`, `end`, `length`, `path(t)`, `angle(t)` and `outline.sample(n)` work as on any walk; `slice(t0, t1)` and an open outline's `d` leave the gaps out, with a move across each. It's an optional field: code that builds a `MarkGeometry` needs no change, and no mark has gaps unless a line skips a value. An effect that draws its own path from `path(t)` would draw across a gap, so draw along a walk with `slice()`, as the effects guide says.
36
+ - **`breaks` on `LineSpec`**, under the 0.x promise: `describe.line({ points, breaks })` takes the indices of the points that start a new run, so there's a gap from `points[i - 1]` to `points[i]`. Each is a whole number from 1 to the last index, in order, with no repeats; anything else throws a `RangeError` naming it (`breaks[1]`). So a page describes a D3 line drawn with `.defined()` by its defined points and where they break. An optional field: code without it needs no change.
37
+ - **`gapBefore` on `Sample`**, under the 0.x promise: `true` on the first sample after a gap, so a data effect doesn't join it to the one before. `samplesAlong()` sets it from the mark's gaps, and `expressive()` keeps it on the samples a page gives. An optional field.
38
+ - **Missing values on `lineChart`.** `series` take fields of `number | null | undefined`, and a value that's `null` or `undefined` is missing: a gap in its line, from the value before to the value after, with no point. It used to throw. The x stays a stop: the crosshair stops there, and its name, the tooltip and the data table say the series is missing ("3: goals missing, 3.6 xg"). At an x with every value missing there's no point to ring, so keyboard focus there is a 2 px line in `--ec-focus` where the crosshair is, which stays when Escape hides the crosshair. A value alone between gaps shows its point at rest; a line revealed into a gap ends at its last value, with its end label there; and a line with no values is empty. Its samples leave the missing values out, with `gapBefore` after each gap, so `threshold` colours nothing there and `travel` jumps across. A gap opens or closes as a change starts, a value that comes growing out of the line. `NaN` and the infinities still throw. `markLabel`'s summary lists only the values an x has.
39
+ - **Effects across a gap.** `travel` jumps: its icon is never drawn over a gap, and goes from one side to the other at once, inset from each run's ends as from the walk's. Its trip's time counts only the runs it's drawn on, and a run shorter than the icon is passed at once, unless it's the last, where the icon rests at the last value. `threshold` doesn't interpolate across a `gapBefore`, in the mark's samples or the reference's, so where either has no value nothing is coloured. `trace`, `pulse`, `flash`, `wiggle`, `delta` and `label` skip gaps unchanged. No built-in effect draws inside a gap.
40
+ - **`room` on `barChart`**: px the layout keeps clear past the labels at each end of the value axis that bars reach, for text an effect draws there, such as a `delta`. Default 0, so nothing moves. At 320 px, `room: 28` keeps a bar's, a column's and a negative bar's `delta` inside the chart, so a page no longer pads the chart's container for it. Anything but a number of px, 0 or more, throws a `RangeError`.
41
+ - **Page Up and Page Down** on every chart, and on an attachment with `keyboard: true`. They move focus a page on or back and stop at the ends, as the arrows do: a tenth of the marks, rounded up, or on a line chart's time axis a calendar month in its `timeZone`, to the first x a month or more away. A month on keeps the day, or ends a shorter month on its last day: 31 January goes to 28 February. So ten years of days is 120 presses, not 3,653. With Alt, Ctrl or Meta they're still the browser's.
42
+
43
+ ### Changed
44
+
45
+ - **`"gapped line"` in `FixtureName` and `fixtures`**, under the 0.x promise: the line fixture with a gap after its second point, a run either side. So `checkEffect` runs every effect on it too, by default: an effect that fails its checks on a mark with gaps fails where it passed before. Code that maps every fixture's name, such as a `Record<FixtureName, …>`, needs one more entry: `"gapped line": …`. Code that only reads fixtures, or passes its own `marks`, needs no change.
46
+ - **An update ends the last one's `update` effects on the marks it leaves alone**, as a re-trigger would: a `delta` goes at its chart's next update, and a `flash` still playing stops there. An update is a chart's `update()` with `data`, even if no value changed (a matchweek where nobody scores), or one that changes a value or adds or removes a mark; or an attachment's `refresh()` that finds a new row, a new value, or a mark entering or leaving. `update({ on })` alone, a re-sort, a resize, a line's `reveal()`, and a `refresh()` that finds nothing new (a Vega render for a hover signal) keep them. Before, an update effect stayed until its own mark's next update, so a page emptied the slot itself (`update({ on: {} })`) before each update; that's no longer needed, and can go. To keep something past the next update, put it in `decorate`.
47
+ - **Overlay text on attachments is sized as on our charts**: 12.5 px, weight 600, with tabular digits, in the theme's text colour, by a new `.ec-overlay .ec-text` rule. So `delta`'s and `label`'s text on an `expressive()` or `fromVegaView()` attachment no longer takes the host page's text size. The rule is in `:where()`, so a page's own CSS still wins: for the page's size, as before, add `.ec-overlay .ec-text { font-size: inherit; font-weight: inherit; }`, or size it in the page's own rule, such as `#slope .ec-text { font-size: 11px; }`.
48
+ - **A bar chart thins labels that would overlap.** Past about 40 bars, its labels overlapped. Now it draws every nth category label, from the first, with n the smallest of 1, 2, 5, 10, 20, 50 and so on that leaves none overlapping, and its value labels all or none: none when any two would overlap. The marks' names, the tooltip, the legend and the data table keep every name and value; `labelBounds` and `labels()` have only the labels drawn. A chart whose labels didn't overlap looks as it did, and there's no option. A page that thinned the labels itself, with CSS such as `.ec-mark:not([data-key$="0"]) .ec-label { display: none; }`, should drop that rule, which now thins them twice. To show every name, give the chart room for them: more `height` for bars, more `width` for columns, or fewer bars.
49
+
50
+ ### Fixed
51
+
52
+ - **An update run's `data.previous` holds the values the last update gave**, not the values part way through a change still playing. So an update that replaces one still moving says "+1" with `delta`'s default `value`, not "+1.88", and a page no longer needs a `value` that reads its rows to get it right. The values before are the data the mark last rested at: its last update, or where it's been since without a transition (a resize, a line's reveal). The `previous` geometry, and an `update` event's `from`, are still the mark on screen, which the transition starts from.
53
+ - **`iconFromSvg` keeps `fill-rule` and `opacity`**, so an icon whose SVG has an even-odd hole (Heroicons' solid style) or a faded part (a duotone set's) draws as its SVG does. Before, the hole filled in and the faded part drew at full strength. They're read from attributes and `style` and inherited through groups, with a group's opacity multiplied into its shapes'. A shape with an opacity of 0 is dropped. `fill-opacity` and `stroke-opacity` still aren't kept.
54
+ - **`import "expressive-charts/style.css"` typechecks on TypeScript 6 and 7.** From TypeScript 6, a side-effect import must find something (`noUncheckedSideEffectImports` is on by default), and the stylesheet had no types, so the import was error TS2882. Its export now has types, an empty module (`dist/expressive-charts.css.d.ts` and `.d.cts`), and bundlers and Node still load the CSS. It keeps a plain `default` too, so a CSS `@import` (css-loader's) and Sass, which resolve with conditions such as `style`, still find it. Nothing changes on TypeScript 5.4 to 5.9.
55
+ - **The tooltip can be hovered** (WCAG 1.4.13, the accessibility audit's one fail). It took no pointer, so moving onto it hovered whatever was under it, or nothing, which hid it. Now, while it shows, the pointer on it stays on the mark or x it's for, so its text can be read, selected and magnified: leaving it for a mark hovers that mark, and leaving it for anything else ends the hover. Beside a mark, a clear bridge over the 12 px gap leads to it, and one that comes up under a resting pointer, as a crosshair's can, lets the pointer through until the pointer is off it. It looks the same, and Escape still hides it. While it shows it covers the marks under it: reach them round it, or by keyboard.
56
+
57
+ ## 0.2.0 (26 October 2026)
58
+
59
+ Built-in effects that explain a change, text that keeps clear of a mark's own labels, and hover linked across charts. Nothing in the effect-author API breaks: its one change, `labelBounds`, is an addition. The other changes are outside the promise, and each says what to write instead, if anything.
60
+
61
+ ### Added
62
+
63
+ - **`trace`**, a built-in effect: a highlighter stroke drawn along a mark's walk, which stays. `trace({ color, width, opacity, duration })` draws in the overlay and leaves the mark itself untouched, so it's safe in any slot. On a stack it runs the whole walk, and on a point it draws nothing. Its end state is the whole stroke. It isn't a preset. The effects guide's `trace` stays as its worked example, a smaller version.
64
+ - **`link(sources, { by, effects })`**: linked hover across charts and attachments. When one source is hovered by the pointer, touch or the keyboard, the others hover their marks with the same linking value: by default a line point's x, else a mark's key, so a column keyed by its matchweek links with the line's x there. `by(event)` gives the value instead, typed by the sources' rows. Linked marks get their chart's emphasis, dimming and hover effect, with `source: "linked"` on their `hover` event, and no tooltip, focus or announcement; `effects: false` keeps them to emphasis and dimming. The newest hover in a link is the one shown, and Escape or `leave()` on the hovered source ends them all. A source can be in one link at a time, and a `chartSwitch` can't be linked yet. With its types, `Link`, `LinkOptions` and `LinkSource`.
65
+ - **`labelBounds` on `MarkGeometry`**, under the 0.x promise: the boxes of the text the chart draws for a mark, so an effect's own text can keep clear of them. Our charts fill it in: a bar's category and value labels, the two lines of a slice's label outside the ring, a line's end label, each where it's drawn in every frame of a change, a reveal and a resize. Segments, points and marks the library didn't draw have none. `describe.bar`, `.arc`, `.line` and `.point` take it in their specs and pass it through, so a page that describes host marks can give it, and `expressive()` keeps it. It's an optional field: code that builds a `MarkGeometry` needs no change, and an effect that ignores it works as before.
66
+ - **`delta` and `label`**, built-in data effects that put text past the end of a mark, clear of its own labels: past a bar's value label, above a column's, past a line's end label, outside a slice's label, and 10 px past the end of a mark with none. `delta({ value, format, color })`, for the `update` slot, says the change since the last update ("+2"), worded in the page's locale with its sign and at most two decimals; with no previous values, or no change, it draws nothing. `label(text, { color })`, usually for `decorate`, says what `text(data, mark)` works out from the mark's data, and is typed by the rows it reads. Both rise 8 px into place and stay, following the mark, so their end state shows the text. The text is in the overlay, which screen readers don't read: say the same in the table or the announcement. With their types, `DeltaOptions` and `LabelOptions`. The effects guide's `delta` stays as its worked example, a smaller version.
67
+
68
+ ### Changed
69
+
70
+ - **`travel`'s trip lasts at most 4 s base**, after the gait's pace. A trip along more than 1,440 px (about 1,250 px for a step) is shorter than before: the icon goes faster rather than longer, so with `stagger` in front it still ends within 5 s. Analysis and Off scale it as before. Nothing needs to change in your code; for a long walk at the old speed, carry the icon in an effect of your own (`defineEffect`).
71
+ - **A `hover` event's `source` can be `"linked"`**, for a mark `link()` hovered because a mark in another chart was. Code that switches on `source` exhaustively gets a type error: add a `"linked"` case, or handle it with `"pointer"` where a linked mark should act as a hovered one. Without `link()`, `source` is never `"linked"`.
72
+ - **A mark's effects hear `onChange` when its own labels move**, even when the mark doesn't: a line's end label pushed aside by another's, or a label whose text changed. So do a bar's and a slice's when only their row changed, as a line's already did, so a decoration that reads a field the chart doesn't plot follows it. An effect that redraws on every change does a little more work; nothing needs to change in your code.
73
+ - **Hover dims the other marks' bodies, not their labels**, on the bar and donut charts and in a chart switch. The names and values of the marks that aren't hovered stay at full strength, so they keep 4.5:1 (WCAG 1.4.3); they used to dim with their marks, to 2.0:1 in the light theme. `--ec-dim-opacity` keeps its default, 0.3, and an effect's `opacity` on a dimmed mark still multiplies with it. `expressive()`'s `dim` doesn't change. To dim the labels too, as before, add this to the page's CSS: `.ec-chart.ec-hovering .ec-mark:not(.ec-hot) :is(.ec-label, .ec-value) { opacity: var(--ec-dim-opacity, 0.3); }`.
74
+
28
75
  ## 0.1.0 (24 October 2026)
29
76
 
30
77
  The first release, published to npm from CI with provenance. Everything in it is new. [docs/api.md](https://github.com/Deaversbp/expressive-charts/blob/main/docs/api.md) documents every export.
package/README.md CHANGED
@@ -15,10 +15,10 @@ Composable motion and expressive effects for web charts. Hover, update and morph
15
15
 
16
16
  Each picture plays once and stops where its effect ends. **[The demo site](https://deaversbp.github.io/expressive-charts/)** has every effect to try, on the library's charts and on D3, Vega-Lite and hand-written ones, with the motion modes and reduced motion.
17
17
 
18
- > **Status: 0.1.0, the first release (October 2026).** The effect-author API is under [the 0.x promise](#the-0x-promise); the charts, adapters, built-in effects and motion core can still change in a minor release. [CHANGELOG.md](https://github.com/Deaversbp/expressive-charts/blob/main/CHANGELOG.md#010-24-october-2026) lists what's in it.
18
+ > **Status: 0.3.0 (October 2026).** The effect-author API is under [the 0.x promise](#the-0x-promise); the charts, adapters, built-in effects and motion core can still change in a minor release. [CHANGELOG.md](https://github.com/Deaversbp/expressive-charts/blob/main/CHANGELOG.md#030-27-october-2026) lists what's new and what changed since 0.2.0.
19
19
 
20
- - **Effects first.** The mark effects `travel`, `flash`, `wiggle`, `pulse` and the data effect `threshold`, put together with `sequence`, `parallel`, `only` and `stagger`; and the transition effect `morph`, which `chartSwitch` plays to turn each mark of one chart into its mark in the next (a transition can't go into a combinator). An effect reads only a shared description of the mark, so one effect works on every chart, and effects of your own work everywhere the built-in ones do.
21
- - **Charts and adapters.** Bar, donut and line charts, a switch that morphs one into another, and adapters that bring the same effects to SVG marks drawn by other code.
20
+ - **Effects first.** The mark effects `travel`, `flash`, `wiggle`, `pulse`, `trace` and the data effects `threshold`, `delta` and `label`, put together with `sequence`, `parallel`, `only` and `stagger`; and the transition effect `morph`, which `chartSwitch` plays to turn each mark of one chart into its mark in the next (a transition can't go into a combinator). An effect reads only a shared description of the mark, so one effect works on every chart, and effects of your own work everywhere the built-in ones do.
21
+ - **Charts and adapters.** Bar, donut and line charts, a switch that morphs one into another, adapters that bring the same effects to SVG marks drawn by other code, and hover linked across them.
22
22
  - **Motion that stays readable.** One clock and three modes: Presentation (staged, about a second), Analysis (at most about 200 ms) and Off. The device's reduced-motion setting is followed unless the viewer picks a mode on the page, and every effect has an end state, which is what reduced motion shows.
23
23
  - **Accessible.** Keyboard focus, a name for every mark, a data table, announcements and a pause control for anything that plays, checked against WCAG 2.2 AA.
24
24
 
@@ -28,13 +28,13 @@ Each picture plays once and stops where its effect ends. **[The demo site](https
28
28
  npm install expressive-charts
29
29
  ```
30
30
 
31
- It has no runtime dependencies. It's an ES module and CommonJS, each with its own types, and its JavaScript has no side effects, so a bundler keeps only what a page imports: a bar chart is about 28 KB gzipped, and everything 65 KB.
31
+ It has no runtime dependencies. It's an ES module and CommonJS, each with its own types, and its JavaScript has no side effects, so a bundler keeps only what a page imports: a bar chart is about 31 KB gzipped, and everything 72 KB.
32
32
 
33
33
  On a page with no bundler, the script-tag bundle defines one global, `ExpressiveCharts`, holding the main entry:
34
34
 
35
35
  ```html
36
36
  <div id="sales"></div>
37
- <script src="https://cdn.jsdelivr.net/npm/expressive-charts@0.1/dist/expressive-charts.global.js"></script>
37
+ <script src="https://cdn.jsdelivr.net/npm/expressive-charts@0.3/dist/expressive-charts.global.js"></script>
38
38
  <script>
39
39
  const { barChart } = ExpressiveCharts;
40
40
  barChart("#sales", {
@@ -124,10 +124,11 @@ playButton("#play", season, { labels: { play: "Play season" } });
124
124
 
125
125
  [docs/api.md](https://github.com/Deaversbp/expressive-charts/blob/main/docs/api.md) documents every export, with its options, their defaults and what it returns.
126
126
 
127
- - **Charts.** [`barChart`](https://github.com/Deaversbp/expressive-charts/blob/main/docs/api.md#barchart) draws bars or columns, plain or stacked; [`donutChart`](https://github.com/Deaversbp/expressive-charts/blob/main/docs/api.md#donutchart) shares of a total; [`lineChart`](https://github.com/Deaversbp/expressive-charts/blob/main/docs/api.md#linechart) a line per series, on a number axis or, when `x` gives `Date`s, a time axis in UTC (or `timeZone: "local"`) worded in the page's locale. Each sizes itself to its container, follows the light or dark theme, and has a tooltip, a legend, a data table and keyboard focus. Its handle has `update()`, which animates a change by the motion mode, and `update({ on })` swaps its effects in place; `focus(key)`; `leave()`, which ends its hover; and `labels()`. `table.series` heads a series' column in the data table.
127
+ - **Charts.** [`barChart`](https://github.com/Deaversbp/expressive-charts/blob/main/docs/api.md#barchart) draws bars or columns, plain or stacked; [`donutChart`](https://github.com/Deaversbp/expressive-charts/blob/main/docs/api.md#donutchart) shares of a total; [`lineChart`](https://github.com/Deaversbp/expressive-charts/blob/main/docs/api.md#linechart) a line per series, on a number axis or, when `x` gives `Date`s, a time axis in UTC (or `timeZone: "local"`) worded in the page's locale, with a gap wherever a value is `null` or `undefined`. Each sizes itself to its container, follows the light or dark theme, and has a tooltip, a legend, a data table and keyboard focus. Its handle has `update()`, which animates a change by the motion mode, and `update({ on })` swaps its effects in place; `focus(key)`; `leave()`, which ends its hover; and `labels()`. `table.series` heads a series' column in the data table.
128
128
  - **Switching.** [`chartSwitch`](https://github.com/Deaversbp/expressive-charts/blob/main/docs/api.md#chartswitch) shows views of the same data one at a time, and turns each mark into its own mark in the next with [`morph()`](https://github.com/Deaversbp/expressive-charts/blob/main/docs/api.md#morph): a donut becoming columns, and back from wherever it is.
129
- - **Adapters.** [`expressive()`](https://github.com/Deaversbp/expressive-charts/blob/main/docs/api.md#expressive) reads keys, rows and geometry from SVG marks drawn by D3, Observable Plot or by hand, and draws on an overlay, leaving the host's styling alone; `watch: true` follows the host's own transitions. Observable Plot binds each rect to its row's index, so pass `datum: (el) => rows[el.__data__]`; Plot draws a new `<svg>` each time, so pass `refresh()` the new one's rects. The Plot accessors are tested against Plot 0.6.17. [`fromVegaView()`](https://github.com/Deaversbp/expressive-charts/blob/main/docs/api.md#fromvegaview) does the same for a Vega or Vega-Lite View rendered as SVG, and follows its renders.
130
- - **Effects.** [`travel`](https://github.com/Deaversbp/expressive-charts/blob/main/docs/api.md#travel) carries an icon along a mark; [`flash`](https://github.com/Deaversbp/expressive-charts/blob/main/docs/api.md#flash), [`wiggle`](https://github.com/Deaversbp/expressive-charts/blob/main/docs/api.md#wiggle) and [`pulse`](https://github.com/Deaversbp/expressive-charts/blob/main/docs/api.md#pulse) draw attention without changing a value; [`threshold`](https://github.com/Deaversbp/expressive-charts/blob/main/docs/api.md#threshold) colours the parts of a mark below or above a reference. Each goes in an effect slot (`hover`, `enter`, `update`, `exit`, `decorate`), as an effect or a preset's name (`"wiggle"`).
129
+ - **Adapters.** [`expressive()`](https://github.com/Deaversbp/expressive-charts/blob/main/docs/api.md#expressive) reads keys, rows and geometry from SVG marks drawn by D3, Observable Plot or by hand, and draws on an overlay, leaving the host's styling alone; `watch: true` follows the host's own transitions. A line drawn with d3's `.defined()` keeps its gaps: describe it with [`describe.line`](https://github.com/Deaversbp/expressive-charts/blob/main/docs/api.md#linespec)'s `breaks`, and no effect draws inside them. Observable Plot binds each rect to its row's index, so pass `datum: (el) => rows[el.__data__]`; Plot draws a new `<svg>` each time, so pass `refresh()` the new one's rects. The Plot accessors are tested against Plot 0.6.17. [`fromVegaView()`](https://github.com/Deaversbp/expressive-charts/blob/main/docs/api.md#fromvegaview) does the same for a Vega or Vega-Lite View rendered as SVG, and follows its renders.
130
+ - **Linked hover.** [`link()`](https://github.com/Deaversbp/expressive-charts/blob/main/docs/api.md#link) links hover across charts and attachments by a value their marks share, such as a column's matchweek and the line's x there: hovering one hovers the others' marks with that value, with their emphasis, dimming and hover effects, as `source: "linked"`. Linked charts show no tooltip and take no focus.
131
+ - **Effects.** [`travel`](https://github.com/Deaversbp/expressive-charts/blob/main/docs/api.md#travel) carries an icon along a mark; [`flash`](https://github.com/Deaversbp/expressive-charts/blob/main/docs/api.md#flash), [`wiggle`](https://github.com/Deaversbp/expressive-charts/blob/main/docs/api.md#wiggle) and [`pulse`](https://github.com/Deaversbp/expressive-charts/blob/main/docs/api.md#pulse) draw attention without changing a value; [`trace`](https://github.com/Deaversbp/expressive-charts/blob/main/docs/api.md#trace) draws a highlighter stroke along a mark and leaves it there; [`threshold`](https://github.com/Deaversbp/expressive-charts/blob/main/docs/api.md#threshold) colours the parts of a mark below or above a reference; [`delta`](https://github.com/Deaversbp/expressive-charts/blob/main/docs/api.md#delta) labels a mark's change since the last update ("+2"), and [`label`](https://github.com/Deaversbp/expressive-charts/blob/main/docs/api.md#label) any text worked out from its data, past the mark's own labels. Each goes in an effect slot (`hover`, `enter`, `update`, `exit`, `decorate`), as an effect or a preset's name (`"wiggle"`).
131
132
  - **Controls.** [`motionSwitch()`](https://github.com/Deaversbp/expressive-charts/blob/main/docs/api.md#motionswitch) is the viewer's own choice of mode. [`playback()`](https://github.com/Deaversbp/expressive-charts/blob/main/docs/api.md#playback) plays a value through a range, and [`playButton()`](https://github.com/Deaversbp/expressive-charts/blob/main/docs/api.md#playbutton) is its Play/Pause button.
132
133
  - **The motion core.** [`motion`](https://github.com/Deaversbp/expressive-charts/blob/main/docs/api.md#motion), [`tween()`](https://github.com/Deaversbp/expressive-charts/blob/main/docs/api.md#tween) and [`animated()`](https://github.com/Deaversbp/expressive-charts/blob/main/docs/api.md#animated), for animations of your own that follow the same modes.
133
134
 
@@ -169,7 +170,7 @@ The script-tag bundle, `dist/expressive-charts.global.js`, is the main entry alo
169
170
  ## Browsers and TypeScript
170
171
 
171
172
  - **Browsers.** Current Chrome and Edge, Firefox, and Safari. Every DOM check in the test suite (names, roles, tab order, focus rings, tooltips, keys, switches and reduced motion), with axe's accessibility rules, runs in Chromium, Firefox and WebKit, in Playwright 1.64; the screenshots are Chromium's. That's each browser's engine, not a device: Safari on macOS and iOS hasn't been run itself. The build targets ES2020.
172
- - **TypeScript 5.4 or newer**, since the types use `NoInfer`. The packed package is checked under `bundler` and `node16` resolution, as an ES module and as CommonJS. Under the old `node10` (`"node"`), TypeScript can't find the subpath entries' types.
173
+ - **TypeScript 5.4 or newer**, since the types use `NoInfer`. The packed package is checked on TypeScript 5.4, 6 and 7, under `bundler` and `node16` resolution, as an ES module and as CommonJS, with `import "expressive-charts/style.css"`. Under the old `node10` (`"node"`), TypeScript can't find the subpath entries' types.
173
174
  - **Node.js 22 or newer** to import it on a server: nothing touches the DOM until a chart, an adapter or a control is made, and those need one.
174
175
 
175
176
  ## Content-Security-Policy
@@ -192,12 +193,12 @@ The package lists its CSS under `sideEffects`, so bundlers keep that import. Cha
192
193
  ## Accessibility
193
194
 
194
195
  - **Names.** Each chart is a `role="group"` named by its `label`, and each mark one image named by what it shows: "Okafor: 16 goals, 4 assists", or a slice's "Saved: 112 shots, 28%". `markLabel` words the names ("1 goal") and `markDescription` adds what they don't say.
195
- - **Keyboard.** A chart is one tab stop: the arrow keys move between its marks, Home and End go to the ends, and focus shows a ring and plays the same effects as hover. Escape ends a hover, and so does `leave()`.
196
+ - **Keyboard.** A chart is one tab stop: the arrow keys move between its marks, Page Up and Page Down by a page (a month on a line's time axis), Home and End go to the ends, and focus shows a ring and plays the same effects as hover. Escape ends a hover, and so does `leave()`.
196
197
  - **Fallbacks.** A data table after every chart, which every screen reader can read, and with `announce: true` a polite live region that says what each update changed.
197
198
  - **Motion.** Reduced motion jumps every animation to its end state unless the viewer picks a mode on the page, with `motionSwitch()`. Nothing plays by itself, and a playback has its pause control in `playButton()` (WCAG 2.2.2).
198
199
  - **Other people's charts.** `expressive()` adds the same keyboard focus with `keyboard: true`, and one name per mark with `markLabel`.
199
200
 
200
- The demo pages with the library's charts on them have had a written WCAG 2.2 AA audit ([a11y-audit.md](https://github.com/Deaversbp/expressive-charts/blob/main/docs/a11y-audit.md)), and the test suite runs axe's WCAG rules on every demo page in Chromium, Firefox and WebKit, in light and dark, at 320 px wide and under forced colours. Screen-reader scripts for NVDA and Chrome, with their results, are in [a11y-check.md](https://github.com/Deaversbp/expressive-charts/blob/main/docs/a11y-check.md#results). Known gaps: the tooltip can't be hovered itself (it can be dismissed with Escape), dimming lowers the other marks' labels below 4.5:1 while one is hovered, and VoiceOver hasn't been run.
201
+ The demo pages with the library's charts on them have had a written WCAG 2.2 AA audit ([a11y-audit.md](https://github.com/Deaversbp/expressive-charts/blob/main/docs/a11y-audit.md)), and the test suite runs axe's WCAG rules on every demo page in Chromium, Firefox and WebKit, in light and dark, at 320 px wide and under forced colours. Screen-reader scripts for NVDA and Chrome, with their results, are in [a11y-check.md](https://github.com/Deaversbp/expressive-charts/blob/main/docs/a11y-check.md#results). The tooltip can be hovered, and dismissed with Escape. Known gap: VoiceOver hasn't been run.
201
202
 
202
203
  ## Limits
203
204
 
@@ -226,7 +227,7 @@ From 0.1.0 the library follows semantic versioning. While it's 0.x, the effect-a
226
227
  - [Examples](https://github.com/Deaversbp/expressive-charts/tree/main/docs/sketches/examples): pages written against the API, which `npm run typecheck` checks: ball-and-cleat bars, a goals vs xG line with playback, a donut that morphs into columns, D3 charts, effects of your own and presets.
227
228
  - [Changelog](https://github.com/Deaversbp/expressive-charts/blob/main/CHANGELOG.md), and [the development log](https://github.com/Deaversbp/expressive-charts/blob/main/docs/plan.md): the plan the library was built to, milestone by milestone, with the reasoning behind each decision.
228
229
  - [Accessibility audit](https://github.com/Deaversbp/expressive-charts/blob/main/docs/a11y-audit.md) and [screen-reader scripts](https://github.com/Deaversbp/expressive-charts/blob/main/docs/a11y-check.md).
229
- - [Demos](https://github.com/Deaversbp/expressive-charts/tree/main/demo), on [the demo site](https://deaversbp.github.io/expressive-charts/), or served by `npm run dev`. `bars.html`, `donut.html`, `line.html` and `morph.html` put the library's charts beside D3, Vega-Lite and hand-written ones, with the same effects on each; `stress.html` is the limits above; and `lab.html` is the single-file prototype the library grew out of.
230
+ - [Demos](https://github.com/Deaversbp/expressive-charts/tree/main/demo), on [the demo site](https://deaversbp.github.io/expressive-charts/), or served by `npm run dev`. `bars.html`, `donut.html`, `line.html` and `morph.html` put the library's charts beside D3, Vega-Lite and hand-written ones, with the same effects on each; `season.html` links three charts by matchweek and labels each change with `delta()` and `label()`; `stress.html` is the limits above; and `lab.html` is the single-file prototype the library grew out of.
230
231
  - [Contributing](https://github.com/Deaversbp/expressive-charts/blob/main/CONTRIBUTING.md) and [issues](https://github.com/Deaversbp/expressive-charts/issues).
231
232
 
232
233
  ## Development
@@ -238,7 +239,7 @@ From 0.1.0 the library follows semantic versioning. While it's 0.x, the effect-a
238
239
  | `npm run size` | Measures the built package and fails when a size is over its budget in `scripts/size-budget.json` (see [CONTRIBUTING.md](https://github.com/Deaversbp/expressive-charts/blob/main/CONTRIBUTING.md#bundle-size)) |
239
240
  | `npm run pack-check` | After a build: packs the package, installs it in a new project and checks every entry as ESM and CommonJS, with its types (see [CONTRIBUTING.md](https://github.com/Deaversbp/expressive-charts/blob/main/CONTRIBUTING.md#setup)) |
240
241
  | `npm test` | Runs the test suite, which also checks [docs/api.md](https://github.com/Deaversbp/expressive-charts/blob/main/docs/api.md) against the exports and type-checks this README's examples |
241
- | `npm run test:visual:docker` | Runs the screenshot tests of `demo/bars.html`, `donut.html`, `line.html`, `morph.html` and `stress.html` in Chromium, and their DOM checks and the accessibility checks (axe) in Chromium, Firefox and WebKit, in Playwright's Linux image (needs Docker; see [CONTRIBUTING.md](https://github.com/Deaversbp/expressive-charts/blob/main/CONTRIBUTING.md#visual-tests)) |
242
+ | `npm run test:visual:docker` | Runs the screenshot tests of `demo/bars.html`, `donut.html`, `line.html`, `morph.html`, `season.html` and `stress.html` in Chromium, and their DOM checks and the accessibility checks (axe) in Chromium, Firefox and WebKit, in Playwright's Linux image (needs Docker; see [CONTRIBUTING.md](https://github.com/Deaversbp/expressive-charts/blob/main/CONTRIBUTING.md#visual-tests)) |
242
243
  | `npm run build:site` | Builds the demo pages into `site/`, which `.github/workflows/pages.yml` publishes as [the demo site](https://deaversbp.github.io/expressive-charts/) |
243
244
  | `npm run media` | Captures README's pictures (`docs/media/*.gif`) from the demo pages, frame by frame, in Playwright's Linux image (needs Docker; see [CONTRIBUTING.md](https://github.com/Deaversbp/expressive-charts/blob/main/CONTRIBUTING.md#readmes-pictures-and-the-demo-site)) |
244
245
  | `npm run bench` | Measures the stress page's cases in headless Chromium against `npm run dev`, unthrottled and at 4×, about 47 minutes; not in CI |
@@ -2,6 +2,7 @@
2
2
  var GAITS = ["roll", "step", "slide"];
3
3
  var LINECAPS = ["butt", "round"];
4
4
  var LINEJOINS = ["miter", "round"];
5
+ var FILL_RULES = ["nonzero", "evenodd"];
5
6
  var PATH_DATA = /^\s*[Mm][MmLlHhVvCcSsQqTtAaZz0-9eE.,+\-\s]*$/;
6
7
  function defineIcon(spec) {
7
8
  const name = spec?.name;
@@ -52,8 +53,11 @@ function checkShape(shape, field, fail, finite) {
52
53
  if (shape.width !== void 0 && finite(`${field}.width`, shape.width) < 0) fail(`${field}.width`, `can't be negative, got ${shape.width}`);
53
54
  if (shape.linecap !== void 0 && !LINECAPS.includes(shape.linecap)) fail(`${field}.linecap`, `must be butt or round, got ${String(shape.linecap)}`);
54
55
  if (shape.linejoin !== void 0 && !LINEJOINS.includes(shape.linejoin)) fail(`${field}.linejoin`, `must be miter or round, got ${String(shape.linejoin)}`);
56
+ if (shape.fillRule !== void 0 && !FILL_RULES.includes(shape.fillRule)) fail(`${field}.fillRule`, `must be nonzero or evenodd, got ${String(shape.fillRule)}`);
57
+ const opacity = shape.opacity === void 0 ? 1 : finite(`${field}.opacity`, shape.opacity);
58
+ if (opacity < 0 || opacity > 1) fail(`${field}.opacity`, `must be from 0 to 1, got ${opacity}`);
55
59
  const copy = { d: shape.d };
56
- for (const key of ["fill", "stroke", "width", "linecap", "linejoin", "clip"]) {
60
+ for (const key of ["fill", "stroke", "width", "linecap", "linejoin", "clip", "fillRule", "opacity"]) {
57
61
  if (shape[key] !== void 0) copy[key] = shape[key];
58
62
  }
59
63
  return freeze(copy);
@@ -63,4 +67,4 @@ var freeze = (value) => Object.freeze(value);
63
67
  export {
64
68
  defineIcon
65
69
  };
66
- //# sourceMappingURL=chunk-N5IF2RO2.js.map
70
+ //# sourceMappingURL=chunk-7A7LXXT4.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"sources":["../src/icons/define.ts"],"sourcesContent":["// defineIcon: fills an icon's defaults and checks every field, so effects can rely on all of them.\n\nimport type { Icon, IconShape, Point, Rect } from \"../core\";\n\n/** What defineIcon takes: an Icon whose pivot, footprint and size are optional. */\nexport type IconSpec = Omit<Icon, \"footprint\" | \"pivot\" | \"size\"> & Partial<Pick<Icon, \"footprint\" | \"pivot\" | \"size\">>;\n\nconst GAITS: readonly string[] = [\"roll\", \"step\", \"slide\"];\nconst LINECAPS: readonly string[] = [\"butt\", \"round\"];\nconst LINEJOINS: readonly string[] = [\"miter\", \"round\"];\nconst FILL_RULES: readonly string[] = [\"nonzero\", \"evenodd\"];\n/** Path data: commands, numbers, separators. Anything else (markup, url(), quotes) is a mistake. */\nconst PATH_DATA = /^\\s*[Mm][MmLlHhVvCcSsQqTtAaZz0-9eE.,+\\-\\s]*$/;\n\n/**\n * Makes an icon from its parts. Shapes are drawn facing +x, up towards −y, in px at the icon's\n * natural size. Defaults: `pivot` is the anchor, `footprint` reaches from the anchor to the box's\n * edges, `size` is the box's width and `radius` half its height. Bad input throws a RangeError\n * naming the field. The icon and its parts are frozen, since one icon is shared by every run.\n */\nexport function defineIcon(spec: IconSpec): Icon {\n const name = spec?.name;\n if (typeof name !== \"string\" || name === \"\") throw new TypeError(`defineIcon needs a non-empty string name, got ${JSON.stringify(name)}.`);\n const fail = (field: string, problem: string): never => {\n throw new RangeError(`defineIcon: \"${name}\" ${field} ${problem}.`);\n };\n const finite = (field: string, value: unknown): number =>\n typeof value === \"number\" && Number.isFinite(value) ? value : fail(field, `must be a finite number, got ${String(value)}`);\n const positive = (field: string, value: unknown): number => (finite(field, value) > 0 ? (value as number) : fail(field, `must be more than 0, got ${String(value)}`));\n const point = (field: string, value: Point | undefined): Point =>\n value && typeof value === \"object\" ? freeze({ x: finite(`${field}.x`, value.x), y: finite(`${field}.y`, value.y) }) : fail(field, \"must be a point { x, y }\");\n\n if (!Array.isArray(spec.shapes) || spec.shapes.length === 0) fail(\"shapes\", \"must be a non-empty array\");\n const shapes = spec.shapes.map((shape, i) => checkShape(shape, `shapes[${i}]`, fail, finite));\n\n const b = spec.box;\n if (!b || typeof b !== \"object\") fail(\"box\", \"must be a rectangle { x, y, width, height }\");\n const box: Rect = freeze({ x: finite(\"box.x\", b.x), y: finite(\"box.y\", b.y), width: positive(\"box.width\", b.width), height: positive(\"box.height\", b.height) });\n\n const anchor = point(\"anchor\", spec.anchor);\n const pivot = spec.pivot === undefined ? anchor : point(\"pivot\", spec.pivot);\n const footprint = spec.footprint ?? [Math.max(0, anchor.x - box.x), Math.max(0, box.x + box.width - anchor.x)];\n if (!Array.isArray(footprint) || footprint.length !== 2) fail(\"footprint\", \"must be [behind, ahead]\");\n footprint.forEach((reach, i) => {\n if (finite(`footprint[${i}]`, reach) < 0) fail(`footprint[${i}]`, `can't be negative, got ${reach}`);\n });\n const size = spec.size === undefined ? box.width : positive(\"size\", spec.size);\n const radius = spec.radius === undefined ? box.height / 2 : positive(\"radius\", spec.radius);\n if (spec.gait !== undefined && !GAITS.includes(spec.gait)) fail(\"gait\", `must be roll, step or slide, got ${String(spec.gait)}`);\n if (spec.upright !== undefined && typeof spec.upright !== \"boolean\") fail(\"upright\", `must be true or false, got ${String(spec.upright)}`);\n\n return freeze({\n name,\n shapes: freeze(shapes),\n box,\n size,\n anchor,\n pivot,\n footprint: freeze([footprint[0], footprint[1]] as const),\n ...(spec.gait !== undefined ? { gait: spec.gait } : {}),\n radius,\n ...(spec.upright !== undefined ? { upright: spec.upright } : {})\n });\n}\n\nfunction checkShape(\n shape: IconShape,\n field: string,\n fail: (field: string, problem: string) => never,\n finite: (field: string, value: unknown) => number\n): IconShape {\n if (!shape || typeof shape !== \"object\") fail(field, \"must be a shape { d, fill?, stroke?, … }\");\n if (typeof shape.d !== \"string\" || !PATH_DATA.test(shape.d)) fail(`${field}.d`, \"must be path data starting with a move\");\n if (shape.clip !== undefined && (typeof shape.clip !== \"string\" || !PATH_DATA.test(shape.clip))) fail(`${field}.clip`, \"must be path data starting with a move\");\n for (const paint of [\"fill\", \"stroke\"] as const) {\n const value = shape[paint];\n if (value !== undefined && (typeof value !== \"string\" || value === \"\")) fail(`${field}.${paint}`, `must be a colour, got ${String(value)}`);\n }\n if (shape.width !== undefined && finite(`${field}.width`, shape.width) < 0) fail(`${field}.width`, `can't be negative, got ${shape.width}`);\n if (shape.linecap !== undefined && !LINECAPS.includes(shape.linecap)) fail(`${field}.linecap`, `must be butt or round, got ${String(shape.linecap)}`);\n if (shape.linejoin !== undefined && !LINEJOINS.includes(shape.linejoin)) fail(`${field}.linejoin`, `must be miter or round, got ${String(shape.linejoin)}`);\n if (shape.fillRule !== undefined && !FILL_RULES.includes(shape.fillRule)) fail(`${field}.fillRule`, `must be nonzero or evenodd, got ${String(shape.fillRule)}`);\n const opacity = shape.opacity === undefined ? 1 : finite(`${field}.opacity`, shape.opacity);\n if (opacity < 0 || opacity > 1) fail(`${field}.opacity`, `must be from 0 to 1, got ${opacity}`);\n const copy: { -readonly [K in keyof IconShape]: IconShape[K] } = { d: shape.d };\n for (const key of [\"fill\", \"stroke\", \"width\", \"linecap\", \"linejoin\", \"clip\", \"fillRule\", \"opacity\"] as const) {\n if (shape[key] !== undefined) (copy as Record<string, unknown>)[key] = shape[key];\n }\n return freeze(copy);\n}\n\nconst freeze = <T>(value: T): T => Object.freeze(value);\n"],"mappings":"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","names":[]}
@@ -99,7 +99,8 @@ function pathData(segments, closed = false) {
99
99
 
100
100
  // src/core/geometry/walk.ts
101
101
  var clamp01 = (t) => t > 0 ? t < 1 ? t : 1 : 0;
102
- function createWalk(segments) {
102
+ var NONE = Object.freeze([]);
103
+ function createWalk(segments, gaps = NONE) {
103
104
  const first = segments[0];
104
105
  const last = segments[segments.length - 1];
105
106
  if (!first || !last) throw new RangeError("A walk needs at least one segment.");
@@ -131,40 +132,54 @@ function createWalk(segments) {
131
132
  const { index, u } = locate(at * length);
132
133
  return pointOn(segments[index], u);
133
134
  };
135
+ const draw = (from, to) => {
136
+ let d = moveTo(point(from));
137
+ const a = from * length;
138
+ const b = to * length;
139
+ if (!(b > a)) return d;
140
+ const first2 = locate(a);
141
+ for (let i = first2.index; i < segments.length && cumulative[i] < b; i++) {
142
+ const segment = segments[i];
143
+ if (!(segment.length > 0)) continue;
144
+ const u0 = i === first2.index ? first2.u : 0;
145
+ const u1 = cumulative[i + 1] > b ? Math.min(1, (b - cumulative[i]) / segment.length) : 1;
146
+ if (u1 > u0) d += drawTo(segment, u0, u1);
147
+ }
148
+ return d;
149
+ };
150
+ const slice = (t0, t1) => {
151
+ const from = clamp01(Math.min(t0, t1));
152
+ const to = clamp01(Math.max(t0, t1));
153
+ if (gaps.length === 0) return draw(from, to);
154
+ let d = "";
155
+ let at = from;
156
+ for (const [a, b] of gaps) {
157
+ if (a >= to) break;
158
+ if (a > at) d += draw(at, a);
159
+ if (b > at) at = b;
160
+ }
161
+ if (to > at) d += draw(at, to);
162
+ return d === "" ? moveTo(point(from)) : d;
163
+ };
134
164
  return {
135
165
  segments,
136
166
  length,
137
167
  start,
138
168
  end,
169
+ gaps,
139
170
  point,
140
171
  angle(t) {
141
172
  const { index, u } = locate(clamp01(t) * length);
142
173
  return angleOn(segments[index], u);
143
174
  },
144
- slice(t0, t1) {
145
- const from = clamp01(Math.min(t0, t1));
146
- const to = clamp01(Math.max(t0, t1));
147
- let d = moveTo(point(from));
148
- const a = from * length;
149
- const b = to * length;
150
- if (!(b > a)) return d;
151
- const first2 = locate(a);
152
- for (let i = first2.index; i < segments.length && cumulative[i] < b; i++) {
153
- const segment = segments[i];
154
- if (!(segment.length > 0)) continue;
155
- const u0 = i === first2.index ? first2.u : 0;
156
- const u1 = cumulative[i + 1] > b ? Math.min(1, (b - cumulative[i]) / segment.length) : 1;
157
- if (u1 > u0) d += drawTo(segment, u0, u1);
158
- }
159
- return d;
160
- },
161
- d: pathData(segments)
175
+ slice,
176
+ d: gaps.length === 0 ? pathData(segments) : slice(0, 1)
162
177
  };
163
178
  }
164
179
 
165
180
  // src/core/geometry/outline.ts
166
181
  function closedOutline(sides) {
167
- const walks = sides.map(createWalk);
182
+ const walks = sides.map((side) => createWalk(side));
168
183
  return {
169
184
  d: pathData(sides.flat(), true),
170
185
  closed: true,
@@ -200,7 +215,7 @@ function checkCount(n, multiple) {
200
215
  }
201
216
 
202
217
  // src/core/geometry/describe/mark.ts
203
- function assemble({ key, series, walk, thickness, outline, bounds, center, pivot, segments }) {
218
+ function assemble({ key, series, walk, thickness, outline, bounds, center, pivot, labelBounds, segments }) {
204
219
  return {
205
220
  key,
206
221
  ...series === void 0 ? {} : { series },
@@ -210,11 +225,13 @@ function assemble({ key, series, walk, thickness, outline, bounds, center, pivot
210
225
  path: (t) => walk.point(t),
211
226
  angle: (t) => walk.angle(t),
212
227
  slice: (t0, t1) => walk.slice(t0, t1),
228
+ ...walk.gaps.length === 0 ? {} : { gaps: walk.gaps },
213
229
  thickness,
214
230
  outline,
215
231
  bounds,
216
232
  center,
217
233
  pivot,
234
+ ...labelBounds === void 0 ? {} : { labelBounds },
218
235
  ...segments === void 0 ? {} : { segments }
219
236
  };
220
237
  }
@@ -222,6 +239,18 @@ function finite(builder, field, value) {
222
239
  if (!Number.isFinite(value)) throw new RangeError(`describe.${builder}: ${field} must be a finite number, got ${value}.`);
223
240
  return value;
224
241
  }
242
+ function labelBoxes(builder, boxes) {
243
+ if (!boxes) return boxes;
244
+ for (let i = 0; i < boxes.length; i++) {
245
+ const { x, y, width, height } = boxes[i];
246
+ if (Number.isFinite(x) && Number.isFinite(y) && Number.isFinite(width) && width >= 0 && Number.isFinite(height) && height >= 0) continue;
247
+ finite(builder, `labelBounds[${i}].x`, x);
248
+ finite(builder, `labelBounds[${i}].y`, y);
249
+ size(builder, `labelBounds[${i}].width`, width);
250
+ size(builder, `labelBounds[${i}].height`, height);
251
+ }
252
+ return boxes;
253
+ }
225
254
  function size(builder, field, value) {
226
255
  if (!(Number.isFinite(value) && value >= 0)) {
227
256
  throw new RangeError(`describe.${builder}: ${field} must be a finite number \u2265 0, got ${value}.`);
@@ -256,7 +285,8 @@ function describeArc(spec) {
256
285
  outline: closedOutline(sides),
257
286
  bounds: boundsOf(sides.flat().flatMap(extremes)),
258
287
  center: walk.point(0.5),
259
- pivot: center
288
+ pivot: center,
289
+ labelBounds: labelBoxes("arc", spec.labelBounds)
260
290
  });
261
291
  }
262
292
 
@@ -273,6 +303,7 @@ function describeBar(spec) {
273
303
  size("bar", "height", height);
274
304
  const radius = size("bar", "radius", spec.radius ?? 0);
275
305
  const gap = size("bar", "gap", spec.gap ?? 0);
306
+ const labelBounds = labelBoxes("bar", spec.labelBounds);
276
307
  const horizontal = baseline === "left" || baseline === "right";
277
308
  const length = horizontal ? width : height;
278
309
  const thickness = horizontal ? height : width;
@@ -325,7 +356,7 @@ function describeBar(spec) {
325
356
  })
326
357
  )
327
358
  );
328
- return part(0, length, radius, { key, series, bounds: { x, y, width, height }, segments });
359
+ return part(0, length, radius, { key, series, bounds: { x, y, width, height }, labelBounds, segments });
329
360
  }
330
361
  function frame({ x, y, width: w, height: h, baseline }) {
331
362
  switch (baseline) {
@@ -350,12 +381,13 @@ function describeLine(spec) {
350
381
  finite("line", `points[${i}].x`, p.x);
351
382
  finite("line", `points[${i}].y`, p.y);
352
383
  });
384
+ const breaks = checkBreaks(spec.breaks, points.length);
353
385
  const segments = [];
354
386
  for (let i = 1; i < points.length; i++) {
355
387
  segments.push(line(points[i - 1], points[i], segments[segments.length - 1]?.angle ?? 0));
356
388
  }
357
389
  if (segments.length === 0) segments.push(line(first, first));
358
- const walk = createWalk(segments);
390
+ const walk = createWalk(segments, gapsAt(breaks, segments));
359
391
  const box = boundsOf(points);
360
392
  const pad = width / 2;
361
393
  return assemble({
@@ -366,9 +398,29 @@ function describeLine(spec) {
366
398
  outline: openOutline(walk),
367
399
  bounds: { x: box.x - pad, y: box.y - pad, width: box.width + width, height: box.height + width },
368
400
  center: walk.point(0.5),
369
- pivot: first
401
+ pivot: first,
402
+ labelBounds: labelBoxes("line", spec.labelBounds)
403
+ });
404
+ }
405
+ function gapsAt(breaks, segments) {
406
+ const along = [0];
407
+ for (const segment of segments) along.push(along[along.length - 1] + segment.length);
408
+ const length = along[along.length - 1];
409
+ return breaks.filter((i) => along[i] > along[i - 1]).map((i) => [along[i - 1] / length, along[i] / length]);
410
+ }
411
+ function checkBreaks(breaks, count) {
412
+ if (breaks === void 0) return [];
413
+ if (!Array.isArray(breaks)) throw new RangeError(`describe.line: breaks must be an array of point indices, got ${show(breaks)}.`);
414
+ let after = 0;
415
+ breaks.forEach((index, i) => {
416
+ if (!(Number.isInteger(index) && index > after && index < count)) {
417
+ throw new RangeError(`describe.line: breaks[${i}] must be a whole number more than ${after} and less than ${count}, the number of points, got ${show(index)}.`);
418
+ }
419
+ after = index;
370
420
  });
421
+ return breaks;
371
422
  }
423
+ var show = (value) => typeof value === "string" ? JSON.stringify(value) : String(value);
372
424
 
373
425
  // src/core/geometry/describe/point.ts
374
426
  function describePoint(spec) {
@@ -389,7 +441,8 @@ function describePoint(spec) {
389
441
  ]),
390
442
  bounds: { x: center.x - r, y: center.y - r, width: 2 * r, height: 2 * r },
391
443
  center,
392
- pivot: center
444
+ pivot: center,
445
+ labelBounds: labelBoxes("point", spec.labelBounds)
393
446
  });
394
447
  }
395
448
 
@@ -497,7 +550,18 @@ function samplesAlong(mark, points) {
497
550
  });
498
551
  const n = mark.length > 0 ? Math.min(MAX_GRID, Math.ceil(mark.length) + 1) : 1;
499
552
  const grid = Array.from({ length: n }, (_, i) => mark.path(n === 1 ? 0 : i / (n - 1)));
500
- return points.map((p, index) => ({ index, sample: { t: nearest(mark, grid, p), value: p.value, ...p.at === void 0 ? {} : { at: p.at } } })).sort((a, b) => a.sample.t - b.sample.t || a.index - b.index).map(({ sample }) => sample);
553
+ const samples = points.map((p, index) => ({ index, sample: { t: nearest(mark, grid, p), value: p.value, ...p.at === void 0 ? {} : { at: p.at } } })).sort((a, b) => a.sample.t - b.sample.t || a.index - b.index).map(({ sample }) => sample);
554
+ return mark.gaps && mark.gaps.length > 0 ? gapped(samples, mark.gaps) : samples;
555
+ }
556
+ function gapped(samples, gaps) {
557
+ const middles = gaps.map(([from, to]) => (from + to) / 2).sort((a, b) => a - b);
558
+ let next = 0;
559
+ return samples.map((sample, k) => {
560
+ if (k === 0) return sample;
561
+ const before = samples[k - 1].t;
562
+ while (next < middles.length && middles[next] <= before) next++;
563
+ return next < middles.length && middles[next] <= sample.t ? { ...sample, gapBefore: true } : sample;
564
+ });
501
565
  }
502
566
  function nearest(mark, grid, p) {
503
567
  const n = grid.length;
@@ -551,4 +615,4 @@ export {
551
615
  offset,
552
616
  samplesAlong
553
617
  };
554
- //# sourceMappingURL=chunk-ZIGBM4NY.js.map
618
+ //# sourceMappingURL=chunk-CJUQHEX6.js.map