@telus-uds/components-base 0.0.2-prerelease.6 → 1.0.0

package/src/SideNav/ItemsGroup.jsx

@@ -1,4 +1,4 @@
-import React from 'react'
+import React, { forwardRef } from 'react'
 import PropTypes from 'prop-types'
 
 import ItemContent from './ItemContent'
@@ -16,52 +16,59 @@ import { useThemeTokensCallback } from '../ThemeProvider'
  ## Usage Criteria
  - Use `SideNav.ItemsGroup` with large pages that have multiple sections
  */
-const ItemsGroup = ({
-  children,
-  label,
-  openGroups,
-  groupId,
-  isActive = false,
-  variant,
-  tokens,
-  itemTokens,
-  onToggle
-}) => {
-  // A SideNav control uses the same style and theme as SideNavItem, with a 'parent' variant,
-  // plus control-specific tokens from the SideNavItemsGroup theme (e.g. open/close icon, etc).
-  const getAppearance = (appearance) => ({ ...variant, ...appearance, active: isActive })
-  const getItemAppearance = (appearance) => ({ ...getAppearance(appearance), type: 'parent' })
+const ItemsGroup = forwardRef(
+  (
+    {
+      children,
+      label,
+      openGroups,
+      groupId,
+      isActive = false,
+      variant,
+      tokens,
+      itemTokens,
+      onToggle
+    },
+    ref
+  ) => {
+    // A SideNav control uses the same style and theme as SideNavItem, with a 'parent' variant,
+    // plus control-specific tokens from the SideNavItemsGroup theme (e.g. open/close icon, etc).
+    const getAppearance = (appearance) => ({ ...variant, ...appearance, active: isActive })
+    const getItemAppearance = (appearance) => ({ ...getAppearance(appearance), type: 'parent' })
 
-  const getGroupTokens = useThemeTokensCallback('SideNavItemsGroup', tokens, variant)
-  const getPanelTokens = (appearance) =>
-    selectTokens('ExpandCollapsePanel', getGroupTokens(getAppearance(appearance)))
+    const getGroupTokens = useThemeTokensCallback('SideNavItemsGroup', tokens, variant)
+    const getPanelTokens = (appearance) =>
+      selectTokens('ExpandCollapsePanel', getGroupTokens(getAppearance(appearance)))
 
-  const getItemTokens = useThemeTokensCallback('SideNavItem', itemTokens, variant)
-  const getControlTokens = (appearance) =>
-    selectTokens('ExpandCollapseControl', {
-      ...getItemTokens(getItemAppearance(appearance)), // main style from SideNavItem
-      ...getGroupTokens(getAppearance(appearance)) // control-specific tokens like icon etc
-    })
+    const getItemTokens = useThemeTokensCallback('SideNavItem', itemTokens, variant)
+    const getControlTokens = (appearance) =>
+      selectTokens('ExpandCollapseControl', {
+        ...getItemTokens(getItemAppearance(appearance)), // main style from SideNavItem
+        ...getGroupTokens(getAppearance(appearance)) // control-specific tokens like icon etc
+      })
 
-  const controlContent = (controlState) => {
-    const currentItemTokens = getItemTokens(getItemAppearance(controlState))
-    return <ItemContent tokens={currentItemTokens}>{label}</ItemContent>
-  }
+    const controlContent = (controlState) => {
+      const currentItemTokens = getItemTokens(getItemAppearance(controlState))
+      return <ItemContent tokens={currentItemTokens}>{label}</ItemContent>
+    }
 
-  return (
-    <ExpandCollapse.Panel
-      openIds={openGroups}
-      panelId={groupId}
-      onToggle={onToggle}
-      tokens={getPanelTokens}
-      controlTokens={getControlTokens}
-      control={controlContent}
-      accessibilityState={{ active: isActive }} // ExpandCollapse.Panel handles expanded state
-    >
-      {children}
-    </ExpandCollapse.Panel>
-  )
-}
+    return (
+      <ExpandCollapse.Panel
+        ref={ref}
+        openIds={openGroups}
+        panelId={groupId}
+        onToggle={onToggle}
+        tokens={getPanelTokens}
+        controlTokens={getControlTokens}
+        control={controlContent}
+        accessibilityState={{ active: isActive }} // ExpandCollapse.Panel handles expanded state
+      >
+        {children}
+      </ExpandCollapse.Panel>
+    )
+  }
+)
+ItemsGroup.displayName = 'ItemsGroup'
 
 ItemsGroup.propTypes = {
   /**

package/src/SideNav/SideNav.jsx

@@ -1,4 +1,4 @@
-import React, { useState } from 'react'
+import React, { forwardRef, useState } from 'react'
 import PropTypes from 'prop-types'
 
 import ExpandCollapse from '../ExpandCollapse'
@@ -20,73 +20,81 @@ function selectBorderStyles(tokens) {
  - Use in conjunction with a large amount of educational / informational content
  - Allow the user to navigate between options frequently and efficiently
  */
-const SideNav = ({ children, variant = {}, tokens, accordion = true, itemTokens, groupTokens }) => {
-  const themeTokens = useThemeTokens('SideNav', tokens, variant)
-  const [active, setActive] = useState({ groupId: undefined, itemId: undefined })
+const SideNav = forwardRef(
+  ({ children, variant = {}, tokens, accordion = true, itemTokens, groupTokens }, ref) => {
+    const themeTokens = useThemeTokens('SideNav', tokens, variant)
+    const [active, setActive] = useState({ groupId: undefined, itemId: undefined })
 
-  const onItemPress = (itemId, groupId) => {
-    setActive({ itemId, groupId })
-  }
-
-  const isItemActive = (itemId, groupId) => {
-    return active.groupId === groupId && active.itemId === itemId
-  }
-
-  return (
-    <ExpandCollapse maxOpen={accordion ? 1 : null} style={selectBorderStyles(themeTokens)}>
-      {({ openIds, onToggle }) => {
-        const renderItem = (item, index, groupId) => {
-          const { itemId = `item-${index}`, onPress } = item.props
-          const handlePress = (...args) => {
-            onItemPress(...args)
-            if (onPress) onPress(...args)
-          }
-          return (
-            <Item
-              {...item.props}
-              key={itemId}
-              itemId={itemId}
-              groupId={groupId}
-              variant={groupId ? { ...variant, type: 'child' } : variant}
-              tokens={itemTokens}
-              isActive={isItemActive(itemId, groupId)}
-              onPress={handlePress}
-            />
-          )
-        }
+    const onItemPress = (itemId, groupId) => {
+      setActive({ itemId, groupId })
+    }
 
-        return React.Children.map(children, (child, index) => {
-          // iterate over children and identify them internally to later reference expanded groups and active items
-          if (child.type === Item) return renderItem(child, index)
+    const isItemActive = (itemId, groupId) => {
+      return active.groupId === groupId && active.itemId === itemId
+    }
 
-          if (child.type === ItemsGroup) {
-            const { groupId = `group-${index}` } = child.props
-            const isGroupActive = active.itemId !== undefined && active.groupId === groupId
+    return (
+      <ExpandCollapse
+        ref={ref}
+        maxOpen={accordion ? 1 : null}
+        style={selectBorderStyles(themeTokens)}
+      >
+        {({ openIds, onToggle }) => {
+          const renderItem = (item, index, groupId) => {
+            const { itemId = `item-${index}`, onPress } = item.props
+            const handlePress = (...args) => {
+              onItemPress(...args)
+              if (onPress) onPress(...args)
+            }
             return (
-              <ItemsGroup
-                {...child.props}
-                key={groupId}
+              <Item
+                {...item.props}
+                key={itemId}
+                itemId={itemId}
                 groupId={groupId}
-                variant={variant}
-                tokens={groupTokens}
-                itemTokens={itemTokens}
-                openGroups={openIds}
-                isActive={isGroupActive}
-                onToggle={() => onToggle(groupId)}
-              >
-                {React.Children.map(child.props.children, (item, itemIndex) =>
-                  renderItem(item, itemIndex, groupId)
-                )}
-              </ItemsGroup>
+                variant={groupId ? { ...variant, type: 'child' } : variant}
+                tokens={itemTokens}
+                isActive={isItemActive(itemId, groupId)}
+                onPress={handlePress}
+              />
             )
           }
 
-          return null
-        })
-      }}
-    </ExpandCollapse>
-  )
-}
+          return React.Children.map(children, (child, index) => {
+            // iterate over children and identify them internally to later reference expanded groups and active items
+            if (child.type === Item) return renderItem(child, index)
+
+            if (child.type === ItemsGroup) {
+              const { groupId = `group-${index}` } = child.props
+              const isGroupActive = active.itemId !== undefined && active.groupId === groupId
+              const handleToggle = (event) => onToggle(groupId, event)
+              return (
+                <ItemsGroup
+                  {...child.props}
+                  key={groupId}
+                  groupId={groupId}
+                  variant={variant}
+                  tokens={groupTokens}
+                  itemTokens={itemTokens}
+                  openGroups={openIds}
+                  isActive={isGroupActive}
+                  onToggle={handleToggle}
+                >
+                  {React.Children.map(child.props.children, (item, itemIndex) =>
+                    renderItem(item, itemIndex, groupId)
+                  )}
+                </ItemsGroup>
+              )
+            }
+
+            return null
+          })
+        }}
+      </ExpandCollapse>
+    )
+  }
+)
+SideNav.displayName = 'SideNav'
 
 SideNav.propTypes = {
   /**

package/src/Skeleton/Skeleton.jsx

@@ -0,0 +1,94 @@
+import React, { forwardRef } from 'react'
+import { Animated, Platform } from 'react-native'
+import propTypes from 'prop-types'
+import StackView from '../StackView'
+import { useThemeTokens } from '../ThemeProvider'
+import { getTokensPropType, useSpacingScale, variantProp } from '../utils'
+import useSkeletonNativeAnimation from './useSkeletonNativeAnimation'
+import skeletonWebAnimation from './skeletonWebAnimation'
+
+const selectSkeletonStyles = ({ color, radius, fadeAnimation }) => ({
+  backgroundColor: color,
+  borderRadius: radius,
+  ...fadeAnimation
+})
+
+const selectLineStyles = ({ skeletonHeight, lineWidth }) => ({
+  width: lineWidth,
+  height: skeletonHeight
+})
+
+const selectShapeStyles = ({ skeletonHeight }) => ({
+  height: skeletonHeight,
+  width: skeletonHeight
+})
+
+const selectSquareStyles = ({ radius }) => ({
+  borderRadius: radius
+})
+
+const Skeleton = forwardRef(({ tokens, variant, size, characters, lines, shape = 'line' }, ref) => {
+  const themeTokens = useThemeTokens('Skeleton', tokens, variant)
+  const skeletonHeight = useSpacingScale(size || themeTokens.size)
+  const nativeAnimation = useSkeletonNativeAnimation()
+
+  const getAnimationBaseOnPlatform = () => {
+    if (Platform.OS !== 'web') {
+      return nativeAnimation
+    }
+
+    return skeletonWebAnimation
+  }
+
+  const getLineWidth = () => {
+    if (characters) {
+      return characters * themeTokens.baseWidth
+    }
+
+    return themeTokens.characters * themeTokens.baseWidth
+  }
+
+  const getStyledBasedOnShape = () => {
+    if (shape === 'circle') {
+      return selectShapeStyles({ skeletonHeight })
+    }
+
+    if (shape === 'box') {
+      return [
+        selectShapeStyles({ skeletonHeight }),
+        selectSquareStyles({ radius: themeTokens.squareRadius })
+      ]
+    }
+
+    return selectLineStyles({ skeletonHeight, lineWidth: getLineWidth() })
+  }
+
+  const renderSkeleton = (index = 0) => (
+    <Animated.View
+      testID="skeleton"
+      key={`skeleton-${index + 1}`}
+      style={[
+        selectSkeletonStyles({ ...themeTokens, fadeAnimation: getAnimationBaseOnPlatform() }),
+        getStyledBasedOnShape()
+      ]}
+    />
+  )
+
+  return (
+    <StackView space={themeTokens.spaceBetweenLines} ref={ref}>
+      {lines > 1 ? [...Array(lines)].map((_, index) => renderSkeleton(index)) : renderSkeleton()}
+    </StackView>
+  )
+})
+Skeleton.displayName = 'Skeleton'
+
+Skeleton.propTypes = {
+  tokens: getTokensPropType('Skeleton'),
+  variant: variantProp.propType,
+  size: propTypes.number,
+  characters: propTypes.number,
+  lines: propTypes.number,
+  shape: propTypes.oneOf(['line', 'circle', 'box'])
+}
+
+export default Skeleton

package/src/Skeleton/index.js

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

package/src/Skeleton/skeleton.constant.js

@@ -0,0 +1,3 @@
+export const DEFAULT_OPACITY = 1
+export const OPACITY_STOP = 0.4
+export const ANIMATION_DURATION = 1500

package/src/Skeleton/skeletonWebAnimation.js

@@ -0,0 +1,13 @@
+import { ANIMATION_DURATION, DEFAULT_OPACITY, OPACITY_STOP } from './skeleton.constant'
+
+export default {
+  animationDuration: `${ANIMATION_DURATION}ms`,
+  animationTimingFunction: 'ease-in-out',
+  animationDelay: '0.5s',
+  animationIterationCount: 'infinite',
+  animationKeyframes: {
+    '0%': { opacity: DEFAULT_OPACITY },
+    '50%': { opacity: OPACITY_STOP },
+    '100%': { opacity: DEFAULT_OPACITY }
+  }
+}

package/src/Skeleton/useSkeletonNativeAnimation.js

@@ -0,0 +1,27 @@
+import { useEffect, useRef } from 'react'
+import { Animated } from 'react-native'
+import { ANIMATION_DURATION, DEFAULT_OPACITY, OPACITY_STOP } from './skeleton.constant'
+
+const useSkeletonNativeAnimation = () => {
+  const fadeAnimation = useRef(new Animated.Value(DEFAULT_OPACITY)).current
+
+  useEffect(() => {
+    const fade = Animated.sequence([
+      Animated.timing(fadeAnimation, {
+        toValue: OPACITY_STOP,
+        duration: ANIMATION_DURATION,
+        useNativeDriver: true
+      }),
+      Animated.timing(fadeAnimation, {
+        toValue: DEFAULT_OPACITY,
+        duration: ANIMATION_DURATION,
+        useNativeDriver: true
+      })
+    ])
+    Animated.loop(fade).start()
+  }, [fadeAnimation])
+
+  return { opacity: fadeAnimation }
+}
+
+export default useSkeletonNativeAnimation

package/src/Spacer/Spacer.jsx

@@ -1,4 +1,4 @@
-import React from 'react'
+import React, { forwardRef } from 'react'
 import PropTypes from 'prop-types'
 import { StyleSheet, View } from 'react-native'
 
@@ -54,11 +54,14 @@ const selectSizeStyle = (size, direction) => ({
  * Spacer has no content and is ignored by tools such as screen readers. Use `Divider` for
  * separations between elements that may be treated as semantically meaningful on web.
  */
-const Spacer = ({ space = 1, direction = 'column', testID }) => {
+const Spacer = forwardRef(({ space = 1, direction = 'column', testID, dataSet }, ref) => {
   const size = useSpacingScale(space)
   const sizeStyle = selectSizeStyle(size, direction)
-  return <View testID={testID} style={[staticStyles.stretch, sizeStyle]} />
-}
+  return (
+    <View ref={ref} testID={testID} style={[staticStyles.stretch, sizeStyle]} dataSet={dataSet} />
+  )
+})
+Spacer.displayName = 'Spacer'
 
 Spacer.propTypes = {
   /**
@@ -74,6 +77,10 @@ Spacer.propTypes = {
    * - `'row'` applies space horizontally; has a fixed width and not height.
    */
   direction: PropTypes.oneOf(['column', 'row']),
+  /**
+   * @ignore
+   */
+  dataSet: PropTypes.object,
   /**
    * @ignore
    * In tests, the only way to select Spacers is with testID prop and getByTestId, since they have no content,

package/src/StackView/StackView.jsx

@@ -1,9 +1,19 @@
-import React from 'react'
+import React, { forwardRef } from 'react'
 import PropTypes from 'prop-types'
 import { View } from 'react-native'
 
 import Divider from '../Divider'
-import { spacingProps, a11yProps, responsiveProps, variantProp, useResponsiveProp } from '../utils'
+import {
+  spacingProps,
+  a11yProps,
+  getTokensPropType,
+  responsiveProps,
+  variantProp,
+  viewProps,
+  useResponsiveProp,
+  getA11yPropsFromHtmlTag,
+  layoutTags
+} from '../utils'
 import { useThemeTokens } from '../ThemeProvider'
 import { useViewport } from '../ViewportProvider'
 import getStackedContent from './getStackedContent'
@@ -51,31 +61,44 @@ import { staticStyles, selectFlexStyles } from './common'
  * It applies no accessibility props of its own, unless `divider` prop is passed (`Divider` has a
  * semantic role but only on web, not within native apps).
  */
-const StackView = ({
-  space = 1,
-  divider,
-  direction: directionProp = 'column',
-  children,
-  variant,
-  tokens,
-  ...rest
-}) => {
-  const viewport = useViewport()
-  const direction = useResponsiveProp(directionProp, 'column')
-  const a11y = a11yProps.select({ ...rest })
-  const content = getStackedContent(children, { direction, divider, space })
-  const themeTokens = useThemeTokens('StackView', tokens, variant, { viewport })
-  const flexStyles = selectFlexStyles(themeTokens)
+const StackView = forwardRef(
+  (
+    {
+      space = 1,
+      divider,
+      direction: directionProp = 'column',
+      children,
+      variant,
+      tokens,
+      tag,
+      accessibilityRole,
+      ...rest
+    },
+    ref
+  ) => {
+    const viewport = useViewport()
+    const direction = useResponsiveProp(directionProp, 'column')
+    const props = {
+      ...getA11yPropsFromHtmlTag(tag, accessibilityRole),
+      ...a11yProps.select(rest),
+      ...viewProps.select(rest)
+    }
+    const content = getStackedContent(children, { direction, divider, space })
+    const themeTokens = useThemeTokens('StackView', tokens, variant, { viewport })
+    const flexStyles = selectFlexStyles(themeTokens)
 
-  return (
-    <View {...a11y} style={[flexStyles, staticStyles[direction]]}>
-      {content}
-    </View>
-  )
-}
+    return (
+      <View ref={ref} {...props} style={[flexStyles, staticStyles[direction]]}>
+        {content}
+      </View>
+    )
+  }
+)
+StackView.displayName = 'StackView'
 
 StackView.propTypes = {
   ...a11yProps.propTypes,
+  tokens: getTokensPropType('StackView'),
   variant: variantProp.propType,
   /**
    * Sets the `flexDirection` of the container and, if `divider` is used, gives the Divider the appropriate direction.
@@ -94,6 +117,13 @@ StackView.propTypes = {
    * or, a SpacingObject with viewport keys and options (see `useSpacingScale` for details).
    */
   space: spacingProps.types.spacingValue,
+  /**
+   * Optional semantic HTML tag, to apply to the container on web. Does not change styling.
+   *
+   * In native apps, if a header tag is provided ("h1", "h2" etc) and accessibilityRole prop
+   * is not defined, the accessibilityRole will default to "heading".
+   */
+  tag: PropTypes.oneOf(layoutTags),
   /**
    * A StackView 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/StackWrap.jsx

@@ -1,4 +1,5 @@
-import React from 'react'
+import React, { forwardRef } from 'react'
+import { Platform } from 'react-native'
 
 import StackWrapBox from './StackWrapBox'
 import StackWrapGap from './StackWrapGap'
@@ -14,20 +15,28 @@ const exampleGapValue = '1px'
  * wrapped lines of items. By default, this `gap` is the same as the gap between spaced items.
  * If a different spacing is desired between wrapped lines, pass a spacing value to the `gap` prop.
  */
-const StackWrap = (props) => {
+const StackWrap = forwardRef((props, ref) => {
   const { space } = props
   // Don't apply separate gap if `null` or `undefined`, so can be unset in Storybook etc
-  // eslint-disable-next-line react/destructuring-assignment
   const gap = props.gap ?? space
 
-  return gap === space && CSS?.supports('gap', exampleGapValue) ? (
+  const canUseCSSGap =
+    Platform.OS === 'web' &&
+    gap === space &&
+    // In Jest/CI, global CSS isn't always available and doesn't always have .supports method
+    typeof CSS?.supports === 'function' &&
+    CSS.supports('gap', exampleGapValue)
+
+  return canUseCSSGap ? (
     // If possible, use the cleaner implementation that applies CSS `gap` styles to the container.
-    <StackWrapGap {...props} />
+    <StackWrapGap ref={ref} {...props} />
   ) : (
     // Else, use the fallback implementation which renders a `Box` component around each child.
-    <StackWrapBox {...props} />
+    <StackWrapBox ref={ref} {...props} />
   )
-}
+})
+StackWrap.displayName = 'StackWrap'
+
 StackWrap.propTypes = StackWrapBox.propTypes
 
 export default StackWrap