Implement basic chart title alignment options [882]

- Not cleaned up.
- Padding attributes missing.
- `auto` values missing.

Author: rmoestl

src/constants/alignment.js

@@ -41,12 +41,17 @@ module.exports = {
     // multiple of fontSize to get the vertical offset between lines
     LINE_SPACING: 1.3,
 
-    // multiple of fontSize to shift from the baseline to the midline
+    // multiple of fontSize to shift from the baseline
+    // to the cap (captical letter) line
     // (to use when we don't calculate this shift from Drawing.bBox)
-    // To be precise this should be half the cap height (capital letter)
-    // of the font, and according to wikipedia:
+    // This is an approximation since in reality cap height can differ
+    // from font to font. However, according to Wikipedia
     //   an "average" font might have a cap height of 70% of the em
     // https://en.wikipedia.org/wiki/Em_(typography)#History
+    CAP_SHIFT: 0.70,
+
+    // half the cap height (distance between baseline and cap line)
+    // of an "average" font (for more info see above).
     MID_SHIFT: 0.35,
 
     OPPOSITE_SIDE: {

src/plot_api/subroutines.js

@@ -449,19 +449,61 @@ function findCounterAxisLineWidth(ax, side, counterAx, axList) {
 
 exports.drawMainTitle = function(gd) {
     var fullLayout = gd._fullLayout;
+    var textAnchorDict = {
+        'left': 'start',
+        'center': 'middle',
+        'right': 'end',
+        'auto': 'middle' // TODO That needs to be calculated based on x
+    };
+    var dyDict = {
+        'top': alignmentConstants.CAP_SHIFT + 'em',
+        'middle': alignmentConstants.MID_SHIFT + 'em',
+        'bottom': '0em',
+    };
 
     Titles.draw(gd, 'gtitle', {
         propContainer: fullLayout,
         propName: 'title.text',
         placeholder: fullLayout._dfltTitle.plot,
         attributes: {
-            x: fullLayout.width / 2,
-            y: fullLayout._size.t / 2,
-            'text-anchor': 'middle'
+            x: getMainTitleX(fullLayout),
+            y: getMainTitleY(fullLayout),
+            'text-anchor': textAnchorDict[fullLayout.title.xanchor],
+            dy: dyDict[fullLayout.title.yanchor]
         }
     });
 };
 
+function getMainTitleX(fullLayout) {
+    var title = fullLayout.title;
+    var _size = fullLayout._size;
+
+    switch(title.xref) {
+        case 'paper':
+            return _size.l + _size.w * title.x;
+        case 'container':
+        default:
+            return fullLayout.width * title.x;
+    }
+}
+
+function getMainTitleY(fullLayout) {
+    var title = fullLayout.title;
+    var _size = fullLayout._size;
+
+    if(title.y === 'auto') {
+        return _size.t / 2;
+    } else {
+        switch(title.yref) {
+            case 'paper':
+                return _size.t + _size.h - _size.h * title.y;
+            case 'container':
+            default:
+                return fullLayout.height - fullLayout.height * title.y;
+        }
+    }
+}
+
 exports.doTraceStyle = function(gd) {
     var calcdata = gd.calcdata;
     var editStyleCalls = [];

src/plots/layout_attributes.js

@@ -38,6 +38,70 @@ module.exports = {
             editType: 'layoutstyle',
             description: 'Sets the title font.'
         }),
+        xref: {
+            valType: 'enumerated',
+            dflt: 'container',
+            values: ['container', 'paper'],
+            role: 'info',
+            editType: 'layoutstyle',
+            description: [
+                'Some',
+                'docu', // TODO document
+            ].join(' ')
+        },
+        yref: {
+            valType: 'enumerated',
+            dflt: 'container',
+            values: ['container', 'paper'],
+            role: 'info',
+            editType: 'layoutstyle',
+            description: [
+                'Some',
+                'docu', // TODO document
+            ].join(' ')
+        },
+        x: {
+            valType: 'number',
+            dflt: '0.5',
+            role: 'style',
+            editType: 'layoutstyle',
+            description: [
+                'Some',
+                'docu', // TODO document
+            ].join(' ')
+        },
+        y: {
+            valType: 'any',
+            dflt: 'auto',
+            role: 'style',
+            editType: 'layoutstyle',
+            description: [
+                'Some',
+                'docu',
+            ].join(' ')
+        },
+        xanchor: {
+            valType: 'enumerated',
+            dflt: 'auto',
+            values: ['auto', 'left', 'center', 'right'],
+            role: 'info',
+            editType: 'layoutstyle',
+            description: [
+                'Some',
+                'docu', // TODO document
+            ].join(' ')
+        },
+        yanchor: {
+            valType: 'enumerated',
+            dflt: 'auto',
+            values: ['auto', 'top', 'middle', 'bottom'],
+            role: 'info',
+            editType: 'layoutstyle',
+            description: [
+                'Some',
+                'docu', // TODO document
+            ].join(' ')
+        },
         editType: 'layoutstyle'
     },
     autosize: {

src/plots/plots.js

@@ -1332,6 +1332,13 @@ plots.supplyLayoutGlobalDefaults = function(layoutIn, layoutOut, formatObj) {
         color: globalFont.color
     });
 
+    coerce('title.xref');
+    coerce('title.yref');
+    coerce('title.x'); // TODO restrict to [-2, 3]?
+    coerce('title.y'); // TODO restrict to [-2, 3]?
+    coerce('title.xanchor');
+    coerce('title.yanchor');
+
     // Make sure that autosize is defaulted to *true*
     // on layouts with no set width and height for backward compatibly,
     // in particular https://plot.ly/javascript/responsive-fluid-layout/