@leonsilicon/react-native-reanimated-carousel 0.0.0

package/src/hooks/usePanGestureProxy.test.tsx

@@ -0,0 +1,368 @@
+import React from "react";
+import { Text } from "react-native";
+import type { PanGesture, PanGestureHandler, TapGesture } from "react-native-gesture-handler";
+import {
+  Gesture,
+  GestureDetector,
+  GestureHandlerRootView,
+  State,
+} from "react-native-gesture-handler";
+
+import { cleanup, render } from "@testing-library/react-native";
+import { fireGestureHandler, getByGestureTestId } from "react-native-gesture-handler/jest-utils";
+
+import { usePanGestureProxy } from "./usePanGestureProxy";
+
+beforeEach(cleanup);
+
+const mockedEventHandlers = () => {
+  return {
+    begin: jest.fn(),
+    start: jest.fn(),
+    active: jest.fn(),
+    end: jest.fn(),
+    fail: jest.fn(),
+    cancel: jest.fn(),
+    finish: jest.fn(),
+  };
+};
+
+const mockedEventHandlersFromUser = () => {
+  return {
+    begin: jest.fn(),
+    start: jest.fn(),
+    active: jest.fn(),
+    end: jest.fn(),
+    fail: jest.fn(),
+    cancel: jest.fn(),
+    finish: jest.fn(),
+  };
+};
+
+describe("Using RNGH v2 gesture API", () => {
+  interface SingleHandlerProps {
+    handlers: ReturnType<typeof mockedEventHandlers>;
+    handlersFromUser: ReturnType<typeof mockedEventHandlers>;
+    treatStartAsUpdate?: boolean;
+  }
+
+  function SingleHandler({ handlers, handlersFromUser, treatStartAsUpdate }: SingleHandlerProps) {
+    const pan = usePanGestureProxy({
+      onConfigurePanGesture: (gesture: PanGesture) => {
+        // This is user's customizations
+        gesture
+          .onBegin(handlersFromUser.begin)
+          .onUpdate(handlersFromUser.active)
+          .onEnd(handlersFromUser.end)
+          .onFinalize(handlers.finish)
+          .withTestId("pan");
+      },
+      onGestureStart: treatStartAsUpdate ? handlers.active : handlers.start,
+      onGestureUpdate: handlers.active,
+      onGestureEnd: handlers.end,
+      options: { enabled: true },
+    });
+
+    return (
+      <GestureHandlerRootView>
+        <GestureDetector gesture={pan}>
+          <Text>v2 API test</Text>
+        </GestureDetector>
+      </GestureHandlerRootView>
+    );
+  }
+
+  interface RacingHandlersProps {
+    tapHandlers: ReturnType<typeof mockedEventHandlers>;
+    panHandlers: ReturnType<typeof mockedEventHandlers>;
+  }
+
+  function RacingHandlers({ tapHandlers, panHandlers }: RacingHandlersProps) {
+    const tap = Gesture.Tap().onBegin(tapHandlers.begin).onEnd(tapHandlers.end).withTestId("tap");
+
+    const pan = usePanGestureProxy({
+      onConfigurePanGesture: (_: PanGesture) => {
+        _.onBegin(panHandlers.begin).onFinalize(panHandlers.finish).withTestId("pan");
+      },
+      onGestureStart: panHandlers.start,
+      onGestureUpdate: panHandlers.active,
+      onGestureEnd: panHandlers.end,
+      options: { enabled: true },
+    });
+
+    return (
+      <GestureHandlerRootView>
+        <GestureDetector gesture={Gesture.Race(tap, pan)}>
+          <Text>v2 API test</Text>
+        </GestureDetector>
+      </GestureHandlerRootView>
+    );
+  }
+
+  it("sends events to handlers", () => {
+    const tapHandlers = mockedEventHandlers();
+    const panHandlers = mockedEventHandlers();
+    render(<RacingHandlers tapHandlers={tapHandlers} panHandlers={panHandlers} />);
+
+    fireGestureHandler<PanGesture>(getByGestureTestId("pan"), [
+      { state: State.BEGAN },
+      { state: State.ACTIVE },
+      { state: State.END },
+    ]);
+    expect(panHandlers.begin).toBeCalledWith(expect.objectContaining({ state: State.BEGAN }));
+    expect(panHandlers.finish).toBeCalled();
+    expect(tapHandlers.begin).not.toBeCalled();
+  });
+
+  it("sends events with additional data to handlers", () => {
+    const panHandlers = mockedEventHandlers();
+    const panHandlersFromUser = mockedEventHandlersFromUser();
+    render(
+      <SingleHandler
+        handlers={panHandlers}
+        handlersFromUser={panHandlersFromUser}
+        treatStartAsUpdate
+      />
+    );
+    fireGestureHandler<PanGesture>(getByGestureTestId("pan"), [
+      { state: State.BEGAN, translationX: 0 },
+      { state: State.ACTIVE, translationX: 10 },
+      { translationX: 20 },
+      { translationX: 20 },
+      { state: State.END, translationX: 30 },
+    ]);
+
+    expect(panHandlersFromUser.begin).toBeCalledTimes(1);
+    expect(panHandlersFromUser.active).toBeCalledTimes(2);
+    expect(panHandlersFromUser.end).toBeCalledTimes(1);
+
+    expect(panHandlers.active).toBeCalledTimes(3);
+    expect(panHandlers.active).toHaveBeenLastCalledWith(
+      expect.objectContaining({ translationX: 20 })
+    );
+  });
+
+  it("does not include console.error in the output", () => {
+    // if react-native-gesture-handler detects that some handlers are
+    // workletized and some are not, it will log an error to the
+    // console. We'd like to make sure that this doesn't happen.
+
+    // The error that would be shown looks like:
+    // [react-native-gesture-handler] Some of the callbacks in the gesture are worklets and some are not. Either make sure that all calbacks are marked as 'worklet' if you wish to run them on the UI thread or use '.scheduleOnRN(true)' modifier on the gesture explicitly to run all callbacks on the JS thread.
+
+    const panHandlers = mockedEventHandlers();
+    const panHandlersFromUser = mockedEventHandlersFromUser();
+
+    jest.spyOn(console, "error");
+
+    render(
+      <SingleHandler
+        handlers={panHandlers}
+        handlersFromUser={panHandlersFromUser}
+        treatStartAsUpdate
+      />
+    );
+    fireGestureHandler<PanGesture>(getByGestureTestId("pan"), [
+      { state: State.BEGAN },
+      { state: State.ACTIVE },
+      { state: State.END },
+    ]);
+
+    expect(console.error).not.toBeCalled();
+  });
+});
+
+describe("Event list validation", () => {
+  interface SingleHandlerProps {
+    handlers: ReturnType<typeof mockedEventHandlers>;
+    handlersFromUser: ReturnType<typeof mockedEventHandlers>;
+    treatStartAsUpdate?: boolean;
+  }
+
+  function SingleHandler({ handlers, handlersFromUser, treatStartAsUpdate }: SingleHandlerProps) {
+    const pan = usePanGestureProxy({
+      onConfigurePanGesture: (_: PanGesture) => {
+        _.onBegin(handlersFromUser.begin)
+          .onUpdate(handlersFromUser.active)
+          .onEnd(handlersFromUser.end)
+          .onFinalize(handlers.finish)
+          .withTestId("pan");
+      },
+      onGestureStart: treatStartAsUpdate ? handlers.active : handlers.start,
+      onGestureUpdate: handlers.active,
+      onGestureEnd: handlers.end,
+      options: { enabled: true },
+    });
+
+    return (
+      <GestureHandlerRootView>
+        <GestureDetector gesture={pan}>
+          <Text>v2 API test</Text>
+        </GestureDetector>
+      </GestureHandlerRootView>
+    );
+  }
+
+  it("throws error when oldState doesn't correspond to previous event's state", () => {
+    const panHandlers = mockedEventHandlers();
+    const panHandlersFromUser = mockedEventHandlersFromUser();
+    render(<SingleHandler handlers={panHandlers} handlersFromUser={panHandlersFromUser} />);
+
+    expect(() => {
+      fireGestureHandler<PanGesture>(getByGestureTestId("pan"), [
+        { oldState: State.UNDETERMINED, state: State.BEGAN, x: 0, y: 10 },
+        { oldState: State.UNDETERMINED, state: State.ACTIVE, x: 1, y: 11 },
+      ]);
+    }).toThrow("when state changes, oldState should be the same as previous event' state");
+  });
+
+  it.each([[State.END], [State.FAILED], [State.CANCELLED]])(
+    "correctly handles events ending with state %s",
+    (lastState) => {
+      const panHandlers = mockedEventHandlers();
+      const panHandlersFromUser = mockedEventHandlersFromUser();
+      render(<SingleHandler handlers={panHandlers} handlersFromUser={panHandlersFromUser} />);
+      fireGestureHandler<PanGesture>(getByGestureTestId("pan"), [
+        { state: State.BEGAN },
+        { state: State.ACTIVE },
+        { state: lastState },
+      ]);
+
+      expect(panHandlersFromUser.begin).toBeCalledTimes(1);
+      expect(panHandlersFromUser.active).toBeCalledTimes(0);
+      expect(panHandlersFromUser.end).toBeCalledTimes(1);
+
+      if (lastState === State.END) expect(panHandlers.end).toBeCalled();
+      else expect(panHandlers.finish).toBeCalledWith(expect.any(Object), false);
+    }
+  );
+});
+
+describe("Filling event list with defaults", () => {
+  interface RacingTapAndPanProps {
+    handlers: ReturnType<typeof mockedEventHandlers>;
+    treatStartAsUpdate?: boolean;
+  }
+
+  function RacingTapAndPan({ handlers, treatStartAsUpdate }: RacingTapAndPanProps) {
+    const tap = Gesture.Tap().onBegin(handlers.begin).onEnd(handlers.end).withTestId("tap");
+
+    const pan = usePanGestureProxy({
+      onConfigurePanGesture: (_: PanGesture) => {
+        _.onBegin(handlers.begin).onFinalize(handlers.finish).withTestId("pan");
+      },
+      onGestureStart: treatStartAsUpdate ? handlers.active : handlers.start,
+      onGestureUpdate: handlers.active,
+      onGestureEnd: handlers.end,
+      options: { enabled: true },
+    });
+
+    return (
+      <GestureHandlerRootView>
+        <GestureDetector gesture={Gesture.Exclusive(pan, tap)}>
+          <Text>v2 API test</Text>
+        </GestureDetector>
+      </GestureHandlerRootView>
+    );
+  }
+
+  it("fills oldState if not passed", () => {
+    const handlers = mockedEventHandlers();
+    render(<RacingTapAndPan handlers={handlers} treatStartAsUpdate />);
+    fireGestureHandler<PanGestureHandler>(getByGestureTestId("pan"), [
+      { state: State.BEGAN },
+      { state: State.ACTIVE },
+      { state: State.ACTIVE },
+      { state: State.ACTIVE },
+      { state: State.END },
+    ]);
+
+    expect(handlers.begin).toBeCalledWith(
+      expect.objectContaining({ oldState: State.UNDETERMINED })
+    );
+    expect(handlers.active).nthCalledWith(1, expect.objectContaining({ oldState: State.BEGAN }));
+    expect(handlers.active).lastCalledWith(
+      expect.not.objectContaining({ oldState: expect.anything() })
+    );
+    expect(handlers.end).toBeCalledWith(expect.objectContaining({ oldState: State.ACTIVE }), true);
+  });
+
+  it("fills missing ACTIVE states", () => {
+    const panHandlers = mockedEventHandlers();
+    render(<RacingTapAndPan handlers={panHandlers} treatStartAsUpdate />);
+    fireGestureHandler<PanGesture>(getByGestureTestId("pan"), [
+      { state: State.BEGAN, x: 0, y: 10 },
+      { state: State.ACTIVE, x: 1, y: 11 },
+      { x: 2, y: 12 },
+      { x: 3, y: 13 },
+      { state: State.END, x: 4, y: 14 },
+    ]);
+
+    expect(panHandlers.active).toBeCalledTimes(3);
+    expect(panHandlers.active).toHaveBeenLastCalledWith(expect.objectContaining({ x: 3, y: 13 }));
+  });
+
+  it("fills BEGIN and END events for discrete handlers", () => {
+    const handlers = mockedEventHandlers();
+    render(<RacingTapAndPan handlers={handlers} treatStartAsUpdate />);
+    fireGestureHandler<TapGesture>(getByGestureTestId("tap"), [{ x: 5 }]);
+    expect(handlers.begin).toBeCalledTimes(1);
+    expect(handlers.end).toBeCalledTimes(1);
+  });
+
+  it("with FAILED event, fills BEGIN event for discrete handlers", () => {
+    const handlers = mockedEventHandlers();
+    render(<RacingTapAndPan handlers={handlers} treatStartAsUpdate />);
+    fireGestureHandler<TapGesture>(getByGestureTestId("tap"), [{ state: State.FAILED }]);
+    expect(handlers.begin).toBeCalledTimes(1);
+    expect(handlers.end).toBeCalledTimes(1);
+    expect(handlers.end).toBeCalledWith(expect.anything(), false);
+  });
+
+  it("uses event data from first event in filled BEGIN, ACTIVE events", () => {
+    const handlers = mockedEventHandlers();
+    render(<RacingTapAndPan handlers={handlers} treatStartAsUpdate />);
+    fireGestureHandler<PanGesture>(getByGestureTestId("pan"), [{ x: 120 }]);
+    expect(handlers.begin).toBeCalledWith(expect.objectContaining({ x: 120 }));
+    expect(handlers.active).toHaveBeenNthCalledWith(1, expect.objectContaining({ x: 120 }));
+  });
+
+  it("uses event data from last event in filled END events", () => {
+    const handlers = mockedEventHandlers();
+    render(<RacingTapAndPan handlers={handlers} treatStartAsUpdate />);
+    fireGestureHandler<PanGesture>(getByGestureTestId("pan"), [{ x: 120, state: State.FAILED }]);
+    expect(handlers.begin).toBeCalledTimes(1);
+    expect(handlers.active).toBeCalledTimes(1);
+    expect(handlers.end).toBeCalledWith(expect.objectContaining({ x: 120 }), false);
+  });
+
+  it("uses event data filled events", () => {
+    const handlers = mockedEventHandlers();
+    render(<RacingTapAndPan handlers={handlers} treatStartAsUpdate />);
+    fireGestureHandler<PanGesture>(getByGestureTestId("pan"), [
+      { x: 5, y: 15 },
+      { x: 6, y: 16 },
+      { x: 7, y: 17 },
+    ]);
+    expect(handlers.begin).toBeCalledWith(expect.objectContaining({ x: 5, y: 15 }));
+    expect(handlers.active).toBeCalledTimes(3);
+    expect(handlers.end).toBeCalledWith(expect.objectContaining({ x: 7, y: 17 }), true);
+  });
+
+  it("fills BEGIN and END events when they're not present, for discrete handlers", () => {
+    const handlers = mockedEventHandlers();
+    render(<RacingTapAndPan handlers={handlers} treatStartAsUpdate />);
+    fireGestureHandler<TapGesture>(getByGestureTestId("tap"));
+    expect(handlers.begin).toBeCalledTimes(1);
+    expect(handlers.end).toHaveBeenCalledTimes(1);
+  });
+
+  it("fills BEGIN, ACTIVE and END events when they're not present, for continuous handlers", () => {
+    const handlers = mockedEventHandlers();
+    render(<RacingTapAndPan handlers={handlers} treatStartAsUpdate />);
+    fireGestureHandler<PanGesture>(getByGestureTestId("pan"));
+    expect(handlers.begin).toBeCalledTimes(1);
+    expect(handlers.active).toBeCalledTimes(1);
+    expect(handlers.end).toHaveBeenCalledTimes(1);
+  });
+});

package/src/hooks/usePanGestureProxy.ts

@@ -0,0 +1,144 @@
+import { useMemo } from "react";
+import type {
+  GestureStateChangeEvent,
+  GestureUpdateEvent,
+  PanGesture,
+  PanGestureHandlerEventPayload,
+} from "react-native-gesture-handler";
+import { Gesture } from "react-native-gesture-handler";
+
+import type { GestureConfig } from "./useUpdateGestureConfig";
+import { useUpdateGestureConfig } from "./useUpdateGestureConfig";
+
+export const usePanGestureProxy = (customization: {
+  onConfigurePanGesture?: (gesture: PanGesture) => void;
+  onGestureStart: (event: GestureStateChangeEvent<PanGestureHandlerEventPayload>) => void;
+  onGestureUpdate: (event: GestureUpdateEvent<PanGestureHandlerEventPayload>) => void;
+  onGestureEnd: (
+    event: GestureStateChangeEvent<PanGestureHandlerEventPayload>,
+    success: boolean
+  ) => void;
+  options?: GestureConfig;
+}) => {
+  const {
+    onConfigurePanGesture,
+    onGestureStart,
+    onGestureUpdate,
+    onGestureEnd,
+    options = {},
+  } = customization;
+
+  const gesture = useMemo(() => {
+    const gesture = Gesture.Pan().withTestId("rnrc-gesture-handler");
+
+    // Save the original gesture callbacks
+    const originalGestures = {
+      onBegin: gesture.onBegin,
+      onStart: gesture.onStart,
+      onUpdate: gesture.onUpdate,
+      onEnd: gesture.onEnd,
+      onFinalize: gesture.onFinalize,
+    };
+
+    // Save the user defined gesture callbacks
+    const userDefinedConflictGestures: {
+      onBegin?: Parameters<(typeof gesture)["onBegin"]>[0];
+      onStart?: Parameters<(typeof gesture)["onStart"]>[0];
+      onUpdate?: Parameters<(typeof gesture)["onUpdate"]>[0];
+      onEnd?: Parameters<(typeof gesture)["onEnd"]>[0];
+      onFinalize?: Parameters<(typeof gesture)["onFinalize"]>[0];
+    } = {
+      onBegin: undefined,
+      onStart: undefined,
+      onUpdate: undefined,
+      onEnd: undefined,
+      onFinalize: undefined,
+    };
+
+    const fakeOnBegin: typeof gesture.onBegin = (cb) => {
+      // Using fakeOnBegin to save the user defined callback
+      userDefinedConflictGestures.onBegin = cb;
+      return gesture;
+    };
+
+    const fakeOnStart: typeof gesture.onStart = (cb) => {
+      // Using fakeOnStart to save the user defined callback
+      userDefinedConflictGestures.onStart = cb;
+      return gesture;
+    };
+
+    const fakeOnUpdate: typeof gesture.onUpdate = (cb) => {
+      // Using fakeOnUpdate to save the user defined callback
+      userDefinedConflictGestures.onUpdate = cb;
+      return gesture;
+    };
+
+    const fakeOnEnd: typeof gesture.onEnd = (cb) => {
+      // Using fakeOnEnd to save the user defined callback
+      userDefinedConflictGestures.onEnd = cb;
+      return gesture;
+    };
+
+    const fakeOnFinalize: typeof gesture.onFinalize = (cb) => {
+      // Using fakeOnFinalize to save the user defined callback
+      userDefinedConflictGestures.onFinalize = cb;
+      return gesture;
+    };
+
+    // Setup the fake callbacks
+    gesture.onBegin = fakeOnBegin;
+    gesture.onStart = fakeOnStart;
+    gesture.onUpdate = fakeOnUpdate;
+    gesture.onEnd = fakeOnEnd;
+    gesture.onFinalize = fakeOnFinalize;
+
+    if (onConfigurePanGesture)
+      // Get the gesture with the user defined configuration
+      onConfigurePanGesture(gesture);
+
+    // Restore the original callbacks
+    gesture.onBegin = originalGestures.onBegin;
+    gesture.onStart = originalGestures.onStart;
+    gesture.onUpdate = originalGestures.onUpdate;
+    gesture.onEnd = originalGestures.onEnd;
+    gesture.onFinalize = originalGestures.onFinalize;
+
+    // Setup the original callbacks with the user defined callbacks
+    gesture
+      .onBegin((e) => {
+        "worklet";
+
+        if (userDefinedConflictGestures.onBegin) userDefinedConflictGestures.onBegin(e);
+      })
+      .onStart((e) => {
+        "worklet";
+        onGestureStart(e);
+
+        if (userDefinedConflictGestures.onStart) userDefinedConflictGestures.onStart(e);
+      })
+      .onUpdate((e) => {
+        "worklet";
+        onGestureUpdate(e);
+
+        if (userDefinedConflictGestures.onUpdate) userDefinedConflictGestures.onUpdate(e);
+      })
+      .onEnd((e, success) => {
+        "worklet";
+        onGestureEnd(e, success);
+
+        if (userDefinedConflictGestures.onEnd) userDefinedConflictGestures.onEnd(e, success);
+      })
+      .onFinalize((e, success) => {
+        "worklet";
+
+        if (userDefinedConflictGestures.onFinalize)
+          userDefinedConflictGestures.onFinalize(e, success);
+      });
+
+    return gesture;
+  }, [onGestureStart, onGestureUpdate, onGestureEnd, onConfigurePanGesture]);
+
+  useUpdateGestureConfig(gesture, options);
+
+  return gesture;
+};

package/src/hooks/usePropsErrorBoundary.ts

@@ -0,0 +1,138 @@
+import React from "react";
+import { StyleSheet } from "react-native";
+
+import type { TCarouselProps } from "../types";
+
+export function usePropsErrorBoundary(props: TCarouselProps & { dataLength: number }) {
+  React.useEffect(() => {
+    const { defaultIndex, dataLength: viewCount } = props;
+
+    if (typeof defaultIndex === "number" && viewCount > 0) {
+      if (defaultIndex < 0 || defaultIndex >= viewCount) {
+        throw new Error("DefaultIndex must be in the range of data length.");
+      }
+    }
+
+    if (__DEV__) {
+      const {
+        style,
+        vertical,
+        width,
+        height,
+        itemWidth,
+        itemHeight,
+        contentContainerStyle,
+        getItemWidth,
+        getItemHeight,
+        autoFillData,
+      } = props;
+
+      // Variable-size mode: sanity-check the first few indices to catch
+      // common mistakes (returning 0, undefined, NaN).
+      const axisGetter = vertical ? getItemHeight : getItemWidth;
+      if (typeof axisGetter === "function" && viewCount > 0 && !warnedRefs.getItemSize) {
+        const sample = Math.min(viewCount, 5);
+        for (let i = 0; i < sample; i++) {
+          const value = axisGetter(i);
+          if (!Number.isFinite(value) || value <= 0) {
+            console.warn(
+              `[react-native-reanimated-carousel] ${
+                vertical ? "getItemHeight" : "getItemWidth"
+              }(${i}) returned ${String(
+                value
+              )}. Each item must report a positive, finite size; non-positive values are clamped to 0 and break snapping.`
+            );
+            warnedRefs.getItemSize = true;
+            break;
+          }
+        }
+      }
+
+      if (typeof axisGetter === "function" && autoFillData && !warnedRefs.autoFillVariable) {
+        console.warn(
+          "[react-native-reanimated-carousel] `autoFillData` is ignored when `getItemWidth`/`getItemHeight` is set. autoFillData duplicates data assuming uniform item size, which conflicts with variable-size layouts. Pre-duplicate your data array if you need a short loopable list."
+        );
+        warnedRefs.autoFillVariable = true;
+      }
+      const { width: styleWidth, height: styleHeight } = StyleSheet.flatten(style) || {};
+
+      // Deprecation warnings for width/height props
+      if (typeof width === "number" && !warnedRefs.width) {
+        console.warn(
+          "[react-native-reanimated-carousel] The `width` prop is deprecated. Please use `style={{ width: ... }}` instead."
+        );
+        warnedRefs.width = true;
+      }
+      if (typeof height === "number" && !warnedRefs.height) {
+        console.warn(
+          "[react-native-reanimated-carousel] The `height` prop is deprecated. Please use `style={{ height: ... }}` instead."
+        );
+        warnedRefs.height = true;
+      }
+
+      // Conflict warning for contentContainerStyle
+      const { opacity, transform } = StyleSheet.flatten(contentContainerStyle) || {};
+      if ((opacity !== undefined || transform !== undefined) && !warnedRefs.conflict) {
+        console.warn(
+          "[react-native-reanimated-carousel] Do not set 'opacity' or 'transform' on 'contentContainerStyle' as it may conflict with animations."
+        );
+        warnedRefs.conflict = true;
+      }
+
+      // Updated missing size warnings
+      const hasHorizontalContainerSize =
+        typeof styleWidth === "number" || typeof width === "number";
+      const hasVerticalContainerSize =
+        typeof styleHeight === "number" || typeof height === "number";
+
+      if (!vertical && !hasHorizontalContainerSize && !warnedRefs.horizontal) {
+        console.warn(
+          "[react-native-reanimated-carousel] Horizontal mode did not specify `width` in `style`, will fall back to automatic measurement mode."
+        );
+        warnedRefs.horizontal = true;
+      }
+      if (vertical && !hasVerticalContainerSize && !warnedRefs.vertical) {
+        console.warn(
+          "[react-native-reanimated-carousel] Vertical mode did not specify `height` in `style`, will fall back to automatic measurement mode."
+        );
+        warnedRefs.vertical = true;
+      }
+
+      // Page-size guidance (common pitfall): setting itemWidth/itemHeight without container size.
+      if (
+        !vertical &&
+        typeof itemWidth === "number" &&
+        !hasHorizontalContainerSize &&
+        !warnedRefs.itemWidth
+      ) {
+        console.warn(
+          "[react-native-reanimated-carousel] `itemWidth` sets the snapping page size, not the container width. Consider setting container width via `style` (e.g. `style={{ width: '100%' }}` or `flex: 1`)."
+        );
+        warnedRefs.itemWidth = true;
+      }
+      if (
+        vertical &&
+        typeof itemHeight === "number" &&
+        !hasVerticalContainerSize &&
+        !warnedRefs.itemHeight
+      ) {
+        console.warn(
+          "[react-native-reanimated-carousel] `itemHeight` sets the snapping page size, not the container height. Consider setting container height via `style` (e.g. `style={{ height: '100%' }}` or `flex: 1`)."
+        );
+        warnedRefs.itemHeight = true;
+      }
+    }
+  }, [props]);
+}
+
+const warnedRefs: { [key: string]: boolean } = {
+  horizontal: false,
+  vertical: false,
+  width: false,
+  height: false,
+  conflict: false,
+  itemWidth: false,
+  itemHeight: false,
+  getItemSize: false,
+  autoFillVariable: false,
+};