react-native-nitro-list 0.0.1 → 0.1.2

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
+}

package/src/types/layout/MainAxisPadding.ts

@@ -0,0 +1,23 @@
+/**
+ * Padding applied along the main scroll axis.
+ *
+ * This is a layout-level concept (not visual styling).
+ *
+ * - vertical   → top / bottom
+ * - horizontal → left / right
+ *
+ * Uses start/end to remain RTL-safe and platform-neutral.
+ */
+export interface MainAxisPadding {
+  readonly start: number
+  readonly end: number
+}
+
+/**
+ * Shared zero-padding constant.
+ * Safe to reuse across layouts.
+ */
+export const ZERO_MAIN_AXIS_PADDING: MainAxisPadding = {
+  start: 0,
+  end: 0,
+}

package/src/types/layout/index.ts

@@ -0,0 +1,3 @@
+export type { LayoutRect } from './LayoutRect'
+export type { LinearLayoutInput } from './LinearLayoutInput'
+export type { MainAxisPadding } from './MainAxisPadding'

package/src/types/recycler/RecyclerCellInstance.ts

@@ -0,0 +1,40 @@
+import type { CellKey } from "../CellKey"
+import type { CellType } from "../CellType"
+
+
+/**
+ * Physical reusable cell instance.
+ *
+ * Represents a single mounted view that can be rebound
+ * to different data items as scrolling occurs.
+ *
+ * Cross-platform equivalent:
+ * - Flutter: Element / RenderObject
+ * - Android: ViewHolder
+ * - iOS: UICollectionViewCell
+ */
+export interface RecyclerCellInstance {
+  /**
+   * Stable physical identity.
+   *
+   * Used as React key.
+   * MUST remain constant for the lifetime of the instance.
+   */
+  readonly key: CellKey
+
+  /**
+   * Logical data index currently bound to this instance.
+   *
+   * This value changes as the cell is recycled.
+   * - -1 may be used to indicate "unbound".
+   */
+  index: number
+
+  /**
+   * Logical compatibility type.
+   *
+   * Determines which instances can be reused together.
+   * Instances with different types MUST NOT be reused.
+   */
+  readonly type: CellType
+}

package/src/types/recycler/RecyclerItemRenderer.ts

@@ -0,0 +1,8 @@
+import type { ReactNode } from 'react'
+import type { RecyclerCellInstance } from './RecyclerCellInstance'
+
+export type RecyclerItemRenderer<T> = (params: {
+  item: T
+  index: number
+  cell: RecyclerCellInstance
+}) => ReactNode

package/src/types/recycler/RecyclerListProps.ts

@@ -0,0 +1,74 @@
+import type { Axis } from '../Axis'
+import type { CellType } from '../CellType'
+import type { MainAxisPadding } from '../layout'
+import type { RecyclerItemRenderer } from './RecyclerItemRenderer'
+
+/**
+ * Public props for RecyclerList.
+ *
+ * Generic, data-driven, layout-deterministic API.
+ * This surface is intentionally minimal and stable.
+ */
+export interface RecyclerListProps<T> {
+  /**
+   * Scroll direction.
+   * Defaults to 'vertical'.
+   */
+  readonly scrollDirection?: Axis
+
+  /**
+   * Cross-axis size.
+   * - vertical   → width
+   * - horizontal → height
+   *
+   * Required for deterministic layout.
+   */
+  readonly containerCrossAxisSize: number
+
+  /**
+   * Data source.
+   * Length is the single source of truth for item count.
+   */
+  readonly data: readonly T[]
+
+  /**
+   * Item sizes along the main axis.
+   * Must match data length.
+   *
+   * - vertical   → heights
+   * - horizontal → widths
+   */
+  readonly itemMainAxisSizes: readonly number[]
+
+  /**
+   * Padding before and after content along the main axis.
+   *
+   * Defaults are applied internally by the layout engine.
+   */
+  readonly padding?: MainAxisPadding
+
+  /**
+   * Space BETWEEN items along the main axis.
+   *
+   * Defaults are applied internally by the layout engine.
+   */
+  readonly itemSpacing?: number
+
+  /**
+   * Extra render buffer as a ratio of viewport size.
+   * Used for overscan / pre-rendering.
+   */
+  readonly bufferRatio?: number
+
+  /**
+   * Logical cell type resolver.
+   * Determines recycling compatibility.
+   */
+  readonly getCellType: (item: T, index: number) => CellType
+
+  /**
+   * Item renderer.
+   * Receives stable cell identity and data.
+   */
+  readonly renderItem: RecyclerItemRenderer<T>
+}

package/src/types/recycler/index.ts

@@ -0,0 +1,3 @@
+export type { RecyclerListProps } from './RecyclerListProps'
+export type { RecyclerItemRenderer } from './RecyclerItemRenderer' 
+export type { RecyclerCellInstance } from './RecyclerCellInstance'  

package/src/types/scroll/ScrollMetrics.ts

@@ -0,0 +1,18 @@
+import type { Axis } from "../Axis"
+
+
+/**
+ * Scroll state snapshot.
+ *
+ * Pure data — no platform or React coupling.
+ */
+export interface ScrollMetrics {
+  /** Scroll axis */
+  readonly axis: Axis
+
+  /** Offset along the main axis */
+  readonly offset: number
+
+  /** Viewport size along the main axis */
+  readonly viewportSize: number
+}

package/src/types/scroll/index.ts

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

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/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/computeVisibleItemRange.ts

@@ -0,0 +1,78 @@
+import type { VisibleRange } from '../types/VisibleRange'
+import type { VisibleRangeInput } from '../types/VisibleRangeInput'
+
+/**
+ * Computes the visible item index range using binary search.
+ *
+ * Responsibilities:
+ * - Determine which items intersect the visible window
+ * - Stay independent of rendering and recycling
+ *
+ * Performance:
+ * - O(log n) to locate the first visible item
+ * - O(k) to expand to the last visible item (k = visible count)
+ */
+export function computeVisibleItemRange(
+  input: VisibleRangeInput
+): VisibleRange | null {
+  const {
+    layouts,
+    offset,
+    viewportSize,
+    buffer,
+    isVertical,
+  } = input
+
+  const itemCount = layouts.length
+  if (itemCount === 0) return null
+
+  const windowStart = Math.max(0, offset - buffer)
+  const windowEnd = offset + viewportSize + buffer
+
+  // --------------------------------------------------
+  // Binary search:
+  // First item whose END >= windowStart
+  // --------------------------------------------------
+  let low = 0
+  let high = itemCount - 1
+  let firstVisibleIndex = itemCount
+
+  while (low <= high) {
+    const mid = (low + high) >>> 1
+    const rect = layouts[mid]!
+
+    const start = isVertical ? rect.y : rect.x
+    const size = isVertical ? rect.height : rect.width
+    const end = start + size
+
+    if (end >= windowStart) {
+      firstVisibleIndex = mid
+      high = mid - 1
+    } else {
+      low = mid + 1
+    }
+  }
+
+  if (firstVisibleIndex === itemCount) {
+    return null
+  }
+
+  // --------------------------------------------------
+  // Linear scan forward:
+  // Last item whose START <= windowEnd
+  // --------------------------------------------------
+  let lastVisibleIndex = firstVisibleIndex
+
+  for (let i = firstVisibleIndex + 1; i < itemCount; i++) {
+    const rect = layouts[i]!
+    const start = isVertical ? rect.y : rect.x
+
+    if (start > windowEnd) break
+    lastVisibleIndex = i
+  }
+
+  return {
+    startIndex: firstVisibleIndex,
+    endIndex: lastVisibleIndex,
+  }
+}

package/src/windowing/index.ts

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

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"}

package/nitrogen/generated/android/c++/JHybridNitroListSpec.cpp

@@ -1,56 +0,0 @@
-///
-/// JHybridNitroListSpec.cpp
-/// This file was generated by nitrogen. DO NOT MODIFY THIS FILE.
-/// https://github.com/mrousavy/nitro
-/// Copyright © 2025 Marc Rousavy @ Margelo
-///
-
-#include "JHybridNitroListSpec.hpp"
-
-
-
-
-
-namespace margelo::nitro::nitrolist {
-
-  jni::local_ref<JHybridNitroListSpec::jhybriddata> JHybridNitroListSpec::initHybrid(jni::alias_ref<jhybridobject> jThis) {
-    return makeCxxInstance(jThis);
-  }
-
-  void JHybridNitroListSpec::registerNatives() {
-    registerHybrid({
-      makeNativeMethod("initHybrid", JHybridNitroListSpec::initHybrid),
-    });
-  }
-
-  size_t JHybridNitroListSpec::getExternalMemorySize() noexcept {
-    static const auto method = javaClassStatic()->getMethod<jlong()>("getMemorySize");
-    return method(_javaPart);
-  }
-
-  void JHybridNitroListSpec::dispose() noexcept {
-    static const auto method = javaClassStatic()->getMethod<void()>("dispose");
-    method(_javaPart);
-  }
-
-  std::string JHybridNitroListSpec::toString() {
-    static const auto method = javaClassStatic()->getMethod<jni::JString()>("toString");
-    auto javaString = method(_javaPart);
-    return javaString->toStdString();
-  }
-
-  // Properties
-  bool JHybridNitroListSpec::getIsRed() {
-    static const auto method = javaClassStatic()->getMethod<jboolean()>("isRed");
-    auto __result = method(_javaPart);
-    return static_cast<bool>(__result);
-  }
-  void JHybridNitroListSpec::setIsRed(bool isRed) {
-    static const auto method = javaClassStatic()->getMethod<void(jboolean /* isRed */)>("setRed");
-    method(_javaPart, isRed);
-  }
-
-  // Methods
-  
-
-} // namespace margelo::nitro::nitrolist