@neo4j-nvl/react 0.1.0

package/README.md

@@ -0,0 +1,3 @@
+### react
+
+A React wrapper that provides the NVL class as a React component.

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

@@ -0,0 +1,71 @@
+import { NamedExoticComponent } from 'react';
+import { NvlOptions, Node, Relationship, ExternalCallbacks, LayoutOptions, Layout } from '@neo4j-nvl/core';
+/**
+ * A basic React wrapper for the NVL class.
+ *
+ * @example
+ * This is the most basic way of using the wrapper. It will create a new NVL instance with the given nodes and relationships.
+ * ```tsx
+ * <BasicNvlWrapper
+ *   nodes={[{ id: 0 }, { id: 1 }, { id: 2 }]}
+ *   rels={[{ from: 0, to: 1, id: 10 }, { from: 0, to: 2, id: 11 }]}
+ * />
+ * ```
+ *
+ * @example
+ * This is a more advanced example, where the nodes and relationships are updated dynamically.
+ * ```tsx
+ * const [nodes, setNodes] = useState<Node[]>([{ id: 0 }, { id: 1 }, { id: 2 }])
+ * const [rels, setRels] = useState<Relationship[]>([{ from: 0, to: 1, id: 10 }, { from: 0, to: 2, id: 11 }])
+ *
+ * const addNode = () => {
+ *   const newNodes = [...nodes, { id: nodes.length }]
+ *   setNodes(newNodes)
+ * }
+ *
+ * const addRel = () => {
+ *   const newRels = [...rels, { from: 0, to: nodes.length - 1, id: rels.length }]
+ *   setRels(newRels)
+ * }
+ *
+ * <div>
+ *   <BasicNvlWrapper
+ *     nodes={nodes}
+ *     rels={rels}
+ *   />
+ *   <button onClick={addNode}>Add Node</button>
+ *   <button onClick={addRel}>Add Relationship</button>
+ * </div>
+ * ```
+ *
+ * @example
+ * This is an example of how to use a reference of NVL to call
+ * NVL methods from inside the React wrapper.
+ * ```tsx
+ * const nvlRef = useRef()
+ *
+ * <div>
+ *   <BasicNvlWrapper
+ *     nodes={[{ id: 0 }, { id: 1 }, { id: 2 }]}
+ *     rels={[{ from: 0, to: 1, id: 10 }, { from: 0, to: 2, id: 11 }]}
+ *     ref={nvlRef}
+ *   />
+ *   <button onClick={() => nvlRef.current?.zoomToNodes([0, 1])}>Zoom to Nodes</button>
+ * </div>
+ * ```
+ */
+declare const BasicNvlWrapper: NamedExoticComponent<{
+    /** 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;
+}>;
+export { BasicNvlWrapper };

package/lib/basic-wrapper/BasicNvlWrapper.js

@@ -0,0 +1,109 @@
+import React, { useEffect, useState, useRef, forwardRef, useImperativeHandle, memo } from 'react';
+import NVL from '@neo4j-nvl/core';
+import { getMapDifferences, getNodeAttributeDifferences } from '../utils/graphComparison';
+import { useDeepCompareEffect } from '../utils/hooks';
+/**
+ * A basic React wrapper for the NVL class.
+ *
+ * @example
+ * This is the most basic way of using the wrapper. It will create a new NVL instance with the given nodes and relationships.
+ * ```tsx
+ * <BasicNvlWrapper
+ *   nodes={[{ id: 0 }, { id: 1 }, { id: 2 }]}
+ *   rels={[{ from: 0, to: 1, id: 10 }, { from: 0, to: 2, id: 11 }]}
+ * />
+ * ```
+ *
+ * @example
+ * This is a more advanced example, where the nodes and relationships are updated dynamically.
+ * ```tsx
+ * const [nodes, setNodes] = useState<Node[]>([{ id: 0 }, { id: 1 }, { id: 2 }])
+ * const [rels, setRels] = useState<Relationship[]>([{ from: 0, to: 1, id: 10 }, { from: 0, to: 2, id: 11 }])
+ *
+ * const addNode = () => {
+ *   const newNodes = [...nodes, { id: nodes.length }]
+ *   setNodes(newNodes)
+ * }
+ *
+ * const addRel = () => {
+ *   const newRels = [...rels, { from: 0, to: nodes.length - 1, id: rels.length }]
+ *   setRels(newRels)
+ * }
+ *
+ * <div>
+ *   <BasicNvlWrapper
+ *     nodes={nodes}
+ *     rels={rels}
+ *   />
+ *   <button onClick={addNode}>Add Node</button>
+ *   <button onClick={addRel}>Add Relationship</button>
+ * </div>
+ * ```
+ *
+ * @example
+ * This is an example of how to use a reference of NVL to call
+ * NVL methods from inside the React wrapper.
+ * ```tsx
+ * const nvlRef = useRef()
+ *
+ * <div>
+ *   <BasicNvlWrapper
+ *     nodes={[{ id: 0 }, { id: 1 }, { id: 2 }]}
+ *     rels={[{ from: 0, to: 1, id: 10 }, { from: 0, to: 2, id: 11 }]}
+ *     ref={nvlRef}
+ *   />
+ *   <button onClick={() => nvlRef.current?.zoomToNodes([0, 1])}>Zoom to Nodes</button>
+ * </div>
+ * ```
+ */
+const BasicNvlWrapper = memo(forwardRef(({ nodes, rels, layout, layoutOptions, nvlCallbacks = {}, nvlOptions }, ref) => {
+    useImperativeHandle(ref, () => {
+        const nvlMethods = Object.getOwnPropertyNames(NVL.prototype);
+        return nvlMethods.reduce((current, method) => (Object.assign(Object.assign({}, current), { [method]: (...args) => nvl && nvl[method](...args) })), {});
+    });
+    const containerRef = useRef();
+    const [nvl, setNvl] = useState();
+    const [currentNodes, setCurrentNodes] = useState(nodes);
+    const [currentRels, setCurrentRels] = useState(rels);
+    useEffect(() => {
+        if (!nvl) {
+            const combinedOptions = Object.assign(Object.assign({}, nvlOptions), { layoutOptions });
+            if (layout) {
+                combinedOptions.layout = layout;
+            }
+            const newNvl = new NVL(containerRef.current, currentNodes, currentRels, combinedOptions, nvlCallbacks);
+            setNvl(newNvl);
+            setCurrentRels(rels);
+            setCurrentNodes(nodes);
+            return () => {
+                newNvl.destroy();
+            };
+        }
+    }, []);
+    useEffect(() => {
+        if (!nvl)
+            return;
+        const nodeChanges = getMapDifferences(currentNodes, nodes);
+        const nodeDiff = getNodeAttributeDifferences(currentNodes, nodes);
+        const relChanges = getMapDifferences(currentRels, rels);
+        setCurrentRels(rels);
+        setCurrentNodes(nodes);
+        nvl.updateGraph([...nodeChanges.added, ...nodeDiff], [...relChanges.added, ...relChanges.updated]);
+        nvl.removeRelationshipsWithIds(relChanges.removed.map((r) => r.id));
+        nvl.removeNodesWithIds(nodeChanges.removed.map((n) => n.id));
+    }, [nodes, rels]);
+    useEffect(() => {
+        nvl === null || nvl === void 0 ? void 0 : nvl.setLayout(layout);
+    }, [layout]);
+    useDeepCompareEffect(() => {
+        nvl === null || nvl === void 0 ? void 0 : nvl.setLayoutOptions(layoutOptions);
+    }, [layoutOptions]);
+    useEffect(() => {
+        nvl === null || nvl === void 0 ? void 0 : nvl.setUseWebGLRenderer(nvlOptions === null || nvlOptions === void 0 ? void 0 : nvlOptions.useWebGL);
+    }, [nvlOptions === null || nvlOptions === void 0 ? void 0 : nvlOptions.useWebGL]);
+    useEffect(() => {
+        nvl === null || nvl === void 0 ? void 0 : nvl.setDisableWebGL(nvlOptions === null || nvlOptions === void 0 ? void 0 : nvlOptions.disableWebGL);
+    }, [nvlOptions === null || nvlOptions === void 0 ? void 0 : nvlOptions.disableWebGL]);
+    return React.createElement("div", { ref: containerRef, style: { height: '100%', outline: '0' } });
+}));
+export { BasicNvlWrapper };

package/lib/index.d.ts

@@ -0,0 +1,2 @@
+import { BasicNvlWrapper } from './basic-wrapper/BasicNvlWrapper';
+export { BasicNvlWrapper };

package/lib/index.js

@@ -0,0 +1,2 @@
+import { BasicNvlWrapper } from './basic-wrapper/BasicNvlWrapper';
+export { BasicNvlWrapper };

package/lib/utils/graphComparison.d.ts

@@ -0,0 +1,14 @@
+import { Node, Relationship } from '@neo4j-nvl/core';
+interface NodeChanges {
+    added: Node[];
+    removed: Node[];
+    updated: Node[];
+}
+interface RelChanges {
+    added: Relationship[];
+    removed: Relationship[];
+    updated: Relationship[];
+}
+declare const getMapDifferences: (prevGraphElements: Node[] | Relationship[], newGraphElements: Node[] | Relationship[]) => any;
+declare const getNodeAttributeDifferences: (prevNodes: Node[], newNodes: Node[]) => any[];
+export { getNodeAttributeDifferences, getMapDifferences, NodeChanges, RelChanges };

package/lib/utils/graphComparison.js

@@ -0,0 +1,59 @@
+import { isEqual, keyBy, transform, sortBy, keys } 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 === currId) {
+            if (!isEqual(prevMap[prevId], currentMap[currId])) {
+                updated.push(currId);
+            }
+            i++;
+            j++;
+        }
+        else if (prevId < currId) {
+            removed.push(prevId);
+            i++;
+        }
+        else {
+            added.push(currId);
+            j++;
+        }
+    }
+    while (i < prevIds.length) {
+        removed.push(prevIds[i++]);
+    }
+    while (j < currentIds.length) {
+        added.push(currentIds[j++]);
+    }
+    return {
+        added: added.map(id => currentMap[id]),
+        removed: removed.map(id => prevMap[id]),
+        updated: updated.map(id => currentMap[id])
+    };
+};
+const getNodeAttributeDifferences = (prevNodes, newNodes) => {
+    const prevNodeMap = keyBy(prevNodes, 'id');
+    return newNodes
+        .map(nodeToUpdate => {
+        const previousNode = prevNodeMap[nodeToUpdate.id];
+        if (!previousNode) {
+            return nodeToUpdate;
+        }
+        return transform(nodeToUpdate, (result, value, key) => {
+            if (key === 'id' || value !== previousNode[key]) {
+                result[key] = value;
+            }
+        });
+    })
+        .filter(n => Object.keys(n).length > 1);
+};
+export { getNodeAttributeDifferences, getMapDifferences };

package/lib/utils/hooks.d.ts

@@ -0,0 +1 @@
+export function useDeepCompareEffect(callback: any, dependencies: any): void;

package/lib/utils/hooks.js

@@ -0,0 +1,15 @@
+import { isEqual } from 'lodash';
+import { useEffect, useRef } from 'react';
+function deepCompareEquals(a, b) {
+    return isEqual(a, b);
+}
+function useDeepCompareMemoize(value) {
+    const ref = useRef();
+    if (!deepCompareEquals(value, ref.current)) {
+        ref.current = value;
+    }
+    return ref.current;
+}
+export const useDeepCompareEffect = (callback, dependencies) => {
+    useEffect(callback, dependencies.map(useDeepCompareMemoize));
+};

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@neo4j-nvl/react",
+  "version": "0.1.0",
+  "main": "lib/index.js",
+  "scripts": {
+    "prebuild": "rm -rf lib/",
+    "build": "tsc",
+    "test": "jest"
+  },
+  "files": [
+    "lib"
+  ],
+  "engines": {
+    "yarn": "^1.10.1"
+  },
+  "typedoc": {
+    "entryPoint": "./src/index.ts",
+    "readmeFile": "./README.md",
+    "displayName": "React",
+    "tsconfig": "./tsconfig.json"
+  },
+  "devDependencies": {
+    "@testing-library/jest-dom": "^5.16.5",
+    "@testing-library/react": "^13.4.0",
+    "@types/lodash": "^4.14.184",
+    "@types/react": "^18.0.18",
+    "babel-eslint": "^10.1.0",
+    "typedoc": "^0.23.15"
+  },
+  "dependencies": {
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0"
+  }
+}