@neo4j-nvl/react 0.3.9 → 1.0.0-e02e0956

package/CHANGELOG.md

@@ -2,6 +2,26 @@
 
 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.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).
+
+### Added
+* support for React 19 in Nvl React wrappers.
+* new prop to the React components to provde zoom and pan values.
+* extend return object of `.getZoomTargetForNodePositions` function to include pan values.
+
+### Changed
+* updated example application UI.
+
+### Fixed
+* display remaining captions when one of the values in the caption array is null or undefined.
+* ensure the computing state for the d3 layout is set correctly.
+* correctly process Right-to-Left (RTL) text for node captions.
+
+### Removed
+* `useWebGL` / `setUseWebGLRenderer`, please use [renderer](https://neo4j.com/docs/api/nvl/current/interfaces/_neo4j_nvl_base.NvlOptions.html#renderer) & [setRenderer](https://neo4j.com/docs/api/nvl/current/classes/_neo4j_nvl_base.NVL.html#setRenderer) instead going forward.
+* `NvlOption.nodeDefaultBorderColor`, `NvlOption.selectedBorderColor`, `NvlOption.disabledItemColor`, `NvlOption.disabledItemFontColor`, please use properties with the same name in [NvlOptions.styling](https://neo4j.com/docs/api/nvl/current/interfaces/_neo4j_nvl_base.NvlOptions.html#styling) object going forward.
+
 ## [0.3.9] - 2025-07-23
 
 The 0.3.9 release contains several fixes for NVL's interaction handler and adds a new method to NVL to directly extract image data from an NVL instance:

package/lib/__tests__/BasicNvlWrapper.test.js

@@ -36,4 +36,34 @@ describe('BasicNvlWrapper', () => {
         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.js

@@ -2,12 +2,13 @@ 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 { act, render } from '@testing-library/react';
-import React, { createRef } from 'react';
+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();
 PanInteraction.prototype.callbackMap = new Map();
@@ -17,10 +18,7 @@ let destroyPanInteraction;
 describe('InteractiveNvlWrapper', () => {
     beforeEach(() => {
         jest.spyOn(NVL.prototype, 'getContainer').mockImplementation(() => document.createElement('div'));
-        // eslint-disable-next-line @typescript-eslint/ban-ts-comment
-        // @ts-expect-error
-        // eslint-disable-next-line @typescript-eslint/no-unsafe-call
-        NVL.mockImplementation((_container, _nodes, _rels, _options, callbacks) => {
+        MockedNVL.mockImplementation((_container, _nodes, _rels, _options, callbacks) => {
             mockOnInitialization = callbacks.onInitialization;
             return {
                 getContainer: () => document.createElement('div'),
@@ -42,7 +40,7 @@ describe('InteractiveNvlWrapper', () => {
     });
     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: expect.any(Function) });
+        expect(NVL).toHaveBeenCalledWith(expect.any(HTMLDivElement), [], [], {}, { onInitialization: mockOnInitialization });
     });
     test('initialises NVL expectedly with a graph object and properties', () => {
         const mockLayoutDoneFunction = jest.fn();
@@ -52,7 +50,7 @@ describe('InteractiveNvlWrapper', () => {
         });
         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: expect.any(Function)
+            onInitialization: mockOnInitialization
         });
     });
     test('initialises expected interaction handlers with correct options', () => {
@@ -132,4 +130,24 @@ describe('InteractiveNvlWrapper', () => {
         });
         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/basic-wrapper/BasicNvlWrapper.d.ts

@@ -1,12 +1,6 @@
 import type { ExternalCallbacks, Layout, LayoutOptions, Node, NvlOptions, Relationship } from '@neo4j-nvl/base';
 import NVL from '@neo4j-nvl/base';
 import { type HTMLProps } from 'react';
-/**
- * @hidden
- */
-type IncludeMethods<T> = Pick<T, {
-    [K in keyof T]: T[K] extends (_: unknown) => unknown ? K : never;
-}[keyof T]>;
 /**
  * The properties that can be passed to the {@link BasicNvlWrapper} component.
  */
@@ -23,18 +17,32 @@ export interface BasicReactWrapperProps {
     nvlCallbacks?: ExternalCallbacks;
     /** An object containing options for the Nvl instance */
     nvlOptions?: NvlOptions;
-    /** Sets the positions of the nodes in the graph using the {@link NVL.setNodePositions} method. */
+    /** 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 base {@link NVL} library within a React component.
+ * 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<IncludeMethods<NVL>>>>;
-export {};
+export declare const BasicNvlWrapper: import("react").MemoExoticComponent<import("react").ForwardRefExoticComponent<Omit<BasicReactWrapperProps & HTMLProps<HTMLDivElement>, "ref"> & import("react").RefAttributes<Partial<Pick<NVL, "performance" | "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" | "getImageDataUrl" | "saveFullGraphToLargeFile" | "setZoom" | "getScale" | "getPan" | "getHits" | "getContainer">>>>>;

package/lib/basic-wrapper/BasicNvlWrapper.js

@@ -6,16 +6,15 @@ import { getMapDifferences, getNodeAttributeDifferences } from '../utils/graph-c
 import { useDeepCompareEffect } from '../utils/hooks';
 /**
  *
- * A basic React wrapper that wraps the base {@link NVL} library within a React component.
+ * 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 = [], onInitializationError, ...nvlEvents }, ref) => {
+export const BasicNvlWrapper = memo(forwardRef(({ nodes, rels, layout, layoutOptions, nvlCallbacks = {}, nvlOptions = {}, positions = [], zoom, pan, onInitializationError, ...nvlEvents }, ref) => {
     const nvlRef = useRef(null);
     useImperativeHandle(ref, () => {
-        // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
         const nvlMethods = Object.getOwnPropertyNames(NVL.prototype);
         return nvlMethods.reduce((current, method) => ({
             ...current,
@@ -23,20 +22,26 @@ export const BasicNvlWrapper = memo(forwardRef(({ nodes, rels, layout, layoutOpt
                 if (nvlRef.current === null) {
                     return null;
                 }
-                // @ts-ignore suppress the type casting error on spreading
+                // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
                 return nvlRef.current[method](...args);
             }
-        }), 
-        // eslint-disable-next-line max-len
-        // eslint-disable-next-line @typescript-eslint/prefer-reduce-type-parameter, @typescript-eslint/consistent-type-assertions
-        {});
+        }), {});
     });
     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;
-        if (containerRef.current !== 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) {
@@ -58,12 +63,8 @@ export const BasicNvlWrapper = memo(forwardRef(({ nodes, rels, layout, layoutOpt
                 }
             }
         }
-        return () => {
-            newNvl?.destroy();
-            nvlRef.current = null;
-        };
         // eslint-disable-next-line react-hooks/exhaustive-deps
-    }, []);
+    }, [containerRef.current, nvlOptions.minimapContainer]);
     useEffect(() => {
         if (nvlRef.current === null) {
             return;
@@ -104,18 +105,12 @@ export const BasicNvlWrapper = memo(forwardRef(({ nodes, rels, layout, layoutOpt
         }
         nvlRef.current.setLayoutOptions(updatedLayoutOptions);
     }, [layoutOptions, nvlOptions.layoutOptions]);
-    useEffect(() => {
-        if (nvlRef.current === null || nvlOptions.useWebGL === undefined) {
-            return;
-        }
-        nvlRef.current.setUseWebGLRenderer(nvlOptions.useWebGL);
-    }, [nvlOptions.useWebGL]);
     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;
@@ -128,5 +123,19 @@ export const BasicNvlWrapper = memo(forwardRef(({ nodes, rels, layout, layoutOpt
         }
         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

@@ -2,5 +2,7 @@ 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';
-export { BasicNvlWrapper, InteractiveNvlWrapper };
-export type { MouseEventCallbacks, MouseEvent, BasicReactWrapperProps, InteractionOptions, InteractiveNvlWrapperProps };
+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

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

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/hooks.js

@@ -1,15 +1,15 @@
 import { isEqual } from 'lodash';
 import { useEffect, useRef } from 'react';
-function deepCompareEquals(a, b) {
+const deepCompareEquals = (a, b) => {
     return isEqual(a, b);
-}
-function useDeepCompareMemoize(value) {
+};
+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": "0.3.9",
+  "version": "1.0.0-e02e0956",
   "main": "lib/index.js",
   "homepage": "https://neo4j.com/docs/nvl/current/",
   "license": "SEE LICENSE IN 'LICENSE.txt'",
@@ -27,17 +27,22 @@
     "lib"
   ],
   "devDependencies": {
+    "@testing-library/dom": "^10.4.0",
     "@testing-library/jest-dom": "^5.16.5",
-    "@testing-library/react": "^13.4.0",
+    "@testing-library/react": "^16.3.0",
     "@types/lodash": "4.14.202",
     "@types/react": "^18.2.58",
-    "babel-eslint": "^10.1.0"
+    "react": "^19.1.1",
+    "react-dom": "^19.1.1"
   },
   "dependencies": {
-    "@neo4j-nvl/base": "0.3.9",
-    "@neo4j-nvl/interaction-handlers": "0.3.9",
-    "lodash": "4.17.21",
-    "react": "^18.2.0",
-    "react-dom": "^18.2.0"
-  }
+    "@neo4j-nvl/base": "1.0.0-e02e0956",
+    "@neo4j-nvl/interaction-handlers": "1.0.0-e02e0956",
+    "lodash": "4.17.21"
+  },
+  "peerDependencies": {
+    "react": "^18.0.0 || ^19.0.0",
+    "react-dom": "^18.0.0 || ^19.0.0"
+  },
+  "stableVersion": "1.0.0"
 }