@telus-uds/components-base 1.8.3 → 1.8.4

package/lib-module/Button/ButtonBase.js

@@ -0,0 +1,271 @@
+import React, { forwardRef } from 'react';
+import PropTypes from 'prop-types';
+import Pressable from "react-native-web/dist/exports/Pressable";
+import View from "react-native-web/dist/exports/View";
+import StyleSheet from "react-native-web/dist/exports/StyleSheet";
+import Platform from "react-native-web/dist/exports/Platform";
+import { applyTextStyles, applyShadowToken, applyOuterBorder } from '../ThemeProvider/utils';
+import buttonPropTypes from './propTypes';
+import { a11yProps, clickProps, focusHandlerProps, getCursorStyle, linkProps, resolvePressableState, resolvePressableTokens, selectSystemProps, viewProps, wrapStringsInText, withLinkRouter } from '../utils';
+import { jsx as _jsx } from "react/jsx-runtime";
+const [selectProps, selectedSystemPropTypes] = selectSystemProps([a11yProps, focusHandlerProps, linkProps, viewProps]);
+
+const getOuterBorderOffset = _ref => {
+  let {
+    outerBorderGap = 0,
+    outerBorderWidth = 0
+  } = _ref;
+  return outerBorderGap + outerBorderWidth;
+};
+
+const selectOuterContainerStyles = _ref2 => {
+  let {
+    alignSelf,
+    opacity,
+    outerBorderColor,
+    outerBorderWidth,
+    outerBorderGap,
+    borderRadius,
+    outerBackgroundColor
+  } = _ref2;
+  return {
+    alignSelf,
+    backgroundColor: outerBackgroundColor,
+    opacity,
+    ...applyOuterBorder({
+      outerBorderGap,
+      outerBorderWidth,
+      outerBorderColor,
+      borderRadius
+    })
+  };
+};
+
+const selectOuterWidthStyles = _ref3 => {
+  let {
+    outerBorderGap,
+    outerBorderWidth,
+    width
+  } = _ref3;
+  // The inner container's bounding box is the bounding box of the button overall
+  // so this many device pixels will sit outside of the overall bounding box
+  const outerBorderOffset = getOuterBorderOffset({
+    outerBorderGap,
+    outerBorderWidth
+  });
+  const widthStyles = {};
+
+  if (!width) {
+    return { ...widthStyles,
+      // Wrap content, stopping a flex parent's default align-items: stretch stretching focus ring beyond content
+      ...Platform.select({
+        // width: fit-content isn't supported on Firefox; can't cascade props like CSS `width: fit-content; width: --moz-fit-content;`
+        web: {
+          display: 'inline-flex'
+        }
+      })
+    };
+  } // Apply width tokens: number === pixels, string === explicit units e.g. %
+
+
+  if (typeof width === 'number') {
+    widthStyles.width = width + outerBorderOffset * 2;
+    return widthStyles;
+  } // Ensure the negative margin doesn't make element off-centre
+
+
+  if (Platform.OS === 'web') {
+    widthStyles.width = "calc(".concat(width, " + ").concat(outerBorderOffset * 2, "px)");
+    return widthStyles;
+  } // Can't use calc() on native but (unlike on web) flexGrow fills the container width here
+
+
+  if (width === '100%') {
+    widthStyles.flexGrow = 1;
+    return widthStyles;
+  } // Slight offset not such a concern if % width < 100%, as the button isn't centered anyway.
+  // If centering support is added (e.g. alignSelf: center), set marginHorizontal 0 when centered.
+
+
+  widthStyles.width = width;
+  return widthStyles;
+};
+
+const selectInnerContainerStyles = _ref4 => {
+  let {
+    backgroundColor,
+    paddingLeft,
+    paddingRight,
+    paddingTop,
+    paddingBottom,
+    shadow,
+    borderWidth,
+    minWidth
+  } = _ref4;
+
+  // Subtract border width from padding so overall button width/height doesn't
+  // jump around if the border width changes (avoiding NaN and negative padding)
+  const offsetBorder = value => typeof value === 'number' && typeof borderWidth === 'number' ? Math.max(0, value - borderWidth) : value;
+
+  return {
+    paddingLeft: offsetBorder(paddingLeft),
+    paddingRight: offsetBorder(paddingRight),
+    paddingTop: offsetBorder(paddingTop),
+    paddingBottom: offsetBorder(paddingBottom),
+    backgroundColor,
+    minWidth,
+    ...applyShadowToken(shadow)
+  };
+};
+
+const selectBorderStyles = _ref5 => {
+  let {
+    borderColor,
+    borderWidth,
+    borderRadius
+  } = _ref5;
+  return {
+    borderColor,
+    borderWidth,
+    borderRadius
+  };
+};
+
+const selectTextStyles = _ref6 => {
+  let {
+    fontSize,
+    color,
+    lineHeight,
+    fontName,
+    fontWeight,
+    textAlign
+  } = _ref6;
+  return applyTextStyles({
+    fontSize,
+    color,
+    lineHeight,
+    fontName,
+    fontWeight,
+    textAlign
+  });
+};
+
+const selectWebOnlyStyles = (inactive, themeTokens, _ref7) => {
+  let {
+    accessibilityRole
+  } = _ref7;
+  return Platform.select({
+    web: {
+      // if it would overflow the container, wraps instead
+      maxWidth: "calc(100% + ".concat(getOuterBorderOffset(themeTokens) * 2, "px)"),
+      outline: 'none',
+      // removes the default browser :focus outline
+      ...getCursorStyle(inactive, accessibilityRole)
+    },
+    default: {}
+  });
+};
+
+const ButtonBase = /*#__PURE__*/forwardRef((_ref8, ref) => {
+  let {
+    id,
+    href,
+    hrefAttrs,
+    children,
+    tokens = {},
+    disabled = false,
+    // alias for inactive
+    inactive = disabled,
+    selected = false,
+    ...rawRest
+  } = _ref8;
+  const {
+    onPress,
+    ...rest
+  } = clickProps.toPressProps(rawRest);
+  const extraButtonState = {
+    inactive,
+    selected
+  };
+
+  const resolveButtonTokens = pressableState => resolvePressableTokens(tokens, pressableState, extraButtonState);
+
+  const systemProps = selectProps(rest);
+
+  const getPressableStyle = pressableState => {
+    const themeTokens = resolveButtonTokens(pressableState);
+    return [staticStyles.row, selectWebOnlyStyles(inactive, themeTokens, systemProps), selectOuterContainerStyles(themeTokens), selectOuterWidthStyles(themeTokens)];
+  };
+
+  return /*#__PURE__*/_jsx(Pressable, {
+    ref: ref,
+    href: href,
+    onPress: linkProps.handleHref({
+      href,
+      onPress
+    }),
+    style: getPressableStyle,
+    disabled: inactive,
+    hrefAttrs: hrefAttrs,
+    ...systemProps,
+    children: pressableState => {
+      const themeTokens = resolveButtonTokens(pressableState);
+      const containerStyles = selectInnerContainerStyles(themeTokens);
+      const borderStyles = selectBorderStyles(themeTokens);
+      const textStyles = [selectTextStyles(themeTokens), staticStyles.text]; // If the container has a width set, fill it instead of sizing from content.
+      // If in future we support text alignments other than center, add here.
+
+      const stretchStyles = themeTokens.width ? staticStyles.stretch : staticStyles.align;
+      return /*#__PURE__*/_jsx(View, {
+        id: id,
+        style: [containerStyles, borderStyles, stretchStyles, staticStyles.row, Platform.select({
+          web: {
+            maxWidth: '100%',
+            // ensure overflowing content wraps
+            // TODO: https://github.com/telus/universal-design-system/issues/487
+            transition: 'background-color 200ms, border-color 200ms'
+          }
+        })],
+        children: wrapStringsInText(typeof children === 'function' ? children({ ...resolvePressableState(pressableState, extraButtonState),
+          textStyles
+        }) : children, {
+          style: textStyles
+        })
+      });
+    }
+  });
+});
+ButtonBase.displayName = 'ButtonBase';
+ButtonBase.propTypes = {
+  id: PropTypes.string,
+  ...selectedSystemPropTypes,
+  ...buttonPropTypes
+};
+ButtonBase.defaultProps = {
+  id: undefined
+};
+const staticStyles = StyleSheet.create({
+  row: {
+    // Apply all button alignment horizontally; no vertical stacking within a button
+    flexDirection: 'row'
+  },
+  text: {
+    flexGrow: 1,
+    // On native but not web, flexShrink here wraps text prematurely
+    ...Platform.select({
+      // TODO: https://github.com/telus/universal-design-system/issues/487
+      web: {
+        transition: 'color 200ms'
+      }
+    })
+  },
+  align: {
+    alignItems: 'center'
+  },
+  stretch: {
+    flex: 1,
+    alignItems: 'center',
+    justifyContent: 'center'
+  }
+});
+export default withLinkRouter(ButtonBase);

package/lib-module/Button/ButtonGroup.js

@@ -0,0 +1,247 @@
+import React, { forwardRef } from 'react';
+import PropTypes from 'prop-types';
+import ABBPropTypes from 'airbnb-prop-types';
+import Platform from "react-native-web/dist/exports/Platform";
+import ButtonBase from './ButtonBase';
+import { StackWrap } from '../StackView';
+import Fieldset from '../Fieldset';
+import { useViewport } from '../ViewportProvider';
+import { useThemeTokens, useThemeTokensCallback } from '../ThemeProvider';
+import { a11yProps, containUniqueFields, focusHandlerProps, pressProps, getTokensPropType, selectSystemProps, selectTokens, useMultipleInputValues, variantProp, viewProps } from '../utils';
+import { getPressHandlersWithArgs } from '../utils/pressability';
+import { jsx as _jsx } from "react/jsx-runtime";
+const [selectProps, selectedSystemPropTypes] = selectSystemProps([a11yProps, viewProps]);
+const [selectItemProps, selectedItemPropTypes] = selectSystemProps([a11yProps, focusHandlerProps, pressProps, viewProps]);
+const ButtonGroup = /*#__PURE__*/forwardRef((_ref, ref) => {
+  let {
+    variant,
+    tokens,
+    items = [],
+    values,
+    initialValues,
+    maxValues = 1,
+    onChange,
+    readOnly = false,
+    inactive = false,
+    legend,
+    tooltip,
+    hint,
+    validation,
+    feedback,
+    name: inputGroupName,
+    copy,
+    accessibilityRole = maxValues === 1 ? 'radiogroup' // radiogroup is cross-platform; only web aria has generic groups
+    : Platform.select({
+      web: 'group',
+      default: 'none'
+    }),
+    ...rest
+  } = _ref;
+  const viewport = useViewport();
+  const themeTokens = useThemeTokens('ButtonGroup', tokens, variant, {
+    viewport
+  });
+  const stackTokens = selectTokens('StackView', themeTokens);
+  const {
+    direction,
+    space,
+    fieldSpace
+  } = themeTokens;
+  const getButtonTokens = useThemeTokensCallback('ButtonGroupItem', tokens, variant);
+  const {
+    currentValues,
+    toggleOneValue
+  } = useMultipleInputValues({
+    initialValues,
+    values,
+    maxValues,
+    onChange,
+    readOnly
+  });
+  const systemProps = selectProps({
+    accessibilityRole,
+    ...rest
+  });
+  const itemA11yRole = systemProps.accessibilityRole === 'radiogroup' ? 'radio' : 'checkbox';
+  const uniqueFields = ['id', 'label'];
+
+  if (!containUniqueFields(items, uniqueFields)) {
+    throw new Error("ButtonGroup items must have unique ".concat(uniqueFields.join(', ')));
+  } // Some web screenreaders e.g. MacOS Voiceover don't handle radiogroups properly unless radio is direct child of radiogroup
+
+
+  const innerRole = Platform.OS === 'web' && accessibilityRole === 'radiogroup' ? accessibilityRole : undefined;
+  return /*#__PURE__*/_jsx(Fieldset, { ...systemProps,
+    ref: ref,
+    name: inputGroupName,
+    legend: legend,
+    tooltip: tooltip,
+    hint: hint,
+    space: fieldSpace,
+    feedback: feedback,
+    readOnly: readOnly,
+    inactive: inactive,
+    validation: validation,
+    accessibilityRole: accessibilityRole,
+    ...selectProps(rest),
+    children: /*#__PURE__*/_jsx(StackWrap, {
+      accessibilityRole: innerRole,
+      space: space,
+      direction: direction,
+      tokens: stackTokens,
+      ref: ref,
+      children: items.map((_ref2, index) => {
+        let {
+          label,
+          id = label,
+          accessibilityLabel,
+          ref: itemRef,
+          ...itemRest
+        } = _ref2;
+        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 = event => {
+          if (pressHandlers.onPress) pressHandlers.onPress(event);
+          toggleOneValue(id, event);
+        };
+
+        const itemA11y = {
+          accessibilityState: {
+            checked: isSelected
+          },
+          accessibilityRole: itemA11yRole,
+          accessibilityLabel,
+          ...a11yProps.getPositionInSet(items.length, index)
+        }; // Ensure button is direct child of group as MacOS voiceover only applies "X of Y" to
+        // "radio" if it's a direct child of "radiogroup", even if aria-posinset etc exists
+
+        return /*#__PURE__*/_jsx(ButtonBase, {
+          ref: itemRef,
+          ...pressHandlers,
+          onPress: handlePress,
+          tokens: getButtonTokens,
+          selected: isSelected,
+          inactive: inactive,
+          ...itemA11y,
+          ...selectItemProps(itemRest),
+          children: label
+        }, id);
+      })
+    })
+  });
+});
+ButtonGroup.displayName = 'ButtonGroup';
+ButtonGroup.propTypes = { ...selectedSystemPropTypes,
+  tokens: getTokensPropType('ButtonGroup'),
+  variant: variantProp.propType,
+
+  /**
+   * The maximum number of items a user may select at once. Defaults to 1 and behaves
+   * like radio buttons. To have no limit and allow any number of selections, pass `null`.
+   */
+  maxValues: PropTypes.number,
+
+  /**
+   * The options a user may select
+   */
+  items: PropTypes.arrayOf(PropTypes.shape({ ...selectedItemPropTypes,
+
+    /**
+     * 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,
+
+    /**
+     * An optional ref for one individual button in the ButtonGroup
+     */
+    ref: ABBPropTypes.ref()
+  })),
+
+  /**
+   * 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),
+
+  /**
+   * Main text used to describe this group, used in Fieldset's Legend element.
+   */
+  legend: PropTypes.string,
+
+  /**
+   * Optional additional text giving more detail to help a user make a choice.
+   */
+  hint: PropTypes.string,
+
+  /**
+   * Optional tooltip text content to include alongside the legend and hint.
+   */
+  tooltip: PropTypes.string,
+
+  /**
+   * Current validation status of the group, passed to the feedback element if there is one.
+   */
+  validation: PropTypes.oneOf(['error', 'success']),
+
+  /**
+   * If provided, a Feedback element is rendered containing this text.
+   */
+  feedback: PropTypes.string,
+
+  /**
+   * If true, the buttons cannot be selected by the user and simply show their current state.
+   */
+  readOnly: PropTypes.bool,
+
+  /**
+   * If true, the buttons cannot be interacted with, elements are set as `disabled` and if the
+   * theme supports `inactive` appearances rules, these are applied.
+   */
+  inactive: PropTypes.bool,
+
+  /**
+   * On Web, this is passed to the `name` attribute of the fieldset.
+   */
+  name: PropTypes.string,
+
+  /**
+   * Sets the language of microcopy in subcomponents (e.g. Tooltip's default accessibility label).
+   */
+  copy: PropTypes.oneOf(['en', 'fr'])
+};
+export default ButtonGroup;

package/lib-module/Button/ButtonLink.js

@@ -0,0 +1,40 @@
+import React, { forwardRef } from 'react';
+import ButtonBase from './ButtonBase';
+import buttonPropTypes, { textAndA11yText } from './propTypes';
+import { a11yProps, hrefAttrsProp, linkProps } from '../utils/props';
+import { useThemeTokensCallback } from '../ThemeProvider';
+/**
+ * `ButtonLink` is a component with the semantics and behaviour of a link, but with the visual appearance of a button.
+ * ButtonLink is a block-level component and should not be used inline.
+ */
+
+import { jsx as _jsx } from "react/jsx-runtime";
+const ButtonLink = /*#__PURE__*/forwardRef((_ref, ref) => {
+  let {
+    accessibilityRole = 'link',
+    tokens,
+    variant,
+    dataSet,
+    ...props
+  } = _ref;
+  const {
+    hrefAttrs,
+    rest
+  } = hrefAttrsProp.bundle(props);
+  const getTokens = useThemeTokensCallback('Button', tokens, variant);
+  return /*#__PURE__*/_jsx(ButtonBase, {
+    ref: ref,
+    accessibilityRole: accessibilityRole,
+    tokens: getTokens,
+    hrefAttrs: hrefAttrs,
+    dataSet: dataSet,
+    ...rest
+  });
+});
+ButtonLink.displayName = 'ButtonLink';
+ButtonLink.propTypes = { ...a11yProps.types,
+  ...buttonPropTypes,
+  ...linkProps.types,
+  children: textAndA11yText
+};
+export default ButtonLink;

package/lib-module/Button/index.js

@@ -0,0 +1,4 @@
+import Button from './Button';
+import ButtonLink from './ButtonLink';
+import ButtonGroup from './ButtonGroup';
+export { Button, ButtonGroup, ButtonLink };

package/lib-module/Button/propTypes.js

@@ -0,0 +1,36 @@
+import PropTypes from 'prop-types';
+import ABBPropTypes from 'airbnb-prop-types';
+import { variantProp, getTokensPropType } from '../utils/props';
+import A11yText from '../A11yText';
+export const textAndA11yText = ABBPropTypes.childrenOf(PropTypes.oneOfType([ABBPropTypes.elementType(A11yText), PropTypes.string]));
+const buttonPropTypes = {
+  tokens: getTokensPropType('Button'),
+
+  /**
+   * If true, prevents the button from being pressed, changes the cursor (on web) and accessibility
+   * attributes to communicate this to the user, and applies `inactive: true` appearances from the theme
+   */
+  inactive: PropTypes.bool,
+
+  /**
+   * Alias for `inactive`
+   */
+  disabled: PropTypes.bool,
+
+  /**
+   * Button's children must be either:
+   *  - One or more text strings and / or A11yText components
+   *  - A render function with contents that responds to current button state by being passed an object of:
+   * ```
+   * { hovered<bool>, focused<bool>, pressed<bool>, inactive<bool>, selected<bool>, textStyles<RNStyle> }
+   * ```
+   */
+  children: PropTypes.oneOfType([PropTypes.func, textAndA11yText]).isRequired,
+
+  /**
+   * Function called when the button is pressed. Required unless the button has a href.
+   */
+  onPress: PropTypes.func,
+  variant: variantProp.propType
+};
+export default buttonPropTypes;

package/lib-module/Card/Card.js

@@ -0,0 +1,84 @@
+import React from 'react';
+import PropTypes from 'prop-types';
+import { useThemeTokens } from '../ThemeProvider';
+import { getTokensPropType, variantProp } from '../utils';
+import { useViewport } from '../ViewportProvider';
+import { a11yProps, selectSystemProps, viewProps } from '../utils/props';
+import CardBase from './CardBase';
+import { jsx as _jsx } from "react/jsx-runtime";
+const [selectProps, selectedSystemPropTypes] = selectSystemProps([a11yProps, viewProps]);
+/**
+ * A basic card component, unstyled by default.
+ *
+ * ## Component API
+ *
+ * ### Background
+ *
+ * In order to control the background of a card, the following tokens are currently
+ * supported:
+ *
+ * - `backgroundColor`
+ *
+ * ### Border
+ *
+ * The following border tokens can be used:
+ *
+ * - `borderColor`
+ * - `borderRadius`
+ * - `borderWidth`
+ *
+ * ### Padding
+ *
+ * Please use the following tokens to control the padding:
+ *
+ * - `paddingBottom`
+ * - `paddingLeft`
+ * - `paddingRight`
+ * - `paddingTop`
+ *
+ * Note that various viewport sizes are supported as well.
+ *
+ * ### Shadow
+ *
+ * Feel free to use the following properties within the `shadow` token:
+ *
+ * - `inset`: boolean
+ * - `color`: string
+ * - `offsetX`: number
+ * - `offsetY`: number
+ * - `blur`: number
+ * - `spread`: number
+ *
+ * ## Accessibility
+ *
+ * Card supports all the common a11y props. Please remember that by marking a card as `accessible`
+ * you automatically make inaccessible its children, which may or may not be appropriate
+ * depending on what you are trying to achieve.
+ */
+
+const Card = _ref => {
+  let {
+    children,
+    tokens,
+    variant,
+    dataSet,
+    ...rest
+  } = _ref;
+  const viewport = useViewport();
+  const themeTokens = useThemeTokens('Card', tokens, variant, {
+    viewport
+  });
+  return /*#__PURE__*/_jsx(CardBase, {
+    tokens: themeTokens,
+    dataSet: dataSet,
+    ...selectProps(rest),
+    children: children
+  });
+};
+
+Card.propTypes = { ...selectedSystemPropTypes,
+  children: PropTypes.node,
+  tokens: getTokensPropType('Card'),
+  variant: variantProp.propType
+};
+export default Card;