@telus-uds/components-base 1.2.0 → 1.4.0

package/lib-module/ThemeProvider/useSetTheme.js

@@ -0,0 +1,22 @@
+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((oldTheme = {}) => ({ ...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,105 @@
+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 = (componentName, tokens = {}, variants = {}, states = {}) => {
+  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 = (componentName, tokens = {}, variants = {}) => {
+  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,174 @@
+/**
+ * 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({
+  fontSize,
+  fontScaleCap,
+  lineHeight,
+  letterSpacing,
+  fontWeight = '400',
+  fontName,
+  fontStyle = 'normal',
+  ...rest
+}) {
+  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 = `${fontName}${fontWeight}${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({
+  inset,
+  color = '',
+  offsetX = 0,
+  offsetY = 0,
+  blur = 0,
+  spread = 0
+}) {
+  const insetString = inset ? 'inset ' : '';
+  const boxShadow = {
+    boxShadow: `${insetString}${offsetX}px ${offsetY}px ${blur}px ${spread}px ${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({
+  inset,
+  color,
+  offsetX,
+  offsetY,
+  spread,
+  blur
+}) {
+  // 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, reverse = 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 = ({
+  outerBorderColor,
+  outerBorderWidth = 0,
+  outerBorderGap = 0,
+  borderRadius = 0
+}) => ({
+  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,151 @@
+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 "${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 "${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 = ([key, value], appearances) => {
+  // 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 = (defaultTokens, appearances = {}, tokenOverrides) => {
+  const resolve = tokens => typeof tokens === 'function' ? tokens(appearances) : tokens;
+
+  if (!tokenOverrides) return resolve(defaultTokens);
+  return Object.entries(resolve(tokenOverrides)).reduce((mergedTokens, [tokenName, tokenValue]) => 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 = (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, variants = {}, states) => {
+  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.
+
+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`);
+  }
+};