handsontable 18.0.0-rc4 → 18.0.0

package/dataMap/metaManager/index.d.ts

@@ -190,6 +190,28 @@ export default class MetaManager {
      * @returns {object[]}
      */
     getCellsMetaAtRow(physicalRow: number): Record<string, unknown>[];
+    /**
+     * Returns a flat snapshot of all cell meta properties that were set imperatively through
+     * `setCellMeta` (for example, by the user or by the context menu), keyed by physical coordinates.
+     * Used to preserve user-defined meta across a `clearCache` call during `updateSettings`.
+     *
+     * @returns {{physicalRow: number, physicalColumn: number, key: string, value: *}[]}
+     */
+    getUserDefinedCellMetas(): {
+        physicalRow: number;
+        physicalColumn: number;
+        key: string;
+        value: unknown;
+    }[];
+    /**
+     * Enables tracking of user-defined cell meta properties set through `setCellMeta`.
+     */
+    enableUserDefinedMetaRecording(): void;
+    /**
+     * Disables tracking of user-defined cell meta properties. Writes made while disabled are treated
+     * as declarative (for example, the `cell` option applied during `updateSettings`).
+     */
+    disableUserDefinedMetaRecording(): void;
     /**
      * Creates one or more rows at specific position.
      *

package/dataMap/metaManager/index.js

@@ -158,6 +158,26 @@ class MetaManager {
         return this.cellMeta.getMetasAtRow(physicalRow);
     }
     /**
+   * Returns a flat snapshot of all cell meta properties that were set imperatively through
+   * `setCellMeta` (for example, by the user or by the context menu), keyed by physical coordinates.
+   * Used to preserve user-defined meta across a `clearCache` call during `updateSettings`.
+   *
+   * @returns {{physicalRow: number, physicalColumn: number, key: string, value: *}[]}
+   */ getUserDefinedCellMetas() {
+        return this.cellMeta.getUserDefinedMetas();
+    }
+    /**
+   * Enables tracking of user-defined cell meta properties set through `setCellMeta`.
+   */ enableUserDefinedMetaRecording() {
+        this.cellMeta.enableUserDefinedMetaRecording();
+    }
+    /**
+   * Disables tracking of user-defined cell meta properties. Writes made while disabled are treated
+   * as declarative (for example, the `cell` option applied during `updateSettings`).
+   */ disableUserDefinedMetaRecording() {
+        this.cellMeta.disableUserDefinedMetaRecording();
+    }
+    /**
    * Creates one or more rows at specific position.
    *
    * @param {number} physicalRow The physical row index which points from what position the row is added.

package/dataMap/metaManager/index.mjs

@@ -143,6 +143,26 @@ class MetaManager {
         return this.cellMeta.getMetasAtRow(physicalRow);
     }
     /**
+   * Returns a flat snapshot of all cell meta properties that were set imperatively through
+   * `setCellMeta` (for example, by the user or by the context menu), keyed by physical coordinates.
+   * Used to preserve user-defined meta across a `clearCache` call during `updateSettings`.
+   *
+   * @returns {{physicalRow: number, physicalColumn: number, key: string, value: *}[]}
+   */ getUserDefinedCellMetas() {
+        return this.cellMeta.getUserDefinedMetas();
+    }
+    /**
+   * Enables tracking of user-defined cell meta properties set through `setCellMeta`.
+   */ enableUserDefinedMetaRecording() {
+        this.cellMeta.enableUserDefinedMetaRecording();
+    }
+    /**
+   * Disables tracking of user-defined cell meta properties. Writes made while disabled are treated
+   * as declarative (for example, the `cell` option applied during `updateSettings`).
+   */ disableUserDefinedMetaRecording() {
+        this.cellMeta.disableUserDefinedMetaRecording();
+    }
+    /**
    * Creates one or more rows at specific position.
    *
    * @param {number} physicalRow The physical row index which points from what position the row is added.

package/dataMap/metaManager/metaLayers/cellMeta.d.ts

@@ -29,6 +29,7 @@ import type ColumnMeta from './columnMeta';
  *                    +-------------+
  */
 export default class CellMeta {
+    #private;
     /**
      * Reference to the ColumnMeta layer. While creating new cell meta objects, all new objects
      * inherit properties from the ColumnMeta layer.
@@ -48,6 +49,20 @@ export default class CellMeta {
      * Initializes the cell meta layer with a reference to the ColumnMeta layer used as the prototype source for new cell meta objects.
      */
     constructor(columnMeta: ColumnMeta);
+    /**
+     * Resumes tracking of user-defined cell meta properties by closing one suspension scope opened by
+     * `disableUserDefinedMetaRecording`. Recording becomes active again only once every suspension has
+     * been closed. Subsequent `setMeta` calls then mark their keys as user-defined, so they are
+     * preserved across `updateSettings`.
+     */
+    enableUserDefinedMetaRecording(): void;
+    /**
+     * Suspends tracking of user-defined cell meta properties. While suspended, `setMeta` calls are
+     * treated as declarative writes and de-mark their keys, so they are not preserved across
+     * `updateSettings`. Suspensions nest - each call must be matched by an `enableUserDefinedMetaRecording`
+     * call before recording resumes.
+     */
+    disableUserDefinedMetaRecording(): void;
     /**
      * Updates cell meta object by merging settings with the current state.
      *
@@ -130,6 +145,21 @@ export default class CellMeta {
      * @returns {object[]}
      */
     getMetasAtRow(physicalRow: number): Record<string, unknown>[];
+    /**
+     * Returns a flat snapshot of all cell meta properties that were set imperatively through
+     * `setMeta` (tracked in each cell's `_userDefinedMetaProps`). The coordinates are read from the
+     * map keys (physical indexes), not from the meta object's `row`/`col` properties, which are only
+     * populated on `getCellMeta` and become stale after row or column shifts. Used to preserve
+     * user-defined meta across a cache clear during `updateSettings`.
+     *
+     * @returns {{physicalRow: number, physicalColumn: number, key: string, value: *}[]}
+     */
+    getUserDefinedMetas(): {
+        physicalRow: number;
+        physicalColumn: number;
+        key: string;
+        value: unknown;
+    }[];
     /**
      * Clears all saved cell meta objects.
      */

package/dataMap/metaManager/metaLayers/cellMeta.js

@@ -13,13 +13,79 @@ const _lazyFactoryMap = /*#__PURE__*/ _interop_require_default(require("../lazyF
 const _object = require("../../../helpers/object");
 const _mixed = require("../../../helpers/mixed");
 const _number = require("../../../helpers/number");
+function _check_private_redeclaration(obj, privateCollection) {
+    if (privateCollection.has(obj)) {
+        throw new TypeError("Cannot initialize the same private elements twice on an object");
+    }
+}
+function _class_apply_descriptor_get(receiver, descriptor) {
+    if (descriptor.get) {
+        return descriptor.get.call(receiver);
+    }
+    return descriptor.value;
+}
+function _class_apply_descriptor_set(receiver, descriptor, value) {
+    if (descriptor.set) {
+        descriptor.set.call(receiver, value);
+    } else {
+        if (!descriptor.writable) {
+            throw new TypeError("attempted to set read only private field");
+        }
+        descriptor.value = value;
+    }
+}
+function _class_extract_field_descriptor(receiver, privateMap, action) {
+    if (!privateMap.has(receiver)) {
+        throw new TypeError("attempted to " + action + " private field on non-instance");
+    }
+    return privateMap.get(receiver);
+}
+function _class_private_field_get(receiver, privateMap) {
+    var descriptor = _class_extract_field_descriptor(receiver, privateMap, "get");
+    return _class_apply_descriptor_get(receiver, descriptor);
+}
+function _class_private_field_init(obj, privateMap, value) {
+    _check_private_redeclaration(obj, privateMap);
+    privateMap.set(obj, value);
+}
+function _class_private_field_set(receiver, privateMap, value) {
+    var descriptor = _class_extract_field_descriptor(receiver, privateMap, "set");
+    _class_apply_descriptor_set(receiver, descriptor, value);
+    return value;
+}
 function _interop_require_default(obj) {
     return obj && obj.__esModule ? obj : {
         default: obj
     };
 }
+var /**
+   * Counts how many times user-defined meta recording has been suspended without a matching
+   * resume. Recording is active only when the count is `0`. A counter (rather than a boolean) keeps
+   * nested suspend/resume scopes correct - for example, when a re-entrant `updateSettings` runs from
+   * a `setCellMeta` hook while the outer `cell` option loop is still applying declarative writes.
+   *
+   * @type {number}
+   */ _userDefinedMetaRecordingSuspendCount = /*#__PURE__*/ new WeakMap();
 class CellMeta {
     /**
+   * Resumes tracking of user-defined cell meta properties by closing one suspension scope opened by
+   * `disableUserDefinedMetaRecording`. Recording becomes active again only once every suspension has
+   * been closed. Subsequent `setMeta` calls then mark their keys as user-defined, so they are
+   * preserved across `updateSettings`.
+   */ enableUserDefinedMetaRecording() {
+        if (_class_private_field_get(this, _userDefinedMetaRecordingSuspendCount) > 0) {
+            _class_private_field_set(this, _userDefinedMetaRecordingSuspendCount, _class_private_field_get(this, _userDefinedMetaRecordingSuspendCount) - 1);
+        }
+    }
+    /**
+   * Suspends tracking of user-defined cell meta properties. While suspended, `setMeta` calls are
+   * treated as declarative writes and de-mark their keys, so they are not preserved across
+   * `updateSettings`. Suspensions nest - each call must be matched by an `enableUserDefinedMetaRecording`
+   * call before recording resumes.
+   */ disableUserDefinedMetaRecording() {
+        _class_private_field_set(this, _userDefinedMetaRecordingSuspendCount, _class_private_field_get(this, _userDefinedMetaRecordingSuspendCount) + 1);
+    }
+    /**
    * Updates cell meta object by merging settings with the current state.
    *
    * @param {number} physicalRow The physical row index which points what cell meta object is updated.
@@ -86,6 +152,14 @@ class CellMeta {
         const cellMeta = this.metas.obtain(physicalRow).obtain(physicalColumn);
         cellMeta._automaticallyAssignedMetaProps?.delete(key);
         cellMeta[key] = value;
+        if (_class_private_field_get(this, _userDefinedMetaRecordingSuspendCount) === 0) {
+            if (cellMeta._userDefinedMetaProps === undefined) {
+                cellMeta._userDefinedMetaProps = new Set();
+            }
+            cellMeta._userDefinedMetaProps.add(key);
+        } else {
+            cellMeta._userDefinedMetaProps?.delete(key);
+        }
     }
     /**
    * Removes a property defined by the "key" argument from the cell meta object.
@@ -96,6 +170,7 @@ class CellMeta {
    */ removeMeta(physicalRow, physicalColumn, key) {
         const cellMeta = this.metas.obtain(physicalRow).obtain(physicalColumn);
         delete cellMeta[key];
+        cellMeta._userDefinedMetaProps?.delete(key);
     }
     /**
    * Returns all cell meta objects that were created during the Handsontable operation. As cell meta
@@ -130,6 +205,36 @@ class CellMeta {
         return Array.from(rowsMeta.get(physicalRow)).sort(([a], [b])=>a - b).map(([, meta])=>meta);
     }
     /**
+   * Returns a flat snapshot of all cell meta properties that were set imperatively through
+   * `setMeta` (tracked in each cell's `_userDefinedMetaProps`). The coordinates are read from the
+   * map keys (physical indexes), not from the meta object's `row`/`col` properties, which are only
+   * populated on `getCellMeta` and become stale after row or column shifts. Used to preserve
+   * user-defined meta across a cache clear during `updateSettings`.
+   *
+   * @returns {{physicalRow: number, physicalColumn: number, key: string, value: *}[]}
+   */ getUserDefinedMetas() {
+        const result = [];
+        for (const [physicalRow, rowMap] of this.metas){
+            for (const [physicalColumn, meta] of rowMap){
+                const userDefinedProps = meta._userDefinedMetaProps;
+                if (userDefinedProps === undefined) {
+                    continue; // eslint-disable-line no-continue
+                }
+                userDefinedProps.forEach((key)=>{
+                    if ((0, _object.hasOwnProperty)(meta, key)) {
+                        result.push({
+                            physicalRow,
+                            physicalColumn,
+                            key,
+                            value: meta[key]
+                        });
+                    }
+                });
+            }
+        }
+        return result;
+    }
+    /**
    * Clears all saved cell meta objects.
    */ clearCache() {
         this.metas.clear();
@@ -155,6 +260,10 @@ class CellMeta {
     /**
    * Initializes the cell meta layer with a reference to the ColumnMeta layer used as the prototype source for new cell meta objects.
    */ constructor(columnMeta){
+        _class_private_field_init(this, _userDefinedMetaRecordingSuspendCount, {
+            writable: true,
+            value: void 0
+        });
         /**
    * Holder for cell meta objects, organized as a grid of LazyFactoryMap of LazyFactoryMaps.
    * The access to the cell meta object is done through access to the row defined by the physical
@@ -162,6 +271,7 @@ class CellMeta {
    *
    * @type {LazyFactoryMap<number, LazyFactoryMap<number, object>>}
    */ this.metas = new _lazyFactoryMap.default(()=>this._createRow());
+        _class_private_field_set(this, _userDefinedMetaRecordingSuspendCount, 0);
         this.columnMeta = columnMeta;
     }
 }

package/dataMap/metaManager/metaLayers/cellMeta.mjs

@@ -1,10 +1,76 @@
+function _check_private_redeclaration(obj, privateCollection) {
+    if (privateCollection.has(obj)) {
+        throw new TypeError("Cannot initialize the same private elements twice on an object");
+    }
+}
+function _class_apply_descriptor_get(receiver, descriptor) {
+    if (descriptor.get) {
+        return descriptor.get.call(receiver);
+    }
+    return descriptor.value;
+}
+function _class_apply_descriptor_set(receiver, descriptor, value) {
+    if (descriptor.set) {
+        descriptor.set.call(receiver, value);
+    } else {
+        if (!descriptor.writable) {
+            throw new TypeError("attempted to set read only private field");
+        }
+        descriptor.value = value;
+    }
+}
+function _class_extract_field_descriptor(receiver, privateMap, action) {
+    if (!privateMap.has(receiver)) {
+        throw new TypeError("attempted to " + action + " private field on non-instance");
+    }
+    return privateMap.get(receiver);
+}
+function _class_private_field_get(receiver, privateMap) {
+    var descriptor = _class_extract_field_descriptor(receiver, privateMap, "get");
+    return _class_apply_descriptor_get(receiver, descriptor);
+}
+function _class_private_field_init(obj, privateMap, value) {
+    _check_private_redeclaration(obj, privateMap);
+    privateMap.set(obj, value);
+}
+function _class_private_field_set(receiver, privateMap, value) {
+    var descriptor = _class_extract_field_descriptor(receiver, privateMap, "set");
+    _class_apply_descriptor_set(receiver, descriptor, value);
+    return value;
+}
 import { extendByMetaType, assert } from '../utils.mjs';
 import LazyFactoryMap from '../lazyFactoryMap.mjs';
-import { extend } from '../../../helpers/object.mjs';
+import { extend, hasOwnProperty } from '../../../helpers/object.mjs';
 import { isDefined } from '../../../helpers/mixed.mjs';
 import { isUnsignedNumber } from '../../../helpers/number.mjs';
+var /**
+   * Counts how many times user-defined meta recording has been suspended without a matching
+   * resume. Recording is active only when the count is `0`. A counter (rather than a boolean) keeps
+   * nested suspend/resume scopes correct - for example, when a re-entrant `updateSettings` runs from
+   * a `setCellMeta` hook while the outer `cell` option loop is still applying declarative writes.
+   *
+   * @type {number}
+   */ _userDefinedMetaRecordingSuspendCount = /*#__PURE__*/ new WeakMap();
 class CellMeta {
     /**
+   * Resumes tracking of user-defined cell meta properties by closing one suspension scope opened by
+   * `disableUserDefinedMetaRecording`. Recording becomes active again only once every suspension has
+   * been closed. Subsequent `setMeta` calls then mark their keys as user-defined, so they are
+   * preserved across `updateSettings`.
+   */ enableUserDefinedMetaRecording() {
+        if (_class_private_field_get(this, _userDefinedMetaRecordingSuspendCount) > 0) {
+            _class_private_field_set(this, _userDefinedMetaRecordingSuspendCount, _class_private_field_get(this, _userDefinedMetaRecordingSuspendCount) - 1);
+        }
+    }
+    /**
+   * Suspends tracking of user-defined cell meta properties. While suspended, `setMeta` calls are
+   * treated as declarative writes and de-mark their keys, so they are not preserved across
+   * `updateSettings`. Suspensions nest - each call must be matched by an `enableUserDefinedMetaRecording`
+   * call before recording resumes.
+   */ disableUserDefinedMetaRecording() {
+        _class_private_field_set(this, _userDefinedMetaRecordingSuspendCount, _class_private_field_get(this, _userDefinedMetaRecordingSuspendCount) + 1);
+    }
+    /**
    * Updates cell meta object by merging settings with the current state.
    *
    * @param {number} physicalRow The physical row index which points what cell meta object is updated.
@@ -71,6 +137,14 @@ class CellMeta {
         const cellMeta = this.metas.obtain(physicalRow).obtain(physicalColumn);
         cellMeta._automaticallyAssignedMetaProps?.delete(key);
         cellMeta[key] = value;
+        if (_class_private_field_get(this, _userDefinedMetaRecordingSuspendCount) === 0) {
+            if (cellMeta._userDefinedMetaProps === undefined) {
+                cellMeta._userDefinedMetaProps = new Set();
+            }
+            cellMeta._userDefinedMetaProps.add(key);
+        } else {
+            cellMeta._userDefinedMetaProps?.delete(key);
+        }
     }
     /**
    * Removes a property defined by the "key" argument from the cell meta object.
@@ -81,6 +155,7 @@ class CellMeta {
    */ removeMeta(physicalRow, physicalColumn, key) {
         const cellMeta = this.metas.obtain(physicalRow).obtain(physicalColumn);
         delete cellMeta[key];
+        cellMeta._userDefinedMetaProps?.delete(key);
     }
     /**
    * Returns all cell meta objects that were created during the Handsontable operation. As cell meta
@@ -115,6 +190,36 @@ class CellMeta {
         return Array.from(rowsMeta.get(physicalRow)).sort(([a], [b])=>a - b).map(([, meta])=>meta);
     }
     /**
+   * Returns a flat snapshot of all cell meta properties that were set imperatively through
+   * `setMeta` (tracked in each cell's `_userDefinedMetaProps`). The coordinates are read from the
+   * map keys (physical indexes), not from the meta object's `row`/`col` properties, which are only
+   * populated on `getCellMeta` and become stale after row or column shifts. Used to preserve
+   * user-defined meta across a cache clear during `updateSettings`.
+   *
+   * @returns {{physicalRow: number, physicalColumn: number, key: string, value: *}[]}
+   */ getUserDefinedMetas() {
+        const result = [];
+        for (const [physicalRow, rowMap] of this.metas){
+            for (const [physicalColumn, meta] of rowMap){
+                const userDefinedProps = meta._userDefinedMetaProps;
+                if (userDefinedProps === undefined) {
+                    continue; // eslint-disable-line no-continue
+                }
+                userDefinedProps.forEach((key)=>{
+                    if (hasOwnProperty(meta, key)) {
+                        result.push({
+                            physicalRow,
+                            physicalColumn,
+                            key,
+                            value: meta[key]
+                        });
+                    }
+                });
+            }
+        }
+        return result;
+    }
+    /**
    * Clears all saved cell meta objects.
    */ clearCache() {
         this.metas.clear();
@@ -140,6 +245,10 @@ class CellMeta {
     /**
    * Initializes the cell meta layer with a reference to the ColumnMeta layer used as the prototype source for new cell meta objects.
    */ constructor(columnMeta){
+        _class_private_field_init(this, _userDefinedMetaRecordingSuspendCount, {
+            writable: true,
+            value: void 0
+        });
         /**
    * Holder for cell meta objects, organized as a grid of LazyFactoryMap of LazyFactoryMaps.
    * The access to the cell meta object is done through access to the row defined by the physical
@@ -147,6 +256,7 @@ class CellMeta {
    *
    * @type {LazyFactoryMap<number, LazyFactoryMap<number, object>>}
    */ this.metas = new LazyFactoryMap(()=>this._createRow());
+        _class_private_field_set(this, _userDefinedMetaRecordingSuspendCount, 0);
         this.columnMeta = columnMeta;
     }
 }

package/dataMap/metaManager/metaSchema.js

@@ -137,6 +137,15 @@ const _default = ()=>{
      * @default undefined
      */ _automaticallyAssignedMetaProps: undefined,
         /**
+     * Information on which of the cell meta properties were set imperatively through `setCellMeta`
+     * (for example, by the user or by the context menu). These properties are preserved across
+     * `updateSettings` calls, unlike the properties applied from the declarative `cell` option.
+     *
+     * @private
+     * @type {Set}
+     * @default undefined
+     */ _userDefinedMetaProps: undefined,
+        /**
      * The `activeHeaderClassName` option lets you add a CSS class name
      * to every currently-active, currently-selected header (when a whole column or row is selected).
      *

package/dataMap/metaManager/metaSchema.mjs

@@ -127,6 +127,15 @@ import { isObjectEqual } from '../../helpers/object.mjs';
      * @default undefined
      */ _automaticallyAssignedMetaProps: undefined,
         /**
+     * Information on which of the cell meta properties were set imperatively through `setCellMeta`
+     * (for example, by the user or by the context menu). These properties are preserved across
+     * `updateSettings` calls, unlike the properties applied from the declarative `cell` option.
+     *
+     * @private
+     * @type {Set}
+     * @default undefined
+     */ _userDefinedMetaProps: undefined,
+        /**
      * The `activeHeaderClassName` option lets you add a CSS class name
      * to every currently-active, currently-selected header (when a whole column or row is selected).
      *

package/dataMap/sourceDataValidator.d.ts

@@ -1,5 +1,14 @@
+import type { HotInstance } from '../core/types';
+type SourceDataValidatorFn = {
+    (value: unknown, cellMeta: CellMeta, source?: string): boolean;
+    /**
+     * When `true`, the validator's result depends only on the value and column/global-level meta, never
+     * on per-row meta — so a single column-level meta object can validate every row of the column.
+     */
+    rowIndependent?: boolean;
+};
 type CellMeta = Record<string, unknown> & {
-    sourceDataValidator?: (value: unknown, cellMeta: CellMeta, source?: string) => boolean;
+    sourceDataValidator?: SourceDataValidatorFn;
     sourceDataWarningMessage?: string;
     allowInvalid?: boolean;
     row?: number;
@@ -7,10 +16,24 @@ type CellMeta = Record<string, unknown> & {
 };
 /**
  * Runs source-data validator for a single cell.
+ *
+ * @param {unknown} value The value to validate.
+ * @param {object} cellMeta The cell meta object.
+ * @param {string} [source] The source identifier of the operation.
+ * @returns {boolean} `true` when the value is valid (or no validator is configured).
  */
 export declare function runSourceDataValidator(value: unknown, cellMeta: CellMeta, source?: string): boolean;
 /**
  * Runs source-data validators for all cells and emits one aggregated warning per cell type.
+ *
+ * For the common case (no `cells` function, no `cell` array, no `before`/`afterGetCellMeta` hooks, no
+ * imperatively-set cell meta, and only row-independent built-in source validators such as `date`/`time`),
+ * validation reuses one column-level meta per column — avoiding the O(rows*cols) cell-meta
+ * materialization that otherwise retains a meta object for every cell at load.
+ *
+ * @param {HotInstance} hotInstance The Handsontable instance.
+ * @param {string} [source] The source identifier of the operation.
+ * @returns {void}
  */
-export declare function runSourceDataValidators(hotInstance: Record<string, unknown>, source?: string): void;
+export declare function runSourceDataValidators(hotInstance: HotInstance, source?: string): void;
 export {};