@yurialvesbordin/graphium 0.0.0-stage → 2.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Graphium contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,113 @@
-# Temporary Holding Version
+# Graphium
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[![npm version](https://img.shields.io/npm/v/@yurialvesbordin/graphium.svg)](https://www.npmjs.com/package/@yurialvesbordin/graphium)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![TypeScript](https://img.shields.io/badge/built%20with-TypeScript-0074c1.svg)](http://www.typescriptlang.org/)
+[![WebGL2](https://img.shields.io/badge/WebGL2-enabled-ff69b4.svg)](https://developer.mozilla.org/en-US/docs/Web/API/WebGL_API)
+
+High-performance WebGL2 graph visualization with silk-smooth force physics, curved edges, node images, and a fluent API.
+
+![Graphium hero](docs/assets/hero.png)
+
+## Installation
+
+```bash
+npm install @yurialvesbordin/graphium
+```
+
+## Usage
+
+```ts
+import { Graphium } from '@yurialvesbordin/graphium';
+
+const graph = Graphium.create({
+  container: document.getElementById('graph-container'),
+  autoStart: true,
+  autoFit: true,
+  physics: { preset: 'silk' },
+  theme: { name: 'midnight' },
+});
+
+graph
+  .addNode('alice', { label: 'Alice' })
+  .addNode('bob',   { label: 'Bob'   })
+  .addNode('carol', { label: 'Carol' });
+
+graph.link('alice', 'bob').link('bob', 'carol').link('carol', 'alice');
+
+graph.fit(80);
+```
+
+## Showcase
+
+### Force-directed physics
+
+A 120 node clustered graph reorganizing itself after a disturbance. The solver
+combines repulsion, link springs, gravity, damping, and collision handling while
+spatial hashing keeps neighbor lookups near O(n). The graph sleeps automatically
+when it settles, dropping CPU usage to near zero.
+
+![Force physics](docs/assets/physics.gif)
+
+### Curved edges
+
+Edge curvature adjusted at runtime from straight to strongly curved in both
+directions. Curves are computed on the GPU, so styling thousands of edges costs
+no extra CPU. Positive values curve one way, negative values the other.
+
+![Curved edges](docs/assets/curved-edges.gif)
+
+### Built-in themes
+
+The four bundled themes (midnight, light, slate, sunset) switching at runtime.
+Each theme controls background, node palette, edge styling, labels, and the
+hover and selection rings. Custom themes merge over the current one, so you can
+override only what you need.
+
+![Themes](docs/assets/themes.gif)
+
+### Node images
+
+Toggling node images on and off. Any node can take an image (URL or canvas
+data URL) rendered inside the circle with cover fit. Images upload to the GPU
+through a texture atlas, keeping draw calls minimal.
+
+![Node images](docs/assets/node-images.gif)
+
+### Arrow heads
+
+Turning directed arrow heads on. Arrows follow the edge path, respect
+curvature, and scale with zoom.
+
+![Arrows](docs/assets/arrows.gif)
+
+### Tree layout
+
+A binary tree dataset settling under the same force solver. When hierarchical
+data needs cleaner separation, edge separation tuning untangles crossings, and
+any dataset type can be swapped at runtime.
+
+![Tree layout](docs/assets/tree-layout.gif)
+
+### Click to focus and inspect
+
+Clicking a node focuses the camera on it and opens the inspector with live
+degree, position, and velocity. Dragging works with momentum, the wheel zooms,
+and every interaction emits events you can subscribe to.
+
+![Interaction](docs/assets/interaction.gif)
+
+## Documentation
+
+Complete guides live in the docs directory:
+
+- Getting Started - installation, first graph, handles, cleanup
+- Physics Configuration - presets and fine-tuning the simulation
+- Theming Guide - built-in and custom themes
+- Events & Interaction - events, interaction, accessibility
+- Node Images - custom images as node backgrounds
+- Performance Tuning - optimization of rendering and physics
+
+## License
+
+MIT

package/dist/Graphium.d.ts

@@ -0,0 +1,156 @@
+/**
+ * Implements the main Graphium facade. The class wires the data model,
+ * physics engine, camera, renderer, label layer and pointer controller into
+ * one object, exposes a fluent chainable API with sensible defaults, and
+ * runs an on demand render loop that pauses completely while the simulation
+ * sleeps.
+ */
+import { Emitter } from './core/events.js';
+import { GraphEditor } from './core/GraphEditor.js';
+import { GraphModel } from './core/GraphModel.js';
+import { LinkHandle, NodeHandle } from './core/handles.js';
+import type { GraphData, GraphiumOptions, InteractionOptions, LinkId, LinkOptions, LinkSnapshot, NodeId, NodeOptions, NodeSnapshot, PhysicsOptions, PhysicsPresetName, StatsSnapshot, ThemeOptions, ThemeResolved } from './core/types.js';
+import { PhysicsEngine } from './physics/PhysicsEngine.js';
+import { Camera } from './render/Camera.js';
+import { LabelLayer } from './render/LabelLayer.js';
+import { Renderer } from './render/Renderer.js';
+import { TextureAtlas } from './render/TextureAtlas.js';
+export declare class Graphium {
+    readonly model: GraphModel;
+    readonly physics: PhysicsEngine;
+    readonly camera: Camera;
+    readonly renderer: Renderer;
+    readonly atlas: TextureAtlas;
+    readonly labels: LabelLayer;
+    readonly editor: GraphEditor;
+    readonly events: Emitter;
+    theme: ThemeResolved;
+    running: boolean;
+    destroyed: boolean;
+    private options;
+    private readonly loop;
+    private readonly selection;
+    private readonly focusController;
+    private readonly viewport;
+    private readonly binder;
+    constructor(options?: GraphiumOptions);
+    /** Creates a Graphium instance with the supplied configuration. */
+    static create(options?: GraphiumOptions): Graphium;
+    /** Subscribes to an event and returns an unsubscribe function. */
+    on<T = unknown>(type: string, listener: (payload: T) => void): () => void;
+    /** Subscribes to an event exactly once. */
+    once<T = unknown>(type: string, listener: (payload: T) => void): () => void;
+    /** Removes one listener, or every listener of a type. */
+    off<T = unknown>(type: string, listener?: (payload: T) => void): this;
+    /** Dispatches an event payload to the registered listeners. */
+    emit<T = unknown>(type: string, payload: T): this;
+    /** Adds one node and returns the graph for chaining. */
+    addNode(id: NodeId, options?: NodeOptions): this;
+    /** Adds many nodes in one call and returns the graph for chaining. */
+    addNodes(nodes: Array<NodeOptions & {
+        id: NodeId;
+    }>): this;
+    /** Links two nodes, reusing an existing link with the same auto id. */
+    link(source: NodeId, target: NodeId, options?: LinkOptions): this;
+    /** Returns a fluent handle when called with a single link id. */
+    link(id: LinkId): LinkHandle | null;
+    /** Adds many links in one call and returns the graph for chaining. */
+    addLinks(links: Array<LinkOptions & {
+        source: NodeId;
+        target: NodeId;
+    }>): this;
+    /** Returns a fluent handle for one node, or null when it is missing. */
+    node(id: NodeId): NodeHandle | null;
+    /** Returns a fluent handle for one link, or null when it is missing. */
+    linkById(id: LinkId): LinkHandle | null;
+    /** Replaces the entire graph with the supplied data payload. */
+    setData(data: GraphData): this;
+    /** Removes one node together with its links. */
+    removeNode(id: NodeId): boolean;
+    /** Removes one link by id. */
+    removeLink(id: LinkId): boolean;
+    /** Removes every node and link while keeping the current theme. */
+    clear(): this;
+    /** Returns a snapshot of one node or null when it does not exist. */
+    getNode(id: NodeId): NodeSnapshot | null;
+    /** Returns a snapshot of one link or null when it does not exist. */
+    getLink(id: LinkId): LinkSnapshot | null;
+    /** Returns the ids of every node currently in the graph. */
+    nodeIds(): NodeId[];
+    /** Returns the ids of every link currently in the graph. */
+    linkIds(): LinkId[];
+    /** Sets the node image and starts the asynchronous load. */
+    setNodeImage(id: NodeId | number, url: string | null, mode?: 'cover' | 'contain'): this;
+    /** Selects one node, optionally keeping the current selection. */
+    selectNode(id: NodeId | number, selected?: boolean, additive?: boolean): this;
+    /** Selects one link, optionally keeping the current selection. */
+    selectLink(id: LinkId | number, selected?: boolean, additive?: boolean): this;
+    /** Clears the selection of every node and link. */
+    clearSelection(): this;
+    /** Returns the ids of every selected node. */
+    selectedNodes(): NodeId[];
+    /** Returns the ids of every selected link. */
+    selectedLinks(): LinkId[];
+    /** Dims every node and link that is not adjacent to the focus node. */
+    focus(id: NodeId | number): this;
+    /** Removes all dimming applied by focus. */
+    unfocus(): this;
+    /** Merges theme values, optionally starting from a built in theme name. */
+    setTheme(theme: ThemeOptions & {
+        name?: string;
+    }): this;
+    /** Updates physics options live and wakes the simulation. */
+    setPhysics(options: PhysicsOptions): this;
+    /** Applies a named physics preset with optional overrides. */
+    usePreset(name: PhysicsPresetName, overrides?: PhysicsOptions): this;
+    /** Updates interaction options on the live pointer controller. */
+    setInteraction(options: InteractionOptions): this;
+    /** Restarts the simulation and returns the graph for chaining. */
+    reboot(): this;
+    /** Scales the view so the whole graph fits with padding. */
+    fit(padding?: number): this;
+    /** Centers the view on a world point. */
+    centerOn(x: number, y: number): this;
+    /** Multiplies the current zoom level. */
+    zoomBy(factor: number): this;
+    /** Sets an absolute zoom level. */
+    zoomTo(zoom: number): this;
+    /** Resizes the renderer to the canvas client size. */
+    resize(): this;
+    /** Advances physics and renders once, returning the kinetic energy. */
+    step(dt?: number): number;
+    /** Renders a frame immediately without stepping the simulation. */
+    render(): this;
+    /** Requests a render on the next scheduled frame. */
+    requestRender(): this;
+    /** Marks the view dirty and guarantees a scheduled frame. */
+    private invalidate;
+    /** Starts the run loop and returns the graph for chaining. */
+    start(): this;
+    /** Stops the run loop and returns the graph for chaining. */
+    stop(): this;
+    /** Resolves when every requested node image finished loading. */
+    loadImages(): Promise<void>;
+    /** Finds the link index closest to a world position within a radius. */
+    pickLinkAt(worldX: number, worldY: number, hitRadius?: number): number;
+    /** Returns the world position under a screen position. */
+    screenToWorld(screenX: number, screenY: number): {
+        x: number;
+        y: number;
+    };
+    /** Returns a performance statistics snapshot for dashboards. */
+    stats(): StatsSnapshot;
+    /** Captures the current canvas contents as a PNG data URL. */
+    screenshot(): string;
+    /** Exports the current graph as a plain JSON friendly object. */
+    toJSON(): GraphData;
+    /** Releases every resource owned by the instance. */
+    destroy(): void;
+    /** Returns the number of nodes in the graph. */
+    get nodeCount(): number;
+    /** Returns the number of links in the graph. */
+    get linkCount(): number;
+    /** Reports whether the physics simulation is currently asleep. */
+    get sleeping(): boolean;
+}
+//# sourceMappingURL=Graphium.d.ts.map

package/dist/Graphium.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Graphium.d.ts","sourceRoot":"","sources":["../src/Graphium.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,kBAAkB,CAAC;AAE3C,OAAO,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AACpD,OAAO,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAClD,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAI3D,OAAO,KAAK,EACV,SAAS,EACT,eAAe,EACf,kBAAkB,EAClB,MAAM,EACN,WAAW,EACX,YAAY,EACZ,MAAM,EACN,WAAW,EACX,YAAY,EACZ,cAAc,EACd,iBAAiB,EACjB,aAAa,EACb,YAAY,EACZ,aAAa,EACd,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EAAE,aAAa,EAAE,MAAM,4BAA4B,CAAC;AAC3D,OAAO,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAC5C,OAAO,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AAEpD,OAAO,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AAChD,OAAO,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AAGxD,qBAAa,QAAQ;IACnB,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAC;IAC3B,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAC;IAChC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;IAC5B,QAAQ,CAAC,KAAK,EAAE,YAAY,CAAC;IAC7B,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC;IAC5B,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;IAC7B,QAAQ,CAAC,MAAM,UAAiB;IAChC,KAAK,EAAE,aAAa,CAAC;IACrB,OAAO,UAAS;IAChB,SAAS,UAAS;IAElB,OAAO,CAAC,OAAO,CAAkB;IACjC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAa;IAClC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAsB;IAChD,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAkB;IAClD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAqB;IAC9C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAoB;gBAE/B,OAAO,GAAE,eAAoB;IAsEzC,mEAAmE;IACnE,MAAM,CAAC,MAAM,CAAC,OAAO,GAAE,eAAoB,GAAG,QAAQ;IAItD,kEAAkE;IAClE,EAAE,CAAC,CAAC,GAAG,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,OAAO,EAAE,CAAC,KAAK,IAAI,GAAG,MAAM,IAAI;IAIzE,2CAA2C;IAC3C,IAAI,CAAC,CAAC,GAAG,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,OAAO,EAAE,CAAC,KAAK,IAAI,GAAG,MAAM,IAAI;IAI3E,yDAAyD;IACzD,GAAG,CAAC,CAAC,GAAG,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,KAAK,IAAI,GAAG,IAAI;IAKrE,+DAA+D;IAC/D,IAAI,CAAC,CAAC,GAAG,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,GAAG,IAAI;IAKjD,wDAAwD;IACxD,OAAO,CAAC,EAAE,EAAE,MAAM,EAAE,OAAO,GAAE,WAAgB,GAAG,IAAI;IAKpD,sEAAsE;IACtE,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC,WAAW,GAAG;QAAE,EAAE,EAAE,MAAM,CAAA;KAAE,CAAC,GAAG,IAAI;IAK1D,uEAAuE;IACvE,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,IAAI;IACjE,iEAAiE;IACjE,IAAI,CAAC,EAAE,EAAE,MAAM,GAAG,UAAU,GAAG,IAAI;IASnC,sEAAsE;IACtE,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC,WAAW,GAAG;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC,GAAG,IAAI;IAK9E,wEAAwE;IACxE,IAAI,CAAC,EAAE,EAAE,MAAM,GAAG,UAAU,GAAG,IAAI;IAKnC,wEAAwE;IACxE,QAAQ,CAAC,EAAE,EAAE,MAAM,GAAG,UAAU,GAAG,IAAI;IAKvC,gEAAgE;IAChE,OAAO,CAAC,IAAI,EAAE,SAAS,GAAG,IAAI;IAK9B,gDAAgD;IAChD,UAAU,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO;IAI/B,8BAA8B;IAC9B,UAAU,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO;IAI/B,mEAAmE;IACnE,KAAK,IAAI,IAAI;IAKb,qEAAqE;IACrE,OAAO,CAAC,EAAE,EAAE,MAAM,GAAG,YAAY,GAAG,IAAI;IAKxC,qEAAqE;IACrE,OAAO,CAAC,EAAE,EAAE,MAAM,GAAG,YAAY,GAAG,IAAI;IAKxC,4DAA4D;IAC5D,OAAO,IAAI,MAAM,EAAE;IAQnB,4DAA4D;IAC5D,OAAO,IAAI,MAAM,EAAE;IAQnB,4DAA4D;IAC5D,YAAY,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI,EAAE,IAAI,GAAE,OAAO,GAAG,SAAmB,GAAG,IAAI;IAKhG,kEAAkE;IAClE,UAAU,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,EAAE,QAAQ,GAAE,OAAc,EAAE,QAAQ,UAAQ,GAAG,IAAI;IAKjF,kEAAkE;IAClE,UAAU,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,EAAE,QAAQ,GAAE,OAAc,EAAE,QAAQ,UAAQ,GAAG,IAAI;IAKjF,mDAAmD;IACnD,cAAc,IAAI,IAAI;IAKtB,8CAA8C;IAC9C,aAAa,IAAI,MAAM,EAAE;IAIzB,8CAA8C;IAC9C,aAAa,IAAI,MAAM,EAAE;IAIzB,uEAAuE;IACvE,KAAK,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI;IAKhC,4CAA4C;IAC5C,OAAO,IAAI,IAAI;IAKf,2EAA2E;IAC3E,QAAQ,CAAC,KAAK,EAAE,YAAY,GAAG;QAAE,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI;IAevD,6DAA6D;IAC7D,UAAU,CAAC,OAAO,EAAE,cAAc,GAAG,IAAI;IAMzC,8DAA8D;IAC9D,SAAS,CAAC,IAAI,EAAE,iBAAiB,EAAE,SAAS,GAAE,cAAmB,GAAG,IAAI;IAMxE,kEAAkE;IAClE,cAAc,CAAC,OAAO,EAAE,kBAAkB,GAAG,IAAI;IAKjD,kEAAkE;IAClE,MAAM,IAAI,IAAI;IAKd,4DAA4D;IAC5D,GAAG,CAAC,OAAO,SAAK,GAAG,IAAI;IAKvB,yCAAyC;IACzC,QAAQ,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,IAAI;IAKpC,yCAAyC;IACzC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAK5B,mCAAmC;IACnC,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAK1B,sDAAsD;IACtD,MAAM,IAAI,IAAI;IAKd,uEAAuE;IACvE,IAAI,CAAC,EAAE,SAAS,GAAG,MAAM;IAIzB,mEAAmE;IACnE,MAAM,IAAI,IAAI;IAKd,qDAAqD;IACrD,aAAa,IAAI,IAAI;IAKrB,6DAA6D;IAC7D,OAAO,CAAC,UAAU;IAIlB,8DAA8D;IAC9D,KAAK,IAAI,IAAI;IAWb,6DAA6D;IAC7D,IAAI,IAAI,IAAI;IASZ,iEAAiE;IACjE,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAI3B,wEAAwE;IACxE,UAAU,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,SAAI,GAAG,MAAM;IAIjE,0DAA0D;IAC1D,aAAa,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG;QAAE,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAA;KAAE;IAIzE,gEAAgE;IAChE,KAAK,IAAI,aAAa;IAYtB,8DAA8D;IAC9D,UAAU,IAAI,MAAM;IAKpB,iEAAiE;IACjE,MAAM,IAAI,SAAS;IAInB,qDAAqD;IACrD,OAAO,IAAI,IAAI;IAef,gDAAgD;IAChD,IAAI,SAAS,IAAI,MAAM,CAEtB;IAED,gDAAgD;IAChD,IAAI,SAAS,IAAI,MAAM,CAEtB;IAED,kEAAkE;IAClE,IAAI,QAAQ,IAAI,OAAO,CAEtB;CACF"}