@internetstiftelsen/charts 0.9.2 → 0.10.1

package/README.md

@@ -6,11 +6,15 @@ A framework-agnostic, composable charting library built on D3.js with TypeScript
 
 - **Framework Agnostic** - Works with vanilla JS, React, Vue, Svelte, or any framework
 - **Composable Architecture** - Build charts by composing components
-- **Multiple Chart Types** - XYChart (lines, areas, bars), WordCloudChart, DonutChart, PieChart, and GaugeChart
-- **Radial Value Labels** - Pie and donut charts support optional on-chart labels with custom formatters
+- **Multiple Chart Types** - XYChart (lines, scatter, areas, bars), WordCloudChart, DonutChart, PieChart, and GaugeChart
+- **Combined Chart Layouts** - `ChartGroup` composes existing charts into shared dashboards with one coordinated legend
+- **Divergent Bar Support** - Bar charts automatically render from zero and diverge around `0` for mixed positive/negative values
+- **Mirrored Bar Sides** - Horizontal bars can mirror a series to the left for population-pyramid style charts without changing source data
+- **Custom Value Labels** - XY, pie, and donut charts support optional on-chart labels with custom formatters
 - **Optional Gauge Animation** - Animate gauge value transitions with `gauge.animate`
 - **Stacking Control** - Bar stacking modes with optional reversed visual series order
-- **Flexible Scales** - Band, linear, time, and logarithmic scales
+- **Axis Direction Control** - Use `scales.x.reverse` / `scales.y.reverse` to flip an axis when needed
+- **Flexible Scales** - Band, linear, time, and logarithmic scales (bar value axes stay linear)
 - **Explicit or Responsive Sizing** - Set top-level `width`/`height` or let the container drive size
 - **Auto Resize** - Built-in ResizeObserver handles responsive behavior
 - **Responsive Policy** - Chart-level container-query overrides for theme and components
@@ -24,6 +28,22 @@ A framework-agnostic, composable charting library built on D3.js with TypeScript
 npm install @internetstiftelsen/charts
 ```
 
+## Agent Skill
+
+This repo also ships a Codex-compatible skill in
+`skills/build-internetstiftelsen-charts`.
+
+Install it globally for Codex with `skills.sh`:
+
+```bash
+npx skills add git@gitlab.com:internetstiftelsen/internal/webbgruppen/packages/charts.git \
+  -a codex \
+  -g \
+  --skill build-internetstiftelsen-charts
+```
+
+Restart Codex after installation so the new skill is discovered.
+
 ## Local Development
 
 ```bash
@@ -90,6 +110,119 @@ from the render container.
 Theme overrides are deep-partial, so nested overrides like
 `theme.axis.fontSize` preserve the rest of the theme defaults.
 
+## Chart Groups
+
+Use `ChartGroup` when you want to combine existing charts into one layout while
+keeping each child chart fully functional.
+
+```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');
+```
+
+Legend state now works even without mounting a `Legend` on each child chart, so
+grouped charts can share one coordinated legend while preserving child tooltip,
+axis, and responsive behavior. `ChartGroup.height` behaves like chart height:
+set it for a fixed total group height, or omit it to size from the render
+container. Set `syncY: true` when you want vertical `XYChart` children to share
+the same Y domain so grid lines stay aligned while only one child renders a
+visible Y axis.
+
+`ChartGroup` also supports declarative responsive layout overrides. Group
+breakpoints can change `cols` and `gap`, while `addChart(..., options)` can
+override `span`, `height`, `order`, or `hidden` per child. Just like chart
+responsive config, both `minWidth` and `maxWidth` are supported and all
+matching breakpoints merge in declaration order:
+
+```typescript
+const group = new ChartGroup({
+    cols: 3,
+    responsive: {
+        breakpoints: {
+            tablet: { maxWidth: 1023, cols: 2 },
+            mobile: { maxWidth: 640, cols: 1, gap: 16 },
+        },
+    },
+});
+
+group
+    .addChart(barChart, {
+        responsive: {
+            breakpoints: {
+                mobile: { maxWidth: 640, hidden: true },
+            },
+        },
+    })
+    .addChart(lineChart, {
+        span: 2,
+        responsive: {
+            breakpoints: {
+                mobile: { maxWidth: 640, span: 1, order: -1 },
+            },
+        },
+    });
+```
+
+## Divergent Bars
+
+Bar charts always render from a zero baseline. When bar data contains both
+positive and negative values, the bars automatically diverge around `0` in both
+vertical and horizontal orientations.
+
+```javascript
+import { XYChart } from '@internetstiftelsen/charts/xy-chart';
+import { Bar } from '@internetstiftelsen/charts/bar';
+import { XAxis } from '@internetstiftelsen/charts/x-axis';
+import { YAxis } from '@internetstiftelsen/charts/y-axis';
+
+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' }));
+```
+
+Automatic numeric bar domains always include `0`. If you configure an explicit
+numeric domain or `min`/`max` for the bar value axis, that final domain must
+still include `0`.
+
+Categorical `y` axes now preserve data order from top to bottom by default.
+Use `scales.x.reverse` or `scales.y.reverse` when you want to intentionally flip
+an axis direction.
+
 Responsive overrides are declarative and merge all matching breakpoints in
 declaration order:
 
@@ -211,6 +344,7 @@ Grouped parsing rules:
 
 - [Getting Started](./docs/getting-started.md) - Installation, Vanilla JS, React integration
 - [XYChart](./docs/xy-chart.md) - Line, area, and bar charts API
+- [ChartGroup](./docs/chart-group.md) - Combined chart layouts with a shared legend
 - [WordCloudChart](./docs/word-cloud-chart.md) - Word frequency visualization API
 - [DonutChart](./docs/donut-chart.md) - Donut/pie charts API
 - [PieChart](./docs/pie-chart.md) - Pie chart API

package/dist/area.d.ts

@@ -21,5 +21,7 @@ export declare class Area implements ChartComponent<AreaConfigBase> {
     createExportComponent(override?: Partial<AreaConfigBase>): ChartComponent<AreaConfigBase>;
     private getStackValues;
     render(plotGroup: Selection<SVGGElement, undefined, null, undefined>, data: DataItem[], xKey: string, x: D3Scale, y: D3Scale, parseValue: (value: unknown) => number, xScaleType: ScaleType | undefined, theme: ChartTheme, stackingContext?: AreaStackingContext, valueLabelLayer?: Selection<SVGGElement, undefined, null, undefined>): void;
+    private renderLinePath;
+    private renderPoints;
     private renderValueLabels;
 }

package/dist/area.js

@@ -199,43 +199,49 @@ export class Area {
             .attr('stroke', 'none')
             .attr('d', areaGenerator);
         if (this.showLine) {
-            const lineGenerator = line()
-                .defined((d) => d.valid)
-                .curve(curveFactory)
-                .x(getXPosition)
-                .y((d) => y(d.y1) || 0);
-            const lineStrokeWidth = this.strokeWidth ?? theme.line.strokeWidth;
-            plotGroup
-                .append('path')
-                .datum(areaData)
-                .attr('class', `area-line-${sanitizedKey}`)
-                .attr('fill', 'none')
-                .attr('stroke', this.stroke)
-                .attr('stroke-width', lineStrokeWidth)
-                .attr('d', lineGenerator);
+            this.renderLinePath(plotGroup, areaData, curveFactory, getXPosition, y, theme, sanitizedKey);
         }
         if (this.showPoints) {
-            const validData = areaData.filter((d) => d.valid);
-            const pointSize = this.pointSize ?? theme.line.point.size;
-            const pointStrokeWidth = theme.line.point.strokeWidth;
-            const pointStrokeColor = theme.line.point.strokeColor || this.stroke;
-            const pointColor = theme.line.point.color || this.stroke;
-            plotGroup
-                .selectAll(`.area-point-${sanitizedKey}`)
-                .data(validData)
-                .join('circle')
-                .attr('class', `area-point-${sanitizedKey}`)
-                .attr('cx', getXPosition)
-                .attr('cy', (d) => y(d.y1) || 0)
-                .attr('r', pointSize)
-                .attr('fill', pointColor)
-                .attr('stroke', pointStrokeColor)
-                .attr('stroke-width', pointStrokeWidth);
+            this.renderPoints(plotGroup, areaData, getXPosition, y, theme, sanitizedKey);
         }
         if (this.valueLabel?.show) {
             this.renderValueLabels(valueLabelLayer ?? plotGroup, areaData.filter((d) => d.valid), y, parseValue, theme, getXPosition);
         }
     }
+    renderLinePath(plotGroup, areaData, curveFactory, getXPosition, y, theme, sanitizedKey) {
+        const lineGenerator = line()
+            .defined((d) => d.valid)
+            .curve(curveFactory)
+            .x(getXPosition)
+            .y((d) => y(d.y1) || 0);
+        const lineStrokeWidth = this.strokeWidth ?? theme.line.strokeWidth;
+        plotGroup
+            .append('path')
+            .datum(areaData)
+            .attr('class', `area-line-${sanitizedKey}`)
+            .attr('fill', 'none')
+            .attr('stroke', this.stroke)
+            .attr('stroke-width', lineStrokeWidth)
+            .attr('d', lineGenerator);
+    }
+    renderPoints(plotGroup, areaData, getXPosition, y, theme, sanitizedKey) {
+        const validData = areaData.filter((d) => d.valid);
+        const pointSize = this.pointSize ?? theme.line.point.size;
+        const pointStrokeWidth = theme.line.point.strokeWidth;
+        const pointStrokeColor = theme.line.point.strokeColor || this.stroke;
+        const pointColor = theme.line.point.color || this.stroke;
+        plotGroup
+            .selectAll(`.area-point-${sanitizedKey}`)
+            .data(validData)
+            .join('circle')
+            .attr('class', `area-point-${sanitizedKey}`)
+            .attr('cx', getXPosition)
+            .attr('cy', (d) => y(d.y1) || 0)
+            .attr('r', pointSize)
+            .attr('fill', pointColor)
+            .attr('stroke', pointStrokeColor)
+            .attr('stroke-width', pointStrokeWidth);
+    }
     renderValueLabels(plotGroup, data, y, parseValue, theme, getXPosition) {
         const config = this.valueLabel;
         const fontSize = config.fontSize ?? theme.valueLabel.fontSize;
@@ -260,7 +266,9 @@ export class Area {
             if (!Number.isFinite(parsedValue)) {
                 return;
             }
-            const valueText = String(parsedValue);
+            const valueText = config.formatter
+                ? config.formatter(this.dataKey, parsedValue, d.data)
+                : String(parsedValue);
             const xPos = getXPosition(d);
             const yPos = y(d.y1) || 0;
             const tempText = labelGroup

package/dist/bar.d.ts

@@ -1,5 +1,5 @@
 import type { Selection } from 'd3';
-import type { BarConfig, BarStackingContext, BarValueLabelConfig, ChartTheme, D3Scale, DataItem, ScaleType, ExportHooks, BarConfigBase } from './types.js';
+import type { BarConfig, BarStackingContext, BarSide, BarValueLabelConfig, ChartTheme, D3Scale, DataItem, Orientation, ScaleType, ExportHooks, BarConfigBase } from './types.js';
 import type { ChartComponent } from './chart-interface.js';
 export declare class Bar implements ChartComponent<BarConfigBase> {
     readonly type: "bar";
@@ -7,14 +7,33 @@ export declare class Bar implements ChartComponent<BarConfigBase> {
     readonly fill: string;
     readonly colorAdapter?: (data: DataItem, index: number) => string;
     readonly maxBarSize?: number;
+    readonly side: BarSide;
     readonly valueLabel?: BarValueLabelConfig;
     readonly exportHooks?: ExportHooks<BarConfigBase>;
     constructor(config: BarConfig);
     getExportConfig(): BarConfigBase;
     createExportComponent(override?: Partial<BarConfigBase>): ChartComponent<BarConfigBase>;
+    getRenderedValue(value: number, orientation?: Orientation): number;
     render(plotGroup: Selection<SVGGElement, undefined, null, undefined>, data: DataItem[], xKey: string, x: D3Scale, y: D3Scale, parseValue: (value: unknown) => number, xScaleType?: ScaleType, theme?: ChartTheme, stackingContext?: BarStackingContext, orientation?: 'vertical' | 'horizontal'): void;
     private renderVertical;
     private renderHorizontal;
+    private resolveValueLabelConfig;
+    private resolveValueLabelPlacement;
+    private resolveValueLabelStyle;
+    private getValueLabelText;
+    private getBarColor;
+    private measureLabelBox;
+    private getLabelColor;
+    private appendValueLabel;
+    private getVerticalLabelPlacement;
+    private getVerticalOutsideLabelPlacement;
+    private getVerticalInsideLabelY;
+    private getHorizontalLabelPlacement;
+    private getHorizontalOutsideLabelPlacement;
+    private getHorizontalInsideLabelX;
+    private isHorizontalLabelWithinBounds;
+    private renderVerticalValueLabel;
+    private renderHorizontalValueLabel;
     private renderVerticalValueLabels;
     private renderHorizontalValueLabels;
 }