Introduce cartesian axis breaks

src/plots/cartesian/autorange.js

@@ -95,14 +95,26 @@ function getAutoRange(gd, ax) {
     // don't allow padding to reduce the data to < 10% of the length
     var minSpan = axLen / 10;
 
+    // find axis breaks in [v0,v1] and compute its length in value space
+    var calcBreaksLength = function(v0, v1) {
+        var lBreaks = 0;
+        if(ax.breaks) {
+            var breaksOut = ax.locateBreaks(v0, v1);
+            for(var i = 0; i < breaksOut.length; i++) {
+                lBreaks += (breaksOut[i].max - breaksOut[i].min);
+            }
+        }
+        return lBreaks;
+    };
+
     var mbest = 0;
     var minpt, maxpt, minbest, maxbest, dp, dv;
 
     for(i = 0; i < minArray.length; i++) {
         minpt = minArray[i];
         for(j = 0; j < maxArray.length; j++) {
             maxpt = maxArray[j];
-            dv = maxpt.val - minpt.val;
+            dv = maxpt.val - minpt.val - calcBreaksLength(minpt.val, maxpt.val);
             if(dv > 0) {
                 dp = axLen - getPad(minpt) - getPad(maxpt);
                 if(dp > minSpan) {
@@ -167,7 +179,7 @@ function getAutoRange(gd, ax) {
         }
 
         // in case it changed again...
-        mbest = (maxbest.val - minbest.val) /
+        mbest = (maxbest.val - minbest.val - calcBreaksLength(minpt.val, maxpt.val)) /
             (axLen - getPad(minbest) - getPad(maxbest));
 
         newRange = [

src/plots/cartesian/axes.js

@@ -526,7 +526,8 @@ axes.prepTicks = function(ax) {
         // have explicit tickvals without tick text
         if(ax.tickmode === 'array') nt *= 100;
 
-        axes.autoTicks(ax, Math.abs(rng[1] - rng[0]) / nt);
+        axes.autoTicks(ax, (Math.abs(rng[1] - rng[0]) - (ax._lBreaks || 0)) / nt);
+
         // check for a forced minimum dtick
         if(ax._minDtick > 0 && ax.dtick < ax._minDtick * 2) {
             ax.dtick = ax._minDtick;
@@ -608,6 +609,19 @@ axes.calcTicks = function calcTicks(ax) {
         tickVals.pop();
     }
 
+    if(ax.breaks) {
+        // remove ticks falling inside breaks
+        tickVals = tickVals.filter(function(d) {
+            return ax.maskBreaks(d.value) !== BADNUM;
+        });
+
+        // TODO what to do with "overlapping" ticks?
+        var tf2 = ax.tickfont ? 1.5 * ax.tickfont.size : 0;
+        tickVals = tickVals.filter(function(d, i, self) {
+            return !(i && Math.abs(ax.c2p(d.value) - ax.c2p(self[i - 1].value)) < tf2);
+        });
+    }
+
     // save the last tick as well as first, so we can
     // show the exponent only on the last one
     ax._tmax = (tickVals[tickVals.length - 1] || {}).value;
@@ -670,6 +684,13 @@ function arrayTicks(ax) {
 
     if(j < vals.length) ticksOut.splice(j, vals.length - j);
 
+    if(ax.breaks) {
+        // remove ticks falling inside breaks
+        ticksOut = ticksOut.filter(function(d) {
+            return ax.maskBreaks(d.x) !== BADNUM;
+        });
+    }
+
     return ticksOut;
 }
 
@@ -718,6 +739,8 @@ axes.autoTicks = function(ax, roughDTick) {
         // being > half of the final unit - so precalculate twice the rough val
         var roughX2 = 2 * roughDTick;
 
+        // TODO find way to have 'better' first tick on axes with breaks
+
         if(roughX2 > ONEAVGYEAR) {
             roughDTick /= ONEAVGYEAR;
             base = getBase(10);
@@ -776,6 +799,9 @@ axes.autoTicks = function(ax, roughDTick) {
         ax.tick0 = 0;
         base = getBase(10);
         ax.dtick = roundDTick(roughDTick, base, roundBase10);
+
+        // TODO having tick0 = 0 being insider a breaks does not seem
+        // to matter ...
     }
 
     // prevent infinite loops
@@ -966,7 +992,7 @@ axes.tickText = function(ax, x, hover, noSuffixPrefix) {
 
     if(arrayMode && Array.isArray(ax.ticktext)) {
         var rng = Lib.simpleMap(ax.range, ax.r2l);
-        var minDiff = Math.abs(rng[1] - rng[0]) / 10000;
+        var minDiff = (Math.abs(rng[1] - rng[0]) - (ax._lBreaks || 0)) / 10000;
 
         for(i = 0; i < ax.ticktext.length; i++) {
             if(Math.abs(x - tickVal2l(ax.tickvals[i])) < minDiff) break;
@@ -2828,6 +2854,7 @@ axes.shouldShowZeroLine = function(gd, ax, counterAxis) {
         (rng[0] * rng[1] <= 0) &&
         ax.zeroline &&
         (ax.type === 'linear' || ax.type === '-') &&
+        !(ax.breaks && ax.maskBreaks(0) === BADNUM) &&
         (
             clipEnds(ax, 0) ||
             !anyCounterAxLineAtZero(gd, ax, counterAxis, rng) ||

src/plots/cartesian/axis_defaults.js

@@ -11,6 +11,8 @@
 var Registry = require('../../registry');
 var Lib = require('../../lib');
 
+var handleArrayContainerDefaults = require('../array_container_defaults');
+
 var layoutAttributes = require('./layout_attributes');
 var handleTickValueDefaults = require('./tick_value_defaults');
 var handleTickMarkDefaults = require('./tick_mark_defaults');
@@ -19,6 +21,8 @@ var handleCategoryOrderDefaults = require('./category_order_defaults');
 var handleLineGridDefaults = require('./line_grid_defaults');
 var setConvert = require('./set_convert');
 
+var ONEDAY = require('../../constants/numerical').ONEDAY;
+
 /**
  * options: object containing:
  *
@@ -117,5 +121,68 @@ module.exports = function handleAxisDefaults(containerIn, containerOut, coerce,
         }
     }
 
+    // TODO
+    // - does this make sense for 'log', 'category' and 'multicategory' axis types ??
+
+    var breaks = containerIn.breaks;
+    if(Array.isArray(breaks) && breaks.length) {
+        handleArrayContainerDefaults(containerIn, containerOut, {
+            name: 'breaks',
+            inclusionAttr: 'enabled',
+            handleItemDefaults: breaksDefaults
+        });
+        setConvert(containerOut, layoutOut);
+    }
+
     return containerOut;
 };
+
+function breaksDefaults(itemIn, itemOut, containerOut) {
+    function coerce(attr, dflt) {
+        return Lib.coerce(itemIn, itemOut, layoutAttributes.breaks, attr, dflt);
+    }
+
+    var enabled = coerce('enabled');
+
+    if(enabled) {
+        var isDateAxis = containerOut.type === 'date';
+
+        var bnds = coerce('bounds');
+
+        if(bnds && bnds.length >= 2) {
+            if(bnds.length > 2) {
+                itemOut.bounds = itemOut.bounds.slice(0, 2);
+            }
+
+            if(containerOut.autorange === false) {
+                var rng = containerOut.range;
+
+                // if bounds are bigger than the (set) range, disable break
+                if(rng[0] < rng[1]) {
+                    if(bnds[0] < rng[0] && bnds[1] > rng[1]) {
+                        itemOut.enabled = false;
+                        return;
+                    }
+                } else if(bnds[0] > rng[0] && bnds[1] < rng[1]) {
+                    itemOut.enabled = false;
+                    return;
+                }
+            }
+
+            if(isDateAxis) {
+                coerce('pattern');
+            }
+        } else {
+            var values = coerce('values');
+
+            if(values && values.length) {
+                coerce('dvalue', isDateAxis ? ONEDAY : 1);
+            } else {
+                itemOut.enabled = false;
+                return;
+            }
+        }
+
+        coerce('operation');
+    }
+}

src/plots/cartesian/dragbox.js

@@ -986,10 +986,20 @@ function zoomAxRanges(axList, r0Fraction, r1Fraction, updates, linkedAxes) {
         var axi = axList[i];
         if(axi.fixedrange) continue;
 
-        var axRangeLinear0 = axi._rl[0];
-        var axRangeLinearSpan = axi._rl[1] - axRangeLinear0;
-        updates[axi._name + '.range[0]'] = axi.l2r(axRangeLinear0 + axRangeLinearSpan * r0Fraction);
-        updates[axi._name + '.range[1]'] = axi.l2r(axRangeLinear0 + axRangeLinearSpan * r1Fraction);
+        if(axi.breaks) {
+            if(axi._id.charAt(0) === 'y') {
+                updates[axi._name + '.range[0]'] = axi.l2r(axi.p2l((1 - r0Fraction) * axi._length));
+                updates[axi._name + '.range[1]'] = axi.l2r(axi.p2l((1 - r1Fraction) * axi._length));
+            } else {
+                updates[axi._name + '.range[0]'] = axi.l2r(axi.p2l(r0Fraction * axi._length));
+                updates[axi._name + '.range[1]'] = axi.l2r(axi.p2l(r1Fraction * axi._length));
+            }
+        } else {
+            var axRangeLinear0 = axi._rl[0];
+            var axRangeLinearSpan = axi._rl[1] - axRangeLinear0;
+            updates[axi._name + '.range[0]'] = axi.l2r(axRangeLinear0 + axRangeLinearSpan * r0Fraction);
+            updates[axi._name + '.range[1]'] = axi.l2r(axRangeLinear0 + axRangeLinearSpan * r1Fraction);
+        }
     }
 
     // zoom linked axes about their centers
@@ -1003,10 +1013,17 @@ function dragAxList(axList, pix) {
     for(var i = 0; i < axList.length; i++) {
         var axi = axList[i];
         if(!axi.fixedrange) {
-            axi.range = [
-                axi.l2r(axi._rl[0] - pix / axi._m),
-                axi.l2r(axi._rl[1] - pix / axi._m)
-            ];
+            if(axi.breaks) {
+                axi.range = [
+                    axi.l2r(axi._rl[0] - (axi.p2l(pix) - axi.p2l(0))),
+                    axi.l2r(axi._rl[1] - (axi.p2l(axi._length + pix) - axi.p2l(axi._length)))
+                ];
+            } else {
+                axi.range = [
+                    axi.l2r(axi._rl[0] - pix / axi._m),
+                    axi.l2r(axi._rl[1] - pix / axi._m)
+                ];
+            }
         }
     }
 }

src/plots/cartesian/layout_attributes.js

@@ -248,6 +248,135 @@ module.exports = {
             'Moreover, note that matching axes must have the same `type`.'
         ].join(' ')
     },
+
+    breaks: templatedArray('break', {
+        enabled: {
+            valType: 'boolean',
+            role: 'info',
+            dflt: true,
+            editType: 'calc',
+            description: [
+                'Determines whether this axis break is enabled or disabled.'
+            ].join(' ')
+        },
+
+        bounds: {
+            valType: 'info_array',
+            role: 'info',
+            items: [
+                {valType: 'any', editType: 'calc'},
+                {valType: 'any', editType: 'calc'}
+            ],
+            editType: 'calc',
+            description: [
+                'Sets the lower and upper bounds of this axis break.',
+                'Can be used with `operation` to determine the behavior at the bounds.',
+                'On *date* axes, it can be used `pattern`.'
+            ].join(' ')
+        },
+
+        pattern: {
+            valType: 'enumerated',
+            // TODO could add '%H:%M:%S'
+            values: ['%w', '%H', ''],
+            dflt: '',
+            role: 'info',
+            editType: 'calc',
+            description: [
+                'Only coerced on *date* axes.',
+                'Determines a pattern on the time line that generates breaks.',
+                'If *%w* - Sunday-based weekday as a decimal number [0, 6].',
+                'If *%H* - hour (24-hour clock) as a decimal number [0, 23].',
+                'These are the same directive as in `tickformat`, see',
+                'https://github.com/d3/d3-time-format#locale_format',
+                'for more info.',
+                'Examples:',
+                '- { pattern: \'%w\', bounds: [6, 0], operation: \'[]\' }',
+                '  breaks from Saturday to Monday (i.e. skips the weekends).',
+                '- { pattern: \'%H\', bounds: [17, 8] }',
+                '  breaks from 5pm to 8am (i.e. skips non-work hours).'
+            ].join(' ')
+        },
+
+        values: {
+            valType: 'info_array',
+            freeLength: true,
+            role: 'info',
+            editType: 'calc',
+            items: {
+                valType: 'any',
+                editType: 'calc'
+            },
+            description: [
+                'Sets the coordinate values corresponding to the breaks.',
+                'An alternative to `bounds`.',
+                'Use `dvalue` to set the spread of the values along the axis.'
+            ].join(' ')
+        },
+        dvalue: {
+            // TODO could become 'any' to add support for 'months', 'years'
+            valType: 'number',
+            role: 'info',
+            editType: 'calc',
+            min: 0,
+            description: [
+                'Sets the spread of each `values` item.',
+                'For *linear* axes, the default is *1*.',
+                'For *date* axes, the default is one day in milliseconds.'
+            ].join(' ')
+        },
+
+        operation: {
+            valType: 'enumerated',
+            values: ['[]', '()', '[)', '(]'],
+            dflt: '()',
+            role: 'info',
+            editType: 'calc',
+            description: [
+                'Determines if we include or not the bound values within the break.',
+                'Closed interval bounds (i.e. starting with *[* or ending with *]*)',
+                'include the bound value within the break and thus make coordinates',
+                'equal to the bound disappear.',
+                'Open interval bounds (i.e. starting with *(* or ending with *)*)',
+                'does not include the bound value within the break and thus keep coordinates',
+                'equal to the bound on the axis.'
+            ].join(' ')
+        },
+
+        /*
+        gap: {
+            valType: 'number',
+            min: 0,
+            dflt: 0, // for *date* axes, maybe something else for *linear*
+            editType: 'calc',
+            role: 'info',
+            description: [
+                'Sets the gap distance between the start and the end of this break.',
+                'Use with `gapmode` to set the unit of measurement.'
+            ].join(' ')
+        },
+        gapmode: {
+            valType: 'enumerated',
+            values: ['pixels', 'fraction'],
+            dflt: 'pixels',
+            editType: 'calc',
+            role: 'info',
+            description: [
+                'Determines if the `gap` value corresponds to a pixel length',
+                'or a fraction of the plot area.'
+            ].join(' ')
+        },
+        */
+
+        // To complete https://github.com/plotly/plotly.js/issues/4210
+        // we additionally need `gap` and make this work on *linear*, and
+        // possibly all other cartesian axis types. We possibly would also need
+        // some style attributes controlling the zig-zag on the corresponding
+        // axis.
+
+        editType: 'calc'
+    }),
+
     // ticks
     tickmode: {
         valType: 'enumerated',