@glitchr/graphjs

The graph

Starting

In a browser, importing src/js/graph.js (or src/index.js, which imports it):

• starts every [data-graph] of the page - at once when the document is parsed already, else at DOMContentLoaded;
• starts them again at every transparent:load event on window (a navigation of @glitchr/flowjs swaps the page without loading it): the graphs already started are left as they are, the new ones start;
• sets window.Graph to the class, unless something holds that name already.

Graph.ready(root) starts the [data-graph] elements under root (and root itself when it matches) that are not started yet, for a fragment added later; it never starts one twice. A graph is also started by hand, on any element, [data-graph] or not:

import Graph from '@glitchr/graphjs';

const graph = new Graph(document.getElementById('pipeline'), { preset: 'pipeline', lineage: 'select' });

new Graph(element) on an element that has a graph already returns that graph, and the options given then are ignored. Graph.get(element) returns the graph of an element, or null.

On start the element gets the class graph, a .graph-viewport (focusable when keyboard is on, role="group", labelled by the element's aria-label, else labels.graph) holding a .graph-canvas, which holds the SVG of the edges (.graph-edges) and the nodes: the [data-graph-node] elements found inside the element are moved into the canvas, in their order. With controls on, a .graph-controls block of four buttons follows. Then the declared nodes are read and laid out (refresh()).

Until the first layout, the stylesheet hides the declared nodes (.graph:not(.is-ready) [data-graph-node] { visibility: hidden }): a page never shows them out of place. A graph whose element has no size yet (hidden, in a closed tab) is laid out again when it gets one (a ResizeObserver), and once more when the page's fonts are loaded (document.fonts.ready), the cards having changed size.

Declared in the page

<div data-graph data-graph-preset="tree" data-graph-focus="me" aria-label="My family">
    <a href="/people/1" data-graph-node="father">Henri Vasseur</a>
    <a href="/people/2" data-graph-node="mother">Jeanne Collet</a>
    <span data-graph-node="union" data-graph-kind="junction" data-graph-from="father mother"></span>
    <a href="/people/3" data-graph-node="me" data-graph-from="union">Paul Vasseur</a>
</div>

On a node

Nothing else of a declared node is read: its content, its classes and its links stay the server's. Nodes are measured as they are drawn (offsetWidth, offsetHeight), so a card's size comes from the stylesheet.

On the graph

Each data-graph-* attribute of the element sets the option of the same name (see Options): data-graph-rank-gap sets rankGap, data-graph-label-zoom-in sets labels.zoomIn. A boolean attribute is false when it reads false, 0, off or no, true otherwise (an empty data-graph-controls is true). A number attribute that is empty or not a number is ignored.

zoomStep and render have no attribute: they are given to new Graph() only.

Given as data

graph.setData({
    nodes: [
        { id: 1, label: 'build', state: 'success' },
        { id: 2, label: 'test', sub: '2 min', state: 'running', href: '/jobs/2' },
        { id: 'gate', kind: 'junction' },
    ],
    edges: [{ from: 1, to: 2 }, { from: 2, to: 'gate', state: 'failed' }],
});

setData() removes the nodes the graph holds (declared or given), builds one element per node, and lays them out. Identifiers are turned into strings (1 and '1' are the same node); a node given twice is built once.

A node

The element built for this data:

<a href="/jobs/2" data-graph-node="2" class="graph-node" data-graph-state="running" data-graph-placed-rank="1"><span class="graph-node-label">test</span><span class="graph-node-sub">2 min</span></a>

The render(node, graph) option builds the element instead: it receives the node as given (its id a string) and the graph, and returns an element; when it returns nothing, the default element is built. data-graph-node, the class graph-node and the rank, state and kind attributes are set on what it returns.

new Graph(element, {
    render: (node) => {
        const card = document.createElement('article');
        card.innerHTML = '<h3></h3><p></p>';
        card.querySelector('h3').textContent = node.label;
        card.querySelector('p').textContent = node.born + ' - ' + (node.died || '');
        return card;
    },
});

An edge

An edge to a node that does not exist, from a node to itself, given twice, or closing a cycle is not drawn: see What is set aside.

The second argument

setData(data, {focus, keepView}):

• focus: changes the focus option (the node the graph opens on and marks is-focus); null removes it.
• keepView: true: the view stays where it is. Otherwise the graph is placed again as on its first layout: the remembered view, else the focus, else the whole graph (see The first view).

A declared graph (refresh()) and a graph given as data are the same thing afterwards: every method works on both. refresh() after setData() reads the elements in the canvas, so it gives back the nodes setData() built, with their data-graph-rank and data-graph-state, and without the edges (the built elements have no data-graph-from).

Options

Given to new Graph(element, options) or Graph.ready(root, options). A preset sets some of them; the element's data-graph-* attributes win over the preset, the options over both. labels is merged key by key (the defaults, then the attributes, then the options).

labels and their defaults:

The options are read once: changing graph.options afterwards changes what the methods read next (lineage, focus, the zoom limits) but not what was built (the buttons, the listeners chosen for lineage: 'hover' and keyboard).

Presets

A preset only sets defaults: data-graph-rank-gap="80" on a tree gives 80, and new Graph(element, {edges: 'line'}) wins over both. Graph.presets holds the table above (the script's half); the stylesheet's half is keyed on [data-graph-preset], see Styling.

Moving about

Pointer, wheel, touch

A drag never starts from a form field (input, textarea, select), a contenteditable element or anything inside a [data-graph-nodrag] element. The browser's own drag of a link or a picture inside a node is prevented. A mouse wheel (notches of 50 or more) zooms by smaller factors than the small steps of a trackpad pinch, so both feel alike; a step is capped at 240 px of wheel.

The keyboard

With keyboard on (the default), the viewport is focusable (tabindex="0") and, once it or a node inside it has the focus:

A key pressed with Ctrl, ⌘ or Alt is left to the browser, and so is any key typed in a form field or a contenteditable element inside a node. A node that takes the focus does not scroll the viewport (the browser's scrolling into view is undone): the graph moves instead.

Full screen

fullscreen() (the fourth button, the F key) asks the browser to show the graph's element in full screen (the Fullscreen API). Where there is none (an iPhone), or the browser refuses, the element gets the class is-fullscreen and the stylesheet makes it cover the window (position: fixed, the highest z-index). fullscreen(false) leaves either. The class is-fullscreen is also set while the browser shows the element in full screen (fullscreenchange), so a stylesheet hooks on one class. In full screen the wheel alone moves the graph.

The first view

When a graph is placed for the first time (its nodes measured, its viewport with a size), it opens on:

1. the remembered view, when remember is on and one was kept for this graph, with the same focus and the same number of nodes;
2. else, when a focus is set and the whole graph would be shown at less than 0.7 of its size, the focused node in the middle at its natural size (scale 1);
3. else the whole graph (fit()), never larger than its natural size.

setData() places the graph again in the same way, unless it is given {keepView: true}.

When the viewport changes size afterwards (the window, a panel), what was in the middle stays in the middle; the zoom does not change.

The remembered view

With remember on, each move of the view writes, once per animation frame, in sessionStorage under graphjs: + the key (the key option, else the element's id, else the page's path and query string) a record of this shape:

{"cx": 412, "cy": 230, "scale": 0.8, "focus": "me", "nodes": 17}

cx, cy are the point of the graph in the middle of the view, so the view comes back right in a window of another size. A view kept for another focus or another number of nodes is not given back. Two graphs of a page without id and without key share one key: give each an id or a data-graph-key. In a private window, or with the storage full, nothing is kept and nothing fails.

The lit line

A node's line is the node, everything it descends from and everything that descends from it along the edges drawn (lineage() of The layout, run on the edges the layout kept: an edge it set aside - a cycle's, a loop, a duplicate, one to no node - is not drawn and leads nowhere). Lit, its nodes and edges get the class is-lineage, the element gets has-lineage, and the stylesheet dims everything else (--graph-dim) and draws the lit edges in --graph-accent.

highlight(id) lights a node's line and keeps it lit (the pinned node) whatever the mode; highlight(null) puts it out.

API

Static

Instance methods

Every method but isFullscreen() and destroy() returns the graph, so calls chain: graph.setData(data).center('me', {scale: 1}).

{animate: true} makes the view glide (the class is-gliding for 320 ms, a CSS transition of 0.28 s; none under prefers-reduced-motion: reduce); {animate: false} stops a glide under way.

Instance properties

Read them; the methods keep them in step.

Events

Dispatched on the graph's element; they bubble, so one listener on document hears every graph.

document.addEventListener('graph:select', (event) => {
    if (event.detail.id === 'deploy-production') {
        event.preventDefault();               // the link is not followed
        openConfirmDialog(event.detail.element);
    }
});

element.addEventListener('graph:view', ({ detail }) => {
    zoomLabel.textContent = Math.round(detail.scale * 100) + ' %';
});

The script listens to transparent:load on window (to start the graphs of a page swapped in) and to fullscreenchange on document.

Classes and attributes the script sets

The layout

layout(data, options) in src/js/layout.js - no DOM. It runs in a browser, a worker, Node or a server; Graph calls it with the sizes it measured.

import { layout, path, lineage } from '@glitchr/graphjs/layout';

layout(
    { nodes: [{ id, rank?, width?, height? }], edges: [{ from, to }] },
    { direction: 'down', gap: 24, rankGap: 56, sort: true, align: 'start', nodeWidth: 160, nodeHeight: 48 },
);

It returns {nodes: Map(id → {id, x, y, width, height, rank, order}), edges: [{from, to, index, points, flat}], ignored: [{from, to, index, reason}], ranks: [{rank, start, size}], width, height, direction}.

Input

Other fields are ignored (the edges' state and kind are Graph's).

Options

Graph passes direction, gap, rankGap, sort and align from its own options; nodeWidth, nodeHeight and sweeps keep their defaults there (a node not measured yet - hidden, no size - is laid out at 160 x 48 until it is).

Result

An empty graph gives no node, no edge, no rank, a size of 0 x 0.

An example, run

import { layout, path, lineage } from '@glitchr/graphjs/layout';

const data = {
    nodes: [
        { id: 'build', width: 120, height: 32 },
        { id: 'test', width: 120, height: 32 },
        { id: 'lint', width: 120, height: 32 },
        { id: 'deploy', width: 120, height: 32 },
    ],
    edges: [
        { from: 'build', to: 'test' },
        { from: 'build', to: 'lint' },
        { from: 'test', to: 'deploy' },
        { from: 'lint', to: 'deploy' },
        { from: 'deploy', to: 'build' },     // closes a cycle
        { from: 'test', to: 'nowhere' },     // no such node
    ],
};

const result = layout(data, { direction: 'right', gap: 14, rankGap: 64 });

Under Node 22 (node:22-alpine), result.nodes:

'build'  => { id: 'build',  x: 0,   y: 23, width: 120, height: 32, rank: 0, order: 0 }
'test'   => { id: 'test',   x: 184, y: 0,  width: 120, height: 32, rank: 1, order: 0 }
'lint'   => { id: 'lint',   x: 184, y: 46, width: 120, height: 32, rank: 1, order: 1 }
'deploy' => { id: 'deploy', x: 368, y: 23, width: 120, height: 32, rank: 2, order: 0 }

result.edges[0], result.ignored, result.ranks, width, height, direction:

{"from":"build","to":"test","index":0,"points":[{"x":120,"y":39},{"x":184,"y":16,"via":152}],"flat":false}
[ { from: 'deploy', to: 'build', index: 4, reason: 'cycle' },
  { from: 'test', to: 'nowhere', index: 5, reason: 'unknown' } ]
[ { rank: 0, start: 0, size: 120 }, { rank: 1, start: 184, size: 120 }, { rank: 2, start: 368, size: 120 } ] 488 78 right

1. What is set aside

An edge to a node that does not exist (unknown), from a node to itself (loop), given twice (duplicate), or closing a cycle (cycle) is listed in ignored and neither counted nor drawn. The cycle is cut where the walk, made in the order the nodes came in, meets a node it is still in.

The walk is depth-first and iterative: a chain of thousands of nodes does not exhaust the stack.

2. Ranks

• A rank given on a node is kept.
• Otherwise a node stands one rank past its farthest parent (longest path).
• A node without parent stands just before the nearest thing it leads to, not at the top. In a family tree the spouse who enters at a union has no parent in the tree: they stand in their partner's rank.

ranks lists every rank from the first to the last, the empty ones included.

A node whose only parents are such parentless nodes stands at rank 1. Given ranks may be any integers, negative included: ranks then starts at the smallest.

3. Order in a rank

Barycentric sweeps: each rank is sorted by the mean place of its neighbours in the rank above, then below, up to sweeps times (12); the order with the fewest crossings is kept. A node with no neighbour on the side looked at keeps its slot. sort: false keeps the order the nodes came in.

Before the sweeps, each rank holds its nodes in the order they came; an edge that crosses a rank is given a slot there beside its source's place in that order.

4. Places

Each node is drawn towards its neighbours of both sides, its rank's order and gap being kept (least squares under the separation, by pooling). A link between two nodes that have only each other on that side weighs eight times more, and is straightened last where there is room: a chain is a straight line, parents stand around their union, an only child under it.

Across the ranks, a rank is as deep as its deepest node, and rankGap separates two ranks. align (start, center, end) places a node that is shallower than its rank.

5. Edges

points go from the source's far side to the target's near side. An edge over several ranks is led through a free slot of each rank it crosses: it enters the rank at its start and, when the rank has a depth, leaves it at its end. A point that ends a stretch between two ranks (the target, and the entry into a crossed rank) carries via: where, between the two ranks, a step edge turns and a curve bends. The first point and the exit from a crossed rank carry none: the edge runs straight from there. An edge between two nodes of the same rank, or going against the direction (both only possible with given ranks), is flat: a straight line, kept out of the ordering.

An edge a → c crossing rank 1 (60 px deep) of a down graph:

[{"x":96,"y":40},{"x":5.33,"y":96,"via":68},{"x":5.33,"y":156},{"x":50,"y":212,"via":184}]

Graph draws a flat edge dashed (.graph-edge-flat).

path()

path(points, {direction, shape, radius}) gives the SVG path (d) of an edge through its points.

A stretch without via, or whose two ends are aligned, is a straight segment in every shape. No point: an empty string. The first edge of the example above, in each shape:

curve  M120 39C152 39 152 16 184 16
step   M120 39L144 39Q152 39 152 31L152 24Q152 16 160 16L184 16
line   M120 39L184 16

Lineage

lineage(data, id) returns {nodes: Set, edges: Set}: the node, everything it descends from and everything that descends from it (edge indexes are those of data.edges).

Siblings are not part of a line: a sibling is neither an ancestor nor a descendant. The walk follows every edge of data.edges, as given: run on the example's data, lineage(data, 'lint') gives the nodes lint, build, deploy, test and nowhere, and the edges 0 to 5, the cycle's edge and the edge to no node included. A graph's lit line runs it on the edges the layout drew only (see The lit line): pass {edges: result.edges} for the same walk (its edge indexes are then those of result.edges).

Styling

The stylesheet (src/css/index.css) reads only --graph-* variables. Set them on the [data-graph] element or on anything above it, with any selector.

The variables

Two variables are set for a stylesheet to read, not to be set: --graph-scale on the element (the current zoom, written by the script at every move) and --graph-state on a node with a state (the colour of its state).

Dark values apply under prefers-color-scheme: dark; data-graph-theme="light" or "dark" on the element forces one. A site with its own theme switch sets the variables under its own selector (for instance [data-theme="dark"] .graph, loaded after the stylesheet), or writes its theme into data-graph-theme.

The stylesheet never declares a --graph-* variable on the element: its defaults, the dark values and the presets' values are fallbacks of private tokens (--_graph-bg: var(--graph-bg, #f6f5f1) on .graph, and so on), which its rules read. So a value set by the site always wins over them, whatever its selector's specificity and wherever it is set: on the element with one class, on a wrapper, on :root for every graph of the site. Inside the graph (on the element's children) every --graph-* is set back to the value in force, so a site's own rule for a node's content reads var(--graph-sub-color) or var(--graph-accent) as expected.

:root {                 /* every graph of the site */
    --graph-accent: var(--ink-red);
}
.my-tree {              /* one class is enough, before or after src/css/index.css */
    --graph-bg: var(--paper);
    --graph-node-bg: var(--paper-raised);
    --graph-node-font: 500 .95rem/1.25 var(--font-text);
}
.my-tree .dates { color: var(--graph-sub-color); }

A value the site sets is the same in light and in dark (it replaces both); for a different dark value, the site sets it under its own @media (prefers-color-scheme: dark) or theme selector. The private --_graph-* tokens are the stylesheet's own: set the public names, not those.

Classes and attributes to hook on

The full list, with when each is set: Classes and attributes the script sets.

States

Outside the pipeline preset, a node's state colour is only set in --graph-state (and the dashed border of skipped and canceled): the pipeline preset draws it as a disc. A stylesheet uses it elsewhere, for instance .graph-node[data-graph-state] { border-left: 3px solid var(--graph-state); }. Under prefers-reduced-motion: reduce nothing turns or flows, and the view does not glide.

Presets

• tree: direction: down, edges: step, centred cards.
• pipeline: direction: right, edges: curve, pill-shaped jobs with a disc for the state (ring: pending, turning: running, full: success or failed, dotted: skipped or canceled), no dots on the ground.

A preset only sets defaults: the element's data-graph-* attributes win over it, the options given to new Graph() over both.

What each preset's stylesheet sets, on .graph[data-graph-preset="..."] (as defaults: a variable the site sets wins over the preset's value too):

The script's half of a preset (direction, edges, gaps) is in Presets.

Junctions

A node [data-graph-kind="junction"] is a ring of 14 px in --graph-edge on --graph-bg, without padding nor shadow: a union in a family tree, a gate in a pipeline. Given as data without a label, it has no text.

Testing

The test suite

npm test                          # node --test: the layout, and the Graph class in Chrome
CHROME=/path/to/chrome npm test   # another browser than the macOS application

npm test runs node --test, which finds test/layout.test.js: 16 tests of layout(), path() and lineage(), without a browser (the layout needs no DOM); and test/browser.test.js, which opens each page of test/browser/ in a headless Chrome (Node 22 or later: it drives Chrome over its DevTools protocol with Node's own WebSocket), under a light then a dark colour scheme. Where no Chrome is found (CHROME, by default /Applications/Google Chrome.app/Contents/MacOS/Google Chrome), that test is skipped and says so.

Each page writes its verdict in #result (lines starting with ok, or FAIL); a console error or an uncaught exception fails it too. In a container, an image with Node 22 and a Chrome (the puppeteer image) runs the whole suite; Chrome there needs --no-sandbox, which a two-line wrapper gives:

printf '#!/bin/sh\nexec /path/to/chrome --no-sandbox "$@"\n' > chrome.sh && chmod +x chrome.sh
docker run --rm -v "$PWD":/repo:ro -v /path/to/dir-with-chrome.sh:/scratch:ro \
    -e CHROME=/scratch/chrome.sh -w /repo --entrypoint node ghcr.io/puppeteer/puppeteer:24.10.0 --test

There the suite ends:

# tests 23
# suites 0
# pass 23
# fail 0
# cancelled 0
# skipped 0
# todo 0

The rest of the Graph class (the pointer, the wheel, the keyboard, full screen) is checked by hand on the example page.

The example page

python3 -m http.server 8000       # then http://localhost:8000/example/

example/index.html loads src/css/index.css and src/js/graph.js from the repository (no build): a family tree declared in the page (five generations, unions as junctions, focus on the youngest) with buttons for fit(), center() and highlight(), and a pipeline given as data (setData(), ten jobs in every state, lineage: 'select') with a button for setState(). It prints the graph:select and graph:view events under each graph, and exposes window.tree and window.pipeline for the console.

Testing a page that uses graphjs

• The layout is a pure function: test what a page gives the graph by calling layout() on the same data in Node and asserting ranks, order or ignored.
• In a browser test, wait for the class is-ready on the element (set after the first layout) or for the graph:layout event before reading places; Graph.get(element).result holds the last layout.
• remember keeps the view in sessionStorage: a test that reloads a page and expects the first view sets data-graph-remember="false" or clears sessionStorage.