@telus-uds/components-base 2.4.0 → 3.0.0

package/lib/cjs/Tooltip/Tooltip.native.js

@@ -0,0 +1,370 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.default = void 0;
+var _react = _interopRequireDefault(require("react"));
+var _Dimensions = _interopRequireDefault(require("react-native-web/dist/cjs/exports/Dimensions"));
+var _Platform = _interopRequireDefault(require("react-native-web/dist/cjs/exports/Platform"));
+var _Pressable = _interopRequireDefault(require("react-native-web/dist/cjs/exports/Pressable"));
+var _StyleSheet = _interopRequireDefault(require("react-native-web/dist/cjs/exports/StyleSheet"));
+var _Text = _interopRequireDefault(require("react-native-web/dist/cjs/exports/Text"));
+var _View = _interopRequireDefault(require("react-native-web/dist/cjs/exports/View"));
+var _shared = _interopRequireDefault(require("./shared"));
+var _ThemeProvider = require("../ThemeProvider");
+var _utils = require("../utils");
+var _Backdrop = _interopRequireDefault(require("./Backdrop"));
+var _getTooltipPosition = _interopRequireDefault(require("./getTooltipPosition"));
+var _TooltipButton = _interopRequireDefault(require("../TooltipButton"));
+var _useCopy = _interopRequireDefault(require("../utils/useCopy"));
+var _dictionary = _interopRequireDefault(require("./dictionary"));
+var _jsxRuntime = require("react/jsx-runtime");
+function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
+const [selectProps, selectedSystemPropTypes] = (0, _utils.selectSystemProps)([_utils.a11yProps, _utils.viewProps]);
+const selectTooltipStyles = _ref => {
+  let {
+    backgroundColor,
+    paddingTop,
+    paddingBottom,
+    paddingLeft,
+    paddingRight,
+    borderRadius
+  } = _ref;
+  return {
+    backgroundColor,
+    paddingTop,
+    paddingBottom,
+    paddingLeft,
+    paddingRight,
+    borderRadius
+  };
+};
+const selectTooltipShadowStyles = _ref2 => {
+  let {
+    shadow,
+    borderRadius
+  } = _ref2;
+  return {
+    borderRadius,
+    ...(0, _ThemeProvider.applyShadowToken)(shadow)
+  };
+};
+const selectToolTipSizeStyles = _ref3 => {
+  let {
+    maxWidth,
+    minWidth
+  } = _ref3;
+  return {
+    maxWidth,
+    minWidth
+  };
+};
+const selectTooltipPositionStyles = _ref4 => {
+  let {
+    top,
+    left,
+    width
+  } = _ref4;
+  return {
+    top,
+    left,
+    width
+  };
+};
+const selectArrowStyles = (_ref5, _ref6) => {
+  let {
+    backgroundColor,
+    arrowWidth,
+    arrowBorderRadius,
+    shadow
+  } = _ref5;
+  let {
+    position,
+    width: tooltipWidth,
+    height: tooltipHeight
+  } = _ref6;
+  // 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 <= 45 ? tooltipHeight / 2 - horizontalOffset : tooltipHeight - (tooltipHeight - 10),
+      transform: [{
+        rotateZ: '-45deg'
+      }]
+    },
+    right: {
+      left: verticalOffset,
+      top: tooltipHeight <= 45 ? tooltipHeight / 2 - horizontalOffset : tooltipHeight - (tooltipHeight - 10),
+      transform: [{
+        rotateZ: '135deg'
+      }]
+    }
+  };
+  return {
+    backgroundColor,
+    width: rectangleSide,
+    height: rectangleSide,
+    borderBottomRightRadius: arrowBorderRadius,
+    // this corner will be the arrow tip after rotation
+    ...(0, _ThemeProvider.applyShadowToken)(shadow),
+    ...directionalStyles[position]
+  };
+};
+const selectTextStyles = tokens => (0, _ThemeProvider.applyTextStyles)((0, _utils.selectTokens)('Typography', tokens));
+const defaultControl = (pressableState, variant, tokens) => /*#__PURE__*/(0, _jsxRuntime.jsx)(_TooltipButton.default, {
+  pressableState: pressableState,
+  variant: variant,
+  tokens: tokens
+});
+
+/**
+ * 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__*/_react.default.forwardRef((_ref7, ref) => {
+  let {
+    children,
+    content,
+    position = 'auto',
+    copy = 'en',
+    onPress = () => {},
+    tokens,
+    variant,
+    inline = false,
+    nativeID,
+    activateOnHover = false,
+    tooltipButtonTokens,
+    ...rest
+  } = _ref7;
+  const [isOpen, setIsOpen] = _react.default.useState(false);
+  const controlRef = _react.default.useRef();
+  const [controlLayout, setControlLayout] = _react.default.useState(null);
+  const [tooltipDimensions, setTooltipDimensions] = _react.default.useState(null);
+  const [windowDimensions, setWindowDimensions] = _react.default.useState(_Dimensions.default.get('window'));
+  const [tooltipPosition, setTooltipPosition] = _react.default.useState(null);
+  const getCopy = (0, _useCopy.default)({
+    dictionary: _dictionary.default,
+    copy
+  });
+  const themeTokens = (0, _ThemeProvider.useThemeTokens)('Tooltip', tokens, variant);
+  const {
+    arrowWidth,
+    arrowOffset
+  } = themeTokens;
+  _react.default.useEffect(() => {
+    const subscription = _Dimensions.default.addEventListener('change', _ref8 => {
+      let {
+        window
+      } = _ref8;
+      setWindowDimensions(window);
+    });
+    return () => subscription?.remove();
+  });
+  const toggleIsOpen = () => {
+    onPress();
+    setIsOpen(!isOpen);
+  };
+  const close = () => setIsOpen(false);
+  const getPressableState = _ref9 => {
+    let {
+      pressed,
+      hovered,
+      focused
+    } = _ref9;
+    return {
+      pressed,
+      hover: hovered,
+      focus: focused
+    };
+  };
+  const onTooltipLayout = _ref10 => {
+    let {
+      nativeEvent: {
+        layout: {
+          width,
+          height
+        }
+      }
+    } = _ref10;
+    if (tooltipDimensions === null || tooltipDimensions.width !== width || tooltipDimensions.height !== height) {
+      setTooltipDimensions({
+        width: _Platform.default.select({
+          web: width + 0.3,
+          // avoids often unnecessary line breaks due to subpixel rendering of fonts
+          native: width
+        }),
+        height
+      });
+    }
+  };
+  _react.default.useEffect(() => {
+    if (isOpen) {
+      controlRef.current.measureInWindow((x, y, width, height) => {
+        setControlLayout({
+          x,
+          y,
+          width,
+          height
+        });
+      });
+    } else {
+      setControlLayout(null);
+      setTooltipDimensions(null);
+      setTooltipPosition(null);
+    }
+  }, [isOpen]);
+  _react.default.useEffect(() => {
+    setIsOpen(false);
+  }, [windowDimensions]);
+  _react.default.useEffect(() => {
+    if (tooltipPosition !== null && !tooltipPosition?.isNormalized || !isOpen || controlLayout === null || tooltipDimensions == null) {
+      return;
+    }
+    const updatedPosition = (0, _getTooltipPosition.default)(position, {
+      controlLayout,
+      tooltipDimensions,
+      windowDimensions,
+      arrowWidth,
+      arrowOffset
+    });
+
+    // avoid ending up in an infinite normalization loop
+    if (tooltipPosition?.isNormalized && updatedPosition.isNormalized) {
+      return;
+    }
+    setTooltipPosition(updatedPosition);
+  }, [isOpen, position, tooltipDimensions, controlLayout, windowDimensions, arrowWidth, arrowOffset, tooltipPosition]);
+  _react.default.useEffect(() => {
+    if (_Platform.default.OS !== 'web') {
+      return undefined;
+    }
+    const handleHover = event => {
+      if (activateOnHover) {
+        const isInsideControl = controlRef.current && controlRef.current.contains(event.target);
+        if (isInsideControl) {
+          if (!isOpen) {
+            setIsOpen(!isOpen);
+          }
+        } else {
+          close();
+        }
+      }
+    };
+    document.addEventListener('mouseover', handleHover, {
+      capture: true
+    });
+    return () => {
+      document.removeEventListener('mouseover', handleHover, {
+        capture: true
+      });
+    };
+  }, [controlLayout, activateOnHover, isOpen, onPress]);
+  const control = children !== undefined ? children : defaultControl;
+  const pressableStyles = control === defaultControl ? _Platform.default.select({
+    web: {
+      outline: 'none'
+    }
+  }) : undefined;
+  const pressableHitSlop = control === defaultControl ? {
+    top: 10,
+    bottom: 10,
+    left: 10,
+    right: 10
+  } : undefined;
+  return /*#__PURE__*/(0, _jsxRuntime.jsxs)(_View.default, {
+    style: [staticStyles.container, _Platform.default.select({
+      web: {
+        display: inline ? 'inline-block' : 'flex'
+      }
+    })],
+    ...selectProps(rest),
+    children: [/*#__PURE__*/(0, _jsxRuntime.jsx)(_Pressable.default, {
+      onPress: toggleIsOpen,
+      ref: controlRef,
+      onBlur: close,
+      style: pressableStyles,
+      hitSlop: pressableHitSlop,
+      accessibilityLabel: getCopy('a11yText'),
+      accessibilityRole: "button",
+      nativeID: nativeID,
+      children: typeof control === 'function' ? pressableState => control(getPressableState(pressableState), variant, tooltipButtonTokens) : control
+    }), isOpen && /*#__PURE__*/(0, _jsxRuntime.jsx)(_Backdrop.default, {
+      onPress: close,
+      children: /*#__PURE__*/(0, _jsxRuntime.jsxs)(_View.default, {
+        ref: ref,
+        style: [staticStyles.tooltip, selectTooltipShadowStyles(themeTokens),
+        // applied separately so that it doesn't cover the arrow
+        selectToolTipSizeStyles(themeTokens), tooltipPosition && selectTooltipPositionStyles(tooltipPosition), (tooltipPosition === null || tooltipPosition?.isNormalized) && staticStyles.tooltipHidden // visually hide the tooltip until we have a final measurement
+        ],
+        onLayout: onTooltipLayout,
+        accessibilityRole: "alert",
+        children: [/*#__PURE__*/(0, _jsxRuntime.jsx)(_View.default, {
+          style: [staticStyles.arrow, tooltipPosition && selectArrowStyles(themeTokens, tooltipPosition)]
+        }), /*#__PURE__*/(0, _jsxRuntime.jsx)(_View.default, {
+          style: selectTooltipStyles(themeTokens),
+          children: /*#__PURE__*/(0, _jsxRuntime.jsx)(_Text.default, {
+            style: selectTextStyles(themeTokens),
+            children: content
+          })
+        })]
+      })
+    })]
+  });
+});
+Tooltip.displayName = 'NativeTooltip';
+Tooltip.propTypes = {
+  ...selectedSystemPropTypes,
+  ..._shared.default
+};
+var _default = exports.default = Tooltip;
+const staticStyles = _StyleSheet.default.create({
+  container: {
+    alignItems: 'flex-start'
+  },
+  tooltip: {
+    position: 'absolute',
+    top: 0,
+    left: 0
+  },
+  tooltipHidden: {
+    opacity: 0
+  },
+  arrow: {
+    position: 'absolute'
+  }
+});

package/lib/cjs/Tooltip/dictionary.js

@@ -0,0 +1,14 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.default = void 0;
+var _default = exports.default = {
+  en: {
+    a11yText: 'Reveal additional information.'
+  },
+  fr: {
+    a11yText: 'Afficher des renseignements supplémentaires.'
+  }
+};

package/lib/cjs/Tooltip/getTooltipPosition.js

@@ -0,0 +1,175 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.default = void 0;
+function getAbsolutePosition(position) {
+  const {
+    left,
+    right,
+    bottom,
+    top,
+    width,
+    ...rest
+  } = position;
+
+  // adjust the coordinates so that it fits within the window
+  const finalPosition = {
+    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
+  finalPosition.width = width - Math.abs(getAbsoluteDiff(left, finalPosition.left) - getAbsoluteDiff(right, finalPosition.right));
+  if (finalPosition.top !== top) {
+    finalPosition.bottom += finalPosition.top - top;
+  }
+  return {
+    ...finalPosition,
+    ...rest,
+    isNormalized: false
+  };
+}
+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(_ref => {
+    let {
+      position: rectPosition
+    } = _ref;
+    return 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, _ref2) {
+  let {
+    controlLayout,
+    tooltipDimensions,
+    windowDimensions,
+    arrowWidth = 0,
+    arrowOffset = 0
+  } = _ref2;
+  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,
+    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(_ref3 => {
+    let {
+      overflow
+    } = _ref3;
+    return 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((_ref4, _ref5) => {
+    let {
+      overflow: overflowA
+    } = _ref4;
+    let {
+      overflow: overflowB
+    } = _ref5;
+    return 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 getAbsolutePosition(leastOverflowing.position === 'above' ? findRectByPosition('below', boundingRects) : leastOverflowing);
+}
+var _default = exports.default = getTooltipPosition;

package/lib/cjs/Tooltip/index.js

@@ -0,0 +1,12 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.default = void 0;
+var _Dimensions = _interopRequireDefault(require("react-native-web/dist/cjs/exports/Dimensions"));
+var _Tooltip = _interopRequireDefault(require("./Tooltip"));
+var _Tooltip2 = _interopRequireDefault(require("./Tooltip.native"));
+function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
+const Tooltip = !_Dimensions.default.get('screen').width <= 340 ? _Tooltip2.default : _Tooltip.default;
+var _default = exports.default = Tooltip;

package/lib/cjs/Tooltip/shared.js

@@ -0,0 +1,48 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.default = void 0;
+var _propTypes = _interopRequireDefault(require("prop-types"));
+var _utils = require("../utils");
+function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
+const propTypes = {
+  /**
+   * 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.default.oneOfType([_propTypes.default.func, _propTypes.default.node]),
+  /**
+   * The message. Can be raw text or text components.
+   */
+  content: _propTypes.default.oneOfType([_propTypes.default.string, _propTypes.default.node]),
+  /**
+   * Select English or French copy for the accessible label.
+   */
+  copy: _propTypes.default.oneOf(['en', 'fr']),
+  /**
+   * Use to place the tooltip in a specific location (only if it fits within viewport).
+   */
+  position: _propTypes.default.oneOf(['auto', 'above', 'right', 'below', 'left']),
+  /**
+   * Display tooltip icon button as an inline element.
+   */
+  inline: _propTypes.default.bool,
+  /**
+   * Callback function triggered when the tooltip is pressed.
+   */
+  onPress: _propTypes.default.func,
+  /**
+   * The `id` of the tooltip button.
+   */
+  nativeID: _propTypes.default.string,
+  /**
+   * Set to `true` to open the tooltip on hover
+   */
+  activateOnHover: _propTypes.default.bool,
+  tooltipButtonTokens: (0, _utils.getTokensPropType)('TooltipButton'),
+  tokens: (0, _utils.getTokensPropType)('Tooltip'),
+  variant: _utils.variantProp.propType
+};
+var _default = exports.default = propTypes;