@legendapp/list 2.1.0-beta.1 → 2.1.0-beta.10

package/CHANGELOG.md

@@ -1,3 +1,6 @@
+## 2.0.14
+- Feat: Add dataVersion prop to trigger re-render when mutating the data array in place
+
 ## 2.0.13
 - Feat: Allow returning undefined in getFixedItemSize to fall back to estimated size
 - Fix: scrollToIndex viewOffset was being subtracted twice, causing incorrect scroll positioning

package/index.d.mts

@@ -1,11 +1,11 @@
 import * as React$1 from 'react';
-import { ComponentProps, ReactNode, Dispatch, SetStateAction } from 'react';
+import { ComponentProps, Key, ReactNode, Dispatch, SetStateAction } from 'react';
 import { View, ScrollView, Animated, LayoutRectangle, ScrollViewComponent, ScrollResponderMixin, StyleProp, ViewStyle, NativeSyntheticEvent, NativeScrollEvent, ScrollViewProps } from 'react-native';
 import Animated$1 from 'react-native-reanimated';
 
 type AnimatedValue = number;
 
-type ListenerType = "numContainers" | "numContainersPooled" | `containerItemKey${number}` | `containerItemData${number}` | `containerPosition${number}` | `containerColumn${number}` | `containerSticky${number}` | `containerStickyOffset${number}` | "containersDidLayout" | "extraData" | "numColumns" | "lastItemKeys" | "totalSize" | "alignItemsPaddingTop" | "lastPositionUpdate" | "stylePaddingTop" | "scrollAdjust" | "scrollAdjustUserOffset" | "headerSize" | "footerSize" | "maintainVisibleContentPosition" | "debugRawScroll" | "debugComputedScroll" | "otherAxisSize" | "snapToOffsets" | "scrollSize";
+type ListenerType = "numContainers" | "numContainersPooled" | `containerItemKey${number}` | `containerItemData${number}` | `containerPosition${number}` | `containerColumn${number}` | `containerSticky${number}` | `containerStickyOffset${number}` | "containersDidLayout" | "extraData" | "numColumns" | "lastItemKeys" | "totalSize" | "alignItemsPaddingTop" | "lastPositionUpdate" | "stylePaddingTop" | "scrollAdjust" | "scrollAdjustUserOffset" | "scrollAdjustPending" | "scrollingTo" | "headerSize" | "footerSize" | "maintainVisibleContentPosition" | "debugRawScroll" | "debugComputedScroll" | "otherAxisSize" | "snapToOffsets" | "scrollSize" | "activeStickyIndex";
 interface StateContext {
     internalState: InternalState | undefined;
     listeners: Map<ListenerType, Set<(value: any) => void>>;
@@ -28,6 +28,7 @@ interface StateContext {
 
 declare class ScrollAdjustHandler {
     private appliedAdjust;
+    private pendingAdjust;
     private context;
     private mounted;
     constructor(ctx: StateContext);
@@ -36,7 +37,7 @@ declare class ScrollAdjustHandler {
     getAdjust(): number;
 }
 
-type BaseScrollViewProps<TScrollView> = Omit<TScrollView, "contentOffset" | "contentInset" | "maintainVisibleContentPosition" | "stickyHeaderIndices" | "removeClippedSubviews" | "children" | "onScroll">;
+type BaseScrollViewProps<TScrollView> = Omit<TScrollView, "contentOffset" | "maintainVisibleContentPosition" | "stickyHeaderIndices" | "removeClippedSubviews" | "children" | "onScroll">;
 interface DataModeProps<ItemT, TItemType extends string | undefined> {
     /**
      * Array of items to render in the list.
@@ -101,6 +102,11 @@ 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
@@ -124,6 +130,12 @@ interface LegendListSpecificProps<ItemT, TItemType extends string | undefined> {
         index: number;
         viewOffset?: number | undefined;
     };
+    /**
+     * When true, the list initializes scrolled to the last item.
+     * Overrides `initialScrollIndex` and `initialScrollOffset` when data is available.
+     * @default false
+     */
+    initialScrollAtEnd?: boolean;
     /**
      * Component to render between items, receiving the leading item as prop.
      */
@@ -213,7 +225,7 @@ interface LegendListSpecificProps<ItemT, TItemType extends string | undefined> {
     onStartReachedThreshold?: number | null | undefined;
     /**
      * Called when the sticky header changes.
-    */
+     */
     onStickyHeaderChange?: (info: {
         index: number;
         item: any;
@@ -243,6 +255,7 @@ interface LegendListSpecificProps<ItemT, TItemType extends string | undefined> {
     refreshing?: boolean;
     /**
      * Render custom ScrollView component.
+     * Note: When using `stickyHeaderIndices`, you must provide an Animated ScrollView component.
      * @default (props) => <ScrollView {...props} />
      */
     renderScrollComponent?: (props: ScrollViewProps) => React.ReactElement<ScrollViewProps>;
@@ -298,6 +311,15 @@ interface ThresholdSnapshot {
     dataLength?: number;
     atThreshold: boolean;
 }
+interface ScrollTarget {
+    offset: number;
+    index?: number;
+    viewOffset?: number;
+    viewPosition?: number;
+    animated?: boolean;
+    isInitialScroll?: boolean;
+    precomputedWithViewOffset?: boolean;
+}
 interface InternalState {
     positions: Map<string, number>;
     columns: Map<string, number>;
@@ -324,6 +346,11 @@ interface InternalState {
     scrollPrev: number;
     scrollPrevTime: number;
     scrollAdjustHandler: ScrollAdjustHandler;
+    triggerCalculateItemsInView?: (params?: {
+        doMVCP?: boolean;
+        dataChanged?: boolean;
+        forceFullItemPositions?: boolean;
+    }) => void;
     maintainingScrollAtEnd?: boolean;
     totalSize: number;
     otherAxisSize?: number;
@@ -349,20 +376,17 @@ interface InternalState {
     queuedInitialLayout?: boolean | undefined;
     queuedCalculateItemsInView: number | undefined;
     dataChangeNeedsScrollUpdate: boolean;
+    previousData?: readonly unknown[];
+    didColumnsChange?: boolean;
+    didDataChange?: boolean;
+    isFirst?: boolean;
     lastBatchingAction: number;
     ignoreScrollFromMVCP?: {
         lt?: number;
         gt?: number;
     };
+    ignoreScrollFromMVCPIgnored?: boolean;
     ignoreScrollFromMVCPTimeout?: any;
-    scrollingTo?: {
-        offset: number;
-        index?: number;
-        viewOffset?: number;
-        viewPosition?: number;
-        animated?: boolean;
-        isInitialScroll?: boolean;
-    } | undefined;
     needsOtherAxisSize?: boolean;
     averageSizes: Record<string, {
         num: number;
@@ -370,7 +394,7 @@ interface InternalState {
     }>;
     refScroller: React.RefObject<ScrollView>;
     loadStartTime: number;
-    initialScroll: ScrollIndexWithOffset | undefined;
+    initialScroll: ScrollIndexWithOffsetAndContentOffset | undefined;
     lastLayout: LayoutRectangle | undefined;
     timeoutSetPaddingTop?: any;
     activeStickyIndex: number | undefined;
@@ -380,6 +404,7 @@ interface InternalState {
     props: {
         alignItemsAtEnd: boolean;
         data: readonly any[];
+        dataVersion: Key | undefined;
         estimatedItemSize: number | undefined;
         getEstimatedItemSize: LegendListProps["getEstimatedItemSize"];
         getFixedItemSize: LegendListProps["getFixedItemSize"];
@@ -401,7 +426,6 @@ interface InternalState {
         suggestEstimatedItemSize: boolean;
         stylePaddingBottom: number | undefined;
         renderItem: LegendListProps["renderItem"];
-        initialScroll: ScrollIndexWithOffset | undefined;
         scrollBuffer: number;
         numColumns: number;
         initialContainerPoolRatio: number;
@@ -431,6 +455,7 @@ type ScrollState = {
     activeStickyIndex: number | undefined;
     contentLength: number;
     data: readonly any[];
+    elementAtIndex: (index: number) => View | null | undefined;
     end: number;
     endBuffered: number;
     isAtEnd: boolean;
@@ -618,6 +643,9 @@ interface ScrollIndexWithOffset {
 interface ScrollIndexWithOffsetPosition extends ScrollIndexWithOffset {
     viewPosition: number;
 }
+interface ScrollIndexWithOffsetAndContentOffset extends ScrollIndexWithOffset {
+    contentOffset?: number;
+}
 type GetRenderedItemResult<ItemT> = {
     index: number;
     item: ItemT;
@@ -640,4 +668,4 @@ declare function useListScrollSize(): {
 };
 declare function useSyncLayout(): () => void;
 
-export { type ColumnWrapperStyle, type GetRenderedItem, type GetRenderedItemResult, type InternalState, LegendList, type LegendListProps, type LegendListPropsBase, type LegendListRecyclingState, type LegendListRef, type LegendListRenderItemProps, type MaintainScrollAtEndOptions, type OnViewableItemsChanged, type ScrollIndexWithOffset, type ScrollIndexWithOffsetPosition, type ScrollState, type ThresholdSnapshot, type TypedForwardRef, type TypedMemo, type ViewAmountToken, type ViewToken, type ViewabilityAmountCallback, type ViewabilityCallback, type ViewabilityConfig, type ViewabilityConfigCallbackPair, type ViewabilityConfigCallbackPairs, type ViewableRange, typedForwardRef, typedMemo, useIsLastItem, useListScrollSize, useRecyclingEffect, useRecyclingState, useSyncLayout, useViewability, useViewabilityAmount };
+export { type ColumnWrapperStyle, type GetRenderedItem, type GetRenderedItemResult, type InternalState, LegendList, type LegendListProps, type LegendListPropsBase, type LegendListRecyclingState, type LegendListRef, type LegendListRenderItemProps, type MaintainScrollAtEndOptions, type OnViewableItemsChanged, type ScrollIndexWithOffset, type ScrollIndexWithOffsetAndContentOffset, type ScrollIndexWithOffsetPosition, type ScrollState, type ScrollTarget, type ThresholdSnapshot, type TypedForwardRef, type TypedMemo, type ViewAmountToken, type ViewToken, type ViewabilityAmountCallback, type ViewabilityCallback, type ViewabilityConfig, type ViewabilityConfigCallbackPair, type ViewabilityConfigCallbackPairs, type ViewableRange, typedForwardRef, typedMemo, useIsLastItem, useListScrollSize, useRecyclingEffect, useRecyclingState, useSyncLayout, useViewability, useViewabilityAmount };

package/index.d.ts

@@ -1,11 +1,11 @@
 import * as React$1 from 'react';
-import { ComponentProps, ReactNode, Dispatch, SetStateAction } from 'react';
+import { ComponentProps, Key, ReactNode, Dispatch, SetStateAction } from 'react';
 import { View, ScrollView, Animated, LayoutRectangle, ScrollViewComponent, ScrollResponderMixin, StyleProp, ViewStyle, NativeSyntheticEvent, NativeScrollEvent, ScrollViewProps } from 'react-native';
 import Animated$1 from 'react-native-reanimated';
 
 type AnimatedValue = number;
 
-type ListenerType = "numContainers" | "numContainersPooled" | `containerItemKey${number}` | `containerItemData${number}` | `containerPosition${number}` | `containerColumn${number}` | `containerSticky${number}` | `containerStickyOffset${number}` | "containersDidLayout" | "extraData" | "numColumns" | "lastItemKeys" | "totalSize" | "alignItemsPaddingTop" | "lastPositionUpdate" | "stylePaddingTop" | "scrollAdjust" | "scrollAdjustUserOffset" | "headerSize" | "footerSize" | "maintainVisibleContentPosition" | "debugRawScroll" | "debugComputedScroll" | "otherAxisSize" | "snapToOffsets" | "scrollSize";
+type ListenerType = "numContainers" | "numContainersPooled" | `containerItemKey${number}` | `containerItemData${number}` | `containerPosition${number}` | `containerColumn${number}` | `containerSticky${number}` | `containerStickyOffset${number}` | "containersDidLayout" | "extraData" | "numColumns" | "lastItemKeys" | "totalSize" | "alignItemsPaddingTop" | "lastPositionUpdate" | "stylePaddingTop" | "scrollAdjust" | "scrollAdjustUserOffset" | "scrollAdjustPending" | "scrollingTo" | "headerSize" | "footerSize" | "maintainVisibleContentPosition" | "debugRawScroll" | "debugComputedScroll" | "otherAxisSize" | "snapToOffsets" | "scrollSize" | "activeStickyIndex";
 interface StateContext {
     internalState: InternalState | undefined;
     listeners: Map<ListenerType, Set<(value: any) => void>>;
@@ -28,6 +28,7 @@ interface StateContext {
 
 declare class ScrollAdjustHandler {
     private appliedAdjust;
+    private pendingAdjust;
     private context;
     private mounted;
     constructor(ctx: StateContext);
@@ -36,7 +37,7 @@ declare class ScrollAdjustHandler {
     getAdjust(): number;
 }
 
-type BaseScrollViewProps<TScrollView> = Omit<TScrollView, "contentOffset" | "contentInset" | "maintainVisibleContentPosition" | "stickyHeaderIndices" | "removeClippedSubviews" | "children" | "onScroll">;
+type BaseScrollViewProps<TScrollView> = Omit<TScrollView, "contentOffset" | "maintainVisibleContentPosition" | "stickyHeaderIndices" | "removeClippedSubviews" | "children" | "onScroll">;
 interface DataModeProps<ItemT, TItemType extends string | undefined> {
     /**
      * Array of items to render in the list.
@@ -101,6 +102,11 @@ 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
@@ -124,6 +130,12 @@ interface LegendListSpecificProps<ItemT, TItemType extends string | undefined> {
         index: number;
         viewOffset?: number | undefined;
     };
+    /**
+     * When true, the list initializes scrolled to the last item.
+     * Overrides `initialScrollIndex` and `initialScrollOffset` when data is available.
+     * @default false
+     */
+    initialScrollAtEnd?: boolean;
     /**
      * Component to render between items, receiving the leading item as prop.
      */
@@ -213,7 +225,7 @@ interface LegendListSpecificProps<ItemT, TItemType extends string | undefined> {
     onStartReachedThreshold?: number | null | undefined;
     /**
      * Called when the sticky header changes.
-    */
+     */
     onStickyHeaderChange?: (info: {
         index: number;
         item: any;
@@ -243,6 +255,7 @@ interface LegendListSpecificProps<ItemT, TItemType extends string | undefined> {
     refreshing?: boolean;
     /**
      * Render custom ScrollView component.
+     * Note: When using `stickyHeaderIndices`, you must provide an Animated ScrollView component.
      * @default (props) => <ScrollView {...props} />
      */
     renderScrollComponent?: (props: ScrollViewProps) => React.ReactElement<ScrollViewProps>;
@@ -298,6 +311,15 @@ interface ThresholdSnapshot {
     dataLength?: number;
     atThreshold: boolean;
 }
+interface ScrollTarget {
+    offset: number;
+    index?: number;
+    viewOffset?: number;
+    viewPosition?: number;
+    animated?: boolean;
+    isInitialScroll?: boolean;
+    precomputedWithViewOffset?: boolean;
+}
 interface InternalState {
     positions: Map<string, number>;
     columns: Map<string, number>;
@@ -324,6 +346,11 @@ interface InternalState {
     scrollPrev: number;
     scrollPrevTime: number;
     scrollAdjustHandler: ScrollAdjustHandler;
+    triggerCalculateItemsInView?: (params?: {
+        doMVCP?: boolean;
+        dataChanged?: boolean;
+        forceFullItemPositions?: boolean;
+    }) => void;
     maintainingScrollAtEnd?: boolean;
     totalSize: number;
     otherAxisSize?: number;
@@ -349,20 +376,17 @@ interface InternalState {
     queuedInitialLayout?: boolean | undefined;
     queuedCalculateItemsInView: number | undefined;
     dataChangeNeedsScrollUpdate: boolean;
+    previousData?: readonly unknown[];
+    didColumnsChange?: boolean;
+    didDataChange?: boolean;
+    isFirst?: boolean;
     lastBatchingAction: number;
     ignoreScrollFromMVCP?: {
         lt?: number;
         gt?: number;
     };
+    ignoreScrollFromMVCPIgnored?: boolean;
     ignoreScrollFromMVCPTimeout?: any;
-    scrollingTo?: {
-        offset: number;
-        index?: number;
-        viewOffset?: number;
-        viewPosition?: number;
-        animated?: boolean;
-        isInitialScroll?: boolean;
-    } | undefined;
     needsOtherAxisSize?: boolean;
     averageSizes: Record<string, {
         num: number;
@@ -370,7 +394,7 @@ interface InternalState {
     }>;
     refScroller: React.RefObject<ScrollView>;
     loadStartTime: number;
-    initialScroll: ScrollIndexWithOffset | undefined;
+    initialScroll: ScrollIndexWithOffsetAndContentOffset | undefined;
     lastLayout: LayoutRectangle | undefined;
     timeoutSetPaddingTop?: any;
     activeStickyIndex: number | undefined;
@@ -380,6 +404,7 @@ interface InternalState {
     props: {
         alignItemsAtEnd: boolean;
         data: readonly any[];
+        dataVersion: Key | undefined;
         estimatedItemSize: number | undefined;
         getEstimatedItemSize: LegendListProps["getEstimatedItemSize"];
         getFixedItemSize: LegendListProps["getFixedItemSize"];
@@ -401,7 +426,6 @@ interface InternalState {
         suggestEstimatedItemSize: boolean;
         stylePaddingBottom: number | undefined;
         renderItem: LegendListProps["renderItem"];
-        initialScroll: ScrollIndexWithOffset | undefined;
         scrollBuffer: number;
         numColumns: number;
         initialContainerPoolRatio: number;
@@ -431,6 +455,7 @@ type ScrollState = {
     activeStickyIndex: number | undefined;
     contentLength: number;
     data: readonly any[];
+    elementAtIndex: (index: number) => View | null | undefined;
     end: number;
     endBuffered: number;
     isAtEnd: boolean;
@@ -618,6 +643,9 @@ interface ScrollIndexWithOffset {
 interface ScrollIndexWithOffsetPosition extends ScrollIndexWithOffset {
     viewPosition: number;
 }
+interface ScrollIndexWithOffsetAndContentOffset extends ScrollIndexWithOffset {
+    contentOffset?: number;
+}
 type GetRenderedItemResult<ItemT> = {
     index: number;
     item: ItemT;
@@ -640,4 +668,4 @@ declare function useListScrollSize(): {
 };
 declare function useSyncLayout(): () => void;
 
-export { type ColumnWrapperStyle, type GetRenderedItem, type GetRenderedItemResult, type InternalState, LegendList, type LegendListProps, type LegendListPropsBase, type LegendListRecyclingState, type LegendListRef, type LegendListRenderItemProps, type MaintainScrollAtEndOptions, type OnViewableItemsChanged, type ScrollIndexWithOffset, type ScrollIndexWithOffsetPosition, type ScrollState, type ThresholdSnapshot, type TypedForwardRef, type TypedMemo, type ViewAmountToken, type ViewToken, type ViewabilityAmountCallback, type ViewabilityCallback, type ViewabilityConfig, type ViewabilityConfigCallbackPair, type ViewabilityConfigCallbackPairs, type ViewableRange, typedForwardRef, typedMemo, useIsLastItem, useListScrollSize, useRecyclingEffect, useRecyclingState, useSyncLayout, useViewability, useViewabilityAmount };
+export { type ColumnWrapperStyle, type GetRenderedItem, type GetRenderedItemResult, type InternalState, LegendList, type LegendListProps, type LegendListPropsBase, type LegendListRecyclingState, type LegendListRef, type LegendListRenderItemProps, type MaintainScrollAtEndOptions, type OnViewableItemsChanged, type ScrollIndexWithOffset, type ScrollIndexWithOffsetAndContentOffset, type ScrollIndexWithOffsetPosition, type ScrollState, type ScrollTarget, type ThresholdSnapshot, type TypedForwardRef, type TypedMemo, type ViewAmountToken, type ViewToken, type ViewabilityAmountCallback, type ViewabilityCallback, type ViewabilityConfig, type ViewabilityConfigCallbackPair, type ViewabilityConfigCallbackPairs, type ViewableRange, typedForwardRef, typedMemo, useIsLastItem, useListScrollSize, useRecyclingEffect, useRecyclingState, useSyncLayout, useViewability, useViewabilityAmount };