@blueprint-chart/docs 0.1.18

package/src/charts/bar-multi.md

@@ -0,0 +1,64 @@
+---
+title: Multi-series bar chart
+---
+
+# Multi-series bar chart
+
+> Multi-series vertical bar chart for side-by-side comparison of a small group of series.
+
+`bar-multi` places several series next to each other within each category, so readers can compare them at a glance. Honours `sort`, `sortMode`, `valueLabels`, and `valueLabelPosition`.
+
+## When to use
+
+- Comparing 2–3 series across the same categories (e.g. medals by colour, revenue by product line)
+- When individual series values matter more than their totals
+- A small, fixed set of categories where the comparison is the story
+
+## When NOT to use
+
+- More than 3–4 series per group — the clusters become unreadable
+- When the total across series is the headline number — use [`bar-stacked`](./bar-stacked) or [`column-stacked`](./column-stacked)
+- When the second dimension is itself a grouping (use [`bar-grouped`](./bar-grouped))
+
+## Example
+
+```bpc
+chart bar-multi {
+  title = "USA tops Paris 2024 with 126 medals across all categories"
+  description = "2024 Paris Summer Games — top six nations"
+  source = "Olympics.com"
+  sourceUrl = "https://olympics.com"
+  colors = "#eeca3b, #c0c0c0, #cd7f32"
+  legendPosition = "top"
+  valueLabels = true
+  sort = descending
+
+  data {
+    _series = "Gold","Silver","Bronze"
+    "USA" = 40,44,42
+    "China" = 38,32,18
+    "Japan" = 27,14,17
+    "Great Britain" = 22,21,22
+    "Australia" = 17,7,22
+    "France" = 16,20,23
+  }
+}
+```
+
+
+## Common pitfalls
+
+- Too many bars per group overwhelms the reader; cap at 3–4 series
+- Inconsistent colour encoding across charts in the same dashboard
+- Sorting by the wrong series — make sure the sort matches the comparison you want readers to make
+
+## Related types
+
+- [`bar-grouped`](./bar-grouped) — when the categories themselves cluster into a higher group
+- [`bar-stacked`](./bar-stacked) — when the total across series is the headline
+- [`column-stacked`](./column-stacked) — composition over a small number of discrete columns
+
+## See also
+
+- [Choosing the right chart](/handbook/choosing)
+- [Design principles](/handbook/design-principles)

package/src/charts/bar-split.md

@@ -0,0 +1,61 @@
+---
+title: Split bar chart
+---
+
+# Split bar chart
+
+> Diverging vertical bar chart for values around a shared baseline (positive/negative).
+
+`bar-split` plots values that radiate out from a shared baseline — positive and negative, gain and loss, opinion for and against. It uses signed values directly; no explicit "diverging" toggle is required.
+
+## When to use
+
+- Net change scenarios where some values are positive and some are negative (sentiment, election swing, year-on-year deltas)
+- Polling spreads and ranges around a central estimate
+- Comparing a small group of categories where direction is part of the story
+
+## When NOT to use
+
+- All-positive datasets — a regular [`bar-vertical`](./bar-vertical) reads more cleanly
+- When the absolute total is what matters, not the spread
+- Many categories with subtle differences — the diverging baseline amplifies noise
+
+## Example
+
+```bpc
+chart bar-split {
+  title = "Phoenix summers hit 37 °C while Chicago winters drop below zero"
+  description = "Mean monthly temperature (°C), NOAA 30-year climate normals 1991–2020"
+  source = "NOAA"
+  sourceUrl = "https://www.ncei.noaa.gov/products/land-based-station/us-climate-normals"
+  valueLabels = true
+
+  data {
+    _series = "Winter (Jan)","Spring (Apr)","Summer (Jul)"
+    "Miami"       = 20,26,29
+    "Los Angeles" = 14,17,23
+    "Phoenix"     = 13,24,37
+    "Seattle"     = 5,10,19
+    "New York"    = 1,12,25
+    "Chicago"     = -4,10,24
+  }
+}
+```
+
+
+## Common pitfalls
+
+- Forgetting that the chart is encoding sign; readers should be able to tell what zero means without reading the axis label
+- Mixing categories that don't share the same scale or meaning around the baseline
+- Sorting that hides the diverging pattern — sort by net change, not by absolute value
+
+## Related types
+
+- [`bar-vertical`](./bar-vertical) — when all values share the same sign
+- [`bar-multi`](./bar-multi) — when you need side-by-side comparison rather than divergence
+- [`bar-stacked`](./bar-stacked) — when the parts of each bar sum to a meaningful total
+
+## See also
+
+- [Choosing the right chart](/handbook/choosing)
+- [Design principles](/handbook/design-principles)

package/src/charts/bar-stacked.md

@@ -0,0 +1,62 @@
+---
+title: Stacked bar chart
+---
+
+# Stacked bar chart
+
+> Stacked horizontal bar chart for composition within a category, emphasising the total.
+
+`bar-stacked` segments horizontal bars into subcategories, showing both the individual parts and the total. Honours `stackMode` and `stackPercent` — flip to a 100 % view for pure composition.
+
+## When to use
+
+- Showing how a total breaks down into parts
+- Comparing totals across categories while keeping the composition visible
+- 100 % stacked view (`stackPercent = true`) when relative proportions matter more than absolute values
+- Categories with long labels that suit the horizontal orientation
+
+## When NOT to use
+
+- When comparing individual segments across categories — only the segment on the baseline is easy to read
+- When there are many small segments — they become invisible
+- When precise segment-to-segment comparison is needed (use [`bar-multi`](./bar-multi) or [`bar-grouped`](./bar-grouped))
+
+## Example
+
+```bpc
+chart bar-stacked {
+  title = "India's working-age population now surpasses China's"
+  description = "Millions of people, 2023"
+  source = "UN Population Division"
+  sourceUrl = "https://population.un.org"
+  horizontalGridStyle = none
+  horizontalLabelPosition = off
+
+  data {
+    _series = "0-14","15-64","65+"
+    "China" = 249,987,191
+    "India" = 365,948,100
+    "USA" = 60,215,58
+    "Indonesia" = 66,191,18
+    "Brazil" = 42,150,22
+  }
+}
+```
+
+
+## Common pitfalls
+
+- Segments not on the baseline are nearly impossible to compare accurately — put the most important segment first
+- Too many segments create visual noise without insight — cap at 3–5 and group the rest into "Other"
+- Inconsistent segment ordering across bars breaks the visual rhythm
+
+## Related types
+
+- [`column-stacked`](./column-stacked) — vertical equivalent for time-like x-axes
+- [`bar-multi`](./bar-multi) — when you'd rather compare series side by side than stack them
+- [`bar-horizontal`](./bar-horizontal) — single-series horizontal bars
+
+## See also
+
+- [Choosing the right chart](/handbook/choosing)
+- [Design principles](/handbook/design-principles)

package/src/charts/bar-vertical.md

@@ -0,0 +1,71 @@
+---
+title: Vertical bar chart
+---
+
+# Vertical bar chart
+
+> Single-series vertical bar chart for ranked categorical comparison, small N.
+
+`bar-vertical` compares discrete categories using the height of rectangular bars. It honours `sort`, `sortMode`, `valueLabels`, and `valueLabelPosition`. The alias `vertical-bar` is registered against the same renderer so `.bpc` documents can read either way.
+
+## When to use
+
+- Comparing quantities across a small number of categories (< 12)
+- Ranking items when the category labels are short enough to fit horizontally
+- A few data points over time (e.g. annual totals for 5 years)
+
+## When NOT to use
+
+- Continuous data distributions (no built-in histogram type)
+- Many time periods — use [`line`](./line) for trends
+- Long category labels that would need rotation — use [`bar-horizontal`](./bar-horizontal)
+
+## Example
+
+```bpc
+chart bar-vertical {
+  title = "Brazil produces more coffee than the next three countries combined"
+  description = "Million 60-kg bags, 2023/24 crop year"
+  source = "International Coffee Organization"
+  sourceUrl = "https://ico.org"
+  colorPalette = "Harvey"
+  valueLabels = true
+  valueLabelPosition = "auto"
+
+  data {
+    "Brazil" = 66.4
+    "Vietnam" = 29
+    "Colombia" = 11.4
+    "Indonesia" = 9.9
+    "Ethiopia" = 8.7
+    "Honduras" = 6.3
+  }
+
+  colorize "Brazil" {
+    color = "#a4432d"
+  }
+
+  transform sort {
+    column = "value"
+    direction = descending
+  }
+}
+```
+
+
+## Common pitfalls
+
+- Truncating the y-axis exaggerates differences and misleads readers — always start at zero
+- Too many categories create visual clutter; group small ones into "Other"
+- 3D effects distort the encoding — Blueprint Chart doesn't offer them, and you shouldn't fake them
+
+## Related types
+
+- [`bar-horizontal`](./bar-horizontal) — when labels are long or you want a ranked list
+- [`bar-multi`](./bar-multi) — when you need to compare two or more series side by side
+- [`bar-stacked`](./bar-stacked) — when the parts of each bar sum to a meaningful total
+
+## See also
+
+- [Choosing the right chart](/handbook/choosing)
+- [Design principles](/handbook/design-principles)

package/src/charts/column-stacked.md

@@ -0,0 +1,57 @@
+---
+title: Stacked column chart
+---
+
+# Stacked column chart
+
+> Stacked vertical column chart for composition over discrete columns; supports percent stacking.
+
+`column-stacked` is the vertical sibling of [`bar-stacked`](./bar-stacked) — each column breaks down into segments. It's the right choice when the x-axis represents a small number of ordered steps (quarters, fiscal years, study cohorts). Honours `stackMode` and `stackPercent`.
+
+## When to use
+
+- Composition over a small number of discrete columns (5–10 quarters, years, or stages)
+- When both the total and the breakdown matter for each column
+- 100 % stacked view (`stackPercent = true`) when readers should focus on relative share
+
+## When NOT to use
+
+- More than ~10 time points — switch to [`area-stacked`](./area-stacked)
+- Data with negative values — stacking breaks down
+- When precise segment-to-segment comparison is needed across columns
+
+## Example
+
+```bpc
+chart column-stacked {
+  title = "Software revenue grew steadily while hardware spiked in Q4"
+  description = "Quarterly revenue in millions, 2024"
+  source = "Annual report"
+
+  data {
+    _series = "Hardware","Software","Services"
+    "Q1" = 120,85,45
+    "Q2" = 135,92,48
+    "Q3" = 128,98,52
+    "Q4" = 155,105,58
+  }
+}
+```
+
+
+## Common pitfalls
+
+- Stacking too many series — the top layers float and lose their baseline
+- Switching to `stackPercent = true` without telling the reader hides the change in absolute total
+- Inconsistent segment ordering between columns destroys the visual flow
+
+## Related types
+
+- [`bar-stacked`](./bar-stacked) — horizontal equivalent for long category labels
+- [`area-stacked`](./area-stacked) — same idea with many time points
+- [`bar-multi`](./bar-multi) — when you want side-by-side comparison instead of stacking
+
+## See also
+
+- [Choosing the right chart](/handbook/choosing)
+- [Design principles](/handbook/design-principles)

package/src/charts/donut.md

@@ -0,0 +1,66 @@
+---
+title: Donut chart
+---
+
+# Donut chart
+
+> Circular part-to-whole chart with a central label slot.
+
+`donut` is a pie chart with the centre removed, opening a slot for a total, key metric, or icon. Honours `displayAsPercentage`, `showTotal`, `showLabels`, `showValues`, `sliceMax`, and `sliceGroupLabel`.
+
+## When to use
+
+- Same situations as a [`pie`](./pie) chart, but where a central metric adds context (total value, share of target, KPI badge)
+- Editorial layouts where the modern aesthetic suits the surrounding design
+- When arc length needs to read slightly more cleanly than wedge area
+
+## When NOT to use
+
+- More than 5–6 slices — use `sliceMax` to merge the tail into "Other"
+- Comparing several donut charts against each other (small multiples of bar charts win)
+- When precise value reading matters
+
+## Example
+
+```bpc
+chart donut {
+  title = "Coal still generates a third of the world's electricity"
+  description = "Share by source, 2024"
+  source = "IEA"
+  sourceUrl = "https://iea.org"
+  byline = "Pierre Romera"
+  note = "Percentages may not sum to 100 due to rounding"
+  colors = "#76b7b2, #4e79a7, #59a14f, #f28e2b, #edc949, #e15759, #b07aa1"
+  legendPosition = "right"
+  tooltips = true
+  displayAsPercentage = true
+
+  data {
+    "Coal" = 34.2
+    "Natural Gas" = 22.1
+    "Hydro" = 14.8
+    "Nuclear" = 9.4
+    "Wind" = 9.5
+    "Solar" = 6.2
+    "Other" = 3.8
+  }
+}
+```
+
+
+## Common pitfalls
+
+- Filling the centre slot with decoration instead of a meaningful metric wastes the chart's main affordance
+- Inner radius too thin reads like a pie; too thick collapses the ring into a stripe
+- Same caveats as a pie: too many slices, similar sizes, and side-by-side comparisons all hurt readability
+
+## Related types
+
+- [`pie`](./pie) — when there's no central metric worth showing
+- [`bar-horizontal`](./bar-horizontal) — when precise comparison matters
+- [`bar-stacked`](./bar-stacked) — composition across several totals
+
+## See also
+
+- [Choosing the right chart](/handbook/choosing)
+- [Design principles](/handbook/design-principles)

package/src/charts/index.md

@@ -0,0 +1,36 @@
+---
+title: Chart Types
+---
+
+# Chart Types
+
+Blueprint Chart ships 13 chart types organized into four families: bar, line, area, and part-to-whole.
+
+## Bar family
+
+- [`bar-vertical`](./bar-vertical) — single-series vertical bars; ranked categorical comparison
+- [`bar-horizontal`](./bar-horizontal) — single-series horizontal bars; long labels
+- [`bar-multi`](./bar-multi) — multi-series side-by-side bars
+- [`bar-grouped`](./bar-grouped) — grouped clusters across a second dimension
+- [`bar-split`](./bar-split) — diverging values around a shared baseline
+- [`bar-stacked`](./bar-stacked) — stacked horizontal bars; composition emphasising the total
+- [`column-stacked`](./column-stacked) — stacked vertical columns; supports percent stacking
+
+## Line family
+
+- [`line`](./line) — single-series trend over an ordered domain
+- [`line-multi`](./line-multi) — multi-series time-series comparison
+
+## Area family
+
+- [`area`](./area) — single-series magnitude over time
+- [`area-stacked`](./area-stacked) — composition over time; supports percent stacking
+
+## Part-to-whole
+
+- [`pie`](./pie) — circular part-to-whole, very small N
+- [`donut`](./donut) — circular part-to-whole with a central label slot
+
+::: tip Choosing the right chart
+Not sure which type fits your data? Start with the decision framework in the [choosing the right chart](/handbook/choosing) handbook entry.
+:::

package/src/charts/line-multi.md

@@ -0,0 +1,64 @@
+---
+title: Multi-line chart
+---
+
+# Multi-line chart
+
+> Multi-series line chart for comparing several time series or trends.
+
+`line-multi` plots two or more series on shared axes so readers can see divergence, convergence, and ranking shifts over an ordered domain. Supports `interpolation`, `lineSymbols`, `crosshair`, and `tooltips`.
+
+## When to use
+
+- Comparing trends across 2–4 series on the same scale
+- Showing divergence or convergence between groups over time
+- Highlighting one key series against grey "context" lines
+
+## When NOT to use
+
+- More than 5–6 series — the chart becomes a spaghetti tangle
+- Series with very different scales (avoid dual axes; consider small multiples instead)
+- Composition over time, where readers need to see how parts add up (use [`area-stacked`](./area-stacked))
+
+## Example
+
+```bpc
+chart line-multi {
+  title = "Germany stagnated while the US and China bounced back"
+  description = "Annual percentage change in real GDP"
+  source = "IMF World Economic Outlook"
+  sourceUrl = "https://imf.org"
+  colorPalette = "SolLeWitt"
+  legend = false
+  tooltips = true
+
+  data {
+    _series = "United States","China","Germany"
+    "2018" = 2.9,6.7,1.0
+    "2019" = 2.3,6.0,1.1
+    "2020" = -2.8,2.2,-3.7
+    "2021" = 5.9,8.4,3.2
+    "2022" = 2.1,3.0,1.8
+    "2023" = 2.5,5.2,-0.1
+    "2024" = 2.8,5.0,-0.2
+  }
+}
+```
+
+
+## Common pitfalls
+
+- Five or more lines crossing each other defeats the chart — either highlight one and grey the rest, or split into small multiples
+- Two y-axes with different scales imply a correlation that may not exist
+- Inconsistent colour assignment between charts in the same story confuses readers
+
+## Related types
+
+- [`line`](./line) — when you only need a single series
+- [`area-stacked`](./area-stacked) — when the running total across series matters
+- [`bar-grouped`](./bar-grouped) — when the x-axis is categorical, not continuous
+
+## See also
+
+- [Choosing the right chart](/handbook/choosing)
+- [Design principles](/handbook/design-principles)

package/src/charts/line.md

@@ -0,0 +1,65 @@
+---
+title: Line chart
+---
+
+# Line chart
+
+> Single-series line chart for continuous trend over an ordered domain.
+
+`line` connects data points to show how a single measure changes across an ordered axis — typically time. It supports `interpolation`, `lineSymbols`, `crosshair`, and `tooltips`.
+
+## When to use
+
+- Showing trends, patterns, or changes over time
+- Continuous data where the order matters
+- Revealing rate of change — the slope communicates speed
+- A single series; readers focus on direction rather than precise totals
+
+## When NOT to use
+
+- Categorical data with no inherent order — lines imply sequence
+- When the cumulative magnitude matters more than the trend (use [`area`](./area))
+- When you want to compare two or more series (use [`line-multi`](./line-multi))
+
+## Example
+
+```bpc
+chart line {
+  title = "2024 was the hottest year on record"
+  description = "Deviation from the 1951–1980 average, in °C"
+  source = "NASA GISS"
+  sourceUrl = "https://data.giss.nasa.gov/gistemp/"
+  colors = "#e15759"
+  interpolation = "monotoneX"
+  lineSymbols = true
+  lineSymbolShowOn = "firstLast"
+  tooltips = true
+
+  data {
+    "1980" = 0.26
+    "1990" = 0.45
+    "2000" = 0.42
+    "2010" = 0.72
+    "2020" = 1.02
+    "2024" = 1.29
+  }
+}
+```
+
+
+## Common pitfalls
+
+- Aggressively truncating the y-axis exaggerates small movements
+- Forcing the y-axis to start at zero when the data sits in a narrow band flattens the trend — unlike bars, line charts don't require a zero baseline
+- Smoothing with `basis` interpolation can overshoot the data; prefer `monotoneX` when fidelity matters
+
+## Related types
+
+- [`line-multi`](./line-multi) — when you need to compare two or more series on the same axes
+- [`area`](./area) — when the magnitude of the value matters as much as the trend
+- [`bar-vertical`](./bar-vertical) — when the x-axis is categorical, not continuous
+
+## See also
+
+- [Choosing the right chart](/handbook/choosing)
+- [Design principles](/handbook/design-principles)

package/src/charts/pie.md

@@ -0,0 +1,63 @@
+---
+title: Pie chart
+---
+
+# Pie chart
+
+> Circular part-to-whole chart for very small N.
+
+`pie` divides a circle into proportional slices, each representing a category's share of the whole. Honours `displayAsPercentage`, `showTotal`, `showLabels`, `showValues`, `sliceMax`, and `sliceGroupLabel`.
+
+## When to use
+
+- Simple proportional splits with 2–5 categories
+- Values near visually meaningful fractions (25 %, 50 %, 75 %)
+- General audiences where the chart needs to carry emotional weight
+- Sidebar or callout context — not the main analytical chart
+
+## When NOT to use
+
+- More than 5 categories — small slices become meaningless; consider grouping with `sliceMax` and `sliceGroupLabel`
+- Comparing similar-sized portions — the human eye is poor at judging angles
+- Comparing multiple pie charts against each other (use small multiples of bar charts instead)
+- When precise values matter — a bar chart is almost always more readable
+
+## Example
+
+```bpc
+chart pie {
+  title = "Asia is home to nearly 60% of the world's population"
+  description = "Estimated share, 2024"
+  source = "United Nations"
+  sourceUrl = "https://population.un.org"
+  colorPalette = "Klimt"
+  legendPosition = "right"
+  tooltips = true
+
+  data {
+    "Asia" = 59.4
+    "Africa" = 18.3
+    "Europe" = 9.3
+    "Latin America" = 8.2
+    "North America" = 4.8
+  }
+}
+```
+
+
+## Common pitfalls
+
+- Too many slices destroy readability — cap at five and use `sliceMax` to merge the tail
+- Exploded or 3D pie effects distort proportions; Blueprint Chart doesn't render them, and you shouldn't approximate them elsewhere
+- As Edward Tufte famously noted: the only thing worse than a pie chart is several of them
+
+## Related types
+
+- [`donut`](./donut) — same encoding with a central slot for a total or label
+- [`bar-horizontal`](./bar-horizontal) — almost always more readable for precise comparison
+- [`bar-stacked`](./bar-stacked) — when you want composition across several totals
+
+## See also
+
+- [Choosing the right chart](/handbook/choosing)
+- [Design principles](/handbook/design-principles)