@fusion.dev/helix-graph 0.120.0 → 0.122.0

package/dist/connect-graph/diff.js

@@ -20,7 +20,8 @@ export const diffGraph = (before, after) => {
         else if (was.label !== node.label ||
             was.size !== node.size ||
             was.x !== node.x ||
-            was.y !== node.y) {
+            was.y !== node.y ||
+            was.z !== node.z) {
             changes.changeNodes.push(node);
         }
     }

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

@@ -58,11 +58,31 @@ export interface NodeLook {
      * neighbors drew their names over each other in a knot nobody could read.
      */
     label: 'always' | 'never' | 'room';
+    /** How heavily it is drawn, where the note says. */
+    emphasis?: 'outlined' | 'solid' | 'subtle' | undefined;
+    /** How strongly it glows, from 0 to 1: the selected note's halo. */
+    glow: number;
+    /** What it is drawn as made of, where the note says. */
+    material?: 'frosted' | 'glass' | undefined;
     /** Drawn over the rest, as the selected note and its neighbors are. */
     raised: boolean;
     /** The selected note. */
     selected: boolean;
+    /** Its shape, where the note says. */
+    shape?: 'circle' | 'diamond' | 'ring' | 'square' | undefined;
 }
+/** A tone from the `tone` axis. */
+export type GraphTone = 'accent' | 'danger' | 'info' | 'neutral' | 'primary' | 'success' | 'warning';
+/** What the looks read off one note. */
+export interface NoteFacts {
+    emphasis?: NodeLook['emphasis'];
+    group?: string | undefined;
+    material?: NodeLook['material'];
+    shape?: NodeLook['shape'];
+    tone?: GraphTone | undefined;
+}
+/** A tone's color: `neutral` is the muted ink, and no tone is `primary`. */
+export declare const toneColor: (colors: GraphColors, tone: GraphTone | undefined) => string;
 /** How one link is drawn. */
 export interface LinkLook {
     color: string;
@@ -71,12 +91,18 @@ export interface LinkLook {
 }
 /** How every note and link is drawn, asked one at a time, so ten thousand cost nothing until drawn. */
 export interface GraphLooks {
+    /** A note's own color, its tone's or its group's, whatever the selection fades. */
+    colorOf(id: string): string;
     /** The typeface the labels are drawn in: the first of the frame's own. */
     font: string;
+    /** What the drawing is laid on, which a name is ringed in so it reads over the links. */
+    ground: string;
     /** The color the labels are drawn in. */
     ink: string;
     /** What a name is drawn on while the pointer is over its note. */
     overlay: string;
+    /** The quieter ink a name at rest is drawn in, beside the selected note's and its neighbors'. */
+    quiet: string;
     link(source: string, target: string): LinkLook;
     node(id: string): NodeLook;
 }
@@ -84,8 +110,8 @@ export interface GraphLooks {
  * How the graph is drawn for one selection.
  *
  * **The neighborhood stands out and the rest steps back**, which is what
- * selecting a note in a graph of thousands is for: the selected note in the
- * brand color, the notes it links to and from in their groups' colors with
+ * selecting a note in a graph of thousands is for: the selected note
+ * glowing, the notes it links to and from in their groups' colors with
  * their names drawn where there is room, and every other note faded toward
  * the ground, unnamed. With
  * nothing selected, every note is in its group's color.
@@ -96,9 +122,9 @@ export interface GraphLooks {
 export declare const looksOf: (options: {
     colors: GraphColors;
     font?: string | undefined;
-    groupOf: (id: string) => string | undefined;
     groups: readonly string[];
     near: ReadonlySet<string>;
+    noteOf: (id: string) => NoteFacts | undefined;
     selected: string | undefined;
     shown: ReadonlySet<string> | undefined;
 }) => GraphLooks;

package/dist/connect-graph/looks.js

@@ -54,12 +54,21 @@ export const mixRgb = (from, to, amount) => {
     const channel = (at) => Math.round((one[at] ?? 0) + ((other[at] ?? 0) - (one[at] ?? 0)) * amount);
     return `rgb(${channel(0)}, ${channel(1)}, ${channel(2)})`;
 };
+export const toneColor = (colors, tone) => tone === undefined || tone === 'primary'
+    ? colors.primary
+    : tone === 'neutral'
+        ? colors.muted
+        : colors[tone];
 const FADED = 0.75;
 export const looksOf = (options) => {
-    const { colors, groupOf, near, selected, shown } = options;
+    const { colors, near, noteOf, selected, shown } = options;
     const order = new Map([...new Set(options.groups)].sort().map((group, at) => [group, at]));
     const own = (id) => {
-        const group = groupOf(id);
+        const note = noteOf(id);
+        if (note?.tone) {
+            return toneColor(colors, note.tone);
+        }
+        const group = note?.group;
         const at = group === undefined ? undefined : order.get(group);
         return at === undefined || colors.series.length === 0
             ? colors.muted
@@ -68,24 +77,30 @@ export const looksOf = (options) => {
     const focused = selected !== undefined;
     const hidden = (id) => shown !== undefined && !shown.has(id);
     return {
+        colorOf: own,
         font: options.font || 'sans-serif',
+        ground: colors.ground,
         ink: colors.ink,
         link: (source, target) => {
             const touches = focused && (source === selected || target === selected);
             return {
                 color: touches
-                    ? colors.muted
+                    ? own(selected)
                     : focused
-                        ? mixRgb(colors.line, colors.ground, 0.5)
-                        : colors.line,
+                        ? mixRgb(colors.line, colors.ground, 0.6)
+                        : mixRgb(own(source), colors.ground, 0.72),
                 hidden: hidden(source) || hidden(target),
                 raised: touches,
             };
         },
         node: (id) => {
+            const note = noteOf(id);
+            const facts = { emphasis: note?.emphasis, material: note?.material, shape: note?.shape };
             if (id === selected) {
                 return {
-                    color: colors.primary,
+                    ...facts,
+                    color: own(id),
+                    glow: 1,
                     hidden: hidden(id),
                     label: 'always',
                     raised: true,
@@ -94,7 +109,9 @@ export const looksOf = (options) => {
             }
             const neighbor = focused && near.has(id);
             return {
+                ...facts,
                 color: focused && !neighbor ? mixRgb(own(id), colors.ground, FADED) : own(id),
+                glow: 0,
                 hidden: hidden(id),
                 label: focused && !neighbor ? 'never' : 'room',
                 raised: neighbor,
@@ -102,5 +119,6 @@ export const looksOf = (options) => {
             };
         },
         overlay: colors.overlay,
+        quiet: colors.muted,
     };
 };

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

@@ -2,12 +2,15 @@
 export interface GraphPoint {
     x: number;
     y: number;
+    /** How near the viewer, for a renderer that draws in three dimensions. */
+    z?: number | undefined;
 }
 /** A note as the connector reads it off the frame. */
 export interface SeedNode {
     id: string;
     x?: number | undefined;
     y?: number | undefined;
+    z?: number | undefined;
 }
 /** A link as the connector reads it off the frame. */
 export interface SeedLink {

package/dist/connect-graph/seed.js

@@ -13,7 +13,11 @@ export const seedPositions = (nodes, links, known = new Map()) => {
     const unplaced = new Set();
     for (const node of nodes) {
         if (Number.isFinite(node.x) && Number.isFinite(node.y)) {
-            positions.set(node.id, { x: node.x, y: node.y });
+            positions.set(node.id, {
+                x: node.x,
+                y: node.y,
+                ...(Number.isFinite(node.z) ? { z: node.z } : {}),
+            });
         }
         else {
             const kept = known.get(node.id);
@@ -23,9 +27,18 @@ export const seedPositions = (nodes, links, known = new Map()) => {
         }
     }
     const neighbors = new Map();
+    const add = (from, to) => {
+        const list = neighbors.get(from);
+        if (list) {
+            list.push(to);
+        }
+        else {
+            neighbors.set(from, [to]);
+        }
+    };
     for (const { source, target } of links) {
-        neighbors.set(source, [...(neighbors.get(source) ?? []), target]);
-        neighbors.set(target, [...(neighbors.get(target) ?? []), source]);
+        add(source, target);
+        add(target, source);
     }
     let spiral = positions.size;
     for (const node of nodes) {
@@ -37,7 +50,11 @@ export const seedPositions = (nodes, links, known = new Map()) => {
         const beside = placed === undefined ? undefined : positions.get(placed);
         if (beside) {
             const offset = nudge(node.id);
-            positions.set(node.id, { x: beside.x + offset.x, y: beside.y + offset.y });
+            positions.set(node.id, {
+                x: beside.x + offset.x,
+                y: beside.y + offset.y,
+                ...(beside.z === undefined ? {} : { z: beside.z + offset.x * offset.y }),
+            });
             continue;
         }
         const radius = Math.sqrt(spiral + 0.5);

package/dist/connect-graph/shape-field.d.ts

@@ -0,0 +1,47 @@
+/**
+ * A shape as a signed distance field: for any point in its box, how far it is
+ * from the shape's edge, below zero inside and above zero outside, in the
+ * box's units. **Flat when `depth` is zero**, and solid otherwise.
+ *
+ * One form for every shape, however it was given, so placing notes inside a
+ * shape, on its surface, or at the nearest point inside it is the same work
+ * in two dimensions and three.
+ */
+export interface ShapeField {
+    /** How deep the box is, from front to back: zero for a flat shape. */
+    readonly depth: number;
+    /** How far a point is from the shape's edge: below zero inside. `z` is ignored for a flat shape. */
+    distance(x: number, y: number, z?: number): number;
+    /** How tall the box is. Its y points down, as an SVG's does. */
+    readonly height: number;
+    /** How wide the box is. */
+    readonly width: number;
+}
+/**
+ * A field from a test of whether a point in the box is inside, sampled at
+ * the center of each cell: flat when `depth` is zero, solid otherwise.
+ */
+export declare const fieldFromInside: (inside: (x: number, y: number, z: number) => boolean, box: {
+    depth?: number | undefined;
+    height: number;
+    width: number;
+}, resolution?: number) => ShapeField;
+/**
+ * A flat field from an SVG path in a box `width` by `height`, its holes cut by
+ * the even-odd rule. Drawn once to a canvas and read off it, which is what
+ * lets a detailed outline become a field in a moment.
+ */
+export declare const fieldFromPath: (path: string, width: number, height: number, resolution?: number) => ShapeField;
+/**
+ * A solid puffed out of a flat shape, as a cushion is: as thick as `depth`
+ * where the shape is widest, rounding to nothing at its edge, and cut
+ * through wherever the flat shape has a hole.
+ *
+ * `roundness`, from 0 to 1, is how far in from the edge the rounding runs, as
+ * a share of the way to the shape's middle: 1, the default, rounds the whole
+ * way, as a pebble; less leaves a flat face, as a coin.
+ */
+export declare const inflate: (flat: ShapeField, { depth, roundness }: {
+    depth: number;
+    roundness?: number;
+}) => ShapeField;

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

@@ -0,0 +1,172 @@
+const FLAT = 512;
+const SOLID = 96;
+const FAR = 1e20;
+const line = (values, count, out) => {
+    const hull = new Int32Array(count);
+    const bounds = new Float64Array(count + 1);
+    const crossing = (at, from) => (values[at] + at * at - (values[from] + from * from)) /
+        (2 * at - 2 * from);
+    let top = 0;
+    hull[0] = 0;
+    bounds[0] = -FAR;
+    bounds[1] = FAR;
+    for (let at = 1; at < count; at++) {
+        let cross = crossing(at, hull[top]);
+        while (cross <= bounds[top]) {
+            top -= 1;
+            cross = crossing(at, hull[top]);
+        }
+        top += 1;
+        hull[top] = at;
+        bounds[top] = cross;
+        bounds[top + 1] = FAR;
+    }
+    top = 0;
+    for (let at = 0; at < count; at++) {
+        while (bounds[top + 1] < at) {
+            top += 1;
+        }
+        const from = hull[top];
+        out[at] = (at - from) * (at - from) + values[from];
+    }
+};
+const transform = (marked, sizes) => {
+    const [nx, ny, nz] = sizes;
+    const grid = new Float64Array(nx * ny * nz);
+    for (let at = 0; at < grid.length; at++) {
+        grid[at] = marked[at] ? 0 : FAR;
+    }
+    const longest = Math.max(nx, ny, nz);
+    const values = new Float64Array(longest);
+    const out = new Float64Array(longest);
+    const pass = (count, stride, starts) => {
+        for (const start of starts) {
+            for (let step = 0; step < count; step++) {
+                values[step] = grid[start + step * stride];
+            }
+            line(values, count, out);
+            for (let step = 0; step < count; step++) {
+                grid[start + step * stride] = out[step];
+            }
+        }
+    };
+    const along = function* (outer, inner, outerStride, innerStride) {
+        for (let one = 0; one < outer; one++) {
+            for (let two = 0; two < inner; two++) {
+                yield one * outerStride + two * innerStride;
+            }
+        }
+    };
+    pass(nx, 1, along(nz, ny, nx * ny, nx));
+    pass(ny, nx, along(nz, nx, nx * ny, 1));
+    if (nz > 1) {
+        pass(nz, nx * ny, along(ny, nx, nx, 1));
+    }
+    for (let at = 0; at < grid.length; at++) {
+        grid[at] = Math.sqrt(grid[at]);
+    }
+    return grid;
+};
+const fieldFromCells = (inside, sizes, cell, box) => {
+    const outside = new Uint8Array(inside.length);
+    for (let at = 0; at < inside.length; at++) {
+        outside[at] = inside[at] ? 0 : 1;
+    }
+    const toInside = transform(inside, sizes);
+    const toOutside = transform(outside, sizes);
+    const [nx, ny, nz] = sizes;
+    const signed = new Float32Array(inside.length);
+    for (let at = 0; at < inside.length; at++) {
+        signed[at] = inside[at]
+            ? -(toOutside[at] - 0.5) * cell
+            : (toInside[at] - 0.5) * cell;
+    }
+    const read = (x, y, z) => signed[Math.min(Math.max(z, 0), nz - 1) * nx * ny +
+        Math.min(Math.max(y, 0), ny - 1) * nx +
+        Math.min(Math.max(x, 0), nx - 1)];
+    return {
+        ...box,
+        distance: (x, y, z = 0) => {
+            const fx = x / cell - 0.5;
+            const fy = y / cell - 0.5;
+            const fz = nz > 1 ? z / cell - 0.5 : 0;
+            const x0 = Math.floor(fx);
+            const y0 = Math.floor(fy);
+            const z0 = Math.floor(fz);
+            const tx = fx - x0;
+            const ty = fy - y0;
+            const tz = fz - z0;
+            const plane = (layer) => (read(x0, y0, layer) * (1 - tx) + read(x0 + 1, y0, layer) * tx) * (1 - ty) +
+                (read(x0, y0 + 1, layer) * (1 - tx) + read(x0 + 1, y0 + 1, layer) * tx) * ty;
+            const within = nz > 1 ? plane(z0) * (1 - tz) + plane(z0 + 1) * tz : plane(0);
+            const past = Math.hypot(Math.max(-x, x - box.width, 0), Math.max(-y, y - box.height, 0), nz > 1 ? Math.max(-z, z - box.depth, 0) : 0);
+            return past > 0 ? Math.max(within, 0) + past : within;
+        },
+    };
+};
+export const fieldFromInside = (inside, box, resolution = box.depth ? SOLID : FLAT) => {
+    const depth = box.depth ?? 0;
+    const cell = Math.max(box.width, box.height, depth) / resolution;
+    const nx = Math.max(1, Math.ceil(box.width / cell));
+    const ny = Math.max(1, Math.ceil(box.height / cell));
+    const nz = depth > 0 ? Math.max(1, Math.ceil(depth / cell)) : 1;
+    const cells = new Uint8Array(nx * ny * nz);
+    for (let z = 0; z < nz; z++) {
+        for (let y = 0; y < ny; y++) {
+            for (let x = 0; x < nx; x++) {
+                cells[z * nx * ny + y * nx + x] = inside((x + 0.5) * cell, (y + 0.5) * cell, depth > 0 ? (z + 0.5) * cell : 0)
+                    ? 1
+                    : 0;
+            }
+        }
+    }
+    return fieldFromCells(cells, [nx, ny, nz], cell, {
+        depth,
+        height: box.height,
+        width: box.width,
+    });
+};
+export const fieldFromPath = (path, width, height, resolution = FLAT) => {
+    const cell = Math.max(width, height, 1) / resolution;
+    const nx = Math.max(1, Math.ceil(width / cell));
+    const ny = Math.max(1, Math.ceil(height / cell));
+    const canvas = document.createElement('canvas');
+    canvas.width = nx;
+    canvas.height = ny;
+    const context = canvas.getContext('2d', { willReadFrequently: true });
+    const cells = new Uint8Array(nx * ny);
+    if (context) {
+        context.scale(1 / cell, 1 / cell);
+        context.fill(new Path2D(path), 'evenodd');
+        const alpha = context.getImageData(0, 0, nx, ny).data;
+        for (let at = 0; at < cells.length; at++) {
+            cells[at] = (alpha[at * 4 + 3] ?? 0) > 127 ? 1 : 0;
+        }
+    }
+    else {
+        cells.fill(1);
+    }
+    return fieldFromCells(cells, [nx, ny, 1], cell, { depth: 0, height, width });
+};
+export const inflate = (flat, { depth, roundness = 1 }) => {
+    let deepest = 0;
+    const probes = 128;
+    for (let row = 0; row < probes; row++) {
+        for (let column = 0; column < probes; column++) {
+            deepest = Math.max(deepest, -flat.distance(((column + 0.5) / probes) * flat.width, ((row + 0.5) / probes) * flat.height));
+        }
+    }
+    const reach = Math.max(deepest * Math.min(Math.max(roundness, 0.01), 1), 1e-6);
+    const middle = depth / 2;
+    return {
+        depth,
+        distance: (x, y, z = middle) => {
+            const across = flat.distance(x, y);
+            const inset = Math.min(Math.max(-across, 0) / reach, 1);
+            const half = middle * Math.sqrt(1 - (1 - inset) ** 2);
+            return Math.max(across, Math.abs(z - middle) - half);
+        },
+        height: flat.height,
+        width: flat.width,
+    };
+};

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

@@ -0,0 +1,50 @@
+import type { GraphPoint } from './seed.js';
+import { type ShapeField } from './shape-field.js';
+/**
+ * A shape the notes are drawn in. **Any shape field**, flat or solid, such as
+ * `inflate` makes; or, flat, an SVG path in a box `width` by `height`, as an
+ * SVG's `viewBox="0 0 width height"` gives one, whose holes are cut by the
+ * even-odd rule; or a test of whether a point in that box is inside.
+ */
+export type GraphStencil = (ShapeField | {
+    height: number;
+    path: string;
+    width: number;
+} | {
+    height: number;
+    inside: (x: number, y: number) => boolean;
+    width: number;
+}) & {
+    /**
+     * Where in the shape the notes go: `fill`, all through it, which unset is;
+     * or `surface`, a thin shell just inside its edge, which is how a solid
+     * reads as the thing it is shaped like.
+     */
+    place?: 'fill' | 'surface' | undefined;
+    /** How thick the surface's shell is, as a share of the shape's size. 0.04 by default. */
+    shell?: number | undefined;
+};
+/** The field a stencil is, or is made into. */
+export declare const fieldOf: (stencil: GraphStencil) => ShapeField;
+/**
+ * `count` places spread evenly over a shape: through all of it, or through a
+ * shell just inside its edge. A grid sized to the room there is, each place
+ * shaken within its cell so no rows show, and made finer until it holds
+ * enough.
+ */
+export declare const placesIn: (field: ShapeField, count: number, { place, shell }?: {
+    place?: 'fill' | 'surface';
+    shell?: number;
+}) => GraphPoint[];
+/**
+ * Places a layout or an arrangement put anywhere, moved into the stencil's
+ * shape and spread evenly over it. **The notes keep their order**, left to
+ * right, top to bottom, and front to back in a solid, so notes put together
+ * land together, and each group takes a region of the shape.
+ *
+ * Centered where the places were, and as large. The stencil's y points down,
+ * as an SVG's does, and the places' up, as Sigma, cosmos.gl and three.js draw
+ * them. Places the shape cannot hold, as when it has no inside, come back as
+ * they were.
+ */
+export declare const fitToStencil: (positions: ReadonlyMap<string, GraphPoint>, stencil: GraphStencil) => Map<string, GraphPoint>;