virtual-scroller - npm Package Compare versions

Comparing version 1.12.6 to 1.13.0

commonjs/getVerticalSpacing.js

@@ -47,4 +47,6 @@ "use strict";
         // Next row is detected. Measure inter-row spacing.
-        // Can't be "negative" with the current `if` condition.
-        return itemTopOffset - (firstShownRowTopOffset + firstShownRowHeight);
+        var verticalSpacing = itemTopOffset - (firstShownRowTopOffset + firstShownRowHeight); // The measured inter-row spacing can be slightly "negative" due to the scaling
+        // rounding errors described above. Example: `-0.00000762939453125`.
+
+        return Math.max(0, verticalSpacing);
       } // Not at the next row yet. Re-measure the current row height.
@@ -51,0 +53,0 @@ // The rationale for re-measuring is that there can be items of variable height

commonjs/react/useVirtualScrollerStartStop.js

@@ -10,12 +10,46 @@ "use strict";
 
-function useVirtualScrollerStartStop(virtualScroller) {
+var _debug = _interopRequireDefault(require("../utility/debug.js"));
+
+function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { "default": obj }; }
+
+function useVirtualScrollerStartStop(virtualScroller, _ref) {
+  var readyToStart = _ref.readyToStart;
+  var hasStarted = (0, _react.useRef)(false);
+
+  var startIfReadyToStartAndNotStarted = function startIfReadyToStartAndNotStarted() {
+    if (!hasStarted.current) {
+      if (readyToStart === false) {
+        (0, _debug["default"])('Could\'ve started but isn\'t ready to start');
+      } else {
+        hasStarted.current = true; // Start listening to scroll events.
+
+        virtualScroller.start();
+      }
+    }
+  };
+
+  var stopIfStarted = function stopIfStarted() {
+    if (hasStarted.current) {
+      // Stop listening to scroll events.
+      virtualScroller.stop(); // Can be re-started.
+
+      hasStarted.current = false;
+    }
+  }; // Uses `useLayoutEffect()` here rather than just `useEffect()`
+  // in order to reduce the timeframe of showing an empty list to the user.
+
+
   (0, _react.useLayoutEffect)(function () {
-    // Start listening to scroll events.
-    virtualScroller.start();
-    return function () {
-      // Stop listening to scroll events.
-      virtualScroller.stop();
-    };
+    startIfReadyToStartAndNotStarted();
+    return stopIfStarted;
   }, []);
+  var readyToStartPrev = (0, _react.useRef)(readyToStart);
+  (0, _react.useEffect)(function () {
+    if (readyToStartPrev.current === false && readyToStart !== false) {
+      readyToStartPrev.current = readyToStart;
+      (0, _debug["default"])('Is ready to start');
+      startIfReadyToStartAndNotStarted();
+    }
+  }, [readyToStart]);
 }
 //# sourceMappingURL=useVirtualScrollerStartStop.js.map

commonjs/react/VirtualScroller.js

@@ -38,3 +38,3 @@ "use strict";
 
-var _excluded = ["as", "items", "itemComponent", "itemComponentProps", "estimatedItemHeight", "getEstimatedItemHeight", "getEstimatedVisibleItemRowsCount", "bypass", "tbody", "preserveScrollPosition", "preserveScrollPositionOnPrependItems", "measureItemsBatchSize", "scrollableContainer", "getScrollableContainer", "getColumnsCount", "getItemId", "className", "onMount", "onItemFirstRender", "onItemInitialRender", "initialScrollPosition", "onScrollPositionChange", "onStateChange", "initialState", "getInitialItemState"];
+var _excluded = ["as", "items", "itemComponent", "itemComponentProps", "estimatedItemHeight", "getEstimatedItemHeight", "getEstimatedVisibleItemRowsCount", "bypass", "tbody", "preserveScrollPosition", "preserveScrollPositionOnPrependItems", "measureItemsBatchSize", "scrollableContainer", "getScrollableContainer", "getColumnsCount", "getItemId", "className", "readyToStart", "onMount", "onItemFirstRender", "onItemInitialRender", "initialScrollPosition", "onScrollPositionChange", "onStateChange", "initialState", "getInitialItemState"];
 
@@ -64,3 +64,4 @@ function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { "default": obj }; }
 function VirtualScroller(_ref, ref) {
-  var AsComponent = _ref.as,
+  var _ref$as = _ref.as,
+      AsComponent = _ref$as === void 0 ? 'div' : _ref$as,
       itemsProperty = _ref.items,
@@ -82,2 +83,3 @@ Component = _ref.itemComponent,
       className = _ref.className,
+      readyToStart = _ref.readyToStart,
       onMount = _ref.onMount,
@@ -150,3 +152,5 @@ onItemFirstRender = _ref.onItemFirstRender,
 
-  (0, _useVirtualScrollerStartStop["default"])(virtualScroller); // List items are rendered with `key`s so that React doesn't
+  (0, _useVirtualScrollerStartStop["default"])(virtualScroller, {
+    readyToStart: readyToStart
+  }); // List items are rendered with `key`s so that React doesn't
   // "reuse" `itemComponent`s in cases when `items` are changed.
@@ -246,2 +250,6 @@
       //
+      // * Passing `onHeightChange` property for legacy reasons.
+      //   The new property name is `onHeightDidChange`.
+      //   The old property name `onHeightChange` is deprecated.
+      //
       return /*#__PURE__*/_react["default"].createElement(Component, _extends({
@@ -297,2 +305,3 @@ item: item,
   className: _propTypes["default"].string,
+  readyToStart: _propTypes["default"].bool,
   onMount: _propTypes["default"].func,
@@ -318,5 +327,2 @@ onItemInitialRender: _propTypes["default"].func,
 };
-VirtualScroller.defaultProps = {
-  as: 'div'
-};
 //# sourceMappingURL=VirtualScroller.js.map

commonjs/VirtualScroller.layout.js

@@ -444,3 +444,14 @@ "use strict";
     if (previousHeight === undefined) {
-      return (0, _debug.reportError)("\"onItemHeightDidChange()\" has been called for item index ".concat(i, " but the item hasn't been rendered before."));
+      // There're valid cases when the item still hasn't been measured and `onItemHeightDidChange()`
+      // function was called for it. That's because measuring items is only done after the `VirtualScroller`
+      // has `start()`ed. But it's not neccessarily `start()`ed by the time it has been rendered (mounted).
+      // For example, the React component `<VirtualScroller/>` provides an `readyToStart={false}` property
+      // in order to let the application finish initializing itself before starting the `VirtualScroller`.
+      // So there're legitimate cases when a `VirtualScroller` is already rendered but is not `start()`ed yet.
+      // In those cases, not re-measuring the item's height when it changes would not result in any bug
+      // because the item height will be re-measured anyway the first time it's rendered.
+      // So in such situations, re-measuring the item's height can be skipped without any consequence.
+      //
+      // return reportError(`"onItemHeightDidChange()" has been called for item index ${i} but the item hasn't been rendered before.`)
+      return;
     }
@@ -447,0 +458,0 @@

dom/index.d.ts

@@ -1,4 +0,4 @@
-import { State, NoItemState, VirtualScrollerCommonOptions, SetItemsOptions } from '../index.d.ts';
+import { State, NoItemState, VirtualScrollerCommonOptions, SetItemsOptions } from '../index.d.js';
 
-export { State } from '../index.d.ts';
+export { State } from '../index.d.js';
 
@@ -5,0 +5,0 @@ import * as React from 'react';

index.d.ts

@@ -24,3 +24,3 @@ export type ItemHeight = number | undefined;
 
-export interface ItemsContainer<Element> {
+export class ItemsContainer<Element> {
 	constructor(getElement: () => Element);
@@ -33,3 +33,3 @@ getNthRenderedItemTopOffset(renderedElementIndex: number): number;
 
-export interface ScrollableContainer<Element> {
+export class ScrollableContainer<Element> {
 	constructor(element: Element, getItemsContainerElement: () => Element);
@@ -56,3 +56,3 @@ getWidth(): number;
 	bypass?: boolean;
-	onStateChange?(newState: State<Item, ItemState>);
+	onStateChange?(newState: State<Item, ItemState>): void;
 	getInitialItemState?: (item: Item) => ItemState;
@@ -59,0 +59,0 @@ measureItemsBatchSize?: number;

modules/getVerticalSpacing.js

@@ -40,4 +40,6 @@ export default function getVerticalSpacing(_ref) {
         // Next row is detected. Measure inter-row spacing.
-        // Can't be "negative" with the current `if` condition.
-        return itemTopOffset - (firstShownRowTopOffset + firstShownRowHeight);
+        var verticalSpacing = itemTopOffset - (firstShownRowTopOffset + firstShownRowHeight); // The measured inter-row spacing can be slightly "negative" due to the scaling
+        // rounding errors described above. Example: `-0.00000762939453125`.
+
+        return Math.max(0, verticalSpacing);
       } // Not at the next row yet. Re-measure the current row height.
@@ -44,0 +46,0 @@ // The rationale for re-measuring is that there can be items of variable height

modules/react/useVirtualScrollerStartStop.js

@@ -1,12 +0,43 @@
-import { useLayoutEffect } from 'react';
-export default function useVirtualScrollerStartStop(virtualScroller) {
+import { useLayoutEffect, useEffect, useRef } from 'react';
+import log from '../utility/debug.js';
+export default function useVirtualScrollerStartStop(virtualScroller, _ref) {
+  var readyToStart = _ref.readyToStart;
+  var hasStarted = useRef(false);
+
+  var startIfReadyToStartAndNotStarted = function startIfReadyToStartAndNotStarted() {
+    if (!hasStarted.current) {
+      if (readyToStart === false) {
+        log('Could\'ve started but isn\'t ready to start');
+      } else {
+        hasStarted.current = true; // Start listening to scroll events.
+
+        virtualScroller.start();
+      }
+    }
+  };
+
+  var stopIfStarted = function stopIfStarted() {
+    if (hasStarted.current) {
+      // Stop listening to scroll events.
+      virtualScroller.stop(); // Can be re-started.
+
+      hasStarted.current = false;
+    }
+  }; // Uses `useLayoutEffect()` here rather than just `useEffect()`
+  // in order to reduce the timeframe of showing an empty list to the user.
+
+
   useLayoutEffect(function () {
-    // Start listening to scroll events.
-    virtualScroller.start();
-    return function () {
-      // Stop listening to scroll events.
-      virtualScroller.stop();
-    };
+    startIfReadyToStartAndNotStarted();
+    return stopIfStarted;
   }, []);
+  var readyToStartPrev = useRef(readyToStart);
+  useEffect(function () {
+    if (readyToStartPrev.current === false && readyToStart !== false) {
+      readyToStartPrev.current = readyToStart;
+      log('Is ready to start');
+      startIfReadyToStartAndNotStarted();
+    }
+  }, [readyToStart]);
 }
 //# sourceMappingURL=useVirtualScrollerStartStop.js.map

modules/react/VirtualScroller.js

@@ -1,2 +0,2 @@
-var _excluded = ["as", "items", "itemComponent", "itemComponentProps", "estimatedItemHeight", "getEstimatedItemHeight", "getEstimatedVisibleItemRowsCount", "bypass", "tbody", "preserveScrollPosition", "preserveScrollPositionOnPrependItems", "measureItemsBatchSize", "scrollableContainer", "getScrollableContainer", "getColumnsCount", "getItemId", "className", "onMount", "onItemFirstRender", "onItemInitialRender", "initialScrollPosition", "onScrollPositionChange", "onStateChange", "initialState", "getInitialItemState"];
+var _excluded = ["as", "items", "itemComponent", "itemComponentProps", "estimatedItemHeight", "getEstimatedItemHeight", "getEstimatedVisibleItemRowsCount", "bypass", "tbody", "preserveScrollPosition", "preserveScrollPositionOnPrependItems", "measureItemsBatchSize", "scrollableContainer", "getScrollableContainer", "getColumnsCount", "getItemId", "className", "readyToStart", "onMount", "onItemFirstRender", "onItemInitialRender", "initialScrollPosition", "onScrollPositionChange", "onStateChange", "initialState", "getInitialItemState"];
 
@@ -34,3 +34,4 @@ function _extends() { _extends = Object.assign || function (target) { for (var i = 1; i < arguments.length; i++) { var source = arguments[i]; for (var key in source) { if (Object.prototype.hasOwnProperty.call(source, key)) { target[key] = source[key]; } } } return target; }; return _extends.apply(this, arguments); }
 function VirtualScroller(_ref, ref) {
-  var AsComponent = _ref.as,
+  var _ref$as = _ref.as,
+      AsComponent = _ref$as === void 0 ? 'div' : _ref$as,
       itemsProperty = _ref.items,
@@ -52,2 +53,3 @@ Component = _ref.itemComponent,
       className = _ref.className,
+      readyToStart = _ref.readyToStart,
       onMount = _ref.onMount,
@@ -120,3 +122,5 @@ onItemFirstRender = _ref.onItemFirstRender,
 
-  useVirtualScrollerStartStop(virtualScroller); // List items are rendered with `key`s so that React doesn't
+  useVirtualScrollerStartStop(virtualScroller, {
+    readyToStart: readyToStart
+  }); // List items are rendered with `key`s so that React doesn't
   // "reuse" `itemComponent`s in cases when `items` are changed.
@@ -216,2 +220,6 @@
       //
+      // * Passing `onHeightChange` property for legacy reasons.
+      //   The new property name is `onHeightDidChange`.
+      //   The old property name `onHeightChange` is deprecated.
+      //
       return /*#__PURE__*/React.createElement(Component, _extends({
@@ -264,2 +272,3 @@ item: item,
   className: PropTypes.string,
+  readyToStart: PropTypes.bool,
   onMount: PropTypes.func,
@@ -285,5 +294,2 @@ onItemInitialRender: PropTypes.func,
 };
-VirtualScroller.defaultProps = {
-  as: 'div'
-};
 //# sourceMappingURL=VirtualScroller.js.map

modules/VirtualScroller.layout.js

@@ -429,3 +429,14 @@ function ownKeys(object, enumerableOnly) { var keys = Object.keys(object); if (Object.getOwnPropertySymbols) { var symbols = Object.getOwnPropertySymbols(object); enumerableOnly && (symbols = symbols.filter(function (sym) { return Object.getOwnPropertyDescriptor(object, sym).enumerable; })), keys.push.apply(keys, symbols); } return keys; }
     if (previousHeight === undefined) {
-      return reportError("\"onItemHeightDidChange()\" has been called for item index ".concat(i, " but the item hasn't been rendered before."));
+      // There're valid cases when the item still hasn't been measured and `onItemHeightDidChange()`
+      // function was called for it. That's because measuring items is only done after the `VirtualScroller`
+      // has `start()`ed. But it's not neccessarily `start()`ed by the time it has been rendered (mounted).
+      // For example, the React component `<VirtualScroller/>` provides an `readyToStart={false}` property
+      // in order to let the application finish initializing itself before starting the `VirtualScroller`.
+      // So there're legitimate cases when a `VirtualScroller` is already rendered but is not `start()`ed yet.
+      // In those cases, not re-measuring the item's height when it changes would not result in any bug
+      // because the item height will be re-measured anyway the first time it's rendered.
+      // So in such situations, re-measuring the item's height can be skipped without any consequence.
+      //
+      // return reportError(`"onItemHeightDidChange()" has been called for item index ${i} but the item hasn't been rendered before.`)
+      return;
     }
@@ -432,0 +443,0 @@

package.json

 {
   "name": "virtual-scroller",
-  "version": "1.12.6",
+  "version": "1.13.0",
   "description": "A component for efficiently rendering large lists of variable height items",
@@ -5,0 +5,0 @@ "main": "index.cjs",

react/index.d.ts

@@ -1,4 +0,4 @@
-import { State, NoItemState, VirtualScrollerCommonOptions } from '../index.d.ts';
+import { State, NoItemState, VirtualScrollerCommonOptions } from '../index.d.js';
 
-export { State } from '../index.d.ts';
+export { State } from '../index.d.js';
 
@@ -51,15 +51,16 @@ import * as React from 'react';
 
-interface ItemComponentPassedProps<Item, ItemState> {
+export interface ItemComponentVirtualScrollerProps<Item, ItemState> {
 	item: Item;
 	state: ItemState;
 	setState: (newState: ItemState) => void;
-	onHeightChange: () => void;
+	onHeightDidChange: () => void;
 }
 
-interface Props<ItemComponentProps extends object, Item, ItemState> extends VirtualScrollerCommonOptions<Item, ItemState> {
+interface PropsBase<ItemComponentProps extends object, Item, ItemState> extends VirtualScrollerCommonOptions<Item, ItemState> {
 	items: Item[];
-	itemComponent: React.ElementType<ItemComponentProps & ItemComponentPassedProps<Item, ItemState>>;
+	itemComponent: React.ElementType<ItemComponentProps & ItemComponentVirtualScrollerProps<Item, ItemState>>;
 	itemComponentProps?: ItemComponentProps;
 	initialState?: State<Item, ItemState>;
 	preserveScrollPositionOnPrependItems?: boolean;
+	readyToStart?: boolean;
 
@@ -69,6 +70,18 @@ getScrollableContainer?(): HTMLElement;
 
-declare function VirtualScroller<ItemComponentProps extends object = {}, Item = any, ItemState = NoItemState, AsElement extends React.ElementType = 'div'>(
-	props: PolymorphicComponentProps<AsElement, Props<ItemComponentProps, Item, ItemState>>
+export type Props<
+	ItemComponentProps extends object = {},
+	Item = any,
+	ItemState = NoItemState,
+	AsElement extends React.ElementType = 'div'
+> = PolymorphicComponentProps<AsElement, PropsBase<ItemComponentProps, Item, ItemState>>
+
+declare function VirtualScroller<
+	ItemComponentProps extends object = {},
+	Item = any,
+	ItemState = NoItemState,
+	AsElement extends React.ElementType = 'div'
+>(
+	props: Props<ItemComponentProps, Item, ItemState, AsElement>
 ): JSX.Element;
 
 export default VirtualScroller;

source/getVerticalSpacing.js

@@ -38,4 +38,6 @@ export default function getVerticalSpacing({ itemsContainer, renderedItemsCount }) {
 				// Next row is detected. Measure inter-row spacing.
-				// Can't be "negative" with the current `if` condition.
-				return itemTopOffset - (firstShownRowTopOffset + firstShownRowHeight)
+				const verticalSpacing = itemTopOffset - (firstShownRowTopOffset + firstShownRowHeight)
+				// The measured inter-row spacing can be slightly "negative" due to the scaling
+				// rounding errors described above. Example: `-0.00000762939453125`.
+				return Math.max(0, verticalSpacing)
 			}
@@ -42,0 +44,0 @@

source/react/useVirtualScrollerStartStop.js

@@ -1,12 +0,45 @@
-import { useLayoutEffect } from 'react'
+import { useLayoutEffect, useEffect, useRef } from 'react'
 
-export default function useVirtualScrollerStartStop(virtualScroller) {
-	useLayoutEffect(() => {
-		// Start listening to scroll events.
-		virtualScroller.start()
-		return () => {
+import log from '../utility/debug.js'
+
+export default function useVirtualScrollerStartStop(virtualScroller, { readyToStart }) {
+	const hasStarted = useRef(false)
+
+	const startIfReadyToStartAndNotStarted = () => {
+		if (!hasStarted.current) {
+			if (readyToStart === false) {
+				log('Could\'ve started but isn\'t ready to start')
+			} else {
+				hasStarted.current = true
+				// Start listening to scroll events.
+				virtualScroller.start()
+			}
+		}
+	}
+
+	const stopIfStarted = () => {
+		if (hasStarted.current) {
 			// Stop listening to scroll events.
 			virtualScroller.stop()
+			// Can be re-started.
+			hasStarted.current = false
 		}
+	}
+
+	// Uses `useLayoutEffect()` here rather than just `useEffect()`
+	// in order to reduce the timeframe of showing an empty list to the user.
+	useLayoutEffect(() => {
+		startIfReadyToStartAndNotStarted()
+		return stopIfStarted
 	}, [])
+
+	const readyToStartPrev = useRef(readyToStart)
+
+	useEffect(() => {
+		if (readyToStartPrev.current === false && readyToStart !== false) {
+			readyToStartPrev.current = readyToStart
+			log('Is ready to start')
+			startIfReadyToStartAndNotStarted()
+		}
+	}, [readyToStart])
 }

source/react/VirtualScroller.js

@@ -30,3 +30,3 @@ import React, { useRef, useMemo, useLayoutEffect } from 'react'
 function VirtualScroller({
-	as: AsComponent,
+	as: AsComponent = 'div',
 	items: itemsProperty,
@@ -54,2 +54,3 @@ itemComponent: Component,
 	className,
+	readyToStart,
 	onMount,
@@ -127,3 +128,3 @@ // `onItemFirstRender(i)` is deprecated, use `onItemInitialRender(item)` instead.
 	// Stop `VirtualScroller` on unmount.
-	useVirtualScrollerStartStop(virtualScroller)
+	useVirtualScrollerStartStop(virtualScroller, { readyToStart })
 
@@ -239,2 +240,6 @@ // List items are rendered with `key`s so that React doesn't
 					//
+					// * Passing `onHeightChange` property for legacy reasons.
+					//   The new property name is `onHeightDidChange`.
+					//   The old property name `onHeightChange` is deprecated.
+					//
 					return (
@@ -298,2 +303,3 @@ <Component
 	className: PropTypes.string,
+	readyToStart: PropTypes.bool,
 	onMount: PropTypes.func,
@@ -319,5 +325,1 @@ onItemInitialRender: PropTypes.func,
 }
-
-VirtualScroller.defaultProps = {
-	as: 'div'
-}

source/VirtualScroller.layout.js

@@ -417,3 +417,14 @@ // For some weird reason, in Chrome, `setTimeout()` would lag up to a second (or more) behind.
 		if (previousHeight === undefined) {
-			return reportError(`"onItemHeightDidChange()" has been called for item index ${i} but the item hasn't been rendered before.`)
+			// There're valid cases when the item still hasn't been measured and `onItemHeightDidChange()`
+			// function was called for it. That's because measuring items is only done after the `VirtualScroller`
+			// has `start()`ed. But it's not neccessarily `start()`ed by the time it has been rendered (mounted).
+			// For example, the React component `<VirtualScroller/>` provides an `readyToStart={false}` property
+			// in order to let the application finish initializing itself before starting the `VirtualScroller`.
+			// So there're legitimate cases when a `VirtualScroller` is already rendered but is not `start()`ed yet.
+			// In those cases, not re-measuring the item's height when it changes would not result in any bug
+			// because the item height will be re-measured anyway the first time it's rendered.
+			// So in such situations, re-measuring the item's height can be skipped without any consequence.
+			//
+			// return reportError(`"onItemHeightDidChange()" has been called for item index ${i} but the item hasn't been rendered before.`)
+			return
 		}
@@ -420,0 +431,0 @@

No alert changes

Improved metrics

Total package byte prevSize

3671438

increased by0.59%

Lines of code

22128

increased by0.65%

Number of lines in readme file

1148

increased by0.26%

No dependency changes