@telus-uds/components-base 0.0.2-prerelease.7 → 1.0.1

package/lib/ThemeProvider/index.js

@@ -1,6 +1,61 @@
-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;
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+var _exportNames = {
+  useTheme: true,
+  useSetTheme: true
+};
+Object.defineProperty(exports, "useTheme", {
+  enumerable: true,
+  get: function () {
+    return _useTheme.default;
+  }
+});
+Object.defineProperty(exports, "useSetTheme", {
+  enumerable: true,
+  get: function () {
+    return _useSetTheme.default;
+  }
+});
+exports.default = void 0;
+
+var _ThemeProvider = _interopRequireDefault(require("./ThemeProvider"));
+
+var _useTheme = _interopRequireDefault(require("./useTheme"));
+
+var _useSetTheme = _interopRequireDefault(require("./useSetTheme"));
+
+var _useThemeTokens = require("./useThemeTokens");
+
+Object.keys(_useThemeTokens).forEach(function (key) {
+  if (key === "default" || key === "__esModule") return;
+  if (Object.prototype.hasOwnProperty.call(_exportNames, key)) return;
+  if (key in exports && exports[key] === _useThemeTokens[key]) return;
+  Object.defineProperty(exports, key, {
+    enumerable: true,
+    get: function () {
+      return _useThemeTokens[key];
+    }
+  });
+});
+
+var _utils = require("./utils");
+
+Object.keys(_utils).forEach(function (key) {
+  if (key === "default" || key === "__esModule") return;
+  if (Object.prototype.hasOwnProperty.call(_exportNames, key)) return;
+  if (key in exports && exports[key] === _utils[key]) return;
+  Object.defineProperty(exports, key, {
+    enumerable: true,
+    get: function () {
+      return _utils[key];
+    }
+  });
+});
+
+function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { default: obj }; }
+
+var _default = _ThemeProvider.default;
+exports.default = _default;

package/lib/ThemeProvider/useSetTheme.js

@@ -1,11 +1,24 @@
-import { useCallback, useContext } from 'react';
-import { ThemeSetterContext } from './ThemeProvider';
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.default = void 0;
+
+var _react = require("react");
+
+var _ThemeProvider = require("./ThemeProvider");
 
 const useSetTheme = () => {
   // Replace current theme with provided object
-  const setTheme = useContext(ThemeSetterContext); // Merge provided object into current theme
+  const setTheme = (0, _react.useContext)(_ThemeProvider.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,
+  const editTheme = (0, _react.useCallback)(newTheme => setTheme((oldTheme = {}) => ({ ...oldTheme,
     ...newTheme
   })), [setTheme]);
   return {
@@ -14,4 +27,5 @@ const useSetTheme = () => {
   };
 };
 
-export default useSetTheme;
+var _default = useSetTheme;
+exports.default = _default;

package/lib/ThemeProvider/useTheme.js

@@ -1,8 +1,16 @@
-import { useContext } from 'react';
-import { ThemeContext } from './ThemeProvider';
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.default = void 0;
+
+var _react = require("react");
+
+var _ThemeProvider = require("./ThemeProvider");
 
 const useTheme = () => {
-  const theme = useContext(ThemeContext); // Fail fast if dev uses useTheme outside of ThemeProvider
+  const theme = (0, _react.useContext)(_ThemeProvider.ThemeContext); // Fail fast if dev uses useTheme outside of ThemeProvider
 
   if (theme instanceof Error) {
     throw theme;
@@ -11,4 +19,5 @@ const useTheme = () => {
   return theme;
 };
 
-export default useTheme;
+var _default = useTheme;
+exports.default = _default;

package/lib/ThemeProvider/useThemeTokens.js

@@ -1,6 +1,18 @@
-import { useCallback } from 'react';
-import useTheme from './useTheme';
-import { getComponentTheme, getThemeTokens, resolveTokens, mergeAppearances } from './utils';
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.useThemeTokensCallback = exports.useThemeTokens = void 0;
+
+var _react = require("react");
+
+var _useTheme = _interopRequireDefault(require("./useTheme"));
+
+var _utils = require("./utils");
+
+function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { default: obj }; }
+
 /**
  * @typedef {import('../utils/propTypes.js').AppearanceSet} AppearanceSet
  * @typedef {import('../utils/propTypes.js').TokensProp} TokensProp
@@ -33,11 +45,10 @@ import { getComponentTheme, getThemeTokens, resolveTokens, mergeAppearances } fr
  * @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);
+const useThemeTokens = (componentName, tokens = {}, variants = {}, states = {}) => {
+  const theme = (0, _useTheme.default)();
+  const componentTheme = (0, _utils.getComponentTheme)(theme, componentName);
+  const themeTokens = (0, _utils.getThemeTokens)(componentTheme, tokens, variants, states);
   return themeTokens;
 };
 /**
@@ -93,13 +104,18 @@ export const useThemeTokens = (componentName, tokens = {}, variants = {}, states
  *      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 = resolveTokens(tokens, tokenOverrides, appearances);
-    return getThemeTokens(componentTheme, resolvedTokens, appearances);
+
+exports.useThemeTokens = useThemeTokens;
+
+const useThemeTokensCallback = (componentName, tokens = {}, variants = {}) => {
+  const theme = (0, _useTheme.default)();
+  const componentTheme = (0, _utils.getComponentTheme)(theme, componentName);
+  const getThemeTokensCallback = (0, _react.useCallback)((states, tokenOverrides) => {
+    const appearances = (0, _utils.mergeAppearances)(variants, states);
+    const resolvedTokens = (0, _utils.resolveThemeTokens)(tokens, appearances, tokenOverrides);
+    return (0, _utils.getThemeTokens)(componentTheme, resolvedTokens, appearances);
   }, [componentTheme, tokens, variants]);
   return getThemeTokensCallback;
-};
+};
+
+exports.useThemeTokensCallback = useThemeTokensCallback;

package/lib/ThemeProvider/utils/index.js

@@ -1,2 +1,31 @@
-export * from './styles';
-export * from './theme-tokens';
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+
+var _styles = require("./styles");
+
+Object.keys(_styles).forEach(function (key) {
+  if (key === "default" || key === "__esModule") return;
+  if (key in exports && exports[key] === _styles[key]) return;
+  Object.defineProperty(exports, key, {
+    enumerable: true,
+    get: function () {
+      return _styles[key];
+    }
+  });
+});
+
+var _themeTokens = require("./theme-tokens");
+
+Object.keys(_themeTokens).forEach(function (key) {
+  if (key === "default" || key === "__esModule") return;
+  if (key in exports && exports[key] === _themeTokens[key]) return;
+  Object.defineProperty(exports, key, {
+    enumerable: true,
+    get: function () {
+      return _themeTokens[key];
+    }
+  });
+});

package/lib/ThemeProvider/utils/styles.js

@@ -1,12 +1,27 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.applyTextStyles = applyTextStyles;
+exports.applyShadowToken = applyShadowToken;
+exports.verticalAlignRow = verticalAlignRow;
+exports.applyOuterBorder = void 0;
+
+var _Platform = _interopRequireDefault(require("react-native-web/dist/cjs/exports/Platform"));
+
+var _systemConstants = require("@telus-uds/system-constants");
+
+function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { default: obj }; }
+
 /**
  * React-Native specific implementations of style patterns that
  * don't map directly to cross-platform design token values.
  */
-import { Platform } from 'react-native';
-import { fontBasePixels } from '@telus-uds/system-constants'; // Make design tokens fit React Native's text styles' specific requirements and quirks
-
-export function applyTextStyles({
+// Make design tokens fit React Native's text styles' specific requirements and quirks
+function applyTextStyles({
   fontSize,
+  fontScaleCap,
   lineHeight,
   letterSpacing,
   fontWeight = '400',
@@ -24,12 +39,12 @@ export function applyTextStyles({
 
   if (typeof lineHeight === 'number') {
     // React Native expects absolute line heights but multipliers are better as design tokens
-    styles.lineHeight = lineHeight * (fontSize || fontBasePixels);
+    styles.lineHeight = lineHeight * (fontSize || _systemConstants.fontBasePixels);
   }
 
-  if (typeof letterSpacing === 'number') {
+  if (typeof letterSpacing === 'number' && letterSpacing) {
     // Same as for line heights - React Native expects absolute letter spacing value
-    styles.letterSpacing = letterSpacing * (fontSize || fontBasePixels);
+    styles.letterSpacing = letterSpacing * (fontSize || _systemConstants.fontBasePixels);
   }
 
   if (fontName) {
@@ -39,7 +54,7 @@ export function applyTextStyles({
   } 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;
+    styles.fontWeight = _Platform.default.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
@@ -61,13 +76,16 @@ export function applyTextStyles({
  * @return {object}
  */
 
-export function applyShadowToken(shadowToken) {
+
+function applyShadowToken(shadowToken) {
   if (!shadowToken) return {};
-  const applyShadow = Platform.select({
+
+  const applyShadow = _Platform.default.select({
     web: () => applyWebShadow(shadowToken),
     ios: () => applyIosShadow(shadowToken),
     android: () => applyAndroidShadow(shadowToken)
   });
+
   return applyShadow();
 }
 
@@ -148,12 +166,30 @@ const verticalAlignToFlexRowAlign = {
   middle: 'center',
   bottom: 'flex-end'
 };
-export function verticalAlignRow(verticalAlign, reverse = false) {
+
+function verticalAlignRow(verticalAlign, reverse = false) {
   return {
     flexDirection: reverse ? 'row-reverse' : 'row',
     alignItems: verticalAlignToFlexRowAlign[verticalAlign]
   };
-} // React Native Views behave like flex blocks. There's no CSS 'display' and they can't inline themselves
+}
+/**
+ * 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 function applyLayoutStyles() {// TODO: map design tokens to styles that implement inline, stretch, center, etc
-}
+const applyOuterBorder = ({
+  outerBorderColor,
+  outerBorderWidth = 0,
+  outerBorderGap = 0,
+  borderRadius = 0
+}) => ({
+  margin: 0 - outerBorderWidth - outerBorderGap,
+  padding: outerBorderGap,
+  borderRadius: borderRadius + outerBorderGap + outerBorderWidth,
+  borderWidth: outerBorderWidth,
+  borderColor: outerBorderColor
+});
+
+exports.applyOuterBorder = applyOuterBorder;

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

@@ -1,3 +1,18 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.validateThemeTokensVersion = exports.toArray = exports.getThemeTokens = exports.mergeAppearances = exports.validateThemeTokens = exports.resolveThemeTokens = exports.doesThemeRuleApply = exports.doesThemeConditionApply = exports.getComponentTheme = void 0;
+
+var _propTypes = _interopRequireDefault(require("prop-types"));
+
+var _satisfies = _interopRequireDefault(require("semver/functions/satisfies"));
+
+var _package = _interopRequireDefault(require("../../../package.json"));
+
+function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { default: obj }; }
+
 /**
  * @typedef {import('../../utils/propTypes.js').AppearanceSet} AppearanceSet
  * @typedef {import('../../utils/propTypes.js').TokensProp} TokensProp
@@ -7,14 +22,16 @@
 /**
  * General utilities around working with theme tokens
  */
-export const getComponentTheme = (theme, componentName) => {
+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?.name || '';
+  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}")`);
@@ -28,23 +45,39 @@ export const getComponentTheme = (theme, componentName) => {
 
   return componentTheme;
 };
-export const doesThemeConditionApply = ([key, value], appearances) => {
+
+exports.getComponentTheme = getComponentTheme;
+
+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));
+
+exports.doesThemeConditionApply = doesThemeConditionApply;
+
+const doesThemeRuleApply = (rule, appearances) => Object.entries(rule.if).every(condition => doesThemeConditionApply(condition, appearances));
 /**
- * Turns a tokens prop and an optional tokens override prop (either or both of which may be a tokens getter function)
- * into one tokens set object where overrides are applied over the resolved default tokens.
+ * Turns a tokens prop (which may be either a tokens object or a tokens getter function)
+ * into one resolved tokens object, based on current appearances state.
+ *
+ * This is used inside `useThemeTokens` and `useThemeTokensCallback` for handling the `tokens`
+ * props of themed components. It may also be used directly in cases where a non-themed component
+ * needs to resolve a tokens prop that may be a tokens getter function or a resolved tokens object.
+ *
+ * A second tokens prop of tokens overrides may optionally be passed; it will be resolved to an object
+ * based on provided appearance state and then shallow-merged over the first set of tokens.
  *
  * @param {TokensProp} defaultTokens - a set of tokens or tokens getter function which may be overridden
- * @param {TokensProp} [tokenOverrides] - optional set of tokens or tokens getter function to override the default
  * @param {AppearanceSet} [appearances] - optional appearance set to pass to tokens getter functions
+ * @param {TokensProp} [tokenOverrides] - optional set of tokens or tokens getter function to override the default
  * @returns {TokensSet} - object containing resolved tokens with overrides applied
  */
 
-export const resolveTokens = (defaultTokens, tokenOverrides, appearances = {}) => {
+
+exports.doesThemeRuleApply = doesThemeRuleApply;
+
+const resolveThemeTokens = (defaultTokens, appearances = {}, tokenOverrides) => {
   const resolve = tokens => typeof tokens === 'function' ? tokens(appearances) : tokens;
 
   if (!tokenOverrides) return resolve(defaultTokens);
@@ -52,6 +85,30 @@ export const resolveTokens = (defaultTokens, tokenOverrides, appearances = {}) =
     [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
+ */
+
+
+exports.resolveThemeTokens = resolveThemeTokens;
+
+const validateThemeTokens = (themeTokens, validator, componentName) => {
+  _propTypes.default.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.
@@ -62,10 +119,28 @@ export const resolveTokens = (defaultTokens, tokenOverrides, appearances = {}) =
  * @returns {AppearanceSet}
  */
 
-export const mergeAppearances = (variants = {}, states) => states ? { ...states,
+
+exports.validateThemeTokens = validateThemeTokens;
+
+const mergeAppearances = (variants = {}, states) => states ? { ...states,
   ...variants
 } : variants;
-export const getThemeTokens = ({
+/**
+ * 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
+ */
+
+
+exports.mergeAppearances = mergeAppearances;
+
+const getThemeTokens = ({
   rules = [],
   tokens: defaultThemeTokens = {}
 }, tokensProp, variants = {}, states) => {
@@ -75,6 +150,40 @@ export const getThemeTokens = ({
   const themeTokens = rules.reduce((mergedTokens, rule) => doesThemeRuleApply(rule, appearances) ? { ...mergedTokens,
     ...rule.tokens
   } : mergedTokens, defaultThemeTokens);
-  return resolveTokens(themeTokens, tokensProp, appearances);
+  return resolveThemeTokens(themeTokens, appearances, tokensProp);
+};
+
+exports.getThemeTokens = getThemeTokens;
+
+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
+ */
+
+
+exports.toArray = toArray;
+
+const validateThemeTokensVersion = theme => {
+  var _theme$metadata2;
+
+  const expectedThemeTokensVersion = _package.default.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 (!(0, _satisfies.default)(actualThemeTokensVersion, expectedThemeTokensVersion)) {
+    throw new Error(`Invalid UDS token schema version detected.
+
+The UDS base components ${_package.default.name} v${_package.default.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 ${_package.default.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`);
+  }
 };
-export const toArray = strOrArr => Array.isArray(strOrArr) ? strOrArr : [strOrArr];
+
+exports.validateThemeTokensVersion = validateThemeTokensVersion;