virtual-scroller 1.11.2 → 1.12.0

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

@@ -7,33 +7,22 @@ import useVirtualScrollerStartStop from './useVirtualScrollerStartStop.js'
 import useInstanceMethods from './useInstanceMethods.js'
 import useItemKeys from './useItemKeys.js'
 import useSetItemState from './useSetItemState.js'
-import useOnItemHeightChange from './useOnItemHeightChange.js'
-import useHandleItemsPropertyChange from './useHandleItemsPropertyChange.js'
-import useHandleItemIndexesChange from './useHandleItemIndexesChange.js'
+import useOnItemHeightDidChange from './useOnItemHeightDidChange.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
@@ -150,27 +139,26 @@ function VirtualScroller({
 		virtualScroller
 	})
 
-	// Cache per-item `onItemHeightChange` functions' "references"
+	// Cache per-item `onItemHeightDidChange` functions' "references"
 	// so that item components don't get re-rendered needlessly.
-	const getOnItemHeightChange = useOnItemHeightChange({
+	const getOnItemHeightDidChange = useOnItemHeightDidChange({
 		initialItemsCount: itemsProperty.length,
 		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
@@ -251,7 +239,8 @@ function VirtualScroller({
 							state={itemStates && itemStates[i]}
 							setState={getSetItemState(i)}
 							onStateChange={getSetItemState(i)}
-							onHeightChange={getOnItemHeightChange(i)}>
+							onHeightChange={getOnItemHeightDidChange(i)}
+							onHeightDidChange={getOnItemHeightDidChange(i)}>
 							{item}
 						</Component>
 					)

package/source/react/useItemKeys.js

@@ -1,3 +1,5 @@
+import log from '../utility/debug.js'
+
 import { useRef, useMemo, useCallback } from 'react'
 
 export default function useItemKeys({ getItemId }) {
@@ -27,12 +29,16 @@ export default function useItemKeys({ getItemId }) {
 		generateItemKeyPrefix()
 	}, [])
 
+	// If `getItemId()` function is defined, then item `id`s are gonna be the item element `key`s.
+	const usesAutogeneratedItemKeys = !getItemId
+
 	const generateItemKeyPrefixIfNotUsingItemIds = useCallback(() => {
-		if (!getItemId) {
+		if (usesAutogeneratedItemKeys) {
 			generateItemKeyPrefix()
+			log('React: ~ Item key prefix:', itemKeyPrefix.current)
 		}
 	}, [
-		getItemId,
+		usesAutogeneratedItemKeys,
 		generateItemKeyPrefix
 	])
 
@@ -54,6 +60,7 @@ export default function useItemKeys({ getItemId }) {
 
 	return {
 		getItemKey,
+		usesAutogeneratedItemKeys,
 		updateItemKeysForNewItems: generateItemKeyPrefixIfNotUsingItemIds
 	}
 }

package/source/react/useOnChange.js

@@ -0,0 +1,11 @@
+import { useRef } from 'react'
+
+export default function useOnChange(value, onChange) {
+	const previousValueRef = useRef(value)
+	const previousValue = previousValueRef.current
+	previousValueRef.current = value
+
+	if (value !== previousValue) {
+		onChange(value, previousValue)
+	}
+}

package/source/react/{useOnItemHeightChange.js → useOnItemHeightDidChange.js}

@@ -1,6 +1,6 @@
 import { useMemo, useRef, useCallback } from 'react'
 
-export default function useOnItemHeightChange({
+export default function useOnItemHeightDidChange({
 	initialItemsCount,
 	virtualScroller
 }) {
@@ -12,11 +12,11 @@ export default function useOnItemHeightChange({
 	// Handler functions cache.
 	const cache = useRef(initialCacheValue)
 
-	// Caches per-item `onItemHeightChange` functions' "references"
+	// Caches per-item `onItemHeightDidChange` functions' "references"
 	// so that item components don't get re-rendered needlessly.
-	const getOnItemHeightChange = useCallback((i) => {
+	const getOnItemHeightDidChange = useCallback((i) => {
 		if (!cache.current[i]) {
-			cache.current[i] = () => virtualScroller.onItemHeightChange(i)
+			cache.current[i] = () => virtualScroller.onItemHeightDidChange(i)
 		}
 		return cache.current[i]
 	}, [
@@ -24,5 +24,5 @@ export default function useOnItemHeightChange({
 		cache
 	])
 
-	return getOnItemHeightChange
+	return getOnItemHeightDidChange
 }

package/source/react/{useHandleItemsPropertyChange.js → useSetNewItemsOnItemsPropertyChange.js}

@@ -1,4 +1,6 @@
-import { useRef } from 'react'
+import log from '../utility/debug.js'
+
+import useOnChange from './useOnChange.js'
 
 // If new `items` property is passed:
 //
@@ -8,13 +10,12 @@ import { useRef } from 'react'
 //
 // * Call `VirtualScroller.setItems()` function.
 //
-export default function useHandleItemsPropertyChange(itemsProperty, {
+export default function useSetNewItemsOnItemsPropertyChange(itemsProperty, {
 	virtualScroller,
 	// `preserveScrollPosition` property name is deprecated,
 	// use `preserveScrollPositionOnPrependItems` property instead.
 	preserveScrollPosition,
-	preserveScrollPositionOnPrependItems,
-	nextItems
+	preserveScrollPositionOnPrependItems
 }) {
 	// During render, check if the `items` list has changed.
 	// If it has, capture the Y scroll position and updated item element `key`s.
@@ -60,15 +61,13 @@ export default function useHandleItemsPropertyChange(itemsProperty, {
 	// scroll Y position is captured while the "Show previous" button
 	// is still being shown.
 
-	const previousItemsProperty = useRef(itemsProperty)
-	const hasItemsPropertyChanged = itemsProperty !== previousItemsProperty.current
-	previousItemsProperty.current = itemsProperty
+	useOnChange(itemsProperty, (itemsProperty, prevItemsProperty) => {
+		log('React: ~ Different `items` property has been passed', itemsProperty)
 
-	if (hasItemsPropertyChanged) {
 		let shouldUpdateItems = true
 
 		// Analyze the upcoming `items` change.
-		const itemsDiff = virtualScroller.getItemsDiff(nextItems, itemsProperty)
+		const itemsDiff = virtualScroller.getItemsDiff(prevItemsProperty, itemsProperty)
 
 		// `itemsDiff` will be `undefined` in case of a non-incremental items list change.
 		if (itemsDiff) {
@@ -79,12 +78,13 @@ export default function useHandleItemsPropertyChange(itemsProperty, {
 			if (prependedItemsCount === 0 && appendedItemsCount === 0) {
 				// The items order hasn't changed.
 				// No need to update them in `VirtualScroller` or to snapshot the Y scroll position.
+				log('React: ~ The `items` elements are identical to the previous ones')
 				shouldUpdateItems = false
 			}
 		}
 
 		if (shouldUpdateItems) {
-			// Request to update the `items` in `VirtualScroller`.
+			// Make a request to update the `items` in `VirtualScroller`.
 			// This will result in a `setState()` call.
 			// The new items won't be rendered until that state update is applied.
 			virtualScroller.setItems(itemsProperty, {
@@ -93,5 +93,5 @@ export default function useHandleItemsPropertyChange(itemsProperty, {
 				preserveScrollPositionOnPrependItems: preserveScrollPositionOnPrependItems || preserveScrollPosition
 			})
 		}
-	}
+	})
 }