@internetstiftelsen/charts 0.7.1 → 0.9.0

package/README.md

@@ -6,7 +6,9 @@ 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
+- **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
 - **Auto Resize** - Built-in ResizeObserver handles responsive behavior
 - **Responsive Policy** - Chart-level container-query overrides for theme and components
@@ -80,6 +82,37 @@ chart
 chart.render('#chart-container');
 ```
 
+## 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`.
@@ -103,12 +136,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');
@@ -117,16 +147,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

@@ -19,7 +19,6 @@ export declare class Area implements ChartComponent<AreaConfigBase> {
     constructor(config: AreaConfig);
     getExportConfig(): AreaConfigBase;
     createExportComponent(override?: Partial<AreaConfigBase>): ChartComponent;
-    private getScaledPosition;
     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

@@ -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

@@ -13,7 +13,6 @@ export declare class Bar implements ChartComponent<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;
     private renderVertical;
     private renderHorizontal;

package/bar.js

@@ -1,4 +1,19 @@
 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;
+const LABEL_MIN_PADDING_STACKED = 16;
+const LAYER_LABEL_GAP = 6;
+function getLabelSpacing(mode) {
+    const stacked = mode !== 'none';
+    return {
+        inset: stacked ? LABEL_INSET_STACKED : LABEL_INSET_DEFAULT,
+        minPadding: stacked
+            ? LABEL_MIN_PADDING_STACKED
+            : LABEL_MIN_PADDING_DEFAULT,
+    };
+}
 export class Bar {
     constructor(config) {
         Object.defineProperty(this, "type", {
@@ -74,24 +89,6 @@ 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') {
             this.renderVertical(plotGroup, data, xKey, x, y, parseValue, xScaleType, stackingContext);
@@ -164,7 +161,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;
@@ -287,7 +284,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;
@@ -374,7 +371,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;
@@ -426,76 +423,42 @@ export class Bar {
                 }
             }
             else {
-                // Inside the bar - with special handling for layer mode
-                if (mode === 'layer') {
-                    const totalSeries = stackingContext?.totalSeries ?? 1;
-                    const seriesIndex = stackingContext?.seriesIndex ?? 0;
-                    const isTopLayer = seriesIndex === totalSeries - 1;
-                    switch (insidePosition) {
-                        case 'top':
-                            // For layer mode + inside + top: check if there's enough space in the gap
-                            if (seriesIndex < totalSeries - 1) {
-                                // Calculate the gap to the next layer
-                                const nextLayerScaleFactor = 1 - ((seriesIndex + 1) / totalSeries) * 0.7;
-                                const nextLayerWidth = (this.maxBarSize
-                                    ? Math.min(bandwidth, this.maxBarSize)
-                                    : bandwidth) * nextLayerScaleFactor;
-                                const gap = (barWidth - nextLayerWidth) / 2;
-                                const marginBelow = 4; // Minimum margin below text
-                                if (boxHeight + marginBelow <= gap) {
-                                    labelY =
-                                        barTop + boxHeight / 2 + marginBelow;
-                                }
-                                else {
-                                    shouldRender = false;
-                                }
-                            }
-                            else {
-                                // Top layer - use normal top position if it fits
-                                labelY = barTop + boxHeight / 2 + 4;
-                                if (boxHeight + 8 > barHeight) {
-                                    shouldRender = false;
-                                }
-                            }
-                            break;
-                        case 'middle':
-                            // For layer mode + inside + middle: only show what fits
-                            labelY = (barTop + barBottom) / 2;
-                            if (boxHeight + 8 > barHeight) {
-                                shouldRender = false;
-                            }
-                            break;
-                        case 'bottom':
-                            // For layer mode + inside + bottom: only show for top layer if it fits
-                            if (isTopLayer) {
-                                labelY = barBottom - boxHeight / 2 - 4;
-                                if (boxHeight + 8 > barHeight) {
-                                    shouldRender = false;
-                                }
-                            }
-                            else {
-                                shouldRender = false;
-                            }
-                            break;
-                    }
+                if (mode === 'layer' && insidePosition === 'bottom') {
+                    // Bottom labels in layer mode are visually ambiguous and often hidden by overlap.
+                    shouldRender = false;
                 }
                 else {
-                    // Non-layer modes - use existing logic
+                    const { inset, minPadding } = getLabelSpacing(mode);
                     switch (insidePosition) {
                         case 'top':
-                            labelY = barTop + boxHeight / 2 + 4;
+                            labelY = barTop + boxHeight / 2 + inset;
                             break;
                         case 'middle':
                             labelY = (barTop + barBottom) / 2;
                             break;
                         case 'bottom':
-                            labelY = barBottom - boxHeight / 2 - 4;
+                            labelY = barBottom - boxHeight / 2 - inset;
                             break;
                     }
                     // Check if it fits inside the bar
-                    if (boxHeight + 8 > barHeight) {
+                    if (boxHeight + minPadding > barHeight) {
                         shouldRender = false;
                     }
+                    // In layer mode, check the label fits in the visible gap
+                    // above the next layer's bar top
+                    if (shouldRender &&
+                        mode === 'layer' &&
+                        insidePosition === 'top' &&
+                        stackingContext?.nextLayerData) {
+                        const nextValue = stackingContext.nextLayerData.get(categoryKey);
+                        if (nextValue !== undefined) {
+                            const nextBarTop = y(nextValue) || 0;
+                            const labelBottom = labelY + boxHeight / 2;
+                            if (labelBottom + LAYER_LABEL_GAP > nextBarTop) {
+                                shouldRender = false;
+                            }
+                        }
+                    }
                 }
             }
             tempText.remove();
@@ -592,7 +555,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;
@@ -644,78 +607,43 @@ export class Bar {
                 }
             }
             else {
-                // Inside the bar - with special handling for layer mode
-                if (mode === 'layer') {
-                    const totalSeries = stackingContext?.totalSeries ?? 1;
-                    const seriesIndex = stackingContext?.seriesIndex ?? 0;
-                    const isTopLayer = seriesIndex === totalSeries - 1;
-                    // Map top/middle/bottom to start/middle/end for horizontal
-                    switch (insidePosition) {
-                        case 'top': // start of bar (left side)
-                            // For layer mode + inside + top(left): check if there's enough space in the gap
-                            if (seriesIndex < totalSeries - 1) {
-                                // Calculate the gap to the next layer
-                                const nextLayerScaleFactor = 1 - ((seriesIndex + 1) / totalSeries) * 0.7;
-                                const nextLayerHeight = (this.maxBarSize
-                                    ? Math.min(bandwidth, this.maxBarSize)
-                                    : bandwidth) * nextLayerScaleFactor;
-                                const gap = (barHeight - nextLayerHeight) / 2;
-                                const marginRight = 4; // Minimum margin to the right of text
-                                if (boxWidth + marginRight <= gap) {
-                                    labelX =
-                                        barLeft + boxWidth / 2 + marginRight;
-                                }
-                                else {
-                                    shouldRender = false;
-                                }
-                            }
-                            else {
-                                // Top layer - use normal left position if it fits
-                                labelX = barLeft + boxWidth / 2 + 4;
-                                if (boxWidth + 8 > barWidth) {
-                                    shouldRender = false;
-                                }
-                            }
-                            break;
-                        case 'middle':
-                            // For layer mode + inside + middle: only show what fits
-                            labelX = (barLeft + barRight) / 2;
-                            if (boxWidth + 8 > barWidth) {
-                                shouldRender = false;
-                            }
-                            break;
-                        case 'bottom': // end of bar (right side)
-                            // For layer mode + inside + bottom(right): only show for top layer if it fits
-                            if (isTopLayer) {
-                                labelX = barRight - boxWidth / 2 - 4;
-                                if (boxWidth + 8 > barWidth) {
-                                    shouldRender = false;
-                                }
-                            }
-                            else {
-                                shouldRender = false;
-                            }
-                            break;
-                    }
+                // Map top/middle/bottom to start/middle/end for horizontal
+                if (mode === 'layer' && insidePosition === 'bottom') {
+                    // Bottom labels in layer mode are visually ambiguous and often hidden by overlap.
+                    shouldRender = false;
                 }
                 else {
-                    // Non-layer modes - use existing logic
-                    // Map top/middle/bottom to start/middle/end for horizontal
+                    const { inset, minPadding } = getLabelSpacing(mode);
                     switch (insidePosition) {
                         case 'top': // start of bar (left side)
-                            labelX = barLeft + boxWidth / 2 + 4;
+                            labelX = barLeft + boxWidth / 2 + inset;
                             break;
                         case 'middle':
                             labelX = (barLeft + barRight) / 2;
                             break;
                         case 'bottom': // end of bar (right side)
-                            labelX = barRight - boxWidth / 2 - 4;
+                            labelX = barRight - boxWidth / 2 - inset;
                             break;
                     }
                     // Check if it fits inside the bar
-                    if (boxWidth + 8 > barWidth) {
+                    if (boxWidth + minPadding > barWidth) {
                         shouldRender = false;
                     }
+                    // In layer mode, check the label fits in the visible gap
+                    // before the next layer's bar end
+                    if (shouldRender &&
+                        mode === 'layer' &&
+                        insidePosition === 'top' &&
+                        stackingContext?.nextLayerData) {
+                        const nextValue = stackingContext.nextLayerData.get(categoryKey);
+                        if (nextValue !== undefined) {
+                            const nextBarRight = x(nextValue) || 0;
+                            const labelRight = labelX + boxWidth / 2;
+                            if (labelRight + LAYER_LABEL_GAP > nextBarRight) {
+                                shouldRender = false;
+                            }
+                        }
+                    }
                 }
             }
             tempText.remove();

package/base-chart.d.ts

@@ -18,6 +18,34 @@ type ResponsiveOverrides = {
     theme?: DeepPartial<ChartTheme>;
     components: Map<ChartComponent, 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 ChartComponent = ChartComponent> = {
+    type: TComponent['type'];
+    get: () => TComponent | null;
+    set: (component: TComponent | null) => void;
+    onRegister?: (component: TComponent) => void;
+};
 export type BaseChartConfig = {
     data: ChartData;
     theme?: Partial<ChartTheme>;
@@ -49,12 +77,14 @@ export declare abstract class BaseChart {
     protected resizeObserver: ResizeObserver | null;
     protected layoutManager: LayoutManager;
     protected plotArea: PlotAreaBounds | null;
+    private readyPromise;
     private disconnectedLegendContainer;
+    private renderThemeOverride;
     protected constructor(config: BaseChartConfig);
     /**
      * Adds a component (axis, grid, tooltip, etc.) to the chart
      */
-    abstract addChild(component: ChartComponent): this;
+    addChild(component: ChartComponent): this;
     /**
      * Renders the chart to the specified target element
      */
@@ -71,13 +101,18 @@ export declare abstract class BaseChart {
     }): ResponsiveRenderContext;
     private resolveBreakpointName;
     private resolveRenderTheme;
-    private applyThemeOverride;
+    private applyRenderTheme;
+    protected get renderTheme(): ChartTheme;
     /**
      * Get layout-aware components in order
      * Override in subclasses to provide chart-specific components
      */
     protected getLayoutComponents(): LayoutAwareComponent[];
+    protected getBaseLayoutComponents(options: BaseLayoutComponentsOptions): LayoutAwareComponent[];
     protected getExportComponents(): ChartComponent[];
+    protected getOverrideableComponents(): ChartComponent[];
+    protected getBaseExportComponents(options: BaseExportComponentsOptions): ChartComponent[];
+    protected registerBaseComponent(component: ChartComponent): boolean;
     protected collectExportOverrides(context: ExportRenderContext): Map<ChartComponent, Record<string, unknown>>;
     protected collectResponsiveOverrides(context: ResponsiveRenderContext): ResponsiveOverrides;
     protected runExportHooks(context: ExportHookContext): void;
@@ -85,7 +120,14 @@ export declare abstract class BaseChart {
     private createOverrideComponents;
     protected applyComponentOverrides(overrides: Map<ChartComponent, ChartComponent>): () => 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 +135,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 +158,11 @@ export declare abstract class BaseChart {
     private resolveDisconnectedLegendHost;
     private cleanupDisconnectedLegendContainer;
     protected parseValue(value: unknown): number;
+    protected rerender(): void;
+    protected tryRegisterComponent(component: ChartComponent, slots: readonly ComponentSlot[]): boolean;
+    protected applySlotOverrides(overrides: Map<ChartComponent, ChartComponent>, slots: readonly ComponentSlot[]): () => void;
+    protected applyArrayComponentOverrides<TComponent extends ChartComponent>(components: TComponent[], overrides: Map<ChartComponent, ChartComponent>, isComponent: (component: ChartComponent) => component is TComponent): () => void;
+    private getBaseComponentSlots;
     /**
      * Exports the chart in the specified format
      * @param format - The export format
@@ -131,7 +180,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 {};