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

package/section-list.d.ts

@@ -59,16 +59,28 @@ type BuildSectionListDataResult<ItemT, SectionT> = {
     stickyHeaderIndices: number[];
 };
 
-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;
@@ -170,6 +182,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
@@ -193,33 +210,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
@@ -230,17 +249,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.
      */
@@ -286,10 +302,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
@@ -316,6 +331,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.
      */
@@ -324,6 +345,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.
@@ -347,6 +371,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
@@ -372,6 +402,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
@@ -386,15 +420,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.
@@ -411,9 +436,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> {
@@ -421,10 +448,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 {
     /**
@@ -487,8 +516,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;
@@ -627,10 +659,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
@@ -661,7 +698,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>;
@@ -683,8 +720,12 @@ type SectionListViewToken<ItemT, SectionT> = {
     section: SectionListData<ItemT, SectionT>;
 };
 type SectionListOnViewableItemsChanged<ItemT, SectionT> = ((info: {
+    end: number;
+    endBuffered: number;
     viewableItems: Array<SectionListViewToken<ItemT, SectionT>>;
     changed: Array<SectionListViewToken<ItemT, SectionT>>;
+    start: number;
+    startBuffered: number;
 }) => void) | null;
 type SectionListLegendProps<ItemT, SectionT> = Omit<LegendListProps<FlatSectionListItem<ItemT, SectionT>>, "data" | "children" | "renderItem" | "keyExtractor" | "ItemSeparatorComponent" | "getItemType" | "getFixedItemSize" | "stickyHeaderIndices" | "numColumns" | "columnWrapperStyle" | "onViewableItemsChanged">;
 type SectionListProps<ItemT, SectionT extends SectionBase<ItemT> = SectionBase<ItemT>> = SectionListLegendProps<ItemT, SectionT> & {

package/section-list.js

@@ -123,6 +123,7 @@ function buildSectionListData({
 }
 
 // src/section-list/SectionList.tsx
+var { typedForwardRef, typedMemo } = reactNative.internal;
 var defaultSeparators = {
   highlight: () => {
   },
@@ -139,8 +140,8 @@ function resolveSeparatorComponent(component, props) {
   const Component = component;
   return /* @__PURE__ */ React__namespace.createElement(Component, { ...props });
 }
-var SectionList = reactNative.typedMemo(
-  reactNative.typedForwardRef(function SectionListInner(props, ref) {
+var SectionList = typedMemo(
+  typedForwardRef(function SectionListInner(props, ref) {
     const {
       sections,
       renderItem: renderItemProp,
@@ -183,7 +184,11 @@ var SectionList = reactNative.typedMemo(
       if (!onViewableItemsChanged) return void 0;
       return ({
         viewableItems,
-        changed
+        changed,
+        start,
+        end,
+        startBuffered,
+        endBuffered
       }) => {
         const mapToken = (token) => {
           if (token.item.kind !== "item") return null;
@@ -197,7 +202,14 @@ var SectionList = reactNative.typedMemo(
         };
         const mappedViewable = viewableItems.map(mapToken).filter(Boolean);
         const mappedChanged = changed.map(mapToken).filter(Boolean);
-        onViewableItemsChanged({ changed: mappedChanged, viewableItems: mappedViewable });
+        onViewableItemsChanged({
+          changed: mappedChanged,
+          end,
+          endBuffered,
+          start,
+          startBuffered,
+          viewableItems: mappedViewable
+        });
       };
     }, [onViewableItemsChanged]);
     const renderItem = React__namespace.useCallback(

package/section-list.mjs

@@ -1,6 +1,6 @@
 import * as React from 'react';
 import { Platform } from 'react-native';
-import { typedMemo, typedForwardRef, LegendList } from '@legendapp/list/react-native';
+import { internal, LegendList } from '@legendapp/list/react-native';
 
 // src/section-list/SectionList.tsx
 
@@ -101,6 +101,7 @@ function buildSectionListData({
 }
 
 // src/section-list/SectionList.tsx
+var { typedForwardRef, typedMemo } = internal;
 var defaultSeparators = {
   highlight: () => {
   },
@@ -161,7 +162,11 @@ var SectionList = typedMemo(
       if (!onViewableItemsChanged) return void 0;
       return ({
         viewableItems,
-        changed
+        changed,
+        start,
+        end,
+        startBuffered,
+        endBuffered
       }) => {
         const mapToken = (token) => {
           if (token.item.kind !== "item") return null;
@@ -175,7 +180,14 @@ var SectionList = typedMemo(
         };
         const mappedViewable = viewableItems.map(mapToken).filter(Boolean);
         const mappedChanged = changed.map(mapToken).filter(Boolean);
-        onViewableItemsChanged({ changed: mappedChanged, viewableItems: mappedViewable });
+        onViewableItemsChanged({
+          changed: mappedChanged,
+          end,
+          endBuffered,
+          start,
+          startBuffered,
+          viewableItems: mappedViewable
+        });
       };
     }, [onViewableItemsChanged]);
     const renderItem = React.useCallback(