expressive-charts 0.8.0 → 0.9.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 +13 -0
- package/README.md +6 -6
- package/dist/expressive-charts.global.js +6 -6
- package/dist/expressive-charts.global.js.map +1 -1
- package/dist/index.cjs +196 -26
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +156 -94
- package/dist/index.d.ts +156 -94
- package/dist/index.js +196 -27
- package/dist/index.js.map +1 -1
- package/package.json +2 -2
package/CHANGELOG.md
CHANGED
|
@@ -25,6 +25,19 @@ 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.9.0 (3 November 2026)
|
|
29
|
+
|
|
30
|
+
Host charts in a chart switch: `hostView()` makes an `expressive()` or `fromVegaView()` attachment a switch's view, so a D3 pie can morph into D3 columns as our donut morphs into our columns, with the switch's optional `keyOf`, `morphing`, `space` and `cssColor` for it; and `expressive()` measuring its effects' text again when it changes size. Nothing in the effect-author API changes. Every change is outside the promise, and none needs anything written instead.
|
|
31
|
+
|
|
32
|
+
### Added
|
|
33
|
+
|
|
34
|
+
- **`hostView()`**, with `HostView`, `HostViewOptions` and `HostLabel`: an attachment that `expressive()` or `fromVegaView()` returned, as a view for `chartSwitch`, so a switch takes host charts. A D3 pie morphs into D3 columns as our donut morphs into our columns, and a host chart and one of ours can share a switch. While a switch plays, the host's mark elements and the labels the page names (`labels`: each `<text>` with its mark's key and role) are hidden inline, through the attachment's own edits, and they're as the host had them once it lands. The labels move and swap their text, in the host text's computed font and fill, at the size the host draws them, and the host's axes and other text fade with its view. Each mark morphs in the host's own colour, its fill or its stroke on a line, a pair in the new view's. With `keyboard: true` on the attachment, focus and the tab stop follow by key, and nothing new is written into the host's DOM. `announce` says the host `<svg>`'s `aria-label`. The view is the attachment's own handle too, so `chart(view)` gives `refresh()` and `update({ on })`, and it's linkable. Anything but an attachment with marks throws a `TypeError`.
|
|
35
|
+
- **`keyOf(element)`, `morphing(on)` and `space` on `ChartSwitchView`, and `cssColor` on `ChartSwitchPaint`,** all optional: a mark's key from its elements, which the switch asks first when it remembers focus; the view hiding its own marks while a switch plays; the element whose space its marks and labels are in; and a mark's own colour, drawn in place of its name's slot. A host view has them. A view without them switches as before, byte for byte.
|
|
36
|
+
|
|
37
|
+
### Fixed
|
|
38
|
+
|
|
39
|
+
- **`expressive()` measures its effects' text again when the text changes size.** An attachment measured a `delta`'s or a `label`'s text once, as it drew, and never again, not even once web fonts loaded. So spacing a viewer adds after load (WCAG 1.4.12's), or a font or size set on the page, widened the text without placing it again, and the text after it could stand on it. Now an attachment keeps a hidden line of text, with no class, in its root `<svg>`, just before its overlay, watched with a `ResizeObserver`, and listens for web fonts loading, as the charts do. When its text changes size, it measures again and places its effects' text again, with no event. A new `<svg>` given to `refresh()` takes the line with it, and `destroy()` takes it out. Until text changes size, an attachment draws as before.
|
|
40
|
+
|
|
28
41
|
## 0.8.0 (2 November 2026)
|
|
29
42
|
|
|
30
43
|
Time zones by name on a line chart's date axis, and a word for a missing value; charts that measure their text again when it changes size, so spacing a viewer adds after load lays them out again; every bar recoloured at once on `update({ colors })`, and a line chart's decorations drawn below its points; a bar chart's labels fading as they thin, and its bars taking the room of the value labels it hides; and `link()` linking an x with every value missing. 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.
|
|
18
|
+
> **Status: 0.9.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#090-3-november-2026) lists what's new and what changed since 0.8.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
|
|
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 89 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.
|
|
37
|
+
<script src="https://cdn.jsdelivr.net/npm/expressive-charts@0.9/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. Its `on()`, `marks()` and `leave()` are the view on show's, and it can be linked like a chart.
|
|
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. 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.
|
|
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.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, 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"`).
|
|
@@ -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()`; `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; `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
|
|
@@ -239,7 +239,7 @@ From 0.1.0 the library follows semantic versioning. While it's 0.x, the effect-a
|
|
|
239
239
|
| `npm run size` | Measures the built package and fails when a size is over its budget in `scripts/size-budget.json` (see [CONTRIBUTING.md](https://github.com/Deaversbp/expressive-charts/blob/main/CONTRIBUTING.md#bundle-size)) |
|
|
240
240
|
| `npm run pack-check` | After a build: packs the package, installs it in a new project and checks every entry as ESM and CommonJS, with its types (see [CONTRIBUTING.md](https://github.com/Deaversbp/expressive-charts/blob/main/CONTRIBUTING.md#setup)) |
|
|
241
241
|
| `npm test` | Runs the test suite, which also checks [docs/api.md](https://github.com/Deaversbp/expressive-charts/blob/main/docs/api.md) against the exports and type-checks this README's examples |
|
|
242
|
-
| `npm run test:visual:docker` | Runs the screenshot tests of `demo/bars.html`, `donut.html`, `line.html`, `morph.html`, `season.html` and `stress.html` in Chromium, and their DOM checks and the accessibility checks (axe) in Chromium, Firefox and WebKit, in Playwright's Linux image (needs Docker; see [CONTRIBUTING.md](https://github.com/Deaversbp/expressive-charts/blob/main/CONTRIBUTING.md#visual-tests)) |
|
|
242
|
+
| `npm run test:visual:docker` | Runs the screenshot tests of `demo/bars.html`, `donut.html`, `line.html`, `morph.html`, `season.html`, `shapes.html`, `charts.html` and `stress.html` in Chromium, and their DOM checks and the accessibility checks (axe) in Chromium, Firefox and WebKit, in Playwright's Linux image (needs Docker; see [CONTRIBUTING.md](https://github.com/Deaversbp/expressive-charts/blob/main/CONTRIBUTING.md#visual-tests)) |
|
|
243
243
|
| `npm run build:site` | Builds the demo pages into `site/`, which `.github/workflows/pages.yml` publishes as [the demo site](https://deaversbp.github.io/expressive-charts/) |
|
|
244
244
|
| `npm run media` | Captures README's pictures (`docs/media/*.gif`) from the demo pages, frame by frame, in Playwright's Linux image (needs Docker; see [CONTRIBUTING.md](https://github.com/Deaversbp/expressive-charts/blob/main/CONTRIBUTING.md#readmes-pictures-and-the-demo-site)) |
|
|
245
245
|
| `npm run bench` | Measures the stress page's cases in headless Chromium against `npm run dev`, unthrottled and at 4×, about 47 minutes; not in CI |
|