@legendapp/list 3.3.0 → 3.3.1

package/CHANGELOG.md

@@ -1,3 +1,10 @@
+## 3.3.1
+
+- Perf: Animated `scrollToIndex` and `scrollToOffset` calls now mount the destination rows before native scrolling starts, so long programmatic jumps are less likely to show blank space at the target.
+- Perf: Fast scrolling shifts more of the render buffer in the direction of travel and settles back after scrolling stops, so rows ahead of the user are ready sooner without keeping the buffer displaced afterward.
+- Perf: Scroll velocity favors recent movement and ignores stale samples, preventing old scroll events from keeping the render buffer pointed in the wrong direction after scrolling slows or stops.
+- Perf: On Fabric, row measurements wait for all expected layout-effect measurements before recalculating positions, reducing the number of computations while scrolling quickly.
+
 ## 3.3.0
 
 - Feat: Add `dataKey` so apps can tell the list when the current array represents a different dataset, such as switching conversations or feeds without remounting `LegendList`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@legendapp/list",
-  "version": "3.3.0",
+  "version": "3.3.1",
   "description": "Legend List is a drop-in replacement for FlatList with much better performance and supporting dynamically sized items.",
   "sideEffects": false,
   "private": false,

package/react-native.js

@@ -1534,6 +1534,7 @@ function finishScrollTo(ctx) {
     const scrollingTo = state.scrollingTo;
     state.scrollHistory.length = 0;
     state.scrollingTo = void 0;
+    state.scrollTargetPinnedRange = void 0;
     if (state.pendingTotalSize !== void 0) {
       addTotalSize(ctx, null, state.pendingTotalSize);
     }
@@ -2173,6 +2174,8 @@ var flushSync = (fn) => {
 };
 
 // src/utils/getScrollVelocity.ts
+var MAX_SCROLL_VELOCITY_WINDOW_MS = 1e3;
+var SCROLL_VELOCITY_HALF_LIFE_MS = 200;
 var getScrollVelocity = (state) => {
   const { scrollHistory } = state;
   const newestIndex = scrollHistory.length - 1;
@@ -2180,35 +2183,37 @@ var getScrollVelocity = (state) => {
     return 0;
   }
   const newest = scrollHistory[newestIndex];
-  const now = Date.now();
-  let direction = 0;
-  for (let i = newestIndex; i > 0; i--) {
-    const delta = scrollHistory[i].scroll - scrollHistory[i - 1].scroll;
-    if (delta !== 0) {
-      direction = Math.sign(delta);
-      break;
-    }
-  }
-  if (direction === 0) {
+  if (Date.now() - newest.time > MAX_SCROLL_VELOCITY_WINDOW_MS) {
     return 0;
   }
-  let oldest = newest;
-  for (let i = newestIndex - 1; i >= 0; i--) {
+  let direction = 0;
+  let weightedVelocity = 0;
+  let totalWeight = 0;
+  for (let i = newestIndex; i > 0; i--) {
     const current = scrollHistory[i];
-    const next = scrollHistory[i + 1];
-    const delta = next.scroll - current.scroll;
-    const deltaSign = Math.sign(delta);
-    if (deltaSign !== 0 && deltaSign !== direction) {
-      break;
+    const previous = scrollHistory[i - 1];
+    const scrollDiff = current.scroll - previous.scroll;
+    const timeDiff = current.time - previous.time;
+    const deltaSign = Math.sign(scrollDiff);
+    if (deltaSign !== 0) {
+      if (direction === 0) {
+        direction = deltaSign;
+      } else if (deltaSign !== direction) {
+        break;
+      }
     }
-    if (now - current.time > 1e3) {
+    if (newest.time - previous.time > MAX_SCROLL_VELOCITY_WINDOW_MS) {
       break;
     }
-    oldest = current;
+    if (scrollDiff === 0 || timeDiff <= 0) {
+      continue;
+    }
+    const age = newest.time - current.time;
+    const weight = Math.exp(-age / SCROLL_VELOCITY_HALF_LIFE_MS);
+    weightedVelocity += scrollDiff / timeDiff * weight;
+    totalWeight += weight;
   }
-  const scrollDiff = newest.scroll - oldest.scroll;
-  const timeDiff = newest.time - oldest.time;
-  return timeDiff > 0 ? scrollDiff / timeDiff : 0;
+  return totalWeight > 0 ? weightedVelocity / totalWeight : 0;
 };
 
 // src/core/updateScroll.ts
@@ -2325,8 +2330,93 @@ function syncInitialScrollNativeWatchdog(state, options) {
     initialScrollWatchdog.clear(state);
   }
 }
-function scrollTo(ctx, params) {
+function findPositionIndexAtOrBeforeOffset(ctx, offset) {
+  const state = ctx.state;
+  const dataLength = state.props.data.length;
+  let low = 0;
+  let high = dataLength - 1;
+  let match;
+  while (low <= high) {
+    const mid = Math.floor((low + high) / 2);
+    const top = state.positions[mid];
+    if (top === void 0) {
+      high = mid - 1;
+    } else {
+      if (top <= offset) {
+        match = mid;
+        low = mid + 1;
+      } else {
+        high = mid - 1;
+      }
+    }
+  }
+  return match;
+}
+function getItemBottom(ctx, index) {
   var _a3;
+  const top = ctx.state.positions[index];
+  if (top === void 0) {
+    return void 0;
+  }
+  const itemSize = (_a3 = getItemSizeAtIndex(ctx, index)) != null ? _a3 : 0;
+  return top + (Number.isFinite(itemSize) ? itemSize : 0);
+}
+function getTargetViewportRenderRange(ctx, targetOffset, targetIndex) {
+  const state = ctx.state;
+  const dataLength = state.props.data.length;
+  if (dataLength === 0) {
+    return void 0;
+  }
+  const viewportStart = Math.max(0, targetOffset);
+  const viewportEnd = Math.max(viewportStart, targetOffset + state.scrollLength);
+  let start = targetIndex !== void 0 ? Math.max(0, Math.min(dataLength - 1, targetIndex)) : findPositionIndexAtOrBeforeOffset(ctx, viewportStart);
+  if (start === void 0) {
+    return void 0;
+  }
+  if (targetIndex !== void 0 && state.positions[start] === void 0) {
+    return { end: start, start };
+  }
+  if (targetIndex === void 0) {
+    const startBottom = getItemBottom(ctx, start);
+    if (startBottom === void 0 || startBottom <= viewportStart) {
+      return void 0;
+    }
+  }
+  while (start > 0) {
+    const top = state.positions[start];
+    if (top === void 0 || top <= viewportStart || state.positions[start - 1] === void 0) {
+      break;
+    }
+    start--;
+  }
+  while (start > 0) {
+    const previousBottom = getItemBottom(ctx, start - 1);
+    if (previousBottom === void 0 || previousBottom <= viewportStart) {
+      break;
+    }
+    start--;
+  }
+  let end = start;
+  while (end + 1 < dataLength) {
+    const nextTop = state.positions[end + 1];
+    if (nextTop === void 0 || nextTop > viewportEnd) {
+      break;
+    }
+    end++;
+  }
+  return { end, start };
+}
+function pinScrollTargetRenderRange(ctx, targetOffset, targetIndex) {
+  const range = getTargetViewportRenderRange(ctx, targetOffset, targetIndex);
+  if (range) {
+    ctx.state.scrollTargetPinnedRange = range;
+    ctx.state.scrollForNextCalculateItemsInView = void 0;
+  } else {
+    ctx.state.scrollTargetPinnedRange = void 0;
+  }
+}
+function scrollTo(ctx, params) {
+  var _a3, _b;
   const state = ctx.state;
   const { noScrollingTo, forceScroll, ...scrollTarget } = params;
   const {
@@ -2361,11 +2451,20 @@ function scrollTo(ctx, params) {
       targetOffset,
       waitForInitialScrollCompletionFrame
     };
+    if (!isInitialScroll) {
+      pinScrollTargetRenderRange(ctx, targetOffset, scrollTarget.index);
+    }
   }
   state.scrollPending = targetOffset;
   syncInitialScrollNativeWatchdog(state, { isInitialScroll, requestedOffset: offset, targetOffset });
-  if (!animated && !isInitialScroll && !noScrollingTo && Math.abs(state.scroll - targetOffset) > 1) {
-    updateScroll(ctx, targetOffset, false, { markHasScrolled: false });
+  if (!isInitialScroll && !noScrollingTo && Math.abs(state.scroll - targetOffset) > 1) {
+    if (animated) {
+      if (state.scrollTargetPinnedRange) {
+        (_b = state.triggerCalculateItemsInView) == null ? void 0 : _b.call(state);
+      }
+    } else {
+      updateScroll(ctx, targetOffset, true, { markHasScrolled: false });
+    }
   }
   if (forceScroll || !isInitialScroll || Platform.OS === "android") {
     doScrollTo(ctx, { animated, horizontal, isInitialScroll, offset });
@@ -4037,6 +4136,32 @@ function setDidLayout(ctx) {
 }
 
 // src/core/calculateItemsInView.ts
+var RENDER_RANGE_PROJECTION_FULL_VELOCITY = 4;
+var RENDER_RANGE_PROJECTION_SETTLE_DELAY = 100;
+function getProjectedBufferAdjustment(scrollVelocity, trailingBuffer) {
+  if (trailingBuffer <= 0) {
+    return 0;
+  }
+  const velocityProgress = Math.min(1, Math.abs(scrollVelocity) / RENDER_RANGE_PROJECTION_FULL_VELOCITY);
+  return Math.sign(scrollVelocity) * trailingBuffer * velocityProgress;
+}
+function scheduleRenderRangeProjectionSettle(ctx) {
+  const state = ctx.state;
+  const previousTimeout = state.timeoutRenderRangeProjectionSettle;
+  if (previousTimeout !== void 0) {
+    clearTimeout(previousTimeout);
+    state.timeouts.delete(previousTimeout);
+  }
+  const timeout = setTimeout(() => {
+    var _a3;
+    state.timeoutRenderRangeProjectionSettle = void 0;
+    state.timeouts.delete(timeout);
+    state.scrollHistory.length = 0;
+    (_a3 = state.triggerCalculateItemsInView) == null ? void 0 : _a3.call(state);
+  }, RENDER_RANGE_PROJECTION_SETTLE_DELAY);
+  state.timeoutRenderRangeProjectionSettle = timeout;
+  state.timeouts.add(timeout);
+}
 function findCurrentStickyIndex(stickyArray, scroll, state) {
   const positions = state.positions;
   for (let i = stickyArray.length - 1; i >= 0; i--) {
@@ -4077,14 +4202,14 @@ function handleStickyActivation(ctx, stickyArray, currentStickyIdx, needNewConta
     }
   }
 }
-function handleStickyRecycling(ctx, stickyArray, scroll, drawDistance, currentStickyIdx, pendingRemoval, alwaysRenderIndicesSet) {
+function handleStickyRecycling(ctx, stickyArray, scroll, drawDistance, currentStickyIdx, pendingRemoval, isPinnedRenderIndex) {
   var _a3, _b;
   const state = ctx.state;
   for (const containerIndex of state.stickyContainerPool) {
     const itemKey = peek$(ctx, `containerItemKey${containerIndex}`);
     const itemIndex = itemKey ? state.indexByKey.get(itemKey) : void 0;
     if (itemIndex === void 0) continue;
-    if (alwaysRenderIndicesSet.has(itemIndex)) continue;
+    if (isPinnedRenderIndex(itemIndex)) continue;
     const arrayIdx = stickyArray.indexOf(itemIndex);
     if (arrayIdx === -1) {
       state.stickyContainerPool.delete(containerIndex);
@@ -4248,8 +4373,6 @@ function calculateItemsInView(ctx, params = {}) {
     const { data } = state.props;
     const stickyHeaderIndicesArr = state.props.stickyHeaderIndicesArr || [];
     const stickyHeaderIndicesSet = state.props.stickyHeaderIndicesSet || /* @__PURE__ */ new Set();
-    const alwaysRenderArr = alwaysRenderIndicesArr || [];
-    const alwaysRenderSet = alwaysRenderIndicesSet || /* @__PURE__ */ new Set();
     const drawDistance = getEffectiveDrawDistance(ctx, params.drawDistanceMode);
     const { dataChanged, doMVCP, forceFullItemPositions } = params;
     const bootstrapInitialScrollState = ((_a3 = state.initialScrollSession) == null ? void 0 : _a3.kind) === "bootstrap" ? state.initialScrollSession.bootstrap : void 0;
@@ -4316,14 +4439,19 @@ function calculateItemsInView(ctx, params = {}) {
       scrollBufferTop = drawDistance * 1.5;
       scrollBufferBottom = drawDistance * 0.5;
     }
+    const shouldProjectRenderRange = !dataChanged && !forceFullItemPositions && !suppressInitialScrollSideEffects && !hasActiveInitialScroll(state) && !state.scrollingTo && !state.pendingNativeMVCPAdjust && !!peek$(ctx, "readyToRender");
+    const projectedBufferAdjustment = shouldProjectRenderRange ? getProjectedBufferAdjustment(speed, Math.min(scrollBufferTop, scrollBufferBottom)) : 0;
     const updateScrollRange = () => {
       const scrollStart = Math.max(0, scroll);
       const overscrollBeforeContent = Math.max(0, -nativeScrollState);
-      scrollTopBuffered = scrollStart - scrollBufferTop;
       scrollBottom = Math.max(scrollStart, scroll + scrollLength + overscrollBeforeContent);
-      scrollBottomBuffered = scrollBottom + scrollBufferBottom;
+      scrollTopBuffered = scrollStart - scrollBufferTop + projectedBufferAdjustment;
+      scrollBottomBuffered = scrollBottom + scrollBufferBottom + projectedBufferAdjustment;
     };
     updateScrollRange();
+    if (projectedBufferAdjustment !== 0) {
+      scheduleRenderRangeProjectionSettle(ctx);
+    }
     if (enableScrollForNextCalculateItemsInView && !suppressInitialScrollSideEffects && !dataChanged && !forceFullItemPositions && scrollForNextCalculateItemsInView) {
       const { top, bottom } = scrollForNextCalculateItemsInView;
       if (top === null && bottom === null) {
@@ -4481,9 +4609,34 @@ function calculateItemsInView(ctx, params = {}) {
         }
       }
     }
+    const scrollTargetPinnedRange = state.scrollTargetPinnedRange;
+    let scrollTargetPinnedStart = 0;
+    let scrollTargetPinnedEnd = -1;
+    if (scrollTargetPinnedRange) {
+      scrollTargetPinnedStart = Math.max(0, Math.min(scrollTargetPinnedRange.start, scrollTargetPinnedRange.end));
+      scrollTargetPinnedEnd = Math.min(
+        dataLength - 1,
+        Math.max(scrollTargetPinnedRange.start, scrollTargetPinnedRange.end)
+      );
+    }
+    const hasScrollTargetPinnedRange = scrollTargetPinnedStart <= scrollTargetPinnedEnd;
+    const isPinnedRenderIndex = (index) => alwaysRenderIndicesSet.has(index) || hasScrollTargetPinnedRange && index >= scrollTargetPinnedStart && index <= scrollTargetPinnedEnd;
     if (startBuffered !== null && endBuffered !== null) {
       const needNewContainers = [];
       const needNewContainersSet = /* @__PURE__ */ new Set();
+      const addPinnedIndex = (index) => {
+        var _a4;
+        if (index >= 0 && index < dataLength) {
+          const id = (_a4 = idCache[index]) != null ? _a4 : getId(state, index);
+          const containerIndex = containerItemKeys.get(id);
+          if (containerIndex !== void 0) {
+            state.stickyContainerPool.add(containerIndex);
+          } else if (!isNullOrUndefined(id) && !needNewContainersSet.has(index)) {
+            needNewContainersSet.add(index);
+            needNewContainers.push(index);
+          }
+        }
+      };
       for (let i = startBuffered; i <= endBuffered; i++) {
         const id = (_m = idCache[i]) != null ? _m : getId(state, i);
         if (!containerItemKeys.has(id)) {
@@ -4491,21 +4644,19 @@ function calculateItemsInView(ctx, params = {}) {
           needNewContainers.push(i);
         }
       }
-      if (alwaysRenderArr.length > 0) {
-        for (const index of alwaysRenderArr) {
-          if (index < 0 || index >= dataLength) continue;
-          const id = (_n = idCache[index]) != null ? _n : getId(state, index);
-          if (id && !containerItemKeys.has(id) && !needNewContainersSet.has(index)) {
-            needNewContainersSet.add(index);
-            needNewContainers.push(index);
-          }
+      for (const index of alwaysRenderIndicesArr) {
+        addPinnedIndex(index);
+      }
+      if (hasScrollTargetPinnedRange) {
+        for (let index = scrollTargetPinnedStart; index <= scrollTargetPinnedEnd; index++) {
+          addPinnedIndex(index);
         }
       }
       if (stickyHeaderIndicesArr.length > 0) {
         handleStickyActivation(
           ctx,
           stickyHeaderIndicesArr,
-          (_o = stickyState == null ? void 0 : stickyState.currentStickyIdx) != null ? _o : -1,
+          (_n = stickyState == null ? void 0 : stickyState.currentStickyIdx) != null ? _n : -1,
           needNewContainers,
           needNewContainersSet,
           startBuffered,
@@ -4531,7 +4682,7 @@ function calculateItemsInView(ctx, params = {}) {
         for (const allocation of availableContainerAllocations) {
           const i = allocation.itemIndex;
           const containerIndex = allocation.containerIndex;
-          const id = (_p = idCache[i]) != null ? _p : getId(state, i);
+          const id = (_o = idCache[i]) != null ? _o : getId(state, i);
           const oldKey = peek$(ctx, `containerItemKey${containerIndex}`);
           if (oldKey && oldKey !== id) {
             containerItemKeys.delete(oldKey);
@@ -4542,10 +4693,14 @@ function calculateItemsInView(ctx, params = {}) {
             state.containerItemTypes.set(containerIndex, allocation.itemType);
           }
           containerItemKeys.set(id, containerIndex);
-          (_q = state.userScrollAnchorReset) == null ? void 0 : _q.keys.add(id);
+          (_p = state.userScrollAnchorReset) == null ? void 0 : _p.keys.add(id);
+          if (IsNewArchitecture) {
+            (_q = state.pendingLayoutEffectMeasurements) != null ? _q : state.pendingLayoutEffectMeasurements = /* @__PURE__ */ new Set();
+            state.pendingLayoutEffectMeasurements.add(id);
+          }
           const containerSticky = `containerSticky${containerIndex}`;
           const isSticky = stickyHeaderIndicesSet.has(i);
-          const isAlwaysRender = alwaysRenderSet.has(i);
+          const isPinnedRender = isPinnedRenderIndex(i);
           if (isSticky) {
             set$(ctx, containerSticky, true);
             state.stickyContainerPool.add(containerIndex);
@@ -4553,9 +4708,9 @@ function calculateItemsInView(ctx, params = {}) {
             if (peek$(ctx, containerSticky)) {
               set$(ctx, containerSticky, false);
             }
-            if (isAlwaysRender) {
+            if (isPinnedRender) {
               state.stickyContainerPool.add(containerIndex);
-            } else if (state.stickyContainerPool.has(containerIndex)) {
+            } else {
               state.stickyContainerPool.delete(containerIndex);
             }
           }
@@ -4570,20 +4725,8 @@ function calculateItemsInView(ctx, params = {}) {
           }
         }
       }
-      if (state.userScrollAnchorReset) {
-        if (state.userScrollAnchorReset.keys.size === 0) {
-          state.userScrollAnchorReset = void 0;
-        }
-      }
-      if (alwaysRenderArr.length > 0) {
-        for (const index of alwaysRenderArr) {
-          if (index < 0 || index >= dataLength) continue;
-          const id = (_r = idCache[index]) != null ? _r : getId(state, index);
-          const containerIndex = containerItemKeys.get(id);
-          if (containerIndex !== void 0) {
-            state.stickyContainerPool.add(containerIndex);
-          }
-        }
+      if (((_r = state.userScrollAnchorReset) == null ? void 0 : _r.keys.size) === 0) {
+        state.userScrollAnchorReset = void 0;
       }
     }
     if (state.stickyContainerPool.size > 0) {
@@ -4594,7 +4737,7 @@ function calculateItemsInView(ctx, params = {}) {
         drawDistance,
         (_s = stickyState == null ? void 0 : stickyState.currentStickyIdx) != null ? _s : -1,
         pendingRemoval,
-        alwaysRenderSet
+        isPinnedRenderIndex
       );
     }
     const pendingRemovalSet = pendingRemoval.length > 0 ? new Set(pendingRemoval) : void 0;
@@ -4766,6 +4909,36 @@ function mergeItemSizeUpdateResult(result, next) {
   result.needsRecalculate || (result.needsRecalculate = next.needsRecalculate);
   result.shouldMaintainScrollAtEnd || (result.shouldMaintainScrollAtEnd = next.shouldMaintainScrollAtEnd);
 }
+var batchedItemSizeRecalculates = /* @__PURE__ */ new WeakMap();
+function flushBatchedItemSizeRecalculate(ctx, didFallback = false, expectedResult) {
+  const result = batchedItemSizeRecalculates.get(ctx);
+  if (!result || expectedResult && result !== expectedResult) {
+    return;
+  }
+  batchedItemSizeRecalculates.delete(ctx);
+  if (didFallback) {
+    ctx.state.pendingLayoutEffectMeasurements = void 0;
+  }
+  flushItemSizeUpdates(ctx, result);
+}
+function queueItemSizeRecalculate(ctx, result) {
+  var _a3, _b;
+  const batch = batchedItemSizeRecalculates.get(ctx);
+  if (batch) {
+    mergeItemSizeUpdateResult(batch, result);
+  } else {
+    const nextBatch = { ...result };
+    batchedItemSizeRecalculates.set(ctx, nextBatch);
+    if ((_a3 = ctx.state.pendingLayoutEffectMeasurements) == null ? void 0 : _a3.size) {
+      requestAnimationFrame(() => {
+        flushBatchedItemSizeRecalculate(ctx, true, nextBatch);
+      });
+    }
+  }
+  if (!((_b = ctx.state.pendingLayoutEffectMeasurements) == null ? void 0 : _b.size)) {
+    flushBatchedItemSizeRecalculate(ctx);
+  }
+}
 function flushItemSizeUpdates(ctx, result) {
   var _a3;
   const state = ctx.state;
@@ -4782,12 +4955,22 @@ function flushItemSizeUpdates(ctx, result) {
 function updateItemSizes(ctx, measurement) {
   var _a3, _b, _c, _d;
   const state = ctx.state;
+  let didDrainLayoutEffectMeasurements = false;
+  if (IsNewArchitecture && measurement.fromLayoutEffect) {
+    const pendingLayoutEffectMeasurements = state.pendingLayoutEffectMeasurements;
+    if ((pendingLayoutEffectMeasurements == null ? void 0 : pendingLayoutEffectMeasurements.delete(measurement.itemKey)) && pendingLayoutEffectMeasurements.size === 0) {
+      state.pendingLayoutEffectMeasurements = void 0;
+      didDrainLayoutEffectMeasurements = true;
+    }
+  }
   const pendingKeys = (_a3 = state.userScrollAnchorReset) == null ? void 0 : _a3.keys;
   const shouldBatchPendingMeasurements = IsNewArchitecture && measurement.fromLayoutEffect && !!(pendingKeys == null ? void 0 : pendingKeys.size);
+  const shouldQueueRecalculate = IsNewArchitecture && !!measurement.fromLayoutEffect;
+  let result;
   if (!shouldBatchPendingMeasurements) {
-    flushItemSizeUpdates(ctx, applyItemSize(ctx, measurement.itemKey, measurement.size));
+    result = applyItemSize(ctx, measurement.itemKey, measurement.size);
   } else {
-    const result = {};
+    result = {};
     const updateContainerItemSize = (itemKey, containerId, size) => {
       if (containerId !== void 0 && peek$(ctx, `containerItemKey${containerId}`) === itemKey) {
         mergeItemSizeUpdateResult(result, applyItemSize(ctx, itemKey, size));
@@ -4805,8 +4988,15 @@ function updateItemSizes(ctx, measurement) {
         });
       }
     }
+  }
+  if (shouldQueueRecalculate && result.needsRecalculate) {
+    queueItemSizeRecalculate(ctx, result);
+  } else {
     flushItemSizeUpdates(ctx, result);
   }
+  if (didDrainLayoutEffectMeasurements) {
+    flushBatchedItemSizeRecalculate(ctx);
+  }
 }
 function applyItemSize(ctx, itemKey, sizeObj) {
   var _a3;