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

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

```js
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