@blueprint-chart/docs 0.1.18

package/src/guide/embed.md

@@ -0,0 +1,208 @@
+# Embedding Charts
+
+Blueprint Chart is **static-first**: every chart is a self-contained artifact independent of any vendor server. There are three ways to put one on a page, and they all run entirely in the browser.
+
+::: tip Data sovereignty
+Charts render in-page (or in a sandboxed `srcdoc` iframe). Data never leaves the visitor's browser by default — no backend call, no analytics ping, no third-party SaaS. This is a structural property, not a marketing claim.
+:::
+
+## Option 1 — Drop in a `<script>` tag
+
+The simplest path. Load the standalone runtime once per page, then add one `<script type="application/blueprint-chart">` per chart.
+
+```html
+<script src="https://unpkg.com/@blueprint-chart/lib/dist/lib/lib.iife.js"></script>
+
+<script type="application/blueprint-chart">
+  chart line-multi {
+    title = "Wind and solar are catching up to hydroelectric power"
+    description = "Share of electricity generation by source (%)"
+    source = "IEA"
+    sourceUrl = "https://iea.org"
+    colors = "#59a14f, #edc949, #4e79a7"
+    legend = false
+    lineSymbols = true
+    lineSymbolShowOn = "last"
+    tooltips = true
+
+    data {
+      _series = "Hydro","Wind","Solar"
+      "2010" = 16.0,1.6,0.3
+      "2012" = 16.2,2.4,0.6
+      "2014" = 16.3,3.3,1.1
+      "2016" = 16.4,4.0,1.5
+      "2018" = 15.8,4.8,2.4
+      "2020" = 16.8,6.2,3.7
+      "2022" = 15.0,7.8,4.5
+      "2024" = 14.8,9.5,6.2
+    }
+  }
+</script>
+```
+
+::: tip From the sample library
+This is `packages/lib/src/samples/renewable-energy.bpc` — a multi-series line with explicit per-series colours and a single trailing symbol on the last datapoint of each series. Pasted verbatim into a page, it renders to a self-contained iframe with no extra wiring.
+:::
+
+The runtime auto-runs on `DOMContentLoaded`, finds every chart script tag, and replaces it with a sandboxed iframe (`sandbox="allow-scripts"`) sized via `postMessage` to match the rendered chart.
+
+### Re-running after a dynamic insert
+
+If you insert chart scripts after page load (SPA navigation, late-injected content) call the runtime explicitly:
+
+```html
+<script>
+  // Available globally as `BlueprintChart` when loaded via the IIFE bundle.
+  BlueprintChart.initBlueprint()
+</script>
+```
+
+## Option 2 — Embed export from the editor
+
+The hosted editor at [blueprintchart.com](https://blueprintchart.com) ships an **Embed** export tab that produces a ready-to-paste snippet — runtime script tag + the chart source — that you can drop directly into any HTML page, CMS rich-text block, or newsletter template.
+
+Choose **Embed** in the export panel and copy the snippet. Nothing else needs to be installed on the host page.
+
+## Option 3 — Programmatic ESM API
+
+For full control — server-side rendering, custom render passes, or wiring into your own component framework — use the ESM API directly.
+
+```ts
+import {
+  parse,
+  buildChartOptions,
+  parseData,
+  registerChart,
+  getChart,
+} from '@blueprint-chart/lib'
+
+const ast = parse(source)            // BPC text → AST
+const data = parseData(ast)          // AST → ChartData
+const options = buildChartOptions(ast) // AST → ChartOptions
+
+const renderer = getChart(ast.chartType) // → ChartRenderer
+renderer.render({ data, options, container })
+```
+
+See the [API reference](/reference/api/) for the full surface area, including frame/canvas/legend primitives and the chart-type registry.
+
+## Static-site integrations
+
+Each integration is a thin wrapper around the runtime script tag. Current status:
+
+| Generator | Status | Notes |
+| --- | --- | --- |
+| Plain HTML | ✅ Ships in `lib` | The `<script>` pattern above. |
+| Hugo       | ⏳ Planned | Phase 2 GTM deliverable. Shortcode wrapping the runtime. |
+| Astro      | ⏳ Planned | `<BlueprintChart>` Astro component. |
+| Eleventy   | ⏳ Planned | Shortcode + plugin. |
+| Next.js    | ⏳ Planned | React component wrapping the runtime in `useEffect`. |
+
+If you need one of these now, the pattern is small enough to write inline: load the IIFE bundle once, then render a `<script type="application/blueprint-chart">` with the chart source in the body of your template.
+
+## Self-hosting the runtime
+
+The `unpkg.com` URL is convenient for prototyping; for production embeds, host the bundle yourself to avoid the third-party request and to pin a known version.
+
+```bash
+# Copy the IIFE bundle into your site's static assets directory
+cp node_modules/@blueprint-chart/lib/dist/lib/lib.iife.js public/vendor/
+```
+
+```html
+<script src="/vendor/lib.iife.js"></script>
+```
+
+## Real-world embeds
+
+Two end-to-end examples drawn straight from the lib's sample library — paste either snippet into an HTML page that already loads `lib.iife.js` and the runtime does the rest.
+
+### Donut: share of energy by source
+
+```html
+<script type="application/blueprint-chart">
+  chart donut {
+    title = "Coal still generates a third of the world's electricity"
+    description = "Share by source, 2024"
+    source = "IEA"
+    sourceUrl = "https://iea.org"
+    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
+    }
+  }
+</script>
+```
+
+::: tip From the sample library
+This is `packages/lib/src/samples/energy-sources.bpc` — a donut chart with an explicit categorical palette, right-anchored legend, and percentage display.
+:::
+
+### Line: a single-series time series with an annotation
+
+```html
+<script type="application/blueprint-chart">
+  chart line {
+    title = "US inflation peaked at 9.1% before retreating to near 3%"
+    description = "Consumer Price Index, year-over-year change (%)"
+    source = "Bureau of Labor Statistics"
+    sourceUrl = "https://bls.gov/cpi/"
+    colors = "#f28e2b"
+    lineSymbols = true
+    lineSymbolShape = "circle"
+    lineSymbolShowOn = "all"
+    verticalNumberFormat = ".1f"
+    tooltips = true
+
+    annotation "Jun 2022" {
+      text = "Peak: 9.1%"
+      dy = -12
+      showArrow = true
+    }
+
+    data {
+      "Jan 2021" = 1.4
+      "Jun 2021" = 5.4
+      "Jan 2022" = 7.5
+      "Jun 2022" = 9.1
+      "Jan 2023" = 6.4
+      "Jun 2023" = 3.0
+      "Jan 2024" = 3.1
+      "Jun 2024" = 3.0
+      "Jan 2025" = 3.0
+    }
+  }
+</script>
+```
+
+::: tip From the sample library
+This is `packages/lib/src/samples/inflation-rate.bpc` — a single-series line with circular symbols on every datapoint, a pinned annotation on the peak, and a one-decimal vertical number format.
+:::
+
+## Security model
+
+- The chart iframe uses `sandbox="allow-scripts"` only — no same-origin, no top-navigation, no forms.
+- The chart source is inserted via `srcdoc` after HTML-entity escaping.
+- The runtime does no network requests for rendering. All chart logic runs locally.
+- The parent page communicates with the iframe only via a single `postMessage` channel used to resize the iframe to fit content.
+
+## Troubleshooting
+
+**The chart doesn't appear.**
+Check the browser console for parse errors. The runtime keeps the original DSL visible inside a `.blueprint-chart-placeholder` div if rendering fails, so the source remains diff-able.
+
+**The iframe height doesn't match the chart.**
+The runtime listens for `blueprint-chart-resize` messages and resizes accordingly. A Content Security Policy that blocks inline scripts inside iframes will break this — the `srcdoc` iframe needs `script-src 'unsafe-inline'` or a matching `'sha256-…'` directive.
+
+**My CMS strips `<script>` tags.**
+Use the editor's standalone HTML export instead and host it as a static asset.

package/src/guide/getting-started.md

@@ -0,0 +1,159 @@
+# Getting Started
+
+Blueprint Chart is published as three packages on NPM. Pick the one that matches what you're building.
+
+<table>
+<thead><tr><th>Package</th><th>When to use it</th></tr></thead>
+<tbody>
+<tr><td nowrap><a href="https://www.npmjs.com/package/@blueprint-chart/lib"><code>@blueprint-chart/lib</code></a></td><td>Pure TypeScript chart engine — render charts from data + options or from a <code>.bpc</code> source. No Vue.</td></tr>
+<tr><td nowrap><a href="https://www.npmjs.com/package/@blueprint-chart/ui"><code>@blueprint-chart/ui</code></a></td><td>Vue 3 component library — forms, panels, navigation, scene timeline, layout primitives.</td></tr>
+<tr><td nowrap><a href="https://www.npmjs.com/package/@blueprint-chart/editor"><code>@blueprint-chart/editor</code></a></td><td>The full SPA — runs on top of <code>lib</code> + <code>ui</code>. Deployed at <a href="https://blueprintchart.com">blueprintchart.com</a>.</td></tr>
+</tbody>
+</table>
+
+## Install
+
+::: code-group
+
+```bash [pnpm]
+pnpm add @blueprint-chart/lib
+```
+
+```bash [npm]
+npm install @blueprint-chart/lib
+```
+
+```bash [yarn]
+yarn add @blueprint-chart/lib
+```
+
+:::
+
+## Render a chart from a BPC source
+
+```ts
+import { parse, buildChartOptions, parseData } from '@blueprint-chart/lib'
+
+const source = `
+  chart line {
+    title = "Bitcoin surged past $90,000 in 2024"
+    description = "USD, year-end closing price"
+    source = "CoinGecko"
+    sourceUrl = "https://www.coingecko.com"
+    colors = "#f7931a"
+    lineSymbols = true
+    lineSymbolShowOn = "all"
+    lineSymbolShape = "diamond"
+    verticalNumberFormat = ",.0f"
+    tooltips = true
+
+    annotation "2021" {
+      text = "All-time high cycle"
+      dy = -12
+      showArrow = true
+    }
+
+    data {
+      "2016" = 963
+      "2017" = 13880
+      "2018" = 3742
+      "2019" = 7194
+      "2020" = 28949
+      "2021" = 46306
+      "2022" = 16547
+      "2023" = 42258
+      "2024" = 93429
+    }
+  }
+`
+
+const ast = parse(source)
+const data = parseData(ast)
+const options = buildChartOptions(ast)
+```
+
+::: tip From the sample library
+This is `packages/lib/src/samples/bitcoin-price.bpc` — a single-series line chart with a fixed-colour brand override (`colors = "#f7931a"`), diamond symbols on every datapoint, and a pinned annotation marking the 2021 peak.
+:::
+
+From here you wire the `data` and `options` into the renderer of your choice — `@blueprint-chart/lib` exposes the building blocks (`createFrame`, `createCanvas`, `renderLegend`, `renderHorizontalAxis`, `renderVerticalAxis`) plus a chart-type registry (`registerChart` / `getChart`). See [the API reference](/reference/api/).
+
+## Drop a chart into any page
+
+If you don't need the programmatic API, use the bundled runtime. It picks up every `<script type="application/blueprint-chart">` tag and replaces it with a sandboxed iframe containing the rendered chart.
+
+```html
+<script src="https://unpkg.com/@blueprint-chart/lib/dist/runtime.iife.js"></script>
+
+<script type="application/blueprint-chart">
+  chart donut {
+    title = "Coal still generates a third of the world's electricity"
+    description = "Share by source, 2024"
+    source = "IEA"
+    sourceUrl = "https://iea.org"
+    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
+    }
+  }
+</script>
+
+<script>
+  blueprintChart.initBlueprint()
+</script>
+```
+
+::: tip From the sample library
+This is `packages/lib/src/samples/energy-sources.bpc` — a donut chart with a hand-picked categorical palette, percentage display, and a right-anchored legend.
+:::
+
+See the [embedding guide](/guide/embed) for static sites, CMS integrations, and the base64 iframe pattern.
+
+## Try the editor instead
+
+The fastest way to author a chart is in the hosted editor.
+
+- Open <https://blueprintchart.com>
+- Pick a sample or paste your own CSV / data
+- Tweak in the panel, watch the live preview, then export as a standalone HTML file or an embeddable `<script>` tag
+
+The editor runs entirely in your browser — no account, no server upload, no telemetry.
+
+## Build from source
+
+If you want to contribute or develop against an unreleased build, see the [repository README](https://github.com/blueprint-chart/blueprint-chart#readme) and `AGENTS.md` for canonical conventions.
+
+```bash
+git clone git@github.com:blueprint-chart/blueprint-chart.git
+cd blueprint-chart
+make install
+make dev          # editor at http://localhost:5555
+make dev-docs     # these docs at http://localhost:4445
+```
+
+## Try these samples
+
+The lib ships ~40 ready-to-run `.bpc` files under `packages/lib/src/samples/`. They double as canonical examples and as integration-test fixtures. A handful worth opening first:
+
+- `bitcoin-price.bpc` — single-series line with a brand colour, year-by-year diamond symbols, and an annotation on the 2021 peak.
+- `co2-emissions-story.bpc` — a bar chart with three scenes, each highlighting a different country to walk a reader through the same data.
+- `farm-compass.bpc` — a multi-scene narrative where later scenes swap the chart type (area → line → area-stacked) without rewriting the source.
+- `browser-market.bpc` — a donut driven by the named `Heep` palette, with right-anchored legend and percentage display.
+- `medal-count.bpc` — `bar-multi` with a gold / silver / bronze custom palette, sorted descending, top-anchored legend.
+- `temperature-anomaly.bpc` — single-series line tuned for dark mode (`autoContrast = false`, `allowDarkMode = true`) with a curved annotation calling out the 2015 Paris Agreement.
+
+## Next steps
+
+- [BPC DSL specification](/reference/dsl/) — the full language reference.
+- [Embedding charts](/guide/embed) — embed flows, CMS integrations, runtime details.
+- [API reference](/reference/api/) — every exported symbol from `@blueprint-chart/lib`.

package/src/guide/palettes.md

@@ -0,0 +1,207 @@
+---
+title: Palettes
+---
+
+# Palettes
+
+> 50+ curated categorical palettes, plus the helpers to resolve, audit, and adjust them for the background you render against.
+
+## Why this matters
+
+Color is the second most powerful encoding after position — and the easiest to misuse. Blueprint Chart ships a curated catalogue of palettes (sourced from [pypalettes](https://github.com/y-sunflower/pypalettes), MIT) so chart authors can pick a tested set instead of hand-rolling one. Each palette is perceptually balanced enough to read at small sizes; the accompanying helpers let you contrast-check and CVD-check before publishing.
+
+## Quickstart
+
+Pick a palette by name in a `.bpc` document:
+
+```bpc
+chart donut {
+  title = "Chrome dominates with two-thirds of the desktop browser market"
+  description = "Worldwide, January 2025"
+  source = "StatCounter"
+  sourceUrl = "https://gs.statcounter.com"
+  colorPalette = "Heep"
+  legendPosition = "right"
+  tooltips = true
+  displayAsPercentage = true
+
+  data {
+    "Chrome" = 65.7
+    "Edge" = 13.1
+    "Safari" = 8.9
+    "Firefox" = 6.3
+    "Opera" = 3.1
+    "Others" = 2.9
+  }
+}
+```
+
+::: tip From the sample library
+This is `packages/lib/src/samples/browser-market.bpc` — a donut chart driven entirely by the named `Heep` palette. Each slice picks up the next colour from the resolved palette array.
+:::
+
+Or pull the colours into TypeScript:
+
+```ts
+import { resolvePalette, listPalettes } from '@blueprint-chart/lib'
+
+resolvePalette('Egypt')
+// → ['#dd5129', '#0f7ba2', '#43b284', '#fab255']
+
+listPalettes()
+// → PaletteEntry[] with every palette currently registered
+```
+
+`resolvePalette()` returns a mutable copy of the underlying readonly array, so you can safely shuffle, slice, or reorder.
+
+## How it works
+
+Palettes are pure data — `packages/lib/src/charts/palettes.ts` declares a `PALETTES` array of `{ name, label, colors }` entries, indexed into a `PALETTE_MAP` for O(1) lookup. At render time:
+
+1. The chart's `colorPalette` property (a palette `name`) is resolved by `resolvePalette()` into an array of hex strings.
+2. Each series is mapped to a palette entry by `resolveSeriesColor`. Per-series overrides — `colors`, `series { color = … }`, `colorize "<name>"` — take precedence.
+3. When `autoContrast = true`, `adjustColorsForBackground(colors, bg)` nudges the lightness of each colour until every series clears WCAG AA against the frame background **and** every adjacent pair has at least CIE2000 ΔE ≥ 12. Hue and saturation are preserved.
+
+The library uses [chroma-js](https://gka.github.io/chroma.js/) under the hood for parsing, deltaE, and perceptual interpolation. See the [color handbook](/handbook/color) for the underlying theory (sequential vs. diverging vs. categorical, the perceptual-uniformity trap, ten ways to use less colour).
+
+## Recipes
+
+### Use a hand-picked colour
+
+The `colorPalette` property accepts any registered palette `name`. For a one-off brand-coloured chart, drop `colors = "<hex>"` (single value) and skip the palette entirely:
+
+```bpc
+chart line {
+  title = "Bitcoin surged past $90,000 in 2024"
+  description = "USD, year-end closing price"
+  source = "CoinGecko"
+  colors = "#f7931a"
+  lineSymbols = true
+  lineSymbolShowOn = "all"
+  lineSymbolShape = "diamond"
+
+  data {
+    "2016" = 963
+    "2020" = 28949
+    "2022" = 16547
+    "2024" = 93429
+  }
+}
+```
+
+::: tip From the sample library
+This is `packages/lib/src/samples/bitcoin-price.bpc` — Bitcoin orange (`#f7931a`) hard-coded as the single series colour, so the chart matches the brand regardless of the active palette.
+:::
+
+For multi-series charts, pass a comma-separated list (`colors = "#a","#b","#c"`) — `medal-count.bpc` does exactly this with gold, silver, and bronze for the Olympic ranking.
+
+### Override a single category
+
+`colorize "<name>"` re-paints one entry without disturbing the rest of the palette. `letter-frequency.bpc` uses it to make the winning entry pop in red against the named `London` palette:
+
+```bpc
+chart bar-vertical {
+  title = "E is the most frequent letter in English"
+  description = "How often each letter appears in typical English text"
+  colorPalette = "London"
+  sort = descending
+  valueLabels = true
+
+  colorize "E" {
+    color = "#e15759"
+  }
+
+  data {
+    "E" = 12.70
+    "T" = 9.06
+    "A" = 8.17
+    "O" = 7.51
+    "I" = 6.97
+    "N" = 6.75
+  }
+}
+```
+
+::: tip From the sample library
+This is `packages/lib/src/samples/letter-frequency.bpc` — every other bar takes its colour from `London`; only `E` is overridden, drawing the eye to the headline finding.
+:::
+
+### Auto-tune the palette to the frame background
+
+Opt a chart into automatic contrast adjustment by setting `autoContrast = true`. The renderer reads the effective background colour through `resolveBackgroundColor(container)` and nudges each palette entry until WCAG AA and a minimum perceptual distance are both satisfied — useful when the same chart ships in both light and dark themes.
+
+### Audit a palette before shipping
+
+The contrast and CVD helpers run outside any chart instance, which makes them handy for build-time linting:
+
+```ts
+import {
+  resolvePalette,
+  wcagContrastRatio,
+  wcagLevel,
+  checkCvdColors,
+} from '@blueprint-chart/lib'
+
+const palette = resolvePalette('Egypt')!
+const bg = '#ffffff'
+
+for (const color of palette) {
+  const ratio = wcagContrastRatio(color, bg)
+  console.log(color, ratio.toFixed(2), wcagLevel(ratio))
+}
+
+const issues = checkCvdColors(palette)
+// issues[].pairs lists colours that collapse under each dichromacy
+```
+
+See [Accessibility](/guide/accessibility) for the full audit workflow.
+
+### Browse the catalogue at runtime
+
+`listPalettes()` returns every entry currently registered, including its human-readable `label`. Drop it into a picker, a Histoire story, or a unit test:
+
+```ts
+import { listPalettes } from '@blueprint-chart/lib'
+
+const options = listPalettes().map((p) => ({
+  value: p.name,
+  label: p.label,
+  swatch: p.colors,
+}))
+```
+
+A small sampling of the catalogue (run `listPalettes()` for the current full list):
+
+| name | label | colours |
+| --- | --- | --- |
+| `Blueprint` | Blueprint | 6 |
+| `JosefAlbers` | Albers | 5 |
+| `Egypt` | Egypt | 4 |
+| `Klimt` | Klimt | 6 |
+| `Maya` | Maya | 5 |
+| `Sunset` | Sunset | 7 |
+| `TheovanDoesburg` | Van Doesburg | 5 |
+
+## API surface
+
+Exported from `@blueprint-chart/lib`:
+
+| Symbol | One-liner |
+| --- | --- |
+| `resolvePalette(name)` | Returns a mutable `string[]` of hex colours for a palette name, or `undefined`. |
+| `listPalettes()` | Returns every `PaletteEntry` currently registered. |
+| `PaletteEntry` (type) | `{ name: string, label: string, colors: readonly string[] }`. |
+| `resolveSeriesColor(...)` | Resolves a series to its final colour, respecting overrides. |
+| `resolveSeriesInterpolation(...)` | Resolves the interpolation function for a series (line / area charts). |
+| `isSeriesHidden(...)` | Whether a series is hidden by a scene or override. |
+| `resolveBackgroundColor(el)` | Walks ancestors until it finds a non-transparent background. |
+| `adjustColorsForBackground(colors, bg)` | Returns a legibility-tuned copy of the palette for the given background. |
+
+For the accessibility helpers (`wcagContrastRatio`, `wcagLevel`, `checkCvdColors`, …) see the [Accessibility guide](/guide/accessibility).
+
+## See also
+
+- [Accessibility](/guide/accessibility) — WCAG and CVD utilities.
+- [Colour handbook](/handbook/color) — palette theory and reduction techniques.
+- [BPC DSL — Color directives](/reference/dsl/annotations#color-directives) for `colorize`, `highlight`, `areafill`.
+- [API reference](/reference/api/#palettes) for the full export list.