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

package/lib/StackView/StackWrapBox.js

@@ -0,0 +1,90 @@
+import React from 'react';
+import PropTypes from 'prop-types';
+import { View } from 'react-native';
+import { spacingProps, a11yProps, responsiveProps, useSpacingScale, useResponsiveProp } from '../utils';
+import { useThemeTokens } from '../ThemeProvider';
+import { useViewport } from '../ViewportProvider';
+import getStackedContent from './getStackedContent';
+import { staticStyles, selectFlexStyles } from './common';
+const offsetSides = {
+  row: 'marginBottom',
+  column: 'marginRight'
+};
+const gapSides = {
+  row: 'bottom',
+  column: 'right'
+};
+const spaceSides = {
+  row: 'right',
+  column: 'bottom'
+};
+/**
+ * An alternative fallback implementation of `StackWrap` that doesn't use CSS `gap`.
+ *
+ * This is not intended to be used directly. It will automatically be used instead of StackWrap in:
+ *
+ * - Native apps (no `gap` style prop in React Native).
+ * - Older (~<=2020) browsers which don't support CSS `gap`.
+ * - Cases where the `space` between items should be different to the `gap` between wrapped rows .
+ *
+ * Unlike the cleaner and more side-effect-free CSS gap StackWrap implementation, this renders a Box (View)
+ * between the container and the stacked children, and requires a negative margin on the container.
+ */
+
+const StackWrapBox = ({
+  space = 1,
+  gap = space,
+  direction: directionProp = 'row',
+  children,
+  tokens,
+  variant,
+  ...rest
+}) => {
+  const viewport = useViewport();
+  const direction = useResponsiveProp(directionProp, 'row');
+  const themeTokens = useThemeTokens('StackView', tokens, variant, {
+    viewport
+  });
+  const flexStyles = selectFlexStyles(themeTokens);
+  const a11y = a11yProps.select({ ...rest
+  }); // Mimic CSS `gap` using box spacing on the side after a wrapped row then offsetting it on the last row.
+
+  const gapSize = useSpacingScale(gap);
+  const offsetStyle = {
+    [offsetSides[direction]]: -1 * gapSize
+  };
+  const boxProps = {
+    [gapSides[direction]]: gap,
+    [spaceSides[direction]]: space
+  };
+  const content = getStackedContent(children, {
+    direction,
+    space: 0,
+    box: boxProps
+  });
+  return /*#__PURE__*/React.createElement(View, Object.assign({}, a11y, {
+    style: [flexStyles, staticStyles.wrap, staticStyles[direction], offsetStyle]
+  }), content);
+};
+
+StackWrapBox.propTypes = { ...a11yProps.propTypes,
+
+  /**
+   * Sets the `flexDirection` of the container
+   */
+  direction: responsiveProps.getTypeOptionallyByViewport(PropTypes.oneOf(['column', 'row', 'row-reverse', 'column-reverse'])),
+
+  /**
+   * The size of the spacer according to the theme's spacing scale.
+   * Either a number corresponding to a position on the theme's spacing scale (1 is smallest, 2 is second smallest, etc),
+   * or, a SpacingObject with viewport keys and options (see `useSpacingScale` for details).
+   */
+  space: spacingProps.types.spacingValue,
+
+  /**
+   * A StackWrap may take any children, but will have no effect if it is only passed one child or is passed children
+   * wrapped in a component. If necessary, children may be wrapped in one React Fragment.
+   */
+  children: PropTypes.node
+};
+export default StackWrapBox;

package/lib/StackView/StackWrapGap.js

@@ -0,0 +1,50 @@
+import React from 'react';
+import { View } from 'react-native';
+import StackWrapBox from './StackWrapBox';
+import { a11yProps, useSpacingScale, useResponsiveProp } from '../utils';
+import { useThemeTokens } from '../ThemeProvider';
+import { useViewport } from '../ViewportProvider';
+import getStackedContent from './getStackedContent';
+import { staticStyles, selectFlexStyles } from './common';
+/**
+ * The primary implementation of StackWrap.
+ *
+ * This is not intended to be used directly. It will automatically be used instead of StackWrap if:
+ *
+ * - On web, and,
+ * - On a browser that supports CSS `gap` (most browser versions from 2020 onwards), and,
+ * - The `space` between items is the same as the `gap` between wrapped rows (this is the
+ *   default if `gap` prop is undefined)
+ */
+
+const StackWrapGap = ({
+  space = 1,
+  tokens,
+  variant,
+  direction: directionProp = 'row',
+  children,
+  ...rest
+}) => {
+  const viewport = useViewport();
+  const direction = useResponsiveProp(directionProp, 'row');
+  const themeTokens = useThemeTokens('StackView', tokens, variant, {
+    viewport
+  });
+  const flexStyles = selectFlexStyles(themeTokens);
+  const a11y = a11yProps.select({ ...rest
+  });
+  const size = useSpacingScale(space);
+  const gapStyle = {
+    gap: size
+  };
+  const content = getStackedContent(children, {
+    direction,
+    space: 0
+  });
+  return /*#__PURE__*/React.createElement(View, Object.assign({}, a11y, {
+    style: [flexStyles, staticStyles.wrap, staticStyles[direction], gapStyle]
+  }), content);
+};
+
+StackWrapGap.propTypes = StackWrapBox.propTypes;
+export default StackWrapGap;

package/lib/StackView/common.js

@@ -0,0 +1,30 @@
+import { StyleSheet } from 'react-native';
+export const selectFlexStyles = ({
+  alignItems,
+  justifyContent,
+  flexGrow
+}) => ({
+  alignItems,
+  justifyContent,
+  flexGrow
+});
+export const staticStyles = StyleSheet.create({
+  wrap: {
+    flexShrink: 1,
+    flexWrap: 'wrap'
+  },
+  row: {
+    flexDirection: 'row'
+  },
+  'row-reverse': {
+    flexDirection: 'row-reverse'
+  },
+  column: {
+    // This is the React Native View default, but also it's very fundamental to the behaviour,
+    // so make it explicit and allow it to be tested for.
+    flexDirection: 'column'
+  },
+  'column-reverse': {
+    flexDirection: 'column-reverse'
+  }
+});

package/lib/StackView/getStackedContent.js

@@ -0,0 +1,111 @@
+import React, { Children, Fragment } from 'react';
+import Box from '../Box';
+import Divider from '../Divider';
+import Spacer from '../Spacer';
+/**
+ * @typedef {import('react').ReactChildren} ReactChildren
+ * @typedef {import('react').ReactElement} ReactElement
+ * @typedef {import('../utils/propTypes.js').SpacingValue} SpacingValue
+ */
+
+/**
+ * Takes valid React Children and inserts a specified amount of space between each valid (not nullish) top
+ * level element, according to the provided `options`.
+ *
+ * Returns an array of the original elements plus inserted spacing elements.
+ * This array of elements is keyed and may be used as a component's `children` without mapping.
+ *
+ * @param {ReactChildren} children
+ * @param {object} [options] -
+ *  - `space`: amount of space to insert using the theme spacing scale (see `useSpacingScale`)
+ *  - `direction`: if 'row' or 'row-reverse', applies space horizontally, if 'column' or 'column-reverse', applies space vertically
+ *  - `box`: if truthy, wraps each valid child in a Box component; if an object, passes it to Box as props
+ *  - `divider`: if truthy, inserts Divider components; if an object, passes it to Divider as props
+ * @param {SpacingValue} [options.space]
+ * @param {boolean | object} [options.divider]
+ * @param {"row" | "column" | "row-reverse" | "column-reverse"} [options.direction]
+ * @returns {ReactElement[]}
+ */
+
+const getStackedContent = (children, {
+  divider,
+  space,
+  direction = 'column',
+  box
+}) => {
+  const boxProps = box && typeof box === 'object' ? box : {
+    space
+  };
+  const dividerProps = divider && typeof divider === 'object' ? divider : {}; // Avoid surprises if children contains comments, nulls, or is a variable wrapped as a fragment
+
+  const validChildren = Children.toArray(unpackFragment(children)).filter(Boolean);
+  const content = validChildren.reduce((newChildren, child, index) => {
+    const boxID = `Stack-Box-${index}`;
+    const item = box ?
+    /*#__PURE__*/
+    // If wrapped in Box, that Box needs a key.
+    // If possible, use an existing content key; use an index-based key only if necessary.
+    React.createElement(Box, Object.assign({}, boxProps, {
+      key: child.key || boxID,
+      testID: boxID
+    }), child) : child;
+    if (!index || !space && !divider) return [...newChildren, item];
+    const testID = `Stack-${divider ? 'Divider' : 'Spacer'}-${index}`;
+    const commonProps = {
+      testID,
+      key: testID,
+      space
+    };
+    const separator = divider ? /*#__PURE__*/React.createElement(Divider, Object.assign({
+      vertical: direction.startsWith('row')
+    }, dividerProps, commonProps)) : /*#__PURE__*/React.createElement(Spacer, Object.assign({
+      direction: direction.startsWith('row') ? 'row' : 'column'
+    }, commonProps));
+    return [...newChildren, separator, item];
+  }, []);
+  return content;
+};
+/**
+ * Unpacks top-level fragments, so that common compositional patterns such as the following examples
+ * can be iterated as flat siblings (as if they were `<Child1 /><Child2 /><Child3 />`):
+ *
+ * - Setting `children` as a property wrapped in a fragment:
+ *
+ * ```jsx
+ * args.children = <><Child1 /><Child2 /><Child3 /></>
+ * ```
+ *
+ * - Defining `children` as a variable wrapped in a fragment:
+ *
+ * ```jsx
+ * const content = <><Child1 /><Child2 /><Child3 /></>
+ * if (someCondition) return <SomeWrapper>{content}</SomeWrapper>
+ * ```
+ *
+ * - Using fragments at the top level of a JSX block for conditional rendering:
+ *
+ * ```jsx
+ * <Child1 />
+ * {someCondition && (
+ *   <>
+ *     <Child2 />
+ *     <Child3 />
+ *   </>
+ * )}
+ * ```
+ *
+ * @param {ReactChildren} child
+ * @returns {ReactChildren}
+ */
+
+
+const unpackFragment = child => {
+  // If this level is a set of top-level siblings rather than one child, check each in turn
+  if (Children.count(child) > 1) return Children.map(child, unpackFragment); // When a fragment is found, unpack its children to the top level and check them
+
+  if (child?.type === Fragment) return unpackFragment(child.props?.children); // Stop unpacking as soon as any non-fragment child is found
+
+  return child;
+};
+
+export default getStackedContent;

package/lib/StackView/index.js

@@ -0,0 +1,5 @@
+import StackView from './StackView';
+import StackWrap from './StackWrap';
+export default StackView;
+export { StackWrap };
+export { default as getStackedContent } from './getStackedContent';

package/lib/Tags/Tags.js

@@ -0,0 +1,217 @@
+import React from 'react';
+import PropTypes from 'prop-types';
+import { Platform, Text, View } from 'react-native';
+import ButtonBase from '../Button/ButtonBase';
+import { StackWrap, getStackedContent } from '../StackView';
+import { useViewport } from '../ViewportProvider';
+import { useThemeTokens, useThemeTokensCallback } from '../ThemeProvider';
+import { a11yProps, pressProps, variantProp, getTokensPropType, selectTokens } from '../utils/propTypes';
+import { useMultipleInputValues } from '../utils/input';
+import { getPressHandlersWithArgs } from '../utils/pressability';
+
+const selectIconTextTokens = ({
+  icon,
+  iconPosition,
+  iconSpace,
+  iconSize,
+  iconColor,
+  iconBackground,
+  iconBorderRadius,
+  iconAlignSelf,
+  iconPadding,
+  iconTranslateX,
+  iconTranslateY
+}) => ({
+  icon,
+  iconPosition,
+  iconSpace,
+  iconWrapperStyle: {
+    backgroundColor: iconBackground,
+    borderRadius: iconBorderRadius,
+    alignSelf: iconAlignSelf,
+    padding: iconPadding,
+    ...Platform.select({
+      // TODO: https://github.com/telus/universal-design-system/issues/487
+      web: {
+        transition: 'color 200ms, background 200ms'
+      }
+    })
+  },
+  iconTokens: {
+    size: iconSize,
+    color: iconColor,
+    translateX: iconTranslateX,
+    translateY: iconTranslateY
+  }
+});
+
+const Tags = ({
+  variant,
+  tokens,
+  items = [],
+  values,
+  initialValues,
+  maxValues,
+  onChange,
+  readOnly = false,
+  inactive = false,
+  accessibilityRole = Platform.select({
+    web: 'group',
+    default: 'none'
+  }),
+  ...rest
+}) => {
+  const viewport = useViewport();
+  const themeTokens = useThemeTokens('Tags', tokens, variant, {
+    viewport
+  });
+  const stackTokens = selectTokens('StackView', themeTokens);
+  const {
+    direction,
+    space
+  } = themeTokens;
+  const getItemTokens = useThemeTokensCallback('TagsItem', tokens, variant);
+
+  const getButtonTokens = buttonState => selectTokens('Button', getItemTokens(buttonState));
+
+  const {
+    currentValues,
+    toggleOneValue
+  } = useMultipleInputValues({
+    initialValues,
+    values,
+    maxValues,
+    onChange,
+    readOnly
+  });
+  const a11y = a11yProps.select({
+    accessibilityRole,
+    ...rest
+  });
+  const itemA11yRole = 'checkbox';
+  return /*#__PURE__*/React.createElement(StackWrap, Object.assign({}, a11y, {
+    space: space,
+    direction: direction,
+    tokens: stackTokens
+  }), items.map(({
+    label,
+    id = label,
+    accessibilityLabel
+  }, index) => {
+    const isSelected = currentValues.includes(id); // Pass an object of relevant component state as first argument for any passed-in press handlers
+
+    const pressHandlers = getPressHandlersWithArgs(rest, [{
+      id,
+      label,
+      currentValues
+    }]);
+
+    const handlePress = () => {
+      if (pressHandlers.onPress) pressHandlers.onPress();
+      toggleOneValue(id);
+    };
+
+    const itemA11y = {
+      accessibilityState: {
+        checked: isSelected
+      },
+      accessibilityRole: itemA11yRole,
+      accessibilityLabel,
+      ...a11yProps.getPositionInSet(items.length, index)
+    };
+    return /*#__PURE__*/React.createElement(ButtonBase, Object.assign({
+      key: id
+    }, pressHandlers, {
+      onPress: handlePress,
+      tokens: getButtonTokens,
+      selected: isSelected,
+      inactive: inactive
+    }, itemA11y), ({
+      textStyles,
+      ...buttonState
+    }) => {
+      // TODO: once Icon/IconButton designs are stable, see if this sort of styling around
+      // an icon should go in Icon itself, or possibly via an IconText token set. Related issues:
+      // - Icon: https://github.com/telus/universal-design-system/issues/327
+      // - IconButton: https://github.com/telus/universal-design-system/issues/281
+      // - Token sets: https://github.com/telus/universal-design-system/issues/782
+      const itemTokens = getItemTokens(buttonState);
+      const {
+        iconTokens,
+        iconPosition,
+        iconSpace,
+        iconWrapperStyle,
+        icon: IconComponent
+      } = selectIconTextTokens(itemTokens);
+      const iconContent = IconComponent ? /*#__PURE__*/React.createElement(View, {
+        style: iconWrapperStyle
+      }, /*#__PURE__*/React.createElement(IconComponent, {
+        tokens: iconTokens
+      })) : null;
+      const textContent = /*#__PURE__*/React.createElement(Text, {
+        style: textStyles
+      }, label);
+      return getStackedContent(iconPosition === 'left' ? [iconContent, textContent] : [textContent, iconContent], {
+        space: iconSpace,
+        direction: 'row'
+      });
+    });
+  }));
+};
+
+Tags.propTypes = { ...a11yProps.propTypes,
+  ...pressProps.propTypes,
+  tokens: getTokensPropType('Tags'),
+  variant: variantProp.propType,
+
+  /**
+   * If provided, sets a maximum number of items a user may select at once.
+   */
+  maxValues: PropTypes.number,
+
+  /**
+   * The options a user may select
+   */
+  items: PropTypes.arrayOf(PropTypes.shape({
+    /**
+     * The text displayed to the user in the button, describing this option,
+     * passed to the button as its child.
+     */
+    label: PropTypes.string.isRequired,
+
+    /**
+     * An optional accessibility label may be passed to ButtonGroup Buttons
+     * which is applied as normal for a React Native accessibilityLabel prop.
+     */
+    accessibilityLabel: PropTypes.string,
+
+    /**
+     * An optional unique string may be provided to identify this option,
+     * which will be used in code and passed to any onChange function.
+     * If not provided, the label is used.
+     */
+    id: PropTypes.string
+  })),
+
+  /**
+   * If provided, this function is called when the current selection is changed
+   * and is passed an array of the `id`s of all currently selected `items`.
+   */
+  onChange: PropTypes.func,
+
+  /**
+   * If the selected item(s) in the button group are to be controlled externally by
+   * a parent component, pass an array of strings as well as an `onChange` handler.
+   * Passing an array for "values" makes the ButtonGroup a "controlled" component that
+   * expects its state to be handled via `onChange` and so doesn't handle it itself.
+   */
+  values: PropTypes.arrayOf(PropTypes.string),
+
+  /**
+   * If `values` is not passed, making the ButtonGroup an "uncontrolled" component
+   * managing its own selected state, a default set of selections may be provided.
+   * Changing the `initialValues` does not change the user's selections.
+   */
+  initialValues: PropTypes.arrayOf(PropTypes.string)
+};
+export default Tags;

package/lib/Tags/index.js

@@ -0,0 +1,2 @@
+import Tags from './Tags';
+export default Tags;

package/lib/TextInput/TextArea.js

@@ -0,0 +1,82 @@
+import React, { useState } from 'react';
+import { Platform } from 'react-native';
+import { getTokensPropType, variantProp } from '../utils';
+import InputSupports from '../InputSupports';
+import TextInputBase from './TextInputBase';
+import { useThemeTokens } from '../ThemeProvider';
+import inputSupportProps from '../InputSupports/propTypes';
+import textInputPropTypes from './propTypes';
+/**
+ * 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.
+ * The `TextArea` height will automatically increase when new lines are added - this behavior can be limited within the theme.
+ *
+ * ## Controlled component
+ * If it is required that the state of the `TextArea` be controlled by the application or other external methods,
+ * `value` and `onChange` props must be passed to the `TextArea`.
+ * If the `TextArea` value should not be changed by user input, a `readOnly` prop must be provided.
+ *
+ * ## Uncontrolled component
+ * If it is not necessary to control the `TextArea` state, you can create one without a value prop.
+ * In this case its value can be accessed within the `onChange` callback.
+ *
+ * ## Getting feedback for entered values
+ * Use the `feedback` prop to give the user feedback regarding their input.
+ * You can affirm that the user's input was correct, or highlight errors that must be corrected, using the `validation` prop.
+ * Keep feedback text as brief as possible, should be limited to text and links.
+ *
+ * ## Supplying a hint
+ * Use the `hint` prop to succinctly clarify attributes of the expected input data, such as the expected format,
+ * or an indicator that the field is optional.
+ * It is a more usable and accessible option than the HTML `placeholder` attribute.
+ */
+
+function TextArea({
+  tokens,
+  variant = {},
+  ...remainingProps
+}) {
+  const themeTokens = useThemeTokens('TextArea', tokens, variant);
+  const [inputHeight, setInputHeight] = useState(); // adjust the text area's height as new lines are added to the content
+
+  const onHeightChange = ({
+    nativeEvent: {
+      contentSize: {
+        height
+      }
+    }
+  }) => {
+    // on native this is happens out of the box
+    if (Platform.OS === 'web') {
+      setInputHeight(height);
+    }
+  };
+
+  const {
+    props: supportsProps,
+    rest
+  } = inputSupportProps.select(remainingProps);
+  const inputProps = { ...rest,
+    variant: { ...variant,
+      validation: supportsProps.validation
+    },
+    multiline: true,
+    onContentSizeChange: onHeightChange,
+    height: inputHeight,
+    tokens: themeTokens
+  };
+  return /*#__PURE__*/React.createElement(InputSupports, supportsProps, ({
+    a11yProps,
+    inputId
+  }) => /*#__PURE__*/React.createElement(TextInputBase, Object.assign({}, inputProps, a11yProps, {
+    nativeID: inputId
+  })));
+}
+
+TextArea.propTypes = { ...inputSupportProps.types,
+  ...textInputPropTypes,
+  tokens: getTokensPropType('TextArea', 'TextInput'),
+  // TODO: support both TextArea and TextInput tokens
+  variant: variantProp.propType
+};
+export default TextArea;

package/lib/TextInput/TextInput.js

@@ -0,0 +1,54 @@
+import React from 'react';
+import { getTokensPropType, variantProp } from '../utils';
+import InputSupports from '../InputSupports';
+import TextInputBase from './TextInputBase';
+import inputSupportProps from '../InputSupports/propTypes';
+import textInputPropTypes from './propTypes';
+/**
+ * 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.
+ *
+ * ## Controlled component
+ * If it is required that the state of the `TextInput` be controlled by the application or other external methods,
+ * `value` and `onChange` props must be passed to the `TextInput`.
+ * If the `TextInput` value should not be changed by user input, a `readOnly` prop must be provided.
+ *
+ * ## Uncontrolled component
+ * If it is not necessary to control the `TextInput` state, you can create one without a value prop.
+ * In this case its value can be accessed within the `onChange` callback.
+ *
+ * NOTE: In order to support more advanced usages all additional props will be passed down to the React Native's
+ * `TextInput` component. See <a href="https://reactnative.dev/docs/textinput" target="_blank">React Native documentation</a> for
+ * supported props and <a href="https://reactnative.dev/docs/textinput" target="_blank">React Native Web documentation</a> for
+ * their implementation on the web.
+ */
+
+function TextInput({
+  tokens,
+  variant = {},
+  ...remainingProps
+}) {
+  const {
+    props: supportsProps,
+    rest
+  } = inputSupportProps.select(remainingProps);
+  const inputProps = { ...rest,
+    tokens,
+    variant: { ...variant,
+      validation: supportsProps.validation
+    }
+  };
+  return /*#__PURE__*/React.createElement(InputSupports, supportsProps, ({
+    a11yProps,
+    inputId
+  }) => /*#__PURE__*/React.createElement(TextInputBase, Object.assign({}, inputProps, a11yProps, {
+    nativeID: inputId
+  })));
+}
+
+TextInput.propTypes = { ...inputSupportProps.types,
+  ...textInputPropTypes,
+  tokens: getTokensPropType('TextInput'),
+  variant: variantProp.propType
+};
+export default TextInput;