handsontable 18.0.0 → 18.1.0-rc7

package/dataMap/metaManager/mods/dynamicCellMeta.d.ts

@@ -1,4 +1,6 @@
 import type { default as MetaManagerInstance } from '..';
+import type { HotInstance } from '../../../core/types';
+import type { CellProperties } from '../../../settings';
 /**
  * @class DynamicCellMetaMod
  *
@@ -15,12 +17,7 @@ import type { default as MetaManagerInstance } from '..';
  * the logic is triggered only once per one Handsontable slow render cycle.
  */
 type MetaManagerWithHot = MetaManagerInstance & {
-    hot: {
-        colToProp: (column: number) => string | number;
-        runHooks: (...args: unknown[]) => unknown;
-        [key: string]: unknown;
-    };
-    addLocalHook: (hookName: string, callback: (...args: unknown[]) => void) => void;
+    hot: HotInstance;
     updateCellMeta: (...args: unknown[]) => void;
     [key: string]: unknown;
 };
@@ -29,16 +26,22 @@ type MetaManagerWithHot = MetaManagerInstance & {
  * memoizing results per render cycle to avoid redundant work.
  */
 export declare class DynamicCellMetaMod {
+    #private;
     /**
      * @type {MetaManager}
      */
     metaManager: MetaManagerWithHot;
     /**
-     * @type {Map}
+     * Per-render-cycle memo of cells already extended by `extendCellMeta`, keyed by physical row to a
+     * set of physical columns.
+     *
+     * @type {Map<number, Set<number>>}
      */
-    metaSyncMemo: Map<any, any>;
+    metaSyncMemo: Map<number, Set<number>>;
     /**
-     * Initializes the modifier, registers the `afterGetCellMeta` local hook, and subscribes to `beforeRender` to clear the memo on full renders.
+     * Initializes the modifier, registers the `afterGetCellMeta` local hook, subscribes to `beforeRender`
+     * to clear the memo on full renders, and subscribes to `afterScrollVertically` and `afterViewRender`
+     * to evict render-derived cell meta for rows that left the viewport.
      */
     constructor(metaManager: MetaManagerWithHot);
     /**
@@ -52,6 +55,17 @@ export declare class DynamicCellMetaMod {
      *
      * @param {object} cellMeta The cell meta object.
      */
-    extendCellMeta(cellMeta: Record<string, unknown>): void;
+    extendCellMeta(cellMeta: CellProperties): void;
+    /**
+     * Extends a transient (not stored) cell meta object by the same user-specific properties as
+     * `extendCellMeta`, with two deliberate differences. The `cells`/`type` settings are applied
+     * directly on the transient object - never through `updateCellMeta`, which would permanently
+     * materialize the cell. And `metaSyncMemo` is neither read nor written: the memo must reflect only
+     * STORED meta objects, or a stored cell created later would skip its extension (a rendering bug),
+     * and memo growth would defeat the point of a retention-free scan.
+     *
+     * @param {object} cellMeta The transient cell meta object.
+     */
+    extendTransientCellMeta(cellMeta: Record<string, unknown>): void;
 }
 export {};

package/dataMap/metaManager/mods/dynamicCellMeta.js

@@ -11,6 +11,112 @@ Object.defineProperty(exports, "DynamicCellMetaMod", {
 const _hooks = require("../../../core/hooks");
 const _object = require("../../../helpers/object");
 const _function = require("../../../helpers/function");
+const _utils = require("../utils");
+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 _class_private_method_get(receiver, privateSet, fn) {
+    if (!privateSet.has(receiver)) {
+        throw new TypeError("attempted to get private field on non-instance");
+    }
+    return fn;
+}
+function _class_private_method_init(obj, privateSet) {
+    _check_private_redeclaration(obj, privateSet);
+    privateSet.add(obj);
+}
+var /**
+   * The lowest visual row index of the meta "keep band" tracked by the previous eviction pass - the
+   * viewport plus a one-viewport hysteresis margin. The next pass evicts the visual rows that fall
+   * between this band and the new one (the rows that just scrolled out), so the work is proportional
+   * to the scroll distance, not the number of materialized rows.
+   *
+   * @type {number}
+   */ _keepBandStart = /*#__PURE__*/ new WeakMap(), /**
+   * The highest visual row index of the meta "keep band". See `#keepBandStart`.
+   *
+   * @type {number}
+   */ _keepBandEnd = /*#__PURE__*/ new WeakMap(), /**
+   * Whether a keep band has been recorded yet. A separate flag (rather than a sentinel value) is
+   * required because a valid `#keepBandStart` is often negative near the top of the grid (the
+   * viewport start minus the hysteresis margin), so no numeric sentinel is safe.
+   *
+   * @type {boolean}
+   */ _keepBandInitialized = /*#__PURE__*/ new WeakMap(), /**
+   * Runs the dynamic-extension sequence on a cell meta object: resolves `prop`, fires
+   * `beforeGetCellMeta`, evaluates the `cells` function and the `type` value it (or the hook)
+   * produced, hands the resulting settings to the caller-provided applier, and fires
+   * `afterGetCellMeta`. The applier is the only step that differs between the stored path
+   * (persist through `updateCellMeta`) and the transient path (extend the throwaway object).
+   *
+   * @param {object} cellMeta The cell meta object to extend.
+   * @param {Function} applyCellSettings Receives the resolved `cells`/`type` settings object.
+   */ _runMetaExtension = /*#__PURE__*/ new WeakSet(), /**
+   * Evicts render-derived cell meta for rows that scrolled out of the viewport, bounding meta
+   * retention to roughly the visible rows plus a one-viewport hysteresis margin on each side ("keep
+   * band"). Only the visual rows that fall between the previous keep band and the new one are visited
+   * (the rows that just left), so the cost is proportional to the scroll distance, NOT to the number
+   * of materialized rows - a grid with many `setCellMeta`/`cell`-option rows pays nothing extra here.
+   * The band is tracked in visual space and never reset, so a full render that does not move the
+   * viewport produces an empty diff (no work). Row-axis only - the vertical axis is the large one;
+   * horizontal scrolling does not evict.
+   */ _evictMetaOutsideViewport = /*#__PURE__*/ new WeakSet(), /**
+   * Evicts render-derived cell meta for an inclusive range of visual rows. Each visual row is
+   * translated to its physical index (cell meta is keyed physically) reading the mapping fresh, so a
+   * sort or move that happened since the band was recorded resolves correctly. Only the active
+   * editor's row is skipped - the selection highlight (focus) cell, where the prepared or active
+   * editor holds the cell meta object by reference (see `BaseEditor#cellProperties`). The remaining
+   * rows of a wide selection (whole column, multi-row) must stay evictable, or they would pin their
+   * cell meta and defeat the viewport bound.
+   *
+   * @param {number} fromVisualRow The first visual row index in the range (inclusive).
+   * @param {number} toVisualRow The last visual row index in the range (inclusive).
+   */ _evictVisualRowRange = /*#__PURE__*/ new WeakSet(), /**
+   * Evicts the render-derived cell meta of a single physical row and prunes the matching
+   * `metaSyncMemo` entries for ONLY the columns that were actually evicted. A re-minted cell then
+   * re-runs its dynamic extension, while persisted/invalid cells kept on the same row retain their
+   * memo - so they are not needlessly re-extended (which could let a `cells()` result overwrite a
+   * `setCellMeta` value). The whole memo row is dropped once empty, keeping the memo bounded.
+   *
+   * @param {number} physicalRow The physical row index to evict.
+   */ _evictRowAndPruneMemo = /*#__PURE__*/ new WeakSet();
 class DynamicCellMetaMod {
     /**
    * Extends the cell meta object by user-specific properties.
@@ -28,47 +134,165 @@ class DynamicCellMetaMod {
         if (this.metaSyncMemo.get(physicalRow)?.has(physicalColumn)) {
             return;
         }
-        const visualRow = cellMeta.visualRow;
-        const visualCol = cellMeta.visualCol;
-        const hot = this.metaManager.hot;
-        const prop = hot.colToProp(visualCol);
-        cellMeta.prop = prop;
-        hot.runHooks('beforeGetCellMeta', visualRow, visualCol, cellMeta);
-        // extend a `type` value, added or changed in the `beforeGetCellMeta` hook
-        const cellType = (0, _object.hasOwnProperty)(cellMeta, 'type') ? cellMeta.type : null;
-        let cellSettings = (0, _function.isFunction)(cellMeta.cells) ? cellMeta.cells(physicalRow, physicalColumn, prop) : null;
-        if (cellType) {
-            if (cellSettings) {
-                cellSettings.type = cellSettings.type ?? cellType;
-            } else {
-                cellSettings = {
-                    type: cellType
-                };
-            }
-        }
-        if (cellSettings) {
+        _class_private_method_get(this, _runMetaExtension, runMetaExtension).call(this, cellMeta, (cellSettings)=>{
             this.metaManager.updateCellMeta(physicalRow, physicalColumn, cellSettings);
+        });
+        let memoRow = this.metaSyncMemo.get(physicalRow);
+        if (memoRow === undefined) {
+            memoRow = new Set();
+            this.metaSyncMemo.set(physicalRow, memoRow);
         }
-        hot.runHooks('afterGetCellMeta', visualRow, visualCol, cellMeta);
-        if (!this.metaSyncMemo.has(physicalRow)) {
-            this.metaSyncMemo.set(physicalRow, new Set());
-        }
-        this.metaSyncMemo.get(physicalRow).add(physicalColumn);
+        memoRow.add(physicalColumn);
     }
     /**
-   * Initializes the modifier, registers the `afterGetCellMeta` local hook, and subscribes to `beforeRender` to clear the memo on full renders.
+   * Extends a transient (not stored) cell meta object by the same user-specific properties as
+   * `extendCellMeta`, with two deliberate differences. The `cells`/`type` settings are applied
+   * directly on the transient object - never through `updateCellMeta`, which would permanently
+   * materialize the cell. And `metaSyncMemo` is neither read nor written: the memo must reflect only
+   * STORED meta objects, or a stored cell created later would skip its extension (a rendering bug),
+   * and memo growth would defeat the point of a retention-free scan.
+   *
+   * @param {object} cellMeta The transient cell meta object.
+   */ extendTransientCellMeta(cellMeta) {
+        _class_private_method_get(this, _runMetaExtension, runMetaExtension).call(this, cellMeta, (cellSettings)=>{
+            (0, _object.extend)(cellMeta, cellSettings);
+            (0, _utils.extendByMetaType)(cellMeta, cellSettings);
+        });
+    }
+    /**
+   * Initializes the modifier, registers the `afterGetCellMeta` local hook, subscribes to `beforeRender`
+   * to clear the memo on full renders, and subscribes to `afterScrollVertically` and `afterViewRender`
+   * to evict render-derived cell meta for rows that left the viewport.
    */ constructor(metaManager){
+        _class_private_method_init(this, _runMetaExtension);
+        _class_private_method_init(this, _evictMetaOutsideViewport);
+        _class_private_method_init(this, _evictVisualRowRange);
+        _class_private_method_init(this, _evictRowAndPruneMemo);
+        _class_private_field_init(this, _keepBandStart, {
+            writable: true,
+            value: void 0
+        });
+        _class_private_field_init(this, _keepBandEnd, {
+            writable: true,
+            value: void 0
+        });
+        _class_private_field_init(this, _keepBandInitialized, {
+            writable: true,
+            value: void 0
+        });
         /**
-   * @type {Map}
+   * Per-render-cycle memo of cells already extended by `extendCellMeta`, keyed by physical row to a
+   * set of physical columns.
+   *
+   * @type {Map<number, Set<number>>}
    */ this.metaSyncMemo = new Map();
+        _class_private_field_set(this, _keepBandStart, 0);
+        _class_private_field_set(this, _keepBandEnd, 0);
+        _class_private_field_set(this, _keepBandInitialized, false);
         this.metaManager = metaManager;
-        metaManager.addLocalHook('afterGetCellMeta', (...args)=>{
-            this.extendCellMeta(args[0]);
+        metaManager.addLocalHook('afterGetCellMeta', (cellMeta)=>{
+            this.extendCellMeta(cellMeta);
+        });
+        metaManager.addLocalHook('extendTransientCellMeta', (cellMeta)=>{
+            this.extendTransientCellMeta(cellMeta);
         });
+        // These hooks are registered through `Hooks.getSingleton().add(..., hot)` rather than
+        // `hot.addHook(...)` on purpose: this modifier is constructed from the `MetaManager`
+        // constructor, which runs early in `Core` setup - before `hot.addHook` is defined. The
+        // singleton form binds the callback to the `hot` instance and is cleaned up on `hot.destroy()`
+        // exactly like `hot.addHook` would be, so this is equivalent once the instance is ready.
         _hooks.Hooks.getSingleton().add('beforeRender', (forceFullRender)=>{
             if (forceFullRender) {
                 this.metaSyncMemo.clear();
             }
         }, this.metaManager.hot);
+        const evict = ()=>_class_private_method_get(this, _evictMetaOutsideViewport, evictMetaOutsideViewport).call(this);
+        // Scrolling materializes cell meta for newly visible rows; evict the rows that left the viewport.
+        _hooks.Hooks.getSingleton().add('afterScrollVertically', evict, this.metaManager.hot);
+        // A full render (for example after a sort or filter) can leave behind meta for rows that are no
+        // longer in view; run the same pass so retention stays bounded regardless of what triggered it.
+        _hooks.Hooks.getSingleton().add('afterViewRender', evict, this.metaManager.hot);
+    }
+}
+function runMetaExtension(cellMeta, applyCellSettings) {
+    const physicalRow = cellMeta.row;
+    const physicalColumn = cellMeta.col;
+    const visualRow = cellMeta.visualRow;
+    const visualCol = cellMeta.visualCol;
+    const hot = this.metaManager.hot;
+    const prop = hot.colToProp(visualCol);
+    cellMeta.prop = prop;
+    hot.runHooks('beforeGetCellMeta', visualRow, visualCol, cellMeta);
+    // extend a `type` value, added or changed in the `beforeGetCellMeta` hook
+    const cellType = (0, _object.hasOwnProperty)(cellMeta, 'type') ? cellMeta.type : null;
+    let cellSettings = (0, _function.isFunction)(cellMeta.cells) ? cellMeta.cells(physicalRow, physicalColumn, prop) : null;
+    if (cellType) {
+        if (cellSettings) {
+            cellSettings.type = cellSettings.type ?? cellType;
+        } else {
+            cellSettings = {
+                type: cellType
+            };
+        }
+    }
+    if (cellSettings) {
+        applyCellSettings(cellSettings);
+    }
+    hot.runHooks('afterGetCellMeta', visualRow, visualCol, cellMeta);
+}
+function evictMetaOutsideViewport() {
+    const hot = this.metaManager.hot;
+    const firstVisibleRow = hot.getFirstRenderedVisibleRow();
+    const lastVisibleRow = hot.getLastRenderedVisibleRow();
+    // The render-range getters are typed `number` but return `null` when the viewport is not yet
+    // calculated; `Number.isInteger` rejects that case without a type-level null comparison.
+    if (!Number.isInteger(firstVisibleRow) || !Number.isInteger(lastVisibleRow) || lastVisibleRow < firstVisibleRow) {
+        return;
+    }
+    const viewportSize = lastVisibleRow - firstVisibleRow + 1;
+    const keepStart = firstVisibleRow - viewportSize;
+    const keepEnd = lastVisibleRow + viewportSize;
+    const previousStart = _class_private_field_get(this, _keepBandStart);
+    const previousEnd = _class_private_field_get(this, _keepBandEnd);
+    if (_class_private_field_get(this, _keepBandInitialized)) {
+        // Previously-kept rows now above the band (visual index below the new keep-band start).
+        _class_private_method_get(this, _evictVisualRowRange, evictVisualRowRange).call(this, previousStart, Math.min(previousEnd, keepStart - 1));
+        // Previously-kept rows now below the band (visual index above the new keep-band end).
+        _class_private_method_get(this, _evictVisualRowRange, evictVisualRowRange).call(this, Math.max(previousStart, keepEnd + 1), previousEnd);
+    }
+    _class_private_field_set(this, _keepBandStart, keepStart);
+    _class_private_field_set(this, _keepBandEnd, keepEnd);
+    _class_private_field_set(this, _keepBandInitialized, true);
+}
+function evictVisualRowRange(fromVisualRow, toVisualRow) {
+    if (fromVisualRow > toVisualRow) {
+        return;
+    }
+    const hot = this.metaManager.hot;
+    const selectedRange = hot.getSelectedRangeLast();
+    const activeEditorRow = selectedRange ? selectedRange.highlight.row : null;
+    for(let visualRow = fromVisualRow; visualRow <= toVisualRow; visualRow++){
+        const physicalRow = hot.toPhysicalRow(visualRow);
+        // `toPhysicalRow` is typed `number` but returns `null` for an out-of-range visual row (for
+        // example after trimming); `Number.isInteger` filters that without a type-level null compare.
+        if (visualRow !== activeEditorRow && Number.isInteger(physicalRow)) {
+            _class_private_method_get(this, _evictRowAndPruneMemo, evictRowAndPruneMemo).call(this, physicalRow);
+        }
+    }
+}
+function evictRowAndPruneMemo(physicalRow) {
+    const evictedColumns = this.metaManager.cellMeta.evictRow(physicalRow);
+    if (evictedColumns.length === 0) {
+        return;
+    }
+    const memoRow = this.metaSyncMemo.get(physicalRow);
+    if (memoRow === undefined) {
+        return;
+    }
+    for(let i = 0; i < evictedColumns.length; i++){
+        memoRow.delete(evictedColumns[i]);
+    }
+    if (memoRow.size === 0) {
+        this.metaSyncMemo.delete(physicalRow);
     }
 }