virtual-scroller - npm Package Compare versions

Comparing version 1.10.2 to 1.11.0

CHANGELOG.md

 <!-- `virtual-scroller`: in `.updateItems()` handle a case when `items.length` is the same, in which case find different items and if those items are rendered then maybe update them on screen and update their height, if the items are past rendered then maybe just discard all item heights past rendered, if the items are before rendered then maybe ignore and it will jump on scroll up which is kinda acceptable. -->
 
+1.11.0 / 19.01.2023
+==================
+
+* Added a new property on `<VirtualScroller/>` — `getInitialItemState(item)`. The same option was added in `VirtualScroller` constructor parameters.
+
+* Deprecated `itemIndex` property of `itemComponent`. The rationale is that setting new `items` on a React component is an asynchronous operation, so when a user obtains `itemIndex`, they don't know which `items` list does that index correspond to, therefore making it useless, or even buggy if used incorreclty.
+
+* (React) Renamed `itemComponent`'s `onStateChange()` property to `setState()`. The older property name still works but is considered deprecated.
+
+* Renamed `VirtualScroller`'s `onItemStateChange()` instance method to `setItemState()`. The older instance method name still works but is considered deprecated.
+
+* (TypeScript) Added a new (second or third) "generic" parameter (interface) called `ItemState` which is `undefined` by default. Removed the previously exported type called `ItemState` which was defined as `any | undefined`.
+  * (React) The addition of the new "generic" parameter has changed the order of generic parameters in the `<VirtualScroller/>` React component from `<Item, ItemComponentProps, AsElement>` to `<ItemComponentProps, Item, ItemState, AsElement>`.
+
+* (miscellaneous) In README, when describing `VirtualScroller` state, `itemStates` and `itemHeights` properties were previously marked as "optional" for some unknown reason. They've been properly marked as "required" now.
+
 1.10.1 / 07.01.2023
@@ -4,0 +20,0 @@ ==================

commonjs/DOM/VirtualScroller.js

@@ -180,2 +180,7 @@ "use strict";
     }
+  }, {
+    key: "setItemState",
+    value: function setItemState(i, newState) {
+      this.virtualScroller.setItemState(i, newState);
+    }
     /**
@@ -182,0 +187,0 @@ * @deprecated

commonjs/ItemHeights.js

@@ -211,3 +211,3 @@ "use strict";
           if (previousHeight !== _height) {
-            (0, _debug.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.
+            (0, _debug.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 `setItemState(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 `setItemState(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.
 
@@ -214,0 +214,0 @@ this._set(i, _height);

commonjs/react/useVirtualScroller.js

@@ -35,2 +35,3 @@ "use strict";
       initialState = _ref.initialState,
+      getInitialItemState = _ref.getInitialItemState,
       onStateChange = _ref.onStateChange;
@@ -65,5 +66,5 @@ var container = _ref2.container;
       getItemId: getItemId
-    }, _defineProperty(_VirtualScroller, "tbody", AsComponent === 'tbody'), _defineProperty(_VirtualScroller, "state", initialState), _defineProperty(_VirtualScroller, "onStateChange", onStateChange), _VirtualScroller));
+    }, _defineProperty(_VirtualScroller, "tbody", AsComponent === 'tbody'), _defineProperty(_VirtualScroller, "state", initialState), _defineProperty(_VirtualScroller, "getInitialItemState", getInitialItemState), _defineProperty(_VirtualScroller, "onStateChange", onStateChange), _VirtualScroller));
   }, []);
 }
 //# sourceMappingURL=useVirtualScroller.js.map

commonjs/react/VirtualScroller.js

@@ -24,3 +24,3 @@ "use strict";
 
-var _useOnItemStateChange = _interopRequireDefault(require("./useOnItemStateChange.js"));
+var _useSetItemState = _interopRequireDefault(require("./useSetItemState.js"));
 
@@ -35,3 +35,3 @@ var _useOnItemHeightChange = _interopRequireDefault(require("./useOnItemHeightChange.js"));
 
-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"];
+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"];
 
@@ -75,2 +75,3 @@ function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { "default": obj }; }
       initialState = _ref.initialState,
+      getInitialItemState = _ref.getInitialItemState,
       rest = _objectWithoutProperties(_ref, _excluded);
@@ -105,2 +106,3 @@
     initialState: initialState,
+    getInitialItemState: getInitialItemState,
     onStateChange: onStateChange
@@ -141,7 +143,7 @@ }, {
       getItemKey = _useItemKeys.getItemKey,
-      updateItemKeysForNewItems = _useItemKeys.updateItemKeysForNewItems; // Cache per-item `onItemStateChange` functions' "references"
+      updateItemKeysForNewItems = _useItemKeys.updateItemKeysForNewItems; // Cache per-item `setItemState` functions' "references"
   // so that item components don't get re-rendered needlessly.
 
 
-  var getOnItemStateChange = (0, _useOnItemStateChange["default"])({
+  var getSetItemState = (0, _useSetItemState["default"])({
     items: items,
@@ -211,6 +213,17 @@ virtualScroller: virtualScroller
     if (i >= firstShownItemIndex && i <= lastShownItemIndex) {
-      // Passing `item` as `children` property is legacy and is deprecated.
-      // If version `2.x` is published in some hypothetical future,
-      // the `item` and `itemIndex` properties should be moved below
-      // `{...itemComponentProps}`.
+      // * Passing `item` as `children` property is legacy and is deprecated.
+      //   If version `2.x` is published in some hypothetical future,
+      //   the `item` and `itemIndex` properties should be moved below
+      //   `{...itemComponentProps}`.
+      //
+      // * Passing `itemIndex` property is legacy and is deprecated.
+      //   The rationale is that setting new `items` on a React component
+      //   is an asynchronous operation, so when a user obtains `itemIndex`,
+      //   they don't know which `items` list does that index correspond to,
+      //   therefore making it useless, or even buggy if used incorreclty.
+      //
+      // * Passing `onStateChange` property for legacy reasons.
+      //   The new property name is `setState`.
+      //   The old property name `onStateChange` is deprecated.
+      //
       return /*#__PURE__*/_react["default"].createElement(Component, _extends({
@@ -222,3 +235,4 @@ item: item,
         state: itemStates && itemStates[i],
-        onStateChange: getOnItemStateChange(i),
+        setState: getSetItemState(i),
+        onStateChange: getSetItemState(i),
         onHeightChange: getOnItemHeightChange(i)
@@ -274,3 +288,3 @@ }), item);
     items: _propTypes["default"].arrayOf(_propTypes["default"].object).isRequired,
-    itemStates: _propTypes["default"].arrayOf(_propTypes["default"].any),
+    itemStates: _propTypes["default"].arrayOf(_propTypes["default"].any).isRequired,
     firstShownItemIndex: _propTypes["default"].number.isRequired,
@@ -283,3 +297,4 @@ lastShownItemIndex: _propTypes["default"].number.isRequired,
     verticalSpacing: _propTypes["default"].number
-  })
+  }),
+  getInitialItemState: _propTypes["default"].func
 };
@@ -286,0 +301,0 @@ VirtualScroller.defaultProps = {

commonjs/VirtualScroller.constructor.js

@@ -60,2 +60,4 @@ "use strict";
       state = options.state,
+      _options$getInitialIt = options.getInitialItemState,
+      getInitialItemState = _options$getInitialIt === void 0 ? function () {} : _options$getInitialIt,
       onStateChange = options.onStateChange,
@@ -213,2 +215,3 @@ initialScrollPosition = options.initialScrollPosition,
     state: state,
+    getInitialItemState: getInitialItemState,
     onStateChange: onStateChange,
@@ -215,0 +218,0 @@ render: render,

commonjs/VirtualScroller.items.js

@@ -14,2 +14,4 @@ "use strict";
 
+var _fillArray = _interopRequireDefault(require("./utility/fillArray.js"));
+
 function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { "default": obj }; }
@@ -101,8 +103,6 @@
         itemHeights = new Array(prependedItemsCount).concat(itemHeights);
+        itemStates = (0, _fillArray["default"])(new Array(prependedItemsCount), function (i) {
+          return _this.getInitialItemState(newItems[i]);
+        }).concat(itemStates); // Restore scroll position after prepending items (if requested).
 
-        if (itemStates) {
-          itemStates = new Array(prependedItemsCount).concat(itemStates);
-        } // Restore scroll position after prepending items (if requested).
-
-
         if (shouldRestoreScrollPosition) {
@@ -151,6 +151,5 @@ (0, _debug["default"])('Will restore scroll position');
         itemHeights = itemHeights.concat(new Array(appendedItemsCount));
-
-        if (itemStates) {
-          itemStates = itemStates.concat(new Array(appendedItemsCount));
-        }
+        itemStates = itemStates.concat((0, _fillArray["default"])(new Array(appendedItemsCount), function (i) {
+          return _this.getInitialItemState(newItems[prependedItemsCount + previousItems.length + i]);
+        }));
       }
@@ -168,3 +167,5 @@
       itemHeights = new Array(newItems.length);
-      itemStates = new Array(newItems.length);
+      itemStates = (0, _fillArray["default"])(new Array(newItems.length), function (i) {
+        return _this.getInitialItemState(newItems[i]);
+      });
       layoutUpdate = _this.layout.getInitialLayoutValues({
@@ -171,0 +172,0 @@ itemsCount: newItems.length,

commonjs/VirtualScroller.js

@@ -251,7 +251,14 @@ "use strict";
   }, {
+    key: "setItemState",
+    value: function setItemState(i, newItemState) {
+      this.hasToBeStarted();
+
+      this._setItemState(i, newItemState);
+    } // (deprecated)
+    // Use `.setItemState()` method name instead.
+
+  }, {
     key: "onItemStateChange",
     value: function onItemStateChange(i, newItemState) {
-      this.hasToBeStarted();
-
-      this._onItemStateChange(i, newItemState);
+      this.setItemState(i, newItemState);
     }
@@ -258,0 +265,0 @@ /**

commonjs/VirtualScroller.layout.js

@@ -125,3 +125,3 @@ "use strict";
     // from what has been initially measured in `this.itemHeights[i]`,
-    // if the developer didn't call `.onItemStateChange()` and `.onItemHeightChange(i)`.
+    // if the developer didn't call `.setItemState(i, newState)` and `.onItemHeightChange(i)`.
 
@@ -285,3 +285,3 @@
    * from what has been initially measured in `this.itemHeights[i]`,
-   * if the developer didn't call `.onItemStateChange()` and `.onItemHeightChange(i)`.
+   * if the developer didn't call `.setItemState(i, newState)` and `.onItemHeightChange(i)`.
    */
@@ -288,0 +288,0 @@

commonjs/VirtualScroller.state.js

@@ -10,2 +10,4 @@ "use strict";
 
+var _fillArray = _interopRequireDefault(require("./utility/fillArray.js"));
+
 var _debug = _interopRequireWildcard(require("./utility/debug.js"));
@@ -17,4 +19,2 @@
 
-function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { "default": obj }; }
-
 function _getRequireWildcardCache(nodeInterop) { if (typeof WeakMap !== "function") return null; var cacheBabelInterop = new WeakMap(); var cacheNodeInterop = new WeakMap(); return (_getRequireWildcardCache = function _getRequireWildcardCache(nodeInterop) { return nodeInterop ? cacheNodeInterop : cacheBabelInterop; })(nodeInterop); }
@@ -24,2 +24,4 @@
 
+function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { "default": obj }; }
+
 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; }
@@ -55,3 +57,4 @@
 
-  var state = _ref.state,
+  var initialState = _ref.state,
+      getInitialItemState = _ref.getInitialItemState,
       onStateChange = _ref.onStateChange,
@@ -62,4 +65,5 @@ render = _ref.render,
   this._render = render;
+  this.getInitialItemState = getInitialItemState;
 
-  this._onItemStateChange = function (i, newItemState) {
+  this._setItemState = function (i, newItemState) {
     if ((0, _debug.isDebug)()) {
@@ -114,7 +118,9 @@ (0, _debug["default"])('~ Item state changed ~');
   this.getInitialState = function () {
-    if (state) {
-      return getRestoredState.call(_this, state);
+    if (initialState) {
+      return getRestoredState.call(_this, initialState);
     }
 
-    return getInitialStateFromScratch.call(_this);
+    return getInitialStateFromScratch.call(_this, {
+      getInitialItemState: getInitialItemState
+    });
   };
@@ -184,2 +190,3 @@
    * (i.e. not from a previously saved one).
+   * @param {function} [options.getInitialItemState] — Gets initial item state.
    * @return {object}
@@ -189,3 +196,4 @@ */
 
-  function getInitialStateFromScratch() {
+  function getInitialStateFromScratch(_ref3) {
+    var getInitialItemState = _ref3.getInitialItemState;
     var items = initialItems;
@@ -197,3 +205,5 @@
       items: items,
-      itemStates: new Array(items.length)
+      itemStates: (0, _fillArray["default"])(new Array(items.length), function (i) {
+        return getInitialItemState(items[i]);
+      })
     });
@@ -260,6 +270,6 @@
 
-  function getInitialLayoutState(items, _ref3) {
+  function getInitialLayoutState(items, _ref4) {
     var _this2 = this;
 
-    var beforeStart = _ref3.beforeStart;
+    var beforeStart = _ref4.beforeStart;
     var itemsCount = items.length;
@@ -308,4 +318,4 @@
 
-  function isStateColumnsCountMismatch(state, _ref4) {
-    var columnsCount = _ref4.columnsCount;
+  function isStateColumnsCountMismatch(state, _ref5) {
+    var columnsCount = _ref5.columnsCount;
     var stateColumnsCount = state.columnsCount || 1;
@@ -312,0 +322,0 @@

dom/index.d.ts

@@ -1,9 +0,9 @@
-import { State, VirtualScrollerCommonOptions, SetItemsOptions } from '../index.d.ts';
+import { State, NoItemState, VirtualScrollerCommonOptions, SetItemsOptions } from '../index.d.ts';
 
-export { State, ItemState } from '../index.d.ts';
+export { State } from '../index.d.ts';
 
 import * as React from 'react';
 
-interface Options<Item> extends VirtualScrollerCommonOptions<Item> {
-	state?: State<Item>;
+interface Options<Item, ItemState> extends VirtualScrollerCommonOptions<Item, ItemState> {
+	state?: State<Item, ItemState>;
 	scrollableContainer?: HTMLElement;
@@ -13,3 +13,3 @@ onItemUnmount?(): void;
 
-export default class VirtualScroller<Item> {
+export default class VirtualScroller<Item, ItemState = NoItemState> {
 	constructor(
@@ -19,3 +19,3 @@ itemsContainerElement: HTMLElement,
 		renderItem: (item: Item) => HTMLElement,
-		options?: Options<Item>
+		options?: Options<Item, ItemState>
 	);
@@ -27,2 +27,3 @@
   onItemHeightChange(i: number): void;
+  setItemState(i: number, newState: ItemState): void;
 }

index.d.ts

 export type ItemHeight = number | undefined;
-export type ItemState = any | undefined;
+export type NoItemState = undefined;
 
@@ -10,3 +10,3 @@ interface BeforeResizeState {
 
-export interface State<Item> {
+export interface State<Item, ItemState> {
 	items: Item[];
@@ -53,5 +53,6 @@ firstShownItemIndex: number;
 
-export interface VirtualScrollerCommonOptions<Item> {
+export interface VirtualScrollerCommonOptions<Item, ItemState> {
 	bypass?: boolean;
-	onStateChange?(newState: State<Item>);
+	onStateChange?(newState: State<Item, ItemState>);
+	getInitialItemState?: (item: Item) => ItemState;
 	measureItemsBatchSize?: number;
@@ -67,5 +68,5 @@ getEstimatedItemHeight?: () => number;
 
-interface Options<Element, Item> extends VirtualScrollerCommonOptions<Item> {
-	state?: State<Item>;
-	render?(state: State<Item>, previousState?: State<Item>): void;
+interface Options<Element, Item, ItemState> extends VirtualScrollerCommonOptions<Item, ItemState> {
+	state?: State<Item, ItemState>;
+	render?(state: State<Item, ItemState>, previousState?: State<Item, ItemState>): void;
 	engine?: Engine<Element>;
@@ -77,5 +78,5 @@ tbody?: boolean;
 
-interface UseStateOptions<Item> {
-	getState?(): State<Item>;
-	updateState?(stateUpdate: Partial<State<Item>>): void;
+interface UseStateOptions<Item, ItemState> {
+	getState?(): State<Item, ItemState>;
+	updateState?(stateUpdate: Partial<State<Item, ItemState>>): void;
 }
@@ -87,7 +88,7 @@
 
-export default class VirtualScroller<Element, Item> {
+export default class VirtualScroller<Element, Item, ItemState> {
 	constructor(
 		getItemsContainerElement: () => Element,
 		items: Item[],
-		options?: Options<Element, Item>
+		options?: Options<Element, Item, ItemState>
 	);
@@ -101,6 +102,6 @@
   onItemHeightChange(i: number): void;
-  onItemStateChange(i: number, itemState?: object): void;
+  setItemState(i: number, itemState?: object): void;
   getItemScrollPosition(i: number): number | undefined;
-  getInitialState(): State<Item>;
-  useState(options: UseStateOptions<Item>): void;
+  getInitialState(): State<Item, ItemState>;
+  useState(options: UseStateOptions<Item, ItemState>): void;
 }

modules/DOM/VirtualScroller.js

@@ -163,2 +163,7 @@ var _excluded = ["onMount", "onItemUnmount"];
     }
+  }, {
+    key: "setItemState",
+    value: function setItemState(i, newState) {
+      this.virtualScroller.setItemState(i, newState);
+    }
     /**
@@ -165,0 +170,0 @@ * @deprecated

modules/ItemHeights.js

@@ -198,3 +198,3 @@ function _classCallCheck(instance, Constructor) { if (!(instance instanceof Constructor)) { throw new TypeError("Cannot call a class as a function"); } }
           if (previousHeight !== _height) {
-            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.
+            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 `setItemState(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 `setItemState(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.
 
@@ -201,0 +201,0 @@ this._set(i, _height);

modules/react/useVirtualScroller.js

@@ -24,2 +24,3 @@ function _defineProperty(obj, key, value) { if (key in obj) { Object.defineProperty(obj, key, { value: value, enumerable: true, configurable: true, writable: true }); } else { obj[key] = value; } return obj; }
       initialState = _ref.initialState,
+      getInitialItemState = _ref.getInitialItemState,
       onStateChange = _ref.onStateChange;
@@ -54,5 +55,5 @@ var container = _ref2.container;
       getItemId: getItemId
-    }, _defineProperty(_VirtualScroller, "tbody", AsComponent === 'tbody'), _defineProperty(_VirtualScroller, "state", initialState), _defineProperty(_VirtualScroller, "onStateChange", onStateChange), _VirtualScroller));
+    }, _defineProperty(_VirtualScroller, "tbody", AsComponent === 'tbody'), _defineProperty(_VirtualScroller, "state", initialState), _defineProperty(_VirtualScroller, "getInitialItemState", getInitialItemState), _defineProperty(_VirtualScroller, "onStateChange", onStateChange), _VirtualScroller));
   }, []);
 }
 //# sourceMappingURL=useVirtualScroller.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"];
+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"];
 
@@ -16,3 +16,3 @@ 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); }
 import useItemKeys from './useItemKeys.js';
-import useOnItemStateChange from './useOnItemStateChange.js';
+import useSetItemState from './useSetItemState.js';
 import useOnItemHeightChange from './useOnItemHeightChange.js';
@@ -48,2 +48,3 @@ import useHandleItemsChange from './useHandleItemsChange.js';
       initialState = _ref.initialState,
+      getInitialItemState = _ref.getInitialItemState,
       rest = _objectWithoutProperties(_ref, _excluded);
@@ -78,2 +79,3 @@
     initialState: initialState,
+    getInitialItemState: getInitialItemState,
     onStateChange: onStateChange
@@ -114,7 +116,7 @@ }, {
       getItemKey = _useItemKeys.getItemKey,
-      updateItemKeysForNewItems = _useItemKeys.updateItemKeysForNewItems; // Cache per-item `onItemStateChange` functions' "references"
+      updateItemKeysForNewItems = _useItemKeys.updateItemKeysForNewItems; // Cache per-item `setItemState` functions' "references"
   // so that item components don't get re-rendered needlessly.
 
 
-  var getOnItemStateChange = useOnItemStateChange({
+  var getSetItemState = useSetItemState({
     items: items,
@@ -184,6 +186,17 @@ virtualScroller: virtualScroller
     if (i >= firstShownItemIndex && i <= lastShownItemIndex) {
-      // Passing `item` as `children` property is legacy and is deprecated.
-      // If version `2.x` is published in some hypothetical future,
-      // the `item` and `itemIndex` properties should be moved below
-      // `{...itemComponentProps}`.
+      // * Passing `item` as `children` property is legacy and is deprecated.
+      //   If version `2.x` is published in some hypothetical future,
+      //   the `item` and `itemIndex` properties should be moved below
+      //   `{...itemComponentProps}`.
+      //
+      // * Passing `itemIndex` property is legacy and is deprecated.
+      //   The rationale is that setting new `items` on a React component
+      //   is an asynchronous operation, so when a user obtains `itemIndex`,
+      //   they don't know which `items` list does that index correspond to,
+      //   therefore making it useless, or even buggy if used incorreclty.
+      //
+      // * Passing `onStateChange` property for legacy reasons.
+      //   The new property name is `setState`.
+      //   The old property name `onStateChange` is deprecated.
+      //
       return /*#__PURE__*/React.createElement(Component, _extends({
@@ -195,3 +208,4 @@ item: item,
         state: itemStates && itemStates[i],
-        onStateChange: getOnItemStateChange(i),
+        setState: getSetItemState(i),
+        onStateChange: getSetItemState(i),
         onHeightChange: getOnItemHeightChange(i)
@@ -244,3 +258,3 @@ }), item);
     items: PropTypes.arrayOf(PropTypes.object).isRequired,
-    itemStates: PropTypes.arrayOf(PropTypes.any),
+    itemStates: PropTypes.arrayOf(PropTypes.any).isRequired,
     firstShownItemIndex: PropTypes.number.isRequired,
@@ -253,3 +267,4 @@ lastShownItemIndex: PropTypes.number.isRequired,
     verticalSpacing: PropTypes.number
-  })
+  }),
+  getInitialItemState: PropTypes.func
 };
@@ -256,0 +271,0 @@ VirtualScroller.defaultProps = {

modules/VirtualScroller.constructor.js

@@ -30,2 +30,4 @@ import { supportsTbody, BROWSER_NOT_SUPPORTED_ERROR } from './DOM/tbody.js';
       state = options.state,
+      _options$getInitialIt = options.getInitialItemState,
+      getInitialItemState = _options$getInitialIt === void 0 ? function () {} : _options$getInitialIt,
       onStateChange = options.onStateChange,
@@ -183,2 +185,3 @@ initialScrollPosition = options.initialScrollPosition,
     state: state,
+    getInitialItemState: getInitialItemState,
     onStateChange: onStateChange,
@@ -185,0 +188,0 @@ render: render,

modules/VirtualScroller.items.js

@@ -9,2 +9,3 @@ 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; }
 import getItemsDiff from './getItemsDiff.js';
+import fillArray from './utility/fillArray.js';
 export default function () {
@@ -84,8 +85,6 @@ var _this = this;
         itemHeights = new Array(prependedItemsCount).concat(itemHeights);
+        itemStates = fillArray(new Array(prependedItemsCount), function (i) {
+          return _this.getInitialItemState(newItems[i]);
+        }).concat(itemStates); // Restore scroll position after prepending items (if requested).
 
-        if (itemStates) {
-          itemStates = new Array(prependedItemsCount).concat(itemStates);
-        } // Restore scroll position after prepending items (if requested).
-
-
         if (shouldRestoreScrollPosition) {
@@ -134,6 +133,5 @@ log('Will restore scroll position');
         itemHeights = itemHeights.concat(new Array(appendedItemsCount));
-
-        if (itemStates) {
-          itemStates = itemStates.concat(new Array(appendedItemsCount));
-        }
+        itemStates = itemStates.concat(fillArray(new Array(appendedItemsCount), function (i) {
+          return _this.getInitialItemState(newItems[prependedItemsCount + previousItems.length + i]);
+        }));
       }
@@ -151,3 +149,5 @@
       itemHeights = new Array(newItems.length);
-      itemStates = new Array(newItems.length);
+      itemStates = fillArray(new Array(newItems.length), function (i) {
+        return _this.getInitialItemState(newItems[i]);
+      });
       layoutUpdate = _this.layout.getInitialLayoutValues({
@@ -154,0 +154,0 @@ itemsCount: newItems.length,

modules/VirtualScroller.js

@@ -239,7 +239,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; }
   }, {
+    key: "setItemState",
+    value: function setItemState(i, newItemState) {
+      this.hasToBeStarted();
+
+      this._setItemState(i, newItemState);
+    } // (deprecated)
+    // Use `.setItemState()` method name instead.
+
+  }, {
     key: "onItemStateChange",
     value: function onItemStateChange(i, newItemState) {
-      this.hasToBeStarted();
-
-      this._onItemStateChange(i, newItemState);
+      this.setItemState(i, newItemState);
     }
@@ -246,0 +253,0 @@ /**

modules/VirtualScroller.layout.js

@@ -113,3 +113,3 @@ 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; }
     // from what has been initially measured in `this.itemHeights[i]`,
-    // if the developer didn't call `.onItemStateChange()` and `.onItemHeightChange(i)`.
+    // if the developer didn't call `.setItemState(i, newState)` and `.onItemHeightChange(i)`.
 
@@ -273,3 +273,3 @@
    * from what has been initially measured in `this.itemHeights[i]`,
-   * if the developer didn't call `.onItemStateChange()` and `.onItemHeightChange(i)`.
+   * if the developer didn't call `.setItemState(i, newState)` and `.onItemHeightChange(i)`.
    */
@@ -276,0 +276,0 @@

modules/VirtualScroller.state.js

@@ -7,2 +7,3 @@ 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; }
 
+import fillArray from './utility/fillArray.js';
 import log, { warn, isDebug, reportError } from './utility/debug.js';
@@ -35,3 +36,4 @@ import { cleanUpBeforeResizeState } from './BeforeResize.js';
 
-  var state = _ref.state,
+  var initialState = _ref.state,
+      getInitialItemState = _ref.getInitialItemState,
       onStateChange = _ref.onStateChange,
@@ -42,4 +44,5 @@ render = _ref.render,
   this._render = render;
+  this.getInitialItemState = getInitialItemState;
 
-  this._onItemStateChange = function (i, newItemState) {
+  this._setItemState = function (i, newItemState) {
     if (isDebug()) {
@@ -94,7 +97,9 @@ log('~ Item state changed ~');
   this.getInitialState = function () {
-    if (state) {
-      return getRestoredState.call(_this, state);
+    if (initialState) {
+      return getRestoredState.call(_this, initialState);
     }
 
-    return getInitialStateFromScratch.call(_this);
+    return getInitialStateFromScratch.call(_this, {
+      getInitialItemState: getInitialItemState
+    });
   };
@@ -164,2 +169,3 @@
    * (i.e. not from a previously saved one).
+   * @param {function} [options.getInitialItemState] — Gets initial item state.
    * @return {object}
@@ -169,3 +175,4 @@ */
 
-  function getInitialStateFromScratch() {
+  function getInitialStateFromScratch(_ref3) {
+    var getInitialItemState = _ref3.getInitialItemState;
     var items = initialItems;
@@ -177,3 +184,5 @@
       items: items,
-      itemStates: new Array(items.length)
+      itemStates: fillArray(new Array(items.length), function (i) {
+        return getInitialItemState(items[i]);
+      })
     });
@@ -240,6 +249,6 @@
 
-  function getInitialLayoutState(items, _ref3) {
+  function getInitialLayoutState(items, _ref4) {
     var _this2 = this;
 
-    var beforeStart = _ref3.beforeStart;
+    var beforeStart = _ref4.beforeStart;
     var itemsCount = items.length;
@@ -288,4 +297,4 @@
 
-  function isStateColumnsCountMismatch(state, _ref4) {
-    var columnsCount = _ref4.columnsCount;
+  function isStateColumnsCountMismatch(state, _ref5) {
+    var columnsCount = _ref5.columnsCount;
     var stateColumnsCount = state.columnsCount || 1;
@@ -292,0 +301,0 @@

package.json

 {
   "name": "virtual-scroller",
-  "version": "1.10.2",
+  "version": "1.11.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, VirtualScrollerCommonOptions } from '../index.d.ts';
+import { State, NoItemState, VirtualScrollerCommonOptions } from '../index.d.ts';
 
-export { State, ItemState } from '../index.d.ts';
+export { State } from '../index.d.ts';
 
@@ -51,8 +51,14 @@ import * as React from 'react';
 
-interface Props<Item, ItemComponentProps extends object>
-	extends VirtualScrollerCommonOptions<Item>{
+interface ItemComponentPassedProps<Item, ItemState> {
+	item: Item;
+	state: ItemState;
+	setState: (newState: ItemState) => void;
+	onHeightChange: () => void;
+}
+
+interface Props<ItemComponentProps extends object, Item, ItemState> extends VirtualScrollerCommonOptions<Item, ItemState> {
 	items: Item[];
-	itemComponent: React.ElementType<ItemComponentProps & { item: Item, itemIndex: number }>;
+	itemComponent: React.ElementType<ItemComponentProps & ItemComponentPassedProps<Item, ItemState>>;
 	itemComponentProps?: ItemComponentProps;
-	initialState?: State<Item>;
+	initialState?: State<Item, ItemState>;
 	preserveScrollPositionOnPrependItems?: boolean;
@@ -63,6 +69,6 @@
 
-declare function VirtualScroller<Item = any, ItemComponentProps extends object={}, AsElement extends React.ElementType = 'div'>(
-	props: PolymorphicComponentProps<AsElement, Props<Item, ItemComponentProps>>
+declare function VirtualScroller<ItemComponentProps extends object = {}, Item = any, ItemState = NoItemState, AsElement extends React.ElementType = 'div'>(
+	props: PolymorphicComponentProps<AsElement, Props<ItemComponentProps, Item, ItemState>>
 ): JSX.Element;
 
 export default VirtualScroller;

source/DOM/VirtualScroller.js

@@ -148,2 +148,6 @@ import VirtualScrollerCore from '../VirtualScroller.js'
 
+  setItemState(i, newState) {
+    this.virtualScroller.setItemState(i, newState)
+  }
+
   /**
@@ -150,0 +154,0 @@ * @deprecated

source/ItemHeights.js

@@ -172,3 +172,3 @@ import log, { warn, isDebug, reportError } from './utility/debug.js'
 				if (previousHeight !== height) {
-					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.')
+					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 `setItemState(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 `setItemState(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.
@@ -175,0 +175,0 @@ this._set(i, height)

source/react/useVirtualScroller.js

@@ -29,2 +29,3 @@ import { useMemo } from 'react'
 	initialState,
+	getInitialItemState,
 	onStateChange
@@ -62,2 +63,3 @@ }, {
 				state: initialState,
+				getInitialItemState,
 				onStateChange
@@ -64,0 +66,0 @@ }

source/react/VirtualScroller.js

@@ -9,3 +9,3 @@ import React, { useRef, useMemo, useLayoutEffect } from 'react'
 import useItemKeys from './useItemKeys.js'
-import useOnItemStateChange from './useOnItemStateChange.js'
+import useSetItemState from './useSetItemState.js'
 import useOnItemHeightChange from './useOnItemHeightChange.js'
@@ -48,2 +48,3 @@ import useHandleItemsChange from './useHandleItemsChange.js'
 	initialState,
+	getInitialItemState,
 	...rest
@@ -79,2 +80,3 @@ }, ref) {
 		initialState,
+		getInitialItemState,
 		onStateChange
@@ -122,5 +124,5 @@ }, {
 
-	// Cache per-item `onItemStateChange` functions' "references"
+	// Cache per-item `setItemState` functions' "references"
 	// so that item components don't get re-rendered needlessly.
-	const getOnItemStateChange = useOnItemStateChange({
+	const getSetItemState = useSetItemState({
 		items,
@@ -200,6 +202,17 @@ virtualScroller
 				if (i >= firstShownItemIndex && i <= lastShownItemIndex) {
-					// Passing `item` as `children` property is legacy and is deprecated.
-					// If version `2.x` is published in some hypothetical future,
-					// the `item` and `itemIndex` properties should be moved below
-					// `{...itemComponentProps}`.
+					// * Passing `item` as `children` property is legacy and is deprecated.
+					//   If version `2.x` is published in some hypothetical future,
+					//   the `item` and `itemIndex` properties should be moved below
+					//   `{...itemComponentProps}`.
+					//
+					// * Passing `itemIndex` property is legacy and is deprecated.
+					//   The rationale is that setting new `items` on a React component
+					//   is an asynchronous operation, so when a user obtains `itemIndex`,
+					//   they don't know which `items` list does that index correspond to,
+					//   therefore making it useless, or even buggy if used incorreclty.
+					//
+					// * Passing `onStateChange` property for legacy reasons.
+					//   The new property name is `setState`.
+					//   The old property name `onStateChange` is deprecated.
+					//
 					return (
@@ -212,3 +225,4 @@ <Component
 							state={itemStates && itemStates[i]}
-							onStateChange={getOnItemStateChange(i)}
+							setState={getSetItemState(i)}
+							onStateChange={getSetItemState(i)}
 							onHeightChange={getOnItemHeightChange(i)}>
@@ -271,3 +285,3 @@ {item}
 		items: PropTypes.arrayOf(PropTypes.object).isRequired,
-		itemStates: PropTypes.arrayOf(PropTypes.any),
+		itemStates: PropTypes.arrayOf(PropTypes.any).isRequired,
 		firstShownItemIndex: PropTypes.number.isRequired,
@@ -280,3 +294,4 @@ lastShownItemIndex: PropTypes.number.isRequired,
 		verticalSpacing: PropTypes.number
-	})
+	}),
+	getInitialItemState: PropTypes.func
 }
@@ -283,0 +298,0 @@

source/VirtualScroller.constructor.js

@@ -39,2 +39,3 @@ import {
 		state,
+		getInitialItemState = () => {},
 		onStateChange,
@@ -189,3 +190,3 @@ initialScrollPosition,
 
-	createStateHelpers.call(this, { state, onStateChange, render, items })
+	createStateHelpers.call(this, { state, getInitialItemState, onStateChange, render, items })
 
@@ -192,0 +193,0 @@ createVerticalSpacingHelpers.call(this)

source/VirtualScroller.items.js

 import log, { isDebug } from './utility/debug.js'
 import getItemsDiff from './getItemsDiff.js'
+import fillArray from './utility/fillArray.js'
 
@@ -84,7 +85,8 @@ export default function() {
 				itemHeights = new Array(prependedItemsCount).concat(itemHeights)
+				itemStates = fillArray(
+					new Array(prependedItemsCount),
+					(i) => this.getInitialItemState(newItems[i])
+				)
+					.concat(itemStates)
 
-				if (itemStates) {
-					itemStates = new Array(prependedItemsCount).concat(itemStates)
-				}
-
 				// Restore scroll position after prepending items (if requested).
@@ -130,5 +132,8 @@ if (shouldRestoreScrollPosition) {
 				itemHeights = itemHeights.concat(new Array(appendedItemsCount))
-				if (itemStates) {
-					itemStates = itemStates.concat(new Array(appendedItemsCount))
-				}
+				itemStates = itemStates.concat(
+					fillArray(
+						new Array(appendedItemsCount),
+						(i) => this.getInitialItemState(newItems[prependedItemsCount + previousItems.length + i])
+					)
+				)
 			}
@@ -147,3 +152,6 @@
 			itemHeights = new Array(newItems.length)
-			itemStates = new Array(newItems.length)
+			itemStates = fillArray(
+				new Array(newItems.length),
+				(i) => this.getInitialItemState(newItems[i])
+			)
 
@@ -150,0 +158,0 @@ layoutUpdate = this.layout.getInitialLayoutValues({

source/VirtualScroller.js

@@ -222,7 +222,13 @@ import VirtualScrollerConstructor from './VirtualScroller.constructor.js'
 	 */
-	onItemStateChange(i, newItemState) {
+	setItemState(i, newItemState) {
 		this.hasToBeStarted()
-		this._onItemStateChange(i, newItemState)
+		this._setItemState(i, newItemState)
 	}
 
+	// (deprecated)
+	// Use `.setItemState()` method name instead.
+	onItemStateChange(i, newItemState) {
+		this.setItemState(i, newItemState)
+	}
+
 	/**
@@ -229,0 +235,0 @@ * Updates `items`. For example, can prepend or append new items to the list.

source/VirtualScroller.layout.js

@@ -102,3 +102,3 @@ // For some weird reason, in Chrome, `setTimeout()` would lag up to a second (or more) behind.
 		// from what has been initially measured in `this.itemHeights[i]`,
-		// if the developer didn't call `.onItemStateChange()` and `.onItemHeightChange(i)`.
+		// if the developer didn't call `.setItemState(i, newState)` and `.onItemHeightChange(i)`.
 		if (!validateWillBeHiddenItemHeightsAreAccurate.call(this, firstShownItemIndex, lastShownItemIndex)) {
@@ -273,3 +273,3 @@ log('~ Because some of the will-be-hidden item heights (listed above) have changed since they\'ve last been measured, redo layout. ~')
 	 * from what has been initially measured in `this.itemHeights[i]`,
-	 * if the developer didn't call `.onItemStateChange()` and `.onItemHeightChange(i)`.
+	 * if the developer didn't call `.setItemState(i, newState)` and `.onItemHeightChange(i)`.
 	 */
@@ -276,0 +276,0 @@ function validateWillBeHiddenItemHeightsAreAccurate(firstShownItemIndex, lastShownItemIndex) {

source/VirtualScroller.state.js

@@ -0,1 +1,2 @@
+import fillArray from './utility/fillArray.js'
 import log, { warn, isDebug, reportError } from './utility/debug.js'
@@ -28,3 +29,4 @@ import { cleanUpBeforeResizeState } from './BeforeResize.js'
 export default function createStateHelpers({
-	state,
+	state: initialState,
+	getInitialItemState,
 	onStateChange,
@@ -37,3 +39,5 @@ render,
 
-	this._onItemStateChange = (i, newItemState) => {
+	this.getInitialItemState = getInitialItemState
+
+	this._setItemState = (i, newItemState) => {
 		if (isDebug()) {
@@ -85,6 +89,6 @@ log('~ Item state changed ~')
 	this.getInitialState = () => {
-		if (state) {
-			return getRestoredState.call(this, state)
+		if (initialState) {
+			return getRestoredState.call(this, initialState)
 		}
-		return getInitialStateFromScratch.call(this)
+		return getInitialStateFromScratch.call(this, { getInitialItemState })
 	}
@@ -162,11 +166,14 @@
 	 * (i.e. not from a previously saved one).
+	 * @param {function} [options.getInitialItemState] — Gets initial item state.
 	 * @return {object}
 	 */
-	function getInitialStateFromScratch() {
+	function getInitialStateFromScratch({ getInitialItemState }) {
 		const items = initialItems
+
 		const state = {
 			...getInitialLayoutState.call(this, items, { beforeStart: true }),
 			items,
-			itemStates: new Array(items.length)
+			itemStates: fillArray(new Array(items.length), (i) => getInitialItemState(items[i]))
 		}
+
 		if (isDebug()) {
@@ -177,2 +184,3 @@ log('Initial state (autogenerated)', getStateSnapshot(state))
 		log('Last shown item index', state.lastShownItemIndex)
+
 		return state
@@ -179,0 +187,0 @@ }

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

3332605

increased by0.82%

Number of package files

299

increased by1.7%

Lines of code

20207

increased by0.82%

Number of lines in readme file

1078

increased by2.28%

No dependency changes