react-native-app-onboard 0.1.9 → 0.2.0

package/src/context/OnboardingContext.tsx

@@ -1,22 +1,35 @@
 import React from 'react';
-import { Dimensions, type FlatList } from 'react-native';
+import {
+  AccessibilityInfo,
+  Animated,
+  Dimensions,
+  type FlatList,
+} from 'react-native';
 
 export type SliderProps = {
   currentPage: number;
   numberOfScreens: number;
   nextPage: (animated?: boolean) => void;
+  previousPage: (animated?: boolean) => void;
   scrollTo: (index: number, animated?: boolean) => void;
 };
 
 type OnboardingContextType = SliderProps & {
   setCurrentPage: (index: number) => void;
   flatListRef: React.RefObject<FlatList>;
+  // Callback ref forwarded to the underlying FlatList. Exposing a setter (vs.
+  // the ref object itself) keeps consumers React-Compiler-safe: assigning a
+  // foreign ref object to a `ref` prop is flagged as "ref access during
+  // render", whereas a callback ref is not.
+  setFlatListRef: (node: FlatList | null) => void;
   width?: number;
   numberOfScreens: number;
   progress: number;
   scrollEnabled?: boolean;
   enableScroll: React.Dispatch<React.SetStateAction<boolean | undefined>>;
   isDone: boolean;
+  pauseAutoPlay: () => void;
+  resumeAutoPlay: () => void;
 };
 
 type OnboardingProviderProps = {
@@ -24,6 +37,11 @@ type OnboardingProviderProps = {
   width?: number;
   numberOfScreens: number;
   scrollEnabled?: boolean;
+  onPageChange?: (index: number) => void;
+  scrollAnimationDuration?: number;
+  autoPlay?: boolean;
+  autoPlayInterval?: number;
+  loop?: boolean;
 };
 
 export const OnboardingContext = React.createContext<
@@ -32,10 +50,16 @@ export const OnboardingContext = React.createContext<
 
 export const OnboardingProvider: React.FC<OnboardingProviderProps> = ({
   children,
-  width = Dimensions.get('window').width,
+  width: widthProp,
   numberOfScreens,
   scrollEnabled,
+  onPageChange,
+  scrollAnimationDuration,
+  autoPlay = false,
+  autoPlayInterval = 3000,
+  loop = false,
 }) => {
+  const width = widthProp ?? Dimensions.get('window').width;
   const getProgress = (page: number) => {
     return Math.round(((page + 1) / numberOfScreens) * 100);
   };
@@ -46,45 +70,140 @@ export const OnboardingProvider: React.FC<OnboardingProviderProps> = ({
   const [enableScroll, setEnableScroll] = React.useState<boolean | undefined>(
     scrollEnabled
   );
-  const flatListRef = React.useRef<FlatList>(null);
+  const flatListRef = React.useRef<FlatList | null>(null);
+  const setFlatListRef = React.useCallback((node: FlatList | null) => {
+    flatListRef.current = node;
+  }, []);
+  // Tracks the latest page so timers/animations read a fresh value without
+  // needing to be recreated on every page change.
+  const currentPageRef = React.useRef(0);
+  const [isAutoPlaying, setIsAutoPlaying] = React.useState(autoPlay);
 
-  const setCurrentPage = (index: number) => {
-    setPage(index);
-    setProgress(getProgress(index));
-    setIsDone(index === numberOfScreens - 1);
-  };
+  // Keep autoplay in sync if the `autoPlay` prop is toggled after mount.
+  React.useEffect(() => {
+    setIsAutoPlaying(autoPlay);
+  }, [autoPlay]);
 
-  const nextPage = (animated: boolean = true) => {
-    if (flatListRef.current && currentPage < numberOfScreens - 1) {
-      flatListRef.current.scrollToOffset({
-        offset: width * (currentPage + 1),
-        animated: animated,
-      });
-      setCurrentPage(currentPage + 1);
-    }
-  };
+  // Dedicated value used to honor a custom scrollAnimationDuration. FlatList's
+  // own animated scroll has a fixed, platform-controlled duration, so when a
+  // duration is requested we drive the offset manually via this value.
+  const scrollAnim = React.useMemo(() => new Animated.Value(0), []);
+  React.useEffect(() => {
+    const id = scrollAnim.addListener(({ value }) => {
+      flatListRef.current?.scrollToOffset({ offset: value, animated: false });
+    });
+    return () => scrollAnim.removeListener(id);
+  }, [scrollAnim]);
 
-  const scrollTo = (index: number, animated: boolean = true) => {
-    if (flatListRef.current && index >= 0) {
-      flatListRef.current.scrollToOffset({
-        offset: index * width,
-        animated: animated,
-      });
-      setCurrentPage(index);
-    }
-  };
+  const animateToOffset = React.useCallback(
+    (offset: number, animated: boolean) => {
+      if (!flatListRef.current) return;
+      if (animated && scrollAnimationDuration) {
+        scrollAnim.stopAnimation();
+        scrollAnim.setValue(width * currentPageRef.current);
+        Animated.timing(scrollAnim, {
+          toValue: offset,
+          duration: scrollAnimationDuration,
+          useNativeDriver: false,
+        }).start();
+      } else {
+        flatListRef.current.scrollToOffset({ offset, animated });
+      }
+    },
+    [scrollAnim, scrollAnimationDuration, width]
+  );
+
+  const setCurrentPage = React.useCallback(
+    (index: number) => {
+      setPage(index);
+      currentPageRef.current = index;
+      setProgress(Math.round(((index + 1) / numberOfScreens) * 100));
+      setIsDone(index === numberOfScreens - 1);
+      onPageChange?.(index);
+      // No-op when no screen reader is active; announces the page otherwise.
+      AccessibilityInfo.announceForAccessibility(
+        `Page ${index + 1} of ${numberOfScreens}`
+      );
+    },
+    [numberOfScreens, onPageChange]
+  );
+
+  const nextPage = React.useCallback(
+    (animated: boolean = true) => {
+      const current = currentPageRef.current;
+      if (current < numberOfScreens - 1) {
+        animateToOffset(width * (current + 1), animated);
+        setCurrentPage(current + 1);
+      } else if (loop) {
+        animateToOffset(0, animated);
+        setCurrentPage(0);
+      }
+    },
+    [numberOfScreens, loop, width, animateToOffset, setCurrentPage]
+  );
+
+  const previousPage = React.useCallback(
+    (animated: boolean = true) => {
+      const current = currentPageRef.current;
+      if (current > 0) {
+        animateToOffset(width * (current - 1), animated);
+        setCurrentPage(current - 1);
+      } else if (loop) {
+        animateToOffset(width * (numberOfScreens - 1), animated);
+        setCurrentPage(numberOfScreens - 1);
+      }
+    },
+    [numberOfScreens, loop, width, animateToOffset, setCurrentPage]
+  );
+
+  const scrollTo = React.useCallback(
+    (index: number, animated: boolean = true) => {
+      if (index >= 0 && index < numberOfScreens) {
+        animateToOffset(index * width, animated);
+        setCurrentPage(index);
+      }
+    },
+    [numberOfScreens, width, animateToOffset, setCurrentPage]
+  );
+
+  const pauseAutoPlay = React.useCallback(() => setIsAutoPlaying(false), []);
+  const resumeAutoPlay = React.useCallback(
+    () => setIsAutoPlaying(autoPlay),
+    [autoPlay]
+  );
+
+  // Autoplay timer. Recreated whenever the page changes so it always advances
+  // from the current position; pauses when the user interacts with the slider.
+  React.useEffect(() => {
+    if (!isAutoPlaying || numberOfScreens <= 1) return;
+    if (!loop && currentPage >= numberOfScreens - 1) return;
+    const timer = setTimeout(() => nextPage(true), autoPlayInterval);
+    return () => clearTimeout(timer);
+  }, [
+    isAutoPlaying,
+    currentPage,
+    numberOfScreens,
+    autoPlayInterval,
+    loop,
+    nextPage,
+  ]);
 
   const contextValue: OnboardingContextType = {
     scrollEnabled: enableScroll,
     enableScroll: setEnableScroll,
+    width,
     currentPage,
     numberOfScreens,
     nextPage,
+    previousPage,
     setCurrentPage,
     flatListRef,
+    setFlatListRef,
     scrollTo,
     progress,
     isDone,
+    pauseAutoPlay,
+    resumeAutoPlay,
   };
 
   return (

package/src/hooks/useOnboarding.tsx

@@ -4,9 +4,7 @@ import { OnboardingContext } from '../context/OnboardingContext';
 export const useOnboarding = () => {
   const context = React.useContext(OnboardingContext);
   if (!context) {
-    throw new Error(
-      'useOnboardingContext must be used within an OnboardingProvider'
-    );
+    throw new Error('useOnboarding must be used within an OnboardingProvider');
   }
   return context;
 };

package/src/index.tsx

@@ -1,15 +1,30 @@
 import React from 'react';
-import { Swiper } from './components/Swiper';
+import { Swiper } from './components';
 import { OnboardingProvider } from './context/OnboardingContext';
 import type { OnboardingProps } from './types';
 
 export { useOnboarding } from './hooks/useOnboarding';
+export type { Page } from './components/Page';
+export type { OnboardingProps } from './types';
+export {
+  createOnboardingStorage,
+  hasCompletedOnboarding,
+  markOnboardingComplete,
+  resetOnboarding,
+} from './utils/persistence';
+export type { OnboardingStorageAdapter } from './utils/persistence';
 
 export function Onboarding(props: OnboardingProps) {
   const numberOfScreens = React.Children.count(props.children);
   return (
     <OnboardingProvider
+      width={props.width}
       scrollEnabled={props.scrollEnabled}
+      onPageChange={props.onPageChange}
+      scrollAnimationDuration={props.scrollAnimationDuration}
+      autoPlay={props.autoPlay}
+      autoPlayInterval={props.autoPlayInterval}
+      loop={props.loop}
       numberOfScreens={numberOfScreens || props.pages?.length || 0}
     >
       <Swiper {...props}>{props.children}</Swiper>

package/src/types/index.ts

@@ -6,13 +6,19 @@ export type OnboardingProps = {
   nextLabel?: string | React.ReactNode;
   skipLabel?: string | React.ReactNode;
   doneLabel?: string | React.ReactNode;
+  previousLabel?: string | React.ReactNode;
   showSkip?: boolean;
   showNext?: boolean;
   showDone?: boolean;
+  showPrevious?: boolean;
   onDone?: () => void;
   onSkip?: () => void;
+  onPageChange?: (index: number) => void;
   showPagination?: boolean;
   scrollEnabled?: boolean;
+  autoPlay?: boolean;
+  autoPlayInterval?: number;
+  loop?: boolean;
   customFooter?: (props: { nextPage: () => void }) => React.ReactNode;
   paginationContainerStyle?: StyleProp<ViewStyle>;
   buttonRightContainerStyle?: StyleProp<ViewStyle>;
@@ -20,9 +26,11 @@ export type OnboardingProps = {
   dotsContainerStyle?: StyleProp<ViewStyle>;
   doneLabelStyle?: StyleProp<TextStyle>;
   skipLabelStyle?: StyleProp<TextStyle>;
+  previousLabelStyle?: StyleProp<TextStyle>;
   skipButtonContainerStyle?: StyleProp<ViewStyle>;
   nextButtonContainerStyle?: StyleProp<ViewStyle>;
   doneButtonContainerStyle?: StyleProp<ViewStyle>;
+  previousButtonContainerStyle?: StyleProp<ViewStyle>;
   skipButtonPosition?: 'top-left' | 'top-right';
   nextLabelStyle?: StyleProp<TextStyle>;
   containerStyle?: StyleProp<ViewStyle>;
@@ -31,8 +39,13 @@ export type OnboardingProps = {
   titleStyle?: StyleProp<TextStyle>;
   subtitleStyle?: StyleProp<TextStyle>;
   paginationPosition?: 'top' | 'bottom';
+  paginationStyle?: 'dots' | 'progress';
+  progressBarStyle?: StyleProp<ViewStyle>;
+  progressBarFillStyle?: StyleProp<ViewStyle>;
+  dotsAreTappable?: boolean;
   scrollAnimationDuration?: number;
   useNativeDriver?: boolean;
+  rtl?: boolean;
   width?: number;
   color?: string;
   pages?: Page[];

package/src/utils/persistence.ts

@@ -0,0 +1,58 @@
+/**
+ * Minimal AsyncStorage-compatible interface. Any storage that implements these
+ * three methods works (e.g. @react-native-async-storage/async-storage,
+ * expo-secure-store wrappers, or an in-memory mock in tests). Keeping the
+ * dependency injected means this library does not have to ship a storage peer
+ * dependency of its own.
+ */
+export type OnboardingStorageAdapter = {
+  getItem: (key: string) => Promise<string | null>;
+  setItem: (key: string, value: string) => Promise<void>;
+  removeItem: (key: string) => Promise<void>;
+};
+
+const DEFAULT_KEY = '@react-native-app-onboard/completed';
+const COMPLETED_VALUE = 'true';
+
+/**
+ * Returns whether the user has previously completed onboarding stored under
+ * `key`. Defaults to a namespaced key so callers usually only pass the storage.
+ */
+export async function hasCompletedOnboarding(
+  storage: OnboardingStorageAdapter,
+  key: string = DEFAULT_KEY
+): Promise<boolean> {
+  const value = await storage.getItem(key);
+  return value === COMPLETED_VALUE;
+}
+
+/** Marks onboarding as completed so it can be skipped on subsequent launches. */
+export async function markOnboardingComplete(
+  storage: OnboardingStorageAdapter,
+  key: string = DEFAULT_KEY
+): Promise<void> {
+  await storage.setItem(key, COMPLETED_VALUE);
+}
+
+/** Clears the stored completion flag (useful for "replay onboarding" actions). */
+export async function resetOnboarding(
+  storage: OnboardingStorageAdapter,
+  key: string = DEFAULT_KEY
+): Promise<void> {
+  await storage.removeItem(key);
+}
+
+/**
+ * Convenience factory that binds a storage adapter (and optional key) once and
+ * returns ready-to-call helpers, so app code doesn't repeat the storage arg.
+ */
+export function createOnboardingStorage(
+  storage: OnboardingStorageAdapter,
+  key: string = DEFAULT_KEY
+) {
+  return {
+    hasCompleted: () => hasCompletedOnboarding(storage, key),
+    markComplete: () => markOnboardingComplete(storage, key),
+    reset: () => resetOnboarding(storage, key),
+  };
+}