highcharts 10.2.1 → 10.3.1

package/es-modules/Extensions/DataGrouping/ApproximationDefaults.js

@@ -0,0 +1,157 @@
+/* *
+ *
+ *  (c) 2010-2021 Torstein Honsi
+ *
+ *  License: www.highcharts.com/license
+ *
+ *  !!!!!!! SOURCE GETS TRANSPILED BY TYPESCRIPT. EDIT TS FILE ONLY. !!!!!!!
+ *
+ * */
+'use strict';
+import ApproximationRegistry from './ApproximationRegistry.js';
+import U from '../../Core/Utilities.js';
+var arrayMax = U.arrayMax, arrayMin = U.arrayMin, correctFloat = U.correctFloat, extend = U.extend, isNumber = U.isNumber;
+/* *
+ *
+ *  Functions
+ *
+ * */
+/**
+ * @private
+ */
+function average(arr) {
+    var len = arr.length;
+    var ret = sum(arr);
+    // If we have a number, return it divided by the length. If not,
+    // return null or undefined based on what the sum method finds.
+    if (isNumber(ret) && len) {
+        ret = correctFloat(ret / len);
+    }
+    return ret;
+}
+/**
+ * The same as average, but for series with multiple values, like area ranges.
+ * @private
+ */
+function averages() {
+    var ret = [];
+    [].forEach.call(arguments, function (arr) {
+        ret.push(average(arr));
+    });
+    // Return undefined when first elem. is undefined and let
+    // sum method handle null (#7377)
+    return typeof ret[0] === 'undefined' ? void 0 : ret;
+}
+/**
+ * @private
+ */
+function close(arr) {
+    return arr.length ?
+        arr[arr.length - 1] :
+        (arr.hasNulls ? null : void 0);
+}
+/**
+ * @private
+ */
+function high(arr) {
+    return arr.length ?
+        arrayMax(arr) :
+        (arr.hasNulls ? null : void 0);
+}
+/**
+ * HLC, OHLC and range are special cases where a multidimensional array is input
+ * and an array is output.
+ * @private
+ */
+function hlc(high, low, close) {
+    high = ApproximationRegistry.high(high);
+    low = ApproximationRegistry.low(low);
+    close = ApproximationRegistry.close(close);
+    if (isNumber(high) ||
+        isNumber(low) ||
+        isNumber(close)) {
+        return [high, low, close];
+    }
+}
+/**
+ * @private
+ */
+function low(arr) {
+    return arr.length ?
+        arrayMin(arr) :
+        (arr.hasNulls ? null : void 0);
+}
+/**
+ * @private
+ */
+function ohlc(open, high, low, close) {
+    open = ApproximationRegistry.open(open);
+    high = ApproximationRegistry.high(high);
+    low = ApproximationRegistry.low(low);
+    close = ApproximationRegistry.close(close);
+    if (isNumber(open) ||
+        isNumber(high) ||
+        isNumber(low) ||
+        isNumber(close)) {
+        return [open, high, low, close];
+    }
+}
+/**
+ * @private
+ */
+function open(arr) {
+    return arr.length ? arr[0] : (arr.hasNulls ? null : void 0);
+}
+/**
+ * @private
+ */
+function range(low, high) {
+    low = ApproximationRegistry.low(low);
+    high = ApproximationRegistry.high(high);
+    if (isNumber(low) || isNumber(high)) {
+        return [low, high];
+    }
+    if (low === null && high === null) {
+        return null;
+    }
+    // else, return is undefined
+}
+/**
+ * @private
+ */
+function sum(arr) {
+    var len = arr.length, ret;
+    // 1. it consists of nulls exclusive
+    if (!len && arr.hasNulls) {
+        ret = null;
+        // 2. it has a length and real values
+    }
+    else if (len) {
+        ret = 0;
+        while (len--) {
+            ret += arr[len];
+        }
+    }
+    // 3. it has zero length, so just return undefined
+    // => doNothing()
+    return ret;
+}
+/* *
+ *
+ *  Default Export
+ *
+ * */
+var ApproximationDefaults = {
+    average: average,
+    averages: averages,
+    close: close,
+    high: high,
+    hlc: hlc,
+    low: low,
+    ohlc: ohlc,
+    open: open,
+    range: range,
+    sum: sum
+};
+extend(ApproximationRegistry, ApproximationDefaults);
+export default ApproximationDefaults;

package/es-modules/Extensions/DataGrouping/ApproximationRegistry.js

@@ -0,0 +1,35 @@
+/* *
+ *
+ *  (c) 2010-2021 Torstein Honsi
+ *
+ *  License: www.highcharts.com/license
+ *
+ *  !!!!!!! SOURCE GETS TRANSPILED BY TYPESCRIPT. EDIT TS FILE ONLY. !!!!!!!
+ *
+ * */
+'use strict';
+/* *
+ *
+ *  Constants
+ *
+ * */
+/**
+ * Define the available approximation types. The data grouping
+ * approximations takes an array or numbers as the first parameter. In case
+ * of ohlc, four arrays are sent in as four parameters. Each array consists
+ * only of numbers. In case null values belong to the group, the property
+ * .hasNulls will be set to true on the array.
+ *
+ * @product highstock
+ *
+ * @private
+ */
+var ApproximationRegistry = {
+// approximations added programmatically
+};
+/* *
+ *
+ *  Default Export
+ *
+ * */
+export default ApproximationRegistry;

package/es-modules/Extensions/DataGrouping/DataGrouping.js

@@ -0,0 +1,469 @@
+/* *
+ *
+ *  (c) 2010-2021 Torstein Honsi
+ *
+ *  License: www.highcharts.com/license
+ *
+ *  !!!!!!! SOURCE GETS TRANSPILED BY TYPESCRIPT. EDIT TS FILE ONLY. !!!!!!!
+ *
+ * */
+'use strict';
+import DataGroupingAxisComposition from './DataGroupingAxisComposition.js';
+import DataGroupingDefaults from './DataGroupingDefaults.js';
+import DataGroupingSeriesComposition from './DataGroupingSeriesComposition.js';
+import F from '../../Core/FormatUtilities.js';
+var format = F.format;
+import U from '../../Core/Utilities.js';
+var addEvent = U.addEvent, extend = U.extend, isNumber = U.isNumber;
+/* *
+ *
+ *  Constants
+ *
+ * */
+var composedMembers = [];
+/* *
+ *
+ *  Functions
+ *
+ * */
+/**
+ * @private
+ */
+function compose(AxisClass, SeriesClass, TooltipClass) {
+    DataGroupingAxisComposition.compose(AxisClass);
+    DataGroupingSeriesComposition.compose(SeriesClass);
+    if (composedMembers.indexOf(TooltipClass) === -1) {
+        composedMembers.push(TooltipClass);
+        addEvent(TooltipClass, 'headerFormatter', onTooltipHeaderFormatter);
+    }
+}
+/**
+ * Extend the original method, make the tooltip's header reflect the grouped
+ * range.
+ * @private
+ */
+function onTooltipHeaderFormatter(e) {
+    var chart = this.chart, time = chart.time, labelConfig = e.labelConfig, series = labelConfig.series, options = series.options, tooltipOptions = series.tooltipOptions, dataGroupingOptions = options.dataGrouping, xAxis = series.xAxis;
+    var xDateFormat = tooltipOptions.xDateFormat, xDateFormatEnd, currentDataGrouping, dateTimeLabelFormats, labelFormats, formattedKey, formatString = tooltipOptions[e.isFooter ? 'footerFormat' : 'headerFormat'];
+    // apply only to grouped series
+    if (xAxis &&
+        xAxis.options.type === 'datetime' &&
+        dataGroupingOptions &&
+        isNumber(labelConfig.key)) {
+        // set variables
+        currentDataGrouping = series.currentDataGrouping;
+        dateTimeLabelFormats = dataGroupingOptions.dateTimeLabelFormats ||
+            // Fallback to commonOptions (#9693)
+            DataGroupingDefaults.common.dateTimeLabelFormats;
+        // if we have grouped data, use the grouping information to get the
+        // right format
+        if (currentDataGrouping) {
+            labelFormats =
+                dateTimeLabelFormats[currentDataGrouping.unitName];
+            if (currentDataGrouping.count === 1) {
+                xDateFormat = labelFormats[0];
+            }
+            else {
+                xDateFormat = labelFormats[1];
+                xDateFormatEnd = labelFormats[2];
+            }
+            // if not grouped, and we don't have set the xDateFormat option, get the
+            // best fit, so if the least distance between points is one minute, show
+            // it, but if the least distance is one day, skip hours and minutes etc.
+        }
+        else if (!xDateFormat && dateTimeLabelFormats && xAxis.dateTime) {
+            xDateFormat = xAxis.dateTime.getXDateFormat(labelConfig.x, tooltipOptions.dateTimeLabelFormats);
+        }
+        // now format the key
+        formattedKey = time.dateFormat(xDateFormat, labelConfig.key);
+        if (xDateFormatEnd) {
+            formattedKey += time.dateFormat(xDateFormatEnd, labelConfig.key + currentDataGrouping.totalRange - 1);
+        }
+        // Replace default header style with class name
+        if (series.chart.styledMode) {
+            formatString = this.styledModeFormat(formatString);
+        }
+        // return the replaced format
+        e.text = format(formatString, {
+            point: extend(labelConfig.point, { key: formattedKey }),
+            series: series
+        }, chart);
+        e.preventDefault();
+    }
+}
+/* *
+ *
+ *  Default Export
+ *
+ * */
+var DataGroupingComposition = {
+    compose: compose,
+    groupData: DataGroupingSeriesComposition.groupData
+};
+export default DataGroupingComposition;
+/* *
+ *
+ *  API Declarations
+ *
+ * */
+/**
+ * @typedef {"average"|"averages"|"open"|"high"|"low"|"close"|"sum"} Highcharts.DataGroupingApproximationValue
+ */
+/**
+ * The position of the point inside the group.
+ *
+ * @typedef    {"start"|"middle"|"end"} Highcharts.DataGroupingAnchor
+ */
+/**
+ * The position of the first or last point in the series inside the group.
+ *
+ * @typedef    {"start"|"middle"|"end"|"firstPoint"|"lastPoint"} Highcharts.DataGroupingAnchorExtremes
+ */
+/**
+ * Highcharts Stock only.
+ *
+ * @product highstock
+ * @interface Highcharts.DataGroupingInfoObject
+ */ /**
+* @name Highcharts.DataGroupingInfoObject#length
+* @type {number}
+*/ /**
+* @name Highcharts.DataGroupingInfoObject#options
+* @type {Highcharts.SeriesOptionsType|undefined}
+*/ /**
+* @name Highcharts.DataGroupingInfoObject#start
+* @type {number}
+*/
+/**
+ * Highcharts Stock only.
+ *
+ * @product highstock
+ * @interface Highcharts.DataGroupingResultObject
+ */ /**
+* @name Highcharts.DataGroupingResultObject#groupedXData
+* @type {Array<number>}
+*/ /**
+* @name Highcharts.DataGroupingResultObject#groupedYData
+* @type {Array<(number|null|undefined)>|Array<Array<(number|null|undefined)>>}
+*/ /**
+* @name Highcharts.DataGroupingResultObject#groupMap
+* @type {Array<DataGroupingInfoObject>}
+*/
+/**
+ * Highcharts Stock only. If a point object is created by data
+ * grouping, it doesn't reflect actual points in the raw
+ * data. In this case, the `dataGroup` property holds
+ * information that points back to the raw data.
+ *
+ * - `dataGroup.start` is the index of the first raw data
+ *   point in the group.
+ *
+ * - `dataGroup.length` is the amount of points in the
+ *   group.
+ *
+ * @sample stock/members/point-datagroup
+ *         Click to inspect raw data points
+ *
+ * @product highstock
+ *
+ * @name Highcharts.Point#dataGroup
+ * @type {Highcharts.DataGroupingInfoObject|undefined}
+ */
+(''); // detach doclets above
+/* *
+ *
+ *  API Options
+ *
+ * */
+/**
+ * Data grouping is the concept of sampling the data values into larger
+ * blocks in order to ease readability and increase performance of the
+ * JavaScript charts. Highcharts Stock by default applies data grouping when
+ * the points become closer than a certain pixel value, determined by
+ * the `groupPixelWidth` option.
+ *
+ * If data grouping is applied, the grouping information of grouped
+ * points can be read from the [Point.dataGroup](
+ * /class-reference/Highcharts.Point#dataGroup). If point options other than
+ * the data itself are set, for example `name` or `color` or custom properties,
+ * the grouping logic doesn't know how to group it. In this case the options of
+ * the first point instance are copied over to the group point. This can be
+ * altered through a custom `approximation` callback function.
+ *
+ * @declare   Highcharts.DataGroupingOptionsObject
+ * @product   highstock
+ * @requires  product:highstock
+ * @requires  module:modules/datagrouping
+ * @apioption plotOptions.series.dataGrouping
+ */
+/**
+ * Specifies how the points should be located on the X axis inside the group.
+ * Points that are extremes can be set separately. Available options:
+ *
+ * - `start` places the point at the beginning of the group
+ * (e.g. range 00:00:00 - 23:59:59 -> 00:00:00)
+ *
+ * - `middle` places the point in the middle of the group
+ * (e.g. range 00:00:00 - 23:59:59 -> 12:00:00)
+ *
+ * - `end` places the point at the end of the group
+ * (e.g. range 00:00:00 - 23:59:59 -> 23:59:59)
+ *
+ * @sample {highstock} stock/plotoptions/series-datagrouping-anchor
+ *         Changing the point x-coordinate inside the group.
+ *
+ * @see [dataGrouping.firstAnchor](#plotOptions.series.dataGrouping.firstAnchor)
+ * @see [dataGrouping.lastAnchor](#plotOptions.series.dataGrouping.lastAnchor)
+ *
+ * @type       {Highcharts.DataGroupingAnchor}
+ * @since 9.1.0
+ * @default    start
+ * @apioption  plotOptions.series.dataGrouping.anchor
+ */
+/**
+ * The method of approximation inside a group. When for example 30 days
+ * are grouped into one month, this determines what value should represent
+ * the group. Possible values are "average", "averages", "open", "high",
+ * "low", "close" and "sum". For OHLC and candlestick series the approximation
+ * is "ohlc" by default, which finds the open, high, low and close values
+ * within all the grouped data. For ranges, the approximation is "range",
+ * which finds the low and high values. For multi-dimensional data,
+ * like ranges and OHLC, "averages" will compute the average for each
+ * dimension.
+ *
+ * Custom aggregate methods can be added by assigning a callback function
+ * as the approximation. This function takes a numeric array as the
+ * argument and should return a single numeric value or `null`. Note
+ * that the numeric array will never contain null values, only true
+ * numbers. Instead, if null values are present in the raw data, the
+ * numeric array will have an `.hasNulls` property set to `true`. For
+ * single-value data sets the data is available in the first argument
+ * of the callback function. For OHLC data sets, all the open values
+ * are in the first argument, all high values in the second etc.
+ *
+ * Since v4.2.7, grouping meta data is available in the approximation
+ * callback from `this.dataGroupInfo`. It can be used to extract information
+ * from the raw data.
+ *
+ * Defaults to `average` for line-type series, `sum` for columns, `range`
+ * for range series, `hlc` for HLC, and `ohlc` for OHLC and candlestick.
+ *
+ * @sample {highstock} stock/plotoptions/series-datagrouping-approximation
+ *         Approximation callback with custom data
+ * @sample {highstock} stock/plotoptions/series-datagrouping-simple-approximation
+ *         Simple approximation demo
+ *
+ * @type       {Highcharts.DataGroupingApproximationValue|Function}
+ * @apioption  plotOptions.series.dataGrouping.approximation
+ */
+/**
+ * Datetime formats for the header of the tooltip in a stock chart.
+ * The format can vary within a chart depending on the currently selected
+ * time range and the current data grouping.
+ *
+ * The default formats are:
+ * ```js
+ * {
+ *     millisecond: [
+ *         '%A, %b %e, %H:%M:%S.%L', '%A, %b %e, %H:%M:%S.%L', '-%H:%M:%S.%L'
+ *     ],
+ *     second: ['%A, %b %e, %H:%M:%S', '%A, %b %e, %H:%M:%S', '-%H:%M:%S'],
+ *     minute: ['%A, %b %e, %H:%M', '%A, %b %e, %H:%M', '-%H:%M'],
+ *     hour: ['%A, %b %e, %H:%M', '%A, %b %e, %H:%M', '-%H:%M'],
+ *     day: ['%A, %b %e, %Y', '%A, %b %e', '-%A, %b %e, %Y'],
+ *     week: ['Week from %A, %b %e, %Y', '%A, %b %e', '-%A, %b %e, %Y'],
+ *     month: ['%B %Y', '%B', '-%B %Y'],
+ *     year: ['%Y', '%Y', '-%Y']
+ * }
+ * ```
+ *
+ * For each of these array definitions, the first item is the format
+ * used when the active time span is one unit. For instance, if the
+ * current data applies to one week, the first item of the week array
+ * is used. The second and third items are used when the active time
+ * span is more than two units. For instance, if the current data applies
+ * to two weeks, the second and third item of the week array are used,
+ *  and applied to the start and end date of the time span.
+ *
+ * @type      {Object}
+ * @apioption plotOptions.series.dataGrouping.dateTimeLabelFormats
+ */
+/**
+ * Enable or disable data grouping.
+ *
+ * @type      {boolean}
+ * @default   true
+ * @apioption plotOptions.series.dataGrouping.enabled
+ */
+/**
+ * Specifies how the first grouped point is positioned on the xAxis.
+ * If firstAnchor and/or lastAnchor are defined, then those options take
+ * precedence over anchor for the first and/or last grouped points.
+ * Available options:
+ *
+ * -`start` places the point at the beginning of the group
+ * (e.g. range 00:00:00 - 23:59:59 -> 00:00:00)
+ *
+ * -`middle` places the point in the middle of the group
+ * (e.g. range 00:00:00 - 23:59:59 -> 12:00:00)
+ *
+ * -`end` places the point at the end of the group
+ * (e.g. range 00:00:00 - 23:59:59 -> 23:59:59)
+ *
+ * -`firstPoint` the first point in the group
+ * (e.g. points at 00:13, 00:35, 00:59 -> 00:13)
+ *
+ * -`lastPoint` the last point in the group
+ * (e.g. points at 00:13, 00:35, 00:59 -> 00:59)
+ *
+ * @sample {highstock} stock/plotoptions/series-datagrouping-first-anchor
+ *         Applying first and last anchor.
+ *
+ * @see [dataGrouping.anchor](#plotOptions.series.dataGrouping.anchor)
+ *
+ * @type       {Highcharts.DataGroupingAnchorExtremes}
+ * @since 9.1.0
+ * @default    start
+ * @apioption  plotOptions.series.dataGrouping.firstAnchor
+ */
+/**
+ * When data grouping is forced, it runs no matter how small the intervals
+ * are. This can be handy for example when the sum should be calculated
+ * for values appearing at random times within each hour.
+ *
+ * @type      {boolean}
+ * @default   false
+ * @apioption plotOptions.series.dataGrouping.forced
+ */
+/**
+ * The approximate pixel width of each group. If for example a series
+ * with 30 points is displayed over a 600 pixel wide plot area, no grouping
+ * is performed. If however the series contains so many points that
+ * the spacing is less than the groupPixelWidth, Highcharts will try
+ * to group it into appropriate groups so that each is more or less
+ * two pixels wide. If multiple series with different group pixel widths
+ * are drawn on the same x axis, all series will take the greatest width.
+ * For example, line series have 2px default group width, while column
+ * series have 10px. If combined, both the line and the column will
+ * have 10px by default.
+ *
+ * @type      {number}
+ * @default   2
+ * @apioption plotOptions.series.dataGrouping.groupPixelWidth
+ */
+/**
+ * By default only points within the visible range are grouped. Enabling this
+ * option will force data grouping to calculate all grouped points for a given
+ * dataset. That option prevents for example a column series from calculating
+ * a grouped point partially. The effect is similar to
+ * [Series.getExtremesFromAll](#plotOptions.series.getExtremesFromAll) but does
+ * not affect yAxis extremes.
+ *
+ * @sample {highstock} stock/plotoptions/series-datagrouping-groupall/
+ *         Two series with the same data but different groupAll setting
+ *
+ * @type      {boolean}
+ * @default   false
+ * @since     6.1.0
+ * @apioption plotOptions.series.dataGrouping.groupAll
+ */
+/**
+ * Specifies how the last grouped point is positioned on the xAxis.
+ * If firstAnchor and/or lastAnchor are defined, then those options take
+ * precedence over anchor for the first and/or last grouped points.
+ * Available options:
+ *
+ * -`start` places the point at the beginning of the group
+ * (e.g. range 00:00:00 - 23:59:59 -> 00:00:00)
+ *
+ * -`middle` places the point in the middle of the group
+ * (e.g. range 00:00:00 - 23:59:59 -> 12:00:00)
+ *
+ * -`end` places the point at the end of the group
+ * (e.g. range 00:00:00 - 23:59:59 -> 23:59:59)
+ *
+ * -`firstPoint` the first point in the group
+ * (e.g. points at 00:13, 00:35, 00:59 -> 00:13)
+ *
+ * -`lastPoint` the last point in the group
+ * (e.g. points at 00:13, 00:35, 00:59 -> 00:59)
+ *
+ * @sample {highstock} stock/plotoptions/series-datagrouping-first-anchor
+ *         Applying first and last anchor.
+ *
+ * @sample {highstock} stock/plotoptions/series-datagrouping-last-anchor
+ *         Applying the last anchor in the chart with live data.
+ *
+ * @see [dataGrouping.anchor](#plotOptions.series.dataGrouping.anchor)
+ *
+ * @type       {Highcharts.DataGroupingAnchorExtremes}
+ * @since 9.1.0
+ * @default    start
+ * @apioption  plotOptions.series.dataGrouping.lastAnchor
+ */
+/**
+ * Normally, a group is indexed by the start of that group, so for example
+ * when 30 daily values are grouped into one month, that month's x value
+ * will be the 1st of the month. This apparently shifts the data to
+ * the left. When the smoothed option is true, this is compensated for.
+ * The data is shifted to the middle of the group, and min and max
+ * values are preserved. Internally, this is used in the Navigator series.
+ *
+ * @type      {boolean}
+ * @default   false
+ * @deprecated
+ * @apioption plotOptions.series.dataGrouping.smoothed
+ */
+/**
+ * An array determining what time intervals the data is allowed to be
+ * grouped to. Each array item is an array where the first value is
+ * the time unit and the second value another array of allowed multiples.
+ *
+ * Defaults to:
+ * ```js
+ * units: [[
+ *     'millisecond', // unit name
+ *     [1, 2, 5, 10, 20, 25, 50, 100, 200, 500] // allowed multiples
+ * ], [
+ *     'second',
+ *     [1, 2, 5, 10, 15, 30]
+ * ], [
+ *     'minute',
+ *     [1, 2, 5, 10, 15, 30]
+ * ], [
+ *     'hour',
+ *     [1, 2, 3, 4, 6, 8, 12]
+ * ], [
+ *     'day',
+ *     [1]
+ * ], [
+ *     'week',
+ *     [1]
+ * ], [
+ *     'month',
+ *     [1, 3, 6]
+ * ], [
+ *     'year',
+ *     null
+ * ]]
+ * ```
+ *
+ * @type      {Array<Array<string,(Array<number>|null)>>}
+ * @apioption plotOptions.series.dataGrouping.units
+ */
+/**
+ * The approximate pixel width of each group. If for example a series
+ * with 30 points is displayed over a 600 pixel wide plot area, no grouping
+ * is performed. If however the series contains so many points that
+ * the spacing is less than the groupPixelWidth, Highcharts will try
+ * to group it into appropriate groups so that each is more or less
+ * two pixels wide. Defaults to `10`.
+ *
+ * @sample {highstock} stock/plotoptions/series-datagrouping-grouppixelwidth/
+ *         Two series with the same data density but different groupPixelWidth
+ *
+ * @type      {number}
+ * @default   10
+ * @apioption plotOptions.column.dataGrouping.groupPixelWidth
+ */
+''; // required by JSDoc parsing