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

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,4 +1,4 @@
-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'
@@ -98,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 {...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/utils/theme-tokens.js

@@ -1,4 +1,6 @@
 import PropTypes from 'prop-types'
+import semVerSatisfies from 'semver/functions/satisfies'
+import pkg from '../../../package.json'
 
 /**
  * @typedef {import('../../utils/propTypes.js').AppearanceSet} AppearanceSet
@@ -133,3 +135,29 @@ export const getThemeTokens = (
 }
 
 export const toArray = (strOrArr) => (Array.isArray(strOrArr) ? strOrArr : [strOrArr])
+
+/**
+ * Throws an error if the theme was built with an incompatible version of @telus-uds/system-theme-tokens
+ *
+ * This is used internally by the ThemeProvider to force a fast failure when an incompatible version is detected.
+ *
+ * Version compatibility is calculated with semver.satisfies.
+ * Refer to https://github.com/npm/node-semver and https://semver.npmjs.com/ for details about how
+ * semver compatibility.
+ *
+ * @param {object} theme - UDS theme built for react-native
+ */
+export const validateThemeTokensVersion = (theme) => {
+  const expectedThemeTokensVersion = pkg.dependencies['@telus-uds/system-theme-tokens']
+  const actualThemeTokensVersion = theme?.metadata?.themeTokensVersion
+
+  if (!semVerSatisfies(actualThemeTokensVersion, expectedThemeTokensVersion)) {
+    throw new Error(
+      `Invalid UDS token schema version detected.
+
+The UDS base components ${pkg.name} v${pkg.version} are only compatible with UDS themes that are built with @telus-uds/system-theme-tokens version that is semver compatible with ${expectedThemeTokensVersion}. The current theme was built with @telus-uds/system-theme-tokens v${actualThemeTokensVersion}.
+
+If you see this error than most likely you have attempted to install ${pkg.name} and a UDS theme manually because you are building a multi-brand application. If you are building a single brand application, consider installing the brand specific design system package such as @telus-uds/ds-allium. For more information, see https://github.com/telus/universal-design-system/blob/main/packages/docs-uds/docs/multi-brand-usage.md`
+    )
+  }
+}

package/src/ToggleSwitch/ToggleSwitch.jsx

@@ -1,4 +1,4 @@
-import React from 'react'
+import React, { forwardRef } from 'react'
 import PropTypes from 'prop-types'
 import { Platform, View, StyleSheet } from 'react-native'
 
@@ -54,62 +54,61 @@ const selectSwitchStyles = ({
   })
 })
 
-const ToggleSwitch = ({
-  value,
-  initialValue,
-  onChange,
-  inactive,
-  tokens,
-  variant,
-  accessibilityRole = 'switch'
-}) => {
-  const getTokens = useThemeTokensCallback('ToggleSwitch', tokens, variant)
+const ToggleSwitch = forwardRef(
+  (
+    { value, initialValue, onChange, inactive, tokens, variant, accessibilityRole = 'switch' },
+    ref
+  ) => {
+    const getTokens = useThemeTokensCallback('ToggleSwitch', tokens, variant)
 
-  const { currentValue, setValue } = useInputValue({
-    value,
-    initialValue,
-    onChange
-  })
+    const { currentValue, setValue } = useInputValue({
+      value,
+      initialValue,
+      onChange
+    })
 
-  const handlePress = () => setValue(!currentValue)
+    const handlePress = (event) => setValue(!currentValue, event)
 
-  const getButtonTokens = (buttonState) => selectButtonTokens(getTokens(buttonState))
+    const getButtonTokens = (buttonState) => selectButtonTokens(getTokens(buttonState))
 
-  return (
-    <ButtonBase
-      selected={currentValue}
-      inactive={inactive}
-      tokens={getButtonTokens}
-      accessibilityRole={accessibilityRole}
-      accessibilityState={{ checked: currentValue }}
-      onPress={handlePress}
-    >
-      {(buttonState) => {
-        const themeTokens = getTokens(buttonState)
-        const IconComponent = themeTokens.icon
-        const switchStyles = selectSwitchStyles(themeTokens)
-        const trackStyles = selectTrackStyles(themeTokens)
-        const iconTokens = selectIconTokens(themeTokens)
+    return (
+      <ButtonBase
+        ref={ref}
+        selected={currentValue}
+        inactive={inactive}
+        tokens={getButtonTokens}
+        accessibilityRole={accessibilityRole}
+        accessibilityState={{ checked: currentValue }}
+        onPress={handlePress}
+      >
+        {(buttonState) => {
+          const themeTokens = getTokens(buttonState)
+          const IconComponent = themeTokens.icon
+          const switchStyles = selectSwitchStyles(themeTokens)
+          const trackStyles = selectTrackStyles(themeTokens)
+          const iconTokens = selectIconTokens(themeTokens)
 
-        // If drag-slide support is needed, use a PanResponder and apply these to an Animated value.
-        // Use translate transforms for smoothest non-thread-blocking animations and to allow drag.
-        const slideStart = 0
-        const slideEnd =
-          themeTokens.width - themeTokens.switchSize - themeTokens.trackBorderWidth * 2
-        const switchOffset = buttonState.selected ? slideEnd : slideStart
-        const switchPositionStyle = { transform: [{ translateX: switchOffset }] }
+          // If drag-slide support is needed, use a PanResponder and apply these to an Animated value.
+          // Use translate transforms for smoothest non-thread-blocking animations and to allow drag.
+          const slideStart = 0
+          const slideEnd =
+            themeTokens.width - themeTokens.switchSize - themeTokens.trackBorderWidth * 2
+          const switchOffset = buttonState.selected ? slideEnd : slideStart
+          const switchPositionStyle = { transform: [{ translateX: switchOffset }] }
 
-        return (
-          <View style={[staticStyles.track, trackStyles]}>
-            <View style={[staticStyles.switch, switchStyles, switchPositionStyle]}>
-              {IconComponent && <IconComponent {...iconTokens} />}
+          return (
+            <View style={[staticStyles.track, trackStyles]}>
+              <View style={[staticStyles.switch, switchStyles, switchPositionStyle]}>
+                {IconComponent && <IconComponent {...iconTokens} />}
+              </View>
             </View>
-          </View>
-        )
-      }}
-    </ButtonBase>
-  )
-}
+          )
+        }}
+      </ButtonBase>
+    )
+  }
+)
+ToggleSwitch.displayName = 'ToggleSwitch'
 
 ToggleSwitch.propTypes = {
   ...a11yProps.propTypes,