@shopify/flash-list 2.1.0 → 2.2.0

package/src/recyclerview/ViewHolderCollection.tsx

@@ -50,6 +50,10 @@ export interface ViewHolderCollectionProps<TItem> {
    * For startRenderingFromBottom, we need to adjust the height of the container
    */
   getAdjustmentMargin: () => number;
+  /** Current sticky index */
+  currentStickyIndex: number;
+  /** Whether the cell associated with an active sticky header is hidden */
+  hideStickyHeaderRelatedCell: boolean;
 }
 
 /**
@@ -84,6 +88,8 @@ export const ViewHolderCollection = <TItem,>(
     onCommitEffect,
     horizontal,
     getAdjustmentMargin,
+    currentStickyIndex,
+    hideStickyHeaderRelatedCell,
   } = props;
 
   const [renderId, setRenderId] = React.useState(0);
@@ -168,6 +174,7 @@ export const ViewHolderCollection = <TItem,>(
           const trailingItem = ItemSeparatorComponent
             ? data[index + 1]
             : undefined;
+
           return (
             <ViewHolder
               key={reactKey}
@@ -185,6 +192,9 @@ export const ViewHolderCollection = <TItem,>(
               CellRendererComponent={CellRendererComponent}
               ItemSeparatorComponent={ItemSeparatorComponent}
               horizontal={horizontal}
+              hidden={
+                hideStickyHeaderRelatedCell && currentStickyIndex === index
+              }
             />
           );
         })}

package/src/recyclerview/components/StickyHeaders.tsx

@@ -27,6 +27,10 @@ import { CompatAnimatedView } from "./CompatView";
 export interface StickyHeaderProps<TItem> {
   /** Array of indices that should have sticky headers */
   stickyHeaderIndices: number[];
+  /** Offset from the top where sticky headers should stick (in pixels) */
+  stickyHeaderOffset: number;
+  /** Sticky header change handler */
+  onChangeStickyIndex: (index: number) => void;
   /** The data array being rendered */
   data: ReadonlyArray<TItem>;
   /** Animated value tracking scroll position */
@@ -56,12 +60,14 @@ interface StickyHeaderState {
 
 export const StickyHeaders = <TItem,>({
   stickyHeaderIndices,
+  stickyHeaderOffset,
   renderItem,
   stickyHeaderRef,
   recyclerViewManager,
   scrollY,
   data,
   extraData,
+  onChangeStickyIndex,
 }: StickyHeaderProps<TItem>) => {
   const [stickyHeaderState, setStickyHeaderState] = useState<StickyHeaderState>(
     {
@@ -91,7 +97,7 @@ export const StickyHeaders = <TItem,>({
     // Binary search for current sticky index
     const currentIndexInArray = findCurrentStickyIndex(
       sortedIndices,
-      adjustedScrollOffset,
+      adjustedScrollOffset + stickyHeaderOffset,
       (index) => recyclerViewManager.getLayout(index).y
     );
 
@@ -102,7 +108,8 @@ export const StickyHeaders = <TItem,>({
       newNextStickyIndex = -1;
     }
 
-    // To make sure header offset is 0 in the interpolate compute
+    // Calculate when the next sticky header should start pushing the current one
+    // The next header starts pushing when it reaches the bottom of the current sticky header
     const newNextStickyY =
       newNextStickyIndex === -1
         ? Number.MAX_SAFE_INTEGER
@@ -111,6 +118,7 @@ export const StickyHeaders = <TItem,>({
     const newCurrentStickyHeight =
       recyclerViewManager.tryGetLayout(newStickyIndex)?.height ?? 0;
 
+    // Push should start when the next header reaches the bottom of the current sticky header
     const newPushStartsAt = newNextStickyY - newCurrentStickyHeight;
 
     if (
@@ -119,15 +127,21 @@ export const StickyHeaders = <TItem,>({
     ) {
       setStickyHeaderState({
         currentStickyIndex: newStickyIndex,
-        pushStartsAt: newPushStartsAt,
+        pushStartsAt: newPushStartsAt - stickyHeaderOffset,
       });
     }
+
+    if (newStickyIndex !== currentStickyIndex) {
+      onChangeStickyIndex?.(newStickyIndex);
+    }
   }, [
     legthInvalid,
     recyclerViewManager,
     sortedIndices,
     currentStickyIndex,
     pushStartsAt,
+    onChangeStickyIndex,
+    stickyHeaderOffset,
   ]);
 
   useEffect(() => {
@@ -147,16 +161,32 @@ export const StickyHeaders = <TItem,>({
 
   const refHolder = useRef(new Map()).current;
 
-  const translateY = useMemo(() => {
+  const { translateY, opacity } = useMemo(() => {
     const currentStickyHeight =
       recyclerViewManager.tryGetLayout(currentStickyIndex)?.height ?? 0;
 
-    return scrollY.interpolate({
-      inputRange: [pushStartsAt, pushStartsAt + currentStickyHeight],
-      outputRange: [0, -currentStickyHeight],
-      extrapolate: "clamp",
-    });
-  }, [recyclerViewManager, currentStickyIndex, scrollY, pushStartsAt]);
+    return {
+      translateY: scrollY.interpolate({
+        inputRange: [pushStartsAt, pushStartsAt + currentStickyHeight],
+        outputRange: [0, -currentStickyHeight],
+        extrapolate: "clamp",
+      }),
+      opacity:
+        stickyHeaderOffset > 0
+          ? scrollY.interpolate({
+              inputRange: [pushStartsAt, pushStartsAt + currentStickyHeight],
+              outputRange: [1, 0],
+              extrapolate: "clamp",
+            })
+          : undefined,
+    };
+  }, [
+    recyclerViewManager,
+    currentStickyIndex,
+    scrollY,
+    pushStartsAt,
+    stickyHeaderOffset,
+  ]);
 
   // Memoize header content
   const headerContent = useMemo(() => {
@@ -164,11 +194,12 @@ export const StickyHeaders = <TItem,>({
       <CompatAnimatedView
         style={{
           position: "absolute",
-          top: 0,
+          top: stickyHeaderOffset,
           left: 0,
           right: 0,
-          zIndex: 1,
+          zIndex: 2,
           transform: [{ translateY }],
+          opacity,
         }}
       >
         {currentStickyIndex !== -1 && currentStickyIndex < data.length ? (
@@ -181,11 +212,21 @@ export const StickyHeaders = <TItem,>({
             extraData={extraData}
             trailingItem={null}
             target="StickyHeader"
+            hidden={false}
           />
         ) : null}
       </CompatAnimatedView>
     );
-  }, [translateY, currentStickyIndex, data, renderItem, refHolder, extraData]);
+  }, [
+    translateY,
+    opacity,
+    currentStickyIndex,
+    data,
+    renderItem,
+    refHolder,
+    extraData,
+    stickyHeaderOffset,
+  ]);
 
   return headerContent;
 };

package/src/recyclerview/hooks/useSecondaryProps.tsx

@@ -20,6 +20,7 @@ import { CompatAnimatedScroller } from "../components/CompatScroller";
  *   - renderHeader: The header component renderer
  *   - renderFooter: The footer component renderer
  *   - renderEmpty: The empty state component renderer
+ *   - renderStickyHeaderBackdrop: The sticky header backdrop component renderer
  *   - CompatScrollView: The animated scroll component
  */
 export function useSecondaryProps<T>(props: RecyclerViewProps<T>) {
@@ -35,6 +36,7 @@ export function useSecondaryProps<T>(props: RecyclerViewProps<T>) {
     onRefresh,
     data,
     refreshControl: customRefreshControl,
+    stickyHeaderConfig,
   } = props;
 
   /**
@@ -94,6 +96,26 @@ export function useSecondaryProps<T>(props: RecyclerViewProps<T>) {
     return getValidComponent(ListEmptyComponent);
   }, [ListEmptyComponent, data]);
 
+  /**
+   * Creates the sticky header backdrop component.
+   */
+  const renderStickyHeaderBackdrop = useMemo(() => {
+    if (!stickyHeaderConfig?.backdropComponent) {
+      return null;
+    }
+    return (
+      <CompatView
+        style={{
+          position: "absolute",
+          inset: 0,
+          pointerEvents: "none",
+        }}
+      >
+        {getValidComponent(stickyHeaderConfig?.backdropComponent)}
+      </CompatView>
+    );
+  }, [stickyHeaderConfig?.backdropComponent]);
+
   /**
    * Creates an animated scroll component based on the provided renderScrollComponent.
    * If no custom component is provided, uses the default CompatAnimatedScroller.
@@ -120,5 +142,6 @@ export function useSecondaryProps<T>(props: RecyclerViewProps<T>) {
     renderFooter,
     renderEmpty,
     CompatScrollView,
+    renderStickyHeaderBackdrop,
   };
 }