VisDelta

VisDelta is a declarative visualization-transition library. Describe a chart before and after a change; VisDelta finds the difference and lets any external control play or seek the transition.

This project is evolving quickly and will remain free and open source forever. If you’ve downloaded it or are using it, please Star the repository and Follow @SonghaiFan to keep up with my projects. Your Star is my biggest source of support and motivation to keep building.

Every frame above is change.progress(t) — the same frames play forward, backward, or under a scrollbar. Try it in the documentation and playground.

Data -> Chart state -> Difference -> Transition -> Frame

import { bar } from "visdelta/bar";
import { transition } from "visdelta/transition";
import "visdelta/style.css";

const revenue = bar(rows)
  .x("category")
  .y("revenue");

const profit = revenue.y("profit");
const change = await transition(revenue, profit, {
  target: "#chart"
});

change.progress(0.42);
change.play({ duration: 800 });

Chart states are immutable: creating profit does not change revenue.

Building with an agent

For downstream MDX applications, see the authoring integration guide and the minimal Bar declaration. Each MDX step pairs its text with chart={...}. The accompanying mount example covers asynchronous generations, pending progress, single states and cleanup. Run npm run authoring:check to verify these examples against an installed package.

Start with llms.txt, the automatic behavior table, and the runnable single-file scroll story. The diagnostic API design is a proposal, not an implemented API.

Install

npm install [email protected]

Or import it directly in a browser, using the same jsDelivr +esm convention as D3:

<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/[email protected]/dist/visdelta.css">
<script type="module">
  import * as vd from "https://cdn.jsdelivr.net/npm/[email protected]/+esm";

  const state = vd.bar(rows);
</script>

See the complete CDN example for a slider-controlled transition and the optional focused entry points.

VisDelta depends only on the d3-* modules it renders with. Declared transforms such as .where(), .sort(), .breakdown(), and .rollup() run without any extra package. The package is ESM-only.

VisDelta expects tidy input. Data cleaning and reshaping belong before the library.

Chart types

Import	Use
visdelta/area	Ordered magnitude and composition
visdelta/bar	Categorical comparison
visdelta/line	Ordered trends
visdelta/point	Relationships between quantities
visdelta/unit	Countable items in grid, force, bar, or beeswarm layouts

The chart modules are peers. Each owns its builder, compiler, marks, axes, matching, and transition rules. Core has no branches for built-in chart types.

base.where({ region: "North" })     // remove other rows
base.highlight({ region: "North" }) // keep rows; change attention
base.focus({ region: "North" })     // keep rows; move the camera

Every visual mapping is explicit. VisDelta can supply presentation defaults, but it never decides that a data field should mean x, y, color, size, or detail.

Public entries

Entry	Responsibility
visdelta	All built-in builders plus the core API
visdelta/core	State normalization, data types, camera math, and delta()
visdelta/transition	transition(), seek, play, pause, resize, and destroy
visdelta/area, /bar, /line, /pie, /point, /unit	Focused chart modules
visdelta/plugins	Define and register independent chart modules
visdelta/chart-style	Structural chart-style modules
visdelta/browser	Browser-global dependency adapter
visdelta/style.css	Required chart styles

React

The optional visdelta/react entry provides one Chart component for React 18/19. Keep chart states and arrays stable between renders. pair below is [a, b]; states can contain any non-empty ordered sequence.

import { Chart } from 'visdelta/react';

<Chart state={a} height={320} />
<Chart state={pair} progress={progress} />
<Chart state={states} progress={position} />

A single state (or one-element array) displays immediately at progress 0. Empty arrays report an error. Pair progress is 0–1; sequence progress uses state boundaries 0, 1, 2, … . Omit progress and use onReady for imperative playback. See the React guide.

Design rules

• Every frame is true: marks, scales, ticks, grid lines, and titles agree.
• Exit marks before changing the scale; change the scale before entering marks.
• Canonical reversible paths use the same frames backward; explicit directional easing profiles are an exception (see design rules).
• focus() is a camera move, never a data filter.
• Core stays chart-agnostic; chart-specific behavior stays in its module.

Read the documentation, the API reference and the playground. The design principles are the semantic constitution the implementation follows.

Development

npm ci
npm run check
npm run build
npm run docs:check

The documentation site lives in website/, a separate Fumadocs project that renders live examples with the built library:

npm run build
cd website
npm ci
npm run dev

See CONTRIBUTING.md before adding a chart type. Generated dist/, site output, test results, and screenshots are not source files.

Released under the MIT License.

Pie and donut charts are available through visdelta/pie:

import { pie } from 'visdelta/pie';
const chart = pie([{ part: 'A', value: 25 }, { part: 'B', value: 75 }])
  .value('value').color('part').key('part').innerRadius(0.75);

See Design comparisons for contextual alternatives, runnable data and code, and seekable arc examples.

JSON specs

parseSpec(json) and stringifySpec(state, space?), exported from visdelta and visdelta/core, read and write the existing ViewSpec declaration. state may be a builder or plain spec. Parsed specs work directly with delta, transition, sequence, and the React components. Register the required chart modules before rendering JSON-only states.

import { parseSpec, stringifySpec } from 'visdelta/core';
const restored = parseSpec(stringifySpec(chart));

The helpers validate JSON values, common structure and transforms; chart-specific validity and data availability remain runtime/plugin concerns. Custom fields are preserved. Dates serialize to ISO strings and undefined object properties are omitted. Non-finite numbers, functions, symbols, bigints, cycles, unsupported object classes and undefined array entries are rejected. Builder validation starts with toSpec() output. Existing aliases normalize into meta; no separate JSON timeline, renderer or module implementation is serialized.

JSON and agent updates

import { render } from 'visdelta';

const view = await render('#chart', json, { data: { sales }, height: 280 });
await view.update(nextSpec);
view.destroy();

Pass complete JSON strings or spec objects. Built-in modules load automatically. The default latest policy finishes the active update and retains only the newest validated pending state. Update promises report applied, superseded or destroyed; invalid updates reject. See the persistent-view section in the API reference for data, revisions and manual control.

For small Bar edits, send a fluent batch against the accepted revision:

await view.edit({
  requestId: 'turn-1-flip',
  baseRevision: view.snapshot().revision,
  edits: [{ method: 'flip', args: [] }],
});

Identical retries reuse their outcome; stale revisions reject. See the fluent edit reference for the supported Bar methods, per-view request limit and custom adapter contract.