virtual-scroller 1.14.0 → 1.15.1

package/source/ItemHeights.js

@@ -1,15 +1,15 @@
-import log, { warn, isDebug, reportError } from './utility/debug.js'
+import log, { warn } from './utility/debug.js'
 
 export default class ItemHeights {
 	constructor({
 		container,
-		itemHeights,
 		getItemHeight,
 		setItemHeight
 	}) {
 		this.container = container
 		this._get = getItemHeight
 		this._set = setItemHeight
+
 		this.reset()
 	}
 
@@ -20,9 +20,9 @@ export default class ItemHeights {
 		// is called, some items might get prepended, in which case
 		// `this.lastMeasuredItemIndex` is updated. If there was no
 		// `this.firstMeasuredItemIndex`, then the average item height
-		// calculated in `.getAverage()` would be incorrect in the timeframe
+		// calculated in `.getAverageItemHeight()` would be incorrect in the timeframe
 		// between `.setItems()` is called and those changes have been rendered.
-		// And in that timeframe, `.getAverage()` is used to calculate the "layout":
+		// And in that timeframe, `.getAverageItemHeight()` is used to calculate the "layout":
 		// stuff like "before/after items height" and "estimated items count on screen".
 		this.firstMeasuredItemIndex = undefined
 		this.lastMeasuredItemIndex = undefined
@@ -64,7 +64,7 @@ export default class ItemHeights {
 	// 		this._set(i, itemHeight)
 	// 		return itemHeight
 	// 	}
-	// 	return this.getAverage()
+	// 	return this.getAverageItemHeight()
 	// }
 
 	_measureItemHeight(i, firstShownItemIndex) {
@@ -169,7 +169,7 @@ export default class ItemHeights {
 				const previousHeight = this._get(i)
 				const height = this._measureItemHeight(i, firstShownItemIndex)
 				if (previousHeight !== height) {
-					warn('Item index', i, 'height changed unexpectedly: it was', previousHeight, 'before, but now it is', height, '. Whenever an item\'s height changes for whatever reason, a developer must call `onItemHeightDidChange(i)` right after that change. If you are calling `onItemHeightDidChange(i)` correctly, then there\'re several other possible causes. For example, perhaps you forgot to persist the item\'s "state" by calling `setItemState(i, newState)` when that "state" did change, and so the item\'s "state" got lost when the item element was unmounted, which resulted in a different item height when the item was shown again with no previous "state". Or perhaps you\'re running your application in "devleopment" mode and `VirtualScroller` has initially rendered the list before your CSS styles or custom fonts have loaded, resulting in different item height measurements "before" and "after" the page has fully loaded.')
+					warn('Item index', i, 'height changed unexpectedly: it was', previousHeight, 'before, but now it is', height, '. Whenever an item\'s height changes for whatever reason, a developer must call `onItemHeightDidChange(item)` right after that change. If you are calling `onItemHeightDidChange(item)` correctly, then there\'re several other possible causes. For example, perhaps you forgot to persist the item\'s "state" by calling `setItemState(item, newState)` when that "state" did change, and so the item\'s "state" got lost when the item element was unmounted, which resulted in a different item height when the item was shown again with no previous "state". Or perhaps you\'re running your application in "devleopment" mode and `VirtualScroller` has initially rendered the list before your CSS styles or custom fonts have loaded, resulting in different item height measurements "before" and "after" the page has fully loaded.')
 					// Update the item's height as an attempt to fix things.
 					this._set(i, height)
 				}
@@ -231,7 +231,7 @@ export default class ItemHeights {
 	//  * Public API: is called by `VirtualScroller`.
 	//  * @return {number}
 	//  */
-	// getAverage() {
+	// getAvergetAverageItemHeightage() {
 	// 	// Previously measured average item height might still be
 	// 	// more precise if it contains more measured items ("samples").
 	// 	if (this.previousAverageItemHeight) {
@@ -244,13 +244,12 @@ export default class ItemHeights {
 
 	/**
 	 * Public API: is called by `VirtualScroller`.
-	 * @return {number}
+	 * @return {number} [averageItemHeight] Returns `undefined` until at least one item has been rendered.
 	 */
-	getAverage() {
-		if (this.lastMeasuredItemIndex === undefined) {
-			return 0
+	getAverageItemHeight() {
+		if (this.lastMeasuredItemIndex !== undefined) {
+			return this.measuredItemsHeight / (this.lastMeasuredItemIndex - this.firstMeasuredItemIndex + 1)
 		}
-		return this.measuredItemsHeight / (this.lastMeasuredItemIndex - this.firstMeasuredItemIndex + 1)
 	}
 
 	onPrepend(count) {

package/source/Layout.defaults.js

@@ -0,0 +1,8 @@
+// These values are used by default in server-side render,
+// unless the developer explicitly specifies:
+// * `getEstimatedItemHeight()`
+// * `getEstimatedVisibleItemRowsCount()`
+// * `getEstimatedInterItemVerticalSpacing()`
+export const DEFAULT_VISIBLE_ITEM_ROWS_COUNT = 1 // determines the count of items to render.
+export const DEFAULT_ITEM_HEIGHT = 0 // determines the length of the scrollbar, i.e. how much the user can scroll.
+export const DEFAULT_INTER_ITEM_VERTICAL_SPACING = 0 // determines the length of the scrollbar, i.e. how much the user can scroll.

package/source/Layout.js

@@ -1,13 +1,14 @@
 import log, { warn } from './utility/debug.js'
 import ScrollableContainerNotReadyError from './ScrollableContainerNotReadyError.js'
+import { DEFAULT_VISIBLE_ITEM_ROWS_COUNT } from './Layout.defaults.js'
 
 export default class Layout {
 	constructor({
 		isInBypassMode,
-		getInitialEstimatedItemHeight,
-		getInitialEstimatedVisibleItemRowsCount,
+		getEstimatedVisibleItemRowsCountForInitialRender,
 		measureItemsBatchSize,
 		getPrerenderMargin,
+		getPrerenderMarginRatio,
 		getVerticalSpacing,
 		getVerticalSpacingBeforeResize,
 		getColumnsCount,
@@ -20,10 +21,10 @@ export default class Layout {
 		getPreviouslyCalculatedLayout
 	}) {
 		this.isInBypassMode = isInBypassMode
-		this.getInitialEstimatedItemHeight = getInitialEstimatedItemHeight
-		this.getInitialEstimatedVisibleItemRowsCount = getInitialEstimatedVisibleItemRowsCount
+		this.getEstimatedVisibleItemRowsCountForInitialRender = getEstimatedVisibleItemRowsCountForInitialRender
 		this.measureItemsBatchSize = measureItemsBatchSize
 		this.getPrerenderMargin = getPrerenderMargin
+		this.getPrerenderMarginRatio = getPrerenderMarginRatio
 		this.getVerticalSpacing = getVerticalSpacing
 		this.getVerticalSpacingBeforeResize = getVerticalSpacingBeforeResize
 		this.getColumnsCount = getColumnsCount
@@ -69,6 +70,10 @@ export default class Layout {
 	}) {
 		let firstShownItemIndex
 		let lastShownItemIndex
+
+		let beforeItemsHeight = 0
+		let afterItemsHeight = 0
+
 		// If there're no items then `firstShownItemIndex` stays `undefined`.
 		if (itemsCount > 0) {
 			const getLastShownItemIndex = () => {
@@ -78,18 +83,30 @@ export default class Layout {
 					firstShownItemIndex
 				})
 			}
+
 			firstShownItemIndex = 0
+
 			lastShownItemIndex = beforeStart
 				? this.getInitialLayoutValueWithFallback(
 					'lastShownItemIndex',
 					getLastShownItemIndex,
-					0
+					firstShownItemIndex
 				)
 				: getLastShownItemIndex()
+
+			const averageItemHeight = this.getAverageItemHeight()
+			const verticalSpacing = this.getVerticalSpacing()
+
+			const beforeItemsCount = firstShownItemIndex
+			const afterItemsCount = itemsCount - (lastShownItemIndex + 1)
+
+			beforeItemsHeight = Math.ceil(beforeItemsCount / columnsCount) * (verticalSpacing + averageItemHeight)
+			afterItemsHeight = Math.ceil(afterItemsCount / columnsCount) * (verticalSpacing + averageItemHeight)
 		}
+
 		return {
-			beforeItemsHeight: 0,
-			afterItemsHeight: 0,
+			beforeItemsHeight,
+			afterItemsHeight,
 			firstShownItemIndex,
 			lastShownItemIndex
 		}
@@ -103,54 +120,47 @@ export default class Layout {
 		if (this.isInBypassMode()) {
 			return itemsCount - 1
 		}
-		// On server side, at initialization time,
-		// `scrollableContainer` is `undefined`,
-		// so default to `1` estimated rows count.
-		let estimatedRowsCount = 1
-		if (this.getMaxVisibleAreaHeight()) {
-			estimatedRowsCount = this.getEstimatedRowsCountForHeight(this.getMaxVisibleAreaHeight() + this.getPrerenderMargin())
-		} else if (this.getInitialEstimatedVisibleItemRowsCount) {
-			estimatedRowsCount = this.getInitialEstimatedVisibleItemRowsCount()
-			if (isNaN(estimatedRowsCount)) {
-				throw new Error('[virtual-scroller] `getEstimatedVisibleItemRowsCount()` must return a number')
-			}
-		}
 		return Math.min(
-			firstShownItemIndex + (estimatedRowsCount * columnsCount - 1),
+			firstShownItemIndex + (this.getInitialRenderedRowsCount() * columnsCount - 1),
 			itemsCount - 1
 		)
 	}
 
-	getEstimatedRowsCountForHeight(height) {
-		const estimatedItemHeight = this.getEstimatedItemHeight()
-		const verticalSpacing = this.getVerticalSpacing()
-		if (estimatedItemHeight) {
-			return Math.ceil((height + verticalSpacing) / (estimatedItemHeight + verticalSpacing))
-		} else {
-			// If no items have been rendered yet, and no `estimatedItemHeight` option
-			// has been passed, then default to `1` estimated rows count in any `height`.
-			return 1
+	getInitialRenderedRowsCount() {
+		const estimatedVisibleItemRowsCount = this.getEstimatedVisibleItemRowsCount()
+		if (typeof estimatedVisibleItemRowsCount === 'number') {
+			return Math.ceil(estimatedVisibleItemRowsCount * (1 + this.getPrerenderMarginRatio()))
 		}
+		// `DEFAULT_VISIBLE_ITEM_ROWS_COUNT` will be used in server-side render
+		// unless `getEstimatedVisibleItemRowsCount()` parameter is specified.
+		return DEFAULT_VISIBLE_ITEM_ROWS_COUNT
 	}
 
-	/**
-	 * Returns estimated list item height.
-	 * (depends on which items have been previously rendered and measured).
-	 * @return {number}
-	 */
-	getEstimatedItemHeight() {
-		const averageItemHeight = this.getAverageItemHeight()
-		if (averageItemHeight) {
-			return averageItemHeight
+	getEstimatedVisibleItemRowsCount() {
+		const maxVisibleAreaHeight = this.getMaxVisibleAreaHeight()
+		if (typeof maxVisibleAreaHeight === 'number') {
+			const estimatedRowsCount = this.getEstimatedRowsCountForHeight(maxVisibleAreaHeight)
+			if (typeof estimatedRowsCount === 'number') {
+				return estimatedRowsCount
+			}
 		}
-		if (this.getInitialEstimatedItemHeight) {
-			const estimatedItemHeight = this.getInitialEstimatedItemHeight()
-			if (isNaN(estimatedItemHeight)) {
-				throw new Error('[virtual-scroller] `getInitialEstimatedItemHeight()` must return a number')
+		if (this.getEstimatedVisibleItemRowsCountForInitialRender) {
+			const estimatedRowsCount = this.getEstimatedVisibleItemRowsCountForInitialRender()
+			if (typeof estimatedRowsCount === 'number') {
+				return estimatedRowsCount
 			}
-			return estimatedItemHeight
+			throw new Error('[virtual-scroller] `getEstimatedVisibleItemRowsCount()` must return a number')
+		}
+	}
+
+	getEstimatedRowsCountForHeight(height) {
+		const averageItemHeight = this.getAverageItemHeight()
+		const verticalSpacing = this.getVerticalSpacing()
+		// `estimatedItemHeight` will most likely be `0` if it hasn't been specified explicitly.
+		// In that case, it can't divide by `0`.
+		if (averageItemHeight + verticalSpacing > 0) {
+			return Math.ceil((height + verticalSpacing) / (averageItemHeight + verticalSpacing))
 		}
-		return 0
 	}
 
 	getLayoutUpdateForItemsDiff({
@@ -328,8 +338,17 @@ export default class Layout {
 
 		const columnsCount = this.getColumnsCount()
 
+		const getNonMeasuredItemRowsCount = () => {
+			const estimatedRowsCount = this.getEstimatedRowsCountForHeight(nonMeasuredAreaHeight)
+			if (typeof estimatedRowsCount === 'number') {
+				return estimatedRowsCount
+			}
+			// Render all available item rows as a sensible fallback behavior.
+			return Math.ceil(itemsCount / columnsCount)
+		}
+
 		const itemsCountToRenderForMeasurement = Math.min(
-			this.getEstimatedRowsCountForHeight(nonMeasuredAreaHeight) * columnsCount,
+			getNonMeasuredItemRowsCount() * columnsCount,
 			this.measureItemsBatchSize || Infinity,
 		)
 
@@ -434,15 +453,12 @@ export default class Layout {
 		// then `shownItemsHeight` would also have to be returned from this function:
 		// the total height of all shown items including vertical spacing between them.
 		//
-		// If "previously calculated layout" would be used then it would first find
-		// `firstShownItemIndex` and then find `lastShownItemIndex` as part of two
+		// If "previously calculated layout" would be used then it would first calculate
+		// `firstShownItemIndex` and then calculate `lastShownItemIndex` as part of two
 		// separate calls of this function, each with or without `backwards` flag,
 		// depending on whether `visibleAreaInsideTheList.top` and `visibleAreaInsideTheList.top`
 		// have shifted up or down.
 
-		let firstShownItemIndex
-		let lastShownItemIndex
-
 		// It's not always required to pass `beforeItemsHeight` parameter:
 		// when `fromIndex` is `0`, it's also assumed to be `0`.
 		if (fromIndex === 0) {
@@ -678,8 +694,6 @@ export default class Layout {
 		const verticalSpacing = beforeResize ? this.getVerticalSpacingBeforeResize() : this.getVerticalSpacing()
 
 		while (i < beforeItemsCount) {
-			const currentRowFirstItemIndex = i
-
 			let rowHeight = 0
 			let columnIndex = 0
 			// Not checking for `itemsCount` overflow here because `i = beforeItemsCount`
@@ -734,7 +748,6 @@ export default class Layout {
 		// Which becomes negligible in my project's use case (a couple thousands items max).
 
 		const columnsCount = this.getColumnsCount()
-		const lastShownRowIndex = Math.floor(lastShownItemIndex / columnsCount)
 
 		let afterItemsHeight = 0
 

package/source/Layout.test.js

@@ -158,9 +158,11 @@ describe('Layout', function() {
 
 		let shouldResetGridLayout
 
+		// Don't `throw` `VirtualScroller` errors but rather collect them in an array.
 		const errors = []
-
-		global.VirtualScrollerCatchError = (error) => errors.push(error)
+		global.VirtualScrollerCatchError = (error) => {
+			errors.push(error)
+		}
 
 		layout.getLayoutUpdateForItemsDiff(
 			{
@@ -185,7 +187,10 @@ describe('Layout', function() {
 			afterItemsHeight: 5 * (ITEM_HEIGHT + VERTICAL_SPACING)
 		})
 
+		// Stop collecting `VirtualScroller` errors in the `errors` array.
+		// Use the default behavior of just `throw`-ing such errors.
 		global.VirtualScrollerCatchError = undefined
+		// Verify the errors that have been `throw`-n.
 		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')

package/source/VirtualScroller.constructor.js

@@ -1,6 +1,7 @@
 import DOMEngine from './DOM/Engine.js'
 
 import Layout, { LAYOUT_REASON } from './Layout.js'
+import { DEFAULT_ITEM_HEIGHT } from './Layout.defaults.js'
 import ScrollableContainerResizeHandler from './ScrollableContainerResizeHandler.js'
 import BeforeResize from './BeforeResize.js'
 import Scroll from './Scroll.js'
@@ -45,6 +46,7 @@ export default function VirtualScrollerConstructor(
 		// `estimatedItemHeight` is deprecated, use `getEstimatedItemHeight()` instead.
 		estimatedItemHeight,
 		getEstimatedVisibleItemRowsCount,
+		getEstimatedInterItemVerticalSpacing,
 		onItemInitialRender,
 		// `onItemFirstRender(i)` is deprecated, use `onItemInitialRender(item)` instead.
 		onItemFirstRender,
@@ -167,7 +169,7 @@ export default function VirtualScrollerConstructor(
 
 	createStateHelpers.call(this, { state, getInitialItemState, onStateChange, render, items })
 
-	createVerticalSpacingHelpers.call(this)
+	createVerticalSpacingHelpers.call(this, { getEstimatedInterItemVerticalSpacing })
 	createColumnsHelpers.call(this, { getColumnsCount })
 
 	createLayoutHelpers.call(this)
@@ -236,12 +238,33 @@ function createHelpers({
 		setItemHeight: (i, height) => this.getState().itemHeights[i] = height
 	})
 
+	this.getAverageItemHeight = () => {
+		const averageItemHeight = this.itemHeights.getAverageItemHeight()
+		if (typeof averageItemHeight === 'number') {
+			return averageItemHeight
+		}
+		return this.getEstimatedItemHeight()
+	}
+
+	this.getEstimatedItemHeight = () => {
+		if (getEstimatedItemHeight) {
+			const estimatedItemHeight = getEstimatedItemHeight()
+			if (typeof estimatedItemHeight === 'number') {
+				return estimatedItemHeight
+			}
+			throw new Error('[virtual-scroller] `getEstimatedItemHeight()` must return a number')
+		}
+		// `DEFAULT_ITEM_HEIGHT` will be used in server-side render
+		// unless `getEstimatedItemHeight()` parameter is specified.
+		return DEFAULT_ITEM_HEIGHT
+	}
+
 	this.layout = new Layout({
 		isInBypassMode: this.isInBypassMode,
-		getInitialEstimatedItemHeight: getEstimatedItemHeight,
-		getInitialEstimatedVisibleItemRowsCount: getEstimatedVisibleItemRowsCount,
+		getEstimatedVisibleItemRowsCountForInitialRender: getEstimatedVisibleItemRowsCount,
 		measureItemsBatchSize,
 		getPrerenderMargin: () => this.getPrerenderMargin(),
+		getPrerenderMarginRatio: () => this.getPrerenderMarginRatio(),
 		getVerticalSpacing: () => this.getVerticalSpacing(),
 		getVerticalSpacingBeforeResize: () => this.getVerticalSpacingBeforeResize(),
 		getColumnsCount: () => this.getColumnsCount(),
@@ -249,7 +272,7 @@ function createHelpers({
 		getItemHeight: (i) => this.getState().itemHeights[i],
 		getItemHeightBeforeResize: (i) => this.getState().beforeResize && this.getState().beforeResize.itemHeights[i],
 		getBeforeResizeItemsCount: () => this.getState().beforeResize ? this.getState().beforeResize.itemHeights.length : 0,
-		getAverageItemHeight: () => this.itemHeights.getAverage(),
+		getAverageItemHeight: () => this.getAverageItemHeight(),
 		// `this.scrollableContainer` is gonna be `undefined` during server-side rendering.
 		// https://gitlab.com/catamphetamine/virtual-scroller/-/issues/30
 		getMaxVisibleAreaHeight: () => this.scrollableContainer && this.scrollableContainer.getHeight(),

package/source/VirtualScroller.items.js

@@ -1,4 +1,4 @@
-import log, { isDebug } from './utility/debug.js'
+import log, { reportError } from './utility/debug.js'
 import getItemsDiff from './getItemsDiff.js'
 import fillArray from './utility/fillArray.js'
 
@@ -7,6 +7,49 @@ export default function() {
 		return this.getState().items.length
 	}
 
+	this._getItemIndexByItemOrIndex = (itemOrIndex) => {
+		const item = itemOrIndex
+		const { items } = this.getState()
+		// Find the `item`'s index in the `items` array.
+		//
+		// Performance notes:
+		// Doing an `.indexOf()` operation on a very large array could be inefficient
+		// because it would have to check every element of the array.
+		// In case of any hypothetical performance-related issues,
+		// the code could use a `new Map()` as an "index" for finding individual items.
+		const i = items.indexOf(item)
+		// validate that the `item` exists in the `items` array.
+		if (i >= 0) {
+			return i
+		}
+
+		// Legacy behavior: some functions used to accept an `i: number` item index as an argument.
+		// Later the argument was changed to `item: Item`.
+		//
+		// The old way of passing an `i: number` argument would only result in weird application behavior
+		// when all of the below circumstances are true, which is assumed extremely unlikely:
+		//
+		// BOTH use a previous version of `virtual-scroller` (ones before December 2025, with downloads count that is not very high)
+		// AND to be used with an `items` array of type `number[]`
+		// AND to use any of the "advanced" functions:
+    // * `setItemState(i, newState)`
+    // * `onItemHeightDidChange(i)`
+    // * `getItemScrollPosition(i)`
+		//
+		// The code below handles the legacy compatibility aspect of the old type of argument
+		// except maybe for those "extremely unlikely" cases in which the app is still unlikely to crash.
+		//
+		if (typeof itemOrIndex === 'number') {
+			const i = itemOrIndex
+			// Validate the item index argument.
+			if (i >= 0 && i < items.length) {
+				return i
+			}
+		}
+
+		reportError(`Item not found: ${JSON.stringify(item)}`)
+	}
+
 	/**
 	 * Updates `items`. For example, can prepend or append new items to the list.
 	 * @param  {any[]} newItems
@@ -81,7 +124,9 @@ export default function() {
 			if (prependedItemsCount > 0) {
 				log('Prepend', prependedItemsCount, 'items')
 
-				itemHeights = new Array(prependedItemsCount).concat(itemHeights)
+				itemHeights = new Array(prependedItemsCount)
+					.concat(itemHeights)
+
 				itemStates = fillArray(
 					new Array(prependedItemsCount),
 					(i) => this.getInitialItemState(newItems[i])

package/source/VirtualScroller.js

@@ -206,10 +206,19 @@ export default class VirtualScroller {
 
 	/**
 	 * Returns the items's top offset relative to the scrollable container's top edge.
-	 * @param {number} i — Item index
+	 * @param {any} item — Item
 	 * @return {[number]} Returns the item's scroll Y position. Returns `undefined` if any of the previous items haven't been rendered yet.
 	 */
-	getItemScrollPosition(i) {
+	getItemScrollPosition(itemOrIndex) {
+		// Item index.
+		const i = this._getItemIndexByItemOrIndex(itemOrIndex)
+
+		// If the item wasn't found, the error was already reported,
+		// so just return some "sensible" default value.
+		if (i === undefined) {
+			return
+		}
+
 		const itemTopOffsetInList = this.layout.getItemTopOffset(i)
 		if (itemTopOffsetInList === undefined) {
 			return
@@ -221,28 +230,28 @@ export default class VirtualScroller {
 	 * @deprecated
 	 * `.onItemHeightChange()` has been renamed to `.onItemHeightDidChange()`.
 	 */
-	onItemHeightChange(i) {
-		warn('`.onItemHeightChange(i)` method was renamed to `.onItemHeightDidChange(i)`')
-		this.onItemHeightDidChange(i)
+	onItemHeightChange(item) {
+		warn('`.onItemHeightChange(item)` method was renamed to `.onItemHeightDidChange(item)`')
+		this.onItemHeightDidChange(item)
 	}
 
 	/**
 	 * Forces a re-measure of an item's height.
-	 * @param  {number} i — Item index
+	 * @param {any} item — Item. Legacy argument variant: Item index.
 	 */
-	onItemHeightDidChange(i) {
+	onItemHeightDidChange(itemOrIndex) {
 		// See the comments in the `setItemState()` function below for the rationale
 		// on why the `hasToBeStarted()` check was commented out.
 		// this.hasToBeStarted()
-		this._onItemHeightDidChange(i)
+		this._onItemHeightDidChange(itemOrIndex)
 	}
 
 	/**
 	 * Updates an item's state in `state.itemStates[]`.
-	 * @param  {number} i — Item index
-	 * @param  {any} i — Item's new state
+	 * @param  {any} item — Item. Legacy argument variant: Item index.
+	 * @param  {any} newItemState — Item's new state
 	 */
-	setItemState(i, newItemState) {
+	setItemState(itemOrIndex, newItemState) {
 		// There is an issue in React 18.2.0 when `useInsertionEffect()` doesn't run twice
 		// on mount unlike `useLayoutEffect()` in "strict" mode. That causes a bug in a React
 		// implementation of the `virtual-scroller`.
@@ -285,13 +294,13 @@ export default class VirtualScroller {
 		// Commenting it out wouldn't result in any potential bugs because the code would work correctly
 		// in both cases.
 		// this.hasToBeStarted()
-		this._setItemState(i, newItemState)
+		this._setItemState(itemOrIndex, newItemState)
 	}
 
 	// (deprecated)
 	// Use `.setItemState()` method name instead.
-	onItemStateChange(i, newItemState) {
-		this.setItemState(i, newItemState)
+	onItemStateChange(item, newItemState) {
+		this.setItemState(item, newItemState)
 	}
 
 	/**