Support adding text labels to lines and shapes

[emilykl]

Text on Shapes feature

Expand the Shape API to support adding a text label to any line or shape.

Labels can be styled similarly to text annotations, and support options for setting their position relative to the shape or line.

Proposed API

Here is the proposed API for Text on Shapes, as discussed with @alexcjohnson :

• label : Top-level property to be added to shape, holding all label options
  • text : The label’s text
  • font : The label’s font properties (same properties as for Annotation)
    • color
    • family
    • size
  • position : The label’s position relative to the shape. Possible values: [ left | center | right ] [ top | middle | bottom ] ; OR [ start | end ] for lines
  • textangle : Rotation angle of the label. Possible values : number between -180 and 180 ; OR [ auto ] for lines (same angle as line)
  • xanchor : The x-component of the anchor point on the label used to determine position (in the pre-rotated reference frame). Possible values : [ left | center | right ]
  • yanchor : The y-component of the anchor point on the label used to determine position (in the pre-rotated reference frame). Possible values : [ top | middle | bottom ]
  • padding : Offset of label relative to xanchor and yanchor (symmetrical on all sides)

cc @alexcjohnson @archmoj

Revised 10 Jan 2023: Changed angle property name to textangle

To-dos

• Add above properties to shape attributes
• Implement basic functionality of rendering text relative to shape position
• Properly handle re-render on pan/zoom
• Properly handle re-render on shape move
• Implement xanchor
• Implement yanchor
• Implement padding
• Implement position
• Implement textangle
  • Numeric angles
  • auto angle for lines
• Implement font
• Correctly handle multiline labels
• Correctly handle clipping outside plot area
• Properly set defaults for all properties
• Add image test
• Add Jasmine test

Partnership

Development of this feature is sponsored by Volkswagen's Center of Excellence for Battery Systems.

[emilykl]

Quick comparison of the above to the annotations API:

• ✅ The properties text, font, xanchor, and yanchor have the same names and functions for annotations
  • Note: xanchor and yanchor support the value auto in addition; worth considering whether we should add auto as a value for xanchor and yanchor here (although the auto behavior would probably be different)
• ❓ angle is called textangle for annotations — should we change the name here for consistency?
• ❓ position and padding don't really have equivalents for annotations (annotations have borderpad, but that's specifically for border appearance)
• ❓Top level label property name is up for debate — it also doesn't have an equivalent for annotations since all annotations properties are already at the top level

[emilykl]

Note: This work will not cover MathJax support for shape text.