highcharts 6.1.1 → 6.2.0

package/js/es-modules/parts/Tooltip.js

@@ -1,11 +1,14 @@
 /**
- * (c) 2010-2017 Torstein Honsi
+ * (c) 2010-2018 Torstein Honsi
  *
  * License: www.highcharts.com/license
  */
+
 'use strict';
+
 import H from './Globals.js';
 import './Utilities.js';
+
 var doc = H.doc,
     each = H.each,
     extend = H.extend,
@@ -17,10 +20,18 @@ var doc = H.doc,
     splat = H.splat,
     syncTimeout = H.syncTimeout,
     timeUnits = H.timeUnits;
+
 /**
- * The tooltip object
- * @param {Object} chart The chart instance
- * @param {Object} options Tooltip options
+ * Tooltip of a chart.
+ *
+ * @class
+ * @name Highcharts.Tooltip
+ *
+ * @param {Highcharts.Chart} chart
+ *        The chart instance.
+ *
+ * @param {Highcharts.TooltipOptions} options
+ *        Tooltip options.
  */
 H.Tooltip = function () {
     this.init.apply(this, arguments);
@@ -28,26 +39,99 @@ H.Tooltip = function () {
 
 H.Tooltip.prototype = {
 
+    /**
+     * @private
+     * @function Highcharts.Tooltip#init
+     *
+     * @param {Highcharts.Chart} chart
+     *        The chart instance.
+     *
+     * @param {Highcharts.TooltipOptions} options
+     *        Tooltip options.
+     */
     init: function (chart, options) {
 
-        // Save the chart and options
+        /**
+         * Chart of the tooltip.
+         *
+         * @readonly
+         * @name Highcharts.Tooltip#chart
+         * @type {Highcharts.Chart}
+         */
         this.chart = chart;
+
+        /**
+         * Used tooltip options.
+         *
+         * @readonly
+         * @name Highcharts.Tooltip#options
+         * @type {Highcharts.TooltipOptions}
+         */
         this.options = options;
 
-        // List of crosshairs
+        /**
+         * List of crosshairs.
+         *
+         * @private
+         * @readonly
+         * @name Highcharts.Tooltip#crosshairs
+         * @type {Array<*>}
+         */
         this.crosshairs = [];
 
-        // Current values of x and y when animating
+        /**
+         * Current values of x and y when animating.
+         *
+         * @private
+         * @readonly
+         * @name Highcharts.Tooltip#now
+         * @type {*}
+         */
         this.now = { x: 0, y: 0 };
 
-        // The tooltip is initially hidden
+        /**
+         * Tooltips are initially hidden.
+         *
+         * @readonly
+         * @name Highcharts.Tooltip#isHidden
+         * @type {boolean}
+         */
         this.isHidden = true;
 
-        // Public properties based on option combinations
+        /**
+         * True, if the tooltip is splitted into one label per series, with the
+         * header close to the axis.
+         *
+         * @readonly
+         * @name Highcharts.Tooltip#split
+         * @type {boolean}
+         */
         this.split = options.split && !chart.inverted;
+
+        /**
+         * When the tooltip is shared, the entire plot area will capture mouse
+         * movement or touch events.
+         *
+         * @readonly
+         * @name Highcharts.Tooltip#shared
+         * @type {boolean}
+         */
         this.shared = options.shared || this.split;
-        // Slit tooltip does not support outside in the first iteration. Should
-        // not be too complicated to implement.
+
+        /**
+         * Whether to allow the tooltip to render outside the chart's SVG
+         * element box. By default (false), the tooltip is rendered within the
+         * chart's SVG element, which results in the tooltip being aligned
+         * inside the chart area.
+         *
+         * @readonly
+         * @name Highcharts.Tooltip#outside
+         * @type {boolean}
+         *
+         * @todo
+         * Split tooltip does not support outside in the first iteration. Should
+         * not be too complicated to implement.
+         */
         this.outside = options.outside && !this.split;
 
     },
@@ -55,8 +139,12 @@ H.Tooltip.prototype = {
     /**
      * Destroy the single tooltips in a split tooltip.
      * If the tooltip is active then it is not destroyed, unless forced to.
-     * @param  {boolean} force Force destroy all tooltips.
-     * @return {undefined}
+     *
+     * @private
+     * @function Highcharts.Tooltip#cleanSplit
+     *
+     * @param {boolean} force
+     *        Force destroy all tooltips.
      */
     cleanSplit: function (force) {
         each(this.chart.series, function (series) {
@@ -72,11 +160,15 @@ H.Tooltip.prototype = {
     },
 
     
+
     /**
      * In styled mode, apply the default filter for the tooltip drop-shadow. It
      * needs to have an id specific to the chart, otherwise there will be issues
      * when one tooltip adopts the filter of a different chart, specifically one
      * where the container is hidden.
+     *
+     * @private
+     * @function Highcharts.Tooltip#applyFilter
      */
     applyFilter: function () {
 
@@ -117,12 +209,16 @@ H.Tooltip.prototype = {
             '}'
         });
     },
+
     
 
 
     /**
-     * Create the Tooltip label element if it doesn't exist, then return the
-     * label.
+     * Creates the Tooltip label element if it does not exist, then returns it.
+     *
+     * @function Highcharts.Tooltip#getLabel
+     *
+     * @return {Highcharts.SVGElement}
      */
     getLabel: function () {
 
@@ -138,7 +234,7 @@ H.Tooltip.prototype = {
                 H.css(container, {
                     position: 'absolute',
                     top: '1px',
-                    pointerEvents: 'none'
+                    pointerEvents: options.style && options.style.pointerEvents
                 });
                 H.doc.body.appendChild(container);
 
@@ -197,6 +293,13 @@ H.Tooltip.prototype = {
         return this.label;
     },
 
+    /**
+     * Updates the tooltip with the provided tooltip options.
+     *
+     * @function Highcharts.Tooltip#update
+     *
+     * @param {Highcharts.TooltipOptions} options
+     */
     update: function (options) {
         this.destroy();
         // Update user options (#6218)
@@ -205,7 +308,9 @@ H.Tooltip.prototype = {
     },
 
     /**
-     * Destroy the tooltip and its elements.
+     * Removes and destroys the tooltip and its elements.
+     *
+     * @function Highcharts.Tooltip#destroy
      */
     destroy: function () {
         // Destroy and clear local variables
@@ -225,11 +330,17 @@ H.Tooltip.prototype = {
     },
 
     /**
-     * Provide a soft movement for the tooltip
+     * Moves the tooltip with a soft animation to a new position.
      *
-     * @param {Number} x
-     * @param {Number} y
-     * @private
+     * @function Highcharts.Tooltip#move
+     *
+     * @param {number} x
+     *
+     * @param {number} y
+     *
+     * @param {number} anchorX
+     *
+     * @param {number} anchorY
      */
     move: function (x, y, anchorX, anchorY) {
         var tooltip = this,
@@ -276,7 +387,14 @@ H.Tooltip.prototype = {
     },
 
     /**
-     * Hide the tooltip
+     * Hides the tooltip with a fade out animation.
+     *
+     * @function Highcharts.Tooltip#hide
+     *
+     * @param {number} [delay]
+     *        The fade out in milliseconds. If no value is provided the value
+     *        of the tooltip.hideDelay option is used. A value of 0 disables
+     *        the fade out animation.
      */
     hide: function (delay) {
         var tooltip = this;
@@ -294,10 +412,18 @@ H.Tooltip.prototype = {
     /**
      * Extendable method to get the anchor position of the tooltip
      * from a point or set of points
+     *
+     * @private
+     * @function Highcharts.Tooltip#getAnchor
+     *
+     * @param {Array<Highchart.Points>} points
+     *
+     * @param {global.Event} [mouseEvent]
      */
     getAnchor: function (points, mouseEvent) {
         var ret,
             chart = this.chart,
+            pointer = chart.pointer,
             inverted = chart.inverted,
             plotTop = chart.plotTop,
             plotLeft = chart.plotLeft,
@@ -308,21 +434,20 @@ H.Tooltip.prototype = {
 
         points = splat(points);
 
-        // Pie uses a special tooltipPos
-        ret = points[0].tooltipPos;
-
         // When tooltip follows mouse, relate the position to the mouse
         if (this.followPointer && mouseEvent) {
             if (mouseEvent.chartX === undefined) {
-                mouseEvent = chart.pointer.normalize(mouseEvent);
+                mouseEvent = pointer.normalize(mouseEvent);
             }
             ret = [
                 mouseEvent.chartX - chart.plotLeft,
                 mouseEvent.chartY - plotTop
             ];
-        }
+        // Pie uses a special tooltipPos
+        } else if (points[0].tooltipPos) {
+            ret = points[0].tooltipPos;
         // When shared, use the average position
-        if (!ret) {
+        } else {
             each(points, function (point) {
                 yAxis = point.series.yAxis;
                 xAxis = point.series.xAxis;
@@ -355,6 +480,17 @@ H.Tooltip.prototype = {
     /**
      * Place the tooltip in a chart without spilling over
      * and not covering the point it self.
+     *
+     * @private
+     * @function Highcharts.Tooltip#getPosition
+     *
+     * @param {number} boxWidth
+     *
+     * @param {number} boxHeight
+     *
+     * @param {Highcharts.Point} point
+     *
+     * @return {*}
      */
     getPosition: function (boxWidth, boxHeight, point) {
 
@@ -403,10 +539,12 @@ H.Tooltip.prototype = {
                 !chart.inverted === !!point.negative
             ), // #4984
 
-            /**
+            /*
              * Handle the preferred dimension. When the preferred dimension is
              * tooltip on top or bottom of the point, it will look for space
              * there.
+             *
+             * @private
              */
             firstDimension = function (
                 dim,
@@ -441,11 +579,14 @@ H.Tooltip.prototype = {
                     return false;
                 }
             },
-            /**
+
+            /*
              * Handle the secondary dimension. If the preferred dimension is
              * tooltip on top or bottom of the point, the second dimension is to
              * align the tooltip above the point, trying to align center but
              * allowing left or right align within the chart box.
+             *
+             * @private
              */
             secondDimension = function (dim, outerSize, innerSize, point) {
                 var retVal;
@@ -465,7 +606,8 @@ H.Tooltip.prototype = {
                 }
                 return retVal;
             },
-            /**
+
+            /*
              * Swap the dimensions
              */
             swap = function (count) {
@@ -505,7 +647,12 @@ H.Tooltip.prototype = {
      * In case no user defined formatter is given, this will be used. Note that
      * the context here is an object holding point, series, x, y etc.
      *
-     * @returns {String|Array<String>}
+     * @private
+     * @function Highcharts.Tooltip#defaultFormatter
+     *
+     * @param {Highcharts.Tooltip} tooltip
+     *
+     * @return {Array<string>}
      */
     defaultFormatter: function (tooltip) {
         var items = this.points || splat(this),
@@ -525,7 +672,15 @@ H.Tooltip.prototype = {
 
     /**
      * Refresh the tooltip's text and position.
-     * @param {Object|Array} pointOrPoints Rither a point or an array of points
+     *
+     * @function Highcharts.Tooltip#refresh
+     *
+     * @param {Highcharts.Point|Array<Highcharts.Point>} pointOrPoints
+     *        Either a point or an array of points.
+     *
+     * @param {global.Event} [mouseEvent]
+     *        Mouse event, that is responsible for the refresh and should be
+     *        used for the tooltip update.
      */
     refresh: function (pointOrPoints, mouseEvent) {
         var tooltip = this,
@@ -637,6 +792,13 @@ H.Tooltip.prototype = {
      * Render the split tooltip. Loops over each point's text and adds
      * a label next to the point, then uses the distribute function to
      * find best non-overlapping positions.
+     *
+     * @private
+     * @function Highcharts.Tooltip#renderSplit
+     *
+     * @param {Array<Highcharts.Label>} labels
+     *
+     * @param {Array<Highcharts.Point>} points
      */
     renderSplit: function (labels, points) {
         var tooltip = this,
@@ -646,7 +808,9 @@ H.Tooltip.prototype = {
             rightAligned = true,
             options = this.options,
             headerHeight = 0,
-            tooltipLabel = this.getLabel();
+            headerTop,
+            tooltipLabel = this.getLabel(),
+            distributionBoxTop = chart.plotTop;
 
         // Graceful degradation for legacy formatters
         if (H.isString(labels)) {
@@ -683,7 +847,10 @@ H.Tooltip.prototype = {
                             null,
                             options.useHTML
                         )
-                        .addClass('highcharts-tooltip-box ' + colorClass)
+                        .addClass(
+                            'highcharts-tooltip-box ' + colorClass +
+                            (point.isHeader ? ' highcharts-tooltip-header' : '')
+                        )
                         .attr({
                             'padding': options.padding,
                             'r': options.borderRadius
@@ -704,12 +871,23 @@ H.Tooltip.prototype = {
                 boxWidth = bBox.width + tt.strokeWidth();
                 if (point.isHeader) {
                     headerHeight = bBox.height;
+                    if (chart.xAxis[0].opposite) {
+                        headerTop = true;
+                        distributionBoxTop -= headerHeight;
+                    }
                     x = Math.max(
                         0, // No left overflow
                         Math.min(
                             point.plotX + chart.plotLeft - boxWidth / 2,
                             // No right overflow (#5794)
-                            chart.chartWidth - boxWidth
+                            chart.chartWidth +
+                            (
+                                // Scrollable plot area
+                                chart.scrollablePixels ?
+                                    chart.scrollablePixels - chart.marginRight :
+                                    0
+                            ) -
+                            boxWidth
                         )
                     );
                 } else {
@@ -726,11 +904,15 @@ H.Tooltip.prototype = {
                 // Prepare for distribution
                 target = (point.series && point.series.yAxis &&
                     point.series.yAxis.pos) + (point.plotY || 0);
-                target -= chart.plotTop;
+                target -= distributionBoxTop;
+
+                if (point.isHeader) {
+                    target = headerTop ?
+                        -headerHeight :
+                        chart.plotHeight + headerHeight;
+                }
                 boxes.push({
-                    target: point.isHeader ?
-                        chart.plotHeight + headerHeight :
-                        target,
+                    target: target,
                     rank: point.isHeader ? 1 : 0,
                     size: owner.tt.getBBox().height + 1,
                     point: point,
@@ -755,12 +937,12 @@ H.Tooltip.prototype = {
                 x: (rightAligned || point.isHeader ?
                     box.x :
                     point.plotX + chart.plotLeft + pick(options.distance, 16)),
-                y: box.pos + chart.plotTop,
+                y: box.pos + distributionBoxTop,
                 anchorX: point.isHeader ?
                     point.plotX + chart.plotLeft :
                     point.plotX + series.xAxis.pos,
                 anchorY: point.isHeader ?
-                    box.pos + chart.plotTop - 15 :
+                    chart.plotTop + chart.plotHeight / 2 :
                     point.plotY + series.yAxis.pos
             });
         });
@@ -768,6 +950,11 @@ H.Tooltip.prototype = {
 
     /**
      * Find the new position and perform the move
+     *
+     * @private
+     * @function Highcharts.Tooltip#updatePosition
+     *
+     * @param {Highcharts.Point} point
      */
     updatePosition: function (point) {
         var chart = this.chart,
@@ -805,12 +992,25 @@ H.Tooltip.prototype = {
 
     /**
      * Get the optimal date format for a point, based on a range.
-     * @param  {number} range - The time range
-     * @param  {number|Date} date - The date of the point in question
-     * @param  {number} startOfWeek - An integer representing the first day of
-     * the week, where 0 is Sunday
-     * @param  {Object} dateTimeLabelFormats - A map of time units to formats
-     * @return {string} - the optimal date format for a point
+     *
+     * @private
+     * @function Highcharts.Tooltip#getDateFormat
+     *
+     * @param {number} range
+     *        The time range
+     *
+     * @param {number|Date} date
+     *        The date of the point in question
+     *
+     * @param {number} startOfWeek
+     *        An integer representing the first day of the week, where 0 is
+     *        Sunday.
+     *
+     * @param {Highcharts.Dictionary<string>} dateTimeLabelFormats
+     *        A map of time units to formats.
+     *
+     * @return {string}
+     *         The optimal date format for a point.
      */
     getDateFormat: function (range, date, startOfWeek, dateTimeLabelFormats) {
         var time = this.chart.time,
@@ -862,7 +1062,7 @@ H.Tooltip.prototype = {
         }
 
         if (n) {
-            format = dateTimeLabelFormats[n];
+            format = time.resolveDTLFormat(dateTimeLabelFormats[n]).main;
         }
 
         return format;
@@ -870,6 +1070,17 @@ H.Tooltip.prototype = {
 
     /**
      * Get the best X date format based on the closest point range on the axis.
+     *
+     * @private
+     * @function Highcharts.Tooltip#getXDateFormat
+     *
+     * @param {Highcharts.Point} point
+     *
+     * @param {Highcharts.TooltipOptions} options
+     *
+     * @param {Highcharts.Axis} xAxis
+     *
+     * @return {string}
      */
     getXDateFormat: function (point, options, xAxis) {
         var xDateFormat,
@@ -893,6 +1104,15 @@ H.Tooltip.prototype = {
     /**
      * Format the footer/header of the tooltip
      * #3397: abstraction to enable formatting of footer and header
+     *
+     * @private
+     * @function Highcharts.Tooltip#tooltipFooterHeaderFormatter
+     *
+     * @param {*} labelConfig
+     *
+     * @param {boolean} isFooter
+     *
+     * @return {string}
      */
     tooltipFooterHeaderFormatter: function (labelConfig, isFooter) {
         var footOrHead = isFooter ? 'footer' : 'header',
@@ -941,6 +1161,13 @@ H.Tooltip.prototype = {
      * Build the body (lines) of the tooltip by iterating over the items and
      * returning one entry for each item, abstracting this functionality allows
      * to easily overwrite and extend it.
+     *
+     * @private
+     * @function Highcharts.Tooltip#bodyFormatter
+     *
+     * @param {Array<Highcharts.Point>} items
+     *
+     * @return {string}
      */
     bodyFormatter: function (items) {
         return map(items, function (item) {