handsontable 18.0.0 → 18.1.0-rc1

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

@@ -1,5 +1,6 @@
 import LazyFactoryMap from '../lazyFactoryMap';
 import type ColumnMeta from './columnMeta';
+import type { CellProperties } from '../../../settings';
 /**
  * @class CellMeta
  *
@@ -44,7 +45,7 @@ export default class CellMeta {
      *
      * @type {LazyFactoryMap<number, LazyFactoryMap<number, object>>}
      */
-    metas: LazyFactoryMap<LazyFactoryMap<Record<string, unknown>>>;
+    metas: LazyFactoryMap<LazyFactoryMap<CellProperties>>;
     /**
      * Initializes the cell meta layer with a reference to the ColumnMeta layer used as the prototype source for new cell meta objects.
      */
@@ -75,16 +76,18 @@ export default class CellMeta {
      * Creates one or more rows at specific position.
      *
      * @param {number} physicalRow The physical row index which points from what position the row is added.
+     *   Pass `null` to append at the end.
      * @param {number} amount An amount of rows to add.
      */
-    createRow(physicalRow: number, amount: number): void;
+    createRow(physicalRow: number | null, amount: number): void;
     /**
      * Creates one or more columns at specific position.
      *
      * @param {number} physicalColumn The physical column index which points from what position the column is added.
+     *   Pass `null` to append at the end.
      * @param {number} amount An amount of columns to add.
      */
-    createColumn(physicalColumn: number, amount: number): void;
+    createColumn(physicalColumn: number | null, amount: number): void;
     /**
      * Removes one or more rows from the collection.
      *
@@ -107,11 +110,41 @@ export default class CellMeta {
      * @param {string} [key] If the key exists its value will be returned, otherwise the whole cell meta object.
      * @returns {object}
      */
-    getMeta(physicalRow: number, physicalColumn: number): Record<string, unknown>;
+    getMeta(physicalRow: number, physicalColumn: number): CellProperties;
     /**
      * Returns the value of the specified property key from the cell meta object at the given physical row and column.
      */
     getMeta(physicalRow: number, physicalColumn: number, key: string): unknown;
+    /**
+     * Checks whether a cell meta object has already been created for the given coordinates, without
+     * creating one. Used to decide whether a cell carries its own (user/declarative) meta that must be
+     * reused, as opposed to deriving a fresh object from the column layer.
+     *
+     * @param {number} physicalRow The physical row index.
+     * @param {number} physicalColumn The physical column index.
+     * @returns {boolean}
+     */
+    hasMeta(physicalRow: number, physicalColumn: number): boolean;
+    /**
+     * Returns the stored cell meta object for the given coordinates, or `undefined` when the cell
+     * has no materialized meta. Unlike `getMeta`, it never creates row or cell objects, so it is
+     * safe for bulk scans; unlike `hasMeta` followed by `getMeta`, it resolves in two map lookups
+     * instead of five, which matters on the per-cell read path.
+     *
+     * @param {number} physicalRow The physical row index.
+     * @param {number} physicalColumn The physical column index.
+     * @returns {object|undefined}
+     */
+    getMetaIfExists(physicalRow: number, physicalColumn: number): CellProperties | undefined;
+    /**
+     * Creates a cell meta object inheriting from the column layer without storing it in the map. The
+     * returned object is transient (eligible for garbage collection) and carries no per-cell overrides,
+     * so it must only be used for reads that do not need persisted per-cell meta.
+     *
+     * @param {number} physicalColumn The physical column index.
+     * @returns {object}
+     */
+    createTransientMeta(physicalColumn: number): CellProperties;
     /**
      * Sets settings object for this layer defined by "key" property.
      *
@@ -136,7 +169,7 @@ export default class CellMeta {
      *
      * @returns {object[]}
      */
-    getMetas(): Record<string, unknown>[];
+    getMetas(): CellProperties[];
     /**
      * Returns all cell meta objects that were created during the Handsontable operation but for
      * specific row index.
@@ -144,7 +177,7 @@ export default class CellMeta {
      * @param {number} physicalRow The physical row index.
      * @returns {object[]}
      */
-    getMetasAtRow(physicalRow: number): Record<string, unknown>[];
+    getMetasAtRow(physicalRow: number): CellProperties[];
     /**
      * 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
@@ -160,6 +193,20 @@ export default class CellMeta {
         key: string;
         value: unknown;
     }[];
+    /**
+     * Releases render-derived cell meta objects for a single physical row, freeing memory for rows
+     * scrolled out of the viewport. A cell is evicted only when it is purely render-derived: it carries
+     * no persisted meta props (nothing set through `setMeta`/`setCellMeta`, whether imperatively or via
+     * the declarative `cell` option) and is not flagged invalid (`valid === false`, written directly by
+     * the validation flow and not rebuilt on render). Such cells are pure cascade/`cells`/`type`
+     * derivations and are re-created lazily on the next `getMeta` call. Cells with persisted props or a
+     * failed validation result are kept so those values survive scrolling. When the whole row is purely
+     * render-derived, its inner map is dropped as well.
+     *
+     * @param {number} physicalRow The physical row index to evict.
+     * @returns {number[]} The physical column indexes whose meta was evicted (empty when nothing was).
+     */
+    evictRow(physicalRow: number): number[];
     /**
      * Clears all saved cell meta objects.
      */
@@ -170,7 +217,7 @@ export default class CellMeta {
      * @private
      * @returns {object}
      */
-    _createRow(): LazyFactoryMap<Record<string, unknown>>;
+    _createRow(): LazyFactoryMap<CellProperties>;
     /**
      * Creates and returns new cell meta object with properties inherited from the column meta layer.
      *
@@ -178,5 +225,5 @@ export default class CellMeta {
      * @param {number} physicalColumn The physical column index.
      * @returns {object}
      */
-    _createMeta(physicalColumn: number): Record<string, unknown>;
+    _createMeta(physicalColumn: number): CellProperties;
 }

package/dataMap/metaManager/metaLayers/cellMeta.js

@@ -19,15 +19,12 @@ function _check_private_redeclaration(obj, privateCollection) {
     }
 }
 function _class_apply_descriptor_get(receiver, descriptor) {
-    if (descriptor.get) {
-        return descriptor.get.call(receiver);
-    }
+    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.set) descriptor.set.call(receiver, value);
+    else {
         if (!descriptor.writable) {
             throw new TypeError("attempted to set read only private field");
         }
@@ -35,9 +32,7 @@ function _class_apply_descriptor_set(receiver, descriptor, value) {
     }
 }
 function _class_extract_field_descriptor(receiver, privateMap, action) {
-    if (!privateMap.has(receiver)) {
-        throw new TypeError("attempted to " + action + " private field on non-instance");
-    }
+    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) {
@@ -100,6 +95,7 @@ class CellMeta {
    * Creates one or more rows at specific position.
    *
    * @param {number} physicalRow The physical row index which points from what position the row is added.
+   *   Pass `null` to append at the end.
    * @param {number} amount An amount of rows to add.
    */ createRow(physicalRow, amount) {
         this.metas.insert(physicalRow, amount);
@@ -108,10 +104,14 @@ class CellMeta {
    * Creates one or more columns at specific position.
    *
    * @param {number} physicalColumn The physical column index which points from what position the column is added.
+   *   Pass `null` to append at the end.
    * @param {number} amount An amount of columns to add.
    */ createColumn(physicalColumn, amount) {
-        for(let i = 0; i < this.metas.size(); i++){
-            this.metas.obtain(i).insert(physicalColumn, amount);
+        // Iterate only materialized rows. Evicted/unmaterialized rows hold no cell meta to shift, so
+        // re-creating them here (the previous `obtain(i)` over `size()`) would needlessly re-inflate
+        // memory and add O(total rows) work after a viewport eviction.
+        for (const [, rowMeta] of this.metas){
+            rowMeta.insert(physicalColumn, amount);
         }
     }
     /**
@@ -128,8 +128,10 @@ class CellMeta {
    * @param {number} physicalColumn The physical column index which points from what position the column is removed.
    * @param {number} amount An amount of columns to remove.
    */ removeColumn(physicalColumn, amount) {
-        for(let i = 0; i < this.metas.size(); i++){
-            this.metas.obtain(i).remove(physicalColumn, amount);
+        // Iterate only materialized rows (see `createColumn`); evicted/unmaterialized rows have no cell
+        // meta to shift, so skipping them avoids re-creating them after a viewport eviction.
+        for (const [, rowMeta] of this.metas){
+            rowMeta.remove(physicalColumn, amount);
         }
     }
     /**
@@ -142,6 +144,39 @@ class CellMeta {
         return cellMeta[key];
     }
     /**
+   * Checks whether a cell meta object has already been created for the given coordinates, without
+   * creating one. Used to decide whether a cell carries its own (user/declarative) meta that must be
+   * reused, as opposed to deriving a fresh object from the column layer.
+   *
+   * @param {number} physicalRow The physical row index.
+   * @param {number} physicalColumn The physical column index.
+   * @returns {boolean}
+   */ hasMeta(physicalRow, physicalColumn) {
+        return this.metas.has(physicalRow) && this.metas.obtain(physicalRow).has(physicalColumn);
+    }
+    /**
+   * Returns the stored cell meta object for the given coordinates, or `undefined` when the cell
+   * has no materialized meta. Unlike `getMeta`, it never creates row or cell objects, so it is
+   * safe for bulk scans; unlike `hasMeta` followed by `getMeta`, it resolves in two map lookups
+   * instead of five, which matters on the per-cell read path.
+   *
+   * @param {number} physicalRow The physical row index.
+   * @param {number} physicalColumn The physical column index.
+   * @returns {object|undefined}
+   */ getMetaIfExists(physicalRow, physicalColumn) {
+        return this.metas.getIfExists(physicalRow)?.getIfExists(physicalColumn);
+    }
+    /**
+   * Creates a cell meta object inheriting from the column layer without storing it in the map. The
+   * returned object is transient (eligible for garbage collection) and carries no per-cell overrides,
+   * so it must only be used for reads that do not need persisted per-cell meta.
+   *
+   * @param {number} physicalColumn The physical column index.
+   * @returns {object}
+   */ createTransientMeta(physicalColumn) {
+        return this._createMeta(physicalColumn);
+    }
+    /**
    * Sets settings object for this layer defined by "key" property.
    *
    * @param {number} physicalRow The physical row index.
@@ -152,6 +187,12 @@ class CellMeta {
         const cellMeta = this.metas.obtain(physicalRow).obtain(physicalColumn);
         cellMeta._automaticallyAssignedMetaProps?.delete(key);
         cellMeta[key] = value;
+        // Every `setMeta` write - imperative or declarative (`cell` option) - is non-reconstructable by
+        // `getCellMeta`, so record it; the viewport-eviction pass keeps cells whose set is non-empty.
+        if (cellMeta._persistedMetaProps === undefined) {
+            cellMeta._persistedMetaProps = new Set();
+        }
+        cellMeta._persistedMetaProps.add(key);
         if (_class_private_field_get(this, _userDefinedMetaRecordingSuspendCount) === 0) {
             if (cellMeta._userDefinedMetaProps === undefined) {
                 cellMeta._userDefinedMetaProps = new Set();
@@ -168,9 +209,16 @@ class CellMeta {
    * @param {number} physicalColumn The physical column index.
    * @param {string} key The property name to remove.
    */ removeMeta(physicalRow, physicalColumn, key) {
-        const cellMeta = this.metas.obtain(physicalRow).obtain(physicalColumn);
+        // Peek instead of `obtain`: removing a key from a cell with no materialized meta is a no-op,
+        // and materializing one object per visited cell here would retain memory the viewport
+        // eviction cannot sweep (bulk callers remove keys across whole regions).
+        const cellMeta = this.metas.getIfExists(physicalRow)?.getIfExists(physicalColumn);
+        if (cellMeta === undefined) {
+            return;
+        }
         delete cellMeta[key];
         cellMeta._userDefinedMetaProps?.delete(key);
+        cellMeta._persistedMetaProps?.delete(key);
     }
     /**
    * Returns all cell meta objects that were created during the Handsontable operation. As cell meta
@@ -198,11 +246,11 @@ class CellMeta {
    * @returns {object[]}
    */ getMetasAtRow(physicalRow) {
         (0, _utils.assert)(()=>(0, _number.isUnsignedNumber)(physicalRow), 'Expecting an unsigned number.');
-        const rowsMeta = new Map(this.metas);
-        if (!rowsMeta.has(physicalRow)) {
+        const rowMeta = this.metas.getIfExists(physicalRow);
+        if (rowMeta === undefined) {
             return [];
         }
-        return Array.from(rowsMeta.get(physicalRow)).sort(([a], [b])=>a - b).map(([, meta])=>meta);
+        return Array.from(rowMeta).sort(([a], [b])=>a - b).map(([, meta])=>meta);
     }
     /**
    * Returns a flat snapshot of all cell meta properties that were set imperatively through
@@ -235,6 +283,49 @@ class CellMeta {
         return result;
     }
     /**
+   * Releases render-derived cell meta objects for a single physical row, freeing memory for rows
+   * scrolled out of the viewport. A cell is evicted only when it is purely render-derived: it carries
+   * no persisted meta props (nothing set through `setMeta`/`setCellMeta`, whether imperatively or via
+   * the declarative `cell` option) and is not flagged invalid (`valid === false`, written directly by
+   * the validation flow and not rebuilt on render). Such cells are pure cascade/`cells`/`type`
+   * derivations and are re-created lazily on the next `getMeta` call. Cells with persisted props or a
+   * failed validation result are kept so those values survive scrolling. When the whole row is purely
+   * render-derived, its inner map is dropped as well.
+   *
+   * @param {number} physicalRow The physical row index to evict.
+   * @returns {number[]} The physical column indexes whose meta was evicted (empty when nothing was).
+   */ evictRow(physicalRow) {
+        const rowMap = this.metas.getIfExists(physicalRow);
+        if (rowMap === undefined) {
+            return [];
+        }
+        let hasKeptCell = false;
+        const evictedColumns = [];
+        for (const [physicalColumn, meta] of rowMap){
+            const persistedProps = meta._persistedMetaProps;
+            const hasPersistedProps = persistedProps !== undefined && persistedProps.size > 0;
+            // A failed validation result (`valid === false`) is written directly onto the meta object by
+            // the core validation flow (not through `setMeta`) and is not rebuilt on render, so the cell
+            // must survive eviction or the invalid-cell highlight would disappear after scrolling away.
+            // Only `false` is preserved, not `valid === true`: a passing result has no rendered state and
+            // preserving every validated-valid cell would defeat the memory bound on a fully validated grid.
+            // The trade-off is that `getCellMeta().valid` reads back as `undefined` (not `true`) for an
+            // evicted-and-re-minted valid cell until it is validated again; no core reader distinguishes the
+            // two (all branch on `!== false`).
+            const isInvalid = meta.valid === false;
+            if (hasPersistedProps || isInvalid) {
+                hasKeptCell = true;
+            } else {
+                rowMap.evict(physicalColumn);
+                evictedColumns.push(physicalColumn);
+            }
+        }
+        if (!hasKeptCell) {
+            this.metas.evict(physicalRow);
+        }
+        return evictedColumns;
+    }
+    /**
    * Clears all saved cell meta objects.
    */ clearCache() {
         this.metas.clear();
@@ -254,6 +345,10 @@ class CellMeta {
    * @param {number} physicalColumn The physical column index.
    * @returns {object}
    */ _createMeta(physicalColumn) {
+        // The constructor is produced by `columnFactory` through runtime prototype inheritance, which
+        // TypeScript cannot follow - this single cast is where the meta object type enters the layer.
+        // The prototype chain supplies every grid setting; the coordinate properties are stamped by
+        // `MetaManager` on each read, completing the `CellProperties` shape.
         const ColumnMeta = this.columnMeta.getMetaConstructor(physicalColumn);
         return new ColumnMeta();
     }

package/dataMap/metaManager/metaLayers/cellMeta.mjs

@@ -4,15 +4,12 @@ function _check_private_redeclaration(obj, privateCollection) {
     }
 }
 function _class_apply_descriptor_get(receiver, descriptor) {
-    if (descriptor.get) {
-        return descriptor.get.call(receiver);
-    }
+    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.set) descriptor.set.call(receiver, value);
+    else {
         if (!descriptor.writable) {
             throw new TypeError("attempted to set read only private field");
         }
@@ -20,9 +17,7 @@ function _class_apply_descriptor_set(receiver, descriptor, value) {
     }
 }
 function _class_extract_field_descriptor(receiver, privateMap, action) {
-    if (!privateMap.has(receiver)) {
-        throw new TypeError("attempted to " + action + " private field on non-instance");
-    }
+    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) {
@@ -85,6 +80,7 @@ class CellMeta {
    * Creates one or more rows at specific position.
    *
    * @param {number} physicalRow The physical row index which points from what position the row is added.
+   *   Pass `null` to append at the end.
    * @param {number} amount An amount of rows to add.
    */ createRow(physicalRow, amount) {
         this.metas.insert(physicalRow, amount);
@@ -93,10 +89,14 @@ class CellMeta {
    * Creates one or more columns at specific position.
    *
    * @param {number} physicalColumn The physical column index which points from what position the column is added.
+   *   Pass `null` to append at the end.
    * @param {number} amount An amount of columns to add.
    */ createColumn(physicalColumn, amount) {
-        for(let i = 0; i < this.metas.size(); i++){
-            this.metas.obtain(i).insert(physicalColumn, amount);
+        // Iterate only materialized rows. Evicted/unmaterialized rows hold no cell meta to shift, so
+        // re-creating them here (the previous `obtain(i)` over `size()`) would needlessly re-inflate
+        // memory and add O(total rows) work after a viewport eviction.
+        for (const [, rowMeta] of this.metas){
+            rowMeta.insert(physicalColumn, amount);
         }
     }
     /**
@@ -113,8 +113,10 @@ class CellMeta {
    * @param {number} physicalColumn The physical column index which points from what position the column is removed.
    * @param {number} amount An amount of columns to remove.
    */ removeColumn(physicalColumn, amount) {
-        for(let i = 0; i < this.metas.size(); i++){
-            this.metas.obtain(i).remove(physicalColumn, amount);
+        // Iterate only materialized rows (see `createColumn`); evicted/unmaterialized rows have no cell
+        // meta to shift, so skipping them avoids re-creating them after a viewport eviction.
+        for (const [, rowMeta] of this.metas){
+            rowMeta.remove(physicalColumn, amount);
         }
     }
     /**
@@ -127,6 +129,39 @@ class CellMeta {
         return cellMeta[key];
     }
     /**
+   * Checks whether a cell meta object has already been created for the given coordinates, without
+   * creating one. Used to decide whether a cell carries its own (user/declarative) meta that must be
+   * reused, as opposed to deriving a fresh object from the column layer.
+   *
+   * @param {number} physicalRow The physical row index.
+   * @param {number} physicalColumn The physical column index.
+   * @returns {boolean}
+   */ hasMeta(physicalRow, physicalColumn) {
+        return this.metas.has(physicalRow) && this.metas.obtain(physicalRow).has(physicalColumn);
+    }
+    /**
+   * Returns the stored cell meta object for the given coordinates, or `undefined` when the cell
+   * has no materialized meta. Unlike `getMeta`, it never creates row or cell objects, so it is
+   * safe for bulk scans; unlike `hasMeta` followed by `getMeta`, it resolves in two map lookups
+   * instead of five, which matters on the per-cell read path.
+   *
+   * @param {number} physicalRow The physical row index.
+   * @param {number} physicalColumn The physical column index.
+   * @returns {object|undefined}
+   */ getMetaIfExists(physicalRow, physicalColumn) {
+        return this.metas.getIfExists(physicalRow)?.getIfExists(physicalColumn);
+    }
+    /**
+   * Creates a cell meta object inheriting from the column layer without storing it in the map. The
+   * returned object is transient (eligible for garbage collection) and carries no per-cell overrides,
+   * so it must only be used for reads that do not need persisted per-cell meta.
+   *
+   * @param {number} physicalColumn The physical column index.
+   * @returns {object}
+   */ createTransientMeta(physicalColumn) {
+        return this._createMeta(physicalColumn);
+    }
+    /**
    * Sets settings object for this layer defined by "key" property.
    *
    * @param {number} physicalRow The physical row index.
@@ -137,6 +172,12 @@ class CellMeta {
         const cellMeta = this.metas.obtain(physicalRow).obtain(physicalColumn);
         cellMeta._automaticallyAssignedMetaProps?.delete(key);
         cellMeta[key] = value;
+        // Every `setMeta` write - imperative or declarative (`cell` option) - is non-reconstructable by
+        // `getCellMeta`, so record it; the viewport-eviction pass keeps cells whose set is non-empty.
+        if (cellMeta._persistedMetaProps === undefined) {
+            cellMeta._persistedMetaProps = new Set();
+        }
+        cellMeta._persistedMetaProps.add(key);
         if (_class_private_field_get(this, _userDefinedMetaRecordingSuspendCount) === 0) {
             if (cellMeta._userDefinedMetaProps === undefined) {
                 cellMeta._userDefinedMetaProps = new Set();
@@ -153,9 +194,16 @@ class CellMeta {
    * @param {number} physicalColumn The physical column index.
    * @param {string} key The property name to remove.
    */ removeMeta(physicalRow, physicalColumn, key) {
-        const cellMeta = this.metas.obtain(physicalRow).obtain(physicalColumn);
+        // Peek instead of `obtain`: removing a key from a cell with no materialized meta is a no-op,
+        // and materializing one object per visited cell here would retain memory the viewport
+        // eviction cannot sweep (bulk callers remove keys across whole regions).
+        const cellMeta = this.metas.getIfExists(physicalRow)?.getIfExists(physicalColumn);
+        if (cellMeta === undefined) {
+            return;
+        }
         delete cellMeta[key];
         cellMeta._userDefinedMetaProps?.delete(key);
+        cellMeta._persistedMetaProps?.delete(key);
     }
     /**
    * Returns all cell meta objects that were created during the Handsontable operation. As cell meta
@@ -183,11 +231,11 @@ class CellMeta {
    * @returns {object[]}
    */ getMetasAtRow(physicalRow) {
         assert(()=>isUnsignedNumber(physicalRow), 'Expecting an unsigned number.');
-        const rowsMeta = new Map(this.metas);
-        if (!rowsMeta.has(physicalRow)) {
+        const rowMeta = this.metas.getIfExists(physicalRow);
+        if (rowMeta === undefined) {
             return [];
         }
-        return Array.from(rowsMeta.get(physicalRow)).sort(([a], [b])=>a - b).map(([, meta])=>meta);
+        return Array.from(rowMeta).sort(([a], [b])=>a - b).map(([, meta])=>meta);
     }
     /**
    * Returns a flat snapshot of all cell meta properties that were set imperatively through
@@ -220,6 +268,49 @@ class CellMeta {
         return result;
     }
     /**
+   * Releases render-derived cell meta objects for a single physical row, freeing memory for rows
+   * scrolled out of the viewport. A cell is evicted only when it is purely render-derived: it carries
+   * no persisted meta props (nothing set through `setMeta`/`setCellMeta`, whether imperatively or via
+   * the declarative `cell` option) and is not flagged invalid (`valid === false`, written directly by
+   * the validation flow and not rebuilt on render). Such cells are pure cascade/`cells`/`type`
+   * derivations and are re-created lazily on the next `getMeta` call. Cells with persisted props or a
+   * failed validation result are kept so those values survive scrolling. When the whole row is purely
+   * render-derived, its inner map is dropped as well.
+   *
+   * @param {number} physicalRow The physical row index to evict.
+   * @returns {number[]} The physical column indexes whose meta was evicted (empty when nothing was).
+   */ evictRow(physicalRow) {
+        const rowMap = this.metas.getIfExists(physicalRow);
+        if (rowMap === undefined) {
+            return [];
+        }
+        let hasKeptCell = false;
+        const evictedColumns = [];
+        for (const [physicalColumn, meta] of rowMap){
+            const persistedProps = meta._persistedMetaProps;
+            const hasPersistedProps = persistedProps !== undefined && persistedProps.size > 0;
+            // A failed validation result (`valid === false`) is written directly onto the meta object by
+            // the core validation flow (not through `setMeta`) and is not rebuilt on render, so the cell
+            // must survive eviction or the invalid-cell highlight would disappear after scrolling away.
+            // Only `false` is preserved, not `valid === true`: a passing result has no rendered state and
+            // preserving every validated-valid cell would defeat the memory bound on a fully validated grid.
+            // The trade-off is that `getCellMeta().valid` reads back as `undefined` (not `true`) for an
+            // evicted-and-re-minted valid cell until it is validated again; no core reader distinguishes the
+            // two (all branch on `!== false`).
+            const isInvalid = meta.valid === false;
+            if (hasPersistedProps || isInvalid) {
+                hasKeptCell = true;
+            } else {
+                rowMap.evict(physicalColumn);
+                evictedColumns.push(physicalColumn);
+            }
+        }
+        if (!hasKeptCell) {
+            this.metas.evict(physicalRow);
+        }
+        return evictedColumns;
+    }
+    /**
    * Clears all saved cell meta objects.
    */ clearCache() {
         this.metas.clear();
@@ -239,6 +330,10 @@ class CellMeta {
    * @param {number} physicalColumn The physical column index.
    * @returns {object}
    */ _createMeta(physicalColumn) {
+        // The constructor is produced by `columnFactory` through runtime prototype inheritance, which
+        // TypeScript cannot follow - this single cast is where the meta object type enters the layer.
+        // The prototype chain supplies every grid setting; the coordinate properties are stamped by
+        // `MetaManager` on each read, completing the `CellProperties` shape.
         const ColumnMeta = this.columnMeta.getMetaConstructor(physicalColumn);
         return new ColumnMeta();
     }

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

@@ -59,9 +59,10 @@ export default class ColumnMeta {
      * Creates one or more columns at specific position.
      *
      * @param {number} physicalColumn The physical column index which points from what position the column is added.
+     *   Pass `null` to append at the end.
      * @param {number} amount An amount of columns to add.
      */
-    createColumn(physicalColumn: number, amount: number): void;
+    createColumn(physicalColumn: number | null, amount: number): void;
     /**
      * Removes one or more columns from the collection.
      *

package/dataMap/metaManager/metaLayers/columnMeta.js

@@ -40,6 +40,7 @@ class ColumnMeta {
    * Creates one or more columns at specific position.
    *
    * @param {number} physicalColumn The physical column index which points from what position the column is added.
+   *   Pass `null` to append at the end.
    * @param {number} amount An amount of columns to add.
    */ createColumn(physicalColumn, amount) {
         this.metas.insert(physicalColumn, amount);

package/dataMap/metaManager/metaLayers/columnMeta.mjs

@@ -25,6 +25,7 @@ class ColumnMeta {
    * Creates one or more columns at specific position.
    *
    * @param {number} physicalColumn The physical column index which points from what position the column is added.
+   *   Pass `null` to append at the end.
    * @param {number} amount An amount of columns to add.
    */ createColumn(physicalColumn, amount) {
         this.metas.insert(physicalColumn, amount);