Deprecate *.titlefont attributes in favor of *.title.font [882]

Author: rmoestl

src/components/colorbar/draw.js

@@ -184,7 +184,6 @@ module.exports = function draw(gd, id) {
                 showticksuffix: opts.showticksuffix,
                 ticksuffix: opts.ticksuffix,
                 title: opts.title,
-                titlefont: opts.titlefont,
                 showline: true,
                 anchor: 'free',
                 side: 'right',
@@ -290,7 +289,7 @@ module.exports = function draw(gd, id) {
             // when we squish the axis. This one only applies to
             // top or bottom titles, not right side.
             var x = gs.l + (opts.x + xpadFrac) * gs.w,
-                fontSize = cbAxisOut.titlefont.size,
+                fontSize = cbAxisOut.title.font.size,
                 y;
 
             if(opts.titleside === 'top') {
@@ -460,7 +459,7 @@ module.exports = function draw(gd, id) {
                 },
                 function() {
                     if(['top', 'bottom'].indexOf(opts.titleside) === -1) {
-                        var fontSize = cbAxisOut.titlefont.size,
+                        var fontSize = cbAxisOut.title.font.size,
                             y = cbAxisOut._offset + cbAxisOut._length / 2,
                             x = gs.l + (cbAxisOut.position || 0) * gs.w + ((cbAxisOut.side === 'right') ?
                                 10 + fontSize * ((cbAxisOut.showticklabels ? 1 : 0.5)) :

src/components/titles/index.js

@@ -67,19 +67,21 @@ function draw(gd, titleClass, options) {
     var group = options.containerGroup;
 
     var fullLayout = gd._fullLayout;
-    var titlefont = cont.titlefont || {};
-    var font = titlefont.family;
-    var fontSize = titlefont.size;
-    var fontColor = titlefont.color;
 
     var opacity = 1;
     var isplaceholder = false;
     var title = cont.title;
     var txt = (title && title.text ? title.text : '').trim();
 
+    var font = title && title.font ? title.font : {};
+    var fontFamily = font.family;
+    var fontSize = font.size;
+    var fontColor = font.color;
+
     // only make this title editable if we positively identify its property
     // as one that has editing enabled.
     var editAttr;
+    // TODO 882 Probably compare against 'title.text'
     if(prop === 'title') editAttr = 'titleText';
     else if(prop.indexOf('axis') !== -1) editAttr = 'axisTitleText';
     else if(prop.indexOf('colorbar' !== -1)) editAttr = 'colorbarTitleText';
@@ -138,7 +140,7 @@ function draw(gd, titleClass, options) {
         titleEl.attr('transform', transformVal);
 
         titleEl.style({
-            'font-family': font,
+            'font-family': fontFamily,
             'font-size': d3.round(fontSize, 2) + 'px',
             fill: Color.rgb(fontColor),
             opacity: opacity * Color.opacity(fontColor),

src/plot_api/helpers.js

@@ -193,6 +193,22 @@ exports.cleanLayout = function(layout) {
         };
     }
 
+    // Check for old-style title font definitions
+    if(Lib.isPlainObject(layout.titlefont) && !Lib.isPlainObject(layout.title.font)) {
+        layout.title.font = layout.titlefont;
+        delete layout.titlefont;
+    }
+    if(layout.xaxis &&
+      Lib.isPlainObject(layout.xaxis.titlefont) && !Lib.isPlainObject(layout.xaxis.title.font)) {
+        layout.xaxis.title.font = layout.xaxis.titlefont;
+        delete layout.xaxis.titlefont;
+    }
+    if(layout.yaxis &&
+      Lib.isPlainObject(layout.yaxis.titlefont) && !Lib.isPlainObject(layout.yaxis.title.font)) {
+        layout.yaxis.title.font = layout.yaxis.titlefont;
+        delete layout.yaxis.titlefont;
+    }
+
     /*
      * Moved from rotate -> orbit for dragmode
      */

src/plot_api/plot_api.js

@@ -1686,6 +1686,34 @@ function _restyle(gd, aobj, traces) {
     };
 }
 
+/**
+ * Maps deprecated layout attributes that need to be converted
+ * to the current API at this stage to ensure backwards compatibility.
+ *
+ * @param layoutObj
+ */
+function mapDeprecatedLayoutAttributes(layoutObj) {
+
+    // Support old-style update of the title's font
+    var isTitlefontSet = layoutObj.titlefont;
+    var isFontInTitleSet = layoutObj.title && layoutObj.title.font;
+    var isFontInTitleNotSet = !isFontInTitleSet;
+    if(isTitlefontSet && isFontInTitleNotSet) {
+
+        // Use string attribute because initiating a new title object
+        // to be able to specify a font property on it would require to
+        // know the potentially existing `title.text` property.
+        layoutObj['title.font'] = layoutObj.titlefont;
+        delete layoutObj.titlefont;
+    }
+
+    // Note, that updating x-axis and y-axis title fonts
+    // was never supported unless (i) using string
+    // attributes or (ii) passing `xaxis.title` / `yaxis.title`
+    // again. And these cases are covered by
+    // helpers.cleanLayout anyways.
+}
+
 /**
  * Maps deprecated layout "string attributes" to
  * "string attributes" of the current API to ensure backwards compatibility.
@@ -1698,13 +1726,32 @@ function mapDeprecatedLayoutAttributeStrings(layoutObj) {
     if(layoutObj.title && !Lib.isPlainObject(layoutObj.title)) {
         layoutObj.title = {text: layoutObj.title};
     }
-    if(layoutObj['xaxis.title'] !== undefined) {
-        layoutObj['xaxis.title.text'] = layoutObj['xaxis.title'];
-        delete layoutObj['xaxis.title'];
-    }
-    if(layoutObj['yaxis.title'] !== undefined) {
-        layoutObj['yaxis.title.text'] = layoutObj['yaxis.title'];
-        delete layoutObj['yaxis.title'];
+    replace('xaxis.title', 'xaxis.title.text');
+    replace('yaxis.title', 'yaxis.title.text');
+
+    // Note: Only "nested" (dot notation) attributes
+    // need to be converted. For example 'titlefont'
+    // was a top-level attribute and thus is covered by
+    // the general compatibility layer.
+    replace('titlefont.color', 'title.font.color');
+    replace('titlefont.family', 'title.font.family');
+    replace('titlefont.size', 'title.font.size');
+
+    replace('xaxis.titlefont', 'xaxis.title.font');
+    replace('xaxis.titlefont.color', 'xaxis.title.font.color');
+    replace('xaxis.titlefont.family', 'xaxis.title.font.family');
+    replace('xaxis.titlefont.size', 'xaxis.title.font.size');
+
+    replace('yaxis.titlefont', 'yaxis.title.font');
+    replace('yaxis.titlefont.color', 'yaxis.title.font.color');
+    replace('yaxis.titlefont.family', 'yaxis.title.font.family');
+    replace('yaxis.titlefont.size', 'yaxis.title.font.size');
+
+    function replace(oldKey, newKey) {
+        if(layoutObj[oldKey] !== undefined) {
+            layoutObj[newKey] = layoutObj[oldKey];
+            delete layoutObj[oldKey];
+        }
     }
 }
 
@@ -1748,6 +1795,7 @@ exports.relayout = function relayout(gd, astr, val) {
 
     if(Object.keys(aobj).length) gd.changed = true;
 
+    mapDeprecatedLayoutAttributes(aobj);
     mapDeprecatedLayoutAttributeStrings(aobj);
 
     var specs = _relayout(gd, aobj);
@@ -2227,6 +2275,7 @@ exports.update = function update(gd, traceUpdate, layoutUpdate, _traces) {
     var restyleSpecs = _restyle(gd, Lib.extendFlat({}, traceUpdate), traces);
     var restyleFlags = restyleSpecs.flags;
 
+    mapDeprecatedLayoutAttributes(layoutUpdate);
     mapDeprecatedLayoutAttributeStrings(layoutUpdate);
 
     var relayoutSpecs = _relayout(gd, Lib.extendFlat({}, layoutUpdate));

src/plots/cartesian/axes.js

@@ -2337,7 +2337,7 @@ axes.drawTitle = function(gd, ax) {
     var axLetter = axId.charAt(0);
     var offsetBase = 1.5;
     var gs = fullLayout._size;
-    var fontSize = ax.titlefont.size;
+    var fontSize = ax.title.font.size;
 
     var transform, counterAxis, x, y;
 

src/plots/cartesian/axis_defaults.js

@@ -69,7 +69,7 @@ module.exports = function handleAxisDefaults(containerIn, containerOut, coerce,
     var dfltTitle = splomStash.label || layoutOut._dfltTitle[letter];
 
     coerce('title.text', dfltTitle);
-    Lib.coerceFont(coerce, 'titlefont', {
+    Lib.coerceFont(coerce, 'title.font', {
         family: font.family,
         size: Math.round(font.size * 1.2),
         color: dfltFontColor

src/plots/cartesian/layout_attributes.js

@@ -47,14 +47,14 @@ module.exports = {
             editType: 'ticks',
             description: 'Sets the title of this axis.'
         },
+        font: fontAttrs({
+            editType: 'ticks',
+            description: [
+                'Sets this axis\' title font.'
+            ].join(' ')
+        }),
         editType: 'ticks'
     },
-    titlefont: fontAttrs({
-        editType: 'ticks',
-        description: [
-            'Sets this axis\' title font.'
-        ].join(' ')
-    }),
     type: {
         valType: 'enumerated',
         // '-' means we haven't yet run autotype or couldn't find any data

src/plots/layout_attributes.js

@@ -34,12 +34,12 @@ module.exports = {
                 'Sets the plot\'s title.'
             ].join(' ')
         },
+        font: fontAttrs({
+            editType: 'layoutstyle',
+            description: 'Sets the title font.'
+        }),
         editType: 'layoutstyle'
     },
-    titlefont: fontAttrs({
-        editType: 'layoutstyle',
-        description: 'Sets the title font.'
-    }),
     autosize: {
         valType: 'boolean',
         role: 'info',

src/plots/plots.js

@@ -1326,7 +1326,7 @@ plots.supplyLayoutGlobalDefaults = function(layoutIn, layoutOut, formatObj) {
 
     coerce('title.text', layoutOut._dfltTitle.plot);
 
-    Lib.coerceFont(coerce, 'titlefont', {
+    Lib.coerceFont(coerce, 'title.font', {
         family: globalFont.family,
         size: Math.round(globalFont.size * 1.4),
         color: globalFont.color