Adding the ability to specify the tail of an annotation arrow in absolute point in grid terms rather than relative pixel offset terms.

Author: MFed

src/components/annotations/attributes.js

@@ -131,14 +131,31 @@ module.exports = {
         role: 'style',
         description: 'Sets the width (in px) of annotation arrow.'
     },
+    absolutetail: {
+        valType: 'boolean',
+        dflt: false,
+        role: 'style',
+        description: [
+            'Indicates if the tail of this arrow is a point in ',
+            'the coordinate system vs a relative offset in pixels.',
+            'This is useful for trendline annotations which should ',
+            'continue to indicate the correct trend when zoomed.',
+            'If *true*, `ax` is a value on the x axis and `ay` is ',
+            'a value on the y axis.',
+            'If *false*, `ax` and `ay` assume their normal offset ',
+            'roles.'
+        ].join(' ')
+    },
     ax: {
         valType: 'number',
         dflt: -10,
         role: 'info',
         description: [
             'Sets the x component of the arrow tail about the arrow head.',
-            'A positive (negative) component corresponds to an arrow pointing',
-            'from right to left (left to right)'
+            'If `absolutetail` is false, a positive (negative) ',
+            'component corresponds to an arrow pointing',
+            'from right to left (left to right).',
+            'If `absolutetail` is true, this is a value on the x axis.'
         ].join(' ')
     },
     ay: {
@@ -147,8 +164,10 @@ module.exports = {
         role: 'info',
         description: [
             'Sets the y component of the arrow tail about the arrow head.',
-            'A positive (negative) component corresponds to an arrow pointing',
-            'from bottom to top (top to bottom)'
+            'If `absolutetail` is false, a positive (negative) ',
+            'component corresponds to an arrow pointing',
+            'from bottom to top (top to bottom).',
+            'If `absolutetail` is true, this is a value on the y axis.'
         ].join(' ')
     },
     // positioning

src/components/annotations/index.js

@@ -59,6 +59,7 @@ function handleAnnotationDefaults(annIn, fullLayout) {
         coerce('arrowwidth', ((borderOpacity && borderWidth) || 1) * 2);
         coerce('ax');
         coerce('ay');
+        coerce('absolutetail');
 
         // if you have one part of arrow length you should have both
         Lib.noneOrAll(annIn, annOut, ['ax', 'ay']);
@@ -89,6 +90,11 @@ function handleAnnotationDefaults(annIn, fullLayout) {
                 if(ax.type === 'date') {
                     newval = Lib.dateTime2ms(annIn[axLetter]);
                     if(newval !== false) annIn[axLetter] = newval;
+
+                    if(annIn.absolutetail) {
+                        var newvalB = Lib.dateTime2ms(annIn['a' + axLetter]);
+                        if(newvalB !== false) annIn['a' + axLetter] = newvalB;
+                    }
                 }
                 else if((ax._categories || []).length) {
                     newval = ax._categories.indexOf(annIn[axLetter]);
@@ -450,13 +456,17 @@ annotations.draw = function(gd, index, opt, value) {
             }
 
             var alignShift = 0;
-            if(options.showarrow) {
-                alignShift = options['a' + axLetter];
-            }
-            else {
-                alignShift = annSize * shiftFraction(alignPosition, anchor);
+            if(options.absolutetail) {
+                annPosPx['aa' + axLetter] = ax._offset + ax.l2p(options['a' + axLetter]);
+            } else {
+                if(options.showarrow) {
+                    alignShift = options['a' + axLetter];
+                }
+                else {
+                    alignShift = annSize * shiftFraction(alignPosition, anchor);
+                }
+                annPosPx[axLetter] += alignShift;
             }
-            annPosPx[axLetter] += alignShift;
 
             // save the current axis type for later log/linear changes
             options['_' + axLetter + 'type'] = ax && ax.type;
@@ -476,8 +486,13 @@ annotations.draw = function(gd, index, opt, value) {
         // make sure the arrowhead (if there is one)
         // and the annotation center are visible
         if(options.showarrow) {
-            arrowX = Lib.constrain(annPosPx.x - options.ax, 1, fullLayout.width - 1);
-            arrowY = Lib.constrain(annPosPx.y - options.ay, 1, fullLayout.height - 1);
+            if(options.absolutetail) {
+                arrowX = Lib.constrain(annPosPx.x, 1, fullLayout.width - 1);
+                arrowY = Lib.constrain(annPosPx.y, 1, fullLayout.height - 1);
+            } else {
+                arrowX = Lib.constrain(annPosPx.x - options.ax, 1, fullLayout.width - 1);
+                arrowY = Lib.constrain(annPosPx.y - options.ay, 1, fullLayout.height - 1);
+            }
         }
         annPosPx.x = Lib.constrain(annPosPx.x, 1, fullLayout.width - 1);
         annPosPx.y = Lib.constrain(annPosPx.y, 1, fullLayout.height - 1);
@@ -496,8 +511,15 @@ annotations.draw = function(gd, index, opt, value) {
         annbg.call(Drawing.setRect, borderwidth / 2, borderwidth / 2,
             outerwidth - borderwidth, outerheight - borderwidth);
 
-        var annX = Math.round(annPosPx.x - outerwidth / 2),
+        var annX = 0, annY = 0;
+        if(options.absolutetail) {
+            annX = Math.round(annPosPx.aax - outerwidth / 2);
+            annY = Math.round(annPosPx.aay - outerheight / 2);
+        } else {
+            annX = Math.round(annPosPx.x - outerwidth / 2);
             annY = Math.round(annPosPx.y - outerheight / 2);
+        }
+
         ann.call(Lib.setTranslate, annX, annY);
 
         var annbase = 'annotations[' + index + ']';
@@ -515,11 +537,18 @@ annotations.draw = function(gd, index, opt, value) {
             // looks like there may be a cross-browser solution, see
             // http://stackoverflow.com/questions/5364980/
             //    how-to-get-the-width-of-an-svg-tspan-element
-            var arrowX0 = annPosPx.x + dx,
-                arrowY0 = annPosPx.y + dy,
+            var arrowX0, arrowY0;
+
+            if(options.absolutetail) {
+                arrowX0 = annPosPx.aax + dx;
+                arrowY0 = annPosPx.aay + dy;
+            } else {
+                arrowX0 = annPosPx.x + dx;
+                arrowY0 = annPosPx.y + dy;
+            }
 
                 // create transform matrix and related functions
-                transform =
+            var transform =
                     Lib.rotationXYMatrix(textangle, arrowX0, arrowY0),
                 applyTransform = Lib.apply2DTransform(transform),
                 applyTransform2 = Lib.apply2DTransform2(transform),
@@ -618,6 +647,15 @@ annotations.draw = function(gd, index, opt, value) {
                             (options.y + dy / ya._m) :
                             (1 - ((arrowY + dy - gs.t) / gs.h));
 
+                        if(options.absolutetail) {
+                            update[annbase + '.ax'] = xa ?
+                              (options.ax + dx / xa._m) :
+                              ((arrowX + dx - gs.l) / gs.w);
+                            update[annbase + '.ay'] = ya ?
+                              (options.ay + dy / ya._m) :
+                              (1 - ((arrowY + dy - gs.t) / gs.h));
+                        }
+
                         anng.attr({
                             transform: 'rotate(' + textangle + ',' +
                                    xcenter + ',' + ycenter + ')'
@@ -660,8 +698,13 @@ annotations.draw = function(gd, index, opt, value) {
                     ann.call(Lib.setTranslate, x0 + dx, y0 + dy);
                     var csr = 'pointer';
                     if(options.showarrow) {
-                        update[annbase + '.ax'] = options.ax + dx;
-                        update[annbase + '.ay'] = options.ay + dy;
+                        if(options.absolutetail) {
+                            update[annbase + '.ax'] = xa.p2l(xa.l2p(options.ax) + dx);
+                            update[annbase + '.ay'] = ya.p2l(ya.l2p(options.ay) + dy);
+                        } else {
+                            update[annbase + '.ax'] = options.ax + dx;
+                            update[annbase + '.ay'] = options.ay + dy;
+                        }
                         drawArrow(dx, dy);
                     }
                     else {

test/image/baselines/annotations.png

@@ -41,7 +41,8 @@
                 "bordercolor":"rgb(255, 0, 0)","borderwidth":4,"bgcolor":"rgba(255,255,0,0.5)",
                 "font":{"color":"rgb(0, 0, 255)","size":20},
                 "arrowcolor":"rgb(166, 28, 0)","borderpad":3,"textangle":50,"x":5,"y":1
-            }
+            },
+            {"text":"","showarrow":true,"borderwidth":1.2,"arrowhead":2,"absolutetail":true,"x":5,"y":5,"ax":4,"ay":3}
         ]
     }
 }

test/image/mocks/annotations.json

@@ -0,0 +1,31 @@
+var Plots = require('@src/plots/plots');
+var Annotations = require('@src/components/annotations');
+
+
+describe('Test annotations', function() {
+    'use strict';
+
+    describe('supplyLayoutDefaults', function() {
+        it('should default to not use absolute arrow tail', function() {
+            var annotationDefaults = {};
+            annotationDefaults._has = Plots._hasPlotType.bind(annotationDefaults);
+
+            Annotations.supplyLayoutDefaults({ annotations: [{ showarrow: true, arrowhead: 2}] }, annotationDefaults);
+
+            expect(annotationDefaults.annotations[0].absolutetail).toBe(false);
+        });
+
+        it('should convert ax/ay date coordinates to milliseconds if absolutetail is true', function() {
+            var annotationOut = { xaxis: { type: 'date', range: ['2000-01-01', '2016-01-01'] }};
+            annotationOut._has = Plots._hasPlotType.bind(annotationOut);
+
+            var annotationIn = {
+                annotations: [{ showarrow: true, absolutetail: true, x: '2008-07-01', ax: '2004-07-01', y: 0, ay: 50}]
+            };
+
+            Annotations.supplyLayoutDefaults(annotationIn, annotationOut);
+
+            expect(annotationIn.annotations[0].ax).toEqual(1088654400000);
+        });
+    });
+});