expressive-charts 0.10.0 → 0.11.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md CHANGED
@@ -25,6 +25,17 @@ 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
+ From 1.0, everything the package exports follows semantic versioning: the motion core, the charts, the adapters, the built-in effects and the controls, as well as the effect-author API.
29
+
30
+ ## 0.11.0 (12 November 2026)
31
+
32
+ Guides that stay put through a chart switch: a view names its axes, grids and ticks, and one that both views draw the same stays on screen, where it is, while the marks morph; and `hostView([a, b, c])`, one switch view of several attachments on one `<svg>`, so a chart drawn with more than one attachment, such as a dumbbell, switches as one chart. Nothing in the effect-author API changes. Every change is an addition outside the promise, and none needs anything written instead. The 0.x promise, above, now says what 1.0 will promise.
33
+
34
+ ### Added
35
+
36
+ - **Guides that stay put through a chart switch:** `guides()` on `ChartSwitchView`, with `ChartSwitchGuide`, and `hostView()`'s `guides` option, with `HostGuide`. A view names its guides, each an element in its `<svg>` (an axis, a grid, a tick) with a key of its own. While a switch plays, a guide whose key the other view has too, drawn the same (the same markup in the same computed paint, ids left out, at the same place within 0.5 px and the same scale), stays on screen at full strength, where it is: the old view's until half way, the new view's from there, through a switch back, a staged jump and a third view. Every other guide fades with its view's other parts, as before. The switch draws each as a copy in its overlay, below the pairs, and a host view hides its own while a switch plays, through the attachment's edits, and again after a refresh. A view with no guides, as our charts are, switches as before, byte for byte.
37
+ - **`hostView([a, b, c])`: one chart switch view of several attachments on one `<svg>`,** so a chart drawn with more than one attachment, such as a dumbbell's dots for each half and the lines between them, switches as one chart. Its marks are all of theirs, and each mark's focus, tab stop, colour and hiding go to the attachment it's from; the labels and guides are the view's, the whole `<svg>`'s. Each key must be one mark's, so a page keys the attachments' marks apart (`first@Okafor`): `hostView()` throws a `TypeError` naming a key two of them have, or two attachments in different `<svg>`s, and a clash a later refresh makes is reported as each switch starts, the key staying the first attachment's. A link between the attachments goes on, and the view takes no part in a link of its switch. `refresh()`, `update()`, `on()`, `leave()` and `destroy()` go to each. `hostView(attachment)` draws as before, byte for byte.
38
+
28
39
  ## 0.10.0 (11 November 2026)
29
40
 
30
41
  A chart switch that stages a jump through a third view, `show(view, { via })`, so bars side by side can stack before they become shares of 100%; `morph()` pairing two areas across the same x's by x, so stacked areas keep each week's x as they become shares of 100%; and a host view drawn again mid-switch keeping its new marks and labels hidden until the switch lands. The type declarations are built with tsdown 0.23.7, with the same types. Nothing in the effect-author API changes. Every change is outside the promise, and none needs anything written instead.
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.10.0 (November 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#0100-11-november-2026) lists what's new and what changed since 0.9.0.
18
+ > **Status: 0.11.0 (November 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#0110-12-november-2026) lists what's new and what changed since 0.10.0.
19
19
 
20
20
  - **Effects first.** The mark effects `travel`, `flash`, `wiggle`, `pulse`, `trace`, `drawIn` 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 32 KB gzipped, and everything 90 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 32 KB gzipped, and everything 92 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.10/dist/expressive-charts.global.js"></script>
37
+ <script src="https://cdn.jsdelivr.net/npm/expressive-charts@0.11/dist/expressive-charts.global.js"></script>
38
38
  <script>
39
39
  const { barChart } = ExpressiveCharts;
40
40
  barChart("#sales", {
@@ -125,7 +125,7 @@ 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, straight or, with `curve: "monotone"`, curved through every value without going past it, on a number axis or, when `x` gives `Date`s, a time axis in UTC (or `timeZone: "local"`, or a zone's name such as `"Europe/London"`) worded in the page's locale, with a gap wherever a value is `null` or `undefined`, which its names, tooltip and table say is `missing` ("missing" by default), hovering every series at an x with a crosshair or, with `hover: "point"`, the one point nearest the pointer, the other lines dimmed. 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, a line chart's points growing into columns keyed as they are, or one line chart's lines becoming another's, and back from wherever it is. Each mark keeps its view's colour, a line its end dot and a point its ring, and focus follows the x, or the tab stop does when focus is on a toggle. In Presentation, `show(view, { via })` stages a jump through a third view, as side-by-side columns stack before they become shares, and announces only where it lands. Its `on()`, `marks()` and `leave()` are the view on show's, and it can be linked like a chart. [`hostView()`](https://github.com/Deaversbp/expressive-charts/blob/main/docs/api.md#hostview) makes an attachment a view, so a D3 pie morphs into D3 columns, or into ours: the host's marks morph in its own colours, the labels the page names move and swap, its axes fade, and with `keyboard: true` focus follows by key.
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, a line chart's points growing into columns keyed as they are, or one line chart's lines becoming another's, and back from wherever it is. Each mark keeps its view's colour, a line its end dot and a point its ring, and focus follows the x, or the tab stop does when focus is on a toggle. In Presentation, `show(view, { via })` stages a jump through a third view, as side-by-side columns stack before they become shares, and announces only where it lands. Its `on()`, `marks()` and `leave()` are the view on show's, and it can be linked like a chart. [`hostView()`](https://github.com/Deaversbp/expressive-charts/blob/main/docs/api.md#hostview) makes an attachment a view, so a D3 pie morphs into D3 columns, or into ours: the host's marks morph in its own colours, the labels the page names move and swap, the guides it names (an axis, a grid, a tick) stay where they are when the next view draws them the same, its other parts fade, and with `keyboard: true` focus follows by key. `hostView([a, b, c])` makes one view of several attachments on one `<svg>`, keyed apart, so a dumbbell drawn as each half's dots and the lines between them switches as one chart, and their link goes on.
129
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, a pie's or a donut's paths as slices, clockwise from 12 o'clock, and other paths, lines, polylines, polygons, ellipses and turned rects as shapes, through their transforms, a non-scaling stroke at its width on screen. 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.19. [`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, and a curve is read from the path Vega draws. Both change their effects in place with `update({ on })`, as a chart does, and `leave()` ends their hover.
130
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. A line chart's x with every value missing links by its x, and a link's hover there shows the line's crosshair.
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; [`drawIn`](https://github.com/Deaversbp/expressive-charts/blob/main/docs/api.md#drawin) draws a mark in along its walk as it enters, a stack part by part in its colours; [`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 and clear of other effects' text. Each goes in an effect slot (`hover`, `enter`, `update`, `exit`, `decorate`), as an effect or a preset's name (`"wiggle"`).
@@ -169,7 +169,7 @@ The script-tag bundle, `dist/expressive-charts.global.js`, is the main entry alo
169
169
 
170
170
  ## Browsers and TypeScript
171
171
 
172
- - **Browsers.** Current Chrome and Edge, Firefox, and Safari. Every DOM check in the test suite (names, roles, tab order, focus rings, tooltips, keys, switches and reduced motion), with axe's accessibility rules, runs in Chromium, Firefox and WebKit, in Playwright 1.64; the screenshots are Chromium's. That's each browser's engine, not a device: Safari on macOS and iOS hasn't been run itself. The build targets ES2020.
172
+ - **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.65; 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
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
 
@@ -217,7 +217,7 @@ The first draw of 1,000 static bars takes about 90 ms, and of 10,000 about a sec
217
217
 
218
218
  ## The 0.x promise
219
219
 
220
- From 0.1.0 the library follows semantic versioning. While it's 0.x, the effect-author API (`defineEffect`, `defineDataEffect`, `describe`, `matrix`, `offset`, the effect contracts and `expressive-charts/testing`) breaks only in a minor release, with a migration note, and a deprecated name keeps working for one minor release. The charts, adapters, built-in effects, controls and motion core can still change in a minor release, and [CHANGELOG.md](https://github.com/Deaversbp/expressive-charts/blob/main/CHANGELOG.md#the-0x-promise) lists every change. [docs/api.md](https://github.com/Deaversbp/expressive-charts/blob/main/docs/api.md) marks each promised name.
220
+ From 0.1.0 the library follows semantic versioning. While it's 0.x, the effect-author API (`defineEffect`, `defineDataEffect`, `describe`, `matrix`, `offset`, the effect contracts and `expressive-charts/testing`) breaks only in a minor release, with a migration note, and a deprecated name keeps working for one minor release. The charts, adapters, built-in effects, controls and motion core can still change in a minor release, and [CHANGELOG.md](https://github.com/Deaversbp/expressive-charts/blob/main/CHANGELOG.md#the-0x-promise) lists every change. [docs/api.md](https://github.com/Deaversbp/expressive-charts/blob/main/docs/api.md) marks each promised name. From 1.0, everything the package exports follows semantic versioning.
221
221
 
222
222
  ## Links
223
223
 
@@ -227,7 +227,7 @@ From 0.1.0 the library follows semantic versioning. While it's 0.x, the effect-a
227
227
  - [Examples](https://github.com/Deaversbp/expressive-charts/tree/main/docs/sketches/examples): pages written against the API, which `npm run typecheck` checks: ball-and-cleat bars, a goals vs xG line with playback, a donut that morphs into columns, D3 charts, effects of your own and presets.
228
228
  - [Changelog](https://github.com/Deaversbp/expressive-charts/blob/main/CHANGELOG.md), and [the development log](https://github.com/Deaversbp/expressive-charts/blob/main/docs/plan.md): the plan the library was built to, milestone by milestone, with the reasoning behind each decision.
229
229
  - [Accessibility audit](https://github.com/Deaversbp/expressive-charts/blob/main/docs/a11y-audit.md) and [screen-reader scripts](https://github.com/Deaversbp/expressive-charts/blob/main/docs/a11y-check.md).
230
- - [Demos](https://github.com/Deaversbp/expressive-charts/tree/main/demo), on [the demo site](https://deaversbp.github.io/expressive-charts/), or served by `npm run dev`. `bars.html`, `donut.html`, `line.html` and `morph.html` put the library's charts beside D3, Vega-Lite and hand-written ones, with the same effects on each; `season.html` links three charts by matchweek and labels each change with `delta()` and `label()`; `shapes.html` and `charts.html` attach the effects to circles, curves and areas, and to a waterfall, a dumbbell, a radar and a butterfly, drawn with D3 and Observable Plot; `layouts.html` switches D3 charts between layouts with `hostView()` and `morph()`: bars side by side, stacked and at 100%, areas stacked and at 100%, a radar into bars and a treemap into bars; `stress.html` is the limits above; and `lab.html` is the single-file prototype the library grew out of.
230
+ - [Demos](https://github.com/Deaversbp/expressive-charts/tree/main/demo), on [the demo site](https://deaversbp.github.io/expressive-charts/), or served by `npm run dev`. `bars.html`, `donut.html`, `line.html` and `morph.html` put the library's charts beside D3, Vega-Lite and hand-written ones, with the same effects on each; `season.html` links three charts by matchweek and labels each change with `delta()` and `label()`; `shapes.html` and `charts.html` attach the effects to circles, curves and areas, and to a waterfall, a dumbbell, a radar and a butterfly, drawn with D3 and Observable Plot; `layouts.html` switches D3 charts between layouts with `hostView()` and `morph()`: bars side by side, stacked and at 100%, areas stacked and at 100%, a radar into bars, a treemap into bars, and the charts page's dumbbell, three attachments as one view, into bars, with the axes both layouts draw the same kept on screen; `stress.html` is the limits above; and `lab.html` is the single-file prototype the library grew out of.
231
231
  - [Contributing](https://github.com/Deaversbp/expressive-charts/blob/main/CONTRIBUTING.md) and [issues](https://github.com/Deaversbp/expressive-charts/issues).
232
232
 
233
233
  ## Development