@legendapp/list 3.0.0-beta.32 → 3.0.0-beta.34

package/keyboard.d.ts

@@ -1,13 +1,209 @@
-import * as React from 'react';
-import { Insets } from 'react-native';
-import { ReanimatedScrollEvent } from 'react-native-reanimated/lib/typescript/hook/commonTypes';
-import { LegendListRef } from '@legendapp/list';
+import * as React$1 from 'react';
+import { ScrollViewComponent, ScrollResponderMixin, Insets as Insets$1 } from 'react-native';
+import { ScrollEvent, ScrollHandlerProcessed } from 'react-native-reanimated';
 import { AnimatedLegendListProps } from '@legendapp/list/reanimated';
 
+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">;
+type ListenerTypeValueMap = {
+    activeStickyIndex: number;
+    animatedScrollY: any;
+    debugComputedScroll: number;
+    debugRawScroll: number;
+    extraData: any;
+    footerSize: number;
+    headerSize: number;
+    lastItemKeys: string[];
+    lastPositionUpdate: number;
+    maintainVisibleContentPosition: MaintainVisibleContentPositionNormalized;
+    numColumns: number;
+    numContainers: number;
+    numContainersPooled: number;
+    otherAxisSize: number;
+    readyToRender: boolean;
+    scrollAdjust: number;
+    scrollAdjustPending: number;
+    scrollAdjustUserOffset: number;
+    scrollSize: {
+        width: number;
+        height: number;
+    };
+    snapToOffsets: number[];
+    stylePaddingTop: number;
+    totalSize: number;
+} & {
+    [K in ListenerType as K extends `containerItemKey${number}` ? K : never]: string;
+} & {
+    [K in ListenerType as K extends `containerItemData${number}` ? K : never]: any;
+} & {
+    [K in ListenerType as K extends `containerPosition${number}` ? K : never]: number;
+} & {
+    [K in ListenerType as K extends `containerColumn${number}` ? K : never]: number;
+} & {
+    [K in ListenerType as K extends `containerSpan${number}` ? K : never]: number;
+} & {
+    [K in ListenerType as K extends `containerSticky${number}` ? K : never]: boolean;
+};
+
+interface Insets {
+    top: number;
+    left: number;
+    bottom: number;
+    right: number;
+}
+interface MaintainVisibleContentPositionNormalized<ItemT = any> {
+    data: boolean;
+    size: boolean;
+    shouldRestorePosition?: (item: ItemT, index: number, data: readonly ItemT[]) => boolean;
+}
+type LegendListState = {
+    activeStickyIndex: number;
+    contentLength: number;
+    data: readonly any[];
+    elementAtIndex: (index: number) => any;
+    end: number;
+    endBuffered: number;
+    isAtEnd: boolean;
+    isAtStart: 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;
+    positionByKey: (key: string) => number | undefined;
+    scroll: number;
+    scrollLength: number;
+    scrollVelocity: number;
+    sizeAtIndex: (index: number) => number;
+    sizes: Map<string, number>;
+    start: number;
+    startBuffered: number;
+};
+type LegendListRef$1 = {
+    /**
+     * Displays the scroll indicators momentarily.
+     */
+    flashScrollIndicators(): void;
+    /**
+     * Returns the native ScrollView component reference.
+     */
+    getNativeScrollRef(): any;
+    /**
+     * Returns the scroll responder instance for handling scroll events.
+     */
+    getScrollableNode(): any;
+    /**
+     * Returns the ScrollResponderMixin for advanced scroll handling.
+     */
+    getScrollResponder(): any;
+    /**
+     * Returns the internal state of the scroll virtualization.
+     */
+    getState(): LegendListState;
+    /**
+     * Scrolls a specific index into view.
+     * @param params - Parameters for scrolling.
+     * @param params.animated - If true, animates the scroll. Default: true.
+     * @param params.index - The index to scroll to.
+     */
+    scrollIndexIntoView(params: {
+        animated?: boolean | undefined;
+        index: number;
+    }): Promise<void>;
+    /**
+     * Scrolls a specific index into view.
+     * @param params - Parameters for scrolling.
+     * @param params.animated - If true, animates the scroll. Default: true.
+     * @param params.item - The item to scroll to.
+     */
+    scrollItemIntoView(params: {
+        animated?: boolean | undefined;
+        item: any;
+    }): Promise<void>;
+    /**
+     * Scrolls to the end of the list.
+     * @param options - Options for scrolling.
+     * @param options.animated - If true, animates the scroll. Default: true.
+     * @param options.viewOffset - Offset from the target position.
+     */
+    scrollToEnd(options?: {
+        animated?: boolean | undefined;
+        viewOffset?: number | undefined;
+    }): Promise<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;
+    }): Promise<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;
+    }): Promise<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;
+    }): 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.
+     */
+    setVisibleContentAnchorOffset(value: number | ((val: number) => number)): 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.
+     */
+    reportContentInset(inset?: Partial<Insets> | null): void;
+};
+
+type LegendListRef = Omit<LegendListRef$1, "getNativeScrollRef" | "getScrollResponder" | "reportContentInset"> & {
+    getNativeScrollRef(): React.ElementRef<typeof ScrollViewComponent>;
+    getScrollResponder(): ScrollResponderMixin;
+    reportContentInset(inset?: Partial<Insets$1> | null): void;
+};
+
+type KeyboardOnScrollCallback = (event: ScrollEvent) => void;
+type KeyboardOnScrollHandler = KeyboardOnScrollCallback | ScrollHandlerProcessed<Record<string, unknown>>;
 declare const KeyboardAvoidingLegendList: <ItemT>(props: Omit<AnimatedLegendListProps<ItemT>, "onScroll" | "automaticallyAdjustContentInsets" | "contentInset"> & {
-    onScroll?: (event: ReanimatedScrollEvent) => void;
-    contentInset?: Insets | undefined;
+    onScroll?: KeyboardOnScrollHandler;
+    contentInset?: Insets$1 | undefined;
     safeAreaInsetBottom?: number;
-} & React.RefAttributes<LegendListRef>) => React.ReactNode;
+} & React$1.RefAttributes<LegendListRef>) => React$1.ReactNode;
 
-export { KeyboardAvoidingLegendList, KeyboardAvoidingLegendList as LegendList };
+export { KeyboardAvoidingLegendList };

package/keyboard.js

@@ -49,6 +49,7 @@ var useCombinedRef = (...refs) => {
   }, refs);
   return callback;
 };
+var typedForwardRef = React.forwardRef;
 
 // src/integrations/keyboard.tsx
 var clampProgress = (progress) => {
@@ -74,7 +75,7 @@ var calculateKeyboardTargetOffset = (startOffset, keyboardHeight, isOpening, pro
   const delta = (isOpening ? keyboardHeight : -keyboardHeight) * normalizedProgress;
   return Math.max(0, startOffset + delta);
 };
-var KeyboardAvoidingLegendList = React.forwardRef(function KeyboardAvoidingLegendList2(props, forwardedRef) {
+var KeyboardAvoidingLegendList = typedForwardRef(function KeyboardAvoidingLegendList2(props, forwardedRef) {
   const {
     contentContainerStyle: contentContainerStyleProp,
     contentInset: contentInsetProp,
@@ -95,7 +96,7 @@ var KeyboardAvoidingLegendList = React.forwardRef(function KeyboardAvoidingLegen
   const scrollOffsetY = reactNativeReanimated.useSharedValue(0);
   const animatedOffsetY = reactNativeReanimated.useSharedValue(null);
   const scrollOffsetAtKeyboardStart = reactNativeReanimated.useSharedValue(0);
-  const mode = reactNativeReanimated.useSharedValue("idle");
+  const animationMode = reactNativeReanimated.useSharedValue("idle");
   const keyboardInset = reactNativeReanimated.useSharedValue(0);
   const keyboardHeight = reactNativeReanimated.useSharedValue(0);
   const contentLength = reactNativeReanimated.useSharedValue(0);
@@ -106,17 +107,33 @@ var KeyboardAvoidingLegendList = React.forwardRef(function KeyboardAvoidingLegen
   const isKeyboardOpen = reactNativeReanimated.useSharedValue(false);
   const keyboardInsetRef = React.useRef(0);
   const [alignItemsAtEndMinSize, setAlignItemsAtEndMinSize] = React.useState(void 0);
+  const onScrollValue = onScrollProp;
+  const onScrollCallback = typeof onScrollValue === "function" ? onScrollValue : void 0;
+  const onScrollProcessed = onScrollValue && typeof onScrollValue === "object" && "workletEventHandler" in onScrollValue ? onScrollValue : null;
+  const onScrollCallbackIsWorklet = React.useMemo(
+    () => onScrollCallback ? reactNativeReanimated.isWorkletFunction(onScrollCallback) : false,
+    [onScrollCallback]
+  );
   const scrollHandler = reactNativeReanimated.useAnimatedScrollHandler(
     (event) => {
-      if (mode.get() !== "running" || didInteractive.get()) {
+      if (animationMode.get() !== "running" || didInteractive.get()) {
         scrollOffsetY.set(event.contentOffset[horizontal ? "x" : "y"]);
       }
-      if (onScrollProp) {
-        reactNativeReanimated.runOnJS(onScrollProp)(event);
+      if (onScrollCallback) {
+        if (onScrollCallbackIsWorklet) {
+          onScrollCallback(event);
+        } else {
+          reactNativeReanimated.runOnJS(onScrollCallback)(event);
+        }
       }
     },
-    [onScrollProp, horizontal]
+    [horizontal, onScrollCallback, onScrollCallbackIsWorklet]
   );
+  const composedScrollHandler = reactNativeReanimated.useComposedEventHandler([
+    scrollHandler,
+    onScrollProcessed
+  ]);
+  const finalScrollHandler = onScrollProcessed ? composedScrollHandler : scrollHandler;
   const setScrollProcessingEnabled = React.useCallback(
     (enabled) => {
       var _a;
@@ -184,19 +201,39 @@ var KeyboardAvoidingLegendList = React.forwardRef(function KeyboardAvoidingLegen
   React.useEffect(() => {
     updateAlignItemsAtEndMinSize();
   }, [updateAlignItemsAtEndMinSize]);
+  const getEffectiveKeyboardHeightFromInset = React.useCallback(
+    (nextKeyboardInset) => {
+      "worklet";
+      return calculateEffectiveKeyboardHeight(
+        nextKeyboardInset,
+        contentLength.get(),
+        scrollLength.get(),
+        alignItemsAtEnd
+      );
+    },
+    [alignItemsAtEnd, contentLength, scrollLength]
+  );
+  const getEffectiveKeyboardHeightFromEvent = React.useCallback(
+    (eventHeight) => {
+      "worklet";
+      const nextKeyboardInset = calculateKeyboardInset(eventHeight, safeAreaInsetBottom);
+      return getEffectiveKeyboardHeightFromInset(nextKeyboardInset);
+    },
+    [getEffectiveKeyboardHeightFromInset, safeAreaInsetBottom]
+  );
   reactNativeKeyboardController.useKeyboardHandler(
     // biome-ignore assist/source/useSortedKeys: prefer start/move/end
     {
       onStart: (event) => {
         "worklet";
-        mode.set("running");
+        animationMode.set("running");
         const progress = clampProgress(event.progress);
         if (isKeyboardOpen.get() && progress >= 1 && event.height > 0) {
           return;
         }
         if (!didInteractive.get()) {
           if (event.height > 0) {
-            keyboardHeight.set(event.height - safeAreaInsetBottom);
+            keyboardHeight.set(calculateKeyboardInset(event.height, safeAreaInsetBottom));
           }
           const vIsOpening = progress > 0;
           isOpening.set(vIsOpening);
@@ -209,15 +246,7 @@ var KeyboardAvoidingLegendList = React.forwardRef(function KeyboardAvoidingLegen
           const vScrollOffset = scrollOffsetY.get();
           scrollOffsetAtKeyboardStart.set(vScrollOffset);
           if (isIos) {
-            const vContentLength = contentLength.get();
-            const vScrollLength = scrollLength.get();
-            const vKeyboardHeight = keyboardHeight.get();
-            const vEffectiveKeyboardHeight = calculateEffectiveKeyboardHeight(
-              vKeyboardHeight,
-              vContentLength,
-              vScrollLength,
-              alignItemsAtEnd
-            );
+            const vEffectiveKeyboardHeight = getEffectiveKeyboardHeightFromInset(keyboardHeight.get());
             const targetOffset = Math.max(
               0,
               vIsOpening ? vScrollOffset + vEffectiveKeyboardHeight : vScrollOffset - vEffectiveKeyboardHeight
@@ -234,10 +263,10 @@ var KeyboardAvoidingLegendList = React.forwardRef(function KeyboardAvoidingLegen
       },
       onInteractive: (event) => {
         "worklet";
-        if (mode.get() !== "running") {
+        if (animationMode.get() !== "running") {
           reactNativeReanimated.runOnJS(setScrollProcessingEnabled)(false);
         }
-        mode.set("running");
+        animationMode.set("running");
         if (!didInteractive.get()) {
           didInteractive.set(true);
         }
@@ -246,13 +275,7 @@ var KeyboardAvoidingLegendList = React.forwardRef(function KeyboardAvoidingLegen
           keyboardInset.set(newInset);
         }
         if (shouldUpdateAlignItemsAtEndMinSize.get() && !horizontal && alignItemsAtEnd) {
-          const vKeyboardHeight = calculateKeyboardInset(event.height, safeAreaInsetBottom);
-          const vEffectiveKeyboardHeight = calculateEffectiveKeyboardHeight(
-            vKeyboardHeight,
-            contentLength.get(),
-            scrollLength.get(),
-            alignItemsAtEnd
-          );
+          const vEffectiveKeyboardHeight = getEffectiveKeyboardHeightFromEvent(event.height);
           reactNativeReanimated.runOnJS(updateAlignItemsAtEndMinSize)(vEffectiveKeyboardHeight);
         }
       },
@@ -262,13 +285,7 @@ var KeyboardAvoidingLegendList = React.forwardRef(function KeyboardAvoidingLegen
         if (isAndroid) {
           if (!didInteractive.get()) {
             const progress = clampProgress(event.progress);
-            const vKeyboardHeight = keyboardHeight.get();
-            const vEffectiveKeyboardHeight = calculateEffectiveKeyboardHeight(
-              vKeyboardHeight,
-              contentLength.get(),
-              scrollLength.get(),
-              alignItemsAtEnd
-            );
+            const vEffectiveKeyboardHeight = getEffectiveKeyboardHeightFromInset(keyboardHeight.get());
             const targetOffset = calculateKeyboardTargetOffset(
               scrollOffsetAtKeyboardStart.get(),
               vEffectiveKeyboardHeight,
@@ -284,30 +301,18 @@ var KeyboardAvoidingLegendList = React.forwardRef(function KeyboardAvoidingLegen
           }
         }
         if (!horizontal && alignItemsAtEnd && !vIsOpening && shouldUpdateAlignItemsAtEndMinSize.get()) {
-          const vKeyboardHeight = calculateKeyboardInset(event.height, safeAreaInsetBottom);
-          const vEffectiveKeyboardHeight = calculateEffectiveKeyboardHeight(
-            vKeyboardHeight,
-            contentLength.get(),
-            scrollLength.get(),
-            alignItemsAtEnd
-          );
+          const vEffectiveKeyboardHeight = getEffectiveKeyboardHeightFromEvent(event.height);
           reactNativeReanimated.runOnJS(updateAlignItemsAtEndMinSize)(vEffectiveKeyboardHeight);
         }
       },
       onEnd: (event) => {
         "worklet";
         const wasInteractive = didInteractive.get();
-        const vMode = mode.get();
-        mode.set("idle");
+        const vMode = animationMode.get();
+        animationMode.set("idle");
         if (vMode === "running") {
           const progress = clampProgress(event.progress);
-          const vKeyboardHeight = keyboardHeight.get();
-          const vEffectiveKeyboardHeight = calculateEffectiveKeyboardHeight(
-            vKeyboardHeight,
-            contentLength.get(),
-            scrollLength.get(),
-            alignItemsAtEnd
-          );
+          const vEffectiveKeyboardHeight = getEffectiveKeyboardHeightFromInset(keyboardHeight.get());
           const vIsOpening = isOpening.get();
           if (!wasInteractive) {
             const targetOffset = calculateKeyboardTargetOffset(
@@ -336,7 +341,18 @@ var KeyboardAvoidingLegendList = React.forwardRef(function KeyboardAvoidingLegen
         }
       }
     },
-    [alignItemsAtEnd, horizontal, safeAreaInsetBottom, scrollViewRef]
+    [
+      alignItemsAtEnd,
+      clearAlignItemsAtEndMinSize,
+      getEffectiveKeyboardHeightFromEvent,
+      getEffectiveKeyboardHeightFromInset,
+      horizontal,
+      reportContentInset,
+      safeAreaInsetBottom,
+      scrollViewRef,
+      setScrollProcessingEnabled,
+      updateAlignItemsAtEndMinSize
+    ]
   );
   const animatedProps = reactNativeReanimated.useAnimatedProps(() => {
     "worklet";
@@ -369,7 +385,7 @@ var KeyboardAvoidingLegendList = React.forwardRef(function KeyboardAvoidingLegen
       marginBottom: keyboardInset.get()
     }),
     [styleProp, keyboardInset]
-  ) : void 0;
+  ) : styleProp;
   const contentContainerStyle = React.useMemo(() => {
     if (alignItemsAtEndMinSize === void 0) {
       return contentContainerStyleProp;
@@ -386,7 +402,7 @@ var KeyboardAvoidingLegendList = React.forwardRef(function KeyboardAvoidingLegen
       contentContainerStyle,
       keyboardDismissMode: "interactive",
       onMetricsChange: handleMetricsChange,
-      onScroll: scrollHandler,
+      onScroll: finalScrollHandler,
       ref: combinedRef,
       refScrollView: scrollViewRef,
       scrollIndicatorInsets: { bottom: 0, top: 0 },
@@ -396,4 +412,3 @@ var KeyboardAvoidingLegendList = React.forwardRef(function KeyboardAvoidingLegen
 });
 
 exports.KeyboardAvoidingLegendList = KeyboardAvoidingLegendList;
-exports.LegendList = KeyboardAvoidingLegendList;