virtual-scroller 1.7.7 → 1.8.1

package/source/DOM/{WaitForStylesToLoad.js → ListTopOffsetWatcher.js}

@@ -4,47 +4,72 @@
 // https://github.com/bvaughn/react-virtualized/issues/722
 import { setTimeout, clearTimeout } from 'request-animation-frame-timeout'
 
-import { LAYOUT_REASON } from '../Layout'
+// Refreshing two times every seconds seems reasonable.
+const WATCH_LIST_TOP_OFFSET_INTERVAL = 500
+
+// Refreshing for 3 seconds after the initial page load seems reasonable.
+const WATCH_LIST_TOP_OFFSET_MAX_DURATION = 3000
 
 // `VirtualScroller` calls `this.layout.layOut()` on mount,
 // but if the page styles are applied after `VirtualScroller` mounts
 // (for example, if styles are applied via javascript, like Webpack does)
-// then the list might not render correctly and will only show the first item.
-// The reason for that would be that calling `.getListTopOffsetInsideScrollableContainer()`
-// on mount returns "incorrect" `top` position because the styles haven't been applied yet.
+// then the list might not render correctly and it will only show the first item.
+// The reason is that in that case calling `.getListTopOffset()` on mount
+// returns "incorrect" `top` position because the styles haven't been applied yet.
+//
 // For example, consider a page:
 // <div class="page">
 //   <nav class="sidebar">...</nav>
 //   <main>...</main>
 // </div>
+//
 // The sidebar is styled as `position: fixed`, but until
 // the page styles have been applied it's gonna be a regular `<div/>`
 // meaning that `<main/>` will be rendered below the sidebar
 // and will appear offscreen and so it will only render the first item.
+//
 // Then, the page styles are loaded and applied and the sidebar
 // is now `position: fixed` so `<main/>` is now rendered at the top of the page
 // but `VirtualScroller`'s `.render()` has already been called
 // and it won't re-render until the user scrolls or the window is resized.
-// This type of a bug doesn't occur in production, but it can appear
+//
+// This type of a bug doesn't seem to occur in production, but it can appear
 // in development mode when using Webpack. The workaround `VirtualScroller`
-// implements for such cases is calling `.getListTopOffsetInsideScrollableContainer()`
+// implements for such cases is calling `.getListTopOffset()`
 // on the list container DOM element periodically (every second) to check
 // if the `top` coordinate has changed as a result of CSS being applied:
 // if it has then it recalculates the shown item indexes.
-export default class WaitForStylesToLoad {
+//
+// Maybe this bug could occur in production when using Webpack chunks.
+// That depends on how a style of a chunk is added to the page:
+// if it's added via `javascript` after the page has been rendered
+// then this workaround will also work for that case.
+//
+// Another example would be a page having a really tall expanded "accordion"
+// section, below which a `VirtualScroller` list resides. If the user un-expands
+// such expanded "accordion" section, the list would become visible but
+// it wouldn't get re-rendered because no `scroll` event has occured,
+// and the list only re-renders automatically on `scroll` events.
+// To work around such cases, call `virtualScroller.updateLayout()` method manually.
+// The workaround below could be extended to refresh the list's top coordinate
+// indefinitely and at higher intervals, but why waste CPU time on that.
+// There doesn't seem to be any DOM API for tracking an element's top position.
+// There is `IntersectionObserver` API but it doesn't exactly do that.
+//
+export default class ListTopOffsetWatcher {
 	constructor({
-		updateLayout,
-		getListTopOffsetInsideScrollableContainer
+		getListTopOffset,
+		onListTopOffsetChange
 	}) {
-		this.updateLayout = updateLayout
-		this.getListTopOffsetInsideScrollableContainer = getListTopOffsetInsideScrollableContainer
+		this.getListTopOffset = getListTopOffset
+		this.onListTopOffsetChange = onListTopOffsetChange
 	}
 
-	onGotListTopOffset(listTopOffset) {
+	onListTopOffset(listTopOffset) {
 		if (this.listTopOffsetInsideScrollableContainer === undefined) {
 			// Start periodical checks of the list's top offset
 			// in order to perform a re-layout in case it changes.
-			// See the comments in `WaitForStylesToLoad.js` file
+			// See the comments in `ListTopOffsetWatcher.js` file
 			// on why can the list's top offset change, and in which circumstances.
 			this.start()
 		}
@@ -58,7 +83,11 @@ export default class WaitForStylesToLoad {
 
 	stop() {
 		this.isRendered = false
-		clearTimeout(this.watchListTopOffsetTimer)
+
+		if (this.watchListTopOffsetTimer) {
+			clearTimeout(this.watchListTopOffsetTimer)
+			this.watchListTopOffsetTimer = undefined
+		}
 	}
 
 	watchListTopOffset() {
@@ -72,11 +101,11 @@ export default class WaitForStylesToLoad {
 			// Skip comparing `top` coordinate of the list
 			// when this function is called for the first time.
 			if (this.listTopOffsetInsideScrollableContainer !== undefined) {
-				// Calling `this.getListTopOffsetInsideScrollableContainer()`
-				// on an element is about 0.003 milliseconds on a modern desktop CPU,
+				// Calling `this.getListTopOffset()` on an element
+				// runs about 0.003 milliseconds on a modern desktop CPU,
 				// so I guess it's fine calling it twice a second.
-				if (this.getListTopOffsetInsideScrollableContainer() !== this.listTopOffsetInsideScrollableContainer) {
-					this.updateLayout({ reason: LAYOUT_REASON.TOP_OFFSET_CHANGED })
+				if (this.getListTopOffset() !== this.listTopOffsetInsideScrollableContainer) {
+					this.onListTopOffsetChange()
 				}
 			}
 			// Compare `top` coordinate of the list twice a second
@@ -93,7 +122,4 @@ export default class WaitForStylesToLoad {
 		// Run the cycle.
 		check()
 	}
-}
-
-const WATCH_LIST_TOP_OFFSET_INTERVAL = 500
-const WATCH_LIST_TOP_OFFSET_MAX_DURATION = 3000
+}

package/source/DOM/ScrollableContainer.js

@@ -2,9 +2,11 @@ export default class ScrollableContainer {
 	/**
 	 * Constructs a new "scrollable container" from an element.
 	 * @param {Element} scrollableContainer
+	 * @param {func} getItemsContainerElement — Returns items "container" element.
 	 */
-	constructor(element) {
+	constructor(element, getItemsContainerElement) {
 		this.element = element
+		this.getItemsContainerElement = getItemsContainerElement
 	}
 
 	/**
@@ -20,7 +22,14 @@ export default class ScrollableContainer {
 	 * @param {number} scrollY
 	 */
 	scrollToY(scrollY) {
-		this.element.scrollTo(0, scrollY)
+		// IE 11 doesn't seem to have a `.scrollTo()` method.
+		// https://gitlab.com/catamphetamine/virtual-scroller/-/issues/10
+		// https://stackoverflow.com/questions/39908825/window-scrollto-is-not-working-in-internet-explorer-11
+		if (this.element.scrollTo) {
+			this.element.scrollTo(0, scrollY)
+		} else {
+			this.element.scrollTop = scrollY
+		}
 	}
 
 	/**
@@ -45,30 +54,15 @@ export default class ScrollableContainer {
 	}
 
 	/**
-	 * Returns the height of the content in a scrollable container.
-	 * For example, a scrollable container can have a height of 500px,
-	 * but the content in it could have a height of 5000px,
-	 * in which case a vertical scrollbar is rendered, and only
-	 * one-tenth of all the items are shown at any given moment.
-	 * This function is currently only used when using the
-	 * `preserveScrollPositionOfTheBottomOfTheListOnMount` feature.
-	 * @return {number}
-	 */
-	getContentHeight() {
-		return this.element.scrollHeight
-	}
-
-	/**
-	 * Returns a "top offset" of an element
+	 * Returns a "top offset" of an items container element
 	 * relative to the "scrollable container"'s top edge.
-	 * @param {Element} element
 	 * @return {number}
 	 */
-	getTopOffset(element) {
+	getItemsContainerTopOffset() {
 		const scrollableContainerTop = this.element.getBoundingClientRect().top
 		const scrollableContainerBorderTopWidth = this.element.clientTop
-		const top = element.getBoundingClientRect().top
-		return (top - scrollableContainerTop) + this.getScrollY() - scrollableContainerBorderTopWidth
+		const itemsContainerTop = this.getItemsContainerElement().getBoundingClientRect().top
+		return (itemsContainerTop - scrollableContainerTop) + this.getScrollY() - scrollableContainerBorderTopWidth
 	}
 
 	// isVisible() {
@@ -81,7 +75,7 @@ export default class ScrollableContainer {
 	 * @param {onScroll} Should be called whenever the scroll position inside the "scrollable container" (potentially) changes.
 	 * @return {function} Returns a function that stops listening.
 	 */
-	addScrollListener(onScroll) {
+	onScroll(onScroll) {
 		this.element.addEventListener('scroll', onScroll)
 		return () => this.element.removeEventListener('scroll', onScroll)
 	}
@@ -89,13 +83,10 @@ export default class ScrollableContainer {
 	/**
 	 * Adds a "resize" event listener to the "scrollable container".
 	 * @param {onResize} Should be called whenever the "scrollable container"'s width or height (potentially) changes.
-	 * @param  {Element} options.container — The result of the `getContainerElement()` function that was passed in `VirtualScroller` constructor. For example, DOM renderer uses it to filter-out unrelated "resize" events.
-	 * @return {function} Returns a function that stops listening.
+   * @return {function} Returns a function that stops listening.
 	 */
-	onResize(onResize, { container }) {
-		// Could somehow track DOM Element size.
-		// For now, `scrollableContainer` is supposed to have constant width and height.
-		// (unless window is resized).
+	onResize(onResize) {
+		// Watches "scrollable container"'s dimensions via a `ResizeObserver`.
 		// https://developer.mozilla.org/en-US/docs/Web/API/ResizeObserver
 		// https://web.dev/resize-observer/
 		let unobserve
@@ -122,7 +113,9 @@ export default class ScrollableContainer {
 		// hasn't changed since the previous time `onResize()` has been called,
 		// then `onResize()` doesn't do anything, so, I guess, there shouldn't be
 		// any "performance implications" of running the listener twice in such case.
-		const unlistenGlobalResize = addGlobalResizeListener(onResize, { container })
+		const unlistenGlobalResize = addGlobalResizeListener(onResize, {
+			itemsContainerElement: this.getItemsContainerElement()
+		})
 		return () => {
 			if (unobserve) {
 				unobserve()
@@ -133,8 +126,12 @@ export default class ScrollableContainer {
 }
 
 export class ScrollableWindowContainer extends ScrollableContainer {
-	constructor() {
-		super(window)
+	/**
+	 * Constructs a new window "scrollable container".
+	 * @param {func} getItemsContainerElement — Returns items "container" element.
+	 */
+	constructor(getItemsContainerElement) {
+		super(window, getItemsContainerElement)
 	}
 
 	/**
@@ -182,38 +179,24 @@ export class ScrollableWindowContainer extends ScrollableContainer {
 	}
 
 	/**
-	 * Returns the height of the content in a scrollable container.
-	 * For example, a scrollable container can have a height of 500px,
-	 * but the content in it could have a height of 5000px,
-	 * in which case a vertical scrollbar is rendered, and only
-	 * one-tenth of all the items are shown at any given moment.
-	 * This function is currently only used when using the
-	 * `preserveScrollPositionOfTheBottomOfTheListOnMount` feature.
-	 * @return {number}
-	 */
-	getContentHeight() {
-		return document.documentElement.scrollHeight
-	}
-
-	/**
-	 * Returns a "top offset" of an element
+	 * Returns a "top offset" of an items container element
 	 * relative to the "scrollable container"'s top edge.
-	 * @param {Element} element
 	 * @return {number}
 	 */
-	getTopOffset(element) {
+	getItemsContainerTopOffset() {
 		const borderTopWidth = document.clientTop || document.body.clientTop || 0
-		return element.getBoundingClientRect().top + this.getScrollY() - borderTopWidth
+		return this.getItemsContainerElement().getBoundingClientRect().top + this.getScrollY() - borderTopWidth
 	}
 
 	/**
 	 * Adds a "resize" event listener to the "scrollable container".
 	 * @param {onScroll} Should be called whenever the "scrollable container"'s width or height (potentially) changes.
-	 * @param  {Element} options.container — The result of the `getContainerElement()` function that was passed in `VirtualScroller` constructor. For example, DOM renderer uses it to filter-out unrelated "resize" events.
 	 * @return {function} Returns a function that stops listening.
 	 */
-	onResize(onResize, { container }) {
-		return addGlobalResizeListener(onResize, { container })
+	onResize(onResize) {
+		return addGlobalResizeListener(onResize, {
+			itemsContainerElement: this.getItemsContainerElement()
+		})
 	}
 
 	// isVisible() {
@@ -223,11 +206,11 @@ export class ScrollableWindowContainer extends ScrollableContainer {
 
 /**
  * Adds a "resize" event listener to the `window`.
- * @param {onResize} Should be called whenever the "container"'s width or height (potentially) changes.
- * @param  {Element} options.container — The "container".
+ * @param {onResize} Should be called whenever the "scrollable container"'s width or height (potentially) changes.
+ * @param  {Element} options.itemsContainerElement — The items "container" element, which is not the same as the "scrollable container" element. For example, "scrollable container" could be resized while the list element retaining its size. One such example is a user entering fullscreen mode on an HTML5 `<video/>` element: in that case, a "resize" event is triggered on a window, and window dimensions change to the user's screen size, but such "resize" event can be ignored because the list isn't visible until the user exits fullscreen mode.
  * @return {function} Returns a function that stops listening.
  */
-function addGlobalResizeListener(onResize, { container }) {
+function addGlobalResizeListener(onResize, { itemsContainerElement }) {
 	const onResizeListener = () => {
 		// By default, `VirtualScroller` always performs a re-layout
 		// on window `resize` event. But browsers (Chrome, Firefox)
@@ -258,7 +241,7 @@ function addGlobalResizeListener(onResize, { container }) {
 			// the layout wouldn't be affected too, so such `resize` event should also be
 			// ignored: when `document.fullscreenElement` is inside the `container`.
 			//
-			if (document.fullscreenElement.contains(container)) {
+			if (document.fullscreenElement.contains(itemsContainerElement)) {
 				// The element is either the `container`'s ancestor,
 				// Or is the `container` itself.
 				// (`a.contains(b)` includes the `a === b` case).

package/source/DOM/VirtualScroller.js

@@ -4,8 +4,8 @@ import log, { warn } from '../utility/debug'
 import px from '../utility/px'
 
 export default class VirtualScroller {
-  constructor(element, items, renderItem, options = {}) {
-    this.container = element
+  constructor(itemsContainerElement, items, renderItem, options = {}) {
+    this.container = itemsContainerElement
     this.renderItem = renderItem
     const {
       onMount,
@@ -55,7 +55,6 @@ export default class VirtualScroller {
     const diffRender = prevState && items === prevState.items && items.length > 0
     // Remove no longer visible items from the DOM.
     if (diffRender) {
-      log('Incremental rerender')
       // Decrement instead of increment here because
       // `this.container.removeChild()` changes indexes.
       let i = prevState.lastShownItemIndex
@@ -63,14 +62,14 @@ export default class VirtualScroller {
         if (i >= firstShownItemIndex && i <= lastShownItemIndex) {
           // The item is still visible.
         } else {
-          log('Remove item index', i)
+          log('DOM: Remove element for item index', i)
           // The item is no longer visible. Remove it.
           this.unmountItem(this.container.childNodes[i - prevState.firstShownItemIndex])
         }
         i--
       }
     } else {
-      log('Rerender from scratch')
+      log('DOM: Rerender the list from scratch')
       while (this.container.firstChild) {
         this.unmountItem(this.container.firstChild)
       }
@@ -89,11 +88,11 @@ export default class VirtualScroller {
       } else {
         const item = this.renderItem(items[i])
         if (shouldPrependItems) {
-          log('Prepend item index', i)
+          log('DOM: Prepend element for item index', i)
           // Append `item` to `this.container` before the retained items.
           this.container.insertBefore(item, prependBeforeItemElement)
         } else {
-          log('Append item index', i)
+          log('DOM: Append element for item index', i)
           // Append `item` to `this.container`.
           this.container.appendChild(item)
         }

package/source/ItemHeights.js

@@ -1,9 +1,8 @@
 import log, { warn, isDebug, reportError } from './utility/debug'
 
 export default class ItemHeights {
-	constructor(screen, getContainerElement, getItemHeight, setItemHeight) {
-		this.screen = screen
-		this.getContainerElement = getContainerElement
+	constructor(container, getItemHeight, setItemHeight) {
+		this.container = container
 		this._get = getItemHeight
 		this._set = setItemHeight
 		this.reset()
@@ -64,13 +63,7 @@ export default class ItemHeights {
 	// }
 
 	_measureItemHeight(i, firstShownItemIndex) {
-		const container = this.getContainerElement()
-		if (container) {
-			const elementIndex = i - firstShownItemIndex
-			if (elementIndex >= 0 && elementIndex < this.screen.getChildElementsCount(container)) {
-				return this.screen.getChildElementHeight(container, elementIndex)
-			}
-		}
+		return this.container.getNthRenderedItemHeight(i - firstShownItemIndex)
 	}
 
 	/**
@@ -92,6 +85,7 @@ export default class ItemHeights {
 	 * @return {number[]} The indexes of the items that have not previously been measured and have been measured now.
 	 */
 	measureItemHeights(firstShownItemIndex, lastShownItemIndex) {
+		log('~ Measure item heights ~')
 		// If no items are rendered, don't measure anything.
 		if (firstShownItemIndex === undefined) {
 			return
@@ -102,8 +96,10 @@ export default class ItemHeights {
 		// then reset `this.measuredItemsHeight` and "first measured"/"last measured" item indexes.
 		// For example, this could happen when `.setItems()` prepends a lot of new items.
 		if (this.firstMeasuredItemIndex !== undefined) {
-			if (firstShownItemIndex > this.lastMeasuredItemIndex + 1 ||
-					lastShownItemIndex < this.firstMeasuredItemIndex - 1) {
+			if (
+				firstShownItemIndex > this.lastMeasuredItemIndex + 1 ||
+				lastShownItemIndex < this.firstMeasuredItemIndex - 1
+			) {
 				// Reset.
 				log('Non-measured items gap detected. Reset first and last measured item indexes.')
 				this.reset()
@@ -115,20 +111,16 @@ export default class ItemHeights {
 		let firstMeasuredItemIndexHasBeenUpdated = false
 		let i = firstShownItemIndex
 		while (i <= lastShownItemIndex) {
+			// Measure item heights that haven't been measured previously.
 			// Don't re-measure item heights that have been measured previously.
 			// The rationale is that developers are supposed to manually call
 			// `.onItemHeightChange()` every time an item's height changes.
-			// If developers aren't neglecting that rule, item heights won't
+			// If developers don't neglect that rule, item heights won't
 			// change unexpectedly.
-			// // Re-measure all shown items' heights, because an item's height
-			// // might have changed since it has been measured initially.
-			// // For example, if an item is a long comment with a "Show more" button,
-			// // then the user might have clicked that "Show more" button.
 			if (this._get(i) === undefined) {
 				nonPreviouslyMeasuredItemIndexes.push(i)
-				log('Item', i, 'hasn\'t been previously measured')
 				const height = this._measureItemHeight(i, firstShownItemIndex)
-				log('Height', height)
+				log('Item index', i, 'height', height)
 				this._set(i, height)
 				// Update average item height calculation variables
 				// related to the previously measured items
@@ -164,14 +156,17 @@ export default class ItemHeights {
 					this.lastMeasuredItemIndex = i
 				}
 			} else {
-				// Validate the item's height right after showing it after being hidden,
-				// because, if the stored item's state isn't applied properly, the item's
-				// height might be incorrect when it's rendered with that state not applied,
-				// and so a developer could know that there's a bug in their code.
+				// Validate that the item's height didn't change since it was last measured.
+				// If it did, then display a warning and update the item's height
+				// as an attempt to fix things.
+				// If an item's height changes unexpectedly then it means that there'll
+				// likely be "content jumping".
 				const previousHeight = this._get(i)
 				const height = this._measureItemHeight(i, firstShownItemIndex)
 				if (previousHeight !== height) {
-					warn('Item', i, 'height was', previousHeight, 'before it was hidden, but, after showing it again, its height is', height, '. Perhaps you forgot to persist the item\'s state by calling `onItemStateChange(i, newState)` when it changed, and that state got lost when the item element was unmounted, which resulted in a different height when the item was shown again, but with the missing state.')
+					warn('Item index', i, 'height changed unexpectedly: it was', previousHeight, 'before, but now it is', height, '. An item\'s height is allowed to change only in two cases: when the item\'s "state" changes and the developer calls `onItemStateChange(i, newState)`, or when the item\'s height changes for some other reason and the developer calls `onItemHeightChange(i)`. Perhaps you forgot to persist the item\'s "state" by calling `onItemStateChange(i, newState)` when it changed, and that "state" got lost when the item element was unmounted, which resulted in a different height when the item was shown again having its "state" reset.')
+					// Update the item's height as an attempt to fix things.
+					this._set(i, height)
 				}
 			}
 			i++