react-native-nitro-list 0.1.1 → 0.1.3

package/lib/typescript/src/windowing/findVisibleIndexRange.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"findVisibleIndexRange.d.ts","sourceRoot":"","sources":["../../../../src/windowing/findVisibleIndexRange.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,2BAA2B,CAAA;AAChE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAA;AAEpD;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,SAAS,eAAe,EAAE,EACnC,OAAO,EAAE,aAAa,EACtB,QAAQ,EAAE,MAAM,GACf,SAAS,MAAM,EAAE,CA6CnB"}

package/nitrogen/generated/ios/swift/HybridNitroLayoutEngineSpec.swift

@@ -1,56 +0,0 @@
-///
-/// HybridNitroLayoutEngineSpec.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
-
-/// See ``HybridNitroLayoutEngineSpec``
-public protocol HybridNitroLayoutEngineSpec_protocol: HybridObject {
-  // Properties
-  
-
-  // Methods
-  func computeLayout(containerWidth: Double, itemHeights: [Double]) throws -> [LayoutRectangle]
-}
-
-public extension HybridNitroLayoutEngineSpec_protocol {
-  /// Default implementation of ``HybridObject.toString``
-  func toString() -> String {
-    return "[HybridObject NitroLayoutEngine]"
-  }
-}
-
-/// See ``HybridNitroLayoutEngineSpec``
-open class HybridNitroLayoutEngineSpec_base {
-  private weak var cxxWrapper: HybridNitroLayoutEngineSpec_cxx? = nil
-  public init() { }
-  public func getCxxWrapper() -> HybridNitroLayoutEngineSpec_cxx {
-  #if DEBUG
-    guard self is HybridNitroLayoutEngineSpec else {
-      fatalError("`self` is not a `HybridNitroLayoutEngineSpec`! Did you accidentally inherit from `HybridNitroLayoutEngineSpec_base` instead of `HybridNitroLayoutEngineSpec`?")
-    }
-  #endif
-    if let cxxWrapper = self.cxxWrapper {
-      return cxxWrapper
-    } else {
-      let cxxWrapper = HybridNitroLayoutEngineSpec_cxx(self as! HybridNitroLayoutEngineSpec)
-      self.cxxWrapper = cxxWrapper
-      return cxxWrapper
-    }
-  }
-}
-
-/**
- * A Swift base-protocol representing the NitroLayoutEngine HybridObject.
- * Implement this protocol to create Swift-based instances of NitroLayoutEngine.
- * ```swift
- * class HybridNitroLayoutEngine : HybridNitroLayoutEngineSpec {
- *   // ...
- * }
- * ```
- */
-public typealias HybridNitroLayoutEngineSpec = HybridNitroLayoutEngineSpec_protocol & HybridNitroLayoutEngineSpec_base

package/src/NitroList.ts

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

package/src/RecyclerList.internal.ts

@@ -1,38 +0,0 @@
-import type { LayoutRectangle } from './layout/LayoutRectangle'
-import type { ScrollMetrics } from './windowing/ScrollMetrics'
-import type { Cell } from './cell/Cell'
-
-import { useCellRenderer } from './hooks/useCellRenderer'
-
-/**
- * INTERNAL hook.
- * MUST ALWAYS CALL hooks in the same order.
- */
-export function useRecyclerListInternal(
-  layouts: readonly LayoutRectangle[],
-  metrics: ScrollMetrics,
-  bufferPx: number,
-  getItemType: (index: number) => string
-): readonly Cell[] {
-
-  /**
-   * FlashList rule:
-   * Hooks are ALWAYS called.
-   * Inputs are guarded instead.
-   */
-  const safeLayouts =
-    metrics.height > 0 ? layouts : EMPTY_LAYOUTS
-
-  const safeBufferPx =
-    metrics.height > 0 ? bufferPx : 0
-
-  return useCellRenderer(
-    safeLayouts,
-    metrics,
-    safeBufferPx,
-    getItemType
-  )
-}
-
-/** Stable empty reference */
-const EMPTY_LAYOUTS: readonly LayoutRectangle[] = []

package/src/RecyclerList.tsx

@@ -1,252 +0,0 @@
-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

@@ -1,24 +0,0 @@
-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/__tests__/windowing/findVisibleIndexRange.test.ts

@@ -1,55 +0,0 @@
-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/StableKey.ts

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

package/src/hooks/useCellRenderer.ts

@@ -1,86 +0,0 @@
-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

@@ -1,13 +0,0 @@
-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/layout/EstimatedLayoutProvider.ts

@@ -1,35 +0,0 @@
-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

@@ -1,21 +0,0 @@
-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

@@ -1,17 +0,0 @@
-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
-}

package/src/layout/LayoutRectangle.ts

@@ -1,10 +0,0 @@
-/**
- * Immutable layout rectangle for a single item.
- * Equivalent to FlashList's Layout.
- */
-export interface LayoutRectangle {
-  readonly x: number
-  readonly y: number
-  readonly width: number
-  readonly height: number
-}

package/src/native/NitroLayoutEngine.ts

@@ -1,7 +0,0 @@
-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

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

package/src/native/NitroRecyclerView.ts

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

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

@@ -1,17 +0,0 @@
-import type { HybridObject } from 'react-native-nitro-modules'
-
-export interface LayoutRectangle {
-  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 LayoutRectangle[]
-}