Inital commit
Jeremy Hayes
commit
cfd64ddd02
|
|
@ -0,0 +1,191 @@
|
||||||
|
# NodeEditor.js API Documentation
|
||||||
|
|
||||||
|
`NodeEditor.js` is a lightweight, framework-agnostic, zero-dependency node editor library written in pure ES6 JavaScript. It leverages standard DOM elements for high-performance node manipulation and an SVG overlay plane for drawing scalable Bezier connections.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🚀 Quick Start
|
||||||
|
|
||||||
|
### 1. HTML Setup
|
||||||
|
Create a dedicated target container for the editor. Ensure the container has explicit dimensional bounds (`width` and `height`).
|
||||||
|
|
||||||
|
```html
|
||||||
|
<!DOCTYPE html>
|
||||||
|
<html lang="en">
|
||||||
|
<head>
|
||||||
|
<meta charset="UTF-8">
|
||||||
|
<title>Node Editor Instance</title>
|
||||||
|
<style>
|
||||||
|
body { margin: 0; background: #111; }
|
||||||
|
#editor-container {
|
||||||
|
width: 100vw;
|
||||||
|
height: 100vh;
|
||||||
|
}
|
||||||
|
</style>
|
||||||
|
</head>
|
||||||
|
<body>
|
||||||
|
|
||||||
|
<div id="editor-container"></div>
|
||||||
|
|
||||||
|
<script type="module" src="./app.js"></script>
|
||||||
|
</body>
|
||||||
|
</html>
|
||||||
|
```
|
||||||
|
|
||||||
|
### 2. JavaScript Initialization (`app.js`)
|
||||||
|
Import the `NodeEditor` module, hook it to your DOM node, and instantiate your first pipeline.
|
||||||
|
|
||||||
|
```javascript
|
||||||
|
import { NodeEditor } from './NodeEditor.js';
|
||||||
|
|
||||||
|
// 1. Initialize the UI Engine
|
||||||
|
const container = document.getElementById('editor-container');
|
||||||
|
const editor = new NodeEditor(container);
|
||||||
|
|
||||||
|
// 2. Extract the State Manager
|
||||||
|
const graph = editor.getGraphManager();
|
||||||
|
|
||||||
|
// 3. Spawning Nodes
|
||||||
|
const nodeA = graph.addNode({
|
||||||
|
type: 'source_node',
|
||||||
|
title: 'Data Stream',
|
||||||
|
x: 100,
|
||||||
|
y: 150,
|
||||||
|
inputs: [],
|
||||||
|
outputs: [{ id: 'out_raw', name: 'Raw Buffer' }]
|
||||||
|
});
|
||||||
|
|
||||||
|
const nodeB = graph.addNode({
|
||||||
|
type: 'processing_node',
|
||||||
|
title: 'Transform Matrix',
|
||||||
|
x: 450,
|
||||||
|
y: 250,
|
||||||
|
inputs: [{ id: 'in_data', name: 'Payload' }],
|
||||||
|
outputs: [{ id: 'out_success', name: 'Success' }]
|
||||||
|
});
|
||||||
|
|
||||||
|
// 4. Create a programmatically driven wire connection
|
||||||
|
graph.connect(nodeA.id, 'out_raw', nodeB.id, 'in_data');
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🛠️ Architecture Overview
|
||||||
|
|
||||||
|
The library enforces a strict separation of concerns via an asynchronous, decoupled state cycle:
|
||||||
|
|
||||||
|
```
|
||||||
|
[User Action / UI Pointer Interaction]
|
||||||
|
│
|
||||||
|
▼
|
||||||
|
[GraphManager State Engine] ◄─── (Single Source of Truth)
|
||||||
|
│
|
||||||
|
▼ (Dispatches Event Hub Actions)
|
||||||
|
[NodeEditor Render Architecture]
|
||||||
|
│
|
||||||
|
┌──────────┴──────────┐
|
||||||
|
▼ ▼
|
||||||
|
[DOM Element Nodes] [SVG Vector Overlay Patches]
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 📚 API Reference
|
||||||
|
|
||||||
|
### `NodeEditor` (UI Controller)
|
||||||
|
|
||||||
|
The wrapper orchestration manager that structures layout elements, listens to user viewport transforms, and monitors state bindings.
|
||||||
|
|
||||||
|
* **`new NodeEditor(containerElement)`**
|
||||||
|
Instantiates a fresh node pipeline map inside a target DOM container.
|
||||||
|
* **`editor.getGraphManager()`**
|
||||||
|
Returns the underlying data `GraphManager` engine operating behind the target instance.
|
||||||
|
* **`editor.updateAllConnections()`**
|
||||||
|
Forces an absolute layout recalculation of all connection nodes in view. Useful if you change node positions outside the lifecycle API or resize your external container dynamically.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### `GraphManager` (State Controller)
|
||||||
|
|
||||||
|
The isolated data engine that processes, updates, validates, and serializes graph states.
|
||||||
|
|
||||||
|
#### Node Management APIs
|
||||||
|
* **`addNode(config)`**
|
||||||
|
Registers a new data node. Returns the instantiated `NodeSchema` object.
|
||||||
|
* `config.title`: (String) Header title text.
|
||||||
|
* `config.x` / `config.y`: (Numbers) Absolute starting canvas positioning.
|
||||||
|
* `config.inputs` / `config.outputs`: Array of port objects (`{ id: 'unique_port_id', name: 'Display Name' }`).
|
||||||
|
* `config.id`: *(Optional)* Provide a deterministic string ID; otherwise, an internal generic system identifier will be automatically assigned.
|
||||||
|
* **`deleteNode(nodeId)`**
|
||||||
|
Destroys the node element matching the identifier and automatically sweeps/prunes any associated broken dependency lines.
|
||||||
|
* **`updateNodePosition(nodeId, x, y)`**
|
||||||
|
Mutates raw positioning values inside the memory reference model and triggers view updating layers.
|
||||||
|
|
||||||
|
#### Connection Management APIs
|
||||||
|
* **`connect(fromNodeId, fromSocketId, toNodeId, toSocketId)`**
|
||||||
|
Wires an active logical curve bridge between an output port and an input port. Returns `ConnectionSchema` object or `null` if the connection is illegal (e.g. self-looping or double mapping onto an input).
|
||||||
|
* **`disconnect(connectionId)`**
|
||||||
|
Severs a trace path across nodes using its direct line identifier.
|
||||||
|
|
||||||
|
#### Serialization & Hydration
|
||||||
|
* **`getState()`**
|
||||||
|
Returns a deep, JSON-serializable clone of the entire active workspace graph network topology.
|
||||||
|
* **`loadState(graphState)`**
|
||||||
|
Clears all active rendered interface objects and loads a freshly mapped `GraphState` configuration layer.
|
||||||
|
|
||||||
|
```javascript
|
||||||
|
// Saving state to local storage
|
||||||
|
const currentSnapshot = graph.getState();
|
||||||
|
localStorage.setItem('my_graph', JSON.stringify(currentSnapshot));
|
||||||
|
|
||||||
|
// Restoring state later
|
||||||
|
const cachedSnapshot = JSON.parse(localStorage.getItem('my_graph'));
|
||||||
|
if (cachedSnapshot) {
|
||||||
|
graph.loadState(cachedSnapshot);
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🎛️ Handling Graph Events
|
||||||
|
|
||||||
|
The `GraphManager` implements a lightweight publisher/subscriber layout. You can listen to lifecycle changes across your pipeline engine to trigger custom code:
|
||||||
|
|
||||||
|
```javascript
|
||||||
|
// Capture changes to map properties to external reactive modules
|
||||||
|
graph.on('stateChanged', (latestState) => {
|
||||||
|
console.log("Global modifications registered:", latestState);
|
||||||
|
});
|
||||||
|
|
||||||
|
// Trace isolated edge terminations
|
||||||
|
graph.on('connectionRemoved', (connId) => {
|
||||||
|
console.warn(`Connection item vanished from runtime: ${connId}`);
|
||||||
|
});
|
||||||
|
|
||||||
|
// Trace node structural changes
|
||||||
|
graph.on('nodeAdded', (node) => {
|
||||||
|
console.log(`New node generated: ${node.title}`);
|
||||||
|
});
|
||||||
|
```
|
||||||
|
|
||||||
|
### Available Event Signatures
|
||||||
|
|
||||||
|
| Event Key | Callback Arguments | Description |
|
||||||
|
| :--- | :--- | :--- |
|
||||||
|
| `'nodeAdded'` | `(nodeSchema)` | Dispatched when a node object joins the topology. |
|
||||||
|
| `'nodeRemoved'` | `(nodeId)` | Dispatched when a node is removed from the canvas. |
|
||||||
|
| `'nodeMoved'` | `(nodeSchema)` | Dispatched repeatedly when a node object moves coordinates. |
|
||||||
|
| `'connectionAdded'`| `(connectionSchema)` | Dispatched when two nodes are connected. |
|
||||||
|
| `'connectionRemoved'`| `(connectionId)` | Dispatched when an edge bridge is broken or deleted. |
|
||||||
|
| `'stateChanged'` | `(graphState)` | Global catch-all event executed immediately after any graph mutation. |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## ⌨️ User Interface Interactions
|
||||||
|
|
||||||
|
* **Pan Canvas:** Click and drag anywhere on the empty background or the SVG connection space.
|
||||||
|
* **Zoom Viewport:** Scroll your mouse wheel or trackpad up and down. The transformation framework calculates and pins vector values centered **directly on your mouse cursor location**.
|
||||||
|
* **Drag Nodes:** Click and hold the node header bar container element. Movement velocities match your active zoom ratio precisely.
|
||||||
|
* **Draw Wires:** Click a target circular socket connector on an output node and drag your mouse. Drop the temporary dashed wire onto a target input node socket to complete a bridge connection.
|
||||||
|
* **Destroy Wires:** Click directly on an active solid colored connection bridge path vector line to delete it from the running memory structure.
|
||||||
|
* **Destroy Nodes:** Click the small `✕` button positioned inside the upper-right corner of the node header frame.
|
||||||
|
|
@ -0,0 +1,30 @@
|
||||||
|
import { NodeEditor } from './NodeEditor.js';
|
||||||
|
|
||||||
|
// 1. Initialize the UI Engine
|
||||||
|
const container = document.getElementById('editor-container');
|
||||||
|
const editor = new NodeEditor(container);
|
||||||
|
|
||||||
|
// 2. Extract the State Manager
|
||||||
|
const graph = editor.getGraphManager();
|
||||||
|
|
||||||
|
// 3. Spawning Nodes
|
||||||
|
const nodeA = graph.addNode({
|
||||||
|
type: 'source_node',
|
||||||
|
title: 'Data Stream',
|
||||||
|
x: 100,
|
||||||
|
y: 150,
|
||||||
|
inputs: [],
|
||||||
|
outputs: [{ id: 'out_raw', name: 'Raw Buffer' }]
|
||||||
|
});
|
||||||
|
|
||||||
|
const nodeB = graph.addNode({
|
||||||
|
type: 'processing_node',
|
||||||
|
title: 'Transform Matrix',
|
||||||
|
x: 450,
|
||||||
|
y: 250,
|
||||||
|
inputs: [{ id: 'in_data', name: 'Payload' }],
|
||||||
|
outputs: [{ id: 'out_success', name: 'Success' }]
|
||||||
|
});
|
||||||
|
|
||||||
|
// 4. Create a programmatically driven wire connection
|
||||||
|
graph.connect(nodeA.id, 'out_raw', nodeB.id, 'in_data');
|
||||||
Loading…
Reference in New Issue