@telus-uds/components-base 1.6.1 → 1.8.0

package/lib-module/Search/Search.js

@@ -1,9 +1,9 @@
-import React, { forwardRef, useState } from 'react';
+import React, { forwardRef } from 'react';
 import View from "react-native-web/dist/exports/View";
 import StyleSheet from "react-native-web/dist/exports/StyleSheet";
 import PropTypes from 'prop-types';
 import { useThemeTokens, useThemeTokensCallback } from '../ThemeProvider';
-import { a11yProps, getTokensPropType, selectSystemProps, selectTokens, useSpacingScale, variantProp, viewProps } from '../utils';
+import { a11yProps, getTokensPropType, selectSystemProps, selectTokens, useInputValue, useSpacingScale, textInputHandlerProps, textInputProps, variantProp, viewProps } from '../utils';
 import TextInputBase from '../TextInput/TextInputBase';
 import ButtonBase from '../Button/ButtonBase';
 import StackView from '../StackView';
@@ -11,7 +11,8 @@ import useCopy from '../utils/useCopy';
 import dictionary from './dictionary';
 import { jsx as _jsx } from "react/jsx-runtime";
 import { jsxs as _jsxs } from "react/jsx-runtime";
-const [selectProps, selectedSystemPropTypes] = selectSystemProps([a11yProps, viewProps]);
+const [selectContainerProps, selectedContainerPropTypes] = selectSystemProps([a11yProps, viewProps]);
+const [selectInputProps, selectedInputPropTypes] = selectSystemProps([textInputHandlerProps, textInputProps]);
 
 const selectInputTokens = ({
   searchTokens,
@@ -66,8 +67,9 @@ const selectIconTokens = ({
 
 
 const Search = /*#__PURE__*/forwardRef(({
-  initialValue = '',
-  placeholder = 'Search',
+  initialValue,
+  value,
+  placeholder,
   inactive,
   onChange,
   onSubmit,
@@ -78,7 +80,14 @@ const Search = /*#__PURE__*/forwardRef(({
   variant,
   ...rest
 }, ref) => {
-  const [value, setValue] = useState(initialValue);
+  const {
+    currentValue = '',
+    setValue
+  } = useInputValue({
+    value,
+    initialValue,
+    onChange
+  });
   const themeTokens = useThemeTokens('Search', tokens, variant);
   const buttonTokens = useThemeTokens('SearchButton', tokens, variant);
   const getThemeTokens = useThemeTokensCallback('Search', tokens, variant);
@@ -99,26 +108,24 @@ const Search = /*#__PURE__*/forwardRef(({
 
   const handleSubmit = event => {
     if (onSubmit !== undefined) {
-      onSubmit(value, event);
+      onSubmit(currentValue, event);
     }
   };
 
-  const handleChange = (currentValue, event) => {
-    setValue(currentValue, event);
-    if (onChange !== undefined) onChange(currentValue, event);
-  };
-
   const handleClear = event => {
     setValue('', event);
     if (onClear !== undefined) onClear('', event);
-    if (onChange !== undefined) onChange('', event);
   };
 
-  const isEmpty = value === '';
+  const isEmpty = currentValue === ''; // Accessibility label should always be present and correctly localised
+
+  const a11yLabelText = accessibilityLabel || getCopy('accessibilityLabel'); // Placeholder is optional and may be unset by passing an empty string
+
+  const placeholderText = placeholder ?? a11yLabelText;
   return /*#__PURE__*/_jsxs(View, {
     style: staticStyles.container,
-    ...selectProps(rest),
-    children: [/*#__PURE__*/_jsx(TextInputBase, {
+    ...selectContainerProps(rest),
+    children: [/*#__PURE__*/_jsx(TextInputBase, { ...selectInputProps(rest),
       ref: ref,
       tokens: appearances => selectInputTokens({
         searchTokens: getThemeTokens(appearances),
@@ -126,15 +133,15 @@ const Search = /*#__PURE__*/forwardRef(({
         buttonsGapSize,
         isEmpty
       }),
-      placeholder: placeholder,
+      placeholder: placeholderText,
       placeholderTextColor: placeholderColor,
       inactive: inactive,
       enablesReturnKeyAutomatically: true,
       returnKeyType: "search",
-      value: value,
-      onChange: handleChange,
+      value: currentValue,
+      onChange: setValue,
       onSubmitEditing: handleSubmit,
-      accessibilityLabel: accessibilityLabel || getCopy('accessibilityLabel')
+      accessibilityLabel: a11yLabelText
     }), /*#__PURE__*/_jsx(View, {
       style: [staticStyles.iconsContainer, selectIconsContainerStyle(themeTokens)],
       children: /*#__PURE__*/_jsxs(StackView, {
@@ -166,7 +173,8 @@ const Search = /*#__PURE__*/forwardRef(({
   });
 });
 Search.displayName = 'Search';
-Search.propTypes = { ...selectedSystemPropTypes,
+Search.propTypes = { ...selectedContainerPropTypes,
+  ...selectedInputPropTypes,
 
   /**
    * Use this to set the initial value of the search input.
@@ -208,7 +216,7 @@ Search.propTypes = { ...selectedSystemPropTypes,
   accessibilityLabel: PropTypes.string,
 
   /**
-   * Select english or french copy for the accessible labels.
+   * 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({

package/lib-module/Skeleton/Skeleton.js

@@ -4,7 +4,7 @@ import Platform from "react-native-web/dist/exports/Platform";
 import propTypes from 'prop-types';
 import StackView from '../StackView';
 import { useThemeTokens } from '../ThemeProvider';
-import { a11yProps, getTokensPropType, selectSystemProps, useSpacingScale, variantProp, viewProps } from '../utils';
+import { a11yProps, getTokensPropType, selectSystemProps, responsiveProps, useResponsiveProp, useSpacingScale, spacingProps, variantProp, viewProps } from '../utils';
 import useSkeletonNativeAnimation from './useSkeletonNativeAnimation';
 import skeletonWebAnimation from './skeletonWebAnimation';
 import { jsx as _jsx } from "react/jsx-runtime";
@@ -45,13 +45,23 @@ const Skeleton = /*#__PURE__*/forwardRef(({
   tokens,
   variant,
   size,
+  sizeIndex = size,
+  sizePixels,
   characters,
   lines,
   shape = 'line',
   ...rest
 }, ref) => {
   const themeTokens = useThemeTokens('Skeleton', tokens, variant);
-  const skeletonHeight = useSpacingScale(size || themeTokens.size);
+  const pixels = useResponsiveProp(sizePixels);
+  const spacingScaleValue = typeof pixels === 'number' ? // Size by an exact number of pixels
+  {
+    options: {
+      size: pixels
+    }
+  } : // Size by an index on the spacing scale (getting default index from theme if none provided)
+  sizeIndex || themeTokens.size;
+  const skeletonHeight = useSpacingScale(spacingScaleValue);
   const nativeAnimation = useSkeletonNativeAnimation();
 
   const getAnimationBaseOnPlatform = () => {
@@ -109,9 +119,45 @@ Skeleton.displayName = 'Skeleton';
 Skeleton.propTypes = { ...selectedSystemPropTypes,
   tokens: getTokensPropType('Skeleton'),
   variant: variantProp.propType,
-  size: propTypes.number,
+
+  /**
+   * Sets the size of Skeleton lines or shape according to the theme's spacing scale. For example, size={1} gives the smallest non-zero theme-defined spacing size.
+   *
+   * May also accept an object with responsive viewport keys or spacing scale options - see `useSpacingScale` for details.
+   */
+  sizeIndex: spacingProps.types.spacingValue,
+
+  /**
+   * @deprecated alias for `sizeIndex`
+   */
+  size: spacingProps.types.spacingValue,
+
+  /**
+   * Sets the size of Skeleton lines or shape to an exact number of pixels. Use when it's necessary to exactly match sizes of images or other boxes.
+   *
+   * Accepts a number or an object with responsive viewport keys, e.g. { xs: 32, lg: 64 } would be 32px at xs, sm and md and 64 at lg and xl viewports.
+   */
+  sizePixels: responsiveProps.getTypeOptionallyByViewport(propTypes.number),
+
+  /**
+   * Determines the width of simulated lines of text if the Skeleton's shape is 'line' (the default shape).
+   *
+   * Only has any affect if shape is line (the default). If unset, takes a default value from the theme.
+   */
   characters: propTypes.number,
+
+  /**
+   * Determines how many Skeleton items are rendered (default 1).
+   *
+   * Recommended usage is to simulate paragraphs of text when Skeleton's shape is 'line' (the default shape).
+   *
+   * The amount of spacing between multiple lines is controlled by theme tokens.
+   */
   lines: propTypes.number,
+
+  /**
+   * Determines if the skeleton should resemble lines of text (default), a circle, or a square box with themed rounded corners.
+   */
   shape: propTypes.oneOf(['line', 'circle', 'box'])
 };
 export default Skeleton;

package/lib-module/TextInput/TextArea.js

@@ -1,12 +1,12 @@
 import React, { forwardRef, useState } from 'react';
 import Platform from "react-native-web/dist/exports/Platform";
-import { a11yProps, focusHandlerProps, getTokensPropType, inputSupportsProps, selectSystemProps, textInputHandlerProps, variantProp, viewProps } from '../utils';
+import { a11yProps, focusHandlerProps, getTokensPropType, inputSupportsProps, selectSystemProps, textInputHandlerProps, textInputProps, variantProp, viewProps } from '../utils';
 import InputSupports from '../InputSupports';
 import TextInputBase from './TextInputBase';
 import { useThemeTokens } from '../ThemeProvider';
 import textInputPropTypes from './propTypes';
 import { jsx as _jsx } from "react/jsx-runtime";
-const [selectProps, selectedSystemPropTypes] = selectSystemProps([a11yProps, focusHandlerProps, inputSupportsProps, textInputHandlerProps, viewProps]);
+const [selectProps, selectedSystemPropTypes] = selectSystemProps([a11yProps, focusHandlerProps, inputSupportsProps, textInputHandlerProps, textInputProps, viewProps]);
 /**
  * Use to collect long-form information such as product feedback or support queries.
  * Due to React Native's implementation of `TextInput` it's not possible to access the current value by passing a ref.

package/lib-module/TextInput/TextInput.js

@@ -1,11 +1,11 @@
 import React, { forwardRef } from 'react';
 import Platform from "react-native-web/dist/exports/Platform";
-import { a11yProps, focusHandlerProps, getTokensPropType, inputSupportsProps, selectSystemProps, textInputHandlerProps, variantProp, viewProps } from '../utils';
+import { a11yProps, focusHandlerProps, getTokensPropType, inputSupportsProps, selectSystemProps, textInputHandlerProps, textInputProps, variantProp, viewProps } from '../utils';
 import InputSupports from '../InputSupports';
 import TextInputBase from './TextInputBase';
 import textInputPropTypes from './propTypes';
 import { jsx as _jsx } from "react/jsx-runtime";
-const [selectProps, selectedSystemPropTypes] = selectSystemProps([a11yProps, focusHandlerProps, inputSupportsProps, textInputHandlerProps, viewProps]);
+const [selectProps, selectedSystemPropTypes] = selectSystemProps([a11yProps, focusHandlerProps, inputSupportsProps, textInputHandlerProps, textInputProps, viewProps]);
 /**
  * A basic text input component. Use in forms or individually to receive user's input.
  * Due to React Native's implementation of `TextInput` it's not possible to access the current value by passing a ref.

package/lib-module/TextInput/TextInputBase.js

@@ -5,10 +5,10 @@ import NativeTextInput from "react-native-web/dist/exports/TextInput";
 import View from "react-native-web/dist/exports/View";
 import PropTypes from 'prop-types';
 import { applyTextStyles, useThemeTokens, applyOuterBorder } from '../ThemeProvider';
-import { a11yProps, getTokensPropType, selectSystemProps, textInputHandlerProps, useInputValue, variantProp, viewProps } from '../utils';
+import { a11yProps, getTokensPropType, selectSystemProps, textInputHandlerProps, textInputProps, useInputValue, variantProp, viewProps } from '../utils';
 import { jsx as _jsx } from "react/jsx-runtime";
 import { jsxs as _jsxs } from "react/jsx-runtime";
-const [selectProps, selectedSystemPropTypes] = selectSystemProps([a11yProps, textInputHandlerProps, viewProps]);
+const [selectProps, selectedSystemPropTypes] = selectSystemProps([a11yProps, textInputHandlerProps, textInputProps, viewProps]);
 
 const selectInputStyles = ({
   backgroundColor,

package/lib-module/ToggleSwitch/ToggleSwitch.js

@@ -83,6 +83,7 @@ const selectLabelTokens = ({
 });
 
 const ToggleSwitch = /*#__PURE__*/forwardRef(({
+  copy = 'en',
   value,
   initialValue,
   onChange,
@@ -119,6 +120,7 @@ const ToggleSwitch = /*#__PURE__*/forwardRef(({
     children: [Boolean(label) && /*#__PURE__*/_jsx(View, {
       style: [selectLabelStyles(themeTokens), staticStyles.containText],
       children: /*#__PURE__*/_jsx(InputLabel, {
+        copy: copy,
         forId: inputId,
         label: label,
         tokens: selectLabelTokens(themeTokens),
@@ -167,6 +169,11 @@ const ToggleSwitch = /*#__PURE__*/forwardRef(({
 });
 ToggleSwitch.displayName = 'ToggleSwitch';
 ToggleSwitch.propTypes = { ...selectedSystemPropTypes,
+
+  /**
+   * Whether the English or French copy will be used (e.g. for accessibility labels).
+   */
+  copy: PropTypes.oneOf(['en', 'fr']),
   tokens: getTokensPropType('ToggleSwitch'),
   variant: variantProp.propType,
 

package/lib-module/ToggleSwitch/ToggleSwitchGroup.js

@@ -12,6 +12,7 @@ import { jsx as _jsx } from "react/jsx-runtime";
 const [selectProps, selectedSystemPropTypes] = selectSystemProps([a11yProps, viewProps]);
 const [selectItemProps, selectedItemPropTypes] = selectSystemProps([a11yProps, focusHandlerProps, viewProps]);
 const ToggleSwitchGroup = /*#__PURE__*/forwardRef(({
+  copy = 'en',
   variant,
   tokens,
   items = [],
@@ -88,6 +89,7 @@ const ToggleSwitchGroup = /*#__PURE__*/forwardRef(({
       ...a11yProps.getPositionInSet(items.length, index)
     };
     return /*#__PURE__*/_jsx(ToggleSwitch, {
+      copy: copy,
       id: id,
       ref: itemRef,
       onChange: handleChange,
@@ -119,6 +121,11 @@ const ToggleSwitchGroup = /*#__PURE__*/forwardRef(({
 });
 ToggleSwitchGroup.displayName = 'ToggleSwitchGroup';
 ToggleSwitchGroup.propTypes = { ...selectedSystemPropTypes,
+
+  /**
+   * Whether the English or French copy will be used (e.g. for accessibility labels).
+   */
+  copy: PropTypes.oneOf(['en', 'fr']),
   tokens: getTokensPropType('ToggleSwitchGroup'),
   variant: variantProp.propType,
 

package/lib-module/Tooltip/Tooltip.js

@@ -301,7 +301,7 @@ Tooltip.propTypes = { ...selectedSystemPropTypes,
   content: PropTypes.oneOfType([PropTypes.string, PropTypes.node]),
 
   /**
-   * Select english or french copy for the accessible label.
+   * Select English or French copy for the accessible label.
    */
   copy: PropTypes.oneOf(['en', 'fr']),
 

package/lib-module/Typography/Typography.js

@@ -5,13 +5,14 @@ import View from "react-native-web/dist/exports/View";
 import { useThemeTokens } from '../ThemeProvider';
 import { useViewport } from '../ViewportProvider';
 import { applyTextStyles } from '../ThemeProvider/utils';
-import { a11yProps, variantProp, getTokensPropType, getMaxFontMultiplier, headingTags, selectSystemProps, textTags, viewProps, getA11yPropsFromHtmlTag } from '../utils';
+import { a11yProps, variantProp, getTokensPropType, getMaxFontMultiplier, headingTags, selectSystemProps, textTags, textProps, viewProps, getA11yPropsFromHtmlTag } from '../utils';
 /**
  * @typedef {import('../utils/a11y/semantics').TextTag} TextTag
  */
 
 import { jsx as _jsx } from "react/jsx-runtime";
-const [selectProps, selectedSystemPropTypes] = selectSystemProps([a11yProps, viewProps]);
+const [selectContainerProps, selectedContainerPropTypes] = selectSystemProps([a11yProps, viewProps]);
+const [selectTextProps, selectedTextPropTypes] = selectSystemProps([textProps]);
 
 const selectTextStyles = ({
   fontWeight,
@@ -50,31 +51,32 @@ const Typography = /*#__PURE__*/forwardRef(({
   const themeTokens = useThemeTokens('Typography', tokens, variant, {
     viewport
   });
-  const textProps = {
+  const resolvedTextProps = { ...selectTextProps(rest),
     style: selectTextStyles(align ? { ...themeTokens,
       textAlign: align
     } : themeTokens),
     dataSet,
     maxFontSizeMultiplier: getMaxFontMultiplier(themeTokens)
   };
-  const selectedProps = selectProps({ ...getA11yPropsFromHtmlTag(tag, accessibilityRole),
-    ...rest
-  });
+  const containerProps = { ...getA11yPropsFromHtmlTag(tag, accessibilityRole),
+    ...selectContainerProps(rest)
+  };
   return block ? /*#__PURE__*/_jsx(View, {
     ref: ref,
-    ...selectedProps,
-    children: /*#__PURE__*/_jsx(Text, { ...textProps,
+    ...containerProps,
+    children: /*#__PURE__*/_jsx(Text, { ...resolvedTextProps,
       children: children
     })
   }) : /*#__PURE__*/_jsx(Text, {
     ref: ref,
-    ...textProps,
-    ...selectedProps,
+    ...containerProps,
+    ...resolvedTextProps,
     children: children
   });
 });
 Typography.displayName = 'Typography';
-Typography.propTypes = { ...selectedSystemPropTypes,
+Typography.propTypes = { ...selectedContainerPropTypes,
+  ...selectedTextPropTypes,
   tokens: getTokensPropType('Typography'),
   variant: variantProp.propType,
 

package/lib-module/index.js

@@ -44,5 +44,5 @@ export { default as Typography } from './Typography';
 export { default as A11yInfoProvider, useA11yInfo } from './A11yInfoProvider';
 export { default as BaseProvider } from './BaseProvider';
 export { default as ViewportProvider, useViewport, ViewportContext } from './ViewportProvider';
-export { default as ThemeProvider, useTheme, useSetTheme, useThemeTokens, getThemeTokens } from './ThemeProvider';
+export { default as ThemeProvider, useTheme, useSetTheme, useThemeTokens, getThemeTokens, applyOuterBorder, applyTextStyles, applyShadowToken } from './ThemeProvider';
 export * from './utils';

package/lib-module/utils/animation/useVerticalExpandAnimation.js

@@ -1,4 +1,4 @@
-import { useEffect, useRef } from 'react';
+import { useEffect, useRef, useState } from 'react';
 import Animated from "react-native-web/dist/exports/Animated";
 import Easing from "react-native-web/dist/exports/Easing";
 import Platform from "react-native-web/dist/exports/Platform"; // TODO: systematise animations
@@ -9,14 +9,25 @@ function useVerticalExpandAnimation({
   isExpanded,
   tokens
 }) {
+  const [isAnimating, setIsAnimating] = useState(false);
   const expandAnimatedValue = useRef(new Animated.Value(0)).current;
+  const elementRef = useRef(null);
   const {
     expandDuration,
     collapseDuration
-  } = tokens;
+  } = tokens; // Treat as animating from when expanded state changes, until animation completes
+
+  useEffect(() => setIsAnimating(true), [isExpanded]);
   useEffect(() => {
+    const onComplete = () => !isExpanded && setIsAnimating(false);
+
     if (Platform.OS === 'web') {
-      return;
+      if (!elementRef.current) return () => {}; // React Native Web does not pass `onTransitionEnd` through, must attach manually.
+      // https://github.com/necolas/react-native-web/pull/1713
+
+      const element = elementRef.current;
+      element.addEventListener('transitionend', onComplete);
+      return () => element.removeEventListener('transitionend', onComplete);
     }
 
     const animationConfig = {
@@ -25,25 +36,26 @@ function useVerticalExpandAnimation({
       toValue: isExpanded ? containerHeight : 0,
       useNativeDriver: false
     };
-    Animated.timing(expandAnimatedValue, animationConfig).start();
-  }, [isExpanded, expandAnimatedValue, containerHeight, expandDuration, collapseDuration]);
-  let containerStyles; // don't visually collapse the container until we have it measured
+    const animation = Animated.timing(expandAnimatedValue, animationConfig);
+    animation.start(onComplete);
+    return () => animation.stop();
+  }, [isExpanded, expandAnimatedValue, containerHeight, expandDuration, collapseDuration]); // Without `visibility: 'hidden', descendents are focusable on web even when collapsed
+
+  const containerStyles = !isExpanded && !isAnimating ? {
+    visibility: 'hidden'
+  } : {}; // don't visually collapse the container until we have it measured
 
   if (containerHeight !== null) {
     if (Platform.OS === 'web') {
       const transitionDuration = isExpanded ? expandDuration : collapseDuration;
-      containerStyles = {
-        transition: `height ${transitionDuration}ms ease-in-out`,
-        height: isExpanded ? containerHeight : 0
-      };
+      containerStyles.transition = `height ${transitionDuration}ms ease-in-out`;
+      containerStyles.height = isExpanded ? containerHeight : 0;
     } else {
-      containerStyles = {
-        height: expandAnimatedValue
-      };
+      containerStyles.height = expandAnimatedValue;
     }
   }
 
-  return containerStyles;
+  return [containerStyles, elementRef];
 }
 
 export default useVerticalExpandAnimation;

package/lib-module/utils/input.js

@@ -1,4 +1,8 @@
 import { useCallback, useRef, useState } from 'react';
+/**
+ * @typedef {import('react').SyntheticEvent} Event
+ */
+
 const pluralHooks = ['useMultipleInputValues'];
 
 const validateProps = ({
@@ -56,11 +60,9 @@ Consumers of this hook must be one of:
  *
  * @param {string} hookName - optional, used for tailoring error messages
  *
- * @typedef {(oldValue: string|number|null) => string|number|null} UpdaterFunction - `setValue` takes a value or
- *          a function returning a new value from the old value
  * @returns {{
  *   currentValue: string|number|null
- *   setValue: (newValue: string|number|null|UpdaterFunction) => void
+ *   setValue: (newValue: string|number|null|(oldValue: string|number) => string|number, event: Event) => void
  *   resetValue: () => void
  *   isControlled: bool
  * }}
@@ -122,12 +124,10 @@ export const useInputValue = (props = {}, hookName = 'useInputValue') => {
  *
  * @param {string} componentName - optional, used in error messages
  *
- * @typedef {(oldValues: string[]|number[]) => string[]|number[]} UpdaterFunction - `setValues` takes values or
- *          a function returning new values from old values
  * @returns {{
  *   currentValues: any
  *   resetValues: () => void
- *   setValues: (newValues: string[]|number[]|UpdaterFunction) => void
+ *   setValues: (newValues: string[]|number[]|(oldValues: string[]|number[]) => string[]|number[], event: Event) => void
  *   toggleOneValue: (value: string|number) => void
  *   unsetValues: () => void
  * }}

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

@@ -13,5 +13,7 @@ export { default as rectProp } from './rectProp';
 export { default as responsiveProps } from './responsiveProps';
 export { default as spacingProps } from './spacingProps';
 export { default as selectSystemProps } from './selectSystemProps';
+export { default as textInputProps } from './textInputProps';
+export { default as textProps } from './textProps';
 export { default as variantProp } from './variantProp';
 export { default as viewProps } from './viewProps';

package/lib-module/utils/props/inputSupportsProps.js

@@ -1,6 +1,11 @@
 import PropTypes from 'prop-types';
 export default {
   types: {
+    /**
+     * Whether the English or French copy will be used (e.g. for accessibility labels).
+     */
+    copy: PropTypes.oneOf(['en', 'fr']),
+
     /**
      * The input label.
      */
@@ -33,6 +38,7 @@ export default {
     validation: PropTypes.oneOf(['error', 'success'])
   },
   select: ({
+    copy,
     label,
     hint,
     hintPosition,
@@ -41,6 +47,7 @@ export default {
     validation
   }) => ({
     supportsProps: {
+      copy,
       label,
       hint,
       hintPosition,