@internetstiftelsen/charts 0.9.2 → 0.10.0

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.