@tanstack/virtual-core 3.0.0-beta.6 → 3.0.0-beta.61

package/src/index.ts

@@ -1,14 +1,18 @@
-import observeRect from '@reach/observe-rect'
-import { memo } from './utils'
+import { approxEqual, memo, notUndefined } from './utils'
 
 export * from './utils'
 
 //
 
+type ScrollDirection = 'forward' | 'backward'
+
 type ScrollAlignment = 'start' | 'center' | 'end' | 'auto'
 
-interface ScrollToOptions {
-  align: ScrollAlignment
+type ScrollBehavior = 'auto' | 'smooth'
+
+export interface ScrollToOptions {
+  align?: ScrollAlignment
+  behavior?: ScrollBehavior
 }
 
 type ScrollToOffsetOptions = ScrollToOptions
@@ -24,12 +28,13 @@ export interface Range {
 
 type Key = number | string
 
-interface Item {
+export interface VirtualItem {
   key: Key
   index: number
   start: number
   end: number
   size: number
+  lane: number
 }
 
 interface Rect {
@@ -37,10 +42,6 @@ interface Rect {
   height: number
 }
 
-export interface VirtualItem<TItemElement> extends Item {
-  measureElement: (el: TItemElement | null) => void
-}
-
 //
 
 export const defaultKeyExtractor = (index: number) => index
@@ -58,152 +59,176 @@ export const defaultRangeExtractor = (range: Range) => {
   return arr
 }
 
-export const observeElementRect = (
-  instance: Virtualizer<any, any>,
+export const observeElementRect = <T extends Element>(
+  instance: Virtualizer<T, any>,
   cb: (rect: Rect) => void,
 ) => {
-  const observer = observeRect(instance.scrollElement as Element, (rect) => {
-    cb(rect)
-  })
-
-  if (!instance.scrollElement) {
+  const element = instance.scrollElement
+  if (!element) {
     return
   }
 
-  cb(instance.scrollElement.getBoundingClientRect())
+  const handler = (rect: Rect) => {
+    const { width, height } = rect
+    cb({ width: Math.round(width), height: Math.round(height) })
+  }
+
+  handler(element.getBoundingClientRect())
 
-  observer.observe()
+  const observer = new ResizeObserver((entries) => {
+    const entry = entries[0]
+    if (entry?.borderBoxSize) {
+      const box = entry.borderBoxSize[0]
+      if (box) {
+        handler({ width: box.inlineSize, height: box.blockSize })
+        return
+      }
+    }
+    handler(element.getBoundingClientRect())
+  })
+
+  observer.observe(element, { box: 'border-box' })
 
   return () => {
-    observer.unobserve()
+    observer.unobserve(element)
   }
 }
 
 export const observeWindowRect = (
-  instance: Virtualizer<any, any>,
+  instance: Virtualizer<Window, any>,
   cb: (rect: Rect) => void,
 ) => {
-  const onResize = () => {
-    cb({
-      width: instance.scrollElement.innerWidth,
-      height: instance.scrollElement.innerHeight,
-    })
-  }
-
-  if (!instance.scrollElement) {
+  const element = instance.scrollElement
+  if (!element) {
     return
   }
 
-  onResize()
+  const handler = () => {
+    cb({ width: element.innerWidth, height: element.innerHeight })
+  }
+  handler()
 
-  instance.scrollElement.addEventListener('resize', onResize, {
-    capture: false,
+  element.addEventListener('resize', handler, {
     passive: true,
   })
 
   return () => {
-    instance.scrollElement.removeEventListener('resize', onResize)
+    element.removeEventListener('resize', handler)
   }
 }
 
-export const observeElementOffset = (
-  instance: Virtualizer<any, any>,
+export const observeElementOffset = <T extends Element>(
+  instance: Virtualizer<T, any>,
   cb: (offset: number) => void,
 ) => {
-  const onScroll = () =>
-    cb(
-      instance.scrollElement[
-        instance.options.horizontal ? 'scrollLeft' : 'scrollTop'
-      ],
-    )
-
-  if (!instance.scrollElement) {
+  const element = instance.scrollElement
+  if (!element) {
     return
   }
 
-  onScroll()
+  const handler = () => {
+    cb(element[instance.options.horizontal ? 'scrollLeft' : 'scrollTop'])
+  }
+  handler()
 
-  instance.scrollElement.addEventListener('scroll', onScroll, {
-    capture: false,
+  element.addEventListener('scroll', handler, {
     passive: true,
   })
 
   return () => {
-    instance.scrollElement.removeEventListener('scroll', onScroll)
+    element.removeEventListener('scroll', handler)
   }
 }
 
 export const observeWindowOffset = (
-  instance: Virtualizer<any, any>,
+  instance: Virtualizer<Window, any>,
   cb: (offset: number) => void,
 ) => {
-  const onScroll = () =>
-    cb(
-      instance.scrollElement[
-        instance.options.horizontal ? 'scrollX' : 'scrollY'
-      ],
-    )
-
-  if (!instance.scrollElement) {
+  const element = instance.scrollElement
+  if (!element) {
     return
   }
 
-  onScroll()
+  const handler = () => {
+    cb(element[instance.options.horizontal ? 'scrollX' : 'scrollY'])
+  }
+  handler()
 
-  instance.scrollElement.addEventListener('scroll', onScroll, {
-    capture: false,
+  element.addEventListener('scroll', handler, {
     passive: true,
   })
 
   return () => {
-    instance.scrollElement.removeEventListener('scroll', onScroll)
+    element.removeEventListener('scroll', handler)
   }
 }
 
-export const measureElement = (
-  element: unknown,
-  instance: Virtualizer<any, any>,
+export const measureElement = <TItemElement extends Element>(
+  element: TItemElement,
+  entry: ResizeObserverEntry | undefined,
+  instance: Virtualizer<any, TItemElement>,
 ) => {
-  return (element as Element).getBoundingClientRect()[
-    instance.options.horizontal ? 'width' : 'height'
-  ]
+  if (entry?.borderBoxSize) {
+    const box = entry.borderBoxSize[0]
+    if (box) {
+      const size = Math.round(
+        box[instance.options.horizontal ? 'inlineSize' : 'blockSize'],
+      )
+      return size
+    }
+  }
+  return Math.round(
+    element.getBoundingClientRect()[
+      instance.options.horizontal ? 'width' : 'height'
+    ],
+  )
 }
 
-export const windowScroll = (
+export const windowScroll = <T extends Window>(
   offset: number,
-  canSmooth: boolean,
-  instance: Virtualizer<any, any>,
+  {
+    adjustments = 0,
+    behavior,
+  }: { adjustments?: number; behavior?: ScrollBehavior },
+  instance: Virtualizer<T, any>,
 ) => {
-  ;(instance.scrollElement as Window)?.scrollTo({
-    [instance.options.horizontal ? 'left' : 'top']: offset,
-    behavior: canSmooth ? 'smooth' : undefined,
+  const toOffset = offset + adjustments
+
+  instance.scrollElement?.scrollTo?.({
+    [instance.options.horizontal ? 'left' : 'top']: toOffset,
+    behavior,
   })
 }
 
-export const elementScroll = (
+export const elementScroll = <T extends Element>(
   offset: number,
-  canSmooth: boolean,
-  instance: Virtualizer<any, any>,
+  {
+    adjustments = 0,
+    behavior,
+  }: { adjustments?: number; behavior?: ScrollBehavior },
+  instance: Virtualizer<T, any>,
 ) => {
-  ;(instance.scrollElement as Element)?.scrollTo({
-    [instance.options.horizontal ? 'left' : 'top']: offset,
-    behavior: canSmooth ? 'smooth' : undefined,
+  const toOffset = offset + adjustments
+
+  instance.scrollElement?.scrollTo?.({
+    [instance.options.horizontal ? 'left' : 'top']: toOffset,
+    behavior,
   })
 }
 
 export interface VirtualizerOptions<
-  TScrollElement = unknown,
-  TItemElement = unknown,
+  TScrollElement extends Element | Window,
+  TItemElement extends Element,
 > {
   // Required from the user
   count: number
-  getScrollElement: () => TScrollElement
+  getScrollElement: () => TScrollElement | null
   estimateSize: (index: number) => number
 
   // Required from the framework adapter (but can be overridden)
   scrollToFn: (
     offset: number,
-    canSmooth: boolean,
+    options: { adjustments?: number; behavior?: ScrollBehavior },
     instance: Virtualizer<TScrollElement, TItemElement>,
   ) => void
   observeElementRect: (
@@ -220,7 +245,8 @@ export interface VirtualizerOptions<
   initialRect?: Rect
   onChange?: (instance: Virtualizer<TScrollElement, TItemElement>) => void
   measureElement?: (
-    el: TItemElement,
+    element: TItemElement,
+    entry: ResizeObserverEntry | undefined,
     instance: Virtualizer<TScrollElement, TItemElement>,
   ) => number
   overscan?: number
@@ -232,29 +258,70 @@ export interface VirtualizerOptions<
   initialOffset?: number
   getItemKey?: (index: number) => Key
   rangeExtractor?: (range: Range) => number[]
-  enableSmoothScroll?: boolean
+  scrollMargin?: number
+  scrollingDelay?: number
+  indexAttribute?: string
+  initialMeasurementsCache?: VirtualItem[]
+  lanes?: number
 }
 
-export class Virtualizer<TScrollElement = unknown, TItemElement = unknown> {
+export class Virtualizer<
+  TScrollElement extends Element | Window,
+  TItemElement extends Element,
+> {
   private unsubs: (void | (() => void))[] = []
   options!: Required<VirtualizerOptions<TScrollElement, TItemElement>>
   scrollElement: TScrollElement | null = null
-  private measurementsCache: Item[] = []
-  private itemMeasurementsCache: Record<Key, number> = {}
+  isScrolling: boolean = false
+  private isScrollingTimeoutId: ReturnType<typeof setTimeout> | null = null
+  private scrollToIndexTimeoutId: ReturnType<typeof setTimeout> | null = null
+  measurementsCache: VirtualItem[] = []
+  private itemSizeCache = new Map<Key, number>()
   private pendingMeasuredCacheIndexes: number[] = []
   private scrollRect: Rect
-  private scrollOffset: number
-  private destinationOffset: undefined | number
-  private scrollCheckFrame!: ReturnType<typeof setTimeout>
-  private measureElementCache: Record<
-    number,
-    (measurableItem: TItemElement | null) => void
-  > = {}
+  scrollOffset: number
+  scrollDirection: ScrollDirection | null = null
+  private scrollAdjustments: number = 0
+  measureElementCache = new Map<Key, TItemElement>()
+  private observer = (() => {
+    let _ro: ResizeObserver | null = null
+
+    const get = () => {
+      if (_ro) {
+        return _ro
+      } else if (typeof ResizeObserver !== 'undefined') {
+        return (_ro = new ResizeObserver((entries) => {
+          entries.forEach((entry) => {
+            this._measureElement(entry.target as TItemElement, entry)
+          })
+        }))
+      } else {
+        return null
+      }
+    }
+
+    return {
+      disconnect: () => get()?.disconnect(),
+      observe: (target: Element) =>
+        get()?.observe(target, { box: 'border-box' }),
+      unobserve: (target: Element) => get()?.unobserve(target),
+    }
+  })()
+  range: { startIndex: number; endIndex: number } = {
+    startIndex: 0,
+    endIndex: 0,
+  }
 
   constructor(opts: VirtualizerOptions<TScrollElement, TItemElement>) {
     this.setOptions(opts)
     this.scrollRect = this.options.initialRect
     this.scrollOffset = this.options.initialOffset
+    this.measurementsCache = this.options.initialMeasurementsCache
+    this.measurementsCache.forEach((item) => {
+      this.itemSizeCache.set(item.key, item.size)
+    })
+
+    this.maybeNotify()
   }
 
   setOptions = (opts: VirtualizerOptions<TScrollElement, TItemElement>) => {
@@ -273,10 +340,14 @@ export class Virtualizer<TScrollElement = unknown, TItemElement = unknown> {
       horizontal: false,
       getItemKey: defaultKeyExtractor,
       rangeExtractor: defaultRangeExtractor,
-      enableSmoothScroll: true,
       onChange: () => {},
       measureElement,
       initialRect: { width: 0, height: 0 },
+      scrollMargin: 0,
+      scrollingDelay: 150,
+      indexAttribute: 'data-index',
+      initialMeasurementsCache: [],
+      lanes: 1,
       ...opts,
     }
   }
@@ -288,10 +359,13 @@ export class Virtualizer<TScrollElement = unknown, TItemElement = unknown> {
   private cleanup = () => {
     this.unsubs.filter(Boolean).forEach((d) => d!())
     this.unsubs = []
+    this.scrollElement = null
   }
 
   _didMount = () => {
+    this.measureElementCache.forEach(this.observer.observe)
     return () => {
+      this.observer.disconnect()
       this.cleanup()
     }
   }
@@ -304,17 +378,52 @@ export class Virtualizer<TScrollElement = unknown, TItemElement = unknown> {
 
       this.scrollElement = scrollElement
 
+      this._scrollToOffset(this.scrollOffset, {
+        adjustments: undefined,
+        behavior: undefined,
+      })
+
       this.unsubs.push(
         this.options.observeElementRect(this, (rect) => {
+          const prev = this.scrollRect
           this.scrollRect = rect
-          this.notify()
+          if (
+            this.options.horizontal
+              ? rect.width !== prev.width
+              : rect.height !== prev.height
+          ) {
+            this.maybeNotify()
+          }
         }),
       )
 
       this.unsubs.push(
         this.options.observeElementOffset(this, (offset) => {
+          this.scrollAdjustments = 0
+
+          if (this.scrollOffset === offset) {
+            return
+          }
+
+          if (this.isScrollingTimeoutId !== null) {
+            clearTimeout(this.isScrollingTimeoutId)
+            this.isScrollingTimeoutId = null
+          }
+
+          this.isScrolling = true
+          this.scrollDirection =
+            this.scrollOffset < offset ? 'forward' : 'backward'
           this.scrollOffset = offset
-          this.notify()
+
+          this.maybeNotify()
+
+          this.isScrollingTimeoutId = setTimeout(() => {
+            this.isScrollingTimeoutId = null
+            this.isScrolling = false
+            this.scrollDirection = null
+
+            this.maybeNotify()
+          }, this.options.scrollingDelay)
         }),
       )
     }
@@ -324,14 +433,67 @@ export class Virtualizer<TScrollElement = unknown, TItemElement = unknown> {
     return this.scrollRect[this.options.horizontal ? 'width' : 'height']
   }
 
-  private getMeasurements = memo(
+  private memoOptions = memo(
     () => [
       this.options.count,
       this.options.paddingStart,
+      this.options.scrollMargin,
       this.options.getItemKey,
-      this.itemMeasurementsCache,
     ],
-    (count, paddingStart, getItemKey, measurementsCache) => {
+    (count, paddingStart, scrollMargin, getItemKey) => {
+      this.pendingMeasuredCacheIndexes = []
+      return {
+        count,
+        paddingStart,
+        scrollMargin,
+        getItemKey,
+      }
+    },
+    {
+      key: false,
+    },
+  )
+
+  private getFurthestMeasurement = (
+    measurements: VirtualItem[],
+    index: number,
+  ) => {
+    const furthestMeasurementsFound = new Map<number, true>()
+    const furthestMeasurements = new Map<number, VirtualItem>()
+    for (let m = index - 1; m >= 0; m--) {
+      const measurement = measurements[m]!
+
+      if (furthestMeasurementsFound.has(measurement.lane)) {
+        continue
+      }
+
+      const previousFurthestMeasurement = furthestMeasurements.get(
+        measurement.lane,
+      )
+      if (
+        previousFurthestMeasurement == null ||
+        measurement.end > previousFurthestMeasurement.end
+      ) {
+        furthestMeasurements.set(measurement.lane, measurement)
+      } else if (measurement.end < previousFurthestMeasurement.end) {
+        furthestMeasurementsFound.set(measurement.lane, true)
+      }
+
+      if (furthestMeasurementsFound.size === this.options.lanes) {
+        break
+      }
+    }
+
+    return furthestMeasurements.size === this.options.lanes
+      ? Array.from(furthestMeasurements.values()).sort(
+          (a, b) => a.end - b.end,
+        )[0]
+      : undefined
+  }
+
+  private getMeasurements = memo(
+    () => [this.memoOptions(), this.itemSizeCache],
+    ({ count, paddingStart, scrollMargin, getItemKey }, itemSizeCache) => {
       const min =
         this.pendingMeasuredCacheIndexes.length > 0
           ? Math.min(...this.pendingMeasuredCacheIndexes)
@@ -342,42 +504,83 @@ export class Virtualizer<TScrollElement = unknown, TItemElement = unknown> {
 
       for (let i = min; i < count; i++) {
         const key = getItemKey(i)
-        const measuredSize = measurementsCache[key]
-        const start = measurements[i - 1]
-          ? measurements[i - 1]!.end
-          : paddingStart
+
+        const furthestMeasurement =
+          this.options.lanes === 1
+            ? measurements[i - 1]
+            : this.getFurthestMeasurement(measurements, i)
+
+        const start = furthestMeasurement
+          ? furthestMeasurement.end
+          : paddingStart + scrollMargin
+
+        const measuredSize = itemSizeCache.get(key)
         const size =
           typeof measuredSize === 'number'
             ? measuredSize
             : this.options.estimateSize(i)
+
         const end = start + size
-        measurements[i] = { index: i, start, size, end, key }
+
+        const lane = furthestMeasurement
+          ? furthestMeasurement.lane
+          : i % this.options.lanes
+
+        measurements[i] = {
+          index: i,
+          start,
+          size,
+          end,
+          key,
+          lane,
+        }
       }
 
       this.measurementsCache = measurements
+
       return measurements
     },
     {
-      key: process.env.NODE_ENV === 'development' && 'getMeasurements',
+      key: process.env.NODE_ENV !== 'production' && 'getMeasurements',
       debug: () => this.options.debug,
     },
   )
 
-  private calculateRange = memo(
+  calculateRange = memo(
     () => [this.getMeasurements(), this.getSize(), this.scrollOffset],
     (measurements, outerSize, scrollOffset) => {
-      return calculateRange({
+      return (this.range = calculateRange({
         measurements,
         outerSize,
         scrollOffset,
-      })
+      }))
     },
     {
-      key: process.env.NODE_ENV === 'development' && 'calculateRange',
+      key: process.env.NODE_ENV !== 'production' && 'calculateRange',
       debug: () => this.options.debug,
     },
   )
 
+  private maybeNotify = memo(
+    () => {
+      const range = this.calculateRange()
+
+      return [range.startIndex, range.endIndex, this.isScrolling]
+    },
+    () => {
+      this.notify()
+    },
+    {
+      key: process.env.NODE_ENV !== 'production' && 'maybeNotify',
+      debug: () => this.options.debug,
+      initialDeps: [
+        this.range.startIndex,
+        this.range.endIndex,
+        this.isScrolling,
+      ],
+    },
+  )
+
   private getIndexes = memo(
     () => [
       this.options.rangeExtractor,
@@ -389,141 +592,186 @@ export class Virtualizer<TScrollElement = unknown, TItemElement = unknown> {
       return rangeExtractor({
         ...range,
         overscan,
-        count: count,
+        count,
       })
     },
     {
-      key: process.env.NODE_ENV === 'development' && 'getIndexes',
+      key: process.env.NODE_ENV !== 'production' && 'getIndexes',
+      debug: () => this.options.debug,
     },
   )
 
-  getVirtualItems = memo(
-    () => [
-      this.getIndexes(),
-      this.getMeasurements(),
-      this.options.measureElement,
-    ],
-    (indexes, measurements, measureElement) => {
-      const makeMeasureElement =
-        (index: number) => (measurableItem: TItemElement | null) => {
-          const item = this.measurementsCache[index]!
+  indexFromElement = (node: TItemElement) => {
+    const attributeName = this.options.indexAttribute
+    const indexStr = node.getAttribute(attributeName)
 
-          if (!measurableItem) {
-            return
-          }
+    if (!indexStr) {
+      console.warn(
+        `Missing attribute name '${attributeName}={index}' on measured element.`,
+      )
+      return -1
+    }
 
-          const measuredItemSize = measureElement(measurableItem, this)
-          const itemSize = this.itemMeasurementsCache[item.key] ?? item.size
-
-          if (measuredItemSize !== itemSize) {
-            if (item.start < this.scrollOffset) {
-              if (
-                process.env.NODE_ENV === 'development' &&
-                this.options.debug
-              ) {
-                console.info('correction', measuredItemSize - itemSize)
-              }
-
-              if (!this.destinationOffset) {
-                this._scrollToOffset(
-                  this.scrollOffset + (measuredItemSize - itemSize),
-                  false,
-                )
-              }
-            }
-
-            this.pendingMeasuredCacheIndexes.push(index)
-            this.itemMeasurementsCache = {
-              ...this.itemMeasurementsCache,
-              [item.key]: measuredItemSize,
-            }
-            this.notify()
-          }
+    return parseInt(indexStr, 10)
+  }
+
+  private _measureElement = (
+    node: TItemElement,
+    entry: ResizeObserverEntry | undefined,
+  ) => {
+    const item = this.measurementsCache[this.indexFromElement(node)]
+    if (!item) {
+      this.measureElementCache.forEach((cached, key) => {
+        if (cached === node) {
+          this.observer.unobserve(node)
+          this.measureElementCache.delete(key)
+        }
+      })
+      return
+    }
+
+    const prevNode = this.measureElementCache.get(item.key)
+
+    if (!node.isConnected) {
+      if (prevNode) {
+        this.observer.unobserve(prevNode)
+        this.measureElementCache.delete(item.key)
+      }
+      return
+    }
+
+    if (prevNode !== node) {
+      if (prevNode) {
+        this.observer.unobserve(prevNode)
+      }
+      this.observer.observe(node)
+      this.measureElementCache.set(item.key, node)
+    }
+
+    const measuredItemSize = this.options.measureElement(node, entry, this)
+
+    this.resizeItem(item, measuredItemSize)
+  }
+
+  resizeItem = (item: VirtualItem, size: number) => {
+    const itemSize = this.itemSizeCache.get(item.key) ?? item.size
+    const delta = size - itemSize
+
+    if (delta !== 0) {
+      if (item.start < this.scrollOffset) {
+        if (process.env.NODE_ENV !== 'production' && this.options.debug) {
+          console.info('correction', delta)
         }
 
-      const virtualItems: VirtualItem<TItemElement>[] = []
+        this._scrollToOffset(this.scrollOffset, {
+          adjustments: (this.scrollAdjustments += delta),
+          behavior: undefined,
+        })
+      }
+
+      this.pendingMeasuredCacheIndexes.push(item.index)
+      this.itemSizeCache = new Map(this.itemSizeCache.set(item.key, size))
+
+      this.notify()
+    }
+  }
 
-      const currentMeasureElements: typeof this.measureElementCache = {}
+  measureElement = (node: TItemElement | null) => {
+    if (!node) {
+      return
+    }
+
+    this._measureElement(node, undefined)
+  }
+
+  getVirtualItems = memo(
+    () => [this.getIndexes(), this.getMeasurements()],
+    (indexes, measurements) => {
+      const virtualItems: VirtualItem[] = []
 
       for (let k = 0, len = indexes.length; k < len; k++) {
         const i = indexes[k]!
         const measurement = measurements[i]!
 
-        const item = {
-          ...measurement,
-          measureElement: (currentMeasureElements[i] =
-            this.measureElementCache[i] ?? makeMeasureElement(i)),
-        }
-        virtualItems.push(item)
+        virtualItems.push(measurement)
       }
 
-      this.measureElementCache = currentMeasureElements
-
       return virtualItems
     },
     {
-      key: process.env.NODE_ENV === 'development' && 'getIndexes',
+      key: process.env.NODE_ENV !== 'production' && 'getIndexes',
+      debug: () => this.options.debug,
     },
   )
 
-  scrollToOffset = (
-    toOffset: number,
-    { align }: ScrollToOffsetOptions = { align: 'start' },
-  ) => {
-    const attempt = () => {
-      const offset = this.scrollOffset
-      const size = this.getSize()
-
-      if (align === 'auto') {
-        if (toOffset <= offset) {
-          align = 'start'
-        } else if (toOffset >= offset + size) {
-          align = 'end'
-        } else {
-          align = 'start'
-        }
-      }
-
-      if (align === 'start') {
-        this._scrollToOffset(toOffset, true)
-      } else if (align === 'end') {
-        this._scrollToOffset(toOffset - size, true)
-      } else if (align === 'center') {
-        this._scrollToOffset(toOffset - size / 2, true)
-      }
-    }
+  getVirtualItemForOffset = (offset: number) => {
+    const measurements = this.getMeasurements()
 
-    attempt()
-    requestAnimationFrame(() => {
-      attempt()
-    })
+    return notUndefined(
+      measurements[
+        findNearestBinarySearch(
+          0,
+          measurements.length - 1,
+          (index: number) => notUndefined(measurements[index]).start,
+          offset,
+        )
+      ],
+    )
   }
 
-  scrollToIndex = (
-    index: number,
-    { align, ...rest }: ScrollToIndexOptions = { align: 'auto' },
-  ) => {
-    const measurements = this.getMeasurements()
-    const offset = this.scrollOffset
+  getOffsetForAlignment = (toOffset: number, align: ScrollAlignment) => {
     const size = this.getSize()
-    const { count } = this.options
 
-    const measurement = measurements[Math.max(0, Math.min(index, count - 1))]
+    if (align === 'auto') {
+      if (toOffset <= this.scrollOffset) {
+        align = 'start'
+      } else if (toOffset >= this.scrollOffset + size) {
+        align = 'end'
+      } else {
+        align = 'start'
+      }
+    }
 
-    if (!measurement) {
-      return
+    if (align === 'start') {
+      toOffset = toOffset
+    } else if (align === 'end') {
+      toOffset = toOffset - size
+    } else if (align === 'center') {
+      toOffset = toOffset - size / 2
     }
 
+    const scrollSizeProp = this.options.horizontal
+      ? 'scrollWidth'
+      : 'scrollHeight'
+    const scrollSize = this.scrollElement
+      ? 'document' in this.scrollElement
+        ? this.scrollElement.document.documentElement[scrollSizeProp]
+        : this.scrollElement[scrollSizeProp]
+      : 0
+
+    const maxOffset = scrollSize - this.getSize()
+
+    return Math.max(Math.min(maxOffset, toOffset), 0)
+  }
+
+  getOffsetForIndex = (index: number, align: ScrollAlignment = 'auto') => {
+    index = Math.max(0, Math.min(index, this.options.count - 1))
+
+    const measurement = notUndefined(this.getMeasurements()[index])
+
     if (align === 'auto') {
-      if (measurement.end >= offset + size - this.options.scrollPaddingEnd) {
+      if (
+        measurement.end >=
+        this.scrollOffset + this.getSize() - this.options.scrollPaddingEnd
+      ) {
         align = 'end'
       } else if (
         measurement.start <=
-        offset + this.options.scrollPaddingStart
+        this.scrollOffset + this.options.scrollPaddingStart
       ) {
         align = 'start'
       } else {
-        return
+        return [this.scrollOffset, align] as const
       }
     }
 
@@ -532,46 +780,111 @@ export class Virtualizer<TScrollElement = unknown, TItemElement = unknown> {
         ? measurement.end + this.options.scrollPaddingEnd
         : measurement.start - this.options.scrollPaddingStart
 
-    this.scrollToOffset(toOffset, { align, ...rest })
+    return [this.getOffsetForAlignment(toOffset, align), align] as const
   }
 
-  getTotalSize = () =>
-    (this.getMeasurements()[this.options.count - 1]?.end ||
-      this.options.paddingStart) + this.options.paddingEnd
+  private isDynamicMode = () => this.measureElementCache.size > 0
 
-  private _scrollToOffset = (offset: number, canSmooth: boolean) => {
-    clearTimeout(this.scrollCheckFrame)
+  private cancelScrollToIndex = () => {
+    if (this.scrollToIndexTimeoutId !== null) {
+      clearTimeout(this.scrollToIndexTimeoutId)
+      this.scrollToIndexTimeoutId = null
+    }
+  }
 
-    this.destinationOffset = offset
-    this.options.scrollToFn(
-      offset,
-      this.options.enableSmoothScroll && canSmooth,
-      this,
-    )
+  scrollToOffset = (
+    toOffset: number,
+    { align = 'start', behavior }: ScrollToOffsetOptions = {},
+  ) => {
+    this.cancelScrollToIndex()
 
-    let scrollCheckFrame: ReturnType<typeof setTimeout>
+    if (behavior === 'smooth' && this.isDynamicMode()) {
+      console.warn(
+        'The `smooth` scroll behavior is not fully supported with dynamic size.',
+      )
+    }
 
-    const check = () => {
-      let lastOffset = this.scrollOffset
-      this.scrollCheckFrame = scrollCheckFrame = setTimeout(() => {
-        if (this.scrollCheckFrame !== scrollCheckFrame) {
-          return
-        }
+    this._scrollToOffset(this.getOffsetForAlignment(toOffset, align), {
+      adjustments: undefined,
+      behavior,
+    })
+  }
+
+  scrollToIndex = (
+    index: number,
+    { align: initialAlign = 'auto', behavior }: ScrollToIndexOptions = {},
+  ) => {
+    index = Math.max(0, Math.min(index, this.options.count - 1))
+
+    this.cancelScrollToIndex()
 
-        if (this.scrollOffset === lastOffset) {
-          this.destinationOffset = undefined
-          return
+    if (behavior === 'smooth' && this.isDynamicMode()) {
+      console.warn(
+        'The `smooth` scroll behavior is not fully supported with dynamic size.',
+      )
+    }
+
+    const [toOffset, align] = this.getOffsetForIndex(index, initialAlign)
+
+    this._scrollToOffset(toOffset, { adjustments: undefined, behavior })
+
+    if (behavior !== 'smooth' && this.isDynamicMode()) {
+      this.scrollToIndexTimeoutId = setTimeout(() => {
+        this.scrollToIndexTimeoutId = null
+
+        const elementInDOM = this.measureElementCache.has(
+          this.options.getItemKey(index),
+        )
+
+        if (elementInDOM) {
+          const [toOffset] = this.getOffsetForIndex(index, align)
+
+          if (!approxEqual(toOffset, this.scrollOffset)) {
+            this.scrollToIndex(index, { align, behavior })
+          }
+        } else {
+          this.scrollToIndex(index, { align, behavior })
         }
-        lastOffset = this.scrollOffset
-        check()
-      }, 100)
+      })
+    }
+  }
+
+  scrollBy = (delta: number, { behavior }: ScrollToOffsetOptions = {}) => {
+    this.cancelScrollToIndex()
+
+    if (behavior === 'smooth' && this.isDynamicMode()) {
+      console.warn(
+        'The `smooth` scroll behavior is not fully supported with dynamic size.',
+      )
     }
 
-    check()
+    this._scrollToOffset(this.scrollOffset + delta, {
+      adjustments: undefined,
+      behavior,
+    })
+  }
+
+  getTotalSize = () =>
+    (this.getMeasurements()[this.options.count - 1]?.end ||
+      this.options.paddingStart) -
+    this.options.scrollMargin +
+    this.options.paddingEnd
+
+  private _scrollToOffset = (
+    offset: number,
+    {
+      adjustments,
+      behavior,
+    }: {
+      adjustments: number | undefined
+      behavior: ScrollBehavior | undefined
+    },
+  ) => {
+    this.options.scrollToFn(offset, { behavior, adjustments }, this)
   }
 
   measure = () => {
-    this.itemMeasurementsCache = {}
+    this.itemSizeCache = new Map()
     this.notify()
   }
 }
@@ -607,7 +920,7 @@ function calculateRange({
   outerSize,
   scrollOffset,
 }: {
-  measurements: Item[]
+  measurements: VirtualItem[]
   outerSize: number
   scrollOffset: number
 }) {