@telus-uds/components-base 3.25.0 → 3.27.0

package/lib/esm/Carousel/Carousel.js

@@ -5,6 +5,7 @@ import PanResponder from "react-native-web/dist/exports/PanResponder";
 import StyleSheet from "react-native-web/dist/exports/StyleSheet";
 import Platform from "react-native-web/dist/exports/Platform";
 import Dimensions from "react-native-web/dist/exports/Dimensions";
+import Easing from "react-native-web/dist/exports/Easing";
 import PropTypes from 'prop-types';
 import { useThemeTokens, useTheme } from '../ThemeProvider';
 import { useViewport } from '../ViewportProvider';
@@ -21,13 +22,8 @@ import CarouselTabsPanel from './CarouselTabs/CarouselTabsPanel';
 import CarouselTabsPanelItem from './CarouselTabs/CarouselTabsPanelItem';
 import dictionary from './dictionary';
 import Box from '../Box';
-import { ITEMS_PER_VIEWPORT_XS_SM, ITEMS_PER_VIEWPORT_MD, ITEMS_PER_VIEWPORT_LG_XL, DEFAULT_POSITION_OFFSET, LARGE_VIEWPORT_MARGIN, DEFAULT_VIEWPORT_MARGIN, PEEKING_MULTIPLIER, ACTIVE_INDEX_OFFSET_MULTIPLIER, NEGATIVE_MULTIPLIER } from './Constants';
+import { ITEMS_PER_VIEWPORT_XS_SM, ITEMS_PER_VIEWPORT_MD, ITEMS_PER_VIEWPORT_LG_XL, DEFAULT_POSITION_OFFSET, LARGE_VIEWPORT_MARGIN, DEFAULT_VIEWPORT_MARGIN, PEEKING_MULTIPLIER, NEGATIVE_MULTIPLIER, TRANSITION_MODES, SWIPE_RELEASE_STYLES, INSTANT_ANIMATION_DURATION, DEFAULT_SWIPE_RELEASE_DURATION, POSITION_VARIANTS, POSITION_PROPERTIES } from './Constants';
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-const TRANSITION_MODES = {
-  MANUAL: 'manual',
-  AUTOMATIC: 'automatic',
-  SWIPE: 'swipe'
-};
 const staticStyles = StyleSheet.create({
   root: {
     backgroundColor: 'transparent',
@@ -76,7 +72,7 @@ const selectHeroContainerStyles = (width, hidden) => ({
   width,
   visibility: hidden ? 'hidden' : 'visible'
 });
-const getDynamicPositionProperty = areStylesAppliedOnPreviousButton => areStylesAppliedOnPreviousButton ? 'left' : 'right';
+const getDynamicPositionProperty = areStylesAppliedOnPreviousButton => areStylesAppliedOnPreviousButton ? POSITION_PROPERTIES.LEFT : POSITION_PROPERTIES.RIGHT;
 const selectControlButtonPositionStyles = _ref => {
   let {
     positionVariant,
@@ -86,23 +82,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] = DEFAULT_POSITION_OFFSET;
-  } else if (positionVariant === 'outside') {
+  let positionOffset = 0;
+  if (positionVariant === POSITION_VARIANTS.EDGE) {
+    positionOffset = -1 * (buttonWidth / 2);
+  } else if (positionVariant === POSITION_VARIANTS.INSIDE) {
+    positionOffset = DEFAULT_POSITION_OFFSET;
+  } else if (positionVariant === 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 === POSITION_PROPERTIES.RIGHT) {
+      const rightMargin = (viewportWidth - maxWidth) / 2;
+      positionOffset += rightMargin;
+    } else if (positionProperty === 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'
@@ -124,7 +133,9 @@ const selectPreviousNextNavigationButtonStyles = (previousNextNavigationButtonWi
       enablePeeking,
       enableDisplayMultipleItemsPerSlide,
       isAutoPlayEnabled,
-      viewport
+      viewport,
+      maxWidth,
+      viewportWidth
     })
   };
 };
@@ -190,7 +201,7 @@ const getMaximumItemsForSlide = (enableDisplayMultipleItemsPerSlide, viewport) =
   }
   return ITEMS_PER_VIEWPORT_XS_SM;
 };
-const selectRootContainerStyles = (enableHero, viewport) => {
+const selectRootContainerStyles = (enableHero, viewport, enablePeeking) => {
   if (enableHero && viewport === 'xl' && Platform.OS === 'web') {
     return {
       alignItems: 'center'
@@ -201,15 +212,25 @@ const selectRootContainerStyles = (enableHero, viewport) => {
       paddingHorizontal: 16
     };
   }
+  if (enablePeeking) {
+    return {
+      width: '100%'
+    };
+  }
   return {};
 };
-const selectMainContainerStyles = (enableHero, viewport, maxWidth) => {
-  if (enableHero && viewport === 'xl' && Platform.OS === 'web') {
+const selectMainContainerStyles = (enableHero, viewport, maxWidth, enablePeeking) => {
+  if (enableHero && viewport === 'xl' && Platform.OS === 'web' && !enablePeeking) {
     return {
       width: '100%',
       maxWidth: maxWidth || 1200
     };
   }
+  if (enablePeeking) {
+    return {
+      width: '100%'
+    };
+  }
   if (maxWidth !== null && maxWidth !== undefined) {
     return {
       maxWidth,
@@ -219,14 +240,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' ? LARGE_VIEWPORT_MARGIN : DEFAULT_VIEWPORT_MARGIN;
   }
-  return {
+  const styles = {
     marginHorizontal
   };
+  if (enablePeeking && maxWidth) {
+    styles.maxWidth = maxWidth;
+    styles.alignSelf = 'center';
+    styles.width = '100%';
+  }
+  return styles;
 };
 
 /**
@@ -235,23 +262,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 * PEEKING_MULTIPLIER + peekingGap * PEEKING_MULTIPLIER);
-    if (activeIndexRef.current === 0) {
-      finalWidth = slideWide + peekingMarginLeft - peekingMiddleSpace;
-    } else {
-      finalWidth = slideWide + peekingGap;
-    }
+    const baseWidth = maxWidth || containerWidth;
+    finalWidth = baseWidth - peekingMiddleSpace * PEEKING_MULTIPLIER + peekingGap;
   }
   return finalWidth;
 };
@@ -362,6 +384,8 @@ const Carousel = /*#__PURE__*/React.forwardRef((_ref3, ref) => {
     autoPlay = false,
     enablePeeking = false,
     contentMaxWidth,
+    swipeReleaseStyle = SWIPE_RELEASE_STYLES.INSTANT,
+    swipeReleaseDuration = DEFAULT_SWIPE_RELEASE_DURATION,
     ...rest
   } = _ref3;
   let childrenArray = unpackFragment(children);
@@ -372,7 +396,10 @@ const Carousel = /*#__PURE__*/React.forwardRef((_ref3, ref) => {
   } = useTheme();
   const contentMaxWidthValue = useResponsiveProp(contentMaxWidth);
   const responsiveWidth = useResponsiveProp(themeOptions?.contentMaxWidth);
-  const maxWidth = resolveContentMaxWidth(contentMaxWidthValue, responsiveWidth);
+  let maxWidth = null;
+  if (enablePeeking || contentMaxWidth !== undefined) {
+    maxWidth = contentMaxWidthValue === undefined ? responsiveWidth : 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
@@ -435,8 +462,16 @@ const Carousel = /*#__PURE__*/React.forwardRef((_ref3, ref) => {
   const [isCarouselPlaying, setisCarouselPlaying] = React.useState(autoPlayFeatureEnabled);
   const isSwiping = React.useRef(false);
   const autoPlayRef = React.useRef(null);
+  const [rootContainerLayout, setRootContainerLayout] = React.useState({
+    x: 0,
+    y: 0,
+    width: 0,
+    height: 0
+  });
+  const rootContainerLayoutRef = React.useRef(rootContainerLayout);
   const isFirstSlide = !activeIndex;
   const isLastSlide = activeIndex + 1 >= totalItems;
+  const currentViewportWidth = rootContainerLayout.width;
   const handleAnimationStart = React.useCallback(function () {
     if (typeof onAnimationStart === 'function') onAnimationStart(...arguments);
     setIsAnimating(true);
@@ -454,15 +489,15 @@ const Carousel = /*#__PURE__*/React.forwardRef((_ref3, ref) => {
     if (enablePeeking) {
       const {
         peekingGap,
-        peekingMiddleSpace,
-        peekingMarginLeft
+        peekingMiddleSpace
       } = getPeekingProps(viewport);
       let finalWidth;
-      const slideWide = containerLayoutRef.current.width - (peekingMiddleSpace * PEEKING_MULTIPLIER + peekingGap * PEEKING_MULTIPLIER);
+      const baseWidth = maxWidth || containerLayoutRef.current.width;
+      const slideWide = baseWidth - peekingMiddleSpace * PEEKING_MULTIPLIER;
       if (activeIndexRef.current === 0) {
         finalWidth = 0;
       } else {
-        finalWidth = slideWide + peekingMarginLeft - peekingMiddleSpace + (slideWide + peekingGap) * (activeIndexRef.current - ACTIVE_INDEX_OFFSET_MULTIPLIER);
+        finalWidth = (slideWide + peekingGap) * activeIndexRef.current;
       }
       animatedX.current = finalWidth * NEGATIVE_MULTIPLIER;
     } else {
@@ -489,8 +524,9 @@ const Carousel = /*#__PURE__*/React.forwardRef((_ref3, ref) => {
         y: 0
       });
     }
-  }, [pan, animatedX, heroPan, heroAnimatedX, enableHero, viewport, enablePeeking]);
-  const animate = React.useCallback((panToAnimate, toValue, toIndex) => {
+  }, [pan, animatedX, heroPan, heroAnimatedX, enableHero, viewport, enablePeeking, maxWidth]);
+  const animate = React.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++) {
@@ -498,10 +534,23 @@ const Carousel = /*#__PURE__*/React.forwardRef((_ref3, ref) => {
       }
       return handleAnimationEnd(toIndex, ...args);
     };
-    if (reduceMotionRef.current || isSwiping.current) {
+    if (reduceMotionRef.current) {
+      Animated.timing(panToAnimate, {
+        toValue,
+        duration: INSTANT_ANIMATION_DURATION,
+        useNativeDriver: false
+      }).start(handleAnimationEndToIndex);
+    } else if (isSwipeRelease && swipeReleaseStyle === SWIPE_RELEASE_STYLES.EASE_OUT) {
       Animated.timing(panToAnimate, {
         toValue,
-        duration: 1,
+        duration: swipeReleaseDuration,
+        easing: Easing.out(Easing.cubic),
+        useNativeDriver: false
+      }).start(handleAnimationEndToIndex);
+    } else if (isSwiping.current || isSwipeRelease) {
+      Animated.timing(panToAnimate, {
+        toValue,
+        duration: INSTANT_ANIMATION_DURATION,
         useNativeDriver: false
       }).start(handleAnimationEndToIndex);
     } else if (isAutoPlayEnabled) {
@@ -525,7 +574,7 @@ const Carousel = /*#__PURE__*/React.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.useCallback(() => {
     if (autoPlayRef?.current) {
       clearTimeout(autoPlayRef?.current);
@@ -548,6 +597,7 @@ const Carousel = /*#__PURE__*/React.forwardRef((_ref3, ref) => {
     };
     let skipChanges = !delta;
     let calcDelta = delta;
+    const isSwipeRelease = transitionMode === TRANSITION_MODES.SWIPE;
     if (activeIndexRef.current <= 0 && delta < 0) {
       skipChanges = transitionMode !== TRANSITION_MODES.AUTOMATIC;
       calcDelta = totalItems + delta;
@@ -558,15 +608,15 @@ const Carousel = /*#__PURE__*/React.forwardRef((_ref3, ref) => {
     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,
@@ -574,9 +624,9 @@ const Carousel = /*#__PURE__*/React.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();
@@ -593,7 +643,7 @@ const Carousel = /*#__PURE__*/React.forwardRef((_ref3, ref) => {
     }
     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.useCallback(() => {
     stopAutoplay();
     if (isAutoPlayEnabled) {
@@ -628,6 +678,9 @@ const Carousel = /*#__PURE__*/React.forwardRef((_ref3, ref) => {
   React.useEffect(() => {
     heroContainerLayoutRef.current = heroContainerLayout;
   }, [heroContainerLayout]);
+  React.useEffect(() => {
+    rootContainerLayoutRef.current = rootContainerLayout;
+  }, [rootContainerLayout]);
   React.useEffect(() => {
     pan.x.addListener(_ref5 => {
       let {
@@ -736,6 +789,25 @@ const Carousel = /*#__PURE__*/React.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.useCallback(() => {
     if (totalItems === 1) {
       return false;
@@ -773,16 +845,16 @@ const Carousel = /*#__PURE__*/React.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);
       }
-      isSwiping.current = false;
     }
   }), [pan, updateIndex, updateOffset, animate, isSwipeAllowed, minDistanceForAction, handleAnimationStart, minDistanceToCapture, startAutoplay, stopAutoplay, isCarouselPlaying]);
   const heroPanResponder = React.useMemo(() => PanResponder.create({
@@ -813,16 +885,16 @@ const Carousel = /*#__PURE__*/React.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);
       }
-      isSwiping.current = false;
     }
   }), [heroPan, updateIndex, updateOffset, animate, isSwipeAllowed, minDistanceForAction, handleAnimationStart, minDistanceToCapture, startAutoplay, stopAutoplay, isCarouselPlaying]);
   const goToNext = React.useCallback(() => {
@@ -901,9 +973,10 @@ const Carousel = /*#__PURE__*/React.forwardRef((_ref3, ref) => {
     }
   }, [isTransitioningRef]);
   return /*#__PURE__*/_jsxs(View, {
-    style: selectRootContainerStyles(enableHero, viewport),
+    style: selectRootContainerStyles(enableHero, viewport, enablePeeking),
+    onLayout: onRootContainerLayout,
     children: [/*#__PURE__*/_jsx(View, {
-      style: selectMainContainerStyles(enableHero, viewport, maxWidth),
+      style: selectMainContainerStyles(enableHero, viewport, maxWidth, enablePeeking),
       children: /*#__PURE__*/_jsxs(CarouselProvider, {
         activeIndex: activeIndex,
         goTo: goTo,
@@ -915,6 +988,8 @@ const Carousel = /*#__PURE__*/React.forwardRef((_ref3, ref) => {
         refocus: refocus,
         width: containerLayout.width,
         maximumItemsForSlide: getMaximumItemsForSlide(enableDisplayMultipleItemsPerSlide, viewport),
+        maxWidth: maxWidth,
+        viewportWidth: currentViewportWidth,
         children: [/*#__PURE__*/_jsxs(View, {
           style: [staticStyles.root, {
             ...(Platform.OS === 'web' ? {
@@ -937,7 +1012,9 @@ const Carousel = /*#__PURE__*/React.forwardRef((_ref3, ref) => {
               enablePeeking,
               enableDisplayMultipleItemsPerSlide,
               isAutoPlayEnabled,
-              viewport
+              viewport,
+              maxWidth,
+              viewportWidth: currentViewportWidth
             })],
             children: /*#__PURE__*/_jsx(IconButton, {
               icon: isCarouselPlaying ? pauseIcon : playIcon,
@@ -946,7 +1023,7 @@ const Carousel = /*#__PURE__*/React.forwardRef((_ref3, ref) => {
               onPress: onAnimationControlButtonPress
             })
           }) : null, showPreviousNextNavigation && totalItems > 1 ? /*#__PURE__*/_jsx(View, {
-            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__*/_jsx(IconButton, {
               onLayout: onPreviousNextNavigationButtonLayout,
@@ -984,16 +1061,7 @@ const Carousel = /*#__PURE__*/React.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) {
@@ -1015,7 +1083,7 @@ const Carousel = /*#__PURE__*/React.forwardRef((_ref3, ref) => {
               })
             })
           }), showPreviousNextNavigation && totalItems > 1 ? /*#__PURE__*/_jsx(View, {
-            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__*/_jsx(IconButton, {
               onLayout: onPreviousNextNavigationButtonLayout,
@@ -1027,7 +1095,7 @@ const Carousel = /*#__PURE__*/React.forwardRef((_ref3, ref) => {
             })
           }) : null]
         }), /*#__PURE__*/_jsx(View, {
-          style: selectNavigationStyles(tabs, enableHero, viewport),
+          style: selectNavigationStyles(tabs, enableHero, viewport, enablePeeking, maxWidth),
           children: showPanelNavigation ? activePanelNavigation : null
         })]
       })
@@ -1278,7 +1346,23 @@ Carousel.propTypes = {
     md: PropTypes.oneOfType([PropTypes.oneOf(['max', 'full']), PropTypes.number]),
     sm: PropTypes.oneOfType([PropTypes.oneOf(['max', 'full']), PropTypes.number]),
     xs: PropTypes.oneOfType([PropTypes.oneOf(['max', 'full']), PropTypes.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.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.number
 };
 Carousel.Item = CarouselItem;
 Carousel.displayName = 'Carousel';

package/lib/esm/Carousel/CarouselContext.js

@@ -14,7 +14,9 @@ const CarouselProvider = _ref => {
     themeTokens,
     totalItems,
     width,
-    maximumItemsForSlide
+    maximumItemsForSlide,
+    maxWidth,
+    viewportWidth
   } = _ref;
   const value = React.useMemo(() => ({
     activeIndex,
@@ -25,8 +27,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__*/_jsx(CarouselContext.Provider, {
     value: value,
     children: children
@@ -49,6 +53,8 @@ CarouselProvider.propTypes = {
   themeTokens: getTokensPropType('Carousel'),
   totalItems: PropTypes.number.isRequired,
   width: PropTypes.number.isRequired,
-  maximumItemsForSlide: PropTypes.number
+  maximumItemsForSlide: PropTypes.number,
+  maxWidth: PropTypes.number,
+  viewportWidth: PropTypes.number
 };
 export { CarouselProvider, useCarousel };

package/lib/esm/Carousel/CarouselItem/CarouselItem.js

@@ -12,26 +12,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':
@@ -89,7 +89,9 @@ const CarouselItem = /*#__PURE__*/React.forwardRef((_ref2, ref) => {
     width,
     activeIndex,
     goTo,
-    maximumItemsForSlide
+    maximumItemsForSlide,
+    maxWidth,
+    viewportWidth
   } = useCarousel();
   const selectedProps = selectProps({
     ...rest,
@@ -132,6 +134,8 @@ const CarouselItem = /*#__PURE__*/React.forwardRef((_ref2, ref) => {
       enablePeeking,
       enableDisplayMultipleItemsPerSlide,
       viewport,
+      maxWidth,
+      viewportWidth,
       ...peekingProps
     }),
     ...selectedProps,

package/lib/esm/Carousel/Constants.js

@@ -8,4 +8,24 @@ export const LARGE_VIEWPORT_MARGIN = 40;
 export const DEFAULT_VIEWPORT_MARGIN = 10;
 export const PEEKING_MULTIPLIER = 2;
 export const ACTIVE_INDEX_OFFSET_MULTIPLIER = 1;
-export const NEGATIVE_MULTIPLIER = -1;
+export const NEGATIVE_MULTIPLIER = -1;
+export const TRANSITION_MODES = {
+  MANUAL: 'manual',
+  AUTOMATIC: 'automatic',
+  SWIPE: 'swipe'
+};
+export const SWIPE_RELEASE_STYLES = {
+  INSTANT: 'instant',
+  EASE_OUT: 'ease-out'
+};
+export const INSTANT_ANIMATION_DURATION = 1;
+export const DEFAULT_SWIPE_RELEASE_DURATION = 500;
+export const POSITION_VARIANTS = {
+  EDGE: 'edge',
+  INSIDE: 'inside',
+  OUTSIDE: 'outside'
+};
+export const POSITION_PROPERTIES = {
+  LEFT: 'left',
+  RIGHT: 'right'
+};