dragon-graph-lib 0.1.1 → 0.1.2

package/src/dragon-graph-lib.js

@@ -4,15 +4,33 @@ function to_slug(string)
     return string.replace(/[^a-z0-9_-]+/ig, "-").toLowerCase();
 }
 
+/**
+ * Connection socket
+ *
+ * This is what allows nodes to be connected between each other,
+ * it provides simple type checking but it can be customized for more complex cases.
+ */
 export class Socket
 {
+    /**
+     * @param {string} name Socket type name
+     * @param {boolean} multi_input (For input sockets) whether it should accept multiple incoming connections
+     */
     constructor(name, multi_input=false)
     {
+        /**
+         * Socket type name
+         * @member {string}
+         */
         this.name = name;
         this.multi_input = multi_input;
         this.accepts_incoming = new Set();
     }
 
+    /**
+     * Allows incoming connections from the given type
+     * @param {Socket|string} type Type name or Socket instance
+     */
     accept(type)
     {
         let type_name = type instanceof Socket ? type.name : type;
@@ -26,16 +44,41 @@ export class Socket
         return elem;
     }
 
+    /**
+     * Checks whether an output sockets allows a connection to the given input socket
+     *
+     * The default implementation defers to the input socket
+     *
+     * @param {Socket} input_socket
+     * @returns {boolean}
+     */
     output_can_connect(input_socket)
     {
         return input_socket.input_can_connect(this);
     }
 
+    /**
+     * Checks whether an input sockets allows a connection from the given output socket
+     *
+     * The default implementation checks types based on name (same or added with accept())
+     *
+     * @param {Socket} output_socket
+     * @returns {boolean}
+     */
     input_can_connect(output_socket)
     {
         return output_socket.name == this.name || this.accepts_incoming.has(output_socket.name);
     }
 
+    /**
+     * Checks whether two sockets allow connections between them
+     *
+     * Equivalent to output_socket.output_can_connect(input_socket)
+     *
+     * @param {Socket} output_socket
+     * @param {Socket} input_socket
+     * @returns {boolean}
+     */
     static can_connect(output_socket, input_socket)
     {
         return output_socket.output_can_connect(input_socket);
@@ -76,14 +119,27 @@ class VisualElement
     }
 }
 
+/**
+ * Connection between two sockets
+ */
 export class Connection extends VisualElement
 {
-    margin = 10;
-
+    /**
+     * @param {NodeOutput} output Output connector
+     * @param {NodeInput} input Input connector
+     */
     constructor(output, input)
     {
         super();
+        /**
+         * Output connector
+         * @member {NodeOutput}
+         */
         this.output = output;
+        /**
+         * Input connector
+         * @member {NodeInput}
+         */
         this.input = input;
     }
 
@@ -103,7 +159,6 @@ export class Connection extends VisualElement
     static path_d(x1, y1, x2, y2)
     {
         let w = x2 - x1;
-        let h = y2 - y1;
 
         return `M ${x1} ${y1}
         C ${x1 + w / 3} ${y1}
@@ -113,15 +168,38 @@ export class Connection extends VisualElement
     }
 }
 
-class NodeIO extends VisualElement
+/**
+ * Base connector class
+ */
+class Connector extends VisualElement
 {
     constructor(node, name, label, socket)
     {
         super();
+        /**
+         * Node this connector is part of
+         * @member {Node}
+         */
         this.node = node;
+        /**
+         * Name of the connector within the node
+         * @member {string}
+         */
         this.name = name;
+        /**
+         * User-visible label / title
+         * @member {NodeOutput}
+         */
         this.label = label;
+        /**
+         * Associated socket
+         * @member {Socket?}
+         */
         this.socket = socket;
+        /**
+         * Active connections
+         * @member {Connection[]}
+         */
         this.connections = [];
         this.dom_items = {};
     }
@@ -131,11 +209,19 @@ class NodeIO extends VisualElement
         this.dom_items.label.textContent = this.label;
     }
 
+    /**
+     * Adds a connection to the connector
+     * @param {Connection} connection
+     */
     connect(connection)
     {
         this.connections.push(connection);
     }
 
+    /**
+     * Removes a connection from the connector
+     * @param {Connection} connection
+     */
     disconnect(connection)
     {
         let index = this.connections.indexOf(connection);
@@ -144,12 +230,26 @@ class NodeIO extends VisualElement
     }
 }
 
-
-export class NodeInput extends NodeIO
+/**
+ * Input connector
+ * @extends Connector
+ */
+export class NodeInput extends Connector
 {
+    /**
+     * @param {Node}    node    Node owning this connector
+     * @param {string}  name    Name of the connector within the node
+     * @param {string}  label   User-visible label / title
+     * @param {Socket?} socket  Optional socket for incoming connectors
+     * @param {HTMLInputElement?} control Optional control to set the value without a connection
+     */
     constructor(node, name, label, socket, control)
     {
         super(node, name, label, socket);
+        /**
+         * Optional control to set the value without a connection
+         * @member {HTMLInputElement?}
+         */
         this.control = control;
     }
 
@@ -190,6 +290,10 @@ export class NodeInput extends NodeIO
             this.control.style.visibility = "hidden";
     }
 
+    /**
+     * Sets the control value
+     * @param value
+     */
     set_value(value)
     {
         if ( this.control )
@@ -198,6 +302,17 @@ export class NodeInput extends NodeIO
         }
     }
 
+    /**
+     * Gets the input value
+     *
+     * If there's input connections, the value is based on those.
+     * Otherwise the value comes from the control.
+     *
+     * If there is a socket on this connector with multi_input, the returned value
+     * is always an array.
+     *
+     * @return {any}
+     */
     get_value()
     {
         if ( this.connections.length )
@@ -228,8 +343,18 @@ export class NodeInput extends NodeIO
     }
 }
 
-export class NodeOutput extends NodeIO
+/**
+ * Output connector
+ * @extends Connector
+ */
+export class NodeOutput extends Connector
 {
+    /**
+     * @param {Node}    node    Node owning this connector
+     * @param {string}  name    Name of the connector within the node
+     * @param {string}  label   User-visible label / title
+     * @param {Socket}  socket  Socket for outgoing connectors
+     */
     constructor(node, name, label, socket)
     {
         super(node, name, label, socket);
@@ -250,16 +375,30 @@ export class NodeOutput extends NodeIO
         return container;
     }
 
+    /**
+     * Clears the stored value.
+     *
+     * Will force re-evaluation of the node on get_value()
+     */
     clear_value()
     {
         this.value = undefined;
     }
 
+    /**
+     * Sets value for outgoing connections
+     * @param value
+     */
     set_value(value)
     {
         this.value = value;
     }
 
+    /**
+     * Gets the output value
+     *
+     * Used by outgoing connections. Might cause the node to be evaluated
+     */
     get_value()
     {
         if ( this.value == undefined )
@@ -274,6 +413,12 @@ function force_default(ev)
     ev.stopPropagation();
 }
 
+/**
+ * Creates a node control
+ * @param {string} type Input type
+ * @param {object} attrs Input attributes as an object
+ * @returns {HTMLInputElement}
+ */
 export function NodeControl(type, attrs={})
 {
     let elem = document.createElement("input");
@@ -288,20 +433,51 @@ export function NodeControl(type, attrs={})
     return elem;
 }
 
+/**
+ * Main node class
+ */
 export class Node extends VisualElement
 {
+    /**
+     * @param {string} title Node title, shown to the user
+     * @param {NodeType?} type Type controlling the node
+     */
     constructor(title, type)
     {
         super();
         this.title = title;
+        /**
+         * Registered outputs
+         * @member {Object.<string, NodeOutput>}
+         */
         this.outputs = {};
+        /**
+         * Registered inputs
+         * @member {Object.<string, NodeInput>}
+         */
         this.inputs = {};
+        /**
+         * Element that can be used to preview the node effect on the editor
+         * @member {HTMLElement}
+         */
         this.preview = null;
         this.type = type;
+        /**
+         * X position in the editor
+         * @member {number}
+         */
         this.x = 0;
+        /**
+         * Y position in the editor
+         * @member {number}
+         */
         this.y = 0;
     }
 
+    /**
+     * Sets control values for inputs
+     * @param {object} data Object with input names as keys and associated values
+     */
     set_input_value(data)
     {
         for ( let [k, v] of Object.entries(this.inputs) )
@@ -311,6 +487,10 @@ export class Node extends VisualElement
         }
     }
 
+    /**
+     * Gets values from the inputs
+     * @returns {object} Object with input names as keys and associated values
+     */
     get_input_value()
     {
         let data = {};
@@ -336,11 +516,30 @@ export class Node extends VisualElement
         return connection;
     }
 
+    /**
+     * Adds a new input
+     *
+     * The resulting input will be accessible from this.inputs[name]
+     *
+     * @param {string}  name    Name of the connector within the node
+     * @param {string}  label   User-visible label / title
+     * @param {Socket?} socket  Optional socket for incoming connectors
+     * @param {HTMLInputElement?} control Optional control to set the value without a connection
+     */
     add_input(name, title, socket, control)
     {
         this.inputs[name] = new NodeInput(this, name, title, socket, control);
     }
 
+    /**
+     * Adds a new output
+     *
+     * The resulting input will be accessible from this.outputs[name]
+     *
+     * @param {string}  name    Name of the connector within the node
+     * @param {string}  label   User-visible label / title
+     * @param {Socket}  socket  Socket for outgoing connectors
+     */
     add_output(name, title, socket)
     {
         this.outputs[name] = new NodeOutput(this, name, title, socket);
@@ -348,7 +547,8 @@ export class Node extends VisualElement
 
     update_dom()
     {
-        this.dom.style.transform = `translate(${this.x}px, ${this.y}px`;
+        this.dom.style.left = `${this.x}px`;
+        this.dom.style.top = `${this.y}px`;
     }
 
     build_dom()
@@ -378,6 +578,34 @@ export class Node extends VisualElement
             this.type.evaluate_node(this);
     }
 
+    /**
+     * Returns a list of all input connections
+     * @returns {Connection[]}
+     */
+    input_connections()
+    {
+        return Object.values(this.inputs)
+            .map(c => c.connections)
+            .reduce((a, b) => a.concat(b), [])
+        ;
+    }
+
+    /**
+     * Returns a list of all output connections
+     * @returns {Connection[]}
+     */
+    all_connections()
+    {
+        return Object.values(this.outputs)
+            .map(c => c.connections)
+            .reduce((a, b) => a.concat(b), [])
+        ;
+    }
+
+    /**
+     * Returns a list of all connections (both input and output)
+     * @returns {Connection[]}
+     */
     all_connections()
     {
         return Object.values(this.inputs).concat(Object.values(this.outputs))
@@ -387,13 +615,32 @@ export class Node extends VisualElement
     }
 }
 
+/**
+ * Node type
+ *
+ * This class is responsible for creating nodes, and adding logic for output values
+ */
 export class NodeType
 {
+    /**
+     * @param {string} name Type name
+     */
     constructor(name)
     {
+        /**
+         * Type name
+         * @member {string}
+         */
         this.name = name;
     }
 
+    /**
+     * Creates and sets up a node for this type
+     *
+     * Custom types should override populate_node() to add connectors or otherwise customize the node
+     *
+     * @returns Node
+     */
     create_node()
     {
         let node = new Node(this.name, this);
@@ -401,23 +648,43 @@ export class NodeType
         return node;
     }
 
-    populate_node(node)
+    /**
+     * Allows custom types to add connectors or otherwise customize the node
+     * @protected
+     * @param {Node} node
+     */
+    populate_node(_node)
     {
     }
 
-    update_node(node)
-    {
-
-    }
-
-    evaluate_node(node)
+    /**
+     * Evaluates node logic
+     *
+     * Generally you should get input values with `node.inputs[name].get_value()`
+     * And set output values with `node.outputs[name].set_value()`.
+     *
+     * You can also alter the `node.preview` to add custom HTML to the node
+     * based on these values
+     *
+     * @param {Node} node
+     */
+    evaluate_node(_node)
     {
 
     }
 }
 
+/**
+ * Context menu for the node editor
+ */
 export class ContextMenu extends VisualElement
 {
+    /**
+     * @param {object|NodeType[]} actions If an object,
+     * keys will be items in the menu while values are the performed actions.
+     * Possible values are callbacks, NodeType instances (which will create new nodes),
+     * Or other actions definitions for submenus
+     */
     constructor(actions)
     {
         super();
@@ -486,6 +753,11 @@ export class ContextMenu extends VisualElement
         return item;
     }
 
+    /**
+     * Opens the menu at the given point
+     * @param {number} x
+     * @param {number} y
+     */
     show(x, y)
     {
         this.dom.style.display = "";
@@ -493,19 +765,32 @@ export class ContextMenu extends VisualElement
         this.dom.style.top = y + "px";
     }
 
+    /**
+     * Closes the menu
+     */
     close()
     {
         this.dom.style.display = "none";
     }
 }
 
+/**
+ * Node Editor
+ */
 export class Editor
 {
+
+    /**
+     * @param {HTMLElement} container Parent element in the DOM
+     * @param {object|NodeType[]} Actions for the context menu (See ContextMenu)
+     */
     constructor(container, context_menu={})
     {
         this.nodes = [];
 
         this.container = container;
+        if ( !container.hasAttribute("tabindex") )
+            container.setAttribute("tabindex", "0");
 
         this.area = container.appendChild(document.createElement("div"));
         container.classList.add("dgl-editor");
@@ -531,6 +816,12 @@ export class Editor
         this.container.addEventListener("mousedown", this._on_area_mouse_down.bind(this));
         this.container.addEventListener("mousemove", this._on_area_mouse_move.bind(this));
         this.container.addEventListener("mouseup", this._on_area_mouse_up.bind(this));
+
+        this.container.addEventListener("touchstart", this._on_area_mouse_down.bind(this));
+        this.container.addEventListener("touchmove", this._on_area_mouse_move.bind(this));
+        this.container.addEventListener("touchend", this._on_area_mouse_up.bind(this));
+        this.container.addEventListener("touchcancel", this._on_area_mouse_up.bind(this));
+
         this.container.addEventListener("wheel", this._on_area_wheel.bind(this));
         this.container.addEventListener("contextmenu", this._on_area_menu.bind(this));
 
@@ -543,8 +834,6 @@ export class Editor
             "Duplicate": () => {
                 if ( this.selected_node ) {
                     let node = this.create_node(this.selected_node.type, this.selected_node.get_input_value());
-                    node.x = this.selected_node.x;
-                    node.y = this.selected_node.y;
                     this._select_node(node);
 
                 }
@@ -555,10 +844,13 @@ export class Editor
         this.container.appendChild(this.context_menu.to_dom(this));
     }
 
-    create_node(type, data={})
+
+    /**
+     * Adds a new node to the graph
+     * @param {Node} node
+     */
+    add_node(node)
     {
-        let node = type.create_node();
-        node.set_input_value(data);
         node.x = this.cursor_x;
         node.y = this.cursor_y;
         this.nodes.push(node);
@@ -566,11 +858,53 @@ export class Editor
         this.area.appendChild(node_dom);
 
         node_dom.addEventListener("mousedown", ev => this._on_node_mouse_down(ev, node));
+        node_dom.addEventListener("touchstart", ev => this._on_node_mouse_down(ev, node));
         node_dom.addEventListener("contextmenu", ev => this._on_node_menu(ev, node));
+        for ( let input of Object.values(node.inputs) )
+        {
+            if ( input.control )
+            {
+                input.control.addEventListener("change", () => this._refresh_graph());
+            }
+        }
+    }
 
+    /**
+     * Removes a node from the graph
+     * @param {Node} node
+     */
+    remove_node(node)
+    {
+        for ( let conn of node.all_connections() )
+            conn.disconnect();
+
+        let ind = this.nodes.indexOf(node);
+        if ( ind != -1 )
+            this.nodes.splice(ind, 1);
+        node.destroy();
+
+        this._refresh_graph();
+    }
+
+    /**
+     * Creates a new node from the given type
+     * @param {NodeType} type
+     * @param {object} data Optional data to populate node inputs
+     * @returns {Node} The created node
+     */
+    create_node(type, data={})
+    {
+        let node = type.create_node();
+        node.set_input_value(data);
+        this.add_node(node);
         return node;
     }
 
+    /**
+     * Automatically lays out the graph
+     *
+     * It assumes all nodes and connections are set up
+     */
     auto_layout()
     {
         setTimeout(() => this._on_auto_layout());
@@ -663,8 +997,60 @@ export class Editor
         }
 
         this._refresh_graph();
+        this.fit_view();
+    }
+
+    /**
+     * Pan and zoom to fit all the nodes
+     * @param {number} margin Margin to leave around the area
+     */
+    fit_view(margin=20)
+    {
+        if ( this.nodes.length == 0 )
+            return;
+
+        let left = Infinity;
+        let right = -Infinity;
+        let top = Infinity;
+        let bottom = -Infinity;
+
+        for ( let node of this.nodes )
+        {
+            let rect = node.dom.getBoundingClientRect();
+            if ( rect.left < left ) left = rect.left;
+            if ( rect.right > right ) right = rect.right;
+            if ( rect.top < top ) top = rect.top;
+            if ( rect.bottom > bottom ) bottom = rect.bottom;
+        }
+
+        let crect = this.container.getBoundingClientRect();
+
+        left += -margin - crect.left;
+        right += margin - crect.left;
+        top += -margin - crect.top;
+        bottom += margin - crect.top;
+
+        let width = right - left;
+        let height = bottom - top;
+        let x_scale = crect.width / width;
+        let y_scale = crect.height / height;
+        let scale = Math.min(x_scale, y_scale);
+        this.scale = scale;
+
+        this.offset_x = (crect.width - width * scale) / 2 - left + margin;
+        this.offset_y = (crect.height - height * scale) / 2 - top + margin;
+        this._apply_transform();
+
     }
 
+    /**
+     * Adds a connection to the graph
+     * @param {Node}    output_node Node the connection is coming from
+     * @param {string}  output_name Name of the output connector within output_node
+     * @param {Node}    input_node  Node the connection is going to
+     * @param {string}  input_name  Name of the input connector within input_node
+     * @return {Connection?} Connection (Or null if the connection is impossible)
+     */
     connect(output_node, output_name, input_node, input_name)
     {
         let conn = output_node.connect(output_name, input_node, input_name);
@@ -680,6 +1066,10 @@ export class Editor
         return conn;
     }
 
+    /**
+     * Removes a connection from the graph
+     * @param {Connection} connection
+     */
     disconnect(connection)
     {
         connection.disconnect();
@@ -699,18 +1089,27 @@ export class Editor
         this.node_menu.close();
     }
 
+    _touch_mouse_pos(ev)
+    {
+        if ( ev.changedTouches )
+            return ev.changedTouches[0];
+        return ev;
+    }
+
     _on_area_mouse_down(ev)
     {
+        this.container.focus();
         this._close_menus();
         if ( ev.button == 0 )
         {
             this._select_node(null);
         }
-        else if ( ev.button == 1 )
+        else if ( ev.button == 1 || ev.changedTouches )
         {
             let rect = this.container.getBoundingClientRect();
-            this.drag_start_x = ev.clientX - rect.left;
-            this.drag_start_y = ev.clientY - rect.top;
+            let evp = this._touch_mouse_pos(ev);
+            this.drag_start_x = evp.clientX - rect.left;
+            this.drag_start_y = evp.clientY - rect.top;
             this.drag_start_ox = this.offset_x;
             this.drag_start_oy = this.offset_y;
             this.drag = "pan";
@@ -736,8 +1135,9 @@ export class Editor
     _on_area_mouse_move(ev)
     {
         let rect = this.container.getBoundingClientRect();
-        let drag_x = ev.clientX - rect.left;
-        let drag_y = ev.clientY - rect.top;
+        let evp = this._touch_mouse_pos(ev);
+        let drag_x = evp.clientX - rect.left;
+        let drag_y = evp.clientY - rect.top;
         this.cursor_x = (drag_x - this.offset_x) / this.scale;
         this.cursor_y = (drag_y - this.offset_y) / this.scale;
 
@@ -757,7 +1157,8 @@ export class Editor
                 let y = this.drag_start_oy + delta_y / this.scale;
                 this.selected_node.x = x;
                 this.selected_node.y = y;
-                this.selected_node.dom.style.transform = `translate(${x}px, ${y}px`;
+                this.selected_node.dom.style.left = `${x}px`;
+                this.selected_node.dom.style.top = `${y}px`;
                 for ( let connection of this.selected_node.all_connections() )
                     this._update_connection(connection);
             }
@@ -802,7 +1203,8 @@ export class Editor
 
     _get_dest_connector(ev)
     {
-        let elem = document.elementFromPoint(ev.clientX, ev.clientY);
+        let evp = this._touch_mouse_pos(ev);
+        let elem = document.elementFromPoint(evp.clientX, evp.clientY);
         if ( !elem.classList.contains("dgl-socket") )
             return null;
 
@@ -844,6 +1246,9 @@ export class Editor
         ev.preventDefault();
         ev.stopPropagation();
 
+        if ( !this.container.contains(document.activeElement) )
+            return;
+
         let rect = this.container.getBoundingClientRect();
         let mouse_x = ev.clientX - rect.left;
         let mouse_y = ev.clientY - rect.top;
@@ -869,15 +1274,17 @@ export class Editor
 
     _on_node_mouse_down(ev, node)
     {
+        // this.container.focus();
         this._close_menus();
-        if ( ev.button == 0 )
+        if ( ev.button == 0 || ev.changedTouches )
         {
             ev.stopPropagation();
             this._select_node(node);
             this.drag = "node";
             let rect = this.container.getBoundingClientRect();
-            this.drag_start_x = ev.clientX - rect.left;
-            this.drag_start_y = ev.clientY - rect.top;
+            let evp = this._touch_mouse_pos(ev);
+            this.drag_start_x = evp.clientX - rect.left;
+            this.drag_start_y = evp.clientY - rect.top;
             this.drag_start_ox = node.x;
             this.drag_start_oy = node.y;
             if ( ev.target.classList.contains("dgl-socket") )