Focus view on a node (#107)

* feat: Focus graph on a node

It is now possible to set a "focusedNodeId" to the graph, which will
result in the selected node appearing on the center of the displayed
area of the graph.

Optionally, aside from centering the view on it, a certain zoom can be
applied while the node is focused on screen. No zoom is applied by
default, but that behaviour can be configured by using the new
"focusZoom" parameter in the config object. This setting should receive
a number with the zoom level to apply, so the larger it is, the bigger
the node will appear on screen.

* feat: Node focus feature example added to sandbox

* fix: Ensure that focusZoom is between minZoom and maxZoom

* fix: Avoid issue with id datatypes when searching for focused node

* refactor: Improve readability for focusZoom bounds

Nested ternary expressions replaced by a more readable if-else
expression when checking if the `focusZoom` property set by the user is
between the configured `minZoom` and `maxZoom`.

* refactor: Remove  statements in library code

* revert: Removed blank lines in DOCUMENTATION.md

* docs: Added more information on focusZoom property

* feat: Customize focus animation length

* refactor: focusNodeId wrapped in data props

Instead of being a prop on its own, the 'focusedNodeId' must now be
included as part of the 'data' object received by the Graph component.

The sandbox code has been update to reflect this change.

* refactor: focus transformation function moved to graphHelper

The 'getCenterAndZoomTransformation' has been rellocated to the graph
helper file, instead of being part of the Graph component.

* docs: Updated jsdoc for getCenterAndZoomTransformation

* refactor: Renamed config param for focus animation duration

* test: Graph snapshot updated

* fix: Consider hidden links when obtaining matrix

The link matrix was not been properly updated when the collapsible
setting was enabled. This is because when obtaining its values it didn't
check whether the different links were hidden or not.

This change fixes the issue and prevents the link matrix from containing
wrong values which cause orphan nodes are not hidden properly during
collapse.

* fix: Reset transition duration after focus animation

The transition duration property was been applied to the graph container
at all times, which affected to every other transformations that
triggered on it. This included the default zoom or the drag and drop
functionality, among others.

In order to fix this, that transition duration value is set back to zero
after the focus and zoom animation has finished. Some actions on the
node do also cancel the animation in case it's still ongoing, like
trying to drag a node.

With this change, there's no longer a delay when moving a node to
another location or while performing a zoom.

* test: Graph snapshot updated with default transition duration

* fix: Drag & drop in focused node

There was an issue with the drag and drop feature when used along the
focus and zoom transformation.

The problem was that we were recalculating the transformation everytime
the page was rendered, which meant that a new transform value would be
created anytime the node moved to a new position.

This issue only affected the focused node itself, since the
`getCenterAndZoomTransformation` did only depend on that node
coordinates.

To avoid abnormal behaviours, the transformation is only obtained when the graph receives props. By doing this, the current view position is preserved until a new focused node is set. If the user drags the node around, current zoom and position will be unaffected by it. This matches the default behaviour we encounter in any other scenario, when moving any other nodes or not having activated the focus and zoom feature.

* refactor: Reset transition duration on drag start

The `enableFocusAnimation` property in Graph' state is now set to
`false` in the `dragStart` event instead of during `dragMove`. This
change should have a positive impact in the application's perfomance, as
the `enableFocusAnimation` value will only checked once instead of being
read in every position change during a drag operation.

* style: Added blank line after variable declaration

* chore: Browser environment added to ESLint config

* refactor: getCenterAndZoomTransformation receives d3Node object

* fix: Node not centered when focusing with zoom

One of the latest changes broke the focus feature in certain scenarios.
When a focus zoom different from one was applied, the view was not
properly centered in the selected node. The transformation obtained in
the 'getCenterAndZoomTransformation' did not work as expected. Applying
a single translate before scaling didn't seem to do the trick, and the
second translate is necessary for the view to display the selected node
in the center after scaling the graph.

* refactor: Store focusedNodeId in Graph component state

Author: LonelyPrincess

.eslintrc.js

@@ -16,6 +16,9 @@ module.exports = {
         }
     },
     plugins: ['standard', 'promise', 'react', 'jest', 'cypress'],
+    env: {
+        browser: true
+    },
     rules: {
         'react/jsx-uses-react': 'error',
         'react/jsx-uses-vars': 'error',

docs/DOCUMENTATION.md

@@ -877,9 +877,11 @@ components.
     },
     ...
     }
+
     ```
 
     ```
+
 *   `linkCallbacks` **[Array][87]<[Function][83]>** array of callbacks for used defined event handler for link interactions.
 *   `config` **[Object][74]** an object containing rd3g consumer defined configurations [config][92] for the graph.
 *   `highlightedNode` **[string][78]** this value contains a string that represents the some currently highlighted node.

package.json

@@ -25,7 +25,8 @@
         "start": "http-server ./sandbox/ -p 8888 -c-1",
         "test:clean": "jest --no-cache --updateSnapshot --verbose --coverage --config jest.config.js",
         "test:watch": "jest --verbose --coverage --watchAll --config jest.config.js",
-        "test": "jest --verbose --coverage --config jest.config.js"
+        "test": "jest --verbose --coverage --config jest.config.js",
+        "sandbox": "npm run dist:sandbox && npm run start"
     },
     "lint-staged": {
         "*.{js,jsx,json,css,md}": [

sandbox/Sandbox.jsx

@@ -53,7 +53,15 @@ export default class Sandbox extends React.Component {
 
     onClickGraph = () => console.info(`Clicked the graph`);
 
-    onClickNode = id => !this.state.config.collapsible && window.alert(`Clicked node ${id}`);
+    onClickNode = id => {
+        !this.state.config.collapsible && window.alert(`Clicked node ${id}`);
+        this.setState({
+            data: {
+                ...this.state.data,
+                focusedNodeId: this.state.data.focusedNodeId !== id ? id : null
+            }
+        });
+    };
 
     onRightClickNode = (event, id) => {
         event.preventDefault();
@@ -299,7 +307,8 @@ export default class Sandbox extends React.Component {
         // to true in the constructor we will provide nodes with initial positions
         const data = {
             nodes: this.decorateGraphNodesWithInitialPositioning(this.state.data.nodes),
-            links: this.state.data.links
+            links: this.state.data.links,
+            focusedNodeId: this.state.data.focusedNodeId
         };
 
         const graphProps = {

src/components/graph/Graph.jsx

@@ -165,7 +165,12 @@ export default class Graph extends React.Component {
      * Handles d3 drag 'start' event.
      * @returns {undefined}
      */
-    _onDragStart = () => this.pauseSimulation();
+    _onDragStart = () => {
+        this.pauseSimulation();
+        if (this.state.enableFocusAnimation) {
+            this.setState({ enableFocusAnimation: false });
+        }
+    };
 
     /**
      * Sets nodes and links highlighted value.
@@ -309,6 +314,7 @@ export default class Graph extends React.Component {
             utils.throwErr(this.constructor.name, ERRORS.GRAPH_NO_ID_PROP);
         }
 
+        this.focusAnimationTimeout = null;
         this.state = graphHelper.initializeGraphState(this.props, this.state);
     }
 
@@ -337,13 +343,21 @@ export default class Graph extends React.Component {
 
         const transform = newConfig.panAndZoom !== this.state.config.panAndZoom ? 1 : this.state.transform;
 
+        const focusedNodeId = nextProps.data.focusedNodeId;
+        const d3FocusedNode = this.state.d3Nodes.find(node => `${node.id}` === `${focusedNodeId}`);
+        const focusTransformation = graphHelper.getCenterAndZoomTransformation(d3FocusedNode, this.state.config);
+        const enableFocusAnimation = this.props.data.focusedNodeId !== nextProps.data.focusedNodeId;
+
         this.setState({
             ...state,
             config,
             configUpdated,
             d3ConfigUpdated,
             newGraphElements,
-            transform
+            transform,
+            focusedNodeId,
+            enableFocusAnimation,
+            focusTransformation
         });
     }
 
@@ -413,6 +427,10 @@ export default class Graph extends React.Component {
      * @returns {undefined}
      */
     onClickGraph = e => {
+        if (this.state.enableFocusAnimation) {
+            this.setState({ enableFocusAnimation: false });
+        }
+
         // Only trigger the graph onClickHandler, if not clicked a node or link.
         // toUpperCase() is added as a precaution, as the documentation says tagName should always
         // return in UPPERCASE, but chrome returns lowercase
@@ -424,6 +442,35 @@ export default class Graph extends React.Component {
         }
     };
 
+    /**
+     * Obtain a set of properties which will be used to perform the focus and zoom animation if
+     * required. In case there's not a focus and zoom animation in progress, it should reset the
+     * transition duration to zero and clear transformation styles.
+     * @returns {Object} - Focus and zoom animation properties.
+     */
+    _generateFocusAnimationProps = () => {
+        const { focusedNodeId } = this.state;
+
+        // In case an older animation was still not complete, clear previous timeout to ensure the new one is not cancelled
+        if (this.state.enableFocusAnimation) {
+            if (this.focusAnimationTimeout) {
+                clearTimeout(this.focusAnimationTimeout);
+            }
+
+            this.focusAnimationTimeout = setTimeout(
+                () => this.setState({ enableFocusAnimation: false }),
+                this.state.config.focusAnimationDuration * 1000
+            );
+        }
+
+        const transitionDuration = this.state.enableFocusAnimation ? this.state.config.focusAnimationDuration : 0;
+
+        return {
+            style: { transitionDuration: `${transitionDuration}s` },
+            transform: focusedNodeId ? this.state.focusTransformation : null
+        };
+    };
+
     render() {
         const { nodes, links, defs } = graphRenderer.buildGraph(
             this.state.nodes,
@@ -452,11 +499,13 @@ export default class Graph extends React.Component {
             width: this.state.config.width
         };
 
+        const containerProps = this._generateFocusAnimationProps();
+
         return (
             <div id={`${this.state.id}-${CONST.GRAPH_WRAPPER_ID}`}>
                 <svg name={`svg-container-${this.state.id}`} style={svgStyle} onClick={this.onClickGraph}>
                     {defs}
-                    <g id={`${this.state.id}-${CONST.GRAPH_CONTAINER_ID}`}>
+                    <g id={`${this.state.id}-${CONST.GRAPH_CONTAINER_ID}`} {...containerProps}>
                         {links}
                         {nodes}
                     </g>

src/components/graph/graph.config.js

@@ -59,6 +59,9 @@
  * the value the more the less highlighted nodes will be visible (related to *nodeHighlightBehavior*).
  * @param {number} [maxZoom=8] - max zoom that can be performed against the graph.
  * @param {number} [minZoom=0.1] - min zoom that can be performed against the graph.
+ * @param {number} [focusZoom=1] - zoom that will be applied when the graph view is focused in a node. Its value must be between
+ * *minZoom* and *maxZoom*. If the specified *focusZoom* is out of this range, *minZoom* or *maxZoom* will be applied instead.
+ * @param {number} [focusAnimationDuration=0.75] - duration (in seconds) for the animation that takes place when focusing the graph on a node.
  * @param {boolean} [panAndZoom=false] - 🚅🚅🚅 pan and zoom effect when performing zoom in the graph,
  * a similar functionality may be consulted {@link https://bl.ocks.org/mbostock/2a39a768b1d4bc00a09650edef75ad39|here}.
  * @param {boolean} [staticGraph=false] - when setting this value to true the graph will be completely static, thus
@@ -182,6 +185,8 @@ export default {
     linkHighlightBehavior: false,
     maxZoom: 8,
     minZoom: 0.1,
+    focusZoom: 1,
+    focusAnimationDuration: 0.75,
     nodeHighlightBehavior: false,
     panAndZoom: false,
     staticGraph: false,

src/components/graph/graph.helper.js

@@ -112,7 +112,7 @@ function _initializeLinks(graphLinks, config) {
             links[target] = {};
         }
 
-        const value = l.value || 1;
+        const value = config.collapsible && l.isHidden ? 0 : l.value || 1;
 
         links[source][target] = value;
 
@@ -475,6 +475,14 @@ function initializeGraphState({ data, id, config }, state) {
     const formatedId = id.replace(/ /g, '_');
     const simulation = _createForceSimulation(newConfig.width, newConfig.height, newConfig.d3 && newConfig.d3.gravity);
 
+    const { minZoom, maxZoom, focusZoom } = newConfig;
+
+    if (focusZoom > maxZoom) {
+        newConfig.focusZoom = maxZoom;
+    } else if (focusZoom < minZoom) {
+        newConfig.focusZoom = minZoom;
+    }
+
     return {
         id: formatedId,
         config: newConfig,
@@ -521,11 +529,34 @@ function updateNodeHighlightedValue(nodes, links, config, id, value = false) {
     };
 }
 
+/**
+ * Returns the transformation to apply in order to center the graph on the
+ * selected node.
+ * @param {Object} d3Node - node to focus the graph view on.
+ * @param {Object} config - same as {@link #buildGraph|config in buildGraph}.
+ * @returns {string} transform rule to apply.
+ * @memberof Graph/helper
+ */
+function getCenterAndZoomTransformation(d3Node, config) {
+    if (!d3Node) {
+        return;
+    }
+
+    const { width, height, focusZoom } = config;
+
+    return `
+        translate(${width / 2}, ${height / 2})
+        scale(${focusZoom})
+        translate(${-d3Node.x}, ${-d3Node.y})
+    `;
+}
+
 export {
     buildLinkProps,
     buildNodeProps,
     checkForGraphConfigChanges,
     checkForGraphElementsChanges,
     initializeGraphState,
-    updateNodeHighlightedValue
+    updateNodeHighlightedValue,
+    getCenterAndZoomTransformation
 };

test/snapshot/graph/__snapshots__/graph.snapshot.test.js.snap

@@ -108,6 +108,12 @@ exports[`Snapshot - Graph Component should match snapshot 1`] = `
     </defs>
     <g
       id="graphId-graph-container-zoomable"
+      style={
+        Object {
+          "transitionDuration": "0s",
+        }
+      }
+      transform={null}
     >
       <path
         className="link"