@fusion.dev/helix-graph 0.120.0 → 0.122.0

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

@@ -1,4 +1,5 @@
 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. */
 export interface SigmaGraph {
     addEdge(source: string, target: string, attributes?: Record<string, unknown>): unknown;
@@ -57,16 +58,19 @@ export interface SigmaRenderer {
         x: number;
         y: number;
     } | undefined;
-    off(type: 'clickNode', listener: (payload: {
+    off(type: 'clickNode' | 'enterNode' | 'leaveNode', listener: (payload: {
         node: string;
     }) => void): unknown;
-    on(type: 'clickNode', listener: (payload: {
+    off(type: 'afterRender' | 'beforeRender', 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;
     resize(force?: boolean): unknown;
     scaleSize(size?: number): number;
-    setSetting(name: 'defaultDrawNodeHover' | 'edgeReducer' | 'labelColor' | 'labelFont' | 'labelRenderedSizeThreshold' | 'nodeReducer', value: unknown): unknown;
+    setSetting(name: 'defaultDrawNodeHover' | 'edgeReducer' | 'labelColor' | 'labelFont' | 'defaultDrawNodeLabel' | 'labelGridCellSize' | 'labelRenderedSizeThreshold' | 'labelSize' | 'minEdgeThickness' | 'nodeProgramClasses' | 'nodeReducer', value: unknown): unknown;
     viewportToFramedGraph(point: {
         x: number;
         y: number;
@@ -100,6 +104,30 @@ export interface SigmaDriverOptions {
      * Without one, notes stay where the connector started them.
      */
     layout?: ((graph: SigmaGraph) => 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,
+     * `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'];
+    /** A note's shape where it does not say: `circle` by default, `square`, `diamond` or `ring`. */
+    shape?: NodeLook['shape'];
+    /**
+     * Whether each group's name is drawn over its notes. On by default, which
+     * is how a reader finds their way while notes are named only on hover.
+     */
+    groupLabels?: boolean | undefined;
+    /**
+     * Which notes are named. `hover`, by default: the note under the pointer,
+     * the selected note and its neighbors. `hubs`: the busiest notes as well, at
+     * rest. `all`: every note, where its name does not cover another.
+     */
+    labels?: 'all' | 'hover' | 'hubs' | undefined;
     /** The longest a layout runs, in milliseconds, settled or not. 10 seconds by default, about where 10,000 notes settle. */
     layoutLimit?: number | undefined;
 }

package/dist/sigma/sigma-driver.js

@@ -1,10 +1,12 @@
+import { ease, gesturesHeld, groupsOver, signalsOver } from '../overlay/overlay.js';
+import { EMPHASES, HelixNodeProgram, MATERIALS, SHAPES } from './node-program.js';
 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 pixels = (size) => 1.6 + 1.35 * Math.max(size, 0);
 const hoverOf = (looks) => (context, data, settings) => {
     if (!data.label) {
         return;
@@ -25,11 +27,33 @@ const hoverOf = (looks) => (context, data, settings) => {
     context.fillStyle = looks.ink;
     context.fillText(data.label, x, data.y + size / 3);
 };
-const TRAVEL = 700;
-const PULSE = 450;
 const GROW = 300;
-const FLYING = 400;
-const ease = (at) => (at < 0.5 ? 2 * at * at : 1 - (-2 * at + 2) ** 2 / 2);
+const labelOf = (looks, claim) => (context, data, settings) => {
+    if (!data.label) {
+        return;
+    }
+    const strong = data.strong === true;
+    const size = strong ? settings.labelSize : settings.labelSize - 1;
+    context.font = `${strong ? 600 : 500} ${size}px ${settings.labelFont}`;
+    const x = data.x + data.size + 4;
+    const y = data.y + size / 3;
+    const box = {
+        bottom: y + 4,
+        left: x - 2,
+        right: x + context.measureText(data.label).width + 2,
+        top: y - size,
+    };
+    if (!claim(box, data.forceLabel === true)) {
+        return;
+    }
+    context.lineJoin = 'round';
+    context.lineWidth = 3;
+    context.strokeStyle = looks.ground;
+    context.strokeText(data.label, x, y);
+    context.fillStyle = strong ? looks.ink : looks.quiet;
+    context.fillText(data.label, x, y);
+};
+const HUB = 6.5;
 const positionsOf = (graph) => {
     const positions = new Map();
     graph.forEachNode((node, attributes) => {
@@ -41,35 +65,8 @@ 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 });
-    }
+    const programs = sigma.getSetting('nodeProgramClasses');
+    sigma.setSetting('nodeProgramClasses', { ...programs, helix: HelixNodeProgram });
     const sized = typeof ResizeObserver === 'function'
         ? new ResizeObserver(() => {
             sigma.resize(true);
@@ -77,10 +74,34 @@ export const sigmaDriver = (sigma, options = {}) => {
         })
         : undefined;
     sized?.observe(container);
-    let overlay;
-    let flights = [];
-    let flying = 0;
-    let ink = 'rgb(128, 128, 128)';
+    let hovered;
+    const enter = ({ node }) => {
+        hovered = node;
+        sigma.refresh();
+    };
+    const leave = () => {
+        hovered = undefined;
+        sigma.refresh();
+    };
+    sigma.on('enterNode', enter);
+    sigma.on('leaveNode', leave);
+    const naming = options.labels ?? 'hover';
+    let taken = [];
+    const claim = (box, must) => {
+        const free = taken.every((other) => box.right < other.left ||
+            box.left > other.right ||
+            box.bottom < other.top ||
+            box.top > other.bottom);
+        if (free || must) {
+            taken.push(box);
+        }
+        return free || must;
+    };
+    const clear = () => {
+        taken = [];
+    };
+    sigma.on('beforeRender', clear);
+    const held = gesturesHeld(container);
     const onScreen = (id) => {
         const data = sigma.getNodeDisplayData(id);
         if (!data || data.hidden) {
@@ -89,76 +110,9 @@ export const sigmaDriver = (sigma, options = {}) => {
         const at = sigma.framedGraphToViewport(data);
         return { radius: sigma.scaleSize(data.size), x: at.x, y: at.y };
     };
-    const fly = (now) => {
-        const context = overlay?.getContext('2d');
-        if (!overlay || !context) {
-            flights = [];
-            return;
-        }
-        const ratio = window.devicePixelRatio || 1;
-        const width = Math.round(container.clientWidth * ratio);
-        const height = Math.round(container.clientHeight * ratio);
-        if (overlay.width !== width || overlay.height !== height) {
-            overlay.width = width;
-            overlay.height = height;
-        }
-        context.setTransform(ratio, 0, 0, ratio, 0, 0);
-        context.clearRect(0, 0, width, height);
-        flights = flights.filter((flight) => {
-            const from = onScreen(flight.from);
-            const to = onScreen(flight.to);
-            const gone = (now - flight.started) / TRAVEL;
-            if (!from || !to || gone >= 1 + PULSE / TRAVEL) {
-                return false;
-            }
-            context.save();
-            context.strokeStyle = flight.color;
-            context.fillStyle = flight.color;
-            if (gone < 1) {
-                if (flight.animate) {
-                    const along = ease(gone);
-                    const x = from.x + (to.x - from.x) * along;
-                    const y = from.y + (to.y - from.y) * along;
-                    context.globalAlpha = 0.6;
-                    context.lineWidth = 2;
-                    context.beginPath();
-                    context.moveTo(from.x, from.y);
-                    context.lineTo(x, y);
-                    context.stroke();
-                    context.globalAlpha = 1;
-                    context.shadowBlur = 14;
-                    context.shadowColor = flight.color;
-                    context.beginPath();
-                    context.arc(x, y, 5, 0, Math.PI * 2);
-                    context.fill();
-                    context.shadowBlur = 0;
-                    context.fillStyle = 'rgba(255, 255, 255, 0.85)';
-                    context.beginPath();
-                    context.arc(x, y, 2, 0, Math.PI * 2);
-                    context.fill();
-                }
-                else {
-                    context.globalAlpha = 1 - gone;
-                    context.lineWidth = 2;
-                    context.beginPath();
-                    context.moveTo(from.x, from.y);
-                    context.lineTo(to.x, to.y);
-                    context.stroke();
-                }
-            }
-            else if (flight.animate) {
-                const opened = (gone - 1) / (PULSE / TRAVEL);
-                context.globalAlpha = 1 - opened;
-                context.lineWidth = 2.5;
-                context.beginPath();
-                context.arc(to.x, to.y, to.radius + 2 + opened * 16, 0, Math.PI * 2);
-                context.stroke();
-            }
-            context.restore();
-            return true;
-        });
-        flying = flights.length > 0 ? requestAnimationFrame(fly) : 0;
-    };
+    const signals = signalsOver(container, onScreen);
+    const groups = groupsOver(container, onScreen);
+    sigma.on('afterRender', groups.draw);
     const grow = (sizes) => {
         const started = performance.now();
         const step = (now) => {
@@ -208,38 +162,83 @@ export const sigmaDriver = (sigma, options = {}) => {
                 }
             }
         },
+        fit: (ids, animate) => {
+            let low = { x: Number.POSITIVE_INFINITY, y: Number.POSITIVE_INFINITY };
+            let high = { x: Number.NEGATIVE_INFINITY, y: Number.NEGATIVE_INFINITY };
+            for (const id of ids) {
+                const at = sigma.getNodeDisplayData(id);
+                if (at) {
+                    low = { x: Math.min(low.x, at.x), y: Math.min(low.y, at.y) };
+                    high = { x: Math.max(high.x, at.x), y: Math.max(high.y, at.y) };
+                }
+            }
+            if (!Number.isFinite(low.x)) {
+                return;
+            }
+            const state = {
+                ratio: Math.min(Math.max(Math.max(high.x - low.x, high.y - low.y) * 2.4, 0.12), 1),
+                x: (low.x + high.x) / 2,
+                y: (low.y + high.y) / 2,
+            };
+            if (animate) {
+                camera.animate(state, { duration: STEP * 2 });
+            }
+            else {
+                camera.setState(state);
+            }
+        },
         gestures: (next) => {
-            mode = next;
-            container.style.touchAction =
-                next === 'free' ? touchAction : next === 'cooperative' ? 'pan-x pan-y' : 'auto';
+            held.set(next);
+        },
+        groups: (next) => {
+            if (options.groupLabels !== false) {
+                groups.set(next);
+            }
         },
         look: (looks) => {
-            ink = looks.ink;
+            signals.look(looks);
+            groups.look(looks);
             sigma.setSetting('labelColor', { color: looks.ink });
+            sigma.setSetting('labelSize', 13);
+            sigma.setSetting('minEdgeThickness', 0.8);
             sigma.setSetting('labelFont', looks.font);
             sigma.setSetting('labelRenderedSizeThreshold', 0);
+            sigma.setSetting('labelGridCellSize', 130);
+            sigma.setSetting('defaultDrawNodeLabel', labelOf(looks, claim));
             sigma.setSetting('defaultDrawNodeHover', hoverOf(looks));
             sigma.setSetting('nodeReducer', (node, data) => {
                 const look = looks.node(node);
                 const grown = look.selected ? 1.5 : look.raised ? 1.25 : 1;
+                const named = look.label === 'always' ||
+                    (look.label === 'room' &&
+                        (look.raised ||
+                            naming === 'all' ||
+                            (naming === 'hubs' && typeof data.size === 'number' && data.size >= HUB)));
                 return {
                     ...data,
                     color: look.color,
+                    emphasisCode: EMPHASES[look.emphasis ?? options.emphasis ?? 'solid'],
                     forceLabel: look.label === 'always',
+                    glow: look.glow,
                     hidden: look.hidden,
-                    label: look.label === 'never' ? null : data.label,
+                    label: named ? data.label : null,
+                    materialCode: MATERIALS[look.material ?? options.material ?? 'flat'],
+                    shapeCode: SHAPES[look.shape ?? options.shape ?? 'circle'],
                     size: typeof data.size === 'number' ? data.size * grown : data.size,
+                    strong: look.selected || look.raised,
+                    type: 'helix',
                     zIndex: look.selected ? 2 : look.raised ? 1 : 0,
                 };
             });
             sigma.setSetting('edgeReducer', (_edge, data) => {
                 const look = looks.link(String(data.from), String(data.to));
+                const lit = hovered !== undefined && (data.from === hovered || data.to === hovered);
                 return {
                     ...data,
-                    color: look.color,
+                    color: lit ? looks.node(hovered).color : look.color,
                     hidden: look.hidden,
-                    size: look.raised ? 1.5 : 1,
-                    zIndex: look.raised ? 1 : 0,
+                    size: look.raised || lit ? 1.6 : 0.8,
+                    zIndex: look.raised || lit ? 1 : 0,
                 };
             });
             sigma.refresh();
@@ -261,33 +260,19 @@ export const sigmaDriver = (sigma, options = {}) => {
                 camera.setState(to);
             }
         },
-        signal: (from, to, color, animate) => {
-            if (!overlay) {
-                overlay = document.createElement('canvas');
-                overlay.setAttribute('aria-hidden', 'true');
-                overlay.style.cssText =
-                    'position:absolute;inset:0;width:100%;height:100%;pointer-events:none';
-                container.append(overlay);
-            }
-            flights.push({ animate, color: color ?? ink, from, started: performance.now(), to });
-            if (flights.length > FLYING) {
-                flights = flights.slice(-FLYING);
-            }
-            if (!flying) {
-                flying = requestAnimationFrame(fly);
-            }
+        signal: (from, to, colors, animate) => {
+            signals.signal(from, to, colors, animate);
         },
         stop: () => {
-            cancelAnimationFrame(flying);
-            flying = 0;
-            flights = [];
-            overlay?.remove();
-            overlay = undefined;
+            sigma.off('afterRender', groups.draw);
+            sigma.off('beforeRender', clear);
+            groups.stop();
+            signals.stop();
+            sigma.off('enterNode', enter);
+            sigma.off('leaveNode', leave);
+            sigma.setSetting('nodeProgramClasses', programs);
             sized?.disconnect();
-            for (const type of held) {
-                container.removeEventListener(type, hold, { capture: true });
-            }
-            container.style.touchAction = touchAction;
+            held.stop();
         },
         update: (changes, animate) => {
             for (const id of changes.removeNodes) {

package/dist/three/index.d.ts

@@ -0,0 +1 @@
+export { type ThreeDriverOptions, threeDriver } from './three-driver.js';

package/dist/three/index.js

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

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

@@ -0,0 +1,32 @@
+import type { GraphDriver } from '../connect-graph/connect-graph.js';
+import type { NodeLook } from '../connect-graph/looks.js';
+/** How the three.js driver behaves where the page does not say. */
+export interface ThreeDriverOptions {
+    /**
+     * Whether the graph turns slowly while nobody is handling it. On by
+     * default, and never for a reader who asks for less motion.
+     */
+    autoRotate?: boolean | undefined;
+    /** Whether each group's name is drawn over its notes. On by default. */
+    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`. */
+    shape?: NodeLook['shape'];
+}
+/**
+ * Drives three.js for a Graph frame: the graph drawn in three dimensions, to
+ * be turned and looked into. Pass the box inside the frame the drawing goes
+ * in, and `connectGraph` fills it:
+ *
+ * ```js
+ * connectGraph(frame, threeDriver(box))
+ * ```
+ *
+ * **A layout runs in three dimensions**, with d3-force-3d, where notes have no
+ * 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.
+ */
+export declare const threeDriver: (container: HTMLElement, options?: ThreeDriverOptions) => GraphDriver;