@telus-uds/components-base 1.8.3 → 1.8.4

package/lib-module/HorizontalScroll/HorizontalScroll.js

@@ -0,0 +1,175 @@
+import React, { forwardRef, useEffect, useRef, useState } from 'react';
+import PropTypes from 'prop-types';
+import Platform from "react-native-web/dist/exports/Platform";
+import StyleSheet from "react-native-web/dist/exports/StyleSheet";
+import View from "react-native-web/dist/exports/View";
+import { validateThemeTokens, resolveThemeTokens } from '../ThemeProvider';
+import { a11yProps, getTokensSetPropType, selectSystemProps, selectTokens, viewProps } from '../utils';
+import ScrollViewEnd from './ScrollViewEnd';
+import { getItemPositionScrollTarget, itemPositionsPropType } from './itemPositions';
+import { jsx as _jsx } from "react/jsx-runtime";
+import { jsxs as _jsxs } from "react/jsx-runtime";
+const [selectProps, selectedSystemPropTypes] = selectSystemProps([a11yProps, viewProps]);
+const tokenKeys = ['nextIcon', 'previousIcon', 'gutter', 'borderBottomWidth', 'borderBottomColor', 'buttonClearance'];
+export const selectHorizontalScrollTokens = (themeTokens, prefix) => selectTokens(tokenKeys, themeTokens, prefix);
+/**
+ * Base component that scrolls horizontally and displays left and right buttons if
+ * there is content to the left and the right which can be scrolled to.
+ *
+ * @TODO revisit `ScrollButton` after IconButton is stable.
+ */
+
+const HorizontalScroll = /*#__PURE__*/forwardRef((_ref, ref) => {
+  let {
+    ScrollButton,
+    tokens,
+    itemPositions,
+    children,
+    ...rest
+  } = _ref;
+  const {
+    nextIcon,
+    previousIcon,
+    gutter,
+    borderBottomWidth,
+    borderBottomColor,
+    buttonClearance = 0
+  } = validateThemeTokens(resolveThemeTokens(tokens), // Allow missing icons
+  getTokensSetPropType(tokenKeys, {
+    partial: true
+  }), 'HorizontalScroll');
+  const [containerWidth, setContainerWidth] = useState(0);
+  const [contentWidth, setContentWidth] = useState(0);
+
+  const handleContentWidth = width => setContentWidth(width);
+
+  const handleContainerLayout = _ref2 => {
+    let {
+      nativeEvent: {
+        layout: {
+          width
+        }
+      }
+    } = _ref2;
+    return setContainerWidth(width);
+  }; // Update the scroll position only when scrolling actions ends to minimally rerender
+  // and update which buttons are conditionally rendered.
+
+
+  const [scrollOffset, setScrollOffset] = useState(0);
+
+  const handleScrollEnd = _ref3 => {
+    let {
+      nativeEvent: {
+        contentOffset: {
+          x
+        }
+      }
+    } = _ref3;
+    setScrollOffset(x);
+  };
+
+  const scrollMax = Math.max(0, contentWidth - containerWidth);
+  const showNextButton = scrollOffset < scrollMax;
+  const showPreviousButton = scrollOffset > 0;
+  const scrollRef = useRef(null);
+
+  const scrollTo = targetX => {
+    var _scrollRef$current;
+
+    if (typeof ((_scrollRef$current = scrollRef.current) === null || _scrollRef$current === void 0 ? void 0 : _scrollRef$current.scrollTo) === 'function') {
+      const x = getItemPositionScrollTarget(targetX, scrollMax, itemPositions.positions, buttonClearance);
+      scrollRef.current.scrollTo({
+        x,
+        animated: true
+      });
+
+      if (Platform.OS === 'android') {
+        // React Native calls onScrollMomentumEnd after scrollTo for iOS, but not Android.
+        // See https://github.com/facebook/react-native/issues/26661
+        // There's also no callback for when scrollTo finishes.
+        setTimeout(() => setScrollOffset(x), 300);
+      }
+    }
+  }; // Make scrollTo and relevant co-ordinates available to any component with an interest in itemPositions.
+  // ItemPositions is a mutable ref object intended to have its properties mutated without any rerenders.
+
+  /* eslint-disable-next-line no-param-reassign */
+
+
+  itemPositions.scrollTo = scrollTo;
+  /* eslint-disable-next-line no-param-reassign */
+
+  itemPositions.containerWidth = containerWidth;
+  /* eslint-disable-next-line no-param-reassign */
+
+  itemPositions.contentWidth = contentWidth;
+  /* eslint-disable-next-line no-param-reassign */
+
+  itemPositions.scrollOffset = scrollOffset;
+  const hasWidths = itemPositions.contentWidth > 0 && itemPositions.contentWidth > 0;
+  useEffect(() => {
+    if (hasWidths) itemPositions.setIsReady(true); // itemPositions is a ref object so this should occur only when elements' widths are set in state
+  }, [hasWidths, itemPositions]); // When scrolling, allow clearance around scroll buttons, so e.g. this...
+  // (<-) Item 5   Item 6   Item 7   Item 8   It(->)
+  // ...doesn't scroll like this with Item 9 never being properly visible:
+  // (<-)em 9   Item 10  Item 11  Item 12  Item (->)
+
+  const scrollDistance = containerWidth - buttonClearance * 2;
+
+  const scrollNext = () => scrollTo(scrollOffset + scrollDistance);
+
+  const scrollPrevious = () => scrollTo(scrollOffset - scrollDistance); // On Web, being scrollable in one direction prevents overflow: visible in the other direction.
+  // Apply a fixed margin gutter that tab highlight effects can overhang without getting trimmed.
+
+
+  return /*#__PURE__*/_jsxs(View, {
+    ref: ref,
+    style: staticStyles.container,
+    children: [/*#__PURE__*/_jsx(ScrollViewEnd, {
+      onScrollEnd: handleScrollEnd,
+      ref: scrollRef,
+      horizontal: true,
+      onContentSizeChange: handleContentWidth,
+      onLayout: handleContainerLayout,
+      showsHorizontalScrollIndicator: false,
+      contentContainerStyle: [staticStyles.scrollContainer, {
+        borderBottomWidth,
+        borderBottomColor
+      }],
+      ...selectProps(rest),
+      children: children
+    }), showPreviousButton && /*#__PURE__*/_jsx(ScrollButton, {
+      icon: previousIcon,
+      onPress: scrollPrevious,
+      offset: gutter,
+      direction: "previous"
+    }), showNextButton && /*#__PURE__*/_jsx(ScrollButton, {
+      icon: nextIcon,
+      onPress: scrollNext,
+      offset: gutter,
+      direction: "next"
+    })]
+  });
+});
+HorizontalScroll.displayName = 'HorizontalScroll';
+const staticStyles = StyleSheet.create({
+  scrollContainer: {
+    // Gives inner container width from content, allowing it to exceed its container's width
+    alignSelf: 'flex-start',
+    flexGrow: 1
+  },
+  container: {
+    // Vertically center the ScrollButtons buttons
+    justifyContent: 'center'
+  }
+});
+HorizontalScroll.propTypes = { ...selectedSystemPropTypes,
+  itemPositions: itemPositionsPropType,
+  ScrollButton: PropTypes.elementType,
+  tokens: getTokensSetPropType(tokenKeys, {
+    allowFunction: true
+  }),
+  children: PropTypes.node
+};
+export default HorizontalScroll;

package/lib-module/HorizontalScroll/HorizontalScrollButton.js

@@ -0,0 +1,81 @@
+import React, { forwardRef } from 'react';
+import PropTypes from 'prop-types';
+import StyleSheet from "react-native-web/dist/exports/StyleSheet";
+import View from "react-native-web/dist/exports/View";
+import { variantProp, getTokensPropType, useCopy, copyPropTypes, a11yProps } from '../utils';
+import { useThemeTokens } from '../ThemeProvider';
+import IconButton from '../IconButton';
+import dictionary from './dictionary';
+import { jsx as _jsx } from "react/jsx-runtime";
+
+const selectContainerStyles = _ref => {
+  let {
+    offset
+  } = _ref;
+  return {
+    marginTop: offset ? -offset : 0
+  };
+};
+/**
+ * Button within a Tabs component showing users that content is available to the left or
+ * right, scrolling a screen's worth of content left or right when pressed.
+ *
+ * This is rendered automatically by `Tabs` and isn't intended be used directly.
+ *
+ * @TODO when IconButton is complete and stable revisit this and update interaction state styles.
+ */
+
+
+const HorizontalScrollButton = /*#__PURE__*/forwardRef((_ref2, ref) => {
+  let {
+    direction = 'next',
+    icon,
+    offset,
+    onPress,
+    variant,
+    tokens,
+    copy
+  } = _ref2;
+  const themeTokens = useThemeTokens('HorizontalScrollButton', tokens, variant);
+  const getCopy = useCopy({
+    dictionary,
+    copy
+  });
+  const label = direction === 'previous' ? getCopy('previousText') : getCopy('nextText');
+  return /*#__PURE__*/_jsx(View, {
+    style: [staticStyles.absolute, staticStyles[direction], selectContainerStyles({
+      offset
+    })],
+    children: /*#__PURE__*/_jsx(IconButton, {
+      accessibilityLabel: label,
+      icon: icon,
+      onPress: onPress,
+      ref: ref,
+      tokens: themeTokens,
+      variant: variant,
+      ...a11yProps.nonFocusableProps
+    })
+  });
+});
+HorizontalScrollButton.displayName = 'HorizontalScrollButton';
+const staticStyles = StyleSheet.create({
+  absolute: {
+    position: 'absolute'
+  },
+  previous: {
+    left: 0
+  },
+  next: {
+    right: 0
+  }
+});
+HorizontalScrollButton.propTypes = {
+  tokens: getTokensPropType('HorizontalScrollButton'),
+  variant: variantProp.propType,
+  copy: copyPropTypes,
+  direction: PropTypes.oneOf(['previous', 'next']),
+  offset: PropTypes.number,
+  icon: PropTypes.elementType,
+  onPress: PropTypes.func.isRequired
+};
+export default HorizontalScrollButton;

package/lib-module/HorizontalScroll/ScrollViewEnd.js

@@ -0,0 +1,48 @@
+import React, { forwardRef, useCallback, useEffect } from 'react';
+import PropTypes from 'prop-types';
+import ScrollView from "react-native-web/dist/exports/ScrollView";
+import debounce from 'lodash.debounce';
+import { jsx as _jsx } from "react/jsx-runtime";
+const DEBOUNCE_MS = 100;
+/**
+ * A wrapper for ScrollView that supports an `onScrollEnd` function.
+ *
+ * React Native Web hasn't got around to implementing any scroll end handlers yet,
+ * so we need to work around it with debouncing on `onScroll`. See:
+ * https://github.com/necolas/react-native-web/issues/1021
+ */
+
+const ScrollViewEnd = /*#__PURE__*/forwardRef((_ref, ref) => {
+  let {
+    onScrollEnd,
+    onScroll,
+    ...props
+  } = _ref;
+  // Return debounced function directly from useCallback so it has .cancel method etc.
+  // Linter complains this stops it automatically scanning the deps, but we can check them manually.
+  // eslint-disable-next-line react-hooks/exhaustive-deps
+  const debounceScrollEnd = useCallback(debounce(event => onScrollEnd(event), DEBOUNCE_MS), [onScrollEnd]); // Call any onScroll handler immediately, and any onScrollEnd handler after 100ms of no scrolling
+
+  const handleScroll = event => {
+    if (typeof onScroll === 'function') onScroll(event);
+    if (typeof onScrollEnd === 'function') debounceScrollEnd(event);
+  }; // Cancel any lingering debounce timeouts on dismount
+
+
+  useEffect(() => debounceScrollEnd.cancel);
+  return /*#__PURE__*/_jsx(ScrollView, {
+    ref: ref,
+    ...props,
+    onScroll: handleScroll,
+    scrollEventThrottle: DEBOUNCE_MS / 2
+  });
+});
+ScrollViewEnd.displayName = 'ScrollViewEnd';
+ScrollViewEnd.propTypes = {
+  onScrollEnd: PropTypes.func.isRequired,
+  onScroll: PropTypes.func
+};
+ScrollViewEnd.defaultProps = {
+  onScroll: null
+};
+export default ScrollViewEnd;

package/lib-module/HorizontalScroll/ScrollViewEnd.native.js

@@ -0,0 +1,27 @@
+import React, { forwardRef } from 'react';
+import PropTypes from 'prop-types';
+import ScrollView from "react-native-web/dist/exports/ScrollView";
+/**
+ * A wrapper for ScrollView that supports an `onScrollEnd` function.
+ *
+ * React Native has two scroll end handlers, we want to treat them both the same.
+ */
+
+import { jsx as _jsx } from "react/jsx-runtime";
+const ScrollViewEnd = /*#__PURE__*/forwardRef((_ref, ref) => {
+  let {
+    onScrollEnd,
+    ...props
+  } = _ref;
+  return /*#__PURE__*/_jsx(ScrollView, {
+    ref: ref,
+    ...props,
+    onScrollEndDrag: onScrollEnd,
+    onMomentumScrollEnd: onScrollEnd
+  });
+});
+ScrollViewEnd.displayName = 'ScrollViewEnd';
+ScrollViewEnd.propTypes = {
+  onScrollEnd: PropTypes.func.isRequired
+};
+export default ScrollViewEnd;

package/lib-module/HorizontalScroll/dictionary.js

@@ -0,0 +1,11 @@
+export default {
+  en: {
+    // English text from TDS Community `Tabs`
+    previousLabel: 'Move menu to the left',
+    nextLabel: 'Move menu to the right'
+  },
+  fr: {
+    previousLabel: 'Déplacer le menu vers la gauche',
+    nextLabel: 'Déplacer le menu vers la droite'
+  }
+};

package/lib-module/HorizontalScroll/index.js

@@ -0,0 +1,11 @@
+import HorizontalScroll, { selectHorizontalScrollTokens } from './HorizontalScroll';
+import { useItemPositions, getItemPositionScrollTarget, getItemPositionLayoutHandler, itemPositionsPropType } from './itemPositions';
+export default HorizontalScroll;
+export { default as HorizontalScrollButton } from './HorizontalScrollButton';
+export const horizontalScrollUtils = {
+  selectHorizontalScrollTokens,
+  useItemPositions,
+  getItemPositionScrollTarget,
+  getItemPositionLayoutHandler,
+  itemPositionsPropType
+};

package/lib-module/HorizontalScroll/itemPositions.js

@@ -0,0 +1,112 @@
+import { useRef, useState } from 'react';
+import PropTypes from 'prop-types'; // Utilities to assist scrolling a parent so that it snaps neatly to an appropriate child.
+
+/**
+ * @typedef ItemPositionPosition
+ * @property {number} [ItemPositionItem.start] - optional theme scale variants e.g. compact, wide
+ * @property {number} [ItemPositionItem.end] - optional override to force a particular pixel size
+ *
+ * @typedef {Object.<number, ItemPositionItem>} ItemPositionPositions - ref object of start/end coordinates
+ *
+ * @typedef ItemPositions
+ * @property {number} ItemPositions.contentWidth - current width of potentially-overflowing content inside scrollable
+ * @property {number} ItemPositions.containerWidth - current width of non-overflowing outer scroll container
+ * @property {number} ItemPositions.scrollOffset - current x position of the left edge of the visible section of the scrollable content
+ * @property {ItemPositionPositions} ItemPositions.positions - `{ start, end }` coordinates of each scrollable content item, by index
+ * @property {(targetX: number) => void)} ItemPositions.scrollTo - function to scroll to a co-ordinate, applying scrolling logic
+ * @property {() => void)} ItemPositions.setIsReady - function to call when layout has been calculated and itemPositions data is ready
+ */
+
+/**
+ * Takes a desired scroll target coordinate and returns a valid coordinate
+ * that, when not scrolling to one end or another, snaps to the start of an item,
+ * making sure any "scroll back" button doesn't overlap the first item.
+ *
+ * @param {number} x - the intended coordinate to scroll to
+ * @param {number} scrollMax - the highest posible coordinate to scroll to
+ * @param {ItemPositionPositions} positions - positions list from `useItemPositions` ref
+ * @param {number} [buttonClearance] - offset to allow space for a button
+ * @returns {number}
+ */
+
+export const getItemPositionScrollTarget = function (x, scrollMax, positions) {
+  let buttonClearance = arguments.length > 3 && arguments[3] !== undefined ? arguments[3] : 0;
+  if (x <= 0) return 0;
+  if (x >= scrollMax) return scrollMax; // If not scrolling all the way to the start or end, stop
+  // where the first item is not coverred by the scroll previous button
+
+  const targetItem = Object.values(positions).find(_ref => {
+    let {
+      start,
+      end
+    } = _ref;
+    return start <= x && end > x;
+  }); // If there's no target item we're landing at a gap between items
+
+  const targetX = targetItem ? targetItem.start : x;
+  return Math.max(0, targetX - buttonClearance);
+};
+/**
+ * Returns a handler for React Native's `onLayout` which updates the values of
+ * the ref object returned from `useItemPositions`.
+ *
+ * @param {ItemPositionPositions} positions
+ * @param {number} index
+ * @returns {function}
+ */
+
+export const getItemPositionLayoutHandler = (positions, index) => {
+  const handleLayout = _ref2 => {
+    let {
+      nativeEvent: {
+        layout: {
+          width,
+          x
+        }
+      }
+    } = _ref2;
+
+    /* eslint-disable-next-line no-param-reassign */
+    positions[index] = {
+      start: x,
+      end: x + width
+    };
+  };
+
+  return handleLayout;
+};
+/**
+ * Wrapper for `useRef` which gives a mutable object in which item start/end coordinates,
+ * scrollTo method and content/container widths may be set and updated without causing a re-render.
+ *
+ * @returns {[ItemPositions, isReady: bool]} tuple array of:
+ *  - current ref object `{ positions, contentWidth, containerWidth, scrollOffset, scrollTo, setIsReady }`
+ *  - boolean that updates to `true` (causing a re-render) after the first time `setIsReady` is called
+ */
+
+export const useItemPositions = () => {
+  const [isReady, setIsReady] = useState(false);
+  return [useRef({
+    positions: {},
+    scrollTo: () => {},
+    contentWidth: 0,
+    containerWidth: 0,
+    scrollOffset: 0,
+    setIsReady
+  }).current, isReady];
+};
+/**
+ * PropType for the ref object returned by `useItemPositions`
+ */
+
+export const itemPositionsPropType = PropTypes.exact({
+  positions: PropTypes.objectOf(PropTypes.shape({
+    start: PropTypes.number,
+    end: PropTypes.number
+  })),
+  scrollTo: PropTypes.func,
+  contentWidth: PropTypes.number,
+  containerWidth: PropTypes.number,
+  scrollOffset: PropTypes.number,
+  setIsReady: PropTypes.func
+});

package/lib-module/Icon/Icon.js

@@ -0,0 +1,62 @@
+import React, { forwardRef } from 'react';
+import Platform from "react-native-web/dist/exports/Platform";
+import View from "react-native-web/dist/exports/View";
+import PropTypes from 'prop-types';
+import { useThemeTokens } from '../ThemeProvider';
+import { getTokensPropType, scaleWithText, variantProp } from '../utils';
+import { jsx as _jsx } from "react/jsx-runtime";
+const Icon = /*#__PURE__*/forwardRef((_ref, ref) => {
+  let {
+    icon: IconComponent,
+    accessibilityLabel,
+    variant,
+    tokens,
+    scalesWithText = false,
+    dataSet
+  } = _ref;
+  const themeTokens = useThemeTokens('Icon', tokens, variant);
+  const size = scalesWithText ? scaleWithText(themeTokens.size) : themeTokens.size;
+
+  const iconContent = /*#__PURE__*/_jsx(IconComponent, {
+    title: accessibilityLabel,
+    size: size,
+    color: themeTokens.color
+  });
+
+  return Platform.OS === 'web' ? /*#__PURE__*/_jsx(View, {
+    ref: ref // eslint-disable-next-line react-native/no-inline-styles
+    ,
+    style: {
+      // TODO: systematise animations.
+      // https://github.com/telus/universal-design-system/issues/487
+      transition: 'transform 200ms, color 200ms',
+      transform: [themeTokens.scale ? "scale(".concat(themeTokens.scale, ")") : '', themeTokens.translateX ? "translateX(".concat(themeTokens.translateX, "px)") : '', themeTokens.translateY ? "translateY(".concat(themeTokens.translateY, "px)") : ''].filter(exists => exists).join(' ')
+    },
+    dataSet: dataSet,
+    children: iconContent
+  }) : iconContent;
+});
+Icon.displayName = 'Icon';
+export const iconComponentPropTypes = {
+  variant: variantProp.propType,
+  tokens: getTokensPropType('Icon'),
+
+  /**
+   * Descriptive label used in web SVG title tag for accessibility
+   */
+  accessibilityLabel: PropTypes.string,
+
+  /**
+   * controls whether the icon size should be proportionate to any accessibility-related font scaling.
+   */
+  scalesWithText: PropTypes.bool
+};
+Icon.propTypes = { ...iconComponentPropTypes,
+
+  /**
+   * A valid UDS icon component imported from a UDS palette
+   * (e.g.) `import { MyIcon } from @telus-uds/palette-<brand>/build/web/icons`
+   */
+  icon: PropTypes.elementType.isRequired
+};
+export default Icon;

package/lib-module/Icon/IconText.js

@@ -0,0 +1,83 @@
+import React, { forwardRef } from 'react';
+import PropTypes from 'prop-types';
+import Platform from "react-native-web/dist/exports/Platform";
+import View from "react-native-web/dist/exports/View";
+import Icon, { iconComponentPropTypes } from './Icon';
+import { getStackedContent } from '../StackView';
+import { spacingProps } from '../utils';
+/**
+ * Returns an icon and some text with a sized gap between them. This is a utility component
+ * intended for use when creating components, not intended for use in applications on its own.
+ *
+ * IconText does not wrap its children, so should be used either:
+ *  - inline within a <Text> element
+ *  - within a container with `flexDirection: 'row'`
+ */
+
+import { jsx as _jsx } from "react/jsx-runtime";
+const IconText = /*#__PURE__*/forwardRef((_ref, ref) => {
+  var _iconProps$tokens;
+
+  let {
+    space,
+    iconPosition = 'left',
+    icon: IconComponent,
+    iconProps,
+    children
+  } = _ref;
+
+  const iconContent = IconComponent && /*#__PURE__*/_jsx(Icon, {
+    ref: ref,
+    icon: IconComponent,
+    scalesWithText: true,
+    ...iconProps
+  }); // Inline images on Android are always baseline-aligned which makes them look misaligned - offset it.
+  // See abandoned issue https://github.com/facebook/react-native/issues/6529
+
+
+  const size = iconProps === null || iconProps === void 0 ? void 0 : (_iconProps$tokens = iconProps.tokens) === null || _iconProps$tokens === void 0 ? void 0 : _iconProps$tokens.size;
+  const iconAdjusted = Platform.OS === 'android' && iconContent && size ? /*#__PURE__*/_jsx(View, {
+    style: {
+      transform: [{
+        translateY: size * 0.2
+      }]
+    },
+    children: iconContent
+  }) : iconContent;
+  return getStackedContent(iconPosition === 'left' ? [iconAdjusted, children] : [children, iconAdjusted], {
+    space,
+    direction: 'row'
+  });
+});
+IconText.displayName = 'IconText';
+IconText.propTypes = {
+  /**
+   * Amount of space to separate the text content and icon. Uses the themes's spacing scale
+   * (see useSpacingScale for more info).
+   */
+  space: spacingProps.types.spacingValue,
+
+  /**
+   * Whether the icon should be to the left of the content or the right of the content.
+   */
+  iconPosition: PropTypes.oneOf(['left', 'right']),
+
+  /**
+   * A valid UDS icon component imported from a UDS palette.
+   */
+  icon: PropTypes.func,
+
+  /**
+   * Props that will be passed to the icon component. By default the icon's `scalesWithText`
+   * prop will be set as "true" so that the icon continues to match the size of the text
+   * if users use accessibility settings to increase text size.
+   */
+  iconProps: PropTypes.exact(iconComponentPropTypes),
+
+  /**
+   * Content to be rendered alongside the Icon component. Usually this should be a
+   * `<Typography>` component, or a component that renders `<Text>`.
+   */
+  children: PropTypes.node
+};
+export default IconText;

package/lib-module/Icon/index.js

@@ -0,0 +1,4 @@
+import Icon, { iconComponentPropTypes } from './Icon';
+import IconText from './IconText';
+export default Icon;
+export { iconComponentPropTypes, IconText };