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

package/src/ThemeProvider/utils/theme-tokens.js

@@ -1,3 +1,7 @@
+import PropTypes from 'prop-types'
+import semVerSatisfies from 'semver/functions/satisfies'
+import pkg from '../../../package.json'
+
 /**
  * @typedef {import('../../utils/propTypes.js').AppearanceSet} AppearanceSet
  * @typedef {import('../../utils/propTypes.js').TokensProp} TokensProp
@@ -37,15 +41,22 @@ export const doesThemeRuleApply = (rule, appearances) =>
   Object.entries(rule.if).every((condition) => doesThemeConditionApply(condition, appearances))
 
 /**
- * Turns a tokens prop and an optional tokens override prop (either or both of which may be a tokens getter function)
- * into one tokens set object where overrides are applied over the resolved default tokens.
+ * Turns a tokens prop (which may be either a tokens object or a tokens getter function)
+ * into one resolved tokens object, based on current appearances state.
+ *
+ * This is used inside `useThemeTokens` and `useThemeTokensCallback` for handling the `tokens`
+ * props of themed components. It may also be used directly in cases where a non-themed component
+ * needs to resolve a tokens prop that may be a tokens getter function or a resolved tokens object.
+ *
+ * A second tokens prop of tokens overrides may optionally be passed; it will be resolved to an object
+ * based on provided appearance state and then shallow-merged over the first set of tokens.
  *
  * @param {TokensProp} defaultTokens - a set of tokens or tokens getter function which may be overridden
- * @param {TokensProp} [tokenOverrides] - optional set of tokens or tokens getter function to override the default
  * @param {AppearanceSet} [appearances] - optional appearance set to pass to tokens getter functions
+ * @param {TokensProp} [tokenOverrides] - optional set of tokens or tokens getter function to override the default
  * @returns {TokensSet} - object containing resolved tokens with overrides applied
  */
-export const resolveTokens = (defaultTokens, tokenOverrides, appearances = {}) => {
+export const resolveThemeTokens = (defaultTokens, appearances = {}, tokenOverrides) => {
   const resolve = (tokens) => (typeof tokens === 'function' ? tokens(appearances) : tokens)
   if (!tokenOverrides) return resolve(defaultTokens)
 
@@ -56,6 +67,27 @@ export const resolveTokens = (defaultTokens, tokenOverrides, appearances = {}) =
   )
 }
 
+/**
+ * Gives a prop types error if a set of resolved tokens doesn't match a provided prop
+ * types validator.
+ *
+ * In production, this is a no-op (PropTypes.checkPropTypes is automatically replaced
+ * with a no-op function).
+ *
+ * @param {TokensSet} themeTokens - object containing resolved theme tokens
+ * @param {function} validator - PropTypes validator function
+ * @param {string} componentName - identifier to display in PropType error messages
+ */
+export const validateThemeTokens = (themeTokens, validator, componentName) => {
+  PropTypes.checkPropTypes(
+    { tokens: validator },
+    { tokens: themeTokens },
+    'resolved token',
+    componentName
+  )
+  return themeTokens
+}
+
 /**
  * Merges variants over states. Must be merged in that order to allow static showcases of a state,
  * e.g. `<Button variant={{ pressed: true }} />` where button's pressed state is `false` by default.
@@ -68,6 +100,17 @@ export const resolveTokens = (defaultTokens, tokenOverrides, appearances = {}) =
 export const mergeAppearances = (variants = {}, states) =>
   states ? { ...states, ...variants } : variants
 
+/**
+ * Get a set of theme tokens by applying a theme's component rules based on a component's variants and state.
+ *
+ * This is used internally in `useThemeTokens` and `useThemeTokensCallback` and should not normally be called directly.
+ *
+ * @param {object} componentTheme - object containing a theme's `tokens` and `rules` for a component
+ * @param {object|function} [tokensProp] - UDS tokens prop containing theming overrides
+ * @param {object} [variants] - UDS variant prop containing the variant options for this component instance
+ * @param {object} [states] - object containing current state options for this component instance
+ * @returns {object} Set of resolved theme tokens
+ */
 export const getThemeTokens = (
   { rules = [], tokens: defaultThemeTokens = {} },
   tokensProp,
@@ -88,7 +131,33 @@ export const getThemeTokens = (
         : mergedTokens,
     defaultThemeTokens
   )
-  return resolveTokens(themeTokens, tokensProp, appearances)
+  return resolveThemeTokens(themeTokens, appearances, tokensProp)
 }
 
 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'
 
@@ -21,8 +21,7 @@ const selectButtonTokens = (tokens) =>
   })
 
 // Map and rename icon-specific tokens to name used within Icon
-const selectIconTokens = ({ iconSize, iconColor, iconOpacity }) => ({
-  opacity: iconOpacity,
+const selectIconTokens = ({ iconSize, iconColor }) => ({
   size: iconSize,
   color: iconColor
 })
@@ -55,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 tokens={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,

package/src/Tooltip/Tooltip.jsx

@@ -1,4 +1,4 @@
-import React, { useEffect, useRef, useState } from 'react'
+import React, { forwardRef, useEffect, useRef, useState } from 'react'
 import { Dimensions, Platform, Pressable, StyleSheet, Text, View } from 'react-native'
 
 import PropTypes from 'prop-types'
@@ -81,7 +81,7 @@ const selectArrowStyles = (
 
 const selectTextStyles = (tokens) => applyTextStyles(selectTokens('Typography', tokens))
 const defaultControl = (pressableState, variant) => (
-  <TooltipButton variant={{ ...pressableState, ...variant }} />
+  <TooltipButton pressableState={pressableState} variant={variant} />
 )
 
 /**
@@ -99,157 +99,161 @@ const defaultControl = (pressableState, variant) => (
  * - You may use one when the information is useful only to a small percentage of users (ie. tech savvy people wouldn't need this info).
  * - Tooltips may also be useful when vertical space is an issue.
  */
-const Tooltip = ({ children, content, position = 'auto', copy = 'en', tokens, variant }) => {
-  const [isOpen, setIsOpen] = useState(false)
+const Tooltip = forwardRef(
+  ({ children, content, position = 'auto', copy = 'en', tokens, variant }, ref) => {
+    const [isOpen, setIsOpen] = useState(false)
 
-  const controlRef = useRef()
-  const [controlLayout, setControlLayout] = useState(null)
-  const [tooltipDimensions, setTooltipDimensions] = useState(null)
-  const [windowDimensions, setWindowDimensions] = useState(Dimensions.get('window'))
-  const [tooltipPosition, setTooltipPosition] = useState(null)
+    const controlRef = useRef()
+    const [controlLayout, setControlLayout] = useState(null)
+    const [tooltipDimensions, setTooltipDimensions] = useState(null)
+    const [windowDimensions, setWindowDimensions] = useState(Dimensions.get('window'))
+    const [tooltipPosition, setTooltipPosition] = useState(null)
 
-  const getCopy = useCopy({ dictionary, copy })
-  const themeTokens = useThemeTokens('Tooltip', tokens, variant)
+    const getCopy = useCopy({ dictionary, copy })
+    const themeTokens = useThemeTokens('Tooltip', tokens, variant)
 
-  const { arrowWidth, arrowOffset } = themeTokens
+    const { arrowWidth, arrowOffset } = themeTokens
 
-  useEffect(() => {
-    const subscription = Dimensions.addEventListener('change', ({ window }) => {
-      setWindowDimensions(window)
-    })
+    useEffect(() => {
+      const subscription = Dimensions.addEventListener('change', ({ window }) => {
+        setWindowDimensions(window)
+      })
 
-    return () => subscription?.remove()
-  })
+      return () => subscription?.remove()
+    })
 
-  const toggleIsOpen = () => setIsOpen(!isOpen)
-  const close = () => setIsOpen(false)
+    const toggleIsOpen = () => setIsOpen(!isOpen)
+    const close = () => setIsOpen(false)
 
-  const getPressableState = ({ pressed, hovered, focused }) => ({
-    pressed,
-    hover: hovered,
-    focus: focused
-  })
+    const getPressableState = ({ pressed, hovered, focused }) => ({
+      pressed,
+      hover: hovered,
+      focus: focused
+    })
 
-  const onTooltipLayout = ({
-    nativeEvent: {
-      layout: { width, height }
-    }
-  }) => {
-    if (
-      tooltipDimensions === null ||
-      tooltipDimensions.width !== width ||
-      tooltipDimensions.height !== height
-    ) {
-      setTooltipDimensions({
-        width: Platform.select({
-          web: width + 0.3, // avoids often unnecessary line breaks due to subpixel rendering of fonts
-          native: width
-        }),
-        height
-      })
+    const onTooltipLayout = ({
+      nativeEvent: {
+        layout: { width, height }
+      }
+    }) => {
+      if (
+        tooltipDimensions === null ||
+        tooltipDimensions.width !== width ||
+        tooltipDimensions.height !== height
+      ) {
+        setTooltipDimensions({
+          width: Platform.select({
+            web: width + 0.3, // avoids often unnecessary line breaks due to subpixel rendering of fonts
+            native: width
+          }),
+          height
+        })
+      }
     }
-  }
 
-  useEffect(() => {
-    if (isOpen) {
-      controlRef.current.measureInWindow((x, y, width, height) => {
-        setControlLayout({ x, y, width, height })
-      })
-    } else {
-      setControlLayout(null)
-      setTooltipDimensions(null)
-      setTooltipPosition(null)
-    }
-  }, [isOpen])
+    useEffect(() => {
+      if (isOpen) {
+        controlRef.current.measureInWindow((x, y, width, height) => {
+          setControlLayout({ x, y, width, height })
+        })
+      } else {
+        setControlLayout(null)
+        setTooltipDimensions(null)
+        setTooltipPosition(null)
+      }
+    }, [isOpen])
 
-  useEffect(() => {
-    setIsOpen(false)
-  }, [windowDimensions])
+    useEffect(() => {
+      setIsOpen(false)
+    }, [windowDimensions])
 
-  useEffect(() => {
-    if (
-      (tooltipPosition !== null && !tooltipPosition?.isNormalized) ||
-      !isOpen ||
-      controlLayout === null ||
-      tooltipDimensions == null
-    ) {
-      return
-    }
+    useEffect(() => {
+      if (
+        (tooltipPosition !== null && !tooltipPosition?.isNormalized) ||
+        !isOpen ||
+        controlLayout === null ||
+        tooltipDimensions == null
+      ) {
+        return
+      }
 
-    const updatedPosition = getTooltipPosition(position, {
-      controlLayout,
+      const updatedPosition = getTooltipPosition(position, {
+        controlLayout,
+        tooltipDimensions,
+        windowDimensions,
+        arrowWidth,
+        arrowOffset
+      })
+
+      // avoid ending up in an infinite normalization loop
+      if (tooltipPosition?.isNormalized && updatedPosition.isNormalized) {
+        return
+      }
+
+      setTooltipPosition(updatedPosition)
+    }, [
+      isOpen,
+      position,
       tooltipDimensions,
+      controlLayout,
       windowDimensions,
       arrowWidth,
-      arrowOffset
-    })
+      arrowOffset,
+      tooltipPosition
+    ])
 
-    // avoid ending up in an infinite normalization loop
-    if (tooltipPosition?.isNormalized && updatedPosition.isNormalized) {
-      return
-    }
+    const control = children !== undefined ? children : defaultControl
+    const pressableStyles =
+      control === defaultControl ? Platform.select({ web: { outline: 'none' } }) : undefined
+    const pressableHitSlop =
+      control === defaultControl ? { top: 10, bottom: 10, left: 10, right: 10 } : undefined
 
-    setTooltipPosition(updatedPosition)
-  }, [
-    isOpen,
-    position,
-    tooltipDimensions,
-    controlLayout,
-    windowDimensions,
-    arrowWidth,
-    arrowOffset,
-    tooltipPosition
-  ])
-
-  const control = children !== undefined ? children : defaultControl
-  const pressableStyles =
-    control === defaultControl ? Platform.select({ web: { outline: 'none' } }) : undefined
-  const pressableHitSlop =
-    control === defaultControl ? { top: 10, bottom: 10, left: 10, right: 10 } : undefined
-
-  return (
-    <View style={staticStyles.container}>
-      <Pressable
-        onPress={toggleIsOpen}
-        ref={controlRef}
-        onBlur={close}
-        style={pressableStyles}
-        hitSlop={pressableHitSlop}
-        accessibilityLabel={getCopy('a11yText')}
-        accessibilityRole="button"
-      >
-        {typeof control === 'function'
-          ? (pressableState) => control(getPressableState(pressableState), variant)
-          : control}
-      </Pressable>
-      {isOpen && (
-        <Backdrop onPress={close}>
-          <View
-            style={[
-              staticStyles.tooltip,
-              selectTooltipShadowStyles(themeTokens), // applied separately so that it doesn't cover the arrow
-              tooltipPosition && selectTooltipPositionStyles(tooltipPosition),
-              (tooltipPosition === null || tooltipPosition?.isNormalized) &&
-                staticStyles.tooltipHidden // visually hide the tooltip until we have a final measurement
-            ]}
-            onLayout={onTooltipLayout}
-            accessibilityRole="alert"
-          >
+    return (
+      <View style={staticStyles.container}>
+        <Pressable
+          onPress={toggleIsOpen}
+          ref={controlRef}
+          onBlur={close}
+          style={pressableStyles}
+          hitSlop={pressableHitSlop}
+          accessibilityLabel={getCopy('a11yText')}
+          accessibilityRole="button"
+        >
+          {typeof control === 'function'
+            ? (pressableState) => control(getPressableState(pressableState), variant)
+            : control}
+        </Pressable>
+        {isOpen && (
+          <Backdrop onPress={close}>
             <View
+              ref={ref}
               style={[
-                staticStyles.arrow,
-                tooltipPosition && selectArrowStyles(themeTokens, tooltipPosition)
+                staticStyles.tooltip,
+                selectTooltipShadowStyles(themeTokens), // applied separately so that it doesn't cover the arrow
+                tooltipPosition && selectTooltipPositionStyles(tooltipPosition),
+                (tooltipPosition === null || tooltipPosition?.isNormalized) &&
+                  staticStyles.tooltipHidden // visually hide the tooltip until we have a final measurement
               ]}
-            />
-            <View style={selectTooltipStyles(themeTokens)}>
-              <Text style={selectTextStyles(themeTokens)}>{content}</Text>
+              onLayout={onTooltipLayout}
+              accessibilityRole="alert"
+            >
+              <View
+                style={[
+                  staticStyles.arrow,
+                  tooltipPosition && selectArrowStyles(themeTokens, tooltipPosition)
+                ]}
+              />
+              <View style={selectTooltipStyles(themeTokens)}>
+                <Text style={selectTextStyles(themeTokens)}>{content}</Text>
+              </View>
             </View>
-          </View>
-        </Backdrop>
-      )}
-    </View>
-  )
-}
+          </Backdrop>
+        )}
+      </View>
+    )
+  }
+)
+Tooltip.displayName = 'Tooltip'
 
 Tooltip.propTypes = {
   /**

package/src/TooltipButton/TooltipButton.jsx

@@ -1,51 +1,47 @@
 import React from 'react'
 import { View } from 'react-native'
 
-import { useThemeTokens } from '../ThemeProvider'
+import PropTypes from 'prop-types'
+import { useThemeTokens, applyOuterBorder } from '../ThemeProvider'
 import { getTokensPropType, variantProp } from '../utils'
+import Icon from '../Icon'
 
-const selectOuterContainerStyles = ({
-  outerBorderColor,
-  outerBorderWidth = 0,
-  outerBorderGap = 0,
-  outerBorderRadius
-}) => {
-  const outerBorderOffset = -1 * (outerBorderWidth + outerBorderGap)
-
-  return {
-    marginTop: outerBorderOffset,
-    marginLeft: outerBorderOffset,
-    marginRight: outerBorderOffset,
-    marginBottom: outerBorderOffset,
-    borderColor: outerBorderColor,
-    borderWidth: outerBorderWidth,
-    padding: outerBorderGap,
-    borderRadius: outerBorderRadius
-  }
-}
 const selectInnerContainerStyles = ({ borderRadius, width }) => ({ borderRadius, width })
 
-const selectIconTokens = ({ iconSize, iconColor, iconScale = 1 }) => ({
+const selectIconTokens = ({ iconSize, iconColor /* iconScale = 1 */ }) => ({
   size: iconSize,
-  color: iconColor,
-  scale: iconScale
+  color: iconColor
+  // scale: iconScale TODO re-enable with icon component
 })
 
-const TooltipButton = ({ tokens, variant }) => {
-  const themeTokens = useThemeTokens('TooltipButton', tokens, variant)
+/**
+ * `TooltipButton` is a helper component used as a default control for the `Tooltip` component.
+ * In fact though, it isn't actually a pressable - it's meant to be used as pressable's content.
+ * Due to this any interaction states (e.g. pressed, hover, etc.) has to be passed down to it as a prop.
+ */
+const TooltipButton = ({ pressableState, tokens, variant }) => {
+  const themeTokens = useThemeTokens('TooltipButton', tokens, variant, pressableState)
 
   const { icon: IconComponent } = themeTokens
 
   return (
-    <View style={selectOuterContainerStyles(themeTokens)}>
+    <View style={applyOuterBorder(themeTokens)}>
       <View style={selectInnerContainerStyles(themeTokens)}>
-        {IconComponent && <IconComponent tokens={selectIconTokens(themeTokens)} />}
+        {IconComponent && <Icon icon={IconComponent} tokens={selectIconTokens(themeTokens)} />}
       </View>
     </View>
   )
 }
 
 TooltipButton.propTypes = {
+  /**
+   * Used as appearances when resolving theme tokens.
+   */
+  pressableState: PropTypes.shape({
+    pressed: PropTypes.bool,
+    hover: PropTypes.bool,
+    focus: PropTypes.bool
+  }),
   tokens: getTokensPropType('TooltipButton'),
   variant: variantProp.propType
 }