highcharts 9.2.2 → 9.3.3

package/es-modules/Extensions/Sonification/{Utilities.js → SonificationUtilities.js}

@@ -10,95 +10,22 @@
  *
  * */
 'use strict';
-import musicalFrequencies from './MusicalFrequencies.js';
+import MusicalFrequencies from './MusicalFrequencies.js';
+import SignalHandler from './SignalHandler.js';
 import U from '../../Core/Utilities.js';
-var clamp = U.clamp;
+var clamp = U.clamp, merge = U.merge;
 /* eslint-disable no-invalid-this, valid-jsdoc */
-/**
- * The SignalHandler class. Stores signal callbacks (event handlers), and
- * provides an interface to register them, and emit signals. The word "event" is
- * not used to avoid confusion with TimelineEvents.
- *
- * @requires module:modules/sonification
+/* *
  *
- * @private
- * @class
- * @name Highcharts.SignalHandler
+ *  Constants
  *
- * @param {Array<string>} supportedSignals
- *        List of supported signal names.
- */
-function SignalHandler(supportedSignals) {
-    this.init(supportedSignals || []);
-}
-SignalHandler.prototype.init = function (supportedSignals) {
-    this.supportedSignals = supportedSignals;
-    this.signals = {};
-};
-/**
- * Register a set of signal callbacks with this SignalHandler.
- * Multiple signal callbacks can be registered for the same signal.
- * @private
- * @param {Highcharts.Dictionary<(Function|undefined)>} signals
- * An object that contains a mapping from the signal name to the callbacks. Only
- * supported events are considered.
- * @return {void}
- */
-SignalHandler.prototype.registerSignalCallbacks = function (signals) {
-    var signalHandler = this;
-    signalHandler.supportedSignals.forEach(function (supportedSignal) {
-        var signal = signals[supportedSignal];
-        if (signal) {
-            (signalHandler.signals[supportedSignal] =
-                signalHandler.signals[supportedSignal] || []).push(signal);
-        }
-    });
-};
-/**
- * Clear signal callbacks, optionally by name.
- * @private
- * @param {Array<string>} [signalNames] - A list of signal names to clear. If
- * not supplied, all signal callbacks are removed.
- * @return {void}
- */
-SignalHandler.prototype.clearSignalCallbacks = function (signalNames) {
-    var signalHandler = this;
-    if (signalNames) {
-        signalNames.forEach(function (signalName) {
-            if (signalHandler.signals[signalName]) {
-                delete signalHandler.signals[signalName];
-            }
-        });
-    }
-    else {
-        signalHandler.signals = {};
-    }
-};
-/**
- * Emit a signal. Does nothing if the signal does not exist, or has no
- * registered callbacks.
- * @private
- * @param {string} signalNames
- * Name of signal to emit.
- * @param {*} [data]
- * Data to pass to the callback.
- * @return {*}
- */
-SignalHandler.prototype.emitSignal = function (signalName, data) {
-    var retval;
-    if (this.signals[signalName]) {
-        this.signals[signalName].forEach(function (handler) {
-            var result = handler(data);
-            retval = typeof result !== 'undefined' ? result : retval;
-        });
-    }
-    return retval;
-};
-var utilities = {
+ * */
+var SonificationUtilities = {
     // List of musical frequencies from C0 to C8
-    musicalFrequencies: musicalFrequencies,
+    musicalFrequencies: MusicalFrequencies,
     // SignalHandler class
     SignalHandler: SignalHandler,
+    getExtremesForInstrumentProps: getExtremesForInstrumentProps,
     /**
      * Get a musical scale by specifying the semitones from 1-12 to include.
      *  1: C, 2: C#, 3: D, 4: D#, 5: E, 6: F,
@@ -111,7 +38,7 @@ var utilities = {
      * Array of frequencies from C0 to C8 that are included in this scale.
      */
     getMusicalScale: function (semitones) {
-        return musicalFrequencies.filter(function (freq, i) {
+        return MusicalFrequencies.filter(function (freq, i) {
             var interval = i % 12 + 1;
             return semitones.some(function (allowedInterval) {
                 return allowedInterval === interval;
@@ -121,9 +48,12 @@ var utilities = {
     /**
      * Calculate the extreme values in a chart for a data prop.
      * @private
-     * @param {Highcharts.Chart} chart - The chart
-     * @param {string} prop - The data prop to find extremes for
-     * @return {Highcharts.RangeObject} Object with min and max properties
+     * @param {Highcharts.Chart} chart
+     * The chart
+     * @param {string} prop
+     * The data prop to find extremes for
+     * @return {Highcharts.RangeObject}
+     * Object with min and max properties
      */
     calculateDataExtremes: function (chart, prop) {
         return chart.series.reduce(function (extremes, series) {
@@ -149,7 +79,7 @@ var utilities = {
      * The relative data value to translate.
      * @param {Highcharts.RangeObject} DataExtremesObject
      * The possible extremes for this value.
-     * @param {object} limits
+     * @param {Object} limits
      * Limits for the virtual axis.
      * @param {boolean} [invert]
      * Invert the virtual axis.
@@ -165,4 +95,56 @@ var utilities = {
             limits.min;
     }
 };
-export default utilities;
+/* *
+ *
+ *  Functions
+ *
+ * */
+/**
+ * Calculate value extremes for used instrument data properties on a chart.
+ * @private
+ * @param {Highcharts.Chart} chart
+ * The chart to calculate extremes from.
+ * @param {Array<Highcharts.PointInstrumentObject>} [instruments]
+ * Additional instrument definitions to inspect for data props used, in
+ * addition to the instruments defined in the chart options.
+ * @param {Highcharts.Dictionary<Highcharts.RangeObject>} [dataExtremes]
+ * Predefined extremes for each data prop.
+ * @return {Highcharts.Dictionary<Highcharts.RangeObject>}
+ * New extremes with data properties mapped to min/max objects.
+ */
+function getExtremesForInstrumentProps(chart, instruments, dataExtremes) {
+    var defaultInstrumentDef = (chart.options.sonification &&
+        chart.options.sonification.defaultInstrumentOptions), optionDefToInstrDef = function (optionDef) { return ({
+        instrumentMapping: optionDef.mapping
+    }); };
+    var allInstrumentDefinitions = (instruments || []).slice(0);
+    if (defaultInstrumentDef) {
+        allInstrumentDefinitions.push(optionDefToInstrDef(defaultInstrumentDef));
+    }
+    chart.series.forEach(function (series) {
+        var instrOptions = (series.options.sonification &&
+            series.options.sonification.instruments);
+        if (instrOptions) {
+            allInstrumentDefinitions = allInstrumentDefinitions.concat(instrOptions.map(optionDefToInstrDef));
+        }
+    });
+    return (allInstrumentDefinitions).reduce(function (newExtremes, instrumentDefinition) {
+        Object.keys(instrumentDefinition.instrumentMapping || {}).forEach(function (instrumentParameter) {
+            var value = instrumentDefinition.instrumentMapping[instrumentParameter];
+            if (typeof value === 'string' && !newExtremes[value]) {
+                // This instrument parameter is mapped to a data prop. If we
+                // don't have predefined data extremes, find them.
+                newExtremes[value] = SonificationUtilities
+                    .calculateDataExtremes(chart, value);
+            }
+        });
+        return newExtremes;
+    }, merge(dataExtremes));
+}
+/* *
+ *
+ *  Default export
+ *
+ * */
+export default SonificationUtilities;