@internetstiftelsen/charts 0.13.3 → 0.14.1

package/dist/theme.d.ts

@@ -1,11 +1,26 @@
 import { type ChartTheme, type ResponsiveConfig } from './types.js';
+export declare const RUBY_COLOR_PALETTE: string[];
+export declare const PEACOCK_COLOR_PALETTE: string[];
+export declare const JADE_COLOR_PALETTE: string[];
+export declare const LEMON_COLOR_PALETTE: string[];
+export declare const OCEAN_COLOR_PALETTE: string[];
 export declare const DEFAULT_COLOR_PALETTE: string[];
 export declare const DEFAULT_CHART_WIDTH = 928;
 export declare const DEFAULT_CHART_HEIGHT = 600;
 export declare const defaultTheme: ChartTheme;
+export declare const rubyTheme: ChartTheme;
+export declare const peacockTheme: ChartTheme;
+export declare const jadeTheme: ChartTheme;
+export declare const lemonTheme: ChartTheme;
+export declare const oceanTheme: ChartTheme;
 export declare const newspaperTheme: ChartTheme;
 export declare const defaultResponsiveConfig: ResponsiveConfig;
 export declare const themes: {
     default: ChartTheme;
+    ruby: ChartTheme;
+    peacock: ChartTheme;
+    jade: ChartTheme;
+    lemon: ChartTheme;
+    ocean: ChartTheme;
     newspaper: ChartTheme;
 };

package/dist/theme.js

@@ -1,3 +1,39 @@
+const SYSTEM_FONT = '-apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial, sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol"';
+export const RUBY_COLOR_PALETTE = [
+    '#ff4069',
+    '#c51f46',
+    '#ff7f99',
+    '#ffb3c2',
+    '#7f102d',
+];
+export const PEACOCK_COLOR_PALETTE = [
+    '#c27fec',
+    '#934bc5',
+    '#d5a4f3',
+    '#ead2fa',
+    '#5f287f',
+];
+export const JADE_COLOR_PALETTE = [
+    '#55c7b4',
+    '#2f8f80',
+    '#88dacd',
+    '#c4eee8',
+    '#1b5f55',
+];
+export const LEMON_COLOR_PALETTE = [
+    '#ffce2e',
+    '#c89200',
+    '#ffe07a',
+    '#fff0b8',
+    '#7a5900',
+];
+export const OCEAN_COLOR_PALETTE = [
+    '#50b2fc',
+    '#147eca',
+    '#8bcbfd',
+    '#c6e6fe',
+    '#0f4f7f',
+];
 export const DEFAULT_COLOR_PALETTE = [
     '#50b2fc', // ocean
     '#ff4069', // ruby
@@ -11,7 +47,7 @@ export const DEFAULT_COLOR_PALETTE = [
 export const DEFAULT_CHART_WIDTH = 928;
 export const DEFAULT_CHART_HEIGHT = 600;
 export const defaultTheme = {
-    fontFamily: '-apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial, sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol"',
+    fontFamily: SYSTEM_FONT,
     margins: {
         top: 20,
         right: 20,
@@ -24,7 +60,7 @@ export const defaultTheme = {
     },
     colorPalette: [...DEFAULT_COLOR_PALETTE],
     axis: {
-        fontFamily: '-apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial, sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol"',
+        fontFamily: SYSTEM_FONT,
         fontSize: 14,
         fontWeight: 'normal',
         groupLabel: {
@@ -72,7 +108,7 @@ export const defaultTheme = {
         background: '#ffffff',
         border: '#dddddd',
         color: '#1f2a36',
-        fontFamily: '-apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial, sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol"',
+        fontFamily: SYSTEM_FONT,
         fontSize: 12,
         fontWeight: 'normal',
     },
@@ -86,7 +122,7 @@ export const defaultTheme = {
     },
     valueLabel: {
         fontSize: 12,
-        fontFamily: '-apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial, sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol"',
+        fontFamily: SYSTEM_FONT,
         fontWeight: '600',
         color: '#1f2a36',
         background: '#ffffff',
@@ -117,6 +153,51 @@ export const defaultTheme = {
         },
     },
 };
+function cloneTheme(theme) {
+    return {
+        ...theme,
+        margins: { ...theme.margins },
+        grid: { ...theme.grid },
+        colorPalette: [...theme.colorPalette],
+        axis: {
+            ...theme.axis,
+            groupLabel: theme.axis.groupLabel
+                ? { ...theme.axis.groupLabel }
+                : undefined,
+        },
+        legend: { ...theme.legend },
+        text: {
+            variants: Object.fromEntries(Object.entries(theme.text.variants).map(([name, style]) => [
+                name,
+                { ...style },
+            ])),
+        },
+        tooltip: { ...theme.tooltip },
+        line: {
+            ...theme.line,
+            point: { ...theme.line.point },
+        },
+        valueLabel: { ...theme.valueLabel },
+        donut: {
+            ...theme.donut,
+            centerContent: {
+                mainValue: { ...theme.donut.centerContent.mainValue },
+                title: { ...theme.donut.centerContent.title },
+                subtitle: { ...theme.donut.centerContent.subtitle },
+            },
+        },
+    };
+}
+function createAccentTheme(colorPalette) {
+    const theme = cloneTheme(defaultTheme);
+    theme.colorPalette = [...colorPalette];
+    return theme;
+}
+export const rubyTheme = createAccentTheme(RUBY_COLOR_PALETTE);
+export const peacockTheme = createAccentTheme(PEACOCK_COLOR_PALETTE);
+export const jadeTheme = createAccentTheme(JADE_COLOR_PALETTE);
+export const lemonTheme = createAccentTheme(LEMON_COLOR_PALETTE);
+export const oceanTheme = createAccentTheme(OCEAN_COLOR_PALETTE);
 export const newspaperTheme = {
     fontFamily: 'Georgia, "Times New Roman", Times, serif',
     margins: {
@@ -261,5 +342,10 @@ export const defaultResponsiveConfig = {
 };
 export const themes = {
     default: defaultTheme,
+    ruby: rubyTheme,
+    peacock: peacockTheme,
+    jade: jadeTheme,
+    lemon: lemonTheme,
+    ocean: oceanTheme,
     newspaper: newspaperTheme,
 };

package/dist/types.d.ts

@@ -180,6 +180,7 @@ export type ValueLabelConfig = {
     borderRadius?: number;
     padding?: number;
     formatter?: SeriesValueFormatter;
+    forceVisible?: boolean;
 };
 export type LineValueLabelConfig = ValueLabelConfig & {
     show?: boolean;

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/dist/xy-motion/config.js

@@ -1,8 +1,10 @@
 import { ChartValidationError, ChartValidator } from '../validation.js';
 import { easeBounceOut, easeCubicIn, easeCubicInOut, easeCubicOut, easeElasticOut, easeLinear, } from 'd3';
+import { createCubicBezierEasing } from '../easing.js';
 const DEFAULT_ANIMATE = false;
 const DEFAULT_ANIMATION_DURATION_MS = 700;
 const DEFAULT_ANIMATION_EASING_PRESET = 'ease-in-out';
+const easeSpringOut = createCubicBezierEasing(0.85, 0, 0.15, 1);
 const XY_ANIMATION_EASING_PRESETS = {
     linear: easeLinear,
     'ease-in': easeCubicIn,
@@ -10,6 +12,7 @@ const XY_ANIMATION_EASING_PRESETS = {
     'ease-in-out': easeCubicInOut,
     'bounce-out': easeBounceOut,
     'elastic-out': easeElasticOut,
+    'spring-out': easeSpringOut,
 };
 export function normalizeXYAnimationConfig(config) {
     if (config === undefined) {

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

@@ -1,5 +1,5 @@
 import type { Selection } from 'd3';
-export type XYAnimationEasingPreset = 'linear' | 'ease-in' | 'ease-out' | 'ease-in-out' | 'bounce-out' | 'elastic-out';
+export type XYAnimationEasingPreset = 'linear' | 'ease-in' | 'ease-out' | 'ease-in-out' | 'bounce-out' | 'elastic-out' | 'spring-out';
 export type XYAnimationConfig = {
     show?: boolean;
     duration?: number;

package/docs/donut-chart.md

@@ -10,17 +10,18 @@ new DonutChart(config: DonutChartConfig)
 
 ### Config Options
 
-| Option       | Type                      | Default   | Description                                                           |
-| ------------ | ------------------------- | --------- | --------------------------------------------------------------------- |
-| `data`       | `DataItem[]`              | required  | Array of data objects                                                 |
-| `width`      | `number`                  | -         | Explicit chart width in pixels                                        |
-| `height`     | `number`                  | -         | Explicit chart height in pixels                                       |
-| `valueKey`   | `string`                  | `'value'` | Key for numeric values in data                                        |
-| `labelKey`   | `string`                  | `'name'`  | Key for segment labels in data                                        |
-| `donut`      | `DonutConfig`             | -         | Donut-specific configuration                                          |
-| `valueLabel` | `DonutValueLabelConfig`   | -         | On-chart outside label/value rendering configuration                  |
-| `theme`      | `DeepPartial<ChartTheme>` | -         | Theme customization                                                   |
-| `responsive` | `ResponsiveConfig`        | -         | Declarative container-query responsive overrides (theme + components) |
+| Option       | Type                              | Default   | Description                                                           |
+| ------------ | --------------------------------- | --------- | --------------------------------------------------------------------- |
+| `data`       | `DataItem[]`                      | required  | Array of data objects                                                 |
+| `width`      | `number`                          | -         | Explicit chart width in pixels                                        |
+| `height`     | `number`                          | -         | Explicit chart height in pixels                                       |
+| `valueKey`   | `string`                          | `'value'` | Key for numeric values in data                                        |
+| `labelKey`   | `string`                          | `'name'`  | Key for segment labels in data                                        |
+| `donut`      | `DonutConfig`                     | -         | Donut-specific configuration                                          |
+| `valueLabel` | `DonutValueLabelConfig`           | -         | On-chart outside label/value rendering configuration                  |
+| `animate`    | `boolean \| DonutAnimationConfig` | `false`   | Opt-in segment animation for initial render and `update()`            |
+| `theme`      | `DeepPartial<ChartTheme>`         | -         | Theme customization                                                   |
+| `responsive` | `ResponsiveConfig`                | -         | Declarative container-query responsive overrides (theme + components) |
 
 ### Donut Config
 
@@ -40,13 +41,50 @@ valueLabel: {
     position?: 'outside' | 'auto', // default: 'auto'
     outsideOffset?: number,        // default: 16
     minVerticalSpacing?: number,   // default: 14
-    formatter?: (label, value, data, percentage) => string, // default: `${label}: ${value}`
+    maxLabelWidth?: number,
+    oversizedBehavior?: 'truncate' | 'wrap' | 'hide', // default: 'truncate'
+    forceVisible?: boolean,        // default: false
+    labelFormatter?: (label, value, data, percentage) => string,
+    valueFormatter?: (label, value, data, percentage) => string,
+    separator?: string,            // default: ': '
+    formatter?: (label, value, data, percentage) => string,
 }
 ```
 
 Donut value labels are rendered outside the ring with leader lines. `auto`
 currently resolves to the same outside placement as `outside`.
 
+By default, donut value labels render as `{label}: {value}`. Use
+`labelFormatter`, `valueFormatter`, and `separator` to customize those parts
+while keeping the label and value structurally separate. When `maxLabelWidth` is
+set, `oversizedBehavior` applies to the label part only, so long labels can be
+truncated, wrapped, or hidden without truncating the value. The `percentage`
+argument is the computed segment share from `0` to `100`.
+
+Use `formatter` for full custom label text. When `formatter` is provided, the
+returned string is treated as a single label and overflow behavior applies to
+that whole string.
+
+Set `forceVisible: true` to keep value labels rendered when
+`oversizedBehavior: 'hide'` would normally hide them.
+
+### Animation Config
+
+```typescript
+animate: boolean | {
+    show?: boolean,        // default: true when object is provided
+    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, segments grow from zero length on the
+first render and animate from their previous geometry on `chart.update(...)` and
+legend visibility changes. Use `chart.whenReady()` when surrounding UI or tests
+need to wait until the current animation has finished.
+
 ## Example
 
 ```javascript
@@ -73,8 +111,13 @@ const chart = new DonutChart({
     },
     valueLabel: {
         show: true,
-        formatter: (label, _value, _data, percentage) =>
-            `${label}: ${percentage.toFixed(1)}%`,
+        formatter: (label, _value, _data, percentage) => {
+            return `${label}: ${percentage.toFixed(1)}%`;
+        },
+    },
+    animate: {
+        duration: 700,
+        easing: 'ease-in-out',
     },
 });