@internetstiftelsen/charts 0.9.2 → 0.10.0

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

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})`,
+});
+```