react-native-nitro-list 0.0.1 → 0.1.1

package/README.md

@@ -1,29 +1,263 @@
-# react-native-nitro-list
+# 🚀 NitroList (RecyclerList)
 
-react-native-nitro-list is a react native package built with Nitro
+**Nitro-powered RecyclerList for React Native New Architecture**
 
-[![Version](https://img.shields.io/npm/v/react-native-nitro-list.svg)](https://www.npmjs.com/package/react-native-nitro-list)
-[![Downloads](https://img.shields.io/npm/dm/react-native-nitro-list.svg)](https://www.npmjs.com/package/react-native-nitro-list)
-[![License](https://img.shields.io/npm/l/react-native-nitro-list.svg)](https://github.com/patrickkabwe/react-native-nitro-list/LICENSE)
+A high-performance, recycler-based list built from the ground up for  
+**Fabric + Nitro (JSI)** — no legacy bridge, no hidden overhead.
 
-## Requirements
+---
 
-- React Native v0.76.0 or higher
-- Node 18.0.0 or higher
+## Preview
 
-> [!IMPORTANT]  
-> To Support `Nitro Views` you need to install React Native version v0.78.0 or higher.
+![NitroList Preview](./NitroList.png)
 
-## Installation
+**Blazing-fast • Deterministic • Architecture-correct**
+
+Built for teams that care about **FPS, memory stability, and correctness**.
+
+---
+
+## ✨ What is NitroList?
+
+**NitroList** (public component: `RecyclerList`) is a **FlashList-class virtualized list**, designed with a stricter architectural philosophy:
+
+- New Architecture only (Fabric)
+- Nitro / JSI friendly
+- True view recycling
+- Explicit layout ownership
+- Predictable memory usage
+
+NitroList is **not a beginner abstraction**.  
+It is **infrastructure-level UI**, meant for performance-critical React Native apps.
+
+---
+
+## 🧠 Core Design Principles
+
+NitroList enforces strict separation of responsibilities:
+
+| Responsibility | Owner |
+|----------------|------|
+| Layout truth | MutableLinearLayout (outside React) |
+| Windowing | Pure binary-search windowing |
+| Recycling | Physical cell reuse |
+| Rendering | React (placement only) |
+| Observers | Viewability / Prefetch (read-only) |
+
+### Key invariants
+
+- React never owns layout state  
+- React never decides what exists  
+- Layout is a mutable truth outside React  
+
+This separation is the foundation of stable performance.
+
+---
+
+## ⚡ Why NitroList over FlatList?
+
+### Problems with FlatList
+
+- Recreates views instead of recycling
+- Layout is implicit and fragile
+- Memory grows with scroll depth
+- Blank cells under pressure
+- Designed for the legacy bridge
+
+### NitroList Advantages
+
+- True view recycling
+- Absolute positioning (no reflow)
+- Deterministic windowing
+- Stable memory footprint
+- No legacy bridge usage
+- Architecture designed for scale
+
+---
+
+## 🆚 NitroList vs FlashList
+
+| Feature | FlashList v2 | NitroList |
+|------|-------------|-----------|
+| New Architecture | Yes | Yes |
+| Legacy bridge | No | No |
+| Recycler model | Yes | Yes |
+| Layout ownership | Internal | Explicit & controllable |
+| Nitro / JSI ready | No | Yes |
+| Deterministic memory | Partial | Strict |
+| Architecture clarity | Medium | Very high |
+
+### Why NitroList Exists
+
+FlashList v2 is excellent — but:
+
+- Layout is internal and opaque
+- Hard to integrate with Nitro / JSI native logic
+- Less control over measurement and relayout
+- Harder to reason about invariants
+
+NitroList is built for:
+
+- Native-heavy apps
+- Nitro / JSI pipelines
+- Custom layout engines
+- Predictable performance at scale
+
+---
+
+## 🧩 Features
+
+### Implemented
+
+- Recycler-based rendering
+- Binary-search windowing
+- Adaptive render buffer
+- Deterministic layout engine
+- Viewability tracking
+- Prefetch hooks
+- Full TypeScript safety
+- Unit-tested windowing logic
+
+### Partially Implemented
+
+- Dynamic measurement pipeline
+- Incremental relayout
+
+### Planned
+
+- scrollToIndex
+- Sticky headers
+- Masonry layout
+- Native measurement via Nitro
+- Benchmark harness
+
+---
+
+## 📦 Installation
 
 ```bash
-npm install react-native-nitro-list react-native-nitro-modules
+npm install react-native-nitro-list
 ```
 
-## Credits
+> Requires React Native New Architecture  
+> NitroList will not run on the legacy bridge.
+
+---
+
+## 🧑‍💻 Usage
+
+### Basic Usage
+
+```tsx
+import { RecyclerList } from 'react-native-nitro-list'
+
+<RecyclerList
+  containerWidth={width}
+  itemCount={10000}
+  estimatedItemHeight={80}
+  renderItem={(index) => <Row index={index} />}
+/>
+```
+
+### Fixed Heights
+
+```tsx
+<RecyclerList
+  containerWidth={width}
+  itemHeights={heights}
+  renderItem={renderItem}
+/>
+```
+
+---
+
+## 👀 Viewability
+
+```tsx
+<RecyclerList
+  onViewableItemsChanged={({ viewableItems, changed }) => {
+    console.log(viewableItems, changed)
+  }}
+/>
+```
+
+- Percentage-based visibility
+- Deterministic enter / exit events
+- Zero layout mutation
+
+---
+
+## ⚡ Prefetching
+
+```tsx
+<RecyclerList
+  onPrefetch={(indices) => {
+    preloadData(indices)
+  }}
+/>
+```
+
+- Runs ahead of the visible window
+- Deduplicated
+- Safe and repeatable
+- Observer-only (never mutates layout)
+
+---
+
+## 🧪 Testing Philosophy
+
+NitroList focuses on pure logic tests:
+
+- Windowing correctness
+- Buffer expansion
+- Boundary conditions
+- Off-by-one safety
+
+No flaky UI snapshot tests.  
+No renderer-dependent assertions.
+
+---
+
+## 🧠 When Should You Use NitroList?
+
+### Use NitroList if:
+
+- You are on Fabric / New Architecture
+- You care about memory stability
+- You plan to integrate Nitro / JSI
+- You want explicit control over layout
+- You are building performance-critical screens
+
+### Don’t use NitroList if:
+
+- You need legacy bridge support
+- You want a beginner-friendly abstraction
+- Your lists are small (less than 500 items)
+- FlatList performance is already sufficient
+
+---
+
+## 🗺️ Roadmap
+
+- v0.2 → measurement pipeline
+- v0.3 → scrollToIndex
+- v0.4 → native measurement (Nitro)
+- v1.0 → production-hardened API
+
+---
+
+## 🤝 Philosophy
+
+NitroList optimizes for:
+
+- Correctness over magic
+- Predictability over heuristics
+- Architecture over convenience
+
+This library is for engineers who value control.
 
-Bootstrapped with [create-nitro-module](https://github.com/patrickkabwe/create-nitro-module).
+---
 
-## Contributing
+## 📄 License
 
-Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.
+MIT

package/android/build.gradle

@@ -130,13 +130,14 @@ repositories {
 
 
 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
+  // React Native
   implementation "com.facebook.react:react-native:+"
 
-  // Add a dependency on NitroModules
+  // Nitro JSI
   implementation project(":react-native-nitro-modules")
+
+  // ✅ REQUIRED: RecyclerView
+  implementation "androidx.recyclerview:recyclerview:1.3.2"
 }
 
 if (isNewArchitectureEnabled()) {

package/android/src/main/java/com/nitrolist/HybridNitroRecyclerView.kt

@@ -0,0 +1,26 @@
+package com.nitrolist
+
+import android.content.Context
+import androidx.recyclerview.widget.LinearLayoutManager
+import androidx.recyclerview.widget.RecyclerView
+
+/**
+ * Native RecyclerView host.
+ * This is a real Android RecyclerView – no Nitro codegen involved.
+ */
+class HybridNitroRecyclerView(context: Context) : RecyclerView(context) {
+
+  init {
+    layoutManager = LinearLayoutManager(context)
+    itemAnimator = null
+    setHasFixedSize(true)
+  }
+
+  fun setItemCount(count: Int) {
+    if (adapter == null) {
+      adapter = NitroRecyclerAdapter(count)
+    } else {
+      (adapter as NitroRecyclerAdapter).updateCount(count)
+    }
+  }
+}

package/android/src/main/java/com/nitrolist/HybridNitroRecyclerViewManager.kt

@@ -0,0 +1,29 @@
+package com.nitrolist
+
+import com.facebook.react.uimanager.SimpleViewManager
+import com.facebook.react.uimanager.ThemedReactContext
+import com.facebook.react.uimanager.annotations.ReactProp
+
+/**
+ * Standard ViewManager.
+ * Fabric compatible, handwritten.
+ */
+class HybridNitroRecyclerViewManager :
+  SimpleViewManager<HybridNitroRecyclerView>() {
+
+  override fun getName(): String = "NitroRecyclerView"
+
+  override fun createViewInstance(
+    reactContext: ThemedReactContext
+  ): HybridNitroRecyclerView {
+    return HybridNitroRecyclerView(reactContext)
+  }
+
+  @ReactProp(name = "itemCount")
+  fun setItemCount(
+    view: HybridNitroRecyclerView,
+    count: Int
+  ) {
+    view.setItemCount(count)
+  }
+}

package/android/src/main/java/com/nitrolist/NitroListPackage.kt

@@ -1,29 +1,18 @@
-package com.nitrolist;
+package com.nitrolist
 
-import com.facebook.react.bridge.NativeModule;
-import com.facebook.react.bridge.ReactApplicationContext;
-import com.facebook.react.module.model.ReactModuleInfoProvider;
-import com.facebook.react.TurboReactPackage;
-import com.facebook.react.uimanager.ViewManager;
-import com.margelo.nitro.nitrolist.*;
-import com.margelo.nitro.nitrolist.views.*;
+import com.facebook.react.ReactPackage
+import com.facebook.react.bridge.NativeModule
+import com.facebook.react.bridge.ReactApplicationContext
+import com.facebook.react.uimanager.ViewManager
 
+class NitroListPackage : ReactPackage {
 
-public class NitroListPackage : TurboReactPackage() {
-  override fun getModule(name: String, reactContext: ReactApplicationContext): NativeModule? = null
+  override fun createNativeModules(
+    reactContext: ReactApplicationContext
+  ): List<NativeModule> = emptyList()
 
-  override fun getReactModuleInfoProvider(): ReactModuleInfoProvider = ReactModuleInfoProvider { emptyMap() }
-  
-  override fun createViewManagers(reactContext: ReactApplicationContext): List<ViewManager<*, *>> {
-    val viewManagers = ArrayList<ViewManager<*, *>>()
-    viewManagers.add(HybridNitroListManager())
-    return viewManagers
-  }
-
-  companion object {
-    init {
-      NitroListOnLoad.initializeNative()
-    }
-  }
+  override fun createViewManagers(
+    reactContext: ReactApplicationContext
+  ): List<ViewManager<*, *>> =
+    listOf(HybridNitroRecyclerViewManager())
 }
-

package/android/src/main/java/com/nitrolist/NitroRecyclerAdapter.kt

@@ -0,0 +1,32 @@
+package com.nitrolist
+
+import android.view.View
+import android.view.ViewGroup
+import androidx.recyclerview.widget.RecyclerView
+
+class NitroRecyclerAdapter(
+  private var itemCountInternal: Int
+) : RecyclerView.Adapter<NitroRecyclerViewHolder>() {
+
+  override fun onCreateViewHolder(
+    parent: ViewGroup,
+    viewType: Int
+  ): NitroRecyclerViewHolder {
+    val view = View(parent.context)
+    return NitroRecyclerViewHolder(view)
+  }
+
+  override fun onBindViewHolder(
+    holder: NitroRecyclerViewHolder,
+    position: Int
+  ) {
+    // JS/Fabric will manage children later
+  }
+
+  override fun getItemCount(): Int = itemCountInternal
+
+  fun updateCount(newCount: Int) {
+    itemCountInternal = newCount
+    notifyDataSetChanged()
+  }
+}

package/android/src/main/java/com/nitrolist/NitroRecyclerViewHolder.kt

@@ -0,0 +1,8 @@
+package com.nitrolist
+
+import android.view.View
+import androidx.recyclerview.widget.RecyclerView
+
+class NitroRecyclerViewHolder(
+  itemView: View
+) : RecyclerView.ViewHolder(itemView)

package/ios/HybridNitroList.swift

@@ -1,21 +1,38 @@
-//
-//  HybridNitroList.swift
-//  Pods
-//
-//  Created by Shiv Shankar Tiwari on 25/12/2025.
-//
-
 import Foundation
-import UIKit
+import NitroModules
+
+/**
+ * Native layout engine for RecyclerList.
+ * Pure, deterministic, synchronous computation.
+ */
+final class HybridNitroList: HybridNitroListSpec {
+
+  /**
+   * Computes absolute layout rectangles for all items.
+   * Called synchronously via JSI.
+   */
+  func computeLayout(
+    containerWidth: Double,
+    itemHeights: [Double]
+  ) -> [LayoutRectangle] {
 
-class HybridNitroList : HybridNitroListSpec {
-  // UIView
-  var view: UIView = UIView()
+    var layouts: [LayoutRectangle] = []
+    layouts.reserveCapacity(itemHeights.count)
 
-  // Props
-  var isRed: Bool = false {
-    didSet {
-      view.backgroundColor = isRed ? .red : .black
+    var currentY: Double = 0
+
+    for height in itemHeights {
+      let rect = LayoutRectangle(
+        x: 0,
+        y: currentY,
+        width: containerWidth,
+        height: height
+      )
+
+      layouts.append(rect)
+      currentY += height
     }
+
+    return layouts
   }
 }

package/lib/commonjs/NitroList.js

@@ -0,0 +1,9 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.NitroRecyclerView = void 0;
+var _reactNative = require("react-native");
+const NitroRecyclerView = exports.NitroRecyclerView = (0, _reactNative.requireNativeComponent)('NitroRecyclerView');
+//# sourceMappingURL=NitroList.js.map

package/lib/commonjs/NitroList.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["_reactNative","require","NitroRecyclerView","exports","requireNativeComponent"],"sourceRoot":"../../src","sources":["NitroList.ts"],"mappings":";;;;;;AAAA,IAAAA,YAAA,GAAAC,OAAA;AAMO,MAAMC,iBAAiB,GAAAC,OAAA,CAAAD,iBAAA,GAC5B,IAAAE,mCAAsB,EAAyB,mBAAmB,CAAC","ignoreList":[]}

package/lib/commonjs/RecyclerList.internal.js

@@ -0,0 +1,25 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.useRecyclerListInternal = useRecyclerListInternal;
+var _useCellRenderer = require("./hooks/useCellRenderer");
+/**
+ * INTERNAL hook.
+ * MUST ALWAYS CALL hooks in the same order.
+ */
+function useRecyclerListInternal(layouts, metrics, bufferPx, getItemType) {
+  /**
+   * FlashList rule:
+   * Hooks are ALWAYS called.
+   * Inputs are guarded instead.
+   */
+  const safeLayouts = metrics.height > 0 ? layouts : EMPTY_LAYOUTS;
+  const safeBufferPx = metrics.height > 0 ? bufferPx : 0;
+  return (0, _useCellRenderer.useCellRenderer)(safeLayouts, metrics, safeBufferPx, getItemType);
+}
+
+/** Stable empty reference */
+const EMPTY_LAYOUTS = [];
+//# sourceMappingURL=RecyclerList.internal.js.map

package/lib/commonjs/RecyclerList.internal.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["_useCellRenderer","require","useRecyclerListInternal","layouts","metrics","bufferPx","getItemType","safeLayouts","height","EMPTY_LAYOUTS","safeBufferPx","useCellRenderer"],"sourceRoot":"../../src","sources":["RecyclerList.internal.ts"],"mappings":";;;;;;AAIA,IAAAA,gBAAA,GAAAC,OAAA;AAEA;AACA;AACA;AACA;AACO,SAASC,uBAAuBA,CACrCC,OAAmC,EACnCC,OAAsB,EACtBC,QAAgB,EAChBC,WAAsC,EACrB;EAEjB;AACF;AACA;AACA;AACA;EACE,MAAMC,WAAW,GACfH,OAAO,CAACI,MAAM,GAAG,CAAC,GAAGL,OAAO,GAAGM,aAAa;EAE9C,MAAMC,YAAY,GAChBN,OAAO,CAACI,MAAM,GAAG,CAAC,GAAGH,QAAQ,GAAG,CAAC;EAEnC,OAAO,IAAAM,gCAAe,EACpBJ,WAAW,EACXH,OAAO,EACPM,YAAY,EACZJ,WACF,CAAC;AACH;;AAEA;AACA,MAAMG,aAAyC,GAAG,EAAE","ignoreList":[]}