@legendapp/list 3.6.0 → 3.7.0

package/reanimated.d.ts

@@ -9,8 +9,8 @@ interface MaintainVisibleContentPositionNormalized<ItemT = any> {
     shouldRestorePosition?: (item: ItemT, index: number, data: readonly ItemT[]) => boolean;
 }
 
-type ListenerType = "activeStickyIndex" | "alignItemsAtEndPadding" | "anchoredEndSpaceSize" | "containerLayoutEpoch" | "debugComputedScroll" | "debugRawScroll" | "extraData" | "footerSize" | "headerSize" | "lastItemKeys" | "lastPositionUpdate" | "maintainVisibleContentPosition" | "numColumns" | "numContainers" | "numContainersPooled" | "otherAxisSize" | "readyToRender" | "scrollAdjust" | "scrollAdjustPending" | "scrollAdjustUserOffset" | "scrollSize" | "snapToOffsets" | "stylePaddingTop" | "totalSize" | "isAtEnd" | "isAtStart" | "isNearEnd" | "isNearStart" | "isWithinMaintainScrollAtEndThreshold" | "adaptiveRender" | `containerColumn${number}` | `containerSpan${number}` | `containerItemData${number}` | `containerItemIndex${number}` | `containerItemKey${number}` | `containerLayoutReady${number}` | `containerPosition${number}` | `containerSticky${number}`;
-type LegendListListenerType = Extract<ListenerType, "activeStickyIndex" | "anchoredEndSpaceSize" | "footerSize" | "headerSize" | "isAtEnd" | "isAtStart" | "isNearEnd" | "isNearStart" | "isWithinMaintainScrollAtEndThreshold" | "adaptiveRender" | "lastItemKeys" | "lastPositionUpdate" | "numContainers" | "numContainersPooled" | "otherAxisSize" | "readyToRender" | "snapToOffsets" | "totalSize">;
+type ListenerType = "activeStickyIndex" | "alignItemsAtEndPadding" | "anchoredEndSpaceSize" | "containerLayoutEpoch" | "debugComputedScroll" | "debugRawScroll" | "extraData" | "footerSize" | "headerSize" | "lastItemKeys" | "lastPositionUpdate" | "maintainVisibleContentPosition" | "numColumns" | "numContainers" | "numContainersPooled" | "otherAxisSize" | "readyToRender" | "isScrollActive" | "scrollAdjust" | "scrollAdjustPending" | "scrollAdjustUserOffset" | "scrollSize" | "snapToOffsets" | "stylePaddingTop" | "totalSize" | "isFollowingEnd" | "isAtEnd" | "isAtStart" | "isNearEnd" | "isNearStart" | "isWithinMaintainScrollAtEndThreshold" | "adaptiveRender" | `containerColumn${number}` | `containerSpan${number}` | `containerItemData${number}` | `containerItemIndex${number}` | `containerItemKey${number}` | `containerLayoutReady${number}` | `containerPosition${number}` | `containerSticky${number}`;
+type LegendListListenerType = Extract<ListenerType, "activeStickyIndex" | "anchoredEndSpaceSize" | "footerSize" | "headerSize" | "isFollowingEnd" | "isAtEnd" | "isAtStart" | "isNearEnd" | "isNearStart" | "isWithinMaintainScrollAtEndThreshold" | "adaptiveRender" | "lastItemKeys" | "lastPositionUpdate" | "numContainers" | "numContainersPooled" | "otherAxisSize" | "readyToRender" | "snapToOffsets" | "totalSize">;
 type ListenerTypeValueMap = {
     activeStickyIndex: number;
     alignItemsAtEndPadding: number;
@@ -22,6 +22,7 @@ type ListenerTypeValueMap = {
     extraData: any;
     footerSize: number;
     headerSize: number;
+    isFollowingEnd: boolean;
     isAtEnd: boolean;
     isAtStart: boolean;
     isNearEnd: boolean;
@@ -35,6 +36,7 @@ type ListenerTypeValueMap = {
     numContainersPooled: number;
     otherAxisSize: number;
     readyToRender: boolean;
+    isScrollActive: boolean;
     scrollAdjust: number;
     scrollAdjustPending: number;
     scrollAdjustUserOffset: number;
@@ -200,6 +202,7 @@ interface LegendListSpecificProps<ItemT, TItemType extends string | undefined> {
     extraData?: any;
     /**
      * In case items always have a fixed size, you can provide a function to return it.
+     * Change extraData when the fixed sizes returned by this callback change.
      */
     getFixedItemSize?: (item: ItemT, index: number, type: TItemType) => number | undefined;
     /**
@@ -272,6 +275,11 @@ interface LegendListSpecificProps<ItemT, TItemType extends string | undefined> {
     /**
      * If true, auto-scrolls to end when new items are added.
      * Use an options object to opt into specific triggers and control whether that scroll is animated.
+     * Setting false pauses maintenance while retaining end-follow intent. Re-enabling resumes
+     * that intent even if content grew beyond the threshold; user or list navigation releases it.
+     * While paused, isFollowingEnd reports the retained intent.
+     * With a native screen reader enabled, unowned accessibility scrolls toward the start
+     * release following. Assistive-tech scrolls during library animations are not detected.
      * @default false
      */
     maintainScrollAtEnd?: boolean | MaintainScrollAtEndOptions;
@@ -282,11 +290,13 @@ interface LegendListSpecificProps<ItemT, TItemType extends string | undefined> {
     maintainScrollAtEndThreshold?: number;
     /**
      * Maintains visibility of content.
-     * - scroll (default: true) stabilizes during size/layout changes while scrolling.
-     * - data (default: false) stabilizes when the data array changes; passing true also sets the RN maintainVisibleContentPosition prop.
+     * - size (default: true) stabilizes during size/layout changes while scrolling.
+     * - data (default: false) stabilizes when the data array changes.
      * - shouldRestorePosition can opt out specific items from data-change anchoring.
      * - undefined (default) enables scroll stabilization but skips data-change anchoring.
-     * - true enables both behaviors; false disables both.
+     * - true enables both JS behaviors; false disables both.
+     * Native iOS maintainVisibleContentPosition is enabled when either size or data stabilization is enabled,
+     * and disabled when both are disabled.
      */
     maintainVisibleContentPosition?: boolean | MaintainVisibleContentPositionConfig<ItemT>;
     /**
@@ -378,8 +388,25 @@ interface LegendListSpecificProps<ItemT, TItemType extends string | undefined> {
      */
     onRefresh?: () => void;
     /**
-     * Called when the list scrolls.
-     */
+     * Called once per accepted user gesture, in either direction: native drag (including
+     * momentum), web wheel/touch movement, non-repeated scroll keydown, or scrollbar drag.
+     * Wheel input at a boundary is ignored unless navigation is active. Without wheel
+     * momentum metadata, gesture boundaries are inferred from timing, direction and force.
+     * iOS status-bar scrolling emits on native onScrollToTop unless accessibility motion
+     * already reported it during the animation.
+     * With a native screen reader enabled, otherwise unowned scroll motion with stable
+     * content/viewport size is inferred as accessibility input (including focus navigation),
+     * once per burst; motion toward the start releases end following. Library animations
+     * and controller/native-ref command windows mask assistive-tech scrolling.
+     * Native commands bypassing the list and its refs (e.g. Reanimated scrollTo worklets)
+     * cannot be distinguished from accessibility input while a screen reader is on; call
+     * cancelScroll() on the JS thread before that navigation to release end following.
+     * Layout/clamp/MVCP events and commands through the list or its refs do not emit it.
+     * @experimental Native pointer/wheel-only input without a screen reader is not detected.
+     * Web scrollbar detection requires pointer events in a measurable, non-overlay gutter.
+     */
+    onUserScroll?: () => void;
+    /** Called when the list scrolls. */
     onScroll?: (event: NativeSyntheticEvent<NativeScrollEvent>) => void;
     /**
      * Called when scrolling reaches the start within onStartReachedThreshold.
@@ -511,6 +538,8 @@ interface AlwaysRenderConfig {
     keys?: string[];
 }
 interface MaintainScrollAtEndOnOptions {
+    /** Follow only additions that preserve every existing item key in order. */
+    dataAppend?: boolean;
     dataChange?: boolean;
     footerLayout?: boolean;
     itemLayout?: boolean;
@@ -552,9 +581,13 @@ type LegendListState = {
     activeStickyIndex: number;
     contentLength: number;
     data: readonly any[];
+    dataKey?: Key;
     elementAtIndex: (index: number) => any;
     end: number;
     endBuffered: number;
+    /** Distance to the physical scroll edge, including the trailing inset. */
+    distanceFromEnd: number;
+    isFollowingEnd: boolean;
     isAtEnd: boolean;
     isAtStart: boolean;
     isNearEnd: boolean;
@@ -564,7 +597,10 @@ type LegendListState = {
     isWithinMaintainScrollAtEndThreshold: boolean;
     getAverageItemSizes: () => Record<string, LegendListAverageItemSize>;
     indexByKey: (key: string) => number | undefined;
-    listen: <T extends LegendListListenerType>(listenerType: T, callback: (value: ListenerTypeValueMap[T]) => void) => () => void;
+    listen: {
+        <T extends Exclude<LegendListListenerType, "isFollowingEnd">>(listenerType: T, callback: (value: Pick<ListenerTypeValueMap, LegendListListenerType>[T]) => void): () => void;
+        <T extends LegendListListenerType>(listenerType: T, callback: (value: Pick<ListenerTypeValueMap, LegendListListenerType>[T]) => void): () => void;
+    };
     listenToPosition: (key: string, callback: (value: number) => void) => () => void;
     positionAtIndex: (index: number) => number;
     positionByKey: (key: string) => number | undefined;
@@ -577,6 +613,28 @@ type LegendListState = {
     startBuffered: number;
 };
 type LegendListRef$1 = {
+    /** Cancels queued and active scrolling, settles its promise, and stops at the observed offset. */
+    cancelScroll(): void;
+    /** Scrolls by stable item identity through prepends; resolves without scrolling if the key is missing or removed. */
+    scrollToKey(params: {
+        key: string;
+        animated?: boolean;
+        viewOffset?: number;
+        viewPosition?: number;
+    }): Promise<void>;
+    /**
+     * Captures an item's key and viewport offset, holding it through layout changes by default.
+     * Omit key to use the first visible item; set hold to false to read without side effects.
+     * Returns undefined before initial placement, during dataset replacement, or if no item is found.
+     * While following at the end, returns the anchor without interrupting end following.
+     */
+    anchorVisibleContent(options?: {
+        key?: string;
+        hold?: boolean;
+    }): {
+        key: string;
+        offset: number;
+    } | undefined;
     /**
      * Clears internal virtualization caches.
      * @param options - Cache clearing options.
@@ -619,20 +677,40 @@ type LegendListRef$1 = {
      * @param params - Parameters for scrolling.
      * @param params.animated - If true, animates the scroll. Default: true.
      * @param params.index - The index to scroll to.
+     * @param params.itemOffset - Region start measured from the item's start along the scroll axis. Default: 0 when itemLength is provided.
+     * @param params.itemLength - Region length along the scroll axis. Default: 0 when itemOffset is provided. Omit both to reveal the whole item.
+     * @param params.viewportMargin - Space to keep clear at the start and end of the viewport along the scroll axis.
+     * The region should be within the item. A visible region does not scroll; otherwise its nearest edge aligns inside the margins. A region larger than the available space aligns its start.
      */
     scrollIndexIntoView(params: {
         animated?: boolean | undefined;
         index: number;
+        itemOffset?: number;
+        itemLength?: number;
+        viewportMargin?: {
+            start?: number;
+            end?: number;
+        };
     }): Promise<void>;
     /**
-     * Scrolls a specific index into view.
+     * Scrolls a specific item into view.
      * @param params - Parameters for scrolling.
      * @param params.animated - If true, animates the scroll. Default: true.
      * @param params.item - The item to scroll to.
+     * @param params.itemOffset - Region start measured from the item's start along the scroll axis. Default: 0 when itemLength is provided.
+     * @param params.itemLength - Region length along the scroll axis. Default: 0 when itemOffset is provided. Omit both to reveal the whole item.
+     * @param params.viewportMargin - Space to keep clear at the start and end of the viewport along the scroll axis.
+     * The region should be within the item. A visible region does not scroll; otherwise its nearest edge aligns inside the margins. A region larger than the available space aligns its start.
      */
     scrollItemIntoView(params: {
         animated?: boolean | undefined;
         item: any;
+        itemOffset?: number;
+        itemLength?: number;
+        viewportMargin?: {
+            start?: number;
+            end?: number;
+        };
     }): Promise<void>;
     /**
      * Scrolls to the end of the list.
@@ -762,7 +840,9 @@ type LegendListPropsOverrides<ItemT, TItemType extends string | undefined> = Omi
 };
 type LegendListProps<ItemT = any, TItemType extends string | undefined = string | undefined> = LegendListPropsOverrides<ItemT, TItemType>;
 type LegendListRef = Omit<LegendListRef$1, "getAnimatableRef" | "getNativeScrollRef" | "getScrollResponder" | "reportContentInset"> & {
+    /** Call cancelScroll() before scrolling it directly so end following and list scrolling stop first. */
     getAnimatableRef(): React.ElementRef<typeof ScrollViewComponent>;
+    /** Call cancelScroll() before scrolling it directly so end following and list scrolling stop first. */
     getNativeScrollRef(): React.ElementRef<typeof ScrollViewComponent>;
     getScrollResponder(): ScrollResponderMixin;
     reportContentInset(inset?: Partial<Insets$1> | null): void;

package/reanimated.js

@@ -112,16 +112,16 @@ var ReanimatedPositionViewSticky = typedMemo(function ReanimatedPositionViewStic
 });
 var ReanimatedPositionView = typedMemo(function ReanimatedPositionViewComponent(props) {
   const ctx = useStateContext();
-  const { id, horizontal, style, refView, children, recycleItems, layoutTransition, ...rest } = props;
-  const [positionValue = POSITION_OUT_OF_VIEW, layoutReady = true] = useArr$([
+  const { id, horizontal, style, refView, children, layoutTransition, ...rest } = props;
+  const [positionValue = POSITION_OUT_OF_VIEW, layoutReady = true, isScrollActive] = useArr$([
     `containerPosition${id}`,
-    `containerLayoutReady${id}`
+    `containerLayoutReady${id}`,
+    "isScrollActive"
   ]);
   const prevItemKeyRef = React__namespace.useRef(void 0);
   let shouldSkipTransitionForRecycleReuse = false;
-  if (recycleItems && layoutTransition) {
-    const itemKeySignal = `containerItemKey${id}`;
-    const itemKey = peek$(ctx, itemKeySignal);
+  if (layoutTransition) {
+    const itemKey = peek$(ctx, `containerItemKey${id}`);
     shouldSkipTransitionForRecycleReuse = itemKey !== void 0 && prevItemKeyRef.current !== void 0 && prevItemKeyRef.current !== itemKey;
     if (itemKey !== void 0) {
       prevItemKeyRef.current = itemKey;
@@ -129,6 +129,10 @@ var ReanimatedPositionView = typedMemo(function ReanimatedPositionViewComponent(
   } else {
     prevItemKeyRef.current = void 0;
   }
+  const previousAdjustment = React__namespace.useRef(ctx.state.layoutAdjustmentEpoch);
+  const wasAdjusted = previousAdjustment.current !== ctx.state.layoutAdjustmentEpoch;
+  previousAdjustment.current = ctx.state.layoutAdjustmentEpoch;
+  const shouldSkipLayoutTransition = wasAdjusted || isScrollActive || !!ctx.state.scrollingTo;
   const viewStyle = React__namespace.useMemo(
     () => [style, horizontal ? { left: positionValue } : { top: positionValue }, !layoutReady && { opacity: 0 }],
     [horizontal, layoutReady, positionValue, style]
@@ -136,7 +140,7 @@ var ReanimatedPositionView = typedMemo(function ReanimatedPositionViewComponent(
   return /* @__PURE__ */ React__namespace.createElement(
     Reanimated__default.default.View,
     {
-      layout: shouldSkipTransitionForRecycleReuse ? void 0 : layoutTransition,
+      layout: shouldSkipTransitionForRecycleReuse || shouldSkipLayoutTransition ? void 0 : layoutTransition,
       ref: refView,
       style: viewStyle,
       ...rest,
@@ -197,13 +201,7 @@ var LegendListForwardedRef = typedMemo(
   // biome-ignore lint/nursery/noShadow: const function name shadowing is intentional
   React__namespace.forwardRef(function LegendListForwardedRef2(props, ref) {
     var _a, _b;
-    const { itemLayoutAnimation, recycleItems, refLegendList, renderScrollComponent, sharedValues, ...rest } = props;
-    const refFn = React.useCallback(
-      (r) => {
-        refLegendList(r);
-      },
-      [refLegendList]
-    );
+    const { itemLayoutAnimation, refLegendList, renderScrollComponent, sharedValues, ...rest } = props;
     const internalScrollOffset = Reanimated.useSharedValue(0);
     const scrollOffset = (_a = sharedValues == null ? void 0 : sharedValues.scrollOffset) != null ? _a : internalScrollOffset;
     const trackedScrollOffset = (sharedValues == null ? void 0 : sharedValues.scrollOffset) !== void 0 || ((_b = rest.stickyHeaderIndices) == null ? void 0 : _b.length) ? scrollOffset : void 0;
@@ -239,26 +237,16 @@ var LegendListForwardedRef = typedMemo(
         return void 0;
       }
       return function PositionComponent(positionProps) {
-        return /* @__PURE__ */ React__namespace.createElement(
-          ReanimatedPositionView,
-          {
-            ...positionProps,
-            layoutTransition: itemLayoutAnimationRef.current,
-            recycleItems
-          }
-        );
+        return /* @__PURE__ */ React__namespace.createElement(ReanimatedPositionView, { ...positionProps, layoutTransition: itemLayoutAnimationRef.current });
       };
-    }, [hasItemLayoutAnimation, recycleItems]);
+    }, [hasItemLayoutAnimation]);
     const legendListProps = {
       ...rest,
       positionComponentInternal,
-      recycleItems,
-      ...{
-        renderScrollComponent: renderReanimatedScrollComponent,
-        ...IsNewArchitecture ? { stickyPositionComponentInternal } : {}
-      } 
+      renderScrollComponent: renderReanimatedScrollComponent,
+      ...IsNewArchitecture ? { stickyPositionComponentInternal } : {}
     };
-    return /* @__PURE__ */ React__namespace.createElement(reactNative.LegendList, { ref: refFn, refScrollView: ref, ...legendListProps });
+    return /* @__PURE__ */ React__namespace.createElement(reactNative.LegendList, { ref: refLegendList, refScrollView: ref, ...legendListProps });
   })
 );
 var AnimatedLegendListComponent = Reanimated__default.default.createAnimatedComponent(LegendListForwardedRef);

package/reanimated.mjs

@@ -88,16 +88,16 @@ var ReanimatedPositionViewSticky = typedMemo(function ReanimatedPositionViewStic
 });
 var ReanimatedPositionView = typedMemo(function ReanimatedPositionViewComponent(props) {
   const ctx = useStateContext();
-  const { id, horizontal, style, refView, children, recycleItems, layoutTransition, ...rest } = props;
-  const [positionValue = POSITION_OUT_OF_VIEW, layoutReady = true] = useArr$([
+  const { id, horizontal, style, refView, children, layoutTransition, ...rest } = props;
+  const [positionValue = POSITION_OUT_OF_VIEW, layoutReady = true, isScrollActive] = useArr$([
     `containerPosition${id}`,
-    `containerLayoutReady${id}`
+    `containerLayoutReady${id}`,
+    "isScrollActive"
   ]);
   const prevItemKeyRef = React.useRef(void 0);
   let shouldSkipTransitionForRecycleReuse = false;
-  if (recycleItems && layoutTransition) {
-    const itemKeySignal = `containerItemKey${id}`;
-    const itemKey = peek$(ctx, itemKeySignal);
+  if (layoutTransition) {
+    const itemKey = peek$(ctx, `containerItemKey${id}`);
     shouldSkipTransitionForRecycleReuse = itemKey !== void 0 && prevItemKeyRef.current !== void 0 && prevItemKeyRef.current !== itemKey;
     if (itemKey !== void 0) {
       prevItemKeyRef.current = itemKey;
@@ -105,6 +105,10 @@ var ReanimatedPositionView = typedMemo(function ReanimatedPositionViewComponent(
   } else {
     prevItemKeyRef.current = void 0;
   }
+  const previousAdjustment = React.useRef(ctx.state.layoutAdjustmentEpoch);
+  const wasAdjusted = previousAdjustment.current !== ctx.state.layoutAdjustmentEpoch;
+  previousAdjustment.current = ctx.state.layoutAdjustmentEpoch;
+  const shouldSkipLayoutTransition = wasAdjusted || isScrollActive || !!ctx.state.scrollingTo;
   const viewStyle = React.useMemo(
     () => [style, horizontal ? { left: positionValue } : { top: positionValue }, !layoutReady && { opacity: 0 }],
     [horizontal, layoutReady, positionValue, style]
@@ -112,7 +116,7 @@ var ReanimatedPositionView = typedMemo(function ReanimatedPositionViewComponent(
   return /* @__PURE__ */ React.createElement(
     Reanimated.View,
     {
-      layout: shouldSkipTransitionForRecycleReuse ? void 0 : layoutTransition,
+      layout: shouldSkipTransitionForRecycleReuse || shouldSkipLayoutTransition ? void 0 : layoutTransition,
       ref: refView,
       style: viewStyle,
       ...rest,
@@ -173,13 +177,7 @@ var LegendListForwardedRef = typedMemo(
   // biome-ignore lint/nursery/noShadow: const function name shadowing is intentional
   React.forwardRef(function LegendListForwardedRef2(props, ref) {
     var _a, _b;
-    const { itemLayoutAnimation, recycleItems, refLegendList, renderScrollComponent, sharedValues, ...rest } = props;
-    const refFn = useCallback(
-      (r) => {
-        refLegendList(r);
-      },
-      [refLegendList]
-    );
+    const { itemLayoutAnimation, refLegendList, renderScrollComponent, sharedValues, ...rest } = props;
     const internalScrollOffset = useSharedValue(0);
     const scrollOffset = (_a = sharedValues == null ? void 0 : sharedValues.scrollOffset) != null ? _a : internalScrollOffset;
     const trackedScrollOffset = (sharedValues == null ? void 0 : sharedValues.scrollOffset) !== void 0 || ((_b = rest.stickyHeaderIndices) == null ? void 0 : _b.length) ? scrollOffset : void 0;
@@ -215,26 +213,16 @@ var LegendListForwardedRef = typedMemo(
         return void 0;
       }
       return function PositionComponent(positionProps) {
-        return /* @__PURE__ */ React.createElement(
-          ReanimatedPositionView,
-          {
-            ...positionProps,
-            layoutTransition: itemLayoutAnimationRef.current,
-            recycleItems
-          }
-        );
+        return /* @__PURE__ */ React.createElement(ReanimatedPositionView, { ...positionProps, layoutTransition: itemLayoutAnimationRef.current });
       };
-    }, [hasItemLayoutAnimation, recycleItems]);
+    }, [hasItemLayoutAnimation]);
     const legendListProps = {
       ...rest,
       positionComponentInternal,
-      recycleItems,
-      ...{
-        renderScrollComponent: renderReanimatedScrollComponent,
-        ...IsNewArchitecture ? { stickyPositionComponentInternal } : {}
-      } 
+      renderScrollComponent: renderReanimatedScrollComponent,
+      ...IsNewArchitecture ? { stickyPositionComponentInternal } : {}
     };
-    return /* @__PURE__ */ React.createElement(LegendList, { ref: refFn, refScrollView: ref, ...legendListProps });
+    return /* @__PURE__ */ React.createElement(LegendList, { ref: refLegendList, refScrollView: ref, ...legendListProps });
   })
 );
 var AnimatedLegendListComponent = Reanimated.createAnimatedComponent(LegendListForwardedRef);

package/section-list.d.ts

@@ -65,8 +65,8 @@ interface MaintainVisibleContentPositionNormalized<ItemT = any> {
     shouldRestorePosition?: (item: ItemT, index: number, data: readonly ItemT[]) => boolean;
 }
 
-type ListenerType = "activeStickyIndex" | "alignItemsAtEndPadding" | "anchoredEndSpaceSize" | "containerLayoutEpoch" | "debugComputedScroll" | "debugRawScroll" | "extraData" | "footerSize" | "headerSize" | "lastItemKeys" | "lastPositionUpdate" | "maintainVisibleContentPosition" | "numColumns" | "numContainers" | "numContainersPooled" | "otherAxisSize" | "readyToRender" | "scrollAdjust" | "scrollAdjustPending" | "scrollAdjustUserOffset" | "scrollSize" | "snapToOffsets" | "stylePaddingTop" | "totalSize" | "isAtEnd" | "isAtStart" | "isNearEnd" | "isNearStart" | "isWithinMaintainScrollAtEndThreshold" | "adaptiveRender" | `containerColumn${number}` | `containerSpan${number}` | `containerItemData${number}` | `containerItemIndex${number}` | `containerItemKey${number}` | `containerLayoutReady${number}` | `containerPosition${number}` | `containerSticky${number}`;
-type LegendListListenerType = Extract<ListenerType, "activeStickyIndex" | "anchoredEndSpaceSize" | "footerSize" | "headerSize" | "isAtEnd" | "isAtStart" | "isNearEnd" | "isNearStart" | "isWithinMaintainScrollAtEndThreshold" | "adaptiveRender" | "lastItemKeys" | "lastPositionUpdate" | "numContainers" | "numContainersPooled" | "otherAxisSize" | "readyToRender" | "snapToOffsets" | "totalSize">;
+type ListenerType = "activeStickyIndex" | "alignItemsAtEndPadding" | "anchoredEndSpaceSize" | "containerLayoutEpoch" | "debugComputedScroll" | "debugRawScroll" | "extraData" | "footerSize" | "headerSize" | "lastItemKeys" | "lastPositionUpdate" | "maintainVisibleContentPosition" | "numColumns" | "numContainers" | "numContainersPooled" | "otherAxisSize" | "readyToRender" | "isScrollActive" | "scrollAdjust" | "scrollAdjustPending" | "scrollAdjustUserOffset" | "scrollSize" | "snapToOffsets" | "stylePaddingTop" | "totalSize" | "isFollowingEnd" | "isAtEnd" | "isAtStart" | "isNearEnd" | "isNearStart" | "isWithinMaintainScrollAtEndThreshold" | "adaptiveRender" | `containerColumn${number}` | `containerSpan${number}` | `containerItemData${number}` | `containerItemIndex${number}` | `containerItemKey${number}` | `containerLayoutReady${number}` | `containerPosition${number}` | `containerSticky${number}`;
+type LegendListListenerType = Extract<ListenerType, "activeStickyIndex" | "anchoredEndSpaceSize" | "footerSize" | "headerSize" | "isFollowingEnd" | "isAtEnd" | "isAtStart" | "isNearEnd" | "isNearStart" | "isWithinMaintainScrollAtEndThreshold" | "adaptiveRender" | "lastItemKeys" | "lastPositionUpdate" | "numContainers" | "numContainersPooled" | "otherAxisSize" | "readyToRender" | "snapToOffsets" | "totalSize">;
 type ListenerTypeValueMap = {
     activeStickyIndex: number;
     alignItemsAtEndPadding: number;
@@ -78,6 +78,7 @@ type ListenerTypeValueMap = {
     extraData: any;
     footerSize: number;
     headerSize: number;
+    isFollowingEnd: boolean;
     isAtEnd: boolean;
     isAtStart: boolean;
     isNearEnd: boolean;
@@ -91,6 +92,7 @@ type ListenerTypeValueMap = {
     numContainersPooled: number;
     otherAxisSize: number;
     readyToRender: boolean;
+    isScrollActive: boolean;
     scrollAdjust: number;
     scrollAdjustPending: number;
     scrollAdjustUserOffset: number;
@@ -256,6 +258,7 @@ interface LegendListSpecificProps<ItemT, TItemType extends string | undefined> {
     extraData?: any;
     /**
      * In case items always have a fixed size, you can provide a function to return it.
+     * Change extraData when the fixed sizes returned by this callback change.
      */
     getFixedItemSize?: (item: ItemT, index: number, type: TItemType) => number | undefined;
     /**
@@ -328,6 +331,11 @@ interface LegendListSpecificProps<ItemT, TItemType extends string | undefined> {
     /**
      * If true, auto-scrolls to end when new items are added.
      * Use an options object to opt into specific triggers and control whether that scroll is animated.
+     * Setting false pauses maintenance while retaining end-follow intent. Re-enabling resumes
+     * that intent even if content grew beyond the threshold; user or list navigation releases it.
+     * While paused, isFollowingEnd reports the retained intent.
+     * With a native screen reader enabled, unowned accessibility scrolls toward the start
+     * release following. Assistive-tech scrolls during library animations are not detected.
      * @default false
      */
     maintainScrollAtEnd?: boolean | MaintainScrollAtEndOptions;
@@ -338,11 +346,13 @@ interface LegendListSpecificProps<ItemT, TItemType extends string | undefined> {
     maintainScrollAtEndThreshold?: number;
     /**
      * Maintains visibility of content.
-     * - scroll (default: true) stabilizes during size/layout changes while scrolling.
-     * - data (default: false) stabilizes when the data array changes; passing true also sets the RN maintainVisibleContentPosition prop.
+     * - size (default: true) stabilizes during size/layout changes while scrolling.
+     * - data (default: false) stabilizes when the data array changes.
      * - shouldRestorePosition can opt out specific items from data-change anchoring.
      * - undefined (default) enables scroll stabilization but skips data-change anchoring.
-     * - true enables both behaviors; false disables both.
+     * - true enables both JS behaviors; false disables both.
+     * Native iOS maintainVisibleContentPosition is enabled when either size or data stabilization is enabled,
+     * and disabled when both are disabled.
      */
     maintainVisibleContentPosition?: boolean | MaintainVisibleContentPositionConfig<ItemT>;
     /**
@@ -434,8 +444,25 @@ interface LegendListSpecificProps<ItemT, TItemType extends string | undefined> {
      */
     onRefresh?: () => void;
     /**
-     * Called when the list scrolls.
-     */
+     * Called once per accepted user gesture, in either direction: native drag (including
+     * momentum), web wheel/touch movement, non-repeated scroll keydown, or scrollbar drag.
+     * Wheel input at a boundary is ignored unless navigation is active. Without wheel
+     * momentum metadata, gesture boundaries are inferred from timing, direction and force.
+     * iOS status-bar scrolling emits on native onScrollToTop unless accessibility motion
+     * already reported it during the animation.
+     * With a native screen reader enabled, otherwise unowned scroll motion with stable
+     * content/viewport size is inferred as accessibility input (including focus navigation),
+     * once per burst; motion toward the start releases end following. Library animations
+     * and controller/native-ref command windows mask assistive-tech scrolling.
+     * Native commands bypassing the list and its refs (e.g. Reanimated scrollTo worklets)
+     * cannot be distinguished from accessibility input while a screen reader is on; call
+     * cancelScroll() on the JS thread before that navigation to release end following.
+     * Layout/clamp/MVCP events and commands through the list or its refs do not emit it.
+     * @experimental Native pointer/wheel-only input without a screen reader is not detected.
+     * Web scrollbar detection requires pointer events in a measurable, non-overlay gutter.
+     */
+    onUserScroll?: () => void;
+    /** Called when the list scrolls. */
     onScroll?: (event: NativeSyntheticEvent<NativeScrollEvent>) => void;
     /**
      * Called when scrolling reaches the start within onStartReachedThreshold.
@@ -567,6 +594,8 @@ interface AlwaysRenderConfig {
     keys?: string[];
 }
 interface MaintainScrollAtEndOnOptions {
+    /** Follow only additions that preserve every existing item key in order. */
+    dataAppend?: boolean;
     dataChange?: boolean;
     footerLayout?: boolean;
     itemLayout?: boolean;
@@ -608,9 +637,13 @@ type LegendListState = {
     activeStickyIndex: number;
     contentLength: number;
     data: readonly any[];
+    dataKey?: Key;
     elementAtIndex: (index: number) => any;
     end: number;
     endBuffered: number;
+    /** Distance to the physical scroll edge, including the trailing inset. */
+    distanceFromEnd: number;
+    isFollowingEnd: boolean;
     isAtEnd: boolean;
     isAtStart: boolean;
     isNearEnd: boolean;
@@ -620,7 +653,10 @@ type LegendListState = {
     isWithinMaintainScrollAtEndThreshold: boolean;
     getAverageItemSizes: () => Record<string, LegendListAverageItemSize>;
     indexByKey: (key: string) => number | undefined;
-    listen: <T extends LegendListListenerType>(listenerType: T, callback: (value: ListenerTypeValueMap[T]) => void) => () => void;
+    listen: {
+        <T extends Exclude<LegendListListenerType, "isFollowingEnd">>(listenerType: T, callback: (value: Pick<ListenerTypeValueMap, LegendListListenerType>[T]) => void): () => void;
+        <T extends LegendListListenerType>(listenerType: T, callback: (value: Pick<ListenerTypeValueMap, LegendListListenerType>[T]) => void): () => void;
+    };
     listenToPosition: (key: string, callback: (value: number) => void) => () => void;
     positionAtIndex: (index: number) => number;
     positionByKey: (key: string) => number | undefined;
@@ -633,6 +669,28 @@ type LegendListState = {
     startBuffered: number;
 };
 type LegendListRef$1 = {
+    /** Cancels queued and active scrolling, settles its promise, and stops at the observed offset. */
+    cancelScroll(): void;
+    /** Scrolls by stable item identity through prepends; resolves without scrolling if the key is missing or removed. */
+    scrollToKey(params: {
+        key: string;
+        animated?: boolean;
+        viewOffset?: number;
+        viewPosition?: number;
+    }): Promise<void>;
+    /**
+     * Captures an item's key and viewport offset, holding it through layout changes by default.
+     * Omit key to use the first visible item; set hold to false to read without side effects.
+     * Returns undefined before initial placement, during dataset replacement, or if no item is found.
+     * While following at the end, returns the anchor without interrupting end following.
+     */
+    anchorVisibleContent(options?: {
+        key?: string;
+        hold?: boolean;
+    }): {
+        key: string;
+        offset: number;
+    } | undefined;
     /**
      * Clears internal virtualization caches.
      * @param options - Cache clearing options.
@@ -675,20 +733,40 @@ type LegendListRef$1 = {
      * @param params - Parameters for scrolling.
      * @param params.animated - If true, animates the scroll. Default: true.
      * @param params.index - The index to scroll to.
+     * @param params.itemOffset - Region start measured from the item's start along the scroll axis. Default: 0 when itemLength is provided.
+     * @param params.itemLength - Region length along the scroll axis. Default: 0 when itemOffset is provided. Omit both to reveal the whole item.
+     * @param params.viewportMargin - Space to keep clear at the start and end of the viewport along the scroll axis.
+     * The region should be within the item. A visible region does not scroll; otherwise its nearest edge aligns inside the margins. A region larger than the available space aligns its start.
      */
     scrollIndexIntoView(params: {
         animated?: boolean | undefined;
         index: number;
+        itemOffset?: number;
+        itemLength?: number;
+        viewportMargin?: {
+            start?: number;
+            end?: number;
+        };
     }): Promise<void>;
     /**
-     * Scrolls a specific index into view.
+     * Scrolls a specific item into view.
      * @param params - Parameters for scrolling.
      * @param params.animated - If true, animates the scroll. Default: true.
      * @param params.item - The item to scroll to.
+     * @param params.itemOffset - Region start measured from the item's start along the scroll axis. Default: 0 when itemLength is provided.
+     * @param params.itemLength - Region length along the scroll axis. Default: 0 when itemOffset is provided. Omit both to reveal the whole item.
+     * @param params.viewportMargin - Space to keep clear at the start and end of the viewport along the scroll axis.
+     * The region should be within the item. A visible region does not scroll; otherwise its nearest edge aligns inside the margins. A region larger than the available space aligns its start.
      */
     scrollItemIntoView(params: {
         animated?: boolean | undefined;
         item: any;
+        itemOffset?: number;
+        itemLength?: number;
+        viewportMargin?: {
+            start?: number;
+            end?: number;
+        };
     }): Promise<void>;
     /**
      * Scrolls to the end of the list.
@@ -818,7 +896,9 @@ type LegendListPropsOverrides<ItemT, TItemType extends string | undefined> = Omi
 };
 type LegendListProps<ItemT = any, TItemType extends string | undefined = string | undefined> = LegendListPropsOverrides<ItemT, TItemType>;
 type LegendListRef = Omit<LegendListRef$1, "getAnimatableRef" | "getNativeScrollRef" | "getScrollResponder" | "reportContentInset"> & {
+    /** Call cancelScroll() before scrolling it directly so end following and list scrolling stop first. */
     getAnimatableRef(): React.ElementRef<typeof ScrollViewComponent>;
+    /** Call cancelScroll() before scrolling it directly so end following and list scrolling stop first. */
     getNativeScrollRef(): React.ElementRef<typeof ScrollViewComponent>;
     getScrollResponder(): ScrollResponderMixin;
     reportContentInset(inset?: Partial<Insets$1> | null): void;
@@ -875,6 +955,14 @@ type SectionListProps<ItemT, SectionT extends SectionBase<ItemT> = SectionBase<I
     stickySectionHeadersEnabled?: boolean;
     onViewableItemsChanged?: SectionListOnViewableItemsChanged<ItemT, SectionT>;
 };
+/**
+ * Key-based methods use flattened keys: `${sectionKey}:item:${itemKey}` for items,
+ * `${sectionKey}:header` and `${sectionKey}:footer` for section chrome,
+ * `${sectionKey}:separator:${itemIndex}` for item separators, and
+ * `${sectionKey}:section-separator` for section separators.
+ * `sectionKey` is the section's key, or `section-${sectionIndex}` when omitted; `itemKey` comes
+ * from the section or list keyExtractor. anchorVisibleContent accepts and returns these same keys.
+ */
 type SectionListRef = LegendListRef & {
     scrollToLocation(params: SectionListScrollParams): void;
 };