@internetstiftelsen/charts 0.6.1 → 0.7.1

package/README.md

@@ -9,6 +9,7 @@ A framework-agnostic, composable charting library built on D3.js with TypeScript
 - **Multiple Chart Types** - XYChart (lines, areas, bars), DonutChart, PieChart, and GaugeChart
 - **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
 - **Type Safe** - Written in TypeScript with full type definitions
 - **Data Validation** - Built-in validation with helpful error messages
 - **Auto Colors** - Smart color palette with sensible defaults
@@ -19,6 +20,42 @@ A framework-agnostic, composable charting library built on D3.js with TypeScript
 npm install @internetstiftelsen/charts
 ```
 
+## Local Development
+
+```bash
+pnpm dev
+```
+
+Runs the interactive demo app (`index.html`) with sidebar controls and
+Chart/Data/Showcase tabs.
+
+```bash
+pnpm dev:docs
+```
+
+Runs the marketing landing page (`docs.html`) built on
+`@internetstiftelsen/styleguide`.
+
+## Build Targets
+
+```bash
+pnpm build
+```
+
+Builds the publishable chart library output into `dist`.
+
+```bash
+pnpm build:docs
+```
+
+Builds the static marketing site into `dist-docs` (used for Pages deploys).
+
+```bash
+pnpm build:demo
+```
+
+Builds the demo app using the default Vite config.
+
 ## Quick Start
 
 ```javascript
@@ -57,6 +94,29 @@ await chart.export('pdf', { download: true, pdfMargin: 16 });
 `xlsx` and `pdf` are lazy-loaded and require optional dependencies (`xlsx` and
 `jspdf`) only when those formats are used.
 
+## Import
+
+`toChartData()` converts tab-delimited string input into chart JSON data.
+It auto-detects grouped and normal (flat) table layouts.
+
+```typescript
+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 chart = new XYChart({ data });
+chart.render('#chart-container');
+```
+
+The parser supports JSON-escaped string payloads and grouped carry-forward row
+structure (blank first column on continuation rows).
+
 ## Documentation
 
 - [Getting Started](./docs/getting-started.md) - Installation, Vanilla JS, React integration

package/base-chart.d.ts

@@ -1,5 +1,5 @@
 import { type Selection } from 'd3';
-import type { ChartData, DataItem, ChartTheme, AxisScaleConfig, ExportFormat, ExportOptions, D3Scale, ExportHookContext, ExportRenderContext } from './types.js';
+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 { XAxis } from './x-axis.js';
 import type { YAxis } from './y-axis.js';
@@ -14,10 +14,15 @@ type RenderDimensions = {
     height: number;
     svgHeightAttr: number | string;
 };
+type ResponsiveOverrides = {
+    theme?: DeepPartial<ChartTheme>;
+    components: Map<ChartComponent, Record<string, unknown>>;
+};
 export type BaseChartConfig = {
     data: ChartData;
     theme?: Partial<ChartTheme>;
     scales?: AxisScaleConfig;
+    responsive?: ResponsiveConfig;
 };
 /**
  * Base chart class that provides common functionality for all chart types
@@ -27,6 +32,7 @@ export declare abstract class BaseChart {
     protected sourceData: ChartData;
     protected readonly theme: ChartTheme;
     protected readonly scaleConfig: AxisScaleConfig;
+    protected readonly responsiveConfig?: ResponsiveConfig;
     protected width: number;
     protected height: number;
     protected xAxis: XAxis | null;
@@ -43,6 +49,7 @@ export declare abstract class BaseChart {
     protected resizeObserver: ResizeObserver | null;
     protected layoutManager: LayoutManager;
     protected plotArea: PlotAreaBounds | null;
+    private disconnectedLegendContainer;
     protected constructor(config: BaseChartConfig);
     /**
      * Adds a component (axis, grid, tooltip, etc.) to the chart
@@ -58,6 +65,13 @@ export declare abstract class BaseChart {
      */
     private performRender;
     protected resolveRenderDimensions(containerRect: DOMRect): RenderDimensions;
+    protected resolveResponsiveContext(context: {
+        width: number;
+        height: number;
+    }): ResponsiveRenderContext;
+    private resolveBreakpointName;
+    private resolveRenderTheme;
+    private applyThemeOverride;
     /**
      * Get layout-aware components in order
      * Override in subclasses to provide chart-specific components
@@ -65,7 +79,11 @@ export declare abstract class BaseChart {
     protected getLayoutComponents(): LayoutAwareComponent[];
     protected getExportComponents(): ChartComponent[];
     protected collectExportOverrides(context: ExportRenderContext): Map<ChartComponent, Record<string, unknown>>;
+    protected collectResponsiveOverrides(context: ResponsiveRenderContext): ResponsiveOverrides;
     protected runExportHooks(context: ExportHookContext): void;
+    private mergeComponentOverrideMaps;
+    private createOverrideComponents;
+    protected applyComponentOverrides(overrides: Map<ChartComponent, ChartComponent>): () => void;
     private renderExportChart;
     protected prepareLayout(): void;
     /**
@@ -77,6 +95,13 @@ export declare abstract class BaseChart {
      */
     protected abstract renderChart(): void;
     protected abstract createExportChart(): BaseChart;
+    protected getLegendSeries(): LegendSeries[];
+    getLegendItems(): LegendItem[];
+    isLegendSeriesVisible(dataKey: string): boolean;
+    setLegendSeriesVisible(dataKey: string, visible: boolean): this;
+    toggleLegendSeries(dataKey: string): this;
+    setLegendVisibility(visibility: Record<string, boolean>): this;
+    onLegendChange(callback: () => void): () => void;
     /**
      * Updates the chart with new data
      */
@@ -85,6 +110,9 @@ export declare abstract class BaseChart {
      * Destroys the chart and cleans up resources
      */
     destroy(): void;
+    private renderDisconnectedLegend;
+    private resolveDisconnectedLegendHost;
+    private cleanupDisconnectedLegendContainer;
     protected parseValue(value: unknown): number;
     /**
      * Exports the chart in the specified format

package/base-chart.js

@@ -7,6 +7,7 @@ import { exportRasterBlob } from './export-image.js';
 import { exportXLSXBlob } from './export-xlsx.js';
 import { exportPDFBlob } from './export-pdf.js';
 import { normalizeChartData } from './grouped-data.js';
+import { mergeDeep } from './utils.js';
 /**
  * Base chart class that provides common functionality for all chart types
  */
@@ -36,6 +37,12 @@ export class BaseChart {
             writable: true,
             value: void 0
         });
+        Object.defineProperty(this, "responsiveConfig", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
         Object.defineProperty(this, "width", {
             enumerable: true,
             configurable: true,
@@ -132,6 +139,12 @@ export class BaseChart {
             writable: true,
             value: null
         });
+        Object.defineProperty(this, "disconnectedLegendContainer", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: null
+        });
         const normalized = normalizeChartData(config.data);
         ChartValidator.validateData(normalized.data);
         this.sourceData = config.data;
@@ -140,6 +153,7 @@ export class BaseChart {
         this.width = this.theme.width;
         this.height = this.theme.height;
         this.scaleConfig = config.scales || {};
+        this.responsiveConfig = config.responsive;
         this.layoutManager = new LayoutManager(this.theme);
     }
     /**
@@ -147,6 +161,7 @@ export class BaseChart {
      */
     render(target) {
         const container = this.resolveContainer(target);
+        this.cleanupDisconnectedLegendContainer();
         this.container = container;
         container.innerHTML = '';
         // Perform initial render
@@ -178,27 +193,45 @@ export class BaseChart {
         const dimensions = this.resolveRenderDimensions(this.container.getBoundingClientRect());
         this.width = dimensions.width;
         this.height = dimensions.height;
-        // Clear and setup SVG
-        this.container.innerHTML = '';
-        this.svg = create('svg')
-            .attr('width', '100%')
-            .attr('height', dimensions.svgHeightAttr)
-            .style('display', 'block');
-        this.container.appendChild(this.svg.node());
-        this.prepareLayout();
-        // Calculate layout
-        const layoutTheme = {
-            ...this.theme,
+        const sizeContext = {
             width: this.width,
             height: this.height,
         };
-        this.layoutManager = new LayoutManager(layoutTheme);
-        const components = this.getLayoutComponents();
-        this.plotArea = this.layoutManager.calculateLayout(components);
-        // Create plot group
-        this.plotGroup = this.svg.append('g').attr('class', 'chart-plot');
-        // Render chart content
-        this.renderChart();
+        const responsiveContext = this.resolveResponsiveContext(sizeContext);
+        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.applyThemeOverride(renderTheme);
+        try {
+            // Clear and setup SVG
+            this.container.innerHTML = '';
+            this.svg = create('svg')
+                .attr('width', '100%')
+                .attr('height', dimensions.svgHeightAttr)
+                .style('display', 'block');
+            this.container.appendChild(this.svg.node());
+            this.prepareLayout();
+            // Calculate layout
+            const layoutTheme = {
+                ...this.theme,
+                width: this.width,
+                height: this.height,
+            };
+            this.layoutManager = new LayoutManager(layoutTheme);
+            const components = this.getLayoutComponents();
+            this.plotArea = this.layoutManager.calculateLayout(components);
+            // Create plot group
+            this.plotGroup = this.svg.append('g').attr('class', 'chart-plot');
+            // Render chart content
+            this.renderChart();
+            this.renderDisconnectedLegend();
+        }
+        finally {
+            restoreComponents();
+            restoreTheme();
+        }
     }
     resolveRenderDimensions(containerRect) {
         const width = containerRect.width || this.theme.width;
@@ -209,6 +242,44 @@ export class BaseChart {
             svgHeightAttr: '100%',
         };
     }
+    resolveResponsiveContext(context) {
+        return {
+            ...context,
+            breakpoint: this.resolveBreakpointName(context.width),
+        };
+    }
+    resolveBreakpointName(width) {
+        const breakpoints = this.responsiveConfig?.breakpoints;
+        if (!breakpoints) {
+            return null;
+        }
+        const sorted = Object.entries(breakpoints)
+            .filter(([, minWidth]) => Number.isFinite(minWidth))
+            .sort((a, b) => a[1] - b[1]);
+        let active = null;
+        sorted.forEach(([name, minWidth]) => {
+            if (width >= minWidth) {
+                active = name;
+            }
+        });
+        return active;
+    }
+    resolveRenderTheme(responsiveOverrides) {
+        if (!responsiveOverrides.theme) {
+            return this.theme;
+        }
+        return mergeDeep(this.theme, responsiveOverrides.theme);
+    }
+    applyThemeOverride(theme) {
+        if (theme === this.theme) {
+            return () => { };
+        }
+        const originalTheme = this.theme;
+        this.theme = theme;
+        return () => {
+            this.theme = originalTheme;
+        };
+    }
     /**
      * Get layout-aware components in order
      * Override in subclasses to provide chart-specific components
@@ -224,7 +295,7 @@ export class BaseChart {
         if (this.yAxis) {
             components.push(this.yAxis);
         }
-        if (this.legend) {
+        if (this.legend?.isInlineMode()) {
             components.push(this.legend);
         }
         return components;
@@ -266,12 +337,120 @@ export class BaseChart {
         });
         return overrides;
     }
+    collectResponsiveOverrides(context) {
+        const beforeRender = this.responsiveConfig?.beforeRender;
+        const components = this.getExportComponents();
+        const componentOverrides = new Map();
+        if (!beforeRender) {
+            return {
+                components: componentOverrides,
+            };
+        }
+        const snapshots = components.map((component, index) => {
+            const exportable = component;
+            const currentConfig = exportable.getExportConfig?.() ?? {};
+            const dataKey = component.dataKey;
+            return {
+                index,
+                type: component.type,
+                dataKey: typeof dataKey === 'string' ? dataKey : undefined,
+                currentConfig,
+            };
+        });
+        const result = beforeRender(context, {
+            theme: this.theme,
+            components: snapshots,
+        });
+        if (!result || typeof result !== 'object') {
+            return {
+                components: componentOverrides,
+            };
+        }
+        result.components?.forEach((entry) => {
+            const match = entry.match ?? {};
+            const override = entry.override;
+            if (!override || typeof override !== 'object') {
+                return;
+            }
+            components.forEach((component, index) => {
+                const dataKey = component.dataKey;
+                const matchesIndex = match.index === undefined || match.index === index;
+                const matchesType = match.type === undefined || match.type === component.type;
+                const matchesDataKey = match.dataKey === undefined ||
+                    (typeof dataKey === 'string' && dataKey === match.dataKey);
+                if (!matchesIndex || !matchesType || !matchesDataKey) {
+                    return;
+                }
+                const existing = componentOverrides.get(component);
+                componentOverrides.set(component, existing ? mergeDeep(existing, override) : { ...override });
+            });
+        });
+        return {
+            theme: result.theme,
+            components: componentOverrides,
+        };
+    }
     runExportHooks(context) {
         const components = this.getExportComponents();
         components.forEach((component) => {
             component.exportHooks?.before?.call(component, context);
         });
     }
+    mergeComponentOverrideMaps(...maps) {
+        const merged = new Map();
+        maps.forEach((map) => {
+            map.forEach((override, component) => {
+                const existing = merged.get(component);
+                merged.set(component, existing ? mergeDeep(existing, override) : { ...override });
+            });
+        });
+        return merged;
+    }
+    createOverrideComponents(overrides) {
+        const overrideComponents = new Map();
+        overrides.forEach((override, component) => {
+            const exportable = component;
+            if (!exportable.createExportComponent) {
+                return;
+            }
+            overrideComponents.set(component, exportable.createExportComponent(override));
+        });
+        return overrideComponents;
+    }
+    applyComponentOverrides(overrides) {
+        if (overrides.size === 0) {
+            return () => { };
+        }
+        const previousState = {
+            title: this.title,
+            grid: this.grid,
+            xAxis: this.xAxis,
+            yAxis: this.yAxis,
+            tooltip: this.tooltip,
+            legend: this.legend,
+        };
+        const resolve = (component) => {
+            if (!component) {
+                return component;
+            }
+            const override = overrides.get(component);
+            return override ?? component;
+        };
+        this.title = resolve(this.title);
+        this.grid = resolve(this.grid);
+        this.xAxis = resolve(this.xAxis);
+        this.yAxis = resolve(this.yAxis);
+        this.tooltip = resolve(this.tooltip);
+        this.legend = resolve(this.legend);
+        return () => {
+            this.title = previousState.title;
+            this.grid = previousState.grid;
+            this.xAxis = previousState.xAxis;
+            this.yAxis = previousState.yAxis;
+            this.tooltip = previousState.tooltip;
+            this.legend = previousState.legend;
+        };
+    }
     renderExportChart(chart, width, height) {
         const container = document.createElement('div');
         const containerId = `chart-export-${Math.random()
@@ -310,6 +489,45 @@ export class BaseChart {
         this.resizeObserver = new ResizeObserver(() => this.performRender());
         this.resizeObserver.observe(this.container);
     }
+    getLegendSeries() {
+        return [];
+    }
+    getLegendItems() {
+        if (!this.legend) {
+            return [];
+        }
+        return this.getLegendSeries().map((series) => {
+            return {
+                dataKey: series.dataKey,
+                color: series.stroke || series.fill || '#8884d8',
+                visible: this.legend.isSeriesVisible(series.dataKey),
+            };
+        });
+    }
+    isLegendSeriesVisible(dataKey) {
+        if (!this.legend) {
+            return true;
+        }
+        return this.legend.isSeriesVisible(dataKey);
+    }
+    setLegendSeriesVisible(dataKey, visible) {
+        this.legend?.setSeriesVisible(dataKey, visible);
+        return this;
+    }
+    toggleLegendSeries(dataKey) {
+        this.legend?.toggleSeries(dataKey);
+        return this;
+    }
+    setLegendVisibility(visibility) {
+        this.legend?.setVisibilityMap(visibility);
+        return this;
+    }
+    onLegendChange(callback) {
+        if (!this.legend) {
+            return () => { };
+        }
+        return this.legend.subscribe(callback);
+    }
     /**
      * Updates the chart with new data
      */
@@ -335,12 +553,82 @@ export class BaseChart {
         if (this.container) {
             this.container.innerHTML = '';
         }
+        this.cleanupDisconnectedLegendContainer();
         this.svg = null;
         this.plotGroup = null;
         this.plotArea = null;
         this.x = null;
         this.y = null;
     }
+    renderDisconnectedLegend() {
+        if (!this.legend || !this.svg || !this.container) {
+            this.cleanupDisconnectedLegendContainer();
+            return;
+        }
+        if (!this.legend.isDisconnectedMode()) {
+            this.cleanupDisconnectedLegendContainer();
+            return;
+        }
+        const series = this.getLegendSeries();
+        if (!series.length) {
+            this.cleanupDisconnectedLegendContainer();
+            return;
+        }
+        const legendHost = this.resolveDisconnectedLegendHost();
+        if (!legendHost) {
+            this.cleanupDisconnectedLegendContainer();
+            return;
+        }
+        legendHost.innerHTML = '';
+        const legendSvg = create('svg')
+            .attr('width', '100%')
+            .style('display', 'block');
+        legendHost.appendChild(legendSvg.node());
+        const svgNode = legendSvg.node();
+        if (!svgNode) {
+            return;
+        }
+        this.legend.estimateLayoutSpace(series, this.theme, this.width, svgNode);
+        const legendHeight = Math.max(1, this.legend.getMeasuredHeight());
+        legendSvg.attr('height', legendHeight);
+        this.legend.render(legendSvg, series, this.theme, this.width);
+    }
+    resolveDisconnectedLegendHost() {
+        if (!this.legend || !this.container) {
+            return null;
+        }
+        const customTarget = this.legend.getDisconnectedTarget();
+        if (customTarget instanceof HTMLElement) {
+            this.disconnectedLegendContainer = customTarget;
+            return customTarget;
+        }
+        if (typeof customTarget === 'string') {
+            const target = document.querySelector(customTarget);
+            if (target instanceof HTMLElement) {
+                this.disconnectedLegendContainer = target;
+                return target;
+            }
+        }
+        if (!this.disconnectedLegendContainer) {
+            const autoContainer = document.createElement('div');
+            autoContainer.className = 'chart-disconnected-legend';
+            this.container.insertAdjacentElement('afterend', autoContainer);
+            this.disconnectedLegendContainer = autoContainer;
+        }
+        return this.disconnectedLegendContainer;
+    }
+    cleanupDisconnectedLegendContainer() {
+        if (!this.disconnectedLegendContainer) {
+            return;
+        }
+        if (this.disconnectedLegendContainer.classList.contains('chart-disconnected-legend')) {
+            this.disconnectedLegendContainer.remove();
+        }
+        else {
+            this.disconnectedLegendContainer.innerHTML = '';
+        }
+        this.disconnectedLegendContainer = null;
+    }
     parseValue(value) {
         if (typeof value === 'string') {
             return parseFloat(value);
@@ -387,7 +675,9 @@ export class BaseChart {
      */
     downloadContent(content, format, options) {
         const mimeType = this.getMimeType(format);
-        const blob = content instanceof Blob ? content : new Blob([content], { type: mimeType });
+        const blob = content instanceof Blob
+            ? content
+            : new Blob([content], { type: mimeType });
         const filename = options.filename || `chart.${format}`;
         const url = URL.createObjectURL(blob);
         const link = document.createElement('a');
@@ -434,7 +724,8 @@ export class BaseChart {
     async exportImage(format, options) {
         const { width, height } = this.exportSize(options);
         const svg = this.exportSVG(options, format);
-        const backgroundColor = options?.backgroundColor ?? (format === 'jpg' ? '#ffffff' : undefined);
+        const backgroundColor = options?.backgroundColor ??
+            (format === 'jpg' ? '#ffffff' : undefined);
         return exportRasterBlob({
             format,
             svg,

package/donut-center-content.js

@@ -67,7 +67,8 @@ export class DonutCenterContent {
             const style = this.config.mainValueStyle;
             elements.push({
                 text: this.mainValue,
-                fontSize: (style?.fontSize ?? defaults.mainValue.fontSize) * fontScale,
+                fontSize: (style?.fontSize ?? defaults.mainValue.fontSize) *
+                    fontScale,
                 fontWeight: style?.fontWeight ?? defaults.mainValue.fontWeight,
                 fontFamily: style?.fontFamily ??
                     defaults.mainValue.fontFamily ??

package/donut-chart.d.ts

@@ -1,4 +1,4 @@
-import type { DataItem } from './types.js';
+import type { DataItem, LegendSeries } from './types.js';
 import { BaseChart, type BaseChartConfig } from './base-chart.js';
 import type { ChartComponent, LayoutAwareComponent } from './chart-interface.js';
 export type DonutConfig = {
@@ -28,9 +28,10 @@ export declare class DonutChart extends BaseChart {
     protected getLayoutComponents(): LayoutAwareComponent[];
     protected prepareLayout(): void;
     protected createExportChart(): BaseChart;
+    protected applyComponentOverrides(overrides: Map<ChartComponent, ChartComponent>): () => void;
     protected renderChart(): void;
     private resolveFontScale;
-    private getLegendSeries;
+    protected getLegendSeries(): LegendSeries[];
     private positionTooltip;
     private buildTooltipContent;
     private renderSegments;