plebeiangraphlibrary 2.1.3 → 2.2.1

package/Build/Core/Graph.d.ts

@@ -2,17 +2,16 @@ import { default as Line } from '../HelperClasses/Line';
 import { default as Point } from '../HelperClasses/Point';
 import { default as _Node } from './_Node';
 import { default as Edge } from './Edge';
-interface Graph {
-    nodes: Map<number, _Node>;
-    edges: Map<number, Edge>;
-}
 /**
  * The main graph object: contains nodes and edges that get modified with different
  * operations (layout, clustering, etc.).
  */
 declare class Graph {
+    nodes: Map<number, _Node>;
+    edges: Map<number, Edge>;
+    /** Next edge ID for add_edge; avoids collisions when edges are removed. */
+    private _nextEdgeId;
     /**
-     *
      * Construct a graph object (no initializing)
      *
      * @param nodes - Map of all the nodes associated with the graph
@@ -25,20 +24,21 @@ declare class Graph {
     printData(): void;
     /**
      * Initializes the graph and constructs the node adjacency list.
+     * Async to avoid blocking the main thread on large graphs.
      */
     initialize(): Promise<void>;
     /**
-     *
-     * This is the official create method to make a graph based on a set of nodes and edges
-     * It also auto-initializes the graph and sets all the adjacency lists in memory.
+     * Official create method to make a graph based on a set of nodes and edges.
+     * Auto-initializes the graph and sets all adjacency lists in memory.
      *
      * @param nodes - map of nodes
      * @param edges - map of edges
-     * @returns
+     * @returns initialized graph
      */
     static create(nodes: Map<number, _Node>, edges: Map<number, Edge>): Promise<Graph>;
     /**
-     * Constructs the adjacency associated with the graph
+     * Constructs the adjacency list representation for the graph.
+     * Async to allow yielding on large graphs and avoid hanging the browser.
      */
     constructAdjacencyList(): Promise<void>;
     /**
@@ -92,6 +92,8 @@ declare class Graph {
     };
     /**
      * Get the position of the nodes in the graph.
+     * Nodes without a defined `data.pos` are skipped.
+     *
      * @returns The position map (node ID to Point)
      */
     get_position_map(): Map<number, Point>;

package/Build/Drawing/GraphDrawer.d.ts

@@ -1,5 +1,6 @@
 import { OrbitControls } from 'three/examples/jsm/controls/OrbitControls';
 import { default as Graph } from '../Core/Graph';
+import { InteractionLayer, InteractionOptions } from './InteractionLayer';
 import * as THREE from "three";
 interface GraphDrawer3d {
     canvas: HTMLCanvasElement;
@@ -13,6 +14,7 @@ interface GraphDrawer3d {
     camera: THREE.PerspectiveCamera;
     scene: THREE.Scene;
     graphs: Map<number, Graph>;
+    interactionLayer?: InteractionLayer;
 }
 /**
  * This is the main graph drawer class
@@ -62,6 +64,23 @@ declare class GraphDrawer3d {
      * Remember to do this since this is a common are for bugs to occur
      */
     rendercall(): void;
+    /**
+     * Enable opt-in interaction: node and edge picking via click/hover, and optional drag-to-reposition.
+     * Callbacks receive graph details (node data, neighbours, edge endpoints).
+     *
+     * @param options - Interaction options. Must include `graph`. Optional:
+     *   - `onNodeClick`, `onEdgeClick` — click callbacks
+     *   - `onNodeHover`, `onEdgeHover` — hover callbacks (receive `null` when leaving)
+     *   - `hoverEnabled` — default true; set false to disable hover
+     *   - `enableNodeDrag` — enable drag-to-reposition (use with mutable vertices/edges)
+     *   - `onNodeDrag(nodeId, newPosition)` — called each pointer move while dragging
+     *   - `controls` — OrbitControls to disable during drag (auto-passed if omitted)
+     */
+    enableInteraction(options: InteractionOptions): void;
+    /**
+     * Disable interaction and remove event listeners.
+     */
+    disableInteraction(): void;
 }
 export { GraphDrawer3d };
 declare const _default: {

package/Build/Drawing/InteractionLayer.d.ts

@@ -0,0 +1,76 @@
+import { OrbitControls } from 'three/examples/jsm/controls/OrbitControls';
+import { default as Graph } from '../Core/Graph';
+import { default as Point, PointLike } from '../HelperClasses/Point';
+/**
+ * Opt-in interaction layer for PGL: node and edge picking via Three.js Raycaster.
+ * Callbacks receive graph details (node data, neighbours, edge endpoints).
+ * 100% opt-in — no interaction unless enableInteraction() is called.
+ */
+import * as THREE from "three";
+/** Details passed to node click/hover callbacks */
+export interface NodePickDetails {
+    nodeId: number;
+    data: unknown;
+    neighbours: number[];
+    position?: Point;
+}
+/** Details passed to edge click/hover callbacks */
+export interface EdgePickDetails {
+    edgeId: number;
+    start: number;
+    end: number;
+    data: unknown;
+}
+/**
+ * Options for GraphDrawer3d.enableInteraction.
+ * Requires `graph`; all callbacks are optional.
+ */
+export interface InteractionOptions {
+    /** Graph used to look up node/edge details for callbacks. */
+    graph: Graph;
+    /** Fired when a node is clicked. */
+    onNodeClick?: (details: NodePickDetails) => void;
+    /** Fired when an edge is clicked. */
+    onEdgeClick?: (details: EdgePickDetails) => void;
+    /** Fired when pointer enters/leaves a node. Receives `null` when leaving. */
+    onNodeHover?: (details: NodePickDetails | null) => void;
+    /** Fired when pointer enters/leaves an edge. Receives `null` when leaving. */
+    onEdgeHover?: (details: EdgePickDetails | null) => void;
+    /** Default true. Set false to disable hover callbacks. */
+    hoverEnabled?: boolean;
+    /** Enable drag-to-reposition for nodes (use with box/instanced vertices). Disables OrbitControls during drag. */
+    enableNodeDrag?: boolean;
+    /** Called each pointer move while dragging. Update graph position and call updatePositions()/updateEdges() for mutable geometry. */
+    onNodeDrag?: (nodeId: number, newPosition: PointLike) => void;
+    /** OrbitControls to disable during drag (prevents camera orbit while moving nodes). Auto-passed by GraphDrawer if omitted. */
+    controls?: OrbitControls;
+}
+export declare class InteractionLayer {
+    private scene;
+    private camera;
+    private domElement;
+    private graph;
+    private options;
+    private raycaster;
+    private mouse;
+    private hoverEnabled;
+    private lastHoverNodeId;
+    private lastHoverEdgeId;
+    private dragNodeId;
+    private wasDragging;
+    private controls;
+    private boundOnClick;
+    private boundOnPointerMove;
+    private boundOnPointerDown;
+    private boundOnPointerUp;
+    constructor(scene: THREE.Scene, camera: THREE.Camera, domElement: HTMLElement, graph: Graph, options: InteractionOptions);
+    dispose(): void;
+    private getMouseNDC;
+    private pick;
+    private onClick;
+    private onPointerDown;
+    private onPointerUp;
+    private getDragPosition;
+    private onPointerMove;
+    private fireHoverCallbacks;
+}

package/Build/index.d.ts

@@ -18,6 +18,7 @@
  * - {@link Graph} — main graph class (nodes + edges)
  * - {@link createKamadaKawai3D} / {@link createStressSGD3D} — layout simulations
  * - `SampleData`, `Drawing`, `ThreeWrapper`, `GraphDrawer` — data loaders and visualization
+ * - `NodePickDetails`, `EdgePickDetails`, `InteractionOptions` — interaction callback types
  */
 export { Graph, _Node, Edge } from './Core';
 export { GraphMethods } from './GraphAlgorithms';
@@ -38,3 +39,4 @@ export * as glMatrix from 'gl-matrix';
 export { createKamadaKawai3D, createStressSGD3D } from './Simulation';
 export type { KamadaKawai3DOptions, StressSGD3DOptions, KamadaKawai3DSimulation, StressSGD3DSimulation, } from './Simulation';
 export type { LoadGraphFromObjResult } from './SampleData';
+export type { NodePickDetails, EdgePickDetails, InteractionOptions, } from './Drawing/InteractionLayer';