@telus-uds/components-base 1.12.0 → 1.14.0

package/src/Carousel/Carousel.jsx

@@ -11,15 +11,17 @@ import {
   selectSystemProps,
   a11yProps,
   viewProps,
-  useCopy
+  useCopy,
+  unpackFragment
 } from '../utils'
 import { useA11yInfo } from '../A11yInfoProvider'
 import { CarouselProvider } from './CarouselContext'
 import CarouselItem from './CarouselItem'
-import StepTracker from '../StepTracker'
-import StackView from '../StackView'
 import IconButton from '../IconButton'
-
+import SkipLink from '../SkipLink'
+import A11yText from '../A11yText'
+import CarouselStepTracker from './CarouselStepTracker'
+import CarouselThumbnailNavigation from './CarouselThumbnailNavigation'
 import dictionary from './dictionary'
 
 const staticStyles = StyleSheet.create({
@@ -33,19 +35,6 @@ const staticStyles = StyleSheet.create({
   }
 })
 
-const staticTokens = {
-  stackView: {
-    justifyContent: 'center'
-  },
-  stepTracker: {
-    showStepLabel: false,
-    showStepTrackerLabel: true,
-    knobCompletedBackgroundColor: 'none',
-    connectorCompletedColor: 'none',
-    connectorColor: 'none'
-  }
-}
-
 const selectContainerStyles = (width) => ({
   backgroundColor: 'transparent',
   overflow: 'hidden',
@@ -160,27 +149,36 @@ const Carousel = React.forwardRef(
       onAnimationStart,
       onAnimationEnd,
       onIndexChanged,
+      skipLinkHref,
+      refocus,
+      title = 'carousel',
       springConfig = undefined,
-      onRenderPanelNavigation,
+      thumbnails = undefined,
+      panelNavigation = thumbnails ? (
+        <CarouselThumbnailNavigation thumbnails={thumbnails} />
+      ) : (
+        <CarouselStepTracker />
+      ),
       tag = 'ul',
-      accessibilityRole = 'adjustable',
-      accessibilityLabel = 'carousel',
+      accessibilityRole,
+      accessibilityLabel = title,
+      accessibilityLiveRegion = 'polite',
       copy,
       ...rest
     },
     ref
   ) => {
     const viewport = useViewport()
+    const themeTokens = useThemeTokens('Carousel', tokens, variant, {
+      viewport
+    })
     const {
       previousIcon,
       nextIcon,
       showPreviousNextNavigation,
       showPanelNavigation,
-      spaceBetweenSlideAndPreviousNextNavigation,
-      spaceBetweenSlideAndPanelNavigation
-    } = useThemeTokens('Carousel', tokens, variant, {
-      viewport
-    })
+      spaceBetweenSlideAndPreviousNextNavigation
+    } = themeTokens
     const [activeIndex, setActiveIndex] = React.useState(0)
 
     const [isAnimating, setIsAnimating] = React.useState(false)
@@ -201,7 +199,7 @@ const Carousel = React.forwardRef(
 
     const getCopy = useCopy({ dictionary, copy })
 
-    const childrenArray = React.Children.toArray(children)
+    const childrenArray = unpackFragment(children)
     const systemProps = selectProps({
       ...rest,
       accessibilityRole,
@@ -220,15 +218,12 @@ const Carousel = React.forwardRef(
     })
     const [previousNextNavigationButtonWidth, setPreviousNextNavigationButtonWidth] =
       React.useState(0)
+    const firstFocusRef = React.useRef(null)
     const pan = React.useRef(new Animated.ValueXY()).current
     const animatedX = React.useRef(0)
     const animatedY = React.useRef(0)
     const isFirstSlide = !activeIndex
     const isLastSlide = activeIndex + 1 >= children.length
-    const panelNavigationTokens = {
-      ...staticTokens.stepTracker,
-      containerPaddingTop: spaceBetweenSlideAndPanelNavigation
-    }
 
     const onContainerLayout = ({
       nativeEvent: {
@@ -308,8 +303,9 @@ const Carousel = React.forwardRef(
         updateOffset()
         handleAnimationStart(activeIndex)
         updateIndex(delta)
+        if (refocus) firstFocusRef.current?.focus()
       },
-      [updateIndex, updateOffset, activeIndex, handleAnimationStart]
+      [updateIndex, updateOffset, activeIndex, handleAnimationStart, refocus]
     )
 
     const goToNeighboring = React.useCallback(
@@ -405,22 +401,31 @@ const Carousel = React.forwardRef(
     // Related discussion - https://github.com/telus/universal-design-system/issues/1549
     const previousNextIconButtonVariants = { size: previousNextIconSize, raised: true }
 
-    const getCopyWithPlaceholders = (copyKey) => {
-      const copyText = getCopy(copyKey)
-        .replace(/%\{itemLabel\}/g, itemLabel)
-        .replace(/%\{stepNumber\}/g, activeIndex + 1)
-        .replace(/%\{stepCount\}/g, childrenArray.length)
+    const getCopyWithPlaceholders = React.useCallback(
+      (copyKey) => {
+        const copyText = getCopy(copyKey)
+          .replace(/%\{title\}/g, title)
+          .replace(/%\{itemLabel\}/g, itemLabel)
+          .replace(/%\{stepNumber\}/g, activeIndex + 1)
+          .replace(/%\{stepCount\}/g, childrenArray.length)
 
-      // First word might be a lowercase placeholder: capitalize the first letter
-      return `${copyText[0].toUpperCase()}${copyText.slice(1)}`
-    }
+        // First word might be a lowercase placeholder: capitalize the first letter
+        return `${copyText[0].toUpperCase()}${copyText.slice(1)}`
+      },
+      [activeIndex, childrenArray.length, itemLabel, getCopy, title]
+    )
 
     return (
       <CarouselProvider
         activeIndex={activeIndex}
+        goTo={goTo}
+        getCopyWithPlaceholders={getCopyWithPlaceholders}
+        itemLabel={itemLabel}
         totalItems={childrenArray.length}
+        themeTokens={themeTokens}
+        firstFocusRef={firstFocusRef}
+        refocus={refocus}
         width={containerLayout.width}
-        goTo={goTo}
       >
         <View style={staticStyles.root} onLayout={onContainerLayout} ref={ref} {...systemProps}>
           {showPreviousNextNavigation && (
@@ -447,6 +452,19 @@ const Carousel = React.forwardRef(
               />
             </View>
           )}
+          {Boolean(skipLinkHref) && (
+            <SkipLink ref={firstFocusRef} href={skipLinkHref}>
+              {getCopyWithPlaceholders('skipLink')}
+            </SkipLink>
+          )}
+          <A11yText
+            // Read the current slide position to screen readers on slide.
+            // If it's set to refocus and doesn't have a SkipLink to focus to, focus this.
+            ref={!skipLinkHref && refocus ? firstFocusRef : null}
+            accessibilityLiveRegion={!skipLinkHref && refocus ? undefined : 'polite'}
+            focusable={!skipLinkHref && refocus}
+            text={getCopyWithPlaceholders('stepTrackerLabel')}
+          />
           <View style={selectContainerStyles(containerLayout.width)}>
             <Animated.View
               style={StyleSheet.flatten([
@@ -457,6 +475,9 @@ const Carousel = React.forwardRef(
               ])}
               {...panResponder.panHandlers}
               {...getA11yPropsFromHtmlTag(tag)}
+              // In iframes on Mac (e.g. in Storybook), this content may be misread or read twice.
+              // This is a known Voiceover bug: https://github.com/phetsims/a11y-research/issues/132
+              accessibilityLiveRegion={accessibilityLiveRegion}
             >
               {childrenArray.map((element, index) => {
                 const hidden = !isAnimating && index !== activeIndex
@@ -490,24 +511,7 @@ const Carousel = React.forwardRef(
             </View>
           )}
         </View>
-        {showPanelNavigation ? (
-          <StackView direction="row" tokens={staticTokens.stackView}>
-            {onRenderPanelNavigation ? (
-              onRenderPanelNavigation({ activeIndex, totalItems: childrenArray.length })
-            ) : (
-              <StepTracker
-                current={activeIndex}
-                steps={childrenArray.map((_, index) => String(index))}
-                copy={{
-                  // Give StepTracker copy from Carousel's language and dictionary
-                  stepLabel: getCopyWithPlaceholders('stepLabel'),
-                  stepTrackerLabel: getCopyWithPlaceholders('stepTrackerLabel')
-                }}
-                tokens={panelNavigationTokens}
-              />
-            )}
-          </StackView>
-        ) : null}
+        {showPanelNavigation ? panelNavigation : null}
       </CarouselProvider>
     )
   }
@@ -542,6 +546,16 @@ Carousel.propTypes = {
    * Carousel uses `Animated.spring` to animate slide changes, use this option to pass custom animation configuration
    */
   springConfig: PropTypes.object,
+  /**
+   * An array of objects containing information on the thumbnails to be rendered as navigation panel
+   */
+  thumbnails: PropTypes.arrayOf(
+    PropTypes.shape({
+      accessibilityLabel: PropTypes.string,
+      alt: PropTypes.string,
+      src: PropTypes.string
+    })
+  ),
   /**
    * Minimal part of slide width must be swiped for changing index.
    * Otherwise animation restore current slide. Default value 0.2 means that 20% must be swiped for change index
@@ -569,20 +583,33 @@ Carousel.propTypes = {
    */
   onIndexChanged: PropTypes.func,
   /**
-   * Use this to render a custom panel navigation element instead of dots navigation
-   * This function is also provided with an object with the following properties
-   * activeIndex: index of current slide
-   * totalItems: total number of slides
+   * If this is a complex carousel with a lot of focusable content, pass a href for a skip link. Typically, this will be an anchor link
+   * with the ID of a focusable element immediately after the Carousel, e.g. `'#section-2-heading'`.
+   */
+  skipLinkHref: PropTypes.string,
+  /**
+   * If true, whenever a new slide comes into view, the focus of the Carousel switches to the start.
+   *
+   * Pass this as true when using carousel items that contain interactive content, so a user can easily tab into that content.
+   *
+   * If skipLinkHref is passed, the focus target will be the SkipLink; if not, it'll be an empty element before the slide content.
+   */
+  refocus: PropTypes.bool,
+  /**
+   * Use this to render a custom panel navigation element instead of the default StepTracker's based navigation
+   * You can make use of `useCarousel` within your custom panel navigation component to hook into various Carousel states such as:
+   * - activeIndex: index of current slide
+   * - totalItems: total number of slides
    * Use it as follows:
    * ```js
    *    <Carousel
-   *      onRenderPanelNavigation={({ totalItems, activeIndex }) => <Text>Showing {activeIndex + 1}</Text>}
+   *      panelNavigation={<CustomPanelNavigation />}
    *    >
    *      <Carousel.Item>First Slide</Carousel.Item>
    *    </Carousel>
    * ```
    */
-  onRenderPanelNavigation: PropTypes.func,
+  panelNavigation: PropTypes.element,
   /**
    * When slide animation start
    * This function is also provided with a parameter indicating the current slide index before animation starts

package/src/Carousel/CarouselContext.jsx

@@ -1,12 +1,32 @@
 import React from 'react'
 import PropTypes from 'prop-types'
+import { getTokensPropType } from '../utils'
 
 const CarouselContext = React.createContext()
 
-const CarouselProvider = ({ children, activeIndex, totalItems, width, goTo }) => {
+const CarouselProvider = ({
+  activeIndex,
+  children,
+  goTo,
+  getCopyWithPlaceholders,
+  itemLabel,
+  refocus = false,
+  themeTokens,
+  totalItems,
+  width
+}) => {
   const value = React.useMemo(
-    () => ({ activeIndex, totalItems, width, goTo }),
-    [activeIndex, totalItems, width, goTo]
+    () => ({
+      activeIndex,
+      goTo,
+      getCopyWithPlaceholders,
+      itemLabel,
+      refocus,
+      themeTokens,
+      totalItems,
+      width
+    }),
+    [activeIndex, goTo, getCopyWithPlaceholders, itemLabel, refocus, totalItems, themeTokens, width]
   )
   return <CarouselContext.Provider value={value}>{children}</CarouselContext.Provider>
 }
@@ -22,9 +42,13 @@ function useCarousel() {
 CarouselProvider.propTypes = {
   children: PropTypes.arrayOf(PropTypes.element).isRequired,
   activeIndex: PropTypes.number.isRequired,
+  goTo: PropTypes.func.isRequired,
+  getCopyWithPlaceholders: PropTypes.func.isRequired,
+  itemLabel: PropTypes.string.isRequired,
+  refocus: PropTypes.bool,
+  themeTokens: getTokensPropType('Carousel'),
   totalItems: PropTypes.number.isRequired,
-  width: PropTypes.number.isRequired,
-  goTo: PropTypes.func.isRequired
+  width: PropTypes.number.isRequired
 }
 
 export { CarouselProvider, useCarousel }

package/src/Carousel/CarouselFirstFocus/CarouselFirstFocus.jsx

@@ -0,0 +1,49 @@
+import React, { forwardRef } from 'react'
+import { Pressable, Platform, StyleSheet } from 'react-native'
+import { PropTypes } from 'prop-types'
+
+import { useCarousel } from '../CarouselContext'
+
+/**
+ * Focus target so that when a new slide is shown, the user can tab into
+ * its content using the keyboard.
+ *
+ * @TODO rework this after integrating with SkipLink when available.
+ */
+const CarouselFirstFocus = forwardRef(({ title }, ref) => {
+  const { getCopyWithPlaceholders } = useCarousel()
+
+  // TODO: integrate skip link description if behaving as skip link.
+  // Consider moving this content to aria-live area while only the skip link is focused.
+  const accessibilityLabel = `${title}, ${getCopyWithPlaceholders('stepTrackerLabel')}`
+
+  const accessibilityRole = Platform.select({
+    web: 'link', // The focused item will ultimately be a skip link.
+    default: 'button' // 'link' role usually denotes opening browser on Native.
+  })
+
+  return (
+    <Pressable
+      // TODO: integrate skip link functionality, jump focus to after Carousel
+      onPress={undefined}
+      ref={ref}
+      accessibilityLabel={accessibilityLabel}
+      accessibilityRole={accessibilityRole}
+      style={StyleSheet.absoluteFill}
+      focusable
+    />
+  )
+})
+
+CarouselFirstFocus.displayName = 'CarouselFirstFocus'
+CarouselFirstFocus.propTypes = {
+  /**
+   * Simple description of this carousel for screenreaders, to be read before
+   * "{itemLabel} {index} of {count}.
+   *
+   * For example, "Summer offers" in "Summer offers, offer 1 of 3"
+   */
+  title: PropTypes.string
+}
+
+export default CarouselFirstFocus

package/src/Carousel/CarouselStepTracker/CarouselStepTracker.jsx

@@ -0,0 +1,36 @@
+import React from 'react'
+import { useCarousel } from '../CarouselContext'
+import StepTracker from '../../StepTracker'
+import StackView from '../../StackView'
+
+const CarouselStepTracker = () => {
+  const { activeIndex, totalItems, getCopyWithPlaceholders, themeTokens } = useCarousel()
+  const stackViewTokens = {
+    justifyContent: 'center'
+  }
+  const stepTrackerTokens = {
+    showStepLabel: false,
+    showStepTrackerLabel: true,
+    knobCompletedBackgroundColor: 'none',
+    connectorCompletedColor: 'none',
+    connectorColor: 'none',
+    containerPaddingTop: themeTokens.spaceBetweenSlideAndPanelNavigation
+  }
+  const steps = Array.from(Array(totalItems)).map((_, index) => String(index))
+  return (
+    <StackView direction="row" tokens={stackViewTokens}>
+      <StepTracker
+        current={activeIndex}
+        steps={steps}
+        copy={{
+          // Give StepTracker copy from Carousel's language and dictionary
+          stepLabel: getCopyWithPlaceholders('stepLabel'),
+          stepTrackerLabel: getCopyWithPlaceholders('stepTrackerLabel')
+        }}
+        tokens={stepTrackerTokens}
+      />
+    </StackView>
+  )
+}
+
+export default CarouselStepTracker

package/src/Carousel/CarouselStepTracker/index.js

@@ -0,0 +1,3 @@
+import CarouselStepTracker from './CarouselStepTracker'
+
+export default CarouselStepTracker

package/src/Carousel/CarouselTabs/CarouselTabs.jsx

@@ -0,0 +1,37 @@
+import React, { forwardRef } from 'react'
+import PropTypes from 'prop-types'
+
+import { useResponsiveProp } from '../../utils'
+import Carousel from '../Carousel'
+import CarouselTabsPanel from './CarouselTabsPanel'
+
+const CarouselTabs = forwardRef(({ items, refocus = true, ...carouselProps }, ref) => {
+  const panelNavigation = useResponsiveProp({ md: <CarouselTabsPanel items={items} /> })
+
+  return (
+    <Carousel refocus={refocus} {...carouselProps} ref={ref} panelNavigation={panelNavigation}>
+      {items.map(({ title, content }) => (
+        <React.Fragment key={title}>{content}</React.Fragment>
+      ))}
+    </Carousel>
+  )
+})
+
+CarouselTabs.displayName = 'CarouselTabs'
+CarouselTabs.propTypes = {
+  /**
+   * An array of objects where title is the string shown in the slide's tab and content is the JSX for the slide itself
+   */
+  items: PropTypes.arrayOf(
+    PropTypes.shape({
+      title: PropTypes.string.isRequired,
+      content: PropTypes.node.isRequired
+    })
+  ),
+  ...Carousel.propTypes
+}
+// CarouselTabs doesn't require `children` prop, it uses `items` instead.
+// eslint-disable-next-line react/forbid-foreign-prop-types
+if (CarouselTabs.propTypes?.children) delete CarouselTabs.propTypes?.children
+
+export default CarouselTabs

package/src/Carousel/CarouselTabs/CarouselTabsPanel.jsx

@@ -0,0 +1,69 @@
+import React, { forwardRef, useRef } from 'react'
+import { View } from 'react-native'
+
+import PropTypes from 'prop-types'
+import StackView from '../../StackView'
+
+import { useCarousel } from '../CarouselContext'
+import CarouselTabsPanelItem from './CarouselTabsPanelItem'
+
+const CarouselTabsPanel = forwardRef(({ items }, ref) => {
+  const { activeIndex, goTo } = useCarousel()
+  const nextFocusRef = useRef()
+  const firstTabRef = useRef()
+
+  // TODO: figure out a better cross-brand way to specify subcomponent variants.
+  // For now, this picks an Allium variant, and does nothing in brands that lack it.
+  // See similar comment in Carousel and https://github.com/telus/universal-design-system/issues/1549
+  const dividerVariant = { decorative: true }
+
+  const lastTabSelected = activeIndex === items.length - 1
+
+  return (
+    <>
+      <View
+        focusable
+        accessible
+        onFocus={(event) => {
+          // When user forward-tabs into this section, focus the next tab; if they backwards-tab
+          // (shift-tab) back into the carousel content, don't interfere.
+          const previousWebFocus = event.relatedTarget
+          if (previousWebFocus !== firstTabRef.current) nextFocusRef.current.focus()
+        }}
+      />
+      <StackView direction="row" space={3} divider={{ variant: dividerVariant }} ref={ref}>
+        {items.map(({ title, onPress, ...panelItemProps }, index) => {
+          const selected = index === activeIndex
+          const isNext = index === activeIndex + 1
+
+          // Selected item should be always unfocusable and unpressable
+          const handlePress = selected
+            ? undefined
+            : (event) => {
+                if (typeof onPress === 'function') onPress(event, index)
+                goTo(index)
+              }
+
+          return (
+            <CarouselTabsPanelItem
+              ref={(isNext && nextFocusRef) || (index === 0 && firstTabRef) || null}
+              key={title}
+              title={title}
+              selected={selected}
+              onPress={handlePress}
+              {...panelItemProps}
+            />
+          )
+        })}
+      </StackView>
+      {/* TODO: integrate with skiplink, replace this with focusing skiplink target */}
+      <View focusable accessible ref={lastTabSelected ? nextFocusRef : null} />
+    </>
+  )
+})
+CarouselTabsPanel.displayName = 'CarouselTabsPanel'
+CarouselTabsPanel.propTypes = {
+  items: PropTypes.arrayOf(PropTypes.shape(CarouselTabsPanelItem.propTypes || {}))
+}
+
+export default CarouselTabsPanel

package/src/Carousel/CarouselTabs/CarouselTabsPanelItem.jsx

@@ -0,0 +1,119 @@
+import React, { forwardRef, useState } from 'react'
+import PropTypes from 'prop-types'
+import { Pressable, Text, Platform } from 'react-native'
+
+import { applyTextStyles, useThemeTokensCallback } from '../../ThemeProvider'
+import {
+  selectSystemProps,
+  a11yProps,
+  pressProps,
+  viewProps,
+  textProps,
+  getTokensPropType,
+  variantProp,
+  resolvePressableState
+} from '../../utils'
+
+const [selectPressProps, pressPropTypes] = selectSystemProps([a11yProps, pressProps, viewProps])
+const [selectTextProps, textPropTypes] = selectSystemProps([textProps])
+
+const selectContainerStyles = ({
+  paddingLeft,
+  paddingRight,
+  paddingTop,
+  paddingBottom = 0,
+  borderBottomColor,
+  borderBottomWidth = 0,
+  borderBottomStyle,
+  flex,
+  alignItems,
+  justifyContent
+}) => ({
+  paddingLeft,
+  paddingRight,
+  paddingTop,
+  paddingBottom: paddingBottom - borderBottomWidth,
+  borderBottomColor,
+  borderBottomWidth,
+  borderBottomStyle,
+  flex,
+  alignItems,
+  justifyContent,
+  ...Platform.select({
+    // Removes the default browser :focus outline
+    web: { outline: 'none' }
+  })
+})
+
+const selectTextStyles = ({
+  fontSize,
+  fontScaleCap,
+  lineHeight,
+  letterSpacing,
+  fontWeight,
+  fontName,
+  color
+}) =>
+  applyTextStyles({
+    fontSize,
+    fontScaleCap,
+    lineHeight,
+    letterSpacing,
+    fontWeight,
+    fontName,
+    color
+  })
+
+const CarouselTabsPanelItem = forwardRef(
+  ({ title, selected, inactive, variant, tokens, accessibilityRole = 'tab', ...rest }, ref) => {
+    // Workaround for React Native Web https://github.com/necolas/react-native-web/issues/2357
+    // Don't allow disabled to be set while focus is true else focus state gets locked `true`
+    // (must refocus _after_ calling `goTo`, else focus target content is not up to date)
+    const [isFocused, setIsFocused] = useState(false)
+    const disabled = (inactive || selected) && !isFocused
+
+    const getTokens = useThemeTokensCallback('CarouselTabsPanelItem', tokens, variant)
+    const resolveTokens = (pressState) => getTokens(resolvePressableState(pressState, { selected }))
+
+    const getContainerStyle = (pressState) => selectContainerStyles(resolveTokens(pressState))
+
+    const getTextStyle = (pressState) => selectTextStyles(resolveTokens(pressState))
+
+    const { onPress, ...selectedPressProps } = selectPressProps(rest)
+    const handleKeyDown = (event) => {
+      // Allow using the spacebar for navigation
+      if (event?.key === ' ') onPress(event)
+    }
+
+    return (
+      <Pressable
+        onPress={onPress}
+        style={getContainerStyle}
+        accessibilityRole={accessibilityRole}
+        ref={ref}
+        onKeyDown={handleKeyDown}
+        onFocus={() => setIsFocused(true)}
+        onBlur={() => setIsFocused(false)}
+        disabled={disabled}
+        {...selectedPressProps}
+      >
+        {(pressState) => (
+          <Text style={getTextStyle(pressState)} {...selectTextProps(rest)}>
+            {title}
+          </Text>
+        )}
+      </Pressable>
+    )
+  }
+)
+CarouselTabsPanelItem.displayName = 'CarouselTabsPanelItem'
+CarouselTabsPanelItem.propTypes = {
+  ...pressPropTypes,
+  ...textPropTypes,
+  title: PropTypes.string.isRequired,
+  selected: PropTypes.bool,
+  tokens: getTokensPropType('CarouselTabsPanelItem'),
+  variant: variantProp.propType
+}
+
+export default CarouselTabsPanelItem

package/src/Carousel/CarouselTabs/index.js

@@ -0,0 +1,3 @@
+import CarouselTabs from './CarouselTabs'
+
+export default CarouselTabs