@internetstiftelsen/charts 0.13.3 → 0.14.1

package/README.md

@@ -10,8 +10,9 @@ A framework-agnostic, composable charting library built on D3.js with TypeScript
 - **Combined Chart Layouts** - `ChartGroup` composes existing charts into shared dashboards with one coordinated legend
 - **Divergent Bar Support** - Bar charts automatically render from zero and diverge around `0` for mixed positive/negative values
 - **Mirrored Bar Sides** - Horizontal bars can mirror a series to the left for population-pyramid style charts without changing source data
-- **Custom Value Labels** - XY, pie, and donut charts support optional on-chart labels with custom formatters
+- **Custom Value Labels** - XY, pie, donut, and gauge charts support configurable labels with formatters, max-width overflow behavior, and forced rendering when labels would otherwise be hidden
 - **Optional XY Animation** - Animate XY series on first render and `chart.update(...)` with `animate`
+- **Optional Radial Animation** - Animate pie and donut segments on first render and `chart.update(...)` with `animate`
 - **Optional Gauge Animation** - Animate gauge value transitions with `gauge.animate`
 - **Stacking Control** - Bar and area stacking modes with optional reversed visual series order
 - **Configurable Tooltips** - Shared or split tooltips with connectors, transitions, and default max-width wrapping
@@ -139,6 +140,8 @@ await chart.whenReady();
 
 Animation is off by default, applies to XY series marks only, and visual
 exports always render the final static state.
+Preset easing values include `linear`, `ease-in`, `ease-out`, `ease-in-out`,
+`bounce-out`, `elastic-out`, and `spring-out`.
 
 ## Lifecycle Events
 
@@ -359,6 +362,7 @@ const data = [
 
 const chart = new WordCloudChart({
     data,
+    animate: true,
     wordCloud: {
         minValue: 5,
         minWordLength: 3,
@@ -376,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
 

package/dist/area.js

@@ -388,6 +388,7 @@ export class Area {
         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', `area-value-labels-${sanitizeForCSS(this.dataKey)}`);
@@ -422,7 +423,7 @@ export class Area {
             if (labelY - boxHeight / 2 < plotTop + 4) {
                 labelY = yPos + boxHeight / 2 + theme.line.point.size + 4;
                 if (labelY + boxHeight / 2 > plotBottom - 4) {
-                    shouldRender = false;
+                    shouldRender = forceVisible;
                 }
             }
             tempText.remove();

package/dist/bar.js

@@ -369,6 +369,7 @@ export class Bar {
             ...this.resolveValueLabelStyle(config, theme),
             formatter: config.formatter,
             autoContrastInside: config.color === undefined,
+            forceVisible: config.forceVisible ?? false,
         };
     }
     resolveValueLabelPlacement(config) {
@@ -461,7 +462,8 @@ export class Bar {
         return {
             x: input.x,
             y,
-            shouldRender: input.labelBox.height + minPadding <= input.barHeight,
+            shouldRender: input.forceVisible ||
+                input.labelBox.height + minPadding <= input.barHeight,
         };
     }
     getVerticalOutsideLabelPlacement(input) {
@@ -474,7 +476,7 @@ export class Bar {
         return {
             x: input.x,
             y,
-            shouldRender,
+            shouldRender: input.forceVisible || shouldRender,
         };
     }
     getVerticalInsideLabelY(barTop, barBottom, labelHeight, insidePosition, inset) {
@@ -506,7 +508,7 @@ export class Bar {
         return {
             x,
             y: input.y,
-            shouldRender: fitsBar && withinBounds,
+            shouldRender: input.forceVisible || (fitsBar && withinBounds),
         };
     }
     getHorizontalOutsideLabelPlacement(input) {
@@ -519,7 +521,7 @@ export class Bar {
         return {
             x,
             y: input.y,
-            shouldRender,
+            shouldRender: input.forceVisible || shouldRender,
         };
     }
     getHorizontalInsideLabelX(barLeft, barRight, labelWidth, isNegative, insidePosition, inset) {
@@ -567,6 +569,7 @@ export class Bar {
             mode,
             position: config.position,
             insidePosition: config.insidePosition,
+            forceVisible: config.forceVisible,
             plotTop,
             plotBottom,
         });
@@ -601,6 +604,7 @@ export class Bar {
             mode,
             position: config.position,
             insidePosition: config.insidePosition,
+            forceVisible: config.forceVisible,
             plotLeft,
             plotRight,
         });

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;
@@ -199,8 +205,10 @@ export declare abstract class BaseChart {
     protected filterVisibleItems<T>(items: T[], getDataKey: (item: T) => string): T[];
     protected validateSourceData(_data: ChartData): void;
     protected syncDerivedState(_previousData?: DataItem[]): void;
+    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,
@@ -268,6 +274,7 @@ export class BaseChart {
         this.responsiveConfig = config.responsive;
         this.legendState = new LegendStateController();
         this.legendState.subscribe(() => {
+            this.prepareForLegendChange();
             this.notifyLegendChanged();
             this.rerender('legend');
         });
@@ -360,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');
@@ -516,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;
@@ -844,6 +904,7 @@ export class BaseChart {
     }
     validateSourceData(_data) { }
     syncDerivedState(_previousData) { }
+    prepareForLegendChange() { }
     initializeDataState() {
         this.validateSourceData(this.sourceData);
         this.syncDerivedState();
@@ -852,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/donut-chart.d.ts

@@ -1,23 +1,34 @@
-import type { DataItem, LegendSeries } from './types.js';
+import type { DataItem, LabelOversizedBehavior, LegendSeries } from './types.js';
 import { type BaseChartConfig, type BaseRenderContext } from './base-chart.js';
 import type { ChartComponentBase } from './chart-interface.js';
 import { RadialChartBase } from './radial-chart-base.js';
+import { type RadialAnimationConfig, type RadialAnimationEasingPreset } from './radial-animation.js';
+export type DonutAnimationConfig = RadialAnimationConfig;
+export type DonutAnimationEasingPreset = RadialAnimationEasingPreset;
 export type DonutConfig = {
     innerRadius?: number;
     padAngle?: number;
     cornerRadius?: number;
 };
 export type DonutValueLabelPosition = 'outside' | 'auto';
+export type DonutValueLabelFormatter = (label: string, value: number, data: DataItem, percentage: number) => string;
 export type DonutValueLabelConfig = {
     show?: boolean;
     position?: DonutValueLabelPosition;
     outsideOffset?: number;
     minVerticalSpacing?: number;
-    formatter?: (label: string, value: number, data: DataItem, percentage: number) => string;
+    maxLabelWidth?: number;
+    oversizedBehavior?: LabelOversizedBehavior;
+    forceVisible?: boolean;
+    labelFormatter?: DonutValueLabelFormatter;
+    valueFormatter?: DonutValueLabelFormatter;
+    separator?: string;
+    formatter?: DonutValueLabelFormatter;
 };
 export type DonutChartConfig = BaseChartConfig & {
     donut?: DonutConfig;
     valueLabel?: DonutValueLabelConfig;
+    animate?: boolean | DonutAnimationConfig;
     valueKey?: string;
     labelKey?: string;
 };
@@ -28,6 +39,7 @@ export declare class DonutChart extends RadialChartBase {
     private readonly valueKey;
     private readonly labelKey;
     private readonly valueLabel;
+    private readonly motionController;
     private segments;
     private centerContent;
     constructor(config: DonutChartConfig);
@@ -36,16 +48,20 @@ export declare class DonutChart extends RadialChartBase {
     addChild(component: ChartComponentBase): this;
     protected getExportComponents(): ChartComponentBase[];
     update(data: DataItem[]): void;
+    protected prepareForLegendChange(): void;
     protected createExportChart(): RadialChartBase;
     protected applyComponentOverrides(overrides: Map<ChartComponentBase, ChartComponentBase>): () => void;
     protected syncDerivedState(): void;
     protected renderChart({ svg, plotGroup, plotArea, }: BaseRenderContext): void;
     protected getLegendSeries(): LegendSeries[];
     private buildTooltipContent;
-    private formatValueLabelText;
+    private resolveValueLabelText;
+    private getValueLabelPercentage;
     private renderSegments;
     private renderLabels;
     private getArcPoint;
     private resolveOutsideLabel;
+    private measureValueLabelDimensions;
     private adjustOutsideLabelPositions;
+    private getOutsideLabelSpacing;
 }