@legendapp/list 1.0.0-beta.25 → 1.0.0-beta.27

package/index.d.mts

@@ -1,7 +1,7 @@
 import * as React$1 from 'react';
 import { ComponentProps, ReactNode } from 'react';
 import * as react_native from 'react-native';
-import { ScrollView, StyleProp, ViewStyle, ScrollViewProps, ScrollViewComponent, ScrollResponderMixin } from 'react-native';
+import { ScrollView, StyleProp, ViewStyle, ScrollViewProps, NativeSyntheticEvent, NativeScrollEvent, ScrollViewComponent, ScrollResponderMixin } from 'react-native';
 import Animated from 'react-native-reanimated';
 
 declare class ScrollAdjustHandler {
@@ -10,52 +10,132 @@ declare class ScrollAdjustHandler {
     private busy;
     private context;
     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"> & {
+    /**
+      * 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; sufficient for most cases. If
+     * you leave this blank, a warning should appear and you will get
+     * a suggested size.
+     * @required
+     * @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 pixels to trigger maintainScrollAtEnd.
+     * @default 100
+     */
     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;
-    columnWrapperStyle?: ColumnWrapperStyle;
-    refScrollView?: React.Ref<ScrollView>;
-    waitForInitialLayout?: boolean;
-    initialContainerPoolRatio?: number | undefined;
-    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<{
-        leadingItem: ItemT;
-    }>;
-    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;
@@ -63,15 +143,67 @@ 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;
-    refreshing?: boolean;
-    onRefresh?: () => void;
-    progressViewOffset?: number;
+    /**
+     * 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;
@@ -139,6 +271,7 @@ interface InternalState {
     queuedCalculateItemsInView: number | undefined;
     lastBatchingAction: number;
     ignoreScrollFromCalcTotal?: boolean;
+    onScroll: ((event: NativeSyntheticEvent<NativeScrollEvent>) => void) | undefined;
 }
 interface ViewableRange<T> {
     startBuffered: number;
@@ -150,6 +283,7 @@ interface ViewableRange<T> {
 interface LegendListRenderItemProps<ItemT> {
     item: ItemT;
     index: number;
+    extraData: any;
     useViewability: (configId: string, callback: ViewabilityCallback) => void;
     useViewabilityAmount: (callback: ViewabilityAmountCallback) => void;
     useRecyclingEffect: (effect: (info: LegendListRecyclingState<ItemT>) => void | (() => void)) => void;
@@ -157,35 +291,63 @@ interface LegendListRenderItemProps<ItemT> {
 }
 type LegendListRef = {
     /**
-     * Displays the scroll indicators momentarily.
-     */
+         * 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;
+    /**
+     * 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;
+    /**
+     * 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;
         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 | undefined;
         item: any;
         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 | undefined;
@@ -258,44 +420,34 @@ type TypedMemo = <T extends React.ComponentType<any>>(Component: T, propsAreEqua
 };
 declare const typedMemo: TypedMemo;
 
-declare const LegendList: <T>(props: Omit<react_native.ScrollViewProps, "contentOffset" | "contentInset" | "maintainVisibleContentPosition" | "stickyHeaderIndices"> & {
+declare const LegendList: <T>(props: Omit<react_native.ScrollViewProps, "maintainVisibleContentPosition" | "stickyHeaderIndices" | "contentInset" | "contentOffset"> & {
+    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;
-    drawDistance?: number;
-    recycleItems?: boolean;
-    onEndReachedThreshold?: number | null | undefined;
-    onStartReachedThreshold?: number | null | undefined;
+    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<react_native.ViewStyle> | undefined;
+    ListHeaderComponent?: React$1.ComponentType<any> | React$1.ReactElement | null | undefined;
+    ListHeaderComponentStyle?: react_native.StyleProp<react_native.ViewStyle> | undefined;
     maintainScrollAtEnd?: boolean;
     maintainScrollAtEndThreshold?: number;
-    alignItemsAtEnd?: boolean;
     maintainVisibleContentPosition?: boolean;
     numColumns?: number;
-    columnWrapperStyle?: ColumnWrapperStyle;
-    refScrollView?: React$1.Ref<ScrollView>;
-    waitForInitialLayout?: boolean;
-    initialContainerPoolRatio?: number | undefined;
-    estimatedItemSize?: number;
-    getEstimatedItemSize?: ((index: number, item: T) => number) | undefined;
-    onStartReached?: ((info: {
-        distanceFromStart: number;
-    }) => void) | null | undefined;
     onEndReached?: ((info: {
         distanceFromEnd: number;
     }) => void) | null | undefined;
-    keyExtractor?: ((item: T, index: number) => string) | undefined;
-    renderItem?: ((props: LegendListRenderItemProps<T>) => React$1.ReactNode) | undefined;
-    ListHeaderComponent?: React$1.ComponentType<any> | React$1.ReactElement | null | undefined;
-    ListHeaderComponentStyle?: react_native.StyleProp<react_native.ViewStyle> | undefined;
-    ListFooterComponent?: React$1.ComponentType<any> | React$1.ReactElement | null | undefined;
-    ListFooterComponentStyle?: react_native.StyleProp<react_native.ViewStyle> | undefined;
-    ListEmptyComponent?: React$1.ComponentType<any> | React$1.ReactElement | null | undefined;
-    ItemSeparatorComponent?: React$1.ComponentType<{
-        leadingItem: T;
-    }> | undefined;
-    viewabilityConfigCallbackPairs?: ViewabilityConfigCallbackPairs | undefined;
-    viewabilityConfig?: ViewabilityConfig;
-    onViewableItemsChanged?: OnViewableItemsChanged | undefined;
+    onEndReachedThreshold?: number | null | undefined;
     onItemSizeChanged?: ((info: {
         size: number;
         previous: number;
@@ -303,11 +455,21 @@ declare const LegendList: <T>(props: Omit<react_native.ScrollViewProps, "content
         itemKey: string;
         itemData: T;
     }) => void) | undefined;
-    renderScrollComponent?: (props: react_native.ScrollViewProps) => React$1.ReactElement<react_native.ScrollViewProps>;
-    extraData?: any;
-    refreshing?: boolean;
     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>;
+    viewabilityConfig?: ViewabilityConfig;
+    viewabilityConfigCallbackPairs?: ViewabilityConfigCallbackPairs | undefined;
+    waitForInitialLayout?: boolean;
 } & React$1.RefAttributes<LegendListRef>) => React$1.ReactNode;
 
 declare function useViewability(configId: string, callback: ViewabilityCallback): void;