web-digraph

A library to render a simple directed graph editor. See the demo at https://web-digraph.hulahula.dev/.

Overview

This is a library for creating a simple directed graph. It was heavily inspired by react-digraph, but with less features, less polished, and less everything. However, it uses canvas instead of svg for rendering, giving much better performance, and have mobile/touchscreen support. Also, it is not using react, because we love imperative things. React is for the weak! (just kidding xD). The bundle size is also really small with no external dependencies, which is one thing I don't like the most about react-digraph.

Note that this is just a renderer, not something that you should use to store your actual node/edge data. Your actual data should live separately from this renderer.

Features

• Built with TypeScript.
• Small size (~8KB minified and gzipped, compared to react-digraph ~100KB minified and gzipped).
• Imperative API (yes, this is a feature).
• Touch input support.

Installation

npm install --save web-digraph

Note about the versioning

I admit, i made a grave mistake. I released v1, then years later, i remake it. I updated to v2 because there are many breaking changes. V1 and v2 were not really tested extensively. So now shortly after v2, i have ideas to improve it more, with breaking changes again.. But now I will not make the same mistake. I will just call the current version v3 alpha, and deprecate v1 and v2. So if i want to break things again, i can just call it v3 alpha 1, alpha 2, and so on. Absolutely no one is using this library yet anyway, so I think it is fine to just break things.

Changes from v2 to v3:

• Restructured memory into a Structure of Arrays (SoA) layout using TypedArrays (Float32Array/Int32Array) for optimizing memory usage.
• Going back to a Quad Tree. But different from v1, this time is a correctly (hopefully) implemented AABB Quad Tree.
• Some API changes.
• This version actually has a bit more complex API, a bit larger, and have a caveat (when deleting nodes/edges, see caveat section below), but with a much more optimized memory usage compared to v2. I will think of a way to solve this in the future.

Changes from v1 to v2:

• Simplify so much of the codebase, it is practically a rewrite, making the size of the library much smaller.
• Just use 1 canvas instead of multiple canvas on v1, as it turns out there is no real performance gain, because the most expensive operation is zooming, which is frequently used and need to rerender everything anyway.
• Fixed the FATAL bug on v1 where it doesn't respect window.devicePixelRatio, making the graph looked blurry on high resolution display. I didn't knew this bug exist because I didn't have expensive gadget to notice this.
• Now interactions (event handler) are decoupled from the renderer, making it tree-shakeable and possible for user to create their own.

BTW, you can still visit the demo of v1 on https://web-digraph.netlify.app/ if you want to compare the differences.

Usage

Here is a minimal example to use the library and get the graph running on a canvas:

import {
  createGraphRenderer,
  createGraphInteractions,
  createShape
} from "web-digraph";

// 1. Get your canvas element
const canvas = document.getElementById("graph-canvas") as HTMLCanvasElement;

// 2. Create the renderer engine
const graph = createGraphRenderer({
  bgColor: "#ffffff",
  nodeShapeColor: "#e2e8f0"
});

graph.mount(canvas);

// 3. Register a custom shape for nodes
const customNodeShape = graph.registerShape(
  createShape({
    w: 80,
    h: 80,
    path: new Path2D("M -40 -40 L 40 -40 L 40 40 L -40 40 Z")
  })
);

// 4. Add some nodes and an edge
const nodeA = graph.addNode(100, 100, customNodeShape);
const nodeB = graph.addNode(300, 100, customNodeShape);
graph.addEdge(nodeA, nodeB);

// 5. Flush the renderer to draw the initial state
graph.flush();

// 6. Attach default mouse/touch interactions
createGraphInteractions(canvas, graph);

For slightly more complex usage, including custom shapes and dynamic UI syncing, see the example site.

Graph Renderer

The createGraphRenderer(options) function creates the core engine. It manages the internal state of nodes, edges, zooming, panning, and handles rendering to the canvas. It exports the following imperative API:

| Property/Method | Type / Signature | Description | | :------------------ | :----------------------------------------- | :------------------------------------------------------------- | | nodes | NodeStore | The SoA structure storing all nodes. | | edges | EdgeStore | The SoA structure storing all edges. | | nodeCount | number | Total number of nodes (getter). | | edgeCount | number | Total number of edges (getter). | | selectedNodes | Int32Array | Subarray of currently selected node IDs (getter). | | selectedEdges | Int32Array | Subarray of currently selected edge IDs (getter). | | zoom | number | Current zoom level (getter). | | cameraX | number | Current camera X position (getter). | | cameraY | number | Current camera Y position (getter). | | mount | (el: HTMLCanvasElement) => void | Mounts the renderer to a canvas element. | | registerShape | (id, shape) => void | Registers a custom graph shape. | | addNode | (x, y, shapeId) => number | Adds a node at (x,y). Returns the node ID. | | addEdge | (sourceId, targetId, shapeId?) => number | Connects two nodes with an edge. Returns edge ID. | | moveNodeTo | (id, x, y) => void | Moves a node to an absolute coordinate. | | moveNodeBy | (id, dx, dy) => void | Moves a node by a relative offset. | | removeNode | (id) => number | Removes a node (and connected edges). Returns swapped item ID. | | removeEdge | (id) => number | Removes a specific edge. Returns swapped item ID. | | removeItems | (nodeIds, edgeIds) => SwapLogs | Batch removes items and returns O(1) swap-and-pop logs. | | clear | () => void | Deletes all nodes and edges from the graph. | | setWorldSize | (size) => void | Rebuilds the quad-tree bounds to a new size. | | beginDrag | (nodeIds: ArrayLike<number>) => void | Initiates dragging on an array of nodes. | | endDrag | () => void | Finishes the dragging state. | | selectNode | (id) => void | Marks a node as selected. | | selectEdge | (id) => void | Marks an edge as selected. | | unselectNode | (id?) => void | Unselects a node (or all nodes if omitted). | | unselectEdge | (id?) => void | Unselects an edge (or all edges if omitted). | | unselectAll | () => void | Clears all selections across nodes and edges. | | getNodeAt | (x, y) => number \| -1 | Returns the ID of the node under graph coords (x,y). | | getEdgeAt | (x, y) => number \| -1 | Returns the ID of the edge under graph coords (x,y). | | zoomTo | (value, targetX?, targetY?) => void | Zooms to an absolute value. | | zoomBy | (dv, targetX?, targetY?) => void | Zooms by a relative offset. | | panTo | (x, y) => void | Pans the camera to an absolute coordinate. | | panBy | (dx, dy) => void | Pans the camera by a relative offset. | | centerView | () => void | Pans and zooms to fit the entire graph on screen. | | screenToGraph | (x, y) => Pos | Converts physical screen coordinates to graph coordinates. | | graphToScreen | (x, y) => Pos | Converts graph coordinates to physical screen coordinates. | | flush | () => void | Triggers a re-render. Throttled to requestAnimationFrame. | | resize | () => void | Syncs physical canvas resolution with logical dimensions. | | setGhostEdge | (sourceId, x?, y?) => void | Renders an interactive rubber-band edge during creation. |

Caveat: Swap-and-Pop Deletions

To achieve good performance and minimize garbage collection, this library stores nodes and edges in tightly packed TypedArray buffers (wanted to use WASM to make things easier, but then I remember this is a library, not so easy for user to install if i include wasm. Hopefully will update to wasm in the future, to make the codebase much cleaner when playing with buffers).

When a node or edge is deleted, the engine performs a "swap-and-pop" operation. It takes the very last item in the buffer and moves it into the memory slot of the deleted item.

This means the ID of the last item in the graph changes.

Because this library is just a renderer, you likely maintain your own external data structures mapping these IDs to your business logic. You MUST update your external data structures to reflect this ID change.

To help you do this, the deletion APIs provide tracking logs:

• removeItems(nodeIds, edgeIds) returns a SwapLogs object containing arrays of which IDs were deleted, and which IDs were moved to replace them (nodeSwapDeletedLog, nodeSwapMovedLog, edgeSwapDeletedLog, edgeSwapMovedLog).
• removeNode(id) and removeEdge(id) directly return the number ID of the item that was swapped to fill the hole (or -1 if no swap was needed).

If you fail to update your application state with these swapped IDs, your application will end up pointing to the wrong items in the renderer, leading to "zombie" bugs. So if you have custom data, you pretty much need to add 4-5 lines in the interaction's onDeleteSelectedItems event. Please see the example site's code for how it is done.

Graph Shape

Nodes and edges are rendered using GraphShape objects. You can create completely custom SVG-like paths using the standard Canvas 2D API.

| Property | Type | Description | | :--------- | :---------------------------------- | :----------------------------------------------------------- | | w | number | The logical width of the shape. | | h | number | The logical height of the shape. | | path | Path2D | Used for precise hit-detection via ctx.isPointInPath. | | draw | (ctx, path, id, renderer) => void | The render loop function where you fill and stroke the path. |

Graph Options

When creating a renderer, you can pass a GraphOptions object to customize the visual appearance.

| Option | Type | Default | Description | | :-------------------------- | :---------------- | :-------------------- | :----------------------------------------- | | bgColor | string | "#fffdf7" | Canvas background color. | | drawGrid | boolean | true | Whether to render the background grid. | | gridType | "line" \| "dot" | "dot" | The style of the grid. | | gridSize | number | 64 | The spacing between grid lines/dots. | | gridLineColor | string | "#d1c9b8" | The color of the grid. | | gridLineWidth | number | 1 | Line width if grid type is line. | | gridDotRadius | number | 2.5 | Radius of the dot if grid type is dot. | | initialMaxNodes | number | 1000 | Initial capacity for nodes (auto-expands). | | initialMaxEdges | number | 10000 | Initial capacity for edges (auto-expands). | | minZoom | number | 0.2 | The maximum zoom-out limit. | | maxZoom | number | 5.0 | The maximum zoom-in limit. | | nodeLineWidth | number | 2 | Stroke width for nodes. | | nodeLineColor | string | "#475569" | Stroke color for nodes. | | nodeShapeColor | string | "#ffffff" | Fill color for nodes. | | nodeFont | string | "600 12px Inter..." | CSS font string for node text. | | edgeLineWidth | number | 2 | Stroke width for edges. | | edgeLineColor | string | "#3f6212" | Stroke color for edges. | | edgeShapeColor | string | "#ffffff" | Fill color for edge labels. | | edgeFont | string | "500 12px Inter..." | CSS font string for edge labels. | | selectedNodeLineWidth | number | 2 | Stroke width for selected nodes. | | selectedNodeLineColor | string | "#2563eb" | Stroke color for selected nodes. | | selectedEdgeLineWidth | number | 2 | Stroke width for selected edges. | | selectedEdgeLineColor | string | "#2563eb" | Stroke color for selected edges. |

Default Interaction

Event handling (mouse, touch, keyboard) is completely decoupled from the GraphRenderer. This architecture ensures the core renderer stays lean and tree-shakeable. createGraphInteractions(canvas, graph) provides the standard behaviors you'd expect (drag-and-drop, box selection, panning, zooming).

If you want a read-only graph, you can simply not mount the interaction. If you want custom hotkeys or entirely different behaviors, you can bypass the default interaction completely and build your own!

FAQ

Q: Why not just use react-digraph if this is basically an inferior version of react-digraph?
A: Size, performance, and mobile support are the main reasons. react-digraph depends on D3 and other dependencies, which make it heavy. Also they use react and svg, which is not performant when the nodes and edges count are really big. Try 1000 nodes on react-digraph's example and then try 999999 (I am not joking) nodes on web-digraph's example and you will see the difference.

Q: Why no react?
A: There are some reasons for this:

• First, react-digraph already use React, so why should we do the same?
• I am not a real fan of React. I just use React because of job's requirements xD
• Well, actually I tried to use React at first xD But it is not performing as well as I wanted and the code becomes ugly very quick (maybe I am just not good with React). And I didn't even know about react-digraph at first. So after knowing about react-digraph, I immediately redo from scratch without React and copies react-digraph. xD

Q: Is it production ready?
A: Use at your own risk! If you find any bugs, please let me know or create a PR. xD

Q: There are some missing event that I need, like onViewMoved, onHoverChange, etc. A: The core graph renderer is just a rendering engine, so it has no concept of events. All event handling lives in the Interaction layer. You can create a custom interaction layer tailored exactly to your needs, or submit a PR to add hooks into createGraphInteractions!