virtual-scroller 1.8.1 → 1.9.0

package/source/react/useClassName.js

@@ -0,0 +1,14 @@
+import { TBODY_CLASS_NAME } from '../DOM/tbody.js'
+
+export default function useClassName(className, { tbody }) {
+	// For `<tbody/>`, a workaround is used which uses CSS variables
+	// and a special CSS class name "VirtualScroller".
+	// See `addTbodyStyles()` function in `../DOM/tbody.js` for more details.
+	if (tbody) {
+		if (className) {
+			return className + ' ' + TBODY_CLASS_NAME
+		}
+		return TBODY_CLASS_NAME
+	}
+	return className
+}

package/source/react/useHandleItemsChange.js

@@ -0,0 +1,115 @@
+import { useRef, useLayoutEffect } from 'react'
+
+// If new `items` are 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
+//   new `items` are rendered.
+//
+// * 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, {
+	virtualScroller,
+	// `preserveScrollPosition` property name is deprecated,
+	// use `preserveScrollPositionOnPrependItems` property instead.
+	preserveScrollPosition,
+	preserveScrollPositionOnPrependItems,
+	updateItemKeysForNewItems
+}) {
+	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.
+
+	// A long "advanced" sidenote on why capturing scroll Y position
+	// is done during render instead of in an "effect":
+	//
+	// Previously, capturing scroll Y position was being done in `useLayoutEffect()`
+	// but it was later found out that it wouldn't work for a "Show previous" button
+	// scenario because that button would get hidden by the time `useLayoutEffect()`
+	// gets called when there're no more "previous" items to show.
+	//
+	// Consider this code example:
+	//
+	// const { fromIndex, items } = this.state
+	// const items = allItems.slice(fromIndex)
+	// return (
+	// 	{fromIndex > 0 &&
+	// 		<button onClick={this.onShowPrevious}>
+	// 			Show previous
+	// 		</button>
+	// 	}
+	// 	<VirtualScroller
+	// 		items={items}
+	// 		itemComponent={ItemComponent}/>
+	// )
+	//
+	// Consider a user clicks "Show previous" to show the items from the start.
+	// By the time `componentDidUpdate()` is called on `<VirtualScroller/>`,
+	// the "Show previous" button has already been hidden
+	// (because there're no more "previous" items)
+	// which results in the scroll Y position jumping forward
+	// by the height of that "Show previous" button.
+	// This is because `<VirtualScroller/>` captures scroll Y
+	// position when items are prepended via `.setItems()`
+	// when the "Show previous" button is still being shown,
+	// and then restores scroll Y position in `.onRender()`
+	// when the "Show previous" button has already been hidden:
+	// that's the reason for the scroll Y "jump".
+	//
+	// To prevent that, scroll Y position is captured at `render()`
+	// time rather than later in `componentDidUpdate()`: this way,
+	// 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
+	if (hasItemsPropertyChanged) {
+		let itemsHaveChanged = true
+		let shouldUpdateItemKeys = true
+		const itemsDiff = virtualScroller.getItemsDiff(renderedItems, items)
+		// `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 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
+			}
+		}
+
+		if (itemsHaveChanged) {
+			// Set the new `items`.
+			virtualScroller.setItems(items, {
+				// `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/useInstanceMethods.js

@@ -0,0 +1,25 @@
+import { useImperativeHandle } from 'react'
+
+import { reportError } from '../utility/debug.js'
+
+// Adds instance methods to the React component.
+export default function useInstanceMethods(ref, {
+	virtualScroller
+}) {
+	useImperativeHandle(ref, () => ({
+		// This is a proxy for `VirtualScroller`'s `.updateLayout` instance method.
+		updateLayout: () => virtualScroller.updateLayout(),
+
+		// (deprecated)
+		// `.layout()` method name is deprecated, use `.updateLayout()` instead.
+    layout: () => virtualScroller.updateLayout(),
+
+		// (deprecated)
+		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`)
+	}), [
+		virtualScroller
+	])
+}

package/source/react/useItemKeys.js

@@ -0,0 +1,59 @@
+import { useRef, useMemo, useCallback } from 'react'
+
+export default function useItemKeys({ getItemId }) {
+	// 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.
+	const generateItemKeyPrefix = useMemo(() => {
+		let counter = 0
+		function getNextCounter() {
+			if (counter === Number.MAX_SAFE_INTEGER) {
+				counter = 0
+			}
+			counter++
+			return counter
+		}
+		return () => {
+			itemKeyPrefix.current = String(getNextCounter())
+		}
+	}, [
+		itemKeyPrefix
+	])
+
+	useMemo(() => {
+		// Generate an initial unique `key` prefix for list item components.
+		generateItemKeyPrefix()
+	}, [])
+
+	const generateItemKeyPrefixIfNotUsingItemIds = useCallback(() => {
+		if (!getItemId) {
+			generateItemKeyPrefix()
+		}
+	}, [
+		getItemId,
+		generateItemKeyPrefix
+	])
+
+	/**
+	 * Returns a `key` for an `item`'s element.
+	 * @param  {object} item — The item.
+	 * @param  {number} i — Item's index in `items` list.
+	 * @return {any}
+	 */
+	const getItemKey = useCallback((item, i) => {
+		if (getItemId) {
+			return getItemId(item)
+		}
+		return `${itemKeyPrefix.current}:${i}`
+	}, [
+		getItemId,
+		itemKeyPrefix
+	])
+
+	return {
+		getItemKey,
+		updateItemKeysForNewItems: generateItemKeyPrefixIfNotUsingItemIds
+	}
+}

package/source/react/useOnItemHeightChange.js

@@ -0,0 +1,28 @@
+import { useMemo, useRef, useCallback } from 'react'
+
+export default function useOnItemHeightChange({
+	items,
+	virtualScroller
+}) {
+	// Only compute the initial cache value once.
+	const initialCacheValue = useMemo(() => {
+		return new Array(items.length)
+	}, [])
+
+	// Handler functions cache.
+	const cache = useRef(initialCacheValue)
+
+	// Caches per-item `onItemHeightChange` functions' "references"
+	// so that item components don't get re-rendered needlessly.
+	const getOnItemHeightChange = useCallback((i) => {
+		if (!cache.current[i]) {
+			cache.current[i] = () => virtualScroller.onItemHeightChange(i)
+		}
+		return cache.current[i]
+	}, [
+		virtualScroller,
+		cache
+	])
+
+	return getOnItemHeightChange
+}

package/source/react/useOnItemStateChange.js

@@ -0,0 +1,28 @@
+import { useMemo, useRef, useCallback } from 'react'
+
+export default function useOnItemStateChange({
+	items,
+	virtualScroller
+}) {
+	// Only compute the initial cache value once.
+	const initialCacheValue = useMemo(() => {
+		return new Array(items.length)
+	}, [])
+
+	// Handler functions cache.
+	const cache = useRef(initialCacheValue)
+
+	// Caches per-item `onItemStateChange` functions' "references"
+	// so that item components don't get re-rendered needlessly.
+	const getOnItemStateChange = useCallback((i) => {
+		if (!cache.current[i]) {
+			cache.current[i] = (itemState) => virtualScroller.onItemStateChange(i, itemState)
+		}
+		return cache.current[i]
+	}, [
+		virtualScroller,
+		cache
+	])
+
+	return getOnItemStateChange
+}

package/source/react/useState.js

@@ -0,0 +1,114 @@
+import { useState, useRef, useLayoutEffect } from 'react'
+
+// Creates state management functions.
+export default function _useState({ initialState, onRender, items }) {
+	// `VirtualScroller` state.
+	//
+	// The `_stateUpdate` variable shouldn't be used directly
+	// because in some cases its value may not represent
+	// the actual `state` of the `VirtualScroller`.
+	//
+	// * It will contain an incorrect initial value if `initialState` property is passed
+	//   because it doesn't get initialized to `initialState`.
+	//
+	// * If `items` property gets changed, `state` reference variable gets updated immediately
+	//   but the `_stateUpdate` variable here doesn't (until the component re-renders some other time).
+	//
+	// Instead, use the `state` reference below.
+	//
+	const [_stateUpdate, _setStateUpdate] = useState()
+
+	// This `state` reference is used for accessing the externally stored
+	// virtual scroller state from inside a `VirtualScroller` instance.
+	//
+	// It's also the "source of truth" on the actual `VirtualScroller` state.
+	//
+	const state = useRef(initialState)
+
+	// Accumulates state updates until they have been applied.
+	const targetState = useRef(initialState)
+
+	// Update the current state reference.
+	//
+	// Ignores the cases when `state` reference has already been updated
+	// "immediately" bypassing a `_setStateUpdate()` call, because
+	// in that case, `_stateUpdate` holds a stale value.
+	//
+	if (state.current !== targetState.current) {
+		state.current = _stateUpdate
+	}
+
+	// Call `onRender()` right after every state update.
+	//
+	// When `items` property changes, `useHandleItemsChange()` hook doesn't call
+	// `_setStateUpdate()` because there's no need for a re-render.
+	// But chaning `items` still does trigger a `VirtualScroller` state update,
+	// so added `items` property in the list of this "effect"'s dependencies.
+	//
+	useLayoutEffect(() => {
+		onRender()
+	}, [
+		_stateUpdate,
+		items
+	])
+
+	return {
+		getState: () => state.current,
+
+		// Updates existing state.
+		//
+		// State updates are incremental meaning that this code should mimick
+		// the classic `React.Component`'s `this.setState()` behavior
+		// when calling `this.setState()` doesn't replace `state` but rather merges
+		// a set of the updated state properties with the rest of the old ones.
+		//
+		// The reason is that `useState()` updates are "asynchronous" (not immediate),
+		// and simply merging over `...state` would merge over potentially stale
+		// property values in cases when more than a single `updateState()` call is made
+		// before the state actually updates, resulting in losing some of the state updates.
+		//
+		// For example, the first `updateState()` call updates shown item indexes,
+		// and the second `updateState()` call updates `verticalSpacing`.
+		// If it was simply `updateState({ ...state, ...stateUpdate })`
+		// then the second state update could overwrite the first state update,
+		// resulting in incorrect items being shown/hidden.
+		//
+		// Using `...state.current` instead of `...pendingState.current` here
+		// would produce "stale" results.
+		//
+		updateState: (stateUpdate) => {
+			const newState = {
+				...targetState.current,
+				...stateUpdate
+			}
+			targetState.current = newState
+			// If `items` property did change the component detects it at render time
+			// and updates `VirtualScroller` items immediately by calling `.setItems()`.
+			// But, since all of that happens at render time and not in an "effect",
+			// if the state update was done as usual by calling `_setStateUpdate()`,
+			// React would throw an error about updating state during render.
+			// Hence, state update in that particular case should happen "directly",
+			// without waiting for an "asynchronous" effect to trigger and call
+			// an "asyncronous" `_setStateUpdate()` function.
+			//
+			// Updating state directly in that particular case works because there
+			// already is a render ongoing, so there's no need to re-render the component
+			// again after such render-time state update.
+			//
+			// When the initial `VirtualScroller` state is being set, it contains an `.items`
+			// property too, but that initial setting is done using another function called
+			// `setInitialState()`, so using `if (stateUpdate.items)` condition here for describing
+			// just the case when `state` has been updated as a result of a `setItems()` call
+			// seems to be fine.
+			//
+			if (stateUpdate.items) {
+				// If a `stateUpdate` contains `items` then it means that there was a `setItems()` call.
+				// No need to trigger a re-render — the component got re-rendered anyway.
+				// Just update the `state` "in place".
+				state.current = newState
+			} else {
+				_setStateUpdate(newState)
+			}
+		}
+	}
+}

package/source/react/useStyle.js

@@ -0,0 +1,20 @@
+import px from '../utility/px.js'
+
+export default function useStyle({
+	tbody,
+	virtualScroller
+}) {
+	if (tbody) {
+		return
+	}
+
+	const {
+		beforeItemsHeight,
+		afterItemsHeight
+	} = virtualScroller.getState()
+
+	return {
+		paddingTop: px(beforeItemsHeight),
+		paddingBottom: px(afterItemsHeight)
+	}
+}

package/source/react/useVirtualScroller.js

@@ -0,0 +1,59 @@
+import { useMemo } from 'react'
+
+import VirtualScroller from '../VirtualScroller.js'
+
+// Creates a `VirtualScroller` instance.
+export default function useVirtualScroller({
+	items,
+	estimatedItemHeight,
+	bypass,
+	// bypassBatchSize,
+	tbody,
+	onItemInitialRender,
+	// `onItemFirstRender(i)` is deprecated, use `onItemInitialRender(item)` instead.
+	onItemFirstRender,
+	initialScrollPosition,
+	onScrollPositionChange,
+	measureItemsBatchSize,
+	// `scrollableContainer` property is deprecated.
+	// Use `getScrollableContainer()` property instead.
+	scrollableContainer,
+	getScrollableContainer,
+	getColumnsCount,
+	getItemId,
+	AsComponent,
+	initialState,
+	onStateChange
+}, {
+	container
+}) {
+	return useMemo(() => {
+		// Create `virtual-scroller` instance.
+		return new VirtualScroller(
+			() => container.current,
+			items,
+			{
+				_useTimeoutInRenderLoop: true,
+				estimatedItemHeight,
+				bypass,
+				// bypassBatchSize,
+				tbody,
+				onItemInitialRender,
+				// `onItemFirstRender(i)` is deprecated, use `onItemInitialRender(item)` instead.
+				onItemFirstRender,
+				initialScrollPosition,
+				onScrollPositionChange,
+				measureItemsBatchSize,
+				// `scrollableContainer` property is deprecated.
+				// Use `getScrollableContainer()` property instead.
+				scrollableContainer,
+				getScrollableContainer,
+				getColumnsCount,
+				getItemId,
+				tbody: AsComponent === 'tbody',
+				state: initialState,
+				onStateChange
+			}
+		)
+	}, [])
+}

package/source/react/useVirtualScrollerStartStop.js

@@ -0,0 +1,12 @@
+import { useLayoutEffect } from 'react'
+
+export default function useVirtualScrollerStartStop(virtualScroller) {
+	useLayoutEffect(() => {
+		// Start listening to scroll events.
+		virtualScroller.start()
+		return () => {
+			// Stop listening to scroll events.
+			virtualScroller.stop()
+		}
+	}, [])
+}

package/source/test/Engine.js

@@ -0,0 +1,11 @@
+import ItemsContainer from './ItemsContainer.js'
+import ScrollableContainer from './ScrollableContainer.js'
+
+export default {
+	createItemsContainer(getItemsContainerElement) {
+		return new ItemsContainer(getItemsContainerElement)
+	},
+	createScrollableContainer(getScrollableContainerElement, getItemsContainerElement) {
+		return new ScrollableContainer(getScrollableContainerElement, getItemsContainerElement)
+	}
+}

package/source/test/ItemsContainer.js

@@ -0,0 +1,87 @@
+export default class ItemsContainer {
+	/**
+	 * Constructs a new "container" from an element.
+	 * @param {function} getElement
+	 */
+	constructor(getElement) {
+		this.getElement = getElement
+	}
+
+	/**
+	 * Returns an item element's "top offset", relative to the items `container`'s top edge.
+	 * @param  {number} renderedElementIndex — An index of an item relative to the "first shown item index". For example, if the list is showing items from index 8 to index 12 then `renderedElementIndex = 0` would mean the item at index `8`.
+	 * @return {number}
+	 */
+	getNthRenderedItemTopOffset(renderedElementIndex) {
+		const children = this.getElement().children
+		const maxWidth = this.getElement().width
+		let topOffset = this.getElement().paddingTop
+		let rowWidth
+		let rowHeight
+		let startNewRow = true
+		let i = 0
+		while (i <= renderedElementIndex) {
+			if (startNewRow || rowWidth + children[i].width > maxWidth) {
+				if (i > 0) {
+					topOffset += rowHeight
+					topOffset += children[i].marginTop
+				}
+				rowWidth = children[i].width
+				rowHeight = children[i].height
+				if (rowWidth > maxWidth) {
+					startNewRow = true
+				} else {
+					startNewRow = false
+				}
+			} else {
+				rowWidth += children[i].width
+				rowHeight = Math.max(rowHeight, children[i].height)
+			}
+			i++
+		}
+		return topOffset
+	}
+
+	/**
+	 * Returns an item element's height.
+	 * @param  {number} renderedElementIndex — An index of an item relative to the "first shown item index". For example, if the list is showing items from index 8 to index 12 then `renderedElementIndex = 0` would mean the item at index `8`.
+	 * @return {number}
+	 */
+	getNthRenderedItemHeight(renderedElementIndex) {
+		return this.getElement().children[renderedElementIndex].height
+	}
+
+	/**
+	 * Returns items container height.
+	 * @return {number}
+	 */
+	getHeight() {
+		const children = this.getElement().children
+		const maxWidth = this.getElement().width
+		let contentHeight = this.getElement().paddingTop
+		let i = 0
+		while (i < children.length) {
+			let rowWidth = 0
+			let rowHeight = 0
+			while (rowWidth <= maxWidth && i < children.length) {
+				if (rowWidth === 0 && i > 0) {
+					const verticalSpacing = children[i].marginTop
+					contentHeight += verticalSpacing
+				}
+				rowWidth += children[i].width
+				rowHeight = Math.max(rowHeight, children[i].height)
+				i++
+			}
+			contentHeight += rowHeight
+		}
+		contentHeight += this.getElement().paddingBottom
+		return contentHeight
+	}
+
+	/**
+	 * Removes all item elements of an items container.
+	 */
+	clear() {
+		this.getElement().children = []
+	}
+}

package/source/test/ScrollableContainer.js

@@ -0,0 +1,88 @@
+export default class ScrollableContainer {
+	/**
+	 * Constructs a new "scrollable container" from an element.
+	 * @param {func} getElement — Returns the scrollable container element.
+	 * @param {func} getItemsContainerElement — Returns items "container" element.
+	 */
+	constructor(getElement, getItemsContainerElement) {
+		this.getElement = getElement
+		this.getItemsContainerElement = getItemsContainerElement
+		this.scrollTop = 0
+	}
+
+	/**
+	 * Returns the current scroll position.
+	 * @return {number}
+	 */
+	getScrollY() {
+		return this.scrollTop
+	}
+
+	/**
+	 * Scrolls to a specific position.
+	 * @param {number} scrollY
+	 */
+	scrollToY(scrollY) {
+		this.scrollTop = scrollY
+		if (this.onScrollListener) {
+			this.onScrollListener()
+		}
+	}
+
+	/**
+	 * Returns "scrollable container" width,
+	 * i.e. the available width for its content.
+	 * @return {number}
+	 */
+	getWidth() {
+		return this.getElement().width
+	}
+
+	/**
+	 * Returns the height of the "scrollable container" itself.
+	 * Not to be confused with the height of "scrollable container"'s content.
+	 * @return {number}
+	 */
+	getHeight() {
+		return this.getElement().height
+	}
+
+	/**
+	 * Returns a "top offset" of an items container element
+	 * relative to the "scrollable container"'s top edge.
+	 * @return {number}
+	 */
+	getItemsContainerTopOffset() {
+		return 0
+	}
+
+	/**
+	 * Adds a "scroll" event listener to the "scrollable container".
+	 * @param {onScroll} Should be called whenever the scroll position inside the "scrollable container" (potentially) changes.
+	 * @return {function} Returns a function that stops listening.
+	 */
+	onScroll(onScroll) {
+		this.onScrollListener = onScroll
+		return () => {
+			delete this.onScrollListener
+		}
+	}
+
+	/**
+	 * Adds a "resize" event listener to the "scrollable container".
+	 * @param {onResize} Should be called whenever the "scrollable container"'s width or height (potentially) changes.
+	 * @return {function} Returns a function that stops listening.
+	 */
+	onResize(onResize) {
+		this.onResizeListener = onResize
+		return () => {
+			delete this.onResizeListener
+		}
+	}
+
+	// Returns a `Promise` because `this.onResizeListener()` is a "debounced" function.
+	// See `./utility/debounce.js` for more details.
+	_triggerResizeListener() {
+		return this.onResizeListener()
+	}
+}