add domainpad for pixel spacing inside axis domains

`domain` is a plot fraction, so the gap it leaves between subplots grows and
shrinks with the figure while a subplot title does not. domainpad reserves a
fixed number of pixels inside the domain edges instead, resolved at draw time.

Applied in ax.setScale to _offset and _length rather than to ax.domain, so the
domain keeps meaning what the user typed and anything referenced to
`<axis> domain` follows the padded area without new drawing code.

Along with it:

- scattergl, splom and the rangeslider rebuilt the plot rect from `domain` and
  so did not see the pad; they now read _offset and _length
- pads that do not fit are backed off together, since setScale already throws
  on a negative length
- updateDomain scales the padded length rather than the raw span, so a
  scaleanchor ratio stays exact when the constraint shrinks a padded axis

Refs #7835

Author: SharadhNaidu

src/components/rangeslider/draw.js

@@ -100,11 +100,13 @@ module.exports = function(gd) {
         // update range slider dimensions
 
         var gs = fullLayout._size;
-        var domain = axisOpts.domain;
 
-        opts._width = gs.w * (domain[1] - domain[0]);
+        // the slider has to line up with the plot area above it, so take its width
+        // and position from the axis rather than working them out from `domain`
+        // again - `domainpad` moves the axis without touching `domain`
+        opts._width = axisOpts._length;
 
-        var x = Math.round(gs.l + (gs.w * domain[0]));
+        var x = Math.round(axisOpts._offset);
 
         var y = Math.round(
             gs.t + gs.h * (1 - axisOpts._counterDomainMin) +

src/plots/cartesian/constraints.js

@@ -565,7 +565,7 @@ exports.enforce = function enforce(gd) {
                         var getPadMin = autorange.makePadFn(fullLayout, ax, 0);
                         var getPadMax = autorange.makePadFn(fullLayout, ax, 1);
 
-                        updateDomain(ax, factor);
+                        updateDomain(ax, factor, fullLayout);
                         var m = Math.abs(ax._m);
                         var extremes = autorange.concatExtremes(gd, ax);
                         var minArray = extremes.min;
@@ -596,7 +596,7 @@ exports.enforce = function enforce(gd) {
                             [rangeMin, rangeMax] : [rangeMax, rangeMin];
                     }
 
-                    updateDomain(ax, factor);
+                    updateDomain(ax, factor, fullLayout);
                 }
             }
         }
@@ -633,14 +633,41 @@ exports.clean = function clean(gd, ax) {
     }
 };
 
-function updateDomain(ax, factor) {
+// `domainpad` in domain fractions rather than pixels, which is the unit
+// everything around the constraint solve is expressed in.
+function domainPadFraction(ax, fullLayout) {
+    var pad = ax.domainpad;
+    if(!pad) return 0;
+
+    var gs = fullLayout._size;
+    return ax._id.charAt(0) === 'y' ?
+        ((pad.top || 0) + (pad.bottom || 0)) / gs.h :
+        ((pad.left || 0) + (pad.right || 0)) / gs.w;
+}
+
+function updateDomain(ax, factor, fullLayout) {
     var inputDomain = ax._inputDomain;
-    var centerFraction = FROM_BL[ax.constraintoward];
-    var center = inputDomain[0] + (inputDomain[1] - inputDomain[0]) * centerFraction;
+    var inputSpan = inputDomain[1] - inputDomain[0];
+    var center = inputDomain[0] + inputSpan * FROM_BL[ax.constraintoward];
+
+    // We have to divide the axis' drawn length by `factor`. With no padding that
+    // length is the domain span, so dividing the span does it. `domainpad` breaks
+    // the equivalence by taking a fixed number of pixels off the ends: the drawn
+    // length is (span - padding), and only that part scales. Divide it and add the
+    // padding back. If the padding covers the whole domain there is nothing left to
+    // scale, so fall through to the plain behaviour and let setScale clamp it.
+    var padFraction = domainPadFraction(ax, fullLayout);
+    var drawnSpan = inputSpan - padFraction;
+    var newSpan = drawnSpan > 0 ?
+        drawnSpan / factor + padFraction :
+        inputSpan / factor;
+
+    // grow or shrink about whichever edge or centre `constraintoward` asked for
+    var scale = newSpan / inputSpan;
 
     ax.domain = ax._input.domain = [
-        center + (inputDomain[0] - center) / factor,
-        center + (inputDomain[1] - center) / factor
+        center + (inputDomain[0] - center) * scale,
+        center + (inputDomain[1] - center) * scale
     ];
     ax.setScale();
 }

src/plots/cartesian/layout_attributes.js

@@ -1205,6 +1205,47 @@ module.exports = {
             'Sets the domain of this axis (in plot fraction).'
         ].join(' ')
     },
+    domainpad: {
+        left: {
+            valType: 'number',
+            min: 0,
+            dflt: 0,
+            editType: 'plot',
+            description: 'Pixels of space to reserve inside the left edge of the domain. Ignored on y axes.'
+        },
+        right: {
+            valType: 'number',
+            min: 0,
+            dflt: 0,
+            editType: 'plot',
+            description: 'Pixels of space to reserve inside the right edge of the domain. Ignored on y axes.'
+        },
+        top: {
+            valType: 'number',
+            min: 0,
+            dflt: 0,
+            editType: 'plot',
+            description: 'Pixels of space to reserve inside the top edge of the domain. Ignored on x axes.'
+        },
+        bottom: {
+            valType: 'number',
+            min: 0,
+            dflt: 0,
+            editType: 'plot',
+            description: 'Pixels of space to reserve inside the bottom edge of the domain. Ignored on x axes.'
+        },
+        editType: 'plot',
+        description: [
+            'Reserves space inside the edges of `domain`, in pixels.',
+            'Because `domain` is a plot fraction, the space it leaves between subplots',
+            'grows and shrinks with the figure. `domainpad` stays the same size at any',
+            'figure height or width, which is what you want for anything sized in pixels',
+            'such as a subplot title.',
+            'x axes use `left` and `right`, y axes use `top` and `bottom`.',
+            'If the padding asks for more room than the domain has, it is scaled down',
+            'so the subplot keeps a usable size.'
+        ].join(' ')
+    },
     position: {
         valType: 'number',
         min: 0,

src/plots/cartesian/position_defaults.js

@@ -84,6 +84,17 @@ module.exports = function handlePositionDefaults(containerIn, containerOut, coer
         if(domain[0] > domain[1] - 1 / 4096) containerOut.domain = dfltDomain;
         Lib.noneOrAll(containerIn.domain, containerOut.domain, dfltDomain);
 
+        // domainpad reserves pixels inside the domain edges. Only the two sides that
+        // point along this axis mean anything, so we skip the other two rather than
+        // let people set a value that silently does nothing.
+        if(letter === 'x') {
+            coerce('domainpad.left');
+            coerce('domainpad.right');
+        } else {
+            coerce('domainpad.top');
+            coerce('domainpad.bottom');
+        }
+
         // tickmode sync needs an overlaying axis, otherwise
         // we should default it to 'auto'
         if(containerOut.tickmode === 'sync') {

src/plots/cartesian/set_convert.js

@@ -35,6 +35,27 @@ function isValidCategory(v) {
     return v !== null && v !== undefined;
 }
 
+// Smallest plot area `domainpad` may leave behind, matching the floor
+// `doAutoMargin` keeps for margins. Zero would not do: the guard at the end of
+// setScale only rejects lengths below zero, so an exactly-zero length slips
+// through with a slope of 0 and the subplot collapses without saying why.
+var MIN_PADDED_LENGTH = 2;
+
+/*
+ * What fraction of the requested `domainpad` actually fits.
+ *
+ * `domain` is a plot fraction, so the band it covers shrinks with the figure while
+ * the padding does not. Make the figure small enough and the two pads together ask
+ * for more room than the band has. Back both off by the same factor rather than
+ * hand setScale a negative length, which throws - the same way `doAutoMargin`
+ * shrinks margins that no longer fit.
+ */
+function padFactor(wanted, bandLength) {
+    if(wanted <= 0) return 0;
+    var room = Math.max(0, bandLength - MIN_PADDED_LENGTH);
+    return wanted > room ? room / wanted : 1;
+}
+
 /**
  * Define the conversion functions for an axis data is used in 5 ways:
  *
@@ -562,6 +583,9 @@ module.exports = function setConvert(ax, fullLayout) {
         if(ax.overlaying) {
             var ax2 = axisIds.getFromId({ _fullLayout: fullLayout }, ax.overlaying);
             ax.domain = ax2.domain;
+            // an overlaying axis has to sit on exactly the same plot area as the axis
+            // underneath it, so it takes that axis' padding along with its domain
+            ax.domainpad = ax2.domainpad;
         }
 
         // While transitions are occurring, we get a double-transform
@@ -576,14 +600,31 @@ module.exports = function setConvert(ax, fullLayout) {
         var rl1 = ax.r2l(ax[rangeAttr][1], calendar);
 
         var isY = axLetter === 'y';
+        // the band `domain` covers, before domainpad takes its share of it
+        var bandLength = (isY ? gs.h : gs.w) * (ax.domain[1] - ax.domain[0]);
+        var pad = ax.domainpad;
+        // padStart is the edge _offset is measured from, the top for y and the left
+        // for x, so it is the one that pushes the plot area inwards
+        var padStart = 0;
+        var padEnd = 0;
+
+        if(pad) {
+            padStart = (isY ? pad.top : pad.left) || 0;
+            padEnd = (isY ? pad.bottom : pad.right) || 0;
+
+            var fits = padFactor(padStart + padEnd, bandLength);
+            padStart *= fits;
+            padEnd *= fits;
+        }
+
+        ax._length = bandLength - padStart - padEnd;
+
         if(isY) {
-            ax._offset = gs.t + (1 - ax.domain[1]) * gs.h;
-            ax._length = gs.h * (ax.domain[1] - ax.domain[0]);
+            ax._offset = gs.t + (1 - ax.domain[1]) * gs.h + padStart;
             ax._m = ax._length / (rl0 - rl1);
             ax._b = -ax._m * rl1;
         } else {
-            ax._offset = gs.l + ax.domain[0] * gs.w;
-            ax._length = gs.w * (ax.domain[1] - ax.domain[0]);
+            ax._offset = gs.l + ax.domain[0] * gs.w + padStart;
             ax._m = ax._length / (rl1 - rl0);
             ax._b = -ax._m * rl0;
         }

src/traces/scattergl/plot.js

@@ -17,21 +17,22 @@ var styleTextSelection = require('./edit_style').styleTextSelection;
 var reglPrecompiled = {};
 
 function getViewport(fullLayout, xaxis, yaxis, plotGlPixelRatio) {
-    var gs = fullLayout._size;
-    var width = fullLayout.width * plotGlPixelRatio;
-    var height = fullLayout.height * plotGlPixelRatio;
-
-    var l = gs.l * plotGlPixelRatio;
-    var b = gs.b * plotGlPixelRatio;
-    var r = gs.r * plotGlPixelRatio;
-    var t = gs.t * plotGlPixelRatio;
-    var w = gs.w * plotGlPixelRatio;
-    var h = gs.h * plotGlPixelRatio;
+    // This is the same rectangle the svg side draws into, only measured up from the
+    // bottom of the figure instead of down from the top. Read it off _offset and
+    // _length rather than working it out from `domain` again, so that anything which
+    // moves the plot area by a pixel amount - `domainpad`, say - lands here as well.
+    var height = fullLayout.height;
+
+    var left = xaxis._offset;
+    var right = xaxis._offset + xaxis._length;
+    var bottom = height - (yaxis._offset + yaxis._length);
+    var top = height - yaxis._offset;
+
     return [
-        l + xaxis.domain[0] * w,
-        b + yaxis.domain[0] * h,
-        (width - r) - (1 - xaxis.domain[1]) * w,
-        (height - t) - (1 - yaxis.domain[1]) * h
+        left * plotGlPixelRatio,
+        bottom * plotGlPixelRatio,
+        right * plotGlPixelRatio,
+        top * plotGlPixelRatio
     ];
 }
 

src/traces/splom/base_plot.js

@@ -90,7 +90,6 @@ function updateGrid(gd) {
 function makeGridData(gd) {
     var plotGlPixelRatio = gd._context.plotGlPixelRatio;
     var fullLayout = gd._fullLayout;
-    var gs = fullLayout._size;
     var fullView = [
         0, 0,
         fullLayout.width * plotGlPixelRatio,
@@ -135,8 +134,10 @@ function makeGridData(gd) {
         var yLength = ya._length;
 
         // ya.l2p assumes top-to-bottom coordinate system (a la SVG),
-        // we need to compute bottom-to-top offsets and slopes:
-        var yOffset = gs.b + ya.domain[0] * gs.h;
+        // we need to compute bottom-to-top offsets and slopes.
+        // Flip the axis' own bottom edge rather than rebuilding it from `domain`,
+        // so pixel adjustments to the plot area such as `domainpad` come along:
+        var yOffset = fullLayout.height - (ya._offset + ya._length);
         var ym = -ya._m;
         var yb = -ym * ya.r2l(ya.range[0], ya.calendar);
         var x, y;

src/traces/splom/plot.js

@@ -41,6 +41,14 @@ function plotOne(gd, cd0) {
     viewOpts.ranges = new Array(visibleLength);
     viewOpts.domains = new Array(visibleLength);
 
+    // regl-splom places each cell as a fraction of the viewport below, which is the
+    // whole plot area. Derive those fractions from where the axes actually ended up
+    // rather than from `domain`, otherwise anything that shifts the plot area in
+    // pixels - `domainpad` - would move the axes but leave the points behind.
+    // regl counts y up from the bottom, so the y pair comes back reversed.
+    function xFraction(px) { return (px - gs.l) / gs.w; }
+    function yFraction(px) { return (fullLayout.height - px - gs.b) / gs.h; }
+
     for(k = 0; k < visibleDims.length; k++) {
         i = visibleDims[k];
 
@@ -51,16 +59,16 @@ function plotOne(gd, cd0) {
         if(xa) {
             rng[0] = xa._rl[0];
             rng[2] = xa._rl[1];
-            dmn[0] = xa.domain[0];
-            dmn[2] = xa.domain[1];
+            dmn[0] = xFraction(xa._offset);
+            dmn[2] = xFraction(xa._offset + xa._length);
         }
 
         ya = AxisIDs.getFromId(gd, trace._diag[i][1]);
         if(ya) {
             rng[1] = ya._rl[0];
             rng[3] = ya._rl[1];
-            dmn[1] = ya.domain[0];
-            dmn[3] = ya.domain[1];
+            dmn[1] = yFraction(ya._offset + ya._length);
+            dmn[3] = yFraction(ya._offset);
         }
     }