Merge pull request #7965 from SharadhNaidu/domainpad

domainpad: pixel spacing inside axis domains

Author: KoolADE85

draftlogs/7965_add.md

@@ -0,0 +1 @@
+- Add `domainpad` to cartesian axes to reserve space in pixels inside the edges of `domain`, so the gap between subplots stays the same at all figure sizes [[#7965](https://github.com/plotly/plotly.js/pull/7965)], with thanks to @SharadhNaidu for the contribution!

src/components/fx/hover.js

@@ -2429,6 +2429,45 @@ function cleanPoint(d, hovermode) {
     return d;
 }
 
+/**
+ * Get the pixel span of a spike with spikemode 'across'.
+ *
+ * @param gd - the graph div
+ * @param ax - the full axis that shows the spike
+ * @param gs - the plot size, `fullLayout._size`
+ * @returns [start, end] in pixels: left to right for a y axis spike, top to bottom for an x axis spike
+ */
+function getAcrossSpikeSpan(gd, ax, gs) {
+    const isY = ax._id.charAt(0) === 'y';
+    let start = Infinity;
+    let end = -Infinity;
+
+    for (const counterId of ax._counterAxes || []) {
+        const counterAx = Axes.getFromId(gd, counterId);
+        if (!counterAx) continue;
+
+        const padStart = counterAx._padStart || 0;
+        const padEnd = counterAx._padEnd || 0;
+
+        if (isY) {
+            start = Math.min(start, gs.l + counterAx.domain[0] * gs.w + padStart);
+            end = Math.max(end, gs.l + counterAx.domain[1] * gs.w - padEnd);
+        } else {
+            start = Math.min(start, gs.t + (1 - counterAx.domain[1]) * gs.h + padStart);
+            end = Math.max(end, gs.t + (1 - counterAx.domain[0]) * gs.h - padEnd);
+        }
+    }
+
+    // a free axis sits outside the plot areas, and the spike must also reach that axis
+    if (ax.anchor === 'free') {
+        const position = isY ? gs.l + ax.position * gs.w : gs.t + (1 - ax.position) * gs.h;
+        start = Math.min(start, position);
+        end = Math.max(end, position);
+    }
+
+    return [start, end];
+}
+
 function createSpikelines(gd, closestPoints, opts) {
     var container = opts.container;
     var fullLayout = opts.fullLayout;
@@ -2478,14 +2517,9 @@ function createSpikelines(gd, closestPoints, opts) {
                 xEndSpike = hLinePointX;
             }
             if (yMode.indexOf('across') !== -1) {
-                var xAcross0 = ya._counterDomainMin;
-                var xAcross1 = ya._counterDomainMax;
-                if (ya.anchor === 'free') {
-                    xAcross0 = Math.min(xAcross0, ya.position);
-                    xAcross1 = Math.max(xAcross1, ya.position);
-                }
-                xBase = gs.l + xAcross0 * gs.w;
-                xEndSpike = gs.l + xAcross1 * gs.w;
+                const xSpan = getAcrossSpikeSpan(gd, ya, gs);
+                xBase = xSpan[0];
+                xEndSpike = xSpan[1];
             }
 
             // Foreground horizontal line (to y-axis)
@@ -2563,14 +2597,9 @@ function createSpikelines(gd, closestPoints, opts) {
                 yEndSpike = vLinePointY;
             }
             if (xMode.indexOf('across') !== -1) {
-                var yAcross0 = xa._counterDomainMin;
-                var yAcross1 = xa._counterDomainMax;
-                if (xa.anchor === 'free') {
-                    yAcross0 = Math.min(yAcross0, xa.position);
-                    yAcross1 = Math.max(yAcross1, xa.position);
-                }
-                yBase = gs.t + (1 - yAcross1) * gs.h;
-                yEndSpike = gs.t + (1 - yAcross0) * gs.h;
+                const ySpan = getAcrossSpikeSpan(gd, xa, gs);
+                yBase = ySpan[0];
+                yEndSpike = ySpan[1];
             }
 
             // Foreground vertical line (to x-axis)

src/components/rangeslider/draw.js

@@ -100,11 +100,12 @@ 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 must line up with the plot area above it. `domainpad` moves the
+        // plot area but not `domain`, so get the width and position from the axis.
+        opts._width = axisOpts._length;
 
-        var x = Math.round(gs.l + (gs.w * domain[0]));
+        const x = Math.round(axisOpts._offset);
 
         var y = Math.round(
             gs.t + gs.h * (1 - axisOpts._counterDomainMin) +

src/plots/cartesian/axes.js

@@ -4683,7 +4683,8 @@ function swapAxisGroup(gd, xIds, yIds) {
     var allAxKeys = Object.keys(axAttrs);
 
     var noSwapAttrs = [
-        'anchor', 'domain', 'overlaying', 'position', 'side', 'tickangle', 'editType'
+        'anchor', 'domain', 'domainpad', 'overlaying', 'position', 'side',
+        'tickangle', 'editType'
     ];
     var numericTypes = ['linear', 'log'];
 

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,32 @@ exports.clean = function clean(gd, ax) {
     }
 };
 
-function updateDomain(ax, factor) {
+function domainPadFraction(ax, fullLayout) {
+    const pad = ax.domainpad;
+    if(!pad) return 0;
+
+    const 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;
 
+    let divisor = factor;
+    const padFraction = domainPadFraction(ax, fullLayout);
+    if(padFraction > 0) {
+        const inputSpan = inputDomain[1] - inputDomain[0];
+        const drawnSpan = inputSpan - padFraction;
+        if(drawnSpan > 0) divisor = inputSpan / (drawnSpan / factor + padFraction);
+    }
+
     ax.domain = ax._input.domain = [
-        center + (inputDomain[0] - center) / factor,
-        center + (inputDomain[1] - center) / factor
+        center + (inputDomain[0] - center) / divisor,
+        center + (inputDomain[1] - center) / divisor
     ];
     ax.setScale();
 }

src/plots/cartesian/layout_attributes.js

@@ -1165,6 +1165,48 @@ module.exports = {
         editType: 'plot',
         description: ['Sets the domain of this axis (in plot fraction).'].join(' ')
     },
+    domainpad: {
+        left: {
+            valType: 'number',
+            min: 0,
+            dflt: 0,
+            editType: 'plot',
+            description: 'Sets the space in pixels to reserve inside the left edge of `domain`. Applies to x axes only.'
+        },
+        right: {
+            valType: 'number',
+            min: 0,
+            dflt: 0,
+            editType: 'plot',
+            description: 'Sets the space in pixels to reserve inside the right edge of `domain`. Applies to x axes only.'
+        },
+        top: {
+            valType: 'number',
+            min: 0,
+            dflt: 0,
+            editType: 'plot',
+            description: 'Sets the space in pixels to reserve inside the top edge of `domain`. Applies to y axes only.'
+        },
+        bottom: {
+            valType: 'number',
+            min: 0,
+            dflt: 0,
+            editType: 'plot',
+            description: 'Sets the space in pixels to reserve inside the bottom edge of `domain`. Applies to y axes only.'
+        },
+        editType: 'plot',
+        description: [
+            'Sets the space in pixels to reserve inside the edges of `domain`.',
+            'Because `domain` is a fraction of the plot area, the gap between subplots',
+            'changes with the figure size. `domainpad` keeps the same size in pixels at all figure sizes,',
+            'so it can hold content with a fixed size, such as a subplot title.',
+            'x axes use `left` and `right`. y axes use `top` and `bottom`.',
+            'If the padding needs more room than the domain has, the two pads shrink by the same factor,',
+            'and the plot area keeps a length of at least 2 pixels.',
+            'An axis that sets `overlaying` ignores its own `domainpad` and uses the `domainpad`',
+            'of the axis it overlays, so that both axes share the same plot area.'
+        ].join(' ')
+    },
     position: {
         valType: 'number',
         min: 0,

src/plots/cartesian/position_defaults.js

@@ -84,6 +84,14 @@ module.exports = function handlePositionDefaults(containerIn, containerOut, coer
         if(domain[0] > domain[1] - 1 / 4096) containerOut.domain = dfltDomain;
         Lib.noneOrAll(containerIn.domain, containerOut.domain, dfltDomain);
 
+        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,21 @@ function isValidCategory(v) {
     return v !== null && v !== undefined;
 }
 
+const MIN_PADDED_LENGTH = 2;
+
+/**
+ * Get the part of the requested `domainpad` that fits in a domain band.
+ *
+ * @param wanted - the total padding of the two edges, in pixels
+ * @param bandLength - the length of the domain band, in pixels
+ * @returns the factor from 0 to 1 to multiply each pad by
+ */
+function padFactor(wanted, bandLength) {
+    if(wanted <= 0) return 0;
+    const 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 +577,7 @@ module.exports = function setConvert(ax, fullLayout) {
         if(ax.overlaying) {
             var ax2 = axisIds.getFromId({ _fullLayout: fullLayout }, ax.overlaying);
             ax.domain = ax2.domain;
+            ax.domainpad = ax2.domainpad;
         }
 
         // While transitions are occurring, we get a double-transform
@@ -576,14 +592,31 @@ module.exports = function setConvert(ax, fullLayout) {
         var rl1 = ax.r2l(ax[rangeAttr][1], calendar);
 
         var isY = axLetter === 'y';
+        // the length in pixels of the domain band, before `domainpad`
+        const bandLength = (isY ? gs.h : gs.w) * (ax.domain[1] - ax.domain[0]);
+        const pad = ax.domainpad;
+        let padStart = 0;
+        let padEnd = 0;
+
+        if(pad) {
+            padStart = (isY ? pad.top : pad.left) || 0;
+            padEnd = (isY ? pad.bottom : pad.right) || 0;
+
+            const fits = padFactor(padStart + padEnd, bandLength);
+            padStart *= fits;
+            padEnd *= fits;
+        }
+
+        ax._length = bandLength - padStart - padEnd;
+        ax._padStart = padStart;
+        ax._padEnd = 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/plots/plots.js

@@ -840,7 +840,6 @@ plots.linkSubplots = function(newFullData, newFullLayout, oldFullData, oldFullLa
         // find "full" domain span of counter axes,
         // this loop can be costly, so only compute it when required
         if(ax._counterAxes.length && (
-            (ax.spikemode && ax.spikemode.indexOf('across') !== -1) ||
             (ax.automargin && ax.mirror && ax.anchor !== 'free') ||
             Registry.getComponentMethod('rangeslider', 'isVisible')(ax)
         )) {

src/traces/scattergl/plot.js

@@ -28,11 +28,17 @@ function getViewport(fullLayout, xaxis, yaxis, plotGlPixelRatio) {
     var t = gs.t * plotGlPixelRatio;
     var w = gs.w * plotGlPixelRatio;
     var h = gs.h * plotGlPixelRatio;
+
+    const padL = (xaxis._padStart || 0) * plotGlPixelRatio;
+    const padR = (xaxis._padEnd || 0) * plotGlPixelRatio;
+    const padT = (yaxis._padStart || 0) * plotGlPixelRatio;
+    const padB = (yaxis._padEnd || 0) * plotGlPixelRatio;
+
     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
+        l + xaxis.domain[0] * w + padL,
+        b + yaxis.domain[0] * h + padB,
+        (width - r) - (1 - xaxis.domain[1]) * w - padR,
+        (height - t) - (1 - yaxis.domain[1]) * h - padT
     ];
 }