virtual-scroller 1.13.0 → 1.14.0

package/source/DOM/VirtualScroller.js

@@ -5,34 +5,46 @@ import px from '../utility/px.js'
 
 export default class VirtualScroller {
   constructor(itemsContainerElement, items, renderItem, options = {}) {
-    this.container = itemsContainerElement
+    this.getItemsContainerElement = typeof itemsContainerElement === 'function'
+      ? itemsContainerElement
+      : () => itemsContainerElement
+
     this.renderItem = renderItem
 
     const {
       onMount,
       onItemUnmount,
+      readyToStart,
+      readyToRender,
       ...restOptions
     } = options
 
+    // `onMount()` option is deprecated due to no longer being used.
+    // If someone thinks there's a valid use case for it, create an issue.
+    this._onMount = onMount
+
     this.onItemUnmount = onItemUnmount
-    this.tbody = this.container.tagName === 'TBODY'
 
     this.virtualScroller = new VirtualScrollerCore(
-      () => this.container,
+      this.getItemsContainerElement,
       items,
       {
         ...restOptions,
-        render: this.render,
-        tbody: this.tbody
+        render: this.render
       }
     )
 
-    this.start()
-
-    // `onMount()` option is deprecated due to no longer being used.
-    // If someone thinks there's a valid use case for it, create an issue.
-    if (onMount) {
-      onMount()
+    if (readyToRender === false) {
+      // Don't automatically perform the initial render of the list.
+      // This means that neither `this.render()` nor `this.start()` methods should be called.
+    } else if (readyToStart === false) {
+      // Don't automatically call the `.start()` method of the "core" component.
+      // Still, perform the initial render of the list.
+      this.render(this.virtualScroller.getInitialState())
+    } else {
+      // Calls the `.start()` method of the "core" component.
+      // It performs the initial render of the list and starts listening to scroll events.
+      this.start()
     }
   }
 
@@ -45,18 +57,24 @@ export default class VirtualScroller {
       afterItemsHeight
     } = state
 
+    const itemsContainerElement = this.getItemsContainerElement()
+
     // log('~ On state change ~')
     // log('Previous state', prevState)
     // log('New state', state)
 
-    // Set container padding top and bottom.
-    // Work around `<tbody/>` not being able to have `padding`.
+    // Set items container's padding-top and padding-bottom.
+    // But only do that for a non-`<tbody/>` item container
+    // because, strangely, CSS `padding` doesn't work on a `<tbody/>` element.
     // https://gitlab.com/catamphetamine/virtual-scroller/-/issues/1
+    //
     // `this.virtualScroller` hasn't been initialized yet at this stage,
-    // so using `this.tbody` instead of `this.virtualScroller.tbody`.
-    if (!this.tbody) {
-      this.container.style.paddingTop = px(beforeItemsHeight)
-      this.container.style.paddingBottom = px(afterItemsHeight)
+    // so this code can't use `this.virtualScroller.isItemsContainerElementTableBody()` function yet.
+    // Instead, it uses its own method of detecting the use of a `<tbody/>` container.
+    //
+    if (!this.virtualScroller.isItemsContainerElementTableBody()) {
+      itemsContainerElement.style.paddingTop = px(beforeItemsHeight)
+      itemsContainerElement.style.paddingBottom = px(afterItemsHeight)
     }
 
     // Perform an intelligent "diff" re-render if the `items` are the same.
@@ -64,7 +82,7 @@ export default class VirtualScroller {
     // Remove no longer visible items from the DOM.
     if (diffRender) {
       // Decrement instead of increment here because
-      // `this.container.removeChild()` changes indexes.
+      // `itemsContainerElement.removeChild()` changes indexes.
       let i = prevState.lastShownItemIndex
       while (i >= prevState.firstShownItemIndex) {
         if (i >= firstShownItemIndex && i <= lastShownItemIndex) {
@@ -72,20 +90,20 @@ export default class VirtualScroller {
         } else {
           log('DOM: Remove element for item index', i)
           // The item is no longer visible. Remove it.
-          this.unmountItem(this.container.childNodes[i - prevState.firstShownItemIndex])
+          this.unmountItem(itemsContainerElement.childNodes[i - prevState.firstShownItemIndex])
         }
         i--
       }
     } else {
       log('DOM: Rerender the list from scratch')
-      while (this.container.firstChild) {
-        this.unmountItem(this.container.firstChild)
+      while (itemsContainerElement.firstChild) {
+        this.unmountItem(itemsContainerElement.firstChild)
       }
     }
 
     // Add newly visible items to the DOM.
     let shouldPrependItems = diffRender
-    const prependBeforeItemElement = shouldPrependItems && this.container.firstChild
+    const prependBeforeItemElement = shouldPrependItems && itemsContainerElement.firstChild
     let i = firstShownItemIndex
     while (i <= lastShownItemIndex) {
       if (diffRender && i >= prevState.firstShownItemIndex && i <= prevState.lastShownItemIndex) {
@@ -98,16 +116,28 @@ export default class VirtualScroller {
         const item = this.renderItem(items[i])
         if (shouldPrependItems) {
           log('DOM: Prepend element for item index', i)
-          // Append `item` to `this.container` before the retained items.
-          this.container.insertBefore(item, prependBeforeItemElement)
+          // Append `item` to `itemsContainerElement` before the retained items.
+          itemsContainerElement.insertBefore(item, prependBeforeItemElement)
         } else {
           log('DOM: Append element for item index', i)
-          // Append `item` to `this.container`.
-          this.container.appendChild(item)
+          // Append `item` to `itemsContainerElement`.
+          itemsContainerElement.appendChild(item)
         }
       }
       i++
     }
+
+    // Call `onMount()` function when the list has rendered for the first time.
+    //
+    // `onMount()` option is deprecated due to no longer being used.
+    // If someone thinks there's a valid use case for it, create an issue.
+    //
+    if (!this._isMounted) {
+      this._isMounted = true
+      if (this._onMount) {
+        this._onMount()
+      }
+    }
   }
 
   // Public API. Should be "bound" to `this`.
@@ -135,7 +165,8 @@ export default class VirtualScroller {
   }
 
   unmountItem(itemElement) {
-    this.container.removeChild(itemElement)
+    this.getItemsContainerElement().removeChild(itemElement)
+
     if (this.onItemUnmount) {
       this.onItemUnmount(itemElement)
     }

package/source/DOM/tbody.js

@@ -5,17 +5,18 @@ import px from '../utility/px.js'
 
 export const BROWSER_NOT_SUPPORTED_ERROR = 'It looks like you\'re using Internet Explorer which doesn\'t support CSS variables required for a <tbody/> container. VirtualScroller has been switched into "bypass" mode (render all items). See: https://gitlab.com/catamphetamine/virtual-scroller/-/issues/1'
 
-export function supportsTbody() {
-	// Detect Internet Explorer.
+function isInternetExplorer() {
+	// This function detects Internet Explorer using `documentMode` IE-only property.
 	// https://stackoverflow.com/questions/19999388/check-if-user-is-using-ie
-	// `documentMode` is an IE-only property.
-	// Supports IE 9-11. Maybe even IE 8.
+	// The `documentMode` property exists in IE 9-11. Maybe even IE 8.
 	// http://msdn.microsoft.com/en-us/library/ie/cc196988(v=vs.85).aspx
-	if (typeof window !== 'undefined' && window.document.documentMode) {
-		// CSS variables aren't supported in Internet Explorer.
-		return false
-	}
-	return true
+	return typeof window !== 'undefined' && Boolean(window.document.documentMode)
+}
+
+export function supportsTbody() {
+	// Internet Explorer doesn't support CSS Variables
+	// and therefore it will not be able to apply the `<tbody/>` workaround.
+	return !isInternetExplorer()
 }
 
 export const TBODY_CLASS_NAME = 'VirtualScroller'

package/source/Layout.js

@@ -3,7 +3,7 @@ import ScrollableContainerNotReadyError from './ScrollableContainerNotReadyError
 
 export default class Layout {
 	constructor({
-		bypass,
+		isInBypassMode,
 		getInitialEstimatedItemHeight,
 		getInitialEstimatedVisibleItemRowsCount,
 		measureItemsBatchSize,
@@ -19,7 +19,7 @@ export default class Layout {
 		getMaxVisibleAreaHeight,
 		getPreviouslyCalculatedLayout
 	}) {
-		this.bypass = bypass
+		this.isInBypassMode = isInBypassMode
 		this.getInitialEstimatedItemHeight = getInitialEstimatedItemHeight
 		this.getInitialEstimatedVisibleItemRowsCount = getInitialEstimatedVisibleItemRowsCount
 		this.measureItemsBatchSize = measureItemsBatchSize
@@ -100,7 +100,7 @@ export default class Layout {
 		columnsCount,
 		firstShownItemIndex
 	}) {
-		if (this.bypass) {
+		if (this.isInBypassMode()) {
 			return itemsCount - 1
 		}
 		// On server side, at initialization time,

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,8 +1,3 @@
-import {
-	supportsTbody,
-	BROWSER_NOT_SUPPORTED_ERROR
-} from './DOM/tbody.js'
-
 import DOMEngine from './DOM/Engine.js'
 
 import Layout, { LAYOUT_REASON } from './Layout.js'
@@ -12,7 +7,7 @@ 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 +29,7 @@ export default function VirtualScrollerConstructor(
 	options = {}
 ) {
 	const {
+		bypass,
 		render,
 		state,
 		getInitialItemState = () => {},
@@ -46,7 +42,6 @@ export default function VirtualScrollerConstructor(
 		measureItemsBatchSize = 50,
 		getColumnsCount,
 		getItemId,
-		tbody,
 		// `estimatedItemHeight` is deprecated, use `getEstimatedItemHeight()` instead.
 		estimatedItemHeight,
 		getEstimatedVisibleItemRowsCount,
@@ -59,7 +54,6 @@ export default function VirtualScrollerConstructor(
 	} = options
 
 	let {
-		bypass,
 		getEstimatedItemHeight,
 		getScrollableContainer
 	} = options
@@ -104,21 +98,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 +112,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
@@ -238,6 +217,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
@@ -251,7 +237,7 @@ function createHelpers({
 	})
 
 	this.layout = new Layout({
-		bypass: this.bypass,
+		isInBypassMode: this.isInBypassMode,
 		getInitialEstimatedItemHeight: getEstimatedItemHeight,
 		getInitialEstimatedVisibleItemRowsCount: getEstimatedVisibleItemRowsCount,
 		measureItemsBatchSize,
@@ -278,7 +264,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 +294,7 @@ function createHelpers({
 	})
 
 	this.scroll = new Scroll({
-		bypass: this.bypass,
+		isInBypassMode: this.isInBypassMode,
 		scrollableContainer: this.scrollableContainer,
 		itemsContainer: this.itemsContainer,
 		waitForScrollingToStop,

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
+				}
 			}
 		}
 

package/source/VirtualScroller.layout.js

@@ -122,7 +122,7 @@ export default function() {
 		const layoutDuration = Date.now() - startedAt
 
 		// Debugging.
-		log('~ Calculated Layout' + (this.bypass ? ' (bypass)' : '') + ' ~')
+		log('~ Calculated Layout' + (this.isInBypassMode() ? ' (bypass)' : '') + ' ~')
 		if (layoutDuration < SLOW_LAYOUT_DURATION) {
 			// log('Calculated in', layoutDuration, 'ms')
 		} else {
@@ -234,7 +234,7 @@ export default function() {
 
 		const visibleAreaInsideTheList = getCoordinatesOfVisibleAreaInsideTheList.call(this)
 
-		if (this.bypass) {
+		if (this.isInBypassMode()) {
 			return {
 				firstShownItemIndex: 0,
 				lastShownItemIndex: itemsCount - 1,

package/source/VirtualScroller.onRender.js

@@ -27,7 +27,7 @@ export default function() {
 		// Update `<tbody/>` `padding`.
 		// (`<tbody/>` is different in a way that it can't have `margin`, only `padding`).
 		// https://gitlab.com/catamphetamine/virtual-scroller/-/issues/1
-		if (this.tbody) {
+		if (this.isItemsContainerElementTableBody()) {
 			setTbodyPadding(
 				this.getItemsContainerElement(),
 				newState.beforeItemsHeight,

package/source/VirtualScroller.state.js

@@ -166,6 +166,14 @@ export default function createStateHelpers({
 		setInitialState(this.getInitialState())
 	}
 
+	this.setUpState = () => {
+		// If no custom state storage has been configured, use the default one.
+		// Also sets the initial state.
+		if (!this._usesCustomStateStorage) {
+			this.useDefaultStateStorage()
+		}
+	}
+
 	function defaultGetState() {
 		return this.state
 	}

package/source/react/VirtualScroller.js

@@ -37,6 +37,8 @@ function VirtualScroller({
 	getEstimatedItemHeight,
 	getEstimatedVisibleItemRowsCount,
 	bypass,
+	// `tbody` property is deprecated.
+	// Pass `as: "tbody"` property instead.
 	tbody,
 	// `preserveScrollPosition` property name is deprecated,
 	// use `preserveScrollPositionOnPrependItems` property instead.
@@ -62,6 +64,16 @@ function VirtualScroller({
 	getInitialItemState,
 	...rest
 }, ref) {
+	// 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.
+	// In the end, it was decided that perhaps `tbody` property value should always be derived from `as` property
+	// 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'
+	}
+
 	// List items "container" DOM Element reference.
 	const container = useRef()
 
@@ -75,7 +87,6 @@ function VirtualScroller({
 		getEstimatedVisibleItemRowsCount,
 		bypass,
 		// bypassBatchSize,
-		tbody,
 		onItemInitialRender,
 		// `onItemFirstRender(i)` is deprecated, use `onItemInitialRender(item)` instead.
 		onItemFirstRender,
@@ -109,8 +120,7 @@ function VirtualScroller({
 		stateToRender
 	} = useState({
 		initialState: _initialState,
-		onRender: virtualScroller.onRender,
-		itemsProperty
+		onRender: virtualScroller.onRender
 	})
 
 	// Use custom (external) state storage in the `VirtualScroller`.
@@ -283,7 +293,9 @@ VirtualScroller.propTypes = {
 	getEstimatedVisibleItemRowsCount: PropTypes.func,
 	bypass: PropTypes.bool,
 	// bypassBatchSize: PropTypes.number,
-	tbody: PropTypes.bool,
+	// `tbody` property is deprecated.
+	// Pass `as: "tbody"` property instead.
+	// tbody: PropTypes.bool,
 	preserveScrollPositionOnPrependItems: PropTypes.bool,
 	// `preserveScrollPosition` property name is deprecated,
 	// use `preserveScrollPositionOnPrependItems` instead.

package/source/react/useState.js

@@ -9,8 +9,7 @@ import useLayoutEffectDontMountTwiceInStrictMode from './useLayoutEffectDontMoun
 // Creates state management functions.
 export default function _useState({
 	initialState,
-	onRender,
-	itemsProperty
+	onRender
 }) {
 	// This is a state variable that is used to re-render the component.
 	// Right after the component has finished re-rendering,

package/source/react/useVirtualScroller.js

@@ -11,7 +11,6 @@ export default function useVirtualScroller({
 	getEstimatedVisibleItemRowsCount,
 	bypass,
 	// bypassBatchSize,
-	tbody,
 	onItemInitialRender,
 	// `onItemFirstRender(i)` is deprecated, use `onItemInitialRender(item)` instead.
 	onItemFirstRender,
@@ -44,7 +43,6 @@ export default function useVirtualScroller({
 				getEstimatedVisibleItemRowsCount,
 				bypass,
 				// bypassBatchSize,
-				tbody,
 				onItemInitialRender,
 				// `onItemFirstRender(i)` is deprecated, use `onItemInitialRender(item)` instead.
 				onItemFirstRender,
@@ -57,7 +55,6 @@ export default function useVirtualScroller({
 				getScrollableContainer,
 				getColumnsCount,
 				getItemId,
-				tbody: AsComponent === 'tbody',
 				state: initialState,
 				getInitialItemState,
 				onStateChange