@react-native-ohos/flash-list 1.8.3-rc.5 → 2.1.1-rc.1

package/src/recyclerview/helpers/EngagedIndicesTracker.ts

@@ -0,0 +1,301 @@
+import { PlatformConfig } from "../../native/config/PlatformHelper";
+import { RVLayoutManager } from "../layout-managers/LayoutManager";
+
+import { ConsecutiveNumbers } from "./ConsecutiveNumbers";
+
+export interface RVEngagedIndicesTracker {
+  // Current scroll offset of the list. Directly setting this won't trigger visible indices updates
+  scrollOffset: number;
+  // Total distance (in pixels) to pre-render items before and after the visible viewport
+  drawDistance: number;
+  // Whether to use offset projection to predict the next scroll offset
+  enableOffsetProjection: boolean;
+  // Average render time of the list
+  averageRenderTime: number;
+
+  /**
+   * Updates the scroll offset and calculates which items should be rendered (engaged indices).
+   * @param offset - The new scroll offset position
+   * @param velocity - Current scroll velocity to optimize buffer distribution
+   * @param layoutManager - Layout manager to fetch item positions and dimensions
+   * @returns New engaged indices if changed, undefined if no change
+   */
+  updateScrollOffset: (
+    offset: number,
+    velocity: Velocity | null | undefined,
+    layoutManager: RVLayoutManager
+  ) => ConsecutiveNumbers | undefined;
+
+  /**
+   * Returns the currently engaged (rendered) indices.
+   * This includes both visible items and buffer items.
+   * @returns The last computed set of engaged indices
+   */
+  getEngagedIndices: () => ConsecutiveNumbers;
+
+  /**
+   * Computes the visible indices in the viewport.
+   * @param layoutManager - Layout manager to fetch item positions and dimensions
+   * @returns Indices of items currently visible in the viewport
+   */
+  computeVisibleIndices: (layoutManager: RVLayoutManager) => ConsecutiveNumbers;
+
+  /**
+   * Sets the scroll direction for velocity history tracking.
+   * @param scrollDirection - The direction of scrolling ("forward" or "backward")
+   */
+  setScrollDirection: (scrollDirection: "forward" | "backward") => void;
+
+  /**
+   * Resets the velocity history based on the current scroll direction.
+   */
+  resetVelocityHistory: () => void;
+}
+
+export interface Velocity {
+  x: number;
+  y: number;
+}
+
+export class RVEngagedIndicesTrackerImpl implements RVEngagedIndicesTracker {
+  // Current scroll position of the list
+  public scrollOffset = 0;
+  // Distance to pre-render items before and after the visible viewport (in pixels)
+  public drawDistance = PlatformConfig.defaultDrawDistance;
+
+  // Whether to use offset projection to predict the next scroll offset
+  public enableOffsetProjection = true;
+
+  // Average render time of the list
+  public averageRenderTime = 16;
+
+  // Internal override to disable offset projection
+  private forceDisableOffsetProjection = false;
+
+  // Currently rendered item indices (including buffer items)
+  private engagedIndices = ConsecutiveNumbers.EMPTY;
+
+  // Buffer distribution multipliers for scroll direction optimization
+  private smallMultiplier = 0.3; // Used for buffer in the opposite direction of scroll
+  private largeMultiplier = 0.7; // Used for buffer in the direction of scroll
+
+  // Circular buffer to track recent scroll velocities for direction detection
+  private velocityHistory = [0, 0, 0, -0.1, -0.1];
+  private velocityIndex = 0;
+
+  /**
+   * Updates scroll position and determines which items should be rendered.
+   * Implements a smart buffer system that:
+   * 1. Calculates the visible viewport
+   * 2. Determines optimal buffer distribution based on scroll direction
+   * 3. Adjusts buffer sizes at list boundaries
+   * 4. Returns new indices that need to be rendered
+   */
+  updateScrollOffset(
+    offset: number,
+    velocity: Velocity | null | undefined,
+    layoutManager: RVLayoutManager
+  ): ConsecutiveNumbers | undefined {
+    // Update current scroll position
+    this.scrollOffset = offset;
+
+    // STEP 1: Determine the currently visible viewport
+    const windowSize = layoutManager.getWindowsSize();
+    const isHorizontal = layoutManager.isHorizontal();
+
+    // Update velocity history
+    if (velocity) {
+      this.updateVelocityHistory(isHorizontal ? velocity.x : velocity.y);
+    }
+
+    // Determine scroll direction to optimize buffer distribution
+    const isScrollingBackward = this.isScrollingBackward();
+    const viewportStart =
+      this.enableOffsetProjection && !this.forceDisableOffsetProjection
+        ? this.getProjectedScrollOffset(offset, this.averageRenderTime)
+        : offset;
+
+    // console.log("timeMs", this.averageRenderTime, offset, viewportStart);
+
+    const viewportSize = isHorizontal ? windowSize.width : windowSize.height;
+    const viewportEnd = viewportStart + viewportSize;
+
+    // STEP 2: Determine buffer size and distribution
+    // The total extra space where items will be pre-rendered
+    const totalBuffer = this.drawDistance * 2;
+
+    // Distribute more buffer in the direction of scrolling
+    // When scrolling forward: more buffer after viewport
+    // When scrolling backward: more buffer before viewport
+    const beforeRatio = isScrollingBackward
+      ? this.largeMultiplier
+      : this.smallMultiplier;
+    const afterRatio = isScrollingBackward
+      ? this.smallMultiplier
+      : this.largeMultiplier;
+
+    const bufferBefore = Math.ceil(totalBuffer * beforeRatio);
+    const bufferAfter = Math.ceil(totalBuffer * afterRatio);
+
+    // STEP 3: Calculate the extended viewport (visible area + buffers)
+    // The start position with buffer (never less than 0)
+    let extendedStart = Math.max(0, viewportStart - bufferBefore);
+
+    // If we couldn't apply full buffer at start, calculate how much was unused
+    const unusedStartBuffer = Math.max(0, bufferBefore - viewportStart);
+
+    // Add any unused start buffer to the end buffer
+    let extendedEnd = viewportEnd + bufferAfter + unusedStartBuffer;
+
+    // STEP 4: Handle end boundary adjustments
+    // Get the total content size to check for end boundary
+    const layoutSize = layoutManager.getLayoutSize();
+    const maxPosition = isHorizontal ? layoutSize.width : layoutSize.height;
+
+    // If we hit the end boundary, redistribute unused buffer to the start
+    if (extendedEnd > maxPosition) {
+      // Calculate unused end buffer and apply it to the start if possible
+      const unusedEndBuffer = extendedEnd - maxPosition;
+      extendedEnd = maxPosition;
+
+      // Try to extend start position further with the unused end buffer
+      extendedStart = Math.max(0, extendedStart - unusedEndBuffer);
+    }
+
+    // STEP 5: Get and return the new engaged indices
+    const newEngagedIndices = layoutManager.getVisibleLayouts(
+      extendedStart,
+      extendedEnd
+    );
+    // console.log(
+    //   "newEngagedIndices",
+    //   newEngagedIndices,
+    //   this.scrollOffset,
+    //   viewportStart
+    // );
+    // Only return new indices if they've changed
+    const oldEngagedIndices = this.engagedIndices;
+    this.engagedIndices = newEngagedIndices;
+
+    return newEngagedIndices.equals(oldEngagedIndices)
+      ? undefined
+      : newEngagedIndices;
+  }
+
+  /**
+   * Updates the velocity history with a new velocity value.
+   * @param velocity - Current scroll velocity component (x or y)
+   */
+  private updateVelocityHistory(velocity: number) {
+    this.velocityHistory[this.velocityIndex] = velocity;
+    this.velocityIndex = (this.velocityIndex + 1) % this.velocityHistory.length;
+  }
+
+  /**
+   * Determines scroll direction by analyzing recent velocity history.
+   * Uses a majority voting system on the last 5 velocity values.
+   * @returns true if scrolling backward (negative direction), false otherwise
+   */
+  private isScrollingBackward(): boolean {
+    // should decide based on whether we have more positive or negative values, use for loop
+    let positiveCount = 0;
+    let negativeCount = 0;
+    // eslint-disable-next-line @typescript-eslint/prefer-for-of
+    for (let i = 0; i < this.velocityHistory.length; i++) {
+      if (this.velocityHistory[i] > 0) {
+        positiveCount++;
+      } else if (this.velocityHistory[i] < 0) {
+        negativeCount++;
+      }
+    }
+    return positiveCount < negativeCount;
+  }
+
+  /**
+   * Calculates the median velocity based on velocity history
+   * Medina works better agains outliers
+   * @returns Median velocity over the recent history
+   */
+  private getMedianVelocity(): number {
+    // Make a copy of velocity history and sort it
+    const sortedVelocities = [...this.velocityHistory].sort(
+      (valueA, valueB) => valueA - valueB
+    );
+    const length = sortedVelocities.length;
+
+    // If length is odd, return the middle element
+    if (length % 2 === 1) {
+      return sortedVelocities[Math.floor(length / 2)];
+    }
+
+    // If length is even, return the average of the two middle elements
+    const midIndex = length / 2;
+    return (sortedVelocities[midIndex - 1] + sortedVelocities[midIndex]) / 2;
+  }
+
+  /**
+   * Projects the next scroll offset based on median velocity
+   * @param timeMs Time in milliseconds to predict ahead
+   * @returns Projected scroll offset
+   */
+  private getProjectedScrollOffset(offset: number, timeMs: number): number {
+    const medianVelocity = this.getMedianVelocity();
+    // Convert time from ms to seconds for velocity calculation
+    // Predict next position: current position + (velocity * time)
+    return offset + medianVelocity * timeMs;
+  }
+
+  /**
+   * Calculates which items are currently visible in the viewport.
+   * Unlike getEngagedIndices, this doesn't include buffer items.
+   * @param layoutManager - Layout manager to fetch item positions
+   * @returns Indices of items currently visible in the viewport
+   */
+  computeVisibleIndices(layoutManager: RVLayoutManager): ConsecutiveNumbers {
+    const windowSize = layoutManager.getWindowsSize();
+    const isHorizontal = layoutManager.isHorizontal();
+
+    // Calculate viewport boundaries
+    const viewportStart = this.scrollOffset;
+    const viewportSize = isHorizontal ? windowSize.width : windowSize.height;
+    const viewportEnd = viewportStart + viewportSize;
+
+    // Get indices of items currently visible in the viewport
+    const newVisibleIndices = layoutManager.getVisibleLayouts(
+      viewportStart,
+      viewportEnd
+    );
+    return newVisibleIndices;
+  }
+
+  /**
+   * Returns the currently engaged (rendered) indices.
+   * This includes both visible items and buffer items.
+   * @returns The last computed set of engaged indices
+   */
+  getEngagedIndices(): ConsecutiveNumbers {
+    return this.engagedIndices;
+  }
+
+  setScrollDirection(scrollDirection: "forward" | "backward") {
+    if (scrollDirection === "forward") {
+      this.velocityHistory = [0, 0, 0, 0.1, 0.1];
+      this.velocityIndex = 0;
+    } else {
+      this.velocityHistory = [0, 0, 0, -0.1, -0.1];
+      this.velocityIndex = 0;
+    }
+  }
+
+  /**
+   * Resets the velocity history based on the current scroll direction.
+   * This ensures that the velocity history is always in sync with the current scroll direction.
+   */
+  resetVelocityHistory() {
+    if (this.isScrollingBackward()) {
+      this.setScrollDirection("backward");
+    } else {
+      this.setScrollDirection("forward");
+    }
+  }
+}

package/src/recyclerview/helpers/RenderTimeTracker.ts

@@ -0,0 +1,50 @@
+import { PlatformConfig } from "../../native/config/PlatformHelper";
+import { AverageWindow } from "../../utils/AverageWindow";
+
+export class RenderTimeTracker {
+  private renderTimeAvgWindow = new AverageWindow(5);
+  private lastTimerStartedAt = -1;
+  private maxRenderTime = 32; // TODO: Improve this even more
+  private defaultRenderTime = 16;
+  private rendersWithoutCommit = 0;
+  private maxRendersWithoutCommit = 40;
+
+  startTracking() {
+    this.rendersWithoutCommit++;
+    if (!PlatformConfig.trackAverageRenderTimeForOffsetProjection) {
+      return;
+    }
+    if (this.lastTimerStartedAt === -1) {
+      this.lastTimerStartedAt = Date.now();
+    }
+  }
+
+  markRenderComplete() {
+    this.rendersWithoutCommit = 0;
+    if (!PlatformConfig.trackAverageRenderTimeForOffsetProjection) {
+      return;
+    }
+    if (this.lastTimerStartedAt !== -1) {
+      this.renderTimeAvgWindow.addValue(Date.now() - this.lastTimerStartedAt);
+      this.lastTimerStartedAt = -1;
+    }
+  }
+
+  hasExceededMaxRendersWithoutCommit() {
+    return this.rendersWithoutCommit >= this.maxRendersWithoutCommit;
+  }
+
+  getRawValue() {
+    return this.renderTimeAvgWindow.currentValue;
+  }
+
+  getAverageRenderTime() {
+    if (!PlatformConfig.trackAverageRenderTimeForOffsetProjection) {
+      return this.defaultRenderTime;
+    }
+    return Math.min(
+      this.maxRenderTime,
+      Math.max(Math.round(this.renderTimeAvgWindow.currentValue), 16)
+    );
+  }
+}

package/src/recyclerview/helpers/VelocityTracker.ts

@@ -0,0 +1,77 @@
+/**
+ * Tracks and calculates velocity for scroll/drag movements
+ * Used to determine momentum scrolling behavior
+ */
+export class VelocityTracker<T> {
+  /** Timestamp of the last velocity update */
+  private lastUpdateTime = Date.now();
+  /** Current velocity vector with x and y components */
+  private velocity = { x: 0, y: 0 };
+
+  /** Reference to the momentum end timeout */
+  private timeoutId: NodeJS.Timeout | null = null;
+
+  /**
+   * Calculates velocity based on position change over time
+   * @param newOffset Current position value
+   * @param oldOffset Previous position value
+   * @param isHorizontal Whether movement is horizontal (true) or vertical (false)
+   * @param isRTL Whether layout direction is right-to-left
+   * @param callback Function to call with velocity updates and momentum end signal
+   */
+  computeVelocity(
+    newOffset: number,
+    oldOffset: number,
+    isHorizontal: boolean,
+    callback: (
+      velocity: { x: number; y: number },
+      isMomentumEnd: boolean
+    ) => void
+  ) {
+    // Clear any pending momentum end timeout
+    this.cleanUp();
+    // Calculate time since last update
+    const currentTime = Date.now();
+    const timeSinceLastUpdate = Math.max(1, currentTime - this.lastUpdateTime);
+
+    // Calculate velocity as distance/time
+    const newVelocity = (newOffset - oldOffset) / timeSinceLastUpdate;
+
+    // console.log(
+    //   "newVelocity",
+    //   newOffset,
+    //   oldOffset,
+    //   currentTime,
+    //   this.lastUpdateTime,
+    //   timeSinceLastUpdate,
+    //   newVelocity
+    // );
+    this.lastUpdateTime = currentTime;
+
+    // Apply velocity to the correct axis
+    this.velocity.x = isHorizontal ? newVelocity : 0;
+    this.velocity.y = isHorizontal ? 0 : newVelocity;
+
+    // Trigger callback with current velocity
+    callback(this.velocity, false);
+
+    // Set timeout to signal momentum end after 100ms of no updates
+    this.timeoutId = setTimeout(() => {
+      this.cleanUp();
+      this.lastUpdateTime = Date.now();
+      this.velocity.x = 0;
+      this.velocity.y = 0;
+      callback(this.velocity, true);
+    }, 100);
+  }
+
+  /**
+   * Cleans up resources by clearing any pending timeout
+   */
+  cleanUp() {
+    if (this.timeoutId !== null) {
+      clearTimeout(this.timeoutId);
+      this.timeoutId = null;
+    }
+  }
+}

package/src/recyclerview/hooks/useBoundDetection.ts

@@ -0,0 +1,176 @@
+import { useCallback, useEffect, useMemo, useRef } from "react";
+
+import { RecyclerViewManager } from "../RecyclerViewManager";
+import { CompatScroller } from "../components/CompatScroller";
+
+import { useUnmountAwareAnimationFrame } from "./useUnmountAwareCallbacks";
+
+/**
+ * Hook to detect when the scroll position reaches near the start or end of the list
+ * and trigger the appropriate callbacks. This hook is responsible for:
+ * 1. Detecting when the user scrolls near the end of the list (onEndReached)
+ * 2. Detecting when the user scrolls near the start of the list (onStartReached)
+ * 3. Managing auto-scrolling to bottom when new content is added
+ *
+ * @param recyclerViewManager - The RecyclerViewManager instance that handles the list's core functionality
+ * @param props - The RecyclerViewProps containing configuration and callbacks
+ * @param scrollViewRef - Reference to the scrollable container component
+ */
+export function useBoundDetection<T>(
+  recyclerViewManager: RecyclerViewManager<T>,
+  scrollViewRef: React.RefObject<CompatScroller>
+) {
+  // Track whether we've already triggered the end reached callback to prevent duplicate calls
+  const pendingEndReached = useRef(false);
+  // Track whether we've already triggered the start reached callback to prevent duplicate calls
+  const pendingStartReached = useRef(false);
+  // Track whether we should auto-scroll to bottom when new content is added
+  const pendingAutoscrollToBottom = useRef(false);
+
+  const lastCheckBoundsTime = useRef(Date.now());
+
+  const { data } = recyclerViewManager.props;
+  const { requestAnimationFrame } = useUnmountAwareAnimationFrame();
+
+  const windowHeight = recyclerViewManager.hasLayout()
+    ? recyclerViewManager.getWindowSize().height
+    : 0;
+
+  const contentHeight = recyclerViewManager.hasLayout()
+    ? recyclerViewManager.getChildContainerDimensions().height
+    : 0;
+
+  const windowWidth = recyclerViewManager.hasLayout()
+    ? recyclerViewManager.getWindowSize().width
+    : 0;
+
+  const contentWidth = recyclerViewManager.hasLayout()
+    ? recyclerViewManager.getChildContainerDimensions().width
+    : 0;
+
+  /**
+   * Checks if the scroll position is near the start or end of the list
+   * and triggers appropriate callbacks if configured.
+   */
+  const checkBounds = useCallback(() => {
+    lastCheckBoundsTime.current = Date.now();
+
+    const {
+      onEndReached,
+      onStartReached,
+      maintainVisibleContentPosition,
+      horizontal,
+      onEndReachedThreshold: onEndReachedThresholdProp,
+      onStartReachedThreshold: onStartReachedThresholdProp,
+    } = recyclerViewManager.props;
+    // Skip all calculations if neither callback is provided and autoscroll is disabled
+    const autoscrollToBottomThreshold =
+      maintainVisibleContentPosition?.autoscrollToBottomThreshold ?? -1;
+
+    if (!onEndReached && !onStartReached && autoscrollToBottomThreshold < 0) {
+      return;
+    }
+
+    if (recyclerViewManager.getIsFirstLayoutComplete()) {
+      const lastScrollOffset =
+        recyclerViewManager.getAbsoluteLastScrollOffset();
+      const contentSize = recyclerViewManager.getChildContainerDimensions();
+      const windowSize = recyclerViewManager.getWindowSize();
+      const isHorizontal = horizontal === true;
+
+      // Calculate dimensions based on scroll direction
+      const visibleLength = isHorizontal ? windowSize.width : windowSize.height;
+      const contentLength =
+        (isHorizontal ? contentSize.width : contentSize.height) +
+        recyclerViewManager.firstItemOffset;
+
+      // Check if we're near the end of the list
+      if (onEndReached) {
+        const onEndReachedThreshold = onEndReachedThresholdProp ?? 0.5;
+        const endThresholdDistance = onEndReachedThreshold * visibleLength;
+
+        const isNearEnd =
+          Math.ceil(lastScrollOffset + visibleLength) >=
+          contentLength - endThresholdDistance;
+
+        if (isNearEnd && !pendingEndReached.current) {
+          pendingEndReached.current = true;
+          onEndReached();
+        }
+        pendingEndReached.current = isNearEnd;
+      }
+
+      // Check if we're near the start of the list
+      if (onStartReached) {
+        const onStartReachedThreshold = onStartReachedThresholdProp ?? 0.2;
+        const startThresholdDistance = onStartReachedThreshold * visibleLength;
+
+        const isNearStart = lastScrollOffset <= startThresholdDistance;
+
+        if (isNearStart && !pendingStartReached.current) {
+          pendingStartReached.current = true;
+          onStartReached();
+        }
+        pendingStartReached.current = isNearStart;
+      }
+
+      // Handle auto-scrolling to bottom for vertical lists
+      if (!isHorizontal && autoscrollToBottomThreshold >= 0) {
+        const autoscrollToBottomThresholdDistance =
+          autoscrollToBottomThreshold * visibleLength;
+
+        const isNearBottom =
+          Math.ceil(lastScrollOffset + visibleLength) >=
+          contentLength - autoscrollToBottomThresholdDistance;
+
+        if (isNearBottom) {
+          pendingAutoscrollToBottom.current = true;
+        } else {
+          pendingAutoscrollToBottom.current = false;
+        }
+      }
+    }
+  }, [recyclerViewManager]);
+
+  const runAutoScrollToBottomCheck = useCallback(() => {
+    if (pendingAutoscrollToBottom.current) {
+      pendingAutoscrollToBottom.current = false;
+      requestAnimationFrame(() => {
+        const shouldAnimate =
+          recyclerViewManager.props.maintainVisibleContentPosition
+            ?.animateAutoScrollToBottom ?? true;
+        scrollViewRef.current?.scrollToEnd({
+          animated: shouldAnimate,
+        });
+      });
+    }
+  }, [requestAnimationFrame, scrollViewRef, recyclerViewManager]);
+
+  // Reset end reached state when data changes
+  useMemo(() => {
+    pendingEndReached.current = false;
+    // needs to run only when data changes
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [data]);
+
+  // Auto-scroll to bottom when new content is added and we're near the bottom
+  useEffect(() => {
+    runAutoScrollToBottomCheck();
+  }, [data, runAutoScrollToBottomCheck, windowHeight, windowWidth]);
+
+  // Since content changes frequently, we try and avoid doing the auto scroll during active scrolls
+  useEffect(() => {
+    if (Date.now() - lastCheckBoundsTime.current >= 100) {
+      runAutoScrollToBottomCheck();
+    }
+  }, [
+    contentHeight,
+    contentWidth,
+    recyclerViewManager.firstItemOffset,
+    runAutoScrollToBottomCheck,
+  ]);
+
+  return {
+    checkBounds,
+  };
+}

package/src/recyclerview/hooks/useLayoutState.ts

@@ -0,0 +1,55 @@
+import { useState, useCallback } from "react";
+
+import { useRecyclerViewContext } from "../RecyclerViewContextProvider";
+
+export type LayoutStateSetter<T> = (
+  newValue: T | ((prevValue: T) => T),
+  skipParentLayout?: boolean
+) => void;
+
+export type LayoutStateInitialValue<T> = T | (() => T);
+
+/**
+ * Custom hook that combines state management with RecyclerView layout updates.
+ * This hook provides a way to manage state that affects the layout of the RecyclerView,
+ * ensuring that any state changes trigger a layout recalculation.
+ *
+ * @param initialState - The initial state value or a function that returns the initial state
+ * @returns A tuple containing:
+ *   - The current state value
+ *   - A setter function that updates the state and triggers a layout recalculation
+ */
+export function useLayoutState<T>(
+  initialState: LayoutStateInitialValue<T>
+): [T, LayoutStateSetter<T>] {
+  // Initialize state with the provided initial value
+  const [state, setState] = useState<T>(initialState);
+  // Get the RecyclerView context for layout management
+  const recyclerViewContext = useRecyclerViewContext();
+
+  /**
+   * Setter function that updates the state and triggers a layout recalculation.
+   * This ensures that any state changes that affect the layout are properly reflected
+   * in the RecyclerView's visual representation.
+   *
+   * @param newValue - Either a new state value or a function that receives the previous state
+   *                   and returns the new state
+   */
+  const setLayoutState: LayoutStateSetter<T> = useCallback(
+    (newValue, skipParentLayout) => {
+      // Update the state using either the new value or the result of the updater function
+      setState((prevValue) =>
+        typeof newValue === "function"
+          ? (newValue as (prevValue: T) => T)(prevValue)
+          : newValue
+      );
+      if (!skipParentLayout) {
+        // Trigger a layout recalculation in the RecyclerView
+        recyclerViewContext?.layout();
+      }
+    },
+    [recyclerViewContext]
+  );
+
+  return [state, setLayoutState];
+}

package/src/recyclerview/hooks/useMappingHelper.ts

@@ -0,0 +1,20 @@
+import { useCallback } from "react";
+
+import { useRecyclerViewContext } from "../RecyclerViewContextProvider";
+
+/**
+ * Returns a function that can help create a mapping key for the items.
+ * Useful when doing .map on items to create a list of components.
+ * Using this ensures that performance is optimal for FlashList
+ */
+export const useMappingHelper = () => {
+  const recyclerViewContext = useRecyclerViewContext();
+  const getMappingKey = useCallback(
+    (itemKey: string | number | bigint, index: number) => {
+      return recyclerViewContext ? index : itemKey;
+    },
+    [recyclerViewContext]
+  );
+
+  return { getMappingKey };
+};