@internetstiftelsen/charts 0.8.0 → 0.9.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Internetstiftelsen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -6,9 +6,12 @@ A framework-agnostic, composable charting library built on D3.js with TypeScript
 
 - **Framework Agnostic** - Works with vanilla JS, React, Vue, Svelte, or any framework
 - **Composable Architecture** - Build charts by composing components
-- **Multiple Chart Types** - XYChart (lines, areas, bars), DonutChart, PieChart, and GaugeChart
+- **Multiple Chart Types** - XYChart (lines, areas, bars), WordCloudChart, DonutChart, PieChart, and GaugeChart
+- **Radial Value Labels** - Pie and donut charts support optional on-chart labels with custom formatters
+- **Optional Gauge Animation** - Animate gauge value transitions with `gauge.animate`
 - **Stacking Control** - Bar stacking modes with optional reversed visual series order
 - **Flexible Scales** - Band, linear, time, and logarithmic scales
+- **Explicit or Responsive Sizing** - Set top-level `width`/`height` or let the container drive size
 - **Auto Resize** - Built-in ResizeObserver handles responsive behavior
 - **Responsive Policy** - Chart-level container-query overrides for theme and components
 - **Type Safe** - Written in TypeScript with full type definitions
@@ -81,6 +84,79 @@ chart
 chart.render('#chart-container');
 ```
 
+Use top-level `width` and `height` for fixed-size charts, or omit them to size
+from the render container.
+
+Theme overrides are deep-partial, so nested overrides like
+`theme.axis.fontSize` preserve the rest of the theme defaults.
+
+Responsive overrides are declarative and merge all matching breakpoints in
+declaration order:
+
+```typescript
+const chart = new XYChart({
+    data,
+    responsive: {
+        breakpoints: {
+            sm: {
+                maxWidth: 640,
+                theme: {
+                    axis: {
+                        fontSize: 11,
+                    },
+                },
+                components: [
+                    {
+                        match: { type: 'xAxis' },
+                        override: { display: false },
+                    },
+                ],
+            },
+            md: {
+                minWidth: 641,
+                maxWidth: 768,
+                theme: {
+                    axis: {
+                        fontSize: 12,
+                    },
+                },
+            },
+        },
+    },
+});
+```
+
+## Word Cloud
+
+```javascript
+import { WordCloudChart } from '@internetstiftelsen/charts/word-cloud-chart';
+
+const data = [
+    { word: 'internet', count: 96 },
+    { word: 'social', count: 82 },
+    { word: 'news', count: 75 },
+];
+
+const chart = new WordCloudChart({
+    data,
+    wordCloud: {
+        minValue: 5,
+        minWordLength: 3,
+        minFontSize: 3,
+        maxFontSize: 20,
+        padding: 1,
+        spiral: 'archimedean',
+    },
+});
+
+chart.render('#word-cloud');
+```
+
+`minFontSize` and `maxFontSize` are percentages of the smaller plot-area
+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.
+
 ## Export
 
 `chart.export()` supports `svg`, `json`, `csv`, `xlsx`, `png`, `jpg`, and `pdf`.
@@ -104,12 +180,9 @@ It auto-detects grouped and normal (flat) table layouts.
 import { toChartData } from '@internetstiftelsen/charts/utils';
 import { XYChart } from '@internetstiftelsen/charts/xy-chart';
 
-const data = toChartData(
-    '\t\tDaily\tWeekly\nAll users\tSegment A\t85%\t92%\n\tSegment B\t84%\t91%',
-    {
-        categoryKey: 'Category',
-    },
-);
+const data = toChartData('\t\tDaily\tWeekly\nAll users\tSegment A\t85%\t92%\n\tSegment B\t84%\t91%', {
+    categoryKey: 'Category',
+});
 
 const chart = new XYChart({ data });
 chart.render('#chart-container');
@@ -118,16 +191,32 @@ chart.render('#chart-container');
 The parser supports JSON-escaped string payloads and grouped carry-forward row
 structure (blank first column on continuation rows).
 
+Supported input shapes:
+
+- Plain tab-delimited strings
+- JSON-escaped string payloads
+
+Auto-detection behavior:
+
+- Grouped rows when a carry-forward group structure is present
+- Flat rows when no grouped continuation rows are detected
+
+Grouped parsing rules:
+
+- Header row starts with two structural columns (`group`, `category`) before metrics
+- Continuation rows leave the first column blank to inherit the previous group
+- Blank separator rows are ignored
+
 ## Documentation
 
 - [Getting Started](./docs/getting-started.md) - Installation, Vanilla JS, React integration
 - [XYChart](./docs/xy-chart.md) - Line, area, and bar charts API
+- [WordCloudChart](./docs/word-cloud-chart.md) - Word frequency visualization API
 - [DonutChart](./docs/donut-chart.md) - Donut/pie charts API
 - [PieChart](./docs/pie-chart.md) - Pie chart API
 - [GaugeChart](./docs/gauge-chart.md) - Gauge chart API
 - [Components](./docs/components.md) - Axes, Grid, Tooltip, Legend, Title
 - [Theming](./docs/theming.md) - Colors, fonts, and styling
-- [Advanced](./docs/advanced.md) - Scales, TypeScript, architecture, performance
 
 ## Browser Support
 

package/{area.d.ts → dist/area.d.ts}

@@ -18,8 +18,7 @@ export declare class Area implements ChartComponent<AreaConfigBase> {
     readonly exportHooks?: ExportHooks<AreaConfigBase>;
     constructor(config: AreaConfig);
     getExportConfig(): AreaConfigBase;
-    createExportComponent(override?: Partial<AreaConfigBase>): ChartComponent;
-    private getScaledPosition;
+    createExportComponent(override?: Partial<AreaConfigBase>): ChartComponent<AreaConfigBase>;
     private getStackValues;
     render(plotGroup: Selection<SVGGElement, undefined, null, undefined>, data: DataItem[], xKey: string, x: D3Scale, y: D3Scale, parseValue: (value: unknown) => number, xScaleType: ScaleType | undefined, theme: ChartTheme, stackingContext?: AreaStackingContext, valueLabelLayer?: Selection<SVGGElement, undefined, null, undefined>): void;
     private renderValueLabels;

package/{area.js → dist/area.js}

@@ -1,5 +1,6 @@
 import { area, curveBasis, curveCardinal, curveLinear, curveMonotoneX, curveNatural, curveStep, line, } from 'd3';
 import { mergeDeep, sanitizeForCSS } from './utils.js';
+import { getScalePosition } from './scale-utils.js';
 const AREA_CURVE_FACTORIES = {
     linear: curveLinear,
     monotone: curveMonotoneX,
@@ -132,24 +133,6 @@ export class Area {
             exportHooks: this.exportHooks,
         });
     }
-    getScaledPosition(data, key, scale, scaleType) {
-        const value = data[key];
-        let scaledValue;
-        switch (scaleType) {
-            case 'band':
-                scaledValue = String(value);
-                break;
-            case 'time':
-                scaledValue =
-                    value instanceof Date ? value : new Date(String(value));
-                break;
-            case 'linear':
-            case 'log':
-                scaledValue = typeof value === 'number' ? value : Number(value);
-                break;
-        }
-        return scale(scaledValue) || 0;
-    }
     getStackValues(dataPoint, xKey, parseValue, stackingContext) {
         const value = parseValue(dataPoint[this.dataKey]);
         if (!stackingContext || stackingContext.mode === 'none') {
@@ -176,7 +159,7 @@ export class Area {
     }
     render(plotGroup, data, xKey, x, y, parseValue, xScaleType = 'band', theme, stackingContext, valueLabelLayer) {
         const getXPosition = (d) => {
-            const scaled = this.getScaledPosition(d.data, xKey, x, xScaleType);
+            const scaled = getScalePosition(x, d.data[xKey], xScaleType);
             return scaled + (x.bandwidth ? x.bandwidth() / 2 : 0);
         };
         const hasValidValue = (d) => {

package/{bar.d.ts → dist/bar.d.ts}

@@ -1,20 +1,18 @@
 import type { Selection } from 'd3';
-import type { BarConfig, BarStackingContext, BarValueLabelConfig, ChartTheme, D3Scale, DataItem, Orientation, ScaleType, ExportHooks, BarConfigBase } from './types.js';
+import type { BarConfig, BarStackingContext, BarValueLabelConfig, ChartTheme, D3Scale, DataItem, ScaleType, ExportHooks, BarConfigBase } from './types.js';
 import type { ChartComponent } from './chart-interface.js';
 export declare class Bar implements ChartComponent<BarConfigBase> {
     readonly type: "bar";
     readonly dataKey: string;
     readonly fill: string;
     readonly colorAdapter?: (data: DataItem, index: number) => string;
-    readonly orientation: Orientation;
     readonly maxBarSize?: number;
     readonly valueLabel?: BarValueLabelConfig;
     readonly exportHooks?: ExportHooks<BarConfigBase>;
     constructor(config: BarConfig);
     getExportConfig(): BarConfigBase;
-    createExportComponent(override?: Partial<BarConfigBase>): ChartComponent;
-    private getScaledPosition;
-    render(plotGroup: Selection<SVGGElement, undefined, null, undefined>, data: DataItem[], xKey: string, x: D3Scale, y: D3Scale, parseValue: (value: unknown) => number, xScaleType?: ScaleType, theme?: ChartTheme, stackingContext?: BarStackingContext): void;
+    createExportComponent(override?: Partial<BarConfigBase>): ChartComponent<BarConfigBase>;
+    render(plotGroup: Selection<SVGGElement, undefined, null, undefined>, data: DataItem[], xKey: string, x: D3Scale, y: D3Scale, parseValue: (value: unknown) => number, xScaleType?: ScaleType, theme?: ChartTheme, stackingContext?: BarStackingContext, orientation?: 'vertical' | 'horizontal'): void;
     private renderVertical;
     private renderHorizontal;
     private renderVerticalValueLabels;

package/{bar.js → dist/bar.js}

@@ -1,4 +1,5 @@
 import { getContrastTextColor, sanitizeForCSS, mergeDeep } from './utils.js';
+import { getScalePosition } from './scale-utils.js';
 const LABEL_INSET_DEFAULT = 4;
 const LABEL_INSET_STACKED = 6;
 const LABEL_MIN_PADDING_DEFAULT = 8;
@@ -39,12 +40,6 @@ export class Bar {
             writable: true,
             value: void 0
         });
-        Object.defineProperty(this, "orientation", {
-            enumerable: true,
-            configurable: true,
-            writable: true,
-            value: void 0
-        });
         Object.defineProperty(this, "maxBarSize", {
             enumerable: true,
             configurable: true,
@@ -66,7 +61,6 @@ export class Bar {
         this.dataKey = config.dataKey;
         this.fill = config.fill || '#8884d8';
         this.colorAdapter = config.colorAdapter;
-        this.orientation = config.orientation || 'vertical';
         this.maxBarSize = config.maxBarSize;
         this.valueLabel = config.valueLabel;
         this.exportHooks = config.exportHooks;
@@ -76,7 +70,6 @@ export class Bar {
             dataKey: this.dataKey,
             fill: this.fill,
             colorAdapter: this.colorAdapter,
-            orientation: this.orientation,
             maxBarSize: this.maxBarSize,
             valueLabel: this.valueLabel,
         };
@@ -88,26 +81,8 @@ export class Bar {
             exportHooks: this.exportHooks,
         });
     }
-    getScaledPosition(data, key, scale, scaleType) {
-        const value = data[key];
-        let scaledValue;
-        switch (scaleType) {
-            case 'band':
-                scaledValue = String(value);
-                break;
-            case 'time':
-                scaledValue =
-                    value instanceof Date ? value : new Date(String(value));
-                break;
-            case 'linear':
-            case 'log':
-                scaledValue = typeof value === 'number' ? value : Number(value);
-                break;
-        }
-        return scale(scaledValue) || 0;
-    }
-    render(plotGroup, data, xKey, x, y, parseValue, xScaleType = 'band', theme, stackingContext) {
-        if (this.orientation === 'vertical') {
+    render(plotGroup, data, xKey, x, y, parseValue, xScaleType = 'band', theme, stackingContext, orientation = 'vertical') {
+        if (orientation === 'vertical') {
             this.renderVertical(plotGroup, data, xKey, x, y, parseValue, xScaleType, stackingContext);
         }
         else {
@@ -115,7 +90,7 @@ export class Bar {
         }
         // Render value labels if enabled
         if (this.valueLabel?.show && theme) {
-            if (this.orientation === 'vertical') {
+            if (orientation === 'vertical') {
                 this.renderVerticalValueLabels(plotGroup, data, xKey, x, y, parseValue, xScaleType, theme, stackingContext);
             }
             else {
@@ -178,7 +153,7 @@ export class Bar {
             .attr('class', `bar-${sanitizedKey}`)
             .attr('data-index', (_, i) => i)
             .attr('x', (d) => {
-            const xPos = this.getScaledPosition(d, xKey, x, xScaleType);
+            const xPos = getScalePosition(x, d[xKey], xScaleType);
             return xScaleType === 'band'
                 ? xPos + barOffset
                 : xPos - barWidth / 2;
@@ -301,7 +276,7 @@ export class Bar {
             }
         })
             .attr('y', (d) => {
-            const yPos = this.getScaledPosition(d, xKey, y, yScaleType);
+            const yPos = getScalePosition(y, d[xKey], yScaleType);
             return yScaleType === 'band'
                 ? yPos + barOffset
                 : yPos - barHeight / 2;
@@ -388,7 +363,7 @@ export class Bar {
             const categoryKey = String(d[xKey]);
             const value = parseValue(d[this.dataKey]);
             const valueText = String(value);
-            const xPos = this.getScaledPosition(d, xKey, x, xScaleType);
+            const xPos = getScalePosition(x, d[xKey], xScaleType);
             const barColor = this.colorAdapter
                 ? this.colorAdapter(d, i)
                 : this.fill;
@@ -572,7 +547,7 @@ export class Bar {
             const categoryKey = String(d[xKey]);
             const value = parseValue(d[this.dataKey]);
             const valueText = String(value);
-            const yPos = this.getScaledPosition(d, xKey, y, yScaleType);
+            const yPos = getScalePosition(y, d[xKey], yScaleType);
             const barColor = this.colorAdapter
                 ? this.colorAdapter(d, i)
                 : this.fill;

package/{base-chart.d.ts → dist/base-chart.d.ts}

@@ -1,6 +1,6 @@
 import { type Selection } from 'd3';
-import type { ChartData, DataItem, ChartTheme, AxisScaleConfig, ExportFormat, ExportOptions, D3Scale, ExportHookContext, ExportRenderContext, LegendItem, LegendSeries, ResponsiveConfig, ResponsiveRenderContext, DeepPartial } from './types.js';
-import type { ChartComponent, LayoutAwareComponent } from './chart-interface.js';
+import type { ChartData, DataItem, ChartTheme, ResolvedChartTheme, AxisScaleConfig, ExportFormat, ExportOptions, D3Scale, ExportHookContext, ExportRenderContext, LegendItem, LegendSeries, ResponsiveConfig, ResponsiveRenderContext, DeepPartial } from './types.js';
+import type { ChartComponentBase, LayoutAwareComponentBase } from './chart-interface.js';
 import type { XAxis } from './x-axis.js';
 import type { YAxis } from './y-axis.js';
 import type { Grid } from './grid.js';
@@ -12,15 +12,46 @@ type VisualExportFormat = 'svg' | 'png' | 'jpg' | 'pdf';
 type RenderDimensions = {
     width: number;
     height: number;
+    svgWidthAttr: number | string;
     svgHeightAttr: number | string;
 };
 type ResponsiveOverrides = {
     theme?: DeepPartial<ChartTheme>;
-    components: Map<ChartComponent, Record<string, unknown>>;
+    components: Map<ChartComponentBase, Record<string, unknown>>;
+};
+type BaseLayoutComponentsOptions = {
+    title?: boolean;
+    xAxis?: boolean;
+    yAxis?: boolean;
+    inlineLegend?: boolean;
+};
+type BaseExportComponentsOptions = {
+    title?: boolean;
+    grid?: boolean;
+    xAxis?: boolean;
+    yAxis?: boolean;
+    tooltip?: boolean;
+    legend?: boolean;
+};
+export type BaseLayoutContext = {
+    svg: Selection<SVGSVGElement, undefined, null, undefined>;
+    svgNode: SVGSVGElement;
+};
+export type BaseRenderContext = BaseLayoutContext & {
+    plotGroup: Selection<SVGGElement, undefined, null, undefined>;
+    plotArea: PlotAreaBounds;
+};
+type ComponentSlot<TComponent extends ChartComponentBase = ChartComponentBase> = {
+    type: TComponent['type'];
+    get: () => TComponent | null;
+    set: (component: TComponent | null) => void;
+    onRegister?: (component: TComponent) => void;
 };
 export type BaseChartConfig = {
     data: ChartData;
-    theme?: Partial<ChartTheme>;
+    width?: number;
+    height?: number;
+    theme?: DeepPartial<ChartTheme>;
     scales?: AxisScaleConfig;
     responsive?: ResponsiveConfig;
 };
@@ -30,6 +61,8 @@ export type BaseChartConfig = {
 export declare abstract class BaseChart {
     protected data: DataItem[];
     protected sourceData: ChartData;
+    protected readonly configuredWidth?: number;
+    protected readonly configuredHeight?: number;
     protected readonly theme: ChartTheme;
     protected readonly scaleConfig: AxisScaleConfig;
     protected readonly responsiveConfig?: ResponsiveConfig;
@@ -49,12 +82,15 @@ export declare abstract class BaseChart {
     protected resizeObserver: ResizeObserver | null;
     protected layoutManager: LayoutManager;
     protected plotArea: PlotAreaBounds | null;
+    private readyPromise;
     private disconnectedLegendContainer;
+    private renderThemeOverride;
+    private renderSizeOverride;
     protected constructor(config: BaseChartConfig);
     /**
      * Adds a component (axis, grid, tooltip, etc.) to the chart
      */
-    abstract addChild(component: ChartComponent): this;
+    addChild(component: ChartComponentBase): this;
     /**
      * Renders the chart to the specified target element
      */
@@ -65,27 +101,45 @@ export declare abstract class BaseChart {
      */
     private performRender;
     protected resolveRenderDimensions(containerRect: DOMRect): RenderDimensions;
+    private resolveAccessibleLabel;
+    private syncAccessibleLabelFromSvg;
     protected resolveResponsiveContext(context: {
         width: number;
         height: number;
     }): ResponsiveRenderContext;
-    private resolveBreakpointName;
+    private resolveActiveBreakpoints;
     private resolveRenderTheme;
-    private applyThemeOverride;
+    private applyRenderTheme;
+    protected get renderTheme(): ChartTheme;
+    protected get resolvedRenderTheme(): ResolvedChartTheme;
     /**
      * Get layout-aware components in order
      * Override in subclasses to provide chart-specific components
      */
-    protected getLayoutComponents(): LayoutAwareComponent[];
-    protected getExportComponents(): ChartComponent[];
-    protected collectExportOverrides(context: ExportRenderContext): Map<ChartComponent, Record<string, unknown>>;
+    protected getLayoutComponents(): LayoutAwareComponentBase[];
+    protected getBaseLayoutComponents(options: BaseLayoutComponentsOptions): LayoutAwareComponentBase[];
+    protected getExportComponents(): ChartComponentBase[];
+    protected getOverrideableComponents(): ChartComponentBase[];
+    protected getBaseExportComponents(options: BaseExportComponentsOptions): ChartComponentBase[];
+    protected registerBaseComponent(component: ChartComponentBase): boolean;
+    protected collectExportOverrides(context: ExportRenderContext): Map<ChartComponentBase, Record<string, unknown>>;
     protected collectResponsiveOverrides(context: ResponsiveRenderContext): ResponsiveOverrides;
+    private collectResponsiveBreakpointOverrides;
+    private createResponsiveComponentSnapshots;
+    private applyResponsiveComponentOverrideEntries;
     protected runExportHooks(context: ExportHookContext): void;
     private mergeComponentOverrideMaps;
     private createOverrideComponents;
-    protected applyComponentOverrides(overrides: Map<ChartComponent, ChartComponent>): () => void;
+    protected applyComponentOverrides(overrides: Map<ChartComponentBase, ChartComponentBase>): () => void;
     private renderExportChart;
-    protected prepareLayout(): void;
+    protected renderTitle(svg: Selection<SVGSVGElement, undefined, null, undefined>): void;
+    protected renderInlineLegend(svg: Selection<SVGSVGElement, undefined, null, undefined>): void;
+    protected measureInlineLegend(svgNode: SVGSVGElement): void;
+    protected filterVisibleItems<T>(items: T[], getDataKey: (item: T) => string): T[];
+    protected validateSourceData(_data: ChartData): void;
+    protected syncDerivedState(_previousData?: DataItem[]): void;
+    protected initializeDataState(): void;
+    protected prepareLayout(context: BaseLayoutContext): void;
     /**
      * Setup ResizeObserver for automatic resize handling
      */
@@ -93,8 +147,10 @@ export declare abstract class BaseChart {
     /**
      * Subclasses must implement this method to define their rendering logic
      */
-    protected abstract renderChart(): void;
+    protected abstract renderChart(context: BaseRenderContext): void;
     protected abstract createExportChart(): BaseChart;
+    protected setReadyPromise(promise: Promise<void>): void;
+    whenReady(): Promise<void>;
     protected getLegendSeries(): LegendSeries[];
     getLegendItems(): LegendItem[];
     isLegendSeriesVisible(dataKey: string): boolean;
@@ -114,6 +170,11 @@ export declare abstract class BaseChart {
     private resolveDisconnectedLegendHost;
     private cleanupDisconnectedLegendContainer;
     protected parseValue(value: unknown): number;
+    protected rerender(): void;
+    protected tryRegisterComponent(component: ChartComponentBase, slots: readonly ComponentSlot[]): boolean;
+    protected applySlotOverrides(overrides: Map<ChartComponentBase, ChartComponentBase>, slots: readonly ComponentSlot[]): () => void;
+    protected applyArrayComponentOverrides<TComponent extends ChartComponentBase>(components: TComponent[], overrides: Map<ChartComponentBase, ChartComponentBase>, isComponent: (component: ChartComponentBase) => component is TComponent): () => void;
+    private getBaseComponentSlots;
     /**
      * Exports the chart in the specified format
      * @param format - The export format
@@ -131,7 +192,7 @@ export declare abstract class BaseChart {
     private exportXLSX;
     private exportImage;
     private exportPDF;
-    protected exportSVG(options?: ExportOptions, formatForHooks?: VisualExportFormat): string;
+    protected exportSVG(options?: ExportOptions, formatForHooks?: VisualExportFormat): Promise<string>;
     protected exportJSON(): string;
 }
 export {};