virtual-scroller 1.7.9 → 1.9.0

package/source/DOM/ScrollableContainer.js

@@ -1,10 +1,12 @@
 export default class ScrollableContainer {
 	/**
 	 * Constructs a new "scrollable container" from an element.
-	 * @param {Element} scrollableContainer
+	 * @param {func} getElement — Returns the scrollable container element.
+	 * @param {func} getItemsContainerElement — Returns items "container" element.
 	 */
-	constructor(element) {
-		this.element = element
+	constructor(getElement, getItemsContainerElement) {
+		this.getElement = getElement
+		this.getItemsContainerElement = getItemsContainerElement
 	}
 
 	/**
@@ -12,7 +14,7 @@ export default class ScrollableContainer {
 	 * @return {number}
 	 */
 	getScrollY() {
-		return this.element.scrollTop
+		return this.getElement().scrollTop
 	}
 
 	/**
@@ -23,10 +25,10 @@ export default class ScrollableContainer {
 		// IE 11 doesn't seem to have a `.scrollTo()` method.
 		// https://gitlab.com/catamphetamine/virtual-scroller/-/issues/10
 		// https://stackoverflow.com/questions/39908825/window-scrollto-is-not-working-in-internet-explorer-11
-		if (this.element.scrollTo) {
-			this.element.scrollTo(0, scrollY)
+		if (this.getElement().scrollTo) {
+			this.getElement().scrollTo(0, scrollY)
 		} else {
-			this.element.scrollTop = scrollY
+			this.getElement().scrollTop = scrollY
 		}
 	}
 
@@ -36,7 +38,7 @@ export default class ScrollableContainer {
 	 * @return {number}
 	 */
 	getWidth() {
-		return this.element.offsetWidth
+		return this.getElement().offsetWidth
 	}
 
 	/**
@@ -45,64 +47,47 @@ export default class ScrollableContainer {
 	 * @return {number}
 	 */
 	getHeight() {
-		// if (!this.element && !precise) {
+		// if (!this.getElement() && !precise) {
 		// 	return getScreenHeight()
 		// }
-		return this.element.offsetHeight
+		return this.getElement().offsetHeight
 	}
 
 	/**
-	 * Returns the height of the content in a scrollable container.
-	 * For example, a scrollable container can have a height of 500px,
-	 * but the content in it could have a height of 5000px,
-	 * in which case a vertical scrollbar is rendered, and only
-	 * one-tenth of all the items are shown at any given moment.
-	 * This function is currently only used when using the
-	 * `preserveScrollPositionOfTheBottomOfTheListOnMount` feature.
-	 * @return {number}
-	 */
-	getContentHeight() {
-		return this.element.scrollHeight
-	}
-
-	/**
-	 * Returns a "top offset" of an element
+	 * Returns a "top offset" of an items container element
 	 * relative to the "scrollable container"'s top edge.
-	 * @param {Element} element
 	 * @return {number}
 	 */
-	getTopOffset(element) {
-		const scrollableContainerTop = this.element.getBoundingClientRect().top
-		const scrollableContainerBorderTopWidth = this.element.clientTop
-		const top = element.getBoundingClientRect().top
-		return (top - scrollableContainerTop) + this.getScrollY() - scrollableContainerBorderTopWidth
+	getItemsContainerTopOffset() {
+		const scrollableContainerTop = this.getElement().getBoundingClientRect().top
+		const scrollableContainerBorderTopWidth = this.getElement().clientTop
+		const itemsContainerTop = this.getItemsContainerElement().getBoundingClientRect().top
+		return (itemsContainerTop - scrollableContainerTop) + this.getScrollY() - scrollableContainerBorderTopWidth
 	}
 
 	// isVisible() {
-	// 	const { top, bottom } = this.element.getBoundingClientRect()
+	// 	const { top, bottom } = this.getElement().getBoundingClientRect()
 	// 	return bottom > 0 && top < getScreenHeight()
 	// }
 
 	/**
 	 * Adds a "scroll" event listener to the "scrollable container".
-	 * @param {onScroll} Should be called whenever the scroll position inside the "scrollable container" (potentially) changes.
+	 * @param {onScrollListener} Should be called whenever the scroll position inside the "scrollable container" (potentially) changes.
 	 * @return {function} Returns a function that stops listening.
 	 */
-	addScrollListener(onScroll) {
-		this.element.addEventListener('scroll', onScroll)
-		return () => this.element.removeEventListener('scroll', onScroll)
+	onScroll(onScrollListener) {
+		const element = this.getElement()
+		element.addEventListener('scroll', onScrollListener)
+		return () => element.removeEventListener('scroll', 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.
-	 * @param  {Element} options.container — The result of the `getContainerElement()` function that was passed in `VirtualScroller` constructor. For example, DOM renderer uses it to filter-out unrelated "resize" events.
-	 * @return {function} Returns a function that stops listening.
+   * @return {function} Returns a function that stops listening.
 	 */
-	onResize(onResize, { container }) {
-		// Could somehow track DOM Element size.
-		// For now, `scrollableContainer` is supposed to have constant width and height.
-		// (unless window is resized).
+	onResize(onResize) {
+		// Watches "scrollable container"'s dimensions via a `ResizeObserver`.
 		// https://developer.mozilla.org/en-US/docs/Web/API/ResizeObserver
 		// https://web.dev/resize-observer/
 		let unobserve
@@ -110,7 +95,7 @@ export default class ScrollableContainer {
 			const resizeObserver = new ResizeObserver((entries) => {
 				// "one entry per observed element".
 				// https://web.dev/resize-observer/
-				// `entry.target === this.element`.
+				// `entry.target === this.getElement()`.
 				const entry = entries[0]
 				// // If `entry.contentBoxSize` property is supported by the web browser.
 				// if (entry.contentBoxSize) {
@@ -120,8 +105,9 @@ export default class ScrollableContainer {
 				// }
 				onResize()
 			})
-			resizeObserver.observe(this.element)
-			unobserve = () => resizeObserver.unobserve(this.element)
+			const element = this.getElement()
+			resizeObserver.observe(element)
+			unobserve = () => resizeObserver.unobserve(element)
 		}
 		// I guess, if window is resized, `onResize()` will be triggered twice:
 		// once for window resize, and once for the scrollable container resize.
@@ -129,7 +115,9 @@ export default class ScrollableContainer {
 		// hasn't changed since the previous time `onResize()` has been called,
 		// then `onResize()` doesn't do anything, so, I guess, there shouldn't be
 		// any "performance implications" of running the listener twice in such case.
-		const unlistenGlobalResize = addGlobalResizeListener(onResize, { container })
+		const unlistenGlobalResize = addGlobalResizeListener(onResize, {
+			itemsContainerElement: this.getItemsContainerElement()
+		})
 		return () => {
 			if (unobserve) {
 				unobserve()
@@ -140,8 +128,12 @@ export default class ScrollableContainer {
 }
 
 export class ScrollableWindowContainer extends ScrollableContainer {
-	constructor() {
-		super(window)
+	/**
+	 * Constructs a new window "scrollable container".
+	 * @param {func} getItemsContainerElement — Returns items "container" element.
+	 */
+	constructor(getItemsContainerElement) {
+		super(() => window, getItemsContainerElement)
 	}
 
 	/**
@@ -189,38 +181,24 @@ export class ScrollableWindowContainer extends ScrollableContainer {
 	}
 
 	/**
-	 * Returns the height of the content in a scrollable container.
-	 * For example, a scrollable container can have a height of 500px,
-	 * but the content in it could have a height of 5000px,
-	 * in which case a vertical scrollbar is rendered, and only
-	 * one-tenth of all the items are shown at any given moment.
-	 * This function is currently only used when using the
-	 * `preserveScrollPositionOfTheBottomOfTheListOnMount` feature.
-	 * @return {number}
-	 */
-	getContentHeight() {
-		return document.documentElement.scrollHeight
-	}
-
-	/**
-	 * Returns a "top offset" of an element
+	 * Returns a "top offset" of an items container element
 	 * relative to the "scrollable container"'s top edge.
-	 * @param {Element} element
 	 * @return {number}
 	 */
-	getTopOffset(element) {
+	getItemsContainerTopOffset() {
 		const borderTopWidth = document.clientTop || document.body.clientTop || 0
-		return element.getBoundingClientRect().top + this.getScrollY() - borderTopWidth
+		return this.getItemsContainerElement().getBoundingClientRect().top + this.getScrollY() - borderTopWidth
 	}
 
 	/**
 	 * Adds a "resize" event listener to the "scrollable container".
 	 * @param {onScroll} Should be called whenever the "scrollable container"'s width or height (potentially) changes.
-	 * @param  {Element} options.container — The result of the `getContainerElement()` function that was passed in `VirtualScroller` constructor. For example, DOM renderer uses it to filter-out unrelated "resize" events.
 	 * @return {function} Returns a function that stops listening.
 	 */
-	onResize(onResize, { container }) {
-		return addGlobalResizeListener(onResize, { container })
+	onResize(onResize) {
+		return addGlobalResizeListener(onResize, {
+			itemsContainerElement: this.getItemsContainerElement()
+		})
 	}
 
 	// isVisible() {
@@ -230,11 +208,11 @@ export class ScrollableWindowContainer extends ScrollableContainer {
 
 /**
  * Adds a "resize" event listener to the `window`.
- * @param {onResize} Should be called whenever the "container"'s width or height (potentially) changes.
- * @param  {Element} options.container — The "container".
+ * @param {onResize} Should be called whenever the "scrollable container"'s width or height (potentially) changes.
+ * @param  {Element} options.itemsContainerElement — The items "container" element, which is not the same as the "scrollable container" element. For example, "scrollable container" could be resized while the list element retaining its size. One such example is a user entering fullscreen mode on an HTML5 `<video/>` element: in that case, a "resize" event is triggered on a window, and window dimensions change to the user's screen size, but such "resize" event can be ignored because the list isn't visible until the user exits fullscreen mode.
  * @return {function} Returns a function that stops listening.
  */
-function addGlobalResizeListener(onResize, { container }) {
+function addGlobalResizeListener(onResize, { itemsContainerElement }) {
 	const onResizeListener = () => {
 		// By default, `VirtualScroller` always performs a re-layout
 		// on window `resize` event. But browsers (Chrome, Firefox)
@@ -265,7 +243,7 @@ function addGlobalResizeListener(onResize, { container }) {
 			// the layout wouldn't be affected too, so such `resize` event should also be
 			// ignored: when `document.fullscreenElement` is inside the `container`.
 			//
-			if (document.fullscreenElement.contains(container)) {
+			if (document.fullscreenElement.contains(itemsContainerElement)) {
 				// The element is either the `container`'s ancestor,
 				// Or is the `container` itself.
 				// (`a.contains(b)` includes the `a === b` case).

package/source/DOM/VirtualScroller.js

@@ -1,37 +1,42 @@
-import VirtualScrollerCore from '../VirtualScroller'
+import VirtualScrollerCore from '../VirtualScroller.js'
 
-import log, { warn } from '../utility/debug'
-import px from '../utility/px'
+import log, { warn } from '../utility/debug.js'
+import px from '../utility/px.js'
 
 export default class VirtualScroller {
-  constructor(element, items, renderItem, options = {}) {
-    this.container = element
+  constructor(itemsContainerElement, items, renderItem, options = {}) {
+    this.container = itemsContainerElement
     this.renderItem = renderItem
+
     const {
       onMount,
       onItemUnmount,
       ...restOptions
     } = options
+
     this.onItemUnmount = onItemUnmount
     this.tbody = this.container.tagName === 'TBODY'
+
     this.virtualScroller = new VirtualScrollerCore(
       () => this.container,
       items,
       {
         ...restOptions,
-        tbody: this.tbody,
-        onStateChange: this.onStateChange
+        render: this.render,
+        tbody: this.tbody
       }
     )
+
+    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()
     }
-    this.virtualScroller.listen()
   }
 
-  onStateChange = (state, prevState) => {
+  render = (state, prevState) => {
     const {
       items,
       firstShownItemIndex,
@@ -39,9 +44,11 @@ export default class VirtualScroller {
       beforeItemsHeight,
       afterItemsHeight
     } = state
-    log('~ On state change ~')
-    log('Previous state', prevState)
-    log('New state', state)
+
+    // 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`.
     // https://gitlab.com/catamphetamine/virtual-scroller/-/issues/1
@@ -51,11 +58,11 @@ export default class VirtualScroller {
       this.container.style.paddingTop = px(beforeItemsHeight)
       this.container.style.paddingBottom = px(afterItemsHeight)
     }
+
     // Perform an intelligent "diff" re-render if the `items` are the same.
     const diffRender = prevState && items === prevState.items && items.length > 0
     // Remove no longer visible items from the DOM.
     if (diffRender) {
-      log('Incremental rerender')
       // Decrement instead of increment here because
       // `this.container.removeChild()` changes indexes.
       let i = prevState.lastShownItemIndex
@@ -63,18 +70,19 @@ export default class VirtualScroller {
         if (i >= firstShownItemIndex && i <= lastShownItemIndex) {
           // The item is still visible.
         } else {
-          log('Remove item index', i)
+          log('DOM: Remove element for item index', i)
           // The item is no longer visible. Remove it.
           this.unmountItem(this.container.childNodes[i - prevState.firstShownItemIndex])
         }
         i--
       }
     } else {
-      log('Rerender from scratch')
+      log('DOM: Rerender the list from scratch')
       while (this.container.firstChild) {
         this.unmountItem(this.container.firstChild)
       }
     }
+
     // Add newly visible items to the DOM.
     let shouldPrependItems = diffRender
     const prependBeforeItemElement = shouldPrependItems && this.container.firstChild
@@ -89,11 +97,11 @@ export default class VirtualScroller {
       } else {
         const item = this.renderItem(items[i])
         if (shouldPrependItems) {
-          log('Prepend item index', i)
+          log('DOM: Prepend element for item index', i)
           // Append `item` to `this.container` before the retained items.
           this.container.insertBefore(item, prependBeforeItemElement)
         } else {
-          log('Append item index', i)
+          log('DOM: Append element for item index', i)
           // Append `item` to `this.container`.
           this.container.appendChild(item)
         }
@@ -114,11 +122,18 @@ export default class VirtualScroller {
     this.stop()
   }
 
-  // Public API. Should be "bound" to `this`.
+  // Public API.
+  // Should be "bound" to `this`.
   stop = () => {
     this.virtualScroller.stop()
   }
 
+  // Potentially public API in some hypothetical scenario.
+  // Should be "bound" to `this`.
+  start = () => {
+    this.virtualScroller.start()
+  }
+
   unmountItem(itemElement) {
     this.container.removeChild(itemElement)
     if (this.onItemUnmount) {

package/source/DOM/tbody.js

@@ -1,7 +1,7 @@
 // A workaround for `<tbody/>` not being able to have `padding`.
 // https://gitlab.com/catamphetamine/virtual-scroller/-/issues/1
 
-import px from '../utility/px'
+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'
 
@@ -18,28 +18,37 @@ export function supportsTbody() {
 	return true
 }
 
+export const TBODY_CLASS_NAME = 'VirtualScroller'
+const STYLE_ELEMENT_ID = 'VirtualScrollerStyle'
+
+export function hasTbodyStyles(tbody) {
+	return tbody.classList.contains(TBODY_CLASS_NAME) &&
+		Boolean(document.getElementById(STYLE_ELEMENT_ID))
+}
+
 export function addTbodyStyles(tbody) {
 	// `classList.add` is supported in Internet Explorer 10+.
-	tbody.classList.add('VirtualScroller')
-	let style = document.getElementById('VirtualScrollerStyle')
-	if (!style) {
-		style = document.createElement('style')
-		style.id = 'VirtualScrollerStyle'
-		// CSS variables aren't supported in Internet Explorer.
-		style.innerText = `
-			tbody.VirtualScroller:before {
-				content: '';
-				display: table-row;
-				height: var(--VirtualScroller-paddingTop);
-			}
-			tbody.VirtualScroller:after {
-				content: '';
-				display: table-row;
-				height: var(--VirtualScroller-paddingBottom);
-			}
-		`.replace(/[\n\t]/g, '')
-		document.head.appendChild(style)
-	}
+	tbody.classList.add(TBODY_CLASS_NAME)
+
+	// Create a `<style/>` element.
+	const style = document.createElement('style')
+	style.id = STYLE_ELEMENT_ID
+
+	// CSS variables aren't supported in Internet Explorer.
+	style.innerText = `
+		tbody.${TBODY_CLASS_NAME}:before {
+			content: '';
+			display: table-row;
+			height: var(--VirtualScroller-paddingTop);
+		}
+		tbody.${TBODY_CLASS_NAME}:after {
+			content: '';
+			display: table-row;
+			height: var(--VirtualScroller-paddingBottom);
+		}
+	`.replace(/[\n\t]/g, '')
+
+	document.head.appendChild(style)
 }
 
 export function setTbodyPadding(tbody, beforeItemsHeight, afterItemsHeight) {

package/source/ItemHeights.js

@@ -1,9 +1,13 @@
-import log, { warn, isDebug, reportError } from './utility/debug'
+import log, { warn, isDebug, reportError } from './utility/debug.js'
 
 export default class ItemHeights {
-	constructor(screen, getContainerElement, getItemHeight, setItemHeight) {
-		this.screen = screen
-		this.getContainerElement = getContainerElement
+	constructor({
+		container,
+		itemHeights,
+		getItemHeight,
+		setItemHeight
+	}) {
+		this.container = container
 		this._get = getItemHeight
 		this._set = setItemHeight
 		this.reset()
@@ -25,14 +29,14 @@ export default class ItemHeights {
 	}
 
 	/**
-	 * Is called after `.reset()`.
+	 * Can only be called after a `.reset()` (including new instance creation).
 	 * Initializes `this.measuredItemsHeight`, `this.firstMeasuredItemIndex`
 	 * and `this.lastMeasuredItemIndex` instance variables from `VirtualScroller` `state`.
 	 * These instance variables are used when calculating "average" item height:
 	 * the "average" item height is simply `this.measuredItemsHeight` divided by
 	 * `this.lastMeasuredItemIndex` minus `this.firstMeasuredItemIndex` plus 1.
 	 */
-	initialize(itemHeights) {
+	readItemHeightsFromState({ itemHeights }) {
 		let i = 0
 		while (i < itemHeights.length) {
 			if (itemHeights[i] === undefined) {
@@ -64,13 +68,7 @@ export default class ItemHeights {
 	// }
 
 	_measureItemHeight(i, firstShownItemIndex) {
-		const container = this.getContainerElement()
-		if (container) {
-			const elementIndex = i - firstShownItemIndex
-			if (elementIndex >= 0 && elementIndex < this.screen.getChildElementsCount(container)) {
-				return this.screen.getChildElementHeight(container, elementIndex)
-			}
-		}
+		return this.container.getNthRenderedItemHeight(i - firstShownItemIndex)
 	}
 
 	/**
@@ -92,6 +90,7 @@ export default class ItemHeights {
 	 * @return {number[]} The indexes of the items that have not previously been measured and have been measured now.
 	 */
 	measureItemHeights(firstShownItemIndex, lastShownItemIndex) {
+		log('~ Measure item heights ~')
 		// If no items are rendered, don't measure anything.
 		if (firstShownItemIndex === undefined) {
 			return
@@ -102,8 +101,10 @@ export default class ItemHeights {
 		// then reset `this.measuredItemsHeight` and "first measured"/"last measured" item indexes.
 		// For example, this could happen when `.setItems()` prepends a lot of new items.
 		if (this.firstMeasuredItemIndex !== undefined) {
-			if (firstShownItemIndex > this.lastMeasuredItemIndex + 1 ||
-					lastShownItemIndex < this.firstMeasuredItemIndex - 1) {
+			if (
+				firstShownItemIndex > this.lastMeasuredItemIndex + 1 ||
+				lastShownItemIndex < this.firstMeasuredItemIndex - 1
+			) {
 				// Reset.
 				log('Non-measured items gap detected. Reset first and last measured item indexes.')
 				this.reset()
@@ -115,20 +116,16 @@ export default class ItemHeights {
 		let firstMeasuredItemIndexHasBeenUpdated = false
 		let i = firstShownItemIndex
 		while (i <= lastShownItemIndex) {
+			// Measure item heights that haven't been measured previously.
 			// Don't re-measure item heights that have been measured previously.
 			// The rationale is that developers are supposed to manually call
 			// `.onItemHeightChange()` every time an item's height changes.
-			// If developers aren't neglecting that rule, item heights won't
+			// If developers don't neglect that rule, item heights won't
 			// change unexpectedly.
-			// // Re-measure all shown items' heights, because an item's height
-			// // might have changed since it has been measured initially.
-			// // For example, if an item is a long comment with a "Show more" button,
-			// // then the user might have clicked that "Show more" button.
 			if (this._get(i) === undefined) {
 				nonPreviouslyMeasuredItemIndexes.push(i)
-				log('Item', i, 'hasn\'t been previously measured')
 				const height = this._measureItemHeight(i, firstShownItemIndex)
-				log('Height', height)
+				log('Item index', i, 'height', height)
 				this._set(i, height)
 				// Update average item height calculation variables
 				// related to the previously measured items
@@ -164,14 +161,17 @@ export default class ItemHeights {
 					this.lastMeasuredItemIndex = i
 				}
 			} else {
-				// Validate the item's height right after showing it after being hidden,
-				// because, if the stored item's state isn't applied properly, the item's
-				// height might be incorrect when it's rendered with that state not applied,
-				// and so a developer could know that there's a bug in their code.
+				// Validate that the item's height didn't change since it was last measured.
+				// If it did, then display a warning and update the item's height
+				// as an attempt to fix things.
+				// If an item's height changes unexpectedly then it means that there'll
+				// likely be "content jumping".
 				const previousHeight = this._get(i)
 				const height = this._measureItemHeight(i, firstShownItemIndex)
 				if (previousHeight !== height) {
-					warn('Item', i, 'height was', previousHeight, 'before it was hidden, but, after showing it again, its height is', height, '. Perhaps you forgot to persist the item\'s state by calling `onItemStateChange(i, newState)` when it changed, and that state got lost when the item element was unmounted, which resulted in a different height when the item was shown again, but with the missing state.')
+					warn('Item index', i, 'height changed unexpectedly: it was', previousHeight, 'before, but now it is', height, '. An item\'s height is allowed to change only in two cases: when the item\'s "state" changes and the developer calls `onItemStateChange(i, newState)`, or when the item\'s height changes for some other reason and the developer calls `onItemHeightChange(i)`. Perhaps you forgot to persist the item\'s "state" by calling `onItemStateChange(i, newState)` when it changed, and that "state" got lost when the item element was unmounted, which resulted in a different height when the item was shown again having its "state" reset.')
+					// Update the item's height as an attempt to fix things.
+					this._set(i, height)
 				}
 			}
 			i++