in legend implement group titles

Author: archmoj

src/components/legend/draw.js

@@ -393,20 +393,26 @@ function drawTexts(g, gd, legendObj) {
     var isEditable = !legendObj._inHover && gd._context.edits.legendText && !isPieLike;
     var maxNameLength = legendObj._maxNameLength;
 
-    var name;
-    if(!legendObj.entries) {
-        name = isPieLike ? legendItem.label : trace.name;
-        if(trace._meta) {
-            name = Lib.templateString(name, trace._meta);
-        }
+    var name, font;
+    if(legendItem.groupTitle) {
+        name = legendItem.groupTitle.text;
+        font = legendItem.groupTitle.font;
     } else {
-        name = legendItem.text;
+        font = legendObj.font;
+        if(!legendObj.entries) {
+            name = isPieLike ? legendItem.label : trace.name;
+            if(trace._meta) {
+                name = Lib.templateString(name, trace._meta);
+            }
+        } else {
+            name = legendItem.text;
+        }
     }
 
     var textEl = Lib.ensureSingle(g, 'text', 'legendtext');
 
     textEl.attr('text-anchor', 'start')
-        .call(Drawing.font, legendObj.font)
+        .call(Drawing.font, font)
         .text(isEditable ? ensureLength(name, maxNameLength) : name);
 
     var textGap = legendObj.itemwidth + constants.itemGap * 2;
@@ -512,7 +518,15 @@ function computeTextDimensions(g, gd, legendObj, aTitle) {
     var mathjaxNode = mathjaxGroup.node();
     if(!legendObj) legendObj = gd._fullLayout.legend;
     var bw = legendObj.borderwidth;
-    var lineHeight = (aTitle === MAIN_TITLE ? legendObj.title : legendObj).font.size * LINE_SPACING;
+    var font;
+    if(aTitle === MAIN_TITLE) {
+        font = legendObj.title.font;
+    } else if(legendItem.groupTitle) {
+        font = legendItem.groupTitle.font;
+    } else {
+        font = legendObj.font;
+    }
+    var lineHeight = font.size * LINE_SPACING;
     var height, width;
 
     if(mathjaxNode) {
@@ -549,8 +563,14 @@ function computeTextDimensions(g, gd, legendObj, aTitle) {
                 bw + lineHeight
             );
         } else { // legend item
+            var x = constants.itemGap * 2 + legendObj.itemwidth;
+            if(legendItem.groupTitle) {
+                x = constants.itemGap;
+                width -= legendObj.itemwidth;
+            }
+
             svgTextUtils.positionText(textEl,
-                legendObj.itemwidth + constants.itemGap * 2,
+                x,
                 -lineHeight * ((textLines - 1) / 2 - 0.3)
             );
         }

src/components/legend/get_legend_data.js

@@ -119,6 +119,28 @@ module.exports = function getLegendData(calcdata, opts) {
         legendData[i].sort(orderFn2);
         if(reversed) legendData[i].reverse();
 
+        var firstItem = legendData[i][0];
+
+        var groupTitle = null;
+        // set group title text
+        for(j = 0; j < legendData[i].length; j++) {
+            var gt = legendData[i][j].trace.legendgrouptitle;
+            if(gt && gt.text) {
+                groupTitle = gt;
+                break;
+            }
+        }
+
+        if(groupTitle) {
+            legendData[i].unshift({
+                i: -1,
+                groupTitle: groupTitle,
+                trace: {
+                    showlegend: firstItem.trace.showlegend
+                }
+            });
+        }
+
         // rearrange lgroupToTraces into a d3-friendly array of arrays
         for(j = 0; j < legendData[i].length; j++) {
             legendData[i][j] = [

src/components/legend/handle_click.js

@@ -32,6 +32,8 @@ module.exports = function handleClick(g, gd, numClicks) {
         [];
 
     var legendItem = g.data()[0][0];
+    if(legendItem.groupTitle) return; // no click on group legends for now
+
     var fullData = gd._fullData;
     var fullTrace = legendItem.trace;
     var legendgroup = fullTrace.legendgroup;

src/plots/attributes.js

@@ -1,5 +1,6 @@
 'use strict';
 
+var fontAttrs = require('./font_attributes');
 var fxAttrs = require('../components/fx/attributes');
 
 module.exports = {
@@ -41,6 +42,23 @@ module.exports = {
             'when toggling legend items.'
         ].join(' ')
     },
+    legendgrouptitle: {
+        text: {
+            valType: 'string',
+            dflt: '',
+            editType: 'style',
+            description: [
+                'Sets the title of the legend group.'
+            ].join(' ')
+        },
+        font: fontAttrs({
+            editType: 'style',
+            description: [
+                'Sets this legend group\'s title font.'
+            ].join(' '),
+        }),
+        editType: 'style',
+    },
     legendrank: {
         valType: 'number',
         dflt: 1000,

src/plots/plots.js

@@ -1309,6 +1309,13 @@ plots.supplyTraceDefaults = function(traceIn, traceOut, colorIndex, layout, trac
             );
 
             coerce('legendgroup');
+            var titleText = coerce('legendgrouptitle.text');
+            if(titleText) {
+                Lib.coerceFont(coerce, 'legendgrouptitle.font', Lib.extendFlat({}, layout.font, {
+                    size: Math.round(layout.font.size * 1.1) // default to larger font size
+                }));
+            }
+
             coerce('legendrank');
 
             traceOut._dfltShowLegend = true;

test/image/baselines/legendgroup-titles-pie.png

@@ -0,0 +1,73 @@
+{
+    "data": [
+        {
+            "type": "pie",
+            "domain": {
+                "y": [0.8, 1]
+            },
+            "labels": [0],
+            "legendgroup": "G1"
+        },
+        {
+            "type": "pie",
+            "domain": {
+                "y": [0.6, 0.8]
+            },
+            "labels": [1],
+            "legendgroup": "G1"
+        },
+        {
+            "type": "pie",
+            "domain": {
+                "y": [0.4, 0.6]
+            },
+            "labels": [2],
+            "legendgroup": "G1",
+            "legendgrouptitle": {
+                "text": "First group"
+            }
+        },
+        {
+            "type": "pie",
+            "domain": {
+                "y": [0.2, 0.4]
+            },
+            "labels": [3],
+            "legendgroup": "G2",
+            "legendgrouptitle": {
+                "text": "Second group"
+            }
+        },
+        {
+            "domain": {
+                "y": [0, 0.2]
+            },
+            "type": "pie",
+            "labels": [4, 5],
+            "legendgroup": "G3",
+            "legendgrouptitle": {
+                "text": "Third group"
+            }
+        }
+    ],
+    "layout": {
+        "title": {
+            "text": "legend group titles"
+        },
+        "margin": {
+            "t": 50,
+            "b": 25,
+            "l": 25,
+            "r": 25
+        },
+        "width": 300,
+        "height": 300,
+        "legend": {
+            "bgcolor": "lightblue",
+            "title": {
+                "text": ""
+            }
+        },
+        "hovermode": "x unified"
+    }
+}

test/image/baselines/legendgroup-titles.png

@@ -0,0 +1,64 @@
+{
+    "data": [
+        {
+            "y": [0],
+            "legendgroup": "G1"
+        },
+        {
+            "y": [1],
+            "legendgroup": "G1"
+        },
+        {
+            "y": [2],
+            "legendgroup": "G1",
+            "legendgrouptitle": {
+                "text": "First group"
+            }
+        },
+        {
+            "y": [3],
+            "legendgroup": "G2",
+            "legendgrouptitle": {
+                "text": "Second<br>group",
+                "font": {
+                    "family": "Raleway",
+                    "size": 14
+                }
+            }
+        },
+        {
+            "y": [4],
+            "legendgroup": "G3",
+            "legendgrouptitle": {
+                "text": "Third group"
+            }
+        },
+        {
+            "y": [5],
+            "legendgroup": "G3"
+        }
+    ],
+    "layout": {
+        "title": {
+            "text": "legend group titles"
+        },
+        "margin": {
+            "t": 50,
+            "b": 25,
+            "l": 25,
+            "r": 25
+        },
+        "width": 300,
+        "height": 300,
+        "yaxis": {
+            "autorange": "reversed"
+        },
+        "legend": {
+            "bgcolor": "lightblue",
+            "title": {
+                "text": ""
+            }
+        },
+        "hovermode": "x unified"
+    }
+}