@highcharts/grid-pro 2.0.0

package/es-modules/Accessibility/Utils/Announcer.js

@@ -0,0 +1,90 @@
+/* *
+ *
+ *  (c) 2009-2025 Øystein Moseng
+ *
+ *  Create announcer to speak messages to screen readers and other AT.
+ *
+ *  License: www.highcharts.com/license
+ *
+ *  !!!!!!! SOURCE GETS TRANSPILED BY TYPESCRIPT. EDIT TS FILE ONLY. !!!!!!!
+ *
+ * */
+'use strict';
+import AST from '../../Core/Renderer/HTML/AST.js';
+import DOMElementProvider from './DOMElementProvider.js';
+import H from '../../Core/Globals.js';
+const { doc } = H;
+import HU from './HTMLUtilities.js';
+const { addClass, visuallyHideElement } = HU;
+import U from '../../Core/Utilities.js';
+const { attr } = U;
+/* *
+ *
+ *  Class
+ *
+ * */
+class Announcer {
+    /* *
+     *
+     *  Constructor
+     *
+     * */
+    constructor(chart, type) {
+        this.chart = chart;
+        this.domElementProvider = new DOMElementProvider();
+        this.announceRegion = this.addAnnounceRegion(type);
+    }
+    /* *
+     *
+     *  Functions
+     *
+     * */
+    destroy() {
+        this.domElementProvider.destroyCreatedElements();
+    }
+    announce(message) {
+        AST.setElementHTML(this.announceRegion, message);
+        // Delete contents after a little while to avoid user finding the live
+        // region in the DOM.
+        if (this.clearAnnouncementRegionTimer) {
+            clearTimeout(this.clearAnnouncementRegionTimer);
+        }
+        this.clearAnnouncementRegionTimer = setTimeout(() => {
+            this.announceRegion.innerHTML = AST.emptyHTML;
+            delete this.clearAnnouncementRegionTimer;
+        }, 3000);
+    }
+    addAnnounceRegion(type) {
+        const chartContainer = (this.chart.announcerContainer || this.createAnnouncerContainer()), div = this.domElementProvider.createElement('div');
+        attr(div, {
+            'aria-hidden': false,
+            'aria-live': type,
+            'aria-atomic': true
+        });
+        if (this.chart.styledMode) {
+            addClass(div, 'highcharts-visually-hidden');
+        }
+        else {
+            visuallyHideElement(div);
+        }
+        chartContainer.appendChild(div);
+        return div;
+    }
+    createAnnouncerContainer() {
+        const chart = this.chart, container = doc.createElement('div');
+        attr(container, {
+            'aria-hidden': false,
+            'class': 'highcharts-announcer-container'
+        });
+        container.style.position = 'relative';
+        chart.renderTo.insertBefore(container, chart.renderTo.firstChild);
+        chart.announcerContainer = container;
+        return container;
+    }
+}
+/* *
+ *
+ *  Default Export
+ *
+ * */
+export default Announcer;

package/es-modules/Accessibility/Utils/ChartUtilities.d.ts

@@ -0,0 +1,90 @@
+import type Accessibility from '../Accessibility';
+import type Axis from '../../Core/Axis/Axis';
+import type Chart from '../../Core/Chart/Chart';
+import type { DOMElementType } from '../../Core/Renderer/DOMElementType';
+import type Point from '../../Core/Series/Point';
+import type Series from '../../Core/Series/Series';
+import type HTMLElement from '../../Core/Renderer/HTML/HTMLElement';
+import type SVGElement from '../../Core/Renderer/SVG/SVGElement';
+/**
+ * Fire an event on an element that is either wrapped by Highcharts,
+ * or a DOM element.
+ * @private
+ */
+declare function fireEventOnWrappedOrUnwrappedElement(el: (HTMLElement | SVGElement | DOMElementType), eventObject: Event): void;
+/**
+ * @private
+ */
+declare function getChartTitle(chart: Accessibility.ChartComposition): string;
+/**
+ * Return string with the axis name/title.
+ * @private
+ */
+declare function getAxisDescription(axis: Axis): string;
+/**
+ * Return string with text description of the axis range.
+ * @private
+ * @param {Highcharts.Axis} axis
+ * The axis to get range desc of.
+ * @return {string}
+ * A string with the range description for the axis.
+ */
+declare function getAxisRangeDescription(axis: Axis): string;
+/**
+ * Get the DOM element for the first point in the series.
+ * @private
+ * @param {Highcharts.Series} series
+ * The series to get element for.
+ * @return {Highcharts.HTMLDOMElement|Highcharts.SVGDOMElement|undefined}
+ * The DOM element for the point.
+ */
+declare function getSeriesFirstPointElement(series: Series): (DOMElementType | undefined);
+/**
+ * Get the DOM element for the series that we put accessibility info on.
+ * @private
+ * @param {Highcharts.Series} series
+ * The series to get element for.
+ * @return {Highcharts.HTMLDOMElement|Highcharts.SVGDOMElement|undefined}
+ * The DOM element for the series
+ */
+declare function getSeriesA11yElement(series: Series): (DOMElementType | undefined);
+/**
+ * Remove aria-hidden from element. Also unhides parents of the element, and
+ * hides siblings that are not explicitly unhidden.
+ * @private
+ */
+declare function unhideChartElementFromAT(chart: Chart, element: DOMElementType): void;
+/**
+ * Hide series from screen readers.
+ * @private
+ */
+declare function hideSeriesFromAT(series: Series): void;
+/**
+ * Get series objects by series name.
+ * @private
+ */
+declare function getSeriesFromName<T extends Chart>(chart: T, name: string): T['series'];
+/**
+ * Get point in a series from x/y values.
+ * @private
+ */
+declare function getPointFromXY<T extends Series>(series: Array<T>, x: number, y: number): (T['points'][0] | undefined);
+/**
+ * Get relative position of point on an x/y axis from 0 to 1.
+ * @private
+ */
+declare function scrollAxisToPoint(point: Point): void;
+declare const ChartUtilities: {
+    fireEventOnWrappedOrUnwrappedElement: typeof fireEventOnWrappedOrUnwrappedElement;
+    getChartTitle: typeof getChartTitle;
+    getAxisDescription: typeof getAxisDescription;
+    getAxisRangeDescription: typeof getAxisRangeDescription;
+    getPointFromXY: typeof getPointFromXY;
+    getSeriesFirstPointElement: typeof getSeriesFirstPointElement;
+    getSeriesFromName: typeof getSeriesFromName;
+    getSeriesA11yElement: typeof getSeriesA11yElement;
+    unhideChartElementFromAT: typeof unhideChartElementFromAT;
+    hideSeriesFromAT: typeof hideSeriesFromAT;
+    scrollAxisToPoint: typeof scrollAxisToPoint;
+};
+export default ChartUtilities;

package/es-modules/Accessibility/Utils/ChartUtilities.js

@@ -0,0 +1,298 @@
+/* *
+ *
+ *  (c) 2009-2025 Øystein Moseng
+ *
+ *  Utils for dealing with charts.
+ *
+ *  License: www.highcharts.com/license
+ *
+ *  !!!!!!! SOURCE GETS TRANSPILED BY TYPESCRIPT. EDIT TS FILE ONLY. !!!!!!!
+ *
+ * */
+'use strict';
+import H from '../../Core/Globals.js';
+const { doc } = H;
+import HU from './HTMLUtilities.js';
+const { stripHTMLTagsFromString: stripHTMLTags } = HU;
+import U from '../../Core/Utilities.js';
+const { defined, find, fireEvent } = U;
+/* *
+ *
+ *  Functions
+ *
+ * */
+/* eslint-disable valid-jsdoc */
+/**
+ * Fire an event on an element that is either wrapped by Highcharts,
+ * or a DOM element.
+ * @private
+ */
+function fireEventOnWrappedOrUnwrappedElement(el, eventObject) {
+    const type = eventObject.type;
+    const hcEvents = el.hcEvents;
+    if (!!doc?.createEvent &&
+        (el.dispatchEvent || el.fireEvent)) {
+        if (el.dispatchEvent) {
+            el.dispatchEvent(eventObject);
+        }
+        else {
+            el.fireEvent(type, eventObject);
+        }
+    }
+    else if (hcEvents && hcEvents[type]) {
+        fireEvent(el, type, eventObject);
+    }
+    else if (el.element) {
+        fireEventOnWrappedOrUnwrappedElement(el.element, eventObject);
+    }
+}
+/**
+ * @private
+ */
+function getChartTitle(chart) {
+    return stripHTMLTags(chart.options.title.text ||
+        chart.langFormat('accessibility.defaultChartTitle', { chart: chart }), chart.renderer.forExport);
+}
+/**
+ * Return string with the axis name/title.
+ * @private
+ */
+function getAxisDescription(axis) {
+    return axis && (axis.options.accessibility?.description ||
+        axis.axisTitle?.textStr ||
+        axis.options.id ||
+        axis.categories && 'categories' ||
+        axis.dateTime && 'Time' ||
+        'values');
+}
+/**
+ * Return string with text description of the axis range.
+ * @private
+ * @param {Highcharts.Axis} axis
+ * The axis to get range desc of.
+ * @return {string}
+ * A string with the range description for the axis.
+ */
+function getAxisRangeDescription(axis) {
+    const axisOptions = axis.options || {};
+    // Handle overridden range description
+    if (axisOptions.accessibility &&
+        typeof axisOptions.accessibility.rangeDescription !== 'undefined') {
+        return axisOptions.accessibility.rangeDescription;
+    }
+    // Handle category axes
+    if (axis.categories) {
+        return getCategoryAxisRangeDesc(axis);
+    }
+    // Use time range, not from-to?
+    if (axis.dateTime && (axis.min === 0 || axis.dataMin === 0)) {
+        return getAxisTimeLengthDesc(axis);
+    }
+    // Just use from and to.
+    // We have the range and the unit to use, find the desc format
+    return getAxisFromToDescription(axis);
+}
+/**
+ * Describe the range of a category axis.
+ * @private
+ */
+function getCategoryAxisRangeDesc(axis) {
+    const chart = axis.chart;
+    if (axis.dataMax && axis.dataMin) {
+        return chart.langFormat('accessibility.axis.rangeCategories', {
+            chart: chart,
+            axis: axis,
+            numCategories: axis.dataMax - axis.dataMin + 1
+        });
+    }
+    return '';
+}
+/**
+ * Describe the length of the time window shown on an axis.
+ * @private
+ */
+function getAxisTimeLengthDesc(axis) {
+    const chart = axis.chart, range = {}, min = axis.dataMin || axis.min || 0, max = axis.dataMax || axis.max || 0;
+    let rangeUnit = 'Seconds';
+    range.Seconds = (max - min) / 1000;
+    range.Minutes = range.Seconds / 60;
+    range.Hours = range.Minutes / 60;
+    range.Days = range.Hours / 24;
+    ['Minutes', 'Hours', 'Days'].forEach(function (unit) {
+        if (range[unit] > 2) {
+            rangeUnit = unit;
+        }
+    });
+    const rangeValue = range[rangeUnit].toFixed(rangeUnit !== 'Seconds' &&
+        rangeUnit !== 'Minutes' ? 1 : 0 // Use decimals for days/hours
+    );
+    // We have the range and the unit to use, find the desc format
+    return chart.langFormat('accessibility.axis.timeRange' + rangeUnit, {
+        chart: chart,
+        axis: axis,
+        range: rangeValue.replace('.0', '')
+    });
+}
+/**
+ * Describe an axis from-to range.
+ * @private
+ */
+function getAxisFromToDescription(axis) {
+    const chart = axis.chart, options = chart.options, dateRangeFormat = (options &&
+        options.accessibility &&
+        options.accessibility.screenReaderSection.axisRangeDateFormat ||
+        ''), extremes = {
+        min: axis.dataMin || axis.min || 0,
+        max: axis.dataMax || axis.max || 0
+    }, format = function (key) {
+        return axis.dateTime ?
+            chart.time.dateFormat(dateRangeFormat, extremes[key]) :
+            extremes[key].toString();
+    };
+    return chart.langFormat('accessibility.axis.rangeFromTo', {
+        chart: chart,
+        axis: axis,
+        rangeFrom: format('min'),
+        rangeTo: format('max')
+    });
+}
+/**
+ * Get the DOM element for the first point in the series.
+ * @private
+ * @param {Highcharts.Series} series
+ * The series to get element for.
+ * @return {Highcharts.HTMLDOMElement|Highcharts.SVGDOMElement|undefined}
+ * The DOM element for the point.
+ */
+function getSeriesFirstPointElement(series) {
+    if (series.points && series.points.length) {
+        const firstPointWithGraphic = find(series.points, (p) => !!p.graphic);
+        return (firstPointWithGraphic &&
+            firstPointWithGraphic.graphic &&
+            firstPointWithGraphic.graphic.element);
+    }
+}
+/**
+ * Get the DOM element for the series that we put accessibility info on.
+ * @private
+ * @param {Highcharts.Series} series
+ * The series to get element for.
+ * @return {Highcharts.HTMLDOMElement|Highcharts.SVGDOMElement|undefined}
+ * The DOM element for the series
+ */
+function getSeriesA11yElement(series) {
+    const firstPointEl = getSeriesFirstPointElement(series);
+    return (firstPointEl &&
+        firstPointEl.parentNode || series.graph &&
+        series.graph.element || series.group &&
+        series.group.element); // Could be tracker series depending on series type
+}
+/**
+ * Remove aria-hidden from element. Also unhides parents of the element, and
+ * hides siblings that are not explicitly unhidden.
+ * @private
+ */
+function unhideChartElementFromAT(chart, element) {
+    element.setAttribute('aria-hidden', false);
+    if (element === chart.renderTo ||
+        !element.parentNode ||
+        element.parentNode === doc.body // #16126: Full screen printing
+    ) {
+        return;
+    }
+    // Hide siblings unless their hidden state is already explicitly set
+    Array.prototype.forEach.call(element.parentNode.childNodes, function (node) {
+        if (!node.hasAttribute('aria-hidden')) {
+            node.setAttribute('aria-hidden', true);
+        }
+    });
+    // Repeat for parent
+    unhideChartElementFromAT(chart, element.parentNode);
+}
+/**
+ * Hide series from screen readers.
+ * @private
+ */
+function hideSeriesFromAT(series) {
+    const seriesEl = getSeriesA11yElement(series);
+    if (seriesEl) {
+        seriesEl.setAttribute('aria-hidden', true);
+    }
+}
+/**
+ * Get series objects by series name.
+ * @private
+ */
+function getSeriesFromName(chart, name) {
+    if (!name) {
+        return chart.series;
+    }
+    return (chart.series || []).filter(function (s) {
+        return s.name === name;
+    });
+}
+/**
+ * Get point in a series from x/y values.
+ * @private
+ */
+function getPointFromXY(series, x, y) {
+    let i = series.length, res;
+    while (i--) {
+        res = find(series[i].points || [], function (p) {
+            return p.x === x && p.y === y;
+        });
+        if (res) {
+            return res;
+        }
+    }
+}
+/**
+ * Get relative position of point on an x/y axis from 0 to 1.
+ * @private
+ */
+function getRelativePointAxisPosition(axis, point) {
+    if (!defined(axis.dataMin) || !defined(axis.dataMax)) {
+        return 0;
+    }
+    const axisStart = axis.toPixels(axis.dataMin), axisEnd = axis.toPixels(axis.dataMax), 
+    // We have to use pixel position because of axis breaks, log axis etc.
+    positionProp = axis.coll === 'xAxis' ? 'x' : 'y', pointPos = axis.toPixels(point[positionProp] || 0);
+    return (pointPos - axisStart) / (axisEnd - axisStart);
+}
+/**
+ * Get relative position of point on an x/y axis from 0 to 1.
+ * @private
+ */
+function scrollAxisToPoint(point) {
+    const xAxis = point.series.xAxis, yAxis = point.series.yAxis, axis = (xAxis && xAxis.scrollbar ? xAxis : yAxis), scrollbar = (axis && axis.scrollbar);
+    if (scrollbar && defined(scrollbar.to) && defined(scrollbar.from)) {
+        const range = scrollbar.to - scrollbar.from;
+        const pos = getRelativePointAxisPosition(axis, point);
+        scrollbar.updatePosition(pos - range / 2, pos + range / 2);
+        fireEvent(scrollbar, 'changed', {
+            from: scrollbar.from,
+            to: scrollbar.to,
+            trigger: 'scrollbar',
+            DOMEvent: null
+        });
+    }
+}
+/* *
+ *
+ *  Default Export
+ *
+ * */
+const ChartUtilities = {
+    fireEventOnWrappedOrUnwrappedElement,
+    getChartTitle,
+    getAxisDescription,
+    getAxisRangeDescription,
+    getPointFromXY,
+    getSeriesFirstPointElement,
+    getSeriesFromName,
+    getSeriesA11yElement,
+    unhideChartElementFromAT,
+    hideSeriesFromAT,
+    scrollAxisToPoint
+};
+export default ChartUtilities;

package/es-modules/Accessibility/Utils/DOMElementProvider.d.ts

@@ -0,0 +1,20 @@
+import type { HTMLDOMElement } from '../../Core/Renderer/DOMElementType';
+/**
+ * @private
+ */
+declare class DOMElementProvider {
+    constructor();
+    elements: Array<HTMLDOMElement>;
+    createElement<K extends keyof HTMLElementTagNameMap>(tagName: K, options?: ElementCreationOptions): HTMLElementTagNameMap[K];
+    /**
+     * Destroy created element, removing it from the DOM.
+     * @private
+     */
+    removeElement(element: HTMLDOMElement): void;
+    /**
+     * Destroy all created elements, removing them from the DOM.
+     * @private
+     */
+    destroyCreatedElements(): void;
+}
+export default DOMElementProvider;

package/es-modules/Accessibility/Utils/DOMElementProvider.js

@@ -0,0 +1,69 @@
+/* *
+ *
+ *  (c) 2009-2025 Øystein Moseng
+ *
+ *  Class that can keep track of elements added to DOM and clean them up on
+ *  destroy.
+ *
+ *  License: www.highcharts.com/license
+ *
+ *  !!!!!!! SOURCE GETS TRANSPILED BY TYPESCRIPT. EDIT TS FILE ONLY. !!!!!!!
+ *
+ * */
+'use strict';
+import H from '../../Core/Globals.js';
+const { doc } = H;
+import HU from './HTMLUtilities.js';
+const { removeElement } = HU;
+/* *
+ *
+ *  Class
+ *
+ * */
+/**
+ * @private
+ */
+class DOMElementProvider {
+    /* *
+     *
+     *  Constructor
+     *
+     * */
+    constructor() {
+        this.elements = [];
+    }
+    /**
+     * Create an element and keep track of it for later removal.
+     * Same args as document.createElement
+     * @private
+     */
+    createElement() {
+        const el = doc.createElement.apply(doc, arguments);
+        this.elements.push(el);
+        return el;
+    }
+    /**
+     * Destroy created element, removing it from the DOM.
+     * @private
+     */
+    removeElement(element) {
+        removeElement(element);
+        this.elements.splice(this.elements.indexOf(element), 1);
+    }
+    /**
+     * Destroy all created elements, removing them from the DOM.
+     * @private
+     */
+    destroyCreatedElements() {
+        this.elements.forEach(function (element) {
+            removeElement(element);
+        });
+        this.elements = [];
+    }
+}
+/* *
+ *
+ *  Default Export
+ *
+ * */
+export default DOMElementProvider;

package/es-modules/Accessibility/Utils/EventProvider.d.ts

@@ -0,0 +1,26 @@
+import type EventCallback from '../../Core/EventCallback';
+import DOMElementType from '../../Core/Renderer/DOMElementType';
+import U from '../../Core/Utilities.js';
+interface ElementsFocusEventRemovers {
+    element: DOMElementType;
+    remover: Function;
+}
+/**
+ * @private
+ */
+declare class EventProvider {
+    constructor();
+    eventRemovers: Array<ElementsFocusEventRemovers>;
+    addEvent<T>(el: (Class<T> | T), type: string, fn: (EventCallback<T> | Function), options?: U.EventOptions): Function;
+    /**
+     * Remove added event.
+     * @private
+     */
+    removeEvent(event: Function): void;
+    /**
+     * Remove all added events.
+     * @private
+     */
+    removeAddedEvents(): void;
+}
+export default EventProvider;

package/es-modules/Accessibility/Utils/EventProvider.js

@@ -0,0 +1,65 @@
+/* *
+ *
+ *  (c) 2009-2025 Øystein Moseng
+ *
+ *  Class that can keep track of events added, and clean them up on destroy.
+ *
+ *  License: www.highcharts.com/license
+ *
+ *  !!!!!!! SOURCE GETS TRANSPILED BY TYPESCRIPT. EDIT TS FILE ONLY. !!!!!!!
+ *
+ * */
+'use strict';
+import H from '../../Core/Globals.js';
+import U from '../../Core/Utilities.js';
+const { addEvent } = U;
+/**
+ * @private
+ */
+class EventProvider {
+    /* *
+     *
+     *  Constructor
+     *
+     * */
+    constructor() {
+        this.eventRemovers = [];
+    }
+    /**
+     * Add an event to an element and keep track of it for later removal.
+     * Same args as Highcharts.addEvent.
+     * @private
+     */
+    addEvent() {
+        const remover = addEvent.apply(H, arguments);
+        this.eventRemovers.push({
+            element: arguments[0], // HTML element
+            remover
+        });
+        return remover;
+    }
+    /**
+     * Remove added event.
+     * @private
+     */
+    removeEvent(event) {
+        const pos = this.eventRemovers.map((e) => e.remover).indexOf(event);
+        this.eventRemovers[pos].remover();
+        this.eventRemovers.splice(pos, 1);
+    }
+    /**
+     * Remove all added events.
+     * @private
+     */
+    removeAddedEvents() {
+        this.eventRemovers.map((e) => e.remover)
+            .forEach((remover) => remover());
+        this.eventRemovers = [];
+    }
+}
+/* *
+ *
+ *  Default Export
+ *
+ * */
+export default EventProvider;