API Reference

Public surface of @blueprint-chart/lib. Every symbol on this page is exported from the package root.

Source of truth

This page mirrors 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.

Rendering a chart

The fastest path: one function returns a chart handle.

import { render } from '@blueprint-chart/lib'

const chart = await render(bpcSource, { theme: 'dark' })

Node — write SVG and PNG to disk

import { render } from '@blueprint-chart/lib'
import { writeFile } from 'node:fs/promises'

const chart = await render(bpc)
await writeFile('chart.svg', await chart.toSvg())
await writeFile('chart.png', await chart.toPng({ width: 1200 }))

Browser — mount and step scenes

const { mount, scene } = await render(bpc)
mount('#chart')   // element or selector
scene(2)          // advance to scene index 2

The handle

render(source, options?) resolves to a ChartHandle. Its methods are bound — destructure them freely (const { toSvg } = await render(bpc)) — and mount/scene are chainable ((await render(bpc)).scene(1).toSvg()).

Method	Browser	Node	Returns
`toSvg(opts?)`	✅	✅	`Promise<string>`
`toHtml(opts?)`	✅	✅	`Promise<string>`
`toPng(opts?)`	❌ throws `PngBrowserUnsupportedError`	✅	`Promise<Uint8Array>`
`mount(target)`	✅	no-op (warns)	`ChartHandle`
`scene(n)`	✅	✅	`ChartHandle`

toHtml() returns the .bc-frame outerHTML (the complete framed chart markup). When frame: false was passed to render(), it falls back to the bare chart SVG.

RenderApiOptions: theme?, scene? (initial scene), width?/height? (default 640×400, used for headless output only), frame? (default true; false renders frameless). OutputOptions on toSvg/toPng: width?, height?.

Node dependencies

PNG export and headless SVG in Node require optional native deps (jsdom, @napi-rs/canvas, @resvg/resvg-js), installed automatically as optionalDependencies. If a binary failed to install, the Node methods throw MissingNodeRenderDepsError naming what to reinstall. Browser bundles never include these.

SVG produced headlessly carries inline data colors and renders fonts via bundled DejaVu during PNG rasterization. It does not inline the full charts.scss theme; opening the bare .svg outside an app with that stylesheet may lack some structural styling.

Low-level surface

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 · 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

import {
  createFrame,
  createCanvas,
  renderVerticalAxis,
  renderHorizontalAxis,
  renderLegend,
} from '@blueprint-chart/lib'

Symbol	Purpose
`createFrame(container, options?)`	Set up the chart's outer frame (title, description, source, axis labels, note) inside `container`. Pass `null` for frameless. Returns `FrameElements`.
`createCanvas(body, margin?)`	Set up the inner drawing surface inside `body` (the frame body element). Returns `CanvasElements`.
`renderVerticalAxis(...)` / `renderHorizontalAxis(...)`	Draw axes with grid lines, ticks, and labels.
`renderLegend(...)`	Draw a chart legend (position + interactivity).

Chart-type registry

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

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:

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 · TransformNode · ColorizeNode · HighlightNode · AreaFillNode · AnnotationNode · PointAnnotationNode · RangeAnnotationNode · FreeAnnotationNode · AnnotationVisibilityNode

See the DSL spec for the corresponding source-level grammar.

Samples

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/.

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

// Available only from the IIFE bundle (auto-initialized) or:
import { initBlueprint, createSceneController, createStepController } from '@blueprint-chart/lib/runtime'
import type { SceneDefinition, SceneController, StepDefinition, StepController } from '@blueprint-chart/lib/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"
      textOffsetY = -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">
  // Each chart renders inside a sandboxed iframe that reloads the standalone
  // runtime bundle. In the IIFE form that URL is detected automatically; in the
  // module form `document.currentScript` is null, so point the runtime at the
  // IIFE bundle explicitly before calling initBlueprint().
  globalThis.BLUEPRINT_CHART_RUNTIME_URL = 'https://unpkg.com/@blueprint-chart/lib/dist/lib/lib.iife.js'
  import { initBlueprint } from '@blueprint-chart/lib/runtime'
  initBlueprint()
</script>

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; set globalThis.BLUEPRINT_CHART_RUNTIME_URL to the IIFE bundle URL so each generated iframe can load the runtime.

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 for the release process.

API Reference ​

Rendering a chart ​

Node — write SVG and PNG to disk ​

Browser — mount and step scenes ​

The handle ​

Node dependencies ​

Low-level surface ​

Entrypoints ​

Enums ​

Types ​

Chart data and options ​

Visual configuration ​

Annotations ​

Rendering primitives ​

Chart-type registry ​

Helpers ​

Data and option helpers ​

Palettes ​

Series ​

Color and accessibility ​

Motion ​

DSL ​

Parsing and serialization ​

Parse, modify, serialize ​

Converters ​

AST node types ​

Samples ​

Runtime entrypoint ​

End-to-end example ​

Versioning ​