@highcharts/grid-pro 2.1.1 → 2.3.0

package/es-modules/Core/Chart/Chart.js

@@ -1,10 +1,11 @@
 /* *
  *
- *  (c) 2010-2025 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';
@@ -25,10 +26,10 @@ import SeriesRegistry from '../Series/SeriesRegistry.js';
 const { seriesTypes } = SeriesRegistry;
 import SVGRenderer from '../Renderer/SVG/SVGRenderer.js';
 import Time from '../Time.js';
-import U from '../Utilities.js';
 import AST from '../Renderer/HTML/AST.js';
 import Tick from '../Axis/Tick.js';
-const { addEvent, attr, createElement, css, defined, diffObjects, discardElement, erase, error, extend, find, fireEvent, getAlignFactor, getStyle, isArray, isNumber, isObject, isString, merge, objectEach, pick, pInt, relativeLength, removeEvent, splat, syncTimeout, uniqueKey } = U;
+import { addEvent, attr, createElement, css, defined, diffObjects, discardElement, erase, extend, find, fireEvent, getAlignFactor, getStyle, internalClearTimeout, isArray, isNumber, isObject, isString, merge, objectEach, pick, pInt, relativeLength, removeEvent, splat, syncTimeout } from '../../Shared/Utilities.js';
+import { error, uniqueKey } from '../Utilities.js';
 /* *
  *
  *  Class
@@ -104,7 +105,13 @@ class Chart {
     b, c
     /* eslint-enable @typescript-eslint/no-unused-vars */
     ) {
+        /** @internal */
         this.sharedClips = {};
+        // Return early if there's no browser API (server environment).
+        if (!doc) {
+            error(36, false, this);
+            return;
+        }
         const args = [
             // ES5 builds fail unless we cast it to an Array
             ...arguments
@@ -124,7 +131,7 @@ class Chart {
      * Function setting zoom options after chart init and after chart update.
      * Offers support for deprecated options.
      *
-     * @private
+     * @internal
      * @function Highcharts.Chart#setZoomOptions
      */
     setZoomOptions() {
@@ -151,7 +158,6 @@ class Chart {
      *        Function to run when the chart has loaded and all external
      *        images are loaded.
      *
-     *
      * @emits Highcharts.Chart#event:init
      * @emits Highcharts.Chart#event:afterInit
      */
@@ -291,7 +297,7 @@ class Chart {
     /**
      * Internal function to initialize an individual series.
      *
-     * @private
+     * @internal
      * @function Highcharts.Chart#initSeries
      */
     initSeries(options) {
@@ -310,7 +316,7 @@ class Chart {
     /**
      * Internal function to set data for all series with enabled sorting.
      *
-     * @private
+     * @internal
      * @function Highcharts.Chart#setSortedData
      */
     setSortedData() {
@@ -325,7 +331,7 @@ class Chart {
      * Sort and return chart series in order depending on the number of linked
      * series.
      *
-     * @private
+     * @internal
      * @function Highcharts.Series#getSeriesOrderByLinks
      */
     getSeriesOrderByLinks() {
@@ -342,9 +348,12 @@ class Chart {
      * (#248, #1123, #2456, #6112). This function is called on series and axis
      * initialization and destroy.
      *
-     * @private
+     * @internal
      * @function Highcharts.Chart#orderItems
-     * @param {string} coll The collection name
+     *
+     * @param {string} coll
+     * The collection name.
+     *
      * @param {number} [fromIndex=0]
      * If this is given, only the series above this index are handled.
      */
@@ -365,13 +374,6 @@ class Chart {
             for (let i = fromIndex, iEnd = collection.length; i < iEnd; ++i) {
                 const item = collection[i];
                 if (item) {
-                    /**
-                     * Contains the series' index in the `Chart.series` array.
-                     *
-                     * @name Highcharts.Series#index
-                     * @type {number}
-                     * @readonly
-                     */
                     item.index = i;
                     if (item instanceof Series) {
                         item.name = item.getName();
@@ -388,7 +390,7 @@ class Chart {
      * Get the clipping for a series. Could be called for a series to initialate
      * animating the clip or to set the final clip (only width and x).
      *
-     * @private
+     * @internal
      * @function Highcharts.Chart#getClipBox
      */
     getClipBox(series, chartCoords) {
@@ -639,9 +641,7 @@ class Chart {
      */
     get(id) {
         const series = this.series;
-        /**
-         * @private
-         */
+        /** @internal */
         function itemById(item) {
             return (item.id === id ||
                 (item.options && item.options.id === id));
@@ -660,7 +660,7 @@ class Chart {
     /**
      * Create the Axis instances based on the config options.
      *
-     * @private
+     * @internal
      * @function Highcharts.Chart#createAxes
      * @emits Highcharts.Chart#event:afterCreateAxes
      * @emits Highcharts.Chart#event:createAxes
@@ -759,10 +759,12 @@ class Chart {
     /**
      * Apply a title, subtitle or caption for the chart
      *
-     * @private
+     * @internal
      * @function Highcharts.Chart#applyDescription
-     * @param key {string}
+     *
+     * @param {string} key
      * Either title, subtitle or caption
+     *
      * @param {Highcharts.TitleOptions|Highcharts.SubtitleOptions|Highcharts.CaptionOptions|undefined} explicitOptions
      * The options to set, will be merged with default options.
      */
@@ -828,10 +830,11 @@ class Chart {
      * cache the full offset height for use in `getMargins`. The result is
      * stored in `this.titleOffset`.
      *
-     * @private
+     * @internal
      * @function Highcharts.Chart#layOutTitles
      *
      * @param {boolean} [redraw=true]
+     *
      * @emits Highcharts.Chart#event:afterLayOutTitles
      */
     layOutTitles(redraw = true) {
@@ -929,7 +932,7 @@ class Chart {
     /**
      * Internal function to get the available size of the container element
      *
-     * @private
+     * @internal
      * @function Highcharts.Chart#getContainerBox
      */
     getContainerBox() {
@@ -955,7 +958,7 @@ class Chart {
      * and container size. Sets {@link Chart.chartWidth} and
      * {@link Chart.chartHeight}.
      *
-     * @private
+     * @internal
      * @function Highcharts.Chart#getChartSize
      */
     getChartSize() {
@@ -988,7 +991,7 @@ class Chart {
      * parents, then save the original display properties, and when the true
      * size is retrieved, reset them. Used on first render and on redraws.
      *
-     * @private
+     * @internal
      * @function Highcharts.Chart#temporaryDisplay
      *
      * @param {boolean} [revert]
@@ -1063,7 +1066,7 @@ class Chart {
      * Get the containing element, determine the size and create the inner
      * container div to hold the chart.
      *
-     * @private
+     * @internal
      * @function Highcharts.Chart#afterGetContainer
      * @emits Highcharts.Chart#event:afterGetContainer
      */
@@ -1177,7 +1180,7 @@ class Chart {
      * Title, subtitle and legend have already been rendered at this stage, but
      * will be moved into their final positions.
      *
-     * @private
+     * @internal
      * @function Highcharts.Chart#getMargins
      * @emits Highcharts.Chart#event:getMargins
      */
@@ -1201,7 +1204,7 @@ class Chart {
         }
     }
     /**
-     * @private
+     * @internal
      * @function Highcharts.Chart#getAxisMargins
      */
     getAxisMargins() {
@@ -1272,7 +1275,7 @@ class Chart {
             containerBox.width) {
             if (containerBox.width !== oldBox.width ||
                 containerBox.height !== oldBox.height) {
-                U.clearTimeout(chart.reflowTimeout);
+                internalClearTimeout(chart.reflowTimeout);
                 // When called from window.resize, e is set, else it's called
                 // directly (#2224)
                 chart.reflowTimeout = syncTimeout(function () {
@@ -1290,7 +1293,7 @@ class Chart {
      * Toggle the event handlers necessary for auto resizing, depending on the
      * `chart.reflow` option.
      *
-     * @private
+     * @internal
      * @function Highcharts.Chart#setReflow
      */
     setReflow() {
@@ -1401,7 +1404,7 @@ class Chart {
      * Set the public chart properties. This is done before and after the
      * pre-render to determine margin sizes.
      *
-     * @private
+     * @internal
      * @function Highcharts.Chart#setChartSize
      * @emits Highcharts.Chart#event:afterSetChartSize
      */
@@ -1472,7 +1475,7 @@ class Chart {
     /**
      * Initial margins before auto size margins are applied.
      *
-     * @private
+     * @internal
      * @function Highcharts.Chart#resetMargins
      */
     resetMargins() {
@@ -1509,7 +1512,7 @@ class Chart {
      * Internal function to draw or redraw the borders and backgrounds for chart
      * and plot area.
      *
-     * @private
+     * @internal
      * @function Highcharts.Chart#drawChartBox
      * @emits Highcharts.Chart#event:afterDrawChartBox
      */
@@ -1618,7 +1621,7 @@ class Chart {
      * options and series. This mainly applies to the chart.inverted property,
      * and in extensions to the chart.angular and chart.polar properties.
      *
-     * @private
+     * @internal
      * @function Highcharts.Chart#propFromSeries
      */
     propFromSeries() {
@@ -1657,7 +1660,7 @@ class Chart {
      * `linkedTo` option. This is done from `Chart.render`, and after
      * `Chart.addSeries` and `Series.remove`.
      *
-     * @private
+     * @internal
      * @function Highcharts.Chart#linkSeries
      * @emits Highcharts.Chart#event:afterLinkSeries
      */
@@ -1676,15 +1679,6 @@ class Chart {
                 // #3341 avoid mutual linking
                 linkedParent.linkedParent !== series) {
                 linkedParent.linkedSeries.push(series);
-                /**
-                 * The parent series of the current series, if the current
-                 * series has a [linkedTo](https://api.highcharts.com/highcharts/series.line.linkedTo)
-                 * setting.
-                 *
-                 * @name Highcharts.Series#linkedParent
-                 * @type {Highcharts.Series}
-                 * @readonly
-                 */
                 series.linkedParent = linkedParent;
                 if (linkedParent.enabledDataSorting) {
                     series.setDataSortingOptions();
@@ -1699,7 +1693,7 @@ class Chart {
     /**
      * Render series for the chart.
      *
-     * @private
+     * @internal
      * @function Highcharts.Chart#renderSeries
      */
     renderSeries() {
@@ -1711,7 +1705,7 @@ class Chart {
     /**
      * Render all graphics for the chart. Runs internally on initialization.
      *
-     * @private
+     * @internal
      * @function Highcharts.Chart#render
      */
     render() {
@@ -1767,14 +1761,25 @@ class Chart {
         while ((redoHorizontal || redoVertical || axisLayoutRuns > 1) &&
             run < axisLayoutRuns // #19794
         ) {
-            const tempWidth = chart.plotWidth, tempHeight = chart.plotHeight;
+            const tempWidth = chart.plotWidth, tempHeight = chart.plotHeight, threshold = [1.05, 1.1];
             for (const axis of axes) {
+                const horizNum = +(axis.horiz || 0);
                 if (run === 0) {
                     // Get margins by pre-rendering axes
                     axis.setScale();
+                    // On datetime axes, consider the tick interval match. A
+                    // match close to 1 means that the current normalized tick
+                    // interval is an insecure match to the requested tick
+                    // interval, on the brink of landing on a higher unit. In
+                    // this case, we should redo the axis to get a more
+                    // appropriate tick interval (#17393).
+                    const tickIntervalMatch = axis.tickPositions?.info?.match;
+                    if (tickIntervalMatch) {
+                        threshold[horizNum] = Math.min(tickIntervalMatch, threshold[horizNum]);
+                    }
                 }
-                else if ((axis.horiz && redoHorizontal) ||
-                    (!axis.horiz && redoVertical)) {
+                else if ((horizNum && redoHorizontal) ||
+                    (!horizNum && redoVertical)) {
                     // Update to reflect the new margins
                     axis.setTickInterval(true);
                 }
@@ -1786,8 +1791,10 @@ class Chart {
                 // Check again for new, rotated or moved labels
                 chart.getMargins();
             }
-            redoHorizontal = (tempWidth / chart.plotWidth) > (run ? 1 : 1.1);
-            redoVertical = (tempHeight / chart.plotHeight) > (run ? 1 : 1.05);
+            redoHorizontal = (tempWidth / chart.plotWidth) >
+                (run ? 1 : threshold[1]);
+            redoVertical = (tempHeight / chart.plotHeight) >
+                (run ? 1 : threshold[0]);
             run++;
         }
         // Draw the borders and backgrounds
@@ -1838,15 +1845,22 @@ class Chart {
              */
             this.credits = this.renderer.text(creds.text + (this.mapCredits || ''), 0, 0)
                 .addClass('highcharts-credits')
-                .on('click', function () {
-                if (creds.href) {
-                    win.location.href = creds.href;
-                }
+                .on('click', function (e) {
+                // Fire the event with browser redirect as default function
+                fireEvent(chart, 'creditsClick', e, () => {
+                    if (creds.href) {
+                        win.location.href = creds.href;
+                    }
+                });
             })
                 .attr({
                 align: creds.position.align,
                 zIndex: 8
             });
+            // If creds.events?.click exists, add it as an event listener
+            if (creds.events?.click) {
+                addEvent(chart, 'creditsClick', creds.events.click);
+            }
             if (!chart.styledMode) {
                 this.credits.css(creds.style);
             }
@@ -1929,7 +1943,7 @@ class Chart {
     /**
      * Prepare for first rendering after all data are loaded.
      *
-     * @private
+     * @internal
      * @function Highcharts.Chart#firstRender
      * @emits Highcharts.Chart#event:beforeRender
      */
@@ -1961,7 +1975,7 @@ class Chart {
         chart.render();
         chart.pointer?.getChartPosition(); // #14973
         // Fire the load event if there are no external images
-        if (!chart.renderer.imgCount && !chart.hasLoaded) {
+        if (!chart.renderer.asyncCounter && !chart.hasLoaded) {
             chart.onload();
         }
         // If the chart was rendered outside the top container, put it back in
@@ -1973,7 +1987,7 @@ class Chart {
      * in the chart. Runs the callbacks and triggers the `load` and `render`
      * events.
      *
-     * @private
+     * @internal
      * @function Highcharts.Chart#onload
      * @emits Highcharts.Chart#event:load
      * @emits Highcharts.Chart#event:render
@@ -1999,7 +2013,7 @@ class Chart {
     }
     /**
      * Emit console warning if the a11y module is not loaded.
-     * @private
+     * @internal
      */
     warnIfA11yModuleNotLoaded() {
         const { options, title } = this;
@@ -2022,7 +2036,7 @@ class Chart {
     }
     /**
      * Emit console warning if the highcharts.css file is not loaded.
-     * @private
+     * @internal
      */
     warnIfCSSNotLoaded() {
         if (this.styledMode) {
@@ -2148,17 +2162,17 @@ class Chart {
     /**
      * Factory for creating different axis types.
      *
-     * @private
+     * @internal
      * @function Highcharts.Chart#createAxis
      *
      * @param {string} coll
-     *        An axis type.
+     * An axis type.
      *
      * @param {...Array<*>} arguments
-     *        All arguments for the constructor.
+     * All arguments for the constructor.
      *
      * @return {Highcharts.Axis}
-     *         The newly generated Axis object.
+     * The newly generated Axis object.
      */
     createAxis(coll, options) {
         const axis = new Axis(this, options.axis, coll);
@@ -2187,13 +2201,13 @@ class Chart {
      *        [lang.loading](https://api.highcharts.com/highcharts/lang.loading).
      */
     showLoading(str) {
-        const chart = this, options = chart.options, loadingOptions = options.loading, setLoadingSize = function () {
+        const chart = this, options = chart.options, loadingOptions = options.loading, loadingStyle = loadingOptions?.style ?? {}, setLoadingSize = function () {
             if (loadingDiv) {
                 css(loadingDiv, {
-                    left: chart.plotLeft + 'px',
-                    top: chart.plotTop + 'px',
-                    width: chart.plotWidth + 'px',
-                    height: chart.plotHeight + 'px'
+                    left: loadingStyle.left ?? chart.plotLeft + 'px',
+                    top: loadingStyle.top ?? chart.plotTop + 'px',
+                    width: loadingStyle.width ?? chart.plotWidth + 'px',
+                    height: loadingStyle.height ?? chart.plotHeight + 'px'
                 });
             }
         };
@@ -2213,10 +2227,8 @@ class Chart {
         AST.setElementHTML(loadingSpan, pick(str, options.lang.loading, ''));
         if (!chart.styledMode) {
             // Update visuals
-            css(loadingDiv, extend(loadingOptions.style, {
-                zIndex: 10
-            }));
-            css(loadingSpan, loadingOptions.labelStyle);
+            css(loadingDiv, extend(loadingStyle, { zIndex: 10 }));
+            css(loadingSpan, loadingOptions?.labelStyle ?? {});
             // Show it
             if (!chart.loadingShown) {
                 css(loadingDiv, {
@@ -2224,9 +2236,9 @@ class Chart {
                     display: ''
                 });
                 animate(loadingDiv, {
-                    opacity: loadingOptions.style.opacity || 0.5
+                    opacity: loadingStyle.opacity ?? 0.5
                 }, {
-                    duration: loadingOptions.showDuration || 0
+                    duration: loadingOptions?.showDuration ?? 0
                 });
             }
         }
@@ -2254,7 +2266,7 @@ class Chart {
                 animate(loadingDiv, {
                     opacity: 0
                 }, {
-                    duration: options.loading.hideDuration || 100,
+                    duration: options.loading?.hideDuration ?? 100,
                     complete: function () {
                         css(loadingDiv, { display: 'none' });
                     }
@@ -2423,9 +2435,12 @@ class Chart {
         // update the first series in the chart. Setting two series without
         // an id will update the first and the second respectively (#6019)
         // chart.update and responsive.
-        this.collectionsWithUpdate.forEach(function (coll) {
+        this.collectionsWithUpdate.forEach((coll) => {
             if (options[coll]) {
-                splat(options[coll]).forEach(function (newOptions, i) {
+                splat(options[coll]).forEach((newOptions, i) => {
+                    if (!newOptions) {
+                        return;
+                    }
                     const hasId = defined(newOptions.id);
                     let item;
                     // Match by id
@@ -2464,7 +2479,7 @@ class Chart {
                 });
                 // Add items for removal
                 if (oneToOne) {
-                    chart[coll].forEach(function (item) {
+                    chart[coll].forEach((item) => {
                         if (!item.touched && !item.options.isInternal) {
                             itemsForRemoval.push(item);
                         }
@@ -2475,7 +2490,7 @@ class Chart {
                 }
             }
         });
-        itemsForRemoval.forEach(function (item) {
+        itemsForRemoval.forEach((item) => {
             if (item.chart && item.remove) { // #9097, avoid removing twice
                 item.remove(false);
             }
@@ -2561,9 +2576,7 @@ class Chart {
             btnOptions.relativeTo === 'spacingBox' ?
             null :
             'plotBox');
-        /**
-         * @private
-         */
+        /** @internal */
         function zoomOut() {
             chart.zoomOut();
         }
@@ -2596,7 +2609,7 @@ class Chart {
      * called on mouse move, and the distance to pan is computed from chartX
      * compared to the first chartX position in the dragging operation.
      *
-     * @private
+     * @internal
      * @function Highcharts.Chart#pan
      * @param {Highcharts.PointerEventObject} event
      * @param {string} panning
@@ -2643,7 +2656,7 @@ class Chart {
      * - In a mousewheel zoom, the `to` rectangle is a 10x10 px square,
      *   while the `to` rectangle reflects the scale around that.
      *
-     * @private
+     * @internal
      * @function Highcharts.Chart#transform
      */
     transform(params) {
@@ -2813,7 +2826,7 @@ extend(Chart.prototype, {
      * Note: We need to define these references after initializers are bound to
      * chart's prototype.
      *
-     * @private
+     * @internal
      */
     collectionsWithInit: {
         // CollectionName: [ initializingMethod, [extraArguments] ]
@@ -2824,7 +2837,7 @@ extend(Chart.prototype, {
     /**
      * These collections (arrays) implement update() methods with support for
      * one-to-one option.
-     * @private
+     * @internal
      */
     collectionsWithUpdate: [
         'xAxis',
@@ -2834,7 +2847,7 @@ extend(Chart.prototype, {
     /**
      * These properties cause isDirtyBox to be set to true when updating. Can be
      * extended from plugins.
-     * @private
+     * @internal
      */
     propsRequireDirtyBox: [
         'backgroundColor',
@@ -2851,7 +2864,7 @@ extend(Chart.prototype, {
     /**
      * These properties require a full reflow of chart elements, best
      * implemented through running `Chart.setSize` internally (#8190).
-     * @private
+     * @internal
      */
     propsRequireReflow: [
         'margin',
@@ -2868,7 +2881,7 @@ extend(Chart.prototype, {
     /**
      * These properties cause all series to be updated when updating. Can be
      * extended from plugins.
-     * @private
+     * @internal
      */
     propsRequireUpdateSeries: [
         'chart.inverted',
@@ -2920,6 +2933,10 @@ export default Chart;
  *        The thousands separator, defaults to the one given in the lang
  *        options, or a space character.
  *
+ * @param {Highcharts.Chart} [ctx]
+ *        Since v12.5.0, the chart context passed as an extra argument for
+ *        arrow functions.
+ *
  * @return {string} The formatted number.
  */
 /**