@telus-uds/components-base 3.18.0 → 3.20.0

package/lib/esm/Spacer/Spacer.js

@@ -1,8 +1,10 @@
 import React from 'react';
 import PropTypes from 'prop-types';
-import StyleSheet from "react-native-web/dist/exports/StyleSheet";
 import View from "react-native-web/dist/exports/View";
-import { a11yProps, selectSystemProps, spacingProps, useSpacingScale, viewProps } from '../utils';
+import StyleSheet from "react-native-web/dist/exports/StyleSheet";
+import { a11yProps, selectSystemProps, spacingProps, useSpacingScale, viewProps, StyleSheet as StyleSheetUtils, createMediaQueryStyles } from '../utils';
+import useMediaQuerySpacing from '../utils/useMediaQuerySpacing';
+import useTheme from '../ThemeProvider/useTheme';
 
 /**
  * @typedef {import('../utils/props/spacingProps.js').SpacingValue} SpacingValue
@@ -60,13 +62,66 @@ const Spacer = /*#__PURE__*/React.forwardRef((_ref, ref) => {
   let {
     space = 1,
     direction = 'column',
+    dataSet,
     ...rest
   } = _ref;
-  const size = useSpacingScale(space);
-  const sizeStyle = selectSizeStyle(size, direction);
+  const {
+    themeOptions: {
+      enableMediaQueryStyleSheet
+    }
+  } = useTheme();
+  const {
+    sizeByViewport
+  } = useMediaQuerySpacing(space);
+  const fallbackSize = useSpacingScale(space);
+  const sizeStyle = selectSizeStyle(fallbackSize, direction);
+  let spacerStyles;
+  let dataSetValue = dataSet;
+  if (enableMediaQueryStyleSheet) {
+    const sizeKey = direction === 'row' ? 'width' : 'height';
+    const stylesByViewport = {
+      xs: {
+        [sizeKey]: sizeByViewport.xs,
+        ...staticStyles.stretch
+      },
+      sm: {
+        [sizeKey]: sizeByViewport.sm,
+        ...staticStyles.stretch
+      },
+      md: {
+        [sizeKey]: sizeByViewport.md,
+        ...staticStyles.stretch
+      },
+      lg: {
+        [sizeKey]: sizeByViewport.lg,
+        ...staticStyles.stretch
+      },
+      xl: {
+        [sizeKey]: sizeByViewport.xl,
+        ...staticStyles.stretch
+      }
+    };
+    const mediaQueryStyles = createMediaQueryStyles(stylesByViewport);
+    const {
+      ids,
+      styles
+    } = StyleSheetUtils.create({
+      spacer: {
+        ...mediaQueryStyles
+      }
+    });
+    spacerStyles = styles.spacer;
+    dataSetValue = {
+      media: ids.spacer,
+      ...dataSet
+    };
+  } else {
+    spacerStyles = [staticStyles.stretch, sizeStyle];
+  }
   return /*#__PURE__*/_jsx(View, {
     ref: ref,
-    style: [staticStyles.stretch, sizeStyle],
+    style: spacerStyles,
+    dataSet: dataSetValue,
     ...selectProps(rest)
   });
 });
@@ -85,7 +140,12 @@ Spacer.propTypes = {
    * - `'column'` (default) applies space vertically; has a fixed height and not width.
    * - `'row'` applies space horizontally; has a fixed width and not height.
    */
-  direction: PropTypes.oneOf(['column', 'row'])
+  direction: PropTypes.oneOf(['column', 'row']),
+  /**
+   * Data attributes to be applied to the element. When media query stylesheet is enabled,
+   * this will include media query IDs for responsive styling.
+   */
+  dataSet: PropTypes.object
 };
 const staticStyles = StyleSheet.create({
   stretch: {

package/lib/esm/StepTracker/Step.js

@@ -150,6 +150,13 @@ const getStepTestID = (isCompleted, isCurrent) => {
   }
   return testID;
 };
+const selectBarContainerStyles = (themeTokens, isCompleted, isCurrent) => ({
+  backgroundColor: isCompleted ? themeTokens.barCompletedBackgroundColor : themeTokens.barBackgroundColor,
+  height: themeTokens.barHeight,
+  ...(isCurrent && {
+    backgroundColor: themeTokens.barCurrentBackgroundColor
+  })
+});
 
 /**
  * A single step of a StepTracker.
@@ -162,6 +169,7 @@ const Step = /*#__PURE__*/React.forwardRef((_ref8, ref) => {
     stepCount = 0,
     stepIndex = 0,
     tokens,
+    isBarVariant,
     ...rest
   } = _ref8;
   const {
@@ -190,7 +198,10 @@ const Step = /*#__PURE__*/React.forwardRef((_ref8, ref) => {
     accessibilityCurrent: status === stepIndex,
     ref: ref,
     ...selectProps(rest),
-    children: [/*#__PURE__*/_jsxs(StackView, {
+    children: [isBarVariant && /*#__PURE__*/_jsx(View, {
+      style: selectBarContainerStyles(themeTokens, isCompleted, isCurrent),
+      testID: getStepTestID(isCompleted, isCurrent)
+    }), !isBarVariant && /*#__PURE__*/_jsxs(StackView, {
       direction: "row",
       space: 0,
       tokens: {

package/lib/esm/StepTracker/StepTracker.js

@@ -12,6 +12,7 @@ import useCopy from '../utils/useCopy';
 import Step from './Step';
 import defaultDictionary from './dictionary';
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+const STYLE_BAR_VARIANT = 'bar';
 const [selectProps, selectedSystemPropTypes] = selectSystemProps([a11yProps, viewProps]);
 const selectContainerStyles = _ref => {
   let {
@@ -52,6 +53,14 @@ const selectStepTrackerLabelStyles = (_ref3, themeOptions) => {
     themeOptions
   });
 };
+const selectStepsContainerStyles = _ref4 => {
+  let {
+    barGap
+  } = _ref4;
+  return {
+    gap: barGap
+  };
+};
 
 /**
  * StepTracker component shows the current position in a sequence of steps.
@@ -85,7 +94,7 @@ const selectStepTrackerLabelStyles = (_ref3, themeOptions) => {
  * - `accessibilityValue.text` (`aria-valuetext`): `<Current Step Label>`,
  *
  */
-const StepTracker = /*#__PURE__*/React.forwardRef((_ref4, ref) => {
+const StepTracker = /*#__PURE__*/React.forwardRef((_ref5, ref) => {
   let {
     current = 0,
     copy = 'en',
@@ -94,7 +103,8 @@ const StepTracker = /*#__PURE__*/React.forwardRef((_ref4, ref) => {
     tokens,
     variant,
     ...rest
-  } = _ref4;
+  } = _ref5;
+  const isBarVariant = variant?.style === STYLE_BAR_VARIANT;
   const viewport = useViewport();
   const {
     showStepTrackerLabel,
@@ -140,7 +150,7 @@ const StepTracker = /*#__PURE__*/React.forwardRef((_ref4, ref) => {
     children: /*#__PURE__*/_jsxs(StackView, {
       space: 0,
       children: [/*#__PURE__*/_jsx(View, {
-        style: staticStyles.stepsContainer,
+        style: [staticStyles.stepsContainer, selectStepsContainerStyles(themeTokens)],
         accessibilityRole: stepsContainerAccessibilityRole,
         children: steps.map((label, index) => {
           return /*#__PURE__*/_jsx(Step, {
@@ -151,7 +161,8 @@ const StepTracker = /*#__PURE__*/React.forwardRef((_ref4, ref) => {
             stepCount: steps.length,
             tokens: themeTokens,
             accessibilityRole: stepAccessibilityRole,
-            accessibilityCurrent: current === index && Platform.OS === 'web' && 'step'
+            accessibilityCurrent: current === index && Platform.OS === 'web' && 'step',
+            isBarVariant: isBarVariant
           }, label);
         })
       }), showStepTrackerLabel && /*#__PURE__*/_jsx(View, {

package/lib/esm/TabBar/TabBar.js

@@ -84,7 +84,8 @@ const TabBar = /*#__PURE__*/React.forwardRef((_ref3, ref) => {
         iconActive: item.iconActive,
         onPress: () => handlePress(item.id),
         id: `tab-item-${index}`,
-        accessibilityRole: "tablist"
+        accessibilityRole: "tablist",
+        tokens: item.tokens
       }, item.id))
     })
   });
@@ -98,7 +99,8 @@ TabBar.propTypes = {
     icon: PropTypes.node,
     iconActive: PropTypes.node,
     label: PropTypes.string.isRequired,
-    href: PropTypes.string
+    href: PropTypes.string,
+    tokens: getTokensPropType('TabBarItem')
   })).isRequired,
   /** Id of the initially selected item. */
   initiallySelectedItem: PropTypes.number,

package/lib/esm/TabBar/index.js

@@ -1,2 +1,4 @@
 import TabBar from './TabBar';
+import TabBarItem from './TabBarItem';
+TabBar.Item = TabBarItem;
 export default TabBar;

package/lib/esm/Tooltip/Backdrop.js

@@ -14,7 +14,7 @@ function createPortalNode(nodeId) {
   left: ${window.scrollX}px; 
   right: 0; 
   bottom: 0; 
-  z-index: 9999; 
+  z-index: 100000; 
   pointer-events: none;
   `;
   document.body.appendChild(node);

package/lib/esm/utils/index.js

@@ -9,6 +9,7 @@ export { default as info } from './info';
 export { default as useCopy } from './useCopy';
 export { default as useHash } from './useHash';
 export { default as useSpacingScale } from './useSpacingScale';
+export { default as useMediaQuerySpacing } from './useMediaQuerySpacing';
 export { default as useResponsiveProp } from './useResponsiveProp';
 export { default as useOverlaidPosition } from './useOverlaidPosition';
 export { default as useSafeLayoutEffect } from './useSafeLayoutEffect';
@@ -24,4 +25,5 @@ export { transformGradient } from './transformGradient';
 export { default as convertFromMegaByteToByte } from './convertFromMegaByteToByte';
 export { default as formatImageSource } from './formatImageSource';
 export { default as getSpacingScale } from './getSpacingScale';
-export { default as useVariants } from './useVariants';
+export { default as useVariants } from './useVariants';
+export { default as isTouchDevice } from './isTouchDevice';

package/lib/esm/utils/isTouchDevice.js

@@ -0,0 +1,27 @@
+import Platform from "react-native-web/dist/exports/Platform";
+/**
+ * Determines if the current device supports touch interactions
+ *
+ * @returns {boolean} True if the device supports touch, false otherwise
+ */
+const isTouchDevice = () => {
+  if (Platform.OS !== 'web') {
+    return true;
+  }
+  if (typeof window !== 'undefined') {
+    if ('ontouchstart' in window) {
+      return true;
+    }
+    if (window.navigator && window.navigator.maxTouchPoints > 0) {
+      return true;
+    }
+    if (window.navigator && window.navigator.msMaxTouchPoints > 0) {
+      return true;
+    }
+    if (window.matchMedia && window.matchMedia('(pointer: coarse)').matches) {
+      return true;
+    }
+  }
+  return false;
+};
+export default isTouchDevice;

package/lib/esm/utils/useMediaQuerySpacing.js

@@ -0,0 +1,116 @@
+import { useThemeTokens } from '../ThemeProvider';
+import { resolveResponsiveProp } from './useResponsiveProp';
+
+/**
+ * @typedef {import('@telus-uds/system-constants/viewports').Viewport} Viewport
+ * @typedef {import('./props/spacingProps.js').SpacingValue} SpacingValue
+ * @typedef {import('./props/spacingProps.js').SpacingIndex} SpacingIndex
+ * @typedef {import('./props/spacingProps.js').SpacingObject} SpacingObject
+ */
+
+/**
+ * A utility hook that simplifies implementing media query-based responsive spacing.
+ *
+ * This hook handles the complexity of:
+ * - Detecting if a space value is responsive (has viewport keys)
+ * - Fetching theme tokens for each viewport
+ * - Resolving the correct space index for each viewport
+ * - Extracting actual pixel values from theme tokens
+ *
+ * ## Usage
+ *
+ * ```jsx
+ * const { sizeByViewport } = useMediaQuerySpacing(space, 'spacingScale')
+ *
+ * // Use sizeByViewport to create media query styles
+ * const stylesByViewport = {
+ *   xs: { padding: sizeByViewport.xs },
+ *   sm: { padding: sizeByViewport.sm },
+ *   md: { padding: sizeByViewport.md },
+ *   lg: { padding: sizeByViewport.lg },
+ *   xl: { padding: sizeByViewport.xl }
+ * }
+ * const mediaQueryStyles = createMediaQueryStyles(stylesByViewport)
+ * ```
+ *
+ * ## Parameters
+ *
+ * @param {SpacingValue} spaceValue - A spacing value (number or responsive object with viewport keys)
+ * @param {string} tokenKey - The theme token key to use (e.g., 'spacingScale', 'Typography')
+ * @param {object} [tokens={}] - Additional tokens to pass to useThemeTokens
+ * @param {object} [variant={}] - Variant to pass to useThemeTokens
+ *
+ * ## Returns
+ *
+ * @returns {{
+ *   spaceIndexByViewport: { xs: number, sm: number, md: number, lg: number, xl: number },
+ *   sizeByViewport: { xs: number, sm: number, md: number, lg: number, xl: number },
+ *   tokensByViewport: { xs: object, sm: object, md: object, lg: object, xl: object }
+ * }}
+ *
+ * - `spaceIndexByViewport`: The resolved space index for each viewport
+ * - `sizeByViewport`: The actual pixel/number values for each viewport
+ * - `tokensByViewport`: The full theme tokens for each viewport (for advanced use cases)
+ */
+const useMediaQuerySpacing = function (spaceValue) {
+  let tokenKey = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : 'spacingScale';
+  let tokens = arguments.length > 2 && arguments[2] !== undefined ? arguments[2] : {};
+  let variant = arguments.length > 3 && arguments[3] !== undefined ? arguments[3] : {};
+  const isResponsive = typeof spaceValue === 'object' && spaceValue !== null && !spaceValue.space && !spaceValue.options;
+  const getSpaceIndex = viewport => {
+    if (isResponsive) {
+      return resolveResponsiveProp(spaceValue, viewport);
+    }
+    if (typeof spaceValue === 'number') {
+      return spaceValue;
+    }
+    return spaceValue?.space ?? 1;
+  };
+  const spaceIndexByViewport = {
+    xs: getSpaceIndex('xs'),
+    sm: getSpaceIndex('sm'),
+    md: getSpaceIndex('md'),
+    lg: getSpaceIndex('lg'),
+    xl: getSpaceIndex('xl')
+  };
+  const tokensXs = useThemeTokens(tokenKey, tokens, variant, {
+    space: spaceIndexByViewport.xs,
+    viewport: 'xs'
+  });
+  const tokensSm = useThemeTokens(tokenKey, tokens, variant, {
+    space: spaceIndexByViewport.sm,
+    viewport: 'sm'
+  });
+  const tokensMd = useThemeTokens(tokenKey, tokens, variant, {
+    space: spaceIndexByViewport.md,
+    viewport: 'md'
+  });
+  const tokensLg = useThemeTokens(tokenKey, tokens, variant, {
+    space: spaceIndexByViewport.lg,
+    viewport: 'lg'
+  });
+  const tokensXl = useThemeTokens(tokenKey, tokens, variant, {
+    space: spaceIndexByViewport.xl,
+    viewport: 'xl'
+  });
+  const sizeByViewport = {
+    xs: tokensXs.size ?? 0,
+    sm: tokensSm.size ?? 0,
+    md: tokensMd.size ?? 0,
+    lg: tokensLg.size ?? 0,
+    xl: tokensXl.size ?? 0
+  };
+  const tokensByViewport = {
+    xs: tokensXs,
+    sm: tokensSm,
+    md: tokensMd,
+    lg: tokensLg,
+    xl: tokensXl
+  };
+  return {
+    spaceIndexByViewport,
+    sizeByViewport,
+    tokensByViewport
+  };
+};
+export default useMediaQuerySpacing;

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.14.0",
+    "@telus-uds/system-theme-tokens": "^4.15.1",
     "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.18.0",
+  "version": "3.20.0",
   "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.14.0",
+    "@telus-uds/system-theme-tokens": "^4.15.1",
     "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.18.0",
+  "version": "3.20.0",
   "types": "types/index.d.ts"
 }

package/src/Box/Box.jsx

@@ -21,9 +21,10 @@ import {
   variantProp,
   viewProps,
   StyleSheet as RNMQStyleSheet,
-  getSpacingScale
+  getSpacingScale,
+  formatImageSource
 } from '../utils'
-import backgroundImageStylesMap from './backgroundImageStylesMap'
+import backgroundImageStylesMap, { backgroundPositions } from './backgroundImageStylesMap'
 import { useViewport } from '../ViewportProvider'
 
 const [selectProps, selectedSystemPropTypes] = selectSystemProps([a11yProps, viewProps])
@@ -87,38 +88,60 @@ const setBackgroundImage = ({
   backgroundImageResizeMode,
   backgroundImagePosition,
   backgroundImageAlign,
-  backgroundImageWidth,
-  backgroundImageHeight,
-  content
+  content,
+  testID
 }) => {
-  if (backgroundImageResizeMode === 'contain') {
-    const containedViewStyle = {
-      ...staticStyles.containedView,
-      width: backgroundImageWidth,
-      height: backgroundImageHeight,
-      ...backgroundImageStylesMap[`${backgroundImagePosition}-${backgroundImageAlign}`]
+  const backgroundImageTestID = testID ? `${testID}-background-image` : undefined
+
+  if (backgroundImageResizeMode === 'contain' && backgroundImagePosition && backgroundImageAlign) {
+    const positionKey = `${backgroundImagePosition}-${backgroundImageAlign}`
+
+    if (Platform.OS === 'web') {
+      const backgroundPosition = backgroundPositions[positionKey] || 'center center'
+
+      const backgroundImageStyle = {
+        backgroundImage: `url(${src})`,
+        backgroundSize: 'contain',
+        backgroundRepeat: 'no-repeat',
+        backgroundPosition
+      }
+
+      return (
+        <View
+          style={[staticStyles.imageBackground, backgroundImageStyle]}
+          aria-label={alt}
+          testID={backgroundImageTestID}
+        >
+          {content}
+        </View>
+      )
     }
+    const positionStyles = backgroundImageStylesMap[positionKey] || {}
 
     return (
-      <View style={staticStyles.containedContainer}>
-        <View style={containedViewStyle}>
-          <Image
-            source={{ uri: src }}
-            alt={alt}
-            style={staticStyles.containedImage}
-            accessibilityIgnoresInvertColors
-          />
-        </View>
-        {content}
+      <View style={staticStyles.containContainer}>
+        <Image
+          source={src}
+          resizeMode={backgroundImageResizeMode}
+          style={[staticStyles.containImage, positionStyles]}
+          accessible={true}
+          accessibilityLabel={alt}
+          accessibilityIgnoresInvertColors={true}
+          testID={backgroundImageTestID}
+        />
+        <View style={staticStyles.contentOverlay}>{content}</View>
       </View>
     )
   }
+
   return (
     <ImageBackground
-      source={{ uri: src }}
-      alt={alt}
-      style={staticStyles.backgroundImageContainer}
+      source={src}
       resizeMode={backgroundImageResizeMode}
+      style={staticStyles.imageBackground}
+      accessible={true}
+      accessibilityLabel={alt}
+      testID={backgroundImageTestID}
     >
       {content}
     </ImageBackground>
@@ -279,33 +302,47 @@ const Box = React.forwardRef(
 
     const { src = '', alt = '', resizeMode = '', position = '', align = '' } = backgroundImage || {}
     const backgroundImageResizeMode = useResponsiveProp(resizeMode, 'cover')
-    const backgroundImagePosition = useResponsiveProp(position, 'none')
-    const backgroundImageAlign = useResponsiveProp(align, 'stretch')
-    const [backgroundImageWidth, setBackgroundImageWidth] = React.useState(0)
-    const [backgroundImageHeight, setBackgroundImageHeight] = React.useState(0)
-    if (backgroundImage)
+    const backgroundImagePosition = useResponsiveProp(position)
+    const backgroundImageAlign = useResponsiveProp(align)
+    const imageSourceViewport = formatImageSource(useResponsiveProp(src))
+
+    if (backgroundImage && src) {
+      const { paddingTop, paddingBottom, paddingLeft, paddingRight, ...containerStyle } = boxStyles
+
+      const hasPadding = paddingTop || paddingBottom || paddingLeft || paddingRight
+      const paddedContent = hasPadding ? (
+        <View style={{ paddingTop, paddingBottom, paddingLeft, paddingRight }}>{children}</View>
+      ) : (
+        children
+      )
+
       content = setBackgroundImage({
-        src,
+        src: imageSourceViewport,
         alt,
         backgroundImageResizeMode,
         backgroundImagePosition,
         backgroundImageAlign,
-        backgroundImageWidth,
-        backgroundImageHeight,
-        content
+        content: paddedContent,
+        testID
       })
 
-    React.useEffect(() => {
-      if (backgroundImage && backgroundImageWidth === 0 && backgroundImageHeight === 0) {
-        Image.getSize(src, (width, height) => {
-          // Only update the state if the size has changed
-          if (width !== backgroundImageWidth || height !== backgroundImageHeight) {
-            setBackgroundImageWidth(width)
-            setBackgroundImageHeight(height)
-          }
-        })
+      const dataSetValue = boxMediaIds ? { media: boxMediaIds, ...dataSet } : dataSet
+
+      if (scroll) {
+        const scrollProps = typeof scroll === 'object' ? scroll : {}
+        scrollProps.contentContainerStyle = [containerStyle, scrollProps.contentContainerStyle]
+        return (
+          <ScrollView {...scrollProps} {...props} testID={testID} dataSet={dataSetValue} ref={ref}>
+            {content}
+          </ScrollView>
+        )
       }
-    }, [backgroundImage, backgroundImageWidth, backgroundImageHeight, src])
+      return (
+        <View {...props} style={containerStyle} testID={testID} dataSet={dataSetValue} ref={ref}>
+          {content}
+        </View>
+      )
+    }
 
     const dataSetValue = boxMediaIds ? { media: boxMediaIds, ...dataSet } : dataSet
 
@@ -416,10 +453,12 @@ Box.propTypes = {
   */
   customGradient: PropTypes.func,
   /**
-   * Use this prop to add a background image to the box.
+   * Apply background image to the box.
    */
   backgroundImage: PropTypes.shape({
-    src: PropTypes.string.isRequired,
+    // The image src is either a URI string or a number (when a local image src is bundled in IOS or Android app)
+    // src is an object when used responsively to provide different image sources for different screen sizes
+    src: PropTypes.oneOfType([PropTypes.string, PropTypes.number, PropTypes.object]).isRequired,
     alt: PropTypes.string,
     resizeMode: responsiveProps.getTypeOptionallyByViewport(
       PropTypes.oneOf(['cover', 'contain', 'stretch', 'repeat', 'center'])
@@ -436,18 +475,21 @@ Box.propTypes = {
 export default Box
 
 const staticStyles = StyleSheet.create({
-  backgroundImageContainer: {
-    flex: 1
-  },
-  containedContainer: {
-    flex: 1,
-    overflow: 'hidden'
+  imageBackground: { width: '100%', height: '100%' },
+  contentOverlay: {
+    position: 'relative',
+    width: '100%',
+    height: '100%',
+    zIndex: 1
   },
-  containedView: {
-    zIndex: -1,
-    position: 'absolute'
+  containContainer: {
+    width: '100%',
+    height: '100%',
+    overflow: 'hidden',
+    position: 'relative'
   },
-  containedImage: {
+  containImage: {
+    position: 'absolute',
     width: '100%',
     height: '100%'
   }