Support adding text labels to lines and shapes

draftlogs/6454_add.md

@@ -0,0 +1,2 @@
+ - Add `label` attribute to shapes [[#6454](https://github.com/plotly/plotly.js/pull/6454)], with thanks to 
+the [Volkswagen](https://www.volkswagenag.com) Center of Excellence for Battery Cells for sponsoring development!

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 `textposition` to the *left*, *center*',
+                'or *right* of the label text.',
+                'For example, if `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 `textposition` to the *top*, *middle*',
+                'or *bottom* of the label text.',
+                'For example, if `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);
+    }
 }

src/components/shapes/display_outlines.js

@@ -36,7 +36,7 @@ module.exports = function displayOutlines(polygons, outlines, dragOptions, nCall
         // recursive call
         displayOutlines(polygons, outlines, dragOptions, nCalls++);
 
-        if(pointsOnEllipse(polygons[0])) {
+        if(pointsOnEllipse(polygons[0]) || dragOptions.hasText) {
             update({redrawing: true});
         }
     }