ng-virtual-list 17.3.2 → 17.4.1

package/fesm2022/ng-virtual-list.mjs

@@ -42,7 +42,8 @@ var SnappingMethods;
 })(SnappingMethods || (SnappingMethods = {}));
 
 const DEFAULT_ITEM_SIZE = 24;
-const DEFAULT_ITEMS_OFFSET = 2;
+const DEFAULT_BUFFER_SIZE = 2;
+const DEFAULT_MAX_BUFFER_SIZE = 100;
 const DEFAULT_LIST_SIZE = 400;
 const DEFAULT_SNAP = false;
 const DEFAULT_ENABLED_BUFFER_OPTIMIZATION = false;
@@ -209,29 +210,15 @@ class NgVirtualListItemComponent extends BaseVirtualListItemComponent {
         styles.zIndex = HIDDEN_ZINDEX;
     }
     static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "17.3.12", ngImport: i0, type: NgVirtualListItemComponent, deps: [], target: i0.ɵɵFactoryTarget.Component });
-    static ɵcmp = i0.ɵɵngDeclareComponent({ minVersion: "17.0.0", version: "17.3.12", type: NgVirtualListItemComponent, selector: "ng-virtual-list-item", host: { classAttribute: "ngvl__item" }, usesInheritance: true, ngImport: i0, template: "@if (data(); as item) {\r\n    <li #listItem part=\"item\" class=\"ngvl-item__container\" [ngClass]=\"{'snapped': item.config.snapped,\r\n        'snapped-out': item.config.snappedOut}\">\r\n        @if (itemRenderer(); as renderer) {\r\n            <ng-container [ngTemplateOutlet]=\"renderer\"\r\n                [ngTemplateOutletContext]=\"{data: item.data || {}, config: item.config}\" />\r\n        }\r\n    </li>\r\n}", styles: [":host{display:block;position:absolute;left:0;top:0;box-sizing:border-box;overflow:hidden;will-change:scroll-position}.ngvl-item__container{margin:0;padding:0;overflow:hidden;background-color:#fff;width:inherit;height:inherit}\n"], dependencies: [{ kind: "directive", type: i1.NgClass, selector: "[ngClass]", inputs: ["class", "ngClass"] }, { kind: "directive", type: i1.NgTemplateOutlet, selector: "[ngTemplateOutlet]", inputs: ["ngTemplateOutletContext", "ngTemplateOutlet", "ngTemplateOutletInjector"] }], changeDetection: i0.ChangeDetectionStrategy.OnPush });
+    static ɵcmp = i0.ɵɵngDeclareComponent({ minVersion: "17.0.0", version: "17.3.12", type: NgVirtualListItemComponent, selector: "ng-virtual-list-item", host: { classAttribute: "ngvl__item" }, usesInheritance: true, ngImport: i0, template: "@if (data(); as item) {\r\n    <li #listItem part=\"item\" class=\"ngvl-item__container\" [ngClass]=\"{'snapped': item.config.snapped,\r\n        'snapped-out': item.config.snappedOut}\">\r\n        @if (itemRenderer(); as renderer) {\r\n            <ng-container [ngTemplateOutlet]=\"renderer\"\r\n                [ngTemplateOutletContext]=\"{data: item.data || {}, config: item.config}\" />\r\n        }\r\n    </li>\r\n}", styles: [":host{display:block;position:absolute;left:0;top:0;box-sizing:border-box;overflow:hidden}.ngvl-item__container{margin:0;padding:0;overflow:hidden;background-color:#fff;width:inherit;height:inherit}\n"], dependencies: [{ kind: "directive", type: i1.NgClass, selector: "[ngClass]", inputs: ["class", "ngClass"] }, { kind: "directive", type: i1.NgTemplateOutlet, selector: "[ngTemplateOutlet]", inputs: ["ngTemplateOutletContext", "ngTemplateOutlet", "ngTemplateOutletInjector"] }], changeDetection: i0.ChangeDetectionStrategy.OnPush });
 }
 i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "17.3.12", ngImport: i0, type: NgVirtualListItemComponent, decorators: [{
             type: Component,
             args: [{ selector: 'ng-virtual-list-item', standalone: false, host: {
                         'class': 'ngvl__item',
-                    }, changeDetection: ChangeDetectionStrategy.OnPush, template: "@if (data(); as item) {\r\n    <li #listItem part=\"item\" class=\"ngvl-item__container\" [ngClass]=\"{'snapped': item.config.snapped,\r\n        'snapped-out': item.config.snappedOut}\">\r\n        @if (itemRenderer(); as renderer) {\r\n            <ng-container [ngTemplateOutlet]=\"renderer\"\r\n                [ngTemplateOutletContext]=\"{data: item.data || {}, config: item.config}\" />\r\n        }\r\n    </li>\r\n}", styles: [":host{display:block;position:absolute;left:0;top:0;box-sizing:border-box;overflow:hidden;will-change:scroll-position}.ngvl-item__container{margin:0;padding:0;overflow:hidden;background-color:#fff;width:inherit;height:inherit}\n"] }]
+                    }, changeDetection: ChangeDetectionStrategy.OnPush, template: "@if (data(); as item) {\r\n    <li #listItem part=\"item\" class=\"ngvl-item__container\" [ngClass]=\"{'snapped': item.config.snapped,\r\n        'snapped-out': item.config.snappedOut}\">\r\n        @if (itemRenderer(); as renderer) {\r\n            <ng-container [ngTemplateOutlet]=\"renderer\"\r\n                [ngTemplateOutletContext]=\"{data: item.data || {}, config: item.config}\" />\r\n        }\r\n    </li>\r\n}", styles: [":host{display:block;position:absolute;left:0;top:0;box-sizing:border-box;overflow:hidden}.ngvl-item__container{margin:0;padding:0;overflow:hidden;background-color:#fff;width:inherit;height:inherit}\n"] }]
         }], ctorParameters: () => [] });
 
-const HORIZONTAL_ALIASES = [Directions.HORIZONTAL, 'horizontal'], VERTICAL_ALIASES = [Directions.VERTICAL, 'vertical'];
-/**
- * Determines the axis membership of a virtual list
- * @link https://github.com/DjonnyX/ng-virtual-list/blob/17.x/projects/ng-virtual-list/src/lib/utils/isDirection.ts
- * @author Evgenii Grebennikov
- * @email djonnyx@gmail.com
- */
-const isDirection = (src, expected) => {
-    if (HORIZONTAL_ALIASES.includes(expected)) {
-        return HORIZONTAL_ALIASES.includes(src);
-    }
-    return VERTICAL_ALIASES.includes(src);
-};
-
 /**
  * Simple debounce function.
  * @link https://github.com/DjonnyX/ng-virtual-list/blob/17.x/projects/ng-virtual-list/src/lib/utils/debounce.ts
@@ -279,137 +266,44 @@ const toggleClassName = (el, className, removeClassName) => {
 };
 
 /**
- * Tracks display items by property
- * @link https://github.com/DjonnyX/ng-virtual-list/blob/17.x/projects/ng-virtual-list/src/lib/utils/tracker.ts
+ * Scroll event.
+ * @link https://github.com/DjonnyX/ng-virtual-list/blob/17.x/projects/ng-virtual-list/src/lib/utils/scrollEvent.ts
  * @author Evgenii Grebennikov
  * @email djonnyx@gmail.com
  */
-class Tracker {
-    /**
-     * display objects dictionary of indexes by id
-     */
-    _displayObjectIndexMapById = {};
-    set displayObjectIndexMapById(v) {
-        if (this._displayObjectIndexMapById === v) {
-            return;
-        }
-        this._displayObjectIndexMapById = v;
-    }
-    get displayObjectIndexMapById() {
-        return this._displayObjectIndexMapById;
-    }
-    /**
-     * Dictionary displayItems propertyNameId by items propertyNameId
-     */
-    _trackMap = {};
-    get trackMap() {
-        return this._trackMap;
-    }
-    _trackingPropertyName;
-    set trackingPropertyName(v) {
-        this._trackingPropertyName = v;
-    }
-    constructor(trackingPropertyName) {
-        this._trackingPropertyName = trackingPropertyName;
-    }
-    /**
-     * tracking by propName
-     */
-    track(items, components, snapedComponent, direction) {
-        if (!items) {
-            return;
-        }
-        const idPropName = this._trackingPropertyName, untrackedItems = [...components], isDown = direction === 0 || direction === 1;
-        let isRegularSnapped = false;
-        for (let i = isDown ? 0 : items.length - 1, l = isDown ? items.length : 0; isDown ? i < l : i >= l; isDown ? i++ : i--) {
-            const item = items[i], itemTrackingProperty = item[idPropName];
-            if (this._trackMap) {
-                if (this._trackMap.hasOwnProperty(itemTrackingProperty)) {
-                    const diId = this._trackMap[itemTrackingProperty], compIndex = this._displayObjectIndexMapById[diId], comp = components[compIndex];
-                    const compId = comp?.instance?.id;
-                    if (comp !== undefined && compId === diId) {
-                        const indexByUntrackedItems = untrackedItems.findIndex(v => {
-                            return v.instance.id === compId;
-                        });
-                        if (indexByUntrackedItems > -1) {
-                            if (snapedComponent) {
-                                if (item['config']['snapped'] || item['config']['snappedOut']) {
-                                    isRegularSnapped = true;
-                                    snapedComponent.instance.item = item;
-                                    snapedComponent.instance.show();
-                                }
-                            }
-                            comp.instance.item = item;
-                            if (snapedComponent) {
-                                if (item['config']['snapped'] || item['config']['snappedOut']) {
-                                    comp.instance.hide();
-                                }
-                                else {
-                                    comp.instance.show();
-                                }
-                            }
-                            else {
-                                comp.instance.show();
-                            }
-                            untrackedItems.splice(indexByUntrackedItems, 1);
-                            continue;
-                        }
-                    }
-                    delete this._trackMap[itemTrackingProperty];
-                }
-            }
-            if (untrackedItems.length > 0) {
-                const comp = untrackedItems.shift(), item = items[i];
-                if (comp) {
-                    if (snapedComponent) {
-                        if (item['config']['snapped'] || item['config']['snappedOut']) {
-                            isRegularSnapped = true;
-                            snapedComponent.instance.item = item;
-                            snapedComponent.instance.show();
-                        }
-                    }
-                    comp.instance.item = item;
-                    if (snapedComponent) {
-                        if (item['config']['snapped'] || item['config']['snappedOut']) {
-                            comp.instance.hide();
-                        }
-                        else {
-                            comp.instance.show();
-                        }
-                    }
-                    else {
-                        comp.instance.show();
-                    }
-                    if (this._trackMap) {
-                        this._trackMap[itemTrackingProperty] = comp.instance.id;
-                    }
-                }
-            }
-        }
-        if (untrackedItems.length) {
-            for (let i = 0, l = untrackedItems.length; i < l; i++) {
-                const comp = untrackedItems[i];
-                comp.instance.hide();
-            }
-        }
-        if (!isRegularSnapped) {
-            if (snapedComponent) {
-                snapedComponent.instance.item = null;
-                snapedComponent.instance.hide();
-            }
-        }
-    }
-    untrackComponentByIdProperty(component) {
-        if (!component) {
-            return;
-        }
-        const propertyIdName = this._trackingPropertyName;
-        if (this._trackMap && component[propertyIdName] !== undefined) {
-            delete this._trackMap[propertyIdName];
-        }
-    }
-    dispose() {
-        this._trackMap = null;
+class ScrollEvent {
+    _direction = 1;
+    get direction() { return this._direction; }
+    _scrollSize = 0;
+    get scrollSize() { return this._scrollSize; }
+    _scrollWeight = 0;
+    get scrollWeight() { return this._scrollWeight; }
+    _isVertical = true;
+    get isVertical() { return this._isVertical; }
+    _listSize = 0;
+    get listSize() { return this._listSize; }
+    _size = 0;
+    get size() { return this._size; }
+    _isStart = true;
+    get isStart() { return this._isStart; }
+    _isEnd = false;
+    get isEnd() { return this._isEnd; }
+    _delta = 0;
+    get delta() { return this._delta; }
+    _scrollDelta = 0;
+    get scrollDelta() { return this._scrollDelta; }
+    constructor(params) {
+        const { direction, isVertical, container, list, delta, scrollDelta } = params;
+        this._direction = direction;
+        this._isVertical = isVertical;
+        this._scrollSize = isVertical ? container.scrollTop : container.scrollLeft;
+        this._scrollWeight = isVertical ? container.scrollHeight : container.scrollWidth;
+        this._listSize = isVertical ? list.offsetHeight : list.offsetWidth;
+        this._size = isVertical ? container.offsetHeight : container.offsetWidth;
+        this._isEnd = (this._scrollSize + this._size) === this._scrollWeight;
+        this._delta = delta;
+        this._scrollDelta = scrollDelta;
+        this._isStart = this._scrollSize === 0;
     }
 }
 
@@ -684,6 +578,168 @@ class CacheMap extends EventEmitter {
     }
 }
 
+/**
+ * Tracks display items by property
+ * @link https://github.com/DjonnyX/ng-virtual-list/blob/17.x/projects/ng-virtual-list/src/lib/utils/tracker.ts
+ * @author Evgenii Grebennikov
+ * @email djonnyx@gmail.com
+ */
+class Tracker {
+    /**
+     * display objects dictionary of indexes by id
+     */
+    _displayObjectIndexMapById = {};
+    set displayObjectIndexMapById(v) {
+        if (this._displayObjectIndexMapById === v) {
+            return;
+        }
+        this._displayObjectIndexMapById = v;
+    }
+    get displayObjectIndexMapById() {
+        return this._displayObjectIndexMapById;
+    }
+    /**
+     * Dictionary displayItems propertyNameId by items propertyNameId
+     */
+    _trackMap = {};
+    get trackMap() {
+        return this._trackMap;
+    }
+    _trackingPropertyName;
+    set trackingPropertyName(v) {
+        this._trackingPropertyName = v;
+    }
+    constructor(trackingPropertyName) {
+        this._trackingPropertyName = trackingPropertyName;
+    }
+    /**
+     * tracking by propName
+     */
+    track(items, components, snapedComponent, direction) {
+        if (!items) {
+            return;
+        }
+        const idPropName = this._trackingPropertyName, untrackedItems = [...components], isDown = direction === 0 || direction === 1;
+        let isRegularSnapped = false;
+        for (let i = isDown ? 0 : items.length - 1, l = isDown ? items.length : 0; isDown ? i < l : i >= l; isDown ? i++ : i--) {
+            const item = items[i], itemTrackingProperty = item[idPropName];
+            if (this._trackMap) {
+                if (this._trackMap.hasOwnProperty(itemTrackingProperty)) {
+                    const diId = this._trackMap[itemTrackingProperty], compIndex = this._displayObjectIndexMapById[diId], comp = components[compIndex];
+                    const compId = comp?.instance?.id;
+                    if (comp !== undefined && compId === diId) {
+                        const indexByUntrackedItems = untrackedItems.findIndex(v => {
+                            return v.instance.id === compId;
+                        });
+                        if (indexByUntrackedItems > -1) {
+                            if (snapedComponent) {
+                                if (item['config']['snapped'] || item['config']['snappedOut']) {
+                                    isRegularSnapped = true;
+                                    snapedComponent.instance.item = item;
+                                    snapedComponent.instance.show();
+                                }
+                            }
+                            comp.instance.item = item;
+                            if (snapedComponent) {
+                                if (item['config']['snapped'] || item['config']['snappedOut']) {
+                                    comp.instance.hide();
+                                }
+                                else {
+                                    comp.instance.show();
+                                }
+                            }
+                            else {
+                                comp.instance.show();
+                            }
+                            untrackedItems.splice(indexByUntrackedItems, 1);
+                            continue;
+                        }
+                    }
+                    delete this._trackMap[itemTrackingProperty];
+                }
+            }
+            if (untrackedItems.length > 0) {
+                const comp = untrackedItems.shift(), item = items[i];
+                if (comp) {
+                    if (snapedComponent) {
+                        if (item['config']['snapped'] || item['config']['snappedOut']) {
+                            isRegularSnapped = true;
+                            snapedComponent.instance.item = item;
+                            snapedComponent.instance.show();
+                        }
+                    }
+                    comp.instance.item = item;
+                    if (snapedComponent) {
+                        if (item['config']['snapped'] || item['config']['snappedOut']) {
+                            comp.instance.hide();
+                        }
+                        else {
+                            comp.instance.show();
+                        }
+                    }
+                    else {
+                        comp.instance.show();
+                    }
+                    if (this._trackMap) {
+                        this._trackMap[itemTrackingProperty] = comp.instance.id;
+                    }
+                }
+            }
+        }
+        if (untrackedItems.length) {
+            for (let i = 0, l = untrackedItems.length; i < l; i++) {
+                const comp = untrackedItems[i];
+                comp.instance.hide();
+            }
+        }
+        if (!isRegularSnapped) {
+            if (snapedComponent) {
+                snapedComponent.instance.item = null;
+                snapedComponent.instance.hide();
+            }
+        }
+    }
+    untrackComponentByIdProperty(component) {
+        if (!component) {
+            return;
+        }
+        const propertyIdName = this._trackingPropertyName;
+        if (this._trackMap && component[propertyIdName] !== undefined) {
+            delete this._trackMap[propertyIdName];
+        }
+    }
+    dispose() {
+        this._trackMap = null;
+    }
+}
+
+const DEFAULT_EXTRA = {
+    extremumThreshold: 2,
+    bufferSize: 10,
+};
+const bufferInterpolation = (currentBufferValue, array, value, extra) => {
+    const { extremumThreshold = DEFAULT_EXTRA.extremumThreshold, bufferSize = DEFAULT_EXTRA.bufferSize, } = extra ?? DEFAULT_EXTRA;
+    if (currentBufferValue < value) {
+        let i = 0;
+        while (i < extremumThreshold) {
+            array.push(value);
+            i++;
+        }
+    }
+    else {
+        array.push(value);
+    }
+    while (array.length >= bufferSize) {
+        array.shift();
+    }
+    const l = array.length;
+    let buffer = 0;
+    for (let i = 0; i < l; i++) {
+        buffer += array[i];
+    }
+    return Math.ceil(buffer / l);
+};
+
 const TRACK_BOX_CHANGE_EVENT_NAME = 'change';
 var ItemDisplayMethods;
 (function (ItemDisplayMethods) {
@@ -692,6 +748,7 @@ var ItemDisplayMethods;
     ItemDisplayMethods[ItemDisplayMethods["DELETE"] = 2] = "DELETE";
     ItemDisplayMethods[ItemDisplayMethods["NOT_CHANGED"] = 3] = "NOT_CHANGED";
 })(ItemDisplayMethods || (ItemDisplayMethods = {}));
+const DEFAULT_BUFFER_EXTREMUM_THRESHOLD = 15, DEFAULT_MAX_BUFFER_SEQUENCE_LENGTH = 30, DEFAULT_RESET_BUFFER_SIZE_TIMEOUT = 10000;
 /**
  * An object that performs tracking, calculations and caching.
  * @link https://github.com/DjonnyX/ng-virtual-list/blob/17.x/projects/ng-virtual-list/src/lib/utils/trackBox.ts
@@ -732,11 +789,16 @@ class TrackBox extends CacheMap {
      * Set the trackBy property
      */
     set trackingPropertyName(v) {
-        this._tracker.trackingPropertyName = v;
+        this._trackingPropertyName = this._tracker.trackingPropertyName = v;
     }
+    _trackingPropertyName = TRACK_BY_PROPERTY_NAME;
     constructor(trackingPropertyName) {
         super();
-        this._tracker = new Tracker(trackingPropertyName);
+        this._trackingPropertyName = trackingPropertyName;
+        this.initialize();
+    }
+    initialize() {
+        this._tracker = new Tracker(this._trackingPropertyName);
     }
     set(id, bounds) {
         if (this._map.has(id)) {
@@ -761,6 +823,16 @@ class TrackBox extends CacheMap {
     _previousTotalSize = 0;
     _scrollDelta = 0;
     get scrollDelta() { return this._scrollDelta; }
+    isAdaptiveBuffer = true;
+    _bufferSequenceExtraThreshold = DEFAULT_BUFFER_EXTREMUM_THRESHOLD;
+    _maxBufferSequenceLength = DEFAULT_MAX_BUFFER_SEQUENCE_LENGTH;
+    _bufferSizeSequence = [];
+    _bufferSize = 0;
+    get bufferSize() { return this._bufferSize; }
+    _defaultBufferSize = 0;
+    _maxBufferSize = this._defaultBufferSize;
+    _resetBufferSizeTimeout = DEFAULT_RESET_BUFFER_SIZE_TIMEOUT;
+    _resetBufferSizeTimer;
     lifeCircle() {
         this.fireChangeIfNeed();
         this.lifeCircleDo();
@@ -854,6 +926,8 @@ class TrackBox extends CacheMap {
      */
     getItemPosition(id, stickyMap, options) {
         const opt = { fromItemId: id, stickyMap, ...options };
+        this._defaultBufferSize = opt.bufferSize;
+        this._maxBufferSize = opt.maxBufferSize;
         const { scrollSize, isFromItemIdFound } = this.recalculateMetrics({
             ...opt,
             dynamicSize: this._crudDetected || opt.dynamicSize,
@@ -871,6 +945,8 @@ class TrackBox extends CacheMap {
         if (opt.dynamicSize) {
             this.cacheElements();
         }
+        this._defaultBufferSize = opt.bufferSize;
+        this._maxBufferSize = opt.maxBufferSize;
         const metrics = this.recalculateMetrics({
             ...opt,
             collection: items,
@@ -879,6 +955,7 @@ class TrackBox extends CacheMap {
             deletedItemsMap,
         });
         this._delta += metrics.delta;
+        this.updateAdaptiveBufferParams(metrics, items.length);
         this._previousTotalSize = metrics.totalSize;
         this._deletedItemsMap = {};
         this._crudDetected = false;
@@ -894,6 +971,27 @@ class TrackBox extends CacheMap {
     getNearestItem(scrollSize, items, itemSize, isVertical) {
         return this.getElementFromStart(scrollSize, items, this._map, itemSize, isVertical);
     }
+    _previousScrollSize = 0;
+    updateAdaptiveBufferParams(metrics, totalItemsLength) {
+        this.disposeClearBufferSizeTimer();
+        const scrollSize = metrics.scrollSize + this._delta, delta = Math.abs(this._previousScrollSize - scrollSize);
+        this._previousScrollSize = scrollSize;
+        const bufferRawSize = Math.min(Math.floor(delta / metrics.typicalItemSize) * 5, totalItemsLength), minBufferSize = bufferRawSize < this._defaultBufferSize ? this._defaultBufferSize : bufferRawSize, bufferValue = minBufferSize > this._maxBufferSize ? this._maxBufferSize : minBufferSize;
+        this._bufferSize = bufferInterpolation(this._bufferSize, this._bufferSizeSequence, bufferValue, {
+            extremumThreshold: this._bufferSequenceExtraThreshold,
+            bufferSize: this._maxBufferSequenceLength,
+        });
+        this.startResetBufferSizeTimer();
+    }
+    startResetBufferSizeTimer() {
+        this._resetBufferSizeTimer = setTimeout(() => {
+            this._bufferSize = this._defaultBufferSize;
+            this._bufferSizeSequence = [];
+        }, this._resetBufferSizeTimeout);
+    }
+    disposeClearBufferSizeTimer() {
+        clearTimeout(this._resetBufferSizeTimer);
+    }
     /**
      * Calculates the position of an element based on the given scrollSize
      */
@@ -945,30 +1043,30 @@ class TrackBox extends CacheMap {
      * Calculates list metrics
      */
     recalculateMetrics(options) {
-        const { fromItemId, bounds, collection, dynamicSize, isVertical, itemSize, itemsOffset, scrollSize, snap, stickyMap, enabledBufferOptimization, previousTotalSize, crudDetected, deletedItemsMap } = options;
-        const { width, height } = bounds, sizeProperty = isVertical ? HEIGHT_PROP_NAME : WIDTH_PROP_NAME, size = isVertical ? height : width, totalLength = collection.length, typicalItemSize = itemSize, w = isVertical ? width : typicalItemSize, h = isVertical ? typicalItemSize : height, map = this._map, snapshot = this._snapshot, checkOverscrollItemsLimit = Math.ceil(size / typicalItemSize), snippedPos = Math.floor(scrollSize), leftItemsWeights = [], isFromId = fromItemId !== undefined && (typeof fromItemId === 'number' && fromItemId > -1)
+        const { fromItemId, bounds, collection, dynamicSize, isVertical, itemSize, bufferSize: minBufferSize, scrollSize, snap, stickyMap, enabledBufferOptimization, previousTotalSize, crudDetected, deletedItemsMap } = options;
+        const bufferSize = Math.max(minBufferSize, this._bufferSize), { width, height } = bounds, sizeProperty = isVertical ? HEIGHT_PROP_NAME : WIDTH_PROP_NAME, size = isVertical ? height : width, totalLength = collection.length, typicalItemSize = itemSize, w = isVertical ? width : typicalItemSize, h = isVertical ? typicalItemSize : height, map = this._map, snapshot = this._snapshot, checkOverscrollItemsLimit = Math.ceil(size / typicalItemSize), snippedPos = Math.floor(scrollSize), leftItemsWeights = [], isFromId = fromItemId !== undefined && (typeof fromItemId === 'number' && fromItemId > -1)
             || (typeof fromItemId === 'string' && fromItemId > '-1');
         let leftItemsOffset = 0, rightItemsOffset = 0;
         if (enabledBufferOptimization) {
             switch (this.scrollDirection) {
                 case 1: {
                     leftItemsOffset = 0;
-                    rightItemsOffset = itemsOffset;
+                    rightItemsOffset = bufferSize;
                     break;
                 }
                 case -1: {
-                    leftItemsOffset = itemsOffset;
+                    leftItemsOffset = bufferSize;
                     rightItemsOffset = 0;
                     break;
                 }
                 case 0:
                 default: {
-                    leftItemsOffset = rightItemsOffset = itemsOffset;
+                    leftItemsOffset = rightItemsOffset = bufferSize;
                 }
             }
         }
         else {
-            leftItemsOffset = rightItemsOffset = itemsOffset;
+            leftItemsOffset = rightItemsOffset = bufferSize;
         }
         let itemsFromStartToScrollEnd = -1, itemsFromDisplayEndToOffsetEnd = 0, itemsFromStartToDisplayEnd = -1, leftItemLength = 0, rightItemLength = 0, leftItemsWeight = 0, rightItemsWeight = 0, leftHiddenItemsWeight = 0, totalItemsToDisplayEndWeight = 0, leftSizeOfAddedItems = 0, leftSizeOfUpdatedItems = 0, leftSizeOfDeletedItems = 0, itemById = undefined, itemByIdPos = 0, targetDisplayItemIndex = -1, isTargetInOverscroll = false, actualScrollSize = itemByIdPos, totalSize = 0, startIndex, isFromItemIdFound = false;
         // If the list is dynamic or there are new elements in the collection, then it switches to the long algorithm.
@@ -1143,9 +1241,9 @@ class TrackBox extends CacheMap {
             }
             itemsFromStartToScrollEnd = Math.floor(scrollSize / typicalItemSize);
             itemsFromStartToDisplayEnd = Math.ceil((scrollSize + size) / typicalItemSize);
-            leftItemLength = Math.min(itemsFromStartToScrollEnd, itemsOffset);
-            rightItemLength = itemsFromStartToDisplayEnd + itemsOffset > totalLength
-                ? totalLength - itemsFromStartToDisplayEnd : itemsOffset;
+            leftItemLength = Math.min(itemsFromStartToScrollEnd, bufferSize);
+            rightItemLength = itemsFromStartToDisplayEnd + bufferSize > totalLength
+                ? totalLength - itemsFromStartToDisplayEnd : bufferSize;
             leftItemsWeight = leftItemLength * typicalItemSize;
             rightItemsWeight = rightItemLength * typicalItemSize;
             leftHiddenItemsWeight = itemsFromStartToScrollEnd * typicalItemSize;
@@ -1242,6 +1340,9 @@ class TrackBox extends CacheMap {
             if (snap) {
                 const startIndex = itemsFromStartToScrollEnd + itemsOnDisplayLength - 1;
                 for (let i = Math.min(startIndex, totalLength > 0 ? totalLength - 1 : 0), l = totalLength; i < l; i++) {
+                    if (!items[i]) {
+                        continue;
+                    }
                     const id = items[i].id, sticky = stickyMap[id], size = dynamicSize
                         ? this.get(id)?.[sizeProperty] || typicalItemSize
                         : typicalItemSize;
@@ -1276,6 +1377,9 @@ class TrackBox extends CacheMap {
                 if (i >= totalLength) {
                     break;
                 }
+                if (!items[i]) {
+                    continue;
+                }
                 const id = items[i].id, size = dynamicSize ? this.get(id)?.[sizeProperty] || typicalItemSize : typicalItemSize;
                 if (id !== stickyItem?.id && id !== endStickyItem?.id) {
                     const snapped = snap && (stickyMap[id] === 1 && pos <= scrollSize || stickyMap[id] === 2 && pos >= scrollSize + boundsSize - size), measures = {
@@ -1387,54 +1491,13 @@ class TrackBox extends CacheMap {
     }
     dispose() {
         super.dispose();
+        this.disposeClearBufferSizeTimer();
         if (this._tracker) {
             this._tracker.dispose();
         }
     }
 }
 
-/**
- * Scroll event.
- * @link https://github.com/DjonnyX/ng-virtual-list/blob/17.x/projects/ng-virtual-list/src/lib/utils/scrollEvent.ts
- * @author Evgenii Grebennikov
- * @email djonnyx@gmail.com
- */
-class ScrollEvent {
-    _direction = 1;
-    get direction() { return this._direction; }
-    _scrollSize = 0;
-    get scrollSize() { return this._scrollSize; }
-    _scrollWeight = 0;
-    get scrollWeight() { return this._scrollWeight; }
-    _isVertical = true;
-    get isVertical() { return this._isVertical; }
-    _listSize = 0;
-    get listSize() { return this._listSize; }
-    _size = 0;
-    get size() { return this._size; }
-    _isStart = true;
-    get isStart() { return this._isStart; }
-    _isEnd = false;
-    get isEnd() { return this._isEnd; }
-    _delta = 0;
-    get delta() { return this._delta; }
-    _scrollDelta = 0;
-    get scrollDelta() { return this._scrollDelta; }
-    constructor(params) {
-        const { direction, isVertical, container, list, delta, scrollDelta } = params;
-        this._direction = direction;
-        this._isVertical = isVertical;
-        this._scrollSize = isVertical ? container.scrollTop : container.scrollLeft;
-        this._scrollWeight = isVertical ? container.scrollHeight : container.scrollWidth;
-        this._listSize = isVertical ? list.offsetHeight : list.offsetWidth;
-        this._size = isVertical ? container.offsetHeight : container.offsetWidth;
-        this._isEnd = (this._scrollSize + this._size) === this._scrollWeight;
-        this._delta = delta;
-        this._scrollDelta = scrollDelta;
-        this._isStart = this._scrollSize === 0;
-    }
-}
-
 const ADVANCED_PATTERNS = [SnappingMethods.ADVANCED, 'advanced'], DEFAULT_PATTERN = [SnappingMethods.NORMAL, 'normal'];
 const isSnappingMethodAdvenced = (method) => {
     return ADVANCED_PATTERNS.includes(method);
@@ -1446,6 +1509,20 @@ const isSnappingMethodDefault = (method) => {
 const IS_FIREFOX = navigator.userAgent.toLowerCase().includes('firefox');
 const FIREFOX_SCROLLBAR_OVERLAP_SIZE = 12;
 
+const HORIZONTAL_ALIASES = [Directions.HORIZONTAL, 'horizontal'], VERTICAL_ALIASES = [Directions.VERTICAL, 'vertical'];
+/**
+ * Determines the axis membership of a virtual list
+ * @link https://github.com/DjonnyX/ng-virtual-list/blob/17.x/projects/ng-virtual-list/src/lib/utils/isDirection.ts
+ * @author Evgenii Grebennikov
+ * @email djonnyx@gmail.com
+ */
+const isDirection = (src, expected) => {
+    if (HORIZONTAL_ALIASES.includes(expected)) {
+        return HORIZONTAL_ALIASES.includes(src);
+    }
+    return VERTICAL_ALIASES.includes(src);
+};
+
 /**
  * Virtual list component.
  * Maximum performance for extremely large lists.
@@ -1530,10 +1607,35 @@ class NgVirtualListComponent {
      * Determines the direction in which elements are placed. Default value is "vertical".
      */
     direction = input(DEFAULT_DIRECTION);
+    _itemOffsetTransform = {
+        transform: (v) => {
+            throw Error('"itemOffset" parameter is deprecated. Use "bufferSize" and "maxBufferSize".');
+        }
+    };
+    /**
+     * Number of elements outside the scope of visibility. Default value is 2.
+     * @deprecated "itemOffset" parameter is deprecated. Use "bufferSize" and "maxBufferSize".
+     */
+    itemsOffset = input(DEFAULT_BUFFER_SIZE, { ...this._itemOffsetTransform });
     /**
      * Number of elements outside the scope of visibility. Default value is 2.
      */
-    itemsOffset = input(DEFAULT_ITEMS_OFFSET);
+    bufferSize = input(DEFAULT_BUFFER_SIZE);
+    _maxBufferSizeTransform = {
+        transform: (v) => {
+            const bufferSize = this.bufferSize();
+            if (v === undefined || v <= bufferSize) {
+                return bufferSize;
+            }
+            return v;
+        }
+    };
+    /**
+     * Maximum number of elements outside the scope of visibility. Default value is 100.
+     * If maxBufferSize is set to be greater than bufferSize, then adaptive buffer mode is enabled.
+     * The greater the scroll size, the more elements are allocated for rendering.
+     */
+    maxBufferSize = input(DEFAULT_MAX_BUFFER_SIZE, { ...this._maxBufferSizeTransform });
     /**
      * Snapping method.
      * 'default' - Normal group rendering.
@@ -1637,7 +1739,7 @@ class NgVirtualListComponent {
         $trackBy.pipe(takeUntilDestroyed(), tap(v => {
             this._trackBox.trackingPropertyName = v;
         })).subscribe();
-        const $bounds = toObservable(this._bounds).pipe(filter(b => !!b)), $items = toObservable(this.items).pipe(map(i => !i ? [] : i)), $scrollSize = toObservable(this._scrollSize), $itemSize = toObservable(this.itemSize).pipe(map(v => v <= 0 ? DEFAULT_ITEM_SIZE : v)), $itemsOffset = toObservable(this.itemsOffset).pipe(map(v => v < 0 ? DEFAULT_ITEMS_OFFSET : v)), $stickyMap = toObservable(this.stickyMap).pipe(map(v => !v ? {} : v)), $snap = toObservable(this.snap), $isVertical = toObservable(this.direction).pipe(map(v => this.getIsVertical(v || DEFAULT_DIRECTION))), $dynamicSize = toObservable(this.dynamicSize), $enabledBufferOptimization = toObservable(this.enabledBufferOptimization), $snappingMethod = toObservable(this.snappingMethod).pipe(map(v => this.getIsSnappingMethodAdvanced(v || DEFAULT_SNAPPING_METHOD))), $cacheVersion = toObservable(this._cacheVersion);
+        const $bounds = toObservable(this._bounds).pipe(filter(b => !!b)), $items = toObservable(this.items).pipe(map(i => !i ? [] : i)), $scrollSize = toObservable(this._scrollSize), $itemSize = toObservable(this.itemSize).pipe(map(v => v <= 0 ? DEFAULT_ITEM_SIZE : v)), $bufferSize = toObservable(this.bufferSize).pipe(map(v => v < 0 ? DEFAULT_BUFFER_SIZE : v)), $maxBufferSize = toObservable(this.maxBufferSize).pipe(map(v => v < 0 ? DEFAULT_BUFFER_SIZE : v)), $stickyMap = toObservable(this.stickyMap).pipe(map(v => !v ? {} : v)), $snap = toObservable(this.snap), $isVertical = toObservable(this.direction).pipe(map(v => this.getIsVertical(v || DEFAULT_DIRECTION))), $dynamicSize = toObservable(this.dynamicSize), $enabledBufferOptimization = toObservable(this.enabledBufferOptimization), $snappingMethod = toObservable(this.snappingMethod).pipe(map(v => this.getIsSnappingMethodAdvanced(v || DEFAULT_SNAPPING_METHOD))), $cacheVersion = toObservable(this._cacheVersion);
         $isVertical.pipe(takeUntilDestroyed(), tap(v => {
             this._isVertical = v;
             const el = this._elementRef.nativeElement;
@@ -1650,12 +1752,12 @@ class NgVirtualListComponent {
             this.listenCacheChangesIfNeed(dynamicSize);
         })).subscribe();
         combineLatest([this.$initialized, $bounds, $items, $stickyMap, $scrollSize, $itemSize,
-            $itemsOffset, $snap, $isVertical, $dynamicSize, $enabledBufferOptimization, $cacheVersion,
-        ]).pipe(takeUntilDestroyed(), distinctUntilChanged(), filter(([initialized]) => !!initialized), switchMap(([, bounds, items, stickyMap, scrollSize, itemSize, itemsOffset, snap, isVertical, dynamicSize, enabledBufferOptimization, cacheVersion,]) => {
+            $bufferSize, $maxBufferSize, $snap, $isVertical, $dynamicSize, $enabledBufferOptimization, $cacheVersion,
+        ]).pipe(takeUntilDestroyed(), distinctUntilChanged(), filter(([initialized]) => !!initialized), switchMap(([, bounds, items, stickyMap, scrollSize, itemSize, bufferSize, maxBufferSize, snap, isVertical, dynamicSize, enabledBufferOptimization, cacheVersion,]) => {
             let actualScrollSize = (this._isVertical ? this._container()?.nativeElement.scrollTop ?? 0 : this._container()?.nativeElement.scrollLeft) ?? 0;
             const { width, height } = bounds, opts = {
                 bounds: { width, height }, dynamicSize, isVertical, itemSize,
-                itemsOffset, scrollSize: actualScrollSize, snap, enabledBufferOptimization,
+                bufferSize, maxBufferSize, scrollSize: actualScrollSize, snap, enabledBufferOptimization,
             }, { displayItems, totalSize } = this._trackBox.updateCollection(items, stickyMap, opts);
             this.resetBoundsSize(isVertical, totalSize);
             this.createDisplayComponentsIfNeed(displayItems);
@@ -1678,9 +1780,6 @@ class NgVirtualListComponent {
             }
             return of(displayItems);
         })).subscribe();
-        this.setupRenderer();
-    }
-    setupRenderer() {
         const $itemRenderer = toObservable(this.itemRenderer);
         $itemRenderer.pipe(takeUntilDestroyed(), distinctUntilChanged(), filter(v => !!v), tap(v => {
             this._itemRenderer.set(v);
@@ -1802,7 +1901,8 @@ class NgVirtualListComponent {
                 }
                 const { width, height } = this._bounds() || { width: DEFAULT_LIST_SIZE, height: DEFAULT_LIST_SIZE }, stickyMap = this.stickyMap(), items = this.items(), isVertical = this._isVertical, delta = this._trackBox.delta, opts = {
                     bounds: { width, height }, collection: items, dynamicSize, isVertical: this._isVertical, itemSize,
-                    itemsOffset: this.itemsOffset(), scrollSize: (isVertical ? container.nativeElement.scrollTop : container.nativeElement.scrollLeft) + delta,
+                    bufferSize: this.bufferSize(), maxBufferSize: this.maxBufferSize(),
+                    scrollSize: (isVertical ? container.nativeElement.scrollTop : container.nativeElement.scrollLeft) + delta,
                     snap: this.snap(), fromItemId: id, enabledBufferOptimization: this.enabledBufferOptimization(),
                 }, scrollSize = this._trackBox.getItemPosition(id, stickyMap, opts), params = { [isVertical ? TOP_PROP_NAME : LEFT_PROP_NAME]: scrollSize, behavior };
                 if (scrollSize === -1) {
@@ -1933,7 +2033,7 @@ class NgVirtualListComponent {
         }
     }
     static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "17.3.12", ngImport: i0, type: NgVirtualListComponent, deps: [], target: i0.ɵɵFactoryTarget.Component });
-    static ɵcmp = i0.ɵɵngDeclareComponent({ minVersion: "17.0.0", version: "17.3.12", type: NgVirtualListComponent, selector: "ng-virtual-list", inputs: { items: { classPropertyName: "items", publicName: "items", isSignal: true, isRequired: true, transformFunction: null }, snap: { classPropertyName: "snap", publicName: "snap", isSignal: true, isRequired: false, transformFunction: null }, enabledBufferOptimization: { classPropertyName: "enabledBufferOptimization", publicName: "enabledBufferOptimization", isSignal: true, isRequired: false, transformFunction: null }, itemRenderer: { classPropertyName: "itemRenderer", publicName: "itemRenderer", isSignal: true, isRequired: true, transformFunction: null }, stickyMap: { classPropertyName: "stickyMap", publicName: "stickyMap", isSignal: true, isRequired: false, transformFunction: null }, itemSize: { classPropertyName: "itemSize", publicName: "itemSize", isSignal: true, isRequired: false, transformFunction: null }, dynamicSize: { classPropertyName: "dynamicSize", publicName: "dynamicSize", isSignal: true, isRequired: false, transformFunction: null }, direction: { classPropertyName: "direction", publicName: "direction", isSignal: true, isRequired: false, transformFunction: null }, itemsOffset: { classPropertyName: "itemsOffset", publicName: "itemsOffset", isSignal: true, isRequired: false, transformFunction: null }, snappingMethod: { classPropertyName: "snappingMethod", publicName: "snappingMethod", isSignal: true, isRequired: false, transformFunction: null }, trackBy: { classPropertyName: "trackBy", publicName: "trackBy", isSignal: true, isRequired: false, transformFunction: null } }, outputs: { onScroll: "onScroll", onScrollEnd: "onScrollEnd" }, viewQueries: [{ propertyName: "_snappedContainer", first: true, predicate: ["snapped"], descendants: true, isSignal: true }, { propertyName: "_container", first: true, predicate: ["container"], descendants: true, isSignal: true }, { propertyName: "_list", first: true, predicate: ["list"], descendants: true, isSignal: true }, { propertyName: "_listContainerRef", first: true, predicate: ["renderersContainer"], descendants: true, read: ViewContainerRef }, { propertyName: "_snapContainerRef", first: true, predicate: ["snapRendererContainer"], descendants: true, read: ViewContainerRef }], ngImport: i0, template: "@if (snap()) {\r\n<div #snapped part=\"snapped-item\" class=\"ngvl__list-snapper\">\r\n  <ng-container #snapRendererContainer></ng-container>\r\n</div>\r\n}\r\n<div #container part=\"scroller\" class=\"ngvl__scroller\">\r\n  <ul #list part=\"list\" class=\"ngvl__list\">\r\n    <ng-container #renderersContainer></ng-container>\r\n  </ul>\r\n</div>", styles: [":host{position:relative;display:block;width:400px;overflow:hidden}:host(.horizontal){height:48px}:host(.horizontal) .ngvl__list{display:inline-flex}:host(.horizontal) .ngvl__scroller{overflow:auto hidden}:host(.vertical) .ngvl__scroller{overflow:hidden auto}:host(.vertical){height:320px}.ngvl__scroller{overflow:auto;width:100%;height:100%}.ngvl__list-snapper{pointer-events:none;position:absolute;list-style:none;left:0;top:0;z-index:1}.ngvl__list{position:relative;list-style:none;padding:0;margin:0;width:100%;height:100%}\n"], changeDetection: i0.ChangeDetectionStrategy.OnPush, encapsulation: i0.ViewEncapsulation.ShadowDom });
+    static ɵcmp = i0.ɵɵngDeclareComponent({ minVersion: "17.0.0", version: "17.3.12", type: NgVirtualListComponent, selector: "ng-virtual-list", inputs: { items: { classPropertyName: "items", publicName: "items", isSignal: true, isRequired: true, transformFunction: null }, snap: { classPropertyName: "snap", publicName: "snap", isSignal: true, isRequired: false, transformFunction: null }, enabledBufferOptimization: { classPropertyName: "enabledBufferOptimization", publicName: "enabledBufferOptimization", isSignal: true, isRequired: false, transformFunction: null }, itemRenderer: { classPropertyName: "itemRenderer", publicName: "itemRenderer", isSignal: true, isRequired: true, transformFunction: null }, stickyMap: { classPropertyName: "stickyMap", publicName: "stickyMap", isSignal: true, isRequired: false, transformFunction: null }, itemSize: { classPropertyName: "itemSize", publicName: "itemSize", isSignal: true, isRequired: false, transformFunction: null }, dynamicSize: { classPropertyName: "dynamicSize", publicName: "dynamicSize", isSignal: true, isRequired: false, transformFunction: null }, direction: { classPropertyName: "direction", publicName: "direction", isSignal: true, isRequired: false, transformFunction: null }, itemsOffset: { classPropertyName: "itemsOffset", publicName: "itemsOffset", isSignal: true, isRequired: false, transformFunction: null }, bufferSize: { classPropertyName: "bufferSize", publicName: "bufferSize", isSignal: true, isRequired: false, transformFunction: null }, maxBufferSize: { classPropertyName: "maxBufferSize", publicName: "maxBufferSize", isSignal: true, isRequired: false, transformFunction: null }, snappingMethod: { classPropertyName: "snappingMethod", publicName: "snappingMethod", isSignal: true, isRequired: false, transformFunction: null }, trackBy: { classPropertyName: "trackBy", publicName: "trackBy", isSignal: true, isRequired: false, transformFunction: null } }, outputs: { onScroll: "onScroll", onScrollEnd: "onScrollEnd" }, viewQueries: [{ propertyName: "_snappedContainer", first: true, predicate: ["snapped"], descendants: true, isSignal: true }, { propertyName: "_container", first: true, predicate: ["container"], descendants: true, isSignal: true }, { propertyName: "_list", first: true, predicate: ["list"], descendants: true, isSignal: true }, { propertyName: "_listContainerRef", first: true, predicate: ["renderersContainer"], descendants: true, read: ViewContainerRef }, { propertyName: "_snapContainerRef", first: true, predicate: ["snapRendererContainer"], descendants: true, read: ViewContainerRef }], ngImport: i0, template: "@if (snap()) {\r\n<div #snapped part=\"snapped-item\" class=\"ngvl__list-snapper\">\r\n  <ng-container #snapRendererContainer></ng-container>\r\n</div>\r\n}\r\n<div #container part=\"scroller\" class=\"ngvl__scroller\">\r\n  <ul #list part=\"list\" class=\"ngvl__list\">\r\n    <ng-container #renderersContainer></ng-container>\r\n  </ul>\r\n</div>", styles: [":host{position:relative;display:block;width:400px;overflow:hidden}:host(.horizontal){height:48px}:host(.horizontal) .ngvl__list{display:inline-flex}:host(.horizontal) .ngvl__scroller{overflow:auto hidden}:host(.vertical) .ngvl__scroller{overflow:hidden auto}:host(.vertical){height:320px}.ngvl__scroller{overflow:auto;width:100%;height:100%}.ngvl__list-snapper{pointer-events:none;position:absolute;list-style:none;left:0;top:0;z-index:1}.ngvl__list{position:relative;list-style:none;padding:0;margin:0;width:100%;height:100%}\n"], changeDetection: i0.ChangeDetectionStrategy.OnPush, encapsulation: i0.ViewEncapsulation.ShadowDom });
 }
 i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "17.3.12", ngImport: i0, type: NgVirtualListComponent, decorators: [{
             type: Component,
@@ -1969,5 +2069,5 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "17.3.12", ngImpo
  * Generated bundle index. Do not edit.
  */
 
-export { BaseVirtualListItemComponent, Directions, NgVirtualListComponent, NgVirtualListItemComponent, NgVirtualListModule, SnappingMethods };
+export { Directions, NgVirtualListComponent, NgVirtualListItemComponent, NgVirtualListModule, ScrollEvent, SnappingMethods, debounce, toggleClassName };
 //# sourceMappingURL=ng-virtual-list.mjs.map