@internetstiftelsen/charts 0.9.2 → 0.10.0

package/docs/chart-group.md

@@ -0,0 +1,213 @@
+# ChartGroup API
+
+Compose multiple existing charts into a shared layout with one coordinated
+legend.
+
+## Constructor
+
+```typescript
+new ChartGroup(config: ChartGroupConfig)
+```
+
+### Config Options
+
+| Option        | Type                              | Default                | Description                                                                 |
+| ------------- | --------------------------------- | ---------------------- | --------------------------------------------------------------------------- |
+| `cols`        | `number`                          | required               | Base number of layout columns                                               |
+| `gap`         | `number`                          | `20`                   | Base horizontal and vertical gap between chart cells in px                  |
+| `syncY`       | `boolean`                         | `false`                | Sync the Y domain across visible vertical `XYChart` children                |
+| `height`      | `number`                          | container height       | Fixed total group height. Omit it to size from the container                |
+| `chartHeight` | `number`                          | `DEFAULT_CHART_HEIGHT` | Fallback child height when neither the child nor container provides one     |
+| `theme`       | `DeepPartial<ChartTheme>`         | -                      | Theme override for the shared group legend and title                        |
+| `responsive`  | `ChartGroupResponsiveConfig`      | -                      | Declarative responsive overrides for group-level `cols` and `gap`           |
+
+`ChartGroup` manages child widths. If a child chart has an explicit `width`,
+that width is ignored inside the group and a warning is emitted.
+
+## Example
+
+```typescript
+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' }))
+    .addChild(new Line({ dataKey: 'expenses' }));
+
+const barChart = new XYChart({ data: barData });
+barChart
+    .addChild(new Bar({ dataKey: 'revenue' }))
+    .addChild(new Bar({ dataKey: 'expenses' }));
+
+const group = new ChartGroup({
+    cols: 3,
+    gap: 20,
+    height: 420,
+    syncY: true,
+});
+
+group
+    .addChild(new Title({ text: 'Revenue vs Expenses' }))
+    .addChart(barChart, { span: 1 })
+    .addChart(lineChart, { span: 2 })
+    .addChild(new Legend());
+
+group.render('#chart-group');
+```
+
+The group legend merges child legend items by key. If multiple child charts use
+the same legend key, toggling that key affects every matching child chart.
+
+## Layout
+
+Use `addChart(chart, options)` to place a child chart in the group:
+
+```typescript
+group.addChart(chart, {
+    span?: number,
+    height?: number,
+    hidden?: boolean,
+    order?: number,
+    responsive?: {
+        breakpoints?: {
+            [name]: {
+                minWidth?: number,
+                maxWidth?: number,
+                span?: number,
+                height?: number,
+                hidden?: boolean,
+                order?: number,
+            }
+        }
+    },
+});
+```
+
+- `span` defaults to `1` and is clamped to the active column count
+- `height` overrides the row item height for that child only
+- `hidden` removes the child from layout, legend merging, `syncY`, and export
+- `order` reorders the visible children before layout
+- Child height resolution is:
+  `item.height ?? childChart.height ?? rowFallbackHeight`
+- `rowFallbackHeight` comes from the available group height when the group has a
+  fixed height or container height, otherwise it falls back to
+  `group.chartHeight`
+
+Child charts keep their own axes, tooltips, responsive overrides, and render
+logic. Their own legend rendering is suppressed while they are mounted inside
+the group so only the shared group legend is shown.
+
+When `syncY` is enabled, `ChartGroup` computes one shared vertical numeric
+domain for its `XYChart` children and applies it before render and export. This
+is useful for layouts like `Bar + Line` where one chart keeps the visible Y
+axis while the other only shows aligned horizontal grid lines.
+
+## Responsive Layout
+
+`ChartGroup` uses the same breakpoint semantics as chart-level `responsive`
+config:
+
+- Breakpoints support both `minWidth` and `maxWidth`
+- A numeric breakpoint value is shorthand for `minWidth`
+- All matching breakpoints merge in declaration order
+
+```typescript
+const group = new ChartGroup({
+    cols: 3,
+    gap: 20,
+    responsive: {
+        breakpoints: {
+            tablet: {
+                maxWidth: 1023,
+                cols: 2,
+            },
+            mobile: {
+                maxWidth: 640,
+                cols: 1,
+                gap: 16,
+            },
+        },
+    },
+});
+
+group
+    .addChart(barChart, {
+        span: 1,
+        responsive: {
+            breakpoints: {
+                mobile: {
+                    maxWidth: 640,
+                    hidden: true,
+                },
+            },
+        },
+    })
+    .addChart(lineChart, {
+        span: 2,
+        responsive: {
+            breakpoints: {
+                mobile: {
+                    maxWidth: 640,
+                    span: 1,
+                    order: -1,
+                },
+            },
+        },
+    });
+```
+
+After a breakpoint's `maxWidth`, that breakpoint stops matching. Use the base
+group config plus `minWidth` breakpoints for mobile-first layouts, or the base
+group config plus `maxWidth` breakpoints for desktop-down layouts.
+
+## Title
+
+`ChartGroup` accepts `Title` via `addChild()` and renders it above the grouped
+chart layout:
+
+```typescript
+group.addChild(new Title({ text: 'Revenue vs Expenses' }));
+```
+
+## Legend
+
+`ChartGroup` accepts `Legend` via `addChild()`. Supported group legend modes:
+
+- `inline` (default)
+- `hidden`
+
+`disconnected` is not supported for `ChartGroup` in v1.
+
+Programmatic legend APIs are available on the group and mirror `BaseChart`:
+
+```typescript
+group.getLegendItems();
+group.toggleLegendSeries('revenue');
+group.setLegendSeriesVisible('expenses', false);
+group.setLegendVisibility({ revenue: true, expenses: false });
+group.onLegendChange(() => {
+    // React to shared legend updates
+});
+```
+
+## Export
+
+`ChartGroup` supports combined visual exports:
+
+```typescript
+await group.export('svg');
+await group.export('png');
+await group.export('jpg');
+await group.export('pdf');
+```
+
+- Export width can be overridden with `options.width`
+- Export height is layout-derived in v1 and cannot be overridden
+- Group titles are included in the combined export
+- Child chart legends are suppressed in the combined export
+- Non-visual exports (`json`, `csv`, `xlsx`) are not supported in v1

package/docs/components.md

@@ -0,0 +1,308 @@
+# 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
+    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)
+    tickFormat?: string | ((value: string | number | Date) => string) | null
+})
+```
+
+### 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`,
+});
+```