@fusion.dev/helix-graph 0.119.0 → 0.121.0

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

@@ -1,6 +1,9 @@
-import { HelixGraphPanEvent, HelixGraphPartChangeEvent, HelixGraphZoomEvent, isRtl, watchTheme, } from '@fusion.dev/helix-core';
-import { graphColorsFrom, looksOf } from './looks.js';
+import { HelixGraphPanEvent, HelixGraphPartChangeEvent, HelixGraphSignalEvent, HelixGraphZoomEvent, isRtl, watchTheme, } from '@fusion.dev/helix-core';
+import { arrangeByGroup } from './arrange.js';
+import { diffGraph, isEmpty, linkKey, } from './diff.js';
+import { graphColorsFrom, looksOf, toneColor, } from './looks.js';
 import { seedPositions } from './seed.js';
+import { fitToStencil } from './stencil.js';
 const viewportOf = (frame) => {
     const box = (frame.shadowRoot?.querySelector('[part="viewport"]') ?? frame).getBoundingClientRect();
     return { height: box.height, width: box.width };
@@ -9,7 +12,13 @@ const still = () => typeof matchMedia === 'function' && matchMedia('(prefers-red
 export const connectGraph = (frame, driver, options = {}) => {
     const graph = frame;
     let known = new Map();
+    let drawnNodes = new Map();
+    let drawnLinks = new Map();
+    let first = true;
+    let waiting = new Set();
+    let owed = false;
     let colors = null;
+    let current;
     let stopSettling;
     let pressed;
     let pending = 0;
@@ -33,58 +42,153 @@ export const connectGraph = (frame, driver, options = {}) => {
                 }
             }
         }
-        const groups = new Map(nodes.map((node) => [node.id, node.group]));
-        driver.look(looksOf({
+        const notes = new Map(nodes.map((node) => [node.id, node]));
+        current = looksOf({
             colors,
             font: getComputedStyle(frame)
                 .fontFamily.split(',')[0]
                 ?.trim()
                 .replace(/^["']|["']$/g, ''),
-            groupOf: (id) => groups.get(id),
             groups: nodes.flatMap((node) => (node.group === undefined ? [] : [node.group])),
             near,
+            noteOf: (id) => notes.get(id),
             selected,
             shown: graph.shown,
-        }));
+        });
+        driver.look(current);
+        if (driver.groups) {
+            const members = new Map();
+            for (const node of nodes) {
+                if (node.group !== undefined) {
+                    const list = members.get(node.group);
+                    if (list) {
+                        list.push(node.id);
+                    }
+                    else {
+                        members.set(node.group, [node.id]);
+                    }
+                }
+            }
+            const own = selected === undefined ? undefined : notes.get(selected)?.group;
+            const looks = current;
+            driver.groups([...members].map(([name, ids]) => ({
+                color: looks.colorOf(ids.find((id) => notes.get(id)?.tone === undefined) ?? ids[0] ?? ''),
+                faded: selected !== undefined && own !== name,
+                ids,
+                name,
+            })));
+        }
     };
-    const draw = () => {
-        stopSettling?.();
-        stopSettling = undefined;
+    const draw = (whole = false) => {
+        if (stopSettling) {
+            stopSettling();
+            stopSettling = undefined;
+        }
         cancelAnimationFrame(pending);
         const nodes = graph.nodes ?? [];
         const ids = new Set(nodes.map((node) => node.id));
-        const links = (graph.links ?? []).filter(({ source, target }) => source !== target && ids.has(source) && ids.has(target));
-        const { positions, unplaced } = seedPositions(nodes, links, known);
-        graph.drawn?.(false);
-        driver.draw({
-            links: links.map(({ label, source, target }) => ({ label, source, target })),
-            nodes: nodes.map((node) => {
-                const at = positions.get(node.id);
-                return {
-                    id: node.id,
-                    label: node.label || node.id,
-                    size: Number.isFinite(node.size) ? node.size : 1,
-                    x: at.x,
-                    y: at.y,
-                };
-            }),
-        });
+        const nextLinks = new Map();
+        for (const { label, source, target } of graph.links ?? []) {
+            if (source !== target && ids.has(source) && ids.has(target)) {
+                nextLinks.set(linkKey({ source, target }), { label, source, target });
+            }
+        }
+        let { positions, unplaced } = seedPositions(nodes, [...nextLinks.values()], known);
+        const shaped = options.stencil && ids.size > 0 && unplaced.size === ids.size
+            ? fitToStencil(arrangeByGroup(nodes, [...nextLinks.values()]), options.stencil)
+            : undefined;
+        if (shaped) {
+            positions = shaped;
+            unplaced = new Set();
+            known = new Map(shaped);
+        }
+        const degree = new Map();
+        for (const { source, target } of nextLinks.values()) {
+            degree.set(source, (degree.get(source) ?? 0) + 1);
+            degree.set(target, (degree.get(target) ?? 0) + 1);
+        }
+        const nextNodes = new Map();
+        for (const node of nodes) {
+            const at = positions.get(node.id);
+            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),
+                x: at.x,
+                y: at.y,
+            });
+        }
+        for (const id of waiting) {
+            if (ids.has(id)) {
+                unplaced.add(id);
+            }
+        }
+        const incremental = !first && !whole && driver.update !== undefined;
+        if (incremental) {
+            const changes = diffGraph({ links: drawnLinks, nodes: drawnNodes }, { links: nextLinks, nodes: nextNodes });
+            if (!isEmpty(changes)) {
+                driver.update?.(changes, !still());
+            }
+        }
+        else {
+            graph.drawn?.(false);
+            driver.draw({ links: [...nextLinks.values()], nodes: [...nextNodes.values()] });
+        }
+        drawnNodes = nextNodes;
+        drawnLinks = nextLinks;
+        known = positions;
         restyle();
+        if (first || whole) {
+            owed = true;
+        }
+        first = false;
         if (unplaced.size > 0 && driver.settle) {
+            waiting = unplaced;
             stopSettling = driver.settle(unplaced, (settled) => {
                 stopSettling = undefined;
+                waiting = new Set();
                 known = new Map(settled);
+                for (const [id, at] of settled) {
+                    const node = drawnNodes.get(id);
+                    if (node) {
+                        drawnNodes.set(id, { ...node, x: at.x, y: at.y });
+                    }
+                }
                 graph.laidOut?.(Object.fromEntries([...settled].map(([id, at]) => [id, { ...at }])));
-                graph.drawn?.(true);
+                if (owed) {
+                    owed = false;
+                    graph.drawn?.(true);
+                }
             });
             return;
         }
-        known = positions;
-        pending = requestAnimationFrame(() => {
-            if (connected) {
-                graph.drawn?.(true);
-            }
-        });
+        waiting = new Set();
+        if (shaped) {
+            graph.laidOut?.(Object.fromEntries([...shaped].map(([id, at]) => [id, { ...at }])));
+        }
+        if (owed) {
+            pending = requestAnimationFrame(() => {
+                if (connected && owed) {
+                    owed = false;
+                    graph.drawn?.(true);
+                }
+            });
+        }
+    };
+    const handleSignal = (event) => {
+        const { from, to, tone } = event.detail;
+        if (!driver.signal || !drawnNodes.has(from) || !drawnNodes.has(to)) {
+            return;
+        }
+        colors ??= graphColorsFrom(frame);
+        const toned = tone !== undefined && colors ? toneColor(colors, tone) : undefined;
+        driver.signal(from, to, toned
+            ? { from: toned, to: toned }
+            : current
+                ? { from: current.colorOf(from), to: current.colorOf(to) }
+                : undefined, !still());
     };
     const handlePartChange = (event) => {
         const { kind } = event.detail;
@@ -95,7 +199,21 @@ export const connectGraph = (frame, driver, options = {}) => {
             restyle();
             const selected = graph.active;
             if (selected && selected !== pressed && options.center !== false) {
-                driver.center?.(selected, !still());
+                const near = [selected];
+                for (const { source, target } of drawnLinks.values()) {
+                    if (source === selected) {
+                        near.push(target);
+                    }
+                    else if (target === selected) {
+                        near.push(source);
+                    }
+                }
+                if (driver.fit && near.length > 1) {
+                    driver.fit(near, !still());
+                }
+                else {
+                    driver.center?.(selected, !still());
+                }
             }
             pressed = undefined;
         }
@@ -117,6 +235,7 @@ export const connectGraph = (frame, driver, options = {}) => {
         }
     };
     frame.addEventListener(HelixGraphPartChangeEvent.eventName, handlePartChange);
+    frame.addEventListener(HelixGraphSignalEvent.eventName, handleSignal);
     frame.addEventListener(HelixGraphPanEvent.eventName, handlePan);
     frame.addEventListener(HelixGraphZoomEvent.eventName, handleZoom);
     const stopPress = driver.onPress?.((id) => {
@@ -147,6 +266,7 @@ export const connectGraph = (frame, driver, options = {}) => {
             stopPress?.();
             stopTheme();
             frame.removeEventListener(HelixGraphPartChangeEvent.eventName, handlePartChange);
+            frame.removeEventListener(HelixGraphSignalEvent.eventName, handleSignal);
             frame.removeEventListener(HelixGraphPanEvent.eventName, handlePan);
             frame.removeEventListener(HelixGraphZoomEvent.eventName, handleZoom);
             if (focusable) {
@@ -163,7 +283,8 @@ export const connectGraph = (frame, driver, options = {}) => {
         },
         relayout: () => {
             known = new Map();
-            draw();
+            waiting = new Set();
+            draw(true);
         },
         restyle: () => {
             colors = null;

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

@@ -0,0 +1,50 @@
+/** A note as the renderer draws it, placed. */
+export interface DrawnNode {
+    id: string;
+    label: string;
+    /** How large it is drawn, relative to the others: the note's `size`, or from how many links it has. */
+    size: number;
+    x: number;
+    y: number;
+}
+/** A link as the renderer draws it, between two notes the graph holds. */
+export interface DrawnLink {
+    label?: string | undefined;
+    source: string;
+    target: string;
+}
+/** What changed between two drawings of a graph, which a renderer applies in place. */
+export interface GraphChanges {
+    /** Links to draw that were not drawn. */
+    addLinks: DrawnLink[];
+    /** Notes to draw that were not drawn, placed. */
+    addNodes: DrawnNode[];
+    /** Notes still drawn whose name, size or place changed. */
+    changeNodes: DrawnNode[];
+    /** Links no longer drawn. */
+    removeLinks: DrawnLink[];
+    /** Notes no longer drawn, by `id`. */
+    removeNodes: string[];
+}
+/** A link's key: its two ends, which no `id` can contain both of by accident. */
+export declare const linkKey: (link: {
+    source: string;
+    target: string;
+}) => string;
+/** Whether a diff changed nothing. */
+export declare const isEmpty: (changes: GraphChanges) => boolean;
+/**
+ * What changed from one drawing to the next, matched by `id` and by a link's
+ * two ends.
+ *
+ * **Linear in the size of the graph and nothing more**, so a page can hand the
+ * frame a new array for every message on a busy feed and the renderer is told
+ * only what moved: ten thousand notes with one added is one note drawn.
+ */
+export declare const diffGraph: (before: {
+    links: ReadonlyMap<string, DrawnLink>;
+    nodes: ReadonlyMap<string, DrawnNode>;
+}, after: {
+    links: ReadonlyMap<string, DrawnLink>;
+    nodes: ReadonlyMap<string, DrawnNode>;
+}) => GraphChanges;

package/dist/connect-graph/diff.js

@@ -0,0 +1,48 @@
+export const linkKey = (link) => `${link.source}\u0000${link.target}`;
+export const isEmpty = (changes) => changes.addLinks.length === 0 &&
+    changes.addNodes.length === 0 &&
+    changes.changeNodes.length === 0 &&
+    changes.removeLinks.length === 0 &&
+    changes.removeNodes.length === 0;
+export const diffGraph = (before, after) => {
+    const changes = {
+        addLinks: [],
+        addNodes: [],
+        changeNodes: [],
+        removeLinks: [],
+        removeNodes: [],
+    };
+    for (const [id, node] of after.nodes) {
+        const was = before.nodes.get(id);
+        if (!was) {
+            changes.addNodes.push(node);
+        }
+        else if (was.label !== node.label ||
+            was.size !== node.size ||
+            was.x !== node.x ||
+            was.y !== node.y) {
+            changes.changeNodes.push(node);
+        }
+    }
+    for (const id of before.nodes.keys()) {
+        if (!after.nodes.has(id)) {
+            changes.removeNodes.push(id);
+        }
+    }
+    for (const [key, link] of after.links) {
+        const was = before.links.get(key);
+        if (!was) {
+            changes.addLinks.push(link);
+        }
+        else if (was.label !== link.label) {
+            changes.removeLinks.push(was);
+            changes.addLinks.push(link);
+        }
+    }
+    for (const [key, link] of before.links) {
+        if (!after.links.has(key)) {
+            changes.removeLinks.push(link);
+        }
+    }
+    return changes;
+};

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

@@ -3,6 +3,10 @@
  * where the frame is.
  */
 export interface GraphColors {
+    /** A signal meaning something to look at: `accent`. */
+    accent: string;
+    /** A signal meaning something went wrong: `danger`. */
+    danger: string;
     /** What the drawing is laid on, which faded notes are mixed toward: `surface-sunken`. */
     ground: string;
     /** The links: `border`. */
@@ -17,6 +21,12 @@ export interface GraphColors {
     primary: string;
     /** One color for each group, in the order of the groups' names: `series-1` and on. */
     series: string[];
+    /** A signal meaning something done: `success`. */
+    success: string;
+    /** A signal meaning something to know: `info`. */
+    info: string;
+    /** A signal meaning something to watch: `warning`. */
+    warning: string;
 }
 /**
  * The page's colors where the frame is, or `null` while they cannot be read.
@@ -48,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;
@@ -61,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;
 }
@@ -74,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.
@@ -86,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

@@ -1,12 +1,17 @@
 import { readColor } from '@fusion.dev/helix-core';
 const SERIES = 24;
 const TOKENS = {
+    accent: '--helix-color-accent',
+    danger: '--helix-color-danger',
     ground: '--helix-color-surface-sunken',
+    info: '--helix-color-info',
     ink: '--helix-color-foreground',
     line: '--helix-color-border',
     muted: '--helix-color-foreground-muted',
     overlay: '--helix-color-surface-overlay',
     primary: '--helix-color-primary',
+    success: '--helix-color-success',
+    warning: '--helix-color-warning',
 };
 export const graphColorsFrom = (element) => {
     if (typeof document === 'undefined') {
@@ -49,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
@@ -63,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,
@@ -89,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,
@@ -97,5 +119,6 @@ export const looksOf = (options) => {
             };
         },
         overlay: colors.overlay,
+        quiet: colors.muted,
     };
 };

package/dist/connect-graph/seed.js

@@ -23,9 +23,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) {

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

@@ -0,0 +1,34 @@
+import type { GraphPoint } from './seed.js';
+/**
+ * A shape the notes are fitted into once a layout settles, in a box `width`
+ * by `height`, as an SVG's `viewBox="0 0 width height"` gives one: an SVG
+ * path, whose holes are cut by the even-odd rule, or a test of whether a
+ * point in the box is inside.
+ */
+export type GraphStencil = {
+    height: number;
+    path: string;
+    width: number;
+} | {
+    height: number;
+    inside: (x: number, y: number) => boolean;
+    width: number;
+};
+/**
+ * `count` places spread evenly over the inside of a shape: a grid sized to
+ * the shape's area, each place shaken within its cell so no rows show, and
+ * the grid made finer until it holds enough.
+ */
+export declare const placesIn: (inside: (x: number, y: number) => boolean, width: number, height: number, count: number) => GraphPoint[];
+/**
+ * Places a layout put anywhere, moved into the stencil's shape and filling it
+ * evenly. **The notes keep their order**, left to right and, within each
+ * strip, top to bottom, so notes the layout put together land together, and
+ * each group takes a region of the shape.
+ *
+ * Centered where the layout was, and as large. The stencil's y points down,
+ * as an SVG's does, and the layout's up, as Sigma and cosmos.gl draw it.
+ * 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>;