@legendapp/list 2.1.0-beta.7 → 2.1.0-beta.9

package/index.mjs

@@ -292,6 +292,16 @@ function getPadding(s, type) {
 function extractPadding(style, contentContainerStyle, type) {
   return getPadding(style, type) + getPadding(contentContainerStyle, type);
 }
+function findContainerId(ctx, key) {
+  const numContainers = peek$(ctx, "numContainers");
+  for (let i = 0; i < numContainers; i++) {
+    const itemKey = peek$(ctx, `containerItemKey${i}`);
+    if (itemKey === key) {
+      return i;
+    }
+  }
+  return -1;
+}
 
 // src/state/ContextContainer.ts
 var ContextContainer = createContext(null);
@@ -1175,26 +1185,6 @@ function calculateOffsetForIndex(ctx, state, index) {
   return position;
 }
 
-// src/core/checkActualChange.ts
-function checkActualChange(state, dataProp, previousData) {
-  if (!previousData || !dataProp || dataProp.length !== previousData.length) {
-    return true;
-  }
-  const {
-    idCache,
-    props: { keyExtractor }
-  } = state;
-  for (let i = 0; i < dataProp.length; i++) {
-    if (dataProp[i] !== previousData[i]) {
-      return true;
-    }
-    if (keyExtractor ? idCache[i] !== keyExtractor(previousData[i], i) : dataProp[i] !== previousData[i]) {
-      return true;
-    }
-  }
-  return false;
-}
-
 // src/utils/setPaddingTop.ts
 function setPaddingTop(ctx, state, { stylePaddingTop, alignItemsPaddingTop }) {
   if (stylePaddingTop !== void 0) {
@@ -1284,7 +1274,7 @@ function setSize(ctx, state, itemKey, size) {
 }
 
 // src/utils/getItemSize.ts
-function getItemSize(ctx, state, key, index, data, useAverageSize) {
+function getItemSize(ctx, state, key, index, data, useAverageSize, preferCachedSize) {
   var _a3, _b;
   const {
     sizesKnown,
@@ -1299,6 +1289,12 @@ function getItemSize(ctx, state, key, index, data, useAverageSize) {
   let size;
   const itemType = getItemType ? (_a3 = getItemType(data, index)) != null ? _a3 : "" : "";
   const scrollingTo = peek$(ctx, "scrollingTo");
+  if (preferCachedSize) {
+    const cachedSize = sizes.get(key);
+    if (cachedSize !== void 0) {
+      return cachedSize;
+    }
+  }
   if (getFixedItemSize) {
     size = getFixedItemSize(index, data, itemType);
     if (size !== void 0) {
@@ -1508,14 +1504,13 @@ function updateScroll(ctx, state, newScroll, forceUpdate) {
 
 // src/core/finishScrollTo.ts
 function finishScrollTo(ctx, state) {
-  var _a3;
+  var _a3, _b;
   if (state) {
     state.scrollHistory.length = 0;
     state.initialScroll = void 0;
-    state.isOptimizingItemPositions = false;
     set$(ctx, "scrollingTo", void 0);
     if ((_a3 = state.props) == null ? void 0 : _a3.data) {
-      calculateItemsInView(ctx, state, { forceFullItemPositions: true });
+      (_b = state.triggerCalculateItemsInView) == null ? void 0 : _b.call(state, { forceFullItemPositions: true });
     }
   }
 }
@@ -1524,14 +1519,14 @@ function finishScrollTo(ctx, state) {
 function scrollTo(ctx, state, params) {
   var _a3;
   const { noScrollingTo, ...scrollTarget } = params;
-  const { animated, isInitialScroll, offset: scrollTargetOffset } = scrollTarget;
+  const { animated, isInitialScroll, offset: scrollTargetOffset, precomputedWithViewOffset } = scrollTarget;
   const {
     refScroller,
     props: { horizontal }
   } = state;
-  let offset = calculateOffsetWithOffsetPosition(ctx, state, scrollTargetOffset, scrollTarget);
+  let offset = precomputedWithViewOffset ? scrollTargetOffset : calculateOffsetWithOffsetPosition(ctx, state, scrollTargetOffset, scrollTarget);
   if (Number.isFinite(state.scrollLength) && Number.isFinite(state.totalSize)) {
-    const maxOffset = Math.max(0, state.totalSize - state.scrollLength);
+    const maxOffset = Math.max(0, getContentSize(ctx) - state.scrollLength);
     offset = Math.min(offset, maxOffset);
   }
   state.scrollHistory.length = 0;
@@ -1763,14 +1758,14 @@ function updateItemPositions(ctx, state, dataChanged, { startIndex, scrollBottom
   scrollBottomBuffered: -1,
   startIndex: 0
 }) {
-  var _a3, _b, _c, _d;
+  var _a3, _b, _c, _d, _e;
   const {
     columns,
     indexByKey,
     positions,
     idCache,
     sizesKnown,
-    props: { getEstimatedItemSize, snapToIndices, enableAverages }
+    props: { getEstimatedItemSize, snapToIndices, enableAverages, maintainVisibleContentPosition }
   } = state;
   const data = state.props.data;
   const dataLength = data.length;
@@ -1779,9 +1774,9 @@ function updateItemPositions(ctx, state, dataChanged, { startIndex, scrollBottom
   const hasColumns = numColumns > 1;
   const indexByKeyForChecking = IS_DEV ? /* @__PURE__ */ new Map() : void 0;
   const shouldOptimize = !forceFullUpdate && !dataChanged && Math.abs(getScrollVelocity(state)) > 0;
-  state.isOptimizingItemPositions = shouldOptimize;
   const maxVisibleArea = scrollBottomBuffered + 1e3;
   const useAverageSize = enableAverages && !getEstimatedItemSize;
+  const preferCachedSize = maintainVisibleContentPosition && (dataChanged || state.scrollAdjustHandler.getAdjust() !== 0 || ((_a3 = peek$(ctx, "scrollAdjustPending")) != null ? _a3 : 0) !== 0);
   let currentRowTop = 0;
   let column = 1;
   let maxSizeInRow = 0;
@@ -1798,8 +1793,8 @@ function updateItemPositions(ctx, state, dataChanged, { startIndex, scrollBottom
     } else if (startIndex < dataLength) {
       const prevIndex = startIndex - 1;
       const prevId = getId(state, prevIndex);
-      const prevPosition = (_a3 = positions.get(prevId)) != null ? _a3 : 0;
-      const prevSize = (_b = sizesKnown.get(prevId)) != null ? _b : getItemSize(ctx, state, prevId, prevIndex, data[prevIndex], useAverageSize);
+      const prevPosition = (_b = positions.get(prevId)) != null ? _b : 0;
+      const prevSize = (_c = sizesKnown.get(prevId)) != null ? _c : getItemSize(ctx, state, prevId, prevIndex, data[prevIndex], useAverageSize, preferCachedSize);
       currentRowTop = prevPosition + prevSize;
     }
   }
@@ -1815,8 +1810,8 @@ function updateItemPositions(ctx, state, dataChanged, { startIndex, scrollBottom
       const itemsPerRow = hasColumns ? numColumns : 1;
       breakAt = i + itemsPerRow + 10;
     }
-    const id = (_c = idCache[i]) != null ? _c : getId(state, i);
-    const size = (_d = sizesKnown.get(id)) != null ? _d : getItemSize(ctx, state, id, i, data[i], useAverageSize);
+    const id = (_d = idCache[i]) != null ? _d : getId(state, i);
+    const size = (_e = sizesKnown.get(id)) != null ? _e : getItemSize(ctx, state, id, i, data[i], useAverageSize, preferCachedSize);
     if (IS_DEV && needsIndexByKey) {
       if (indexByKeyForChecking.has(id)) {
         console.error(
@@ -2034,16 +2029,6 @@ function isViewable(state, ctx, viewabilityConfig, containerId, key, scrollSize,
   const value = ctx.mapViewabilityAmountValues.get(containerId) || computeViewability(state, ctx, viewabilityConfig, containerId, key, scrollSize, item, index);
   return value.isViewable;
 }
-function findContainerId(ctx, key) {
-  const numContainers = peek$(ctx, "numContainers");
-  for (let i = 0; i < numContainers; i++) {
-    const itemKey = peek$(ctx, `containerItemKey${i}`);
-    if (itemKey === key) {
-      return i;
-    }
-  }
-  return -1;
-}
 function maybeUpdateViewabilityCallback(ctx, configId, containerId, viewToken) {
   const key = containerId + configId;
   ctx.mapViewabilityValues.set(key, viewToken);
@@ -2565,7 +2550,7 @@ function calculateItemsInView(ctx, state, params = {}) {
     for (let i = 0; i < numContainers; i++) {
       const itemKey = peek$(ctx, `containerItemKey${i}`);
       if (pendingRemoval.includes(i)) {
-        if (itemKey) {
+        if (itemKey !== void 0) {
           containerItemKeys.delete(itemKey);
         }
         state.containerItemTypes.delete(i);
@@ -2626,6 +2611,26 @@ function calculateItemsInView(ctx, state, params = {}) {
   });
 }
 
+// src/core/checkActualChange.ts
+function checkActualChange(state, dataProp, previousData) {
+  if (!previousData || !dataProp || dataProp.length !== previousData.length) {
+    return true;
+  }
+  const {
+    idCache,
+    props: { keyExtractor }
+  } = state;
+  for (let i = 0; i < dataProp.length; i++) {
+    if (dataProp[i] !== previousData[i]) {
+      return true;
+    }
+    if (keyExtractor ? idCache[i] !== keyExtractor(previousData[i], i) : dataProp[i] !== previousData[i]) {
+      return true;
+    }
+  }
+  return false;
+}
+
 // src/core/doMaintainScrollAtEnd.ts
 function doMaintainScrollAtEnd(ctx, state, animated) {
   const {
@@ -3141,6 +3146,7 @@ var LegendListInner = typedForwardRef(function LegendListInner2(props, forwarded
     columnWrapperStyle,
     contentContainerStyle: contentContainerStyleProp,
     data: dataProp = [],
+    dataVersion,
     drawDistance = 250,
     enableAverages = true,
     estimatedItemSize: estimatedItemSizeProp,
@@ -3190,13 +3196,13 @@ var LegendListInner = typedForwardRef(function LegendListInner2(props, forwarded
     waitForInitialLayout = true,
     ...rest
   } = props;
-  const [renderNum, setRenderNum] = useState(0);
-  const initialScrollProp = initialScrollAtEnd ? { index: dataProp.length - 1, viewOffset: 0 } : initialScrollIndexProp || initialScrollOffsetProp ? typeof initialScrollIndexProp === "object" ? { index: initialScrollIndexProp.index || 0, viewOffset: initialScrollIndexProp.viewOffset || 0 } : { index: initialScrollIndexProp || 0, viewOffset: initialScrollOffsetProp || 0 } : void 0;
-  const [canRender, setCanRender] = React3.useState(!IsNewArchitecture);
   const contentContainerStyle = { ...StyleSheet.flatten(contentContainerStyleProp) };
   const style = { ...StyleSheet.flatten(styleProp) };
   const stylePaddingTopState = extractPadding(style, contentContainerStyle, "Top");
   const stylePaddingBottomState = extractPadding(style, contentContainerStyle, "Bottom");
+  const [renderNum, setRenderNum] = useState(0);
+  const initialScrollProp = initialScrollAtEnd ? { index: Math.max(0, dataProp.length - 1), viewOffset: -stylePaddingBottomState } : initialScrollIndexProp || initialScrollOffsetProp ? typeof initialScrollIndexProp === "object" ? { index: initialScrollIndexProp.index || 0, viewOffset: initialScrollIndexProp.viewOffset || 0 } : { index: initialScrollIndexProp || 0, viewOffset: initialScrollOffsetProp || 0 } : void 0;
+  const [canRender, setCanRender] = React3.useState(!IsNewArchitecture);
   const ctx = useStateContext();
   ctx.columnWrapperStyle = columnWrapperStyle || (contentContainerStyle ? createColumnWrapperStyle(contentContainerStyle) : void 0);
   const refScroller = useRef(null);
@@ -3230,7 +3236,6 @@ var LegendListInner = typedForwardRef(function LegendListInner2(props, forwarded
         isAtStart: false,
         isEndReached: false,
         isFirst: true,
-        isOptimizingItemPositions: false,
         isStartReached: false,
         lastBatchingAction: Date.now(),
         lastLayout: void 0,
@@ -3263,6 +3268,8 @@ var LegendListInner = typedForwardRef(function LegendListInner2(props, forwarded
         totalSize: 0,
         viewabilityConfigCallbackPairs: void 0
       };
+      const internalState = ctx.internalState;
+      internalState.triggerCalculateItemsInView = (params) => calculateItemsInView(ctx, internalState, params);
       set$(ctx, "maintainVisibleContentPosition", maintainVisibleContentPosition);
       set$(ctx, "extraData", extraData);
     }
@@ -3271,7 +3278,7 @@ var LegendListInner = typedForwardRef(function LegendListInner2(props, forwarded
   const state = refState.current;
   const isFirstLocal = state.isFirst;
   state.didColumnsChange = numColumnsProp !== state.props.numColumns;
-  const didDataChangeLocal = state.props.data !== dataProp && checkActualChange(state, dataProp, state.props.data);
+  const didDataChangeLocal = state.props.dataVersion !== dataVersion || state.props.data !== dataProp && checkActualChange(state, dataProp, state.props.data);
   if (didDataChangeLocal) {
     state.dataChangeNeedsScrollUpdate = true;
     state.didDataChange = true;
@@ -3281,6 +3288,7 @@ var LegendListInner = typedForwardRef(function LegendListInner2(props, forwarded
   state.props = {
     alignItemsAtEnd,
     data: dataProp,
+    dataVersion,
     enableAverages,
     estimatedItemSize,
     getEstimatedItemSize,
@@ -3319,7 +3327,7 @@ var LegendListInner = typedForwardRef(function LegendListInner2(props, forwarded
       { length: Math.min(numColumnsProp, dataProp.length) },
       (_, i) => getId(state, dataProp.length - 1 - i)
     );
-  }, [dataProp, numColumnsProp]);
+  }, [dataProp, dataVersion, numColumnsProp]);
   const initializeStateVars = () => {
     set$(ctx, "lastItemKeys", memoizedLastItemKeys);
     set$(ctx, "numColumns", numColumnsProp);
@@ -3345,17 +3353,26 @@ var LegendListInner = typedForwardRef(function LegendListInner2(props, forwarded
   }
   const initialContentOffset = useMemo(() => {
     const { initialScroll } = refState.current;
-    if (initialScroll) {
-      const { index, viewOffset } = initialScroll;
-      let initialContentOffset2 = viewOffset || 0;
-      if (index !== void 0) {
-        initialContentOffset2 += calculateOffsetForIndex(ctx, state, index);
-      }
-      refState.current.isStartReached = initialContentOffset2 < refState.current.scrollLength * onStartReachedThreshold;
-      return initialContentOffset2;
-    }
-    return 0;
-  }, [renderNum]);
+    if (!initialScroll) {
+      return 0;
+    }
+    if (initialScroll.contentOffset !== void 0) {
+      return initialScroll.contentOffset;
+    }
+    const baseOffset = initialScroll.index !== void 0 ? calculateOffsetForIndex(ctx, state, initialScroll.index) : 0;
+    const resolvedOffset = calculateOffsetWithOffsetPosition(ctx, state, baseOffset, initialScroll);
+    let clampedOffset = resolvedOffset;
+    if (Number.isFinite(state.scrollLength) && Number.isFinite(state.totalSize)) {
+      const maxOffset = Math.max(0, state.totalSize - state.scrollLength);
+      clampedOffset = Math.min(clampedOffset, maxOffset);
+    }
+    clampedOffset = Math.max(0, clampedOffset);
+    const updatedInitialScroll = { ...initialScroll, contentOffset: clampedOffset };
+    refState.current.initialScroll = updatedInitialScroll;
+    state.initialScroll = updatedInitialScroll;
+    refState.current.isStartReached = clampedOffset < refState.current.scrollLength * onStartReachedThreshold;
+    return clampedOffset;
+  }, [renderNum, state.initialScroll]);
   if (isFirstLocal || didDataChangeLocal || numColumnsProp !== peek$(ctx, "numColumns")) {
     refState.current.lastBatchingAction = Date.now();
     if (!keyExtractorProp && !isFirstLocal && didDataChangeLocal) {
@@ -3382,9 +3399,15 @@ var LegendListInner = typedForwardRef(function LegendListInner2(props, forwarded
     }
   }, []);
   const doInitialScroll = useCallback(() => {
+    var _a4;
     const initialScroll = state.initialScroll;
     if (initialScroll) {
-      scrollTo(ctx, state, { animated: false, offset: initialContentOffset, ...state.initialScroll || {} });
+      scrollTo(ctx, state, {
+        animated: false,
+        index: (_a4 = state.initialScroll) == null ? void 0 : _a4.index,
+        offset: initialContentOffset,
+        precomputedWithViewOffset: true
+      });
     }
   }, [initialContentOffset, state.initialScroll]);
   const onLayoutChange = useCallback((layout) => {
@@ -3416,15 +3439,16 @@ var LegendListInner = typedForwardRef(function LegendListInner2(props, forwarded
     state.didColumnsChange = false;
     state.didDataChange = false;
     state.isFirst = false;
-  }, [dataProp, numColumnsProp]);
+  }, [dataProp, dataVersion, numColumnsProp]);
   useLayoutEffect(() => {
     set$(ctx, "extraData", extraData);
   }, [extraData]);
   useLayoutEffect(initializeStateVars, [
+    dataVersion,
     memoizedLastItemKeys.join(","),
     numColumnsProp,
-    stylePaddingTopState,
-    stylePaddingBottomState
+    stylePaddingBottomState,
+    stylePaddingTopState
   ]);
   useEffect(() => {
     const viewability = setupViewability({
@@ -3462,6 +3486,10 @@ var LegendListInner = typedForwardRef(function LegendListInner2(props, forwarded
           activeStickyIndex: state2.activeStickyIndex,
           contentLength: state2.totalSize,
           data: state2.props.data,
+          elementAtIndex: (index) => {
+            var _a4;
+            return (_a4 = ctx.viewRefs.get(findContainerId(ctx, getId(state2, index)))) == null ? void 0 : _a4.current;
+          },
           end: state2.endNoBuffer,
           endBuffered: state2.endBuffered,
           isAtEnd: state2.isAtEnd,

package/index.native.d.mts

@@ -1,5 +1,5 @@
 import * as React$1 from 'react';
-import { ComponentProps, ReactNode, Dispatch, SetStateAction } from 'react';
+import { ComponentProps, Key, ReactNode, Dispatch, SetStateAction } from 'react';
 import { View, ScrollView, Animated, LayoutRectangle, ScrollViewComponent, ScrollResponderMixin, StyleProp, ViewStyle, NativeSyntheticEvent, NativeScrollEvent, ScrollViewProps } from 'react-native';
 import Reanimated from 'react-native-reanimated';
 
@@ -102,6 +102,11 @@ interface LegendListSpecificProps<ItemT, TItemType extends string | undefined> {
      * Extra data to trigger re-rendering when changed.
      */
     extraData?: any;
+    /**
+     * Version token that forces the list to treat data as updated even when the array reference is stable.
+     * Increment or change this when mutating the data array in place.
+     */
+    dataVersion?: Key;
     /**
      * In case you have distinct item sizes, you can provide a function to get the size of an item.
      * Use instead of FlatList's getItemLayout or FlashList overrideItemLayout if you want to have accurate initialScrollOffset, you should provide this function
@@ -250,6 +255,7 @@ interface LegendListSpecificProps<ItemT, TItemType extends string | undefined> {
     refreshing?: boolean;
     /**
      * Render custom ScrollView component.
+     * Note: When using `stickyHeaderIndices`, you must provide an Animated ScrollView component.
      * @default (props) => <ScrollView {...props} />
      */
     renderScrollComponent?: (props: ScrollViewProps) => React.ReactElement<ScrollViewProps>;
@@ -312,6 +318,7 @@ interface ScrollTarget {
     viewPosition?: number;
     animated?: boolean;
     isInitialScroll?: boolean;
+    precomputedWithViewOffset?: boolean;
 }
 interface InternalState {
     positions: Map<string, number>;
@@ -339,6 +346,11 @@ interface InternalState {
     scrollPrev: number;
     scrollPrevTime: number;
     scrollAdjustHandler: ScrollAdjustHandler;
+    triggerCalculateItemsInView?: (params?: {
+        doMVCP?: boolean;
+        dataChanged?: boolean;
+        forceFullItemPositions?: boolean;
+    }) => void;
     maintainingScrollAtEnd?: boolean;
     totalSize: number;
     otherAxisSize?: number;
@@ -382,17 +394,17 @@ interface InternalState {
     }>;
     refScroller: React.RefObject<ScrollView>;
     loadStartTime: number;
-    initialScroll: ScrollIndexWithOffset | undefined;
+    initialScroll: ScrollIndexWithOffsetAndContentOffset | undefined;
     lastLayout: LayoutRectangle | undefined;
     timeoutSetPaddingTop?: any;
     activeStickyIndex: number | undefined;
     stickyContainers: Map<number, number>;
     stickyContainerPool: Set<number>;
     scrollProcessingEnabled: boolean;
-    isOptimizingItemPositions: boolean;
     props: {
         alignItemsAtEnd: boolean;
         data: readonly any[];
+        dataVersion: Key | undefined;
         estimatedItemSize: number | undefined;
         getEstimatedItemSize: LegendListProps["getEstimatedItemSize"];
         getFixedItemSize: LegendListProps["getFixedItemSize"];
@@ -443,6 +455,7 @@ type ScrollState = {
     activeStickyIndex: number | undefined;
     contentLength: number;
     data: readonly any[];
+    elementAtIndex: (index: number) => View | null | undefined;
     end: number;
     endBuffered: number;
     isAtEnd: boolean;
@@ -630,6 +643,9 @@ interface ScrollIndexWithOffset {
 interface ScrollIndexWithOffsetPosition extends ScrollIndexWithOffset {
     viewPosition: number;
 }
+interface ScrollIndexWithOffsetAndContentOffset extends ScrollIndexWithOffset {
+    contentOffset?: number;
+}
 type GetRenderedItemResult<ItemT> = {
     index: number;
     item: ItemT;
@@ -652,4 +668,4 @@ declare function useListScrollSize(): {
 };
 declare function useSyncLayout(): () => void;
 
-export { type ColumnWrapperStyle, type GetRenderedItem, type GetRenderedItemResult, type InternalState, LegendList, type LegendListProps, type LegendListPropsBase, type LegendListRecyclingState, type LegendListRef, type LegendListRenderItemProps, type MaintainScrollAtEndOptions, type OnViewableItemsChanged, type ScrollIndexWithOffset, type ScrollIndexWithOffsetPosition, type ScrollState, type ScrollTarget, type ThresholdSnapshot, type TypedForwardRef, type TypedMemo, type ViewAmountToken, type ViewToken, type ViewabilityAmountCallback, type ViewabilityCallback, type ViewabilityConfig, type ViewabilityConfigCallbackPair, type ViewabilityConfigCallbackPairs, type ViewableRange, typedForwardRef, typedMemo, useIsLastItem, useListScrollSize, useRecyclingEffect, useRecyclingState, useSyncLayout, useViewability, useViewabilityAmount };
+export { type ColumnWrapperStyle, type GetRenderedItem, type GetRenderedItemResult, type InternalState, LegendList, type LegendListProps, type LegendListPropsBase, type LegendListRecyclingState, type LegendListRef, type LegendListRenderItemProps, type MaintainScrollAtEndOptions, type OnViewableItemsChanged, type ScrollIndexWithOffset, type ScrollIndexWithOffsetAndContentOffset, type ScrollIndexWithOffsetPosition, type ScrollState, type ScrollTarget, type ThresholdSnapshot, type TypedForwardRef, type TypedMemo, type ViewAmountToken, type ViewToken, type ViewabilityAmountCallback, type ViewabilityCallback, type ViewabilityConfig, type ViewabilityConfigCallbackPair, type ViewabilityConfigCallbackPairs, type ViewableRange, typedForwardRef, typedMemo, useIsLastItem, useListScrollSize, useRecyclingEffect, useRecyclingState, useSyncLayout, useViewability, useViewabilityAmount };

package/index.native.d.ts

@@ -1,5 +1,5 @@
 import * as React$1 from 'react';
-import { ComponentProps, ReactNode, Dispatch, SetStateAction } from 'react';
+import { ComponentProps, Key, ReactNode, Dispatch, SetStateAction } from 'react';
 import { View, ScrollView, Animated, LayoutRectangle, ScrollViewComponent, ScrollResponderMixin, StyleProp, ViewStyle, NativeSyntheticEvent, NativeScrollEvent, ScrollViewProps } from 'react-native';
 import Reanimated from 'react-native-reanimated';
 
@@ -102,6 +102,11 @@ interface LegendListSpecificProps<ItemT, TItemType extends string | undefined> {
      * Extra data to trigger re-rendering when changed.
      */
     extraData?: any;
+    /**
+     * Version token that forces the list to treat data as updated even when the array reference is stable.
+     * Increment or change this when mutating the data array in place.
+     */
+    dataVersion?: Key;
     /**
      * In case you have distinct item sizes, you can provide a function to get the size of an item.
      * Use instead of FlatList's getItemLayout or FlashList overrideItemLayout if you want to have accurate initialScrollOffset, you should provide this function
@@ -250,6 +255,7 @@ interface LegendListSpecificProps<ItemT, TItemType extends string | undefined> {
     refreshing?: boolean;
     /**
      * Render custom ScrollView component.
+     * Note: When using `stickyHeaderIndices`, you must provide an Animated ScrollView component.
      * @default (props) => <ScrollView {...props} />
      */
     renderScrollComponent?: (props: ScrollViewProps) => React.ReactElement<ScrollViewProps>;
@@ -312,6 +318,7 @@ interface ScrollTarget {
     viewPosition?: number;
     animated?: boolean;
     isInitialScroll?: boolean;
+    precomputedWithViewOffset?: boolean;
 }
 interface InternalState {
     positions: Map<string, number>;
@@ -339,6 +346,11 @@ interface InternalState {
     scrollPrev: number;
     scrollPrevTime: number;
     scrollAdjustHandler: ScrollAdjustHandler;
+    triggerCalculateItemsInView?: (params?: {
+        doMVCP?: boolean;
+        dataChanged?: boolean;
+        forceFullItemPositions?: boolean;
+    }) => void;
     maintainingScrollAtEnd?: boolean;
     totalSize: number;
     otherAxisSize?: number;
@@ -382,17 +394,17 @@ interface InternalState {
     }>;
     refScroller: React.RefObject<ScrollView>;
     loadStartTime: number;
-    initialScroll: ScrollIndexWithOffset | undefined;
+    initialScroll: ScrollIndexWithOffsetAndContentOffset | undefined;
     lastLayout: LayoutRectangle | undefined;
     timeoutSetPaddingTop?: any;
     activeStickyIndex: number | undefined;
     stickyContainers: Map<number, number>;
     stickyContainerPool: Set<number>;
     scrollProcessingEnabled: boolean;
-    isOptimizingItemPositions: boolean;
     props: {
         alignItemsAtEnd: boolean;
         data: readonly any[];
+        dataVersion: Key | undefined;
         estimatedItemSize: number | undefined;
         getEstimatedItemSize: LegendListProps["getEstimatedItemSize"];
         getFixedItemSize: LegendListProps["getFixedItemSize"];
@@ -443,6 +455,7 @@ type ScrollState = {
     activeStickyIndex: number | undefined;
     contentLength: number;
     data: readonly any[];
+    elementAtIndex: (index: number) => View | null | undefined;
     end: number;
     endBuffered: number;
     isAtEnd: boolean;
@@ -630,6 +643,9 @@ interface ScrollIndexWithOffset {
 interface ScrollIndexWithOffsetPosition extends ScrollIndexWithOffset {
     viewPosition: number;
 }
+interface ScrollIndexWithOffsetAndContentOffset extends ScrollIndexWithOffset {
+    contentOffset?: number;
+}
 type GetRenderedItemResult<ItemT> = {
     index: number;
     item: ItemT;
@@ -652,4 +668,4 @@ declare function useListScrollSize(): {
 };
 declare function useSyncLayout(): () => void;
 
-export { type ColumnWrapperStyle, type GetRenderedItem, type GetRenderedItemResult, type InternalState, LegendList, type LegendListProps, type LegendListPropsBase, type LegendListRecyclingState, type LegendListRef, type LegendListRenderItemProps, type MaintainScrollAtEndOptions, type OnViewableItemsChanged, type ScrollIndexWithOffset, type ScrollIndexWithOffsetPosition, type ScrollState, type ScrollTarget, type ThresholdSnapshot, type TypedForwardRef, type TypedMemo, type ViewAmountToken, type ViewToken, type ViewabilityAmountCallback, type ViewabilityCallback, type ViewabilityConfig, type ViewabilityConfigCallbackPair, type ViewabilityConfigCallbackPairs, type ViewableRange, typedForwardRef, typedMemo, useIsLastItem, useListScrollSize, useRecyclingEffect, useRecyclingState, useSyncLayout, useViewability, useViewabilityAmount };
+export { type ColumnWrapperStyle, type GetRenderedItem, type GetRenderedItemResult, type InternalState, LegendList, type LegendListProps, type LegendListPropsBase, type LegendListRecyclingState, type LegendListRef, type LegendListRenderItemProps, type MaintainScrollAtEndOptions, type OnViewableItemsChanged, type ScrollIndexWithOffset, type ScrollIndexWithOffsetAndContentOffset, type ScrollIndexWithOffsetPosition, type ScrollState, type ScrollTarget, type ThresholdSnapshot, type TypedForwardRef, type TypedMemo, type ViewAmountToken, type ViewToken, type ViewabilityAmountCallback, type ViewabilityCallback, type ViewabilityConfig, type ViewabilityConfigCallbackPair, type ViewabilityConfigCallbackPairs, type ViewableRange, typedForwardRef, typedMemo, useIsLastItem, useListScrollSize, useRecyclingEffect, useRecyclingState, useSyncLayout, useViewability, useViewabilityAmount };