Add new useMappingHelper hook for solving .map

Author: naqvitalha

README.md

@@ -181,6 +181,36 @@ const MyList = () => {
   };
   ```
 
+- `useMappingHelper`: Returns a function that helps create optimal mapping keys for items when using `.map()` in your render methods. Using this ensures optimized recycling and performance for FlashList.
+
+  ```jsx
+  import { useMappingHelper } from "@shopify/flash-list";
+
+  const MyComponent = ({ items }) => {
+    const { getMappingKey } = useMappingHelper();
+
+    return (
+      <FlashList
+        data={items}
+        renderItem={({ item }) => <ItemComponent item={item} />}
+      />
+    );
+  };
+
+  // When mapping over items inside components:
+  const NestedList = ({ items }) => {
+    const { getMappingKey } = useMappingHelper();
+
+    return (
+      <View>
+        {items.map((item, index) => (
+          <Text key={getMappingKey(index, item.id)}>{item.title}</Text>
+        ))}
+      </View>
+    );
+  };
+  ```
+
 - If you're nesting horizontal FlashLists in vertical lists, we highly recommend the vertical list to be FlashList too. We have optimizations to wait for child layout to complete which can improve load times.
 - For chat apps, consider increasing drawDistance to 500 or higher if you're going to add a lot of items to the top. Higher drawDistance can remove some flickers. 500-1000 for chat can be okay. We would like to hear from you if you run into issues.
 - Memoizing props passed to FlashList is more important in v2. v1 was more selective about updating items, but this was often perceived as a bug by developers. We will not follow that approach and will instead allow developers to ensure that props are memoized. We will stop re-renders of children wherever it is obvious.

documentation/docs/fundamentals/usage.md

@@ -617,6 +617,67 @@ const GridItem = ({ item }) => {
 };
 ```
 
+### useMappingHelper
+
+```tsx
+const { getMappingKey } = useMappingHelper();
+```
+
+Returns a function that helps create a mapping key for items when using `.map()` in your render methods. Using this ensures that performance is optimal for FlashList by providing consistent keys that work with the recycling system.
+
+The `getMappingKey` function takes two parameters:
+
+- `index`: The index of the item in the array
+- `itemKey`: A unique identifier for the item (string, number, or bigint)
+
+It returns the appropriate key value to use in the `key` prop based on the current context.
+
+**Basic usage:**
+
+```jsx
+import { useMappingHelper } from "@shopify/flash-list";
+
+const MyComponent = ({ items }) => {
+  const { getMappingKey } = useMappingHelper();
+
+  return (
+    <View>
+      {items.map((item, index) => (
+        <Text key={getMappingKey(index, item.id)}>{item.title}</Text>
+      ))}
+    </View>
+  );
+};
+```
+
+**When to use it:**
+
+- When mapping over arrays to create lists of components inside FlashList items
+- When building nested components that render multiple items from an array
+- To ensure consistent key generation that works well with FlashList's recycling system
+
+```jsx
+import { useMappingHelper } from "@shopify/flash-list";
+
+const ProductList = ({ products }) => {
+  const { getMappingKey } = useMappingHelper();
+
+  return (
+    <View style={styles.container}>
+      <Text style={styles.title}>Featured Products</Text>
+      <View style={styles.grid}>
+        {products.map((product, index) => (
+          <ProductCard
+            key={getMappingKey(index, product.id)}
+            product={product}
+          />
+        ))}
+      </View>
+    </View>
+  );
+};
+```
+
 # FlashList methods
 
 ### `prepareForLayoutAnimationRender()`

src/index.ts

@@ -45,6 +45,7 @@ export {
 } from "./MasonryFlashList";
 export { useLayoutState } from "./recyclerview/hooks/useLayoutState";
 export { useRecyclingState } from "./recyclerview/hooks/useRecyclingState";
+export { useMappingHelper } from "./recyclerview/hooks/useMappingHelper";
 export { JSFPSMonitor, JSFPSResult } from "./benchmark/JSFPSMonitor";
 export { autoScroll, Cancellable } from "./benchmark/AutoScrollHelper";
 export { default as ViewToken } from "./viewability/ViewToken";

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(
+    (index: number, itemKey: string | number | bigint) => {
+      return recyclerViewContext ? index : itemKey;
+    },
+    [recyclerViewContext]
+  );
+
+  return { getMappingKey };
+};