@fusion.dev/helix-graph 0.134.0 → 0.136.0

package/README.md

@@ -69,6 +69,8 @@ first.
   gestures the frame's `gestures` lets it take.
 - Draws only what changed when the page hands the frame new notes or links, and
   draws the frame's `signal()`s.
+- Fades out a snapshot drawn on the server by `graphSnapshot` once the renderer
+  has drawn the graph whole.
 
 ## Live graphs
 
@@ -357,6 +359,7 @@ connectGraph(frame, threeDriver(box), {
 | `@fusion.dev/helix-graph/three` | `threeDriver(box, options)`, and the type `ThreeDriverOptions` |
 | `@fusion.dev/helix-graph/shapes` | `shapeFromTriangles`, `shapeFromSvg`, `shapeFromImage`, `shapeFromPath`, `shapeFromInside`, `inflate`, `sphere`, `torus`, `cuboid`, `onSphere`, `surfaceOf`, and the types `ImageOptions`, `ShapeField` and `TriangleOptions` |
 | `@fusion.dev/helix-graph/model` | `shapeFromModel(source, options)`, which needs three.js |
+| `@fusion.dev/helix-graph/snapshot` | `graphSnapshot(nodes, links, options)`, an SVG of the graph to paint before the renderer loads, and the types `GraphSnapshotOptions`, `SnapshotLink` and `SnapshotNode` |
 
 **Sigma, cosmos.gl, three.js and d3-force-3d are optional peers, and graphology is the page's.** Each
 driver types its renderer by the calls it makes on it, so a page brings

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

@@ -4,6 +4,7 @@ import { diffGraph, isEmpty, linkKey, } from './diff.js';
 import { graphColorsFrom, looksOf, toneColor, } from './looks.js';
 import { reachOf } from './reach.js';
 import { seedPositions } from './seed.js';
+import { sizeOf } from './sizes.js';
 import { fieldOf, fitInStencil } from './stencil.js';
 const clustersOf = (nodes, hubOf) => {
     const groupOf = new Map(nodes.map((node) => [node.id, node.group ?? '']));
@@ -33,6 +34,35 @@ export const connectGraph = (frame, driver, options = {}) => {
     let pressed;
     let pending = 0;
     let connected = true;
+    const snapshots = [...frame.querySelectorAll(':scope > [data-helix-graph-snapshot]')];
+    const away = (snapshot) => {
+        snapshot.hidden = true;
+        snapshot.style.display = 'none';
+    };
+    const ready = () => {
+        graph.drawn?.(true);
+        if (snapshots.length === 0) {
+            return;
+        }
+        const style = getComputedStyle(frame);
+        const time = /^\s*(\d*\.?\d+)(ms|s)\s*$/i.exec(style.getPropertyValue('--helix-duration-normal'));
+        const duration = time ? Number(time[1]) * (time[2]?.toLowerCase() === 's' ? 1000 : 1) : 200;
+        const easing = style.getPropertyValue('--helix-easing-standard').trim() || 'ease';
+        for (const snapshot of snapshots.splice(0)) {
+            if (still() || duration <= 0 || typeof snapshot.animate !== 'function') {
+                away(snapshot);
+                continue;
+            }
+            let fade;
+            try {
+                fade = snapshot.animate([{ opacity: 1 }, { opacity: 0 }], { duration, easing });
+            }
+            catch {
+                fade = snapshot.animate([{ opacity: 1 }, { opacity: 0 }], { duration });
+            }
+            fade.finished.then(() => away(snapshot), () => away(snapshot));
+        }
+    };
     const selectedNote = () => {
         const active = graph.active;
         return active && (graph.nodes ?? []).some((node) => node.id === active) ? active : undefined;
@@ -145,9 +175,7 @@ export const connectGraph = (frame, driver, options = {}) => {
             nextNodes.set(node.id, {
                 id: node.id,
                 label: node.label || node.id,
-                size: Number.isFinite(node.size)
-                    ? node.size
-                    : 1 + Math.min(Math.sqrt(degree.get(node.id) ?? 0), 6),
+                size: sizeOf(node.size, degree.get(node.id) ?? 0),
                 x: at.x,
                 y: at.y,
                 ...(at.z === undefined ? {} : { z: at.z }),
@@ -195,7 +223,7 @@ export const connectGraph = (frame, driver, options = {}) => {
                 graph.laidOut?.(Object.fromEntries([...settled].map(([id, at]) => [id, { ...at }])));
                 if (owed) {
                     owed = false;
-                    graph.drawn?.(true);
+                    ready();
                 }
             });
             return;
@@ -208,7 +236,7 @@ export const connectGraph = (frame, driver, options = {}) => {
             pending = requestAnimationFrame(() => {
                 if (connected && owed) {
                     owed = false;
-                    graph.drawn?.(true);
+                    ready();
                 }
             });
         }

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

@@ -0,0 +1,14 @@
+/**
+ * How large a note is drawn, in one place, so the drawing and a snapshot
+ * drawn on the server agree.
+ */
+/**
+ * **A note without a size is as large as it is connected**, so a hub reads as
+ * one at a glance and the graph's shape shows before a word of it is read.
+ * The square root, so a note with a hundred links is not ten times the size
+ * of one with ten, and no larger than a note with thirty-six, so a hub with
+ * thousands does not cover its own region.
+ */
+export declare const sizeOf: (size: number | undefined, links: number) => number;
+/** A note's drawn radius in pixels, from its relative size: a leaf about four, a busy hub about nine. */
+export declare const pixelsOf: (size: number) => number;

package/dist/connect-graph/sizes.js

@@ -0,0 +1,2 @@
+export const sizeOf = (size, links) => Number.isFinite(size) ? size : 1 + Math.min(Math.sqrt(links), 6);
+export const pixelsOf = (size) => 1.6 + 1.35 * Math.max(size, 0);

package/dist/sigma/sigma-driver.js

@@ -1,3 +1,4 @@
+import { pixelsOf } from '../connect-graph/sizes.js';
 import { chromeOver, clearOf, ease, gesturesHeld, groupsOver, nameStart, signalsOver, } from '../overlay/overlay.js';
 import { EMPHASES, HelixNodeProgram, MATERIALS, SHAPES } from './node-program.js';
 const SETTINGS = [
@@ -21,7 +22,6 @@ const SAMPLE = 250;
 const STILL = 0.004;
 const HELD = 2;
 const IDLE = 2000;
-const pixels = (size) => 1.6 + 1.35 * Math.max(size, 0);
 const hoverOf = (looks) => (context, data, settings) => {
     if (!data.label) {
         return;
@@ -180,7 +180,7 @@ export const sigmaDriver = (sigma, options = {}) => {
             for (const node of nodes) {
                 graph.addNode(node.id, {
                     label: node.label,
-                    size: pixels(node.size),
+                    size: pixelsOf(node.size),
                     x: node.x,
                     y: node.y,
                 });
@@ -330,7 +330,7 @@ export const sigmaDriver = (sigma, options = {}) => {
             }
             const growing = new Map();
             for (const node of changes.addNodes) {
-                const size = pixels(node.size);
+                const size = pixelsOf(node.size);
                 graph.addNode(node.id, {
                     label: node.label,
                     size: animate ? 0 : size,
@@ -351,7 +351,7 @@ export const sigmaDriver = (sigma, options = {}) => {
                 }
                 graph.mergeNodeAttributes(node.id, {
                     label: node.label,
-                    size: pixels(node.size),
+                    size: pixelsOf(node.size),
                     ...(moves.has(node.id) ? {} : { x: node.x, y: node.y }),
                 });
             }

package/dist/snapshot/index.d.ts

@@ -0,0 +1 @@
+export { type GraphSnapshotOptions, graphSnapshot, type SnapshotLink, type SnapshotNode, } from './snapshot.js';

package/dist/snapshot/index.js

@@ -0,0 +1 @@
+export { graphSnapshot, } from './snapshot.js';

package/dist/snapshot/snapshot.d.ts

@@ -0,0 +1,60 @@
+import type { NodeLook, NoteFacts } from '../connect-graph/looks.js';
+import { type GraphReach } from '../connect-graph/reach.js';
+/** A note, as a snapshot draws it: the frame's own, with its place given. */
+export interface SnapshotNode extends NoteFacts {
+    id: string;
+    label?: string | undefined;
+    size?: number | undefined;
+    x?: number | undefined;
+    y?: number | undefined;
+}
+/** A link, as a snapshot draws it. */
+export interface SnapshotLink {
+    source: string;
+    target: string;
+}
+/** What a snapshot draws, and the box it is drawn for. */
+export interface GraphSnapshotOptions {
+    /** The selected note, lit as the frame lights it. None by default. */
+    active?: string | undefined;
+    /**
+     * The part of the graph the drawing fits, as Sigma's `setCustomBBox` takes
+     * it. The box around the notes by default. Give both the same box.
+     */
+    bounds?: {
+        x: readonly [number, number];
+        y: readonly [number, number];
+    } | null | undefined;
+    /** How heavily a note is drawn where it does not say, as the Sigma driver's `emphasis`. */
+    emphasis?: NodeLook['emphasis'];
+    /** Whether each group's name is drawn over its notes, as the Sigma driver's `groupLabels`. On by default. */
+    groupLabels?: boolean | undefined;
+    /** The box's height, in pixels. 480 by default. */
+    height?: number | undefined;
+    /** Which notes are named, as the Sigma driver's `labels`. `hover` by default. */
+    labels?: 'all' | 'hover' | 'hubs' | undefined;
+    /** The room kept at each edge, in pixels, as Sigma's `stagePadding`. 30 by default. */
+    padding?: number | undefined;
+    /** How far `active` reaches, as `connectGraph`'s `reach`. `links` by default. */
+    reach?: GraphReach | undefined;
+    /** A note's shape where it does not say, as the Sigma driver's `shape`. */
+    shape?: NodeLook['shape'];
+    /** The box's width, in pixels. 1200 by default. */
+    width?: number | undefined;
+}
+/**
+ * **The graph drawn on the server, as an SVG in the theme's colors**, for a
+ * page to paint before the renderer has loaded. Put it in the frame after
+ * the element the renderer draws in, and `connectGraph` fades it out once
+ * the renderer has drawn the graph whole.
+ *
+ * **Where Sigma.js draws it**: fitted to the box as Sigma fits a graph, each
+ * note its size and its group's or tone's color, each link tinted by the
+ * note it leaves, and the names placed after their notes and left out where
+ * one would cover another. The colors are the theme's tokens, so it is
+ * light or dark with the page.
+ *
+ * **Whole or absent.** An empty string where any note has no `x` and `y`,
+ * since only a layout run in the browser could place it.
+ */
+export declare const graphSnapshot: (nodes: readonly SnapshotNode[], links: readonly SnapshotLink[], options?: GraphSnapshotOptions) => string;

package/dist/snapshot/snapshot.js

@@ -0,0 +1,204 @@
+import { reachOf } from '../connect-graph/reach.js';
+import { pixelsOf, sizeOf } from '../connect-graph/sizes.js';
+import { clearOf } from '../overlay/overlay.js';
+const SERIES = 24;
+const FADED = 75;
+const HUB = 6.5;
+const LABEL = 13;
+const widthOf = (text, size) => text.length * size * 0.56;
+const escaped = (text) => text.replace(/[&<>"']/g, (character) => ({ "'": '&#39;', '"': '&quot;', '&': '&amp;', '<': '&lt;', '>': '&gt;' })[character]);
+const short = (value) => String(Math.round(value * 10) / 10);
+const token = (name) => `var(--helix-color-${name})`;
+const mix = (from, to, amount) => amount <= 0 ? from : `color-mix(in srgb, ${to} ${short(amount)}%, ${from})`;
+const toneOf = (tone) => tone === 'primary'
+    ? token('primary')
+    : tone === 'neutral'
+        ? token('foreground-muted')
+        : token(tone);
+const correctionOf = (width, height, across, down) => {
+    const box = height / width;
+    const graph = down / across;
+    if ((box < 1 && graph > 1) || (box > 1 && graph < 1)) {
+        return 1;
+    }
+    const ratio = Math.min(Math.max(graph, 1 / graph), Math.max(1 / box, box));
+    return Number.isFinite(ratio) ? ratio : 1;
+};
+const shapeOf = (shape, x, y, radius, paint) => {
+    if (shape === 'square') {
+        const half = radius * 0.88;
+        return `<rect height="${short(half * 2)}" rx="${short(radius * 0.18)}" width="${short(half * 2)}" x="${short(x - half)}" y="${short(y - half)}" ${paint}/>`;
+    }
+    if (shape === 'diamond') {
+        const reach = radius * 1.216;
+        return `<path d="M${short(x)} ${short(y - reach)}L${short(x + reach)} ${short(y)}L${short(x)} ${short(y + reach)}L${short(x - reach)} ${short(y)}Z" ${paint}/>`;
+    }
+    return `<circle cx="${short(x)}" cy="${short(y)}" r="${short(radius)}" ${paint}/>`;
+};
+export const graphSnapshot = (nodes, links, options = {}) => {
+    const width = options.width ?? 1200;
+    const height = options.height ?? 480;
+    const padding = options.padding ?? 30;
+    if (nodes.length === 0 ||
+        nodes.some((node) => !(Number.isFinite(node.x) && Number.isFinite(node.y)))) {
+        return '';
+    }
+    const notes = new Map(nodes.map((node) => [node.id, node]));
+    const drawn = links.filter((link) => link.source !== link.target && notes.has(link.source) && notes.has(link.target));
+    const xs = nodes.map((node) => node.x);
+    const ys = nodes.map((node) => node.y);
+    const [left, right] = options.bounds?.x ?? [Math.min(...xs), Math.max(...xs)];
+    const [bottom, top] = options.bounds?.y ?? [Math.min(...ys), Math.max(...ys)];
+    const extent = Math.max(right - left, top - bottom) || 1;
+    const scale = ((Math.min(width, height) - 2 * padding) *
+        correctionOf(width, height, right - left, top - bottom)) /
+        extent;
+    const at = (node) => ({
+        x: width / 2 + (node.x - (left + right) / 2) * scale,
+        y: height / 2 - (node.y - (bottom + top) / 2) * scale,
+    });
+    const selected = options.active && notes.has(options.active) ? options.active : undefined;
+    const reached = selected === undefined ? undefined : reachOf(selected, drawn, options.reach ?? 'links');
+    const near = reached?.near ?? new Set();
+    const groups = [...new Set(nodes.flatMap((node) => (node.group ? [node.group] : [])))].sort();
+    const series = new Map(groups.map((group, index) => [group, token(`series-${(index % SERIES) + 1}`)]));
+    const own = (node) => node.tone
+        ? toneOf(node.tone)
+        : ((node.group && series.get(node.group)) ?? token('foreground-muted'));
+    const ground = token('surface-sunken');
+    const faded = (node) => selected !== undefined && node.id !== selected && !near.has(node.id);
+    const degree = new Map();
+    for (const { source, target } of drawn) {
+        degree.set(source, (degree.get(source) ?? 0) + 1);
+        degree.set(target, (degree.get(target) ?? 0) + 1);
+    }
+    const radiusOf = (node) => pixelsOf(sizeOf(node.size, degree.get(node.id) ?? 0)) *
+        (node.id === selected ? 1.5 : near.has(node.id) ? 1.25 : 1);
+    const along = Math.min(Math.max(Math.log(drawn.length / 50) / Math.log(2000 / 50), 0), 1);
+    const rest = (0.35 + (0.72 - 0.35) * along) * 100;
+    const lines = [];
+    const raisedLines = [];
+    for (const link of drawn) {
+        const from = at(notes.get(link.source));
+        const to = at(notes.get(link.target));
+        const lit = reached?.along(link.source, link.target) ?? false;
+        const color = lit
+            ? own(notes.get(selected))
+            : selected !== undefined
+                ? mix(token('border'), ground, 60)
+                : mix(own(notes.get(link.source)), ground, rest);
+        (lit ? raisedLines : lines).push(`<line style="stroke:${color}" stroke-width="${lit ? 1.2 : 0.6}" x1="${short(from.x)}" x2="${short(to.x)}" y1="${short(from.y)}" y2="${short(to.y)}"/>`);
+    }
+    const order = (node) => node.id === selected ? 2 : near.has(node.id) ? 1 : 0;
+    const shapes = [...nodes]
+        .sort((one, other) => order(one) - order(other))
+        .map((node) => {
+        const { x, y } = at(node);
+        const radius = radiusOf(node);
+        const color = faded(node) ? mix(own(node), ground, FADED) : own(node);
+        const shape = node.shape ?? options.shape ?? 'circle';
+        const emphasis = shape === 'ring' ? 'outlined' : (node.emphasis ?? options.emphasis ?? 'solid');
+        const body = emphasis === 'solid'
+            ? shapeOf(shape === 'ring' ? 'circle' : shape, x, y, radius, `style="fill:${color}"`)
+            :
+                (emphasis === 'subtle'
+                    ? shapeOf(shape, x, y, radius, `fill-opacity="0.3" style="fill:${color}"`)
+                    : '') +
+                    shapeOf(shape === 'ring' ? 'circle' : shape, x, y, radius * 0.84, `fill="none" stroke-width="${short(radius * 0.32)}" style="stroke:${color}"`);
+        const glow = node.id === selected
+            ? `<circle cx="${short(x)}" cy="${short(y)}" fill-opacity="0.18" r="${short(radius * 2.2)}" style="fill:${color}"/>` +
+                `<circle cx="${short(x)}" cy="${short(y)}" fill="none" r="${short(radius * 1.32)}" stroke-width="${short(Math.max(radius * 0.08, 1))}" style="stroke:${color}"/>`
+            : '';
+        return glow + body;
+    });
+    const naming = options.labels ?? 'hover';
+    const taken = [];
+    const names = [];
+    const candidates = nodes
+        .filter((node) => {
+        if (!node.label && !node.id) {
+            return false;
+        }
+        if (node.id === selected) {
+            return true;
+        }
+        if (faded(node)) {
+            return false;
+        }
+        return (near.has(node.id) ||
+            naming === 'all' ||
+            (naming === 'hubs' && pixelsOf(sizeOf(node.size, degree.get(node.id) ?? 0)) >= HUB));
+    })
+        .sort((one, other) => (other.id === selected ? 1 : 0) - (one.id === selected ? 1 : 0) ||
+        radiusOf(other) - radiusOf(one));
+    for (const node of candidates) {
+        const text = node.label || node.id;
+        const strong = node.id === selected || near.has(node.id);
+        const size = strong ? LABEL : LABEL - 1;
+        const { x, y } = at(node);
+        const radius = radiusOf(node);
+        const wide = widthOf(text, size);
+        const line = y + size / 3;
+        const boxAt = (from) => ({
+            bottom: line + 4,
+            left: from - 2,
+            right: from + wide + 2,
+            top: line - size,
+        });
+        const after = x + radius + 4;
+        const fits = (from) => {
+            const box = boxAt(from);
+            return box.left >= 0 && box.right <= width && clearOf(box, taken);
+        };
+        const before = x - radius - 4 - wide;
+        const start = fits(after) || !fits(before) ? after : before;
+        const box = boxAt(start);
+        if (!clearOf(box, taken) && node.id !== selected) {
+            continue;
+        }
+        taken.push(box);
+        names.push(`<text font-size="${size}" font-weight="${strong ? 600 : 500}" style="fill:${token(strong ? 'foreground' : 'foreground-muted')};stroke:${ground}" x="${short(start)}" y="${short(line)}">${escaped(text)}</text>`);
+    }
+    const regions = [];
+    if (options.groupLabels !== false) {
+        const ownGroup = selected === undefined ? undefined : notes.get(selected)?.group;
+        for (const group of groups) {
+            const members = nodes.filter((node) => node.group === group);
+            const points = members.map(at);
+            const middle = {
+                x: points.reduce((sum, point) => sum + point.x, 0) / points.length,
+                y: points.reduce((sum, point) => sum + point.y, 0) / points.length,
+            };
+            const spread = points.reduce((sum, point) => sum + Math.hypot(point.x - middle.x, point.y - middle.y), 0) /
+                points.length;
+            if (points.length < 2 || spread < 12) {
+                continue;
+            }
+            const name = group.toLocaleUpperCase();
+            const half = (widthOf(name, 11) * 1.14) / 2 + 4;
+            const boxAt = (y) => ({
+                bottom: y + 9,
+                left: middle.x - half,
+                right: middle.x + half,
+                top: y - 9,
+            });
+            const y = [0, 18, -18]
+                .map((step) => middle.y + step)
+                .find((one) => clearOf(boxAt(one), taken));
+            if (y === undefined) {
+                continue;
+            }
+            taken.push(boxAt(y));
+            const tinted = members.find((node) => node.tone === undefined) ?? members[0];
+            const color = mix(tinted ? own(tinted) : token('foreground-muted'), token('foreground'), 60);
+            const fade = selected !== undefined && ownGroup !== group ? 0.3 : 0.92;
+            regions.push(`<text dominant-baseline="middle" fill-opacity="${fade}" font-size="11" font-weight="650" letter-spacing="0.14em" style="fill:${color};stroke:${ground}" text-anchor="middle" x="${short(middle.x)}" y="${short(y)}">${escaped(name)}</text>`);
+        }
+    }
+    return (`<div aria-hidden="true" data-helix-graph-snapshot style="inset:0;overflow:hidden;pointer-events:none;position:absolute">` +
+        `<svg height="${height}" viewBox="0 0 ${width} ${height}" width="${width}" xmlns="http://www.w3.org/2000/svg" style="left:50%;position:absolute;top:50%;translate:-50% -50%">` +
+        `<g stroke-linecap="round">${lines.join('')}${raisedLines.join('')}</g>` +
+        `<g>${shapes.join('')}</g>` +
+        `<g paint-order="stroke" stroke-linejoin="round" stroke-width="3">${regions.join('')}${names.join('')}</g>` +
+        `</svg></div>`);
+};

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@fusion.dev/helix-graph",
   "description": "Connects the Helix Graph frame to a graph renderer: Sigma.js, cosmos.gl, three.js, or a driver of your own.",
-  "version": "0.134.0",
+  "version": "0.136.0",
   "license": "MIT",
   "author": "Ross Sheppard <ross.sheppard@fusion.dev>",
   "repository": {
@@ -33,6 +33,10 @@
       "types": "./dist/sigma/index.d.ts",
       "default": "./dist/sigma/index.js"
     },
+    "./snapshot": {
+      "types": "./dist/snapshot/index.d.ts",
+      "default": "./dist/snapshot/index.js"
+    },
     "./three": {
       "types": "./dist/three/index.d.ts",
       "default": "./dist/three/index.js"
@@ -51,12 +55,12 @@
   },
   "bugs": "https://github.com/project-fusion/fusion/issues",
   "dependencies": {
-    "@fusion.dev/helix-core": "0.134.0"
+    "@fusion.dev/helix-core": "0.136.0"
   },
   "devDependencies": {
     "@cosmos.gl/graph": "^3.4.2",
-    "@fusion.dev/helix-headless": "0.134.0",
-    "@fusion.dev/helix-testing": "0.134.0",
+    "@fusion.dev/helix-headless": "0.136.0",
+    "@fusion.dev/helix-testing": "0.136.0",
     "@types/bun": "^1.3.0",
     "@types/three": "^0.186.0",
     "d3-force-3d": "^3.0.6",