@telus-uds/components-base 3.23.0 → 3.24.0

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/Tooltip/Tooltip.native.jsx

@@ -127,12 +127,12 @@ const Tooltip = React.forwardRef(
       nativeID,
       activateOnHover = false,
       tooltipButtonTokens,
+      testID,
       ...rest
     },
     ref
   ) => {
     const [isOpen, setIsOpen] = React.useState(false)
-
     const controlRef = React.useRef()
     const [controlLayout, setControlLayout] = React.useState(null)
     const [tooltipDimensions, setTooltipDimensions] = React.useState(null)
@@ -276,6 +276,7 @@ const Tooltip = React.forwardRef(
             }
           })
         ]}
+        testID={testID}
         {...selectProps(rest)}
       >
         <Pressable

package/src/index.js

@@ -51,6 +51,7 @@ export { default as RadioCard, RadioCardGroup } from './RadioCard'
 export { default as Responsive } from './Responsive'
 export { default as Search } from './Search'
 export { default as Select } from './Select'
+export { default as Shortcuts, ShortcutsItem } from './Shortcuts'
 export { default as SideNav } from './SideNav'
 export { default as Skeleton } from './Skeleton'
 export { default as SkipLink } from './SkipLink'

package/types/Listbox.d.ts

@@ -40,6 +40,29 @@ type ListboxTokens = {
   itemHeight?: number
   groupHeight?: number
   lineHeight?: number
+  secondLevelHeaderBackgroundColor?: string
+  secondLevelHeaderPaddingTop?: number
+  secondLevelHeaderPaddingBottom?: number
+  secondLevelHeaderPaddingLeft?: number
+  secondLevelHeaderPaddingRight?: number
+  secondLevelBackIcon?: string
+  secondLevelBackIconColor?: string
+  secondLevelBackIconSize?: number
+  secondLevelBackLinkColor?: string
+  secondLevelBackLinkFontSize?: number
+  secondLevelBackLinkFontName?: string
+  secondLevelBackLinkFontWeight?: string
+  secondLevelCloseIcon?: string
+  secondLevelCloseIconColor?: string
+  secondLevelCloseIconSize?: number
+  secondLevelCloseButtonBackgroundColor?: string
+  secondLevelCloseButtonBorderColor?: string
+  secondLevelCloseButtonBorderWidth?: number | string
+  secondLevelCloseButtonBorderRadius?: number | string
+  secondLevelCloseButtonPadding?: number
+  secondLevelDividerColor?: string
+  secondLevelDividerWidth?: number
+  secondLevelParentIcon?: string
 }
 
 type ListboxItems = {
@@ -55,6 +78,7 @@ export interface ListboxProps {
   LinkRouter?: React.ElementType
   linkRouterProps?: object
   tokens?: ListboxTokens
+  variant?: { secondLevel?: boolean }
   selectedId?: string
   onClose?: () => void
 }

package/types/Shortcuts.d.ts

@@ -0,0 +1,136 @@
+import type { ComponentType, ReactNode } from 'react'
+import type { IconVariant } from './Icon'
+
+export interface ShortcutsProps {
+  /**
+   * ShortcutsItem components to render as shortcuts.
+   */
+  children: ReactNode
+  /**
+   * Shortcuts variant options.
+   */
+  variant?: ShortcutsVariant
+  /**
+   * Custom tokens for styling the Shortcuts container.
+   */
+  tokens?: ShortcutsTokens
+  /**
+   * Hide labels for all shortcuts items globally.
+   * Can be overridden by individual ShortcutsItem hideLabel prop.
+   */
+  hideLabels?: boolean
+  /**
+   * Icon variant to apply to all shortcuts items.
+   * Can be overridden by individual ShortcutsItem iconVariant prop.
+   */
+  iconVariant?: IconVariant
+}
+
+export type ShortcutsVariant = {
+  /**
+   * Width distribution of shortcuts items.
+   * - 'equal': All items have equal width (default)
+   * - 'dynamic': Items size based on content
+   */
+  width?: 'equal' | 'dynamic'
+}
+
+export interface ShortcutsTokens {
+  mainContainerGap?: number
+  mainContainerPaddingHorizontal?: number
+  mainContainerPaddingVertical?: number
+  itemContainerMinHeight?: number
+  itemContainerPaddingHorizontal?: number
+  itemContainerPaddingVertical?: number
+  itemContainerBackgroundColor?: string
+  itemContainerBorderRadius?: number
+  labelFontColor?: string
+  labelFontSize?: number
+  labelFontWeight?: number
+  labelLineHeight?: number
+  labelMarginTop?: number
+}
+
+export interface ShortcutsItemProps {
+  /**
+   * Label text for the shortcut item.
+   */
+  label: string
+  /**
+   * Icon component to display.
+   */
+  icon?: ComponentType<any>
+  /**
+   * Image to display instead of icon.
+   */
+  image?: ShortcutsItemImage
+  /**
+   * URL to navigate to when pressed.
+   */
+  href?: string
+  /**
+   * Function to call when the item is pressed.
+   */
+  onPress?: () => void
+  /**
+   * Hide the label for this specific item.
+   * Overrides parent Shortcuts hideLabels prop.
+   */
+  hideLabel?: boolean
+  /**
+   * Icon variant for this specific item.
+   * Overrides parent Shortcuts iconVariant prop.
+   */
+  iconVariant?: IconVariant
+  /**
+   * Custom tokens for styling this item.
+   */
+  tokens?: ShortcutsItemTokens
+  /**
+   * Variant options for this item.
+   */
+  variant?: ShortcutsItemVariant
+  /**
+   * Callback function that receives the pressable state.
+   * Can be used to dynamically set iconVariant based on press state.
+   */
+  onPressableStateChange?: (state: PressableState) => IconVariant | void
+}
+
+export type ShortcutsItemImage = {
+  src: string
+  alt: string
+}
+
+export type ShortcutsItemVariant = {
+  /**
+   * Whether the item is in a pressed state.
+   */
+  pressed?: boolean
+}
+
+export interface ShortcutsItemTokens {
+  containerMinHeight?: number
+  containerPaddingHorizontal?: number
+  containerPaddingVertical?: number
+  containerBackgroundColor?: string
+  containerBorderRadius?: number
+  labelFontColor?: string
+  labelFontSize?: number
+  labelFontWeight?: number
+  labelLineHeight?: number
+  labelMarginTop?: number
+  iconSize?: number
+}
+
+export type PressableState = {
+  pressed: boolean
+  hovered?: boolean
+  focused?: boolean
+}
+
+declare const Shortcuts: ComponentType<ShortcutsProps>
+declare const ShortcutsItem: ComponentType<ShortcutsItemProps>
+
+export { Shortcuts, ShortcutsItem }
+export default Shortcuts

package/types/index.d.ts

@@ -51,6 +51,18 @@ export { SearchTokens, SearchProps } from './Search'
 export { default as Select } from './Select'
 export { SelectTokens, SelectProps, SelectItemProps, SelectGroupProps } from './Select'
 
+export { default as Shortcuts, ShortcutsItem } from './Shortcuts'
+export {
+  ShortcutsProps,
+  ShortcutsTokens,
+  ShortcutsVariant,
+  ShortcutsItemProps,
+  ShortcutsItemTokens,
+  ShortcutsItemVariant,
+  ShortcutsItemImage,
+  PressableState
+} from './Shortcuts'
+
 export { default as Spacer } from './Spacer'
 export { SpacerProps } from './Spacer'