@fusion.dev/helix-graph 0.126.0 → 0.127.0

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

@@ -1,12 +1,16 @@
 import type { GraphDriver } from '../connect-graph/connect-graph.js';
 import type { NodeLook } from '../connect-graph/looks.js';
-/** A graphology graph, as far as the driver calls it. */
+/**
+ * A graphology graph, as far as the driver calls it. Each member is
+ * graphology's own, as its documentation describes it.
+ */
 export interface SigmaGraph {
     addEdge(source: string, target: string, attributes?: Record<string, unknown>): unknown;
     addNode(node: string, attributes?: Record<string, unknown>): unknown;
     clear(): void;
     dropEdge(source: string, target: string): void;
     dropNode(node: string): void;
+    edges(node: string): string[];
     forEachNode(callback: (node: string, attributes: Record<string, unknown>) => void): void;
     getNodeAttributes(node: string): Record<string, unknown>;
     hasEdge(source: string, target: string): boolean;
@@ -15,7 +19,7 @@ export interface SigmaGraph {
     readonly order: number;
     setNodeAttribute(node: string, name: string, value: unknown): unknown;
 }
-/** Sigma's camera, as far as the driver calls it. */
+/** Sigma's camera, as far as the driver calls it. Each member is Sigma's own. */
 export interface SigmaCamera {
     animate(state: {
         ratio?: number;
@@ -36,15 +40,18 @@ export interface SigmaCamera {
         y?: number;
     }): unknown;
 }
-/** A Sigma renderer, as far as the driver calls it. */
-export interface SigmaRenderer {
+/**
+ * A Sigma renderer, as far as the driver calls it, over a graph of type `G`.
+ * Each member is Sigma's own, as its documentation describes it.
+ */
+export interface SigmaRenderer<G extends SigmaGraph = SigmaGraph> {
     getCamera(): SigmaCamera;
     getContainer(): HTMLElement;
     getDimensions(): {
         height: number;
         width: number;
     };
-    getGraph(): SigmaGraph;
+    getGraph(): G;
     framedGraphToViewport(point: {
         x: number;
         y: number;
@@ -61,16 +68,21 @@ export interface SigmaRenderer {
     off(type: 'clickNode' | 'enterNode' | 'leaveNode', listener: (payload: {
         node: string;
     }) => void): unknown;
-    off(type: 'afterRender' | 'beforeRender', listener: () => void): unknown;
+    off(type: 'afterRender' | 'beforeRender' | 'clickStage', listener: () => void): unknown;
     on(type: 'clickNode' | 'enterNode' | 'leaveNode', listener: (payload: {
         node: string;
     }) => void): unknown;
-    on(type: 'afterRender' | 'beforeRender', listener: () => void): unknown;
-    getSetting(name: 'nodeProgramClasses'): Record<string, unknown>;
-    refresh(): unknown;
+    on(type: 'afterRender' | 'beforeRender' | 'clickStage', listener: () => void): unknown;
+    getSetting(name: SigmaSetting): unknown;
+    refresh(options?: {
+        partialGraph?: {
+            edges?: string[];
+            nodes?: string[];
+        };
+    }): unknown;
     resize(force?: boolean): unknown;
     scaleSize(size?: number): number;
-    setSetting(name: 'defaultDrawNodeHover' | 'edgeReducer' | 'labelColor' | 'labelFont' | 'defaultDrawNodeLabel' | 'labelGridCellSize' | 'labelRenderedSizeThreshold' | 'labelSize' | 'minEdgeThickness' | 'nodeProgramClasses' | 'nodeReducer', value: unknown): unknown;
+    setSetting(name: SigmaSetting, value: unknown): unknown;
     viewportToFramedGraph(point: {
         x: number;
         y: number;
@@ -79,14 +91,16 @@ export interface SigmaRenderer {
         y: number;
     };
 }
+/** The settings the driver sets, and puts back as they were when it stops. */
+type SigmaSetting = 'defaultDrawNodeHover' | 'defaultDrawNodeLabel' | 'edgeReducer' | 'enableCameraPanning' | 'enableCameraZooming' | 'labelColor' | 'labelFont' | 'labelGridCellSize' | 'labelRenderedSizeThreshold' | 'labelSize' | 'minEdgeThickness' | 'nodeProgramClasses' | 'nodeReducer';
 /** 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 {
+/** How the Sigma driver behaves where the page does not say, over a graph of type `G`. */
+export interface SigmaDriverOptions<G extends SigmaGraph = SigmaGraph> {
     /**
      * 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
@@ -103,18 +117,18 @@ export interface SigmaDriverOptions {
      *
      * Without one, notes stay where the connector started them.
      */
-    layout?: ((graph: SigmaGraph) => SigmaLayout) | undefined;
+    layout?: ((graph: G) => SigmaLayout) | undefined;
     /**
      * How heavily a note is drawn where it does not say: `solid`, filled, by
      * default; `outlined`, a ring; `subtle`, a tinted fill with a ring.
      */
     emphasis?: NodeLook['emphasis'];
     /**
-     * What a note is drawn as made of where it does not say: flat by default,
+     * What a note is drawn as made of where it does not say: `flat` by default,
      * `glass`, a shaded sphere with a highlight and a lit rim, or `frosted`, a
      * milky body with a soft fall of light.
      */
-    material?: NodeLook['material'];
+    material?: NodeLook['material'] | 'flat';
     /** A note's shape where it does not say: `circle` by default, `square`, `diamond` or `ring`. */
     shape?: NodeLook['shape'];
     /**
@@ -142,6 +156,8 @@ export interface SigmaDriverOptions {
  *
  * **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.
+ * has, and a spec holds those shapes to the real classes. The renderer is the
+ * page's: after `disconnect()`, `sigma.kill()` frees it.
  */
-export declare const sigmaDriver: (sigma: SigmaRenderer, options?: SigmaDriverOptions) => GraphDriver;
+export declare const sigmaDriver: <G extends SigmaGraph>(sigma: SigmaRenderer<G>, options?: SigmaDriverOptions<G>) => GraphDriver;
+export {};

package/dist/sigma/sigma-driver.js

@@ -1,5 +1,20 @@
 import { ease, gesturesHeld, groupsOver, signalsOver } from '../overlay/overlay.js';
 import { EMPHASES, HelixNodeProgram, MATERIALS, SHAPES } from './node-program.js';
+const SETTINGS = [
+    'defaultDrawNodeHover',
+    'defaultDrawNodeLabel',
+    'edgeReducer',
+    'enableCameraPanning',
+    'enableCameraZooming',
+    'labelColor',
+    'labelFont',
+    'labelGridCellSize',
+    'labelRenderedSizeThreshold',
+    'labelSize',
+    'minEdgeThickness',
+    'nodeProgramClasses',
+    'nodeReducer',
+];
 const STEP = 250;
 const ZOOM = 1.5;
 const SAMPLE = 250;
@@ -65,7 +80,8 @@ export const sigmaDriver = (sigma, options = {}) => {
     const graph = sigma.getGraph();
     const container = sigma.getContainer();
     const camera = sigma.getCamera();
-    const programs = sigma.getSetting('nodeProgramClasses');
+    const before = new Map(SETTINGS.map((name) => [name, sigma.getSetting(name)]));
+    const programs = before.get('nodeProgramClasses');
     sigma.setSetting('nodeProgramClasses', { ...programs, helix: HelixNodeProgram });
     const sized = typeof ResizeObserver === 'function'
         ? new ResizeObserver(() => {
@@ -75,13 +91,22 @@ export const sigmaDriver = (sigma, options = {}) => {
         : undefined;
     sized?.observe(container);
     let hovered;
+    const cursor = container.style.cursor;
+    const relight = (from, to) => {
+        const edges = [from, to].flatMap((id) => id !== undefined && graph.hasNode(id) ? graph.edges(id) : []);
+        sigma.refresh({ partialGraph: { edges } });
+    };
     const enter = ({ node }) => {
+        const was = hovered;
         hovered = node;
-        sigma.refresh();
+        container.style.cursor = 'pointer';
+        relight(was, node);
     };
     const leave = () => {
+        const was = hovered;
         hovered = undefined;
-        sigma.refresh();
+        container.style.cursor = cursor;
+        relight(was, undefined);
     };
     sigma.on('enterNode', enter);
     sigma.on('leaveNode', leave);
@@ -111,22 +136,31 @@ export const sigmaDriver = (sigma, options = {}) => {
         return { radius: sigma.scaleSize(data.size), x: at.x, y: at.y };
     };
     const signals = signalsOver(container, onScreen);
-    const groups = groupsOver(container, onScreen);
+    const groups = groupsOver(container, onScreen, () => taken);
     sigma.on('afterRender', groups.draw);
-    const grow = (sizes) => {
+    let gliding = 0;
+    const glide = (sizes, moves) => {
+        cancelAnimationFrame(gliding);
         const started = performance.now();
-        const step = (now) => {
-            const along = Math.min((now - started) / GROW, 1);
+        const step = () => {
+            const along = Math.min((performance.now() - started) / GROW, 1);
+            const eased = ease(along);
             for (const [id, size] of sizes) {
                 if (graph.hasNode(id)) {
-                    graph.setNodeAttribute(id, 'size', size * ease(along));
+                    graph.setNodeAttribute(id, 'size', size * eased);
                 }
             }
-            if (along < 1) {
-                requestAnimationFrame(step);
+            for (const [id, { from, to }] of moves) {
+                if (graph.hasNode(id)) {
+                    graph.mergeNodeAttributes(id, {
+                        x: from.x + (to.x - from.x) * eased,
+                        y: from.y + (to.y - from.y) * eased,
+                    });
+                }
             }
+            gliding = along < 1 ? requestAnimationFrame(step) : 0;
         };
-        requestAnimationFrame(step);
+        gliding = requestAnimationFrame(step);
     };
     return {
         center: (id, animate) => {
@@ -176,7 +210,7 @@ export const sigmaDriver = (sigma, options = {}) => {
                 return;
             }
             const state = {
-                ratio: Math.min(Math.max(Math.max(high.x - low.x, high.y - low.y) * 2.4, 0.12), 1),
+                ratio: Math.min(Math.max(Math.max(high.x - low.x, high.y - low.y) * 2.4, 0.25), 1),
                 x: (low.x + high.x) / 2,
                 y: (low.y + high.y) / 2,
             };
@@ -189,6 +223,8 @@ export const sigmaDriver = (sigma, options = {}) => {
         },
         gestures: (next) => {
             held.set(next);
+            sigma.setSetting('enableCameraZooming', next !== 'off');
+            sigma.setSetting('enableCameraPanning', next !== 'off');
         },
         groups: (next) => {
             if (options.groupLabels !== false) {
@@ -245,9 +281,12 @@ export const sigmaDriver = (sigma, options = {}) => {
         },
         onPress: (press) => {
             const listener = ({ node }) => press(node);
+            const away = () => press(undefined);
             sigma.on('clickNode', listener);
+            sigma.on('clickStage', away);
             return () => {
                 sigma.off('clickNode', listener);
+                sigma.off('clickStage', away);
             };
         },
         panBy: (x, y, animate) => {
@@ -270,7 +309,11 @@ export const sigmaDriver = (sigma, options = {}) => {
             signals.stop();
             sigma.off('enterNode', enter);
             sigma.off('leaveNode', leave);
-            sigma.setSetting('nodeProgramClasses', programs);
+            cancelAnimationFrame(gliding);
+            container.style.cursor = cursor;
+            for (const [name, value] of before) {
+                sigma.setSetting(name, value);
+            }
             sized?.disconnect();
             held.stop();
         },
@@ -298,12 +341,18 @@ export const sigmaDriver = (sigma, options = {}) => {
                     growing.set(node.id, size);
                 }
             }
+            const moves = new Map();
             for (const node of changes.changeNodes) {
+                const was = graph.getNodeAttributes(node.id);
+                const from = { x: Number(was.x), y: Number(was.y) };
+                const moved = from.x !== node.x || from.y !== node.y;
+                if (animate && moved && Number.isFinite(from.x) && Number.isFinite(from.y)) {
+                    moves.set(node.id, { from, to: { x: node.x, y: node.y } });
+                }
                 graph.mergeNodeAttributes(node.id, {
                     label: node.label,
                     size: pixels(node.size),
-                    x: node.x,
-                    y: node.y,
+                    ...(moves.has(node.id) ? {} : { x: node.x, y: node.y }),
                 });
             }
             for (const link of changes.addLinks) {
@@ -318,8 +367,8 @@ export const sigmaDriver = (sigma, options = {}) => {
                     });
                 }
             }
-            if (growing.size > 0) {
-                grow(growing);
+            if (growing.size > 0 || moves.size > 0) {
+                glide(growing, moves);
             }
         },
         zoomBy: (direction, animate) => {
@@ -394,6 +443,9 @@ export const sigmaDriver = (sigma, options = {}) => {
                         clearInterval(timer);
                         layout.stop();
                         layout.kill();
+                        graph.forEachNode((node) => {
+                            graph.setNodeAttribute(node, 'fixed', false);
+                        });
                     };
                 },
             }

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

@@ -1,7 +1,13 @@
 import type { GraphDriver } from '../connect-graph/connect-graph.js';
-import type { NodeLook } from '../connect-graph/looks.js';
+import { type NodeLook } from '../connect-graph/looks.js';
 /** How the three.js driver behaves where the page does not say. */
 export interface ThreeDriverOptions {
+    /**
+     * How many pixels the drawing has for each of the page's. By default half
+     * as many again as the screen has, at least two and at most three, which
+     * smooths every edge. Fewer is faster on a slow GPU.
+     */
+    density?: number | undefined;
     /**
      * Whether the graph turns slowly while nobody is handling it. On by
      * default, and never for a reader who asks for less motion.
@@ -11,7 +17,7 @@ export interface ThreeDriverOptions {
     groupLabels?: boolean | undefined;
     /** The longest a layout runs, in milliseconds, settled or not. 10 seconds by default. */
     layoutLimit?: number | undefined;
-    /** A note's shape where it does not say: `circle` by default, `square` or `diamond`. */
+    /** A note's shape where it does not say: `circle` by default, `square` or `diamond`. A `ring` is drawn as a circle. */
     shape?: NodeLook['shape'];
 }
 /**
@@ -27,6 +33,9 @@ export interface ThreeDriverOptions {
  * place; with a solid `stencil`, the notes are drawn in its shape and none
  * runs. Dragging turns the graph, the wheel and a pinch bring it nearer, and
  * it turns slowly by itself while nobody is handling it, unless the reader
- * asks for less motion.
+ * asks for less motion. It draws only while something moves, and not at all
+ * while the box is out of view or off the page.
+ *
+ * The renderer is the driver's own, and `disconnect()` frees it.
  */
 export declare const threeDriver: (container: HTMLElement, options?: ThreeDriverOptions) => GraphDriver;