feat: add prop disableAutoFixScroll to disable/enable auto scroll adjustment

Author: e-younan

example/src/screens/usage/FlatList.tsx

@@ -86,6 +86,7 @@ const FlatList: React.FC<FlatListUsageScreenNavigationProps> = () => {
       getItemLayout={(_, index) => ({ index, length: ITEM_HEIGHT, offset: index * ITEM_HEIGHT })}
       initialNumToRender={50}
       maxToRenderPerBatch={100}
+      disableAutoFixScroll
       keyExtractor={(_, i) => `text-row-${i}`}
     />
   );

src/components/containers/FlatList.tsx

@@ -34,6 +34,7 @@ const AnimatedFlatListWithHeaders = <ItemT extends unknown>({
   onMomentumScrollEnd,
   ignoreLeftSafeArea,
   ignoreRightSafeArea,
+  disableAutoFixScroll,
   ...rest
 }: AnimatedFlatListProps<ItemT> & SharedScrollContainerProps) => {
   const insets = useSafeAreaInsets();
@@ -46,6 +47,7 @@ const AnimatedFlatListWithHeaders = <ItemT extends unknown>({
       scrollRef,
       scrollY,
       largeHeaderShown,
+      disableAutoFixScroll,
       largeHeaderExists: !!LargeHeaderComponent,
     });
 

src/components/containers/ScrollView.tsx

@@ -26,6 +26,7 @@ const AnimatedScrollViewWithHeaders: React.FC<
   onScrollEndDrag,
   onMomentumScrollBegin,
   onMomentumScrollEnd,
+  disableAutoFixScroll,
   children,
   ...rest
 }) => {
@@ -38,6 +39,7 @@ const AnimatedScrollViewWithHeaders: React.FC<
       scrollRef,
       scrollY,
       largeHeaderShown,
+      disableAutoFixScroll,
       largeHeaderExists: !!LargeHeaderComponent,
     });
 

src/components/containers/types.ts

@@ -62,56 +62,55 @@ export type SharedScrollContainerProps = {
   HeaderComponent: (props: ScrollHeaderProps) => React.ReactNode;
   /**
    * This is executed when the onLayout event is fired on the large header container component.
-   *
-   * @param {LayoutRectangle} rect
    */
   onLargeHeaderLayout?: (rect: LayoutRectangle) => void;
   /**
    * The large header's container style.
    *
    * @default undefined
-   * @type {StyleProp<ViewStyle>}
    */
   largeHeaderContainerStyle?: StyleProp<ViewStyle>;
   /**
    * The style of the root container of the scoll container.
    *
    * @default undefined
-   * @type {StyleProp<ViewStyle>}
    */
   containerStyle?: StyleProp<ViewStyle>;
   /**
    * Whether the scroll container should ignore the left safe area. This is useful for landscape
    * mode on iOS where devices have a notch/status bar on the left side.
+   *
+   * @default false
    */
   ignoreLeftSafeArea?: boolean;
   /**
    * Whether the scroll container should ignore the right safe area. This is useful for landscape
    * mode on iOS where devices have a notch/status bar on the right side.
+   *
+   * @default false
    */
   ignoreRightSafeArea?: boolean;
   /**
-   * Fires if a user initiates a scroll gesture.
+   * Disables the auto fix scroll mechanism. This is useful if you want to disable the auto scroll
+   * when the large header is partially visible.
    *
-   * @param {NativeSyntheticEvent<NativeScrollEvent>} event
+   * @default false
+   */
+  disableAutoFixScroll?: boolean;
+  /**
+   * Fires if a user initiates a scroll gesture.
    */
   onScrollBeginDrag?: (event: NativeSyntheticEvent<NativeScrollEvent>) => void;
   /**
    * Fires when a user has finished scrolling.
-   *
-   * @param {NativeSyntheticEvent<NativeScrollEvent>} event
    */
   onScrollEndDrag?: (event: NativeSyntheticEvent<NativeScrollEvent>) => void;
   /**
    * Fires when scroll view has begun moving.
-   *
-   * @param {NativeSyntheticEvent<NativeScrollEvent>} event
    */
   onMomentumScrollBegin?: (event: NativeSyntheticEvent<NativeScrollEvent>) => void;
   /**
    * Fires when scroll view has finished moving.
-   *
-   * @param {NativeSyntheticEvent<NativeScrollEvent>} event
    */
   onMomentumScrollEnd?: (event: NativeSyntheticEvent<NativeScrollEvent>) => void;
 };

src/components/containers/useScrollContainerLogic.ts

@@ -39,8 +39,17 @@ interface UseScrollContainerLogicArgs {
    * @type {SharedScrollContainerProps['largeHeaderShown']}
    */
   largeHeaderShown: SharedScrollContainerProps['largeHeaderShown'];
-
+  /**
+   * Whether or not the large header exists.
+   */
   largeHeaderExists: boolean;
+  /**
+   * Disables the auto fix scroll mechanism. This is useful if you want to disable the auto scroll
+   * when the large header is partially visible.
+   *
+   * @default false
+   */
+  disableAutoFixScroll?: boolean;
 }
 
 /**
@@ -54,6 +63,7 @@ export const useScrollContainerLogic = ({
   scrollY,
   largeHeaderShown,
   largeHeaderExists,
+  disableAutoFixScroll = false,
   adjustmentOffset = 4,
 }: UseScrollContainerLogicArgs) => {
   const largeHeaderHeight = useSharedValue(0);
@@ -82,6 +92,8 @@ export const useScrollContainerLogic = ({
   });
 
   const debouncedFixScroll = useDebouncedCallback(() => {
+    if (disableAutoFixScroll) return;
+
     if (largeHeaderHeight.value !== 0 && scrollRef && scrollRef.current) {
       if (scrollY.value >= largeHeaderHeight.value / 2 && scrollY.value < largeHeaderHeight.value) {
         // Scroll to end of large header