react-virtuoso 0.0.0-prepend → 0.0.0-semantic-release

package/dist/index.mjs

@@ -34,6 +34,9 @@ function joinProc(...procs) {
     procs.map(call);
   };
 }
+function isDefined(arg) {
+  return arg !== void 0;
+}
 function noop() {
 }
 function subscribe(emitter, subscription) {
@@ -184,7 +187,7 @@ function skip(times) {
   };
 }
 function throttleTime(interval) {
-  let currentValue;
+  let currentValue = null;
   let timeout;
   return (done) => (value) => {
     currentValue = value;
@@ -392,7 +395,22 @@ function systemToComponent(systemSpec, map2, Root) {
   const usePublisher2 = (key) => {
     return React.useCallback(curry2to1(publish, React.useContext(Context)[key]), [key]);
   };
-  const useEmitterValue2 = (key) => {
+  const useEmitterValue18 = (key) => {
+    const system2 = React.useContext(Context);
+    const source = system2[key];
+    const cb = React.useCallback(
+      (c) => {
+        return subscribe(source, c);
+      },
+      [source]
+    );
+    return React.useSyncExternalStore(
+      cb,
+      () => getValue(source),
+      () => getValue(source)
+    );
+  };
+  const useEmitterValueLegacy = (key) => {
     const system2 = React.useContext(Context);
     const source = system2[key];
     const [value, setValue] = React.useState(curry1to0(getValue, source));
@@ -406,6 +424,7 @@ function systemToComponent(systemSpec, map2, Root) {
     );
     return value;
   };
+  const useEmitterValue2 = React.version.startsWith("18") ? useEmitterValue18 : useEmitterValueLegacy;
   const useEmitter2 = (key, callback) => {
     const context = React.useContext(Context);
     const source = context[key];
@@ -428,17 +447,33 @@ var LogLevel = /* @__PURE__ */ ((LogLevel2) => {
   return LogLevel2;
 })(LogLevel || {});
 const CONSOLE_METHOD_MAP = {
-  [0]: "debug",
-  [1]: "log",
-  [2]: "warn",
-  [3]: "error"
+  [
+    0
+    /* DEBUG */
+  ]: "debug",
+  [
+    1
+    /* INFO */
+  ]: "log",
+  [
+    2
+    /* WARN */
+  ]: "warn",
+  [
+    3
+    /* ERROR */
+  ]: "error"
 };
 const getGlobalThis = () => typeof globalThis === "undefined" ? window : globalThis;
 const loggerSystem = system(
   () => {
-    const logLevel = statefulStream(3);
+    const logLevel = statefulStream(
+      3
+      /* ERROR */
+    );
     const log = statefulStream((label, message, level = 1) => {
-      const currentLevel = getGlobalThis()["VIRTUOSO_LOG_LEVEL"] ?? getValue(logLevel);
+      var _a;
+      const currentLevel = (_a = getGlobalThis()["VIRTUOSO_LOG_LEVEL"]) != null ? _a : getValue(logLevel);
       if (level >= currentLevel) {
         console[CONSOLE_METHOD_MAP[level]](
           "%creact-virtuoso: %c%s %o",
@@ -464,10 +499,12 @@ function useSizeWithElRef(callback, enabled = true) {
   if (typeof ResizeObserver !== "undefined") {
     const observer = React.useMemo(() => {
       return new ResizeObserver((entries) => {
-        const element = entries[0].target;
-        if (element.offsetParent !== null) {
-          callback(element);
-        }
+        requestAnimationFrame(() => {
+          const element = entries[0].target;
+          if (element.offsetParent !== null) {
+            callback(element);
+          }
+        });
       });
     }, [callback]);
     callbackRef = (elRef) => {
@@ -487,24 +524,26 @@ function useSizeWithElRef(callback, enabled = true) {
 function useSize(callback, enabled = true) {
   return useSizeWithElRef(callback, enabled).callbackRef;
 }
-function useChangedListContentsSizes(callback, itemSize, enabled, scrollContainerStateCallback, log, gap, customScrollParent) {
+function useChangedListContentsSizes(callback, itemSize, enabled, scrollContainerStateCallback, log, gap, customScrollParent, horizontalDirection) {
   const memoedCallback = React.useCallback(
     (el) => {
-      const ranges = getChangedChildSizes(el.children, itemSize, "offsetHeight", log);
+      const ranges = getChangedChildSizes(el.children, itemSize, horizontalDirection ? "offsetWidth" : "offsetHeight", log);
       let scrollableElement = el.parentElement;
       while (!scrollableElement.dataset["virtuosoScroller"]) {
         scrollableElement = scrollableElement.parentElement;
       }
       const windowScrolling = scrollableElement.lastElementChild.dataset["viewportType"] === "window";
-      const scrollTop = customScrollParent ? customScrollParent.scrollTop : windowScrolling ? window.pageYOffset || document.documentElement.scrollTop : scrollableElement.scrollTop;
-      const scrollHeight = customScrollParent ? customScrollParent.scrollHeight : windowScrolling ? document.documentElement.scrollHeight : scrollableElement.scrollHeight;
-      const viewportHeight = customScrollParent ? customScrollParent.offsetHeight : windowScrolling ? window.innerHeight : scrollableElement.offsetHeight;
+      const scrollTop = customScrollParent ? horizontalDirection ? customScrollParent.scrollLeft : customScrollParent.scrollTop : windowScrolling ? horizontalDirection ? window.pageXOffset || document.documentElement.scrollLeft : window.pageYOffset || document.documentElement.scrollTop : horizontalDirection ? scrollableElement.scrollLeft : scrollableElement.scrollTop;
+      const scrollHeight = customScrollParent ? horizontalDirection ? customScrollParent.scrollWidth : customScrollParent.scrollHeight : windowScrolling ? horizontalDirection ? document.documentElement.scrollWidth : document.documentElement.scrollHeight : horizontalDirection ? scrollableElement.scrollWidth : scrollableElement.scrollHeight;
+      const viewportHeight = customScrollParent ? horizontalDirection ? customScrollParent.offsetWidth : customScrollParent.offsetHeight : windowScrolling ? horizontalDirection ? window.innerWidth : window.innerHeight : horizontalDirection ? scrollableElement.offsetWidth : scrollableElement.offsetHeight;
       scrollContainerStateCallback({
         scrollTop: Math.max(scrollTop, 0),
         scrollHeight,
         viewportHeight
       });
-      gap == null ? void 0 : gap(resolveGapValue$1("row-gap", getComputedStyle(el).rowGap, log));
+      gap == null ? void 0 : gap(
+        horizontalDirection ? resolveGapValue$1("column-gap", getComputedStyle(el).columnGap, log) : resolveGapValue$1("row-gap", getComputedStyle(el).rowGap, log)
+      );
       if (ranges !== null) {
         callback(ranges);
       }
@@ -549,7 +588,7 @@ function resolveGapValue$1(property, value, log) {
   if (value === "normal") {
     return 0;
   }
-  return parseInt(value ?? "0", 10);
+  return parseInt(value != null ? value : "0", 10);
 }
 function correctItemSize(el, dimension) {
   return Math.round(el.getBoundingClientRect()[dimension]);
@@ -557,7 +596,7 @@ function correctItemSize(el, dimension) {
 function approximatelyEqual(num1, num2) {
   return Math.abs(num1 - num2) < 1.01;
 }
-function useScrollTop(scrollContainerStateCallback, smoothScrollTargetReached, scrollerElement, scrollerRefCallback = noop, customScrollParent) {
+function useScrollTop(scrollContainerStateCallback, smoothScrollTargetReached, scrollerElement, scrollerRefCallback = noop, customScrollParent, horizontalDirection) {
   const scrollerRef = React.useRef(null);
   const scrollTopTarget = React.useRef(null);
   const timeoutRef = React.useRef(null);
@@ -565,9 +604,9 @@ function useScrollTop(scrollContainerStateCallback, smoothScrollTargetReached, s
     (ev) => {
       const el = ev.target;
       const windowScroll = el === window || el === document;
-      const scrollTop = windowScroll ? window.pageYOffset || document.documentElement.scrollTop : el.scrollTop;
-      const scrollHeight = windowScroll ? document.documentElement.scrollHeight : el.scrollHeight;
-      const viewportHeight = windowScroll ? window.innerHeight : el.offsetHeight;
+      const scrollTop = horizontalDirection ? windowScroll ? window.pageXOffset || document.documentElement.scrollLeft : el.scrollLeft : windowScroll ? window.pageYOffset || document.documentElement.scrollTop : el.scrollTop;
+      const scrollHeight = horizontalDirection ? windowScroll ? document.documentElement.scrollWidth : el.scrollWidth : windowScroll ? document.documentElement.scrollHeight : el.scrollHeight;
+      const viewportHeight = horizontalDirection ? windowScroll ? window.innerWidth : el.offsetWidth : windowScroll ? window.innerHeight : el.offsetHeight;
       const call2 = () => {
         scrollContainerStateCallback({
           scrollTop: Math.max(scrollTop, 0),
@@ -605,7 +644,7 @@ function useScrollTop(scrollContainerStateCallback, smoothScrollTargetReached, s
   }, [scrollerRef, handler, scrollerElement, scrollerRefCallback, customScrollParent]);
   function scrollToCallback(location) {
     const scrollerElement2 = scrollerRef.current;
-    if (!scrollerElement2 || "offsetHeight" in scrollerElement2 && scrollerElement2.offsetHeight === 0) {
+    if (!scrollerElement2 || (horizontalDirection ? "offsetWidth" in scrollerElement2 && scrollerElement2.offsetWidth === 0 : "offsetHeight" in scrollerElement2 && scrollerElement2.offsetHeight === 0)) {
       return;
     }
     const isSmooth = location.behavior === "smooth";
@@ -613,13 +652,16 @@ function useScrollTop(scrollContainerStateCallback, smoothScrollTargetReached, s
     let scrollHeight;
     let scrollTop;
     if (scrollerElement2 === window) {
-      scrollHeight = Math.max(correctItemSize(document.documentElement, "height"), document.documentElement.scrollHeight);
-      offsetHeight = window.innerHeight;
-      scrollTop = document.documentElement.scrollTop;
+      scrollHeight = Math.max(
+        correctItemSize(document.documentElement, horizontalDirection ? "width" : "height"),
+        horizontalDirection ? document.documentElement.scrollWidth : document.documentElement.scrollHeight
+      );
+      offsetHeight = horizontalDirection ? window.innerWidth : window.innerHeight;
+      scrollTop = horizontalDirection ? document.documentElement.scrollLeft : document.documentElement.scrollTop;
     } else {
-      scrollHeight = scrollerElement2.scrollHeight;
-      offsetHeight = correctItemSize(scrollerElement2, "height");
-      scrollTop = scrollerElement2.scrollTop;
+      scrollHeight = scrollerElement2[horizontalDirection ? "scrollWidth" : "scrollHeight"];
+      offsetHeight = correctItemSize(scrollerElement2, horizontalDirection ? "width" : "height");
+      scrollTop = scrollerElement2[horizontalDirection ? "scrollLeft" : "scrollTop"];
     }
     const maxScrollTop = scrollHeight - offsetHeight;
     location.top = Math.ceil(Math.max(Math.min(maxScrollTop, location.top), 0));
@@ -643,9 +685,15 @@ function useScrollTop(scrollContainerStateCallback, smoothScrollTargetReached, s
     } else {
       scrollTopTarget.current = null;
     }
+    if (horizontalDirection) {
+      location = { left: location.top, behavior: location.behavior };
+    }
     scrollerElement2.scrollTo(location);
   }
   function scrollByCallback(location) {
+    if (horizontalDirection) {
+      location = { left: location.top, behavior: location.behavior };
+    }
     scrollerRef.current.scrollBy(location);
   }
   return { scrollerRef, scrollByCallback, scrollToCallback };
@@ -666,6 +714,7 @@ const domIOSystem = system(
     const scrollTo = stream();
     const scrollBy = stream();
     const scrollingInProgress = statefulStream(false);
+    const horizontalDirection = statefulStream(false);
     connect(
       pipe(
         scrollContainerState,
@@ -682,6 +731,7 @@ const domIOSystem = system(
     );
     connect(scrollTop, statefulScrollTop);
     return {
+      // input
       scrollContainerState,
       scrollTop,
       viewportHeight,
@@ -691,8 +741,11 @@ const domIOSystem = system(
       footerHeight,
       scrollHeight,
       smoothScrollTargetReached,
+      horizontalDirection,
+      // signals
       scrollTo,
       scrollBy,
+      // state
       statefulScrollTop,
       deviation,
       scrollingInProgress
@@ -746,10 +799,10 @@ function findMaxKeyValue(node, value, field = "k") {
   if (empty(node)) {
     return [-Infinity, void 0];
   }
-  if (node[field] === value) {
+  if (Number(node[field]) === value) {
     return [node.k, node.v];
   }
-  if (node[field] < value) {
+  if (Number(node[field]) < value) {
     const r = findMaxKeyValue(node.r, value, field);
     if (r[0] === -Infinity) {
       return [node.k, node.v];
@@ -1114,6 +1167,13 @@ function originalIndexFromItemIndex(itemIndex, sizes) {
 function hasGroups(sizes) {
   return !empty(sizes.groupOffsetTree);
 }
+function sizeTreeToRanges(sizeTree) {
+  return walk(sizeTree).map(({ k: startIndex, v: size }, index, sizeArray) => {
+    const nextSize = sizeArray[index + 1];
+    const endIndex = nextSize ? nextSize.k - 1 : Infinity;
+    return { startIndex, endIndex, size };
+  });
+}
 const SIZE_MAP = {
   offsetHeight: "height",
   offsetWidth: "width"
@@ -1171,8 +1231,8 @@ const sizeSystem = system(
       pipe(
         totalCount,
         withLatestFrom(sizes),
-        filter(([totalCount2, { lastIndex, groupIndices: groupIndices2 }]) => {
-          return totalCount2 < lastIndex && groupIndices2.length === 0;
+        filter(([totalCount2, { lastIndex }]) => {
+          return totalCount2 < lastIndex;
         }),
         map(([totalCount2, { lastIndex, lastSize }]) => {
           return [
@@ -1239,8 +1299,9 @@ const sizeSystem = system(
         } else if (offset < 0) {
           const prevGroupIndicesValue = getValue(prevGroupIndices);
           if (prevGroupIndicesValue.length > 0) {
-            publish(shiftWith, offset - affectedGroupCount(-offset, prevGroupIndicesValue));
+            offset -= affectedGroupCount(-offset, prevGroupIndicesValue);
           }
+          publish(shiftWith, offset);
         }
       }
     );
@@ -1268,7 +1329,7 @@ const sizeSystem = system(
             let groupIndex = 0;
             while (prependedGroupItemsCount < unshiftWith2) {
               const theGroupIndex = sizes2.groupIndices[groupIndex];
-              const groupItemCount = sizes2.groupIndices[groupIndex + 1] - theGroupIndex - 1;
+              const groupItemCount = sizes2.groupIndices.length === groupIndex + 1 ? Infinity : sizes2.groupIndices[groupIndex + 1] - theGroupIndex - 1;
               initialRanges.push({
                 startIndex: theGroupIndex,
                 endIndex: theGroupIndex,
@@ -1348,6 +1409,9 @@ const sizeSystem = system(
         map(([shiftWith2, sizes2, gap2]) => {
           const groupedMode = sizes2.groupIndices.length > 0;
           if (groupedMode) {
+            if (empty(sizes2.sizeTree)) {
+              return sizes2;
+            }
             let newSizeTree = newTree();
             const prevGroupIndicesValue = getValue(prevGroupIndices);
             let removedItemsCount = 0;
@@ -1389,6 +1453,7 @@ const sizeSystem = system(
       sizes
     );
     return {
+      // input
       data,
       totalCount,
       sizeRanges,
@@ -1401,6 +1466,7 @@ const sizeSystem = system(
       beforeUnshiftWith,
       firstItemIndex,
       gap,
+      // output
       sizes,
       listRefresh,
       statefulTotalCount,
@@ -1441,6 +1507,7 @@ const scrollToIndexSystem = system(
     { log }
   ]) => {
     const scrollToIndex = stream();
+    const scrollTargetReached = stream();
     const topListHeight = statefulStream(0);
     let unsubscribeNextListRefresh = null;
     let cleartTimeoutRef = null;
@@ -1496,6 +1563,7 @@ const scrollToIndexSystem = system(
                 log2("retrying to scroll to", { location }, LogLevel.DEBUG);
                 publish(scrollToIndex, location);
               } else {
+                publish(scrollTargetReached, true);
                 log2("list did not change, scroll successful", {}, LogLevel.DEBUG);
               }
             };
@@ -1524,6 +1592,7 @@ const scrollToIndexSystem = system(
     );
     return {
       scrollToIndex,
+      scrollTargetReached,
       topListHeight
     };
   },
@@ -1703,6 +1772,7 @@ const stateFlagsSystem = system(([{ scrollContainerState, scrollTop, viewportHei
     pipe(
       isScrolling,
       filter((value) => !value),
+      // eslint-disable-next-line @typescript-eslint/no-unsafe-argument
       mapTo(0)
     ),
     scrollVelocity
@@ -1750,15 +1820,23 @@ const propsReadySystem = system(
   tup(loggerSystem),
   { singleton: true }
 );
+function skipFrames(frameCount, callback) {
+  if (frameCount == 0) {
+    callback();
+  } else {
+    requestAnimationFrame(() => skipFrames(frameCount - 1, callback));
+  }
+}
 function getInitialTopMostItemIndexNumber(location, totalCount) {
   const lastIndex = totalCount - 1;
   const index = typeof location === "number" ? location : location.index === "LAST" ? lastIndex : location.index;
   return index;
 }
 const initialTopMostItemIndexSystem = system(
-  ([{ sizes, listRefresh, defaultItemSize }, { scrollTop }, { scrollToIndex }, { didMount }]) => {
+  ([{ sizes, listRefresh, defaultItemSize }, { scrollTop }, { scrollToIndex, scrollTargetReached }, { didMount }]) => {
     const scrolledToInitialItem = statefulStream(true);
     const initialTopMostItemIndex = statefulStream(0);
+    const initialItemFinalLocationReached = statefulStream(true);
     connect(
       pipe(
         didMount,
@@ -1768,17 +1846,29 @@ const initialTopMostItemIndexSystem = system(
       ),
       scrolledToInitialItem
     );
+    connect(
+      pipe(
+        didMount,
+        withLatestFrom(initialTopMostItemIndex),
+        filter(([_, location]) => !!location),
+        mapTo(false)
+      ),
+      initialItemFinalLocationReached
+    );
     subscribe(
       pipe(
         combineLatest(listRefresh, didMount),
-        withLatestFrom(scrolledToInitialItem, sizes, defaultItemSize),
-        filter(([[, didMount2], scrolledToInitialItem2, { sizeTree }, defaultItemSize2]) => {
-          return didMount2 && (!empty(sizeTree) || defaultItemSize2 !== void 0) && !scrolledToInitialItem2;
+        withLatestFrom(scrolledToInitialItem, sizes, defaultItemSize, initialItemFinalLocationReached),
+        filter(([[, didMount2], scrolledToInitialItem2, { sizeTree }, defaultItemSize2, scrollScheduled]) => {
+          return didMount2 && (!empty(sizeTree) || isDefined(defaultItemSize2)) && !scrolledToInitialItem2 && !scrollScheduled;
         }),
         withLatestFrom(initialTopMostItemIndex)
       ),
       ([, initialTopMostItemIndex2]) => {
-        setTimeout(() => {
+        handleNext(scrollTargetReached, () => {
+          publish(initialItemFinalLocationReached, true);
+        });
+        skipFrames(3, () => {
           handleNext(scrollTop, () => {
             publish(scrolledToInitialItem, true);
           });
@@ -1788,7 +1878,8 @@ const initialTopMostItemIndexSystem = system(
     );
     return {
       scrolledToInitialItem,
-      initialTopMostItemIndex
+      initialTopMostItemIndex,
+      initialItemFinalLocationReached
     };
   },
   tup(sizeSystem, domIOSystem, scrollToIndexSystem, propsReadySystem),
@@ -1876,7 +1967,9 @@ const followOutputSystem = system(
         withLatestFrom(followOutput, totalCount)
       ),
       ([, followOutput2]) => {
-        trapNextSizeIncrease(followOutput2 !== false);
+        if (getValue(scrolledToInitialItem)) {
+          trapNextSizeIncrease(followOutput2 !== false);
+        }
       }
     );
     subscribe(autoscrollToBottom, () => {
@@ -2019,10 +2112,12 @@ const sizeRangeSystem = system(
       [0, 0]
     );
     return {
+      // input
       listBoundary,
       overscan,
       topListHeight,
       increaseViewportBy,
+      // output
       visibleRange
     };
   },
@@ -2116,6 +2211,26 @@ function buildListState(items, topItems, totalCount, gap, sizes, firstItemIndex)
     firstItemIndex
   };
 }
+function buildListStateFromItemCount(itemCount, initialTopMostItemIndex, sizes, firstItemIndex, gap, data) {
+  let includedGroupsCount = 0;
+  if (sizes.groupIndices.length > 0) {
+    for (const index of sizes.groupIndices) {
+      if (index - includedGroupsCount >= itemCount) {
+        break;
+      }
+      includedGroupsCount++;
+    }
+  }
+  const adjustedCount = itemCount + includedGroupsCount;
+  const initialTopMostItemIndexNumber = getInitialTopMostItemIndexNumber(initialTopMostItemIndex, adjustedCount);
+  const items = Array.from({ length: adjustedCount }).map((_, index) => ({
+    index: index + initialTopMostItemIndexNumber,
+    size: 0,
+    offset: 0,
+    data: data[index + initialTopMostItemIndexNumber]
+  }));
+  return buildListState(items, [], adjustedCount, gap, sizes, firstItemIndex);
+}
 const listStateSystem = system(
   ([
     { sizes, totalCount, data, firstItemIndex, gap },
@@ -2128,6 +2243,7 @@ const listStateSystem = system(
     { recalcInProgress }
   ]) => {
     const topItemsIndexes = statefulStream([]);
+    const initialItemCount = statefulStream(0);
     const itemsRendered = stream();
     connect(groupedListSystem2.topItemsIndexes, topItemsIndexes);
     const listState = statefulStreamFromEmitter(
@@ -2165,11 +2281,22 @@ const listStateSystem = system(
           ]) => {
             const sizesValue = sizes2;
             const { sizeTree, offsetTree } = sizesValue;
-            if (totalCount2 === 0 || startOffset === 0 && endOffset === 0) {
+            const initialItemCountValue = getValue(initialItemCount);
+            if (totalCount2 === 0) {
               return { ...EMPTY_LIST_STATE, totalCount: totalCount2 };
             }
+            if (startOffset === 0 && endOffset === 0) {
+              if (initialItemCountValue === 0) {
+                return { ...EMPTY_LIST_STATE, totalCount: totalCount2 };
+              } else {
+                return buildListStateFromItemCount(initialItemCountValue, initialTopMostItemIndex2, sizes2, firstItemIndex2, gap2, data2 || []);
+              }
+            }
             if (empty(sizeTree)) {
-              return buildListState(
+              if (initialItemCountValue > 0) {
+                return null;
+              }
+              const state = buildListState(
                 probeItemSet(getInitialTopMostItemIndexNumber(initialTopMostItemIndex2, totalCount2), sizesValue, data2),
                 [],
                 totalCount2,
@@ -2177,6 +2304,7 @@ const listStateSystem = system(
                 sizesValue,
                 firstItemIndex2
               );
+              return state;
             }
             const topItems = [];
             if (topItemsIndexes2.length > 0) {
@@ -2230,6 +2358,7 @@ const listStateSystem = system(
             return buildListState(items, topItems, totalCount2, gap2, sizesValue, firstItemIndex2);
           }
         ),
+        //@ts-expect-error filter needs to be fixed
         filter((value) => value !== null),
         distinctUntilChanged()
       ),
@@ -2238,7 +2367,7 @@ const listStateSystem = system(
     connect(
       pipe(
         data,
-        filter((data2) => data2 !== void 0),
+        filter(isDefined),
         map((data2) => data2 == null ? void 0 : data2.length)
       ),
       totalCount
@@ -2308,7 +2437,7 @@ const listStateSystem = system(
         distinctUntilChanged(rangeComparator)
       )
     );
-    return { listState, topItemsIndexes, endReached, startReached, rangeChanged, itemsRendered, ...stateFlags };
+    return { listState, topItemsIndexes, endReached, startReached, rangeChanged, itemsRendered, initialItemCount, ...stateFlags };
   },
   tup(
     sizeSystem,
@@ -2323,34 +2452,22 @@ const listStateSystem = system(
   { singleton: true }
 );
 const initialItemCountSystem = system(
-  ([{ sizes, firstItemIndex, data, gap }, { listState }, { didMount }]) => {
-    const initialItemCount = statefulStream(0);
+  ([{ sizes, firstItemIndex, data, gap }, { initialTopMostItemIndex }, { initialItemCount, listState }, { didMount }]) => {
     connect(
       pipe(
         didMount,
         withLatestFrom(initialItemCount),
         filter(([, count]) => count !== 0),
-        withLatestFrom(sizes, firstItemIndex, gap, data),
-        map(([[, count], sizes2, firstItemIndex2, gap2, data2 = []]) => {
-          let includedGroupsCount = 0;
-          if (sizes2.groupIndices.length > 0) {
-            for (const index of sizes2.groupIndices) {
-              if (index - includedGroupsCount >= count) {
-                break;
-              }
-              includedGroupsCount++;
-            }
-          }
-          const adjustedCount = count + includedGroupsCount;
-          const items = Array.from({ length: adjustedCount }).map((_, index) => ({ index, size: 0, offset: 0, data: data2[index] }));
-          return buildListState(items, [], adjustedCount, gap2, sizes2, firstItemIndex2);
+        withLatestFrom(initialTopMostItemIndex, sizes, firstItemIndex, gap, data),
+        map(([[, count], initialTopMostItemIndexValue, sizes2, firstItemIndex2, gap2, data2 = []]) => {
+          return buildListStateFromItemCount(count, initialTopMostItemIndexValue, sizes2, firstItemIndex2, gap2, data2);
         })
       ),
       listState
     );
-    return { initialItemCount };
+    return {};
   },
-  tup(sizeSystem, listStateSystem, propsReadySystem),
+  tup(sizeSystem, initialTopMostItemIndexSystem, listStateSystem, propsReadySystem),
   { singleton: true }
 );
 const scrollSeekSystem = system(
@@ -2528,7 +2645,7 @@ const upwardScrollFixSystem = system(
             while (recognizedOffsetItems < offset) {
               recognizedOffsetItems++;
               amount += defaultGroupSize;
-              let groupItemCount = groupIndices[groupIndex + 1] - groupIndices[groupIndex] - 1;
+              let groupItemCount = groupIndices.length === groupIndex + 1 ? Infinity : groupIndices[groupIndex + 1] - groupIndices[groupIndex] - 1;
               if (recognizedOffsetItems + groupItemCount > offset) {
                 amount -= defaultGroupSize;
                 groupItemCount = offset - recognizedOffsetItems + 1;
@@ -2557,7 +2674,7 @@ const upwardScrollFixSystem = system(
   tup(domIOSystem, stateFlagsSystem, listStateSystem, sizeSystem, loggerSystem, recalcSystem)
 );
 const initialScrollTopSystem = system(
-  ([{ totalListHeight }, { didMount }, { scrollTo }]) => {
+  ([{ didMount }, { scrollTo }, { listState }]) => {
     const initialScrollTop = statefulStream(0);
     subscribe(
       pipe(
@@ -2569,11 +2686,12 @@ const initialScrollTopSystem = system(
       (location) => {
         handleNext(
           pipe(
-            totalListHeight,
-            filter((val) => val !== 0)
+            listState,
+            skip(1),
+            filter((state) => state.items.length > 1)
           ),
           () => {
-            setTimeout(() => {
+            requestAnimationFrame(() => {
               publish(scrollTo, location);
             });
           }
@@ -2584,7 +2702,7 @@ const initialScrollTopSystem = system(
       initialScrollTop
     };
   },
-  tup(totalListHeightSystem, propsReadySystem, domIOSystem),
+  tup(propsReadySystem, domIOSystem, listStateSystem),
   { singleton: true }
 );
 const alignToBottomSystem = system(
@@ -2597,6 +2715,7 @@ const alignToBottomSystem = system(
         map(([, viewportHeight2, totalListHeight2]) => {
           return Math.max(0, viewportHeight2 - totalListHeight2);
         }),
+        throttleTime(0),
         distinctUntilChanged()
       ),
       0
@@ -2639,10 +2758,13 @@ const windowScrollerSystem = system(([{ scrollTo, scrollContainerState }]) => {
     windowScrollTo
   );
   return {
+    // config
     useWindowScroll,
     customScrollParent,
+    // input
     windowScrollContainerState,
     windowViewportRect,
+    // signals
     windowScrollTo
   };
 }, tup(domIOSystem));
@@ -2654,10 +2776,10 @@ const defaultCalculateViewLocation = ({
   locationParams: { behavior, align, ...rest }
 }) => {
   if (itemTop2 < viewportTop) {
-    return { ...rest, behavior, align: align ?? "start" };
+    return { ...rest, behavior, align: align != null ? align : "start" };
   }
   if (itemBottom > viewportBottom) {
-    return { ...rest, behavior, align: align ?? "end" };
+    return { ...rest, behavior, align: align != null ? align : "end" };
   }
   return null;
 };
@@ -2692,6 +2814,8 @@ const scrollIntoViewSystem = system(
               pipe(
                 scrollingInProgress,
                 filter((value) => value === false),
+                // skips the initial publish of false, and the cleanup call.
+                // but if scrollingInProgress is true, we skip the initial publish.
                 skip(getValue(scrollingInProgress) ? 1 : 2)
               ),
               done
@@ -2712,6 +2836,53 @@ const scrollIntoViewSystem = system(
   tup(sizeSystem, domIOSystem, scrollToIndexSystem, listStateSystem, loggerSystem),
   { singleton: true }
 );
+const stateLoadSystem = system(
+  ([
+    { sizes, sizeRanges },
+    { scrollTop },
+    { initialTopMostItemIndex },
+    { didMount },
+    { useWindowScroll, windowScrollContainerState, windowViewportRect }
+  ]) => {
+    const getState = stream();
+    const restoreStateFrom = statefulStream(void 0);
+    const statefulWindowScrollContainerState = statefulStream(null);
+    const statefulWindowViewportRect = statefulStream(null);
+    connect(windowScrollContainerState, statefulWindowScrollContainerState);
+    connect(windowViewportRect, statefulWindowViewportRect);
+    subscribe(
+      pipe(getState, withLatestFrom(sizes, scrollTop, useWindowScroll, statefulWindowScrollContainerState, statefulWindowViewportRect)),
+      ([callback, sizes2, scrollTop2, useWindowScroll2, windowScrollContainerState2, windowViewportRect2]) => {
+        const ranges = sizeTreeToRanges(sizes2.sizeTree);
+        if (useWindowScroll2 && windowScrollContainerState2 !== null && windowViewportRect2 !== null) {
+          scrollTop2 = windowScrollContainerState2.scrollTop - windowViewportRect2.offsetTop;
+        }
+        callback({ ranges, scrollTop: scrollTop2 });
+      }
+    );
+    connect(pipe(restoreStateFrom, filter(isDefined), map(locationFromSnapshot)), initialTopMostItemIndex);
+    connect(
+      pipe(
+        didMount,
+        withLatestFrom(restoreStateFrom),
+        filter(([, state]) => state !== void 0),
+        distinctUntilChanged(),
+        map(([, snapshot]) => {
+          return snapshot.ranges;
+        })
+      ),
+      sizeRanges
+    );
+    return {
+      getState,
+      restoreStateFrom
+    };
+  },
+  tup(sizeSystem, domIOSystem, initialTopMostItemIndexSystem, propsReadySystem, windowScrollerSystem)
+);
+function locationFromSnapshot(snapshot) {
+  return { offset: snapshot.scrollTop, index: 0, align: "start" };
+}
 const featureGroup1System = system(
   ([
     sizeRange,
@@ -2722,7 +2893,8 @@ const featureGroup1System = system(
     initialScrollTopSystem2,
     alignToBottom,
     windowScroller,
-    scrollIntoView
+    scrollIntoView,
+    logger
   ]) => {
     return {
       ...sizeRange,
@@ -2733,7 +2905,8 @@ const featureGroup1System = system(
       ...initialScrollTopSystem2,
       ...alignToBottom,
       ...windowScroller,
-      ...scrollIntoView
+      ...scrollIntoView,
+      ...logger
     };
   },
   tup(
@@ -2745,7 +2918,8 @@ const featureGroup1System = system(
     initialScrollTopSystem,
     alignToBottomSystem,
     windowScrollerSystem,
-    scrollIntoViewSystem
+    scrollIntoViewSystem,
+    loggerSystem
   )
 );
 const listSystem = system(
@@ -2764,16 +2938,16 @@ const listSystem = system(
       gap,
       sizes
     },
-    { initialTopMostItemIndex, scrolledToInitialItem },
+    { initialTopMostItemIndex, scrolledToInitialItem, initialItemFinalLocationReached },
     domIO,
+    stateLoad,
     followOutput,
     { listState, topItemsIndexes, ...flags },
     { scrollToIndex },
     _,
     { topItemCount },
     { groupCounts },
-    featureGroup1,
-    log
+    featureGroup1
   ]) => {
     connect(flags.rangeChanged, featureGroup1.scrollSeekRangeChanged);
     connect(
@@ -2784,12 +2958,14 @@ const listSystem = system(
       domIO.viewportHeight
     );
     return {
+      // input
       totalCount,
       data,
       firstItemIndex,
       sizeRanges,
       initialTopMostItemIndex,
       scrolledToInitialItem,
+      initialItemFinalLocationReached,
       topItemsIndexes,
       topItemCount,
       groupCounts,
@@ -2797,31 +2973,34 @@ const listSystem = system(
       defaultItemHeight: defaultItemSize,
       gap,
       ...followOutput,
+      // output
       statefulTotalCount,
       listState,
       scrollToIndex,
       trackItemSizes,
       itemSize,
       groupIndices,
+      // exported from stateFlagsSystem
       ...flags,
+      // the bag of IO from featureGroup1System
       ...featureGroup1,
       ...domIO,
-      ...log,
-      sizes
+      sizes,
+      ...stateLoad
     };
   },
   tup(
     sizeSystem,
     initialTopMostItemIndexSystem,
     domIOSystem,
+    stateLoadSystem,
     followOutputSystem,
     listStateSystem,
     scrollToIndexSystem,
     upwardScrollFixSystem,
     topItemCountSystem,
     groupedListSystem,
-    featureGroup1System,
-    loggerSystem
+    featureGroup1System
   )
 );
 const WEBKIT_STICKY = "-webkit-sticky";
@@ -2869,7 +3048,9 @@ function useWindowViewportRectRef(callback, customScrollParent) {
   React.useEffect(() => {
     if (customScrollParent) {
       customScrollParent.addEventListener("scroll", scrollAndResizeEventHandler);
-      const observer = new ResizeObserver(scrollAndResizeEventHandler);
+      const observer = new ResizeObserver(() => {
+        requestAnimationFrame(scrollAndResizeEventHandler);
+      });
       observer.observe(customScrollParent);
       return () => {
         customScrollParent.removeEventListener("scroll", scrollAndResizeEventHandler);
@@ -2933,7 +3114,8 @@ const combinedSystem$2 = /* @__PURE__ */ system(([listSystem2, propsSystem]) =>
 }, tup(listSystem, listComponentPropsSystem));
 const DefaultScrollSeekPlaceholder$1 = ({ height }) => /* @__PURE__ */ React.createElement("div", { style: { height } });
 const GROUP_STYLE = { position: positionStickyCssValue(), zIndex: 1, overflowAnchor: "none" };
-const ITEM_STYLE = { overflowAnchor: "none" };
+const ITEM_STYLE$1 = { overflowAnchor: "none" };
+const HORIZONTAL_ITEM_STYLE = { ...ITEM_STYLE$1, display: "inline-block", height: "100%" };
 const Items$1 = /* @__PURE__ */ React.memo(function VirtuosoItems({ showTopList = false }) {
   const listState = useEmitterValue$2("listState");
   const sizeRanges = usePublisher$2("sizeRanges");
@@ -2949,6 +3131,7 @@ const Items$1 = /* @__PURE__ */ React.memo(function VirtuosoItems({ showTopList
   const itemSize = useEmitterValue$2("itemSize");
   const log = useEmitterValue$2("log");
   const listGap = usePublisher$2("gap");
+  const horizontalDirection = useEmitterValue$2("horizontalDirection");
   const { callbackRef } = useChangedListContentsSizes(
     sizeRanges,
     itemSize,
@@ -2956,7 +3139,8 @@ const Items$1 = /* @__PURE__ */ React.memo(function VirtuosoItems({ showTopList
     showTopList ? noop : scrollContainerStateCallback,
     log,
     listGap,
-    customScrollParent
+    customScrollParent,
+    horizontalDirection
   );
   const [deviation, setDeviation] = React.useState(0);
   useEmitter$2("deviation", (value) => {
@@ -2972,12 +3156,23 @@ const Items$1 = /* @__PURE__ */ React.memo(function VirtuosoItems({ showTopList
   const computeItemKey = useEmitterValue$2("computeItemKey");
   const isSeeking = useEmitterValue$2("isSeeking");
   const hasGroups2 = useEmitterValue$2("groupIndices").length > 0;
-  const paddingTopAddition = useEmitterValue$2("paddingTopAddition");
+  const alignToBottom = useEmitterValue$2("alignToBottom");
+  const initialItemFinalLocationReached = useEmitterValue$2("initialItemFinalLocationReached");
   const containerStyle = showTopList ? {} : {
     boxSizing: "border-box",
-    paddingTop: listState.offsetTop + paddingTopAddition,
-    paddingBottom: listState.offsetBottom,
-    marginTop: deviation
+    ...horizontalDirection ? {
+      whiteSpace: "nowrap",
+      display: "inline-block",
+      height: "100%",
+      paddingLeft: listState.offsetTop,
+      paddingRight: listState.offsetBottom,
+      marginLeft: deviation !== 0 ? deviation : alignToBottom ? "auto" : 0
+    } : {
+      marginTop: deviation !== 0 ? deviation : alignToBottom ? "auto" : 0,
+      paddingTop: listState.offsetTop,
+      paddingBottom: listState.offsetBottom
+    },
+    ...initialItemFinalLocationReached ? {} : { visibility: "hidden" }
   };
   if (!showTopList && listState.totalCount === 0 && EmptyPlaceholder) {
     return React.createElement(EmptyPlaceholder, contextPropIfNotDomElement(EmptyPlaceholder, context));
@@ -2988,7 +3183,7 @@ const Items$1 = /* @__PURE__ */ React.memo(function VirtuosoItems({ showTopList
       ...contextPropIfNotDomElement(ListComponent, context),
       ref: callbackRef,
       style: containerStyle,
-      "data-test-id": showTopList ? "virtuoso-top-item-list" : "virtuoso-item-list"
+      "data-testid": showTopList ? "virtuoso-top-item-list" : "virtuoso-item-list"
     },
     (showTopList ? listState.topItems : listState.items).map((item) => {
       const index = item.originalIndex;
@@ -3021,13 +3216,13 @@ const Items$1 = /* @__PURE__ */ React.memo(function VirtuosoItems({ showTopList
           ItemComponent,
           {
             ...contextPropIfNotDomElement(ItemComponent, context),
+            ...itemPropIfNotDomElement(ItemComponent, item.data),
             key,
             "data-index": index,
             "data-known-size": item.size,
             "data-item-index": item.index,
             "data-item-group-index": item.groupIndex,
-            item: item.data,
-            style: ITEM_STYLE
+            style: horizontalDirection ? HORIZONTAL_ITEM_STYLE : ITEM_STYLE$1
           },
           hasGroups2 ? itemContent(item.index, item.groupIndex, item.data, context) : itemContent(item.index, item.data, context)
         );
@@ -3042,12 +3237,18 @@ const scrollerStyle = {
   position: "relative",
   WebkitOverflowScrolling: "touch"
 };
-const viewportStyle = {
+const horizontalScrollerStyle = {
+  outline: "none",
+  overflowX: "auto",
+  position: "relative"
+};
+const viewportStyle = (alignToBottom) => ({
   width: "100%",
   height: "100%",
   position: "absolute",
-  top: 0
-};
+  top: 0,
+  ...alignToBottom ? { display: "flex", flexDirection: "column" } : {}
+});
 const topItemListStyle = {
   width: "100%",
   position: positionStickyCssValue(),
@@ -3060,6 +3261,9 @@ function contextPropIfNotDomElement(element, context) {
   }
   return { context };
 }
+function itemPropIfNotDomElement(element, item) {
+  return { item: typeof element === "string" ? void 0 : item };
+}
 const Header$1 = /* @__PURE__ */ React.memo(function VirtuosoHeader() {
   const Header2 = useEmitterValue$2("HeaderComponent");
   const headerHeight = usePublisher$2("headerHeight");
@@ -3083,20 +3287,24 @@ function buildScroller({ usePublisher: usePublisher2, useEmitter: useEmitter2, u
     const smoothScrollTargetReached = usePublisher2("smoothScrollTargetReached");
     const scrollerRefCallback = useEmitterValue2("scrollerRef");
     const context = useEmitterValue2("context");
+    const horizontalDirection = useEmitterValue2("horizontalDirection") || false;
     const { scrollerRef, scrollByCallback, scrollToCallback } = useScrollTop(
       scrollContainerStateCallback,
       smoothScrollTargetReached,
       ScrollerComponent,
-      scrollerRefCallback
+      scrollerRefCallback,
+      void 0,
+      horizontalDirection
     );
     useEmitter2("scrollTo", scrollToCallback);
     useEmitter2("scrollBy", scrollByCallback);
+    const defaultStyle = horizontalDirection ? horizontalScrollerStyle : scrollerStyle;
     return React.createElement(
       ScrollerComponent,
       {
         ref: scrollerRef,
-        style: { ...scrollerStyle, ...style },
-        "data-test-id": "virtuoso-scroller",
+        style: { ...defaultStyle, ...style },
+        "data-testid": "virtuoso-scroller",
         "data-virtuoso-scroller": true,
         tabIndex: 0,
         ...props,
@@ -3148,14 +3356,16 @@ const Viewport$2 = ({ children }) => {
   const ctx = React.useContext(VirtuosoMockContext);
   const viewportHeight = usePublisher$2("viewportHeight");
   const fixedItemHeight = usePublisher$2("fixedItemHeight");
-  const viewportRef = useSize(compose(viewportHeight, (el) => correctItemSize(el, "height")));
+  const alignToBottom = useEmitterValue$2("alignToBottom");
+  const horizontalDirection = useEmitterValue$2("horizontalDirection");
+  const viewportRef = useSize(compose(viewportHeight, (el) => correctItemSize(el, horizontalDirection ? "width" : "height")));
   React.useEffect(() => {
     if (ctx) {
       viewportHeight(ctx.viewportHeight);
       fixedItemHeight(ctx.itemHeight);
     }
   }, [ctx, viewportHeight, fixedItemHeight]);
-  return /* @__PURE__ */ React.createElement("div", { style: viewportStyle, ref: viewportRef, "data-viewport-type": "element" }, children);
+  return /* @__PURE__ */ React.createElement("div", { style: viewportStyle(alignToBottom), ref: viewportRef, "data-viewport-type": "element" }, children);
 };
 const WindowViewport$2 = ({ children }) => {
   const ctx = React.useContext(VirtuosoMockContext);
@@ -3163,20 +3373,21 @@ const WindowViewport$2 = ({ children }) => {
   const fixedItemHeight = usePublisher$2("fixedItemHeight");
   const customScrollParent = useEmitterValue$2("customScrollParent");
   const viewportRef = useWindowViewportRectRef(windowViewportRect, customScrollParent);
+  const alignToBottom = useEmitterValue$2("alignToBottom");
   React.useEffect(() => {
     if (ctx) {
       fixedItemHeight(ctx.itemHeight);
       windowViewportRect({ offsetTop: 0, visibleHeight: ctx.viewportHeight, visibleWidth: 100 });
     }
   }, [ctx, windowViewportRect, fixedItemHeight]);
-  return /* @__PURE__ */ React.createElement("div", { ref: viewportRef, style: viewportStyle, "data-viewport-type": "window" }, children);
+  return /* @__PURE__ */ React.createElement("div", { ref: viewportRef, style: viewportStyle(alignToBottom), "data-viewport-type": "window" }, children);
 };
 const TopItemListContainer = ({ children }) => {
-  const TopItemList = useEmitterValue$2("TopItemListComponent");
+  const TopItemList = useEmitterValue$2("TopItemListComponent") || "div";
   const headerHeight = useEmitterValue$2("headerHeight");
   const style = { ...topItemListStyle, marginTop: `${headerHeight}px` };
   const context = useEmitterValue$2("context");
-  return React.createElement(TopItemList || "div", { style, context }, children);
+  return React.createElement(TopItemList, { style, ...contextPropIfNotDomElement(TopItemList, context) }, children);
 };
 const ListRoot = /* @__PURE__ */ React.memo(function VirtuosoRoot(props) {
   const useWindowScroll = useEmitterValue$2("useWindowScroll");
@@ -3196,6 +3407,7 @@ const {
   {
     required: {},
     optional: {
+      restoreStateFrom: "restoreStateFrom",
       context: "context",
       followOutput: "followOutput",
       itemContent: "itemContent",
@@ -3223,14 +3435,16 @@ const {
       useWindowScroll: "useWindowScroll",
       customScrollParent: "customScrollParent",
       scrollerRef: "scrollerRef",
-      logLevel: "logLevel"
+      logLevel: "logLevel",
+      horizontalDirection: "horizontalDirection"
     },
     methods: {
       scrollToIndex: "scrollToIndex",
       scrollIntoView: "scrollIntoView",
       scrollTo: "scrollTo",
       scrollBy: "scrollBy",
-      autoscrollToBottom: "autoscrollToBottom"
+      autoscrollToBottom: "autoscrollToBottom",
+      getState: "getState"
     },
     events: {
       isScrolling: "isScrolling",
@@ -3276,9 +3490,10 @@ function buildProbeGridState(items) {
   };
 }
 function buildItems(startIndex, endIndex, data) {
-  return Array.from({ length: endIndex - startIndex + 1 }).map(
-    (_, i) => ({ index: i + startIndex, data: data == null ? void 0 : data[i + startIndex] })
-  );
+  return Array.from({ length: endIndex - startIndex + 1 }).map((_, i) => {
+    const dataItem = data === null ? null : data[i + startIndex];
+    return { index: i + startIndex, data: dataItem };
+  });
 }
 function gapComparator(prev, next) {
   return prev && prev.column === next.column && prev.row === next.row;
@@ -3293,7 +3508,7 @@ const gridSystem = /* @__PURE__ */ system(
     stateFlags,
     scrollSeek,
     { propsReady, didMount },
-    { windowViewportRect, windowScrollTo, useWindowScroll, customScrollParent, windowScrollContainerState },
+    { windowViewportRect, useWindowScroll, customScrollParent, windowScrollContainerState, windowScrollTo },
     log
   ]) => {
     const totalCount = statefulStream(0);
@@ -3304,25 +3519,96 @@ const gridSystem = /* @__PURE__ */ system(
     const scrollToIndex = stream();
     const scrollHeight = stream();
     const deviation = statefulStream(0);
-    const data = statefulStream(void 0);
+    const data = statefulStream(null);
     const gap = statefulStream({ row: 0, column: 0 });
-    connect(
+    const stateChanged = stream();
+    const restoreStateFrom = stream();
+    const stateRestoreInProgress = statefulStream(false);
+    const initialTopMostItemIndex = statefulStream(0);
+    const scrolledToInitialItem = statefulStream(true);
+    const scrollScheduled = statefulStream(false);
+    const horizontalDirection = statefulStream(false);
+    subscribe(
       pipe(
-        combineLatest(didMount, initialItemCount, data),
-        filter(([, count]) => count !== 0),
-        map(([, count, data2]) => {
-          return {
-            items: buildItems(0, count - 1, data2),
-            top: 0,
-            bottom: 0,
-            offsetBottom: 0,
-            offsetTop: 0,
-            itemHeight: 0,
-            itemWidth: 0
-          };
+        didMount,
+        withLatestFrom(initialTopMostItemIndex),
+        filter(([_, location]) => !!location)
+      ),
+      () => {
+        publish(scrolledToInitialItem, false);
+        publish(initialItemCount, 0);
+      }
+    );
+    subscribe(
+      pipe(
+        combineLatest(didMount, scrolledToInitialItem, itemDimensions, viewportDimensions, initialTopMostItemIndex, scrollScheduled),
+        filter(([didMount2, scrolledToInitialItem2, itemDimensions2, viewportDimensions2, , scrollScheduled2]) => {
+          return didMount2 && !scrolledToInitialItem2 && itemDimensions2.height !== 0 && viewportDimensions2.height !== 0 && !scrollScheduled2;
         })
       ),
-      gridState
+      ([, , , , initialTopMostItemIndex2]) => {
+        publish(scrollScheduled, true);
+        skipFrames(1, () => {
+          publish(scrollToIndex, initialTopMostItemIndex2);
+        });
+        handleNext(pipe(scrollTop), () => {
+          publish(listBoundary, [0, 0]);
+          publish(scrolledToInitialItem, true);
+        });
+      }
+    );
+    connect(
+      pipe(
+        restoreStateFrom,
+        filter((value) => value !== void 0 && value !== null && value.scrollTop > 0),
+        mapTo(0)
+      ),
+      initialItemCount
+    );
+    subscribe(
+      pipe(
+        didMount,
+        withLatestFrom(restoreStateFrom),
+        filter(([, snapshot]) => snapshot !== void 0 && snapshot !== null)
+      ),
+      ([, snapshot]) => {
+        if (!snapshot) {
+          return;
+        }
+        publish(viewportDimensions, snapshot.viewport), publish(itemDimensions, snapshot == null ? void 0 : snapshot.item);
+        publish(gap, snapshot.gap);
+        if (snapshot.scrollTop > 0) {
+          publish(stateRestoreInProgress, true);
+          handleNext(pipe(scrollTop, skip(1)), (_value) => {
+            publish(stateRestoreInProgress, false);
+          });
+          publish(scrollTo, { top: snapshot.scrollTop });
+        }
+      }
+    );
+    connect(
+      pipe(
+        viewportDimensions,
+        map(({ height }) => height)
+      ),
+      viewportHeight
+    );
+    connect(
+      pipe(
+        combineLatest(
+          duc(viewportDimensions, dimensionComparator),
+          duc(itemDimensions, dimensionComparator),
+          duc(gap, (prev, next) => prev && prev.column === next.column && prev.row === next.row),
+          duc(scrollTop)
+        ),
+        map(([viewport, item, gap2, scrollTop2]) => ({
+          viewport,
+          item,
+          gap: gap2,
+          scrollTop: scrollTop2
+        }))
+      ),
+      stateChanged
     );
     connect(
       pipe(
@@ -3332,65 +3618,104 @@ const gridSystem = /* @__PURE__ */ system(
           duc(gap, gapComparator),
           duc(itemDimensions, dimensionComparator),
           duc(viewportDimensions, dimensionComparator),
-          data
+          duc(data),
+          duc(initialItemCount),
+          duc(stateRestoreInProgress),
+          duc(scrolledToInitialItem),
+          duc(initialTopMostItemIndex)
         ),
-        map(([totalCount2, [startOffset, endOffset], gap2, item, viewport, data2]) => {
-          const { row: rowGap, column: columnGap } = gap2;
-          const { height: itemHeight, width: itemWidth } = item;
-          const { width: viewportWidth } = viewport;
-          if (totalCount2 === 0 || viewportWidth === 0) {
-            return INITIAL_GRID_STATE;
-          }
-          if (itemWidth === 0) {
-            return buildProbeGridState(buildItems(0, 0, data2));
+        filter(([, , , , , , , stateRestoreInProgress2]) => {
+          return !stateRestoreInProgress2;
+        }),
+        map(
+          ([
+            totalCount2,
+            [startOffset, endOffset],
+            gap2,
+            item,
+            viewport,
+            data2,
+            initialItemCount2,
+            ,
+            scrolledToInitialItem2,
+            initialTopMostItemIndex2
+          ]) => {
+            const { row: rowGap, column: columnGap } = gap2;
+            const { height: itemHeight, width: itemWidth } = item;
+            const { width: viewportWidth } = viewport;
+            if (initialItemCount2 === 0 && (totalCount2 === 0 || viewportWidth === 0)) {
+              return INITIAL_GRID_STATE;
+            }
+            if (itemWidth === 0) {
+              const startIndex2 = getInitialTopMostItemIndexNumber(initialTopMostItemIndex2, totalCount2);
+              const endIndex2 = startIndex2 === 0 ? Math.max(initialItemCount2 - 1, 0) : startIndex2;
+              return buildProbeGridState(buildItems(startIndex2, endIndex2, data2));
+            }
+            const perRow = itemsPerRow(viewportWidth, itemWidth, columnGap);
+            let startIndex;
+            let endIndex;
+            if (!scrolledToInitialItem2) {
+              startIndex = 0;
+              endIndex = -1;
+            } else if (startOffset === 0 && endOffset === 0 && initialItemCount2 > 0) {
+              startIndex = 0;
+              endIndex = initialItemCount2 - 1;
+            } else {
+              startIndex = perRow * floor((startOffset + rowGap) / (itemHeight + rowGap));
+              endIndex = perRow * ceil((endOffset + rowGap) / (itemHeight + rowGap)) - 1;
+              endIndex = min(totalCount2 - 1, max(endIndex, perRow - 1));
+              startIndex = min(endIndex, max(0, startIndex));
+            }
+            const items = buildItems(startIndex, endIndex, data2);
+            const { top, bottom } = gridLayout(viewport, gap2, item, items);
+            const rowCount = ceil(totalCount2 / perRow);
+            const totalHeight = rowCount * itemHeight + (rowCount - 1) * rowGap;
+            const offsetBottom = totalHeight - bottom;
+            return { items, offsetTop: top, offsetBottom, top, bottom, itemHeight, itemWidth };
           }
-          const perRow = itemsPerRow(viewportWidth, itemWidth, columnGap);
-          let startIndex = perRow * floor((startOffset + rowGap) / (itemHeight + rowGap));
-          let endIndex = perRow * ceil((endOffset + rowGap) / (itemHeight + rowGap)) - 1;
-          endIndex = min(totalCount2 - 1, max(endIndex, perRow - 1));
-          startIndex = min(endIndex, max(0, startIndex));
-          const items = buildItems(startIndex, endIndex, data2);
-          const { top, bottom } = gridLayout(viewport, gap2, item, items);
-          const rowCount = ceil(totalCount2 / perRow);
-          const totalHeight = rowCount * itemHeight + (rowCount - 1) * rowGap;
-          const offsetBottom = totalHeight - bottom;
-          return { items, offsetTop: top, offsetBottom, top, bottom, itemHeight, itemWidth };
-        })
+        )
       ),
       gridState
     );
     connect(
       pipe(
         data,
-        filter((data2) => data2 !== void 0),
+        filter((data2) => data2 !== null),
         map((data2) => data2.length)
       ),
       totalCount
     );
-    connect(
-      pipe(
-        viewportDimensions,
-        map(({ height }) => height)
-      ),
-      viewportHeight
-    );
     connect(
       pipe(
         combineLatest(viewportDimensions, itemDimensions, gridState, gap),
-        map(([viewportDimensions2, item, { items }, gap2]) => {
-          const { top, bottom } = gridLayout(viewportDimensions2, gap2, item, items);
+        filter(([viewportDimensions2, itemDimensions2, { items }]) => {
+          return items.length > 0 && itemDimensions2.height !== 0 && viewportDimensions2.height !== 0;
+        }),
+        map(([viewportDimensions2, itemDimensions2, { items }, gap2]) => {
+          const { top, bottom } = gridLayout(viewportDimensions2, gap2, itemDimensions2, items);
           return [top, bottom];
         }),
         distinctUntilChanged(tupleComparator)
       ),
       listBoundary
     );
+    const hasScrolled = statefulStream(false);
+    connect(
+      pipe(
+        scrollTop,
+        withLatestFrom(hasScrolled),
+        map(([scrollTop2, hasScrolled2]) => {
+          return hasScrolled2 || scrollTop2 !== 0;
+        })
+      ),
+      hasScrolled
+    );
     const endReached = streamFromEmitter(
       pipe(
         duc(gridState),
         filter(({ items }) => items.length > 0),
-        withLatestFrom(totalCount),
-        filter(([{ items }, totalCount2]) => items[items.length - 1].index === totalCount2 - 1),
+        withLatestFrom(totalCount, hasScrolled),
+        filter(([{ items }, totalCount2, hasScrolled2]) => hasScrolled2 && items[items.length - 1].index === totalCount2 - 1),
         map(([, totalCount2]) => totalCount2 - 1),
         distinctUntilChanged()
       )
@@ -3401,6 +3726,7 @@ const gridSystem = /* @__PURE__ */ system(
         filter(({ items }) => {
           return items.length > 0 && items[0].index === 0;
         }),
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-argument
         mapTo(0),
         distinctUntilChanged()
       )
@@ -3408,14 +3734,16 @@ const gridSystem = /* @__PURE__ */ system(
     const rangeChanged = streamFromEmitter(
       pipe(
         duc(gridState),
-        filter(({ items }) => items.length > 0),
-        map(({ items }) => {
+        withLatestFrom(stateRestoreInProgress),
+        filter(([{ items }, stateRestoreInProgress2]) => items.length > 0 && !stateRestoreInProgress2),
+        map(([{ items }]) => {
           return {
             startIndex: items[0].index,
             endIndex: items[items.length - 1].index
           };
         }),
-        distinctUntilChanged(rangeComparator)
+        distinctUntilChanged(rangeComparator),
+        throttleTime(0)
       )
     );
     connect(rangeChanged, scrollSeek.scrollSeekRangeChanged);
@@ -3423,7 +3751,7 @@ const gridSystem = /* @__PURE__ */ system(
       pipe(
         scrollToIndex,
         withLatestFrom(viewportDimensions, itemDimensions, totalCount, gap),
-        map(([location, viewport, item, totalCount2, gap2]) => {
+        map(([location, viewportDimensions2, itemDimensions2, totalCount2, gap2]) => {
           const normalLocation = normalizeIndexLocation(location);
           const { align, behavior, offset } = normalLocation;
           let index = normalLocation.index;
@@ -3431,11 +3759,11 @@ const gridSystem = /* @__PURE__ */ system(
             index = totalCount2 - 1;
           }
           index = max(0, index, min(totalCount2 - 1, index));
-          let top = itemTop(viewport, gap2, item, index);
+          let top = itemTop(viewportDimensions2, gap2, itemDimensions2, index);
           if (align === "end") {
-            top = round(top - viewport.height + item.height);
+            top = round(top - viewportDimensions2.height + itemDimensions2.height);
           } else if (align === "center") {
-            top = round(top - viewport.height / 2 + item.height / 2);
+            top = round(top - viewportDimensions2.height / 2 + itemDimensions2.height / 2);
           }
           if (offset) {
             top += offset;
@@ -3462,6 +3790,7 @@ const gridSystem = /* @__PURE__ */ system(
       viewportDimensions
     );
     return {
+      // input
       data,
       totalCount,
       viewportDimensions,
@@ -3484,14 +3813,20 @@ const gridSystem = /* @__PURE__ */ system(
       headerHeight,
       initialItemCount,
       gap,
+      restoreStateFrom,
       ...scrollSeek,
+      initialTopMostItemIndex,
+      horizontalDirection,
+      // output
       gridState,
       totalListHeight,
       ...stateFlags,
       startReached,
       endReached,
       rangeChanged,
+      stateChanged,
       propsReady,
+      stateRestoreInProgress,
       ...log
     };
   },
@@ -3513,7 +3848,7 @@ function itemTop(viewport, gap, item, index) {
   return top > 0 ? top + gap.row : top;
 }
 function itemsPerRow(viewportWidth, itemWidth, gap) {
-  return max(1, floor((viewportWidth + gap) / (itemWidth + gap)));
+  return max(1, floor((viewportWidth + gap) / (floor(itemWidth) + gap)));
 }
 const gridComponentPropsSystem = /* @__PURE__ */ system(() => {
   const itemContent = statefulStream((index) => `Item ${index}`);
@@ -3569,18 +3904,23 @@ const GridItems = /* @__PURE__ */ React.memo(function GridItems2() {
   const itemDimensions = usePublisher$1("itemDimensions");
   const gridGap = usePublisher$1("gap");
   const log = useEmitterValue$1("log");
+  const stateRestoreInProgress = useEmitterValue$1("stateRestoreInProgress");
   const listRef = useSize((el) => {
     const scrollHeight = el.parentElement.parentElement.scrollHeight;
     scrollHeightCallback(scrollHeight);
     const firstItem = el.firstChild;
     if (firstItem) {
-      itemDimensions(firstItem.getBoundingClientRect());
+      const { width, height } = firstItem.getBoundingClientRect();
+      itemDimensions({ width, height });
     }
     gridGap({
       row: resolveGapValue("row-gap", getComputedStyle(el).rowGap, log),
       column: resolveGapValue("column-gap", getComputedStyle(el).columnGap, log)
     });
   });
+  if (stateRestoreInProgress) {
+    return null;
+  }
   return React.createElement(
     ListComponent,
     {
@@ -3588,7 +3928,7 @@ const GridItems = /* @__PURE__ */ React.memo(function GridItems2() {
       className: listClassName,
       ...contextPropIfNotDomElement(ListComponent, context),
       style: { paddingTop: gridState.offsetTop, paddingBottom: gridState.offsetBottom },
-      "data-test-id": "virtuoso-item-list"
+      "data-testid": "virtuoso-item-list"
     },
     gridState.items.map((item) => {
       const key = computeItemKey(item.index, item.data, context);
@@ -3635,7 +3975,7 @@ const Viewport$1 = ({ children }) => {
       itemDimensions({ height: ctx.itemHeight, width: ctx.itemWidth });
     }
   }, [ctx, viewportDimensions, itemDimensions]);
-  return /* @__PURE__ */ React.createElement("div", { style: viewportStyle, ref: viewportRef }, children);
+  return /* @__PURE__ */ React.createElement("div", { style: viewportStyle(false), ref: viewportRef }, children);
 };
 const WindowViewport$1 = ({ children }) => {
   const ctx = React.useContext(VirtuosoGridMockContext);
@@ -3649,7 +3989,7 @@ const WindowViewport$1 = ({ children }) => {
       windowViewportRect({ offsetTop: 0, visibleHeight: ctx.viewportHeight, visibleWidth: ctx.viewportWidth });
     }
   }, [ctx, windowViewportRect, itemDimensions]);
-  return /* @__PURE__ */ React.createElement("div", { ref: viewportRef, style: viewportStyle }, children);
+  return /* @__PURE__ */ React.createElement("div", { ref: viewportRef, style: viewportStyle(false) }, children);
 };
 const GridRoot = /* @__PURE__ */ React.memo(function GridRoot2({ ...props }) {
   const useWindowScroll = useEmitterValue$1("useWindowScroll");
@@ -3681,7 +4021,10 @@ const {
       itemClassName: "itemClassName",
       useWindowScroll: "useWindowScroll",
       customScrollParent: "customScrollParent",
-      scrollerRef: "scrollerRef"
+      scrollerRef: "scrollerRef",
+      logLevel: "logLevel",
+      restoreStateFrom: "restoreStateFrom",
+      initialTopMostItemIndex: "initialTopMostItemIndex"
     },
     methods: {
       scrollTo: "scrollTo",
@@ -3694,7 +4037,8 @@ const {
       startReached: "startReached",
       rangeChanged: "rangeChanged",
       atBottomStateChange: "atBottomStateChange",
-      atTopStateChange: "atTopStateChange"
+      atTopStateChange: "atTopStateChange",
+      stateChanged: "stateChanged"
     }
   },
   GridRoot
@@ -3708,7 +4052,7 @@ function resolveGapValue(property, value, log) {
   if (value === "normal") {
     return 0;
   }
-  return parseInt(value ?? "0", 10);
+  return parseInt(value != null ? value : "0", 10);
 }
 const VirtuosoGrid = Grid;
 const tableComponentPropsSystem = /* @__PURE__ */ system(() => {
@@ -3753,6 +4097,7 @@ const combinedSystem = /* @__PURE__ */ system(([listSystem2, propsSystem]) => {
 }, tup(listSystem, tableComponentPropsSystem));
 const DefaultScrollSeekPlaceholder = ({ height }) => /* @__PURE__ */ React.createElement("tr", null, /* @__PURE__ */ React.createElement("td", { style: { height } }));
 const DefaultFillerRow = ({ height }) => /* @__PURE__ */ React.createElement("tr", null, /* @__PURE__ */ React.createElement("td", { style: { height, padding: 0, border: 0 } }));
+const ITEM_STYLE = { overflowAnchor: "none" };
 const Items = /* @__PURE__ */ React.memo(function VirtuosoItems2() {
   const listState = useEmitterValue("listState");
   const sizeRanges = usePublisher("sizeRanges");
@@ -3815,19 +4160,19 @@ const Items = /* @__PURE__ */ React.memo(function VirtuosoItems2() {
       TableRowComponent,
       {
         ...contextPropIfNotDomElement(TableRowComponent, context),
+        ...itemPropIfNotDomElement(TableRowComponent, item.data),
         key,
         "data-index": index,
         "data-known-size": item.size,
         "data-item-index": item.index,
-        item: item.data,
-        style: { overflowAnchor: "none" }
+        style: ITEM_STYLE
       },
       itemContent(item.index, item.data, context)
     );
   });
   return React.createElement(
     TableBodyComponent,
-    { ref: callbackRef, "data-test-id": "virtuoso-item-list", ...contextPropIfNotDomElement(TableBodyComponent, context) },
+    { ref: callbackRef, "data-testid": "virtuoso-item-list", ...contextPropIfNotDomElement(TableBodyComponent, context) },
     [paddingTopEl, ...items, paddingBottomEl]
   );
 });
@@ -3842,7 +4187,7 @@ const Viewport = ({ children }) => {
       fixedItemHeight(ctx.itemHeight);
     }
   }, [ctx, viewportHeight, fixedItemHeight]);
-  return /* @__PURE__ */ React.createElement("div", { style: viewportStyle, ref: viewportRef, "data-viewport-type": "element" }, children);
+  return /* @__PURE__ */ React.createElement("div", { style: viewportStyle(false), ref: viewportRef, "data-viewport-type": "element" }, children);
 };
 const WindowViewport = ({ children }) => {
   const ctx = React.useContext(VirtuosoMockContext);
@@ -3856,7 +4201,7 @@ const WindowViewport = ({ children }) => {
       windowViewportRect({ offsetTop: 0, visibleHeight: ctx.viewportHeight, visibleWidth: 100 });
     }
   }, [ctx, windowViewportRect, fixedItemHeight]);
-  return /* @__PURE__ */ React.createElement("div", { ref: viewportRef, style: viewportStyle, "data-viewport-type": "window" }, children);
+  return /* @__PURE__ */ React.createElement("div", { ref: viewportRef, style: viewportStyle(false), "data-viewport-type": "window" }, children);
 };
 const TableRoot = /* @__PURE__ */ React.memo(function TableVirtuosoRoot(props) {
   const useWindowScroll = useEmitterValue("useWindowScroll");
@@ -3877,7 +4222,7 @@ const TableRoot = /* @__PURE__ */ React.memo(function TableVirtuosoRoot(props) {
     TheTHead,
     {
       key: "TableHead",
-      style: { zIndex: 1, position: "sticky", top: 0 },
+      style: { zIndex: 2, position: "sticky", top: 0 },
       ref: theadRef,
       ...contextPropIfNotDomElement(TheTHead, context)
     },
@@ -3893,11 +4238,11 @@ const TableRoot = /* @__PURE__ */ React.memo(function TableVirtuosoRoot(props) {
     },
     fixedFooterContent()
   ) : null;
-  return /* @__PURE__ */ React.createElement(TheScroller, { ...props }, /* @__PURE__ */ React.createElement(TheViewport, null, React.createElement(TheTable, { style: { borderSpacing: 0 }, ...contextPropIfNotDomElement(TheTable, context) }, [
-    theHead,
-    /* @__PURE__ */ React.createElement(Items, { key: "TableBody" }),
-    theFoot
-  ])));
+  return /* @__PURE__ */ React.createElement(TheScroller, { ...props }, /* @__PURE__ */ React.createElement(TheViewport, null, React.createElement(
+    TheTable,
+    { style: { borderSpacing: 0, overflowAnchor: "none" }, ...contextPropIfNotDomElement(TheTable, context) },
+    [theHead, /* @__PURE__ */ React.createElement(Items, { key: "TableBody" }), theFoot]
+  )));
 });
 const {
   Component: Table,
@@ -3909,6 +4254,7 @@ const {
   {
     required: {},
     optional: {
+      restoreStateFrom: "restoreStateFrom",
       context: "context",
       followOutput: "followOutput",
       firstItemIndex: "firstItemIndex",
@@ -3942,7 +4288,8 @@ const {
       scrollToIndex: "scrollToIndex",
       scrollIntoView: "scrollIntoView",
       scrollTo: "scrollTo",
-      scrollBy: "scrollBy"
+      scrollBy: "scrollBy",
+      getState: "getState"
     },
     events: {
       isScrolling: "isScrolling",