@neo4j-nvl/react 2.0.0-ec6fdba7 → 2.1.0

package/CHANGELOG.md

@@ -2,7 +2,7 @@
 
 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/).
 
-## [Unreleased]
+## [2.1.0] - 2026-11-10
 
 This release adds keyboard actions for moving nodes, ships an agent skill for NVL, and makes all packages loadable as ESM in Node.js without a bundler.
 
@@ -24,6 +24,7 @@ This release adds keyboard actions for moving nodes, ships an agent skill for NV
 * `fit()` zooms out beyond `minZoom` when `allowDynamicMinZoom` is `true` and the graph does not fit the viewport.
 * `onHover` callback's `element` parameter is now typed as possibly `undefined`, matching the runtime behaviour.
 * Added missing caret for the React 18 peer dependency range in `@neo4j-nvl/react`.
+* Several dependency updates
 
 ## [2.0.0] - 2026-09-15
 

package/README.md

@@ -78,6 +78,14 @@ const [boxSelect, setBoxSelect] = useState(false)
 
 You can also find more instructions and examples on how to use the NVL React wrappers in the [docs](https://neo4j.com/docs/nvl/current/react-wrappers/).
 
+### Agent skills
+
+The agent skill for NVL (`neo4j-nvl-skill`) ships with `@neo4j-nvl/base`, which this package depends on. To make it available to your AI coding assistant, run the following with a recent version of the `skills` CLI:
+
+```bash
+npx skills experimental_sync
+```
+
 ### Product analytics
 
 In order to improve the library we are collecting some information about the usage of NVL. If you prefer to disable this behavior setting `disableTelemetry` to `true` in the `nvlOptions` property.

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

@@ -8,11 +8,25 @@ export interface BasicReactWrapperProps {
   nodes: Node[];
   /** The rels of the graph of type Relationship[] */
   rels: Relationship[];
-  /** an Object containing functions for callbacks on certain actions */
+  /**
+   * An object containing functions for callbacks on certain actions.
+   * @remarks Passed to the NVL constructor once; later changes to this prop are ignored.
+   * Read changing state through a ref inside the callbacks instead of redefining them.
+   */
   nvlCallbacks?: ExternalCallbacks;
-  /** An object containing options for the Nvl instance */
+  /**
+   * An object containing options for the Nvl instance.
+   * @remarks
+   * If `minimapContainer` is present it must be a non-null element before NVL is created, otherwise
+   * creation is deferred until it is.
+   */
   nvlOptions?: NvlOptions;
-  /** Sets the positions of the nodes in the graph using the setNodePositions method. */
+  /**
+   * Sets the positions of the nodes in the graph using the setNodePositions method.
+   * @remarks Applied whenever the array reference changes and is non-empty. This is the way to
+   * position nodes.
+   * Do not set `x` and `y` on `nodes` directly.
+   */
   positions?: Node[];
   /**
    * Sets the zoom level of the viewport using the setZoom method.
@@ -36,8 +50,21 @@ export interface BasicReactWrapperProps {
  *
  * 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.
+ *
+ * The `ref` exposes every NVL method. Calls made before the instance exists return `null`.
  *
  * For examples, head to the {@link https://neo4j.com/docs/nvl/current/react-wrappers/#_basic_react_wrapper Basic React wrapper documentation page}.
+ * @example
+ * ```tsx
+ * const Graph = () => {
+ *   const nvlRef = useRef<NVL>(null)
+ *   return (
+ *     <>
+ *       <BasicNvlWrapper ref={nvlRef} nodes={nodes} rels={relationships} />
+ *       <button onClick={() => nvlRef.current?.fit(nodes.map((node) => node.id))}>Fit</button>
+ *     </>
+ *   )
+ * }
+ * ```
  */
 export declare const BasicNvlWrapper: import("react").MemoExoticComponent<import("react").ForwardRefExoticComponent<Omit<BasicReactWrapperProps & HTMLProps<HTMLDivElement>, "ref"> & import("react").RefAttributes<Partial<Pick<NVL, "restart" | "addAndUpdateElementsInGraph" | "getSelectedNodes" | "getSelectedRelationships" | "removeNodesWithIds" | "removeRelationshipsWithIds" | "getNodes" | "getRelationships" | "getNodeById" | "getRelationshipById" | "getPositionById" | "getCurrentOptions" | "destroy" | "deselectAll" | "fit" | "resetZoom" | "setRenderer" | "setDisableWebGL" | "pinNode" | "unPinNode" | "setLayout" | "setLayoutOptions" | "getNodesOnScreen" | "getNodePositions" | "setNodePositions" | "isLayoutMoving" | "saveToFile" | "saveToSvg" | "getImageDataUrl" | "getSvgDataUrl" | "saveFullGraphToLargeFile" | "getZoomLimits" | "setZoom" | "getScale" | "getPan" | "getHits" | "getContainer">>>>>;

package/lib/basic-wrapper/BasicNvlWrapper.js

@@ -9,9 +9,22 @@ import { jsx } from "react/jsx-runtime";
 *
 * 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.
+*
+* The `ref` exposes every NVL method. Calls made before the instance exists return `null`.
 *
 * For examples, head to the {@link https://neo4j.com/docs/nvl/current/react-wrappers/#_basic_react_wrapper Basic React wrapper documentation page}.
+* @example
+* ```tsx
+* const Graph = () => {
+*   const nvlRef = useRef<NVL>(null)
+*   return (
+*     <>
+*       <BasicNvlWrapper ref={nvlRef} nodes={nodes} rels={relationships} />
+*       <button onClick={() => nvlRef.current?.fit(nodes.map((node) => node.id))}>Fit</button>
+*     </>
+*   )
+* }
+* ```
 */
 const BasicNvlWrapper = memo(forwardRef(({ nodes, rels, nvlCallbacks = {}, nvlOptions = {}, positions = [], zoom, pan, onInitializationError, ...nvlEvents }, ref) => {
 	const nvlRef = useRef(null);

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

@@ -9,6 +9,7 @@ import { HTMLProps } from "react";
  *
  * The mouseEventCallbacks property takes an object where various callbacks can be defined
  * and behavior can be toggled on and off.
+ * See {@link MouseEventCallbacks} for which key enables which handler.
  *
  * For examples, head to the {@link https://neo4j.com/docs/nvl/current/react-wrappers/#_interactive_react_wrapper Interactive React wrapper documentation page}.
  */

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

@@ -18,6 +18,7 @@ const options = {
 *
 * The mouseEventCallbacks property takes an object where various callbacks can be defined
 * and behavior can be toggled on and off.
+* See {@link MouseEventCallbacks} for which key enables which handler.
 *
 * For examples, head to the {@link https://neo4j.com/docs/nvl/current/react-wrappers/#_interactive_react_wrapper Interactive React wrapper documentation page}.
 */

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

@@ -5,6 +5,13 @@ export type Interaction = HoverInteraction | ClickInteraction | PanInteraction |
 /**
  * Collection of mouse event callbacks that can be used with
  * the {@link InteractiveNvlWrapper} component.
+ *
+ * Each key enables the interaction handler that owns it: a function enables the handler and is
+ * called.
+ * `true` enables it without a callback and `false` destroys the handler (and all its other callbacks).
+ *
+ * @remarks Zoom is only enabled through `onZoomAndPan`. There is no `onZoom` key.
+ * Keyboard callbacks use the separate {@link KeyboardEventCallbacks} prop.
  */
 export type MouseEventCallbacks = ClickInteractionCallbacks & DragNodeInteractionCallbacks & HoverInteractionCallbacks & PanInteractionCallbacks & ZoomInteractionCallbacks & BoxSelectInteractionCallbacks & DrawInteractionCallbacks & LassoInteractionCallbacks;
 /**
@@ -22,6 +29,10 @@ export type InteractionOptions = ClickInteractionOptions & BoxSelectInteractionO
  * to turn on/off certain events for the {@link InteractiveNvlWrapper} component.
  */
 export type MouseEvent = keyof MouseEventCallbacks;
+/**
+ * The events that can be passed to the {@link KeyboardEventCallbacks} object
+ * to turn on/off certain events for the {@link InteractiveNvlWrapper} component.
+ */
 export type KeyboardEvent = keyof KeyboardEventCallbacks;
 /**
  * The properties that can be passed to the {@link InteractiveNvlWrapper} component.
@@ -31,6 +42,10 @@ export interface InteractiveNvlWrapperProps extends BasicReactWrapperProps {
   mouseEventCallbacks?: MouseEventCallbacks;
   /** {@link KeyboardEventCallbacks} containing functions for callbacks on keyboard actions */
   keyboardEventCallbacks?: KeyboardEventCallbacks;
-  /** {@link InteractionOptions} for the underlying interaction handlers */
+  /**
+   * {@link InteractionOptions} for the underlying interaction handlers.
+   * @remarks Options are read when a handler is
+   * first created and changing them later does not affect existing handlers.
+   */
   interactionOptions?: InteractionOptions;
 }

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

@@ -23,6 +23,12 @@ export type StaticPictureWrapperProps = {
  * The component automatically fits all nodes in the viewport before capturing the image
  * NVL is automatically destroyed after capturing the image to free up resources.
  *
+ * @remarks
+ * When showing many pictures at once, either set `disableWebGL: true` in `nvlOptions` or mount the components in
+ * batches to avoid exceeding the WebGL context limit of the browser.
+ * Otherwise, the browser may drop the oldest contexts and warn "Too many active WebGL contexts" when reaching its limit
+ * and some pictures can fail to render.
+ *
  * @param props - The component properties
  * @returns An img element displaying the graph visualization, or null during rendering
  *

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

@@ -8,6 +8,12 @@ import { jsx } from "react/jsx-runtime";
 * The component automatically fits all nodes in the viewport before capturing the image
 * NVL is automatically destroyed after capturing the image to free up resources.
 *
+* @remarks
+* When showing many pictures at once, either set `disableWebGL: true` in `nvlOptions` or mount the components in
+* batches to avoid exceeding the WebGL context limit of the browser.
+* Otherwise, the browser may drop the oldest contexts and warn "Too many active WebGL contexts" when reaching its limit
+* and some pictures can fail to render.
+*
 * @param props - The component properties
 * @returns An img element displaying the graph visualization, or null during rendering
 *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@neo4j-nvl/react",
-  "version": "2.0.0-ec6fdba7",
+  "version": "2.1.0",
   "type": "module",
   "main": "lib/index.js",
   "types": "lib/index.d.ts",
@@ -50,13 +50,12 @@
     "tsdown": "0.23.1"
   },
   "dependencies": {
-    "@neo4j-nvl/base": "2.0.0-ec6fdba7",
-    "@neo4j-nvl/interaction-handlers": "2.0.0-ec6fdba7",
+    "@neo4j-nvl/base": "2.1.0",
+    "@neo4j-nvl/interaction-handlers": "2.1.0",
     "lodash-es": "4.18.1"
   },
   "peerDependencies": {
     "react": "^18.0.0 || ^19.0.0",
     "react-dom": "^18.0.0 || ^19.0.0"
-  },
-  "stableVersion": "2.0.0"
+  }
 }