@telus-uds/components-base 3.25.0 → 3.27.0

package/lib/cjs/Carousel/Carousel.js

@@ -11,6 +11,7 @@ var _PanResponder = _interopRequireDefault(require("react-native-web/dist/cjs/ex
 var _StyleSheet = _interopRequireDefault(require("react-native-web/dist/cjs/exports/StyleSheet"));
 var _Platform = _interopRequireDefault(require("react-native-web/dist/cjs/exports/Platform"));
 var _Dimensions = _interopRequireDefault(require("react-native-web/dist/cjs/exports/Dimensions"));
+var _Easing = _interopRequireDefault(require("react-native-web/dist/cjs/exports/Easing"));
 var _propTypes = _interopRequireDefault(require("prop-types"));
 var _ThemeProvider = require("../ThemeProvider");
 var _ViewportProvider = require("../ViewportProvider");
@@ -30,11 +31,6 @@ var _Box = _interopRequireDefault(require("../Box"));
 var _Constants = require("./Constants");
 var _jsxRuntime = require("react/jsx-runtime");
 function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
-const TRANSITION_MODES = {
-  MANUAL: 'manual',
-  AUTOMATIC: 'automatic',
-  SWIPE: 'swipe'
-};
 const staticStyles = _StyleSheet.default.create({
   root: {
     backgroundColor: 'transparent',
@@ -83,7 +79,7 @@ const selectHeroContainerStyles = (width, hidden) => ({
   width,
   visibility: hidden ? 'hidden' : 'visible'
 });
-const getDynamicPositionProperty = areStylesAppliedOnPreviousButton => areStylesAppliedOnPreviousButton ? 'left' : 'right';
+const getDynamicPositionProperty = areStylesAppliedOnPreviousButton => areStylesAppliedOnPreviousButton ? _Constants.POSITION_PROPERTIES.LEFT : _Constants.POSITION_PROPERTIES.RIGHT;
 const selectControlButtonPositionStyles = _ref => {
   let {
     positionVariant,
@@ -93,23 +89,36 @@ const selectControlButtonPositionStyles = _ref => {
     enablePeeking,
     enableDisplayMultipleItemsPerSlide,
     isAutoPlayEnabled,
-    viewport
+    viewport,
+    maxWidth,
+    viewportWidth
   } = _ref;
   const styles = {};
-  if (positionVariant === 'edge') {
-    styles[positionProperty] = -1 * (buttonWidth / 2);
-  } else if (positionVariant === 'inside') {
-    styles[positionProperty] = _Constants.DEFAULT_POSITION_OFFSET;
-  } else if (positionVariant === 'outside') {
+  let positionOffset = 0;
+  if (positionVariant === _Constants.POSITION_VARIANTS.EDGE) {
+    positionOffset = -1 * (buttonWidth / 2);
+  } else if (positionVariant === _Constants.POSITION_VARIANTS.INSIDE) {
+    positionOffset = _Constants.DEFAULT_POSITION_OFFSET;
+  } else if (positionVariant === _Constants.POSITION_VARIANTS.OUTSIDE) {
     if (enablePeeking || enableDisplayMultipleItemsPerSlide || isAutoPlayEnabled && viewport === 'xs') {
-      styles[positionProperty] = 0;
+      positionOffset = 0;
     } else {
-      styles[positionProperty] = -1 * (spaceBetweenSlideAndButton + buttonWidth);
+      positionOffset = -1 * (spaceBetweenSlideAndButton + buttonWidth);
+    }
+  }
+  if (enablePeeking) {
+    if (positionProperty === _Constants.POSITION_PROPERTIES.RIGHT) {
+      const rightMargin = (viewportWidth - maxWidth) / 2;
+      positionOffset += rightMargin;
+    } else if (positionProperty === _Constants.POSITION_PROPERTIES.LEFT) {
+      const leftMargin = (viewportWidth - maxWidth) / 2;
+      positionOffset += leftMargin;
     }
   }
+  styles[positionProperty] = positionOffset;
   return styles;
 };
-const selectPreviousNextNavigationButtonStyles = (previousNextNavigationButtonWidth, previousNextNavigationPosition, spaceBetweenSlideAndPreviousNextNavigation, isFirstSlide, isLastSlide, areStylesAppliedOnPreviousButton, enablePeeking, enableDisplayMultipleItemsPerSlide, isAutoPlayEnabled, viewport) => {
+const selectPreviousNextNavigationButtonStyles = (previousNextNavigationButtonWidth, previousNextNavigationPosition, spaceBetweenSlideAndPreviousNextNavigation, isFirstSlide, isLastSlide, areStylesAppliedOnPreviousButton, enablePeeking, enableDisplayMultipleItemsPerSlide, isAutoPlayEnabled, viewport, maxWidth, viewportWidth) => {
   const styles = {
     zIndex: 1,
     position: 'absolute'
@@ -131,7 +140,9 @@ const selectPreviousNextNavigationButtonStyles = (previousNextNavigationButtonWi
       enablePeeking,
       enableDisplayMultipleItemsPerSlide,
       isAutoPlayEnabled,
-      viewport
+      viewport,
+      maxWidth,
+      viewportWidth
     })
   };
 };
@@ -197,7 +208,7 @@ const getMaximumItemsForSlide = (enableDisplayMultipleItemsPerSlide, viewport) =
   }
   return _Constants.ITEMS_PER_VIEWPORT_XS_SM;
 };
-const selectRootContainerStyles = (enableHero, viewport) => {
+const selectRootContainerStyles = (enableHero, viewport, enablePeeking) => {
   if (enableHero && viewport === 'xl' && _Platform.default.OS === 'web') {
     return {
       alignItems: 'center'
@@ -208,15 +219,25 @@ const selectRootContainerStyles = (enableHero, viewport) => {
       paddingHorizontal: 16
     };
   }
+  if (enablePeeking) {
+    return {
+      width: '100%'
+    };
+  }
   return {};
 };
-const selectMainContainerStyles = (enableHero, viewport, maxWidth) => {
-  if (enableHero && viewport === 'xl' && _Platform.default.OS === 'web') {
+const selectMainContainerStyles = (enableHero, viewport, maxWidth, enablePeeking) => {
+  if (enableHero && viewport === 'xl' && _Platform.default.OS === 'web' && !enablePeeking) {
     return {
       width: '100%',
       maxWidth: maxWidth || 1200
     };
   }
+  if (enablePeeking) {
+    return {
+      width: '100%'
+    };
+  }
   if (maxWidth !== null && maxWidth !== undefined) {
     return {
       maxWidth,
@@ -226,14 +247,20 @@ const selectMainContainerStyles = (enableHero, viewport, maxWidth) => {
   }
   return {};
 };
-const selectNavigationStyles = (tabs, enableHero, viewport) => {
+const selectNavigationStyles = (tabs, enableHero, viewport, enablePeeking, maxWidth) => {
   let marginHorizontal = 0;
   if (enableHero && tabs) {
     marginHorizontal = viewport === 'xl' ? _Constants.LARGE_VIEWPORT_MARGIN : _Constants.DEFAULT_VIEWPORT_MARGIN;
   }
-  return {
+  const styles = {
     marginHorizontal
   };
+  if (enablePeeking && maxWidth) {
+    styles.maxWidth = maxWidth;
+    styles.alignSelf = 'center';
+    styles.width = '100%';
+  }
+  return styles;
 };
 
 /**
@@ -242,23 +269,18 @@ const selectNavigationStyles = (tabs, enableHero, viewport) => {
  * @param {number} containerWidth - The width of the carousel container.
  * @param {boolean} enablePeeking - Flag indicating whether peeking is enabled.
  * @param {Object} viewport - The viewport configuration object used to determine peeking properties.
- * @param {React.MutableRefObject<number>} activeIndexRef - A ref object holding the current active index of the carousel.
+ * @param {number} maxWidth - The maximum width constraint for the carousel content.
  * @returns {number} The calculated final width of the carousel container.
  */
-const calculateFinalWidth = (containerWidth, enablePeeking, viewport, activeIndexRef) => {
+const calculateFinalWidth = (containerWidth, enablePeeking, viewport, maxWidth) => {
   let finalWidth = containerWidth;
   if (enablePeeking) {
     const {
       peekingGap,
-      peekingMiddleSpace,
-      peekingMarginLeft
+      peekingMiddleSpace
     } = getPeekingProps(viewport);
-    const slideWide = containerWidth - (peekingMiddleSpace * _Constants.PEEKING_MULTIPLIER + peekingGap * _Constants.PEEKING_MULTIPLIER);
-    if (activeIndexRef.current === 0) {
-      finalWidth = slideWide + peekingMarginLeft - peekingMiddleSpace;
-    } else {
-      finalWidth = slideWide + peekingGap;
-    }
+    const baseWidth = maxWidth || containerWidth;
+    finalWidth = baseWidth - peekingMiddleSpace * _Constants.PEEKING_MULTIPLIER + peekingGap;
   }
   return finalWidth;
 };
@@ -369,6 +391,8 @@ const Carousel = /*#__PURE__*/_react.default.forwardRef((_ref3, ref) => {
     autoPlay = false,
     enablePeeking = false,
     contentMaxWidth,
+    swipeReleaseStyle = _Constants.SWIPE_RELEASE_STYLES.INSTANT,
+    swipeReleaseDuration = _Constants.DEFAULT_SWIPE_RELEASE_DURATION,
     ...rest
   } = _ref3;
   let childrenArray = (0, _utils.unpackFragment)(children);
@@ -379,7 +403,10 @@ const Carousel = /*#__PURE__*/_react.default.forwardRef((_ref3, ref) => {
   } = (0, _ThemeProvider.useTheme)();
   const contentMaxWidthValue = (0, _utils.useResponsiveProp)(contentMaxWidth);
   const responsiveWidth = (0, _utils.useResponsiveProp)(themeOptions?.contentMaxWidth);
-  const maxWidth = (0, _utils.resolveContentMaxWidth)(contentMaxWidthValue, responsiveWidth);
+  let maxWidth = null;
+  if (enablePeeking || contentMaxWidth !== undefined) {
+    maxWidth = contentMaxWidthValue === undefined ? responsiveWidth : (0, _utils.resolveContentMaxWidth)(contentMaxWidthValue, responsiveWidth);
+  }
   const totalItems = getTotalItems(enableDisplayMultipleItemsPerSlide, childrenArray, viewport);
   const autoPlayFeatureEnabled = autoPlay && slideDuration > 0 && transitionDuration > 0 && totalItems > 1;
   // if `Carousel` only has one `Carousel.Item`, convert this to a single-item array
@@ -442,8 +469,16 @@ const Carousel = /*#__PURE__*/_react.default.forwardRef((_ref3, ref) => {
   const [isCarouselPlaying, setisCarouselPlaying] = _react.default.useState(autoPlayFeatureEnabled);
   const isSwiping = _react.default.useRef(false);
   const autoPlayRef = _react.default.useRef(null);
+  const [rootContainerLayout, setRootContainerLayout] = _react.default.useState({
+    x: 0,
+    y: 0,
+    width: 0,
+    height: 0
+  });
+  const rootContainerLayoutRef = _react.default.useRef(rootContainerLayout);
   const isFirstSlide = !activeIndex;
   const isLastSlide = activeIndex + 1 >= totalItems;
+  const currentViewportWidth = rootContainerLayout.width;
   const handleAnimationStart = _react.default.useCallback(function () {
     if (typeof onAnimationStart === 'function') onAnimationStart(...arguments);
     setIsAnimating(true);
@@ -461,15 +496,15 @@ const Carousel = /*#__PURE__*/_react.default.forwardRef((_ref3, ref) => {
     if (enablePeeking) {
       const {
         peekingGap,
-        peekingMiddleSpace,
-        peekingMarginLeft
+        peekingMiddleSpace
       } = getPeekingProps(viewport);
       let finalWidth;
-      const slideWide = containerLayoutRef.current.width - (peekingMiddleSpace * _Constants.PEEKING_MULTIPLIER + peekingGap * _Constants.PEEKING_MULTIPLIER);
+      const baseWidth = maxWidth || containerLayoutRef.current.width;
+      const slideWide = baseWidth - peekingMiddleSpace * _Constants.PEEKING_MULTIPLIER;
       if (activeIndexRef.current === 0) {
         finalWidth = 0;
       } else {
-        finalWidth = slideWide + peekingMarginLeft - peekingMiddleSpace + (slideWide + peekingGap) * (activeIndexRef.current - _Constants.ACTIVE_INDEX_OFFSET_MULTIPLIER);
+        finalWidth = (slideWide + peekingGap) * activeIndexRef.current;
       }
       animatedX.current = finalWidth * _Constants.NEGATIVE_MULTIPLIER;
     } else {
@@ -496,8 +531,9 @@ const Carousel = /*#__PURE__*/_react.default.forwardRef((_ref3, ref) => {
         y: 0
       });
     }
-  }, [pan, animatedX, heroPan, heroAnimatedX, enableHero, viewport, enablePeeking]);
-  const animate = _react.default.useCallback((panToAnimate, toValue, toIndex) => {
+  }, [pan, animatedX, heroPan, heroAnimatedX, enableHero, viewport, enablePeeking, maxWidth]);
+  const animate = _react.default.useCallback(function (panToAnimate, toValue, toIndex) {
+    let isSwipeRelease = arguments.length > 3 && arguments[3] !== undefined ? arguments[3] : false;
     const applicableTransitionDuration = isLastSlide && toIndex === 0 ? loopDuration : transitionDuration;
     const handleAnimationEndToIndex = function () {
       for (var _len = arguments.length, args = new Array(_len), _key = 0; _key < _len; _key++) {
@@ -505,10 +541,23 @@ const Carousel = /*#__PURE__*/_react.default.forwardRef((_ref3, ref) => {
       }
       return handleAnimationEnd(toIndex, ...args);
     };
-    if (reduceMotionRef.current || isSwiping.current) {
+    if (reduceMotionRef.current) {
+      _Animated.default.timing(panToAnimate, {
+        toValue,
+        duration: _Constants.INSTANT_ANIMATION_DURATION,
+        useNativeDriver: false
+      }).start(handleAnimationEndToIndex);
+    } else if (isSwipeRelease && swipeReleaseStyle === _Constants.SWIPE_RELEASE_STYLES.EASE_OUT) {
       _Animated.default.timing(panToAnimate, {
         toValue,
-        duration: 1,
+        duration: swipeReleaseDuration,
+        easing: _Easing.default.out(_Easing.default.cubic),
+        useNativeDriver: false
+      }).start(handleAnimationEndToIndex);
+    } else if (isSwiping.current || isSwipeRelease) {
+      _Animated.default.timing(panToAnimate, {
+        toValue,
+        duration: _Constants.INSTANT_ANIMATION_DURATION,
         useNativeDriver: false
       }).start(handleAnimationEndToIndex);
     } else if (isAutoPlayEnabled) {
@@ -532,7 +581,7 @@ const Carousel = /*#__PURE__*/_react.default.forwardRef((_ref3, ref) => {
         useNativeDriver: false
       }).start(handleAnimationEndToIndex);
     }
-  }, [springConfig, handleAnimationEnd, transitionDuration, loopDuration, isLastSlide, isAutoPlayEnabled, enablePeeking, enableDisplayMultipleItemsPerSlide]);
+  }, [springConfig, handleAnimationEnd, transitionDuration, loopDuration, isLastSlide, isAutoPlayEnabled, enablePeeking, enableDisplayMultipleItemsPerSlide, swipeReleaseStyle, swipeReleaseDuration]);
   const stopAutoplay = _react.default.useCallback(() => {
     if (autoPlayRef?.current) {
       clearTimeout(autoPlayRef?.current);
@@ -555,25 +604,26 @@ const Carousel = /*#__PURE__*/_react.default.forwardRef((_ref3, ref) => {
     };
     let skipChanges = !delta;
     let calcDelta = delta;
+    const isSwipeRelease = transitionMode === _Constants.TRANSITION_MODES.SWIPE;
     if (activeIndexRef.current <= 0 && delta < 0) {
-      skipChanges = transitionMode !== TRANSITION_MODES.AUTOMATIC;
+      skipChanges = transitionMode !== _Constants.TRANSITION_MODES.AUTOMATIC;
       calcDelta = totalItems + delta;
     } else if (activeIndexRef.current + 1 >= totalItems && delta > 0) {
-      skipChanges = transitionMode !== TRANSITION_MODES.AUTOMATIC;
+      skipChanges = transitionMode !== _Constants.TRANSITION_MODES.AUTOMATIC;
       calcDelta = -1 * activeIndexRef.current + delta - 1;
     }
     const index = activeIndexRef.current + calcDelta;
     if (skipChanges) {
       isTransitioningRef.current = true;
-      animate(pan, toValue, index);
+      animate(pan, toValue, index, isSwipeRelease);
       if (enableHero) {
-        animate(heroPan, toValue, index);
+        animate(heroPan, toValue, index, isSwipeRelease);
       }
       return calcDelta;
     }
     stopAutoplay();
     setActiveIndex(index);
-    const finalWidth = calculateFinalWidth(containerLayoutRef.current.width, enablePeeking, viewport, activeIndexRef);
+    const finalWidth = calculateFinalWidth(containerLayoutRef.current.width, enablePeeking, viewport, maxWidth);
     toValue.x = finalWidth * -1 * calcDelta;
     const heroToValue = {
       x: 0,
@@ -581,33 +631,33 @@ const Carousel = /*#__PURE__*/_react.default.forwardRef((_ref3, ref) => {
     };
     heroToValue.x = heroContainerLayoutRef.current.width * -1 * calcDelta;
     isTransitioningRef.current = true;
-    animate(pan, toValue, index);
+    animate(pan, toValue, index, isSwipeRelease);
     if (enableHero) {
-      animate(heroPan, heroToValue, index);
+      animate(heroPan, heroToValue, index, isSwipeRelease);
     }
     if (isCarouselPlaying) {
       stopAutoplay();
-      if (index === 0 && activeIndexRef.current + 1 === totalItems && transitionMode === TRANSITION_MODES.AUTOMATIC) {
+      if (index === 0 && activeIndexRef.current + 1 === totalItems && transitionMode === _Constants.TRANSITION_MODES.AUTOMATIC) {
         setisCarouselPlaying(false);
       } else if (isAutoPlayEnabled) {
         autoPlayRef.current = setTimeout(() => {
           updateOffset();
           handleAnimationStart(activeIndexRef.current);
-          updateIndex(slideDuration < 0 ? -1 : 1, TRANSITION_MODES.AUTOMATIC);
+          updateIndex(slideDuration < 0 ? -1 : 1, _Constants.TRANSITION_MODES.AUTOMATIC);
           triggerRefocus();
         }, Math.abs(slideDuration) * 1000);
       }
     }
     if (onIndexChanged) onIndexChanged(calcDelta, index);
     return calcDelta;
-  }, [handleAnimationStart, triggerRefocus, slideDuration, updateOffset, animate, totalItems, onIndexChanged, isCarouselPlaying, stopAutoplay, isAutoPlayEnabled, viewport, enablePeeking, pan, heroPan, enableHero]);
+  }, [handleAnimationStart, triggerRefocus, slideDuration, updateOffset, animate, totalItems, onIndexChanged, isCarouselPlaying, stopAutoplay, isAutoPlayEnabled, viewport, enablePeeking, pan, heroPan, enableHero, maxWidth]);
   const startAutoplay = _react.default.useCallback(() => {
     stopAutoplay();
     if (isAutoPlayEnabled) {
       autoPlayRef.current = setTimeout(() => {
         updateOffset();
         handleAnimationStart(activeIndexRef.current);
-        updateIndex(slideDuration < 0 ? -1 : 1, TRANSITION_MODES.AUTOMATIC);
+        updateIndex(slideDuration < 0 ? -1 : 1, _Constants.TRANSITION_MODES.AUTOMATIC);
         triggerRefocus();
       }, Math.abs(slideDuration) * 1000);
     }
@@ -620,7 +670,7 @@ const Carousel = /*#__PURE__*/_react.default.forwardRef((_ref3, ref) => {
   }, [updateIndex, updateOffset, handleAnimationStart, triggerRefocus]);
   const goToNeighboring = _react.default.useCallback(function () {
     let toPrev = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : false;
-    let transitionMode = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : TRANSITION_MODES.MANUAL;
+    let transitionMode = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : _Constants.TRANSITION_MODES.MANUAL;
     fixOffsetAndGo(toPrev ? -1 : 1, transitionMode);
   }, [fixOffsetAndGo]);
   _react.default.useEffect(() => {
@@ -635,6 +685,9 @@ const Carousel = /*#__PURE__*/_react.default.forwardRef((_ref3, ref) => {
   _react.default.useEffect(() => {
     heroContainerLayoutRef.current = heroContainerLayout;
   }, [heroContainerLayout]);
+  _react.default.useEffect(() => {
+    rootContainerLayoutRef.current = rootContainerLayout;
+  }, [rootContainerLayout]);
   _react.default.useEffect(() => {
     pan.x.addListener(_ref5 => {
       let {
@@ -743,6 +796,25 @@ const Carousel = /*#__PURE__*/_react.default.forwardRef((_ref3, ref) => {
     } = _ref11;
     return setPreviousNextNavigationButtonWidth(width);
   };
+  const onRootContainerLayout = _ref12 => {
+    let {
+      nativeEvent: {
+        layout: {
+          x,
+          y,
+          width,
+          height
+        }
+      }
+    } = _ref12;
+    return setRootContainerLayout(prevState => ({
+      ...prevState,
+      x,
+      y,
+      width,
+      height
+    }));
+  };
   const isSwipeAllowed = _react.default.useCallback(() => {
     if (totalItems === 1) {
       return false;
@@ -780,16 +852,16 @@ const Carousel = /*#__PURE__*/_react.default.forwardRef((_ref3, ref) => {
         startAutoplay();
       }
       const correction = gesture.moveX - gesture.x0;
+      isSwiping.current = false;
       if (Math.abs(correction) < containerLayoutRef.current.width * minDistanceForAction) {
         animate(pan, {
           x: 0,
           y: 0
-        }, 0);
+        }, activeIndexRef.current, true);
       } else {
         const delta = correction > 0 ? -1 : 1;
-        updateIndex(delta, TRANSITION_MODES.SWIPE);
+        updateIndex(delta, _Constants.TRANSITION_MODES.SWIPE);
       }
-      isSwiping.current = false;
     }
   }), [pan, updateIndex, updateOffset, animate, isSwipeAllowed, minDistanceForAction, handleAnimationStart, minDistanceToCapture, startAutoplay, stopAutoplay, isCarouselPlaying]);
   const heroPanResponder = _react.default.useMemo(() => _PanResponder.default.create({
@@ -820,16 +892,16 @@ const Carousel = /*#__PURE__*/_react.default.forwardRef((_ref3, ref) => {
         startAutoplay();
       }
       const correction = gesture.moveX - gesture.x0;
+      isSwiping.current = false;
       if (Math.abs(correction) < containerLayoutRef.current.width * minDistanceForAction) {
         animate(heroPan, {
           x: 0,
           y: 0
-        }, 0);
+        }, activeIndexRef.current, true);
       } else {
         const delta = correction > 0 ? -1 : 1;
-        updateIndex(delta, TRANSITION_MODES.SWIPE);
+        updateIndex(delta, _Constants.TRANSITION_MODES.SWIPE);
       }
-      isSwiping.current = false;
     }
   }), [heroPan, updateIndex, updateOffset, animate, isSwipeAllowed, minDistanceForAction, handleAnimationStart, minDistanceToCapture, startAutoplay, stopAutoplay, isCarouselPlaying]);
   const goToNext = _react.default.useCallback(() => {
@@ -842,7 +914,7 @@ const Carousel = /*#__PURE__*/_react.default.forwardRef((_ref3, ref) => {
     let index = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : 0;
     const delta = index - activeIndexRef.current;
     if (delta) {
-      fixOffsetAndGo(delta, TRANSITION_MODES.MANUAL);
+      fixOffsetAndGo(delta, _Constants.TRANSITION_MODES.MANUAL);
     }
   }, [fixOffsetAndGo]);
 
@@ -908,9 +980,10 @@ const Carousel = /*#__PURE__*/_react.default.forwardRef((_ref3, ref) => {
     }
   }, [isTransitioningRef]);
   return /*#__PURE__*/(0, _jsxRuntime.jsxs)(_View.default, {
-    style: selectRootContainerStyles(enableHero, viewport),
+    style: selectRootContainerStyles(enableHero, viewport, enablePeeking),
+    onLayout: onRootContainerLayout,
     children: [/*#__PURE__*/(0, _jsxRuntime.jsx)(_View.default, {
-      style: selectMainContainerStyles(enableHero, viewport, maxWidth),
+      style: selectMainContainerStyles(enableHero, viewport, maxWidth, enablePeeking),
       children: /*#__PURE__*/(0, _jsxRuntime.jsxs)(_CarouselContext.CarouselProvider, {
         activeIndex: activeIndex,
         goTo: goTo,
@@ -922,6 +995,8 @@ const Carousel = /*#__PURE__*/_react.default.forwardRef((_ref3, ref) => {
         refocus: refocus,
         width: containerLayout.width,
         maximumItemsForSlide: getMaximumItemsForSlide(enableDisplayMultipleItemsPerSlide, viewport),
+        maxWidth: maxWidth,
+        viewportWidth: currentViewportWidth,
         children: [/*#__PURE__*/(0, _jsxRuntime.jsxs)(_View.default, {
           style: [staticStyles.root, {
             ...(_Platform.default.OS === 'web' ? {
@@ -944,7 +1019,9 @@ const Carousel = /*#__PURE__*/_react.default.forwardRef((_ref3, ref) => {
               enablePeeking,
               enableDisplayMultipleItemsPerSlide,
               isAutoPlayEnabled,
-              viewport
+              viewport,
+              maxWidth,
+              viewportWidth: currentViewportWidth
             })],
             children: /*#__PURE__*/(0, _jsxRuntime.jsx)(_IconButton.default, {
               icon: isCarouselPlaying ? pauseIcon : playIcon,
@@ -953,7 +1030,7 @@ const Carousel = /*#__PURE__*/_react.default.forwardRef((_ref3, ref) => {
               onPress: onAnimationControlButtonPress
             })
           }) : null, showPreviousNextNavigation && totalItems > 1 ? /*#__PURE__*/(0, _jsxRuntime.jsx)(_View.default, {
-            style: selectPreviousNextNavigationButtonStyles(previousNextNavigationButtonWidth, previousNextNavigationPosition, spaceBetweenSlideAndPreviousNextNavigation, isFirstSlide, isLastSlide, true, enablePeeking, enableDisplayMultipleItemsPerSlide, isAutoPlayEnabled, viewport),
+            style: selectPreviousNextNavigationButtonStyles(previousNextNavigationButtonWidth, previousNextNavigationPosition, spaceBetweenSlideAndPreviousNextNavigation, isFirstSlide, isLastSlide, true, enablePeeking, enableDisplayMultipleItemsPerSlide, isAutoPlayEnabled, viewport, maxWidth, currentViewportWidth),
             testID: "previous-button-container",
             children: /*#__PURE__*/(0, _jsxRuntime.jsx)(_IconButton.default, {
               onLayout: onPreviousNextNavigationButtonLayout,
@@ -991,16 +1068,7 @@ const Carousel = /*#__PURE__*/_react.default.forwardRef((_ref3, ref) => {
               children: childrenArray.map((element, index) => {
                 let hidden = !isAnimating && index !== activeIndex;
                 if (enablePeeking && !isAnimating) {
-                  if (enableDisplayMultipleItemsPerSlide) {
-                    const maxItemsForSlide = getMaximumItemsForSlide(enableDisplayMultipleItemsPerSlide, viewport);
-                    if (index >= activeIndex * maxItemsForSlide - 1 && index < activeIndex * maxItemsForSlide + maxItemsForSlide + 1) {
-                      hidden = false;
-                    } else {
-                      hidden = true;
-                    }
-                  } else if (index >= activeIndex - 1 && index <= activeIndex + 1) {
-                    hidden = false;
-                  }
+                  hidden = false;
                 } else if (!enablePeeking && enableDisplayMultipleItemsPerSlide && !isAnimating) {
                   const maxItemsForSlide = getMaximumItemsForSlide(enableDisplayMultipleItemsPerSlide, viewport);
                   if (index >= activeIndex * maxItemsForSlide && index < activeIndex * maxItemsForSlide + maxItemsForSlide) {
@@ -1022,7 +1090,7 @@ const Carousel = /*#__PURE__*/_react.default.forwardRef((_ref3, ref) => {
               })
             })
           }), showPreviousNextNavigation && totalItems > 1 ? /*#__PURE__*/(0, _jsxRuntime.jsx)(_View.default, {
-            style: selectPreviousNextNavigationButtonStyles(previousNextNavigationButtonWidth, previousNextNavigationPosition, spaceBetweenSlideAndPreviousNextNavigation, isFirstSlide, isLastSlide, false, enablePeeking, enableDisplayMultipleItemsPerSlide, isAutoPlayEnabled, viewport),
+            style: selectPreviousNextNavigationButtonStyles(previousNextNavigationButtonWidth, previousNextNavigationPosition, spaceBetweenSlideAndPreviousNextNavigation, isFirstSlide, isLastSlide, false, enablePeeking, enableDisplayMultipleItemsPerSlide, isAutoPlayEnabled, viewport, maxWidth, currentViewportWidth),
             testID: "next-button-container",
             children: /*#__PURE__*/(0, _jsxRuntime.jsx)(_IconButton.default, {
               onLayout: onPreviousNextNavigationButtonLayout,
@@ -1034,7 +1102,7 @@ const Carousel = /*#__PURE__*/_react.default.forwardRef((_ref3, ref) => {
             })
           }) : null]
         }), /*#__PURE__*/(0, _jsxRuntime.jsx)(_View.default, {
-          style: selectNavigationStyles(tabs, enableHero, viewport),
+          style: selectNavigationStyles(tabs, enableHero, viewport, enablePeeking, maxWidth),
           children: showPanelNavigation ? activePanelNavigation : null
         })]
       })
@@ -1285,7 +1353,23 @@ Carousel.propTypes = {
     md: _propTypes.default.oneOfType([_propTypes.default.oneOf(['max', 'full']), _propTypes.default.number]),
     sm: _propTypes.default.oneOfType([_propTypes.default.oneOf(['max', 'full']), _propTypes.default.number]),
     xs: _propTypes.default.oneOfType([_propTypes.default.oneOf(['max', 'full']), _propTypes.default.number])
-  })
+  }),
+  /**
+   * Animation style for swipe release transitions.
+   * - `'instant'`: Immediate snap to position (current default)
+   * - `'ease-out'`: Smooth deceleration animation
+   * - Default value is `'instant'`
+   * - Use `swipeReleaseDuration` to customize the animation duration when using `'ease-out'`
+   *
+   * @deprecated The default will change to `'ease-out'` in Q2 2026 (introduced Jan 2026).
+   */
+  swipeReleaseStyle: _propTypes.default.oneOf(['instant', 'ease-out']),
+  /**
+   * Duration in milliseconds of the ease-out animation when releasing a swipe gesture.
+   * Only applies when `swipeReleaseStyle` is set to `'ease-out'`.
+   * - Default value is `500` (500ms)
+   */
+  swipeReleaseDuration: _propTypes.default.number
 };
 Carousel.Item = _CarouselItem.default;
 Carousel.displayName = 'Carousel';

package/lib/cjs/Carousel/CarouselContext.js

@@ -22,7 +22,9 @@ const CarouselProvider = _ref => {
     themeTokens,
     totalItems,
     width,
-    maximumItemsForSlide
+    maximumItemsForSlide,
+    maxWidth,
+    viewportWidth
   } = _ref;
   const value = _react.default.useMemo(() => ({
     activeIndex,
@@ -33,8 +35,10 @@ const CarouselProvider = _ref => {
     themeTokens,
     totalItems,
     width,
-    maximumItemsForSlide
-  }), [activeIndex, goTo, getCopyWithPlaceholders, itemLabel, refocus, totalItems, themeTokens, width, maximumItemsForSlide]);
+    maximumItemsForSlide,
+    maxWidth,
+    viewportWidth
+  }), [activeIndex, goTo, getCopyWithPlaceholders, itemLabel, refocus, totalItems, themeTokens, width, maximumItemsForSlide, maxWidth, viewportWidth]);
   return /*#__PURE__*/(0, _jsxRuntime.jsx)(CarouselContext.Provider, {
     value: value,
     children: children
@@ -58,5 +62,7 @@ CarouselProvider.propTypes = {
   themeTokens: (0, _utils.getTokensPropType)('Carousel'),
   totalItems: _propTypes.default.number.isRequired,
   width: _propTypes.default.number.isRequired,
-  maximumItemsForSlide: _propTypes.default.number
+  maximumItemsForSlide: _propTypes.default.number,
+  maxWidth: _propTypes.default.number,
+  viewportWidth: _propTypes.default.number
 };

package/lib/cjs/Carousel/CarouselItem/CarouselItem.js

@@ -19,26 +19,26 @@ const selectContainerStyle = _ref => {
     width,
     elementIndex,
     enablePeeking,
-    peekingMarginLeft,
     peekingGap,
     hidden,
     enableDisplayMultipleItemsPerSlide,
     viewport,
-    peekingMiddleSpace
+    peekingMiddleSpace,
+    maxWidth,
+    viewportWidth
   } = _ref;
   let adjustedWidth = width;
   let marginLeft = 0;
   if (enablePeeking) {
     const isFirst = elementIndex === 0;
-    adjustedWidth = width - (peekingMiddleSpace * 2 + peekingGap * 2);
+    const baseWidth = maxWidth || width;
+    adjustedWidth = baseWidth - peekingMiddleSpace * 2;
     if (isFirst) {
-      marginLeft = peekingMarginLeft;
+      marginLeft = peekingMiddleSpace + (viewportWidth - maxWidth) / 2;
     } else {
       marginLeft = peekingGap;
     }
   }
-
-  // Adjust width and margins for multiple items per slide.
   if (enableDisplayMultipleItemsPerSlide) {
     switch (viewport) {
       case 'xs':
@@ -96,7 +96,9 @@ const CarouselItem = /*#__PURE__*/_react.default.forwardRef((_ref2, ref) => {
     width,
     activeIndex,
     goTo,
-    maximumItemsForSlide
+    maximumItemsForSlide,
+    maxWidth,
+    viewportWidth
   } = (0, _CarouselContext.useCarousel)();
   const selectedProps = selectProps({
     ...rest,
@@ -139,6 +141,8 @@ const CarouselItem = /*#__PURE__*/_react.default.forwardRef((_ref2, ref) => {
       enablePeeking,
       enableDisplayMultipleItemsPerSlide,
       viewport,
+      maxWidth,
+      viewportWidth,
       ...peekingProps
     }),
     ...selectedProps,

package/lib/cjs/Carousel/Constants.js

@@ -3,7 +3,7 @@
 Object.defineProperty(exports, "__esModule", {
   value: true
 });
-exports.PEEKING_MULTIPLIER = exports.NEGATIVE_MULTIPLIER = exports.LARGE_VIEWPORT_MARGIN = exports.ITEMS_PER_VIEWPORT_XS_SM = exports.ITEMS_PER_VIEWPORT_MD = exports.ITEMS_PER_VIEWPORT_LG_XL = exports.HERO_POSITION_OFFSET = exports.GAP_BETWEEN_ITEMS = exports.DEFAULT_VIEWPORT_MARGIN = exports.DEFAULT_POSITION_OFFSET = exports.ACTIVE_INDEX_OFFSET_MULTIPLIER = void 0;
+exports.TRANSITION_MODES = exports.SWIPE_RELEASE_STYLES = exports.POSITION_VARIANTS = exports.POSITION_PROPERTIES = exports.PEEKING_MULTIPLIER = exports.NEGATIVE_MULTIPLIER = exports.LARGE_VIEWPORT_MARGIN = exports.ITEMS_PER_VIEWPORT_XS_SM = exports.ITEMS_PER_VIEWPORT_MD = exports.ITEMS_PER_VIEWPORT_LG_XL = exports.INSTANT_ANIMATION_DURATION = exports.HERO_POSITION_OFFSET = exports.GAP_BETWEEN_ITEMS = exports.DEFAULT_VIEWPORT_MARGIN = exports.DEFAULT_SWIPE_RELEASE_DURATION = exports.DEFAULT_POSITION_OFFSET = exports.ACTIVE_INDEX_OFFSET_MULTIPLIER = void 0;
 const ITEMS_PER_VIEWPORT_XS_SM = exports.ITEMS_PER_VIEWPORT_XS_SM = 1;
 const ITEMS_PER_VIEWPORT_MD = exports.ITEMS_PER_VIEWPORT_MD = 2;
 const ITEMS_PER_VIEWPORT_LG_XL = exports.ITEMS_PER_VIEWPORT_LG_XL = 3;
@@ -14,4 +14,24 @@ const LARGE_VIEWPORT_MARGIN = exports.LARGE_VIEWPORT_MARGIN = 40;
 const DEFAULT_VIEWPORT_MARGIN = exports.DEFAULT_VIEWPORT_MARGIN = 10;
 const PEEKING_MULTIPLIER = exports.PEEKING_MULTIPLIER = 2;
 const ACTIVE_INDEX_OFFSET_MULTIPLIER = exports.ACTIVE_INDEX_OFFSET_MULTIPLIER = 1;
-const NEGATIVE_MULTIPLIER = exports.NEGATIVE_MULTIPLIER = -1;
+const NEGATIVE_MULTIPLIER = exports.NEGATIVE_MULTIPLIER = -1;
+const TRANSITION_MODES = exports.TRANSITION_MODES = {
+  MANUAL: 'manual',
+  AUTOMATIC: 'automatic',
+  SWIPE: 'swipe'
+};
+const SWIPE_RELEASE_STYLES = exports.SWIPE_RELEASE_STYLES = {
+  INSTANT: 'instant',
+  EASE_OUT: 'ease-out'
+};
+const INSTANT_ANIMATION_DURATION = exports.INSTANT_ANIMATION_DURATION = 1;
+const DEFAULT_SWIPE_RELEASE_DURATION = exports.DEFAULT_SWIPE_RELEASE_DURATION = 500;
+const POSITION_VARIANTS = exports.POSITION_VARIANTS = {
+  EDGE: 'edge',
+  INSIDE: 'inside',
+  OUTSIDE: 'outside'
+};
+const POSITION_PROPERTIES = exports.POSITION_PROPERTIES = {
+  LEFT: 'left',
+  RIGHT: 'right'
+};