@internetstiftelsen/charts 0.10.0 → 0.11.0

package/README.md

@@ -10,7 +10,8 @@ A framework-agnostic, composable charting library built on D3.js with TypeScript
 - **Combined Chart Layouts** - `ChartGroup` composes existing charts into shared dashboards with one coordinated legend
 - **Divergent Bar Support** - Bar charts automatically render from zero and diverge around `0` for mixed positive/negative values
 - **Mirrored Bar Sides** - Horizontal bars can mirror a series to the left for population-pyramid style charts without changing source data
-- **Radial Value Labels** - Pie and donut charts support optional on-chart labels with custom formatters
+- **Custom Value Labels** - XY, pie, and donut charts support optional on-chart labels with custom formatters
+- **Optional XY Animation** - Animate XY series on first render and `chart.update(...)` with `animate`
 - **Optional Gauge Animation** - Animate gauge value transitions with `gauge.animate`
 - **Stacking Control** - Bar stacking modes with optional reversed visual series order
 - **Axis Direction Control** - Use `scales.x.reverse` / `scales.y.reverse` to flip an axis when needed
@@ -18,6 +19,7 @@ A framework-agnostic, composable charting library built on D3.js with TypeScript
 - **Explicit or Responsive Sizing** - Set top-level `width`/`height` or let the container drive size
 - **Auto Resize** - Built-in ResizeObserver handles responsive behavior
 - **Responsive Policy** - Chart-level container-query overrides for theme and components
+- **Lazy Mount Utility** - Observe a container and defer chart imports until it approaches the viewport
 - **Type Safe** - Written in TypeScript with full type definitions
 - **Data Validation** - Built-in validation with helpful error messages
 - **Auto Colors** - Smart color palette with sensible defaults
@@ -110,6 +112,68 @@ from the render container.
 Theme overrides are deep-partial, so nested overrides like
 `theme.axis.fontSize` preserve the rest of the theme defaults.
 
+## XY Animation
+
+Enable `animate` on `XYChart` when you want series marks to animate on the
+first render and on later `chart.update(...)` calls.
+
+```typescript
+const chart = new XYChart({
+    data,
+    animate: {
+        duration: 700,
+        easing: 'ease-in-out',
+    },
+});
+
+chart
+    .addChild(new XAxis({ dataKey: 'month' }))
+    .addChild(new YAxis())
+    .addChild(new Line({ dataKey: 'value' }));
+
+chart.render('#chart-container');
+
+await chart.whenReady();
+```
+
+Animation is off by default, applies to XY series marks only, and visual
+exports always render the final static state.
+
+## Lazy Loading
+
+Use `mountChartWhenVisible` when you want the page to wait until a chart is
+near the viewport before importing chart code and rendering it.
+
+```typescript
+import { mountChartWhenVisible } from '@internetstiftelsen/charts/lazy-mount';
+
+const lazyChart = mountChartWhenVisible(
+    '#chart-container',
+    async (container) => {
+        const [{ XYChart }, { Line }, { XAxis }, { YAxis }] = await Promise.all([import('@internetstiftelsen/charts/xy-chart'), import('@internetstiftelsen/charts/line'), import('@internetstiftelsen/charts/x-axis'), import('@internetstiftelsen/charts/y-axis')]);
+
+        const chart = new XYChart({ data });
+        chart
+            .addChild(new XAxis({ dataKey: 'month' }))
+            .addChild(new YAxis())
+            .addChild(new Line({ dataKey: 'value' }));
+
+        chart.render(container);
+        return chart;
+    },
+    {
+        rootMargin: '240px 0px',
+    },
+);
+
+// Optional: preload manually before it scrolls into view
+await lazyChart.load();
+```
+
+The utility is intentionally small: it observes the container, calls your async
+factory once, and gives you `load()` plus `destroy()` so higher-level DOM
+conventions such as `data-chart` scanners can build on top of it.
+
 ## Chart Groups
 
 Use `ChartGroup` when you want to combine existing charts into one layout while

package/dist/area.d.ts

@@ -1,6 +1,7 @@
 import { type Selection } from 'd3';
 import type { AreaConfig, AreaCurveType, AreaConfigBase, AreaStackingContext, ChartTheme, D3Scale, DataItem, ExportHooks, LineValueLabelConfig, ScaleType } from './types.js';
 import type { ChartComponent } from './chart-interface.js';
+import type { XYAreaAnimationContext, XYAreaPointSnapshot, XYSeriesRenderResult } from './xy-motion/types.js';
 export declare class Area implements ChartComponent<AreaConfigBase> {
     readonly type: "area";
     readonly dataKey: string;
@@ -20,6 +21,15 @@ export declare class Area implements ChartComponent<AreaConfigBase> {
     getExportConfig(): AreaConfigBase;
     createExportComponent(override?: Partial<AreaConfigBase>): ChartComponent<AreaConfigBase>;
     private getStackValues;
-    render(plotGroup: Selection<SVGGElement, undefined, null, undefined>, data: DataItem[], xKey: string, x: D3Scale, y: D3Scale, parseValue: (value: unknown) => number, xScaleType: ScaleType | undefined, theme: ChartTheme, stackingContext?: AreaStackingContext, valueLabelLayer?: Selection<SVGGElement, undefined, null, undefined>): void;
+    render(plotGroup: Selection<SVGGElement, undefined, null, undefined>, data: DataItem[], xKey: string, x: D3Scale, y: D3Scale, parseValue: (value: unknown) => number, xScaleType: ScaleType | undefined, theme: ChartTheme, stackingContext?: AreaStackingContext, valueLabelLayer?: Selection<SVGGElement, undefined, null, undefined>, animation?: XYAreaAnimationContext): XYSeriesRenderResult<XYAreaPointSnapshot>;
+    private buildAreaData;
+    private buildAnimatedAreaData;
+    private createSnapshot;
+    private renderAreaFill;
+    private renderLinePath;
+    private getInitialAreaPathValue;
+    private getInitialLinePathValue;
+    private createRevealTransitions;
+    private renderPoints;
     private renderValueLabels;
 }

package/dist/area.js

@@ -1,6 +1,7 @@
 import { area, curveBasis, curveCardinal, curveLinear, curveMonotoneX, curveNatural, curveStep, line, } from 'd3';
 import { mergeDeep, sanitizeForCSS } from './utils.js';
 import { getScalePosition } from './scale-utils.js';
+import { buildXYDatumSnapshotKeys, createTransitionCompletionPromise, createLeftToRightRevealTransition, getEnterStaggerTiming, } from './xy-motion/helpers.js';
 const AREA_CURVE_FACTORIES = {
     linear: curveLinear,
     monotone: curveMonotoneX,
@@ -157,9 +158,9 @@ export class Area {
             y1: cumulative + value,
         };
     }
-    render(plotGroup, data, xKey, x, y, parseValue, xScaleType = 'band', theme, stackingContext, valueLabelLayer) {
-        const getXPosition = (d) => {
-            const scaled = getScalePosition(x, d.data[xKey], xScaleType);
+    render(plotGroup, data, xKey, x, y, parseValue, xScaleType = 'band', theme, stackingContext, valueLabelLayer, animation) {
+        const getXPosition = (dataPoint) => {
+            const scaled = getScalePosition(x, dataPoint[xKey], xScaleType);
             return scaled + (x.bandwidth ? x.bandwidth() / 2 : 0);
         };
         const hasValidValue = (d) => {
@@ -169,74 +170,215 @@ export class Area {
             }
             return Number.isFinite(parseValue(value));
         };
-        const areaData = data.map((d) => {
-            const valid = hasValidValue(d);
+        const snapshotKeys = buildXYDatumSnapshotKeys(data, xKey);
+        const areaData = this.buildAreaData(data, xKey, snapshotKeys, y, parseValue, stackingContext, getXPosition, hasValidValue);
+        const animatedAreaData = this.buildAnimatedAreaData(areaData, animation);
+        const curveFactory = AREA_CURVE_FACTORIES[this.curve] || curveLinear;
+        const sanitizedKey = sanitizeForCSS(this.dataKey);
+        const transitions = this.renderAreaFill(plotGroup, areaData, animatedAreaData, curveFactory, sanitizedKey, animation);
+        const snapshot = this.createSnapshot(areaData);
+        if (this.showLine) {
+            const lineTransitions = this.renderLinePath(plotGroup, areaData, animatedAreaData, curveFactory, theme, sanitizedKey, animation);
+            transitions.push(...lineTransitions);
+        }
+        if (this.showPoints) {
+            const pointTransitions = this.renderPoints(plotGroup, areaData, animatedAreaData, theme, sanitizedKey, animation);
+            transitions.push(...pointTransitions);
+        }
+        if (this.valueLabel?.show) {
+            this.renderValueLabels(valueLabelLayer ?? plotGroup, areaData.filter((d) => d.valid), y, parseValue, theme);
+        }
+        return {
+            snapshot,
+            transitions,
+        };
+    }
+    buildAreaData(data, xKey, snapshotKeys, y, parseValue, stackingContext, getXPosition, hasValidValue) {
+        return data.map((entry, index) => {
+            const valid = hasValidValue(entry);
             const stackValues = valid
-                ? this.getStackValues(d, xKey, parseValue, stackingContext)
+                ? this.getStackValues(entry, xKey, parseValue, stackingContext)
                 : { y0: this.baseline, y1: this.baseline };
             return {
-                data: d,
+                data: entry,
                 valid,
-                y0: stackValues.y0,
-                y1: stackValues.y1,
+                snapshotKey: snapshotKeys[index] ?? String(index),
+                x: getXPosition(entry),
+                y0: y(stackValues.y0) ?? 0,
+                y1: y(stackValues.y1) ?? 0,
             };
         });
-        const curveFactory = AREA_CURVE_FACTORIES[this.curve] || curveLinear;
+    }
+    buildAnimatedAreaData(areaData, animation) {
+        return areaData.map((entry) => {
+            if (!animation || !entry.valid) {
+                return entry;
+            }
+            const previousSnapshot = animation.previousSnapshot?.get(entry.snapshotKey);
+            return {
+                ...entry,
+                x: previousSnapshot?.x ?? entry.x,
+                y0: previousSnapshot?.y0 ?? entry.y0,
+                y1: previousSnapshot?.y1 ?? entry.y0,
+            };
+        });
+    }
+    createSnapshot(areaData) {
+        const snapshot = new Map();
+        areaData.forEach((entry) => {
+            if (!entry.valid) {
+                return;
+            }
+            snapshot.set(entry.snapshotKey, {
+                x: entry.x,
+                y0: entry.y0,
+                y1: entry.y1,
+            });
+        });
+        return snapshot;
+    }
+    renderAreaFill(plotGroup, areaData, animatedAreaData, curveFactory, sanitizedKey, animation) {
+        const areaOpacity = Math.max(0, Math.min(1, this.opacity));
         const areaGenerator = area()
             .defined((d) => d.valid)
             .curve(curveFactory)
-            .x(getXPosition)
-            .y0((d) => y(d.y0) || 0)
-            .y1((d) => y(d.y1) || 0);
-        const areaOpacity = Math.max(0, Math.min(1, this.opacity));
-        const sanitizedKey = sanitizeForCSS(this.dataKey);
-        plotGroup
+            .x((entry) => entry.x)
+            .y0((entry) => entry.y0)
+            .y1((entry) => entry.y1);
+        const finalAreaPath = areaGenerator(areaData);
+        const areaPath = plotGroup
             .append('path')
             .datum(areaData)
             .attr('class', `area-${sanitizedKey}`)
             .attr('fill', this.fill)
             .attr('fill-opacity', areaOpacity)
             .attr('stroke', 'none')
-            .attr('d', areaGenerator);
-        if (this.showLine) {
-            const lineGenerator = line()
-                .defined((d) => d.valid)
-                .curve(curveFactory)
-                .x(getXPosition)
-                .y((d) => y(d.y1) || 0);
-            const lineStrokeWidth = this.strokeWidth ?? theme.line.strokeWidth;
-            plotGroup
-                .append('path')
-                .datum(areaData)
-                .attr('class', `area-line-${sanitizedKey}`)
-                .attr('fill', 'none')
-                .attr('stroke', this.stroke)
-                .attr('stroke-width', lineStrokeWidth)
-                .attr('d', lineGenerator);
+            .attr('d', this.getInitialAreaPathValue(finalAreaPath, areaData, animatedAreaData, areaGenerator, animation));
+        if (!animation || !finalAreaPath) {
+            return [];
         }
-        if (this.showPoints) {
-            const validData = areaData.filter((d) => d.valid);
-            const pointSize = this.pointSize ?? theme.line.point.size;
-            const pointStrokeWidth = theme.line.point.strokeWidth;
-            const pointStrokeColor = theme.line.point.strokeColor || this.stroke;
-            const pointColor = theme.line.point.color || this.stroke;
-            plotGroup
-                .selectAll(`.area-point-${sanitizedKey}`)
-                .data(validData)
-                .join('circle')
-                .attr('class', `area-point-${sanitizedKey}`)
-                .attr('cx', getXPosition)
-                .attr('cy', (d) => y(d.y1) || 0)
-                .attr('r', pointSize)
-                .attr('fill', pointColor)
-                .attr('stroke', pointStrokeColor)
-                .attr('stroke-width', pointStrokeWidth);
+        const revealTransitions = this.createRevealTransitions(areaPath.node(), `area-${sanitizedKey}-reveal`, animation, animation.previousAreaRevealProgress);
+        const transition = areaPath
+            .transition()
+            .duration(animation.duration)
+            .ease(animation.easing)
+            .attr('d', finalAreaPath);
+        return [
+            ...revealTransitions,
+            createTransitionCompletionPromise(transition),
+        ];
+    }
+    renderLinePath(plotGroup, areaData, animatedAreaData, curveFactory, theme, sanitizedKey, animation) {
+        const lineGenerator = line()
+            .defined((d) => d.valid)
+            .curve(curveFactory)
+            .x((entry) => entry.x)
+            .y((entry) => entry.y1);
+        const lineStrokeWidth = this.strokeWidth ?? theme.line.strokeWidth;
+        const finalPath = lineGenerator(areaData);
+        const linePath = plotGroup
+            .append('path')
+            .datum(areaData)
+            .attr('class', `area-line-${sanitizedKey}`)
+            .attr('fill', 'none')
+            .attr('stroke', this.stroke)
+            .attr('stroke-width', lineStrokeWidth)
+            .attr('d', this.getInitialLinePathValue(finalPath, areaData, animatedAreaData, lineGenerator, animation));
+        if (!animation || !finalPath) {
+            return [];
         }
-        if (this.valueLabel?.show) {
-            this.renderValueLabels(valueLabelLayer ?? plotGroup, areaData.filter((d) => d.valid), y, parseValue, theme, getXPosition);
+        const revealTransitions = this.createRevealTransitions(linePath.node(), `area-line-${sanitizedKey}-reveal`, animation, animation.previousLineRevealProgress, lineStrokeWidth);
+        const transition = linePath
+            .transition()
+            .duration(animation.duration)
+            .ease(animation.easing)
+            .attr('d', finalPath);
+        return [
+            ...revealTransitions,
+            createTransitionCompletionPromise(transition),
+        ];
+    }
+    getInitialAreaPathValue(finalAreaPath, areaData, animatedAreaData, areaGenerator, animation) {
+        if (animation?.mode === 'initial') {
+            return finalAreaPath;
+        }
+        if (!animation) {
+            return finalAreaPath;
+        }
+        return (animation.previousAreaPath ??
+            areaGenerator(animation ? animatedAreaData : areaData));
+    }
+    getInitialLinePathValue(finalPath, areaData, animatedAreaData, lineGenerator, animation) {
+        if (animation?.mode === 'initial') {
+            return finalPath;
+        }
+        if (!animation) {
+            return finalPath;
+        }
+        return (animation.previousLinePath ??
+            lineGenerator(animation ? animatedAreaData : areaData));
+    }
+    createRevealTransitions(path, revealId, animation, previousRevealProgress, padding = 0) {
+        if (animation.mode === 'initial') {
+            return createLeftToRightRevealTransition(path, animation.duration, animation.easing, revealId, padding);
+        }
+        if (previousRevealProgress == null) {
+            return [];
+        }
+        return createLeftToRightRevealTransition(path, animation.duration, animation.easing, revealId, padding, previousRevealProgress);
+    }
+    renderPoints(plotGroup, areaData, animatedAreaData, theme, sanitizedKey, animation) {
+        const validData = areaData.filter((d) => d.valid);
+        const validAnimatedData = animatedAreaData.filter((d) => d.valid);
+        const pointSize = this.pointSize ?? theme.line.point.size;
+        const pointStrokeWidth = theme.line.point.strokeWidth;
+        const pointStrokeColor = theme.line.point.strokeColor || this.stroke;
+        const pointColor = theme.line.point.color || this.stroke;
+        const isInitialAnimation = animation?.mode === 'initial';
+        const circles = plotGroup
+            .selectAll(`.area-point-${sanitizedKey}`)
+            .data(validData)
+            .join('circle')
+            .attr('class', `area-point-${sanitizedKey}`)
+            .attr('cx', (_, index) => (isInitialAnimation
+            ? validData[index]?.x
+            : animation
+                ? validAnimatedData[index]?.x
+                : validData[index]?.x) ?? 0)
+            .attr('cy', (_, index) => (isInitialAnimation
+            ? validData[index]?.y1
+            : animation
+                ? validAnimatedData[index]?.y1
+                : validData[index]?.y1) ?? 0)
+            .attr('r', isInitialAnimation ? 0 : pointSize)
+            .attr('fill', pointColor)
+            .attr('stroke', pointStrokeColor)
+            .attr('stroke-width', pointStrokeWidth);
+        if (!animation) {
+            return [];
+        }
+        if (isInitialAnimation) {
+            const transition = circles
+                .transition()
+                .delay((_, index) => {
+                return getEnterStaggerTiming(index, validData.length, animation.duration).delay;
+            })
+                .duration((_, index) => {
+                return getEnterStaggerTiming(index, validData.length, animation.duration).duration;
+            })
+                .ease(animation.easing)
+                .attr('r', pointSize);
+            return [createTransitionCompletionPromise(transition)];
         }
+        const transition = circles
+            .transition()
+            .duration(animation.duration)
+            .ease(animation.easing)
+            .attr('cx', (_, index) => validData[index]?.x ?? 0)
+            .attr('cy', (_, index) => validData[index]?.y1 ?? 0);
+        return [createTransitionCompletionPromise(transition)];
     }
-    renderValueLabels(plotGroup, data, y, parseValue, theme, getXPosition) {
+    renderValueLabels(plotGroup, data, y, parseValue, theme) {
         const config = this.valueLabel;
         const fontSize = config.fontSize ?? theme.valueLabel.fontSize;
         const fontFamily = config.fontFamily ?? theme.valueLabel.fontFamily;
@@ -260,9 +402,11 @@ export class Area {
             if (!Number.isFinite(parsedValue)) {
                 return;
             }
-            const valueText = String(parsedValue);
-            const xPos = getXPosition(d);
-            const yPos = y(d.y1) || 0;
+            const valueText = config.formatter
+                ? config.formatter(this.dataKey, parsedValue, d.data)
+                : String(parsedValue);
+            const xPos = d.x;
+            const yPos = d.y1;
             const tempText = labelGroup
                 .append('text')
                 .style('font-size', `${fontSize}px`)

package/dist/bar.d.ts

@@ -1,6 +1,7 @@
 import type { Selection } from 'd3';
 import type { BarConfig, BarStackingContext, BarSide, BarValueLabelConfig, ChartTheme, D3Scale, DataItem, Orientation, ScaleType, ExportHooks, BarConfigBase } from './types.js';
 import type { ChartComponent } from './chart-interface.js';
+import type { XYBarAnimationContext, XYBarSnapshot, XYSeriesRenderResult } from './xy-motion/types.js';
 export declare class Bar implements ChartComponent<BarConfigBase> {
     readonly type: "bar";
     readonly dataKey: string;
@@ -14,9 +15,33 @@ export declare class Bar implements ChartComponent<BarConfigBase> {
     getExportConfig(): BarConfigBase;
     createExportComponent(override?: Partial<BarConfigBase>): ChartComponent<BarConfigBase>;
     getRenderedValue(value: number, orientation?: Orientation): number;
-    render(plotGroup: Selection<SVGGElement, undefined, null, undefined>, data: DataItem[], xKey: string, x: D3Scale, y: D3Scale, parseValue: (value: unknown) => number, xScaleType?: ScaleType, theme?: ChartTheme, stackingContext?: BarStackingContext, orientation?: 'vertical' | 'horizontal'): void;
+    render(plotGroup: Selection<SVGGElement, undefined, null, undefined>, data: DataItem[], xKey: string, x: D3Scale, y: D3Scale, parseValue: (value: unknown) => number, xScaleType?: ScaleType, theme?: ChartTheme, stackingContext?: BarStackingContext, orientation?: 'vertical' | 'horizontal', animation?: XYBarAnimationContext): XYSeriesRenderResult<XYBarSnapshot>;
     private renderVertical;
     private renderHorizontal;
+    private createVerticalLayoutData;
+    private createHorizontalLayoutData;
+    private createAnimatedVerticalLayoutData;
+    private createAnimatedHorizontalLayoutData;
+    private resolveAnimatedLayoutDatum;
+    private createSnapshot;
+    private renderBars;
+    private resolveValueLabelConfig;
+    private resolveValueLabelPlacement;
+    private resolveValueLabelStyle;
+    private getValueLabelText;
+    private getBarColor;
+    private measureLabelBox;
+    private getLabelColor;
+    private appendValueLabel;
+    private getVerticalLabelPlacement;
+    private getVerticalOutsideLabelPlacement;
+    private getVerticalInsideLabelY;
+    private getHorizontalLabelPlacement;
+    private getHorizontalOutsideLabelPlacement;
+    private getHorizontalInsideLabelX;
+    private isHorizontalLabelWithinBounds;
+    private renderVerticalValueLabel;
+    private renderHorizontalValueLabel;
     private renderVerticalValueLabels;
     private renderHorizontalValueLabels;
 }