@telus-uds/components-base 3.13.0 → 3.14.1

package/src/Card/PressableCardBase.jsx

@@ -80,6 +80,7 @@ const PressableCardBase = React.forwardRef(
       href,
       hrefAttrs,
       dataSet,
+      backgroundImage,
       accessibilityRole = href ? 'link' : undefined,
       ...rawRest
     },
@@ -158,10 +159,13 @@ const PressableCardBase = React.forwardRef(
               setFocused(false)
               setPressed(false)
             }}
-            style={{ ...staticStyles.container, textDecoration: 'none' }}
+            style={staticStyles.linkContainer}
             {...(hrefAttrs || {})}
           >
-            <CardBase tokens={getCardTokens({ pressed, focused, hovered })}>
+            <CardBase
+              tokens={getCardTokens({ pressed, focused, hovered })}
+              backgroundImage={backgroundImage}
+            >
               {typeof children === 'function'
                 ? children(getCardState({ pressed, focused, hovered }))
                 : children}
@@ -183,7 +187,7 @@ const PressableCardBase = React.forwardRef(
         {...selectProps({ ...rest, accessibilityRole })}
       >
         {(pressableState) => (
-          <CardBase tokens={getCardTokens(pressableState)}>
+          <CardBase tokens={getCardTokens(pressableState)} backgroundImage={backgroundImage}>
             {typeof children === 'function' ? children(getCardState(pressableState)) : children}
           </CardBase>
         )}
@@ -196,6 +200,11 @@ const staticStyles = StyleSheet.create({
   container: {
     flex: 1,
     display: 'flex'
+  },
+  linkContainer: {
+    flex: 1,
+    display: 'flex',
+    textDecoration: 'none'
   }
 })
 
@@ -205,7 +214,25 @@ PressableCardBase.propTypes = {
   ...selectedSystemPropTypes,
   children: PropTypes.oneOfType([PropTypes.func, PropTypes.node]),
   tokens: getTokensSetPropType(tokenKeys, { partial: true, allowFunction: true }),
-  variant: variantProp.propType
+  variant: variantProp.propType,
+  backgroundImage: PropTypes.shape({
+    // 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: PropTypes.oneOfType([
+      PropTypes.oneOf(['cover', 'contain', 'stretch', 'repeat', 'center']),
+      PropTypes.object
+    ]),
+    position: PropTypes.oneOfType([
+      PropTypes.oneOf(['bottom', 'left', 'right', 'top']),
+      PropTypes.object
+    ]),
+    align: PropTypes.oneOfType([
+      PropTypes.oneOf(['start', 'end', 'center', 'stretch']),
+      PropTypes.object
+    ])
+  })
 }
 
 export default withLinkRouter(PressableCardBase)

package/src/Card/backgroundImageStylesMap.js

@@ -0,0 +1,41 @@
+import { Platform } from 'react-native'
+
+const webStyles = {
+  'top-start': { top: 0, left: 0 },
+  'top-center': { top: 0, left: '50%', transform: [{ translateX: '-50%' }] },
+  'top-end': { top: 0, right: 0 },
+  'right-start': { top: 0, right: 0 },
+  'left-start': { top: 0, left: 0 },
+  'left-center': { top: '50%', left: 0, transform: [{ translateY: '-50%' }] },
+  'right-center': { top: '50%', right: 0, transform: [{ translateY: '-50%' }] },
+  'bottom-start': { bottom: 0, left: 0 },
+  'left-end': { bottom: 0, left: 0 },
+  'bottom-center': { bottom: 0, left: '50%', transform: [{ translateX: '-50%' }] },
+  'bottom-end': { bottom: 0, right: 0 },
+  'right-end': { bottom: 0, right: 0 },
+  'top-stretch': { top: 0, left: 0, right: 0, width: '100%' },
+  'left-stretch': { top: 0, bottom: 0, left: 0, height: '100%' },
+  'right-stretch': { top: 0, bottom: 0, right: 0, height: '100%' },
+  'bottom-stretch': { bottom: 0, left: 0, right: 0, width: '100%' }
+}
+
+const nativeStyles = {
+  'top-start': { top: 0, left: 0, width: 150, height: 200 },
+  'top-center': { top: 0, left: '50%', marginLeft: -75, width: 150, height: 200 },
+  'top-end': { top: 0, right: 0, width: 150, height: 200 },
+  'right-start': { top: 0, right: 0, width: 150, height: 200 },
+  'left-start': { top: 0, left: 0, width: 150, height: 200 },
+  'left-center': { left: 0, top: '50%', marginTop: -100, width: 150, height: 200 },
+  'right-center': { right: 0, top: '50%', marginTop: -100, width: 150, height: 200 },
+  'bottom-start': { bottom: 0, left: 0, width: 150, height: 200 },
+  'left-end': { bottom: 0, left: 0, width: 150, height: 200 },
+  'bottom-center': { bottom: 0, left: '50%', marginLeft: -75, width: 150, height: 200 },
+  'bottom-end': { bottom: 0, right: 0, width: 150, height: 200 },
+  'right-end': { bottom: 0, right: 0, width: 150, height: 200 },
+  'top-stretch': { top: 0, left: 0, right: 0, width: '100%' },
+  'left-stretch': { top: 0, bottom: 0, left: 0, height: '100%' },
+  'right-stretch': { top: 0, bottom: 0, right: 0, height: '100%' },
+  'bottom-stretch': { bottom: 0, left: 0, right: 0, width: '100%' }
+}
+
+export default Platform.OS === 'web' ? webStyles : nativeStyles

package/src/FlexGrid/FlexGrid.jsx

@@ -29,19 +29,15 @@ const CONTENT_FULL_WIDTH = 'full'
  * Resolves the maximum width for content based on the provided value and responsive width.
  *
  * @param {number|string|null|undefined} contentMinWidthValue - The minimum width value for the content.
- *        Can be a number (pixels), a string constant (e.g., CONTENT_FULL_WIDTH, CONTENT_MAX_WIDTH), or null/undefined.
- * @param {number|string} responsiveWidth - The responsive width to use when contentMinWidthValue is CONTENT_MAX_WIDTH.
- * @returns {number|string|null} The resolved maximum width value, which can be a number, a string (e.g., '100%'), or null.
+ *        Can be a number, a special string constant (e.g., CONTENT_FULL_WIDTH, CONTENT_MAX_WIDTH), or null/undefined.
+ * @param {number} responsiveWidth - The responsive width to use when contentMinWidthValue is CONTENT_MAX_WIDTH.
+ * @returns {number|string|null} The resolved maximum width value, or null if full width is desired.
  */
 const resolveContentMaxWidth = (contentMinWidthValue, responsiveWidth) => {
-  if (!contentMinWidthValue) {
+  if (!contentMinWidthValue || contentMinWidthValue === CONTENT_FULL_WIDTH) {
     return null
   }
 
-  if (contentMinWidthValue === CONTENT_FULL_WIDTH) {
-    return '100%'
-  }
-
   if (Number.isFinite(contentMinWidthValue)) {
     return contentMinWidthValue
   }
@@ -53,6 +49,27 @@ const resolveContentMaxWidth = (contentMinWidthValue, responsiveWidth) => {
   return contentMinWidthValue
 }
 
+/**
+ * Calculates the maximum width for a given viewport based on limitWidth and contentMinWidth settings.
+ *
+ * @param {string} viewportKey - The viewport key ('xs', 'sm', 'md', 'lg', 'xl')
+ * @param {boolean} limitWidth - Whether to limit the width to viewport breakpoints
+ * @param {any} contentMinWidth - The contentMinWidth prop value
+ * @param {number|string|null} maxWidth - The resolved max width value
+ * @returns {number|string|null} The calculated maximum width for the viewport
+ */
+const getMaxWidthForViewport = (viewportKey, limitWidth, contentMinWidth, maxWidth) => {
+  if (limitWidth) {
+    return viewports.map.get(viewportKey === 'xs' ? 'sm' : viewportKey)
+  }
+
+  if (contentMinWidth) {
+    return maxWidth
+  }
+
+  return viewportKey === 'xl' ? viewports.map.get('xl') : null
+}
+
 /**
  * A mobile-first flexbox grid.
  */
@@ -93,23 +110,23 @@ const FlexGrid = React.forwardRef(
 
     const stylesByViewport = {
       xs: {
-        maxWidth: limitWidth ? viewports.map.get('sm') : maxWidth,
+        maxWidth: getMaxWidthForViewport('xs', limitWidth, contentMinWidth, maxWidth),
         flexDirection: reverseLevel[0] ? 'column-reverse' : 'column'
       },
       sm: {
-        maxWidth: limitWidth ? viewports.map.get('sm') : maxWidth,
+        maxWidth: getMaxWidthForViewport('sm', limitWidth, contentMinWidth, maxWidth),
         flexDirection: reverseLevel[1] ? 'column-reverse' : 'column'
       },
       md: {
-        maxWidth: limitWidth ? viewports.map.get('md') : maxWidth,
+        maxWidth: getMaxWidthForViewport('md', limitWidth, contentMinWidth, maxWidth),
         flexDirection: reverseLevel[2] ? 'column-reverse' : 'column'
       },
       lg: {
-        maxWidth: limitWidth ? viewports.map.get('lg') : maxWidth,
+        maxWidth: getMaxWidthForViewport('lg', limitWidth, contentMinWidth, maxWidth),
         flexDirection: reverseLevel[3] ? 'column-reverse' : 'column'
       },
       xl: {
-        maxWidth: limitWidth ? viewports.map.get('xl') : maxWidth,
+        maxWidth: getMaxWidthForViewport('xl', limitWidth, contentMinWidth, maxWidth),
         flexDirection: reverseLevel[4] ? 'column-reverse' : 'column'
       }
     }

package/src/Tabs/Tabs.jsx

@@ -12,6 +12,7 @@ import {
   selectSystemProps,
   useHash,
   useInputValue,
+  useResponsiveProp,
   variantProp,
   viewProps,
   withLinkRouter
@@ -21,6 +22,7 @@ import HorizontalScroll, {
   HorizontalScrollButton
 } from '../HorizontalScroll'
 import TabsItem from './TabsItem'
+import TabsDropdown from './TabsDropdown'
 
 const [selectProps, selectedSystemPropTypes] = selectSystemProps([a11yProps, viewProps])
 const [selectItemProps, selectedItemPropTypes] = selectSystemProps([
@@ -58,6 +60,12 @@ const getStackViewTokens = (variant) => {
  * Tabs renders a horizontally-scrolling menu of selectable buttons which may link
  * to a page or control what content is displayed on this page.
  *
+ * By default, Tabs always renders as horizontal scrolling tabs regardless of viewport.
+ * To enable dropdown mode, you must explicitly pass `variant={{ dropdown: true }}`.
+ * When dropdown is enabled, it will only render as a dropdown on mobile and tablet
+ * viewports (XS and SM). On larger viewports (MD, LG, XL), it will still render as
+ * horizontal tabs even with dropdown enabled.
+ *
  * If you are using Tabs to navigate to a new page (web-only) you should pass
  * `navigation`as the `accessibilityRole` to te Tabs component, this will cause
  * TabItems to default to a role of link and obtain aria-current behaviour.
@@ -102,6 +110,32 @@ const Tabs = React.forwardRef(
       getDefaultTabItemAccessibilityRole(parentAccessibilityRole)
     const stackViewTokens = getStackViewTokens(variant)
 
+    // Render dropdown only if explicitly requested via variant AND viewport is xs or sm
+    const isSmallViewport = useResponsiveProp(
+      { xs: true, sm: true, md: false, lg: false, xl: false },
+      false
+    )
+    const shouldRenderDropdown = variant?.dropdown === true && isSmallViewport
+
+    if (shouldRenderDropdown) {
+      return (
+        <TabsDropdown
+          ref={ref}
+          tokens={tokens}
+          itemTokens={itemTokens}
+          variant={variant}
+          value={currentValue}
+          onChange={setValue}
+          items={items}
+          LinkRouter={LinkRouter}
+          linkRouterProps={linkRouterProps}
+          accessibilityRole={
+            parentAccessibilityRole === 'tablist' ? 'button' : parentAccessibilityRole
+          }
+          {...restProps}
+        />
+      )
+    }
     return (
       <HorizontalScroll
         ref={ref}
@@ -169,14 +203,14 @@ Tabs.displayName = 'Tabs'
 
 Tabs.propTypes = {
   ...selectedSystemPropTypes,
-  ...withLinkRouter.PropTypes,
+  ...withLinkRouter.propTypes,
   /**
    * Array of `TabsItem`s
    */
   items: PropTypes.arrayOf(
     PropTypes.shape({
       ...selectedItemPropTypes,
-      ...withLinkRouter.PropTypes,
+      ...withLinkRouter.propTypes,
       href: PropTypes.string,
       label: PropTypes.string,
       id: PropTypes.string,

package/src/Tabs/TabsDropdown.jsx

@@ -0,0 +1,265 @@
+import React from 'react'
+import PropTypes from 'prop-types'
+import { Pressable, StyleSheet, Text, View } from 'react-native'
+import { useThemeTokensCallback, applyTextStyles, useTheme } from '../ThemeProvider'
+import {
+  a11yProps,
+  getTokensPropType,
+  resolvePressableTokens,
+  selectSystemProps,
+  selectTokens,
+  useOverlaidPosition,
+  useCopy,
+  variantProp,
+  viewProps,
+  withLinkRouter
+} from '../utils'
+import { useViewport } from '../ViewportProvider'
+import Icon from '../Icon'
+import Listbox from '../Listbox'
+import dictionary from './dictionary'
+
+const [selectProps, selectedSystemPropTypes] = selectSystemProps([a11yProps, viewProps])
+
+const selectButtonContentStyles = ({
+  backgroundColor,
+  borderColor,
+  borderWidth,
+  borderRadius,
+  paddingHorizontal,
+  paddingVertical,
+  marginHorizontal,
+  marginVertical
+}) => ({
+  backgroundColor,
+  borderColor,
+  borderWidth,
+  borderRadius,
+  paddingHorizontal,
+  paddingVertical,
+  marginLeft: marginHorizontal,
+  marginRight: marginHorizontal,
+  marginTop: marginVertical,
+  marginBottom: marginVertical
+})
+
+/**
+ * TabsDropdown renders a dropdown version of tabs for mobile/tablet viewports.
+ * It shows the currently selected tab as a button that opens a dropdown menu
+ * containing all available tabs.
+ *
+ * This is rendered automatically by `Tabs` on mobile viewports and when variant
+ * is dropdown and isn't intended to be used directly.
+ */
+const TabsDropdown = React.forwardRef(
+  (
+    {
+      itemTokens,
+      variant,
+      value,
+      onChange,
+      items = [],
+      LinkRouter,
+      linkRouterProps,
+      accessibilityRole = 'button',
+      copy = 'en',
+      dictionary: customDictionary = dictionary,
+      ...rest
+    },
+    ref
+  ) => {
+    const { themeOptions } = useTheme()
+    const viewport = useViewport()
+    const [isOpen, setIsOpen] = React.useState(false)
+
+    const getTokens = useThemeTokensCallback('TabsItem', itemTokens, { viewport, ...variant })
+
+    const selectedItem =
+      items.find((item) => {
+        const itemId = item.id ?? item.label
+        return value === itemId
+      }) || items[0]
+
+    const { overlaidPosition, sourceRef, targetRef, onTargetLayout, isReady } = useOverlaidPosition(
+      {
+        isShown: isOpen,
+        offsets: { vertical: 4 },
+        align: { top: 'bottom', left: 'left' }
+      }
+    )
+
+    const handleToggle = () => setIsOpen((prev) => !prev)
+    const handleClose = () => setIsOpen(false)
+
+    const handleItemSelect = (item, event) => {
+      const itemId = item.id ?? item.label
+      setIsOpen(false)
+
+      if (onChange) onChange(itemId, event)
+      if (item.onPress) item.onPress(event)
+    }
+
+    const listboxItems = items.map((item) => ({
+      ...item,
+      onPress: (event) => handleItemSelect(item, event)
+    }))
+
+    const isSelected = Boolean(selectedItem && value)
+    const getCopy = useCopy({ dictionary: customDictionary, copy })
+
+    const selectedProps = selectProps({
+      accessibilityRole,
+      ...rest
+    })
+
+    return (
+      <View ref={ref} style={styles.container}>
+        <Pressable
+          ref={sourceRef}
+          onPress={handleToggle}
+          {...selectedProps}
+          style={styles.pressable}
+        >
+          {(pressableState) => {
+            // Use resolvePressableTokens like TabBarItem does for proper state handling
+            const resolvedTokens = resolvePressableTokens(getTokens, pressableState, {
+              viewport,
+              expanded: isOpen,
+              selected: isSelected
+            })
+
+            const textStyles = applyTextStyles({
+              ...selectTokens('Typography', resolvedTokens),
+              themeOptions
+            })
+
+            // Get dropdown icons from resolved tokens
+            const dropdownIcon = isOpen
+              ? resolvedTokens.dropdownIconExpanded
+              : resolvedTokens.dropdownIcon
+
+            return (
+              <View style={[styles.buttonContent, selectButtonContentStyles(resolvedTokens)]}>
+                <Text style={textStyles}>{selectedItem?.label || getCopy('selectTab')}</Text>
+                {dropdownIcon && (
+                  <Icon
+                    icon={dropdownIcon}
+                    variant={{ size: 'micro' }}
+                    tokens={{
+                      color: textStyles.color
+                    }}
+                  />
+                )}
+              </View>
+            )
+          }}
+        </Pressable>
+
+        {isOpen && (
+          <Listbox.Overlay
+            overlaidPosition={overlaidPosition}
+            maxWidth={400}
+            minWidth={200}
+            isReady={isReady}
+            onLayout={onTargetLayout}
+          >
+            <Listbox
+              items={listboxItems}
+              firstItemRef={targetRef}
+              parentRef={sourceRef}
+              selectedId={value}
+              onClose={handleClose}
+              LinkRouter={LinkRouter}
+              linkRouterProps={linkRouterProps}
+            />
+          </Listbox.Overlay>
+        )}
+      </View>
+    )
+  }
+)
+
+TabsDropdown.displayName = 'TabsDropdown'
+
+const dictionaryContentShape = PropTypes.shape({
+  selectTab: PropTypes.string.isRequired
+})
+
+TabsDropdown.propTypes = {
+  ...selectedSystemPropTypes,
+  ...withLinkRouter.propTypes,
+  /**
+   * Array of tab items
+   */
+  items: PropTypes.arrayOf(
+    PropTypes.shape({
+      ...withLinkRouter.propTypes,
+      /** URL to navigate to when the tab is pressed */
+      href: PropTypes.string,
+      /** Display text for the tab */
+      label: PropTypes.string,
+      /** Unique identifier for the tab */
+      id: PropTypes.string,
+      /** Reference to the tab element */
+      ref: PropTypes.oneOfType([PropTypes.func, PropTypes.object]),
+      /** Custom render function for the tab content */
+      render: PropTypes.func
+    })
+  ),
+  /**
+   * Current selected tab id
+   */
+  value: PropTypes.string,
+  /**
+   * Callback for when the selected tab changes
+   */
+  onChange: PropTypes.func,
+  /**
+   * Custom tokens for the main Tabs container
+   */
+  tokens: getTokensPropType('Tabs'),
+  /**
+   * Custom tokens for `TabsItem`
+   */
+  itemTokens: getTokensPropType('TabsItem'),
+  /**
+   * Visual and behavioral variants for the tabs dropdown
+   */
+  variant: variantProp.propType,
+  /**
+   * Select English or French copy for the accessible labels.
+   * You may also pass in a custom dictionary object.
+   */
+  copy: PropTypes.oneOfType([PropTypes.oneOf(['en', 'fr']), dictionaryContentShape]),
+  /**
+   * Override the default dictionary, by passing the complete dictionary object for `en` and `fr`
+   */
+  dictionary: PropTypes.shape({
+    en: dictionaryContentShape,
+    fr: dictionaryContentShape
+  })
+}
+
+const styles = StyleSheet.create({
+  container: {
+    position: 'relative',
+    width: '100%'
+  },
+  pressable: {
+    outlineWidth: 0,
+    outlineStyle: 'none',
+    outlineColor: 'transparent'
+  },
+  buttonContent: {
+    display: 'flex',
+    flexDirection: 'row',
+    alignItems: 'center',
+    justifyContent: 'space-between',
+    width: '100%',
+    minHeight: 44,
+    outline: 'none',
+    boxSizing: 'border-box'
+  }
+})
+
+export default TabsDropdown

package/src/Tabs/TabsItem.jsx

@@ -70,8 +70,10 @@ const selectContainerStyles = ({
   borderRadius,
   paddingHorizontal: paddingHorizontal - borderWidth,
   paddingVertical: paddingVertical - borderWidth,
-  marginHorizontal,
-  marginVertical
+  marginLeft: marginHorizontal,
+  marginRight: marginHorizontal,
+  marginTop: marginVertical,
+  marginBottom: marginVertical
 })
 
 /**

package/src/Tabs/dictionary.js

@@ -0,0 +1,8 @@
+export default {
+  en: {
+    selectTab: 'Select tab'
+  },
+  fr: {
+    selectTab: 'Sélectionner un onglet'
+  }
+}

package/src/ViewportProvider/ViewportProvider.jsx

@@ -6,16 +6,21 @@ import useViewportListener from './useViewportListener'
 
 /**
  * Provides an up-to-date viewport value from system-constants, available via the `useViewport` hook
+ *
+ * @param {React.ReactNode} children - Child components that will have access to viewport context
+ * @param {string} [defaultViewport] - Default viewport to use during server-side rendering.
+ *   Must be one of the viewport keys from system-constants. If not provided, defaults to the smallest viewport.
  */
-const ViewportProvider = ({ children }) => {
+const ViewportProvider = ({ children, defaultViewport }) => {
   // Default to the smallest viewport for mobile-first SSR. On client side, this is updated
   // by useViewportListener in a layout effect before anything is shown to the user.
-  const [viewport, setViewport] = React.useState(viewports.keys[0])
+  const [viewport, setViewport] = React.useState(defaultViewport || viewports.keys[0])
   useViewportListener(setViewport)
   return <ViewportContext.Provider value={viewport}>{children}</ViewportContext.Provider>
 }
 ViewportProvider.propTypes = {
-  children: PropTypes.node.isRequired
+  children: PropTypes.node.isRequired,
+  defaultViewport: PropTypes.oneOf(viewports.keys)
 }
 
 export default ViewportProvider