@itwin/itwinui-react 1.38.0 → 1.38.1

package/esm/core/utils/components/VirtualScroll.d.ts

@@ -16,6 +16,10 @@ export declare type VirtualScrollProps = {
      * @default 10
      */
     bufferSize?: number;
+    /**
+     * Index of the first element on initial render.
+     */
+    scrollToIndex?: number;
 } & React.ComponentPropsWithRef<'div'>;
 /**
  * `VirtualScroll` component is used to render a huge amount of items in the DOM. It renders only the ones which are visible
@@ -38,5 +42,35 @@ export declare type VirtualScrollProps = {
  * />
  * @private
  */
-export declare const VirtualScroll: React.ForwardRefExoticComponent<Pick<VirtualScrollProps, "key" | keyof React.HTMLAttributes<HTMLDivElement> | "itemsLength" | "itemRenderer" | "bufferSize"> & React.RefAttributes<HTMLDivElement>>;
+export declare const VirtualScroll: React.ForwardRefExoticComponent<Pick<VirtualScrollProps, "key" | keyof React.HTMLAttributes<HTMLDivElement> | "itemsLength" | "itemRenderer" | "bufferSize" | "scrollToIndex"> & React.RefAttributes<HTMLDivElement>>;
+/**
+ * `useVirtualization` is used for efficiently rendering only the visible rows from a large list.
+ * It returns `outerProps` and `innerProps`, which need to be applied on 2 container elements and `visibleChildren` which is a list of virtualized items.
+ * @example
+ * const itemRenderer = React.useCallback((index: number) => (
+ *  <li key={index}>
+ *    This is my item #{index}
+ *  </li>
+ * ), [])
+ *
+ * const { outerProps, innerProps, visibleChildren } = useVirtualization({itemsLength: 1000, itemRenderer: itemRenderer});
+ * return (
+ *  <div {...outerProps}>
+ *   <ul {...innerProps}>
+ *    {visibleChildren}
+ *   </ul>
+ *  </div>
+ * );
+ * @private
+ */
+export declare const useVirtualization: (props: VirtualScrollProps) => {
+    outerProps: React.HTMLAttributes<HTMLElement>;
+    innerProps: {
+        readonly style: {
+            readonly willChange: "transform";
+        };
+        readonly ref: (instance: HTMLElement | null) => void;
+    };
+    visibleChildren: JSX.Element[];
+};
 export default VirtualScroll;

package/esm/core/utils/components/VirtualScroll.js

@@ -25,6 +25,7 @@ var __rest = (this && this.__rest) || function (s, e) {
  * See LICENSE.md in the project root for license terms and full copyright notice.
  *--------------------------------------------------------------------------------------------*/
 import React from 'react';
+import { mergeRefs } from '../hooks';
 import { useResizeObserver } from '../hooks/useResizeObserver';
 var getScrollableParent = function (element, ownerDocument) {
     if (ownerDocument === void 0) { ownerDocument = document; }
@@ -46,6 +47,14 @@ var getElementHeight = function (element) {
     var _a;
     return (_a = element === null || element === void 0 ? void 0 : element.getBoundingClientRect().height) !== null && _a !== void 0 ? _a : 0;
 };
+var getElementHeightWithMargins = function (element) {
+    if (!element) {
+        return undefined;
+    }
+    var margin = parseFloat(getElementStyle(element, 'margin-top')) +
+        parseFloat(getElementStyle(element, 'margin-bottom'));
+    return getElementHeight(element) + (isNaN(margin) ? 0 : margin);
+};
 var getNumberOfNodesInHeight = function (childHeight, totalHeight) {
     if (!childHeight) {
         return 0;
@@ -53,7 +62,10 @@ var getNumberOfNodesInHeight = function (childHeight, totalHeight) {
     return Math.floor(totalHeight / childHeight);
 };
 var getTranslateValue = function (childHeight, startIndex) {
-    return childHeight * startIndex;
+    if (startIndex > 0) {
+        return childHeight * startIndex;
+    }
+    return 0;
 };
 var getVisibleNodeCount = function (childHeight, startIndex, childrenLength, scrollContainer) {
     return Math.min(childrenLength - startIndex, getNumberOfNodesInHeight(childHeight, getElementHeight(scrollContainer)));
@@ -79,21 +91,55 @@ var getVisibleNodeCount = function (childHeight, startIndex, childrenLength, scr
  * />
  * @private
  */
-export var VirtualScroll = React.forwardRef(function (_a, ref) {
-    var itemsLength = _a.itemsLength, itemRenderer = _a.itemRenderer, _b = _a.bufferSize, bufferSize = _b === void 0 ? 10 : _b, style = _a.style, rest = __rest(_a, ["itemsLength", "itemRenderer", "bufferSize", "style"]);
-    var _c = React.useState(0), startNode = _c[0], setStartNode = _c[1];
-    var _d = React.useState(0), visibleNodeCount = _d[0], setVisibleNodeCount = _d[1];
+export var VirtualScroll = React.forwardRef(function (props, ref) {
+    var _a = useVirtualization(props), innerProps = _a.innerProps, outerProps = _a.outerProps, visibleChildren = _a.visibleChildren;
+    return (React.createElement("div", __assign({}, outerProps, { ref: ref }),
+        React.createElement("div", __assign({}, innerProps), visibleChildren)));
+});
+/**
+ * `useVirtualization` is used for efficiently rendering only the visible rows from a large list.
+ * It returns `outerProps` and `innerProps`, which need to be applied on 2 container elements and `visibleChildren` which is a list of virtualized items.
+ * @example
+ * const itemRenderer = React.useCallback((index: number) => (
+ *  <li key={index}>
+ *    This is my item #{index}
+ *  </li>
+ * ), [])
+ *
+ * const { outerProps, innerProps, visibleChildren } = useVirtualization({itemsLength: 1000, itemRenderer: itemRenderer});
+ * return (
+ *  <div {...outerProps}>
+ *   <ul {...innerProps}>
+ *    {visibleChildren}
+ *   </ul>
+ *  </div>
+ * );
+ * @private
+ */
+export var useVirtualization = function (props) {
+    var itemsLength = props.itemsLength, itemRenderer = props.itemRenderer, _a = props.bufferSize, bufferSize = _a === void 0 ? 10 : _a, scrollToIndex = props.scrollToIndex, style = props.style, rest = __rest(props, ["itemsLength", "itemRenderer", "bufferSize", "scrollToIndex", "style"]);
+    var _b = React.useState(0), startNode = _b[0], setStartNode = _b[1];
+    var _c = React.useState(0), visibleNodeCount = _c[0], setVisibleNodeCount = _c[1];
     var scrollContainer = React.useRef();
     var parentRef = React.useRef(null);
-    var childHeight = React.useRef(0);
+    var childHeight = React.useRef({ first: 0, middle: 0, last: 0 });
     var onScrollRef = React.useRef();
     // Used only to recalculate on resize
-    var _e = React.useState(0), scrollContainerHeight = _e[0], setScrollContainerHeight = _e[1];
+    var _d = React.useState(0), scrollContainerHeight = _d[0], setScrollContainerHeight = _d[1];
+    var visibleIndex = React.useRef({ start: 0, end: 0 });
+    // Used to mark when scroll container has height (updated by resize observer)
+    // because before that calculations are not right
+    var _e = React.useState(false), isMounted = _e[0], setIsMounted = _e[1];
     var onResize = React.useCallback(function (_a) {
         var height = _a.height;
+        // Initial value returned by resize observer is 0
+        // So wait for the next one
+        if (height > 0) {
+            setIsMounted(true);
+        }
         setScrollContainerHeight(height);
     }, []);
-    var resizeRef = useResizeObserver(onResize)[0];
+    var _f = useResizeObserver(onResize), resizeRef = _f[0], resizeObserver = _f[1];
     // Find scrollable parent
     // Needed only on init
     React.useLayoutEffect(function () {
@@ -102,6 +148,14 @@ export var VirtualScroll = React.forwardRef(function (_a, ref) {
         scrollContainer.current = scrollableParent;
         resizeRef(scrollableParent);
     }, [resizeRef]);
+    // Stop watching resize, when virtual scroll is unmounted
+    React.useLayoutEffect(function () {
+        return function () { return resizeObserver === null || resizeObserver === void 0 ? void 0 : resizeObserver.disconnect(); };
+    }, [resizeObserver]);
+    var getScrollableContainer = function () {
+        var _a, _b;
+        return (_a = scrollContainer.current) !== null && _a !== void 0 ? _a : (_b = parentRef.current) === null || _b === void 0 ? void 0 : _b.ownerDocument.scrollingElement;
+    };
     var visibleChildren = React.useMemo(function () {
         var arr = [];
         var endIndex = Math.min(itemsLength, startNode + visibleNodeCount + bufferSize * 2);
@@ -112,27 +166,42 @@ export var VirtualScroll = React.forwardRef(function (_a, ref) {
     }, [itemsLength, itemRenderer, bufferSize, startNode, visibleNodeCount]);
     // Get child height when children available
     React.useLayoutEffect(function () {
+        var _a, _b, _c, _d, _e, _f;
         if (!parentRef.current || !visibleChildren.length) {
             return;
         }
         var firstChild = parentRef.current.children.item(0);
-        childHeight.current = Number(getElementHeight(firstChild).toFixed(2));
+        var secondChild = parentRef.current.children.item(1);
+        var lastChild = parentRef.current.children.item(parentRef.current.children.length - 1);
+        var firstChildHeight = Number((_b = (_a = getElementHeightWithMargins(firstChild)) === null || _a === void 0 ? void 0 : _a.toFixed(2)) !== null && _b !== void 0 ? _b : 0);
+        childHeight.current = {
+            first: firstChildHeight,
+            middle: Number((_d = (_c = getElementHeightWithMargins(secondChild)) === null || _c === void 0 ? void 0 : _c.toFixed(2)) !== null && _d !== void 0 ? _d : firstChildHeight),
+            last: Number((_f = (_e = getElementHeightWithMargins(lastChild)) === null || _e === void 0 ? void 0 : _e.toFixed(2)) !== null && _f !== void 0 ? _f : firstChildHeight),
+        };
     }, [visibleChildren.length]);
     var updateVirtualScroll = React.useCallback(function () {
-        var _a, _b;
-        var scrollableContainer = (_a = scrollContainer.current) !== null && _a !== void 0 ? _a : (_b = parentRef.current) === null || _b === void 0 ? void 0 : _b.ownerDocument.scrollingElement;
+        var scrollableContainer = getScrollableContainer();
         if (!scrollableContainer) {
             return;
         }
-        var start = getNumberOfNodesInHeight(childHeight.current, scrollableContainer.scrollTop);
-        var startIndex = Math.max(0, start - bufferSize);
+        var start = getNumberOfNodesInHeight(childHeight.current.middle, Math.round(scrollableContainer.scrollTop));
+        var visibleNodes = getVisibleNodeCount(childHeight.current.middle, start, itemsLength, scrollableContainer);
+        // If there are less items at the end than buffer size
+        // show more items at the start.
+        // Have boundaries for edge cases, e.g. 1 item length
+        var startIndex = Math.min(Math.max(0, start - bufferSize), Math.max(0, itemsLength - bufferSize * 2 - visibleNodes));
+        visibleIndex.current = { start: start, end: start + visibleNodes };
         setStartNode(startIndex);
-        setVisibleNodeCount(getVisibleNodeCount(childHeight.current, start, itemsLength, scrollableContainer));
+        setVisibleNodeCount(visibleNodes);
         if (!parentRef.current) {
             return;
         }
-        parentRef.current.style.transform = "translateY(".concat(getTranslateValue(childHeight.current, startIndex), "px)");
+        parentRef.current.style.transform = "translateY(".concat(getTranslateValue(childHeight.current.middle, startIndex), "px)");
     }, [bufferSize, itemsLength]);
+    var onScroll = React.useCallback(function () {
+        updateVirtualScroll();
+    }, [updateVirtualScroll]);
     var removeScrollListener = React.useCallback(function () {
         var _a, _b;
         if (!onScrollRef.current) {
@@ -147,22 +216,85 @@ export var VirtualScroll = React.forwardRef(function (_a, ref) {
     React.useLayoutEffect(function () {
         var _a, _b;
         removeScrollListener();
-        onScrollRef.current = updateVirtualScroll;
+        onScrollRef.current = onScroll;
         if (!scrollContainer.current ||
             scrollContainer.current === ((_a = parentRef.current) === null || _a === void 0 ? void 0 : _a.ownerDocument.body)) {
-            (_b = parentRef.current) === null || _b === void 0 ? void 0 : _b.ownerDocument.addEventListener('scroll', updateVirtualScroll);
+            (_b = parentRef.current) === null || _b === void 0 ? void 0 : _b.ownerDocument.addEventListener('scroll', onScroll);
         }
         else {
-            scrollContainer.current.addEventListener('scroll', updateVirtualScroll);
+            scrollContainer.current.addEventListener('scroll', onScroll);
         }
         return removeScrollListener;
-    }, [updateVirtualScroll, removeScrollListener]);
+    }, [onScroll, removeScrollListener]);
+    React.useLayoutEffect(function () {
+        if (!isMounted) {
+            return;
+        }
+        var scrollableContainer = getScrollableContainer();
+        if (!scrollableContainer || scrollToIndex == null) {
+            return;
+        }
+        // if `scrollToIndex` is not visible, scroll to it
+        if (scrollToIndex > visibleIndex.current.end ||
+            scrollToIndex < visibleIndex.current.start) {
+            var indexDiff = scrollToIndex > visibleIndex.current.end
+                ? scrollToIndex - visibleIndex.current.end
+                : scrollToIndex - visibleIndex.current.start;
+            if (scrollToIndex === 0) {
+                scrollableContainer.scrollTo({ top: 0 });
+                return;
+            }
+            // If go down: add to the existing scrollTop needed height
+            // If go up: calculate the exact scroll top
+            scrollableContainer.scrollTo({
+                top: indexDiff > 0
+                    ? Math.ceil(scrollableContainer.scrollTop) +
+                        indexDiff * childHeight.current.middle
+                    : scrollToIndex * childHeight.current.middle,
+            });
+        }
+        // if `scrollToIndex` is the first visible node
+        // ensure it is fully visible
+        if (scrollToIndex === visibleIndex.current.start) {
+            var roundedScrollTop = Math.round(scrollableContainer.scrollTop);
+            var diff = roundedScrollTop % childHeight.current.middle;
+            diff > 0 &&
+                scrollableContainer.scrollTo({
+                    top: roundedScrollTop - diff,
+                });
+            return;
+        }
+        // if `scrollToIndex` is the last visible node
+        // ensure it is fully visible
+        if (scrollToIndex === visibleIndex.current.end) {
+            var diff = (scrollableContainer.offsetHeight - childHeight.current.first) %
+                childHeight.current.middle;
+            var roundedScrollTop = Math.ceil(scrollableContainer.scrollTop);
+            var scrollTopMod = roundedScrollTop % childHeight.current.middle;
+            if (diff > 0 && scrollTopMod === 0) {
+                scrollableContainer.scrollTo({
+                    top: roundedScrollTop + childHeight.current.middle - diff,
+                });
+            }
+        }
+    }, [scrollToIndex, isMounted]);
     React.useLayoutEffect(function () {
+        if (!scrollContainerHeight) {
+            return;
+        }
         updateVirtualScroll();
-    }, [scrollContainerHeight, itemsLength, updateVirtualScroll]);
-    return (React.createElement("div", __assign({ style: __assign({ overflow: 'hidden', minHeight: itemsLength * childHeight.current, width: '100%' }, style), ref: ref }, rest),
-        React.createElement("div", { style: {
-                willChange: 'transform',
-            }, ref: parentRef }, visibleChildren)));
-});
+    }, [scrollContainerHeight, updateVirtualScroll]);
+    return {
+        outerProps: __assign({ style: __assign({ overflow: 'hidden', minHeight: itemsLength > 1
+                    ? Math.max(itemsLength - 2, 0) * childHeight.current.middle +
+                        childHeight.current.first +
+                        childHeight.current.last
+                    : childHeight.current.middle, width: '100%' }, style) }, rest),
+        innerProps: {
+            style: { willChange: 'transform' },
+            ref: mergeRefs(parentRef), // convert object ref to callback ref for better types
+        },
+        visibleChildren: visibleChildren,
+    };
+};
 export default VirtualScroll;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@itwin/itwinui-react",
-  "version": "1.38.0",
+  "version": "1.38.1",
   "author": "Bentley Systems",
   "license": "MIT",
   "main": "cjs/index.js",