virtual-scroller 1.8.0 → 1.9.1

package/source/VirtualScroller.onRender.js

@@ -0,0 +1,345 @@
+import log, { warn, isDebug } from './utility/debug.js'
+import getStateSnapshot from './utility/getStateSnapshot.js'
+import shallowEqual from './utility/shallowEqual.js'
+import { LAYOUT_REASON } from './Layout.js'
+import { setTbodyPadding } from './DOM/tbody.js'
+
+export default function() {
+	/**
+	 * Should be called right after updates to `state` have been rendered.
+	 * @param  {object} newState
+	 * @param  {object} [prevState]
+	 */
+	this._onRender = (newState, prevState) => {
+		log('~ Rendered ~')
+		if (isDebug()) {
+			log('State', getStateSnapshot(newState))
+		}
+
+		if (this.onStateChange) {
+			if (!shallowEqual(newState, prevState)) {
+				this.onStateChange(newState)
+			}
+		}
+
+		// 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) {
+			setTbodyPadding(
+				this.getItemsContainerElement(),
+				newState.beforeItemsHeight,
+				newState.afterItemsHeight
+			)
+		}
+
+		if (!prevState) {
+			return
+		}
+
+		// `this.resetStateUpdateFlags()` must be called before calling
+		// `this.measureItemHeightsAndSpacing()`.
+		const {
+			nonMeasuredItemsHaveBeenRendered,
+			widthHasChanged
+		} = resetStateUpdateFlags.call(this)
+
+		let layoutUpdateReason
+
+		// If the `VirtualScroller`, while calculating layout parameters, encounters
+		// a not-shown item with a non-measured height, it calls `updateState()` just to
+		// render that item first, and then, after the list has been re-rendered, it measures
+		// the item's height and then proceeds with calculating the correct layout parameters.
+		if (nonMeasuredItemsHaveBeenRendered) {
+			layoutUpdateReason = LAYOUT_REASON.NON_MEASURED_ITEMS_HAVE_BEEN_MEASURED
+		}
+
+		// If scrollable container width has changed, and it has been re-rendered,
+		// then it's time to measure the new item heights and then perform a re-layout
+		// with the correctly calculated layout parameters.
+		//
+		// A re-layout is required because the layout parameters calculated on resize
+		// are approximate ones, and the exact item heights aren't known at that point.
+		// So on resize, it calls `updateState()` just to re-render the `VirtualScroller`.
+		// After it has been re-rendered, it will measure item heights and then calculate
+		// correct layout parameters.
+		//
+		if (widthHasChanged) {
+			layoutUpdateReason = LAYOUT_REASON.VIEWPORT_WIDTH_CHANGED
+
+			// Reset measured item heights on viewport width change.
+			this.itemHeights.reset()
+
+			// Reset `verticalSpacing` (will be re-measured).
+			this.verticalSpacing = undefined
+		}
+
+		const { items: previousItems } = prevState
+		const { items: newItems } = newState
+		// Even if `this.newItemsWillBeRendered` flag is `true`,
+		// `newItems` could still be equal to `previousItems`.
+		// For example, when `updateState()` calls don't update `state` immediately
+		// and a developer first calls `setItems(newItems)` and then calls `setItems(oldItems)`:
+		// in that case, `this.newItemsWillBeRendered` flag will be `true` but the actual `items`
+		// in state wouldn't have changed due to the first `updateState()` call being overwritten
+		// by the second `updateState()` call (that's called "batching state updates" in React).
+		if (newItems !== previousItems) {
+			const itemsDiff = this.getItemsDiff(previousItems, newItems)
+			if (itemsDiff) {
+				// The call to `.onPrepend()` must precede the call to `.measureItemHeights()`
+				// which is called in `.onRender()`.
+				// `this.itemHeights.onPrepend()` updates `firstMeasuredItemIndex`
+				// and `lastMeasuredItemIndex` of `this.itemHeights`.
+				const { prependedItemsCount } = itemsDiff
+				this.itemHeights.onPrepend(prependedItemsCount)
+			} else {
+				this.itemHeights.reset()
+			}
+
+			if (!widthHasChanged) {
+				// The call to `this.onNewItemsRendered()` must precede the call to
+				// `.measureItemHeights()` which is called in `.onRender()` because
+				// `this.onNewItemsRendered()` updates `firstMeasuredItemIndex` and
+				// `lastMeasuredItemIndex` of `this.itemHeights` in case of a prepend.
+				//
+				// If after prepending items the scroll position
+				// should be "restored" so that there's no "jump" of content
+				// then it means that all previous items have just been rendered
+				// in a single pass, and there's no need to update layout again.
+				//
+				if (onNewItemsRendered.call(this, itemsDiff, newState) !== 'SEAMLESS_PREPEND') {
+					layoutUpdateReason = LAYOUT_REASON.ITEMS_CHANGED
+				}
+			}
+		}
+
+		let stateUpdate
+
+		// Re-measure item heights.
+		// Also, measure vertical spacing (if not measured) and fix `<table/>` padding.
+		//
+		// This block should go after `if (newItems !== previousItems) {}`
+		// because `this.itemHeights` can get `.reset()` there, which would
+		// discard all the measurements done here, and having currently shown
+		// item height measurements is required.
+		//
+		if (
+			newState.firstShownItemIndex !== prevState.firstShownItemIndex ||
+			newState.lastShownItemIndex !== prevState.lastShownItemIndex ||
+			newState.items !== prevState.items ||
+			widthHasChanged
+		) {
+			const verticalSpacingStateUpdate = this.measureItemHeightsAndSpacing()
+			if (verticalSpacingStateUpdate) {
+				stateUpdate = {
+					...stateUpdate,
+					...verticalSpacingStateUpdate
+				}
+			}
+		}
+
+		// Clean up "before resize" item heights and adjust the scroll position accordingly.
+		// Calling `this.beforeResize.cleanUpBeforeResizeItemHeights()` might trigger
+		// a `this.updateState()` call but that wouldn't matter because `beforeResize`
+		// properties have already been modified directly in `state` (a hacky technique)
+		const cleanedUpBeforeResize = this.beforeResize.cleanUpBeforeResizeItemHeights()
+		if (cleanedUpBeforeResize !== undefined) {
+			const { scrollBy, beforeResize } = cleanedUpBeforeResize
+			log('Correct scroll position by', scrollBy)
+			this.scroll.scrollByY(scrollBy)
+			stateUpdate = {
+				...stateUpdate,
+				beforeResize
+			}
+		}
+
+		if (!this._isActive) {
+			this._stoppedStateUpdate = stateUpdate
+			return
+		}
+
+		if (layoutUpdateReason) {
+			updateStateRightAfterRender.call(this, {
+				stateUpdate,
+				reason: layoutUpdateReason
+			})
+		} else if (stateUpdate) {
+			this.updateState(stateUpdate)
+		} else {
+			log('~ Finished Layout ~')
+		}
+	}
+
+	// After a new set of items has been rendered:
+	//
+	// * Restores scroll position when using `preserveScrollPositionOnPrependItems`
+	//   and items have been prepended.
+	//
+	// * Applies any "pending" `itemHeights` updates — those ones that happened
+	//   while an asynchronous `updateState()` call in `setItems()` was pending.
+	//
+	// * Either creates or resets the snapshot of the current layout.
+	//
+	//   The current layout snapshot could be stored as a "previously calculated layout" variable
+	//   so that it could theoretically be used when calculating new layout incrementally
+	//   rather than from scratch, which would be an optimization.
+	//
+	//   The "previously calculated layout" feature is not currently used.
+	//
+	function onNewItemsRendered(itemsDiff, newLayout) {
+		// If it's an "incremental" update.
+		if (itemsDiff) {
+			const {
+				prependedItemsCount,
+				appendedItemsCount
+			} = itemsDiff
+
+			const {
+				itemHeights,
+				itemStates
+			} = this.getState()
+
+			// See if any items' heights changed while new items were being rendered.
+			if (this.itemHeightsThatChangedWhileNewItemsWereBeingRendered) {
+				for (const i of Object.keys(this.itemHeightsThatChangedWhileNewItemsWereBeingRendered)) {
+					itemHeights[prependedItemsCount + parseInt(i)] = this.itemHeightsThatChangedWhileNewItemsWereBeingRendered[i]
+				}
+			}
+
+			// See if any items' states changed while new items were being rendered.
+			if (this.itemStatesThatChangedWhileNewItemsWereBeingRendered) {
+				for (const i of Object.keys(this.itemStatesThatChangedWhileNewItemsWereBeingRendered)) {
+					itemStates[prependedItemsCount + parseInt(i)] = this.itemStatesThatChangedWhileNewItemsWereBeingRendered[i]
+				}
+			}
+
+			if (prependedItemsCount === 0) {
+				// Adjust `this.previouslyCalculatedLayout`.
+				if (this.previouslyCalculatedLayout) {
+					if (
+						this.previouslyCalculatedLayout.firstShownItemIndex === newLayout.firstShownItemIndex &&
+						this.previouslyCalculatedLayout.lastShownItemIndex === newLayout.lastShownItemIndex
+					) {
+						// `this.previouslyCalculatedLayout` stays the same.
+						// `firstShownItemIndex` / `lastShownItemIndex` didn't get changed in `setItems()`,
+						// so `beforeItemsHeight` and `shownItemsHeight` also stayed the same.
+					} else {
+						warn('Unexpected (non-matching) "firstShownItemIndex" or "lastShownItemIndex" encountered in "onRender()" after appending items')
+						warn('Previously calculated layout', this.previouslyCalculatedLayout)
+						warn('New layout', newLayout)
+						this.previouslyCalculatedLayout = undefined
+					}
+				}
+				return 'SEAMLESS_APPEND'
+			} else {
+				if (this.listHeightMeasurement.hasSnapshot()) {
+					if (newLayout.firstShownItemIndex === 0) {
+						// Restore (adjust) scroll position.
+						log('~ Restore Scroll Position ~')
+						const listBottomOffsetChange = this.listHeightMeasurement.getListBottomOffsetChange({
+							beforeItemsHeight: newLayout.beforeItemsHeight
+						})
+						this.listHeightMeasurement.reset()
+						if (listBottomOffsetChange) {
+							log('Scroll down by', listBottomOffsetChange)
+							this.scroll.scrollByY(listBottomOffsetChange)
+						} else {
+							log('Scroll position hasn\'t changed')
+						}
+						// Create new `this.previouslyCalculatedLayout`.
+						if (this.previouslyCalculatedLayout) {
+							if (
+								this.previouslyCalculatedLayout.firstShownItemIndex === 0 &&
+								this.previouslyCalculatedLayout.lastShownItemIndex === newLayout.lastShownItemIndex - prependedItemsCount
+							) {
+								this.previouslyCalculatedLayout = {
+									beforeItemsHeight: 0,
+									shownItemsHeight: this.previouslyCalculatedLayout.shownItemsHeight + listBottomOffsetChange,
+									firstShownItemIndex: 0,
+									lastShownItemIndex: newLayout.lastShownItemIndex
+								}
+							} else {
+								warn('Unexpected (non-matching) "firstShownItemIndex" or "lastShownItemIndex" encountered in "onRender()" after prepending items')
+								warn('Previously calculated layout', this.previouslyCalculatedLayout)
+								warn('New layout', newLayout)
+								this.previouslyCalculatedLayout = undefined
+							}
+						}
+						return 'SEAMLESS_PREPEND'
+					} else {
+						warn(`Unexpected "firstShownItemIndex" ${newLayout.firstShownItemIndex} encountered in "onRender()" after prepending items. Expected 0.`)
+					}
+				}
+			}
+		}
+
+		// Reset `this.previouslyCalculatedLayout` in any case other than
+		// SEAMLESS_PREPEND or SEAMLESS_APPEND.
+		this.previouslyCalculatedLayout = undefined
+	}
+
+	function updateStateRightAfterRender({
+		reason,
+		stateUpdate
+	}) {
+		// In React, `setTimeout()` is used to prevent a React error:
+		// "Maximum update depth exceeded.
+		//  This can happen when a component repeatedly calls
+		//  `.updateState()` inside `componentWillUpdate()` or `componentDidUpdate()`.
+		//  React limits the number of nested updates to prevent infinite loops."
+		if (this._useTimeoutInRenderLoop) {
+			// Cancel a previously scheduled re-layout.
+			stateUpdate = this.cancelLayoutTimer({ stateUpdate })
+			// Schedule a new re-layout.
+			this.scheduleLayoutTimer({
+				reason,
+				stateUpdate
+			})
+		} else {
+			this.onUpdateShownItemIndexes({
+				reason,
+				stateUpdate
+			})
+		}
+	}
+
+	function resetStateUpdateFlags() {
+		// Read and reset `this.widthHasChanged` flag.
+		//
+		// If `this.widthHasChanged` flag was reset after calling
+		// `this.measureWidthHeightsAndSpacingAndUpdateTablePadding()`
+		// then there would be a bug because
+		// `this.measureWidthHeightsAndSpacingAndUpdateTablePadding()`
+		// calls `this.updateState({ verticalSpacing })` which calls
+		// `this.onRender()` immediately, so `this.widthHasChanged`
+		// flag wouldn't be reset by that time and would trigger things
+		// like `this.itemHeights.reset()` a second time.
+		//
+		// So, instead read the value of `this.widthHasChanged` flag
+		// and reset it right away to prevent any such potential bugs.
+		//
+		const widthHasChanged = Boolean(this.widthHasChanged)
+		//
+		// Reset `this.widthHasChanged` flag.
+		this.widthHasChanged = undefined
+
+		// Read `this.firstNonMeasuredItemIndex` flag.
+		const nonMeasuredItemsHaveBeenRendered = this.firstNonMeasuredItemIndex !== undefined
+		// Reset `this.firstNonMeasuredItemIndex` flag.
+		this.firstNonMeasuredItemIndex = undefined
+
+		// Reset `this.newItemsWillBeRendered` flag.
+		this.newItemsWillBeRendered = undefined
+
+		// Reset `this.itemHeightsThatChangedWhileNewItemsWereBeingRendered`.
+		this.itemHeightsThatChangedWhileNewItemsWereBeingRendered = undefined
+
+		// Reset `this.itemStatesThatChangedWhileNewItemsWereBeingRendered`.
+		this.itemStatesThatChangedWhileNewItemsWereBeingRendered = undefined
+
+		return {
+			nonMeasuredItemsHaveBeenRendered,
+			widthHasChanged
+		}
+	}
+}

package/source/VirtualScroller.resize.js

@@ -0,0 +1,189 @@
+import log from './utility/debug.js'
+
+export default function() {
+	this.onResize = () => {
+		// Reset "previously calculated layout".
+		//
+		// The "previously calculated layout" feature is not currently used.
+		//
+		// The current layout snapshot could be stored as a "previously calculated layout" variable
+		// so that it could theoretically be used when calculating new layout incrementally
+		// rather than from scratch, which would be an optimization.
+		//
+		this.previouslyCalculatedLayout = undefined
+
+		// Cancel any potential scheduled scroll position restoration.
+		this.listHeightMeasurement.reset()
+
+		// Get the most recent items count.
+		// If there're a "pending" `setItems()` call then use the items count from that call
+		// instead of using the count of currently shown `items` from `state`.
+		// A `setItems()` call is "pending" when `updateState()` operation is "asynchronous", that is
+		// when `updateState()` calls aren't applied immediately, like in React.
+		const itemsCount = this.newItemsWillBeRendered
+			? this.newItemsWillBeRendered.count
+			: this.getState().itemHeights.length
+
+		// If layout values have been calculated as a result of a "pending" `setItems()` call,
+		// then don't discard those new layout values and use them instead of the ones from `state`.
+		//
+		// A `setItems()` call is "pending" when `updateState()` operation is "asynchronous", that is
+		// when `updateState()` calls aren't applied immediately, like in React.
+		//
+		const layout = this.newItemsWillBeRendered
+			? this.newItemsWillBeRendered.layout
+			: this.getState()
+
+		// Update `VirtualScroller` state.
+		const newState = {
+			scrollableContainerWidth: this.scrollableContainer.getWidth(),
+
+			// This state update should also overwrite all the `state` properties
+			// that are also updated in the "on scroll" handler (`getShownItemIndexes()`):
+			//
+			// * `firstShownItemIndex`
+			// * `lastShownItemIndex`
+			// * `beforeItemsHeight`
+			// * `afterItemsHeight`
+			//
+			// That's because this `updateState()` update has a higher priority
+			// than that of the "on scroll" handler, so it should overwrite
+			// any potential state changes dispatched by the "on scroll" handler.
+			//
+			// All these properties might have changed, but they're not
+			// recalculated here becase they'll be recalculated after
+			// this new state is applied (rendered).
+			//
+			firstShownItemIndex: layout.firstShownItemIndex,
+			lastShownItemIndex: layout.lastShownItemIndex,
+			beforeItemsHeight: layout.beforeItemsHeight,
+			afterItemsHeight: layout.afterItemsHeight,
+
+			// Reset item heights, because if scrollable container's width (or height)
+			// has changed, then the list width (or height) most likely also has changed,
+			// and also some CSS `@media()` rules might have been added or removed.
+			// So re-render the list entirely.
+			itemHeights: new Array(itemsCount),
+
+			columnsCount: this.getActualColumnsCountForState(),
+
+			// Re-measure vertical spacing after render because new CSS styles
+			// might be applied for the new window width.
+			verticalSpacing: undefined
+		}
+
+		const { firstShownItemIndex, lastShownItemIndex } = layout
+
+		// Get the `columnsCount` for the new window width.
+		const newColumnsCount = this.getActualColumnsCount()
+
+		// Re-calculate `firstShownItemIndex` and `lastShownItemIndex`
+		// based on the new `columnsCount` so that the whole row is visible.
+		const newFirstShownItemIndex = Math.floor(firstShownItemIndex / newColumnsCount) * newColumnsCount
+		const newLastShownItemIndex = Math.min(
+			Math.ceil((lastShownItemIndex + 1) / newColumnsCount) * newColumnsCount,
+			itemsCount
+		) - 1
+
+		// Potentially update `firstShownItemIndex` if it needs to be adjusted in order to
+		// correspond to the new `columnsCount`.
+		if (newFirstShownItemIndex !== firstShownItemIndex) {
+			log('Columns Count changed from', this.getState().columnsCount || 1, 'to', newColumnsCount)
+			log('First Shown Item Index needs to change from', firstShownItemIndex, 'to', newFirstShownItemIndex)
+		}
+
+		// Always rewrite `firstShownItemIndex` and `lastShownItemIndex`
+		// as part of the `state` update, even if it hasn't been modified.
+		//
+		// The reason is that there could be two subsequent `onResize()` calls:
+		// the first one could be user resizing the window to half of its width,
+		// resulting in an "asynchronous" `updateState()` call, and then, before that
+		// `updateState()` call is applied, a second resize event happens when the user
+		// has resized the window back to its original width, meaning that the
+		// `columnsCount` is back to its original value.
+		// In that case, the final `newFirstShownItemIndex` will be equal to the
+		// original `firstShownItemIndex` that was in `state` before the user
+		// has started resizing the window, so, in the end, `state.firstShownItemIndex`
+		// property wouldn't have changed, but it still has to be part of the final
+		// state update in order to overwrite the previous update of `firstShownItemIndex`
+		// property that has been scheduled to be applied in state after the first resize
+		// happened.
+		//
+		newState.firstShownItemIndex = newFirstShownItemIndex
+		newState.lastShownItemIndex = newLastShownItemIndex
+
+		const verticalSpacing = this.getVerticalSpacing()
+		const columnsCount = this.getColumnsCount()
+
+		// `beforeResize` is always overwritten in `state` here.
+		// (once it has started being tracked in `state`)
+		if (this.shouldDiscardBeforeResizeItemHeights() || newFirstShownItemIndex === 0) {
+			if (this.beforeResize.shouldIncludeBeforeResizeValuesInState()) {
+				newState.beforeResize = undefined
+			}
+		}
+		// Snapshot "before resize" values in order to preserve the currently
+		// shown items' vertical position on screen so that there's no "content jumping".
+		else {
+			// Keep "before resize" values in order to preserve the currently
+			// shown items' vertical position on screen so that there's no
+			// "content jumping". These "before resize" values will be discarded
+			// when (if) the user scrolls back to the top of the list.
+			newState.beforeResize = {
+				verticalSpacing,
+				columnsCount,
+				itemHeights: this.beforeResize.snapshotBeforeResizeItemHeights({
+					firstShownItemIndex,
+					newFirstShownItemIndex,
+					newColumnsCount
+				})
+			}
+		}
+
+		// `this.widthHasChanged` tells `VirtualScroller` that it should
+		// temporarily stop other updates (like "on scroll" updates) and wait
+		// for the new `state` to be applied, after which the `onRender()`
+		// function will clear this flag and perform a re-layout.
+		//
+		// A re-layout is required because the layout parameters calculated above
+		// are approximate ones, and the exact item heights aren't known at this point.
+		// So the `updateState()` call below is just to re-render the `VirtualScroller`.
+		// After it has been re-rendered, it will measure item heights and then calculate
+		// correct layout parameters.
+		//
+		this.widthHasChanged = {
+			stateUpdate: newState
+		}
+
+		// Rerender.
+		this.updateState(newState)
+	}
+
+	// Returns whether "before resize" item heights should be discarded
+	// as a result of calling `setItems()` with a new set of items
+	// when an asynchronous `updateState()` call inside that function
+	// hasn't been applied yet.
+	//
+	// If `setItems()` update was an "incremental" one and no items
+	// have been prepended, then `firstShownItemIndex` is preserved,
+	// and all items' heights before it should be kept in order to
+	// preserve the top offset of the first shown item so that there's
+	// no "content jumping".
+	//
+	// If `setItems()` update was an "incremental" one but there're
+	// some prepended items, then it means that now there're new items
+	// with unknown heights at the top, so the top offset of the first
+	// shown item won't be preserved because there're no "before resize"
+	// heights of those items.
+	//
+	// If `setItems()` update was not an "incremental" one, then don't
+	// attempt to restore previous item heights after a potential window
+	// width change because all item heights have been reset.
+	//
+	this.shouldDiscardBeforeResizeItemHeights = () => {
+		if (this.newItemsWillBeRendered) {
+			const { prepend, replace } = this.newItemsWillBeRendered
+			return prepend || replace
+		}
+	}
+}