@telus-uds/components-base 0.0.2-prerelease.7 → 1.0.1

package/src/Skeleton/Skeleton.jsx

@@ -1,14 +1,16 @@
-import React, { useEffect, useRef } from 'react'
+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,
-  opacity: fadeAnimation
+  ...fadeAnimation
 })
 
 const selectLineStyles = ({ skeletonHeight, lineWidth }) => ({
@@ -25,10 +27,18 @@ const selectSquareStyles = ({ radius }) => ({
   borderRadius: radius
 })
 
-const Skeleton = ({ tokens, variant, size, characters, lines, shape = 'line' }) => {
+const Skeleton = forwardRef(({ tokens, variant, size, characters, lines, shape = 'line' }, ref) => {
   const themeTokens = useThemeTokens('Skeleton', tokens, variant)
   const skeletonHeight = useSpacingScale(size || themeTokens.size)
-  const fadeAnimation = useRef(new Animated.Value(0)).current
+  const nativeAnimation = useSkeletonNativeAnimation()
+
+  const getAnimationBaseOnPlatform = () => {
+    if (Platform.OS !== 'web') {
+      return nativeAnimation
+    }
+
+    return skeletonWebAnimation
+  }
 
   const getLineWidth = () => {
     if (characters) {
@@ -38,22 +48,6 @@ const Skeleton = ({ tokens, variant, size, characters, lines, shape = 'line' })
     return themeTokens.characters * themeTokens.baseWidth
   }
 
-  useEffect(() => {
-    const fade = Animated.sequence([
-      Animated.timing(fadeAnimation, {
-        toValue: 1,
-        duration: 1000,
-        useNativeDriver: Platform.OS !== 'web'
-      }),
-      Animated.timing(fadeAnimation, {
-        toValue: 0,
-        duration: 1000,
-        useNativeDriver: Platform.OS !== 'web'
-      })
-    ])
-    Animated.loop(fade).start()
-  }, [fadeAnimation])
-
   const getStyledBasedOnShape = () => {
     if (shape === 'circle') {
       return selectShapeStyles({ skeletonHeight })
@@ -73,21 +67,20 @@ const Skeleton = ({ tokens, variant, size, characters, lines, shape = 'line' })
     <Animated.View
       testID="skeleton"
       key={`skeleton-${index + 1}`}
-      style={[selectSkeletonStyles({ ...themeTokens, fadeAnimation }), getStyledBasedOnShape()]}
+      style={[
+        selectSkeletonStyles({ ...themeTokens, fadeAnimation: getAnimationBaseOnPlatform() }),
+        getStyledBasedOnShape()
+      ]}
     />
   )
 
-  if (lines) {
-    const arrayOfSkeletons = [...Array(lines)]
-    return (
-      <StackView space={themeTokens.spaceBetweenLines}>
-        {arrayOfSkeletons.map((_, index) => renderSkeleton(index))}
-      </StackView>
-    )
-  }
-
-  return renderSkeleton()
-}
+  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'),

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,45 @@ 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,
+  ...viewProps.types,
+  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 +118,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

package/src/StackView/StackWrapBox.jsx

@@ -1,13 +1,17 @@
-import React from 'react'
+import React, { forwardRef } from 'react'
 import PropTypes from 'prop-types'
 import { View } from 'react-native'
 
 import {
   spacingProps,
   a11yProps,
+  getTokensPropType,
   responsiveProps,
   useSpacingScale,
-  useResponsiveProp
+  useResponsiveProp,
+  viewProps,
+  getA11yPropsFromHtmlTag,
+  layoutTags
 } from '../utils'
 import { useThemeTokens } from '../ThemeProvider'
 import { useViewport } from '../ViewportProvider'
@@ -41,36 +45,54 @@ const spaceSides = {
  * Unlike the cleaner and more side-effect-free CSS gap StackWrap implementation, this renders a Box (View)
  * between the container and the stacked children, and requires a negative margin on the container.
  */
-const StackWrapBox = ({
-  space = 1,
-  gap = space,
-  direction: directionProp = 'row',
-  children,
-  tokens,
-  variant,
-  ...rest
-}) => {
-  const viewport = useViewport()
-  const direction = useResponsiveProp(directionProp, 'row')
-  const themeTokens = useThemeTokens('StackView', tokens, variant, { viewport })
-  const flexStyles = selectFlexStyles(themeTokens)
-  const a11y = a11yProps.select({ ...rest })
+const StackWrapBox = forwardRef(
+  (
+    {
+      space = 1,
+      gap = space,
+      direction: directionProp = 'row',
+      children,
+      tokens,
+      variant,
+      tag,
+      accessibilityRole,
+      ...rest
+    },
+    ref
+  ) => {
+    const viewport = useViewport()
+    const direction = useResponsiveProp(directionProp, 'row')
+    const themeTokens = useThemeTokens('StackView', tokens, variant, { viewport })
+    const flexStyles = selectFlexStyles(themeTokens)
+    const props = {
+      ...getA11yPropsFromHtmlTag(tag, accessibilityRole),
+      ...a11yProps.select(rest),
+      ...viewProps.select(rest)
+    }
 
-  // Mimic CSS `gap` using box spacing on the side after a wrapped row then offsetting it on the last row.
-  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 })
+    // Mimic CSS `gap` using box spacing on the side after a wrapped row then offsetting it on the last row.
+    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 })
 
-  return (
-    <View {...a11y} style={[flexStyles, staticStyles.wrap, staticStyles[direction], offsetStyle]}>
-      {content}
-    </View>
-  )
-}
+    return (
+      <View
+        ref={ref}
+        {...props}
+        style={[flexStyles, staticStyles.wrap, staticStyles[direction], offsetStyle]}
+      >
+        {content}
+      </View>
+    )
+  }
+)
+StackWrapBox.displayName = 'StackWrapBox'
 
 StackWrapBox.propTypes = {
   ...a11yProps.propTypes,
+  ...viewProps.types,
+  tokens: getTokensPropType('StackView'),
   /**
    * Sets the `flexDirection` of the container
    */
@@ -78,11 +100,24 @@ StackWrapBox.propTypes = {
     PropTypes.oneOf(['column', 'row', 'row-reverse', 'column-reverse'])
   ),
   /**
-   * The size of the spacer according to the theme's spacing scale.
+   * The size of the space between items according to the theme's spacing scale.
    * Either a number corresponding to a position on the theme's spacing scale (1 is smallest, 2 is second smallest, etc),
    * or, a SpacingObject with viewport keys and options (see `useSpacingScale` for details).
    */
   space: spacingProps.types.spacingValue,
+  /**
+   * The size of the space between lines of content, according to the theme's spacing scale. By default, matches `space`.
+   * Either a number corresponding to a position on the theme's spacing scale (1 is smallest, 2 is second smallest, etc),
+   * or, a SpacingObject with viewport keys and options (see `useSpacingScale` for details).
+   */
+  gap: 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 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

@@ -1,8 +1,14 @@
-import React from 'react'
+import React, { forwardRef } from 'react'
 import { View } from 'react-native'
 
 import StackWrapBox from './StackWrapBox'
-import { a11yProps, useSpacingScale, useResponsiveProp } from '../utils'
+import {
+  a11yProps,
+  useSpacingScale,
+  useResponsiveProp,
+  viewProps,
+  getA11yPropsFromHtmlTag
+} from '../utils'
 import { useThemeTokens } from '../ThemeProvider'
 import { useViewport } from '../ViewportProvider'
 import getStackedContent from './getStackedContent'
@@ -18,31 +24,47 @@ import { staticStyles, selectFlexStyles } from './common'
  * - The `space` between items is the same as the `gap` between wrapped rows (this is the
  *   default if `gap` prop is undefined)
  */
-const StackWrapGap = ({
-  space = 1,
-  tokens,
-  variant,
-  direction: directionProp = 'row',
-  children,
-  ...rest
-}) => {
-  const viewport = useViewport()
-  const direction = useResponsiveProp(directionProp, 'row')
-  const themeTokens = useThemeTokens('StackView', tokens, variant, { viewport })
-  const flexStyles = selectFlexStyles(themeTokens)
-  const a11y = a11yProps.select({ ...rest })
+const StackWrapGap = forwardRef(
+  (
+    {
+      space = 1,
+      tokens,
+      variant,
+      direction: directionProp = 'row',
+      children,
+      tag,
+      accessibilityRole,
+      ...rest
+    },
+    ref
+  ) => {
+    const viewport = useViewport()
+    const direction = useResponsiveProp(directionProp, 'row')
+    const themeTokens = useThemeTokens('StackView', tokens, variant, { viewport })
+    const flexStyles = selectFlexStyles(themeTokens)
+    const props = {
+      ...getA11yPropsFromHtmlTag(tag, accessibilityRole),
+      ...a11yProps.select(rest),
+      ...viewProps.select(rest)
+    }
 
-  const size = useSpacingScale(space)
-  const gapStyle = { gap: size }
+    const size = useSpacingScale(space)
+    const gapStyle = { gap: size }
 
-  const content = getStackedContent(children, { direction, space: 0 })
+    const content = getStackedContent(children, { direction, space: 0 })
 
-  return (
-    <View {...a11y} style={[flexStyles, staticStyles.wrap, staticStyles[direction], gapStyle]}>
-      {content}
-    </View>
-  )
-}
+    return (
+      <View
+        ref={ref}
+        {...props}
+        style={[flexStyles, staticStyles.wrap, staticStyles[direction], gapStyle]}
+      >
+        {content}
+      </View>
+    )
+  }
+)
+StackWrapGap.displayName = 'StackWrapGap'
 
 StackWrapGap.propTypes = StackWrapBox.propTypes
 

package/src/StackView/common.jsx

@@ -1,9 +1,10 @@
 import { StyleSheet } from 'react-native'
 
-export const selectFlexStyles = ({ alignItems, justifyContent, flexGrow }) => ({
+export const selectFlexStyles = ({ alignItems, justifyContent, flexGrow, flexShrink }) => ({
   alignItems,
   justifyContent,
-  flexGrow
+  flexGrow,
+  flexShrink
 })
 
 export const staticStyles = StyleSheet.create({

package/src/StackView/getStackedContent.jsx

@@ -23,17 +23,23 @@ import Spacer from '../Spacer'
  *  - `direction`: if 'row' or 'row-reverse', applies space horizontally, if 'column' or 'column-reverse', applies space vertically
  *  - `box`: if truthy, wraps each valid child in a Box component; if an object, passes it to Box as props
  *  - `divider`: if truthy, inserts Divider components; if an object, passes it to Divider as props
+ *  - `preserveFragments`: if true, adds no space between top-level elements that were passed inside a nested fragment
  * @param {SpacingValue} [options.space]
  * @param {boolean | object} [options.divider]
  * @param {"row" | "column" | "row-reverse" | "column-reverse"} [options.direction]
+ * @param {boolean} [options.preserveFragments]
  * @returns {ReactElement[]}
  */
-const getStackedContent = (children, { divider, space, direction = 'column', box }) => {
+const getStackedContent = (
+  children,
+  { divider, space, direction = 'column', box, preserveFragments = false }
+) => {
   const boxProps = box && typeof box === 'object' ? box : { space }
   const dividerProps = divider && typeof divider === 'object' ? divider : {}
 
   // Avoid surprises if children contains comments, nulls, or is a variable wrapped as a fragment
-  const validChildren = Children.toArray(unpackFragment(children)).filter(Boolean)
+  const topLevelChildren = preserveFragments ? children : unpackFragment(children)
+  const validChildren = Children.toArray(topLevelChildren).filter(Boolean)
   const content = validChildren.reduce((newChildren, child, index) => {
     const boxID = `Stack-Box-${index}`
     const item = box ? (