ingooutgo

IngoOutgo

Node Graph Editor in React!
View Demo »

Report Bug · Request Feature

Table of Contents

1. About The Project
   • Built With
2. Getting Started
   • Prerequisites
   • Installation
3. Usage
   • Basic Usage
   • Editor Store
   • Serialization
   • Styling
4. License
5. Contact

About The Project

A Node Graph Editor written in React.

Each Node has Inputs and Outputs (called Sockets), which can be connected to each other. A Socket can have an interface component, used for displaying and editing the current value.
Users can then select Nodes from a catalogue, combining them into a graph, constructing more complex logic in the process.

At its core, it uses Emil Widlund's Nodl for the Node logic, but with a completely new UI and some other new features.

• Nodes can be defined with accent color and a neat icon, and Sockets can have their own UI components
• The UI is themable, using classnames and css variables, and even customized rendering of connections (see Styling)
• Nodes can be (de-)serialized, allowing for saving and loading of graphs
• Better UX:
  • Node can be copied and pasted, even across different instances of the editor
  • When connecting Nodes, the connection snaps to compatible Sockets
  • Built-in Node Browser
  • Nodes can be dragged not just by their title bar
  • And more improvements

Built With

Usage without React

Getting Started

Prerequisites

• React
• npm or deno

Installation

Deno

import { Catalog, EditorStore, NodeEditor } from "https://deno.land/x/ingooutgo/index.ts"

NPM

npm install ingooutgo

import { Catalog, EditorStore, NodeEditor } from "ingooutgo"

Usage without React

Usage

Basic Usage

See the Nodes Readme for info on how to create Nodes.

// See example/src/app/page.tsx for full example
import { useState } from "react"
import { DemoWrapper } from "./styles"
import { Catalog, EditorStore, NodeEditor } from "ingooutgo"
import { mathCatalog, stringCatalog } from "ingooutgo-example-nodes"

const nodeCatalog: Catalog = {
  nodes: [],
  subcategories: {
    mathNodes: mathCatalog,
    stringNodes: stringCatalog,
  },
}

const App = () => {
  const [store] = useState(new EditorStore(nodeCatalog))

  // ------- Render -------
  return (
    <DemoWrapper>
      <NodeEditor
        store={store}
        reactions={{
          onConnection: (connection) => console.log("NEW CONNECTION", connection),
          onConnectionRemoval: (connection) =>
            console.log("REMOVED CONNECTION", connection),
          onNodeRemoval: (node) => console.log("REMOVED NODE", node),
          onSelectionChanged: (nodes, connections) =>
            console.log("SELECTION CHANGED", { nodes, connections }),
        }}
      />
    </DemoWrapper>
  )
}

Editor Store

The manager which is responsible for the editor state. It has the following structure:

Properties

Property name	Type	Description
nodes	IngoNode[]	The associated Nodes
connections	Connection<any>[]	The associated Connections
selectedNodes	IngoNode[]	The currently selected Nodes
selectedConnections	Connection<any>[]	The currently selected Connections
nodeCatalog	Catalog	The Catalog containing NodeRegistrations
mousePosition	MousePosition	Current mouse position within the Canvas surface

Methods

Method signature	Description
addNode(node: IngoNode, position: {x: number, y: number})	Used to add a Node at the given position
removeNode(nodeId: IngoNode['id'])	Removes a Node from the store
setNodePosition(nodeId: IngoNode["id"], position: { x: number; y: number }	Sets the position of a Node
connectSockets(a: ConnectionIds | undefined, b: ConnectionIds | undefined)	Connects two sockets (each defined as [nodeId, socketId])
removeConnection(connectionId: Connection<any>["id"])	Removes a Connection from the store
checkConnectionCompatibility(connectIdsA?: ConnectionIds, connectIdsB?: ConnectionIds): [Output<any>, Input<any>] | false	Checks for compatibility between nodes, and if compatible, returns them ordered as [Output, Input]
setSelectedNodes(nodes: IngoNode[])	Selects the given Nodes
setSelectedConnections(connections: Connection<any>[])	Selects the given Connections
deleteSelection()	Deletes the currently selected Nodes & Connections
clear()	Deletes all Nodes and Connections

Serialization

I expose two utility functions for (de-)serializing the editor.

Utility	Description
serializeNodes: (nodes: IngoNode[], positionsForNodes: Record<IngoNode["id"], Position | undefined>) => SerializedNode[]	Serializes nodes into a storable format
serializeAllNodes(store: EditorStore): SerializedNode[]	Serializes all nodes in a given store
loadSerializedNodes: (store: EditorStore, serializedNodes: SerializedNode[]) => void	Loads serialized nodes into a Store

• Note that when serializing a Node without its position, it will be set to {x: 0, y: 0}.
• When loading a serialized a Node into an EditorStore, the EditorStore needs to have a matching NodeRegistration. Otherwise, it will be ignored.

Usage without React

You can also use the editor without React, by using the EditorStore directly. See deno-sandbox/serialization-tests.ts as an example.
One usecase would be to automate inputs, once you have built a graph that you are happy with.
You can build a graph using the React UI, serialize it by selecting and copying the nodes, and then paste it into a script.

Styling

Custom Path Function

If you want, you can customize the path function used to render connections. It should return a string that can be used as the d-attribute of an SVG-Path.

// To render the path as a straight line between the sockets.
const customPathFunction = (from: Position, to: Position) => {
  return `M ${from.x} ${from.y} L ${to.x} ${to.y}`
}

Custom Styles

You can customize the theme using css variables, or by using exposed classnames. This was not tested extensively, please report any issues you encounter.

CSS variables

These are the available css variables and their default values:

.ingo {
  --color-text: rgba(255, 255, 255, 0.9);
  --color-editor-background: #343a40;
  --color-browser-divider: #343a40;
  --color-browser-background: rgba(0, 0, 0, 0.5);
  --color-browser-entry-highlight: rgba(0, 0, 0, 0.2);
  --color-node-background: #212529;
  --color-node-divider: #343a40;
  --color-node-background-lighter: #464c51;
  --color-node-icon-background: #464c51;
  --color-node-socket: #ffffff;
  --color-connection: #ffff;
  --color-selection: rgba(253, 126, 20, 1);
  --color-connection-selection: rgba(253, 126, 20, 1);
  --color-selection-shadow: rgba(253, 126, 20, 0.2);
  --color-input-border: #343a40;
  --color-input-background: #464c51;
  --color-input-background-lighter: #464c51;
}

CSS classes

And these are the classnames for the components:

Classname	Target
.ingo	All components
.connection-g	A connection between sockets
.browser-search	The Search-field for the node browser
.browser-divider	The divider in the node browser
.browser-entry	An entry in the node browser
.browser-entry-label	The label for an entry in the node browser
.node-browser	The node browser itself
.node-card	The whole node card
.node-title-bar	The title bar of a node
.node-title-label	The title label of a node
.node-title-icon	The icon of a node
.node-divider	The divider in the node card
.node-field	A field inside a node
.node-field-label	The label of a field
.node-field-type	The type-text of a field
.node-field-socket	The socket of a field
.node-field-hover-zone	The hover zone of a field
.node-field-component-wrapper	The wrapper around a component for a field
.editor-wrapper	The wrapper around the whole editor
.nodes-container	The container of the nodes

License

Distributed under the MIT License. See LICENSE.txt for more information.

Usage without React

Contact

PetrosiliusPatter - [e-mail]

Project Link: https://github.com/PetrosiliusPatter/ingooutgo

Usage without React