Adding automargin support to plot titles

src/components/titles/index.js

@@ -167,11 +167,21 @@ function draw(gd, titleClass, options) {
             var pad = isNumeric(avoid.pad) ? avoid.pad : 2;
 
             var titlebb = Drawing.bBox(titleGroup.node());
+
+            // Account for reservedMargins
+            var reservedMargins = {t: 0, b: 0, l: 0, r: 0};
+            var margins = gd._fullLayout._reservedMargin;
+            for(var key in margins) {
+                for(var side in margins[key]) {
+                    var val = margins[key][side];
+                    reservedMargins[side] = Math.max(reservedMargins[side], val);
+                }
+            }
             var paperbb = {
-                left: 0,
-                top: 0,
-                right: fullLayout.width,
-                bottom: fullLayout.height
+                left: reservedMargins.l,
+                top: reservedMargins.t,
+                right: fullLayout.width - reservedMargins.r,
+                bottom: fullLayout.height - reservedMargins.b
             };
 
             var maxshift = avoid.maxShift ||

src/plot_api/plot_api.js

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

src/plot_api/subroutines.js

@@ -3,8 +3,10 @@
 var d3 = require('@plotly/d3');
 var Registry = require('../registry');
 var Plots = require('../plots/plots');
+var Loggers = require('../lib/loggers');
 
 var Lib = require('../lib');
+var svgTextUtils = require('../lib/svg_text_utils');
 var clearGlCanvases = require('../lib/clear_gl_canvases');
 
 var Color = require('../components/color');
@@ -397,24 +399,156 @@ function findCounterAxisLineWidth(ax, side, counterAx, axList) {
 }
 
 exports.drawMainTitle = function(gd) {
+    var title = gd._fullLayout.title;
     var fullLayout = gd._fullLayout;
-
     var textAnchor = getMainTitleTextAnchor(fullLayout);
     var dy = getMainTitleDy(fullLayout);
+    var y = getMainTitleY(fullLayout, dy);
+    var x = getMainTitleX(fullLayout, textAnchor);
 
+    // Draw title without positioning to get size
     Titles.draw(gd, 'gtitle', {
         propContainer: fullLayout,
         propName: 'title.text',
         placeholder: fullLayout._dfltTitle.plot,
-        attributes: {
-            x: getMainTitleX(fullLayout, textAnchor),
-            y: getMainTitleY(fullLayout, dy),
+        attributes: ({
+            x: x,
+            y: y,
             'text-anchor': textAnchor,
             dy: dy
-        }
+        })
     });
+
+    if(title.text && title.automargin) {
+        var titleObj = d3.selectAll('.gtitle');
+        var titleHeight = Drawing.bBox(titleObj.node()).height;
+        var pushMargin = needsMarginPush(gd, title, titleHeight);
+        if(pushMargin > 0) {
+            setDflts(title, getDflts(title)[0], getDflts(title)[1]);
+            // Recalculate these since the defaults have changed
+            dy = getMainTitleDy(fullLayout);
+            y = getMainTitleY(fullLayout, dy);
+            applyTitleAutoMargin(gd, y, pushMargin, titleHeight);
+
+            // Position the title once we know where it needs to be
+            titleObj.attr({
+                x: x,
+                y: y,
+                'text-anchor': textAnchor,
+                dy: dy
+            }).call(svgTextUtils.positionText, x, y);
+        }
+    }
 };
 
+
+function isOutsideContainer(gd, title, position, y, titleHeight) {
+    var plotHeight = title.yref === 'paper' ? gd._fullLayout._size.h : gd._fullLayout.height;
+    var yPosTop = Lib.isTopAnchor(title) ? y : y - titleHeight; // 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 {
+        return yPosRel < titleHeight;
+    }
+}
+
+
+// title.y is 1 or 0 if automargin and paper ref
+// 'auto' is not supported for either title.y or title.yanchor when automargin=true
+function getDflts(title) {
+    var titleY = title.y;
+    var titleYanchor = title.yanchor;
+    if(title.automargin && title.yref === 'paper') {
+        titleY = title.y === 0 ? 0 : 1;
+        if(title.yanchor === 'auto') {
+            titleYanchor = title.y === 0 ? 'top' : 'bottom';
+        }
+    }
+    if(title.automargin && title.yref === 'container') {
+        if(title.y === 'auto') titleY = 1;
+        if(title.yanchor === 'auto') {
+            titleYanchor = title.y < 0.5 ? 'bottom' : 'top';
+        }
+    }
+    return [titleY, titleYanchor];
+}
+
+function setDflts(title, titleY, titleYanchor) {
+    if(title.yref === 'paper' && title.y !== 0 && title.y !== 1 && title.y !== 'auto') {
+        Loggers.warn('title.automargin=true so resetting the supplied title.y value to 1.');
+    }
+    title.y = titleY;
+    title.yanchor = titleYanchor;
+}
+
+
+function containerPushVal(position, titleY, titleYanchor, height, titleDepth) {
+    var push = 0;
+    if(titleYanchor === 'middle') {
+        push += titleDepth / 2;
+    }
+    if(position === 't') {
+        if(titleYanchor === 'top') {
+            push += titleDepth;
+        }
+        push += (height - titleY * height);
+    } else {
+        if(titleYanchor === 'bottom') {
+            push += titleDepth;
+        }
+        push += titleY * height;
+    }
+    return push;
+}
+
+function needsMarginPush(gd, title, titleHeight) {
+    var titleY = getDflts(title)[0];
+    var titleYanchor = getDflts(title)[1];
+    var position = titleY > 0.5 ? 't' : 'b';
+    var curMargin = gd._fullLayout.margin[position];
+    var pushMargin = 0;
+    if(title.yref === 'paper') {
+        pushMargin = (
+            titleHeight +
+            title.pad.t +
+            title.pad.b
+        );
+    } else if(title.yref === 'container') {
+        pushMargin = (
+            containerPushVal(position, titleY, titleYanchor, gd._fullLayout.height, titleHeight) +
+            title.pad.t +
+            title.pad.b
+        );
+    }
+    if(pushMargin > curMargin) {
+        return pushMargin;
+    }
+    return 0;
+}
+
+function applyTitleAutoMargin(gd, y, pushMargin, titleHeight) {
+    var titleID = 'title.automargin';
+    var title = gd._fullLayout.title;
+    var position = title.y > 0.5 ? 't' : 'b';
+    var push = {
+        x: title.x,
+        y: title.y,
+        t: 0,
+        b: 0
+    };
+    var reservedPush = {};
+
+    if(title.yref === 'paper' && isOutsideContainer(gd, title, position, y, titleHeight)) {
+        push[position] = pushMargin;
+    } else if(title.yref === 'container') {
+        reservedPush[position] = pushMargin;
+        gd._fullLayout._reservedMargin[titleID] = reservedPush;
+    }
+    Plots.allowAutoMargin(gd, titleID);
+    Plots.autoMargin(gd, titleID, push);
+}
+
 function getMainTitleX(fullLayout, textAnchor) {
     var title = fullLayout.title;
     var gs = fullLayout._size;
@@ -439,7 +573,6 @@ 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') {

src/plots/layout_attributes.js

@@ -125,6 +125,21 @@ 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.',
+                'If `yref=\'paper\'` then the margin will expand to ensure that the title doesn\’t',
+                'overlap with the edges of the container. If `yref=\'container\'` then the margins',
+                'will ensure that the title doesn\’t overlap with the plot area, tick labels,',
+                'and axis titles. If `automargin=true` and the margins need to be expanded,',
+                'then y will be set to a default 1 and yanchor will be set to an appropriate',
+                'default to ensure that minimal margin space is needed. Note that when `yref=\'paper\'`,',
+                'only 1 or 0 are allowed y values. Invalid values will be reset to the default 1.'
+            ].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) {
@@ -1862,6 +1863,7 @@ function initMargins(fullLayout) {
     }
     if(!fullLayout._pushmargin) fullLayout._pushmargin = {};
     if(!fullLayout._pushmarginIds) fullLayout._pushmarginIds = {};
+    if(!fullLayout._reservedMargin) fullLayout._reservedMargin = {};
 }
 
 // non-negotiable - this is the smallest height we will allow users to specify via explicit margins
@@ -1979,8 +1981,16 @@ plots.doAutoMargin = function(gd) {
 
     var gs = fullLayout._size;
     var margin = fullLayout.margin;
+    var reservedMargins = {t: 0, b: 0, l: 0, r: 0};
     var oldMargins = Lib.extendFlat({}, gs);
 
+    var margins = gd._fullLayout._reservedMargin;
+    for(var key in margins) {
+        for(var side in margins[key]) {
+            var val = margins[key][side];
+            reservedMargins[side] = Math.max(reservedMargins[side], val);
+        }
+    }
     // adjust margins for outside components
     // fullLayout.margin is the requested margin,
     // fullLayout._size has margins and plotsize after adjustment
@@ -2016,14 +2026,16 @@ plots.doAutoMargin = function(gd) {
             var pl = pushleft.size;
             var fb = pushbottom.val;
             var pb = pushbottom.size;
+            var availableWidth = width - reservedMargins.r - reservedMargins.l;
+            var availableHeight = height - reservedMargins.t - reservedMargins.b;
 
             for(var k2 in pushMargin) {
                 if(isNumeric(pl) && pushMargin[k2].r) {
                     var fr = pushMargin[k2].r.val;
                     var pr = pushMargin[k2].r.size;
                     if(fr > fl) {
-                        var newL = (pl * fr + (pr - width) * fl) / (fr - fl);
-                        var newR = (pr * (1 - fl) + (pl - width) * (1 - fr)) / (fr - fl);
+                        var newL = (pl * fr + (pr - availableWidth) * fl) / (fr - fl);
+                        var newR = (pr * (1 - fl) + (pl - availableWidth) * (1 - fr)) / (fr - fl);
                         if(newL + newR > ml + mr) {
                             ml = newL;
                             mr = newR;
@@ -2035,8 +2047,8 @@ plots.doAutoMargin = function(gd) {
                     var ft = pushMargin[k2].t.val;
                     var pt = pushMargin[k2].t.size;
                     if(ft > fb) {
-                        var newB = (pb * ft + (pt - height) * fb) / (ft - fb);
-                        var newT = (pt * (1 - fb) + (pb - height) * (1 - ft)) / (ft - fb);
+                        var newB = (pb * ft + (pt - availableHeight) * fb) / (ft - fb);
+                        var newT = (pt * (1 - fb) + (pb - availableHeight) * (1 - ft)) / (ft - fb);
                         if(newB + newT > mb + mt) {
                             mb = newB;
                             mt = newT;
@@ -2078,10 +2090,11 @@ plots.doAutoMargin = function(gd) {
         }
     }
 
-    gs.l = Math.round(ml);
-    gs.r = Math.round(mr);
-    gs.t = Math.round(mt);
-    gs.b = Math.round(mb);
+
+    gs.l = Math.round(ml) + reservedMargins.l;
+    gs.r = Math.round(mr) + reservedMargins.r;
+    gs.t = Math.round(mt) + reservedMargins.t;
+    gs.b = Math.round(mb) + reservedMargins.b;
     gs.p = Math.round(margin.pad);
     gs.w = Math.round(width) - gs.l - gs.r;
     gs.h = Math.round(height) - gs.t - gs.b;

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

@@ -0,0 +1,30 @@
+{
+    "data": [
+        {
+            "showlegend": false,
+            "type": "scatter",
+            "x": [
+            1,
+            2,
+            3
+            ],
+            "y": [
+            4,
+            5,
+            6
+            ]
+        }],
+    "layout": {
+        "height": 300,
+        "width": 400,
+        "margin": {"t":0, "b": 0, "l": 0, "r": 0},
+        "xaxis": {"automargin": true, "title": {"text": "x-axis title"}},
+        "title": {
+            "automargin": true, 
+            "text": "Container | pad | y=0",
+            "pad": {"t": 15, "b": 10},
+            "y": 0,
+            "yref": "container"
+        }
+    }
+}

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

@@ -0,0 +1,29 @@
+{
+    "data": [
+        {
+            "showlegend": false,
+            "type": "scatter",
+            "x": [
+            1,
+            2,
+            3
+            ],
+            "y": [
+            4,
+            5,
+            6
+            ]
+        }],
+    "layout": {
+        "height": 300,
+        "width": 400,
+        "margin": {"t":0, "b": 0, "l": 0, "r": 0},
+        "xaxis": {"automargin": true, "title": {"text": "x-axis title"}},
+        "title": {
+            "automargin": true, 
+            "text": "Container | no-pad | y=1",
+            "pad": {"t": 0, "b": 0},
+            "yref": "container"
+        }
+    }
+}