virtual-scroller 1.13.1 → 1.15.0

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({
-		bypass,
-		getInitialEstimatedItemHeight,
-		getInitialEstimatedVisibleItemRowsCount,
+		isInBypassMode,
+		getEstimatedVisibleItemRowsCountForInitialRender,
 		measureItemsBatchSize,
 		getPrerenderMargin,
+		getPrerenderMarginRatio,
 		getVerticalSpacing,
 		getVerticalSpacingBeforeResize,
 		getColumnsCount,
@@ -19,11 +20,11 @@ export default class Layout {
 		getMaxVisibleAreaHeight,
 		getPreviouslyCalculatedLayout
 	}) {
-		this.bypass = bypass
-		this.getInitialEstimatedItemHeight = getInitialEstimatedItemHeight
-		this.getInitialEstimatedVisibleItemRowsCount = getInitialEstimatedVisibleItemRowsCount
+		this.isInBypassMode = isInBypassMode
+		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
 		}
@@ -100,57 +117,50 @@ export default class Layout {
 		columnsCount,
 		firstShownItemIndex
 	}) {
-		if (this.bypass) {
+		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/Scroll.js

@@ -8,7 +8,7 @@ import log from './utility/debug.js'
 
 export default class Scroll {
 	constructor({
-		bypass,
+		isInBypassMode,
 		scrollableContainer,
 		itemsContainer,
 		onScroll,
@@ -23,7 +23,7 @@ export default class Scroll {
 		onScrolledToTop,
 		waitForScrollingToStop
 	}) {
-		this.bypass = bypass
+		this.isInBypassMode = isInBypassMode
 		this.scrollableContainer = scrollableContainer
 		this.itemsContainer = itemsContainer
 		this.onScroll = onScroll
@@ -98,7 +98,7 @@ export default class Scroll {
 			}
 		}
 
-		if (this.bypass) {
+		if (this.isInBypassMode()) {
 			return
 		}
 

package/source/ScrollableContainerResizeHandler.js

@@ -1,9 +1,9 @@
 import debounce from './utility/debounce.js'
-import log from './utility/debug.js'
+// import log from './utility/debug.js'
 
 export default class ScrollableContainerResizeHandler {
 	constructor({
-		bypass,
+		isInBypassMode,
 		getWidth,
 		getHeight,
 		listenForResize,
@@ -13,7 +13,7 @@ export default class ScrollableContainerResizeHandler {
 		onWidthChange,
 		onNoChange
 	}) {
-		this.bypass = bypass
+		this.isInBypassMode = isInBypassMode
 
 		this.onHeightChange = onHeightChange
 		this.onWidthChange = onWidthChange
@@ -35,7 +35,7 @@ export default class ScrollableContainerResizeHandler {
 
 	start() {
 		this.isActive = true
-		if (this.bypass) {
+		if (this.isInBypassMode()) {
 			return
 		}
 		this.width = this.getWidth()

package/source/VirtualScroller.constructor.js

@@ -1,18 +1,14 @@
-import {
-	supportsTbody,
-	BROWSER_NOT_SUPPORTED_ERROR
-} from './DOM/tbody.js'
-
 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'
 import ListHeightMeasurement from './ListHeightMeasurement.js'
 import ItemHeights from './ItemHeights.js'
 
-import log, { warn, isDebug, reportError } from './utility/debug.js'
+import log, { warn } from './utility/debug.js'
 
 import createStateHelpers from './VirtualScroller.state.js'
 import createVerticalSpacingHelpers from './VirtualScroller.verticalSpacing.js'
@@ -34,6 +30,7 @@ export default function VirtualScrollerConstructor(
 	options = {}
 ) {
 	const {
+		bypass,
 		render,
 		state,
 		getInitialItemState = () => {},
@@ -46,10 +43,10 @@ export default function VirtualScrollerConstructor(
 		measureItemsBatchSize = 50,
 		getColumnsCount,
 		getItemId,
-		tbody,
 		// `estimatedItemHeight` is deprecated, use `getEstimatedItemHeight()` instead.
 		estimatedItemHeight,
 		getEstimatedVisibleItemRowsCount,
+		getEstimatedInterItemVerticalSpacing,
 		onItemInitialRender,
 		// `onItemFirstRender(i)` is deprecated, use `onItemInitialRender(item)` instead.
 		onItemFirstRender,
@@ -59,7 +56,6 @@ export default function VirtualScrollerConstructor(
 	} = options
 
 	let {
-		bypass,
 		getEstimatedItemHeight,
 		getScrollableContainer
 	} = options
@@ -104,21 +100,6 @@ export default function VirtualScrollerConstructor(
 		throw new Error('[virtual-scroller] `getState`/`setState` options usage has changed in the new version. See the readme for more details.')
 	}
 
-	// Work around `<tbody/>` not being able to have `padding`.
-	// https://gitlab.com/catamphetamine/virtual-scroller/-/issues/1
-	if (tbody) {
-		if (this.engine !== DOMEngine) {
-			throw new Error('[virtual-scroller] `tbody` option is only supported for DOM rendering engine')
-		}
-		log('~ <tbody/> detected ~')
-		this.tbody = true
-		if (!supportsTbody()) {
-			log('~ <tbody/> not supported ~')
-			reportError(BROWSER_NOT_SUPPORTED_ERROR)
-			bypass = true
-		}
-	}
-
 	if (bypass) {
 		log('~ "bypass" mode ~')
 	}
@@ -133,7 +114,7 @@ export default function VirtualScrollerConstructor(
 	// It turned out that unmounting large React component trees
 	// is a very long process, so `VirtualScroller` does seem to
 	// make sense when used in a React application.
-	this.bypass = bypass
+	this._bypass = bypass
 	// this.bypassBatchSize = bypassBatchSize || 10
 
 	// Using `setTimeout()` in render loop is a workaround
@@ -188,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)
@@ -238,6 +219,13 @@ function createHelpers({
 		this.itemsContainer.clear()
 	}
 
+	this.isItemsContainerElementTableBody = () => {
+		return this.engine === DOMEngine &&
+			this.getItemsContainerElement().tagName === 'TBODY'
+	}
+
+	this.isInBypassMode = () => this._bypass
+
 	this.scrollableContainer = this.engine.createScrollableContainer(
 		getScrollableContainer,
 		this.getItemsContainerElement
@@ -250,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({
-		bypass: this.bypass,
-		getInitialEstimatedItemHeight: getEstimatedItemHeight,
-		getInitialEstimatedVisibleItemRowsCount: getEstimatedVisibleItemRowsCount,
+		isInBypassMode: this.isInBypassMode,
+		getEstimatedVisibleItemRowsCountForInitialRender: getEstimatedVisibleItemRowsCount,
 		measureItemsBatchSize,
 		getPrerenderMargin: () => this.getPrerenderMargin(),
+		getPrerenderMarginRatio: () => this.getPrerenderMarginRatio(),
 		getVerticalSpacing: () => this.getVerticalSpacing(),
 		getVerticalSpacingBeforeResize: () => this.getVerticalSpacingBeforeResize(),
 		getColumnsCount: () => this.getColumnsCount(),
@@ -263,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(),
@@ -278,7 +287,7 @@ function createHelpers({
 	})
 
 	this.scrollableContainerResizeHandler = new ScrollableContainerResizeHandler({
-		bypass: this.bypass,
+		isInBypassMode: this.isInBypassMode,
 		getWidth: () => this.scrollableContainer.getWidth(),
 		getHeight: () => this.scrollableContainer.getHeight(),
 		listenForResize: (listener) => this.scrollableContainer.onResize(listener),
@@ -308,7 +317,7 @@ function createHelpers({
 	})
 
 	this.scroll = new Scroll({
-		bypass: this.bypass,
+		isInBypassMode: this.isInBypassMode,
 		scrollableContainer: this.scrollableContainer,
 		itemsContainer: this.itemsContainer,
 		waitForScrollingToStop,

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

@@ -1,11 +1,17 @@
 import VirtualScrollerConstructor from './VirtualScroller.constructor.js'
-import { hasTbodyStyles, addTbodyStyles } from './DOM/tbody.js'
 import { LAYOUT_REASON } from './Layout.js'
-import log, { warn } from './utility/debug.js'
+import log, { warn, reportError } from './utility/debug.js'
+
+import {
+	supportsTbody,
+	hasTbodyStyles,
+	addTbodyStyles,
+	BROWSER_NOT_SUPPORTED_ERROR
+} from './DOM/tbody.js'
 
 export default class VirtualScroller {
 	/**
-	 * @param  {function} getItemsContainerElement — Returns the container DOM `Element`.
+	 * @param  {function} getItemsContainerElement — Returns the items container DOM `Element`.
 	 * @param  {any[]} items — The list of items.
 	 * @param  {Object} [options] — See README.md.
 	 * @return {VirtualScroller}
@@ -35,13 +41,8 @@ export default class VirtualScroller {
 		const isRestart = this._isActive === false
 
 		if (!isRestart) {
+			this.setUpState()
 			this.waitingForRender = true
-
-			// If no custom state storage has been configured, use the default one.
-			// Also sets the initial state.
-			if (!this._usesCustomStateStorage) {
-				this.useDefaultStateStorage()
-			}
 			// If `render()` function parameter was passed,
 			// perform an initial render.
 			if (this._render) {
@@ -67,11 +68,23 @@ export default class VirtualScroller {
 		// Reset `_isSettingNewItems` flag just in case it has some "leftover" value.
 		this._isSettingNewItems = undefined
 
-		// Work around `<tbody/>` not being able to have `padding`.
+		// When `<tbody/>` is used as an items container element,
+		// `virtual-scroller` has to work around the HTML bug of
+		// `padding` not working on a `<tbody/>` element.
 		// https://gitlab.com/catamphetamine/virtual-scroller/-/issues/1
-		if (this.tbody) {
-			if (!hasTbodyStyles(this.getItemsContainerElement())) {
-				addTbodyStyles(this.getItemsContainerElement())
+		if (!this.isInBypassMode()) {
+			if (this.isItemsContainerElementTableBody()) {
+				if (supportsTbody()) {
+					if (!hasTbodyStyles(this.getItemsContainerElement())) {
+						log('~ <tbody/> container ~')
+						addTbodyStyles(this.getItemsContainerElement())
+					}
+				} else {
+					log('~ <tbody/> container not supported ~')
+					reportError(BROWSER_NOT_SUPPORTED_ERROR)
+					log('~ enter "bypass" mode ~')
+					this._bypass = true
+				}
 			}
 		}
 
@@ -193,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
@@ -208,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`.
@@ -272,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)
 	}
 
 	/**