force-3d-graph 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,320 @@
+import type * as THREE_2 from 'three';
+
+/**
+ * Creates a normalized edge key for duplicate detection
+ * Always puts the smaller ID first to handle bidirectional edges
+ */
+export declare function createEdgeKey(source: string, target: string): string;
+
+/**
+ * Default options
+ */
+export declare const DEFAULT_OPTIONS: Required<Omit<ForceGraph3DOptions, 'container' | 'onNodeClick' | 'onNodeHover' | 'onEdgeHover' | 'onNodeAdd' | 'onNodeRemove' | 'onEdgeAdd' | 'onEdgeRemove' | 'onExpand' | 'panelTemplate' | 'panelStyles'>>;
+
+/**
+ * Edge data provided by the user
+ */
+export declare interface Edge {
+    /** Source node ID */
+    source: string;
+    /** Target node ID */
+    target: string;
+    /** Optional relationship label */
+    relationship?: string;
+    /** Additional custom data */
+    [key: string]: unknown;
+}
+
+export declare interface EdgeObject {
+    line: THREE_2.Line;
+    source: string;
+    target: string;
+}
+
+export declare type EventCallback = (...args: unknown[]) => void;
+
+export declare type EventType = 'nodeClick' | 'nodeHover' | 'edgeHover' | 'nodeAdd' | 'nodeRemove' | 'edgeAdd' | 'edgeRemove' | 'expand' | 'ready';
+
+/**
+ * ForceGraph3D
+ * Main class for the 3D force-directed graph library
+ */
+export declare class ForceGraph3D {
+    private options;
+    private container;
+    private sceneManager;
+    private nodeManager;
+    private edgeManager;
+    private graphEngine;
+    private rendererManager;
+    private materialFactory;
+    private nodeFactory;
+    private edgeFactory;
+    private lodManager;
+    private frustumCuller;
+    private raycasterManager;
+    private panelManager;
+    private edgeTooltipManager;
+    private eventCallbacks;
+    private initialized;
+    private devControls;
+    constructor(container?: HTMLElement | null, options?: ForceGraph3DOptions);
+    /**
+     * Sets up internal callbacks
+     */
+    private setupCallbacks;
+    /**
+     * Handles edge hover
+     */
+    private onEdgeHover;
+    /**
+     * Handles node click
+     */
+    private onNodeClick;
+    /**
+     * Called every simulation step
+     */
+    private onSimulate;
+    /**
+     * Called every render frame
+     */
+    private onRender;
+    /**
+     * Sets the graph data
+     */
+    setData(data: GraphData): void;
+    /**
+     * Adds a node to the graph
+     * @returns true if added, false if node already exists or invalid
+     */
+    addNode(nodeData: NodeData): boolean;
+    /**
+     * Removes a node from the graph
+     * @returns true if removed, false if not found
+     */
+    removeNode(nodeId: string): boolean;
+    /**
+     * Updates a node's properties
+     */
+    updateNode(nodeId: string, updates: Partial<NodeData>): boolean;
+    /**
+     * Adds an edge to the graph
+     * @returns true if added, false if edge already exists or nodes don't exist
+     */
+    addEdge(edge: Edge): boolean;
+    /**
+     * Removes an edge from the graph
+     * @returns true if removed, false if not found
+     */
+    removeEdge(source: string, target: string): boolean;
+    /**
+     * Expands a node by fetching more data
+     * @param nodeId - The ID of the node to expand
+     * @param depth - The depth of expansion (1-3 levels, default 1)
+     * @param fetchFn - Optional fetch function to override the default
+     */
+    expandNode(nodeId: string, depth?: number, fetchFn?: (nodeId: string, depth: number) => Promise<GraphData>): Promise<boolean>;
+    /**
+     * Gets a node by ID
+     */
+    getNode(nodeId: string): NodeData | undefined;
+    /**
+     * Gets neighbor nodes for a node
+     */
+    getNeighbors(nodeId: string): NodeData[];
+    /**
+     * Gets the number of nodes
+     */
+    getNodeCount(): number;
+    /**
+     * Gets the number of edges
+     */
+    getEdgeCount(): number;
+    /**
+     * Sets the expand callback
+     * @param callback - Function that fetches expansion data given a nodeId and depth
+     */
+    setExpandCallback(callback: (nodeId: string, depth?: number) => Promise<GraphData>): void;
+    /**
+     * Focuses the camera on a specific node with smooth animation
+     */
+    focusOnNode(nodeId: string, distance?: number): void;
+    /**
+     * Shows the info panel for a specific node
+     */
+    showNodePanel(nodeId: string): void;
+    /**
+     * Searches nodes by label or ID (case-insensitive)
+     * @returns Array of matching nodes
+     */
+    searchNodes(query: string): NodeData[];
+    /**
+     * Searches edges by relationship (case-insensitive)
+     * @returns Array of matching edges with source/target node info
+     */
+    searchEdges(query: string): Array<{
+        edge: Edge;
+        sourceNode: NodeData;
+        targetNode: NodeData;
+    }>;
+    /**
+     * Gets all nodes as an array
+     */
+    getAllNodes(): NodeData[];
+    /**
+     * Gets all edges
+     */
+    getAllEdges(): Edge[];
+    /**
+     * Checks if the graph is initialized
+     */
+    isInitialized(): boolean;
+    /**
+     * Registers an event listener
+     */
+    on(event: EventType, callback: EventCallback): void;
+    /**
+     * Emits an event
+     */
+    private emit;
+    /**
+     * Sets physics parameters
+     */
+    setPhysicsParams(params: {
+        repulsionStrength?: number;
+        attractionStrength?: number;
+        damping?: number;
+    }): void;
+    /**
+     * Creates dev mode controls (only in development)
+     */
+    private createDevControls;
+    /**
+     * Destroys the graph and releases all resources
+     */
+    destroy(): void;
+}
+
+/**
+ * Constructor options for ForceGraph3D
+ */
+export declare interface ForceGraph3DOptions {
+    container?: HTMLElement | null;
+    backgroundColor?: number | string;
+    cameraPosition?: Vector3Data;
+    cameraFov?: number;
+    repulsionStrength?: number;
+    attractionStrength?: number;
+    damping?: number;
+    useBarnesHut?: boolean;
+    barnesHutTheta?: number;
+    defaultNodeColor?: number;
+    nodeRadius?: number;
+    nodeSegments?: number;
+    enableLOD?: boolean;
+    lodDistances?: number[];
+    lodSegments?: number[];
+    edgeColor?: number;
+    edgeOpacity?: number;
+    enableEdgeCulling?: boolean;
+    showPanel?: boolean;
+    panelTemplate?: (nodeData: NodeData, neighbors: NodeData[]) => string;
+    panelStyles?: Record<string, string>;
+    targetFPS?: number;
+    maxVisibleNodes?: number;
+    onNodeClick?: (nodeData: NodeData) => void;
+    onNodeHover?: (nodeData: NodeData | null) => void;
+    onEdgeHover?: (edge: Edge | null, sourceNode: NodeData | null, targetNode: NodeData | null) => void;
+    onNodeAdd?: (nodeData: NodeData) => void;
+    onNodeRemove?: (nodeId: string) => void;
+    onEdgeAdd?: (edge: Edge) => void;
+    onEdgeRemove?: (edge: Edge) => void;
+    onExpand?: (nodeId: string, depth?: number) => Promise<GraphData>;
+}
+
+/**
+ * Generates a large sample dataset for performance testing
+ */
+export declare function generateLargeSampleData(nodeCount?: number): GraphData;
+
+/**
+ * Generates sample graph data with the specified number of nodes
+ */
+export declare function generateSampleData(nodeCount?: number): GraphData;
+
+/**
+ * Graph data structure
+ */
+export declare interface GraphData {
+    nodes: NodeData[];
+    edges: Edge[];
+}
+
+/**
+ * Internal edge representation
+ */
+export declare interface InternalEdge extends Edge {
+    sourceNode: InternalNode;
+    targetNode: InternalNode;
+}
+
+/**
+ * Internal node representation with physics state
+ */
+export declare interface InternalNode extends NodeData {
+    position: Vector3Data;
+    velocity: Vector3Data;
+    mass: number;
+}
+
+export declare enum LODLevel {
+    HIGH = 0,
+    MEDIUM = 1,
+    LOW = 2
+}
+
+/**
+ * Node data provided by the user
+ */
+export declare interface NodeData {
+    /** Unique identifier for the node */
+    id: string;
+    /** Display label for the node */
+    label: string;
+    /** Optional hex color (default: 0x4A90E2) */
+    color?: number;
+    /** Optional initial position (random if not provided) */
+    position?: Vector3Data;
+    /** Additional custom data */
+    [key: string]: unknown;
+}
+
+export declare interface NodeObject {
+    group: THREE_2.Group;
+    sphere: THREE_2.Mesh;
+    label: THREE_2.Sprite;
+    lodLevel: LODLevel;
+}
+
+/**
+ * Validates edge data
+ * @returns true if valid, false otherwise (logs warning)
+ */
+export declare function validateEdgeData(edge: unknown): edge is Edge;
+
+/**
+ * Validates node data
+ * @returns true if valid, false otherwise (logs warning)
+ */
+export declare function validateNodeData(node: unknown): node is NodeData;
+
+/**
+ * Simple 3D vector
+ */
+export declare interface Vector3Data {
+    x: number;
+    y: number;
+    z: number;
+}
+
+export { }

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "force-3d-graph",
+  "version": "1.0.0",
+  "description": "A 3D force-directed graph visualization library built with Three.js",
+  "type": "module",
+  "main": "./dist/force-3d-graph.umd.cjs",
+  "module": "./dist/force-3d-graph.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/force-3d-graph.js",
+      "require": "./dist/force-3d-graph.umd.cjs",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "dev": "vite",
+    "build": "tsc && vite build",
+    "preview": "vite preview"
+  },
+  "keywords": [
+    "3d",
+    "graph",
+    "force-directed",
+    "three.js",
+    "visualization",
+    "network"
+  ],
+  "author": "Anish <visy.ani@gmail.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/visy-ani/force-graph.git"
+  },
+  "bugs": {
+    "url": "https://github.com/visy-ani/force-graph/issues"
+  },
+  "homepage": "https://github.com/visy-ani/force-graph#readme",
+  "dependencies": {
+    "three": ">=0.150.0"
+  },
+  "devDependencies": {
+    "@types/node": "^25.0.8",
+    "@types/three": "^0.160.0",
+    "typescript": "^5.3.3",
+    "vite": "^5.0.10",
+    "vite-plugin-dts": "^3.7.0"
+  },
+  "peerDependencies": {
+    "three": ">=0.150.0"
+  }
+}