virtual-scroller 1.7.9 → 1.9.0

package/source/Layout.test.js

@@ -0,0 +1,176 @@
+import Layout from './Layout.js'
+
+import Engine from './test/Engine.js'
+
+describe('Layout', function() {
+	it('should work', function() {
+		const SCREEN_HEIGHT = 400
+
+		const scrollableContainer = {
+			width: 800,
+			height: SCREEN_HEIGHT
+		}
+
+		const ITEM_WIDTH = scrollableContainer.width
+		const ITEM_HEIGHT = 200
+
+		const VERTICAL_SPACING = 100
+
+		const items = new Array(9).fill(ITEM_WIDTH * ITEM_HEIGHT)
+
+		const layout = new Layout({
+			getPrerenderMargin: () => SCREEN_HEIGHT,
+			getVerticalSpacing: () => VERTICAL_SPACING,
+			getColumnsCount: () => 1,
+			getItemHeight: (i) => items[i] / scrollableContainer.width,
+			getBeforeResizeItemsCount: () => 0,
+			getAverageItemHeight: () => ITEM_HEIGHT,
+			getScrollableContainerHeight: () => scrollableContainer.height
+		})
+
+		// Initial render.
+		layout.getShownItemIndexes({
+			itemsCount: items.length,
+			visibleAreaTop: 0,
+			visibleAreaBottom: SCREEN_HEIGHT
+		}).should.deep.equal({
+			firstShownItemIndex: 0,
+			lastShownItemIndex: 2
+		})
+
+		// The first item is almost hidden.
+		layout.getShownItemIndexes({
+			itemsCount: items.length,
+			visibleAreaTop: SCREEN_HEIGHT + ITEM_HEIGHT - 1,
+			visibleAreaBottom: (SCREEN_HEIGHT + ITEM_HEIGHT - 1) + SCREEN_HEIGHT
+		}).should.deep.equal({
+			firstShownItemIndex: 0,
+			lastShownItemIndex: 4
+		})
+
+		// The first item is hidden.
+		layout.getShownItemIndexes({
+			itemsCount: items.length,
+			visibleAreaTop: SCREEN_HEIGHT + ITEM_HEIGHT,
+			visibleAreaBottom: (SCREEN_HEIGHT + ITEM_HEIGHT) + SCREEN_HEIGHT
+		}).should.deep.equal({
+			firstShownItemIndex: 1,
+			lastShownItemIndex: 4
+		})
+
+		// A new item at the bottom is almost visible.
+		layout.getShownItemIndexes({
+			itemsCount: items.length,
+			visibleAreaTop: (ITEM_HEIGHT + VERTICAL_SPACING) * 5 - SCREEN_HEIGHT * 2,
+			visibleAreaBottom: (ITEM_HEIGHT + VERTICAL_SPACING) * 5 - SCREEN_HEIGHT
+		}).should.deep.equal({
+			firstShownItemIndex: 1,
+			lastShownItemIndex: 4
+		})
+
+		// A new item at the bottom is visible.
+		layout.getShownItemIndexes({
+			itemsCount: items.length,
+			visibleAreaTop: (ITEM_HEIGHT + VERTICAL_SPACING) * 5 + 1 - SCREEN_HEIGHT * 2,
+			visibleAreaBottom: (ITEM_HEIGHT + VERTICAL_SPACING) * 5 + 1 - SCREEN_HEIGHT
+		}).should.deep.equal({
+			firstShownItemIndex: 1,
+			lastShownItemIndex: 5
+		})
+	})
+
+	it('should update layout for items incremental change', function() {
+		const scrollableContainer = {
+			width: 800,
+			height: 400
+		}
+
+		const ITEM_WIDTH = scrollableContainer.width
+		const ITEM_HEIGHT = 200
+
+		const items = new Array(9).fill(ITEM_WIDTH * ITEM_HEIGHT)
+
+		const VERTICAL_SPACING = 100
+
+		const layout = new Layout({
+			getPrerenderMargin: () => scrollableContainer.height,
+			getVerticalSpacing: () => VERTICAL_SPACING,
+			getColumnsCount: () => 1,
+			getItemHeight: (i) => ITEM_HEIGHT,
+			getBeforeResizeItemsCount: () => 0,
+			getAverageItemHeight: () => ITEM_HEIGHT,
+			getScrollableContainerHeight: () => scrollableContainer.height
+		})
+
+		layout.getLayoutUpdateForItemsDiff(
+			{
+				firstShownItemIndex: 3,
+				lastShownItemIndex: 5,
+				beforeItemsHeight: 3 * (ITEM_HEIGHT + VERTICAL_SPACING),
+				afterItemsHeight: 3 * (ITEM_HEIGHT + VERTICAL_SPACING)
+			},
+			{
+				prependedItemsCount: 5,
+				appendedItemsCount: 5
+			}, {
+				itemsCount: 5 + 5 + items.length,
+				columnsCount: 1
+			}
+		).should.deep.equal({
+			firstShownItemIndex: 5 + 3,
+			lastShownItemIndex: 5 + 5,
+			beforeItemsHeight: (5 + 3) * (ITEM_HEIGHT + VERTICAL_SPACING),
+			afterItemsHeight: (3 + 5) * (ITEM_HEIGHT + VERTICAL_SPACING)
+		})
+	})
+
+	it('should update layout for items incremental change (rows get rebalanced)', function() {
+		const scrollableContainer = {
+			width: 800,
+			height: 400
+		}
+		const ITEM_WIDTH = scrollableContainer.width
+		const ITEM_HEIGHT = 400
+
+		const items = new Array(9).fill(ITEM_WIDTH * ITEM_HEIGHT)
+
+		const VERTICAL_SPACING = 100
+
+		const layout = new Layout({
+			getPrerenderMargin: () => scrollableContainer.height,
+			getVerticalSpacing: () => VERTICAL_SPACING,
+			getColumnsCount: () => 4,
+			getItemHeight: () => ITEM_HEIGHT,
+			getBeforeResizeItemsCount: () => 0,
+			getAverageItemHeight: () => ITEM_HEIGHT,
+			getScrollableContainerHeight: () => scrollableContainer.height
+		})
+
+		let shouldResetGridLayout
+
+		layout.getLayoutUpdateForItemsDiff(
+			{
+				firstShownItemIndex: 3,
+				lastShownItemIndex: 5,
+				beforeItemsHeight: 3 * (ITEM_HEIGHT + VERTICAL_SPACING),
+				afterItemsHeight: 3 * (ITEM_HEIGHT + VERTICAL_SPACING)
+			},
+			{
+				prependedItemsCount: 5,
+				appendedItemsCount: 5
+			}, {
+				itemsCount: 5 + 5 + items.length,
+				columnsCount: 4,
+				shouldRestoreScrollPosition: true,
+				onResetGridLayout: () => shouldResetGridLayout = true
+			}
+		).should.deep.equal({
+			firstShownItemIndex: 0,
+			lastShownItemIndex: 5 + 5,
+			beforeItemsHeight: 0,
+			afterItemsHeight: 5 * (ITEM_HEIGHT + VERTICAL_SPACING)
+		})
+
+		shouldResetGridLayout.should.equal(true)
+	})
+})

package/source/ListHeightMeasurement.js

@@ -0,0 +1,95 @@
+export default class ListHeightMeasurement {
+	constructor({
+		itemsContainer,
+		getListTopOffset
+	}) {
+		this.itemsContainer = itemsContainer
+		this.getListTopOffset = getListTopOffset
+	}
+
+	/**
+	 * Snapshots the list height while `previousItems` are still rendered,
+	 * before rendering `newItems`. The list height will be re-measured
+	 * after the new items have been rendered, yielding the list height difference
+	 * which is gonna be the amount to scroll vertically in order to restore
+	 * the previous scroll position. Is only used when prepending items.
+	 * @param  {any[]} previousItems
+	 * @param  {any[]} newItems
+	 * @param  {number} prependedItemsCount
+	 */
+	snapshotListHeightBeforeAddingNewItems({
+		previousItems,
+		newItems,
+		prependedItemsCount
+	}) {
+		// If there were no items in the list
+		// then there's no point in restoring scroll position.
+		if (previousItems.length === 0) {
+			return
+		}
+
+		// If no items were prepended then no need to restore scroll position.
+		if (prependedItemsCount === 0) {
+			return
+		}
+
+		// The first item is supposed to be shown when the user clicks
+		// "Show previous items" button. If it isn't shown though,
+		// could still calculate the first item's top position using
+		// the values from `itemHeights` and `verticalSpacing`.
+		// But that would be a weird non-realistic scenario.
+		// if (firstShownItemIndex > 0) {
+		// 	let i = firstShownItemIndex - 1
+		// 	while (i >= 0) {
+		// 		firstItemTopOffset += itemHeights[i] + verticalSpacing
+		// 		i--
+		// 	}
+		// }
+
+		// This part is longer relevant: <ReactVirtualScroller/> no longer calls
+		// this function two times consequtively.
+		//
+		// // If the scroll position has already been captured for restoration,
+		// // then don't capture it the second time.
+		// if (this._snapshot &&
+		// 	this._snapshot.previousItems === previousItems &&
+		// 	this._snapshot.newItems === newItems) {
+		// 	return
+		// }
+
+		this._snapshot = {
+			previousItems,
+			newItems,
+			itemIndex: prependedItemsCount,
+			itemTopOffset: this.itemsContainer.getNthRenderedItemTopOffset(0),
+			// Snapshot list top offset inside the scrollable container too
+			// because it's common to hide the "Show previous items" button
+			// when the user has browsed to the top of the list, which causes
+			// the list's top position to shift upwards due to the button
+			// no longer being rendered. Tracking list top offset doesn't
+			// fit here that well, but it makes sense in real-world applications.
+			listTopOffset: this.getListTopOffset()
+		}
+	}
+
+	getAnchorItemIndex() {
+		return this._snapshot.itemIndex
+	}
+
+	hasSnapshot() {
+		return this._snapshot !== undefined
+	}
+
+	getListBottomOffsetChange() {
+		const { itemIndex, itemTopOffset, listTopOffset } = this._snapshot
+		// `firstShownItemIndex` is supposed to be `0` at this point,
+		// so `renderedElementIndex` would be the same as the `itemIndex`.
+		const itemTopOffsetNew = this.itemsContainer.getNthRenderedItemTopOffset(itemIndex)
+		const listTopOffsetNew = this.getListTopOffset()
+		return (itemTopOffsetNew - itemTopOffset) + (listTopOffsetNew - listTopOffset)
+	}
+
+	reset() {
+		this._snapshot = undefined
+	}
+}

package/source/Resize.js

@@ -1,72 +1,96 @@
-import { LAYOUT_REASON } from './Layout'
-import debounce from './utility/debounce'
+import debounce from './utility/debounce.js'
+import log from './utility/debug.js'
 
 export default class Resize {
 	constructor({
 		bypass,
-		scrollableContainer,
-		getContainerElement,
-		updateLayout,
-		resetStateAndLayout
+		getWidth,
+		getHeight,
+		listenForResize,
+		onResizeStart,
+		onResizeStop,
+		onHeightChange,
+		onWidthChange,
+		onNoChange
 	}) {
 		this.bypass = bypass
-		this.scrollableContainer = scrollableContainer
-		this.getContainerElement = getContainerElement
-		this.updateLayout = updateLayout
-		this.resetStateAndLayout = resetStateAndLayout
+
+		this.onHeightChange = onHeightChange
+		this.onWidthChange = onWidthChange
+		this.onNoChange = onNoChange
+
+		this.getWidth = getWidth
+		this.getHeight = getHeight
+		this.listenForResize = listenForResize
+
+		this.onResize = debounce(
+			this._onResize,
+			SCROLLABLE_CONTAINER_RESIZE_DEBOUNCE_INTERVAL,
+			{
+				onStart: onResizeStart,
+				onStop: onResizeStop
+			}
+		)
 	}
 
-	listen() {
+	start() {
+		this.isActive = true
 		if (this.bypass) {
 			return
 		}
-		this.isRendered = true
-		this.scrollableContainerWidth = this.scrollableContainer.getWidth()
-		this.scrollableContainerHeight = this.scrollableContainer.getHeight()
-		this.scrollableContainerUnlistenResize = this.scrollableContainer.onResize(this.onResize, {
-			container: this.getContainerElement()
-		})
+		this.width = this.getWidth()
+		this.height = this.getHeight()
+		this.unlistenResize = this.listenForResize(this.onResize)
 	}
 
 	stop() {
-		this.isRendered = false
-		if (this.scrollableContainerUnlistenResize) {
-			this.scrollableContainerUnlistenResize()
+		this.isActive = false
+		this.width = undefined
+		this.height = undefined
+		if (this.unlistenResize) {
+			this.unlistenResize()
+			this.unlistenResize = undefined
 		}
 	}
 
 	/**
 	 * On scrollable container resize.
 	 */
-	onResize = debounce(() => {
+	_onResize = () => {
 		// If `VirtualScroller` has been unmounted
 		// while `debounce()`'s `setTimeout()` was waiting, then exit.
-		if (!this.isRendered) {
+		// If the `VirtualScroller` gets restarted later, it will detect
+		// that `state.scrollableContainerWidth` doesn't match the actual
+		// scrollable container width, and will call `this.onResize()`.
+		if (!this.isActive) {
 			return
 		}
-		const prevScrollableContainerWidth = this.scrollableContainerWidth
-		const prevScrollableContainerHeight = this.scrollableContainerHeight
-		this.scrollableContainerWidth = this.scrollableContainer.getWidth()
-		this.scrollableContainerHeight = this.scrollableContainer.getHeight()
-		if (this.scrollableContainerWidth === prevScrollableContainerWidth) {
-			if (this.scrollableContainerHeight === prevScrollableContainerHeight) {
+
+		const prevScrollableContainerWidth = this.width
+		const prevScrollableContainerHeight = this.height
+
+		this.width = this.getWidth()
+		this.height = this.getHeight()
+
+		if (this.width === prevScrollableContainerWidth) {
+			if (this.height === prevScrollableContainerHeight) {
 				// The dimensions of the container didn't change,
 				// so there's no need to re-layout anything.
-				return
+				this.onNoChange()
 			} else {
 				// Scrollable container height has changed,
 				// so just recalculate shown item indexes.
 				// No need to perform a re-layout from scratch.
-				this.updateLayout({ reason: LAYOUT_REASON.RESIZE })
+				this.onHeightChange(prevScrollableContainerHeight, this.height)
 			}
 		} else {
 			// 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.
-			this.resetStateAndLayout()
+			this.onWidthChange(prevScrollableContainerWidth, this.width)
 		}
-	}, SCROLLABLE_CONTAINER_RESIZE_DEBOUNCE_INTERVAL)
+	}
 }
 
 const SCROLLABLE_CONTAINER_RESIZE_DEBOUNCE_INTERVAL = 250