@leonsilicon/react-native-reanimated-carousel 0.0.0

package/src/hooks/useOffsetX.ts

@@ -0,0 +1,109 @@
+import type { SharedValue } from "react-native-reanimated";
+import { Extrapolation, interpolate, useDerivedValue } from "react-native-reanimated";
+
+import type { SizeResolver } from "../utils/size-resolver";
+import type { IVisibleRanges } from "./useVisibleRanges";
+
+export interface IOpts {
+  index: number;
+  /**
+   * Uniform-mode item size. Used by the legacy callsites and tests that pass a
+   * scalar. When `resolver` is provided it takes precedence.
+   */
+  size: number;
+  handlerOffset: SharedValue<number>;
+  dataLength: number;
+  type?: "positive" | "negative";
+  viewCount?: number;
+  loop?: boolean;
+  /**
+   * Optional `SizeResolver`. When supplied, position math reads per-item
+   * offsets from the prefix-sum table instead of multiplying by `size`. Pass
+   * `undefined` for legacy uniform behavior.
+   */
+  resolver?: SizeResolver;
+}
+
+export const useOffsetX = (opts: IOpts, visibleRanges: IVisibleRanges) => {
+  const {
+    handlerOffset,
+    index,
+    size,
+    loop,
+    dataLength,
+    type = "positive",
+    viewCount: _viewCount,
+    resolver,
+  } = opts;
+
+  const ITEM_LENGTH = dataLength;
+  const VALID_LENGTH = ITEM_LENGTH - 1;
+
+  const viewCount = _viewCount ?? Math.round((ITEM_LENGTH - 1) / 2);
+  const positiveCount = type === "positive" ? viewCount : VALID_LENGTH - viewCount;
+
+  const x = useDerivedValue(() => {
+    // Resolve per-item geometry. In uniform mode we mirror the historical
+    // `size * index` math; in variable mode we read from the prefix-sum table
+    // via the resolver. Both branches converge on the same 7-anchor wrap
+    // interpolation, just with different inputs.
+    const useResolver = resolver?.variable === true;
+    const totalLength = useResolver ? resolver!.total.value : size * ITEM_LENGTH;
+    const itemSize = useResolver ? resolver!.itemSize(index) : size;
+    const halfItem = 0.5 * itemSize;
+
+    if ((!useResolver && !size) || (useResolver && totalLength <= 0)) return 0;
+
+    const { negativeRange, positiveRange } = visibleRanges.value;
+    const inWindow =
+      (index >= negativeRange[0] && index <= negativeRange[1]) ||
+      (index >= positiveRange[0] && index <= positiveRange[1]);
+    if (!inWindow) return Number.MAX_SAFE_INTEGER;
+
+    // Natural start position of this item along the scroll axis.
+    let startPos = useResolver ? resolver!.offsetAt(index) : size * index;
+    if (index > positiveCount) {
+      // Item is past the forward edge of the viewing window — wrap it to the
+      // negative side so it can re-enter from the other end during a loop.
+      startPos = useResolver
+        ? resolver!.offsetAt(index) - totalLength
+        : (index - ITEM_LENGTH) * size;
+    }
+
+    // Cutoffs for the wrap-around. In uniform mode these are offsets to the
+    // window edges; in variable mode they're offsets to the (positiveCount)-th
+    // item's start.
+    const MAX = useResolver ? resolver!.offsetAt(positiveCount) : positiveCount * size;
+    const MIN = useResolver
+      ? -(totalLength - resolver!.offsetAt(positiveCount + 1))
+      : -((VALID_LENGTH - positiveCount) * size);
+
+    if (loop) {
+      const inputRange = [
+        -totalLength,
+        MIN - halfItem - startPos - Number.MIN_VALUE,
+        MIN - halfItem - startPos,
+        0,
+        MAX + halfItem - startPos,
+        MAX + halfItem - startPos + Number.MIN_VALUE,
+        totalLength,
+      ];
+
+      const outputRange = [
+        startPos,
+        MAX + halfItem - Number.MIN_VALUE,
+        MIN - halfItem,
+        startPos,
+        MAX + halfItem,
+        MIN - halfItem + Number.MIN_VALUE,
+        startPos,
+      ];
+
+      return interpolate(handlerOffset.value, inputRange, outputRange, Extrapolation.CLAMP);
+    }
+
+    return handlerOffset.value + (useResolver ? resolver!.offsetAt(index) : size * index);
+  }, [loop, dataLength, viewCount, type, size, visibleRanges, handlerOffset, resolver]);
+
+  return x;
+};

package/src/hooks/useOnProgressChange.test.tsx

@@ -0,0 +1,207 @@
+import { useSharedValue } from "react-native-reanimated";
+
+import { renderHook } from "@testing-library/react-hooks";
+
+import { useOnProgressChange } from "./useOnProgressChange";
+
+// Mock Reanimated and Easing
+jest.mock("react-native-reanimated", () => {
+  let reactionCallback: ((value: any) => void) | null = null;
+
+  return {
+    useSharedValue: jest.fn((initialValue) => ({
+      value: initialValue,
+    })),
+    useAnimatedReaction: jest.fn((deps, cb) => {
+      reactionCallback = cb;
+      const depsResult = deps();
+      cb(depsResult);
+      return () => {
+        reactionCallback = null;
+      };
+    }),
+    Easing: {
+      bezier: () => ({
+        factory: () => 0,
+      }),
+    },
+    // Export the helper function for testing
+    __triggerReaction: (value: any) => {
+      if (reactionCallback) reactionCallback(value);
+    },
+  };
+});
+
+jest.mock("react-native-worklets", () => {
+  const mockScheduleOnRN = jest.fn((fn, ...args) => fn(...args));
+  return {
+    scheduleOnRN: mockScheduleOnRN,
+    mockScheduleOnRN,
+  };
+});
+
+// Mock computedOffsetXValueWithAutoFillData
+jest.mock("../utils/computed-with-auto-fill-data", () => ({
+  computedOffsetXValueWithAutoFillData: jest.fn(({ value }) => value),
+}));
+
+describe("useOnProgressChange", () => {
+  const mockOffsetX = useSharedValue(0);
+  const mockSizeReady = useSharedValue(true);
+  const mockOnProgressChange = jest.fn();
+  const { __triggerReaction } = jest.requireMock("react-native-reanimated");
+
+  beforeEach(() => {
+    jest.clearAllMocks();
+    mockOffsetX.value = 0;
+  });
+
+  it("should handle progress change with function callback", () => {
+    renderHook(() =>
+      useOnProgressChange({
+        size: 300,
+        sizeReady: mockSizeReady,
+        autoFillData: false,
+        loop: false,
+        offsetX: mockOffsetX,
+        rawDataLength: 5,
+        onProgressChange: mockOnProgressChange,
+      })
+    );
+
+    mockOffsetX.value = -300; // Move to next slide
+    __triggerReaction({ offset: mockOffsetX.value, ready: mockSizeReady.value });
+    expect(mockOnProgressChange).toHaveBeenCalledWith(-300, 1);
+  });
+
+  it("should handle progress change with shared value", () => {
+    const progressValue = useSharedValue(0);
+    renderHook(() =>
+      useOnProgressChange({
+        size: 300,
+        sizeReady: mockSizeReady,
+        autoFillData: false,
+        loop: false,
+        offsetX: mockOffsetX,
+        rawDataLength: 5,
+        onProgressChange: progressValue,
+      })
+    );
+
+    mockOffsetX.value = -300; // Move to next slide
+    __triggerReaction({ offset: mockOffsetX.value, ready: mockSizeReady.value });
+    expect(progressValue.value).toBe(1);
+  });
+
+  it("should handle loop mode", () => {
+    renderHook(() =>
+      useOnProgressChange({
+        size: 300,
+        sizeReady: mockSizeReady,
+        autoFillData: false,
+        loop: true,
+        offsetX: mockOffsetX,
+        rawDataLength: 5,
+        onProgressChange: mockOnProgressChange,
+      })
+    );
+
+    mockOffsetX.value = -1500; // Move to last slide
+    __triggerReaction({ offset: mockOffsetX.value, ready: mockSizeReady.value });
+    expect(mockOnProgressChange).toHaveBeenCalledWith(-1500, 5);
+  });
+
+  it("should handle autoFillData mode", () => {
+    renderHook(() =>
+      useOnProgressChange({
+        size: 300,
+        sizeReady: mockSizeReady,
+        autoFillData: true,
+        loop: false,
+        offsetX: mockOffsetX,
+        rawDataLength: 3,
+        onProgressChange: mockOnProgressChange,
+      })
+    );
+
+    mockOffsetX.value = -300; // Move to next slide
+    __triggerReaction({ offset: mockOffsetX.value, ready: mockSizeReady.value });
+    expect(mockOnProgressChange).toHaveBeenCalledWith(-300, 1);
+  });
+
+  it("should clamp values when not in loop mode", () => {
+    renderHook(() =>
+      useOnProgressChange({
+        size: 300,
+        sizeReady: mockSizeReady,
+        autoFillData: false,
+        loop: false,
+        offsetX: mockOffsetX,
+        rawDataLength: 3,
+        onProgressChange: mockOnProgressChange,
+      })
+    );
+
+    mockOffsetX.value = 300; // Try to move before first slide
+    __triggerReaction({ offset: mockOffsetX.value, ready: mockSizeReady.value });
+    expect(mockOnProgressChange).toHaveBeenCalledWith(0, 0);
+
+    mockOffsetX.value = -900; // Try to move after last slide
+    __triggerReaction({ offset: mockOffsetX.value, ready: mockSizeReady.value });
+    expect(mockOnProgressChange).toHaveBeenCalledWith(-600, 2);
+  });
+
+  it("should handle positive offset values", () => {
+    renderHook(() =>
+      useOnProgressChange({
+        size: 300,
+        sizeReady: mockSizeReady,
+        autoFillData: false,
+        loop: true,
+        offsetX: mockOffsetX,
+        rawDataLength: 5,
+        onProgressChange: mockOnProgressChange,
+      })
+    );
+
+    mockOffsetX.value = 300; // Move backwards
+    __triggerReaction({ offset: mockOffsetX.value, ready: mockSizeReady.value });
+    expect(mockOnProgressChange).toHaveBeenCalledWith(300, 4);
+  });
+
+  it("should not call onProgressChange if not provided", () => {
+    renderHook(() =>
+      useOnProgressChange({
+        size: 300,
+        sizeReady: mockSizeReady,
+        autoFillData: false,
+        loop: false,
+        offsetX: mockOffsetX,
+        rawDataLength: 5,
+      })
+    );
+
+    mockOffsetX.value = -300; // Move to next slide
+    __triggerReaction({ offset: mockOffsetX.value, ready: mockSizeReady.value });
+    // Should not throw any errors or call any callbacks
+  });
+
+  it("should not trigger progress change when size is not ready", () => {
+    const mockSizeNotReady = useSharedValue(false);
+    renderHook(() =>
+      useOnProgressChange({
+        size: 300,
+        sizeReady: mockSizeNotReady,
+        autoFillData: false,
+        loop: false,
+        offsetX: mockOffsetX,
+        rawDataLength: 5,
+        onProgressChange: mockOnProgressChange,
+      })
+    );
+
+    mockOffsetX.value = -300; // Move to next slide
+    __triggerReaction({ offset: mockOffsetX.value, ready: mockSizeNotReady.value });
+    expect(mockOnProgressChange).not.toHaveBeenCalled();
+  });
+});

package/src/hooks/useOnProgressChange.ts

@@ -0,0 +1,105 @@
+import type { SharedValue } from "react-native-reanimated";
+import { useAnimatedReaction } from "react-native-reanimated";
+import { scheduleOnRN } from "react-native-worklets";
+
+import type { TCarouselProps } from "../types";
+import { computedOffsetXValueWithAutoFillData } from "../utils/computed-with-auto-fill-data";
+import type { SizeResolver } from "../utils/size-resolver";
+
+export function useOnProgressChange(
+  opts: {
+    size: number;
+    sizeReady: SharedValue<boolean>;
+    autoFillData: boolean;
+    loop: boolean;
+    offsetX: SharedValue<number>;
+    rawDataLength: number;
+    sizeResolver: SizeResolver;
+    variableSize: boolean;
+  } & Pick<TCarouselProps, "onProgressChange">
+) {
+  const {
+    autoFillData,
+    loop,
+    offsetX,
+    size,
+    rawDataLength,
+    onProgressChange,
+    sizeReady,
+    sizeResolver,
+    variableSize,
+  } = opts;
+
+  // remember `isFunc` here because we can't accurately check typeof
+  // from within useAnimatedReaction because its code has been workletized;
+  // the `onProgressChange` value will be typeof "object" from within
+  // the worklet code even if it's a function.
+  const isFunc = typeof onProgressChange === "function";
+
+  useAnimatedReaction(
+    () => ({ offset: offsetX.value, ready: sizeReady.value }),
+    ({ offset, ready }) => {
+      if (!ready) return;
+
+      if (variableSize) {
+        // Variable-size progress: integer part is the current item index,
+        // fractional part is the proportion scrolled into that item. We
+        // intentionally keep `offsetProgress` in raw pixels (it has always
+        // been documented as "Total of offset distance").
+        const total = sizeResolver.total.value;
+        if (total <= 0) return;
+        // Normalise into one loop length and convert to a positive-leaning
+        // offset so the math mirrors the uniform branch.
+        let value = offset;
+        if (!loop) {
+          const lastItemStart = sizeResolver.offsetAt(rawDataLength - 1);
+          value = Math.max(-lastItemStart, Math.min(value, 0));
+        }
+        const absOffset = Math.abs(value);
+        const idx = sizeResolver.indexAt(absOffset);
+        const itemStart = sizeResolver.offsetAt(idx);
+        const itemSize = sizeResolver.itemSize(idx);
+        const fraction = itemSize > 0 ? (absOffset - itemStart) / itemSize : 0;
+        let absoluteProgress = idx + fraction;
+        if (value > 0) absoluteProgress = rawDataLength - absoluteProgress;
+
+        if (onProgressChange) {
+          if (isFunc) {
+            scheduleOnRN(onProgressChange, value, absoluteProgress);
+          } else {
+            (onProgressChange as SharedValue<number>).value = absoluteProgress;
+          }
+        }
+        return;
+      }
+
+      const safeSize = size > 0 ? size : 0;
+      if (safeSize <= 0) return;
+
+      let value = computedOffsetXValueWithAutoFillData({
+        value: offset,
+        rawDataLength,
+        size: safeSize,
+        autoFillData,
+        loop,
+      });
+
+      if (!loop) {
+        value = Math.max(-((rawDataLength - 1) * safeSize), Math.min(value, 0));
+      }
+
+      let absoluteProgress = Math.abs(value / safeSize);
+
+      if (value > 0) absoluteProgress = rawDataLength - absoluteProgress;
+
+      if (onProgressChange) {
+        if (isFunc) {
+          scheduleOnRN(onProgressChange, value, absoluteProgress);
+        } else {
+          (onProgressChange as SharedValue<number>).value = absoluteProgress;
+        }
+      }
+    },
+    [loop, autoFillData, rawDataLength, onProgressChange, size, variableSize, sizeResolver]
+  );
+}