virtual-scroller 1.7.6 → 1.8.0

package/source/Layout.test.js

@@ -0,0 +1,171 @@
+import Layout from './Layout'
+
+import Engine from '../test/Engine'
+
+describe('Layout', function() {
+	it('should work', function() {
+		const SCREEN_HEIGHT = 400
+
+		const scrollableContainer = {
+			width: 800,
+			height: SCREEN_HEIGHT
+		}
+
+		const ITEM_WIDTH = scrollableContainer.width
+		const ITEM_HEIGHT = 200
+
+		const VERTICAL_SPACING = 100
+
+		const items = new Array(9).fill(ITEM_WIDTH * ITEM_HEIGHT)
+
+		const layout = new Layout({
+			getPrerenderMargin: () => SCREEN_HEIGHT,
+			getVerticalSpacing: () => VERTICAL_SPACING,
+			getColumnsCount: () => 1,
+			getItemHeight: (i) => items[i] / scrollableContainer.width,
+			getBeforeResizeItemsCount: () => 0,
+			getAverageItemHeight: () => ITEM_HEIGHT,
+			getScrollableContainerHeight: () => scrollableContainer.height
+		})
+
+		// Initial render.
+		layout.getShownItemIndexes({
+			itemsCount: items.length,
+			visibleAreaTop: 0,
+			visibleAreaBottom: SCREEN_HEIGHT
+		}).should.deep.equal({
+			firstShownItemIndex: 0,
+			lastShownItemIndex: 2
+		})
+
+		// The first item is almost hidden.
+		layout.getShownItemIndexes({
+			itemsCount: items.length,
+			visibleAreaTop: SCREEN_HEIGHT + ITEM_HEIGHT - 1,
+			visibleAreaBottom: (SCREEN_HEIGHT + ITEM_HEIGHT - 1) + SCREEN_HEIGHT
+		}).should.deep.equal({
+			firstShownItemIndex: 0,
+			lastShownItemIndex: 4
+		})
+
+		// The first item is hidden.
+		layout.getShownItemIndexes({
+			itemsCount: items.length,
+			visibleAreaTop: SCREEN_HEIGHT + ITEM_HEIGHT,
+			visibleAreaBottom: (SCREEN_HEIGHT + ITEM_HEIGHT) + SCREEN_HEIGHT
+		}).should.deep.equal({
+			firstShownItemIndex: 1,
+			lastShownItemIndex: 4
+		})
+
+		// A new item at the bottom is almost visible.
+		layout.getShownItemIndexes({
+			itemsCount: items.length,
+			visibleAreaTop: (ITEM_HEIGHT + VERTICAL_SPACING) * 5 - SCREEN_HEIGHT * 2,
+			visibleAreaBottom: (ITEM_HEIGHT + VERTICAL_SPACING) * 5 - SCREEN_HEIGHT
+		}).should.deep.equal({
+			firstShownItemIndex: 1,
+			lastShownItemIndex: 4
+		})
+
+		// A new item at the bottom is visible.
+		layout.getShownItemIndexes({
+			itemsCount: items.length,
+			visibleAreaTop: (ITEM_HEIGHT + VERTICAL_SPACING) * 5 + 1 - SCREEN_HEIGHT * 2,
+			visibleAreaBottom: (ITEM_HEIGHT + VERTICAL_SPACING) * 5 + 1 - SCREEN_HEIGHT
+		}).should.deep.equal({
+			firstShownItemIndex: 1,
+			lastShownItemIndex: 5
+		})
+	})
+
+	it('should update layout for items incremental change', function() {
+		const scrollableContainer = {
+			width: 800,
+			height: 400
+		}
+
+		const ITEM_WIDTH = scrollableContainer.width
+		const ITEM_HEIGHT = 200
+
+		const items = new Array(9).fill(ITEM_WIDTH * ITEM_HEIGHT)
+
+		const VERTICAL_SPACING = 100
+
+		const layout = new Layout({
+			getPrerenderMargin: () => scrollableContainer.height,
+			getVerticalSpacing: () => VERTICAL_SPACING,
+			getColumnsCount: () => 1,
+			getItemHeight: (i) => ITEM_HEIGHT,
+			getBeforeResizeItemsCount: () => 0,
+			getAverageItemHeight: () => ITEM_HEIGHT,
+			getScrollableContainerHeight: () => scrollableContainer.height
+		})
+
+		layout.getLayoutUpdateForItemsDiff(
+			{
+				firstShownItemIndex: 3,
+				lastShownItemIndex: 5,
+				beforeItemsHeight: 3 * (ITEM_HEIGHT + VERTICAL_SPACING),
+				afterItemsHeight: 3 * (ITEM_HEIGHT + VERTICAL_SPACING)
+			},
+			{
+				prependedItemsCount: 5,
+				appendedItemsCount: 5
+			}, {
+				itemsCount: 5 + 5 + items.length,
+				columnsCount: 1
+			}
+		).should.deep.equal({
+			firstShownItemIndex: 5 + 3,
+			lastShownItemIndex: 5 + 5,
+			beforeItemsHeight: (5 + 3) * (ITEM_HEIGHT + VERTICAL_SPACING),
+			afterItemsHeight: (3 + 5) * (ITEM_HEIGHT + VERTICAL_SPACING)
+		})
+	})
+
+	it('should update layout for items incremental change (rows get rebalanced)', function() {
+		const scrollableContainer = {
+			width: 800,
+			height: 400
+		}
+		const ITEM_WIDTH = scrollableContainer.width
+		const ITEM_HEIGHT = 400
+
+		const items = new Array(9).fill(ITEM_WIDTH * ITEM_HEIGHT)
+
+		const VERTICAL_SPACING = 100
+
+		const layout = new Layout({
+			getPrerenderMargin: () => scrollableContainer.height,
+			getVerticalSpacing: () => VERTICAL_SPACING,
+			getColumnsCount: () => 4,
+			getItemHeight: () => ITEM_HEIGHT,
+			getBeforeResizeItemsCount: () => 0,
+			getAverageItemHeight: () => ITEM_HEIGHT,
+			getScrollableContainerHeight: () => scrollableContainer.height
+		})
+
+		layout.getLayoutUpdateForItemsDiff(
+			{
+				firstShownItemIndex: 3,
+				lastShownItemIndex: 5,
+				beforeItemsHeight: 3 * (ITEM_HEIGHT + VERTICAL_SPACING),
+				afterItemsHeight: 3 * (ITEM_HEIGHT + VERTICAL_SPACING)
+			},
+			{
+				prependedItemsCount: 5,
+				appendedItemsCount: 5
+			}, {
+				itemsCount: 5 + 5 + items.length,
+				columnsCount: 4,
+				shouldRestoreScrollPosition: true
+			}
+		).should.deep.equal({
+			firstShownItemIndex: 0,
+			lastShownItemIndex: 5 + 5,
+			beforeItemsHeight: 0,
+			afterItemsHeight: 5 * (ITEM_HEIGHT + VERTICAL_SPACING)
+		})
+	})
+})

package/source/ListHeightChangeWatcher.js

@@ -0,0 +1,94 @@
+export default class ListHeightChangeWatcher {
+	constructor({
+		itemsContainer,
+		getListTopOffset
+	}) {
+		this.itemsContainer = itemsContainer
+		this.getListTopOffset = getListTopOffset
+	}
+
+	/**
+	 * `<ReactVirtualScroller/>` calls this method.
+	 * @param  {any[]} previousItems
+	 * @param  {any[]} newItems
+	 * @param  {number} prependedItemsCount
+	 */
+	snapshot({
+		previousItems,
+		newItems,
+		prependedItemsCount
+	}) {
+		// If there were no items in the list
+		// then there's no point in restoring scroll position.
+		if (previousItems.length === 0) {
+			return
+		}
+		// If no items were prepended then no need to restore scroll position.
+		if (prependedItemsCount === 0) {
+			return
+		}
+		// The first item is supposed to be shown when the user clicks
+		// "Show previous items" button. If it isn't shown though,
+		// could still calculate the first item's top position using
+		// the values from `itemHeights` and `verticalSpacing`.
+		// But that would be a weird non-realistic scenario.
+		// if (firstShownItemIndex > 0) {
+		// 	let i = firstShownItemIndex - 1
+		// 	while (i >= 0) {
+		// 		firstItemTopOffset += itemHeights[i] + verticalSpacing
+		// 		i--
+		// 	}
+		// }
+		// If the scroll position has already been captured for restoration,
+		// then don't capture it the second time.
+		// Capturing scroll position could happen when using `<ReactVirtualScroller/>`
+		// because it calls `ListHeightChangeWatcher.snapshot()` inside `ReactVirtualScroller.render()`
+		// which is followed by `<VirtualScroller/>`'s `.componentDidUpdate()`
+		// that also calls `ListHeightChangeWatcher.snapshot()` with the same arguments,
+		// so that second call to `ListHeightChangeWatcher.snapshot()` is ignored.
+		// Calling `ListHeightChangeWatcher.snapshot()` inside `ReactVirtualScroller.render()`
+		// is done to prevent scroll Y position from jumping
+		// when showing the first page of the "Previous items".
+		// See the long section of comments in `ReactVirtualScroller.render()`
+		// method for more info on why is `ListHeightChangeWatcher.snapshot()` called there.
+		if (this._snapshot &&
+			this._snapshot.previousItems === previousItems &&
+			this._snapshot.newItems === newItems) {
+			return
+		}
+		this._snapshot = {
+			previousItems,
+			newItems,
+			itemIndex: prependedItemsCount,
+			itemTopOffset: this.itemsContainer.getNthRenderedItemTopOffset(0),
+			// Snapshot list top offset inside the scrollable container too
+			// because it's common to hide the "Show previous items" button
+			// when the user has browsed to the top of the list, which causes
+			// the list's top position to shift upwards due to the button
+			// no longer being rendered. Tracking list top offset doesn't
+			// fit here that well, but it makes sense in real-world applications.
+			listTopOffset: this.getListTopOffset()
+		}
+	}
+
+	getAnchorItemIndex() {
+		return this._snapshot.itemIndex
+	}
+
+	hasSnapshot() {
+		return this._snapshot !== undefined
+	}
+
+	getListBottomOffsetChange() {
+		const { itemIndex, itemTopOffset, listTopOffset } = this._snapshot
+		// `firstShownItemIndex` is supposed to be `0` at this point,
+		// so `renderedElementIndex` would be the same as the `itemIndex`.
+		const itemTopOffsetNew = this.itemsContainer.getNthRenderedItemTopOffset(itemIndex)
+		const listTopOffsetNew = this.getListTopOffset()
+		return (itemTopOffsetNew - itemTopOffset) + (listTopOffsetNew - listTopOffset)
+	}
+
+	reset() {
+		this._snapshot = undefined
+	}
+}

package/source/Resize.js

@@ -1,19 +1,28 @@
-import { LAYOUT_REASON } from './Layout'
 import debounce from './utility/debounce'
+import log from './utility/debug'
 
 export default class Resize {
 	constructor({
 		bypass,
 		scrollableContainer,
-		getContainerElement,
-		updateLayout,
-		resetStateAndLayout
+		onStart,
+		onStop,
+		onHeightChange,
+		onWidthChange,
+		onNoChange
 	}) {
 		this.bypass = bypass
 		this.scrollableContainer = scrollableContainer
-		this.getContainerElement = getContainerElement
-		this.updateLayout = updateLayout
-		this.resetStateAndLayout = resetStateAndLayout
+
+		this.onHeightChange = onHeightChange
+		this.onWidthChange = onWidthChange
+		this.onNoChange = onNoChange
+
+		this.onResize = debounce(
+			this._onResize,
+			SCROLLABLE_CONTAINER_RESIZE_DEBOUNCE_INTERVAL,
+			{ onStart, onStop }
+		)
 	}
 
 	listen() {
@@ -23,22 +32,21 @@ export default class Resize {
 		this.isRendered = true
 		this.scrollableContainerWidth = this.scrollableContainer.getWidth()
 		this.scrollableContainerHeight = this.scrollableContainer.getHeight()
-		this.scrollableContainerUnlistenResize = this.scrollableContainer.onResize(this.onResize, {
-			container: this.getContainerElement()
-		})
+		this.scrollableContainerUnlistenResize = this.scrollableContainer.onResize(this.onResize)
 	}
 
 	stop() {
 		this.isRendered = false
 		if (this.scrollableContainerUnlistenResize) {
 			this.scrollableContainerUnlistenResize()
+			this.scrollableContainerUnlistenResize = undefined
 		}
 	}
 
 	/**
 	 * On scrollable container resize.
 	 */
-	onResize = debounce(() => {
+	_onResize = () => {
 		// If `VirtualScroller` has been unmounted
 		// while `debounce()`'s `setTimeout()` was waiting, then exit.
 		if (!this.isRendered) {
@@ -52,21 +60,21 @@ export default class Resize {
 			if (this.scrollableContainerHeight === prevScrollableContainerHeight) {
 				// The dimensions of the container didn't change,
 				// so there's no need to re-layout anything.
-				return
+				this.onNoChange()
 			} else {
 				// Scrollable container height has changed,
 				// so just recalculate shown item indexes.
 				// No need to perform a re-layout from scratch.
-				this.updateLayout({ reason: LAYOUT_REASON.RESIZE })
+				this.onHeightChange(prevScrollableContainerHeight, this.scrollableContainerHeight)
 			}
 		} else {
 			// Reset item heights, because if scrollable container's width (or height)
 			// has changed, then the list width (or height) most likely also has changed,
 			// and also some CSS `@media()` rules might have been added or removed.
 			// So re-render the list entirely.
-			this.resetStateAndLayout()
+			this.onWidthChange(prevScrollableContainerWidth, this.scrollableContainerWidth)
 		}
-	}, SCROLLABLE_CONTAINER_RESIZE_DEBOUNCE_INTERVAL)
+	}
 }
 
 const SCROLLABLE_CONTAINER_RESIZE_DEBOUNCE_INTERVAL = 250

package/source/Scroll.js

@@ -4,39 +4,39 @@
 // https://github.com/bvaughn/react-virtualized/issues/722
 import { setTimeout, clearTimeout } from 'request-animation-frame-timeout'
 
-import { LAYOUT_REASON } from './Layout'
 import log from './utility/debug'
 
 export default class Scroll {
 	constructor({
 		bypass,
 		scrollableContainer,
-		updateLayout,
+		itemsContainer,
+		onScroll,
 		initialScrollPosition,
 		onScrollPositionChange,
 		isImmediateLayoutScheduled,
 		hasNonRenderedItemsAtTheTop,
 		hasNonRenderedItemsAtTheBottom,
-		getLatestLayoutVisibleAreaIncludingMargins,
-		preserveScrollPositionOfTheBottomOfTheListOnMount
+		getLatestLayoutVisibleArea,
+		getListTopOffset,
+		getPrerenderMargin,
+		onScrolledToTop,
+		waitForScrollingToStop
 	}) {
 		this.bypass = bypass
 		this.scrollableContainer = scrollableContainer
-		this.updateLayout = updateLayout
+		this.itemsContainer = itemsContainer
+		this.onScroll = onScroll
 		this.initialScrollPosition = initialScrollPosition
 		this.onScrollPositionChange = onScrollPositionChange
 		this.isImmediateLayoutScheduled = isImmediateLayoutScheduled
 		this.hasNonRenderedItemsAtTheTop = hasNonRenderedItemsAtTheTop
 		this.hasNonRenderedItemsAtTheBottom = hasNonRenderedItemsAtTheBottom
-		this.getLatestLayoutVisibleAreaIncludingMargins = getLatestLayoutVisibleAreaIncludingMargins
-
-		if (preserveScrollPositionOfTheBottomOfTheListOnMount) {
-			if (scrollableContainer) {
-				this.preserveScrollPositionOfTheBottomOfTheListOnMount = {
-					scrollableContainerContentHeight: scrollableContainer.getContentHeight()
-				}
-			}
-		}
+		this.getLatestLayoutVisibleArea = getLatestLayoutVisibleArea
+		this.getListTopOffset = getListTopOffset
+		this.getPrerenderMargin = getPrerenderMargin
+		this.onScrolledToTop = onScrolledToTop
+		this.waitForScrollingToStop = waitForScrollingToStop
 	}
 
 	listen() {
@@ -44,32 +44,36 @@ export default class Scroll {
 			this.scrollToY(this.initialScrollPosition)
 		}
 		if (this.onScrollPositionChange) {
-			this.updateScrollPosition()
-			this.removeScrollPositionListener = this.scrollableContainer.addScrollListener(this.updateScrollPosition)
-		}
-		if (!this.bypass) {
-			this.removeScrollListener = this.scrollableContainer.addScrollListener(this.onScroll)
-		}
-		if (this.preserveScrollPositionOfTheBottomOfTheListOnMount) {
-			this.scrollToY(this.getScrollY() + (this.scrollableContainer.getContentHeight() - this.preserveScrollPositionOfTheBottomOfTheListOnMount.scrollableContainerContentHeight))
+			this.onScrollPositionChange(this.getScrollY())
 		}
+		this.stopListeningToScroll = this.scrollableContainer.onScroll(this.onScrollListener)
 	}
 
 	stop() {
-		if (this.removeScrollPositionListener) {
-			this.removeScrollPositionListener()
+		if (this.stopReportingScrollPositionChange) {
+			this.stopReportingScrollPositionChange()
+			this.stopReportingScrollPositionChange = undefined
+		}
+		if (this.stopListeningToScroll) {
+			this.stopListeningToScroll()
+			this.stopListeningToScroll = undefined
+		}
+		if (this.onStopScrollingListener) {
+			this.onStopScrollingListener = undefined
 		}
-		if (this.removeScrollListener) {
-			this.removeScrollListener()
+		if (this.onScrollOnStopScrolling) {
+			this.onScrollOnStopScrolling = undefined
 		}
-		this.cancelOnUserStopsScrollingTimer()
+		this.cancelOnStopScrollingTimer()
 	}
 
 	scrollToY(scrollY) {
+		this.ignoreScrollEvents = true
 		this.scrollableContainer.scrollToY(scrollY)
+		this.ignoreScrollEvents = undefined
 	}
 
-	scrollByY(scrollByY) {
+	scrollByY = (scrollByY) => {
 		this.scrollToY(this.getScrollY() + scrollByY)
 	}
 
@@ -77,86 +81,143 @@ export default class Scroll {
 		return this.scrollableContainer.getScrollY()
 	}
 
-	/**
-	 * Updates the current scroll Y position in state.
-	 */
-	updateScrollPosition = () => {
-		this.onScrollPositionChange(this.getScrollY())
-	}
-
-	cancelOnUserStopsScrollingTimer() {
-		if (this.onUserStopsScrollingTimer) {
-			clearTimeout(this.onUserStopsScrollingTimer)
-			this.onUserStopsScrollingTimer = undefined
+	cancelOnStopScrollingTimer() {
+		if (this.onStopScrollingTimer) {
+			clearTimeout(this.onStopScrollingTimer)
+			this.onStopScrollingTimer = undefined
 		}
 	}
 
-	onLayout() {
+	cancelScheduledLayout() {
 		// Cancel a "re-layout when user stops scrolling" timer.
-		this.cancelOnUserStopsScrollingTimer()
+		this.cancelOnStopScrollingTimer()
 	}
 
-	onScroll = () => {
+	onScrollListener = () => {
+		if (this.onScrollPositionChange) {
+			this.onScrollPositionChange(this.getScrollY())
+		}
+
+		// If the user has scrolled up to the top of the items container.
+		// (this option isn't currently used)
+		if (this.onScrolledToTop) {
+			if (this.getScrollY() < this.getListTopOffset()) {
+				this.onScrolledToTop()
+			}
+		}
+
+		if (this.bypass) {
+			return
+		}
+
+		if (this.ignoreScrollEvents) {
+			return
+		}
+
 		// Prefer not performing a re-layout while the user is scrolling (if possible).
 		// If the user doesn't scroll too far and then stops for a moment,
 		// then a mid-scroll re-layout could be delayed until such a brief stop:
 		// presumably, this results in better (smoother) scrolling performance,
 		// delaying the work to when it doesn't introduce any stutter or "jank".
 
-		// Reset `this.onUserStopsScrollingTimer` (will be re-created below).
-		this.cancelOnUserStopsScrollingTimer()
+		// Reset `this.onStopScrollingTimer` (will be re-created below).
+		this.cancelOnStopScrollingTimer()
 
-		// See whether rendering "new" previous/next items is required
-		// right now, or it can wait until the user stops scrolling.
+		// See if the latest "layout" (the currently rendered set of items)
+		// is still sufficient in order to show all the items that're
+		// currently inside the viewport. If there're some non-rendered items
+		// that're visible in the current viewport, then those items
+		// should be rendered "immediately" rather than waiting until
+		// the user stops scrolling.
 		const forceUpdate =
 			// If the items have been rendered at least once
-			this.getLatestLayoutVisibleAreaIncludingMargins() && (
+			this.getLatestLayoutVisibleArea() && (
 				(
-					// If the user has scrolled up past the extra "margin"
-					(this.getScrollY() < this.getLatestLayoutVisibleAreaIncludingMargins().top) &&
-					// and if there're any previous non-rendered items to render.
+					// If the user has scrolled up past the "prerender margin"
+					// and there're some non-rendered items at the top,
+					// then force a re-layout.
+					//
+					// (during these calculations we assume that the list's top coordinate
+					//  hasn't changed since previous layout; even if that's not exactly true,
+					//  the items will be re-layout when the user stops scrolling anyway)
+					//
+					(this.getScrollY() < this.getLatestLayoutVisibleArea().top - this.getPrerenderMargin()) &&
 					this.hasNonRenderedItemsAtTheTop()
 				)
 				||
 				(
-					// If the user has scrolled down past the extra "margin"
-					(this.getScrollY() + this.scrollableContainer.getHeight() > this.getLatestLayoutVisibleAreaIncludingMargins().bottom) &&
-					// and if there're any next non-rendered items to render.
+					// If the user has scrolled down past the "prerender margin"
+					// and there're any non-rendered items left at the end,
+					// then force a re-layout.
+					//
+					// (during these calculations we assume that the list's top coordinate
+					//  hasn't changed since previous layout; even if that's not exactly true,
+					//  the items will be re-layout when the user stops scrolling anyway)
+					//
+					(this.getScrollY() + this.scrollableContainer.getHeight() > this.getLatestLayoutVisibleArea().bottom + this.getPrerenderMargin()) &&
 					this.hasNonRenderedItemsAtTheBottom()
 				)
 			)
 
 		if (forceUpdate) {
-			log('The user has scrolled far enough: force re-layout')
+			log('The user has scrolled far enough: perform a re-layout')
 		} else {
-			log('The user hasn\'t scrolled too much: delay re-layout')
+			log('The user is scrolling: perform a re-layout when they stop scrolling')
 		}
 
-		if (!forceUpdate) {
-			// If a re-layout is already scheduled at the next "frame",
-			// don't schedule a "re-layout when user stops scrolling" timer.
-			if (this.isImmediateLayoutScheduled()) {
-				return
-			}
-			this.onUserStopsScrollingTimer = setTimeout(
-				() => {
-					this.onUserStopsScrollingTimer = undefined
-					this.updateLayout({ reason: LAYOUT_REASON.STOPPED_SCROLLING })
-				},
-				// "scroll" events are usually dispatched every 16 milliseconds
-				// for 60fps refresh rate, so waiting for 100 milliseconds feels
-				// reasonable: that would be about 6 frames of inactivity period,
-				// which could mean that either the user has stopped scrolling
-				// (for a moment) or the browser is lagging and stuttering
-				// (skipping frames due to high load).
-				// If the user continues scrolling then this timeout is constantly
-				// refreshed (cancelled and then re-created).
-				WAIT_FOR_USER_TO_STOP_SCROLLING_TIMEOUT
-			)
+		if (forceUpdate || this.waitForScrollingToStop === false) {
+			return this.onScroll()
+		}
+
+		// If a re-layout is already scheduled at the next "frame",
+		// don't schedule a "re-layout when user stops scrolling" timer.
+		if (this.isImmediateLayoutScheduled()) {
 			return
 		}
 
-		this.updateLayout({ reason: LAYOUT_REASON.SCROLL })
+		this.onScrollOnStopScrolling = true
+		this.watchOnStopScrolling()
+	}
+
+	watchOnStopScrolling() {
+		this.onStopScrollingTimer = setTimeout(
+			() => {
+				this.onStopScrollingTimer = undefined
+
+				if (this.onScrollOnStopScrolling) {
+					this.onScrollOnStopScrolling = undefined
+					this.onScroll({ delayed: true })
+				}
+
+				if (this.onStopScrollingListener) {
+					const onStopScrollingListener = this.onStopScrollingListener
+					this.onStopScrollingListener = undefined
+					// `onStopScrollingListener()` may hypothetically schedule
+					// another `onStopScrolling()` listener, so set
+					// `this.onStopScrollingListener` to `undefined` before
+					// calling it rather than after.
+					log('~ The user has stopped scrolling ~')
+					onStopScrollingListener()
+				}
+			},
+			// "scroll" events are usually dispatched every 16 milliseconds
+			// for 60fps refresh rate, so waiting for 100 milliseconds feels
+			// reasonable: that would be about 6 frames of inactivity period,
+			// which could mean that either the user has stopped scrolling
+			// (for a moment) or the browser is lagging and stuttering
+			// (skipping frames due to high load).
+			// If the user continues scrolling then this timeout is constantly
+			// refreshed (cancelled and then re-created).
+			ON_STOP_SCROLLING_INACTIVE_PERIOD
+		)
+	}
+
+	// (this function isn't currently used)
+	onStopScrolling(onStopScrollingListener) {
+		this.onStopScrollingListener = onStopScrollingListener
+		if (!this.onStopScrollingTimer) {
+			this.watchOnStopScrolling()
+		}
 	}
 
 	/**
@@ -174,4 +235,4 @@ export default class Scroll {
 	}
 }
 
-const WAIT_FOR_USER_TO_STOP_SCROLLING_TIMEOUT = 100
+const ON_STOP_SCROLLING_INACTIVE_PERIOD = 100