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

package/core/hooks/useCarouselController.tsx

@@ -0,0 +1,295 @@
+import React, { useRef } from "react";
+import type { SharedValue } from "react-native-reanimated";
+import { useAnimatedReaction, useSharedValue } from "react-native-reanimated";
+import { scheduleOnRN } from "react-native-worklets";
+
+import { useGlobalState } from "../store";
+import type {
+  CarouselAnimation,
+  CarouselRef,
+  InternalCarouselScrollToOptions,
+  InternalCarouselStepOptions,
+} from "../types";
+import {
+  getLogicalProgress,
+  getNearestLogicalPage,
+  getSettledRawIndex,
+  getShortestLoopTargetPage,
+  positiveModulo,
+} from "../utils/carousel-math";
+import { dealWithAnimation } from "../utils/deal-with-animation";
+
+interface CarouselControllerOptions {
+  ref: React.ForwardedRef<CarouselRef>;
+  loop: boolean;
+  size: number;
+  dataLength: number;
+  rawDataLength: number;
+  handlerOffset: SharedValue<number>;
+  animation: CarouselAnimation;
+  defaultIndex?: number | undefined;
+  onScrollStart?: (() => void) | undefined;
+  onMovementEnd?: ((index: number) => void) | undefined;
+}
+
+export interface CarouselController {
+  getSharedIndex: () => number;
+  prev: (options?: InternalCarouselStepOptions) => void;
+  next: (options?: InternalCarouselStepOptions) => void;
+  getCurrentIndex: () => number;
+  scrollTo: (options: InternalCarouselScrollToOptions) => void;
+  index: SharedValue<number>;
+  startMovement: () => void;
+  cancelMovement: () => void;
+  settle: () => number;
+}
+
+export function useCarouselController(options: CarouselControllerOptions): CarouselController {
+  const {
+    animation,
+    dataLength,
+    defaultIndex = 0,
+    handlerOffset,
+    loop,
+    rawDataLength,
+    ref,
+    size,
+  } = options;
+  const {
+    common: {
+      cancelMovement: cancelCommonMovement,
+      dataRevision,
+      isMoving,
+      resolvedSize,
+      settleMovement,
+      sizePhase,
+      startMovement: startCommonMovement,
+    },
+  } = useGlobalState();
+
+  const index = useSharedValue(defaultIndex);
+  const liveRawIndex = useRef(rawDataLength > 0 ? defaultIndex : 0);
+  const settledIndex = useRef(rawDataLength > 0 ? defaultIndex : 0);
+  const warnedCommands = useRef(new Set<string>());
+  const canMove = rawDataLength > 1;
+
+  const warnOnce = React.useCallback((key: string, message: string) => {
+    if (!__DEV__ || warnedCommands.current.has(key)) return;
+    warnedCommands.current.add(key);
+    console.warn(`[react-native-reanimated-carousel] ${message}`);
+  }, []);
+
+  const currentVisualPage = React.useCallback(() => {
+    if (size <= 0 || rawDataLength <= 0) return 0;
+
+    const page = getNearestLogicalPage(handlerOffset.value, size);
+    return loop ? page : Math.max(0, Math.min(rawDataLength - 1, page));
+  }, [handlerOffset, loop, rawDataLength, size]);
+
+  function setLiveRawIndex(nextIndex: number) {
+    liveRawIndex.current = nextIndex;
+  }
+
+  useAnimatedReaction(
+    () => {
+      if (size <= 0 || dataLength <= 0 || rawDataLength <= 0) {
+        return { physicalIndex: 0, rawIndex: 0 };
+      }
+
+      const page = getNearestLogicalPage(handlerOffset.value, size);
+      return {
+        physicalIndex: positiveModulo(page, dataLength),
+        rawIndex: positiveModulo(page, rawDataLength),
+      };
+    },
+    ({ physicalIndex, rawIndex }) => {
+      index.value = physicalIndex;
+      scheduleOnRN(setLiveRawIndex, rawIndex);
+    },
+    [dataLength, handlerOffset, index, rawDataLength, size]
+  );
+
+  const settle = React.useCallback(
+    (targetIndex?: number) => {
+      settleMovement();
+
+      const nextSettledIndex =
+        typeof targetIndex === "number" && rawDataLength > 0
+          ? positiveModulo(Math.round(targetIndex), rawDataLength)
+          : getSettledRawIndex(
+              loop
+                ? getLogicalProgress(handlerOffset.value, size)
+                : Math.max(
+                    0,
+                    Math.min(rawDataLength - 1, getLogicalProgress(handlerOffset.value, size))
+                  ),
+              rawDataLength
+            );
+
+      settledIndex.current = nextSettledIndex;
+      return nextSettledIndex;
+    },
+    [handlerOffset, loop, rawDataLength, settleMovement, size]
+  );
+
+  const getCurrentIndex = React.useCallback(() => settledIndex.current, []);
+  const getSharedIndex = React.useCallback(() => liveRawIndex.current, []);
+  const startMovement = React.useCallback(() => startCommonMovement(), [startCommonMovement]);
+  const cancelMovement = React.useCallback(() => cancelCommonMovement(), [cancelCommonMovement]);
+
+  React.useEffect(() => {
+    if (!isMoving.value) settle();
+  }, [dataRevision, isMoving, rawDataLength, settle]);
+
+  const isReady = React.useCallback(() => {
+    const currentSize = resolvedSize.value ?? size;
+    return sizePhase.value === "ready" && currentSize > 0;
+  }, [resolvedSize, size, sizePhase]);
+
+  const emitStart = React.useCallback(() => {
+    startMovement();
+    options.onScrollStart?.();
+  }, [options, startMovement]);
+
+  const emitSettle = React.useCallback(
+    (targetIndex?: number) => {
+      const nextSettledIndex = settle(targetIndex);
+      options.onMovementEnd?.(nextSettledIndex);
+    },
+    [options, settle]
+  );
+
+  const animateTo = React.useCallback(
+    (targetOffset: number, targetIndex: number, onFinished?: () => void) => {
+      "worklet";
+      return dealWithAnimation(animation)(targetOffset, (finished) => {
+        "worklet";
+        if (finished) {
+          scheduleOnRN(emitSettle, targetIndex);
+          if (onFinished) scheduleOnRN(onFinished);
+        } else {
+          scheduleOnRN(cancelMovement);
+        }
+      });
+    },
+    [animation, cancelMovement, emitSettle]
+  );
+
+  const moveToPage = React.useCallback(
+    (targetPage: number, animated: boolean, onFinished?: () => void) => {
+      "worklet";
+      const targetRawIndex = positiveModulo(targetPage, rawDataLength);
+      emitStart();
+      index.value = positiveModulo(targetPage, Math.max(dataLength, 1));
+
+      const targetOffset = -targetPage * size;
+      if (animated) {
+        handlerOffset.value = animateTo(targetOffset, targetRawIndex, onFinished);
+      } else {
+        handlerOffset.value = targetOffset;
+        emitSettle(targetRawIndex);
+        onFinished?.();
+      }
+    },
+    [animateTo, dataLength, emitSettle, emitStart, handlerOffset, index, rawDataLength, size]
+  );
+
+  const validateCount = React.useCallback(
+    (command: "next" | "prev", count: number) => {
+      if (count === 0) return false;
+      if (Number.isInteger(count) && count > 0) return true;
+
+      warnOnce(
+        `${command}:count`,
+        `${command} count must be a positive integer; received ${String(count)}.`
+      );
+      return false;
+    },
+    [warnOnce]
+  );
+
+  const next = React.useCallback(
+    (stepOptions: InternalCarouselStepOptions = {}) => {
+      "worklet";
+      const { animated = true, count = 1, onFinished } = stepOptions;
+      if (!canMove || !isReady() || !validateCount("next", count)) return;
+
+      const currentPage = currentVisualPage();
+      const targetPage = loop
+        ? currentPage + count
+        : Math.min(rawDataLength - 1, currentPage + count);
+      if (targetPage === currentPage) return;
+
+      moveToPage(targetPage, animated, onFinished);
+    },
+    [canMove, currentVisualPage, isReady, loop, moveToPage, rawDataLength, validateCount]
+  );
+
+  const prev = React.useCallback(
+    (stepOptions: InternalCarouselStepOptions = {}) => {
+      "worklet";
+      const { animated = true, count = 1, onFinished } = stepOptions;
+      if (!canMove || !isReady() || !validateCount("prev", count)) return;
+
+      const currentPage = currentVisualPage();
+      const targetPage = loop ? currentPage - count : Math.max(0, currentPage - count);
+      if (targetPage === currentPage) return;
+
+      moveToPage(targetPage, animated, onFinished);
+    },
+    [canMove, currentVisualPage, isReady, loop, moveToPage, validateCount]
+  );
+
+  const scrollTo = React.useCallback(
+    (scrollOptions: InternalCarouselScrollToOptions) => {
+      "worklet";
+      const { animated = true, index: targetIndex, onFinished } = scrollOptions;
+      if (!canMove || !isReady()) return;
+
+      if (!Number.isInteger(targetIndex) || targetIndex < 0 || targetIndex >= rawDataLength) {
+        warnOnce(
+          "scrollTo:index",
+          `scrollTo index must be an integer between 0 and ${rawDataLength - 1}; received ${String(targetIndex)}.`
+        );
+        return;
+      }
+
+      const currentPage = currentVisualPage();
+      const currentRawIndex = positiveModulo(currentPage, rawDataLength);
+      if (currentRawIndex === targetIndex) return;
+
+      const targetPage = loop
+        ? getShortestLoopTargetPage({
+            currentPage,
+            targetIndex,
+            count: rawDataLength,
+          })
+        : targetIndex;
+      moveToPage(targetPage, animated, onFinished);
+    },
+    [canMove, currentVisualPage, isReady, loop, moveToPage, rawDataLength, warnOnce]
+  );
+
+  React.useImperativeHandle(
+    ref,
+    () => ({
+      next,
+      prev,
+      getCurrentIndex,
+      scrollTo,
+    }),
+    [getCurrentIndex, next, prev, scrollTo]
+  );
+
+  return {
+    next,
+    prev,
+    scrollTo,
+    getCurrentIndex,
+    getSharedIndex,
+    index,
+    startMovement,
+    cancelMovement,
+    settle,
+  };
+}

package/core/hooks/useCheckMounted.ts

@@ -0,0 +1,14 @@
+import React from "react";
+
+export function useCheckMounted() {
+  const mounted = React.useRef(false);
+
+  React.useEffect(() => {
+    mounted.current = true;
+    return () => {
+      mounted.current = false;
+    };
+  }, []);
+
+  return mounted;
+}

package/core/hooks/useCommonVariables.ts

@@ -0,0 +1,261 @@
+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 { InitializedCarouselProps } from "./useInitProps";
+
+import {
+  getNearestLogicalPage,
+  positiveModulo,
+  reconcileOffsetAfterDataChange,
+} from "../utils/carousel-math";
+import { computeOffsetIfSizeChanged } from "../utils/compute-offset-if-size-changed";
+
+export type CarouselSizePhase = "pending" | "ready" | "updating";
+
+export interface CarouselCommonVariables {
+  size: number;
+  validLength: number;
+  handlerOffset: SharedValue<number>;
+  resolvedSize: SharedValue<number | null>;
+  sizePhase: SharedValue<CarouselSizePhase>;
+  sizeExplicit: boolean;
+  isMoving: SharedValue<boolean>;
+  dataRevision: number;
+  startMovement: () => void;
+  cancelMovement: () => void;
+  settleMovement: () => void;
+}
+
+export function useCommonVariables(
+  props: InitializedCarouselProps<unknown>
+): CarouselCommonVariables {
+  const {
+    orientation,
+    style,
+    dataLength,
+    defaultIndex,
+    keyExtractor,
+    loop,
+    itemSize,
+    rawData,
+    rawDataLength,
+  } = props;
+  const isVertical = orientation === "vertical";
+
+  const manualSize = React.useMemo(() => {
+    if (typeof itemSize === "number" && itemSize > 0) {
+      return itemSize;
+    }
+
+    const { width, height } = StyleSheet.flatten(style) || {};
+    const candidate = isVertical ? height : width;
+    if (typeof candidate === "number" && candidate > 0) {
+      return candidate;
+    }
+
+    return null;
+  }, [isVertical, itemSize, style]);
+
+  const resolvedSize = useSharedValue<number | null>(manualSize);
+  const sizePhase = useSharedValue<CarouselSizePhase>(manualSize ? "ready" : "pending");
+
+  const defaultHandlerOffsetValue =
+    manualSize && dataLength > 0 ? -Math.abs(defaultIndex * manualSize) : 0;
+  const _handlerOffset = useSharedValue<number>(defaultHandlerOffsetValue);
+  const handlerOffset = props.scrollOffsetValue ?? _handlerOffset;
+  const prevDataLength = useSharedValue(rawDataLength);
+  const previousRawData = React.useRef(rawData);
+  const previousKeyExtractor = React.useRef(keyExtractor);
+  const isMoving = useSharedValue(false);
+  const pendingDataChange = useSharedValue<{
+    previousLength: number;
+    currentLength: number;
+    retainedIndex: number | null;
+  } | null>(null);
+  // Start at zero even when a synchronous item size is available. The first
+  // size reaction owns initialization and must write the default-index offset
+  // into consumer-provided SharedValues as well as the internal value.
+  const prevSize = useSharedValue(0);
+  const hasInitializedOffset = useSharedValue(false);
+  const sizeExplicit = typeof itemSize === "number" && itemSize > 0;
+
+  const [size, setSize] = React.useState<number>(manualSize ?? 0);
+  const [dataRevision, setDataRevision] = React.useState(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]);
+
+  React.useEffect(() => {
+    const currentSize = resolvedSize.value ?? 0;
+    if (currentSize <= 0 || dataLength <= 0 || hasInitializedOffset.value) return;
+
+    handlerOffset.value = -(defaultIndex * currentSize);
+    prevSize.value = currentSize;
+    hasInitializedOffset.value = true;
+  }, [dataLength, defaultIndex, handlerOffset, hasInitializedOffset, prevSize, resolvedSize]);
+
+  const reconcileDataChange = React.useCallback(
+    (previousLength: number, currentLength: number, retainedIndex?: number) => {
+      const currentSize = resolvedSize.value ?? 0;
+      if (currentSize <= 0) return;
+
+      handlerOffset.value = reconcileOffsetAfterDataChange({
+        offset: handlerOffset.value,
+        itemSize: currentSize,
+        previousCount: previousLength,
+        nextCount: currentLength,
+        defaultIndex,
+        loop,
+        retainedIndex,
+      });
+      setDataRevision((revision) => revision + 1);
+    },
+    [defaultIndex, handlerOffset, loop, resolvedSize]
+  );
+
+  const startMovement = React.useCallback(() => {
+    isMoving.value = true;
+  }, [isMoving]);
+
+  const finishMovement = React.useCallback(() => {
+    isMoving.value = false;
+    const pending = pendingDataChange.value;
+    if (!pending) return;
+
+    pendingDataChange.value = null;
+    reconcileDataChange(
+      pending.previousLength,
+      pending.currentLength,
+      pending.retainedIndex ?? undefined
+    );
+  }, [isMoving, pendingDataChange, reconcileDataChange]);
+
+  /**
+   * When data changes, we need to compute new index for handlerOffset
+   */
+  React.useEffect(() => {
+    const previousLength = prevDataLength.value;
+    const previousItems = previousRawData.current;
+    const dataChanged =
+      previousLength !== rawDataLength ||
+      previousItems.length !== rawData.length ||
+      previousItems.some((item, index) => !Object.is(item, rawData[index]));
+
+    previousRawData.current = rawData;
+    const extractorForPreviousData = previousKeyExtractor.current ?? keyExtractor;
+    previousKeyExtractor.current = keyExtractor;
+
+    if (!dataChanged) return;
+
+    let retainedIndex: number | undefined;
+    if (keyExtractor && extractorForPreviousData && previousLength > 0 && rawDataLength > 0) {
+      const currentSize = resolvedSize.value ?? 0;
+      const pendingIndex = pendingDataChange.value?.retainedIndex;
+      const previousIndex =
+        typeof pendingIndex === "number"
+          ? pendingIndex
+          : positiveModulo(getNearestLogicalPage(handlerOffset.value, currentSize), previousLength);
+      if (previousIndex < previousItems.length) {
+        const selectedKey = extractorForPreviousData(previousItems[previousIndex], previousIndex);
+        const matchingIndex = rawData.findIndex(
+          (item, index) => keyExtractor(item, index) === selectedKey
+        );
+        if (matchingIndex >= 0) retainedIndex = matchingIndex;
+      }
+    }
+
+    prevDataLength.value = rawDataLength;
+    if (isMoving.value) {
+      pendingDataChange.value = {
+        previousLength: pendingDataChange.value?.previousLength ?? previousLength,
+        currentLength: rawDataLength,
+        retainedIndex: retainedIndex ?? null,
+      };
+      return;
+    }
+
+    reconcileDataChange(previousLength, rawDataLength, retainedIndex);
+  }, [
+    handlerOffset,
+    isMoving,
+    keyExtractor,
+    pendingDataChange,
+    prevDataLength,
+    rawData,
+    rawDataLength,
+    reconcileDataChange,
+    resolvedSize,
+  ]);
+
+  /**
+   * When size changes, we need to compute new index for handlerOffset
+   */
+  useAnimatedReaction(
+    () => resolvedSize.value,
+    (currentSize) => {
+      if (currentSize == null || currentSize <= 0) return;
+      const previousSize = prevSize.value;
+
+      if (previousSize === currentSize) return;
+
+      sizePhase.value = previousSize > 0 ? "updating" : sizePhase.value;
+
+      if (dataLength <= 0) {
+        prevSize.value = currentSize;
+        sizePhase.value = "ready";
+        return;
+      }
+
+      if (previousSize <= 0 || !hasInitializedOffset.value) {
+        handlerOffset.value = -(defaultIndex * currentSize);
+        hasInitializedOffset.value = true;
+      } else {
+        handlerOffset.value = computeOffsetIfSizeChanged({
+          handlerOffset: handlerOffset.value,
+          prevSize: previousSize,
+          size: currentSize,
+        });
+      }
+
+      prevSize.value = currentSize;
+      sizePhase.value = "ready";
+    },
+    [dataLength, defaultIndex, hasInitializedOffset, resolvedSize, sizePhase]
+  );
+
+  return {
+    size,
+    validLength: dataLength - 1,
+    handlerOffset,
+    resolvedSize,
+    sizePhase,
+    sizeExplicit,
+    isMoving,
+    dataRevision,
+    startMovement,
+    cancelMovement: finishMovement,
+    settleMovement: finishMovement,
+  };
+}