@internetstiftelsen/charts 0.14.0 → 0.14.2

package/README.md

@@ -362,6 +362,7 @@ const data = [
 
 const chart = new WordCloudChart({
     data,
+    animate: true,
     wordCloud: {
         minValue: 5,
         minWordLength: 3,
@@ -379,6 +380,8 @@ chart.render('#word-cloud');
 dimension and define the relative size range passed into `d3-cloud`. The chart
 expects flat `{ word, count }` rows, aggregates duplicate words after trimming,
 and maps theme typography and colors directly into the layout and rendered SVG.
+Set `animate: true` or pass an animation config to fade and scale words from
+their own centers on initial render and `chart.update(...)`.
 
 ## Export
 
@@ -391,8 +394,8 @@ await chart.export('xlsx', { download: true, sheetName: 'Data' });
 await chart.export('pdf', { download: true, pdfMargin: 16 });
 ```
 
-`xlsx` and `pdf` are lazy-loaded and require optional dependencies (`xlsx` and
-`jspdf`) only when those formats are used.
+`xlsx` and `pdf` are lazy-loaded and require optional dependencies
+(`write-excel-file` and `jspdf`) only when those formats are used.
 
 ## Import
 

package/dist/base-chart.d.ts

@@ -16,6 +16,7 @@ type RenderDimensions = {
     svgWidthAttr: number | string;
     svgHeightAttr: number | string;
 };
+type PlotAreaOverride = Partial<Pick<PlotAreaBounds, 'top' | 'right' | 'bottom' | 'left'>>;
 type ResponsiveOverrides = {
     theme?: DeepPartial<ChartTheme>;
     components: Map<ChartComponentBase, Record<string, unknown>>;
@@ -123,6 +124,7 @@ export declare abstract class BaseChart {
     private disconnectedLegendContainer;
     private renderThemeOverride;
     private renderSizeOverride;
+    private plotAreaOverride;
     private legendModeOverride;
     private readonly eventListeners;
     private renderId;
@@ -165,6 +167,10 @@ export declare abstract class BaseChart {
         width?: number;
         height?: number;
     };
+    /** @internal */
+    measurePlotArea(width: number, height: number): PlotAreaBounds;
+    /** @internal */
+    setPlotAreaOverride(override: PlotAreaOverride | null, rerender?: boolean): this;
     setLegendModeOverride(mode: LegendMode | null, rerender?: boolean): this;
     on<TEventName extends ChartEventName>(eventName: TEventName, listener: ChartEventListener<TEventName>): this;
     off<TEventName extends ChartEventName>(eventName: TEventName, listener: ChartEventListener<TEventName>): this;
@@ -202,6 +208,7 @@ export declare abstract class BaseChart {
     protected prepareForLegendChange(): void;
     protected initializeDataState(): void;
     protected prepareLayout(context: BaseLayoutContext): void;
+    private applyPlotAreaOverride;
     /**
      * Setup ResizeObserver for automatic resize handling
      */

package/dist/base-chart.js

@@ -219,6 +219,12 @@ export class BaseChart {
             writable: true,
             value: null
         });
+        Object.defineProperty(this, "plotAreaOverride", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: null
+        });
         Object.defineProperty(this, "legendModeOverride", {
             enumerable: true,
             configurable: true,
@@ -361,7 +367,7 @@ export class BaseChart {
             // Calculate layout
             this.layoutManager = new LayoutManager(this.resolvedRenderTheme);
             const components = this.getLayoutComponents();
-            const plotArea = this.layoutManager.calculateLayout(components);
+            const plotArea = this.applyPlotAreaOverride(this.layoutManager.calculateLayout(components));
             this.plotArea = plotArea;
             // Create plot group
             const plotGroup = this.svg.append('g').attr('class', 'chart-plot');
@@ -517,6 +523,59 @@ export class BaseChart {
             height: this.configuredHeight,
         };
     }
+    /** @internal */
+    measurePlotArea(width, height) {
+        const previousWidth = this.width;
+        const previousHeight = this.height;
+        const measurementSvg = create('svg')
+            .attr('width', width)
+            .attr('height', height)
+            .style('position', 'absolute')
+            .style('left', '-9999px')
+            .style('top', '-9999px')
+            .style('overflow', 'hidden')
+            .style('pointer-events', 'none');
+        const svgNode = measurementSvg.node();
+        if (!svgNode) {
+            throw new Error('Failed to initialize chart measurement SVG');
+        }
+        document.body.appendChild(svgNode);
+        this.width = width;
+        this.height = height;
+        const responsiveContext = this.resolveResponsiveContext({
+            width,
+            height,
+        });
+        const responsiveOverrides = this.collectResponsiveOverrides(responsiveContext);
+        const mergedComponentOverrides = this.mergeComponentOverrideMaps(responsiveOverrides.components);
+        const renderTheme = this.resolveRenderTheme(responsiveOverrides);
+        const overrideComponents = this.createOverrideComponents(mergedComponentOverrides);
+        const restoreComponents = this.applyComponentOverrides(overrideComponents);
+        const restoreTheme = this.applyRenderTheme(renderTheme);
+        try {
+            this.prepareLayout({
+                svg: measurementSvg,
+                svgNode,
+            });
+            const layoutManager = new LayoutManager(this.resolvedRenderTheme);
+            return this.applyPlotAreaOverride(layoutManager.calculateLayout(this.getLayoutComponents()));
+        }
+        finally {
+            restoreComponents();
+            restoreTheme();
+            this.width = previousWidth;
+            this.height = previousHeight;
+            svgNode.remove();
+        }
+    }
+    /** @internal */
+    setPlotAreaOverride(override, rerender = true) {
+        this.plotAreaOverride = override;
+        if (rerender) {
+            this.rerender('component');
+        }
+        return this;
+    }
     setLegendModeOverride(mode, rerender = true) {
         if (this.legendModeOverride === mode) {
             return this;
@@ -854,6 +913,23 @@ export class BaseChart {
     prepareLayout(context) {
         this.measureInlineLegend(context.svgNode);
     }
+    applyPlotAreaOverride(plotArea) {
+        if (!this.plotAreaOverride) {
+            return plotArea;
+        }
+        const left = this.plotAreaOverride.left ?? plotArea.left;
+        const right = this.plotAreaOverride.right ?? plotArea.right;
+        const top = this.plotAreaOverride.top ?? plotArea.top;
+        const bottom = this.plotAreaOverride.bottom ?? plotArea.bottom;
+        return {
+            left,
+            right,
+            top,
+            bottom,
+            width: Math.max(0, right - left),
+            height: Math.max(0, bottom - top),
+        };
+    }
     /**
      * Setup ResizeObserver for automatic resize handling
      */

package/dist/chart-group.d.ts

@@ -96,6 +96,7 @@ export declare class ChartGroup {
     private resolveSharedYDomain;
     private warnIncompatibleYScaleTypes;
     private applyScaleSyncOverrides;
+    private applyPlotAreaSyncOverrides;
     private buildRows;
     private resolveDefaultChartHeight;
     private resolveDefaultChartHeightForWidth;

package/dist/chart-group.js

@@ -291,7 +291,9 @@ export class ChartGroup {
         const { width, renderedTopText, renderedBottomText, renderedLegend, layout, totalHeight, } = this.prepareRenderState(container);
         this.isRendering = true;
         try {
-            this.applyScaleSyncOverrides(width);
+            const sharedYDomain = this.resolveSharedYDomain(width);
+            this.applyScaleSyncOverrides(width, sharedYDomain);
+            this.applyPlotAreaSyncOverrides(layout.items, sharedYDomain);
             container.innerHTML = '';
             const { root, chartLayer } = this.createRenderHosts(totalHeight, layout.chartHeight);
             this.appendRenderedTextSections(root, renderedTopText);
@@ -376,6 +378,7 @@ export class ChartGroup {
             chart.setLegendModeOverride(null, false);
             if (chart instanceof XYChart) {
                 chart.setScaleConfigOverride(null, false);
+                chart.setPlotAreaOverride(null, false);
             }
             chart.destroy();
         });
@@ -508,9 +511,8 @@ export class ChartGroup {
         this.hasWarnedIncompatibleYScaleTypes = true;
         ChartValidator.warn('ChartGroup: syncY requires all synced XY child charts to use the same vertical numeric scale type');
     }
-    applyScaleSyncOverrides(width) {
+    applyScaleSyncOverrides(width, sharedDomain) {
         const syncedCharts = new Set(this.getVerticalXYCharts(width));
-        const sharedDomain = this.resolveSharedYDomain(width);
         this.getAllVerticalXYCharts().forEach((chart) => {
             if (!sharedDomain || !syncedCharts.has(chart)) {
                 chart.setScaleConfigOverride(null, false);
@@ -524,6 +526,43 @@ export class ChartGroup {
             }, false);
         });
     }
+    applyPlotAreaSyncOverrides(items, sharedDomain) {
+        this.getAllVerticalXYCharts().forEach((chart) => {
+            chart.setPlotAreaOverride(null, false);
+        });
+        if (!sharedDomain) {
+            return;
+        }
+        const rowItems = new Map();
+        items.forEach((item) => {
+            if (!(item.chart instanceof XYChart) ||
+                item.chart.getOrientation() !== 'vertical') {
+                return;
+            }
+            const row = rowItems.get(item.y) ?? [];
+            row.push(item);
+            rowItems.set(item.y, row);
+        });
+        rowItems.forEach((row) => {
+            if (row.length < 2) {
+                return;
+            }
+            const measuredPlotAreas = row.map((item) => {
+                return {
+                    chart: item.chart,
+                    plotArea: item.chart.measurePlotArea(item.width, item.height),
+                };
+            });
+            const top = Math.max(...measuredPlotAreas.map(({ plotArea }) => plotArea.top));
+            const bottom = Math.min(...measuredPlotAreas.map(({ plotArea }) => plotArea.bottom));
+            if (bottom <= top) {
+                return;
+            }
+            measuredPlotAreas.forEach(({ chart }) => {
+                chart.setPlotAreaOverride({ top, bottom }, false);
+            });
+        });
+    }
     buildRows(entries, width, cols, gap) {
         const availableWidth = Math.max(1, width - gap * Math.max(0, cols - 1));
         const columnWidth = availableWidth / cols;
@@ -802,10 +841,12 @@ export class ChartGroup {
         this.resizeObserver.observe(this.container);
     }
     async exportSVG(format, width, options) {
-        this.applyScaleSyncOverrides(width);
+        const sharedYDomain = this.resolveSharedYDomain(width);
+        this.applyScaleSyncOverrides(width, sharedYDomain);
         const baseContext = this.createExportRenderContext(format, width, options);
         const exportLayoutState = this.resolveExportLayoutState(width, baseContext);
         const layout = this.calculateLayout(width, exportLayoutState.chartAreaHeight, exportLayoutState.defaultChartHeightOverride);
+        this.applyPlotAreaSyncOverrides(layout.items, sharedYDomain);
         const childSvgs = await this.exportLayoutItems(layout.items, options);
         const totalHeight = exportLayoutState.topTextHeight +
             layout.chartHeight +

package/dist/export-xlsx.d.ts

@@ -1,4 +1,4 @@
 import type { ChartData, ExportOptions } from './types.js';
-type XlsxLoader = () => Promise<unknown>;
-export declare function exportXLSXBlob(data: ChartData, options?: ExportOptions, loader?: XlsxLoader): Promise<Blob>;
+type XlsxWriterLoader = () => Promise<unknown>;
+export declare function exportXLSXBlob(data: ChartData, options?: ExportOptions, loader?: XlsxWriterLoader): Promise<Blob>;
 export {};

package/dist/export-xlsx.js

@@ -3,42 +3,38 @@ const XLSX_MIME_TYPE = 'application/vnd.openxmlformats-officedocument.spreadshee
 function isObject(value) {
     return typeof value === 'object' && value !== null;
 }
-function resolveXlsxApi(moduleValue) {
+function resolveXlsxWriter(moduleValue) {
+    if (typeof moduleValue === 'function') {
+        return moduleValue;
+    }
     if (!isObject(moduleValue)) {
-        throw new Error('Invalid "xlsx" module export');
+        throw new Error('Invalid "write-excel-file" module export');
     }
     const moduleCandidate = moduleValue;
-    const xlsxCandidate = moduleCandidate.default && isObject(moduleCandidate.default)
-        ? moduleCandidate.default
-        : moduleCandidate;
-    if (!xlsxCandidate.utils || !xlsxCandidate.write) {
-        throw new Error('Invalid "xlsx" module export');
+    if (typeof moduleCandidate.default === 'function') {
+        return moduleCandidate.default;
     }
-    return {
-        utils: xlsxCandidate.utils,
-        write: xlsxCandidate.write,
-    };
+    throw new Error('Invalid "write-excel-file" module export');
 }
-async function defaultXlsxLoader() {
-    return import('xlsx');
+async function defaultXlsxWriterLoader() {
+    return import('write-excel-file/universal');
 }
-export async function exportXLSXBlob(data, options, loader = defaultXlsxLoader) {
-    let xlsxModule;
+export async function exportXLSXBlob(data, options, loader = defaultXlsxWriterLoader) {
+    let xlsxWriterModule;
     try {
-        xlsxModule = await loader();
+        xlsxWriterModule = await loader();
     }
     catch {
-        throw new Error('XLSX export requires optional dependency "xlsx". Install optional dependency "xlsx".');
+        throw new Error('XLSX export requires optional dependency "write-excel-file". Install optional dependency "write-excel-file".');
     }
-    const xlsx = resolveXlsxApi(xlsxModule);
+    const writeXlsxFile = resolveXlsxWriter(xlsxWriterModule);
     const { columns, rows } = toTabularData(data, options?.columns);
-    const worksheet = xlsx.utils.aoa_to_sheet([columns, ...rows]);
-    const workbook = xlsx.utils.book_new();
     const sheetName = options?.sheetName?.trim() || 'Sheet1';
-    xlsx.utils.book_append_sheet(workbook, worksheet, sheetName);
-    const buffer = xlsx.write(workbook, {
-        type: 'array',
-        bookType: 'xlsx',
-    });
-    return new Blob([buffer], { type: XLSX_MIME_TYPE });
+    const blob = await writeXlsxFile([columns, ...rows], {
+        sheet: sheetName,
+    }).toBlob();
+    if (blob.type === XLSX_MIME_TYPE) {
+        return blob;
+    }
+    return new Blob([await blob.arrayBuffer()], { type: XLSX_MIME_TYPE });
 }

package/dist/word-cloud-chart.d.ts

@@ -2,6 +2,12 @@ import { BaseChart, type BaseChartConfig, type BaseRenderContext } from './base-
 import type { ChartData } from './types.js';
 export type WordCloudRotationMode = 'none' | 'right-angle';
 export type WordCloudSpiral = 'archimedean' | 'rectangular';
+export type WordCloudAnimationEasingPreset = 'linear' | 'ease-in' | 'ease-out' | 'ease-in-out' | 'bounce-out' | 'elastic-out' | 'spring-out';
+export type WordCloudAnimationConfig = {
+    show?: boolean;
+    duration?: number;
+    easing?: WordCloudAnimationEasingPreset | `linear(${string})` | ((progress: number) => number);
+};
 export type WordCloudConfig = {
     maxWords?: number;
     minWordLength?: number;
@@ -14,19 +20,43 @@ export type WordCloudConfig = {
 };
 export type WordCloudChartConfig = Pick<BaseChartConfig, 'data' | 'width' | 'height' | 'theme' | 'responsive'> & {
     wordCloud?: WordCloudConfig;
+    animate?: boolean | WordCloudAnimationConfig;
 };
 export declare class WordCloudChart extends BaseChart {
     private readonly options;
+    private readonly animation;
     private layout;
     private layoutRunId;
     private resolvePendingReady;
+    private hasRenderedLive;
+    private nextRenderShouldAnimate;
+    private previousWordSnapshot;
     constructor(config: WordCloudChartConfig);
+    update(data: ChartData): void;
     destroy(): void;
     protected validateSourceData(data: ChartData): void;
     protected renderChart({ svg, plotArea }: BaseRenderContext): void;
     protected createExportChart(): BaseChart;
+    private prepareAnimationForUpdate;
     private startLayout;
     private renderWords;
+    private shouldAnimateWords;
+    private createInitialWordTransform;
+    private createInitialWordTransformState;
+    private createWordTransform;
+    private createWordTransformState;
+    private createWordPositionTransform;
+    private createInitialScaleTransform;
+    private createScaleTransform;
+    private createInitialWordOpacity;
+    private animateWords;
+    private createWordGroupAnimationEntries;
+    private createWordTextAnimationEntries;
+    private applyWordAnimationFrame;
+    private requestAnimationFrame;
+    private now;
+    private completeRender;
+    private createWordSnapshot;
     private stopLayout;
     private finishReady;
 }

package/dist/word-cloud-chart.js

@@ -2,6 +2,7 @@ import cloud from 'd3-cloud';
 import { scaleSqrt } from 'd3';
 import { BaseChart, } from './base-chart.js';
 import { isGroupedData } from './grouped-data.js';
+import { normalizeRadialAnimationConfig, } from './radial-animation.js';
 const DEFAULT_OPTIONS = {
     maxWords: 75,
     minWordLength: 1,
@@ -12,6 +13,7 @@ const DEFAULT_OPTIONS = {
     rotation: undefined,
     spiral: 'archimedean',
 };
+const INITIAL_WORD_SCALE = 0.2;
 const GROUPED_DATA_ERROR = 'WordCloudChart: grouped datasets are not supported; provide a flat array of rows instead';
 function createPreparedWords(data, plotArea, options, colors) {
     const counts = new Map();
@@ -61,6 +63,12 @@ export class WordCloudChart extends BaseChart {
             writable: true,
             value: void 0
         });
+        Object.defineProperty(this, "animation", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
         Object.defineProperty(this, "layout", {
             enumerable: true,
             configurable: true,
@@ -79,6 +87,24 @@ export class WordCloudChart extends BaseChart {
             writable: true,
             value: null
         });
+        Object.defineProperty(this, "hasRenderedLive", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: false
+        });
+        Object.defineProperty(this, "nextRenderShouldAnimate", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: false
+        });
+        Object.defineProperty(this, "previousWordSnapshot", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: new Map()
+        });
         const wordCloud = config.wordCloud ?? {};
         this.options = {
             maxWords: wordCloud.maxWords ?? DEFAULT_OPTIONS.maxWords,
@@ -90,8 +116,16 @@ export class WordCloudChart extends BaseChart {
             rotation: wordCloud.rotation,
             spiral: wordCloud.spiral ?? DEFAULT_OPTIONS.spiral,
         };
+        this.animation = normalizeRadialAnimationConfig(config.animate, 'WordCloudChart');
+        this.nextRenderShouldAnimate = this.animation.show;
         this.initializeDataState();
     }
+    update(data) {
+        if (this.container) {
+            this.prepareAnimationForUpdate();
+        }
+        super.update(data);
+    }
     destroy() {
         this.layoutRunId += 1;
         this.stopLayout();
@@ -120,8 +154,15 @@ export class WordCloudChart extends BaseChart {
             theme: this.theme,
             responsive: this.responsiveConfig,
             wordCloud: this.options,
+            animate: false,
         });
     }
+    prepareAnimationForUpdate() {
+        this.nextRenderShouldAnimate =
+            this.animation.show &&
+                this.animation.duration > 0 &&
+                this.hasRenderedLive;
+    }
     startLayout(words, plotArea, runId, resolve) {
         const layout = cloud()
             .words(words.map((word) => ({ ...word })))
@@ -146,8 +187,10 @@ export class WordCloudChart extends BaseChart {
             if (placedWords.length < words.length) {
                 console.warn(`[Chart Warning] WordCloudChart: rendered ${placedWords.length} of ${words.length} words within the available area; reduce maxWords or font sizes to fit more words`);
             }
-            this.renderWords(this.plotGroup, this.plotArea, placedWords);
-            this.finishReady(resolve);
+            const transitions = this.renderWords(this.plotGroup, this.plotArea, placedWords);
+            this.completeRender(placedWords, transitions).then(() => {
+                this.finishReady(resolve);
+            });
         });
         if (this.options.rotation === 'none') {
             layout.rotate(0);
@@ -170,27 +213,184 @@ export class WordCloudChart extends BaseChart {
             .attr('fill', 'transparent')
             .attr('stroke', 'none')
             .attr('pointer-events', 'none');
-        plotGroup
+        const cloudGroup = plotGroup
             .append('g')
             .attr('class', 'word-cloud')
-            .attr('transform', `translate(${plotArea.width / 2}, ${plotArea.height / 2})`)
-            .selectAll('text')
+            .attr('transform', `translate(${plotArea.width / 2}, ${plotArea.height / 2})`);
+        const wordGroupSelection = cloudGroup
+            .selectAll('g.word-cloud-word-wrapper')
             .data(words)
-            .join('text')
+            .join('g')
+            .attr('class', 'word-cloud-word-wrapper')
+            .attr('transform', (word) => this.createWordTransform(word));
+        const wordSelection = wordGroupSelection
+            .append('text')
             .attr('class', 'word-cloud-word')
             .attr('text-anchor', 'middle')
             .style('font-family', this.renderTheme.fontFamily)
             .style('font-weight', String(this.renderTheme.valueLabel.fontWeight))
             .style('font-size', (word) => `${word.size}px`)
             .style('fill', (word) => word.color)
-            .attr('transform', (word) => `translate(${word.x ?? 0}, ${word.y ?? 0}) rotate(${word.rotate ?? 0})`)
             .text((word) => word.text);
+        if (!this.shouldAnimateWords()) {
+            return [];
+        }
+        wordGroupSelection.attr('transform', (word) => this.createInitialWordTransform(word));
+        wordSelection.attr('transform', (word) => this.createInitialScaleTransform(word));
+        wordSelection.attr('opacity', (word) => String(this.createInitialWordOpacity(word)));
+        return [this.animateWords(wordGroupSelection, wordSelection)];
+    }
+    shouldAnimateWords() {
+        return (this.nextRenderShouldAnimate &&
+            this.animation.show &&
+            this.animation.duration > 0);
+    }
+    createInitialWordTransform(word) {
+        return this.createWordPositionTransform(this.createInitialWordTransformState(word));
+    }
+    createInitialWordTransformState(word) {
+        const previous = this.previousWordSnapshot.get(word.text);
+        if (previous) {
+            return {
+                x: previous.x,
+                y: previous.y,
+                rotate: previous.rotate,
+                scale: word.size > 0 ? previous.size / word.size : 1,
+            };
+        }
+        return {
+            x: word.x ?? 0,
+            y: word.y ?? 0,
+            rotate: word.rotate ?? 0,
+            scale: INITIAL_WORD_SCALE,
+        };
+    }
+    createWordTransform(word) {
+        return this.createWordPositionTransform({
+            x: word.x ?? 0,
+            y: word.y ?? 0,
+            rotate: word.rotate ?? 0,
+        });
+    }
+    createWordTransformState(word) {
+        return {
+            x: word.x ?? 0,
+            y: word.y ?? 0,
+            rotate: word.rotate ?? 0,
+            scale: 1,
+        };
+    }
+    createWordPositionTransform(state) {
+        return `translate(${state.x}, ${state.y}) rotate(${state.rotate})`;
+    }
+    createInitialScaleTransform(word) {
+        return this.createScaleTransform(this.createInitialWordTransformState(word).scale);
+    }
+    createScaleTransform(scale) {
+        return `scale(${scale})`;
+    }
+    createInitialWordOpacity(word) {
+        return this.previousWordSnapshot.has(word.text) ? 1 : 0;
+    }
+    animateWords(wordGroupSelection, wordSelection) {
+        const groupEntries = this.createWordGroupAnimationEntries(wordGroupSelection);
+        const textEntries = this.createWordTextAnimationEntries(wordSelection);
+        const startTime = this.now();
+        return new Promise((resolve) => {
+            const tick = (currentTime) => {
+                const progress = Math.min(1, (currentTime - startTime) / this.animation.duration);
+                const easedProgress = this.animation.easing(progress);
+                this.applyWordAnimationFrame(groupEntries, textEntries, easedProgress);
+                if (progress >= 1) {
+                    resolve();
+                    return;
+                }
+                this.requestAnimationFrame(tick);
+            };
+            this.requestAnimationFrame(tick);
+        });
+    }
+    createWordGroupAnimationEntries(wordGroupSelection) {
+        const entries = [];
+        wordGroupSelection.each((word, _index, nodes) => {
+            const node = nodes[_index];
+            entries.push({
+                node,
+                start: this.createInitialWordTransformState(word),
+                end: this.createWordTransformState(word),
+            });
+        });
+        return entries;
+    }
+    createWordTextAnimationEntries(wordSelection) {
+        const entries = [];
+        wordSelection.each((word, _index, nodes) => {
+            entries.push({
+                node: nodes[_index],
+                startScale: this.createInitialWordTransformState(word).scale,
+                startOpacity: this.createInitialWordOpacity(word),
+            });
+        });
+        return entries;
+    }
+    applyWordAnimationFrame(groupEntries, textEntries, progress) {
+        groupEntries.forEach((entry) => {
+            entry.node.setAttribute('transform', this.createWordPositionTransform({
+                x: entry.start.x + (entry.end.x - entry.start.x) * progress,
+                y: entry.start.y + (entry.end.y - entry.start.y) * progress,
+                rotate: entry.start.rotate +
+                    (entry.end.rotate - entry.start.rotate) * progress,
+            }));
+        });
+        textEntries.forEach((entry) => {
+            entry.node.setAttribute('opacity', String(entry.startOpacity + (1 - entry.startOpacity) * progress));
+            entry.node.setAttribute('transform', this.createScaleTransform(entry.startScale + (1 - entry.startScale) * progress));
+        });
+    }
+    requestAnimationFrame(callback) {
+        if (typeof requestAnimationFrame === 'function') {
+            requestAnimationFrame(callback);
+            return;
+        }
+        setTimeout(() => {
+            callback(this.now());
+        }, 16);
+    }
+    now() {
+        return typeof performance === 'undefined'
+            ? Date.now()
+            : performance.now();
+    }
+    completeRender(words, transitions) {
+        this.previousWordSnapshot = this.createWordSnapshot(words);
+        this.hasRenderedLive = true;
+        this.nextRenderShouldAnimate = false;
+        if (transitions.length === 0) {
+            return Promise.resolve();
+        }
+        return Promise.allSettled(transitions).then(() => undefined);
+    }
+    createWordSnapshot(words) {
+        return new Map(words.map((word) => {
+            return [
+                word.text,
+                {
+                    x: word.x ?? 0,
+                    y: word.y ?? 0,
+                    rotate: word.rotate ?? 0,
+                    size: word.size,
+                },
+            ];
+        }));
     }
     stopLayout() {
         if (this.layout) {
             this.layout.stop();
             this.layout = null;
         }
+        this.plotGroup
+            ?.selectAll('.word-cloud-word-wrapper, .word-cloud-word')
+            .interrupt();
         this.resolvePendingReady?.();
         this.resolvePendingReady = null;
     }

package/docs/components.md

@@ -400,7 +400,7 @@ breakpoints in chart constructor config (see
 - `svg`
 - `json`
 - `csv`
-- `xlsx` (lazy-loads optional `xlsx`)
+- `xlsx` (lazy-loads optional `write-excel-file`)
 - `png`
 - `jpg`
 - `pdf` (lazy-loads optional `jspdf`)

package/docs/getting-started.md

@@ -338,6 +338,7 @@ const data = [
 
 const chart = new WordCloudChart({
     data,
+    animate: true,
     wordCloud: {
         minWordLength: 3,
         minValue: 5,
@@ -357,6 +358,8 @@ chart.render('#word-cloud-container');
 dimension and define the relative size range passed into `d3-cloud`. Word
 clouds accept flat `{ word, count }` rows and use theme typography/colors
 directly when laying out and rendering the cloud.
+Set `animate: true` or pass an animation config to fade and scale words from
+their own centers on initial render and `chart.update(...)`.
 
 ## Next Steps
 

package/docs/word-cloud-chart.md

@@ -17,14 +17,15 @@ new WordCloudChart(config: WordCloudChartConfig)
 
 ## Config Options
 
-| Option       | Type                      | Default  | Description                                      |
-| ------------ | ------------------------- | -------- | ------------------------------------------------ |
-| `data`       | `DataItem[]`              | required | Flat `{ word, count }` rows                      |
-| `width`      | `number`                  | -        | Explicit chart width in pixels                   |
-| `height`     | `number`                  | -        | Explicit chart height in pixels                  |
-| `theme`      | `DeepPartial<ChartTheme>` | -        | Theme customization                              |
-| `responsive` | `ResponsiveConfig`        | -        | Declarative container-query responsive overrides |
-| `wordCloud`  | `WordCloudConfig`         | -        | Layout and filtering options                     |
+| Option       | Type                                   | Default  | Description                                             |
+| ------------ | -------------------------------------- | -------- | ------------------------------------------------------- |
+| `data`       | `DataItem[]`                           | required | Flat `{ word, count }` rows                             |
+| `width`      | `number`                               | -        | Explicit chart width in pixels                          |
+| `height`     | `number`                               | -        | Explicit chart height in pixels                         |
+| `theme`      | `DeepPartial<ChartTheme>`              | -        | Theme customization                                     |
+| `responsive` | `ResponsiveConfig`                     | -        | Declarative container-query responsive overrides        |
+| `wordCloud`  | `WordCloudConfig`                      | -        | Layout and filtering options                            |
+| `animate`    | `boolean \| WordCloudAnimationConfig`  | `false`  | Opt-in word animation for initial render and `update()` |
 
 ### `wordCloud`
 
@@ -41,6 +42,36 @@ wordCloud: {
 }
 ```
 
+### Animation
+
+```typescript
+animate: true
+```
+
+or:
+
+```typescript
+animate: {
+    duration?: number; // default: 700
+    easing?:
+        | 'linear'
+        | 'ease-in'
+        | 'ease-out'
+        | 'ease-in-out'
+        | 'bounce-out'
+        | 'elastic-out'
+        | 'spring-out'
+        | `linear(${string})`
+        | ((progress: number) => number);
+}
+```
+
+Animation is off by default. When enabled, words fade and scale from their own
+centers on the first render. On `chart.update(...)`, words that existed in the
+previous layout animate from their previous positions and scale from their own
+centers when their size changes. Use `chart.whenReady()` when surrounding UI or
+tests need to wait until layout and animation have finished.
+
 ## Example
 
 ```typescript
@@ -56,6 +87,10 @@ const data = [
 
 const chart = new WordCloudChart({
     data,
+    animate: {
+        duration: 700,
+        easing: 'ease-in-out',
+    },
     wordCloud: {
         minWordLength: 3,
         minValue: 10,

package/package.json

@@ -1,5 +1,5 @@
 {
-    "version": "0.14.0",
+    "version": "0.14.2",
     "name": "@internetstiftelsen/charts",
     "type": "module",
     "sideEffects": false,
@@ -39,7 +39,7 @@
     },
     "optionalDependencies": {
         "jspdf": "^4.2.1",
-        "xlsx": "^0.18.5"
+        "write-excel-file": "^4.0.7"
     },
     "devDependencies": {
         "@eslint/js": "^10.0.1",
@@ -57,30 +57,30 @@
         "@types/d3": "^7.4.3",
         "@types/d3-cloud": "^1.2.9",
         "@types/node": "^25.9.1",
-        "@types/react": "^19.2.15",
+        "@types/react": "^19.2.16",
         "@types/react-dom": "^19.2.3",
         "@vitejs/plugin-react-swc": "^4.3.1",
         "class-variance-authority": "^0.7.1",
         "clsx": "^2.1.1",
-        "eslint": "^10.4.0",
+        "eslint": "^10.4.1",
         "eslint-plugin-react-hooks": "^7.1.1",
         "eslint-plugin-react-refresh": "^0.5.2",
         "globals": "^17.6.0",
         "handsontable": "^17.1.0",
         "jsdom": "^29.1.1",
-        "lucide-react": "^1.16.0",
+        "lucide-react": "^1.17.0",
         "prettier": "3.8.3",
         "radix-ui": "^1.4.3",
-        "react": "^19.2.6",
-        "react-dom": "^19.2.6",
+        "react": "^19.2.7",
+        "react-dom": "^19.2.7",
         "sass": "^1.100.0",
         "tailwind-merge": "^3.6.0",
         "tailwindcss": "^4.3.0",
         "tsc-alias": "^1.8.17",
         "tw-animate-css": "^1.4.0",
         "typescript": "~6.0.3",
-        "typescript-eslint": "^8.59.4",
-        "vite": "^8.0.14",
-        "vitest": "^4.1.7"
+        "typescript-eslint": "^8.60.1",
+        "vite": "^8.0.16",
+        "vitest": "^4.1.8"
     }
 }