react-native-nitro-list 0.0.1 → 0.1.1

package/src/RecyclerList.tsx

@@ -0,0 +1,252 @@
+import React, {
+  useMemo,
+  useRef,
+  useEffect,
+} from 'react'
+import {
+  ScrollView,
+  View,
+  StyleSheet,
+} from 'react-native'
+
+import type { Cell } from './cell/Cell'
+import type { LayoutRectangle } from './layout/LayoutRectangle'
+
+import { useRecyclerListInternal } from './RecyclerList.internal'
+import { useScrollMetrics } from './windowing'
+import { MutableLinearLayout } from './layout/MutableLinearLayout'
+import { ViewabilityHelper } from './viewability/ViewabilityHelper'
+import { PrefetchHelper } from './prefetch/PrefetchHelper'
+
+/**
+ * Public API — mirrors FlashList behavior, not internals.
+ */
+export type RecyclerListProps = {
+  containerWidth: number
+  itemCount?: number
+  itemHeights?: readonly number[]
+  estimatedItemHeight?: number
+  renderBufferRatio?: number
+  getItemType?: (index: number) => string
+  renderItem: (index: number) => React.ReactElement
+  onPrefetch?: (indices: number[]) => void
+  onViewableItemsChanged?: (info: {
+    viewableItems: { index: number; isViewable: boolean }[]
+    changed: { index: number; isViewable: boolean }[]
+  }) => void
+}
+
+/**
+ * FlashList invariant:
+ * Never allow viewport height = 0 to gate windowing.
+ */
+const DEFAULT_VIEWPORT_HEIGHT = 800
+
+export function RecyclerList(props: RecyclerListProps): React.ReactElement {
+  const {
+    containerWidth,
+    itemCount,
+    itemHeights,
+    estimatedItemHeight = 80,
+    renderBufferRatio = 1.3,
+    getItemType = () => 'default',
+    renderItem,
+    onPrefetch,
+    onViewableItemsChanged,
+  } = props
+
+  /**
+   * 🚨 DEV WARNINGS ONLY (never throw in render!)
+   */
+  if (__DEV__) {
+    if (!itemHeights && itemCount == null) {
+      console.error(
+        'RecyclerList requires either itemCount or itemHeights.'
+      )
+    }
+
+    if (itemHeights && itemCount != null) {
+      console.error(
+        'Provide only one of itemCount or itemHeights.'
+      )
+    }
+  }
+
+  /**
+   * STEP 1: Resolve item count safely (props only).
+   * Never depend on hooks for structural decisions.
+   */
+  const itemLength =
+    itemHeights?.length ??
+    itemCount ??
+    0
+
+  /**
+   * STEP 2: Resolve initial heights (always defined).
+   */
+  const resolvedHeights = useMemo<readonly number[]>(() => {
+    if (itemHeights) return itemHeights
+
+    return Array.from(
+      { length: itemLength },
+      () => estimatedItemHeight
+    )
+  }, [itemHeights, itemLength, estimatedItemHeight])
+
+  /**
+   * STEP 3: Mutable layout lifecycle.
+   * Recreate layout only when shape changes.
+   */
+  const layoutRef = useRef<MutableLinearLayout | null>(null)
+  const lastLayoutKeyRef = useRef<string | null>(null)
+
+  const layoutKey = `${containerWidth}-${itemLength}`
+
+  if (
+    !layoutRef.current ||
+    lastLayoutKeyRef.current !== layoutKey
+  ) {
+    layoutRef.current = new MutableLinearLayout(
+      resolvedHeights,
+      containerWidth
+    )
+    lastLayoutKeyRef.current = layoutKey
+  }
+
+  /**
+   * STEP 4: Read layout snapshot.
+   */
+  const layouts: readonly LayoutRectangle[] =
+    layoutRef.current.getLayouts()
+
+  const contentHeight =
+    layoutRef.current.getContentHeight()
+
+  /**
+   * STEP 5: Scroll metrics.
+   */
+  const {
+    metrics,
+    onScroll,
+    onLayout,
+  } = useScrollMetrics()
+
+  /**
+   * STEP 6: Guard initial windowing.
+   */
+  const effectiveViewportHeight =
+    metrics.height > 0
+      ? metrics.height
+      : DEFAULT_VIEWPORT_HEIGHT
+
+  const bufferPx =
+    effectiveViewportHeight * renderBufferRatio
+
+  /**
+   * STEP 7: Windowing + recycling.
+   */
+  const cells: readonly Cell[] =
+    useRecyclerListInternal(
+      layouts,
+      metrics,
+      bufferPx,
+      getItemType
+    )
+
+  /**
+   * STEP 8: Phase-1 observers.
+   */
+  const viewabilityRef = useRef(
+    new ViewabilityHelper({
+      itemVisiblePercentThreshold: 50,
+    })
+  )
+
+  const prefetchRef = useRef(
+    new PrefetchHelper()
+  )
+
+  useEffect(() => {
+    prefetchRef.current = new PrefetchHelper()
+  }, [itemLength])
+
+  useEffect(() => {
+    if (metrics.height === 0) return
+
+    if (onViewableItemsChanged) {
+      const visibleLayouts: LayoutRectangle[] = []
+
+      for (const cell of cells) {
+        const layout = layouts[cell.index]
+        if (layout) visibleLayouts.push(layout)
+      }
+
+      const info =
+        viewabilityRef.current.computeViewableItems(
+          visibleLayouts,
+          metrics
+        )
+
+      onViewableItemsChanged(info)
+    }
+
+    if (onPrefetch && itemLength > 0) {
+      prefetchRef.current.runPrefetch(
+        cells.map(c => c.index),
+        itemLength,
+        5,
+        onPrefetch
+      )
+    }
+  }, [
+    cells,
+    metrics.offsetY,
+    metrics.height,
+    onViewableItemsChanged,
+    onPrefetch,
+    itemLength,
+    layouts,
+  ])
+
+  /**
+   * STEP 9: Render absolutely positioned cells.
+   */
+  return (
+    <ScrollView
+      style={styles.container}
+      onLayout={onLayout}
+      onScroll={onScroll}
+      scrollEventThrottle={16}
+      removeClippedSubviews
+    >
+      <View style={[styles.content, { height: contentHeight }]}>
+        {cells.map(cell => {
+          const layout = layouts[cell.index]
+          if (!layout) return null
+
+          return (
+            <View
+              key={cell.key}
+              style={[
+                styles.cell,
+                {
+                  top: layout.y,
+                  width: layout.width,
+                  height: layout.height,
+                },
+              ]}
+            >
+              {renderItem(cell.index)}
+            </View>
+          )
+        })}
+      </View>
+    </ScrollView>
+  )
+}
+
+const styles = StyleSheet.create({
+  container: { flex: 1 },
+  content: { position: 'relative', width: '100%' },
+  cell: { position: 'absolute', left: 0 },
+})

package/src/RecyclerList.types.ts

@@ -0,0 +1,24 @@
+import type React from 'react'
+
+export type RecyclerListProps = {
+  /** Width of the list container (required) */
+  readonly containerWidth: number
+
+  /** Total number of items (used with estimatedItemHeight) */
+  readonly itemCount?: number
+
+  /** Explicit item heights (fast path, skips estimation) */
+  readonly itemHeights?: readonly number[]
+
+  /** Estimated item height when itemHeights not provided */
+  readonly estimatedItemHeight?: number
+
+  /** Render buffer multiplier (FlashList-style, default ~1.3) */
+  readonly renderBufferRatio?: number
+
+  /** Optional item type resolver for recycling */
+  readonly getItemType?: (index: number) => string
+
+  /** Render function */
+  readonly renderItem: (index: number) => React.ReactElement
+}

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/__tests__/windowing/findVisibleIndexRange.test.ts

@@ -0,0 +1,55 @@
+import { findVisibleIndexRange } from '../../windowing/findVisibleIndexRange'
+
+describe('findVisibleIndexRange', () => {
+  /**
+   * Layouts:
+   * index 0 → y: 0–50
+   * index 1 → y: 50–100
+   * index 2 → y: 100–150
+   * ...
+   */
+  const layouts = Array.from({ length: 10 }, (_, i) => ({
+    x: 0,
+    y: i * 50,
+    width: 100,
+    height: 50,
+  }))
+
+  it('returns empty array when layouts are empty', () => {
+    const result = findVisibleIndexRange([], { offsetY: 0, height: 300 }, 100)
+
+    expect(result).toEqual([])
+  })
+  it('returns correct visible indices without buffer', () => {
+    const result = findVisibleIndexRange(
+      layouts,
+      { offsetY: 100, height: 150 },
+      0
+    )
+
+    /**
+     * Viewport: 100–250 (inclusive)
+     * Items that intersect this window:
+     * indices 1–5
+     */
+    expect(result).toEqual([1, 2, 3, 4, 5])
+  })
+
+  it('extends window using bufferPx (inclusive boundaries)', () => {
+    const result = findVisibleIndexRange(
+      layouts,
+      { offsetY: 100, height: 100 },
+      100
+    )
+
+    /**
+     * Viewport:      100–200
+     * Buffer:        ±100
+     * Effective win: 0–300 (inclusive)
+     *
+     * index 6 starts at y = 300 → included by design
+     * This matches FlashList / RecyclerView behavior
+     */
+    expect(result).toEqual([0, 1, 2, 3, 4, 5, 6])
+  })
+})

package/src/cell/Cell.ts

@@ -0,0 +1,14 @@
+/**
+ * Physical reusable cell.
+ * Mirrors FlashList's Cell abstraction.
+ */
+export interface Cell {
+  /** Stable physical identity (never changes) */
+  readonly key: string
+
+  /** Logical data index currently bound */
+  index: number
+
+  /** Compatibility type (row, header, etc.) */
+  readonly type: string
+}

package/src/cell/CellRecycler.ts

@@ -0,0 +1,66 @@
+import type { Cell } from './Cell'
+
+const MAX_CELLS = 40
+
+/**
+ * Owns physical cell reuse.
+ * Stateful, imperative, React-agnostic.
+ *
+ * FlashList equivalent: CellRecycler
+ */
+export class CellRecycler {
+  private readonly activeCells = new Map<number, Cell>()
+  private readonly reusableCellsByType = new Map<string, Cell[]>()
+  private readonly orderedCells: Cell[] = []
+  private nextCellId = 0
+
+  /**
+   * Reconcile visible indices against existing cells.
+   * Returns a stable ordered snapshot.
+   */
+  reconcile(
+    visibleIndices: readonly number[],
+    getCellType: (index: number) => string
+  ): readonly Cell[] {
+    const visibleSet = new Set(visibleIndices)
+
+    // 1️⃣ Release cells no longer visible
+    for (const [index, cell] of this.activeCells) {
+      if (visibleSet.has(index)) continue
+
+      this.activeCells.delete(index)
+
+      const orderedIndex = this.orderedCells.indexOf(cell)
+      if (orderedIndex !== -1) {
+        this.orderedCells.splice(orderedIndex, 1)
+      }
+
+      const pool = this.reusableCellsByType.get(cell.type) ?? []
+      if (pool.length < MAX_CELLS) pool.push(cell)
+      this.reusableCellsByType.set(cell.type, pool)
+    }
+
+    // 2️⃣ Acquire cells for newly visible indices
+    for (const index of visibleIndices) {
+      if (this.activeCells.has(index)) continue
+
+      const type = getCellType(index)
+      const pool = this.reusableCellsByType.get(type)
+      let cell = pool?.pop()
+
+      if (!cell) {
+        cell = {
+          key: `cell-${this.nextCellId++}`,
+          type,
+          index,
+        }
+      }
+
+      cell.index = index
+      this.activeCells.set(index, cell)
+      this.orderedCells.push(cell)
+    }
+
+    return this.orderedCells
+  }
+}

package/src/cell/StableKey.ts

@@ -0,0 +1,6 @@
+export function getStableKey(
+  slotKey: string,
+  index: number
+): string {
+  return `${slotKey}:${index}`
+}

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,53 @@
+import type { LayoutRectangle } from './layout/LayoutRectangle'
+import type { ScrollMetrics } from './windowing/ScrollMetrics'
+
+/**
+ * Binary-search based windowing.
+ * Returns indices intersecting viewport ± buffer.
+ */
+export function getVisibleRange(
+  layouts: readonly LayoutRectangle[],
+  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
+}

package/src/hooks/useCellRenderer.ts

@@ -0,0 +1,86 @@
+import { useEffect, useMemo, useRef, useState } from 'react'
+import type { Cell } from '../cell/Cell'
+import { CellRecycler } from '../cell/CellRecycler'
+import { findVisibleIndexRange } from '../windowing/findVisibleIndexRange'
+import type { LayoutRectangle } from '../layout/LayoutRectangle'
+import type { ScrollMetrics } from '../windowing/ScrollMetrics'
+
+/**
+ * 🔒 Stable empty references (module-level)
+ * These MUST NOT be recreated per render.
+ */
+const EMPTY_INDICES: readonly number[] = []
+
+/**
+ * React bridge for CellRecycler.
+ * FlashList equivalent: useCellRenderer
+ *
+ * Responsibilities:
+ * - Translate scroll state → visible indices
+ * - Ask recycler for physical cells
+ * - Commit results with referential stability
+ *
+ * Responsibilities it does NOT have:
+ * ❌ Layout mutation
+ * ❌ Measurement
+ * ❌ Rendering
+ */
+export function useCellRenderer(
+  layouts: readonly LayoutRectangle[],
+  metrics: ScrollMetrics,
+  bufferPx: number,
+  getCellType: (index: number) => string
+): readonly Cell[] {
+  /**
+   * Recycler instance is stable across renders.
+   */
+  const recyclerRef = useRef<CellRecycler>(new CellRecycler())
+
+  /**
+   * Compute visible indices.
+   * PURE + TOTAL:
+   * - Never throws
+   * - Always returns the same reference when empty
+   */
+  const visibleIndices = useMemo(
+    () =>
+      layouts.length === 0
+        ? EMPTY_INDICES
+        : findVisibleIndexRange(
+            layouts,
+            metrics,
+            bufferPx
+          ),
+    [layouts, metrics.offsetY, metrics.height, bufferPx]
+  )
+
+  /**
+   * Physical cells to render.
+   */
+  const [cells, setCells] =
+    useState<readonly Cell[]>([])
+
+  /**
+   * Reconcile visible indices → physical cells.
+   *
+   * FlashList invariant:
+   * - Only update state if identity truly changed
+   * - Prevents pointless re-renders
+   */
+  useEffect(() => {
+    const next =
+      recyclerRef.current.reconcile(
+        visibleIndices,
+        getCellType
+      )
+
+    setCells(prev =>
+      prev.length === next.length &&
+      prev.every((c, i) => c === next[i])
+        ? prev
+        : next
+    )
+  }, [visibleIndices, getCellType])
+
+  return cells
+}

package/src/hooks/useStableCallback.ts

@@ -0,0 +1,13 @@
+import { useRef, useCallback } from 'react'
+
+export function useStableCallback<T extends (...args: never[]) => unknown>(
+  fn: T
+): T {
+  const ref = useRef(fn)
+  ref.current = fn
+
+  return useCallback(
+    ((...args: never[]) => ref.current(...args)) as T,
+    []
+  )
+}

package/src/index.ts

@@ -1,14 +1,2 @@
-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 './RecyclerList'
+export type { RecyclerListProps } from './RecyclerList.types'

package/src/layout/EstimatedLayoutProvider.ts

@@ -0,0 +1,35 @@
+import type { LayoutProvider } from './LayoutProvider'
+import type { LayoutRectangle } from './LayoutRectangle'
+
+/**
+ * Layout provider using estimated item heights.
+ * Used before real measurements are available.
+ */
+export class EstimatedLayoutProvider implements LayoutProvider {
+  private readonly itemCount: number
+  private readonly itemHeight: number
+  private readonly width: number
+
+  constructor(
+    itemCount: number,
+    itemHeight: number,
+    width: number
+  ) {
+    this.itemCount = itemCount
+    this.itemHeight = itemHeight
+    this.width = width
+  }
+
+  getItemCount(): number {
+    return this.itemCount
+  }
+
+  getLayout(index: number): LayoutRectangle {
+    return {
+      x: 0,
+      y: index * this.itemHeight,
+      width: this.width,
+      height: this.itemHeight,
+    }
+  }
+}

package/src/layout/LayoutEngine.ts

@@ -0,0 +1,21 @@
+import type { LayoutProvider } from './LayoutProvider'
+import type { LayoutRectangle } from './LayoutRectangle'
+
+/**
+ * Resolves layouts eagerly into a contiguous array.
+ * Pure, deterministic, and reusable.
+ *
+ * FlashList equivalent: internal layout resolver.
+ */
+export function computeLayouts(
+  provider: LayoutProvider
+): readonly LayoutRectangle[] {
+  const count = provider.getItemCount()
+  const layouts: LayoutRectangle[] = new Array(count)
+
+  for (let i = 0; i < count; i++) {
+    layouts[i] = provider.getLayout(i)
+  }
+
+  return layouts
+}

package/src/layout/LayoutProvider.ts

@@ -0,0 +1,17 @@
+import type { LayoutRectangle } from './LayoutRectangle'
+
+/**
+ * Provides layout information for items.
+ * FlashList equivalent: LayoutProvider
+ */
+export interface LayoutProvider {
+  /**
+   * Total number of items
+   */
+  getItemCount(): number
+
+  /**
+   * Layout rectangle for a given index
+   */
+  getLayout(index: number): LayoutRectangle
+}