react-native-nitro-list 0.1.1 → 0.1.2

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'
 
-/**
- * INTERNAL mutable layout record.
- * This is intentionally mutable and never exposed publicly.
- */
-type MutableLayoutRectangle = {
-  x: number
-  y: number
-  width: number
-  height: number
-}
+import { DEFAULT_ITEM_SPACING } from './constants/layoutDefaults'
 
 /**
- * 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/NitroList.types.ts

@@ -1,4 +1,5 @@
-import type { LayoutRectangle } from '../layout/LayoutRectangle'
+import type { LayoutRect } from "../types/layout";
+
 
 /**
  * JS runtime interface backed by Nitro (JSI).
@@ -8,5 +9,5 @@ export interface NitroList {
   computeLayout(
     containerWidth: number,
     itemHeights: readonly number[]
-  ): readonly LayoutRectangle[]
+  ): readonly LayoutRect[]
 }

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

@@ -1,6 +1,6 @@
 import type { HybridObject } from 'react-native-nitro-modules'
 
-export interface LayoutRectangle {
+export interface LayoutRect {
   readonly x: number
   readonly y: number
   readonly width: number
@@ -13,5 +13,5 @@ export interface NitroLayoutEngine
   computeLayout(
     containerWidth: number,
     itemHeights: readonly number[]
-  ): readonly LayoutRectangle[]
+  ): 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'

package/src/types/CellKey.ts

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

package/src/types/CellType.ts

@@ -0,0 +1,10 @@
+/**
+ * Logical cell type.
+ *
+ * Used to group compatible cells for recycling.
+ *
+ * Cross-platform equivalent:
+ * - Android: viewType
+ * - iOS: reuseIdentifier
+ */
+export type CellType = string | number

package/src/types/VisibleRange.ts

@@ -0,0 +1,9 @@
+/**
+ * Visible item index range.
+ *
+ * Indices are inclusive.
+ */
+export interface VisibleRange {
+  readonly startIndex: number
+  readonly endIndex: number
+}

package/src/types/VisibleRangeInput.ts

@@ -0,0 +1,39 @@
+import type { LayoutRect } from './layout/LayoutRect'
+
+/**
+ * Input required to compute the visible item range.
+ *
+ * Pure contract:
+ * - No logic
+ * - No platform assumptions
+ * - Safe to share with native / tests
+ */
+export interface VisibleRangeInput {
+  /**
+   * Ordered, monotonic layouts along the main axis.
+   * Required for binary search correctness.
+   */
+  readonly layouts: readonly LayoutRect[]
+
+  /**
+   * Scroll offset along the main axis.
+   */
+  readonly offset: number
+
+  /**
+   * Viewport size along the main axis.
+   */
+  readonly viewportSize: number
+
+  /**
+   * Extra buffer before and after the viewport.
+   */
+  readonly buffer: number
+
+  /**
+   * Axis selector.
+   * true  → vertical
+   * false → horizontal
+   */
+  readonly isVertical: boolean
+}

package/src/types/index.ts

@@ -0,0 +1,15 @@
+export type { Axis } from './Axis'
+
+export type {
+  MainAxisPadding,
+} from './layout/MainAxisPadding'
+export {
+  ZERO_MAIN_AXIS_PADDING,
+} from './layout/MainAxisPadding'
+
+export type { LayoutRect } from './layout/LayoutRect'
+export type { VisibleRange } from './VisibleRange'
+export type { CellKey } from './CellKey'
+export type { CellType } from './CellType'
+
+

package/src/types/layout/LayoutRect.ts

@@ -0,0 +1,14 @@
+/**
+ * Absolute layout rectangle.
+ *
+ * Cross-platform equivalent of:
+ * - Flutter: Rect
+ * - Android: Rect
+ * - iOS: CGRect
+ */
+export interface LayoutRect {
+  readonly x: number
+  readonly y: number
+  readonly width: number
+  readonly height: number
+}

package/src/types/layout/LinearLayoutInput.ts

@@ -0,0 +1,12 @@
+import type { MainAxisPadding } from './MainAxisPadding'
+
+export interface LinearLayoutInput {
+  readonly crossAxisSize: number
+  readonly itemMainAxisSizes: readonly number[]
+
+  /** Padding before/after content (main axis) */
+  readonly padding: MainAxisPadding
+
+  /** Space BETWEEN items (main axis) */
+  readonly itemSpacing?: number
+}