@neo4j-nvl/interaction-handlers 2.0.0 → 2.1.0

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

@@ -1,46 +1,50 @@
-import type { HitTargets, NVL, Node, Relationship } from '@neo4j-nvl/base';
-import { BaseInteraction } from './base';
+import { BaseInteraction } from "./base.js";
+import { HitTargets, NVL, Node, Relationship } from "@neo4j-nvl/base";
 /**
  * Options for the hover interaction handler to customize its behavior.
  */
 export type HoverInteractionOptions = {
-    /**
-     * Whether to draw a shadow on hover for nodes/relationships
-     * @default false
-     */
-    drawShadowOnHover?: boolean;
+  /**
+   * Whether to draw a shadow on hover for nodes/relationships
+   * @default false
+   */
+  drawShadowOnHover?: boolean;
 };
 /**
  * Callbacks for the hover interaction handler.
  */
 export type HoverInteractionCallbacks = {
-    /**
-     * 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.
-     */
-    onHover?: ((element: Node | Relationship, hitElements: HitTargets, event: MouseEvent) => void) | boolean;
+  /**
+   * Called when a node or relationship is hovered.
+   * @param element - The highest-priority node or relationship under the pointer, or `undefined` if nothing is hovered.
+   * @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.
+   */
+  onHover?: ((element: Node | Relationship | undefined, hitElements: HitTargets, event: MouseEvent) => void) | boolean;
 };
 /**
  * Interaction handler for hovering nodes and relationships.
  *
+ * @remarks Clusters are not hoverable elements: `element` is never a cluster and no hover state is drawn
+ * for hulls. Read `hitElements.clusters` in {@link HoverInteractionCallbacks.onHover}, or call
+ * {@link NVL.getHits} with `['cluster']`, to react to the pointer being inside a cluster hull.
+ *
  * For examples, head to the {@link https://neo4j.com/docs/nvl/current/interaction-handlers/#_hoverinteraction Hover Interaction documentation page}.
  */
 export declare class HoverInteraction extends BaseInteraction<HoverInteractionOptions> {
-    private currentHoveredElementId;
-    private currentHoveredElementIsNode;
-    private readonly updates;
-    constructor(nvl: NVL, options?: HoverInteractionOptions);
-    /**
-     * Handle mouse hover events
-     * @param event - The mouse event.
-     */
-    handleHover: (event: MouseEvent) => void;
-    private updateElementsInNVL;
-    private clearUpdates;
-    private unHoverCurrentElement;
-    destroy(): void;
-}
+  private currentHoveredElementId;
+  private currentHoveredElementIsNode;
+  private readonly updates;
+  constructor(nvl: NVL, options?: HoverInteractionOptions);
+  /**
+   * Handle mouse hover events
+   * @param event - The mouse event.
+   */
+  handleHover: (event: MouseEvent) => void;
+  private updateElementsInNVL;
+  private clearUpdates;
+  private unHoverCurrentElement;
+  destroy(): void;
+}

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

@@ -1,90 +1,84 @@
-import { BaseInteraction } from './base';
+import { BaseInteraction } from "./base.js";
+// src/interaction-handlers/hover-interaction.ts
 /**
- * Interaction handler for hovering nodes and relationships.
- *
- * For examples, head to the {@link https://neo4j.com/docs/nvl/current/interaction-handlers/#_hoverinteraction Hover Interaction documentation page}.
- */
-export class HoverInteraction extends BaseInteraction {
-    currentHoveredElementId = undefined;
-    currentHoveredElementIsNode = undefined;
-    updates = {
-        nodes: [],
-        relationships: []
-    };
-    constructor(nvl, options = { drawShadowOnHover: false }) {
-        super(nvl, options);
-        this.addEventListener('mousemove', this.handleHover, true);
-    }
-    /**
-     * Handle mouse hover events
-     * @param event - The mouse event.
-     */
-    handleHover = (event) => {
-        const { nvlTargets } = this.nvlInstance.getHits(event);
-        const { nodes = [], relationships = [] } = nvlTargets;
-        const mainTarget = nodes[0] ?? relationships[0];
-        const hoveredElement = mainTarget?.data;
-        const newHoveredElementIsNode = hoveredElement !== undefined && nodes[0] !== undefined;
-        const nothingHasBeenHoveredOrUnHovered = this.currentHoveredElementId === undefined && hoveredElement === undefined;
-        const newHoveredElementIsTheSameAsCurrent = hoveredElement?.id !== undefined &&
-            this.currentHoveredElementId === hoveredElement.id &&
-            newHoveredElementIsNode === this.currentHoveredElementIsNode;
-        if (nothingHasBeenHoveredOrUnHovered || newHoveredElementIsTheSameAsCurrent) {
-            this.callCallbackIfRegistered('onHover', hoveredElement, nvlTargets, event);
-            return;
-        }
-        const currentElementNeedsUnHover = this.currentHoveredElementId !== undefined && this.currentHoveredElementId !== hoveredElement?.id;
-        if (currentElementNeedsUnHover) {
-            this.unHoverCurrentElement();
-        }
-        if (newHoveredElementIsNode) {
-            this.updates.nodes.push({ id: hoveredElement.id, hovered: true });
-            this.currentHoveredElementId = hoveredElement.id;
-            this.currentHoveredElementIsNode = true;
-        }
-        else if (hoveredElement !== undefined) {
-            const { id } = hoveredElement;
-            this.updates.relationships.push({ id, hovered: true });
-            this.currentHoveredElementId = hoveredElement.id;
-            this.currentHoveredElementIsNode = false;
-        }
-        else {
-            this.currentHoveredElementId = undefined;
-            this.currentHoveredElementIsNode = undefined;
-        }
-        this.callCallbackIfRegistered('onHover', hoveredElement, nvlTargets, event);
-        this.updateElementsInNVL();
-        this.clearUpdates();
-    };
-    updateElementsInNVL() {
-        // Use pure update API to avoid the previous removed node to be re-added to the scene.
-        if (this.currentOptions.drawShadowOnHover === true) {
-            const currentNodes = this.nvlInstance.getNodes();
-            if (currentNodes.length > 0) {
-                this.nvlInstance.updateElementsInGraph(this.updates.nodes, this.updates.relationships);
-            }
-        }
-    }
-    clearUpdates() {
-        this.updates.nodes = [];
-        this.updates.relationships = [];
-    }
-    unHoverCurrentElement() {
-        if (this.currentHoveredElementId === undefined) {
-            return;
-        }
-        const update = {
-            id: this.currentHoveredElementId,
-            hovered: false
-        };
-        if (this.currentHoveredElementIsNode === true) {
-            this.updates.nodes.push(update);
-        }
-        else {
-            this.updates.relationships.push({ ...update });
-        }
-    }
-    destroy() {
-        this.removeEventListener('mousemove', this.handleHover, true);
-    }
-}
+* Interaction handler for hovering nodes and relationships.
+*
+* @remarks Clusters are not hoverable elements: `element` is never a cluster and no hover state is drawn
+* for hulls. Read `hitElements.clusters` in {@link HoverInteractionCallbacks.onHover}, or call
+* {@link NVL.getHits} with `['cluster']`, to react to the pointer being inside a cluster hull.
+*
+* For examples, head to the {@link https://neo4j.com/docs/nvl/current/interaction-handlers/#_hoverinteraction Hover Interaction documentation page}.
+*/
+var HoverInteraction = class extends BaseInteraction {
+	currentHoveredElementId = void 0;
+	currentHoveredElementIsNode = void 0;
+	updates = {
+		nodes: [],
+		relationships: []
+	};
+	constructor(nvl, options = { drawShadowOnHover: false }) {
+		super(nvl, options);
+		this.addEventListener("mousemove", this.handleHover, true);
+	}
+	/**
+	* Handle mouse hover events
+	* @param event - The mouse event.
+	*/
+	handleHover = (event) => {
+		const { nvlTargets } = this.nvlInstance.getHits(event);
+		const { nodes = [], relationships = [] } = nvlTargets;
+		const hoveredElement = (nodes[0] ?? relationships[0])?.data;
+		const newHoveredElementIsNode = hoveredElement !== void 0 && nodes[0] !== void 0;
+		const nothingHasBeenHoveredOrUnHovered = this.currentHoveredElementId === void 0 && hoveredElement === void 0;
+		const newHoveredElementIsTheSameAsCurrent = hoveredElement?.id !== void 0 && this.currentHoveredElementId === hoveredElement.id && newHoveredElementIsNode === this.currentHoveredElementIsNode;
+		if (nothingHasBeenHoveredOrUnHovered || newHoveredElementIsTheSameAsCurrent) {
+			this.callCallbackIfRegistered("onHover", hoveredElement, nvlTargets, event);
+			return;
+		}
+		if (this.currentHoveredElementId !== void 0 && this.currentHoveredElementId !== hoveredElement?.id) this.unHoverCurrentElement();
+		if (newHoveredElementIsNode) {
+			this.updates.nodes.push({
+				id: hoveredElement.id,
+				hovered: true
+			});
+			this.currentHoveredElementId = hoveredElement.id;
+			this.currentHoveredElementIsNode = true;
+		} else if (hoveredElement !== void 0) {
+			const { id } = hoveredElement;
+			this.updates.relationships.push({
+				id,
+				hovered: true
+			});
+			this.currentHoveredElementId = hoveredElement.id;
+			this.currentHoveredElementIsNode = false;
+		} else {
+			this.currentHoveredElementId = void 0;
+			this.currentHoveredElementIsNode = void 0;
+		}
+		this.callCallbackIfRegistered("onHover", hoveredElement, nvlTargets, event);
+		this.updateElementsInNVL();
+		this.clearUpdates();
+	};
+	updateElementsInNVL() {
+		if (this.currentOptions.drawShadowOnHover === true) {
+			if (this.nvlInstance.getNodes().length > 0) this.nvlInstance.updateElementsInGraph(this.updates.nodes, this.updates.relationships);
+		}
+	}
+	clearUpdates() {
+		this.updates.nodes = [];
+		this.updates.relationships = [];
+	}
+	unHoverCurrentElement() {
+		if (this.currentHoveredElementId === void 0) return;
+		const update = {
+			id: this.currentHoveredElementId,
+			hovered: false
+		};
+		if (this.currentHoveredElementIsNode === true) this.updates.nodes.push(update);
+		else this.updates.relationships.push({ ...update });
+	}
+	destroy() {
+		this.removeEventListener("mousemove", this.handleHover, true);
+	}
+};
+export { HoverInteraction };

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

@@ -1,5 +1,5 @@
-import type { NVL, Node, Relationship } from '@neo4j-nvl/base';
-import { BaseInteraction } from './base';
+import { BaseInteraction } from "./base.js";
+import { NVL, Node, Point, Relationship } from "@neo4j-nvl/base";
 /**
  * Options for the keyboard interaction handler.
  * Allows configuring which keys trigger specific navigation actions.
@@ -17,76 +17,107 @@ import { BaseInteraction } from './base';
  * ```
  */
 export type KeyboardInteractionOptions = {
-    /** Key combo for entering the graph and focusing the first element. Default: `['Enter']` */
-    enterGraphKey?: string[];
-    /** Key combo for navigating focus to the next element. Default: `['Tab']` */
-    navigateForwardKey?: string[];
-    /** Key combo for navigating focus to the previous element. Default: `['Shift', 'Tab']` */
-    navigateBackwardKey?: string[];
-    /** Key combo for exiting the graph (blur focused element and container). Default: `['Escape']` */
-    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;
+  /** Key combo for entering the graph and focusing the first element. Default: `['Enter']` */
+  enterGraphKey?: string[];
+  /** Key combo for navigating focus to the next element. Default: `['Tab']` */
+  navigateForwardKey?: string[];
+  /** Key combo for navigating focus to the previous element. Default: `['Shift', 'Tab']` */
+  navigateBackwardKey?: string[];
+  /** Key combo for exiting the graph (blur focused element and container). Default: `['Escape']` */
+  exitGraphKey?: string[];
+  /** Key combo for opening the context menu on the focused element. Default: `['Shift', 'F10']` */
+  contextMenuKey?: string[];
+  /** Key combo for moving the selected (or focused) node(s) up. Default: `['ArrowUp']` */
+  moveUpKey?: string[];
+  /** Key combo for moving the selected (or focused) node(s) down. Default: `['ArrowDown']` */
+  moveDownKey?: string[];
+  /** Key combo for moving the selected (or focused) node(s) left. Default: `['ArrowLeft']` */
+  moveLeftKey?: string[];
+  /** Key combo for moving the selected (or focused) node(s) right. Default: `['ArrowRight']` */
+  moveRightKey?: string[];
+  /**
+   * Distance in screen pixels the node(s) are moved per key press. Converted to graph
+   * coordinates using the current zoom level, so the node travels the same visible
+   * distance however far the graph is zoomed in or out. Default: `5`
+   */
+  moveStep?: number;
+  /**
+   * Distance in screen pixels the node(s) are moved per key press while
+   * {@link KeyboardInteractionOptions.largeMoveStepModifier} is held. Default: `50`
+   */
+  largeMoveStep?: number;
+  /**
+   * Modifier key that, held together with a move key, applies
+   * {@link KeyboardInteractionOptions.largeMoveStep} instead of
+   * {@link KeyboardInteractionOptions.moveStep}. Default: `'Shift'`
+   */
+  largeMoveStepModifier?: 'Shift' | 'Ctrl' | 'Alt' | 'Meta';
+  /** The color of the outline shown when the canvas receives keyboard focus. Default: `'#30839D'` */
+  canvasOutlineColor?: string;
 };
 /**
  * Callbacks for the keyboard interaction handler.
  */
 export type KeyboardInteractionCallbacks = {
-    /**
-     * Called when a key is pressed while the NVL container is focused.
-     * Fires for all key events, including those handled by the built-in navigation.
-     * @param event - The original keyboard event.
-     * @param focusedElement - The currently focused node or relationship, if any.
-     */
-    onKeyDown?: ((event: KeyboardEvent, focusedElement?: Node | Relationship) => void) | boolean;
-    /**
-     * Called when a key is released while the NVL container is focused
-     * @param event - The original keyboard event.
-     * @param focusedElement - The currently focused node or relationship, if any.
-     */
-    onKeyUp?: ((event: KeyboardEvent, focusedElement?: Node | Relationship) => void) | boolean;
-    /**
-     * Called when a node receives focus (via keyboard navigation)
-     * @param node - The node that received focus.
-     * @param event - The original keyboard event that triggered the focus change.
-     */
-    onNodeFocus?: ((node: Node, event: KeyboardEvent) => void) | boolean;
-    /**
-     * Called when a node loses focus (via keyboard navigation)
-     * @param node - The node that lost focus.
-     * @param event - The original keyboard event that triggered the focus change.
-     */
-    onNodeBlur?: ((node: Node, event: KeyboardEvent) => void) | boolean;
-    /**
-     * Called when a relationship receives focus (via keyboard navigation)
-     * @param relationship - The relationship that received focus.
-     * @param event - The original keyboard event that triggered the focus change.
-     */
-    onRelationshipFocus?: ((relationship: Relationship, event: KeyboardEvent) => void) | boolean;
-    /**
-     * Called when a relationship loses focus (via keyboard navigation)
-     * @param relationship - The relationship that lost focus.
-     * @param event - The original keyboard event that triggered the focus change.
-     */
-    onRelationshipBlur?: ((relationship: Relationship, event: KeyboardEvent) => void) | boolean;
-    /**
-     * Called when the NVL canvas container receives DOM focus
-     * @param event - The original focus event.
-     */
-    onCanvasFocus?: ((event: FocusEvent) => void) | boolean;
-    /**
-     * Called when the NVL canvas container loses DOM focus
-     * @param event - The original focus event.
-     */
-    onCanvasBlur?: ((event: FocusEvent) => void) | boolean;
-    /**
-     * Called when the context menu key is pressed while the NVL container is focused.
-     * @param element - The focused node or relationship, or undefined if the canvas itself is focused.
-     * @param event - The original keyboard event.
-     */
-    onContextMenu?: ((element: Node | Relationship | undefined, event: KeyboardEvent) => void) | boolean;
+  /**
+   * Called when a key is pressed while the NVL container is focused.
+   * Fires for all key events, including those handled by the built-in navigation.
+   * @param event - The original keyboard event.
+   * @param focusedElement - The currently focused node or relationship, if any.
+   */
+  onKeyDown?: ((event: KeyboardEvent, focusedElement?: Node | Relationship) => void) | boolean;
+  /**
+   * Called when a key is released while the NVL container is focused
+   * @param event - The original keyboard event.
+   * @param focusedElement - The currently focused node or relationship, if any.
+   */
+  onKeyUp?: ((event: KeyboardEvent, focusedElement?: Node | Relationship) => void) | boolean;
+  /**
+   * Called when a node receives focus (via keyboard navigation)
+   * @param node - The node that received focus.
+   * @param event - The original keyboard event that triggered the focus change.
+   */
+  onNodeFocus?: ((node: Node, event: KeyboardEvent) => void) | boolean;
+  /**
+   * Called when a node loses focus (via keyboard navigation)
+   * @param node - The node that lost focus.
+   * @param event - The original keyboard event that triggered the focus change.
+   */
+  onNodeBlur?: ((node: Node, event: KeyboardEvent) => void) | boolean;
+  /**
+   * Called when a relationship receives focus (via keyboard navigation)
+   * @param relationship - The relationship that received focus.
+   * @param event - The original keyboard event that triggered the focus change.
+   */
+  onRelationshipFocus?: ((relationship: Relationship, event: KeyboardEvent) => void) | boolean;
+  /**
+   * Called when a relationship loses focus (via keyboard navigation)
+   * @param relationship - The relationship that lost focus.
+   * @param event - The original keyboard event that triggered the focus change.
+   */
+  onRelationshipBlur?: ((relationship: Relationship, event: KeyboardEvent) => void) | boolean;
+  /**
+   * Called when the NVL canvas container receives DOM focus
+   * @param event - The original focus event.
+   */
+  onCanvasFocus?: ((event: FocusEvent) => void) | boolean;
+  /**
+   * Called when the NVL canvas container loses DOM focus
+   * @param event - The original focus event.
+   */
+  onCanvasBlur?: ((event: FocusEvent) => void) | boolean;
+  /**
+   * Called when the context menu key is pressed while the NVL container is focused.
+   * @param element - The focused node or relationship, or undefined if the canvas itself is focused.
+   * @param event - The original keyboard event.
+   */
+  onContextMenu?: ((element: Node | Relationship | undefined, event: KeyboardEvent) => void) | boolean;
+  /**
+   * Called when node(s) are moved with the keyboard.
+   * @param nodes - The moved node(s), with their updated positions.
+   * @param event - The original keyboard event.
+   */
+  onNodeMove?: ((nodes: (Node & Point)[], event: KeyboardEvent) => void) | boolean;
 };
 /**
  * Opinionated interaction handler for keyboard-driven focus navigation
@@ -94,39 +125,60 @@ export type KeyboardInteractionCallbacks = {
  *
  * By default, Tab / Shift+Tab cycle focus through elements, Escape exits the
  * graph, and Shift+F10 call the `onContextMenu` callback with the focused element.
+ * While a node is focused, the arrow keys move the selected node(s), or the focused
+ * node when nothing is selected, by `moveStep` screen pixels - or by `largeMoveStep`
+ * while the large step modifier (Shift by default) is held.
  * All keys can be reconfigured via {@link KeyboardInteractionOptions}.
  *
  * Callbacks are fired for focus/blur transitions and context-menu activation,
  * following the same one-way data-flow pattern as the other interaction handlers.
  */
 export declare class KeyboardInteraction extends BaseInteraction<KeyboardInteractionOptions> {
-    private focusedElementId;
-    private focusedElementIsNode;
-    private focusableElements;
-    private addedTabindex;
-    private resolvedOptions;
-    /**
-     * Creates a new keyboard interaction handler.
-     * @param nvl - The NVL instance to attach the interaction handler to.
-     * @param options - Options for the keyboard interaction handler.
-     */
-    constructor(nvl: NVL, options?: KeyboardInteractionOptions);
-    private buildFocusableElements;
-    /**
-     * Returns the currently focused element, if any.
-     */
-    getFocused(): Node | Relationship | undefined;
-    private setCanvasOutline;
-    private clearCanvasOutline;
-    private handleFocusIn;
-    private handleFocusOut;
-    private handleKeyDown;
-    private handleKeyUp;
-    private navigateFocus;
-    private setFocus;
-    private clearFocus;
-    /**
-     * Removes all related event listeners from the container.
-     */
-    destroy(): void;
-}
+  private focusedElementId;
+  private focusedElementIsNode;
+  private focusableElements;
+  private addedTabindex;
+  private resolvedOptions;
+  /**
+   * Creates a new keyboard interaction handler.
+   * @param nvl - The NVL instance to attach the interaction handler to.
+   * @param options - Options for the keyboard interaction handler.
+   */
+  constructor(nvl: NVL, options?: KeyboardInteractionOptions);
+  private buildFocusableElements;
+  /**
+   * Returns the currently focused element, if any.
+   */
+  getFocused(): Node | Relationship | undefined;
+  private setCanvasOutline;
+  private clearCanvasOutline;
+  private handleFocusIn;
+  private handleFocusOut;
+  private handleKeyDown;
+  /**
+   * Moves the nodes to be moved when the event matches one of the move key combos,
+   * either by `moveStep` or, with the large step modifier held, by `largeMoveStep`.
+   *
+   * The step is given in screen pixels and converted to graph coordinates using the
+   * current zoom level, the same way the drag interaction converts pointer
+   * movement, so keyboard and pointer moves cover the same visible distance.
+   */
+  private handleMoveKeys;
+  /**
+   * Returns the nodes a move key applies to: the selected nodes, or the focused
+   * node when nothing is selected.
+   *
+   * A node must be focused for any of them to move, so move keys are inert until
+   * the graph has been entered, and a focused relationship blocks moving entirely.
+   */
+  private getNodesToMove;
+  private moveNodes;
+  private handleKeyUp;
+  private navigateFocus;
+  private setFocus;
+  private clearFocus;
+  /**
+   * Removes all related event listeners from the container.
+   */
+  destroy(): void;
+}