@internetstiftelsen/charts 0.10.1 → 0.11.0

package/dist/types.d.ts

@@ -69,6 +69,14 @@ export type ChartTheme = {
         itemSpacingX: number;
         itemSpacingY: number;
     };
+    tooltip: {
+        background: string;
+        border: string;
+        color: string;
+        fontFamily: string;
+        fontSize: number;
+        fontWeight: string;
+    };
     line: {
         strokeWidth: number;
         point: {
@@ -277,7 +285,19 @@ export type GridConfigBase = {
 export type GridConfig = GridConfigBase & {
     exportHooks?: ExportHooks<GridConfigBase>;
 };
+export type TooltipMode = 'shared' | 'split';
+export type TooltipPosition = 'side' | 'vertical';
+export type TooltipBarAnchorPosition = 'top' | 'middle';
+export type TooltipTransitionConfig = {
+    show?: boolean;
+    duration?: number;
+    easing?: string;
+};
 export type TooltipConfigBase = {
+    mode?: TooltipMode;
+    position?: TooltipPosition;
+    barAnchorPosition?: TooltipBarAnchorPosition;
+    transition?: TooltipTransitionConfig;
     formatter?: SeriesValueFormatter;
     labelFormatter?: (label: string, data: DataItem) => string;
     customFormatter?: (data: DataItem, series: {

package/dist/xy-animation.d.ts

@@ -0,0 +1,3 @@
+export type { NormalizedXYAnimation, XYAnimationConfig, XYAnimationEasingPreset, XYAreaAnimationContext, XYAreaPointSnapshot, XYBarAnimationContext, XYBarSnapshot, XYMotionRenderResult, XYMotionSeries, XYMotionUpdateContext, XYPointAnimationContext, XYPointSnapshot, XYRenderAnimationMode, XYSeriesDatumSnapshot, XYSeriesRenderResult, XYSeriesSnapshot, XYSeriesSnapshotCollection, } from './xy-motion/types.js';
+export { normalizeXYAnimationConfig } from './xy-motion/config.js';
+export { buildXYDatumSnapshotKeys, cloneXYSeriesSnapshotCollection, createLeftToRightRevealTransition, createTransitionCompletionPromise, createXYAnimationId, createXYDatumKey, createXYSeriesSnapshotId, getEnterStaggerTiming, } from './xy-motion/helpers.js';

package/dist/xy-animation.js

@@ -0,0 +1,2 @@
+export { normalizeXYAnimationConfig } from './xy-motion/config.js';
+export { buildXYDatumSnapshotKeys, cloneXYSeriesSnapshotCollection, createLeftToRightRevealTransition, createTransitionCompletionPromise, createXYAnimationId, createXYDatumKey, createXYSeriesSnapshotId, getEnterStaggerTiming, } from './xy-motion/helpers.js';

package/dist/xy-chart.d.ts

@@ -1,10 +1,13 @@
 import { BaseChart, type BaseChartConfig, type BaseLayoutContext, type BaseRenderContext } from './base-chart.js';
 import type { ChartComponentBase } from './chart-interface.js';
-import { type AreaStackConfig, type AxisScaleConfig, type BarStackConfig, type LegendSeries, type Orientation, type ScaleType } from './types.js';
+import { type AreaStackConfig, type AxisScaleConfig, type BarStackConfig, type ChartData, type LegendSeries, type Orientation, type ScaleType } from './types.js';
+import type { XYAnimationConfig } from './xy-animation.js';
+export type { XYAnimationConfig, XYAnimationEasingPreset, } from './xy-animation.js';
 export type XYChartConfig = BaseChartConfig & {
     orientation?: Orientation;
     barStack?: BarStackConfig;
     areaStack?: AreaStackConfig;
+    animate?: boolean | XYAnimationConfig;
 };
 export declare class XYChart extends BaseChart {
     private readonly series;
@@ -13,11 +16,13 @@ export declare class XYChart extends BaseChart {
     private barStackReverseSeries;
     private areaStackMode;
     private readonly orientation;
+    private readonly motionDriver;
     private scaleConfigOverride;
     constructor(config: XYChartConfig);
     addChild(component: ChartComponentBase): this;
     protected getExportComponents(): ChartComponentBase[];
     protected createExportChart(): BaseChart;
+    update(data: ChartData): void;
     protected applyComponentOverrides(overrides: Map<ChartComponentBase, ChartComponentBase>): () => void;
     protected prepareLayout(context: BaseLayoutContext): void;
     private getYAxisEstimateLabels;
@@ -76,6 +81,11 @@ export declare class XYChart extends BaseChart {
     private applyNiceDomain;
     private getAreaTooltipValue;
     private renderSeries;
+    private getBarBaselinePosition;
+    private getPointBaselineY;
+    private getNumericPointBaselineDomain;
+    private getPointBaselineValue;
+    private getPointBaselineFallback;
     private computeStackingData;
     private computeAreaStackingContexts;
 }

package/dist/xy-chart.js

@@ -4,7 +4,19 @@ import { ChartValidationError, ChartValidator } from './validation.js';
 import { GROUPED_GAP_TICK_PREFIX, GROUPED_GROUP_LABEL_KEY, } from './grouped-data.js';
 import { resolveScaleValue } from './scale-utils.js';
 import { mergeDeep } from './utils.js';
+import { createXYMotionDriver, } from './xy-motion/driver.js';
+import { createXYSeriesSnapshotId } from './xy-motion/helpers.js';
 const DEFAULT_SERIES_COLOR = '#8884d8';
+function resolveBarStackSettings(config) {
+    return {
+        mode: config.barStack?.mode ?? 'normal',
+        gap: config.barStack?.gap ?? 0.1,
+        reverseSeries: config.barStack?.reverseSeries ?? false,
+    };
+}
+function resolveAreaStackMode(config) {
+    return config.areaStack?.mode ?? 'none';
+}
 function isXYSeries(component) {
     return (component.type === 'line' ||
         component.type === 'scatter' ||
@@ -50,17 +62,25 @@ export class XYChart extends BaseChart {
             writable: true,
             value: void 0
         });
+        Object.defineProperty(this, "motionDriver", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
         Object.defineProperty(this, "scaleConfigOverride", {
             enumerable: true,
             configurable: true,
             writable: true,
             value: null
         });
+        const barStack = resolveBarStackSettings(config);
         this.orientation = config.orientation ?? 'vertical';
-        this.barStackMode = config.barStack?.mode ?? 'normal';
-        this.barStackGap = config.barStack?.gap ?? 0.1;
-        this.barStackReverseSeries = config.barStack?.reverseSeries ?? false;
-        this.areaStackMode = config.areaStack?.mode ?? 'none';
+        this.barStackMode = barStack.mode;
+        this.barStackGap = barStack.gap;
+        this.barStackReverseSeries = barStack.reverseSeries;
+        this.areaStackMode = resolveAreaStackMode(config);
+        this.motionDriver = createXYMotionDriver(config.animate);
     }
     addChild(component) {
         if (isXYSeries(component)) {
@@ -101,7 +121,15 @@ export class XYChart extends BaseChart {
             areaStack: {
                 mode: this.areaStackMode,
             },
+            animate: false,
+        });
+    }
+    update(data) {
+        this.motionDriver.prepareForUpdate({
+            plotGroup: this.plotGroup,
+            visibleSeries: this.getVisibleSeries(),
         });
+        super.update(data);
     }
     applyComponentOverrides(overrides) {
         const restoreBase = super.applyComponentOverrides(overrides);
@@ -187,7 +215,8 @@ export class XYChart extends BaseChart {
         if (this.grid && this.x && this.y) {
             this.grid.render(plotGroup, this.x, this.y, this.renderTheme, this.isHorizontalOrientation());
         }
-        this.renderSeries(visibleSeries);
+        const motionResult = this.renderSeries(visibleSeries);
+        this.setReadyPromise(this.motionDriver.completeRender(motionResult));
         this.renderAxes(svg, plotArea);
         this.attachTooltip(svg, plotArea, visibleSeries, xKey, categoryScaleType);
         this.renderInlineLegend(svg);
@@ -785,7 +814,10 @@ export class XYChart extends BaseChart {
     }
     renderSeries(visibleSeries) {
         if (!this.plotGroup || !this.x || !this.y) {
-            return;
+            return {
+                snapshotCollection: new Map(),
+                transitions: [],
+            };
         }
         const xKey = this.getXKey();
         const categoryScaleType = this.getCategoryScaleType();
@@ -800,6 +832,8 @@ export class XYChart extends BaseChart {
             : null;
         const { cumulativeDataBySeriesIndex, positiveCumulativeDataBySeriesIndex, negativeCumulativeDataBySeriesIndex, totalData, positiveTotalData, negativeTotalData, rawValuesBySeriesIndex, } = this.computeStackingData(this.data, xKey, barSeries);
         const areaStackingContextBySeries = this.computeAreaStackingContexts(this.data, xKey, areaSeries);
+        const snapshotCollection = new Map();
+        const transitions = [];
         barSeries.forEach((series, barIndex) => {
             const nextLayerData = this.barStackMode === 'layer'
                 ? rawValuesBySeriesIndex.get(barIndex + 1)
@@ -819,20 +853,83 @@ export class XYChart extends BaseChart {
                 gap: this.barStackGap,
                 nextLayerData,
             };
-            series.render(this.plotGroup, this.data, xKey, this.x, this.y, this.parseValue, categoryScaleType, this.renderTheme, stackingContext, this.orientation);
+            const result = series.render(this.plotGroup, this.data, xKey, this.x, this.y, this.parseValue, categoryScaleType, this.renderTheme, stackingContext, this.orientation, this.motionDriver.getBarAnimationContext(series, this.getBarBaselinePosition()));
+            snapshotCollection.set(createXYSeriesSnapshotId(series.type, series.dataKey), result.snapshot);
+            transitions.push(...result.transitions);
         });
         areaSeries.forEach((series) => {
-            series.render(this.plotGroup, this.data, xKey, this.x, this.y, this.parseValue, categoryScaleType, this.renderTheme, areaStackingContextBySeries.get(series), areaValueLabelLayer ?? undefined);
+            const result = series.render(this.plotGroup, this.data, xKey, this.x, this.y, this.parseValue, categoryScaleType, this.renderTheme, areaStackingContextBySeries.get(series), areaValueLabelLayer ?? undefined, this.motionDriver.getAreaAnimationContext(series));
+            snapshotCollection.set(createXYSeriesSnapshotId(series.type, series.dataKey), result.snapshot);
+            transitions.push(...result.transitions);
         });
         lineSeries.forEach((series) => {
-            series.render(this.plotGroup, this.data, xKey, this.x, this.y, this.parseValue, categoryScaleType, this.renderTheme);
+            const result = series.render(this.plotGroup, this.data, xKey, this.x, this.y, this.parseValue, categoryScaleType, this.renderTheme, this.motionDriver.getPointAnimationContext(series, this.getPointBaselineY()));
+            snapshotCollection.set(createXYSeriesSnapshotId(series.type, series.dataKey), result.snapshot);
+            transitions.push(...result.transitions);
         });
         scatterSeries.forEach((series) => {
-            series.render(this.plotGroup, this.data, xKey, this.x, this.y, this.parseValue, categoryScaleType, this.renderTheme);
+            const result = series.render(this.plotGroup, this.data, xKey, this.x, this.y, this.parseValue, categoryScaleType, this.renderTheme, this.motionDriver.getPointAnimationContext(series, this.getPointBaselineY()));
+            snapshotCollection.set(createXYSeriesSnapshotId(series.type, series.dataKey), result.snapshot);
+            transitions.push(...result.transitions);
         });
         if (areaValueLabelLayer) {
             areaValueLabelLayer.raise();
         }
+        return {
+            snapshotCollection,
+            transitions,
+        };
+    }
+    getBarBaselinePosition() {
+        const valueScale = this.isHorizontalOrientation() ? this.x : this.y;
+        if (!valueScale) {
+            return 0;
+        }
+        return valueScale(0) ?? 0;
+    }
+    getPointBaselineY() {
+        if (!this.y) {
+            return 0;
+        }
+        const numericDomain = this.getNumericPointBaselineDomain();
+        if (!numericDomain) {
+            return this.getPointBaselineFallback();
+        }
+        const baselineValue = this.getPointBaselineValue(numericDomain);
+        return (this.y(baselineValue) ?? this.getPointBaselineFallback());
+    }
+    getNumericPointBaselineDomain() {
+        if (!this.y) {
+            return null;
+        }
+        const domain = this.y.domain?.();
+        if (!Array.isArray(domain) ||
+            domain.length < 2 ||
+            typeof domain[0] !== 'number' ||
+            typeof domain[1] !== 'number') {
+            return null;
+        }
+        return [domain[0], domain[1]];
+    }
+    getPointBaselineValue(domain) {
+        const minValue = Math.min(...domain);
+        const maxValue = Math.max(...domain);
+        if (minValue <= 0 && maxValue >= 0) {
+            return 0;
+        }
+        return Math.abs(domain[0]) <= Math.abs(domain[1])
+            ? domain[0]
+            : domain[1];
+    }
+    getPointBaselineFallback() {
+        if (!this.y) {
+            return 0;
+        }
+        const range = this.y.range?.();
+        if (!Array.isArray(range) || range.length === 0) {
+            return 0;
+        }
+        return Math.max(...range);
     }
     computeStackingData(data, xKey, barSeries) {
         const cumulativeDataBySeriesIndex = new Map();

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

@@ -0,0 +1,2 @@
+import type { NormalizedXYAnimation, XYAnimationConfig } from './types.js';
+export declare function normalizeXYAnimationConfig(config: boolean | XYAnimationConfig | undefined): NormalizedXYAnimation;

package/dist/xy-motion/config.js

@@ -0,0 +1,177 @@
+import { ChartValidationError, ChartValidator } from '../validation.js';
+import { easeBounceOut, easeCubicIn, easeCubicInOut, easeCubicOut, easeElasticOut, easeLinear, } from 'd3';
+const DEFAULT_ANIMATE = false;
+const DEFAULT_ANIMATION_DURATION_MS = 700;
+const DEFAULT_ANIMATION_EASING_PRESET = 'ease-in-out';
+const XY_ANIMATION_EASING_PRESETS = {
+    linear: easeLinear,
+    'ease-in': easeCubicIn,
+    'ease-out': easeCubicOut,
+    'ease-in-out': easeCubicInOut,
+    'bounce-out': easeBounceOut,
+    'elastic-out': easeElasticOut,
+};
+export function normalizeXYAnimationConfig(config) {
+    if (config === undefined) {
+        return {
+            show: DEFAULT_ANIMATE,
+            duration: DEFAULT_ANIMATION_DURATION_MS,
+            easing: XY_ANIMATION_EASING_PRESETS[DEFAULT_ANIMATION_EASING_PRESET],
+        };
+    }
+    if (typeof config === 'boolean') {
+        return {
+            show: config,
+            duration: DEFAULT_ANIMATION_DURATION_MS,
+            easing: XY_ANIMATION_EASING_PRESETS[DEFAULT_ANIMATION_EASING_PRESET],
+        };
+    }
+    const normalized = {
+        show: config.show ?? true,
+        duration: config.duration ?? DEFAULT_ANIMATION_DURATION_MS,
+        easing: resolveXYAnimationEasing(config.easing),
+    };
+    if (!Number.isFinite(normalized.duration) || normalized.duration < 0) {
+        throw new ChartValidationError(`XYChart: animate.duration must be >= 0, received '${normalized.duration}'`);
+    }
+    return normalized;
+}
+function resolveXYAnimationEasing(easing) {
+    if (!easing) {
+        return XY_ANIMATION_EASING_PRESETS[DEFAULT_ANIMATION_EASING_PRESET];
+    }
+    if (typeof easing === 'function') {
+        return easing;
+    }
+    if (easing in XY_ANIMATION_EASING_PRESETS) {
+        return XY_ANIMATION_EASING_PRESETS[easing];
+    }
+    if (easing.startsWith('linear(')) {
+        const parsedCssLinear = parseCssLinearEasing(easing);
+        if (parsedCssLinear) {
+            return parsedCssLinear;
+        }
+    }
+    ChartValidator.warn(`XYChart: unsupported animate.easing '${easing}', falling back to '${DEFAULT_ANIMATION_EASING_PRESET}'`);
+    return XY_ANIMATION_EASING_PRESETS[DEFAULT_ANIMATION_EASING_PRESET];
+}
+function parseCssLinearEasing(cssLinearEasing) {
+    const normalized = cssLinearEasing.trim();
+    if (!normalized.startsWith('linear(') || !normalized.endsWith(')')) {
+        return null;
+    }
+    const body = normalized.slice('linear('.length, -1);
+    const tokens = body
+        .split(',')
+        .map((token) => token.trim())
+        .filter((token) => token.length > 0);
+    if (tokens.length < 2) {
+        return null;
+    }
+    const rawStops = tokens.map((token) => parseLinearEasingStop(token));
+    if (rawStops.some((stop) => stop === null)) {
+        return null;
+    }
+    const stops = rawStops;
+    const firstPosition = stops[0].position ?? 0;
+    const lastPosition = stops[stops.length - 1].position ?? 1;
+    if (!hasValidLinearStopPositions(stops, firstPosition, lastPosition)) {
+        return null;
+    }
+    fillMissingLinearStopPositions(stops, firstPosition, lastPosition);
+    return (progress) => sampleLinearEasing(stops, progress);
+}
+function hasValidLinearStopPositions(stops, firstPosition, lastPosition) {
+    if (lastPosition <= firstPosition) {
+        return false;
+    }
+    let previousPosition = firstPosition;
+    for (let index = 1; index < stops.length; index += 1) {
+        const stopPosition = stops[index].position;
+        if (stopPosition === undefined) {
+            continue;
+        }
+        if (stopPosition < previousPosition) {
+            return false;
+        }
+        previousPosition = stopPosition;
+    }
+    return true;
+}
+function parseLinearEasingStop(token) {
+    const parts = token
+        .trim()
+        .split(/\s+/)
+        .map((part) => part.trim())
+        .filter((part) => part.length > 0);
+    if (parts.length === 0 || parts.length > 2) {
+        return null;
+    }
+    const value = Number(parts[0]);
+    if (!Number.isFinite(value)) {
+        return null;
+    }
+    if (parts.length === 1) {
+        return { value, position: undefined };
+    }
+    const positionText = parts[1];
+    if (!positionText.endsWith('%')) {
+        return null;
+    }
+    const percentValue = Number(positionText.slice(0, -1));
+    if (!Number.isFinite(percentValue)) {
+        return null;
+    }
+    return {
+        value,
+        position: percentValue / 100,
+    };
+}
+function fillMissingLinearStopPositions(stops, firstPosition, lastPosition) {
+    stops[0].position = firstPosition;
+    stops[stops.length - 1].position = lastPosition;
+    let index = 1;
+    while (index < stops.length - 1) {
+        if (stops[index].position !== undefined) {
+            index += 1;
+            continue;
+        }
+        const startIndex = index - 1;
+        let endIndex = index + 1;
+        while (endIndex < stops.length &&
+            stops[endIndex].position === undefined) {
+            endIndex += 1;
+        }
+        const start = stops[startIndex].position ?? firstPosition;
+        const end = stops[endIndex].position ?? lastPosition;
+        const gapSize = (end - start) / (endIndex - startIndex);
+        for (let fillIndex = index; fillIndex < endIndex; fillIndex += 1) {
+            stops[fillIndex].position =
+                start + gapSize * (fillIndex - startIndex);
+        }
+        index = endIndex;
+    }
+}
+function sampleLinearEasing(stops, progress) {
+    if (progress <= (stops[0].position ?? 0)) {
+        return stops[0].value;
+    }
+    if (progress >= (stops[stops.length - 1].position ?? 1)) {
+        return stops[stops.length - 1].value;
+    }
+    for (let index = 1; index < stops.length; index += 1) {
+        const previousStop = stops[index - 1];
+        const nextStop = stops[index];
+        const start = previousStop.position ?? 0;
+        const end = nextStop.position ?? 1;
+        if (progress > end) {
+            continue;
+        }
+        if (end === start) {
+            return nextStop.value;
+        }
+        const ratio = (progress - start) / (end - start);
+        return (previousStop.value + (nextStop.value - previousStop.value) * ratio);
+    }
+    return stops[stops.length - 1].value;
+}

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

@@ -0,0 +1,9 @@
+import type { XYAnimationConfig, XYAreaAnimationContext, XYBarAnimationContext, XYMotionRenderResult, XYMotionSeries, XYMotionUpdateContext, XYPointAnimationContext } from './types.js';
+export interface 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>;
+}
+export declare function createXYMotionDriver(config: boolean | XYAnimationConfig | undefined): XYMotionDriverContract;

package/dist/xy-motion/driver.js

@@ -0,0 +1,10 @@
+import { normalizeXYAnimationConfig } from './config.js';
+import { NoopXYMotionDriver } from './noop-xy-motion-driver.js';
+import { XYMotionDriver } from './xy-motion-driver.js';
+export function createXYMotionDriver(config) {
+    const animation = normalizeXYAnimationConfig(config);
+    if (!animation.show) {
+        return new NoopXYMotionDriver();
+    }
+    return new XYMotionDriver(animation);
+}

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

@@ -0,0 +1,17 @@
+import type { DataItem } from '../types.js';
+type TransitionLike = {
+    end: () => Promise<unknown>;
+};
+type XYEnterStaggerTiming = {
+    delay: number;
+    duration: number;
+};
+export declare function createXYSeriesSnapshotId(seriesType: string, dataKey: string): string;
+export declare function createXYDatumKey(value: unknown): string;
+export declare function buildXYDatumSnapshotKeys(data: DataItem[], xKey: string): string[];
+export declare function cloneXYSeriesSnapshotCollection<TSnapshot>(collection: Map<string, Map<string, TSnapshot>>): Map<string, Map<string, TSnapshot>>;
+export declare function createTransitionCompletionPromise(transition: TransitionLike): Promise<void>;
+export declare function createXYAnimationId(prefix: string): string;
+export declare function createLeftToRightRevealTransition(target: SVGGraphicsElement | null, duration: number, easing: (progress: number) => number, idPrefix: string, padding?: number, initialProgress?: number): Promise<void>[];
+export declare function getEnterStaggerTiming(index: number, itemCount: number, totalDuration: number, maxDelayShare?: number): XYEnterStaggerTiming;
+export {};

package/dist/xy-motion/helpers.js

@@ -0,0 +1,105 @@
+import { select } from 'd3';
+const DEFAULT_ENTER_STAGGER_SHARE = 0.55;
+export function createXYSeriesSnapshotId(seriesType, dataKey) {
+    return `${seriesType}:${dataKey}`;
+}
+export function createXYDatumKey(value) {
+    return createXYDatumKeyWithOccurrence(value, 0);
+}
+function createXYDatumKeyWithOccurrence(value, occurrenceIndex) {
+    if (value instanceof Date) {
+        const isoValue = value.toISOString();
+        return occurrenceIndex === 0
+            ? isoValue
+            : `${isoValue}::${occurrenceIndex}`;
+    }
+    const stringValue = String(value);
+    return occurrenceIndex === 0
+        ? stringValue
+        : `${stringValue}::${occurrenceIndex}`;
+}
+export function buildXYDatumSnapshotKeys(data, xKey) {
+    const occurrenceCounts = new Map();
+    return data.map((entry) => {
+        const baseKey = createXYDatumKey(entry[xKey]);
+        const occurrenceIndex = occurrenceCounts.get(baseKey) ?? 0;
+        occurrenceCounts.set(baseKey, occurrenceIndex + 1);
+        return createXYDatumKeyWithOccurrence(entry[xKey], occurrenceIndex);
+    });
+}
+export function cloneXYSeriesSnapshotCollection(collection) {
+    return new Map(Array.from(collection.entries(), ([seriesKey, snapshot]) => {
+        return [seriesKey, new Map(snapshot)];
+    }));
+}
+export function createTransitionCompletionPromise(transition) {
+    return transition.end().then(() => undefined, () => undefined);
+}
+let xyAnimationIdCounter = 0;
+export function createXYAnimationId(prefix) {
+    xyAnimationIdCounter += 1;
+    return `${prefix}-${xyAnimationIdCounter}`;
+}
+export function createLeftToRightRevealTransition(target, duration, easing, idPrefix, padding = 0, initialProgress = 0) {
+    if (!target) {
+        return [];
+    }
+    const svg = target.ownerSVGElement;
+    if (!svg) {
+        return [];
+    }
+    const bbox = target.getBBox();
+    const clipWidth = Math.max(1, bbox.width + padding * 2);
+    const clipHeight = Math.max(1, bbox.height + padding * 2);
+    const clampedInitialProgress = Math.max(0, Math.min(1, initialProgress));
+    if (clampedInitialProgress >= 1) {
+        return [];
+    }
+    const clipId = createXYAnimationId(idPrefix);
+    const defs = select(svg)
+        .selectAll('defs.xy-animation-defs')
+        .data([undefined])
+        .join('defs')
+        .attr('class', 'xy-animation-defs');
+    const clipPath = defs
+        .append('clipPath')
+        .attr('id', clipId)
+        .attr('class', 'xy-animation-reveal-clip');
+    const clipRect = clipPath
+        .append('rect')
+        .attr('x', bbox.x - padding)
+        .attr('y', bbox.y - padding)
+        .attr('width', clipWidth * clampedInitialProgress)
+        .attr('height', clipHeight);
+    const targetSelection = select(target);
+    targetSelection.attr('clip-path', `url(#${clipId})`);
+    return [
+        clipRect
+            .transition()
+            .duration(duration)
+            .ease(easing)
+            .attr('width', clipWidth)
+            .end()
+            .then(() => {
+            targetSelection.attr('clip-path', null);
+            clipPath.remove();
+        }, () => {
+            targetSelection.attr('clip-path', null);
+            clipPath.remove();
+        }),
+    ];
+}
+export function getEnterStaggerTiming(index, itemCount, totalDuration, maxDelayShare = DEFAULT_ENTER_STAGGER_SHARE) {
+    const delayRange = totalDuration * maxDelayShare;
+    const duration = Math.max(totalDuration - delayRange, 1);
+    if (itemCount <= 1) {
+        return {
+            delay: 0,
+            duration,
+        };
+    }
+    return {
+        delay: (delayRange * index) / (itemCount - 1),
+        duration,
+    };
+}

package/dist/xy-motion/live-state.d.ts

@@ -0,0 +1,8 @@
+import { type Selection } from 'd3';
+import { type XYLivePathStateCollection, type XYMotionSeries, type XYSeriesSnapshotCollection } from './types.js';
+type PlotGroup = Selection<SVGGElement, undefined, null, undefined>;
+export declare function captureLiveAnimationState(plotGroup: PlotGroup | null, visibleSeries: XYMotionSeries[], lastSeriesSnapshot: XYSeriesSnapshotCollection): {
+    snapshotCollection: XYSeriesSnapshotCollection;
+    pathState: XYLivePathStateCollection;
+};
+export {};