@telus-uds/components-base 2.0.0 → 2.0.2

package/src/Carousel/Carousel.jsx

@@ -1,5 +1,5 @@
 import React from 'react'
-import { View, Animated, PanResponder, StyleSheet, Platform } from 'react-native'
+import { View, Animated, PanResponder, StyleSheet, Platform, Dimensions } from 'react-native'
 import PropTypes from 'prop-types'
 import { useThemeTokens } from '../ThemeProvider'
 import { useViewport } from '../ViewportProvider'
@@ -26,6 +26,12 @@ import CarouselTabsPanel from './CarouselTabs/CarouselTabsPanel'
 import CarouselTabsPanelItem from './CarouselTabs/CarouselTabsPanelItem'
 import dictionary from './dictionary'
 
+const TRANSITION_MODES = {
+  MANUAL: 'manual',
+  AUTOMATIC: 'automatic',
+  SWIPE: 'swipe'
+}
+
 const staticStyles = StyleSheet.create({
   root: {
     backgroundColor: 'transparent',
@@ -34,6 +40,12 @@ const staticStyles = StyleSheet.create({
     position: 'relative',
     top: 0,
     left: 0
+  },
+  animationControlButton: {
+    position: 'absolute',
+    zIndex: 1,
+    right: Platform.OS === 'web' ? undefined : 40,
+    top: 40
   }
 })
 
@@ -43,25 +55,50 @@ const selectContainerStyles = (width) => ({
   width
 })
 
-const selectSwipeAreaStyles = (count, width) => ({
+const selectSwipeAreaStyles = (count, width, enablePeeking) => ({
   width: width * count,
-  justifyContent: 'space-between',
+  justifyContent: enablePeeking ? 'flex-start' : 'space-between',
   flexDirection: 'row'
 })
 
+const getDynamicPositionProperty = (areStylesAppliedOnPreviousButton) =>
+  areStylesAppliedOnPreviousButton ? 'left' : 'right'
+
+const selectControlButtonPositionStyles = ({
+  positionVariant,
+  buttonWidth,
+  positionProperty = getDynamicPositionProperty(),
+  spaceBetweenSlideAndButton,
+  enablePeeking
+}) => {
+  const styles = {}
+  if (positionVariant === 'edge') {
+    styles[positionProperty] = -1 * (buttonWidth / 2)
+  } else if (positionVariant === 'inside') {
+    styles[positionProperty] = 0
+  } else if (positionVariant === 'outside') {
+    if (enablePeeking) {
+      styles[positionProperty] = 0
+    } else {
+      styles[positionProperty] = -1 * (spaceBetweenSlideAndButton + buttonWidth)
+    }
+  }
+  return styles
+}
+
 const selectPreviousNextNavigationButtonStyles = (
   previousNextNavigationButtonWidth,
   previousNextNavigationPosition,
   spaceBetweenSlideAndPreviousNextNavigation,
   isFirstSlide,
   isLastSlide,
-  areStylesAppliedOnPreviousButton
+  areStylesAppliedOnPreviousButton,
+  enablePeeking
 ) => {
   const styles = {
     zIndex: 1,
     position: 'absolute'
   }
-  const dynamicPositionProperty = areStylesAppliedOnPreviousButton ? 'left' : 'right'
   if (isFirstSlide) {
     styles.visibility = areStylesAppliedOnPreviousButton ? 'hidden' : 'visible'
   } else if (isLastSlide) {
@@ -70,17 +107,41 @@ const selectPreviousNextNavigationButtonStyles = (
     styles.visibility = 'visible'
   }
 
-  if (previousNextNavigationPosition === 'edge') {
-    styles[dynamicPositionProperty] = -1 * (previousNextNavigationButtonWidth / 2)
-  } else if (previousNextNavigationPosition === 'inside') {
-    styles[dynamicPositionProperty] = 0
-  } else if (previousNextNavigationPosition === 'outside') {
-    styles[dynamicPositionProperty] =
-      -1 * (spaceBetweenSlideAndPreviousNextNavigation + previousNextNavigationButtonWidth)
+  return {
+    ...styles,
+    ...selectControlButtonPositionStyles({
+      positionVariant: previousNextNavigationPosition,
+      buttonWidth: previousNextNavigationButtonWidth,
+      positionProperty: getDynamicPositionProperty(areStylesAppliedOnPreviousButton),
+      spaceBetweenSlideAndButton: spaceBetweenSlideAndPreviousNextNavigation,
+      enablePeeking
+    })
+  }
+}
+
+const getPeekingProps = (viewport) => {
+  if (viewport === 'xs' || viewport === 'sm' || viewport === 'md') {
+    return {
+      peekingFirstSpace: 48,
+      peekingGap: 16,
+      peekingLastSpace: 48,
+      peekingMarginLeft: 24,
+      peekingMarginRight: 24,
+      peekingMiddleSpace: 28
+    }
+  }
+  return {
+    peekingFirstSpace: 48,
+    peekingGap: 16,
+    peekingLastSpace: 48,
+    peekingMarginLeft: 16,
+    peekingMarginRight: 16,
+    peekingMiddleSpace: 24
   }
-  return styles
 }
 
+const selectIconStyles = ({ iconBackgroundColor }) => ({ backgroundColor: iconBackgroundColor })
+
 const [selectProps, selectedSystemPropTypes] = selectSystemProps([a11yProps, viewProps])
 
 /**
@@ -168,10 +229,22 @@ const Carousel = React.forwardRef(
       accessibilityLabel,
       accessibilityLiveRegion = 'polite',
       copy,
+      slideDuration = 0,
+      transitionDuration = 0,
+      autoPlay = false,
+      enablePeeking = false,
       ...rest
     },
     ref
   ) => {
+    let childrenArray = unpackFragment(children)
+    const autoPlayFeatureEnabled =
+      autoPlay && slideDuration > 0 && transitionDuration > 0 && childrenArray.length > 1
+    // if `Carousel` only has one `Carousel.Item`, convert this to a single-item array
+    if (!Array.isArray(childrenArray)) {
+      childrenArray = [childrenArray]
+    }
+    const getCopy = useCopy({ dictionary, copy })
     const viewport = useViewport()
     const themeTokens = useThemeTokens('Carousel', tokens, variant, {
       viewport
@@ -179,14 +252,45 @@ const Carousel = React.forwardRef(
     const {
       previousIcon,
       nextIcon,
+      playIcon,
+      pauseIcon,
       showPreviousNextNavigation,
       showPanelNavigation,
       showPanelTabs,
       spaceBetweenSlideAndPreviousNextNavigation
     } = themeTokens
     const [activeIndex, setActiveIndex] = React.useState(0)
+    const activeIndexRef = React.useRef(activeIndex)
+    const { reduceMotionEnabled } = useA11yInfo()
+    const reduceMotionRef = React.useRef(reduceMotionEnabled)
+    const [containerLayout, setContainerLayout] = React.useState({
+      x: 0,
+      y: 0,
+      width: 0
+    })
+    const containerLayoutRef = React.useRef(containerLayout)
 
+    const [previousNextNavigationButtonWidth, setPreviousNextNavigationButtonWidth] =
+      React.useState(0)
+    const firstFocusRef = React.useRef(null)
+    const pan = React.useRef(new Animated.ValueXY()).current
+    const animatedX = React.useRef(0)
+    const animatedY = React.useRef(0)
     const [isAnimating, setIsAnimating] = React.useState(false)
+    /**
+     * While having the same starting point, `isAutoPlayEnabled` and `isCarouselPlaying` are different states
+     *
+     * `isAutoPlayEnabled` is a state to determine if the autoplay feature is enabled or disabled
+     * `isCarouselPlaying` is a state to determine if the carousel is currently playing or paused
+     */
+    const [isAutoPlayEnabled, setIsAutoPlayEnabled] = React.useState(autoPlayFeatureEnabled)
+    const [isCarouselPlaying, setisCarouselPlaying] = React.useState(autoPlayFeatureEnabled)
+    const isSwiping = React.useRef(false)
+    const autoPlayRef = React.useRef(null)
+
+    const isFirstSlide = !activeIndex
+    const isLastSlide = activeIndex + 1 >= childrenArray.length
+
     const handleAnimationStart = React.useCallback(
       (...args) => {
         if (typeof onAnimationStart === 'function') onAnimationStart(...args)
@@ -202,63 +306,37 @@ const Carousel = React.forwardRef(
       [onAnimationEnd]
     )
 
-    const getCopy = useCopy({ dictionary, copy })
-
-    const childrenArray = unpackFragment(children)
-    const systemProps = selectProps({
-      ...rest,
-      accessibilityRole,
-      accessibilityLabel,
-      accessibilityValue: {
-        min: 1,
-        max: childrenArray.length,
-        now: activeIndex + 1
-      }
-    })
-    const { reduceMotionEnabled } = useA11yInfo()
-    const [containerLayout, setContainerLayout] = React.useState({
-      x: 0,
-      y: 0,
-      width: 0
-    })
-    const [previousNextNavigationButtonWidth, setPreviousNextNavigationButtonWidth] =
-      React.useState(0)
-    const firstFocusRef = React.useRef(null)
-    const pan = React.useRef(new Animated.ValueXY()).current
-    const animatedX = React.useRef(0)
-    const animatedY = React.useRef(0)
-    const isFirstSlide = !activeIndex
-    const isLastSlide = activeIndex + 1 >= children.length
-
-    const onContainerLayout = ({
-      nativeEvent: {
-        layout: { x, y, width }
-      }
-    }) => setContainerLayout((prevState) => ({ ...prevState, x, y, width }))
-
-    const onPreviousNextNavigationButtonLayout = ({
-      nativeEvent: {
-        layout: { width }
-      }
-    }) => setPreviousNextNavigationButtonWidth(width)
-
     const updateOffset = React.useCallback(() => {
-      animatedX.current = containerLayout.width * activeIndex * -1
+      animatedX.current = containerLayoutRef.current.width * activeIndexRef.current * -1
       animatedY.current = 0
       pan.setOffset({
         x: animatedX.current,
         y: animatedY.current
       })
       pan.setValue({ x: 0, y: 0 })
-    }, [activeIndex, containerLayout.width, pan, animatedX])
+    }, [pan, animatedX])
 
     const animate = React.useCallback(
       (toValue, toIndex) => {
         const handleAnimationEndToIndex = (...args) => handleAnimationEnd(toIndex, ...args)
-        if (reduceMotionEnabled) {
+        if (reduceMotionRef.current || isSwiping.current) {
           Animated.timing(pan, { toValue, duration: 1, useNativeDriver: false }).start(
             handleAnimationEndToIndex
           )
+        } else if (isAutoPlayEnabled) {
+          Animated.timing(pan, {
+            ...springConfig,
+            toValue,
+            useNativeDriver: false,
+            duration: transitionDuration * 1000
+          }).start(handleAnimationEndToIndex)
+        } else if (enablePeeking) {
+          Animated.timing(pan, {
+            ...springConfig,
+            toValue,
+            useNativeDriver: false,
+            duration: transitionDuration ? transitionDuration * 1000 : 1000
+          }).start(handleAnimationEndToIndex)
         } else {
           Animated.spring(pan, {
             ...springConfig,
@@ -267,65 +345,192 @@ const Carousel = React.forwardRef(
           }).start(handleAnimationEndToIndex)
         }
       },
-      [pan, springConfig, reduceMotionEnabled, handleAnimationEnd]
+      [pan, springConfig, handleAnimationEnd, transitionDuration, isAutoPlayEnabled, enablePeeking]
     )
 
+    const stopAutoplay = React.useCallback(() => {
+      if (autoPlayRef?.current) {
+        clearTimeout(autoPlayRef?.current)
+      }
+    }, [])
+
+    const triggerRefocus = React.useCallback(() => {
+      if (refocus && Platform.OS === 'web') {
+        firstFocusRef.current?.focus({ preventScroll: true, focusVisible: false })
+      }
+    }, [refocus, firstFocusRef])
+
     const updateIndex = React.useCallback(
-      (delta = 1) => {
+      (delta = 1, transitionMode) => {
         const toValue = { x: 0, y: 0 }
         let skipChanges = !delta
         let calcDelta = delta
-
-        if (activeIndex <= 0 && delta < 0) {
-          skipChanges = true
-          calcDelta = children.length + delta
-        } else if (activeIndex + 1 >= children.length && delta > 0) {
-          skipChanges = true
-          calcDelta = -1 * activeIndex + delta - 1
+        if (activeIndexRef.current <= 0 && delta < 0) {
+          skipChanges = transitionMode !== TRANSITION_MODES.AUTOMATIC
+          calcDelta = childrenArray.length + delta
+        } else if (activeIndexRef.current + 1 >= childrenArray.length && delta > 0) {
+          skipChanges = transitionMode !== TRANSITION_MODES.AUTOMATIC
+          calcDelta = -1 * activeIndexRef.current + delta - 1
         }
 
-        const index = activeIndex + calcDelta
-
+        const index = activeIndexRef.current + calcDelta
         if (skipChanges) {
           animate(toValue, index)
           return calcDelta
         }
 
+        stopAutoplay()
         setActiveIndex(index)
 
-        toValue.x = containerLayout.width * -1 * calcDelta
-
+        toValue.x = containerLayoutRef.current.width * -1 * calcDelta
         animate(toValue, index)
-
+        if (isCarouselPlaying) {
+          stopAutoplay()
+          if (
+            index === 0 &&
+            activeIndexRef.current + 1 === childrenArray.length &&
+            transitionMode === TRANSITION_MODES.AUTOMATIC
+          ) {
+            setisCarouselPlaying(false)
+          } else if (isAutoPlayEnabled) {
+            autoPlayRef.current = setTimeout(() => {
+              updateOffset()
+              handleAnimationStart(activeIndexRef.current)
+              updateIndex(slideDuration < 0 ? -1 : 1, TRANSITION_MODES.AUTOMATIC)
+              triggerRefocus()
+            }, Math.abs(slideDuration) * 1000)
+          }
+        }
         if (onIndexChanged) onIndexChanged(calcDelta, index)
         return calcDelta
       },
-      [containerLayout.width, activeIndex, animate, children.length, onIndexChanged]
+      [
+        handleAnimationStart,
+        triggerRefocus,
+        slideDuration,
+        updateOffset,
+        animate,
+        childrenArray.length,
+        onIndexChanged,
+        isCarouselPlaying,
+        stopAutoplay,
+        isAutoPlayEnabled
+      ]
     )
 
+    const startAutoplay = React.useCallback(() => {
+      stopAutoplay()
+      if (isAutoPlayEnabled) {
+        autoPlayRef.current = setTimeout(() => {
+          updateOffset()
+          handleAnimationStart(activeIndexRef.current)
+          updateIndex(slideDuration < 0 ? -1 : 1, TRANSITION_MODES.AUTOMATIC)
+          triggerRefocus()
+        }, Math.abs(slideDuration) * 1000)
+      }
+    }, [
+      handleAnimationStart,
+      triggerRefocus,
+      updateIndex,
+      updateOffset,
+      slideDuration,
+      stopAutoplay,
+      isAutoPlayEnabled
+    ])
+
     const fixOffsetAndGo = React.useCallback(
-      (delta) => {
+      (delta, transitionMode) => {
         updateOffset()
-        handleAnimationStart(activeIndex)
-        updateIndex(delta)
-        if (refocus) firstFocusRef.current?.focus()
+        handleAnimationStart(activeIndexRef.current)
+        updateIndex(delta, transitionMode)
+        triggerRefocus()
       },
-      [updateIndex, updateOffset, activeIndex, handleAnimationStart, refocus]
+      [updateIndex, updateOffset, handleAnimationStart, triggerRefocus]
     )
 
     const goToNeighboring = React.useCallback(
-      (toPrev = false) => {
-        fixOffsetAndGo(toPrev ? -1 : 1)
+      (toPrev = false, transitionMode = TRANSITION_MODES.MANUAL) => {
+        fixOffsetAndGo(toPrev ? -1 : 1, transitionMode)
       },
       [fixOffsetAndGo]
     )
 
+    React.useEffect(() => {
+      activeIndexRef.current = activeIndex
+    }, [activeIndex])
+
+    React.useEffect(() => {
+      reduceMotionRef.current = reduceMotionEnabled
+    }, [reduceMotionEnabled])
+
+    React.useEffect(() => {
+      containerLayoutRef.current = containerLayout
+    }, [containerLayout])
+
+    React.useEffect(() => {
+      pan.x.addListener(({ value }) => {
+        animatedX.current = value
+      })
+      pan.y.addListener(({ value }) => {
+        animatedY.current = value
+      })
+      if (isCarouselPlaying) {
+        startAutoplay()
+      }
+      return () => {
+        stopAutoplay()
+        pan.x.removeAllListeners()
+        pan.y.removeAllListeners()
+      }
+    }, [pan.x, pan.y, startAutoplay, stopAutoplay, isCarouselPlaying])
+
+    React.useEffect(() => {
+      const subscription = Dimensions.addEventListener('change', () => {
+        updateOffset()
+      })
+
+      return () => {
+        if (subscription.remove) {
+          subscription.remove()
+        } else {
+          Dimensions.removeEventListener('change', updateOffset)
+        }
+      }
+    }, [updateOffset])
+
+    React.useEffect(() => {
+      setIsAutoPlayEnabled(
+        autoPlay && slideDuration > 0 && transitionDuration > 0 && childrenArray.length > 1
+      )
+    }, [autoPlay, slideDuration, transitionDuration, childrenArray.length])
+
+    React.useEffect(() => {
+      return () => {
+        stopAutoplay()
+      }
+    }, [stopAutoplay])
+
+    const onContainerLayout = ({
+      nativeEvent: {
+        layout: { x, y, width }
+      }
+    }) => setContainerLayout((prevState) => ({ ...prevState, x, y, width }))
+
+    const onPreviousNextNavigationButtonLayout = ({
+      nativeEvent: {
+        layout: { width }
+      }
+    }) => setPreviousNextNavigationButtonWidth(width)
+
     const isSwipeAllowed = React.useCallback(() => {
+      if (childrenArray.length === 1) {
+        return false
+      }
       if (Platform.OS === 'web') {
         return !!(viewport === 'xs' || viewport === 'sm')
       }
       return true
-    }, [viewport])
+    }, [viewport, childrenArray.length])
 
     const panResponder = React.useMemo(
       () =>
@@ -337,52 +542,54 @@ const Carousel = React.forwardRef(
               return false
             }
 
-            handleAnimationStart(activeIndex)
+            handleAnimationStart(activeIndexRef.current)
+
+            const allow = Math.abs(gestureState.dx) > minDistanceToCapture
+
+            if (allow) {
+              isSwiping.current = true
+              stopAutoplay()
+            }
 
-            return Math.abs(gestureState.dx) > minDistanceToCapture
+            return allow
+          },
+          onPanResponderGrant: () => {
+            updateOffset()
           },
-          onPanResponderGrant: () => updateOffset(),
           onPanResponderMove: Animated.event([null, { dx: pan.x }], {
             useNativeDriver: false
           }),
           onPanResponderRelease: (_, gesture) => {
+            if (isCarouselPlaying) {
+              startAutoplay()
+            }
             const correction = gesture.moveX - gesture.x0
 
-            if (Math.abs(correction) < containerLayout.width * minDistanceForAction) {
+            if (Math.abs(correction) < containerLayoutRef.current.width * minDistanceForAction) {
               animate({ x: 0, y: 0 }, 0)
             } else {
               const delta = correction > 0 ? -1 : 1
-              updateIndex(delta)
+              updateIndex(delta, TRANSITION_MODES.SWIPE)
             }
+
+            isSwiping.current = false
           }
         }),
       [
-        containerLayout.width,
         updateIndex,
         updateOffset,
         animate,
         isSwipeAllowed,
-        activeIndex,
         minDistanceForAction,
         handleAnimationStart,
         minDistanceToCapture,
-        pan.x
+        pan.x,
+        startAutoplay,
+        stopAutoplay,
+        isCarouselPlaying
       ]
     )
 
-    React.useEffect(() => {
-      pan.x.addListener(({ value }) => {
-        animatedX.current = value
-      })
-      pan.y.addListener(({ value }) => {
-        animatedY.current = value
-      })
-      return () => {
-        pan.x.removeAllListeners()
-        pan.y.removeAllListeners()
-      }
-    }, [pan.x, pan.y])
-
     const goToNext = React.useCallback(() => {
       goToNeighboring()
     }, [goToNeighboring])
@@ -393,18 +600,22 @@ const Carousel = React.forwardRef(
 
     const goTo = React.useCallback(
       (index = 0) => {
-        const delta = index - activeIndex
+        const delta = index - activeIndexRef.current
         if (delta) {
-          fixOffsetAndGo(delta)
+          fixOffsetAndGo(delta, TRANSITION_MODES.MANUAL)
         }
       },
-      [fixOffsetAndGo, activeIndex]
+      [fixOffsetAndGo]
     )
 
     // @TODO: - these are Allium-theme variants and won't have any effect in themes that don't implement them.
     // Normally we avoid setting variants of subcomponents, however this could be re-considered.
     // Related discussion - https://github.com/telus/universal-design-system/issues/1549
-    const previousNextIconButtonVariants = { size: previousNextIconSize, raised: true }
+    const previousNextIconButtonVariants = {
+      size: previousNextIconSize,
+      raised: !variant?.inverse && true,
+      inverse: variant?.inverse
+    }
 
     const getCopyWithPlaceholders = React.useCallback(
       (copyKey) => {
@@ -437,6 +648,13 @@ const Carousel = React.forwardRef(
         }
       }
     }
+
+    const systemProps = selectProps({
+      ...rest,
+      accessibilityRole,
+      accessibilityLabel
+    })
+
     // If container isn't used for focus, give it a label of title if none is passed in,
     // otherwise read the current position on focus
     const containerAccessibilityLabel =
@@ -449,6 +667,15 @@ const Carousel = React.forwardRef(
       ...(isFirstFocusContainer && { ref: containerRef, focusable: true })
     }
 
+    const onAnimationControlButtonPress = React.useCallback(() => {
+      if (isCarouselPlaying) {
+        stopAutoplay()
+      } else {
+        startAutoplay()
+      }
+      setisCarouselPlaying((prevState) => !prevState)
+    }, [isCarouselPlaying, stopAutoplay, startAutoplay])
+
     return (
       <CarouselProvider
         activeIndex={activeIndex}
@@ -462,13 +689,45 @@ const Carousel = React.forwardRef(
         width={containerLayout.width}
       >
         <View
-          style={staticStyles.root}
+          style={[
+            staticStyles.root,
+            {
+              ...Platform.select({
+                web: {
+                  outline: 'none'
+                }
+              })
+            }
+          ]}
           onLayout={onContainerLayout}
           ref={ref}
           {...systemProps}
           {...containerProps}
         >
-          {showPreviousNextNavigation && (
+          {isAutoPlayEnabled ? (
+            <View
+              style={[
+                staticStyles.animationControlButton,
+                selectControlButtonPositionStyles({
+                  positionVariant: previousNextNavigationPosition,
+                  buttonWidth: previousNextNavigationButtonWidth,
+                  positionProperty: getDynamicPositionProperty(),
+                  spaceBetweenSlideAndButton: spaceBetweenSlideAndPreviousNextNavigation,
+                  enablePeeking
+                })
+              ]}
+            >
+              <IconButton
+                icon={isCarouselPlaying ? pauseIcon : playIcon}
+                accessibilityLabel={
+                  isCarouselPlaying ? getCopy('pauseButtonLabel') : getCopy('playButtonLabel')
+                }
+                variant={previousNextIconButtonVariants}
+                onPress={onAnimationControlButtonPress}
+              />
+            </View>
+          ) : null}
+          {showPreviousNextNavigation && childrenArray.length > 1 ? (
             <View
               style={selectPreviousNextNavigationButtonStyles(
                 previousNextNavigationButtonWidth,
@@ -476,7 +735,8 @@ const Carousel = React.forwardRef(
                 spaceBetweenSlideAndPreviousNextNavigation,
                 isFirstSlide,
                 isLastSlide,
-                true
+                true,
+                enablePeeking
               )}
               testID="previous-button-container"
             >
@@ -489,9 +749,10 @@ const Carousel = React.forwardRef(
                   '%{targetStep}',
                   activeIndex
                 )}
+                tokens={selectIconStyles(themeTokens)}
               />
             </View>
-          )}
+          ) : null}
           {Boolean(skipLinkHref) && (
             <SkipLink ref={firstFocusRef} href={skipLinkHref}>
               {getCopyWithPlaceholders('skipLink')}
@@ -508,7 +769,7 @@ const Carousel = React.forwardRef(
           <View style={selectContainerStyles(containerLayout.width)}>
             <Animated.View
               style={StyleSheet.flatten([
-                selectSwipeAreaStyles(children.length, containerLayout.width),
+                selectSwipeAreaStyles(childrenArray.length, containerLayout.width, enablePeeking),
                 {
                   transform: [{ translateX: pan.x }, { translateY: pan.y }]
                 }
@@ -523,13 +784,15 @@ const Carousel = React.forwardRef(
                 const hidden = !isAnimating && index !== activeIndex
                 const clonedElement = React.cloneElement(element, {
                   elementIndex: index,
-                  hidden
+                  hidden: enablePeeking ? false : hidden,
+                  enablePeeking,
+                  peekingProps: getPeekingProps(viewport)
                 })
                 return <React.Fragment key={index.toFixed(2)}>{clonedElement}</React.Fragment>
               })}
             </Animated.View>
           </View>
-          {showPreviousNextNavigation && (
+          {showPreviousNextNavigation && childrenArray.length > 1 ? (
             <View
               style={selectPreviousNextNavigationButtonStyles(
                 previousNextNavigationButtonWidth,
@@ -537,7 +800,8 @@ const Carousel = React.forwardRef(
                 spaceBetweenSlideAndPreviousNextNavigation,
                 isFirstSlide,
                 isLastSlide,
-                false
+                false,
+                enablePeeking
               )}
               testID="next-button-container"
             >
@@ -550,9 +814,10 @@ const Carousel = React.forwardRef(
                   '%{targetStep}',
                   activeIndex + 2
                 )}
+                tokens={selectIconStyles(themeTokens)}
               />
             </View>
-          )}
+          ) : null}
         </View>
         {showPanelNavigation ? activePanelNavigation : null}
       </CarouselProvider>
@@ -626,7 +891,7 @@ Carousel.propTypes = {
    *      <Carousel.Item>First Slide</Carousel.Item>
    *    </Carousel>
    * ```
-   * Caution: Always consider wrapping your callback for `onIndexChanged` in `useCallback` in order to avoid bugs and performance issues
+   * Caution: Always consider wrapping your callback for `onIndexChanged` in `React.useCallback` in order to avoid bugs and performance issues
    */
   onIndexChanged: PropTypes.func,
   /**
@@ -677,7 +942,7 @@ Carousel.propTypes = {
    *      <Carousel.Item>First Slide</Carousel.Item>
    *    </Carousel>
    * ```
-   * Caution: Always consider wrapping your callback for `onAnimationStart` in `useCallback` in order to avoid bugs and performance issues
+   * Caution: Always consider wrapping your callback for `onAnimationStart` in `React.useCallback` in order to avoid bugs and performance issues
    */
   onAnimationStart: PropTypes.func,
   /**
@@ -694,7 +959,7 @@ Carousel.propTypes = {
    *      <Carousel.Item>First Slide</Carousel.Item>
    *    </Carousel>
    * ```
-   * Caution: Always consider wrapping your callback for `onAnimationEnd` in `useCallback` in order to avoid bugs and performance issues
+   * Caution: Always consider wrapping your callback for `onAnimationEnd` in `React.useCallback` in order to avoid bugs and performance issues
    */
   onAnimationEnd: PropTypes.func,
   /**
@@ -719,7 +984,31 @@ Carousel.propTypes = {
    * Note that if the immediate Carousel children do not all render as `'li'` elements,
    * this should be changed (e.g. pass tag="div") because only 'li' is a valid child of 'ul'.
    */
-  tag: PropTypes.oneOf(layoutTags)
+  tag: PropTypes.oneOf(layoutTags),
+  /**
+   * If set to `true`, the Carousel will automatically transition between slides
+   * and show the play/pause button
+   * - Default value is `false`
+   * - `slideDuration` and `transitionDuration` are required to be set for this to work
+   */
+  autoPlay: PropTypes.bool,
+  /**
+   * Duration of the time in seconds spent on each slide
+   * - Default value is `0`
+   * - `autoPlay` and `transitionDuration` are required to be set for this to work
+   */
+  slideDuration: PropTypes.number,
+  /**
+   * Duration of the time in seconds between each slide transition
+   * - Default value is `0`
+   * - `autoPlay` and `slideDuration` are required to be set for this to work
+   */
+  transitionDuration: PropTypes.number,
+  /**
+   * If set to `true`, the Carousel will show the previous and next slides
+   * - Default value is `false`
+   */
+  enablePeeking: PropTypes.bool
 }
 
 Carousel.Item = CarouselItem