add title to legend

archmoj · archmoj · commit 9174470bb967 · 2019-11-25T14:44:05.000-05:00
diff --git a/src/components/legend/attributes.js b/src/components/legend/attributes.js
@@ -193,5 +193,38 @@ module.exports = {
             'Sets the vertical alignment of the symbols with respect to their associated text.',
         ].join(' ')
     },
+    title: {
+        text: {
+            valType: 'string',
+            dflt: '',
+            role: 'info',
+            editType: 'legend',
+            description: [
+                'Sets the title of the legend.'
+            ].join(' ')
+        },
+        font: fontAttrs({
+            editType: 'legend',
+            description: [
+                'Sets this legend\'s title font.'
+            ].join(' '),
+        }),
+        side: {
+            valType: 'enumerated',
+            values: ['top', 'left', 'top left'],
+            role: 'style',
+            editType: 'legend',
+            description: [
+                'Determines the location of legend\'s title',
+                'with respect to the legend items.',
+                'Defaulted to *top* with `orientation` is *h*.',
+                'Defaulted to *left* with `orientation` is *v*.',
+                'The *top left* options could be used to expand',
+                'legend area in both x and y sides.'
+            ].join(' ')
+        },
+        editType: 'legend',
+    },
+
     editType: 'legend'
 };
diff --git a/src/components/legend/constants.js b/src/components/legend/constants.js
@@ -15,6 +15,8 @@ module.exports = {
     scrollBarMargin: 4,
     scrollBarEnterAttrs: {rx: 20, ry: 3, width: 0, height: 0},
 
+    // number of px between legend title and (left) side of legend (always in x direction and from inner border)
+    titlePad: 2,
     // number of px between legend symbol and legend text (always in x direction)
     textGap: 40,
     // number of px between each legend item (x and/or y direction)
diff --git a/src/components/legend/defaults.js b/src/components/legend/defaults.js
@@ -116,4 +116,10 @@ module.exports = function legendDefaults(layoutIn, layoutOut, fullData) {
     coerce('yanchor', defaultYAnchor);
     coerce('valign');
     Lib.noneOrAll(containerIn, containerOut, ['x', 'y']);
+
+    var titleText = coerce('title.text');
+    if(titleText) {
+        coerce('title.side', orientation === 'h' ? 'left' : 'top');
+        Lib.coerceFont(coerce, 'title.font', layoutOut.font);
+    }
 };
diff --git a/src/components/legend/draw.js b/src/components/legend/draw.js
@@ -63,6 +63,19 @@ module.exports = function draw(gd) {
         .call(Color.fill, opts.bgcolor)
         .style('stroke-width', opts.borderwidth + 'px');
 
+
+    var title = fullLayout.legend.title;
+    gd._fullLayout._legendTitleWidth = 0;
+    gd._fullLayout._legendTitleHeight = 0;
+    if(title.text) {
+        var titleEl = Lib.ensureSingle(legend, 'text', 'legendtitletext');
+        titleEl.attr('text-anchor', 'start')
+            .classed('user-select-none', true)
+            .call(Drawing.font, title.font)
+            .text(title.text);
+
+        textLayout(titleEl, legend, gd); // handle mathjax or multi-line text and compute title height
+    }
     var scrollBox = Lib.ensureSingle(legend, 'g', 'scrollbox');
 
     var scrollBar = Lib.ensureSingle(legend, 'rect', 'scrollbar', function(s) {
@@ -121,7 +134,7 @@ module.exports = function draw(gd) {
             }
 
             // Set size and position of all the elements that make up a legend:
-            // legend, background and border, scroll box and scroll bar
+            // legend, background and border, scroll box and scroll bar as well as title
             Drawing.setTranslate(legend, lx, ly);
 
             // to be safe, remove previous listeners
@@ -375,18 +388,12 @@ function drawTexts(g, gd) {
 
     svgTextUtils.positionText(textEl, constants.textGap, 0);
 
-    function textLayout(s) {
-        svgTextUtils.convertToTspans(s, gd, function() {
-            computeTextDimensions(g, gd);
-        });
-    }
-
     if(isEditable) {
         textEl.call(svgTextUtils.makeEditable, {gd: gd, text: name})
-            .call(textLayout)
+            .call(textLayout, g, gd)
             .on('edit', function(newName) {
                 this.text(ensureLength(newName, maxNameLength))
-                    .call(textLayout);
+                    .call(textLayout, g, gd);
 
                 var fullInput = legendItem.trace._fullInput || {};
                 var update = {};
@@ -407,7 +414,7 @@ function drawTexts(g, gd) {
                 return Registry.call('_guiRestyle', gd, update, traceIndex);
             });
     } else {
-        textLayout(textEl);
+        textLayout(textEl, g, gd);
     }
 }
 
@@ -460,17 +467,25 @@ function setupTraceToggle(g, gd) {
     });
 }
 
+function textLayout(s, g, gd) {
+    svgTextUtils.convertToTspans(s, gd, function() {
+        computeTextDimensions(g, gd);
+    });
+}
+
 function computeTextDimensions(g, gd) {
     var legendItem = g.data()[0][0];
-
-    if(!legendItem.trace.showlegend) {
+    if(legendItem && !legendItem.trace.showlegend) {
         g.remove();
         return;
     }
 
     var mathjaxGroup = g.select('g[class*=math-group]');
     var mathjaxNode = mathjaxGroup.node();
-    var opts = gd._fullLayout.legend;
+    var bw = gd._fullLayout.legend.borderwidth;
+    var opts = legendItem ?
+        gd._fullLayout.legend :
+        gd._fullLayout.legend.title;
     var lineHeight = opts.font.size * LINE_SPACING;
     var height, width;
 
@@ -480,24 +495,43 @@ function computeTextDimensions(g, gd) {
         height = mathjaxBB.height;
         width = mathjaxBB.width;
 
-        Drawing.setTranslate(mathjaxGroup, 0, (height / 4));
+        if(legendItem) {
+            Drawing.setTranslate(mathjaxGroup, 0, height * 0.25);
+        } else { // case of title
+            Drawing.setTranslate(mathjaxGroup, bw, height * 0.75 + bw);
+        }
     } else {
-        var text = g.select('.legendtext');
-        var textLines = svgTextUtils.lineCount(text);
-        var textNode = text.node();
+        var textEl = g.select(legendItem ?
+            '.legendtext' : '.legendtitletext'
+        );
+        var textLines = svgTextUtils.lineCount(textEl);
+        var textNode = textEl.node();
 
         height = lineHeight * textLines;
         width = textNode ? Drawing.bBox(textNode).width : 0;
 
         // approximation to height offset to center the font
         // to avoid getBoundingClientRect
-        var textY = lineHeight * (0.3 + (1 - textLines) / 2);
-        svgTextUtils.positionText(text, constants.textGap, textY);
+        var textY = lineHeight * ((textLines - 1) / 2 - 0.3);
+        if(legendItem) {
+            svgTextUtils.positionText(textEl, constants.textGap, -textY);
+        } else { // case of title
+            svgTextUtils.positionText(textEl, constants.titlePad + bw, lineHeight + bw);
+        }
     }
 
-    legendItem.lineHeight = lineHeight;
-    legendItem.height = Math.max(height, 16) + 3;
-    legendItem.width = width;
+    if(legendItem) {
+        legendItem.lineHeight = lineHeight;
+        legendItem.height = Math.max(height, 16) + 3;
+        legendItem.width = width;
+    } else { // case of title
+        if(opts.side.indexOf('left') !== -1) {
+            gd._fullLayout._legendTitleWidth = width;
+        }
+        if(opts.side.indexOf('top') !== -1) {
+            gd._fullLayout._legendTitleHeight = height;
+        }
+    }
 }
 
 /*
@@ -514,6 +548,9 @@ function computeLegendDimensions(gd, groups, traces) {
     var fullLayout = gd._fullLayout;
     var opts = fullLayout.legend;
     var gs = fullLayout._size;
+    opts._titleWidth = fullLayout._legendTitleWidth;
+    opts._titleHeight = fullLayout._legendTitleHeight;
+
     var isVertical = helpers.isVertical(opts);
     var isGrouped = helpers.isGrouped(opts);
 
@@ -541,7 +578,10 @@ function computeLegendDimensions(gd, groups, traces) {
     if(isVertical) {
         traces.each(function(d) {
             var h = d[0].height;
-            Drawing.setTranslate(this, bw, itemGap + bw + opts._height + h / 2);
+            Drawing.setTranslate(this,
+                bw + opts._titleWidth,
+                bw + opts._titleHeight + opts._height + h / 2 + itemGap
+            );
             opts._height += h;
             opts._width = Math.max(opts._width, d[0].width);
         });
@@ -591,7 +631,10 @@ function computeLegendDimensions(gd, groups, traces) {
                 var offsetY = 0;
                 d3.select(this).selectAll('g.traces').each(function(d) {
                     var h = d[0].height;
-                    Drawing.setTranslate(this, 0, itemGap + bw + h / 2 + offsetY);
+                    Drawing.setTranslate(this,
+                        opts._titleWidth,
+                        bw + opts._titleHeight + itemGap + h / 2 + offsetY
+                    );
                     offsetY += h;
                     maxWidthInGroup = Math.max(maxWidthInGroup, textGap + d[0].width);
                 });
@@ -634,7 +677,10 @@ function computeLegendDimensions(gd, groups, traces) {
                     maxItemHeightInRow = 0;
                 }
 
-                Drawing.setTranslate(this, bw + offsetX, itemGap + bw + h / 2 + offsetY);
+                Drawing.setTranslate(this,
+                    bw + opts._titleWidth + offsetX,
+                    bw + opts._titleHeight + offsetY + h / 2 + itemGap
+                );
 
                 rowWidth = offsetX + w + itemGap;
                 offsetX += next;
@@ -651,8 +697,8 @@ function computeLegendDimensions(gd, groups, traces) {
         }
     }
 
-    opts._width = Math.ceil(opts._width);
-    opts._height = Math.ceil(opts._height);
+    opts._width = Math.ceil(opts._width + opts._titleWidth);
+    opts._height = Math.ceil(opts._height + opts._titleHeight);
 
     opts._effHeight = Math.min(opts._height, opts._maxHeight);
 
diff --git a/test/jasmine/tests/legend_test.js b/test/jasmine/tests/legend_test.js
@@ -172,6 +172,44 @@ describe('legend defaults', function() {
         expect(layoutOut.legend.orientation).toEqual('v');
     });
 
+    it('should not coerce `title.font` and `title.side` if the `title.text` is blank', function() {
+        var layoutWithTitle = Lib.extendDeep({
+            legend: {
+                title: {
+                    text: ''
+                }
+            }
+        }, layoutIn);
+        supplyLayoutDefaults(layoutWithTitle, layoutOut, []);
+        expect(layoutOut.legend.title.font).toEqual(undefined);
+        expect(layoutOut.legend.title.side).toEqual(undefined);
+    });
+
+    it('should default `title.side` to *top* for vertical legends', function() {
+        var layoutWithTitle = Lib.extendDeep({
+            legend: {
+                title: {
+                    text: 'Legend Title'
+                }
+            }
+        }, layoutIn);
+        supplyLayoutDefaults(layoutWithTitle, layoutOut, []);
+        expect(layoutOut.legend.title.side).toEqual('top');
+    });
+
+    it('should default `title.side` to *left* for horizontal legends', function() {
+        var layoutWithTitle = Lib.extendDeep({
+            legend: {
+                orientation: 'h',
+                title: {
+                    text: 'Legend Title'
+                }
+            }
+        }, layoutIn);
+        supplyLayoutDefaults(layoutWithTitle, layoutOut, []);
+        expect(layoutOut.legend.title.side).toEqual('left');
+    });
+
     describe('for horizontal legends', function() {
         var layoutInForHorizontalLegends;
 
