react-native-nitro-list 0.0.1 → 0.1.2

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,14 +1 @@
-import { getHostComponent, type HybridRef } from 'react-native-nitro-modules'
-import NitroListConfig from '../nitrogen/generated/shared/json/NitroListConfig.json'
-import type {
-  NitroListProps,
-  NitroListMethods,
-} from './specs/nitro-list.nitro'
-
-
-export const NitroList = getHostComponent<NitroListProps, NitroListMethods>(
-  'NitroList',
-  () => NitroListConfig
-)
-
-export type NitroListRef = HybridRef<NitroListProps, NitroListMethods>
+export { RecyclerList } from './recycler/RecyclerList'

package/src/layout/MutableLinearLayout.ts

@@ -0,0 +1,112 @@
+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.
+ *
+ * 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 isVertical: boolean
+
+  /** 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.layouts = layouts
+    this.contentSize = cursor + padding.end
+  }
+
+  /**
+   * Returns computed item layouts.
+   *
+   * Order is guaranteed monotonic along the main axis,
+   * which is required for binary-search-based windowing.
+   */
+  getLayouts(): readonly LayoutRect[] {
+    return this.layouts
+  }
+
+  /**
+   * Returns total scrollable size along the main axis,
+   * including padding and inter-item spacing.
+   */
+  getContentSize(): number {
+    return this.contentSize
+  }
+
+  /**
+   * Clears internal layout state.
+   * Call on severe invalidation or teardown.
+   */
+  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

@@ -0,0 +1 @@
+export type { MutableLinearLayout } from './MutableLinearLayout'

package/src/measurement/MeasureLayout.ts

@@ -0,0 +1,20 @@
+import type { LayoutChangeEvent } from 'react-native'
+
+export interface MeasuredLayout {
+  readonly width: number
+  readonly height: number
+}
+
+/**
+ * Extracts stable layout measurements from RN onLayout event.
+ */
+export function measureLayout(
+  event: LayoutChangeEvent
+): MeasuredLayout {
+  const { width, height } = event.nativeEvent.layout
+
+  return {
+    width,
+    height,
+  }
+}

package/src/measurement/useItemMeasurement.ts

@@ -0,0 +1,32 @@
+import { useCallback, useRef } from 'react'
+import type { LayoutChangeEvent } from 'react-native'
+
+/**
+ * Hook to measure a rendered item safely.
+ *
+ * Guarantees:
+ * - No duplicate height reports
+ * - No render loops
+ * - Stable callback identity
+ */
+export function useItemMeasurement(
+  index: number,
+  onMeasured: (index: number, height: number) => void
+) {
+  const lastHeightRef = useRef<number | null>(null)
+
+  const onLayout = useCallback(
+    (e: LayoutChangeEvent) => {
+      const height = e.nativeEvent.layout.height
+
+      // Ignore identical measurements
+      if (lastHeightRef.current === height) return
+
+      lastHeightRef.current = height
+      onMeasured(index, height)
+    },
+    [index, onMeasured]
+  )
+
+  return onLayout
+}

package/src/native/NitroLayoutEngine.ts

@@ -0,0 +1,7 @@
+import { NitroModules } from 'react-native-nitro-modules'
+import type { NitroLayoutEngine as NitroLayoutEngineSpec } from '../specs/nitro-layout-engine.nitro'
+
+export const NitroLayoutEngine =
+  NitroModules.createHybridObject<NitroLayoutEngineSpec>(
+    'NitroLayoutEngine'
+  )

package/src/native/NitroList.types.ts

@@ -0,0 +1,13 @@
+import type { LayoutRect } from "../types/layout";
+
+
+/**
+ * JS runtime interface backed by Nitro (JSI).
+ * Must match native HybridNitroList exactly.
+ */
+export interface NitroList {
+  computeLayout(
+    containerWidth: number,
+    itemHeights: readonly number[]
+  ): readonly LayoutRect[]
+}

package/src/native/NitroRecyclerView.ts

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

package/src/prefetch/PrefetchHelper.ts

@@ -0,0 +1,47 @@
+/**
+ * Callback invoked when new items should be prefetched.
+ */
+export type PrefetchCallback = (indices: number[]) => void
+
+/**
+ * PrefetchHelper
+ *
+ * Stateless with respect to layout.
+ * Only tracks what has already been prefetched to avoid duplication.
+ *
+ * Designed to be driven by *visible window*, not scroll events.
+ */
+export class PrefetchHelper {
+  private lastPrefetched = new Set<number>()
+
+  runPrefetch(
+    visibleIndices: readonly number[],
+    itemCount: number,
+    aheadCount: number,
+    onPrefetch: PrefetchCallback
+  ) {
+    if (visibleIndices.length === 0) return
+
+    const lastVisible =
+      visibleIndices[visibleIndices.length - 1]!
+
+    const start = lastVisible + 1
+    const end = Math.min(
+      itemCount - 1,
+      start + aheadCount
+    )
+
+    const toPrefetch: number[] = []
+
+    for (let i = start; i <= end; i++) {
+      if (!this.lastPrefetched.has(i)) {
+        this.lastPrefetched.add(i)
+        toPrefetch.push(i)
+      }
+    }
+
+    if (toPrefetch.length > 0) {
+      onPrefetch(toPrefetch)
+    }
+  }
+}

package/src/recycler/CellPool.ts

@@ -0,0 +1,47 @@
+import type { CellType } from '../types/CellType'
+import type { RecyclerCellInstance } from '../types/recycler'
+
+export class CellPool {
+  private readonly pools = new Map<CellType, RecyclerCellInstance[]>()
+  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)
+    this.pools.set(type, [])
+  }
+
+  acquire(type: CellType): RecyclerCellInstance | null {
+    const bucket = this.pools.get(type)
+    if (!bucket || bucket.length === 0) return null
+    return bucket.pop()!
+  }
+
+  release(cell: RecyclerCellInstance): void {
+    const { type } = cell
+    const bucket = this.pools.get(type)
+    const max = this.maxPerType.get(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/RecyclerList.tsx

@@ -0,0 +1,304 @@
+import React, { useRef, useEffect, useState } from 'react'
+import {
+  ScrollView,
+  View,
+  StyleSheet,
+  type NativeSyntheticEvent,
+  type NativeScrollEvent,
+} from 'react-native'
+
+import type { LayoutRect, VisibleRange } from '../types'
+import type {
+  RecyclerCellInstance,
+  RecyclerListProps,
+} from '../types/recycler'
+import type { CellType } from '../types/CellType'
+
+import { MutableLinearLayout } from '../layout/MutableLinearLayout'
+import { computeVisibleItemRange } from '../windowing'
+import { CellPool } from './CellPool'
+
+/* =========================================================
+ * Constants
+ * =======================================================*/
+
+const DEFAULT_VIEWPORT_SIZE = 800
+const DEFAULT_ITEM_SIZE = 60
+const SCROLL_EVENT_THROTTLE = 16
+
+/* =========================================================
+ * RecyclerList
+ * =======================================================*/
+
+export function RecyclerList<T>(
+  props: RecyclerListProps<T>
+): React.ReactElement {
+  const {
+    scrollDirection = 'vertical',
+    containerCrossAxisSize,
+    data,
+    itemMainAxisSizes,
+    padding = { start: 0, end: 0 },
+    itemSpacing,
+    bufferRatio = 1.3,
+    getCellType,
+    renderItem,
+  } = props
+
+  const isVertical = scrollDirection === 'vertical'
+  const itemCount = data.length
+
+  /* -------------------------------------------------------
+   * Controlled render
+   * -----------------------------------------------------*/
+
+  const [, forceRender] = useState(0)
+
+  /* -------------------------------------------------------
+   * Layout engine
+   * -----------------------------------------------------*/
+
+  const layoutEngineRef = useRef<MutableLinearLayout | null>(null)
+  const layoutSignatureRef = useRef('')
+
+  const layoutSignature = [
+    scrollDirection,
+    containerCrossAxisSize,
+    itemCount,
+    itemMainAxisSizes,
+    padding.start,
+    padding.end,
+    itemSpacing ?? 'default',
+  ].join('|')
+
+  if (
+    !layoutEngineRef.current ||
+    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 =
+    layoutEngineRef.current.getContentSize()
+
+  /* -------------------------------------------------------
+   * Scroll metrics
+   * -----------------------------------------------------*/
+
+  const scrollOffsetRef = useRef(0)
+  const viewportSizeRef = useRef(DEFAULT_VIEWPORT_SIZE)
+
+  /* -------------------------------------------------------
+   * Cell pool + physical cells
+   * -----------------------------------------------------*/
+
+  const cellPoolRef = useRef(new CellPool())
+  const activeCellsRef = useRef<RecyclerCellInstance[]>([])
+  const nextCellKeyRef = useRef(0)
+
+  const createCell = (type: CellType): RecyclerCellInstance => ({
+    key: nextCellKeyRef.current++,
+    index: -1,
+    type,
+  })
+
+  const MAX_CELLS = Math.ceil(
+    (viewportSizeRef.current / DEFAULT_ITEM_SIZE) *
+      bufferRatio
+  ) + 2
+
+  /* -------------------------------------------------------
+   * Visible cell coordinator
+   * -----------------------------------------------------*/
+
+  const updateVisibleCells = (): void => {
+    const offset = scrollOffsetRef.current
+    const viewportSize = viewportSizeRef.current
+    const buffer = viewportSize * bufferRatio
+
+    const range: VisibleRange | null =
+      computeVisibleItemRange({
+        layouts,
+        offset,
+        viewportSize,
+        buffer,
+        isVertical,
+      })
+
+    if (!range) return
+
+    const nextCells: RecyclerCellInstance[] = []
+    const used = new Set<RecyclerCellInstance>()
+
+    for (
+      let index = range.startIndex;
+      index <= range.endIndex;
+      index++
+    ) {
+      const item = data[index]
+      if (item === undefined) continue
+
+      const type = getCellType(item, index)
+
+      // Register type once, with hard cap
+      if (!cellPoolRef.current.hasType(type)) {
+        cellPoolRef.current.registerType(type, MAX_CELLS)
+        for (let i = 0; i < MAX_CELLS; i++) {
+          cellPoolRef.current.release(createCell(type))
+        }
+      }
+
+      let cell = cellPoolRef.current.acquire(type)
+
+      if (!cell) {
+        const reuseIndex =
+          activeCellsRef.current.findIndex(
+            c => c.type === type
+          )
+
+        if (reuseIndex === -1) continue
+
+        cell =
+          activeCellsRef.current.splice(
+            reuseIndex,
+            1
+          )[0]!
+      }
+
+      cell.index = index
+      nextCells.push(cell)
+      used.add(cell)
+    }
+
+    for (const cell of activeCellsRef.current) {
+      if (!used.has(cell)) {
+        cellPoolRef.current.release(cell)
+      }
+    }
+
+    let changed =
+      nextCells.length !== activeCellsRef.current.length
+
+    if (!changed) {
+      for (let i = 0; i < nextCells.length; i++) {
+        if (nextCells[i] !== activeCellsRef.current[i]) {
+          changed = true
+          break
+        }
+      }
+    }
+
+    if (changed) {
+      activeCellsRef.current = nextCells
+      forceRender(v => v + 1)
+    }
+  }
+
+  /* -------------------------------------------------------
+   * Scroll handlers
+   * -----------------------------------------------------*/
+
+  const frameScheduledRef = useRef(false)
+
+  const onScroll = (
+    e: NativeSyntheticEvent<NativeScrollEvent>
+  ): void => {
+    scrollOffsetRef.current = isVertical
+      ? e.nativeEvent.contentOffset.y
+      : e.nativeEvent.contentOffset.x
+
+    if (frameScheduledRef.current) return
+    frameScheduledRef.current = true
+
+    requestAnimationFrame(() => {
+      frameScheduledRef.current = false
+      updateVisibleCells()
+    })
+  }
+
+  const onLayout = (e: any): void => {
+    viewportSizeRef.current = isVertical
+      ? e.nativeEvent.layout.height
+      : e.nativeEvent.layout.width
+
+    updateVisibleCells()
+  }
+
+  useEffect(() => {
+    updateVisibleCells()
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [])
+
+  /* -------------------------------------------------------
+   * Render
+   * -----------------------------------------------------*/
+
+  return (
+    <ScrollView
+      onScroll={onScroll}
+      onLayout={onLayout}
+      horizontal={!isVertical}
+      scrollEventThrottle={SCROLL_EVENT_THROTTLE}
+      removeClippedSubviews
+    >
+      <View
+        style={
+          isVertical
+            ? { height: contentSize }
+            : { width: contentSize }
+        }
+      >
+        {activeCellsRef.current.map(cell => {
+          const index = cell.index
+          const layout = layouts[index]
+          const item = data[index]
+
+          if (!layout || 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 })}
+            </View>
+          )
+        })}
+      </View>
+    </ScrollView>
+  )
+}
+
+/* =========================================================
+ * Styles
+ * =======================================================*/
+
+const styles = StyleSheet.create({
+  cell: {
+    position: 'absolute',
+  },
+})

package/src/specs/nitro-layout-engine.nitro.ts

@@ -0,0 +1,17 @@
+import type { HybridObject } from 'react-native-nitro-modules'
+
+export interface LayoutRect {
+  readonly x: number
+  readonly y: number
+  readonly width: number
+  readonly height: number
+}
+
+export interface NitroLayoutEngine
+  extends HybridObject<{ ios: 'swift'; android: 'kotlin' }> {
+
+  computeLayout(
+    containerWidth: number,
+    itemHeights: readonly number[]
+  ): readonly LayoutRect[]
+}

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'