@telus-uds/components-base 3.27.0 → 3.28.1

package/lib/esm/SideNav/ItemsGroup.js

@@ -4,6 +4,19 @@ import ItemContent from './ItemContent';
 import ExpandCollapse from '../ExpandCollapse';
 import { getTokensPropType, variantProp, componentPropType, selectTokens } from '../utils';
 import { useThemeTokensCallback } from '../ThemeProvider';
+import { jsx as _jsx } from "react/jsx-runtime";
+const selectPanelTokens = _ref => {
+  let {
+    borderWidth,
+    borderColor,
+    backgroundColor
+  } = _ref;
+  return {
+    contentPanelBackgroundColor: backgroundColor,
+    borderBottomWidth: borderWidth,
+    borderColor
+  };
+};
 
 /**
  Expandable content areas for use within `SideNav`.
@@ -15,8 +28,7 @@ import { useThemeTokensCallback } from '../ThemeProvider';
  ## Usage Criteria
  - Use `SideNav.ItemsGroup` with large pages that have multiple sections
  */
-import { jsx as _jsx } from "react/jsx-runtime";
-const ItemsGroup = /*#__PURE__*/React.forwardRef((_ref, ref) => {
+const ItemsGroup = /*#__PURE__*/React.forwardRef((_ref2, ref) => {
   let {
     children,
     label,
@@ -27,7 +39,7 @@ const ItemsGroup = /*#__PURE__*/React.forwardRef((_ref, ref) => {
     tokens,
     itemTokens,
     onToggle
-  } = _ref;
+  } = _ref2;
   // A SideNav control uses the same style and theme as SideNavItem, with a 'parent' variant,
   // plus control-specific tokens from the SideNavItemsGroup theme (e.g. open/close icon, etc).
   const getAppearance = appearance => ({
@@ -40,28 +52,27 @@ const ItemsGroup = /*#__PURE__*/React.forwardRef((_ref, ref) => {
     type: 'parent'
   });
   const getGroupTokens = useThemeTokensCallback('SideNavItemsGroup', tokens, variant);
-  const getPanelTokens = appearance => {
-    const {
-      panelBorderColor,
-      ...itemsGroupTokens
-    } = getGroupTokens(getAppearance(appearance));
-    const groupTokens = {
-      ...itemsGroupTokens,
-      borderWidth: 0,
-      marginBottom: 0
-    };
-    return selectTokens('ExpandCollapsePanel', groupTokens);
-  };
   const getItemTokens = useThemeTokensCallback('SideNavItem', itemTokens, variant);
-  const getControlTokens = appearance => selectTokens('ExpandCollapseControl', {
-    ...getItemTokens(getItemAppearance(appearance)),
-    // main style from SideNavItem
-    ...getGroupTokens(getAppearance(appearance)) // control-specific tokens like icon etc
+  const getPanelTokens = appearance => selectTokens('ExpandCollapsePanel', {
+    ...staticTokens.panel,
+    ...getGroupTokens(getAppearance(appearance)),
+    ...selectPanelTokens(getItemTokens(getItemAppearance(appearance)))
+  });
+  const getControlTokens = appearance => ({
+    ...selectTokens('ExpandCollapseControl', {
+      ...getItemTokens(getItemAppearance(appearance)),
+      // main style from SideNavItem
+      ...getGroupTokens(getAppearance(appearance)) // control-specific tokens like icon etc,
+    }),
+    ...staticTokens.control
   });
   const controlContent = controlState => {
     const currentItemTokens = getItemTokens(getItemAppearance(controlState));
     return /*#__PURE__*/_jsx(ItemContent, {
-      tokens: currentItemTokens,
+      tokens: {
+        ...currentItemTokens,
+        ...staticTokens.content
+      },
       children: label
     });
   };
@@ -77,9 +88,23 @@ const ItemsGroup = /*#__PURE__*/React.forwardRef((_ref, ref) => {
       active: isActive
     } // ExpandCollapse.Panel handles expanded state
     ,
+    disableMobileScrollBuffer: true,
     children: children
   });
 });
+const staticTokens = {
+  panel: {
+    borderWidth: 0,
+    marginBottom: 0
+  },
+  control: {
+    borderWidth: 0,
+    textLine: null
+  },
+  content: {
+    accentWidth: 0
+  }
+};
 ItemsGroup.displayName = 'ItemsGroup';
 ItemsGroup.propTypes = {
   /**

package/lib/esm/SideNav/SideNav.js

@@ -6,13 +6,28 @@ import ItemsGroup from './ItemsGroup';
 import { useThemeTokens } from '../ThemeProvider';
 import { a11yProps, componentPropType, getTokensPropType, selectSystemProps, variantProp, viewProps } from '../utils';
 import { jsx as _jsx } from "react/jsx-runtime";
-function selectBorderStyles(tokens) {
+const selectContainerTokens = _ref => {
+  let {
+    borderWidth,
+    borderStyle,
+    borderColor
+  } = _ref;
   return {
-    borderBottomWidth: tokens.borderWidth,
-    borderBottomStyle: tokens.borderStyle,
-    borderBottomColor: tokens.borderColor
+    borderTopWidth: borderWidth,
+    borderStyle,
+    borderColor
   };
-}
+};
+const selectItemTokens = function () {
+  let tokens = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : {};
+  let isLastItem = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : false;
+  return {
+    ...tokens,
+    ...(isLastItem ? {
+      borderWidth: 0
+    } : {})
+  };
+};
 const [selectProps, selectedSystemPropTypes] = selectSystemProps([a11yProps, viewProps]);
 
 /**
@@ -20,7 +35,7 @@ const [selectProps, selectedSystemPropTypes] = selectSystemProps([a11yProps, vie
  - Use in conjunction with a large amount of educational / informational content
  - Allow the user to navigate between options frequently and efficiently
  */
-const SideNav = /*#__PURE__*/React.forwardRef((_ref, ref) => {
+const SideNav = /*#__PURE__*/React.forwardRef((_ref2, ref) => {
   let {
     children,
     variant = {},
@@ -29,7 +44,7 @@ const SideNav = /*#__PURE__*/React.forwardRef((_ref, ref) => {
     itemTokens,
     groupTokens,
     ...rest
-  } = _ref;
+  } = _ref2;
   const themeTokens = useThemeTokens('SideNav', tokens, variant);
   const [active, setActive] = React.useState({
     groupId: undefined,
@@ -47,14 +62,15 @@ const SideNav = /*#__PURE__*/React.forwardRef((_ref, ref) => {
   return /*#__PURE__*/_jsx(ExpandCollapse, {
     ref: ref,
     maxOpen: accordion ? 1 : null,
-    style: selectBorderStyles(themeTokens),
+    tokens: selectContainerTokens(themeTokens),
     ...selectProps(rest),
-    children: _ref2 => {
+    children: _ref3 => {
       let {
         openIds,
         onToggle
-      } = _ref2;
-      const renderItem = (item, index, groupId) => {
+      } = _ref3;
+      const renderItem = function (item, index, groupId) {
+        let isLastItem = arguments.length > 3 && arguments[3] !== undefined ? arguments[3] : false;
         const {
           itemId = `item-${index}`,
           onPress
@@ -72,7 +88,7 @@ const SideNav = /*#__PURE__*/React.forwardRef((_ref, ref) => {
             ...variant,
             type: 'child'
           } : variant,
-          tokens: itemTokens,
+          tokens: selectItemTokens(itemTokens, isLastItem),
           isActive: isItemActive(itemId, groupId),
           onPress: handlePress
         });
@@ -96,7 +112,7 @@ const SideNav = /*#__PURE__*/React.forwardRef((_ref, ref) => {
             openGroups: openIds,
             isActive: isGroupActive,
             onToggle: handleToggle
-          }, React.Children.map(child.props.children, (item, itemIndex) => renderItem(item, itemIndex, groupId)));
+          }, React.Children.map(child.props.children, (item, itemIndex) => renderItem(item, itemIndex, groupId, itemIndex === child.props.children.length - 1)));
         }
         return null;
       });

package/lib/package.json

@@ -12,7 +12,7 @@
     "@gorhom/portal": "^1.0.14",
     "@react-native-picker/picker": "^2.9.0",
     "@telus-uds/system-constants": "^3.0.0",
-    "@telus-uds/system-theme-tokens": "^4.19.0",
+    "@telus-uds/system-theme-tokens": "^4.20.0",
     "airbnb-prop-types": "^2.16.0",
     "css-mediaquery": "^0.1.2",
     "expo-document-picker": "^13.0.1",
@@ -84,6 +84,6 @@
   "standard-engine": {
     "skip": true
   },
-  "version": "3.27.0",
+  "version": "3.28.1",
   "types": "types/index.d.ts"
 }

package/package.json

@@ -12,7 +12,7 @@
     "@gorhom/portal": "^1.0.14",
     "@react-native-picker/picker": "^2.9.0",
     "@telus-uds/system-constants": "^3.0.0",
-    "@telus-uds/system-theme-tokens": "^4.19.0",
+    "@telus-uds/system-theme-tokens": "^4.20.0",
     "airbnb-prop-types": "^2.16.0",
     "css-mediaquery": "^0.1.2",
     "expo-document-picker": "^13.0.1",
@@ -84,6 +84,6 @@
   "standard-engine": {
     "skip": true
   },
-  "version": "3.27.0",
+  "version": "3.28.1",
   "types": "types/index.d.ts"
 }

package/src/Card/CardBase.jsx

@@ -233,7 +233,13 @@ export const selectStyles = ({
  */
 const CardBase = React.forwardRef(
   ({ children, tokens, dataSet, backgroundImage, fullBleedContent, cardState, ...rest }, ref) => {
-    const cardStyle = selectStyles(typeof tokens === 'function' ? tokens(cardState) : tokens)
+    const resolvedTokens = typeof tokens === 'function' ? tokens(cardState) : tokens
+    const tokensToUse =
+      backgroundImage && backgroundImage.src
+        ? { ...resolvedTokens, gradient: undefined, backgroundGradient: undefined }
+        : resolvedTokens
+
+    const cardStyle = selectStyles(tokensToUse)
     const props = selectProps(rest)
 
     let content = children
@@ -314,7 +320,7 @@ const CardBase = React.forwardRef(
       })
 
       return (
-        <View style={containerStyle} dataSet={dataSet} ref={ref} {...props}>
+        <View style={{ ...containerStyle, borderRadius }} dataSet={dataSet} ref={ref} {...props}>
           {content}
         </View>
       )
@@ -393,7 +399,7 @@ const staticStyles = StyleSheet.create({
   contentOverlay: {
     position: 'relative',
     width: '100%',
-    height: '100%',
+    minHeight: '100%',
     zIndex: 2
   },
   containContainer: {

package/src/Carousel/Carousel.jsx

@@ -125,7 +125,7 @@ const selectControlButtonPositionStyles = ({
   isAutoPlayEnabled,
   viewport,
   maxWidth,
-  viewportWidth
+  containerWidth
 }) => {
   const styles = {}
 
@@ -148,13 +148,11 @@ const selectControlButtonPositionStyles = ({
   }
 
   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
-    }
+    const { peekingMiddleSpace, peekingGap } = getPeekingProps(viewport)
+    const clampedMaxWidth = Math.min(maxWidth || containerWidth, containerWidth)
+    const slideRightEdge = (containerWidth + clampedMaxWidth) / 2 - peekingMiddleSpace
+    const buttonCenter = slideRightEdge + peekingGap / 2
+    positionOffset = containerWidth - buttonCenter - buttonWidth / 2
   }
 
   styles[positionProperty] = positionOffset
@@ -173,7 +171,7 @@ const selectPreviousNextNavigationButtonStyles = (
   isAutoPlayEnabled,
   viewport,
   maxWidth,
-  viewportWidth
+  containerWidth
 ) => {
   const styles = {
     zIndex: 1,
@@ -199,7 +197,7 @@ const selectPreviousNextNavigationButtonStyles = (
       isAutoPlayEnabled,
       viewport,
       maxWidth,
-      viewportWidth
+      containerWidth
     })
   }
 }
@@ -343,7 +341,7 @@ const calculateFinalWidth = (containerWidth, enablePeeking, viewport, maxWidth)
 
   if (enablePeeking) {
     const { peekingGap, peekingMiddleSpace } = getPeekingProps(viewport)
-    const baseWidth = maxWidth || containerWidth
+    const baseWidth = Math.min(maxWidth || containerWidth, containerWidth)
     finalWidth = baseWidth - peekingMiddleSpace * PEEKING_MULTIPLIER + peekingGap
   }
 
@@ -572,7 +570,10 @@ const Carousel = React.forwardRef(
         const { peekingGap, peekingMiddleSpace } = getPeekingProps(viewport)
 
         let finalWidth
-        const baseWidth = maxWidth || containerLayoutRef.current.width
+        const baseWidth = Math.min(
+          maxWidth || containerLayoutRef.current.width,
+          containerLayoutRef.current.width
+        )
         const slideWide = baseWidth - peekingMiddleSpace * PEEKING_MULTIPLIER
 
         if (activeIndexRef.current === 0) {
@@ -1177,7 +1178,7 @@ const Carousel = React.forwardRef(
                       isAutoPlayEnabled,
                       viewport,
                       maxWidth,
-                      viewportWidth: currentViewportWidth
+                      containerWidth: containerLayout.width
                     })
                   ]}
                 >
@@ -1205,7 +1206,7 @@ const Carousel = React.forwardRef(
                     isAutoPlayEnabled,
                     viewport,
                     maxWidth,
-                    currentViewportWidth
+                    containerLayout.width
                   )}
                   testID="previous-button-container"
                 >
@@ -1303,7 +1304,7 @@ const Carousel = React.forwardRef(
                     isAutoPlayEnabled,
                     viewport,
                     maxWidth,
-                    currentViewportWidth
+                    containerLayout.width
                   )}
                   testID="next-button-container"
                 >

package/src/Carousel/CarouselItem/CarouselItem.jsx

@@ -31,10 +31,10 @@ const selectContainerStyle = ({
 
   if (enablePeeking) {
     const isFirst = elementIndex === 0
-    const baseWidth = maxWidth || width
-    adjustedWidth = baseWidth - peekingMiddleSpace * 2
+    const clampedMaxWidth = Math.min(maxWidth || width, width)
+    adjustedWidth = clampedMaxWidth - peekingMiddleSpace * 2
     if (isFirst) {
-      marginLeft = peekingMiddleSpace + (viewportWidth - maxWidth) / 2
+      marginLeft = peekingMiddleSpace + (viewportWidth - clampedMaxWidth) / 2
     } else {
       marginLeft = peekingGap
     }

package/src/ExpandCollapse/Control.jsx

@@ -50,7 +50,7 @@ function selectIconContainerStyles({ iconGap, iconPaddingTop, iconPosition }) {
   const paddingSide = iconPosition === 'right' ? 'paddingLeft' : 'paddingRight'
   return {
     [paddingSide]: iconGap,
-    paddingTop: iconPaddingTop
+    ...(iconPaddingTop && { transform: [{ translateY: iconPaddingTop }] })
   }
 }
 

package/src/ExpandCollapse/ExpandCollapse.jsx

@@ -20,13 +20,14 @@ const [selectProps, selectedSystemPropTypes] = selectSystemProps([
   contentfulProps
 ])
 
-function selectBorderStyles(tokens) {
-  return {
-    borderBottomWidth: tokens.borderWidth,
-    borderBottomStyle: tokens.borderStyle,
-    borderBottomColor: tokens.borderColor
-  }
-}
+const selectWrapperStyles = ({ borderWidth, borderTopWidth, borderStyle, borderColor }) => ({
+  borderStyle,
+  borderColor,
+  borderTopWidth,
+  borderBottomWidth: borderWidth,
+  borderBottomStyle: borderStyle,
+  borderBottomColor: borderColor
+})
 
 /**
  * Flexible base component for lists where some or all items are collapsible headers.
@@ -55,7 +56,7 @@ const ExpandCollapse = React.forwardRef(
 
     return (
       <View style={staticStyles.container} ref={ref} {...selectProps(rest)} dataSet={dataSet}>
-        <View style={selectBorderStyles(themeTokens)}>
+        <View style={selectWrapperStyles(themeTokens)}>
           {typeof children === 'function'
             ? children({ openIds, onToggle, resetValues, setValues, unsetValues, instanceId })
             : children}

package/src/ExpandCollapse/Panel.jsx

@@ -96,6 +96,7 @@ const ExpandCollapsePanel = React.forwardRef(
       controlRef,
       content,
       copy = 'en',
+      disableMobileScrollBuffer = false,
       ...rest
     },
     ref
@@ -118,7 +119,10 @@ const ExpandCollapsePanel = React.forwardRef(
 
     // on mobile devices we require a scroll buffer equal to the font size
     // to avoid triggering scrolling unnecessarily
-    const mobileScrollBuffer = Platform.OS === 'web' ? 0 : selectTextStyles(themeTokens)?.fontSize
+    const mobileScrollBuffer =
+      Platform.OS === 'web' || disableMobileScrollBuffer
+        ? 0
+        : selectTextStyles(themeTokens)?.fontSize
 
     const handleControlPress = (event) => {
       onToggle?.(panelId, event)
@@ -287,7 +291,11 @@ ExpandCollapsePanel.propTypes = {
   /**
    * A boolean prop to determine if the panel is a content panel or not. If true, the panel will not have a control
    */
-  content: PropTypes.bool
+  content: PropTypes.bool,
+  /**
+   * A boolean prop to disable the extra scroll buffer on mobile devices (only applicable on iOS/Android, ignored on web)
+   */
+  disableMobileScrollBuffer: PropTypes.bool
 }
 
 export default ExpandCollapsePanel

package/src/IconButton/IconButton.jsx

@@ -92,34 +92,46 @@ const selectInnerStyle = (
     height
   },
   password
-) => ({
-  // Inner borders animate with the icon and should be treated like a themable feature of the icon
-  borderColor,
-  borderRadius,
-  borderWidth,
-  borderTopLeftRadius,
-  borderTopRightRadius,
-  borderBottomLeftRadius,
-  borderBottomRightRadius,
-  borderTopWidth,
-  borderRightWidth,
-  borderBottomWidth,
-  borderLeftWidth,
-  padding: calculatePadding(padding, borderWidth),
-  paddingLeft: calculatePadding(paddingLeft, borderLeftWidth),
-  paddingRight: calculatePadding(paddingRight, borderRightWidth),
-  paddingTop: calculatePadding(paddingTop, borderTopWidth),
-  paddingBottom: calculatePadding(paddingBottom, borderBottomWidth),
-  ...Platform.select({
-    web: {
-      pointerEvents: 'none',
-      display: 'inline-flex',
-      alignItems: 'center',
-      justifyContent: 'center'
-    }
-  }),
-  ...getPasswordDimensions(password, width, height)
-})
+) => {
+  const basePadding = calculatePadding(padding, borderWidth)
+
+  const calculateSpecificPadding = (specificPadding, specificBorderWidth) => {
+    const calculated = calculatePadding(
+      specificPadding ?? padding,
+      specificBorderWidth ?? borderWidth
+    )
+    return calculated !== basePadding && calculated !== undefined ? calculated : undefined
+  }
+
+  return {
+    // Inner borders animate with the icon and should be treated like a themable feature of the icon
+    borderColor,
+    borderRadius,
+    borderWidth,
+    borderTopLeftRadius,
+    borderTopRightRadius,
+    borderBottomLeftRadius,
+    borderBottomRightRadius,
+    borderTopWidth,
+    borderRightWidth,
+    borderBottomWidth,
+    borderLeftWidth,
+    padding: basePadding,
+    paddingLeft: calculateSpecificPadding(paddingLeft, borderLeftWidth),
+    paddingRight: calculateSpecificPadding(paddingRight, borderRightWidth),
+    paddingTop: calculateSpecificPadding(paddingTop, borderTopWidth),
+    paddingBottom: calculateSpecificPadding(paddingBottom, borderBottomWidth),
+    ...Platform.select({
+      web: {
+        pointerEvents: 'none',
+        display: 'inline-flex',
+        alignItems: 'center',
+        justifyContent: 'center'
+      }
+    }),
+    ...getPasswordDimensions(password, width, height)
+  }
+}
 
 /**
  * A pressable themeless base component that handles pressable states and passes tokens

package/src/Modal/Modal.jsx

@@ -68,9 +68,10 @@ const selectModalStyles = ({
   ...applyShadowToken(shadow)
 })
 
-const selectBackdropStyles = ({ backdropColor, backdropOpacity }) => ({
+const selectBackdropStyles = ({ backdropColor, backdropOpacity, backdropCursor }) => ({
   backgroundColor: backdropColor,
-  opacity: backdropOpacity
+  opacity: backdropOpacity,
+  ...(Platform.OS === 'web' && backdropCursor ? { cursor: backdropCursor } : {})
 })
 
 const selectCloseButtonContainerStyles = ({ paddingRight, paddingTop }) => ({
@@ -119,12 +120,20 @@ const Modal = React.forwardRef(
       cancelButtonText,
       cancelButtonType,
       footer,
+      backgroundDismissible = true,
       ...rest
     },
     ref
   ) => {
     const viewport = useViewport()
-    const themeTokens = useThemeTokens('Modal', tokens, variant, { viewport, maxWidth })
+
+    const isBackdropClickable = onClose && backgroundDismissible
+
+    const themeTokens = useThemeTokens('Modal', tokens, variant, {
+      viewport,
+      maxWidth,
+      backdropCursor: isBackdropClickable ? 'pointer' : 'default'
+    })
     const modalRef = useScrollBlocking(isOpen)
     const modalBodyRef = React.useRef(ref)
     const modalContentRef = React.useRef(null)
@@ -253,7 +262,7 @@ const Modal = React.forwardRef(
           </View>
           {/* when a modal becomes open its first focusable element is being automatically focused */}
           {/* and we prefer the close button over backdrop */}
-          <TouchableWithoutFeedback onPress={handleClose}>
+          <TouchableWithoutFeedback onPress={isBackdropClickable && handleClose}>
             <View style={[staticStyles.backdrop, selectBackdropStyles(themeTokens)]} />
           </TouchableWithoutFeedback>
         </ScrollView>
@@ -349,7 +358,15 @@ Modal.propTypes = {
   /**
    * Receive a react node or an array of nodes to render at the bottom of the modal, above the action buttons.
    */
-  footer: PropTypes.oneOfType([PropTypes.node, PropTypes.arrayOf(PropTypes.node)])
+  footer: PropTypes.oneOfType([PropTypes.node, PropTypes.arrayOf(PropTypes.node)]),
+  /**
+   * Controls whether the modal can be dismissed by clicking on the backdrop.
+   * When set to `false`, clicking the backdrop will not close the modal.
+   * The backdrop cursor automatically changes to 'default' to indicate it's not clickable.
+   * Note: Backdrop dismissal requires `onClose` to be defined.
+   * @default true
+   */
+  backgroundDismissible: PropTypes.bool
 }
 
 export default Modal
@@ -361,12 +378,7 @@ const staticStyles = StyleSheet.create({
     left: 0,
     right: 0,
     bottom: 0,
-    zIndex: -1,
-    ...Platform.select({
-      web: {
-        cursor: 'pointer'
-      }
-    })
+    zIndex: -1
   },
   positioningContainer: {
     flexBasis: '100%',

package/src/MultiSelectFilter/MultiSelectFilter.jsx

@@ -185,6 +185,12 @@ const MultiSelectFilter = React.forwardRef(
 
     React.useEffect(() => setCheckedIds(currentValues ?? []), [currentValues])
 
+    React.useEffect(() => {
+      if (isOpen && onOpen) {
+        onOpen()
+      }
+    }, [isOpen, onOpen])
+
     const uniqueFields = ['id', 'label']
     if (!containUniqueFields(items, uniqueFields)) {
       throw new Error(`MultiSelectFilter items must have unique ${uniqueFields.join(', ')}`)
@@ -194,7 +200,6 @@ const MultiSelectFilter = React.forwardRef(
 
     const handleChange = (event) => {
       if (pressHandlers.onPress) pressHandlers?.onPress(event)
-      if (isOpen) onOpen()
       setIsOpen(!isOpen)
     }
 

package/src/Progress/Progress.jsx

@@ -4,6 +4,7 @@ import { View, StyleSheet } from 'react-native'
 
 import { applyShadowToken, useThemeTokens } from '../ThemeProvider'
 import { a11yProps, getTokensPropType, selectSystemProps, variantProp, viewProps } from '../utils'
+import ProgressContext from './ProgressContext'
 
 const [selectProps, selectedSystemPropTypes] = selectSystemProps([a11yProps, viewProps])
 
@@ -45,6 +46,12 @@ const selectProgressStyles = ({
  *
  * - Use the `size` variant to control the height of your progress bars:  passing `'mini'` will make your
  *   progress bar container narrower.
+ * - Use the `layers` variant to control how multiple progress bars are positioned:
+ *   - `false` (default): bars are positioned vertically one below the other.
+ *   - `true`: bars overlay on top of each other (layered/stacked on z-axis).
+ *   Note: The `layers` prop is deprecated. After August 2026, `layers: true` will become the permanent
+ *   default behavior and the `layers` prop will be removed. To maintain vertical layout after removal,
+ *   use separate individual Progress components.
  *
  * ## Usability and A11y guidelines
  *
@@ -55,15 +62,19 @@ const selectProgressStyles = ({
  */
 const Progress = React.forwardRef(({ children, tokens, variant, ...rest }, ref) => {
   const themeTokens = useThemeTokens('Progress', tokens, variant)
+  // Default to false (vertical layout) to preserve existing behavior and avoid breaking changes
+  const layers = variant?.layers ?? false
 
   return (
-    <View
-      ref={ref}
-      style={[staticStyles.progressContainer, selectProgressStyles(themeTokens)]}
-      {...selectProps(rest)}
-    >
-      {children}
-    </View>
+    <ProgressContext.Provider value={{ layers }}>
+      <View
+        ref={ref}
+        style={[staticStyles.progressContainer, selectProgressStyles(themeTokens)]}
+        {...selectProps(rest)}
+      >
+        {children}
+      </View>
+    </ProgressContext.Provider>
   )
 })
 Progress.displayName = 'Progress'