From ab6ede8406e57621695f07b89854a48890972c50 Mon Sep 17 00:00:00 2001
From: Damian Pieczynski <piecyk@gmail.com>
Date: Mon, 29 Apr 2024 11:08:33 +0200
Subject: [PATCH] feat: add isScrollingResetDelay option to Virtualizer (#719)

---
 docs/api/virtualizer.md            | 36 ++++++++++++++++++++++++++++++
 packages/virtual-core/src/index.ts |  6 +++--
 2 files changed, 40 insertions(+), 2 deletions(-)

diff --git a/docs/api/virtualizer.md b/docs/api/virtualizer.md
index 92845303..f6458233 100644
--- a/docs/api/virtualizer.md
+++ b/docs/api/virtualizer.md
@@ -209,6 +209,16 @@ lanes: number
 
 The number of lanes the list is divided into (aka columns for vertical lists and rows for horizontal lists).
 
+### `isScrollingResetDelay`
+
+```tsx
+isScrollingResetDelay: number
+```
+
+This option allows you to specify the duration to wait after the last scroll event before resetting the isScrolling instance property. The default value is 150 milliseconds. 
+
+The implementation of this option is driven by the need for a reliable mechanism to handle scrolling behavior across different browsers. Until all browsers uniformly support the scrollEnd event.
+
 ## Virtualizer Instance
 
 The following properties and methods are available on the virtualizer instance:
@@ -320,8 +330,34 @@ scrollRect: Rect
 
 Current `Rect` of the scroll element.
 
+### `shouldAdjustScrollPositionOnItemSizeChange`
+
 ```tsx
 shouldAdjustScrollPositionOnItemSizeChange: undefined | ((item: VirtualItem, delta: number, instance: Virtualizer<TScrollElement, TItemElement>) => boolean)
 ```
 
 The shouldAdjustScrollPositionOnItemSizeChange method enables fine-grained control over the adjustment of scroll position when the size of dynamically rendered items differs from the estimated size. When jumping in the middle of the list and scrolling backward new elements may have a different size than the initially estimated size. This discrepancy can cause subsequent items to shift, potentially disrupting the user's scrolling experience, particularly when navigating backward through the list. 
+
+### `isScrolling`
+
+```tsx
+isScrolling: boolean
+```
+
+Boolean flag indicating if list is currently being scrolled.
+
+### `scrollDirection`
+
+```tsx
+scrollDirection: 'forward' | 'backward' | null
+```
+
+This option indicates the direction of scrolling, with possible values being 'forward' for scrolling downwards and 'backward' for scrolling upwards. The value is set to null when there is no active scrolling.
+
+### `scrollOffset`
+
+```tsx
+scrollOffset: number
+```
+
+This option represents the current scroll position along the scrolling axis. It is measured in pixels from the starting point of the scrollable area.
diff --git a/packages/virtual-core/src/index.ts b/packages/virtual-core/src/index.ts
index f799faf3..a8012a19 100644
--- a/packages/virtual-core/src/index.ts
+++ b/packages/virtual-core/src/index.ts
@@ -140,7 +140,7 @@ export const observeElementOffset = <T extends Element>(
     ? () => undefined
     : debounce(() => {
         cb(offset, false)
-      }, 150)
+      }, instance.options.isScrollingResetDelay)
 
   const createHandler = (isScrolling: boolean) => () => {
     offset = element[instance.options.horizontal ? 'scrollLeft' : 'scrollTop']
@@ -174,7 +174,7 @@ export const observeWindowOffset = (
     ? () => undefined
     : debounce(() => {
         cb(offset, false)
-      }, 150)
+      }, instance.options.isScrollingResetDelay)
 
   const createHandler = (isScrolling: boolean) => () => {
     offset = element[instance.options.horizontal ? 'scrollX' : 'scrollY']
@@ -297,6 +297,7 @@ export interface VirtualizerOptions<
   indexAttribute?: string
   initialMeasurementsCache?: VirtualItem[]
   lanes?: number
+  isScrollingResetDelay?: number
 }
 
 export class Virtualizer<
@@ -388,6 +389,7 @@ export class Virtualizer<
       indexAttribute: 'data-index',
       initialMeasurementsCache: [],
       lanes: 1,
+      isScrollingResetDelay: 150,
       ...opts,
     }
   }