handsontable 16.0.1-next-eee5f08-20250710 → 16.1.0-next-abd8f2e-20250904

package/dataMap/metaManager/metaSchema.mjs

@@ -1794,6 +1794,117 @@ export default () => {
      * ```
      */
     disableVisualSelection: false,
+    /**
+     * @description
+     * The `dialog` option configures the [`Dialog`](@/api/dialog.md) plugin.
+     *
+     * You can set the `dialog` option to one of the following:
+     *
+     * | Setting   | Description                                                                 |
+     * | --------- | --------------------------------------------------------------------------- |
+     * | `false`   | Disable the [`Dialog`](@/api/dialog.md) plugin                              |
+     * | `true`    | Enable the [`Dialog`](@/api/dialog.md) plugin with default options          |
+     *
+     * ##### dialog: Additional options
+     *
+     * | Option                   | Possible settings                                                                                                               | Description                             |
+     * | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------|
+     * | `content`                | A string, HTMLElement or DocumentFragment (default: `''`)                                                                       | The content of the dialog               |
+     * | `customClassName`        | A string (default: `''`)                                                                                                        | The custom class name of the dialog     |
+     * | `background`             | One of the options: `'solid'` or `'semi-transparent'` (default: `'solid'`)                                                      | The background of the dialog            |
+     * | `contentBackground`      | Boolean (default: `false`)                                                                                                      | Whether to show the content background  |
+     * | `animation`              | Boolean (default: `true`)                                                                                                       | Whether to show the animation           |
+     * | `closable`               | Boolean (default: `false`)                                                                                                      | Whether to make the dialog closable     |
+     * | `a11y`                   | Object with accessibility options (default: `{ role: 'dialog', ariaLabel: 'Dialog', ariaLabelledby: '', ariaDescribedby: '' }`) | Accessibility options for the dialog    |
+     *
+     * Read more:
+     * - [Plugins: `Dialog`](@/api/dialog.md)
+     *
+     * @since 16.1.0
+     * @memberof Options#
+     * @type {boolean|object}
+     * @default false
+     * @category Dialog
+     *
+     * @example
+     * ::: only-for javascript
+     * ```js
+     * // enable the Dialog plugin with default option
+     * dialog: true,
+     *
+     * // enable the Dialog plugin with custom configuration
+     * dialog: {
+     *   content: 'Dialog content',
+     *   customClassName: 'custom-dialog',
+     *   background: 'semi-transparent',
+     *   contentBackground: false,
+     *   animation: false,
+     *   closable: true,
+     *   a11y: {
+     *     role: 'dialog',
+     *     ariaLabel: 'Dialog',
+     *     ariaLabelledby: 'titleID',
+     *     ariaDescribedby: 'descriptionID',
+     *   }
+     * }
+     * ```
+     * :::
+     *
+     * ::: only-for react
+     * ```jsx
+     * // enable the Dialog plugin with default option
+     * <HotTable
+     *   dialog={true}
+     * />
+     *
+     * // enable the Dialog plugin with custom configuration
+     * <HotTable
+     *   dialog={{
+     *     content: 'Dialog content',
+     *     customClassName: 'custom-dialog',
+     *     background: 'semi-transparent',
+     *     contentBackground: false,
+     *     animation: false,
+     *     closable: true,
+     *     a11y: {
+     *       role: 'dialog',
+     *       ariaLabel: 'Dialog',
+     *       ariaLabelledby: 'titleID',
+     *       ariaDescribedby: 'descriptionID',
+     *     }
+     *   }
+     *   }}
+     * />
+     * ```
+     * :::
+     *
+     * ::: only-for angular
+     * ```ts
+     * settings = {
+     *   dialog: {
+     *     content: 'Dialog content',
+     *     customClassName: 'custom-dialog',
+     *     background: 'semi-transparent',
+     *     contentBackground: false,
+     *     animation: false,
+     *     closable: true,
+     *     a11y: {
+     *       role: 'dialog',
+     *       ariaLabel: 'Dialog',
+     *       ariaLabelledby: 'titleID',
+     *       ariaDescribedby: 'descriptionID',
+     *     }
+     *   }
+     * };
+     * ```
+     *
+     * ```html
+     * <hot-table [settings]="settings" />
+     * ```
+     * :::
+     *
+     */
+    dialog: false,
     /**
      * @description
      * The `dragToScroll` option configures the [`DragToScroll`](@/api/dragToScroll.md) plugin.
@@ -2517,6 +2628,28 @@ export default () => {
      * ```
      */
     hiddenRows: undefined,
+    /**
+     * The `initialState` option configures the grid's initial state.
+     * This object accepts any grid configuration option. In case of conflicts between
+     * `initialState` and table settings, the table settings take precedence.
+     * Note: The `initialState` option is ignored when passed to the
+     * [`updateSettings()`](@/api/core.md#updatesettings) method.
+     *
+     * @since 16.1.0
+     * @memberof Options#
+     * @type {object | undefined}
+     * @default undefined
+     * @category Core
+     *
+     * @example
+     * ```js
+     * initialState: {
+     *   // configure initial column order
+     *   manualColumnMove: [1, 0],
+     * },
+     * ```
+     */
+    initialState: undefined,
     /**
      * The `invalidCellClassName` option lets you add a CSS class name to cells
      * that were marked as `invalid` by the [cell validator](@/guides/cell-functions/cell-validator/cell-validator.md).
@@ -2815,6 +2948,50 @@ export default () => {
      * ```
      */
     locale: 'en-US',
+    /**
+     * @description
+     * The `loading` option configures the [`Loading`](@/api/loading.md) plugin.
+     *
+     * Loading plugin, automatically loads [`Dialog`](@/api/dialog.md) plugin.
+     *
+     * You can set the `loading` option to one of the following:
+     *
+     * | Setting   | Description                                                                 |
+     * | --------- | --------------------------------------------------------------------------- |
+     * | `false`   | Disable the [`Loading`](@/api/loading.md) plugin                           |
+     * | `true`    | Enable the [`Loading`](@/api/loading.md) plugin with default configuration |
+     * | An object | - Enable the [`Loading`](@/api/loading.md) plugin<br>- Apply custom configuration |
+     *
+     * If you set the `loading` option to an object, you can configure the following loading options:
+     *
+     * | Option        | Possible settings | Description                                               |
+     * | ------------- | ----------------- | --------------------------------------------------------- |
+     * | `icon`        | A string          | Custom loading icon to display (default: `<svg />`)       |
+     * | `title`       | A string          | Custom loading title to display (default: `'Loading...'`) |
+     * | `description` | A string          | Custom loading description to display (default: `''`)     |
+     *
+     * Read more:
+     * - [Plugins: `Loading`](@/api/loading.md)
+     * @since 16.1.0
+     * @memberof Options#
+     * @type {boolean|object}
+     * @default false
+     * @category Loading
+     *
+     * @example
+     * ```js
+     * // enable the `Loading` plugin with default configuration
+     * loading: true,
+     *
+     * // enable the `Loading` plugin with custom configuration
+     * loading: {
+     *   icon: 'A custom loading icon in SVG format',
+     *   title: 'Custom loading title',
+     *   description: 'Custom loading description',
+     * }
+     * ```
+     */
+    loading: false,
     /**
      * The `manualColumnFreeze` option configures the [`ManualColumnFreeze`](@/api/manualColumnFreeze.md) plugin.
      *
@@ -3482,6 +3659,48 @@ export default () => {
      * ```
      */
     outsideClickDeselects: true,
+    /**
+     * @description
+     * The `pagination` option configures the [`Pagination`](@/api/pagination.md) plugin.
+     *
+     * You can set the `pagination` option to one of the following:
+     *
+     * | Setting                          | Description                                                                                   |
+     * | -------------------------------- | --------------------------------------------------------------------------------------------- |
+     * | `false`                          | Disable the [`Pagination`](@/api/pagination.md) plugin                                            |
+     * | `true`                           | Enable the [`Pagination`](@/api/pagination.md) plugin                                             |
+     *
+     * ##### pagination: Additional options
+     *
+     * If you set the `pagination` option to an object, you can set the following `Pagination` plugin options:
+     *
+     * | Option                   | Possible settings                                  | Description                                                                                                                                                      |
+     * | ------------------------ | -------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+     * | `pageSize`               | A number or `auto` (default: `10`)                 | Sets the number of rows displayed per page. If `'auto'` is set, the page size will be calculated to match all rows to the currently set table's viewport height  |
+     * | `pageSizeList`           | An array (default: `['auto', 5, 10, 20, 50, 100]`) | Defines the selectable values for page size in the UI                                                                                                            |
+     * | `initialPage`            | A number (default: `1`)                            | Specifies which page to display on initial load                                                                                                                  |
+     * | `showPageSize`           | Boolean (default: `true`)                          | Controls visibility of the "page size" section                                                                                                                   |
+     * | `showCounter`            | Boolean (default: `true`)                          | Controls visibility of the "page counter" section (e.g., "1 - 10 of 50");                                                                                        |
+     * | `showNavigation`         | Boolean (default: `true`)                          | Controls visibility of the "page navigation" section                                                                                                             |
+     * | `uiContainer`            | An HTML element (default: `null`)                  | The container element where the pagination UI will be installed. If not provided, the pagination container will be injected below the root table element.        |
+     *
+     * Read more:
+     * - [Rows pagination](@/guides/rows/rows-pagination/rows-pagination.md)
+     * - [Plugins: `Pagination`](@/api/pagination.md)
+     *
+     * @since 16.1.0
+     * @memberof Options#
+     * @type {boolean}
+     * @default undefined
+     * @category Pagination
+     *
+     * @example
+     * ```js
+     * // enable the `Pagination` plugin
+     * pagination: true,
+     * ```
+     */
+    pagination: undefined,
     /**
      * @description
      * The `persistentState` option configures the [`PersistentState`](@/api/persistentState.md) plugin.
@@ -3883,7 +4102,7 @@ export default () => {
     /**
      * The `rowHeights` option sets rows' heights, in pixels.
      *
-     * In the rendering process, the default row height is `classic: 23px`, `main: 29px`, `horizon: 37px` (in the classic theme: 22px + 1px of the row's bottom border) or whatever is defined in the used theme (based on the line height, vertical padding and cell borders).
+     * In the rendering process, the default row height is `classic (legacy): 23px`, `main: 29px`, `horizon: 37px` (in the classic (legacy) theme: 22px + 1px of the row's bottom border) or whatever is defined in the used theme (based on the line height, vertical padding and cell borders).
      * You can change it to equal or greater than the default value, by setting the `rowHeights` option to one of the following:
      *
      * | Setting     | Description                                                                                         | Example                                                      |
@@ -4175,9 +4394,13 @@ export default () => {
      *
      * You can set the `source` option to one of the following:
      *
-     * - An array
+     * - An array of string values
+     * - An array of objects with `key` and `value` properties
      * - A function
      *
+     * Note: When defining the `source` option as an array of objects with `key` and `value` properties, the data format for that cell
+     * needs to be an object with `key` and `value` properties as well.
+     *
      * Read more:
      * - [Autocomplete cell type](@/guides/cell-types/autocomplete-cell-type/autocomplete-cell-type.md)
      * - [Dropdown cell type](@/guides/cell-types/dropdown-cell-type/dropdown-cell-type.md)
@@ -4193,7 +4416,7 @@ export default () => {
      *
      * @example
      * ```js
-     * // set `source` to an array
+     * // set `source` to an array of string values
      * columns: [{
      *   // set the `type` of each cell in this column to `autocomplete`
      *   type: 'autocomplete',
@@ -4201,6 +4424,20 @@ export default () => {
      *   source: ['A', 'B', 'C', 'D']
      * }],
      *
+     * // set `source` to an array of objects with `key` and `value` properties
+     * columns: [{
+     *   // set the `type` of each cell in this column to `autocomplete`
+     *   type: 'autocomplete',
+     *   // set options available in every `autocomplete` cell of this column
+     *   source: [{
+     *     key: 'A',
+     *     value: 'Label A'
+     *   }, {
+     *     key: 'B',
+     *     value: 'Label B'
+     *   }]
+     * }],
+     *
      * // set `source` to a function
      * columns: [{
      *   // set the `type` of each cell in this column to `autocomplete`
@@ -4388,7 +4625,7 @@ export default () => {
     /**
      * The `themeName` option allows enabling a theme by that name.
      *
-     * If no `themeName` is provided, the table will use the classic theme (if the correct CSS files are imported).
+     * If no `themeName` is provided, the table will use the classic (legacy) theme (if the correct CSS files are imported).
      *
      * Read more:
      * - [Themes](@/guides/styling/themes/themes.md)
@@ -4754,6 +4991,54 @@ export default () => {
      * ```
      */
     validator: undefined,
+    /**
+     * @description
+     * The `valueGetter` option configures a function that defines what value will be used when displaying the cell content.
+     * It can be used to modify the value of a cell before it is displayed (for example, for object-based data).
+     *
+     * @example
+     * ```js
+     * // use the `label` property of the value object with a fallback to the value itself
+     * valueGetter: (value, row, column, cellMeta) => {
+     *   return value?.label ?? value;
+     * }
+     * ```
+     *
+     * @memberof Options#
+     * @type {function(any, number, number): any}
+     * @param {*} value The value to be displayed in the cell.
+     * @param {number} row The visual row index of the cell.
+     * @param {number} column The visual column index of the cell.
+     * @param {object} cellMeta The cell meta object.
+     * @since 16.1.0
+     * @default undefined
+     * @category Core
+     */
+    valueGetter: undefined,
+    /**
+     * @description
+     * The `valueSetter` option configures a function that defines what value will be used when setting the cell content.
+     * It can be used to modify the value of a cell before it is saved (for example, for object-based data).
+     *
+     * @example
+     * ```js
+     * // Modify the value of a cell before it is saved
+     * valueSetter: (value, row, column, cellMeta) => {
+     *   return { id: value?.id ?? value, value: `${value?.value ?? value} at ${row}, ${column}` }
+     * },
+     * ```
+     *
+     * @memberof Options#
+     * @type {function(any, number, number): any}
+     * @param {*} value The value to be set to a cell.
+     * @param {number} row The visual row index of the cell.
+     * @param {number} column The visual column index of the cell.
+     * @param {object} cellMeta The cell meta object.
+     * @since 16.1.0
+     * @default undefined
+     * @category Core
+     */
+    valueSetter: undefined,
     /**
      * @description
      * The `viewportColumnRenderingOffset` option configures the number of columns

package/dataMap/metaManager/utils.js

@@ -5,7 +5,6 @@ exports.assert = assert;
 exports.columnFactory = columnFactory;
 exports.extendByMetaType = extendByMetaType;
 exports.isNullish = isNullish;
-exports.isUnsignedNumber = isUnsignedNumber;
 require("core-js/modules/es.error.cause.js");
 require("core-js/modules/es.set.difference.v2.js");
 require("core-js/modules/es.set.intersection.v2.js");
@@ -95,16 +94,6 @@ function columnFactory(TableMeta) {
   return ColumnMeta;
 }
 
-/**
- * Helper which checks if the provided argument is an unsigned number.
- *
- * @param {*} value Value to check.
- * @returns {boolean}
- */
-function isUnsignedNumber(value) {
-  return Number.isInteger(value) && value >= 0;
-}
-
 /**
  * Function which makes assertion by custom condition. Function throws an error when assertion doesn't meet the spec.
  *

package/dataMap/metaManager/utils.mjs

@@ -87,16 +87,6 @@ export function columnFactory(TableMeta) {
   return ColumnMeta;
 }
 
-/**
- * Helper which checks if the provided argument is an unsigned number.
- *
- * @param {*} value Value to check.
- * @returns {boolean}
- */
-export function isUnsignedNumber(value) {
-  return Number.isInteger(value) && value >= 0;
-}
-
 /**
  * Function which makes assertion by custom condition. Function throws an error when assertion doesn't meet the spec.
  *

package/dataMap/replaceData.js

@@ -111,6 +111,7 @@ function replaceData(data, setDataMapFunction, callbackFunction, config) {
   // TODO: rethink the way the `afterChange` hook is being run here in the core `init` method.
   if (!firstRun) {
     hotInstance.runHooks('afterChange', null, internalSource);
+    hotInstance.view.adjustElementsSize();
     hotInstance.render();
   }
   if (hotInstance.getSettings().ariaTags) {

package/dataMap/replaceData.mjs

@@ -106,6 +106,7 @@ function replaceData(data, setDataMapFunction, callbackFunction, config) {
   // TODO: rethink the way the `afterChange` hook is being run here in the core `init` method.
   if (!firstRun) {
     hotInstance.runHooks('afterChange', null, internalSource);
+    hotInstance.view.adjustElementsSize();
     hotInstance.render();
   }
   if (hotInstance.getSettings().ariaTags) {