@telus-uds/components-base 1.8.5 → 1.11.0

package/src/Carousel/Carousel.jsx

@@ -0,0 +1,649 @@
+import React from 'react'
+import { View, Animated, PanResponder, StyleSheet, Platform } from 'react-native'
+import PropTypes from 'prop-types'
+import { useThemeTokens } from '../ThemeProvider'
+import { useViewport } from '../ViewportProvider'
+import {
+  getTokensPropType,
+  getA11yPropsFromHtmlTag,
+  layoutTags,
+  variantProp,
+  selectSystemProps,
+  a11yProps,
+  viewProps,
+  useCopy
+} 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 dictionary from './dictionary'
+
+const staticStyles = StyleSheet.create({
+  root: {
+    backgroundColor: 'transparent',
+    justifyContent: 'center',
+    alignItems: 'center',
+    position: 'relative',
+    top: 0,
+    left: 0
+  }
+})
+
+const staticTokens = {
+  stackView: {
+    justifyContent: 'center'
+  },
+  stepTracker: {
+    showStepLabel: false,
+    showStepTrackerLabel: true,
+    knobCompletedBackgroundColor: 'none',
+    connectorCompletedColor: 'none',
+    connectorColor: 'none'
+  }
+}
+
+const selectContainerStyles = (width) => ({
+  backgroundColor: 'transparent',
+  overflow: 'hidden',
+  width
+})
+
+const selectSwipeAreaStyles = (count, width) => ({
+  width: width * count,
+  justifyContent: 'space-between',
+  flexDirection: 'row'
+})
+
+const selectPreviousNextNavigationButtonStyles = (
+  previousNextNavigationButtonWidth,
+  previousNextNavigationPosition,
+  spaceBetweenSlideAndPreviousNextNavigation,
+  isFirstSlide,
+  isLastSlide,
+  areStylesAppliedOnPreviousButton
+) => {
+  const styles = {
+    zIndex: 1,
+    position: 'absolute'
+  }
+  const dynamicPositionProperty = areStylesAppliedOnPreviousButton ? 'left' : 'right'
+  if (isFirstSlide) {
+    styles.visibility = areStylesAppliedOnPreviousButton ? 'hidden' : 'visible'
+  } else if (isLastSlide) {
+    styles.visibility = areStylesAppliedOnPreviousButton ? 'visible' : 'hidden'
+  } else {
+    styles.visibility = 'visible'
+  }
+
+  if (previousNextNavigationPosition === 'edge') {
+    styles[dynamicPositionProperty] = -1 * (previousNextNavigationButtonWidth / 2)
+  } else if (previousNextNavigationPosition === 'inside') {
+    styles[dynamicPositionProperty] = 0
+  } else if (previousNextNavigationPosition === 'outside') {
+    styles[dynamicPositionProperty] =
+      -1 * (spaceBetweenSlideAndPreviousNextNavigation + previousNextNavigationButtonWidth)
+  }
+  return styles
+}
+
+const [selectProps, selectedSystemPropTypes] = selectSystemProps([a11yProps, viewProps])
+
+/**
+ * Carousel is a general-purpose content slider that can be used to render content in terms of slides.
+
+  ## Usage
+  - `Carousel` is a top-level export from `@telus-uds/components-base` which is used to render a Carousel
+  - Immediately within `Carousel`, individual slides are wrapped in `Carousel.Item` for the top-level `Carousel` to know how to identify an individual slide
+  - You can use any UDS component or other platform-specific component, (based on the platform you're rendering) to achieve any desired layout
+  - By default, Carousel takea all the `width` available to it and the `height` is determined based on the content in the slide with more content
+  - You may want to wrap Carousel in other layout components like `Box`, `FlexGrid` etc, to achieve a responsive layout of your need
+
+  ## `useCarousel` custom hook
+
+  ```jsx
+  import { useCarousel } from '@telus-uds/components-base'
+
+  const SomeComponentWithinCarouselItem = () => {
+    const {
+      activeIndex,
+      totalItems,
+      width,
+      goTo
+    } = useCarousel()
+    return <Text>Hi!</Text>
+  }
+  ```
+
+  You can use `useCarousel` to hook into internal state of the Carousel component like:
+  - `activeIndex`: Index of the current slide
+  - `totalItems`: Total number of items/slides passed to the Carousel
+  - `width`: Width of the individual carousel slide
+  - `goTo`: A function to go to a particular slide by passing the index of that slide, e.g: goTo(0) where `0` is the index of the first slide
+
+  ## Accessibility
+
+  - Top-level `Carousel` and `Carousel.Item` can take all possible React Native's `View` and `a11y` props
+  - If your slide contains input elements like buttons, you may want to configure them to be only focusable when `activeIndex` is equal to the current slide index in order to avoid tabbing going between slides
+
+  ## Platform considerations
+  The component is available on both native platforms and web.
+
+  ## Other considerations
+  - You may want to use the same kind of layout in all your slides to avoid visual and height differences
+  - `previous` and `next` navigation buttons are automatically removed in `sm` and `xs` viewports, as these smaller viewports offers swipe functionality
+
+  ## Tokens
+
+  You can override the following tokens in exceptional circumstances:
+  - `previousIcon` - Icon of the previous button
+  - `nextIcon` - Icon of the next button
+  - `showPreviousNextNavigation` - If you want to show/hide the previous/next navigation
+  - `showPanelNavigation` - If you want to show/hide the panel navigation
+  - `spaceBetweenSlideAndPreviousNextNavigation` - Horizontal space between slide and previous/next navigational buttons
+  - `spaceBetweenSlideAndPanelNavigation` - Vertical space between slide area and panel navigation area
+ */
+const Carousel = React.forwardRef(
+  (
+    {
+      tokens,
+      variant,
+      children,
+      itemLabel = 'item',
+      previousNextNavigationPosition = 'inside',
+      previousNextIconSize = 'default',
+      minDistanceToCapture = 5,
+      minDistanceForAction = 0.2,
+      onAnimationStart,
+      onAnimationEnd,
+      onIndexChanged,
+      springConfig = undefined,
+      onRenderPanelNavigation,
+      tag = 'ul',
+      accessibilityRole = 'adjustable',
+      accessibilityLabel = 'carousel',
+      copy,
+      ...rest
+    },
+    ref
+  ) => {
+    const viewport = useViewport()
+    const {
+      previousIcon,
+      nextIcon,
+      showPreviousNextNavigation,
+      showPanelNavigation,
+      spaceBetweenSlideAndPreviousNextNavigation,
+      spaceBetweenSlideAndPanelNavigation
+    } = useThemeTokens('Carousel', tokens, variant, {
+      viewport
+    })
+    const [activeIndex, setActiveIndex] = React.useState(0)
+
+    const [isAnimating, setIsAnimating] = React.useState(false)
+    const handleAnimationStart = React.useCallback(
+      (...args) => {
+        if (typeof onAnimationStart === 'function') onAnimationStart(...args)
+        setIsAnimating(true)
+      },
+      [onAnimationStart]
+    )
+    const handleAnimationEnd = React.useCallback(
+      (...args) => {
+        if (typeof onAnimationEnd === 'function') onAnimationEnd(...args)
+        setIsAnimating(false)
+      },
+      [onAnimationEnd]
+    )
+
+    const getCopy = useCopy({ dictionary, copy })
+
+    const childrenArray = React.Children.toArray(children)
+    const systemProps = selectProps({
+      ...rest,
+      accessibilityRole,
+      accessibilityLabel,
+      accessibilityValue: {
+        min: 1,
+        max: childrenArray.length,
+        now: activeIndex + 1
+      }
+    })
+    const { reduceMotionEnabled } = useA11yInfo()
+    const [containerLayout, setContainerLayout] = React.useState({
+      x: 0,
+      y: 0,
+      width: 0
+    })
+    const [previousNextNavigationButtonWidth, setPreviousNextNavigationButtonWidth] =
+      React.useState(0)
+    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: {
+        layout: { x, y, width }
+      }
+    }) => setContainerLayout((prevState) => ({ ...prevState, x, y, width }))
+
+    const onPreviousNextNavigationButtonLayout = ({
+      nativeEvent: {
+        layout: { width }
+      }
+    }) => setPreviousNextNavigationButtonWidth(width)
+
+    const updateOffset = React.useCallback(() => {
+      animatedX.current = containerLayout.width * activeIndex * -1
+      animatedY.current = 0
+      pan.setOffset({
+        x: animatedX.current,
+        y: animatedY.current
+      })
+      pan.setValue({ x: 0, y: 0 })
+    }, [activeIndex, containerLayout.width, pan, animatedX])
+
+    const animate = React.useCallback(
+      (toValue, toIndex) => {
+        const handleAnimationEndToIndex = (...args) => handleAnimationEnd(toIndex, ...args)
+        if (reduceMotionEnabled) {
+          Animated.timing(pan, { toValue, duration: 1, useNativeDriver: false }).start(
+            handleAnimationEndToIndex
+          )
+        } else {
+          Animated.spring(pan, {
+            ...springConfig,
+            toValue,
+            useNativeDriver: false
+          }).start(handleAnimationEndToIndex)
+        }
+      },
+      [pan, springConfig, reduceMotionEnabled, handleAnimationEnd]
+    )
+
+    const updateIndex = React.useCallback(
+      (delta = 1) => {
+        const toValue = { x: 0, y: 0 }
+        let skipChanges = !delta
+        let calcDelta = delta
+
+        if (activeIndex <= 0 && delta < 0) {
+          skipChanges = true
+          calcDelta = children.length + delta
+        } else if (activeIndex + 1 >= children.length && delta > 0) {
+          skipChanges = true
+          calcDelta = -1 * activeIndex + delta - 1
+        }
+
+        const index = activeIndex + calcDelta
+
+        if (skipChanges) {
+          animate(toValue, index)
+          return calcDelta
+        }
+
+        setActiveIndex(index)
+
+        toValue.x = containerLayout.width * -1 * calcDelta
+
+        animate(toValue, index)
+
+        if (onIndexChanged) onIndexChanged(calcDelta)
+        return calcDelta
+      },
+      [containerLayout.width, activeIndex, animate, children.length, onIndexChanged]
+    )
+
+    const fixOffsetAndGo = React.useCallback(
+      (delta) => {
+        updateOffset()
+        handleAnimationStart(activeIndex)
+        updateIndex(delta)
+      },
+      [updateIndex, updateOffset, activeIndex, handleAnimationStart]
+    )
+
+    const goToNeighboring = React.useCallback(
+      (toPrev = false) => {
+        fixOffsetAndGo(toPrev ? -1 : 1)
+      },
+      [fixOffsetAndGo]
+    )
+
+    const isSwipeAllowed = React.useCallback(() => {
+      if (Platform.OS === 'web') {
+        return !!(viewport === 'xs' || viewport === 'sm')
+      }
+      return true
+    }, [viewport])
+
+    const panResponder = React.useMemo(
+      () =>
+        PanResponder.create({
+          onPanResponderTerminationRequest: () => false,
+          onMoveShouldSetResponderCapture: () => true,
+          onMoveShouldSetPanResponderCapture: (_, gestureState) => {
+            if (!isSwipeAllowed()) {
+              return false
+            }
+
+            handleAnimationStart(activeIndex)
+
+            return Math.abs(gestureState.dx) > minDistanceToCapture
+          },
+          onPanResponderGrant: () => updateOffset(),
+          onPanResponderMove: Animated.event([null, { dx: pan.x }], {
+            useNativeDriver: false
+          }),
+          onPanResponderRelease: (_, gesture) => {
+            const correction = gesture.moveX - gesture.x0
+
+            if (Math.abs(correction) < containerLayout.width * minDistanceForAction) {
+              animate({ x: 0, y: 0 }, 0)
+            } else {
+              const delta = correction > 0 ? -1 : 1
+              updateIndex(delta)
+            }
+          }
+        }),
+      [
+        containerLayout.width,
+        updateIndex,
+        updateOffset,
+        animate,
+        isSwipeAllowed,
+        activeIndex,
+        minDistanceForAction,
+        handleAnimationStart,
+        minDistanceToCapture,
+        pan.x
+      ]
+    )
+
+    React.useEffect(() => {
+      pan.x.addListener(({ value }) => {
+        animatedX.current = value
+      })
+      pan.y.addListener(({ value }) => {
+        animatedY.current = value
+      })
+      return () => {
+        pan.x.removeAllListeners()
+        pan.y.removeAllListeners()
+      }
+    }, [pan.x, pan.y])
+
+    const goToNext = React.useCallback(() => {
+      goToNeighboring()
+    }, [goToNeighboring])
+
+    const goToPrev = React.useCallback(() => {
+      goToNeighboring(true)
+    }, [goToNeighboring])
+
+    const goTo = React.useCallback(
+      (index = 0) => {
+        const delta = index - activeIndex
+        if (delta) {
+          fixOffsetAndGo(delta)
+        }
+      },
+      [fixOffsetAndGo, activeIndex]
+    )
+
+    // @TODO: - these are Allium-theme variants and won't have any effect in themes that don't implement them.
+    // Normally we avoid setting variants of subcomponents, however this could be re-considered.
+    // 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)
+
+      // First word might be a lowercase placeholder: capitalize the first letter
+      return `${copyText[0].toUpperCase()}${copyText.slice(1)}`
+    }
+
+    return (
+      <CarouselProvider
+        activeIndex={activeIndex}
+        totalItems={childrenArray.length}
+        width={containerLayout.width}
+        goTo={goTo}
+      >
+        <View style={staticStyles.root} onLayout={onContainerLayout} ref={ref} {...systemProps}>
+          {showPreviousNextNavigation && (
+            <View
+              style={selectPreviousNextNavigationButtonStyles(
+                previousNextNavigationButtonWidth,
+                previousNextNavigationPosition,
+                spaceBetweenSlideAndPreviousNextNavigation,
+                isFirstSlide,
+                isLastSlide,
+                true
+              )}
+              testID="previous-button-container"
+            >
+              <IconButton
+                onLayout={onPreviousNextNavigationButtonLayout}
+                icon={previousIcon}
+                onPress={goToPrev}
+                variant={previousNextIconButtonVariants}
+                accessibilityLabel={getCopyWithPlaceholders('iconButtonLabel').replace(
+                  '%{targetStep}',
+                  activeIndex
+                )}
+              />
+            </View>
+          )}
+          <View style={selectContainerStyles(containerLayout.width)}>
+            <Animated.View
+              style={StyleSheet.flatten([
+                selectSwipeAreaStyles(children.length, containerLayout.width),
+                {
+                  transform: [{ translateX: pan.x }, { translateY: pan.y }]
+                }
+              ])}
+              {...panResponder.panHandlers}
+              {...getA11yPropsFromHtmlTag(tag)}
+            >
+              {childrenArray.map((element, index) => {
+                const hidden = !isAnimating && index !== activeIndex
+                const clonedElement = React.cloneElement(element, { elementIndex: index, hidden })
+                return <React.Fragment key={index.toFixed(2)}>{clonedElement}</React.Fragment>
+              })}
+            </Animated.View>
+          </View>
+          {showPreviousNextNavigation && (
+            <View
+              style={selectPreviousNextNavigationButtonStyles(
+                previousNextNavigationButtonWidth,
+                previousNextNavigationPosition,
+                spaceBetweenSlideAndPreviousNextNavigation,
+                isFirstSlide,
+                isLastSlide,
+                false
+              )}
+              testID="next-button-container"
+            >
+              <IconButton
+                onLayout={onPreviousNextNavigationButtonLayout}
+                icon={nextIcon}
+                onPress={goToNext}
+                variant={previousNextIconButtonVariants}
+                accessibilityLabel={getCopyWithPlaceholders('iconButtonLabel').replace(
+                  '%{targetStep}',
+                  activeIndex + 2
+                )}
+              />
+            </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}
+      </CarouselProvider>
+    )
+  }
+)
+
+Carousel.propTypes = {
+  ...selectedSystemPropTypes,
+  tokens: getTokensPropType('Carousel'),
+  variant: variantProp.propType,
+  /**
+   * Slides to render in Carousel. Wrap individual slides in `Carousel.Item`
+   */
+  children: PropTypes.oneOfType([PropTypes.arrayOf(PropTypes.node), PropTypes.node]).isRequired,
+  /**
+   * Lowercase language-appropriate user-facing description of what each Carousel slide represents.
+   * This is used when generating item labels. For example, if a carousel contains offers,
+   * pass itemLabel="summer offer" (or copy="fr" and an appropriate French translation) to genereate
+   * accessible labels such as "Summer offer 1 of 3" and "Show summer offer 2 of 3".
+   */
+  itemLabel: PropTypes.string,
+  /**
+   * `inside` renders the previous and next buttons inside the slide
+   * `outside` renders the previous and next buttons outside the slide
+   * `edge` renders the previous and next buttons at the edge of the slide
+   */
+  previousNextNavigationPosition: PropTypes.oneOf(['inside', 'outside', 'edge']),
+  /**
+   * Defines the size of the `IconButton` which is being used to render next and previous buttons
+   */
+  previousNextIconSize: PropTypes.oneOf(['default', 'small', 'large']),
+  /**
+   * Carousel uses `Animated.spring` to animate slide changes, use this option to pass custom animation configuration
+   */
+  springConfig: PropTypes.object,
+  /**
+   * 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
+   */
+  minDistanceForAction: PropTypes.number,
+  /**
+   * Initiate animation after swipe this distance.
+   */
+  minDistanceToCapture: PropTypes.number,
+  /**
+   * Called when active index changed
+   * This function is also provided with a parameter indicating changed index (either 1, or -1)
+   * Use it as follows:
+   * ```js
+   *    const onIndexChangedCallback = React.useCallback((changedIndex) => {
+   *      console.log(changedIndex)
+   *    }, [])  // pass local dependencies as per your component
+   *    <Carousel
+   *      onIndexChanged={onIndexChangedCallback}
+   *    >
+   *      <Carousel.Item>First Slide</Carousel.Item>
+   *    </Carousel>
+   * ```
+   * Caution: Always consider wrapping your callback for `onIndexChanged` in `useCallback` in order to avoid bugs and performance issues
+   */
+  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
+   * Use it as follows:
+   * ```js
+   *    <Carousel
+   *      onRenderPanelNavigation={({ totalItems, activeIndex }) => <Text>Showing {activeIndex + 1}</Text>}
+   *    >
+   *      <Carousel.Item>First Slide</Carousel.Item>
+   *    </Carousel>
+   * ```
+   */
+  onRenderPanelNavigation: PropTypes.func,
+  /**
+   * When slide animation start
+   * This function is also provided with a parameter indicating the current slide index before animation starts
+   * Use it as follows:
+   * ```js
+   *    const onAnimationStartCallback = React.useCallback((currentIndex) => {
+   *      console.log(currentIndex)
+   *    }, [])  // pass local dependencies as per your component
+   *    <Carousel
+   *      onAnimationStart={onAnimationStartCallback}
+   *    >
+   *      <Carousel.Item>First Slide</Carousel.Item>
+   *    </Carousel>
+   * ```
+   * Caution: Always consider wrapping your callback for `onAnimationStart` in `useCallback` in order to avoid bugs and performance issues
+   */
+  onAnimationStart: PropTypes.func,
+  /**
+   * When slide animation end with parameter of current index (after animation ends)
+   * This function is also provided with a parameter indicating the updated slide index after animation ends
+   * Use it as follows:
+   * ```js
+   *    const onAnimationEndCallback = React.useCallback((changedIndex) => {
+   *      console.log(changedIndex)
+   *    }, [])  // pass local dependencies as per your component
+   *    <Carousel
+   *      onAnimationEnd={onAnimationEndCallback}
+   *    >
+   *      <Carousel.Item>First Slide</Carousel.Item>
+   *    </Carousel>
+   * ```
+   * Caution: Always consider wrapping your callback for `onAnimationEnd` in `useCallback` in order to avoid bugs and performance issues
+   */
+  onAnimationEnd: PropTypes.func,
+  /**
+   * Use this to override the default text for panel navigation
+   */
+  panelNavigationTextDictionary: PropTypes.shape({
+    en: PropTypes.shape({ stepTrackerLabel: PropTypes.string.isRequired }),
+    fr: PropTypes.shape({ stepTrackerLabel: PropTypes.string.isRequired })
+  }),
+  /**
+   * Provide custom accessibilityRole for Carousel container
+   */
+  accessibilityRole: PropTypes.string,
+  /**
+   * Provide custom accessibilityLabel for Carousel container
+   */
+  accessibilityLabel: PropTypes.string,
+  /**
+   * HTML tag to use for the Carousel item's immediate parent. Defaults to `'ul'` so that
+   * assistive technology tools know to intepret the carousel as a list.
+   *
+   * Note that if the immediate Carousel children do not all render as `'li'` elements,
+   * this should be changed (e.g. pass tag="div") because only 'li' is a valid child of 'ul'.
+   */
+  tag: PropTypes.oneOf(layoutTags)
+}
+
+Carousel.Item = CarouselItem
+
+Carousel.displayName = 'Carousel'
+
+export default Carousel

package/src/Carousel/CarouselContext.jsx

@@ -0,0 +1,30 @@
+import React from 'react'
+import PropTypes from 'prop-types'
+
+const CarouselContext = React.createContext()
+
+const CarouselProvider = ({ children, activeIndex, totalItems, width, goTo }) => {
+  const value = React.useMemo(
+    () => ({ activeIndex, totalItems, width, goTo }),
+    [activeIndex, totalItems, width, goTo]
+  )
+  return <CarouselContext.Provider value={value}>{children}</CarouselContext.Provider>
+}
+
+function useCarousel() {
+  const context = React.useContext(CarouselContext)
+  if (context === undefined) {
+    throw new Error(`'useCarousel' must be used within a 'CarouselProvider'`)
+  }
+  return context
+}
+
+CarouselProvider.propTypes = {
+  children: PropTypes.arrayOf(PropTypes.element).isRequired,
+  activeIndex: PropTypes.number.isRequired,
+  totalItems: PropTypes.number.isRequired,
+  width: PropTypes.number.isRequired,
+  goTo: PropTypes.func.isRequired
+}
+
+export { CarouselProvider, useCarousel }