@neo4j-nvl/react 0.2.61-80e72072 → 0.2.61-9ad61b94

package/README.md

@@ -1 +1,85 @@
-This module exports a collection of React components that are build around the NVL class. They act as wrappers around the NVL class that provide a React interface to the NVL class.
+# Neo4j Visualization Library
+
+Welcome to NVL (Neo4j Visualization Library). NVL is a collection of libraries that can be used to build custom graph visualizations like [Neo4j Bloom](https://neo4j.com/product/bloom/). If you want to use NVL with a different framework than React or what to build your own React wrappers, you can do so by using the NVL core library.
+
+## Consuming the library
+
+### Installing the library
+
+You can install the NVL React wrappers with your preferred package manager, for example
+
+```bash
+npm install @neo4j-nvl/react
+```
+
+### Using the library
+
+This is an example on how to use the BasicReactWrapper component: 
+
+```tsx
+<BasicNvlWrapper
+ nodes={nodes}
+ rels={relationships}
+ nvlOptions={options}
+ nvlCallbacks={callbacks}
+/>
+```
+
+When nodes and/or relationships are updated in the React wrapper, the NVL instance will be updated accordingly:
+
+```tsx
+const [nodes, setNodes] = useState<Node[]>([{ id: '0' }, { id: '1' }])
+
+const addElements = () => {
+  const newNodes = [...nodes, { id: nodes.length }]
+  setNodes(newNodes)
+}
+
+<div>
+  <BasicNvlWrapper nodes={nodes} />
+  <button onClick={addElements}>Add Graph Elements</button>
+</div>
+```
+
+If you want to access the NVL class outside of the React wrapper you can use a reference of NVL to call its methods:
+
+```tsx
+const nvlRef = useRef<NVL>()
+
+<div>
+  <BasicNvlWrapper
+    nodes={[{ id: '0' }, { id: '1' }]}
+    rels={[{ from: '0', to: '1', id: '10' }]}
+    ref={nvlRef}
+  />
+  <button onClick={() => nvlRef.current?.zoomToNodes([0, 1])}>Zoom to Nodes</button>
+</div>
+```
+
+To easily add common graph interaction, you can make use of the interaction handlers module and the InteractiveNvlWrapper.
+
+The InteractiveNvlWrapper is a wrapper component that provides a basic set of interactions for the NVL. It is an extension of the BasicNvlWrapper component and incorporates the interaction handlers to provide a set of interaction events.
+
+Events can be turned on and off by passing a callback function or a boolean value to the
+`mouseEventCallbacks` prop. The callback function will be called with the event's arguments when the event is triggered. If a boolean value is passed, the event will be turned on or off accordingly.
+
+```tsx
+const [multiSelect, setMultiSelect] = useState(false)
+<>
+  <button onClick={() => setMultiSelect(!multiSelect)}>
+    {multiSelect ? 'Disable' : 'Enable'} multi-select
+  </button>
+  <InteractiveNvlWrapper
+    nodes={nodes}
+    rels={relationships}
+    mouseEventCallbacks={{
+      onHover: (element) => console.log(element),
+      onNodeClick: (node) => console.log(node),
+      onMultiSelect: multiSelect
+   }}
+  />
+</>
+```
+
+
+You can also find more instructions and examples on how to use NVL in the docs.

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

@@ -107,7 +107,7 @@ export interface BasicReactWrapperProps {
  * ```
  *
  * For more about interactivity, check out the {@link NVL}.hittest method,
- * the Interaction Handlers module module and the {@link InteractiveNvlWrapper}.
+ * the Interaction Handlers module and the {@link InteractiveNvlWrapper}.
  */
 export declare const BasicNvlWrapper: import("react").MemoExoticComponent<import("react").ForwardRefExoticComponent<Omit<BasicReactWrapperProps & HTMLProps<HTMLDivElement>, "ref"> & import("react").RefAttributes<IncludeMethods<NVL>>>>;
 export {};

package/lib/basic-wrapper/BasicNvlWrapper.js

@@ -85,7 +85,7 @@ import { useDeepCompareEffect } from '../utils/hooks';
  * ```
  *
  * For more about interactivity, check out the {@link NVL}.hittest method,
- * the Interaction Handlers module module and the {@link InteractiveNvlWrapper}.
+ * the Interaction Handlers module and the {@link InteractiveNvlWrapper}.
  */
 export const BasicNvlWrapper = memo(forwardRef(({ nodes, rels, layout, layoutOptions, nvlCallbacks = {}, nvlOptions = {}, onInitializationError, ...nvlEvents }, ref) => {
     const nvlRef = useRef(null);

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

@@ -2,7 +2,15 @@ import type { BoxSelectInteraction, BoxSelectInteractionCallbacks, BoxSelectInte
 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@neo4j-nvl/react",
-  "version": "0.2.61-80e72072",
+  "version": "0.2.61-9ad61b94",
   "main": "lib/index.js",
   "license": "SEE LICENSE IN 'LICENSE.txt'",
   "scripts": {
@@ -29,8 +29,8 @@
     "typescript": "^5.4.5"
   },
   "dependencies": {
-    "@neo4j-nvl/core": "^0.2.63-80e72072",
-    "@neo4j-nvl/interaction-handlers": "^0.2.64-80e72072",
+    "@neo4j-nvl/core": "^0.2.63-9ad61b94",
+    "@neo4j-nvl/interaction-handlers": "^0.2.64-9ad61b94",
     "lodash": "4.17.21",
     "react": "^18.2.0",
     "react-dom": "^18.2.0"