@legendapp/list 3.6.0 → 3.7.1

package/CHANGELOG.md

@@ -1,3 +1,23 @@
+## 3.7.1
+
+- Fix: Loading callbacks respond reliably to data changes and new scroll gestures.
+- Fix: Lists preserve scroll positions as rows, insets, and viewport sizes change.
+- Fix: iOS lists with `contentInset.top` now rest at and measure from the inset start.
+- Fix: Keyboard dismissal and interrupted scrolling no longer cause jumps or doubled movement.
+- Fix: Rows stay correctly positioned after items are inserted, removed, or reordered.
+- Perf: Lists prepare more rows before the first scroll.
+
+## 3.7.0
+
+- Feat: `LegendListRef` gains `cancelScroll`, `scrollToKey`, `anchorVisibleContent`; state gains `distanceFromEnd`, `isFollowingEnd`.
+- Feat: Expose end-following state and allow following only newly appended items.
+- Feat: `onUserScroll` reports user scroll gestures.
+- Fix: Scroll promises resolve reliably when scrolling finishes or is interrupted.
+- Fix: Lists follow new content smoothly and respect users scrolling away from the end. #563 #568
+- Fix: Scrolling to the end while closing the keyboard moves smoothly in one motion. #557
+- Fix: Row sizing and layout changes preserve visible content and improve viewability accuracy.
+- Perf: Recycled lists reuse rows more efficiently and process appended data faster.
+
 ## 3.6.0
 
 - Feat: Add `viewPositionFallback` to align oversized items to the start or end of the viewport during initial or programmatic scrolling, while keeping `viewPosition` alignment for items that fit.

package/README.md

@@ -26,8 +26,9 @@ Beyond standard `FlatList` capabilities:
 *   `recycleItems`: (boolean) Toggles item component recycling.
     *   `true`: Reuses item components for optimal performance. Be cautious if your item components contain local state, as it might be reused unexpectedly.
     *   `false` (default): Creates new item components every time. Less performant but safer if items have complex internal state.
-*   `maintainScrollAtEnd`: Keeps the list pinned to the tail when the user is already near the end (within `maintainScrollAtEndThreshold * screen height`). Pass `true` for all triggers, or `{ animated?: boolean, on?: { dataChange?: boolean, layout?: boolean, itemLayout?: boolean } }`; if `on` is omitted, the object form also enables all triggers.
-*   `maintainVisibleContentPosition`: Keeps visible content steady during size/layout changes while scrolling up or when items resize above the viewport (default). Pass `true` or `{ data: true }` to also anchor during data updates; pass `false` to disable; pass `{ size: false }` to opt out of scroll-time stabilization.
+*   `maintainScrollAtEnd`: Keeps the list pinned to the tail when the user is already near the end (within `maintainScrollAtEndThreshold * screen height`). Pass `true` for all triggers, or `{ animated?: boolean, on?: { dataChange?: boolean, dataAppend?: boolean, footerLayout?: boolean, layout?: boolean, itemLayout?: boolean } }`; `dataAppend` follows only additions that preserve existing item keys in order. If `on` is omitted, the object form also enables all triggers.
+*   `onUserScroll` (experimental): Runs once per accepted user gesture, including inferred native accessibility scrolling. See the [API JSDoc](https://github.com/LegendApp/legend-list/blob/main/src/types.base.ts#L376-L394) for supported input, gesture grouping, and native commands that require `cancelScroll()`.
+*   `maintainVisibleContentPosition`: Keeps visible content steady during size/layout changes while scrolling up or when items resize above the viewport (default). Pass `true` or `{ data: true }` to also anchor during data updates; pass `false` to disable JS size/data stabilization; pass `{ size: false }` to opt out of scroll-time stabilization. Native iOS maintainVisibleContentPosition is enabled when either size or data stabilization is enabled, and disabled when both are disabled.
 *   `alignItemsAtEnd`: (boolean) Useful for chat UIs, content smaller than the View will be aligned to the bottom of the list.
 
 ---
@@ -74,7 +75,7 @@ interface UserData {
 }
 
 const LegendListExample = () => {
-    // Optional: Ref for accessing list methods (e.g., scrollTo)
+    // Optional: Ref for accessing list methods (e.g., scrollToIndex)
     const listRef = useRef<LegendListRef | null>(null)
 
     const data = []
@@ -112,6 +113,20 @@ export default LegendListExample
 
 ---
 
+### Paging at reached edges
+
+Inside their thresholds, `onEndReached` and `onStartReached` fire again when the data length changes, or when a new data array arrives and the content size differs from the size at the last callback. A new array with the same length and content size does not re-arm an edge. An empty page that leaves both unchanged does not automatically request another page.
+
+A new user gesture toward an edge can retry unchanged data inside its threshold. If the current array already received a callback for changed content, that delivery counts toward the next gesture; a later gesture can retry it. Keep the data reference stable between updates to preserve that duplicate-callback protection.
+
+While the scroll offset stays unchanged, row measurements, loading footers and other layout changes do not re-arm an already reached edge, even if they temporarily move it outside its hysteresis band. Scroll-offset changes, including MVCP compensation and native clamping, retain the existing distance-based reset behavior. Empty data fires neither callback.
+
+### Native scroll offsets and top insets
+
+`scrollToOffset({ offset })` and `initialScrollOffset` use raw native scroll offsets, like React Native's `ScrollView`. With a vertical iOS `contentInset.top` of `T`, the resting start is `-T`: use `scrollToOffset({ offset: -T })` or `initialScrollOffset={-T}` to request it. An explicit `0` still requests native offset `0`, subject to the reachable content bounds. Omitting the initial target starts at `-T`.
+
+`scrollToEnd()` lands at `-T` when the content plus both insets fits within the viewport. Start thresholds and `distanceFromStart` measure from this resting start.
+
 ### Sharing a scrollbar on the web
 
 React DOM lists can use an ancestor element's scrollbar with `scrollElement`:

package/animated.d.ts

@@ -8,8 +8,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;
@@ -21,6 +21,7 @@ type ListenerTypeValueMap = {
     extraData: any;
     footerSize: number;
     headerSize: number;
+    isFollowingEnd: boolean;
     isAtEnd: boolean;
     isAtStart: boolean;
     isNearEnd: boolean;
@@ -34,6 +35,7 @@ type ListenerTypeValueMap = {
     numContainersPooled: number;
     otherAxisSize: number;
     readyToRender: boolean;
+    isScrollActive: boolean;
     scrollAdjust: number;
     scrollAdjustPending: number;
     scrollAdjustUserOffset: number;
@@ -199,6 +201,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;
     /**
@@ -271,6 +274,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;
@@ -281,11 +289,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>;
     /**
@@ -377,8 +387,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.
@@ -510,6 +537,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;
@@ -551,9 +580,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;
@@ -563,7 +596,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;
@@ -576,6 +612,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.
@@ -618,20 +676,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.
@@ -761,7 +839,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/keyboard-legacy.d.ts

@@ -1,4 +1,5 @@
 import * as React from 'react';
+import { Key } from 'react';
 import { ScrollViewComponent, ScrollResponderMixin, Insets as Insets$1 } from 'react-native';
 import { ScrollEvent, ScrollHandlerProcessed } from 'react-native-reanimated';
 import { AnimatedLegendListProps } from '@legendapp/list/reanimated';
@@ -9,8 +10,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 +23,7 @@ type ListenerTypeValueMap = {
     extraData: any;
     footerSize: number;
     headerSize: number;
+    isFollowingEnd: boolean;
     isAtEnd: boolean;
     isAtStart: boolean;
     isNearEnd: boolean;
@@ -35,6 +37,7 @@ type ListenerTypeValueMap = {
     numContainersPooled: number;
     otherAxisSize: number;
     readyToRender: boolean;
+    isScrollActive: boolean;
     scrollAdjust: number;
     scrollAdjustPending: number;
     scrollAdjustUserOffset: number;
@@ -88,9 +91,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;
@@ -100,7 +107,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;
@@ -113,6 +123,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.
@@ -155,20 +187,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.
@@ -239,7 +291,9 @@ type LegendListRef$1 = {
 };
 
 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/keyboard.d.ts

@@ -1,4 +1,5 @@
 import * as React from 'react';
+import { Key } from 'react';
 import { ScrollViewComponent, ScrollResponderMixin, Insets as Insets$1, ScrollViewProps, View, LayoutChangeEvent } from 'react-native';
 import { KeyboardChatScrollViewProps } from 'react-native-keyboard-controller';
 import { SharedValue } from 'react-native-reanimated';
@@ -10,8 +11,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;
@@ -23,6 +24,7 @@ type ListenerTypeValueMap = {
     extraData: any;
     footerSize: number;
     headerSize: number;
+    isFollowingEnd: boolean;
     isAtEnd: boolean;
     isAtStart: boolean;
     isNearEnd: boolean;
@@ -36,6 +38,7 @@ type ListenerTypeValueMap = {
     numContainersPooled: number;
     otherAxisSize: number;
     readyToRender: boolean;
+    isScrollActive: boolean;
     scrollAdjust: number;
     scrollAdjustPending: number;
     scrollAdjustUserOffset: number;
@@ -106,9 +109,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;
@@ -118,7 +125,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;
@@ -131,6 +141,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.
@@ -173,20 +205,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.
@@ -257,7 +309,9 @@ type LegendListRef$1 = {
 };
 
 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;
@@ -270,9 +324,7 @@ type ScrollMessageToEndOptions = {
 };
 type KeyboardScrollToEndListRef = {
     current: {
-        scrollToEnd(params?: {
-            animated?: boolean;
-        }): Promise<void>;
+        scrollToEnd: LegendListRef["scrollToEnd"];
     } | null;
 };
 type UseKeyboardScrollToEndOptions = {