@neo4j-nvl/interaction-handlers 0.2.1

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

@@ -0,0 +1,58 @@
+import { NVL } from '@neo4j-nvl/core';
+import { BaseInteraction } from './base';
+/**
+ * Callbacks for the pan interaction handler.
+ */
+export type PanInteractionCallbacks = {
+    /**
+     * Called when the canvas is panned.
+     * @param panning - The panning coordinates
+     */
+    onPan: (panning: {
+        x: number;
+        y: number;
+    }) => void;
+};
+/**
+ * Interaction handler for panning the canvas.
+ * Panning is achieved by clicking and dragging on the canvas.
+ *
+ * @example
+ * ```js
+ * const nvl = new NVL(container, nodes, relationships)
+ * const panInteraction = new PanInteraction(nvl)
+ *
+ * panInteraction.updateCallback('onPan', (panning) => {
+ *   console.log('Panning:', panning)
+ * })
+ */
+export declare class PanInteraction extends BaseInteraction<PanInteractionCallbacks> {
+    private mousePosition;
+    private targets;
+    private excludeNodeMargin;
+    private shouldPan;
+    /**
+     * Creates a new instance of the pan interaction handler.
+     * @param nvl - The NVL instance to attach the interaction handler to
+     */
+    constructor(nvl: NVL);
+    /**
+     * Updates which type of graph elements should hinder panning.
+     * @param targets - The graph elements that should hinder panning
+     * @param excludeNodeMargin - If true, the node margin will not hinder panning
+     * @note By default, panning is hindered by nodes and relationships.
+     *
+     * @example
+     * ```js
+     * // Pan canvas even when dragging on nodes and relationships
+     * panInteraction.updateTargets([], true)
+     * ```
+     */
+    updateTargets: (targets: Array<'node' | 'relationship'>, excludeNodeMargin: boolean) => void;
+    private handleMouseDown;
+    private handleMouseMove;
+    /**
+     * Removes the related event listeners from the canvas.
+     */
+    destroy(): void;
+}

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

@@ -0,0 +1,115 @@
+import { difference } from 'lodash';
+import { NODE_EDGE_WIDTH } from '../constants';
+import { BaseInteraction } from './base';
+/**
+ * Interaction handler for panning the canvas.
+ * Panning is achieved by clicking and dragging on the canvas.
+ *
+ * @example
+ * ```js
+ * const nvl = new NVL(container, nodes, relationships)
+ * const panInteraction = new PanInteraction(nvl)
+ *
+ * panInteraction.updateCallback('onPan', (panning) => {
+ *   console.log('Panning:', panning)
+ * })
+ */
+export class PanInteraction extends BaseInteraction {
+    /**
+     * Creates a new instance of the pan 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, "targets", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "excludeNodeMargin", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "shouldPan", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        /**
+         * Updates which type of graph elements should hinder panning.
+         * @param targets - The graph elements that should hinder panning
+         * @param excludeNodeMargin - If true, the node margin will not hinder panning
+         * @note By default, panning is hindered by nodes and relationships.
+         *
+         * @example
+         * ```js
+         * // Pan canvas even when dragging on nodes and relationships
+         * panInteraction.updateTargets([], true)
+         * ```
+         */
+        Object.defineProperty(this, "updateTargets", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: (targets, excludeNodeMargin) => {
+                this.targets = targets;
+                this.excludeNodeMargin = excludeNodeMargin;
+            }
+        });
+        Object.defineProperty(this, "handleMouseDown", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: (event) => {
+                const hits = this.nvlInstance.getHits(event, difference(['node', 'relationship'], this.targets), { hitNodeMarginWidth: this.excludeNodeMargin ? NODE_EDGE_WIDTH : 0 });
+                if (hits.nvlTargets.nodes.length > 0 || hits.nvlTargets.relationships.length > 0) {
+                    this.shouldPan = false;
+                }
+                else {
+                    this.mousePosition = { x: event.clientX, y: event.clientY };
+                    this.shouldPan = true;
+                }
+            }
+        });
+        Object.defineProperty(this, "handleMouseMove", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: (evt) => {
+                if (!this.shouldPan || evt.buttons !== 1) {
+                    return;
+                }
+                const zoom = this.nvlInstance.getScale();
+                const { x, y } = this.nvlInstance.getPan();
+                const dx = (evt.clientX - this.mousePosition.x) / zoom * window.devicePixelRatio;
+                const dy = (evt.clientY - this.mousePosition.y) / zoom * window.devicePixelRatio;
+                this.nvlInstance.setPan(x - dx, y - dy);
+                this.callCallbackIfRegistered('onPan', { x: x - dx, y: y - dy });
+                this.mousePosition = { x: evt.clientX, y: evt.clientY };
+            }
+        });
+        this.mousePosition = { x: 0, y: 0 };
+        this.targets = [];
+        this.excludeNodeMargin = false;
+        this.shouldPan = false;
+        this.addEventListener('mousedown', this.handleMouseDown, true);
+        this.addEventListener('mousemove', this.handleMouseMove, true);
+    }
+    /**
+     * Removes the related event listeners from the canvas.
+     */
+    destroy() {
+        this.removeEventListener('mousedown', this.handleMouseDown, true);
+        this.removeEventListener('mousemove', this.handleMouseMove, true);
+    }
+}

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

@@ -0,0 +1 @@
+export declare const generateUniqueId: (digit: number) => string;

package/lib/interaction-handlers/utils.js

@@ -0,0 +1 @@
+export const generateUniqueId = (digit) => Math.floor((Math.random() * Math.pow(10, digit))).toString();

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

@@ -0,0 +1,52 @@
+import { NVL } from '@neo4j-nvl/core';
+import { BaseInteraction } from './base';
+/**
+ * Callbacks for the zoom interaction handler.
+ */
+export type ZoomInteractionCallbacks = {
+    /**
+     * Called when the canvas is zoomed.
+     * @param zoomLevel - The zoom level
+     */
+    onZoom: (zoomLevel: number) => void;
+};
+/**
+ * Interaction handler for zooming the canvas.
+ * Zooming is achieved by scrolling the mouse wheel on the canvas.
+ *
+ * @example
+ * ```js
+ * const nvl = new NVL(container, nodes, relationships)
+ * const zoomInteraction = new ZoomInteraction(nvl)
+ *
+ * zoomInteraction.updateCallback('onZoom', (zoomLevel) => {
+ *   console.log('Zoom level:', zoomLevel)
+ * })
+ * ```
+ */
+export declare class ZoomInteraction extends BaseInteraction<ZoomInteractionCallbacks> {
+    private MinZoom;
+    private MaxZoom;
+    /**
+     * Creates a new instance of the zoom interaction handler.
+     * @param nvl - The NVL instance to attach the interaction handler to
+     */
+    constructor(nvl: NVL);
+    /**
+     * Throttled zoom function to avoid events happening too fast.
+     * @param event - The original mouse wheel event
+     * @note "Wheel" with a touchpad, the wheel is triggered event a lot,
+     * especially a lot of very small values.
+     * However, updating values in NVL instance takes time.
+     * Sometimes it lost the track of multiple events happening too soon.
+     * As a result, the zoom might lose its anchor point under touch pad.
+     * Therefore, the throttle is needed to avoid events happening too fast.
+     * @note The throttle is set to 25ms.
+     */
+    private throttledZoom;
+    private handleWheel;
+    /**
+     * Removes the relevant event listeners from the canvas.
+     */
+    destroy: () => void;
+}

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

@@ -0,0 +1,91 @@
+import { throttle } from 'lodash';
+import { BaseInteraction } from './base';
+/**
+ * Interaction handler for zooming the canvas.
+ * Zooming is achieved by scrolling the mouse wheel on the canvas.
+ *
+ * @example
+ * ```js
+ * const nvl = new NVL(container, nodes, relationships)
+ * const zoomInteraction = new ZoomInteraction(nvl)
+ *
+ * zoomInteraction.updateCallback('onZoom', (zoomLevel) => {
+ *   console.log('Zoom level:', zoomLevel)
+ * })
+ * ```
+ */
+export class ZoomInteraction extends BaseInteraction {
+    /**
+     * Creates a new instance of the zoom interaction handler.
+     * @param nvl - The NVL instance to attach the interaction handler to
+     */
+    constructor(nvl) {
+        super(nvl);
+        Object.defineProperty(this, "MinZoom", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "MaxZoom", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        /**
+         * Throttled zoom function to avoid events happening too fast.
+         * @param event - The original mouse wheel event
+         * @note "Wheel" with a touchpad, the wheel is triggered event a lot,
+         * especially a lot of very small values.
+         * However, updating values in NVL instance takes time.
+         * Sometimes it lost the track of multiple events happening too soon.
+         * As a result, the zoom might lose its anchor point under touch pad.
+         * Therefore, the throttle is needed to avoid events happening too fast.
+         * @note The throttle is set to 25ms.
+         */
+        Object.defineProperty(this, "throttledZoom", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: throttle((event) => {
+                const zoom = this.nvlInstance.getScale();
+                const { x, y } = this.nvlInstance.getPan();
+                const factor = event.deltaY / 500;
+                const newZoomTarget = zoom - factor * Math.min(1, zoom);
+                if (newZoomTarget < this.MinZoom || newZoomTarget > this.MaxZoom) {
+                    return;
+                }
+                this.nvlInstance.setZoom(newZoomTarget);
+                this.callCallbackIfRegistered('onZoom', newZoomTarget);
+                const { offsetX, offsetY } = this.nvlInstance.getMouseElementCoordinates(event);
+                const newPanX = x + (offsetX / zoom - offsetX / newZoomTarget);
+                const newPanY = y + (offsetY / zoom - offsetY / newZoomTarget);
+                this.nvlInstance.setPan(newPanX, newPanY);
+            }, 25, { leading: true })
+        });
+        Object.defineProperty(this, "handleWheel", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: (evt) => {
+                evt.preventDefault();
+                this.throttledZoom(evt);
+            }
+        });
+        /**
+         * Removes the relevant event listeners from the canvas.
+         */
+        Object.defineProperty(this, "destroy", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: () => {
+                this.removeEventListener('wheel', this.handleWheel);
+            }
+        });
+        this.MinZoom = 0.1;
+        this.MaxZoom = 5;
+        this.addEventListener('wheel', this.handleWheel);
+    }
+}

package/lib/overlay-renderer/overlay-renderer.d.ts

@@ -0,0 +1,12 @@
+export declare class OverlayRenderer {
+    private _ctx;
+    canvas: HTMLCanvasElement;
+    removeResizeListener: any;
+    constructor(canvasParent: HTMLElement);
+    _fixCanvasSize(canvas: HTMLCanvasElement): void;
+    _zoomAndPan(zoom: number, panX: number, panY: number): void;
+    drawBox(startX: number, startY: number, endX: number, endY: number): void;
+    drawNodeRing(x: number, y: number, radius: number, zoom: number, panX: number, panY: number): void;
+    clear(): void;
+    destroy(): void;
+}

package/lib/overlay-renderer/overlay-renderer.js

@@ -0,0 +1,111 @@
+import { drawCircleBand } from '@neo4j-nvl/core';
+import onResize from 'resizelistener';
+const marquee = {
+    frameWidth: 2,
+    frameColor: '#a9a9a9',
+    color: '#e0e0e0',
+    opacity: 0.5
+};
+export class OverlayRenderer {
+    constructor(canvasParent) {
+        Object.defineProperty(this, "_ctx", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "canvas", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "removeResizeListener", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        const canvas = document.createElement('canvas');
+        canvas.id = 'OVERLAY';
+        canvas.style.position = 'absolute';
+        canvas.style.top = '0';
+        canvas.style.bottom = '0';
+        canvas.style.left = '0';
+        canvas.style.right = '0';
+        // These are needed for touchpad zoom on Edge
+        canvas.style.touchAction = 'none';
+        // @ts-expect-error revisit later
+        canvas.style.msTouchAction = 'none';
+        canvasParent.appendChild(canvas);
+        const context = canvas.getContext('2d');
+        this._ctx = context;
+        this.canvas = canvas;
+        this.removeResizeListener = onResize(canvasParent, () => {
+            this._fixCanvasSize(canvas);
+        });
+        this._fixCanvasSize(canvas);
+    }
+    _fixCanvasSize(canvas) {
+        const parent = canvas.parentElement;
+        const rect = parent.getBoundingClientRect();
+        const width = rect.width;
+        const height = rect.height;
+        const devicePixelRatio = window.devicePixelRatio || 1;
+        canvas.width = width * devicePixelRatio;
+        canvas.height = height * devicePixelRatio;
+        canvas.style.width = `${width}px`;
+        canvas.style.height = `${height}px`;
+    }
+    // Can be extracted as a util
+    _zoomAndPan(zoom, panX, panY) {
+        const { width, height } = this.canvas;
+        this._ctx.translate((-width / 2) * zoom, (-height / 2) * zoom);
+        this._ctx.translate(-panX * zoom, -panY * zoom);
+        this._ctx.scale(zoom, zoom);
+        this._ctx.translate(width / 2 / zoom, height / 2 / zoom);
+        this._ctx.translate(width / 2, height / 2);
+    }
+    drawBox(startX, startY, endX, endY) {
+        this.clear();
+        this._ctx.save();
+        const devicePixelRatio = window.devicePixelRatio || 1;
+        const rect = this.canvas.getBoundingClientRect();
+        const localStartX = (startX - rect.left) * devicePixelRatio;
+        const localStartY = (startY - rect.top) * devicePixelRatio;
+        const localEndX = (endX - rect.left) * devicePixelRatio;
+        const localEndY = (endY - rect.top) * devicePixelRatio;
+        if (!this._ctx)
+            return;
+        this._ctx.beginPath();
+        this._ctx.rect(localStartX, localStartY, localEndX - localStartX, localEndY - localStartY);
+        this._ctx.closePath();
+        this._ctx.strokeStyle = marquee.frameColor;
+        this._ctx.lineWidth = marquee.frameWidth * devicePixelRatio;
+        this._ctx.fillStyle = marquee.color;
+        this._ctx.globalAlpha = marquee.opacity;
+        this._ctx.stroke();
+        this._ctx.fill();
+    }
+    drawNodeRing(x, y, radius, zoom, panX, panY) {
+        this.clear();
+        this._ctx.save();
+        const devicePixelRatio = window.devicePixelRatio || 1;
+        this._zoomAndPan(zoom, panX, panY);
+        // TODO: make 0.2 configurable from state and same as colour
+        const width = (radius !== null && radius !== void 0 ? radius : 25) * devicePixelRatio * 0.2;
+        drawCircleBand(this._ctx, x, y, (radius !== null && radius !== void 0 ? radius : 25) * devicePixelRatio, [{ width, color: 'blue' }]);
+        this._ctx.restore();
+    }
+    clear() {
+        const rect = this.canvas.getBoundingClientRect();
+        const devicePixelRatio = window.devicePixelRatio || 1;
+        if (!this._ctx)
+            return;
+        this._ctx.clearRect(0, 0, rect.width * devicePixelRatio, rect.height * devicePixelRatio);
+    }
+    destroy() {
+        this.removeResizeListener();
+        this.canvas.remove();
+    }
+}

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@neo4j-nvl/interaction-handlers",
+  "version": "0.2.1",
+  "license": "SEE LICENSE IN 'Neo4j Early Access Agreement - Visualization Library.pdf'",
+  "main": "lib/index.js",
+  "types": "lib/index.d.ts",
+  "files": [
+    "Neo4j Early Access Agreement - Visualization Library.pdf",
+    "lib"
+  ],
+  "scripts": {
+    "prebuild": "rm -rf lib/",
+    "build": "tsc",
+    "test": "jest",
+    "prepack": "cp ../../Neo4j\\ Early\\ Access\\ Agreement\\ -\\ Visualization\\ Library.pdf ./",
+    "postpack": "rm Neo4j\\ Early\\ Access\\ Agreement\\ -\\ Visualization\\ Library.pdf"
+  },
+  "typedoc": {
+    "entryPoint": "./src/index.ts",
+    "readmeFile": "./README.md",
+    "displayName": "Interaction Handlers",
+    "tsconfig": "./tsconfig.json"
+  },
+  "engines": {
+    "yarn": "^1.10.1"
+  },
+  "dependencies": {
+    "lodash": "^4.17.21",
+    "resizelistener": "^1.1.0"
+  },
+  "devDependencies": {
+    "@testing-library/jest-dom": "^5.16.5",
+    "@testing-library/react": "^13.4.0",
+    "@types/lodash": "^4.14.184"
+  }
+}