@telus-uds/components-base 0.0.2-prerelease.9 → 1.1.0

package/src/StackView/StackView.jsx

@@ -1,4 +1,4 @@
-import React from 'react'
+import React, { forwardRef } from 'react'
 import PropTypes from 'prop-types'
 import { View } from 'react-native'
 
@@ -6,10 +6,13 @@ import Divider from '../Divider'
 import {
   spacingProps,
   a11yProps,
+  getTokensPropType,
   responsiveProps,
   variantProp,
   viewProps,
-  useResponsiveProp
+  useResponsiveProp,
+  getA11yPropsFromHtmlTag,
+  layoutTags
 } from '../utils'
 import { useThemeTokens } from '../ThemeProvider'
 import { useViewport } from '../ViewportProvider'
@@ -58,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 props = { ...a11yProps.select(rest), ...viewProps.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 {...props} 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.
@@ -101,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,9 +1,15 @@
-import React from 'react'
+import React, { forwardRef } from 'react'
 import { Platform } from 'react-native'
 
 import StackWrapBox from './StackWrapBox'
 import StackWrapGap from './StackWrapGap'
 
+// In Jest/CI/SSR, global CSS isn't always available and doesn't always have .supports method
+const cssSupports = (...args) =>
+  typeof window !== 'undefined' &&
+  typeof window.CSS?.supports === 'function' &&
+  window.CSS.supports(...args)
+
 // CSS.supports needs an example of the type of value you intend to use.
 // Will be an integer appended `px` after hooks and JSX styles are resolved.
 const exampleGapValue = '1px'
@@ -15,27 +21,23 @@ 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
 
-  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)
+  const canUseCSSGap = Platform.OS === 'web' && gap === space && cssSupports('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,14 +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,
-  viewProps
+  viewProps,
+  getA11yPropsFromHtmlTag,
+  layoutTags
 } from '../utils'
 import { useThemeTokens } from '../ThemeProvider'
 import { useViewport } from '../ViewportProvider'
@@ -42,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 props = { ...a11yProps.select(rest), ...viewProps.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 {...props} 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
    */
@@ -79,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, viewProps } 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 props = { ...a11yProps.select(rest), ...viewProps.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 {...props} 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/StepTracker/StepTracker.jsx

@@ -1,4 +1,4 @@
-import React from 'react'
+import React, { forwardRef } from 'react'
 import PropTypes from 'prop-types'
 import { StyleSheet, Text, View } from 'react-native'
 
@@ -73,70 +73,81 @@ const selectStepTrackerLabelStyles = ({
  * - `accessibilityValue.text` (`aria-valuetext`): `<Current Step Label>`,
  *
  */
-const StepTracker = ({
-  current = 0,
-  copy = 'en',
-  dictionary = defaultDictionary,
-  steps = [],
-  tokens,
-  variant,
-  ...rest
-}) => {
-  const viewport = useViewport()
-  const { showStepTrackerLabel, ...themeTokens } = useThemeTokens('StepTracker', tokens, variant, {
-    viewport
-  })
-  const getCopy = useCopy({ dictionary, copy })
-  const stepTrackerLabel = getCopy('stepTrackerLabel')
-    .replace('%{stepNumber}', current < steps.length ? current + 1 : steps.length)
-    .replace('%{stepCount}', steps.length)
-    .replace('%{stepLabel}', current < steps.length ? steps[current] : steps[steps.length - 1])
-  if (!steps.length) return null
-  const accessibilityProps = {
-    accessibilityLabel: stepTrackerLabel,
-    accessibilityLevel: 1,
-    accessibilityRole: 'progressbar',
-    accessibilityValue: {
-      min: 0,
-      max: steps.length - 1,
-      now: current,
-      text: steps[current]
+const StepTracker = forwardRef(
+  (
+    {
+      current = 0,
+      copy = 'en',
+      dictionary = defaultDictionary,
+      steps = [],
+      tokens,
+      variant,
+      ...rest
     },
-    ...a11yProps.select(rest)
-  }
+    ref
+  ) => {
+    const viewport = useViewport()
+    const { showStepTrackerLabel, ...themeTokens } = useThemeTokens(
+      'StepTracker',
+      tokens,
+      variant,
+      {
+        viewport
+      }
+    )
+    const getCopy = useCopy({ dictionary, copy })
+    const stepTrackerLabel = getCopy('stepTrackerLabel')
+      .replace('%{stepNumber}', current < steps.length ? current + 1 : steps.length)
+      .replace('%{stepCount}', steps.length)
+      .replace('%{stepLabel}', current < steps.length ? steps[current] : steps[steps.length - 1])
+    if (!steps.length) return null
+    const accessibilityProps = {
+      accessibilityLabel: stepTrackerLabel,
+      accessibilityLevel: 1,
+      accessibilityRole: 'progressbar',
+      accessibilityValue: {
+        min: 0,
+        max: steps.length - 1,
+        now: current,
+        text: steps[current]
+      },
+      ...a11yProps.select(rest)
+    }
 
-  return (
-    <View style={selectContainerStyles(themeTokens)} {...accessibilityProps}>
-      <StackView space={0}>
-        <View style={staticStyles.stepsContainer}>
-          {steps.map((label, index) => {
-            return (
-              <Step
-                status={current}
-                key={label}
-                label={label}
-                name={getCopy('stepLabel').replace('%{stepNumber}', index + 1)}
-                stepIndex={index}
-                stepCount={steps.length}
-                tokens={themeTokens}
-              />
-            )
-          })}
-        </View>
-        {showStepTrackerLabel && (
-          <View
-            style={[
-              staticStyles.stepTrackerLabelContainer,
-              selectStepTrackerLabelContainerStyles(themeTokens)
-            ]}
-          >
-            <Text style={selectStepTrackerLabelStyles(themeTokens)}>{stepTrackerLabel}</Text>
+    return (
+      <View ref={ref} style={selectContainerStyles(themeTokens)} {...accessibilityProps}>
+        <StackView space={0}>
+          <View style={staticStyles.stepsContainer}>
+            {steps.map((label, index) => {
+              return (
+                <Step
+                  status={current}
+                  key={label}
+                  label={label}
+                  name={getCopy('stepLabel').replace('%{stepNumber}', index + 1)}
+                  stepIndex={index}
+                  stepCount={steps.length}
+                  tokens={themeTokens}
+                />
+              )
+            })}
           </View>
-        )}
-      </StackView>
-    </View>
-  )
-}
+          {showStepTrackerLabel && (
+            <View
+              style={[
+                staticStyles.stepTrackerLabelContainer,
+                selectStepTrackerLabelContainerStyles(themeTokens)
+              ]}
+            >
+              <Text style={selectStepTrackerLabelStyles(themeTokens)}>{stepTrackerLabel}</Text>
+            </View>
+          )}
+        </StackView>
+      </View>
+    )
+  }
+)
+StepTracker.displayName = 'StepTracker'
 
 StepTracker.propTypes = {
   current: PropTypes.number,