Handle both mouse wheel and trackpad

.eslintrc.js

@@ -1,3 +1,34 @@
 module.exports = {
   extends: [require.resolve("vis-dev-utils/eslint-shareable-config")],
+  overrides: [
+    {
+      files: ["**/*.js", "**/*.ts"],
+      extends: ["plugin:jsdoc/recommended"],
+      rules: {
+        "jsdoc/check-examples": "off",
+        "jsdoc/check-indentation": "off",
+        "jsdoc/check-syntax": "warn",
+        "jsdoc/check-tag-names": ["error", { definedTags: ["remarks"] }],
+        "jsdoc/empty-tags": "warn",
+        "jsdoc/no-undefined-types": "off",
+        "jsdoc/require-description": "off",
+        "jsdoc/require-jsdoc": "warn",
+        "jsdoc/require-param-description": "off",
+        "jsdoc/require-param-type": "off",
+        "jsdoc/require-returns": "off",
+        "jsdoc/require-returns-check": "off",
+        "jsdoc/require-returns-description": "off",
+        "jsdoc/require-returns-type": "off",
+        "jsdoc/tag-lines": "off",
+      },
+      settings: {
+        jsdoc: {
+          tagNamePreference: {
+            inheritdoc: "inheritDoc",
+            typeparam: "typeParam",
+          },
+        },
+      },
+    },
+  ],
 };

examples/network/exampleUtil.js

@@ -1,10 +1,10 @@
 // These globals will be injected into a page that will use them.
-/* eslint no-unused-vars: "off" */
+/* eslint no-unused-vars: "off" -- old example */
 
 // This is quite old and I don't want to waste too much time here. We probably
 // should stop using this altogether as the examples should be easy and
 // straightforward to understand and this only obscures it.
-/* eslint require-jsdoc: "off" */
+/* eslint require-jsdoc: "off" -- it's an example */
 
 /* global Alea:false seededRandom:true */
 

lib/DOMutil.js

@@ -144,8 +144,7 @@ export function getDOMElement(
  *
  * @param {number} x
  * @param {number} y
- * @param {object} groupTemplate: A template containing the necessary information to draw the datapoint e.g., {style: 'circle', size: 5, className: 'className' }
- * @param groupTemplate
+ * @param {object} groupTemplate A template containing the necessary information to draw the datapoint e.g., {style: 'circle', size: 5, className: 'className' }
  * @param {object} JSONcontainer
  * @param {object} svgContainer
  * @param {object} labelObj

lib/network/modules/CanvasRenderer.js

@@ -254,8 +254,8 @@ class CanvasRenderer {
   /**
    * Redraw the network with the current data
    *
-   * @param {boolean} [hidden=false] | Used to get the first estimate of the node sizes.
-   *                                   Only the nodes are drawn after which they are quickly drawn over.
+   * @param {boolean} [hidden] Used to get the first estimate of the node sizes.
+   * Only the nodes are drawn after which they are quickly drawn over.
    * @private
    */
   _redraw(hidden = false) {
@@ -355,8 +355,6 @@ class CanvasRenderer {
   /**
    * Redraw all nodes
    *
-   * @param {CanvasRenderingContext2D}   ctx
-   * @param {boolean} [alwaysShow]
    * @private
    */
   _resizeNodes() {

lib/network/modules/Clustering.js

@@ -151,7 +151,7 @@ class ClusterEngine {
    * loop over all nodes, check if they adhere to the condition and cluster if needed.
    *
    * @param {object} options
-   * @param {boolean} [refreshData=true]
+   * @param {boolean} [refreshData]
    */
   cluster(options = {}, refreshData = true) {
     if (options.joinCondition === undefined) {
@@ -188,7 +188,7 @@ class ClusterEngine {
    *
    * @param {number} edgeCount
    * @param {object} options
-   * @param {boolean} [refreshData=true]
+   * @param {boolean} [refreshData]
    */
   clusterByEdgeCount(edgeCount, options, refreshData = true) {
     options = this._checkOptions(options);
@@ -310,7 +310,7 @@ class ClusterEngine {
    * Cluster all nodes in the network that have only 1 edge
    *
    * @param {object} options
-   * @param {boolean} [refreshData=true]
+   * @param {boolean} [refreshData]
    */
   clusterOutliers(options, refreshData = true) {
     this.clusterByEdgeCount(1, options, refreshData);
@@ -320,7 +320,7 @@ class ClusterEngine {
    * Cluster all nodes in the network that have only 2 edge
    *
    * @param {object} options
-   * @param {boolean} [refreshData=true]
+   * @param {boolean} [refreshData]
    */
   clusterBridges(options, refreshData = true) {
     this.clusterByEdgeCount(2, options, refreshData);
@@ -331,7 +331,7 @@ class ClusterEngine {
    *
    * @param {Node.id} nodeId
    * @param {object} options
-   * @param {boolean} [refreshData=true]
+   * @param {boolean} [refreshData]
    */
   clusterByConnection(nodeId, options, refreshData = true) {
     // kill conditions

lib/network/modules/EdgesHandler.js

@@ -248,7 +248,7 @@ class EdgesHandler {
    * Load edges by reading the data table
    *
    * @param {Array | DataSet | DataView} edges    The data containing the edges.
-   * @param {boolean} [doNotEmit=false] - Suppress data changed event.
+   * @param {boolean} [doNotEmit] - Suppress data changed event.
    * @private
    */
   setData(edges, doNotEmit = false) {
@@ -298,7 +298,7 @@ class EdgesHandler {
    * Add edges
    *
    * @param {number[] | string[]} ids
-   * @param {boolean} [doNotEmit=false]
+   * @param {boolean} [doNotEmit]
    * @private
    */
   add(ids, doNotEmit = false) {
@@ -362,7 +362,7 @@ class EdgesHandler {
    * Remove existing edges. Non existing ids will be ignored
    *
    * @param {number[] | string[]} ids
-   * @param {boolean} [emit=true]
+   * @param {boolean} [emit]
    * @private
    */
   remove(ids, emit = true) {

lib/network/modules/Groups.js

@@ -175,7 +175,7 @@ export class Groups {
    * If groupname is not found, a new group may be created.
    *
    * @param {*}       groupname     Can be a number, string, Date, etc.
-   * @param {boolean} [shouldCreate=true] If true, create a new group
+   * @param {boolean} [shouldCreate] If true, create a new group
    * @returns {object} The found or created group
    */
   get(groupname, shouldCreate = true) {

lib/network/modules/InteractionHandler.js

@@ -213,7 +213,7 @@ class InteractionHandler {
    * Select and deselect nodes depending current selection change.
    *
    * @param {{x: number, y: number}} pointer
-   * @param {boolean} [add=false]
+   * @param {boolean} [add]
    */
   checkSelectionChanges(pointer, add = false) {
     if (add === true) {
@@ -590,8 +590,6 @@ class InteractionHandler {
 
   /**
    * Event handler for mouse wheel event, used to zoom the timeline
-   * See http://adomas.org/javascript-mouse-wheel/
-   *     https://github.com/EightMedia/hammer.js/issues/256
    *
    * @param {MouseEvent}  event
    * @private
@@ -604,8 +602,14 @@ class InteractionHandler {
       if (event.deltaY !== 0) {
         // calculate the new scale
         let scale = this.body.view.scale;
-        scale *=
-          1 + (event.deltaY < 0 ? 1 : -1) * (this.options.zoomSpeed * 0.1);
+        const scaledY = event.deltaY / 8;
+        /**
+         * Rapid mouse wheel movement can cause the graph to zoom so fast
+         * that the entire graph disappears; therefore limit it to two
+         * "wheel clicks" per event.
+         */
+        const clampedY = Math.sign(scaledY) * Math.min(Math.abs(scaledY), 2);
+        scale *= 1 - clampedY * (this.options.zoomSpeed * 0.1);
 
         // calculate the pointer location
         const pointer = this.getPointer({ x: event.clientX, y: event.clientY });

lib/network/modules/KamadaKawai.js

@@ -43,7 +43,7 @@ class KamadaKawai {
    *
    * @param {Array.<Node>} nodesArray
    * @param {Array.<vis.Edge>} edgesArray
-   * @param {boolean} [ignoreClusters=false]
+   * @param {boolean} [ignoreClusters]
    */
   solve(nodesArray, edgesArray, ignoreClusters = false) {
     // get distance matrix

lib/network/modules/LayoutEngine.js

@@ -1615,7 +1615,7 @@ class LayoutEngine {
   /**
    * Crawl over the entire network and use a callback on each node couple that is connected to each other.
    *
-   * @param {Function} [callback=function(){}]          | will receive nodeA, nodeB and the connecting edge. A and B are distinct.
+   * @param {Function} [callback]          | will receive nodeA, nodeB and the connecting edge. A and B are distinct.
    * @param {Node.id} startingNodeId
    * @private
    */
@@ -1745,10 +1745,6 @@ class LayoutEngine {
    *
    * The individual instances contain all the operations and data specific to a layout direction.
    *
-   * @param {Node} node
-   * @param {{x: number, y: number}} position
-   * @param {number} level
-   * @param {boolean} [doNotUpdate=false]
    * @private
    */
   setDirectionStrategy() {

lib/network/modules/ManipulationSystem.js

@@ -723,7 +723,7 @@ class ManipulationSystem {
   /**
    * create a seperator line. the index is to differentiate in the manipulation dom
    *
-   * @param {number} [index=1]
+   * @param {number} [index]
    * @private
    */
   _createSeperator(index = 1) {

lib/network/modules/NodesHandler.js

@@ -245,7 +245,7 @@ class NodesHandler {
    * Set a data set with nodes for the network
    *
    * @param {Array | DataSet | DataView} nodes         The data containing the nodes.
-   * @param {boolean} [doNotEmit=false] - Suppress data changed event.
+   * @param {boolean} [doNotEmit] - Suppress data changed event.
    * @private
    */
   setData(nodes, doNotEmit = false) {
@@ -293,7 +293,7 @@ class NodesHandler {
    * Add nodes
    *
    * @param {number[] | string[]} ids
-   * @param {boolean} [doNotEmit=false]
+   * @param {boolean} [doNotEmit]
    * @private
    */
   add(ids, doNotEmit = false) {
@@ -380,7 +380,7 @@ class NodesHandler {
    * create a node
    *
    * @param {object} properties
-   * @param {class} [constructorClass=Node.default]
+   * @param {class} [constructorClass]
    * @returns {*}
    */
   create(properties, constructorClass = Node) {
@@ -396,7 +396,7 @@ class NodesHandler {
 
   /**
    *
-   * @param {boolean} [clearPositions=false]
+   * @param {boolean} [clearPositions]
    */
   refresh(clearPositions = false) {
     forEach(this.body.nodes, (node, nodeId) => {

lib/network/modules/PhysicsEngine.js

@@ -304,7 +304,7 @@ class PhysicsEngine {
   /**
    * Stop the simulation, force stabilization.
    *
-   * @param {boolean} [emit=true]
+   * @param {boolean} [emit]
    */
   stopSimulation(emit = true) {
     this.stabilized = true;
@@ -350,7 +350,7 @@ class PhysicsEngine {
   /**
    * trigger the stabilized event.
    *
-   * @param {number} [amountOfIterations=this.stabilizationIterations]
+   * @param {number} [amountOfIterations]
    * @private
    */
   _emitStabilized(amountOfIterations = this.stabilizationIterations) {
@@ -706,7 +706,7 @@ class PhysicsEngine {
   /**
    * Find a stable position for all nodes
    *
-   * @param {number} [iterations=this.options.stabilization.iterations]
+   * @param {number} [iterations]
    */
   stabilize(iterations = this.options.stabilization.iterations) {
     if (typeof iterations !== "number") {

lib/network/modules/SelectionHandler.js

@@ -124,11 +124,11 @@ class SelectionHandler {
    * This adds some extra data to the event with respect to cursor position and
    * selected nodes and edges.
    *
-   * @param {string} eventType                          Name of event to send
+   * @param {string} eventType Name of event to send
    * @param {Event}  event
-   * @param {{x: number, y: number}} pointer            Object with the x and y screen coordinates of the mouse
-   * @param {object | undefined} oldSelection             If present, selection state before event occured
-   * @param {boolean|undefined} [emptySelection=false]  Indicate if selection data should be passed
+   * @param {{x: number, y: number}} pointer Object with the x and y screen coordinates of the mouse
+   * @param {object | undefined} oldSelection If present, selection state before event occured
+   * @param {boolean|undefined} [emptySelection]  Indicate if selection data should be passed
    */
   generateClickEvent(
     eventType,
@@ -168,7 +168,7 @@ class SelectionHandler {
   /**
    *
    * @param {object} obj
-   * @param {boolean} [highlightEdges=this.options.selectConnectedEdges]
+   * @param {boolean} [highlightEdges]
    * @returns {boolean}
    */
   selectObject(obj, highlightEdges = this.options.selectConnectedEdges) {
@@ -237,7 +237,7 @@ class SelectionHandler {
    * Get the top node at the passed point (like a click)
    *
    * @param {{x: number, y: number}} pointer
-   * @param {boolean} [returnNode=true]
+   * @param {boolean} [returnNode]
    * @returns {Node | undefined} node
    */
   getNodeAt(pointer, returnNode = true) {
@@ -291,7 +291,7 @@ class SelectionHandler {
    * Get the edges nearest to the passed point (like a click)
    *
    * @param {{x: number, y: number}} pointer
-   * @param {boolean} [returnEdge=true]
+   * @param {boolean} [returnEdge]
    * @returns {Edge | undefined} node
    */
   getEdgeAt(pointer, returnEdge = true) {

lib/network/modules/View.js

@@ -37,7 +37,7 @@ class View {
 
   /**
    *
-   * @param {object} [options={}]
+   * @param {object} [options]
    */
   setOptions(options = {}) {
     this.options = options;
@@ -46,9 +46,8 @@ class View {
   /**
    * This function zooms out to fit all data on screen based on amount of nodes
    *
-   * @param {object} [options={{nodes=Array}}]
-   * @param options
-   * @param {boolean} [initialZoom=false]  | zoom based on fitted formula or range, true = fitted, default = false;
+   * @param {object} options
+   * @param {boolean} [initialZoom] zoom based on fitted formula or range, true = fitted, default = false;
    */
   fit(options, initialZoom = false) {
     options = normalizeFitOptions(options, this.body.nodeIndices);
@@ -368,7 +367,7 @@ class View {
   }
 
   /**
-   * @param {boolean} [finished=false]
+   * @param {boolean} [finished]
    * @private
    */
   _transitionRedraw(finished = false) {