@fusion.dev/helix-graph 0.119.0 → 0.121.0

package/README.md

@@ -1,6 +1,6 @@
 # @fusion.dev/helix-graph
 
-Connects the Helix `Graph` frame to whatever draws the graph: Sigma.js, or a
+Connects the Helix `Graph` frame to whatever draws the graph: Sigma.js, cosmos.gl, or a
 driver of your own, colored from your tokens.
 
 ```sh
@@ -55,28 +55,193 @@ connection.disconnect()
   changes.
 - Answers the frame's pan and zoom buttons and keys, and tells the renderer which
   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.
+
+## Live graphs
+
+**Hand the frame new arrays as often as the graph changes.** The connection
+compares them with what is drawn, by each note's `id` and each link's two ends,
+and the renderer is told only what was added, taken away, renamed or moved. New
+notes grow in and are laid out with the rest held still, and the frame stays
+`:state(ready)` throughout.
+
+```js
+socket.addEventListener('message', ({ data }) => {
+  const note = JSON.parse(data)
+  frame.nodes = [...frame.nodes, note]
+  frame.links = [...frame.links, { source: note.id, target: note.parent }]
+})
+```
+
+**`frame.signal(from, to, { tone })` shows something passing between two
+notes**: a message, a request, a payment. It is drawn as a pulse of light
+traveling from one to the other, turning from the first note's color to the
+second's, or in the tone's color where it has one, over the graph and without
+redrawing it, so a busy feed costs a dot each. A reader who asks for less motion
+sees the link lit for a moment instead.
+
+```js
+frame.signal('Checkout', 'Payments', { tone: 'success' })
+frame.signal('Payments', 'Fraud review', { tone: 'danger' })
+```
+
+A signal is drawn and never said: a screen reader does not hear it. Where what
+passed matters to a reader, say it in the page's own words as well.
+
+## How notes look
+
+Each note can say how it is drawn, in the words Helix's other components use:
+
+| Field | Values | What it does |
+|---|---|---|
+| `shape` | `circle`, `square`, `diamond`, `ring` | What kind of note it is at a glance |
+| `emphasis` | `solid`, `outlined`, `subtle` | Filled, a ring with the ground showing through, or a tinted fill with a ring |
+| `material` | `glass`, `frosted` | A shaded sphere with a highlight and a lit rim, or a milky body with a soft fall of light |
+| `tone` | `primary`, `accent`, `info`, `success`, `warning`, `danger`, `neutral` | What it means, which colors it over its group |
+
+```js
+frame.nodes = [
+  { id: 'Roadmap', group: 'Product', shape: 'square' },
+  { id: 'Outage 14', group: 'Support', tone: 'danger', emphasis: 'outlined' },
+]
+```
+
+`sigmaDriver(sigma, { material, shape, emphasis })` sets what a note is drawn as
+where it does not say. The selected note keeps its own color and is told apart by
+a ring and a glow in that color.
+
+**A note without a `size` is as large as it is connected**, so hubs read at a
+glance. Links are tinted by the note they leave, the selected note's and the
+hovered note's in their color, and choosing a note in the list frames it with
+its neighbors.
+
+**Notes are named on hover**, and the selected note and its neighbors where
+there is room, each name ringed in the ground's color so it reads over the
+links. Each group's name is drawn over its notes, which is how a reader finds
+their way. `labels: 'hubs'` names the busiest notes at rest as well, quietly,
+and `labels: 'all'` every note where its name does not cover another.
+
+## Large graphs
+
+**Past fifty thousand notes, draw with cosmos.gl**, which lays the graph out
+and draws it on the GPU. The frame, the list, selection and signals are the
+same; only the driver changes:
+
+```sh
+bun add @cosmos.gl/graph
+```
+
+```js
+import { Graph } from '@cosmos.gl/graph'
+import { connectGraph } from '@fusion.dev/helix-graph'
+import { cosmosDriver } from '@fusion.dev/helix-graph/cosmos'
+
+const box = document.getElementById('drawing')
+const graph = new Graph(box, { attribution: '', enableSimulation: true, scalePointsOnZoom: false })
+connectGraph(frame, cosmosDriver(graph, box))
+```
+
+cosmos.gl draws notes with its own shaders, so a note's `shape` is honored and
+its `material` and `emphasis` are not. Each group is given a place of its own
+and its notes are drawn toward it, so twenty thousand notes in twelve groups
+come apart into twelve regions. The view follows the layout as it opens out,
+until the reader moves it. Zoomed out, a note is a fine point and a leaf is
+drawn partly clear, so a group reads as a field of points with its hubs
+standing out; notes grow as the reader zooms in.
+
+**cosmos.gl's own start reports a `ResizeObserver loop` error**, which is
+harmless and shows in the console: it observes its canvas from inside
+luma.gl's resize callback. Make the GPU device yourself and hand it over a
+frame after its canvas is measured, and cosmos.gl starts outside any callback:
+
+```js
+import { luma } from '@luma.gl/core'
+import { webgl2Adapter } from '@luma.gl/webgl'
+
+const canvas = Object.assign(document.createElement('canvas'), {
+  style: 'width:100%;height:100%',
+})
+box.append(canvas)
+const device = luma
+  .createDevice({
+    adapters: [webgl2Adapter],
+    createCanvasContext: { autoResize: true, canvas, useDevicePixels: true },
+    type: 'webgl',
+    webgl: { antialias: false },
+  })
+  .then(async (made) => {
+    await made.canvasContext?.initialized
+    await new Promise((done) => requestAnimationFrame(done))
+    return made
+  })
+const graph = new Graph(box, { attribution: '', enableSimulation: true }, device)
+```
+
+Use the `@luma.gl` version `@cosmos.gl/graph` depends on, since two versions
+on one page throw, and destroy the device after the graph.
+
+**The driver is for `@cosmos.gl/graph`, which is MIT.** Cosmograph, the
+product built on it, is licensed for noncommercial use only.
+
+## Shapes
+
+**`stencil` draws the notes in a shape**, such as a brain or a country's
+outline. Pass an SVG path and the box it is drawn in, as the SVG's `viewBox`
+gives it:
+
+```js
+connectGraph(frame, driver, {
+  stencil: { path: brain.getAttribute('d'), width: 220, height: 170 },
+})
+```
+
+No layout runs, so the shape is there from the first frame. Each group takes
+a region of the shape, each note sits by the hub it links to, and the notes
+fill the shape evenly, with borders between regions that curve. Holes are cut
+by the even-odd rule, which is how the grooves of a brain show. Only a graph
+with no places of its own is shaped; a note added later is placed by the
+layout beside its neighbors. `stencil` also takes `inside(x, y)`, a test of
+whether a point in the box is in the shape, in place of `path`, and
+`fitToStencil` fits places a page has into one.
 
 ## What it exports
 
 | Import | What |
 |---|---|
-| `@fusion.dev/helix-graph` | `connectGraph`, `graphColorsFrom`, `seedPositions`, and the `GraphDriver` type |
+| `@fusion.dev/helix-graph` | `connectGraph`, `diffGraph`, `fitToStencil`, `graphColorsFrom`, `seedPositions`, and the `GraphDriver`, `GraphChanges` and `GraphStencil` types |
 | `@fusion.dev/helix-graph/sigma` | `sigmaDriver(sigma, options)` |
+| `@fusion.dev/helix-graph/cosmos` | `cosmosDriver(graph, box, options)` |
 
-**Neither Sigma nor graphology is a dependency.** The driver types the renderer
-by the calls it makes on it, so a page brings whichever version it has. A spec
-holds those shapes to the real classes, so a renamed method fails a typecheck
-here rather than a page.
+**Sigma and cosmos.gl 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
+whichever version it has, and a spec holds those shapes to the real classes,
+so a renamed method fails a typecheck here before it reaches a page. `@fusion.dev/helix-graph/sigma` imports
+Sigma's rendering module for the program that draws the notes, which is why
+Sigma 3 is a peer dependency.
 
 | `connectGraph` option | Default | What else it takes |
 |---|---|---|
 | `center` | `true` | `false` leaves the view where it is when a note is chosen in the list |
+| `stencil` | none | A shape to draw the notes in: `{ path, width, height }` or `{ inside, width, height }` |
 
 | `sigmaDriver` option | Default | What else it takes |
 |---|---|---|
 | `layout` | none | A function that makes a layout for the graph, such as ForceAtlas2's worker |
+| `material` | flat | `glass` or `frosted`, for every note that does not say |
+| `shape` | `circle` | `square`, `diamond` or `ring`, for every note that does not say |
+| `emphasis` | `solid` | `outlined` or `subtle`, for every note that does not say |
+| `labels` | `'hover'` | `'hubs'` or `'all'`: which notes are named at rest |
+| `groupLabels` | `true` | `false` leaves each group unnamed |
 | `layoutLimit` | `10000` | The longest a layout runs, in milliseconds, about where 10,000 notes settle |
 
+| `cosmosDriver` option | Default | What else it takes |
+|---|---|---|
+| `shape` | `circle` | `square` or `diamond`, for every note that does not say |
+| `groupLabels` | `true` | `false` leaves each group unnamed |
+| `layoutLimit` | `15000` | The longest a layout runs, in milliseconds |
+| `spaceSize` | `4096` | The size of cosmos.gl's space, as its own `spaceSize` says |
+
 ## Working on it
 
 ```sh

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

@@ -0,0 +1,18 @@
+import type { GraphPoint, SeedLink } from './seed.js';
+/** A note as the arrangement reads it: its group, if it has one. */
+export interface ArrangedNode {
+    group?: string | undefined;
+    id: string;
+}
+/**
+ * Places for every note from the graph's structure alone, with no layout to
+ * wait for: **each group around a circle, each hub in its group, and each
+ * note beside the hub it hangs from**, the most connected note it links to
+ * in its group.
+ *
+ * Not a layout to look at, since fans overlap and nothing is pushed apart:
+ * it is where a stencil starts, which reads only which notes are near which,
+ * so the shape is drawn from the first frame with each group a region and
+ * each hub's notes around it.
+ */
+export declare const arrangeByGroup: (nodes: readonly ArrangedNode[], links: readonly SeedLink[]) => Map<string, GraphPoint>;

package/dist/connect-graph/arrange.js

@@ -0,0 +1,92 @@
+const TURN = Math.PI * (3 - Math.sqrt(5));
+const spiral = (at, spacing) => ({
+    x: Math.cos(at * TURN) * Math.sqrt(at + 0.5) * spacing,
+    y: Math.sin(at * TURN) * Math.sqrt(at + 0.5) * spacing,
+});
+export const arrangeByGroup = (nodes, links) => {
+    const groupOf = new Map(nodes.map((node) => [node.id, node.group ?? '']));
+    const degree = new Map();
+    const neighbors = new Map();
+    const add = (from, to) => {
+        degree.set(from, (degree.get(from) ?? 0) + 1);
+        const list = neighbors.get(from);
+        if (list) {
+            list.push(to);
+        }
+        else {
+            neighbors.set(from, [to]);
+        }
+    };
+    for (const { source, target } of links) {
+        if (groupOf.has(source) && groupOf.has(target)) {
+            add(source, target);
+            add(target, source);
+        }
+    }
+    const rank = (id) => degree.get(id) ?? 0;
+    const above = (one, other) => rank(one) > rank(other) || (rank(one) === rank(other) && one < other);
+    const parent = new Map();
+    for (const { id } of nodes) {
+        let best = id;
+        for (const near of neighbors.get(id) ?? []) {
+            if (groupOf.get(near) === groupOf.get(id) && above(near, best)) {
+                best = near;
+            }
+        }
+        parent.set(id, best);
+    }
+    const hubOf = (id) => {
+        let at = id;
+        while (parent.get(at) !== at) {
+            at = parent.get(at);
+        }
+        let step = id;
+        while (step !== at) {
+            const next = parent.get(step);
+            parent.set(step, at);
+            step = next;
+        }
+        return at;
+    };
+    const groups = new Map();
+    for (const { id } of nodes) {
+        const group = groupOf.get(id);
+        const hubs = groups.get(group) ?? new Map();
+        groups.set(group, hubs);
+        const hub = hubOf(id);
+        const members = hubs.get(hub) ?? [];
+        hubs.set(hub, members);
+        if (hub !== id) {
+            members.push(id);
+        }
+    }
+    const radiusOf = (hubs) => {
+        let count = 0;
+        for (const members of hubs.values()) {
+            count += members.length + 1;
+        }
+        return Math.sqrt(count) * 1.5;
+    };
+    const radii = [...groups.values()].map(radiusOf);
+    const widest = Math.max(0, ...radii);
+    const ring = groups.size > 1 ? (widest * 1.2) / Math.sin(Math.PI / groups.size) : 0;
+    const positions = new Map();
+    [...groups.values()].forEach((hubs, at) => {
+        const turn = (at / groups.size) * Math.PI * 2;
+        const middle = { x: Math.cos(turn) * ring, y: Math.sin(turn) * ring };
+        const ordered = [...hubs].sort(([, one], [, other]) => other.length - one.length);
+        const mean = ordered.reduce((sum, [, members]) => sum + members.length + 1, 0) / ordered.length;
+        ordered.forEach(([hub, members], place) => {
+            const spot = spiral(place, Math.sqrt(mean) * 2);
+            const center = { x: middle.x + spot.x, y: middle.y + spot.y };
+            positions.set(hub, center);
+            members
+                .sort((one, other) => rank(other) - rank(one))
+                .forEach((member, step) => {
+                const off = spiral(step + 1, 1);
+                positions.set(member, { x: center.x + off.x, y: center.y + off.y });
+            });
+        });
+    });
+    return positions;
+};

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

@@ -1,21 +1,9 @@
 import { type ViewportGestureMode } from '@fusion.dev/helix-core';
+import { type DrawnLink, type DrawnNode, type GraphChanges } from './diff.js';
 import { type GraphLooks } from './looks.js';
 import { type GraphPoint } from './seed.js';
-/** 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 1. */
-    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;
-}
+import { type GraphStencil } from './stencil.js';
+export type { DrawnLink, DrawnNode, GraphChanges } from './diff.js';
 /**
  * What a renderer has to answer for the frame to drive it, and nothing that is
  * the same for every renderer: that is the connector's.
@@ -34,6 +22,25 @@ export interface GraphDriver {
         links: DrawnLink[];
         nodes: DrawnNode[];
     }): void;
+    /**
+     * Applies what changed since the last drawing, in place: what to add, what
+     * to take away and which notes moved or were renamed. `animate` says
+     * whether the reader may watch it happen. Without one, every change is a
+     * whole `draw`, which is right for a graph that changes now and then and
+     * wasteful for one that changes on every message.
+     */
+    update?(changes: GraphChanges, animate: boolean): void;
+    /**
+     * Draws something passing from one note to another, traveling the way it
+     * went and arriving with a pulse, or, where `animate` is false, the link
+     * between them lit for a moment. It leaves in `colors.from` and arrives in
+     * `colors.to`, which are one color where the signal has a tone. `colors` is
+     * undefined while the page's colors cannot be read.
+     */
+    signal?(from: string, to: string, colors: {
+        from: string;
+        to: string;
+    } | undefined, animate: boolean): void;
     /**
      * How each note and link is drawn from now on, asked one at a time as the
      * renderer draws them: a selection or a theme changed.
@@ -45,6 +52,11 @@ export interface GraphDriver {
     zoomBy(direction: 1 | -1, animate: boolean): void;
     /** Brings a note into the middle of the view, where the renderer can. */
     center?(id: string, animate: boolean): void;
+    /**
+     * Frames a set of notes, the selected one and its neighbors, in the middle
+     * of the view at a zoom that holds them all, where the renderer can.
+     */
+    fit?(ids: readonly string[], animate: boolean): void;
     /** Calls `press` with a note's `id` when the reader presses it in the drawing. Returns what stops listening. */
     onPress?(press: (id: string) => void): () => void;
     /**
@@ -63,9 +75,26 @@ export interface GraphDriver {
     gestures?(mode: ViewportGestureMode): void;
     /** The element the renderer made focusable, which the connector takes out of the tab order. */
     focusTarget?(): HTMLElement | null;
+    /**
+     * The graph's groups, each named over its notes, which is how a reader
+     * finds their way while notes are named only on hover. `faded` while a note
+     * outside the group is selected.
+     */
+    groups?(groups: readonly GraphGroup[]): void;
     /** Removes whatever the driver added to the renderer or the page, when the connection ends. */
     stop?(): void;
 }
+/** One group of notes, as the renderer names it over them. */
+export interface GraphGroup {
+    /** The group's color, which its name is drawn in. */
+    color: string;
+    /** Whether a note outside the group is selected, which steps its name back. */
+    faded: boolean;
+    /** The notes in the group, by `id`. */
+    ids: readonly string[];
+    /** The group's name, as the notes give it. */
+    name: string;
+}
 /** How a connection behaves where the page does not say. */
 export interface ConnectGraphOptions {
     /**
@@ -74,6 +103,14 @@ export interface ConnectGraphOptions {
      * reader is already looking at it.
      */
     center?: boolean | undefined;
+    /**
+     * A shape the notes are drawn in, such as a brain or a country's outline:
+     * an SVG path and the box it is drawn in. **No layout runs**: each group
+     * takes a region of the shape and each note sits by the hub it links to,
+     * from the first frame. Only a graph with no places of its own is shaped;
+     * a note added later is placed by the layout beside its neighbors.
+     */
+    stencil?: GraphStencil | undefined;
 }
 /** A connection, which is ended rather than left to leak. */
 export interface GraphConnection {
@@ -96,7 +133,11 @@ export interface GraphConnection {
  * connection draws the frame's `nodes` and `links`, lays out the notes that
  * have no position and says where it put them in `helix-graph-layout`, answers
  * the frame's pan and zoom, keeps the selection the same in the list and the
- * drawing, colors the graph from the page's tokens, and tells the renderer
- * which gestures it may take.
+ * drawing, colors the graph from the page's tokens, tells the renderer which
+ * gestures it may take, and draws the frame's `signal()`s.
+ *
+ * **A page changes the graph by handing the frame new arrays**, as often as
+ * it likes: the connection compares them with what is drawn and the renderer
+ * is told only what changed.
  */
 export declare const connectGraph: (frame: HTMLElement, driver: GraphDriver, options?: ConnectGraphOptions) => GraphConnection;