@tanstack/virtual-core 3.0.0-beta.2 → 3.0.0-beta.21

package/src/index.ts

@@ -1,4 +1,3 @@
-import observeRect from '@reach/observe-rect'
 import { memo } from './utils'
 
 export * from './utils'
@@ -7,8 +6,9 @@ export * from './utils'
 
 type ScrollAlignment = 'start' | 'center' | 'end' | 'auto'
 
-interface ScrollToOptions {
-  align: ScrollAlignment
+export interface ScrollToOptions {
+  align?: ScrollAlignment
+  smoothScroll?: boolean
 }
 
 type ScrollToOffsetOptions = ScrollToOptions
@@ -24,7 +24,7 @@ export interface Range {
 
 type Key = number | string
 
-interface Item {
+export interface VirtualItem {
   key: Key
   index: number
   start: number
@@ -37,10 +37,6 @@ interface Rect {
   height: number
 }
 
-export interface VirtualItem<TItemElement> extends Item {
-  measureElement: (el: TItemElement | null) => void
-}
-
 //
 
 export const defaultKeyExtractor = (index: number) => index
@@ -58,12 +54,34 @@ export const defaultRangeExtractor = (range: Range) => {
   return arr
 }
 
+const memoRectCallback = (
+  instance: Virtualizer<any, any>,
+  cb: (rect: Rect) => void,
+) => {
+  let prev: Rect = { height: -1, width: -1 }
+
+  return (rect: Rect) => {
+    if (
+      instance.options.horizontal
+        ? rect.width !== prev.width
+        : rect.height !== prev.height
+    ) {
+      cb(rect)
+    }
+
+    prev = rect
+  }
+}
+
 export const observeElementRect = (
   instance: Virtualizer<any, any>,
   cb: (rect: Rect) => void,
 ) => {
-  const observer = observeRect(instance.scrollElement as Element, (rect) => {
-    cb(rect)
+  const observer = new ResizeObserver((entries) => {
+    cb({
+      width: entries[0]?.contentRect.width as number,
+      height: entries[0]?.contentRect.height as number,
+    })
   })
 
   if (!instance.scrollElement) {
@@ -72,10 +90,10 @@ export const observeElementRect = (
 
   cb(instance.scrollElement.getBoundingClientRect())
 
-  observer.observe()
+  observer.observe(instance.scrollElement)
 
   return () => {
-    observer.unobserve()
+    observer.unobserve(instance.scrollElement)
   }
 }
 
@@ -83,12 +101,12 @@ export const observeWindowRect = (
   instance: Virtualizer<any, any>,
   cb: (rect: Rect) => void,
 ) => {
-  const onResize = () => {
-    cb({
+  const memoizedCallback = memoRectCallback(instance, cb)
+  const onResize = () =>
+    memoizedCallback({
       width: instance.scrollElement.innerWidth,
       height: instance.scrollElement.innerHeight,
     })
-  }
 
   if (!instance.scrollElement) {
     return
@@ -106,104 +124,111 @@ export const observeWindowRect = (
   }
 }
 
-export const observeElementOffset = (
-  instance: Virtualizer<any, any>,
-  cb: (offset: number) => void,
-) => {
-  const onScroll = () =>
-    cb(
-      instance.scrollElement[
-        instance.options.horizontal ? 'scrollLeft' : 'scrollTop'
-      ],
-    )
+type ObserverMode = 'element' | 'window'
 
-  if (!instance.scrollElement) {
-    return
-  }
+const scrollProps = {
+  element: ['scrollLeft', 'scrollTop'],
+  window: ['scrollX', 'scrollY'],
+} as const
 
-  onScroll()
+const createOffsetObserver = (mode: ObserverMode) => {
+  return (instance: Virtualizer<any, any>, cb: (offset: number) => void) => {
+    if (!instance.scrollElement) {
+      return
+    }
 
-  instance.scrollElement.addEventListener('scroll', onScroll, {
-    capture: false,
-    passive: true,
-  })
+    const propX = scrollProps[mode][0]
+    const propY = scrollProps[mode][1]
 
-  return () => {
-    instance.scrollElement.removeEventListener('scroll', onScroll)
-  }
-}
+    let prevX: number = instance.scrollElement[propX]
+    let prevY: number = instance.scrollElement[propY]
 
-export const observeWindowOffset = (
-  instance: Virtualizer<any, any>,
-  cb: (offset: number) => void,
-) => {
-  const onScroll = () =>
-    cb(
-      instance.scrollElement[
-        instance.options.horizontal ? 'scrollX' : 'scrollY'
-      ],
-    )
+    const scroll = () => {
+      const offset =
+        instance.scrollElement[instance.options.horizontal ? propX : propY]
 
-  if (!instance.scrollElement) {
-    return
-  }
+      cb(Math.max(0, offset - instance.options.scrollMargin))
+    }
 
-  onScroll()
+    scroll()
 
-  instance.scrollElement.addEventListener('scroll', onScroll, {
-    capture: false,
-    passive: true,
-  })
+    const onScroll = (e: Event) => {
+      const target = e.currentTarget as HTMLElement & Window
+      const scrollX = target[propX]
+      const scrollY = target[propY]
 
-  return () => {
-    instance.scrollElement.removeEventListener('scroll', onScroll)
+      if (instance.options.horizontal ? prevX - scrollX : prevY - scrollY) {
+        scroll()
+      }
+
+      prevX = scrollX
+      prevY = scrollY
+    }
+
+    instance.scrollElement.addEventListener('scroll', onScroll, {
+      capture: false,
+      passive: true,
+    })
+
+    return () => {
+      instance.scrollElement.removeEventListener('scroll', onScroll)
+    }
   }
 }
 
-export const measureElement = (
-  element: unknown,
-  instance: Virtualizer<any, any>,
+export const observeElementOffset = createOffsetObserver('element')
+export const observeWindowOffset = createOffsetObserver('window')
+
+export const measureElement = <TItemElement extends Element>(
+  element: TItemElement,
+  instance: Virtualizer<any, TItemElement>,
 ) => {
-  return (element as Element).getBoundingClientRect()[
-    instance.options.horizontal ? 'width' : 'height'
-  ]
+  return Math.round(
+    element.getBoundingClientRect()[
+      instance.options.horizontal ? 'width' : 'height'
+    ],
+  )
 }
 
 export const windowScroll = (
   offset: number,
-  canSmooth: boolean,
+  { canSmooth, sync }: { canSmooth: boolean; sync: boolean },
   instance: Virtualizer<any, any>,
 ) => {
-  ;(instance.scrollElement as Window)?.scrollTo({
-    [instance.options.horizontal ? 'left' : 'top']: offset,
+  const toOffset = sync ? offset : offset + instance.options.scrollMargin
+
+  ;(instance.scrollElement as Window)?.scrollTo?.({
+    [instance.options.horizontal ? 'left' : 'top']: toOffset,
     behavior: canSmooth ? 'smooth' : undefined,
   })
 }
 
 export const elementScroll = (
   offset: number,
-  canSmooth: boolean,
+  { canSmooth, sync }: { canSmooth: boolean; sync: boolean },
   instance: Virtualizer<any, any>,
 ) => {
-  ;(instance.scrollElement as Element)?.scrollTo({
-    [instance.options.horizontal ? 'left' : 'top']: offset,
+  const toOffset = sync ? offset : offset + instance.options.scrollMargin
+
+  ;(instance.scrollElement as Element)?.scrollTo?.({
+    [instance.options.horizontal ? 'left' : 'top']: toOffset,
     behavior: canSmooth ? 'smooth' : undefined,
   })
 }
 
 export interface VirtualizerOptions<
-  TScrollElement = unknown,
-  TItemElement = unknown,
+  TScrollElement extends unknown,
+  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: { canSmooth: boolean; sync: boolean },
     instance: Virtualizer<TScrollElement, TItemElement>,
   ) => void
   observeElementRect: (
@@ -233,24 +258,45 @@ export interface VirtualizerOptions<
   getItemKey?: (index: number) => Key
   rangeExtractor?: (range: Range) => number[]
   enableSmoothScroll?: boolean
+  scrollMargin?: number
+  scrollingDelay?: number
+  indexAttribute?: string
 }
 
-export class Virtualizer<TScrollElement = unknown, TItemElement = unknown> {
+export class Virtualizer<
+  TScrollElement extends unknown,
+  TItemElement extends Element,
+> {
   private unsubs: (void | (() => void))[] = []
   options!: Required<VirtualizerOptions<TScrollElement, TItemElement>>
   scrollElement: TScrollElement | null = null
-  private measurementsCache: Item[] = []
+  isScrolling: boolean = false
+  private isScrollingTimeoutId: ReturnType<typeof setTimeout> | null = null
+  measurementsCache: VirtualItem[] = []
   private itemMeasurementsCache: Record<Key, number> = {}
   private pendingMeasuredCacheIndexes: number[] = []
   private scrollRect: Rect
   private scrollOffset: number
+  private scrollDelta: number = 0
   private destinationOffset: undefined | number
   private scrollCheckFrame!: ReturnType<typeof setTimeout>
+  private measureElementCache: Record<string, TItemElement> = {}
+  private ro = new ResizeObserver((entries) => {
+    entries.forEach((entry) => {
+      this._measureElement(entry.target as TItemElement, false)
+    })
+  })
+  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.calculateRange()
   }
 
   setOptions = (opts: VirtualizerOptions<TScrollElement, TItemElement>) => {
@@ -273,6 +319,9 @@ export class Virtualizer<TScrollElement = unknown, TItemElement = unknown> {
       onChange: () => {},
       measureElement,
       initialRect: { width: 0, height: 0 },
+      scrollMargin: 0,
+      scrollingDelay: 150,
+      indexAttribute: 'data-index',
       ...opts,
     }
   }
@@ -284,10 +333,14 @@ export class Virtualizer<TScrollElement = unknown, TItemElement = unknown> {
   private cleanup = () => {
     this.unsubs.filter(Boolean).forEach((d) => d!())
     this.unsubs = []
+    this.scrollElement = null
   }
 
   _didMount = () => {
     return () => {
+      this.ro.disconnect()
+      this.measureElementCache = {}
+
       this.cleanup()
     }
   }
@@ -299,20 +352,47 @@ export class Virtualizer<TScrollElement = unknown, TItemElement = unknown> {
       this.cleanup()
 
       this.scrollElement = scrollElement
+      this._scrollToOffset(this.scrollOffset, {
+        canSmooth: false,
+        sync: true,
+        requested: false,
+      })
 
       this.unsubs.push(
         this.options.observeElementRect(this, (rect) => {
           this.scrollRect = rect
-          this.notify()
+          this.calculateRange()
         }),
       )
 
       this.unsubs.push(
         this.options.observeElementOffset(this, (offset) => {
-          this.scrollOffset = offset
-          this.notify()
+          if (this.isScrollingTimeoutId !== null) {
+            clearTimeout(this.isScrollingTimeoutId)
+            this.isScrollingTimeoutId = null
+          }
+
+          if (this.scrollOffset !== offset) {
+            this.scrollOffset = offset
+            this.isScrolling = true
+            this.scrollDelta = 0
+
+            this.isScrollingTimeoutId = setTimeout(() => {
+              this.isScrollingTimeoutId = null
+              this.isScrolling = false
+
+              this.notify()
+            }, this.options.scrollingDelay)
+          } else {
+            this.isScrolling = false
+            this.scrollDelta = 0
+          }
+
+          this.calculateRange()
         }),
       )
+    } else if (!this.isScrolling) {
+      this.calculateRange()
     }
   }
 
@@ -354,22 +434,30 @@ export class Virtualizer<TScrollElement = unknown, TItemElement = unknown> {
       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({
+      const range = calculateRange({
         measurements,
         outerSize,
         scrollOffset,
       })
+      if (
+        range.startIndex !== this.range.startIndex ||
+        range.endIndex !== this.range.endIndex
+      ) {
+        this.range = range
+        this.notify()
+      }
+      return this.range
     },
     {
-      key: process.env.NODE_ENV === 'development' && 'calculateRange',
+      key: process.env.NODE_ENV !== 'production' && 'calculateRange',
       debug: () => this.options.debug,
     },
   )
@@ -377,7 +465,7 @@ export class Virtualizer<TScrollElement = unknown, TItemElement = unknown> {
   private getIndexes = memo(
     () => [
       this.options.rangeExtractor,
-      this.calculateRange(),
+      this.range,
       this.options.overscan,
       this.options.count,
     ],
@@ -389,102 +477,151 @@ export class Virtualizer<TScrollElement = unknown, TItemElement = unknown> {
       })
     },
     {
-      key: process.env.NODE_ENV === 'development' && 'getIndexes',
+      key: process.env.NODE_ENV !== 'production' && 'getIndexes',
+      debug: () => this.options.debug,
     },
   )
 
+  indexFromElement = (node: TItemElement) => {
+    const attributeName = this.options.indexAttribute
+    const indexStr = node.getAttribute(attributeName)
+
+    if (!indexStr) {
+      console.warn(
+        `Missing attribute name '${attributeName}={index}' on measured element.`,
+      )
+      return -1
+    }
+
+    return parseInt(indexStr, 10)
+  }
+
+  _measureElement = (node: TItemElement, _sync: boolean) => {
+    const index = this.indexFromElement(node)
+
+    const item = this.measurementsCache[index]
+    if (!item) {
+      return
+    }
+    const key = String(item.key)
+
+    const prevNode = this.measureElementCache[key]
+
+    if (!node.isConnected) {
+      if (prevNode) {
+        this.ro.unobserve(prevNode)
+        delete this.measureElementCache[key]
+      }
+      return
+    }
+
+    if (!prevNode || prevNode !== node) {
+      if (prevNode) {
+        this.ro.unobserve(prevNode)
+      }
+      this.measureElementCache[key] = node
+      this.ro.observe(node)
+    }
+
+    const measuredItemSize = this.options.measureElement(node, this)
+
+    const itemSize = this.itemMeasurementsCache[item.key] ?? item.size
+
+    if (measuredItemSize !== itemSize) {
+      if (item.start < this.scrollOffset) {
+        if (process.env.NODE_ENV !== 'production' && this.options.debug) {
+          console.info('correction', measuredItemSize - itemSize)
+        }
+
+        if (this.destinationOffset === undefined) {
+          this.scrollDelta += measuredItemSize - itemSize
+
+          this._scrollToOffset(this.scrollOffset + this.scrollDelta, {
+            canSmooth: false,
+            sync: false,
+            requested: false,
+          })
+        }
+      }
+
+      this.pendingMeasuredCacheIndexes.push(index)
+      this.itemMeasurementsCache = {
+        ...this.itemMeasurementsCache,
+        [item.key]: measuredItemSize,
+      }
+      this.notify()
+    }
+  }
+
+  measureElement = (node: TItemElement | null) => {
+    if (!node) {
+      return
+    }
+
+    this._measureElement(node, true)
+  }
+
   getVirtualItems = memo(
-    () => [
-      this.getIndexes(),
-      this.getMeasurements(),
-      this.options.measureElement,
-    ],
-    (indexes, measurements, measureElement) => {
-      const virtualItems: VirtualItem<TItemElement>[] = []
+    () => [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: (measurableItem: TItemElement | null) => {
-            if (measurableItem) {
-              const measuredItemSize = measureElement(measurableItem, this)
-
-              if (measuredItemSize !== item.size) {
-                if (item.start < this.scrollOffset) {
-                  if (
-                    process.env.NODE_ENV === 'development' &&
-                    this.options.debug
-                  )
-                    console.info('correction', measuredItemSize - item.size)
-
-                  if (!this.destinationOffset) {
-                    this._scrollToOffset(
-                      this.scrollOffset + (measuredItemSize - item.size),
-                      false,
-                    )
-                  }
-                }
-
-                this.pendingMeasuredCacheIndexes.push(i)
-                this.itemMeasurementsCache = {
-                  ...this.itemMeasurementsCache,
-                  [item.key]: measuredItemSize,
-                }
-                this.notify()
-              }
-            }
-          },
-        }
-
-        virtualItems.push(item)
+        virtualItems.push(measurement)
       }
 
       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' },
+    {
+      align = 'start',
+      smoothScroll = this.options.enableSmoothScroll,
+    }: ScrollToOffsetOptions = {},
   ) => {
-    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'
-        }
-      }
+    const offset = this.scrollOffset
+    const size = this.getSize()
 
-      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)
+    if (align === 'auto') {
+      if (toOffset <= offset) {
+        align = 'start'
+      } else if (toOffset >= offset + size) {
+        align = 'end'
+      } else {
+        align = 'start'
       }
     }
 
-    attempt()
-    requestAnimationFrame(() => {
-      attempt()
-    })
+    const options = {
+      canSmooth: smoothScroll,
+      sync: false,
+      requested: true,
+    }
+    if (align === 'start') {
+      this._scrollToOffset(toOffset, options)
+    } else if (align === 'end') {
+      this._scrollToOffset(toOffset - size, options)
+    } else if (align === 'center') {
+      this._scrollToOffset(toOffset - size / 2, options)
+    }
   }
 
   scrollToIndex = (
     index: number,
-    { align, ...rest }: ScrollToIndexOptions = { align: 'auto' },
+    {
+      align = 'auto',
+      smoothScroll = this.options.enableSmoothScroll,
+      ...rest
+    }: ScrollToIndexOptions = {},
   ) => {
     const measurements = this.getMeasurements()
     const offset = this.scrollOffset
@@ -515,22 +652,27 @@ export class Virtualizer<TScrollElement = unknown, TItemElement = unknown> {
         ? measurement.end + this.options.scrollPaddingEnd
         : measurement.start - this.options.scrollPaddingStart
 
-    this.scrollToOffset(toOffset, { align, ...rest })
+    this.scrollToOffset(toOffset, { align, smoothScroll, ...rest })
   }
 
   getTotalSize = () =>
     (this.getMeasurements()[this.options.count - 1]?.end ||
       this.options.paddingStart) + this.options.paddingEnd
 
-  private _scrollToOffset = (offset: number, canSmooth: boolean) => {
+  private _scrollToOffset = (
+    offset: number,
+    {
+      requested,
+      canSmooth,
+      sync,
+    }: { canSmooth: boolean; sync: boolean; requested: boolean },
+  ) => {
     clearTimeout(this.scrollCheckFrame)
 
-    this.destinationOffset = offset
-    this.options.scrollToFn(
-      offset,
-      this.options.enableSmoothScroll && canSmooth,
-      this,
-    )
+    if (requested) {
+      this.destinationOffset = offset
+    }
+    this.options.scrollToFn(offset, { canSmooth, sync }, this)
 
     let scrollCheckFrame: ReturnType<typeof setTimeout>
 
@@ -590,7 +732,7 @@ function calculateRange({
   outerSize,
   scrollOffset,
 }: {
-  measurements: Item[]
+  measurements: VirtualItem[]
   outerSize: number
   scrollOffset: number
 }) {