@tanstack/virtual-core 3.13.20 → 3.13.22

package/dist/cjs/index.d.cts

@@ -1,7 +1,7 @@
 export * from './utils.cjs';
 type ScrollDirection = 'forward' | 'backward';
 type ScrollAlignment = 'start' | 'center' | 'end' | 'auto';
-type ScrollBehavior = 'auto' | 'smooth';
+type ScrollBehavior = 'auto' | 'smooth' | 'instant';
 export interface ScrollToOptions {
     align?: ScrollAlignment;
     behavior?: ScrollBehavior;
@@ -83,7 +83,7 @@ export declare class Virtualizer<TScrollElement extends Element | Window, TItemE
     scrollElement: TScrollElement | null;
     targetWindow: (Window & typeof globalThis) | null;
     isScrolling: boolean;
-    private currentScrollToIndex;
+    private scrollState;
     measurementsCache: Array<VirtualItem>;
     private itemSizeCache;
     private laneAssignments;
@@ -97,6 +97,7 @@ export declare class Virtualizer<TScrollElement extends Element | Window, TItemE
     private scrollAdjustments;
     shouldAdjustScrollPositionOnItemSizeChange: undefined | ((item: VirtualItem, delta: number, instance: Virtualizer<TScrollElement, TItemElement>) => boolean);
     elementsCache: Map<Key, TItemElement>;
+    private now;
     private observer;
     range: {
         startIndex: number;
@@ -109,6 +110,9 @@ export declare class Virtualizer<TScrollElement extends Element | Window, TItemE
     private cleanup;
     _didMount: () => () => void;
     _willUpdate: () => void;
+    private rafId;
+    private scheduleScrollReconcile;
+    private reconcileScroll;
     private getSize;
     private getScrollOffset;
     private getFurthestMeasurement;
@@ -126,9 +130,14 @@ export declare class Virtualizer<TScrollElement extends Element | Window, TItemE
         updateDeps(newDeps: [(range: Range) => number[], number, number, number | null, number | null]): void;
     };
     indexFromElement: (node: TItemElement) => number;
-    private _measureElement;
+    /**
+     * Determines if an item at the given index should be measured during smooth scroll.
+     * During smooth scroll, only items within a buffer range around the target are measured
+     * to prevent items far from the target from pushing it away.
+     */
+    private shouldMeasureDuringScroll;
+    measureElement: (node: TItemElement | null) => void;
     resizeItem: (index: number, size: number) => void;
-    measureElement: (node: TItemElement | null | undefined) => void;
     getVirtualItems: {
         (): VirtualItem[];
         updateDeps(newDeps: [number[], VirtualItem[]]): void;
@@ -137,9 +146,8 @@ export declare class Virtualizer<TScrollElement extends Element | Window, TItemE
     private getMaxScrollOffset;
     getOffsetForAlignment: (toOffset: number, align: ScrollAlignment, itemSize?: number) => number;
     getOffsetForIndex: (index: number, align?: ScrollAlignment) => readonly [number, "auto"] | readonly [number, "start" | "center" | "end"] | undefined;
-    private isDynamicMode;
     scrollToOffset: (toOffset: number, { align, behavior }?: ScrollToOffsetOptions) => void;
-    scrollToIndex: (index: number, { align: initialAlign, behavior }?: ScrollToIndexOptions) => void;
+    scrollToIndex: (index: number, { align: initialAlign, behavior, }?: ScrollToIndexOptions) => void;
     scrollBy: (delta: number, { behavior }?: ScrollToOffsetOptions) => void;
     getTotalSize: () => number;
     private _scrollToOffset;

package/dist/esm/index.d.ts

@@ -1,7 +1,7 @@
 export * from './utils.js';
 type ScrollDirection = 'forward' | 'backward';
 type ScrollAlignment = 'start' | 'center' | 'end' | 'auto';
-type ScrollBehavior = 'auto' | 'smooth';
+type ScrollBehavior = 'auto' | 'smooth' | 'instant';
 export interface ScrollToOptions {
     align?: ScrollAlignment;
     behavior?: ScrollBehavior;
@@ -83,7 +83,7 @@ export declare class Virtualizer<TScrollElement extends Element | Window, TItemE
     scrollElement: TScrollElement | null;
     targetWindow: (Window & typeof globalThis) | null;
     isScrolling: boolean;
-    private currentScrollToIndex;
+    private scrollState;
     measurementsCache: Array<VirtualItem>;
     private itemSizeCache;
     private laneAssignments;
@@ -97,6 +97,7 @@ export declare class Virtualizer<TScrollElement extends Element | Window, TItemE
     private scrollAdjustments;
     shouldAdjustScrollPositionOnItemSizeChange: undefined | ((item: VirtualItem, delta: number, instance: Virtualizer<TScrollElement, TItemElement>) => boolean);
     elementsCache: Map<Key, TItemElement>;
+    private now;
     private observer;
     range: {
         startIndex: number;
@@ -109,6 +110,9 @@ export declare class Virtualizer<TScrollElement extends Element | Window, TItemE
     private cleanup;
     _didMount: () => () => void;
     _willUpdate: () => void;
+    private rafId;
+    private scheduleScrollReconcile;
+    private reconcileScroll;
     private getSize;
     private getScrollOffset;
     private getFurthestMeasurement;
@@ -126,9 +130,14 @@ export declare class Virtualizer<TScrollElement extends Element | Window, TItemE
         updateDeps(newDeps: [(range: Range) => number[], number, number, number | null, number | null]): void;
     };
     indexFromElement: (node: TItemElement) => number;
-    private _measureElement;
+    /**
+     * Determines if an item at the given index should be measured during smooth scroll.
+     * During smooth scroll, only items within a buffer range around the target are measured
+     * to prevent items far from the target from pushing it away.
+     */
+    private shouldMeasureDuringScroll;
+    measureElement: (node: TItemElement | null) => void;
     resizeItem: (index: number, size: number) => void;
-    measureElement: (node: TItemElement | null | undefined) => void;
     getVirtualItems: {
         (): VirtualItem[];
         updateDeps(newDeps: [number[], VirtualItem[]]): void;
@@ -137,9 +146,8 @@ export declare class Virtualizer<TScrollElement extends Element | Window, TItemE
     private getMaxScrollOffset;
     getOffsetForAlignment: (toOffset: number, align: ScrollAlignment, itemSize?: number) => number;
     getOffsetForIndex: (index: number, align?: ScrollAlignment) => readonly [number, "auto"] | readonly [number, "start" | "center" | "end"] | undefined;
-    private isDynamicMode;
     scrollToOffset: (toOffset: number, { align, behavior }?: ScrollToOffsetOptions) => void;
-    scrollToIndex: (index: number, { align: initialAlign, behavior }?: ScrollToIndexOptions) => void;
+    scrollToIndex: (index: number, { align: initialAlign, behavior, }?: ScrollToIndexOptions) => void;
     scrollBy: (delta: number, { behavior }?: ScrollToOffsetOptions) => void;
     getTotalSize: () => number;
     private _scrollToOffset;

package/dist/esm/index.js

@@ -181,7 +181,7 @@ class Virtualizer {
     this.scrollElement = null;
     this.targetWindow = null;
     this.isScrolling = false;
-    this.currentScrollToIndex = null;
+    this.scrollState = null;
     this.measurementsCache = [];
     this.itemSizeCache = /* @__PURE__ */ new Map();
     this.laneAssignments = /* @__PURE__ */ new Map();
@@ -194,6 +194,10 @@ class Virtualizer {
     this.scrollDirection = null;
     this.scrollAdjustments = 0;
     this.elementsCache = /* @__PURE__ */ new Map();
+    this.now = () => {
+      var _a, _b, _c;
+      return ((_c = (_b = (_a = this.targetWindow) == null ? void 0 : _a.performance) == null ? void 0 : _b.now) == null ? void 0 : _c.call(_b)) ?? Date.now();
+    };
     this.observer = /* @__PURE__ */ (() => {
       let _ro = null;
       const get = () => {
@@ -206,7 +210,19 @@ class Virtualizer {
         return _ro = new this.targetWindow.ResizeObserver((entries) => {
           entries.forEach((entry) => {
             const run = () => {
-              this._measureElement(entry.target, entry);
+              const node = entry.target;
+              const index = this.indexFromElement(node);
+              if (!node.isConnected) {
+                this.observer.unobserve(node);
+                this.elementsCache.delete(this.options.getItemKey(index));
+                return;
+              }
+              if (this.shouldMeasureDuringScroll(index)) {
+                this.resizeItem(
+                  index,
+                  this.options.measureElement(node, entry, this)
+                );
+              }
             };
             this.options.useAnimationFrameWithResizeObserver ? requestAnimationFrame(run) : run();
           });
@@ -291,6 +307,11 @@ class Virtualizer {
       this.unsubs.filter(Boolean).forEach((d) => d());
       this.unsubs = [];
       this.observer.disconnect();
+      if (this.rafId != null && this.targetWindow) {
+        this.targetWindow.cancelAnimationFrame(this.rafId);
+        this.rafId = null;
+      }
+      this.scrollState = null;
       this.scrollElement = null;
       this.targetWindow = null;
     };
@@ -329,6 +350,9 @@ class Virtualizer {
             this.scrollDirection = isScrolling ? this.getScrollOffset() < offset ? "forward" : "backward" : null;
             this.scrollOffset = offset;
             this.isScrolling = isScrolling;
+            if (this.scrollState) {
+              this.scheduleScrollReconcile();
+            }
             this.maybeNotify();
           })
         );
@@ -338,6 +362,7 @@ class Virtualizer {
         });
       }
     };
+    this.rafId = null;
     this.getSize = () => {
       if (!this.options.enabled) {
         this.scrollRect = null;
@@ -556,17 +581,38 @@ class Virtualizer {
       }
       return parseInt(indexStr, 10);
     };
-    this._measureElement = (node, entry) => {
-      if (!node.isConnected) {
-        this.observer.unobserve(node);
-        return;
+    this.shouldMeasureDuringScroll = (index) => {
+      var _a;
+      if (!this.scrollState || this.scrollState.behavior !== "smooth") {
+        return true;
       }
-      const index = this.indexFromElement(node);
-      const item = this.measurementsCache[index];
-      if (!item) {
+      const scrollIndex = this.scrollState.index ?? ((_a = this.getVirtualItemForOffset(this.scrollState.lastTargetOffset)) == null ? void 0 : _a.index);
+      if (scrollIndex !== void 0 && this.range) {
+        const bufferSize = Math.max(
+          this.options.overscan,
+          Math.ceil((this.range.endIndex - this.range.startIndex) / 2)
+        );
+        const minIndex = Math.max(0, scrollIndex - bufferSize);
+        const maxIndex = Math.min(
+          this.options.count - 1,
+          scrollIndex + bufferSize
+        );
+        return index >= minIndex && index <= maxIndex;
+      }
+      return true;
+    };
+    this.measureElement = (node) => {
+      if (!node) {
+        this.elementsCache.forEach((cached, key2) => {
+          if (!cached.isConnected) {
+            this.observer.unobserve(cached);
+            this.elementsCache.delete(key2);
+          }
+        });
         return;
       }
-      const key = item.key;
+      const index = this.indexFromElement(node);
+      const key = this.options.getItemKey(index);
       const prevNode = this.elementsCache.get(key);
       if (prevNode !== node) {
         if (prevNode) {
@@ -575,17 +621,18 @@ class Virtualizer {
         this.observer.observe(node);
         this.elementsCache.set(key, node);
       }
-      this.resizeItem(index, this.options.measureElement(node, entry, this));
+      if ((!this.isScrolling || this.scrollState) && this.shouldMeasureDuringScroll(index)) {
+        this.resizeItem(index, this.options.measureElement(node, void 0, this));
+      }
     };
     this.resizeItem = (index, size) => {
+      var _a;
       const item = this.measurementsCache[index];
-      if (!item) {
-        return;
-      }
+      if (!item) return;
       const itemSize = this.itemSizeCache.get(item.key) ?? item.size;
       const delta = size - itemSize;
       if (delta !== 0) {
-        if (this.shouldAdjustScrollPositionOnItemSizeChange !== void 0 ? this.shouldAdjustScrollPositionOnItemSizeChange(item, delta, this) : item.start < this.getScrollOffset() + this.scrollAdjustments) {
+        if (((_a = this.scrollState) == null ? void 0 : _a.behavior) !== "smooth" && (this.shouldAdjustScrollPositionOnItemSizeChange !== void 0 ? this.shouldAdjustScrollPositionOnItemSizeChange(item, delta, this) : item.start < this.getScrollOffset() + this.scrollAdjustments)) {
           if (process.env.NODE_ENV !== "production" && this.options.debug) {
             console.info("correction", delta);
           }
@@ -599,18 +646,6 @@ class Virtualizer {
         this.notify(false);
       }
     };
-    this.measureElement = (node) => {
-      if (!node) {
-        this.elementsCache.forEach((cached, key) => {
-          if (!cached.isConnected) {
-            this.observer.unobserve(cached);
-            this.elementsCache.delete(key);
-          }
-        });
-        return;
-      }
-      this._measureElement(node, void 0);
-    };
     this.getVirtualItems = memo(
       () => [this.getVirtualIndexes(), this.getMeasurements()],
       (indexes, measurements) => {
@@ -667,12 +702,10 @@ class Virtualizer {
     };
     this.getOffsetForIndex = (index, align = "auto") => {
       index = Math.max(0, Math.min(index, this.options.count - 1));
-      const item = this.measurementsCache[index];
-      if (!item) {
-        return void 0;
-      }
       const size = this.getSize();
       const scrollOffset = this.getScrollOffset();
+      const item = this.measurementsCache[index];
+      if (!item) return;
       if (align === "auto") {
         if (item.end >= scrollOffset + size - this.options.scrollPaddingEnd) {
           align = "end";
@@ -691,85 +724,55 @@ class Virtualizer {
         align
       ];
     };
-    this.isDynamicMode = () => this.elementsCache.size > 0;
-    this.scrollToOffset = (toOffset, { align = "start", behavior } = {}) => {
-      if (behavior === "smooth" && this.isDynamicMode()) {
-        console.warn(
-          "The `smooth` scroll behavior is not fully supported with dynamic size."
-        );
-      }
-      this._scrollToOffset(this.getOffsetForAlignment(toOffset, align), {
-        adjustments: void 0,
-        behavior
-      });
+    this.scrollToOffset = (toOffset, { align = "start", behavior = "auto" } = {}) => {
+      const offset = this.getOffsetForAlignment(toOffset, align);
+      const now = this.now();
+      this.scrollState = {
+        index: null,
+        align,
+        behavior,
+        startedAt: now,
+        lastTargetOffset: offset,
+        stableFrames: 0
+      };
+      this._scrollToOffset(offset, { adjustments: void 0, behavior });
+      this.scheduleScrollReconcile();
     };
-    this.scrollToIndex = (index, { align: initialAlign = "auto", behavior } = {}) => {
-      if (behavior === "smooth" && this.isDynamicMode()) {
-        console.warn(
-          "The `smooth` scroll behavior is not fully supported with dynamic size."
-        );
-      }
+    this.scrollToIndex = (index, {
+      align: initialAlign = "auto",
+      behavior = "auto"
+    } = {}) => {
       index = Math.max(0, Math.min(index, this.options.count - 1));
-      this.currentScrollToIndex = index;
-      let attempts = 0;
-      const maxAttempts = 10;
-      const tryScroll = (currentAlign) => {
-        if (!this.targetWindow) return;
-        const offsetInfo = this.getOffsetForIndex(index, currentAlign);
-        if (!offsetInfo) {
-          console.warn("Failed to get offset for index:", index);
-          return;
-        }
-        const [offset, align] = offsetInfo;
-        this._scrollToOffset(offset, { adjustments: void 0, behavior });
-        this.targetWindow.requestAnimationFrame(() => {
-          if (!this.targetWindow) return;
-          const verify = () => {
-            if (this.currentScrollToIndex !== index) return;
-            const currentOffset = this.getScrollOffset();
-            const afterInfo = this.getOffsetForIndex(index, align);
-            if (!afterInfo) {
-              console.warn("Failed to get offset for index:", index);
-              return;
-            }
-            if (!approxEqual(afterInfo[0], currentOffset)) {
-              scheduleRetry(align);
-            }
-          };
-          if (this.isDynamicMode()) {
-            this.targetWindow.requestAnimationFrame(verify);
-          } else {
-            verify();
-          }
-        });
-      };
-      const scheduleRetry = (align) => {
-        if (!this.targetWindow) return;
-        if (this.currentScrollToIndex !== index) return;
-        attempts++;
-        if (attempts < maxAttempts) {
-          if (process.env.NODE_ENV !== "production" && this.options.debug) {
-            console.info("Schedule retry", attempts, maxAttempts);
-          }
-          this.targetWindow.requestAnimationFrame(() => tryScroll(align));
-        } else {
-          console.warn(
-            `Failed to scroll to index ${index} after ${maxAttempts} attempts.`
-          );
-        }
+      const offsetInfo = this.getOffsetForIndex(index, initialAlign);
+      if (!offsetInfo) {
+        return;
+      }
+      const [offset, align] = offsetInfo;
+      const now = this.now();
+      this.scrollState = {
+        index,
+        align,
+        behavior,
+        startedAt: now,
+        lastTargetOffset: offset,
+        stableFrames: 0
       };
-      tryScroll(initialAlign);
+      this._scrollToOffset(offset, { adjustments: void 0, behavior });
+      this.scheduleScrollReconcile();
     };
-    this.scrollBy = (delta, { behavior } = {}) => {
-      if (behavior === "smooth" && this.isDynamicMode()) {
-        console.warn(
-          "The `smooth` scroll behavior is not fully supported with dynamic size."
-        );
-      }
-      this._scrollToOffset(this.getScrollOffset() + delta, {
-        adjustments: void 0,
-        behavior
-      });
+    this.scrollBy = (delta, { behavior = "auto" } = {}) => {
+      const offset = this.getScrollOffset() + delta;
+      const now = this.now();
+      this.scrollState = {
+        index: null,
+        align: "start",
+        behavior,
+        startedAt: now,
+        lastTargetOffset: offset,
+        stableFrames: 0
+      };
+      this._scrollToOffset(offset, { adjustments: void 0, behavior });
+      this.scheduleScrollReconcile();
     };
     this.getTotalSize = () => {
       var _a;
@@ -809,6 +812,49 @@ class Virtualizer {
     };
     this.setOptions(opts);
   }
+  scheduleScrollReconcile() {
+    if (!this.targetWindow) {
+      this.scrollState = null;
+      return;
+    }
+    if (this.rafId != null) return;
+    this.rafId = this.targetWindow.requestAnimationFrame(() => {
+      this.rafId = null;
+      this.reconcileScroll();
+    });
+  }
+  reconcileScroll() {
+    if (!this.scrollState) return;
+    const el = this.scrollElement;
+    if (!el) return;
+    const MAX_RECONCILE_MS = 5e3;
+    if (this.now() - this.scrollState.startedAt > MAX_RECONCILE_MS) {
+      this.scrollState = null;
+      return;
+    }
+    const offsetInfo = this.scrollState.index != null ? this.getOffsetForIndex(this.scrollState.index, this.scrollState.align) : void 0;
+    const targetOffset = offsetInfo ? offsetInfo[0] : this.scrollState.lastTargetOffset;
+    const STABLE_FRAMES = 1;
+    const targetChanged = targetOffset !== this.scrollState.lastTargetOffset;
+    if (!targetChanged && approxEqual(targetOffset, this.getScrollOffset())) {
+      this.scrollState.stableFrames++;
+      if (this.scrollState.stableFrames >= STABLE_FRAMES) {
+        this.scrollState = null;
+        return;
+      }
+    } else {
+      this.scrollState.stableFrames = 0;
+      if (targetChanged) {
+        this.scrollState.lastTargetOffset = targetOffset;
+        this.scrollState.behavior = "auto";
+        this._scrollToOffset(targetOffset, {
+          adjustments: void 0,
+          behavior: "auto"
+        });
+      }
+    }
+    this.scheduleScrollReconcile();
+  }
 }
 const findNearestBinarySearch = (low, high, getCurrentValue, value) => {
   while (low <= high) {