@legendapp/list 3.1.2 → 3.3.0

package/CHANGELOG.md

@@ -1,3 +1,17 @@
+## 3.3.0
+
+- Feat: Add `dataKey` so apps can tell the list when the current array represents a different dataset, such as switching conversations or feeds without remounting `LegendList`.
+- Feat: `experimental_adaptiveRender.onChange` now receives a reason (`initial`, `ready`, or `scroll`) so item components can tell why the render mode changed.
+- Fix: Large user scroll jumps render the visible rows first and fill the normal draw distance on the next frame, making long jumps less likely to land on a blank range.
+- Fix: `maintainScrollAtEnd` reruns a pending keep-at-end request after the current one settles, so a footer resize and a new message arriving together keep chat-style lists pinned to the end.
+- Fix: Replacing data after clearing the list, or changing `dataKey` for a non-empty replacement, resets layout readiness and uses the latest initial scroll target for the new dataset.
+
+## 3.2.0
+
+- Feat: Add `onFirstVisibleItemChanged` so apps can track the item at the top of the viewport without setting up full viewability callbacks.
+- Feat: Add `experimental_adaptiveRender.initialMode` for choosing whether adaptive rendering starts in `normal` or `light` mode before the list is ready.
+- Perf: On Fabric, replacement container measurements are batched into the same layout pass, so scroll anchoring and item positioning recalculate once instead of once per pending row.
+
 ## 3.1.2
 
 - Fix: On Android, end-aligned lists could double apply scroll clamping during MVCP and be slightly underscrolled

package/animated.d.ts

@@ -92,26 +92,32 @@ interface NativeSyntheticEvent<T> {
 type ViewStyle = Record<string, unknown>;
 type StyleProp<T> = T | T[] | null | undefined | false;
 type AdaptiveRender = "normal" | "light";
+type AdaptiveRenderChangeReason = "initial" | "ready" | "scroll";
 interface AdaptiveRenderConfig {
+    /**
+     * Mode to use before the list is ready to render.
+     * @default "normal"
+     */
+    initialMode?: AdaptiveRender;
     /**
      * Scroll velocity in pixels per millisecond above which items should switch to light mode.
-     * @default 4
+     * @default 3 native, 6 web
      */
     enterVelocity?: number;
     /**
      * Scroll velocity in pixels per millisecond below which items can return to normal mode.
-     * @default 1
+     * @default 1 native, 3 web
      */
     exitVelocity?: number;
     /**
      * Time to wait without velocity above exitVelocity before returning to normal mode.
-     * @default 1000
+     * @default 250
      */
     exitDelay?: number;
     /**
      * Called when the list-level adaptive render changes.
      */
-    onChange?: (mode: AdaptiveRender) => void;
+    onChange?: (mode: AdaptiveRender, reason: AdaptiveRenderChangeReason) => void;
 }
 type BaseScrollViewProps<TScrollView> = Omit<TScrollView, "contentOffset" | "maintainVisibleContentPosition" | "stickyHeaderIndices" | "removeClippedSubviews" | "children" | "onScroll">;
 interface DataModeProps<ItemT, TItemType extends string | undefined> {
@@ -153,6 +159,11 @@ interface LegendListSpecificProps<ItemT, TItemType extends string | undefined> {
      * Style applied to each column's wrapper view.
      */
     columnWrapperStyle?: ColumnWrapperStyle;
+    /**
+     * Identity token for the dataset represented by `data`.
+     * Change this when replacing the current dataset with a different logical dataset.
+     */
+    dataKey?: Key;
     /**
      * 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.
@@ -321,6 +332,15 @@ interface LegendListSpecificProps<ItemT, TItemType extends string | undefined> {
      * Called when list layout metrics change.
      */
     onMetricsChange?: (metrics: LegendListMetrics) => void;
+    /**
+     * Called when the first visible item changes. This is emitted from the core range calculation and is cheaper than
+     * viewability tracking when you only need to follow the item at the top of the viewport.
+     */
+    onFirstVisibleItemChanged?: (info: {
+        index: number;
+        item: ItemT;
+        key: string;
+    }) => void;
     /**
      * Configures the adaptive render signal. Items can use this to render a lighter version while scrolling quickly.
      */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@legendapp/list",
-  "version": "3.1.2",
+  "version": "3.3.0",
   "description": "Legend List is a drop-in replacement for FlatList with much better performance and supporting dynamically sized items.",
   "sideEffects": false,
   "private": false,

package/react-native.d.ts

@@ -92,26 +92,32 @@ interface NativeSyntheticEvent<T> {
 type ViewStyle = Record<string, unknown>;
 type StyleProp<T> = T | T[] | null | undefined | false;
 type AdaptiveRender = "normal" | "light";
+type AdaptiveRenderChangeReason = "initial" | "ready" | "scroll";
 interface AdaptiveRenderConfig {
+    /**
+     * Mode to use before the list is ready to render.
+     * @default "normal"
+     */
+    initialMode?: AdaptiveRender;
     /**
      * Scroll velocity in pixels per millisecond above which items should switch to light mode.
-     * @default 4
+     * @default 3 native, 6 web
      */
     enterVelocity?: number;
     /**
      * Scroll velocity in pixels per millisecond below which items can return to normal mode.
-     * @default 1
+     * @default 1 native, 3 web
      */
     exitVelocity?: number;
     /**
      * Time to wait without velocity above exitVelocity before returning to normal mode.
-     * @default 1000
+     * @default 250
      */
     exitDelay?: number;
     /**
      * Called when the list-level adaptive render changes.
      */
-    onChange?: (mode: AdaptiveRender) => void;
+    onChange?: (mode: AdaptiveRender, reason: AdaptiveRenderChangeReason) => void;
 }
 type BaseScrollViewProps<TScrollView> = Omit<TScrollView, "contentOffset" | "maintainVisibleContentPosition" | "stickyHeaderIndices" | "removeClippedSubviews" | "children" | "onScroll">;
 interface DataModeProps<ItemT, TItemType extends string | undefined> {
@@ -153,6 +159,11 @@ interface LegendListSpecificProps<ItemT, TItemType extends string | undefined> {
      * Style applied to each column's wrapper view.
      */
     columnWrapperStyle?: ColumnWrapperStyle;
+    /**
+     * Identity token for the dataset represented by `data`.
+     * Change this when replacing the current dataset with a different logical dataset.
+     */
+    dataKey?: Key;
     /**
      * 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.
@@ -321,6 +332,15 @@ interface LegendListSpecificProps<ItemT, TItemType extends string | undefined> {
      * Called when list layout metrics change.
      */
     onMetricsChange?: (metrics: LegendListMetrics) => void;
+    /**
+     * Called when the first visible item changes. This is emitted from the core range calculation and is cheaper than
+     * viewability tracking when you only need to follow the item at the top of the viewport.
+     */
+    onFirstVisibleItemChanged?: (info: {
+        index: number;
+        item: ItemT;
+        key: string;
+    }) => void;
     /**
      * Configures the adaptive render signal. Items can use this to render a lighter version while scrolling quickly.
      */
@@ -750,4 +770,4 @@ declare function useSyncLayout(): () => void;
 
 declare const LegendList: LegendListComponent;
 
-export { type AdaptiveRender, type AdaptiveRenderConfig, type AlwaysRenderConfig, type ColumnWrapperStyle, type Insets, type LayoutRectangle, LegendList, type LegendListAverageItemSize, type LegendListComponent, type LegendListMetrics, type LegendListProps, type LegendListRecyclingState, type LegendListRef, type LegendListRenderItemProps, type LegendListState, type MaintainScrollAtEndOnOptions, type MaintainScrollAtEndOptions, type MaintainVisibleContentPositionConfig, type NativeScrollEvent, type NativeSyntheticEvent, type OnViewableItemsChanged, type OnViewableItemsChangedInfo, type ScrollIndexWithOffset, type ScrollIndexWithOffsetAndContentOffset, type ScrollIndexWithOffsetPosition, type StickyHeaderConfig, type StyleProp, type ViewAmountToken, type ViewStyle, type ViewToken, type ViewabilityAmountCallback, type ViewabilityCallback, type ViewabilityConfig, type ViewabilityConfigCallbackPair, type ViewabilityConfigCallbackPairs, useAdaptiveRender, useAdaptiveRenderChange, useIsLastItem, useListScrollSize, useRecyclingEffect, useRecyclingState, useSyncLayout, useViewability, useViewabilityAmount };
+export { type AdaptiveRender, type AdaptiveRenderChangeReason, type AdaptiveRenderConfig, type AlwaysRenderConfig, type ColumnWrapperStyle, type Insets, type LayoutRectangle, LegendList, type LegendListAverageItemSize, type LegendListComponent, type LegendListMetrics, type LegendListProps, type LegendListRecyclingState, type LegendListRef, type LegendListRenderItemProps, type LegendListState, type MaintainScrollAtEndOnOptions, type MaintainScrollAtEndOptions, type MaintainVisibleContentPositionConfig, type NativeScrollEvent, type NativeSyntheticEvent, type OnViewableItemsChanged, type OnViewableItemsChangedInfo, type ScrollIndexWithOffset, type ScrollIndexWithOffsetAndContentOffset, type ScrollIndexWithOffsetPosition, type StickyHeaderConfig, type StyleProp, type ViewAmountToken, type ViewStyle, type ViewToken, type ViewabilityAmountCallback, type ViewabilityCallback, type ViewabilityConfig, type ViewabilityConfigCallbackPair, type ViewabilityConfigCallbackPairs, useAdaptiveRender, useAdaptiveRenderChange, useIsLastItem, useListScrollSize, useRecyclingEffect, useRecyclingState, useSyncLayout, useViewability, useViewabilityAmount };