@neo4j-nvl/interaction-handlers 1.2.0 → 1.2.1

package/CHANGELOG.md

@@ -2,6 +2,22 @@
 
 All notable changes to NVL will be documented in this file. The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
+## [1.2.1] - 2026-07-28
+
+This 1.2.1 patch release contains several fixes and accessibility improvements.
+
+### Added
+* Outline when the canvas is focused while using the keyboard interaction handlers.
+
+### Changed
+* Renamed links in README from Explore to Neo4j Bloom.
+
+### Fixed
+* Aligned padding on svg and png export.
+* Aligned start behaviour of box and lasso select interaction handlers. 
+* Fixed static image wrapper React component returning incorrect height when using SVG format.
+* Fixed self-referencing relationship captions being misplaced on downward curves.
+
 ## [1.2.0] - 2026-05-27
 
 This 1.2.0 release introduces a new keyboard interaction handler and SVG support for the static image wrapper React component. It also includes several performance improvements for clustering and text/icon rendering, as well as several bug fixes.

package/README.md

@@ -1,6 +1,6 @@
 # Neo4j Visualization Library
 
-Welcome to the Neo4j Visualization Library, NVL for short. NVL is a collection of libraries that can be used to build custom graph visualizations like those used in [Neo4j Bloom and Explore(powered by Bloom)](https://neo4j.com/product/bloom/). NVL is written in TypeScript and can be used in any JavaScript project. It is also available as a React component that can be used in React applications.
+Welcome to the Neo4j Visualization Library, NVL for short. NVL is a collection of libraries that can be used to build custom graph visualizations like those used in [Neo4j Bloom](https://neo4j.com/product/bloom/). NVL is written in TypeScript and can be used in any JavaScript project. It is also available as a React component that can be used in React applications.
 
 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 more information about the NVL class in the [NVL base library](https://www.npmjs.com/package/@neo4j-nvl/base).
 

package/lib/__tests__/box-select-interaction.test.js

@@ -50,14 +50,15 @@ describe('BoxSelectInteraction', () => {
             resolve();
         });
     });
-    test.failing('will not start when node is below pointer when dragging', () => {
+    test('will not start when node is below pointer when dragging', () => {
         boxSelectInteraction.updateCallback('onBoxStarted', startCallback);
         boxSelectInteraction.updateCallback('onBoxSelect', selectCallback);
         expect(myNVL.getSelectedNodes()).toHaveLength(0);
         const gesture = [
             createMouseEvent('mousedown', 25, 25),
             createMouseEvent('mousemove', 50, 50),
-            createMouseEvent('mouseup', 50, 50)
+            createMouseEvent('mousemove', 200, 200),
+            createMouseEvent('mouseup', 200, 200)
         ];
         const container = myNVL.getContainer();
         gesture.forEach((e) => container.dispatchEvent(e));
@@ -67,6 +68,31 @@ describe('BoxSelectInteraction', () => {
             resolve();
         });
     });
+    test('can start box select when only a relationship is under the pointer', () => {
+        boxSelectInteraction.updateCallback('onBoxStarted', startCallback);
+        boxSelectInteraction.updateCallback('onBoxSelect', selectCallback);
+        const gesture = [
+            createMouseEvent('mousedown', 100, 100),
+            createMouseEvent('mousemove', 150, 100),
+            createMouseEvent('mouseup', 150, 100)
+        ];
+        const container = myNVL.getContainer();
+        gesture.forEach((e) => container.dispatchEvent(e));
+        return new Promise((resolve) => {
+            expect(startCallback).toHaveBeenCalledTimes(1);
+            expect(selectCallback).toHaveBeenCalledTimes(1);
+            resolve();
+        });
+    });
+    test('does not fire callbacks when clicking directly on a relationship without dragging', () => {
+        boxSelectInteraction.updateCallback('onBoxStarted', startCallback);
+        boxSelectInteraction.updateCallback('onBoxSelect', selectCallback);
+        const container = myNVL.getContainer();
+        container.dispatchEvent(createMouseEvent('mousedown', 112, 112));
+        container.dispatchEvent(createMouseEvent('mouseup', 112, 112));
+        expect(startCallback).not.toHaveBeenCalled();
+        expect(selectCallback).not.toHaveBeenCalled();
+    });
     test('box selection should disable text selection until mouse release', () => {
         const container = myNVL.getContainer();
         boxSelectInteraction.updateCallback('onBoxSelect', boxSelectCallbackMock);

package/lib/__tests__/lasso-interaction.test.js

@@ -78,12 +78,39 @@ describe('LassoInteraction', () => {
             resolve();
         });
     });
+    test('does not fire started or select callbacks when movement stays below drag threshold', () => {
+        lassoInteraction.updateCallback('onLassoStarted', startCallback);
+        lassoInteraction.updateCallback('onLassoSelect', selectCallback);
+        const container = myNVL.getContainer();
+        container.dispatchEvent(createMouseEvent('mousedown', 100, 100));
+        container.dispatchEvent(createMouseEvent('mousemove', 100, 103));
+        container.dispatchEvent(createMouseEvent('mouseup', 100, 103));
+        expect(startCallback).not.toHaveBeenCalled();
+        expect(selectCallback).not.toHaveBeenCalled();
+    });
+    test('can start lasso when only a relationship is under the pointer', () => {
+        lassoInteraction.updateCallback('onLassoStarted', startCallback);
+        lassoInteraction.updateCallback('onLassoSelect', selectCallback);
+        const gesture = [
+            createMouseEvent('mousedown', 100, 100),
+            createMouseEvent('mousemove', 150, 100),
+            createMouseEvent('mousemove', 50, 150),
+            createMouseEvent('mouseup', 100, 100)
+        ];
+        const container = myNVL.getContainer();
+        gesture.forEach((e) => container.dispatchEvent(e));
+        return new Promise((resolve) => {
+            expect(startCallback).toHaveBeenCalledTimes(1);
+            expect(selectCallback).toHaveBeenCalledTimes(1);
+            resolve();
+        });
+    });
     test('will not start when node is below pointer when dragging', () => {
         lassoInteraction.updateCallback('onLassoStarted', startCallback);
         lassoInteraction.updateCallback('onLassoSelect', selectCallback);
         expect(myNVL.getSelectedNodes()).toHaveLength(0);
         const gesture1 = [
-            createMouseEvent('mousedown', 10, 10),
+            createMouseEvent('mousedown', 25, 25),
             createMouseEvent('mousemove', 50, 0),
             createMouseEvent('mousemove', 20, 50),
             createMouseEvent('mouseup', 0, 0)
@@ -95,6 +122,15 @@ describe('LassoInteraction', () => {
             resolve();
         });
     });
+    test('does not fire callbacks when clicking directly on a relationship without dragging', () => {
+        lassoInteraction.updateCallback('onLassoStarted', startCallback);
+        lassoInteraction.updateCallback('onLassoSelect', selectCallback);
+        const container = myNVL.getContainer();
+        container.dispatchEvent(createMouseEvent('mousedown', 112, 112));
+        container.dispatchEvent(createMouseEvent('mouseup', 112, 112));
+        expect(startCallback).not.toHaveBeenCalled();
+        expect(selectCallback).not.toHaveBeenCalled();
+    });
     test('test for line crossing utility function', () => {
         const res1 = checkLinesCrossing([0, 0], [10, 10], [10, 0], [0, 10]);
         expect(res1).toBeTruthy();

package/lib/__tests__/utils.test.d.ts

@@ -0,0 +1 @@
+export {};

package/lib/__tests__/utils.test.js

@@ -0,0 +1,19 @@
+import { isDraggingDistance, isDraggingMovement } from '../interaction-handlers/utils';
+describe('interaction utils', () => {
+    test('returns true when movement reaches threshold on either axis', () => {
+        expect(isDraggingDistance({ x: 0, y: 0 }, { x: 10, y: 0 })).toBe(true);
+        expect(isDraggingDistance({ x: 0, y: 0 }, { x: 0, y: 10 })).toBe(true);
+    });
+    test('returns true for diagonal movement whose combined movement reaches threshold', () => {
+        expect(isDraggingDistance({ x: 0, y: 0 }, { x: 2, y: 2 })).toBe(false);
+        expect(isDraggingDistance({ x: 0, y: 0 }, { x: 7, y: 7 })).toBe(true);
+        expect(isDraggingDistance({ x: 0, y: 0 }, { x: 8, y: 8 })).toBe(true);
+    });
+    test('applies the same threshold logic to mouse events', () => {
+        expect(isDraggingMovement(new MouseEvent('mousemove', { clientX: 10, clientY: 0 }), { x: 0, y: 0 })).toBe(true);
+        expect(isDraggingMovement(new MouseEvent('mousemove', { clientX: 0, clientY: 10 }), { x: 0, y: 0 })).toBe(true);
+        expect(isDraggingMovement(new MouseEvent('mousemove', { clientX: 2, clientY: 2 }), { x: 0, y: 0 })).toBe(false);
+        expect(isDraggingMovement(new MouseEvent('mousemove', { clientX: 7, clientY: 7 }), { x: 0, y: 0 })).toBe(true);
+        expect(isDraggingMovement(new MouseEvent('mousemove', { clientX: 8, clientY: 8 }), { x: 0, y: 0 })).toBe(true);
+    });
+});

package/lib/interaction-handlers/box-select-interaction.d.ts

@@ -38,8 +38,10 @@ export type BoxSelectInteractionCallbacks = {
 export declare class BoxSelectInteraction extends BaseInteraction<BoxSelectInteractionOptions> {
     private mousePosition;
     private startWorldPosition;
+    private startClientPosition;
     private overlayRenderer;
     private isBoxSelecting;
+    private boxSelectPending;
     /**
      * Creates a new instance of the multi-select interaction handler.
      * @param nvl - The NVL instance to attach the interaction handler to.
@@ -54,5 +56,6 @@ export declare class BoxSelectInteraction extends BaseInteraction<BoxSelectInter
      * Removes all related event listeners and the overlay renderer for the box.
      */
     destroy(): void;
+    private activateBoxSelect;
     private turnOnBoxSelect;
 }

package/lib/interaction-handlers/box-select-interaction.js

@@ -1,7 +1,7 @@
 import { NODE_EDGE_WIDTH } from '../constants';
 import { OverlayRenderer } from '../overlay-renderer/overlay-renderer';
 import { BaseInteraction } from './base';
-import { getCanvasPosition, getWorldPosition } from './utils';
+import { getCanvasPosition, getWorldPosition, isDraggingMovement } from './utils';
 /**
  * An interaction handler for multi-selecting nodes and relationships.
  * When dragging the cursor, it draws a box on the scene and all nodes and relationships inside the box are selected.
@@ -11,8 +11,10 @@ import { getCanvasPosition, getWorldPosition } from './utils';
 export class BoxSelectInteraction extends BaseInteraction {
     mousePosition = { x: 0, y: 0 };
     startWorldPosition = { x: 0, y: 0 };
+    startClientPosition = { x: 0, y: 0 };
     overlayRenderer;
     isBoxSelecting = false;
+    boxSelectPending = false;
     /**
      * Creates a new instance of the multi-select interaction handler.
      * @param nvl - The NVL instance to attach the interaction handler to.
@@ -28,6 +30,7 @@ export class BoxSelectInteraction extends BaseInteraction {
     handleMouseDown = (event) => {
         if (event.button !== 0) {
             this.isBoxSelecting = false;
+            this.boxSelectPending = false;
             return;
         }
         this.turnOnBoxSelect(event);
@@ -36,9 +39,12 @@ export class BoxSelectInteraction extends BaseInteraction {
         if (this.isBoxSelecting) {
             const curPos = getCanvasPosition(this.containerInstance, event);
             this.overlayRenderer.drawBox(this.mousePosition.x, this.mousePosition.y, curPos.x, curPos.y);
+            return;
         }
-        else if (event.buttons === 1) {
-            this.turnOnBoxSelect(event);
+        if (this.boxSelectPending && event.buttons === 1) {
+            if (isDraggingMovement(event, this.startClientPosition)) {
+                this.activateBoxSelect(event);
+            }
         }
     };
     getHitsInBox = (startPos, endPos) => {
@@ -71,6 +77,7 @@ export class BoxSelectInteraction extends BaseInteraction {
     };
     endBoxSelect = (event) => {
         if (!this.isBoxSelecting) {
+            this.boxSelectPending = false;
             return;
         }
         this.isBoxSelecting = false;
@@ -94,20 +101,28 @@ export class BoxSelectInteraction extends BaseInteraction {
         this.removeEventListener('mouseup', this.endBoxSelect, true);
         this.overlayRenderer.destroy();
     }
+    activateBoxSelect = (event) => {
+        this.boxSelectPending = false;
+        this.isBoxSelecting = true;
+        this.toggleGlobalTextSelection(false, this.endBoxSelect);
+        this.callCallbackIfRegistered('onBoxStarted', event);
+        if (this.currentOptions.selectOnRelease === true) {
+            this.nvlInstance.deselectAll();
+        }
+        const curPos = getCanvasPosition(this.containerInstance, event);
+        this.overlayRenderer.drawBox(this.mousePosition.x, this.mousePosition.y, curPos.x, curPos.y);
+    };
     turnOnBoxSelect(event) {
         this.mousePosition = getCanvasPosition(this.containerInstance, event);
         this.startWorldPosition = getWorldPosition(this.nvlInstance, this.mousePosition);
         const hits = this.nvlInstance.getHits(event, ['node'], { hitNodeMarginWidth: NODE_EDGE_WIDTH });
         if (hits.nvlTargets.nodes.length > 0) {
             this.isBoxSelecting = false;
+            this.boxSelectPending = false;
         }
         else {
-            this.isBoxSelecting = true;
-            this.toggleGlobalTextSelection(false, this.endBoxSelect);
-            this.callCallbackIfRegistered('onBoxStarted', event);
-            if (this.currentOptions.selectOnRelease === true) {
-                this.nvlInstance.deselectAll();
-            }
+            this.startClientPosition = { x: event.clientX, y: event.clientY };
+            this.boxSelectPending = true;
         }
     }
 }

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

@@ -27,6 +27,8 @@ export type KeyboardInteractionOptions = {
     exitGraphKey?: string[];
     /** Key combo for opening the context menu on the focused element. Default: `['Shift', 'F10']` */
     contextMenuKey?: string[];
+    /** The color of the outline shown when the canvas receives keyboard focus. Default: `'#30839D'` */
+    canvasOutlineColor?: string;
 };
 /**
  * Callbacks for the keyboard interaction handler.
@@ -114,6 +116,8 @@ export declare class KeyboardInteraction extends BaseInteraction<KeyboardInterac
      * Returns the currently focused element, if any.
      */
     getFocused(): Node | Relationship | undefined;
+    private setCanvasOutline;
+    private clearCanvasOutline;
     private handleFocusIn;
     private handleFocusOut;
     private handleKeyDown;

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

@@ -4,7 +4,8 @@ const DEFAULT_OPTIONS = {
     navigateForwardKey: ['Tab'],
     navigateBackwardKey: ['Shift', 'Tab'],
     exitGraphKey: ['Escape'],
-    contextMenuKey: ['Shift', 'F10']
+    contextMenuKey: ['Shift', 'F10'],
+    canvasOutlineColor: '#30839D'
 };
 /**
  * Checks whether a keyboard event matches a key combo array.
@@ -79,11 +80,25 @@ export class KeyboardInteraction extends BaseInteraction {
         }
         return this.nvlInstance.getRelationships().find((r) => r.id === this.focusedElementId);
     }
+    setCanvasOutline() {
+        const container = this.containerInstance;
+        if (container.matches(':focus-visible')) {
+            container.style.outline = `2px solid ${this.resolvedOptions.canvasOutlineColor}`;
+            container.style.outlineOffset = '-2px';
+        }
+    }
+    clearCanvasOutline() {
+        const container = this.containerInstance;
+        container.style.outline = 'none';
+        container.style.outlineOffset = '';
+    }
     handleFocusIn = (event) => {
+        this.setCanvasOutline();
         this.callCallbackIfRegistered('onCanvasFocus', event);
     };
     handleFocusOut = (event) => {
         this.callCallbackIfRegistered('onCanvasBlur', event);
+        this.clearCanvasOutline();
     };
     handleKeyDown = (event) => {
         const focusedElement = this.getFocused();
@@ -108,6 +123,7 @@ export class KeyboardInteraction extends BaseInteraction {
             }
         }
         else if (matchesKeyCombo(event, exitGraphKey)) {
+            this.setCanvasOutline();
             if (focusedElement !== undefined) {
                 event.preventDefault();
                 this.clearFocus(event);
@@ -150,6 +166,7 @@ export class KeyboardInteraction extends BaseInteraction {
         // Notify about the newly focused element
         const newElement = this.getFocused();
         if (newElement !== undefined) {
+            this.clearCanvasOutline();
             if (isNode) {
                 this.callCallbackIfRegistered('onNodeFocus', newElement, event);
             }
@@ -179,6 +196,7 @@ export class KeyboardInteraction extends BaseInteraction {
         this.removeEventListener('keyup', this.handleKeyUp);
         this.removeEventListener('focusin', this.handleFocusIn);
         this.removeEventListener('focusout', this.handleFocusOut);
+        this.clearCanvasOutline();
         if (this.addedTabindex) {
             this.containerInstance.removeAttribute('tabindex');
         }

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

@@ -60,6 +60,9 @@ export declare const checkPointInside: (x: number, y: number, vs: Point[]) => bo
  */
 export declare class LassoInteraction extends BaseInteraction<LassoInteractionOptions> {
     private active;
+    private lassoPending;
+    private startClientPosition;
+    private pendingPointerCanvas;
     private points;
     private overlayRenderer;
     /**
@@ -71,6 +74,7 @@ export declare class LassoInteraction extends BaseInteraction<LassoInteractionOp
     private startLasso;
     private handleMouseDown;
     private handleDrag;
+    private activateLasso;
     private handleMouseUp;
     private getLassoItems;
     private endLasso;

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

@@ -2,7 +2,7 @@ import concaveman from 'concaveman';
 import { NODE_EDGE_WIDTH } from '../constants';
 import { OverlayRenderer } from '../overlay-renderer/overlay-renderer';
 import { BaseInteraction } from './base';
-import { getCanvasPosition, getWorldPosition } from './utils';
+import { getCanvasPosition, getWorldPosition, isDraggingMovement } from './utils';
 const pointDist = 10;
 const shapeShowTime = 500;
 /**
@@ -73,6 +73,9 @@ export const checkPointInside = (x, y, vs) => {
  */
 export class LassoInteraction extends BaseInteraction {
     active = false;
+    lassoPending = false;
+    startClientPosition = { x: 0, y: 0 };
+    pendingPointerCanvas = { x: 0, y: 0 };
     points = [];
     overlayRenderer;
     /**
@@ -91,19 +94,16 @@ export class LassoInteraction extends BaseInteraction {
         const hits = this.nvlInstance.getHits(event, ['node'], { hitNodeMarginWidth: NODE_EDGE_WIDTH });
         if (hits.nvlTargets.nodes.length > 0) {
             this.active = false;
+            this.lassoPending = false;
         }
         else {
-            this.active = true;
-            this.points = [getCanvasPosition(this.containerInstance, event)];
-            this.toggleGlobalTextSelection(false, this.endLasso);
-            this.callCallbackIfRegistered('onLassoStarted', event);
-            if (this.currentOptions.selectOnRelease === true) {
-                this.nvlInstance.deselectAll();
-            }
+            this.lassoPending = true;
+            this.startClientPosition = { x: event.clientX, y: event.clientY };
+            this.pendingPointerCanvas = getCanvasPosition(this.containerInstance, event);
         }
     };
     handleMouseDown = (event) => {
-        if (event.button === 0 && !this.active) {
+        if (event.button === 0 && !this.active && !this.lassoPending) {
             this.startLasso(event);
         }
     };
@@ -120,9 +120,31 @@ export class LassoInteraction extends BaseInteraction {
                 this.points.push(pos);
                 this.overlayRenderer.drawLasso(this.points, true, false);
             }
+            return;
+        }
+        if (this.lassoPending && event.buttons === 1) {
+            if (isDraggingMovement(event, this.startClientPosition)) {
+                this.activateLasso(event);
+            }
+        }
+    };
+    activateLasso = (event) => {
+        this.lassoPending = false;
+        this.active = true;
+        const pos = getCanvasPosition(this.containerInstance, event);
+        this.points = [this.pendingPointerCanvas, pos];
+        this.toggleGlobalTextSelection(false, this.endLasso);
+        this.callCallbackIfRegistered('onLassoStarted', event);
+        if (this.currentOptions.selectOnRelease === true) {
+            this.nvlInstance.deselectAll();
         }
+        this.overlayRenderer.drawLasso(this.points, true, false);
     };
     handleMouseUp = (event) => {
+        if (!this.active) {
+            this.lassoPending = false;
+            return;
+        }
         this.points.push(getCanvasPosition(this.containerInstance, event));
         this.endLasso(event);
     };

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

@@ -1,6 +1,7 @@
 import type { NVL, Point } from '@neo4j-nvl/base';
 export declare const generateUniqueId: (digit: number) => string;
-export declare const isDraggingMovement: (event: MouseEvent, originalPosition: Point) => boolean;
+export declare const isDraggingDistance: (startPoint: Point, endPoint: Point) => boolean;
+export declare const isDraggingMovement: (event: MouseEvent, point: Point) => boolean;
 export declare const getCanvasPosition: (canvas: HTMLElement, mouseEvent: MouseEvent) => Point;
 export declare const getCanvasCenterOffset: (canvas: HTMLElement, mouseEvent: MouseEvent) => Point;
 export declare const getWorldPosition: (nvl: NVL, pos: Point) => Point;

package/lib/interaction-handlers/utils.js

@@ -1,14 +1,17 @@
 import { DRAG_THRESHOLD } from '../constants';
 export const generateUniqueId = (digit) => Math.floor(Math.random() * Math.pow(10, digit)).toString();
-export const isDraggingMovement = (event, originalPosition) => {
-    const diffX = Math.abs(event.clientX - originalPosition.x);
-    const diffY = Math.abs(event.clientY - originalPosition.y);
+export const isDraggingDistance = (startPoint, endPoint) => {
+    const diffX = Math.abs(endPoint.x - startPoint.x);
+    const diffY = Math.abs(endPoint.y - startPoint.y);
     if (diffX > DRAG_THRESHOLD || diffY > DRAG_THRESHOLD) {
         return true;
     }
     const distanceSquared = Math.pow(diffX, 2) + Math.pow(diffY, 2);
     return distanceSquared > DRAG_THRESHOLD;
 };
+export const isDraggingMovement = (event, point) => {
+    return isDraggingDistance(point, { x: event.clientX, y: event.clientY });
+};
 export const getCanvasPosition = (canvas, mouseEvent) => {
     const rect = canvas.getBoundingClientRect();
     const devicePixelRatio = window.devicePixelRatio || 1;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@neo4j-nvl/interaction-handlers",
-  "version": "1.2.0",
+  "version": "1.2.1",
   "license": "SEE LICENSE IN 'LICENSE.txt'",
   "homepage": "https://neo4j.com/docs/nvl/current/",
   "description": "Interaction handlers for the Neo4j Visualization Library",
@@ -27,7 +27,7 @@
     "eslint": "yarn global:eslint ./src/"
   },
   "dependencies": {
-    "@neo4j-nvl/base": "1.2.0",
+    "@neo4j-nvl/base": "1.2.1",
     "concaveman": "1.2.1",
     "lodash": "4.18.1"
   },