@neo4j-nvl/interaction-handlers 2.0.0 → 2.1.0

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

@@ -1,207 +1,261 @@
-import { BaseInteraction } from './base';
+import { BaseInteraction } from "./base.js";
+// src/interaction-handlers/keyboard-interaction.ts
 const DEFAULT_OPTIONS = {
-    enterGraphKey: ['Enter'],
-    navigateForwardKey: ['Tab'],
-    navigateBackwardKey: ['Shift', 'Tab'],
-    exitGraphKey: ['Escape'],
-    contextMenuKey: ['Shift', 'F10'],
-    canvasOutlineColor: '#30839D'
+	enterGraphKey: ["Enter"],
+	navigateForwardKey: ["Tab"],
+	navigateBackwardKey: ["Shift", "Tab"],
+	exitGraphKey: ["Escape"],
+	contextMenuKey: ["Shift", "F10"],
+	moveUpKey: ["ArrowUp"],
+	moveDownKey: ["ArrowDown"],
+	moveLeftKey: ["ArrowLeft"],
+	moveRightKey: ["ArrowRight"],
+	moveStep: 5,
+	largeMoveStep: 50,
+	largeMoveStepModifier: "Shift",
+	canvasOutlineColor: "#30839D"
 };
 /**
- * Checks whether a keyboard event matches a key combo array.
- * The last element is the primary key (`event.key`), preceding elements are modifiers.
- * Examples: `['Tab']`, `['Shift', 'Tab']`, `['Shift', 'F10']`
- */
+* Checks whether a keyboard event matches a key combo array.
+* The last element is the primary key (`event.key`), preceding elements are modifiers.
+* Examples: `['Tab']`, `['Shift', 'Tab']`, `['Shift', 'F10']`
+*/
 const matchesKeyCombo = (event, keyCombo) => {
-    const key = keyCombo[keyCombo.length - 1];
-    const requireShift = keyCombo.includes('Shift');
-    const requireCtrl = keyCombo.includes('Ctrl');
-    const requireAlt = keyCombo.includes('Alt');
-    const requireMeta = keyCombo.includes('Meta');
-    return (event.key === key &&
-        event.shiftKey === requireShift &&
-        event.ctrlKey === requireCtrl &&
-        event.altKey === requireAlt &&
-        event.metaKey === requireMeta);
+	const key = keyCombo[keyCombo.length - 1];
+	const requireShift = keyCombo.includes("Shift");
+	const requireCtrl = keyCombo.includes("Ctrl");
+	const requireAlt = keyCombo.includes("Alt");
+	const requireMeta = keyCombo.includes("Meta");
+	return event.key === key && event.shiftKey === requireShift && event.ctrlKey === requireCtrl && event.altKey === requireAlt && event.metaKey === requireMeta;
 };
 /**
- * Opinionated interaction handler for keyboard-driven focus navigation
- * through graph elements (nodes and relationships).
- *
- * By default, Tab / Shift+Tab cycle focus through elements, Escape exits the
- * graph, and Shift+F10 call the `onContextMenu` callback with the focused element.
- * 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 class KeyboardInteraction extends BaseInteraction {
-    focusedElementId = undefined;
-    focusedElementIsNode = undefined;
-    focusableElements = [];
-    addedTabindex = false;
-    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, options = {}) {
-        super(nvl, options);
-        this.resolvedOptions = { ...DEFAULT_OPTIONS, ...options };
-        // Ensure the container is focusable for keyboard events
-        const tabindex = this.containerInstance.getAttribute('tabindex');
-        if (tabindex === null || tabindex === '') {
-            this.containerInstance.setAttribute('tabindex', '0');
-            this.addedTabindex = true;
-        }
-        this.addEventListener('keydown', this.handleKeyDown);
-        this.addEventListener('keyup', this.handleKeyUp);
-        this.addEventListener('focusin', this.handleFocusIn);
-        this.addEventListener('focusout', this.handleFocusOut);
-    }
-    buildFocusableElements() {
-        const nodes = this.nvlInstance.getNodes();
-        const relationships = this.nvlInstance.getRelationships();
-        this.focusableElements = [
-            ...nodes.map((node) => ({ id: node.id, isNode: true })),
-            ...relationships.map((rel) => ({ id: rel.id, isNode: false }))
-        ];
-    }
-    /**
-     * Returns the currently focused element, if any.
-     */
-    getFocused() {
-        if (this.focusedElementId === undefined) {
-            return undefined;
-        }
-        if (this.focusedElementIsNode === true) {
-            return this.nvlInstance.getNodes().find((n) => n.id === this.focusedElementId);
-        }
-        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();
-        this.callCallbackIfRegistered('onKeyDown', event, focusedElement);
-        const { enterGraphKey, navigateForwardKey, navigateBackwardKey, exitGraphKey, contextMenuKey } = this.resolvedOptions;
-        if (matchesKeyCombo(event, enterGraphKey)) {
-            if (focusedElement === undefined) {
-                event.preventDefault();
-                this.navigateFocus(1, event);
-            }
-        }
-        else if (matchesKeyCombo(event, navigateForwardKey)) {
-            if (focusedElement !== undefined) {
-                event.preventDefault();
-                this.navigateFocus(1, event);
-            }
-        }
-        else if (matchesKeyCombo(event, navigateBackwardKey)) {
-            if (focusedElement !== undefined) {
-                event.preventDefault();
-                this.navigateFocus(-1, event);
-            }
-        }
-        else if (matchesKeyCombo(event, exitGraphKey)) {
-            this.setCanvasOutline();
-            if (focusedElement !== undefined) {
-                event.preventDefault();
-                this.clearFocus(event);
-            }
-        }
-        else if (matchesKeyCombo(event, contextMenuKey)) {
-            event.preventDefault();
-            this.callCallbackIfRegistered('onContextMenu', focusedElement, event);
-        }
-    };
-    handleKeyUp = (event) => {
-        const focusedElement = this.getFocused();
-        this.callCallbackIfRegistered('onKeyUp', event, focusedElement);
-    };
-    navigateFocus(direction, event) {
-        this.buildFocusableElements();
-        if (this.focusableElements.length === 0) {
-            return;
-        }
-        const currentIndex = this.focusedElementId !== undefined
-            ? this.focusableElements.findIndex((el) => el.id === this.focusedElementId && el.isNode === this.focusedElementIsNode)
-            : -1;
-        let nextIndex;
-        if (currentIndex === -1) {
-            nextIndex = direction === 1 ? 0 : this.focusableElements.length - 1;
-        }
-        else {
-            nextIndex = (currentIndex + direction + this.focusableElements.length) % this.focusableElements.length;
-        }
-        const nextElement = this.focusableElements[nextIndex];
-        if (nextElement) {
-            this.setFocus(nextElement.id, nextElement.isNode, event);
-        }
-    }
-    setFocus(elementId, isNode, event) {
-        this.clearFocus(event);
-        // Update focus state
-        this.focusedElementId = elementId;
-        this.focusedElementIsNode = isNode;
-        // Notify about the newly focused element
-        const newElement = this.getFocused();
-        if (newElement !== undefined) {
-            this.clearCanvasOutline();
-            if (isNode) {
-                this.callCallbackIfRegistered('onNodeFocus', newElement, event);
-            }
-            else {
-                this.callCallbackIfRegistered('onRelationshipFocus', newElement, event);
-            }
-        }
-    }
-    clearFocus(event) {
-        const previousElement = this.getFocused();
-        if (previousElement !== undefined) {
-            if (this.focusedElementIsNode === true) {
-                this.callCallbackIfRegistered('onNodeBlur', previousElement, event);
-            }
-            else {
-                this.callCallbackIfRegistered('onRelationshipBlur', previousElement, event);
-            }
-        }
-        this.focusedElementId = undefined;
-        this.focusedElementIsNode = undefined;
-    }
-    /**
-     * Removes all related event listeners from the container.
-     */
-    destroy() {
-        this.removeEventListener('keydown', this.handleKeyDown);
-        this.removeEventListener('keyup', this.handleKeyUp);
-        this.removeEventListener('focusin', this.handleFocusIn);
-        this.removeEventListener('focusout', this.handleFocusOut);
-        this.clearCanvasOutline();
-        if (this.addedTabindex) {
-            this.containerInstance.removeAttribute('tabindex');
-        }
-        this.focusedElementId = undefined;
-        this.focusedElementIsNode = undefined;
-        this.focusableElements = [];
-    }
-}
+* Nodes without layout coordinates cannot be moved by a relative offset.
+*/
+const hasPosition = (node) => node.x !== void 0 && node.y !== void 0;
+/**
+* Opinionated interaction handler for keyboard-driven focus navigation
+* through graph elements (nodes and relationships).
+*
+* 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.
+*/
+var KeyboardInteraction = class extends BaseInteraction {
+	focusedElementId = void 0;
+	focusedElementIsNode = void 0;
+	focusableElements = [];
+	addedTabindex = false;
+	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, options = {}) {
+		super(nvl, options);
+		this.resolvedOptions = {
+			...DEFAULT_OPTIONS,
+			...options
+		};
+		const tabindex = this.containerInstance.getAttribute("tabindex");
+		if (tabindex === null || tabindex === "") {
+			this.containerInstance.setAttribute("tabindex", "0");
+			this.addedTabindex = true;
+		}
+		this.addEventListener("keydown", this.handleKeyDown);
+		this.addEventListener("keyup", this.handleKeyUp);
+		this.addEventListener("focusin", this.handleFocusIn);
+		this.addEventListener("focusout", this.handleFocusOut);
+	}
+	buildFocusableElements() {
+		const nodes = this.nvlInstance.getNodes();
+		const relationships = this.nvlInstance.getRelationships();
+		this.focusableElements = [...nodes.map((node) => ({
+			id: node.id,
+			isNode: true
+		})), ...relationships.map((rel) => ({
+			id: rel.id,
+			isNode: false
+		}))];
+	}
+	/**
+	* Returns the currently focused element, if any.
+	*/
+	getFocused() {
+		if (this.focusedElementId === void 0) return;
+		if (this.focusedElementIsNode === true) return this.nvlInstance.getNodes().find((n) => n.id === this.focusedElementId);
+		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();
+		this.callCallbackIfRegistered("onKeyDown", event, focusedElement);
+		const { enterGraphKey, navigateForwardKey, navigateBackwardKey, exitGraphKey, contextMenuKey } = this.resolvedOptions;
+		if (matchesKeyCombo(event, enterGraphKey)) {
+			if (focusedElement === void 0) {
+				event.preventDefault();
+				this.navigateFocus(1, event);
+			}
+		} else if (matchesKeyCombo(event, navigateForwardKey)) {
+			if (focusedElement !== void 0) {
+				event.preventDefault();
+				this.navigateFocus(1, event);
+			}
+		} else if (matchesKeyCombo(event, navigateBackwardKey)) {
+			if (focusedElement !== void 0) {
+				event.preventDefault();
+				this.navigateFocus(-1, event);
+			}
+		} else if (matchesKeyCombo(event, exitGraphKey)) {
+			this.setCanvasOutline();
+			if (focusedElement !== void 0) {
+				event.preventDefault();
+				this.clearFocus(event);
+			}
+		} else if (matchesKeyCombo(event, contextMenuKey)) {
+			event.preventDefault();
+			this.callCallbackIfRegistered("onContextMenu", focusedElement, event);
+		} else this.handleMoveKeys(event);
+	};
+	/**
+	* 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.
+	*/
+	handleMoveKeys(event) {
+		const { moveUpKey, moveDownKey, moveLeftKey, moveRightKey, moveStep, largeMoveStep, largeMoveStepModifier } = this.resolvedOptions;
+		const direction = [
+			{
+				keyCombo: moveUpKey,
+				x: 0,
+				y: -1
+			},
+			{
+				keyCombo: moveDownKey,
+				x: 0,
+				y: 1
+			},
+			{
+				keyCombo: moveLeftKey,
+				x: -1,
+				y: 0
+			},
+			{
+				keyCombo: moveRightKey,
+				x: 1,
+				y: 0
+			}
+		].find(({ keyCombo }) => matchesKeyCombo(event, keyCombo) || matchesKeyCombo(event, [largeMoveStepModifier, ...keyCombo]));
+		if (direction === void 0) return;
+		const graphStep = (matchesKeyCombo(event, direction.keyCombo) ? moveStep : largeMoveStep) / this.nvlInstance.getScale() * window.devicePixelRatio;
+		this.moveNodes(direction.x * graphStep, direction.y * graphStep, event);
+	}
+	/**
+	* 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.
+	*/
+	getNodesToMove() {
+		if (this.focusedElementId === void 0 || this.focusedElementIsNode !== true) return [];
+		const selectedNodes = this.nvlInstance.getSelectedNodes();
+		if (selectedNodes.length > 0) return selectedNodes.filter(hasPosition);
+		return this.nvlInstance.getNodes().filter((node) => node.id === this.focusedElementId).filter(hasPosition);
+	}
+	moveNodes(dx, dy, event) {
+		const nodesToMove = this.getNodesToMove();
+		if (nodesToMove.length === 0) return;
+		event.preventDefault();
+		const movedNodes = nodesToMove.map((node) => ({
+			...node,
+			x: node.x + dx,
+			y: node.y + dy,
+			pinned: true
+		}));
+		this.nvlInstance.setNodePositions(movedNodes.map(({ id, x, y, pinned }) => ({
+			id,
+			x,
+			y,
+			pinned
+		})), true);
+		this.callCallbackIfRegistered("onNodeMove", movedNodes, event);
+	}
+	handleKeyUp = (event) => {
+		const focusedElement = this.getFocused();
+		this.callCallbackIfRegistered("onKeyUp", event, focusedElement);
+	};
+	navigateFocus(direction, event) {
+		this.buildFocusableElements();
+		if (this.focusableElements.length === 0) return;
+		const currentIndex = this.focusedElementId !== void 0 ? this.focusableElements.findIndex((el) => el.id === this.focusedElementId && el.isNode === this.focusedElementIsNode) : -1;
+		let nextIndex;
+		if (currentIndex === -1) nextIndex = direction === 1 ? 0 : this.focusableElements.length - 1;
+		else nextIndex = (currentIndex + direction + this.focusableElements.length) % this.focusableElements.length;
+		const nextElement = this.focusableElements[nextIndex];
+		if (nextElement) this.setFocus(nextElement.id, nextElement.isNode, event);
+	}
+	setFocus(elementId, isNode, event) {
+		this.clearFocus(event);
+		this.focusedElementId = elementId;
+		this.focusedElementIsNode = isNode;
+		const newElement = this.getFocused();
+		if (newElement !== void 0) {
+			this.clearCanvasOutline();
+			if (isNode) this.callCallbackIfRegistered("onNodeFocus", newElement, event);
+			else this.callCallbackIfRegistered("onRelationshipFocus", newElement, event);
+		}
+	}
+	clearFocus(event) {
+		const previousElement = this.getFocused();
+		if (previousElement !== void 0) {
+			if (this.focusedElementIsNode === true) this.callCallbackIfRegistered("onNodeBlur", previousElement, event);
+			else this.callCallbackIfRegistered("onRelationshipBlur", previousElement, event);
+		}
+		this.focusedElementId = void 0;
+		this.focusedElementIsNode = void 0;
+	}
+	/**
+	* Removes all related event listeners from the container.
+	*/
+	destroy() {
+		this.removeEventListener("keydown", this.handleKeyDown);
+		this.removeEventListener("keyup", this.handleKeyUp);
+		this.removeEventListener("focusin", this.handleFocusIn);
+		this.removeEventListener("focusout", this.handleFocusOut);
+		this.clearCanvasOutline();
+		if (this.addedTabindex) this.containerInstance.removeAttribute("tabindex");
+		this.focusedElementId = void 0;
+		this.focusedElementIsNode = void 0;
+		this.focusableElements = [];
+	}
+};
+export { KeyboardInteraction };

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

@@ -1,33 +1,33 @@
-import type { NVL, Node, Point, 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 lasso interaction handler to customize its behavior.
  */
 export type LassoInteractionOptions = {
-    /**
-     * If true, the selected items will be automatically selected when the gesture is finished.
-     * @default false
-     */
-    selectOnRelease?: boolean;
+  /**
+   * If true, the selected items will be automatically selected when the gesture is finished.
+   * @default false
+   */
+  selectOnRelease?: boolean;
 };
 /**
  * Callbacks for the lasso interaction handler.
  */
 export type LassoInteractionCallbacks = {
-    /**
-     * Called once when the user presses the mouse on the canvas, starting the lasso.
-     * @param event - The original mouse event.
-     */
-    onLassoStarted?: ((event: MouseEvent) => void) | boolean;
-    /**
-     * Called once when the user releases the mouse after lasso selecting.
-     * @param selectionObject - The selected nodes and relationships.
-     * @param event - The original mouse event.
-     */
-    onLassoSelect?: (({ nodes, rels }: {
-        nodes: Node[];
-        rels: Relationship[];
-    }, event: MouseEvent) => void) | boolean;
+  /**
+   * Called once when the user presses the mouse on the canvas, starting the lasso.
+   * @param event - The original mouse event.
+   */
+  onLassoStarted?: ((event: MouseEvent) => void) | boolean;
+  /**
+   * Called once when the user releases the mouse after lasso selecting.
+   * @param selectionObject - The selected nodes and relationships.
+   * @param event - The original mouse event.
+   */
+  onLassoSelect?: (({ nodes, rels }: {
+    nodes: Node[];
+    rels: Relationship[];
+  }, event: MouseEvent) => void) | boolean;
 };
 /**
  * @internal
@@ -59,27 +59,27 @@ export declare const checkPointInside: (x: number, y: number, vs: Point[]) => bo
  * For examples, head to the {@link https://neo4j.com/docs/nvl/current/interaction-handlers/#_lassointeraction Lasso Interaction documentation page}.
  */
 export declare class LassoInteraction extends BaseInteraction<LassoInteractionOptions> {
-    private active;
-    private lassoPending;
-    private startClientPosition;
-    private pendingPointerCanvas;
-    private points;
-    private overlayRenderer;
-    /**
-     * Creates a new instance of the lasso interaction handler.
-     * @param nvl - The NVL instance to attach the interaction handler to.
-     * @param options - Options for the lasso interaction handler to customize its behavior.
-     */
-    constructor(nvl: NVL, options?: LassoInteractionOptions);
-    private startLasso;
-    private handleMouseDown;
-    private handleDrag;
-    private activateLasso;
-    private handleMouseUp;
-    private getLassoItems;
-    private endLasso;
-    /**
-     * Removes all related event listeners and the overlay renderer for the box.
-     */
-    destroy(): void;
-}
+  private active;
+  private lassoPending;
+  private startClientPosition;
+  private pendingPointerCanvas;
+  private points;
+  private overlayRenderer;
+  /**
+   * Creates a new instance of the lasso interaction handler.
+   * @param nvl - The NVL instance to attach the interaction handler to.
+   * @param options - Options for the lasso interaction handler to customize its behavior.
+   */
+  constructor(nvl: NVL, options?: LassoInteractionOptions);
+  private startLasso;
+  private handleMouseDown;
+  private handleDrag;
+  private activateLasso;
+  private handleMouseUp;
+  private getLassoItems;
+  private endLasso;
+  /**
+   * Removes all related event listeners and the overlay renderer for the box.
+   */
+  destroy(): void;
+}