@internetstiftelsen/charts 0.8.0 → 0.9.0

package/README.md

@@ -6,7 +6,8 @@ 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
@@ -81,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`.
@@ -104,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');
@@ -118,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,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;
@@ -88,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);
@@ -178,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;
@@ -301,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;
@@ -388,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;
@@ -572,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;

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 {};