@telus-uds/components-base 3.22.0 → 3.24.0

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

package/src/Shortcuts/ShortcutsItem.jsx

@@ -0,0 +1,297 @@
+import React from 'react'
+import { Image, Platform, Pressable, StyleSheet, View } from 'react-native'
+import PropTypes from 'prop-types'
+
+import { applyTextStyles, useThemeTokensCallback } from '../ThemeProvider'
+import {
+  a11yProps,
+  clickProps,
+  getTokensPropType,
+  hrefAttrsProp,
+  linkProps,
+  resolvePressableState,
+  selectSystemProps,
+  variantProp,
+  viewProps,
+  wrapStringsInText
+} from '../utils'
+import Icon from '../Icon'
+
+const DYNAMIC_WIDTH_VARIANT = 'dynamic'
+const EQUAL_WIDTH_VARIANT = 'equal'
+
+const [selectProps, selectedSystemPropTypes] = selectSystemProps([a11yProps, linkProps, viewProps])
+
+const selectPressableStyles = (tokens, widthVariant, equalWidth) => {
+  const styles = {
+    borderColor: tokens.borderColor,
+    borderRadius: tokens.borderRadius,
+    borderWidth: tokens.borderWidth,
+    ...Platform.select({
+      web: {
+        outline: 'none'
+      }
+    })
+  }
+
+  if (widthVariant === DYNAMIC_WIDTH_VARIANT) {
+    styles.width = 'auto'
+  } else if (widthVariant === EQUAL_WIDTH_VARIANT) {
+    if (equalWidth) {
+      styles.width = equalWidth
+    } else {
+      styles.minWidth = tokens.width
+    }
+  } else {
+    styles.width = tokens.width
+  }
+
+  return styles
+}
+
+const selectIconContainerStyles = (tokens) => ({
+  paddingBottom: tokens.iconContainerPaddingBottom,
+  paddingLeft: tokens.iconContainerPaddingLeft,
+  paddingRight: tokens.iconContainerPaddingRight,
+  paddingTop: tokens.iconContainerPaddingTop
+})
+
+const selectIconVariant = () => ({
+  background: true,
+  padding: 'medium'
+})
+
+const selectIconTokens = (tokens) => ({
+  backgroundColor: tokens.iconBackgroundColor,
+  color: tokens.iconColor,
+  size: tokens.iconSize,
+  width: tokens.iconWidth
+})
+
+const selectImageStyles = (tokens) => ({
+  width: tokens.imageWidth,
+  height: tokens.imageHeight
+})
+
+const selectLabelContainerStyles = (tokens) => ({
+  paddingBottom: tokens.labelContainerPaddingBottom,
+  paddingLeft: tokens.labelContainerPaddingLeft,
+  paddingRight: tokens.labelContainerPaddingRight,
+  paddingTop: tokens.labelContainerPaddingTop
+})
+
+const selectTitleTextStyles = (tokens) =>
+  applyTextStyles({
+    fontColor: tokens.labelFontColor,
+    fontName: tokens.labelFontName,
+    fontSize: tokens.labelFontSize,
+    fontWeight: tokens.labelFontWeight,
+    lineHeight: tokens.labelLineHeight,
+    textDecorationLine: tokens.labelUnderline,
+    textAlign: tokens.labelTextAlign
+  })
+
+/**
+ * A clickable shortcut item component that displays an icon or image with an optional label.
+ * Can be used within a Shortcuts container to create a grid of navigation shortcuts.
+ *
+ * @component
+ * @param {Object} props - Component props
+ * @param {string} [props.icon] - Icon identifier to display
+ * @param {Object} [props.image={ src: '', alt: '' }] - Image object with src and alt properties
+ * @param {string} [props.image.src] - Image source URL
+ * @param {string} [props.image.alt] - Image alt text for accessibility
+ * @param {string|React.ReactNode} props.label - Label text or content to display below the icon/image
+ * @param {boolean} [props.hideLabel=false] - Whether to hide the label for this specific item
+ * @param {string} [props.href] - Link URL for navigation
+ * @param {Object} [props.iconVariant] - Icon variant to apply to this specific item
+ * @param {Object} [props.tokens] - Theme tokens to customize appearance
+ * @param {Object} [props.variant] - Variant configuration object for this specific item
+ * @param {string} [props.variant.width] - Width variant (e.g., 'dynamic', 'equal')
+ * @param {Function} [props.onPressableStateChange] - Callback function that receives the pressable state object (pressed, hovered, focused)
+ * @param {number} [props.maxWidth] - Maximum width for equal width variant (injected by Shortcuts container)
+ * @param {Function} [props.registerWidth] - Callback to register width for equal width variant (injected by Shortcuts container)
+ * @param {Object} [props.containerVariant] - Variant configuration from Shortcuts container (injected by Shortcuts container)
+ * @param {boolean} [props.containerHideLabels] - Hide labels setting from Shortcuts container (injected by Shortcuts container)
+ * @param {Object} [props.containerIconVariant] - Icon variant from Shortcuts container (injected by Shortcuts container)
+ * @param {React.Ref} ref - Forwarded ref to the Pressable component
+ * @returns {React.ReactElement} The rendered shortcut item
+ *
+ * @example
+ * <ShortcutsItem
+ *   icon={HomeIcon}
+ *   label="Home"
+ *   href="/home"
+ *   onPressableStateChange={(state) => console.log(state)}
+ * />
+ */
+const ShortcutsItem = React.forwardRef(
+  (
+    {
+      icon,
+      image = { src: '', alt: '' },
+      label,
+      hideLabel = false,
+      href,
+      iconVariant,
+      tokens,
+      variant,
+      onPressableStateChange,
+      maxWidth,
+      registerWidth,
+      containerVariant,
+      containerHideLabels,
+      containerIconVariant,
+      ...rest
+    },
+    ref
+  ) => {
+    const mergedVariant = { ...containerVariant, ...variant }
+    const widthVariant = mergedVariant?.width
+    const shouldHideLabel = hideLabel || containerHideLabels
+    const mergedIconVariant = iconVariant ?? containerIconVariant
+
+    const getThemeTokens = useThemeTokensCallback('ShortcutsItem', tokens, mergedVariant)
+    const getTokens = (pressableState) => getThemeTokens(resolvePressableState(pressableState))
+
+    const { onPress, ...props } = clickProps.toPressProps(rest)
+    const { hrefAttrs, rawRest } = hrefAttrsProp.bundle(props)
+    const selectedProps = selectProps({
+      href,
+      onPress: linkProps.handleHref({ href, onPress }),
+      hrefAttrs,
+      ...rawRest
+    })
+
+    const handleLayout = (event) => {
+      if (widthVariant === EQUAL_WIDTH_VARIANT && registerWidth) {
+        const { width } = event.nativeEvent.layout
+        registerWidth(width)
+      }
+    }
+
+    return (
+      <Pressable
+        ref={ref}
+        style={(pressableState) =>
+          selectPressableStyles(getTokens(pressableState), widthVariant, maxWidth)
+        }
+        onLayout={handleLayout}
+        {...selectedProps}
+      >
+        {(pressableState) => {
+          const themeTokens = getTokens(pressableState)
+
+          if (onPressableStateChange) {
+            onPressableStateChange(resolvePressableState(pressableState))
+          }
+
+          return (
+            <View style={staticStyles.container}>
+              {icon && (
+                <View style={selectIconContainerStyles(themeTokens)}>
+                  <Icon
+                    icon={icon}
+                    variant={mergedIconVariant ?? selectIconVariant()}
+                    tokens={mergedIconVariant ? {} : selectIconTokens(themeTokens)}
+                    {...(Platform.OS === 'web' && { accessibilityLabel: label })}
+                  />
+                </View>
+              )}
+              {!icon && image && (
+                <Image
+                  source={image.src}
+                  alt={image.alt}
+                  style={selectImageStyles(themeTokens)}
+                  resizeMethod="resize"
+                  accessibilityIgnoresInvertColors
+                />
+              )}
+              {label && !shouldHideLabel && (
+                <View style={[staticStyles.label, selectLabelContainerStyles(themeTokens)]}>
+                  {wrapStringsInText(label, { style: selectTitleTextStyles(themeTokens) })}
+                </View>
+              )}
+            </View>
+          )
+        }}
+      </Pressable>
+    )
+  }
+)
+
+ShortcutsItem.displayName = 'ShortcutsItem'
+
+ShortcutsItem.propTypes = {
+  ...selectedSystemPropTypes,
+  tokens: getTokensPropType('ShortcutsItem'),
+  variant: variantProp.propType,
+  /**
+   * Icon for the ShortcutsItem
+   */
+  icon: PropTypes.elementType,
+  /**
+   * Image for the ShortcutsItem
+   */
+  image: PropTypes.shape({
+    src: PropTypes.oneOfType([PropTypes.string, PropTypes.number, PropTypes.object]),
+    alt: PropTypes.string
+  }),
+  /**
+   * Label for the ShortcutsItem
+   */
+  label: PropTypes.string,
+  /**
+   * Hide the label for this specific ShortcutsItem. When true, the label is visually hidden but remains accessible to screen readers via the icon's accessibilityLabel.
+   */
+  hideLabel: PropTypes.bool,
+  /**
+   * href for the ShortcutsItem
+   */
+  href: PropTypes.string,
+  /**
+   * Icon variant for this specific ShortcutsItem
+   */
+  iconVariant: variantProp.propType,
+  /**
+   * Callback function that receives the pressable state object containing pressed, hovered, and focused boolean properties
+   */
+  onPressableStateChange: PropTypes.func,
+  /**
+   * Maximum width for equal width variant (automatically injected by Shortcuts container)
+   * @private
+   */
+  maxWidth: PropTypes.number,
+  /**
+   * Callback to register width for equal width variant (automatically injected by Shortcuts container)
+   * @private
+   */
+  registerWidth: PropTypes.func,
+  /**
+   * Variant configuration from Shortcuts container (automatically injected by Shortcuts container)
+   * @private
+   */
+  containerVariant: variantProp.propType,
+  /**
+   * Hide labels setting from Shortcuts container (automatically injected by Shortcuts container)
+   * @private
+   */
+  containerHideLabels: PropTypes.bool,
+  /**
+   * Icon variant from Shortcuts container (automatically injected by Shortcuts container)
+   * @private
+   */
+  containerIconVariant: variantProp.propType
+}
+
+const staticStyles = StyleSheet.create({
+  container: {
+    alignItems: 'center',
+    justifyContent: 'center'
+  },
+  label: {
+    flexWrap: 'wrap'
+  }
+})
+
+export default ShortcutsItem

package/src/Shortcuts/index.js

@@ -0,0 +1,4 @@
+import Shortcuts from './Shortcuts'
+
+export { default as ShortcutsItem } from './ShortcutsItem'
+export default Shortcuts

package/src/TextInput/TextInputBase.jsx

@@ -263,6 +263,10 @@ const TextInputBase = React.forwardRef(
         // Add a space every 4 digits starting from the 5th position
         filteredText = formattedValue.replace(regex, '$1 ').trim()
       }
+      // Apply maxLength if provided
+      if (rest.maxLength && filteredText && filteredText.length > rest.maxLength) {
+        filteredText = filteredText.substring(0, rest.maxLength)
+      }
       setValue(filteredText, event)
       if (typeof onChangeText === 'function') onChangeText(filteredText, event)
     }
@@ -340,7 +344,7 @@ const TextInputBase = React.forwardRef(
       onMouseOut: handleMouseOut,
       onChange: handleChangeText,
       defaultValue: initialValue,
-      maxLength: type === 'card' ? 19 : undefined,
+      maxLength: type === 'card' ? 19 : rest.maxLength,
       value: isControlled ? currentValue : undefined,
       onKeyPress
     }