@internetstiftelsen/charts 0.9.2 → 0.10.1

package/docs/components.md

@@ -0,0 +1,321 @@
+# Components
+
+Charts are built by composing components. All components are added via the `addChild()` method.
+
+## XAxis
+
+Renders the X axis.
+
+```typescript
+new XAxis({
+    display?: boolean,        // Render axis and reserve layout space (default: true)
+    dataKey?: string,         // Key in data objects for X values (auto-detected if omitted)
+    labelKey?: string,        // Optional display label key (uses dataKey values if omitted)
+    groupLabelKey?: string,   // Optional key used for second-row grouped labels
+    showGroupLabels?: boolean, // Show second-row grouped labels (default: false)
+    groupLabelGap?: number,   // Vertical gap between tick row and grouped row
+    rotatedLabels?: boolean,  // Rotate tick labels -45deg
+    maxLabelWidth?: number,   // Optional cap for tick-label width
+    oversizedBehavior?: 'truncate' | 'wrap' | 'hide', // Only applies when maxLabelWidth is set
+    autoHideOverlapping?: boolean, // Automatically hide overlapping labels
+    minLabelGap?: number,     // Minimum gap between visible labels when auto-hide is enabled
+    preserveEndLabels?: boolean, // Keep first/last labels visible when auto-hide is enabled
+    tickFormat?: string | ((value: string | number | Date) => string) | null
+})
+```
+
+Grouped label styles come from `theme.axis.groupLabel` and are bold by default.
+
+### Example
+
+```javascript
+chart.addChild(new XAxis({ dataKey: 'date' }));
+```
+
+Callback formatter example:
+
+```typescript
+new XAxis({
+    dataKey: 'month',
+    tickFormat: (value) => `Month ${value}`,
+});
+```
+
+Grouped axis example:
+
+```typescript
+new XAxis({
+    // dataKey can be omitted if XAxis auto-detection is enough
+    dataKey: '__iis_grouped_category_id__',
+    showGroupLabels: true,
+});
+```
+
+---
+
+## YAxis
+
+Renders the Y axis.
+
+```typescript
+new YAxis({
+    display?: boolean,          // Render axis and reserve layout space (default: true)
+    rotatedLabels?: boolean,    // Rotate tick labels -45deg
+    maxLabelWidth?: number,     // Optional cap for tick-label width
+    oversizedBehavior?: 'truncate' | 'wrap' | 'hide', // Only applies when maxLabelWidth is set
+    tickFormat?: string | ((value: string | number | Date) => string) | null
+})
+```
+
+When `maxLabelWidth` is omitted, `YAxis` reserves the measured width of its
+rendered tick labels. Set `maxLabelWidth` to cap the reserved width and use
+`oversizedBehavior` to control truncation, wrapping, or hiding.
+
+### Format Examples
+
+```javascript
+new YAxis(); // Raw numbers: 35000
+new YAxis({ tickFormat: 's' }); // SI-prefix: 35k
+new YAxis({ tickFormat: '$,' }); // Currency: $35,000
+new YAxis({ tickFormat: '.1%' }); // Percentage: 35.0%
+new YAxis({ tickFormat: '.2f' }); // Fixed decimal: 35000.00
+new YAxis({ tickFormat: (value) => `Value ${value}` });
+```
+
+See [D3 format specifiers](https://github.com/d3/d3-format) for all options.
+
+---
+
+## Grid
+
+Renders grid lines in the plot area.
+
+```typescript
+new Grid({
+    value?: boolean,       // Show grid lines for the value axis (default: true)
+    category?: boolean,    // Show grid lines for the category axis (default: true)
+})
+```
+
+`value` and `category` stay semantically stable when `XYChart.orientation`
+changes. In vertical charts, `value: true` renders horizontal grid lines. In
+horizontal charts, `value: true` renders vertical grid lines.
+
+### Example
+
+```javascript
+// Value-axis grid only
+chart.addChild(new Grid({ category: false, value: true }));
+
+// Both axes
+chart.addChild(new Grid());
+```
+
+---
+
+## Tooltip
+
+Renders interactive tooltips on hover and keyboard focus.
+
+```typescript
+new Tooltip({
+    formatter?: (dataKey: string, value: DataValue, data: DataItem) => string
+})
+```
+
+The formatter receives:
+
+- `dataKey` - The series key (e.g., 'revenue')
+- `value` - The data value at this point
+- `data` - The full data item object
+
+### Example
+
+```javascript
+new Tooltip({
+    formatter: (dataKey, value, data) =>
+        `<strong>${dataKey}</strong><br/>
+         Value: ${value.toLocaleString()}<br/>
+         Date: ${data.date}`,
+});
+```
+
+---
+
+## Legend
+
+Renders an interactive legend. Click items to toggle series visibility.
+
+```typescript
+new Legend({
+    mode?: 'inline' | 'disconnected' | 'hidden', // Rendering mode (default: 'inline')
+    position?: 'bottom',     // Position (currently only 'bottom')
+    disconnectedTarget?: string | HTMLElement, // External mount target when mode is 'disconnected'
+    marginTop?: number,      // Space above legend (default: 20)
+    marginBottom?: number,   // Space below legend (default: 10)
+    paddingX?: number,       // Horizontal inset for legend layout (default: theme.legend.paddingX)
+    itemSpacingX?: number,   // Horizontal space between legend items (default: theme.legend.itemSpacingX)
+    itemSpacingY?: number,   // Vertical space between wrapped legend rows (default: theme.legend.itemSpacingY)
+})
+```
+
+Legend items automatically wrap to new rows when they do not fit available
+width. Each wrapped row is centered independently.
+
+- `inline`: current default behavior (legend rendered inside the chart SVG)
+- `disconnected`: legend rendered in a separate SVG outside chart layout
+- `hidden`: no legend rendering; use chart legend APIs for custom HTML legends
+
+### Example
+
+```javascript
+chart.addChild(new Legend({ position: 'bottom' }));
+```
+
+### Custom HTML Legend
+
+```javascript
+chart.addChild(new Legend({ mode: 'hidden' }));
+
+const items = chart.getLegendItems();
+// Render items in HTML and call:
+chart.toggleLegendSeries(items[0].dataKey);
+```
+
+Legend control APIs also work without mounting a `Legend` component at all. This
+is what allows [`ChartGroup`](./chart-group.md) to coordinate multiple child
+charts from one shared legend.
+
+---
+
+## Title
+
+Renders a title for the chart.
+
+```typescript
+new Title({
+    display?: boolean,      // Render title and reserve layout space (default: true)
+    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)
+})
+```
+
+### Example
+
+```javascript
+chart.addChild(
+    new Title({
+        text: 'Monthly Revenue',
+        align: 'left',
+        fontSize: 20,
+    }),
+);
+```
+
+---
+
+## Export Hooks
+
+Components can provide `exportHooks` to adjust export-only settings or mutate
+the exported SVG right before serialization. Hooks run only for visual exports
+(`svg`, `png`, `jpg`, `pdf`) and never touch the live chart instance. Use
+`beforeRender` to return config overrides and `before` to mutate the export
+SVG.
+
+```typescript
+const title = new Title({
+    text: 'Original',
+    exportHooks: {
+        before({ svg }) {
+            const text = svg.querySelector('.title text');
+            if (text) {
+                text.textContent = 'Exported';
+            }
+        },
+    },
+});
+
+chart.addChild(title);
+```
+
+You can control the export size via options:
+
+```typescript
+await chart.export('svg', { width: 1200, height: 800 });
+```
+
+You can also return a partial config to re-render the export:
+
+```typescript
+new Line({
+    dataKey: 'revenue',
+    exportHooks: {
+        beforeRender(_context, currentConfig) {
+            if (!currentConfig.valueLabel?.show) {
+                return {
+                    valueLabel: {
+                        show: true,
+                    },
+                };
+            }
+        },
+    },
+});
+```
+
+For container-query responsive behavior, use chart-level `responsive`
+breakpoints in chart constructor config (see
+[XYChart API](./xy-chart.md#responsive-overrides)).
+
+## Export Formats
+
+`chart.export()` is async and supports:
+
+- `svg`
+- `json`
+- `csv`
+- `xlsx` (lazy-loads optional `xlsx`)
+- `png`
+- `jpg`
+- `pdf` (lazy-loads optional `jspdf`)
+
+```typescript
+await chart.export('png', { download: true });
+await chart.export('csv', { download: true, delimiter: ';' });
+await chart.export('xlsx', { download: true, sheetName: 'Data' });
+await chart.export('pdf', { download: true, pdfMargin: 16 });
+```
+
+Export option highlights:
+
+- `columns`: choose specific columns for `csv` and `xlsx`
+- `delimiter`: CSV delimiter (default `,`)
+- `pixelRatio`: render scale for `png`, `jpg`, `pdf`
+- `backgroundColor`: defaults transparent for `png`, white for `jpg`/`pdf`
+- `jpegQuality`: JPEG quality for `jpg` (default `0.92`)
+- `sheetName`: sheet name for `xlsx` (default `Sheet1`)
+- `pdfMargin`: page margin for `pdf` (default `0`)
+
+`json` export returns only the chart data payload
+
+---
+
+## Component Order
+
+Components are rendered in the order they're added. A typical order:
+
+```javascript
+chart
+    .addChild(new Title({ text: 'Chart Title' }))
+    .addChild(new Grid({ value: true }))
+    .addChild(new XAxis({ dataKey: 'date' }))
+    .addChild(new YAxis())
+    .addChild(new Tooltip())
+    .addChild(new Legend({ position: 'bottom' }))
+    .addChild(new Line({ dataKey: 'value1' }))
+    .addChild(new Line({ dataKey: 'value2' }));
+```

package/docs/donut-chart.md

@@ -0,0 +1,193 @@
+# DonutChart API
+
+A chart for displaying proportional data as segments of a donut/pie.
+
+## Constructor
+
+```typescript
+new DonutChart(config: DonutChartConfig)
+```
+
+### 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                                        |
+| `donut`      | `DonutConfig`             | -         | Donut-specific configuration                                          |
+| `valueLabel` | `DonutValueLabelConfig`   | -         | On-chart outside label/value rendering configuration                  |
+| `theme`      | `DeepPartial<ChartTheme>` | -         | Theme customization                                                   |
+| `responsive` | `ResponsiveConfig`        | -         | Declarative container-query responsive overrides (theme + components) |
+
+### Donut Config
+
+```typescript
+donut: {
+    innerRadius?: number,   // 0-1, percentage of outer radius (default: 0.5)
+    padAngle?: number,      // Radians between segments (default: 0.02)
+    cornerRadius?: number,  // Corner radius in pixels (default: 0)
+}
+```
+
+### ValueLabel Config
+
+```typescript
+valueLabel: {
+    show?: boolean,                 // default: false
+    position?: 'outside' | 'auto', // default: 'auto'
+    outsideOffset?: number,        // default: 16
+    minVerticalSpacing?: number,   // default: 14
+    formatter?: (label, value, data, percentage) => string, // default: `${label}: ${value}`
+}
+```
+
+Donut value labels are rendered outside the ring with leader lines. `auto`
+currently resolves to the same outside placement as `outside`.
+
+## 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';
+import { Title } from '@internetstiftelsen/charts/title';
+
+const data = [
+    { name: 'Desktop', value: 450 },
+    { name: 'Mobile', value: 320 },
+    { name: 'Tablet', value: 130 },
+];
+
+const chart = new DonutChart({
+    data,
+    valueKey: 'value',
+    labelKey: 'name',
+    donut: {
+        innerRadius: 0.6,
+        padAngle: 0.02,
+        cornerRadius: 4,
+    },
+    valueLabel: {
+        show: true,
+        formatter: (label, _value, _data, percentage) =>
+            `${label}: ${percentage.toFixed(1)}%`,
+    },
+});
+
+chart
+    .addChild(new Title({ text: 'Device Distribution' }))
+    .addChild(
+        new DonutCenterContent({
+            mainValue: '900',
+            title: 'Total',
+            subtitle: 'visitors',
+        }),
+    )
+    .addChild(new Legend({ position: 'bottom' }))
+    .addChild(new Tooltip());
+
+chart.render('#chart-container');
+```
+
+## Responsive Height and Center Text
+
+- DonutChart uses container-driven `100%` height (same behavior model as width).
+- Set an explicit container height for predictable visual sizing.
+- Donut center-content text shrinks with chart size so it scales with the donut.
+- Donut value-label text also scales down with the chart size.
+
+## Custom Colors
+
+You can specify colors directly in your data:
+
+```javascript
+const data = [
+    { name: 'Desktop', value: 450, color: '#4ecdc4' },
+    { name: 'Mobile', value: 320, color: '#ff6b6b' },
+    { name: 'Tablet', value: 130, color: '#45b7d1' },
+];
+```
+
+Or use the theme's color palette (colors are auto-assigned by index).
+
+---
+
+## DonutCenterContent
+
+Displays text content in the center of the donut.
+
+```typescript
+new DonutCenterContent(config: DonutCenterContentConfig)
+```
+
+### Config Options
+
+| Option           | Type        | Description                       |
+| ---------------- | ----------- | --------------------------------- |
+| `mainValue`      | `string`    | Large primary value (e.g., "900") |
+| `title`          | `string`    | Title text below main value       |
+| `subtitle`       | `string`    | Smaller subtitle text             |
+| `mainValueStyle` | `TextStyle` | Style for main value              |
+| `titleStyle`     | `TextStyle` | Style for title                   |
+| `subtitleStyle`  | `TextStyle` | Style for subtitle                |
+
+### TextStyle Options
+
+```typescript
+{
+    fontSize?: number,
+    fontWeight?: string,
+    fontFamily?: string,
+    color?: string,
+}
+```
+
+### Example
+
+```javascript
+new DonutCenterContent({
+    mainValue: '$1.2M',
+    title: 'Revenue',
+    subtitle: 'Q4 2024',
+    mainValueStyle: {
+        fontSize: 36,
+        fontWeight: 'bold',
+        color: '#333',
+    },
+    titleStyle: {
+        fontSize: 14,
+        color: '#666',
+    },
+    subtitleStyle: {
+        fontSize: 12,
+        color: '#999',
+    },
+});
+```
+
+---
+
+## Supported Components
+
+DonutChart supports the following components via `addChild()`:
+
+- `DonutCenterContent` - Center text content
+- `Title` - Chart title
+- `Legend` - Interactive legend (click to toggle segments)
+- `Tooltip` - Hover tooltips with segment 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`,
+});
+```

package/docs/gauge-chart.md

@@ -0,0 +1,175 @@
+# GaugeChart API
+
+A chart for displaying a single KPI value against a range with optional
+threshold bands and target marker.
+
+## Constructor
+
+```typescript
+new GaugeChart(config: GaugeChartConfig)
+```
+
+### Config Options
+
+| Option           | Type                      | Default   | Description                                                           |
+| ---------------- | ------------------------- | --------- | --------------------------------------------------------------------- |
+| `data`           | `DataItem[]`              | required  | Data array (first row is used)                                        |
+| `width`          | `number`                  | -         | Explicit chart width in pixels                                        |
+| `height`         | `number`                  | -         | Explicit chart height in pixels                                       |
+| `valueKey`       | `string`                  | `'value'` | Key for the current value in the first row                            |
+| `targetValueKey` | `string`                  | -         | Optional key for target value in the first row                        |
+| `gauge`          | `GaugeConfig`             | -         | Gauge-specific configuration                                          |
+| `theme`          | `DeepPartial<ChartTheme>` | -         | Theme customization                                                   |
+| `responsive`     | `ResponsiveConfig`        | -         | Declarative container-query responsive overrides (theme + components) |
+
+### Gauge Config
+
+```typescript
+gauge: {
+    value?: number,           // Explicit value (overrides valueKey)
+    targetValue?: number,     // Explicit target (overrides targetValueKey)
+    min?: number,             // default: 0
+    max?: number,             // default: 100
+    animate?: boolean | {     // default: false
+        show?: boolean,       // default: true when object is used
+        duration?: number,    // ms, default: 700
+        easing?:              // default: 'ease-in-out'
+            | 'linear'
+            | 'ease-in'
+            | 'ease-out'
+            | 'ease-in-out'
+            | 'bounce-out'
+            | 'elastic-out'
+            | `linear(...)`   // CSS-like piecewise linear easing
+            | ((t: number) => number),
+    },
+    halfCircle?: boolean,     // default: false
+    startAngle?: number,      // default: -Math.PI * 0.75 (or -Math.PI / 2 in halfCircle mode)
+    endAngle?: number,        // default: Math.PI * 0.75 (or Math.PI / 2 in halfCircle mode)
+    innerRadius?: number,     // 0-1, default: 0.68
+    thickness?: number,       // px, overrides innerRadius when provided
+    cornerRadius?: number,    // px, default: 4
+    trackColor?: string,      // default: #e5e7eb
+    progressColor?: string,   // default: theme.colorPalette[0]
+    targetColor?: string,     // default: #111827
+    segmentStyle?: 'solid' | 'gradient', // default: 'solid'
+    showValue?: boolean,      // default: true
+    valueFormatter?: (value) => string,
+    valueLabelStyle?: {
+        fontSize?: number | string,  // default: 28
+        fontFamily?: string,         // default: theme.axis.fontFamily
+        fontWeight?: number | string, // default: 700
+        color?: string,              // default: #111827
+    },
+    needle?: boolean | {
+        show?: boolean,       // default: true
+        color?: string,       // default: #111827
+        width?: number,
+        lengthRatio?: number,
+        capRadius?: number,
+    },
+    marker?: boolean | {
+        show?: boolean,       // default: !needle.show
+        color?: string,
+        width?: number,
+    },
+    ticks?: {
+        count?: number,       // default: 5
+        show?: boolean,       // default: true
+        showLines?: boolean,  // default: true
+        showLabels?: boolean, // default: true
+        size?: number,        // default: 8
+        labelOffset?: number, // default: 12
+        formatter?: (value) => string,
+        labelStyle?: {
+            fontSize?: number | string,  // default: 11
+            fontFamily?: string,         // default: theme.axis.fontFamily
+            fontWeight?: number | string, // default: theme.axis.fontWeight
+            color?: string,              // default: #4b5563
+        },
+    },
+    segments?: [
+        {
+            from: number,
+            to: number,
+            color?: string,    // uses theme.colorPalette[index] when omitted
+            label?: string,
+        }
+    ],
+}
+```
+
+## Example
+
+```javascript
+import { GaugeChart } from '@internetstiftelsen/charts/gauge-chart';
+import { Tooltip } from '@internetstiftelsen/charts/tooltip';
+import { Legend } from '@internetstiftelsen/charts/legend';
+import { Title } from '@internetstiftelsen/charts/title';
+
+const chart = new GaugeChart({
+    data: [{ label: 'KPI', value: 72, target: 80 }],
+    valueKey: 'value',
+    targetValueKey: 'target',
+    gauge: {
+        min: 0,
+        max: 100,
+        animate: {
+            show: true,
+            duration: 900,
+            easing: 'ease-out',
+        },
+        halfCircle: true,
+        showValue: true,
+        needle: true,
+        ticks: { count: 5 },
+        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 Title({ text: 'Operational KPI' }))
+    .addChild(new Tooltip())
+    .addChild(new Legend({ position: 'bottom' }));
+
+chart.render('#gauge-container');
+```
+
+## Validation and Clamping
+
+- `gauge.min` must be less than `gauge.max`.
+- Segment ranges must stay inside `[min, max]` and must not overlap.
+- You can pass any number of threshold segments.
+- Segment colors are optional; omitted colors use `theme.colorPalette`
+  (or a built-in fallback palette if the theme palette is empty).
+- Out-of-range `value` and `targetValue` are clamped to `[min, max]` with a
+  non-fatal warning.
+
+## Animation Easing Example
+
+```typescript
+const chart = new GaugeChart({
+    data: [{ value: 72 }],
+    gauge: {
+        min: 0,
+        max: 100,
+        animate: {
+            show: true,
+            duration: 1200,
+            easing: 'linear(0, 0.029 1.6%, 0.123 3.5%, 0.651 10.6%, 0.862 14.1%, 1.002 17.7%, 1.046 19.6%, 1.074 21.6%, 1.087 23.9%, 1.086 26.6%, 1.014 38.5%, 0.994 46.3%, 1)',
+        },
+    },
+});
+```
+
+## Supported Components
+
+GaugeChart supports the following components via `addChild()`:
+
+- `Title` - Chart title
+- `Tooltip` - Hover tooltip (value, target)
+- `Legend` - Segment legend with visibility toggles