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

package/src/Tags/Tags.jsx

@@ -1,8 +1,10 @@
-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'
+import Icon from '../Icon'
 import { StackWrap, getStackedContent } from '../StackView'
 import { useViewport } from '../ViewportProvider'
 import { useThemeTokens, useThemeTokensCallback } from '../ThemeProvider'
@@ -50,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}>
-                  <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,
@@ -180,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()
     })
   ),
   /**

package/src/TextInput/TextArea.jsx

@@ -1,4 +1,4 @@
-import React, { useState } from 'react'
+import React, { forwardRef, useState } from 'react'
 
 import { Platform } from 'react-native'
 import { getTokensPropType, variantProp } from '../utils'
@@ -32,7 +32,7 @@ import textInputPropTypes from './propTypes'
  * or an indicator that the field is optional.
  * It is a more usable and accessible option than the HTML `placeholder` attribute.
  */
-function TextArea({ tokens, variant = {}, ...remainingProps }) {
+const TextArea = forwardRef(({ tokens, variant = {}, ...remainingProps }, ref) => {
   const themeTokens = useThemeTokens('TextArea', tokens, variant)
   const [inputHeight, setInputHeight] = useState()
 
@@ -62,11 +62,12 @@ function TextArea({ tokens, variant = {}, ...remainingProps }) {
   return (
     <InputSupports {...supportsProps}>
       {({ a11yProps, inputId }) => (
-        <TextInputBase {...inputProps} {...a11yProps} nativeID={inputId} />
+        <TextInputBase ref={ref} {...inputProps} {...a11yProps} nativeID={inputId} />
       )}
     </InputSupports>
   )
-}
+})
+TextArea.displayName = 'TextArea'
 
 TextArea.propTypes = {
   ...inputSupportProps.types,

package/src/TextInput/TextInput.jsx

@@ -1,4 +1,4 @@
-import React from 'react'
+import React, { forwardRef } from 'react'
 
 import { getTokensPropType, variantProp } from '../utils'
 import InputSupports from '../InputSupports'
@@ -24,7 +24,7 @@ import textInputPropTypes from './propTypes'
  * supported props and <a href="https://reactnative.dev/docs/textinput" target="_blank">React Native Web documentation</a> for
  * their implementation on the web.
  */
-function TextInput({ tokens, variant = {}, ...remainingProps }) {
+const TextInput = forwardRef(({ tokens, variant = {}, ...remainingProps }, ref) => {
   const { props: supportsProps, rest } = inputSupportProps.select(remainingProps)
 
   const inputProps = {
@@ -36,11 +36,12 @@ function TextInput({ tokens, variant = {}, ...remainingProps }) {
   return (
     <InputSupports {...supportsProps}>
       {({ a11yProps, inputId }) => (
-        <TextInputBase {...inputProps} {...a11yProps} nativeID={inputId} />
+        <TextInputBase ref={ref} {...inputProps} {...a11yProps} nativeID={inputId} />
       )}
     </InputSupports>
   )
-}
+})
+TextInput.displayName = 'TextInput'
 
 TextInput.propTypes = {
   ...inputSupportProps.types,

package/src/TextInput/TextInputBase.jsx

@@ -1,8 +1,8 @@
-import React, { useState } from 'react'
+import React, { forwardRef, useState } from 'react'
 import { Platform, StyleSheet, TextInput as NativeTextInput, View } from 'react-native'
 
 import PropTypes from 'prop-types'
-import { applyTextStyles, useThemeTokens } from '../ThemeProvider'
+import { applyTextStyles, useThemeTokens, applyOuterBorder } from '../ThemeProvider'
 import { getTokensPropType, useInputValue, variantProp } from '../utils'
 
 const selectInputStyles = (
@@ -76,27 +76,17 @@ const selectInputStyles = (
 
 const selectOuterBorderStyles = ({
   outerBackgroundColor,
-  outerBorderWidth = 0,
+  outerBorderWidth,
   outerBorderColor,
-  outerBorderRadius = 0
-}) => {
-  // Use negative margins so that the outer border doesn't expand the input's bounding box
-  const margin = -1 * outerBorderWidth
-
-  // Account for the border width since we style it as an outline
-  const borderRadius = outerBorderRadius + outerBorderWidth
-
-  return {
-    background: outerBackgroundColor,
-    borderWidth: outerBorderWidth,
-    borderColor: outerBorderColor,
-    borderRadius,
-    marginTop: margin,
-    marginBottom: margin,
-    marginLeft: margin,
-    marginRight: margin
-  }
-}
+  borderRadius
+}) => ({
+  background: outerBackgroundColor,
+  ...applyOuterBorder({
+    outerBorderColor,
+    outerBorderWidth,
+    borderRadius
+  })
+})
 
 const selectIconTokens = ({ iconSize, iconColor }) => ({
   size: iconSize,
@@ -108,90 +98,97 @@ const selectIconContainerStyles = ({ paddingRight, paddingBottom }) => ({
   paddingBottom
 })
 
-function TextInputBase({
-  value,
-  height,
-  initialValue,
-  inactive,
-  readOnly,
-  onChange,
-  onChangeText,
-  onFocus,
-  onBlur,
-  onMouseOver,
-  onMouseOut,
-  tokens,
-  variant = {},
-  ...remainingProps
-}) {
-  const [isFocused, setIsFocused] = useState(false)
-  const handleFocus = (event) => {
-    setIsFocused(true)
-    if (typeof onFocus === 'function') onFocus(event)
-  }
-  const handleBlur = (event) => {
-    setIsFocused(false)
-    if (typeof onBlur === 'function') onBlur(event)
-  }
+const TextInputBase = forwardRef(
+  (
+    {
+      value,
+      height,
+      initialValue,
+      inactive,
+      readOnly,
+      onChange,
+      onChangeText,
+      onFocus,
+      onBlur,
+      onMouseOver,
+      onMouseOut,
+      tokens,
+      variant = {},
+      ...remainingProps
+    },
+    ref
+  ) => {
+    const [isFocused, setIsFocused] = useState(false)
+    const handleFocus = (event) => {
+      setIsFocused(true)
+      if (typeof onFocus === 'function') onFocus(event)
+    }
+    const handleBlur = (event) => {
+      setIsFocused(false)
+      if (typeof onBlur === 'function') onBlur(event)
+    }
 
-  const [isHovered, setIsHovered] = useState(false)
-  const handleMouseOver = (event) => {
-    setIsHovered(true)
-    if (typeof onMouseOver === 'function') onMouseOver(event)
-  }
-  const handleMouseOut = (event) => {
-    setIsHovered(false)
-    if (typeof onMouseOut === 'function') onMouseOut(event)
-  }
+    const [isHovered, setIsHovered] = useState(false)
+    const handleMouseOver = (event) => {
+      setIsHovered(true)
+      if (typeof onMouseOver === 'function') onMouseOver(event)
+    }
+    const handleMouseOut = (event) => {
+      setIsHovered(false)
+      if (typeof onMouseOut === 'function') onMouseOut(event)
+    }
 
-  const { currentValue, setValue, isControlled } = useInputValue({
-    value,
-    initialValue,
-    onChange,
-    readOnly
-  })
+    const { currentValue, setValue, isControlled } = useInputValue({
+      value,
+      initialValue,
+      onChange,
+      readOnly
+    })
+
+    const handleChangeText = (event) => {
+      const text = event.nativeEvent?.text || event.target?.value
+      setValue(text, event)
+      if (typeof onChangeText === 'function') onChangeText(text, event)
+    }
 
-  const handleChangeText = (text) => {
-    setValue(text)
-    if (typeof onChangeText === 'function') onChangeText(text)
-  }
+    const states = { focus: isFocused, hover: isHovered, inactive }
 
-  const states = { focus: isFocused, hover: isHovered, inactive }
+    const themeTokens = useThemeTokens('TextInput', tokens, variant, states)
 
-  const themeTokens = useThemeTokens('TextInput', tokens, variant, states)
+    const { icon: IconComponent } = themeTokens
 
-  const { icon: IconComponent } = themeTokens
+    const inputProps = {
+      ...remainingProps,
+      editable: !inactive,
+      onFocus: handleFocus,
+      onBlur: handleBlur,
+      onMouseOver: handleMouseOver,
+      onMouseOut: handleMouseOut,
+      onChange: handleChangeText,
+      defaultValue: initialValue,
+      // currentValue is being updated even if the input is not controlled, passing it down to the
+      // Input could lead to changing its state from uncontrolled to controlled
+      value: isControlled ? currentValue : undefined
+    }
 
-  const inputProps = {
-    ...remainingProps,
-    editable: !inactive,
-    onFocus: handleFocus,
-    onBlur: handleBlur,
-    onMouseOver: handleMouseOver,
-    onMouseOut: handleMouseOut,
-    onChangeText: handleChangeText,
-    defaultValue: initialValue,
-    // currentValue is being updated even if the input is not controlled, passing it down to the
-    // Input could lead to changing its state from uncontrolled to controlled
-    value: isControlled ? currentValue : undefined
+    const nativeInputStyle = selectInputStyles({ ...themeTokens, height }, inactive)
+
+    return (
+      <View style={selectOuterBorderStyles(themeTokens)}>
+        <NativeTextInput ref={ref} style={nativeInputStyle} {...inputProps} />
+        {IconComponent && (
+          <View
+            pointerEvents="none" // avoid hijacking input press events
+            style={[staticStyles.iconContainer, selectIconContainerStyles(themeTokens)]}
+          >
+            <IconComponent {...selectIconTokens(themeTokens)} />
+          </View>
+        )}
+      </View>
+    )
   }
-
-  const nativeInputStyle = selectInputStyles({ ...themeTokens, height }, inactive)
-
-  return (
-    <View style={selectOuterBorderStyles(themeTokens)}>
-      <NativeTextInput style={nativeInputStyle} {...inputProps} />
-      {IconComponent && (
-        <View
-          pointerEvents="none" // avoid hijacking input press events
-          style={[staticStyles.iconContainer, selectIconContainerStyles(themeTokens)]}
-        >
-          <IconComponent tokens={selectIconTokens(themeTokens)} />
-        </View>
-      )}
-    </View>
-  )
-}
+)
+TextInputBase.displayName = 'TextInputBase'
 
 TextInputBase.propTypes = {
   value: PropTypes.string,

package/src/ThemeProvider/ThemeProvider.jsx

@@ -1,18 +1,20 @@
 import React, { createContext, useState } from 'react'
 import PropTypes from 'prop-types'
+import { validateThemeTokensVersion } from './utils'
 
 export const uninitialisedError = new Error('Theme context used outside of ThemeProvider')
 
 export const ThemeContext = createContext(uninitialisedError)
 export const ThemeSetterContext = createContext(uninitialisedError)
 
-// TODO: develop this as theme metadata is added
-// https://github.com/telus/universal-design-system/issues/92
-export const themeType = PropTypes.object
-
 const ThemeProvider = ({ children, defaultTheme }) => {
   const [theme, setTheme] = useState(defaultTheme)
 
+  // Validate the theme tokens version on every render.
+  // This will intentionally break the application when attempting to use an invalid theme.
+  // This will surface an incompatibility quickly rather than allowing the potential for strange bugs due to missing or incompatible tokens.
+  validateThemeTokensVersion(theme)
+
   return (
     <ThemeSetterContext.Provider value={setTheme}>
       <ThemeContext.Provider value={theme}>{children}</ThemeContext.Provider>
@@ -21,10 +23,12 @@ const ThemeProvider = ({ children, defaultTheme }) => {
 }
 
 ThemeProvider.propTypes = {
-  // TODO: implement a custom propType that validates schema version
-  // https://github.com/telus/universal-design-system/issues/92
   children: PropTypes.node.isRequired,
-  defaultTheme: themeType.isRequired
+  defaultTheme: PropTypes.shape({
+    metadata: PropTypes.shape({
+      themeTokensVersion: PropTypes.string.isRequired
+    }).isRequired
+  }).isRequired
 }
 
 export default ThemeProvider

package/src/ThemeProvider/useSetTheme.js

@@ -4,6 +4,10 @@ import { ThemeSetterContext } from './ThemeProvider'
 const useSetTheme = () => {
   // Replace current theme with provided object
   const setTheme = useContext(ThemeSetterContext)
+  // Fail fast if dev uses useSetTheme outside of ThemeProvider
+  if (setTheme instanceof Error) {
+    throw setTheme
+  }
 
   // Merge provided object into current theme
   const editTheme = useCallback(

package/src/ThemeProvider/useThemeTokens.js

@@ -1,6 +1,6 @@
 import { useCallback } from 'react'
 import useTheme from './useTheme'
-import { getComponentTheme, getThemeTokens, resolveTokens, mergeAppearances } from './utils'
+import { getComponentTheme, getThemeTokens, resolveThemeTokens, mergeAppearances } from './utils'
 /**
  * @typedef {import('../utils/propTypes.js').AppearanceSet} AppearanceSet
  * @typedef {import('../utils/propTypes.js').TokensProp} TokensProp
@@ -98,7 +98,7 @@ export const useThemeTokensCallback = (componentName, tokens = {}, variants = {}
   const getThemeTokensCallback = useCallback(
     (states, tokenOverrides) => {
       const appearances = mergeAppearances(variants, states)
-      const resolvedTokens = resolveTokens(tokens, tokenOverrides, appearances)
+      const resolvedTokens = resolveThemeTokens(tokens, appearances, tokenOverrides)
       return getThemeTokens(componentTheme, resolvedTokens, appearances)
     },
     [componentTheme, tokens, variants]

package/src/ThemeProvider/utils/styles.js

@@ -9,6 +9,7 @@ import { fontBasePixels } from '@telus-uds/system-constants'
 // Make design tokens fit React Native's text styles' specific requirements and quirks
 export function applyTextStyles({
   fontSize,
+  fontScaleCap,
   lineHeight,
   letterSpacing,
   fontWeight = '400',
@@ -27,7 +28,7 @@ export function applyTextStyles({
     styles.lineHeight = lineHeight * (fontSize || fontBasePixels)
   }
 
-  if (typeof letterSpacing === 'number') {
+  if (typeof letterSpacing === 'number' && letterSpacing) {
     // Same as for line heights - React Native expects absolute letter spacing value
     styles.letterSpacing = letterSpacing * (fontSize || fontBasePixels)
   }
@@ -133,7 +134,19 @@ export function verticalAlignRow(verticalAlign, reverse = false) {
   }
 }
 
-// React Native Views behave like flex blocks. There's no CSS 'display' and they can't inline themselves
-export function applyLayoutStyles() {
-  // TODO: map design tokens to styles that implement inline, stretch, center, etc
-}
+/**
+ * Use on an outer container to create an outer border with an optional gap around it
+ * that matches the border radius of any inner border.
+ */
+export const applyOuterBorder = ({
+  outerBorderColor,
+  outerBorderWidth = 0,
+  outerBorderGap = 0,
+  borderRadius = 0
+}) => ({
+  margin: 0 - outerBorderWidth - outerBorderGap,
+  padding: outerBorderGap,
+  borderRadius: borderRadius + outerBorderGap + outerBorderWidth,
+  borderWidth: outerBorderWidth,
+  borderColor: outerBorderColor
+})