@highcharts/grid-pro 2.0.0

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

@@ -0,0 +1,148 @@
+/**
+ * Accessibility options for the Grid.
+ */
+export interface A11yOptions {
+    /**
+     * Enable accessibility features for the Grid.
+     *
+     * @default true
+     */
+    enabled?: boolean;
+    /**
+     * The default option is auto, which applies the high contrast theme the
+     * user's system has a high contrast theme active.
+     */
+    highContrastMode?: boolean | 'auto';
+    /**
+     * VoiceOver announcer options for Grid actions.
+     */
+    announcements?: A11yAnnouncementsOptions;
+}
+/**
+ * VoiceOver announcer options for Grid actions.
+ */
+export interface A11yAnnouncementsOptions {
+    /**
+     * Enable accessibility announcements for the sorting.
+     *
+     * @default true
+     */
+    sorting?: boolean;
+    /**
+     * Enable accessibility announcements for the filtering.
+     *
+     * @default true
+     */
+    filtering?: boolean;
+}
+/**
+ * Accessibility language options for the Grid.
+ */
+export interface LangAccessibilityOptions {
+    /**
+     * Language options for the accessibility descriptions in sorting.
+     */
+    sorting?: SortingLangA11yOptions;
+    /**
+     * Language options for the accessibility descriptions in pagination.
+     */
+    pagination?: PaginationLangA11yOptions;
+    /**
+     * Language options for the accessibility descriptions in filtering.
+     */
+    filtering?: FilteringLangA11yOptions;
+}
+/**
+ * Accessibility options for the Grid sorting functionality.
+ */
+export interface SortingLangA11yOptions {
+    /**
+     * An additional hint (a visually hidden span) read by the voice over
+     * after the column name.
+     *
+     * @default 'Sortable.'
+     */
+    sortable?: string;
+    /**
+     * Accessibility lang options for the sorting announcements.
+     */
+    announcements?: {
+        /**
+         * The message when the column was sorted in ascending order.
+         *
+         * @default 'Sorted ascending.'
+         */
+        ascending?: string;
+        /**
+         * The message when the column was sorted in descending order.
+         *
+         * @default 'Sorted descending.'
+         */
+        descending?: string;
+        /**
+         * The message when the column was unsorted.
+         *
+         * @default 'Not sorted.'
+         */
+        none?: string;
+    };
+}
+/**
+ * Accessibility options for the Grid pagination functionality.
+ */
+export interface PaginationLangA11yOptions {
+    /**
+     * Language options for the accessibility descriptions in pagination.
+     */
+    announcements?: {
+        /**
+         * The message when the page size was changed.
+         *
+         * @default 'Page size changed to.'
+         */
+        pageSizeChange?: string;
+        /**
+         * The message when the page was changed.
+         *
+         * @default 'Page changed to.'
+         */
+        pageChange?: string;
+    };
+}
+/**
+ * Accessibility options for the Grid filtering functionality.
+ */
+export interface FilteringLangA11yOptions {
+    /**
+     * Language options for the accessibility descriptions in filtering.
+     */
+    announcements?: {
+        /**
+         * The message when the filter was applied.
+         *
+         * @default 'Filter applied for {columnId}, {condition} {value}. {rowsCount} results found.'
+         */
+        filterApplied?: string;
+        /**
+         * The message when the filter was applied for empty-like conditions.
+         *
+         * @default 'Filter applied for {columnId}, {condition} values. {rowsCount} results found.'
+         */
+        emptyFilterApplied?: string;
+        /**
+         * The message when the filter was cleared.
+         *
+         * @default 'Filter cleared for {columnId}. {rowsCount} results found.'
+         */
+        filterCleared?: string;
+    };
+}
+/**
+ * Accessibility options for the Grid header cell.
+ */
+export interface HeaderCellA11yOptions {
+    /**
+     * The aria description of the header cell.
+     */
+    description?: string;
+}

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

@@ -0,0 +1,17 @@
+/* *
+ *
+ *  Grid Accessibility options
+ *
+ *  (c) 2020-2025 Highsoft AS
+ *
+ *  License: www.highcharts.com/license
+ *
+ *  !!!!!!! SOURCE GETS TRANSPILED BY TYPESCRIPT. EDIT TS FILE ONLY. !!!!!!!
+ *
+ *  Authors:
+ *  - Dawid Dragula
+ *  - Sebastian Bochan
+ *
+ * */
+'use strict';
+export {};

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

@@ -0,0 +1,115 @@
+import type Grid from '../Grid';
+import type { ColumnSortingOrder, FilteringCondition } from '../Options';
+/**
+ *  Representing the accessibility functionalities for the Data Grid.
+ */
+declare class Accessibility {
+    /**
+     * The Data Grid Table instance which the accessibility belong to.
+     */
+    grid: Grid;
+    /**
+     * The HTML element of the accessibility.
+     */
+    private element;
+    /**
+     * The HTML element of the announcer.
+     */
+    private announcerElement;
+    /**
+     * The timeout for the announcer element removal.
+     */
+    private announcerTimeout?;
+    /**
+     * Construct the accessibility object.
+     *
+     * @param grid
+     * The Grid Table instance which the accessibility controller belong to.
+     */
+    constructor(grid: Grid);
+    /**
+     * Add the description to the header cell.
+     *
+     * @param thElement
+     * The header cell element to add the description to.
+     *
+     * @param description
+     * The description to be added.
+     */
+    addHeaderCellDescription(thElement: HTMLElement, description: string | undefined): void;
+    /**
+     * Announce the message to the screen reader.
+     *
+     * @param msg
+     * The message to be announced.
+     *
+     * @param assertive
+     * Whether the message should be assertive. Default is false.
+     */
+    announce(msg: string, assertive?: boolean): void;
+    /**
+     * Announce the message to the screen reader that the user sorted the
+     * column.
+     *
+     * @param order
+     * The order of the sorting.
+     */
+    userSortedColumn(order: ColumnSortingOrder): void;
+    /**
+     * Set the aria sort state of the column header cell element.
+     *
+     * @param thElement
+     * The header cell element to set the `aria-sort` state to.
+     *
+     * @param state
+     * The sort state to be set for the column header cell.
+     */
+    setColumnSortState(thElement: HTMLElement, state: Accessibility.AriaSortState): void;
+    /**
+     * Announce the message to the screen reader that the user filtered the
+     * column.
+     *
+     * @param filteredColumnValues
+     * The values of the filtered column.
+     *
+     * @param filteringApplied
+     * Whether the filtering was applied or cleared.
+     */
+    userFilteredColumn(filteredColumnValues: Accessibility.FilteredColumnValues, filteringApplied: boolean): void;
+    /**
+     * Adds high contrast CSS class, if the browser is in High Contrast mode.
+     */
+    addHighContrast(): void;
+    /**
+     * Set the row index attribute for the row element.
+     *
+     * @param el
+     * The row element to set the index to.
+     *
+     * @param idx
+     * The index of the row in the data table.
+     */
+    setRowIndex(el: HTMLElement, idx: number): void;
+    /**
+     * Set a11y options for the Grid.
+     */
+    setA11yOptions(): void;
+    /**
+     * Destroy the accessibility controller.
+     */
+    destroy(): void;
+}
+declare namespace Accessibility {
+    /**
+     * The possible states of the aria-sort attribute.
+     */
+    type AriaSortState = 'ascending' | 'descending' | 'none';
+    /**
+     * The values of the filtered column.
+     */
+    type FilteredColumnValues = FilteringCondition & {
+        columnId: string;
+        rowsCount: number;
+    };
+}
+export default Accessibility;

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

@@ -0,0 +1,231 @@
+/* *
+ *
+ *  Grid Accessibility class
+ *
+ *  (c) 2020-2025 Highsoft AS
+ *
+ *  License: www.highcharts.com/license
+ *
+ *  !!!!!!! SOURCE GETS TRANSPILED BY TYPESCRIPT. EDIT TS FILE ONLY. !!!!!!!
+ *
+ *  Authors:
+ *  - Dawid Dragula
+ *  - Sebastian Bochan
+ *
+ * */
+'use strict';
+import whcm from '../../../Accessibility/HighContrastMode.js';
+import Globals from '../Globals.js';
+import ColumnFiltering from '../Table/Actions/ColumnFiltering/ColumnFiltering.js';
+import GridUtils from '../GridUtils.js';
+const { formatText } = GridUtils;
+/**
+ *  Representing the accessibility functionalities for the Data Grid.
+ */
+class Accessibility {
+    /* *
+    *
+    *  Constructor
+    *
+    * */
+    /**
+     * Construct the accessibility object.
+     *
+     * @param grid
+     * The Grid Table instance which the accessibility controller belong to.
+     */
+    constructor(grid) {
+        this.grid = grid;
+        this.element = document.createElement('div');
+        this.element.classList.add(Globals.getClassName('visuallyHidden'));
+        this.grid.container?.prepend(this.element);
+        this.announcerElement = document.createElement('p');
+        this.announcerElement.setAttribute('aria-atomic', 'true');
+        this.announcerElement.setAttribute('aria-hidden', 'false');
+    }
+    /* *
+    *
+    *  Methods
+    *
+    * */
+    /**
+     * Add the description to the header cell.
+     *
+     * @param thElement
+     * The header cell element to add the description to.
+     *
+     * @param description
+     * The description to be added.
+     */
+    addHeaderCellDescription(thElement, description) {
+        if (description) {
+            thElement.setAttribute('aria-description', description);
+        }
+    }
+    /**
+     * Announce the message to the screen reader.
+     *
+     * @param msg
+     * The message to be announced.
+     *
+     * @param assertive
+     * Whether the message should be assertive. Default is false.
+     */
+    announce(msg, assertive = false) {
+        if (this.announcerTimeout) {
+            clearTimeout(this.announcerTimeout);
+        }
+        this.announcerElement.remove();
+        this.announcerElement.setAttribute('aria-live', assertive ? 'assertive' : 'polite');
+        this.element.appendChild(this.announcerElement);
+        requestAnimationFrame(() => {
+            this.announcerElement.textContent = msg;
+        });
+        this.announcerTimeout = setTimeout(() => {
+            this.announcerElement.remove();
+        }, 3000);
+    }
+    /**
+     * Announce the message to the screen reader that the user sorted the
+     * column.
+     *
+     * @param order
+     * The order of the sorting.
+     */
+    userSortedColumn(order) {
+        const { options } = this.grid;
+        const announcementsLang = options?.lang
+            ?.accessibility?.sorting?.announcements;
+        if (!options?.accessibility?.announcements?.sorting) {
+            return;
+        }
+        let msg;
+        switch (order) {
+            case 'asc':
+                msg = announcementsLang?.ascending;
+                break;
+            case 'desc':
+                msg = announcementsLang?.descending;
+                break;
+            default:
+                msg = announcementsLang?.none;
+        }
+        if (!msg) {
+            return;
+        }
+        this.announce(msg, true);
+    }
+    /**
+     * Set the aria sort state of the column header cell element.
+     *
+     * @param thElement
+     * The header cell element to set the `aria-sort` state to.
+     *
+     * @param state
+     * The sort state to be set for the column header cell.
+     */
+    setColumnSortState(thElement, state) {
+        thElement?.setAttribute('aria-sort', state);
+    }
+    /**
+     * Announce the message to the screen reader that the user filtered the
+     * column.
+     *
+     * @param filteredColumnValues
+     * The values of the filtered column.
+     *
+     * @param filteringApplied
+     * Whether the filtering was applied or cleared.
+     */
+    userFilteredColumn(filteredColumnValues, filteringApplied) {
+        const { columnId, condition, value, rowsCount } = filteredColumnValues;
+        const { lang, accessibility } = this.grid.options || {};
+        if (!accessibility?.announcements?.filtering) {
+            return;
+        }
+        const announcementsLang = lang?.accessibility?.filtering?.announcements;
+        let msg;
+        if (filteringApplied && condition) {
+            const parsedCondition = ColumnFiltering.parseCamelCaseToReadable(condition);
+            if (condition === 'empty' ||
+                condition === 'notEmpty' ||
+                condition === 'false' ||
+                condition === 'true') {
+                msg = formatText(announcementsLang?.emptyFilterApplied || '', {
+                    columnId,
+                    condition: parsedCondition,
+                    rowsCount: rowsCount
+                });
+            }
+            else {
+                msg = formatText(announcementsLang?.filterApplied || '', {
+                    columnId,
+                    condition: parsedCondition,
+                    value: value?.toString() || '',
+                    rowsCount: rowsCount
+                });
+            }
+        }
+        else {
+            msg = formatText(announcementsLang?.filterCleared || '', {
+                columnId,
+                rowsCount: rowsCount
+            });
+        }
+        this.announce(msg, true);
+    }
+    /**
+     * Adds high contrast CSS class, if the browser is in High Contrast mode.
+     */
+    addHighContrast() {
+        const highContrastMode = this.grid.options?.accessibility?.highContrastMode;
+        if (highContrastMode !== false && (whcm.isHighContrastModeActive() ||
+            highContrastMode === true)) {
+            this.grid.contentWrapper?.classList.add('hcg-theme-highcontrast');
+        }
+    }
+    /**
+     * Set the row index attribute for the row element.
+     *
+     * @param el
+     * The row element to set the index to.
+     *
+     * @param idx
+     * The index of the row in the data table.
+     */
+    setRowIndex(el, idx) {
+        el.setAttribute('aria-rowindex', idx);
+    }
+    /**
+     * Set a11y options for the Grid.
+     */
+    setA11yOptions() {
+        const grid = this.grid;
+        const tableEl = grid.tableElement;
+        if (!tableEl) {
+            return;
+        }
+        tableEl.setAttribute('aria-rowcount', grid.dataTable?.getRowCount() || 0);
+        if (grid.captionElement) {
+            tableEl.setAttribute('aria-labelledby', grid.captionElement.id);
+        }
+        if (grid.descriptionElement) {
+            tableEl.setAttribute('aria-describedby', grid.descriptionElement.id);
+        }
+        this.addHighContrast();
+    }
+    /**
+     * Destroy the accessibility controller.
+     */
+    destroy() {
+        this.element.remove();
+        this.announcerElement.remove();
+        clearTimeout(this.announcerTimeout);
+    }
+}
+/* *
+ *
+ *  Default Export
+ *
+ * */
+export default Accessibility;

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

@@ -0,0 +1,57 @@
+import type { CreditsOptions } from './Options';
+import type Grid from './Grid';
+/**
+ * Represents a credits in the grid.
+ */
+declare class Credits {
+    /**
+     * Default options of the credits.
+     */
+    static defaultOptions: CreditsOptions;
+    /**
+     * The Grid instance which the credits belong to.
+     */
+    readonly grid: Grid;
+    /**
+     * The credits container HTML element.
+     */
+    readonly containerElement: HTMLElement;
+    /**
+     * The credits content HTML element.
+     */
+    textElement: HTMLElement;
+    /**
+     * The options for the credits.
+     */
+    options: CreditsOptions;
+    /**
+     * Construct the credits.
+     *
+     * @param grid
+     * The Grid instance which the credits belong to.
+     *
+     * @param options
+     * Options for the credits label. Predefined if not provided.
+     *
+     */
+    constructor(grid: Grid, options?: CreditsOptions);
+    /**
+     * Render the credits. If the credits are disabled, they will be removed
+     * from the container.
+     */
+    render(): void;
+    private renderAnchor;
+    /**
+     * Get the height of the credits container.
+     */
+    getHeight(): number;
+    /**
+     * Destroy the credits. The credits will be removed from the container and
+     * the reference to the credits will be deleted from the Grid instance
+     * it belongs to.
+     */
+    destroy(): void;
+}
+declare namespace Credits {
+}
+export default Credits;

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

@@ -0,0 +1,125 @@
+/* *
+ *
+ *  Grid Credits class
+ *
+ *  (c) 2020-2025 Highsoft AS
+ *
+ *  License: www.highcharts.com/license
+ *
+ *  !!!!!!! SOURCE GETS TRANSPILED BY TYPESCRIPT. EDIT TS FILE ONLY. !!!!!!!
+ *
+ *  Authors:
+ *  - Dawid Dragula
+ *  - Sebastian Bochan
+ *
+ * */
+'use strict';
+import Globals from './Globals.js';
+import GridUtils from './GridUtils.js';
+const { makeHTMLElement, setHTMLContent } = GridUtils;
+/* *
+ *
+ *  Class
+ *
+ * */
+/**
+ * Represents a credits in the grid.
+ */
+class Credits {
+    /* *
+    *
+    *  Constructor
+    *
+    * */
+    /**
+     * Construct the credits.
+     *
+     * @param grid
+     * The Grid instance which the credits belong to.
+     *
+     * @param options
+     * Options for the credits label. Predefined if not provided.
+     *
+     */
+    constructor(grid, options) {
+        this.grid = grid;
+        this.containerElement = makeHTMLElement('div', {
+            className: Globals.getClassName('creditsContainer')
+        });
+        this.textElement = this.renderAnchor();
+        this.options = options ?? Credits.defaultOptions;
+        this.render();
+    }
+    /* *
+    *
+    *  Methods
+    *
+    * */
+    /**
+     * Render the credits. If the credits are disabled, they will be removed
+     * from the container.
+     */
+    render() {
+        const grid = this.grid;
+        const contentWrapper = grid.contentWrapper;
+        const { text, href } = this.options;
+        this.containerElement.remove();
+        if (!this.textElement) {
+            this.textElement = this.renderAnchor();
+        }
+        if (text) {
+            setHTMLContent(this.textElement, text);
+        }
+        if (href) {
+            this.textElement.setAttribute('href', href || '');
+        }
+        if (grid.descriptionElement) {
+            contentWrapper?.insertBefore(this.containerElement, grid.descriptionElement);
+        }
+        else {
+            contentWrapper?.appendChild(this.containerElement);
+        }
+    }
+    renderAnchor() {
+        const anchorElement = makeHTMLElement('a', {
+            className: Globals.getClassName('creditsText')
+        }, this.containerElement);
+        anchorElement.setAttribute('target', '_blank');
+        anchorElement.setAttribute('alt', 'Highcharts logo');
+        return anchorElement;
+    }
+    /**
+     * Get the height of the credits container.
+     */
+    getHeight() {
+        return this.containerElement.offsetHeight;
+    }
+    /**
+     * Destroy the credits. The credits will be removed from the container and
+     * the reference to the credits will be deleted from the Grid instance
+     * it belongs to.
+     */
+    destroy() {
+        this.containerElement.remove();
+    }
+}
+/* *
+*
+*  Static Properties
+*
+* */
+/**
+ * Default options of the credits.
+ */
+Credits.defaultOptions = {
+    enabled: true,
+    text: '',
+    href: 'https://www.highcharts.com',
+    position: 'bottom'
+};
+/* *
+ *
+ *  Default Export
+ *
+ * */
+export default Credits;

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

@@ -0,0 +1,20 @@
+import type Options from './Options';
+import type { DeepPartial } from '../../Shared/Types';
+/**
+ * Namespace for default options.
+ */
+declare namespace Defaults {
+    /**
+     * Default options for the Grid.
+     */
+    const defaultOptions: DeepPartial<Options>;
+    /**
+     * Merge the default options with custom options. Commonly used for defining
+     * reusable templates.
+     *
+     * @param options
+     * The new custom chart options.
+     */
+    function setOptions(options: DeepPartial<Options>): void;
+}
+export default Defaults;