@fusion.dev/helix-graph 0.120.0 → 0.121.0

package/dist/cosmos/cosmos-driver.js

@@ -0,0 +1,467 @@
+import { gesturesHeld, groupsOver, signalsOver } from '../overlay/overlay.js';
+const SHAPES = { circle: 0, diamond: 3, ring: 0, square: 1 };
+const STEP = 250;
+const FAINT = 0.16;
+const MORPH = 1400;
+const ZOOM = 1.5;
+const SAMPLE = 24;
+const pixels = (size) => 0.5 * (1.6 + 1.35 * Math.max(size, 0));
+const CLUSTER = 0.1;
+const FOLLOW = 1000;
+const PADDING = 0.08;
+const channels = (color, alpha = 1) => {
+    const [red = 128, green = 128, blue = 128] = color.match(/[\d.]+/g)?.map(Number) ?? [];
+    return [red / 255, green / 255, blue / 255, alpha];
+};
+export const cosmosDriver = (graph, container, options = {}) => {
+    let ids = [];
+    let index = new Map();
+    let drawnNow = new Map();
+    let links = [];
+    let sizes = [];
+    let looks;
+    let hovered;
+    let selected;
+    let near = new Set();
+    let groupSample = [];
+    let following = new Set();
+    let moved = false;
+    let stopped = false;
+    let uploaded = 0;
+    const live = () => graph.isReady && uploaded > 0 && !stopped;
+    let clustered = [];
+    const space = options.spaceSize ?? 4096;
+    let scale = 1;
+    const toSpace = (point) => [
+        space / 2 + point.x * scale,
+        space / 2 + point.y * scale,
+    ];
+    const fromSpace = (x, y) => ({
+        x: (x - space / 2) / scale,
+        y: (y - space / 2) / scale,
+    });
+    const follow = (extra = []) => {
+        const next = new Set(groupSample);
+        for (const id of [selected, ...near]) {
+            const at = id === undefined ? undefined : index.get(id);
+            if (at !== undefined) {
+                next.add(at);
+            }
+        }
+        if (hovered !== undefined) {
+            next.add(hovered);
+        }
+        for (const at of extra) {
+            next.add(at);
+        }
+        if (next.size !== following.size || [...next].some((at) => !following.has(at))) {
+            following = next;
+            graph.trackPointPositionsByIndices([...next]);
+        }
+    };
+    let tracked = new Map();
+    let trackedAt = Number.NEGATIVE_INFINITY;
+    const positionsNow = () => {
+        const now = performance.now();
+        if (now - trackedAt > 8 && live()) {
+            tracked = graph.getTrackedPointPositionsMap();
+            trackedAt = now;
+        }
+        return tracked;
+    };
+    const onScreen = (id) => {
+        const at = index.get(id);
+        const point = at === undefined ? undefined : positionsNow().get(at);
+        if (!point || at === undefined) {
+            return undefined;
+        }
+        const [x, y] = graph.spaceToScreenPosition(point);
+        return { radius: (sizes[at] ?? 8) / 2, x, y };
+    };
+    const held = gesturesHeld(container);
+    const signals = signalsOver(container, onScreen);
+    const groups = groupsOver(container, onScreen);
+    const names = document.createElement('canvas');
+    names.setAttribute('aria-hidden', 'true');
+    names.style.cssText = 'position:absolute;inset:0;width:100%;height:100%;pointer-events:none';
+    container.append(names);
+    const drawNames = () => {
+        const context = names.getContext('2d');
+        if (!context || !looks) {
+            return;
+        }
+        const ratio = window.devicePixelRatio || 1;
+        const width = Math.round(container.clientWidth * ratio);
+        const height = Math.round(container.clientHeight * ratio);
+        if (names.width !== width || names.height !== height) {
+            names.width = width;
+            names.height = height;
+        }
+        context.setTransform(ratio, 0, 0, ratio, 0, 0);
+        context.clearRect(0, 0, width, height);
+        const taken = [];
+        const shown = [selected, hovered === undefined ? undefined : ids[hovered], ...near];
+        for (const id of shown) {
+            if (id === undefined) {
+                continue;
+            }
+            const at = onScreen(id);
+            const label = looks.node(id);
+            if (!at || label.hidden) {
+                continue;
+            }
+            const name = drawnNow.get(id)?.label ?? id;
+            const strong = id === selected || id === ids[hovered ?? -1];
+            context.font = `${strong ? 600 : 500} ${strong ? 13 : 12}px ${looks.font}`;
+            const x = at.x + at.radius + 4;
+            const y = at.y + 4;
+            const box = {
+                bottom: y + 4,
+                left: x - 2,
+                right: x + context.measureText(name).width + 2,
+                top: y - 13,
+            };
+            const free = taken.every((other) => box.right < other.left ||
+                box.left > other.right ||
+                box.bottom < other.top ||
+                box.top > other.bottom);
+            if (!free && !strong) {
+                continue;
+            }
+            taken.push(box);
+            context.lineJoin = 'round';
+            context.lineWidth = 3;
+            context.strokeStyle = looks.ground;
+            context.strokeText(name, x, y);
+            context.fillStyle = strong ? looks.ink : looks.quiet;
+            context.fillText(name, x, y);
+        }
+    };
+    const redraw = () => {
+        drawNames();
+        groups.draw();
+    };
+    const flatNow = () => live()
+        ? graph.getPointPositions()
+        : ids.flatMap((id) => toSpace(drawnNow.get(id) ?? { x: 0, y: 0 }));
+    const fitAll = (duration) => {
+        if (stopped) {
+            return;
+        }
+        if (!graph.isReady) {
+            void graph.ready.then(() => requestAnimationFrame(() => fitAll(duration)));
+            return;
+        }
+        if (!moved && live()) {
+            graph.fitView(duration, PADDING);
+            clearTimeout(overviewing);
+            overviewing = setTimeout(() => {
+                overview = graph.getZoomLevel();
+                grow();
+            }, duration + 20);
+        }
+    };
+    let overview = 0;
+    let overviewing;
+    let grown = 1;
+    const grow = () => {
+        const by = overview > 0 ? Math.min(Math.max(Math.sqrt(graph.getZoomLevel() / overview), 0.7), 2.4) : 1;
+        if (Math.abs(by - grown) > 0.01) {
+            grown = by;
+            graph.setConfigPartial({ pointSizeScale: by });
+            if (Math.abs(clarity() - painted) > 0.04) {
+                paintLinks();
+                graph.render();
+            }
+        }
+    };
+    const clarity = () => FAINT + (1 - FAINT) * Math.min(Math.max((grown - 1) / 0.8, 0), 1);
+    let painted = 1;
+    const paintLinks = () => {
+        if (!looks) {
+            return;
+        }
+        painted = clarity();
+        const linkColors = new Float32Array(links.length * 4);
+        const widths = new Float32Array(links.length);
+        const lit = hovered === undefined ? undefined : ids[hovered];
+        links.forEach((link, at) => {
+            const look = looks.link(link.source, link.target);
+            const touches = lit !== undefined && (link.source === lit || link.target === lit);
+            const whole = look.raised || touches;
+            linkColors.set(channels(touches ? looks.node(lit).color : look.color, look.hidden ? 0 : whole ? 1 : painted), at * 4);
+            widths[at] = whole ? 1.6 : 0.8;
+        });
+        graph.setLinkColors(linkColors);
+        graph.setLinkWidths(widths);
+    };
+    const paint = (transition = 0) => {
+        if (!looks) {
+            return;
+        }
+        const colors = new Float32Array(ids.length * 4);
+        const drawn = new Float32Array(ids.length);
+        const shapes = new Float32Array(ids.length);
+        selected = undefined;
+        near = new Set();
+        ids.forEach((id, at) => {
+            const look = looks.node(id);
+            const weight = Math.min(Math.max(((drawnNow.get(id)?.size ?? 1) - 1) / 6, 0), 1);
+            const alpha = look.selected || look.raised ? 1 : 0.5 + 0.5 * weight;
+            colors.set(channels(look.color, look.hidden ? 0 : alpha), at * 4);
+            drawn[at] = (sizes[at] ?? 8) * (look.selected ? 1.5 : look.raised ? 1.25 : 1);
+            shapes[at] = SHAPES[look.shape ?? options.shape ?? 'circle'];
+            if (look.selected) {
+                selected = id;
+            }
+            else if (look.raised) {
+                near.add(id);
+            }
+        });
+        graph.setPointColors(colors);
+        graph.setPointSizes(drawn);
+        graph.setPointShapes(shapes);
+        paintLinks();
+        const focused = selected === undefined ? undefined : index.get(selected);
+        graph.setConfigPartial({
+            focusedPointIndex: focused,
+            focusedPointRingColor: selected === undefined ? undefined : channels(looks.node(selected).color),
+            hoveredPointRingColor: channels(looks.ink, 0.6),
+        });
+        follow();
+        if (transition > 0) {
+            graph.render(undefined, transition);
+        }
+        else {
+            graph.render();
+        }
+        redraw();
+    };
+    const load = (nodes, next, positions, transition = 0) => {
+        ids = nodes.map((node) => node.id);
+        index = new Map(ids.map((id, at) => [id, at]));
+        drawnNow = new Map(nodes.map((node) => [node.id, node]));
+        sizes = nodes.map((node) => pixels(node.size));
+        links = next.filter((link) => index.has(link.source) && index.has(link.target));
+        const pairs = new Float32Array(links.length * 2);
+        links.forEach((link, at) => {
+            pairs[at * 2] = index.get(link.source);
+            pairs[at * 2 + 1] = index.get(link.target);
+        });
+        graph.setPointPositions(positions, true);
+        graph.setLinks(pairs);
+        paint(transition);
+        uploaded = 0;
+        if (graph.isReady) {
+            uploaded = ids.length;
+        }
+        else {
+            void graph.ready.then(() => {
+                uploaded = ids.length;
+            });
+        }
+    };
+    graph.setConfigPartial({
+        backgroundColor: [0, 0, 0, 0],
+        onPointMouseOut: () => {
+            hovered = undefined;
+            paint();
+        },
+        onPointMouseOver: (at) => {
+            hovered = at;
+            paint();
+        },
+        onSimulationTick: redraw,
+        onTransition: redraw,
+        onZoom: () => {
+            grow();
+            redraw();
+        },
+        onZoomStart: (_, userDriven) => {
+            moved ||= userDriven;
+        },
+        simulationDecay: 600,
+        simulationGravity: 1.5,
+        simulationLinkDistance: 30,
+        simulationLinkSpring: 0.15,
+        simulationRepulsion: 30,
+        spaceSize: space,
+    });
+    return {
+        center: (id, animate) => {
+            const at = index.get(id);
+            if (at !== undefined) {
+                graph.zoomToPointByIndex(at, animate ? STEP * 2 : 0, graph.getZoomLevel(), true);
+            }
+        },
+        draw: ({ links: next, nodes }) => {
+            const reach = Math.max(1, ...nodes.map((node) => Math.max(Math.abs(node.x), Math.abs(node.y))));
+            scale = (space * 0.12) / reach;
+            moved = false;
+            const positions = new Float32Array(nodes.length * 2);
+            nodes.forEach((node, at) => {
+                positions.set(toSpace(node), at * 2);
+            });
+            load(nodes, next, positions);
+            graph.pause();
+            fitAll(0);
+        },
+        fit: (fitted, animate) => {
+            const indices = fitted.flatMap((id) => {
+                const at = index.get(id);
+                return at === undefined ? [] : [at];
+            });
+            graph.fitViewByPointIndices(indices, animate ? STEP * 2 : 0, 0.25);
+        },
+        gestures: (next) => {
+            held.set(next);
+        },
+        groups: (next) => {
+            if (options.groupLabels === false) {
+                return;
+            }
+            groupSample = next.flatMap((group) => group.ids.slice(0, SAMPLE).flatMap((id) => {
+                const at = index.get(id);
+                return at === undefined ? [] : [at];
+            }));
+            follow();
+            groups.set(next.map((group) => ({ ...group, ids: group.ids.slice(0, SAMPLE) })));
+            const cluster = new Map();
+            next.forEach((group, at) => {
+                for (const id of group.ids) {
+                    cluster.set(id, at);
+                }
+            });
+            const clusters = ids.map((id) => cluster.get(id));
+            if (clusters.length === clustered.length &&
+                clusters.every((at, position) => at === clustered[position])) {
+                return;
+            }
+            clustered = clusters;
+            graph.setPointClusters(clusters);
+            graph.setClusterPositions(next.flatMap((_, at) => {
+                const turn = (at / Math.max(next.length, 1)) * Math.PI * 2;
+                return [
+                    space / 2 + Math.cos(turn) * space * 0.2,
+                    space / 2 + Math.sin(turn) * space * 0.2,
+                ];
+            }));
+            graph.setConfigPartial({ simulationCluster: next.length > 1 ? CLUSTER : 0 });
+            graph.render();
+        },
+        look: (next) => {
+            looks = next;
+            signals.look(next);
+            groups.look(next);
+            paint();
+        },
+        onPress: (press) => {
+            graph.setConfigPartial({
+                onPointClick: (at) => {
+                    const id = ids[at];
+                    if (id !== undefined) {
+                        press(id);
+                    }
+                },
+            });
+            return () => graph.setConfigPartial({ onPointClick: undefined });
+        },
+        panBy: (x, y, animate) => {
+            const { height, width } = container.getBoundingClientRect();
+            const to = graph.screenToSpacePosition([width / 2 + x, height / 2 + y]);
+            graph.setZoomTransformByPointPositions(new Float32Array(to), animate ? STEP : 0, graph.getZoomLevel());
+        },
+        settle: (unplaced, placed) => {
+            graph.setPinnedPoints(ids.flatMap((id, at) => (unplaced.has(id) ? [] : [at])));
+            let done = false;
+            const finish = () => {
+                if (done) {
+                    return;
+                }
+                done = true;
+                clearTimeout(limit);
+                clearInterval(fitting);
+                graph.setPinnedPoints(null);
+                graph.pause();
+                fitAll(STEP * 2);
+                const flat = flatNow();
+                placed(new Map(ids.map((id, at) => [id, fromSpace(flat[at * 2] ?? 0, flat[at * 2 + 1] ?? 0)])));
+            };
+            graph.setConfigPartial({ onSimulationEnd: finish });
+            graph.start(1);
+            const limit = setTimeout(finish, options.layoutLimit ?? 15000);
+            const fitting = setInterval(() => fitAll(FOLLOW), FOLLOW);
+            return () => {
+                done = true;
+                clearTimeout(limit);
+                clearInterval(fitting);
+                graph.setConfigPartial({ onSimulationEnd: undefined });
+                graph.setPinnedPoints(null);
+            };
+        },
+        signal: (from, to, colors, animate) => {
+            const ends = [index.get(from), index.get(to)].filter((at) => at !== undefined);
+            follow(ends);
+            signals.signal(from, to, colors, animate);
+        },
+        stop: () => {
+            stopped = true;
+            clearTimeout(overviewing);
+            graph.setConfigPartial({
+                onPointClick: undefined,
+                onPointMouseOut: undefined,
+                onPointMouseOver: undefined,
+                onSimulationEnd: undefined,
+                onSimulationTick: undefined,
+                onTransition: undefined,
+                onZoom: undefined,
+            });
+            signals.stop();
+            groups.stop();
+            names.remove();
+            held.stop();
+        },
+        update: (changes, animate) => {
+            const flat = flatNow();
+            const kept = new Map();
+            ids.forEach((id, at) => {
+                const node = drawnNow.get(id);
+                if (node) {
+                    kept.set(id, { ...node, ...fromSpace(flat[at * 2] ?? 0, flat[at * 2 + 1] ?? 0) });
+                }
+            });
+            for (const id of changes.removeNodes) {
+                kept.delete(id);
+            }
+            let shifted = false;
+            for (const node of changes.changeNodes) {
+                const was = drawnNow.get(node.id);
+                const moved = was !== undefined && (was.x !== node.x || was.y !== node.y);
+                shifted ||= moved;
+                const now = kept.get(node.id);
+                kept.set(node.id, moved || !now ? node : { ...node, x: now.x, y: now.y });
+            }
+            for (const node of changes.addNodes) {
+                kept.set(node.id, node);
+            }
+            const removed = new Set(changes.removeLinks.map((link) => `${link.source}\u0000${link.target}`));
+            const next = [
+                ...links.filter((link) => !removed.has(`${link.source}\u0000${link.target}`)),
+                ...changes.addLinks,
+            ];
+            const nodes = [...kept.values()];
+            const positions = new Float32Array(nodes.length * 2);
+            nodes.forEach((node, at) => {
+                positions.set(toSpace(node), at * 2);
+            });
+            const glide = shifted && animate ? MORPH : 0;
+            load(nodes, next, positions, glide);
+            if (shifted) {
+                fitAll(glide);
+            }
+        },
+        zoomBy: (direction, animate) => {
+            graph.setZoomLevel(graph.getZoomLevel() * (direction > 0 ? ZOOM : 1 / ZOOM), animate ? STEP : 0);
+        },
+    };
+};

package/dist/cosmos/index.d.ts

@@ -0,0 +1 @@
+export { type CosmosDriverOptions, type CosmosGraph, cosmosDriver } from './cosmos-driver.js';

package/dist/cosmos/index.js

@@ -0,0 +1 @@
+export { cosmosDriver } from './cosmos-driver.js';

package/dist/index.d.ts

@@ -1,4 +1,5 @@
-export { type ConnectGraphOptions, connectGraph, type DrawnLink, type DrawnNode, type GraphChanges, type GraphConnection, type GraphDriver, } from './connect-graph/connect-graph.js';
+export { type ConnectGraphOptions, connectGraph, type DrawnLink, type DrawnNode, type GraphChanges, type GraphConnection, type GraphDriver, type GraphGroup, } from './connect-graph/connect-graph.js';
 export { diffGraph } from './connect-graph/diff.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';
+export { fitToStencil, type GraphStencil } from './connect-graph/stencil.js';

package/dist/index.js

@@ -2,3 +2,4 @@ export { connectGraph, } from './connect-graph/connect-graph.js';
 export { diffGraph } from './connect-graph/diff.js';
 export { graphColorsFrom, } from './connect-graph/looks.js';
 export { seedPositions } from './connect-graph/seed.js';
+export { fitToStencil } from './connect-graph/stencil.js';

package/dist/overlay/overlay.d.ts

@@ -0,0 +1,59 @@
+import type { ViewportGestureMode } from '@fusion.dev/helix-core';
+import type { GraphGroup } from '../connect-graph/connect-graph.js';
+import { type GraphLooks } from '../connect-graph/looks.js';
+/** Where a note is on screen and how large, or nothing where it is not drawn. */
+export type OnScreen = (id: string) => {
+    radius: number;
+    x: number;
+    y: number;
+} | undefined;
+/** Eases in and out, so a signal leaves and arrives gently. */
+export declare const ease: (at: number) => number;
+/** A name's box on screen, in pixels. */
+export interface Box {
+    bottom: number;
+    left: number;
+    right: number;
+    top: number;
+}
+/**
+ * **Signals are drawn on a canvas of the driver's own**, over the renderer's,
+ * so a signal never makes the renderer redraw the graph: ten signals a second
+ * over ten thousand notes draw ten dots. It draws only while something is in
+ * flight, and takes no pointer, so a press reaches the note under it.
+ */
+export declare const signalsOver: (container: HTMLElement, onScreen: OnScreen) => {
+    look: (looks: GraphLooks) => void;
+    signal: (from: string, to: string, colors: {
+        from: string;
+        to: string;
+    } | undefined, animate: boolean) => void;
+    stop: () => void;
+};
+/**
+ * **Group names are drawn on a canvas of their own**, under the signals', and
+ * drawn again whenever the driver says the view moved, so they follow it.
+ */
+export declare const groupsOver: (container: HTMLElement, onScreen: OnScreen) => {
+    draw: () => void;
+    look: (next: GraphLooks) => void;
+    set: (next: readonly GraphGroup[]) => void;
+    stop: () => void;
+};
+/**
+ * **Held back from the renderer rather than switched off in it.** A
+ * renderer's own switches turn its zoom and pan off for code as well, so the
+ * frame's buttons stopped working with them. A listener on the container in
+ * the capture phase runs before the renderer's, and keeps from it what the
+ * page has: the plain wheel and one finger while cooperative, and every
+ * gesture while a waiting surface is off.
+ */
+export declare const gesturesHeld: (container: HTMLElement) => {
+    /**
+     * Which gestures the renderer takes. One finger scrolls the page past a
+     * graph that shares its gestures, and every finger does past one that is
+     * off.
+     */
+    set: (next: ViewportGestureMode) => void;
+    stop: () => void;
+};