@fusion.dev/helix-graph 0.0.0-dev → 0.118.0

package/README.md

@@ -0,0 +1,82 @@
+# @fusion.dev/helix-graph
+
+Connects the Helix `Graph` frame to whatever draws the graph: Sigma.js, or a
+driver of your own, colored from your tokens.
+
+```sh
+bun add @fusion.dev/helix @fusion.dev/helix-graph sigma graphology graphology-layout-forceatlas2
+```
+
+The elements themselves are on the
+[Graph reference](https://fusion.dev/helix/components/graph).
+
+```js
+import { connectGraph } from '@fusion.dev/helix-graph'
+import { sigmaDriver } from '@fusion.dev/helix-graph/sigma'
+import Graph from 'graphology'
+import forceAtlas2 from 'graphology-layout-forceatlas2'
+import FA2Layout from 'graphology-layout-forceatlas2/worker'
+import Sigma from 'sigma'
+
+const frame = document.querySelector('helix-graph')
+frame.nodes = notes // [{ id, label, group, size, x, y }]
+frame.links = links // [{ source, target, label }]
+
+const sigma = new Sigma(new Graph(), document.getElementById('drawing'))
+const connection = connectGraph(
+  frame,
+  sigmaDriver(sigma, {
+    layout: (graph) => new FA2Layout(graph, { settings: forceAtlas2.inferSettings(graph) }),
+  }),
+)
+
+// Keep where the layout put each note, and pass it back as `x` and `y` next time.
+frame.addEventListener('helix-graph-layout', (event) => save(event.detail.positions))
+
+// Later, when the graph goes away:
+connection.disconnect()
+```
+
+## What it does
+
+- Draws the frame's `nodes` and `links`, and draws them again when either changes.
+- Lays out only the notes without a position, in a worker, and stops once they
+  are still. Notes keep where they were when a page adds one.
+- Says where every note ended in `helix-graph-layout`, and makes the frame
+  `:state(ready)`.
+- Keeps the selection the same in the list and the drawing. A note chosen in
+  the list is brought into view. The selected note's links and backlinks stand
+  out, and the rest of the graph is faded.
+- Colors each `group` from the series tokens, the selected note from `primary`,
+  and the labels in the theme's face, and draws them again when the theme
+  changes.
+- Answers the frame's pan and zoom buttons and keys, and tells the renderer which
+  gestures the frame's `gestures` lets it take.
+
+## What it exports
+
+| Import | What |
+|---|---|
+| `@fusion.dev/helix-graph` | `connectGraph`, `graphColorsFrom`, `seedPositions`, and the `GraphDriver` type |
+| `@fusion.dev/helix-graph/sigma` | `sigmaDriver(sigma, options)` |
+
+**Neither Sigma nor graphology is a dependency.** The driver types the renderer
+by the calls it makes on it, so a page brings whichever version it has. A spec
+holds those shapes to the real classes, so a renamed method fails a typecheck
+here rather than a page.
+
+| `connectGraph` option | Default | What else it takes |
+|---|---|---|
+| `center` | `true` | `false` leaves the view where it is when a note is chosen in the list |
+
+| `sigmaDriver` option | Default | What else it takes |
+|---|---|---|
+| `layout` | none | A function that makes a layout for the graph, such as ForceAtlas2's worker |
+| `layoutLimit` | `10000` | The longest a layout runs, in milliseconds, about where 10,000 notes settle |
+
+## Working on it
+
+```sh
+bun run --filter @fusion.dev/helix-graph build
+bun run --filter @fusion.dev/helix-graph test
+```

package/dist/connect-graph/connect-graph.d.ts

@@ -0,0 +1,94 @@
+import { type ViewportGestureMode } from '@fusion.dev/helix-core';
+import { type GraphLooks } from './looks.js';
+import { type GraphPoint } from './seed.js';
+/** A note as the renderer draws it, placed. */
+export interface DrawnNode {
+    id: string;
+    label: string;
+    /** How large it is drawn, relative to the others: the note's `size`, or 1. */
+    size: number;
+    x: number;
+    y: number;
+}
+/** A link as the renderer draws it, between two notes the graph holds. */
+export interface DrawnLink {
+    label?: string | undefined;
+    source: string;
+    target: string;
+}
+/**
+ * What a renderer has to answer for the frame to drive it, and nothing that is
+ * the same for every renderer: that is the connector's.
+ *
+ * **Pixels in, whatever the renderer calls them out.** The frame asks in
+ * reading order and in fractions of the viewport, and the connector turns that
+ * into pixels on screen before a driver sees it, so which way `start` is on a
+ * right-to-left page is answered once.
+ */
+export interface GraphDriver {
+    /**
+     * Draws the graph, replacing whatever was drawn, where each note is placed.
+     * Keep the view where it is: a note added to a graph is no reason to move.
+     */
+    draw(graph: {
+        links: DrawnLink[];
+        nodes: DrawnNode[];
+    }): void;
+    /**
+     * How each note and link is drawn from now on, asked one at a time as the
+     * renderer draws them: a selection or a theme changed.
+     */
+    look(looks: GraphLooks): void;
+    /** Moves the view by pixels on screen, over a short animation or at once. */
+    panBy(x: number, y: number, animate: boolean): void;
+    /** Zooms the view one step about its middle: `1` in and `-1` out. */
+    zoomBy(direction: 1 | -1, animate: boolean): void;
+    /** Brings a note into the middle of the view, where the renderer can. */
+    center?(id: string, animate: boolean): void;
+    /** Calls `press` with a note's `id` when the reader presses it in the drawing. Returns what stops listening. */
+    onPress?(press: (id: string) => void): () => void;
+    /**
+     * Runs a layout over the drawn graph, moving the notes in `unplaced` and
+     * holding the rest, and calls `placed` once it has settled with where every
+     * note ended. Returns what stops it early. Without one, notes stay where the
+     * connector started them.
+     */
+    settle?(unplaced: ReadonlySet<string>, placed: (positions: ReadonlyMap<string, GraphPoint>) => void): () => void;
+    /**
+     * Which gestures the renderer takes from the page, as the frame's
+     * `gestures` decides. `free` is what the renderer did before it was told
+     * otherwise. `cooperative` leaves the wheel and one finger to the page and
+     * takes the wheel with Ctrl or ⌘, and two fingers. `off` takes none.
+     */
+    gestures?(mode: ViewportGestureMode): void;
+    /** The element the renderer made focusable, which the connector takes out of the tab order. */
+    focusTarget?(): HTMLElement | null;
+}
+/** How a connection behaves where the page does not say. */
+export interface ConnectGraphOptions {
+    /**
+     * Whether selecting a note in the list brings it into the middle of the
+     * view. On by default. A note pressed in the drawing is never moved: the
+     * reader is already looking at it.
+     */
+    center?: boolean | undefined;
+}
+/** A connection, which is ended rather than left to leak. */
+export interface GraphConnection {
+    /** Stops answering the frame and puts back everything connecting changed. */
+    disconnect(): void;
+    /** Lays the graph out again from where it starts, ignoring where the last layout put each note. */
+    relayout(): void;
+}
+/**
+ * Connects a Graph frame to whatever draws the graph.
+ *
+ * The frame is `helix-graph` or `helix-headless-graph`, and the driver is
+ * `sigmaDriver` from `@fusion.dev/helix-graph/sigma` or one of your own. The
+ * connection draws the frame's `nodes` and `links`, lays out the notes that
+ * have no position and says where it put them in `helix-graph-layout`, answers
+ * the frame's pan and zoom, keeps the selection the same in the list and the
+ * drawing, colors the graph from the page's tokens, and tells the renderer
+ * which gestures it may take.
+ */
+export declare const connectGraph: (frame: HTMLElement, driver: GraphDriver, options?: ConnectGraphOptions) => GraphConnection;

package/dist/connect-graph/connect-graph.js

@@ -0,0 +1,168 @@
+import { HelixGraphPanEvent, HelixGraphPartChangeEvent, HelixGraphZoomEvent, isRtl, watchTheme, } from '@fusion.dev/helix-core';
+import { graphColorsFrom, looksOf } from './looks.js';
+import { seedPositions } from './seed.js';
+const viewportOf = (frame) => {
+    const box = (frame.shadowRoot?.querySelector('[part="viewport"]') ?? frame).getBoundingClientRect();
+    return { height: box.height, width: box.width };
+};
+const still = () => typeof matchMedia === 'function' && matchMedia('(prefers-reduced-motion: reduce)').matches;
+export const connectGraph = (frame, driver, options = {}) => {
+    const graph = frame;
+    let known = new Map();
+    let colors = null;
+    let stopSettling;
+    let pressed;
+    let pending = 0;
+    let connected = true;
+    const restyle = () => {
+        colors ??= graphColorsFrom(frame);
+        if (!colors) {
+            return;
+        }
+        const nodes = graph.nodes ?? [];
+        const links = graph.links ?? [];
+        const selected = graph.active || undefined;
+        const near = new Set();
+        if (selected !== undefined) {
+            for (const { source, target } of links) {
+                if (source === selected) {
+                    near.add(target);
+                }
+                else if (target === selected) {
+                    near.add(source);
+                }
+            }
+        }
+        const groups = new Map(nodes.map((node) => [node.id, node.group]));
+        driver.look(looksOf({
+            colors,
+            font: getComputedStyle(frame)
+                .fontFamily.split(',')[0]
+                ?.trim()
+                .replace(/^["']|["']$/g, ''),
+            groupOf: (id) => groups.get(id),
+            groups: nodes.flatMap((node) => (node.group === undefined ? [] : [node.group])),
+            near,
+            selected,
+            shown: graph.shown,
+        }));
+    };
+    const draw = () => {
+        stopSettling?.();
+        stopSettling = undefined;
+        cancelAnimationFrame(pending);
+        const nodes = graph.nodes ?? [];
+        const ids = new Set(nodes.map((node) => node.id));
+        const links = (graph.links ?? []).filter(({ source, target }) => source !== target && ids.has(source) && ids.has(target));
+        const { positions, unplaced } = seedPositions(nodes, links, known);
+        graph.drawn?.(false);
+        driver.draw({
+            links: links.map(({ label, source, target }) => ({ label, source, target })),
+            nodes: nodes.map((node) => {
+                const at = positions.get(node.id);
+                return {
+                    id: node.id,
+                    label: node.label || node.id,
+                    size: Number.isFinite(node.size) ? node.size : 1,
+                    x: at.x,
+                    y: at.y,
+                };
+            }),
+        });
+        restyle();
+        if (unplaced.size > 0 && driver.settle) {
+            stopSettling = driver.settle(unplaced, (settled) => {
+                stopSettling = undefined;
+                known = new Map(settled);
+                graph.laidOut?.(Object.fromEntries([...settled].map(([id, at]) => [id, { ...at }])));
+                graph.drawn?.(true);
+            });
+            return;
+        }
+        known = positions;
+        pending = requestAnimationFrame(() => {
+            if (connected) {
+                graph.drawn?.(true);
+            }
+        });
+    };
+    const handlePartChange = (event) => {
+        const { kind } = event.detail;
+        if (kind === 'data') {
+            draw();
+        }
+        else if (kind === 'focus') {
+            restyle();
+            const selected = graph.active;
+            if (selected && selected !== pressed && options.center !== false) {
+                driver.center?.(selected, !still());
+            }
+            pressed = undefined;
+        }
+        else {
+            driver.gestures?.(graph.gestureMode ?? 'free');
+        }
+    };
+    const handlePan = (event) => {
+        const { by, to } = event.detail;
+        const { height, width } = viewportOf(frame);
+        const inline = (to === 'end' ? 1 : to === 'start' ? -1 : 0) * (isRtl(frame) ? -1 : 1);
+        const block = to === 'down' ? 1 : to === 'up' ? -1 : 0;
+        driver.panBy(inline * width * by, block * height * by, !still());
+    };
+    const handleZoom = (event) => {
+        const { by } = event.detail;
+        if (by !== 0) {
+            driver.zoomBy(by > 0 ? 1 : -1, !still());
+        }
+    };
+    frame.addEventListener(HelixGraphPartChangeEvent.eventName, handlePartChange);
+    frame.addEventListener(HelixGraphPanEvent.eventName, handlePan);
+    frame.addEventListener(HelixGraphZoomEvent.eventName, handleZoom);
+    const stopPress = driver.onPress?.((id) => {
+        pressed = id;
+        if (graph.requestActive?.(id) === false || graph.active !== id) {
+            pressed = undefined;
+        }
+    });
+    const focusable = driver.focusTarget?.() ?? null;
+    const tabIndex = focusable?.getAttribute('tabindex') ?? null;
+    focusable?.setAttribute('tabindex', '-1');
+    const stopTheme = watchTheme(frame, () => {
+        colors = null;
+        restyle();
+    });
+    void Promise.resolve(graph.updateComplete).then(() => {
+        if (!connected) {
+            return;
+        }
+        driver.gestures?.(graph.gestureMode ?? 'free');
+        draw();
+    });
+    return {
+        disconnect: () => {
+            connected = false;
+            cancelAnimationFrame(pending);
+            stopSettling?.();
+            stopPress?.();
+            stopTheme();
+            frame.removeEventListener(HelixGraphPartChangeEvent.eventName, handlePartChange);
+            frame.removeEventListener(HelixGraphPanEvent.eventName, handlePan);
+            frame.removeEventListener(HelixGraphZoomEvent.eventName, handleZoom);
+            if (focusable) {
+                if (tabIndex === null) {
+                    focusable.removeAttribute('tabindex');
+                }
+                else {
+                    focusable.setAttribute('tabindex', tabIndex);
+                }
+            }
+            driver.gestures?.('free');
+            graph.drawn?.(false);
+        },
+        relayout: () => {
+            known = new Map();
+            draw();
+        },
+    };
+};

package/dist/connect-graph/looks.d.ts

@@ -0,0 +1,82 @@
+/**
+ * The colors a graph is drawn in, each `rgb()`, read from the page's tokens
+ * where the frame is.
+ */
+export interface GraphColors {
+    /** What the drawing is laid on, which faded notes are mixed toward: `surface-sunken`. */
+    ground: string;
+    /** The links: `border`. */
+    line: string;
+    /** The labels: `foreground`. */
+    ink: string;
+    /** A note in no group, and the links that touch the selected note: `foreground-muted`. */
+    muted: string;
+    /** The selected note: `primary`. */
+    primary: string;
+    /** One color for each group, in the order of the groups' names: `series-1` and on. */
+    series: string[];
+}
+/**
+ * The page's colors where the frame is, or `null` while they cannot be read.
+ *
+ * **Settled by the browser and read back as `rgb()`**, because a token is not
+ * a color yet: it is `light-dark()` over a ramp, which only the browser can
+ * settle for the frame's scheme, and what it settles to may be `oklch()`,
+ * which a WebGL renderer cannot parse. Read inside the frame, so a graph in a
+ * dark region of a light page is drawn dark.
+ *
+ * **Not yet rather than never.** A stylesheet being swapped takes the tokens
+ * away for a moment, which is `null` here, and the connector asks again on the
+ * next change.
+ */
+export declare const graphColorsFrom: (element: Element) => GraphColors | null;
+/** One `rgb()` moved toward another by `amount`, from 0 to 1. */
+export declare const mixRgb: (from: string, to: string, amount: number) => string;
+/** How one note is drawn. */
+export interface NodeLook {
+    color: string;
+    /** Outside the local graph that `depth` keeps. */
+    hidden: boolean;
+    /** Its name is drawn whatever the room, as the selected note's and its neighbors' are. */
+    label: boolean;
+    /** Drawn over the rest, as the selected note and its neighbors are. */
+    raised: boolean;
+    /** The selected note. */
+    selected: boolean;
+}
+/** How one link is drawn. */
+export interface LinkLook {
+    color: string;
+    hidden: boolean;
+    raised: boolean;
+}
+/** How every note and link is drawn, asked one at a time, so ten thousand cost nothing until drawn. */
+export interface GraphLooks {
+    /** The typeface the labels are drawn in: the first of the frame's own. */
+    font: string;
+    /** The color the labels are drawn in. */
+    ink: string;
+    link(source: string, target: string): LinkLook;
+    node(id: string): NodeLook;
+}
+/**
+ * How the graph is drawn for one selection.
+ *
+ * **The neighborhood stands out and the rest steps back**, which is what
+ * selecting a note in a graph of thousands is for: the selected note in the
+ * brand color, the notes it links to and from in their groups' colors with
+ * their names drawn, and every other note faded toward the ground. With
+ * nothing selected, every note is in its group's color.
+ *
+ * Groups take the series in the order of their names, so a group keeps its
+ * color whichever notes a page loads first.
+ */
+export declare const looksOf: (options: {
+    colors: GraphColors;
+    font?: string | undefined;
+    groupOf: (id: string) => string | undefined;
+    groups: readonly string[];
+    near: ReadonlySet<string>;
+    selected: string | undefined;
+    shown: ReadonlySet<string> | undefined;
+}) => GraphLooks;

package/dist/connect-graph/looks.js

@@ -0,0 +1,99 @@
+import { readColor } from '@fusion.dev/helix-core';
+const SERIES = 24;
+const TOKENS = {
+    ground: '--helix-color-surface-sunken',
+    ink: '--helix-color-foreground',
+    line: '--helix-color-border',
+    muted: '--helix-color-foreground-muted',
+    primary: '--helix-color-primary',
+};
+export const graphColorsFrom = (element) => {
+    if (typeof document === 'undefined') {
+        return null;
+    }
+    const probe = document.createElement('span');
+    probe.style.display = 'none';
+    probe.setAttribute('aria-hidden', 'true');
+    element.append(probe);
+    try {
+        const read = (token) => {
+            if (getComputedStyle(probe).getPropertyValue(token).trim() === '') {
+                return null;
+            }
+            probe.style.color = `var(${token})`;
+            const bytes = readColor(getComputedStyle(probe).color);
+            return bytes ? `rgb(${bytes[0]}, ${bytes[1]}, ${bytes[2]})` : null;
+        };
+        const named = Object.fromEntries(Object.entries(TOKENS).map(([name, token]) => [name, read(token)]));
+        if (Object.values(named).some((one) => one === null)) {
+            return null;
+        }
+        const series = [];
+        for (let at = 1; at <= SERIES; at++) {
+            const one = read(`--helix-color-series-${at}`);
+            if (one === null) {
+                break;
+            }
+            series.push(one);
+        }
+        return { ...named, series };
+    }
+    finally {
+        probe.remove();
+    }
+};
+export const mixRgb = (from, to, amount) => {
+    const parts = (value) => value.match(/[\d.]+/g)?.map(Number) ?? [0, 0, 0];
+    const [one, other] = [parts(from), parts(to)];
+    const channel = (at) => Math.round((one[at] ?? 0) + ((other[at] ?? 0) - (one[at] ?? 0)) * amount);
+    return `rgb(${channel(0)}, ${channel(1)}, ${channel(2)})`;
+};
+const FADED = 0.75;
+export const looksOf = (options) => {
+    const { colors, groupOf, near, selected, shown } = options;
+    const order = new Map([...new Set(options.groups)].sort().map((group, at) => [group, at]));
+    const own = (id) => {
+        const group = groupOf(id);
+        const at = group === undefined ? undefined : order.get(group);
+        return at === undefined || colors.series.length === 0
+            ? colors.muted
+            : colors.series[at % colors.series.length];
+    };
+    const focused = selected !== undefined;
+    const hidden = (id) => shown !== undefined && !shown.has(id);
+    return {
+        font: options.font || 'sans-serif',
+        ink: colors.ink,
+        link: (source, target) => {
+            const touches = focused && (source === selected || target === selected);
+            return {
+                color: touches
+                    ? colors.muted
+                    : focused
+                        ? mixRgb(colors.line, colors.ground, 0.5)
+                        : colors.line,
+                hidden: hidden(source) || hidden(target),
+                raised: touches,
+            };
+        },
+        node: (id) => {
+            if (id === selected) {
+                return {
+                    color: colors.primary,
+                    hidden: hidden(id),
+                    label: true,
+                    raised: true,
+                    selected: true,
+                };
+            }
+            const neighbor = focused && near.has(id);
+            return {
+                color: focused && !neighbor ? mixRgb(own(id), colors.ground, FADED) : own(id),
+                hidden: hidden(id),
+                label: neighbor,
+                raised: neighbor,
+                selected: false,
+            };
+        },
+    };
+};

package/dist/connect-graph/seed.d.ts

@@ -0,0 +1,30 @@
+/** A point in the renderer's own units. */
+export interface GraphPoint {
+    x: number;
+    y: number;
+}
+/** A note as the connector reads it off the frame. */
+export interface SeedNode {
+    id: string;
+    x?: number | undefined;
+    y?: number | undefined;
+}
+/** A link as the connector reads it off the frame. */
+export interface SeedLink {
+    source: string;
+    target: string;
+}
+/**
+ * Where each note starts, and which of them a layout still has to place.
+ *
+ * **Kept where it is known.** A note's own `x` and `y` win, then where the
+ * last layout put it, so a page that adds one note does not watch the rest
+ * of the graph jump. A new note starts beside a placed neighbor, which is
+ * close to where a layout will want it, and a note with none starts on a
+ * spiral around the middle, in the order it was given. Nothing is random, so
+ * the same graph starts the same way on every load.
+ */
+export declare const seedPositions: (nodes: readonly SeedNode[], links: readonly SeedLink[], known?: ReadonlyMap<string, GraphPoint>) => {
+    positions: Map<string, GraphPoint>;
+    unplaced: Set<string>;
+};

package/dist/connect-graph/seed.js

@@ -0,0 +1,49 @@
+const TURN = Math.PI * (3 - Math.sqrt(5));
+const NEAR = 0.5;
+const nudge = (id) => {
+    let hash = 2166136261;
+    for (let at = 0; at < id.length; at++) {
+        hash = Math.imul(hash ^ id.charCodeAt(at), 16777619);
+    }
+    const angle = ((hash >>> 0) / 4294967296) * Math.PI * 2;
+    return { x: Math.cos(angle) * NEAR, y: Math.sin(angle) * NEAR };
+};
+export const seedPositions = (nodes, links, known = new Map()) => {
+    const positions = new Map();
+    const unplaced = new Set();
+    for (const node of nodes) {
+        if (Number.isFinite(node.x) && Number.isFinite(node.y)) {
+            positions.set(node.id, { x: node.x, y: node.y });
+        }
+        else {
+            const kept = known.get(node.id);
+            if (kept) {
+                positions.set(node.id, { ...kept });
+            }
+        }
+    }
+    const neighbors = new Map();
+    for (const { source, target } of links) {
+        neighbors.set(source, [...(neighbors.get(source) ?? []), target]);
+        neighbors.set(target, [...(neighbors.get(target) ?? []), source]);
+    }
+    let spiral = positions.size;
+    for (const node of nodes) {
+        if (positions.has(node.id)) {
+            continue;
+        }
+        unplaced.add(node.id);
+        const placed = (neighbors.get(node.id) ?? []).find((one) => positions.has(one));
+        const beside = placed === undefined ? undefined : positions.get(placed);
+        if (beside) {
+            const offset = nudge(node.id);
+            positions.set(node.id, { x: beside.x + offset.x, y: beside.y + offset.y });
+            continue;
+        }
+        const radius = Math.sqrt(spiral + 0.5);
+        const angle = spiral * TURN;
+        positions.set(node.id, { x: Math.cos(angle) * radius, y: Math.sin(angle) * radius });
+        spiral += 1;
+    }
+    return { positions, unplaced };
+};

package/dist/index.d.ts

@@ -1,2 +1,3 @@
-export {};
-//# sourceMappingURL=index.d.ts.map
+export { type ConnectGraphOptions, connectGraph, type DrawnLink, type DrawnNode, type GraphConnection, type GraphDriver, } from './connect-graph/connect-graph.js';
+export { type GraphColors, type GraphLooks, graphColorsFrom, type LinkLook, type NodeLook, } from './connect-graph/looks.js';
+export { type GraphPoint, seedPositions } from './connect-graph/seed.js';

package/dist/index.js

@@ -1,2 +1,3 @@
-export {};
-//# sourceMappingURL=index.js.map
+export { connectGraph, } from './connect-graph/connect-graph.js';
+export { graphColorsFrom, } from './connect-graph/looks.js';
+export { seedPositions } from './connect-graph/seed.js';

package/dist/sigma/index.d.ts

@@ -1,2 +1 @@
-export {};
-//# sourceMappingURL=index.d.ts.map
+export { type SigmaCamera, type SigmaDriverOptions, type SigmaGraph, type SigmaLayout, type SigmaRenderer, sigmaDriver, } from './sigma-driver.js';

package/dist/sigma/index.js

@@ -1,2 +1 @@
-export {};
-//# sourceMappingURL=index.js.map
+export { sigmaDriver, } from './sigma-driver.js';

package/dist/sigma/sigma-driver.d.ts

@@ -0,0 +1,105 @@
+import type { GraphDriver } from '../connect-graph/connect-graph.js';
+/** A graphology graph, as far as the driver calls it. */
+export interface SigmaGraph {
+    addEdge(source: string, target: string, attributes?: Record<string, unknown>): unknown;
+    addNode(node: string, attributes?: Record<string, unknown>): unknown;
+    clear(): void;
+    forEachNode(callback: (node: string, attributes: Record<string, unknown>) => void): void;
+    getNodeAttributes(node: string): Record<string, unknown>;
+    hasEdge(source: string, target: string): boolean;
+    hasNode(node: string): boolean;
+    readonly order: number;
+    setNodeAttribute(node: string, name: string, value: unknown): unknown;
+}
+/** Sigma's camera, as far as the driver calls it. */
+export interface SigmaCamera {
+    animate(state: {
+        ratio?: number;
+        x?: number;
+        y?: number;
+    }, options?: {
+        duration?: number;
+    }): unknown;
+    getState(): {
+        angle: number;
+        ratio: number;
+        x: number;
+        y: number;
+    };
+    setState(state: {
+        ratio?: number;
+        x?: number;
+        y?: number;
+    }): unknown;
+}
+/** A Sigma renderer, as far as the driver calls it. */
+export interface SigmaRenderer {
+    getCamera(): SigmaCamera;
+    getContainer(): HTMLElement;
+    getDimensions(): {
+        height: number;
+        width: number;
+    };
+    getGraph(): SigmaGraph;
+    getNodeDisplayData(node: string): {
+        x: number;
+        y: number;
+    } | undefined;
+    off(type: 'clickNode', listener: (payload: {
+        node: string;
+    }) => void): unknown;
+    on(type: 'clickNode', listener: (payload: {
+        node: string;
+    }) => void): unknown;
+    refresh(): unknown;
+    setSetting(name: 'edgeReducer' | 'labelColor' | 'labelFont' | 'nodeReducer', value: unknown): unknown;
+    viewportToFramedGraph(point: {
+        x: number;
+        y: number;
+    }): {
+        x: number;
+        y: number;
+    };
+}
+/** A layout that runs over a graphology graph until it is stopped, as ForceAtlas2's worker does. */
+export interface SigmaLayout {
+    kill(): void;
+    start(): void;
+    stop(): void;
+}
+/** How the Sigma driver behaves where the page does not say. */
+export interface SigmaDriverOptions {
+    /**
+     * Makes a layout for the graph, which the driver runs where notes have no
+     * position and stops once they have settled. ForceAtlas2's worker is the
+     * one to use:
+     *
+     * ```js
+     * import FA2Layout from 'graphology-layout-forceatlas2/worker'
+     * import forceAtlas2 from 'graphology-layout-forceatlas2'
+     *
+     * sigmaDriver(sigma, {
+     *   layout: (graph) => new FA2Layout(graph, { settings: forceAtlas2.inferSettings(graph) }),
+     * })
+     * ```
+     *
+     * Without one, notes stay where the connector started them.
+     */
+    layout?: ((graph: SigmaGraph) => SigmaLayout) | undefined;
+    /** The longest a layout runs, in milliseconds, settled or not. 10 seconds by default, about where 10,000 notes settle. */
+    layoutLimit?: number | undefined;
+}
+/**
+ * Drives Sigma.js for a Graph frame. Make the renderer with an empty
+ * graphology graph and pass it here, and `connectGraph` fills it:
+ *
+ * ```js
+ * const sigma = new Sigma(new Graph(), container)
+ * connectGraph(frame, sigmaDriver(sigma, { layout }))
+ * ```
+ *
+ * **Neither Sigma nor graphology is a dependency.** The driver types the
+ * renderer by the calls it makes on it, so a page brings whichever version it
+ * has, and a spec holds those shapes to the real classes.
+ */
+export declare const sigmaDriver: (sigma: SigmaRenderer, options?: SigmaDriverOptions) => GraphDriver;

package/dist/sigma/sigma-driver.js

@@ -0,0 +1,207 @@
+const STEP = 250;
+const ZOOM = 1.5;
+const SAMPLE = 250;
+const STILL = 0.004;
+const HELD = 2;
+const IDLE = 2000;
+const pixels = (size) => 2 + 2 * Math.sqrt(Math.max(size, 0));
+const positionsOf = (graph) => {
+    const positions = new Map();
+    graph.forEachNode((node, attributes) => {
+        positions.set(node, { x: Number(attributes.x), y: Number(attributes.y) });
+    });
+    return positions;
+};
+export const sigmaDriver = (sigma, options = {}) => {
+    const graph = sigma.getGraph();
+    const container = sigma.getContainer();
+    const camera = sigma.getCamera();
+    let mode = 'free';
+    const touchAction = container.style.touchAction;
+    const hold = (event) => {
+        if (mode === 'free') {
+            return;
+        }
+        if (mode === 'off') {
+            event.stopImmediatePropagation();
+            return;
+        }
+        if (event instanceof WheelEvent) {
+            if (!(event.ctrlKey || event.metaKey)) {
+                event.stopImmediatePropagation();
+            }
+            return;
+        }
+        if (typeof TouchEvent !== 'undefined' && event instanceof TouchEvent) {
+            if (event.touches.length < 2) {
+                event.stopImmediatePropagation();
+            }
+            else if (event.type === 'touchstart' && event.cancelable) {
+                event.preventDefault();
+            }
+        }
+    };
+    const held = ['wheel', 'touchstart', 'touchmove', 'mousedown'];
+    for (const type of held) {
+        container.addEventListener(type, hold, { capture: true, passive: false });
+    }
+    return {
+        center: (id, animate) => {
+            const at = sigma.getNodeDisplayData(id);
+            if (!at) {
+                return;
+            }
+            if (animate) {
+                camera.animate({ x: at.x, y: at.y }, { duration: STEP * 2 });
+            }
+            else {
+                camera.setState({ x: at.x, y: at.y });
+            }
+        },
+        draw: ({ links, nodes }) => {
+            graph.clear();
+            for (const node of nodes) {
+                graph.addNode(node.id, {
+                    label: node.label,
+                    size: pixels(node.size),
+                    x: node.x,
+                    y: node.y,
+                });
+            }
+            for (const link of links) {
+                if (!graph.hasEdge(link.source, link.target)) {
+                    graph.addEdge(link.source, link.target, {
+                        from: link.source,
+                        label: link.label,
+                        size: 1,
+                        to: link.target,
+                    });
+                }
+            }
+        },
+        gestures: (next) => {
+            mode = next;
+            container.style.touchAction =
+                next === 'free' ? touchAction : next === 'cooperative' ? 'pan-x pan-y' : 'auto';
+        },
+        look: (looks) => {
+            sigma.setSetting('labelColor', { color: looks.ink });
+            sigma.setSetting('labelFont', looks.font);
+            sigma.setSetting('nodeReducer', (node, data) => {
+                const look = looks.node(node);
+                return {
+                    ...data,
+                    color: look.color,
+                    forceLabel: look.label,
+                    hidden: look.hidden,
+                    size: look.selected && typeof data.size === 'number' ? data.size * 1.5 : data.size,
+                    zIndex: look.selected ? 2 : look.raised ? 1 : 0,
+                };
+            });
+            sigma.setSetting('edgeReducer', (_edge, data) => {
+                const look = looks.link(String(data.from), String(data.to));
+                return {
+                    ...data,
+                    color: look.color,
+                    hidden: look.hidden,
+                    size: look.raised ? 1.5 : 1,
+                    zIndex: look.raised ? 1 : 0,
+                };
+            });
+            sigma.refresh();
+        },
+        onPress: (press) => {
+            const listener = ({ node }) => press(node);
+            sigma.on('clickNode', listener);
+            return () => {
+                sigma.off('clickNode', listener);
+            };
+        },
+        panBy: (x, y, animate) => {
+            const { height, width } = sigma.getDimensions();
+            const to = sigma.viewportToFramedGraph({ x: width / 2 + x, y: height / 2 + y });
+            if (animate) {
+                camera.animate(to, { duration: STEP });
+            }
+            else {
+                camera.setState(to);
+            }
+        },
+        zoomBy: (direction, animate) => {
+            const ratio = camera.getState().ratio * (direction > 0 ? 1 / ZOOM : ZOOM);
+            if (animate) {
+                camera.animate({ ratio }, { duration: STEP });
+            }
+            else {
+                camera.setState({ ratio });
+            }
+        },
+        ...(options.layout
+            ? {
+                settle: (unplaced, placed) => {
+                    const make = options.layout;
+                    graph.forEachNode((node) => {
+                        graph.setNodeAttribute(node, 'fixed', !unplaced.has(node));
+                    });
+                    const layout = make(graph);
+                    layout.start();
+                    const limit = options.layoutLimit ?? 10000;
+                    const started = performance.now();
+                    let last = positionsOf(graph);
+                    let done = false;
+                    let moving = false;
+                    let held = 0;
+                    const finish = () => {
+                        if (done) {
+                            return;
+                        }
+                        done = true;
+                        clearInterval(timer);
+                        layout.stop();
+                        layout.kill();
+                        graph.forEachNode((node) => {
+                            graph.setNodeAttribute(node, 'fixed', false);
+                        });
+                        placed(positionsOf(graph));
+                    };
+                    const timer = setInterval(() => {
+                        const now = positionsOf(graph);
+                        let moved = 0;
+                        let low = Number.POSITIVE_INFINITY;
+                        let high = Number.NEGATIVE_INFINITY;
+                        for (const [id, at] of now) {
+                            const was = last.get(id);
+                            if (was) {
+                                moved += Math.hypot(at.x - was.x, at.y - was.y);
+                            }
+                            low = Math.min(low, at.x, at.y);
+                            high = Math.max(high, at.x, at.y);
+                        }
+                        last = now;
+                        const extent = Math.max(high - low, 1);
+                        if (moved / Math.max(now.size, 1) / extent >= STILL) {
+                            moving = true;
+                            held = 0;
+                        }
+                        else if (moving) {
+                            held += 1;
+                        }
+                        const elapsed = performance.now() - started;
+                        if ((moving && held >= HELD) || (!moving && elapsed > IDLE) || elapsed > limit) {
+                            finish();
+                        }
+                    }, SAMPLE);
+                    return () => {
+                        if (done) {
+                            return;
+                        }
+                        done = true;
+                        clearInterval(timer);
+                        layout.stop();
+                        layout.kill();
+                    };
+                },
+            }
+            : {}),
+    };
+};

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@fusion.dev/helix-graph",
   "description": "Connects the Helix Graph frame to a graph renderer: Sigma.js, or a driver of your own.",
-  "version": "0.0.0-dev",
+  "version": "0.118.0",
   "license": "MIT",
   "author": "Ross Sheppard <ross.sheppard@fusion.dev>",
   "repository": {
@@ -35,11 +35,11 @@
   },
   "bugs": "https://github.com/project-fusion/fusion/issues",
   "dependencies": {
-    "@fusion.dev/helix-core": "0.115.0"
+    "@fusion.dev/helix-core": "0.118.0"
   },
   "devDependencies": {
-    "@fusion.dev/helix-headless": "0.115.0",
-    "@fusion.dev/helix-testing": "0.115.0",
+    "@fusion.dev/helix-headless": "0.118.0",
+    "@fusion.dev/helix-testing": "0.118.0",
     "@types/bun": "^1.3.0",
     "graphology": "^0.26.0",
     "graphology-layout-forceatlas2": "^0.10.1",

package/dist/index.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,CAAA"}

package/dist/index.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,CAAA"}

package/dist/sigma/index.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/sigma/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,CAAA"}

package/dist/sigma/index.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/sigma/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,CAAA"}