virtual-scroller 1.11.3 → 1.12.0

package/source/ItemNotRenderedError.js

@@ -0,0 +1,16 @@
+export default class ItemNotRenderedError extends Error {
+	constructor({
+		renderedElementIndex,
+		renderedElementsCount,
+		message
+	}) {
+		super(message || getDefaultMessage({ renderedElementIndex, renderedElementsCount }))
+	}
+}
+
+function getDefaultMessage({
+	renderedElementIndex,
+	renderedElementsCount
+}) {
+	return `Element with index ${renderedElementIndex} was not found in the list of Rendered Item Elements in the Items Container of Virtual Scroller. There're only ${renderedElementsCount} Elements there.`
+}

package/source/Layout.test.js

@@ -148,6 +148,10 @@ describe('Layout', function() {
 
 		let shouldResetGridLayout
 
+		const errors = []
+
+		global.VirtualScrollerCatchError = (error) => errors.push(error)
+
 		layout.getLayoutUpdateForItemsDiff(
 			{
 				firstShownItemIndex: 3,
@@ -171,6 +175,11 @@ describe('Layout', function() {
 			afterItemsHeight: 5 * (ITEM_HEIGHT + VERTICAL_SPACING)
 		})
 
+		global.VirtualScrollerCatchError = undefined
+		errors.length.should.equal(2)
+		errors[0].message.should.equal('[virtual-scroller] ~ Prepended items count 5 is not divisible by Columns Count 4 ~')
+		errors[1].message.should.equal('[virtual-scroller] Layout reset required')
+
 		shouldResetGridLayout.should.equal(true)
 	})
 })

package/source/VirtualScroller.js

@@ -35,6 +35,8 @@ export default class VirtualScroller {
 		const isRestart = this._isActive === false
 
 		if (!isRestart) {
+			this.waitingForRender = true
+
 			// If no custom state storage has been configured, use the default one.
 			// Also sets the initial state.
 			if (!this._usesCustomStateStorage) {

package/source/VirtualScroller.layout.js

@@ -7,6 +7,8 @@ import { setTimeout, clearTimeout } from 'request-animation-frame-timeout'
 import log, { warn, isDebug, reportError } from './utility/debug.js'
 import { LAYOUT_REASON } from './Layout.js'
 
+import ItemNotRenderedError from './ItemNotRenderedError.js'
+
 export default function() {
 	this.onUpdateShownItemIndexes = ({ reason, stateUpdate }) => {
 		// In case of "don't do anything".
@@ -149,6 +151,9 @@ export default function() {
 
 		// Set `this.firstNonMeasuredItemIndex`.
 		this.firstNonMeasuredItemIndex = firstNonMeasuredItemIndex
+		// if (firstNonMeasuredItemIndex !== undefined) {
+		// 	log('Non-measured item index that will be measured at next layout', firstNonMeasuredItemIndex)
+		// }
 
 		// Set "previously calculated layout".
 		//
@@ -340,20 +345,21 @@ export default function() {
 	// rather than from scratch, which would be an optimization.
 	//
 	function updatePreviouslyCalculatedLayoutOnItemHeightChange(i, previousHeight, newHeight) {
-		if (this.previouslyCalculatedLayout) {
+		const prevLayout = this.previouslyCalculatedLayout
+		if (prevLayout) {
 			const heightDifference = newHeight - previousHeight
-			if (i < this.previouslyCalculatedLayout.firstShownItemIndex) {
-				// Patch `this.previouslyCalculatedLayout`'s `.beforeItemsHeight`.
-				this.previouslyCalculatedLayout.beforeItemsHeight += heightDifference
-			} else if (i > this.previouslyCalculatedLayout.lastShownItemIndex) {
-				// Could patch `.afterItemsHeight` of `this.previouslyCalculatedLayout` here,
-				// if `.afterItemsHeight` property existed in `this.previouslyCalculatedLayout`.
-				if (this.previouslyCalculatedLayout.afterItemsHeight !== undefined) {
-					this.previouslyCalculatedLayout.afterItemsHeight += heightDifference
+			if (i < prevLayout.firstShownItemIndex) {
+				// Patch `prevLayout`'s `.beforeItemsHeight`.
+				prevLayout.beforeItemsHeight += heightDifference
+			} else if (i > prevLayout.lastShownItemIndex) {
+				// Could patch `.afterItemsHeight` of `prevLayout` here,
+				// if `.afterItemsHeight` property existed in `prevLayout`.
+				if (prevLayout.afterItemsHeight !== undefined) {
+					prevLayout.afterItemsHeight += heightDifference
 				}
 			} else {
-				// Patch `this.previouslyCalculatedLayout`'s shown items height.
-				this.previouslyCalculatedLayout.shownItemsHeight += newHeight - previousHeight
+				// Patch `prevLayout`'s shown items height.
+				prevLayout.shownItemsHeight += newHeight - previousHeight
 			}
 		}
 	}
@@ -371,7 +377,7 @@ export default function() {
 	}
 
 	this._onItemHeightDidChange = (i) => {
-		log('~ Re-measure item height ~')
+		log('~ On Item Height Did Change was called ~')
 		log('Item index', i)
 
 		const {
@@ -412,24 +418,57 @@ export default function() {
 
 		const previousHeight = itemHeights[i]
 		if (previousHeight === undefined) {
-			return reportError(`"onItemHeightDidChange()" has been called for item ${i}, but that item hasn't been rendered before.`)
+			return reportError(`"onItemHeightDidChange()" has been called for item index ${i} but the item hasn't been rendered before.`)
 		}
 
-		const newHeight = remeasureItemHeight.call(this, i)
+		log('~ Re-measure item height ~')
+
+		let newHeight
+
+		try {
+			newHeight = remeasureItemHeight.call(this, i)
+		} catch (error) {
+			// Successfully finishing an `onItemHeightDidChange(i)` call is not considered
+			// critical for `VirtualScroller`'s operation, so such errors could be ignored.
+			if (error instanceof ItemNotRenderedError) {
+				return reportError(`"onItemHeightDidChange()" has been called for item index ${i} but the item is not currently rendered and can\'t be measured. The exact error was: ${error.message}`)
+			}
+		}
 
 		log('Previous height', previousHeight)
 		log('New height', newHeight)
 
 		if (previousHeight !== newHeight) {
-			log('~ Item height has changed ~')
+			log('~ Item height has changed. Should update layout. ~')
 
-			// Update or reset previously calculated layout.
+			// Update or reset a previously calculated layout
+			// so that the "diff"s based on that layout in the future
+			// produce correct results.
 			updatePreviouslyCalculatedLayoutOnItemHeightChange.call(this, i, previousHeight, newHeight)
 
 			// Recalculate layout.
-			this.onUpdateShownItemIndexes({ reason: LAYOUT_REASON.ITEM_HEIGHT_CHANGED })
+			//
+			// If the `VirtualScroller` is already waiting for a state update to be rendered,
+			// delay `onItemHeightDidChange(i)`'s re-layout until that state update is rendered.
+			// The reason is that React `<VirtualScroller/>`'s `onHeightDidChange()` is meant to
+			// be called inside `useLayoutEffect()` hook. Due to how React is implemented internally,
+			// that might happen in the middle of the currently pending `setState()` operation
+			// being applied, resulting in weird "race condition" bugs.
+			//
+			if (this.waitingForRender) {
+				log('~ Another state update is already waiting to be rendered. Delay the layout update until then. ~')
+				this.updateLayoutAfterRenderBecauseItemHeightChanged = true
+			} else {
+				this.onUpdateShownItemIndexes({ reason: LAYOUT_REASON.ITEM_HEIGHT_CHANGED })
+			}
 
-			// Schedule the item height update for after the new items have been rendered.
+			// If there was a request for `setState()` with new `items`, then the changes
+			// to `currentState.itemHeights[]` made above in a `remeasureItemHeight()` call
+			// would be overwritten when that pending `setState()` call gets applied.
+			// To fix that, the updates to current `itemHeights[]` are noted in
+			// `this.itemHeightsThatChangedWhileNewItemsWereBeingRendered` variable.
+			// That variable is then checked when the `setState()` call with the new `items`
+			// has been updated.
 			if (this.newItemsWillBeRendered) {
 				if (!this.itemHeightsThatChangedWhileNewItemsWereBeingRendered) {
 					this.itemHeightsThatChangedWhileNewItemsWereBeingRendered = {}

package/source/VirtualScroller.onRender.js

@@ -1,4 +1,4 @@
-import log, { warn, isDebug } from './utility/debug.js'
+import log, { warn, reportError, isDebug } from './utility/debug.js'
 import getStateSnapshot from './utility/getStateSnapshot.js'
 import shallowEqual from './utility/shallowEqual.js'
 import { LAYOUT_REASON } from './Layout.js'
@@ -11,6 +11,8 @@ export default function() {
 	 * @param  {object} [prevState]
 	 */
 	this._onRender = (newState, prevState) => {
+		this.waitingForRender = false
+
 		log('~ Rendered ~')
 		if (isDebug()) {
 			log('State', getStateSnapshot(newState))
@@ -33,19 +35,58 @@ export default function() {
 			)
 		}
 
-		if (!prevState) {
-			return
+		// `this.mostRecentlySetState` checks that state management behavior is correct:
+		// that in situations when there're multiple new states waiting to be set,
+		// only the latest one gets applied.
+		// It keeps the code simpler and prevents possible race condition bugs.
+		// For example, `VirtualScroller` keeps track of its latest requested
+		// state update in different instance variable flags which assume that
+		// only that latest requested state update gets actually applied.
+		//
+		// This check should also be performed for the initial render in order to
+		// guarantee that no potentially incorrect state update goes unnoticed.
+		// Incorrect state updates could happen when `VirtualScroller` state
+		// is managed externally by passing `getState()`/`updateState()` options.
+		//
+		// Perform the check only when `this.mostRecentSetStateValue` is defined.
+		// `this.mostRecentSetStateValue` is normally gonna be `undefined` at the initial render
+		// because the initial state is not set by calling `this.updateState()`.
+		// At the same time, it is possible that the initial render is delayed
+		// for whatever reason, and `this.updateState()` gets called before the initial render,
+		// so `this.mostRecentSetStateValue` could also be defined at the initial render,
+		// in which case the check should be performed.
+		//
+		if (this.mostRecentSetStateValue) {
+			// "Shallow equality" is used here instead of "strict equality"
+			// because a developer might choose to supply an `updateState()` function
+			// rather than a `setState()` function, in which case the `updateState()` function
+			// would construct its own state object.
+			if (!shallowEqual(newState, this.mostRecentSetStateValue)) {
+				warn('The most recent state that was set', getStateSnapshot(this.mostRecentSetStateValue))
+				reportError('The state that has been rendered is not the most recent one that was set')
+			}
 		}
 
 		// `this.resetStateUpdateFlags()` must be called before calling
 		// `this.measureItemHeightsAndSpacing()`.
 		const {
 			nonMeasuredItemsHaveBeenRendered,
+			itemHeightHasChanged,
 			widthHasChanged
 		} = resetStateUpdateFlags.call(this)
 
 		let layoutUpdateReason
 
+		if (this.updateLayoutAfterRenderBecauseItemHeightChanged) {
+			layoutUpdateReason = LAYOUT_REASON.ITEM_HEIGHT_CHANGED
+		}
+
+		if (!prevState) {
+			if (!layoutUpdateReason) {
+				return
+			}
+		}
+
 		// If the `VirtualScroller`, while calculating layout parameters, encounters
 		// a not-shown item with a non-measured height, it calls `updateState()` just to
 		// render that item first, and then, after the list has been re-rendered, it measures
@@ -74,41 +115,43 @@ export default function() {
 			this.verticalSpacing = undefined
 		}
 
-		const { items: previousItems } = prevState
-		const { items: newItems } = newState
-		// Even if `this.newItemsWillBeRendered` flag is `true`,
-		// `newItems` could still be equal to `previousItems`.
-		// For example, when `updateState()` calls don't update `state` immediately
-		// and a developer first calls `setItems(newItems)` and then calls `setItems(oldItems)`:
-		// in that case, `this.newItemsWillBeRendered` flag will be `true` but the actual `items`
-		// in state wouldn't have changed due to the first `updateState()` call being overwritten
-		// by the second `updateState()` call (that's called "batching state updates" in React).
-		if (newItems !== previousItems) {
-			const itemsDiff = this.getItemsDiff(previousItems, newItems)
-			if (itemsDiff) {
-				// The call to `.onPrepend()` must precede the call to `.measureItemHeights()`
-				// which is called in `.onRender()`.
-				// `this.itemHeights.onPrepend()` updates `firstMeasuredItemIndex`
-				// and `lastMeasuredItemIndex` of `this.itemHeights`.
-				const { prependedItemsCount } = itemsDiff
-				this.itemHeights.onPrepend(prependedItemsCount)
-			} else {
-				this.itemHeights.reset()
-			}
+		if (prevState) {
+			const { items: previousItems } = prevState
+			const { items: newItems } = newState
+			// Even if `this.newItemsWillBeRendered` flag is `true`,
+			// `newItems` could still be equal to `previousItems`.
+			// For example, when `updateState()` calls don't update `state` immediately
+			// and a developer first calls `setItems(newItems)` and then calls `setItems(oldItems)`:
+			// in that case, `this.newItemsWillBeRendered` flag will be `true` but the actual `items`
+			// in state wouldn't have changed due to the first `updateState()` call being overwritten
+			// by the second `updateState()` call (that's called "batching state updates" in React).
+			if (newItems !== previousItems) {
+				const itemsDiff = this.getItemsDiff(previousItems, newItems)
+				if (itemsDiff) {
+					// The call to `.onPrepend()` must precede the call to `.measureItemHeights()`
+					// which is called in `.onRender()`.
+					// `this.itemHeights.onPrepend()` updates `firstMeasuredItemIndex`
+					// and `lastMeasuredItemIndex` of `this.itemHeights`.
+					const { prependedItemsCount } = itemsDiff
+					this.itemHeights.onPrepend(prependedItemsCount)
+				} else {
+					this.itemHeights.reset()
+				}
 
-			if (!widthHasChanged) {
-				// The call to `this.onNewItemsRendered()` must precede the call to
-				// `.measureItemHeights()` which is called in `.onRender()` because
-				// `this.onNewItemsRendered()` updates `firstMeasuredItemIndex` and
-				// `lastMeasuredItemIndex` of `this.itemHeights` in case of a prepend.
-				//
-				// If after prepending items the scroll position
-				// should be "restored" so that there's no "jump" of content
-				// then it means that all previous items have just been rendered
-				// in a single pass, and there's no need to update layout again.
-				//
-				if (onNewItemsRendered.call(this, itemsDiff, newState) !== 'SEAMLESS_PREPEND') {
-					layoutUpdateReason = LAYOUT_REASON.ITEMS_CHANGED
+				if (!widthHasChanged) {
+					// The call to `this.onNewItemsRendered()` must precede the call to
+					// `.measureItemHeights()` which is called in `.onRender()` because
+					// `this.onNewItemsRendered()` updates `firstMeasuredItemIndex` and
+					// `lastMeasuredItemIndex` of `this.itemHeights` in case of a prepend.
+					//
+					// If after prepending items the scroll position
+					// should be "restored" so that there's no "jump" of content
+					// then it means that all previous items have just been rendered
+					// in a single pass, and there's no need to update layout again.
+					//
+					if (onNewItemsRendered.call(this, itemsDiff, newState) !== 'SEAMLESS_PREPEND') {
+						layoutUpdateReason = LAYOUT_REASON.ITEMS_CHANGED
+					}
 				}
 			}
 		}
@@ -124,9 +167,11 @@ export default function() {
 		// item height measurements is required.
 		//
 		if (
-			newState.firstShownItemIndex !== prevState.firstShownItemIndex ||
-			newState.lastShownItemIndex !== prevState.lastShownItemIndex ||
-			newState.items !== prevState.items ||
+			(prevState && (
+				newState.firstShownItemIndex !== prevState.firstShownItemIndex ||
+				newState.lastShownItemIndex !== prevState.lastShownItemIndex ||
+				newState.items !== prevState.items
+			)) ||
 			widthHasChanged
 		) {
 			const verticalSpacingStateUpdate = this.measureItemHeightsAndSpacing()
@@ -202,14 +247,14 @@ export default function() {
 			// See if any items' heights changed while new items were being rendered.
 			if (this.itemHeightsThatChangedWhileNewItemsWereBeingRendered) {
 				for (const i of Object.keys(this.itemHeightsThatChangedWhileNewItemsWereBeingRendered)) {
-					itemHeights[prependedItemsCount + parseInt(i)] = this.itemHeightsThatChangedWhileNewItemsWereBeingRendered[i]
+					itemHeights[prependedItemsCount + Number(i)] = this.itemHeightsThatChangedWhileNewItemsWereBeingRendered[i]
 				}
 			}
 
 			// See if any items' states changed while new items were being rendered.
 			if (this.itemStatesThatChangedWhileNewItemsWereBeingRendered) {
 				for (const i of Object.keys(this.itemStatesThatChangedWhileNewItemsWereBeingRendered)) {
-					itemStates[prependedItemsCount + parseInt(i)] = this.itemStatesThatChangedWhileNewItemsWereBeingRendered[i]
+					itemStates[prependedItemsCount + Number(i)] = this.itemStatesThatChangedWhileNewItemsWereBeingRendered[i]
 				}
 			}
 
@@ -325,6 +370,9 @@ export default function() {
 
 		// Read `this.firstNonMeasuredItemIndex` flag.
 		const nonMeasuredItemsHaveBeenRendered = this.firstNonMeasuredItemIndex !== undefined
+		if (nonMeasuredItemsHaveBeenRendered) {
+			log('Non-measured item index', this.firstNonMeasuredItemIndex)
+		}
 		// Reset `this.firstNonMeasuredItemIndex` flag.
 		this.firstNonMeasuredItemIndex = undefined
 
@@ -337,8 +385,13 @@ export default function() {
 		// Reset `this.itemStatesThatChangedWhileNewItemsWereBeingRendered`.
 		this.itemStatesThatChangedWhileNewItemsWereBeingRendered = undefined
 
+		// Reset `this.updateLayoutAfterRenderBecauseItemHeightChanged`.
+		const itemHeightHasChanged = this.updateLayoutAfterRenderBecauseItemHeightChanged
+		this.updateLayoutAfterRenderBecauseItemHeightChanged = undefined
+
 		return {
 			nonMeasuredItemsHaveBeenRendered,
+			itemHeightHasChanged,
 			widthHasChanged
 		}
 	}

package/source/VirtualScroller.state.js

@@ -52,7 +52,13 @@ export default function createStateHelpers({
 
 		this.getState().itemStates[i] = newItemState
 
-		// Schedule the item state update for after the new items have been rendered.
+		// If there was a request for `setState()` with new `items`, then the changes
+		// to `currentState.itemStates[]` made above would be overwritten when that
+		// pending `setState()` call gets applied.
+		// To fix that, the updates to current `itemStates[]` are noted in
+		// `this.itemStatesThatChangedWhileNewItemsWereBeingRendered` variable.
+		// That variable is then checked when the `setState()` call with the new `items`
+		// has been updated.
 		if (this.newItemsWillBeRendered) {
 			if (!this.itemStatesThatChangedWhileNewItemsWereBeingRendered) {
 				this.itemStatesThatChangedWhileNewItemsWereBeingRendered = {}
@@ -78,9 +84,25 @@ export default function createStateHelpers({
 		}
 		this._isSettingNewItems = undefined
 
-		// Update `state`.
+		this.waitingForRender = true
+
+		// Store previous `state`.
 		this.previousState = this.getState()
-		this._updateState(stateUpdate)
+
+		// If it's the first call to `this.updateState()` then initialize
+		// the most recent `setState()` value to be the current state.
+		if (!this.mostRecentSetStateValue) {
+			this.mostRecentSetStateValue = this.getState()
+		}
+
+		// Accumulates all "pending" state updates until they have been applied.
+		this.mostRecentSetStateValue = {
+			...this.mostRecentSetStateValue,
+			...stateUpdate
+		}
+
+		// Update `state`.
+		this._setState(this.mostRecentSetStateValue, stateUpdate)
 	}
 
 	this.getInitialState = () => {
@@ -92,6 +114,7 @@ export default function createStateHelpers({
 
 	this.useState = ({
 		getState,
+		setState,
 		updateState
 	}) => {
 		if (this._isActive) {
@@ -103,17 +126,28 @@ export default function createStateHelpers({
 		}
 
 		if (render) {
-			throw new Error('[virtual-scroller] Creating a `VirtualScroller` class instance with a `render()` parameter means using the default (internal) state storage')
+			throw new Error('[virtual-scroller] Creating a `VirtualScroller` class instance with a `render()` parameter implies using the default (internal) state storage')
 		}
 
-		if (!getState || !updateState) {
-			throw new Error('[virtual-scroller] When using a custom state storage, one must supply both `getState()` and `updateState()` functions')
+		if (setState && updateState) {
+			throw new Error('[virtual-scroller] When using a custom state storage, one must supply either `setState()` or `updateState()` function but not both')
+		}
+
+		if (!getState || !(setState || updateState)) {
+			throw new Error('[virtual-scroller] When using a custom state storage, one must supply both `getState()` and `setState()`/`updateState()` functions')
 		}
 
 		this._usesCustomStateStorage = true
 
 		this._getState = getState
-		this._updateState = updateState
+
+		this._setState = (newState, stateUpdate) => {
+			if (setState) {
+				setState(newState)
+			} else {
+				updateState(stateUpdate)
+			}
+		}
 	}
 
 	this.useDefaultStateStorage = () => {
@@ -121,9 +155,9 @@ export default function createStateHelpers({
 			throw new Error('[virtual-scroller] When using the default (internal) state management, one must supply a `render(state, prevState)` function parameter')
 		}
 
-		// Create default `getState()`/`updateState()` functions.
+		// Create default `getState()`/`setState()` functions.
 		this._getState = defaultGetState.bind(this)
-		this._updateState = defaultUpdateState.bind(this)
+		this._setState = defaultSetState.bind(this)
 
 		// When `state` is stored externally, a developer is responsible for
 		// initializing it with the initial value.
@@ -140,17 +174,20 @@ export default function createStateHelpers({
 		this.state = newState
 	}
 
-	function defaultUpdateState(stateUpdate) {
-		// Because this variant of `.updateState()` is "synchronous" (immediate),
-		// it can be written like `...prevState`, and no state updates would be lost.
-		// But if it was "asynchronous" (not immediate), then `...prevState`
-		// wouldn't work in all cases, because it could be stale in cases
-		// when more than a single `updateState()` call is made before
-		// the state actually updates, making `prevState` stale.
-		this.state = {
-			...this.state,
-			...stateUpdate
-		}
+	function defaultSetState(newState, stateUpdate) {
+		// // Because the default state updates are "synchronous" (immediate),
+		// // the `...stateUpdate` could be applied over `...this.state`,
+		// // and no state updates would be lost.
+		// // But if it was "asynchronous" (not immediate), then `...this.state`
+		// // wouldn't work in all cases, because it could be stale in cases
+		// // when more than a single `setState()` call is made before
+		// // the state actually updates, making some properties of `this.state` stale.
+		// this.state = {
+		// 	...this.state,
+		// 	...stateUpdate
+		// }
+
+		this.state = newState
 
 		render(this.state, this.previousState)
 

package/source/react/VirtualScroller.js

@@ -8,32 +8,21 @@ import useInstanceMethods from './useInstanceMethods.js'
 import useItemKeys from './useItemKeys.js'
 import useSetItemState from './useSetItemState.js'
 import useOnItemHeightDidChange from './useOnItemHeightDidChange.js'
-import useHandleItemsPropertyChange from './useHandleItemsPropertyChange.js'
-import useHandleItemIndexesChange from './useHandleItemIndexesChange.js'
+import useSetNewItemsOnItemsPropertyChange from './useSetNewItemsOnItemsPropertyChange.js'
+import useUpdateItemKeysOnItemsChange from './useUpdateItemKeysOnItemsChange.js'
 import useClassName from './useClassName.js'
 import useStyle from './useStyle.js'
 
-// When `items` property changes, `useHandleItemsPropertyChange()` hook detects that
-// and calls `VirtualScroller.setItems()` which in turn calls the `updateState()` function.
-// At this point, an insignificant optimization could be applied:
-// the component could avoid re-rendering the second time.
-// Instead, the state update could be applied "immediately" if it originated
-// from `.setItems()` function call, eliminating the unneeded second re-render.
-//
-// I could see how this minor optimization could get brittle when modifiying the code,
-// so I put it under a feature flag so that it could potentially be turned off
-// in case of any potential weird issues in some future.
-//
-// Another reason for using this feature is:
-//
-// Since `useHandleItemsPropertyChange()` runs at render time
-// and not after the render has finished (not in an "effect"),
-// if the state update was done "conventionally" (by calling `_setNewState()`),
-// React would throw an error about updating state during render.
-// No one knows what the original error message was.
-// Perhaps it's no longer relevant in newer versions of React.
-//
-const USE_ITEMS_UPDATE_NO_SECOND_RENDER_OPTIMIZATION = true
+// When `items` property changes:
+// * A new `items` property is supplied to the React component.
+// * The React component re-renders itself.
+// * `useSetNewItemsOnItemsPropertyChange()` hook is run.
+// * `useSetNewItemsOnItemsPropertyChange()` hook detects that the `items` property
+//   has changed and calls `VirtualScroller.setItems(items)`.
+// * `VirtualScroller.setItems(items)` calls `VirtualScroller.setState()`.
+// * `VirtualScroller.setState()` calls the `setState()` function.
+// * The `setState()` function calls a setter from a `useState()` hook.
+// * The React component re-renders itself the second time.
 
 function VirtualScroller({
 	as: AsComponent,
@@ -113,20 +102,19 @@ function VirtualScroller({
 	// This way, React will re-render the component on every state update.
 	const {
 		getState,
-		updateState,
-		getNextState
+		setState,
+		stateToRender
 	} = useState({
 		initialState: _initialState,
 		onRender: virtualScroller.onRender,
-		itemsProperty,
-		USE_ITEMS_UPDATE_NO_SECOND_RENDER_OPTIMIZATION
+		itemsProperty
 	})
 
 	// Use custom (external) state storage in the `VirtualScroller`.
 	useMemo(() => {
 		virtualScroller.useState({
 			getState,
-			updateState
+			setState
 		})
 	}, [])
 
@@ -138,6 +126,7 @@ function VirtualScroller({
 	// "reuse" `itemComponent`s in cases when `items` are changed.
 	const {
 		getItemKey,
+		usesAutogeneratedItemKeys,
 		updateItemKeysForNewItems
 	} = useItemKeys({
 		getItemId
@@ -158,19 +147,18 @@ function VirtualScroller({
 	})
 
 	// Calls `.setItems()` if `items` property has changed.
-	useHandleItemsPropertyChange(itemsProperty, {
+	useSetNewItemsOnItemsPropertyChange(itemsProperty, {
 		virtualScroller,
 		// `preserveScrollPosition` property name is deprecated,
 		// use `preserveScrollPositionOnPrependItems` property instead.
 		preserveScrollPosition,
-		preserveScrollPositionOnPrependItems,
-		nextItems: getNextState().items
+		preserveScrollPositionOnPrependItems
 	})
 
 	// Updates `key`s if item indexes have changed.
-	useHandleItemIndexesChange({
+	useUpdateItemKeysOnItemsChange(stateToRender.items, {
 		virtualScroller,
-		itemsBeingRendered: getNextState().items,
+		usesAutogeneratedItemKeys,
 		updateItemKeysForNewItems
 	})
 
@@ -209,7 +197,7 @@ function VirtualScroller({
 
 	const style = useStyle({
 		tbody,
-		getNextState
+		state: stateToRender
 	})
 
 	const {
@@ -217,7 +205,7 @@ function VirtualScroller({
 		itemStates,
 		firstShownItemIndex,
 		lastShownItemIndex
-	} = getNextState()
+	} = stateToRender
 
 	return (
 		<AsComponent