@legendapp/list 1.0.0-beta.9 → 1.0.1

package/index.d.mts

@@ -1,54 +1,139 @@
-import * as react from 'react';
-import { ComponentProps, ReactNode, ForwardedRef, ReactElement } from 'react';
-import { ScrollView, StyleProp, ViewStyle, ScrollViewProps, ScrollViewComponent, ScrollResponderMixin } from 'react-native';
-import Animated from 'react-native-reanimated';
+import * as React$1 from 'react';
+import { ComponentProps, ReactNode, Dispatch, SetStateAction } from 'react';
+import * as react_native from 'react-native';
+import { ScrollView, StyleProp, ViewStyle, ScrollViewProps, NativeSyntheticEvent, NativeScrollEvent, ScrollViewComponent, ScrollResponderMixin } from 'react-native';
+import react_native_reanimated__default from 'react-native-reanimated';
 
 declare class ScrollAdjustHandler {
     private ctx;
     private appliedAdjust;
-    private pendingAdjust;
     private busy;
     private context;
-    private firstAdjust;
+    private isPaused;
+    private isDisabled;
     constructor(ctx: any);
+    private doAjdust;
     requestAdjust(adjust: number, onAdjusted: (diff: number) => void): void;
     getAppliedAdjust(): number;
+    pauseAdjust(): void;
+    setDisableAdjust(disable: boolean): void;
+    unPauseAdjust(): boolean;
 }
 
-type LegendListPropsBase<ItemT, TScrollView extends ComponentProps<typeof ScrollView> | ComponentProps<typeof Animated.ScrollView>> = Omit<TScrollView, 'contentOffset' | 'contentInset' | 'maintainVisibleContentPosition' | 'stickyHeaderIndices'> & {
+type LegendListPropsBase<ItemT, TScrollView extends ComponentProps<typeof ScrollView> | ComponentProps<typeof react_native_reanimated__default.ScrollView>> = Omit<TScrollView, "contentOffset" | "contentInset" | "maintainVisibleContentPosition" | "stickyHeaderIndices"> & {
+    /**
+     * If true, aligns items at the end of the list.
+     * @default false
+     */
+    alignItemsAtEnd?: boolean;
+    /**
+     * Style applied to each column's wrapper view.
+     */
+    columnWrapperStyle?: ColumnWrapperStyle;
+    /**
+     * Array of items to render in the list.
+     * @required
+     */
     data: ReadonlyArray<ItemT>;
+    /**
+     * Distance in pixels to pre-render items ahead of the visible area.
+     * @default 250
+     */
+    drawDistance?: number;
+    /**
+     * Estimated size of each item in pixels, a hint for the first render. After some
+     * items are rendered, the average size of rendered items will be used instead.
+     * @default undefined
+     */
+    estimatedItemSize?: number;
+    /**
+     * Extra data to trigger re-rendering when changed.
+     */
+    extraData?: any;
+    /**
+     * 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?: (index: number, item: ItemT) => number;
+    /**
+     * Ratio of initial container pool size to data length (e.g., 0.5 for half).
+     * @default 1
+     */
+    initialContainerPoolRatio?: number | undefined;
+    /**
+     * Initial scroll position in pixels.
+     * @default 0
+     */
     initialScrollOffset?: number;
+    /**
+     * Index to scroll to initially.
+     * @default 0
+     */
     initialScrollIndex?: number;
-    drawDistance?: number;
-    recycleItems?: boolean;
-    onEndReachedThreshold?: number | null | undefined;
-    onStartReachedThreshold?: number | null | undefined;
+    /**
+     * Component to render between items, receiving the leading item as prop.
+     */
+    ItemSeparatorComponent?: React.ComponentType<{
+        leadingItem: ItemT;
+    }>;
+    /**
+     * Function to extract a unique key for each item.
+     */
+    keyExtractor?: (item: ItemT, index: number) => string;
+    /**
+     * Component or element to render when the list is empty.
+     */
+    ListEmptyComponent?: React.ComponentType<any> | React.ReactElement | null | undefined;
+    /**
+     * Component or element to render below the list.
+     */
+    ListFooterComponent?: React.ComponentType<any> | React.ReactElement | null | undefined;
+    /**
+     * Style for the footer component.
+     */
+    ListFooterComponentStyle?: StyleProp<ViewStyle> | undefined;
+    /**
+     * Component or element to render above the list.
+     */
+    ListHeaderComponent?: React.ComponentType<any> | React.ReactElement | null | undefined;
+    /**
+     * Style for the header component.
+     */
+    ListHeaderComponentStyle?: StyleProp<ViewStyle> | undefined;
+    /**
+     * If true, auto-scrolls to end when new items are added.
+     * @default false
+     */
     maintainScrollAtEnd?: boolean;
+    /**
+     * Distance threshold in percentage of screen size to trigger maintainScrollAtEnd.
+     * @default 0.1
+     */
     maintainScrollAtEndThreshold?: number;
-    alignItemsAtEnd?: boolean;
+    /**
+     * If true, maintains visibility of content during scroll (e.g., after insertions).
+     * @default false
+     */
     maintainVisibleContentPosition?: boolean;
+    /**
+     * Number of columns to render items in.
+     * @default 1
+     */
     numColumns?: number;
-    refScrollView?: React.Ref<ScrollView>;
-    waitForInitialLayout?: boolean;
-    estimatedItemSize?: number;
-    getEstimatedItemSize?: (index: number, item: ItemT) => number;
-    onStartReached?: ((info: {
-        distanceFromStart: number;
-    }) => void) | null | undefined;
+    /**
+     * Called when scrolling reaches the end within onEndReachedThreshold.
+     */
     onEndReached?: ((info: {
         distanceFromEnd: number;
     }) => void) | null | undefined;
-    keyExtractor?: (item: ItemT, index: number) => string;
-    renderItem?: (props: LegendListRenderItemProps<ItemT>) => ReactNode;
-    ListHeaderComponent?: React.ComponentType<any> | React.ReactElement | null | undefined;
-    ListHeaderComponentStyle?: StyleProp<ViewStyle> | undefined;
-    ListFooterComponent?: React.ComponentType<any> | React.ReactElement | null | undefined;
-    ListFooterComponentStyle?: StyleProp<ViewStyle> | undefined;
-    ListEmptyComponent?: React.ComponentType<any> | React.ReactElement | null | undefined;
-    ItemSeparatorComponent?: React.ComponentType<any>;
-    viewabilityConfigCallbackPairs?: ViewabilityConfigCallbackPairs | undefined;
-    viewabilityConfig?: ViewabilityConfig;
-    onViewableItemsChanged?: OnViewableItemsChanged | undefined;
+    /**
+     * How close to the end (in fractional units of visible length) to trigger onEndReached.
+     * @default 0.5
+     */
+    onEndReachedThreshold?: number | null | undefined;
+    /**
+     * Called when an item's size changes.
+     */
     onItemSizeChanged?: (info: {
         size: number;
         previous: number;
@@ -56,19 +141,85 @@ type LegendListPropsBase<ItemT, TScrollView extends ComponentProps<typeof Scroll
         itemKey: string;
         itemData: ItemT;
     }) => void;
+    /**
+     * Function to call when the user pulls to refresh.
+     */
+    onRefresh?: () => void;
+    /**
+     * Called when scrolling reaches the start within onStartReachedThreshold.
+     */
+    onStartReached?: ((info: {
+        distanceFromStart: number;
+    }) => void) | null | undefined;
+    /**
+     * How close to the start (in fractional units of visible length) to trigger onStartReached.
+     * @default 0.5
+     */
+    onStartReachedThreshold?: number | null | undefined;
+    /**
+     * Called when the viewability of items changes.
+     */
+    onViewableItemsChanged?: OnViewableItemsChanged | undefined;
+    /**
+     * Offset in pixels for the refresh indicator.
+     * @default 0
+     */
+    progressViewOffset?: number;
+    /**
+     * If true, recycles item views for better performance.
+     * @default false
+     */
+    recycleItems?: boolean;
+    /**
+     * Ref to the underlying ScrollView component.
+     */
+    refScrollView?: React.Ref<ScrollView>;
+    /**
+     * If true, shows a refresh indicator.
+     * @default false
+     */
+    refreshing?: boolean;
+    /**
+     * Function to render each item in the list.
+     * @required
+     */
+    renderItem?: (props: LegendListRenderItemProps<ItemT>) => ReactNode;
     /**
      * Render custom ScrollView component.
      * @default (props) => <ScrollView {...props} />
      */
     renderScrollComponent?: (props: ScrollViewProps) => React.ReactElement<ScrollViewProps>;
-    extraData?: any;
+    /**
+     * This will log a suggested estimatedItemSize.
+     * @required
+     * @default false
+     */
+    suggestEstimatedItemSize?: boolean;
+    /**
+     * Configuration for determining item viewability.
+     */
+    viewabilityConfig?: ViewabilityConfig;
+    /**
+     * Pairs of viewability configs and their callbacks for tracking visibility.
+     */
+    viewabilityConfigCallbackPairs?: ViewabilityConfigCallbackPairs | undefined;
+    /**
+     * If true, delays rendering until initial layout is complete.
+     * @default false
+     */
+    waitForInitialLayout?: boolean;
 };
+interface ColumnWrapperStyle {
+    rowGap?: number;
+    gap?: number;
+    columnGap?: number;
+}
 type AnchoredPosition = {
-    type: 'top' | 'bottom';
+    type: "top" | "bottom";
     relativeCoordinate: number;
     top: number;
 };
-type LegendListProps<ItemT> = LegendListPropsBase<ItemT, ComponentProps<typeof ScrollView>>;
+type LegendListProps<ItemT> = LegendListPropsBase<ItemT, Omit<ComponentProps<typeof ScrollView>, "scrollEventThrottle">>;
 interface InternalState {
     anchorElement?: {
         id: string;
@@ -79,16 +230,14 @@ interface InternalState {
     positions: Map<string, number>;
     columns: Map<string, number>;
     sizes: Map<string, number>;
-    sizesLaidOut: Map<string, number> | undefined;
+    sizesKnown: Map<string, number>;
     pendingAdjust: number;
-    waitingForMicrotask: any;
     isStartReached: boolean;
     isEndReached: boolean;
     isAtBottom: boolean;
     isAtTop: boolean;
     data: readonly any[];
-    idsInFirstRender: Set<string>;
-    hasScrolled: boolean;
+    hasScrolled?: boolean;
     scrollLength: number;
     startBuffered: number;
     startBufferedId?: string;
@@ -101,6 +250,7 @@ interface InternalState {
     scrollPrevTime: number;
     scrollVelocity: number;
     scrollAdjustHandler: ScrollAdjustHandler;
+    maintainingScrollAtEnd?: boolean;
     totalSize: number;
     totalSizeBelowAnchor: number;
     timeouts: Set<number>;
@@ -115,12 +265,24 @@ interface InternalState {
     }>;
     scrollTimer: Timer | undefined;
     startReachedBlockedByTimer: boolean;
+    endReachedBlockedByTimer: boolean;
     scrollForNextCalculateItemsInView: {
         top: number;
         bottom: number;
     } | undefined;
     enableScrollForNextCalculateItemsInView: boolean;
     minIndexSizeChanged: number | undefined;
+    numPendingInitialLayout: number;
+    queuedInitialLayout?: boolean | undefined;
+    queuedCalculateItemsInView: number | undefined;
+    lastBatchingAction: number;
+    ignoreScrollFromCalcTotal?: boolean;
+    scrollingToOffset?: number | undefined;
+    averageSizes: Record<string, {
+        num: number;
+        avg: number;
+    }>;
+    onScroll: ((event: NativeSyntheticEvent<NativeScrollEvent>) => void) | undefined;
 }
 interface ViewableRange<T> {
     startBuffered: number;
@@ -132,44 +294,105 @@ interface ViewableRange<T> {
 interface LegendListRenderItemProps<ItemT> {
     item: ItemT;
     index: number;
-    useViewability: (configId: string, callback: ViewabilityCallback) => void;
-    useViewabilityAmount: (callback: ViewabilityAmountCallback) => void;
-    useRecyclingEffect: (effect: (info: LegendListRecyclingState<ItemT>) => void | (() => void)) => void;
-    useRecyclingState: <T>(updateState: ((info: LegendListRecyclingState<ItemT>) => T) | T) => [T, React.Dispatch<T>];
+    extraData: any;
 }
+type ScrollState = {
+    contentLength: number;
+    end: number;
+    endBuffered: number;
+    isAtEnd: boolean;
+    isAtStart: boolean;
+    scroll: number;
+    scrollLength: number;
+    start: number;
+    startBuffered: number;
+};
 type LegendListRef = {
     /**
      * Displays the scroll indicators momentarily.
      */
     flashScrollIndicators(): void;
+    /**
+     * Returns the native ScrollView component reference.
+     */
     getNativeScrollRef(): React.ElementRef<typeof ScrollViewComponent>;
-    getScrollResponder(): ScrollResponderMixin;
+    /**
+     * Returns the scroll responder instance for handling scroll events.
+     */
     getScrollableNode(): any;
     /**
-     * A helper function that scrolls to the end of the scrollview;
-     * If this is a vertical ScrollView, it scrolls to the bottom.
-     * If this is a horizontal ScrollView scrolls to the right.
-     *
-     * The options object has an animated prop, that enables the scrolling animation or not.
-     * The animated prop defaults to true
+     * Returns the ScrollResponderMixin for advanced scroll handling.
+     */
+    getScrollResponder(): ScrollResponderMixin;
+    /**
+     * Returns the internal state of the scroll virtualization.
+     */
+    getState(): ScrollState;
+    /**
+     * Scrolls a specific index into view.
+     * @param params - Parameters for scrolling.
+     * @param params.animated - If true, animates the scroll. Default: true.
+     * @param params.index - The index to scroll to.
+     */
+    scrollIndexIntoView(params: {
+        animated?: boolean | undefined;
+        index: number;
+    }): void;
+    /**
+     * Scrolls a specific index 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.
+     */
+    scrollItemIntoView(params: {
+        animated?: boolean | undefined;
+        item: any;
+    }): void;
+    /**
+     * Scrolls to the end of the list.
+     * @param options - Options for scrolling.
+     * @param options.animated - If true, animates the scroll. Default: true.
      */
     scrollToEnd(options?: {
         animated?: boolean | undefined;
     }): void;
-    scrollToIndex: (params: {
+    /**
+     * Scrolls to a specific index in the list.
+     * @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.viewOffset - Offset from the target position.
+     * @param params.viewPosition - Position of the item in the viewport (0 to 1).
+     */
+    scrollToIndex(params: {
+        animated?: boolean | undefined;
         index: number;
-        animated?: boolean;
-        viewOffset?: number;
-        viewPosition?: number;
-    }) => void;
+        viewOffset?: number | undefined;
+        viewPosition?: number | undefined;
+    }): void;
+    /**
+     * Scrolls to a specific item in the list.
+     * @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.viewOffset - Offset from the target position.
+     * @param params.viewPosition - Position of the item in the viewport (0 to 1).
+     */
     scrollToItem(params: {
-        animated?: boolean;
+        animated?: boolean | undefined;
         item: any;
-        viewPosition?: number;
+        viewOffset?: number | undefined;
+        viewPosition?: number | undefined;
     }): void;
+    /**
+     * Scrolls to a specific offset in pixels.
+     * @param params - Parameters for scrolling.
+     * @param params.offset - The pixel offset to scroll to.
+     * @param params.animated - If true, animates the scroll. Default: true.
+     */
     scrollToOffset(params: {
         offset: number;
-        animated?: boolean;
+        animated?: boolean | undefined;
     }): void;
 };
 interface ViewToken<ItemT = any> {
@@ -177,13 +400,13 @@ interface ViewToken<ItemT = any> {
     key: string;
     index: number;
     isViewable: boolean;
+    containerId: number;
 }
 interface ViewAmountToken<ItemT = any> extends ViewToken<ItemT> {
     sizeVisible: number;
     size: number;
     percentVisible: number;
     percentOfScroller: number;
-    position: number;
     scrollSize: number;
 }
 interface ViewabilityConfigCallbackPair {
@@ -232,14 +455,69 @@ interface LegendListRecyclingState<T> {
     index: number;
     prevIndex: number | undefined;
 }
+type TypedForwardRef = <T, P = {}>(render: (props: P, ref: React.Ref<T>) => React.ReactNode) => (props: P & React.RefAttributes<T>) => React.ReactNode;
+declare const typedForwardRef: TypedForwardRef;
+type TypedMemo = <T extends React.ComponentType<any>>(Component: T, propsAreEqual?: (prevProps: Readonly<ComponentProps<T>>, nextProps: Readonly<ComponentProps<T>>) => boolean) => T & {
+    displayName?: string;
+};
+declare const typedMemo: TypedMemo;
 
-declare const LegendList: <T>(props: LegendListProps<T> & {
-    ref?: ForwardedRef<LegendListRef>;
-}) => ReactElement;
+declare const LegendList: <T>(props: Omit<Omit<react_native.ScrollViewProps, "scrollEventThrottle">, "contentOffset" | "contentInset" | "maintainVisibleContentPosition" | "stickyHeaderIndices"> & {
+    alignItemsAtEnd?: boolean;
+    columnWrapperStyle?: ColumnWrapperStyle;
+    data: readonly T[];
+    drawDistance?: number;
+    estimatedItemSize?: number;
+    extraData?: any;
+    getEstimatedItemSize?: ((index: number, item: T) => number) | undefined;
+    initialContainerPoolRatio?: number | undefined;
+    initialScrollOffset?: number;
+    initialScrollIndex?: number;
+    ItemSeparatorComponent?: React$1.ComponentType<{
+        leadingItem: T;
+    }> | undefined;
+    keyExtractor?: ((item: T, index: number) => string) | undefined;
+    ListEmptyComponent?: React$1.ComponentType<any> | React$1.ReactElement | null | undefined;
+    ListFooterComponent?: React$1.ComponentType<any> | React$1.ReactElement | null | undefined;
+    ListFooterComponentStyle?: react_native.StyleProp<ViewStyle> | undefined;
+    ListHeaderComponent?: React$1.ComponentType<any> | React$1.ReactElement | null | undefined;
+    ListHeaderComponentStyle?: react_native.StyleProp<ViewStyle> | undefined;
+    maintainScrollAtEnd?: boolean;
+    maintainScrollAtEndThreshold?: number;
+    maintainVisibleContentPosition?: boolean;
+    numColumns?: number;
+    onEndReached?: ((info: {
+        distanceFromEnd: number;
+    }) => void) | null | undefined;
+    onEndReachedThreshold?: number | null | undefined;
+    onItemSizeChanged?: ((info: {
+        size: number;
+        previous: number;
+        index: number;
+        itemKey: string;
+        itemData: T;
+    }) => void) | undefined;
+    onRefresh?: () => void;
+    onStartReached?: ((info: {
+        distanceFromStart: number;
+    }) => void) | null | undefined;
+    onStartReachedThreshold?: number | null | undefined;
+    onViewableItemsChanged?: OnViewableItemsChanged | undefined;
+    progressViewOffset?: number;
+    recycleItems?: boolean;
+    refScrollView?: React$1.Ref<ScrollView>;
+    refreshing?: boolean;
+    renderItem?: ((props: LegendListRenderItemProps<T>) => React$1.ReactNode) | undefined;
+    renderScrollComponent?: (props: react_native.ScrollViewProps) => React$1.ReactElement<react_native.ScrollViewProps>;
+    suggestEstimatedItemSize?: boolean;
+    viewabilityConfig?: ViewabilityConfig;
+    viewabilityConfigCallbackPairs?: ViewabilityConfigCallbackPairs | undefined;
+    waitForInitialLayout?: boolean;
+} & React$1.RefAttributes<LegendListRef>) => React$1.ReactNode;
 
-declare function useViewability(configId: string, callback: ViewabilityCallback): void;
+declare function useViewability(callback: ViewabilityCallback, configId?: string): void;
 declare function useViewabilityAmount(callback: ViewabilityAmountCallback): void;
 declare function useRecyclingEffect(effect: (info: LegendListRecyclingState<unknown>) => void | (() => void)): void;
-declare function useRecyclingState(valueOrFun: ((info: LegendListRecyclingState<unknown>) => any) | any): [any, react.Dispatch<any>];
+declare function useRecyclingState<ItemT>(valueOrFun: ((info: LegendListRecyclingState<ItemT>) => ItemT) | ItemT): readonly [ItemT | null, Dispatch<SetStateAction<ItemT>>];
 
-export { type AnchoredPosition, type InternalState, LegendList, type LegendListProps, type LegendListPropsBase, type LegendListRecyclingState, type LegendListRef, type LegendListRenderItemProps, type OnViewableItemsChanged, type ViewAmountToken, type ViewToken, type ViewabilityAmountCallback, type ViewabilityCallback, type ViewabilityConfig, type ViewabilityConfigCallbackPair, type ViewabilityConfigCallbackPairs, type ViewableRange, useRecyclingEffect, useRecyclingState, useViewability, useViewabilityAmount };
+export { type AnchoredPosition, type ColumnWrapperStyle, type InternalState, LegendList, type LegendListProps, type LegendListPropsBase, type LegendListRecyclingState, type LegendListRef, type LegendListRenderItemProps, type OnViewableItemsChanged, type ScrollState, type TypedForwardRef, type TypedMemo, type ViewAmountToken, type ViewToken, type ViewabilityAmountCallback, type ViewabilityCallback, type ViewabilityConfig, type ViewabilityConfigCallbackPair, type ViewabilityConfigCallbackPairs, type ViewableRange, typedForwardRef, typedMemo, useRecyclingEffect, useRecyclingState, useViewability, useViewabilityAmount };