@internetstiftelsen/charts 0.1.1 → 0.3.0

package/README.md

@@ -4,15 +4,14 @@ A framework-agnostic, composable charting library built on D3.js with TypeScript
 
 ## Features
 
-- **Framework Agnostic**: Core library has zero framework dependencies - works with vanilla JS, React, Vue, Svelte, or any other framework
-- **Flexible Scale System**: Support for band, linear, time, and logarithmic scales
-- **Composable Architecture**: Build charts by composing components (lines, axes, grids, tooltips, legends, titles)
-- **Layout-Driven Design**: Components self-measure and automatically adjust chart dimensions
-- **Automatic Resize**: Built-in ResizeObserver handles responsive behavior automatically
-- **Type Safe**: Written in TypeScript with comprehensive type definitions
-- **Data Validation**: Built-in validation with helpful error messages
-- **Performance Optimized**: Data caching and minimized redundant calculations
-- **Automatic Color Assignment**: Smart color palette system with sensible defaults
+- **Framework Agnostic** - Works with vanilla JS, React, Vue, Svelte, or any framework
+- **Composable Architecture** - Build charts by composing components
+- **Multiple Chart Types** - XYChart (lines, bars) and DonutChart
+- **Flexible Scales** - Band, linear, time, and logarithmic scales
+- **Auto Resize** - Built-in ResizeObserver handles responsive behavior
+- **Type Safe** - Written in TypeScript with full type definitions
+- **Data Validation** - Built-in validation with helpful error messages
+- **Auto Colors** - Smart color palette with sensible defaults
 
 ## Installation
 
@@ -22,396 +21,41 @@ npm install @internetstiftelsen/charts
 
 ## Quick Start
 
-### 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';
 
-// 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 },
+    { date: '2023', revenue: 100, expenses: 80 },
+    { date: '2024', revenue: 150, expenses: 90 },
 ];
 
-// Create chart
 const chart = new XYChart({ data });
 
-// Add components
 chart
-    .addChild(new Title({ text: 'Revenue vs Expenses' }))
-    .addChild(new Grid({ horizontal: true, vertical: false }))
     .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
+    .addChild(new Line({ dataKey: 'revenue' }))
+    .addChild(new Line({ dataKey: 'expenses' }));
 
-// 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();
-```
-
-### With React (Demo Wrapper)
-
-```jsx
-import { useRef, useEffect } from 'react';
-import { XYChart, Line, Bar, XAxis, YAxis, Grid, Tooltip, Legend } from './charts';
-
-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({ horizontal: 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} />;
-}
-```
-
-## API Reference
-
-### XYChart
-
-The main chart class for creating XY-coordinate charts (line, bar, or mixed).
-
-#### Constructor
-
-```typescript
-new XYChart(config: XYChartConfig)
 ```
 
-**Config Options:**
-
-- `data: DataItem[]` - Array of data objects (required)
-- `theme?: Partial<ChartTheme>` - Theme customization
-    - `width: number` - Chart max-width in pixels (default: 928)
-    - `height: number` - Chart height in pixels (default: 600)
-    - `margins: { top, right, bottom, left }` - Base margins around plot area (default: { top: 20, right: 20, bottom: 30, left: 40 })
-    - `colorPalette: string[]` - Array of colors for auto-assignment
-    - `gridColor: string` - Grid line color (default: '#e0e0e0')
-    - `axis: { fontFamily, fontSize }` - Axis text styling
-- `scales?: AxisScaleConfig` - Scale configuration
-    - `x?: { type: 'band' | 'linear' | 'time' | 'log', domain?: any[], padding?: number, nice?: boolean }`
-    - `y?: { type: 'band' | 'linear' | 'time' | 'log', domain?: any[], padding?: number, nice?: boolean }`
-
-#### Methods
+## Documentation
 
-**`addChild(component: ChartComponent): this`**
-Adds a component to the chart (chainable).
-
-**`render(target: string): HTMLElement`**
-Renders the chart to a DOM element specified by CSS selector. Automatically sets up resize handling.
-
-**`update(data: DataItem[]): void`**
-Updates the chart with new data and re-renders.
-
-**`destroy(): void`**
-Cleans up all resources, removes resize observer, and clears the chart from the DOM.
-
-### Components
-
-#### 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)
-})
-```
-
-#### Bar
-
-Renders a bar series on the chart.
-
-```typescript
-new Bar({
-    dataKey: string,          // Key in data objects for Y values (required)
-    fill? : string,            // Bar color (auto-assigned if omitted)
-})
-```
-
-#### XAxis
-
-Renders the X axis.
-
-```typescript
-new XAxis({
-    dataKey? : string,  // Key in data objects for X values (auto-detected if omitted)
-})
-```
-
-#### YAxis
-
-Renders the Y axis.
-
-```typescript
-new YAxis({
-    tickFormat?: string | null,  // D3 format specifier (e.g., 's' for SI-prefix like "35k"). Default: null (no formatting)
-})
-```
-
-**Examples:**
-```javascript
-new YAxis()                         // Shows raw numbers: 35000
-new YAxis({ tickFormat: 's' })      // Shows SI-prefix: 35k
-new YAxis({ tickFormat: '$,' })     // Shows formatted: $35,000
-```
-
-#### Grid
-
-Renders grid lines.
-
-```typescript
-new Grid({
-    horizontal? : boolean,  // Show horizontal lines (default: true)
-    vertical? : boolean,    // Show vertical lines (default: true)
-})
-```
-
-#### Tooltip
-
-Renders interactive tooltips on hover.
-
-```typescript
-new Tooltip({
-    formatter? : (dataKey: string, value: any, data: DataItem) => string
-})
-```
-
-**Example formatter:**
-
-```javascript
-new Tooltip({
-    formatter: (dataKey, value, data) =>
-        `<strong>${dataKey}</strong><br/>Value: ${value}<br/>Date: ${data.date}`
-})
-```
-
-#### Legend
-
-Renders a legend for the chart.
-
-```typescript
-new Legend({
-    position?: 'bottom',      // Position (currently only 'bottom' supported)
-    marginTop?: number,       // Space above legend (default: 20)
-    marginBottom?: number,    // Space below legend (default: 10)
-})
-```
-
-#### Title
-
-Renders a title for the chart.
-
-```typescript
-new Title({
-    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)
-})
-```
-
-## Advanced Usage
-
-### Custom Scale Types
-
-Use time scales for temporal data:
-
-```javascript
-const chart = new XYChart({
-    data: [
-        { date: new Date('2024-01-01'), value: 100 },
-        { date: new Date('2024-01-02'), value: 150 },
-    ],
-    scales: {
-        x: { type: 'time', nice: true },
-        y: { type: 'linear', nice: true },
-    },
-});
-```
-
-Use logarithmic scales for exponential data:
-
-```javascript
-const chart = new XYChart({
-    data: [
-        { x: 1, y: 10 },
-        { x: 2, y: 100 },
-        { x: 3, y: 1000 },
-    ],
-    scales: {
-        y: { type: 'log', domain: [1, 10000] },
-    },
-});
-```
-
-### Custom Theming
-
-```javascript
-const chart = new XYChart({
-    data,
-    theme: {
-        width: 1200,           // Max-width (chart won't exceed this)
-        height: 600,
-        margins: {
-            top: 30,
-            right: 30,
-            bottom: 40,
-            left: 60,
-        },
-        colorPalette: ['#ff6b6b', '#4ecdc4', '#45b7d1', '#f7b731'],
-        gridColor: '#333333',
-        axis: {
-            fontFamily: 'Inter, sans-serif',
-            fontSize: '12',
-        },
-    },
-});
-```
-
-### Manual Color Assignment
-
-```javascript
-chart
-    .addChild(new Line({ dataKey: 'revenue', stroke: '#00ff00' }))
-    .addChild(new Line({ dataKey: 'expenses', stroke: '#ff0000' }));
-```
-
-### Responsive Charts
-
-Charts automatically resize with their container using ResizeObserver. The chart width adapts to the container up to the `theme.width` (which acts as max-width).
-
-```javascript
-// Container width: 500px → Chart width: 500px
-// Container width: 1200px → Chart width: 928px (theme default max-width)
-
-// Custom max-width
-const chart = new XYChart({
-    data,
-    theme: { width: 1200 },  // Chart won't exceed 1200px
-});
-```
-
-**No manual resize calls needed** - the chart automatically responds to container size changes!
-
-## Data Validation
-
-The library includes built-in validation with helpful error messages:
-
-```javascript
-// Empty data
-new XYChart({ data: [] });
-// Error: Data array cannot be empty
-
-// Missing dataKey
-new Line({ dataKey: 'nonexistent' });
-// Error: Line: dataKey "nonexistent" not found in data items at indices: 0, 1, 2
-
-// Invalid numeric data
-new Line({ dataKey: 'textField' });
-// Error: Line: No valid numeric values found for dataKey "textField"
-```
+- [Getting Started](./docs/getting-started.md) - Installation, Vanilla JS, React integration
+- [XYChart](./docs/xy-chart.md) - Line and bar charts API
+- [DonutChart](./docs/donut-chart.md) - Donut/pie charts API
+- [Components](./docs/components.md) - Axes, Grid, Tooltip, Legend, Title
+- [Theming](./docs/theming.md) - Colors, fonts, and styling
+- [Advanced](./docs/advanced.md) - Scales, TypeScript, architecture, performance
 
 ## Browser Support
 
 Modern browsers with ES6+ support. Uses D3.js v7.
 
-## TypeScript
-
-Full TypeScript support included:
-
-```typescript
-import type { DataItem, ChartTheme, LineConfig } from './charts/types';
-
-const data: DataItem[] = [
-    { x: 1, y: 100 },
-    { x: 2, y: 200 },
-];
-
-const config: LineConfig = {
-    dataKey: 'y',
-    stroke: '#8884d8',
-    strokeWidth: 2,
-};
-```
-
-## Architecture
-
-The library follows a composable, layout-driven design:
-
-- **BaseChart**: Abstract base class providing common functionality (lifecycle, rendering, validation)
-- **XYChart**: Concrete implementation for XY-coordinate charts (lines, bars, or mixed)
-- **LayoutManager**: Calculates component positions and plot area dimensions (D3 margin convention)
-- **LayoutAwareComponent**: Interface for self-measuring components (Title, Legend, Axes)
-- **Components**: Modular components that implement `ChartComponent` or `LayoutAwareComponent`
-- **Validation**: Centralized validation layer with `ChartValidator`
-- **Scales**: Flexible scale factory supporting multiple D3 scale types
-
-Key principles:
-- **Layout-driven**: Components report their space requirements, plot area adjusts automatically
-- **Separation of concerns**: Only the plot area (grid) scales; UI elements stay fixed size
-- **D3 conventions**: Follows D3's margin convention pattern for clean, predictable layouts
-
-This architecture makes it easy to add new chart types or series (Area, Scatter, etc.) by extending BaseChart or implementing new series components.
-
-## Performance
+## License
 
-- **Data Caching**: Sorted data is cached to avoid redundant sorting operations
-- **Smart Re-rendering**: Only re-renders when necessary (data updates or container resize)
-- **Automatic Cleanup**: ResizeObserver and tooltips properly cleaned up on destroy
-- **Minimal DOM Manipulation**: Uses D3's efficient data binding
-- **SVG Optimization**: Clean SVG generation with proper cleanup
-- **Small Bundle**: ~105 KB gzipped (including D3)
-- **Small Bundle**: ~105 KB gzipped (including D3)
+MIT

package/bar.js

@@ -387,7 +387,7 @@ export class Bar {
             const boxWidth = textBBox.width + padding * 2;
             const boxHeight = textBBox.height + padding * 2;
             const labelX = barCenterX;
-            let labelY;
+            let labelY = (barTop + barBottom) / 2; // Default to middle
             let shouldRender = true;
             if (position === 'outside') {
                 // Place above the bar
@@ -399,21 +399,76 @@ export class Bar {
                 }
             }
             else {
-                // Inside the bar
-                switch (insidePosition) {
-                    case 'top':
-                        labelY = barTop + boxHeight / 2 + 4;
-                        break;
-                    case 'middle':
-                        labelY = (barTop + barBottom) / 2;
-                        break;
-                    case 'bottom':
-                        labelY = barBottom - boxHeight / 2 - 4;
-                        break;
+                // Inside the bar - with special handling for layer mode
+                if (mode === 'layer') {
+                    const totalSeries = stackingContext?.totalSeries ?? 1;
+                    const seriesIndex = stackingContext?.seriesIndex ?? 0;
+                    const isTopLayer = seriesIndex === totalSeries - 1;
+                    switch (insidePosition) {
+                        case 'top':
+                            // For layer mode + inside + top: check if there's enough space in the gap
+                            if (seriesIndex < totalSeries - 1) {
+                                // Calculate the gap to the next layer
+                                const nextLayerScaleFactor = 1 - ((seriesIndex + 1) / totalSeries) * 0.7;
+                                const nextLayerWidth = (this.maxBarSize
+                                    ? Math.min(bandwidth, this.maxBarSize)
+                                    : bandwidth) * nextLayerScaleFactor;
+                                const gap = (barWidth - nextLayerWidth) / 2;
+                                const marginBelow = 4; // Minimum margin below text
+                                if (boxHeight + marginBelow <= gap) {
+                                    labelY =
+                                        barTop + boxHeight / 2 + marginBelow;
+                                }
+                                else {
+                                    shouldRender = false;
+                                }
+                            }
+                            else {
+                                // Top layer - use normal top position if it fits
+                                labelY = barTop + boxHeight / 2 + 4;
+                                if (boxHeight + 8 > barHeight) {
+                                    shouldRender = false;
+                                }
+                            }
+                            break;
+                        case 'middle':
+                            // For layer mode + inside + middle: only show what fits
+                            labelY = (barTop + barBottom) / 2;
+                            if (boxHeight + 8 > barHeight) {
+                                shouldRender = false;
+                            }
+                            break;
+                        case 'bottom':
+                            // For layer mode + inside + bottom: only show for top layer if it fits
+                            if (isTopLayer) {
+                                labelY = barBottom - boxHeight / 2 - 4;
+                                if (boxHeight + 8 > barHeight) {
+                                    shouldRender = false;
+                                }
+                            }
+                            else {
+                                shouldRender = false;
+                            }
+                            break;
+                    }
                 }
-                // Check if it fits inside the bar
-                if (boxHeight + 8 > barHeight) {
-                    shouldRender = false;
+                else {
+                    // Non-layer modes - use existing logic
+                    switch (insidePosition) {
+                        case 'top':
+                            labelY = barTop + boxHeight / 2 + 4;
+                            break;
+                        case 'middle':
+                            labelY = (barTop + barBottom) / 2;
+                            break;
+                        case 'bottom':
+                            labelY = barBottom - boxHeight / 2 - 4;
+                            break;
+                    }
+                    // Check if it fits inside the bar
+                    if (boxHeight + 8 > barHeight) {
+                        shouldRender = false;
+                    }
                 }
             }
             tempText.remove();
@@ -543,7 +598,7 @@ export class Bar {
             const textBBox = tempText.node().getBBox();
             const boxWidth = textBBox.width + padding * 2;
             const boxHeight = textBBox.height + padding * 2;
-            let labelX;
+            let labelX = (barLeft + barRight) / 2; // Default to middle
             const labelY = barCenterY;
             let shouldRender = true;
             if (position === 'outside') {
@@ -556,21 +611,78 @@ export class Bar {
                 }
             }
             else {
-                // Inside the bar - map top/middle/bottom to start/middle/end for horizontal
-                switch (insidePosition) {
-                    case 'top': // start of bar (left side)
-                        labelX = barLeft + boxWidth / 2 + 4;
-                        break;
-                    case 'middle':
-                        labelX = (barLeft + barRight) / 2;
-                        break;
-                    case 'bottom': // end of bar (right side)
-                        labelX = barRight - boxWidth / 2 - 4;
-                        break;
+                // Inside the bar - with special handling for layer mode
+                if (mode === 'layer') {
+                    const totalSeries = stackingContext?.totalSeries ?? 1;
+                    const seriesIndex = stackingContext?.seriesIndex ?? 0;
+                    const isTopLayer = seriesIndex === totalSeries - 1;
+                    // Map top/middle/bottom to start/middle/end for horizontal
+                    switch (insidePosition) {
+                        case 'top': // start of bar (left side)
+                            // For layer mode + inside + top(left): check if there's enough space in the gap
+                            if (seriesIndex < totalSeries - 1) {
+                                // Calculate the gap to the next layer
+                                const nextLayerScaleFactor = 1 - ((seriesIndex + 1) / totalSeries) * 0.7;
+                                const nextLayerHeight = (this.maxBarSize
+                                    ? Math.min(bandwidth, this.maxBarSize)
+                                    : bandwidth) * nextLayerScaleFactor;
+                                const gap = (barHeight - nextLayerHeight) / 2;
+                                const marginRight = 4; // Minimum margin to the right of text
+                                if (boxWidth + marginRight <= gap) {
+                                    labelX =
+                                        barLeft + boxWidth / 2 + marginRight;
+                                }
+                                else {
+                                    shouldRender = false;
+                                }
+                            }
+                            else {
+                                // Top layer - use normal left position if it fits
+                                labelX = barLeft + boxWidth / 2 + 4;
+                                if (boxWidth + 8 > barWidth) {
+                                    shouldRender = false;
+                                }
+                            }
+                            break;
+                        case 'middle':
+                            // For layer mode + inside + middle: only show what fits
+                            labelX = (barLeft + barRight) / 2;
+                            if (boxWidth + 8 > barWidth) {
+                                shouldRender = false;
+                            }
+                            break;
+                        case 'bottom': // end of bar (right side)
+                            // For layer mode + inside + bottom(right): only show for top layer if it fits
+                            if (isTopLayer) {
+                                labelX = barRight - boxWidth / 2 - 4;
+                                if (boxWidth + 8 > barWidth) {
+                                    shouldRender = false;
+                                }
+                            }
+                            else {
+                                shouldRender = false;
+                            }
+                            break;
+                    }
                 }
-                // Check if it fits inside the bar
-                if (boxWidth + 8 > barWidth) {
-                    shouldRender = false;
+                else {
+                    // Non-layer modes - use existing logic
+                    // Map top/middle/bottom to start/middle/end for horizontal
+                    switch (insidePosition) {
+                        case 'top': // start of bar (left side)
+                            labelX = barLeft + boxWidth / 2 + 4;
+                            break;
+                        case 'middle':
+                            labelX = (barLeft + barRight) / 2;
+                            break;
+                        case 'bottom': // end of bar (right side)
+                            labelX = barRight - boxWidth / 2 - 4;
+                            break;
+                    }
+                    // Check if it fits inside the bar
+                    if (boxWidth + 8 > barWidth) {
+                        shouldRender = false;
+                    }
                 }
             }
             tempText.remove();

package/base-chart.d.ts

@@ -1,6 +1,6 @@
 import { type Selection } from 'd3';
 import type { DataItem, ChartTheme, AxisScaleConfig, ExportFormat, ExportOptions, D3Scale } from './types.js';
-import type { ChartComponent } from './chart-interface.js';
+import type { ChartComponent, LayoutAwareComponent } from './chart-interface.js';
 import type { XAxis } from './x-axis.js';
 import type { YAxis } from './y-axis.js';
 import type { Grid } from './grid.js';
@@ -50,8 +50,9 @@ export declare abstract class BaseChart {
     private performRender;
     /**
      * Get layout-aware components in order
+     * Override in subclasses to provide chart-specific components
      */
-    private getLayoutComponents;
+    protected getLayoutComponents(): LayoutAwareComponent[];
     /**
      * Setup ResizeObserver for automatic resize handling
      */

package/base-chart.js

@@ -167,6 +167,7 @@ export class BaseChart {
     }
     /**
      * Get layout-aware components in order
+     * Override in subclasses to provide chart-specific components
      */
     getLayoutComponents() {
         const components = [];
@@ -237,9 +238,7 @@ export class BaseChart {
      * @returns The exported content as a string if download is false/undefined, void if download is true
      */
     export(format, options) {
-        const content = format === 'svg'
-            ? this.exportSVG()
-            : this.exportJSON();
+        const content = format === 'svg' ? this.exportSVG() : this.exportJSON();
         if (options?.download) {
             this.downloadContent(content, format, options);
             return;
@@ -250,9 +249,7 @@ export class BaseChart {
      * Downloads the exported content as a file
      */
     downloadContent(content, format, options) {
-        const mimeType = format === 'svg'
-            ? 'image/svg+xml'
-            : 'application/json';
+        const mimeType = format === 'svg' ? 'image/svg+xml' : 'application/json';
         const blob = new Blob([content], { type: mimeType });
         const url = URL.createObjectURL(blob);
         const link = document.createElement('a');