@telus-uds/components-base 3.23.0 → 3.24.0

package/src/Listbox/ListboxGroup.jsx

@@ -2,21 +2,36 @@
 import React from 'react'
 import PropTypes from 'prop-types'
 import { View, StyleSheet, Platform } from 'react-native'
-import { withLinkRouter } from '../utils'
+import { withLinkRouter, variantProp, copyPropTypes } from '../utils'
+import { useThemeTokens } from '../ThemeProvider'
 import ExpandCollapse from '../ExpandCollapse'
 import ListboxItem from './ListboxItem'
 import { useListboxContext } from './ListboxContext'
 import GroupControl from './GroupControl'
+import SecondLevelHeader from './SecondLevelHeader'
+import defaultDictionary from './dictionary'
 
 const styles = StyleSheet.create({
   groupWrapper: {
     margin: 0,
     padding: 0,
-    overflow: 'hidden'
+    overflow: 'visible'
   },
   list: {
     margin: 0,
     padding: 0
+  },
+  secondLevelContainer: {
+    margin: 0,
+    padding: 0,
+    width: '100%',
+    display: 'flex',
+    flexDirection: 'column'
+  },
+  secondLevelList: {
+    margin: 0,
+    padding: 0,
+    width: '100%'
   }
 })
 
@@ -27,6 +42,10 @@ const getAccessibilityRole = () =>
     web: 'listitem'
   })
 
+const selectSecondLevelContainerStyles = ({ secondLevelHeaderBackgroundColor }) => ({
+  backgroundColor: secondLevelHeaderBackgroundColor
+})
+
 const ListboxGroup = React.forwardRef(
   (
     {
@@ -38,11 +57,86 @@ const ListboxGroup = React.forwardRef(
       expandProps,
       onLastItemBlur,
       nextItemRef,
-      prevItemRef
+      prevItemRef,
+      copy = 'en',
+      dictionary = defaultDictionary,
+      variant = {},
+      tokens = {},
+      onClose
     },
     ref
   ) => {
-    const { selectedId } = useListboxContext()
+    const { selectedId, activeSecondLevelGroup, setActiveSecondLevelGroup } = useListboxContext()
+    const [secondLevelOpen, setSecondLevelOpen] = React.useState(false)
+    const isSecondLevel = variant?.secondLevel === true
+    const listboxTokens = useThemeTokens('Listbox', variant, tokens)
+    const groupId = id ?? label
+
+    const handleGroupClick = React.useCallback(() => {
+      if (isSecondLevel) {
+        setSecondLevelOpen(true)
+        setActiveSecondLevelGroup(groupId)
+      }
+    }, [isSecondLevel, groupId, setActiveSecondLevelGroup])
+
+    const handleBackClick = React.useCallback(() => {
+      setSecondLevelOpen(false)
+      setActiveSecondLevelGroup(null)
+    }, [setActiveSecondLevelGroup])
+
+    const handleCloseClick = React.useCallback(() => {
+      setSecondLevelOpen(false)
+      setActiveSecondLevelGroup(null)
+      if (onClose) {
+        onClose()
+      }
+    }, [setActiveSecondLevelGroup, onClose])
+
+    if (isSecondLevel && activeSecondLevelGroup && activeSecondLevelGroup !== groupId) {
+      return null
+    }
+
+    if (isSecondLevel && secondLevelOpen) {
+      return (
+        <View
+          style={[styles.secondLevelContainer, selectSecondLevelContainerStyles(listboxTokens)]}
+        >
+          <SecondLevelHeader
+            label={label}
+            onBack={handleBackClick}
+            onClose={handleCloseClick}
+            copy={copy}
+            dictionary={dictionary}
+            variant={variant}
+            tokens={tokens}
+          />
+          <View style={styles.secondLevelList}>
+            {items &&
+              items.map((item, index) => {
+                return (
+                  <ListboxItem
+                    key={item.label}
+                    id={item.id ?? item.label}
+                    {...item}
+                    selected={
+                      (item.id && item.id === selectedId) ||
+                      (item.label && item.label === selectedId)
+                    }
+                    isChild={false}
+                    LinkRouter={LinkRouter}
+                    linkRouterProps={linkRouterProps}
+                    variant={variant}
+                    tokens={tokens}
+                    {...(index === 0 && { prevItemRef })}
+                    {...(index === items.length - 1 && { nextItemRef })}
+                    {...(index === items.length - 1 && { onBlur: onLastItemBlur })}
+                  />
+                )
+              })}
+          </View>
+        </View>
+      )
+    }
 
     // TODO: implement keyboard navigation via refs for grouped items separately here
     return (
@@ -63,9 +157,11 @@ const ListboxGroup = React.forwardRef(
           // TODO refactor
           // eslint-disable-next-line react/no-unstable-nested-components
           control={(controlProps) => (
-            <GroupControl id={id ?? label} {...controlProps} label={label} />
+            <GroupControl id={id ?? label} {...controlProps} label={label} variant={variant} />
           )}
           {...expandProps}
+          {...(isSecondLevel && { open: false })}
+          {...(isSecondLevel && { onPress: handleGroupClick })}
           tokens={{
             contentPaddingLeft: 0,
             contentPaddingRight: 0,
@@ -79,26 +175,31 @@ const ListboxGroup = React.forwardRef(
           }}
           controlRef={ref}
         >
-          <View style={styles.list}>
-            {items.map((item, index) => {
-              return (
-                <ListboxItem
-                  key={item.label}
-                  id={item.id ?? item.label}
-                  {...item}
-                  selected={
-                    (item.id && item.id === selectedId) || (item.label && item.label === selectedId)
-                  }
-                  isChild
-                  LinkRouter={LinkRouter}
-                  linkRouterProps={linkRouterProps}
-                  {...(index === 0 && { prevItemRef })}
-                  {...(index === items.length - 1 && { nextItemRef })}
-                  {...(index === items.length - 1 && { onBlur: onLastItemBlur })}
-                />
-              )
-            })}
-          </View>
+          {!isSecondLevel && (
+            <View style={styles.list}>
+              {items.map((item, index) => {
+                return (
+                  <ListboxItem
+                    key={item.label}
+                    id={item.id ?? item.label}
+                    {...item}
+                    selected={
+                      (item.id && item.id === selectedId) ||
+                      (item.label && item.label === selectedId)
+                    }
+                    isChild
+                    LinkRouter={LinkRouter}
+                    linkRouterProps={linkRouterProps}
+                    variant={variant}
+                    tokens={tokens}
+                    {...(index === 0 && { prevItemRef })}
+                    {...(index === items.length - 1 && { nextItemRef })}
+                    {...(index === items.length - 1 && { onBlur: onLastItemBlur })}
+                  />
+                )
+              })}
+            </View>
+          )}
         </ExpandCollapse.Panel>
       </View>
     )
@@ -108,6 +209,10 @@ ListboxGroup.displayName = 'ListboxGroup'
 
 ListboxGroup.propTypes = {
   ...withLinkRouter.propTypes,
+  /**
+   * Unique identifier for the group
+   */
+  id: PropTypes.string,
   label: PropTypes.string,
   items: PropTypes.arrayOf(
     PropTypes.shape({
@@ -122,7 +227,34 @@ ListboxGroup.propTypes = {
   /**
    * Use this callback to redirect the focus after it leaves the last item of the group.
    */
-  onLastItemBlur: PropTypes.func
+  onLastItemBlur: PropTypes.func,
+  /**
+   * Select English or French copy
+   */
+  copy: copyPropTypes,
+  /**
+   * Override the default dictionary, by passing the complete dictionary object for `en` and `fr`
+   */
+  dictionary: PropTypes.shape({
+    en: PropTypes.shape({
+      closeMenu: PropTypes.string.isRequired
+    }),
+    fr: PropTypes.shape({
+      closeMenu: PropTypes.string.isRequired
+    })
+  }),
+  /**
+   * Variant configuration for secondLevel behavior
+   */
+  variant: variantProp.propType,
+  /**
+   * Custom tokens
+   */
+  tokens: PropTypes.object,
+  /**
+   * Callback when the menu is closed
+   */
+  onClose: PropTypes.func
 }
 
 export default ListboxGroup

package/src/Listbox/ListboxOverlay.jsx

@@ -23,10 +23,21 @@ const paddingHorizontal = 0
 
 const DropdownOverlay = React.forwardRef(
   (
-    { children, isReady = false, overlaidPosition, maxWidth, minWidth, onLayout, tokens, testID },
+    {
+      children,
+      isReady = false,
+      overlaidPosition,
+      maxWidth,
+      minWidth,
+      onLayout,
+      tokens,
+      testID,
+      variant
+    },
+
     ref
   ) => {
-    const systemTokens = useThemeTokens('Listbox', {}, {})
+    const systemTokens = useThemeTokens('Listbox', variant, tokens)
 
     return (
       <View
@@ -43,11 +54,12 @@ const DropdownOverlay = React.forwardRef(
         <Card
           tokens={{
             shadow: systemTokens.shadow,
+            borderRadius: systemTokens.borderRadius,
+            ...(Platform.OS === 'web' && { overflowY: 'hidden' }),
             paddingBottom: paddingVertical,
             paddingTop: paddingVertical,
             paddingLeft: paddingHorizontal,
-            paddingRight: paddingHorizontal,
-            ...tokens
+            paddingRight: paddingHorizontal
           }}
         >
           {children}
@@ -80,7 +92,8 @@ DropdownOverlay.propTypes = {
   minWidth: PropTypes.number,
   onLayout: PropTypes.func,
   tokens: PropTypes.object,
-  testID: PropTypes.string
+  testID: PropTypes.string,
+  variant: PropTypes.object
 }
 
 export default Platform.OS === 'web' ? withPortal(DropdownOverlay) : DropdownOverlay

package/src/Listbox/SecondLevelHeader.jsx

@@ -0,0 +1,182 @@
+import React from 'react'
+import PropTypes from 'prop-types'
+import { View, StyleSheet, Text, Pressable } from 'react-native'
+import { useThemeTokens } from '../ThemeProvider'
+import { useCopy, variantProp, copyPropTypes } from '../utils'
+import Icon from '../Icon'
+import IconButton from '../IconButton'
+import Divider from '../Divider'
+import defaultDictionary from './dictionary'
+
+const styles = StyleSheet.create({
+  headerContainer: {
+    width: '100%'
+  },
+  headerContent: {
+    flexDirection: 'row',
+    alignItems: 'center',
+    width: '100%'
+  },
+  leftSection: {
+    flexDirection: 'row',
+    alignItems: 'center',
+    flex: 1
+  },
+  backIcon: {
+    marginRight: 8,
+    flexShrink: 0
+  },
+  labelText: {
+    flex: 1
+  },
+  closeButton: {
+    flexShrink: 0
+  },
+  dividerContainer: {
+    width: '100%'
+  }
+})
+
+const selectHeaderContainerStyles = ({ secondLevelHeaderBackgroundColor }) => ({
+  backgroundColor: secondLevelHeaderBackgroundColor
+})
+
+const selectHeaderContentStyles = ({
+  secondLevelHeaderPaddingTop,
+  secondLevelHeaderPaddingBottom,
+  secondLevelHeaderPaddingLeft,
+  secondLevelHeaderPaddingRight
+}) => ({
+  paddingTop: secondLevelHeaderPaddingTop,
+  paddingBottom: secondLevelHeaderPaddingBottom,
+  paddingLeft: secondLevelHeaderPaddingLeft,
+  paddingRight: secondLevelHeaderPaddingRight
+})
+
+const selectLabelTextStyles = ({
+  secondLevelBackLinkFontName,
+  secondLevelBackLinkFontWeight,
+  secondLevelBackLinkFontSize,
+  secondLevelBackLinkColor
+}) => ({
+  fontFamily: `${secondLevelBackLinkFontName}${secondLevelBackLinkFontWeight}normal`,
+  fontSize: secondLevelBackLinkFontSize,
+  color: secondLevelBackLinkColor
+})
+
+/**
+ * SecondLevelHeader component for Listbox secondLevel variant.
+ * Displays a header with back button icon, title text, and close button (IconButton),
+ * separated from content by a Divider.
+ */
+const SecondLevelHeader = React.forwardRef(
+  (
+    {
+      label,
+      onBack,
+      onClose,
+      copy = 'en',
+      dictionary = defaultDictionary,
+      tokens: tokensProp = {},
+      variant = {}
+    },
+    ref
+  ) => {
+    const tokens = useThemeTokens('Listbox', variant, tokensProp)
+    const getCopy = useCopy({ dictionary, copy })
+
+    const {
+      secondLevelBackIcon,
+      secondLevelBackIconColor,
+      secondLevelCloseIcon,
+      secondLevelCloseIconSize,
+      secondLevelCloseButtonBorderWidth,
+      secondLevelCloseButtonPadding,
+      secondLevelDividerColor,
+      secondLevelDividerWidth
+    } = tokens
+
+    return (
+      <View style={[styles.headerContainer, selectHeaderContainerStyles(tokens)]} ref={ref}>
+        <View style={[styles.headerContent, selectHeaderContentStyles(tokens)]}>
+          <Pressable onPress={onBack} style={styles.leftSection}>
+            <View style={styles.backIcon}>
+              <Icon
+                icon={secondLevelBackIcon}
+                tokens={{
+                  color: secondLevelBackIconColor
+                }}
+                variant={{ size: 'micro' }}
+              />
+            </View>
+            <Text numberOfLines={1} style={[styles.labelText, selectLabelTextStyles(tokens)]}>
+              {label}
+            </Text>
+          </Pressable>
+          <View style={styles.closeButton}>
+            <IconButton
+              icon={secondLevelCloseIcon}
+              onPress={onClose}
+              accessibilityLabel={getCopy('closeMenu')}
+              tokens={{
+                iconSize: secondLevelCloseIconSize,
+                borderWidth: secondLevelCloseButtonBorderWidth,
+                padding: secondLevelCloseButtonPadding
+              }}
+            />
+          </View>
+        </View>
+        <View style={styles.dividerContainer}>
+          <Divider
+            tokens={{
+              color: secondLevelDividerColor,
+              width: secondLevelDividerWidth
+            }}
+          />
+        </View>
+      </View>
+    )
+  }
+)
+
+SecondLevelHeader.displayName = 'SecondLevelHeader'
+
+SecondLevelHeader.propTypes = {
+  /**
+   * The label text to display (typically the parent item label)
+   */
+  label: PropTypes.string.isRequired,
+  /**
+   * Callback when back button is clicked
+   */
+  onBack: PropTypes.func.isRequired,
+  /**
+   * Callback when close button is clicked
+   */
+  onClose: PropTypes.func.isRequired,
+  /**
+   * Select English or French copy
+   */
+  copy: copyPropTypes,
+  /**
+   * Override the default dictionary, by passing the complete dictionary object for `en` and `fr`
+   */
+  dictionary: PropTypes.shape({
+    en: PropTypes.shape({
+      closeMenu: PropTypes.string.isRequired
+    }),
+    fr: PropTypes.shape({
+      closeMenu: PropTypes.string.isRequired
+    })
+  }),
+  /**
+   * Custom tokens to override theme tokens
+   */
+  tokens: PropTypes.object,
+  /**
+   * Variant configuration
+   */
+  variant: variantProp.propType
+}
+
+export default SecondLevelHeader

package/src/Listbox/dictionary.js

@@ -0,0 +1,8 @@
+export default {
+  en: {
+    closeMenu: 'Close menu'
+  },
+  fr: {
+    closeMenu: 'Fermer le menu'
+  }
+}

package/src/Shortcuts/Shortcuts.jsx

@@ -0,0 +1,174 @@
+import React from 'react'
+import PropTypes from 'prop-types'
+import { Platform, StyleSheet, View } from 'react-native'
+import { viewports } from '@telus-uds/system-constants'
+
+import { useTheme, useThemeTokens } from '../ThemeProvider'
+import { useViewport } from '../ViewportProvider'
+import {
+  a11yProps,
+  getTokensPropType,
+  selectSystemProps,
+  useResponsiveProp,
+  variantProp,
+  viewProps
+} from '../utils'
+
+import HorizontalScroll, {
+  horizontalScrollUtils,
+  HorizontalScrollButton
+} from '../HorizontalScroll'
+
+const [selectProps, selectedSystemPropTypes] = selectSystemProps([a11yProps, viewProps])
+
+const { selectHorizontalScrollTokens, useItemPositions } = horizontalScrollUtils
+
+const selectStyles = (themeTokens, maxWidth, viewport) => {
+  const isDesktop =
+    viewport === viewports.md || viewport === viewports.lg || viewport === viewports.xl
+
+  return {
+    wrapper: {
+      alignItems: isDesktop ? 'center' : 'flex-start'
+    },
+    scrollContainer: {
+      width: '100%',
+      ...(isDesktop && { maxWidth })
+    },
+    container: {
+      paddingTop: themeTokens.mainContainerTopPadding,
+      paddingBottom: themeTokens.mainContainerBottomPadding,
+      paddingLeft: themeTokens.mainContainerLeftPadding,
+      paddingRight: themeTokens.mainContainerRightPadding,
+      gap: themeTokens.mainContainerGap,
+      ...(isDesktop && {
+        alignItems: 'flex-start',
+        justifyContent: 'center'
+      })
+    }
+  }
+}
+
+/**
+ * A horizontal scrollable shortcuts component that displays a collection of shortcut items.
+ * This component automatically injects shared configuration props to all ShortcutsItem children
+ * via React.cloneElement, including variant settings, hideLabels, and iconVariant.
+ *
+ * @component
+ * @param {Object} props - Component properties
+ * @param {Object} [props.tokens] - Theme tokens to customize the component's appearance
+ * @param {Object} [props.variant] - Visual variant configuration for the shortcuts container and its items
+ * @param {string} [props.variant.width] - Width variant to apply to all items (e.g., 'equal', 'dynamic')
+ * @param {Object} [props.scrollButtonTokens] - Tokens to customize scroll button appearance
+ * @param {boolean} [props.hideLabels=false] - Whether to hide labels on all shortcut items (can be overridden per item)
+ * @param {Object} [props.iconVariant] - Icon variant to apply to all shortcut items (can be overridden per item)
+ * @param {React.ReactNode} props.children - ShortcutsItem components to render
+ * @param {React.Ref} ref - Forwarded ref to the component's root element
+ * @returns {React.ReactElement} Rendered shortcuts component with horizontal scroll functionality
+ *
+ * @example
+ * <Shortcuts hideLabels={false} variant={{ width: 'equal' }}>
+ *   <ShortcutsItem icon={HomeIcon} label="Home" href="/home" />
+ *   <ShortcutsItem icon={SettingsIcon} label="Settings" href="/settings" />
+ * </Shortcuts>
+ *
+ * @example
+ * // Item-level props override container props
+ * <Shortcuts hideLabels iconVariant={{ size: 'small' }}>
+ *   <ShortcutsItem icon={HomeIcon} label="Home" hideLabel={false} />
+ *   <ShortcutsItem icon={SettingsIcon} label="Settings" />
+ * </Shortcuts>
+ */
+const Shortcuts = React.forwardRef(
+  (
+    { tokens, variant, scrollButtonTokens, hideLabels = false, iconVariant, children, ...rest },
+    ref
+  ) => {
+    const viewport = useViewport()
+    const themeTokens = useThemeTokens('Shortcuts', tokens, variant, {
+      viewport
+    })
+
+    const { themeOptions } = useTheme()
+    const maxWidth = useResponsiveProp(
+      themeOptions?.contentMaxWidth,
+      viewports.map.get(viewports.xl)
+    )
+
+    const [itemPositions] = useItemPositions()
+
+    const [maxItemWidth, setMaxItemWidth] = React.useState(null)
+
+    const registerWidth = React.useCallback(
+      (width) => setMaxItemWidth((prev) => (prev == null || width > prev ? width : prev)),
+      []
+    )
+
+    const styles = selectStyles(themeTokens, maxWidth, viewport)
+
+    const childrenWithProps = React.Children.map(children, (child) => {
+      if (!React.isValidElement(child)) {
+        return child
+      }
+      return React.cloneElement(child, {
+        maxWidth: maxItemWidth,
+        registerWidth,
+        containerVariant: variant,
+        containerHideLabels: hideLabels,
+        containerIconVariant: iconVariant
+      })
+    })
+
+    return (
+      <View style={[staticStyles.wrapper, styles.wrapper]} ref={ref} {...selectProps(rest)}>
+        <View style={styles.scrollContainer}>
+          <HorizontalScroll
+            ScrollButton={HorizontalScrollButton}
+            itemPositions={itemPositions}
+            tokens={selectHorizontalScrollTokens(themeTokens)}
+            scrollButtonTokens={scrollButtonTokens}
+            variant={{ hideNavigationButtons: Platform.OS !== 'web' }}
+          >
+            <View style={[staticStyles.container, styles.container]}>{childrenWithProps}</View>
+          </HorizontalScroll>
+        </View>
+      </View>
+    )
+  }
+)
+
+Shortcuts.displayName = 'Shortcuts'
+
+Shortcuts.propTypes = {
+  ...selectedSystemPropTypes,
+  tokens: getTokensPropType('Shortcuts'),
+  variant: variantProp.propType,
+  /**
+   * Custom tokens for `HorizontalScrollButton`
+   */
+  scrollButtonTokens: getTokensPropType('HorizontalScrollButton'),
+  /**
+   * Hide labels for all ShortcutsItem children. When true, labels are visually hidden but remain accessible to screen readers via the icon's accessibilityLabel.
+   */
+  hideLabels: PropTypes.bool,
+  /**
+   * Icon variant to apply to all ShortcutsItem children.
+   */
+  iconVariant: variantProp.propType,
+  /**
+   * ShortcutsItem components to be rendered within the Shortcuts container
+   */
+  children: PropTypes.node
+}
+
+const staticStyles = StyleSheet.create({
+  wrapper: {
+    flexGrow: 1
+  },
+  container: {
+    flexDirection: 'row',
+    flex: 1
+  }
+})
+
+export default Shortcuts