@highcharts/grid-pro 2.1.1 → 2.3.0

package/es-modules/Data/Modifiers/RangeModifierOptions.js

@@ -1,10 +1,10 @@
 /* *
  *
- *  (c) 2009-2025 Highsoft AS
+ *  (c) 2009-2026 Highsoft AS
  *
- *  License: www.highcharts.com/license
+ *  A commercial license may be required depending on use.
+ *  See www.highcharts.com/license
  *
- *  !!!!!!! SOURCE GETS TRANSPILED BY TYPESCRIPT. EDIT TS FILE ONLY. !!!!!!!
  *
  *  Authors:
  *  - Sophie Bremer

package/es-modules/Data/Modifiers/SortModifier.d.ts

@@ -1,11 +1,11 @@
-import type DataEvent from '../DataEvent';
+import type { DataEventDetail } from '../DataEvent';
 import type SortModifierOptions from './SortModifierOptions';
 import DataModifier from './DataModifier.js';
-import DataTable from '../DataTable.js';
+import DataTable, { type Row as DataTableRow } from '../DataTable.js';
 /** @private */
 interface SortRowReference {
     index: number;
-    row: DataTable.Row;
+    row: DataTableRow;
 }
 /**
  * Sort table rows according to values of a column.
@@ -22,7 +22,7 @@ declare class SortModifier extends DataModifier {
     /**
      * Constructs an instance of the sort modifier.
      *
-     * @param {Partial<SortDataModifier.Options>} [options]
+     * @param {Partial<SortModifierOptions>} [options]
      * Options to configure the sort modifier.
      */
     constructor(options?: Partial<SortModifierOptions>);
@@ -35,16 +35,11 @@ declare class SortModifier extends DataModifier {
      * @param {Highcharts.DataTable} table
      * Table with rows to reference.
      *
-     * @return {Array<SortModifier.RowReference>}
+     * @return {Array<SortRowReference>}
      * Array of row references.
      */
     protected getRowReferences(table: DataTable): Array<SortRowReference>;
-    modifyTable(table: DataTable, eventDetail?: DataEvent.Detail): DataTable;
-}
-/**
- * Additionally provided types for modifier events and options.
- */
-declare namespace SortModifier {
+    modifyTable(table: DataTable, eventDetail?: DataEventDetail): DataTable;
 }
 declare module './DataModifierType' {
     interface DataModifierTypes {

package/es-modules/Data/Modifiers/SortModifier.js

@@ -1,10 +1,10 @@
 /* *
  *
- *  (c) 2009-2025 Highsoft AS
+ *  (c) 2009-2026 Highsoft AS
  *
- *  License: www.highcharts.com/license
+ *  A commercial license may be required depending on use.
+ *  See www.highcharts.com/license
  *
- *  !!!!!!! SOURCE GETS TRANSPILED BY TYPESCRIPT. EDIT TS FILE ONLY. !!!!!!!
  *
  *  Authors:
  *  - Sophie Bremer
@@ -13,8 +13,7 @@
  * */
 'use strict';
 import DataModifier from './DataModifier.js';
-import U from '../../Core/Utilities.js';
-const { merge } = U;
+import { merge } from '../../Shared/Utilities.js';
 /* *
  *
  *  Class
@@ -59,7 +58,7 @@ class SortModifier extends DataModifier {
     /**
      * Constructs an instance of the sort modifier.
      *
-     * @param {Partial<SortDataModifier.Options>} [options]
+     * @param {Partial<SortModifierOptions>} [options]
      * Options to configure the sort modifier.
      */
     constructor(options) {
@@ -79,7 +78,7 @@ class SortModifier extends DataModifier {
      * @param {Highcharts.DataTable} table
      * Table with rows to reference.
      *
-     * @return {Array<SortModifier.RowReference>}
+     * @return {Array<SortRowReference>}
      * Array of row references.
      */
     getRowReferences(table) {
@@ -95,9 +94,35 @@ class SortModifier extends DataModifier {
     modifyTable(table, eventDetail) {
         const modifier = this;
         modifier.emit({ type: 'modify', detail: eventDetail, table });
-        const columnIds = table.getColumnIds(), rowCount = table.getRowCount(), rowReferences = this.getRowReferences(table), { direction, orderByColumn, orderInColumn, compare: customCompare } = modifier.options, compare = SortModifier.compareFactory(direction, customCompare), orderByColumnIndex = columnIds.indexOf(orderByColumn), modified = table.getModified();
-        if (orderByColumnIndex !== -1) {
-            rowReferences.sort((a, b) => compare(a.row[orderByColumnIndex], b.row[orderByColumnIndex]));
+        const columnIds = table.getColumnIds(), rowCount = table.getRowCount(), rowReferences = this.getRowReferences(table), { direction, orderInColumn, compare: customCompare } = modifier.options, modified = table.getModified();
+        const orderBy = ('columns' in modifier.options ?
+            modifier.options.columns :
+            [modifier.options.orderByColumn]);
+        const orderByIndexes = [];
+        for (let i = 0, iEnd = orderBy.length; i < iEnd; ++i) {
+            const sort = orderBy[i];
+            const isString = typeof sort === 'string';
+            const column = isString ? sort : sort.column;
+            const columnIndex = columnIds.indexOf(column);
+            if (columnIndex === -1) {
+                continue;
+            }
+            orderByIndexes.push({
+                columnIndex,
+                compare: SortModifier.compareFactory(isString ? direction : (sort.direction || direction), isString ? customCompare : (sort.compare || customCompare))
+            });
+        }
+        if (orderByIndexes.length) {
+            rowReferences.sort((a, b) => {
+                for (let i = 0, iEnd = orderByIndexes.length; i < iEnd; ++i) {
+                    const { columnIndex, compare } = orderByIndexes[i];
+                    const result = compare(a.row[columnIndex], b.row[columnIndex]);
+                    if (result) {
+                        return result;
+                    }
+                }
+                return a.index - b.index;
+            });
         }
         if (orderInColumn) {
             const column = [];

package/es-modules/Data/Modifiers/SortModifierOptions.d.ts

@@ -1,9 +1,28 @@
 import type DataModifierOptions from './DataModifierOptions';
-import type DataTable from '../DataTable';
+import type { CellType as DataTableCellType } from '../DataTable';
 /**
- * Options to configure the modifier.
+ * Definition of a sorting level when sorting by multiple columns.
  */
-export interface SortModifierOptions extends DataModifierOptions {
+export interface SortModifierOrderByOption {
+    /**
+     * Column ID with values to order by.
+     */
+    column: string;
+    /**
+     * Direction of sorting for this level. If not set, the modifier-level
+     * `direction` is used.
+     */
+    direction?: ('asc' | 'desc');
+    /**
+     * Custom compare function for this level. If not set, the modifier-level
+     * `compare` is used.
+     */
+    compare?: (a: DataTableCellType, b: DataTableCellType) => number;
+}
+/**
+ * Base options shared by sorting modifiers.
+ */
+export interface SortModifierBaseOptions extends DataModifierOptions {
     /**
      * Name of the related modifier for these options.
      */
@@ -29,16 +48,34 @@ export interface SortModifierOptions extends DataModifierOptions {
      * A number indicating whether the first value (`a`) is less than (`-1`),
      * equal to (`0`), or greater than (`1`) the second value (`b`).
      */
-    compare?: (a: DataTable.CellType, b: DataTable.CellType) => number;
+    compare?: (a: DataTableCellType, b: DataTableCellType) => number;
+    /**
+     * Column to update with order index instead of change order of rows.
+     */
+    orderInColumn?: string;
+}
+/**
+ * Options to configure a single-column sort modifier.
+ */
+export interface SingleSortModifierOptions extends SortModifierBaseOptions {
     /**
      * Column with values to order.
      *
      * @default "y"
      */
     orderByColumn: string;
+}
+/**
+ * Options to configure a multi-column sort modifier.
+ */
+export interface MultiSortModifierOptions extends SortModifierBaseOptions {
     /**
-     * Column to update with order index instead of change order of rows.
+     * Columns and directions to order by, in priority order.
      */
-    orderInColumn?: string;
+    columns: SortModifierOrderByOption[];
 }
+/**
+ * Options to configure the modifier.
+ */
+export type SortModifierOptions = SingleSortModifierOptions | MultiSortModifierOptions;
 export default SortModifierOptions;

package/es-modules/Data/Modifiers/SortModifierOptions.js

@@ -1,10 +1,10 @@
 /* *
  *
- *  (c) 2009-2025 Highsoft AS
+ *  (c) 2009-2026 Highsoft AS
  *
- *  License: www.highcharts.com/license
+ *  A commercial license may be required depending on use.
+ *  See www.highcharts.com/license
  *
- *  !!!!!!! SOURCE GETS TRANSPILED BY TYPESCRIPT. EDIT TS FILE ONLY. !!!!!!!
  *
  *  Authors:
  *  - Sophie Bremer

package/es-modules/Grid/Core/Accessibility/A11yOptions.d.ts

@@ -1,3 +1,4 @@
+import type Grid from '../Grid';
 /**
  * Accessibility options for the Grid.
  */
@@ -17,6 +18,10 @@ export interface A11yOptions {
      * VoiceOver announcer options for Grid actions.
      */
     announcements?: A11yAnnouncementsOptions;
+    /**
+     * Options for screen reader sections before and after the Grid.
+     */
+    screenReaderSection?: ScreenReaderSectionOptions;
 }
 /**
  * VoiceOver announcer options for Grid actions.
@@ -51,6 +56,10 @@ export interface LangAccessibilityOptions {
      * Language options for the accessibility descriptions in filtering.
      */
     filtering?: FilteringLangA11yOptions;
+    /**
+     * Language options for screen reader sections before and after the Grid.
+     */
+    screenReaderSection?: ScreenReaderSectionLangOptions;
 }
 /**
  * Accessibility options for the Grid sorting functionality.
@@ -86,6 +95,13 @@ export interface SortingLangA11yOptions {
          */
         none?: string;
     };
+    /**
+     * The message for multi-column sort priority. Use `{priority}` to insert
+     * the priority index.
+     *
+     * @default 'Priority {priority}.'
+     */
+    priority?: string;
 }
 /**
  * Accessibility options for the Grid pagination functionality.
@@ -146,3 +162,64 @@ export interface HeaderCellA11yOptions {
      */
     description?: string;
 }
+/**
+ * Options for screen reader sections before and after the Grid.
+ */
+export interface ScreenReaderSectionOptions {
+    /**
+     * A formatter function to create the HTML contents of the hidden screen
+     * reader information region before the Grid.
+     */
+    beforeGridFormatter?: ScreenReaderFormatterCallback;
+    /**
+     * Format for the screen reader information region before the Grid.
+     * Supported HTML tags are h1-h6, p, div. Attributes are not supported.
+     *
+     * Available template variables:
+     * - {gridTitle}: The Grid caption/title.
+     * - {gridDescription}: The Grid description.
+     * - {rowCount}: Number of rows in the Grid.
+     * - {columnCount}: Number of columns in the Grid.
+     *
+     * @default '<div>{gridTitle}</div><div>{gridDescription}</div><div>Grid with {rowCount} rows and {columnCount} columns.</div>'
+     */
+    beforeGridFormat?: string;
+    /**
+     * A formatter function to create the HTML contents of the hidden screen
+     * reader information region after the Grid.
+     */
+    afterGridFormatter?: ScreenReaderFormatterCallback;
+    /**
+     * Format for the screen reader information region after the Grid.
+     *
+     * @default 'End of Grid.'
+     */
+    afterGridFormat?: string;
+}
+/**
+ * Formatter callback function for screen reader sections.
+ *
+ * @param grid
+ * A Grid instance.
+ *
+ * @returns
+ * A string with the HTML content of the region.
+ */
+export type ScreenReaderFormatterCallback = (grid: Grid) => string;
+/**
+ * Language options for screen reader sections.
+ */
+export interface ScreenReaderSectionLangOptions {
+    /**
+     * Text for the aria-label attribute of the before screen reader region.
+     *
+     * @default ''
+     */
+    beforeRegionLabel?: string;
+    /**
+     * Text for the aria-label attribute of the after screen reader region.
+     *
+     * @default ''
+     */
+    afterRegionLabel?: string;
+}

package/es-modules/Grid/Core/Accessibility/A11yOptions.js

@@ -2,15 +2,16 @@
  *
  *  Grid Accessibility options
  *
- *  (c) 2020-2025 Highsoft AS
+ *  (c) 2020-2026 Highsoft AS
  *
- *  License: www.highcharts.com/license
+ *  A commercial license may be required depending on use.
+ *  See www.highcharts.com/license
  *
- *  !!!!!!! SOURCE GETS TRANSPILED BY TYPESCRIPT. EDIT TS FILE ONLY. !!!!!!!
  *
  *  Authors:
  *  - Dawid Dragula
  *  - Sebastian Bochan
+ *  - Kamil Kubik
  *
  * */
 'use strict';

package/es-modules/Grid/Core/Accessibility/Accessibility.d.ts

@@ -20,6 +20,14 @@ declare class Accessibility {
      * The timeout for the announcer element removal.
      */
     private announcerTimeout?;
+    /**
+     * The before Grid screen reader section element.
+     */
+    private beforeGridElement;
+    /**
+     * The after Grid screen reader section element.
+     */
+    private afterGridElement;
     /**
      * Construct the accessibility object.
      *
@@ -93,7 +101,66 @@ declare class Accessibility {
     /**
      * Set a11y options for the Grid.
      */
-    setA11yOptions(): void;
+    setA11yOptions(): Promise<void>;
+    /**
+     * Adds the screen reader section before or after the Grid.
+     *
+     * @param placement
+     * Either 'before' or 'after'.
+     */
+    addScreenReaderSection(placement: 'before' | 'after'): void;
+    /**
+     * Sets the accessibility attributes for the screen reader section.
+     *
+     * @param sectionElement
+     * The section element.
+     *
+     * @param placement
+     * Either 'before' or 'after'.
+     */
+    setScreenReaderSectionAttributes(sectionElement: HTMLElement, placement: 'before' | 'after'): void;
+    /**
+     * Gets the default formatter for the before-Grid screen reader section.
+     * @private
+     */
+    private defaultBeforeFormatter;
+    /**
+     * Checks if a string is already wrapped in a heading tag (h1-h6).
+     * @private
+     *
+     * @param text
+     * The text to check.
+     *
+     * @returns
+     * True if the text is wrapped in a heading tag.
+     */
+    private isWrappedInHeadingTag;
+    /**
+     * Formats a string with template variables.
+     *
+     * @param format
+     * The format string.
+     *
+     * @param context
+     * The context object.
+     *
+     * @private
+     */
+    private formatTemplateString;
+    /**
+     * Gets the default formatter for the after-Grid screen reader section.
+     * @private
+     */
+    private defaultAfterFormatter;
+    /**
+     * Strips empty HTML tags from a string recursively.
+     *
+     * @param string
+     * The string to strip empty HTML tags from.
+     *
+     * @private
+     */
+    private stripEmptyHTMLTags;
     /**
      * Destroy the accessibility controller.
      */

package/es-modules/Grid/Core/Accessibility/Accessibility.js

@@ -2,15 +2,16 @@
  *
  *  Grid Accessibility class
  *
- *  (c) 2020-2025 Highsoft AS
+ *  (c) 2020-2026 Highsoft AS
  *
- *  License: www.highcharts.com/license
+ *  A commercial license may be required depending on use.
+ *  See www.highcharts.com/license
  *
- *  !!!!!!! SOURCE GETS TRANSPILED BY TYPESCRIPT. EDIT TS FILE ONLY. !!!!!!!
  *
  *  Authors:
  *  - Dawid Dragula
  *  - Sebastian Bochan
+ *  - Kamil Kubik
  *
  * */
 'use strict';
@@ -18,7 +19,11 @@ import whcm from '../../../Accessibility/HighContrastMode.js';
 import Globals from '../Globals.js';
 import ColumnFiltering from '../Table/Actions/ColumnFiltering/ColumnFiltering.js';
 import GridUtils from '../GridUtils.js';
+import AST from '../../../Core/Renderer/HTML/AST.js';
+import HTMLU from '../../../Accessibility/Utils/HTMLUtilities.js';
+import { internalClearTimeout, replaceNested } from '../../../Shared/Utilities.js';
 const { formatText } = GridUtils;
+const { getHeadingTagNameForElement } = HTMLU;
 /**
  *  Representing the accessibility functionalities for the Data Grid.
  */
@@ -35,6 +40,14 @@ class Accessibility {
      * The Grid Table instance which the accessibility controller belong to.
      */
     constructor(grid) {
+        /**
+         * The before Grid screen reader section element.
+         */
+        this.beforeGridElement = null;
+        /**
+         * The after Grid screen reader section element.
+         */
+        this.afterGridElement = null;
         this.grid = grid;
         this.element = document.createElement('div');
         this.element.classList.add(Globals.getClassName('visuallyHidden'));
@@ -73,7 +86,7 @@ class Accessibility {
      */
     announce(msg, assertive = false) {
         if (this.announcerTimeout) {
-            clearTimeout(this.announcerTimeout);
+            internalClearTimeout(this.announcerTimeout);
         }
         this.announcerElement.remove();
         this.announcerElement.setAttribute('aria-live', assertive ? 'assertive' : 'polite');
@@ -199,13 +212,13 @@ class Accessibility {
     /**
      * Set a11y options for the Grid.
      */
-    setA11yOptions() {
+    async setA11yOptions() {
         const grid = this.grid;
         const tableEl = grid.tableElement;
         if (!tableEl) {
             return;
         }
-        tableEl.setAttribute('aria-rowcount', grid.dataTable?.getRowCount() || 0);
+        tableEl.setAttribute('aria-rowcount', await grid.dataProvider?.getRowCount() || 0);
         if (grid.captionElement) {
             tableEl.setAttribute('aria-labelledby', grid.captionElement.id);
         }
@@ -214,13 +227,172 @@ class Accessibility {
         }
         this.addHighContrast();
     }
+    /**
+     * Adds the screen reader section before or after the Grid.
+     *
+     * @param placement
+     * Either 'before' or 'after'.
+     */
+    addScreenReaderSection(placement) {
+        const grid = this.grid;
+        const isBefore = placement === 'before';
+        // Get the screen reader section content.
+        const defaultFormatter = isBefore ?
+            this.defaultBeforeFormatter() :
+            this.defaultAfterFormatter();
+        const formatter = grid.options?.accessibility?.screenReaderSection?.[`${placement}GridFormatter`];
+        const content = formatter ? formatter(grid) : defaultFormatter;
+        // Create the screen reader section element.
+        const sectionElement = this[`${placement}GridElement`] = (this[`${placement}GridElement`] || document.createElement('div'));
+        // Create the hidden element.
+        const hiddenElement = sectionElement.firstChild ||
+            document.createElement('div');
+        if (content) {
+            this.setScreenReaderSectionAttributes(sectionElement, placement);
+            AST.setElementHTML(hiddenElement, content);
+            // Append only if not already a child.
+            if (hiddenElement.parentNode !== sectionElement) {
+                sectionElement.appendChild(hiddenElement);
+            }
+            // Insert only if not already in the DOM.
+            const gridContainer = grid.container;
+            if (!sectionElement.parentNode && gridContainer) {
+                if (isBefore) {
+                    gridContainer.insertBefore(sectionElement, gridContainer.firstChild);
+                }
+                else {
+                    gridContainer.appendChild(sectionElement);
+                }
+            }
+            hiddenElement.classList.add(Globals.getClassName('visuallyHidden'));
+        }
+        else {
+            if (sectionElement.parentNode) {
+                sectionElement.parentNode.removeChild(sectionElement);
+            }
+            this[`${placement}GridElement`] = null;
+        }
+    }
+    /**
+     * Sets the accessibility attributes for the screen reader section.
+     *
+     * @param sectionElement
+     * The section element.
+     *
+     * @param placement
+     * Either 'before' or 'after'.
+     */
+    setScreenReaderSectionAttributes(sectionElement, placement) {
+        const grid = this.grid;
+        sectionElement.setAttribute('id', `grid-screen-reader-region-${placement}-${grid.id}`);
+        const regionLabel = grid.options?.lang?.accessibility?.screenReaderSection?.[`${placement}RegionLabel`];
+        if (regionLabel) {
+            sectionElement.setAttribute('aria-label', regionLabel);
+            sectionElement.setAttribute('role', 'region');
+        }
+        // Position the section relatively to the Grid.
+        sectionElement.style.position = 'relative';
+    }
+    /**
+     * Gets the default formatter for the before-Grid screen reader section.
+     * @private
+     */
+    defaultBeforeFormatter() {
+        const grid = this.grid;
+        const { container, dataTable, options } = grid;
+        const format = options?.accessibility?.screenReaderSection?.beforeGridFormat;
+        if (!format || !container) {
+            return '';
+        }
+        const gridTitle = options?.caption?.text;
+        let formattedGridTitle = '';
+        if (gridTitle) {
+            if (this.isWrappedInHeadingTag(gridTitle)) {
+                formattedGridTitle = gridTitle;
+            }
+            else {
+                const headingTag = getHeadingTagNameForElement(container);
+                formattedGridTitle =
+                    `<${headingTag}>${gridTitle}</${headingTag}>`;
+            }
+        }
+        const context = {
+            gridTitle: formattedGridTitle,
+            gridDescription: options?.description?.text || '',
+            rowCount: dataTable?.rowCount || 0,
+            columnCount: (dataTable?.getColumnIds() || []).length
+        };
+        const formattedString = this.formatTemplateString(format, context);
+        return this.stripEmptyHTMLTags(formattedString);
+    }
+    /**
+     * Checks if a string is already wrapped in a heading tag (h1-h6).
+     * @private
+     *
+     * @param text
+     * The text to check.
+     *
+     * @returns
+     * True if the text is wrapped in a heading tag.
+     */
+    isWrappedInHeadingTag(text) {
+        return /^<h([1-6])[^>]*>[\s\S]*<\/h\1>$/i.test(text.trim());
+    }
+    /**
+     * Formats a string with template variables.
+     *
+     * @param format
+     * The format string.
+     *
+     * @param context
+     * The context object.
+     *
+     * @private
+     */
+    formatTemplateString(format, context) {
+        return format.replace(/\{(\w+)\}/g, (_, key) => (key in context ? String(context[key]) : `{${key}}`));
+    }
+    /**
+     * Gets the default formatter for the after-Grid screen reader section.
+     * @private
+     */
+    defaultAfterFormatter() {
+        const grid = this.grid;
+        const format = grid.options?.accessibility?.screenReaderSection
+            ?.afterGridFormat;
+        if (!format) {
+            return '';
+        }
+        return this.stripEmptyHTMLTags(format);
+    }
+    /**
+     * Strips empty HTML tags from a string recursively.
+     *
+     * @param string
+     * The string to strip empty HTML tags from.
+     *
+     * @private
+     */
+    stripEmptyHTMLTags(string) {
+        return replaceNested(string, [/<([\w\-.:!]+)\b[^<>]*>\s*<\/\1>/g, '']);
+    }
     /**
      * Destroy the accessibility controller.
      */
     destroy() {
+        // Removes the screen reader before section.
+        const beforeGridElement = this.beforeGridElement;
+        if (beforeGridElement?.parentNode) {
+            beforeGridElement.parentNode.removeChild(beforeGridElement);
+        }
+        // Removes the screen reader after section.
+        const afterGridElement = this.afterGridElement;
+        if (afterGridElement?.parentNode) {
+            afterGridElement.parentNode.removeChild(afterGridElement);
+        }
         this.element.remove();
         this.announcerElement.remove();
-        clearTimeout(this.announcerTimeout);
+        internalClearTimeout(this.announcerTimeout);
     }
 }
 /* *

package/es-modules/Grid/Core/Credits.js

@@ -2,11 +2,11 @@
  *
  *  Grid Credits class
  *
- *  (c) 2020-2025 Highsoft AS
+ *  (c) 2020-2026 Highsoft AS
  *
- *  License: www.highcharts.com/license
+ *  A commercial license may be required depending on use.
+ *  See www.highcharts.com/license
  *
- *  !!!!!!! SOURCE GETS TRANSPILED BY TYPESCRIPT. EDIT TS FILE ONLY. !!!!!!!
  *
  *  Authors:
  *  - Dawid Dragula