ggaction

Most visualization grammars describe a finished chart. ggaction represents chart authoring itself as an immutable, traceable sequence of graphical actions.

Build, inspect, select, and revise charts one meaningful action at a time.

Every frame is rendered from an immutable ChartProgram. The final R² label is a traceable action built from public extension primitives.

Actions are verbs:

create · transform · encode · edit · select · compose

Chart resources are nouns:

data · marks · scales · coordinates · guides

A ChartProgram is the immutable sentence they produce.

The following fragment assumes cars is an array of row objects:

import { chart } from "ggaction";

const program = chart()
  .createCanvas()
  .createData({ values: cars })
  .createScatterPlot({
    id: "points",
    x: "Displacement",
    y: "Acceleration",
    color: "Origin",
    guides: false
  })
  .createRegression()
  .createGuides();

• Progressive — build and revise a chart one meaningful operation at a time.
• Traceable — retain high-level actions and the wrapped actions they invoke.
• Materialized — actions create concrete backend-neutral graphics; rendering does not perform hidden semantic compilation.

Install the current public release:

npm install ggaction

Add the Canvas element that the rendering code targets. Its accessible name and fallback text summarize the chart for contexts where Canvas pixels are not available:

<canvas id="chart" aria-label="Scatterplot of displacement versus acceleration by origin">
  Scatterplot of displacement versus acceleration by origin.
</canvas>

import { chart, render } from "ggaction/basic";

const observations = [
  { displacement: 97, acceleration: 14.5, origin: "Japan" },
  { displacement: 140, acceleration: 15.5, origin: "USA" },
  { displacement: 86, acceleration: 16.4, origin: "Japan" }
];

const program = chart()
  .createCanvas({
    width: 640,
    height: 400,
    margin: { top: 30, right: 130, bottom: 60, left: 70 }
  })
  .createData({ values: observations })
  .createScatterPlot({
    x: "displacement",
    y: "acceleration",
    color: "origin",
    shape: "origin"
  });

const context = document.querySelector("#chart").getContext("2d");
render(program, context);

Matching color and shape encodings give each origin a redundant visual cue and create a labeled categorical legend automatically.

The Quick Start uses the smaller ggaction/basic entry for the common creation path. Import from ggaction when you need editing, selection, composition, alternative coordinates, or statistical layers.

Start a separate program without a shape encoding, then derive alternatives without changing the checkpoint:

import { chart as editableChart } from "ggaction";

const checkpoint = editableChart()
  .createCanvas({ width: 640, height: 400 })
  .createData({ values: observations })
  .createScatterPlot({
    x: "displacement",
    y: "acceleration",
    color: "origin"
  });

const outlined = checkpoint.editPointMark({
  stroke: "#0f172a",
  strokeWidth: 2
});
const muted = checkpoint.editPointMark({ opacity: 0.35 });

console.log(checkpoint === outlined); // false
console.log(checkpoint.trace.children.at(-1).op); // "createScatterPlot"
console.log(outlined.trace.children.at(-1).op);   // "editPointMark"

All three remain renderable and inspectable. They are immutable values, not an automatic undo stack; the application chooses which to retain or render.

Use createLinePlot, createBarPlot, createHistogram, and createHeatmap for the other basic Cartesian charts. The ggaction/basic entry keeps this common creation path at or below the current 120,000-byte gzip regression ceiling while each facade still records its mark, encoding, and guide actions as trace children. Import from ggaction when you need editing, selection, composition, alternative coordinates, or statistical layers. See the Basic Charts API.

Use createParallelCoordinates({ dimensions }) to connect each source row across ordered, dimension-local scales and axes. See the Parallel Coordinates API or the runnable Cars example.

For an advanced layered example, follow the regression recipe or open the runnable regression example. To compare category distributions with density-filled strips, read the gradient-plot guide or open the runnable example. For symmetric or split density shapes centered on categories, use the violin-plot API or the runnable Cars example. For compact signed time-series bands, use encodeHorizon on an area mark and open the runnable Gapminder example.

• Cartesian, Polar, and Parallel-coordinate charts
• Statistical layers and intervals
• Faceting and program composition
• Mark selection and coordinated highlighting
• Browser Canvas, SVG, Node PNG, and vector PDF output
• TypeScript declarations and traceable extension actions

See the current supported features, tutorials and examples, and action reference for exact coverage. Runnable programs are collected in examples/.

The package is ESM-only and requires Node.js 20 or later.

All entries include TypeScript declarations. The default, basic, extension, and SVG entries are browser-safe; the PNG and PDF adapters are Node-only.

• Getting Started
• Tutorials and Examples
• Action Reference
• Concepts
• Supported Features

Bug reports, documentation improvements, examples, and focused code changes are welcome. Read CONTRIBUTING.md for setup, scope, tests, and the extra discussion required before public API or architecture changes.

Status: 0.0.8 is the current experimental public release. APIs may change before 1.0.0; changes are recorded in the changelog.

npm install
npm run assets:readme
npm test
npm run test:render
npm run test:docs

• Action-trace demo: Link