@neo4j-nvl/interaction-handlers 0.2.1

package/README.md

@@ -0,0 +1 @@
+This module is a collection of decorator classes that can be used to add interaction events to an NVL instance. The decorators are applied to the NVL class. You can find documentation for the decorators in the usage documentation of each class.

package/lib/constants.d.ts

@@ -0,0 +1 @@
+export declare const NODE_EDGE_WIDTH = 10;

package/lib/constants.js

@@ -0,0 +1 @@
+export const NODE_EDGE_WIDTH = 10;

package/lib/index.d.ts

@@ -0,0 +1,15 @@
+import type { ClickInteractionCallbacks, ClickInteractionOptions } from './interaction-handlers/click-interaction';
+import { ClickInteraction } from './interaction-handlers/click-interaction';
+import { DragNodeInteraction } from './interaction-handlers/drag-node-interaction';
+import type { DragNodeInteractionCallbacks } from './interaction-handlers/drag-node-interaction';
+import { DrawInteraction } from './interaction-handlers/draw-interaction';
+import type { HoverInteractionOptions, HoverInteractionCallbacks } from './interaction-handlers/hover-interaction';
+import { HoverInteraction } from './interaction-handlers/hover-interaction';
+import type { MultiSelectInteractionOptions } from './interaction-handlers/multi-select-interaction';
+import { MultiSelectInteraction } from './interaction-handlers/multi-select-interaction';
+import type { PanInteractionCallbacks } from './interaction-handlers/pan-interaction';
+import { PanInteraction } from './interaction-handlers/pan-interaction';
+import type { ZoomInteractionCallbacks } from './interaction-handlers/zoom-interaction';
+import { ZoomInteraction } from './interaction-handlers/zoom-interaction';
+export type { MultiSelectInteractionOptions, ClickInteractionOptions, HoverInteractionOptions, HoverInteractionCallbacks, DragNodeInteractionCallbacks, ClickInteractionCallbacks, PanInteractionCallbacks, ZoomInteractionCallbacks };
+export { ZoomInteraction, PanInteraction, MultiSelectInteraction, ClickInteraction, HoverInteraction, DragNodeInteraction, DrawInteraction };

package/lib/index.js

@@ -0,0 +1,8 @@
+import { ClickInteraction } from './interaction-handlers/click-interaction';
+import { DragNodeInteraction } from './interaction-handlers/drag-node-interaction';
+import { DrawInteraction } from './interaction-handlers/draw-interaction';
+import { HoverInteraction } from './interaction-handlers/hover-interaction';
+import { MultiSelectInteraction } from './interaction-handlers/multi-select-interaction';
+import { PanInteraction } from './interaction-handlers/pan-interaction';
+import { ZoomInteraction } from './interaction-handlers/zoom-interaction';
+export { ZoomInteraction, PanInteraction, MultiSelectInteraction, ClickInteraction, HoverInteraction, DragNodeInteraction, DrawInteraction };

package/lib/interaction-handlers/base.d.ts

@@ -0,0 +1,54 @@
+import { NVL } from '@neo4j-nvl/core';
+/**
+ * Base class for all interactions.
+ * @abstract
+ * @internal
+ */
+declare abstract class BaseInteraction<T extends Record<string, (...args: unknown[]) => void>> {
+    private readonly nvl;
+    private readonly container;
+    /**
+     * @internal
+     */
+    callbackMap: Map<keyof T, T[keyof T]>;
+    /**
+     * @internal
+     */
+    constructor(nvl: NVL);
+    /**
+     * @internal
+     */
+    get nvlInstance(): NVL;
+    /**
+     * @internal
+     */
+    get containerInstance(): HTMLElement;
+    /**
+     * @internal
+     */
+    addEventListener: (type: keyof HTMLElementEventMap, listener: (event: Event) => void, options?: boolean | AddEventListenerOptions) => void;
+    /**
+     * @internal
+     */
+    removeEventListener: (type: keyof HTMLElementEventMap, listener: (event: Event) => void, options?: boolean | EventListenerOptions) => void;
+    /**
+     * @internal
+     */
+    callCallbackIfRegistered: (name: keyof T, ...args: Parameters<T[keyof T]>) => void;
+    /**
+     * Add or update a callback for a given event of type.
+     * @param name - The name of the event
+     * @param callback - The callback to be called when the event is triggered
+     */
+    updateCallback: (name: keyof T, callback: T[keyof T]) => void;
+    /**
+     * Remove a callback for a given event of type.
+     * @param name - The name of the event
+     */
+    removeCallback: (name: keyof T) => void;
+    /**
+     * @internal
+     */
+    abstract destroy(): void;
+}
+export { BaseInteraction };

package/lib/interaction-handlers/base.js

@@ -0,0 +1,110 @@
+/**
+ * Base class for all interactions.
+ * @abstract
+ * @internal
+ */
+class BaseInteraction {
+    /**
+     * @internal
+     */
+    constructor(nvl) {
+        Object.defineProperty(this, "nvl", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "container", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        /**
+         * @internal
+         */
+        Object.defineProperty(this, "callbackMap", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        /**
+         * @internal
+         */
+        Object.defineProperty(this, "addEventListener", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: (type, listener, options) => {
+                this.container.addEventListener(type, listener, options);
+            }
+        });
+        /**
+         * @internal
+         */
+        Object.defineProperty(this, "removeEventListener", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: (type, listener, options) => {
+                this.container.removeEventListener(type, listener, options);
+            }
+        });
+        /**
+         * @internal
+         */
+        Object.defineProperty(this, "callCallbackIfRegistered", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: (name, ...args) => {
+                const callback = this.callbackMap.get(name);
+                if (callback) {
+                    callback(...args);
+                }
+            }
+        });
+        /**
+         * Add or update a callback for a given event of type.
+         * @param name - The name of the event
+         * @param callback - The callback to be called when the event is triggered
+         */
+        Object.defineProperty(this, "updateCallback", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: (name, callback) => {
+                this.callbackMap.set(name, callback);
+            }
+        });
+        /**
+         * Remove a callback for a given event of type.
+         * @param name - The name of the event
+         */
+        Object.defineProperty(this, "removeCallback", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: (name) => {
+                this.callbackMap.delete(name);
+            }
+        });
+        this.nvl = nvl;
+        this.container = this.nvl.getContainer();
+        this.callbackMap = new Map();
+    }
+    /**
+     * @internal
+     */
+    get nvlInstance() {
+        return this.nvl;
+    }
+    /**
+     * @internal
+     */
+    get containerInstance() {
+        return this.container;
+    }
+}
+export { BaseInteraction };

package/lib/interaction-handlers/click-interaction.d.ts

@@ -0,0 +1,109 @@
+import type { HitTargets, NVL, Node, Relationship } from '@neo4j-nvl/core';
+import { BaseInteraction } from './base';
+/**
+ * Options for the click interaction handler to customize its behavior.
+ */
+export type ClickInteractionOptions = {
+    /**
+     * Whether to select the node or relationship on click
+     * @defaultValue false
+     */
+    selectOnClick?: boolean;
+};
+/**
+ * Callbacks for the click interaction handler.
+ */
+export type ClickInteractionCallbacks = {
+    /**
+     * Called when a node is clicked
+     * @param nodes - The node that was clicked
+     * @param hitElements - All elements that were hit by the click
+     * @param event - The original mouse event
+     */
+    onNodeClick: (nodes: Node, hitElements: HitTargets, event: MouseEvent) => void;
+    /**
+     * Called when a relationship is clicked
+     * @param relationship - The relationship that was clicked
+     * @param hitElements - All elements that were hit by the click
+     * @param event - The original mouse event
+     */
+    onRelationshipClick: (relationship: Relationship, hitElements: HitTargets, event: MouseEvent) => void;
+    /**
+     * Called when the canvas is clicked
+     * @param event - The original mouse event
+     */
+    onCanvasClick: (event: MouseEvent) => void;
+    /**
+     * Called when a node is double clicked
+     * @param event - The original mouse event
+     */
+    onCanvasDoubleClick: (event: MouseEvent) => void;
+    /**
+     * Called when a relationship is right-clicked
+     * @param event - The original mouse event
+     */
+    onCanvasRightClick: (event: MouseEvent) => void;
+    /**
+     * Called when a node is double-clicked
+     * @param nodes - The node that was double-clicked
+     * @param hitElements - All elements that were hit by the double-click
+     * @param event - The original mouse event
+     */
+    onNodeDoubleClick: (node: Node, hitElements: HitTargets, event: MouseEvent) => void;
+    /**
+     * Called when a node is right-clicked
+     * @param nodes - The node that was right-clicked
+     * @param hitElements - All elements that were hit by the right-click
+     * @param event - The original mouse event
+     */
+    onNodeRightClick: (node: Node, hitElements: HitTargets, event: MouseEvent) => void;
+    /**
+     * Called when a relationship is double-clicked
+     * @param relationship - The relationship that was double-clicked
+     * @param hitElements - All elements that were hit by the double-click
+     * @param event - The original mouse event
+     */
+    onRelationshipDoubleClick: (relationship: Relationship, hitElements: HitTargets, event: MouseEvent) => void;
+    /**
+     * Called when a relationship is right-clicked
+     * @param relationship - The relationship that was right-clicked
+     * @param hitElements - All elements that were hit by the right-click
+     * @param event - The original mouse event
+     */
+    onRelationshipRightClick: (relationship: Relationship, hitElements: HitTargets, event: MouseEvent) => void;
+};
+/**
+ * Click interaction handler that handles click, double click and right click events on
+ * nodes, relationships and canvas.
+ *
+ * @example
+ * ```ts
+ * import { ClickInteraction } from '@neo4j-nvl/interaction-handlers'
+ * import { NVL } from '@neo4j-nvl/core'
+ *
+ * const nvl = new NVL(nodes, relationships, options)
+ * const clickInteraction = new ClickInteraction(nvl)
+ * clickInteraction.updateCallback('onNodeClick', (node) => {
+ *   console.log('Node clicked', node)
+ * })
+ * ```
+ */
+export declare class ClickInteraction extends BaseInteraction<ClickInteractionCallbacks> {
+    private moved;
+    private readonly options;
+    /**
+     * Creates a new click interaction handler.
+     * @param nvl - The NVL instance to attach the interaction handler to
+     * @param options - Options for the click interaction handler
+     */
+    constructor(nvl: NVL, options?: ClickInteractionOptions);
+    private handleMouseDown;
+    private handleMouseMove;
+    private handleRightClick;
+    private handleDoubleClick;
+    private handleMouseUp;
+    /**
+     * Removes all related event listeners from the container.
+     */
+    destroy: () => void;
+}

package/lib/interaction-handlers/click-interaction.js

@@ -0,0 +1,162 @@
+import { BaseInteraction } from './base';
+/**
+ * Click interaction handler that handles click, double click and right click events on
+ * nodes, relationships and canvas.
+ *
+ * @example
+ * ```ts
+ * import { ClickInteraction } from '@neo4j-nvl/interaction-handlers'
+ * import { NVL } from '@neo4j-nvl/core'
+ *
+ * const nvl = new NVL(nodes, relationships, options)
+ * const clickInteraction = new ClickInteraction(nvl)
+ * clickInteraction.updateCallback('onNodeClick', (node) => {
+ *   console.log('Node clicked', node)
+ * })
+ * ```
+ */
+export class ClickInteraction extends BaseInteraction {
+    /**
+     * Creates a new click interaction handler.
+     * @param nvl - The NVL instance to attach the interaction handler to
+     * @param options - Options for the click interaction handler
+     */
+    constructor(nvl, options = { selectOnClick: false }) {
+        super(nvl);
+        Object.defineProperty(this, "moved", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "options", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "handleMouseDown", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: () => {
+                this.moved = false;
+            }
+        });
+        Object.defineProperty(this, "handleMouseMove", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: () => {
+                this.moved = true;
+            }
+        });
+        Object.defineProperty(this, "handleRightClick", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: (event) => {
+                event.preventDefault();
+                const { nvlTargets } = this.nvlInstance.getHits(event);
+                const { nodes = [], relationships = [] } = nvlTargets;
+                if (nodes.length === 0 && relationships.length === 0) {
+                    this.callCallbackIfRegistered('onCanvasRightClick', event);
+                    return;
+                }
+                if (nodes.length > 0) {
+                    this.callCallbackIfRegistered('onNodeRightClick', nodes[0].data, nvlTargets, event);
+                }
+                else if (relationships.length > 0) {
+                    this.callCallbackIfRegistered('onRelationshipRightClick', relationships[0].data, nvlTargets, event);
+                }
+            }
+        });
+        Object.defineProperty(this, "handleDoubleClick", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: (event) => {
+                const { nvlTargets } = this.nvlInstance.getHits(event);
+                const { nodes = [], relationships = [] } = nvlTargets;
+                if (nodes.length === 0 && relationships.length === 0) {
+                    this.callCallbackIfRegistered('onCanvasDoubleClick', event);
+                    return;
+                }
+                if (nodes.length > 0) {
+                    this.callCallbackIfRegistered('onNodeDoubleClick', nodes[0].data, nvlTargets, event);
+                }
+                else if (relationships.length > 0) {
+                    this.callCallbackIfRegistered('onRelationshipDoubleClick', relationships[0].data, nvlTargets, event);
+                }
+            }
+        });
+        Object.defineProperty(this, "handleMouseUp", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: (event) => {
+                if (this.moved) {
+                    return;
+                }
+                const { nvlTargets } = this.nvlInstance.getHits(event);
+                const { nodes = [], relationships = [] } = nvlTargets;
+                if (nodes.length === 0 && relationships.length === 0) {
+                    if (this.options.selectOnClick) {
+                        this.nvlInstance.deselectAll();
+                    }
+                    this.callCallbackIfRegistered('onCanvasClick', event);
+                    return;
+                }
+                if (nodes.length > 0) {
+                    const hitNodeData = nodes.map((node) => node.data);
+                    if (this.options.selectOnClick) {
+                        const selectedNodes = this.nvlInstance.getSelectedNodes();
+                        const selectedRelationships = this.nvlInstance.getSelectedRelationships();
+                        const nodeUpdates = [
+                            ...selectedNodes.map((node) => ({ id: node.id, selected: false })),
+                            { id: hitNodeData[0].id, selected: true }
+                        ];
+                        const relationshipUpdates = selectedRelationships.map((relationship) => (Object.assign(Object.assign({}, relationship), { selected: false })));
+                        this.nvlInstance.updateElementsInGraph(nodeUpdates, relationshipUpdates);
+                    }
+                    this.callCallbackIfRegistered('onNodeClick', nodes[0].data, nvlTargets, event);
+                }
+                else if (relationships.length > 0) {
+                    const hitRelationshipData = relationships.map((relationship) => relationship.data);
+                    if (this.options.selectOnClick) {
+                        const selectedNodes = this.nvlInstance.getSelectedNodes();
+                        const selectedRelationships = this.nvlInstance.getSelectedRelationships();
+                        const nodeUpdates = selectedNodes.map((node) => ({ id: node.id, selected: false }));
+                        const relationshipUpdates = [
+                            { id: hitRelationshipData[0].id, selected: true },
+                            ...selectedRelationships.map((relationship) => (Object.assign(Object.assign({}, relationship), { selected: false })))
+                        ];
+                        this.nvlInstance.updateElementsInGraph(nodeUpdates, relationshipUpdates);
+                    }
+                    this.callCallbackIfRegistered('onRelationshipClick', relationships[0].data, nvlTargets, event);
+                }
+            }
+        });
+        /**
+         * Removes all related event listeners from the container.
+         */
+        Object.defineProperty(this, "destroy", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: () => {
+                this.removeEventListener('mousedown', this.handleMouseDown, true);
+                this.removeEventListener('mousemove', this.handleMouseMove, true);
+                this.removeEventListener('mouseup', this.handleMouseUp, true);
+                this.removeEventListener('dblclick', this.handleMouseUp, true);
+                this.removeEventListener('contextmenu', this.handleRightClick, true);
+            }
+        });
+        this.options = options;
+        this.addEventListener('mousedown', this.handleMouseDown, true);
+        this.addEventListener('mousemove', this.handleMouseMove, true);
+        this.addEventListener('mouseup', this.handleMouseUp, true);
+        this.addEventListener('dblclick', this.handleDoubleClick, true);
+        this.addEventListener('contextmenu', this.handleRightClick, true);
+    }
+}

package/lib/interaction-handlers/drag-node-interaction.d.ts

@@ -0,0 +1,46 @@
+import type { NVL, Node } from '@neo4j-nvl/core';
+import { BaseInteraction } from './base';
+/**
+ * Callbacks for the drag node interaction handler.
+ */
+export type DragNodeInteractionCallbacks = {
+    /**
+     * Called when node(s) are dragged
+     * @param nodes - The node(s) being dragged
+     */
+    onDrag: (nodes: Node[]) => void;
+};
+/**
+ * Interaction handler for dragging nodes.
+ * Dragging is achieved by clicking and dragging on the node.
+ * @note When more than one node is selected, all selected nodes will be dragged.
+ *
+ * @example
+ * ```js
+ * const nvl = new NVL(container, nodes, relationships)
+ * const dragNodeInteraction = new DragNodeInteraction(nvl)
+ *
+ * dragNodeInteraction.updateCallback('onDrag', (nodes) => {
+ *   console.log('Dragged nodes:', nodes)
+ * })
+ * ```
+ */
+export declare class DragNodeInteraction extends BaseInteraction<DragNodeInteractionCallbacks> {
+    private mousePosition;
+    private mouseDownNode;
+    private isDrawing;
+    private selectedNodes;
+    private moveSelectedNodes;
+    /**
+     * Creates a new instance of the drag node interaction handler.
+     * @param nvl - The NVL instance to attach the interaction handler to
+     */
+    constructor(nvl: NVL);
+    private handleMouseDown;
+    private handleMouseMove;
+    private handleMouseUp;
+    /**
+     * Removes all related event listeners from the container.
+     */
+    destroy: () => void;
+}

package/lib/interaction-handlers/drag-node-interaction.js

@@ -0,0 +1,137 @@
+import { NODE_EDGE_WIDTH } from '../constants';
+import { BaseInteraction } from './base';
+/**
+ * Interaction handler for dragging nodes.
+ * Dragging is achieved by clicking and dragging on the node.
+ * @note When more than one node is selected, all selected nodes will be dragged.
+ *
+ * @example
+ * ```js
+ * const nvl = new NVL(container, nodes, relationships)
+ * const dragNodeInteraction = new DragNodeInteraction(nvl)
+ *
+ * dragNodeInteraction.updateCallback('onDrag', (nodes) => {
+ *   console.log('Dragged nodes:', nodes)
+ * })
+ * ```
+ */
+export class DragNodeInteraction extends BaseInteraction {
+    /**
+     * Creates a new instance of the drag node interaction handler.
+     * @param nvl - The NVL instance to attach the interaction handler to
+     */
+    constructor(nvl) {
+        super(nvl);
+        Object.defineProperty(this, "mousePosition", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "mouseDownNode", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "isDrawing", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "selectedNodes", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "moveSelectedNodes", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "handleMouseDown", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: (event) => {
+                this.mousePosition = { x: event.clientX, y: event.clientY };
+                const hits = this.nvlInstance.getHits(event, ['node'], { hitNodeMarginWidth: NODE_EDGE_WIDTH });
+                const hitNodes = hits.nvlTargets.nodes.filter(node => node.insideNode);
+                const hitNodeEdges = hits.nvlTargets.nodes.filter(node => !node.insideNode);
+                if (hitNodeEdges.length > 0) {
+                    this.isDrawing = true;
+                    this.mouseDownNode = null;
+                }
+                else if (hitNodes.length > 0) {
+                    this.mouseDownNode = hits.nvlTargets.nodes[0];
+                }
+                else {
+                    this.mouseDownNode = null;
+                }
+                this.selectedNodes = this.nvlInstance.getSelectedNodes();
+                if (this.mouseDownNode && this.selectedNodes.map(node => node.id).includes(this.mouseDownNode.data.id)) {
+                    this.moveSelectedNodes = true;
+                }
+                else {
+                    this.moveSelectedNodes = false;
+                }
+            }
+        });
+        Object.defineProperty(this, "handleMouseMove", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: (event) => {
+                // Avoid conflicts on moving node position in drawing process.
+                if (!this.mouseDownNode || event.buttons !== 1 || this.isDrawing)
+                    return;
+                const zoom = this.nvlInstance.getScale();
+                const dx = (event.clientX - this.mousePosition.x) / zoom * window.devicePixelRatio;
+                const dy = (event.clientY - this.mousePosition.y) / zoom * window.devicePixelRatio;
+                if (this.moveSelectedNodes) {
+                    this.nvlInstance.setNodePositions(this.selectedNodes.map((node) => ({ id: node.id, x: node.x +
+                            dx, y: node.y + dy, pinned: true })), true);
+                    this.callCallbackIfRegistered('onDrag', this.selectedNodes);
+                }
+                else {
+                    this.nvlInstance.setNodePositions([{ id: this.mouseDownNode.data.id, x: this.mouseDownNode.targetCoordinates.x + dx, y: this.mouseDownNode.targetCoordinates.y + dy, pinned: true }], true);
+                    this.callCallbackIfRegistered('onDrag', [this.mouseDownNode.data]);
+                }
+            }
+        });
+        Object.defineProperty(this, "handleMouseUp", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: () => {
+                this.mouseDownNode = null;
+                this.isDrawing = false;
+                this.selectedNodes = [];
+                this.moveSelectedNodes = false;
+            }
+        });
+        /**
+         * Removes all related event listeners from the container.
+         */
+        Object.defineProperty(this, "destroy", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: () => {
+                this.removeEventListener('mousedown', this.handleMouseDown);
+                this.removeEventListener('mousemove', this.handleMouseMove);
+                this.removeEventListener('mouseup', this.handleMouseUp);
+            }
+        });
+        this.mousePosition = { x: 0, y: 0 };
+        this.isDrawing = false;
+        this.selectedNodes = [];
+        this.moveSelectedNodes = false;
+        this.addEventListener('mousedown', this.handleMouseDown);
+        this.addEventListener('mousemove', this.handleMouseMove);
+        this.addEventListener('mouseup', this.handleMouseUp);
+    }
+}