d3-rosetta

A powerful utility library for creating reusable D3.js visualizations with unidirectional data flow. Write your interactive data visualization logic once using vanilla JavaScript and D3, and wrap it as a component in any framework.

Overview

d3-rosetta serves two main purposes:

• A utility library for simplifying D3 rendering logic with unidirectional data flow
• A rosetta stone of example implementations of the unidirectional data flow pattern across various frameworks (work in progress)

https://github.com/user-attachments/assets/c23aa1c2-f86b-4f7e-9ff4-979987cd090f

Fully working examples:

• US States with Hover - leverages utilities one, stateField, and memoize which makes the interaction so snappy!
• Multidimensional Filtering - brushing on multiple histograms with filtering - a solution to a classic complex problem with interactive visualization

The Problem: Re-using D3 Rendering Logic Across Frameworks

While frameworks like React, Svelte, Vue, and Angular offer state management and DOM manipulation solutions, D3 excels in data transformation and visualization, particularly with axes, transitions, and behaviors (e.g. zoom, drag, and brush). These D3 features require direct access to the DOM, making it challenging to replicate them effectively within frameworks.

The Solution: Unidirectional Data Flow

Unidirectional data flow is a pattern that can be cleanly invoked from multiple frameworks. In this paradigm, a single function is responsible for updating the DOM or rendering visuals based on a single, central state. As the state updates, the function re-renders the visualization in an idempotent manner, meaning it can run multiple times without causing side effects. Here's what the entry point function looks like for a D3-based visualization that uses unidirectional data flow:

export const viz = (container, { state, setState }) => {
  // Your reusable D3-based rendering logic goes here
};

• container: A DOM element where the visualization will be rendered.
• state: An object representing the current state of the application. It is initialized as an empty object {} by unidirectionalDataFlow.
• setState: A function to update the state. It accepts a callback function that receives the previous state and should return the new state (e.g., setState(prevState => ({ ...prevState, newProperty: 'value' }))). Invoking setState triggers unidirectionalDataFlow to re-execute the main function with the updated state.

Whenever setState is invoked, viz re-executes with the new state, ensuring that the rendering logic is both dynamic and responsive. This pattern is implemented in the VizHub runtime environment and can be invoked from different frameworks as needed.

Utilities

d3-rosetta provides several utilities designed to enhance the unidirectional data flow pattern by optimizing performance and simplifying common tasks in D3-based visualizations.

• one - Simplifies the management of single DOM elements within a D3 selection.
• createMemoize - Optimizes expensive calculations by caching results and reusing them when the same inputs are encountered.
• createStateField - Simplifies creating getters and setters for individual state properties.
• unidirectionalDataFlow - Establishes the unidirectional data flow pattern.

one

one(selection, tagName[, className])

The one function is a convenience utility designed to simplify the management of single DOM elements within a D3 selection. It ensures that only one element of the specified tagName (e.g., 'g', 'rect') exists within the given selection. Optionally, it can also apply a className to disambiguate between siblings of the same tag.

Example:

Consider the following traditional D3 logic for managing an axis container:

const xAxisG = selection
  .selectAll('g.x-axis')
  .data([null])
  .join('g')
  .attr('class', 'x-axis');

This can be expressed more concisely using one:

const xAxisG = one(selection, 'g', 'x-axis');

In this example, one simplifies the creation and management of a single g element with the class x-axis within the selection. This utility reduces boilerplate code and enhances the clarity of your D3 logic, particularly when dealing with elements that should only have a single instance within a selection.

createMemoize

createMemoize(node)

The createMemoize function creates a memoize function that stores memoized values on a given node (typically a DOM element). This utility is designed to optimize expensive calculations within D3 rendering logic by caching their results. The cache is associated with the node, and results are reused when the same inputs (dependencies) are encountered again, minimizing unnecessary recalculations and enhancing visualization performance.

The node parameter is the DOM element on which memoized values will be stored. Each call to the returned memoize function will use a unique property on this node to store its memoized value and dependencies.

// `container` is typically a DOM element
const memoize = createMemoize(container);

memoize(callback, dependencies)

The memoize function, returned by createMemoize, accepts a callback function (which performs the expensive computation) and an array of dependencies.

• callback: A function that computes the value to be memoized.
• dependencies: An array of values. If these dependency values are strictly equal (===) to the dependencies from the previous call for this specific memoization instance, the cached value is returned. Otherwise, the callback is executed, and its result is cached and returned.

This pattern is similar to React's useMemo hook and is particularly useful for computationally intensive data processing or DOM rendering operations.

Example:

import { createMemoize } from 'd3-rosetta';

export const viz = (container, { state, setState }) => {
  const { a, b } = state;
  const memoize = createMemoize(container); // `container` is the DOM node here
  const computed = memoize(() => {
    // Imagine that this is a very expensive calculation
    return a + b;
  }, [a, b]);
  console.log(computed); // Outputs the sum of a and b
};

createStateField

createStateField(state, setState)

The createStateField function is a higher-order function that simplifies the creation of getters and setters for individual properties within a state object. This is particularly useful when working with the unidirectional data flow pattern, where components need to read from and write to specific parts of the application state.

It takes the current state object and the setState function as arguments and returns a stateField function.

• state: The current state object of your application.
• setState: The function used to update the state. It should follow the pattern setState(prevState => newState).

stateField(propertyName)

The stateField function (returned by createStateField) takes a propertyName (string) corresponding to a key in the state object. It returns a two-element array:

1. value: The current value of state[propertyName].
2. setterForProperty: A function that, when called with a new value, will invoke setState to update only that specific propertyName in the state, preserving the rest of the state.

Example:

import { createStateField } from 'd3-rosetta';

export const viz = (container, { state, setState }) => {
  const stateField = createStateField(state, setState);

  const [name, setName] = stateField('name'); // Gets state.name and a setter for state.name
  const [age, setAge] = stateField('age'); // Gets state.age and a setter for state.age

  console.log(name); // Outputs the current value of state.name (e.g., undefined if not set)
  console.log(age); // Outputs the current value of state.age

  // To update the name:
  setName('Alice');
  // This is equivalent to:
  // setState(prevState => ({ ...prevState, name: 'Alice' }));

  // To update the age:
  setAge(30);
  // This is equivalent to:
  // setState(prevState => ({ ...prevState, age: 30 }));
};

This utility helps reduce boilerplate code when managing multiple state properties, making component logic cleaner and more focused on the specific fields being handled.

unidirectionalDataFlow

unidirectionalDataFlow(container, viz)

The unidirectionalDataFlow function is a core utility that establishes and manages the unidirectional data flow pattern for a visualization. It handles state initialization and updates, and ensures the visualization (viz function) is re-rendered whenever the state changes.

• container: A DOM element where the visualization will be rendered or attached. This container is passed through to the viz function. This typically has measurable width and height using container.clientWidth and container.clientHeight.
• viz: A function that encapsulates the rendering logic of the visualization. This function is called by unidirectionalDataFlow initially and every time the state is updated. It receives two arguments:
  • container: The same container object passed to unidirectionalDataFlow.
  • {state, setState}: An object containing:
    • state: An object representing the current state of the application. It is initialized as an empty object {} by unidirectionalDataFlow.
    • setState: A function to update the state. It accepts a callback function that receives the previous state and should return the new state using immutable update patterns (e.g., setState(prevState => ({ ...prevState, newProperty: 'value' }))). Invoking setState triggers unidirectionalDataFlow to re-execute the viz function with the updated state.

How it Works:

1. unidirectionalDataFlow initializes an internal state variable to an empty object ({}).
2. It defines a setState function. When this setState(nextStateFn) is called: a. The new state is computed: state = nextStateFn(state). b. The viz function is called again with the container, and an object containing the newly updated state and the same (stable) setState function: viz(container, {state, setState}).
3. Initially, unidirectionalDataFlow calls viz(container, {state, setState}) once to perform the first render with the initial empty state.

This utility is fundamental for structuring D3 (or other rendering library) visualizations in a way that is self-contained and can be easily integrated into various JavaScript frameworks or run in a vanilla JavaScript environment. For a more detailed explanation of the pattern itself, see The Solution: Unidirectional Data Flow.

The example under Vanilla JS in the Rosetta Stone section also demonstrates its typical usage.

Rosetta Stone

This section provides concrete examples of how to integrate a D3.js visualization using the unidirectional data flow pattern into various JavaScript frameworks and vanilla JavaScript setups. Each example aims to be a minimal, runnable project, typically set up with Vite.

The core visualization logic (referred to as viz in the examples) is assumed to follow the signature: viz(container, {state, setState})

You can find these examples in the rosetta-stone directory of this repository:

• Vanilla JS (HTML): See rosetta-stone/vanilla-html/

cd rosetta-stone/vanilla-html
npx http-server

• React (Vite): See rosetta-stone/react-vite/

cd rosetta-stone/react-vite
npm install
npm run dev

• Svelte (Vite): See rosetta-stone/svelte-vite/

cd rosetta-stone/svelte-vite
npm install
npm run dev

• Vue (Vite): See rosetta-stone/vue-vite/

cd rosetta-stone/vue-vite
npm install
npm run dev

• Angular (Vite): See rosetta-stone/angular-vite/

cd rosetta-stone/angular-vite
npm install
npm run dev

These examples demonstrate how to manage state and trigger re-renders of the D3 visualization from within each specific framework, leveraging the utilities provided by d3-rosetta where applicable (like unidirectionalDataFlow for the vanilla JS example).

In general, when integrating a viz function into a framework like React, Svelte, or Vue, developers should use the framework's native primitives for memoization and side effects, namely:

• In React, use useMemo and useEffect.
• In Svelte, use reactive declarations ($:) and onMount/onDestroy.
• In Vue, use computed and watchEffect.

The core pattern that d3-rosetta champions is the viz(container, {state, setState}) function signature and the unidirectional data flow. The helper utilities are a temporary bridge for non-framework environments. The long-term vision is for the rosetta-stone examples to demonstrate how to best integrate the core pattern using the host framework's own powerful and idiomatic tools for managing state, side effects, and performance.