expressive-charts 0.2.0 → 0.4.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 (46) hide show
  1. package/CHANGELOG.md +69 -1
  2. package/README.md +10 -10
  3. package/dist/define-DeZLs1h7.js +95 -0
  4. package/dist/define-DeZLs1h7.js.map +1 -0
  5. package/dist/drawing-Dz_IvJPB.d.cts +208 -0
  6. package/dist/drawing-Dz_IvJPB.d.ts +208 -0
  7. package/dist/effect-CdH5449m.d.ts +232 -0
  8. package/dist/effect-uYC8Vs6_.d.cts +232 -0
  9. package/dist/expressive-charts.css +8 -1
  10. package/dist/expressive-charts.css.d.cts +1 -0
  11. package/dist/expressive-charts.css.d.ts +1 -0
  12. package/dist/expressive-charts.global.js +50 -47
  13. package/dist/expressive-charts.global.js.map +1 -1
  14. package/dist/icons/sport.cjs +211 -152
  15. package/dist/icons/sport.cjs.map +1 -1
  16. package/dist/icons/sport.d.cts +5 -7
  17. package/dist/icons/sport.d.ts +5 -7
  18. package/dist/icons/sport.js +122 -71
  19. package/dist/icons/sport.js.map +1 -1
  20. package/dist/index.cjs +12647 -9513
  21. package/dist/index.cjs.map +1 -1
  22. package/dist/index.d.cts +929 -859
  23. package/dist/index.d.ts +929 -859
  24. package/dist/index.js +10452 -7822
  25. package/dist/index.js.map +1 -1
  26. package/dist/path-data-DnEckjY8.js +123 -0
  27. package/dist/path-data-DnEckjY8.js.map +1 -0
  28. package/dist/testing.cjs +2034 -1222
  29. package/dist/testing.cjs.map +1 -1
  30. package/dist/testing.d.cts +137 -141
  31. package/dist/testing.d.ts +137 -141
  32. package/dist/testing.js +696 -501
  33. package/dist/testing.js.map +1 -1
  34. package/dist/transition-DSRt2DH3.js +2053 -0
  35. package/dist/transition-DSRt2DH3.js.map +1 -0
  36. package/package.json +18 -6
  37. package/dist/chunk-CVXP2L2J.js +0 -1182
  38. package/dist/chunk-CVXP2L2J.js.map +0 -1
  39. package/dist/chunk-N5IF2RO2.js +0 -66
  40. package/dist/chunk-N5IF2RO2.js.map +0 -1
  41. package/dist/chunk-V5IUTXRW.js +0 -571
  42. package/dist/chunk-V5IUTXRW.js.map +0 -1
  43. package/dist/drawing-DWZIXIeR.d.cts +0 -194
  44. package/dist/drawing-DWZIXIeR.d.ts +0 -194
  45. package/dist/effect-CZUckY0l.d.ts +0 -245
  46. package/dist/effect-CcGdU41j.d.cts +0 -245
package/CHANGELOG.md CHANGED
@@ -10,7 +10,7 @@ The library follows [semantic versioning](https://semver.org) from 0.1.0, with t
10
10
 
11
11
  - `defineEffect` and `defineDataEffect`, with `GeometryEffectSpec` and `DataEffectSpec`;
12
12
  - `matrix` and `offset`;
13
- - `describe.bar`, `describe.arc`, `describe.line` and `describe.point`, with their specs: `BarSpec`, `BarSegmentSpec`, `Baseline`, `ArcSpec`, `LineSpec` and `PointSpec`;
13
+ - `describe.bar`, `describe.arc`, `describe.line`, `describe.point` and `describe.shape`, with their specs: `BarSpec`, `BarSegmentSpec`, `Baseline`, `ArcSpec`, `LineSpec`, `PointSpec` and `ShapeSpec`;
14
14
  - the effect contracts (`GeometryEffect`, `DataEffect`, `TransitionEffect`, `MarkEffect`, `AnyMarkEffect`, `Combined`), the contexts (`EffectContext`, `TransitionContext`), the mark and its data (`MarkGeometry`, `Outline`, `Point`, `Rect`, `MarkData`, `Sample`), the drawing API (`Layer`, `MarkHandle`, `MarkStyle`, `Matrix`, `Paint`, `TextStyle`, `Color`, and the handles `IconHandle`, `PathHandle` and `TextHandle`), and icons as an effect gets them (`Icon`, `IconShape`, `IconSource`);
15
15
  - the motion types the context uses: `MotionView`, `MotionMode`, `Timing`, `Tween`, `TweenOptions`, `TweenResult` and `Easing`;
16
16
  - `expressive-charts/testing`: `checkEffect`, `checkTransition`, `fixtures`, `fixturePairs`, `testContext` and `play`, with their options (`CheckEffectOptions`, `CheckTransitionOptions`, `TestContextOptions`, `PlayOptions`), the fixtures' names (`FixtureName`, `FixturePairName`), the test context (`TestContext`) and what it records (`RecordingLayer`, `RecordingMark`, `Drawn`, `DrawnIcon`, `DrawnPath`, `DrawnText`, `LayerCall`, `MarkCall`, `Picture`), and the motion types they use: `Motion`, `Clock`, `ManualClock`, `ScalingOverrides` and `ScalingRule`.
@@ -25,6 +25,74 @@ 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.4.0 (27 October 2026)
29
+
30
+ Attachments that swap their effects and end their hover as charts do, `expressive()` reading circles and other SVG shapes through the new `describe.shape`, a chart switch in a link, Vega lines with gaps, the icon sets' faded parts, and a build with tsdown. In the effect-author API, `describe.shape`, `ShapeSpec`, and `fillOpacity` and `strokeOpacity` on `IconShape` are additions, and `checkEffect`'s default data on a gap is a fix, under Fixed: an effect that joins across a gap can now fail, as it should. The other changes are outside the promise, and each says what to write instead, if anything.
31
+
32
+ ### Added
33
+
34
+ - **`describe.shape`**, under the 0.x promise, with its spec, `ShapeSpec`: a mark's geometry from SVG path data, `describe.shape({ key, series, d, matrix, width, labelBounds })`. The library follows the path itself, so it works the same in Node, Vitest and every browser. `d` is read as SVG reads it, up to its first error, and `matrix` moves it into the marks' px, as an element's transform does. A shape is closed when every subpath ends with `Z`, or where it started, and otherwise open.
35
+ - An open shape is a line. Its walk follows the path, and each later move starts a new run after a gap, so a D3 line drawn with `.defined()` comes with its gaps. Its outline is the stroke, `width` px wide (default 1).
36
+ - A closed shape, such as a D3 area, has no direction, like a point: its walk has length 0, at its centre. Its outline is the whole path, holes too, sampled round its longest subpath from its upper left, so a circle samples as `describe.point`'s does.
37
+ - Béziers, and arcs that aren't circular, become straight pieces within 0.1 px of the curve, so path data still has only `M`, `L`, `A` and `Z`.
38
+ - Path data with nothing to draw, a `matrix` that isn't six finite numbers and a `width` that isn't more than 0 each throw a `RangeError` naming the field.
39
+
40
+ These are new names, so no code needs to change. The effects guide says how to check an effect on a curve or an area with it.
41
+
42
+ - **`fillOpacity` and `strokeOpacity` on `IconShape`**, under the 0.x promise: the fill's and the stroke's own opacity, each from 0 to 1 (default 1), inside the shape's `opacity`, so one shape can have a faint fill inside a full outline. `defineIcon` checks them, with a `RangeError` naming the shape and the field, and the SVG layer sets them on the shape's path. They're optional fields: code that builds an `IconShape` needs no change.
43
+ - **`expressive()` reads circles and shapes by their tags.** A `<circle>` is a point at its centre, with its radius, and a `<path>`, `<line>`, `<polyline>`, `<polygon>` or `<ellipse>` is a shape, read with `describe.shape` from its own path data, each through its transforms. So a D3 scatter, a D3 curve or area, `d3.symbol()` paths and Plot's dots need only a key, and a curve drawn with `.defined()` keeps its gaps.
44
+ - A circle under an uneven scale or a skew is an ellipse, a shape. An open shape is as wide as its stroke as drawn, scaled by its transforms; a width of 0 reads as 1 px.
45
+ - A circle with a numeric `value` gets it as its one sample, `{ t: 0, value }`, as a Vega symbol does. `segment` names a circle's or a shape's series, so a data effect can read it through `related`.
46
+ - Each is a mark of its own: a key it shares with another element throws a `TypeError` naming the key. Circles and shapes keep document order, as marks described with `geometry` do. A shape SVG wouldn't draw, such as a path with no path data, isn't a mark until it draws something.
47
+ - `watch` follows `x1`, `y1`, `x2`, `y2`, `rx` and `ry` too.
48
+
49
+ Other elements (`<text>`, `<g>`, `<use>`, `<image>`) still throw, naming their tag. Elements that threw are read now, and a page's `geometry` still wins, so no page needs to change.
50
+ - **`update({ on })` and `leave()` on attachments.** `expressive()`'s and `fromVegaView()`'s attachments swap their effects in place, as a chart's `update({ on })` does: a slot given the same effect or preset name keeps its runs, a changed slot's new effect starts where the old one's runs were, and focus and the tab stop stay, so a page with an effect picker needn't attach again. It returns a promise, which resolves at once, and rejects, changing nothing, on an unknown preset name, a series a data effect needs that the marks don't have, or any option but `on`. `leave()` ends the hover, pointer or keyboard, as a chart's does, with focus staying where it is. Both are additions.
51
+ - **Vega lines with gaps.** `fromVegaView()` reads a line that Vega breaks at a point it leaves out (`defined: false`), as Vega-Lite 6 does at a missing value by default: the line has gaps, its samples have `gapBefore` after each, and no effect draws inside one. It used to throw. A line with no point drawn has no mark, as Vega draws nothing. A curve still throws.
52
+ - **A `chartSwitch` in a `link()`.** `link()` takes a chart switch as a source, through its view on show: hovering that view hovers the other sources, and their hovers hover it. The hidden view is never hovered, and its hovers aren't linked. While a switch plays, neither view can be reached, so it neither starts a link's hover nor shows one. A hover in the view it leaves ends as it starts, and the link hears it end; when it lands, the link's hover, if there is one, shows in the new view. A source is in one link at a time, a switch's views' charts with it: a switch whose view's chart is in a link throws, and so does a view's chart whose switch is in one. `link()` no longer throws on a switch, and its types read a switch's rows from its views' charts.
53
+ - **`on()`, `marks()` and `leave()` on `ChartSwitch`**, each the view on show's, as its chart's are. `on()` hears only the view on show, typed by the views' rows; `marks()` gives its marks, while a switch plays the marks of the view it's heading for; and `leave()` ends its hover. So a switch is a `LinkSource`, and a page can call them as on a chart.
54
+
55
+ ### Changed
56
+
57
+ - **The package is built with tsdown, on Rolldown,** instead of tsup. Each entry has the same names, as an ES module and as CommonJS, with the same types, checked on TypeScript 5.4, 6 and 7. The files keep their names, but for the shared chunks, which are named by their first module. On the same code, the script-tag bundle is 6.6 KB smaller gzipped, and `expressive-charts/icons/sport` loads 4 KB with its chunks, not 9. Nothing to write instead.
58
+ - **A chart switch ends the old view's hover before `current` changes**, so `leave` listeners on that view's chart read `current` as the view the switch is leaving, not the one it's heading for. A page that wants the new view there takes it from the `show(view)` that started the switch. A `show()` such a listener calls runs once the switch has begun.
59
+
60
+ ### Fixed
61
+
62
+ - **`checkEffect`'s default data on a gap**, under the 0.x promise. On a mark with gaps, such as the `"gapped line"` fixture, it has a sample at each end of each gap, with its `t` as its value and `gapBefore` on the one after, so a data effect sees the gap as on a line chart's line. Before, it had two samples, 0 at the start and 1 at the end, on every mark, so a data effect never saw a gap. On a mark without gaps it's as before. An effect that leaves the gap alone passes as it did; one that joins across a gap can now fail, as it should. A test that needs other data passes `data`.
63
+ - **`expressive()` takes a mark's colour as the browser computes it.** A fill or stroke that the page's CSS sets to black (or `none`) over the element's own colour attribute, or its group's, was read as the attribute's colour, so the hover colour and emphasis started from it. The fallback to the attributes is for jsdom, which computes no presentation attributes; the adapter now finds which it is, once a root `<svg>`. Nothing to write instead.
64
+ - **What effects draw for a mark stays with it.** The paths and icons an effect draws in the overlay, such as `threshold`'s runs and a riding `travel` ball, now take the transform another effect gives the mark, so they rock with a `wiggle` instead of coming up to 3 px apart from it. They fade with the mark when hover dims it, on our charts and on attachments with `dim`. Before, they stayed where they were, at full strength. Text in the overlay, such as `delta`'s and `label`'s, stays put and keeps its contrast, as a mark's labels do. No effect needs to change: the drawing API's types are as they were, and so are `checkEffect`'s checks. An effect that turns its mark and draws in the overlay where the turned mark is would now turn its drawing twice: draw on the mark as it is, and let the drawing follow. In the SVG, a run's paths and icons are in a `<g class="ec-follow">` in its group, so CSS that picked them out as its children (`.ec-run > path`) needs `.ec-run path`.
65
+ - **`iconFromSvg` keeps `fill-opacity` and `stroke-opacity`**, so an icon whose SVG fades a part's fill or stroke with them draws as its SVG does. Before, the faded part drew at full strength. They're read from attributes and `style`, as numbers or percentages, and inherited through groups as SVG inherits them: a shape's own replaces its group's, rather than multiplying as `opacity` does. A fill or stroke faded to 0 is dropped, as `none` is, and so is a shape left with neither. An icon made from SVG without them comes out the same. A long `width` or `height` on an `<svg>` with no viewBox is now read at once, too: a run of 100,000 digits followed by a letter took 23 s.
66
+
67
+ ## 0.3.0 (27 October 2026)
68
+
69
+ 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.
70
+
71
+ ### Added
72
+
73
+ - **`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.
74
+ - **`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.
75
+ - **`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.
76
+ - **`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.
77
+ - **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.
78
+ - **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.
79
+ - **`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`.
80
+ - **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.
81
+
82
+ ### Changed
83
+
84
+ - **`"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.
85
+ - **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`.
86
+ - **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; }`.
87
+ - **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.
88
+
89
+ ### Fixed
90
+
91
+ - **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.
92
+ - **`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.
93
+ - **`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.
94
+ - **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.
95
+
28
96
  ## 0.2.0 (26 October 2026)
29
97
 
30
98
  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.
package/README.md CHANGED
@@ -15,7 +15,7 @@ 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.2.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#020-26-october-2026) lists what's new and what changed since 0.1.0.
18
+ > **Status: 0.4.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#040-27-october-2026) lists what's new and what changed since 0.3.0.
19
19
 
20
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
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.
@@ -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 29 KB gzipped, and everything 68 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 30 KB gzipped, and everything 76 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.2/dist/expressive-charts.global.js"></script>
37
+ <script src="https://cdn.jsdelivr.net/npm/expressive-charts@0.4/dist/expressive-charts.global.js"></script>
38
38
  <script>
39
39
  const { barChart } = ExpressiveCharts;
40
40
  barChart("#sales", {
@@ -124,10 +124,10 @@ 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.
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
- - **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.
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
+ - **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. Its `on()`, `marks()` and `leave()` are the view on show's, and it can be linked like a chart.
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, with only a key: rects as bars, circles as points, and paths, lines, polylines, polygons and ellipses as shapes, through their transforms. It draws on an overlay, leaving the host's styling alone; `watch: true` follows the host's own transitions. A curve, or a line drawn with d3's `.defined()`, is read from its own path data, with its gaps, and no effect draws inside them; `geometry` describes anything else, or a mark as you'd rather have it. Observable Plot binds each rect or dot 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 marks. 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; a line breaks where Vega-Lite leaves out a missing value. Both change their effects in place with `update({ on })`, as a chart does, and `leave()` ends their hover.
130
+ - **Linked hover.** [`link()`](https://github.com/Deaversbp/expressive-charts/blob/main/docs/api.md#link) links hover across charts, chart switches 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
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"`).
132
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.
133
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.
@@ -170,7 +170,7 @@ The script-tag bundle, `dist/expressive-charts.global.js`, is the main entry alo
170
170
  ## Browsers and TypeScript
171
171
 
172
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.
173
- - **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.
174
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.
175
175
 
176
176
  ## Content-Security-Policy
@@ -193,12 +193,12 @@ The package lists its CSS under `sideEffects`, so bundlers keep that import. Cha
193
193
  ## Accessibility
194
194
 
195
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.
196
- - **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()`.
197
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.
198
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).
199
199
  - **Other people's charts.** `expressive()` adds the same keyboard focus with `keyboard: true`, and one name per mark with `markLabel`.
200
200
 
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). Known gaps: the tooltip can't be hovered itself (it can be dismissed with Escape), 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.
202
202
 
203
203
  ## Limits
204
204
 
@@ -0,0 +1,95 @@
1
+ // src/icons/define.ts
2
+ const GAITS = [
3
+ "roll",
4
+ "step",
5
+ "slide"
6
+ ];
7
+ const LINECAPS = ["butt", "round"];
8
+ const LINEJOINS = ["miter", "round"];
9
+ const FILL_RULES = ["nonzero", "evenodd"];
10
+ const PATH_DATA = /^\s*[Mm][MmLlHhVvCcSsQqTtAaZz0-9eE.,+\-\s]*$/;
11
+ function defineIcon(spec) {
12
+ const name = spec?.name;
13
+ if (typeof name !== "string" || name === "") throw new TypeError(`defineIcon needs a non-empty string name, got ${JSON.stringify(name)}.`);
14
+ const fail = (field, problem) => {
15
+ throw new RangeError(`defineIcon: "${name}" ${field} ${problem}.`);
16
+ };
17
+ const finite = (field, value) => typeof value === "number" && Number.isFinite(value) ? value : fail(field, `must be a finite number, got ${String(value)}`);
18
+ const positive = (field, value) => finite(field, value) > 0 ? value : fail(field, `must be more than 0, got ${String(value)}`);
19
+ const point = (field, value) => value && typeof value === "object" ? freeze({
20
+ x: finite(`${field}.x`, value.x),
21
+ y: finite(`${field}.y`, value.y)
22
+ }) : fail(field, "must be a point { x, y }");
23
+ if (!Array.isArray(spec.shapes) || spec.shapes.length === 0) fail("shapes", "must be a non-empty array");
24
+ const shapes = spec.shapes.map((shape, i) => checkShape(shape, `shapes[${i}]`, fail, finite));
25
+ const b = spec.box;
26
+ if (!b || typeof b !== "object") fail("box", "must be a rectangle { x, y, width, height }");
27
+ const box = freeze({
28
+ x: finite("box.x", b.x),
29
+ y: finite("box.y", b.y),
30
+ width: positive("box.width", b.width),
31
+ height: positive("box.height", b.height)
32
+ });
33
+ const anchor = point("anchor", spec.anchor);
34
+ const pivot = spec.pivot === void 0 ? anchor : point("pivot", spec.pivot);
35
+ const footprint = spec.footprint ?? [Math.max(0, anchor.x - box.x), Math.max(0, box.x + box.width - anchor.x)];
36
+ if (!Array.isArray(footprint) || footprint.length !== 2) fail("footprint", "must be [behind, ahead]");
37
+ footprint.forEach((reach, i) => {
38
+ if (finite(`footprint[${i}]`, reach) < 0) fail(`footprint[${i}]`, `can't be negative, got ${reach}`);
39
+ });
40
+ const size = spec.size === void 0 ? box.width : positive("size", spec.size);
41
+ const radius = spec.radius === void 0 ? box.height / 2 : positive("radius", spec.radius);
42
+ if (spec.gait !== void 0 && !GAITS.includes(spec.gait)) fail("gait", `must be roll, step or slide, got ${String(spec.gait)}`);
43
+ if (spec.upright !== void 0 && typeof spec.upright !== "boolean") fail("upright", `must be true or false, got ${String(spec.upright)}`);
44
+ return freeze({
45
+ name,
46
+ shapes: freeze(shapes),
47
+ box,
48
+ size,
49
+ anchor,
50
+ pivot,
51
+ footprint: freeze([footprint[0], footprint[1]]),
52
+ ...spec.gait !== void 0 ? { gait: spec.gait } : {},
53
+ radius,
54
+ ...spec.upright !== void 0 ? { upright: spec.upright } : {}
55
+ });
56
+ }
57
+ function checkShape(shape, field, fail, finite) {
58
+ if (!shape || typeof shape !== "object") fail(field, "must be a shape { d, fill?, stroke?, … }");
59
+ if (typeof shape.d !== "string" || !PATH_DATA.test(shape.d)) fail(`${field}.d`, "must be path data starting with a move");
60
+ if (shape.clip !== void 0 && (typeof shape.clip !== "string" || !PATH_DATA.test(shape.clip))) fail(`${field}.clip`, "must be path data starting with a move");
61
+ for (const paint of ["fill", "stroke"]) {
62
+ const value = shape[paint];
63
+ if (value !== void 0 && (typeof value !== "string" || value === "")) fail(`${field}.${paint}`, `must be a colour, got ${String(value)}`);
64
+ }
65
+ if (shape.width !== void 0 && finite(`${field}.width`, shape.width) < 0) fail(`${field}.width`, `can't be negative, got ${shape.width}`);
66
+ if (shape.linecap !== void 0 && !LINECAPS.includes(shape.linecap)) fail(`${field}.linecap`, `must be butt or round, got ${String(shape.linecap)}`);
67
+ if (shape.linejoin !== void 0 && !LINEJOINS.includes(shape.linejoin)) fail(`${field}.linejoin`, `must be miter or round, got ${String(shape.linejoin)}`);
68
+ if (shape.fillRule !== void 0 && !FILL_RULES.includes(shape.fillRule)) fail(`${field}.fillRule`, `must be nonzero or evenodd, got ${String(shape.fillRule)}`);
69
+ for (const key of [
70
+ "opacity",
71
+ "fillOpacity",
72
+ "strokeOpacity"
73
+ ]) {
74
+ const opacity = shape[key] === void 0 ? 1 : finite(`${field}.${key}`, shape[key]);
75
+ if (opacity < 0 || opacity > 1) fail(`${field}.${key}`, `must be from 0 to 1, got ${opacity}`);
76
+ }
77
+ const copy = { d: shape.d };
78
+ for (const key of [
79
+ "fill",
80
+ "stroke",
81
+ "width",
82
+ "linecap",
83
+ "linejoin",
84
+ "clip",
85
+ "fillRule",
86
+ "opacity",
87
+ "fillOpacity",
88
+ "strokeOpacity"
89
+ ]) if (shape[key] !== void 0) copy[key] = shape[key];
90
+ return freeze(copy);
91
+ }
92
+ const freeze = (value) => Object.freeze(value);
93
+ export { defineIcon as t };
94
+
95
+ //# sourceMappingURL=define-DeZLs1h7.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"define-DeZLs1h7.js","names":[],"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 for (const key of [\"opacity\", \"fillOpacity\", \"strokeOpacity\"] as const) {\n const opacity = shape[key] === undefined ? 1 : finite(`${field}.${key}`, shape[key]);\n if (opacity < 0 || opacity > 1) fail(`${field}.${key}`, `must be from 0 to 1, got ${opacity}`);\n }\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\", \"fillOpacity\", \"strokeOpacity\"] 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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"}
@@ -0,0 +1,208 @@
1
+ interface Point {
2
+ readonly x: number;
3
+ readonly y: number;
4
+ }
5
+ interface Rect {
6
+ readonly x: number;
7
+ readonly y: number;
8
+ readonly width: number;
9
+ readonly height: number;
10
+ }
11
+ interface Outline {
12
+ /** SVG path data in the mark's coordinate space. */
13
+ readonly d: string;
14
+ /** True for areas (bars, slices, markers), false for strokes (lines). */
15
+ readonly closed: boolean;
16
+ /**
17
+ * Closed outlines: n points (n a multiple of 4), walking clockwise on screen from the start-left
18
+ * corner, n/4 per side in the order left, end, right, start, evenly spaced along each side. The
19
+ * corners are at indices 0, n/4, n/2 and 3n/4. Open outlines: n points along the stroke, from
20
+ * start to end inclusive. Morph depends on this.
21
+ */
22
+ sample(n: number): readonly Point[];
23
+ }
24
+ interface MarkGeometry {
25
+ /** Stable identity across updates. Segments are keyed "<mark key>/<series>". */
26
+ readonly key: string;
27
+ /** The series this mark or segment belongs to, if any ("goals", "xg"). */
28
+ readonly series?: string;
29
+ /** Equals path(0). */
30
+ readonly start: Point;
31
+ /** Equals path(1). */
32
+ readonly end: Point;
33
+ /** Length of the walk in px; 0 for marks with no direction (a scatter dot). */
34
+ readonly length: number;
35
+ /** t in [0, 1], proportional to distance along the walk. Values outside are clamped. */
36
+ path(t: number): Point;
37
+ /** Direction of travel in radians, in (-PI, PI]; the mark's "up" side is angle - PI/2. */
38
+ angle(t: number): number;
39
+ /** SVG path data for the part of the walk between t0 and t1, in either order. It leaves out the gaps. */
40
+ slice(t0: number, t1: number): string;
41
+ /**
42
+ * The stretches of the walk with no data, as [from, to] values of t, in order and apart: each with
43
+ * 0 ≤ from < to ≤ 1, ending at or before the next starts. A line that skips a value has one, from
44
+ * the value before to the value after. The walk runs straight across a gap, so `path` and `angle`
45
+ * work as on any walk, and `outline.sample(n)` runs along it all; `slice()` and an open outline's
46
+ * `d` leave the gaps out, with a moveto across each. Unset means none.
47
+ */
48
+ readonly gaps?: readonly (readonly [from: number, to: number])[];
49
+ /** Px across the walk: bar height, ring width, stroke width, marker diameter. */
50
+ readonly thickness: number;
51
+ readonly outline: Outline;
52
+ readonly bounds: Rect;
53
+ /** Visual centre: tooltips, focus rings, labels. */
54
+ readonly center: Point;
55
+ /** Where the mark is attached to the chart: a bar's baseline, a donut's centre. */
56
+ readonly pivot: Point;
57
+ /**
58
+ * The boxes of the text the chart draws for this mark, so an effect's text can keep clear of
59
+ * them: a bar's category and value labels, a slice's label outside the ring, a line's end label.
60
+ * Unset when nothing says where they are (segments, points, and marks the library didn't draw).
61
+ */
62
+ readonly labelBounds?: readonly Rect[];
63
+ /** Ordered parts, from the baseline (goals, then assists). Every bar has at least one. */
64
+ readonly segments?: readonly MarkGeometry[];
65
+ }
66
+ /** One path of an icon, drawn in order (the first is at the bottom). */
67
+ interface IconShape {
68
+ /** Path data in icon units. */
69
+ readonly d: string;
70
+ /** Unset draws no fill (unlike SVG, where it's black). */
71
+ readonly fill?: Color;
72
+ /** Unset draws no stroke. */
73
+ readonly stroke?: Color;
74
+ /** Stroke width in icon units, so it scales with the icon. Default 1. */
75
+ readonly width?: number;
76
+ /** Default "butt". */
77
+ readonly linecap?: "butt" | "round";
78
+ /** Default "miter". */
79
+ readonly linejoin?: "miter" | "round";
80
+ /** Path data, in icon units, that clips this shape (the ball's panel pattern). */
81
+ readonly clip?: string;
82
+ /** Default "nonzero". "evenodd" leaves a hole where the path's parts overlap, as solid icon sets draw them. */
83
+ readonly fillRule?: "nonzero" | "evenodd";
84
+ /** From 0 to 1, for the whole shape, fill and stroke together (a duotone set's lighter part). Default 1. */
85
+ readonly opacity?: number;
86
+ /** From 0 to 1, the fill's own, inside `opacity` (a set that fades only a part's fill). Default 1. */
87
+ readonly fillOpacity?: number;
88
+ /** From 0 to 1, the stroke's own, inside `opacity`. Default 1. */
89
+ readonly strokeOpacity?: number;
90
+ }
91
+ /**
92
+ * Build one with defineIcon() or iconFromSvg(), which fill the defaults and check it. Icon units
93
+ * are px at the icon's natural size: `layer.icon(icon, { size })` scales it by size / icon.size
94
+ * about its anchor before `place()`.
95
+ */
96
+ interface Icon {
97
+ readonly name: string;
98
+ /** Drawn facing +x, with its up side towards −y, in icon units. */
99
+ readonly shapes: readonly IconShape[];
100
+ /** Icon-space bounds. */
101
+ readonly box: Rect;
102
+ /** The natural length along the walk, in px (and icon units). */
103
+ readonly size: number;
104
+ /** The icon-space point that sits on the walk. */
105
+ readonly anchor: Point;
106
+ /** What it spins or tilts around. */
107
+ readonly pivot: Point;
108
+ /** Extent along +x from the anchor, which travel keeps inside the mark. */
109
+ readonly footprint: readonly [behind: number, ahead: number];
110
+ /** The gait travel uses unless it's given one. */
111
+ readonly gait?: "roll" | "step" | "slide";
112
+ /** Rolling radius; default box height / 2. */
113
+ readonly radius?: number;
114
+ /** Mirror instead of turning upside down (a boot keeps its sole down). */
115
+ readonly upright?: boolean;
116
+ }
117
+ /** Resolves icon names; the composition root fills it from the icon registry. */
118
+ interface IconSource {
119
+ get(name: string): Icon | undefined;
120
+ }
121
+ /**
122
+ * A theme token or any CSS colour. Tokens: "text", "text-muted", "surface", "grid", "axis", "focus",
123
+ * "negative", "series-N" and "series-N-strong" (palette slots 1–8), and "mark" / "mark-strong", the
124
+ * colours of the mark a run belongs to (its first segment's, for a stack).
125
+ */
126
+ type Color = string;
127
+ /**
128
+ * A 2D affine transform in SVG order: x' = a·x + c·y + e, y' = b·x + d·y + f.
129
+ * Build one with the `matrix` helpers.
130
+ */
131
+ type Matrix = readonly [a: number, b: number, c: number, d: number, e: number, f: number];
132
+ interface Paint {
133
+ readonly fill?: Color;
134
+ readonly stroke?: Color;
135
+ readonly width?: number;
136
+ readonly opacity?: number;
137
+ readonly linecap?: "butt" | "round";
138
+ }
139
+ interface MarkStyle {
140
+ /** In chart space. Moves the mark's body; its labels and pointer target stay put. */
141
+ readonly transform?: Matrix;
142
+ readonly opacity?: number;
143
+ /** 0–1 toward the series' strong colour. */
144
+ readonly emphasis?: number;
145
+ /**
146
+ * A stroke along the outline, behind the mark. `width` is the stroke width, so half of it shows
147
+ * outside the mark (the prototype's flash peaks at 8). Default colour: the mark's own.
148
+ */
149
+ readonly halo?: {
150
+ readonly width: number;
151
+ readonly opacity: number;
152
+ readonly color?: Color;
153
+ };
154
+ }
155
+ /** Restyles the mark itself. The runner resets it when the run is cleared. */
156
+ interface MarkHandle {
157
+ /** Changes only the fields given, so parallel effects don't undo each other. A field given as undefined goes back to its default. */
158
+ set(style: MarkStyle): void;
159
+ /** Back to the mark's own style. */
160
+ reset(): void;
161
+ }
162
+ interface IconHandle {
163
+ /** Moves the icon: a transform from icon space into chart space. The icon is hidden until first placed. */
164
+ place(transform: Matrix): void;
165
+ remove(): void;
166
+ }
167
+ interface PathHandle {
168
+ /** Replaces the path data; paint fields given are merged into the current paint. */
169
+ update(d: string, paint?: Partial<Paint>): void;
170
+ remove(): void;
171
+ }
172
+ /** Effects that label a change ("+2") need text, drawn in theme text colours by default. */
173
+ interface TextStyle {
174
+ /** The anchor point, on the text's baseline. */
175
+ readonly at: Point;
176
+ readonly anchor?: "start" | "middle" | "end";
177
+ /** Default "text". Series colours are allowed only for swatches, never for words. */
178
+ readonly color?: Color;
179
+ readonly opacity?: number;
180
+ }
181
+ interface TextHandle {
182
+ /** Style fields given are merged into the current style; content is replaced if given. */
183
+ update(style: Partial<TextStyle>, content?: string): void;
184
+ remove(): void;
185
+ }
186
+ /** One run's own overlay group, above the marks, in chart coordinates. The runner empties it when the run is cleared. */
187
+ interface Layer {
188
+ /**
189
+ * Draws an icon, hidden until its first `place()`.
190
+ *
191
+ * Size rule: with `size`, the icon is scaled by `size / icon.size` about its anchor, in icon space,
192
+ * before the `place()` transform. So effects build the transform as if the icon were its natural
193
+ * size, and the anchor still lands where the transform puts it. Icon-space lengths (footprint,
194
+ * radius, the pivot's offset from the anchor) scale by the same factor. A negative size throws.
195
+ *
196
+ * Each shape is one path, in order (the first at the bottom). An unset `fill` or `stroke` draws
197
+ * none; `width` is in icon units (default 1), so it scales with the icon. `clip` is path data in
198
+ * icon space.
199
+ */
200
+ icon(icon: Icon, options?: {
201
+ readonly size?: number;
202
+ }): IconHandle;
203
+ /** Draws an overlay path, unfilled unless `paint.fill` is given. */
204
+ path(d: string, paint: Paint): PathHandle;
205
+ text(content: string, style: TextStyle): TextHandle;
206
+ }
207
+ export { Rect as _, MarkStyle as a, PathHandle as c, Icon as d, IconShape as f, Point as g, Outline as h, MarkHandle as i, TextHandle as l, MarkGeometry as m, IconHandle as n, Matrix as o, IconSource as p, Layer as r, Paint as s, Color as t, TextStyle as u };
208
+ //# sourceMappingURL=drawing-Dz_IvJPB.d.cts.map