@highcharts/grid-pro 2.0.0

package/es-modules/Accessibility/Components/SeriesComponent/ForcedMarkers.js

@@ -0,0 +1,234 @@
+/* *
+ *
+ *  (c) 2009-2025 Øystein Moseng
+ *
+ *  Handle forcing series markers.
+ *
+ *  License: www.highcharts.com/license
+ *
+ *  !!!!!!! SOURCE GETS TRANSPILED BY TYPESCRIPT. EDIT TS FILE ONLY. !!!!!!!
+ *
+ * */
+'use strict';
+import H from '../../../Core/Globals.js';
+const { composed } = H;
+import U from '../../../Core/Utilities.js';
+const { addEvent, merge, pushUnique } = U;
+/* *
+ *
+ *  Composition
+ *
+ * */
+var ForcedMarkersComposition;
+(function (ForcedMarkersComposition) {
+    /* *
+     *
+     *  Declarations
+     *
+     * */
+    /* *
+     *
+     *  Functions
+     *
+     * */
+    /**
+     * @private
+     */
+    function compose(SeriesClass) {
+        if (pushUnique(composed, 'A11y.FM')) {
+            addEvent(SeriesClass, 'afterSetOptions', seriesOnAfterSetOptions);
+            addEvent(SeriesClass, 'render', seriesOnRender);
+            addEvent(SeriesClass, 'afterRender', seriesOnAfterRender);
+            addEvent(SeriesClass, 'renderCanvas', seriesOnRenderCanvas);
+        }
+    }
+    ForcedMarkersComposition.compose = compose;
+    /**
+     * @private
+     */
+    function forceZeroOpacityMarkerOptions(options) {
+        merge(true, options, {
+            marker: {
+                enabled: true,
+                states: {
+                    normal: {
+                        opacity: 0
+                    }
+                }
+            }
+        });
+    }
+    /**
+     * @private
+     */
+    function getPointMarkerOpacity(pointOptions) {
+        return pointOptions.marker.states &&
+            pointOptions.marker.states.normal &&
+            pointOptions.marker.states.normal.opacity;
+    }
+    /**
+     * @private
+     */
+    function handleForcePointMarkers(series) {
+        let i = series.points.length;
+        while (i--) {
+            const point = series.points[i];
+            const pointOptions = point.options;
+            const hadForcedMarker = point.hasForcedA11yMarker;
+            delete point.hasForcedA11yMarker;
+            if (pointOptions.marker) {
+                const isStillForcedMarker = hadForcedMarker &&
+                    getPointMarkerOpacity(pointOptions) === 0;
+                if (pointOptions.marker.enabled && !isStillForcedMarker) {
+                    unforcePointMarkerOptions(pointOptions);
+                    point.hasForcedA11yMarker = false;
+                }
+                else if (pointOptions.marker.enabled === false) {
+                    forceZeroOpacityMarkerOptions(pointOptions);
+                    point.hasForcedA11yMarker = true;
+                }
+            }
+        }
+    }
+    /**
+     * @private
+     */
+    function hasIndividualPointMarkerOptions(series) {
+        return !!(series._hasPointMarkers &&
+            series.points &&
+            series.points.length);
+    }
+    /**
+     * @private
+     */
+    function isWithinDescriptionThreshold(series) {
+        const a11yOptions = series.chart.options.accessibility;
+        return series.points.length <
+            a11yOptions.series.pointDescriptionEnabledThreshold ||
+            a11yOptions.series
+                .pointDescriptionEnabledThreshold === false;
+    }
+    /**
+     * Process marker graphics after render
+     * @private
+     */
+    function seriesOnAfterRender() {
+        const series = this;
+        // For styled mode the rendered graphic does not reflect the style
+        // options, and we need to add/remove classes to achieve the same.
+        if (series.chart.styledMode) {
+            if (series.markerGroup) {
+                series.markerGroup[series.a11yMarkersForced ? 'addClass' : 'removeClass']('highcharts-a11y-markers-hidden');
+            }
+            // Do we need to handle individual points?
+            if (hasIndividualPointMarkerOptions(series)) {
+                series.points.forEach((point) => {
+                    if (point.graphic) {
+                        point.graphic[point.hasForcedA11yMarker ?
+                            'addClass' : 'removeClass']('highcharts-a11y-marker-hidden');
+                        point.graphic[point.hasForcedA11yMarker === false ?
+                            'addClass' :
+                            'removeClass']('highcharts-a11y-marker-visible');
+                    }
+                });
+            }
+        }
+    }
+    /**
+     * Keep track of options to reset markers to if no longer forced.
+     * @private
+     */
+    function seriesOnAfterSetOptions(e) {
+        this.resetA11yMarkerOptions = merge(e.options.marker || {}, this.userOptions.marker || {});
+    }
+    /**
+     * Keep track of forcing markers.
+     * @private
+     */
+    function seriesOnRender() {
+        const series = this, options = series.options;
+        if (shouldForceMarkers(series)) {
+            if (options.marker && options.marker.enabled === false) {
+                series.a11yMarkersForced = true;
+                forceZeroOpacityMarkerOptions(series.options);
+            }
+            if (hasIndividualPointMarkerOptions(series)) {
+                handleForcePointMarkers(series);
+            }
+        }
+        else if (series.a11yMarkersForced) {
+            delete series.a11yMarkersForced;
+            unforceSeriesMarkerOptions(series);
+            if (options.marker && options.marker.enabled === false) { // #23329
+                delete series.resetA11yMarkerOptions; // #16624
+            }
+        }
+    }
+    /**
+     * @private
+     */
+    function shouldForceMarkers(series) {
+        const chart = series.chart, chartA11yEnabled = chart.options.accessibility.enabled, seriesA11yEnabled = (series.options.accessibility &&
+            series.options.accessibility.enabled) !== false;
+        return (chartA11yEnabled &&
+            seriesA11yEnabled &&
+            isWithinDescriptionThreshold(series));
+    }
+    /**
+     * @private
+     */
+    function unforcePointMarkerOptions(pointOptions) {
+        merge(true, pointOptions.marker, {
+            states: {
+                normal: {
+                    opacity: getPointMarkerOpacity(pointOptions) || 1
+                }
+            }
+        });
+    }
+    /**
+     * Reset markers to normal
+     * @private
+     */
+    function unforceSeriesMarkerOptions(series) {
+        const resetMarkerOptions = series.resetA11yMarkerOptions;
+        if (resetMarkerOptions) {
+            const originalOpacity = resetMarkerOptions.states &&
+                resetMarkerOptions.states.normal &&
+                resetMarkerOptions.states.normal.opacity;
+            // Temporarily set the old marker options to enabled in order to
+            // trigger destruction of the markers in Series.update.
+            if (series.userOptions && series.userOptions.marker) {
+                series.userOptions.marker.enabled = true;
+            }
+            series.update({
+                marker: {
+                    enabled: resetMarkerOptions.enabled,
+                    states: {
+                        normal: { opacity: originalOpacity }
+                    }
+                }
+            });
+        }
+    }
+    /**
+     * Reset markers if series is boosted and had forced markers (#17320).
+     * @private
+     */
+    function seriesOnRenderCanvas() {
+        if (this.boosted && this.a11yMarkersForced) {
+            merge(true, this.options, {
+                marker: {
+                    enabled: false
+                }
+            });
+            delete this.a11yMarkersForced;
+        }
+    }
+})(ForcedMarkersComposition || (ForcedMarkersComposition = {}));
+/* *
+ *
+ *  Default Export
+ *
+ * */
+export default ForcedMarkersComposition;

package/es-modules/Accessibility/Components/SeriesComponent/NewDataAnnouncer.d.ts

@@ -0,0 +1,87 @@
+import type Accessibility from '../../Accessibility';
+import type Series from '../../../Core/Series/Series';
+import Announcer from '../../Utils/Announcer.js';
+import EventProvider from '../../Utils/EventProvider.js';
+/**
+ * @private
+ * @class
+ */
+declare class NewDataAnnouncer {
+    constructor(chart: Accessibility.ChartComposition);
+    announcer: Announcer;
+    chart: Accessibility.ChartComposition;
+    dirty: NewDataAnnouncer.DirtyObject;
+    eventProvider: EventProvider;
+    lastAnnouncementTime: number;
+    queuedAnnouncement?: NewDataAnnouncer.QueuedAnnouncementObject;
+    queuedAnnouncementTimer?: number;
+    /**
+     * Initialize the new data announcer.
+     * @private
+     */
+    init(): void;
+    /**
+     * Remove traces of announcer.
+     * @private
+     */
+    destroy(): void;
+    /**
+     * Add event listeners for the announcer
+     * @private
+     */
+    addEventListeners(): void;
+    /**
+     * On new data series added, update dirty list.
+     * @private
+     * @param {Highcharts.Series} series
+     */
+    onSeriesAdded(series: Accessibility.SeriesComposition): void;
+    /**
+     * Gather what we know and announce the data to user.
+     * @private
+     */
+    announceDirtyData(): void;
+    /**
+     * Announce to user that there is new data.
+     * @private
+     * @param {Array<Highcharts.Series>} dirtySeries
+     *          Array of series with new data.
+     * @param {Highcharts.Series} [newSeries]
+     *          If a single new series was added, a reference to this series.
+     * @param {Highcharts.Point} [newPoint]
+     *          If a single point was added, a reference to this point.
+     */
+    queueAnnouncement(dirtySeries: Array<Accessibility.SeriesComposition>, newSeries?: Accessibility.SeriesComposition, newPoint?: Accessibility.PointComposition): void;
+    /**
+     * Get announcement message for new data.
+     * @private
+     * @param {Array<Highcharts.Series>} dirtySeries
+     *          Array of series with new data.
+     * @param {Highcharts.Series} [newSeries]
+     *          If a single new series was added, a reference to this series.
+     * @param {Highcharts.Point} [newPoint]
+     *          If a single point was added, a reference to this point.
+     *
+     * @return {string|null}
+     * The announcement message to give to user.
+     */
+    buildAnnouncementMessage(dirtySeries: Array<Accessibility.SeriesComposition>, newSeries?: Accessibility.SeriesComposition, newPoint?: Accessibility.PointComposition): (string | null);
+}
+declare namespace NewDataAnnouncer {
+    interface DirtyObject {
+        allSeries: Record<string, Accessibility.SeriesComposition>;
+        hasDirty?: boolean;
+        newPoint?: Accessibility.PointComposition;
+        newSeries?: Accessibility.SeriesComposition;
+    }
+    interface QueuedAnnouncementObject {
+        message: string;
+        series: Array<Accessibility.SeriesComposition>;
+        time: number;
+    }
+    /**
+     * @private
+     */
+    function compose(SeriesClass: typeof Series): void;
+}
+export default NewDataAnnouncer;

package/es-modules/Accessibility/Components/SeriesComponent/NewDataAnnouncer.js

@@ -0,0 +1,309 @@
+/* *
+ *
+ *  (c) 2009-2025 Øystein Moseng
+ *
+ *  Handle announcing new data for a chart.
+ *
+ *  License: www.highcharts.com/license
+ *
+ *  !!!!!!! SOURCE GETS TRANSPILED BY TYPESCRIPT. EDIT TS FILE ONLY. !!!!!!!
+ *
+ * */
+'use strict';
+import H from '../../../Core/Globals.js';
+const { composed } = H;
+import U from '../../../Core/Utilities.js';
+const { addEvent, defined, pushUnique } = U;
+import Announcer from '../../Utils/Announcer.js';
+import ChartUtilities from '../../Utils/ChartUtilities.js';
+const { getChartTitle } = ChartUtilities;
+import EventProvider from '../../Utils/EventProvider.js';
+import SeriesDescriber from './SeriesDescriber.js';
+const { defaultPointDescriptionFormatter, defaultSeriesDescriptionFormatter } = SeriesDescriber;
+/* *
+ *
+ *  Functions
+ *
+ * */
+/* eslint-disable valid-jsdoc */
+/**
+ * @private
+ */
+function chartHasAnnounceEnabled(chart) {
+    return !!chart.options.accessibility.announceNewData.enabled;
+}
+/**
+ * @private
+ */
+function findPointInDataArray(point) {
+    const candidates = point.series.data.filter((candidate) => (point.x === candidate.x && point.y === candidate.y));
+    return candidates.length === 1 ? candidates[0] : point;
+}
+/**
+ * Get array of unique series from two arrays
+ * @private
+ */
+function getUniqueSeries(arrayA, arrayB) {
+    const uniqueSeries = (arrayA || []).concat(arrayB || []).reduce((acc, cur) => {
+        acc[cur.name + cur.index] = cur;
+        return acc;
+    }, {});
+    return Object
+        .keys(uniqueSeries)
+        .map((ix) => uniqueSeries[ix]);
+}
+/* *
+ *
+ *  Class
+ *
+ * */
+/**
+ * @private
+ * @class
+ */
+class NewDataAnnouncer {
+    /* *
+     *
+     *  Constructor
+     *
+     * */
+    constructor(chart) {
+        this.dirty = {
+            allSeries: {}
+        };
+        this.lastAnnouncementTime = 0;
+        this.chart = chart;
+    }
+    /* *
+     *
+     *  Functions
+     *
+     * */
+    /* eslint-disable valid-jsdoc */
+    /**
+     * Initialize the new data announcer.
+     * @private
+     */
+    init() {
+        const chart = this.chart;
+        const announceOptions = (chart.options.accessibility.announceNewData);
+        const announceType = announceOptions.interruptUser ?
+            'assertive' : 'polite';
+        this.lastAnnouncementTime = 0;
+        this.dirty = {
+            allSeries: {}
+        };
+        this.eventProvider = new EventProvider();
+        this.announcer = new Announcer(chart, announceType);
+        this.addEventListeners();
+    }
+    /**
+     * Remove traces of announcer.
+     * @private
+     */
+    destroy() {
+        this.eventProvider.removeAddedEvents();
+        this.announcer.destroy();
+    }
+    /**
+     * Add event listeners for the announcer
+     * @private
+     */
+    addEventListeners() {
+        const announcer = this, chart = this.chart, e = this.eventProvider;
+        e.addEvent(chart, 'afterApplyDrilldown', function () {
+            announcer.lastAnnouncementTime = 0;
+        });
+        e.addEvent(chart, 'afterAddSeries', function (e) {
+            announcer.onSeriesAdded(e.series);
+        });
+        e.addEvent(chart, 'redraw', function () {
+            announcer.announceDirtyData();
+        });
+    }
+    /**
+     * On new data series added, update dirty list.
+     * @private
+     * @param {Highcharts.Series} series
+     */
+    onSeriesAdded(series) {
+        if (chartHasAnnounceEnabled(this.chart)) {
+            this.dirty.hasDirty = true;
+            this.dirty.allSeries[series.name + series.index] = series;
+            // Add it to newSeries storage unless we already have one
+            this.dirty.newSeries = defined(this.dirty.newSeries) ?
+                void 0 : series;
+        }
+    }
+    /**
+     * Gather what we know and announce the data to user.
+     * @private
+     */
+    announceDirtyData() {
+        const chart = this.chart, announcer = this;
+        if (chart.options.accessibility.announceNewData &&
+            this.dirty.hasDirty) {
+            let newPoint = this.dirty.newPoint;
+            // If we have a single new point, see if we can find it in the
+            // data array. Otherwise we can only pass through options to
+            // the description builder, and it is a bit sparse in info.
+            if (newPoint) {
+                newPoint = findPointInDataArray(newPoint);
+            }
+            this.queueAnnouncement(Object
+                .keys(this.dirty.allSeries)
+                .map((ix) => announcer.dirty.allSeries[ix]), this.dirty.newSeries, newPoint);
+            // Reset
+            this.dirty = {
+                allSeries: {}
+            };
+        }
+    }
+    /**
+     * Announce to user that there is new data.
+     * @private
+     * @param {Array<Highcharts.Series>} dirtySeries
+     *          Array of series with new data.
+     * @param {Highcharts.Series} [newSeries]
+     *          If a single new series was added, a reference to this series.
+     * @param {Highcharts.Point} [newPoint]
+     *          If a single point was added, a reference to this point.
+     */
+    queueAnnouncement(dirtySeries, newSeries, newPoint) {
+        const chart = this.chart;
+        const annOptions = chart.options.accessibility.announceNewData;
+        if (annOptions.enabled) {
+            const now = +new Date();
+            const dTime = now - this.lastAnnouncementTime;
+            const time = Math.max(0, annOptions.minAnnounceInterval - dTime);
+            // Add series from previously queued announcement.
+            const allSeries = getUniqueSeries(this.queuedAnnouncement && this.queuedAnnouncement.series, dirtySeries);
+            // Build message and announce
+            const message = this.buildAnnouncementMessage(allSeries, newSeries, newPoint);
+            if (message) {
+                // Is there already one queued?
+                if (this.queuedAnnouncement) {
+                    clearTimeout(this.queuedAnnouncementTimer);
+                }
+                // Build the announcement
+                this.queuedAnnouncement = {
+                    time: now,
+                    message: message,
+                    series: allSeries
+                };
+                // Queue the announcement
+                this.queuedAnnouncementTimer = setTimeout(() => {
+                    if (this && this.announcer) {
+                        this.lastAnnouncementTime = +new Date();
+                        this.announcer.announce(this.queuedAnnouncement.message);
+                        delete this.queuedAnnouncement;
+                        delete this.queuedAnnouncementTimer;
+                    }
+                }, time);
+            }
+        }
+    }
+    /**
+     * Get announcement message for new data.
+     * @private
+     * @param {Array<Highcharts.Series>} dirtySeries
+     *          Array of series with new data.
+     * @param {Highcharts.Series} [newSeries]
+     *          If a single new series was added, a reference to this series.
+     * @param {Highcharts.Point} [newPoint]
+     *          If a single point was added, a reference to this point.
+     *
+     * @return {string|null}
+     * The announcement message to give to user.
+     */
+    buildAnnouncementMessage(dirtySeries, newSeries, newPoint) {
+        const chart = this.chart, annOptions = chart.options.accessibility.announceNewData;
+        // User supplied formatter?
+        if (annOptions.announcementFormatter) {
+            const formatterRes = annOptions.announcementFormatter(dirtySeries, newSeries, newPoint);
+            if (formatterRes !== false) {
+                return formatterRes.length ? formatterRes : null;
+            }
+        }
+        // Default formatter - use lang options
+        const multiple = H.charts && H.charts.length > 1 ?
+            'Multiple' : 'Single', langKey = newSeries ? 'newSeriesAnnounce' + multiple :
+            newPoint ? 'newPointAnnounce' + multiple : 'newDataAnnounce', chartTitle = getChartTitle(chart);
+        return chart.langFormat('accessibility.announceNewData.' + langKey, {
+            chartTitle: chartTitle,
+            seriesDesc: newSeries ?
+                defaultSeriesDescriptionFormatter(newSeries) :
+                null,
+            pointDesc: newPoint ?
+                defaultPointDescriptionFormatter(newPoint) :
+                null,
+            point: newPoint,
+            series: newSeries
+        });
+    }
+}
+/* *
+ *
+ *  Class Namespace
+ *
+ * */
+(function (NewDataAnnouncer) {
+    /* *
+     *
+     *  Declarations
+     *
+     * */
+    /* *
+     *
+     *  Static Functions
+     *
+     * */
+    /**
+     * @private
+     */
+    function compose(SeriesClass) {
+        if (pushUnique(composed, 'A11y.NDA')) {
+            addEvent(SeriesClass, 'addPoint', seriesOnAddPoint);
+            addEvent(SeriesClass, 'updatedData', seriesOnUpdatedData);
+        }
+    }
+    NewDataAnnouncer.compose = compose;
+    /**
+     * On new point added, update dirty list.
+     * @private
+     * @param {Highcharts.Point} point
+     */
+    function seriesOnAddPoint(e) {
+        const chart = this.chart, newDataAnnouncer = chart.accessibility?.components
+            .series.newDataAnnouncer;
+        if (newDataAnnouncer &&
+            newDataAnnouncer.chart === chart &&
+            chartHasAnnounceEnabled(chart)) {
+            // Add it to newPoint storage unless we already have one
+            newDataAnnouncer.dirty.newPoint = (defined(newDataAnnouncer.dirty.newPoint) ?
+                void 0 :
+                e.point);
+        }
+    }
+    /**
+     * On new data in the series, make sure we add it to the dirty list.
+     * @private
+     * @param {Highcharts.Series} series
+     */
+    function seriesOnUpdatedData() {
+        const chart = this.chart, newDataAnnouncer = chart.accessibility?.components
+            .series.newDataAnnouncer;
+        if (newDataAnnouncer &&
+            newDataAnnouncer.chart === chart &&
+            chartHasAnnounceEnabled(chart)) {
+            newDataAnnouncer.dirty.hasDirty = true;
+            newDataAnnouncer.dirty.allSeries[this.name + this.index] = this;
+        }
+    }
+})(NewDataAnnouncer || (NewDataAnnouncer = {}));
+/* *
+ *
+ *  Default Export
+ *
+ * */
+export default NewDataAnnouncer;

package/es-modules/Accessibility/Components/SeriesComponent/SeriesComponent.d.ts

@@ -0,0 +1,53 @@
+import type Chart from '../../../Core/Chart/Chart';
+import type KeyboardNavigationHandler from '../../KeyboardNavigationHandler';
+import type Point from '../../../Core/Series/Point';
+import AccessibilityComponent from '../../AccessibilityComponent.js';
+import NewDataAnnouncer from './NewDataAnnouncer.js';
+import Series from '../../../Core/Series/Series.js';
+import SeriesKeyboardNavigation from './SeriesKeyboardNavigation.js';
+/**
+ * The SeriesComponent class
+ *
+ * @private
+ * @class
+ * @name Highcharts.SeriesComponent
+ */
+declare class SeriesComponent extends AccessibilityComponent {
+    /**
+     * @private
+     */
+    static compose(ChartClass: typeof Chart, PointClass: typeof Point, SeriesClass: typeof Series): void;
+    keyboardNavigation?: SeriesKeyboardNavigation;
+    newDataAnnouncer?: NewDataAnnouncer;
+    /**
+     * Init the component.
+     */
+    init(): void;
+    /**
+     * @private
+     */
+    hideTooltipFromATWhenShown(): void;
+    /**
+     * @private
+     */
+    hideSeriesLabelsFromATWhenShown(): void;
+    /**
+     * Called on chart render. It is necessary to do this for render in case
+     * markers change on zoom/pixel density.
+     */
+    onChartRender(): void;
+    /**
+     * Get keyboard navigation handler for this component.
+     * @private
+     */
+    getKeyboardNavigation(): KeyboardNavigationHandler;
+    /**
+     * Remove traces
+     * @private
+     */
+    destroy(): void;
+}
+interface SeriesComponent {
+    chart: SeriesKeyboardNavigation.ChartComposition;
+}
+export default SeriesComponent;