@highcharts/grid-pro 2.1.1 → 2.3.0

package/es-modules/Core/Tooltip.js

@@ -1,10 +1,11 @@
 /* *
  *
- *  (c) 2010-2024 Torstein Honsi
+ *  (c) 2010-2026 Highsoft AS
+ *  Author: Torstein Honsi
  *
- *  License: www.highcharts.com/license
+ *  A commercial license may be required depending on use.
+ *  See www.highcharts.com/license
  *
- *  !!!!!!! SOURCE GETS TRANSPILED BY TYPESCRIPT. EDIT TS FILE ONLY. !!!!!!!
  *
  * */
 'use strict';
@@ -17,8 +18,16 @@ const { composed, dateFormats, doc, isSafari } = H;
 import R from './Renderer/RendererUtilities.js';
 const { distribute } = R;
 import RendererRegistry from './Renderer/RendererRegistry.js';
-import U from './Utilities.js';
-const { addEvent, clamp, css, clearTimeout, discardElement, extend, fireEvent, getAlignFactor, isArray, isNumber, isObject, isString, merge, pick, pushUnique, splat, syncTimeout } = U;
+import { addEvent, clamp, css, discardElement, extend, fireEvent, getAlignFactor, internalClearTimeout, isArray, isNumber, isObject, isString, merge, pick, pushUnique, splat, syncTimeout } from '../Shared/Utilities.js';
+/**
+ * Clear all timeouts for showing and hiding the tooltip.
+ *
+ * @internal
+ */
+const clearTimeouts = (tooltip) => {
+    clearTimeout(tooltip.hideTimer);
+    clearTimeout(tooltip.showTimer);
+};
 /* *
  *
  *  Class
@@ -53,11 +62,48 @@ class Tooltip {
          *
          * */
         this.allowShared = true;
+        /**
+         * List of crosshairs.
+         *
+         * @internal
+         * @readonly
+         * @name Highcharts.Tooltip#crosshairs
+         * @type {Array<null>}
+         */
         this.crosshairs = [];
         this.distance = 0;
+        /**
+         * Tooltips are initially hidden.
+         *
+         * @internal
+         * @readonly
+         * @name Highcharts.Tooltip#isHidden
+         * @type {boolean}
+         */
         this.isHidden = true;
         this.isSticky = false;
+        /**
+         * Used tooltip options.
+         *
+         * @readonly
+         * @name Highcharts.Tooltip#options
+         * @type {Highcharts.TooltipOptions}
+         */
         this.options = {};
+        /**
+         * 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 = false;
         this.chart = chart;
         this.init(chart, options);
@@ -73,21 +119,21 @@ class Tooltip {
      * returning one entry for each item, abstracting this functionality allows
      * to easily overwrite and extend it.
      *
-     * @private
+     * @internal
      * @function Highcharts.Tooltip#bodyFormatter
      */
     bodyFormatter(points) {
         return points.map((point) => {
             const tooltipOptions = point.series.tooltipOptions, formatPrefix = point.formatPrefix || 'point';
             return (tooltipOptions[formatPrefix + 'Formatter'] ||
-                point.tooltipFormatter).call(point, tooltipOptions[formatPrefix + 'Format'] || '');
+                point.tooltipFormatter).call(point, tooltipOptions[formatPrefix + 'Format'] || '', point);
         });
     }
     /**
      * Destroy the single tooltips in a split tooltip.
      * If the tooltip is active then it is not destroyed, unless forced to.
      *
-     * @private
+     * @internal
      * @function Highcharts.Tooltip#cleanSplit
      *
      * @param {boolean} [force]
@@ -112,7 +158,7 @@ class Tooltip {
      *
      * @function Highcharts.Tooltip#defaultFormatter
      *
-     * @param {Highcharts.Tooltip} tooltip
+     * @param {Highcharts.Tooltip} tooltip The tooltip instance.
      *
      * @return {string|Array<string>}
      * Returns a string (single tooltip and shared)
@@ -149,13 +195,14 @@ class Tooltip {
             this.renderer = this.renderer.destroy();
             discardElement(this.container);
         }
-        clearTimeout(this.hideTimer);
+        internalClearTimeout(this.hideTimer);
+        clearTimeouts(this);
     }
     /**
      * Extendable method to get the anchor position of the tooltip
      * from a point or set of points
      *
-     * @private
+     * @internal
      * @function Highcharts.Tooltip#getAnchor
      */
     getAnchor(points, mouseEvent) {
@@ -335,7 +382,7 @@ class Tooltip {
     /**
      * Get the total area available area to place the tooltip
      *
-     * @private
+     * @internal
      */
     getPlayingField() {
         const { body, documentElement } = doc, { chart, distance, outside } = this;
@@ -414,7 +461,7 @@ class Tooltip {
          * tooltip on top or bottom of the point, it will look for space
          * there.
          *
-         * @private
+         * @internal
          */
         firstDimension = function (dim, outerSize, innerSize, scaledInnerSize, // #11329
         point, min, max) {
@@ -446,7 +493,7 @@ class Tooltip {
          * align the tooltip above the point, trying to align center but
          * allowing left or right align within the chart box.
          *
-         * @private
+         * @internal
          */
         secondDimension = function (dim, outerSize, innerSize, scaledInnerSize, // #11329
         point) {
@@ -500,7 +547,7 @@ class Tooltip {
      * Place the tooltip when `position.fixed` is true. This is called both for
      * single tooltips, and for partial tooltips when `split`.
      *
-     * @private
+     * @internal
      */
     getFixedPosition(boxWidth, boxHeight, point) {
         const series = point.series, { chart, options, split } = this, position = options.position, relativeToOption = position.relativeTo, noPane = options.shared || series?.yAxis?.isRadial &&
@@ -530,7 +577,7 @@ class Tooltip {
     hide(delay) {
         const tooltip = this;
         // Disallow duplicate timers (#1728, #1766)
-        clearTimeout(this.hideTimer);
+        clearTimeouts(this);
         delay = pick(delay, this.options.hideDelay);
         if (!this.isHidden) {
             this.hideTimer = syncTimeout(function () {
@@ -558,7 +605,7 @@ class Tooltip {
     /**
      * Initialize tooltip.
      *
-     * @private
+     * @internal
      * @function Highcharts.Tooltip#init
      *
      * @param {Highcharts.Chart} chart
@@ -587,7 +634,7 @@ class Tooltip {
         /**
          * List of crosshairs.
          *
-         * @private
+         * @internal
          * @readonly
          * @name Highcharts.Tooltip#crosshairs
          * @type {Array<null>}
@@ -596,7 +643,7 @@ class Tooltip {
         /**
          * Tooltips are initially hidden.
          *
-         * @private
+         * @internal
          * @readonly
          * @name Highcharts.Tooltip#isHidden
          * @type {boolean}
@@ -644,7 +691,7 @@ class Tooltip {
     /**
      * Moves the tooltip with a soft animation to a new position.
      *
-     * @private
+     * @internal
      * @function Highcharts.Tooltip#move
      *
      * @param {number} x
@@ -689,7 +736,7 @@ class Tooltip {
         if (!options.enabled || !point.series) { // #16820
             return;
         }
-        clearTimeout(this.hideTimer);
+        clearTimeouts(this);
         // A switch saying if this specific tooltip configuration allows shared
         // or split modes
         tooltip.allowShared = !(!isArray(pointOrPoints) &&
@@ -709,7 +756,7 @@ class Tooltip {
         this.len = points.length; // #6128
         const text = isString(formatString) ?
             format(formatString, point, chart) :
-            formatter.call(point, tooltip);
+            formatter.call(point, tooltip, point);
         // Reset the preliminary circular references
         point.points = void 0;
         // Register the current series
@@ -720,79 +767,83 @@ class Tooltip {
             this.hide();
         }
         else {
-            // Update text
-            if (tooltip.split && tooltip.allowShared) { // #13868
-                this.renderSplit(text, points);
-            }
-            else {
-                let checkX = x;
-                let checkY = y;
-                if (mouseEvent && pointer.isDirectTouch) {
-                    checkX = mouseEvent.chartX - chart.plotLeft;
-                    checkY = mouseEvent.chartY - chart.plotTop;
+            this.showTimer = syncTimeout(() => {
+                // Update text
+                if (tooltip.split && tooltip.allowShared) { // #13868
+                    tooltip.renderSplit(text, points);
                 }
-                // #11493, #13095
-                if (chart.polar ||
-                    currentSeries.options.clip === false ||
-                    points.some((p) => // #16004
-                     pointer.isDirectTouch || // ##17929
-                        p.series.shouldShowTooltip(checkX, checkY))) {
-                    const label = tooltip.getLabel(wasShared && tooltip.tt || {});
-                    // Prevent the tooltip from flowing over the chart box
-                    // (#6659)
-                    if (!options.style.width || styledMode) {
-                        label.css({
-                            width: (this.outside ?
-                                this.getPlayingField() :
-                                chart.spacingBox).width + 'px'
-                        });
+                else {
+                    let checkX = x;
+                    let checkY = y;
+                    if (mouseEvent && pointer.isDirectTouch) {
+                        checkX = mouseEvent.chartX - chart.plotLeft;
+                        checkY = mouseEvent.chartY - chart.plotTop;
                     }
-                    label.attr({
-                        // Add class before the label BBox calculation (#21035)
-                        'class': tooltip.getClassName(point),
-                        text: text && text.join ?
-                            text.join('') :
-                            text
-                    });
-                    // When the length of the label has increased, immediately
-                    // update the x position to prevent tooltip from flowing
-                    // outside the viewport during animation (#21371)
-                    if (this.outside) {
+                    // #11493, #13095
+                    if (chart.polar ||
+                        currentSeries.options.clip === false ||
+                        points.some((p) => // #16004
+                         pointer.isDirectTouch || // ##17929
+                            p.series.shouldShowTooltip(checkX, checkY))) {
+                        const label = tooltip.getLabel(wasShared && tooltip.tt || {});
+                        // Prevent the tooltip from flowing over the chart box
+                        // (#6659)
+                        if (!options.style.width || styledMode) {
+                            label.css({
+                                width: (this.outside ?
+                                    this.getPlayingField() :
+                                    chart.spacingBox).width + 'px'
+                            });
+                        }
                         label.attr({
-                            x: clamp(label.x || 0, 0, this.getPlayingField().width -
-                                (label.width || 0) -
-                                1)
+                            // Add class before the label BBox calculation
+                            // (#21035)
+                            'class': tooltip.getClassName(point),
+                            text: isArray(text) ?
+                                text.join('') :
+                                text
                         });
-                    }
-                    if (!styledMode) {
-                        label.attr({
-                            stroke: (options.borderColor ||
-                                point.color ||
-                                currentSeries.color ||
-                                "#666666" /* Palette.neutralColor60 */)
+                        // When the length of the label has increased,
+                        // immediately update the x position to prevent
+                        // tooltip from flowing outside the viewport
+                        // during animation (#21371)
+                        if (this.outside) {
+                            label.attr({
+                                x: clamp(label.x || 0, 0, this.getPlayingField().width -
+                                    (label.width || 0) -
+                                    1)
+                            });
+                        }
+                        if (!styledMode) {
+                            label.attr({
+                                stroke: (options.borderColor ||
+                                    point.color ||
+                                    currentSeries.color ||
+                                    "#666666" /* Palette.neutralColor60 */)
+                            });
+                        }
+                        tooltip.updatePosition({
+                            plotX: x,
+                            plotY: y,
+                            negative: point.negative,
+                            ttBelow: point.ttBelow,
+                            series: currentSeries,
+                            h: anchor[2] || 0
                         });
                     }
-                    tooltip.updatePosition({
-                        plotX: x,
-                        plotY: y,
-                        negative: point.negative,
-                        ttBelow: point.ttBelow,
-                        series: currentSeries,
-                        h: anchor[2] || 0
-                    });
+                    else {
+                        tooltip.hide();
+                        return;
+                    }
                 }
-                else {
-                    tooltip.hide();
-                    return;
+                // Show it
+                if (tooltip.isHidden && tooltip.label) {
+                    tooltip.label.attr({
+                        opacity: 1
+                    }).show();
                 }
-            }
-            // Show it
-            if (tooltip.isHidden && tooltip.label) {
-                tooltip.label.attr({
-                    opacity: 1
-                }).show();
-            }
-            tooltip.isHidden = false;
+                tooltip.isHidden = false;
+            }, tooltip.isHidden ? options.showDelay || 0 : 0);
         }
         fireEvent(this, 'refresh');
     }
@@ -801,7 +852,7 @@ class Tooltip {
      * a label next to the point, then uses the distribute function to
      * find best non-overlapping positions.
      *
-     * @private
+     * @internal
      * @function Highcharts.Tooltip#renderSplit
      *
      * @param {string|Array<(boolean|string)>} labels
@@ -834,7 +885,7 @@ class Tooltip {
         /**
          * Calculates the anchor position for the partial tooltip
          *
-         * @private
+         * @internal
          * @param {Highcharts.Point} point The point related to the tooltip
          * @return {Object} Returns an object with anchorX and anchorY
          */
@@ -865,9 +916,9 @@ class Tooltip {
         }
         /**
          * Calculate the position of the partial tooltip
-         * @private
+         * @internal
          */
-        const defaultPositioner = function (boxWidth, boxHeight, point, anchor = [0, 0], alignedLeft = true) {
+        const defaultPositioner = function (boxWidth, boxHeight, point, ctx, anchor = [0, 0], alignedLeft = true) {
             let x, y;
             if (point.isHeader) {
                 y = headerTop ? 0 : adjustedPlotHeight;
@@ -892,7 +943,7 @@ class Tooltip {
          * Updates the attributes and styling of the partial tooltip. Creates a
          * new partial tooltip if it does not exists.
          *
-         * @private
+         * @internal
          * @param {Highcharts.SVGElement|undefined} partialTooltip
          *  The partial tooltip to update
          * @param {Highcharts.Point} point
@@ -967,7 +1018,7 @@ class Tooltip {
                 }
                 const { anchorX, anchorY } = getAnchor(point);
                 if (typeof anchorY === 'number') {
-                    const size = bBox.height + 1, boxPosition = (positioner || defaultPositioner).call(tooltip, boxWidth, size, point, [anchorX, anchorY]);
+                    const size = bBox.height + 1, boxPosition = (positioner || defaultPositioner).call(tooltip, boxWidth, size, point, tooltip, [anchorX, anchorY]);
                     boxes.push({
                         // 0-align to the top, 1-align to the bottom
                         align: hasFixedPosition ? 0 : void 0,
@@ -1005,7 +1056,7 @@ class Tooltip {
                 bounds.right - boxStart > boxStart;
         })) {
             boxes = boxes.map((box) => {
-                const { x, y } = defaultPositioner.call(this, box.boxWidth, box.size, box.point, [box.anchorX, box.anchorY], false);
+                const { x, y } = defaultPositioner.call(this, box.boxWidth, box.size, box.point, void 0, [box.anchorX, box.anchorY], false);
                 return extend(box, {
                     target: y,
                     x
@@ -1094,7 +1145,7 @@ class Tooltip {
     /**
      * If the `stickOnContact` option is active, this will add a tracker shape.
      *
-     * @private
+     * @internal
      * @function Highcharts.Tooltip#drawTracker
      */
     drawTracker() {
@@ -1142,9 +1193,7 @@ class Tooltip {
                 .add(label);
             // For a rapid move going outside of the elements keeping the
             // tooltip visible, cancel the hide (#23512).
-            addEvent(tooltip.tracker.element, 'mouseenter', () => {
-                clearTimeout(tooltip.hideTimer);
-            });
+            addEvent(tooltip.tracker.element, 'mouseenter', () => clearTimeouts(tooltip));
             if (!chart.styledMode) {
                 tooltip.tracker.attr({
                     fill: 'rgba(0,0,0,0)'
@@ -1152,9 +1201,7 @@ class Tooltip {
             }
         }
     }
-    /**
-     * @private
-     */
+    /** @internal */
     styledModeFormat(formatString) {
         return formatString
             .replace('style="font-size: 0.8em"', 'class="highcharts-header"')
@@ -1166,7 +1213,7 @@ class Tooltip {
      * Format the footer/header of the tooltip
      * #3397: abstraction to enable formatting of footer and header
      *
-     * @private
+     * @internal
      * @function Highcharts.Tooltip#headerFooterFormatter
      */
     headerFooterFormatter(point, isFooter) {
@@ -1215,17 +1262,17 @@ class Tooltip {
     /**
      * Find the new position and perform the move
      *
-     * @private
+     * @internal
      * @function Highcharts.Tooltip#updatePosition
      *
-     * @param {Highcharts.Point} point
+     * @param {Highcharts.Point} point The point object.
      */
     updatePosition(point) {
         const { chart, container, distance, options, pointer, renderer } = this, label = this.getLabel(), { height = 0, width = 0 } = label, { fixed, positioner } = options, 
         // Needed for outside: true (#11688)
         { left, top, scaleX, scaleY } = pointer.getChartPosition(), pos = (positioner ||
             (fixed && this.getFixedPosition) ||
-            this.getPosition).call(this, width, height, point), doc = H.doc;
+            this.getPosition).call(this, width, height, point, this), doc = H.doc;
         let anchorX = (point.plotX || 0) + chart.plotLeft, anchorY = (point.plotY || 0) + chart.plotTop, pad;
         // Set the renderer size dynamically to prevent document size to change.
         // Renderer only exists when tooltip is outside.
@@ -1277,9 +1324,7 @@ class Tooltip {
      *  Functions
      *
      * */
-    /**
-     * @private
-     */
+    /** @internal */
     function compose(PointerClass) {
         if (pushUnique(composed, 'Core.Tooltip')) {
             addEvent(PointerClass, 'afterInit', function () {
@@ -1326,6 +1371,10 @@ export default Tooltip;
  * @param {Highcharts.Tooltip} tooltip
  * The tooltip instance
  *
+ * @param {Highcharts.Point} [ctx]
+ * Since v12.5.0, the point context passed as an extra argument for arrow
+ * functions.
+ *
  * @return {false|string|Array<(string|null|undefined)>|null|undefined}
  * Formatted text or false
  */
@@ -1346,6 +1395,10 @@ export default Tooltip;
  * @param {Highcharts.TooltipPositionerPointObject} point
  * Point information for positioning a tooltip.
  *
+ * @param {Highcharts.Tooltip} [ctx]
+ * Since v12.5.0, the tooltip context passed as an extra argument for arrow
+ * functions.
+ *
  * @return {Highcharts.PositionObject}
  * New position for the tooltip.
  */