virtual-scroller 1.12.2 → 1.12.3

package/source/VirtualScroller.js

@@ -49,7 +49,11 @@ export default class VirtualScroller {
 			}
 		}
 
-		log('~ Start ~')
+		if (isRestart) {
+			log('~ Start (restart) ~')
+		} else {
+			log('~ Start ~')
+		}
 
 		// `this._isActive = true` should be placed somewhere at the start of this function.
 		this._isActive = true
@@ -71,18 +75,13 @@ export default class VirtualScroller {
 			}
 		}
 
-		// If there was a pending state update that didn't get applied
-		// because of stopping the `VirtualScroller`, apply that state update now.
-		//
-		// The pending state update won't get applied if the scrollable container width
-		// has changed but that's ok because that state update currently could only contain:
-		// * `scrollableContainerWidth`
-		// * `verticalSpacing`
-		// * `beforeResize`
-		// All of those get rewritten in `onResize()` anyway.
-		//
-		let stateUpdate = this._stoppedStateUpdate
-		this._stoppedStateUpdate = undefined
+		// If there was a pending "after render" state update that didn't get applied
+		// because the `VirtualScroller` got stopped, then apply that pending "after render"
+		// state update now. Such state update could include properties like:
+		// * A `verticalSpacing` that has been measured in `onRender()`.
+		// * A cleaned-up `beforeResize` object that was cleaned-up in `onRender()`.
+		let stateUpdate = this._afterRenderStateUpdateThatWasStopped
+		this._afterRenderStateUpdateThatWasStopped = undefined
 
 		// Reset `this.verticalSpacing` so that it re-measures it in cases when
 		// the `VirtualScroller` was previously stopped and is now being restarted.
@@ -122,12 +121,10 @@ export default class VirtualScroller {
 			const prevWidth = this.getState().scrollableContainerWidth
 			if (newWidth !== prevWidth) {
 				log('~ Scrollable container width changed from', prevWidth, 'to', newWidth, '~')
-				// `stateUpdate` doesn't get passed to `this.onResize()`, and, therefore,
-				// won't be applied. But that's ok because currently it could only contain:
-				// * `scrollableContainerWidth`
-				// * `verticalSpacing`
-				// * `beforeResize`
-				// All of those get rewritten in `onResize()` anyway.
+				// The pending state update (if present) won't be applied in this case.
+				// That's ok because such state update could currently only originate in
+				// `this.onResize()` function. Therefore, alling `this.onResize()` again
+				// would rewrite all those `stateUpdate` properties anyway, so they're not passed.
 				return this.onResize()
 			}
 		}
@@ -221,7 +218,9 @@ export default class VirtualScroller {
 	 * @param  {number} i — Item index
 	 */
 	onItemHeightDidChange(i) {
-		this.hasToBeStarted()
+		// See the comments in the `setItemState()` function below for the rationale
+		// on why the `hasToBeStarted()` check was commented out.
+		// this.hasToBeStarted()
 		this._onItemHeightDidChange(i)
 	}
 
@@ -231,7 +230,48 @@ export default class VirtualScroller {
 	 * @param  {any} i — Item's new state
 	 */
 	setItemState(i, newItemState) {
-		this.hasToBeStarted()
+		// 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`.
+		// https://gitlab.com/catamphetamine/virtual-scroller/-/issues/33
+		// https://github.com/facebook/react/issues/26320
+		// A workaround for that bug is ignoring the second-initial run of the effects at mount.
+		//
+		// But in that case, if an `ItemComponent` calls `setItemState()` in `useLayoutEffect()`,
+		// it could result in a bug.
+		//
+		// Consider a type of `useLayoutEffect()` that skips the initial mount:
+		// `useLayoutEffectSkipInitialMount()`.
+		// Suppose that effect is written in such a way that it only skips the first call of itself.
+		// In that case, if React is run in "strict" mode, the effect will no longer work as expected
+		// and it won't actually skip the initial mount and will be executed during the second initial run.
+		// But the `VirtualScroller` itself has already implemented a workaround that prevents
+		// its hooks from running twice on mount. This means that `useVirtualScrollerStartStop()`
+		// of the React component would have already stopped the `VirtualScroller` by the time
+		// `ItemComponent`'s incorrectly-behaving `useLayoutEffectSkipInitialMount()` effect is run,
+		// resulting in an error: "`VirtualScroller` hasn't been started".
+		//
+		// The log when not in "strict" mode would be:
+		//
+		// * `useLayoutEffect()` is run in `ItemComponent` — skips the initial run.
+		// * `useLayoutEffect()` is run in `useVirtualScrollerStartStop()`. It starts the `VirtualScroller`.
+		// * Some dependency property gets updated inside `ItemComponent`.
+		// * `useLayoutEffect()` is run in `ItemComponent` — no longer skips. Calls `setItemState()`.
+		// * The `VirtualScroller` is started so it handles `setState()` correctly.
+		//
+		// The log when in "strict" mode would be:
+		//
+		// * `useLayoutEffect()` is run in `ItemComponent` — skips the initial run.
+		// * `useLayoutEffect()` is run in `useVirtualScrollerStartStop()`. It starts the `VirtualScroller`.
+		// * `useLayoutEffect()` is unmounted in `useVirtualScrollerStartStop()`. It stops the `VirtualScroller`.
+		// * `useLayoutEffect()` is unmounted in `ItemComponent` — does nothing.
+		// * `useLayoutEffect()` is run the second time in `ItemComponent` — no longer skips. Calls `setItemState()`.
+		// * The `VirtualScroller` is stopped so it throws an error: "`VirtualScroller` hasn't been started".
+		//
+		// For that reason, the requirement of the `VirtualScroller` to be started was commented out.
+		// 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)
 	}
 

package/source/VirtualScroller.layout.js

@@ -441,9 +441,13 @@ export default function() {
 		if (previousHeight !== newHeight) {
 			log('~ Item height has changed. Should update layout. ~')
 
-			// Update or reset a previously calculated layout
-			// so that the "diff"s based on that layout in the future
-			// produce correct results.
+			// Update or reset a previously calculated layout with the new item height
+			// so that the potential future "diff"s based on that "previously calculated" layout
+			// would be correct.
+			//
+			// The "previously calculated layout" feature is not currently used
+			// so this function call doesn't really affect anything.
+			//
 			updatePreviouslyCalculatedLayoutOnItemHeightChange.call(this, i, previousHeight, newHeight)
 
 			// Recalculate layout.
@@ -455,11 +459,13 @@ export default function() {
 			// that might happen in the middle of the currently pending `setState()` operation
 			// being applied, resulting in weird "race condition" bugs.
 			//
-			if (this.waitingForRender) {
-				log('~ Another state update is already waiting to be rendered. Delay the layout update until then. ~')
-				this.updateLayoutAfterRenderBecauseItemHeightChanged = true
-			} else {
-				this.onUpdateShownItemIndexes({ reason: LAYOUT_REASON.ITEM_HEIGHT_CHANGED })
+			if (this._isActive) {
+				if (this.waitingForRender) {
+					log('~ Another state update is already waiting to be rendered. Delay the layout update until then. ~')
+					this.updateLayoutAfterRenderBecauseItemHeightChanged = true
+				} else {
+					this.onUpdateShownItemIndexes({ reason: LAYOUT_REASON.ITEM_HEIGHT_CHANGED })
+				}
 			}
 
 			// If there was a request for `setState()` with new `items`, then the changes

package/source/VirtualScroller.onRender.js

@@ -63,7 +63,7 @@ export default function() {
 			// would construct its own state object.
 			if (!shallowEqual(newState, this.mostRecentSetStateValue)) {
 				warn('The most recent state that was set', getStateSnapshot(this.mostRecentSetStateValue))
-				reportError('The state that has been rendered is not the most recent one that was set')
+				reportError('`VirtualScroller` has been rendered with a `state` that is not equal to the most recently set one')
 			}
 		}
 
@@ -199,7 +199,7 @@ export default function() {
 		}
 
 		if (!this._isActive) {
-			this._stoppedStateUpdate = stateUpdate
+			this._afterRenderStateUpdateThatWasStopped = stateUpdate
 			return
 		}
 

package/source/react/VirtualScroller.js

@@ -13,6 +13,8 @@ import useUpdateItemKeysOnItemsChange from './useUpdateItemKeysOnItemsChange.js'
 import useClassName from './useClassName.js'
 import useStyle from './useStyle.js'
 
+import { warn } from '../utility/debug.js'
+
 // When `items` property changes:
 // * A new `items` property is supplied to the React component.
 // * The React component re-renders itself.
@@ -172,6 +174,7 @@ function VirtualScroller({
 		// `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) {
+			warn('`onMount` property is deprecated')
 			onMount()
 		}
 	}, [])

package/source/react/useEffectDontMountTwiceInStrictMode.js

@@ -0,0 +1,68 @@
+import { useRef, useCallback } from 'react'
+
+// A workaround for a React bug when `useInsertionEffect()` doesn't run twice on mount
+// in "strict" mode unlike `useEffect()` and `useLayoutEffect()` do.
+// https://github.com/facebook/react/issues/26320
+export default function useEffectDontMountTwiceInStrictMode(useEffect, handler, dependencies) {
+  if (!Array.isArray(dependencies)) {
+    throw new Error('Dependencies argument must be an array')
+  }
+
+  const { onEffect } = useEffectStatus()
+  const { onChange } = usePrevousValue(dependencies)
+
+  useEffect(() => {
+    const { isInitialRun } = onEffect()
+    const previousDependencies = onChange(dependencies)
+    if (isInitialRun || !isShallowEqualArrays(previousDependencies, dependencies)) {
+      const cleanUpFunction = handler()
+      if (typeof cleanUpFunction === 'function') {
+        throw new Error('An effect can\'t return a clean-up function when used with `useEffectDontMountTwiceInStrictMode()` because the clean-up function won\'t behave correctly in that case')
+      }
+    }
+  }, dependencies)
+}
+
+function useEffectStatus() {
+  const hasMounted = useRef(false)
+
+  const onEffect = useCallback(() => {
+    const wasAlreadyMounted = hasMounted.current
+    hasMounted.current = true
+    return {
+      isInitialRun: !wasAlreadyMounted
+    }
+  }, [])
+
+  return {
+    onEffect
+  }
+}
+
+function usePrevousValue(value) {
+  const prevValue = useRef(value)
+
+  const onChange = useCallback((value) => {
+    const previousValue = prevValue.current
+    prevValue.current = value
+    return previousValue
+  }, [])
+
+  return {
+    onChange
+  }
+}
+
+function isShallowEqualArrays(a, b) {
+  if (a.length !== b.length) {
+    return false
+  }
+  let i = 0
+  while (i < a.length) {
+    if (a[i] !== b[i]) {
+      return false
+    }
+    i++
+  }
+  return true
+}

package/source/react/useInsertionEffectDontMountTwiceInStrictMode.js

@@ -0,0 +1,10 @@
+import { useInsertionEffect } from 'react'
+
+import useEffectDontMountTwiceInStrictMode from './useEffectDontMountTwiceInStrictMode.js'
+
+// A workaround for a React bug when `useInsertionEffect()` doesn't run twice on mount
+// in "strict" mode unlike `useEffect()` and `useLayoutEffect()` do.
+// https://github.com/facebook/react/issues/26320
+export default function useInsertionEffectDontMountTwiceInStrictMode(handler, dependencies) {
+  return useEffectDontMountTwiceInStrictMode(useInsertionEffect, handler, dependencies)
+}

package/source/react/useLayoutEffectDontMountTwiceInStrictMode.js

@@ -0,0 +1,10 @@
+import { useLayoutEffect } from 'react'
+
+import useEffectDontMountTwiceInStrictMode from './useEffectDontMountTwiceInStrictMode.js'
+
+// A workaround for a React bug when `useInsertionEffect()` doesn't run twice on mount
+// in "strict" mode unlike `useEffect()` and `useLayoutEffect()` do.
+// https://github.com/facebook/react/issues/26320
+export default function useLayoutEffectDontMountTwiceInStrictMode(handler, dependencies) {
+  return useEffectDontMountTwiceInStrictMode(useLayoutEffect, handler, dependencies)
+}

package/source/react/useState.js

@@ -1,7 +1,10 @@
 import log, { isDebug } from '../utility/debug.js'
 import getStateSnapshot from '../utility/getStateSnapshot.js'
 
-import { useState, useRef, useCallback, useLayoutEffect, useInsertionEffect } from 'react'
+import { useRef, useCallback } from 'react'
+import useStateNoStaleBug from './useStateNoStaleBug.js'
+import useInsertionEffectDontMountTwiceInStrictMode from './useInsertionEffectDontMountTwiceInStrictMode.js'
+import useLayoutEffectDontMountTwiceInStrictMode from './useLayoutEffectDontMountTwiceInStrictMode.js'
 
 // Creates state management functions.
 export default function _useState({
@@ -14,7 +17,7 @@ export default function _useState({
 	// `VirtualScroller` state gets updated from this variable.
 	// The reason for that is that `VirtualScroller` state must always
 	// correspond exactly to what's currently rendered on the screen.
-	const [_newState, _setNewState] = useState(initialState)
+	const [_newState, _setNewState] = useStateNoStaleBug(initialState)
 
 	// This `state` reference is what `VirtualScroller` uses internally.
 	// It's the "source of truth" on the actual `VirtualScroller` state.
@@ -137,7 +140,7 @@ export default function _useState({
 	// So if `useInsertionEffect()` gets removed from React in some hypothetical future,
 	// it could be replaced with using `ref`s on `ItemComponent`s to measure the DOM element heights.
 	//
-	useInsertionEffect(() => {
+	useInsertionEffectDontMountTwiceInStrictMode(() => {
 		// Update the actual `VirtualScroller` state right before the DOM changes
 		// are going to be applied for the requested state update.
 		//
@@ -160,13 +163,13 @@ export default function _useState({
 		// This hook doesn't do anything at the initial render.
 		//
 		if (isDebug()) {
-			log('React: ~ The requested state is about to be applied in DOM. Set it as the `VirtualScroller` state. ~')
+			log('React: ~ The requested state is about to be applied in DOM. Setting it as the `VirtualScroller` state. ~')
 			log(getStateSnapshot(_newState))
 		}
 		setState(_newState)
 	}, [_newState])
 
-	useLayoutEffect(() => {
+	useLayoutEffectDontMountTwiceInStrictMode(() => {
 		// Call `onRender()` right after a requested state update has been applied,
 		// and also right after the initial render.
 		onRender()

package/source/react/useStateNoStaleBug.js

@@ -0,0 +1,35 @@
+import { useRef, useState, useCallback } from 'react'
+
+// This hook fixes any weird intermediate inconsistent/invalid/stale state values.
+// https://github.com/facebook/react/issues/25023#issuecomment-1480463544
+export default function useStateNoStaleBug(initialState) {
+  // const latestValidState = useRef(initialState)
+  const latestWrittenState = useRef(initialState)
+  const [_state, _setState] = useState(initialState)
+
+  // Instead of dealing with a potentially out-of-sync (stale) state value,
+  // simply use the correct latest one.
+  const state = latestWrittenState.current
+
+  /*
+  let state
+  if (_state === latestWrittenState.current) {
+    state = _state
+    latestValidState.current = _state
+  } else {
+    // React bug detected: an out-of-sync (stale) state value received.
+    // Ignore the out-of-sync (stale) state value.
+    state = latestValidState.current
+  }
+  */
+
+  const setState = useCallback((newState) => {
+    if (typeof newState === 'function') {
+      throw new Error('Function argument of `setState()` function is not supported by this hook')
+    }
+    latestWrittenState.current = newState
+    _setState(newState)
+  }, [])
+
+  return [state, setState]
+}