Support adding text labels to lines and shapes

src/components/shapes/attributes.js

@@ -1,6 +1,7 @@
 'use strict';
 
 var annAttrs = require('../annotations/attributes');
+var fontAttrs = require('../../plots/font_attributes');
 var scatterLineAttrs = require('../../traces/scatter/attributes').line;
 var dash = require('../drawing/attributes').dash;
 var extendFlat = require('../../lib/extend').extendFlat;
@@ -224,6 +225,85 @@ module.exports = templatedArray('shape', {
             '`config.editable` or `config.edits.shapePosition`.'
         ].join(' ')
     },
-
+    label: {
+        text: {
+            valType: 'string',
+            dflt: '',
+            editType: 'arraydraw',
+            description: 'Sets the text to display with shape.'
+        },
+        font: fontAttrs({
+            editType: 'calc+arraydraw',
+            colorEditType: 'arraydraw',
+            description: 'Sets the shape label text font.'
+        }),
+        textposition: {
+            valType: 'enumerated',
+            values: [
+                'top left', 'top center', 'top right',
+                'middle left', 'middle center', 'middle right',
+                'bottom left', 'bottom center', 'bottom right',
+                'start', 'middle', 'end',
+            ],
+            editType: 'arraydraw',
+            description: [
+                'Sets the position of the label text relative to the shape.',
+                'Supported values for rectangles, circles and paths are',
+                '`top left`, `top center`, `top right`, `middle left`,',
+                '`middle center`, `middle right`, `bottom left`, `bottom center`,',
+                'and `bottom right`.',
+                'Supported values for lines are `start`, `middle`, and `end`.',
+                'Default: `middle center` for rectangles, circles, and paths; `middle` for lines.',
+            ].join(' ')
+        },
+        textangle: {
+            valType: 'angle',
+            dflt: 'auto',
+            editType: 'calc+arraydraw',
+            description: [
+                'Sets the angle at which the label text is drawn',
+                'with respect to the horizontal. For lines, angle `auto`',
+                'is the same angle as the line. For all other shapes,',
+                'angle `auto` is horizontal.'
+            ].join(' ')
+        },
+        xanchor: {
+            valType: 'enumerated',
+            values: ['auto', 'left', 'center', 'right'],
+            dflt: 'auto',
+            editType: 'calc+arraydraw',
+            description: [
+                'Sets the label\'s horizontal position anchor',
+                'This anchor binds the specified `label.textposition` to the *left*, *center*',
+                'or *right* of the label text.',
+                'For example, if `label.textposition` is set to *top right* and',
+                '`xanchor` to *right* then the right-most portion of the',
+                'label text lines up with the right-most edge of the',
+                'shape.',
+            ].join(' '),
+        },
+        yanchor: {
+            valType: 'enumerated',
+            values: ['top', 'middle', 'bottom'],
+            editType: 'calc+arraydraw',
+            description: [
+                'Sets the label\'s vertical position anchor',
+                'This anchor binds the specified `label.textposition` to the *top*, *middle*',
+                'or *bottom* of the label text.',
+                'For example, if `label.textposition` is set to *top right* and',
+                '`yanchor` to *top* then the top-most portion of the',
+                'label text lines up with the top-most edge of the',
+                'shape.',
+            ].join(' ')
+        },
+        padding: {
+            valType: 'number',
+            dflt: 3,
+            min: 0,
+            editType: 'arraydraw',
+            description: 'Sets padding (in px) between edge of label and edge of shape.'
+        },
+        editType: 'arraydraw'
+    },
     editType: 'arraydraw'
 });

src/components/shapes/defaults.js

@@ -15,6 +15,15 @@ module.exports = function supplyLayoutDefaults(layoutIn, layoutOut) {
     });
 };
 
+function dfltLabelYanchor(isLine, labelTextPosition) {
+    // If shape is a line, default y-anchor is 'bottom' (so that text is above line by default)
+    // Otherwise, default y-anchor is equal to y-component of `textposition`
+    // (so that text is positioned inside shape bounding box by default)
+    return isLine ? 'bottom' :
+        labelTextPosition.indexOf('top') !== -1 ? 'top' :
+        labelTextPosition.indexOf('bottom') !== -1 ? 'bottom' : 'middle';
+}
+
 function handleShapeDefaults(shapeIn, shapeOut, fullLayout) {
     function coerce(attr, dflt) {
         return Lib.coerce(shapeIn, shapeOut, attributes, attr, dflt);
@@ -116,4 +125,16 @@ function handleShapeDefaults(shapeIn, shapeOut, fullLayout) {
     if(noPath) {
         Lib.noneOrAll(shapeIn, shapeOut, ['x0', 'x1', 'y0', 'y1']);
     }
+
+    // Label options
+    var isLine = shapeType === 'line';
+    var labelText = coerce('label.text');
+    if(labelText) {
+        coerce('label.textangle');
+        var labelTextPosition = coerce('label.textposition', isLine ? 'middle' : 'middle center');
+        coerce('label.xanchor');
+        coerce('label.yanchor', dfltLabelYanchor(isLine, labelTextPosition));
+        coerce('label.padding');
+        Lib.coerceFont(coerce, 'label.font', fullLayout.font);
+    }
 }