Add emitParticles and onBackground events

Author: vasturiano

README.md

@@ -35,6 +35,7 @@ Check out the examples:
 * [Click to focus on node](https://vasturiano.github.io/react-force-graph/example/click-to-focus/) ([source](https://github.com/vasturiano/react-force-graph/blob/master/example/click-to-focus/index.html))
 * [Camera automatic orbitting](https://vasturiano.github.io/react-force-graph/example/camera-auto-orbit/) ([source](https://github.com/vasturiano/react-force-graph/blob/master/example/camera-auto-orbit/index.html))
 * [Node collision detection](https://vasturiano.github.io/react-force-graph/example/collision-detection/) ([source](https://github.com/vasturiano/react-force-graph/blob/master/example/collision-detection/index.html))
+* [Emit link particles on demand](https://vasturiano.github.io/react-force-graph/example/emit-particles/) ([source](https://github.com/vasturiano/react-force-graph/blob/master/example/emit-particles/index.html))
 * [Force-directed tree (DAG mode)](https://vasturiano.github.io/react-force-graph/example/tree/) ([source](https://github.com/vasturiano/react-force-graph/blob/master/example/tree/index.html))
 
 ## Quick start
@@ -134,6 +135,10 @@ Note that not all props listed below apply to all 3 components. The last 3 colum
 | <b>linkDirectionalParticleColor</b> | <i>string</i> or <i>func</i> | `color` | Link object accessor function or attribute for the directional particles color. | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: |
 | <b>linkDirectionalParticleResolution</b> | <i>number</i> | 4 | Geometric resolution of each 3D directional particle, expressed in how many slice segments to divide the circumference. Higher values yield smoother particles. | | :heavy_check_mark: | :heavy_check_mark: |
 
+| Method | Arguments | Description | 2D | 3D | VR |
+| --- | :--: | --- | :--: | :--: | :--: |
+| <b>emitParticle</b> | (<i>link</i>) | An alternative mechanism for generating particles, this method emits a non-cyclical single particle within a specific link. The emitted particle shares the styling (speed, width, color) of the regular particle props. A valid `link` object that is included in `graphData` should be passed as a single parameter. | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: |
+
 ### Render control
 
 | Prop | Type | Default | Description |
@@ -185,6 +190,8 @@ Note that not all props listed below apply to all 3 components. The last 3 colum
 | <b>onLinkClick</b> | <i>func</i> | *-* | Callback function for link (left-button) clicks. The link object is included as single argument `onLinkClick(link)`. | :heavy_check_mark: | :heavy_check_mark: | |
 | <b>onLinkRightClick</b> | <i>func</i> | *-* | Callback function for link right-clicks. The link object is included as single argument `onLinkRightClick(link)`. | :heavy_check_mark: | :heavy_check_mark: | |
 | <b>onLinkHover</b> | <i>func</i> | *-* | Callback function for link mouse over events. The link object (or `null` if there's no link under the mouse line of sight) is included as the first argument, and the previous link object (or null) as second argument: `onLinkHover(link, prevLink)`. | :heavy_check_mark: | :heavy_check_mark: | |
+| <b>onBackgroundClick</b> | <i>func</i> | *-* | Callback function for click events on the empty space between the nodes and links. | :heavy_check_mark: | :heavy_check_mark: | |
+| <b>onBackgroundRightClick</b> | <i>func</i> | *-* | Callback function for right-click events on the empty space between the nodes and links. | :heavy_check_mark: | :heavy_check_mark: | |
 | <b>linkHoverPrecision</b> | <i>number</i> | 4 | Whether to display the link label when gazing the link closely (low value) or from far away (high value). | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: |
 | <b>onZoom</b> | <i>func</i> | *-* | Callback function for zoom/pan events. The current zoom transform is included as single argument `onZoom({ k, x, y })`. Note that `onZoom` is triggered by user interaction as well as programmatic zooming/panning with `zoom()` and `centerAt()`. | :heavy_check_mark: | | |
 | <b>controlType</b> | <i>string</i> | `trackball` | Which type of control to use to control the camera on 3D mode. Choice between [trackball](https://threejs.org/examples/misc_controls_trackball.html), [orbit](https://threejs.org/examples/#misc_controls_orbit) or [fly](https://threejs.org/examples/misc_controls_fly.html). | | :heavy_check_mark: | |

example/emit-particles/index.html

@@ -0,0 +1,41 @@
+<head>
+  <style> body { margin: 0; } </style>
+
+  <script src="//unpkg.com/react@16/umd/react.production.min.js"></script>
+  <script src="//unpkg.com/react-dom@16/umd/react-dom.production.min.js"></script>
+  <script src="//unpkg.com/babel-standalone"></script>
+
+  <script src="//unpkg.com/react-force-graph-3d"></script>
+  <!--<script src="../../src/packages/react-force-graph-3d/dist/react-force-graph-3d.js"></script>-->
+
+  <script src="../datasets/random-data.js"></script>
+</head>
+
+<body>
+<div id="graph"></div>
+
+<script type="text/jsx">
+  const { useEffect, useRef } = React;
+
+  const data = genRandomTree();
+  const distance = 1400;
+
+  const CameraOrbit = () => {
+    const fgRef = useRef();
+
+    return <ForceGraph3D
+      ref={fgRef}
+      graphData={data}
+      linkDirectionalParticleColor={() => 'red'}
+      linkDirectionalParticleWidth={6}
+      linkHoverPrecision={10}
+      onLinkClick={link => fgRef.current.emitParticle(link)}
+    />;
+  };
+
+  ReactDOM.render(
+    <CameraOrbit />,
+    document.getElementById('graph')
+  );
+</script>
+</body>

package.json

@@ -40,9 +40,9 @@
     "dist/**/*"
   ],
   "dependencies": {
-    "3d-force-graph": "^1.54.0",
-    "3d-force-graph-vr": "^1.28.0",
-    "force-graph": "^1.19.0",
+    "3d-force-graph": "^1.55.1",
+    "3d-force-graph-vr": "^1.29.0",
+    "force-graph": "^1.21.2",
     "prop-types": "^15.7.2",
     "react-kapsule": "^1.4.3"
   },
@@ -56,11 +56,11 @@
     "@babel/preset-env": "^7.6.2",
     "@babel/preset-react": "^7.0.0",
     "rimraf": "^3.0.0",
-    "rollup": "^1.21.4",
+    "rollup": "^1.22.0",
     "rollup-plugin-babel": "^4.3.3",
     "rollup-plugin-commonjs": "^10.1.0",
     "rollup-plugin-node-resolve": "^5.2.0",
     "rollup-plugin-replace": "^2.2.0",
-    "terser": "^4.3.1"
+    "terser": "^4.3.4"
   }
 }

src/forcegraph-proptypes.js

@@ -51,6 +51,8 @@ const pointerBasedPropTypes = {
   onLinkClick: PropTypes.func,
   onLinkRightClick: PropTypes.func,
   onLinkHover: PropTypes.func,
+  onBackgroundClick: PropTypes.func,
+  onBackgroundRightClick: PropTypes.func,
   enablePointerInteraction: PropTypes.bool,
   enableNodeDrag: PropTypes.bool
 };

src/packages/react-force-graph-2d/index.js

@@ -6,6 +6,7 @@ const ForceGraph2D = fromKapsule(
   ForceGraph2DKapsule,
   undefined,
   [ // bind methods
+    'emitParticle',
     'd3Force',
     'd3ReheatSimulation',
     'stopAnimation',

src/packages/react-force-graph-2d/package.json

@@ -36,7 +36,7 @@
     "dist/**/*"
   ],
   "dependencies": {
-    "force-graph": "^1.19.0",
+    "force-graph": "^1.21.2",
     "prop-types": "^15.7.2",
     "react-kapsule": "^1.4.3"
   },
@@ -45,7 +45,7 @@
   },
   "devDependencies": {
     "rimraf": "^3.0.0",
-    "rollup": "^1.21.4",
-    "terser": "^4.3.1"
+    "rollup": "^1.22.0",
+    "terser": "^4.3.4"
   }
 }

src/packages/react-force-graph-3d/index.js

@@ -6,6 +6,7 @@ const ForceGraph3D = fromKapsule(
   ForceGraph3DKapsule,
   undefined,
   [ // bind methods
+    'emitParticle',
     'd3Force',
     'd3ReheatSimulation',
     'stopAnimation',

src/packages/react-force-graph-3d/package.json

@@ -37,7 +37,7 @@
     "dist/**/*"
   ],
   "dependencies": {
-    "3d-force-graph": "^1.54.0",
+    "3d-force-graph": "^1.55.1",
     "prop-types": "^15.7.2",
     "react-kapsule": "^1.4.3"
   },
@@ -46,7 +46,7 @@
   },
   "devDependencies": {
     "rimraf": "^3.0.0",
-    "rollup": "^1.21.4",
-    "terser": "^4.3.1"
+    "rollup": "^1.22.0",
+    "terser": "^4.3.4"
   }
 }

src/packages/react-force-graph-vr/index.js

@@ -6,6 +6,7 @@ const ForceGraphVR = fromKapsule(
   ForceGraphVRKapsule,
   undefined,
   [ // bind methods
+    'emitParticle',
     'd3Force',
     'd3ReheatSimulation',
     'refresh'

src/packages/react-force-graph-vr/package.json

@@ -37,7 +37,7 @@
     "dist/**/*"
   ],
   "dependencies": {
-    "3d-force-graph-vr": "^1.28.0",
+    "3d-force-graph-vr": "^1.29.0",
     "prop-types": "^15.7.2",
     "react-kapsule": "^1.4.3"
   },
@@ -46,7 +46,7 @@
   },
   "devDependencies": {
     "rimraf": "^3.0.0",
-    "rollup": "^1.21.4",
-    "terser": "^4.3.1"
+    "rollup": "^1.22.0",
+    "terser": "^4.3.4"
   }
 }