react-native-nitro-list 0.1.2 → 0.1.3

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

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

package/nitrogen/generated/shared/c++/{LayoutRect.hpp → ItemLayout.hpp}

@@ -1,5 +1,5 @@
 ///
-/// LayoutRect.hpp
+/// ItemLayout.hpp
 /// This file was generated by nitrogen. DO NOT MODIFY THIS FILE.
 /// https://github.com/mrousavy/nitro
 /// Copyright © 2025 Marc Rousavy @ Margelo
@@ -35,9 +35,9 @@
 namespace margelo::nitro::nitrolist {
 
   /**
-   * A struct which can be represented as a JavaScript object (LayoutRect).
+   * A struct which can be represented as a JavaScript object (ItemLayout).
    */
-  struct LayoutRect final {
+  struct ItemLayout final {
   public:
     double x     SWIFT_PRIVATE;
     double y     SWIFT_PRIVATE;
@@ -45,30 +45,30 @@ namespace margelo::nitro::nitrolist {
     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) {}
+    ItemLayout() = default;
+    explicit ItemLayout(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;
+    friend bool operator==(const ItemLayout& lhs, const ItemLayout& rhs) = default;
   };
 
 } // namespace margelo::nitro::nitrolist
 
 namespace margelo::nitro {
 
-  // C++ LayoutRect <> JS LayoutRect (object)
+  // C++ ItemLayout <> JS ItemLayout (object)
   template <>
-  struct JSIConverter<margelo::nitro::nitrolist::LayoutRect> final {
-    static inline margelo::nitro::nitrolist::LayoutRect fromJSI(jsi::Runtime& runtime, const jsi::Value& arg) {
+  struct JSIConverter<margelo::nitro::nitrolist::ItemLayout> final {
+    static inline margelo::nitro::nitrolist::ItemLayout fromJSI(jsi::Runtime& runtime, const jsi::Value& arg) {
       jsi::Object obj = arg.asObject(runtime);
-      return margelo::nitro::nitrolist::LayoutRect(
+      return margelo::nitro::nitrolist::ItemLayout(
         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) {
+    static inline jsi::Value toJSI(jsi::Runtime& runtime, const margelo::nitro::nitrolist::ItemLayout& 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));

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "react-native-nitro-list",
-  "version": "0.1.2",
-  "description": "react-native-nitro-list is a react native package built with Nitro",
+  "version": "0.1.3",
+  "description": "High-performance list for React Native powered by Nitro",
   "main": "./lib/commonjs/index.js",
   "module": "./lib/module/index.js",
   "types": "./lib/typescript/src/index.d.ts",
@@ -45,11 +45,11 @@
   "workspaces": [
     "example"
   ],
-  "repository": "https://github.com/shivshankartiwari/react-native-nitro-list.git",
+  "repository": "https://github.com/pythonsst/nitro-list",
   "author": "Shiv Shankar Tiwari",
   "license": "MIT",
-  "bugs": "https://github.com/shivshankartiwari/react-native-nitro-list/issues",
-  "homepage": "https://github.com/shivshankartiwari/react-native-nitro-list#readme",
+  "bugs": "https://github.com/pythonsst/nitro-list/issues",
+  "homepage": "https://github.com/pythonsst/nitro-list#readme",
   "publishConfig": {
     "access": "public",
     "registry": "https://registry.npmjs.org/"

package/src/index.ts

@@ -1 +1,7 @@
-export { RecyclerList } from './recycler/RecyclerList'
+
+// Export the Native View
+export * from './native/NitroListView';
+// Export the JSI Specs
+export * from './specs/NitroList.nitro';
+
+export { default as NitroList } from './recycler/NitroList';

package/src/layout/MutableLinearLayout.ts

@@ -1,9 +1,9 @@
 import type { Axis } from '../types/Axis'
 import type { LinearLayoutInput } from '../types/layout'
 import type { LayoutRect } from '../types/layout/LayoutRect'
-
 import { DEFAULT_ITEM_SPACING } from './constants/layoutDefaults'
 
+
 /**
  * Mutable, deterministic linear layout engine.
  *

package/src/native/NitroListView.ts

@@ -0,0 +1,22 @@
+import { requireNativeComponent, type ViewProps } from 'react-native'
+
+/**
+ * Props for the NitroListView.
+ * * We extend ViewProps so that developers can use standard styles 
+ * like 'flex: 1' or 'backgroundColor' on the list.
+ */
+export type NitroListViewProps = ViewProps & {
+  /**
+   * The total number of items to be displayed in the list.
+   * This is passed to the native side (Swift/Kotlin) for layout math.
+   */
+  itemCount: number
+}
+
+/**
+ * The Native Component that maps to the physical view in Swift/Kotlin.
+ * * 'NitroListView' is the "Secret Handshake" name. It must match 
+ * the name exported by your Native ViewManagers.
+ */
+export const NitroListView =
+  requireNativeComponent<NitroListViewProps>('NitroListView')

package/src/recycler/CellPool.ts

@@ -1,47 +1,33 @@
+import type { RecyclerCell } from '../types/recycler/RecyclerCell'
 import type { CellType } from '../types/CellType'
-import type { RecyclerCellInstance } from '../types/recycler'
 
-export class CellPool {
-  private readonly pools = new Map<CellType, RecyclerCellInstance[]>()
+export class CellPool<T extends RecyclerCell<any>> {
+  private readonly pools = new Map<CellType, T[]>()
   private readonly maxPerType = new Map<CellType, number>()
 
-  /** ✅ NEW: check if a type is registered */
   hasType(type: CellType): boolean {
     return this.pools.has(type)
   }
 
   registerType(type: CellType, maxCount: number): void {
-    if (this.maxPerType.has(type)) return
-    this.maxPerType.set(type, maxCount)
+    if (this.pools.has(type)) return
     this.pools.set(type, [])
+    this.maxPerType.set(type, maxCount)
   }
 
-  acquire(type: CellType): RecyclerCellInstance | null {
+  acquire(type: CellType): T | null {
     const bucket = this.pools.get(type)
     if (!bucket || bucket.length === 0) return null
-    return bucket.pop()!
+    return bucket.pop() ?? null
   }
 
-  release(cell: RecyclerCellInstance): void {
-    const { type } = cell
-    const bucket = this.pools.get(type)
-    const max = this.maxPerType.get(type)
-
+  release(cell: T): void {
+    const bucket = this.pools.get(cell.type)
+    const max = this.maxPerType.get(cell.type)
     if (!bucket || max === undefined) return
 
     cell.index = -1
-
     if (bucket.length >= max) return
     bucket.push(cell)
   }
-
-  clear(): void {
-    for (const bucket of this.pools.values()) {
-      bucket.length = 0
-    }
-  }
-
-  getPoolSize(type: CellType): number {
-    return this.pools.get(type)?.length ?? 0
-  }
 }

package/src/recycler/NitroList.tsx

@@ -0,0 +1,317 @@
+import React, { useRef, useEffect, useState } from 'react'
+import {
+  ScrollView,
+  View,
+  StyleSheet,
+  type NativeSyntheticEvent,
+  type NativeScrollEvent,
+  type LayoutChangeEvent,
+} from 'react-native'
+
+import type { LayoutRect, VisibleRange } from '../types'
+import type { RecyclerCell, NitroListProps } from '../types/recycler'
+import type { CellType } from '../types/CellType'
+import type { CellKey } from '../types/CellKey'
+
+import { MutableLinearLayout } from '../layout/MutableLinearLayout'
+import { computeVisibleItemRange } from '../windowing'
+import { CellPool } from './CellPool'
+
+/* ========================================================= */
+
+const DEFAULT_VIEWPORT_SIZE = 800
+const DEFAULT_ITEM_SIZE = 60
+const SCROLL_EVENT_THROTTLE = 16
+
+/* ========================================================= */
+/* Internal (mutable) cell                                  */
+/* ========================================================= */
+
+interface InternalRecyclerCell extends RecyclerCell<CellKey> {
+  active: boolean
+}
+
+/* ========================================================= */
+/* NitroList                                             */
+/* ========================================================= */
+
+export default function NitroList<T>(
+  props: NitroListProps<T>
+): React.ReactElement {
+  const {
+    data,
+    renderItem,
+    getCellType,
+    scrollDirection = 'vertical',
+    bufferRatio = 1.3,
+    containerCrossAxisSize,
+    itemMainAxisSizes,
+    padding = { start: 0, end: 0 },
+    itemSpacing,
+  } = props
+
+  const isVertical = scrollDirection === 'vertical'
+  const [, forceRender] = useState(0)
+
+  const DEBUG = true
+
+
+  /* ======================================================= */
+  /* Layout engine (recomputed when signature changes)       */
+  /* ======================================================= */
+
+  const layoutEngineRef = useRef<MutableLinearLayout | null>(null)
+  const layoutSignatureRef = useRef<string>('')
+
+  const layoutSignature = [
+    scrollDirection,
+    containerCrossAxisSize,
+    data.length,
+    itemMainAxisSizes,
+    padding.start,
+    padding.end,
+    itemSpacing ?? 'none',
+  ].join('|')
+
+  if (
+    layoutEngineRef.current === null ||
+    layoutSignatureRef.current !== layoutSignature
+  ) {
+    const engine = new MutableLinearLayout(scrollDirection)
+    engine.compute({
+      crossAxisSize: containerCrossAxisSize,
+      itemMainAxisSizes,
+      padding,
+      itemSpacing,
+    })
+
+    layoutEngineRef.current = engine
+    layoutSignatureRef.current = layoutSignature
+  }
+
+  const layouts: readonly LayoutRect[] =
+    layoutEngineRef.current.getLayouts()
+
+  const contentSize: number =
+    layoutEngineRef.current.getContentSize()
+
+  /* ======================================================= */
+  /* Scroll metrics                                          */
+  /* ======================================================= */
+
+  const scrollOffsetRef = useRef<number>(0)
+  const viewportSizeRef = useRef<number>(DEFAULT_VIEWPORT_SIZE)
+
+  /* ======================================================= */
+  /* Cell pool                                               */
+  /* ======================================================= */
+
+  const cellPoolRef = useRef<CellPool<InternalRecyclerCell>>(
+    new CellPool<InternalRecyclerCell>()
+  )
+
+  const activeCellsRef = useRef<InternalRecyclerCell[]>([])
+  const nextKeyRef = useRef<number>(0)
+
+  const createCell = (type: CellType): InternalRecyclerCell => ({
+    key: nextKeyRef.current++,
+    type,
+    index: -1,
+    active: false,
+  })
+
+  /* ======================================================= */
+  /* Visible window coordination                             */
+  /* ======================================================= */
+
+  const updateVisibleCells = (): void => {
+    const range: VisibleRange | null =
+      computeVisibleItemRange({
+        layouts,
+        offset: scrollOffsetRef.current,
+        viewportSize: viewportSizeRef.current,
+        buffer: viewportSizeRef.current * bufferRatio,
+        isVertical,
+      })
+
+    
+
+    if (range === null) return
+
+    if (DEBUG) {
+  console.log(
+    '[NitroList] range:',
+    range.startIndex,
+    range.endIndex
+  )
+}
+
+
+    const active = activeCellsRef.current
+
+    // 1. Mark all inactive
+    for (const cell of active) {
+      cell.active = false
+    }
+
+    let writeIndex = 0
+
+    // 2. Activate visible range
+    for (
+      let index = range.startIndex;
+      index <= range.endIndex;
+      index++
+    ) {
+      const item = data[index]
+      if (item === undefined) continue
+
+      const type = getCellType(item, index)
+
+      // Seed pool once per type
+      if (!cellPoolRef.current.hasType(type)) {
+        const maxCells =
+          Math.ceil(
+            (viewportSizeRef.current / DEFAULT_ITEM_SIZE) *
+              bufferRatio
+          ) + 2
+
+        cellPoolRef.current.registerType(type, maxCells)
+        for (let i = 0; i < maxCells; i++) {
+          cellPoolRef.current.release(createCell(type))
+        }
+      }
+
+      let cell: InternalRecyclerCell | null =
+        cellPoolRef.current.acquire(type)
+
+if (cell === null) {
+  const reusable = active.find(
+    c => !c.active && c.type === type
+  )
+
+  cell = reusable ?? createCell(type)
+}
+
+
+      cell.index = index
+      cell.active = true
+      active[writeIndex++] = cell
+    }
+
+    // 3. Recycle unused cells
+    for (let i = writeIndex; i < active.length; i++) {
+      const cell = active[i]
+      if (cell === undefined) continue
+
+      cell.index = -1
+      cell.active = false
+      cellPoolRef.current.release(cell)
+    }
+
+    // 4. Compact once
+    if (active.length !== writeIndex) {
+      active.length = writeIndex
+      forceRender(v => v + 1)
+    }
+  }
+
+  /* ======================================================= */
+  /* Handlers                                                */
+  /* ======================================================= */
+
+  const onScroll = (
+    e: NativeSyntheticEvent<NativeScrollEvent>
+  ): void => {
+    scrollOffsetRef.current = isVertical
+      ? e.nativeEvent.contentOffset.y
+      : e.nativeEvent.contentOffset.x
+
+    updateVisibleCells()
+  }
+
+  const onLayout = (e: LayoutChangeEvent): void => {
+    viewportSizeRef.current = isVertical
+      ? e.nativeEvent.layout.height
+      : e.nativeEvent.layout.width
+
+    updateVisibleCells()
+  }
+
+  useEffect(() => {
+    updateVisibleCells()
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [])
+
+
+if (DEBUG) {
+  console.log('[NitroList] layouts:', layouts.length)
+  console.log('[NitroList] contentSize:', contentSize)
+  console.log('[NitroList] data.length:', data.length)
+}
+
+  /* ======================================================= */
+  /* Render                                                  */
+  /* ======================================================= */
+
+  return (
+    <ScrollView
+      onScroll={onScroll}
+      onLayout={onLayout}
+      horizontal={!isVertical}
+      scrollEventThrottle={SCROLL_EVENT_THROTTLE}
+      removeClippedSubviews
+    >
+      {/* REQUIRED positioning container */}
+      <View
+        style={
+          isVertical
+            ? { height: contentSize }
+            : { width: contentSize }
+        }
+      >
+        {activeCellsRef.current.map(cell => {
+          const layout = layouts[cell.index]
+          const item = data[cell.index]
+
+          if (layout === undefined || item === undefined) {
+            return null
+          }
+
+          return (
+            <View
+              key={cell.key}
+              style={[
+                styles.cell,
+                isVertical
+                  ? {
+                      top: layout.y,
+                      height: layout.height,
+                      width: layout.width,
+                    }
+                  : {
+                      left: layout.x,
+                      width: layout.width,
+                      height: layout.height,
+                    },
+              ]}
+            >
+              {renderItem({
+                item,
+                index: cell.index,
+                cell,
+              })}
+            </View>
+          )
+        })}
+      </View>
+    </ScrollView>
+  )
+}
+
+/* ========================================================= */
+
+const styles = StyleSheet.create({
+  cell: {
+    position: 'absolute',
+  },
+})

package/src/scroll/useScrollVelocity.ts

@@ -0,0 +1,16 @@
+export function createScrollVelocityTracker() {
+  let lastOffset = 0
+  let lastTime = Date.now()
+
+  return function getVelocity(offset: number): number {
+    const now = Date.now()
+    const dt = now - lastTime
+    const dy = Math.abs(offset - lastOffset)
+
+    lastOffset = offset
+    lastTime = now
+
+    if (dt === 0) return 0
+    return dy / dt // px per ms
+  }
+}

package/src/specs/NitroList.nitro.ts

@@ -0,0 +1,29 @@
+import type { HybridObject } from 'react-native-nitro-modules'
+
+/**
+ * Represents the physical area an item occupies on the screen.
+ * Standard: 'Layout' suffix tells the user this is a data object, not a logic object.
+ */
+export interface ItemLayout {
+  readonly x: number
+  readonly y: number
+  readonly width: number
+  readonly height: number
+}
+
+/**
+ * The high-performance layout engine for NitroList.
+ * This interface will be used by Nitro to generate your Swift and Kotlin code.
+ */
+export interface NitroList
+  extends HybridObject<{ ios: 'swift'; android: 'kotlin' }> {
+
+  /**
+   * Calculates exactly where every item should sit on the screen.
+   * Standard: Use descriptive parameter names so developers know what to provide.
+   */
+  computeLayout(
+    containerWidth: number,
+    itemHeights: readonly number[]
+  ): readonly ItemLayout[]
+}

package/src/types/CellKey.ts

@@ -1,9 +1,2 @@
-/**
- * Stable identifier for a cell.
- *
- * Cross-platform equivalent:
- * - Flutter: Key
- * - Android: stableId
- * - iOS: reuseIdentifier (logical)
- */
-export type CellKey = string | number
+// CellKey.ts
+export type CellKey = number

package/src/types/CellType.ts

@@ -1,10 +1,9 @@
-/**
- * Logical cell type.
- *
- * Used to group compatible cells for recycling.
- *
- * Cross-platform equivalent:
- * - Android: viewType
- * - iOS: reuseIdentifier
+/** * CellType is just a string, but we give it a name 
+ * so the code is easier to read. 
  */
-export type CellType = string | number
+export type CellType = string;
+
+/** * This is an "Identity" function. It doesn't do anything 
+ * to the computer, but it helps the human reading the code.
+ */
+export const cellType = (name: string): CellType => name;