@blueprint-chart/docs 0.1.18

package/src/handbook/tooltips.md

@@ -0,0 +1,98 @@
+---
+title: Tooltips & Interaction
+---
+
+# Tooltips & Interaction
+
+> Tooltips progressively disclose detail, they never replace critical information. Interaction must be consistent, accessible, and keyboard-reachable. Crosshairs and hover states support — not replace — clear visual hierarchy.
+
+## Tooltip content
+
+- Include **both value AND category context**: *"3.4% unemployed"* not just *"3.4%"*
+- Keep content brief and self-sufficient (microcopy)
+- Repeat units and formatting seen elsewhere in the chart
+- Do not rely on tooltips for critical information — essential data must always be visible
+
+::: warning
+Tooltips are hidden by default. If information is essential to the chart's headline, it must be in the frame or on the data, not behind a hover.
+:::
+
+## Tooltip interaction
+
+- Support both **mouse hover and keyboard navigation** for accessibility
+- Tooltips are primarily a desktop pattern; on touch devices, use tap-triggered popups or always-visible labels
+- Apply tooltips **consistently** across all interactive elements — erratic deployment means users will not discover them
+- Tooltips must be user-initiated, not auto-appearing
+
+## Tooltip positioning
+
+- Never obscure the data point the user is examining
+- Use arrow indicators when multiple elements are nearby
+- Keep the tooltip within the viewport
+
+## Crosshair patterns
+
+- **Vertical crosshair** (tracking x-position) is standard for time-series line charts
+- Helps align reading across multiple series at the same x-value
+- Often combined with a tooltip showing all series values at that position
+- **Horizontal crosshair** is useful for value comparison on scatter plots
+- Crosshair lines should be subtle (dashed, light grey by default)
+- Hide crosshairs when the cursor leaves the chart area
+
+## Hover states
+
+- Use color saturation or opacity changes to indicate the active element
+- De-emphasize non-hovered elements (reduce opacity to 0.2-0.3) to create focus
+- Maintain the visual hierarchy: the hovered element should become the most prominent
+
+## Interaction design checklist
+
+- Is there a visible affordance that the chart is interactive?
+- Is the same interaction reachable by keyboard?
+- Do tooltips reappear consistently, or are they flaky at chart edges?
+- Does the tooltip echo the chart's number format and units?
+- Does the hovered element stay inside the viewport when tooltips grow?
+
+## How Blueprint Chart applies interaction
+
+Blueprint Chart's interaction layer is declarative. Crosshair direction and style enums configure axis-aligned crosshairs; tooltips are produced from the same scale and accessor layer used to render the chart, so the numbers always match. Tooltip positioning respects the viewport and flips sides automatically when the cursor approaches the chart edge.
+
+See the [API reference](/reference/api/) for the tooltip options exposed to consumers.
+
+## Worked example: tooltips plus a dashed vertical crosshair
+
+```bpc
+chart line-multi {
+  title = "Detroit's unemployment hit 16% during the Great Recession"
+  description = "Percent of labour force, 2000–2014"
+  source = "Bureau of Labor Statistics"
+  legend = false
+  tooltips = true
+  crosshair = true
+  crosshairStyle = "dashed"
+
+  annotation "2009" {
+    text = "Great Recession peak"
+    dy = -10
+    showArrow = true
+  }
+
+  data {
+    _series = "New York","Los Angeles","Chicago","Detroit"
+    "2000" = 5.0,5.6,4.5,3.8
+    "2009" = 9.5,12.4,11.2,16.2
+    "2014" = 6.5,8.0,7.1,8.2
+  }
+}
+```
+
+::: info From `packages/lib/src/samples/unemployment-rates.bpc`
+The annotation carries the headline (`"Great Recession peak"`) so the chart stands on its own. `tooltips = true` plus `crosshair = true` then layer progressive disclosure on top: hover anywhere on the x-axis and a dashed vertical line aligns the cursor with all four series at once, while the tooltip shows the four percentages for that year. The essential story is never trapped behind a hover.
+:::
+
+## See also
+
+- [Accessibility](/handbook/accessibility)
+- [Labels & Legends](/handbook/labels)
+- [Annotations](/handbook/annotations)
+- [Design Principles](/handbook/design-principles)

package/src/handbook/typography.md

@@ -0,0 +1,93 @@
+---
+title: Typography
+---
+
+# Typography
+
+> Type in charts must be small, sharp, and legible at a glance. Use sans-serifs with unambiguous character shapes, size ruthlessly, never rotate, prefer sentence case, and left-align.
+
+## Font selection
+
+- Use **sans-serif fonts** for charts: Roboto, Lato, Open Sans, Source Sans Pro, Noto Sans
+- Choose fonts where capital I, lowercase l, and number 1 are visibly different (Source Sans Pro, Verdana pass this test)
+- For maximum accessibility: **Atkinson Hyperlegible** (Braille Institute / Google Fonts)
+- Use **lining figures** (same height) for numbers in charts
+- Use **tabular figures** (equal width) for aligned columns and data tables
+- Maximum **two font families** in a single visualization
+
+## Sizing
+
+- Minimum **12-14px** for chart text on web
+- Minimum **36pt** for presentations
+- Title should be the largest, boldest text with highest contrast
+- Axis labels and data labels at medium size
+- Source and credit lines at smallest size, lowest contrast
+
+## Readability rules
+
+::: warning
+**Never rotate text.** If axis labels don't fit, rephrase them, abbreviate, or switch to horizontal bars.
+:::
+
+- Use **sentence case** (not ALL CAPS) for readability
+- **Left-align** multi-line text
+- Use **bold** sparingly for emphasis; avoid italics (harder to read)
+- Add text outlines (stroke in background color) when labels overlay chart elements
+
+## Hierarchy
+
+A chart typically has three to four type levels:
+
+1. **Title** — largest, boldest, highest contrast (states the insight)
+2. **Description / subtitle** — medium size, regular weight (context, time period, units)
+3. **Axis and data labels** — medium, consistent throughout
+4. **Source, note, credit** — smallest, lowest contrast
+
+Anything beyond four levels starts competing for attention. Collapse hierarchy aggressively.
+
+## How Blueprint Chart applies typography
+
+The renderer defaults to a sans-serif with tabular figures for axis ticks and data labels; source lines are the smallest, greyest type in the frame. Type sizes and weights are exposed as CSS custom properties so a single theme change propagates everywhere — including the editor's stories and the component library.
+
+```css
+.bc-chart {
+  --bc-font-family: system-ui, -apple-system, "Segoe UI", Roboto, sans-serif;
+  --bc-font-size-title: 1.25rem;
+  --bc-font-size-description: 0.9375rem;
+  --bc-font-size-axis: 0.8125rem;
+  --bc-font-size-source: 0.75rem;
+}
+```
+
+## Worked example: a short title doing the work
+
+```bpc
+chart bar-vertical {
+  title = "E is the most frequent letter in English"
+  description = "How often each letter appears in typical English text"
+  source = "Lewand, Cryptological Mathematics"
+  note = "Based on analysis of 40,000 words from English prose"
+  valueLabels = true
+  verticalLabelPosition = off
+  verticalGridStyle = none
+
+  data {
+    "E" = 12.70
+    "T" = 9.06
+    "A" = 8.17
+    "O" = 7.51
+    "I" = 6.97
+  }
+}
+```
+
+::: info From `packages/lib/src/samples/letter-frequency.bpc`
+Title under 50 characters, description under 70, single-letter axis labels — no rotation needed. The chart frame stays typographically neutral so the value labels (`12.70`, `9.06`…) sit at the same medium size as the axis ticks. Type hierarchy is collapsed to the minimum.
+:::
+
+## See also
+
+- [Frame Elements](/handbook/frame-elements)
+- [Labels & Legends](/handbook/labels)
+- [Accessibility](/handbook/accessibility)
+- [Design Principles](/handbook/design-principles)

package/src/reference/api/index.md

@@ -0,0 +1,245 @@
+# API Reference
+
+Public surface of [`@blueprint-chart/lib`](https://www.npmjs.com/package/@blueprint-chart/lib). Every symbol on this page is exported from the package root.
+
+::: info Source of truth
+This page mirrors [`packages/lib/src/index.ts`](https://github.com/blueprint-chart/blueprint-chart/blob/main/packages/lib/src/index.ts). It will be progressively replaced by automatically-generated TypeDoc output; for now, treat the source file as canonical when a symbol is missing here.
+:::
+
+## Entrypoints
+
+| Entrypoint | Purpose |
+| --- | --- |
+| `@blueprint-chart/lib` | The ESM API — types, parsing, rendering primitives, registry. |
+| `@blueprint-chart/lib/dist/lib/lib.iife.js` | Standalone IIFE runtime that auto-renders `<script type="application/blueprint-chart">` tags. Exposed globally as `BlueprintChart`. |
+| `@blueprint-chart/lib/charts.scss` | Base SCSS for chart styling — import once at the app level. |
+
+## Enums
+
+Authoritative list of enum exports (from `./enums`):
+
+`ChartType` · `AxisDirection` · `ScaleType` · `GridStyle` · `LabelPosition` · `LabelRotation` · `TickPosition` · `FrameSizing` · `CompassDirection` · `AnnotationLineStyle` · `StrokeStyle` · `AnnotationKind` · `AnnotationAction` · `RangeAnchor` · `Orientation` · `SymbolShape` · `SymbolShowOn` · `SymbolStyle` · `SortDirection` · `SortMode` · `LegendPosition` · `Anchor` · `ValueLabelPosition` · `CrosshairDirection` · `CrosshairStyle` · `StackMode` · `LineStyle` · `ChartOptionType` · `DirectLabelMode` · `Interpolation` · `DslNodeType`
+
+## Types
+
+### Chart data and options
+
+`ChartData` · `ChartOptions` · `ChartRenderer` · `ChartOptionDef` · `ChartTypeOptions` · `ChartTypeOptionKey` · `Margin`
+
+### Visual configuration
+
+`ColorizeConfig` · `HighlightConfig` · `AxisOptions` · `FrameOptions` · `AreaFillConfig` · `LineSymbolConfig` · `SeriesOverride`
+
+### Annotations
+
+`AnnotationConfig` · `PointAnnotationConfig` · `RangeAnnotationConfig` · `FreeAnnotationConfig` · `AnnotationLineConfig`
+
+## Rendering primitives
+
+```ts
+import {
+  createFrame,
+  createCanvas,
+  renderVerticalAxis,
+  renderHorizontalAxis,
+  renderLegend,
+} from '@blueprint-chart/lib'
+```
+
+| Symbol | Purpose |
+| --- | --- |
+| `createFrame(options)` | Set up the chart's outer frame (title, description, source, axis labels, note). Returns `FrameElements`. |
+| `createCanvas(options)` | Set up the inner drawing surface. Returns `CanvasElements`. |
+| `renderVerticalAxis(...)` / `renderHorizontalAxis(...)` | Draw axes with grid lines, ticks, and labels. |
+| `renderLegend(...)` | Draw a chart legend (position + interactivity). |
+
+## Chart-type registry
+
+```ts
+import {
+  registerChart,
+  getChart,
+  getChartOptions,
+  listCharts,
+} from '@blueprint-chart/lib'
+```
+
+Charts register themselves with the registry at import time. `getChart(type)` returns the renderer; `listCharts()` enumerates every registered type.
+
+## Helpers
+
+### Data and option helpers
+
+`parseData` · `buildChartOptions` · `getChartTypeDefaults` · `resolveChartTypeOptions` · `resolveBarGapPadding` · `DEFAULT_BAR_GAP`
+
+### Palettes
+
+`resolvePalette` · `listPalettes` · type `PaletteEntry`
+
+### Series
+
+`resolveSeriesColor` · `resolveSeriesInterpolation` · `isSeriesHidden`
+
+### Color and accessibility
+
+`resolveBackgroundColor` · `adjustColorsForBackground` · `wcagContrastRatio` · `wcagLevel`
+
+`getCvdFilterId` · `createCvdSvgFilter` · `simulateCvdColor` · `checkCvdColors` · types `CvdType` · `CvdIssue`
+
+### Motion
+
+`getTransitionDuration` · `snapshotForFadeOut` · `commitFadeOut` · `fadeIn` · `getCachedChart`
+
+## DSL
+
+### Parsing and serialization
+
+```ts
+import { parse, serialize, compactSerialize } from '@blueprint-chart/lib'
+```
+
+| Symbol | Behaviour |
+| --- | --- |
+| `parse(source)` | BPC text → AST. Throws on syntax errors. |
+| `serialize(ast)` | AST → BPC text (formatted). |
+| `compactSerialize(ast)` | AST → BPC text (whitespace-minimized). |
+
+### Parse, modify, serialize
+
+A typical pipeline reads a BPC source, mutates the AST in-place, then writes it back. Bundled samples make convenient inputs:
+
+```ts
+import { parse, serialize, samples } from '@blueprint-chart/lib'
+
+// Pull the Bitcoin price sample shipped with the lib.
+const bitcoin = samples.find(s => s.id === 'bitcoin-price')!
+
+// Parse the verbatim BPC source into an AST.
+const ast = parse(bitcoin.dsl)
+
+// Mutate: retitle the chart and bump the latest data point.
+const title = ast.properties.find(p => p.key === 'title')
+if (title) {
+  title.value = 'Bitcoin closed 2024 at a record high'
+}
+
+const latest = ast.data?.entries.find(e => e.key === '2024')
+if (latest) {
+  latest.value = 95000
+}
+
+// Serialize back to BPC text — round-trip safe.
+const updated = serialize(ast)
+console.log(updated)
+```
+
+The `parse → mutate → serialize` cycle is **round-trip safe**: re-parsing the output yields a structurally equal AST. Use `compactSerialize(ast)` instead of `serialize(ast)` when emitting BPC for embedding in HTML attributes or one-line URLs.
+
+### Converters
+
+`propertyMap` · `extractChartTypeOptions` · `dataEntriesToString` · `extractSceneOverrides` · `convertColorizes` · `convertHighlights` · `convertAreaFills` · `convertAnnotations` · `convertSeriesOverrides`
+
+### AST node types
+
+`ChartNode` · `DataNode` · `PropertyNode` · `SeriesNode` · `SceneNode` · `StepNode` · `TransformNode` · `ColorizeNode` · `HighlightNode` · `AreaFillNode` · `AnnotationNode` · `PointAnnotationNode` · `RangeAnnotationNode` · `FreeAnnotationNode` · `AnnotationVisibilityNode`
+
+See [the DSL spec](/reference/dsl/) for the corresponding source-level grammar.
+
+## Samples
+
+```ts
+import { samples, type ChartSample } from '@blueprint-chart/lib'
+```
+
+`samples` is a curated set of BPC sources used by the editor's sample gallery. Each entry includes title, description, and source — the underlying `.bpc` files live in [`packages/lib/src/samples/`](https://github.com/blueprint-chart/blueprint-chart/tree/main/packages/lib/src/samples).
+
+```ts
+import { samples, parse } from '@blueprint-chart/lib'
+
+// Discover everything bundled and filter by chart type.
+const lineSamples = samples.filter(s => s.chartType === 'line')
+
+// Each sample carries its raw BPC source on `.dsl`.
+const ast = parse(lineSamples[0].dsl)
+```
+
+Each `ChartSample` exposes:
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `id` | `string` | Stable identifier matching the source filename (e.g. `bitcoin-price`). |
+| `title` | `string` | The chart's `title` property, extracted at build time. |
+| `description` | `string` | The chart's `description` property. |
+| `chartType` | `string` | The DSL chart type (`line`, `bar-vertical`, `area-stacked`, …). |
+| `tsvData` | `string` | Data block flattened to tab-separated values for paste-in flows. |
+| `serializedData` | `string` | Data block re-emitted as BPC `data { … }` lines. |
+| `dsl` | `string` | The verbatim `.bpc` source. |
+
+## Runtime entrypoint
+
+```ts
+// Available only from the IIFE bundle (auto-initialized) or:
+import { initBlueprint, createSceneController, createStepController } from '@blueprint-chart/lib/dist/runtime'
+import type { SceneDefinition, SceneController, StepDefinition, StepController } from '@blueprint-chart/lib/dist/runtime'
+```
+
+| Symbol | Purpose |
+| --- | --- |
+| `initBlueprint()` | Find every `<script type="application/blueprint-chart">` on the page and replace it with a rendered chart iframe. |
+| `createSceneController(...)` | Imperative API for stepping through a chart's scenes programmatically. |
+| `createStepController(...)` | Lower-level step-based controller (aliased scene API). |
+
+### End-to-end example
+
+Drop a BPC source into the page inside a typed `<script>` tag, then call `initBlueprint()` once. Each script tag is replaced with a sandboxed iframe that renders the chart and posts back its measured height:
+
+```html
+<script type="application/blueprint-chart">
+  chart line {
+    title = "Bitcoin surged past $90,000 in 2024"
+    description = "USD, year-end closing price"
+    source = "CoinGecko"
+    colors = "#f7931a"
+    lineSymbols = true
+    lineSymbolShape = "diamond"
+    verticalNumberFormat = ",.0f"
+
+    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
+    }
+  }
+</script>
+
+<script type="module">
+  import { initBlueprint } from '@blueprint-chart/lib/dist/runtime'
+  initBlueprint()
+</script>
+```
+
+::: info BPC source from `packages/lib/src/samples/bitcoin-price.bpc`
+The IIFE bundle (`@blueprint-chart/lib/dist/lib/lib.iife.js`) calls `initBlueprint()` for you on `DOMContentLoaded`. Import the module form when you want to control timing or re-initialize after DOM updates.
+:::
+
+## Versioning
+
+The lib follows semver:
+
+- **Patch** — bug fixes, internal refactors, doc updates.
+- **Minor** — additive API surface, backward-compatible grammar growth.
+- **Major** — breaking changes (rare). The DSL grammar version tracks `MAJOR.MINOR` of the lib.
+
+See [`RELEASING.md`](https://github.com/blueprint-chart/blueprint-chart/blob/main/RELEASING.md) for the release process.

package/src/reference/dsl/annotations.md

@@ -0,0 +1,135 @@
+# DSL — Color directives & annotations
+
+Two families of named blocks that target specific data values to draw the eye: **color directives** (`colorize`, `highlight`, `areafill`) recolor or emphasize parts of the chart, and **annotations** (`annotation`, `range`, `note`) attach text and shapes to data points, ranges, or absolute positions. Both share the same "named block with a body" shape, and `highlight` is the verb scenes use to switch emphasis — see [Scenes & transforms](/reference/dsl/scenes-and-transforms).
+
+## Color directives
+
+| Directive | Purpose |
+| --- | --- |
+| `colorize "<target>" { … }` | Apply a color rule to a target (axis label, value label, etc.). |
+| `highlight "<target>" { … }` or `highlight "<target>"` | Emphasize a data point or series. The short form has no body. |
+| `areafill "<from>" "<to>" { … }` | Fill the area between two series with a color (line / area charts). |
+
+### `colorize`
+
+```bpc
+chart bar-vertical {
+  title = "E is the most frequent letter in English"
+  colorPalette = "London"
+  sort = descending
+
+  colorize "E" {
+    color = "#e15759"
+  }
+
+  data {
+    "E" = 12.70
+    "T" = 9.06
+    "A" = 8.17
+    "O" = 7.51
+  }
+}
+```
+
+::: info From `packages/lib/src/samples/letter-frequency.bpc`
+`colorize` paints a single category (`"E"`) in a contrasting color over the base palette, drawing the eye to the chart's lede.
+:::
+
+### `highlight`
+
+The short form `highlight "<name>"` (no body) is the common case — useful inside `scene` blocks for emphasising one series at a time:
+
+```bpc
+scene "China spotlight" {
+  title = "China emits more than the US and India combined"
+
+  highlight "China"
+}
+
+scene "India rising" {
+  title = "India surpassed the EU in 2023"
+
+  highlight "India"
+}
+
+scene "Japan declining" {
+  title = "Japan's emissions fell 20% from their peak"
+
+  highlight "Japan"
+}
+```
+
+::: info From `packages/lib/src/samples/co2-emissions-story.bpc`
+Three scenes share the same data and successively highlight one country each — the canonical "guided tour" pattern.
+:::
+
+### `areafill`
+
+```bpc
+areafill "Lower bound" "Upper bound" {
+  color = "#94a3b8"
+  opacity = 0.2
+}
+```
+
+::: tip
+No bundled sample currently uses `areafill`. The grammar is documented and parser-tested; the example above is illustrative.
+:::
+
+## Annotations
+
+Three kinds of annotation, sharing a body of properties (`text`, `dx`, `dy`, `showArrow`, …):
+
+### Point annotation — anchored to a data key
+
+```bpc
+annotation "2021" {
+  text = "All-time high cycle"
+  dy = -12
+  showArrow = true
+}
+```
+
+::: info From `packages/lib/src/samples/bitcoin-price.bpc`
+A minimal point annotation: the key matches a data label, `dy` nudges the text up, and an arrow draws back to the point.
+:::
+
+A richer point annotation with a connector line and curved leader:
+
+```bpc
+annotation "2015" {
+  id = "2o3cx"
+  text = "2015 Paris Agreement to limit global warming to 1.5°C "
+  maxWidth = 224
+  showLine = true
+  lineStyle = curve-right
+  showArrow = true
+  showCircle = true
+}
+```
+
+::: info From `packages/lib/src/samples/temperature-anomaly.bpc`
+Demonstrates `showLine` + `lineStyle = curve-right` for a labelled callout that arcs from the data point to the text block, plus `maxWidth` for wrapping.
+:::
+
+### Range and free annotations
+
+```bpc
+range {                    # range: spans a domain/value window
+  fromX = "2020"
+  toX = "2022"
+  text = "Pandemic rally"
+}
+
+note {                     # free: absolutely positioned
+  text = "Methodology footnote"
+  x = "10%"
+  y = "90%"
+}
+```
+
+::: tip
+The bundled samples do not currently exercise `range` or `note` annotations — these are illustrative. The grammar is parser-tested and the AST node types (`RangeAnnotationNode`, `FreeAnnotationNode`) are exported.
+:::
+
+The full property surface for each annotation kind is documented in the `AnnotationConfig` / `PointAnnotationConfig` / `RangeAnnotationConfig` / `FreeAnnotationConfig` types exported by `@blueprint-chart/lib`.