[WIP] Frame + Animate API

animate-api.md

@@ -0,0 +1,133 @@
+## Top-level Plotly API methods
+
+#### `Plotly.transition(gd, data, layout[, traceIndices[, config]])`
+Transition (eased or abruptly if desired) to a new set of data. Knows nothing about the larger state of transitions and frames; identically a 'transition the plot to look like X over Y ms' command.
+
+**Parameters**:
+- `data`: an *array* of *objects* containing trace data, e.g. `[{x: [1, 2, 3], 'lines.color': 'red'}, {y: [7,8]}]`, mapped to traces.
+- `layout`: layout properties to which to transition, probably mostly just axis ranges
+- `traceIndices`: a mapping between the items of `data` and the trace indices, e.g. `[0, 2]`. If omitted, is inferred from semantics like for `restyle`—which means maybe affecting all traces?
+- `config`: object containing transition configuration, including:
+  - `duration`: duration in ms of transition
+  - `ease`: d3 easing function, e.g. `elastic-in-out`
+  - `delay`: delay until animation; not so useful, just very very easy to pass to d3
+  - `cascade`: transition points in sequence for a nice visual effect. Maybe just leave out. Kind of a common visual effect for eye candy purposes. Very easy. Can leave out if it leads to weird corner cases. See: http://rickyreusser.com/animation-experiments/#object-constancy
+
+**Returns**: promise that resolves when animation begins or rejects if config is invalid.
+
+**Events**:
+- `plotly_starttransition`
+- `plotly_endtransition`
+
+<hr>
+
+#### `Plotly.animate(gd, frame[, config])`
+Transition to a keyframe. Animation sequence is:
+
+1. Compute the requested frame
+2. Separate animatable and non-animatable properties into separate objects
+3. Mark exactly what needs to happen. This includes transitions vs. non-animatable properties, whether the axis needs to be redrawn (`needsRelayout`?), and any other optimizations that seem relevant. Since for some cases very simple updates may be coming through at up to 60fps, cutting out work here could be fairly important.
+
+**Parameters**:
+- `frame`: name of the frame to which to animate
+- `config`: see `.transition`.
+
+**Returns**: promise that resolves when animation begins or rejects if config is invalid.
+
+**Events**:
+- `plotly_startanimation`
+- `plotly_endanimation`
+
+<hr>
+
+#### `Plotly.addFrames(gd, frames[, frameIndices])`
+Add or overwrite frames. New frames are appended to current frame list.
+
+**Parameters**
+- `frames`: an array of objects containing any of `name`, `data`, `layout` and `traceIndices` fields as specified above. If no name is provided, a unique name (e.g. `frame 7`) will be assigned. If the frame already exists, then its definition is overwritten.
+- `frameIndices`: optional array of indices at which to insert the given frames. If indices are omitted or a specific index is falsey, then frame is appended.
+
+**Returns**: Promise that resolves on completion. (In this case, that's synchronously and mainly for the sake of API consistency.)
+
+<hr>
+
+#### `Plotly.deleteFrames(gd, frameIndices)`
+Remove frames by frame index.
+
+**Parameters**:
+- `frameIndices`: an array of integer indices of the frames to be removed.
+
+**Returns**: Promise that resolves on completion (which here means synchronously).
+
+<hr>
+
+## Frame definition
+
+Frames are defined similarly to mirror the input format, *not* that of `Plotly.restyle`. The easiest way to explain seems to be via an example that touches all features:
+
+```json
+{
+  "data": [{
+    "x": [1, 2, 3],
+    "y": [4, 5, 6],
+    "identifiers": ["China", "Pakistan", "Australia"],
+    "lines": {
+      "color": "red"
+    }
+  }, {
+    "x": [1, 2, 3],
+    "y": [3, 8, 9],
+    "markers": {
+      "color": "red"
+    }
+  }],
+  "layout": {
+    "slider": {
+      "visible": true,
+      "plotly_method": "animate",
+      "args": ["$value", {"duration": 500}]
+    },
+    "slider2": {
+      "visible": true,
+      "plotly_method": "animate",
+      "args": ["$value", {"duration": 500}]
+    }
+  },
+  "frames": [
+    {
+      "name": "base",
+      "y": [4, 5, 7],
+      "identifiers": ["China", "Pakistan", "Australia"],
+    }, {
+      "name": "1960",
+      "data": [{
+        "y": [1, 2, 3],
+        "identifiers": ["China", "Pakistan", "Australia"],
+      }],
+      "layout": {
+        "xaxis": {"range": [7, 3]},
+        "yaxis": {"range": [0, 5]}
+      },
+      "baseFrame": "base",
+      "traceIndices": [0]
+    }, {
+      "name": "1965",
+      "data": [{
+        "y": [5, 3, 2],
+        "identifiers": ["China", "Pakistan", "Australia"],
+      }],
+      "layout": {
+        "xaxis": {"range": [7, 3]},
+        "yaxis": {"range": [0, 5]}
+      },
+      "baseFrame": "base",
+      "traceIndices": [0]
+    }
+  ]
+}
+```
+
+Notes on JSON:
+- `identifiers` is used as a d3 `key` argument.
+- `baseFrame` is merged… recursively? non-recursively? We'll see. Not a crucial implementation choice.
+- `frames` seems maybe best stored at top level. Or maybe best on the object. If on the object, `Plotly.plot` would have to be variadic (probably), accepting `Plotly.plot(gd, data, layout[, frames], config)`. That's backward-compatible but a bit ugly. If not on the object, then it would have to be shoved into `layout` (except how, because it's really awkward place in `layout`.

build/plotcss.js

@@ -1,6 +1,5 @@
 'use strict';
 
-var Plotly = require('../src/plotly');
 var rules = {
     "X,X div": "font-family:'Open Sans', verdana, arial, sans-serif;margin:0;padding:0;",
     "X input,X button": "font-family:'Open Sans', verdana, arial, sans-serif;",
@@ -54,9 +53,4 @@ var rules = {
     "Y .notifier-close:hover": "color:#444;text-decoration:none;cursor:pointer;"
 };
 
-for(var selector in rules) {
-    var fullSelector = selector.replace(/^,/,' ,')
-        .replace(/X/g, '.js-plotly-plot .plotly')
-        .replace(/Y/g, '.plotly-notifier');
-    Plotly.Lib.addStyleRule(fullSelector, rules[selector]);
-}
+module.exports = rules;

src/components/colorbar/has_colorbar.js

@@ -9,10 +9,9 @@
 
 'use strict';
 
+var Lib = require('../../lib');
+
 
 module.exports = function hasColorbar(container) {
-    return (
-        typeof container.colorbar === 'object' &&
-        container.colorbar !== null
-    );
+    return Lib.isPlainObject(container.colorbar);
 };

src/components/colorscale/has_colorscale.js

@@ -33,12 +33,12 @@ module.exports = function hasColorscale(trace, containerStr) {
     }
 
     return (
-        (typeof container === 'object' && container !== null) && (
+        Lib.isPlainObject(container) && (
             isArrayWithOneNumber ||
             container.showscale === true ||
             (isNumeric(container.cmin) && isNumeric(container.cmax)) ||
             isValidScale(container.colorscale) ||
-            (typeof container.colorbar === 'object' && container.colorbar !== null)
+            Lib.isPlainObject(container.colorbar)
         )
     );
 };

src/components/dragelement/index.js

@@ -86,7 +86,7 @@ dragElement.init = function init(options) {
 
         if(options.prepFn) options.prepFn(e, startX, startY);
 
-        dragCover = coverSlip();
+        dragCover = coverSlip(gd);
 
         dragCover.onmousemove = onMove;
         dragCover.onmouseup = onDone;
@@ -139,7 +139,7 @@ dragElement.init = function init(options) {
         if(options.doneFn) options.doneFn(gd._dragged, numClicks);
 
         if(!gd._dragged) {
-            var e2 = document.createEvent('MouseEvents');
+            var e2 = gd._document.createEvent('MouseEvents');
             e2.initEvent('click', true, true);
             initialTarget.dispatchEvent(e2);
         }
@@ -159,8 +159,8 @@ dragElement.init = function init(options) {
     options.element.style.pointerEvents = 'all';
 };
 
-function coverSlip() {
-    var cover = document.createElement('div');
+function coverSlip(gd) {
+    var cover = gd._document.createElement('div');
 
     cover.className = 'dragcover';
     var cStyle = cover.style;
@@ -172,7 +172,7 @@ function coverSlip() {
     cStyle.zIndex = 999999999;
     cStyle.background = 'none';
 
-    document.body.appendChild(cover);
+    gd._document.body.appendChild(cover);
 
     return cover;
 }

src/components/drawing/index.js

@@ -46,16 +46,62 @@ drawing.setRect = function(s, x, y, w, h) {
     s.call(drawing.setPosition, x, y).call(drawing.setSize, w, h);
 };
 
-drawing.translatePoints = function(s, xa, ya) {
-    s.each(function(d) {
+drawing.translatePoints = function(s, xa, ya, trace, transitionConfig, joinDirection) {
+    var size;
+
+    var hasTransition = transitionConfig && (transitionConfig || {}).duration > 0;
+
+    if(hasTransition) {
+        size = s.size();
+    }
+
+    s.each(function(d, i) {
         // put xp and yp into d if pixel scaling is already done
         var x = d.xp || xa.c2p(d.x),
             y = d.yp || ya.c2p(d.y),
             p = d3.select(this);
         if(isNumeric(x) && isNumeric(y)) {
             // for multiline text this works better
-            if(this.nodeName === 'text') p.attr('x', x).attr('y', y);
-            else p.attr('transform', 'translate(' + x + ',' + y + ')');
+            if(this.nodeName === 'text') {
+                p.attr('x', x).attr('y', y);
+            } else {
+                if(hasTransition) {
+                    var trans;
+                    if(!joinDirection) {
+                        trans = p.transition()
+                        .delay(transitionConfig.delay + transitionConfig.cascade / size * i)
+                        .duration(transitionConfig.duration)
+                        .ease(transitionConfig.ease)
+                        .attr('transform', 'translate(' + x + ',' + y + ')');
+
+                        if(trace) {
+                            trans.call(drawing.pointStyle, trace);
+                        }
+                    } else if(joinDirection === -1) {
+                        trans = p.style('opacity', 1)
+                        .transition()
+                            .duration(transitionConfig.duration)
+                            .ease(transitionConfig.ease)
+                            .style('opacity', 0)
+                            .remove();
+                    } else if(joinDirection === 1) {
+                        trans = p.attr('transform', 'translate(' + x + ',' + y + ')');
+
+                        if(trace) {
+                            trans.call(drawing.pointStyle, trace);
+                        }
+
+                        trans.style('opacity', 0)
+                        .transition()
+                            .duration(transitionConfig.duration)
+                            .ease(transitionConfig.ease)
+                            .style('opacity', 1);
+                    }
+
+                } else {
+                    p.attr('transform', 'translate(' + x + ',' + y + ')');
+                }
+            }
         }
         else p.remove();
     });