react-native-list 1.0.1 → 2.0.0-alpha.2

package/README.md

@@ -1,49 +1,203 @@
-FlatList, VirtualizedList, SectionList for React-Native < 0.43
---
+# React Native List
 
-This repository mimics the latest changes in React Native 0.43.
+High-performance list for React Native.
 
-## Motivation
-Currently, React-Native@0.43 depends on React@16.0.0-alpha6 which isn't yet supported by many libraries like Enzyme etc. Although, this version of RN brings us amazing list views: FlatList, VirtualizedList & SectionList. So there is a choice either to use 0.43 with its awesome lists or use 0.42 and being able to test your applications with Enzyme. Well, I choose both ;)
+- 📱 True native [`UICollectionView`](https://developer.apple.com/documentation/uikit/uicollectionview) on iOS
+- 🤖 True native [`RecyclerView`](https://developer.android.com/develop/ui/views/layout/recyclerview) on android
+- 🔄 Synchronous rendering of react components using "worklet" function components
+- 🐎 Platform native animations out of the box for list item transitions
+- 📉 Low memory usage due to true native view recycling
 
-This package contains copied and adapted implementation of 0.43 list features to < 0.43 realms.
+https://github.com/user-attachments/assets/4a2684bf-7337-45e0-bb17-ee7b8a382943
 
 ## Installation
 
-- Install package using your favorite manager:
+> [!WARNING]
+> Using this library requires you to use [react-native-worklets **bundle mode**](https://docs.swmansion.com/react-native-worklets/docs/bundleMode/setup).
+>
+> - Please follow [the setup instructions of it first](https://docs.swmansion.com/react-native-worklets/docs/bundleMode/setup), and make sure your app works before using react-native-list!
+> - You need at least version 0.10.0!
 
-  ```sh
-  yarn add react-native-list
-  ```
-  or
-  ```sh
-  npm add react-native --save
-  ```
+Once that's out of the way, you can start with the regular setup of the library:
 
-- Add `react-native-list` to your `providesModuleNodeModules`:
+```sh
+bun add react-native-list@alpha
+```
+
+### Configuring Metro
+
+Simply wrap your config with `getReactNativeListMetroConfig` in `metro.config.js`:
+
+```js
+const { getDefaultConfig } = require("expo/metro-config");
+const {
+  getBundleModeMetroConfig,
+} = require("react-native-worklets/bundleMode");
+
+let config = getDefaultConfig(__dirname);
+config = getBundleModeMetroConfig(config);
+// ⚠️ Make sure to apply this _after_ the bundle mode metro config:
+config = getReactNativeListMetroConfig(config);
+module.exports = config;
+```
+
+> [!NOTE]
+> If you're using expo you need to make sure to enable inline requires in your metro config:
+>
+> ```js
+> const config = {
+>   transformer: {
+>     getTransformOptions: async () => ({
+>       transform: {
+>         // Bundle mode only works with inline support
+>         // See: https://github.com/software-mansion/react-native-reanimated/issues/8904
+>         inlineRequires: true,
+>       },
+>     }),
+>   },
+> };
+> ```
+>
+> If you don't see a `metro.config.js` in your project, see [expo's documentation on modifying metro](https://docs.expo.dev/guides/customizing-metro/).
+
+## Simple example
+
+```tsx
+import {  List, useLinearListLayout, useListDataSource } from "react-native-list";
+import type { ListItem, ListRenderers } from "react-native-list";
 
-  - If you don't have `rn-cli.config.js`, create `rn-cli.config.js` in the root directory of your project:
+type TextItem = ListItem<
+  // The type of your list item
+  "text",
+  // The data shape for that list item:
+  {
+    text: string;
+  }
+>;
 
-  ```js
-  module.exports = {
-    getProvidesModuleNodeModules() {
-      return [
-        'react-native',
-        'react-native-windows',
-        'react-native-list',
-      ];
+type ImageItem = ...
+
+type Items = TextItem | ImageItem
+
+// Provide render functions for your item types:
+const renderers: ListRenderers<Items> = {
+  text: {
+    renderItemWorklet: ({ item }) => {
+      "worklet"; // 👀 Note: our render function is a worklet!
+
+      return (
+        // Though being in a worklet, you can use any component you like in here
+        <View
+          style={{
+            justifyContent: "center",
+            paddingHorizontal: 16,
+            backgroundColor: "#f6f8fa",
+          }}
+        >
+          // Note: there are two phases: 1. View creation (without data), 2. binding data to the views
+          //       that's why item.data can be undefined because the native list is requesting to
+          //       create the view hierarchy, but without any data yet.
+          <Text>{item.data?.text}</Text>
+        </View>
+      );
     },
-  };
-  ```
+  },
+  image: ...
+};
 
-  - If you already have `rn-cli.config.js`, add `react-native-list` to your `getProvidesModuleNodeModules` function or copy it from the snippet above.
+export function ExampleList() {
+  const dataSource = useListDataSource<Items>({
+    data: [...],
+  });
+  const layout = useLinearListLayout({
+    itemSpacing: 8,
+  });
 
-## Usage
+  return (
+    <List
+      dataSource={dataSource}
+      layout={layout}
+      renderers={renderers}
+      style={{
+        flex: 1,
+      }}
+    />
+  );
+}
+```
 
-```js
-import { FlatList, VirtualizedList, SectionList } from 'react-native-list';
+## API
+
+XXXX TODO
+
+## Benchmark
+
+> Scrolling as fast as possible. Release build. iPhone 13 Pro.
+
+https://github.com/user-attachments/assets/aa7c2c41-b7ac-4d8b-9eb1-fd8b2feda4de
 
-// then use it like a regular react-native@0.43 components
+|           | Legend List | react-native-list |
+| --------- | ----------- | ----------------- |
+| FPS       | 60          | 60                |
+| Memory    | 86.89mb     | 86.88mb           |
+| Total CPU | 144.69%     | 185.93%           |
+| Can blank | yes         | no                |
+
+Performance difference is best described as this:
+
+- With react-native-list you will never get a blank. However, instead, you could see UI thread drop frames if your item rendering is too heavy.
+- With Legend List you may see blanks, however, its way less likely you will drop frames on the UI thread (instead your JS thread might be fully busy, but you won't really get to notice that on the UIs performance)
+
+## Known performance pitfalls
+
+- For iOS when using dynamically sized items, try to use `iosConfig.estimatedItemSize` to roughly specify how many items will be visible in the view port. This can help a lot with performance.
+- When specifying sizes for items use `useLinearListLayout({})` inset configs. Avoid setting a width in the styles that exceed the actual available view port width.
+- If you can, always provide item sizes upfront. With that the performance will be unbeatable.
+- In your item render function, when you have no item data yet it is tempting to return early with `null` or just an empty `<View />`. However, this is super bad for performance. There are two phases for native lists. First is view creation, where you're expected to create the view hierarchy for your item - just not with any data yet (so that any data could be bind to it). The second phase is actually binding data to the view. This will result in a simple "update props" operation on the native side instead of needing to create a new view hierarchy. Example:
+
+❌ **Bad**:
+
+```jsx
+renderItemWorklet: ({ item }) => {
+  "worklet";
+  if (item == null) return <View />
+  return (
+    <View>
+      <Image src={item.image}>
+      <Text>{item.userName}</Text>
+    </View>
+  )
+```
+
+✅ **Good**:
+
+```jsx
+renderItemWorklet: ({ item }) => {
+  "worklet";
+  return (
+    <View>
+      <Image src={item?.image}>
+      <Text>{item?.userName ?? ""}</Text>
+    </View>
+  )
 ```
 
-For more information, see [Better List Views in React Native](https://facebook.github.io/react-native/blog/2017/03/13/better-list-views.html).
+## Development
+
+First clone init the submodules:
+
+```sh
+git submodule update --init --recursive
+```
+
+Regenerate native Nitro specs after changing files in `src/specs` or `nitro.json`:
+
+```sh
+bun specs
+```
+
+Run TypeScript checks:
+
+```sh
+bun run typecheck
+```

package/ReactNativeList.podspec

@@ -0,0 +1,39 @@
+require "json"
+
+package = JSON.parse(File.read(File.join(__dir__, "package.json")))
+
+Pod::Spec.new do |s|
+  s.name         = "ReactNativeList"
+  s.version      = package["version"]
+  s.summary      = package["description"]
+  s.homepage     = package["homepage"]
+  s.license      = package["license"]
+  s.authors      = package["author"]
+
+  s.platforms    = { :ios => min_ios_version_supported, :visionos => 1.0 }
+  s.source       = { :git => "https://github.com/hannojg/react-native-list.git", :tag => "#{s.version}" }
+
+  s.source_files = [
+    # Implementation (Swift)
+    "ios/**/*.{h,swift}",
+    # Autolinking/Registration (Objective-C++)
+    "ios/**/*.{m,mm}",
+    # Implementation (C++ objects)
+    "cpp/**/*.{hpp,cpp}",
+  ]
+  s.public_header_files = "ios/**/*.h"
+  s.pod_target_xcconfig = {
+    "HEADER_SEARCH_PATHS" => [
+      '"$(PODS_TARGET_SRCROOT)/ReactCommon"',
+    ].join(' ')
+  }
+
+  load 'nitrogen/generated/ios/ReactNativeList+autolinking.rb'
+  add_nitrogen_files(s)
+
+  s.dependency 'React-jsi'
+  s.dependency 'React-callinvoker'
+  s.dependency 'DifferenceKit', '~> 1.3'
+  s.dependency "RNWorklets"
+  install_modules_dependencies(s)
+end

package/android/CMakeLists.txt

@@ -0,0 +1,48 @@
+project(ReactNativeList)
+cmake_minimum_required(VERSION 3.9.0)
+
+set (PACKAGE_NAME ReactNativeList)
+set (CMAKE_VERBOSE_MAKEFILE ON)
+set (CMAKE_CXX_STANDARD 20)
+
+# Define C++ library and add all sources
+add_library(${PACKAGE_NAME} SHARED
+        ../cpp/HybridUiManagerHelper.cpp
+        ../cpp/WorkletsUiCallInvoker.cpp
+        src/main/cpp/cpp-adapter.cpp
+        src/main/cpp/JHybridUiListModule.cpp
+)
+
+# Add Nitrogen specs :)
+include(${CMAKE_SOURCE_DIR}/../nitrogen/generated/android/ReactNativeList+autolinking.cmake)
+
+# Set up local includes
+include_directories(
+        "src/main/cpp"
+        "../cpp"
+)
+
+
+find_library(LOG_LIB log)
+find_package(react-native-worklets REQUIRED)       # <-- for Worklets
+
+# Worklets prefab headers transitively need these React Native internal headers
+# (they are PRIVATE in the worklets CMakeLists.txt, so not propagated via prefab)
+#TODO: THIS SHOULDN'T BE HARDCODED LIKE THIS!
+set(REACT_NATIVE_DIR "${CMAKE_SOURCE_DIR}/../../node_modules/react-native")
+target_include_directories(${PACKAGE_NAME} PRIVATE
+        "${REACT_NATIVE_DIR}/ReactCommon"
+        "${REACT_NATIVE_DIR}/ReactCommon/callinvoker"
+        "${REACT_NATIVE_DIR}/ReactCommon/runtimeexecutor"
+        "${REACT_NATIVE_DIR}/ReactCommon/jsiexecutor"
+        "${REACT_NATIVE_DIR}/ReactAndroid/src/main/jni/react/turbomodule"
+        "${REACT_NATIVE_DIR}/ReactCommon/react/nativemodule/core/ReactCommon"
+)
+
+# Link all libraries together
+target_link_libraries(
+        ${PACKAGE_NAME}
+        ${LOG_LIB}
+        android                                   # <-- Android core
+        react-native-worklets::worklets           # <-- Worklets C++ library
+)

package/android/build.gradle

@@ -0,0 +1,151 @@
+buildscript {
+  repositories {
+    google()
+    mavenCentral()
+  }
+
+  dependencies {
+    classpath "com.android.tools.build:gradle:8.13.2"
+  }
+}
+
+def reactNativeArchitectures() {
+  def value = rootProject.getProperties().get("reactNativeArchitectures")
+  return value ? value.split(",") : ["armeabi-v7a", "x86", "x86_64", "arm64-v8a"]
+}
+
+def isNewArchitectureEnabled() {
+  return rootProject.hasProperty("newArchEnabled") && rootProject.getProperty("newArchEnabled") == "true"
+}
+
+apply plugin: "com.android.library"
+apply plugin: 'org.jetbrains.kotlin.android'
+apply from: '../nitrogen/generated/android/ReactNativeList+autolinking.gradle'
+apply from: "./fix-prefab.gradle"
+
+if (isNewArchitectureEnabled()) {
+  apply plugin: "com.facebook.react"
+
+    react {
+            libraryName = "ReactNativeList"
+            codegenJavaPackageName = "com.hannojg.reactnativelist"
+            jsRootDir = file("../src")
+        }
+}
+
+def getExtOrDefault(name) {
+  return rootProject.ext.has(name) ? rootProject.ext.get(name) : project.properties["ReactNativeList_" + name]
+}
+
+def getExtOrIntegerDefault(name) {
+  return rootProject.ext.has(name) ? rootProject.ext.get(name) : (project.properties["ReactNativeList_" + name]).toInteger()
+}
+
+android {
+  namespace "com.hannojg.reactnativelist"
+  ndkVersion getExtOrDefault("ndkVersion")
+  compileSdkVersion getExtOrIntegerDefault("compileSdkVersion")
+
+  defaultConfig {
+    minSdkVersion getExtOrIntegerDefault("minSdkVersion")
+    targetSdkVersion getExtOrIntegerDefault("targetSdkVersion")
+    buildConfigField "boolean", "IS_NEW_ARCHITECTURE_ENABLED", isNewArchitectureEnabled().toString()
+
+    externalNativeBuild {
+      cmake {
+        cppFlags "-frtti -fexceptions -Wall -Wextra -fstack-protector-all"
+        arguments "-DANDROID_STL=c++_shared", "-DANDROID_SUPPORT_FLEXIBLE_PAGE_SIZES=ON"
+        abiFilters (*reactNativeArchitectures())
+
+        buildTypes {
+          debug {
+            cppFlags "-O1 -g"
+          }
+          release {
+            cppFlags "-O2"
+          }
+        }
+      }
+    }
+  }
+
+  externalNativeBuild {
+    cmake {
+      path "CMakeLists.txt"
+    }
+  }
+
+  packagingOptions {
+    excludes = [
+            "META-INF",
+            "META-INF/**",
+            "**/libc++_shared.so",
+            "**/libNitroModules.so",
+            "**/libfbjni.so",
+            "**/libjsi.so",
+            "**/libfolly_json.so",
+            "**/libfolly_runtime.so",
+            "**/libglog.so",
+            "**/libhermes.so",
+            "**/libhermes-executor-debug.so",
+            "**/libhermes_executor.so",
+            "**/libreactnative.so",
+            "**/libreactnativejni.so",
+            "**/libturbomodulejsijni.so",
+            "**/libreact_nativemodule_core.so",
+            "**/libjscexecutor.so"
+    ]
+  }
+
+  buildFeatures {
+    buildConfig true
+    prefab true
+  }
+
+  buildTypes {
+    release {
+      minifyEnabled false
+    }
+  }
+
+  lintOptions {
+    disable "GradleCompatible"
+  }
+
+  sourceSets {
+    main {
+      if (isNewArchitectureEnabled()) {
+        java.srcDirs += [
+          // React Codegen files
+          "${project.buildDir}/generated/source/codegen/java"
+        ]
+      }
+    }
+  }
+
+  compileOptions {
+    sourceCompatibility JavaVersion.VERSION_1_8
+    targetCompatibility JavaVersion.VERSION_1_8
+  }
+
+}
+
+repositories {
+  mavenCentral()
+  google()
+}
+
+
+dependencies {
+  // For < 0.71, this will be from the local maven repo
+  // For > 0.71, this will be replaced by `com.facebook.react:react-android:$version` by react gradle plugin
+  //noinspection GradleDynamicVersion
+  implementation "com.facebook.react:react-native:+"
+
+  // Add a dependency on NitroModules
+  implementation project(":react-native-nitro-modules")
+  implementation project(":react-native-worklets")
+
+  // RecyclerView
+  implementation "androidx.recyclerview:recyclerview:1.4.0"
+}

package/android/fix-prefab.gradle

@@ -0,0 +1,51 @@
+tasks.configureEach { task ->
+  // Make sure that we generate our prefab publication file only after having built the native library
+  // so that not a header publication file, but a full configuration publication will be generated, which
+  // will include the .so file
+
+  def prefabConfigurePattern = ~/^prefab(.+)ConfigurePackage$/
+  def matcher = task.name =~ prefabConfigurePattern
+  if (matcher.matches()) {
+    def variantName = matcher[0][1]
+    task.outputs.upToDateWhen { false }
+    task.dependsOn("externalNativeBuild${variantName}")
+  }
+}
+
+afterEvaluate {
+  def abis = reactNativeArchitectures()
+  rootProject.allprojects.each { proj ->
+    if (proj === rootProject) return
+
+    def dependsOnThisLib = proj.configurations.findAll { it.canBeResolved }.any { config ->
+      config.dependencies.any { dep ->
+        dep.group == project.group && dep.name == project.name
+      }
+    }
+    if (!dependsOnThisLib && proj != project) return
+
+    if (!proj.plugins.hasPlugin('com.android.application') && !proj.plugins.hasPlugin('com.android.library')) {
+      return
+    }
+
+    def variants = proj.android.hasProperty('applicationVariants') ? proj.android.applicationVariants : proj.android.libraryVariants
+    // Touch the prefab_config.json files to ensure that in ExternalNativeJsonGenerator.kt we will re-trigger the prefab CLI to
+    // generate a libnameConfig.cmake file that will contain our native library (.so).
+    // See this condition: https://cs.android.com/android-studio/platform/tools/base/+/mirror-goog-studio-main:build-system/gradle-core/src/main/java/com/android/build/gradle/tasks/ExternalNativeJsonGenerator.kt;l=207-219?q=createPrefabBuildSystemGlue
+    variants.all { variant ->
+      def variantName = variant.name
+      abis.each { abi ->
+        def searchDir = new File(proj.projectDir, ".cxx/${variantName}")
+        if (!searchDir.exists()) return
+        def matches = []
+        searchDir.eachDir { randomDir ->
+          def prefabFile = new File(randomDir, "${abi}/prefab_config.json")
+          if (prefabFile.exists()) matches << prefabFile
+        }
+        matches.each { prefabConfig ->
+          prefabConfig.setLastModified(System.currentTimeMillis())
+        }
+      }
+    }
+  }
+}

package/android/gradle.properties

@@ -0,0 +1,5 @@
+ReactNativeList_kotlinVersion=2.1.20
+ReactNativeList_minSdkVersion=23
+ReactNativeList_targetSdkVersion=36
+ReactNativeList_compileSdkVersion=36
+ReactNativeList_ndkVersion=27.1.12297006

package/android/src/main/AndroidManifest.xml

@@ -0,0 +1,2 @@
+<manifest xmlns:android="http://schemas.android.com/apk/res/android">
+</manifest>