@leonsilicon/react-native-reanimated-carousel 0.0.0

package/src/hooks/useCommonVariables.test.tsx

@@ -0,0 +1,384 @@
+import { act, renderHook } from "@testing-library/react-hooks";
+import { StyleProp, ViewStyle } from "react-native";
+import { SharedValue, useSharedValue } from "react-native-reanimated";
+
+import { useCommonVariables } from "./useCommonVariables";
+import type { TInitializeCarouselProps } from "./useInitProps";
+
+function createBaseProps(
+  overrides: Partial<TInitializeCarouselProps<any>> = {}
+): TInitializeCarouselProps<any> {
+  return {
+    defaultIndex: 0,
+    loop: true,
+    scrollAnimationDuration: 500,
+    autoFillData: true,
+    autoPlayInterval: 2000,
+    autoPlay: false,
+    data: [0, 1, 2, 3],
+    dataLength: 4,
+    rawData: [0, 1, 2, 3],
+    rawDataLength: 4,
+    vertical: false,
+    style: { width: 700, height: 350 } as StyleProp<ViewStyle>,
+    renderItem: () => null,
+    pagingEnabled: true,
+    enabled: true,
+    overscrollEnabled: true,
+    snapEnabled: true,
+    testID: "carousel",
+    ...overrides,
+  } as TInitializeCarouselProps<any>;
+}
+
+describe("useCommonVariables", () => {
+  it("returns expected values when style provides width", () => {
+    const props = createBaseProps();
+    const { result } = renderHook(() => useCommonVariables(props));
+
+    expect(result.current.size).toBe(700);
+    expect(result.current.validLength).toBe(3);
+    expect(result.current.handlerOffset.value).toBeCloseTo(0);
+    expect(result.current.resolvedSize.value).toBe(700);
+    expect(result.current.sizePhase.value).toBe("ready");
+  });
+
+  it("uses style.height as size when vertical", () => {
+    const props = createBaseProps({ vertical: true, style: { height: 360 } });
+    const { result } = renderHook(() => useCommonVariables(props));
+
+    expect(result.current.size).toBe(360);
+    expect(result.current.resolvedSize.value).toBe(360);
+  });
+
+  it("initializes handlerOffset when defaultIndex is non-zero", () => {
+    const props = createBaseProps({ defaultIndex: 2 });
+    const { result } = renderHook(() => useCommonVariables(props));
+
+    expect(result.current.handlerOffset.value).toBe(-1400);
+  });
+
+  it("respects custom defaultScrollOffsetValue", () => {
+    let shared!: SharedValue<number>;
+    const { result } = renderHook(() => {
+      shared = useSharedValue(-500);
+      const props = createBaseProps({ defaultScrollOffsetValue: shared });
+      return useCommonVariables(props);
+    });
+
+    expect(result.current.handlerOffset).toBe(shared);
+    expect(result.current.handlerOffset.value).toBe(-500);
+  });
+
+  it("sets validLength to 0 when dataLength is 1", () => {
+    const props = createBaseProps({ dataLength: 1, data: [0] });
+    const { result } = renderHook(() => useCommonVariables(props));
+
+    expect(result.current.validLength).toBe(0);
+  });
+
+  it("sets validLength to -1 when dataLength is 0", () => {
+    const props = createBaseProps({ dataLength: 0, data: [] });
+    const { result } = renderHook(() => useCommonVariables(props));
+
+    expect(result.current.validLength).toBe(-1);
+  });
+
+  it("handles negative defaultIndex", () => {
+    const props = createBaseProps({ defaultIndex: -1 });
+    const { result } = renderHook(() => useCommonVariables(props));
+
+    expect(result.current.handlerOffset.value).toBe(-700);
+  });
+
+  it("keeps size calculation when loop is disabled", () => {
+    const props = createBaseProps({ loop: false });
+    const { result } = renderHook(() => useCommonVariables(props));
+
+    expect(result.current.size).toBe(700);
+    expect(result.current.validLength).toBe(3);
+  });
+
+  it("syncs resolvedSize when style width changes", () => {
+    const initial = createBaseProps();
+    const hook = renderHook(({ p }) => useCommonVariables(p), { initialProps: { p: initial } });
+    expect(hook.result.current.resolvedSize.value).toBe(700);
+
+    const updated = createBaseProps({ style: { width: 800 } });
+    act(() => {
+      hook.rerender({ p: updated });
+    });
+
+    expect(hook.result.current.resolvedSize.value).toBe(800);
+  });
+
+  it("updates validLength when dataLength changes", () => {
+    const hook = renderHook(({ p }) => useCommonVariables(p), {
+      initialProps: { p: createBaseProps() },
+    });
+    expect(hook.result.current.validLength).toBe(3);
+
+    act(() => {
+      hook.rerender({ p: createBaseProps({ dataLength: 6, data: [0, 1, 2, 3, 4, 5] }) });
+    });
+
+    expect(hook.result.current.validLength).toBe(5);
+  });
+
+  it("remains pending when style lacks numeric size", () => {
+    const props = createBaseProps({ style: { width: "100%" } });
+    const { result } = renderHook(() => useCommonVariables(props));
+
+    expect(result.current.size).toBe(0);
+    expect(result.current.resolvedSize.value).toBeNull();
+    expect(result.current.sizePhase.value).toBe("pending");
+  });
+
+  it("keeps handlerOffset at zero when width is 0", () => {
+    const props = createBaseProps({ style: { width: 0 } });
+    const { result } = renderHook(() => useCommonVariables(props));
+
+    expect(result.current.size).toBe(0);
+    expect(result.current.handlerOffset.value).toBeCloseTo(0);
+  });
+
+  it("handles large defaultIndex values", () => {
+    const props = createBaseProps({ defaultIndex: 10 });
+    const { result } = renderHook(() => useCommonVariables(props));
+
+    expect(result.current.handlerOffset.value).toBe(-7000);
+  });
+
+  it("returns zero size when vertical height is 0", () => {
+    const props = createBaseProps({ vertical: true, style: { height: 0 } });
+    const { result } = renderHook(() => useCommonVariables(props));
+
+    expect(result.current.size).toBe(0);
+  });
+
+  it("accepts floating point dimensions", () => {
+    const props = createBaseProps({ style: { width: 700.5 } });
+    const { result } = renderHook(() => useCommonVariables(props));
+
+    expect(result.current.size).toBe(700.5);
+    expect(result.current.resolvedSize.value).toBe(700.5);
+  });
+
+  it("stays pending when only height is provided", () => {
+    const props = createBaseProps({ style: { height: 200 } });
+    const { result } = renderHook(() => useCommonVariables(props));
+
+    expect(result.current.size).toBe(0);
+    expect(result.current.sizePhase.value).toBe("pending");
+  });
+
+  describe("itemWidth/itemHeight props", () => {
+    it("uses itemWidth for horizontal carousel size when provided", () => {
+      const props = createBaseProps({
+        style: { width: 700, height: 350 },
+        itemWidth: 350,
+      });
+      const { result } = renderHook(() => useCommonVariables(props));
+
+      expect(result.current.size).toBe(350);
+      expect(result.current.resolvedSize.value).toBe(350);
+      expect(result.current.sizePhase.value).toBe("ready");
+    });
+
+    it("uses itemHeight for vertical carousel size when provided", () => {
+      const props = createBaseProps({
+        vertical: true,
+        style: { width: 700, height: 350 },
+        itemHeight: 200,
+      });
+      const { result } = renderHook(() => useCommonVariables(props));
+
+      expect(result.current.size).toBe(200);
+      expect(result.current.resolvedSize.value).toBe(200);
+      expect(result.current.sizePhase.value).toBe("ready");
+    });
+
+    it("prioritizes itemWidth over style.width for horizontal carousel", () => {
+      const props = createBaseProps({
+        style: { width: 700 },
+        itemWidth: 350,
+      });
+      const { result } = renderHook(() => useCommonVariables(props));
+
+      expect(result.current.size).toBe(350);
+    });
+
+    it("prioritizes itemHeight over style.height for vertical carousel", () => {
+      const props = createBaseProps({
+        vertical: true,
+        style: { height: 400 },
+        itemHeight: 200,
+      });
+      const { result } = renderHook(() => useCommonVariables(props));
+
+      expect(result.current.size).toBe(200);
+    });
+
+    it("prioritizes itemWidth over deprecated width prop", () => {
+      const props = createBaseProps({
+        width: 700,
+        itemWidth: 350,
+      });
+      const { result } = renderHook(() => useCommonVariables(props));
+
+      expect(result.current.size).toBe(350);
+    });
+
+    it("prefers style.width over deprecated width prop when itemWidth not provided", () => {
+      const props = createBaseProps({
+        width: 500,
+      });
+      const { result } = renderHook(() => useCommonVariables(props));
+
+      expect(result.current.size).toBe(700);
+    });
+
+    it("prefers style.height over deprecated height prop when itemHeight not provided in vertical mode", () => {
+      const props = createBaseProps({
+        vertical: true,
+        height: 400,
+      });
+      const { result } = renderHook(() => useCommonVariables(props));
+
+      expect(result.current.size).toBe(350);
+    });
+
+    it("falls back to deprecated width prop when style.width is not provided", () => {
+      const props = createBaseProps({
+        style: {},
+        width: 500,
+      });
+      const { result } = renderHook(() => useCommonVariables(props));
+
+      expect(result.current.size).toBe(500);
+    });
+
+    it("falls back to deprecated height prop when style.height is not provided (vertical mode)", () => {
+      const props = createBaseProps({
+        vertical: true,
+        style: {},
+        height: 400,
+      });
+      const { result } = renderHook(() => useCommonVariables(props));
+
+      expect(result.current.size).toBe(400);
+    });
+
+    it("ignores zero or negative itemWidth", () => {
+      const props = createBaseProps({
+        style: { width: 700 },
+        itemWidth: 0,
+      });
+      const { result } = renderHook(() => useCommonVariables(props));
+
+      expect(result.current.size).toBe(700);
+    });
+
+    it("ignores zero or negative itemHeight", () => {
+      const props = createBaseProps({
+        vertical: true,
+        style: { height: 400 },
+        itemHeight: -10,
+      });
+      const { result } = renderHook(() => useCommonVariables(props));
+
+      expect(result.current.size).toBe(400);
+    });
+
+    it("calculates handlerOffset correctly with itemWidth", () => {
+      const props = createBaseProps({
+        style: { width: 700 },
+        itemWidth: 350,
+        defaultIndex: 2,
+      });
+      const { result } = renderHook(() => useCommonVariables(props));
+
+      // defaultIndex 2 * itemWidth 350 = -700
+      expect(result.current.handlerOffset.value).toBe(-700);
+    });
+
+    it("updates resolvedSize when itemWidth changes", () => {
+      const initial = createBaseProps({ style: { width: 700 }, itemWidth: 350 });
+      const hook = renderHook(({ p }) => useCommonVariables(p), { initialProps: { p: initial } });
+      expect(hook.result.current.size).toBe(350);
+      expect(hook.result.current.resolvedSize.value).toBe(350);
+
+      const updated = createBaseProps({ style: { width: 700 }, itemWidth: 400 });
+      act(() => {
+        hook.rerender({ p: updated });
+      });
+
+      // resolvedSize (SharedValue) updates immediately via useEffect
+      expect(hook.result.current.resolvedSize.value).toBe(400);
+      // size (state) updates asynchronously via useAnimatedReaction
+      // In test environment, this requires waiting for the animated reaction to fire
+    });
+  });
+
+  describe("sizeExplicit flag", () => {
+    it("sets sizeExplicit to true when itemWidth is provided for horizontal carousel", () => {
+      const props = createBaseProps({
+        style: { width: 700 },
+        itemWidth: 350,
+      });
+      const { result } = renderHook(() => useCommonVariables(props));
+
+      expect(result.current.sizeExplicit).toBe(true);
+    });
+
+    it("sets sizeExplicit to true when itemHeight is provided for vertical carousel", () => {
+      const props = createBaseProps({
+        vertical: true,
+        style: { height: 400 },
+        itemHeight: 200,
+      });
+      const { result } = renderHook(() => useCommonVariables(props));
+
+      expect(result.current.sizeExplicit).toBe(true);
+    });
+
+    it("sets sizeExplicit to false when only style.width is provided", () => {
+      const props = createBaseProps({
+        style: { width: 700 },
+      });
+      const { result } = renderHook(() => useCommonVariables(props));
+
+      expect(result.current.sizeExplicit).toBe(false);
+    });
+
+    it("sets sizeExplicit to false when only deprecated width prop is provided", () => {
+      const props = createBaseProps({
+        width: 700,
+      });
+      const { result } = renderHook(() => useCommonVariables(props));
+
+      expect(result.current.sizeExplicit).toBe(false);
+    });
+
+    it("sets sizeExplicit to false when itemWidth is zero", () => {
+      const props = createBaseProps({
+        style: { width: 700 },
+        itemWidth: 0,
+      });
+      const { result } = renderHook(() => useCommonVariables(props));
+
+      expect(result.current.sizeExplicit).toBe(false);
+    });
+
+    it("sets sizeExplicit to false when itemHeight is negative", () => {
+      const props = createBaseProps({
+        vertical: true,
+        style: { height: 400 },
+        itemHeight: -10,
+      });
+      const { result } = renderHook(() => useCommonVariables(props));
+
+      expect(result.current.sizeExplicit).toBe(false);
+    });
+  });
+});

package/src/hooks/useCommonVariables.ts

@@ -0,0 +1,202 @@
+import React from "react";
+import { StyleSheet } from "react-native";
+import type { SharedValue } from "react-native-reanimated";
+import { useAnimatedReaction, useSharedValue } from "react-native-reanimated";
+import { scheduleOnRN } from "react-native-worklets";
+
+import type { TInitializeCarouselProps } from "./useInitProps";
+
+import { computeOffsetIfDataChanged } from "../utils/compute-offset-if-data-changed";
+import { computeOffsetIfSizeChanged } from "../utils/compute-offset-if-size-changed";
+import { handlerOffsetDirection } from "../utils/handleroffset-direction";
+import { buildPrefixSum } from "../utils/size-resolver";
+
+export type TCarouselSizePhase = "pending" | "ready" | "updating";
+
+export interface ICommonVariables {
+  size: number;
+  validLength: number;
+  handlerOffset: SharedValue<number>;
+  resolvedSize: SharedValue<number | null>;
+  sizePhase: SharedValue<TCarouselSizePhase>;
+  sizeExplicit: boolean;
+}
+
+export function useCommonVariables(props: TInitializeCarouselProps<any>): ICommonVariables {
+  const {
+    vertical,
+    style,
+    dataLength,
+    defaultIndex,
+    defaultScrollOffsetValue,
+    loop,
+    width: explicitWidth,
+    height: explicitHeight,
+    itemWidth: explicitItemWidth,
+    itemHeight: explicitItemHeight,
+    getItemSize,
+    variableSize,
+  } = props;
+
+  // Variable-size default offset: precompute the prefix up to `defaultIndex`
+  // so the carousel mounts already scrolled to the right starting position.
+  const variableDefaultOffset = React.useMemo(() => {
+    if (!variableSize || !getItemSize || dataLength <= 0) return null;
+    const built = buildPrefixSum(dataLength, getItemSize);
+    const clamped = Math.max(0, Math.min(dataLength - 1, defaultIndex));
+    return -built.prefix[clamped];
+  }, [variableSize, getItemSize, dataLength, defaultIndex]);
+
+  const manualSize = React.useMemo(() => {
+    const explicitPageSize = vertical ? explicitItemHeight : explicitItemWidth;
+    if (typeof explicitPageSize === "number" && explicitPageSize > 0) {
+      return explicitPageSize;
+    }
+
+    const { width, height } = StyleSheet.flatten(style) || {};
+    const candidate = vertical ? height : width;
+    if (typeof candidate === "number" && candidate > 0) {
+      return candidate;
+    }
+
+    // NOTE: `width`/`height` props are deprecated in v5. They are still respected here to
+    // maintain backwards compatibility with v4-style usage. Prefer using `style` when both exist.
+    const explicitCandidate = vertical ? explicitHeight : explicitWidth;
+    if (typeof explicitCandidate === "number" && explicitCandidate > 0) {
+      return explicitCandidate;
+    }
+
+    return null;
+  }, [vertical, style, explicitWidth, explicitHeight, explicitItemHeight, explicitItemWidth]);
+
+  const resolvedSize = useSharedValue<number | null>(manualSize);
+  const sizePhase = useSharedValue<TCarouselSizePhase>(
+    variableSize ? "ready" : manualSize ? "ready" : "pending"
+  );
+
+  // Variable mode mounts already-ready: every item's size is known up-front,
+  // so we don't wait for an `onLayout` measurement to start positioning.
+  const defaultHandlerOffsetValue =
+    variableDefaultOffset !== null
+      ? variableDefaultOffset
+      : manualSize
+        ? -Math.abs(defaultIndex * manualSize)
+        : 0;
+  const _handlerOffset = useSharedValue<number>(defaultHandlerOffsetValue);
+  // Prefer the newer `scrollOffsetValue` name, but keep the legacy prop for compatibility.
+  const handlerOffset = props.scrollOffsetValue ?? defaultScrollOffsetValue ?? _handlerOffset;
+  const prevDataLength = useSharedValue(dataLength);
+  const prevSize = useSharedValue(manualSize ?? 0);
+  const sizeExplicit = React.useMemo(() => {
+    const explicitPageSize = vertical ? explicitItemHeight : explicitItemWidth;
+    return typeof explicitPageSize === "number" && explicitPageSize > 0;
+  }, [explicitItemHeight, explicitItemWidth, vertical]);
+
+  const [size, setSize] = React.useState<number>(manualSize ?? 0);
+
+  const syncSize = React.useCallback((next: number) => {
+    setSize((current) => (current === next ? current : next));
+  }, []);
+
+  useAnimatedReaction(
+    () => resolvedSize.value,
+    (current, previous) => {
+      if (current == null || current <= 0) return;
+      if (current !== previous) {
+        scheduleOnRN(syncSize, current);
+      }
+    },
+    [syncSize]
+  );
+
+  React.useEffect(() => {
+    if (manualSize && manualSize > 0) {
+      resolvedSize.value = manualSize;
+      sizePhase.value = "ready";
+    }
+  }, [manualSize, resolvedSize, sizePhase]);
+
+  /**
+   * When data changes, we need to compute new index for handlerOffset
+   */
+  useAnimatedReaction(
+    () => {
+      const previousLength = prevDataLength.value;
+      const currentLength = dataLength;
+      const isLengthChanged = previousLength !== currentLength;
+      const shouldComputed = isLengthChanged && loop;
+
+      if (shouldComputed) prevDataLength.value = dataLength;
+
+      return {
+        shouldComputed,
+        previousLength,
+        currentLength,
+      };
+    },
+    ({ shouldComputed, previousLength, currentLength }) => {
+      if (shouldComputed) {
+        // Variable-mode reflow is handled by useSizeResolver rebuilding the
+        // prefix table; the size-based handlerOffset adjustment doesn't apply.
+        if (variableSize) return;
+
+        // direction -> 1 | -1
+        const direction = handlerOffsetDirection(handlerOffset);
+
+        const _size = resolvedSize.value ?? 0;
+        if (_size <= 0) return;
+
+        handlerOffset.value = computeOffsetIfDataChanged({
+          direction,
+          previousLength,
+          currentLength,
+          size: _size,
+          handlerOffset: handlerOffset.value,
+        });
+      }
+    },
+    [dataLength, loop, resolvedSize, variableSize]
+  );
+
+  /**
+   * When size changes, we need to compute new index for handlerOffset. This
+   * reaction is uniform-mode only — in variable-size mode, item positions come
+   * from the resolver's prefix table, not the scalar container size, so an
+   * onLayout-driven resize doesn't translate to a handlerOffset adjustment.
+   */
+  useAnimatedReaction(
+    () => resolvedSize.value,
+    (currentSize) => {
+      if (variableSize) return;
+      if (currentSize == null || currentSize <= 0) return;
+      const previousSize = prevSize.value;
+
+      if (previousSize === currentSize) return;
+
+      sizePhase.value = previousSize > 0 ? "updating" : sizePhase.value;
+
+      if (previousSize <= 0) {
+        handlerOffset.value = -Math.abs(defaultIndex * currentSize);
+      } else {
+        handlerOffset.value = computeOffsetIfSizeChanged({
+          handlerOffset: handlerOffset.value,
+          prevSize: previousSize,
+          size: currentSize,
+        });
+      }
+
+      prevSize.value = currentSize;
+      sizePhase.value = "ready";
+    },
+    [defaultIndex, resolvedSize, sizePhase, variableSize]
+  );
+
+  return {
+    size,
+    validLength: dataLength - 1,
+    handlerOffset,
+    resolvedSize,
+    sizePhase,
+    sizeExplicit,
+  };
+}