react-native-nitro-list 0.1.1 → 0.1.3

package/src/getVisibleIndices.ts

@@ -1,4 +1,6 @@
-import type { LayoutRectangle } from './layout/LayoutRectangle'
+
+
+import type { LayoutRect } from './types/layout'
 import type { ScrollMetrics } from './windowing/ScrollMetrics'
 
 /**
@@ -6,7 +8,7 @@ import type { ScrollMetrics } from './windowing/ScrollMetrics'
  * Returns indices intersecting viewport ± buffer.
  */
 export function getVisibleRange(
-  layouts: readonly LayoutRectangle[],
+  layouts: readonly LayoutRect[],
   metrics: ScrollMetrics,
   bufferPx: number
 ): readonly number[] {

package/src/hooks/usePersistentCallback.ts

@@ -0,0 +1,37 @@
+import { useRef, useCallback } from 'react'
+
+/**
+ * Returns a function whose identity is stable across renders,
+ * but always invokes the latest provided implementation.
+ *
+ * Invariants:
+ * - Function reference NEVER changes
+ * - Logic is ALWAYS up to date
+ *
+ * This is critical for long-lived systems such as:
+ * - Recyclers
+ * - Effects
+ * - Native bridges
+ * - Event pipelines
+ */
+export function usePersistentCallback<
+  T extends (...args: never[]) => unknown
+>(fn: T): T {
+
+  /**
+   * Holds the latest implementation.
+   * Updating this does NOT trigger re-renders.
+   */
+  const fnRef = useRef(fn)
+  fnRef.current = fn
+
+  /**
+   * Stable wrapper that forwards calls
+   * to the latest implementation.
+   */
+  return useCallback(
+    ((...args: never[]) =>
+      fnRef.current(...args)) as T,
+    []
+  )
+}

package/src/index.ts

@@ -1,2 +1,7 @@
-export { RecyclerList } from './RecyclerList'
-export type { RecyclerListProps } from './RecyclerList.types'
+
+// 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,79 +1,112 @@
-import type { LayoutRectangle } from './LayoutRectangle'
+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'
 
-/**
- * INTERNAL mutable layout record.
- * This is intentionally mutable and never exposed publicly.
- */
-type MutableLayoutRectangle = {
-  x: number
-  y: number
-  width: number
-  height: number
-}
 
 /**
- * Mutable linear layout store.
- * FlashList-style incremental relayout.
+ * Mutable, deterministic linear layout engine.
+ *
+ * Responsibilities:
+ * - Compute absolute item geometry
+ * - Own layout truth (no React, no scroll state)
+ * - Guarantee monotonic ordering along the main axis
+ *
+ * Cross-platform equivalents:
+ * - Flutter: RenderSliver / SliverList
+ * - Android: LinearLayoutManager
+ * - iOS: UICollectionViewFlowLayout (linear)
  */
 export class MutableLinearLayout {
-  private readonly layouts: MutableLayoutRectangle[]
-  private totalHeight: number
+  private readonly isVertical: boolean
 
-  constructor(
-    initialHeights: readonly number[],
-    width: number
-  ) {
-    this.layouts = []
-    let y = 0
-
-    for (const height of initialHeights) {
-      this.layouts.push({
-        x: 0,
-        y,
-        width,
-        height,
-      })
-      y += height
+  /** Absolute item layouts in index order */
+  private layouts: LayoutRect[] = []
+
+  /** Total scrollable size along main axis */
+  private contentSize = 0
+
+  constructor(axis: Axis) {
+    this.isVertical = axis === 'vertical'
+  }
+
+  /**
+   * Computes layout synchronously from input.
+   *
+   * This method is intentionally parameter-object based
+   * to allow future extension without breaking API.
+   *
+   * Invariants:
+   * - Layouts are monotonic along main axis
+   * - No gaps except explicit spacing
+   * - Deterministic for identical inputs
+   */
+  compute(input: LinearLayoutInput): void {
+    const {
+      crossAxisSize,
+      itemMainAxisSizes,
+      padding,
+      itemSpacing = DEFAULT_ITEM_SPACING,
+    } = input
+
+    const itemCount = itemMainAxisSizes.length
+    const layouts: LayoutRect[] = new Array(itemCount)
+
+    let cursor = padding.start
+
+    for (let i = 0; i < itemCount; i++) {
+      const mainAxisSize = itemMainAxisSizes[i]!
+
+      layouts[i] = this.isVertical
+        ? {
+            x: 0,
+            y: cursor,
+            width: crossAxisSize,
+            height: mainAxisSize,
+          }
+        : {
+            x: cursor,
+            y: 0,
+            width: mainAxisSize,
+            height: crossAxisSize,
+          }
+
+      cursor += mainAxisSize
+
+      // Space BETWEEN items, not after the last
+      if (i < itemCount - 1) {
+        cursor += itemSpacing
+      }
     }
 
-    this.totalHeight = y
+    this.layouts = layouts
+    this.contentSize = cursor + padding.end
   }
 
   /**
-   * Read-only snapshot for consumers.
-   * Returned type is immutable.
+   * Returns computed item layouts.
+   *
+   * Order is guaranteed monotonic along the main axis,
+   * which is required for binary-search-based windowing.
    */
-  getLayouts(): readonly LayoutRectangle[] {
+  getLayouts(): readonly LayoutRect[] {
     return this.layouts
   }
 
-  getContentHeight(): number {
-    return this.totalHeight
+  /**
+   * Returns total scrollable size along the main axis,
+   * including padding and inter-item spacing.
+   */
+  getContentSize(): number {
+    return this.contentSize
   }
 
   /**
-   * Update height of one item and shift following items.
-   * Returns true if layout changed.
+   * Clears internal layout state.
+   * Call on severe invalidation or teardown.
    */
-  updateItemHeight(
-    index: number,
-    newHeight: number
-  ): boolean {
-    const layout = this.layouts[index]
-    if (!layout) return false
-
-    const delta = newHeight - layout.height
-    if (delta === 0) return false
-
-    // Update this item
-    layout.height = newHeight
-
-    // Shift all items after this index
-    for (let i = index + 1; i < this.layouts.length; i++) {
-      this.layouts[i]!.y += delta
-    }
-
-    this.totalHeight += delta
-    return true
+  reset(): void {
+    this.layouts = []
+    this.contentSize = 0
   }
 }

package/src/layout/constants/layoutDefaults.ts

@@ -0,0 +1,12 @@
+/**
+ * Default spacing between items along the main axis.
+ *
+ * This value is used by layout engines when no explicit
+ * itemSpacing is provided.
+ *
+ * Mirrors:
+ * - Android RecyclerView ItemDecoration (typical 8–16dp)
+ * - iOS UICollectionViewFlowLayout minimumLineSpacing
+ * - Flutter SliverList spacing conventions
+ */
+export const DEFAULT_ITEM_SPACING = 12

package/src/layout/index.ts

@@ -1,4 +1 @@
-export type { LayoutRectangle } from './LayoutRectangle'
-export type { LayoutProvider } from './LayoutProvider'
-export { EstimatedLayoutProvider } from './EstimatedLayoutProvider'
-export { computeLayouts } from './LayoutEngine'
+export type { MutableLinearLayout } from './MutableLinearLayout'

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

@@ -0,0 +1,33 @@
+import type { RecyclerCell } from '../types/recycler/RecyclerCell'
+import type { CellType } from '../types/CellType'
+
+export class CellPool<T extends RecyclerCell<any>> {
+  private readonly pools = new Map<CellType, T[]>()
+  private readonly maxPerType = new Map<CellType, number>()
+
+  hasType(type: CellType): boolean {
+    return this.pools.has(type)
+  }
+
+  registerType(type: CellType, maxCount: number): void {
+    if (this.pools.has(type)) return
+    this.pools.set(type, [])
+    this.maxPerType.set(type, maxCount)
+  }
+
+  acquire(type: CellType): T | null {
+    const bucket = this.pools.get(type)
+    if (!bucket || bucket.length === 0) return null
+    return bucket.pop() ?? null
+  }
+
+  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)
+  }
+}

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/Axis.ts

@@ -0,0 +1,10 @@
+/**
+ * Axis along which scrolling and layout occur.
+ *
+ * Matches Flutter's Axis:
+ * - vertical   → Y axis
+ * - horizontal → X axis
+ *
+ * This is NOT gesture direction.
+ */
+export type Axis = 'vertical' | 'horizontal'

package/src/types/CellKey.ts

@@ -0,0 +1,2 @@
+// CellKey.ts
+export type CellKey = number