@legendapp/list 3.5.0 → 3.7.0

package/react.d.ts

@@ -35,8 +35,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;
@@ -48,6 +48,7 @@ type ListenerTypeValueMap = {
     extraData: any;
     footerSize: number;
     headerSize: number;
+    isFollowingEnd: boolean;
     isAtEnd: boolean;
     isAtStart: boolean;
     isNearEnd: boolean;
@@ -61,6 +62,7 @@ type ListenerTypeValueMap = {
     numContainersPooled: number;
     otherAxisSize: number;
     readyToRender: boolean;
+    isScrollActive: boolean;
     scrollAdjust: number;
     scrollAdjustPending: number;
     scrollAdjustUserOffset: number;
@@ -226,6 +228,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;
     /**
@@ -252,6 +255,8 @@ interface LegendListSpecificProps<ItemT, TItemType extends string | undefined> {
         index: number;
         viewOffset?: number | undefined;
         viewPosition?: number | undefined;
+        /** Alignment used only when the item exceeds the viewport. Omit to preserve viewPosition. */
+        viewPositionFallback?: "start" | "end";
     };
     /**
      * Initial scroll position in pixels.
@@ -296,6 +301,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;
@@ -306,11 +316,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>;
     /**
@@ -402,8 +414,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.
@@ -535,6 +564,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;
@@ -576,9 +607,13 @@ type LegendListState$1 = {
     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;
@@ -588,7 +623,10 @@ type LegendListState$1 = {
     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;
@@ -601,6 +639,28 @@ type LegendListState$1 = {
     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.
@@ -643,20 +703,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.
@@ -678,6 +758,8 @@ type LegendListRef$1 = {
         index: number;
         viewOffset?: number | undefined;
         viewPosition?: number | undefined;
+        /** Alignment used only when the item exceeds the viewport. Omit to preserve viewPosition. */
+        viewPositionFallback?: "start" | "end";
     }): Promise<void>;
     /**
      * Scrolls to a specific item in the list.
@@ -692,6 +774,8 @@ type LegendListRef$1 = {
         item: any;
         viewOffset?: number | undefined;
         viewPosition?: number | undefined;
+        /** Alignment used only when the item exceeds the viewport. Omit to preserve viewPosition. */
+        viewPositionFallback?: "start" | "end";
     }): Promise<void>;
     /**
      * Scrolls to a specific offset in pixels.
@@ -731,6 +815,10 @@ interface ViewToken<ItemT = any> {
 interface ViewAmountToken<ItemT = any> extends ViewToken<ItemT> {
     percentOfScroller: number;
     percentVisible: number;
+    /**
+     * Viewport size used for this measurement, with any integration-reported
+     * occlusion (for example a keyboard) already subtracted.
+     */
     scrollSize: number;
     size: number;
     sizeVisible: number;
@@ -790,6 +878,8 @@ interface ScrollIndexWithOffset {
     index: number;
     viewOffset?: number;
     viewPosition?: number;
+    /** Alignment used only when the item exceeds the viewport. Omit to preserve viewPosition. */
+    viewPositionFallback?: "start" | "end";
 }
 interface ScrollIndexWithOffsetPosition extends ScrollIndexWithOffset {
     viewPosition?: number;
@@ -821,6 +911,7 @@ interface LooseScrollViewProps {
     onMomentumScrollEnd?: (event: NativeSyntheticEvent<NativeScrollEvent>) => void;
     onScroll?: (event: NativeSyntheticEvent<NativeScrollEvent>) => void;
     onScrollBeginDrag?: (event: NativeSyntheticEvent<NativeScrollEvent>) => void;
+    onScrollToTop?: (event: NativeSyntheticEvent<NativeScrollEvent>) => void;
     onScrollEndDrag?: (event: NativeSyntheticEvent<NativeScrollEvent>) => void;
     refreshControl?: ReactElement | null;
     removeClippedSubviews?: boolean;