@internetstiftelsen/charts 0.9.2 → 0.10.1

package/docs/getting-started.md

@@ -0,0 +1,311 @@
+# Getting Started
+
+This guide covers installation and basic usage with Vanilla JavaScript and React.
+
+## Installation
+
+```bash
+npm install @internetstiftelsen/charts
+```
+
+## 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';
+import { Title } from '@internetstiftelsen/charts/title';
+
+// 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 },
+];
+
+// Create chart
+const chart = new XYChart({ data });
+
+// Add components
+chart
+    .addChild(new Title({ text: 'Revenue vs Expenses' }))
+    .addChild(new Grid({ category: false, value: true }))
+    .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
+
+// 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();
+```
+
+## Sizing
+
+By default, charts size themselves from the render container.
+
+```javascript
+const chart = new XYChart({ data });
+chart.render('#chart-container');
+```
+
+For fixed-size charts, set top-level `width` and `height`:
+
+```javascript
+const chart = new XYChart({
+    data,
+    width: 800,
+    height: 400,
+});
+```
+
+## Grouping Charts
+
+```javascript
+import { ChartGroup } from '@internetstiftelsen/charts/chart-group';
+import { XYChart } from '@internetstiftelsen/charts/xy-chart';
+import { Line } from '@internetstiftelsen/charts/line';
+import { Bar } from '@internetstiftelsen/charts/bar';
+import { Legend } from '@internetstiftelsen/charts/legend';
+import { Title } from '@internetstiftelsen/charts/title';
+
+const lineChart = new XYChart({ data: lineData });
+lineChart.addChild(new Line({ dataKey: 'revenue' }));
+
+const barChart = new XYChart({ data: barData });
+barChart.addChild(new Bar({ dataKey: 'revenue' }));
+
+const group = new ChartGroup({
+    cols: 2,
+    gap: 20,
+    height: 420,
+    syncY: true,
+});
+
+group
+    .addChild(new Title({ text: 'Revenue vs Expenses' }))
+    .addChart(barChart)
+    .addChart(lineChart)
+    .addChild(new Legend());
+
+group.render('#chart-group');
+```
+
+Each child chart keeps its own rendering logic, scales, tooltips, and responsive
+behavior. The shared group legend controls matching series keys across all child
+charts, and group height can be fixed with `height` or inherited from the render
+container. Use `syncY: true` when you want visible vertical `XYChart` children
+to share the same Y domain.
+
+`ChartGroup` also supports responsive layout breakpoints at both levels:
+
+- group-level `responsive.breakpoints` can override `cols` and `gap`
+- `addChart(..., options)` can override `span`, `height`, `order`, and `hidden`
+
+These breakpoints use the same `minWidth` / `maxWidth` matching rules as chart
+responsive config, and all matching breakpoints merge in declaration order.
+
+## React Integration
+
+```jsx
+import { useRef, useEffect } from 'react';
+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';
+
+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({ value: 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} />;
+}
+```
+
+## Donut Chart Example
+
+```javascript
+import { DonutChart } from '@internetstiftelsen/charts/donut-chart';
+import { DonutCenterContent } from '@internetstiftelsen/charts/donut-center-content';
+import { Legend } from '@internetstiftelsen/charts/legend';
+import { Tooltip } from '@internetstiftelsen/charts/tooltip';
+
+const data = [
+    { name: 'Desktop', value: 450 },
+    { name: 'Mobile', value: 320 },
+    { name: 'Tablet', value: 130 },
+];
+
+const chart = new DonutChart({
+    data,
+    valueKey: 'value',
+    labelKey: 'name',
+});
+
+chart
+    .addChild(
+        new DonutCenterContent({
+            mainValue: '900',
+            title: 'Total',
+            subtitle: 'visitors',
+        }),
+    )
+    .addChild(new Legend({ position: 'bottom' }))
+    .addChild(new Tooltip());
+
+chart.render('#donut-container');
+```
+
+## Pie Chart Example
+
+```javascript
+import { PieChart } from '@internetstiftelsen/charts/pie-chart';
+import { Legend } from '@internetstiftelsen/charts/legend';
+import { Tooltip } from '@internetstiftelsen/charts/tooltip';
+
+const data = [
+    { name: 'Desktop', value: 450 },
+    { name: 'Mobile', value: 320 },
+    { name: 'Tablet', value: 130 },
+];
+
+const chart = new PieChart({
+    data,
+    valueKey: 'value',
+    labelKey: 'name',
+    pie: {
+        sort: 'none',
+    },
+});
+
+chart.addChild(new Legend({ position: 'bottom' })).addChild(new Tooltip());
+
+chart.render('#pie-container');
+```
+
+## Gauge Chart Example
+
+```javascript
+import { GaugeChart } from '@internetstiftelsen/charts/gauge-chart';
+import { Legend } from '@internetstiftelsen/charts/legend';
+import { Tooltip } from '@internetstiftelsen/charts/tooltip';
+
+const data = [{ label: 'KPI', value: 72, target: 80 }];
+
+const chart = new GaugeChart({
+    data,
+    valueKey: 'value',
+    targetValueKey: 'target',
+    gauge: {
+        min: 0,
+        max: 100,
+        halfCircle: true,
+        segments: [
+            { from: 0, to: 60, color: '#10b981', label: 'Good' },
+            { from: 60, to: 85, color: '#f59e0b', label: 'Warning' },
+            { from: 85, to: 100, color: '#ef4444', label: 'Risk' },
+        ],
+    },
+});
+
+chart.addChild(new Legend({ position: 'bottom' })).addChild(new Tooltip());
+
+chart.render('#gauge-container');
+```
+
+## Word Cloud Example
+
+```javascript
+import { WordCloudChart } from '@internetstiftelsen/charts/word-cloud-chart';
+import { Title } from '@internetstiftelsen/charts/title';
+
+const data = [
+    { word: 'internet', count: 96 },
+    { word: 'social', count: 82 },
+    { word: 'news', count: 75 },
+    { word: 'streaming', count: 68 },
+];
+
+const chart = new WordCloudChart({
+    data,
+    wordCloud: {
+        minWordLength: 3,
+        minValue: 5,
+        minFontSize: 3,
+        maxFontSize: 20,
+        padding: 1,
+        spiral: 'archimedean',
+    },
+});
+
+chart.addChild(new Title({ text: 'Most mentioned words' }));
+
+chart.render('#word-cloud-container');
+```
+
+`minFontSize` and `maxFontSize` are percentages of the smaller plot-area
+dimension and define the relative size range passed into `d3-cloud`. Word
+clouds accept flat `{ word, count }` rows and use theme typography/colors
+directly when laying out and rendering the cloud.
+
+## Next Steps
+
+- [XYChart API](./xy-chart.md) - Line and bar charts
+- [ChartGroup API](./chart-group.md) - Combined chart layouts
+- [WordCloudChart API](./word-cloud-chart.md) - Word clouds and frequency filtering
+- [DonutChart API](./donut-chart.md) - Donut/pie charts
+- [PieChart API](./pie-chart.md) - Pie charts
+- [GaugeChart API](./gauge-chart.md) - Gauge charts
+- [Components](./components.md) - Axes, Grid, Tooltip, Legend, Title
+- [Theming](./theming.md) - Customize colors and styles

package/docs/pie-chart.md

@@ -0,0 +1,123 @@
+# PieChart API
+
+A chart for displaying proportional categorical data as pie slices.
+
+## Constructor
+
+```typescript
+new PieChart(config: PieChartConfig)
+```
+
+### Config Options
+
+| Option       | Type                      | Default   | Description                                                           |
+| ------------ | ------------------------- | --------- | --------------------------------------------------------------------- |
+| `data`       | `DataItem[]`              | required  | Array of data objects                                                 |
+| `width`      | `number`                  | -         | Explicit chart width in pixels                                        |
+| `height`     | `number`                  | -         | Explicit chart height in pixels                                       |
+| `valueKey`   | `string`                  | `'value'` | Key for numeric values in data                                        |
+| `labelKey`   | `string`                  | `'name'`  | Key for segment labels in data                                        |
+| `pie`        | `PieConfig`               | -         | Pie-specific configuration                                            |
+| `valueLabel` | `PieValueLabelConfig`     | -         | On-chart slice label/value rendering configuration                    |
+| `theme`      | `DeepPartial<ChartTheme>` | -         | Theme customization                                                   |
+| `responsive` | `ResponsiveConfig`        | -         | Declarative container-query responsive overrides (theme + components) |
+
+### Pie Config
+
+```typescript
+pie: {
+    innerRadius?: number,   // 0-1, percentage of outer radius (default: 0)
+    startAngle?: number,    // Radians (default: 0)
+    endAngle?: number,      // Radians (default: Math.PI * 2)
+    padAngle?: number,      // Radians between slices (default: theme.donut.padAngle)
+    cornerRadius?: number,  // Corner radius in pixels (default: theme.donut.cornerRadius)
+    sort?: 'none' | 'ascending' | 'descending' | ((a, b) => number),
+}
+```
+
+### ValueLabel Config
+
+```typescript
+valueLabel: {
+    show?: boolean,                 // default: false
+    position?: 'inside' | 'outside' | 'auto', // default: 'auto'
+    minInsidePercentage?: number,   // default: 8
+    outsideOffset?: number,         // default: 16
+    insideMargin?: number,          // default: 8
+    minVerticalSpacing?: number,    // default: 14
+    formatter?: (label, value, data, percentage) => string, // default: `${label}: ${value}`
+}
+```
+
+Rendered pie value-label text defaults to `{label}: {value}` and can be customized with `valueLabel.formatter`. The `percentage` argument is the computed slice share from `0` to `100`.
+
+## Example
+
+```javascript
+import { PieChart } from '@internetstiftelsen/charts/pie-chart';
+import { Legend } from '@internetstiftelsen/charts/legend';
+import { Tooltip } from '@internetstiftelsen/charts/tooltip';
+import { Title } from '@internetstiftelsen/charts/title';
+
+const data = [
+    { name: 'Desktop', value: 450 },
+    { name: 'Mobile', value: 320 },
+    { name: 'Tablet', value: 130 },
+];
+
+const chart = new PieChart({
+    data,
+    valueKey: 'value',
+    labelKey: 'name',
+    pie: {
+        padAngle: 0.02,
+        sort: 'none',
+    },
+    valueLabel: {
+        show: true,
+        position: 'auto',
+        formatter: (label, _value, _data, percentage) =>
+            `${label}: ${percentage.toFixed(1)}%`,
+    },
+});
+
+chart
+    .addChild(new Title({ text: 'Device Distribution' }))
+    .addChild(new Legend({ position: 'bottom' }))
+    .addChild(new Tooltip());
+
+chart.render('#chart-container');
+```
+
+## Responsive Height and Labels
+
+- PieChart uses container-driven `100%` height (same behavior model as width).
+- Set an explicit container height for predictable visual sizing.
+- Value label font size shrinks with the chart size for better fit on smaller pies.
+
+## Negative Values
+
+Negative values are skipped (not rendered) and logged as warnings. If all rows
+are negative, the chart throws an error because there is nothing to render.
+
+When `valueLabel.position` is `inside`, the formatted value-label text that does not
+fit inside its slice is hidden. In `auto` mode, labels that are too tight (based on
+`insideMargin`) move outside instead.
+
+## Supported Components
+
+PieChart supports the following components via `addChild()`:
+
+- `Title` - Chart title
+- `Legend` - Interactive legend (click to toggle slices)
+- `Tooltip` - Hover/focus tooltips with slice info
+
+## Tooltip Formatting
+
+The default tooltip shows label, value, and percentage. Customize with a formatter:
+
+```javascript
+new Tooltip({
+    formatter: (dataKey, value, data) => `${dataKey}: ${value.toLocaleString()} visitors (${data.region})`,
+});
+```

package/docs/theming.md

@@ -0,0 +1,162 @@
+# Theming
+
+Customize the appearance of charts through the theme configuration.
+
+Theme overrides are deep-partial. You can override nested fields like
+`theme.axis.fontSize` or `theme.donut.centerContent.mainValue.color` without
+redefining the rest of those nested objects.
+
+## Theme Configuration
+
+```javascript
+const chart = new XYChart({
+    data,
+    theme: {
+        margins: {
+            top: 30,
+            right: 30,
+            bottom: 40,
+            left: 60,
+        },
+        colorPalette: ['#ff6b6b', '#4ecdc4', '#45b7d1', '#f7b731'],
+        grid: {
+            color: '#e0e0e0',
+            opacity: 0.5,
+        },
+        axis: {
+            fontFamily: 'Inter, sans-serif',
+            fontSize: 12,
+        },
+    },
+});
+```
+
+Built-in theme presets are exported from `@internetstiftelsen/charts/theme`:
+
+```javascript
+import { defaultTheme, newspaperTheme, themes } from '@internetstiftelsen/charts/theme';
+```
+
+## Theme Options
+
+| Option                | Type       | Default                                        | Description                                  |
+| --------------------- | ---------- | ---------------------------------------------- | -------------------------------------------- |
+| `margins`             | `object`   | `{ top: 20, right: 20, bottom: 20, left: 20 }` | Base margins                                 |
+| `colorPalette`        | `string[]` | -                                              | Colors for auto-assignment                   |
+| `grid.color`          | `string`   | `'#e0e0e0'`                                    | Grid line color                              |
+| `grid.opacity`        | `number`   | `0.5`                                          | Grid line opacity                            |
+| `fontFamily`          | `string`   | -                                              | Base font family                             |
+| `axis.fontFamily`     | `string`   | -                                              | Axis text font                               |
+| `axis.fontSize`       | `number`   | -                                              | Axis text size in pixels                     |
+| `legend.paddingX`     | `number`   | `0`                                            | Horizontal legend layout padding             |
+| `legend.itemSpacingX` | `number`   | `20`                                           | Horizontal spacing between legend items      |
+| `legend.itemSpacingY` | `number`   | `8`                                            | Vertical spacing between wrapped legend rows |
+
+---
+
+## Color Palette
+
+The color palette is used for automatic color assignment. Series without explicit colors get assigned colors from this palette based on their index.
+
+```javascript
+theme: {
+    colorPalette: [
+        '#4ecdc4',  // First series
+        '#ff6b6b',  // Second series
+        '#45b7d1',  // Third series
+        '#f7b731',  // Fourth series
+        // ... continues cycling
+    ],
+}
+```
+
+---
+
+## Manual Color Assignment
+
+Override auto-colors by specifying colors directly on series:
+
+```javascript
+// Lines
+chart.addChild(new Line({ dataKey: 'revenue', stroke: '#00ff00' }));
+chart.addChild(new Line({ dataKey: 'expenses', stroke: '#ff0000' }));
+
+// Bars
+chart.addChild(new Bar({ dataKey: 'sales', fill: '#4ecdc4' }));
+```
+
+For DonutChart, specify colors in the data:
+
+```javascript
+const data = [
+    { name: 'Desktop', value: 450, color: '#4ecdc4' },
+    { name: 'Mobile', value: 320, color: '#ff6b6b' },
+    { name: 'Tablet', value: 130, color: '#45b7d1' },
+];
+```
+
+---
+
+## Donut Theme Defaults
+
+DonutChart has additional theme defaults:
+
+```javascript
+theme: {
+    donut: {
+        innerRadius: 0.5,    // Inner radius ratio (0-1)
+        padAngle: 0.02,      // Gap between segments
+        cornerRadius: 0,     // Rounded corners
+        centerContent: {
+            mainValue: {
+                fontSize: 32,
+                fontWeight: 'bold',
+                color: '#1f2a36',
+            },
+            title: {
+                fontSize: 14,
+                fontWeight: 'normal',
+                color: '#6b7280',
+            },
+            subtitle: {
+                fontSize: 12,
+                fontWeight: 'normal',
+                color: '#9ca3af',
+            },
+        },
+    },
+}
+```
+
+---
+
+## Responsive Behavior
+
+Theme config controls styling, not sizing. To control size, either pass
+top-level `width` and `height` on the chart config or style the container.
+
+For fixed-size charts:
+
+```javascript
+const chart = new XYChart({
+    data,
+    width: 800,
+    height: 400,
+});
+```
+
+For responsive charts:
+
+```css
+.chart-container {
+    width: 100%;
+    max-width: 1200px;
+    height: 600px;
+}
+```
+
+Charts render with container-driven `100%` height (same model as width). Set an
+explicit container height for predictable visual sizing when you are not using a
+fixed `height`.
+
+No manual resize calls needed - charts use ResizeObserver to respond automatically.

package/docs/word-cloud-chart.md

@@ -0,0 +1,98 @@
+# WordCloudChart API
+
+`WordCloudChart` renders a word cloud from flat rows with a fixed shape:
+
+```typescript
+[
+    { word: 'internet', count: 96 },
+    { word: 'social', count: 82 },
+];
+```
+
+## Constructor
+
+```typescript
+new WordCloudChart(config: WordCloudChartConfig)
+```
+
+## Config Options
+
+| Option       | Type                      | Default  | Description                                      |
+| ------------ | ------------------------- | -------- | ------------------------------------------------ |
+| `data`       | `DataItem[]`              | required | Flat `{ word, count }` rows                      |
+| `width`      | `number`                  | -        | Explicit chart width in pixels                   |
+| `height`     | `number`                  | -        | Explicit chart height in pixels                  |
+| `theme`      | `DeepPartial<ChartTheme>` | -        | Theme customization                              |
+| `responsive` | `ResponsiveConfig`        | -        | Declarative container-query responsive overrides |
+| `wordCloud`  | `WordCloudConfig`         | -        | Layout and filtering options                     |
+
+### `wordCloud`
+
+```typescript
+wordCloud: {
+    maxWords?: number;                  // default: 75
+    minWordLength?: number;             // default: 1
+    minValue?: number;                  // default: 1
+    minFontSize?: number;               // default: 3 (% of smaller plot-area dimension)
+    maxFontSize?: number;               // default: 20 (% of smaller plot-area dimension)
+    padding?: number;                   // default: 1
+    rotation?: 'none' | 'right-angle';  // optional preset
+    spiral?: 'archimedean' | 'rectangular';
+}
+```
+
+## Example
+
+```typescript
+import { WordCloudChart } from '@internetstiftelsen/charts/word-cloud-chart';
+import { Title } from '@internetstiftelsen/charts/title';
+
+const data = [
+    { word: 'internet', count: 96 },
+    { word: 'social', count: 82 },
+    { word: 'news', count: 75 },
+    { word: 'streaming', count: 68 },
+];
+
+const chart = new WordCloudChart({
+    data,
+    wordCloud: {
+        minWordLength: 3,
+        minValue: 10,
+        minFontSize: 3,
+        maxFontSize: 20,
+        padding: 1,
+        spiral: 'archimedean',
+    },
+});
+
+chart.addChild(new Title({ text: 'Most mentioned words' }));
+
+chart.render('#word-cloud');
+```
+
+## Data Rules
+
+- Grouped datasets are not supported.
+- Word text is normalized with `trim()`.
+- Rows with empty words, non-numeric counts, counts below `minValue`, or words
+  shorter than `minWordLength` are skipped.
+- Duplicate surviving words are aggregated after normalization.
+- The chart throws if no valid words remain after filtering.
+
+## Supported Components
+
+- `Title`
+
+`XAxis`, `YAxis`, `Grid`, `Legend`, and `Tooltip` are not used by
+`WordCloudChart`.
+
+## Notes
+
+- `minFontSize` and `maxFontSize` use percentages of the smaller plot-area
+  dimension and define the relative size range passed into `d3-cloud`.
+- The chart uses theme typography and palette colors directly when configuring
+  `d3-cloud` and rendering the final SVG.
+- If `rotation` is omitted, the chart uses the native `d3-cloud` rotate
+  accessor.
+- `rotation: 'right-angle'` mixes `0` and `90` degree labels.