@fusion.dev/helix-graph 0.125.0 → 0.127.0

package/dist/{three → shapes}/surface.d.ts

@@ -1,4 +1,4 @@
-import type { ShapeField } from '../connect-graph/shape-field.js';
+import type { ShapeField } from './shape-field.js';
 /**
  * The surface of a solid field where its distance is `at`, as triangles:
  * corners three numbers each in the field's box, and triangles three corners

package/dist/shapes/triangles.d.ts

@@ -1,7 +1,16 @@
-import { type ShapeField } from '../connect-graph/shape-field.js';
+import { type ShapeField } from './shape-field.js';
 /** How a solid is read from triangles. */
 export interface TriangleOptions {
-    /** How many cells the field has along the solid's longest side. 96 by default. */
+    /**
+     * The named parts the triangles make: each part's name, and which part
+     * each triangle is in, by its place in `names`. Gives the field
+     * `regionOf`, the part a point is in: the part of the triangle nearest it.
+     */
+    regions?: {
+        names: readonly string[];
+        ofTriangle: ArrayLike<number>;
+    } | undefined;
+    /** How many cells the field has along the solid's longest side. 144 by default. */
     resolution?: number | undefined;
 }
 /**
@@ -17,4 +26,4 @@ export interface TriangleOptions {
  * minutes. A surface with gaps is read as closed where it can be, and a gap
  * shows as a column filled or emptied through.
  */
-export declare const shapeFromTriangles: (positions: ArrayLike<number>, index?: ArrayLike<number> | null | undefined, { resolution }?: TriangleOptions) => ShapeField;
+export declare const shapeFromTriangles: (positions: ArrayLike<number>, index?: ArrayLike<number> | null | undefined, { regions, resolution }?: TriangleOptions) => ShapeField;

package/dist/shapes/triangles.js

@@ -1,6 +1,73 @@
-import { fieldFromCells, SOLID } from '../connect-graph/shape-field.js';
+import { fieldFromCells, SOLID } from './shape-field.js';
 const NUDGE = 1e-6 * Math.PI;
-export const shapeFromTriangles = (positions, index, { resolution = SOLID } = {}) => {
+const NEAREST = 40;
+const nearestPart = (middles, parts, names, box) => {
+    const size = Math.max(box.width, box.height, box.depth) / NEAREST || 1;
+    const nx = Math.ceil(box.width / size) + 1;
+    const ny = Math.ceil(box.height / size) + 1;
+    const nz = Math.ceil(box.depth / size) + 1;
+    const clamp = (value, most) => Math.min(most - 1, Math.max(0, value));
+    const cellOf = (x, y, z) => clamp(Math.floor(x / size), nx) +
+        nx * (clamp(Math.floor(y / size), ny) + ny * clamp(Math.floor(z / size), nz));
+    const count = middles.length / 3;
+    const start = new Int32Array(nx * ny * nz + 1);
+    const cellAt = new Int32Array(count);
+    for (let at = 0; at < count; at++) {
+        const cell = cellOf(middles[at * 3], middles[at * 3 + 1], middles[at * 3 + 2]);
+        cellAt[at] = cell;
+        start[cell + 1] = start[cell + 1] + 1;
+    }
+    for (let cell = 0; cell < nx * ny * nz; cell++) {
+        start[cell + 1] = start[cell + 1] + start[cell];
+    }
+    const filled = start.slice(0, -1);
+    const order = new Int32Array(count);
+    for (let at = 0; at < count; at++) {
+        const cell = cellAt[at];
+        order[filled[cell]] = at;
+        filled[cell] = filled[cell] + 1;
+    }
+    const furthest = Math.max(nx, ny, nz);
+    return (x, y, z = box.depth / 2) => {
+        const cx = clamp(Math.floor(x / size), nx);
+        const cy = clamp(Math.floor(y / size), ny);
+        const cz = clamp(Math.floor(z / size), nz);
+        let best = -1;
+        let nearest = Number.POSITIVE_INFINITY;
+        const search = (ix, iy, iz) => {
+            if (ix < 0 || iy < 0 || iz < 0 || ix >= nx || iy >= ny || iz >= nz) {
+                return;
+            }
+            const cell = ix + nx * (iy + ny * iz);
+            for (let at = start[cell]; at < start[cell + 1]; at++) {
+                const one = order[at];
+                const far = (middles[one * 3] - x) ** 2 +
+                    (middles[one * 3 + 1] - y) ** 2 +
+                    (middles[one * 3 + 2] - z) ** 2;
+                if (far < nearest) {
+                    nearest = far;
+                    best = one;
+                }
+            }
+        };
+        for (let ring = 0; ring <= furthest; ring++) {
+            for (let dz = -ring; dz <= ring; dz++) {
+                const face = Math.abs(dz) === ring;
+                for (let dy = -ring; dy <= ring; dy++) {
+                    const edge = face || Math.abs(dy) === ring;
+                    for (let dx = -ring; dx <= ring; dx += edge || ring === 0 ? 1 : 2 * ring) {
+                        search(cx + dx, cy + dy, cz + dz);
+                    }
+                }
+            }
+            if (best >= 0 && Math.sqrt(nearest) <= ring * size) {
+                break;
+            }
+        }
+        return best < 0 ? undefined : names[parts[best]];
+    };
+};
+export const shapeFromTriangles = (positions, index, { regions, resolution = SOLID } = {}) => {
     const corners = Math.floor(positions.length / 3);
     const low = [Number.POSITIVE_INFINITY, Number.POSITIVE_INFINITY, Number.POSITIVE_INFINITY];
     const high = [Number.NEGATIVE_INFINITY, Number.NEGATIVE_INFINITY, Number.NEGATIVE_INFINITY];
@@ -84,9 +151,23 @@ export const shapeFromTriangles = (positions, index, { resolution = SOLID } = {}
         height: ny * cell,
         width: nx * cell,
     });
+    let regionOf;
+    if (regions && regions.names.length > 0) {
+        const middles = new Float32Array(triangles * 3);
+        for (let triangle = 0; triangle < triangles; triangle++) {
+            for (let which = 0; which < 3; which++) {
+                const at = corner(triangle, which);
+                middles[triangle * 3] = middles[triangle * 3] + (at[0] * cell) / 3;
+                middles[triangle * 3 + 1] = middles[triangle * 3 + 1] + (at[1] * cell) / 3;
+                middles[triangle * 3 + 2] = middles[triangle * 3 + 2] + (at[2] * cell) / 3;
+            }
+        }
+        regionOf = nearestPart(middles, regions.ofTriangle, regions.names, field);
+    }
     return {
         ...field,
         distance: field.distance,
         mesh: { corners: meshCorners, triangles: meshTriangles },
+        ...(regionOf ? { regionOf } : {}),
     };
 };

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;