@neo4j-nvl/react 0.3.9-dc45154c → 1.0.0-e90ba568

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,13 +22,10 @@ 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);
@@ -104,18 +100,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 +118,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/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-dc45154c",
+  "version": "1.0.0-e90ba568",
   "main": "lib/index.js",
   "homepage": "https://neo4j.com/docs/nvl/current/",
   "license": "SEE LICENSE IN 'LICENSE.txt'",
@@ -36,13 +36,13 @@
     "react-dom": "^19.1.1"
   },
   "dependencies": {
-    "@neo4j-nvl/base": "0.3.9-dc45154c",
-    "@neo4j-nvl/interaction-handlers": "0.3.9-dc45154c",
+    "@neo4j-nvl/base": "1.0.0-e90ba568",
+    "@neo4j-nvl/interaction-handlers": "1.0.0-e90ba568",
     "lodash": "4.17.21"
   },
   "peerDependencies": {
     "react": "^18.0.0 || ^19.0.0",
     "react-dom": "^18.0.0 || ^19.0.0"
   },
-  "stableVersion": "0.3.9"
+  "stableVersion": "1.0.0"
 }