@telus-uds/components-base 0.0.2-prerelease.3 → 0.0.2-prerelease.7

package/src/Tooltip/Tooltip.jsx

@@ -0,0 +1,294 @@
+import React, { useEffect, useRef, useState } from 'react'
+import { Dimensions, Platform, Pressable, StyleSheet, Text, View } from 'react-native'
+
+import PropTypes from 'prop-types'
+import { applyShadowToken, applyTextStyles, useThemeTokens } from '../ThemeProvider'
+import { getTokensPropType, selectTokens, variantProp } from '../utils'
+import Backdrop from './Backdrop'
+import getTooltipPosition from './getTooltipPosition'
+import TooltipButton from '../TooltipButton'
+import useCopy from '../utils/useCopy'
+import dictionary from './dictionary'
+
+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 variant={{ ...pressableState, ...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 = ({ children, content, position = 'auto', copy = 'en', tokens, variant }) => {
+  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}>
+      <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
+            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.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 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/dictionary.js

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

package/src/Tooltip/getTooltipPosition.js

@@ -0,0 +1,161 @@
+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/src/Tooltip/index.js

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

package/src/TooltipButton/TooltipButton.jsx

@@ -0,0 +1,53 @@
+import React from 'react'
+import { View } from 'react-native'
+
+import { useThemeTokens } from '../ThemeProvider'
+import { getTokensPropType, variantProp } from '../utils'
+
+const selectOuterContainerStyles = ({
+  outerBorderColor,
+  outerBorderWidth = 0,
+  outerBorderGap = 0,
+  outerBorderRadius
+}) => {
+  const outerBorderOffset = -1 * (outerBorderWidth + outerBorderGap)
+
+  return {
+    marginTop: outerBorderOffset,
+    marginLeft: outerBorderOffset,
+    marginRight: outerBorderOffset,
+    marginBottom: outerBorderOffset,
+    borderColor: outerBorderColor,
+    borderWidth: outerBorderWidth,
+    padding: outerBorderGap,
+    borderRadius: outerBorderRadius
+  }
+}
+const selectInnerContainerStyles = ({ borderRadius, width }) => ({ borderRadius, width })
+
+const selectIconTokens = ({ iconSize, iconColor, iconScale = 1 }) => ({
+  size: iconSize,
+  color: iconColor,
+  scale: iconScale
+})
+
+const TooltipButton = ({ tokens, variant }) => {
+  const themeTokens = useThemeTokens('TooltipButton', tokens, variant)
+
+  const { icon: IconComponent } = themeTokens
+
+  return (
+    <View style={selectOuterContainerStyles(themeTokens)}>
+      <View style={selectInnerContainerStyles(themeTokens)}>
+        {IconComponent && <IconComponent tokens={selectIconTokens(themeTokens)} />}
+      </View>
+    </View>
+  )
+}
+
+TooltipButton.propTypes = {
+  tokens: getTokensPropType('TooltipButton'),
+  variant: variantProp.propType
+}
+
+export default TooltipButton

package/src/TooltipButton/index.js

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

package/src/Typography/Typography.jsx

@@ -1,11 +1,11 @@
 import React from 'react'
 import PropTypes from 'prop-types'
-import { Platform, Text, View } from 'react-native'
+import { Text, View } from 'react-native'
 
 import { useThemeTokens } from '../ThemeProvider'
 import { useViewport } from '../ViewportProvider'
 import { applyTextStyles } from '../ThemeProvider/utils'
-import { a11yProps, variantProp, getTokensPropType } from '../utils/propTypes'
+import { a11yProps, variantProp, getTokensPropType, getMaxFontMultiplier } from '../utils'
 
 /**
  * If passed a string like 'h1', 'h2' etc, returns the heading number as a string,
@@ -16,25 +16,12 @@ function getHeadingLevel(heading) {
   return match && match[1]
 }
 
-/**
- * Enforces `fontScaleCap` theme tokens as the maximum font size text can become
- * after iOS or Android font scaling, to give consistent accessible maximum sizes
- * that don't make the content unusable
- */
-function getMaxFontMultiplier({ fontSize, fontScaleCap }) {
-  if (!fontScaleCap || !fontSize) return undefined
-  if (fontScaleCap <= fontSize) return 1
-  return fontScaleCap / fontSize
-}
-
 const selectTextStyles = ({
   fontWeight,
   fontSize,
   color,
   lineHeight,
   fontName,
-  marginTop,
-  marginBottom,
   textAlign,
   textTransform
 }) =>
@@ -44,8 +31,6 @@ const selectTextStyles = ({
     color,
     lineHeight,
     fontName,
-    marginTop,
-    marginBottom,
     textAlign,
     textTransform
   })
@@ -64,9 +49,9 @@ const Typography = ({
   const viewport = useViewport()
   const themeTokens = useThemeTokens('Typography', tokens, variant, { viewport })
   const textProps = {
-    style: selectTextStyles(align ? { ...themeTokens, textAlign: align } : themeTokens)
+    style: selectTextStyles(align ? { ...themeTokens, textAlign: align } : themeTokens),
+    maxFontSizeMultiplier: getMaxFontMultiplier(themeTokens)
   }
-  if (Platform.OS !== 'web') textProps.maxFontSizeMultiplier = getMaxFontMultiplier(themeTokens)
 
   const headingLevel = getHeadingLevel(heading)
   const a11y = {

package/src/ViewportProvider/ViewportProvider.jsx

@@ -0,0 +1,21 @@
+import React, { useState } from 'react'
+import PropTypes from 'prop-types'
+import { viewports } from '@telus-uds/system-constants'
+import { ViewportContext } from './useViewport'
+import useViewportListener from './useViewportListener'
+
+/**
+ * Provides an up-to-date viewport value from system-constants, available via the `useViewport` hook
+ */
+const ViewportProvider = ({ children }) => {
+  // Default to the smallest viewport for mobile-first SSR. On client side, this is updated
+  // by useViewportListener in a layout effect before anything is shown to the user.
+  const [viewport, setViewport] = useState(viewports.keys[0])
+  useViewportListener(setViewport)
+  return <ViewportContext.Provider value={viewport}>{children}</ViewportContext.Provider>
+}
+ViewportProvider.propTypes = {
+  children: PropTypes.node.isRequired
+}
+
+export default ViewportProvider

package/src/ViewportProvider/index.jsx

@@ -1,43 +1,4 @@
-import React, { createContext, useState, useEffect, useContext } from 'react'
-import PropTypes from 'prop-types'
-import { Dimensions } from 'react-native'
-import { viewports } from '@telus-uds/system-constants'
-
-// we are using Dimensions instead of useWindowDimensions
-// that's because useWindowDimensions forces context to update on
-// every pixel change on the browser, therefore we used Dimension to only enforce
-// context update on viewport changes
-const lookupViewport = () => viewports.select(Dimensions.get('window').width)
-
-export const ViewportContext = createContext({})
-
-/**
- * Provides an up-to-date viewport value from system-constants, available via the `useViewport` hook
- */
-const ViewportProvider = ({ children }) => {
-  // initialize with a function so we don't re-execute on each render
-  const [viewport, setViewport] = useState(lookupViewport)
-
-  useEffect(() => {
-    const onChange = ({ window }) => setViewport(viewports.select(window.width))
-
-    Dimensions.addEventListener('change', onChange)
-    // We might have missed an update between calling `get` in render and
-    // `addEventListener` in this handler, so we set it here. If there was
-    // no change, React will filter out this update as a no-op.
-    setViewport(lookupViewport())
-    return () => {
-      Dimensions.removeEventListener('change', onChange)
-    }
-  }, [])
-
-  return <ViewportContext.Provider value={viewport}>{children}</ViewportContext.Provider>
-}
-
-ViewportProvider.propTypes = {
-  children: PropTypes.node.isRequired
-}
+import ViewportProvider from './ViewportProvider'
 
 export default ViewportProvider
-
-export const useViewport = () => useContext(ViewportContext)
+export * from './useViewport'

package/src/ViewportProvider/useViewport.js

@@ -0,0 +1,5 @@
+import { createContext, useContext } from 'react'
+
+export const ViewportContext = createContext({})
+
+export const useViewport = () => useContext(ViewportContext)