@shopify/flash-list 2.0.1 → 2.0.2-rc.1

package/README.md

@@ -5,7 +5,7 @@
   <a href="https://discord.gg/k2gzABTfav">Discord</a> •
   <a href="https://shopify.github.io/flash-list/docs/">Getting started</a> •
   <a href="https://shopify.github.io/flash-list/docs/usage">Usage</a> •
-  <a href="https://shopify.github.io/flash-list/docs/fundamentals/performance">Performance</a> •
+  <a href="https://shopify.github.io/flash-list/docs/fundamentals/performant-components">Writing performant components</a> •
   <a href="https://shopify.github.io/flash-list/docs/known-issues">Known Issues</a>
 <br><br>
 
@@ -19,41 +19,25 @@ Swap from FlatList in seconds. Get instant performance.
 
 FlashList v2 has been rebuilt from the ground up for RN's new architecture and delivers fast performance, higher precision, and better ease of use compared to v1. We've achieved all this while moving to a JS-only solution! One of the key advantages of FlashList v2 is that it doesn't require any estimates. It also introduces several new features compared to v1. To know more about what's new in v2 click [here](https://shopify.github.io/flash-list/docs/v2-changes).
 
-> ⚠️ **IMPORTANT:** FlashList v2.x has been designed to be new architecture only and will not run on old architecture. If you're running on old architecture or using FlashList v1.x, you can access the documentation specific to v1 here: [FlashList v1 Documentation](https://shopify.github.io/flash-list/docs/1.x/).
+> ⚠️ **IMPORTANT:** FlashList v2.x has been designed to fully leverage the new architecture. **Old architecture will only be supported while FlashList v2 is in alpha/beta/rc and will be dropped once it's ready.** When run on old architecture, we just fall back to v1.x which doesn't have any of the new features.
 
-## Why use FlashList?
+### Is v2 production ready?
 
-### 🚀 Superior Performance
+Yes, please use one of the release candidates if you want to ship to production `2.0.0-rc.x`. While we can make some changes in the final version, we expect release candidates to be quite stable. Use the alpha track if you want to test new changes quickly and don't mind occasional bugs.
 
-- No more blank cells: FlashList uses view recycling to ensure smooth scrolling without visible blank areas.
-- Fast initial render: Optimized for quick first paint.
-- Efficient memory usage: Recycles views instead of destroying them, reducing memory overhead.
-- Supports view types: Great performance even if different types of components make up the list.
-- Dynamic sizes: Super fast and doesn't need any estimates.
+> ⚠️ **IMPORTANT:** FlashList v2.x's alpha track moves quickly and can have some issues. Please report any issues or edge cases you run into. We're actively working on testing and optimizing v2. We also highly recommend using it with RN 0.78+ for optimal performance.
 
-### 🎯 Developer Experience
+### Old architecture / FlashList v1
 
-- Drop-in replacement for FlatList: Simply change the component name - if you know FlatList, you already know FlashList.
-- No size estimates required in v2: Unlike v1, FlashList v2 automatically handles item sizing.
-- Type-safe: Full TypeScript support with comprehensive type definitions.
+If you're running on old architecture or using FlashList v1.x, you can access the documentation specific to v1 here: [FlashList v1 Documentation](https://shopify.github.io/flash-list/docs/1.x/).
 
-### 📱 Advanced Features
+### Web support
 
-- Masonry layout support: Create Pinterest-style layouts with varying item heights and column spans.
-- Maintain visible content position: Automatically handles content shifts when adding items (enabled by default in v2).
-- Multiple recycling pools: Optimizes performance for lists with different item types using `getItemType`.
-- Built for React Native's new architecture: FlashList v2 is designed specifically for the new architecture.
-
-### ⚡ Real-world Benefits
-
-- Reduced frame drops: Maintains 60 FPS even with complex item components.
-- Lower CPU usage: Efficient recycling reduces computational overhead.
-- Smoother scrolling: Predictable performance even with thousands of items.
-- JS-only solution in v2: No native dependencies, making it easier to maintain while delivering fast performance.
+FlashList v2 has web support. Most of the features should work but we're not actively testing it right now. If you run into an issue, please raise it on GitHub.
 
 ## Installation
 
-Add the package to your project via `yarn add @shopify/flash-list`.
+Add the package to your project via `yarn add @shopify/flash-list@rc` and run `pod install` in the `ios` directory.
 
 ## Usage
 
@@ -83,7 +67,93 @@ const MyList = () => {
 };
 ```
 
-To avoid common pitfalls, you can also follow these [`steps`](https://shopify.github.io/flash-list/docs/usage#migration-steps) for migrating from `FlatList`.
+To avoid common pitfalls, you can also follow these steps for migrating from `FlatList`, based on our own experience:
+
+1. Simply change from `FlatList` to `FlashList` and render the list.
+2. **Important**: Scan your [`renderItem`](https://shopify.github.io/flash-list/docs/usage/#renderitem) hierarchy for explicit `key` prop definitions and remove them. If you’re doing a `.map()` use our hook called [`useMappingHelper`](https://shopify.github.io/flash-list/docs/usage/#usemappinghelper).
+3. Check your [`renderItem`](https://shopify.github.io/flash-list/docs/usage/#renderitem) hierarchy for components that make use of `useState` and verify whether that state would need to be reset if a different item is passed to that component (see [Recycling](https://shopify.github.io/flash-list/docs/recycling))
+4. If your list has heterogenous views, pass their types to `FlashList` using [`getItemType`](https://shopify.github.io/flash-list/docs/usage/#getitemtype) prop to improve performance.
+5. Do not test performance with JS dev mode on. Make sure you’re in release mode. `FlashList` can appear slower while in dev mode due to a small render buffer.
+6. 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.
+
+## Other things to know
+
+- `keyExtractor` is important to prevent glitches due to item layout changes when going upwards. We highly recommend having a valid `keyExtractor` with v2.
+- `useLayoutState`: This is similar to `useState` but communicates the change in state to FlashList. It's useful if you want to resize a child component based on a local state. Item layout changes will still be detected using `onLayout` callback in the absence of `useLayoutState`, which might not look as smooth on a case-by-case basis.
+
+  ```jsx
+  import { useLayoutState } from "@shopify/flash-list";
+
+  const MyItem = ({ item }) => {
+    const [isExpanded, setIsExpanded] = useLayoutState(false);
+    const height = isExpanded ? 150 : 80;
+
+    return (
+      <Pressable onPress={() => setIsExpanded(!isExpanded)}>
+        <View style={{ height, padding: 16 }}>
+          <Text>{item.title}</Text>
+        </View>
+      </Pressable>
+    );
+  };
+  ```
+
+- `useRecyclingState`: Similar to `useState` but accepts a dependency array. On change of deps, the state gets reset without an additional `setState` call. Useful for maintaining local item state if really necessary. It also has the functionality of `useLayoutState` built in.
+
+  ```jsx
+  import { useRecyclingState } from "@shopify/flash-list";
+
+  const GridItem = ({ item }) => {
+    const [isExpanded, setIsExpanded] = useRecyclingState(
+      false,
+      [item.id],
+      () => {
+        // runs on reset. Can be used to reset scroll positions of nested horizontal lists
+      }
+    );
+    const height = isExpanded ? 100 : 50;
+
+    return (
+      <Pressable onPress={() => setIsExpanded(!isExpanded)}>
+        <View style={{ height, backgroundColor: item.color }}>
+          <Text>{item.title}</Text>
+        </View>
+      </Pressable>
+    );
+  };
+  ```
+
+- `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(item.id, index)}>{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.
 
 ## App / Playground
 

package/RNFlashList.podspec

@@ -0,0 +1,37 @@
+require 'json'
+
+package = JSON.parse(File.read(File.join(__dir__, 'package.json')))
+new_arch_enabled = ENV['RCT_NEW_ARCH_ENABLED']
+
+Pod::Spec.new do |s|
+  s.name             = 'RNFlashList'
+  s.version          = package['version']
+  s.summary          = package['description']
+  s.homepage         = package['homepage']
+  s.license          = package['license']
+  s.author           = package['author']
+  s.platforms        = { :ios => '11.0', :tvos => '12.0' }
+  s.source           = { git: 'https://github.com/shopify/flash-list.git', tag: "v#{s.version}" }
+  s.source_files     = 'ios/Sources/**/*'
+  s.requires_arc     = true
+  s.swift_version    = '5.0'
+
+  if new_arch_enabled
+    s.pod_target_xcconfig = {
+      'OTHER_SWIFT_FLAGS' => '-D RCT_NEW_ARCH_ENABLED',
+    }
+  end
+
+  # install_modules_dependencies is available since RN 0.71
+  if respond_to?(:install_modules_dependencies, true)
+    install_modules_dependencies(s)
+  else
+    s.dependency "React-Core"
+  end
+
+  # Tests spec
+  s.test_spec 'Tests' do |test_spec|
+    test_spec.source_files = 'ios/Tests/**/*'
+    test_spec.framework = 'XCTest'
+  end
+end

package/android/build.gradle

@@ -0,0 +1,89 @@
+def isNewArchitectureEnabled() {
+    return project.hasProperty("newArchEnabled") && project.newArchEnabled == "true"
+}
+
+apply plugin: 'com.android.library'
+
+apply plugin: 'kotlin-android'
+
+if (isNewArchitectureEnabled()) {
+    apply plugin: 'com.facebook.react'
+}
+
+def _ext = rootProject.ext
+
+def _reactNativeVersion = _ext.has('reactNative') ? _ext.reactNative : '+'
+def _compileSdkVersion = _ext.has('compileSdkVersion') ? _ext.compileSdkVersion : 30
+def _buildToolsVersion = _ext.has('buildToolsVersion') ? _ext.buildToolsVersion : '30.0.2'
+def _minSdkVersion = _ext.has('minSdkVersion') ? _ext.minSdkVersion : 21
+def _targetSdkVersion = _ext.has('targetSdkVersion') ? _ext.targetSdkVersion : 30
+def _junitVersion = _ext.has('junitVersion') ? _ext.junitVersion : '4.13.2'
+def _mockitoVersion = _ext.has('mockitoVersion') ? _ext.mockitoVersion : '3.2.0'
+def _androidTestRunnerVersion = _ext.has('androidTestRunnerVersion') ? _ext.androidTestRunnerVersion : '1.1.0'
+
+buildscript {
+    // buildscript is evaluated before any other task is executed, so this must be defined here
+    ext._kotlinVersion = rootProject.ext.has("kotlinVersion") ?  rootProject.ext.get('kotlinVersion') : '1.8.10'
+
+    repositories {
+        mavenCentral()
+    }
+
+    dependencies {
+        classpath("org.jetbrains.kotlin:kotlin-gradle-plugin:${_kotlinVersion}")
+    }
+}
+
+android {
+    compileSdkVersion _compileSdkVersion
+    buildToolsVersion _buildToolsVersion
+
+    // Conditional for compatibility with AGP <4.2.
+    if (project.android.hasProperty("namespace")) {
+        namespace = "com.shopify.reactnative.flash_list"
+    }
+
+    compileOptions {
+        sourceCompatibility JavaVersion.VERSION_1_8
+        targetCompatibility JavaVersion.VERSION_1_8
+    }
+
+    sourceSets {
+        main.java.srcDirs += 'src/main/kotlin'
+        debug.java.srcDirs += 'src/debug/kotlin'
+        test.java.srcDirs += 'src/test/kotlin'
+        androidTest.java.srcDirs += 'src/androidTest/kotlin'
+
+        if (!isNewArchitectureEnabled()) {
+            main.java.srcDirs += ['src/paper/java']
+        }
+    }
+
+    defaultConfig {
+        minSdkVersion _minSdkVersion
+        targetSdkVersion _targetSdkVersion
+        buildConfigField "boolean", "IS_NEW_ARCHITECTURE_ENABLED", isNewArchitectureEnabled().toString()
+        versionCode 1
+        versionName "1.0"
+        testInstrumentationRunner = "androidx.test.runner.AndroidJUnitRunner"
+    }
+
+    lintOptions {
+        abortOnError false
+    }
+
+    testOptions {
+      unitTests.returnDefaultValues = true
+    }
+}
+
+dependencies {
+    compileOnly "com.facebook.react:react-native:${_reactNativeVersion}"
+    implementation "org.jetbrains.kotlin:kotlin-stdlib-jdk7:${_kotlinVersion}"
+    testImplementation "junit:junit:${_junitVersion}"
+    testImplementation "org.mockito.kotlin:mockito-kotlin:${_mockitoVersion}"
+    testImplementation "org.mockito:mockito-inline:${_mockitoVersion}"
+    testImplementation 'com.google.code.gson:gson:2.8.9'
+    androidTestImplementation("androidx.test:runner:${_androidTestRunnerVersion}")
+    androidTestImplementation("androidx.test:rules:${_androidTestRunnerVersion}")
+}

package/android/src/main/AndroidManifest.xml

@@ -0,0 +1,3 @@
+<manifest xmlns:android="http://schemas.android.com/apk/res/android"
+          package="com.shopify.reactnative.flash_list">
+</manifest>

package/android/src/main/kotlin/com/shopify/reactnative/flash_list/AutoLayoutShadow.kt

@@ -0,0 +1,105 @@
+package com.shopify.reactnative.flash_list
+
+class AutoLayoutShadow {
+    var horizontal: Boolean = false
+    var scrollOffset: Int = 0
+    var offsetFromStart: Int = 0
+    var windowSize: Int = 0
+    var renderOffset = 0
+
+    var blankOffsetAtStart = 0 // Tracks blank area from the top
+    var blankOffsetAtEnd = 0 // Tracks blank area from the bottom
+
+    var lastMaxBoundOverall = 0 // Tracks where the last pixel is drawn in the overall
+
+    private var lastMaxBound = 0 // Tracks where the last pixel is drawn in the visible window
+    private var lastMinBound = 0 // Tracks where first pixel is drawn in the visible window
+
+    /** Checks for overlaps or gaps between adjacent items and then applies a correction (Only Grid layouts with varying spans)
+     * Performance: RecyclerListView renders very small number of views and this is not going to trigger multiple layouts on Android side. Not expecting any major perf issue. */
+    fun clearGapsAndOverlaps(sortedItems: Array<CellContainer>) {
+        var maxBound = 0
+        var minBound = Int.MAX_VALUE
+        var maxBoundNeighbour = 0
+        lastMaxBoundOverall = 0
+        for (i in 0 until sortedItems.size - 1) {
+            val cell = sortedItems[i]
+            val neighbour = sortedItems[i + 1]
+            // Only apply correction if the next cell is consecutive.
+            val isNeighbourConsecutive = neighbour.index == cell.index + 1
+            if (isWithinBounds(cell) || isWithinBounds(neighbour)) {
+                if (!horizontal) {
+                    maxBound = kotlin.math.max(maxBound, cell.bottom);
+                    minBound = kotlin.math.min(minBound, cell.top);
+                    maxBoundNeighbour = maxBound
+                    if (isNeighbourConsecutive) {
+                        if (cell.left < neighbour.left) {
+                            if (cell.right != neighbour.left) {
+                                neighbour.right = cell.right + neighbour.width
+                                neighbour.left = cell.right
+                            }
+                            if (cell.top != neighbour.top) {
+                                neighbour.bottom = cell.top + neighbour.height
+                                neighbour.top = cell.top
+                            }
+                        } else {
+                            neighbour.bottom = maxBound + neighbour.height
+                            neighbour.top = maxBound
+                        }
+                    }
+                    if (isWithinBounds(neighbour)) {
+                        maxBoundNeighbour = kotlin.math.max(maxBound, neighbour.bottom)
+                    }
+                } else {
+                    maxBound = kotlin.math.max(maxBound, cell.right);
+                    minBound = kotlin.math.min(minBound, cell.left);
+                    maxBoundNeighbour = maxBound
+                    if (isNeighbourConsecutive) {
+                        if (cell.top < neighbour.top) {
+                            if (cell.bottom != neighbour.top) {
+                                neighbour.bottom = cell.bottom + neighbour.height
+                                neighbour.top = cell.bottom
+                            }
+                            if (cell.left != neighbour.left) {
+                                neighbour.right = cell.left + neighbour.width
+                                neighbour.left = cell.left
+                            }
+                        } else {
+                            neighbour.right = maxBound + neighbour.width
+                            neighbour.left = maxBound
+                        }
+                    }
+                    if (isWithinBounds(neighbour)) {
+                        maxBoundNeighbour = kotlin.math.max(maxBound, neighbour.right)
+                    }
+                }
+            }
+            lastMaxBoundOverall = kotlin.math.max(lastMaxBoundOverall, if (horizontal) cell.right else cell.bottom)
+            lastMaxBoundOverall = kotlin.math.max(lastMaxBoundOverall, if (horizontal) neighbour.right else neighbour.bottom)
+        }
+        lastMaxBound = maxBoundNeighbour
+        lastMinBound = minBound
+    }
+
+    /** Offset provided by react can be one frame behind the real one, it's important that this method is called with offset taken directly from
+     * scrollview object */
+    fun computeBlankFromGivenOffset(actualScrollOffset: Int, distanceFromWindowStart: Int, distanceFromWindowEnd: Int): Int {
+        val actualScrollOffset = actualScrollOffset - offsetFromStart;
+        blankOffsetAtStart = lastMinBound - actualScrollOffset - distanceFromWindowStart
+        blankOffsetAtEnd = actualScrollOffset + windowSize - renderOffset - lastMaxBound - distanceFromWindowEnd
+        return kotlin.math.max(blankOffsetAtStart, blankOffsetAtEnd)
+    }
+
+    /** It's important to avoid correcting views outside the render window. An item that isn't being recycled might still remain in the view tree. If views outside get considered then gaps between
+     * unused items will cause algorithm to fail.*/
+    private fun isWithinBounds(cell: CellContainer): Boolean {
+        val scrollOffset = scrollOffset - offsetFromStart;
+        return if (!horizontal) {
+            (cell.top >= (scrollOffset - renderOffset) || cell.bottom >= (scrollOffset - renderOffset)) &&
+                    (cell.top <= scrollOffset + windowSize || cell.bottom <= scrollOffset + windowSize)
+        } else {
+            (cell.left >= (scrollOffset - renderOffset) || cell.right >= (scrollOffset - renderOffset)) &&
+                    (cell.left <= scrollOffset + windowSize || cell.right <= scrollOffset + windowSize)
+        }
+    }
+}

package/android/src/main/kotlin/com/shopify/reactnative/flash_list/AutoLayoutView.kt

@@ -0,0 +1,158 @@
+package com.shopify.reactnative.flash_list
+
+import android.content.Context
+import android.graphics.Canvas
+import android.util.DisplayMetrics
+import android.util.Log
+import android.view.View
+import android.view.ViewGroup
+import android.widget.HorizontalScrollView
+import android.widget.ScrollView
+import com.facebook.react.bridge.Arguments
+import com.facebook.react.bridge.ReactContext
+import com.facebook.react.bridge.WritableMap
+import com.facebook.react.uimanager.UIManagerHelper
+import com.facebook.react.uimanager.events.EventDispatcher
+import com.facebook.react.uimanager.events.RCTEventEmitter
+import com.facebook.react.views.view.ReactViewGroup
+
+
+/** Container for all RecyclerListView children. This will automatically remove all gaps and overlaps for GridLayouts with flexible spans.
+ * Note: This cannot work for masonry layouts i.e, pinterest like layout */
+class AutoLayoutView(context: Context) : ReactViewGroup(context) {
+    val alShadow = AutoLayoutShadow()
+    var enableInstrumentation = false
+    var disableAutoLayout = false
+
+    var pixelDensity = 1.0;
+
+    /** Overriding draw instead of onLayout. RecyclerListView uses absolute positions for each and every item which means that changes in child layouts may not trigger onLayout on this container. The same layout
+     * can still cause views to overlap. Therefore, it makes sense to override draw to do correction. */
+    override fun dispatchDraw(canvas: Canvas) {
+        fixLayout()
+        fixFooter()
+        super.dispatchDraw(canvas)
+
+        val parentScrollView = getParentScrollView()
+        if (enableInstrumentation && parentScrollView != null) {
+            /** Since we need to call this method with scrollOffset on the UI thread and not with the one react has we're querying parent's parent
+            directly which will be a ScrollView. If it isn't reported values will be incorrect but the component will not break.
+            RecyclerListView is expected not to change the hierarchy of children. */
+
+            val scrollContainerSize = if (alShadow.horizontal) parentScrollView.width else parentScrollView.height
+
+            val scrollOffset = if (alShadow.horizontal) parentScrollView.scrollX else parentScrollView.scrollY
+
+            val startOffset = if (alShadow.horizontal) left else top
+            val endOffset = if (alShadow.horizontal) right else bottom
+
+            val distanceFromWindowStart = kotlin.math.max(startOffset - scrollOffset, 0)
+            val distanceFromWindowEnd = kotlin.math.max(scrollOffset + scrollContainerSize - endOffset, 0)
+
+            alShadow.computeBlankFromGivenOffset(scrollOffset, distanceFromWindowStart, distanceFromWindowEnd)
+            emitBlankAreaEvent()
+        }
+    }
+
+    /** Sorts views by index and then invokes clearGaps which does the correction.
+     * Performance: Sort is needed. Given relatively low number of views in RecyclerListView render tree this should be a non issue.*/
+    private fun fixLayout() {
+        if (childCount > 1 && !disableAutoLayout) {
+            val positionSortedViews: Array<CellContainer> = Array(childCount) {
+                val child = getChildAt(it)
+                if (child is CellContainer) {
+                    child
+                } else {
+                    throw IllegalStateException("CellRendererComponent outer view should always be CellContainer. Learn more here: https://shopify.github.io/flash-list/docs/usage#cellrenderercomponent.")
+                }
+            }
+            positionSortedViews.sortBy { it.index }
+            alShadow.offsetFromStart = if (alShadow.horizontal) left else top
+            alShadow.clearGapsAndOverlaps(positionSortedViews)
+        }
+    }
+
+    /** Fixes footer position along with rest of the items */
+    private fun fixFooter() {
+        val parentScrollView = getParentScrollView()
+        if (disableAutoLayout || parentScrollView == null) {
+            return
+        }
+        val isAutoLayoutEndVisible = if (alShadow.horizontal) right <= parentScrollView.width else bottom <= parentScrollView.height
+        if (!isAutoLayoutEndVisible) {
+            return
+        }
+        val autoLayoutParent = parent as? View
+        val footer = getFooter();
+        val diff = getFooterDiff()
+        if (diff == 0 || footer == null || autoLayoutParent == null) {
+            return
+        }
+
+        if (alShadow.horizontal) {
+            footer.offsetLeftAndRight(diff)
+            right += diff
+            autoLayoutParent.right += diff
+        } else {
+            footer.offsetTopAndBottom(diff)
+            bottom += diff
+            autoLayoutParent.bottom += diff
+        }
+    }
+
+    private fun getFooterDiff(): Int {
+        if (childCount == 0) {
+            alShadow.lastMaxBoundOverall = 0
+        } else if (childCount == 1) {
+            val firstChild = getChildAt(0)
+            alShadow.lastMaxBoundOverall = if (alShadow.horizontal) {
+                firstChild.right
+            } else {
+                firstChild.bottom
+            }
+        }
+        val autoLayoutEnd = if (alShadow.horizontal) right - left else bottom - top
+        return alShadow.lastMaxBoundOverall - autoLayoutEnd
+    }
+
+    private fun getFooter(): View? {
+        return (parent as? ViewGroup)?.let {
+            for (i in 0 until it.childCount) {
+                val view = it.getChildAt(i)
+                if (view is CellContainer && view.index == -1) {
+                    return@let view
+                }
+            }
+            return@let null
+        }
+    }
+
+    private fun getParentScrollView(): View? {
+        var autoLayoutParent = parent;
+        while (autoLayoutParent != null) {
+            if (autoLayoutParent is ScrollView || autoLayoutParent is HorizontalScrollView) {
+                return autoLayoutParent as View
+            }
+            autoLayoutParent = autoLayoutParent.parent;
+        }
+        return null
+    }
+
+
+    private fun emitBlankAreaEvent() {
+        val eventDispatcher: EventDispatcher? =
+            UIManagerHelper.getEventDispatcherForReactTag(context as ReactContext, id)
+
+        if (eventDispatcher != null) {
+            val surfaceId = UIManagerHelper.getSurfaceId(context as ReactContext)
+            eventDispatcher.dispatchEvent(
+                BlankAreaEvent(
+                    surfaceId,
+                    viewTag = id,
+                    offsetStart = alShadow.blankOffsetAtStart / pixelDensity,
+                    offsetEnd = alShadow.blankOffsetAtEnd / pixelDensity
+                )
+            )
+        }
+    }
+}

package/android/src/main/kotlin/com/shopify/reactnative/flash_list/AutoLayoutViewManager.kt

@@ -0,0 +1,70 @@
+package com.shopify.reactnative.flash_list
+
+import com.facebook.react.module.annotations.ReactModule
+import com.facebook.react.uimanager.ThemedReactContext
+import com.facebook.react.uimanager.annotations.ReactProp
+import com.facebook.react.uimanager.ViewGroupManager
+import com.facebook.react.uimanager.ViewManagerDelegate
+import com.facebook.react.viewmanagers.AutoLayoutViewManagerDelegate
+import com.facebook.react.viewmanagers.AutoLayoutViewManagerInterface
+import kotlin.math.roundToInt
+
+/** ViewManager for AutoLayoutView - Container for all RecyclerListView children. Automatically removes all gaps and overlaps for GridLayouts with flexible spans.
+ * Note: This cannot work for masonry layouts i.e, pinterest like layout */
+@ReactModule(name = AutoLayoutViewManager.REACT_CLASS)
+class AutoLayoutViewManager: ViewGroupManager<AutoLayoutView>(), AutoLayoutViewManagerInterface<AutoLayoutView> {
+    private val mDelegate: AutoLayoutViewManagerDelegate<AutoLayoutView, AutoLayoutViewManager> =
+        AutoLayoutViewManagerDelegate(this)
+
+    companion object {
+        const val REACT_CLASS = "AutoLayoutView"
+    }
+
+    override fun getName(): String {
+        return REACT_CLASS
+    }
+
+    override fun getDelegate(): ViewManagerDelegate<AutoLayoutView> = mDelegate
+
+    override fun createViewInstance(context: ThemedReactContext): AutoLayoutView {
+        return AutoLayoutView(context).also { it.pixelDensity = context.resources.displayMetrics.density.toDouble() }
+    }
+
+    override fun getExportedCustomDirectEventTypeConstants() = mutableMapOf(
+        "onBlankAreaEvent" to mutableMapOf("registrationName" to "onBlankAreaEvent"),
+    )
+
+    @ReactProp(name = "horizontal")
+    override fun setHorizontal(view: AutoLayoutView, isHorizontal: Boolean) {
+        view.alShadow.horizontal = isHorizontal
+    }
+
+    @ReactProp(name = "disableAutoLayout")
+    override fun setDisableAutoLayout(view: AutoLayoutView, disableAutoLayout: Boolean) {
+        view.disableAutoLayout = disableAutoLayout
+    }
+
+    @ReactProp(name = "scrollOffset")
+    override fun setScrollOffset(view: AutoLayoutView, scrollOffset: Double) {
+        view.alShadow.scrollOffset = convertToPixelLayout(scrollOffset, view.pixelDensity)
+    }
+
+    @ReactProp(name = "windowSize")
+    override fun setWindowSize(view: AutoLayoutView, windowSize: Double) {
+        view.alShadow.windowSize = convertToPixelLayout(windowSize, view.pixelDensity)
+    }
+
+    @ReactProp(name = "renderAheadOffset")
+    override fun setRenderAheadOffset(view: AutoLayoutView, renderOffset: Double) {
+        view.alShadow.renderOffset = convertToPixelLayout(renderOffset, view.pixelDensity)
+    }
+
+    @ReactProp(name = "enableInstrumentation")
+    override fun setEnableInstrumentation(view: AutoLayoutView, enableInstrumentation: Boolean) {
+        view.enableInstrumentation = enableInstrumentation
+    }
+
+    private fun convertToPixelLayout(dp: Double, density: Double): Int {
+        return (dp * density).roundToInt()
+    }
+}

package/android/src/main/kotlin/com/shopify/reactnative/flash_list/BlankAreaEvent.kt

@@ -0,0 +1,29 @@
+@file:Suppress("DEPRECATION") // We want to use RCTEventEmitter for interop purposes
+package com.shopify.reactnative.flash_list
+
+import com.facebook.react.bridge.Arguments
+import com.facebook.react.bridge.WritableMap
+import com.facebook.react.uimanager.events.Event
+import com.facebook.react.uimanager.events.RCTEventEmitter
+
+class BlankAreaEvent(
+    surfaceId: Int,
+    viewTag: Int,
+    private val offsetStart: Double,
+    private val offsetEnd: Double
+): Event<BlankAreaEvent>(surfaceId, viewTag) {
+    override fun getEventName() = EVENT_NAME
+
+    override fun getEventData(): WritableMap = Arguments.createMap().apply {
+        putDouble("offsetStart", offsetStart)
+        putDouble("offsetEnd", offsetEnd)
+    }
+
+    override fun dispatch(rctEventEmitter: RCTEventEmitter) {
+        rctEventEmitter.receiveEvent(viewTag, eventName, getEventData())
+    }
+
+    companion object {
+        const val EVENT_NAME: String = "onBlankAreaEvent"
+    }
+}

package/android/src/main/kotlin/com/shopify/reactnative/flash_list/CellContainer.java

@@ -0,0 +1,16 @@
+package com.shopify.reactnative.flash_list;
+
+public interface CellContainer {
+    void setIndex(int value);
+    int getIndex();
+    void setLeft(int value);
+    int getLeft();
+    void setTop(int value);
+    int getTop();
+    void setRight(int value);
+    int getRight();
+    void setBottom(int value);
+    int getBottom();
+    int getHeight();
+    int getWidth();
+}