@internetstiftelsen/charts 0.2.0 → 0.3.0

package/README.md

@@ -4,15 +4,14 @@ A framework-agnostic, composable charting library built on D3.js with TypeScript
 
 ## Features
 
-- **Framework Agnostic**: Core library has zero framework dependencies - works with vanilla JS, React, Vue, Svelte, or any other framework
-- **Flexible Scale System**: Support for band, linear, time, and logarithmic scales
-- **Composable Architecture**: Build charts by composing components (lines, axes, grids, tooltips, legends, titles)
-- **Layout-Driven Design**: Components self-measure and automatically adjust chart dimensions
-- **Automatic Resize**: Built-in ResizeObserver handles responsive behavior automatically
-- **Type Safe**: Written in TypeScript with comprehensive type definitions
-- **Data Validation**: Built-in validation with helpful error messages
-- **Performance Optimized**: Data caching and minimized redundant calculations
-- **Automatic Color Assignment**: Smart color palette system with sensible defaults
+- **Framework Agnostic** - Works with vanilla JS, React, Vue, Svelte, or any framework
+- **Composable Architecture** - Build charts by composing components
+- **Multiple Chart Types** - XYChart (lines, bars) and DonutChart
+- **Flexible Scales** - Band, linear, time, and logarithmic scales
+- **Auto Resize** - Built-in ResizeObserver handles responsive behavior
+- **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
 
 ## Installation
 
@@ -22,396 +21,41 @@ npm install @internetstiftelsen/charts
 
 ## Quick Start
 
-### Vanilla JavaScript
-
 ```javascript
 import { XYChart } from '@internetstiftelsen/charts/xy-chart';
 import { Line } from '@internetstiftelsen/charts/line';
-import { Bar } from '@internetstiftelsen/charts/bar';
 import { XAxis } from '@internetstiftelsen/charts/x-axis';
 import { YAxis } from '@internetstiftelsen/charts/y-axis';
-import { Grid } from '@internetstiftelsen/charts/grid';
-import { Tooltip } from '@internetstiftelsen/charts/tooltip';
-import { Legend } from '@internetstiftelsen/charts/legend';
 
-// Your data
 const data = [
-    { date: '2010', revenue: 100, expenses: 80 },
-    { date: '2011', revenue: 150, expenses: 90 },
-    { date: '2012', revenue: 200, expenses: 110 },
-    { date: '2013', revenue: 250, expenses: 130 },
+    { date: '2023', revenue: 100, expenses: 80 },
+    { date: '2024', revenue: 150, expenses: 90 },
 ];
 
-// Create chart
 const chart = new XYChart({ data });
 
-// Add components
 chart
-    .addChild(new Title({ text: 'Revenue vs Expenses' }))
-    .addChild(new Grid({ horizontal: true, vertical: false }))
     .addChild(new XAxis({ dataKey: 'date' }))
     .addChild(new YAxis())
-    .addChild(
-        new Tooltip({
-            formatter: (dataKey, value) => `<strong>${dataKey}</strong>: $${value}k`,
-        })
-    )
-    .addChild(new Legend({ position: 'bottom' }))
-    .addChild(new Line({ dataKey: 'revenue' }))  // Auto-assigned color
-    .addChild(new Line({ dataKey: 'expenses' })); // Auto-assigned color
+    .addChild(new Line({ dataKey: 'revenue' }))
+    .addChild(new Line({ dataKey: 'expenses' }));
 
-// Render to DOM (automatically resizes with container)
 chart.render('#chart-container');
-
-// Later: update with new data
-chart.update(newData);
-
-// Clean up when done
-chart.destroy();
-```
-
-### With React (Demo Wrapper)
-
-```jsx
-import { useRef, useEffect } from 'react';
-import { XYChart, Line, Bar, XAxis, YAxis, Grid, Tooltip, Legend } from './charts';
-
-function Chart({ data }) {
-    const containerRef = useRef(null);
-    const chartRef = useRef(null);
-
-    useEffect(() => {
-        if (containerRef.current) {
-            // Create chart
-            const chart = new XYChart({ data });
-
-            chart
-                .addChild(new Grid({ horizontal: true }))
-                .addChild(new XAxis({ dataKey: 'column' }))
-                .addChild(new YAxis())
-                .addChild(new Tooltip())
-                .addChild(new Legend({ position: 'bottom' }))
-                .addChild(new Line({ dataKey: 'value1' }))
-                .addChild(new Line({ dataKey: 'value2' }));
-
-            chart.render(containerRef.current);
-            chartRef.current = chart;
-
-            return () => {
-                chart.destroy();
-            };
-        }
-    }, []);
-
-    // Update when data changes
-    useEffect(() => {
-        if (chartRef.current && data) {
-            chartRef.current.update(data);
-        }
-    }, [data]);
-
-    return <div ref={containerRef} />;
-}
-```
-
-## API Reference
-
-### XYChart
-
-The main chart class for creating XY-coordinate charts (line, bar, or mixed).
-
-#### Constructor
-
-```typescript
-new XYChart(config: XYChartConfig)
 ```
 
-**Config Options:**
-
-- `data: DataItem[]` - Array of data objects (required)
-- `theme?: Partial<ChartTheme>` - Theme customization
-    - `width: number` - Chart max-width in pixels (default: 928)
-    - `height: number` - Chart height in pixels (default: 600)
-    - `margins: { top, right, bottom, left }` - Base margins around plot area (default: { top: 20, right: 20, bottom: 30, left: 40 })
-    - `colorPalette: string[]` - Array of colors for auto-assignment
-    - `gridColor: string` - Grid line color (default: '#e0e0e0')
-    - `axis: { fontFamily, fontSize }` - Axis text styling
-- `scales?: AxisScaleConfig` - Scale configuration
-    - `x?: { type: 'band' | 'linear' | 'time' | 'log', domain?: any[], padding?: number, nice?: boolean }`
-    - `y?: { type: 'band' | 'linear' | 'time' | 'log', domain?: any[], padding?: number, nice?: boolean }`
-
-#### Methods
+## Documentation
 
-**`addChild(component: ChartComponent): this`**
-Adds a component to the chart (chainable).
-
-**`render(target: string): HTMLElement`**
-Renders the chart to a DOM element specified by CSS selector. Automatically sets up resize handling.
-
-**`update(data: DataItem[]): void`**
-Updates the chart with new data and re-renders.
-
-**`destroy(): void`**
-Cleans up all resources, removes resize observer, and clears the chart from the DOM.
-
-### Components
-
-#### Line
-
-Renders a line series on the chart.
-
-```typescript
-new Line({
-    dataKey: string,          // Key in data objects for Y values (required)
-    stroke? : string,          // Line color (auto-assigned if omitted)
-    strokeWidth? : number,     // Line width in pixels (default: 2)
-})
-```
-
-#### Bar
-
-Renders a bar series on the chart.
-
-```typescript
-new Bar({
-    dataKey: string,          // Key in data objects for Y values (required)
-    fill? : string,            // Bar color (auto-assigned if omitted)
-})
-```
-
-#### XAxis
-
-Renders the X axis.
-
-```typescript
-new XAxis({
-    dataKey? : string,  // Key in data objects for X values (auto-detected if omitted)
-})
-```
-
-#### YAxis
-
-Renders the Y axis.
-
-```typescript
-new YAxis({
-    tickFormat?: string | null,  // D3 format specifier (e.g., 's' for SI-prefix like "35k"). Default: null (no formatting)
-})
-```
-
-**Examples:**
-```javascript
-new YAxis()                         // Shows raw numbers: 35000
-new YAxis({ tickFormat: 's' })      // Shows SI-prefix: 35k
-new YAxis({ tickFormat: '$,' })     // Shows formatted: $35,000
-```
-
-#### Grid
-
-Renders grid lines.
-
-```typescript
-new Grid({
-    horizontal? : boolean,  // Show horizontal lines (default: true)
-    vertical? : boolean,    // Show vertical lines (default: true)
-})
-```
-
-#### Tooltip
-
-Renders interactive tooltips on hover.
-
-```typescript
-new Tooltip({
-    formatter? : (dataKey: string, value: any, data: DataItem) => string
-})
-```
-
-**Example formatter:**
-
-```javascript
-new Tooltip({
-    formatter: (dataKey, value, data) =>
-        `<strong>${dataKey}</strong><br/>Value: ${value}<br/>Date: ${data.date}`
-})
-```
-
-#### Legend
-
-Renders a legend for the chart.
-
-```typescript
-new Legend({
-    position?: 'bottom',      // Position (currently only 'bottom' supported)
-    marginTop?: number,       // Space above legend (default: 20)
-    marginBottom?: number,    // Space below legend (default: 10)
-})
-```
-
-#### Title
-
-Renders a title for the chart.
-
-```typescript
-new Title({
-    text: string,             // Title text (required)
-    fontSize?: number,        // Font size in pixels (default: 18)
-    fontWeight?: string,      // Font weight (default: 'bold')
-    align?: 'left' | 'center' | 'right',  // Alignment (default: 'center')
-    marginTop?: number,       // Space above title (default: 10)
-    marginBottom?: number,    // Space below title (default: 15)
-})
-```
-
-## Advanced Usage
-
-### Custom Scale Types
-
-Use time scales for temporal data:
-
-```javascript
-const chart = new XYChart({
-    data: [
-        { date: new Date('2024-01-01'), value: 100 },
-        { date: new Date('2024-01-02'), value: 150 },
-    ],
-    scales: {
-        x: { type: 'time', nice: true },
-        y: { type: 'linear', nice: true },
-    },
-});
-```
-
-Use logarithmic scales for exponential data:
-
-```javascript
-const chart = new XYChart({
-    data: [
-        { x: 1, y: 10 },
-        { x: 2, y: 100 },
-        { x: 3, y: 1000 },
-    ],
-    scales: {
-        y: { type: 'log', domain: [1, 10000] },
-    },
-});
-```
-
-### Custom Theming
-
-```javascript
-const chart = new XYChart({
-    data,
-    theme: {
-        width: 1200,           // Max-width (chart won't exceed this)
-        height: 600,
-        margins: {
-            top: 30,
-            right: 30,
-            bottom: 40,
-            left: 60,
-        },
-        colorPalette: ['#ff6b6b', '#4ecdc4', '#45b7d1', '#f7b731'],
-        gridColor: '#333333',
-        axis: {
-            fontFamily: 'Inter, sans-serif',
-            fontSize: '12',
-        },
-    },
-});
-```
-
-### Manual Color Assignment
-
-```javascript
-chart
-    .addChild(new Line({ dataKey: 'revenue', stroke: '#00ff00' }))
-    .addChild(new Line({ dataKey: 'expenses', stroke: '#ff0000' }));
-```
-
-### Responsive Charts
-
-Charts automatically resize with their container using ResizeObserver. The chart width adapts to the container up to the `theme.width` (which acts as max-width).
-
-```javascript
-// Container width: 500px → Chart width: 500px
-// Container width: 1200px → Chart width: 928px (theme default max-width)
-
-// Custom max-width
-const chart = new XYChart({
-    data,
-    theme: { width: 1200 },  // Chart won't exceed 1200px
-});
-```
-
-**No manual resize calls needed** - the chart automatically responds to container size changes!
-
-## Data Validation
-
-The library includes built-in validation with helpful error messages:
-
-```javascript
-// Empty data
-new XYChart({ data: [] });
-// Error: Data array cannot be empty
-
-// Missing dataKey
-new Line({ dataKey: 'nonexistent' });
-// Error: Line: dataKey "nonexistent" not found in data items at indices: 0, 1, 2
-
-// Invalid numeric data
-new Line({ dataKey: 'textField' });
-// Error: Line: No valid numeric values found for dataKey "textField"
-```
+- [Getting Started](./docs/getting-started.md) - Installation, Vanilla JS, React integration
+- [XYChart](./docs/xy-chart.md) - Line and bar charts API
+- [DonutChart](./docs/donut-chart.md) - Donut/pie charts 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
 
 Modern browsers with ES6+ support. Uses D3.js v7.
 
-## TypeScript
-
-Full TypeScript support included:
-
-```typescript
-import type { DataItem, ChartTheme, LineConfig } from './charts/types';
-
-const data: DataItem[] = [
-    { x: 1, y: 100 },
-    { x: 2, y: 200 },
-];
-
-const config: LineConfig = {
-    dataKey: 'y',
-    stroke: '#8884d8',
-    strokeWidth: 2,
-};
-```
-
-## Architecture
-
-The library follows a composable, layout-driven design:
-
-- **BaseChart**: Abstract base class providing common functionality (lifecycle, rendering, validation)
-- **XYChart**: Concrete implementation for XY-coordinate charts (lines, bars, or mixed)
-- **LayoutManager**: Calculates component positions and plot area dimensions (D3 margin convention)
-- **LayoutAwareComponent**: Interface for self-measuring components (Title, Legend, Axes)
-- **Components**: Modular components that implement `ChartComponent` or `LayoutAwareComponent`
-- **Validation**: Centralized validation layer with `ChartValidator`
-- **Scales**: Flexible scale factory supporting multiple D3 scale types
-
-Key principles:
-- **Layout-driven**: Components report their space requirements, plot area adjusts automatically
-- **Separation of concerns**: Only the plot area (grid) scales; UI elements stay fixed size
-- **D3 conventions**: Follows D3's margin convention pattern for clean, predictable layouts
-
-This architecture makes it easy to add new chart types or series (Area, Scatter, etc.) by extending BaseChart or implementing new series components.
-
-## Performance
+## License
 
-- **Data Caching**: Sorted data is cached to avoid redundant sorting operations
-- **Smart Re-rendering**: Only re-renders when necessary (data updates or container resize)
-- **Automatic Cleanup**: ResizeObserver and tooltips properly cleaned up on destroy
-- **Minimal DOM Manipulation**: Uses D3's efficient data binding
-- **SVG Optimization**: Clean SVG generation with proper cleanup
-- **Small Bundle**: ~105 KB gzipped (including D3)
-- **Small Bundle**: ~105 KB gzipped (including D3)
+MIT

package/base-chart.d.ts

@@ -1,6 +1,6 @@
 import { type Selection } from 'd3';
 import type { DataItem, ChartTheme, AxisScaleConfig, ExportFormat, ExportOptions, D3Scale } from './types.js';
-import type { ChartComponent } from './chart-interface.js';
+import type { ChartComponent, LayoutAwareComponent } from './chart-interface.js';
 import type { XAxis } from './x-axis.js';
 import type { YAxis } from './y-axis.js';
 import type { Grid } from './grid.js';
@@ -50,8 +50,9 @@ export declare abstract class BaseChart {
     private performRender;
     /**
      * Get layout-aware components in order
+     * Override in subclasses to provide chart-specific components
      */
-    private getLayoutComponents;
+    protected getLayoutComponents(): LayoutAwareComponent[];
     /**
      * Setup ResizeObserver for automatic resize handling
      */

package/base-chart.js

@@ -167,6 +167,7 @@ export class BaseChart {
     }
     /**
      * Get layout-aware components in order
+     * Override in subclasses to provide chart-specific components
      */
     getLayoutComponents() {
         const components = [];

package/chart-interface.d.ts

@@ -1,5 +1,5 @@
 export interface ChartComponent {
-    type: 'line' | 'bar' | 'xAxis' | 'yAxis' | 'grid' | 'tooltip' | 'legend' | 'title';
+    type: 'line' | 'bar' | 'xAxis' | 'yAxis' | 'grid' | 'tooltip' | 'legend' | 'title' | 'donutCenterContent';
 }
 export type ComponentSpace = {
     width: number;

package/donut-center-content.d.ts

@@ -0,0 +1,27 @@
+import { type Selection } from 'd3';
+import type { ChartTheme } from './types.js';
+import type { ChartComponent } from './chart-interface.js';
+type TextStyle = {
+    fontSize?: number;
+    fontWeight?: string;
+    fontFamily?: string;
+    color?: string;
+};
+export type DonutCenterContentConfig = {
+    mainValue?: string;
+    title?: string;
+    subtitle?: string;
+    mainValueStyle?: TextStyle;
+    titleStyle?: TextStyle;
+    subtitleStyle?: TextStyle;
+};
+export declare class DonutCenterContent implements ChartComponent {
+    readonly type: "donutCenterContent";
+    readonly mainValue?: string;
+    readonly title?: string;
+    readonly subtitle?: string;
+    private readonly config;
+    constructor(config?: DonutCenterContentConfig);
+    render(svg: Selection<SVGSVGElement, undefined, null, undefined>, cx: number, cy: number, theme: ChartTheme): void;
+}
+export {};

package/donut-center-content.js

@@ -0,0 +1,98 @@
+export class DonutCenterContent {
+    constructor(config = {}) {
+        Object.defineProperty(this, "type", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: 'donutCenterContent'
+        });
+        Object.defineProperty(this, "mainValue", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "title", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "subtitle", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "config", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        this.mainValue = config.mainValue;
+        this.title = config.title;
+        this.subtitle = config.subtitle;
+        this.config = config;
+    }
+    render(svg, cx, cy, theme) {
+        const defaults = theme.donut.centerContent;
+        const elements = [];
+        if (this.mainValue) {
+            const style = this.config.mainValueStyle;
+            elements.push({
+                text: this.mainValue,
+                fontSize: style?.fontSize ?? defaults.mainValue.fontSize,
+                fontWeight: style?.fontWeight ?? defaults.mainValue.fontWeight,
+                fontFamily: style?.fontFamily ??
+                    defaults.mainValue.fontFamily ??
+                    theme.fontFamily,
+                color: style?.color ?? defaults.mainValue.color,
+            });
+        }
+        if (this.title) {
+            const style = this.config.titleStyle;
+            elements.push({
+                text: this.title,
+                fontSize: style?.fontSize ?? defaults.title.fontSize,
+                fontWeight: style?.fontWeight ?? defaults.title.fontWeight,
+                fontFamily: style?.fontFamily ??
+                    defaults.title.fontFamily ??
+                    theme.fontFamily,
+                color: style?.color ?? defaults.title.color,
+            });
+        }
+        if (this.subtitle) {
+            const style = this.config.subtitleStyle;
+            elements.push({
+                text: this.subtitle,
+                fontSize: style?.fontSize ?? defaults.subtitle.fontSize,
+                fontWeight: style?.fontWeight ?? defaults.subtitle.fontWeight,
+                fontFamily: style?.fontFamily ??
+                    defaults.subtitle.fontFamily ??
+                    theme.fontFamily,
+                color: style?.color ?? defaults.subtitle.color,
+            });
+        }
+        if (elements.length === 0)
+            return;
+        const lineSpacing = 6;
+        const totalHeight = elements.reduce((sum, el, i) => sum + el.fontSize + (i < elements.length - 1 ? lineSpacing : 0), 0);
+        const group = svg.append('g').attr('class', 'donut-center-content');
+        let currentY = cy - totalHeight / 2;
+        for (const el of elements) {
+            group
+                .append('text')
+                .attr('x', cx)
+                .attr('y', currentY + el.fontSize / 2)
+                .attr('text-anchor', 'middle')
+                .attr('dominant-baseline', 'middle')
+                .style('font-size', `${el.fontSize}px`)
+                .style('font-weight', el.fontWeight)
+                .style('font-family', el.fontFamily)
+                .style('fill', el.color)
+                .text(el.text);
+            currentY += el.fontSize + lineSpacing;
+        }
+    }
+}

package/donut-chart.d.ts

@@ -0,0 +1,32 @@
+import type { DataItem } from './types.js';
+import { BaseChart, type BaseChartConfig } from './base-chart.js';
+import type { ChartComponent, LayoutAwareComponent } from './chart-interface.js';
+export type DonutConfig = {
+    innerRadius?: number;
+    padAngle?: number;
+    cornerRadius?: number;
+};
+export type DonutChartConfig = BaseChartConfig & {
+    donut?: DonutConfig;
+    valueKey?: string;
+    labelKey?: string;
+};
+export declare class DonutChart extends BaseChart {
+    private readonly innerRadiusRatio;
+    private readonly padAngle;
+    private readonly cornerRadius;
+    private readonly valueKey;
+    private readonly labelKey;
+    private segments;
+    private centerContent;
+    constructor(config: DonutChartConfig);
+    private validateDonutData;
+    private prepareSegments;
+    addChild(component: ChartComponent): this;
+    update(data: DataItem[]): void;
+    protected getLayoutComponents(): LayoutAwareComponent[];
+    protected renderChart(): void;
+    private positionTooltip;
+    private buildTooltipContent;
+    private renderSegments;
+}

package/donut-chart.js

@@ -0,0 +1,240 @@
+import { arc, pie, select } from 'd3';
+import { BaseChart } from './base-chart.js';
+import { sanitizeForCSS } from './utils.js';
+import { ChartValidator } from './validation.js';
+const HOVER_EXPAND_PX = 8;
+const ANIMATION_DURATION_MS = 150;
+const TOOLTIP_OFFSET_PX = 12;
+const EDGE_MARGIN_PX = 10;
+export class DonutChart extends BaseChart {
+    constructor(config) {
+        super(config);
+        Object.defineProperty(this, "innerRadiusRatio", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "padAngle", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "cornerRadius", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "valueKey", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "labelKey", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "segments", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: []
+        });
+        Object.defineProperty(this, "centerContent", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: null
+        });
+        const donut = config.donut ?? {};
+        this.innerRadiusRatio =
+            donut.innerRadius ?? this.theme.donut.innerRadius;
+        this.padAngle = donut.padAngle ?? this.theme.donut.padAngle;
+        this.cornerRadius = donut.cornerRadius ?? this.theme.donut.cornerRadius;
+        this.valueKey = config.valueKey ?? 'value';
+        this.labelKey = config.labelKey ?? 'name';
+        this.validateDonutData();
+        this.prepareSegments();
+    }
+    validateDonutData() {
+        ChartValidator.validateDataKey(this.data, this.labelKey, 'DonutChart');
+        ChartValidator.validateDataKey(this.data, this.valueKey, 'DonutChart');
+        ChartValidator.validateNumericData(this.data, this.valueKey, 'DonutChart');
+        for (const [index, item] of this.data.entries()) {
+            const value = this.parseValue(item[this.valueKey]);
+            if (value < 0) {
+                throw new Error(`DonutChart: data item at index ${index} has negative value '${item[this.valueKey]}' for key '${this.valueKey}'`);
+            }
+        }
+    }
+    prepareSegments() {
+        this.segments = this.data.map((item, index) => ({
+            label: String(item[this.labelKey]),
+            value: this.parseValue(item[this.valueKey]),
+            color: item.color ||
+                this.theme.colorPalette[index % this.theme.colorPalette.length],
+        }));
+    }
+    addChild(component) {
+        const type = component.type;
+        if (type === 'tooltip') {
+            this.tooltip = component;
+        }
+        else if (type === 'legend') {
+            this.legend = component;
+            this.legend.setToggleCallback(() => this.update(this.data));
+        }
+        else if (type === 'title') {
+            this.title = component;
+        }
+        else if (type === 'donutCenterContent') {
+            this.centerContent = component;
+        }
+        return this;
+    }
+    update(data) {
+        this.data = data;
+        this.validateDonutData();
+        this.prepareSegments();
+        super.update(data);
+    }
+    getLayoutComponents() {
+        const components = [];
+        if (this.title)
+            components.push(this.title);
+        if (this.legend)
+            components.push(this.legend);
+        return components;
+    }
+    renderChart() {
+        if (!this.plotArea || !this.svg || !this.plotGroup) {
+            throw new Error('Plot area not calculated');
+        }
+        if (this.title) {
+            const pos = this.layoutManager.getComponentPosition(this.title);
+            this.title.render(this.svg, this.theme, this.width, pos.x, pos.y);
+        }
+        const visibleSegments = this.legend
+            ? this.segments.filter((seg) => this.legend.isSeriesVisible(seg.label))
+            : this.segments;
+        const cx = this.plotArea.left + this.plotArea.width / 2;
+        const cy = this.plotArea.top + this.plotArea.height / 2;
+        const outerRadius = Math.min(this.plotArea.width, this.plotArea.height) / 2;
+        const innerRadius = outerRadius * this.innerRadiusRatio;
+        this.renderSegments(visibleSegments, cx, cy, innerRadius, outerRadius);
+        if (this.centerContent) {
+            this.centerContent.render(this.svg, cx, cy, this.theme);
+        }
+        if (this.legend) {
+            const pos = this.layoutManager.getComponentPosition(this.legend);
+            const legendSeries = this.segments.map((seg) => ({
+                dataKey: seg.label,
+                fill: seg.color,
+            }));
+            this.legend.render(this.svg, legendSeries, this.theme, this.width, pos.x, pos.y);
+        }
+        if (this.tooltip) {
+            this.tooltip.initialize(this.theme);
+        }
+    }
+    positionTooltip(event, tooltipDiv) {
+        const node = tooltipDiv.node();
+        if (!node)
+            return;
+        const rect = node.getBoundingClientRect();
+        let x = event.pageX + TOOLTIP_OFFSET_PX;
+        let y = event.pageY - rect.height / 2;
+        if (x + rect.width > window.innerWidth - EDGE_MARGIN_PX) {
+            x = event.pageX - rect.width - TOOLTIP_OFFSET_PX;
+        }
+        x = Math.max(EDGE_MARGIN_PX, x);
+        y = Math.max(EDGE_MARGIN_PX, Math.min(y, window.innerHeight +
+            window.scrollY -
+            rect.height -
+            EDGE_MARGIN_PX));
+        tooltipDiv.style('left', `${x}px`).style('top', `${y}px`);
+    }
+    buildTooltipContent(d, segments) {
+        const total = segments.reduce((sum, s) => sum + s.value, 0);
+        const percentage = total > 0 ? ((d.data.value / total) * 100).toFixed(1) : '0.0';
+        const dataItem = this.data.find((item) => String(item[this.labelKey]) === d.data.label);
+        if (this.tooltip?.customFormatter) {
+            return this.tooltip.customFormatter(dataItem || {}, [
+                { dataKey: d.data.label, fill: d.data.color },
+            ]);
+        }
+        if (this.tooltip?.formatter) {
+            return `<strong>${d.data.label}</strong><br/>${this.tooltip.formatter(d.data.label, d.data.value, dataItem || {})}`;
+        }
+        return `<strong>${d.data.label}</strong><br/>${d.data.value} (${percentage}%)`;
+    }
+    renderSegments(segments, cx, cy, innerRadius, outerRadius) {
+        if (!this.plotGroup || !this.svg)
+            return;
+        const pieGenerator = pie()
+            .value((d) => d.value)
+            .padAngle(this.padAngle)
+            .sort(null);
+        const arcGenerator = arc()
+            .innerRadius(innerRadius)
+            .outerRadius(outerRadius)
+            .cornerRadius(this.cornerRadius);
+        const hoverArcGenerator = arc()
+            .innerRadius(innerRadius)
+            .outerRadius(outerRadius + HOVER_EXPAND_PX)
+            .cornerRadius(this.cornerRadius);
+        const pieData = pieGenerator(segments);
+        const segmentGroup = this.plotGroup
+            .append('g')
+            .attr('class', 'donut-segments')
+            .attr('transform', `translate(${cx}, ${cy})`);
+        const tooltipDiv = this.tooltip
+            ? select(`#${this.tooltip.id}`)
+            : null;
+        segmentGroup
+            .selectAll('.donut-segment')
+            .data(pieData)
+            .join('path')
+            .attr('class', (d) => `donut-segment segment-${sanitizeForCSS(d.data.label)}`)
+            .attr('d', arcGenerator)
+            .attr('fill', (d) => d.data.color)
+            .style('cursor', 'pointer')
+            .style('transition', 'opacity 0.15s ease')
+            .on('mouseenter', (event, d) => {
+            select(event.currentTarget)
+                .transition()
+                .duration(ANIMATION_DURATION_MS)
+                .attr('d', hoverArcGenerator(d));
+            segmentGroup
+                .selectAll('.donut-segment')
+                .filter((_, i, nodes) => nodes[i] !== event.currentTarget)
+                .style('opacity', 0.5);
+            if (tooltipDiv && !tooltipDiv.empty()) {
+                tooltipDiv
+                    .style('visibility', 'visible')
+                    .html(this.buildTooltipContent(d, segments));
+                this.positionTooltip(event, tooltipDiv);
+            }
+        })
+            .on('mousemove', (event) => {
+            if (tooltipDiv && !tooltipDiv.empty()) {
+                this.positionTooltip(event, tooltipDiv);
+            }
+        })
+            .on('mouseleave', (event, d) => {
+            select(event.currentTarget)
+                .transition()
+                .duration(ANIMATION_DURATION_MS)
+                .attr('d', arcGenerator(d));
+            segmentGroup.selectAll('.donut-segment').style('opacity', 1);
+            if (tooltipDiv && !tooltipDiv.empty()) {
+                tooltipDiv.style('visibility', 'hidden');
+            }
+        });
+    }
+}

package/legend.d.ts

@@ -1,7 +1,5 @@
 import { type Selection } from 'd3';
-import type { LegendConfig, ChartTheme } from './types.js';
-import type { Line } from './line.js';
-import type { Bar } from './bar.js';
+import type { LegendConfig, ChartTheme, LegendSeries } from './types.js';
 import type { LayoutAwareComponent, ComponentSpace } from './chart-interface.js';
 export declare class Legend implements LayoutAwareComponent {
     readonly type: "legend";
@@ -20,5 +18,5 @@ export declare class Legend implements LayoutAwareComponent {
      * Returns the space required by the legend
      */
     getRequiredSpace(): ComponentSpace;
-    render(svg: Selection<SVGSVGElement, undefined, null, undefined>, series: (Line | Bar)[], theme: ChartTheme, width: number, _x?: number, y?: number): void;
+    render(svg: Selection<SVGSVGElement, undefined, null, undefined>, series: LegendSeries[], theme: ChartTheme, width: number, _x?: number, y?: number): void;
 }

package/package.json

@@ -1,5 +1,5 @@
 {
-    "version": "0.2.0",
+    "version": "0.3.0",
     "name": "@internetstiftelsen/charts",
     "type": "module",
     "sideEffects": false,

package/theme.js

@@ -50,6 +50,28 @@ export const defaultTheme = {
         borderRadius: 4,
         padding: 4,
     },
+    donut: {
+        innerRadius: 0.5,
+        padAngle: 0.02,
+        cornerRadius: 0,
+        centerContent: {
+            mainValue: {
+                fontSize: 32,
+                fontWeight: 'bold',
+                color: '#1f2a36',
+            },
+            title: {
+                fontSize: 14,
+                fontWeight: 'normal',
+                color: '#6b7280',
+            },
+            subtitle: {
+                fontSize: 12,
+                fontWeight: 'normal',
+                color: '#9ca3af',
+            },
+        },
+    },
 };
 export const newspaperTheme = {
     width: 928,
@@ -104,6 +126,28 @@ export const newspaperTheme = {
         borderRadius: 2,
         padding: 3,
     },
+    donut: {
+        innerRadius: 0.5,
+        padAngle: 0.015,
+        cornerRadius: 0,
+        centerContent: {
+            mainValue: {
+                fontSize: 28,
+                fontWeight: 'bold',
+                color: '#1a1a1a',
+            },
+            title: {
+                fontSize: 13,
+                fontWeight: 'normal',
+                color: '#4a4a4a',
+            },
+            subtitle: {
+                fontSize: 11,
+                fontWeight: 'normal',
+                color: '#6b6b6b',
+            },
+        },
+    },
 };
 export const themes = {
     default: defaultTheme,

package/types.d.ts

@@ -50,6 +50,31 @@ export type ChartTheme = {
         borderRadius: number;
         padding: number;
     };
+    donut: {
+        innerRadius: number;
+        padAngle: number;
+        cornerRadius: number;
+        centerContent: {
+            mainValue: {
+                fontSize: number;
+                fontWeight: string;
+                fontFamily?: string;
+                color: string;
+            };
+            title: {
+                fontSize: number;
+                fontWeight: string;
+                fontFamily?: string;
+                color: string;
+            };
+            subtitle: {
+                fontSize: number;
+                fontWeight: string;
+                fontFamily?: string;
+                color: string;
+            };
+        };
+    };
 };
 export type ValueLabelConfig = {
     fontSize?: number;
@@ -126,6 +151,11 @@ export type LegendConfig = {
     marginTop?: number;
     marginBottom?: number;
 };
+export type LegendSeries = {
+    dataKey: string;
+    stroke?: string;
+    fill?: string;
+};
 export type TitleConfig = {
     text: string;
     fontSize?: number;