@telus-uds/components-base 4.0.0-alpha.0 → 4.0.0-alpha.1

package/src/Carousel/CarouselThumbnail.jsx

@@ -1,9 +1,10 @@
 import React from 'react'
 import PropTypes from 'prop-types'
-import { Pressable, Image } from 'react-native'
+import { StyleSheet, Pressable, Image, View } from 'react-native'
 import { useCarousel } from './CarouselContext'
 import { useThemeTokensCallback } from '../ThemeProvider/useThemeTokens'
 import { useViewport } from '../ViewportProvider/useViewport'
+import { Icon } from '../Icon/Icon'
 
 const selectPressableTokens = ({ borderColor, borderRadius, borderWidth, margin, padding }) => ({
   borderColor,
@@ -13,12 +14,47 @@ const selectPressableTokens = ({ borderColor, borderRadius, borderWidth, margin,
   padding
 })
 
+// Play icon overlay appearance is consistent across all brands and is not theme-configurable.
+// The circle occupies 55% of the thumbnail size, and the icon occupies 55% of the circle diameter.
+const PLAY_ICON_RATIO = 0.55
+const PLAY_ICON_BORDER_RADIUS_DIVISOR = 2
+
+const selectImageStyles = (size) => ({
+  width: size,
+  height: size
+})
+
+const selectSelectedStyles = ({ selectedBorderColor, selectedBorderWidth, padding, margin }) => ({
+  borderColor: selectedBorderColor,
+  borderWidth: selectedBorderWidth,
+  padding: padding - selectedBorderWidth,
+  marginBottom: margin + selectedBorderWidth
+})
+
+const selectNonSelectedStyles = ({ borderWidth, padding, margin, selectedBorderWidth }) => ({
+  padding: padding - borderWidth,
+  marginBottom: margin + selectedBorderWidth
+})
+
+const selectPlayIconCircleStyles = (thumbnailSize) => {
+  const diameter = thumbnailSize * PLAY_ICON_RATIO
+  return {
+    width: diameter,
+    height: diameter,
+    borderRadius: diameter / PLAY_ICON_BORDER_RADIUS_DIVISOR
+  }
+}
+
+const selectPlayIconTokens = (thumbnailSize) => ({
+  size: thumbnailSize * PLAY_ICON_RATIO * PLAY_ICON_RATIO
+})
+
 /**
- * `Carousel.Thumbnail` is used to wrap the content of an individual slide and is suppsoed to be the
+ * `CarouselThumbnail` is used to wrap the content of an individual slide and is suppsoed to be the
  * only top-level component passed to the `Carousel`
  */
 export const CarouselThumbnail = React.forwardRef(
-  ({ accessibilityLabel, alt, index, src }, ref) => {
+  ({ accessibilityLabel, alt, index, isVideo, src }, ref) => {
     const { activeIndex, itemLabel, totalItems, getCopyWithPlaceholders, goTo } = useCarousel()
     const getThumbnailTokens = useThemeTokensCallback('CarouselThumbnail')
     const viewport = useViewport()
@@ -33,24 +69,15 @@ export const CarouselThumbnail = React.forwardRef(
       // Allow using the spacebar for navigation
       if (event?.key === ' ') goTo(index)
     }
-    const { borderWidth, padding, selectedBorderColor, selectedBorderWidth, size, margin } =
-      getThumbnailTokens({ viewport })
-    const styles = {
-      image: {
-        height: size,
-        width: size
-      },
-      selected: {
-        borderColor: selectedBorderColor,
-        borderWidth: selectedBorderWidth,
-        padding: padding - selectedBorderWidth,
-        marginBottom: margin + selectedBorderWidth
-      },
-      nonSelected: {
-        padding: padding - borderWidth,
-        marginBottom: margin + selectedBorderWidth
-      }
-    }
+    const {
+      borderWidth,
+      padding,
+      selectedBorderColor,
+      selectedBorderWidth,
+      size,
+      margin,
+      playIcon
+    } = getThumbnailTokens({ viewport })
 
     return (
       <Pressable
@@ -68,18 +95,48 @@ export const CarouselThumbnail = React.forwardRef(
 
           return [
             pressableStyles,
-            index === activeIndex ? [styles.selected, { outline: 'none' }] : styles.nonSelected
+            index === activeIndex
+              ? [
+                  selectSelectedStyles({
+                    selectedBorderColor,
+                    selectedBorderWidth,
+                    padding,
+                    margin
+                  }),
+                  staticStyles.selectedPressableOutline
+                ]
+              : selectNonSelectedStyles({ borderWidth, padding, margin, selectedBorderWidth })
           ]
         }}
         ref={ref}
       >
-        <Image
-          accessibilityIgnoresInvertColors
-          accessibilityLabel={accessibilityLabel ?? alt}
-          source={src}
-          style={styles.image}
-          title={thumbnailTitle}
-        />
+        <View style={[staticStyles.imageContainer, selectImageStyles(size)]}>
+          <Image
+            accessibilityIgnoresInvertColors
+            accessibilityLabel={accessibilityLabel ?? alt}
+            source={src}
+            style={selectImageStyles(size)}
+            title={thumbnailTitle}
+          />
+          {isVideo && playIcon && (
+            <View
+              style={staticStyles.playIconOverlayContainer}
+              testID={`play-icon-overlay-${index}`}
+            >
+              <View
+                style={[selectPlayIconCircleStyles(size), staticStyles.playIconCircleBackground]}
+              >
+                <Icon
+                  icon={playIcon}
+                  tokens={{
+                    ...selectPlayIconTokens(size),
+                    color: staticStyles.playIconSymbol.color
+                  }}
+                />
+              </View>
+            </View>
+          )}
+        </View>
       </Pressable>
     )
   }
@@ -88,8 +145,38 @@ export const CarouselThumbnail = React.forwardRef(
 CarouselThumbnail.displayName = 'CarouselThumbnail'
 
 CarouselThumbnail.propTypes = {
+  /** Accessibility label for screen readers, overrides the alt text */
   accessibilityLabel: PropTypes.string,
+  /** Alt text for the thumbnail image */
   alt: PropTypes.string,
+  /** Zero-based index of this thumbnail within the carousel */
   index: PropTypes.number,
-  src: PropTypes.string
+  /**
+   * When true, renders a play icon overlay on the thumbnail to indicate that the slide contains a video.
+   */
+  isVideo: PropTypes.bool,
+  /** Image source URI (web) or local asset require() (native) */
+  src: PropTypes.oneOfType([PropTypes.string, PropTypes.number])
 }
+
+const staticStyles = StyleSheet.create({
+  imageContainer: {
+    position: 'relative'
+  },
+  playIconOverlayContainer: {
+    position: 'absolute',
+    top: 0,
+    left: 0,
+    right: 0,
+    bottom: 0,
+    justifyContent: 'center',
+    alignItems: 'center'
+  },
+  selectedPressableOutline: { outlineStyle: 'none' },
+  playIconCircleBackground: {
+    backgroundColor: 'rgba(0, 0, 0, 0.6)',
+    justifyContent: 'center',
+    alignItems: 'center'
+  },
+  playIconSymbol: { color: 'rgb(255, 255, 255)' }
+})

package/src/Carousel/CarouselThumbnailNavigation.jsx

@@ -27,11 +27,12 @@ export const CarouselThumbnailNavigation = React.forwardRef(({ thumbnails = [] }
   return (
     <View style={containerStyles}>
       <StackWrap direction="row" tokens={stackWrapTokens} space={2} ref={ref}>
-        {thumbnails.map(({ accessibilityLabel, alt, src }, index) => (
+        {thumbnails.map(({ accessibilityLabel, alt, isVideo, src }, index) => (
           <CarouselThumbnail
             accessibilityLabel={accessibilityLabel}
             alt={alt}
             index={index}
+            isVideo={isVideo}
             key={src}
             src={src}
           />
@@ -47,9 +48,14 @@ CarouselThumbnailNavigation.propTypes = {
    */
   thumbnails: PropTypes.arrayOf(
     PropTypes.shape({
+      /** Accessibility label for the thumbnail image, used by assistive technologies. */
       accessibilityLabel: PropTypes.string,
+      /** Alternative text for the thumbnail image, displayed when the image cannot be rendered. */
       alt: PropTypes.string,
-      src: PropTypes.string
+      /** When true, renders a play icon overlay on the thumbnail to indicate that the slide contains a video. */
+      isVideo: PropTypes.bool,
+      /** URL or path of the thumbnail image. When used with `isVideo`, this should be the video's poster/preview image. */
+      src: PropTypes.oneOfType([PropTypes.string, PropTypes.number])
     })
   ).isRequired
 }

package/src/InputSupports/InputSupports.jsx

@@ -67,12 +67,7 @@ export const InputSupports = React.forwardRef(
           />
         )}
         {typeof children === 'function'
-          ? children({
-              inputId,
-              ...a11yProps,
-              validation: feedbackValidation,
-              accessibilityDescribedBy: feedbackId
-            })
+          ? children({ inputId, ...a11yProps, validation: feedbackValidation })
           : children}
         {feedback || maxCharsReachedErrorMessage ? (
           <Feedback

package/src/InputSupports/useInputSupports.js

@@ -31,8 +31,8 @@ export const useInputSupports = ({
         : undefined
     ]), // native only -> replaced with describedBy on web
     accessibilityDescribedBy: joinDefined([
-      !hasValidationError && feedback && feedbackId, // feedback receives a11yRole=alert on error, so there's no need to include it here
       hint && hintId,
+      (feedback && feedbackId) || undefined,
       charactersCount
         ? getCopy('charactersRemaining').replace(/%\{charCount\}/g, charactersCount)
         : undefined

package/src/Link/ChevronLink.jsx

@@ -53,8 +53,7 @@ ChevronLink.propTypes = {
   children: PropTypes.node,
   variant: PropTypes.exact({
     size: PropTypes.oneOf(['large', 'small', 'micro']),
-    alternative: PropTypes.bool,
-    inverse: PropTypes.bool
+    style: PropTypes.oneOf(['inline', 'subtle', 'feature', 'danger', 'inverse'])
   }),
   ...linkProps.types,
   tokens: getTokensPropType('ChevronLink', 'Link'),

package/src/Notification/Notification.jsx

@@ -227,11 +227,10 @@ const getDefaultStyles = (
  * ### Variants
  * - Use `variant.style` to set the visual style of the notification
  * - Use `dismissible` prop to enable dismissible functionality
- * - Use `system` prop to set the visual style of the notification and denote an announcement from the system or application
  *
- * ### When to use the system prop?
- * - Use `system` to show system-based messages coming from the application
- * - Don’t use `system` when the message is in response to user action
+ * ### When to use the system style variant?
+ * - Use `variant.style ‘system’` to show system-based messages coming from the application
+ * - Don’t use the `system` style variant when the message is in response to user action
  *
  * ## Variants
  *
@@ -263,25 +262,14 @@ const getDefaultStyles = (
  */
 export const Notification = React.forwardRef(
   (
-    {
-      children,
-      system,
-      dismissible,
-      copy = 'en',
-      tokens,
-      variant,
-      onDismiss,
-      contentMinWidth,
-      ...rest
-    },
+    { children, dismissible, copy = 'en', tokens, variant, onDismiss, contentMinWidth, ...rest },
     ref
   ) => {
     const [isDismissed, setIsDismissed] = React.useState(false)
     const viewport = useViewport()
     const getCopy = useCopy({ dictionary, copy })
 
-    // TODO: Remove this once the system style variant is deprecated
-    const isSystemEnabled = system || variant?.style?.includes('system')
+    const isSystemEnabled = variant?.style?.includes('system')
 
     const { themeOptions } = useTheme()
     const { enableMediaQueryStyleSheet } = themeOptions
@@ -442,10 +430,6 @@ Notification.propTypes = {
    * Content of the `Notification`.
    */
   children: PropTypes.oneOfType([PropTypes.string, PropTypes.node, PropTypes.func]),
-  /**
-   * Use `system` prop to set the visual style of the notification and denote an announcement from the system or application
-   */
-  system: PropTypes.bool,
   /**
    * Use the `dismissible` prop to allow users to dismiss the Notification at any time.
    */

package/src/Progress/ProgressBar.jsx

@@ -48,9 +48,9 @@ const selectBarStyles = ({ themeTokens, calculatedPercentage, barPosition, layer
  *
  * ## Variants
  *
- * - Use the following variants to render specific types of progress bars:
- *   - `negative`: set to `true` if you wish to use the negative theming for progress bar filling,
- *   - `inactive`: set to `true` if you wish to style the progress bar as inactive.
+ * - Use `variant={{ style: 'value' }}` to render specific types of progress bars:
+ *   - `style: 'negative'` for negative theming for progress bar filling,
+ *   - `style: 'inactive'` to style the progress bar as inactive.
  *
  * ## Usability and A11y guidelines
  *

package/src/Progress/ProgressBarBackground.jsx

@@ -9,10 +9,9 @@ const negativeBackground = `%3Csvg xmlns='http://www.w3.org/2000/svg' width='100
 
 export const ProgressBarBackground = React.forwardRef(({ variant }, ref) => {
   let source = null
-  // TODO: Remove the `variant?.inactive` & `variant?.negative` to complete the deprecation
-  if (variant?.inactive || variant?.style === INACTIVE_VARIANT) {
+  if (variant?.style === INACTIVE_VARIANT) {
     source = inactiveBackground
-  } else if (variant?.negative || variant?.style === NEGATIVE_VARIANT) {
+  } else if (variant?.style === NEGATIVE_VARIANT) {
     source = negativeBackground
   } else {
     return null

package/src/QuickLinks/QuickLinks.jsx

@@ -1,10 +1,12 @@
 import React from 'react'
 import PropTypes from 'prop-types'
 
+import { Platform } from 'react-native'
 import { useThemeTokens } from '../ThemeProvider/useThemeTokens'
 import { useViewport } from '../ViewportProvider/useViewport'
 import { getTokensPropType } from '../utils/props/tokens'
 import { variantProp } from '../utils/props/variantProp'
+import { tagsToRoles } from '../utils/a11y/semantics'
 
 import { List } from '../List/List'
 import { StackWrap } from '../StackView/StackWrap'
@@ -28,6 +30,11 @@ export const QuickLinks = React.forwardRef(
       }
     )
 
+    const itemAccessibilityRole = Platform.select({
+      web: ['ul', 'ol'].includes(tag) ? tagsToRoles.li : undefined,
+      default: undefined
+    })
+
     const content = (list && (
       <List ref={ref} tokens={listTokens} showDivider={dividers} tag={tag} {...rest}>
         {children}
@@ -38,6 +45,7 @@ export const QuickLinks = React.forwardRef(
         gap={stackGap}
         tokens={{ justifyContent: stackJustify }}
         tag={tag}
+        itemAccessibilityRole={itemAccessibilityRole}
         {...rest}
       >
         {children}

package/src/StackView/StackWrapBox.jsx

@@ -55,6 +55,7 @@ export const StackWrapBox = React.forwardRef(
       variant,
       tag,
       accessibilityRole,
+      itemAccessibilityRole,
       ...rest
     },
     ref
@@ -73,7 +74,12 @@ export const StackWrapBox = React.forwardRef(
     const gapSize = useSpacingScale(gap)
     const offsetStyle = { [offsetSides[direction]]: -1 * gapSize }
     const boxProps = { [gapSides[direction]]: gap, [spaceSides[direction]]: space }
-    const content = getStackedContent(children, { direction, space: 0, box: boxProps })
+    const content = getStackedContent(children, {
+      direction,
+      space: 0,
+      box: boxProps,
+      itemAccessibilityRole
+    })
 
     return (
       <View
@@ -116,6 +122,12 @@ StackWrapBox.propTypes = {
    * is not defined, the accessibilityRole will default to "heading".
    */
   tag: PropTypes.oneOf(layoutTags),
+  /**
+   * Optional accessibility role to apply to each item in the stack.
+   * On web, items are wrapped (or cloned) with this role, enabling correct list semantics
+   * when the container tag is "ul" or "ol".
+   */
+  itemAccessibilityRole: PropTypes.string,
   /**
    * A StackWrap may take any children, but will have no effect if it is only passed one child or is passed children
    * wrapped in a component. If necessary, children may be wrapped in one React Fragment.

package/src/StackView/StackWrapGap.jsx

@@ -35,6 +35,7 @@ export const StackWrapGap = React.forwardRef(
       children,
       tag,
       accessibilityRole,
+      itemAccessibilityRole,
       ...rest
     },
     ref
@@ -52,7 +53,7 @@ export const StackWrapGap = React.forwardRef(
     const size = useSpacingScale(space)
     const gapStyle = { gap: size }
 
-    const content = getStackedContent(children, { direction, space: 0 })
+    const content = getStackedContent(children, { direction, space: 0, itemAccessibilityRole })
 
     return (
       <View

package/src/StackView/getStackedContent.jsx

@@ -32,7 +32,7 @@ import { Spacer } from '../Spacer/Spacer'
  */
 export const getStackedContent = (
   children,
-  { divider, space, direction = 'column', box, preserveFragments = false }
+  { divider, space, direction = 'column', box, preserveFragments = false, itemAccessibilityRole }
 ) => {
   const boxProps = box && typeof box === 'object' ? box : { space }
   const dividerProps = divider && typeof divider === 'object' ? divider : {}
@@ -42,15 +42,29 @@ export const getStackedContent = (
   const validChildren = React.Children.toArray(topLevelChildren).filter(Boolean)
   const content = validChildren.reduce((newChildren, child, index) => {
     const boxID = `Stack-Box-${index}`
-    const item = box ? (
+
+    let item
+    if (box) {
       // If wrapped in Box, that Box needs a key.
       // If possible, use an existing content key; use an index-based key only if necessary.
-      <Box {...boxProps} key={child.key || boxID} testID={boxID}>
-        {child}
-      </Box>
-    ) : (
-      child
-    )
+      item = (
+        <Box
+          {...boxProps}
+          accessibilityRole={itemAccessibilityRole}
+          key={child.key || boxID}
+          testID={boxID}
+        >
+          {child}
+        </Box>
+      )
+    } else if (itemAccessibilityRole) {
+      item = React.cloneElement(child, {
+        accessibilityRole: itemAccessibilityRole,
+        key: child.key || boxID
+      })
+    } else {
+      item = child
+    }
     if (!index || (!space && !divider)) return [...newChildren, item]
 
     const testID = `Stack-${divider ? 'Divider' : 'Spacer'}-${index}`

package/types/Link.d.ts

@@ -22,8 +22,7 @@ export enum LinkSize {
 
 export type LinkAndTextButtonVariants = {
   size?: 'large' | 'small' | 'micro'
-  alternative?: boolean
-  inverse?: boolean
+  style?: 'inline' | 'subtle' | 'feature' | 'danger' | 'inverse'
 }
 
 export type LinkTokens = {