@telus-uds/components-base 3.5.2 → 3.7.0

package/lib/esm/utils/props/inputSupportsProps.js

@@ -1,4 +1,5 @@
 import PropTypes from 'prop-types';
+import tooltipPropTypes from '../../Tooltip/shared';
 export default {
   types: {
     /**
@@ -31,9 +32,12 @@ export default {
      */
     feedbackProps: PropTypes.object,
     /**
-     * Content of an optional `Tooltip`. If set, a tooltip button will be shown next to the label.
+     * an optional `Tooltip`. If set, tooltip will be shown next to the label.
+     * Props can be passed to the tooltip in one of the following ways.
+     * 1. `tooltip` as a string - The content of the tooltip.
+     * 2. `tooltip` as an object - Tooltip component props to be passed.
      */
-    tooltip: PropTypes.string,
+    tooltip: PropTypes.oneOfType([tooltipPropTypes, PropTypes.string]),
     /**
      * Use to visually mark an input as valid or invalid.
      */

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.3.0",
+    "@telus-uds/system-theme-tokens": "^4.5.0",
     "airbnb-prop-types": "^2.16.0",
     "css-mediaquery": "^0.1.2",
     "expo-document-picker": "^13.0.1",
@@ -56,8 +56,8 @@
   "module": "lib/esm/index.js",
   "name": "@telus-uds/components-base",
   "peerDependencies": {
-    "react": "^18.2.0",
-    "react-dom": "^18.2.0",
+    "react": ">=18.2.0 <19.0.0",
+    "react-dom": ">=18.2.0 <19.0.0",
     "react-native": "^0.74.5",
     "react-native-web": "^0.19.10",
     "react-native-svg": "15.7.1"
@@ -84,6 +84,6 @@
   "standard-engine": {
     "skip": true
   },
-  "version": "3.5.2",
+  "version": "3.7.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.3.0",
+    "@telus-uds/system-theme-tokens": "^4.5.0",
     "airbnb-prop-types": "^2.16.0",
     "css-mediaquery": "^0.1.2",
     "expo-document-picker": "^13.0.1",
@@ -56,8 +56,8 @@
   "module": "lib/esm/index.js",
   "name": "@telus-uds/components-base",
   "peerDependencies": {
-    "react": "^18.2.0",
-    "react-dom": "^18.2.0",
+    "react": ">=18.2.0 <19.0.0",
+    "react-dom": ">=18.2.0 <19.0.0",
     "react-native": "^0.74.5",
     "react-native-web": "^0.19.10",
     "react-native-svg": "15.7.1"
@@ -84,6 +84,6 @@
   "standard-engine": {
     "skip": true
   },
-  "version": "3.5.2",
+  "version": "3.7.0",
   "types": "types/index.d.ts"
 }

package/src/Box/Box.jsx

@@ -1,9 +1,15 @@
 import React from 'react'
 import PropTypes from 'prop-types'
 import { View, ScrollView, Platform, StyleSheet, ImageBackground, Image } from 'react-native'
-import { useThemeTokens } from '../ThemeProvider'
+import {
+  useTheme,
+  useThemeTokens,
+  useResponsiveThemeTokens,
+  useThemeTokensCallback
+} from '../ThemeProvider'
 import {
   a11yProps,
+  createMediaQueryStyles,
   getA11yPropsFromHtmlTag,
   getTokensPropType,
   layoutTags,
@@ -13,9 +19,12 @@ import {
   useResponsiveProp,
   useSpacingScale,
   variantProp,
-  viewProps
+  viewProps,
+  StyleSheet as RNMQStyleSheet,
+  getSpacingScale
 } from '../utils'
 import backgroundImageStylesMap from './backgroundImageStylesMap'
+import { useViewport } from '../ViewportProvider'
 
 const [selectProps, selectedSystemPropTypes] = selectSystemProps([a11yProps, viewProps])
 
@@ -212,8 +221,20 @@ const Box = React.forwardRef(
       ...selectProps(rest)
     }
 
-    const themeTokens = useThemeTokens('Box', tokens, variant)
-    const styles = {
+    const viewport = useViewport()
+    const { themeOptions } = useTheme()
+    const { enableMediaQueryStyleSheet } = themeOptions
+
+    const useTokens = enableMediaQueryStyleSheet ? useResponsiveThemeTokens : useThemeTokens
+    const themeTokens = useTokens(
+      'Box',
+      tokens,
+      variant,
+      !enableMediaQueryStyleSheet && { viewport }
+    )
+    const getSpacingTokens = useThemeTokensCallback('spacingScale')
+
+    let boxStyles = {
       flex,
       paddingLeft: useSpacingScale(left),
       paddingRight: useSpacingScale(right),
@@ -221,10 +242,40 @@ const Box = React.forwardRef(
       paddingBottom: useSpacingScale(bottom),
       ...selectBoxStyles(themeTokens, customGradient)
     }
+    let boxMediaIds
+
+    if (enableMediaQueryStyleSheet) {
+      const { transformedThemeTokens } = Object.entries(themeTokens).reduce(
+        (acc, [vp]) => {
+          acc.transformedThemeTokens[vp] = {
+            paddingLeft: getSpacingScale(left, vp, getSpacingTokens),
+            paddingRight: getSpacingScale(right, vp, getSpacingTokens),
+            paddingTop: getSpacingScale(top, vp, getSpacingTokens),
+            paddingBottom: getSpacingScale(bottom, vp, getSpacingTokens)
+          }
+          return acc
+        },
+        {
+          transformedThemeTokens: {}
+        }
+      )
+
+      const mediaQueryStyles = createMediaQueryStyles(transformedThemeTokens)
+      const { ids } = RNMQStyleSheet.create({
+        box: {
+          ...mediaQueryStyles
+        }
+      })
+      boxStyles = {
+        flex,
+        ...selectBoxStyles(themeTokens[viewport], customGradient)
+      }
+      boxMediaIds = ids.box
+    }
 
     let content = children
     if (typeof customGradient === 'function')
-      content = customGradient(styles.colors, styles)(children)
+      content = customGradient(boxStyles.colors, boxStyles)(children)
 
     const { src = '', alt = '', resizeMode = '', position = '', align = '' } = backgroundImage || {}
     const backgroundImageResizeMode = useResponsiveProp(resizeMode, 'cover')
@@ -256,17 +307,19 @@ const Box = React.forwardRef(
       }
     }, [backgroundImage, backgroundImageWidth, backgroundImageHeight, src])
 
+    const dataSetValue = boxMediaIds ? { media: boxMediaIds, ...dataSet } : dataSet
+
     if (scroll) {
       const scrollProps = typeof scroll === 'object' ? scroll : {}
-      scrollProps.contentContainerStyle = [styles, scrollProps.contentContainerStyle]
+      scrollProps.contentContainerStyle = [boxStyles, scrollProps.contentContainerStyle]
       return (
-        <ScrollView {...scrollProps} {...props} testID={testID} dataSet={dataSet} ref={ref}>
+        <ScrollView {...scrollProps} {...props} testID={testID} dataSet={dataSetValue} ref={ref}>
           {content}
         </ScrollView>
       )
     }
     return (
-      <View {...props} style={styles} testID={testID} dataSet={dataSet} ref={ref}>
+      <View {...props} style={boxStyles} testID={testID} dataSet={dataSetValue} ref={ref}>
         {content}
       </View>
     )

package/src/Card/Card.jsx

@@ -9,7 +9,14 @@ import {
 } from '../ThemeProvider'
 import { getTokensPropType, variantProp, StyleSheet, createMediaQueryStyles } from '../utils'
 import { useViewport } from '../ViewportProvider'
-import { a11yProps, linkProps, selectSystemProps, viewProps, responsiveProps } from '../utils/props'
+import {
+  a11yProps,
+  linkProps,
+  selectSystemProps,
+  viewProps,
+  responsiveProps,
+  hrefAttrsProp
+} from '../utils/props'
 import CardBase from './CardBase'
 import PressableCardBase from './PressableCardBase'
 import CheckboxButton from '../Checkbox/CheckboxButton'
@@ -227,6 +234,8 @@ const Card = React.forwardRef(
                 tokens={getThemeTokens}
                 dataSet={dataSet}
                 onPress={onPress}
+                href={interactiveCard?.href}
+                hrefAttrs={interactiveCard?.hrefAttrs}
                 {...selectProps(rest)}
               >
                 {(cardState) => {
@@ -308,12 +317,16 @@ Card.propTypes = {
         - `radiogroup`
         - `checkbox`
    * - variant: The variant to be used for the interactive card
+   * - href: The href to be used for the interactive card
+   * - hrefAttrs: The href attributes to be used for the interactive card
    */
   interactiveCard: PropTypes.shape({
     body: PropTypes.oneOfType([PropTypes.node, PropTypes.func]),
     tokens: getTokensPropType('Card'),
     selectionType: PropTypes.oneOf(Object.values(SelectionType)),
-    variant: variantProp.propType
+    variant: variantProp.propType,
+    href: PropTypes.string,
+    hrefAttrs: PropTypes.shape(hrefAttrsProp.types)
   }),
   /**
    * Apply background image to the card.
@@ -326,7 +339,11 @@ Card.propTypes = {
     resizeMode: responsiveProps.getTypeOptionallyByViewport(
       PropTypes.oneOf(['cover', 'contain', 'stretch', 'repeat', 'center'])
     )
-  })
+  }),
+  /**
+   * Data set for the card.
+   */
+  dataSet: PropTypes.object
 }
 
 export default Card

package/src/Card/PressableCardBase.jsx

@@ -1,6 +1,6 @@
 import React from 'react'
 import PropTypes from 'prop-types'
-import { Pressable, Platform } from 'react-native'
+import { Pressable, Platform, View, StyleSheet } from 'react-native'
 
 import { useViewport } from '../ViewportProvider'
 import { applyOuterBorder, validateThemeTokens } from '../ThemeProvider'
@@ -118,7 +118,57 @@ const PressableCardBase = React.forwardRef(
     const handleChange = linkProps.handleHref({ href, onPress })
     const handleKeyDown = (event) => {
       // The expected keyboard shortcut for selecting a focused item is the Space key
-      if (event?.key === ' ') handleChange(event)
+      if (event?.key === ' ') handleChange?.(event)
+    }
+
+    const [hovered, setHovered] = React.useState(false)
+    const [focused, setFocused] = React.useState(false)
+    const [pressed, setPressed] = React.useState(false)
+
+    if (Platform.OS === 'web' && href) {
+      return (
+        <View
+          ref={ref}
+          style={getOuterBorderStyle({ pressed, focused, hovered })}
+          dataSet={dataSet}
+          onMouseEnter={() => setHovered(true)}
+          onMouseLeave={() => setHovered(false)}
+          {...selectProps({ ...rest, accessibilityRole })}
+        >
+          <a
+            href={href}
+            tabIndex={0}
+            onClick={(event) => {
+              setPressed(false)
+              handleChange?.(event)
+            }}
+            onKeyDown={(event) => {
+              if (event.key === ' ') {
+                setPressed(true)
+                handleKeyDown(event)
+              }
+            }}
+            onKeyUp={(event) => {
+              if (event.key === ' ') setPressed(false)
+            }}
+            onMouseDown={() => setPressed(true)}
+            onMouseUp={() => setPressed(false)}
+            onFocus={() => setFocused(true)}
+            onBlur={() => {
+              setFocused(false)
+              setPressed(false)
+            }}
+            style={staticStyles.container}
+            {...(hrefAttrs || {})}
+          >
+            <CardBase tokens={getCardTokens({ pressed, focused, hovered })}>
+              {typeof children === 'function'
+                ? children(getCardState({ pressed, focused, hovered }))
+                : children}
+            </CardBase>
+          </a>
+        </View>
+      )
     }
 
     return (
@@ -141,6 +191,14 @@ const PressableCardBase = React.forwardRef(
     )
   }
 )
+
+const staticStyles = StyleSheet.create({
+  container: {
+    flex: 1,
+    display: 'flex'
+  }
+})
+
 PressableCardBase.displayName = 'PressableCardBase'
 
 PressableCardBase.propTypes = {

package/src/ExpandCollapseMini/ExpandCollapseMini.jsx

@@ -2,6 +2,7 @@ import React from 'react'
 import PropTypes from 'prop-types'
 import ExpandCollapse from '../ExpandCollapse'
 import { getTokensPropType, selectSystemProps, contentfulProps } from '../utils'
+import { variantProp } from '../utils/props'
 import ExpandCollapseMiniControl from './ExpandCollapseMiniControl'
 
 const [selectContainerProps, selectedContainerPropTypes] = selectSystemProps([contentfulProps])
@@ -79,6 +80,10 @@ ExpandCollapseMini.propTypes = {
    * Optional variant object to override the default theme tokens
    */
   tokens: getTokensPropType('ExpandCollapseMini'),
+  /**
+   * ExpandCollapseMini variant.
+   */
+  variant: variantProp.propType,
   /**
    * The dataSet prop allows to pass data-* attributes element to the component.
    */

package/src/ExpandCollapseMini/ExpandCollapseMiniControl.jsx

@@ -15,13 +15,6 @@ const presentationOnly = {
   focusable: false // Stop RNW from setting tabIndex={0}: focus goes to Control only
 }
 
-const selectLinkTokens = ({ color, textLine, lineHeight, fontSize }) => ({
-  color,
-  textLine,
-  blockLineHeight: lineHeight,
-  blockFontSize: fontSize
-})
-
 const ExpandCollapseMiniControl = React.forwardRef(
   (
     {
@@ -35,20 +28,24 @@ const ExpandCollapseMiniControl = React.forwardRef(
     },
     ref
   ) => {
-    const { expanded, hover, focus } = pressableState || {}
-    // we only want focus outline when focusing, if user is pressing we don't want the border.
-    const { outerBorderColor } = useThemeTokens(
+    const { expanded, hover, focus, pressed } = pressableState || {}
+    const { quiet } = variant
+    const isFocusVisible = Platform.OS === 'web' ? focus && !pressed && !hover : expanded
+
+    const linkTokens = useThemeTokens(
       'Link',
       {},
-      {},
-      { focus: Platform.OS !== 'web' ? expanded : focus }
-    )
-    const { size, icon, ...themeTokens } = useThemeTokens(
-      'ExpandCollapseMiniControl',
-      tokens,
-      variant,
-      { expanded, focus }
+      { ...variant, quiet: expanded ?? quiet },
+      {
+        focus: isFocusVisible,
+        hover,
+        pressed
+      }
     )
+    const { size, icon } = useThemeTokens('ExpandCollapseMiniControl', tokens, variant, {
+      expanded,
+      focus
+    })
 
     // Choose hover styles when any part of Control is hoverred
     const appearance = { ...variant, hover }
@@ -75,9 +72,8 @@ const ExpandCollapseMiniControl = React.forwardRef(
         icon={icon}
         iconPosition={iconPosition}
         tokens={(linkState) => ({
-          ...getTokens(linkState),
-          ...selectLinkTokens(themeTokens),
-          outerBorderColor
+          ...linkTokens,
+          ...getTokens(linkState)
         })}
         ref={ref}
         {...presentationOnly}

package/src/Icon/Icon.jsx

@@ -24,7 +24,12 @@ const Icon = React.forwardRef(
     const size = scalesWithText ? themeTokens.size * fontScale : themeTokens.size
 
     const iconContent = (
-      <IconComponent title={accessibilityLabel} size={size} color={themeTokens.color} />
+      <IconComponent
+        title={accessibilityLabel}
+        size={size}
+        color={themeTokens.color}
+        gradient={themeTokens.gradient}
+      />
     )
 
     const paddingStyles = variant?.padding

package/src/InputLabel/InputLabel.jsx

@@ -14,6 +14,7 @@ import {
 
 import LabelContent from './LabelContent'
 import Tooltip from '../Tooltip'
+import tooltipPropTypes from '../Tooltip/shared'
 
 const [selectProps, selectedSystemPropTypes] = selectSystemProps([a11yProps, viewProps])
 
@@ -56,10 +57,14 @@ const InputLabel = React.forwardRef(
     const themeTokens = useThemeTokens('InputLabel', tokens, variant)
 
     const hasTooltip = tooltip !== undefined
+
     const isHintInline = hintPosition === 'inline'
 
     const { themeOptions } = useTheme()
 
+    const getTooltipProps = () => {
+      return typeof tooltip === 'string' ? { content: tooltip } : tooltip
+    }
     return (
       <>
         <View ref={ref} style={staticStyles.container} {...selectProps(rest)}>
@@ -94,7 +99,7 @@ const InputLabel = React.forwardRef(
                 }
               ]}
             >
-              <Tooltip content={tooltip} copy={copy} />
+              <Tooltip copy={copy} {...getTooltipProps()} />
             </View>
           )}
           {maxCharacterAllowed && isHintInline && (
@@ -156,7 +161,7 @@ InputLabel.propTypes = {
   /**
    * Content of an optional `Tooltip`. If set, a tooltip button will be shown next to the label.
    */
-  tooltip: PropTypes.string,
+  tooltip: PropTypes.oneOfType([tooltipPropTypes, PropTypes.string]),
   /**
    * Current number of characterts of an input text.
    */

package/src/InputSupports/InputSupports.jsx

@@ -8,6 +8,7 @@ import { useThemeTokens } from '../ThemeProvider'
 import useInputSupports from './useInputSupports'
 import { getTokensPropType, useCopy } from '../utils'
 import dictionary from './dictionary'
+import tooltipPropTypes from '../Tooltip/shared'
 
 const InputSupports = React.forwardRef(
   (
@@ -115,9 +116,12 @@ InputSupports.propTypes = {
    */
   feedbackProps: PropTypes.object,
   /**
-   * Content of an optional `Tooltip`. If set, a tooltip button will be shown next to the label.
+   * an optional `Tooltip`. If set, tooltip will be shown next to the label.
+   * Props can be passed to the tooltip in one of the following ways.
+   * 1. `tooltip` as a string - The content of the tooltip.
+   * 2. `tooltip` as an object - Tooltip component props to be passed.
    */
-  tooltip: PropTypes.string,
+  tooltip: PropTypes.oneOfType([tooltipPropTypes, PropTypes.string]),
   /**
    * Use to visually mark an input as valid or invalid.
    */

package/src/List/ListItemMark.jsx

@@ -45,8 +45,6 @@ const selectBulletContainerStyles = ({
  * icon or bullet nicely against the first line of text in a ListIconContent.
  */
 const ListItemMark = React.forwardRef(({ icon, iconColor, iconSize, tokens = {} }, ref) => {
-  const IconComponent = icon || <></>
-
   const themeTokens = typeof tokens === 'function' ? tokens() : tokens
 
   const sideItemContainerStyles = selectSideItemContainerStyles(themeTokens)
@@ -56,7 +54,11 @@ const ListItemMark = React.forwardRef(({ icon, iconColor, iconSize, tokens = {}
     const iconTokens = selectItemIconTokens(themeTokens)
     return (
       <View style={[sideItemContainerStyles, bulletContainerStyles]}>
-        <IconComponent size={iconSize || iconTokens.size} color={iconColor || iconTokens.color} />
+        <Icon
+          icon={icon}
+          tokens={{ size: iconSize ?? iconTokens.size }}
+          variant={{ color: iconColor ?? iconTokens.color }}
+        />
       </View>
     )
   }

package/src/MultiSelectFilter/MultiSelectFilter.jsx

@@ -134,6 +134,10 @@ const MultiSelectFilter = React.forwardRef(
       buttonIconPadding,
       subtitleColor,
       dividerColor,
+      iconColor,
+      buttonBackgroundColor,
+      iconColorSelected,
+      buttonBackgroundColorSelected,
       ...restTokens
     } = useThemeTokens(
       'MultiSelectFilter',
@@ -154,7 +158,9 @@ const MultiSelectFilter = React.forwardRef(
       paddingBottom: labelPaddingBottom,
       paddingLeft: labelPaddingLeft,
       paddingRight: labelPaddingRight,
-      iconBackground: buttonIconBackgroundColor
+      iconBackground: buttonIconBackgroundColor,
+      iconColor: isSelected ? iconColorSelected : iconColor,
+      backgroundColor: isSelected ? buttonBackgroundColorSelected : buttonBackgroundColor
     }
     const getButtonDropdownTokens = useThemeTokensCallback(
       'ButtonDropdown',

package/src/ToggleSwitch/ToggleSwitch.jsx

@@ -107,6 +107,7 @@ const ToggleSwitch = React.forwardRef(
       variant,
       accessibilityRole = 'switch',
       accessibilityLabel = label,
+      togglePosition = 'end',
       ...rest
     },
     ref
@@ -125,8 +126,13 @@ const ToggleSwitch = React.forwardRef(
       selectButtonTokens(getTokens(buttonState), getTokens(themeTokens))
     const uniqueId = useUniqueId('toggleSwitch')
     const inputId = id ?? uniqueId
+
     return (
-      <StackView space={themeTokens.space} direction="row" tokens={{ alignItems: 'center' }}>
+      <StackView
+        space={themeTokens.space}
+        direction={togglePosition === 'start' ? 'row-reverse' : 'row'}
+        tokens={{ alignItems: 'center', justifyContent: 'start' }}
+      >
         {Boolean(label) && (
           <View style={[selectLabelStyles(themeTokens), staticStyles.containText]}>
             <InputLabel
@@ -225,7 +231,13 @@ ToggleSwitch.propTypes = {
   /**
    * Content of an optional Tooltip. If set, a tooltip button will be shown next to the label.
    */
-  tooltip: PropTypes.string
+  tooltip: PropTypes.string,
+  /**
+   * Controls the position of the switch in relation to the label.
+   * - 'start': switch on the start, before the `label` and `tooltip`.
+   * - 'end': switch to the end, after the `label` and `tooltip` (default).
+   */
+  togglePosition: PropTypes.oneOf(['start', 'end'])
 }
 
 const staticStyles = StyleSheet.create({

package/src/ToggleSwitch/ToggleSwitchGroup.jsx

@@ -87,6 +87,7 @@ const ToggleSwitchGroup = React.forwardRef(
           onChange: itemOnChange,
           ref: itemRef,
           tooltip: itemTooltip,
+          togglePosition,
           ...itemRest
         },
         index
@@ -117,6 +118,7 @@ const ToggleSwitchGroup = React.forwardRef(
             inactive={inactive}
             label={label}
             tooltip={itemTooltip}
+            togglePosition={togglePosition}
             {...itemA11y}
             {...selectItemProps(itemRest)}
           />
@@ -182,7 +184,13 @@ ToggleSwitchGroup.propTypes = {
       /**
        * An optional ref for one individual ToggleSwitch in the ToggleSwitchGroup
        */
-      ref: ABBPropTypes.ref()
+      ref: ABBPropTypes.ref(),
+      /**
+       * Controls the position of the switch in relation to the label.
+       * - 'start': switch on the start, before the `label` and `tooltip`.
+       * - 'end': switch to the end, after the `label` and `tooltip` (default).
+       */
+      togglePosition: PropTypes.oneOf(['start', 'end'])
     })
   ),
   /**

package/src/Tooltip/shared.js

@@ -1,6 +1,6 @@
 import PropTypes from 'prop-types'
-
-import { getTokensPropType, variantProp } from '../utils'
+import { getTokensPropType } from '../utils/props/tokens'
+import variantProp from '../utils/props/variantProp'
 
 const propTypes = {
   /**

package/src/utils/getSpacingScale.js

@@ -0,0 +1,50 @@
+import { resolveResponsiveProp } from './useResponsiveProp'
+
+/**
+ * Resolves spacing options from the provided space object.
+ *
+ * @param {Object} space - The space configuration object.
+ * @param {Object} [space.options] - The options for spacing.
+ * @param {number|string} [space.options.size] - The size of the spacing. Can be a number or a string.
+ * @param {string} [space.options.variant] - The variant of the spacing.
+ * @param {number} [space.options.subtract=0] - A value to subtract from the spacing size.
+ * @returns {Object} An object containing resolved spacing tokens, variant, overridden flag, and subtract value.
+ * @property {Object} tokens - The resolved spacing tokens.
+ * @property {number|string} tokens.size - The size of the spacing.
+ * @property {string} [variant] - The variant of the spacing.
+ * @property {boolean} overridden - Indicates if the size is explicitly overridden as a number.
+ * @property {number} subtract - The value to subtract from the spacing size.
+ */
+const resolveSpacingOptions = (space) => {
+  if (!space?.options) return {}
+
+  const { size, variant, subtract = 0 } = space.options
+  const overridden = typeof size === 'number'
+
+  return { tokens: { size }, variant, overridden, subtract }
+}
+
+/**
+ * Calculates the spacing scale based on the provided space value, viewport, and spacing tokens.
+ *
+ * @param {Object} spaceValue - The space value configuration, which may include responsive properties.
+ * @param {Object} viewport - The current viewport dimensions or configuration.
+ * @param {Function} getSpacingTokens - A function that retrieves spacing tokens based on the provided options.
+ * @returns {number} The calculated spacing scale, ensuring it is non-negative.
+ */
+const getSpacingScale = (spaceValue, viewport, getSpacingTokens) => {
+  const { tokens, variant, overridden, subtract = 0 } = resolveSpacingOptions(spaceValue)
+  const space = !overridden && (spaceValue?.space ?? resolveResponsiveProp(spaceValue, viewport, 0))
+
+  const { size } = getSpacingTokens(
+    {
+      ...variant,
+      space: typeof space === 'number' ? space : 0,
+      viewport
+    },
+    tokens
+  )
+  return Math.max(size - subtract, 0)
+}
+
+export default getSpacingScale

package/src/utils/index.js

@@ -23,3 +23,4 @@ export { default as htmlAttrs } from './htmlAttrs'
 export { transformGradient } from './transformGradient'
 export { default as convertFromMegaByteToByte } from './convertFromMegaByteToByte'
 export { default as formatImageSource } from './formatImageSource'
+export { default as getSpacingScale } from './getSpacingScale'