@legendapp/list 3.0.0-beta.43 → 3.0.0-beta.45

package/animated.d.ts

@@ -2,16 +2,28 @@ import * as React from 'react';
 import { Key } from 'react';
 import { ScrollViewProps, NativeSyntheticEvent as NativeSyntheticEvent$1, NativeScrollEvent as NativeScrollEvent$1, ScrollView, StyleProp as StyleProp$1, ViewStyle as ViewStyle$1, ScrollViewComponent, ScrollResponderMixin, Insets as Insets$1, Animated } from 'react-native';
 
-type ListenerType = "activeStickyIndex" | "debugComputedScroll" | "debugRawScroll" | "extraData" | "footerSize" | "headerSize" | "lastItemKeys" | "lastPositionUpdate" | "maintainVisibleContentPosition" | "numColumns" | "numContainers" | "numContainersPooled" | "otherAxisSize" | "readyToRender" | "scrollAdjust" | "scrollAdjustPending" | "scrollAdjustUserOffset" | "scrollSize" | "snapToOffsets" | "stylePaddingTop" | "totalSize" | `containerColumn${number}` | `containerSpan${number}` | `containerItemData${number}` | `containerItemKey${number}` | `containerPosition${number}` | `containerSticky${number}`;
-type LegendListListenerType = Extract<ListenerType, "activeStickyIndex" | "footerSize" | "headerSize" | "lastItemKeys" | "lastPositionUpdate" | "numContainers" | "numContainersPooled" | "otherAxisSize" | "readyToRender" | "snapToOffsets" | "totalSize">;
+interface MaintainVisibleContentPositionNormalized<ItemT = any> {
+    data: boolean;
+    size: boolean;
+    shouldRestorePosition?: (item: ItemT, index: number, data: readonly ItemT[]) => boolean;
+}
+
+type ListenerType = "activeStickyIndex" | "anchoredEndSpaceSize" | "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" | `containerColumn${number}` | `containerSpan${number}` | `containerItemData${number}` | `containerItemKey${number}` | `containerPosition${number}` | `containerSticky${number}`;
+type LegendListListenerType = Extract<ListenerType, "activeStickyIndex" | "anchoredEndSpaceSize" | "footerSize" | "headerSize" | "isAtEnd" | "isAtStart" | "isNearEnd" | "isNearStart" | "isWithinMaintainScrollAtEndThreshold" | "lastItemKeys" | "lastPositionUpdate" | "numContainers" | "numContainersPooled" | "otherAxisSize" | "readyToRender" | "snapToOffsets" | "totalSize">;
 type ListenerTypeValueMap = {
     activeStickyIndex: number;
+    anchoredEndSpaceSize: number;
     animatedScrollY: any;
     debugComputedScroll: number;
     debugRawScroll: number;
     extraData: any;
     footerSize: number;
     headerSize: number;
+    isAtEnd: boolean;
+    isAtStart: boolean;
+    isNearEnd: boolean;
+    isNearStart: boolean;
+    isWithinMaintainScrollAtEndThreshold: boolean;
     lastItemKeys: string[];
     lastPositionUpdate: number;
     maintainVisibleContentPosition: MaintainVisibleContentPositionNormalized;
@@ -113,6 +125,11 @@ interface LegendListSpecificProps<ItemT, TItemType extends string | undefined> {
      * Style applied to each column's wrapper view.
      */
     columnWrapperStyle?: ColumnWrapperStyle;
+    /**
+     * 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;
     /**
      * Distance in pixels to pre-render items ahead of the visible area.
      * @default 250
@@ -136,33 +153,35 @@ 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
      */
     getEstimatedItemSize?: (item: ItemT, index: number, type: TItemType) => number;
     /**
-     * Customize layout for multi-column lists, such as allowing items to span multiple columns.
-     * Similar to FlashList's overrideItemLayout.
+     * In case items always have a fixed size, you can provide a function to return it.
      */
-    overrideItemLayout?: (layout: {
-        span?: number;
-    }, item: ItemT, index: number, maxColumns: number, extraData?: any) => void;
+    getFixedItemSize?: (item: ItemT, index: number, type: TItemType) => number | undefined;
+    /**
+     * Returns a stable item type used for pooling and size estimation.
+     */
+    getItemType?: (item: ItemT, index: number) => TItemType;
+    /**
+     * Component to render between items, receiving the leading item as prop.
+     */
+    ItemSeparatorComponent?: React.ComponentType<{
+        leadingItem: ItemT;
+    }>;
     /**
      * Ratio of initial container pool size to data length (e.g., 0.5 for half).
      * @default 2
      */
     initialContainerPoolRatio?: number | undefined;
     /**
-     * Initial scroll position in pixels.
-     * @default 0
+     * When true, the list initializes scrolled to the last item.
+     * Overrides `initialScrollIndex` and `initialScrollOffset` when data is available.
+     * @default false
      */
-    initialScrollOffset?: number;
+    initialScrollAtEnd?: boolean;
     /**
      * Index to scroll to initially.
      * @default 0
@@ -173,17 +192,14 @@ interface LegendListSpecificProps<ItemT, TItemType extends string | undefined> {
         viewPosition?: number | undefined;
     };
     /**
-     * When true, the list initializes scrolled to the last item.
-     * Overrides `initialScrollIndex` and `initialScrollOffset` when data is available.
-     * @default false
+     * Initial scroll position in pixels.
+     * @default 0
      */
-    initialScrollAtEnd?: boolean;
+    initialScrollOffset?: number;
     /**
-     * Component to render between items, receiving the leading item as prop.
+     * Custom equality function to detect semantically unchanged items.
      */
-    ItemSeparatorComponent?: React.ComponentType<{
-        leadingItem: ItemT;
-    }>;
+    itemsAreEqual?: (itemPrevious: ItemT, item: ItemT, index: number, data: readonly ItemT[]) => boolean;
     /**
      * Function to extract a unique key for each item.
      */
@@ -229,10 +245,9 @@ interface LegendListSpecificProps<ItemT, TItemType extends string | undefined> {
      */
     maintainVisibleContentPosition?: boolean | MaintainVisibleContentPositionConfig<ItemT>;
     /**
-     * Web only: when true, listens to window/body scrolling instead of rendering a scrollable list container.
-     * @default false
+     * Keeps an item visually anchored to the start by adding trailing space when the content below it underflows.
      */
-    useWindowScroll?: boolean;
+    anchoredEndSpace?: AnchoredEndSpaceConfig;
     /**
      * Number of columns to render items in.
      * @default 1
@@ -259,6 +274,12 @@ interface LegendListSpecificProps<ItemT, TItemType extends string | undefined> {
         itemKey: string;
         itemData: ItemT;
     }) => void;
+    /**
+     * Called after the initial render work completes.
+     */
+    onLoad?: (info: {
+        elapsedTimeInMs: number;
+    }) => void;
     /**
      * Called when list layout metrics change.
      */
@@ -267,6 +288,9 @@ interface LegendListSpecificProps<ItemT, TItemType extends string | undefined> {
      * Function to call when the user pulls to refresh.
      */
     onRefresh?: () => void;
+    /**
+     * Called when the list scrolls.
+     */
     onScroll?: (event: NativeSyntheticEvent<NativeScrollEvent>) => void;
     /**
      * Called when scrolling reaches the start within onStartReachedThreshold.
@@ -290,6 +314,12 @@ interface LegendListSpecificProps<ItemT, TItemType extends string | undefined> {
      * Called when the viewability of items changes.
      */
     onViewableItemsChanged?: OnViewableItemsChanged<ItemT> | undefined;
+    /**
+     * Customize layout for multi-column lists, such as allowing items to span multiple columns.
+     */
+    overrideItemLayout?: (layout: {
+        span?: number;
+    }, item: ItemT, index: number, maxColumns: number, extraData?: any) => void;
     /**
      * Offset in pixels for the refresh indicator.
      * @default 0
@@ -315,6 +345,10 @@ interface LegendListSpecificProps<ItemT, TItemType extends string | undefined> {
      * @default (props) => <ScrollView {...props} />
      */
     renderScrollComponent?: (props: any) => React.ReactElement | null;
+    /**
+     * Array of item indices to use as snap points.
+     */
+    snapToIndices?: number[];
     /**
      * This will log a suggested estimatedItemSize.
      * @required
@@ -329,15 +363,6 @@ interface LegendListSpecificProps<ItemT, TItemType extends string | undefined> {
      * Pairs of viewability configs and their callbacks for tracking visibility.
      */
     viewabilityConfigCallbackPairs?: ViewabilityConfigCallbackPairs<ItemT> | undefined;
-    /**
-     * If true, delays rendering until initial layout is complete.
-     * @default false
-     */
-    waitForInitialLayout?: boolean;
-    onLoad?: (info: {
-        elapsedTimeInMs: number;
-    }) => void;
-    snapToIndices?: number[];
     /**
      * Array of child indices determining which children get docked to the top of the screen when scrolling.
      * For example, passing stickyHeaderIndices={[0]} will cause the first child to be fixed to the top of the scroll view.
@@ -354,9 +379,11 @@ interface LegendListSpecificProps<ItemT, TItemType extends string | undefined> {
      * @default undefined
      */
     stickyHeaderConfig?: StickyHeaderConfig;
-    getItemType?: (item: ItemT, index: number) => TItemType;
-    getFixedItemSize?: (item: ItemT, index: number, type: TItemType) => number | undefined;
-    itemsAreEqual?: (itemPrevious: ItemT, item: ItemT, index: number, data: readonly ItemT[]) => boolean;
+    /**
+     * Web only: when true, listens to window/body scrolling instead of rendering a scrollable list container.
+     * @default false
+     */
+    useWindowScroll?: boolean;
 }
 type LegendListPropsBase<ItemT, TScrollViewProps = Record<string, any>, TItemType extends string | undefined = string | undefined> = BaseScrollViewProps<TScrollViewProps> & LegendListSpecificProps<ItemT, TItemType> & (DataModeProps<ItemT, TItemType> | ChildrenModeProps);
 interface MaintainVisibleContentPositionConfig<ItemT = any> {
@@ -364,10 +391,12 @@ interface MaintainVisibleContentPositionConfig<ItemT = any> {
     size?: boolean;
     shouldRestorePosition?: (item: ItemT, index: number, data: readonly ItemT[]) => boolean;
 }
-interface MaintainVisibleContentPositionNormalized<ItemT = any> {
-    data: boolean;
-    size: boolean;
-    shouldRestorePosition?: (item: ItemT, index: number, data: readonly ItemT[]) => boolean;
+interface AnchoredEndSpaceConfig {
+    anchorIndex: number;
+    anchorOffset?: number;
+    anchorMaxSize?: number;
+    includeInEndInset?: boolean;
+    onSizeChanged?: (size: number) => void;
 }
 interface StickyHeaderConfig {
     /**
@@ -430,8 +459,11 @@ type LegendListState = {
     endBuffered: number;
     isAtEnd: boolean;
     isAtStart: boolean;
+    isNearEnd: boolean;
+    isNearStart: boolean;
     isEndReached: boolean;
     isStartReached: boolean;
+    isWithinMaintainScrollAtEndThreshold: boolean;
     listen: <T extends LegendListListenerType>(listenerType: T, callback: (value: ListenerTypeValueMap[T]) => void) => () => void;
     listenToPosition: (key: string, callback: (value: number) => void) => () => void;
     positionAtIndex: (index: number) => number;
@@ -570,10 +602,15 @@ interface ViewabilityConfigCallbackPair<ItemT = any> {
     viewabilityConfig: ViewabilityConfig;
 }
 type ViewabilityConfigCallbackPairs<ItemT> = ViewabilityConfigCallbackPair<ItemT>[];
-type OnViewableItemsChanged<ItemT> = ((info: {
-    viewableItems: Array<ViewToken<ItemT>>;
+interface OnViewableItemsChangedInfo<ItemT> {
     changed: Array<ViewToken<ItemT>>;
-}) => void) | null;
+    end: number;
+    endBuffered: number;
+    start: number;
+    startBuffered: number;
+    viewableItems: Array<ViewToken<ItemT>>;
+}
+type OnViewableItemsChanged<ItemT> = ((info: OnViewableItemsChangedInfo<ItemT>) => void) | null;
 interface ViewabilityConfig {
     /**
      * A unique ID to identify this viewability config
@@ -604,7 +641,7 @@ interface ViewabilityConfig {
     waitForInteraction?: boolean | undefined;
 }
 
-type LegendListPropsOverrides<ItemT, TItemType extends string | undefined> = Omit<LegendListPropsBase<ItemT, ScrollViewProps, TItemType>, "onScroll" | "refScrollView" | "renderScrollComponent" | "ListHeaderComponentStyle" | "ListFooterComponentStyle"> & {
+type LegendListPropsOverrides<ItemT, TItemType extends string | undefined> = Omit<LegendListPropsBase<ItemT, ScrollViewProps, TItemType>, "anchoredEndSpace" | "onScroll" | "refScrollView" | "renderScrollComponent" | "ListHeaderComponentStyle" | "ListFooterComponentStyle"> & {
     onScroll?: (event: NativeSyntheticEvent$1<NativeScrollEvent$1>) => void;
     refScrollView?: React.Ref<ScrollView>;
     renderScrollComponent?: (props: ScrollViewProps) => React.ReactElement<ScrollViewProps>;