Add axis title standoff

src/plots/cartesian/axes.js

@@ -33,6 +33,7 @@ var MINUS_SIGN = constants.MINUS_SIGN;
 var BADNUM = constants.BADNUM;
 
 var MID_SHIFT = require('../../constants/alignment').MID_SHIFT;
+var CAP_SHIFT = require('../../constants/alignment').CAP_SHIFT;
 var LINE_SPACING = require('../../constants/alignment').LINE_SPACING;
 var OPPOSITE_SIDE = require('../../constants/alignment').OPPOSITE_SIDE;
 
@@ -1859,6 +1860,11 @@ axes.drawOne = function(gd, ax, opts) {
                 transFn: transFn
             });
         });
+    } else if(ax.title.hasOwnProperty('standoff')) {
+        seq.push(function() {
+            var sgn = {l: -1, t: -1, r: 1, b: 1}[ax.side.charAt(0)];
+            ax._depth = sgn * (getLabelLevelBbox()[ax.side] - mainLinePosition);
+        });
     }
 
     var hasRangeSlider = Registry.getComponentMethod('rangeslider', 'isVisible')(ax);
@@ -1936,10 +1942,7 @@ axes.drawOne = function(gd, ax, opts) {
                 ax._anchorAxis.domain[domainIndices[0]];
 
             if(ax.title.text !== fullLayout._dfltTitle[axLetter]) {
-                var extraLines = (ax.title.text.match(svgTextUtils.BR_TAG_ALL) || []).length;
-                push[s] += extraLines ?
-                    ax.title.font.size * (extraLines + 1) * LINE_SPACING :
-                    ax.title.font.size;
+                push[s] += approxTitleDepth(ax) + (ax.title.standoff || 0);
             }
 
             if(ax.mirror && ax.anchor !== 'free') {
@@ -2699,42 +2702,84 @@ axes.getPxPosition = function(gd, ax) {
     }
 };
 
+/**
+ * Approximate axis title depth (w/o computing its bounding box)
+ *
+ * @param {object} ax (full) axis object
+ *  - {string} title.text
+ *  - {number} title.font.size
+ *  - {number} title.standoff
+ * @return {number} (in px)
+ */
+function approxTitleDepth(ax) {
+    var fontSize = ax.title.font.size;
+    var extraLines = (ax.title.text.match(svgTextUtils.BR_TAG_ALL) || []).length;
+    if(ax.title.hasOwnProperty('standoff')) {
+        return extraLines ?
+            fontSize * (CAP_SHIFT + (extraLines * LINE_SPACING)) :
+            fontSize * CAP_SHIFT;
+    } else {
+        return extraLines ?
+            fontSize * (extraLines + 1) * LINE_SPACING :
+            fontSize;
+    }
+}
+
+/**
+ * Draw axis title, compute default standoff if necessary
+ *
+ * @param {DOM element} gd
+ * @param {object} ax (full) axis object
+ *  - {string} _id
+ *  - {string} _name
+ *  - {string} side
+ *  - {number} title.font.size
+ *  - {object} _selections
+ *
+ *  - {number} _depth
+ *  - {number} title.standoff
+ *  OR
+ *  - {number} linewidth
+ *  - {boolean} showticklabels
+ */
 function drawTitle(gd, ax) {
     var fullLayout = gd._fullLayout;
     var axId = ax._id;
     var axLetter = axId.charAt(0);
     var fontSize = ax.title.font.size;
 
     var titleStandoff;
-    if(ax.type === 'multicategory') {
-        titleStandoff = ax._depth;
+
+    if(ax.title.hasOwnProperty('standoff')) {
+        titleStandoff = ax._depth + ax.title.standoff + approxTitleDepth(ax);
     } else {
-        var offsetBase = 1.5;
-        titleStandoff = 10 + fontSize * offsetBase + (ax.linewidth ? ax.linewidth - 1 : 0);
+        if(ax.type === 'multicategory') {
+            titleStandoff = ax._depth;
+        } else {
+            var offsetBase = 1.5;
+            titleStandoff = 10 + fontSize * offsetBase + (ax.linewidth ? ax.linewidth - 1 : 0);
+        }
+
+        if(axLetter === 'x') {
+            titleStandoff += ax.side === 'top' ?
+                fontSize * (ax.showticklabels ? 1 : 0) :
+                fontSize * (ax.showticklabels ? 1.5 : 0.5);
+        } else {
+            titleStandoff += ax.side === 'right' ?
+                fontSize * (ax.showticklabels ? 1 : 0.5) :
+                fontSize * (ax.showticklabels ? 0.5 : 0);
+        }
     }
 
     var pos = axes.getPxPosition(gd, ax);
     var transform, x, y;
 
     if(axLetter === 'x') {
         x = ax._offset + ax._length / 2;
-
-        if(ax.side === 'top') {
-            y = -titleStandoff - fontSize * (ax.showticklabels ? 1 : 0);
-        } else {
-            y = titleStandoff + fontSize * (ax.showticklabels ? 1.5 : 0.5);
-        }
-        y += pos;
+        y = (ax.side === 'top') ? pos - titleStandoff : pos + titleStandoff;
     } else {
         y = ax._offset + ax._length / 2;
-
-        if(ax.side === 'right') {
-            x = titleStandoff + fontSize * (ax.showticklabels ? 1 : 0.5);
-        } else {
-            x = -titleStandoff - fontSize * (ax.showticklabels ? 0.5 : 0);
-        }
-        x += pos;
-
+        x = (ax.side === 'right') ? pos + titleStandoff : pos - titleStandoff;
         transform = {rotate: '-90', offset: 0};
     }
 
@@ -2753,6 +2798,10 @@ function drawTitle(gd, ax) {
             avoid.offsetLeft = translation.x;
             avoid.offsetTop = translation.y;
         }
+
+        if(ax.title.hasOwnProperty('standoff')) {
+            avoid.pad = 0;
+        }
     }
 
     return Titles.draw(gd, axId + 'title', {

src/plots/cartesian/layout_attributes.js

@@ -62,6 +62,21 @@ module.exports = {
                 'by the now deprecated `titlefont` attribute.'
             ].join(' ')
         }),
+        standoff: {
+            valType: 'number',
+            role: 'info',
+            min: 0,
+            editType: 'ticks',
+            description: [
+                'Sets the standoff distance (in px) between the axis labels and the title text',
+                'The default value is a function of the axis tick labels, the title `font.size`',
+                'and the axis `linewidth`.',
+                'Note that the axis title position is always constrained within the margins,',
+                'so the actual standoff distance is always less than the set or default value.',
+                'By setting `standoff` and turning on `automargin`, plotly.js will push the',
+                'margins to fit the axis title at given standoff distance.'
+            ].join(' ')
+        },
         editType: 'ticks'
     },
     type: {

src/plots/cartesian/layout_defaults.js

@@ -235,6 +235,8 @@ module.exports = function supplyLayoutDefaults(layoutIn, layoutOut, fullData) {
             grid: layoutOut.grid
         });
 
+        coerce('title.standoff');
+
         axLayoutOut._input = axLayoutIn;
     }
 

src/plots/polar/layout_attributes.js

@@ -122,6 +122,7 @@ var radialAxisAttrs = {
 
         // TODO
         // - might need a 'titleside' and even 'titledirection' down the road
+        // - what about standoff ??
 
         editType: 'plot'
     },

src/plots/ternary/layout_attributes.js

@@ -19,6 +19,7 @@ var ternaryAxesAttrs = {
     title: {
         text: axesAttrs.title.text,
         font: axesAttrs.title.font
+        // TODO does standoff here make sense?
     },
     color: axesAttrs.color,
     // ticks

src/traces/carpet/axis_attributes.js

@@ -57,6 +57,7 @@ module.exports = {
                 'by the now deprecated `titlefont` attribute.'
             ].join(' ')
         }),
+        // TODO how is this different than `title.standoff`
         offset: {
             valType: 'number',
             role: 'info',

test/image/mocks/automargin-title-standoff.json

@@ -0,0 +1,65 @@
+{
+  "data": [
+    {"x": ["looooooooooong label"], "y": [1]},
+    {"y": ["looooooooooong label"], "x": [1], "xaxis": "x2", "yaxis": "y2"}
+  ],
+  "layout": {
+    "grid": {"rows": 1, "columns": 2, "pattern": "independent"},
+    "width": 600,
+    "height": 500,
+    "margin": {"l": 0, "r": 0, "t": 0, "b": 0},
+    "showlegend": false,
+    "title": {
+      "text": "With axis automargin:true<br>with margin:0",
+      "x": 0,
+      "xanchor": "left",
+      "xref": "paper"
+    },
+    "xaxis": {
+      "title": {
+        "text": "X Axis (standoff: 60)",
+        "standoff": 60,
+        "font": {"size": 25}
+      },
+      "automargin": true,
+      "showline": true,
+      "mirror": true,
+      "ticks": "outside",
+      "tickangle": 20
+    },
+    "yaxis": {
+      "title": {
+        "text": "Y<br>Axis (standoff: 100)",
+        "standoff": 100,
+        "font": {"size": 20}
+      },
+      "automargin": true,
+      "showline": true,
+      "mirror": true
+    },
+    "xaxis2": {
+      "anchor": "y2",
+      "side": "top",
+      "title": {
+        "text": "X<br>Axis 2<br>(standoff: 80)",
+        "standoff": 80
+      },
+      "automargin": true,
+      "showline": true,
+      "mirror": true
+    },
+    "yaxis2": {
+      "anchor": "x2",
+      "side": "right",
+      "title": {
+        "text": "Y Axis 2 (standoff: 30)",
+        "standoff": 30
+      },
+      "automargin": true,
+      "showline": true,
+      "mirror": true,
+      "ticks": "outside",
+      "tickangle": 80
+    }
+  }
+}

test/image/mocks/axis-title-standoff.json

@@ -0,0 +1,59 @@
+{
+  "data": [
+    {"x": ["looooooooooong label"], "y": [1]},
+    {"y": ["looooooooooong label"], "x": [1], "xaxis": "x2", "yaxis": "y2"}
+  ],
+  "layout": {
+    "grid": {"rows": 1, "columns": 2, "pattern": "independent"},
+    "width": 600,
+    "height": 500,
+    "showlegend": false,
+    "title": {
+      "text": "No axis automargin:true<br>with default margins",
+      "x": 0,
+      "xanchor": "left",
+      "xref": "paper"
+    },
+    "xaxis": {
+      "title": {
+        "text": "X Axis (standoff:10)",
+        "standoff": 10,
+        "font": {"size": 25}
+      },
+      "showline": true,
+      "mirror": true,
+      "ticks": "outside"
+    },
+    "yaxis": {
+      "title": {
+        "text": "Y<br>Axis (standoff:8)",
+        "standoff": 0,
+        "font": {"size": 8}
+      },
+      "showline": true,
+      "mirror": true
+    },
+    "xaxis2": {
+      "anchor": "y2",
+      "side": "top",
+      "title": {
+        "text": "X<br>Axis 2<br>(standoff:0)",
+        "standoff": 0
+      },
+      "showline": true,
+      "mirror": true
+    },
+    "yaxis2": {
+      "anchor": "x2",
+      "side": "right",
+      "title": {
+        "text": "Y Axis 2 (standoff:0)",
+        "standoff": 0
+      },
+      "showline": true,
+      "mirror": true,
+      "ticks": "outside",
+      "tickangle": 80
+    }
+  }
+}