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

package/src/Select/Select.jsx

@@ -1,4 +1,4 @@
-import React, { useState } from 'react'
+import React, { forwardRef, useState } from 'react'
 
 import { View, Platform, StyleSheet } from 'react-native'
 import PropTypes from 'prop-types'
@@ -147,100 +147,143 @@ const selectValidationIconContainerStyles = ({
  * NOTE: this does not work on native platforms - the grouped items will be shown at the same level as the non-grouped items.
  *
  */
-const Select = ({
-  value,
-  initialValue,
-  onChange,
-  children,
-  inactive,
-  readOnly,
-  placeholder,
-  validation,
-  tokens,
-  variant,
-  testID,
-  ...rest
-}) => {
-  const { currentValue, setValue } = useInputValue({
-    value,
-    initialValue,
-    onChange,
-    readOnly
-  })
+const Select = forwardRef(
+  (
+    {
+      value,
+      initialValue,
+      onChange,
+      children,
+      inactive,
+      readOnly,
+      placeholder,
+      validation,
+      tokens,
+      variant,
+      testID,
+      ...rest
+    },
+    ref
+  ) => {
+    const { currentValue, setValue } = useInputValue({
+      value,
+      initialValue,
+      onChange,
+      readOnly
+    })
 
-  const [isFocused, setIsFocused] = useState(false)
-  const handleFocus = () => setIsFocused(true)
-  const handleBlur = () => setIsFocused(false)
+    const [isFocused, setIsFocused] = useState(false)
+    const handleFocus = () => setIsFocused(true)
+    const handleBlur = () => setIsFocused(false)
 
-  const [isHovered, setIsHovered] = useState(false)
-  const handleMouseOver = () => setIsHovered(true)
-  const handleMouseOut = () => setIsHovered(false)
+    const [isHovered, setIsHovered] = useState(false)
+    const handleMouseOver = () => setIsHovered(true)
+    const handleMouseOut = () => setIsHovered(false)
 
-  const { props: supportsProps } = inputSupportsProps.select(rest)
+    const { props: supportsProps } = inputSupportsProps.select(rest)
 
-  const themeTokens = useThemeTokens('Select', tokens, variant, {
-    focus: isFocused,
-    hover: isHovered,
-    inactive,
-    validation
-  })
+    const themeTokens = useThemeTokens('Select', tokens, variant, {
+      focus: isFocused,
+      hover: isHovered,
+      inactive,
+      validation
+    })
+
+    const { icon: IconComponent, validationIcon: ValidationIconComponent } = themeTokens
 
-  const { icon: IconComponent, validationIcon: ValidationIconComponent } = themeTokens
-
-  return (
-    <InputSupports {...supportsProps}>
-      {({ a11yProps, inputId }) => (
-        <View style={selectOuterBorderStyles(themeTokens)}>
-          <Picker
-            style={selectInputStyles(themeTokens, inactive)}
-            onFocus={handleFocus}
-            onBlur={handleBlur}
-            onMouseOver={handleMouseOver}
-            onMouseOut={handleMouseOut}
-            onChange={setValue}
-            value={currentValue}
-            inactive={inactive}
-            placeholder={placeholder !== undefined ? { label: placeholder, value: '' } : undefined}
-            {...a11yProps}
-            nativeID={inputId}
-            testID={testID}
-          >
-            {children}
-          </Picker>
-          {ValidationIconComponent && (
-            <View
-              pointerEvents="none"
-              style={[staticStyles.iconContainer, selectValidationIconContainerStyles(themeTokens)]}
+    return (
+      <InputSupports {...supportsProps}>
+        {({ a11yProps, inputId }) => (
+          <View style={selectOuterBorderStyles(themeTokens)}>
+            <Picker
+              ref={ref}
+              style={selectInputStyles(themeTokens, inactive)}
+              onFocus={handleFocus}
+              onBlur={handleBlur}
+              onMouseOver={handleMouseOver}
+              onMouseOut={handleMouseOut}
+              onChange={setValue}
+              value={currentValue}
+              inactive={inactive}
+              placeholder={
+                placeholder !== undefined ? { label: placeholder, value: '' } : undefined
+              }
+              {...a11yProps}
+              nativeID={inputId}
+              testID={testID}
             >
-              <ValidationIconComponent tokens={selectValidationIconTokens(themeTokens)} />
-            </View>
-          )}
-          {IconComponent &&
-            Platform.OS !== 'android' && ( // we can't hide the default caret of a native picker on android
+              {children}
+            </Picker>
+            {ValidationIconComponent && (
               <View
                 pointerEvents="none"
-                style={[staticStyles.iconContainer, selectIconContainerStyles(themeTokens)]}
+                style={[
+                  staticStyles.iconContainer,
+                  selectValidationIconContainerStyles(themeTokens)
+                ]}
               >
-                <IconComponent {...selectIconTokens(themeTokens)} />
+                <ValidationIconComponent tokens={selectValidationIconTokens(themeTokens)} />
               </View>
             )}
-        </View>
-      )}
-    </InputSupports>
-  )
-}
+            {IconComponent &&
+              Platform.OS !== 'android' && ( // we can't hide the default caret of a native picker on android
+                <View
+                  pointerEvents="none"
+                  style={[staticStyles.iconContainer, selectIconContainerStyles(themeTokens)]}
+                >
+                  <IconComponent {...selectIconTokens(themeTokens)} />
+                </View>
+              )}
+          </View>
+        )}
+      </InputSupports>
+    )
+  }
+)
+Select.displayName = 'Select'
 
 Select.propTypes = {
   ...inputSupportsProps.types,
+  /**
+   * Initial value for the uncontrolled version.
+   */
   initialValue: PropTypes.string,
+  /**
+   * Current value to be set as selected.
+   */
   value: PropTypes.string,
+  /**
+   * Callback to be called when the value changes.
+   */
   onChange: PropTypes.func,
+  /**
+   * An array of items or item groups to be used as options.
+   */
   children: componentPropType(['Item', 'Group']),
+  /**
+   * Whether the select is disabled.
+   */
   inactive: PropTypes.bool,
+  /**
+   * Whether the select is read-only.
+   */
   readOnly: PropTypes.bool,
+  /**
+   * A placeholder to provide instructions (such as "Please select...")
+   * as an unselectable option
+   */
   placeholder: PropTypes.string,
+  /**
+   * Select tokens.
+   */
   tokens: getTokensPropType('Select'),
+  /**
+   * Select variant.
+   */
   variant: variantProp.propType,
+  /**
+   * Dedicated ID for testing.
+   */
   testID: PropTypes.string
 }
 

package/src/SideNav/Item.jsx

@@ -1,4 +1,4 @@
-import React from 'react'
+import React, { forwardRef } from 'react'
 import { Pressable } from 'react-native'
 import PropTypes from 'prop-types'
 
@@ -37,54 +37,61 @@ function selectItemStyles({
 
  This component can only be accessed as a name-spaced component: `SideNav.Item`.
  */
-const Item = ({
-  children,
-  itemId,
-  groupId,
-  onPress,
-  isActive = false,
-  isExpanded = false,
-  tokens,
-  variant,
-  href,
-  accessibilityRole = 'link',
-  testID,
-  ...props
-}) => {
-  const handlePress = () => onPress(itemId, groupId)
+const Item = forwardRef(
+  (
+    {
+      children,
+      itemId,
+      groupId,
+      onPress,
+      isActive = false,
+      isExpanded = false,
+      tokens,
+      variant,
+      href,
+      accessibilityRole = 'link',
+      testID,
+      ...props
+    },
+    ref
+  ) => {
+    const handlePress = () => onPress(itemId, groupId)
 
-  const { hrefAttrs, rest } = hrefAttrsProp.bundle(props)
-  const linkPropSet = linkProps.select({
-    accessibilityRole,
-    href,
-    onPress: handlePress,
-    hrefAttrs,
-    ...rest
-  })
+    const { hrefAttrs, rest } = hrefAttrsProp.bundle(props)
+    const linkPropSet = linkProps.select({
+      accessibilityRole,
+      href,
+      onPress: handlePress,
+      hrefAttrs,
+      ...rest
+    })
 
-  const getTokens = useThemeTokensCallback('SideNavItem', tokens, variant)
-  const getAppearanceState = ({ hovered }) => ({
-    hover: hovered,
-    active: isActive,
-    expanded: isExpanded
-  })
-  const getPressableStyle = (pressableState) =>
-    selectItemStyles(getTokens(getAppearanceState(pressableState)))
+    const getTokens = useThemeTokensCallback('SideNavItem', tokens, variant)
+    const getAppearanceState = ({ hovered }) => ({
+      hover: hovered,
+      active: isActive,
+      expanded: isExpanded
+    })
+    const getPressableStyle = (pressableState) =>
+      selectItemStyles(getTokens(getAppearanceState(pressableState)))
 
-  return (
-    <Pressable
-      style={getPressableStyle}
-      {...linkPropSet}
-      accessibilityState={{ selected: isActive }}
-      testID={testID}
-    >
-      {(pressableState) => {
-        const themeTokens = getTokens(getAppearanceState(pressableState))
-        return <ItemContent tokens={themeTokens}>{children}</ItemContent>
-      }}
-    </Pressable>
-  )
-}
+    return (
+      <Pressable
+        ref={ref}
+        style={getPressableStyle}
+        {...linkPropSet}
+        accessibilityState={{ selected: isActive }}
+        testID={testID}
+      >
+        {(pressableState) => {
+          const themeTokens = getTokens(getAppearanceState(pressableState))
+          return <ItemContent tokens={themeTokens}>{children}</ItemContent>
+        }}
+      </Pressable>
+    )
+  }
+)
+Item.displayName = 'Item'
 
 Item.propTypes = {
   /**

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

@@ -1,4 +1,4 @@
-import React from 'react'
+import React, { forwardRef } from 'react'
 import { Animated, Platform } from 'react-native'
 import propTypes from 'prop-types'
 import StackView from '../StackView'
@@ -27,7 +27,7 @@ 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 nativeAnimation = useSkeletonNativeAnimation()
@@ -74,17 +74,13 @@ const Skeleton = ({ tokens, variant, size, characters, lines, shape = 'line' })
     />
   )
 
-  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/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,