@highcharts/grid-pro 2.1.1 → 2.2.0

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.
      *
@@ -94,6 +102,65 @@ declare class Accessibility {
      * Set a11y options for the Grid.
      */
     setA11yOptions(): 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,12 @@ 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 U from '../../../Core/Utilities.js';
+import HTMLU from '../../../Accessibility/Utils/HTMLUtilities.js';
 const { formatText } = GridUtils;
+const { replaceNested } = U;
+const { getHeadingTagNameForElement } = HTMLU;
 /**
  *  Representing the accessibility functionalities for the Data Grid.
  */
@@ -35,6 +41,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'));
@@ -214,10 +228,169 @@ 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);

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

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

@@ -2,11 +2,11 @@
  *
  *  Grid default options
  *
- *  (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:
  *  - Dawid Dragula
@@ -28,7 +28,8 @@ export const defaultLangOptions = {
                 ascending: 'Sorted ascending.',
                 descending: 'Sorted descending.',
                 none: 'Not sorted.'
-            }
+            },
+            priority: 'Priority {priority}.'
         },
         pagination: {
             announcements: {
@@ -45,6 +46,10 @@ export const defaultLangOptions = {
                 filterCleared: 'Filter cleared for {columnId}. ' +
                     '{rowsCount} results found.'
             }
+        },
+        screenReaderSection: {
+            beforeRegionLabel: '',
+            afterRegionLabel: ''
         }
     },
     loading: 'Loading...',
@@ -95,6 +100,13 @@ export const defaultOptions = {
         announcements: {
             sorting: true,
             filtering: true
+        },
+        screenReaderSection: {
+            beforeGridFormat: '{gridTitle}' +
+                '<div>{gridDescription}</div>' +
+                '<div>Grid with {rowCount} rows and {columnCount}' +
+                ' columns.</div>',
+            afterGridFormat: 'End of Grid.'
         }
     },
     time: {
@@ -120,7 +132,7 @@ export const defaultOptions = {
     },
     columnDefaults: {
         sorting: {
-            sortable: true
+            enabled: true
         },
         filtering: {
             inline: false

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

@@ -3,7 +3,7 @@ export type DeepRequired<T> = {
 };
 export type ClassNameKey = keyof typeof rawClassNames;
 export declare const classNamePrefix: string;
-export declare const version = "2.1.1";
+export declare const version = "2.2.0";
 export declare const rawClassNames: {
     readonly container: "container";
     readonly tableElement: "table";
@@ -15,7 +15,6 @@ export declare const rawClassNames: {
     readonly rowEven: "row-even";
     readonly rowOdd: "row-odd";
     readonly hoveredRow: "hovered-row";
-    readonly columnElement: "column";
     readonly hoveredCell: "hovered-cell";
     readonly hoveredColumn: "hovered-column";
     readonly syncedRow: "synced-row";
@@ -41,6 +40,7 @@ export declare const rawClassNames: {
     readonly columnSortableIcon: "column-sortable-icon";
     readonly columnSortedAsc: "column-sorted-asc";
     readonly columnSortedDesc: "column-sorted-desc";
+    readonly sortPriorityIndicator: "sort-priority-indicator";
     readonly resizableContent: "resizable-content";
     readonly resizerHandles: "column-resizer";
     readonly resizedColumn: "column-resized";
@@ -90,7 +90,7 @@ export declare const isSafari: boolean;
 export declare const getClassName: (classNameKey: ClassNameKey) => string;
 declare const _default: {
     readonly classNamePrefix: string;
-    readonly version: "2.1.1";
+    readonly version: "2.2.0";
     readonly rawClassNames: {
         readonly container: "container";
         readonly tableElement: "table";
@@ -102,7 +102,6 @@ declare const _default: {
         readonly rowEven: "row-even";
         readonly rowOdd: "row-odd";
         readonly hoveredRow: "hovered-row";
-        readonly columnElement: "column";
         readonly hoveredCell: "hovered-cell";
         readonly hoveredColumn: "hovered-column";
         readonly syncedRow: "synced-row";
@@ -128,6 +127,7 @@ declare const _default: {
         readonly columnSortableIcon: "column-sortable-icon";
         readonly columnSortedAsc: "column-sorted-asc";
         readonly columnSortedDesc: "column-sorted-desc";
+        readonly sortPriorityIndicator: "sort-priority-indicator";
         readonly resizableContent: "resizable-content";
         readonly resizerHandles: "column-resizer";
         readonly resizedColumn: "column-resized";

package/es-modules/Grid/Core/Globals.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:
  *  - Dawid Dragula
@@ -18,7 +18,7 @@
  *
  * */
 export const classNamePrefix = 'hcg-';
-export const version = '2.1.1';
+export const version = '2.2.0';
 export const rawClassNames = {
     container: 'container',
     tableElement: 'table',
@@ -30,7 +30,6 @@ export const rawClassNames = {
     rowEven: 'row-even',
     rowOdd: 'row-odd',
     hoveredRow: 'hovered-row',
-    columnElement: 'column',
     hoveredCell: 'hovered-cell',
     hoveredColumn: 'hovered-column',
     syncedRow: 'synced-row',
@@ -56,6 +55,7 @@ export const rawClassNames = {
     columnSortableIcon: 'column-sortable-icon',
     columnSortedAsc: 'column-sorted-asc',
     columnSortedDesc: 'column-sorted-desc',
+    sortPriorityIndicator: 'sort-priority-indicator',
     resizableContent: 'resizable-content',
     resizerHandles: 'column-resizer',
     resizedColumn: 'column-resized',

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

@@ -1,4 +1,4 @@
-import type { Options, GroupedHeaderOptions } from './Options';
+import type { ColumnSortingOrder, Options, GroupedHeaderOptions } from './Options';
 import type { NoIdColumnOptions } from './Table/Column';
 import type Popup from './UI/Popup.js';
 import Accessibility from './Accessibility/Accessibility.js';
@@ -217,6 +217,17 @@ export declare class Grid {
     redraw(): Promise<void>;
     updateColumn(columnId: string, options: NoIdColumnOptions, render?: boolean, overwrite?: boolean): Promise<void>;
     updateColumn(columnId: string, options: NoIdColumnOptions, render?: false, overwrite?: boolean): void;
+    /**
+     * Sets the sorting order for one or more columns. Provide the sortings
+     * in priority order. Use `null` to clear sorting.
+     *
+     * @param sortings
+     * The sorting definition in priority order.
+     */
+    setSorting(sortings: Array<{
+        columnId: string;
+        order: ColumnSortingOrder;
+    }> | null): Promise<void>;
     private render;
     /**
      * Hovers the row with the provided index. It removes the hover effect from

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

@@ -2,11 +2,11 @@
  *
  *  Highcharts Grid 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
@@ -25,8 +25,8 @@ import QueryingController from './Querying/QueryingController.js';
 import Globals from './Globals.js';
 import TimeBase from '../../Shared/TimeBase.js';
 import Pagination from './Pagination/Pagination.js';
-const { makeHTMLElement, setHTMLContent } = GridUtils;
-const { defined, diffObjects, extend, fireEvent, getStyle, merge, pick } = U;
+const { makeHTMLElement, setHTMLContent, createOptionsProxy } = GridUtils;
+const { defined, diffObjects, extend, fireEvent, merge, pick } = U;
 /* *
  *
  *  Class
@@ -153,8 +153,8 @@ export class Grid {
             throw new Error('Rendering div not found. It is unable to find the HTML ' +
                 'element to render the Grid in.');
         }
-        this.initialContainerHeight = getStyle(container, 'height', true) || 0;
         this.container = container;
+        this.container.style.minHeight = 0 + 'px';
         this.container.innerHTML = AST.emptyHTML;
         this.contentWrapper = makeHTMLElement('div', {
             className: Globals.getClassName('container')
@@ -195,6 +195,9 @@ export class Grid {
         merge(true, diff, diffObjects(newOptions, this.userOptions));
         this.userOptions = merge(this.userOptions, newOptions);
         this.options = merge(this.options ?? defaultOptions, this.userOptions);
+        this.viewport?.columns.forEach((column) => {
+            column.options = createOptionsProxy(this.columnOptionsMap?.[column.id]?.options ?? {}, this.options?.columnDefaults);
+        });
         return diff;
     }
     /**
@@ -496,7 +499,9 @@ export class Grid {
         fireEvent(this, 'beforeRedraw');
         const flags = this.dirtyFlags;
         if (flags.has('grid')) {
-            return await this.render();
+            await this.render();
+            fireEvent(this, 'afterRedraw');
+            return;
         }
         const { viewport: vp, pagination } = this;
         const colResizing = vp?.columnResizing;
@@ -583,6 +588,90 @@ export class Grid {
             columnId
         });
     }
+    /**
+     * Sets the sorting order for one or more columns. Provide the sortings
+     * in priority order. Use `null` to clear sorting.
+     *
+     * @param sortings
+     * The sorting definition in priority order.
+     */
+    async setSorting(sortings) {
+        const viewport = this.viewport;
+        if (!viewport) {
+            return;
+        }
+        if (viewport.validator?.errorCell) {
+            return;
+        }
+        const normalized = (sortings || []).filter((sorting) => !!(sorting.columnId && sorting.order));
+        const sortingController = this.querying.sorting;
+        const previousSortings = sortingController.currentSortings || [];
+        const eventColumnIds = new Set();
+        for (const sorting of previousSortings) {
+            if (sorting.columnId) {
+                eventColumnIds.add(sorting.columnId);
+            }
+        }
+        for (const sorting of normalized) {
+            eventColumnIds.add(sorting.columnId);
+        }
+        const eventColumns = Array.from(eventColumnIds)
+            .map((columnId) => {
+            const column = viewport.getColumn(columnId);
+            if (!column) {
+                return null;
+            }
+            const order = normalized.find((sorting) => sorting.columnId === columnId)?.order || null;
+            return { column, order };
+        })
+            .filter((item) => !!item);
+        for (const { column, order } of eventColumns) {
+            [column, this].forEach((source) => {
+                fireEvent(source, 'beforeSort', {
+                    target: column,
+                    order
+                });
+            });
+        }
+        sortingController.setSorting(normalized);
+        await viewport.updateRows();
+        const currentSortings = sortingController.currentSortings || [];
+        const hasMultiple = currentSortings.length > 1;
+        for (const column of viewport.columns) {
+            const sortingIndex = currentSortings.findIndex((sorting) => sorting.columnId === column.id);
+            if (sortingIndex !== -1 && currentSortings[sortingIndex].order) {
+                const sorting = currentSortings[sortingIndex];
+                const sortingOptions = {
+                    order: sorting.order
+                };
+                if (hasMultiple) {
+                    sortingOptions.priority = sortingIndex + 1;
+                }
+                column.setOptions({ sorting: sortingOptions });
+                if (!hasMultiple) {
+                    delete column.options.sorting?.priority;
+                }
+            }
+            else {
+                delete column.options.sorting?.order;
+                delete column.options.sorting?.priority;
+                if (column.options.sorting &&
+                    Object.keys(column.options.sorting).length < 1) {
+                    delete column.options.sorting;
+                }
+            }
+            column.sorting?.refreshHeaderAttributes();
+        }
+        this.accessibility?.userSortedColumn(currentSortings[0]?.order || null);
+        for (const { column, order } of eventColumns) {
+            [column, this].forEach((source) => {
+                fireEvent(source, 'afterSort', {
+                    target: column,
+                    order
+                });
+            });
+        }
+    }
     async render() {
         if (this.isRendered) {
             this.destroy(true);
@@ -765,7 +854,7 @@ export class Grid {
         else {
             this.renderNoData();
         }
-        this.accessibility?.setA11yOptions();
+        this.renderAccessibility();
         // Render bottom pagination, footer pagination,
         // or custom container pagination (after table).
         if (paginationPosition !== 'top') {
@@ -775,6 +864,19 @@ export class Grid {
         fireEvent(this, 'afterRenderViewport');
         this.viewport?.reflow();
     }
+    /**
+     * Renders the Grid accessibility.
+     * @internal
+     */
+    renderAccessibility() {
+        const accessibility = this.accessibility;
+        if (!accessibility) {
+            return;
+        }
+        accessibility.setA11yOptions();
+        accessibility.addScreenReaderSection('before');
+        accessibility.addScreenReaderSection('after');
+    }
     /**
      * Renders the table (viewport) of the Grid.
      *

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

@@ -2,11 +2,11 @@
  *
  *  Grid utilities
  *
- *  (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:
  *  - Dawid Dragula