@internetstiftelsen/charts 0.9.1 → 0.10.0

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
+- **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
 - **Radial Value Labels** - 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/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,11 +7,13 @@ 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;