first cut title.standoff for cartesian axes

Author: etpinard

src/plots/cartesian/axes.js

@@ -1937,9 +1937,11 @@ axes.drawOne = function(gd, ax, opts) {
 
             if(ax.title.text !== fullLayout._dfltTitle[axLetter]) {
                 var extraLines = (ax.title.text.match(svgTextUtils.BR_TAG_ALL) || []).length;
-                push[s] += extraLines ?
+                var titlePush = extraLines ?
                     ax.title.font.size * (extraLines + 1) * LINE_SPACING :
                     ax.title.font.size;
+
+                push[s] = Math.max(push[s] + titlePush, (ax.title.standoff || 0));
             }
 
             if(ax.mirror) {
@@ -2706,35 +2708,37 @@ function drawTitle(gd, ax) {
     var fontSize = ax.title.font.size;
 
     var titleStandoff;
-    if(ax.type === 'multicategory') {
-        titleStandoff = ax._depth;
+
+    if(ax.title.hasOwnProperty('standoff')) {
+        titleStandoff = ax.title.standoff;
     } 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};
     }
 

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 line 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;
     }
 

test/image/baselines/automargin-title-standoff.png

@@ -0,0 +1,55 @@
+{
+  "data": [
+    {"y": [1]},
+    {"y": [1], "xaxis": "x2", "yaxis": "y2"}
+  ],
+  "layout": {
+    "width": 600,
+    "height": 300,
+    "margin": {"l": 0, "r": 0, "t": 0, "b": 0},
+    "showlegend": false,
+    "grid": {"rows": 1, "columns": 2, "pattern": "independent"},
+    "xaxis": {
+      "title": {
+        "text": "X Axis",
+        "standoff": 60,
+        "font": {"size": 25}
+      },
+      "automargin": true,
+      "showline": true,
+      "mirror": true
+    },
+    "yaxis": {
+      "title": {
+        "text": "Y<br>Axis",
+        "standoff": 100,
+        "font": {"size": 20}
+      },
+      "automargin": true,
+      "showline": true,
+      "mirror": true
+    },
+    "xaxis2": {
+      "anchor": "y2",
+      "side": "top",
+      "title": {
+        "text": "X<br>Axis<br>2",
+        "standoff": 80
+      },
+      "automargin": true,
+      "showline": true,
+      "mirror": true
+    },
+    "yaxis2": {
+      "anchor": "x2",
+      "side": "right",
+      "title": {
+        "text": "Y Axis 2",
+        "standoff": 30
+      },
+      "automargin": true,
+      "showline": true,
+      "mirror": true
+    }
+  }
+}