@telus-uds/components-base 1.8.2 → 1.8.5

package/lib-module/ThemeProvider/ThemeProvider.js

@@ -0,0 +1,36 @@
+import React, { createContext, useState } from 'react';
+import PropTypes from 'prop-types';
+import { validateThemeTokensVersion } from './utils';
+import { jsx as _jsx } from "react/jsx-runtime";
+export const uninitialisedError = new Error('Theme context used outside of ThemeProvider');
+export const ThemeContext = /*#__PURE__*/createContext(uninitialisedError);
+export const ThemeSetterContext = /*#__PURE__*/createContext(uninitialisedError);
+
+const ThemeProvider = _ref => {
+  let {
+    children,
+    defaultTheme
+  } = _ref;
+  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 /*#__PURE__*/_jsx(ThemeSetterContext.Provider, {
+    value: setTheme,
+    children: /*#__PURE__*/_jsx(ThemeContext.Provider, {
+      value: theme,
+      children: children
+    })
+  });
+};
+
+ThemeProvider.propTypes = {
+  children: PropTypes.node.isRequired,
+  defaultTheme: PropTypes.shape({
+    metadata: PropTypes.shape({
+      themeTokensVersion: PropTypes.string.isRequired
+    }).isRequired
+  }).isRequired
+};
+export default ThemeProvider;

package/lib-module/ThemeProvider/index.js

@@ -0,0 +1,6 @@
+import ThemeProvider from './ThemeProvider';
+export { default as useTheme } from './useTheme';
+export { default as useSetTheme } from './useSetTheme';
+export * from './useThemeTokens';
+export * from './utils';
+export default ThemeProvider;

package/lib-module/ThemeProvider/useSetTheme.js

@@ -0,0 +1,25 @@
+import { useCallback, useContext } from 'react';
+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(newTheme => setTheme(function () {
+    let oldTheme = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : {};
+    return { ...oldTheme,
+      ...newTheme
+    };
+  }), [setTheme]);
+  return {
+    setTheme,
+    editTheme
+  };
+};
+
+export default useSetTheme;

package/lib-module/ThemeProvider/useTheme.js

@@ -0,0 +1,14 @@
+import { useContext } from 'react';
+import { ThemeContext } from './ThemeProvider';
+
+const useTheme = () => {
+  const theme = useContext(ThemeContext); // Fail fast if dev uses useTheme outside of ThemeProvider
+
+  if (theme instanceof Error) {
+    throw theme;
+  }
+
+  return theme;
+};
+
+export default useTheme;

package/lib-module/ThemeProvider/useThemeTokens.js

@@ -0,0 +1,110 @@
+import { useCallback } from 'react';
+import useTheme from './useTheme';
+import { getComponentTheme, getThemeTokens, resolveThemeTokens, mergeAppearances } from './utils';
+/**
+ * @typedef {import('../utils/props/variantProp.js').AppearanceSet} AppearanceSet
+ * @typedef {import('../utils/props/tokens.js').TokensProp} TokensProp
+ * @typedef {import('../utils/props/tokens.js').TokensSet} TokensSet
+ */
+
+/**
+ * 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
+ * @param {AppearanceSet} [states] - optional object containing current theme appearances dictated by user action or context
+ * @returns {TokensSet} - the currently-applicable resolved set of theme tokens to apply
+ */
+
+export const useThemeTokens = function (componentName) {
+  let tokens = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : {};
+  let variants = arguments.length > 2 && arguments[2] !== undefined ? arguments[2] : {};
+  let states = arguments.length > 3 && arguments[3] !== undefined ? arguments[3] : {};
+  const theme = useTheme();
+  const componentTheme = getComponentTheme(theme, componentName);
+  const themeTokens = getThemeTokens(componentTheme, tokens, variants, states);
+  return themeTokens;
+};
+/**
+ * Returns a memoised tokens getter function that gets tokens similar to calling useThemeTokens.
+ * Scenarios where `useThemeTokensCallback` should be used instead of `useThemeTokens` include:
+ *
+ * - 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
+ * @returns {(states: AppearanceSet, tokenOverrides?: TokensProp) => TokensSet}
+ *    - callback function that returning an overridable tokens set for current state. Only pass
+ *      tokenOverrides in rare cases where tokens overrides are also generated outside hook scope,
+ *      e.g. if one theme tokens callback needs to pass certain token overrides to another.
+ */
+
+export const useThemeTokensCallback = function (componentName) {
+  let tokens = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : {};
+  let variants = arguments.length > 2 && arguments[2] !== undefined ? arguments[2] : {};
+  const theme = useTheme();
+  const componentTheme = getComponentTheme(theme, componentName);
+  const getThemeTokensCallback = useCallback((states, tokenOverrides) => {
+    const appearances = mergeAppearances(variants, states);
+    const resolvedTokens = resolveThemeTokens(tokens, appearances, tokenOverrides);
+    return getThemeTokens(componentTheme, resolvedTokens, appearances);
+  }, [componentTheme, tokens, variants]);
+  return getThemeTokensCallback;
+};

package/lib-module/ThemeProvider/utils/index.js

@@ -0,0 +1,2 @@
+export * from './styles';
+export * from './theme-tokens';

package/lib-module/ThemeProvider/utils/styles.js

@@ -0,0 +1,181 @@
+/**
+ * React-Native specific implementations of style patterns that
+ * don't map directly to cross-platform design token values.
+ */
+import Platform from "react-native-web/dist/exports/Platform";
+import { fontBasePixels } from '@telus-uds/system-constants'; // Make design tokens fit React Native's text styles' specific requirements and quirks
+
+export function applyTextStyles(_ref) {
+  let {
+    fontSize,
+    fontScaleCap,
+    lineHeight,
+    letterSpacing,
+    fontWeight = '400',
+    fontName,
+    fontStyle = 'normal',
+    ...rest
+  } = _ref;
+  const styles = { ...rest
+  };
+
+  if (fontSize) {
+    // If relative font sizes are needed, catch and calculate them here
+    styles.fontSize = fontSize;
+  }
+
+  if (typeof lineHeight === 'number') {
+    // React Native expects absolute line heights but multipliers are better as design tokens
+    styles.lineHeight = lineHeight * (fontSize || fontBasePixels);
+  }
+
+  if (typeof letterSpacing === 'number' && letterSpacing) {
+    // Same as for line heights - React Native expects absolute letter spacing value
+    styles.letterSpacing = letterSpacing * (fontSize || fontBasePixels);
+  }
+
+  if (fontName) {
+    // Don't set undefined font families. May need some validation here that the font is available.
+    // Android doesn't recognise font weights natively so apply custom font weights via `fontFamily`.
+    styles.fontFamily = "".concat(fontName).concat(fontWeight).concat(fontStyle);
+  } else if (fontWeight) {
+    // If using system default font, apply the font weight directly.
+    // Font weight support in Android is limited to 'bold' or anything else === 'normal'.
+    styles.fontWeight = Platform.OS === 'android' && Number(fontWeight) > 400 ? 'bold' : fontWeight;
+  } // TODO: look into calculating typographic spacing with PixelRatio.getFontScale()
+  // Do while implementing advanced typography e.g. paragraph etc
+  // https://github.com/telus/universal-design-system/issues/89
+
+
+  return styles;
+}
+/**
+ * React Native's in-built shadow support is limited. Take an object describing an ideal shadow and
+ * return a platform-appropriate implementation that gets close to the described effect.
+ *
+ * @param {object}  shadowToken
+ * @param {boolean} shadowToken.inset
+ * @param {color}   shadowToken.string
+ * @param {number}  shadowToken.offsetX
+ * @param {number}  shadowToken.offsetY
+ * @param {number}  shadowToken.blur
+ * @param {number}  shadowToken.spread
+ * @return {object}
+ */
+
+export function applyShadowToken(shadowToken) {
+  if (!shadowToken) return {};
+  const applyShadow = Platform.select({
+    web: () => applyWebShadow(shadowToken),
+    ios: () => applyIosShadow(shadowToken),
+    android: () => applyAndroidShadow(shadowToken)
+  });
+  return applyShadow();
+}
+
+function applyWebShadow(_ref2) {
+  let {
+    inset,
+    color = '',
+    offsetX = 0,
+    offsetY = 0,
+    blur = 0,
+    spread = 0
+  } = _ref2;
+  const insetString = inset ? 'inset ' : '';
+  const boxShadow = {
+    boxShadow: "".concat(insetString).concat(offsetX, "px ").concat(offsetY, "px ").concat(blur, "px ").concat(spread, "px ").concat(color)
+  };
+  return boxShadow;
+}
+
+function applyAndroidShadow(shadowToken) {
+  const {
+    color,
+    inset,
+    spread,
+    offsetY,
+    offsetX
+  } = shadowToken; // Android shadows are very limited and workarounds are hacky. Use the built-in `elevation` API unless
+  // shadow design is radically different to a simple top-down shadow (e.g. horizontal, upward, or inset)
+
+  if (!inset && offsetY >= 0 && offsetY >= offsetX) {
+    return {
+      // Can't match other platforms, but can give longer shadows to elements designed for longer shadows
+      elevation: spread + offsetY,
+      shadowColor: color // Only applies on Android >= 9 and React Native >= 0.64.0
+
+    };
+  } // TODO: maybe use a library or workaround to increase capabilities.
+  // https://github.com/telus/universal-design-system/issues/535
+
+
+  return {};
+}
+
+function applyIosShadow(_ref3) {
+  let {
+    inset,
+    color,
+    offsetX,
+    offsetY,
+    spread,
+    blur
+  } = _ref3;
+  // React Native iOS doesn't support inset shadows.
+  // TODO: maybe use a library or workaround for inset shadows. This is a sizable task and would
+  // involve changing component implementations to use a custom view, can't be done with styles alone.
+  // https://github.com/telus/universal-design-system/issues/535
+  if (inset) return {}; // React Native iOS doesn't support spread. Where there's an offset, can approximate positive spread by
+  // increasing the (positive or negative) offset by the spread. This makes the shadow reach the point it
+  // would if spread was supported (with a side effect that its start is further "under" the element).
+
+  const nudgeBySpread = offset => {
+    if (!offset || spread <= 0) return 0;
+    return offset > 0 ? spread : spread * -1;
+  };
+
+  return {
+    shadowColor: color,
+    shadowOffset: {
+      width: offsetX + nudgeBySpread(offsetX),
+      height: offsetY + nudgeBySpread(offsetY)
+    },
+    shadowRadius: blur,
+    shadowOpacity: 1 // opacity is applied via RGBA in the `color` token
+
+  };
+}
+
+const verticalAlignToFlexRowAlign = {
+  top: 'flex-start',
+  middle: 'center',
+  bottom: 'flex-end'
+};
+export function verticalAlignRow(verticalAlign) {
+  let reverse = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : false;
+  return {
+    flexDirection: reverse ? 'row-reverse' : 'row',
+    alignItems: verticalAlignToFlexRowAlign[verticalAlign]
+  };
+}
+/**
+ * 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 = _ref4 => {
+  let {
+    outerBorderColor,
+    outerBorderWidth = 0,
+    outerBorderGap = 0,
+    borderRadius = 0
+  } = _ref4;
+  return {
+    margin: 0 - outerBorderWidth - outerBorderGap,
+    padding: outerBorderGap,
+    borderRadius: borderRadius + outerBorderGap + outerBorderWidth,
+    borderWidth: outerBorderWidth,
+    borderColor: outerBorderColor
+  };
+};

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

@@ -0,0 +1,163 @@
+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) => {
+  var _theme$metadata;
+
+  // 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 \"".concat(componentName, "\" with no theme provided"));
+  }
+
+  const themeName = ((_theme$metadata = theme.metadata) === null || _theme$metadata === void 0 ? void 0 : _theme$metadata.name) || '';
+
+  if (!theme.components) {
+    throw new Error("Theme \"".concat(themeName, "\" has no components defined (looking for \"").concat(componentName, "\")"));
+  }
+
+  const componentTheme = theme.components[componentName];
+
+  if (!componentTheme) {
+    throw new Error("Theme \"".concat(themeName, "\" does not have styles for component \"").concat(componentName, "\""));
+  }
+
+  return componentTheme;
+};
+export const doesThemeConditionApply = (_ref, appearances) => {
+  var _appearances$key;
+
+  let [key, value] = _ref;
+  // use null rather than undefined so we can serialise the value in themes
+  const appearanceValue = (_appearances$key = appearances[key]) !== null && _appearances$key !== void 0 ? _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 => {
+  var _theme$metadata2;
+
+  const expectedThemeTokensVersion = pkg.dependencies['@telus-uds/system-theme-tokens'];
+  const actualThemeTokensVersion = theme === null || theme === void 0 ? void 0 : (_theme$metadata2 = theme.metadata) === null || _theme$metadata2 === void 0 ? void 0 : _theme$metadata2.themeTokensVersion;
+
+  if (!semVerSatisfies(actualThemeTokensVersion, expectedThemeTokensVersion)) {
+    throw new Error("Invalid UDS token schema version detected.\n\nThe UDS base components ".concat(pkg.name, " v").concat(pkg.version, " are only compatible with UDS themes that are built with @telus-uds/system-theme-tokens version that is semver compatible with ").concat(expectedThemeTokensVersion, ". The current theme was built with @telus-uds/system-theme-tokens v").concat(actualThemeTokensVersion, ".\n\nIf you see this error than most likely you have attempted to install ").concat(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"));
+  }
+};