@telus-uds/components-base 1.2.0 → 1.4.0

package/lib-module/Box/Box.js

@@ -0,0 +1,243 @@
+import React, { forwardRef } from 'react';
+import PropTypes from 'prop-types';
+import View from "react-native-web/dist/exports/View";
+import ScrollView from "react-native-web/dist/exports/ScrollView";
+import { useThemeTokens } from '../ThemeProvider';
+import { a11yProps, getA11yPropsFromHtmlTag, getTokensPropType, layoutTags, selectSystemProps, spacingProps, useSpacingScale, variantProp, viewProps } from '../utils';
+import { jsx as _jsx } from "react/jsx-runtime";
+const [selectProps, selectedSystemPropTypes] = selectSystemProps([a11yProps, viewProps]);
+/**
+ * @typedef {import('../utils/props/spacingProps.js').SpacingValue} SpacingValue
+ * @typedef {import('../utils/props/spacingProps.js').SpacingIndex} SpacingIndex
+ * @typedef {import('../utils/props/spacingProps.js').SpacingObject} SpacingObject
+ * @typedef {import('../utils/props/spacingProps.js').SpacingOptions} SpacingOptions
+ */
+
+const selectBoxStyles = tokens => {
+  const styles = {
+    backgroundColor: tokens.backgroundColor
+  };
+  const paddings = ['paddingLeft', 'paddingRight', 'paddingTop', 'paddingBottom']; // Only set on styles if token provided because we spread this object after the spacing scale values
+
+  paddings.forEach(side => {
+    if (tokens[side]) {
+      styles[side] = tokens[side];
+    }
+  });
+  return styles;
+};
+/**
+ * A layout utility component. Use Box to create space (padding) around content.
+ *
+ * ## Spacing
+ *
+ * For most simple uses, pass a number to Box's `space` prop referring to an index in the theme's
+ * spacing scale. For example, for a box with the theme's smallest non-zero amount of padding on all sides:
+ *
+ * ```jsx
+ * <Box space={1}>
+ * ```
+ *
+ * #### Targetting specific sides
+ *
+ * Box allows spacing value props to be assigned to any side or all sides using the following props:
+ *
+ * - `space` sets the default for all sides, which is overridden by other props below
+ * - `horizontal` sets defaults for `left` and `right` (overriding `space` there if it is set)
+ * - `vertical` sets defaults for `top` and `bottom` (overriding `space` there if it is set)
+ * - `left` sets the left side padding, inside the box's bounds
+ * - `right` sets the right side padding, inside the box's bounds
+ * - `top` sets the top side padding, inside the box's bounds
+ * - `bottom` sets the bottom side padding, inside the box's bounds
+ *
+ * Box only controls spacing within its bounds. If space is needed around a box outside of its bounds,
+ * use `Spacer`, `StackView` or wrap the `Box` inside another `Box`.
+ *
+ * #### Viewport-specific spacing
+ *
+ * Responsive behaviours may be set by passing any of the above props an object keyed by viewports.
+ *
+ * For example, if a theme's spacing scale is [0, 4, 8...], this below will have padding of 4px on top,
+ * bottom, and right, and its left padding will be 0px on xs, sm and md viewports and 8px on lg and xl viewports:
+ *
+ * ```jsx
+ * <Box space={1} left={{ xs: 0, lg: 2 }} />`
+ * ```
+ *
+ * #### Subtracting from spacing
+ *
+ * A parent may sometimes need to reduce the spacing size on one or more sides of a `Box` by some variable.
+ * For example, the parent may have a border on one side and want to reduce the spacing of a child box
+ * by the width of that border on that side. This can be achieved using the `subtract` option of the
+ * spacing object, for example:
+ *
+ * ```jsx
+ * <Box space={2} left={{ space: 2, options: { subtract: themeTokens.borderWidthLeft } }} />`
+ * ```
+ *
+ * See `useSpacingScale` hook for other spacing value options and documentation.
+ *
+ * ## Theming
+ *
+ * Box is intended for layout, so minimal theming is supported. Use components like `Card` for
+ * more sophisticated theming.
+ *
+ * ## Scroll
+ *
+ * If passed, the box will be scrollable. If an object is passed, it will be passed to React Native's
+ * `ScrollView` component as props.
+ *
+ * When building native iOS and Android apps, it is important to remember to ensure any screen containing
+ * text content is inside a scrollable box, as screens are not scrollable by default and even very
+ * short text will require scrolling on small devices at the highest accessibility text scaling settings.
+ */
+
+
+const Box = /*#__PURE__*/forwardRef(({
+  space,
+  horizontal = space,
+  vertical = space,
+  top = vertical,
+  bottom = vertical,
+  left = horizontal,
+  right = horizontal,
+  flex,
+  children,
+  variant,
+  tokens,
+  scroll,
+  tag,
+  accessibilityRole,
+  testID,
+  dataSet,
+  ...rest
+}, ref) => {
+  const props = { ...getA11yPropsFromHtmlTag(tag, accessibilityRole),
+    ...selectProps(rest)
+  };
+  const themeTokens = useThemeTokens('Box', tokens, variant);
+  const styles = {
+    flex,
+    paddingLeft: useSpacingScale(left),
+    paddingRight: useSpacingScale(right),
+    paddingTop: useSpacingScale(top),
+    paddingBottom: useSpacingScale(bottom),
+    ...selectBoxStyles(themeTokens)
+  };
+
+  if (scroll) {
+    const scrollProps = typeof scroll === 'object' ? scroll : {};
+    scrollProps.contentContainerStyle = [styles, scrollProps.contentContainerStyle];
+    return /*#__PURE__*/_jsx(ScrollView, { ...scrollProps,
+      ...props,
+      testID: testID,
+      dataSet: dataSet,
+      ref: ref,
+      children: children
+    });
+  }
+
+  return /*#__PURE__*/_jsx(View, { ...props,
+    style: styles,
+    testID: testID,
+    dataSet: dataSet,
+    ref: ref,
+    children: children
+  });
+});
+Box.displayName = 'Box';
+Box.propTypes = { ...selectedSystemPropTypes,
+  variant: variantProp.propType,
+  tokens: getTokensPropType('Box'),
+
+  /**
+   * Sets default padding on all sides of the box using the theme's spacing scale.
+   *
+   * @see {@link SpacingValue}
+   */
+  space: spacingProps.types.spacingValue,
+
+  /**
+   * Sets top and bottom padding using the theme's spacing scale.
+   *
+   * @see {@link SpacingValue}
+   */
+  vertical: spacingProps.types.spacingValue,
+
+  /**
+   * Sets left and right padding using the theme's spacing scale.
+   *
+   * @see {@link SpacingValue}
+   */
+  horizontal: spacingProps.types.spacingValue,
+
+  /**
+   * Sets bottom padding using the theme's spacing scale.
+   *
+   * @see {@link SpacingValue}
+   */
+  bottom: spacingProps.types.spacingValue,
+
+  /**
+   * Sets left padding using the theme's spacing scale.
+   *
+   * @see {@link SpacingValue}
+   */
+  left: spacingProps.types.spacingValue,
+
+  /**
+   * Sets right padding using the theme's spacing scale.
+   *
+   * @see {@link SpacingValue}
+   */
+  right: spacingProps.types.spacingValue,
+
+  /**
+   * Sets top padding using the theme's spacing scale.
+   *
+   * @see {@link SpacingValue}
+   */
+  top: spacingProps.types.spacingValue,
+
+  /**
+   * Sets the `flex` style, which controls `flexGrow`, `flexShrink` and `flexBasis` styles.
+   *
+   * Set as 1 for the box to stretch and grow to fit in the available space, or another number to share
+   * space disproportionately with siblings. See https://reactnative.dev/docs/flexbox#flex for details.
+   *
+   * With the default `0`, the box takes its minimum width from its content.
+   */
+  flex: PropTypes.number,
+
+  /**
+   * Renders a scrollable ScrollView instead of an unscrollable View.
+   *
+   * May take an object of ScrollView props which are passed to the rendered ScrollView.
+   */
+  scroll: PropTypes.oneOfType([PropTypes.bool, ScrollView.propTypes ? PropTypes.shape(ScrollView.propTypes) : PropTypes.object]),
+
+  /**
+   * Optional semantic HTML tag, to apply to the container on web. Does not change styling.
+   *
+   * In native apps, if a header tag is provided ("h1", "h2" etc) and accessibilityRole prop
+   * is not defined, the accessibilityRole will default to "heading".
+   */
+  tag: PropTypes.oneOf(layoutTags),
+
+  /**
+   * Use in tests if the box itself needs to be targetted and no other way of selecting the
+   * box is available (e.g. it cannot be targetted using an appropriate `accessibilityRole`).
+   */
+  testID: PropTypes.string,
+
+  /**
+   * @ignore
+   */
+  dataSet: PropTypes.object,
+
+  /**
+   * Box accepts any content as children.
+   */
+  children: PropTypes.node.isRequired
+};
+export default Box;

package/lib-module/Box/index.js

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

package/lib-module/Button/Button.js

@@ -0,0 +1,25 @@
+import React, { forwardRef } from 'react';
+import ButtonBase from './ButtonBase';
+import buttonPropTypes, { textAndA11yText } from './propTypes';
+import { useThemeTokensCallback } from '../ThemeProvider';
+import { a11yProps } from '../utils/props';
+import { jsx as _jsx } from "react/jsx-runtime";
+const Button = /*#__PURE__*/forwardRef(({
+  accessibilityRole = 'button',
+  tokens,
+  variant,
+  ...props
+}, ref) => {
+  const getTokens = useThemeTokensCallback('Button', tokens, variant);
+  return /*#__PURE__*/_jsx(ButtonBase, { ...props,
+    tokens: getTokens,
+    accessibilityRole: accessibilityRole,
+    ref: ref
+  });
+});
+Button.displayName = 'Button';
+Button.propTypes = { ...a11yProps.types,
+  ...buttonPropTypes,
+  children: textAndA11yText
+};
+export default Button;

package/lib-module/Button/ButtonBase.js

@@ -0,0 +1,254 @@
+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, getCursorStyle, clickProps, linkProps, resolvePressableState, resolvePressableTokens, selectSystemProps, viewProps, wrapStringsInText, withLinkRouter } from '../utils';
+import { jsx as _jsx } from "react/jsx-runtime";
+const [selectProps, selectedSystemPropTypes] = selectSystemProps([a11yProps, linkProps, viewProps]);
+
+const getOuterBorderOffset = ({
+  outerBorderGap = 0,
+  outerBorderWidth = 0
+}) => outerBorderGap + outerBorderWidth;
+
+const selectOuterContainerStyles = ({
+  alignSelf,
+  opacity,
+  outerBorderColor,
+  outerBorderWidth,
+  outerBorderGap,
+  borderRadius,
+  outerBackgroundColor
+}) => ({
+  alignSelf,
+  backgroundColor: outerBackgroundColor,
+  opacity,
+  ...applyOuterBorder({
+    outerBorderGap,
+    outerBorderWidth,
+    outerBorderColor,
+    borderRadius
+  })
+});
+
+const selectOuterWidthStyles = ({
+  outerBorderGap,
+  outerBorderWidth,
+  width
+}) => {
+  // 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(${width} + ${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 = ({
+  backgroundColor,
+  paddingLeft,
+  paddingRight,
+  paddingTop,
+  paddingBottom,
+  shadow,
+  borderWidth,
+  minWidth
+}) => {
+  // 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 = ({
+  borderColor,
+  borderWidth,
+  borderRadius
+}) => ({
+  borderColor,
+  borderWidth,
+  borderRadius
+});
+
+const selectTextStyles = ({
+  fontSize,
+  color,
+  lineHeight,
+  fontName,
+  fontWeight,
+  textAlign
+}) => applyTextStyles({
+  fontSize,
+  color,
+  lineHeight,
+  fontName,
+  fontWeight,
+  textAlign
+});
+
+const selectWebOnlyStyles = (inactive, themeTokens, {
+  accessibilityRole
+}) => {
+  return Platform.select({
+    web: {
+      // if it would overflow the container, wraps instead
+      maxWidth: `calc(100% + ${getOuterBorderOffset(themeTokens) * 2}px)`,
+      outline: 'none',
+      // removes the default browser :focus outline
+      ...getCursorStyle(inactive, accessibilityRole)
+    },
+    default: {}
+  });
+};
+
+const ButtonBase = /*#__PURE__*/forwardRef(({
+  id,
+  href,
+  hrefAttrs,
+  children,
+  tokens = {},
+  disabled = false,
+  // alias for inactive
+  inactive = disabled,
+  selected = false,
+  ...rawRest
+}, ref) => {
+  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,164 @@
+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 { useViewport } from '../ViewportProvider';
+import { useThemeTokens, useThemeTokensCallback } from '../ThemeProvider';
+import { a11yProps, pressProps, getTokensPropType, selectSystemProps, selectTokens, variantProp, viewProps } from '../utils/props';
+import { useMultipleInputValues } from '../utils/input';
+import { getPressHandlersWithArgs } from '../utils/pressability';
+import { jsx as _jsx } from "react/jsx-runtime";
+const [selectProps, selectedSystemPropTypes] = selectSystemProps([a11yProps, pressProps, viewProps]);
+const ButtonGroup = /*#__PURE__*/forwardRef(({
+  variant,
+  tokens,
+  items = [],
+  values,
+  initialValues,
+  maxValues = 1,
+  onChange,
+  readOnly = false,
+  inactive = false,
+  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
+  } = 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';
+  return /*#__PURE__*/_jsx(StackWrap, { ...systemProps,
+    space: space,
+    direction: direction,
+    tokens: stackTokens,
+    ref: ref,
+    children: items.map(({
+      label,
+      id = label,
+      accessibilityLabel,
+      ref: itemRef
+    }, 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 = event => {
+        if (pressHandlers.onPress) pressHandlers.onPress();
+        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,
+        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({
+    /**
+     * 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)
+};
+export default ButtonGroup;