@internetstiftelsen/charts 0.9.2 → 0.10.0

package/docs/xy-chart.md

@@ -0,0 +1,502 @@
+# XYChart API
+
+The main chart class for creating XY-coordinate charts (line, scatter, area, bar, or mixed).
+
+## Constructor
+
+```typescript
+new XYChart(config: XYChartConfig)
+```
+
+### Config Options
+
+| Option        | Type                               | Default                                              | Description                                                           |
+| ------------- | ---------------------------------- | ---------------------------------------------------- | --------------------------------------------------------------------- |
+| `data`        | `DataItem[] \| GroupedDataGroup[]` | required                                             | Flat rows or grouped nested rows                                      |
+| `width`       | `number`                           | -                                                    | Explicit chart width in pixels                                        |
+| `height`      | `number`                           | -                                                    | Explicit chart height in pixels                                       |
+| `theme`       | `DeepPartial<ChartTheme>`          | -                                                    | Theme customization                                                   |
+| `scales`      | `AxisScaleConfig`                  | -                                                    | Scale configuration                                                   |
+| `orientation` | `'vertical' \| 'horizontal'`       | `'vertical'`                                         | Chart orientation. Horizontal mode currently supports bar-only charts |
+| `responsive`  | `ResponsiveConfig`                 | -                                                    | Container-query responsive overrides (theme + components)             |
+| `barStack`    | `BarStackConfig`                   | `{ mode: 'normal', gap: 0.1, reverseSeries: false }` | Bar stacking configuration                                            |
+| `areaStack`   | `AreaStackConfig`                  | `{ mode: 'none' }`                                   | Area stacking configuration                                           |
+
+### Theme Options
+
+```typescript
+theme: {
+    margins: {               // Base margins around plot area
+        top: number,         // default: 20
+        right: number,       // default: 20
+        bottom: number,      // default: 20
+        left: number,        // default: 20
+    },
+    colorPalette: string[],  // Colors for auto-assignment
+    grid: {
+        color: string,       // Grid line color (default: '#e0e0e0')
+        opacity: number,     // Grid line opacity (default: 0.5)
+    },
+    axis: {
+        fontFamily: string,
+        fontSize: string,
+    },
+}
+```
+
+Use top-level `width` and `height` for fixed-size charts. If omitted, the chart
+sizes itself from the render container.
+
+### Grouped Dataset Shape
+
+Grouped categorical datasets can be passed as nested groups:
+
+```json
+[
+    {
+        "group": "Internetanv. 8+ år",
+        "data": [
+            {
+                "Kategori": "Man",
+                "Använt sociala medier varje dag": "83%",
+                "Använt sociala medier minst varje vecka": "90%"
+            },
+            {
+                "Kategori": "Kvinna",
+                "Använt sociala medier varje dag": "86%",
+                "Använt sociala medier minst varje vecka": "92%"
+            }
+        ]
+    }
+]
+```
+
+Rules for grouped datasets:
+
+- The first key of each row object is used as the category key (for example `Kategori`).
+- Remaining keys are treated as metric columns.
+- Each `group` must be a non-empty string.
+- Group labels are rendered on a second x-axis row when `XAxis.showGroupLabels` is enabled.
+- CSV/XLSX exports use spreadsheet-style grouped rows (blank first two headers, blank continuation group cells, no spacer rows).
+
+### Scale Options
+
+```typescript
+scales: {
+    x: {
+        type: 'band' | 'linear' | 'time' | 'log',
+        domain?: ScaleDomainValue[],
+        padding?: number,
+        groupGap?: number, // adds visual slot gaps between grouped categories
+        reverse?: boolean, // reverse the rendered axis direction
+        nice?: boolean,
+    },
+    y: {
+        type: 'band' | 'linear' | 'time' | 'log',
+        domain?: ScaleDomainValue[],
+        padding?: number,
+        reverse?: boolean, // reverse the rendered axis direction
+        nice?: boolean,
+    },
+}
+```
+
+Categorical `y` axes render in data order from top to bottom by default. Set
+`reverse: true` on either axis to intentionally flip its direction for category,
+numeric, time, or log scales.
+
+## Scale Types
+
+`XYChart` supports categorical, numeric, temporal, and logarithmic axes.
+
+### Time Scale
+
+Use `time` when the axis values are `Date` objects:
+
+```javascript
+const chart = new XYChart({
+    data: [
+        { date: new Date('2024-01-01'), value: 100 },
+        { date: new Date('2024-01-02'), value: 150 },
+        { date: new Date('2024-01-03'), value: 120 },
+    ],
+    scales: {
+        x: { type: 'time', nice: true },
+        y: { type: 'linear', nice: true },
+    },
+});
+```
+
+### Logarithmic Scale
+
+Use `log` for exponential data. Log scales require positive values and a
+strictly positive domain:
+
+```javascript
+const chart = new XYChart({
+    data: [
+        { x: 1, y: 10 },
+        { x: 2, y: 100 },
+        { x: 3, y: 1000 },
+        { x: 4, y: 10000 },
+    ],
+    scales: {
+        y: { type: 'log', domain: [1, 10000] },
+    },
+});
+```
+
+Bar series cannot use logarithmic value axes because bars always render from a
+zero baseline.
+
+### Custom Domains
+
+Set `domain` to override the automatic extent calculation:
+
+```javascript
+const chart = new XYChart({
+    data,
+    scales: {
+        y: {
+            type: 'linear',
+            domain: [0, 100],
+            nice: true,
+        },
+    },
+});
+```
+
+For bar charts, automatic numeric value domains always include `0`. If you set
+an explicit numeric domain or `min`/`max` for the bar value axis, that final
+domain must still include `0`.
+
+On horizontal bar charts, category order is controlled with `scales.x.reverse`
+because `x` remains the categorical dimension even when it renders vertically.
+
+## Responsive Overrides
+
+Use chart-level `responsive` to declare breakpoint-specific theme and component
+overrides before layout is calculated:
+
+```typescript
+const chart = new XYChart({
+    data,
+    responsive: {
+        breakpoints: {
+            sm: {
+                maxWidth: 640,
+                theme: {
+                    axis: {
+                        fontSize: 11,
+                    },
+                },
+                components: [
+                    {
+                        match: { type: 'xAxis' },
+                        override: {
+                            display: false,
+                        },
+                    },
+                ],
+            },
+            md: {
+                minWidth: 641,
+                maxWidth: 768,
+                theme: {
+                    axis: {
+                        fontSize: 12,
+                    },
+                },
+            },
+        },
+    },
+});
+```
+
+`minWidth` and `maxWidth` are both optional, but breakpoints that omit both are
+ignored. Multiple breakpoints can match at the same width; matching breakpoints
+merge in declaration order, so later entries win when they override the same
+values.
+
+If you need dynamic logic, `responsive.beforeRender` still runs before spacing
+is measured after declarative breakpoint overrides are merged. It receives
+`context.activeBreakpoints` with every match and `context.breakpoint` as the
+last matching breakpoint name.
+
+## Validation
+
+`XYChart` validates configuration and series data early:
+
+- `data` must be a non-empty array.
+- Series `dataKey` values must exist in the dataset.
+- Rendered series values must resolve to numeric values.
+- Log scales reject zero or negative domain values and zero or negative series values.
+- Bar series require a linear value axis and explicit numeric bar domains must include `0`.
+
+## Methods
+
+### addChild(component)
+
+Adds a component to the chart. Returns `this` for chaining.
+
+```javascript
+chart
+    .addChild(new XAxis({ dataKey: 'date' }))
+    .addChild(new YAxis())
+    .addChild(new Line({ dataKey: 'value' }));
+```
+
+### render(target)
+
+Renders the chart to a DOM element. Accepts a CSS selector or HTMLElement. Automatically sets up resize handling.
+
+```javascript
+chart.render('#chart-container');
+// or
+chart.render(document.getElementById('chart-container'));
+```
+
+### update(data)
+
+Updates the chart with new data and re-renders.
+
+```javascript
+chart.update(newData);
+```
+
+### destroy()
+
+Cleans up all resources, removes resize observer, and clears the chart from the DOM.
+
+```javascript
+chart.destroy();
+```
+
+---
+
+## 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)
+})
+```
+
+### Example
+
+```javascript
+// Auto-assigned colors
+chart.addChild(new Line({ dataKey: 'revenue' }));
+chart.addChild(new Line({ dataKey: 'expenses' }));
+
+// Manual colors
+chart.addChild(new Line({ dataKey: 'revenue', stroke: '#00ff00' }));
+chart.addChild(new Line({ dataKey: 'expenses', stroke: '#ff0000' }));
+```
+
+---
+
+## Scatter
+
+Renders a point-only scatter series on the chart.
+
+```typescript
+new Scatter({
+    dataKey: string,                 // Key in data objects for Y values (required)
+    stroke?: string,                 // Point color (auto-assigned if omitted)
+    pointSize?: number,              // Point radius in pixels (default: theme.line.point.size)
+    valueLabel?: { show?: boolean }  // Point value badges
+})
+```
+
+### Example
+
+```javascript
+chart.addChild(new Scatter({ dataKey: 'revenue' }));
+chart.addChild(new Scatter({ dataKey: 'expenses', pointSize: 7 }));
+```
+
+---
+
+## Bar
+
+Renders a bar series on the chart.
+
+```typescript
+new Bar({
+    dataKey: string,               // Key in data objects for values (required)
+    fill?: string,                 // Bar color (auto-assigned if omitted)
+    maxBarSize?: number,           // Max width/height depending on chart orientation
+    side?: 'left' | 'right',       // Mirror horizontal bars to the left without changing source data
+    valueLabel?: {
+        show?: boolean,
+        position?: 'inside' | 'outside',
+        insidePosition?: 'top' | 'middle' | 'bottom'
+    }
+})
+```
+
+### Example
+
+```javascript
+chart.addChild(new Bar({ dataKey: 'sales' }));
+chart.addChild(new Bar({ dataKey: 'returns', fill: '#ff6b6b' }));
+```
+
+Use `XYChart.orientation: 'horizontal'` for horizontal bar charts:
+
+```javascript
+const chart = new XYChart({
+    data,
+    orientation: 'horizontal',
+});
+
+chart
+    .addChild(new XAxis({ dataKey: 'metric' }))
+    .addChild(new YAxis())
+    .addChild(new Bar({ dataKey: 'current' }))
+    .addChild(new Bar({ dataKey: 'benchmark' }));
+```
+
+Horizontal and vertical bar charts now render from a true zero baseline. When a
+bar dataset contains both positive and negative values, bars automatically
+diverge around `0`.
+
+```javascript
+const chart = new XYChart({
+    data: [
+        { metric: 'Pricing', delta: -18 },
+        { metric: 'Feature set', delta: 24 },
+        { metric: 'Support', delta: 11 },
+    ],
+    orientation: 'horizontal',
+});
+
+chart
+    .addChild(new XAxis({ dataKey: 'metric' }))
+    .addChild(new YAxis())
+    .addChild(new Bar({ dataKey: 'delta' }));
+```
+
+Population-pyramid style charts can keep both series positive in source data and
+mirror one series to the left at render time:
+
+```javascript
+const chart = new XYChart({
+    data: [
+        {
+            source: 'Digitala tidningar/nyhetssajter',
+            yngre: '51%',
+            äldre: '19%',
+        },
+        {
+            source: 'Tv-kanal (SVT, TV4 etc.)',
+            yngre: '45%',
+            äldre: '86%',
+        },
+    ],
+    orientation: 'horizontal',
+    scales: {
+        y: { type: 'linear', min: -100, max: 100, nice: false },
+    },
+    barStack: { mode: 'normal' },
+});
+
+chart
+    .addChild(
+        new XAxis({
+            dataKey: 'source',
+            tickFormat: (value) => `${Math.abs(Number(value))}%`,
+        }),
+    )
+    .addChild(new YAxis())
+    .addChild(new Bar({ dataKey: 'yngre', side: 'left' }))
+    .addChild(new Bar({ dataKey: 'äldre' }));
+```
+
+Horizontal orientation currently supports bar-only charts. Mixed horizontal
+bar/line, bar/scatter, or bar/area charts are rejected.
+
+### Stacking Modes
+
+Bar charts support different stacking modes:
+
+- `none` - Bars side by side (default)
+- `normal` - Stacked bars
+- `percent` - 100% stacked bars
+- `layer` - Overlapping bars
+
+Use `barStack.reverseSeries: true` to reverse bar series display order for rendering, legend entries, and tooltip rows without changing data exports.
+
+---
+
+## Area
+
+Renders an area series on the chart.
+
+```typescript
+new Area({
+    dataKey: string,                // Key in data objects for Y values (required)
+    fill?: string,                  // Area fill color (auto-assigned if omitted)
+    stroke?: string,                // Optional line color (defaults to fill color)
+    opacity?: number,               // Fill opacity (default: 0.3)
+    curve?: 'linear' | 'monotone' | 'step' | 'natural' | 'basis' | 'cardinal',
+    stackId?: string | number,      // Group key used for area stacking
+    baseline?: number,              // Baseline for non-stacked area (default: 0)
+    showLine?: boolean,             // Show top stroke line (default: true)
+    showPoints?: boolean,           // Show points on top line (default: false)
+    valueLabel?: { show?: boolean } // Point value badges
+})
+```
+
+### Example
+
+```javascript
+chart.addChild(new Area({ dataKey: 'revenue' }));
+chart.addChild(
+    new Area({
+        dataKey: 'expenses',
+        fill: '#ff6b6b',
+        opacity: 0.2,
+        curve: 'monotone',
+        showPoints: true,
+    }),
+);
+```
+
+### Area Stacking
+
+Area charts support stacking when series share the same `stackId`:
+
+- `none` - No area stacking (default)
+- `normal` - Absolute stacking
+- `percent` - Normalized 100% stacking
+
+```javascript
+const chart = new XYChart({
+    data,
+    areaStack: { mode: 'percent' },
+});
+
+chart.addChild(new Area({ dataKey: 'desktop', stackId: 'traffic' })).addChild(new Area({ dataKey: 'mobile', stackId: 'traffic' }));
+```
+
+---
+
+## Mixed Charts
+
+Combine lines, scatter series, areas, and bars in the same chart:
+
+```javascript
+const chart = new XYChart({ data });
+
+chart
+    .addChild(new Bar({ dataKey: 'volume' }))
+    .addChild(new Scatter({ dataKey: 'orders' }))
+    .addChild(new Area({ dataKey: 'averageRange', opacity: 0.2 }))
+    .addChild(new Line({ dataKey: 'price' }));
+```

package/package.json

@@ -1,5 +1,5 @@
 {
-    "version": "0.9.2",
+    "version": "0.10.0",
     "name": "@internetstiftelsen/charts",
     "type": "module",
     "sideEffects": false,
@@ -12,6 +12,7 @@
     },
     "files": [
         "dist",
+        "docs",
         "README.md",
         "LICENSE"
     ],