@internetstiftelsen/charts 0.10.1 → 0.11.0

package/dist/xy-motion/live-state.js

@@ -0,0 +1,240 @@
+import { select } from 'd3';
+import { sanitizeForCSS } from '../utils.js';
+import { cloneXYSeriesSnapshotCollection, createXYSeriesSnapshotId, } from './helpers.js';
+export function captureLiveAnimationState(plotGroup, visibleSeries, lastSeriesSnapshot) {
+    const snapshotCollection = cloneXYSeriesSnapshotCollection(lastSeriesSnapshot);
+    const pathState = new Map();
+    if (!plotGroup) {
+        return {
+            snapshotCollection,
+            pathState,
+        };
+    }
+    visibleSeries.forEach((series) => {
+        captureLiveSeriesState(series, plotGroup, snapshotCollection, pathState, lastSeriesSnapshot);
+    });
+    return {
+        snapshotCollection,
+        pathState,
+    };
+}
+function captureLiveSeriesState(series, plotGroup, snapshotCollection, pathState, lastSeriesSnapshot) {
+    switch (series.type) {
+        case 'bar':
+            captureLiveBarSeriesState(series, plotGroup, snapshotCollection);
+            return;
+        case 'line':
+            captureLiveLineSeriesState(series, plotGroup, snapshotCollection, pathState);
+            return;
+        case 'scatter':
+            captureLiveScatterSeriesState(series, plotGroup, snapshotCollection);
+            return;
+        case 'area':
+            captureLiveAreaSeriesState(series, plotGroup, snapshotCollection, pathState, lastSeriesSnapshot);
+            return;
+    }
+}
+function captureLiveBarSeriesState(series, plotGroup, snapshotCollection) {
+    const seriesId = createXYSeriesSnapshotId(series.type, series.dataKey);
+    const snapshot = captureLiveBarSnapshot(plotGroup, series.dataKey);
+    if (!snapshot) {
+        return;
+    }
+    snapshotCollection.set(seriesId, new Map([
+        ...(snapshotCollection.get(seriesId) ?? new Map()),
+        ...snapshot,
+    ]));
+}
+function captureLiveLineSeriesState(series, plotGroup, snapshotCollection, pathState) {
+    const seriesId = createXYSeriesSnapshotId(series.type, series.dataKey);
+    const snapshot = captureLivePointSnapshot(plotGroup, `.circle-${sanitizeForCSS(series.dataKey)}`);
+    const linePathState = captureLivePathState(plotGroup, `.line-${sanitizeForCSS(series.dataKey)}`);
+    if (snapshot) {
+        snapshotCollection.set(seriesId, new Map([
+            ...(snapshotCollection.get(seriesId) ?? new Map()),
+            ...snapshot,
+        ]));
+    }
+    if (linePathState.path !== null || linePathState.revealProgress !== null) {
+        pathState.set(seriesId, {
+            linePath: linePathState.path,
+            lineRevealProgress: linePathState.revealProgress,
+        });
+    }
+}
+function captureLiveScatterSeriesState(series, plotGroup, snapshotCollection) {
+    const seriesId = createXYSeriesSnapshotId(series.type, series.dataKey);
+    const snapshot = captureLivePointSnapshot(plotGroup, `.scatter-point-${sanitizeForCSS(series.dataKey)}`);
+    if (!snapshot) {
+        return;
+    }
+    snapshotCollection.set(seriesId, new Map([
+        ...(snapshotCollection.get(seriesId) ?? new Map()),
+        ...snapshot,
+    ]));
+}
+function captureLiveAreaSeriesState(series, plotGroup, snapshotCollection, pathState, lastSeriesSnapshot) {
+    const seriesId = createXYSeriesSnapshotId(series.type, series.dataKey);
+    const snapshot = captureLiveAreaSnapshot(plotGroup, series.dataKey, lastSeriesSnapshot.get(seriesId));
+    const areaPathState = captureLivePathState(plotGroup, `.area-${sanitizeForCSS(series.dataKey)}`);
+    const areaLinePathState = captureLivePathState(plotGroup, `.area-line-${sanitizeForCSS(series.dataKey)}`);
+    if (snapshot) {
+        snapshotCollection.set(seriesId, new Map([
+            ...(snapshotCollection.get(seriesId) ?? new Map()),
+            ...snapshot,
+        ]));
+    }
+    if (areaPathState.path !== null ||
+        areaLinePathState.path !== null ||
+        areaPathState.revealProgress !== null ||
+        areaLinePathState.revealProgress !== null) {
+        pathState.set(seriesId, {
+            areaPath: areaPathState.path,
+            areaLinePath: areaLinePathState.path,
+            areaRevealProgress: areaPathState.revealProgress,
+            areaLineRevealProgress: areaLinePathState.revealProgress,
+        });
+    }
+}
+function captureLiveBarSnapshot(plotGroup, dataKey) {
+    const bars = plotGroup.selectAll(`.bar-${sanitizeForCSS(dataKey)}`);
+    if (bars.empty()) {
+        return null;
+    }
+    bars.interrupt();
+    const snapshot = new Map();
+    bars.each((datum, index, nodes) => {
+        if (!datum.snapshotKey) {
+            return;
+        }
+        const node = nodes[index];
+        const x = getNumericAttribute(node, 'x');
+        const y = getNumericAttribute(node, 'y');
+        const width = getNumericAttribute(node, 'width');
+        const height = getNumericAttribute(node, 'height');
+        if (x === null || y === null || width === null || height === null) {
+            return;
+        }
+        snapshot.set(datum.snapshotKey, {
+            x,
+            y,
+            width,
+            height,
+        });
+    });
+    return snapshot.size > 0 ? snapshot : null;
+}
+function captureLivePointSnapshot(plotGroup, selector) {
+    const points = plotGroup.selectAll(selector);
+    if (points.empty()) {
+        return null;
+    }
+    points.interrupt();
+    const snapshot = new Map();
+    points.each((datum, index, nodes) => {
+        if (!datum.snapshotKey) {
+            return;
+        }
+        const node = nodes[index];
+        const x = getNumericAttribute(node, 'cx');
+        const y = getNumericAttribute(node, 'cy');
+        if (x === null || y === null) {
+            return;
+        }
+        snapshot.set(datum.snapshotKey, {
+            x,
+            y,
+        });
+    });
+    return snapshot.size > 0 ? snapshot : null;
+}
+function captureLiveAreaSnapshot(plotGroup, dataKey, previousSnapshot) {
+    const pointSnapshot = captureLivePointSnapshot(plotGroup, `.area-point-${sanitizeForCSS(dataKey)}`);
+    if (!pointSnapshot) {
+        return null;
+    }
+    const snapshot = new Map();
+    pointSnapshot.forEach((point, snapshotKey) => {
+        snapshot.set(snapshotKey, {
+            x: point.x,
+            y0: previousSnapshot?.get(snapshotKey)?.y0 ?? point.y,
+            y1: point.y,
+        });
+    });
+    return snapshot.size > 0 ? snapshot : null;
+}
+function captureLivePathState(plotGroup, selector) {
+    const path = plotGroup.select(selector);
+    if (path.empty()) {
+        return {
+            path: null,
+            revealProgress: null,
+        };
+    }
+    const node = path.node();
+    const revealProgress = node ? captureLeftToRightRevealProgress(node) : null;
+    path.interrupt();
+    interruptLeftToRightReveal(path.node());
+    return {
+        path: path.attr('d') || null,
+        revealProgress,
+    };
+}
+function getNumericAttribute(element, attribute) {
+    if (!element) {
+        return null;
+    }
+    const value = Number(element.getAttribute(attribute));
+    return Number.isFinite(value) ? value : null;
+}
+function captureLeftToRightRevealProgress(target) {
+    const clipRect = getRevealClipRect(target);
+    if (!clipRect) {
+        return null;
+    }
+    const targetBounds = target.getBBox();
+    const clipWidth = getNumericAttribute(clipRect, 'width');
+    const clipX = getNumericAttribute(clipRect, 'x');
+    if (clipWidth === null || clipX === null) {
+        return null;
+    }
+    const padding = targetBounds.x - clipX;
+    const totalWidth = targetBounds.width + padding * 2;
+    if (totalWidth <= 0) {
+        return null;
+    }
+    const progress = clipWidth / totalWidth;
+    if (!Number.isFinite(progress) || progress >= 1) {
+        return null;
+    }
+    return Math.max(0, Math.min(1, progress));
+}
+function interruptLeftToRightReveal(target) {
+    const clipRect = target ? getRevealClipRect(target) : null;
+    if (!clipRect) {
+        return;
+    }
+    select(clipRect).interrupt();
+}
+function getRevealClipRect(target) {
+    const svg = target.ownerSVGElement;
+    if (!svg) {
+        return null;
+    }
+    const clipPathId = extractClipPathId(target.getAttribute('clip-path'));
+    if (!clipPathId) {
+        return null;
+    }
+    const clipPath = target.ownerDocument?.getElementById(clipPathId);
+    if (!clipPath || !clipPath.classList.contains('xy-animation-reveal-clip')) {
+        return null;
+    }
+    return clipPath.querySelector('rect');
+}
+function extractClipPathId(value) {
+    if (!value) {
+        return null;
+    }
+    const match = value.match(/url\((?:['"])?#([^'")]+)(?:['"])?\)/);
+    return match?.[1] ?? null;
+}

package/dist/xy-motion/noop-xy-motion-driver.d.ts

@@ -0,0 +1,9 @@
+import type { XYMotionDriverContract } from './driver.js';
+import type { XYAreaAnimationContext, XYBarAnimationContext, XYMotionRenderResult, XYMotionSeries, XYMotionUpdateContext, XYPointAnimationContext } from './types.js';
+export declare class NoopXYMotionDriver implements XYMotionDriverContract {
+    prepareForUpdate(_context: XYMotionUpdateContext): void;
+    getPointAnimationContext(_series: XYMotionSeries, _baselineY: number): XYPointAnimationContext | undefined;
+    getAreaAnimationContext(_series: XYMotionSeries): XYAreaAnimationContext | undefined;
+    getBarAnimationContext(_series: XYMotionSeries, _baselineValuePosition: number): XYBarAnimationContext | undefined;
+    completeRender(_result: XYMotionRenderResult): Promise<void>;
+}

package/dist/xy-motion/noop-xy-motion-driver.js

@@ -0,0 +1,15 @@
+export class NoopXYMotionDriver {
+    prepareForUpdate(_context) { }
+    getPointAnimationContext(_series, _baselineY) {
+        return undefined;
+    }
+    getAreaAnimationContext(_series) {
+        return undefined;
+    }
+    getBarAnimationContext(_series, _baselineValuePosition) {
+        return undefined;
+    }
+    completeRender(_result) {
+        return Promise.resolve();
+    }
+}

package/dist/xy-motion/types.d.ts

@@ -0,0 +1,85 @@
+import type { Selection } from 'd3';
+export type XYAnimationEasingPreset = 'linear' | 'ease-in' | 'ease-out' | 'ease-in-out' | 'bounce-out' | 'elastic-out';
+export type XYAnimationConfig = {
+    show?: boolean;
+    duration?: number;
+    easing?: XYAnimationEasingPreset | `linear(${string})` | ((progress: number) => number);
+};
+export type XYRenderAnimationMode = 'none' | 'initial' | 'update';
+export type XYPointSnapshot = {
+    x: number;
+    y: number;
+};
+export type XYAreaPointSnapshot = {
+    x: number;
+    y0: number;
+    y1: number;
+};
+export type XYBarSnapshot = {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+};
+export type XYSeriesDatumSnapshot = XYPointSnapshot | XYAreaPointSnapshot | XYBarSnapshot;
+export type XYSeriesSnapshot<TSnapshot = XYSeriesDatumSnapshot> = Map<string, TSnapshot>;
+export type XYSeriesSnapshotCollection = Map<string, XYSeriesSnapshot<XYSeriesDatumSnapshot>>;
+export type NormalizedXYAnimation = {
+    show: boolean;
+    duration: number;
+    easing: (progress: number) => number;
+};
+export type XYPointAnimationContext = {
+    mode: Exclude<XYRenderAnimationMode, 'none'>;
+    duration: number;
+    easing: (progress: number) => number;
+    baselineY: number;
+    previousSnapshot?: XYSeriesSnapshot<XYPointSnapshot>;
+    previousPath?: string | null;
+    previousRevealProgress?: number | null;
+};
+export type XYAreaAnimationContext = {
+    mode: Exclude<XYRenderAnimationMode, 'none'>;
+    duration: number;
+    easing: (progress: number) => number;
+    previousSnapshot?: XYSeriesSnapshot<XYAreaPointSnapshot>;
+    previousAreaPath?: string | null;
+    previousLinePath?: string | null;
+    previousAreaRevealProgress?: number | null;
+    previousLineRevealProgress?: number | null;
+};
+export type XYBarAnimationContext = {
+    mode: Exclude<XYRenderAnimationMode, 'none'>;
+    duration: number;
+    easing: (progress: number) => number;
+    baselineValuePosition: number;
+    previousSnapshot?: XYSeriesSnapshot<XYBarSnapshot>;
+};
+export type XYSeriesRenderResult<TSnapshot = XYSeriesDatumSnapshot> = {
+    snapshot: XYSeriesSnapshot<TSnapshot>;
+    transitions: Promise<void>[];
+};
+export type XYMotionSeries = {
+    type: 'line' | 'scatter' | 'bar' | 'area';
+    dataKey: string;
+};
+export type XYMotionRenderResult = {
+    snapshotCollection: XYSeriesSnapshotCollection;
+    transitions: Promise<void>[];
+};
+export type XYMotionUpdateContext = {
+    plotGroup: Selection<SVGGElement, undefined, null, undefined> | null;
+    visibleSeries: XYMotionSeries[];
+};
+export type XYLivePathState = {
+    linePath?: string | null;
+    areaPath?: string | null;
+    areaLinePath?: string | null;
+    lineRevealProgress?: number | null;
+    areaRevealProgress?: number | null;
+    areaLineRevealProgress?: number | null;
+};
+export type XYLivePathStateCollection = Map<string, XYLivePathState>;
+export type XYSnapshotBoundDatum = {
+    snapshotKey?: string;
+};

package/dist/xy-motion/types.js

@@ -0,0 +1 @@
+export {};

package/dist/xy-motion/xy-motion-driver.d.ts

@@ -0,0 +1,19 @@
+import type { XYMotionDriverContract } from './driver.js';
+import type { NormalizedXYAnimation, XYAreaAnimationContext, XYBarAnimationContext, XYMotionRenderResult, XYMotionSeries, XYMotionUpdateContext, XYPointAnimationContext } from './types.js';
+export declare class XYMotionDriver implements XYMotionDriverContract {
+    private readonly animation;
+    private hasRenderedLive;
+    private nextRenderAnimationMode;
+    private pendingAnimationSnapshot;
+    private pendingPathState;
+    private lastSeriesSnapshot;
+    constructor(animation: NormalizedXYAnimation);
+    prepareForUpdate(context: XYMotionUpdateContext): void;
+    getPointAnimationContext(series: XYMotionSeries, baselineY: number): XYPointAnimationContext | undefined;
+    getAreaAnimationContext(series: XYMotionSeries): XYAreaAnimationContext | undefined;
+    getBarAnimationContext(series: XYMotionSeries, baselineValuePosition: number): XYBarAnimationContext | undefined;
+    completeRender(result: XYMotionRenderResult): Promise<void>;
+    private getRenderMode;
+    private getPreviousSeriesSnapshot;
+    private getPreviousPathState;
+}

package/dist/xy-motion/xy-motion-driver.js

@@ -0,0 +1,130 @@
+import { createXYSeriesSnapshotId } from './helpers.js';
+import { captureLiveAnimationState } from './live-state.js';
+export class XYMotionDriver {
+    constructor(animation) {
+        Object.defineProperty(this, "animation", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "hasRenderedLive", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: false
+        });
+        Object.defineProperty(this, "nextRenderAnimationMode", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "pendingAnimationSnapshot", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: null
+        });
+        Object.defineProperty(this, "pendingPathState", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: new Map()
+        });
+        Object.defineProperty(this, "lastSeriesSnapshot", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: new Map()
+        });
+        this.animation = animation;
+        this.nextRenderAnimationMode = 'initial';
+    }
+    prepareForUpdate(context) {
+        if (!this.hasRenderedLive) {
+            this.pendingAnimationSnapshot = null;
+            this.pendingPathState = new Map();
+            this.nextRenderAnimationMode = 'none';
+            return;
+        }
+        const liveState = captureLiveAnimationState(context.plotGroup, context.visibleSeries, this.lastSeriesSnapshot);
+        this.pendingAnimationSnapshot = liveState.snapshotCollection;
+        this.pendingPathState = liveState.pathState;
+        this.nextRenderAnimationMode =
+            this.animation.duration > 0 ? 'update' : 'none';
+    }
+    getPointAnimationContext(series, baselineY) {
+        const mode = this.getRenderMode();
+        if (mode === 'none') {
+            return undefined;
+        }
+        return {
+            mode,
+            duration: this.animation.duration,
+            easing: this.animation.easing,
+            baselineY,
+            previousSnapshot: this.getPreviousSeriesSnapshot(series.type, series.dataKey),
+            previousPath: series.type === 'line'
+                ? this.getPreviousPathState(series.type, series.dataKey)
+                    ?.linePath
+                : undefined,
+            previousRevealProgress: series.type === 'line'
+                ? this.getPreviousPathState(series.type, series.dataKey)
+                    ?.lineRevealProgress
+                : undefined,
+        };
+    }
+    getAreaAnimationContext(series) {
+        const mode = this.getRenderMode();
+        if (mode === 'none') {
+            return undefined;
+        }
+        return {
+            mode,
+            duration: this.animation.duration,
+            easing: this.animation.easing,
+            previousSnapshot: this.getPreviousSeriesSnapshot(series.type, series.dataKey),
+            previousAreaPath: this.getPreviousPathState(series.type, series.dataKey)?.areaPath,
+            previousAreaRevealProgress: this.getPreviousPathState(series.type, series.dataKey)?.areaRevealProgress,
+            previousLinePath: this.getPreviousPathState(series.type, series.dataKey)?.areaLinePath,
+            previousLineRevealProgress: this.getPreviousPathState(series.type, series.dataKey)?.areaLineRevealProgress,
+        };
+    }
+    getBarAnimationContext(series, baselineValuePosition) {
+        const mode = this.getRenderMode();
+        if (mode === 'none') {
+            return undefined;
+        }
+        return {
+            mode,
+            duration: this.animation.duration,
+            easing: this.animation.easing,
+            baselineValuePosition,
+            previousSnapshot: this.getPreviousSeriesSnapshot(series.type, series.dataKey),
+        };
+    }
+    completeRender(result) {
+        this.lastSeriesSnapshot = result.snapshotCollection;
+        this.hasRenderedLive = true;
+        this.nextRenderAnimationMode = 'none';
+        this.pendingAnimationSnapshot = null;
+        this.pendingPathState = new Map();
+        if (result.transitions.length === 0) {
+            return Promise.resolve();
+        }
+        return Promise.allSettled(result.transitions).then(() => undefined);
+    }
+    getRenderMode() {
+        if (this.animation.duration === 0) {
+            return 'none';
+        }
+        return this.nextRenderAnimationMode;
+    }
+    getPreviousSeriesSnapshot(seriesType, dataKey) {
+        return this.pendingAnimationSnapshot?.get(createXYSeriesSnapshotId(seriesType, dataKey));
+    }
+    getPreviousPathState(seriesType, dataKey) {
+        return this.pendingPathState.get(createXYSeriesSnapshotId(seriesType, dataKey));
+    }
+}

package/docs/components.md

@@ -119,6 +119,14 @@ Renders interactive tooltips on hover and keyboard focus.
 
 ```typescript
 new Tooltip({
+    mode?: 'shared' | 'split',
+    position?: 'side' | 'vertical',
+    barAnchorPosition?: 'top' | 'middle',
+    transition?: {
+        show?: boolean,
+        duration?: number,
+        easing?: string
+    },
     formatter?: (dataKey: string, value: DataValue, data: DataItem) => string
 })
 ```
@@ -129,6 +137,34 @@ The formatter receives:
 - `value` - The data value at this point
 - `data` - The full data item object
 
+Tooltip modes:
+
+- `shared` - One tooltip per hovered category/value group
+- `split` - Default. One tooltip per visible series at the hovered category/value group
+
+Split tooltip positions:
+
+- `side` - Default. Place split tooltips to the side of each data point
+- `vertical` - Place split tooltips above or below each data point
+
+When `split` mode is active, `customFormatter` receives the current series only for
+that tooltip box instead of the full visible series list. Split tooltips include
+directional arrows and avoid overlapping on the same side of the chart when
+possible.
+
+For bars, `barAnchorPosition` controls whether split tooltips point to the `top`
+or `middle` of each bar.
+
+Set `transition.show: true` to fade tooltips in and out. Tooltip position and
+connector geometry update immediately; only opacity and the small entrance
+offset transition.
+
+Tooltip box, text, connector, and arrow colors use `theme.tooltip`.
+
+Formatter, label formatter, and custom formatter output is inserted as HTML.
+Only return trusted content or sanitize user-provided strings before returning
+them from formatter callbacks.
+
 ### Example
 
 ```javascript

package/docs/getting-started.md

@@ -76,6 +76,41 @@ const chart = new XYChart({
 });
 ```
 
+## Lazy Loading
+
+When a page contains charts further down the document, you can defer the chart
+imports until the container is near the viewport.
+
+```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: 'date' }))
+            .addChild(new YAxis())
+            .addChild(new Line({ dataKey: 'revenue' }));
+
+        chart.render(container);
+        return chart;
+    },
+    {
+        rootMargin: '240px 0px',
+    },
+);
+
+// Optional if you want to trigger the load early
+await lazyChart.load();
+```
+
+`mountChartWhenVisible` keeps the loading strategy separate from chart
+construction, which makes it a good building block for custom wrappers or
+attribute-driven mounting later on.
+
 ## Grouping Charts
 
 ```javascript

package/docs/theming.md

@@ -27,6 +27,14 @@ const chart = new XYChart({
             fontFamily: 'Inter, sans-serif',
             fontSize: 12,
         },
+        tooltip: {
+            background: '#102030',
+            border: '#405060',
+            color: '#f7fafc',
+            fontFamily: 'Inter, sans-serif',
+            fontSize: 13,
+            fontWeight: '600',
+        },
     },
 });
 ```
@@ -51,6 +59,12 @@ import { defaultTheme, newspaperTheme, themes } from '@internetstiftelsen/charts
 | `legend.paddingX`     | `number`   | `0`                                            | Horizontal legend layout padding             |
 | `legend.itemSpacingX` | `number`   | `20`                                           | Horizontal spacing between legend items      |
 | `legend.itemSpacingY` | `number`   | `8`                                            | Vertical spacing between wrapped legend rows |
+| `tooltip.background`  | `string`   | `'#ffffff'`                                    | Tooltip box and arrow fill color             |
+| `tooltip.border`      | `string`   | `'#dddddd'`                                    | Tooltip box, connector, and arrow border     |
+| `tooltip.color`       | `string`   | `'#1f2a36'`                                    | Tooltip text color                           |
+| `tooltip.fontFamily`  | `string`   | -                                              | Tooltip text font                            |
+| `tooltip.fontSize`    | `number`   | `12`                                           | Tooltip text size in pixels                  |
+| `tooltip.fontWeight`  | `string`   | `'normal'`                                     | Tooltip text weight                          |
 
 ---