@telus-uds/components-base 1.82.0 → 1.84.0

package/src/Carousel/Carousel.jsx

@@ -1,4 +1,4 @@
-import React from 'react'
+import React, { useState, useRef, useEffect, useCallback, useMemo, forwardRef } from 'react'
 import { View, Animated, PanResponder, StyleSheet, Platform, Dimensions } from 'react-native'
 import PropTypes from 'prop-types'
 import { useThemeTokens } from '../ThemeProvider'
@@ -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
   }
 })
 
@@ -49,6 +61,26 @@ const selectSwipeAreaStyles = (count, width) => ({
   flexDirection: 'row'
 })
 
+const getDynamicPositionProperty = (areStylesAppliedOnPreviousButton) =>
+  areStylesAppliedOnPreviousButton ? 'left' : 'right'
+
+const selectControlButtonPositionStyles = ({
+  positionVariant,
+  buttonWidth,
+  positionProperty = getDynamicPositionProperty(),
+  spaceBetweenSlideAndButton
+}) => {
+  const styles = {}
+  if (positionVariant === 'edge') {
+    styles[positionProperty] = -1 * (buttonWidth / 2)
+  } else if (positionVariant === 'inside') {
+    styles[positionProperty] = 0
+  } else if (positionVariant === 'outside') {
+    styles[positionProperty] = -1 * (spaceBetweenSlideAndButton + buttonWidth)
+  }
+  return styles
+}
+
 const selectPreviousNextNavigationButtonStyles = (
   previousNextNavigationButtonWidth,
   previousNextNavigationPosition,
@@ -61,7 +93,6 @@ const selectPreviousNextNavigationButtonStyles = (
     zIndex: 1,
     position: 'absolute'
   }
-  const dynamicPositionProperty = areStylesAppliedOnPreviousButton ? 'left' : 'right'
   if (isFirstSlide) {
     styles.visibility = areStylesAppliedOnPreviousButton ? 'hidden' : 'visible'
   } else if (isLastSlide) {
@@ -70,15 +101,15 @@ 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
+    })
   }
-  return styles
 }
 
 const selectIconStyles = ({ iconBackgroundColor }) => ({ backgroundColor: iconBackgroundColor })
@@ -139,7 +170,7 @@ const [selectProps, selectedSystemPropTypes] = selectSystemProps([a11yProps, vie
   - `spaceBetweenSlideAndPreviousNextNavigation` - Horizontal space between slide and previous/next navigational buttons
   - `spaceBetweenSlideAndPanelNavigation` - Vertical space between slide area and panel navigation area
  */
-const Carousel = React.forwardRef(
+const Carousel = forwardRef(
   (
     {
       tokens,
@@ -170,10 +201,21 @@ const Carousel = React.forwardRef(
       accessibilityLabel,
       accessibilityLiveRegion = 'polite',
       copy,
+      slideDuration = 0,
+      transitionDuration = 0,
+      autoPlay = 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
@@ -181,22 +223,52 @@ const Carousel = React.forwardRef(
     const {
       previousIcon,
       nextIcon,
+      playIcon,
+      pauseIcon,
       showPreviousNextNavigation,
       showPanelNavigation,
       showPanelTabs,
       spaceBetweenSlideAndPreviousNextNavigation
     } = themeTokens
-    const [activeIndex, setActiveIndex] = React.useState(0)
+    const [activeIndex, setActiveIndex] = useState(0)
+    const activeIndexRef = useRef(activeIndex)
+    const { reduceMotionEnabled } = useA11yInfo()
+    const reduceMotionRef = useRef(reduceMotionEnabled)
+    const [containerLayout, setContainerLayout] = React.useState({
+      x: 0,
+      y: 0,
+      width: 0
+    })
+    const containerLayoutRef = useRef(containerLayout)
+
+    const [previousNextNavigationButtonWidth, setPreviousNextNavigationButtonWidth] = useState(0)
+    const firstFocusRef = useRef(null)
+    const pan = useRef(new Animated.ValueXY()).current
+    const animatedX = useRef(0)
+    const animatedY = useRef(0)
+    const [isAnimating, setIsAnimating] = 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] = useState(autoPlayFeatureEnabled)
+    const [isCarouselPlaying, setisCarouselPlaying] = useState(autoPlayFeatureEnabled)
+    const isSwiping = useRef(false)
+    const autoPlayRef = useRef(null)
 
-    const [isAnimating, setIsAnimating] = React.useState(false)
-    const handleAnimationStart = React.useCallback(
+    const isFirstSlide = !activeIndex
+    const isLastSlide = activeIndex + 1 >= childrenArray.length
+
+    const handleAnimationStart = useCallback(
       (...args) => {
         if (typeof onAnimationStart === 'function') onAnimationStart(...args)
         setIsAnimating(true)
       },
       [onAnimationStart]
     )
-    const handleAnimationEnd = React.useCallback(
+    const handleAnimationEnd = useCallback(
       (...args) => {
         if (typeof onAnimationEnd === 'function') onAnimationEnd(...args)
         setIsAnimating(false)
@@ -204,68 +276,30 @@ const Carousel = React.forwardRef(
       [onAnimationEnd]
     )
 
-    const getCopy = useCopy({ dictionary, copy })
-
-    let childrenArray = unpackFragment(children)
-    // if `Carousel` only has one `Carousel.Item`, convert this to a single-item array
-    if (!Array.isArray(childrenArray)) {
-      childrenArray = [childrenArray]
-    }
-    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
+    const updateOffset = useCallback(() => {
+      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(
+    const animate = 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 {
           Animated.spring(pan, {
             ...springConfig,
@@ -274,60 +308,178 @@ const Carousel = React.forwardRef(
           }).start(handleAnimationEndToIndex)
         }
       },
-      [pan, springConfig, reduceMotionEnabled, handleAnimationEnd]
+      [pan, springConfig, handleAnimationEnd, transitionDuration, isAutoPlayEnabled]
     )
 
-    const updateIndex = React.useCallback(
-      (delta = 1) => {
+    const stopAutoplay = useCallback(() => {
+      if (autoPlayRef?.current) {
+        clearTimeout(autoPlayRef?.current)
+      }
+    }, [])
+
+    const updateIndex = useCallback(
+      (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)
+              if (refocus) firstFocusRef.current?.focus()
+            }, Math.abs(slideDuration) * 1000)
+          }
+        }
         if (onIndexChanged) onIndexChanged(calcDelta, index)
         return calcDelta
       },
-      [containerLayout.width, activeIndex, animate, children.length, onIndexChanged]
+      [
+        handleAnimationStart,
+        refocus,
+        slideDuration,
+        updateOffset,
+        animate,
+        childrenArray.length,
+        onIndexChanged,
+        isCarouselPlaying,
+        stopAutoplay,
+        isAutoPlayEnabled
+      ]
     )
 
-    const fixOffsetAndGo = React.useCallback(
-      (delta) => {
+    const startAutoplay = useCallback(() => {
+      stopAutoplay()
+      if (isAutoPlayEnabled) {
+        autoPlayRef.current = setTimeout(() => {
+          updateOffset()
+          handleAnimationStart(activeIndexRef.current)
+          updateIndex(slideDuration < 0 ? -1 : 1, TRANSITION_MODES.AUTOMATIC)
+          if (refocus && Platform.OS === 'web') firstFocusRef.current?.focus()
+        }, Math.abs(slideDuration) * 1000)
+      }
+    }, [
+      handleAnimationStart,
+      refocus,
+      updateIndex,
+      updateOffset,
+      slideDuration,
+      stopAutoplay,
+      isAutoPlayEnabled
+    ])
+
+    const fixOffsetAndGo = useCallback(
+      (delta, transitionMode) => {
         updateOffset()
-        handleAnimationStart(activeIndex)
-        updateIndex(delta)
-        if (refocus) firstFocusRef.current?.focus()
+        handleAnimationStart(activeIndexRef.current)
+        updateIndex(delta, transitionMode)
+        if (refocus && Platform.OS === 'web') firstFocusRef.current?.focus()
       },
-      [updateIndex, updateOffset, activeIndex, handleAnimationStart, refocus]
+      [updateIndex, updateOffset, handleAnimationStart, refocus]
     )
 
-    const goToNeighboring = React.useCallback(
-      (toPrev = false) => {
-        fixOffsetAndGo(toPrev ? -1 : 1)
+    const goToNeighboring = useCallback(
+      (toPrev = false, transitionMode = TRANSITION_MODES.MANUAL) => {
+        fixOffsetAndGo(toPrev ? -1 : 1, transitionMode)
       },
       [fixOffsetAndGo]
     )
 
-    const isSwipeAllowed = React.useCallback(() => {
+    useEffect(() => {
+      activeIndexRef.current = activeIndex
+    }, [activeIndex])
+
+    useEffect(() => {
+      reduceMotionRef.current = reduceMotionEnabled
+    }, [reduceMotionEnabled])
+
+    useEffect(() => {
+      containerLayoutRef.current = containerLayout
+    }, [containerLayout])
+
+    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])
+
+    useEffect(() => {
+      const subscription = Dimensions.addEventListener('change', () => {
+        updateOffset()
+      })
+
+      return () => {
+        if (subscription.remove) {
+          subscription.remove()
+        } else {
+          Dimensions.removeEventListener('change', updateOffset)
+        }
+      }
+    }, [updateOffset])
+
+    useEffect(() => {
+      setIsAutoPlayEnabled(
+        autoPlay && slideDuration > 0 && transitionDuration > 0 && childrenArray.length > 1
+      )
+    }, [autoPlay, slideDuration, transitionDuration, childrenArray.length])
+
+    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 = useCallback(() => {
       if (childrenArray.length === 1) {
         return false
       }
@@ -337,7 +489,7 @@ const Carousel = React.forwardRef(
       return true
     }, [viewport, childrenArray.length])
 
-    const panResponder = React.useMemo(
+    const panResponder = useMemo(
       () =>
         PanResponder.create({
           onPanResponderTerminationRequest: () => false,
@@ -347,76 +499,70 @@ const Carousel = React.forwardRef(
               return false
             }
 
-            handleAnimationStart(activeIndex)
+            handleAnimationStart(activeIndexRef.current)
 
-            return Math.abs(gestureState.dx) > minDistanceToCapture
+            const allow = Math.abs(gestureState.dx) > minDistanceToCapture
+
+            if (allow) {
+              isSwiping.current = true
+              stopAutoplay()
+            }
+
+            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])
-
-    React.useEffect(() => {
-      const subscription = Dimensions.addEventListener('change', () => {
-        updateOffset()
-      })
-
-      return () => subscription?.remove()
-    })
-
-    const goToNext = React.useCallback(() => {
+    const goToNext = useCallback(() => {
       goToNeighboring()
     }, [goToNeighboring])
 
-    const goToPrev = React.useCallback(() => {
+    const goToPrev = useCallback(() => {
       goToNeighboring(true)
     }, [goToNeighboring])
 
-    const goTo = React.useCallback(
+    const goTo = 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.
@@ -428,7 +574,7 @@ const Carousel = React.forwardRef(
       inverse: variant?.inverse
     }
 
-    const getCopyWithPlaceholders = React.useCallback(
+    const getCopyWithPlaceholders = useCallback(
       (copyKey) => {
         const copyText = getCopy(copyKey)
           .replace(/%\{title\}/g, title)
@@ -459,6 +605,18 @@ const Carousel = React.forwardRef(
         }
       }
     }
+
+    const systemProps = selectProps({
+      ...rest,
+      accessibilityRole,
+      accessibilityLabel,
+      accessibilityValue: {
+        min: 1,
+        max: childrenArray.length,
+        now: activeIndex + 1
+      }
+    })
+
     // 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 =
@@ -471,6 +629,15 @@ const Carousel = React.forwardRef(
       ...(isFirstFocusContainer && { ref: containerRef, focusable: true })
     }
 
+    const onAnimationControlButtonPress = useCallback(() => {
+      if (isCarouselPlaying) {
+        stopAutoplay()
+      } else {
+        startAutoplay()
+      }
+      setisCarouselPlaying((prevState) => !prevState)
+    }, [isCarouselPlaying, stopAutoplay, startAutoplay])
+
     return (
       <CarouselProvider
         activeIndex={activeIndex}
@@ -490,6 +657,25 @@ const Carousel = React.forwardRef(
           {...systemProps}
           {...containerProps}
         >
+          {isAutoPlayEnabled ? (
+            <View
+              style={[
+                staticStyles.animationControlButton,
+                selectControlButtonPositionStyles({
+                  positionVariant: previousNextNavigationPosition,
+                  buttonWidth: previousNextNavigationButtonWidth,
+                  positionProperty: getDynamicPositionProperty(),
+                  spaceBetweenSlideAndButton: spaceBetweenSlideAndPreviousNextNavigation
+                })
+              ]}
+            >
+              <IconButton
+                icon={isCarouselPlaying ? pauseIcon : playIcon}
+                variant={previousNextIconButtonVariants}
+                onPress={onAnimationControlButtonPress}
+              />
+            </View>
+          ) : null}
           {showPreviousNextNavigation && childrenArray.length > 1 ? (
             <View
               style={selectPreviousNextNavigationButtonStyles(
@@ -531,7 +717,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),
                 {
                   transform: [{ translateX: pan.x }, { translateY: pan.y }]
                 }
@@ -641,7 +827,7 @@ Carousel.propTypes = {
    * This function is also provided with a parameter indicating changed index (either 1, or -1)
    * Use it as follows:
    * ```js
-   *    const onIndexChangedCallback = React.useCallback((changedIndex, currentActiveIndex) => {
+   *    const onIndexChangedCallback = useCallback((changedIndex, currentActiveIndex) => {
    *      console.log(changedIndex)
    *    }, [])  // pass local dependencies as per your component
    *    <Carousel
@@ -692,7 +878,7 @@ Carousel.propTypes = {
    * This function is also provided with a parameter indicating the current slide index before animation starts
    * Use it as follows:
    * ```js
-   *    const onAnimationStartCallback = React.useCallback((currentIndex) => {
+   *    const onAnimationStartCallback = useCallback((currentIndex) => {
    *      console.log(currentIndex)
    *    }, [])  // pass local dependencies as per your component
    *    <Carousel
@@ -709,7 +895,7 @@ Carousel.propTypes = {
    * This function is also provided with a parameter indicating the updated slide index after animation ends
    * Use it as follows:
    * ```js
-   *    const onAnimationEndCallback = React.useCallback((changedIndex) => {
+   *    const onAnimationEndCallback = useCallback((changedIndex) => {
    *      console.log(changedIndex)
    *    }, [])  // pass local dependencies as per your component
    *    <Carousel
@@ -743,7 +929,26 @@ 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
 }
 
 Carousel.Item = CarouselItem