react-native-nitro-list 0.0.1 → 0.1.2

package/nitrogen/generated/ios/swift/{HybridNitroListSpec_cxx.swift → HybridNitroLayoutEngineSpec_cxx.swift}

@@ -1,5 +1,5 @@
 ///
-/// HybridNitroListSpec_cxx.swift
+/// HybridNitroLayoutEngineSpec_cxx.swift
 /// This file was generated by nitrogen. DO NOT MODIFY THIS FILE.
 /// https://github.com/mrousavy/nitro
 /// Copyright © 2025 Marc Rousavy @ Margelo
@@ -9,7 +9,7 @@ import Foundation
 import NitroModules
 
 /**
- * A class implementation that bridges HybridNitroListSpec over to C++.
+ * A class implementation that bridges HybridNitroLayoutEngineSpec over to C++.
  * In C++, we cannot use Swift protocols - so we need to wrap it in a class to make it strongly defined.
  *
  * Also, some Swift types need to be bridged with special handling:
@@ -17,7 +17,7 @@ import NitroModules
  * - Other HybridObjects need to be wrapped/unwrapped from the Swift TCxx wrapper
  * - Throwing methods need to be wrapped with a Result<T, Error> type, as exceptions cannot be propagated to C++
  */
-open class HybridNitroListSpec_cxx {
+open class HybridNitroLayoutEngineSpec_cxx {
   /**
    * The Swift <> C++ bridge's namespace (`margelo::nitro::nitrolist::bridge::swift`)
    * from `NitroList-Swift-Cxx-Bridge.hpp`.
@@ -26,30 +26,30 @@ open class HybridNitroListSpec_cxx {
   public typealias bridge = margelo.nitro.nitrolist.bridge.swift
 
   /**
-   * Holds an instance of the `HybridNitroListSpec` Swift protocol.
+   * Holds an instance of the `HybridNitroLayoutEngineSpec` Swift protocol.
    */
-  private var __implementation: any HybridNitroListSpec
+  private var __implementation: any HybridNitroLayoutEngineSpec
 
   /**
    * Holds a weak pointer to the C++ class that wraps the Swift class.
    */
-  private var __cxxPart: bridge.std__weak_ptr_HybridNitroListSpec_
+  private var __cxxPart: bridge.std__weak_ptr_HybridNitroLayoutEngineSpec_
 
   /**
-   * Create a new `HybridNitroListSpec_cxx` that wraps the given `HybridNitroListSpec`.
+   * Create a new `HybridNitroLayoutEngineSpec_cxx` that wraps the given `HybridNitroLayoutEngineSpec`.
    * All properties and methods bridge to C++ types.
    */
-  public init(_ implementation: any HybridNitroListSpec) {
+  public init(_ implementation: any HybridNitroLayoutEngineSpec) {
     self.__implementation = implementation
     self.__cxxPart = .init()
     /* no base class */
   }
 
   /**
-   * Get the actual `HybridNitroListSpec` instance this class wraps.
+   * Get the actual `HybridNitroLayoutEngineSpec` instance this class wraps.
    */
   @inline(__always)
-  public func getHybridNitroListSpec() -> any HybridNitroListSpec {
+  public func getHybridNitroLayoutEngineSpec() -> any HybridNitroLayoutEngineSpec {
     return __implementation
   }
 
@@ -62,25 +62,25 @@ open class HybridNitroListSpec_cxx {
   }
 
   /**
-   * Casts an unsafe pointer to a `HybridNitroListSpec_cxx`.
-   * The pointer has to be a retained opaque `Unmanaged<HybridNitroListSpec_cxx>`.
+   * Casts an unsafe pointer to a `HybridNitroLayoutEngineSpec_cxx`.
+   * The pointer has to be a retained opaque `Unmanaged<HybridNitroLayoutEngineSpec_cxx>`.
    * This removes one strong reference from the object!
    */
-  public class func fromUnsafe(_ pointer: UnsafeMutableRawPointer) -> HybridNitroListSpec_cxx {
-    return Unmanaged<HybridNitroListSpec_cxx>.fromOpaque(pointer).takeRetainedValue()
+  public class func fromUnsafe(_ pointer: UnsafeMutableRawPointer) -> HybridNitroLayoutEngineSpec_cxx {
+    return Unmanaged<HybridNitroLayoutEngineSpec_cxx>.fromOpaque(pointer).takeRetainedValue()
   }
 
   /**
    * Gets (or creates) the C++ part of this Hybrid Object.
-   * The C++ part is a `std::shared_ptr<HybridNitroListSpec>`.
+   * The C++ part is a `std::shared_ptr<HybridNitroLayoutEngineSpec>`.
    */
-  public func getCxxPart() -> bridge.std__shared_ptr_HybridNitroListSpec_ {
+  public func getCxxPart() -> bridge.std__shared_ptr_HybridNitroLayoutEngineSpec_ {
     let cachedCxxPart = self.__cxxPart.lock()
     if Bool(fromCxx: cachedCxxPart) {
       return cachedCxxPart
     } else {
-      let newCxxPart = bridge.create_std__shared_ptr_HybridNitroListSpec_(self.toUnsafe())
-      __cxxPart = bridge.weakify_std__shared_ptr_HybridNitroListSpec_(newCxxPart)
+      let newCxxPart = bridge.create_std__shared_ptr_HybridNitroLayoutEngineSpec_(self.toUnsafe())
+      __cxxPart = bridge.weakify_std__shared_ptr_HybridNitroLayoutEngineSpec_(newCxxPart)
       return newCxxPart
     }
   }
@@ -114,27 +114,24 @@ open class HybridNitroListSpec_cxx {
   }
 
   // Properties
-  public final var isRed: Bool {
-    @inline(__always)
-    get {
-      return self.__implementation.isRed
-    }
-    @inline(__always)
-    set {
-      self.__implementation.isRed = newValue
-    }
-  }
+  
 
   // Methods
-  public final func getView() -> UnsafeMutableRawPointer {
-    return Unmanaged.passRetained(__implementation.view).toOpaque()
-  }
-  
-  public final func beforeUpdate() {
-    __implementation.beforeUpdate()
-  }
-  
-  public final func afterUpdate() {
-    __implementation.afterUpdate()
+  @inline(__always)
+  public final func computeLayout(containerWidth: Double, itemHeights: bridge.std__vector_double_) -> bridge.Result_std__vector_LayoutRect__ {
+    do {
+      let __result = try self.__implementation.computeLayout(containerWidth: containerWidth, itemHeights: itemHeights.map({ __item in __item }))
+      let __resultCpp = { () -> bridge.std__vector_LayoutRect_ in
+        var __vector = bridge.create_std__vector_LayoutRect_(__result.count)
+        for __item in __result {
+          __vector.push_back(__item)
+        }
+        return __vector
+      }()
+      return bridge.create_Result_std__vector_LayoutRect__(__resultCpp)
+    } catch (let __error) {
+      let __exceptionPtr = __error.toCpp()
+      return bridge.create_Result_std__vector_LayoutRect__(__exceptionPtr)
+    }
   }
 }

package/nitrogen/generated/ios/swift/LayoutRect.swift

@@ -0,0 +1,45 @@
+///
+/// LayoutRect.swift
+/// This file was generated by nitrogen. DO NOT MODIFY THIS FILE.
+/// https://github.com/mrousavy/nitro
+/// Copyright © 2025 Marc Rousavy @ Margelo
+///
+
+import Foundation
+import NitroModules
+
+/**
+ * Represents an instance of `LayoutRect`, backed by a C++ struct.
+ */
+public typealias LayoutRect = margelo.nitro.nitrolist.LayoutRect
+
+public extension LayoutRect {
+  private typealias bridge = margelo.nitro.nitrolist.bridge.swift
+
+  /**
+   * Create a new instance of `LayoutRect`.
+   */
+  init(x: Double, y: Double, width: Double, height: Double) {
+    self.init(x, y, width, height)
+  }
+
+  @inline(__always)
+  var x: Double {
+    return self.__x
+  }
+  
+  @inline(__always)
+  var y: Double {
+    return self.__y
+  }
+  
+  @inline(__always)
+  var width: Double {
+    return self.__width
+  }
+  
+  @inline(__always)
+  var height: Double {
+    return self.__height
+  }
+}

package/nitrogen/generated/shared/c++/{HybridNitroListSpec.cpp → HybridNitroLayoutEngineSpec.cpp}

@@ -1,21 +1,20 @@
 ///
-/// HybridNitroListSpec.cpp
+/// HybridNitroLayoutEngineSpec.cpp
 /// This file was generated by nitrogen. DO NOT MODIFY THIS FILE.
 /// https://github.com/mrousavy/nitro
 /// Copyright © 2025 Marc Rousavy @ Margelo
 ///
 
-#include "HybridNitroListSpec.hpp"
+#include "HybridNitroLayoutEngineSpec.hpp"
 
 namespace margelo::nitro::nitrolist {
 
-  void HybridNitroListSpec::loadHybridMethods() {
+  void HybridNitroLayoutEngineSpec::loadHybridMethods() {
     // load base methods/properties
     HybridObject::loadHybridMethods();
     // load custom methods/properties
     registerHybrids(this, [](Prototype& prototype) {
-      prototype.registerHybridGetter("isRed", &HybridNitroListSpec::getIsRed);
-      prototype.registerHybridSetter("isRed", &HybridNitroListSpec::setIsRed);
+      prototype.registerHybridMethod("computeLayout", &HybridNitroLayoutEngineSpec::computeLayout);
     });
   }
 

package/nitrogen/generated/shared/c++/{HybridNitroListSpec.hpp → HybridNitroLayoutEngineSpec.hpp}

@@ -1,5 +1,5 @@
 ///
-/// HybridNitroListSpec.hpp
+/// HybridNitroLayoutEngineSpec.hpp
 /// This file was generated by nitrogen. DO NOT MODIFY THIS FILE.
 /// https://github.com/mrousavy/nitro
 /// Copyright © 2025 Marc Rousavy @ Margelo
@@ -13,43 +13,44 @@
 #error NitroModules cannot be found! Are you sure you installed NitroModules properly?
 #endif
 
+// Forward declaration of `LayoutRect` to properly resolve imports.
+namespace margelo::nitro::nitrolist { struct LayoutRect; }
 
-
-
+#include "LayoutRect.hpp"
+#include <vector>
 
 namespace margelo::nitro::nitrolist {
 
   using namespace margelo::nitro;
 
   /**
-   * An abstract base class for `NitroList`
-   * Inherit this class to create instances of `HybridNitroListSpec` in C++.
+   * An abstract base class for `NitroLayoutEngine`
+   * Inherit this class to create instances of `HybridNitroLayoutEngineSpec` in C++.
    * You must explicitly call `HybridObject`'s constructor yourself, because it is virtual.
    * @example
    * ```cpp
-   * class HybridNitroList: public HybridNitroListSpec {
+   * class HybridNitroLayoutEngine: public HybridNitroLayoutEngineSpec {
    * public:
-   *   HybridNitroList(...): HybridObject(TAG) { ... }
+   *   HybridNitroLayoutEngine(...): HybridObject(TAG) { ... }
    *   // ...
    * };
    * ```
    */
-  class HybridNitroListSpec: public virtual HybridObject {
+  class HybridNitroLayoutEngineSpec: public virtual HybridObject {
     public:
       // Constructor
-      explicit HybridNitroListSpec(): HybridObject(TAG) { }
+      explicit HybridNitroLayoutEngineSpec(): HybridObject(TAG) { }
 
       // Destructor
-      ~HybridNitroListSpec() override = default;
+      ~HybridNitroLayoutEngineSpec() override = default;
 
     public:
       // Properties
-      virtual bool getIsRed() = 0;
-      virtual void setIsRed(bool isRed) = 0;
+      
 
     public:
       // Methods
-      
+      virtual std::vector<LayoutRect> computeLayout(double containerWidth, const std::vector<double>& itemHeights) = 0;
 
     protected:
       // Hybrid Setup
@@ -57,7 +58,7 @@ namespace margelo::nitro::nitrolist {
 
     protected:
       // Tag for logging
-      static constexpr auto TAG = "NitroList";
+      static constexpr auto TAG = "NitroLayoutEngine";
   };
 
 } // namespace margelo::nitro::nitrolist

package/nitrogen/generated/shared/c++/LayoutRect.hpp

@@ -0,0 +1,95 @@
+///
+/// LayoutRect.hpp
+/// This file was generated by nitrogen. DO NOT MODIFY THIS FILE.
+/// https://github.com/mrousavy/nitro
+/// Copyright © 2025 Marc Rousavy @ Margelo
+///
+
+#pragma once
+
+#if __has_include(<NitroModules/JSIConverter.hpp>)
+#include <NitroModules/JSIConverter.hpp>
+#else
+#error NitroModules cannot be found! Are you sure you installed NitroModules properly?
+#endif
+#if __has_include(<NitroModules/NitroDefines.hpp>)
+#include <NitroModules/NitroDefines.hpp>
+#else
+#error NitroModules cannot be found! Are you sure you installed NitroModules properly?
+#endif
+#if __has_include(<NitroModules/JSIHelpers.hpp>)
+#include <NitroModules/JSIHelpers.hpp>
+#else
+#error NitroModules cannot be found! Are you sure you installed NitroModules properly?
+#endif
+#if __has_include(<NitroModules/PropNameIDCache.hpp>)
+#include <NitroModules/PropNameIDCache.hpp>
+#else
+#error NitroModules cannot be found! Are you sure you installed NitroModules properly?
+#endif
+
+
+
+
+
+namespace margelo::nitro::nitrolist {
+
+  /**
+   * A struct which can be represented as a JavaScript object (LayoutRect).
+   */
+  struct LayoutRect final {
+  public:
+    double x     SWIFT_PRIVATE;
+    double y     SWIFT_PRIVATE;
+    double width     SWIFT_PRIVATE;
+    double height     SWIFT_PRIVATE;
+
+  public:
+    LayoutRect() = default;
+    explicit LayoutRect(double x, double y, double width, double height): x(x), y(y), width(width), height(height) {}
+
+  public:
+    friend bool operator==(const LayoutRect& lhs, const LayoutRect& rhs) = default;
+  };
+
+} // namespace margelo::nitro::nitrolist
+
+namespace margelo::nitro {
+
+  // C++ LayoutRect <> JS LayoutRect (object)
+  template <>
+  struct JSIConverter<margelo::nitro::nitrolist::LayoutRect> final {
+    static inline margelo::nitro::nitrolist::LayoutRect fromJSI(jsi::Runtime& runtime, const jsi::Value& arg) {
+      jsi::Object obj = arg.asObject(runtime);
+      return margelo::nitro::nitrolist::LayoutRect(
+        JSIConverter<double>::fromJSI(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "x"))),
+        JSIConverter<double>::fromJSI(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "y"))),
+        JSIConverter<double>::fromJSI(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "width"))),
+        JSIConverter<double>::fromJSI(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "height")))
+      );
+    }
+    static inline jsi::Value toJSI(jsi::Runtime& runtime, const margelo::nitro::nitrolist::LayoutRect& arg) {
+      jsi::Object obj(runtime);
+      obj.setProperty(runtime, PropNameIDCache::get(runtime, "x"), JSIConverter<double>::toJSI(runtime, arg.x));
+      obj.setProperty(runtime, PropNameIDCache::get(runtime, "y"), JSIConverter<double>::toJSI(runtime, arg.y));
+      obj.setProperty(runtime, PropNameIDCache::get(runtime, "width"), JSIConverter<double>::toJSI(runtime, arg.width));
+      obj.setProperty(runtime, PropNameIDCache::get(runtime, "height"), JSIConverter<double>::toJSI(runtime, arg.height));
+      return obj;
+    }
+    static inline bool canConvert(jsi::Runtime& runtime, const jsi::Value& value) {
+      if (!value.isObject()) {
+        return false;
+      }
+      jsi::Object obj = value.getObject(runtime);
+      if (!nitro::isPlainObject(runtime, obj)) {
+        return false;
+      }
+      if (!JSIConverter<double>::canConvert(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "x")))) return false;
+      if (!JSIConverter<double>::canConvert(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "y")))) return false;
+      if (!JSIConverter<double>::canConvert(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "width")))) return false;
+      if (!JSIConverter<double>::canConvert(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "height")))) return false;
+      return true;
+    }
+  };
+
+} // namespace margelo::nitro

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-native-nitro-list",
-  "version": "0.0.1",
+  "version": "0.1.2",
   "description": "react-native-nitro-list is a react native package built with Nitro",
   "main": "./lib/commonjs/index.js",
   "module": "./lib/module/index.js",
@@ -8,6 +8,9 @@
   "react-native": "src/index",
   "source": "src/index",
   "scripts": {
+    "publish:release": "./scripts/publish.sh",
+    "test": "npx jest --passWithNoTests",
+    "test:watch": "npx jest --watch",
     "typecheck": "tsc --noEmit",
     "clean": "git clean -dfX",
     "release": "semantic-release",
@@ -57,12 +60,14 @@
     "@semantic-release/git": "^10.0.1",
     "@types/jest": "^29.5.12",
     "@types/react": "19.2.0",
-    "nitrogen": "0.32.0",
+    "conventional-changelog-conventionalcommits": "^9.1.0",
+    "jest-environment-jsdom": "^30.2.0",
+    "nitrogen": "^0.32.0",
     "react": "19.2.0",
     "react-native": "0.83",
     "react-native-builder-bob": "^0.40.17",
     "react-native-nitro-modules": "0.32.0",
-    "conventional-changelog-conventionalcommits": "^9.1.0",
+    "react-test-renderer": "^19.2.0",
     "semantic-release": "^25.0.2",
     "typescript": "^5.8.3"
   },
@@ -118,5 +123,8 @@
         }
       ]
     ]
+  },
+  "dependencies": {
+    "nitro-modules": "^0.1.1"
   }
-}
+}

package/src/NitroList.ts

@@ -0,0 +1,8 @@
+import { requireNativeComponent } from 'react-native'
+
+export type NitroRecyclerViewProps = {
+  itemCount: number
+}
+
+export const NitroRecyclerView =
+  requireNativeComponent<NitroRecyclerViewProps>('NitroRecyclerView')

package/src/ReusableView.ts

@@ -0,0 +1,12 @@
+// src/ReusableView.ts
+
+export type ReusableView = {
+  /** Stable identity for React */
+  readonly key: string
+
+  /** Current data index bound to this slot */
+  index: number
+
+  /** Optional type (header, row, etc — future) */
+  type?: string
+}

package/src/cell/Cell.ts

@@ -0,0 +1,23 @@
+/**
+ * Physical reusable cell.
+ * Represents a single mounted view instance.
+ */
+export interface Cell {
+  /**
+   * Stable physical identity.
+   * Used as React key. NEVER changes.
+   */
+  readonly key: string
+
+  /**
+   * Logical data index currently bound.
+   * Changes as the cell is recycled.
+   */
+  index: number
+
+  /**
+   * Compatibility type (row, header, etc).
+   * Determines reuse eligibility.
+   */
+  readonly type: string
+}

package/src/cell/CellKeyGenerator.ts

@@ -0,0 +1,17 @@
+import type { CellKey } from '../types/CellKey'
+
+/**
+ * Monotonic key generator for physical cell instances.
+ * Guarantees stable keys across the lifetime of the list.
+ */
+export class CellKeyGenerator {
+  private nextId = 0
+
+  next(): CellKey {
+    return this.nextId++
+  }
+
+  reset(): void {
+    this.nextId = 0
+  }
+}

package/src/cell/CellRecycler.ts

@@ -0,0 +1,76 @@
+import type { Cell } from './Cell'
+import { createCell } from './createCell'
+
+/**
+ * Manages physical cell reuse.
+ * Imperative and stateful by design.
+ * This is NOT React code.
+ */
+export class CellRecycler {
+  /**
+   * Active cells mapped by logical index.
+   */
+  private readonly indexToCell = new Map<number, Cell>()
+
+  /**
+   * Pool of detached reusable cells.
+   */
+  private readonly recycledCells: Cell[] = []
+
+  /**
+   * Reconcile a contiguous visible index range
+   * into a stable list of physical cells.
+   *
+   * HOT PATH:
+   * - No index arrays
+   * - Minimal allocations
+   * - Deterministic
+   */
+  reconcileRange(
+    startIndex: number,
+    endIndex: number,
+    resolveCellType: (index: number) => string
+  ): readonly Cell[] {
+    const nextActive: Cell[] = []
+
+    // Track which current indices are no longer visible
+    const unusedIndices = new Set(this.indexToCell.keys())
+
+    for (let index = startIndex; index <= endIndex; index++) {
+      unusedIndices.delete(index)
+
+      let cell = this.indexToCell.get(index)
+      if (cell) {
+        // Existing assignment — reuse
+        nextActive.push(cell)
+        continue
+      }
+
+      const type = resolveCellType(index)
+
+      // Try to reuse a recycled cell of same type
+      const recycledIdx = this.recycledCells.findIndex(
+        c => c.type === type
+      )
+
+      if (recycledIdx !== -1) {
+        cell = this.recycledCells.splice(recycledIdx, 1)[0]!
+      } else {
+        cell = createCell(type)
+      }
+
+      cell.index = index
+      this.indexToCell.set(index, cell)
+      nextActive.push(cell)
+    }
+
+    // Recycle cells that left the visible window
+    for (const index of unusedIndices) {
+      const cell = this.indexToCell.get(index)!
+      this.indexToCell.delete(index)
+      this.recycledCells.push(cell)
+    }
+
+    return nextActive
+  }
+}

package/src/cell/createCell.ts

@@ -0,0 +1,15 @@
+import type { Cell } from './Cell'
+
+let nextCellId = 0
+
+/**
+ * Creates a new physical cell with a stable identity.
+ * The key is generated ONCE and never changes.
+ */
+export function createCell(type: string): Cell {
+  return {
+    key: `cell-${nextCellId++}`, // stable physical identity
+    type,
+    index: -1,                  // assigned by recycler
+  }
+}

package/src/cell/index.ts

@@ -0,0 +1,5 @@
+// Public cell-layer exports
+
+export type { Cell } from './Cell'
+export { CellRecycler } from './CellRecycler'
+export { createCell } from './createCell'

package/src/debug/useDebugOverlay.ts

@@ -0,0 +1,14 @@
+import { useEffect } from 'react'
+
+export function useDebugOverlay(
+  enabled: boolean,
+  visibleCount: number
+): void {
+  useEffect(() => {
+    if (__DEV__ && enabled) {
+      console.log(
+        `[RecyclerList] visible items: ${visibleCount}`
+      )
+    }
+  }, [enabled, visibleCount])
+}

package/src/getVisibleIndices.ts

@@ -0,0 +1,55 @@
+
+
+import type { LayoutRect } from './types/layout'
+import type { ScrollMetrics } from './windowing/ScrollMetrics'
+
+/**
+ * Binary-search based windowing.
+ * Returns indices intersecting viewport ± buffer.
+ */
+export function getVisibleRange(
+  layouts: readonly LayoutRect[],
+  metrics: ScrollMetrics,
+  bufferPx: number
+): readonly number[] {
+  if (
+    layouts.length === 0 ||
+    metrics.height <= 0
+  ) {
+    return []
+  }
+
+  const startY = Math.max(
+    0,
+    metrics.offsetY - bufferPx
+  )
+
+  const endY =
+    metrics.offsetY + metrics.height + bufferPx
+
+  let low = 0
+  let high = layouts.length - 1
+  let first = layouts.length
+
+  while (low <= high) {
+    const mid = (low + high) >> 1
+    const rect = layouts[mid]!
+
+    if (rect.y + rect.height >= startY) {
+      first = mid
+      high = mid - 1
+    } else {
+      low = mid + 1
+    }
+  }
+
+  const visible: number[] = []
+
+  for (let i = first; i < layouts.length; i++) {
+    const rect = layouts[i]!
+    if (rect.y > endY) break
+    visible.push(i)
+  }
+
+  return visible
+}