react-native-app-onboard 0.1.9 → 0.2.1

package/src/components/Pagination.tsx

@@ -1,5 +1,6 @@
 import {
   View,
+  Pressable,
   Animated,
   StyleSheet,
   type StyleProp,
@@ -7,6 +8,7 @@ import {
   type TextStyle,
 } from 'react-native';
 import React from 'react';
+import { setAlpha } from '../utils/color';
 import { useOnboarding } from '../hooks/useOnboarding';
 import { Button } from './button';
 
@@ -19,9 +21,11 @@ type FooterProps = {
   showDone?: boolean;
   showSkip?: boolean;
   showNext?: boolean;
+  showPrevious?: boolean;
   nextLabel?: string | React.ReactNode;
   skipLabel?: string | React.ReactNode;
   doneLabel?: string | React.ReactNode;
+  previousLabel?: string | React.ReactNode;
   paginationContainerStyle?: StyleProp<ViewStyle>;
   buttonRightContainerStyle?: StyleProp<ViewStyle>;
   buttonLeftContainerStyle?: StyleProp<ViewStyle>;
@@ -29,20 +33,30 @@ type FooterProps = {
   doneLabelStyle?: StyleProp<TextStyle>;
   hasSkipPosition?: boolean;
   skipLabelStyle?: StyleProp<TextStyle>;
+  previousLabelStyle?: StyleProp<TextStyle>;
   skipButtonContainerStyle?: StyleProp<ViewStyle>;
   nextButtonContainerStyle?: StyleProp<ViewStyle>;
   doneButtonContainerStyle?: StyleProp<ViewStyle>;
+  previousButtonContainerStyle?: StyleProp<ViewStyle>;
   nextLabelStyle?: StyleProp<TextStyle>;
   paginationPosition?: 'top' | 'bottom';
+  paginationStyle?: 'dots' | 'progress';
+  progressBarStyle?: StyleProp<ViewStyle>;
+  progressBarFillStyle?: StyleProp<ViewStyle>;
+  dotsAreTappable?: boolean;
+  mirror?: boolean;
   onDone?: () => void;
   onSkip?: () => void;
   onNext?: () => void;
 };
 
 export function Pagination(props: FooterProps) {
-  const { isDone } = useOnboarding();
+  const { isDone, currentPage, progress, scrollTo, previousPage } =
+    useOnboarding();
   const dots = Array.from({ length: props.numberOfScreens }, (_, i) => i);
   const width = props.width;
+  const showPrevious = props.showPrevious && currentPage > 0;
+
   return (
     <View
       style={[
@@ -60,7 +74,15 @@ export function Pagination(props: FooterProps) {
           props.buttonLeftContainerStyle,
         ]}
       >
-        {props.showSkip && !props.hasSkipPosition && (
+        {showPrevious && (
+          <Button
+            onPress={() => previousPage()}
+            buttonTextStyle={props.previousLabelStyle}
+            buttonStyle={props.previousButtonContainerStyle}
+            label={props.previousLabel || 'Back'}
+          />
+        )}
+        {!showPrevious && props.showSkip && !props.hasSkipPosition && (
           <Button
             onPress={props.onSkip}
             buttonTextStyle={props.skipLabelStyle}
@@ -69,29 +91,82 @@ export function Pagination(props: FooterProps) {
           />
         )}
       </View>
-      <View style={styles.dotsContainer}>
-        {dots.map((_, i) => {
-          const inputRange = [(i - 1) * width, i * width, (i + 1) * width];
-          const dotOpacity = props.animatedValue.interpolate({
-            inputRange,
-            outputRange: [0.3, 1, 0.3],
-            extrapolate: 'clamp',
-          });
-          return (
-            <Animated.View
-              key={i}
-              style={[
-                styles.dot,
-                {
-                  backgroundColor: props.color,
-                  opacity: dotOpacity,
-                },
-                props.dotsContainerStyle,
-              ]}
-            />
-          );
-        })}
-      </View>
+
+      {props.paginationStyle === 'progress' ? (
+        <View
+          accessible
+          accessibilityRole="progressbar"
+          accessibilityValue={{ min: 0, max: 100, now: progress }}
+          style={[
+            styles.progressTrack,
+            // Derive a faint track from the (background-aware) fill color so it
+            // stays visible on both light and dark pages.
+            { backgroundColor: setAlpha(props.color, 0.25) },
+            // Mirror the fill direction so it grows from the trailing edge.
+            props.mirror && styles.mirror,
+            props.progressBarStyle,
+          ]}
+        >
+          <View
+            style={[
+              styles.progressFill,
+              { backgroundColor: props.color, width: `${progress}%` },
+              props.progressBarFillStyle,
+            ]}
+          />
+        </View>
+      ) : (
+        <View
+          style={[
+            styles.dotsContainer,
+            props.mirror && styles.mirror,
+            props.dotsContainerStyle,
+          ]}
+        >
+          {dots.map((_, i) => {
+            const inputRange = [(i - 1) * width, i * width, (i + 1) * width];
+            const dotOpacity = props.animatedValue.interpolate({
+              inputRange,
+              outputRange: [0.3, 1, 0.3],
+              extrapolate: 'clamp',
+            });
+            const dotProps = {
+              accessibilityRole: props.dotsAreTappable
+                ? ('button' as const)
+                : ('image' as const),
+              accessibilityLabel: `Page ${i + 1} of ${props.numberOfScreens}`,
+              accessibilityState: { selected: i === currentPage },
+            };
+            const dot = (
+              <Animated.View
+                key={i}
+                style={[
+                  styles.dot,
+                  {
+                    backgroundColor: props.color,
+                    opacity: dotOpacity,
+                  },
+                ]}
+              />
+            );
+            return props.dotsAreTappable ? (
+              <Pressable
+                key={i}
+                onPress={() => scrollTo(i)}
+                hitSlop={8}
+                {...dotProps}
+              >
+                {dot}
+              </Pressable>
+            ) : (
+              <View key={i} {...dotProps}>
+                {dot}
+              </View>
+            );
+          })}
+        </View>
+      )}
+
       <View
         style={[
           styles.buttons,
@@ -138,21 +213,34 @@ const styles = StyleSheet.create({
   },
   dotsContainer: {
     flexDirection: 'row',
-    flex: 1,
+    flex: 2,
     justifyContent: 'center',
+    alignItems: 'center',
+  },
+  progressTrack: {
+    flex: 2,
+    height: 6,
+    borderRadius: 3,
+    marginHorizontal: 16,
+    overflow: 'hidden',
+  },
+  progressFill: {
+    height: '100%',
+    borderRadius: 3,
   },
   text: {
     fontSize: 16,
   },
   buttons: {
-    minWidth: 200,
+    flex: 1,
   },
   rightButton: {
     alignItems: 'flex-end',
-    paddingRight: 30,
   },
   leftButton: {
     alignItems: 'flex-start',
-    paddingLeft: 30,
+  },
+  mirror: {
+    transform: [{ scaleX: -1 }],
   },
 });

package/src/components/Swiper.tsx

@@ -1,109 +1,87 @@
 import React from 'react';
 import { OnboardingPages } from './OnboardingPages';
 import { CustomPages } from './CustomPages';
-import { Animated } from 'react-native';
+import {
+  Animated,
+  I18nManager,
+  type NativeSyntheticEvent,
+  type NativeScrollEvent,
+} from 'react-native';
 import { useOnboarding } from '../hooks/useOnboarding';
 import type { OnboardingProps } from '../types';
 
 export const Swiper: React.FC<OnboardingProps> = (props) => {
-  const scrollX = React.useRef(new Animated.Value(0)).current;
+  // `scrollX` is always JS-driven because the background-color interpolation
+  // cannot run on the native thread. When `useNativeDriver` is enabled we also
+  // keep `nativeScrollX`, driven natively, for transform/opacity animations
+  // (the pagination dots), and mirror its offset onto `scrollX` via a JS
+  // listener so the color interpolation keeps working.
+  const scrollX = React.useMemo(() => new Animated.Value(0), []);
+  const nativeScrollX = React.useMemo(() => new Animated.Value(0), []);
+  const nativeDriverEnabled = props.useNativeDriver ?? false;
+  const dotsAnimatedValue = nativeDriverEnabled ? nativeScrollX : scrollX;
+
+  // Direction handling: default to the device direction. We only mirror
+  // manually (via scaleX) when the requested direction differs from the
+  // device's — when they match, React Native already lays the row out
+  // correctly and an extra flip would double-invert it.
+  const rtl = props.rtl ?? I18nManager.isRTL;
+  const mirror = rtl !== I18nManager.isRTL;
+
   const {
-    flatListRef,
+    setFlatListRef,
     setCurrentPage,
     currentPage,
     numberOfScreens,
     nextPage,
     scrollEnabled,
+    pauseAutoPlay,
   } = useOnboarding();
+
+  const onScroll = React.useMemo(
+    () =>
+      nativeDriverEnabled
+        ? Animated.event(
+            [{ nativeEvent: { contentOffset: { x: nativeScrollX } } }],
+            {
+              useNativeDriver: true,
+              listener: (event: NativeSyntheticEvent<NativeScrollEvent>) =>
+                scrollX.setValue(event.nativeEvent.contentOffset.x),
+            }
+          )
+        : Animated.event([{ nativeEvent: { contentOffset: { x: scrollX } } }], {
+            useNativeDriver: false,
+          }),
+    [nativeDriverEnabled, nativeScrollX, scrollX]
+  );
+
+  // Stop autoplay as soon as the user takes manual control of the slider.
+  const onScrollBeginDrag = React.useCallback(
+    () => pauseAutoPlay(),
+    [pauseAutoPlay]
+  );
+
+  const shared = {
+    setFlatListRef,
+    scrollX,
+    dotsAnimatedValue,
+    onScroll,
+    onScrollBeginDrag,
+    setPage: setCurrentPage,
+    currentPage,
+    numberOfScreens,
+    nextPage,
+    scrollEnabled,
+    mirror,
+  };
+
   if (props.children) {
     return (
-      <CustomPages
-        customFooter={props.customFooter}
-        showPagination={props.showPagination}
-        flatListRef={flatListRef}
-        scrollX={scrollX}
-        setPage={setCurrentPage}
-        scrollEnabled={scrollEnabled}
-        currentPage={currentPage}
-        numberOfScreens={numberOfScreens}
-        nextPage={nextPage}
-        showDone={props.showDone}
-        showNext={props.showNext}
-        onDone={props.onDone}
-        skipButtonContainerStyle={props.skipButtonContainerStyle}
-        nextButtonContainerStyle={props.nextButtonContainerStyle}
-        doneButtonContainerStyle={props.doneButtonContainerStyle}
-        skipButtonPosition={props.skipButtonPosition}
-        paginationContainerStyle={props.paginationContainerStyle}
-        paginationPosition={props.paginationPosition}
-        nextLabel={props.nextLabel}
-        skipLabel={props.skipLabel}
-        doneLabel={props.doneLabel}
-        showSkip={props.showSkip}
-        onSkip={props.onSkip}
-        scrollAnimationDuration={props.scrollAnimationDuration}
-        buttonLeftContainerStyle={props.buttonLeftContainerStyle}
-        buttonRightContainerStyle={props.buttonRightContainerStyle}
-        dotsContainerStyle={props.dotsContainerStyle}
-        doneLabelStyle={props.doneLabelStyle}
-        skipLabelStyle={props.skipLabelStyle}
-        nextLabelStyle={props.nextLabelStyle}
-        width={props.width}
-        color={props.color}
-        useNativeDriver={props.useNativeDriver}
-        imageContainerStyle={props.imageContainerStyle}
-        containerStyle={props.containerStyle}
-        titleContainerStyle={props.titleContainerStyle}
-        titleStyle={props.titleStyle}
-        subtitleStyle={props.subtitleStyle}
-        swap={props.swap}
-      >
+      <CustomPages {...props} {...shared}>
         {props.children}
       </CustomPages>
     );
   }
 
-  return (
-    <OnboardingPages
-      showDone={props.showDone}
-      customFooter={props.customFooter}
-      flatListRef={flatListRef}
-      scrollX={scrollX}
-      setPage={setCurrentPage}
-      currentPage={currentPage}
-      paginationPosition={props.paginationPosition}
-      nextPage={nextPage}
-      showSkip={props.showSkip}
-      onDone={props.onDone}
-      pages={props.pages || []}
-      width={props.width}
-      showNext={props.showNext}
-      skipButtonContainerStyle={props.skipButtonContainerStyle}
-      nextButtonContainerStyle={props.nextButtonContainerStyle}
-      doneButtonContainerStyle={props.doneButtonContainerStyle}
-      skipLabelStyle={props.skipLabelStyle}
-      skipButtonPosition={props.skipButtonPosition}
-      showPagination={props.showPagination}
-      color={props.color}
-      onSkip={props.onSkip}
-      swap={props.swap}
-      scrollEnabled={scrollEnabled}
-      nextLabel={props.nextLabel}
-      skipLabel={props.skipLabel}
-      doneLabel={props.doneLabel}
-      scrollAnimationDuration={props.scrollAnimationDuration}
-      buttonLeftContainerStyle={props.buttonLeftContainerStyle}
-      buttonRightContainerStyle={props.buttonRightContainerStyle}
-      dotsContainerStyle={props.dotsContainerStyle}
-      doneLabelStyle={props.doneLabelStyle}
-      nextLabelStyle={props.nextLabelStyle}
-      useNativeDriver={props.useNativeDriver}
-      imageContainerStyle={props.imageContainerStyle}
-      containerStyle={props.containerStyle}
-      titleContainerStyle={props.titleContainerStyle}
-      titleStyle={props.titleStyle}
-      subtitleStyle={props.subtitleStyle}
-      paginationContainerStyle={props.paginationContainerStyle}
-    />
-  );
+  return <OnboardingPages {...props} {...shared} pages={props.pages || []} />;
 };

package/src/components/button.tsx

@@ -18,7 +18,12 @@ type ButtonProps = {
 
 export const Button = (props: ButtonProps) => {
   return typeof props.label === 'string' ? (
-    <TouchableOpacity onPress={props.onPress} style={props.buttonStyle}>
+    <TouchableOpacity
+      onPress={props.onPress}
+      style={props.buttonStyle}
+      accessibilityRole="button"
+      accessibilityLabel={props.label}
+    >
       <Text
         style={[
           styles.text,

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>