@internetstiftelsen/charts 0.13.3 → 0.14.0

package/dist/radial-chart-base.js

@@ -1,7 +1,9 @@
 import { BaseChart } from './base-chart.js';
 import { DEFAULT_CHART_HEIGHT } from './theme.js';
+import { measureTextWidth, truncateText, wrapText } from './utils.js';
 const TOOLTIP_OFFSET_PX = 12;
 const EDGE_MARGIN_PX = 10;
+const DEFAULT_LABEL_FONT_SIZE = 14;
 export class RadialChartBase extends BaseChart {
     initializeTooltip() {
         this.tooltip?.initialize(this.renderTheme);
@@ -27,6 +29,119 @@ export class RadialChartBase extends BaseChart {
             fill: item.color,
         }));
     }
+    renderRadialLabelText(textElement, text, options, verticalAnchor = 'middle') {
+        const layout = this.resolveRadialLabelLayout(text, options);
+        textElement.text(null).style('visibility', null);
+        if (layout.hidden) {
+            textElement.text(text).style('visibility', 'hidden');
+            return;
+        }
+        if (layout.lines.length === 1) {
+            textElement.text(layout.lines[0]);
+            this.addRadialLabelTitle(textElement, layout.titleText);
+            return;
+        }
+        const lineHeight = this.resolveRadialLabelLineHeight(options.fontSize);
+        const startDy = verticalAnchor === 'middle'
+            ? -((layout.lines.length - 1) * lineHeight) / 2
+            : 0;
+        const x = textElement.attr('x') ?? '0';
+        layout.lines.forEach((line, index) => {
+            textElement
+                .append('tspan')
+                .attr('x', x)
+                .attr('dy', index === 0 ? `${startDy}px` : `${lineHeight}px`)
+                .text(line);
+        });
+        this.addRadialLabelTitle(textElement, layout.titleText);
+    }
+    renderRadialStructuredLabelText(textElement, labelText, valueText, separator, options, verticalAnchor = 'middle') {
+        const layout = this.resolveRadialLabelLayout(labelText, options);
+        const fullText = `${labelText}${separator}${valueText}`;
+        textElement.text(null).style('visibility', null);
+        if (layout.hidden) {
+            textElement.text(fullText).style('visibility', 'hidden');
+            return;
+        }
+        if (layout.lines.length === 1) {
+            textElement.text(`${layout.lines[0]}${separator}${valueText}`);
+            this.addRadialLabelTitle(textElement, layout.titleText ? fullText : null);
+            return;
+        }
+        const lineHeight = this.resolveRadialLabelLineHeight(options.fontSize);
+        const startDy = verticalAnchor === 'middle'
+            ? -((layout.lines.length - 1) * lineHeight) / 2
+            : 0;
+        const x = textElement.attr('x') ?? '0';
+        const lastLineIndex = layout.lines.length - 1;
+        layout.lines.forEach((line, index) => {
+            const renderedLine = index === lastLineIndex
+                ? `${line}${separator}${valueText}`
+                : line;
+            textElement
+                .append('tspan')
+                .attr('x', x)
+                .attr('dy', index === 0 ? `${startDy}px` : `${lineHeight}px`)
+                .text(renderedLine);
+        });
+        this.addRadialLabelTitle(textElement, layout.titleText ? fullText : null);
+    }
+    measureRadialLabelDimensions(text, options) {
+        const layout = this.resolveRadialLabelLayout(text, options);
+        if (layout.hidden) {
+            return {
+                width: 0,
+                height: 0,
+            };
+        }
+        const svgNode = this.svg?.node();
+        const fontWeight = String(options.fontWeight);
+        const width = svgNode
+            ? layout.lines.reduce((maxWidth, line) => {
+                return Math.max(maxWidth, measureTextWidth(line, options.fontSize, options.fontFamily, fontWeight, svgNode));
+            }, 0)
+            : (options.maxLabelWidth ?? 0);
+        return {
+            width,
+            height: Math.max(layout.lines.length, 1) *
+                this.resolveRadialLabelLineHeight(options.fontSize),
+        };
+    }
+    measureRadialStructuredLabelDimensions(labelText, valueText, separator, options) {
+        const layout = this.resolveRadialLabelLayout(labelText, options);
+        if (layout.hidden) {
+            return {
+                width: 0,
+                height: 0,
+            };
+        }
+        const svgNode = this.svg?.node();
+        const fontWeight = String(options.fontWeight);
+        const lastLineIndex = layout.lines.length - 1;
+        const width = svgNode
+            ? layout.lines.reduce((maxWidth, line, index) => {
+                const renderedLine = index === lastLineIndex
+                    ? `${line}${separator}${valueText}`
+                    : line;
+                return Math.max(maxWidth, measureTextWidth(renderedLine, options.fontSize, options.fontFamily, fontWeight, svgNode));
+            }, 0)
+            : (options.maxLabelWidth ?? 0);
+        return {
+            width,
+            height: Math.max(layout.lines.length, 1) *
+                this.resolveRadialLabelLineHeight(options.fontSize),
+        };
+    }
+    resolveRadialLabelLineHeight(fontSize) {
+        if (typeof fontSize === 'number' && Number.isFinite(fontSize)) {
+            return fontSize * 1.2;
+        }
+        const parsedFontSize = Number.parseFloat(String(fontSize));
+        if (Number.isFinite(parsedFontSize)) {
+            return parsedFontSize * 1.2;
+        }
+        return DEFAULT_LABEL_FONT_SIZE * 1.2;
+    }
     showTooltipFromPointer(event, content) {
         if (!this.tooltip) {
             return;
@@ -84,6 +199,72 @@ export class RadialChartBase extends BaseChart {
         const y = Math.max(EDGE_MARGIN_PX, Math.min(rawY, window.innerHeight + window.scrollY - height - EDGE_MARGIN_PX));
         this.tooltip?.showAt(x, y);
     }
+    resolveRadialLabelLayout(text, options) {
+        const overflowContext = this.resolveRadialLabelOverflowContext(options.maxLabelWidth);
+        if (!overflowContext) {
+            return this.createVisibleRadialLabelLayout(text);
+        }
+        const { maxLabelWidth, svgNode } = overflowContext;
+        const fontWeight = String(options.fontWeight);
+        const textWidth = measureTextWidth(text, options.fontSize, options.fontFamily, fontWeight, svgNode);
+        if (textWidth <= maxLabelWidth) {
+            return this.createVisibleRadialLabelLayout(text);
+        }
+        return this.resolveOverflowingRadialLabelLayout(text, options, maxLabelWidth, fontWeight, svgNode);
+    }
+    resolveRadialLabelOverflowContext(maxLabelWidth) {
+        const svgNode = this.svg?.node();
+        if (maxLabelWidth === undefined ||
+            !Number.isFinite(maxLabelWidth) ||
+            maxLabelWidth <= 0 ||
+            !svgNode) {
+            return null;
+        }
+        return { maxLabelWidth, svgNode };
+    }
+    createVisibleRadialLabelLayout(text) {
+        return {
+            lines: [text],
+            hidden: false,
+            titleText: null,
+        };
+    }
+    resolveOverflowingRadialLabelLayout(text, options, maxLabelWidth, fontWeight, svgNode) {
+        if (options.oversizedBehavior === 'hide') {
+            if (options.forceVisible) {
+                return {
+                    lines: [text],
+                    hidden: false,
+                    titleText: null,
+                };
+            }
+            return {
+                lines: [text],
+                hidden: true,
+                titleText: null,
+            };
+        }
+        if (options.oversizedBehavior === 'wrap') {
+            const lines = wrapText(text, maxLabelWidth, options.fontSize, options.fontFamily, fontWeight, svgNode);
+            return {
+                lines,
+                hidden: false,
+                titleText: lines.length > 1 ? text : null,
+            };
+        }
+        const result = truncateText(text, maxLabelWidth, options.fontSize, options.fontFamily, fontWeight, svgNode);
+        return {
+            lines: [result.text],
+            hidden: false,
+            titleText: result.truncated ? text : null,
+        };
+    }
+    addRadialLabelTitle(textElement, text) {
+        if (!text) {
+            return;
+        }
+        textElement.append('title').text(text);
+    }
     resolveRadialFontScale(outerRadius, theme) {
         const referenceHeight = this.configuredHeight ?? DEFAULT_CHART_HEIGHT;
         const plotHeight = Math.max(1, referenceHeight - theme.margins.top - theme.margins.bottom);

package/dist/scatter.js

@@ -183,6 +183,7 @@ export class Scatter {
         const border = config.border ?? theme.valueLabel.border;
         const borderRadius = config.borderRadius ?? theme.valueLabel.borderRadius;
         const padding = config.padding ?? theme.valueLabel.padding;
+        const forceVisible = config.forceVisible === true;
         const labelGroup = plotGroup
             .append('g')
             .attr('class', `scatter-value-labels-${sanitizeForCSS(this.dataKey)}`);
@@ -211,7 +212,7 @@ export class Scatter {
             if (labelY - boxHeight / 2 < plotTop + 4) {
                 labelY = yPos + boxHeight / 2 + pointSize + 4;
                 if (labelY + boxHeight / 2 > plotBottom - 4) {
-                    shouldRender = false;
+                    shouldRender = forceVisible;
                 }
             }
             tempText.remove();

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/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',
     },
 });
 

package/docs/gauge-chart.md

@@ -40,6 +40,7 @@ gauge: {
             | 'ease-in-out'
             | 'bounce-out'
             | 'elastic-out'
+            | 'spring-out'
             | `linear(...)`   // CSS-like piecewise linear easing
             | ((t: number) => number),
     },
@@ -60,6 +61,9 @@ gauge: {
         fontFamily?: string,         // default: theme.axis.fontFamily
         fontWeight?: number | string, // default: 700
         color?: string,              // default: #111827
+        maxLabelWidth?: number,
+        oversizedBehavior?: 'truncate' | 'wrap' | 'hide', // default: 'truncate'
+        forceVisible?: boolean,      // default: false
     },
     needle?: boolean | {
         show?: boolean,       // default: true
@@ -86,6 +90,9 @@ gauge: {
             fontFamily?: string,         // default: theme.axis.fontFamily
             fontWeight?: number | string, // default: theme.axis.fontWeight
             color?: string,              // default: #4b5563
+            maxLabelWidth?: number,
+            oversizedBehavior?: 'truncate' | 'wrap' | 'hide', // default: 'truncate'
+            forceVisible?: boolean,      // default: false
         },
     },
     segments?: [
@@ -99,6 +106,11 @@ gauge: {
 }
 ```
 
+Set `maxLabelWidth` on `valueLabelStyle` or `ticks.labelStyle` to cap rendered
+label width. `oversizedBehavior` controls whether labels over that cap are
+truncated, wrapped, or hidden. Set `forceVisible: true` to keep labels rendered
+when `oversizedBehavior: 'hide'` would normally hide them.
+
 ## Example
 
 ```javascript
@@ -151,6 +163,8 @@ chart.render('#gauge-container');
 
 ## Animation Easing Example
 
+`spring-out` is a duration-based cubic-bezier preset.
+
 ```typescript
 const chart = new GaugeChart({
     data: [{ value: 72 }],

package/docs/pie-chart.md

@@ -10,17 +10,18 @@ new PieChart(config: PieChartConfig)
 
 ### 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                                        |
-| `pie`        | `PieConfig`               | -         | Pie-specific configuration                                            |
-| `valueLabel` | `PieValueLabelConfig`     | -         | On-chart slice 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                                        |
+| `pie`        | `PieConfig`                     | -         | Pie-specific configuration                                            |
+| `valueLabel` | `PieValueLabelConfig`           | -         | On-chart slice label/value rendering configuration                    |
+| `animate`    | `boolean \| PieAnimationConfig` | `false`   | Opt-in slice animation for initial render and `update()`              |
+| `theme`      | `DeepPartial<ChartTheme>`       | -         | Theme customization                                                   |
+| `responsive` | `ResponsiveConfig`              | -         | Declarative container-query responsive overrides (theme + components) |
 
 ### Pie Config
 
@@ -45,11 +46,46 @@ valueLabel: {
     outsideOffset?: number,         // default: 16
     insideMargin?: number,          // default: 8
     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,
 }
 ```
 
-Rendered pie value-label text defaults to `{label}: {value}` and can be customized with `valueLabel.formatter`. The `percentage` argument is the computed slice share from `0` to `100`.
+Rendered pie value-label text defaults to `{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 slice 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 inside-fit checks or
+`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, slices 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
 
@@ -76,8 +112,13 @@ const chart = new PieChart({
     valueLabel: {
         show: true,
         position: 'auto',
-        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',
     },
 });
 
@@ -102,7 +143,8 @@ are negative, the chart throws an error because there is nothing to render.
 
 When `valueLabel.position` is `inside`, the formatted value-label text that does not
 fit inside its slice is hidden. In `auto` mode, labels that are too tight (based on
-`insideMargin`) move outside instead.
+`insideMargin`) move outside instead. Set `valueLabel.forceVisible: true` to
+keep inside labels rendered even when they do not fit.
 
 ## Supported Components