@internetstiftelsen/charts 0.0.1 → 0.0.3

package/README.md

@@ -0,0 +1,417 @@
+# Chart Library
+
+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
+
+## Installation
+
+```bash
+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 },
+];
+
+// 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
+
+// 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
+
+**`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"
+```
+
+## 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
+
+- **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)

package/bar.d.ts

@@ -1,6 +1,6 @@
 import type { Selection } from 'd3';
-import type { BarConfig, DataItem, ScaleType, Orientation } from './types';
-import type { ChartComponent } from '@/lib/chart-interface';
+import type { BarConfig, DataItem, ScaleType, Orientation } from './types.js';
+import type { ChartComponent } from './chart-interface.js';
 export declare class Bar implements ChartComponent {
     readonly type: "bar";
     readonly dataKey: string;

package/base-chart.d.ts

@@ -1,13 +1,13 @@
 import { type Selection } from 'd3';
-import type { DataItem, ChartTheme, AxisScaleConfig } from './types';
-import type { ChartComponent } from '@/lib/chart-interface';
-import type { XAxis } from './x-axis';
-import type { YAxis } from './y-axis';
-import type { Grid } from './grid';
-import type { Tooltip } from './tooltip';
-import type { Legend } from './legend';
-import type { Title } from './title';
-import { LayoutManager, type PlotAreaBounds } from './layout-manager';
+import type { DataItem, ChartTheme, AxisScaleConfig } from './types.js';
+import type { ChartComponent } from './chart-interface.js';
+import type { XAxis } from './x-axis.js';
+import type { YAxis } from './y-axis.js';
+import type { Grid } from './grid.js';
+import type { Tooltip } from './tooltip.js';
+import type { Legend } from './legend.js';
+import type { Title } from './title.js';
+import { LayoutManager, type PlotAreaBounds } from './layout-manager.js';
 export type BaseChartConfig = {
     data: DataItem[];
     theme?: Partial<ChartTheme>;

package/base-chart.js

@@ -1,7 +1,7 @@
 import { create } from 'd3';
-import { defaultTheme } from './theme';
-import { ChartValidator } from './validation';
-import { LayoutManager } from './layout-manager';
+import { defaultTheme } from './theme.js';
+import { ChartValidator } from './validation.js';
+import { LayoutManager } from './layout-manager.js';
 /**
  * Base chart class that provides common functionality for all chart types
  */

package/grid.d.ts

@@ -1,6 +1,6 @@
 import { type Selection } from 'd3';
-import type { GridConfig, ChartTheme } from './types';
-import type { ChartComponent } from '@/lib/chart-interface';
+import type { GridConfig, ChartTheme } from './types.js';
+import type { ChartComponent } from './chart-interface.js';
 export declare class Grid implements ChartComponent {
     readonly type: "grid";
     readonly horizontal: boolean;

package/layout-manager.d.ts

@@ -1,5 +1,5 @@
-import type { LayoutAwareComponent } from './chart-interface';
-import type { ChartTheme } from './types';
+import type { LayoutAwareComponent } from './chart-interface.js';
+import type { ChartTheme } from './types.js';
 export type PlotAreaBounds = {
     left: number;
     right: number;

package/legend.d.ts

@@ -1,8 +1,8 @@
 import { type Selection } from 'd3';
-import type { LegendConfig, ChartTheme } from './types';
-import type { Line } from './line';
-import type { Bar } from './bar';
-import type { LayoutAwareComponent, ComponentSpace } from '@/lib/chart-interface';
+import type { LegendConfig, ChartTheme } from './types.js';
+import type { Line } from './line.js';
+import type { Bar } from './bar.js';
+import type { LayoutAwareComponent, ComponentSpace } from './chart-interface.js';
 export declare class Legend implements LayoutAwareComponent {
     readonly type: "legend";
     readonly position: LegendConfig['position'];

package/legend.js

@@ -1,5 +1,4 @@
-import {} from 'd3';
-import { getSeriesColor } from './types';
+import { getSeriesColor } from './types.js';
 export class Legend {
     constructor(config) {
         Object.defineProperty(this, "type", {

package/line.d.ts

@@ -1,6 +1,6 @@
 import { type Selection } from 'd3';
-import type { LineConfig, DataItem, ScaleType } from './types';
-import type { ChartComponent } from '@/lib/chart-interface';
+import type { LineConfig, DataItem, ScaleType } from './types.js';
+import type { ChartComponent } from './chart-interface.js';
 export declare class Line implements ChartComponent {
     readonly type: "line";
     readonly dataKey: string;

package/package.json

@@ -1,7 +1,8 @@
 {
-    "version": "0.0.1",
+    "version": "0.0.3",
     "name": "@internetstiftelsen/charts",
     "type": "module",
+    "sideEffects": false,
     "exports": {
         "./*": {
             "types": "./*.d.ts",
@@ -10,7 +11,8 @@
     },
     "files": [
         "*.js",
-        "*.d.ts"
+        "*.d.ts",
+        "README.md"
     ],
     "scripts": {
         "dev": "vite",
@@ -18,7 +20,7 @@
         "lint": "eslint .",
         "preview": "vite preview",
         "build:lib": "tsc --project tsconfig.lib.json && tsc-alias --project tsconfig.lib.json",
-        "prepub": "rm -rf dist && npm run build:lib && cp package.json dist",
+        "prepub": "rm -rf dist && npm run build:lib && cp package.json dist && cp README.md dist",
         "pub": "npm run prepub && cd dist && npm publish --access public"
     },
     "dependencies": {

package/theme.d.ts

@@ -1,2 +1,2 @@
-import { type ChartTheme } from '@/lib/types';
+import { type ChartTheme } from './types.js';
 export declare const defaultTheme: ChartTheme;

package/theme.js

@@ -1,4 +1,3 @@
-import {} from '@/lib/types';
 export const defaultTheme = {
     width: 928,
     height: 600,

package/title.d.ts

@@ -1,6 +1,6 @@
 import { type Selection } from 'd3';
-import type { TitleConfig, ChartTheme } from './types';
-import type { LayoutAwareComponent, ComponentSpace } from './chart-interface';
+import type { TitleConfig, ChartTheme } from './types.js';
+import type { LayoutAwareComponent, ComponentSpace } from './chart-interface.js';
 export declare class Title implements LayoutAwareComponent {
     readonly type: "title";
     readonly text: string;

package/title.js

@@ -1,4 +1,3 @@
-import {} from 'd3';
 export class Title {
     constructor(config) {
         Object.defineProperty(this, "type", {

package/tooltip.d.ts

@@ -1,9 +1,9 @@
 import { type Selection } from 'd3';
-import type { TooltipConfig, DataItem, ChartTheme } from './types';
-import type { ChartComponent } from '@/lib/chart-interface';
-import type { Line } from './line';
-import type { Bar } from './bar';
-import type { PlotAreaBounds } from './layout-manager';
+import type { TooltipConfig, DataItem, ChartTheme } from './types.js';
+import type { ChartComponent } from './chart-interface.js';
+import type { Line } from './line.js';
+import type { Bar } from './bar.js';
+import type { PlotAreaBounds } from './layout-manager.js';
 export declare class Tooltip implements ChartComponent {
     readonly type: "tooltip";
     readonly formatter?: (dataKey: string, value: any, data: DataItem) => string;

package/tooltip.js

@@ -1,5 +1,5 @@
 import { pointer, select } from 'd3';
-import { getSeriesColor } from './types';
+import { getSeriesColor } from './types.js';
 export class Tooltip {
     constructor(config) {
         Object.defineProperty(this, "type", {

package/validation.d.ts

@@ -1,4 +1,4 @@
-import type { DataItem } from './types';
+import type { DataItem } from './types.js';
 export declare class ChartValidationError extends Error {
     constructor(message: string);
 }

package/x-axis.d.ts

@@ -1,6 +1,6 @@
 import { type Selection } from 'd3';
-import type { XAxisConfig, ChartTheme } from './types';
-import type { LayoutAwareComponent, ComponentSpace } from '@/lib/chart-interface';
+import type { XAxisConfig, ChartTheme } from './types.js';
+import type { LayoutAwareComponent, ComponentSpace } from './chart-interface.js';
 export declare class XAxis implements LayoutAwareComponent {
     readonly type: "xAxis";
     readonly dataKey?: string;

package/xy-chart.d.ts

@@ -1,5 +1,5 @@
-import { BaseChart, type BaseChartConfig } from './base-chart';
-import type { ChartComponent } from '@/lib/chart-interface';
+import { BaseChart, type BaseChartConfig } from './base-chart.js';
+import type { ChartComponent } from './chart-interface.js';
 export type XYChartConfig = BaseChartConfig;
 export declare class XYChart extends BaseChart {
     private readonly series;

package/xy-chart.js

@@ -1,7 +1,7 @@
 import { max, min, scaleBand, scaleLinear, scaleTime, scaleLog, } from 'd3';
-import { getSeriesColor } from './types';
-import { BaseChart } from './base-chart';
-import { ChartValidator } from './validation';
+import { getSeriesColor } from './types.js';
+import { BaseChart } from './base-chart.js';
+import { ChartValidator } from './validation.js';
 export class XYChart extends BaseChart {
     constructor(config) {
         super(config);

package/y-axis.d.ts

@@ -1,6 +1,6 @@
 import { type Selection } from 'd3';
-import type { ChartTheme, YAxisConfig } from './types';
-import type { LayoutAwareComponent, ComponentSpace } from '@/lib/chart-interface';
+import type { ChartTheme, YAxisConfig } from './types.js';
+import type { LayoutAwareComponent, ComponentSpace } from './chart-interface.js';
 export declare class YAxis implements LayoutAwareComponent {
     readonly type: "yAxis";
     private readonly tickPadding;