Merge pull request #7439 from plotly/unifiedhovertemplate

feat: Add `unifiedhovertitle` to format unified hover title

Author: archmoj

draftlogs/7439_add.md

@@ -0,0 +1 @@
+ - Add `unifiedhovertitle.text` to format unified hover titles [[#7439](https://github.com/plotly/plotly.js/pull/7439)]

src/components/fx/hover.js

@@ -1211,10 +1211,26 @@ function createHoverText(hoverData, opts) {
         // mock legend
         var hoverlabel = fullLayout.hoverlabel;
         var font = hoverlabel.font;
+
+        var item0 = groupedHoverData[0];
+
+        var unifiedhovertitleText = ((
+            hovermode === 'x unified' ?
+                item0.xa :
+                item0.ya
+            ).unifiedhovertitle || {}).text;
+
+        var mainText = !unifiedhovertitleText ? t0 :
+            Lib.hovertemplateString(unifiedhovertitleText, {}, fullLayout._d3locale,
+                hovermode === 'x unified' ?
+                    {xa: item0.xa, x: item0.xVal} :
+                    {ya: item0.ya, y: item0.yVal}
+        );
+
         var mockLayoutIn = {
             showlegend: true,
             legend: {
-                title: {text: t0, font: font},
+                title: {text: mainText, font: font},
                 font: font,
                 bgcolor: hoverlabel.bgcolor,
                 bordercolor: hoverlabel.bordercolor,

src/plots/cartesian/axis_defaults.js

@@ -100,7 +100,12 @@ module.exports = function handleAxisDefaults(containerIn, containerOut, coerce,
 
     handleCategoryOrderDefaults(containerIn, containerOut, coerce, options);
 
-    if(axType !== 'category' && !options.noHover) coerce('hoverformat');
+    if(!options.noHover) {
+        if(axType !== 'category') coerce('hoverformat');
+        if(!options.noUnifiedhovertitle) {
+            coerce('unifiedhovertitle.text');
+        }
+    }
 
     var dfltColor = coerce('color');
     // if axis.color was provided, use it for fonts too; otherwise,

src/plots/cartesian/layout_attributes.js

@@ -5,6 +5,7 @@ var colorAttrs = require('../../components/color/attributes');
 var dash = require('../../components/drawing/attributes').dash;
 var extendFlat = require('../../lib/extend').extendFlat;
 var templatedArray = require('../../plot_api/plot_template').templatedArray;
+var templateFormatStringDescription = require('../../plots/template_attributes').templateFormatStringDescription;
 var descriptionWithDates = require('../../plots/cartesian/axis_format_attributes').descriptionWithDates;
 
 var ONEDAY = require('../../constants/numerical').ONEDAY;
@@ -987,6 +988,18 @@ module.exports = {
         editType: 'none',
         description: descriptionWithDates('hover text')
     },
+    unifiedhovertitle: {
+        text : {
+            valType: 'string',
+            dflt: '',
+            editType: 'none',
+            description: [
+                'Template string used for rendering the title that appear on x or y unified hover box.',
+                templateFormatStringDescription()
+            ].join(' ')
+        },
+        editType: 'none'
+    },
     // lines and grids
     showline: {
         valType: 'boolean',

src/plots/gl3d/layout/axis_defaults.js

@@ -52,6 +52,7 @@ module.exports = function supplyLayoutDefaults(layoutIn, layoutOut, options) {
                 noTicklabelposition: true,
                 noTicklabeloverflow: true,
                 noInsiderange: true,
+                noUnifiedhovertitle: true,
                 bgColor: options.bgColor,
                 calendar: options.calendar
             },

src/plots/template_attributes.js

@@ -22,6 +22,7 @@ function templateFormatStringDescription(opts) {
         'for details on the date formatting syntax.'
     ].join(' ');
 }
+exports.templateFormatStringDescription = templateFormatStringDescription;
 
 function shapeTemplateFormatStringDescription() {
     return [

test/jasmine/tests/hover_label_test.js

@@ -6901,6 +6901,73 @@ describe('hovermode: (x|y)unified', function() {
             })
             .then(done, done.fail);
     });
+
+    it('should format title of unified hover in respect to `unifiedhovertitle` linear axis', function(done) {
+        Plotly.newPlot(gd, [{
+            type: 'bar',
+            y: [1, 2, 3]
+        }, {
+            type: 'scatter',
+            y: [2, 3, 1]
+        }], {
+            xaxis: {
+                unifiedhovertitle: { text: 'X: %{x:.2f}' },
+            },
+            hovermode: 'x unified',
+            showlegend: false,
+            width: 500,
+            height: 500,
+            margin: {
+                t: 50,
+                b: 50,
+                l: 50,
+                r: 50
+            }
+        })
+        .then(function() {
+            _hover(gd, { xpx: 200, ypx: 200 });
+            assertLabel({title: 'X: 1.00', items: [
+                'trace 0 : 2',
+                'trace 1 : 3'
+            ]});
+        })
+        .then(done, done.fail);
+    });
+
+    it('should format title of unified hover in respect to `unifiedhovertitle` date axis', function(done) {
+        Plotly.newPlot(gd, [{
+            type: 'bar',
+            x: ['2000-01-01', '2000-02-01', '2000-03-01'],
+            y: [1, 2, 3]
+        }, {
+            type: 'scatter',
+            x: ['2000-01-01', '2000-02-01', '2000-03-01'],
+            y: [2, 3, 1]
+        }], {
+            xaxis: {
+                type: 'date',
+                unifiedhovertitle: { text: 'X: %{x|%x %X}' },
+            },
+            hovermode: 'x unified',
+            showlegend: false,
+            width: 500,
+            height: 500,
+            margin: {
+                t: 50,
+                b: 50,
+                l: 50,
+                r: 50
+            }
+        })
+        .then(function() {
+            _hover(gd, { xpx: 200, ypx: 200 });
+            assertLabel({title: 'X: 02/01/2000 00:00:00', items: [
+                'trace 0 : 2',
+                'trace 1 : 3'
+            ]});
+        })
+        .then(done, done.fail);
+    });
 });
 
 describe('hover on traces with (x|y)hoverformat', function() {

test/plot-schema.json

@@ -14997,6 +14997,16 @@
      "editType": "none",
      "valType": "any"
     },
+    "unifiedhovertitle": {
+     "editType": "none",
+     "role": "object",
+     "text": {
+      "description": "Template string used for rendering the title that appear on x or y unified hover box. Variables are inserted using %{variable}, for example \"y: %{y}\". Numbers are formatted using d3-format's syntax %{variable:d3-format}, for example \"Price: %{y:$.2f}\". https://github.com/d3/d3-format/tree/v1.4.5#d3-format for details on the formatting syntax. Dates are formatted using d3-time-format's syntax %{variable|d3-time-format}, for example \"Day: %{2019-01-01|%A}\". https://github.com/d3/d3-time-format/tree/v2.2.3#locale_format for details on the date formatting syntax.",
+      "dflt": "",
+      "editType": "none",
+      "valType": "string"
+     }
+    },
     "visible": {
      "description": "A single toggle to hide the axis while preserving interaction like dragging. Default is true when a cheater plot is present on the axis, otherwise false",
      "editType": "plot",
@@ -16265,6 +16275,16 @@
      "editType": "none",
      "valType": "any"
     },
+    "unifiedhovertitle": {
+     "editType": "none",
+     "role": "object",
+     "text": {
+      "description": "Template string used for rendering the title that appear on x or y unified hover box. Variables are inserted using %{variable}, for example \"y: %{y}\". Numbers are formatted using d3-format's syntax %{variable:d3-format}, for example \"Price: %{y:$.2f}\". https://github.com/d3/d3-format/tree/v1.4.5#d3-format for details on the formatting syntax. Dates are formatted using d3-time-format's syntax %{variable|d3-time-format}, for example \"Day: %{2019-01-01|%A}\". https://github.com/d3/d3-time-format/tree/v2.2.3#locale_format for details on the date formatting syntax.",
+      "dflt": "",
+      "editType": "none",
+      "valType": "string"
+     }
+    },
     "visible": {
      "description": "A single toggle to hide the axis while preserving interaction like dragging. Default is true when a cheater plot is present on the axis, otherwise false",
      "editType": "plot",