virtual-scroller 1.14.0 → 1.15.0

package/source/VirtualScroller.state.js

@@ -37,7 +37,16 @@ export default function createStateHelpers({
 
 	this.getInitialItemState = getInitialItemState
 
-	this._setItemState = (i, newItemState) => {
+	this._setItemState = (itemOrIndex, newItemState) => {
+		// 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
+		}
+
 		if (isDebug()) {
 			log('~ Item state changed ~')
 			log('Item index', i)
@@ -284,16 +293,6 @@ export default function createStateHelpers({
 	function getInitialLayoutState(items, { beforeStart }) {
 		const itemsCount = items.length
 
-		const getColumnsCount = () => this.getActualColumnsCount()
-
-		const columnsCount = beforeStart
-			? this.layout.getInitialLayoutValueWithFallback(
-				'columnsCount',
-				getColumnsCount,
-				1
-			)
-			: getColumnsCount()
-
 		const {
 			firstShownItemIndex,
 			lastShownItemIndex,

package/source/VirtualScroller.verticalSpacing.js

@@ -1,20 +1,46 @@
 import log from './utility/debug.js'
 import getVerticalSpacing from './getVerticalSpacing.js'
+import { DEFAULT_INTER_ITEM_VERTICAL_SPACING } from './Layout.defaults.js'
 
-export default function createVerticalSpacingHelpers() {
+export default function createVerticalSpacingHelpers({
+	getEstimatedInterItemVerticalSpacing
+}) {
 	// Bind to `this` in order to prevent bugs when this function is passed by reference
 	// and then called with its `this` being unintentionally `window` resulting in
 	// the `if` condition being "falsy".
 	this.getVerticalSpacing = () => {
-		return this.verticalSpacing || 0
+		const { verticalSpacing } = this
+		if (typeof verticalSpacing === 'number') {
+			return verticalSpacing
+		}
+		return this.getEstimatedInterItemVerticalSpacing()
 	}
 
 	this.getVerticalSpacingBeforeResize = () => {
-		// `beforeResize.verticalSpacing` can be `undefined`.
-		// For example, if `this.updateState({ verticalSpacing })` call hasn't been applied
-		// before the resize happened (in case of an "asynchronous" state update).
 		const { beforeResize } = this.getState()
-		return beforeResize && beforeResize.verticalSpacing || 0
+		if (beforeResize) {
+			const { verticalSpacing } = beforeResize
+			// `beforeResize.verticalSpacing` can be `undefined`.
+			// For example, if `this.updateState({ verticalSpacing })` call hasn't been applied
+			// before the resize happened (in case of an "asynchronous" state update).
+			if (typeof verticalSpacing === 'number') {
+				return verticalSpacing
+			}
+			return this.getEstimatedInterItemVerticalSpacing()
+		}
+	}
+
+	this.getEstimatedInterItemVerticalSpacing = () => {
+		if (getEstimatedInterItemVerticalSpacing) {
+			const estimatedVerticalSpacing = getEstimatedInterItemVerticalSpacing()
+			if (typeof estimatedVerticalSpacing === 'number') {
+				return estimatedVerticalSpacing
+			}
+			throw new Error('[virtual-scroller] `getEstimatedInterItemVerticalSpacing()` must return a number')
+		}
+		// `DEFAULT_INTER_ITEM_VERTICAL_SPACING` will be used in server-side render
+		// unless `getEstimatedInterItemVerticalSpacing()` parameter is specified.
+		return DEFAULT_INTER_ITEM_VERTICAL_SPACING
 	}
 
 	/**

package/source/react/VirtualScroller.js

@@ -1,4 +1,4 @@
-import React, { useRef, useMemo, useLayoutEffect } from 'react'
+import React, { useMemo, useLayoutEffect } from 'react'
 import PropTypes from 'prop-types'
 
 import useState from './useState.js'
@@ -10,6 +10,8 @@ import useSetItemState from './useSetItemState.js'
 import useOnItemHeightDidChange from './useOnItemHeightDidChange.js'
 import useSetNewItemsOnItemsPropertyChange from './useSetNewItemsOnItemsPropertyChange.js'
 import useUpdateItemKeysOnItemsChange from './useUpdateItemKeysOnItemsChange.js'
+import useValidateTableBodyItemsContainer from './useValidateTableBodyItemsContainer.js'
+import useForwardedRef from './useForwardedRef.js'
 import useClassName from './useClassName.js'
 import useStyle from './useStyle.js'
 
@@ -27,19 +29,32 @@ import { warn } from '../utility/debug.js'
 // * The React component re-renders itself the second time.
 
 function VirtualScroller({
-	as: AsComponent = 'div',
+	// The following are `<VirtualScroller/>` properties.
+	//
+	// `as` property is deprecated, use `itemsContainerComponent` property instead.
+	as,
 	items: itemsProperty,
-	itemComponent: Component,
+	itemComponent: ItemComponent,
 	itemComponentProps,
+	itemsContainerComponent: ItemsContainerComponent,
+	itemsContainerComponentProps,
+	itemsContainerRef,
 	// `estimatedItemHeight` property name is deprecated,
 	// use `getEstimatedItemHeight` property instead.
 	estimatedItemHeight,
 	getEstimatedItemHeight,
 	getEstimatedVisibleItemRowsCount,
-	bypass,
+	getEstimatedInterItemVerticalSpacing,
+	onMount,
 	// `tbody` property is deprecated.
 	// Pass `as: "tbody"` property instead.
 	tbody,
+	readyToStart,
+	className: classNameProperty,
+
+	// The following are the "core" component options.
+	//
+	bypass,
 	// `preserveScrollPosition` property name is deprecated,
 	// use `preserveScrollPositionOnPrependItems` property instead.
 	preserveScrollPosition,
@@ -51,19 +66,26 @@ function VirtualScroller({
 	getScrollableContainer,
 	getColumnsCount,
 	getItemId,
-	className,
-	readyToStart,
-	onMount,
 	// `onItemFirstRender(i)` is deprecated, use `onItemInitialRender(item)` instead.
 	onItemFirstRender,
 	onItemInitialRender,
 	initialScrollPosition,
 	onScrollPositionChange,
-	onStateChange,
 	initialState,
 	getInitialItemState,
+	onStateChange,
+
+	// "Rest" properties that will be passed through to the `itemsContainerComponent`.
 	...rest
 }, ref) {
+	// Previously, `as` property was being used instead of `itemsContainerComponent`,
+	// and the default `as` property value was a generic `<div/>`.
+	// Starting from version `1.14.1`, it is recommended to explicitly specify the `itemsContainerComponent`.
+	// The default `"div"` fallback value is just a legacy compatibility relic, and so is the `as` property.
+	if (!ItemsContainerComponent) {
+		ItemsContainerComponent = as || 'div'
+	}
+
 	// It turns out that since May 2022, `useVirtualScroller()` hook completely ignored the `tbody` property.
 	// Instead, it always derived `tbody` property value from `as` property value by comparing it to `"tbody"` string.
 	// As a result, it seemed like the explicit passing of `tbody` property didn't really work as intended.
@@ -71,11 +93,22 @@ function VirtualScroller({
 	// without a developer having to manually specify it. So the `tbody` property was deprecated.
 	// It still exists though for backwards compatibility with the older versions of the package.
 	if (tbody === undefined) {
-		tbody = AsComponent === 'tbody'
+		// `tbody` should be somehow detected before any DOM Elements have been mounted.
+		// This is because during Server-Side Render there's no DOM Elements tree at all.
+		// And server-sider render result is required to be exactly the same as client-side render result.
+		// This means that `tbody` detection for the purposes of getting the initial
+		// `className` or `style` property values must not rely on any DOM Elements at all,
+		// and should use some other means such as explicitly passing a `tbody: true` property
+		// (as it used to be in the past) or detecting `<tbody/>` tag usage from the
+		// `itemsContainerCompoent` property value.
+		tbody = ItemsContainerComponent === 'tbody'
 	}
 
 	// List items "container" DOM Element reference.
-	const container = useRef()
+	const {
+		setRef: setItemsContainerRef,
+		internalRef: itemsContainer
+	} = useForwardedRef(itemsContainerRef)
 
 	// Create a `VirtualScroller` instance.
 	const virtualScroller = useVirtualScroller({
@@ -85,6 +118,7 @@ function VirtualScroller({
 		estimatedItemHeight,
 		getEstimatedItemHeight,
 		getEstimatedVisibleItemRowsCount,
+		getEstimatedInterItemVerticalSpacing,
 		bypass,
 		// bypassBatchSize,
 		onItemInitialRender,
@@ -99,12 +133,11 @@ function VirtualScroller({
 		getScrollableContainer,
 		getColumnsCount,
 		getItemId,
-		AsComponent,
 		initialState,
 		getInitialItemState,
 		onStateChange
 	}, {
-		container
+		itemsContainer
 	})
 
 	// Only compute the initial state once.
@@ -139,6 +172,7 @@ function VirtualScroller({
 	// "reuse" `itemComponent`s in cases when `items` are changed.
 	const {
 		getItemKey,
+		onItemKeysReset,
 		usesAutogeneratedItemKeys,
 		updateItemKeysForNewItems
 	} = useItemKeys({
@@ -148,14 +182,16 @@ function VirtualScroller({
 	// Cache per-item `setItemState` functions' "references"
 	// so that item components don't get re-rendered needlessly.
 	const getSetItemState = useSetItemState({
-		initialItemsCount: itemsProperty.length,
+		getItemKey,
+		onItemKeysReset,
 		virtualScroller
 	})
 
 	// Cache per-item `onItemHeightDidChange` functions' "references"
 	// so that item components don't get re-rendered needlessly.
 	const getOnItemHeightDidChange = useOnItemHeightDidChange({
-		initialItemsCount: itemsProperty.length,
+		getItemKey,
+		onItemKeysReset,
 		virtualScroller
 	})
 
@@ -190,6 +226,14 @@ function VirtualScroller({
 		}
 	}, [])
 
+	// A developer might "forget" to pass `itemsContainerComponent="tbody"` property
+	// when using a `<tbody/>` as a container for list items.
+	// This hook validates that the developer didn't "forget" to do that in such case.
+	useValidateTableBodyItemsContainer({
+		virtualScroller,
+		tbody
+	})
+
 	// `willRender()` function is no longer used.
 	//
 	// // `getSnapshotBeforeUpdate()` is called right before `componentDidUpdate()`.
@@ -205,11 +249,15 @@ function VirtualScroller({
 	// 	return null
 	// }
 
-	className = useClassName(className, {
+	const classNamePassThrough = classNameProperty || itemsContainerComponentProps && itemsContainerComponentProps.className
+
+	const className = useClassName(classNamePassThrough, {
 		tbody
 	})
 
-	const style = useStyle({
+	const stylePassThrough = itemsContainerComponentProps && itemsContainerComponentProps.style
+
+	const style = useStyle(stylePassThrough, {
 		tbody,
 		state: stateToRender
 	})
@@ -222,34 +270,39 @@ function VirtualScroller({
 	} = stateToRender
 
 	return (
-		<AsComponent
+		<ItemsContainerComponent
+			{...itemsContainerComponentProps}
 			{...rest}
-			ref={container}
+			ref={setItemsContainerRef}
 			className={className}
 			style={style}>
 			{currentItems.map((item, i) => {
 				if (i >= firstShownItemIndex && i <= lastShownItemIndex) {
-					// * Passing `item` as `children` property is legacy and is deprecated.
+					// * Passing the `item` as `children` property is legacy and is deprecated.
 					//   If version `2.x` is published in some hypothetical future,
-					//   the `item` and `itemIndex` properties should be moved below
-					//   `{...itemComponentProps}`.
+					//   the `item` property should be moved below `{...itemComponentProps}`.
 					//
-					// * Passing `itemIndex` property is legacy and is deprecated.
-					//   The rationale is that setting new `items` on a React component
-					//   is an asynchronous operation, so when a user obtains `itemIndex`,
-					//   they don't know which `items` list does that index correspond to,
-					//   therefore making it useless, or even buggy if used incorreclty.
+					// * Passing `itemIndex` property is legacy and is deprecated
+					//   and could be removed in some future.
+					//   The rationale for deprecation is that the `items` property
+					//   is not constant and could change, in which case the `itemIndex` value
+					//   would be of no use because the application wouldn't know
+					//   which exact `items` it corresponds to at any given moment in time.
+					//   Having just the `itemIndex` and no actual `item` is therefore considered useless.
+					//   Instead, a developer could simply use `getItemKey(item)` function.
 					//
-					// * Passing `onStateChange` property for legacy reasons.
+					// * `onStateChange` property is passed here for legacy reasons.
 					//   The new property name is `setState`.
-					//   The old property name `onStateChange` is deprecated.
+					//   The old property name `onStateChange` is deprecated
+					//   and could be removed in some future.
 					//
-					// * Passing `onHeightChange` property for legacy reasons.
+					// * `onHeightChange` property is passed here for legacy reasons.
 					//   The new property name is `onHeightDidChange`.
-					//   The old property name `onHeightChange` is deprecated.
+					//   The old property name `onHeightChange` is deprecated
+					//   and could be removed in some future.
 					//
 					return (
-						<Component
+						<ItemComponent
 							item={item}
 							itemIndex={i}
 							{...itemComponentProps}
@@ -260,12 +313,12 @@ function VirtualScroller({
 							onHeightChange={getOnItemHeightDidChange(i)}
 							onHeightDidChange={getOnItemHeightDidChange(i)}>
 							{item}
-						</Component>
+						</ItemComponent>
 					)
 				}
 				return null
 			})}
-		</AsComponent>
+		</ItemsContainerComponent>
 	)
 }
 
@@ -282,15 +335,25 @@ const elementType = PropTypes.elementType || PropTypes.oneOfType([
 ])
 
 VirtualScroller.propTypes = {
+	// `as` property is deprecated, use `itemsContainerComponent` property instead.
 	as: elementType,
 	items: PropTypes.arrayOf(PropTypes.any).isRequired,
 	itemComponent: elementType.isRequired,
 	itemComponentProps: PropTypes.object,
+	// `itemsContainerComponent` property is not required just for legacy compatibility reasons.
+	// Any new applications should explicitly specify it.
+	itemsContainerComponent: elementType,
+	itemsContainerComponentProps: PropTypes.object,
+	itemsContainerRef: PropTypes.oneOfType([
+		PropTypes.func,
+		PropTypes.shape({ current: PropTypes.object })
+	]),
 	// `estimatedItemHeight` property name is deprecated,
 	// use `getEstimatedItemHeight` property instead.
 	estimatedItemHeight: PropTypes.number,
 	getEstimatedItemHeight: PropTypes.func,
 	getEstimatedVisibleItemRowsCount: PropTypes.func,
+	getEstimatedInterItemVerticalSpacing: PropTypes.func,
 	bypass: PropTypes.bool,
 	// bypassBatchSize: PropTypes.number,
 	// `tbody` property is deprecated.

package/source/react/useClassName.js

@@ -1,4 +1,4 @@
-import { TBODY_CLASS_NAME } from '../DOM/tbody.js'
+import { CLASS_NAME_FOR_TBODY_WORKAROUND } from '../DOM/tbody.js'
 
 export default function useClassName(className, { tbody }) {
 	// For `<tbody/>`, a workaround is used which uses CSS variables
@@ -6,9 +6,9 @@ export default function useClassName(className, { tbody }) {
 	// See `addTbodyStyles()` function in `../DOM/tbody.js` for more details.
 	if (tbody) {
 		if (className) {
-			return className + ' ' + TBODY_CLASS_NAME
+			return className + ' ' + CLASS_NAME_FOR_TBODY_WORKAROUND
 		}
-		return TBODY_CLASS_NAME
+		return CLASS_NAME_FOR_TBODY_WORKAROUND
 	}
 	return className
 }

package/source/react/useForwardedRef.js

@@ -0,0 +1,39 @@
+// import type { MutableRefObject } from 'react'
+import { useCallback, useRef } from 'react'
+
+// When a React component receives a `ref` which it is supposed to "forward"
+// and when it would like to also read that `ref` in its internal implementation,
+// this `useForwardedRef()` hook could be used to get read access to such "forwarded" ref
+// inside the component's internal implementation.
+//
+// ```js
+// const FormWithAutoFocus = forwardRef((props, ref) => {
+//   const { setRef, internalRef } = useForwardedRef<RefValueType>(ref)
+//
+//   useEffect(() => {
+//     internalRef.current.focus()
+//   }, [])
+//
+//   return (
+//     <Form ref={setRef} {...props}/>
+//   )
+// })
+// ```
+//
+// export default function useForwardedRef<T extends MutableRefObject<any>>(ref) {
+export default function useForwardedRef(ref) {
+	const internalRef = useRef() // as T
+
+	const setRef = useCallback((instance) => {
+		internalRef.current = instance
+		if (ref) {
+			if (typeof ref === 'function') {
+				ref(instance)
+			} else {
+				ref.current = instance
+			}
+		}
+	}, [ref])
+
+	return { setRef, internalRef }
+}

package/source/react/useInstanceMethods.js

@@ -8,17 +8,25 @@ export default function useInstanceMethods(ref, {
 }) {
 	useImperativeHandle(ref, () => ({
 		// This is a proxy for `VirtualScroller`'s `.updateLayout` instance method.
-		updateLayout: () => virtualScroller.updateLayout(),
+		updateLayout: () => {
+			virtualScroller.updateLayout()
+		},
 
 		// (deprecated)
 		// `.layout()` method name is deprecated, use `.updateLayout()` instead.
-    layout: () => virtualScroller.updateLayout(),
+    layout: () => {
+			virtualScroller.updateLayout()
+		},
 
 		// (deprecated)
-		updateItem: (i) => reportError(`[virtual-scroller] ".updateItem(i)" method of React <VirtualScroller/> has been removed`),
+		updateItem: (i) => {
+			reportError(`[virtual-scroller] ".updateItem(i)" method of React <VirtualScroller/> has been removed`)
+		},
 
 		// (deprecated)
-		renderItem: (i) => reportError(`[virtual-scroller] ".renderItem(i)" method of React <VirtualScroller/> has been removed`)
+		renderItem: (i) => {
+			reportError(`[virtual-scroller] ".renderItem(i)" method of React <VirtualScroller/> has been removed`)
+		}
 	}), [
 		virtualScroller
 	])

package/source/react/useItemKeys.js

@@ -3,15 +3,31 @@ import log from '../utility/debug.js'
 import { useRef, useMemo, useCallback } from 'react'
 
 export default function useItemKeys({ getItemId }) {
+	// These "listeners" will be called in case the auto-generated item keys are reset
+	// due to the prefix counter number reaching its maximum allowed value.
+	const itemKeysResetEventListeners = useMemo(() => {
+		return []
+	}, [])
+
+	// Adds an "on item keys reset" listener.
+	const onItemKeysReset = useCallback((listener) => {
+		itemKeysResetEventListeners.push(listener)
+	}, [])
+
 	// List items are rendered with `key`s so that React doesn't
 	// "reuse" `itemComponent`s in cases when `items` are changed.
   const itemKeyPrefix = useRef()
 
-	// Generates a unique `key` prefix for list item components.
+	// When no `getItemId()` function is specified, it creates an item key
+	// from an auto-generated unique prefix and the item's index in the `items` array.
+	// This way, when the `items` change, their keys are also changed.
 	const generateItemKeyPrefix = useMemo(() => {
 		let counter = 0
 		function getNextCounter() {
 			if (counter === Number.MAX_SAFE_INTEGER) {
+				for (const listener of itemKeysResetEventListeners) {
+					listener()
+				}
 				counter = 0
 			}
 			counter++
@@ -21,11 +37,12 @@ export default function useItemKeys({ getItemId }) {
 			itemKeyPrefix.current = String(getNextCounter())
 		}
 	}, [
-		itemKeyPrefix
+		itemKeyPrefix,
+		itemKeysResetEventListeners
 	])
 
 	useMemo(() => {
-		// Generate an initial unique `key` prefix for list item components.
+		// Generate an initial unique `key` prefix for list items.
 		generateItemKeyPrefix()
 	}, [])
 
@@ -50,7 +67,7 @@ export default function useItemKeys({ getItemId }) {
 	 */
 	const getItemKey = useCallback((item, i) => {
 		if (getItemId) {
-			return getItemId(item)
+			return String(getItemId(item))
 		}
 		return `${itemKeyPrefix.current}:${i}`
 	}, [
@@ -60,6 +77,7 @@ export default function useItemKeys({ getItemId }) {
 
 	return {
 		getItemKey,
+		onItemKeysReset,
 		usesAutogeneratedItemKeys,
 		updateItemKeysForNewItems: generateItemKeyPrefixIfNotUsingItemIds
 	}

package/source/react/useOnItemHeightDidChange.js

@@ -1,28 +1,47 @@
 import { useMemo, useRef, useCallback } from 'react'
 
 export default function useOnItemHeightDidChange({
-	initialItemsCount,
+	getItemKey,
+	onItemKeysReset,
 	virtualScroller
 }) {
-	// Only compute the initial cache value once.
-	const initialCacheValue = useMemo(() => {
-		return new Array(initialItemsCount)
+	// Only create the initial cache once.
+	const initialCache = useMemo(() => {
+		return createCache()
 	}, [])
 
-	// Handler functions cache.
-	const cache = useRef(initialCacheValue)
+	// A cache of `onItemHeightDidChange()` functions.
+	const cache = useRef(initialCache)
+
+	// Adds an "on item keys reset" listener that clears the cache when item keys are reset.
+	useMemo(() => {
+		onItemKeysReset(() => {
+			cache.current = createCache()
+		})
+	}, [])
 
 	// Caches per-item `onItemHeightDidChange` functions' "references"
 	// so that item components don't get re-rendered needlessly.
-	const getOnItemHeightDidChange = useCallback((i) => {
-		if (!cache.current[i]) {
-			cache.current[i] = () => virtualScroller.onItemHeightDidChange(i)
+	const getOnItemHeightDidChange = useCallback((item) => {
+		const itemKey = getItemKey(item)
+		if (!cache.current[itemKey]) {
+			cache.current[itemKey] = () => {
+				virtualScroller.onItemHeightDidChange(item)
+			}
 		}
-		return cache.current[i]
+		return cache.current[itemKey]
 	}, [
 		virtualScroller,
+		getItemKey,
 		cache
 	])
 
 	return getOnItemHeightDidChange
+}
+
+function createCache() {
+	// It could also use a `new Map()` here and then use `item` as a key.
+	// Although, sometimes an `item` "reference" might change while it still being
+	// the same item, i.e. having the same `getItemId(item)` value.
+	return {}
 }

package/source/react/useSetItemState.js

@@ -1,28 +1,50 @@
 import { useMemo, useRef, useCallback } from 'react'
 
 export default function useSetItemState({
-	initialItemsCount,
+	getItemKey,
+	onItemKeysReset,
 	virtualScroller
 }) {
-	// Only compute the initial cache value once.
-	const initialCacheValue = useMemo(() => {
-		return new Array(initialItemsCount)
+	// Only create the initial cache once.
+	const initialCache = useMemo(() => {
+		return createCache()
 	}, [])
 
-	// Handler functions cache.
-	const cache = useRef(initialCacheValue)
+	// A cache of `setItemState()` functions.
+	const cache = useRef(initialCache)
+
+	// Adds an "on item keys reset" listener that clears the cache when item keys are reset.
+	useMemo(() => {
+		onItemKeysReset(() => {
+			cache.current = createCache()
+		})
+	}, [])
 
 	// Caches per-item `setItemState` functions' "references"
 	// so that item components don't get re-rendered needlessly.
-	const getSetItemState = useCallback((i) => {
-		if (!cache.current[i]) {
-			cache.current[i] = (itemState) => virtualScroller.setItemState(i, itemState)
+	// I.e. it could just re-create this function every time
+	// but that would also make React re-render the item component every time
+	// which wouldn't be efficient.
+	const getSetItemState = useCallback((item) => {
+		const itemKey = getItemKey(item)
+		if (!cache.current[itemKey]) {
+			cache.current[itemKey] = (itemState) => {
+				virtualScroller.setItemState(item, itemState)
+			}
 		}
-		return cache.current[i]
+		return cache.current[itemKey]
 	}, [
 		virtualScroller,
+		getItemKey,
 		cache
 	])
 
 	return getSetItemState
+}
+
+function createCache() {
+	// It could also use a `new Map()` here and then use `item` as a key.
+	// Although, sometimes an `item` "reference" might change while it still being
+	// the same item, i.e. having the same `getItemId(item)` value.
+	return {}
 }