react-native-nitro-list 0.0.1 → 0.1.1

package/src/layout/LayoutRectangle.ts

@@ -0,0 +1,10 @@
+/**
+ * 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/layout/MutableLinearLayout.ts

@@ -0,0 +1,79 @@
+import type { LayoutRectangle } from './LayoutRectangle'
+
+/**
+ * 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.
+ */
+export class MutableLinearLayout {
+  private readonly layouts: MutableLayoutRectangle[]
+  private totalHeight: number
+
+  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
+    }
+
+    this.totalHeight = y
+  }
+
+  /**
+   * Read-only snapshot for consumers.
+   * Returned type is immutable.
+   */
+  getLayouts(): readonly LayoutRectangle[] {
+    return this.layouts
+  }
+
+  getContentHeight(): number {
+    return this.totalHeight
+  }
+
+  /**
+   * Update height of one item and shift following items.
+   * Returns true if layout changed.
+   */
+  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
+  }
+}

package/src/layout/index.ts

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

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,12 @@
+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

@@ -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/specs/nitro-layout-engine.nitro.ts

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

package/src/utils/arrayEqual.ts

@@ -0,0 +1,13 @@
+export function arrayEqual<T>(
+  a: readonly T[],
+  b: readonly T[]
+): boolean {
+  if (a === b) return true
+  if (a.length !== b.length) return false
+
+  for (let i = 0; i < a.length; i++) {
+    if (!Object.is(a[i], b[i])) return false
+  }
+
+  return true
+}

package/src/utils/assertNever.ts

@@ -0,0 +1,3 @@
+export function assertNever(x: never): never {
+  throw new Error(`Unexpected value: ${String(x)}`)
+}

package/src/utils/clamp.ts

@@ -0,0 +1,7 @@
+export function clamp(
+  value: number,
+  min: number,
+  max: number
+): number {
+  return Math.min(Math.max(value, min), max)
+}

package/src/utils/devAssert.ts

@@ -0,0 +1,8 @@
+export function devAssert(
+  condition: boolean,
+  message: string
+): void {
+  if (__DEV__ && !condition) {
+    throw new Error(`RecyclerList: ${message}`)
+  }
+}

package/src/utils/invariant.ts

@@ -0,0 +1,8 @@
+export function invariant(
+  condition: unknown,
+  message: string
+): asserts condition {
+  if (!condition) {
+    throw new Error(`Invariant failed: ${message}`)
+  }
+}

package/src/utils/isDefined.ts

@@ -0,0 +1,5 @@
+export function isDefined<T>(
+  value: T | undefined | null
+): value is T {
+  return value !== undefined && value !== null
+}

package/src/utils/isNumber.ts

@@ -0,0 +1,3 @@
+export function isNumber(value: unknown): value is number {
+  return typeof value === 'number' && !Number.isNaN(value)
+}

package/src/utils/noop.ts

@@ -0,0 +1,3 @@
+export function noop(): void {
+  // intentionally empty
+}

package/src/utils/shallowEqual.ts

@@ -0,0 +1,34 @@
+export function shallowEqual(
+  a: unknown,
+  b: unknown
+): boolean {
+  if (Object.is(a, b)) return true
+
+  if (
+    typeof a !== 'object' ||
+    typeof b !== 'object' ||
+    a === null ||
+    b === null
+  ) {
+    return false
+  }
+
+  const aKeys = Object.keys(a as object)
+  const bKeys = Object.keys(b as object)
+
+  if (aKeys.length !== bKeys.length) return false
+
+  for (const key of aKeys) {
+    if (
+      !(key in (b as object)) ||
+      !Object.is(
+        (a as Record<string, unknown>)[key],
+        (b as Record<string, unknown>)[key]
+      )
+    ) {
+      return false
+    }
+  }
+
+  return true
+}

package/src/utils/throttle.ts

@@ -0,0 +1,13 @@
+export function throttle<T extends (...args: never[]) => void>(
+  fn: T,
+  ms: number
+): T {
+  let last = 0
+  return ((...args: never[]) => {
+    const now = Date.now()
+    if (now - last > ms) {
+      last = now
+      fn(...args)
+    }
+  }) as T
+}

package/src/viewability/ViewabilityHelper.ts

@@ -0,0 +1,130 @@
+import type { LayoutRectangle } from '../layout/LayoutRectangle'
+import type { ScrollMetrics } from '../windowing/ScrollMetrics'
+
+/**
+ * Public token describing viewability state of an item.
+ * Mirrors FlashList's ViewToken concept.
+ */
+export type ViewToken = {
+  index: number
+  isViewable: boolean
+}
+
+/**
+ * Configuration for viewability calculations.
+ */
+export type ViewabilityConfig = {
+  /**
+   * Percentage (0–100) of item height that must be visible
+   * for the item to be considered "viewable".
+   */
+  itemVisiblePercentThreshold?: number
+}
+
+/**
+ * ViewabilityHelper
+ *
+ * Pure observer:
+ * - Does NOT affect layout
+ * - Does NOT affect recycling
+ * - Computes visibility based on layout + scroll metrics
+ *
+ * This class is intentionally stateful (lastVisible)
+ * to compute "changed" items efficiently.
+ */
+export class ViewabilityHelper {
+  /** Previously visible indices */
+  private lastVisible = new Set<number>()
+
+  constructor(
+    private readonly config: ViewabilityConfig = {}
+  ) {}
+
+  /**
+   * Computes which items are viewable and which changed
+   * since the last invocation.
+   *
+   * IMPORTANT:
+   * - This method should be called AFTER windowing,
+   *   not on the full dataset.
+   */
+  computeViewableItems(
+    layouts: readonly LayoutRectangle[],
+    metrics: ScrollMetrics
+  ): {
+    viewableItems: ViewToken[]
+    changed: ViewToken[]
+  } {
+    const visibleNow = new Set<number>()
+    const viewableItems: ViewToken[] = []
+    const changed: ViewToken[] = []
+
+    const viewportTop = metrics.offsetY
+    const viewportBottom = viewportTop + metrics.height
+
+    // Normalize threshold into [0, 1]
+    const threshold =
+      (this.config.itemVisiblePercentThreshold ?? 0) / 100
+
+    /**
+     * NOTE:
+     * We intentionally iterate layouts sequentially,
+     * but EXIT EARLY when items are completely below viewport.
+     *
+     * This keeps complexity near O(visibleItems),
+     * not O(totalItems).
+     */
+    for (let i = 0; i < layouts.length; i++) {
+      const layout = layouts[i]!
+
+      // If item is completely below viewport, stop
+      if (layout.y > viewportBottom) {
+        break
+      }
+
+      const itemTop = layout.y
+      const itemBottom = layout.y + layout.height
+
+      // If item is completely above viewport, skip
+      if (itemBottom < viewportTop) {
+        continue
+      }
+
+      // Compute visible intersection
+      const visibleTop = Math.max(itemTop, viewportTop)
+      const visibleBottom = Math.min(itemBottom, viewportBottom)
+
+      const visibleHeight = Math.max(0, visibleBottom - visibleTop)
+
+      // Guard against zero-height items
+      const itemHeight =
+        layout.height > 0 ? layout.height : 1
+
+      const visibleRatio = visibleHeight / itemHeight
+
+      if (visibleRatio >= threshold) {
+        visibleNow.add(i)
+        viewableItems.push({ index: i, isViewable: true })
+
+        // Newly visible
+        if (!this.lastVisible.has(i)) {
+          changed.push({ index: i, isViewable: true })
+        }
+      }
+    }
+
+    /**
+     * Items that were visible before but not anymore
+     */
+    for (const index of this.lastVisible) {
+      if (!visibleNow.has(index)) {
+        changed.push({ index, isViewable: false })
+      }
+    }
+
+    // Update snapshot
+    this.lastVisible = visibleNow
+
+    return { viewableItems, changed }
+  }
+}

package/src/windowing/ScrollMetrics.ts

@@ -0,0 +1,11 @@
+/**
+ * Immutable snapshot of scroll state.
+ * FlashList terminology.
+ */
+export interface ScrollMetrics {
+  /** Vertical scroll offset */
+  offsetY: number
+
+  /** Viewport height */
+  height: number
+}

package/src/windowing/findVisibleIndexRange.ts

@@ -0,0 +1,60 @@
+import type { LayoutRectangle } from '../layout/LayoutRectangle'
+import type { ScrollMetrics } from './ScrollMetrics'
+
+/**
+ * Computes the contiguous range of item indices
+ * intersecting the viewport expanded by bufferPx.
+ *
+ * PURE function. No allocations besides output.
+ * FlashList-style windowing.
+ */
+export function findVisibleIndexRange(
+  layouts: readonly LayoutRectangle[],
+  metrics: ScrollMetrics,
+  bufferPx: number
+): readonly number[] {
+  const count = layouts.length
+
+  // 🔒 CRITICAL GUARDS (FlashList-style)
+  if (
+    count === 0 ||
+    metrics.height <= 0 ||
+    bufferPx < 0
+  ) {
+    return []
+  }
+
+  const windowStart =
+    Math.max(0, metrics.offsetY - bufferPx)
+
+  const windowEnd =
+    metrics.offsetY + metrics.height + bufferPx
+
+  // Binary search for first intersecting item
+  let low = 0
+  let high = count - 1
+  let firstVisible = count
+
+  while (low <= high) {
+    const mid = (low + high) >> 1
+    const rect = layouts[mid]!
+
+    if (rect.y + rect.height >= windowStart) {
+      firstVisible = mid
+      high = mid - 1
+    } else {
+      low = mid + 1
+    }
+  }
+
+  // Linear scan forward
+  const visible: number[] = []
+
+  for (let i = firstVisible; i < count; i++) {
+    const rect = layouts[i]!
+    if (rect.y > windowEnd) break
+    visible.push(i)
+  }
+
+  return visible
+}

package/src/windowing/index.ts

@@ -0,0 +1,3 @@
+export type { ScrollMetrics } from './ScrollMetrics'
+export { findVisibleIndexRange } from './findVisibleIndexRange'
+export { useScrollMetrics } from './useScrollMetrics'

package/src/windowing/useScrollMetrics.ts

@@ -0,0 +1,56 @@
+import { useCallback, useState } from 'react'
+import type {
+  LayoutChangeEvent,
+  NativeScrollEvent,
+  NativeSyntheticEvent,
+} from 'react-native'
+import type { ScrollMetrics } from './ScrollMetrics'
+
+/**
+ * Scroll metrics hook.
+ * Provides stable scroll snapshot + handlers.
+ *
+ * FlashList equivalent: useScrollMetrics
+ */
+export function useScrollMetrics(): {
+  metrics: ScrollMetrics
+  onScroll: (e: NativeSyntheticEvent<NativeScrollEvent>) => void
+  onLayout: (e: LayoutChangeEvent) => void
+} {
+  const [metrics, setMetrics] = useState<ScrollMetrics>({
+    offsetY: 0,
+    height: 0,
+  })
+
+  const onScroll = useCallback(
+    (e: NativeSyntheticEvent<NativeScrollEvent>) => {
+      const offsetY = e.nativeEvent.contentOffset.y
+
+      setMetrics(prev =>
+        prev.offsetY === offsetY
+          ? prev
+          : { ...prev, offsetY }
+      )
+    },
+    []
+  )
+
+  const onLayout = useCallback(
+    (e: LayoutChangeEvent) => {
+      const height = e.nativeEvent.layout.height
+
+      setMetrics(prev =>
+        prev.height === height
+          ? prev
+          : { ...prev, height }
+      )
+    },
+    []
+  )
+
+  return {
+    metrics,
+    onScroll,
+    onLayout,
+  }
+}

package/android/src/main/java/com/nitrolist/HybridNitroList.kt

@@ -1,27 +0,0 @@
-package com.nitrolist
-
-import android.graphics.Color
-import android.view.View
-import androidx.annotation.Keep
-import com.facebook.proguard.annotations.DoNotStrip
-import com.facebook.react.uimanager.ThemedReactContext
-import com.margelo.nitro.nitrolist.HybridNitroListSpec
-
-@Keep
-@DoNotStrip
-class HybridNitroList(val context: ThemedReactContext): HybridNitroListSpec() {
-    // View
-    override val view: View = View(context)
-
-    // Props
-    private var _isRed = false
-    override var isRed: Boolean
-        get() = _isRed
-        set(value) {
-            _isRed = value
-            view.setBackgroundColor(
-                if (value) Color.RED
-                else Color.BLACK
-            )
-        }
-}

package/lib/module/specs/nitro-list.nitro.js

@@ -1,4 +0,0 @@
-"use strict";
-
-export {};
-//# sourceMappingURL=nitro-list.nitro.js.map

package/lib/typescript/src/specs/nitro-list.nitro.d.ts

@@ -1,11 +0,0 @@
-import type { HybridView, HybridViewProps, HybridViewMethods } from 'react-native-nitro-modules';
-export interface NitroListProps extends HybridViewProps {
-    isRed: boolean;
-}
-export interface NitroListMethods extends HybridViewMethods {
-}
-export type NitroList = HybridView<NitroListProps, NitroListMethods, {
-    ios: 'swift';
-    android: 'kotlin';
-}>;
-//# sourceMappingURL=nitro-list.nitro.d.ts.map

package/lib/typescript/src/specs/nitro-list.nitro.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"nitro-list.nitro.d.ts","sourceRoot":"","sources":["../../../../src/specs/nitro-list.nitro.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,UAAU,EACV,eAAe,EACf,iBAAiB,EAClB,MAAM,4BAA4B,CAAA;AAEnC,MAAM,WAAW,cAAe,SAAQ,eAAe;IACpD,KAAK,EAAE,OAAO,CAAA;CAChB;AAED,MAAM,WAAW,gBAAiB,SAAQ,iBAAiB;CAAG;AAE9D,MAAM,MAAM,SAAS,GAAG,UAAU,CAAC,cAAc,EAAE,gBAAgB,EAAE;IAAE,GAAG,EAAE,OAAO,CAAC;IAAC,OAAO,EAAE,QAAQ,CAAA;CAAE,CAAC,CAAA"}