@leonsilicon/react-native-reanimated-carousel 0.0.0

package/src/utils/size-resolver.ts

@@ -0,0 +1,216 @@
+import type { SharedValue } from "react-native-reanimated";
+
+/**
+ * Worklet-safe abstraction over per-item sizes. Lets every position-math site
+ * read `offsetAt(i)` / `indexAt(offset)` instead of multiplying by a scalar
+ * `size`. Two implementations:
+ *
+ * - Uniform: backed by a single scalar; O(1) for every operation.
+ * - Variable: backed by a prefix-sum SharedValue<number[]>; O(log n) for
+ *   `indexAt`, with a cached-hint fast path for sequential scrolls.
+ */
+export interface SizeResolver {
+  /**
+   * `true` when sizes vary per item (variable mode). UI-thread reads should be
+   * cheap — this flag lives outside SharedValues so worklets can branch on it.
+   */
+  readonly variable: boolean;
+  /** Total span across all items: sum of every item's size. */
+  readonly total: SharedValue<number>;
+  /** Number of items (must equal `prefix.length - 1` in variable mode). */
+  readonly count: SharedValue<number>;
+  /** Size of item at `index`. Worklet-safe. */
+  itemSize: (index: number) => number;
+  /** Start offset of item at `index` (sum of sizes of items [0, index)). Worklet-safe. */
+  offsetAt: (index: number) => number;
+  /** Index of the item that contains pixel `offset` from the start. Worklet-safe. */
+  indexAt: (offset: number) => number;
+  /** Center offset of item at `index`: `offsetAt(index) + itemSize(index) / 2`. Worklet-safe. */
+  midpointOf: (index: number) => number;
+}
+
+/**
+ * Binary search the prefix-sum array for the index `i` such that
+ * `prefix[i] <= target < prefix[i+1]`. Clamps to `[0, length-1]`.
+ *
+ * Worklet-callable. `prefix` should have `length === itemCount + 1` so that
+ * `prefix[itemCount]` equals the total span.
+ */
+export function binarySearchPrefix(prefix: number[], target: number): number {
+  "worklet";
+  const n = prefix.length - 1;
+  if (n <= 0) return 0;
+  if (target <= prefix[0]) return 0;
+  if (target >= prefix[n]) return n - 1;
+
+  let lo = 0;
+  let hi = n - 1;
+  while (lo <= hi) {
+    const mid = (lo + hi) >> 1;
+    const start = prefix[mid];
+    const end = prefix[mid + 1];
+    if (target < start) hi = mid - 1;
+    else if (target >= end) lo = mid + 1;
+    else return mid;
+  }
+  return Math.max(0, Math.min(n - 1, lo));
+}
+
+/**
+ * Cached-hint variant: checks `hint`, `hint+1`, `hint-1` before falling back to
+ * full binary search. The common case during a single gesture is that the
+ * answer either stays the same or moves by ±1, so this keeps amortized cost at
+ * O(1) for typical scroll patterns.
+ */
+export function binarySearchPrefixCached(prefix: number[], target: number, hint: number): number {
+  "worklet";
+  const n = prefix.length - 1;
+  if (n <= 0) return 0;
+
+  const clampedHint = Math.max(0, Math.min(n - 1, hint));
+  // Check hint, hint+1, hint-1 first.
+  for (let delta = 0; delta <= 1; delta++) {
+    const i = clampedHint + delta;
+    if (i >= 0 && i < n && target >= prefix[i] && target < prefix[i + 1]) return i;
+    if (delta === 0) continue;
+    const j = clampedHint - delta;
+    if (j >= 0 && j < n && target >= prefix[j] && target < prefix[j + 1]) return j;
+  }
+  return binarySearchPrefix(prefix, target);
+}
+
+/**
+ * Creates a resolver for the uniform-size case. The scalar `size` is read on
+ * every call so callers always get the latest value. The owner is responsible
+ * for keeping `total` in sync with `size * count` (typically via
+ * `useAnimatedReaction`).
+ *
+ * `size` may be `SharedValue<number | null>` — `null` is treated as 0, which
+ * lets callers pass `common.resolvedSize` directly without a cast.
+ */
+export function createUniformSizeResolver(opts: {
+  size: SharedValue<number | null> | SharedValue<number>;
+  count: SharedValue<number>;
+  total: SharedValue<number>;
+}): SizeResolver {
+  const { size, count, total } = opts;
+
+  const readSize = () => {
+    "worklet";
+    const v = (size as SharedValue<number | null>).value;
+    return typeof v === "number" ? v : 0;
+  };
+
+  return {
+    variable: false,
+    total,
+    count,
+    itemSize: (_index: number) => {
+      "worklet";
+      return readSize();
+    },
+    offsetAt: (index: number) => {
+      "worklet";
+      return readSize() * index;
+    },
+    indexAt: (offset: number) => {
+      "worklet";
+      const s = readSize();
+      if (s <= 0) return 0;
+      return Math.round(offset / s);
+    },
+    midpointOf: (index: number) => {
+      "worklet";
+      const s = readSize();
+      return s * index + s / 2;
+    },
+  };
+}
+
+/**
+ * Creates a resolver backed by a prefix-sum array. `prefix[i]` is the sum of
+ * sizes of items `[0, i)`, so `prefix[0] === 0` and `prefix[count] === total`.
+ * `sizes` is `[size(0), size(1), ..., size(count-1)]`.
+ *
+ * `hint` is an optional SharedValue used as the seed for `indexAt`'s cached
+ * binary search; passing the previous result keeps lookups O(1) during
+ * continuous scrolls.
+ */
+export function createVariableSizeResolver(opts: {
+  sizes: SharedValue<number[]>;
+  prefix: SharedValue<number[]>;
+  total: SharedValue<number>;
+  count: SharedValue<number>;
+  hint?: SharedValue<number>;
+}): SizeResolver {
+  const { sizes, prefix, total, count, hint } = opts;
+
+  return {
+    variable: true,
+    total,
+    count,
+    itemSize: (index: number) => {
+      "worklet";
+      const arr = sizes.value;
+      const n = arr.length;
+      if (n === 0) return 0;
+      if (index < 0) return arr[0];
+      if (index >= n) return arr[n - 1];
+      return arr[index];
+    },
+    offsetAt: (index: number) => {
+      "worklet";
+      const arr = prefix.value;
+      const n = arr.length;
+      if (n === 0) return 0;
+      if (index <= 0) return 0;
+      if (index >= n) return arr[n - 1];
+      return arr[index];
+    },
+    indexAt: (offset: number) => {
+      "worklet";
+      const arr = prefix.value;
+      if (arr.length <= 1) return 0;
+      if (hint) {
+        const found = binarySearchPrefixCached(arr, offset, hint.value);
+        hint.value = found;
+        return found;
+      }
+      return binarySearchPrefix(arr, offset);
+    },
+    midpointOf: (index: number) => {
+      "worklet";
+      const prefixArr = prefix.value;
+      const sizesArr = sizes.value;
+      const n = sizesArr.length;
+      if (n === 0) return 0;
+      const clamped = Math.max(0, Math.min(n - 1, index));
+      return prefixArr[clamped] + sizesArr[clamped] / 2;
+    },
+  };
+}
+
+/**
+ * Builds a `(sizes, prefix, total)` tuple from a `getItemSize(index)` getter.
+ * JS-thread, O(n). Returns plain arrays — callers ferry them into SharedValues.
+ *
+ * Guards against non-finite or non-positive sizes by treating them as 0 so the
+ * carousel doesn't NaN-out. `usePropsErrorBoundary` warns the user separately.
+ */
+export function buildPrefixSum(
+  count: number,
+  getItemSize: (index: number) => number
+): { sizes: number[]; prefix: number[]; total: number } {
+  const sizes = new Array<number>(count);
+  const prefix = new Array<number>(count + 1);
+  prefix[0] = 0;
+  let running = 0;
+  for (let i = 0; i < count; i++) {
+    const raw = getItemSize(i);
+    const safe = Number.isFinite(raw) && raw > 0 ? raw : 0;
+    sizes[i] = safe;
+    running += safe;
+    prefix[i + 1] = running;
+  }
+  return { sizes, prefix, total: running };
+}