@legendapp/list 3.0.6 → 3.1.0

package/CHANGELOG.md

@@ -1,3 +1,17 @@
+## 3.1.0
+
+- Feat: Add `experimental_adaptiveRender` with `useAdaptiveRender` and `useAdaptiveRenderChange`, so item components can render a lighter version while the list is moving quickly and return to normal after scrolling slows.
+- Feat: Add `setItemSize` to the list ref for updating a known item's measured size directly when its content changes outside normal layout measurement.
+- Fix: Web maintainVisibleContentPosition keeps the intended anchor when headers change, browser scroll anchoring runs, or an animated `scrollToEnd` is already in progress. #468 #463
+- Fix: `initialScrollIndex` and `initialScrollAtEnd` use the latest initial scroll props when data starts empty and loads later, so lists do not scroll to an old startup target.
+- Fix: Changing `gap` now refreshes cached item measurements, and fixed-size rows include the gap in their positions.
+- Fix: SectionList sticky headers update after the section data changes. #445
+- Fix: Horizontal lists with end alignment now place items at the end instead of ignoring the alignment. #472
+- Fix: Lists clear scheduled timers on unmount, preventing delayed adaptive-render or scroll work from running after the list is gone.
+- Perf: The first render starts with a smaller draw distance and expands shortly after, reducing offscreen work before the initial content appears.
+- Perf: `alignItemsAtEnd` spacer updates cause fewer ScrollView rerenders.
+- Types: Export `AdaptiveRender` and `AdaptiveRenderConfig` from the React Native and web type entrypoints.
+
 ## 3.0.6
 
 - Fix: KeyboardAwareLegendList now accounts for bottom insets when alignItemsAtEnd is used, so short chat-style lists stay pinned above the keyboard or safe area instead of being pushed too low or leaving extra scroll space.

package/animated.d.ts

@@ -8,8 +8,8 @@ interface MaintainVisibleContentPositionNormalized<ItemT = any> {
     shouldRestorePosition?: (item: ItemT, index: number, data: readonly ItemT[]) => boolean;
 }
 
-type ListenerType = "activeStickyIndex" | "alignItemsAtEndPadding" | "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 ListenerType = "activeStickyIndex" | "alignItemsAtEndPadding" | "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" | "adaptiveRender" | `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" | "adaptiveRender" | "lastItemKeys" | "lastPositionUpdate" | "numContainers" | "numContainersPooled" | "otherAxisSize" | "readyToRender" | "snapToOffsets" | "totalSize">;
 type ListenerTypeValueMap = {
     activeStickyIndex: number;
     alignItemsAtEndPadding: number;
@@ -43,6 +43,7 @@ type ListenerTypeValueMap = {
     snapToOffsets: number[];
     stylePaddingTop: number;
     totalSize: number;
+    adaptiveRender: "normal" | "light";
 } & {
     [K in ListenerType as K extends `containerItemKey${number}` ? K : never]: string;
 } & {
@@ -63,6 +64,12 @@ interface Insets {
     bottom: number;
     right: number;
 }
+interface LayoutRectangle {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
 interface NativeScrollEvent {
     contentOffset: {
         x: number;
@@ -84,6 +91,28 @@ interface NativeSyntheticEvent<T> {
 }
 type ViewStyle = Record<string, unknown>;
 type StyleProp<T> = T | T[] | null | undefined | false;
+type AdaptiveRender = "normal" | "light";
+interface AdaptiveRenderConfig {
+    /**
+     * Scroll velocity in pixels per millisecond above which items should switch to light mode.
+     * @default 4
+     */
+    enterVelocity?: number;
+    /**
+     * Scroll velocity in pixels per millisecond below which items can return to normal mode.
+     * @default 1
+     */
+    exitVelocity?: number;
+    /**
+     * Time to wait without velocity above exitVelocity before returning to normal mode.
+     * @default 1000
+     */
+    exitDelay?: number;
+    /**
+     * Called when the list-level adaptive render changes.
+     */
+    onChange?: (mode: AdaptiveRender) => void;
+}
 type BaseScrollViewProps<TScrollView> = Omit<TScrollView, "contentOffset" | "maintainVisibleContentPosition" | "stickyHeaderIndices" | "removeClippedSubviews" | "children" | "onScroll">;
 interface DataModeProps<ItemT, TItemType extends string | undefined> {
     /**
@@ -292,6 +321,10 @@ interface LegendListSpecificProps<ItemT, TItemType extends string | undefined> {
      * Called when list layout metrics change.
      */
     onMetricsChange?: (metrics: LegendListMetrics) => void;
+    /**
+     * Configures the adaptive render signal. Items can use this to render a lighter version while scrolling quickly.
+     */
+    experimental_adaptiveRender?: AdaptiveRenderConfig;
     /**
      * Function to call when the user pulls to refresh.
      */
@@ -490,6 +523,14 @@ type LegendListState = {
     startBuffered: number;
 };
 type LegendListRef$1 = {
+    /**
+     * Clears internal virtualization caches.
+     * @param options - Cache clearing options.
+     * @param options.mode - `sizes` clears measurement caches. `full` also clears key/position caches.
+     */
+    clearCaches(options?: {
+        mode?: "sizes" | "full";
+    }): void;
     /**
      * Displays the scroll indicators momentarily.
      */
@@ -510,6 +551,11 @@ type LegendListRef$1 = {
      * Returns the internal state of the scroll virtualization.
      */
     getState(): LegendListState;
+    /**
+     * Reports an externally measured content inset. Pass null/undefined to clear.
+     * Values are merged on top of props/animated/native insets.
+     */
+    reportContentInset(inset?: Partial<Insets> | null): void;
     /**
      * Scrolls a specific index into view.
      * @param params - Parameters for scrolling.
@@ -576,29 +622,22 @@ type LegendListRef$1 = {
         animated?: boolean | undefined;
     }): Promise<void>;
     /**
-     * Sets or adds to the offset of the visible content anchor.
-     * @param value - The offset to set or add.
-     * @param animated - If true, uses Animated to animate the change.
+     * Sets a measured item size and recalculates list positions as needed.
+     * @param itemKey - The key of the item whose size changed.
+     * @param size - The measured item size.
      */
-    setVisibleContentAnchorOffset(value: number | ((val: number) => number)): void;
+    setItemSize(itemKey: string, size: Pick<LayoutRectangle, "height" | "width">): void;
     /**
      * Sets whether scroll processing is enabled.
      * @param enabled - If true, scroll processing is enabled.
      */
     setScrollProcessingEnabled(enabled: boolean): void;
     /**
-     * Clears internal virtualization caches.
-     * @param options - Cache clearing options.
-     * @param options.mode - `sizes` clears measurement caches. `full` also clears key/position caches.
-     */
-    clearCaches(options?: {
-        mode?: "sizes" | "full";
-    }): void;
-    /**
-     * Reports an externally measured content inset. Pass null/undefined to clear.
-     * Values are merged on top of props/animated/native insets.
+     * Sets or adds to the offset of the visible content anchor.
+     * @param value - The offset to set or add.
+     * @param animated - If true, uses Animated to animate the change.
      */
-    reportContentInset(inset?: Partial<Insets> | null): void;
+    setVisibleContentAnchorOffset(value: number | ((val: number) => number)): void;
 };
 interface ViewToken<ItemT = any> {
     containerId: number;

package/keyboard-legacy.d.ts

@@ -9,8 +9,8 @@ interface MaintainVisibleContentPositionNormalized<ItemT = any> {
     shouldRestorePosition?: (item: ItemT, index: number, data: readonly ItemT[]) => boolean;
 }
 
-type ListenerType = "activeStickyIndex" | "alignItemsAtEndPadding" | "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 ListenerType = "activeStickyIndex" | "alignItemsAtEndPadding" | "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" | "adaptiveRender" | `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" | "adaptiveRender" | "lastItemKeys" | "lastPositionUpdate" | "numContainers" | "numContainersPooled" | "otherAxisSize" | "readyToRender" | "snapToOffsets" | "totalSize">;
 type ListenerTypeValueMap = {
     activeStickyIndex: number;
     alignItemsAtEndPadding: number;
@@ -44,6 +44,7 @@ type ListenerTypeValueMap = {
     snapToOffsets: number[];
     stylePaddingTop: number;
     totalSize: number;
+    adaptiveRender: "normal" | "light";
 } & {
     [K in ListenerType as K extends `containerItemKey${number}` ? K : never]: string;
 } & {
@@ -64,6 +65,12 @@ interface Insets {
     bottom: number;
     right: number;
 }
+interface LayoutRectangle {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
 interface ScrollToEndOptions {
     animated?: boolean;
     viewOffset?: number;
@@ -100,6 +107,14 @@ type LegendListState = {
     startBuffered: number;
 };
 type LegendListRef$1 = {
+    /**
+     * Clears internal virtualization caches.
+     * @param options - Cache clearing options.
+     * @param options.mode - `sizes` clears measurement caches. `full` also clears key/position caches.
+     */
+    clearCaches(options?: {
+        mode?: "sizes" | "full";
+    }): void;
     /**
      * Displays the scroll indicators momentarily.
      */
@@ -120,6 +135,11 @@ type LegendListRef$1 = {
      * Returns the internal state of the scroll virtualization.
      */
     getState(): LegendListState;
+    /**
+     * Reports an externally measured content inset. Pass null/undefined to clear.
+     * Values are merged on top of props/animated/native insets.
+     */
+    reportContentInset(inset?: Partial<Insets> | null): void;
     /**
      * Scrolls a specific index into view.
      * @param params - Parameters for scrolling.
@@ -186,29 +206,22 @@ type LegendListRef$1 = {
         animated?: boolean | undefined;
     }): Promise<void>;
     /**
-     * Sets or adds to the offset of the visible content anchor.
-     * @param value - The offset to set or add.
-     * @param animated - If true, uses Animated to animate the change.
+     * Sets a measured item size and recalculates list positions as needed.
+     * @param itemKey - The key of the item whose size changed.
+     * @param size - The measured item size.
      */
-    setVisibleContentAnchorOffset(value: number | ((val: number) => number)): void;
+    setItemSize(itemKey: string, size: Pick<LayoutRectangle, "height" | "width">): void;
     /**
      * Sets whether scroll processing is enabled.
      * @param enabled - If true, scroll processing is enabled.
      */
     setScrollProcessingEnabled(enabled: boolean): void;
     /**
-     * Clears internal virtualization caches.
-     * @param options - Cache clearing options.
-     * @param options.mode - `sizes` clears measurement caches. `full` also clears key/position caches.
-     */
-    clearCaches(options?: {
-        mode?: "sizes" | "full";
-    }): void;
-    /**
-     * Reports an externally measured content inset. Pass null/undefined to clear.
-     * Values are merged on top of props/animated/native insets.
+     * Sets or adds to the offset of the visible content anchor.
+     * @param value - The offset to set or add.
+     * @param animated - If true, uses Animated to animate the change.
      */
-    reportContentInset(inset?: Partial<Insets> | null): void;
+    setVisibleContentAnchorOffset(value: number | ((val: number) => number)): void;
 };
 
 type LegendListRef = Omit<LegendListRef$1, "getNativeScrollRef" | "getScrollResponder" | "reportContentInset"> & {

package/keyboard.d.ts

@@ -10,8 +10,8 @@ interface MaintainVisibleContentPositionNormalized<ItemT = any> {
     shouldRestorePosition?: (item: ItemT, index: number, data: readonly ItemT[]) => boolean;
 }
 
-type ListenerType = "activeStickyIndex" | "alignItemsAtEndPadding" | "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 ListenerType = "activeStickyIndex" | "alignItemsAtEndPadding" | "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" | "adaptiveRender" | `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" | "adaptiveRender" | "lastItemKeys" | "lastPositionUpdate" | "numContainers" | "numContainersPooled" | "otherAxisSize" | "readyToRender" | "snapToOffsets" | "totalSize">;
 type ListenerTypeValueMap = {
     activeStickyIndex: number;
     alignItemsAtEndPadding: number;
@@ -45,6 +45,7 @@ type ListenerTypeValueMap = {
     snapToOffsets: number[];
     stylePaddingTop: number;
     totalSize: number;
+    adaptiveRender: "normal" | "light";
 } & {
     [K in ListenerType as K extends `containerItemKey${number}` ? K : never]: string;
 } & {
@@ -65,6 +66,12 @@ interface Insets {
     bottom: number;
     right: number;
 }
+interface LayoutRectangle {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
 interface AnchoredEndSpaceReadyInfo {
     anchorIndex: number | undefined;
     anchorKey: string | undefined;
@@ -114,6 +121,14 @@ type LegendListState = {
     startBuffered: number;
 };
 type LegendListRef$1 = {
+    /**
+     * Clears internal virtualization caches.
+     * @param options - Cache clearing options.
+     * @param options.mode - `sizes` clears measurement caches. `full` also clears key/position caches.
+     */
+    clearCaches(options?: {
+        mode?: "sizes" | "full";
+    }): void;
     /**
      * Displays the scroll indicators momentarily.
      */
@@ -134,6 +149,11 @@ type LegendListRef$1 = {
      * Returns the internal state of the scroll virtualization.
      */
     getState(): LegendListState;
+    /**
+     * Reports an externally measured content inset. Pass null/undefined to clear.
+     * Values are merged on top of props/animated/native insets.
+     */
+    reportContentInset(inset?: Partial<Insets> | null): void;
     /**
      * Scrolls a specific index into view.
      * @param params - Parameters for scrolling.
@@ -200,29 +220,22 @@ type LegendListRef$1 = {
         animated?: boolean | undefined;
     }): Promise<void>;
     /**
-     * Sets or adds to the offset of the visible content anchor.
-     * @param value - The offset to set or add.
-     * @param animated - If true, uses Animated to animate the change.
+     * Sets a measured item size and recalculates list positions as needed.
+     * @param itemKey - The key of the item whose size changed.
+     * @param size - The measured item size.
      */
-    setVisibleContentAnchorOffset(value: number | ((val: number) => number)): void;
+    setItemSize(itemKey: string, size: Pick<LayoutRectangle, "height" | "width">): void;
     /**
      * Sets whether scroll processing is enabled.
      * @param enabled - If true, scroll processing is enabled.
      */
     setScrollProcessingEnabled(enabled: boolean): void;
     /**
-     * Clears internal virtualization caches.
-     * @param options - Cache clearing options.
-     * @param options.mode - `sizes` clears measurement caches. `full` also clears key/position caches.
-     */
-    clearCaches(options?: {
-        mode?: "sizes" | "full";
-    }): void;
-    /**
-     * Reports an externally measured content inset. Pass null/undefined to clear.
-     * Values are merged on top of props/animated/native insets.
+     * Sets or adds to the offset of the visible content anchor.
+     * @param value - The offset to set or add.
+     * @param animated - If true, uses Animated to animate the change.
      */
-    reportContentInset(inset?: Partial<Insets> | null): void;
+    setVisibleContentAnchorOffset(value: number | ((val: number) => number)): void;
 };
 
 interface AnchoredEndSpaceConfig extends Omit<AnchoredEndSpaceConfig$1, "includeInEndInset"> {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@legendapp/list",
-  "version": "3.0.6",
+  "version": "3.1.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

@@ -8,8 +8,8 @@ interface MaintainVisibleContentPositionNormalized<ItemT = any> {
     shouldRestorePosition?: (item: ItemT, index: number, data: readonly ItemT[]) => boolean;
 }
 
-type ListenerType = "activeStickyIndex" | "alignItemsAtEndPadding" | "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 ListenerType = "activeStickyIndex" | "alignItemsAtEndPadding" | "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" | "adaptiveRender" | `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" | "adaptiveRender" | "lastItemKeys" | "lastPositionUpdate" | "numContainers" | "numContainersPooled" | "otherAxisSize" | "readyToRender" | "snapToOffsets" | "totalSize">;
 type ListenerTypeValueMap = {
     activeStickyIndex: number;
     alignItemsAtEndPadding: number;
@@ -43,6 +43,7 @@ type ListenerTypeValueMap = {
     snapToOffsets: number[];
     stylePaddingTop: number;
     totalSize: number;
+    adaptiveRender: "normal" | "light";
 } & {
     [K in ListenerType as K extends `containerItemKey${number}` ? K : never]: string;
 } & {
@@ -90,6 +91,28 @@ interface NativeSyntheticEvent<T> {
 }
 type ViewStyle = Record<string, unknown>;
 type StyleProp<T> = T | T[] | null | undefined | false;
+type AdaptiveRender = "normal" | "light";
+interface AdaptiveRenderConfig {
+    /**
+     * Scroll velocity in pixels per millisecond above which items should switch to light mode.
+     * @default 4
+     */
+    enterVelocity?: number;
+    /**
+     * Scroll velocity in pixels per millisecond below which items can return to normal mode.
+     * @default 1
+     */
+    exitVelocity?: number;
+    /**
+     * Time to wait without velocity above exitVelocity before returning to normal mode.
+     * @default 1000
+     */
+    exitDelay?: number;
+    /**
+     * Called when the list-level adaptive render changes.
+     */
+    onChange?: (mode: AdaptiveRender) => void;
+}
 type BaseScrollViewProps<TScrollView> = Omit<TScrollView, "contentOffset" | "maintainVisibleContentPosition" | "stickyHeaderIndices" | "removeClippedSubviews" | "children" | "onScroll">;
 interface DataModeProps<ItemT, TItemType extends string | undefined> {
     /**
@@ -298,6 +321,10 @@ interface LegendListSpecificProps<ItemT, TItemType extends string | undefined> {
      * Called when list layout metrics change.
      */
     onMetricsChange?: (metrics: LegendListMetrics) => void;
+    /**
+     * Configures the adaptive render signal. Items can use this to render a lighter version while scrolling quickly.
+     */
+    experimental_adaptiveRender?: AdaptiveRenderConfig;
     /**
      * Function to call when the user pulls to refresh.
      */
@@ -496,6 +523,14 @@ type LegendListState$1 = {
     startBuffered: number;
 };
 type LegendListRef$1 = {
+    /**
+     * Clears internal virtualization caches.
+     * @param options - Cache clearing options.
+     * @param options.mode - `sizes` clears measurement caches. `full` also clears key/position caches.
+     */
+    clearCaches(options?: {
+        mode?: "sizes" | "full";
+    }): void;
     /**
      * Displays the scroll indicators momentarily.
      */
@@ -516,6 +551,11 @@ type LegendListRef$1 = {
      * Returns the internal state of the scroll virtualization.
      */
     getState(): LegendListState$1;
+    /**
+     * Reports an externally measured content inset. Pass null/undefined to clear.
+     * Values are merged on top of props/animated/native insets.
+     */
+    reportContentInset(inset?: Partial<Insets> | null): void;
     /**
      * Scrolls a specific index into view.
      * @param params - Parameters for scrolling.
@@ -582,29 +622,22 @@ type LegendListRef$1 = {
         animated?: boolean | undefined;
     }): Promise<void>;
     /**
-     * Sets or adds to the offset of the visible content anchor.
-     * @param value - The offset to set or add.
-     * @param animated - If true, uses Animated to animate the change.
+     * Sets a measured item size and recalculates list positions as needed.
+     * @param itemKey - The key of the item whose size changed.
+     * @param size - The measured item size.
      */
-    setVisibleContentAnchorOffset(value: number | ((val: number) => number)): void;
+    setItemSize(itemKey: string, size: Pick<LayoutRectangle, "height" | "width">): void;
     /**
      * Sets whether scroll processing is enabled.
      * @param enabled - If true, scroll processing is enabled.
      */
     setScrollProcessingEnabled(enabled: boolean): void;
     /**
-     * Clears internal virtualization caches.
-     * @param options - Cache clearing options.
-     * @param options.mode - `sizes` clears measurement caches. `full` also clears key/position caches.
-     */
-    clearCaches(options?: {
-        mode?: "sizes" | "full";
-    }): void;
-    /**
-     * Reports an externally measured content inset. Pass null/undefined to clear.
-     * Values are merged on top of props/animated/native insets.
+     * Sets or adds to the offset of the visible content anchor.
+     * @param value - The offset to set or add.
+     * @param animated - If true, uses Animated to animate the change.
      */
-    reportContentInset(inset?: Partial<Insets> | null): void;
+    setVisibleContentAnchorOffset(value: number | ((val: number) => number)): void;
 };
 interface ViewToken<ItemT = any> {
     containerId: number;
@@ -701,6 +734,8 @@ type LegendListState = Omit<LegendListState$1, "elementAtIndex"> & {
 };
 type LegendListComponent = <ItemT = any>(props: LegendListProps<ItemT> & React.RefAttributes<LegendListRef>) => React.ReactElement | null;
 
+declare function useAdaptiveRender(): AdaptiveRender;
+declare function useAdaptiveRenderChange(callback: (mode: AdaptiveRender) => void): void;
 declare function useViewability<ItemT = any>(callback: ViewabilityCallback<ItemT>, configId?: string): void;
 declare function useViewabilityAmount<ItemT = any>(callback: ViewabilityAmountCallback<ItemT>): void;
 declare function useRecyclingEffect(effect: (info: LegendListRecyclingState<unknown>) => void | (() => void)): void;
@@ -714,4 +749,4 @@ declare function useSyncLayout(): () => void;
 
 declare const LegendList: LegendListComponent;
 
-export { 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, useIsLastItem, useListScrollSize, useRecyclingEffect, useRecyclingState, useSyncLayout, useViewability, useViewabilityAmount };
+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 };