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

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
@@ -11,6 +11,22 @@ import { getComponentTheme, getThemeTokens, resolveTokens, mergeAppearances } fr
  * Returns a complete set of theme tokens for a component based on which of the
  * component's theme rules apply to the current set of theme appearances.
  *
+ * When applying theme tokens as styles to a component, don't spread the theme tokens
+ * object, explicitly select each property. This way, if new theme tokens are added to the
+ * component's theme in a minor or patch release of the theme package, the appearance
+ * of the component in sites and apps will only change when the component itself is updated.
+ *
+ * @example
+ * const seletContainerTokens = ({ color, width, height }) => ({
+ *   backgroundColor: color, width, height
+ * })
+ * const MyComponent = ({ tokens, variant, children }) => {
+ *   const viewport = useViewport()
+ *   const themeTokens = useThemeTokens('MyComponent', tokens, variant, { viewport })
+ *   const style = seletContainerTokens(themeTokens)
+ *   return <View style={style}>{children}</View>
+ * }
+ *
  * @param {string} componentName - the name as defined in the theme schema of the component whose theme is to be used
  * @param {TokensProp} [tokens] - every themed component should accept an optional `tokens` prop allowing theme tokens to be overridden
  * @param {AppearanceSet} [variants] - every themed component should accept an optional `variants` prop specifying theme variants
@@ -26,13 +42,48 @@ export const useThemeTokens = (componentName, tokens = {}, variants = {}, states
 
 /**
  * Returns a memoised tokens getter function that gets tokens similar to calling useThemeTokens.
- * Scenarios where useThemeTokensCallback should be used instead of useThemeTokens include:
+ * Scenarios where `useThemeTokensCallback` should be used instead of `useThemeTokens` include:
  *
- * - Where tokens to be obtained from state accessible only in scopes like callbacks and render functions,
- *   where calling useThemeTokens directly would be disallowed by React's hook rules.
+ * - Where tokens are to be obtained from state that is accessible only in scopes like callbacks
+ *   and render functions, where calling useThemeTokens directly would be disallowed by React's hook rules.
  * - Passing a tokens getter down via a child component's `tokens` prop, applying rules using the
  *   child component's current state. Consider wrapping the returned tokens in `selectTokens()`.
  *
+ * The function returned by `useThemeTokens` may be called with an object of state appearances to get an object
+ * of tokens, or may be passed as a `tokens` prop to other themed components or `useThemeTokens`/`useThemeTokensCallback`
+ * hooks.
+ *
+ * @example
+ * // Resolving tokens inside Pressable's style function, based on Pressable state
+ * const PressMe = ({ tokens, variant, children }) => {
+ *   const getTokens = useThemeTokensCallback('PressMe', tokens, variant)
+ *   const getPressableStyle = ({ pressed }) => {
+ *     const { color, width, height } = getTokens({ pressed })
+ *     return { backgroundColor: color, width, height }
+ *   }
+ *   return <Pressable style={getPressableStyle}>{children}</Pressable>
+ * }
+ *
+ * @example
+ * // Setting the theme in a parent and resolving it in a child based on child's state
+ * const MenuButton = ({ tokens, variant, ...buttonProps }) => {
+ *   // Define what theme, variant etc we want in this component...
+ *   const getTokens = useThemeTokensCallback('Button', tokens, variant)
+ *   // ...resolve them in another component based on its state (e.g. press, hover...)
+ *   return <ButtonBase tokens={getTokens} accessibilityRole="menuitem" {...buttonProps} />
+ * }
+ *
+ * @example
+ * // Chaining multiple themes together, sharing the same variants and state
+ * const GlowingLink = ({ tokens, variant, children }) => {
+ *   // applies a small theme for a glowing effect, using same variants and states as "link"
+ *   const getGlowTokens = useThemeCallback('GlowingLink', tokens, variant)
+ *   // applies link state to get "Link" theme tokens and merge "GlowingLink" tokens on top
+ *   const getTokens = useThemeCallback('Link', getGlowTokens, variant)
+ *   // renders a link with both themes applied, both based on current link state
+ *   return <LinkBase tokens={getTokens}>{children}</LinkBase>
+ * }
+ *
  * @param {string} componentName - the name as defined in the theme schema of the component whose theme is to be used
  * @param {TokensProp} [tokens] - every themed component should accept a `tokens` prop allowing theme tokens to be overridden
  * @param {AppearanceSet} [variants] - variants passed in as props that don't change dynamically
@@ -47,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
+})

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,
@@ -142,7 +140,7 @@ ToggleSwitch.propTypes = {
 
 const staticStyles = StyleSheet.create({
   track: {
-    flex: 1,
+    flexGrow: 1,
     alignSelf: 'stretch',
     flexDirection: 'row'
   },