@neo4j-nvl/interaction-handlers 1.2.2 → 2.0.0

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

@@ -19,6 +19,7 @@ describe('HoverInteraction', () => {
         hoverInteraction.destroy();
         myNVL.destroy();
         callbackMock.mockReset();
+        jest.restoreAllMocks();
     });
     describe('handleHover', () => {
         it('should register hover event on canvas', () => {
@@ -27,7 +28,7 @@ describe('HoverInteraction', () => {
                 clientY: 10
             });
             hoverInteraction.handleHover(mouseEvent);
-            expect(callbackMock).toHaveBeenCalledWith(undefined, { nodes: [], relationships: [] }, mouseEvent);
+            expect(callbackMock).toHaveBeenCalledWith(undefined, { nodes: [], relationships: [], clusters: [] }, mouseEvent);
             expect(callbackMock).toHaveBeenCalledTimes(1);
         });
         it('should register hover event for node', () => {
@@ -55,7 +56,8 @@ describe('HoverInteraction', () => {
                         toTargetCoordinates: { x: 200, y: 200 },
                         pointerCoordinates: { x: 100, y: 100 }
                     }
-                ]
+                ],
+                clusters: []
             }, mouseEvent);
             expect(callbackMock).toHaveBeenCalledTimes(1);
         });
@@ -75,7 +77,8 @@ describe('HoverInteraction', () => {
                         toTargetCoordinates: { x: 200, y: 200 },
                         pointerCoordinates: { x: 150, y: 150 }
                     }
-                ]
+                ],
+                clusters: []
             }, mouseEvent);
             expect(callbackMock).toHaveBeenCalledTimes(1);
         });
@@ -104,7 +107,8 @@ describe('HoverInteraction', () => {
                         toTargetCoordinates: { x: 200, y: 200 },
                         pointerCoordinates: { x: 100, y: 100 }
                     }
-                ]
+                ],
+                clusters: []
             }, mouseEvent);
             expect(callbackMock).toHaveBeenCalledTimes(1);
             const mouseEvent2 = new MouseEvent('mousemove', {
@@ -131,9 +135,10 @@ describe('HoverInteraction', () => {
                         toTargetCoordinates: { x: 200, y: 200 },
                         pointerCoordinates: { x: 100, y: 100 }
                     }
-                ]
+                ],
+                clusters: []
             }, mouseEvent2);
-            expect(callbackMock).toHaveBeenCalledWith(undefined, { nodes: [], relationships: [] }, mouseEvent2);
+            expect(callbackMock).toHaveBeenCalledWith(undefined, { nodes: [], relationships: [], clusters: [] }, mouseEvent2);
             expect(callbackMock).toHaveBeenCalledTimes(2);
         });
         it('should register un-hover event for relationship', () => {
@@ -152,7 +157,8 @@ describe('HoverInteraction', () => {
                         toTargetCoordinates: { x: 200, y: 200 },
                         pointerCoordinates: { x: 150, y: 150 }
                     }
-                ]
+                ],
+                clusters: []
             }, mouseEvent);
             expect(callbackMock).toHaveBeenCalledTimes(1);
             const mouseEvent2 = new MouseEvent('mousemove', {
@@ -170,9 +176,10 @@ describe('HoverInteraction', () => {
                         toTargetCoordinates: { x: 200, y: 200 },
                         pointerCoordinates: { x: 150, y: 150 }
                     }
-                ]
+                ],
+                clusters: []
             }, mouseEvent2);
-            expect(callbackMock).toHaveBeenCalledWith(undefined, { nodes: [], relationships: [] }, mouseEvent2);
+            expect(callbackMock).toHaveBeenCalledWith(undefined, { nodes: [], relationships: [], clusters: [] }, mouseEvent2);
             expect(callbackMock).toHaveBeenCalledTimes(2);
         });
         it('should un-hover node and hover relationships when moving mouse from node to relationship', () => {
@@ -200,7 +207,8 @@ describe('HoverInteraction', () => {
                         toTargetCoordinates: { x: 200, y: 200 },
                         pointerCoordinates: { x: 100, y: 100 }
                     }
-                ]
+                ],
+                clusters: []
             }, mouseEvent);
             expect(callbackMock).toHaveBeenCalledTimes(1);
             const mouseEvent2 = new MouseEvent('mousemove', {
@@ -227,7 +235,8 @@ describe('HoverInteraction', () => {
                         toTargetCoordinates: { x: 200, y: 200 },
                         pointerCoordinates: { x: 100, y: 100 }
                     }
-                ]
+                ],
+                clusters: []
             }, mouseEvent2);
             expect(callbackMock).toHaveBeenCalledWith({ id: '10', from: '0', to: '1', hovered: true }, {
                 nodes: [],
@@ -239,7 +248,8 @@ describe('HoverInteraction', () => {
                         toTargetCoordinates: { x: 200, y: 200 },
                         pointerCoordinates: { x: 150, y: 150 }
                     }
-                ]
+                ],
+                clusters: []
             }, mouseEvent2);
             expect(callbackMock).toHaveBeenCalledTimes(2);
         });
@@ -259,7 +269,8 @@ describe('HoverInteraction', () => {
                         toTargetCoordinates: { x: 200, y: 200 },
                         pointerCoordinates: { x: 150, y: 150 }
                     }
-                ]
+                ],
+                clusters: []
             }, mouseEvent);
             expect(callbackMock).toHaveBeenCalledTimes(1);
             const mouseEvent2 = new MouseEvent('mousemove', {
@@ -286,7 +297,8 @@ describe('HoverInteraction', () => {
                         toTargetCoordinates: { x: 200, y: 200 },
                         pointerCoordinates: { x: 100, y: 100 }
                     }
-                ]
+                ],
+                clusters: []
             }, mouseEvent2);
             expect(callbackMock).toHaveBeenCalledWith({ id: '10', from: '0', to: '1', hovered: false }, {
                 nodes: [],
@@ -298,9 +310,65 @@ describe('HoverInteraction', () => {
                         toTargetCoordinates: { x: 200, y: 200 },
                         pointerCoordinates: { x: 150, y: 150 }
                     }
-                ]
+                ],
+                clusters: []
             }, mouseEvent2);
             expect(callbackMock).toHaveBeenCalledTimes(2);
         });
+        it('should report a hovered cluster', () => {
+            const nvlTargets = {
+                nodes: [],
+                relationships: [],
+                clusters: [
+                    {
+                        data: { id: 'group-a', nodeIds: ['0', '1'] },
+                        pointerCoordinates: { x: 50, y: 50 },
+                        hull: [
+                            { x: 0, y: 0 },
+                            { x: 100, y: 0 },
+                            { x: 100, y: 100 },
+                            { x: 0, y: 100 }
+                        ]
+                    }
+                ]
+            };
+            jest.spyOn(myNVL, 'getHits').mockImplementation((event) => Object.assign(event, { nvlTargets }));
+            const mouseEvent = new MouseEvent('mousemove', { clientX: 50, clientY: 50 });
+            hoverInteraction.handleHover(mouseEvent);
+            expect(callbackMock).toHaveBeenCalledWith(undefined, nvlTargets, mouseEvent);
+            expect(callbackMock).toHaveBeenCalledTimes(1);
+        });
+        it('should keep the cluster in the hit elements when hovering one of its nodes', () => {
+            const nvlTargets = {
+                nodes: [
+                    {
+                        data: { id: '0', x: 100, y: 100 },
+                        distance: 0,
+                        targetCoordinates: { x: 100, y: 100 },
+                        pointerCoordinates: { x: 100, y: 100 },
+                        distanceVector: { x: 0, y: 0 },
+                        insideNode: true
+                    }
+                ],
+                relationships: [],
+                clusters: [
+                    {
+                        data: { id: 'group-a', nodeIds: ['0', '1'] },
+                        pointerCoordinates: { x: 100, y: 100 },
+                        hull: [
+                            { x: 0, y: 0 },
+                            { x: 200, y: 0 },
+                            { x: 200, y: 200 },
+                            { x: 0, y: 200 }
+                        ]
+                    }
+                ]
+            };
+            jest.spyOn(myNVL, 'getHits').mockImplementation((event) => Object.assign(event, { nvlTargets }));
+            const mouseEvent = new MouseEvent('mousemove', { clientX: 100, clientY: 100 });
+            hoverInteraction.handleHover(mouseEvent);
+            expect(callbackMock).toHaveBeenCalledWith({ id: '0', x: 100, y: 100 }, nvlTargets, mouseEvent);
+            expect(callbackMock).toHaveBeenCalledTimes(1);
+        });
     });
 });

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

@@ -6,7 +6,6 @@ describe('ZoomInteraction', () => {
     let zoomInteraction;
     let myNVL;
     let myNvlContainer;
-    const zoomCallbackMock = jest.fn();
     const zoomAndPanCallbackMock = jest.fn();
     beforeEach(() => {
         myNVL = new NVL(document.createElement('div'), [], [], { disableWebGL: true, initialZoom: 1, layout: 'free' });
@@ -16,7 +15,6 @@ describe('ZoomInteraction', () => {
     afterEach(() => {
         zoomInteraction.destroy();
         myNVL.destroy();
-        zoomCallbackMock.mockReset();
         zoomAndPanCallbackMock.mockReset();
     });
     const simulateWheelEvent = async (container, deltaY, delay = 50, eventOptions = {}) => {
@@ -38,31 +36,33 @@ describe('ZoomInteraction', () => {
     };
     describe('Scrolling', () => {
         test('zooming in should increase the scale', async () => {
-            zoomInteraction.updateCallback('onZoom', zoomCallbackMock);
+            zoomInteraction.updateCallback('onZoomAndPan', zoomAndPanCallbackMock);
             const initialScale = myNVL.getScale();
             const container = myNVL.getContainer();
             await simulateWheelEvent(container, -100);
-            expect(zoomCallbackMock).toHaveBeenCalledTimes(1);
+            expect(zoomAndPanCallbackMock).toHaveBeenCalledTimes(1);
             const newScale = myNVL.getScale();
             expect(newScale).toBeGreaterThan(initialScale);
             expect(newScale).toBe(1.2);
         });
         test('zooming out should decrease the scale', async () => {
-            zoomInteraction.updateCallback('onZoom', zoomCallbackMock);
+            zoomInteraction.updateCallback('onZoomAndPan', zoomAndPanCallbackMock);
             const initialScale = myNVL.getScale();
             await simulateWheelEvent(myNvlContainer, 100);
-            expect(zoomCallbackMock).toHaveBeenCalledTimes(1);
+            expect(zoomAndPanCallbackMock).toHaveBeenCalledTimes(1);
             const newScale = myNVL.getScale();
             expect(newScale).toBeLessThan(initialScale);
             expect(newScale).toBe(0.8);
         });
-        test('zoom callback should be called with the correct zoom level', async () => {
-            zoomInteraction.updateCallback('onZoom', zoomCallbackMock);
+        test('zoom callback should be called with the correct zoom level and pan values', async () => {
+            zoomInteraction.updateCallback('onZoomAndPan', zoomAndPanCallbackMock);
             const wheelEvent = await simulateWheelEvent(myNvlContainer, -100);
-            expect(zoomCallbackMock).toHaveBeenCalledTimes(1);
-            const zoomCallbackMockArguments = zoomCallbackMock.mock.calls[0] ?? [];
-            expect(zoomCallbackMockArguments[0]).toBe(1.2);
-            expect(zoomCallbackMockArguments[1]).toBe(wheelEvent);
+            expect(zoomAndPanCallbackMock).toHaveBeenCalledTimes(1);
+            const zoomAndPanCallbackMockArguments = zoomAndPanCallbackMock.mock.calls[0] ?? [];
+            expect(zoomAndPanCallbackMockArguments[0]).toBe(1.2);
+            expect(zoomAndPanCallbackMockArguments[1]).toBe(25);
+            expect(zoomAndPanCallbackMockArguments[2]).toBe(25);
+            expect(zoomAndPanCallbackMockArguments[3]).toBe(wheelEvent);
         });
         test('zooming should adjust pan to mouse position', async () => {
             const initialPan = myNVL.getPan();
@@ -92,53 +92,27 @@ describe('ZoomInteraction', () => {
             expect(newScale).toBeGreaterThan(2.5);
             expect(newScale).toBeLessThan(2.7);
         });
-        test('onZoomAndPan callback should be called with zoom level and pan values', async () => {
-            zoomInteraction.updateCallback('onZoomAndPan', zoomAndPanCallbackMock);
-            const wheelEvent = await simulateWheelEvent(myNvlContainer, -100);
-            expect(zoomAndPanCallbackMock).toHaveBeenCalledTimes(1);
-            const zoomAndPanCallbackMockArguments = zoomAndPanCallbackMock.mock.calls[0] ?? [];
-            expect(zoomAndPanCallbackMockArguments[0]).toBe(1.2);
-            expect(zoomAndPanCallbackMockArguments[1]).toBe(25);
-            expect(zoomAndPanCallbackMockArguments[2]).toBe(25);
-            expect(zoomAndPanCallbackMockArguments[3]).toBe(wheelEvent);
-            expect(zoomCallbackMock).toHaveBeenCalledTimes(0);
-        });
-        test('both callbacks should be called when both are registered', async () => {
-            zoomInteraction.updateCallback('onZoom', zoomCallbackMock);
-            zoomInteraction.updateCallback('onZoomAndPan', zoomAndPanCallbackMock);
-            const wheelEvent = await simulateWheelEvent(myNvlContainer, -100);
-            expect(zoomCallbackMock).toHaveBeenCalledTimes(1);
-            expect(zoomAndPanCallbackMock).toHaveBeenCalledTimes(1);
-            const zoomCallbackMockArguments = zoomCallbackMock.mock.calls[0] ?? [];
-            expect(zoomCallbackMockArguments[0]).toBe(1.2);
-            expect(zoomCallbackMockArguments[1]).toBe(wheelEvent);
-            const zoomAndPanCallbackMockArguments = zoomAndPanCallbackMock.mock.calls[0] ?? [];
-            expect(zoomAndPanCallbackMockArguments[0]).toBe(1.2);
-            expect(zoomAndPanCallbackMockArguments[1]).toBe(25);
-            expect(zoomAndPanCallbackMockArguments[2]).toBe(25);
-            expect(zoomAndPanCallbackMockArguments[3]).toBe(wheelEvent);
-        });
     });
     describe('Trackpad pinch gestures', () => {
         test('trackpad pinch out should zoom in', async () => {
-            zoomInteraction.updateCallback('onZoom', zoomCallbackMock);
+            zoomInteraction.updateCallback('onZoomAndPan', zoomAndPanCallbackMock);
             await simulateWheelEvent(myNvlContainer, -75, 50, { ctrlKey: true });
-            expect(zoomCallbackMock).toHaveBeenCalledTimes(1);
+            expect(zoomAndPanCallbackMock).toHaveBeenCalledTimes(1);
             const newScale = myNVL.getScale();
             expect(newScale).toBe(2);
         });
         test('trackpad pinch in should zoom out', async () => {
-            zoomInteraction.updateCallback('onZoom', zoomCallbackMock);
+            zoomInteraction.updateCallback('onZoomAndPan', zoomAndPanCallbackMock);
             await simulateWheelEvent(myNvlContainer, 100, 50, { ctrlKey: true });
-            expect(zoomCallbackMock).toHaveBeenCalledTimes(1);
+            expect(zoomAndPanCallbackMock).toHaveBeenCalledTimes(1);
             const newScale = myNVL.getScale();
             expect(newScale).toBe(0.075);
         });
         test('trackpad pinch should work with meta key (macOS)', async () => {
-            zoomInteraction.updateCallback('onZoom', zoomCallbackMock);
+            zoomInteraction.updateCallback('onZoomAndPan', zoomAndPanCallbackMock);
             const initialScale = myNVL.getScale();
             await simulateWheelEvent(myNvlContainer, -50, 50, { metaKey: true });
-            expect(zoomCallbackMock).toHaveBeenCalledTimes(1);
+            expect(zoomAndPanCallbackMock).toHaveBeenCalledTimes(1);
             const newScale = myNVL.getScale();
             expect(newScale).toBeGreaterThan(initialScale);
         });
@@ -183,12 +157,12 @@ describe('ZoomInteraction', () => {
             myNVL = new NVL(document.createElement('div'), [], [], { disableWebGL: true, initialZoom: 1, layout: 'free' });
             myNvlContainer = myNVL.getContainer();
             const zoomInteractionWithUpdate = new ZoomInteraction(myNVL, { controlledZoom: false });
-            zoomInteractionWithUpdate.updateCallback('onZoom', zoomCallbackMock);
+            zoomInteractionWithUpdate.updateCallback('onZoomAndPan', zoomAndPanCallbackMock);
             const initialScale = myNVL.getScale();
             await simulateWheelEvent(myNvlContainer, -100);
             expect(myNVL.getScale()).not.toBe(initialScale);
             expect(myNVL.getScale()).toBe(1.2);
-            expect(zoomCallbackMock).toHaveBeenCalledTimes(1);
+            expect(zoomAndPanCallbackMock).toHaveBeenCalledTimes(1);
             zoomInteractionWithUpdate.destroy();
         });
         test('when controlledZoom is true, should provide correct callback values for multiple operations', async () => {

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

@@ -20,7 +20,7 @@ export type BoxSelectInteractionCallbacks = {
      */
     onBoxStarted?: ((event: MouseEvent) => void) | boolean;
     /**
-     * Called after once the user releases the mouse after multi-selecting.
+     * Called once the user releases the mouse after multi-selecting.
      * @param selectionObject - The selected nodes and relationships.
      * @param event - The original mouse event.
      */

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

@@ -1,11 +1,12 @@
-import type { HitTargets, NVL, Node, Relationship } from '@neo4j-nvl/base';
+import type { Cluster, HitTargets, NVL, Node, Relationship } from '@neo4j-nvl/base';
 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
+     * Whether to select the node, relationship, or cluster members on click.
+     * Clicking something that is already selected clears the selection.
      * @defaultValue false
      */
     selectOnClick?: boolean;
@@ -15,66 +16,87 @@ export type ClickInteractionOptions = {
  */
 export type ClickInteractionCallbacks = {
     /**
-     * Called when a node is clicked
-     * @param nodes - The node that was clicked.
+     * Called when a node is clicked.
+     * @param node - 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) | boolean;
+    onNodeClick?: ((node: Node, hitElements: HitTargets, event: MouseEvent) => void) | boolean;
     /**
-     * Called when a relationship is clicked
+     * 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) | boolean;
     /**
-     * Called when the canvas is clicked
+     * Called when a cluster hull is clicked (empty space inside a clusterBy hull).
+     * @param cluster - The cluster that was clicked.
+     * @param hitElements - All elements that were hit by the click.
+     * @param event - The original mouse event.
+     */
+    onClusterClick?: ((cluster: Cluster, hitElements: HitTargets, event: MouseEvent) => void) | boolean;
+    /**
+     * Called when the canvas is clicked.
      * @param event - The original mouse event.
      */
     onCanvasClick?: ((event: MouseEvent) => void) | boolean;
     /**
-     * Called when a node is double clicked
+     * Called when the canvas is double-clicked.
      * @param event - The original mouse event.
      */
     onCanvasDoubleClick?: ((event: MouseEvent) => void) | boolean;
     /**
-     * Called when a relationship is right-clicked
+     * Called when the canvas is right-clicked.
      * @param event - The original mouse event.
      */
     onCanvasRightClick?: ((event: MouseEvent) => void) | boolean;
     /**
-     * Called when a node is double-clicked
-     * @param nodes - The node that was double-clicked.
+     * Called when a node is double-clicked.
+     * @param node - 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) | boolean;
     /**
-     * Called when a node is right-clicked
-     * @param nodes - The node that was right-clicked.
+     * Called when a node is right-clicked.
+     * @param node - 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) | boolean;
     /**
-     * Called when a relationship is double-clicked
+     * 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) | boolean;
     /**
-     * Called when a relationship is right-clicked
+     * 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) | boolean;
+    /**
+     * Called when a cluster hull is double-clicked.
+     * @param cluster - The cluster that was double-clicked.
+     * @param hitElements - All elements that were hit by the double-click.
+     * @param event - The original mouse event.
+     */
+    onClusterDoubleClick?: ((cluster: Cluster, hitElements: HitTargets, event: MouseEvent) => void) | boolean;
+    /**
+     * Called when a cluster hull is right-clicked.
+     * @param cluster - The cluster that was right-clicked.
+     * @param hitElements - All elements that were hit by the right-click.
+     * @param event - The original mouse event.
+     */
+    onClusterRightClick?: ((cluster: Cluster, hitElements: HitTargets, event: MouseEvent) => void) | boolean;
 };
 /**
  * Click interaction handler that handles click, double click and right click events on
- * nodes, relationships, and the scene.
+ * nodes, relationships, clusters, and the scene.
  *
  * For examples, head to the {@link https://neo4j.com/docs/nvl/current/interaction-handlers/#_clickinteraction Click Interaction documentation page}.
  */
@@ -91,6 +113,14 @@ export declare class ClickInteraction extends BaseInteraction<ClickInteractionOp
     private handleRightClick;
     private handleDoubleClick;
     private handleClick;
+    /**
+     * Makes the given elements the entire selection, deselecting everything else.
+     *
+     * Clicking something that is already fully selected clears the selection instead, so a repeated
+     * click toggles it off. A cluster counts as selected once all of its members are, which keeps
+     * cluster clicks behaving like node and relationship clicks.
+     */
+    private setSelection;
     /**
      * Removes all related event listeners from the container.
      */

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

@@ -1,8 +1,18 @@
 import { BaseInteraction } from './base';
 import { isDraggingMovement } from './utils';
+/**
+ * Marks the given ids as selected and deselects everything that is currently selected but not in that list.
+ */
+const buildSelectionUpdates = (idsToSelect, currentlySelected) => {
+    const keptSelected = new Set(idsToSelect);
+    return [
+        ...idsToSelect.map((id) => ({ id, selected: true })),
+        ...currentlySelected.filter(({ id }) => !keptSelected.has(id)).map(({ id }) => ({ id, selected: false }))
+    ];
+};
 /**
  * Click interaction handler that handles click, double click and right click events on
- * nodes, relationships, and the scene.
+ * nodes, relationships, clusters, and the scene.
  *
  * For examples, head to the {@link https://neo4j.com/docs/nvl/current/interaction-handlers/#_clickinteraction Click Interaction documentation page}.
  */
@@ -27,8 +37,8 @@ export class ClickInteraction extends BaseInteraction {
     handleRightClick = (event) => {
         event.preventDefault();
         const { nvlTargets } = this.nvlInstance.getHits(event);
-        const { nodes = [], relationships = [] } = nvlTargets;
-        if (nodes.length === 0 && relationships.length === 0) {
+        const { nodes = [], relationships = [], clusters = [] } = nvlTargets;
+        if (nodes.length === 0 && relationships.length === 0 && clusters.length === 0) {
             this.callCallbackIfRegistered('onCanvasRightClick', event);
             return;
         }
@@ -38,11 +48,14 @@ export class ClickInteraction extends BaseInteraction {
         else if (relationships.length > 0) {
             this.callCallbackIfRegistered('onRelationshipRightClick', relationships[0]?.data, nvlTargets, event);
         }
+        else if (clusters.length > 0) {
+            this.callCallbackIfRegistered('onClusterRightClick', clusters[0]?.data, nvlTargets, event);
+        }
     };
     handleDoubleClick = (event) => {
         const { nvlTargets } = this.nvlInstance.getHits(event);
-        const { nodes = [], relationships = [] } = nvlTargets;
-        if (nodes.length === 0 && relationships.length === 0) {
+        const { nodes = [], relationships = [], clusters = [] } = nvlTargets;
+        if (nodes.length === 0 && relationships.length === 0 && clusters.length === 0) {
             this.callCallbackIfRegistered('onCanvasDoubleClick', event);
             return;
         }
@@ -52,14 +65,17 @@ export class ClickInteraction extends BaseInteraction {
         else if (relationships.length > 0) {
             this.callCallbackIfRegistered('onRelationshipDoubleClick', relationships[0]?.data, nvlTargets, event);
         }
+        else if (clusters.length > 0) {
+            this.callCallbackIfRegistered('onClusterDoubleClick', clusters[0]?.data, nvlTargets, event);
+        }
     };
     handleClick = (event) => {
         if (isDraggingMovement(event, this.mousePosition) || event.button !== 0) {
             return;
         }
         const { nvlTargets } = this.nvlInstance.getHits(event);
-        const { nodes = [], relationships = [] } = nvlTargets;
-        if (nodes.length === 0 && relationships.length === 0) {
+        const { nodes = [], relationships = [], clusters = [] } = nvlTargets;
+        if (nodes.length === 0 && relationships.length === 0 && clusters.length === 0) {
             if (this.currentOptions.selectOnClick === true) {
                 this.nvlInstance.deselectAll();
             }
@@ -67,41 +83,46 @@ export class ClickInteraction extends BaseInteraction {
             return;
         }
         if (nodes.length > 0) {
-            const hitNodeData = nodes.map((node) => node.data);
+            const node = nodes[0]?.data;
             if (this.currentOptions.selectOnClick === true) {
-                const selectedNodes = this.nvlInstance.getSelectedNodes();
-                const selectedRelationships = this.nvlInstance.getSelectedRelationships();
-                const newSelectedNodes = hitNodeData[0] ? [{ id: hitNodeData[0].id, selected: true }] : [];
-                const nodeUpdates = [...newSelectedNodes, ...selectedNodes.map((node) => ({ id: node.id, selected: false }))];
-                const relationshipUpdates = selectedRelationships.map((relationship) => ({
-                    ...relationship,
-                    selected: false
-                }));
-                this.nvlInstance.updateElementsInGraph(nodeUpdates, relationshipUpdates);
+                this.setSelection(node ? [node.id] : [], []);
             }
-            this.callCallbackIfRegistered('onNodeClick', nodes[0]?.data, nvlTargets, event);
+            this.callCallbackIfRegistered('onNodeClick', node, nvlTargets, event);
         }
         else if (relationships.length > 0) {
-            const hitRelationshipData = relationships.map((relationship) => relationship.data);
+            const relationship = relationships[0]?.data;
+            if (this.currentOptions.selectOnClick === true) {
+                this.setSelection([], relationship ? [relationship.id] : []);
+            }
+            this.callCallbackIfRegistered('onRelationshipClick', relationship, nvlTargets, event);
+        }
+        else if (clusters.length > 0) {
+            const cluster = clusters[0]?.data;
             if (this.currentOptions.selectOnClick === true) {
-                const selectedNodes = this.nvlInstance.getSelectedNodes();
-                const selectedRelationships = this.nvlInstance.getSelectedRelationships();
-                const nodeUpdates = selectedNodes.map((node) => ({ id: node.id, selected: false }));
-                const newSelectedRelationships = hitRelationshipData[0]
-                    ? [{ id: hitRelationshipData[0].id, selected: true }]
-                    : [];
-                const relationshipUpdates = [
-                    ...newSelectedRelationships,
-                    ...selectedRelationships.map((relationship) => ({
-                        ...relationship,
-                        selected: false
-                    }))
-                ];
-                this.nvlInstance.updateElementsInGraph(nodeUpdates, relationshipUpdates);
+                this.setSelection(cluster ? cluster.nodeIds : [], []);
             }
-            this.callCallbackIfRegistered('onRelationshipClick', relationships[0]?.data, nvlTargets, event);
+            this.callCallbackIfRegistered('onClusterClick', cluster, nvlTargets, event);
         }
     };
+    /**
+     * Makes the given elements the entire selection, deselecting everything else.
+     *
+     * Clicking something that is already fully selected clears the selection instead, so a repeated
+     * click toggles it off. A cluster counts as selected once all of its members are, which keeps
+     * cluster clicks behaving like node and relationship clicks.
+     */
+    setSelection(nodeIds, relationshipIds) {
+        const selectedNodes = this.nvlInstance.getSelectedNodes();
+        const selectedRelationships = this.nvlInstance.getSelectedRelationships();
+        const selectedNodeIds = new Set(selectedNodes.map((n) => n.id));
+        const selectedRelationshipIds = new Set(selectedRelationships.map((r) => r.id));
+        const isAlreadySelected = nodeIds.length + relationshipIds.length > 0 &&
+            nodeIds.every((id) => selectedNodeIds.has(id)) &&
+            relationshipIds.every((id) => selectedRelationshipIds.has(id));
+        const nodeIdsToSelect = isAlreadySelected ? [] : nodeIds;
+        const relationshipIdsToSelect = isAlreadySelected ? [] : relationshipIds;
+        this.nvlInstance.updateElementsInGraph(buildSelectionUpdates(nodeIdsToSelect, selectedNodes), buildSelectionUpdates(relationshipIdsToSelect, selectedRelationships));
+    }
     /**
      * Removes all related event listeners from the container.
      */

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

@@ -1,11 +1,11 @@
 import type { HitTargets, NVL, Node, Relationship } from '@neo4j-nvl/base';
 import { BaseInteraction } from './base';
 /**
- * Options for the click interaction handler to customize its behavior.
+ * Options for the hover interaction handler to customize its behavior.
  */
 export type HoverInteractionOptions = {
     /**
-     * Whether to draw a shadow on hover
+     * Whether to draw a shadow on hover for nodes/relationships
      * @default false
      */
     drawShadowOnHover?: boolean;
@@ -15,9 +15,9 @@ export type HoverInteractionOptions = {
  */
 export type HoverInteractionCallbacks = {
     /**
-     * Called when a node or relationship is hovered
-     * @param element - The node or relationship that was hovered.
-     * @param hitElements - All elements that were hit by the hover.
+     * Called when a node or relationship is hovered.
+     * @param element - The highest-priority node or relationship under the pointer.
+     * @param hitElements - All nodes, relationships, and clusters under the pointer.
      * @param event - The original mouse event.
      * This callback is called every time the mouse moves,
      * even when no element is hovered or the current element is already hovered.

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

@@ -21,7 +21,7 @@ export type LassoInteractionCallbacks = {
     onLassoStarted?: ((event: MouseEvent) => void) | boolean;
     /**
      * Called once when the user releases the mouse after lasso selecting.
-     * @param selectionObject - The selected node and relationship ids.
+     * @param selectionObject - The selected nodes and relationships.
      * @param event - The original mouse event.
      */
     onLassoSelect?: (({ nodes, rels }: {

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

@@ -1,7 +1,7 @@
 import type { NVL } from '@neo4j-nvl/base';
 import { BaseInteraction } from './base';
 /**
- * Options for the click interaction handler to customize its behavior.
+ * Options for the pan interaction handler to customize its behavior.
  */
 export type PanInteractionOptions = {
     /**