@internetstiftelsen/charts 0.10.1 → 0.11.0

package/docs/xy-chart.md

@@ -21,6 +21,7 @@ new XYChart(config: XYChartConfig)
 | `responsive`  | `ResponsiveConfig`                 | -                                                    | Container-query responsive overrides (theme + components)             |
 | `barStack`    | `BarStackConfig`                   | `{ mode: 'normal', gap: 0.1, reverseSeries: false }` | Bar stacking configuration                                            |
 | `areaStack`   | `AreaStackConfig`                  | `{ mode: 'none' }`                                   | Area stacking configuration                                           |
+| `animate`     | `boolean \| XYAnimationConfig`     | `false`                                              | Opt-in XY series animation for initial render and `update()`          |
 
 ### Theme Options
 
@@ -223,6 +224,45 @@ is measured after declarative breakpoint overrides are merged. It receives
 `context.activeBreakpoints` with every match and `context.breakpoint` as the
 last matching breakpoint name.
 
+## Animation
+
+Use `animate` when you want XY series marks to animate on the first render and
+when calling `chart.update(...)`.
+
+```typescript
+const chart = new XYChart({
+    data,
+    animate: {
+        duration: 700,
+        easing: 'ease-in-out',
+    },
+});
+```
+
+`XYAnimationConfig` supports:
+
+```typescript
+animate: boolean | {
+    show?: boolean,       // default: true when object form is used
+    duration?: number,    // ms, default: 700
+    easing?:
+        | 'linear'
+        | 'ease-in'
+        | 'ease-out'
+        | 'ease-in-out'
+        | 'bounce-out'
+        | 'elastic-out'
+        | `linear(...)`
+        | ((t: number) => number),
+}
+```
+
+Notes:
+
+- Animation is off by default.
+- Animates XY series marks only. Axes, legends, tooltips, and value labels remain static.
+- Visual exports always render the final static state, even when the live chart is animated.
+
 ## Validation
 
 `XYChart` validates configuration and series data early:
@@ -256,6 +296,9 @@ chart.render('#chart-container');
 chart.render(document.getElementById('chart-container'));
 ```
 
+When `animate` is enabled, the first render returns immediately while the series
+transition continues in the background.
+
 ### update(data)
 
 Updates the chart with new data and re-renders.
@@ -264,6 +307,18 @@ Updates the chart with new data and re-renders.
 chart.update(newData);
 ```
 
+When `animate` is enabled, `update()` animates XY series marks from the previous
+rendered geometry to the new one.
+
+### whenReady()
+
+Returns a promise that resolves after any pending async render work finishes.
+For animated XY charts, this waits until the current series transitions finish.
+
+```javascript
+await chart.whenReady();
+```
+
 ### destroy()
 
 Cleans up all resources, removes resize observer, and clears the chart from the DOM.
@@ -438,7 +493,18 @@ Bar charts support different stacking modes:
 - `percent` - 100% stacked bars
 - `layer` - Overlapping bars
 
-Use `barStack.reverseSeries: true` to reverse bar series display order for rendering, legend entries, and tooltip rows without changing data exports.
+XY charts use split tooltips by default, rendering one tooltip per visible
+series at the hovered category. Use
+`new Tooltip({ mode: 'shared' | 'split', position: 'side' | 'vertical' })`
+to override the grouping and split-tooltip placement.
+For bars, set `barAnchorPosition: 'top' | 'middle'` to choose whether split
+tooltips point to the top or middle of each bar.
+Use `transition: { show: true, duration: 120, easing: 'ease-out' }` to opt in
+to softer tooltip opacity transitions without delaying position updates.
+
+Use `barStack.reverseSeries: true` to reverse bar series display order for
+rendering, legend entries, and split tooltip ordering without changing data
+exports.
 
 ---
 

package/package.json

@@ -1,5 +1,5 @@
 {
-    "version": "0.10.1",
+    "version": "0.11.0",
     "name": "@internetstiftelsen/charts",
     "type": "module",
     "sideEffects": false,