expressive-charts 0.3.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 +40 -1
  2. package/README.md +6 -6
  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 +2 -0
  10. package/dist/expressive-charts.css.d.cts +1 -2
  11. package/dist/expressive-charts.css.d.ts +1 -2
  12. package/dist/expressive-charts.global.js +45 -47
  13. package/dist/expressive-charts.global.js.map +1 -1
  14. package/dist/icons/sport.cjs +211 -156
  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 +12632 -9979
  21. package/dist/index.cjs.map +1 -1
  22. package/dist/index.d.cts +913 -871
  23. package/dist/index.d.ts +913 -871
  24. package/dist/index.js +10444 -8232
  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 +2030 -1252
  29. package/dist/testing.cjs.map +1 -1
  30. package/dist/testing.d.cts +135 -139
  31. package/dist/testing.d.ts +135 -139
  32. package/dist/testing.js +696 -499
  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 +6 -6
  37. package/dist/chunk-7A7LXXT4.js +0 -70
  38. package/dist/chunk-7A7LXXT4.js.map +0 -1
  39. package/dist/chunk-CJUQHEX6.js +0 -618
  40. package/dist/chunk-CJUQHEX6.js.map +0 -1
  41. package/dist/chunk-N2BLUETM.js +0 -1194
  42. package/dist/chunk-N2BLUETM.js.map +0 -1
  43. package/dist/drawing-CdTgixMY.d.cts +0 -206
  44. package/dist/drawing-CdTgixMY.d.ts +0 -206
  45. package/dist/effect-Bu3MHHeg.d.ts +0 -247
  46. package/dist/effect-D4vmdYP4.d.cts +0 -247
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,45 @@ 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
+
28
67
  ## 0.3.0 (27 October 2026)
29
68
 
30
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.
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.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.
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 31 KB gzipped, and everything 72 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.3/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", {
@@ -125,9 +125,9 @@ playButton("#play", season, { labels: { play: "Play season" } });
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
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.
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.
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.
@@ -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