Adding automargin support to plot titles

src/components/titles/index.js

@@ -77,6 +77,7 @@ function draw(gd, titleClass, options) {
     else if(prop.indexOf('colorbar' !== -1)) editAttr = 'colorbarTitleText';
     var editable = gd._context.edits[editAttr];
 
+
     if(txt === '') opacity = 0;
     // look for placeholder text while stripping out numbers from eg X2, Y3
     // this is just for backward compatibility with the old version that had

src/plot_api/plot_api.js

@@ -277,6 +277,7 @@ function _doPlot(gd, data, layout, config) {
 
         subroutines.drawMarginPushers(gd);
         Axes.allowAutoMargin(gd);
+        Plots.allowAutoMargin(gd, 'title.automargin');
 
         // TODO can this be moved elsewhere?
         if(fullLayout._has('pie')) {

src/plot_api/subroutines.js

@@ -5,6 +5,7 @@ var Registry = require('../registry');
 var Plots = require('../plots/plots');
 
 var Lib = require('../lib');
+var svgTextUtils = require('../lib/svg_text_utils');
 var clearGlCanvases = require('../lib/clear_gl_canvases');
 
 var Color = require('../components/color');
@@ -22,6 +23,7 @@ var doAutoRange = require('../plots/cartesian/autorange').doAutoRange;
 var SVG_TEXT_ANCHOR_START = 'start';
 var SVG_TEXT_ANCHOR_MIDDLE = 'middle';
 var SVG_TEXT_ANCHOR_END = 'end';
+var LINE_SPACING = alignmentConstants.LINE_SPACING;
 
 exports.layoutStyles = function(gd) {
     return Lib.syncOrAsync([Plots.doAutoMargin, lsInner], gd);
@@ -397,24 +399,98 @@ function findCounterAxisLineWidth(ax, side, counterAx, axList) {
 }
 
 exports.drawMainTitle = function(gd) {
+    var title = gd._fullLayout.title;
+    setDflts(title);
     var fullLayout = gd._fullLayout;
-
     var textAnchor = getMainTitleTextAnchor(fullLayout);
     var dy = getMainTitleDy(fullLayout);
+    var y = getMainTitleY(fullLayout, dy);
+    var position = fullLayout.title.y > 0.5 ? 't' : 'b';
+
+    if(gd._fullLayout.title.automargin) {
+        applyTitleAutoMargin(gd, position, y);
+    }
 
     Titles.draw(gd, 'gtitle', {
         propContainer: fullLayout,
         propName: 'title.text',
         placeholder: fullLayout._dfltTitle.plot,
         attributes: {
             x: getMainTitleX(fullLayout, textAnchor),
-            y: getMainTitleY(fullLayout, dy),
+            y: y,
             'text-anchor': textAnchor,
             dy: dy
         }
     });
 };
 
+// Is any part of the title outside of the container?
+// TODO: What if yref='container'?
+function isOutsideContainer(gd, title, position, y) {
+    var plotHeight = gd._fullLayout._size.h;
+    var yPosTop = Lib.isTopAnchor(title) ? y : y - titleDepth(title); // Standardize to the top of the title
+    var yPosRel = position === 'b' ? plotHeight - yPosTop : yPosTop; // Position relative to the top or bottom of plot
+    if((Lib.isTopAnchor(title) && position === 't') || Lib.isBottomAnchor(title) && position === 'b') {
+        return false;
+    } else {
+        if(yPosRel < titleDepth(title)) {
+            return true;
+        } else {
+            return false;
+        }
+    }
+}
+
+// TODO: Move to setting defaults stage, rather than drawing
+// title.y is 1 or 0 if automargin and paper ref
+function setDflts(title) {
+    if(title.automargin && title.yref === 'paper') {
+        title.y = title.y === 0 ? title.y : 1;
+    }
+    if(title.automargin) {
+        title.yanchor = title.yanchor === 'auto' ? 'bottom' : title.yanchor;
+    }
+}
+
+function titleDepth(title) {
+    var fontSize = title.font.size;
+    var extraLines = (title.text.match(svgTextUtils.BR_TAG_ALL) || []).length;
+    return extraLines ?
+        fontSize * (extraLines + 1) * LINE_SPACING :
+        fontSize;
+}
+
+function applyTitleAutoMargin(gd, position, y) {
+    var titleID = 'title.automargin';
+    var title = gd._fullLayout.title;
+    var push = {
+        x: title.x,
+        y: position === 't' ? 1 : 0, // TODO: Assuming that y is either 1 or 0?
+        t: 0,
+        b: 0
+    };
+
+    if(isOutsideContainer(gd, title, position, y)) {
+        push[position] = (
+            titleDepth(title) +
+            title.pad.t +
+            title.pad.b
+        );
+    }
+    Plots.allowAutoMargin(gd, titleID);
+    Plots.autoMargin(gd, titleID, push);
+}
+
+function getVPadShift(title, dy) {
+    var vPadShift = 0;
+    if(dy === '0em' || !dy) {
+        vPadShift = -title.pad.b;
+    } else if(dy === alignmentConstants.CAP_SHIFT + 'em') {
+        vPadShift = title.pad.t;
+    }
+    return vPadShift;
+}
+
 function getMainTitleX(fullLayout, textAnchor) {
     var title = fullLayout.title;
     var gs = fullLayout._size;
@@ -438,14 +514,7 @@ function getMainTitleX(fullLayout, textAnchor) {
 function getMainTitleY(fullLayout, dy) {
     var title = fullLayout.title;
     var gs = fullLayout._size;
-    var vPadShift = 0;
-
-    if(dy === '0em' || !dy) {
-        vPadShift = -title.pad.b;
-    } else if(dy === alignmentConstants.CAP_SHIFT + 'em') {
-        vPadShift = title.pad.t;
-    }
-
+    var vPadShift = getVPadShift(title, dy);
     if(title.y === 'auto') {
         return gs.t / 2;
     } else {

src/plots/layout_attributes.js

@@ -125,6 +125,14 @@ module.exports = {
                 'Padding is muted if the respective anchor value is *middle*/*center*.'
             ].join(' ')
         }),
+        automargin: {
+            valType: 'boolean',
+            dflt: false,
+            editType: 'plot',
+            description: [
+                'Determines whether the title can automatically push the figure margins.'
+            ].join(' ')
+        },
         editType: 'layoutstyle'
     },
     uniformtext: {

src/plots/plots.js

@@ -1489,6 +1489,7 @@ plots.supplyLayoutGlobalDefaults = function(layoutIn, layoutOut, formatObj) {
     coerce('title.pad.r');
     coerce('title.pad.b');
     coerce('title.pad.l');
+    coerce('title.automargin');
 
     var uniformtextMode = coerce('uniformtext.mode');
     if(uniformtextMode) {

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

@@ -0,0 +1,27 @@
+{
+    "data": [
+        {
+            "showlegend": false,
+            "type": "scatter",
+            "x": [
+            1,
+            2,
+            3
+            ],
+            "y": [
+            4,
+            5,
+            6
+            ]
+        }],
+    "layout": {
+        "margin": {"t":0, "b": 0, "l": 0, "r": 0},
+        "title": {
+            "automargin": true, 
+            "text": "Basic title",
+            "font": {"size": 24},
+            "pad": {"t": 15, "b": 10},
+            "yref": "paper"
+        }
+  }
+}

test/jasmine/tests/pie_test.js

@@ -972,7 +972,7 @@ describe('Pie traces', function() {
             textposition: [['outside', 'outside', 'inside', 'inside', 'outside']],
             'outsidetextfont.size': 12
         }, {
-            t: '~=', l: 'shrunk',
+            t: 'grew', l: 'shrunk',
             b: 'grew', r: 'grew'
         }))
         .then(check('automargin:false', {automargin: false}, {

test/jasmine/tests/titles_test.js

@@ -1066,6 +1066,48 @@ describe('Titles for multiple axes', function() {
     });
 });
 
+describe('Title automargining', function() {
+    'use strict';
+
+    var data = [{x: [1, 1, 3], y: [1, 2, 3]}];
+    var layout = {
+        'margin': {'t': 0, 'b': 0, 'l': 0, 'r': 0},
+        'title': {
+            'text': 'Basic title',
+            'font': {'size': 24},
+            'yref': 'paper'
+        }
+    };
+    var gd;
+
+    beforeEach(function() {
+        gd = createGraphDiv();
+    });
+
+    afterEach(destroyGraphDiv);
+
+    it('should avoid overlap with container for yref=paper and allow padding', function(done) {
+        Plotly.newPlot(gd, data, layout).then(function() {
+            expect(gd._fullLayout._size.t).toBe(0);
+            return Plotly.relayout(gd, 'title.automargin', true);
+        }).then(function() {
+            expect(gd._fullLayout.title.automargin).toBe(true);
+            expect(gd._fullLayout.title.y).toBe(1);
+            expect(gd._fullLayout.title.yanchor).toBe('bottom');
+            expect(gd._fullLayout._size.t).toBe(24);
+            return Plotly.relayout(gd, 'title.pad.t', 10);
+        }).then(function() {
+            expect(gd._fullLayout._size.t).toBe(34);
+            return Plotly.relayout(gd, 'title.pad.b', 10);
+        }).then(function() {
+            expect(gd._fullLayout._size.t).toBe(44);
+            return Plotly.relayout(gd, 'title.yanchor', 'top');
+        }).then(function() {
+            expect(gd._fullLayout._size.t).toBe(0);
+        }).then(done, done.fail);
+    });
+});
+
 function expectTitle(expTitle) {
     expectTitleFn(expTitle)();
 }

test/plot-schema.json

@@ -9425,6 +9425,12 @@
     }
    },
    "title": {
+    "automargin": {
+     "description": "Determines whether the title can automatically push the figure margins.",
+     "dflt": false,
+     "editType": "plot",
+     "valType": "boolean"
+    },
     "editType": "layoutstyle",
     "font": {
      "color": {