@highcharts/grid-pro 2.0.0

package/es-modules/Accessibility/Components/AnnotationsA11y.js

@@ -0,0 +1,160 @@
+/* *
+ *
+ *  (c) 2009-2025 Øystein Moseng
+ *
+ *  Annotations accessibility code.
+ *
+ *  License: www.highcharts.com/license
+ *
+ *  !!!!!!! SOURCE GETS TRANSPILED BY TYPESCRIPT. EDIT TS FILE ONLY. !!!!!!!
+ *
+ * */
+'use strict';
+import HTMLUtilities from '../Utils/HTMLUtilities.js';
+const { escapeStringForHTML, stripHTMLTagsFromString } = HTMLUtilities;
+/* *
+ *
+ *  Functions
+ *
+ * */
+/**
+ * Get list of all annotation labels in the chart.
+ *
+ * @private
+ * @param {Highcharts.Chart} chart The chart to get annotation info on.
+ * @return {Array<object>} The labels, or empty array if none.
+ */
+function getChartAnnotationLabels(chart) {
+    const annotations = chart.annotations || [];
+    return annotations.reduce((acc, cur) => {
+        if (cur.options &&
+            cur.options.visible !== false) {
+            acc = acc.concat(cur.labels);
+        }
+        return acc;
+    }, []);
+}
+/**
+ * Get the text of an annotation label.
+ *
+ * @private
+ * @param {Object} label The annotation label object
+ * @return {string} The text in the label.
+ */
+function getLabelText(label) {
+    return ((label.options &&
+        label.options.accessibility &&
+        label.options.accessibility.description) ||
+        (label.graphic &&
+            label.graphic.text &&
+            label.graphic.text.textStr) ||
+        '');
+}
+/**
+ * Describe an annotation label.
+ *
+ * @private
+ * @param {Object} label The annotation label object to describe
+ * @return {string} The description for the label.
+ */
+function getAnnotationLabelDescription(label) {
+    const a11yDesc = (label.options &&
+        label.options.accessibility &&
+        label.options.accessibility.description);
+    if (a11yDesc) {
+        return a11yDesc;
+    }
+    const chart = label.chart;
+    const labelText = getLabelText(label);
+    const points = label.points;
+    const getAriaLabel = (point) => (point.graphic &&
+        point.graphic.element &&
+        point.graphic.element.getAttribute('aria-label') ||
+        '');
+    const getValueDesc = (point) => {
+        const valDesc = (point.accessibility &&
+            point.accessibility.valueDescription ||
+            getAriaLabel(point));
+        const seriesName = (point &&
+            point.series.name ||
+            '');
+        return (seriesName ? seriesName + ', ' : '') + 'data point ' + valDesc;
+    };
+    const pointValueDescriptions = points
+        .filter((p) => !!p.graphic) // Filter out mock points
+        .map(getValueDesc)
+        // Filter out points we can't describe
+        .filter((desc) => !!desc);
+    const numPoints = pointValueDescriptions.length;
+    const pointsSelector = numPoints > 1 ?
+        'MultiplePoints' : numPoints ?
+        'SinglePoint' : 'NoPoints';
+    const langFormatStr = ('accessibility.screenReaderSection.annotations.description' +
+        pointsSelector);
+    const context = {
+        annotationText: labelText,
+        annotation: label,
+        numPoints: numPoints,
+        annotationPoint: pointValueDescriptions[0],
+        additionalAnnotationPoints: pointValueDescriptions.slice(1)
+    };
+    return chart.langFormat(langFormatStr, context);
+}
+/**
+ * Return array of HTML strings for each annotation label in the chart.
+ *
+ * @private
+ * @param {Highcharts.Chart} chart The chart to get annotation info on.
+ * @return {Array<string>} Array of strings with HTML content for each annotation label.
+ */
+function getAnnotationListItems(chart) {
+    const labels = getChartAnnotationLabels(chart);
+    return labels.map((label) => {
+        const desc = escapeStringForHTML(stripHTMLTagsFromString(getAnnotationLabelDescription(label), chart.renderer.forExport));
+        return desc ? `<li>${desc}</li>` : '';
+    });
+}
+/**
+ * Return the annotation info for a chart as string.
+ *
+ * @private
+ * @param {Highcharts.Chart} chart The chart to get annotation info on.
+ * @return {string} String with HTML content or empty string if no annotations.
+ */
+function getAnnotationsInfoHTML(chart) {
+    const annotations = chart.annotations;
+    if (!(annotations && annotations.length)) {
+        return '';
+    }
+    const annotationItems = getAnnotationListItems(chart);
+    return `<ul style="list-style-type: none">${annotationItems.join(' ')}</ul>`;
+}
+/**
+ * Return the texts for the annotation(s) connected to a point, or empty array
+ * if none.
+ *
+ * @private
+ * @param {Highcharts.Point} point The data point to get the annotation info from.
+ * @return {Array<string>} Annotation texts
+ */
+function getPointAnnotationTexts(point) {
+    const labels = getChartAnnotationLabels(point.series.chart);
+    const pointLabels = labels
+        .filter((label) => label.points.indexOf(point) > -1);
+    if (!pointLabels.length) {
+        return [];
+    }
+    return pointLabels.map((label) => `${getLabelText(label)}`);
+}
+/* *
+ *
+ *  Default Export
+ *
+ * */
+const AnnotationsA11y = {
+    getAnnotationsInfoHTML,
+    getAnnotationLabelDescription,
+    getAnnotationListItems,
+    getPointAnnotationTexts
+};
+export default AnnotationsA11y;

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

@@ -0,0 +1,48 @@
+import type { SVGDOMElement } from '../../Core/Renderer/DOMElementType';
+import AccessibilityComponent from '../AccessibilityComponent.js';
+import KeyboardNavigationHandler from '../KeyboardNavigationHandler.js';
+/**
+ * The ContainerComponent class
+ *
+ * @private
+ * @class
+ * @name Highcharts.ContainerComponent
+ */
+declare class ContainerComponent extends AccessibilityComponent {
+    svgTitleElement?: SVGDOMElement;
+    /**
+     * Called on first render/updates to the chart, including options changes.
+     */
+    onChartUpdate(): void;
+    /**
+     * @private
+     */
+    handleSVGTitleElement(): void;
+    /**
+     * @private
+     */
+    setSVGContainerLabel(): void;
+    /**
+     * @private
+     */
+    setGraphicContainerAttrs(): void;
+    /**
+     * Set attributes on the chart container element.
+     * @private
+     */
+    setRenderToAttrs(): void;
+    /**
+     * @private
+     */
+    makeCreditsAccessible(): void;
+    /**
+     * Empty handler to just set focus on chart
+     * @private
+     */
+    getKeyboardNavigation(): KeyboardNavigationHandler;
+    /**
+     * Accessibility disabled/chart destroyed.
+     */
+    destroy(): void;
+}
+export default ContainerComponent;

package/es-modules/Accessibility/Components/ContainerComponent.js

@@ -0,0 +1,142 @@
+/* *
+ *
+ *  (c) 2009-2025 Øystein Moseng
+ *
+ *  Accessibility component for chart container.
+ *
+ *  License: www.highcharts.com/license
+ *
+ *  !!!!!!! SOURCE GETS TRANSPILED BY TYPESCRIPT. EDIT TS FILE ONLY. !!!!!!!
+ *
+ * */
+'use strict';
+import AccessibilityComponent from '../AccessibilityComponent.js';
+import KeyboardNavigationHandler from '../KeyboardNavigationHandler.js';
+import CU from '../Utils/ChartUtilities.js';
+const { unhideChartElementFromAT, getChartTitle } = CU;
+import H from '../../Core/Globals.js';
+const { doc } = H;
+import HU from '../Utils/HTMLUtilities.js';
+const { stripHTMLTagsFromString: stripHTMLTags } = HU;
+/**
+ * The ContainerComponent class
+ *
+ * @private
+ * @class
+ * @name Highcharts.ContainerComponent
+ */
+class ContainerComponent extends AccessibilityComponent {
+    /* *
+     *
+     *  Functions
+     *
+     * */
+    /* eslint-disable valid-jsdoc */
+    /**
+     * Called on first render/updates to the chart, including options changes.
+     */
+    onChartUpdate() {
+        this.handleSVGTitleElement();
+        this.setSVGContainerLabel();
+        this.setGraphicContainerAttrs();
+        this.setRenderToAttrs();
+        this.makeCreditsAccessible();
+    }
+    /**
+     * @private
+     */
+    handleSVGTitleElement() {
+        const chart = this.chart, titleId = 'highcharts-title-' + chart.index, titleContents = stripHTMLTags(chart.langFormat('accessibility.svgContainerTitle', {
+            chartTitle: getChartTitle(chart)
+        }));
+        if (titleContents.length) {
+            const titleElement = this.svgTitleElement =
+                this.svgTitleElement || doc.createElementNS('http://www.w3.org/2000/svg', 'title');
+            titleElement.textContent = titleContents;
+            titleElement.id = titleId;
+            chart.renderTo.insertBefore(titleElement, chart.renderTo.firstChild);
+        }
+    }
+    /**
+     * @private
+     */
+    setSVGContainerLabel() {
+        const chart = this.chart, svgContainerLabel = chart.langFormat('accessibility.svgContainerLabel', {
+            chartTitle: getChartTitle(chart)
+        });
+        if (chart.renderer.box && svgContainerLabel.length) {
+            chart.renderer.box.setAttribute('aria-label', svgContainerLabel);
+        }
+    }
+    /**
+     * @private
+     */
+    setGraphicContainerAttrs() {
+        const chart = this.chart, label = chart.langFormat('accessibility.graphicContainerLabel', {
+            chartTitle: getChartTitle(chart)
+        });
+        if (label.length) {
+            chart.container.setAttribute('aria-label', label);
+        }
+    }
+    /**
+     * Set attributes on the chart container element.
+     * @private
+     */
+    setRenderToAttrs() {
+        const chart = this.chart, shouldHaveLandmark = chart.options.accessibility
+            .landmarkVerbosity !== 'disabled', containerLabel = chart.langFormat('accessibility.chartContainerLabel', {
+            title: getChartTitle(chart),
+            chart: chart
+        });
+        if (containerLabel) {
+            chart.renderTo.setAttribute('role', shouldHaveLandmark ? 'region' : 'group');
+            chart.renderTo.setAttribute('aria-label', containerLabel);
+        }
+    }
+    /**
+     * @private
+     */
+    makeCreditsAccessible() {
+        const chart = this.chart, credits = chart.credits;
+        if (credits) {
+            if (credits.textStr) {
+                credits.element.setAttribute('aria-label', chart.langFormat('accessibility.credits', {
+                    creditsStr: stripHTMLTags(credits.textStr, chart.renderer.forExport)
+                }));
+            }
+            unhideChartElementFromAT(chart, credits.element);
+        }
+    }
+    /**
+     * Empty handler to just set focus on chart
+     * @private
+     */
+    getKeyboardNavigation() {
+        const chart = this.chart;
+        return new KeyboardNavigationHandler(chart, {
+            keyCodeMap: [],
+            validate: function () {
+                return true;
+            },
+            init: function () {
+                const a11y = chart.accessibility;
+                if (a11y) {
+                    a11y.keyboardNavigation.tabindexContainer.focus();
+                }
+            }
+        });
+    }
+    /**
+     * Accessibility disabled/chart destroyed.
+     */
+    destroy() {
+        this.chart.renderTo.setAttribute('aria-hidden', true);
+    }
+}
+/* *
+ *
+ *  Default Export
+ *
+ * */
+export default ContainerComponent;

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

@@ -0,0 +1,144 @@
+import type { DOMElementType, HTMLDOMElement } from '../../Core/Renderer/DOMElementType';
+import AccessibilityComponent from '../AccessibilityComponent.js';
+import Announcer from '../Utils/Announcer.js';
+import AST from '../../Core/Renderer/HTML/AST.js';
+import Chart from '../../Core/Chart/Chart.js';
+/**
+ * The InfoRegionsComponent class
+ *
+ * @private
+ * @class
+ * @name Highcharts.InfoRegionsComponent
+ */
+declare class InfoRegionsComponent extends AccessibilityComponent {
+    announcer: Announcer;
+    dataTableButtonId?: string;
+    dataTableDiv?: HTMLDOMElement;
+    linkedDescriptionElement: (HTMLDOMElement | undefined);
+    screenReaderSections: Record<string, InfoRegionsComponent.ScreenReaderSectionObject>;
+    sonifyButton?: (DOMElementType | null);
+    sonifyButtonId?: string;
+    viewDataTableButton?: ('' | DOMElementType | null);
+    /**
+     * Init the component
+     * @private
+     */
+    init(): void;
+    /**
+     * @private
+     */
+    initRegionsDefinitions(): void;
+    /**
+     * Called on chart render. Have to update the sections on render, in order
+     * to get a11y info from series.
+     */
+    onChartRender(): void;
+    updateAllScreenReaderSections(): void;
+    /**
+     * @private
+     */
+    getLinkedDescriptionElement(): (HTMLDOMElement | undefined);
+    /**
+     * @private
+     */
+    setLinkedDescriptionAttrs(): void;
+    /**
+     * @private
+     * @param {string} regionKey
+     * The name/key of the region to update
+     */
+    updateScreenReaderSection(regionKey: string): void;
+    /**
+     * Apply a11y attributes to a screen reader info section
+     * @private
+     * @param {Highcharts.HTMLDOMElement} sectionDiv The section element
+     * @param {string} regionKey Name/key of the region we are setting attrs for
+     */
+    setScreenReaderSectionAttribs(sectionDiv: HTMLDOMElement, regionKey: string): void;
+    /**
+     * @private
+     */
+    defaultBeforeChartFormatter(): string;
+    /**
+     * @private
+     */
+    defaultAfterChartFormatter(): string;
+    /**
+     * @private
+     */
+    getLinkedDescription(): string;
+    /**
+     * @private
+     */
+    getLongdescText(): string;
+    /**
+     * @private
+     */
+    getTypeDescriptionText(): string;
+    /**
+     * @private
+     */
+    getDataTableButtonText(buttonId: string): string;
+    /**
+     * @private
+     */
+    getSonifyButtonText(buttonId: string): string;
+    /**
+     * @private
+     */
+    getSubtitleText(): string;
+    /**
+     * @private
+     */
+    getEndOfChartMarkerText(): string;
+    /**
+     * @private
+     * @param {Highcharts.Dictionary<string>} e
+     */
+    onDataTableCreated(e: {
+        tree: AST.Node;
+    }): void;
+    /**
+     * @private
+     */
+    focusDataTable(): void;
+    /**
+     * @private
+     * @param {string} sonifyButtonId
+     */
+    initSonifyButton(sonifyButtonId: string): void;
+    /**
+     * Set attribs and handlers for default viewAsDataTable button if exists.
+     * @private
+     * @param {string} tableButtonId
+     */
+    initDataTableButton(tableButtonId: string): void;
+    /**
+     * Return object with text description of each of the chart's axes.
+     * @private
+     */
+    getAxesDescription(): Record<string, string>;
+    /**
+     * @private
+     */
+    getAxisDescriptionText(collectionKey: ('xAxis' | 'yAxis')): string;
+    /**
+     * Remove component traces
+     */
+    destroy(): void;
+}
+declare namespace InfoRegionsComponent {
+    interface ScreenReaderSectionObject {
+        afterInserted?: Function;
+        element: (HTMLDOMElement | null);
+        buildContent: Function;
+        insertIntoDOM: Function;
+    }
+    interface TypeDescFormatContextObject {
+        chart: Chart;
+        mapTitle: (string | undefined);
+        numSeries: number;
+        numPoints: number;
+    }
+}
+export default InfoRegionsComponent;