@telus-uds/components-base 2.4.0 → 3.0.0

package/lib/esm/TextInput/TextInputBase.js

@@ -0,0 +1,495 @@
+import React from 'react';
+import PropTypes from 'prop-types';
+import Platform from "react-native-web/dist/exports/Platform";
+import StyleSheet from "react-native-web/dist/exports/StyleSheet";
+import NativeTextInput from "react-native-web/dist/exports/TextInput";
+import View from "react-native-web/dist/exports/View";
+import { applyTextStyles, useTheme, useThemeTokens, applyOuterBorder } from '../ThemeProvider';
+import StackView from '../StackView';
+import IconButton from '../IconButton';
+import Icon from '../Icon';
+import { a11yProps, getTokensPropType, selectSystemProps, textInputHandlerProps, textInputProps, useCopy, useInputValue, useSpacingScale, variantProp, viewProps } from '../utils';
+import dictionary from './dictionary';
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+const [selectProps, selectedSystemPropTypes] = selectSystemProps([a11yProps, textInputHandlerProps, textInputProps, viewProps]);
+const selectInputStyles = function (_ref, themeOptions, inactive, type) {
+  let {
+    backgroundColor,
+    color,
+    borderWidth = 0,
+    borderColor,
+    borderRadius,
+    paddingTop = 0,
+    paddingBottom = 0,
+    paddingLeft,
+    paddingRight = 0,
+    fontName,
+    fontSize,
+    fontWeight,
+    lineHeight,
+    icon,
+    minLines,
+    maxLines,
+    width,
+    height
+  } = _ref;
+  let buttonCount = arguments.length > 4 && arguments[4] !== undefined ? arguments[4] : 0;
+  let buttonSize = arguments.length > 5 && arguments[5] !== undefined ? arguments[5] : 0;
+  let buttonsGapSize = arguments.length > 6 && arguments[6] !== undefined ? arguments[6] : 0;
+  let isPassword = arguments.length > 7 ? arguments[7] : undefined;
+  let iconLeftWidth = arguments.length > 8 ? arguments[8] : undefined;
+  let iconLeftGap = arguments.length > 9 ? arguments[9] : undefined;
+  let direction = arguments.length > 10 ? arguments[10] : undefined;
+  // Subtract border width from padding so overall input width/height doesn't
+  // jump around if the border width changes (avoiding NaN and negative padding)
+  const offsetBorder = value => typeof value === 'number' ? Math.max(0, value - borderWidth) : value;
+  const textStyles = applyTextStyles({
+    fontName: isPassword ? undefined : fontName,
+    // In this case, we don't want to apply the fontName to the input if it's a password because Monotype don't have support for the masked characters in mobile.
+    fontSize,
+    lineHeight,
+    fontWeight,
+    themeOptions
+  });
+  function linesToHeight(lines) {
+    const {
+      lineHeight: absoluteLineHeight
+    } = textStyles;
+    return lines !== undefined ? lines * absoluteLineHeight + paddingTop + paddingBottom : undefined;
+  }
+  const minHeight = linesToHeight(minLines);
+  const maxHeight = linesToHeight(maxLines);
+  const webStyles = Platform.select({
+    web: {
+      outline: 'none',
+      cursor: inactive ? 'not-allowed' : undefined,
+      resize: minHeight !== maxHeight ? 'vertical' : 'none' // does nothing for an input, only needed for textarea
+    }
+  });
+  const getPaddingLeft = () => {
+    if (type === 'card') {
+      return offsetBorder(paddingLeft + 34);
+    }
+    if (direction === 'left') {
+      return offsetBorder(iconLeftWidth + iconLeftGap + staticStyles.iconLeftContainer.paddingLeft);
+    }
+    return offsetBorder(paddingLeft);
+  };
+  const buttonSpacing = isPassword ? buttonsGapSize : -buttonsGapSize;
+  const adjustedPaddingRight = paddingRight + (buttonCount ? 1 : 0) * (buttonSize + buttonSpacing);
+  const adjustedPaddingWithButtons = buttonCount > 1 ? paddingRight : adjustedPaddingRight;
+  const paddingWithIcon = buttonSize + adjustedPaddingRight;
+  return {
+    backgroundColor,
+    color,
+    borderWidth,
+    borderColor,
+    borderRadius,
+    paddingLeft: getPaddingLeft(),
+    paddingRight: icon ? offsetBorder(paddingWithIcon) : offsetBorder(adjustedPaddingWithButtons),
+    paddingTop: offsetBorder(paddingTop),
+    paddingBottom: offsetBorder(paddingBottom),
+    minHeight,
+    maxHeight,
+    width,
+    height,
+    ...textStyles,
+    ...webStyles
+  };
+};
+const selectOuterBorderStyles = _ref2 => {
+  let {
+    outerBackgroundColor,
+    outerBorderWidth,
+    outerBorderColor,
+    borderRadius
+  } = _ref2;
+  return {
+    background: outerBackgroundColor,
+    ...applyOuterBorder({
+      outerBorderColor,
+      outerBorderWidth,
+      borderRadius
+    })
+  };
+};
+const selectIconTokens = _ref3 => {
+  let {
+    iconSize,
+    iconColor
+  } = _ref3;
+  return {
+    size: iconSize,
+    color: iconColor
+  };
+};
+const selectIconContainerStyles = (_ref4, buttonCount) => {
+  let {
+    buttonSize,
+    buttonsGapSize,
+    paddingRight,
+    paddingBottom
+  } = _ref4;
+  return {
+    paddingRight: paddingRight + buttonCount * (buttonSize + buttonsGapSize),
+    paddingBottom
+  };
+};
+const selectIconCardLeftContainerStyles = _ref5 => {
+  let {
+    leftIconPaddingBottom
+  } = _ref5;
+  return {
+    paddingBottom: leftIconPaddingBottom
+  };
+};
+const selectIconLeftContainerStyles = _ref6 => {
+  let {
+    iconLeftPaddingBottom
+  } = _ref6;
+  return {
+    paddingBottom: iconLeftPaddingBottom
+  };
+};
+const selectButtonsContainerStyle = _ref7 => {
+  let {
+    buttonsPaddingRight
+  } = _ref7;
+  return {
+    paddingRight: buttonsPaddingRight
+  };
+};
+const getIcon = function () {
+  let cardNumber = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : '';
+  let {
+    defaultCreditIcon,
+    amexIcon,
+    visaIcon,
+    masterCardIcon
+  } = arguments.length > 1 ? arguments[1] : undefined;
+  const sanitizedCardNumber = cardNumber.replace(/[^0-9]/g, '');
+  const firstFourDigits = sanitizedCardNumber.slice(0, 4);
+  const number = Number(firstFourDigits);
+  const visaRange = number >= 4000 && number <= 4999;
+  const amexRange = number >= 3400 && number <= 3499 || number >= 3700 && number <= 3799;
+  const masterCardRange = number >= 5100 && number <= 5599 || number >= 2221 && number <= 2720;
+  let selectedIcon = {
+    icon: defaultCreditIcon,
+    testID: 'default'
+  };
+  const objVisaIcon = {
+    icon: visaIcon,
+    testID: 'visa'
+  };
+  const objAmexIcon = {
+    icon: amexIcon,
+    testID: 'amex'
+  };
+  const objMasterCardIcon = {
+    icon: masterCardIcon,
+    testID: 'mastercard'
+  };
+  if (visaRange) selectedIcon = objVisaIcon;else if (amexRange) selectedIcon = objAmexIcon;else if (masterCardRange) selectedIcon = objMasterCardIcon;
+  return /*#__PURE__*/_jsx(Icon, {
+    icon: selectedIcon.icon,
+    variant: {
+      size: 'large'
+    },
+    testID: selectedIcon.testID
+  });
+};
+const TextInputBase = /*#__PURE__*/React.forwardRef((_ref8, ref) => {
+  let {
+    buttons = [],
+    copy = 'en',
+    height,
+    inactive,
+    initialValue,
+    onBlur,
+    onChange,
+    onChangeText,
+    onClear,
+    onFocus,
+    onMouseOut,
+    onMouseOver,
+    pattern,
+    readOnly,
+    tokens,
+    value,
+    variant = {},
+    type,
+    onKeyPress,
+    direction,
+    ...rest
+  } = _ref8;
+  const [isFocused, setIsFocused] = React.useState(false);
+  const [showPassword, setShowPassword] = React.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] = React.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 defaultRef = React.useRef();
+  const inputRef = ref ?? defaultRef;
+  const {
+    currentValue,
+    resetValue,
+    setValue,
+    isControlled,
+    isDirty
+  } = useInputValue({
+    value,
+    initialValue,
+    inputRef,
+    onChange,
+    readOnly
+  });
+  const {
+    password,
+    numeric
+  } = variant;
+  const isNumeric = numeric || type === 'card' || type === 'number';
+  const isPassword = password || type === 'password';
+  const element = inputRef?.current;
+  React.useEffect(() => {
+    if (Platform.OS === 'web' && pattern && element) {
+      // React Native Web doesn't support `pattern`, so we have to attach it via a ref,
+      // which a `pattern` user must provide anyway to call .checkValidity() on the element.
+      element.pattern = pattern;
+    }
+  }, [element, pattern]);
+  const handleChangeText = event => {
+    const text = event.nativeEvent?.text || event.target?.value;
+    let filteredText = isNumeric ? text?.replace(/[^\d]/g, '') : text;
+    if (type === 'card' && filteredText) {
+      const formattedValue = filteredText.replace(/[^a-zA-Z0-9]/g, '');
+      const regex = new RegExp(`([a-zA-Z0-9]{4})(?=[a-zA-Z0-9])`, 'g');
+      // Add a space every 4 digits starting from the 5th position
+      filteredText = formattedValue.replace(regex, '$1 ').trim();
+    }
+    setValue(filteredText, event);
+    if (typeof onChangeText === 'function') onChangeText(filteredText, event);
+  };
+  const states = {
+    focus: isFocused,
+    hover: isHovered,
+    inactive
+  };
+  const themeTokens = useThemeTokens('TextInput', tokens, variant, states);
+  const handleClear = event => {
+    onClear?.(event);
+    resetValue(event);
+    inputRef?.current?.focus();
+  };
+  const handleShowOrHide = () => {
+    if (!variant.inactive) setShowPassword(!showPassword);
+  };
+  const {
+    buttonsGap,
+    clearButtonIcon: ClearButtonIcon,
+    icon: IconComponent,
+    passwordShowButtonIcon,
+    passwordHideButtonIcon,
+    defaultCreditIcon,
+    amexIcon,
+    visaIcon,
+    masterCardIcon,
+    iconLeftGap
+  } = themeTokens;
+  const buttonsGapSize = useSpacingScale(buttonsGap);
+  const getCopy = useCopy({
+    dictionary,
+    copy
+  });
+  const textInputButtons = direction === 'left' ? buttons.filter(button => button && button.key !== 'submitIcon') : buttons;
+  const submitIcon = direction === 'left' ? buttons.find(button => button && button.key === 'submitIcon') : null;
+  if (onClear && isDirty) {
+    textInputButtons?.unshift(/*#__PURE__*/_jsx(IconButton, {
+      accessibilityLabel: getCopy('clearButtonAccessibilityLabel'),
+      icon: ClearButtonIcon,
+      onPress: handleClear,
+      variant: {
+        compact: true
+      }
+    }, "clear"));
+  }
+  if (isPassword) {
+    textInputButtons?.unshift(/*#__PURE__*/_jsx(IconButton, {
+      accessibilityLabel: showPassword ? getCopy('hidePasswordAccessibilityLabel') : getCopy('showPasswordAccessibilityLabel'),
+      icon: !showPassword ? passwordShowButtonIcon : passwordHideButtonIcon,
+      onPress: handleShowOrHide,
+      variant: {
+        compact: true,
+        password: true,
+        inactive: variant.inactive,
+        size: 'large'
+      },
+      tokens: {
+        width: 40,
+        height: 40
+      }
+    }, !showPassword ? 'hide' : 'show'));
+  }
+  const inputProps = {
+    ...selectProps(rest),
+    editable: !inactive,
+    onFocus: handleFocus,
+    onBlur: handleBlur,
+    onMouseOver: handleMouseOver,
+    onMouseOut: handleMouseOut,
+    onChange: handleChangeText,
+    defaultValue: initialValue,
+    maxLength: type === 'card' ? 19 : undefined,
+    value: isControlled ? currentValue : undefined,
+    onKeyPress
+  };
+  const {
+    themeOptions
+  } = useTheme();
+  const iconLeftWidth = submitIcon ? submitIcon.props.tokens.size ?? 0 : 0;
+  const nativeInputStyle = selectInputStyles({
+    ...themeTokens,
+    height
+  }, themeOptions, inactive, type, buttons?.length, themeTokens.buttonSize, buttonsGapSize, isPassword, iconLeftWidth, iconLeftGap, direction);
+  const {
+    minHeight = 0,
+    maxHeight = Infinity
+  } = nativeInputStyle;
+  const [inputHeight, setInputHeight] = React.useState(minHeight || 0);
+
+  /* get the new height between the limits and update 
+  the state with the new height */
+  const measureHeightWeb = React.useCallback(() => {
+    const el = inputRef.current;
+    const scrollHeight = el.scrollHeight || 0;
+    let newHeight = Math.max(scrollHeight, minHeight);
+    newHeight = Math.min(newHeight, maxHeight);
+    setInputHeight(newHeight);
+  }, [inputRef, minHeight, maxHeight]);
+
+  /* restores the height and the value first to then 
+  calculate the height correctly */
+  React.useEffect(() => {
+    if (Platform.OS === 'web' && inputRef.current) {
+      const el = inputRef.current;
+      el.style.height = 'auto';
+      el.value = currentValue;
+      measureHeightWeb();
+    }
+  }, [currentValue, measureHeightWeb, inputRef]);
+  const shouldShowSubmitIcon = submitIcon && direction === 'left' && !inactive;
+  return /*#__PURE__*/_jsxs(View, {
+    style: selectOuterBorderStyles(themeTokens),
+    children: [shouldShowSubmitIcon && /*#__PURE__*/_jsx(View, {
+      style: [staticStyles.iconLeftContainer, selectIconLeftContainerStyles(themeTokens)],
+      children: submitIcon
+    }), type === 'card' && /*#__PURE__*/_jsx(View, {
+      pointerEvents: "none",
+      style: [staticStyles.iconCardLeftContainer, selectIconCardLeftContainerStyles(themeTokens)],
+      children: getIcon(currentValue, {
+        defaultCreditIcon,
+        amexIcon,
+        visaIcon,
+        masterCardIcon
+      })
+    }), /*#__PURE__*/_jsx(NativeTextInput, {
+      ref: inputRef,
+      keyboardType: isNumeric ? 'numeric' : 'default',
+      inputMode: isNumeric ? 'numeric' : undefined,
+      style: {
+        ...nativeInputStyle,
+        height: Math.max(inputHeight, minHeight)
+      },
+      secureTextEntry: isPassword && !showPassword,
+      ...inputProps
+    }), IconComponent && /*#__PURE__*/_jsx(View, {
+      pointerEvents: "none" // avoid hijacking input press events
+      ,
+      style: [staticStyles.rightIconContainer, selectIconContainerStyles({
+        ...themeTokens,
+        buttonsGapSize
+      }, buttons?.length)],
+      children: /*#__PURE__*/_jsx(IconComponent, {
+        ...selectIconTokens(themeTokens)
+      })
+    }), buttons?.length > 0 && !inactive && /*#__PURE__*/_jsx(View, {
+      style: [staticStyles.buttonsContainer, selectButtonsContainerStyle(themeTokens)],
+      children: /*#__PURE__*/_jsx(StackView, {
+        direction: "row",
+        space: buttonsGap,
+        children: textInputButtons
+      })
+    })]
+  });
+});
+TextInputBase.displayName = 'TextInputBase';
+TextInputBase.propTypes = {
+  ...selectedSystemPropTypes,
+  buttons: PropTypes.arrayOf(PropTypes.node),
+  /**
+   * Select English or French copy for the accessible labels.
+   * You may also pass in a custom dictionary object.
+   */
+  copy: PropTypes.oneOfType([PropTypes.oneOf(['en', 'fr']), PropTypes.shape({
+    clearButtonAccessibilityLabel: PropTypes.string
+  })]),
+  type: PropTypes.oneOfType([PropTypes.oneOf(['password', 'card', 'number'])]),
+  height: PropTypes.number,
+  inactive: PropTypes.bool,
+  initialValue: PropTypes.string,
+  onBlur: PropTypes.func,
+  onChange: PropTypes.func,
+  onChangeText: PropTypes.func,
+  onClear: PropTypes.func,
+  onFocus: PropTypes.func,
+  onMouseOut: PropTypes.func,
+  onMouseOver: PropTypes.func,
+  onKeyPress: PropTypes.func,
+  readOnly: PropTypes.bool,
+  tokens: getTokensPropType('TextInput', 'TextArea'),
+  value: PropTypes.string,
+  variant: variantProp.propType
+};
+export default TextInputBase;
+const staticStyles = StyleSheet.create({
+  buttonsContainer: {
+    position: 'absolute',
+    flexDirection: 'row',
+    alignItems: 'center',
+    right: 0,
+    top: 0,
+    bottom: 0,
+    justifyContent: 'center'
+  },
+  rightIconContainer: {
+    position: 'absolute',
+    right: 0,
+    bottom: 0
+  },
+  iconCardLeftContainer: {
+    paddingLeft: 10,
+    position: 'absolute',
+    left: 0,
+    bottom: 0,
+    zIndex: 1
+  },
+  iconLeftContainer: {
+    paddingLeft: 10,
+    position: 'absolute',
+    left: 0,
+    bottom: 0,
+    zIndex: 1
+  }
+});

package/lib/esm/ThemeProvider/utils/theme-tokens.js

@@ -0,0 +1,158 @@
+import PropTypes from 'prop-types';
+import semVerSatisfies from 'semver/functions/satisfies';
+import pkg from '../../../package.json';
+
+/**
+ * @typedef {import('../../utils/props/variantProp.js').AppearanceSet} AppearanceSet
+ * @typedef {import('../../utils/props/tokens.js').TokensProp} TokensProp
+ * @typedef {import('../../utils/props/tokens.js').TokensSet} TokensSet
+ */
+
+/**
+ * General utilities around working with theme tokens
+ */
+
+export const getComponentTheme = (theme, componentName) => {
+  // Give clear and understandable error messages for common dev errors, for example,
+  // typo in component name, missing export or accessing old version of theme
+  if (!theme) {
+    throw new Error(`Called useTheme's getStyle on "${componentName}" with no theme provided`);
+  }
+  const themeName = theme.metadata?.name || '';
+  if (!theme.components) {
+    throw new Error(`Theme "${themeName}" has no components defined (looking for "${componentName}")`);
+  }
+  const componentTheme = theme.components[componentName];
+  if (!componentTheme) {
+    throw new Error(`Theme "${themeName}" does not have styles for component "${componentName}"`);
+  }
+  return componentTheme;
+};
+export const doesThemeConditionApply = (_ref, appearances) => {
+  let [key, value] = _ref;
+  // use null rather than undefined so we can serialise the value in themes
+  const appearanceValue = appearances[key] ?? null;
+  return Array.isArray(value) ? value.includes(appearanceValue) : value === appearanceValue;
+};
+export const doesThemeRuleApply = (rule, appearances) => Object.entries(rule.if).every(condition => doesThemeConditionApply(condition, appearances));
+
+/**
+ * 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 {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 resolveThemeTokens = function (defaultTokens) {
+  let appearances = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : {};
+  let tokenOverrides = arguments.length > 2 ? arguments[2] : undefined;
+  const resolve = tokens => typeof tokens === 'function' ? tokens(appearances) : tokens;
+  if (!tokenOverrides) return resolve(defaultTokens);
+  return Object.entries(resolve(tokenOverrides)).reduce((mergedTokens, _ref2) => {
+    let [tokenName, tokenValue] = _ref2;
+    return tokenValue === undefined ? mergedTokens : {
+      ...mergedTokens,
+      [tokenName]: tokenValue
+    };
+  }, resolve(defaultTokens));
+};
+
+/**
+ * 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.
+ * Returns an empty object if both variants and states are undefined.
+ *
+ * @param {AppearanceSet} [variants]
+ * @param {AppearanceSet} [states]
+ * @returns {AppearanceSet}
+ */
+export const mergeAppearances = function () {
+  let variants = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : {};
+  let states = arguments.length > 1 ? arguments[1] : undefined;
+  return 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 = function (_ref3, tokensProp) {
+  let {
+    rules = [],
+    tokens: defaultThemeTokens = {}
+  } = _ref3;
+  let variants = arguments.length > 2 && arguments[2] !== undefined ? arguments[2] : {};
+  let states = arguments.length > 3 ? arguments[3] : undefined;
+  const appearances = mergeAppearances(variants, states);
+  // TODO: if in dev mode, validate the appearances and provided propTokens
+
+  // Get the theme's default tokens set and merge tokens from applicable theme rules over it
+  const themeTokens = rules.reduce((mergedTokens, rule) => doesThemeRuleApply(rule, appearances) ? {
+    ...mergedTokens,
+    ...rule.tokens
+  } : mergedTokens, defaultThemeTokens);
+  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/docs/docs/multi-brand-usage.md`);
+  }
+};