@neo4j-nvl/react 1.0.0-0e1dd35b-alpha → 1.0.0-0f60498a

package/CHANGELOG.md

@@ -2,6 +2,31 @@
 
 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.1.0] - 2026-02-16
+
+This 1.1.0 release introduces new rendering capabilities with the addition of a new SVG export method, alongside a new Circular Layout algorithm and touchpad gestures for zooming. It also includes performance improvements for the renderer and physics engine, as well as various fixes for the React wrappers and Minimap.
+
+### Added
+
+- new SVG export functionality.
+- new circular layout option.
+- two-finger pinch gesture to zoom with touchpads.
+- onCanvasDoubleClick callback to the interactive NVL React wrapper.
+
+### Changed
+
+- improved minimap handling for React components.
+- rendering performance improvements.
+- physics layout performance and gravity improvements.
+
+### Fixed
+
+- seed radius calculation in D3 layout for large graphs.
+- forceDirected layout unnecessarily reheating on switch without changes.
+- ensure drag operations are always correctly ended on mouse up.
+- minimap positioning issues.
+- background color for the 'os' theme in api documentation.
+
 ## [1.0.0] - 2025-09-30
 This 1.0.0 release is our first major release, with NVL's release strategy fully adopting semantic versioning going forward. Updates in this release include React 19 support for the React wrappers, a UI overhaul of the [examples app](https://neo4j.com/docs/api/nvl/current/examples.html).
 

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

@@ -0,0 +1 @@
+import '@testing-library/jest-dom';

package/lib/__tests__/BasicNvlWrapper.test.js

@@ -0,0 +1,69 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import NVL, { HierarchicalLayoutType } from '@neo4j-nvl/base';
+import '@testing-library/jest-dom';
+import { render } from '@testing-library/react';
+import React from 'react';
+import { BasicNvlWrapper } from '../basic-wrapper/BasicNvlWrapper';
+jest.mock('@neo4j-nvl/base');
+jest.mock('@neo4j-nvl/layout-workers');
+describe('BasicNvlWrapper', () => {
+    afterEach(() => {
+        jest.clearAllMocks();
+    });
+    test('initialises NVL expectedly with an empty graph object and no other properties', () => {
+        render(_jsx("div", { children: _jsx(BasicNvlWrapper, { nodes: [], rels: [] }) }));
+        expect(NVL).toHaveBeenCalledWith(expect.any(HTMLDivElement), [], [], {}, {});
+    });
+    test('initialises NVL expectedly with a graph object and properties', () => {
+        const mockLayoutDoneFunction = jest.fn();
+        render(_jsx("div", { children: _jsx(BasicNvlWrapper, { nodes: [{ id: '1' }, { id: '2' }], rels: [{ id: '12', from: '1', to: '2' }], layout: HierarchicalLayoutType, layoutOptions: { enableCytoscape: true }, nvlOptions: { renderer: 'canvas' }, nvlCallbacks: { onLayoutDone: mockLayoutDoneFunction } }) }));
+        expect(NVL).toHaveBeenCalledWith(expect.any(HTMLDivElement), [{ id: '1' }, { id: '2' }], [{ id: '12', from: '1', to: '2' }], { renderer: 'canvas', layout: HierarchicalLayoutType, layoutOptions: { enableCytoscape: true } }, {
+            onLayoutDone: mockLayoutDoneFunction
+        });
+    });
+    test('destroys NVL on unmount', () => {
+        const destroy = jest.fn();
+        jest.spyOn(NVL.prototype, 'destroy').mockImplementation(destroy);
+        const { unmount } = render(_jsx("div", { children: _jsx(BasicNvlWrapper, { nodes: [], rels: [] }) }));
+        unmount();
+        expect(NVL).toHaveBeenCalledTimes(1);
+        expect(destroy).toHaveBeenCalledTimes(1);
+    });
+    test('successfully re-initialises NVL when using React StrictMode', () => {
+        const destroy = jest.fn();
+        jest.spyOn(NVL.prototype, 'destroy').mockImplementation(destroy);
+        render(_jsx(React.StrictMode, { children: _jsx("div", { children: _jsx(BasicNvlWrapper, { nodes: [], rels: [] }) }) }));
+        expect(NVL).toHaveBeenCalledTimes(2);
+        expect(destroy).toHaveBeenCalledTimes(1);
+    });
+    test('calls setZoom when zoom property is provided', () => {
+        const setZoom = jest.fn();
+        jest.spyOn(NVL.prototype, 'setZoom').mockImplementation(setZoom);
+        render(_jsx("div", { children: _jsx(BasicNvlWrapper, { nodes: [], rels: [], zoom: 1.5 }) }));
+        expect(setZoom).toHaveBeenCalledWith(1.5);
+    });
+    test('calls setPan when pan property is provided', () => {
+        const setPan = jest.fn();
+        jest.spyOn(NVL.prototype, 'setPan').mockImplementation(setPan);
+        render(_jsx("div", { children: _jsx(BasicNvlWrapper, { nodes: [], rels: [], pan: { x: 10, y: 20 } }) }));
+        expect(setPan).toHaveBeenCalledWith(10, 20);
+    });
+    test('calls setZoomAndPan when both zoom and pan properties are provided', () => {
+        const setZoomAndPan = jest.fn();
+        jest.spyOn(NVL.prototype, 'setZoomAndPan').mockImplementation(setZoomAndPan);
+        render(_jsx("div", { children: _jsx(BasicNvlWrapper, { nodes: [], rels: [], zoom: 1.5, pan: { x: 10, y: 20 } }) }));
+        expect(setZoomAndPan).toHaveBeenCalledWith(1.5, 10, 20);
+    });
+    test('does not call zoom/pan methods when properties are undefined', () => {
+        const setZoom = jest.fn();
+        jest.spyOn(NVL.prototype, 'setZoom').mockImplementation(setZoom);
+        const setPan = jest.fn();
+        jest.spyOn(NVL.prototype, 'setPan').mockImplementation(setPan);
+        const setZoomAndPan = jest.fn();
+        jest.spyOn(NVL.prototype, 'setZoomAndPan').mockImplementation(setZoomAndPan);
+        render(_jsx("div", { children: _jsx(BasicNvlWrapper, { nodes: [], rels: [] }) }));
+        expect(setZoom).not.toHaveBeenCalled();
+        expect(setPan).not.toHaveBeenCalled();
+        expect(setZoomAndPan).not.toHaveBeenCalled();
+    });
+});

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

@@ -0,0 +1 @@
+import '@testing-library/jest-dom';

package/lib/__tests__/InteractiveNvlWrapper.test.js

@@ -0,0 +1,331 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import NVL, { HierarchicalLayoutType } from '@neo4j-nvl/base';
+import { BoxSelectInteraction, ClickInteraction, DragNodeInteraction, DrawInteraction, HoverInteraction, LassoInteraction, PanInteraction, ZoomInteraction } from '@neo4j-nvl/interaction-handlers';
+import '@testing-library/jest-dom';
+import { render } from '@testing-library/react';
+import React, { act, createRef } from 'react';
+import { InteractiveNvlWrapper } from '../interactive-nvl-wrapper/InteractiveNvlWrapper';
+jest.mock('@neo4j-nvl/base');
+jest.mock('@neo4j-nvl/layout-workers');
+jest.mock('@neo4j-nvl/interaction-handlers');
+const MockedNVL = NVL;
+let mockOnInitialization;
+HoverInteraction.prototype.callbackMap = new Map();
+HoverInteraction.prototype.updateCallback = jest.fn();
+HoverInteraction.prototype.removeCallback = jest.fn();
+HoverInteraction.prototype.destroy = jest.fn();
+PanInteraction.prototype.callbackMap = new Map();
+PanInteraction.prototype.updateCallback = jest.fn();
+PanInteraction.prototype.removeCallback = jest.fn();
+PanInteraction.prototype.destroy = jest.fn();
+ClickInteraction.prototype.callbackMap = new Map();
+ClickInteraction.prototype.updateCallback = jest.fn();
+ClickInteraction.prototype.removeCallback = jest.fn();
+ClickInteraction.prototype.destroy = jest.fn();
+ZoomInteraction.prototype.callbackMap = new Map();
+ZoomInteraction.prototype.updateCallback = jest.fn();
+ZoomInteraction.prototype.removeCallback = jest.fn();
+ZoomInteraction.prototype.destroy = jest.fn();
+DragNodeInteraction.prototype.callbackMap = new Map();
+DragNodeInteraction.prototype.updateCallback = jest.fn();
+DragNodeInteraction.prototype.removeCallback = jest.fn();
+DragNodeInteraction.prototype.destroy = jest.fn();
+DrawInteraction.prototype.callbackMap = new Map();
+DrawInteraction.prototype.updateCallback = jest.fn();
+DrawInteraction.prototype.removeCallback = jest.fn();
+DrawInteraction.prototype.destroy = jest.fn();
+BoxSelectInteraction.prototype.callbackMap = new Map();
+BoxSelectInteraction.prototype.updateCallback = jest.fn();
+BoxSelectInteraction.prototype.removeCallback = jest.fn();
+BoxSelectInteraction.prototype.destroy = jest.fn();
+LassoInteraction.prototype.callbackMap = new Map();
+LassoInteraction.prototype.updateCallback = jest.fn();
+LassoInteraction.prototype.removeCallback = jest.fn();
+LassoInteraction.prototype.destroy = jest.fn();
+let mockDestroy;
+let destroyHoverInteraction;
+let destroyPanInteraction;
+describe('InteractiveNvlWrapper', () => {
+    beforeEach(() => {
+        jest.spyOn(NVL.prototype, 'getContainer').mockImplementation(() => document.createElement('div'));
+        MockedNVL.mockImplementation((_container, _nodes, _rels, _options, callbacks) => {
+            mockOnInitialization = callbacks.onInitialization;
+            return {
+                getContainer: () => document.createElement('div'),
+                destroy: mockDestroy,
+                setLayout: jest.fn(),
+                setLayoutOptions: jest.fn(),
+                setRenderer: jest.fn()
+            };
+        });
+        mockDestroy = jest.fn();
+        destroyHoverInteraction = jest.fn();
+        destroyPanInteraction = jest.fn();
+        jest.spyOn(NVL.prototype, 'destroy').mockImplementation(mockDestroy);
+        jest.spyOn(HoverInteraction.prototype, 'destroy').mockImplementation(destroyHoverInteraction);
+        jest.spyOn(PanInteraction.prototype, 'destroy').mockImplementation(destroyPanInteraction);
+        jest.spyOn(ClickInteraction.prototype, 'destroy').mockImplementation(jest.fn());
+        jest.spyOn(ZoomInteraction.prototype, 'destroy').mockImplementation(jest.fn());
+        jest.spyOn(DragNodeInteraction.prototype, 'destroy').mockImplementation(jest.fn());
+        jest.spyOn(DrawInteraction.prototype, 'destroy').mockImplementation(jest.fn());
+        jest.spyOn(BoxSelectInteraction.prototype, 'destroy').mockImplementation(jest.fn());
+        jest.spyOn(LassoInteraction.prototype, 'destroy').mockImplementation(jest.fn());
+    });
+    afterEach(() => {
+        jest.clearAllMocks();
+    });
+    test('initialises NVL expectedly with an empty graph object and no other properties', () => {
+        render(_jsx("div", { children: _jsx(InteractiveNvlWrapper, { nodes: [], rels: [] }) }));
+        expect(NVL).toHaveBeenCalledWith(expect.any(HTMLDivElement), [], [], {}, { onInitialization: mockOnInitialization });
+    });
+    test('initialises NVL expectedly with a graph object and properties', () => {
+        const mockLayoutDoneFunction = jest.fn();
+        render(_jsx(InteractiveNvlWrapper, { nodes: [{ id: '1' }, { id: '2' }], rels: [{ id: '12', from: '1', to: '2' }], layout: HierarchicalLayoutType, layoutOptions: { enableCytoscape: true }, nvlOptions: { renderer: 'canvas' }, nvlCallbacks: { onLayoutDone: mockLayoutDoneFunction } }));
+        act(() => {
+            mockOnInitialization?.();
+        });
+        expect(NVL).toHaveBeenCalledWith(expect.any(HTMLDivElement), [{ id: '1' }, { id: '2' }], [{ id: '12', from: '1', to: '2' }], { renderer: 'canvas', layout: HierarchicalLayoutType, layoutOptions: { enableCytoscape: true } }, {
+            onLayoutDone: mockLayoutDoneFunction,
+            onInitialization: mockOnInitialization
+        });
+    });
+    test('initialises expected interaction handlers with correct options', () => {
+        const myNvlRef = createRef();
+        render(_jsx(InteractiveNvlWrapper, { nodes: [], rels: [], ref: myNvlRef, mouseEventCallbacks: {
+                onHover: true,
+                onPan: true
+            }, interactionOptions: {
+                drawShadowOnHover: true
+            } }));
+        act(() => {
+            mockOnInitialization?.();
+        });
+        expect(HoverInteraction).toHaveBeenCalledWith(myNvlRef.current, { drawShadowOnHover: true });
+        expect(PanInteraction).toHaveBeenCalledWith(myNvlRef.current, { drawShadowOnHover: true });
+        expect(HoverInteraction).toHaveBeenCalledTimes(1);
+        expect(PanInteraction).toHaveBeenCalledTimes(1);
+        expect(ClickInteraction).not.toHaveBeenCalled();
+        expect(DragNodeInteraction).not.toHaveBeenCalled();
+        expect(DrawInteraction).not.toHaveBeenCalled();
+        expect(ZoomInteraction).not.toHaveBeenCalled();
+        expect(BoxSelectInteraction).not.toHaveBeenCalled();
+        expect(LassoInteraction).not.toHaveBeenCalled();
+    });
+    test.each([
+        {
+            name: 'HoverInteraction',
+            InteractionClass: HoverInteraction,
+            callback: { onHover: jest.fn() },
+            options: { drawShadowOnHover: true }
+        },
+        {
+            name: 'ClickInteraction with onCanvasClick',
+            InteractionClass: ClickInteraction,
+            callback: { onCanvasClick: jest.fn() },
+            options: { selectOnClick: false }
+        },
+        {
+            name: 'ClickInteraction with onCanvasDoubleClick',
+            InteractionClass: ClickInteraction,
+            callback: { onCanvasDoubleClick: jest.fn() },
+            options: { selectOnClick: false }
+        },
+        {
+            name: 'ClickInteraction with onCanvasRightClick',
+            InteractionClass: ClickInteraction,
+            callback: { onCanvasRightClick: jest.fn() },
+            options: { selectOnClick: false }
+        },
+        {
+            name: 'ClickInteraction with onNodeClick',
+            InteractionClass: ClickInteraction,
+            callback: { onNodeClick: jest.fn() },
+            options: { selectOnClick: true }
+        },
+        {
+            name: 'ClickInteraction with onNodeDoubleClick',
+            InteractionClass: ClickInteraction,
+            callback: { onNodeDoubleClick: jest.fn() },
+            options: { selectOnClick: false }
+        },
+        {
+            name: 'ClickInteraction with onNodeRightClick',
+            InteractionClass: ClickInteraction,
+            callback: { onNodeRightClick: jest.fn() },
+            options: { selectOnClick: false }
+        },
+        {
+            name: 'ClickInteraction with onRelationshipClick',
+            InteractionClass: ClickInteraction,
+            callback: { onRelationshipClick: jest.fn() },
+            options: { selectOnClick: false }
+        },
+        {
+            name: 'ClickInteraction with onRelationshipDoubleClick',
+            InteractionClass: ClickInteraction,
+            callback: { onRelationshipDoubleClick: jest.fn() },
+            options: { selectOnClick: false }
+        },
+        {
+            name: 'ClickInteraction with onRelationshipRightClick',
+            InteractionClass: ClickInteraction,
+            callback: { onRelationshipRightClick: jest.fn() },
+            options: { selectOnClick: false }
+        },
+        {
+            name: 'PanInteraction',
+            InteractionClass: PanInteraction,
+            callback: { onPan: jest.fn() },
+            options: {}
+        },
+        {
+            name: 'ZoomInteraction',
+            InteractionClass: ZoomInteraction,
+            callback: { onZoom: jest.fn() },
+            options: {}
+        },
+        {
+            name: 'DragNodeInteraction with onDrag',
+            InteractionClass: DragNodeInteraction,
+            callback: { onDrag: jest.fn() },
+            options: { selectOnRelease: false }
+        },
+        {
+            name: 'DragNodeInteraction with onDragStart',
+            InteractionClass: DragNodeInteraction,
+            callback: { onDragStart: jest.fn() },
+            options: {}
+        },
+        {
+            name: 'DragNodeInteraction with onDragEnd',
+            InteractionClass: DragNodeInteraction,
+            callback: { onDragEnd: jest.fn() },
+            options: {}
+        },
+        {
+            name: 'DrawInteraction with onHoverNodeMargin',
+            InteractionClass: DrawInteraction,
+            callback: { onHoverNodeMargin: jest.fn() },
+            options: { excludeNodeMargin: false }
+        },
+        {
+            name: 'DrawInteraction with onDrawStarted',
+            InteractionClass: DrawInteraction,
+            callback: { onDrawStarted: jest.fn() },
+            options: {}
+        },
+        {
+            name: 'DrawInteraction with onDrawEnded',
+            InteractionClass: DrawInteraction,
+            callback: { onDrawEnded: jest.fn() },
+            options: {}
+        },
+        {
+            name: 'BoxSelectInteraction with onBoxStarted',
+            InteractionClass: BoxSelectInteraction,
+            callback: { onBoxStarted: jest.fn() },
+            options: {}
+        },
+        {
+            name: 'BoxSelectInteraction with onBoxSelect',
+            InteractionClass: BoxSelectInteraction,
+            callback: { onBoxSelect: jest.fn() },
+            options: {}
+        },
+        {
+            name: 'LassoInteraction with onLassoStarted',
+            InteractionClass: LassoInteraction,
+            callback: { onLassoStarted: jest.fn() },
+            options: {}
+        },
+        {
+            name: 'LassoInteraction with onLassoSelect',
+            InteractionClass: LassoInteraction,
+            callback: { onLassoSelect: jest.fn() },
+            options: {}
+        }
+    ])('initialises $name when its callback is provided', ({ InteractionClass, callback, options }) => {
+        const myNvlRef = createRef();
+        render(_jsx(InteractiveNvlWrapper, { nodes: [], rels: [], ref: myNvlRef, mouseEventCallbacks: callback, interactionOptions: options }));
+        act(() => {
+            mockOnInitialization?.();
+        });
+        expect(InteractionClass).toHaveBeenCalledWith(myNvlRef.current, options);
+        expect(InteractionClass).toHaveBeenCalledTimes(1);
+    });
+    test('does not attempt to initialize interaction handlers if NVL container is not available', () => {
+        const myNvlRef = createRef();
+        // eslint-disable-next-line @typescript-eslint/ban-ts-comment
+        // @ts-expect-error
+        jest.spyOn(NVL.prototype, 'getContainer').mockImplementation(() => null);
+        render(_jsx(InteractiveNvlWrapper, { nodes: [], rels: [], ref: myNvlRef, mouseEventCallbacks: {
+                onHover: true
+            }, interactionOptions: {
+                drawShadowOnHover: true
+            } }));
+        expect(HoverInteraction).not.toHaveBeenCalled();
+        expect(NVL).toHaveBeenCalledTimes(1);
+    });
+    test('destroys NVL and active interaction handlers on unmount', () => {
+        const { unmount } = render(_jsx(InteractiveNvlWrapper, { nodes: [], rels: [], mouseEventCallbacks: {
+                onHover: true
+            } }));
+        act(() => {
+            mockOnInitialization?.();
+        });
+        unmount();
+        expect(mockDestroy).toHaveBeenCalledTimes(1);
+        expect(destroyHoverInteraction).toHaveBeenCalledTimes(1);
+        expect(destroyPanInteraction).not.toHaveBeenCalled();
+    });
+    test('successfully re-initialises NVL and active interaction handlers when using React StrictMode', () => {
+        const myNvlRef = createRef();
+        render(_jsx(React.StrictMode, { children: _jsx(InteractiveNvlWrapper, { nodes: [], rels: [], ref: myNvlRef, mouseEventCallbacks: {
+                    onHover: true
+                }, interactionOptions: {
+                    drawShadowOnHover: true
+                } }) }));
+        act(() => {
+            mockOnInitialization?.();
+        });
+        expect(NVL).toHaveBeenCalledTimes(2);
+        expect(HoverInteraction).toHaveBeenCalledTimes(2);
+        expect(HoverInteraction).toHaveBeenCalledWith(myNvlRef.current, { drawShadowOnHover: true });
+        expect(mockDestroy).toHaveBeenCalledTimes(1);
+        expect(destroyHoverInteraction).toHaveBeenCalledTimes(1);
+        expect(destroyPanInteraction).not.toHaveBeenCalled();
+        expect(DragNodeInteraction).not.toHaveBeenCalled();
+        expect(DrawInteraction).not.toHaveBeenCalled();
+        expect(ZoomInteraction).not.toHaveBeenCalled();
+        expect(BoxSelectInteraction).not.toHaveBeenCalled();
+        expect(LassoInteraction).not.toHaveBeenCalled();
+    });
+    test('also calls custom callbacks on initialization', () => {
+        const customOnInitializationCallback = jest.fn();
+        render(_jsx(InteractiveNvlWrapper, { nodes: [], rels: [], nvlCallbacks: { onInitialization: customOnInitializationCallback } }));
+        act(() => {
+            mockOnInitialization?.();
+        });
+        expect(customOnInitializationCallback).toHaveBeenCalledTimes(1);
+    });
+    test('passes zoom and pan properties to BasicNvlWrapper', () => {
+        const setZoom = jest.fn();
+        const setPan = jest.fn();
+        const setZoomAndPan = jest.fn();
+        MockedNVL.mockImplementation(() => ({
+            getContainer: () => document.createElement('div'),
+            destroy: jest.fn(),
+            setLayout: jest.fn(),
+            setLayoutOptions: jest.fn(),
+            setNodePositions: jest.fn(),
+            setZoom,
+            setPan,
+            setZoomAndPan
+        }));
+        render(_jsx(InteractiveNvlWrapper, { nodes: [], rels: [], zoom: 1.5, pan: { x: 10, y: 20 } }));
+        act(() => {
+            mockOnInitialization?.();
+        });
+        expect(setZoomAndPan).toHaveBeenCalledWith(1.5, 10, 20);
+    });
+});

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

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

package/lib/__tests__/index.test.js

@@ -0,0 +1,8 @@
+import * as exportedModules from '../index';
+jest.mock('@neo4j-nvl/layout-workers');
+describe('index', () => {
+    test('provides the expected components', () => {
+        const modules = Object.keys(exportedModules);
+        expect(modules).toContain('BasicNvlWrapper');
+    });
+});

package/lib/basic-wrapper/BasicNvlWrapper.d.ts

@@ -0,0 +1,48 @@
+import type { ExternalCallbacks, Layout, LayoutOptions, Node, NvlOptions, Relationship } from '@neo4j-nvl/base';
+import NVL from '@neo4j-nvl/base';
+import { type HTMLProps } from 'react';
+/**
+ * The properties that can be passed to the {@link BasicNvlWrapper} component.
+ */
+export interface BasicReactWrapperProps {
+    /** The nodes of the graph of type Node[] */
+    nodes: Node[];
+    /** The rels of the graph of type Relationship[] */
+    rels: Relationship[];
+    /** The layout, can be 'forceDirected' or 'hierarchical' */
+    layout?: Layout;
+    /** Options for the current layout */
+    layoutOptions?: LayoutOptions;
+    /** an Object containing functions for callbacks on certain actions */
+    nvlCallbacks?: ExternalCallbacks;
+    /** An object containing options for the Nvl instance */
+    nvlOptions?: NvlOptions;
+    /** Sets the positions of the nodes in the graph using the setNodePositions method. */
+    positions?: Node[];
+    /**
+     * Sets the zoom level of the viewport using the setZoom method.
+     * @remarks If both zoom and pan are provided, the setZoomAndPan method will be used.
+     */
+    zoom?: number;
+    /**
+     * Sets the pan coordinates of the viewport using the setPan method.
+     * @remarks If both zoom and pan are provided, the setZoomAndPan method will be used.
+     */
+    pan?: {
+        /** The x coordinate of the pan. */
+        x: number;
+        /** The y coordinate of the pan. */
+        y: number;
+    };
+    /** A callback to handle any errors that happen during NVL initialization */
+    onInitializationError?: (error: unknown) => void;
+}
+/**
+ *
+ * A basic React wrapper that wraps the NVL base library within a React component.
+ * It takes the class' arguments as properties, which are passed to the NVL constructor.
+ * Any changes in properties will be reflected in the NVL instance by calling the corresponding methods.
+ *
+ * For examples, head to the {@link https://neo4j.com/docs/nvl/current/react-wrappers/#_basic_react_wrapper Basic React wrapper documentation page}.
+ */
+export declare const BasicNvlWrapper: import("react").MemoExoticComponent<import("react").ForwardRefExoticComponent<Omit<BasicReactWrapperProps & HTMLProps<HTMLDivElement>, "ref"> & import("react").RefAttributes<Partial<Pick<NVL, "restart" | "destroy" | "addAndUpdateElementsInGraph" | "getSelectedNodes" | "getSelectedRelationships" | "removeNodesWithIds" | "removeRelationshipsWithIds" | "getNodes" | "getRelationships" | "getNodeById" | "getRelationshipById" | "getPositionById" | "getCurrentOptions" | "deselectAll" | "fit" | "resetZoom" | "setRenderer" | "setDisableWebGL" | "pinNode" | "unPinNode" | "setLayout" | "setLayoutOptions" | "getNodesOnScreen" | "getNodePositions" | "setNodePositions" | "isLayoutMoving" | "saveToFile" | "saveToSvg" | "getImageDataUrl" | "saveFullGraphToLargeFile" | "setZoom" | "getScale" | "getPan" | "getHits" | "getContainer">>>>>;

package/lib/basic-wrapper/BasicNvlWrapper.js

@@ -0,0 +1,141 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import NVL from '@neo4j-nvl/base';
+import { forwardRef, memo, useEffect, useImperativeHandle, useRef, useState } from 'react';
+import { BASIC_WRAPPER_ID } from '../utils/constants';
+import { getMapDifferences, getNodeAttributeDifferences } from '../utils/graph-comparison';
+import { useDeepCompareEffect } from '../utils/hooks';
+/**
+ *
+ * A basic React wrapper that wraps the NVL base library within a React component.
+ * It takes the class' arguments as properties, which are passed to the NVL constructor.
+ * Any changes in properties will be reflected in the NVL instance by calling the corresponding methods.
+ *
+ * For examples, head to the {@link https://neo4j.com/docs/nvl/current/react-wrappers/#_basic_react_wrapper Basic React wrapper documentation page}.
+ */
+export const BasicNvlWrapper = memo(forwardRef(({ nodes, rels, layout, layoutOptions, nvlCallbacks = {}, nvlOptions = {}, positions = [], zoom, pan, onInitializationError, ...nvlEvents }, ref) => {
+    const nvlRef = useRef(null);
+    useImperativeHandle(ref, () => {
+        const nvlMethods = Object.getOwnPropertyNames(NVL.prototype);
+        return nvlMethods.reduce((current, method) => ({
+            ...current,
+            [method]: (...args) => {
+                if (nvlRef.current === null) {
+                    return null;
+                }
+                // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
+                return nvlRef.current[method](...args);
+            }
+        }), {});
+    });
+    const containerRef = useRef(null);
+    const [currentNodes, setCurrentNodes] = useState(nodes);
+    const [currentRels, setCurrentRels] = useState(rels);
+    useEffect(() => {
+        return () => {
+            nvlRef.current?.destroy();
+            nvlRef.current = null;
+        };
+    }, []);
+    useEffect(() => {
+        let newNvl = null;
+        const hasMinimap = 'minimapContainer' in nvlOptions;
+        const minimapContainerIsReady = hasMinimap ? nvlOptions.minimapContainer !== null : true;
+        const mainContainerIsReady = containerRef.current !== null;
+        if (mainContainerIsReady && minimapContainerIsReady) {
+            if (nvlRef.current === null) {
+                const combinedOptions = { ...nvlOptions, layoutOptions };
+                if (layout !== undefined) {
+                    combinedOptions.layout = layout;
+                }
+                try {
+                    newNvl = new NVL(containerRef.current, currentNodes, currentRels, combinedOptions, nvlCallbacks);
+                    nvlRef.current = newNvl;
+                    setCurrentRels(rels);
+                    setCurrentNodes(nodes);
+                }
+                catch (e) {
+                    if (typeof onInitializationError === 'function') {
+                        onInitializationError(e);
+                    }
+                    else {
+                        throw e;
+                    }
+                }
+            }
+        }
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [containerRef.current, nvlOptions.minimapContainer]);
+    useEffect(() => {
+        if (nvlRef.current === null) {
+            return;
+        }
+        const nodeChanges = getMapDifferences(currentNodes, nodes);
+        const nodeDiff = getNodeAttributeDifferences(currentNodes, nodes);
+        const relChanges = getMapDifferences(currentRels, rels);
+        const graphIsUnchanged = nodeChanges.added.length === 0 &&
+            nodeChanges.removed.length === 0 &&
+            nodeDiff.length === 0 &&
+            relChanges.added.length === 0 &&
+            relChanges.removed.length === 0 &&
+            relChanges.updated.length === 0;
+        if (graphIsUnchanged) {
+            return;
+        }
+        setCurrentRels(rels);
+        setCurrentNodes(nodes);
+        const nodesToAddAndUpdate = [...nodeChanges.added, ...nodeDiff];
+        const relsToAddAndUpdate = [...relChanges.added, ...relChanges.updated];
+        nvlRef.current.addAndUpdateElementsInGraph(nodesToAddAndUpdate, relsToAddAndUpdate);
+        const relationshipsToRemove = relChanges.removed.map((r) => r.id);
+        const nodesToRemove = nodeChanges.removed.map((n) => n.id);
+        nvlRef.current.removeRelationshipsWithIds(relationshipsToRemove);
+        nvlRef.current.removeNodesWithIds(nodesToRemove);
+    }, [currentNodes, currentRels, nodes, rels]);
+    useEffect(() => {
+        const updatedLayout = layout ?? nvlOptions.layout;
+        if (nvlRef.current === null || updatedLayout === undefined) {
+            return;
+        }
+        nvlRef.current.setLayout(updatedLayout);
+    }, [layout, nvlOptions.layout]);
+    useDeepCompareEffect(() => {
+        const updatedLayoutOptions = layoutOptions ?? nvlOptions?.layoutOptions;
+        if (nvlRef.current === null || updatedLayoutOptions === undefined) {
+            return;
+        }
+        nvlRef.current.setLayoutOptions(updatedLayoutOptions);
+    }, [layoutOptions, nvlOptions.layoutOptions]);
+    useEffect(() => {
+        if (nvlRef.current === null || nvlOptions.renderer === undefined) {
+            return;
+        }
+        nvlRef.current.setRenderer(nvlOptions.renderer);
+    }, [nvlOptions.renderer]);
+    useEffect(() => {
+        if (nvlRef.current === null || nvlOptions.disableWebGL === undefined) {
+            return;
+        }
+        nvlRef.current.setDisableWebGL(nvlOptions.disableWebGL);
+    }, [nvlOptions.disableWebGL]);
+    useEffect(() => {
+        if (nvlRef.current === null || positions.length === 0) {
+            return;
+        }
+        nvlRef.current.setNodePositions(positions);
+    }, [positions]);
+    useEffect(() => {
+        if (nvlRef.current === null) {
+            return;
+        }
+        if (zoom !== undefined && pan !== undefined) {
+            nvlRef.current.setZoomAndPan(zoom, pan.x, pan.y);
+        }
+        else if (zoom !== undefined) {
+            nvlRef.current.setZoom(zoom);
+        }
+        else if (pan !== undefined) {
+            nvlRef.current.setPan(pan.x, pan.y);
+        }
+    }, [zoom, pan]);
+    return _jsx("div", { id: BASIC_WRAPPER_ID, ref: containerRef, style: { height: '100%', outline: '0' }, ...nvlEvents });
+}));

package/lib/index.d.ts

@@ -0,0 +1,8 @@
+import { BasicNvlWrapper } from './basic-wrapper/BasicNvlWrapper';
+import type { BasicReactWrapperProps } from './basic-wrapper/BasicNvlWrapper';
+import { InteractiveNvlWrapper } from './interactive-nvl-wrapper/InteractiveNvlWrapper';
+import type { InteractionOptions, InteractiveNvlWrapperProps, MouseEvent, MouseEventCallbacks } from './interactive-nvl-wrapper/types';
+import type { StaticPictureWrapperProps } from './static-picture-wrapper/StaticPictureWrapper';
+import { StaticPictureWrapper } from './static-picture-wrapper/StaticPictureWrapper';
+export { BasicNvlWrapper, InteractiveNvlWrapper, StaticPictureWrapper };
+export type { MouseEventCallbacks, MouseEvent, BasicReactWrapperProps, InteractionOptions, InteractiveNvlWrapperProps, StaticPictureWrapperProps };

package/lib/index.js

@@ -0,0 +1,4 @@
+import { BasicNvlWrapper } from './basic-wrapper/BasicNvlWrapper';
+import { InteractiveNvlWrapper } from './interactive-nvl-wrapper/InteractiveNvlWrapper';
+import { StaticPictureWrapper } from './static-picture-wrapper/StaticPictureWrapper';
+export { BasicNvlWrapper, InteractiveNvlWrapper, StaticPictureWrapper };

package/lib/interactive-nvl-wrapper/InteractionHandlers.d.ts

@@ -0,0 +1,10 @@
+import type NVL from '@neo4j-nvl/base';
+import type { MutableRefObject } from 'react';
+import type { InteractionOptions, MouseEventCallbacks } from './types';
+interface InteractionHandlersProps {
+    nvlRef: MutableRefObject<NVL | null>;
+    mouseEventCallbacks: MouseEventCallbacks;
+    interactionOptions: InteractionOptions;
+}
+export declare const InteractionHandlers: React.FC<InteractionHandlersProps>;
+export {};

package/lib/interactive-nvl-wrapper/InteractionHandlers.js

@@ -0,0 +1,46 @@
+import { BoxSelectInteraction, ClickInteraction, DragNodeInteraction, DrawInteraction, HoverInteraction, LassoInteraction, PanInteraction, ZoomInteraction } from '@neo4j-nvl/interaction-handlers';
+import { useEffect, useRef } from 'react';
+import { destroyInteraction, useInteraction } from './hooks';
+export const InteractionHandlers = ({ nvlRef, mouseEventCallbacks, interactionOptions }) => {
+    const hoverInteraction = useRef(null);
+    const clickInteraction = useRef(null);
+    const panInteraction = useRef(null);
+    const zoomInteraction = useRef(null);
+    const dragNodeInteraction = useRef(null);
+    const drawInteraction = useRef(null);
+    const multiSelectInteraction = useRef(null);
+    const lassoInteraction = useRef(null);
+    useInteraction(HoverInteraction, hoverInteraction, mouseEventCallbacks.onHover, 'onHover', nvlRef, interactionOptions);
+    useInteraction(ClickInteraction, clickInteraction, mouseEventCallbacks.onNodeClick, 'onNodeClick', nvlRef, interactionOptions);
+    useInteraction(ClickInteraction, clickInteraction, mouseEventCallbacks.onNodeDoubleClick, 'onNodeDoubleClick', nvlRef, interactionOptions);
+    useInteraction(ClickInteraction, clickInteraction, mouseEventCallbacks.onNodeRightClick, 'onNodeRightClick', nvlRef, interactionOptions);
+    useInteraction(ClickInteraction, clickInteraction, mouseEventCallbacks.onRelationshipClick, 'onRelationshipClick', nvlRef, interactionOptions);
+    useInteraction(ClickInteraction, clickInteraction, mouseEventCallbacks.onRelationshipDoubleClick, 'onRelationshipDoubleClick', nvlRef, interactionOptions);
+    useInteraction(ClickInteraction, clickInteraction, mouseEventCallbacks.onRelationshipRightClick, 'onRelationshipRightClick', nvlRef, interactionOptions);
+    useInteraction(ClickInteraction, clickInteraction, mouseEventCallbacks.onCanvasClick, 'onCanvasClick', nvlRef, interactionOptions);
+    useInteraction(ClickInteraction, clickInteraction, mouseEventCallbacks.onCanvasDoubleClick, 'onCanvasDoubleClick', nvlRef, interactionOptions);
+    useInteraction(ClickInteraction, clickInteraction, mouseEventCallbacks.onCanvasRightClick, 'onCanvasRightClick', nvlRef, interactionOptions);
+    useInteraction(PanInteraction, panInteraction, mouseEventCallbacks.onPan, 'onPan', nvlRef, interactionOptions);
+    useInteraction(ZoomInteraction, zoomInteraction, mouseEventCallbacks.onZoom, 'onZoom', nvlRef, interactionOptions);
+    useInteraction(DragNodeInteraction, dragNodeInteraction, mouseEventCallbacks.onDrag, 'onDrag', nvlRef, interactionOptions);
+    useInteraction(DragNodeInteraction, dragNodeInteraction, mouseEventCallbacks.onDragStart, 'onDragStart', nvlRef, interactionOptions);
+    useInteraction(DragNodeInteraction, dragNodeInteraction, mouseEventCallbacks.onDragEnd, 'onDragEnd', nvlRef, interactionOptions);
+    useInteraction(DrawInteraction, drawInteraction, mouseEventCallbacks.onHoverNodeMargin, 'onHoverNodeMargin', nvlRef, interactionOptions);
+    useInteraction(DrawInteraction, drawInteraction, mouseEventCallbacks.onDrawStarted, 'onDrawStarted', nvlRef, interactionOptions);
+    useInteraction(DrawInteraction, drawInteraction, mouseEventCallbacks.onDrawEnded, 'onDrawEnded', nvlRef, interactionOptions);
+    useInteraction(BoxSelectInteraction, multiSelectInteraction, mouseEventCallbacks.onBoxStarted, 'onBoxStarted', nvlRef, interactionOptions);
+    useInteraction(BoxSelectInteraction, multiSelectInteraction, mouseEventCallbacks.onBoxSelect, 'onBoxSelect', nvlRef, interactionOptions);
+    useInteraction(LassoInteraction, lassoInteraction, mouseEventCallbacks.onLassoStarted, 'onLassoStarted', nvlRef, interactionOptions);
+    useInteraction(LassoInteraction, lassoInteraction, mouseEventCallbacks.onLassoSelect, 'onLassoSelect', nvlRef, interactionOptions);
+    useEffect(() => () => {
+        destroyInteraction(hoverInteraction);
+        destroyInteraction(clickInteraction);
+        destroyInteraction(panInteraction);
+        destroyInteraction(zoomInteraction);
+        destroyInteraction(dragNodeInteraction);
+        destroyInteraction(drawInteraction);
+        destroyInteraction(multiSelectInteraction);
+        destroyInteraction(lassoInteraction);
+    }, []);
+    return null;
+};

package/lib/interactive-nvl-wrapper/InteractiveNvlWrapper.d.ts

@@ -0,0 +1,16 @@
+import type NVL from '@neo4j-nvl/base';
+import type { HTMLProps } from 'react';
+import React from 'react';
+import type { InteractiveNvlWrapperProps } from './types';
+/**
+ * The interactive React wrapper component contains a collection of interaction handlers by default
+ * and provides a variety of common functionality and callbacks.
+ * It is an extension of the {@link BasicNvlWrapper} component and incorporates the
+ * @neo4j-nvl/interaction-handlers module's decorators to provide a set of interaction events.
+ *
+ * The mouseEventCallbacks property takes an object where various callbacks can be defined
+ * and behavior can be toggled on and off.
+ *
+ * For examples, head to the {@link https://neo4j.com/docs/nvl/current/react-wrappers/#_interactive_reactive_wrapperr Interactive React wrapper documentation page}.
+ */
+export declare const InteractiveNvlWrapper: React.MemoExoticComponent<React.ForwardRefExoticComponent<Omit<InteractiveNvlWrapperProps & HTMLProps<HTMLDivElement>, "ref"> & React.RefAttributes<NVL>>>;

package/lib/interactive-nvl-wrapper/InteractiveNvlWrapper.js

@@ -0,0 +1,46 @@
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+import { forwardRef, memo, useCallback, useRef, useState } from 'react';
+import { BasicNvlWrapper } from '../basic-wrapper/BasicNvlWrapper';
+import { INTERACTIVE_WRAPPER_ID } from '../utils/constants';
+import { InteractionHandlers } from './InteractionHandlers';
+const options = {
+    selectOnClick: false,
+    drawShadowOnHover: true,
+    selectOnRelease: false,
+    excludeNodeMargin: true
+};
+/**
+ * The interactive React wrapper component contains a collection of interaction handlers by default
+ * and provides a variety of common functionality and callbacks.
+ * It is an extension of the {@link BasicNvlWrapper} component and incorporates the
+ * @neo4j-nvl/interaction-handlers module's decorators to provide a set of interaction events.
+ *
+ * The mouseEventCallbacks property takes an object where various callbacks can be defined
+ * and behavior can be toggled on and off.
+ *
+ * For examples, head to the {@link https://neo4j.com/docs/nvl/current/react-wrappers/#_interactive_reactive_wrapperr Interactive React wrapper documentation page}.
+ */
+export const InteractiveNvlWrapper = memo(forwardRef(({ nodes, rels, layout, layoutOptions, onInitializationError, mouseEventCallbacks = {}, nvlCallbacks = {}, nvlOptions = {}, interactionOptions = options, ...nvlEvents }, nvlRef) => {
+    const newNvlRef = useRef(null);
+    const myNvlRef = nvlRef ?? newNvlRef;
+    const [isNvlInitialized, setIsNvlInitialized] = useState(false);
+    const handleInitialization = useCallback(() => {
+        setIsNvlInitialized(true);
+    }, []);
+    const handleInitializationError = useCallback((error) => {
+        setIsNvlInitialized(false);
+        if (onInitializationError) {
+            onInitializationError(error);
+        }
+    }, [onInitializationError]);
+    const setupInteractions = isNvlInitialized && myNvlRef.current !== null;
+    return (_jsxs(_Fragment, { children: [_jsx(BasicNvlWrapper, { ref: myNvlRef, nodes: nodes, id: INTERACTIVE_WRAPPER_ID, rels: rels, nvlOptions: nvlOptions, nvlCallbacks: {
+                    ...nvlCallbacks,
+                    onInitialization: () => {
+                        if (nvlCallbacks.onInitialization !== undefined) {
+                            nvlCallbacks.onInitialization();
+                        }
+                        handleInitialization();
+                    }
+                }, layout: layout, layoutOptions: layoutOptions, onInitializationError: handleInitializationError, ...nvlEvents }), setupInteractions && (_jsx(InteractionHandlers, { nvlRef: myNvlRef, mouseEventCallbacks: mouseEventCallbacks, interactionOptions: interactionOptions }))] }));
+}));

package/lib/interactive-nvl-wrapper/hooks.d.ts

@@ -0,0 +1,5 @@
+import type NVL from '@neo4j-nvl/base';
+import type { MutableRefObject } from 'react';
+import type { InteractionOptions, MouseEvent, MouseInteraction, MouseInteractionModule } from './types';
+export declare const destroyInteraction: (interactionRef: MutableRefObject<MouseInteraction | null>) => void;
+export declare const useInteraction: (Interaction: MouseInteractionModule, interactionRef: MutableRefObject<MouseInteraction | null>, callback: ((...args: unknown[]) => void) | boolean | undefined, eventName: MouseEvent, nvlRef: MutableRefObject<NVL | null>, interactionOptions: InteractionOptions) => void;

package/lib/interactive-nvl-wrapper/hooks.js

@@ -0,0 +1,29 @@
+import { isNil } from 'lodash';
+import { useEffect } from 'react';
+export const destroyInteraction = (interactionRef) => {
+    interactionRef.current?.destroy();
+    interactionRef.current = null;
+};
+export const useInteraction = (Interaction, interactionRef, callback, eventName, nvlRef, interactionOptions) => {
+    useEffect(() => {
+        const nvl = nvlRef.current;
+        // Make sure we are not mounting interaction handlers when there is NVL setup
+        if (isNil(nvl) || isNil(nvl.getContainer())) {
+            return;
+        }
+        if (callback === true || typeof callback === 'function') {
+            if (isNil(interactionRef.current)) {
+                interactionRef.current = new Interaction(nvl, interactionOptions);
+            }
+            if (typeof callback === 'function') {
+                interactionRef.current.updateCallback(eventName, callback);
+            }
+            else if (!isNil(interactionRef.current.callbackMap[eventName])) {
+                interactionRef.current.removeCallback(eventName);
+            }
+        }
+        else if (callback === false) {
+            destroyInteraction(interactionRef);
+        }
+    }, [Interaction, callback, eventName, interactionOptions, interactionRef, nvlRef]);
+};

package/lib/interactive-nvl-wrapper/types.d.ts

@@ -0,0 +1,28 @@
+import type { BoxSelectInteraction, BoxSelectInteractionCallbacks, BoxSelectInteractionOptions, ClickInteraction, ClickInteractionCallbacks, ClickInteractionOptions, DragNodeInteraction, DragNodeInteractionCallbacks, DrawInteraction, DrawInteractionCallbacks, DrawInteractionOptions, HoverInteraction, HoverInteractionCallbacks, HoverInteractionOptions, LassoInteraction, LassoInteractionCallbacks, LassoInteractionOptions, PanInteraction, PanInteractionCallbacks, PanInteractionOptions, ZoomInteraction, ZoomInteractionCallbacks } from '@neo4j-nvl/interaction-handlers';
+import type { BasicReactWrapperProps } from '../basic-wrapper/BasicNvlWrapper';
+export type MouseInteractionModule = typeof HoverInteraction | typeof ClickInteraction | typeof PanInteraction | typeof ZoomInteraction | typeof DragNodeInteraction | typeof DrawInteraction | typeof BoxSelectInteraction | typeof LassoInteraction;
+export type MouseInteraction = HoverInteraction | ClickInteraction | PanInteraction | ZoomInteraction | DragNodeInteraction | DrawInteraction | BoxSelectInteraction | LassoInteraction;
+/**
+ * Collection of mouse event callbacks that can be used with
+ * the {@link InteractiveNvlWrapper} component.
+ */
+export type MouseEventCallbacks = ClickInteractionCallbacks & DragNodeInteractionCallbacks & HoverInteractionCallbacks & PanInteractionCallbacks & ZoomInteractionCallbacks & BoxSelectInteractionCallbacks & DrawInteractionCallbacks & LassoInteractionCallbacks;
+/**
+ * Collection of interaction options that can be used with
+ * the {@link InteractiveNvlWrapper} component.
+ */
+export type InteractionOptions = ClickInteractionOptions & BoxSelectInteractionOptions & HoverInteractionOptions & PanInteractionOptions & LassoInteractionOptions & DrawInteractionOptions;
+/**
+ * The events that can be passed to the {@link MouseEventCallbacks} object
+ * to turn on/off certain events for the {@link InteractiveNvlWrapper} component.
+ */
+export type MouseEvent = keyof MouseEventCallbacks;
+/**
+ * The properties that can be passed to the {@link InteractiveNvlWrapper} component.
+ */
+export interface InteractiveNvlWrapperProps extends BasicReactWrapperProps {
+    /** {@link MouseEventCallbacks} containing functions for callbacks on certain actions */
+    mouseEventCallbacks?: MouseEventCallbacks;
+    /** {@link InteractionOptions} for the underlying interaction handlers */
+    interactionOptions?: InteractionOptions;
+}

package/lib/interactive-nvl-wrapper/types.js

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

package/lib/static-picture-wrapper/StaticPictureWrapper.d.ts

@@ -0,0 +1,22 @@
+import type { Node, NvlOptions, Relationship } from '@neo4j-nvl/base';
+/**
+ * The properties that can be passed to the StaticPictureWrapper component.
+ */
+export type StaticPictureWrapperProps = {
+    /** The nodes to be displayed in the graph. */
+    nodes: Node[];
+    /** The relationships to be displayed in the graph. */
+    rels: Relationship[];
+    /** Options to customize the NVL instance. */
+    nvlOptions?: NvlOptions;
+    /** The width of the static picture. */
+    width?: number;
+    /** The height of the static picture. */
+    height?: number;
+};
+/**
+ * A React component that creates a static picture of a graph using NVL.
+ * This component is useful for generating static visualizations of graphs without requiring user interaction.
+ * NVL is destroyed after capturing the image to free up resources.
+ */
+export declare const StaticPictureWrapper: ({ nodes, rels, nvlOptions, width, height }: StaticPictureWrapperProps) => import("react/jsx-runtime").JSX.Element | null;

package/lib/static-picture-wrapper/StaticPictureWrapper.js

@@ -0,0 +1,32 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import NVL from '@neo4j-nvl/base';
+import { useEffect, useState } from 'react';
+/**
+ * A React component that creates a static picture of a graph using NVL.
+ * This component is useful for generating static visualizations of graphs without requiring user interaction.
+ * NVL is destroyed after capturing the image to free up resources.
+ */
+export const StaticPictureWrapper = ({ nodes, rels, nvlOptions = {}, width = 500, height = 500 }) => {
+    const [imgSrc, setImgSrc] = useState();
+    useEffect(() => {
+        const div = document.createElement('div');
+        div.style.width = `${width / window.devicePixelRatio}px`;
+        div.style.height = `${height / window.devicePixelRatio}px`;
+        const myNvl = new NVL(div, nodes, rels, nvlOptions, {
+            onLayoutDone: () => {
+                myNvl.fit(myNvl.getNodes().map((n) => n.id));
+            },
+            onZoomTransitionDone: () => {
+                setImgSrc(myNvl.getImageDataUrl());
+                setTimeout(() => {
+                    myNvl.destroy();
+                });
+            }
+        });
+        return () => {
+            myNvl?.destroy();
+        };
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [nodes, rels, width, height]);
+    return imgSrc !== undefined ? _jsx("img", { src: imgSrc, width: width, height: height, alt: "Graph" }) : null;
+};

package/lib/utils/constants.d.ts

@@ -0,0 +1,2 @@
+export const BASIC_WRAPPER_ID: "NVL_basic-wrapper";
+export const INTERACTIVE_WRAPPER_ID: "NVL_interactive-wrapper";

package/lib/utils/constants.js

@@ -0,0 +1,2 @@
+export const BASIC_WRAPPER_ID = 'NVL_basic-wrapper';
+export const INTERACTIVE_WRAPPER_ID = 'NVL_interactive-wrapper';

package/lib/utils/graph-comparison.d.ts

@@ -0,0 +1,8 @@
+import type { Node, Relationship } from '@neo4j-nvl/base';
+declare const getMapDifferences: <T extends Node | Relationship>(prevGraphElements: T[], newGraphElements: T[]) => {
+    added: T[];
+    removed: T[];
+    updated: T[];
+};
+declare const getNodeAttributeDifferences: (prevNodes: Node[], newNodes: Node[]) => Node[];
+export { getNodeAttributeDifferences, getMapDifferences };

package/lib/utils/graph-comparison.js

@@ -0,0 +1,72 @@
+import { isEqual, isNil, keyBy, keys, sortBy, transform } from 'lodash';
+const getMapDifferences = (prevGraphElements, newGraphElements) => {
+    const prevMap = keyBy(prevGraphElements, 'id');
+    const currentMap = keyBy(newGraphElements, 'id');
+    const prevIds = sortBy(keys(prevMap));
+    const currentIds = sortBy(keys(currentMap));
+    const added = [];
+    const removed = [];
+    const updated = [];
+    let i = 0;
+    let j = 0;
+    while (i < prevIds.length && j < currentIds.length) {
+        const prevId = prevIds[i];
+        const currId = currentIds[j];
+        if (prevId === undefined || currId === undefined) {
+            continue;
+        }
+        if (prevId === currId) {
+            if (!isEqual(prevMap[prevId], currentMap[currId])) {
+                updated.push(currId);
+            }
+            i += 1;
+            j += 1;
+        }
+        else if (prevId < currId) {
+            removed.push(prevId);
+            i += 1;
+        }
+        else {
+            added.push(currId);
+            j += 1;
+        }
+    }
+    while (i < prevIds.length) {
+        const prevId = prevIds[i];
+        if (prevId === undefined) {
+            continue;
+        }
+        removed.push(prevId);
+        i += 1;
+    }
+    while (j < currentIds.length) {
+        const currId = currentIds[j];
+        if (currId === undefined) {
+            continue;
+        }
+        added.push(currId);
+        j += 1;
+    }
+    return {
+        added: added.map((id) => currentMap[id]).filter((n) => !isNil(n)),
+        removed: removed.map((id) => prevMap[id]).filter((n) => !isNil(n)),
+        updated: updated.map((id) => currentMap[id]).filter((n) => !isNil(n))
+    };
+};
+const getNodeAttributeDifferences = (prevNodes, newNodes) => {
+    const prevNodeMap = keyBy(prevNodes, 'id');
+    return newNodes
+        .map((nodeToUpdate) => {
+        const previousNode = prevNodeMap[nodeToUpdate.id];
+        if (previousNode === undefined) {
+            return null;
+        }
+        return transform(nodeToUpdate, (result, value, key) => {
+            if (key === 'id' || value !== previousNode[key]) {
+                Object.assign(result, { [key]: value });
+            }
+        });
+    })
+        .filter((n) => n !== null && Object.keys(n).length > 1);
+};
+export { getNodeAttributeDifferences, getMapDifferences };

package/lib/utils/hooks.d.ts

@@ -0,0 +1,2 @@
+import type { EffectCallback } from 'react';
+export declare const useDeepCompareEffect: (callback: EffectCallback, dependencies: unknown[]) => void;

package/lib/utils/hooks.js

@@ -0,0 +1,16 @@
+import { isEqual } from 'lodash';
+import { useEffect, useRef } from 'react';
+const deepCompareEquals = (a, b) => {
+    return isEqual(a, b);
+};
+const useDeepCompareMemoize = (value) => {
+    const ref = useRef();
+    if (!deepCompareEquals(value, ref.current)) {
+        ref.current = value;
+    }
+    return ref.current;
+};
+export const useDeepCompareEffect = (callback, dependencies) => {
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    useEffect(callback, dependencies.map(useDeepCompareMemoize));
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@neo4j-nvl/react",
-  "version": "1.0.0-0e1dd35b-alpha",
+  "version": "1.0.0-0f60498a",
   "main": "lib/index.js",
   "homepage": "https://neo4j.com/docs/nvl/current/",
   "license": "SEE LICENSE IN 'LICENSE.txt'",
@@ -27,22 +27,22 @@
     "lib"
   ],
   "devDependencies": {
-    "@testing-library/dom": "^10.4.0",
-    "@testing-library/jest-dom": "^5.16.5",
-    "@testing-library/react": "^16.3.0",
-    "@types/lodash": "4.14.202",
-    "@types/react": "^18.2.58",
-    "react": "^19.1.1",
-    "react-dom": "^19.1.1"
+    "@testing-library/dom": "10.4.1",
+    "@testing-library/jest-dom": "5.17.0",
+    "@testing-library/react": "16.3.0",
+    "@types/lodash": "4.17.21",
+    "@types/react": "18.3.27",
+    "react": "19.2.1",
+    "react-dom": "19.2.1"
   },
   "dependencies": {
-    "@neo4j-nvl/base": "1.0.0-0e1dd35b-alpha",
-    "@neo4j-nvl/interaction-handlers": "1.0.0-0e1dd35b-alpha",
-    "lodash": "4.17.21"
+    "@neo4j-nvl/base": "1.0.0-0f60498a",
+    "@neo4j-nvl/interaction-handlers": "1.0.0-0f60498a",
+    "lodash": "4.17.23"
   },
   "peerDependencies": {
-    "react": "^18.0.0 || ^19.0.0",
-    "react-dom": "^18.0.0 || ^19.0.0"
+    "react": "18.0.0 || ^19.0.0",
+    "react-dom": "18.0.0 || ^19.0.0"
   },
   "stableVersion": "1.0.0"
 }