@telus-uds/components-base 0.0.2-prerelease.9 → 1.0.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,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 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,
+  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 +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,4 @@
-import React from 'react'
+import React, { forwardRef } from 'react'
 import { Platform } from 'react-native'
 
 import StackWrapBox from './StackWrapBox'
@@ -15,10 +15,9 @@ 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 =
@@ -30,12 +29,14 @@ const StackWrap = (props) => {
 
   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,53 @@ 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,
+  tokens: getTokensPropType('StackView'),
   /**
    * Sets the `flexDirection` of the container
    */
@@ -79,11 +99,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,

package/src/Tabs/Tabs.jsx

@@ -1,88 +1,96 @@
-import React, { useCallback } from 'react'
+import React, { forwardRef, useCallback } from 'react'
 import PropTypes from 'prop-types'
+import ABBPropTypes from 'airbnb-prop-types'
 
 import { useThemeTokens } from '../ThemeProvider'
 import StackView from '../StackView'
 import { getTokensPropType, variantProp, useHash, useInputValue } from '../utils'
-import HorizontalScroll, { selectHorizontalScrollTokens } from './HorizontalScroll'
+import HorizontalScroll, {
+  horizontalScrollUtils,
+  HorizontalScrollButton
+} from '../HorizontalScroll'
 import TabsItem from './TabsItem'
-import TabsScrollButton from './TabsScrollButton'
-import { useItemPositions } from './itemPositions'
+
+const { selectHorizontalScrollTokens, useItemPositions } = horizontalScrollUtils
 
 /**
  * Tabs renders a horizontally-scrolling menu of selectable buttons which may link
  * to a page or control what content is displayed on this page.
  */
-const Tabs = ({
-  tokens,
-  itemTokens,
-  scrollButtonTokens,
-  variant,
-  value,
-  initialValue,
-  onChange,
-  items = []
-}) => {
-  const { space, ...themeTokens } = useThemeTokens('Tabs', tokens, variant)
-  const { currentValue, setValue } = useInputValue({ value, initialValue, onChange })
+const Tabs = forwardRef(
+  (
+    { tokens, itemTokens, scrollButtonTokens, variant, value, initialValue, onChange, items = [] },
+    ref
+  ) => {
+    const { space, ...themeTokens } = useThemeTokens('Tabs', tokens, variant)
+    const { currentValue, setValue } = useInputValue({ value, initialValue, onChange })
 
-  const [itemPositions, isPositioningReady] = useItemPositions()
+    const [itemPositions, isPositioningReady] = useItemPositions()
 
-  useHash(
-    useCallback(
-      (hash) => {
-        const hashItem = hash && items.find(({ href }) => hash === href)
-        const hashId = hashItem && (hashItem.id || hashItem.label)
-        if (hashId) setTimeout(setValue(hashId), 500)
-      },
-      [items, setValue]
-    ),
-    isPositioningReady
-  )
+    useHash(
+      useCallback(
+        (hash, event) => {
+          const hashItem = hash && items.find(({ href }) => hash === href)
+          const hashId = hashItem && (hashItem.id || hashItem.label)
+          if (hashId) setTimeout(setValue(hashId, event), 500)
+        },
+        [items, setValue]
+      ),
+      isPositioningReady
+    )
 
-  return (
-    <HorizontalScroll
-      ScrollButton={TabsScrollButton}
-      itemPositions={itemPositions}
-      tokens={selectHorizontalScrollTokens(themeTokens)}
-      scrollButtonTokens={scrollButtonTokens}
-      accessibilityRole="tablist"
-    >
-      <StackView space={space} direction="row">
-        {items.map(({ href, label, id }, index) => {
-          const itemId = id ?? label
-          const isSelected = Boolean(currentValue && currentValue === itemId)
-          const handlePress = () => setValue(itemId)
-          return (
-            <TabsItem
-              key={itemId}
-              href={href}
-              variant={variant}
-              tokens={itemTokens}
-              onPress={handlePress}
-              selected={isSelected}
-              itemPositions={itemPositions}
-              index={index}
-            >
-              {label}
-            </TabsItem>
-          )
-        })}
-      </StackView>
-    </HorizontalScroll>
-  )
-}
+    return (
+      <HorizontalScroll
+        ref={ref}
+        ScrollButton={HorizontalScrollButton}
+        itemPositions={itemPositions}
+        tokens={selectHorizontalScrollTokens(themeTokens)}
+        scrollButtonTokens={scrollButtonTokens}
+        accessibilityRole="tablist"
+      >
+        <StackView space={space} direction="row">
+          {items.map(({ href, label, id, ref: itemRef }, index) => {
+            const itemId = id ?? label
+            const isSelected = Boolean(currentValue && currentValue === itemId)
+            const handlePress = (event) => setValue(itemId, event)
+            return (
+              <TabsItem
+                ref={itemRef}
+                key={itemId}
+                href={href}
+                variant={variant}
+                tokens={itemTokens}
+                onPress={handlePress}
+                selected={isSelected}
+                itemPositions={itemPositions}
+                index={index}
+              >
+                {label}
+              </TabsItem>
+            )
+          })}
+        </StackView>
+      </HorizontalScroll>
+    )
+  }
+)
+Tabs.displayName = 'Tabs'
 
 Tabs.propTypes = {
   items: PropTypes.arrayOf(
-    PropTypes.shape({ href: PropTypes.string, label: PropTypes.string, id: PropTypes.string })
+    PropTypes.shape({
+      href: PropTypes.string,
+      label: PropTypes.string,
+      id: PropTypes.string,
+      ref: ABBPropTypes.ref()
+    })
   ),
   value: PropTypes.string,
   initialValue: PropTypes.string,
   onChange: PropTypes.func,
   tokens: getTokensPropType('Tabs'),
   itemTokens: getTokensPropType('TabsItem'),
-  scrollButtonTokens: getTokensPropType('TabsScrollButton'),
+  scrollButtonTokens: getTokensPropType('HorizontalScrollButton'),
   variant: variantProp.propType
 }