@leonsilicon/react-native-reanimated-carousel 0.0.0

package/src/components/Pagination/Basic/PaginationItem.tsx

@@ -0,0 +1,149 @@
+import type { PropsWithChildren } from "react";
+import React, { useState } from "react";
+import type { AccessibilityRole, AccessibilityState, ViewStyle } from "react-native";
+import { Pressable, View } from "react-native";
+import type { SharedValue } from "react-native-reanimated";
+import Animated, {
+  Extrapolation,
+  interpolate,
+  useAnimatedReaction,
+  useAnimatedStyle,
+} from "react-native-reanimated";
+import { scheduleOnRN } from "react-native-worklets";
+
+export type DotStyle = Omit<ViewStyle, "width" | "height"> & {
+  width?: number;
+  height?: number;
+};
+
+export type PaginationItemAccessibilityOverrides = {
+  accessibilityLabel?: string;
+  accessibilityHint?: string;
+  accessibilityRole?: AccessibilityRole;
+  accessibilityState?: AccessibilityState;
+};
+
+export const PaginationItem: React.FC<
+  PropsWithChildren<{
+    index: number;
+    count: number;
+    size?: number;
+    animValue: SharedValue<number>;
+    horizontal?: boolean;
+    dotStyle?: DotStyle;
+    activeDotStyle?: DotStyle;
+    onPress: () => void;
+    accessibilityLabel?: string;
+    accessibilityHint?: string;
+    accessibilityRole?: AccessibilityRole;
+    accessibilityState?: AccessibilityState;
+  }>
+> = (props) => {
+  const {
+    animValue,
+    dotStyle,
+    activeDotStyle,
+    index,
+    count,
+    size,
+    horizontal,
+    children,
+    onPress,
+    accessibilityLabel,
+    accessibilityHint,
+    accessibilityRole,
+    accessibilityState,
+  } = props;
+
+  const defaultDotSize = 10;
+
+  const sizes = {
+    width: size || dotStyle?.width || defaultDotSize,
+    height: size || dotStyle?.height || defaultDotSize,
+  };
+
+  /**
+   * TODO: Keep this for future implementation
+   * Used to change the size of the active dot with animation
+   */
+  // const animatedSize = {
+  //   width: activeDotStyle?.width,
+  //   height: activeDotStyle?.height,
+  // };
+
+  const width = sizes.width;
+  const height = sizes.height;
+
+  const [isSelected, setIsSelected] = useState(false);
+  const resolvedAccessibilityLabel = accessibilityLabel ?? `Slide ${index + 1} of ${count}`;
+  const resolvedAccessibilityHint =
+    accessibilityHint ?? (isSelected ? "" : `Go to ${resolvedAccessibilityLabel}`);
+  const resolvedAccessibilityRole = accessibilityRole ?? "button";
+  const resolvedAccessibilityState = accessibilityState ?? { selected: isSelected };
+
+  useAnimatedReaction(
+    () => animValue.value,
+    (value) => {
+      scheduleOnRN(setIsSelected, value === index);
+    },
+    [animValue, index]
+  );
+
+  const animStyle = useAnimatedStyle(() => {
+    const size = horizontal ? height : width;
+    let inputRange = [index - 1, index, index + 1];
+    let outputRange = [-size, 0, size];
+
+    if (index === 0 && animValue?.value > count - 1) {
+      inputRange = [count - 1, count, count + 1];
+      outputRange = [-size, 0, size];
+    }
+
+    return {
+      transform: [
+        {
+          translateX: interpolate(animValue?.value, inputRange, outputRange, Extrapolation.CLAMP),
+        },
+      ],
+    };
+  }, [animValue, index, count, horizontal]);
+
+  return (
+    <Pressable
+      onPress={onPress}
+      accessibilityLabel={resolvedAccessibilityLabel}
+      accessibilityRole={resolvedAccessibilityRole}
+      accessibilityHint={resolvedAccessibilityHint}
+      accessibilityState={resolvedAccessibilityState}
+    >
+      <View
+        style={[
+          {
+            width,
+            height,
+            overflow: "hidden",
+            transform: [
+              {
+                rotateZ: horizontal ? "90deg" : "0deg",
+              },
+            ],
+          },
+          dotStyle,
+        ]}
+      >
+        <Animated.View
+          style={[
+            {
+              backgroundColor: "black",
+              flex: 1,
+            },
+            animStyle,
+            activeDotStyle,
+          ]}
+        >
+          {children}
+        </Animated.View>
+      </View>
+    </Pressable>
+  );
+};

package/src/components/Pagination/Basic/index.tsx

@@ -0,0 +1,98 @@
+import { type StyleProp, View, type ViewStyle } from "react-native";
+import type { SharedValue } from "react-native-reanimated";
+
+import React from "react";
+import type { DotStyle, PaginationItemAccessibilityOverrides } from "./PaginationItem";
+import { PaginationItem } from "./PaginationItem";
+
+export interface BasicProps<T> {
+  progress: SharedValue<number>;
+  horizontal?: boolean;
+  data: Array<T>;
+  renderItem?: (item: T, index: number) => React.ReactNode;
+  containerStyle?: StyleProp<ViewStyle>;
+  dotStyle?: DotStyle;
+  activeDotStyle?: DotStyle;
+  size?: number;
+  onPress?: (index: number) => void;
+  carouselName?: string;
+  /**
+   * Optional accessibility overrides for each pagination item.
+   * Use this to fully control screen reader announcements per dot.
+   */
+  paginationItemAccessibility?: (
+    index: number,
+    length: number
+  ) => PaginationItemAccessibilityOverrides;
+}
+
+export const Basic = <T extends {}>(props: BasicProps<T>) => {
+  const {
+    activeDotStyle,
+    dotStyle,
+    progress,
+    horizontal = true,
+    data,
+    size,
+    containerStyle,
+    renderItem,
+    onPress,
+    carouselName,
+    paginationItemAccessibility,
+  } = props;
+
+  if (
+    typeof size === "string" ||
+    typeof dotStyle?.width === "string" ||
+    typeof dotStyle?.height === "string"
+  )
+    throw new Error("size/width/height must be a number");
+
+  return (
+    <View
+      style={[
+        {
+          justifyContent: "space-between",
+          alignSelf: "center",
+        },
+        horizontal
+          ? {
+              flexDirection: "row",
+            }
+          : {
+              flexDirection: "column",
+            },
+        containerStyle,
+      ]}
+    >
+      {data.map((item, index) => {
+        const defaultAccessibilityLabel = carouselName
+          ? `Slide ${index + 1} of ${data.length} - ${carouselName}`
+          : `Slide ${index + 1} of ${data.length}`;
+        const accessibilityOverrides = paginationItemAccessibility?.(index, data.length) ?? {};
+
+        return (
+          <PaginationItem
+            key={index}
+            index={index}
+            size={size}
+            count={data.length}
+            dotStyle={dotStyle}
+            animValue={progress}
+            horizontal={!horizontal}
+            activeDotStyle={activeDotStyle}
+            onPress={() => onPress?.(index)}
+            accessibilityLabel={
+              accessibilityOverrides.accessibilityLabel ?? defaultAccessibilityLabel
+            }
+            accessibilityHint={accessibilityOverrides.accessibilityHint}
+            accessibilityRole={accessibilityOverrides.accessibilityRole}
+            accessibilityState={accessibilityOverrides.accessibilityState}
+          >
+            {renderItem?.(item, index)}
+          </PaginationItem>
+        );
+      })}
+    </View>
+  );
+};

package/src/components/Pagination/Custom/PaginationItem.tsx

@@ -0,0 +1,166 @@
+import type { PropsWithChildren } from "react";
+import React, { useState } from "react";
+import type { AccessibilityRole, AccessibilityState } from "react-native";
+import { Pressable } from "react-native";
+import type { ImageStyle, TextStyle, ViewStyle } from "react-native";
+import type { SharedValue } from "react-native-reanimated";
+import Animated, {
+  Extrapolation,
+  interpolate,
+  interpolateColor,
+  useAnimatedStyle,
+  useSharedValue,
+  useDerivedValue,
+  useAnimatedReaction,
+} from "react-native-reanimated";
+import { scheduleOnRN } from "react-native-worklets";
+
+type AnimatedDefaultStyle = ViewStyle | ImageStyle | TextStyle;
+
+export type PaginationItemAccessibilityOverrides = {
+  accessibilityLabel?: string;
+  accessibilityHint?: string;
+  accessibilityRole?: AccessibilityRole;
+  accessibilityState?: AccessibilityState;
+};
+
+export type DotStyle = Omit<ViewStyle, "width" | "height" | "backgroundColor" | "borderRadius"> & {
+  width?: number;
+  height?: number;
+  backgroundColor?: string;
+  borderRadius?: number;
+};
+
+export const PaginationItem: React.FC<
+  PropsWithChildren<{
+    index: number;
+    count: number;
+    size?: number;
+    animValue: SharedValue<number>;
+    horizontal?: boolean;
+    dotStyle?: DotStyle;
+    activeDotStyle?: DotStyle;
+    onPress: () => void;
+    customReanimatedStyle?: (
+      progress: number,
+      index: number,
+      length: number
+    ) => AnimatedDefaultStyle;
+    accessibilityLabel?: string;
+    accessibilityHint?: string;
+    accessibilityRole?: AccessibilityRole;
+    accessibilityState?: AccessibilityState;
+  }>
+> = (props) => {
+  const defaultDotSize = 10;
+  const {
+    animValue,
+    dotStyle,
+    activeDotStyle,
+    index,
+    count,
+    size,
+    horizontal,
+    children,
+    customReanimatedStyle,
+    onPress,
+    accessibilityLabel,
+    accessibilityHint,
+    accessibilityRole,
+    accessibilityState,
+  } = props;
+  const customReanimatedStyleRef = useSharedValue<AnimatedDefaultStyle>({});
+  const handleCustomAnimation = (progress: number) => {
+    customReanimatedStyleRef.value = customReanimatedStyle?.(progress, index, count) ?? {};
+  };
+
+  const [isSelected, setIsSelected] = useState(false);
+  const resolvedAccessibilityLabel = accessibilityLabel ?? `Slide ${index + 1} of ${count}`;
+  const resolvedAccessibilityHint =
+    accessibilityHint ?? (isSelected ? "" : `Go to ${resolvedAccessibilityLabel}`);
+  const resolvedAccessibilityRole = accessibilityRole ?? "button";
+  const resolvedAccessibilityState = accessibilityState ?? { selected: isSelected };
+
+  useDerivedValue(() => {
+    scheduleOnRN(handleCustomAnimation, animValue?.value);
+  });
+
+  useAnimatedReaction(
+    () => animValue.value,
+    (value) => {
+      scheduleOnRN(setIsSelected, value === index);
+    },
+    [animValue, index]
+  );
+
+  const animStyle = useAnimatedStyle((): AnimatedDefaultStyle => {
+    const {
+      width = size || defaultDotSize,
+      height = size || defaultDotSize,
+      borderRadius,
+      backgroundColor = "#FFF",
+      ...restDotStyle
+    } = dotStyle ?? {};
+    const {
+      width: activeWidth = width,
+      height: activeHeight = height,
+      borderRadius: activeBorderRadius,
+      backgroundColor: activeBackgroundColor = "#000",
+      ...restActiveDotStyle
+    } = activeDotStyle ?? {};
+    let val = Math.abs(animValue?.value - index);
+    if (index === 0 && animValue?.value > count - 1) val = Math.abs(animValue?.value - count);
+
+    const inputRange = [0, 1, 2];
+    const restStyle = (val === 0 ? restActiveDotStyle : restDotStyle) ?? {};
+
+    return {
+      width: interpolate(val, inputRange, [activeWidth, width, width], Extrapolation.CLAMP),
+      height: interpolate(val, inputRange, [activeHeight, height, height], Extrapolation.CLAMP),
+      borderRadius: interpolate(
+        val,
+        inputRange,
+        [activeBorderRadius ?? borderRadius ?? 0, borderRadius ?? 0, borderRadius ?? 0],
+        Extrapolation.CLAMP
+      ),
+      backgroundColor: interpolateColor(val, inputRange, [
+        activeBackgroundColor,
+        backgroundColor,
+        backgroundColor,
+      ]),
+      ...restStyle,
+      ...(customReanimatedStyleRef.value ?? {}),
+      transform: [
+        ...(restStyle?.transform ?? []),
+        ...(customReanimatedStyleRef.value?.transform ?? []),
+      ] as AnimatedDefaultStyle["transform"],
+    };
+  }, [animValue, index, count, horizontal, dotStyle, activeDotStyle, customReanimatedStyle]);
+
+  return (
+    <Pressable
+      onPress={onPress}
+      accessibilityLabel={resolvedAccessibilityLabel}
+      accessibilityRole={resolvedAccessibilityRole}
+      accessibilityHint={resolvedAccessibilityHint}
+      accessibilityState={resolvedAccessibilityState}
+    >
+      <Animated.View
+        style={[
+          {
+            overflow: "hidden",
+            transform: [
+              {
+                rotateZ: horizontal ? "90deg" : "0deg",
+              },
+            ],
+          },
+          dotStyle,
+          animStyle,
+        ]}
+      >
+        {children}
+      </Animated.View>
+    </Pressable>
+  );
+};

package/src/components/Pagination/Custom/index.tsx

@@ -0,0 +1,111 @@
+import React from "react";
+import type { ImageStyle, StyleProp, TextStyle, ViewStyle } from "react-native";
+import { View } from "react-native";
+import type { SharedValue } from "react-native-reanimated";
+
+import type { DotStyle, PaginationItemAccessibilityOverrides } from "./PaginationItem";
+import { PaginationItem } from "./PaginationItem";
+
+export interface ShapeProps<T extends {}> {
+  progress: SharedValue<number>;
+  horizontal?: boolean;
+  data: Array<T>;
+  renderItem?: (item: T, index: number) => React.ReactNode;
+  containerStyle?: StyleProp<ViewStyle>;
+  dotStyle?: DotStyle;
+  activeDotStyle?: DotStyle;
+  size?: number;
+  onPress?: (index: number) => void;
+  customReanimatedStyle?: (progress: number, index: number, length: number) => AnimatedDefaultStyle;
+  carouselName?: string;
+  /**
+   * Optional accessibility overrides for each pagination item.
+   * Use this to fully control screen reader announcements per dot.
+   */
+  paginationItemAccessibility?: (
+    index: number,
+    length: number
+  ) => PaginationItemAccessibilityOverrides;
+}
+
+type AnimatedDefaultStyle = ViewStyle | ImageStyle | TextStyle;
+
+export const Custom = <T extends {}>(props: ShapeProps<T>) => {
+  const {
+    activeDotStyle,
+    dotStyle,
+    progress,
+    horizontal = true,
+    data,
+    size,
+    containerStyle,
+    renderItem,
+    onPress,
+    customReanimatedStyle,
+    carouselName,
+    paginationItemAccessibility,
+  } = props;
+
+  if (
+    typeof size === "string" ||
+    typeof dotStyle?.width === "string" ||
+    typeof dotStyle?.height === "string" ||
+    typeof activeDotStyle?.width === "string" ||
+    typeof activeDotStyle?.height === "string"
+  )
+    throw new Error("size/width/height must be a number");
+
+  const maxItemWidth = Math.max(size ?? 0, dotStyle?.width ?? 0, activeDotStyle?.width ?? 0);
+  const maxItemHeight = Math.max(size ?? 0, dotStyle?.height ?? 0, activeDotStyle?.height ?? 0);
+
+  return (
+    <View
+      style={[
+        {
+          justifyContent: "space-between",
+          alignSelf: "center",
+          minWidth: maxItemWidth,
+          minHeight: maxItemHeight,
+        },
+        horizontal
+          ? {
+              flexDirection: "row",
+            }
+          : {
+              flexDirection: "column",
+            },
+        containerStyle,
+      ]}
+    >
+      {data.map((item, index) => {
+        const defaultAccessibilityLabel = carouselName
+          ? `Slide ${index + 1} of ${data.length} - ${carouselName}`
+          : `Slide ${index + 1} of ${data.length}`;
+        const accessibilityOverrides = paginationItemAccessibility?.(index, data.length) ?? {};
+
+        return (
+          <PaginationItem
+            key={index}
+            index={index}
+            size={size}
+            count={data.length}
+            dotStyle={dotStyle}
+            animValue={progress}
+            horizontal={!horizontal}
+            activeDotStyle={activeDotStyle}
+            customReanimatedStyle={customReanimatedStyle}
+            onPress={() => onPress?.(index)}
+            accessibilityLabel={
+              accessibilityOverrides.accessibilityLabel ?? defaultAccessibilityLabel
+            }
+            accessibilityHint={accessibilityOverrides.accessibilityHint}
+            accessibilityRole={accessibilityOverrides.accessibilityRole}
+            accessibilityState={accessibilityOverrides.accessibilityState}
+          >
+            {renderItem?.(item, index)}
+          </PaginationItem>
+        );
+      })}
+    </View>
+  );
+};

package/src/components/Pagination/Pagination.test.tsx

@@ -0,0 +1,178 @@
+import { act, fireEvent, render } from "@testing-library/react-native";
+import { View } from "react-native";
+import { useSharedValue } from "react-native-reanimated";
+
+import { Pagination } from ".";
+
+jest.mock("react-native-worklets", () => ({
+  scheduleOnRN: (fn: (...args: unknown[]) => void, ...args: unknown[]) => fn(...args),
+}));
+
+// Use fake timers so the reanimated mapper's mockedRequestAnimationFrame
+// (a setTimeout-based RAF) doesn't fire outside of act().
+beforeEach(() => {
+  jest.useFakeTimers();
+});
+
+afterEach(() => {
+  jest.useRealTimers();
+});
+
+describe("Pagination.Basic", () => {
+  it("throws when size/dot width/height are non-number", () => {
+    const Test = () => {
+      const progress = useSharedValue(0);
+      return (
+        <Pagination.Basic
+          data={[1, 2]}
+          progress={progress}
+          // @ts-expect-error intentional invalid type
+          size={"12px"}
+        />
+      );
+    };
+
+    expect(() => render(<Test />)).toThrow("size/width/height must be a number");
+  });
+
+  it("renders dots and calls onPress", async () => {
+    const handlePress = jest.fn();
+    const Test = () => {
+      const progress = useSharedValue(0);
+      return (
+        <Pagination.Basic
+          data={[1, 2, 3]}
+          progress={progress}
+          onPress={handlePress}
+          carouselName="Demo"
+        />
+      );
+    };
+
+    const { UNSAFE_root } = render(<Test />);
+    await act(async () => {
+      jest.advanceTimersByTime(100);
+    });
+
+    const buttons = UNSAFE_root.findAll(
+      (node) =>
+        node?.props?.accessibilityRole === "button" &&
+        typeof node?.props?.accessibilityLabel === "string" &&
+        node.props.accessibilityLabel.startsWith("Slide ")
+    );
+
+    const uniqueByLabel = Array.from(
+      new Map(buttons.map((b) => [b.props.accessibilityLabel, b])).values()
+    );
+
+    expect(uniqueByLabel).toHaveLength(3);
+
+    await act(async () => {
+      fireEvent.press(uniqueByLabel[1]);
+      jest.advanceTimersByTime(100);
+    });
+    expect(handlePress).toHaveBeenCalledWith(1);
+  });
+
+  it("does not include undefined in default accessibilityLabel when carouselName is omitted", async () => {
+    const Test = () => {
+      const progress = useSharedValue(0);
+      return <Pagination.Basic data={[1, 2]} progress={progress} />;
+    };
+
+    const { UNSAFE_root } = render(<Test />);
+    await act(async () => {
+      jest.advanceTimersByTime(100);
+    });
+
+    const buttons = UNSAFE_root.findAll(
+      (node) =>
+        node?.props?.accessibilityRole === "button" &&
+        typeof node?.props?.accessibilityLabel === "string" &&
+        node.props.accessibilityLabel.startsWith("Slide ")
+    );
+
+    const uniqueByLabel = Array.from(
+      new Map(buttons.map((b) => [b.props.accessibilityLabel, b])).values()
+    );
+
+    expect(uniqueByLabel[0].props.accessibilityLabel).toBe("Slide 1 of 2");
+    expect(uniqueByLabel[0].props.accessibilityLabel).not.toContain("undefined");
+  });
+});
+
+describe("Pagination.Custom", () => {
+  it("throws when any size-related prop is non-number", () => {
+    const Test = () => {
+      const progress = useSharedValue(0);
+      return (
+        <Pagination.Custom
+          data={[1]}
+          progress={progress}
+          // @ts-expect-error intentional invalid type
+          activeDotStyle={{ width: "10px" }}
+        />
+      );
+    };
+
+    expect(() => render(<Test />)).toThrow("size/width/height must be a number");
+  });
+
+  it("uses max item dimensions for container min sizes", async () => {
+    const Test = () => {
+      const progress = useSharedValue(0);
+      return (
+        <Pagination.Custom
+          data={[1, 2]}
+          progress={progress}
+          size={12}
+          dotStyle={{ width: 14, height: 8 }}
+          activeDotStyle={{ width: 16, height: 20 }}
+        />
+      );
+    };
+
+    const { UNSAFE_root } = render(<Test />);
+    await act(async () => {
+      jest.advanceTimersByTime(100);
+    });
+
+    // @ts-expect-error
+    const container = UNSAFE_root.findByType(View);
+    const flattened = Array.isArray(container.props.style)
+      ? Object.assign({}, ...container.props.style.filter(Boolean))
+      : container.props.style;
+
+    expect(flattened.minWidth).toBe(16);
+    expect(flattened.minHeight).toBe(20);
+  });
+
+  it("allows overriding pagination item accessibility props", async () => {
+    const Test = () => {
+      const progress = useSharedValue(0);
+      return (
+        <Pagination.Custom
+          data={[1, 2]}
+          progress={progress}
+          paginationItemAccessibility={(index: number, length: number) => ({
+            accessibilityLabel: `Page ${index + 1}/${length}`,
+            accessibilityHint: `Jump to ${index + 1}`,
+            accessibilityRole: "link",
+          })}
+        />
+      );
+    };
+
+    const { UNSAFE_root } = render(<Test />);
+    await act(async () => {
+      jest.advanceTimersByTime(100);
+    });
+
+    const item = UNSAFE_root.find(
+      (node) =>
+        node?.props?.accessibilityLabel === "Page 1/2" && node?.props?.accessibilityRole === "link"
+    );
+
+    expect(item.props.accessibilityHint).toBe("Jump to 1");
+  });
+});

package/src/components/Pagination/index.tsx

@@ -0,0 +1,7 @@
+import { Basic } from "./Basic";
+import { Custom } from "./Custom";
+
+export const Pagination = {
+  Basic,
+  Custom,
+};