virtual-scroller 1.7.9 → 1.9.0

package/source/BeforeResize.js

@@ -0,0 +1,312 @@
+import log from './utility/debug.js'
+
+export default class BeforeResize {
+	constructor({
+		getState,
+		getVerticalSpacing,
+		getColumnsCount
+	}) {
+		this.getState = getState
+		this.getVerticalSpacing = getVerticalSpacing
+		this.getColumnsCount = getColumnsCount
+	}
+
+	initializeFromState(state) {
+		this._includesBeforeResizeInState = Boolean(state.beforeResize)
+	}
+
+	// Cleans up "before resize" item heights and adjusts the scroll position accordingly.
+	//
+	// Hypothetically, it could also wait for the user to stop scrolling and only then
+	// adjust the scroll position. The rationale is that if `window.scrollTo()` is called
+	// while the user is scrolling, the user would occasionally experience "lost" mouse wheel
+	// events when scrolling with a mouse wheel.
+	//
+	// Seems like Twitter's website waits for the user to stop scrolling before applying
+	// the scroll position correction after a window resize. This library could do that too,
+	// but that would require rewriting "before items height" top padding calculation
+	// so that it doesn't re-calculate it on every re-render and instead does so incrementally,
+	// and then, when the user stops, it re-calculates it from scratch removing the error
+	// and adjusting the scroll position accordingly so that there's no "jump of content".
+	//
+	// But, seems like it works fine as it is and there's no need to rewrite anything.
+	//
+	cleanUpBeforeResizeItemHeights() {
+		const {
+			firstShownItemIndex,
+			lastShownItemIndex,
+			itemHeights,
+			beforeResize
+		} = this.getState()
+
+		// If there're "before resize" properties in `state`
+		// then it means that the corresponding items are waiting to be
+		// re-measured after container resize. Since the resize,
+		// some of those non-re-measured items might have just been measured,
+		// so see if that's true, and if it is, remove those now-obsolete
+		// "before resize" item heights and ajust the scroll position
+		// so that there's no "content jumping".
+
+		if (beforeResize) {
+			// If the user has scrolled up to reveal a previously hidden item
+			// that has not yet been re-measured after a previous resize.
+			if (firstShownItemIndex < beforeResize.itemHeights.length) {
+				log('~ Clean up "before resize" item heights and correct scroll position ~')
+
+				// Some of the "before" items have been un-hidden and re-measured.
+				// Un-hiding those items would result in a "jump of content"
+				// because "before resize" heights of those un-hidden items
+				// could (and most likely will) be different from the current ones,
+				// or because "before resize" columns count is different from
+				// the current one.
+				// To prevent a "jump of content", calculate the scroll position
+				// difference and adjust the scroll position.
+
+				// The height of the item rows that have transitioned
+				// from hidden to shown.
+				let newlyShownItemRowsHeight = 0
+
+				// Some of the `itemHeights` between the current `firstShownItemIndex` and
+				// the previous `firstShownItemIndex` could stay `undefined` if the user
+				// scrolled "abruptly": for example, by using a `window.scrollTo()` call.
+				// In that case, the items below the visible ones won't be rendered and measured.
+				// In such case, limit the items being iterated over to the current `lastShownItemIndex`
+				// rather than the previous `firstShownItemIndex`.
+				const prevFirstReMeasuredItemsRowIndex = Math.floor(beforeResize.itemHeights.length / this.getColumnsCount())
+				const newlyShownItemsToIndex = Math.min(
+					prevFirstReMeasuredItemsRowIndex * this.getColumnsCount() - 1,
+					lastShownItemIndex
+				)
+
+				let i = firstShownItemIndex
+				while (i <= newlyShownItemsToIndex) {
+					// Calculate newly shown row height.
+					let rowHeight = 0
+					let columnIndex = 0
+					while (columnIndex < this.getColumnsCount() && i <= newlyShownItemsToIndex) {
+						let itemHeight = itemHeights[i]
+						if (itemHeight === undefined) {
+							// `itemHeight` can only be `undefined` when not `beforeResize`.
+							// Use the current "average item height" as a substitute.
+							itemHeight = this.getAverageItemHeight()
+						}
+						rowHeight = Math.max(rowHeight, itemHeight)
+						i++
+						columnIndex++
+					}
+					// Append to the total "newly shown item rows height".
+					newlyShownItemRowsHeight += rowHeight
+					newlyShownItemRowsHeight += this.getVerticalSpacing()
+				}
+
+				// The height of the "before resize" item rows
+				// that will be "cleaned up" in this function call.
+				let cleanedUpBeforeResizeItemRowsHeight = 0
+
+				// Some of the `beforeResize` item rows might have been skipped if the user
+				// scrolled up "abruptly": for example, by using a `window.scrollTo()` call.
+				// In that case, the "before resize" items below the bottom border of the screen
+				// shouldn't be accounted for when calculating the scrollbar adjustment shift
+				// because items after `lastShownItemIndex` aren't participating in the calculation
+				// of `newlyShownItemRowsHeight`.
+				const maxParticipatingBeforeResizeItemsCount = Math.min(beforeResize.itemHeights.length, lastShownItemIndex + 1)
+				const participatingBeforeResizeItemRowsCount = Math.ceil(maxParticipatingBeforeResizeItemsCount / beforeResize.columnsCount)
+
+				const firstCleanedUpBeforeResizeItemsRowIndex = firstShownItemIndex === 0
+					? 0
+					: Math.floor((firstShownItemIndex - 1) / beforeResize.columnsCount) + 1
+
+				let k = firstCleanedUpBeforeResizeItemsRowIndex
+				while (k < participatingBeforeResizeItemRowsCount) {
+					const rowHeight = beforeResize.itemHeights[k * beforeResize.columnsCount]
+					cleanedUpBeforeResizeItemRowsHeight += rowHeight
+					cleanedUpBeforeResizeItemRowsHeight += beforeResize.verticalSpacing
+					k++
+				}
+
+				// Schedule an asynchronous `this.updateState()` call that will update
+				// `beforeResize` property of `state`. Ideally, it should be updated
+				// immediately, but since `this.updateState()` calls are asynchronous,
+				// the code updates just the underlying `beforeResize.itemHeights`
+				// array immediately instead, which is still a hack but still a lesser one.
+				if (firstShownItemIndex === 0) {
+					log('Drop all "before resize" item heights')
+				} else {
+					const firstDroppedBeforeResizeItemIndex = firstShownItemIndex
+					const lastDroppedBeforeResizeItemIndex = beforeResize.itemHeights.length - 1
+					if (firstDroppedBeforeResizeItemIndex === lastDroppedBeforeResizeItemIndex) {
+						log('For item index', firstDroppedBeforeResizeItemIndex, '— drop "before resize" height', beforeResize.itemHeights[firstDroppedBeforeResizeItemIndex], )
+					} else {
+						log('For item indexes from', firstDroppedBeforeResizeItemIndex, 'to', lastDroppedBeforeResizeItemIndex, '— drop "before resize" heights', beforeResize.itemHeights.slice(firstDroppedBeforeResizeItemIndex))
+					}
+				}
+
+				// Immediately update `beforeResize.itemHeights`
+				// so that the component isn't left in an inconsistent state
+				// before a `this.updateState()` call below is applied.
+				beforeResize.itemHeights.splice(
+					firstShownItemIndex,
+					beforeResize.itemHeights.length - firstShownItemIndex
+				)
+
+				// Return the "scroll by" amount that would correct the scroll position.
+				// Also return a state update.
+				return {
+					scrollBy: newlyShownItemRowsHeight - cleanedUpBeforeResizeItemRowsHeight,
+					beforeResize: firstShownItemIndex === 0 ? undefined : {
+						// Simply change the "reference" to `beforeResize` while leaving
+						// its contents unchanged. That simply indicates that it has been updated:
+						// `beforeResize.itemHeights` array length has been changed "directly".
+						...beforeResize
+					}
+				}
+			}
+		}
+	}
+
+	// Snapshots "before resize" values in order to preserve the currently
+	// shown items' vertical position on screen so that there's no "content jumping".
+	//
+	// `newFirstShownItemIndex` is `> 0`.
+	//
+	snapshotBeforeResizeItemHeights({
+		firstShownItemIndex,
+		newFirstShownItemIndex,
+		newColumnsCount
+	}) {
+		const columnsCount = this.getColumnsCount()
+		const verticalSpacing = this.getVerticalSpacing()
+
+		this._includesBeforeResizeInState = true
+
+		const {
+			beforeResize: prevBeforeResize,
+			itemHeights
+		} = this.getState()
+
+		const prevBeforeResizeItemsCount = prevBeforeResize
+			? prevBeforeResize.itemHeights.length
+			: 0
+
+		// If there already are "before resize" values in `state`
+		// then it means that those should be merged with the new ones.
+		//
+		// `beforeResize.itemHeights` could be empty in an edge case
+		// when there's a pending state update that sets `beforeResize`
+		// to `undefined`, and in that case empty `beforeResize.itemHeights`
+		// signals about that type of a situation.
+		//
+		if (prevBeforeResizeItemsCount > 0) {
+			// Because the "previous" before resize values might have been captured
+			// for a window width corresponding to a layout with a different columns count
+			// and different vertical spacing, re-calculate those item heights as if
+			// they corresponded to the current columns count and current vertical spacing,
+			// since "previous" and "new" before resize item heights are gonna be merged.
+			if (
+				prevBeforeResize.columnsCount !== columnsCount ||
+				prevBeforeResize.verticalSpacing !== verticalSpacing
+			) {
+				let prevBeforeResizeBeforeItemsHeight = 0
+
+				const prevBeforeResizeItemRowsCount = Math.ceil(prevBeforeResizeItemsCount / prevBeforeResize.columnsCount)
+				let rowIndex = 0
+				while (rowIndex < prevBeforeResizeItemRowsCount) {
+					// Since all "before resize" item heights are equal within a row,
+					// the height of the first "before resize" item in a row is that row's height.
+					const rowHeight = prevBeforeResize.itemHeights[rowIndex * prevBeforeResize.columnsCount]
+					prevBeforeResizeBeforeItemsHeight += rowHeight
+					prevBeforeResizeBeforeItemsHeight += prevBeforeResize.verticalSpacing
+					rowIndex++
+				}
+
+				let newBeforeResizeAdditionalBeforeItemsHeight = 0
+				let i = firstShownItemIndex
+				while (i < newFirstShownItemIndex) {
+					let rowHeight = 0
+					let k = 0
+					while (k < columnsCount && i < newFirstShownItemIndex) {
+						rowHeight = Math.max(rowHeight, itemHeights[i])
+						k++
+						i++
+					}
+					newBeforeResizeAdditionalBeforeItemsHeight += rowHeight
+					newBeforeResizeAdditionalBeforeItemsHeight += verticalSpacing
+				}
+
+				const newBeforeResizeBeforeItemsHeight = prevBeforeResizeBeforeItemsHeight + newBeforeResizeAdditionalBeforeItemsHeight
+				const newBeforeResizeBeforeItemRowsCount = Math.ceil(newFirstShownItemIndex / columnsCount)
+
+				return new Array(newFirstShownItemIndex).fill(
+					// Re-calculate "before resize" item heights so that "previous" and "new" ones
+					// correspond to the same (new) columns count.
+					// Also don't occasionally set item heights to `< 0`.
+					Math.max(0, newBeforeResizeBeforeItemsHeight / newBeforeResizeBeforeItemRowsCount - verticalSpacing)
+				)
+			} else {
+				// Add new item heights to the previously snapshotted ones.
+				return prevBeforeResize.itemHeights.concat(
+					equalizeItemHeights(
+						itemHeights,
+						newFirstShownItemIndex,
+						columnsCount
+					).slice(prevBeforeResize.itemHeights.length)
+				)
+			}
+		} else {
+			return equalizeItemHeights(
+				itemHeights,
+				newFirstShownItemIndex,
+				columnsCount
+			)
+		}
+	}
+
+	shouldIncludeBeforeResizeValuesInState() {
+		return this._includesBeforeResizeInState
+	}
+}
+
+// Equalizes all item heights within a given row, for each row.
+//
+// The reason is that `beforeResize.itemHeights` is not necessarily divisible by
+// `beforeResize.columnsCount`, which would result in varying last row height
+// as items get removed from `beforeResize.itemHeights` as the user scrolls up.
+//
+// By equalizing all item heights within a given row, for each row, such "jumping"
+// last "before resize" row height is prevented when the user scrolls up.
+//
+function equalizeItemHeights(itemHeights, maxItemsCount, columnsCount) {
+	itemHeights = itemHeights.slice(0, Math.ceil(maxItemsCount / columnsCount) * columnsCount)
+
+	let rowIndex = 0
+	while (rowIndex * columnsCount < maxItemsCount) {
+		// Calculate row height.
+		let rowHeight = 0
+		let k = 0
+		while (k < columnsCount) {
+			rowHeight = Math.max(rowHeight, itemHeights[rowIndex * columnsCount + k])
+			k++
+		}
+
+		// Equalize all item heights within the row.
+		k = 0
+		while (k < columnsCount) {
+			itemHeights[rowIndex * columnsCount + k] = rowHeight
+			k++
+		}
+
+		// Proceed with the next row.
+		rowIndex++
+	}
+
+	return itemHeights.slice(0, maxItemsCount)
+}
+
+export function cleanUpBeforeResizeState(state) {
+	if (state.beforeResize) {
+		if (state.beforeResize.itemHeights.length === 0) {
+			state.beforeResize = undefined
+		}
+	}
+	return state
+}

package/source/DOM/Engine.js

@@ -0,0 +1,30 @@
+import ItemsContainer from './ItemsContainer.js'
+import ScrollableContainer, { ScrollableWindowContainer } from './ScrollableContainer.js'
+import ListTopOffsetWatcher from './ListTopOffsetWatcher.js'
+
+export default {
+	createItemsContainer(getItemsContainerElement) {
+		return new ItemsContainer(getItemsContainerElement)
+	},
+
+	// Creates a `scrollableContainer`.
+	// On client side, `scrollableContainer` is always created.
+	// On server side, `scrollableContainer` is not created (and not used).
+	createScrollableContainer(getScrollableContainerElement, getItemsContainerElement) {
+		if (getScrollableContainerElement) {
+			return new ScrollableContainer(getScrollableContainerElement, getItemsContainerElement)
+		} else if (typeof window !== 'undefined') {
+			return new ScrollableWindowContainer(getItemsContainerElement)
+		}
+	},
+
+	watchListTopOffset({
+		getListTopOffset,
+		onListTopOffsetChange
+	}) {
+		return new ListTopOffsetWatcher({
+			getListTopOffset,
+			onListTopOffsetChange
+		})
+	}
+}

package/source/DOM/ItemsContainer.js

@@ -0,0 +1,48 @@
+export default class ItemsContainer {
+	/**
+	 * Constructs a new "container" from an element.
+	 * @param {function} getElement
+	 */
+	constructor(getElement) {
+		this.getElement = getElement
+	}
+
+	/**
+	 * Returns an item element's "top offset", relative to the items `container`'s top edge.
+	 * @param  {number} renderedElementIndex — An index of an item relative to the "first shown item index". For example, if the list is showing items from index 8 to index 12 then `renderedElementIndex = 0` would mean the item at index `8`.
+	 * @return {number}
+	 */
+	getNthRenderedItemTopOffset(renderedElementIndex) {
+		return this.getElement().childNodes[renderedElementIndex].getBoundingClientRect().top - this.getElement().getBoundingClientRect().top
+	}
+
+	/**
+	 * Returns an item element's height.
+	 * @param  {number} renderedElementIndex — An index of an item relative to the "first shown item index". For example, if the list is showing items from index 8 to index 12 then `renderedElementIndex = 0` would mean the item at index `8`.
+	 * @return {number}
+	 */
+	getNthRenderedItemHeight(renderedElementIndex) {
+		// `offsetHeight` is not precise enough (doesn't return fractional pixels).
+		// return this.getElement().childNodes[renderedElementIndex].offsetHeight
+		return this.getElement().childNodes[renderedElementIndex].getBoundingClientRect().height
+	}
+
+	/**
+	 * Returns items container height.
+	 * @return {number}
+	 */
+	getHeight() {
+		// `offsetHeight` is not precise enough (doesn't return fractional pixels).
+		// return this.getElement().offsetHeight
+		return this.getElement().getBoundingClientRect().height
+	}
+
+	/**
+	 * Removes all item elements of an items container.
+	 */
+	clear() {
+		while (this.getElement().firstChild) {
+			this.getElement().removeChild(this.getElement().firstChild)
+		}
+	}
+}

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

@@ -4,47 +4,73 @@
 // 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/>`
+//
+// 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
+// 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()
 		}
@@ -52,13 +78,21 @@ export default class WaitForStylesToLoad {
 	}
 
 	start() {
-		this.isRendered = true
+		this._isActive = true
 		this.watchListTopOffset()
 	}
 
+	isStarted() {
+		return this._isActive
+	}
+
 	stop() {
-		this.isRendered = false
-		clearTimeout(this.watchListTopOffsetTimer)
+		this._isActive = false
+
+		if (this.watchListTopOffsetTimer) {
+			clearTimeout(this.watchListTopOffsetTimer)
+			this.watchListTopOffsetTimer = undefined
+		}
 	}
 
 	watchListTopOffset() {
@@ -66,17 +100,17 @@ export default class WaitForStylesToLoad {
 		const check = () => {
 			// If `VirtualScroller` has been unmounted
 			// while `setTimeout()` was waiting, then exit.
-			if (!this.isRendered) {
+			if (!this._isActive) {
 				return
 			}
 			// 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 +127,4 @@ export default class WaitForStylesToLoad {
 		// Run the cycle.
 		check()
 	}
-}
-
-const WATCH_LIST_TOP_OFFSET_INTERVAL = 500
-const WATCH_LIST_TOP_OFFSET_MAX_DURATION = 3000
+}