DSL — Scenes & transforms

Story-level constructs: scenes compose multiple visualisation states into a stepable narrative, and transforms describe data-pipeline operations applied before rendering. Scenes can override almost any chart member, including chart type and data. Annotation lifetime is controlled with the repeat property on the annotation itself.

Scenes

A scene is a named visualisation state — the same chart with different data, styling, or annotations. Multiple scenes compose into a story that users can step through.

A simple "highlight tour" — each scene swaps the title and emphasises one bar:

scene "China spotlight" {
  title = "China alone emits more than the US and India together"

  highlight "China"
}

scene "India rising" {
  title = "India passed the EU to become the third-largest emitter"

  highlight "India"
}

scene "Japan declining" {
  title = "Japan's emissions have fallen since their 2013 peak"

  highlight "Japan"
}

From packages/lib/src/samples/co2-emissions-story.bpc

Three scenes from a bar-horizontal story. Each scene inherits the chart's data and styling, and only overrides what changes — title plus a highlight target.

Scenes can also override the chart's type and data wholesale, switching from one visualisation to another mid-story:

scene "Bulgarian farms grew" {
  title = "Average farm size in Bulgaria quadrupled"
  description = "Average farm size in hectares"
  type = line

  data {
    "2005" = 5
    "2007" = 6
    "2010" = 12
    "2013" = 18
  }
}

scene "Cash crops replaced vegetables" {
  title = "Cash crops replaced vegetables in Bulgaria"
  description = "Production of Bulgarian farms, million euros"
  type = area-stacked

  data {
    series = "Vegetables","Cash crops","Other production"
    "2000" = 464,615,1854
    "2008" = 541,2045,1563
    "2015" = 144,2986,785
  }

  highlight "Cash crops"
}

From packages/lib/src/samples/farm-compass.bpc

A "story" can transition between chart types — here from a stacked area to a single-series line, then to a different stacked area — by setting type and supplying fresh data inside the scene.

Scenes accept the same member set as the top-level chart.

Annotation lifetime is governed by the repeat property on each annotation, not by scene-level verbs:

Value	Meaning
repeat = false (or omitted)	Show only in the scene where the annotation is declared (default).
repeat = N	Show in the declaring scene plus the next N scenes, so repeat = 1 spans 2 scenes and repeat = 3 spans 4. N must be a positive integer.
repeat = true	Show in the declaring scene and every scene after it.

A top-level annotation (declared on the chart, outside any scene) anchors at the base chart frame: with no repeat it shows only on that first frame, and repeat carries it forward into the following scenes.

Transforms

Transforms describe data-pipeline operations applied before rendering.

transform sort {
  column = "value"
  direction = descending
}

From packages/lib/src/samples/coffee-production.bpc

A sort transform reorders the data by the value column in descending order. The chart's sort = descending property is equivalent for simple cases; the transform form composes with other pipeline steps.

Transforms compose — each transform <name> { … } block is applied in source order. The grammar accepts any identifier in the <name> slot; the set of registered transform types is part of @blueprint-chart/lib's public surface; see the API reference.