Merge branch 'master' into axis-breaks

Author: etpinard

CONTRIBUTING.md

@@ -17,6 +17,7 @@ We use the following [labels](https://github.com/plotly/plotly.js/labels) to tra
 | `type: bug` | bug report confirmed by a plotly team member |
 | `type: regression` | bug that introduced a change in behavior from one version to the next |
 | `type: feature` | planned feature additions |
+| `type: new trace type` | subset of `type: feature` reserved for planned new trace types |
 | `type: translation` | localization-related tasks |
 | `type: performance` | performance related tasks |
 | `type: maintenance` | source code cleanup resulting in no enhancement for users |
@@ -96,6 +97,13 @@ Three additional helpers exist that are refreshed every second:
 There is also a search bar in the top right of the dashboard. This fuzzy-searches
 image mocks based on their file name and trace type.
 
+#### Alternative to test dashboard
+
+Use the [`plotly-mock-viewer`](https://github.com/rreusser/plotly-mock-viewer)
+which has live-reloading and a bunch of other cool features.
+An online version of `plotly-mock-viewer` is available at https://rreusser.github.io/plotly-mock-viewer/
+which uses https://cdn.plot.ly/plotly-latest.min.js
+
 #### Other npm scripts
 
 - `npm run preprocess`: pre-processes the css and svg source file in js. This
@@ -175,11 +183,23 @@ which shows the baseline image, the generated image, the diff and the json mocks
 
 To view the results of a run on CircleCI, download the `build/test_images/` and `build/test_images_diff/` artifacts into your local repo and then run `npm run start-image_viewer`.
 
-### Writing interaction tests
+### Using the developer console in karma to write/debug jasmine tests
+
+- Click on the `DEBUG` button
+- In the `DEBUG RUNNER` window, open the console (e.g. with `<ctrl-shift-j>`)
+- Find test file (e.g. with `<ctrl-o>` + typing the name of the file), look out
+  for "bundled" files with the same name.
+- Set `debugger` on relevant line(s)
+- Rerun the test suite by refreshing the page (e.g. with `<crtl-r>`)
+
+![Peek 2020-03-11 10-45](https://user-images.githubusercontent.com/6675409/76438118-f2502300-6390-11ea-88d2-17a553c3b4e8.gif)
+
+### Writing jasmine interaction tests
+
 Keep in mind that the interaction coordinates are relative to the top-left corner of the plot, including the margins. To produce a reliable interaction test, 
 it may be necessary to fix the width, height, margins, X axis range and Y axis range of the plot. For example:
 
-```
+```js
 Plotly.newPlot(gd, [{
     x: [1, 1, 1, 2, 2, 2, 3, 3, 3],
     y: [1, 2, 3, 1, 2, 3, 1, 2, 3],
@@ -196,18 +216,67 @@ This will produce the following plot, and say you want to simulate a selection p
 
 <img src="https://user-images.githubusercontent.com/31989842/38890553-0bc6190c-4282-11e8-8efc-077bf05ca565.png">
 
-
 ## Repo organization
 
 - Distributed files are in `dist/`
 - CommonJS require-able modules are in `lib/`
-- Sources files are in `src/`, including the index
+- Sources files are in `src/`
 - Build and repo management scripts are in `tasks/`
 - All tasks can be run using [`npm run-script`](https://docs.npmjs.com/cli/run-script)
 - Tests are `test/`, they are partitioned into `image` and `jasmine` tests
 - Test dashboard and image viewer code is in `devtools/`
-- Built files are in `build/` (most files in here are git-ignored, the css and font built files are exceptions)
-
+- Built files are in `build/` (the files in here are git-ignored, except for `plotcss.js`)
+
+## Trace module design
+
+The trace modules (found in [`src/traces`](https://github.com/plotly/plotly.js/tree/master/src/traces))
+are defined as plain objects with functions and constants attached to them in an index file
+(e.g. `src/traces/scatter/index.js`). The trace modules are "registered" undo the `Registry` object
+(found in [`src/registry.js`](https://github.com/plotly/plotly.js/blob/master/src/registry.js)) using
+`Plotly.register` (as done in the index files in `dist/`).
+
+The trace module methods are meant to be called as part of loops during subplot-specific
+(e.g. in `plots/cartesian/index.js`) and figure-wide (e.g. in `plots/plots.js`) subroutines.
+That way, the subroutines work no matter which trace modules got registered.
+
+All traces modules set:
+
+- `_module.name`: name of the trace module as used by the trace `type` attribute.
+- `_module.basePlotModule`: base plot (or subplot) module corresponding to the
+  trace type (e.g. `scatter` links to the `Cartesian` base plot module, `scatter3d` links to `gl3d`).
+- `_module.attributes`: JSON-serializable object of attribute declarations.
+  This object is used to generate the plot-schema JSON.
+- `_module.supplyDefaults`: Takes in input trace settings and coerces them into "full" settings
+  under `gd._fullData`. This one is called during the figure-wide `Plots.supplyDefaults` routine.
+  Note that the `supplyDefaults` method performance should scale with the number of attributes (**not** the
+  number of data points - so it should not loop over any data arrays).
+- `_module.calc`: Converts inputs data into "calculated" (or sanitized) data. This one is called during
+  the figure-wide `Plots.doCalcdata` routine. The `calc` method is allowed to
+  scale with the number of data points and is in general more costly than `supplyDefaults`.
+  Please note that some edit pathways skip `Plots.doCalcdata` (as determined by the
+  `editType` flags in the attributes files).
+- `_module.plot`: Draws the trace on screen. This one is called by the defined `basePlotModule`.
+
+Other methods used by some trace modules:
+
+- `_module.categories`: list of string identifiers used to group traces by behavior. Traces that
+   have a given category can then be detected using [`Registry.traceIs`](https://github.com/plotly/plotly.js/blob/8f049fddbac0ca0382816984b8526857e9714fe6/src/registry.js#L129-L155)
+- `_module.layoutAttributes`: JSON-serializable object of attribute declarations
+  coerced in the layout (e.g. `barmode` for `bar` traces)
+- `_module.supplyLayoutDefaults`: Defaults logic for layout attributes.
+- `_module.crossTraceDefaults`: Defaults logic that depends on input setting of multiple traces.
+- `_module.crossTraceCalc`: Computations that depend on the data of multiple traces.
+- `_module.colorbar`: Defines the colorbar appearance for traces that support it.
+- `_module.hoverPoints`: Point-picking logic called during hover.
+- `_module.selectPoints`: Polygon-containing logic called during selections.
+- `_module.style`: Sometimes split from `_module.plot` where `_module.plot` only
+  draws the elements and `_module.style` styles them.
+- `_module.styleOnSelect`: Optimization of `_module.style` called during
+  selections.
+- `_module.convert`: Sometimes separated from `_module.plot` or `_module.calc` to convert the
+  plotly.js settings to another framework e.g. to `gl-plot3d` for `gl3d` traces, to
+  `mapbox-gl` from `mapbox` traces. This split can make the logic easier to test.
+  If you make a `convert`, you should call it from either `calc` or `plot`.
 
 ## Coding style
 

package-lock.json

@@ -88,7 +88,7 @@
     "gl-select-box": "^1.0.3",
     "gl-spikes2d": "^1.0.2",
     "gl-streamtube3d": "^1.4.0",
-    "gl-surface3d": "^1.4.6",
+    "gl-surface3d": "^1.5.0",
     "gl-text": "^1.1.8",
     "glslify": "^7.0.0",
     "has-hover": "^1.0.1",

package.json

@@ -11,7 +11,6 @@
 var saneTopojson = require('sane-topojson');
 
 
-// package version injected by `npm run preprocess`
-exports.version = '1.52.3';
+exports.version = require('../version').version;
 
 exports.topojson = saneTopojson;

src/assets/geo_assets.js

@@ -8,8 +8,7 @@
 
 'use strict';
 
-// package version injected by `npm run preprocess`
-exports.version = '1.52.3';
+exports.version = require('./version').version;
 
 // inject promise polyfill
 require('es6-promise').polyfill();

src/core.js

@@ -11,16 +11,18 @@
 var isNumeric = require('fast-isnumeric');
 
 var plotApi = require('./plot_api');
+var plots = require('../plots/plots');
 var Lib = require('../lib');
 
 var helpers = require('../snapshot/helpers');
 var toSVG = require('../snapshot/tosvg');
 var svgToImg = require('../snapshot/svgtoimg');
+var version = require('../version').version;
 
 var attrs = {
     format: {
         valType: 'enumerated',
-        values: ['png', 'jpeg', 'webp', 'svg'],
+        values: ['png', 'jpeg', 'webp', 'svg', 'full-json'],
         dflt: 'png',
         description: 'Sets the format of exported image.'
     },
@@ -170,8 +172,24 @@ function toImage(gd, opts) {
             var width = clonedGd._fullLayout.width;
             var height = clonedGd._fullLayout.height;
 
-            plotApi.purge(clonedGd);
-            document.body.removeChild(clonedGd);
+            function cleanup() {
+                plotApi.purge(clonedGd);
+                document.body.removeChild(clonedGd);
+            }
+
+            if(format === 'full-json') {
+                var json = plots.graphJson(clonedGd, false, 'keepdata', 'object', true, true);
+                json.version = version;
+                json = JSON.stringify(json);
+                cleanup();
+                if(imageDataOnly) {
+                    return resolve(json);
+                } else {
+                    return resolve(helpers.encodeJSON(json));
+                }
+            }
+
+            cleanup();
 
             if(format === 'svg') {
                 if(imageDataOnly) {

src/plot_api/to_image.js

@@ -1018,6 +1018,37 @@ proto.updateFx = function(dragmode, hovermode) {
     scene.fullSceneLayout.hovermode = hovermode;
 };
 
+function flipPixels(pixels, w, h) {
+    for(var i = 0, q = h - 1; i < q; ++i, --q) {
+        for(var j = 0; j < w; ++j) {
+            for(var k = 0; k < 4; ++k) {
+                var a = 4 * (w * i + j) + k;
+                var b = 4 * (w * q + j) + k;
+                var tmp = pixels[a];
+                pixels[a] = pixels[b];
+                pixels[b] = tmp;
+            }
+        }
+    }
+}
+
+function correctRGB(pixels, w, h) {
+    for(var i = 0; i < h; ++i) {
+        for(var j = 0; j < w; ++j) {
+            var k = 4 * (w * i + j);
+
+            var a = pixels[k + 3]; // alpha
+            if(a > 0) {
+                var q = 255 / a;
+
+                for(var l = 0; l < 3; ++l) { // RGB
+                    pixels[k + l] = Math.min(q * pixels[k + l], 255);
+                }
+            }
+        }
+    }
+}
+
 proto.toImage = function(format) {
     var scene = this;
 
@@ -1036,17 +1067,8 @@ proto.toImage = function(format) {
 
     var pixels = new Uint8Array(w * h * 4);
     gl.readPixels(0, 0, w, h, gl.RGBA, gl.UNSIGNED_BYTE, pixels);
-
-    // Flip pixels
-    for(var j = 0, k = h - 1; j < k; ++j, --k) {
-        for(var i = 0; i < w; ++i) {
-            for(var l = 0; l < 4; ++l) {
-                var tmp = pixels[4 * (w * j + i) + l];
-                pixels[4 * (w * j + i) + l] = pixels[4 * (w * k + i) + l];
-                pixels[4 * (w * k + i) + l] = tmp;
-            }
-        }
-    }
+    flipPixels(pixels, w, h);
+    correctRGB(pixels, w, h);
 
     var canvas = document.createElement('canvas');
     canvas.width = w;

src/plots/gl3d/scene.js

@@ -2037,9 +2037,10 @@ plots.didMarginChange = function(margin0, margin1) {
  *      keepall: keep data and src
  * @param {String} output If you specify 'object', the result will not be stringified
  * @param {Boolean} useDefaults If truthy, use _fullLayout and _fullData
+ * @param {Boolean} includeConfig If truthy, include _context
  * @returns {Object|String}
  */
-plots.graphJson = function(gd, dataonly, mode, output, useDefaults) {
+plots.graphJson = function(gd, dataonly, mode, output, useDefaults, includeConfig) {
     // if the defaults aren't supplied yet, we need to do that...
     if((useDefaults && dataonly && !gd._fullData) ||
             (useDefaults && !dataonly && !gd._fullLayout)) {
@@ -2050,26 +2051,29 @@ plots.graphJson = function(gd, dataonly, mode, output, useDefaults) {
     var layout = (useDefaults) ? gd._fullLayout : gd.layout;
     var frames = (gd._transitionData || {})._frames;
 
-    function stripObj(d) {
+    function stripObj(d, keepFunction) {
         if(typeof d === 'function') {
-            return null;
+            return keepFunction ? '_function_' : null;
         }
         if(Lib.isPlainObject(d)) {
             var o = {};
-            var v, src;
-            for(v in d) {
+            var src;
+            Object.keys(d).sort().forEach(function(v) {
                 // remove private elements and functions
                 // _ is for private, [ is a mistake ie [object Object]
-                if(typeof d[v] === 'function' ||
-                        ['_', '['].indexOf(v.charAt(0)) !== -1) {
-                    continue;
+                if(['_', '['].indexOf(v.charAt(0)) !== -1) return;
+
+                // if a function, add if necessary then move on
+                if(typeof d[v] === 'function') {
+                    if(keepFunction) o[v] = '_function';
+                    return;
                 }
 
                 // look for src/data matches and remove the appropriate one
                 if(mode === 'keepdata') {
                     // keepdata: remove all ...src tags
                     if(v.substr(v.length - 3) === 'src') {
-                        continue;
+                        return;
                     }
                 } else if(mode === 'keepstream') {
                     // keep sourced data if it's being streamed.
@@ -2078,26 +2082,26 @@ plots.graphJson = function(gd, dataonly, mode, output, useDefaults) {
                     src = d[v + 'src'];
                     if(typeof src === 'string' && src.indexOf(':') > 0) {
                         if(!Lib.isPlainObject(d.stream)) {
-                            continue;
+                            return;
                         }
                     }
                 } else if(mode !== 'keepall') {
                     // keepref: remove sourced data but only
                     // if the source tag is well-formed
                     src = d[v + 'src'];
                     if(typeof src === 'string' && src.indexOf(':') > 0) {
-                        continue;
+                        return;
                     }
                 }
 
                 // OK, we're including this... recurse into it
-                o[v] = stripObj(d[v]);
-            }
+                o[v] = stripObj(d[v], keepFunction);
+            });
             return o;
         }
 
         if(Array.isArray(d)) {
-            return d.map(stripObj);
+            return d.map(function(x) {return stripObj(x, keepFunction);});
         }
 
         if(Lib.isTypedArray(d)) {
@@ -2126,6 +2130,8 @@ plots.graphJson = function(gd, dataonly, mode, output, useDefaults) {
 
     if(frames) obj.frames = stripObj(frames);
 
+    if(includeConfig) obj.config = stripObj(gd._context, true);
+
     return (output === 'object') ? obj : JSON.stringify(obj);
 };
 

src/plots/plots.js

@@ -51,7 +51,7 @@ function downloadImage(gd, opts) {
         var promise = toImage(gd, opts);
 
         var filename = opts.filename || gd.fn || 'newplot';
-        filename += '.' + opts.format;
+        filename += '.' + opts.format.replace('-', '.');
 
         promise.then(function(result) {
             if(_gd) _gd._snapshotInProgress = false;

src/snapshot/download.js

@@ -36,6 +36,10 @@ exports.encodeSVG = function(svg) {
     return 'data:image/svg+xml,' + encodeURIComponent(svg);
 };
 
+exports.encodeJSON = function(json) {
+    return 'data:application/json,' + encodeURIComponent(json);
+};
+
 var DOM_URL = window.URL || window.webkitURL;
 
 exports.createObjectURL = function(blob) {
@@ -49,6 +53,8 @@ exports.revokeObjectURL = function(url) {
 exports.createBlob = function(url, format) {
     if(format === 'svg') {
         return new window.Blob([url], {type: 'image/svg+xml;charset=utf-8'});
+    } else if(format === 'full-json') {
+        return new window.Blob([url], {type: 'application/json;charset=utf-8'});
     } else {
         var binary = fixBinary(window.atob(url));
         return new window.Blob([binary], {type: 'image/' + format});

src/snapshot/helpers.js

@@ -242,7 +242,7 @@ function plot(gd, plotinfo, cdModule, traceLayer, opts, makeOnCompleteCallback)
             var sel = transition(Lib.ensureSingle(bar, 'path'), fullLayout, opts, makeOnCompleteCallback);
             sel
                 .style('vector-effect', 'non-scaling-stroke')
-                .attr('d', 'M' + x0 + ',' + y0 + 'V' + y1 + 'H' + x1 + 'V' + y0 + 'Z')
+                .attr('d', isNaN((x1 - x0) * (y1 - y0)) ? 'M0,0Z' : 'M' + x0 + ',' + y0 + 'V' + y1 + 'H' + x1 + 'V' + y0 + 'Z')
                 .call(Drawing.setClipUrl, plotinfo.layerClipId, gd);
 
             if(!fullLayout.uniformtext.mode && withTransition) {