@telus-uds/components-base 1.24.1 → 1.24.2

package/src/Tooltip/Tooltip.native.jsx

@@ -0,0 +1,283 @@
+import React, { forwardRef, useEffect, useRef, useState } from 'react'
+import { Dimensions, Platform, Pressable, StyleSheet, Text, View } from 'react-native'
+import propTypes from './shared'
+
+import { applyShadowToken, applyTextStyles, useThemeTokens } from '../ThemeProvider'
+import { a11yProps, selectSystemProps, selectTokens, viewProps } from '../utils'
+import Backdrop from './Backdrop'
+import getTooltipPosition from './getTooltipPosition'
+import TooltipButton from '../TooltipButton'
+import useCopy from '../utils/useCopy'
+import dictionary from './dictionary'
+
+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) => (
+  <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 = 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?.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?.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?.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 (
+      <View style={staticStyles.container} {...selectProps(rest)}>
+        <Pressable
+          onPress={toggleIsOpen}
+          ref={controlRef}
+          onBlur={close}
+          style={pressableStyles}
+          hitSlop={pressableHitSlop}
+          accessibilityLabel={getCopy('a11yText')}
+          accessibilityRole="button"
+        >
+          {typeof control === 'function'
+            ? (pressableState) => control(getPressableState(pressableState), variant)
+            : control}
+        </Pressable>
+        {isOpen && (
+          <Backdrop onPress={close}>
+            <View
+              ref={ref}
+              style={[
+                staticStyles.tooltip,
+                selectTooltipShadowStyles(themeTokens), // applied separately so that it doesn't cover the arrow
+                tooltipPosition && selectTooltipPositionStyles(tooltipPosition),
+                (tooltipPosition === null || tooltipPosition?.isNormalized) &&
+                  staticStyles.tooltipHidden // visually hide the tooltip until we have a final measurement
+              ]}
+              onLayout={onTooltipLayout}
+              accessibilityRole="alert"
+            >
+              <View
+                style={[
+                  staticStyles.arrow,
+                  tooltipPosition && selectArrowStyles(themeTokens, tooltipPosition)
+                ]}
+              />
+              <View style={selectTooltipStyles(themeTokens)}>
+                <Text style={selectTextStyles(themeTokens)}>{content}</Text>
+              </View>
+            </View>
+          </Backdrop>
+        )}
+      </View>
+    )
+  }
+)
+Tooltip.displayName = 'NativeTooltip'
+
+Tooltip.propTypes = {
+  ...selectedSystemPropTypes,
+  ...propTypes
+}
+
+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/src/Tooltip/index.js

@@ -1,3 +1,7 @@
-import Tooltip from './Tooltip'
+import { Dimensions } from 'react-native'
+import NonNativeTooltip from './Tooltip'
+import NativeToolTip from './Tooltip.native'
+
+const Tooltip = !Dimensions.get('screen').width <= 340 ? NativeToolTip : NonNativeTooltip
 
 export default Tooltip

package/src/Tooltip/shared.js

@@ -0,0 +1,27 @@
+import PropTypes from 'prop-types'
+
+import { getTokensPropType, variantProp } from '../utils'
+
+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.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 propTypes

package/src/Typography/Typography.jsx

@@ -71,6 +71,7 @@ const Typography = forwardRef(
     }
 
     const containerProps = {
+      accessibilityRole,
       ...getA11yPropsFromHtmlTag(tag, accessibilityRole),
       ...selectContainerProps(rest)
     }

package/src/utils/floating-ui/index.js

@@ -0,0 +1 @@
+export { useFloating, arrow, offset, shift, flip, autoPlacement } from '@floating-ui/react-dom'

package/src/utils/floating-ui/index.native.js

@@ -0,0 +1 @@
+export { useFloating, arrow, offset, shift, flip, autoPlacement } from '@floating-ui/react-native'