handsontable 17.1.0 → 18.0.0-rc1

package/dataMap/metaManager/metaSchema.mjs

@@ -1,6 +1,6 @@
 import { isEmpty } from '../../helpers/mixed.mjs';
 import { isObjectEqual } from '../../helpers/object.mjs';
-/* eslint-disable jsdoc/require-description-complete-sentence */ /**
+/**
  * @alias Options
  * @class Options
  * @description
@@ -117,7 +117,7 @@ import { isObjectEqual } from '../../helpers/object.mjs';
  * - [Configuration options](@/guides/getting-started/configuration-options/configuration-options.md)
  */ export default (()=>{
     return {
-        /* eslint-disable jsdoc/require-description-complete-sentence */ /**
+        /**
      * Information on which of the meta properties were added automatically.
      * For example: setting the `renderer` property directly won't extend the `_automaticallyAssignedMetaProps`
      * entry, but setting a `type` will modify it to `Set(3) {'renderer', 'editor', 'validator', ...}`.
@@ -191,7 +191,7 @@ import { isObjectEqual } from '../../helpers/object.mjs';
      * columns: [
      *   {
      *     type: 'date',
-     *     dateFormat: 'DD/MM/YYYY',
+     *     dateFormat: { day: '2-digit', month: '2-digit', year: 'numeric' },
      *     // allow empty values in each cell of the 'date' column
      *     allowEmpty: true
      *   }
@@ -824,7 +824,10 @@ import { isObjectEqual } from '../../helpers/object.mjs';
      *     // column options for the first (by physical index) column
      *     type: 'numeric',
      *     numericFormat: {
-     *       pattern: '0,0.00 $'
+     *       style: 'currency',
+     *       currency: 'USD',
+     *       minimumFractionDigits: 2,
+     *       maximumFractionDigits: 2
      *     }
      *   },
      *   {
@@ -1278,53 +1281,6 @@ import { isObjectEqual } from '../../helpers/object.mjs';
      * ```
      */ copyPaste: true,
         /**
-     * The `correctFormat` option configures whether incorrectly-formatted times and dates are amended or not.
-     *
-     * When the user enters dates and times, Handsontable can automatically adjust their format
-     * to match the [`dateFormat`](#dateFormat) and [`timeFormat`](@/guides/cell-types/time-cell-type/time-cell-type.md) settings.
-     *
-     * You can set the `correctFormat` option to one of the following:
-     *
-     * | Setting           | Description                                                                                                                                               |
-     * | ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
-     * | `false` (default) | Don't correct the format of the entered date or time (treat the entered date or time as invalid)                                                          |
-     * | `true`            | Correct the format of the entered date or time to match the [`dateFormat`](#dateFormat) or [`timeFormat`](@/guides/cell-types/time-cell-type/time-cell-type.md) settings |
-     *
-     * Read more:
-     * - [Date cell type](@/guides/cell-types/date-cell-type/date-cell-type.md)
-     * - [Time cell type](@/guides/cell-types/time-cell-type/time-cell-type.md)
-     * - [`dateFormat`](#dateFormat)
-     *
-     * @deprecated This option is deprecated and will be removed in the next major release.
-     * @memberof Options#
-     * @type {boolean}
-     * @default false
-     * @category Core
-     *
-     * @example
-     * ```js
-     * columns: [
-     *   {
-     *   // set the `type` of each cell in this column to `date`
-     *   type: 'date',
-     *   // for every `date` cell of this column, set the date format to `YYYY-MM-DD`
-     *   dateFormat: 'YYYY-MM-DD',
-     *   // enforce the `YYYY-MM-DD` date format
-     *   correctFormat: true
-     *   },
-     *
-     *   {
-     *   // set the `type` of each cell in this column to `time`
-     *   type: 'time',
-     *   // for every `time` cell of this column, set the time format to `h:mm:ss a`
-     *   timeFormat: 'h:mm:ss a',
-     *   // enforce the `h:mm:ss a` time format
-     *   correctFormat: true
-     *   },
-     * ],
-     * ```
-     */ correctFormat: false,
-        /**
      * The `currentColClassName` option lets you add a CSS class name
      * to each cell of the currently-visible, currently-selected columns.
      *
@@ -1685,23 +1641,14 @@ import { isObjectEqual } from '../../helpers/object.mjs';
      * ```
      */ dataSchema: undefined,
         /**
-     * Configures the date format for date cells. Accepts either a string (legacy, for [`date`](@/guides/cell-types/date-cell-type/date-cell-type.md)
-     * cells) or an object of [`Intl.DateTimeFormat`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat/DateTimeFormat)
-     * options (for [`intl-date`](@/guides/cell-types/date-cell-type/date-cell-type.md) cells).
-     *
-     * ::: warning
-     * The string form of `dateFormat` is deprecated and will be removed in the next major release.
-     * It is used only by the `date` cell type (moment.js-based). Use the `intl-date` cell type
-     * with an `Intl.DateTimeFormat` options object instead. In the next major release, `intl-date`
-     * will become the default `date` cell type, and `intl-date` will be an alias for `date`.
-     * :::
-     *
-     * **Object form (Intl.DateTimeFormat options):**
+     * Configures the date format for date cells using an
+     * [`Intl.DateTimeFormat`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat/DateTimeFormat)
+     * options object.
      *
-     * The object form is supported only when the cell type is `intl-date`. The locale is controlled separately via the [`locale`](@/api/options.md#locale) option.
+     * The locale is controlled separately via the [`locale`](@/api/options.md#locale) option.
      *
      * ::: tip Source data format
-     * For `intl-date` cells, source data must be in an ISO 8601 date format (`YYYY-MM-DD`). Otherwise operations such
+     * Source data must be in ISO 8601 date format (`YYYY-MM-DD`). Otherwise operations such
      * as sorting and filtering can be unstable or unpredictable. The `dateFormat` object affects only how dates are
      * displayed; the underlying value should remain ISO.
      * :::
@@ -1711,7 +1658,6 @@ import { isObjectEqual } from '../../helpers/object.mjs';
      * | Property     | Possible values                                    | Description                                              |
      * | ------------ | -------------------------------------------------- | -------------------------------------------------------- |
      * | `dateStyle`  | `'full'`, `'long'`, `'medium'`, `'short'`          | Date formatting style (expands to weekday, day, month, year, era) |
-     * | `timeStyle`  | `'full'`, `'long'`, `'medium'`, `'short'`          | Time formatting style (expands to hour, minute, second, timeZoneName) |
      *
      * **Date-time component options:**
      *
@@ -1747,45 +1693,16 @@ import { isObjectEqual } from '../../helpers/object.mjs';
      * - [Date cell type](@/guides/cell-types/date-cell-type/date-cell-type.md)
      * - [`locale`](@/api/options.md#locale)
      *
-     * ---
-     *
-     * **Deprecated: string form**
-     *
-     * Passing a string (e.g. `'DD/MM/YYYY'`, `'YYYY-MM-DD'`) is deprecated and works only with the `date` cell type.
-     * Migrate to the `intl-date` cell type and pass an `Intl.DateTimeFormat` options object.
-     *
-     * **Migration example:**
-     *
-     * ```js
-     * // Before (deprecated)
-     * columns: [{
-     *   type: 'date',
-     *   dateFormat: 'YYYY-MM-DD'
-     * }]
-     *
-     * // After (recommended)
-     * columns: [{
-     *   type: 'intl-date',
-     *   locale: 'en-US',
-     *   dateFormat: {
-     *     year: 'numeric',
-     *     month: '2-digit',
-     *     day: '2-digit'
-     *   }
-     * }]
-     * ```
-     *
      * @memberof Options#
-     * @type {string|object}
-     * @default 'DD/MM/YYYY'
+     * @type {Intl.DateTimeFormatOptions}
+     * @default { year: 'numeric', month: '2-digit', day: '2-digit' }
      * @category Core
      *
      * @example
      * ```js
-     * // intl-date cell type with Intl options
      * columns: [
      *   {
-     *     type: 'intl-date',
+     *     type: 'date',
      *     locale: 'en-US',
      *     dateFormat: {
      *       dateStyle: 'short'
@@ -1793,36 +1710,18 @@ import { isObjectEqual } from '../../helpers/object.mjs';
      *   }
      * ]
      * ```
-     *
-     * @example
-     * ```js
-     * // Legacy: date cell type with string format (deprecated)
-     * columns: [
-     *   {
-     *     type: 'date',
-     *     dateFormat: 'YYYY-MM-DD'
-     *   }
-     * ]
-     * ```
-     */ dateFormat: 'DD/MM/YYYY',
+     */ dateFormat: {
+            year: 'numeric',
+            month: '2-digit',
+            day: '2-digit'
+        },
         /**
-     * Configures the time format for time cells. Accepts either a string (legacy, for [`time`](@/guides/cell-types/time-cell-type/time-cell-type.md)
-     * cells) or an object of [`Intl.DateTimeFormat`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat/DateTimeFormat)
-     * options (for [`intl-time`](@/guides/cell-types/time-cell-type/time-cell-type.md) cells).
-     *
-     * ::: warning
-     * The string form of `timeFormat` is deprecated and will be removed in the next major release.
-     * It is used only by the `time` cell type. Use the `intl-time` cell type with an `Intl.DateTimeFormat`
-     * options object instead.
-     * :::
-     *
-     * **Object form (Intl.DateTimeFormat options):**
-     *
-     * The object form is supported only when the cell type is `intl-time`. The locale is controlled separately
-     * via the [`locale`](@/api/options.md#locale) option.
+     * Configures the time format for `intl-time` cells using an
+     * [`Intl.DateTimeFormat`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat/DateTimeFormat)
+     * options object. The locale is controlled separately via the [`locale`](@/api/options.md#locale) option.
      *
      * ::: tip Source data format
-     * For `intl-time` cells, source data must be in 24-hour time format (`HH:mm`, `HH:mm:ss`, or `HH:mm:ss.SSS`), matching
+     * Source data must be in 24-hour time format (`HH:mm`, `HH:mm:ss`, or `HH:mm:ss.SSS`), matching
      * the HTML `input type="time"` value. Otherwise operations such as sorting and filtering can be unstable or unpredictable.
      * The `timeFormat` object affects only how times are displayed; the underlying value should remain in that format.
      * :::
@@ -1860,43 +1759,13 @@ import { isObjectEqual } from '../../helpers/object.mjs';
      * - [Time cell type](@/guides/cell-types/time-cell-type/time-cell-type.md)
      * - [`locale`](@/api/options.md#locale)
      *
-     * ---
-     *
-     * **Deprecated: string form**
-     *
-     * Passing a string (e.g. `'h:mm:ss a'`) is deprecated and works only with the `time` cell type.
-     * Migrate to the `intl-time` cell type and pass an `Intl.DateTimeFormat` options object.
-     *
-     * **Migration example:**
-     *
-     * ```js
-     * // Before (deprecated)
-     * columns: [{
-     *   type: 'time',
-     *   timeFormat: 'h:mm:ss a'
-     * }]
-     *
-     * // After (recommended)
-     * columns: [{
-     *   type: 'intl-time',
-     *   locale: 'en-US',
-     *   timeFormat: {
-     *     hour: 'numeric',
-     *     minute: '2-digit',
-     *     second: '2-digit',
-     *     hour12: true
-     *   }
-     * }]
-     * ```
-     *
      * @memberof Options#
-     * @type {string|object}
-     * @default 'h:mm:ss a'
+     * @type {object}
+     * @default { hour: '2-digit', minute: '2-digit' }
      * @category Core
      *
      * @example
      * ```js
-     * // intl-time cell type with Intl options
      * columns: [
      *   {
      *     type: 'intl-time',
@@ -1907,47 +1776,10 @@ import { isObjectEqual } from '../../helpers/object.mjs';
      *   }
      * ]
      * ```
-     *
-     * @example
-     * ```js
-     * // Legacy: time cell type with string format (deprecated)
-     * columns: [
-     *   {
-     *     type: 'time',
-     *     timeFormat: 'h:mm:ss a'
-     *   }
-     * ]
-     * ```
-     */ timeFormat: 'h:mm:ss a',
-        /**
-     * The `datePickerConfig` option configures the `date` [cell editor](@/guides/cell-functions/cell-editor/cell-editor.md)'s date picker, which uses an external dependency: [Pikaday](https://github.com/Pikaday/Pikaday/tree/1.8.2).
-     *
-     * You can set the `datePickerConfig` option to an object with any of the available [Pikaday options](https://github.com/Pikaday/Pikaday/tree/1.8.2#configuration),
-     * except for the following, which are always overwritten by the `date` [cell editor](@/guides/cell-functions/cell-editor/cell-editor.md):
-     * - `bound`
-     * - `container`
-     * - `field`
-     * - `trigger`
-     *
-     * If the `datePickerConfig` option is not defined, the `date` [cell editor](@/guides/cell-functions/cell-editor/cell-editor.md) overwrites the following [Pikaday options](https://github.com/Pikaday/Pikaday/tree/1.8.2#configuration) as well:
-     *
-     * | Pikaday option       | Handsontable's setting |
-     * | -------------------- | ---------------------- |
-     * | `format`             | `'DD/MM/YYYY'`         |
-     * | `reposition`         | `false`                |
-     *
-     * Read more:
-     * - [`editor`](#editor)
-     * - [`dateFormat`](#dateFormat)
-     * - [Cell editor](@/guides/cell-functions/cell-editor/cell-editor.md)
-     * - [All Pikaday options →](https://github.com/Pikaday/Pikaday/tree/1.8.2#configuration)
-     *
-     * @deprecated This option is deprecated and will be removed in the next major release.
-     * @memberof Options#
-     * @type {object}
-     * @default undefined
-     * @category Core
-     */ datePickerConfig: undefined,
+     */ timeFormat: {
+            hour: '2-digit',
+            minute: '2-digit'
+        },
         /**
      * The `defaultDate` option configures the date pre-selected in the date picker editor
      * when opening an empty [`date`](@/guides/cell-types/date-cell-type/date-cell-type.md) cell for editing.
@@ -2001,6 +1833,11 @@ import { isObjectEqual } from '../../helpers/object.mjs';
      * This option can only be set at the [grid level](@/guides/getting-started/configuration-options/configuration-options.md#set-grid-options).
      * It has no effect when set in the [`columns`](#columns), [`cells`](#cells), or [`cell`](#cell) options.
      *
+     * When set to any non-`false` value, the second-click deselect behavior
+     * (Ctrl/Cmd+click on an already-selected cell removing it from a multi-cell selection)
+     * is also skipped. Without visible feedback, toggling layers off can cause unexpected
+     * highlight jumps.
+     *
      * Read more:
      * - [Selection](@/guides/cell-features/selection/selection.md)
      *
@@ -2195,23 +2032,50 @@ import { isObjectEqual } from '../../helpers/object.mjs';
      *
      * You can set the `dragToScroll` option to one of the following:
      *
-     * | Setting          | Description                                                                 |
-     * | ---------------- | --------------------------------------------------------------------------- |
-     * | `true` (default) | When selection reaches the edge of the grid's viewport, scroll the viewport |
-     * | `false`          | Don't scroll the viewport                                                   |
+     * | Setting          | Description                                                                                                                                 |
+     * | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
+     * | `true` (default) | Enable with default auto-scroll settings                                                                                                    |
+     * | `false`          | Disable the plugin entirely                                                                                                                 |
+     * | Object           | Enable with custom auto-scroll settings (see below)                                                                                        |
+     *
+     * When passing an object, the following properties control the auto-scroll speed:
+     *
+     * ```js
+     * dragToScroll: {
+     *   interval: {
+     *     min: 20,   // Fastest scroll interval in ms (reached at rampDistance)
+     *     max: 500,  // Slowest scroll interval in ms (applied at the viewport edge)
+     *   },
+     *   rampDistance: 120,  // Pixels outside the edge over which speed ramps up
+     * },
+     * ```
+     *
+     * The viewport scrolls periodically while the mouse pointer stays outside the
+     * viewport edge. Speed follows a logarithmic curve: slow at the edge, fast when
+     * far outside. The active selection (regular drag-select or autofill drag)
+     * extends to follow the scroll.
      *
      * Read more:
      * - [Plugins: `DragToScroll`](@/api/dragToScroll.md)
      *
      * @memberof Options#
-     * @type {boolean}
+     * @type {boolean|object}
      * @default true
      * @category DragToScroll
      *
      * @example
      * ```js
-     * // when selection reaches the edge of the grid's viewport, scroll the viewport
+     * // Enable with default settings
      * dragToScroll: true,
+     *
+     * // Enable with custom scroll speed
+     * dragToScroll: {
+     *   interval: { min: 60, max: 300 },
+     *   rampDistance: 60,
+     * },
+     *
+     * // Disable
+     * dragToScroll: false,
      * ```
      */ dragToScroll: true,
         /**
@@ -2951,6 +2815,73 @@ import { isObjectEqual } from '../../helpers/object.mjs';
      * ```
      */ fragmentSelection: false,
         /**
+     * The `hashLength` option sets a fixed display length for the hash mask used by the
+     * [`password`](@/guides/cell-types/password-cell-type/password-cell-type.md) cell type.
+     *
+     * By default, the hash length equals the actual value length. Set `hashLength` to a positive
+     * integer to always display that many hash symbols regardless of the real value length.
+     *
+     * @memberof Options#
+     * @type {number}
+     * @default undefined
+     * @category Core
+     *
+     * @example
+     * ```js
+     * columns: [
+     *   {
+     *     type: 'password',
+     *     hashLength: 10,
+     *   },
+     * ],
+     * ```
+     */ hashLength: undefined,
+        /**
+     * The `hashRevealDelay` option enables a brief character-reveal on each keystroke in the
+     * [`password`](@/guides/cell-types/password-cell-type/password-cell-type.md) cell type editor.
+     *
+     * When set to a positive number (milliseconds), each typed character stays visible for that
+     * duration and is then replaced by the `hashSymbol`. This lets the user confirm what they
+     * typed without permanently exposing the value. Requires `type: 'password'`.
+     *
+     * @since 17.2.0
+     * @memberof Options#
+     * @type {number}
+     * @default undefined
+     * @category Core
+     *
+     * @example
+     * ```js
+     * columns: [
+     *   {
+     *     type: 'password',
+     *     hashRevealDelay: 1000,
+     *   },
+     * ],
+     * ```
+     */ hashRevealDelay: undefined,
+        /**
+     * The `hashSymbol` option sets the character used as the hash mask in the
+     * [`password`](@/guides/cell-types/password-cell-type/password-cell-type.md) cell type renderer.
+     *
+     * Defaults to `'*'`. You can use any character, HTML entity, or string.
+     *
+     * @memberof Options#
+     * @type {string}
+     * @default '*'
+     * @category Core
+     *
+     * @example
+     * ```js
+     * columns: [
+     *   {
+     *     type: 'password',
+     *     hashSymbol: '•',
+     *   },
+     * ],
+     * ```
+     */ hashSymbol: '*',
+        /**
      * The `headerClassName` option allows adding one or more class names to the column headers' inner `div` element.
      * It can be used to align the labels in the column headers to left, center or right by setting this option to
      * `htLeft`, `htCenter`, or `htRight` respectively.
@@ -3204,12 +3135,12 @@ import { isObjectEqual } from '../../helpers/object.mjs';
      * ```
      */ isEmptyCol (col) {
             let row;
-            let rowLen;
             let value;
             const hasExplicitSchema = !!this.getSettings().dataSchema;
             const schema = this.getSchema();
             const prop = this.colToProp(col);
-            for(row = 0, rowLen = this.countRows(); row < rowLen; row++){
+            const rowLen = this.countRows();
+            for(row = 0; row < rowLen; row++){
                 value = this.getDataAtCell(row, col);
                 if (isEmpty(value) === false) {
                     if (typeof value === 'object') {
@@ -3252,11 +3183,11 @@ import { isObjectEqual } from '../../helpers/object.mjs';
      * ```
      */ isEmptyRow (row) {
             let col;
-            let colLen;
             let value;
             const hasExplicitSchema = !!this.getSettings().dataSchema;
             const schema = this.getSchema();
-            for(col = 0, colLen = this.countCols(); col < colLen; col++){
+            const colLen = this.countCols();
+            for(col = 0; col < colLen; col++){
                 value = this.getDataAtCell(row, col);
                 if (isEmpty(value) === false) {
                     const prop = this.colToProp(col);
@@ -3401,6 +3332,28 @@ import { isObjectEqual } from '../../helpers/object.mjs';
      * ```
      */ layoutDirection: 'inherit',
         /**
+     * The `layout` option configures the order of plugin UI elements within the user-orderable
+     * wrapper slots rendered around the grid: `top` and `bottom`. Each slot takes an ordered array
+     * of element keys (for example `'pagination'`). Keys you list are placed first in that order;
+     * any remaining elements follow by their default weight. The grid and the overlays layer (the
+     * modal layer, such as the dialog) are not orderable through this option. The license
+     * notification is not orderable either; it always renders last in the `bottom` slot.
+     *
+     * @since 18.0.0
+     * @memberof Options#
+     * @type {object}
+     * @default undefined
+     * @category Core
+     *
+     * @example
+     * ```js
+     * // render pagination above a custom 'summary' element registered in the bottom slot
+     * layout: {
+     *   bottom: ['pagination', 'summary'],
+     * },
+     * ```
+     */ layout: undefined,
+        /**
      * The `licenseKey` option sets your Handsontable license key.
      *
      * You can set the `licenseKey` option to one of the following:
@@ -4057,14 +4010,31 @@ import { isObjectEqual } from '../../helpers/object.mjs';
      * | `true`            | - Enable the [`NestedHeaders`](@/api/nestedHeaders.md) plugin<br>- Don't configure any nested headers                                 |
      * | Array of arrays   | - Enable the [`NestedHeaders`](@/api/nestedHeaders.md) plugin<br>- Configure headers that are nested on Handsontable's initialization |
      *
-     * If you set the `nestedHeaders` option to an array of arrays, each array configures one set of nested headers.
+     * If you set the `nestedHeaders` option to an array of arrays, each array configures one row of
+     * nested headers (top row first). Within a row, headers are listed left to right.
      *
      * Each array element configures one header, and can be one of the following:
      *
-     * | Array element | Description                                                                                  |
-     * | ------------- | -------------------------------------------------------------------------------------------- |
-     * | A string      | The header's label                                                                           |
-     * | An object     | Properties:<br>`label` (string): the header's label<br>`colspan` (integer): number of data columns the header spans<br>`rowspan` (integer): number of header rows the header spans<br>`headerClassName` (string): optional space-separated CSS class names |
+     * | Array element | Description                                               |
+     * | ------------- | --------------------------------------------------------- |
+     * | A string      | The header's label                                        |
+     * | An object     | A header configuration object (see the properties below) |
+     *
+     * A header configuration object accepts the following properties:
+     *
+     * | Property          | Type      | Description                                                                                                                                                                                                                                                                                          |
+     * | ----------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+     * | `label`           | `string`  | The header's label.                                                                                                                                                                                                                                                                                  |
+     * | `colspan`         | `number`  | The number of data columns the header spans (an integer greater than `1`). Groups the columns it covers.                                                                                                                                                                                             |
+     * | `rowspan`         | `number`  | The number of header rows the header spans (an integer greater than `1`).                                                                                                                                                                                                                            |
+     * | `headerClassName` | `string`  | One or more space-separated CSS class names added to the header element (for example, `'htRight'`).                                                                                                                                                                                                  |
+     * | `visibleWhen`     | `string`  | For a header inside a collapsible group, sets in which collapse state the header (and its columns) stays visible: `'collapsed'` (visible only while the group is collapsed), `'expanded'` (visible only while the group is expanded), or `'always'` (visible in both states). When omitted, a header in such a group defaults to `'expanded'` - it is hidden when the group collapses. At least one column of a group always stays visible. |
+     *
+     * ::: tip
+     * A header group is made collapsible through the [`collapsibleColumns`](#collapsibleColumns) option, not through
+     * `nestedHeaders`. Once a group is collapsible, mark the column(s) you want to keep visible when it collapses
+     * with `visibleWhen: 'always'` (or `'collapsed'`); the remaining columns are hidden on collapse by default.
+     * :::
      *
      * ::: tip
      * When `nestedHeaders` is configured, the `label` defined in the [`columns`](#columns) option for the same
@@ -4074,6 +4044,7 @@ import { isObjectEqual } from '../../helpers/object.mjs';
      * Read more:
      * - [Plugins: `NestedHeaders`](@/api/nestedHeaders.md)
      * - [Column groups: Nested headers](@/guides/columns/column-groups/column-groups.md#nested-headers)
+     * - [Column groups: Choose which columns stay visible when collapsed](@/guides/columns/column-groups/column-groups.md#choose-which-columns-stay-visible-when-collapsed)
      *
      * @memberof Options#
      * @type {boolean|Array[]}
@@ -4082,11 +4053,20 @@ import { isObjectEqual } from '../../helpers/object.mjs';
      *
      * @example
      * ```js
+     * // group headers with `label` and `colspan`
      * nestedHeaders: [
      *   ['A', {label: 'B', colspan: 8}, 'C'],
      *   ['D', {label: 'E', colspan: 4}, {label: 'F', colspan: 4}, 'G'],
      *   ['H', 'I', 'J', 'K', 'L', 'M', 'N', 'R', 'S', 'T']
      * ],
+     *
+     * // choose which columns stay visible when a collapsible group is collapsed:
+     * // unmarked headers (Jan, Feb, Mar) are hidden on collapse; `Total` appears only when collapsed
+     * nestedHeaders: [
+     *   ['Region', {label: 'Q1 2025', colspan: 4}],
+     *   ['Region', 'Jan', 'Feb', 'Mar', {label: 'Total', visibleWhen: 'collapsed'}]
+     * ],
+     * collapsibleColumns: true,
      * ```
      */ nestedHeaders: undefined,
         /**
@@ -4146,12 +4126,6 @@ import { isObjectEqual } from '../../helpers/object.mjs';
      * Configures the number format for [`numeric`](@/guides/cell-types/numeric-cell-type/numeric-cell-type.md)
      * cells, including currency, units, precision, and other display options.
      *
-     * ::: warning
-     * The `numericFormat.pattern` and `numericFormat.culture` options are deprecated and will be
-     * removed in the next major release. Pass `Intl.NumberFormat` options directly to `numericFormat`
-     * and use the `locale` cell property instead of `culture`.
-     * :::
-     *
      * Since v17.0.0, this option accepts all properties of the
      * [`Intl.NumberFormatOptions`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat/NumberFormat)
      * object. The locale is controlled separately via the [`locale`](@/api/options.md#locale) option.
@@ -4217,39 +4191,8 @@ import { isObjectEqual } from '../../helpers/object.mjs';
      * - [`locale`](@/api/options.md#locale)
      * - [Numeric cell type](@/guides/cell-types/numeric-cell-type/numeric-cell-type.md)
      * - [Cell renderer](@/guides/cell-functions/cell-renderer/cell-renderer.md)
-     * - [Numbro cell type](@/recipes/cell-types/numbro/numbro.md)
      * - [Third-party licenses](@/guides/technical-specification/third-party-licenses/third-party-licenses.md)
      *
-     * ---
-     *
-     * **Deprecated options:**
-     *
-     * The `pattern` and `culture` properties (numbro.js-based formatting) are deprecated and will be
-     * removed in the next major release. Migrate to the `Intl.NumberFormat` API shown above.
-     *
-     * | Deprecated property | Possible values                                                               | Replacement                                           |
-     * | ------------------- | ----------------------------------------------------------------------------- | ----------------------------------------------------- |
-     * | `pattern`           | All [`numbro.js` number formats](https://numbrojs.com/format.html#numbers)    | Use `Intl.NumberFormat` options (see tables above)    |
-     * | `culture`           | All [`numbro.js` currency formats](https://numbrojs.com/format.html#currency) | Use the [`locale`](@/api/options.md#locale) option    |
-     *
-     * **Migration example:**
-     *
-     * ```js
-     * // Before (deprecated)
-     * numericFormat: {
-     *   pattern: '0,0.00 $',
-     *   culture: 'en-US'
-     * }
-     *
-     * // After (recommended)
-     * locale: 'en-US',
-     * numericFormat: {
-     *   style: 'currency',
-     *   currency: 'USD',
-     *   minimumFractionDigits: 2
-     * }
-     * ```
-     *
      * @memberof Options#
      * @since 0.35.0
      * @type {object}
@@ -4395,7 +4338,7 @@ import { isObjectEqual } from '../../helpers/object.mjs';
      * columns: [
      *   {
      *     data: 'date',
-     *     dateFormat: 'DD/MM/YYYY',
+     *     dateFormat: { day: '2-digit', month: '2-digit', year: 'numeric' },
      *     // display 'Empty date cell' text
      *     // in every empty cell of the `date` column
      *     placeholder: 'Empty date cell'
@@ -6027,7 +5970,7 @@ import { isObjectEqual } from '../../helpers/object.mjs';
      * ```
      *
      * @memberof Options#
-     * @type {function(any, number, number): any}
+     * @type {function(*, number, number): *}
      * @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.
@@ -6050,7 +5993,7 @@ import { isObjectEqual } from '../../helpers/object.mjs';
      * ```
      *
      * @memberof Options#
-     * @type {function(any, number, number): any}
+     * @type {function(*, number, number): *}
      * @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.
@@ -6327,8 +6270,10 @@ import { isObjectEqual } from '../../helpers/object.mjs';
      * Whenever Handsontable sets HTML (e.g. cell content, headers, context menu labels, dialog content,
      * paste from clipboard), it can pass the string through this function first. Sanitization is important
      * when content comes from users or external sources to prevent XSS (e.g. script injection, event handlers).
-     * If no sanitizer is set, HTML is applied as-is. Set a sanitizer when you need to allow rich content
-     * while stripping or neutralizing dangerous markup.
+     *
+     * By default (when no sanitizer is set), HTML is applied as-is (pass-through). You are responsible for
+     * XSS protection. Set a sanitizer when you need to allow rich content while stripping or neutralizing
+     * dangerous markup.
      *
      * The function receives the raw HTML string and an optional second argument (source) indicating where
      * the content is used (e.g. `'innerHTML'`, `'CopyPaste.paste'`), so you can apply different rules per source.
@@ -6345,20 +6290,8 @@ import { isObjectEqual } from '../../helpers/object.mjs';
      *
      * @example
      * ```js
-     * // Allowlist-based sanitization based on the DOMPurify library
-     * import DOMPurify from 'dompurify';
-     *
-     * sanitizer: (content, source) {
-     *   if (source === 'CopyPaste.paste') {
-     *     return DOMPurify.sanitize(content, {
-     *       ADD_TAGS: ['meta'],
-     *       ADD_ATTR: ['content'],
-     *       FORCE_BODY: true,
-     *     });
-     *   }
-     *
-     *   return DOMPurify.sanitize(content);
-     * },
+     * // Allowlist-based sanitization using a custom library
+     * sanitizer: (content, source) => myLibrary.sanitize(content),
      * ```
      *
      * @example
@@ -6385,11 +6318,11 @@ import { isObjectEqual } from '../../helpers/object.mjs';
      * // Trusted Types: wrap sanitization in a policy so the sink accepts the result.
      * // Add the policy name to the CSP trusted-types directive (e.g. trusted-types default handsontable).
      * const policy = window.trustedTypes?.createPolicy('handsontable', {
-     *   createHTML: (input) => DOMPurify.sanitize(input),
+     *   createHTML: (input) => myLibrary.sanitize(input),
      * });
      *
      * sanitizer: (content, source) =>
-     *   policy ? policy.createHTML(content) : DOMPurify.sanitize(content),
+     *   policy ? policy.createHTML(content) : myLibrary.sanitize(content),
      * ```
      */ sanitizer: undefined,
         /**