Grammar of Graphics architecture

Taucharts is built on the ideas laid out in The Grammar of Graphics by Leland Wilkinson. Rather than providing a fixed set of chart types, the library lets you compose charts from a small vocabulary of orthogonal concepts — data sources, typed dimensions, scales, coordinate systems, and visual marks — and combines them according to declarative rules. Understanding this model is key to writing effective plugins, debugging rendering issues, and working with the lower-level Plot API.

This is an advanced topic intended for plugin authors and library contributors. Most users can ignore these internals and work with the high-level Chart config instead.

Core concepts

Data sources

The raw material for every chart is a flat array of JavaScript objects. Each object is a row; each property is a field.

const data = [
  { team: 'Alpha', effort: 40, date: '2024-01-01' },
  { team: 'Beta',  effort: 55, date: '2024-02-01' },
];

Taucharts stores data sources internally under two keys: '?' (the empty source used for null-scale placeholders) and '/' (the primary data source).

Dimensions

Dimensions are typed data fields. Taucharts detects types automatically or accepts explicit declarations in the dimensions config option.

Type	Description
`category`	Discrete string values — mapped to ordinal scales
`measure`	Continuous numeric values — mapped to linear or time scales
`order`	Discrete values with an explicit sort order

dimensions: {
  team:   { type: 'category' },
  effort: { type: 'measure' },
  date:   { type: 'measure', scale: 'time' }
}

Scales

Scales map data values to visual encodings. The internal GPL config contains a scales dictionary that describes each mapping.

Scale type	Purpose
`ordinal`	Maps categories to discrete positions or colors
`time`	Maps Date values to a continuous axis
`linear`	Maps numbers to a continuous axis
`logarithmic`	Maps numbers on a log axis
`period`	Maps dates to repeating calendar periods
`color`	Maps values to a color palette
`size`	Maps values to mark sizes

Grammar elements

Grammar elements are the visual marks that appear on screen. Each element type is registered in the units registry under a string key:

Key	Description
`ELEMENT.POINT`	Scatter-plot dots
`ELEMENT.LINE`	Connected line segments
`ELEMENT.PATH`	Free-form connected path
`ELEMENT.AREA`	Filled area under a line
`ELEMENT.INTERVAL`	Bars and stacked bars
`PARALLEL/ELEMENT.LINE`	Lines used inside a parallel-coordinates chart

Coordinate systems

Coordinate systems wrap grammar elements and determine how data positions are projected onto the canvas:

Key	Description
`COORDS.RECT`	Cartesian (x/y) coordinate system — used for all standard charts
`COORDS.MAP`	Geographic map projection
`COORDS.PARALLEL`	Parallel-coordinates projection

GPL config

The GPL (Graphics Programming Language) config is the internal specification that drives rendering. It is produced by SpecConverter from the user-facing ChartSpec and has the following shape:

{
  sources: {
    '?': { dims: {}, data: [] },  // empty placeholder source
    '/': { dims: {}, data: [] }   // primary data source
  },
  scales: {
    'x_null': { type: 'ordinal', source: '?' },
    'y_null': { type: 'ordinal', source: '?' },
    // ... one entry per mapped field
  },
  unit: {
    type: 'COORDS.RECT',
    x: 'x_scale',
    y: 'y_scale',
    unit: [
      { type: 'ELEMENT.LINE', x: 'x_scale', y: 'y_scale', color: 'color_scale' }
    ]
  },
  settings: { /* ChartSettings */ }
}

How config transforms to a rendered chart

When you call new Taucharts.Chart(config), Taucharts runs the config through a multi-stage pipeline before a single pixel is drawn.

Stage 1: Config → ChartSpec

DataProcessor.autoDetectDimTypes scans config.data to infer dimension types. DataProcessor.autoAssignScales then assigns default scale types to each dimension. The appropriate chart factory (ChartLine, ChartInterval, etc.) is looked up from the chart-types registry using config.type, and transformConfig converts the simplified user config into an explicit hierarchical spec:

config.spec = {
  dimensions: { /* detected or declared */ },
  unit: {
    type: 'COORDS.RECT',
    x: [...],
    y: [...],
    unit: [ { type: 'ELEMENT.LINE', x, y, ... } ]
  }
}

Stage 2: ChartSpec → GPL config

new SpecConverter(config).convert() produces the full GPL config with populated sources and scales dictionaries.

Stage 3: GPL config → live spec

Two spec transformers run before plugins see the spec:

SpecTransformApplyRatio — removes empty facet values and resizes remaining facets proportionally
SpecTransformAutoLayout — calculates layout parameters (padding, tick sizes) based on the chart’s rendered size

After these transformers complete, the specready event fires. Plugin init callbacks can subscribe to this event to inspect or modify the spec.

Stage 4: Live spec → grammar elements

GPL.unfoldStructure() expands the nested unit tree, propagating data from parent nodes to children and applying filter expressions. Two more transformers then run:

SpecTransformExtractAxes — removes repeated X and Y axes from facet cells
SpecTransformCalcSize — calculates required chart size and suppresses ticks or labels when there is insufficient space

After this stage, the unitsstructureexpanded event fires.

Stage 5: Grammar elements → SVG DOM

The draw scenario queue is built from the expanded grammar elements. The beforerender event fires, then each grammar element’s draw() method is called in turn, with unitdraw firing for each one. When all elements have been drawn, the render event fires.

CONFIG
  └─ SpecConverter ──────────────────────────────► GPL CONFIG
                                                        │
                          SpecTransformApplyRatio ──────┤
                          SpecTransformAutoLayout ──────┤
                                                        │
                                                   ► LIVE SPEC  ── (specready)
                                                        │
                               GPL.unfoldStructure ─────┤
                          SpecTransformExtractAxes ──────┤
                            SpecTransformCalcSize ───────┤
                                                        │
                                                   ► FINAL SPEC  ── (unitsstructureexpanded)
                                                        │
                                         draw scenario  │
                                                        │
                                           (beforerender)
                                           element.draw() × N  ── (unitdraw × N)
                                           (render)

Facets

When you pass an array to x or y in your config, Taucharts builds a hierarchical coordinate system — a facet. Each value in the outermost dimension becomes a row or column of sub-charts, each of which is its own COORDS.RECT with its own nested grammar elements.

// Two-level facet: rows = class, sub-axis = price; columns = milespergallon
var chart = new Taucharts.Chart({
  type: 'scatterplot',
  x: ['milespergallon'],
  y: ['class', 'price'],
  color: 'class',
  data: [...]
});

In the GPL spec, facets appear as nested unit arrays inside COORDS.RECT nodes. Each level of nesting adds one dimension of faceting. SpecTransformApplyRatio and SpecTransformExtractAxes handle proportional sizing and shared-axis deduplication across facet cells automatically.

Chart events timeline

The full sequence of events that fire during a single chart.renderTo() call:

specready

Fires after SpecTransformApplyRatio and SpecTransformAutoLayout have run. The GPL spec is available. Plugins can read or modify spec.scales and spec.unit here.

unitsstructureexpanded

Fires after GPL.unfoldStructure(), SpecTransformExtractAxes, and SpecTransformCalcSize have run. The unit tree is fully expanded; this is the last point where the spec can be changed before drawing begins.

beforerender

Fires immediately before grammar elements begin drawing to the SVG. Use this to prepare overlay elements that must be positioned relative to the final chart geometry.

unitdraw (× N)

Fires once for each grammar element as it finishes drawing. The second callback argument is the GrammarElement instance that just drew.

render

Fires when all grammar elements have drawn and the SVG is complete. This is the most common hook for post-processing the rendered output.

Registered element and coordinate types

The following types are registered in api.unitsRegistry at startup in src/tau.charts.ts:

api.unitsRegistry
  .reg('COORDS.RECT',              Cartesian)
  .reg('COORDS.MAP',               GeoMap)
  .reg('COORDS.PARALLEL',          Parallel)
  .reg('ELEMENT.GENERIC.CARTESIAN', GenericCartesian)
  .reg('ELEMENT.POINT',  Point,    'ELEMENT.GENERIC.CARTESIAN')
  .reg('ELEMENT.LINE',   Line,     'ELEMENT.GENERIC.CARTESIAN')
  .reg('ELEMENT.PATH',   Path,     'ELEMENT.GENERIC.CARTESIAN')
  .reg('ELEMENT.AREA',   Area,     'ELEMENT.GENERIC.CARTESIAN')
  .reg('ELEMENT.INTERVAL', Interval, 'ELEMENT.GENERIC.CARTESIAN')
  .reg('PARALLEL/ELEMENT.LINE', ParallelLine);

The third argument to .reg() is an optional parent type. ELEMENT.GENERIC.CARTESIAN acts as a base class for all standard cartesian marks.

You can register your own grammar element types using Taucharts.api.unitsRegistry.reg(key, ElementClass, parentKey). This is the extension point used by the layers plugin to introduce additional visual mark types at runtime.

Getting Started

Chart Types

Configuration

Plugins

Advanced

Grammar of Graphics architecture

Core concepts

Data sources

Dimensions

Scales

Grammar elements

Coordinate systems

GPL config

How config transforms to a rendered chart

Stage 1: Config → ChartSpec

Stage 2: ChartSpec → GPL config

Stage 3: GPL config → live spec

Stage 4: Live spec → grammar elements

Stage 5: Grammar elements → SVG DOM

Facets

Chart events timeline

Registered element and coordinate types

Build docs developers (and LLMs) love

Getting Started

Chart Types

Configuration

Plugins

Advanced

Documentation Index

​Core concepts

​Data sources

​Dimensions

​Scales

​Grammar elements

​Coordinate systems

​GPL config

​How config transforms to a rendered chart

​Stage 1: Config → ChartSpec

​Stage 2: ChartSpec → GPL config

​Stage 3: GPL config → live spec

​Stage 4: Live spec → grammar elements

​Stage 5: Grammar elements → SVG DOM

​Facets

​Chart events timeline

​Registered element and coordinate types

Build docs developers (and LLMs) love

Core concepts

Data sources

Dimensions

Scales

Grammar elements

Coordinate systems

GPL config

How config transforms to a rendered chart

Stage 1: Config → ChartSpec

Stage 2: ChartSpec → GPL config

Stage 3: GPL config → live spec

Stage 4: Live spec → grammar elements

Stage 5: Grammar elements → SVG DOM

Facets

Chart events timeline

Registered element and coordinate types