Enhancement: add property Graph.prependData to support Plotly.prependTraces

CHANGELOG.md

@@ -2,6 +2,11 @@
 All notable changes to this project will be documented in this file.
 This project adheres to [Semantic Versioning](http://semver.org/).
 
+## [Unreleased]
+### Added
+- [#850](https://github.com/plotly/dash-core-components/pull/850) Add property `prependData` to `Graph` to support `Plotly.prependTraces`
+  + refactored the existing `extendTraces` API to be a single `mergeTraces` API that can handle both `prepend` as well as `extend`.
+
 ## [1.12.0] - 2020-09-03
 ### Updated
 - [#858](https://github.com/plotly/dash-core-components/pull/858)

src/components/Graph.react.js

@@ -9,7 +9,7 @@ import {
     privateDefaultProps,
 } from '../fragments/Graph.privateprops';
 
-const EMPTY_EXTEND_DATA = [];
+const EMPTY_DATA = [];
 
 /**
  * Graph can be used to render any plotly.js-powered data visualization.
@@ -22,13 +22,19 @@ class PlotlyGraph extends Component {
         super(props);
 
         this.state = {
+            prependData: [],
             extendData: [],
         };
 
-        this.clearExtendData = this.clearExtendData.bind(this);
+        this.clearState = this.clearState.bind(this);
     }
 
     componentDidMount() {
+        if (this.props.prependData) {
+            this.setState({
+                prependData: [this.props.prependData],
+            });
+        }
         if (this.props.extendData) {
             this.setState({
                 extendData: [this.props.extendData],
@@ -38,15 +44,37 @@ class PlotlyGraph extends Component {
 
     componentWillUnmount() {
         this.setState({
+            prependData: [],
             extendData: [],
         });
     }
 
     UNSAFE_componentWillReceiveProps(nextProps) {
+        let prependData = this.state.prependData.slice(0);
+
+        if (this.props.figure !== nextProps.figure) {
+            prependData = EMPTY_DATA;
+        }
+
+        if (
+            nextProps.prependData &&
+            this.props.prependData !== nextProps.prependData
+        ) {
+            prependData.push(nextProps.prependData);
+        } else {
+            prependData = EMPTY_DATA;
+        }
+
+        if (prependData !== EMPTY_DATA) {
+            this.setState({
+                prependData,
+            });
+        }
+
         let extendData = this.state.extendData.slice(0);
 
         if (this.props.figure !== nextProps.figure) {
-            extendData = EMPTY_EXTEND_DATA;
+            extendData = EMPTY_DATA;
         }
 
         if (
@@ -55,22 +83,23 @@ class PlotlyGraph extends Component {
         ) {
             extendData.push(nextProps.extendData);
         } else {
-            extendData = EMPTY_EXTEND_DATA;
+            extendData = EMPTY_DATA;
         }
 
-        if (extendData !== EMPTY_EXTEND_DATA) {
+        if (extendData !== EMPTY_DATA) {
             this.setState({
                 extendData,
             });
         }
     }
 
-    clearExtendData() {
-        this.setState(({extendData}) => {
+    clearState(dataKey) {
+        this.setState(props => {
+            var data = props[dataKey];
             const res =
-                extendData && extendData.length
+                data && data.length
                     ? {
-                          extendData: EMPTY_EXTEND_DATA,
+                          [dataKey]: EMPTY_DATA,
                       }
                     : undefined;
 
@@ -82,8 +111,9 @@ class PlotlyGraph extends Component {
         return (
             <ControlledPlotlyGraph
                 {...this.props}
+                prependData={this.state.prependData}
                 extendData={this.state.extendData}
-                clearExtendData={this.clearExtendData}
+                clearState={this.clearState}
             />
         );
     }
@@ -191,6 +221,18 @@ PlotlyGraph.propTypes = {
      */
     extendData: PropTypes.oneOfType([PropTypes.array, PropTypes.object]),
 
+    /**
+     * Data that should be prepended to existing traces. Has the form
+     * `[updateData, traceIndices, maxPoints]`, where `updateData` is an object
+     * containing the data to prepend, `traceIndices` (optional) is an array of
+     * trace indices that should be prepended, and `maxPoints` (optional) is
+     * either an integer defining the maximum number of points allowed or an
+     * object with key:value pairs matching `updateData`
+     * Reference the Plotly.prependTraces API for full usage:
+     * https://plotly.com/javascript/plotlyjs-function-reference/#plotlyprependtraces
+     */
+    prependData: PropTypes.oneOfType([PropTypes.array, PropTypes.object]),
+
     /**
      * Data from latest restyle event which occurs
      * when the user toggles a legend item, changes
@@ -523,6 +565,7 @@ PlotlyGraph.defaultProps = {
     hoverData: null,
     selectedData: null,
     relayoutData: null,
+    prependData: null,
     extendData: null,
     restyleData: null,
     figure: {

src/fragments/Graph.react.js

@@ -188,18 +188,16 @@ class PlotlyGraph extends Component {
         });
     }
 
-    extend(props) {
-        const {clearExtendData, extendData: extendDataArray} = props;
+    mergeTraces(props, dataKey, plotlyFnKey) {
+        const clearState = props.clearState;
+        const dataArray = props[dataKey];
 
-        extendDataArray.forEach(extendData => {
+        dataArray.forEach(data => {
             let updateData, traceIndices, maxPoints;
-            if (
-                Array.isArray(extendData) &&
-                typeof extendData[0] === 'object'
-            ) {
-                [updateData, traceIndices, maxPoints] = extendData;
+            if (Array.isArray(data) && typeof data[0] === 'object') {
+                [updateData, traceIndices, maxPoints] = data;
             } else {
-                updateData = extendData;
+                updateData = data;
             }
 
             if (!traceIndices) {
@@ -214,9 +212,9 @@ class PlotlyGraph extends Component {
             }
 
             const gd = this.gd.current;
-            return Plotly.extendTraces(gd, updateData, traceIndices, maxPoints);
+            return Plotly[plotlyFnKey](gd, updateData, traceIndices, maxPoints);
         });
-        clearExtendData();
+        clearState(dataKey);
     }
 
     getConfig(config, responsive) {
@@ -348,8 +346,11 @@ class PlotlyGraph extends Component {
 
     componentDidMount() {
         this.plot(this.props);
+        if (this.props.prependData) {
+            this.mergeTraces(this.props, 'prependData', 'prependTraces');
+        }
         if (this.props.extendData) {
-            this.extend(this.props);
+            this.mergeTraces(this.props, 'extendData', 'extendTraces');
         }
     }
 
@@ -392,8 +393,12 @@ class PlotlyGraph extends Component {
             this.plot(nextProps);
         }
 
+        if (this.props.prependData !== nextProps.prependData) {
+            this.mergeTraces(nextProps, 'prependData', 'prependTraces');
+        }
+
         if (this.props.extendData !== nextProps.extendData) {
-            this.extend(nextProps);
+            this.mergeTraces(nextProps, 'extendData', 'extendTraces');
         }
     }
 
@@ -432,14 +437,18 @@ class PlotlyGraph extends Component {
 
 PlotlyGraph.propTypes = {
     ...graphPropTypes,
+    prependData: PropTypes.arrayOf(
+        PropTypes.oneOfType([PropTypes.array, PropTypes.object])
+    ),
     extendData: PropTypes.arrayOf(
         PropTypes.oneOfType([PropTypes.array, PropTypes.object])
     ),
-    clearExtendData: PropTypes.func.isRequired,
+    clearState: PropTypes.func.isRequired,
 };
 
 PlotlyGraph.defaultProps = {
     ...graphDefaultProps,
+    prependData: [],
     extendData: [],
 };