@fusion.dev/helix-graph 0.121.0 → 0.122.0

package/dist/connect-graph/stencil.js

@@ -1,5 +1,6 @@
-const RASTER = 1024;
-const PROBE = 64;
+import { fieldFromInside, fieldFromPath } from './shape-field.js';
+const PROBE = { flat: 64, solid: 32 };
+const SHELL = 0.04;
 const WAVE = 0.07;
 const seeded = (seed) => {
     let state = seed >>> 0 || 1;
@@ -8,57 +9,60 @@ const seeded = (seed) => {
         return state / 4294967296;
     };
 };
-const insideOf = (stencil) => {
-    if ('inside' in stencil) {
-        return stencil.inside;
+const fields = new WeakMap();
+export const fieldOf = (stencil) => {
+    if ('distance' in stencil) {
+        return stencil;
     }
-    const scale = RASTER / Math.max(stencil.width, stencil.height, 1);
-    const width = Math.max(1, Math.ceil(stencil.width * scale));
-    const height = Math.max(1, Math.ceil(stencil.height * scale));
-    const canvas = document.createElement('canvas');
-    canvas.width = width;
-    canvas.height = height;
-    const context = canvas.getContext('2d', { willReadFrequently: true });
-    if (!context) {
-        return () => true;
+    const made = fields.get(stencil);
+    if (made) {
+        return made;
     }
-    context.scale(scale, scale);
-    context.fill(new Path2D(stencil.path), 'evenodd');
-    const alpha = context.getImageData(0, 0, width, height).data;
-    return (x, y) => {
-        const column = Math.floor(x * scale);
-        const row = Math.floor(y * scale);
-        return (column >= 0 &&
-            row >= 0 &&
-            column < width &&
-            row < height &&
-            (alpha[(row * width + column) * 4 + 3] ?? 0) > 127);
-    };
+    const field = 'path' in stencil
+        ? fieldFromPath(stencil.path, stencil.width, stencil.height)
+        : fieldFromInside((x, y) => stencil.inside(x, y), stencil);
+    fields.set(stencil, field);
+    return field;
 };
-export const placesIn = (inside, width, height, count) => {
-    let filled = 0;
-    for (let row = 0; row < PROBE; row++) {
-        for (let column = 0; column < PROBE; column++) {
-            if (inside(((column + 0.5) / PROBE) * width, ((row + 0.5) / PROBE) * height)) {
-                filled += 1;
+export const placesIn = (field, count, { place = 'fill', shell = SHELL } = {}) => {
+    const solid = field.depth > 0;
+    const { depth, height, width } = field;
+    const thickness = shell * Math.max(width, height, depth);
+    const takes = (x, y, z) => {
+        const distance = field.distance(x, y, z);
+        return distance < 0 && (place === 'fill' || distance > -thickness);
+    };
+    const probe = solid ? PROBE.solid : PROBE.flat;
+    let taken = 0;
+    for (let layer = 0; layer < (solid ? probe : 1); layer++) {
+        for (let row = 0; row < probe; row++) {
+            for (let column = 0; column < probe; column++) {
+                if (takes(((column + 0.5) / probe) * width, ((row + 0.5) / probe) * height, solid ? ((layer + 0.5) / probe) * depth : 0)) {
+                    taken += 1;
+                }
             }
         }
     }
-    if (count === 0 || filled === 0) {
+    if (count === 0 || taken === 0) {
         return [];
     }
     const random = seeded(count);
-    let step = Math.sqrt(((filled / PROBE ** 2) * width * height) / count);
+    const room = (taken / probe ** (solid ? 3 : 2)) * width * height * (solid ? depth : 1);
+    let step = (room / count) ** (1 / (solid ? 3 : 2));
     for (let tries = 0; tries < 8; tries++) {
         const places = [];
-        for (let y = step / 2; y < height; y += step) {
-            for (let x = step / 2; x < width; x += step) {
-                const place = {
-                    x: x + (random() - 0.5) * step * 0.8,
-                    y: y + (random() - 0.5) * step * 0.8,
-                };
-                if (inside(place.x, place.y)) {
-                    places.push(place);
+        const layers = solid ? Math.ceil(depth / step) : 1;
+        for (let layer = 0; layer < layers; layer++) {
+            for (let y = step / 2; y < height; y += step) {
+                for (let x = step / 2; x < width; x += step) {
+                    const place = {
+                        x: x + (random() - 0.5) * step * 0.8,
+                        y: y + (random() - 0.5) * step * 0.8,
+                        ...(solid ? { z: (layer + 0.5 + (random() - 0.5) * 0.8) * step } : {}),
+                    };
+                    if (takes(place.x, place.y, place.z ?? 0)) {
+                        places.push(place);
+                    }
                 }
             }
         }
@@ -69,53 +73,127 @@ export const placesIn = (inside, width, height, count) => {
             }
             return places.slice(0, count);
         }
-        step *= Math.sqrt(places.length / count) * 0.97 || 0.5;
+        step *= (places.length / count) ** (1 / (solid ? 3 : 2)) * 0.97 || 0.5;
     }
     return [];
 };
+const nested = (items, keys) => {
+    const [key, ...rest] = keys;
+    if (!key) {
+        return items;
+    }
+    const sorted = [...items].sort((one, other) => key(one) - key(other));
+    if (rest.length === 0) {
+        return sorted;
+    }
+    const slice = Math.ceil(items.length ** (rest.length / keys.length));
+    const out = [];
+    for (let from = 0; from < sorted.length; from += slice) {
+        out.push(...nested(sorted.slice(from, from + slice), rest));
+    }
+    return out;
+};
 export const fitToStencil = (positions, stencil) => {
     const notes = [...positions].map(([id, at]) => ({ at, id }));
     if (notes.length === 0) {
         return new Map();
     }
-    const places = placesIn(insideOf(stencil), stencil.width, stencil.height, notes.length);
+    const field = fieldOf(stencil);
+    const places = placesIn(field, notes.length, {
+        place: stencil.place ?? 'fill',
+        shell: stencil.shell ?? SHELL,
+    });
     if (places.length < notes.length) {
         return new Map(positions);
     }
-    let left = Number.POSITIVE_INFINITY;
-    let right = Number.NEGATIVE_INFINITY;
-    let bottom = Number.POSITIVE_INFINITY;
-    let top = Number.NEGATIVE_INFINITY;
+    const solid = field.depth > 0;
+    const low = {
+        x: Number.POSITIVE_INFINITY,
+        y: Number.POSITIVE_INFINITY,
+        z: Number.POSITIVE_INFINITY,
+    };
+    const high = {
+        x: Number.NEGATIVE_INFINITY,
+        y: Number.NEGATIVE_INFINITY,
+        z: Number.NEGATIVE_INFINITY,
+    };
     for (const { at } of notes) {
-        left = Math.min(left, at.x);
-        right = Math.max(right, at.x);
-        bottom = Math.min(bottom, at.y);
-        top = Math.max(top, at.y);
+        for (const axis of ['x', 'y', 'z']) {
+            const value = at[axis] ?? 0;
+            low[axis] = Math.min(low[axis], value);
+            high[axis] = Math.max(high[axis], value);
+        }
     }
-    const scale = Math.max(right - left, top - bottom, 1) / Math.max(stencil.width, stencil.height);
-    const { height, width } = stencil;
-    const spots = places
-        .map((place) => ({
-        across: place.x + WAVE * width * Math.sin((place.y / height) * Math.PI * 3 + 1.3),
-        at: {
-            x: (left + right) / 2 + (place.x - width / 2) * scale,
-            y: (bottom + top) / 2 - (place.y - height / 2) * scale,
-        },
-        down: -place.y + WAVE * height * Math.sin((place.x / width) * Math.PI * 3 + 0.4),
-    }))
-        .sort((one, other) => one.across - other.across);
-    notes.sort((one, other) => one.at.x - other.at.x || one.at.y - other.at.y);
-    const strip = Math.ceil(Math.sqrt(notes.length));
+    const { depth, height, width } = field;
+    const scale = Math.max(high.x - low.x, high.y - low.y, solid ? high.z - low.z : 0, 1) /
+        Math.max(width, height, depth);
+    const middle = { x: (low.x + high.x) / 2, y: (low.y + high.y) / 2, z: (low.z + high.z) / 2 };
+    const spots = places.map((place) => {
+        const z = place.z ?? depth / 2;
+        return {
+            across: place.x + WAVE * width * Math.sin((place.y / height) * Math.PI * 3 + 1.3),
+            at: {
+                x: middle.x + (place.x - width / 2) * scale,
+                y: middle.y - (place.y - height / 2) * scale,
+                ...(solid ? { z: middle.z + (z - depth / 2) * scale } : {}),
+            },
+            down: -place.y + WAVE * height * Math.sin((place.x / width) * Math.PI * 3 + 0.4),
+        };
+    });
     const fitted = new Map();
-    for (let from = 0; from < notes.length; from += strip) {
-        const ours = notes.slice(from, from + strip).sort((one, other) => one.at.y - other.at.y);
-        const theirs = spots
-            .slice(from, from + strip)
-            .sort((one, other) => one.down - other.down)
-            .map((spot) => spot.at);
-        ours.forEach((note, at) => {
-            fitted.set(note.id, theirs[at]);
-        });
+    if (solid) {
+        const surface = (stencil.place ?? 'fill') === 'surface';
+        const way = (point) => {
+            if (!surface) {
+                return point;
+            }
+            const x = point.x - middle.x;
+            const y = point.y - middle.y;
+            const z = (point.z ?? 0) - middle.z;
+            const length = Math.hypot(x, y, z) || 1;
+            return { x: x / length, y: y / length, z: z / length };
+        };
+        const widest = (points) => {
+            let best = 'x';
+            let spread = Number.NEGATIVE_INFINITY;
+            for (const axis of ['x', 'y', 'z']) {
+                let low = Number.POSITIVE_INFINITY;
+                let high = Number.NEGATIVE_INFINITY;
+                for (const point of points) {
+                    const value = point[axis] ?? 0;
+                    low = Math.min(low, value);
+                    high = Math.max(high, value);
+                }
+                if (high - low > spread) {
+                    spread = high - low;
+                    best = axis;
+                }
+            }
+            return best;
+        };
+        const halve = (ours, theirs) => {
+            if (ours.length === 1) {
+                fitted.set(ours[0].id, theirs[0].at);
+                return;
+            }
+            if (ours.length === 0) {
+                return;
+            }
+            const mine = widest(ours.map((note) => note.key));
+            const yours = widest(theirs.map((spot) => spot.key));
+            ours.sort((one, other) => (one.key[mine] ?? 0) - (other.key[mine] ?? 0));
+            theirs.sort((one, other) => (one.key[yours] ?? 0) - (other.key[yours] ?? 0));
+            const half = Math.floor(ours.length / 2);
+            halve(ours.slice(0, half), theirs.slice(0, half));
+            halve(ours.slice(half), theirs.slice(half));
+        };
+        halve(notes.map((note) => ({ ...note, key: way(note.at) })), spots.map((spot) => ({ at: spot.at, key: way(spot.at) })));
+        return fitted;
     }
+    const ours = nested(notes, [(note) => note.at.x, (note) => note.at.y]);
+    const theirs = nested(spots, [(spot) => spot.across, (spot) => spot.down]);
+    ours.forEach((note, at) => {
+        fitted.set(note.id, theirs[at].at);
+    });
     return fitted;
 };

package/dist/cosmos/cosmos-driver.js

@@ -1,4 +1,4 @@
-import { gesturesHeld, groupsOver, signalsOver } from '../overlay/overlay.js';
+import { gesturesHeld, groupsOver, namesOver, signalsOver, } from '../overlay/overlay.js';
 const SHAPES = { circle: 0, diamond: 3, ring: 0, square: 1 };
 const STEP = 250;
 const FAINT = 0.16;
@@ -81,61 +81,13 @@ export const cosmosDriver = (graph, container, options = {}) => {
     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 names = namesOver(container, onScreen);
     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 lit = hovered === undefined ? undefined : ids[hovered];
+        const shown = [...new Set([selected, lit, ...near])].flatMap((id) => id === undefined
+            ? []
+            : [{ id, name: drawnNow.get(id)?.label ?? id, strong: id === selected || id === lit }]);
+        names.draw(looks, shown);
     };
     const redraw = () => {
         drawNames();
@@ -418,7 +370,7 @@ export const cosmosDriver = (graph, container, options = {}) => {
             });
             signals.stop();
             groups.stop();
-            names.remove();
+            names.stop();
             held.stop();
         },
         update: (changes, animate) => {

package/dist/overlay/overlay.d.ts

@@ -7,6 +7,8 @@ export type OnScreen = (id: string) => {
     x: number;
     y: number;
 } | undefined;
+/** Whether an `rgb()` color is light, which a light ink says the ground is dark. */
+export declare const isLight: (color: string) => boolean;
 /** 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. */
@@ -30,6 +32,22 @@ export declare const signalsOver: (container: HTMLElement, onScreen: OnScreen) =
     } | undefined, animate: boolean) => void;
     stop: () => void;
 };
+/** A note to name over the drawing: its name, and whether it is the one the reader is on. */
+export interface Named {
+    id: string;
+    name: string;
+    strong: boolean;
+}
+/**
+ * **Names on a canvas of their own**, for a renderer that draws none: each
+ * note given, beside it, ringed in the ground's color so it reads over the
+ * links. The strong ones always, and the rest where there is room, in the
+ * order given.
+ */
+export declare const namesOver: (container: HTMLElement, onScreen: OnScreen) => {
+    draw: (looks: GraphLooks | undefined, named: readonly Named[]) => 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.

package/dist/overlay/overlay.js

@@ -65,7 +65,7 @@ const arrive = (context, color, at, gone) => {
     context.arc(at.x, at.y, reach, 0, Math.PI * 2);
     context.fill();
 };
-const isLight = (color) => {
+export const isLight = (color) => {
     const [red = 0, green = 0, blue = 0] = color.match(/[\d.]+/g)?.map(Number) ?? [];
     return (0.2126 * red + 0.7152 * green + 0.0722 * blue) / 255 > 0.5;
 };
@@ -76,6 +76,7 @@ const nameGroups = (context, groups, looks, at) => {
     context.textAlign = 'center';
     context.textBaseline = 'middle';
     context.shadowColor = looks.ground;
+    const taken = [];
     for (const group of groups) {
         let x = 0;
         let y = 0;
@@ -100,6 +101,23 @@ const nameGroups = (context, groups, looks, at) => {
             continue;
         }
         const name = group.name.toLocaleUpperCase();
+        const half = context.measureText(name).width / 2 + 4;
+        const boxAt = (middle) => ({
+            bottom: middle + 9,
+            left: x - half,
+            right: x + half,
+            top: middle - 9,
+        });
+        const clear = (box) => taken.every((other) => box.right < other.left ||
+            box.left > other.right ||
+            box.bottom < other.top ||
+            box.top > other.bottom);
+        const line = [0, 18, -18].map((step) => y + step).find((middle) => clear(boxAt(middle)));
+        if (line === undefined) {
+            continue;
+        }
+        y = line;
+        taken.push(boxAt(y));
         context.globalAlpha = group.faded ? 0.3 : 0.92;
         context.fillStyle = mixRgb(group.color, looks.ink, 0.6);
         context.shadowBlur = 10;
@@ -223,6 +241,50 @@ export const signalsOver = (container, onScreen) => {
         },
     };
 };
+export const namesOver = (container, onScreen) => {
+    const canvas = layer(container, 'names');
+    return {
+        draw: (looks, named) => {
+            const context = looks ? fresh(canvas, container) : null;
+            if (!context || !looks) {
+                return;
+            }
+            const taken = [];
+            for (const { id, name, strong } of named) {
+                const at = onScreen(id);
+                if (!at || looks.node(id).hidden) {
+                    continue;
+                }
+                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);
+            }
+        },
+        stop: () => {
+            canvas.remove();
+        },
+    };
+};
 export const groupsOver = (container, onScreen) => {
     let canvas;
     let groups = [];

package/dist/shapes/index.d.ts

@@ -0,0 +1 @@
+export { fieldFromInside as shapeFromInside, fieldFromPath as shapeFromPath, inflate, type ShapeField, } from '../connect-graph/shape-field.js';

package/dist/shapes/index.js

@@ -0,0 +1 @@
+export { fieldFromInside as shapeFromInside, fieldFromPath as shapeFromPath, inflate, } from '../connect-graph/shape-field.js';

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;