Graph-Explorer-JS/README.md

Canvas Graph Explorer

A lightweight, dependency-free JavaScript graph editor built on the HTML Canvas API. It provides draggable nodes, Bézier-curve connections, panning, zooming, grid rendering, and basic context-menu operations.

Overview

This project implements an interactive node-graph system similar to visual programming or shader editors. It is designed for direct use in the browser and does not rely on external frameworks.

Core capabilities:

• Rectangular nodes with named input and output ports
• Curved connection wires (Bézier curves)
• Drag-and-drop node positioning
• Wire creation by dragging from output ports
• Canvas panning with inertia
• Zooming with mouse wheel
• Grid rendering in world space
• Context menus for deleting nodes and wires

Architecture

The system is composed of three main classes:

Node

Represents a visual node in the graph.

Responsibilities:

• Stores position, size, name, inputs, and outputs
• Dynamically calculates height and width
• Renders itself and its ports
• Performs hit-testing

Edge

Represents a connection between an output port and an input port.

Responsibilities:

• Draws a Bézier curve between ports
• Supports temporary endpoints while dragging
• Provides proximity testing for selection and deletion

GraphExplorer

The main controller and renderer.

Responsibilities:

• Manages nodes and edges
• Handles mouse and wheel interaction
• Performs coordinate transforms (screen ↔ world)
• Renders grid, nodes, and edges
• Implements panning, zooming, inertia, and selection logic

Requirements

• A modern web browser
• An HTML <canvas> element
• Minimal supporting HTML for context menus

No build step or package manager is required.

Basic Usage

<canvas id="graph"></canvas>

import { GraphExplorer, Node } from "./graph.js";

const canvas = document.getElementById("graph");

const graph = new GraphExplorer();
graph.setup(canvas);

graph.addNode(
	new Node(
		"Example Node",
		100,
		100,
		["Input A", "Input B"],
		["Output"]
	)
);

graph.draw();

Interaction Model

• Left mouse button

  • Drag node: move node
  • Drag from output port: create wire
  • Drag background: pan canvas

• Mouse wheel

  • Zoom in and out (centered on canvas)

• Right mouse button

  • Open context menu on node or wire

• Context menu

  • Delete node (removes connected wires)
  • Delete wire

Notes

• The code assumes the presence of DOM elements with IDs:

  • nodeMenu
  • wireMenu
  • deleteNodeBtn
  • deleteWireBtn

• Styling and menu layout are intentionally left to the host application.

• The implementation is intentionally imperative and framework-agnostic.

Intended Use Cases

• Visual programming editors
• Audio or signal-processing graphs
• Shader or material editors
• Workflow or dependency visualization
• Prototyping node-based user interfaces

License

MIT