How a chart is built

Every chart in the Graphy SDK is a spec — a plain, immutable object you build by folding parts together.

The builder pipeline

You start a spec with createSpec and fold parts onto it with pipe. Each part is a small tagged object produced by a builder (geom.*, scale.*, coord.*, config, …):

import { createSpec, pipe, geom, scale } from '@graphysdk/react';

const spec = pipe(
  createSpec({ x: 'month', y: 'revenue' }),
  geom.line(),
  scale.x(),
  scale.y()
);

pipe(spec, ...parts) returns a new spec with each part folded in, left to right — it never mutates. Each kind folds in its own way:

Kind	How it folds
`geom.`, `scale.`, `transform.*`, `highlight`	Appended to a list
`mapping`	Shallow-merges over the current mapping
`config`	Deep-merges over the current config
`coord`	Overwrites — one coord per spec, the last one wins
`styles`	Becomes the new stylesheet, with the previous one nested into its `extends`

Two of those are worth reading twice. coord overwrites, so piping coord.polar({ innerRadius: 0.5 }) after coord.polar({ theta: 'y' }) leaves you with the inner radius and no theta — pass both params in one call. And a piped styles(...) sits above everything piped before it, so a later stylesheet wins where the two declare the same property. Because a spec is a plain object, you can build it up conditionally, share fragments across charts, and store or serialize it.

import { createSpec, pipe, geom, scale, stat } from '@graphysdk/react';

declare const showAverage: boolean;

// Build in stages — each call returns a new spec.
let spec = createSpec({ x: 'month', y: 'revenue' });
spec = pipe(spec, geom.line(), scale.x(), scale.y());
if (showAverage) {
  spec = pipe(spec, geom.rule({ stat: stat.mean() }));
}

The parts of a spec

A spec brings together these parts. Each has its own page:

Part	What it decides	Builder
Mapping	Which data columns feed which aesthetics	`mapping`, `createSpec`
Geoms	The shapes drawn — line, bar, point, area, rule	`geom.*`
Scales	How data values become positions, colors and sizes	`scale.*`
Coordinate systems	The plane observations are drawn in	`coord.*`
Statistics	Per-layer summaries (count, sum, mean, smoothing)	`stat.*`
Transforms	Reshaping the data before it’s drawn	`transform.*`
Styles	How the marks and chart furniture are painted	`styles`, `style.*`
Highlights	Which observations are called out	`highlight`
Annotations	Text, arrows and brackets drawn over the plot	`annotation.*`

Plus configuration (config) for chart chrome — titles, axes, legend, layout.

Compile, then render

A spec is a description; it isn’t yet pixels. Turning it into a chart happens in two stages, one per package:

Compile (@graphysdk/viz-engine). The engine takes your spec plus your data and produces a CompiledSpec: scales are resolved to concrete domains, statistics are run, every observation is placed in a normalized [0,1] position space, the stylesheet is validated and its token() references are inlined, and guides (axes, legend) are worked out. This stage is pure data-in, data-out — no DOM. It is also what makes a styled spec serializable: paint comes out the far side as plain values.
Render (@graphysdk/react-renderer). The renderer takes the CompiledSpec and paints it: it lays out pixel rectangles, formats numbers and dates for the locale, picks the light or dark half of every color pair, and wires up hover and animation.

In a React app you don’t call the compiler yourself — <GraphProvider> does it for you and recompiles when the spec or data change. The colorScheme is resolved as the chart is read rather than at compile time, so switching it costs nothing:

import { GraphProvider, GraphRenderer } from '@graphysdk/react';

<GraphProvider input={spec} data={data} colorScheme="light">
  <GraphRenderer />
</GraphProvider>;

Why the split matters

The split between the two packages shapes how you use the SDK:

Data lives outside the spec. A spec references columns by name; the actual rows are passed to <GraphProvider> separately. One spec can draw many datasets.
The compiler never formats. It emits raw values and descriptors; the renderer turns them into locale-aware text. That’s why formatting options live on the renderer side.
Scales are resolved once, at compile time. This is why you declare scales explicitly in the spec — the engine can’t paint a position it was never told how to compute.

Authoring concerns — mapping, geoms, scales, stats, and the stylesheet that paints the marks — live in the engine; presentation concerns — layout, formatting, interactivity, and chrome theme — live in the renderer. Both are imported from @graphysdk/react.

Scales — the one part you must always declare
Serializable spec — a spec is plain JSON you can persist and reload

Get Started

Core concepts

Chart types

Annotations & emphasis

Rendering

Configuration

Advanced

Extending

How a chart is built

The builder pipeline

The parts of a spec

Compile, then render

Why the split matters

Next

​The builder pipeline

​The parts of a spec

​Compile, then render

​Why the split matters

​Next

The builder pipeline

The parts of a spec

Compile, then render

Why the split matters

Next