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

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
 }
 

package/src/Tabs/TabsItem.jsx

@@ -1,7 +1,6 @@
-import React, { useEffect } from 'react'
+import React, { forwardRef, useEffect } from 'react'
 import PropTypes from 'prop-types'
 import { Platform, Pressable, StyleSheet, Text, View } from 'react-native'
-import system from '@telus-uds/system-themes/src/tokens/rn'
 
 import { applyTextStyles, useThemeTokensCallback } from '../ThemeProvider'
 import {
@@ -13,7 +12,9 @@ import {
   a11yProps
 } from '../utils'
 import Spacer from '../Spacer'
-import { itemPositionsPropType, getItemPositionLayoutHandler } from './itemPositions'
+import { horizontalScrollUtils } from '../HorizontalScroll'
+
+const { itemPositionsPropType, getItemPositionLayoutHandler } = horizontalScrollUtils
 
 const selectHighlightBarStyles = ({
   highlightColor,
@@ -41,9 +42,9 @@ const selectHighlightTriangleStyles = ({ highlightColor, highlightTriangleSize }
     width: 0,
     borderWidth: highlightTriangleSize,
     borderTopColor: highlightColor,
-    borderBottomColor: system.color.transparent,
-    borderLeftColor: system.color.transparent,
-    borderRightColor: system.color.transparent
+    borderBottomColor: 'transparent',
+    borderLeftColor: 'transparent',
+    borderRightColor: 'transparent'
   }
 })
 
@@ -69,108 +70,115 @@ const selectContainerStyles = ({
  *
  * This is rendered automatically by `Tabs` and isn't intended be used directly.
  */
-const TabsItem = ({
-  onPress,
-  href,
-  variant,
-  tokens,
-  selected,
-  itemPositions,
-  index,
-  children,
-  accessibilityRole = href ? 'link' : 'tab',
-  accessibilityState = Platform.OS === 'web' && accessibilityRole === 'link'
-    ? // Web links can't be aria-selected but can be aria-current
-      { current: selected ? 'page' : false }
-    : { selected },
-  ...rest
-}) => {
-  const getTokens = useThemeTokensCallback('TabsItem', tokens, variant)
-  const resolveTokens = (pressableState) =>
-    resolvePressableTokens(getTokens, pressableState, { selected })
-
-  const getPressableStyle = (pressableState) => {
-    const { maxWidth } = resolveTokens(pressableState)
-    return [{ maxWidth }, Platform.OS === 'web' && { outline: 'none' }]
-  }
+const TabsItem = forwardRef(
+  (
+    {
+      onPress,
+      href,
+      variant,
+      tokens,
+      selected,
+      itemPositions,
+      index,
+      children,
+      accessibilityRole = href ? 'link' : 'tab',
+      accessibilityState = Platform.OS === 'web' && accessibilityRole === 'link'
+        ? // Web links can't be aria-selected but can be aria-current
+          { current: selected ? 'page' : false }
+        : { selected },
+      ...rest
+    },
+    ref
+  ) => {
+    const getTokens = useThemeTokensCallback('TabsItem', tokens, variant)
+    const resolveTokens = (pressableState) =>
+      resolvePressableTokens(getTokens, pressableState, { selected })
+
+    const getPressableStyle = (pressableState) => {
+      const { maxWidth } = resolveTokens(pressableState)
+      return [{ maxWidth }, Platform.OS === 'web' && { outline: 'none' }]
+    }
 
-  const handleLayout = getItemPositionLayoutHandler(itemPositions.positions, index)
+    const handleLayout = getItemPositionLayoutHandler(itemPositions.positions, index)
+
+    // On press, update the selection, call any press handler, and open any href in platform-appropriate way
+    const openHref = href && linkProps.handleHref({ href })
+    const handlePress =
+      onPress || openHref
+        ? () => {
+            if (onPress) onPress()
+            if (openHref) openHref()
+          }
+        : undefined
+
+    const a11y = {
+      accessibilityRole,
+      accessibilityState,
+      ...a11yProps.select(rest)
+    }
 
-  // On press, update the selection, call any press handler, and open any href in platform-appropriate way
-  const openHref = href && linkProps.handleHref({ href })
-  const handlePress =
-    onPress || openHref
-      ? () => {
-          if (onPress) onPress()
-          if (openHref) openHref()
+    useEffect(() => {
+      // If this is selected while off-screen, scroll it into view
+      if (selected) {
+        const position = itemPositions.positions[index]
+        const scrollEnd = itemPositions.scrollOffset + itemPositions.containerWidth
+        if (
+          // is off the right edge, or
+          (scrollEnd && position?.end > scrollEnd) ||
+          // is off the left edge
+          (typeof position?.start === 'number' && position.start < itemPositions.scrollOffset)
+        ) {
+          itemPositions.scrollTo(position.start)
         }
-      : undefined
-
-  const a11y = {
-    accessibilityRole,
-    accessibilityState,
-    ...a11yProps.select(rest)
-  }
-
-  useEffect(() => {
-    // If this is selected while off-screen, scroll it into view
-    if (selected) {
-      const position = itemPositions.positions[index]
-      const scrollEnd = itemPositions.scrollOffset + itemPositions.containerWidth
-      if (
-        // is off the right edge, or
-        (scrollEnd && position?.end > scrollEnd) ||
-        // is off the left edge
-        (typeof position?.start === 'number' && position.start < itemPositions.scrollOffset)
-      ) {
-        itemPositions.scrollTo(position.start)
       }
-    }
-    // itemPositions is a ref object so this should only re-run when `selected` (or `index`) change
-  }, [selected, index, itemPositions])
-
-  return (
-    <Pressable
-      onPress={handlePress}
-      href={href}
-      style={getPressableStyle}
-      onLayout={handleLayout}
-      {...a11y}
-    >
-      {(pressableState) => {
-        const { space, textAlign, ...themeTokens } = resolveTokens(pressableState)
-
-        const hasHighlightBar = Boolean(themeTokens.highlightBarHeight)
-        const highlightBarStyle = hasHighlightBar && selectHighlightBarStyles(themeTokens)
-
-        const hasHighlightTriangle = Boolean(themeTokens.highlightTriangleSize)
-        const highlightTriangleStyle =
-          hasHighlightTriangle && selectHighlightTriangleStyles(themeTokens)
-
-        const containerStyles = selectContainerStyles(themeTokens)
-        const textStyles = applyTextStyles({
-          ...selectTokens('Typography', themeTokens),
-          textAlign
-        })
-
-        return (
-          <View style={staticStyles.container}>
-            <View style={containerStyles}>
-              <Text style={textStyles}>{children}</Text>
-            </View>
-            <Spacer space={space} />
-            {hasHighlightBar && <View style={[staticStyles.absolute, highlightBarStyle]} />}
-            {hasHighlightTriangle && (
-              <View style={[staticStyles.absolute, highlightTriangleStyle.container]}>
-                <View style={highlightTriangleStyle.triangle} />
+      // itemPositions is a ref object so this should only re-run when `selected` (or `index`) change
+    }, [selected, index, itemPositions])
+
+    return (
+      <Pressable
+        ref={ref}
+        onPress={handlePress}
+        href={href}
+        style={getPressableStyle}
+        onLayout={handleLayout}
+        {...a11y}
+      >
+        {(pressableState) => {
+          const { space, textAlign, ...themeTokens } = resolveTokens(pressableState)
+
+          const hasHighlightBar = Boolean(themeTokens.highlightBarHeight)
+          const highlightBarStyle = hasHighlightBar && selectHighlightBarStyles(themeTokens)
+
+          const hasHighlightTriangle = Boolean(themeTokens.highlightTriangleSize)
+          const highlightTriangleStyle =
+            hasHighlightTriangle && selectHighlightTriangleStyles(themeTokens)
+
+          const containerStyles = selectContainerStyles(themeTokens)
+          const textStyles = applyTextStyles({
+            ...selectTokens('Typography', themeTokens),
+            textAlign
+          })
+
+          return (
+            <View style={staticStyles.container}>
+              <View style={containerStyles}>
+                <Text style={textStyles}>{children}</Text>
               </View>
-            )}
-          </View>
-        )
-      }}
-    </Pressable>
-  )
-}
+              <Spacer space={space} />
+              {hasHighlightBar && <View style={[staticStyles.absolute, highlightBarStyle]} />}
+              {hasHighlightTriangle && (
+                <View style={[staticStyles.absolute, highlightTriangleStyle.container]}>
+                  <View style={highlightTriangleStyle.triangle} />
+                </View>
+              )}
+            </View>
+          )
+        }}
+      </Pressable>
+    )
+  }
+)
+TabsItem.displayName = 'TabsItem'
 
 TabsItem.propTypes = {
   ...a11yProps.propTypes,

package/src/Tags/Tags.jsx

@@ -1,5 +1,6 @@
-import React from 'react'
+import React, { forwardRef } from 'react'
 import PropTypes from 'prop-types'
+import ABBPropTypes from 'airbnb-prop-types'
 import { Platform, Text, View } from 'react-native'
 
 import ButtonBase from '../Button/ButtonBase'
@@ -51,106 +52,113 @@ const selectIconTextTokens = ({
   }
 })
 
-const Tags = ({
-  variant,
-  tokens,
-  items = [],
-  values,
-  initialValues,
-  maxValues,
-  onChange,
-  readOnly = false,
-  inactive = false,
-  accessibilityRole = Platform.select({ web: 'group', default: 'none' }),
-  ...rest
-}) => {
-  const viewport = useViewport()
-  const themeTokens = useThemeTokens('Tags', tokens, variant, { viewport })
-  const stackTokens = selectTokens('StackView', themeTokens)
-  const { direction, space } = themeTokens
-
-  const getItemTokens = useThemeTokensCallback('TagsItem', tokens, variant)
-  const getButtonTokens = (buttonState) => selectTokens('Button', getItemTokens(buttonState))
-
-  const { currentValues, toggleOneValue } = useMultipleInputValues({
-    initialValues,
-    values,
-    maxValues,
-    onChange,
-    readOnly
-  })
-
-  const a11y = a11yProps.select({
-    accessibilityRole,
-    ...rest
-  })
-  const itemA11yRole = 'checkbox'
-
-  return (
-    <StackWrap {...a11y} space={space} direction={direction} tokens={stackTokens}>
-      {items.map(({ label, id = label, accessibilityLabel }, index) => {
-        const isSelected = currentValues.includes(id)
-
-        // Pass an object of relevant component state as first argument for any passed-in press handlers
-        const pressHandlers = getPressHandlersWithArgs(rest, [{ id, label, currentValues }])
-
-        const handlePress = () => {
-          if (pressHandlers.onPress) pressHandlers.onPress()
-          toggleOneValue(id)
-        }
-
-        const itemA11y = {
-          accessibilityState: { checked: isSelected },
-          accessibilityRole: itemA11yRole,
-          accessibilityLabel,
-          ...a11yProps.getPositionInSet(items.length, index)
-        }
-
-        return (
-          <ButtonBase
-            key={id}
-            {...pressHandlers}
-            onPress={handlePress}
-            tokens={getButtonTokens}
-            selected={isSelected}
-            inactive={inactive}
-            {...itemA11y}
-          >
-            {({ textStyles, ...buttonState }) => {
-              // TODO: once Icon/IconButton designs are stable, see if this sort of styling around
-              // an icon should go in Icon itself, or possibly via an IconText token set. Related issues:
-              // - Icon: https://github.com/telus/universal-design-system/issues/327
-              // - IconButton: https://github.com/telus/universal-design-system/issues/281
-              // - Token sets: https://github.com/telus/universal-design-system/issues/782
-
-              const itemTokens = getItemTokens(buttonState)
-
-              const {
-                iconTokens,
-                iconPosition,
-                iconSpace,
-                iconWrapperStyle,
-                icon: IconComponent
-              } = selectIconTextTokens(itemTokens)
-
-              const iconContent = IconComponent ? (
-                <View style={iconWrapperStyle}>
-                  <Icon icon={IconComponent} tokens={iconTokens} />
-                </View>
-              ) : null
-              const textContent = <Text style={textStyles}>{label}</Text>
-
-              return getStackedContent(
-                iconPosition === 'left' ? [iconContent, textContent] : [textContent, iconContent],
-                { space: iconSpace, direction: 'row' }
-              )
-            }}
-          </ButtonBase>
-        )
-      })}
-    </StackWrap>
-  )
-}
+const Tags = forwardRef(
+  (
+    {
+      variant,
+      tokens,
+      items = [],
+      values,
+      initialValues,
+      maxValues,
+      onChange,
+      readOnly = false,
+      inactive = false,
+      accessibilityRole = Platform.select({ web: 'group', default: 'none' }),
+      ...rest
+    },
+    ref
+  ) => {
+    const viewport = useViewport()
+    const themeTokens = useThemeTokens('Tags', tokens, variant, { viewport })
+    const stackTokens = selectTokens('StackView', themeTokens)
+    const { direction, space } = themeTokens
+
+    const getItemTokens = useThemeTokensCallback('TagsItem', tokens, variant)
+    const getButtonTokens = (buttonState) => selectTokens('Button', getItemTokens(buttonState))
+
+    const { currentValues, toggleOneValue } = useMultipleInputValues({
+      initialValues,
+      values,
+      maxValues,
+      onChange,
+      readOnly
+    })
+
+    const a11y = a11yProps.select({
+      accessibilityRole,
+      ...rest
+    })
+    const itemA11yRole = 'checkbox'
+
+    return (
+      <StackWrap ref={ref} {...a11y} space={space} direction={direction} tokens={stackTokens}>
+        {items.map(({ label, id = label, accessibilityLabel, ref: itemRef }, index) => {
+          const isSelected = currentValues.includes(id)
+
+          // Pass an object of relevant component state as first argument for any passed-in press handlers
+          const pressHandlers = getPressHandlersWithArgs(rest, [{ id, label, currentValues }])
+
+          const handlePress = (event) => {
+            if (pressHandlers.onPress) pressHandlers.onPress()
+            toggleOneValue(id, event)
+          }
+
+          const itemA11y = {
+            accessibilityState: { checked: isSelected },
+            accessibilityRole: itemA11yRole,
+            accessibilityLabel,
+            ...a11yProps.getPositionInSet(items.length, index)
+          }
+
+          return (
+            <ButtonBase
+              ref={itemRef}
+              key={id}
+              {...pressHandlers}
+              onPress={handlePress}
+              tokens={getButtonTokens}
+              selected={isSelected}
+              inactive={inactive}
+              {...itemA11y}
+            >
+              {({ textStyles, ...buttonState }) => {
+                // TODO: once Icon/IconButton designs are stable, see if this sort of styling around
+                // an icon should go in Icon itself, or possibly via an IconText token set. Related issues:
+                // - Icon: https://github.com/telus/universal-design-system/issues/327
+                // - IconButton: https://github.com/telus/universal-design-system/issues/281
+                // - Token sets: https://github.com/telus/universal-design-system/issues/782
+
+                const itemTokens = getItemTokens(buttonState)
+
+                const {
+                  iconTokens,
+                  iconPosition,
+                  iconSpace,
+                  iconWrapperStyle,
+                  icon: IconComponent
+                } = selectIconTextTokens(itemTokens)
+
+                const iconContent = IconComponent ? (
+                  <View style={iconWrapperStyle}>
+                    <Icon icon={IconComponent} tokens={iconTokens} />
+                  </View>
+                ) : null
+                const textContent = <Text style={textStyles}>{label}</Text>
+
+                return getStackedContent(
+                  iconPosition === 'left' ? [iconContent, textContent] : [textContent, iconContent],
+                  { space: iconSpace, direction: 'row' }
+                )
+              }}
+            </ButtonBase>
+          )
+        })}
+      </StackWrap>
+    )
+  }
+)
+Tags.displayName = 'Tags'
 
 Tags.propTypes = {
   ...a11yProps.propTypes,
@@ -181,7 +189,11 @@ Tags.propTypes = {
        * which will be used in code and passed to any onChange function.
        * If not provided, the label is used.
        */
-      id: PropTypes.string
+      id: PropTypes.string,
+      /**
+       * An optional ref for one individual Tag button in the tags
+       */
+      ref: ABBPropTypes.ref()
     })
   ),
   /**