@internetstiftelsen/charts 0.10.0 → 0.11.0

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

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

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

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

package/dist/y-axis.d.ts

@@ -5,12 +5,14 @@ export declare class YAxis implements LayoutAwareComponent<YAxisConfigBase> {
     readonly type: "yAxis";
     readonly display: boolean;
     private readonly tickPadding;
-    private readonly fontSize;
-    private readonly maxLabelWidth;
+    private fontSize;
+    private readonly maxLabelWidth?;
     private readonly tickFormat;
     private readonly rotatedLabels;
     private readonly oversizedBehavior;
+    private estimatedWidth;
     readonly exportHooks?: ExportHooks<YAxisConfigBase>;
+    private resolveFontSizeValue;
     constructor(config?: YAxisConfig);
     getExportConfig(): YAxisConfigBase;
     createExportComponent(override?: Partial<YAxisConfigBase>): LayoutAwareComponent<YAxisConfigBase>;
@@ -18,8 +20,11 @@ export declare class YAxis implements LayoutAwareComponent<YAxisConfigBase> {
      * Returns the space required by the y-axis
      */
     getRequiredSpace(): ComponentSpace;
+    estimateLayoutSpace(labels: unknown[], theme: ChartTheme, svg: SVGSVGElement): void;
+    clearEstimatedSpace(): void;
     render(svg: Selection<SVGSVGElement, undefined, null, undefined>, y: D3Scale, theme: ChartTheme, xPosition: number): void;
     private applyLabelConstraints;
+    private measureLabelDimensions;
     private wrapTextElement;
     private addTitleTooltip;
 }

package/dist/y-axis.js

@@ -1,6 +1,18 @@
 import { axisLeft } from 'd3';
 import { measureTextWidth, truncateText, wrapText, mergeDeep } from './utils.js';
 export class YAxis {
+    resolveFontSizeValue(fontSize, fallback) {
+        if (typeof fontSize === 'number' && Number.isFinite(fontSize)) {
+            return fontSize;
+        }
+        if (typeof fontSize === 'string') {
+            const parsedFontSize = parseFloat(fontSize);
+            if (Number.isFinite(parsedFontSize)) {
+                return parsedFontSize;
+            }
+        }
+        return fallback;
+    }
     constructor(config) {
         Object.defineProperty(this, "type", {
             enumerable: true,
@@ -50,18 +62,25 @@ export class YAxis {
             writable: true,
             value: void 0
         });
+        Object.defineProperty(this, "estimatedWidth", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: null
+        });
         Object.defineProperty(this, "exportHooks", {
             enumerable: true,
             configurable: true,
             writable: true,
             value: void 0
         });
-        this.display = config?.display ?? true;
-        this.tickFormat = config?.tickFormat ?? null;
-        this.rotatedLabels = config?.rotatedLabels ?? false;
-        this.maxLabelWidth = config?.maxLabelWidth ?? 40; // Default 40 for backward compatibility
-        this.oversizedBehavior = config?.oversizedBehavior ?? 'truncate';
-        this.exportHooks = config?.exportHooks;
+        const { display = true, tickFormat = null, rotatedLabels = false, maxLabelWidth, oversizedBehavior = 'truncate', exportHooks, } = config ?? {};
+        this.display = display;
+        this.tickFormat = tickFormat;
+        this.rotatedLabels = rotatedLabels;
+        this.maxLabelWidth = maxLabelWidth;
+        this.oversizedBehavior = oversizedBehavior;
+        this.exportHooks = exportHooks;
     }
     getExportConfig() {
         return {
@@ -90,20 +109,54 @@ export class YAxis {
                 position: 'left',
             };
         }
-        // Width = max label width + tick padding
-        // Rotated labels need less width (cos(45°) ≈ 0.7 of horizontal width)
-        const baseWidth = this.maxLabelWidth + this.tickPadding;
-        const width = this.rotatedLabels ? baseWidth * 0.7 : baseWidth;
+        if (this.estimatedWidth !== null) {
+            return {
+                width: this.estimatedWidth,
+                height: 0,
+                position: 'left',
+            };
+        }
+        const fallbackLabelWidth = this.maxLabelWidth ?? this.fontSize;
+        const width = fallbackLabelWidth + this.tickPadding;
         return {
             width,
             height: 0, // Y-axis spans full height
             position: 'left',
         };
     }
+    estimateLayoutSpace(labels, theme, svg) {
+        if (!labels.length) {
+            this.estimatedWidth = 0;
+            return;
+        }
+        this.fontSize = this.resolveFontSizeValue(theme.axis.fontSize, this.fontSize);
+        const fontSize = this.fontSize;
+        const fontFamily = theme.axis.fontFamily;
+        const fontWeight = theme.axis.fontWeight || 'normal';
+        let maxWidth = 0;
+        let maxHeight = 0;
+        for (const label of labels) {
+            const text = String(label ?? '');
+            if (!text)
+                continue;
+            const { width, height } = this.measureLabelDimensions(text, fontSize, fontFamily, fontWeight, svg);
+            maxWidth = Math.max(maxWidth, width);
+            maxHeight = Math.max(maxHeight, height);
+        }
+        const radians = Math.PI / 4;
+        const labelFootprint = this.rotatedLabels
+            ? Math.cos(radians) * maxWidth + Math.sin(radians) * maxHeight
+            : maxWidth;
+        this.estimatedWidth = this.tickPadding + labelFootprint;
+    }
+    clearEstimatedSpace() {
+        this.estimatedWidth = null;
+    }
     render(svg, y, theme, xPosition) {
         if (!this.display) {
             return;
         }
+        this.fontSize = this.resolveFontSizeValue(theme.axis.fontSize, this.fontSize);
         const axis = axisLeft(y).tickSize(0).tickPadding(this.tickPadding);
         // Apply tick formatting if specified
         if (this.tickFormat) {
@@ -138,6 +191,9 @@ export class YAxis {
         axisGroup.selectAll('.domain').remove();
     }
     applyLabelConstraints(axisGroup, svg, fontSize, fontFamily, fontWeight) {
+        if (this.maxLabelWidth === undefined) {
+            return;
+        }
         const maxWidth = this.maxLabelWidth;
         const behavior = this.oversizedBehavior;
         axisGroup
@@ -170,6 +226,39 @@ export class YAxis {
             }
         });
     }
+    measureLabelDimensions(text, fontSize, fontFamily, fontWeight, svg) {
+        const textWidth = measureTextWidth(text, fontSize, fontFamily, fontWeight, svg);
+        const lineHeight = fontSize * 1.2;
+        if (this.maxLabelWidth === undefined ||
+            textWidth <= this.maxLabelWidth) {
+            return {
+                width: textWidth,
+                height: fontSize,
+            };
+        }
+        switch (this.oversizedBehavior) {
+            case 'truncate':
+                return {
+                    width: this.maxLabelWidth,
+                    height: fontSize,
+                };
+            case 'wrap': {
+                const lines = wrapText(text, this.maxLabelWidth, fontSize, fontFamily, fontWeight, svg);
+                const widestLine = lines.reduce((widest, line) => {
+                    return Math.max(widest, measureTextWidth(line, fontSize, fontFamily, fontWeight, svg));
+                }, 0);
+                return {
+                    width: widestLine,
+                    height: Math.max(lines.length, 1) * lineHeight,
+                };
+            }
+            case 'hide':
+                return {
+                    width: 0,
+                    height: 0,
+                };
+        }
+    }
     wrapTextElement(textEl, lines, originalText) {
         // Clear existing content
         textEl.textContent = '';

package/docs/components.md

@@ -8,12 +8,18 @@ Renders the X axis.
 
 ```typescript
 new XAxis({
-    display?: boolean,       // Render axis and reserve layout space (default: true)
+    display?: boolean,        // Render axis and reserve layout space (default: true)
     dataKey?: string,         // Key in data objects for X values (auto-detected if omitted)
     labelKey?: string,        // Optional display label key (uses dataKey values if omitted)
     groupLabelKey?: string,   // Optional key used for second-row grouped labels
     showGroupLabels?: boolean, // Show second-row grouped labels (default: false)
     groupLabelGap?: number,   // Vertical gap between tick row and grouped row
+    rotatedLabels?: boolean,  // Rotate tick labels -45deg
+    maxLabelWidth?: number,   // Optional cap for tick-label width
+    oversizedBehavior?: 'truncate' | 'wrap' | 'hide', // Only applies when maxLabelWidth is set
+    autoHideOverlapping?: boolean, // Automatically hide overlapping labels
+    minLabelGap?: number,     // Minimum gap between visible labels when auto-hide is enabled
+    preserveEndLabels?: boolean, // Keep first/last labels visible when auto-hide is enabled
     tickFormat?: string | ((value: string | number | Date) => string) | null
 })
 ```
@@ -54,10 +60,17 @@ Renders the Y axis.
 ```typescript
 new YAxis({
     display?: boolean,          // Render axis and reserve layout space (default: true)
+    rotatedLabels?: boolean,    // Rotate tick labels -45deg
+    maxLabelWidth?: number,     // Optional cap for tick-label width
+    oversizedBehavior?: 'truncate' | 'wrap' | 'hide', // Only applies when maxLabelWidth is set
     tickFormat?: string | ((value: string | number | Date) => string) | null
 })
 ```
 
+When `maxLabelWidth` is omitted, `YAxis` reserves the measured width of its
+rendered tick labels. Set `maxLabelWidth` to cap the reserved width and use
+`oversizedBehavior` to control truncation, wrapping, or hiding.
+
 ### Format Examples
 
 ```javascript
@@ -106,6 +119,14 @@ Renders interactive tooltips on hover and keyboard focus.
 
 ```typescript
 new Tooltip({
+    mode?: 'shared' | 'split',
+    position?: 'side' | 'vertical',
+    barAnchorPosition?: 'top' | 'middle',
+    transition?: {
+        show?: boolean,
+        duration?: number,
+        easing?: string
+    },
     formatter?: (dataKey: string, value: DataValue, data: DataItem) => string
 })
 ```
@@ -116,6 +137,34 @@ The formatter receives:
 - `value` - The data value at this point
 - `data` - The full data item object
 
+Tooltip modes:
+
+- `shared` - One tooltip per hovered category/value group
+- `split` - Default. One tooltip per visible series at the hovered category/value group
+
+Split tooltip positions:
+
+- `side` - Default. Place split tooltips to the side of each data point
+- `vertical` - Place split tooltips above or below each data point
+
+When `split` mode is active, `customFormatter` receives the current series only for
+that tooltip box instead of the full visible series list. Split tooltips include
+directional arrows and avoid overlapping on the same side of the chart when
+possible.
+
+For bars, `barAnchorPosition` controls whether split tooltips point to the `top`
+or `middle` of each bar.
+
+Set `transition.show: true` to fade tooltips in and out. Tooltip position and
+connector geometry update immediately; only opacity and the small entrance
+offset transition.
+
+Tooltip box, text, connector, and arrow colors use `theme.tooltip`.
+
+Formatter, label formatter, and custom formatter output is inserted as HTML.
+Only return trusted content or sanitize user-provided strings before returning
+them from formatter callbacks.
+
 ### Example
 
 ```javascript

package/docs/getting-started.md

@@ -76,6 +76,41 @@ const chart = new XYChart({
 });
 ```
 
+## Lazy Loading
+
+When a page contains charts further down the document, you can defer the chart
+imports until the container is near the viewport.
+
+```typescript
+import { mountChartWhenVisible } from '@internetstiftelsen/charts/lazy-mount';
+
+const lazyChart = mountChartWhenVisible(
+    '#chart-container',
+    async (container) => {
+        const [{ XYChart }, { Line }, { XAxis }, { YAxis }] = await Promise.all([import('@internetstiftelsen/charts/xy-chart'), import('@internetstiftelsen/charts/line'), import('@internetstiftelsen/charts/x-axis'), import('@internetstiftelsen/charts/y-axis')]);
+
+        const chart = new XYChart({ data });
+        chart
+            .addChild(new XAxis({ dataKey: 'date' }))
+            .addChild(new YAxis())
+            .addChild(new Line({ dataKey: 'revenue' }));
+
+        chart.render(container);
+        return chart;
+    },
+    {
+        rootMargin: '240px 0px',
+    },
+);
+
+// Optional if you want to trigger the load early
+await lazyChart.load();
+```
+
+`mountChartWhenVisible` keeps the loading strategy separate from chart
+construction, which makes it a good building block for custom wrappers or
+attribute-driven mounting later on.
+
 ## Grouping Charts
 
 ```javascript

package/docs/theming.md

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

package/docs/xy-chart.md

@@ -21,6 +21,7 @@ new XYChart(config: XYChartConfig)
 | `responsive`  | `ResponsiveConfig`                 | -                                                    | Container-query responsive overrides (theme + components)             |
 | `barStack`    | `BarStackConfig`                   | `{ mode: 'normal', gap: 0.1, reverseSeries: false }` | Bar stacking configuration                                            |
 | `areaStack`   | `AreaStackConfig`                  | `{ mode: 'none' }`                                   | Area stacking configuration                                           |
+| `animate`     | `boolean \| XYAnimationConfig`     | `false`                                              | Opt-in XY series animation for initial render and `update()`          |
 
 ### Theme Options
 
@@ -223,6 +224,45 @@ is measured after declarative breakpoint overrides are merged. It receives
 `context.activeBreakpoints` with every match and `context.breakpoint` as the
 last matching breakpoint name.
 
+## Animation
+
+Use `animate` when you want XY series marks to animate on the first render and
+when calling `chart.update(...)`.
+
+```typescript
+const chart = new XYChart({
+    data,
+    animate: {
+        duration: 700,
+        easing: 'ease-in-out',
+    },
+});
+```
+
+`XYAnimationConfig` supports:
+
+```typescript
+animate: boolean | {
+    show?: boolean,       // default: true when object form is used
+    duration?: number,    // ms, default: 700
+    easing?:
+        | 'linear'
+        | 'ease-in'
+        | 'ease-out'
+        | 'ease-in-out'
+        | 'bounce-out'
+        | 'elastic-out'
+        | `linear(...)`
+        | ((t: number) => number),
+}
+```
+
+Notes:
+
+- Animation is off by default.
+- Animates XY series marks only. Axes, legends, tooltips, and value labels remain static.
+- Visual exports always render the final static state, even when the live chart is animated.
+
 ## Validation
 
 `XYChart` validates configuration and series data early:
@@ -256,6 +296,9 @@ chart.render('#chart-container');
 chart.render(document.getElementById('chart-container'));
 ```
 
+When `animate` is enabled, the first render returns immediately while the series
+transition continues in the background.
+
 ### update(data)
 
 Updates the chart with new data and re-renders.
@@ -264,6 +307,18 @@ Updates the chart with new data and re-renders.
 chart.update(newData);
 ```
 
+When `animate` is enabled, `update()` animates XY series marks from the previous
+rendered geometry to the new one.
+
+### whenReady()
+
+Returns a promise that resolves after any pending async render work finishes.
+For animated XY charts, this waits until the current series transitions finish.
+
+```javascript
+await chart.whenReady();
+```
+
 ### destroy()
 
 Cleans up all resources, removes resize observer, and clears the chart from the DOM.
@@ -280,9 +335,13 @@ Renders a line series on the chart.
 
 ```typescript
 new Line({
-    dataKey: string,       // Key in data objects for Y values (required)
-    stroke?: string,       // Line color (auto-assigned if omitted)
-    strokeWidth?: number,  // Line width in pixels (default: 2)
+    dataKey: string,                 // Key in data objects for Y values (required)
+    stroke?: string,                 // Line color (auto-assigned if omitted)
+    strokeWidth?: number,            // Line width in pixels (default: 2)
+    valueLabel?: {
+        show?: boolean,
+        formatter?: (dataKey, value, data) => string
+    }                                // Point value badges
 })
 ```
 
@@ -309,7 +368,10 @@ new Scatter({
     dataKey: string,                 // Key in data objects for Y values (required)
     stroke?: string,                 // Point color (auto-assigned if omitted)
     pointSize?: number,              // Point radius in pixels (default: theme.line.point.size)
-    valueLabel?: { show?: boolean }  // Point value badges
+    valueLabel?: {
+        show?: boolean,
+        formatter?: (dataKey, value, data) => string
+    }                                // Point value badges
 })
 ```
 
@@ -335,7 +397,8 @@ new Bar({
     valueLabel?: {
         show?: boolean,
         position?: 'inside' | 'outside',
-        insidePosition?: 'top' | 'middle' | 'bottom'
+        insidePosition?: 'top' | 'middle' | 'bottom',
+        formatter?: (dataKey, value, data) => string
     }
 })
 ```
@@ -430,7 +493,18 @@ Bar charts support different stacking modes:
 - `percent` - 100% stacked bars
 - `layer` - Overlapping bars
 
-Use `barStack.reverseSeries: true` to reverse bar series display order for rendering, legend entries, and tooltip rows without changing data exports.
+XY charts use split tooltips by default, rendering one tooltip per visible
+series at the hovered category. Use
+`new Tooltip({ mode: 'shared' | 'split', position: 'side' | 'vertical' })`
+to override the grouping and split-tooltip placement.
+For bars, set `barAnchorPosition: 'top' | 'middle'` to choose whether split
+tooltips point to the top or middle of each bar.
+Use `transition: { show: true, duration: 120, easing: 'ease-out' }` to opt in
+to softer tooltip opacity transitions without delaying position updates.
+
+Use `barStack.reverseSeries: true` to reverse bar series display order for
+rendering, legend entries, and split tooltip ordering without changing data
+exports.
 
 ---
 
@@ -449,7 +523,10 @@ new Area({
     baseline?: number,              // Baseline for non-stacked area (default: 0)
     showLine?: boolean,             // Show top stroke line (default: true)
     showPoints?: boolean,           // Show points on top line (default: false)
-    valueLabel?: { show?: boolean } // Point value badges
+    valueLabel?: {
+        show?: boolean,
+        formatter?: (dataKey, value, data) => string
+    }                               // Point value badges
 })
 ```
 
@@ -468,6 +545,10 @@ chart.addChild(
 );
 ```
 
+For `Line`, `Scatter`, `Bar`, and `Area`, `valueLabel.formatter` receives
+`(dataKey, value, data)`, where `value` is the parsed numeric series value used
+for rendering that label.
+
 ### Area Stacking
 
 Area charts support stacking when series share the same `stackId`: