@telus-uds/components-base 1.96.0 → 1.97.1

package/lib-module/ThemeProvider/ThemeProvider.js

@@ -1,84 +0,0 @@
-import React from 'react';
-import PropTypes from 'prop-types';
-import { validateThemeTokensVersion } from './utils';
-import responsiveProps from '../utils/props/responsiveProps';
-import { jsx as _jsx } from "react/jsx-runtime";
-export const uninitialisedError = new Error('Theme context used outside of ThemeProvider');
-export const ThemeContext = /*#__PURE__*/React.createContext(uninitialisedError);
-export const ThemeSetterContext = /*#__PURE__*/React.createContext(uninitialisedError);
-
-// These options default to `true` in v1.x to match legacy defaults and avoid breaking changes.
-// This should change in future major releases to become "opt-in" legacy support.
-const defaultThemeOptions = {
-  // TODO: switch `forceAbsoluteFontSizing` to be false by default in the next major version
-  forceAbsoluteFontSizing: true,
-  // TODO: switch `forceZIndex` to be false by default in the next major version
-  forceZIndex: true,
-  // TODO: switch `enableHelmetSSR` to be false by default in the next major version
-  enableHelmetSSR: true,
-  enableMediaQueryStyleSheet: false
-};
-const ThemeProvider = _ref => {
-  let {
-    children,
-    defaultTheme,
-    themeOptions = {}
-  } = _ref;
-  const [theme, setTheme] = React.useState(defaultTheme);
-  React.useEffect(() => {
-    if (theme.metadata.name !== defaultTheme.metadata.name) {
-      setTheme(defaultTheme);
-    }
-  }, [theme.metadata.name, defaultTheme]);
-  const appliedThemeOptions = {
-    ...defaultThemeOptions,
-    ...themeOptions
-  };
-
-  // 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,
-        themeOptions: appliedThemeOptions
-      },
-      children: children
-    })
-  });
-};
-ThemeProvider.propTypes = {
-  children: PropTypes.node.isRequired,
-  defaultTheme: PropTypes.shape({
-    metadata: PropTypes.shape({
-      themeTokensVersion: PropTypes.string.isRequired,
-      name: PropTypes.string.isRequired
-    }).isRequired
-  }).isRequired,
-  /**
-   * An object containing options allowing to customize the theming experience:
-   *
-   * - `forceAbsoluteFontSizing`: available on web only; when set to true, allows
-   *   using absolute font sizing (in pixels, doesn't scale) instead of the
-   *   relative sizing (in `rem`, scales depending on the browser settings)
-   * - `contentMaxWidth`: allows configuration of the content max width to be used in components
-   *   such as Footnote and Notification to avoid content to stretch width more then the page's width
-   * - `forceZIndex`: available on web only, when set to false, sets zIndex on `View` to be `auto`
-   *   and when true, sets zIndex to be `0` (the default from `react-native-web`)
-   * - `enableHelmetSSR`: on Web SSR, allows React Helmet to run during server-side rendering. This should be
-   *   disabled unless a web app has been specifically configured to stop React Helmet accumulating
-   *   instances (which may cause a memory leak). See React Helmet's docs: https://github.com/nfl/react-helmet
-   * - `enableMediaQueryStyleSheet`: enables the use of Media Query StyleSheet.
-   */
-  themeOptions: PropTypes.shape({
-    forceAbsoluteFontSizing: PropTypes.bool,
-    forceZIndex: PropTypes.bool,
-    enableHelmetSSR: PropTypes.bool,
-    contentMaxWidth: responsiveProps.getTypeOptionallyByViewport(PropTypes.number),
-    enableMediaQueryStyleSheet: PropTypes.bool
-  })
-};
-export default ThemeProvider;

package/lib-module/ThemeProvider/index.js

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

package/lib-module/ThemeProvider/useResponsiveThemeTokens.js

@@ -1,81 +0,0 @@
-import { viewports } from '@telus-uds/system-constants';
-import useTheme from './useTheme';
-import { getComponentTheme, mergeAppearances, resolveThemeTokens } from './utils';
-const getResponsiveThemeTokens = function (_ref, tokensProp) {
-  let {
-    rules = [],
-    tokens: defaultThemeTokens = {}
-  } = _ref;
-  let variants = arguments.length > 2 && arguments[2] !== undefined ? arguments[2] : {};
-  let states = arguments.length > 3 ? arguments[3] : undefined;
-  const appearances = mergeAppearances(variants, states);
-  const tokensByViewport = Object.fromEntries(viewports.keys.map(viewport => [viewport, {
-    ...defaultThemeTokens
-  }]));
-
-  // Go through each rule and collect them for the corresponding viewport if they apply
-  rules.forEach(rule => {
-    if (doesRuleApply(rule, appearances)) {
-      // If the rule does not have a viewport specified, we collect it in all viewports
-      let targetViewports = rule.if.viewport || viewports.keys;
-      if (!Array.isArray(targetViewports)) {
-        targetViewports = [targetViewports];
-      }
-      targetViewports.forEach(viewport => {
-        tokensByViewport[viewport] = {
-          ...tokensByViewport[viewport],
-          ...rule.tokens
-        };
-      });
-    }
-  });
-  Object.keys(tokensByViewport).forEach(viewport => {
-    tokensByViewport[viewport] = resolveThemeTokens(tokensByViewport[viewport], appearances, tokensProp);
-  });
-  return tokensByViewport;
-};
-const doesRuleApply = (rule, appearances) => Object.entries(rule.if).every(condition => doesConditionApply(condition, appearances));
-const doesConditionApply = (_ref2, appearances) => {
-  let [key, value] = _ref2;
-  if (key === 'viewport') {
-    return true;
-  }
-  // 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;
-};
-
-/**
- * @typedef {import('../utils/props/tokens.js').TokensSet} TokensSet
- * @typedef {import('../utils/props/tokens.js').TokensProp} TokensProp
- * @typedef {import('../utils/props/variantProp').AppearanceSet} AppearanceSet
- *
- * Returns a complete set of tokens for a component for each viewport based on which of the
- * component's theme rules apply to the current set of theme appearances.
- * Pass the returned output to createMediaQueryStyles to generate media query styles for use inside
- * the media query stylesheet from './utils/ssr-media-query'.
- *
- * @typedef {Object} ResponsiveObject
- * @property {TokensSet} xs
- * @property {TokensSet} sm
- * @property {TokensSet} md
- * @property {TokensSet} lg
- * @property {TokensSet} xl
- *
- * @param { string } componentName
- * @param { TokensProp } tokens
- * @param { AppearanceSet } variants
- * @param { AppearanceSet } states
- * @returns { ResponsiveObject }
- */
-
-const useResponsiveThemeTokens = 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 = getResponsiveThemeTokens(componentTheme, tokens, variants, states);
-  return themeTokens;
-};
-export default useResponsiveThemeTokens;

package/lib-module/ThemeProvider/useSetTheme.js

@@ -1,24 +0,0 @@
-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

@@ -1,11 +0,0 @@
-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

@@ -1,109 +0,0 @@
-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

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

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

@@ -1,198 +0,0 @@
-/**
- * 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 {
-    fontColor,
-    fontSize,
-    fontScaleCap,
-    lineHeight,
-    letterSpacing,
-    fontWeight = '400',
-    fontName,
-    fontStyle = 'normal',
-    themeOptions = {
-      // TODO: switch `forceAbsoluteFontSizing` to be false by default in the next major version
-      forceAbsoluteFontSizing: true
-    },
-    ...rest
-  } = _ref;
-  const styles = {
-    ...rest
-  };
-  const {
-    forceAbsoluteFontSizing
-  } = themeOptions;
-  if (fontSize) {
-    // If relative font sizes are needed, catch and calculate them here
-    styles.fontSize = Platform.OS === 'web' && !forceAbsoluteFontSizing ? `${fontSize / fontBasePixels}rem` : 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;
-  }
-  if (fontColor) {
-    styles.color = fontColor;
-  }
-
-  // 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: `${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(_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]
-  };
-}
-const calculateBorderRadius = (borderRadius, outerBorderGap, outerBorderWidth) => {
-  if (borderRadius) {
-    return borderRadius + outerBorderGap + outerBorderWidth;
-  }
-  return null;
-};
-/**
- * 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,
-    borderTopLeftRadius,
-    borderTopRightRadius,
-    borderBottomLeftRadius,
-    borderBottomRightRadius
-  } = _ref4;
-  return {
-    margin: 0 - outerBorderWidth - outerBorderGap,
-    padding: outerBorderGap,
-    borderRadius: calculateBorderRadius(borderRadius, outerBorderGap, outerBorderWidth),
-    borderTopLeftRadius: calculateBorderRadius(borderTopLeftRadius, outerBorderGap, outerBorderWidth),
-    borderTopRightRadius: calculateBorderRadius(borderTopRightRadius, outerBorderGap, outerBorderWidth),
-    borderBottomLeftRadius: calculateBorderRadius(borderBottomLeftRadius, outerBorderGap, outerBorderWidth),
-    borderBottomRightRadius: calculateBorderRadius(borderBottomRightRadius, outerBorderGap, outerBorderWidth),
-    borderWidth: outerBorderWidth,
-    borderColor: outerBorderColor
-  };
-};