virtual-scroller 1.11.1 → 1.11.3

package/source/VirtualScroller.layout.js

@@ -99,7 +99,7 @@ export default function() {
 		// or an "Expand YouTube video" button, which would result
 		// in the actual height of the list item being different
 		// from what has been initially measured in `this.itemHeights[i]`,
-		// if the developer didn't call `.setItemState(i, newState)` and `.onItemHeightChange(i)`.
+		// if the developer didn't call `.setItemState(i, newState)` and `.onItemHeightDidChange(i)`.
 		if (!validateWillBeHiddenItemHeightsAreAccurate.call(this, firstShownItemIndex, lastShownItemIndex)) {
 			log('~ Because some of the will-be-hidden item heights (listed above) have changed since they\'ve last been measured, redo layout. ~')
 			// Redo layout, now with the correct item heights.
@@ -172,9 +172,9 @@ export default function() {
 			// Instead of using a `this.previouslyCalculatedLayout` instance variable,
 			// this code could use `this.getState()` because it reflects what's currently on screen,
 			// but there's a single edge case when it could go out of sync —
-			// updating item heights externally via `.onItemHeightChange(i)`.
+			// updating item heights externally via `.onItemHeightDidChange(i)`.
 			//
-			// If, for example, an item height was updated externally via `.onItemHeightChange(i)`
+			// If, for example, an item height was updated externally via `.onItemHeightDidChange(i)`
 			// then `this.getState().itemHeights` would get updated immediately but
 			// `this.getState().beforeItemsHeight` or `this.getState().afterItemsHeight`
 			// would still correspond to the previous item height, so those would be "stale".
@@ -269,7 +269,7 @@ export default function() {
 	 * or an "Expand YouTube video" button, which would result
 	 * in the actual height of the list item being different
 	 * from what has been initially measured in `this.itemHeights[i]`,
-	 * if the developer didn't call `.setItemState(i, newState)` and `.onItemHeightChange(i)`.
+	 * if the developer didn't call `.setItemState(i, newState)` and `.onItemHeightDidChange(i)`.
 	 */
 	function validateWillBeHiddenItemHeightsAreAccurate(firstShownItemIndex, lastShownItemIndex) {
 		let isValid = true
@@ -281,26 +281,26 @@ export default function() {
 				// The item will be hidden. Re-measure its height.
 				// The rationale is that there could be a situation when an item's
 				// height has changed, and the developer has properly added an
-				// `.onItemHeightChange(i)` call to notify `VirtualScroller`
+				// `.onItemHeightDidChange(i)` call to notify `VirtualScroller`
 				// about that change, but at the same time that wouldn't work.
 				// For example, suppose there's a list of several items on a page,
 				// and those items are in "minimized" state (having height 100px).
 				// Then, a user clicks an "Expand all items" button, and all items
 				// in the list are expanded (expanded item height is gonna be 700px).
-				// `VirtualScroller` demands that `.onItemHeightChange(i)` is called
+				// `VirtualScroller` demands that `.onItemHeightDidChange(i)` is called
 				// in such cases, and the developer has properly added the code to do that.
 				// So, if there were 10 "minimized" items visible on a page, then there
-				// will be 10 individual `.onItemHeightChange(i)` calls. No issues so far.
-				// But, as the first `.onItemHeightChange(i)` call executes, it immediately
+				// will be 10 individual `.onItemHeightDidChange(i)` calls. No issues so far.
+				// But, as the first `.onItemHeightDidChange(i)` call executes, it immediately
 				// ("synchronously") triggers a re-layout, and that re-layout finds out
 				// that now, because the first item is big, it occupies most of the screen
 				// space, and only the first 3 items are visible on screen instead of 10,
 				// and so it leaves the first 3 items mounted and unmounts the rest 7.
 				// Then, after `VirtualScroller` has rerendered, the code returns to
-				// where it was executing, and calls `.onItemHeightChange(i)` for the
+				// where it was executing, and calls `.onItemHeightDidChange(i)` for the
 				// second item. It also triggers an immediate re-layout that finds out
 				// that only the first 2 items are visible on screen, and it unmounts
-				// the third one too. After that, it calls `.onItemHeightChange(i)`
+				// the third one too. After that, it calls `.onItemHeightDidChange(i)`
 				// for the third item, but that item is no longer rendered, so its height
 				// can't be measured, and the same's for all the rest of the original 10 items.
 				// So, even though the developer has written their code properly, the
@@ -318,7 +318,7 @@ export default function() {
 						updatePreviouslyCalculatedLayoutOnItemHeightChange.call(this, i, previouslyMeasuredItemHeight, actualItemHeight)
 					}
 					isValid = false
-					warn('Item index', i, 'is no longer visible and will be unmounted. Its height has changed from', previouslyMeasuredItemHeight, 'to', actualItemHeight, 'since it was last measured. This is not necessarily a bug, and could happen, for example, on screen width change, or when there\'re several `onItemHeightChange(i)` calls issued at the same time, and the first one triggers a re-layout before the rest of them have had a chance to be executed.')
+					warn('Item index', i, 'is no longer visible and will be unmounted. Its height has changed from', previouslyMeasuredItemHeight, 'to', actualItemHeight, 'since it was last measured. This is not necessarily a bug, and could happen, for example, on screen width change, or when there\'re several `onItemHeightDidChange(i)` calls issued at the same time, and the first one triggers a re-layout before the rest of them have had a chance to be executed.')
 				}
 			}
 			i++
@@ -370,9 +370,9 @@ export default function() {
 		return listTopOffset
 	}
 
-	this._onItemHeightChange = (i) => {
+	this._onItemHeightDidChange = (i) => {
 		log('~ Re-measure item height ~')
-		log('Item', i)
+		log('Item index', i)
 
 		const {
 			itemHeights,
@@ -383,36 +383,36 @@ export default function() {
 		// Check if the item is still rendered.
 		if (!(i >= firstShownItemIndex && i <= lastShownItemIndex)) {
 			// There could be valid cases when an item is no longer rendered
-			// by the time `.onItemHeightChange(i)` gets called.
+			// by the time `.onItemHeightDidChange(i)` gets called.
 			// For example, suppose there's a list of several items on a page,
 			// and those items are in "minimized" state (having height 100px).
 			// Then, a user clicks an "Expand all items" button, and all items
 			// in the list are expanded (expanded item height is gonna be 700px).
-			// `VirtualScroller` demands that `.onItemHeightChange(i)` is called
+			// `VirtualScroller` demands that `.onItemHeightDidChange(i)` is called
 			// in such cases, and the developer has properly added the code to do that.
 			// So, if there were 10 "minimized" items visible on a page, then there
-			// will be 10 individual `.onItemHeightChange(i)` calls. No issues so far.
-			// But, as the first `.onItemHeightChange(i)` call executes, it immediately
+			// will be 10 individual `.onItemHeightDidChange(i)` calls. No issues so far.
+			// But, as the first `.onItemHeightDidChange(i)` call executes, it immediately
 			// ("synchronously") triggers a re-layout, and that re-layout finds out
 			// that now, because the first item is big, it occupies most of the screen
 			// space, and only the first 3 items are visible on screen instead of 10,
 			// and so it leaves the first 3 items mounted and unmounts the rest 7.
 			// Then, after `VirtualScroller` has rerendered, the code returns to
-			// where it was executing, and calls `.onItemHeightChange(i)` for the
+			// where it was executing, and calls `.onItemHeightDidChange(i)` for the
 			// second item. It also triggers an immediate re-layout that finds out
 			// that only the first 2 items are visible on screen, and it unmounts
-			// the third one too. After that, it calls `.onItemHeightChange(i)`
+			// the third one too. After that, it calls `.onItemHeightDidChange(i)`
 			// for the third item, but that item is no longer rendered, so its height
 			// can't be measured, and the same's for all the rest of the original 10 items.
 			// So, even though the developer has written their code properly, there're
 			// still situations when the item could be no longer rendered by the time
-			// `.onItemHeightChange(i)` gets called.
-			return warn('The item is no longer rendered. This is not necessarily a bug, and could happen, for example, when there\'re several `onItemHeightChange(i)` calls issued at the same time.')
+			// `.onItemHeightDidChange(i)` gets called.
+			return warn('The item is no longer rendered. This is not necessarily a bug, and could happen, for example, when when a developer calls `onItemHeightDidChange(i)` while looping through a batch of items.')
 		}
 
 		const previousHeight = itemHeights[i]
 		if (previousHeight === undefined) {
-			return reportError(`"onItemHeightChange()" has been called for item ${i}, but that item hasn't been rendered before.`)
+			return reportError(`"onItemHeightDidChange()" has been called for item ${i}, but that item hasn't been rendered before.`)
 		}
 
 		const newHeight = remeasureItemHeight.call(this, i)

package/source/VirtualScroller.state.js

@@ -40,7 +40,7 @@ export default function createStateHelpers({
 	this._setItemState = (i, newItemState) => {
 		if (isDebug()) {
 			log('~ Item state changed ~')
-			log('Item', i)
+			log('Item index', i)
 			// Uses `JSON.stringify()` here instead of just outputting the JSON objects as is
 			// because outputting JSON objects as is would show different results later when
 			// the developer inspects those in the web browser console if those state objects

package/source/react/VirtualScroller.js

@@ -7,14 +7,37 @@ 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 useHandleItemsChange from './useHandleItemsChange.js'
+import useOnItemHeightDidChange from './useOnItemHeightDidChange.js'
+import useHandleItemsPropertyChange from './useHandleItemsPropertyChange.js'
+import useHandleItemIndexesChange from './useHandleItemIndexesChange.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
+
 function VirtualScroller({
 	as: AsComponent,
-	items,
+	items: itemsProperty,
 	itemComponent: Component,
 	itemComponentProps,
 	// `estimatedItemHeight` property name is deprecated,
@@ -52,7 +75,7 @@ function VirtualScroller({
 
 	// Create a `VirtualScroller` instance.
 	const virtualScroller = useVirtualScroller({
-		items,
+		items: itemsProperty,
 		// `estimatedItemHeight` property name is deprecated,
 		// use `getEstimatedItemHeight` property instead.
 		estimatedItemHeight,
@@ -90,11 +113,13 @@ function VirtualScroller({
 	// This way, React will re-render the component on every state update.
 	const {
 		getState,
-		updateState
+		updateState,
+		getNextState
 	} = useState({
 		initialState: _initialState,
 		onRender: virtualScroller.onRender,
-		items
+		itemsProperty,
+		USE_ITEMS_UPDATE_NO_SECOND_RENDER_OPTIMIZATION
 	})
 
 	// Use custom (external) state storage in the `VirtualScroller`.
@@ -121,24 +146,31 @@ function VirtualScroller({
 	// Cache per-item `setItemState` functions' "references"
 	// so that item components don't get re-rendered needlessly.
 	const getSetItemState = useSetItemState({
-		items,
+		initialItemsCount: itemsProperty.length,
 		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({
-		items,
+	const getOnItemHeightDidChange = useOnItemHeightDidChange({
+		initialItemsCount: itemsProperty.length,
 		virtualScroller
 	})
 
-	// Detect if `items` have changed.
-	useHandleItemsChange(items, {
+	// Calls `.setItems()` if `items` property has changed.
+	useHandleItemsPropertyChange(itemsProperty, {
 		virtualScroller,
 		// `preserveScrollPosition` property name is deprecated,
 		// use `preserveScrollPositionOnPrependItems` property instead.
 		preserveScrollPosition,
 		preserveScrollPositionOnPrependItems,
+		nextItems: getNextState().items
+	})
+
+	// Updates `key`s if item indexes have changed.
+	useHandleItemIndexesChange({
+		virtualScroller,
+		itemsBeingRendered: getNextState().items,
 		updateItemKeysForNewItems
 	})
 
@@ -177,15 +209,15 @@ function VirtualScroller({
 
 	const style = useStyle({
 		tbody,
-		virtualScroller
+		getNextState
 	})
 
 	const {
-		items: renderedItems,
+		items: currentItems,
 		itemStates,
 		firstShownItemIndex,
 		lastShownItemIndex
-	} = virtualScroller.getState()
+	} = getNextState()
 
 	return (
 		<AsComponent
@@ -193,7 +225,7 @@ function VirtualScroller({
 			ref={container}
 			className={className}
 			style={style}>
-			{renderedItems.map((item, i) => {
+			{currentItems.map((item, i) => {
 				if (i >= firstShownItemIndex && i <= lastShownItemIndex) {
 					// * Passing `item` as `children` property is legacy and is deprecated.
 					//   If version `2.x` is published in some hypothetical future,
@@ -219,7 +251,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/useHandleItemIndexesChange.js

@@ -0,0 +1,49 @@
+import { useRef } from 'react'
+
+// If the order of the `items` changes, or new `items` get prepended resulting in a "shift":
+//
+// * Re-generate the React `key` prefix for item elements
+//   so that all item components are re-rendered for the new `items` list.
+//   That's because item components may have their own internal state,
+//   and simply passing another `item` property for an item component
+//   might result in bugs, which React would do with its "re-using" policy
+//   if the unique `key` workaround hasn't been used.
+//
+export default function useHandleItemIndexesChange({
+	virtualScroller,
+	itemsBeingRendered,
+	updateItemKeysForNewItems
+}) {
+	const previousItemsBeingRenderedRef = useRef(itemsBeingRendered)
+	const previousItemsBeingRendered = previousItemsBeingRenderedRef.current
+	const haveItemsChanged = itemsBeingRendered !== previousItemsBeingRendered
+	previousItemsBeingRenderedRef.current = itemsBeingRendered
+
+	if (haveItemsChanged) {
+		let shouldUpdateItemKeys = true
+
+		const itemsDiff = virtualScroller.getItemsDiff(previousItemsBeingRendered, itemsBeingRendered)
+		// `itemsDiff` will be `undefined` in case of a non-incremental items list change.
+		if (itemsDiff) {
+			const {
+				prependedItemsCount,
+				appendedItemsCount
+			} = itemsDiff
+			if (prependedItemsCount === 0 && appendedItemsCount === 0) {
+				// The items order hasn't changed.
+				// No need to re-generate the `key` prefix.
+				shouldUpdateItemKeys = false
+			}
+			else if (prependedItemsCount === 0 && appendedItemsCount > 0) {
+				// The item order hasn't changed.
+				// No need to re-generate the `key` prefix.
+				shouldUpdateItemKeys = false
+			}
+		}
+
+		// Update React element `key`s for the new set of `items`.
+		if (shouldUpdateItemKeys) {
+			updateItemKeysForNewItems()
+		}
+	}
+}

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

@@ -1,6 +1,6 @@
 import { useRef } from 'react'
 
-// If new `items` are passed:
+// If new `items` property is passed:
 //
 // * Store the scroll Y position for the first one of the current items
 //   so that it could potentially (in some cases) be restored after the
@@ -8,26 +8,14 @@ import { useRef } from 'react'
 //
 // * Call `VirtualScroller.setItems()` function.
 //
-// * Re-generate the React `key` prefix for item elements
-//   so that all item components are re-rendered for the new `items` list.
-//   That's because item components may have their own internal state,
-//   and simply passing another `item` property for an item component
-//   might result in bugs, which React would do with its "re-using" policy
-//   if the unique `key` workaround hasn't been used.
-//
-export default function useHandleItemsChange(items, {
+export default function useHandleItemsPropertyChange(itemsProperty, {
 	virtualScroller,
 	// `preserveScrollPosition` property name is deprecated,
 	// use `preserveScrollPositionOnPrependItems` property instead.
 	preserveScrollPosition,
 	preserveScrollPositionOnPrependItems,
-	updateItemKeysForNewItems
+	nextItems
 }) {
-	const {
-		items: renderedItems,
-		firstShownItemIndex
-	} = virtualScroller.getState()
-
 	// During render, check if the `items` list has changed.
 	// If it has, capture the Y scroll position and updated item element `key`s.
 
@@ -72,13 +60,16 @@ export default function useHandleItemsChange(items, {
 	// scroll Y position is captured while the "Show previous" button
 	// is still being shown.
 
-	const previousItems = useRef(items)
-	const hasItemsPropertyChanged = items !== previousItems.current
-	previousItems.current = items
+	const previousItemsProperty = useRef(itemsProperty)
+	const hasItemsPropertyChanged = itemsProperty !== previousItemsProperty.current
+	previousItemsProperty.current = itemsProperty
+
 	if (hasItemsPropertyChanged) {
-		let itemsHaveChanged = true
-		let shouldUpdateItemKeys = true
-		const itemsDiff = virtualScroller.getItemsDiff(renderedItems, items)
+		let shouldUpdateItems = true
+
+		// Analyze the upcoming `items` change.
+		const itemsDiff = virtualScroller.getItemsDiff(nextItems, itemsProperty)
+
 		// `itemsDiff` will be `undefined` in case of a non-incremental items list change.
 		if (itemsDiff) {
 			const {
@@ -86,30 +77,21 @@ export default function useHandleItemsChange(items, {
 				appendedItemsCount
 			} = itemsDiff
 			if (prependedItemsCount === 0 && appendedItemsCount === 0) {
-				// The items haven't changed. No need to re-generate
-				// the `key` prefix or to snapshot the Y scroll position.
-				itemsHaveChanged = false
-				shouldUpdateItemKeys = false
-			}
-			else if (prependedItemsCount === 0 && appendedItemsCount > 0) {
-				// Just some items got appended. No need to re-generate
-				// the `key` prefix or to snapshot the Y scroll position.
-				shouldUpdateItemKeys = false
+				// The items order hasn't changed.
+				// No need to update them in `VirtualScroller` or to snapshot the Y scroll position.
+				shouldUpdateItems = false
 			}
 		}
 
-		if (itemsHaveChanged) {
-			// Set the new `items`.
-			virtualScroller.setItems(items, {
+		if (shouldUpdateItems) {
+			// 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, {
 				// `preserveScrollPosition` property name is deprecated,
 				// use `preserveScrollPositionOnPrependItems` property instead.
 				preserveScrollPositionOnPrependItems: preserveScrollPositionOnPrependItems || preserveScrollPosition
 			})
-
-			// Update React element `key`s for the new set of `items`.
-			if (shouldUpdateItemKeys) {
-				updateItemKeysForNewItems()
-			}
 		}
 	}
 }

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

@@ -1,22 +1,22 @@
 import { useMemo, useRef, useCallback } from 'react'
 
-export default function useOnItemHeightChange({
-	items,
+export default function useOnItemHeightDidChange({
+	initialItemsCount,
 	virtualScroller
 }) {
 	// Only compute the initial cache value once.
 	const initialCacheValue = useMemo(() => {
-		return new Array(items.length)
+		return new Array(initialItemsCount)
 	}, [])
 
 	// 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/useSetItemState.js

@@ -1,12 +1,12 @@
 import { useMemo, useRef, useCallback } from 'react'
 
 export default function useSetItemState({
-	items,
+	initialItemsCount,
 	virtualScroller
 }) {
 	// Only compute the initial cache value once.
 	const initialCacheValue = useMemo(() => {
-		return new Array(items.length)
+		return new Array(initialItemsCount)
 	}, [])
 
 	// Handler functions cache.