@telus-uds/components-base 1.2.0 → 1.4.0

package/lib-module/Tooltip/Tooltip.js

@@ -0,0 +1,332 @@
+import React, { forwardRef, useEffect, useRef, useState } from 'react';
+import Dimensions from "react-native-web/dist/exports/Dimensions";
+import Platform from "react-native-web/dist/exports/Platform";
+import Pressable from "react-native-web/dist/exports/Pressable";
+import StyleSheet from "react-native-web/dist/exports/StyleSheet";
+import Text from "react-native-web/dist/exports/Text";
+import View from "react-native-web/dist/exports/View";
+import PropTypes from 'prop-types';
+import { applyShadowToken, applyTextStyles, useThemeTokens } from '../ThemeProvider';
+import { a11yProps, getTokensPropType, selectSystemProps, selectTokens, variantProp, viewProps } from '../utils';
+import Backdrop from './Backdrop';
+import getTooltipPosition from './getTooltipPosition';
+import TooltipButton from '../TooltipButton';
+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 selectTooltipStyles = ({
+  backgroundColor,
+  paddingTop,
+  paddingBottom,
+  paddingLeft,
+  paddingRight,
+  borderRadius
+}) => ({
+  backgroundColor,
+  paddingTop,
+  paddingBottom,
+  paddingLeft,
+  paddingRight,
+  borderRadius
+});
+
+const selectTooltipShadowStyles = ({
+  shadow,
+  borderRadius
+}) => ({
+  borderRadius,
+  ...applyShadowToken(shadow)
+});
+
+const selectTooltipPositionStyles = ({
+  top,
+  left,
+  width
+}) => {
+  return {
+    top,
+    left,
+    width
+  };
+};
+
+const selectArrowStyles = ({
+  backgroundColor,
+  arrowWidth,
+  arrowBorderRadius,
+  shadow
+}, {
+  position,
+  width: tooltipWidth,
+  height: tooltipHeight
+}) => {
+  // the arrow width is actually a diagonal of the rectangle that we'll use as a tip
+  const rectangleSide = Math.sqrt(arrowWidth * arrowWidth / 2); // position the arrow at the side and center of the tooltip - this happens before rotation
+  // so we use the rectangle size as basis
+
+  const verticalOffset = -1 * rectangleSide / 2;
+  const horizontalOffset = rectangleSide / 2; // percentage-based absolute positioning doesn't act well on native, so we have to
+  // calculate the pixel values
+
+  const directionalStyles = {
+    above: {
+      bottom: verticalOffset,
+      left: tooltipWidth / 2 - horizontalOffset,
+      transform: [{
+        rotateZ: '45deg'
+      }]
+    },
+    below: {
+      top: verticalOffset,
+      left: tooltipWidth / 2 - horizontalOffset,
+      transform: [{
+        rotateZ: '-135deg'
+      }]
+    },
+    left: {
+      right: verticalOffset,
+      top: tooltipHeight / 2 - horizontalOffset,
+      transform: [{
+        rotateZ: '-45deg'
+      }]
+    },
+    right: {
+      left: verticalOffset,
+      top: tooltipHeight / 2 - horizontalOffset,
+      transform: [{
+        rotateZ: '135deg'
+      }]
+    }
+  };
+  return {
+    backgroundColor,
+    width: rectangleSide,
+    height: rectangleSide,
+    borderBottomRightRadius: arrowBorderRadius,
+    // this corner will be the arrow tip after rotation
+    ...applyShadowToken(shadow),
+    ...directionalStyles[position]
+  };
+};
+
+const selectTextStyles = tokens => applyTextStyles(selectTokens('Typography', tokens));
+
+const defaultControl = (pressableState, variant) => /*#__PURE__*/_jsx(TooltipButton, {
+  pressableState: pressableState,
+  variant: variant
+});
+/**
+ * Tooltip provides a descriptive and detailed explanation or instructions. It can be used next to an input label
+ * to help a user fill it in, or as a standalone component.
+ *
+ * By default the TooltipButton component will be used as a control for triggering the tooltip, but you may attach
+ * a tooltip to any other component. A render function can be used to adjust the control's styling on state changes (hover, focus, etc.).
+ *
+ * ### Positioning
+ * By default a Tooltip will be automatically positioned in a way that ensures it fits within the viewport.
+ * You may suggest a position with a prop - it will be used, unless the tooltip would end up outside the viewport.
+ *
+ * ### Usage criteria
+ * - You may use one when the information is useful only to a small percentage of users (ie. tech savvy people wouldn't need this info).
+ * - Tooltips may also be useful when vertical space is an issue.
+ */
+
+
+const Tooltip = /*#__PURE__*/forwardRef(({
+  children,
+  content,
+  position = 'auto',
+  copy = 'en',
+  tokens,
+  variant,
+  ...rest
+}, ref) => {
+  const [isOpen, setIsOpen] = useState(false);
+  const controlRef = useRef();
+  const [controlLayout, setControlLayout] = useState(null);
+  const [tooltipDimensions, setTooltipDimensions] = useState(null);
+  const [windowDimensions, setWindowDimensions] = useState(Dimensions.get('window'));
+  const [tooltipPosition, setTooltipPosition] = useState(null);
+  const getCopy = useCopy({
+    dictionary,
+    copy
+  });
+  const themeTokens = useThemeTokens('Tooltip', tokens, variant);
+  const {
+    arrowWidth,
+    arrowOffset
+  } = themeTokens;
+  useEffect(() => {
+    const subscription = Dimensions.addEventListener('change', ({
+      window
+    }) => {
+      setWindowDimensions(window);
+    });
+    return () => subscription === null || subscription === void 0 ? void 0 : subscription.remove();
+  });
+
+  const toggleIsOpen = () => setIsOpen(!isOpen);
+
+  const close = () => setIsOpen(false);
+
+  const getPressableState = ({
+    pressed,
+    hovered,
+    focused
+  }) => ({
+    pressed,
+    hover: hovered,
+    focus: focused
+  });
+
+  const onTooltipLayout = ({
+    nativeEvent: {
+      layout: {
+        width,
+        height
+      }
+    }
+  }) => {
+    if (tooltipDimensions === null || tooltipDimensions.width !== width || tooltipDimensions.height !== height) {
+      setTooltipDimensions({
+        width: Platform.select({
+          web: width + 0.3,
+          // avoids often unnecessary line breaks due to subpixel rendering of fonts
+          native: width
+        }),
+        height
+      });
+    }
+  };
+
+  useEffect(() => {
+    if (isOpen) {
+      controlRef.current.measureInWindow((x, y, width, height) => {
+        setControlLayout({
+          x,
+          y,
+          width,
+          height
+        });
+      });
+    } else {
+      setControlLayout(null);
+      setTooltipDimensions(null);
+      setTooltipPosition(null);
+    }
+  }, [isOpen]);
+  useEffect(() => {
+    setIsOpen(false);
+  }, [windowDimensions]);
+  useEffect(() => {
+    if (tooltipPosition !== null && !(tooltipPosition !== null && tooltipPosition !== void 0 && tooltipPosition.isNormalized) || !isOpen || controlLayout === null || tooltipDimensions == null) {
+      return;
+    }
+
+    const updatedPosition = getTooltipPosition(position, {
+      controlLayout,
+      tooltipDimensions,
+      windowDimensions,
+      arrowWidth,
+      arrowOffset
+    }); // avoid ending up in an infinite normalization loop
+
+    if (tooltipPosition !== null && tooltipPosition !== void 0 && tooltipPosition.isNormalized && updatedPosition.isNormalized) {
+      return;
+    }
+
+    setTooltipPosition(updatedPosition);
+  }, [isOpen, position, tooltipDimensions, controlLayout, windowDimensions, arrowWidth, arrowOffset, tooltipPosition]);
+  const control = children !== undefined ? children : defaultControl;
+  const pressableStyles = control === defaultControl ? Platform.select({
+    web: {
+      outline: 'none'
+    }
+  }) : undefined;
+  const pressableHitSlop = control === defaultControl ? {
+    top: 10,
+    bottom: 10,
+    left: 10,
+    right: 10
+  } : undefined;
+  return /*#__PURE__*/_jsxs(View, {
+    style: staticStyles.container,
+    ...selectProps(rest),
+    children: [/*#__PURE__*/_jsx(Pressable, {
+      onPress: toggleIsOpen,
+      ref: controlRef,
+      onBlur: close,
+      style: pressableStyles,
+      hitSlop: pressableHitSlop,
+      accessibilityLabel: getCopy('a11yText'),
+      accessibilityRole: "button",
+      children: typeof control === 'function' ? pressableState => control(getPressableState(pressableState), variant) : control
+    }), isOpen && /*#__PURE__*/_jsx(Backdrop, {
+      onPress: close,
+      children: /*#__PURE__*/_jsxs(View, {
+        ref: ref,
+        style: [staticStyles.tooltip, selectTooltipShadowStyles(themeTokens), // applied separately so that it doesn't cover the arrow
+        tooltipPosition && selectTooltipPositionStyles(tooltipPosition), (tooltipPosition === null || (tooltipPosition === null || tooltipPosition === void 0 ? void 0 : tooltipPosition.isNormalized)) && staticStyles.tooltipHidden // visually hide the tooltip until we have a final measurement
+        ],
+        onLayout: onTooltipLayout,
+        accessibilityRole: "alert",
+        children: [/*#__PURE__*/_jsx(View, {
+          style: [staticStyles.arrow, tooltipPosition && selectArrowStyles(themeTokens, tooltipPosition)]
+        }), /*#__PURE__*/_jsx(View, {
+          style: selectTooltipStyles(themeTokens),
+          children: /*#__PURE__*/_jsx(Text, {
+            style: selectTextStyles(themeTokens),
+            children: content
+          })
+        })]
+      })
+    })]
+  });
+});
+Tooltip.displayName = 'Tooltip';
+Tooltip.propTypes = { ...selectedSystemPropTypes,
+
+  /**
+   * Used to render the control (i.e. tooltip trigger). If a render function is used it will receive the
+   * pressable state and tooltip variant as an argument.
+   */
+  children: PropTypes.oneOfType([PropTypes.func, PropTypes.node]),
+
+  /**
+   * The message. Can be raw text or text components.
+   */
+  content: PropTypes.oneOfType([PropTypes.string, PropTypes.node]),
+
+  /**
+   * Select english or french copy for the accessible label.
+   */
+  copy: PropTypes.oneOf(['en', 'fr']),
+
+  /**
+   * Use to place the tooltip in a specific location (only if it fits within viewport).
+   */
+  position: PropTypes.oneOf(['auto', 'above', 'right', 'below', 'left']),
+  tokens: getTokensPropType('Tooltip'),
+  variant: variantProp.propType
+};
+export default Tooltip;
+const staticStyles = StyleSheet.create({
+  container: {
+    alignItems: 'flex-start'
+  },
+  tooltip: {
+    position: 'absolute',
+    maxWidth: 240,
+    top: 0,
+    left: 0
+  },
+  tooltipHidden: {
+    opacity: 0
+  },
+  arrow: {
+    position: 'absolute'
+  }
+});

package/lib-module/Tooltip/dictionary.js

@@ -0,0 +1,8 @@
+export default {
+  en: {
+    a11yText: 'Reveal additional information.'
+  },
+  fr: {
+    a11yText: 'Afficher des renseignements supplémentaires.'
+  }
+};

package/lib-module/Tooltip/getTooltipPosition.js

@@ -0,0 +1,164 @@
+function normalizePosition(position) {
+  const {
+    left,
+    right,
+    bottom,
+    top,
+    width,
+    ...rest
+  } = position; // adjust the coordinates so that it fits within the window
+
+  const normalized = {
+    left: Math.max(0, left),
+    right: Math.max(0, right),
+    top: Math.max(0, top),
+    bottom // since it's ok the make the document grow downwards - no need to normalize here
+
+  };
+
+  const getAbsoluteDiff = (value1, value2) => Math.abs(Math.abs(value1) - Math.abs(value2)); // adjust the width by whatever has been subtracted from left or right
+
+
+  normalized.width = width - Math.abs(getAbsoluteDiff(left, normalized.left) - getAbsoluteDiff(right, normalized.right));
+
+  if (normalized.top !== top) {
+    normalized.bottom += normalized.top - top;
+  }
+
+  const isNormalized = normalized.right !== right || normalized.left !== left || normalized.top !== top;
+  return { ...normalized,
+    ...rest,
+    isNormalized
+  };
+}
+
+function invertPosition(position) {
+  switch (position) {
+    case 'above':
+      return 'below';
+
+    case 'below':
+      return 'above';
+
+    case 'left':
+      return 'right';
+
+    default:
+      return 'left';
+  }
+}
+
+function findRectByPosition(position, rectsArray) {
+  return rectsArray.find(({
+    position: rectPosition
+  }) => rectPosition === position);
+}
+/**
+ * Used for absolute positioning of the tooltip. Since the tooltip is always centered relatively
+ * to the control (button) and we have a limited set of positions, an easy and consistent way
+ * of positioning it is to check all of the possible positions and pick one that will be rendered
+ * within the window bounds. This way we can also rely on the tooltip being actually rendered
+ * before it is shown, which makes it account for the width being limiting in styles, custom font
+ * rendering, etc.
+ */
+
+
+function getTooltipPosition(position, {
+  controlLayout,
+  tooltipDimensions,
+  windowDimensions,
+  arrowWidth = 0,
+  arrowOffset = 0
+}) {
+  const {
+    width: controlWidth,
+    height: controlHeight,
+    x: controlX,
+    y: controlY
+  } = controlLayout;
+  const {
+    width: tooltipWidth,
+    height: tooltipHeight
+  } = tooltipDimensions;
+  const {
+    width: windowWidth,
+    height: windowHeight
+  } = windowDimensions;
+  const arrowSize = arrowWidth / 2 + arrowOffset;
+  const horizontalBounds = {
+    left: controlX + controlWidth / 2 - tooltipWidth / 2,
+    right: windowWidth - (controlX + controlWidth / 2 + tooltipWidth / 2)
+  };
+  const verticalBounds = {
+    top: controlY + controlHeight / 2 - tooltipHeight / 2,
+    bottom: windowHeight - (controlY + controlHeight / 2 + tooltipHeight / 2)
+  }; // calculate absolute coordinates for each of the potential positions (relative to window)
+
+  const boundingRects = [{
+    position: 'above',
+    ...horizontalBounds,
+    top: controlY - tooltipHeight - arrowSize,
+    bottom: windowHeight - (controlY - arrowSize)
+  }, {
+    position: 'right',
+    ...verticalBounds,
+    left: controlX + controlWidth + arrowSize,
+    right: windowWidth - (controlX + controlWidth + tooltipWidth + arrowSize)
+  }, {
+    position: 'below',
+    ...horizontalBounds,
+    top: controlY + controlHeight + arrowSize,
+    bottom: windowHeight - (controlY + controlHeight + tooltipHeight + arrowSize)
+  }, {
+    position: 'left',
+    ...verticalBounds,
+    left: controlX - tooltipWidth - arrowSize,
+    right: windowWidth - (controlX - arrowSize)
+  }].map(rect => {
+    // an absolute value representing how much of the tooltip is overflowing the window on each side
+    const windowOverflow = Math.abs(Math.min(rect.top, 0) - Math.min(rect.left, 0) - Math.min(rect.right, 0) - Math.min(rect.bottom, 0));
+    return { ...rect,
+      ...tooltipDimensions,
+      overflow: windowOverflow,
+      isNormalized: false
+    };
+  }); // the 'position' prop overrides the automatic positioning
+
+  if (position !== 'auto') {
+    let rect = findRectByPosition(position, boundingRects); // check if the suggested 'position' fits in window
+
+    if (rect.overflow === 0) {
+      return rect;
+    } // otherwise try the inverted position (e.g. left -> right)
+
+
+    rect = findRectByPosition(invertPosition(position), boundingRects);
+
+    if (rect.overflow === 0) {
+      return rect;
+    }
+  }
+
+  const inWindow = boundingRects.filter(({
+    overflow
+  }) => overflow === 0); // pick the first position that fits in window
+  // (these are sorted clockwise which makes them show where one would expect them to be)
+
+  if (inWindow.length > 0) {
+    return inWindow[0];
+  } // if all positions would end up being out of window bounds, let's pick the one that is
+  // the least overflowing and normalize its position to fit within window bounds
+
+
+  boundingRects.sort(({
+    overflow: overflowA
+  }, {
+    overflow: overflowB
+  }) => overflowA - overflowB);
+  const leastOverflowing = boundingRects[0]; // prefer 'below' over 'above', since we can always expand the document downwards,
+  // and 'above' might cause issues on small viewports with large tooltips
+
+  return normalizePosition(leastOverflowing.position === 'above' ? findRectByPosition('below', boundingRects) : leastOverflowing);
+}
+
+export default getTooltipPosition;

package/lib-module/Tooltip/index.js

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

package/lib-module/TooltipButton/TooltipButton.js

@@ -0,0 +1,71 @@
+import React from 'react';
+import View from "react-native-web/dist/exports/View";
+import PropTypes from 'prop-types';
+import { useThemeTokens, applyOuterBorder } from '../ThemeProvider';
+import { a11yProps, getTokensPropType, selectSystemProps, variantProp, viewProps } from '../utils';
+import Icon from '../Icon';
+import { jsx as _jsx } from "react/jsx-runtime";
+const [selectProps, selectedSystemPropTypes] = selectSystemProps([a11yProps, viewProps]);
+
+const selectInnerContainerStyles = ({
+  borderRadius,
+  width
+}) => ({
+  borderRadius,
+  width
+});
+
+const selectIconTokens = ({
+  iconSize,
+  iconColor
+  /* iconScale = 1 */
+
+}) => ({
+  size: iconSize,
+  color: iconColor // scale: iconScale TODO re-enable with icon component
+
+});
+/**
+ * `TooltipButton` is a helper component used as a default control for the `Tooltip` component.
+ * In fact though, it isn't actually a pressable - it's meant to be used as pressable's content.
+ * Due to this any interaction states (e.g. pressed, hover, etc.) has to be passed down to it as a prop.
+ */
+
+
+const TooltipButton = ({
+  pressableState,
+  tokens,
+  variant,
+  ...rest
+}) => {
+  const themeTokens = useThemeTokens('TooltipButton', tokens, variant, pressableState);
+  const {
+    icon: IconComponent
+  } = themeTokens;
+  return /*#__PURE__*/_jsx(View, {
+    style: applyOuterBorder(themeTokens),
+    ...selectProps(rest),
+    children: /*#__PURE__*/_jsx(View, {
+      style: selectInnerContainerStyles(themeTokens),
+      children: IconComponent && /*#__PURE__*/_jsx(Icon, {
+        icon: IconComponent,
+        tokens: selectIconTokens(themeTokens)
+      })
+    })
+  });
+};
+
+TooltipButton.propTypes = { ...selectedSystemPropTypes,
+
+  /**
+   * Used as appearances when resolving theme tokens.
+   */
+  pressableState: PropTypes.shape({
+    pressed: PropTypes.bool,
+    hover: PropTypes.bool,
+    focus: PropTypes.bool
+  }),
+  tokens: getTokensPropType('TooltipButton'),
+  variant: variantProp.propType
+};
+export default TooltipButton;

package/lib-module/TooltipButton/index.js

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

package/lib-module/Typography/Typography.js

@@ -0,0 +1,118 @@
+import React, { forwardRef } from 'react';
+import PropTypes from 'prop-types';
+import Text from "react-native-web/dist/exports/Text";
+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';
+/**
+ * @typedef {import('../utils/a11y/semantics').TextTag} TextTag
+ */
+
+import { jsx as _jsx } from "react/jsx-runtime";
+const [selectProps, selectedSystemPropTypes] = selectSystemProps([a11yProps, viewProps]);
+
+const selectTextStyles = ({
+  fontWeight,
+  fontSize,
+  color,
+  lineHeight,
+  fontName,
+  textAlign,
+  textTransform,
+  letterSpacing
+}) => applyTextStyles({
+  fontWeight,
+  fontSize,
+  color,
+  lineHeight,
+  fontName,
+  textAlign,
+  textTransform,
+  letterSpacing
+}); // General-purpose flexible theme-neutral base component for text
+
+
+const Typography = /*#__PURE__*/forwardRef(({
+  children,
+  variant,
+  heading,
+  tag = typeof heading === 'string' ? heading : undefined,
+  accessibilityRole = heading === true ? 'header' : undefined,
+  block = false,
+  align = undefined,
+  tokens,
+  dataSet,
+  ...rest
+}, ref) => {
+  const viewport = useViewport();
+  const themeTokens = useThemeTokens('Typography', tokens, variant, {
+    viewport
+  });
+  const textProps = {
+    style: selectTextStyles(align ? { ...themeTokens,
+      textAlign: align
+    } : themeTokens),
+    dataSet,
+    maxFontSizeMultiplier: getMaxFontMultiplier(themeTokens)
+  };
+  const selectedProps = selectProps({ ...getA11yPropsFromHtmlTag(tag, accessibilityRole),
+    ...rest
+  });
+  return block ? /*#__PURE__*/_jsx(View, {
+    ref: ref,
+    ...selectedProps,
+    children: /*#__PURE__*/_jsx(Text, { ...textProps,
+      children: children
+    })
+  }) : /*#__PURE__*/_jsx(Text, {
+    ref: ref,
+    ...textProps,
+    ...selectedProps,
+    children: children
+  });
+});
+Typography.displayName = 'Typography';
+Typography.propTypes = { ...selectedSystemPropTypes,
+  tokens: getTokensPropType('Typography'),
+  variant: variantProp.propType,
+
+  /**
+   * Renders the text as a semantic heading. If a html heading tag is provided, uses that tag on Web.
+   *
+   * Does not affect styling: <Typography heading="h2"> will render a <h2> that looks like plain text.
+   * Use both `heading` and `variant` props to render semantic headings that look like headings.
+   *
+   * In native apps, if this is `true` or any html heading tag string and accessibilityRole prop
+   * is not defined, the accessibilityRole will default to "heading".
+   */
+  heading: PropTypes.oneOf([...headingTags, true]),
+
+  /**
+   * Optional semantic HTML tag, to apply to the text on web. Does not change styling.
+   *
+   * `tag` and `heading` props set the same thing, so shouldn't be used together (`tag` overrides `heading`).
+   *
+   * 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(textTags),
+
+  /**
+   * If true, forces the element to behave as a View block even if nested in other text
+   */
+  block: PropTypes.bool,
+
+  /**
+   * Works the same as css text-align, note that RN doesn't support "start" or "end" (see https://reactnative.dev/docs/text-style-props#textalign)
+   * Justify is known to make text harder to read, especially for people with dyslexia (see https://developer.mozilla.org/en-US/docs/Web/CSS/text-align#accessibility_concerns)
+   */
+  align: PropTypes.oneOf(['auto', 'left', 'right', 'center', 'justify']),
+
+  /**
+   * Same children allowed as a React Native <Text> node
+   */
+  children: PropTypes.node
+};
+export default Typography;

package/lib-module/Typography/index.js

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