@momo-kits/carousel 0.165.2-beta.1 → 0.165.2-beta.3

package/index.tsx

@@ -9,548 +9,483 @@ import React, {
 } from 'react';
 import {
   Dimensions,
-  FlatList,
-  GestureResponderEvent,
-  LayoutChangeEvent,
-  NativeScrollEvent,
-  NativeSyntheticEvent,
-  Platform,
+  I18nManager,
   StyleSheet,
   View,
+  type LayoutChangeEvent,
+  type NativeScrollEvent,
+  type NativeSyntheticEvent,
 } from 'react-native';
-import Animated, {
+import {
   Extrapolation,
   interpolate,
   runOnJS,
-  useAnimatedScrollHandler,
-  useAnimatedStyle,
-  useSharedValue,
   type SharedValue,
 } from 'react-native-reanimated';
-import { CarouselProps, CarouselRef } from './types';
-
-const { width: viewportWidth } = Dimensions.get('window');
-
-const AnimatedFlatList = Animated.createAnimatedComponent(FlatList);
-
-type CarouselItemProps = {
-  index: number;
-  itemWidth: number;
-  scrollX: SharedValue<number>;
-  inactiveSlideOpacity: number;
-  inactiveSlideScale: number;
-  slideStyle: any;
-  children: React.ReactNode;
-};
-
-const CarouselItem: React.FC<CarouselItemProps> = ({
-  index,
-  itemWidth,
-  scrollX,
-  inactiveSlideOpacity,
-  inactiveSlideScale,
-  slideStyle,
-  children,
-}) => {
-  const animatedStyle = useAnimatedStyle(() => {
-    const inputRange = [
-      (index - 1) * itemWidth,
-      index * itemWidth,
-      (index + 1) * itemWidth,
-    ];
-    const opacity =
-      inactiveSlideOpacity < 1
-        ? interpolate(
-            scrollX.value,
-            inputRange,
-            [inactiveSlideOpacity, 1, inactiveSlideOpacity],
-            Extrapolation.CLAMP,
-          )
-        : 1;
-    const scale =
-      inactiveSlideScale < 1
-        ? interpolate(
-            scrollX.value,
-            inputRange,
-            [inactiveSlideScale, 1, inactiveSlideScale],
-            Extrapolation.CLAMP,
-          )
-        : 1;
-    return {
-      opacity,
-      transform: [{ scale }],
-    };
-  });
-
-  return (
-    <Animated.View style={[{ width: itemWidth }, slideStyle, animatedStyle]}>
-      {children}
-    </Animated.View>
-  );
-};
 
-const Carousel = forwardRef<CarouselRef, CarouselProps>((props, ref) => {
+import { Carousel as CoreCarousel } from './core/components/Carousel';
+import type {
+  CarouselItemAnimation,
+  CarouselPanGesture,
+  CarouselProps as CoreCarouselProps,
+  CarouselRef as CoreCarouselRef,
+} from './core/public-types';
+import type { CarouselProps, CarouselRef } from './types';
+
+const { width: WINDOW_WIDTH } = Dimensions.get('window');
+
+/** Gap the FlatList implementation left between items when `visibleItem > 1`. */
+const MULTI_ITEM_SPACING = 10;
+
+/** How long a `fireCallback: false` command suppresses `onSnapToItem`. */
+const SUPPRESS_CALLBACK_WINDOW = 1000;
+
+const IGNORED_LEGACY_PROPS = [
+  'loopClonesPerSide',
+  'snapToInterval',
+  'disableIntervalMomentum',
+  'getItemLayout',
+  'activeSlideOffset',
+  'onMomentumScrollEnd',
+] as const;
+
+function positiveModulo(value: number, divisor: number) {
+  if (divisor <= 0) return 0;
+  const remainder = value % divisor;
+  return remainder < 0 ? remainder + divisor : remainder;
+}
+
+function scrollEvent(x: number) {
+  return {
+    nativeEvent: { contentOffset: { x, y: 0 } },
+  } as NativeSyntheticEvent<NativeScrollEvent>;
+}
+
+const CarouselImpl = forwardRef<CarouselRef, CarouselProps>((props, ref) => {
   const {
+    // engine props
     data,
     renderItem,
     keyExtractor,
-    firstItem = 0,
-    itemWidth: itemWidthProp,
+    defaultIndex,
+    loop,
+    autoplay = false,
+    autoplayInterval,
+    autoplayDirection,
+    orientation = 'horizontal',
+    itemSize,
+    scrollEnabled,
+    snapMode,
+    overscrollEnabled,
+    renderWindowSize,
+    animation,
+    progress,
+    onProgressChange,
+    scrollOffsetValue,
+    style,
+    contentContainerStyle,
+    testID,
+    onLayout,
+    onConfigurePanGesture,
+    onScrollStart,
+    onSnapToItem,
+    layout,
+    itemAnimation,
+
+    // legacy props
+    firstItem,
+    itemWidth,
     visibleItem = 1,
     full = false,
-    activeSlideOffset = 20,
-    scrollEnabled = true,
-    enableSnap = true,
-    snapToInterval: snapToIntervalProp,
-    disableIntervalMomentum = Platform.OS === 'android',
-    loop = false,
-    loopClonesPerSide = 3,
-    autoplay = false,
-    autoplayDelay = 1000,
-    autoplayInterval = 3000,
+    enableSnap,
+    autoplayDelay = 0,
     inactiveSlideOpacity = 1,
     inactiveSlideScale = 1,
     apparitionDelay = 0,
-    style,
     slideStyle,
-    contentContainerStyle,
-    onSnapToItem,
     onScrollIndexChanged,
-    onScroll: onScrollProp,
-    onMomentumScrollEnd: onMomentumScrollEndProp,
-    onTouchStart: onTouchStartProp,
-    onTouchEnd: onTouchEndProp,
-    onLayout: onLayoutProp,
-    getItemLayout: getItemLayoutProp,
+    onScroll,
+    onTouchStart,
+    onTouchEnd,
   } = props;
 
-  const flatListRef = useRef<FlatList>(null);
-  const autoplayTimerRef = useRef<ReturnType<typeof setInterval> | null>(null);
-  const scrollX = useSharedValue(0);
-  const containerWidthRef = useRef(viewportWidth);
-  const isAutoplayPausedRef = useRef(false);
-  const currentIndexRef = useRef(firstItem);
-
-  const [currentIndex, setCurrentIndex] = useState(firstItem);
-  const [containerWidth, setContainerWidth] = useState(viewportWidth);
-  const [isVisible, setIsVisible] = useState(apparitionDelay === 0);
-  const [isLayoutReady, setIsLayoutReady] = useState(false);
-
-  const itemWidth = useMemo(() => {
-    if (full) {
-      return containerWidth;
-    }
-    if (itemWidthProp) {
-      return itemWidthProp;
-    }
-    const spacing = visibleItem > 1 ? 10 : 0;
-    return (containerWidth - spacing * (visibleItem - 1)) / visibleItem;
-  }, [containerWidth, full, itemWidthProp, visibleItem]);
-
-  const snapToInterval = useMemo(() => {
-    if (snapToIntervalProp !== undefined) {
-      return snapToIntervalProp;
-    }
-    return itemWidth;
-  }, [itemWidth, snapToIntervalProp]);
-
-  const dataWithClones = useMemo(() => {
-    if (!loop || data.length === 0) {
-      return data;
+  const coreRef = useRef<CoreCarouselRef>(null);
+  const suppressUntilRef = useRef(0);
+  const autoplayDelayTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+
+  const [containerSize, setContainerSize] = useState(WINDOW_WIDTH);
+  const [measuredItemSize, setMeasuredItemSize] = useState<number | null>(null);
+  const [isVisible, setIsVisible] = useState(apparitionDelay <= 0);
+  const [isAutoplayRunning, setIsAutoplayRunning] = useState(false);
+
+  const isVertical = orientation === 'vertical';
+  const flattenedStyle = StyleSheet.flatten(style) ?? {};
+  const sizeField = isVertical ? 'width' : 'height';
+  const hasExplicitSize =
+    flattenedStyle[sizeField] !== undefined ||
+    flattenedStyle.flex !== undefined ||
+    flattenedStyle.flexGrow !== undefined;
+
+  const warnedRef = useRef(false);
+  if (__DEV__ && !warnedRef.current) {
+    warnedRef.current = true;
+    for (const name of IGNORED_LEGACY_PROPS) {
+      if (props[name] !== undefined) {
+        console.warn(
+          `[@momo-kits/carousel] \`${name}\` is no longer supported and is ignored.`
+        );
+      }
     }
-
-    const clones = [];
-    for (let i = 0; i < loopClonesPerSide; i++) {
-      const startIndex = data.length - loopClonesPerSide + i;
-      const endIndex = i;
-      clones.push(data[startIndex >= 0 ? startIndex : data.length + startIndex]);
+    for (const name of ['onTouchStart', 'onTouchEnd'] as const) {
+      if (props[name] && props[name]!.length > 0) {
+        console.warn(
+          `[@momo-kits/carousel] \`${name}\` is called without an event object; the gesture handler has no GestureResponderEvent to pass.`
+        );
+      }
     }
+  }
 
-    const result = [...clones, ...data];
-
-    for (let i = 0; i < loopClonesPerSide; i++) {
-      result.push(data[i % data.length]);
+  const resolvedItemSize = useMemo(() => {
+    if (itemSize && itemSize > 0) return itemSize;
+    if (itemWidth && itemWidth > 0) return itemWidth;
+    if (!full && visibleItem > 1) {
+      const size =
+        (containerSize - MULTI_ITEM_SPACING * (visibleItem - 1)) / visibleItem;
+      return size > 0 ? size : undefined;
     }
+    // Undefined lets the engine measure the container itself.
+    return undefined;
+  }, [containerSize, full, itemSize, itemWidth, visibleItem]);
+
+  /** Size the animations interpolate against. */
+  const pageSize = resolvedItemSize ?? containerSize;
+
+  const resolvedDefaultIndex = useMemo(() => {
+    const requested = defaultIndex ?? firstItem ?? 0;
+    return Number.isInteger(requested) &&
+      requested >= 0 &&
+      requested < data.length
+      ? requested
+      : 0;
+  }, [data.length, defaultIndex, firstItem]);
+
+  const resolvedSnapMode = snapMode ?? (enableSnap === false ? 'none' : 'page');
+
+  const hasLegacyItemAnimation =
+    inactiveSlideOpacity < 1 || inactiveSlideScale < 1;
+
+  const legacyItemAnimation = useMemo<CarouselItemAnimation | undefined>(() => {
+    if (!hasLegacyItemAnimation) return undefined;
+
+    // An `itemAnimation` replaces the built-in layout, so it has to carry the
+    // slide translation as well as the legacy opacity/scale.
+    const size = pageSize;
+    const directionSign = I18nManager.isRTL ? -1 : 1;
+    const minOpacity = inactiveSlideOpacity;
+    const minScale = inactiveSlideScale;
+
+    return (relativeProgress: number) => {
+      'worklet';
+      const translate = interpolate(
+        relativeProgress,
+        [-1, 0, 1],
+        [-size, 0, size]
+      );
+      const opacity =
+        minOpacity < 1
+          ? interpolate(
+              relativeProgress,
+              [-1, 0, 1],
+              [minOpacity, 1, minOpacity],
+              Extrapolation.CLAMP
+            )
+          : 1;
+      const scale =
+        minScale < 1
+          ? interpolate(
+              relativeProgress,
+              [-1, 0, 1],
+              [minScale, 1, minScale],
+              Extrapolation.CLAMP
+            )
+          : 1;
 
-    return result;
-  }, [data, loop, loopClonesPerSide]);
-
-  const getRealIndex = useCallback(
-    (index: number) => {
-      if (!loop) return index;
-      
-      const dataLength = data.length;
-      if (dataLength === 0) return 0;
-
-      let realIndex = index - loopClonesPerSide;
-      
-      if (realIndex < 0) {
-        realIndex = dataLength + realIndex;
-      } else if (realIndex >= dataLength) {
-        realIndex = realIndex % dataLength;
-      }
-
-      return realIndex;
-    },
-    [loop, loopClonesPerSide, data.length]
-  );
-
-  const getLoopIndex = useCallback(
-    (realIndex: number) => {
-      if (!loop) return realIndex;
-      return realIndex + loopClonesPerSide;
+      return {
+        opacity,
+        transform: [
+          isVertical
+            ? { translateY: translate }
+            : { translateX: translate * directionSign },
+          { scale },
+        ],
+      };
+    };
+  }, [
+    hasLegacyItemAnimation,
+    inactiveSlideOpacity,
+    inactiveSlideScale,
+    isVertical,
+    pageSize,
+  ]);
+
+  const resolvedItemAnimation =
+    itemAnimation ?? (layout ? undefined : legacyItemAnimation);
+
+  const handleContainerLayout = useCallback(
+    (event: LayoutChangeEvent) => {
+      const { width, height } = event.nativeEvent.layout;
+      const size = isVertical ? height : width;
+      if (size > 0) setContainerSize(size);
+      onLayout?.(event);
     },
-    [loop, loopClonesPerSide]
+    [isVertical, onLayout]
   );
 
-  const snapToItem = useCallback(
-    (index: number, animated = true, fireCallback = true) => {
-      if (!flatListRef.current || index < 0 || index >= data.length) {
-        return;
-      }
-
-      const loopIndex = getLoopIndex(index);
-      const offset = loopIndex * itemWidth;
-
-      flatListRef.current.scrollToOffset({
-        offset,
-        animated,
-      });
-
-      currentIndexRef.current = index;
-      setCurrentIndex(index);
-
-      if (fireCallback && onSnapToItem) {
-        onSnapToItem(index);
+  const handleItemLayout = useCallback(
+    (event: LayoutChangeEvent) => {
+      if (hasExplicitSize) return;
+      const { width, height } = event.nativeEvent.layout;
+      const size = isVertical ? width : height;
+      if (size > 0) {
+        setMeasuredItemSize(prev => (prev === null || size > prev ? size : prev));
       }
     },
-    [data.length, getLoopIndex, itemWidth, onSnapToItem]
+    [hasExplicitSize, isVertical]
   );
 
-  const snapToNext = useCallback(
-    (animated = true, fireCallback = true) => {
-      const nextIndex = (currentIndexRef.current + 1) % data.length;
-      snapToItem(nextIndex, animated, fireCallback);
-    },
-    [data.length, snapToItem]
+  const slideWrapperStyle = useMemo(
+    () => (hasExplicitSize ? styles.slideFill : styles.slideAuto),
+    [hasExplicitSize]
   );
 
-  const snapToPrev = useCallback(
-    (animated = true, fireCallback = true) => {
-      const prevIndex =
-        currentIndexRef.current === 0 ? data.length - 1 : currentIndexRef.current - 1;
-      snapToItem(prevIndex, animated, fireCallback);
-    },
-    [data.length, snapToItem]
+  const renderCoreItem = useCallback(
+    (info: { item: any; index: number; relativeProgress: SharedValue<number> }) => (
+      <View style={[slideWrapperStyle, slideStyle]} onLayout={handleItemLayout}>
+        {renderItem(info)}
+      </View>
+    ),
+    [handleItemLayout, renderItem, slideStyle, slideWrapperStyle]
   );
 
-  const stopAutoplay = useCallback(() => {
-    if (autoplayTimerRef.current) {
-      clearInterval(autoplayTimerRef.current);
-      autoplayTimerRef.current = null;
-    }
-  }, []);
+  const lastIndexRef = useRef(resolvedDefaultIndex);
 
-  const pauseAutoPlay = useCallback(() => {
-    isAutoplayPausedRef.current = true;
-    stopAutoplay();
-  }, [stopAutoplay]);
+  const needsProgress = !!(onProgressChange || onScroll || onScrollIndexChanged);
 
-  const startAutoplay = useCallback(() => {
-    stopAutoplay();
-    isAutoplayPausedRef.current = false;
+  const handleProgressChange = useCallback(
+    (value: number) => {
+      onProgressChange?.(value);
+      onScroll?.(scrollEvent(value * pageSize));
 
-    if (!autoplay || data.length <= 1) {
-      return;
-    }
-
-    const startTimer = () => {
-      autoplayTimerRef.current = setInterval(() => {
-        if (!isAutoplayPausedRef.current) {
-          snapToNext(true, true);
+      if (onScrollIndexChanged && data.length > 0) {
+        const index = positiveModulo(Math.round(value), data.length);
+        if (index !== lastIndexRef.current) {
+          lastIndexRef.current = index;
+          onScrollIndexChanged(index);
         }
-      }, autoplayInterval);
-    };
-
-    if (autoplayDelay > 0) {
-      setTimeout(startTimer, autoplayDelay);
-    } else {
-      startTimer();
-    }
-  }, [autoplay, autoplayDelay, autoplayInterval, data.length, snapToNext, stopAutoplay]);
-
-  const handleLoopReposition = useCallback(
-    (index: number) => {
-      if (!loop || !flatListRef.current) return;
-
-      const dataLength = data.length;
-      if (dataLength === 0) return;
-
-      if (index < loopClonesPerSide) {
-        const realIndex = dataLength - (loopClonesPerSide - index);
-        const loopIndex = getLoopIndex(realIndex);
-        setTimeout(() => {
-          flatListRef.current?.scrollToOffset({
-            offset: loopIndex * itemWidth,
-            animated: false,
-          });
-        }, 50);
-      } else if (index >= dataLength + loopClonesPerSide) {
-        const realIndex = index - (dataLength + loopClonesPerSide);
-        const loopIndex = getLoopIndex(realIndex);
-        setTimeout(() => {
-          flatListRef.current?.scrollToOffset({
-            offset: loopIndex * itemWidth,
-            animated: false,
-          });
-        }, 50);
       }
     },
-    [loop, data.length, loopClonesPerSide, itemWidth, getLoopIndex]
+    [data.length, onProgressChange, onScroll, onScrollIndexChanged, pageSize]
   );
 
-  const handleScroll = useCallback(
-    (offsetX: number) => {
-      const index = Math.round(offsetX / itemWidth);
-      const realIndex = getRealIndex(index);
-
-      if (realIndex !== currentIndexRef.current) {
-        currentIndexRef.current = realIndex;
-        setCurrentIndex(realIndex);
-
-        if (onScrollIndexChanged) {
-          onScrollIndexChanged(realIndex);
-        }
-      }
-    },
-    [itemWidth, getRealIndex, onScrollIndexChanged]
-  );
-
-  const handleMomentumScrollEnd = useCallback(
-    (event: NativeSyntheticEvent<NativeScrollEvent>) => {
-      const offsetX = event.nativeEvent.contentOffset.x;
-      const index = Math.round(offsetX / itemWidth);
-      const realIndex = getRealIndex(index);
-
-      currentIndexRef.current = realIndex;
-      setCurrentIndex(realIndex);
+  const handleSnapToItem = useCallback(
+    (index: number) => {
+      lastIndexRef.current = index;
 
-      if (onSnapToItem) {
-        onSnapToItem(realIndex);
+      if (Date.now() < suppressUntilRef.current) {
+        suppressUntilRef.current = 0;
+        return;
       }
 
-      handleLoopReposition(index);
-
-      if (onMomentumScrollEndProp) {
-        onMomentumScrollEndProp(event);
-      }
+      onSnapToItem?.(index);
     },
-    [itemWidth, getRealIndex, onSnapToItem, handleLoopReposition, onMomentumScrollEndProp]
+    [onSnapToItem]
   );
 
-  const handleTouchStart = useCallback(
-    (event: any) => {
-      if (autoplay) {
-        pauseAutoPlay();
-      }
-      if (onTouchStartProp) {
-        onTouchStartProp(event);
-      }
-    },
-    [autoplay, pauseAutoPlay, onTouchStartProp]
+  const needsGestureConfig = !!(
+    onConfigurePanGesture ||
+    onTouchStart ||
+    onTouchEnd
   );
 
-  const handleTouchEnd = useCallback(
-    (event: GestureResponderEvent) => {
-      if (autoplay && !isAutoplayPausedRef.current) {
-        startAutoplay();
+  const configurePanGesture = useCallback(
+    (gesture: CarouselPanGesture) => {
+      if (onTouchStart) {
+        gesture.onBegin(() => {
+          'worklet';
+          runOnJS(onTouchStart)();
+        });
       }
-      if (onTouchEndProp) {
-        onTouchEndProp(event);
+      if (onTouchEnd) {
+        gesture.onFinalize(() => {
+          'worklet';
+          runOnJS(onTouchEnd)();
+        });
       }
+      onConfigurePanGesture?.(gesture);
     },
-    [autoplay, startAutoplay, onTouchEndProp]
+    [onConfigurePanGesture, onTouchEnd, onTouchStart]
   );
 
-  const handleLayout = useCallback(
-    (event: LayoutChangeEvent) => {
-      const { width } = event.nativeEvent.layout;
-      containerWidthRef.current = width;
-      setContainerWidth(width);
-      setIsLayoutReady(true);
-
-      if (onLayoutProp) {
-        onLayoutProp(event);
-      }
-    },
-    [onLayoutProp]
-  );
-
-  const getItemLayout = useCallback(
-    (data: any, index: number) => {
-      if (getItemLayoutProp) {
-        return getItemLayoutProp(data, index);
-      }
-      return {
-        length: itemWidth,
-        offset: itemWidth * index,
-        index,
-      };
-    },
-    [itemWidth, getItemLayoutProp]
-  );
+  const clearAutoplayDelay = useCallback(() => {
+    if (autoplayDelayTimerRef.current) {
+      clearTimeout(autoplayDelayTimerRef.current);
+      autoplayDelayTimerRef.current = null;
+    }
+  }, []);
 
-  const renderAnimatedItem = useCallback(
-    ({ item, index }: { item: any; index: number }) => {
-      const realIndex = getRealIndex(index);
-      const hasOpacityAnimation = inactiveSlideOpacity < 1;
-      const hasScaleAnimation = inactiveSlideScale < 1;
-
-      if (!hasOpacityAnimation && !hasScaleAnimation) {
-        return (
-          <View style={[{ width: itemWidth }, slideStyle]}>
-            {renderItem({ item, index: realIndex })}
-          </View>
-        );
-      }
+  const startAutoplay = useCallback(() => {
+    clearAutoplayDelay();
+    if (!autoplay) return;
 
-      return (
-        <CarouselItem
-          index={index}
-          itemWidth={itemWidth}
-          scrollX={scrollX}
-          inactiveSlideOpacity={inactiveSlideOpacity}
-          inactiveSlideScale={inactiveSlideScale}
-          slideStyle={slideStyle}
-        >
-          {renderItem({ item, index: realIndex })}
-        </CarouselItem>
+    if (autoplayDelay > 0) {
+      autoplayDelayTimerRef.current = setTimeout(
+        () => setIsAutoplayRunning(true),
+        autoplayDelay
       );
-    },
-    [
-      getRealIndex,
-      inactiveSlideOpacity,
-      inactiveSlideScale,
-      itemWidth,
-      slideStyle,
-      renderItem,
-      scrollX,
-    ]
-  );
-
-  const handleKeyExtractor = useCallback(
-    (item: any, index: number) => {
-      if (keyExtractor) {
-        return keyExtractor(item, index);
-      }
-      return `carousel-item-${index}`;
-    },
-    [keyExtractor]
-  );
-
-  const emitScrollProp = useCallback(
-    (offsetX: number) => {
-      if (onScrollProp) {
-        onScrollProp({
-          nativeEvent: { contentOffset: { x: offsetX, y: 0 } },
-        } as NativeSyntheticEvent<NativeScrollEvent>);
-      }
-    },
-    [onScrollProp],
-  );
-
-  const onScrollEvent = useAnimatedScrollHandler({
-    onScroll: (event) => {
-      scrollX.value = event.contentOffset.x;
-      runOnJS(handleScroll)(event.contentOffset.x);
-      runOnJS(emitScrollProp)(event.contentOffset.x);
-    },
-  });
-
-  useEffect(() => {
-    if (isLayoutReady && firstItem > 0 && firstItem < data.length) {
-      setTimeout(() => {
-        snapToItem(firstItem, false, false);
-      }, 50);
+    } else {
+      setIsAutoplayRunning(true);
     }
-  }, [isLayoutReady, firstItem, data.length, snapToItem]);
+  }, [autoplay, autoplayDelay, clearAutoplayDelay]);
+
+  const pauseAutoplay = useCallback(() => {
+    clearAutoplayDelay();
+    setIsAutoplayRunning(false);
+  }, [clearAutoplayDelay]);
 
   useEffect(() => {
-    if (autoplay && data.length > 1) {
-      startAutoplay();
-    }
+    if (autoplay) startAutoplay();
+    else pauseAutoplay();
 
-    return () => {
-      stopAutoplay();
-    };
-  }, [autoplay, data.length, startAutoplay, stopAutoplay]);
+    return clearAutoplayDelay;
+  }, [autoplay, clearAutoplayDelay, pauseAutoplay, startAutoplay]);
 
   useEffect(() => {
-    if (apparitionDelay > 0) {
-      const timer = setTimeout(() => {
-        setIsVisible(true);
-      }, apparitionDelay);
+    if (apparitionDelay <= 0) return;
 
-      return () => clearTimeout(timer);
-    }
+    const timer = setTimeout(() => setIsVisible(true), apparitionDelay);
+    return () => clearTimeout(timer);
   }, [apparitionDelay]);
 
+  const suppressNextCallback = useCallback(() => {
+    suppressUntilRef.current = Date.now() + SUPPRESS_CALLBACK_WINDOW;
+  }, []);
+
   useImperativeHandle(
     ref,
     () => ({
-      snapToItem,
-      snapToNext,
-      snapToPrev,
+      next: options => coreRef.current?.next(options),
+      prev: options => coreRef.current?.prev(options),
+      scrollTo: options => coreRef.current?.scrollTo(options),
+      getCurrentIndex: () => coreRef.current?.getCurrentIndex() ?? 0,
+
+      snapToItem: (index, animated = true, fireCallback = true) => {
+        if (!fireCallback) suppressNextCallback();
+        coreRef.current?.scrollTo({ index, animated });
+      },
+      snapToNext: (animated = true, fireCallback = true) => {
+        if (!fireCallback) suppressNextCallback();
+        coreRef.current?.next({ animated });
+      },
+      snapToPrev: (animated = true, fireCallback = true) => {
+        if (!fireCallback) suppressNextCallback();
+        coreRef.current?.prev({ animated });
+      },
       startAutoplay,
-      pauseAutoplay: pauseAutoPlay,
-      stopAutoplay,
+      pauseAutoplay,
+      stopAutoplay: pauseAutoplay,
     }),
-    [snapToItem, snapToNext, snapToPrev, startAutoplay, pauseAutoPlay, stopAutoplay]  // eslint-disable-line react-hooks/exhaustive-deps
+    [pauseAutoplay, startAutoplay, suppressNextCallback]
   );
 
+  // A FlatList grows into the space it is given and otherwise takes the height
+  // of its content. Items are absolutely positioned here, so both halves of
+  // that have to be restored when the caller sets no size of its own.
+  const resolvedStyle = hasExplicitSize
+    ? style
+    : [
+        styles.autoSize,
+        measuredItemSize === null
+          ? null
+          : { [isVertical ? 'minWidth' : 'minHeight']: measuredItemSize },
+        style,
+      ];
+
   if (!isVisible) {
-    return <View style={[styles.container, style]} />;
+    return <View style={resolvedStyle} testID={testID} />;
   }
 
-  return (
-    <View style={[styles.container, style]} onLayout={handleLayout}>
-      <AnimatedFlatList
-        ref={flatListRef}
-        data={dataWithClones}
-        renderItem={renderAnimatedItem}
-        keyExtractor={handleKeyExtractor}
-        horizontal
-        showsHorizontalScrollIndicator={false}
-        scrollEnabled={scrollEnabled}
-        scrollEventThrottle={16}
-        onScroll={onScrollEvent}
-        onMomentumScrollEnd={handleMomentumScrollEnd}
-        onTouchStart={handleTouchStart}
-        onTouchEnd={handleTouchEnd}
-        snapToInterval={enableSnap ? (snapToInterval as number) : undefined}
-        snapToAlignment={enableSnap ? 'start' : undefined}
-        decelerationRate={enableSnap ? 'fast' : 'normal'}
-        disableIntervalMomentum={disableIntervalMomentum}
-        getItemLayout={getItemLayout}
-        contentContainerStyle={contentContainerStyle}
-        removeClippedSubviews={false}
-        initialNumToRender={Math.min(10, dataWithClones.length)}
-        maxToRenderPerBatch={5}
-        windowSize={5}
-      />
-    </View>
-  );
+  // `layout` and `itemAnimation` are a union in the engine props; both are
+  // optional here, so the object is assembled before the cast.
+  const coreProps = {
+    data,
+    renderItem: renderCoreItem,
+    defaultIndex: resolvedDefaultIndex,
+    orientation,
+    snapMode: resolvedSnapMode,
+    autoplay: isAutoplayRunning,
+    style: resolvedStyle,
+    onLayout: handleContainerLayout,
+    onSnapToItem: handleSnapToItem,
+    ...(keyExtractor ? { keyExtractor } : null),
+    ...(loop !== undefined ? { loop } : null),
+    ...(autoplayInterval !== undefined ? { autoplayInterval } : null),
+    ...(autoplayDirection !== undefined ? { autoplayDirection } : null),
+    ...(resolvedItemSize ? { itemSize: resolvedItemSize } : null),
+    ...(scrollEnabled !== undefined ? { scrollEnabled } : null),
+    ...(overscrollEnabled !== undefined ? { overscrollEnabled } : null),
+    ...(renderWindowSize !== undefined ? { renderWindowSize } : null),
+    ...(animation ? { animation } : null),
+    ...(progress ? { progress } : null),
+    ...(scrollOffsetValue ? { scrollOffsetValue } : null),
+    ...(contentContainerStyle ? { contentContainerStyle } : null),
+    ...(testID ? { testID } : null),
+    ...(onScrollStart ? { onScrollStart } : null),
+    ...(layout ? { layout } : null),
+    ...(resolvedItemAnimation
+      ? { itemAnimation: resolvedItemAnimation }
+      : null),
+    ...(needsProgress ? { onProgressChange: handleProgressChange } : null),
+    ...(needsGestureConfig
+      ? { onConfigurePanGesture: configurePanGesture }
+      : null),
+  } as CoreCarouselProps<any>;
+
+  return <CoreCarousel ref={coreRef} {...coreProps} />;
 });
 
 const styles = StyleSheet.create({
-  container: {
-    overflow: 'hidden',
+  autoSize: {
+    flexGrow: 1,
+    flexShrink: 1,
+  },
+  slideAuto: {
+    width: '100%',
+  },
+  slideFill: {
+    width: '100%',
+    height: '100%',
   },
 });
 
-Carousel.displayName = 'Carousel';
+CarouselImpl.displayName = 'Carousel';
+
+type CarouselComponent = <Item>(
+  props: CarouselProps<Item> & { ref?: React.Ref<CarouselRef> }
+) => React.ReactElement;
 
+export const Carousel = CarouselImpl as CarouselComponent;
 export default Carousel;
-export { Carousel };
-export type { CarouselProps, CarouselRef };
 
+export type {
+  CarouselAnimation,
+  CarouselItemAnimation,
+  CarouselLayout,
+  CarouselPanGesture,
+  CarouselProgressChangeHandler,
+  CarouselProps,
+  CarouselRef,
+  CarouselRenderItem,
+  CarouselRenderItemInfo,
+  CarouselScrollToOptions,
+  CarouselStepOptions,
+} from './types';