@telus-uds/components-base 0.0.2-prerelease.4 → 0.0.2-prerelease.8

package/src/ThemeProvider/utils/styles.js

@@ -9,6 +9,7 @@ import { fontBasePixels } from '@telus-uds/system-constants'
 // Make design tokens fit React Native's text styles' specific requirements and quirks
 export function applyTextStyles({
   fontSize,
+  fontScaleCap,
   lineHeight,
   letterSpacing,
   fontWeight = '400',
@@ -27,7 +28,7 @@ export function applyTextStyles({
     styles.lineHeight = lineHeight * (fontSize || fontBasePixels)
   }
 
-  if (typeof letterSpacing === 'number') {
+  if (typeof letterSpacing === 'number' && letterSpacing) {
     // Same as for line heights - React Native expects absolute letter spacing value
     styles.letterSpacing = letterSpacing * (fontSize || fontBasePixels)
   }
@@ -133,7 +134,19 @@ export function verticalAlignRow(verticalAlign, reverse = false) {
   }
 }
 
-// React Native Views behave like flex blocks. There's no CSS 'display' and they can't inline themselves
-export function applyLayoutStyles() {
-  // TODO: map design tokens to styles that implement inline, stretch, center, etc
-}
+/**
+ * Use on an outer container to create an outer border with an optional gap around it
+ * that matches the border radius of any inner border.
+ */
+export const applyOuterBorder = ({
+  outerBorderColor,
+  outerBorderWidth = 0,
+  outerBorderGap = 0,
+  borderRadius = 0
+}) => ({
+  margin: 0 - outerBorderWidth - outerBorderGap,
+  padding: outerBorderGap,
+  borderRadius: borderRadius + outerBorderGap + outerBorderWidth,
+  borderWidth: outerBorderWidth,
+  borderColor: outerBorderColor
+})

package/src/ThemeProvider/utils/theme-tokens.js

@@ -1,3 +1,5 @@
+import PropTypes from 'prop-types'
+
 /**
  * @typedef {import('../../utils/propTypes.js').AppearanceSet} AppearanceSet
  * @typedef {import('../../utils/propTypes.js').TokensProp} TokensProp
@@ -37,15 +39,22 @@ export const doesThemeRuleApply = (rule, appearances) =>
   Object.entries(rule.if).every((condition) => doesThemeConditionApply(condition, appearances))
 
 /**
- * Turns a tokens prop and an optional tokens override prop (either or both of which may be a tokens getter function)
- * into one tokens set object where overrides are applied over the resolved default tokens.
+ * Turns a tokens prop (which may be either a tokens object or a tokens getter function)
+ * into one resolved tokens object, based on current appearances state.
+ *
+ * This is used inside `useThemeTokens` and `useThemeTokensCallback` for handling the `tokens`
+ * props of themed components. It may also be used directly in cases where a non-themed component
+ * needs to resolve a tokens prop that may be a tokens getter function or a resolved tokens object.
+ *
+ * A second tokens prop of tokens overrides may optionally be passed; it will be resolved to an object
+ * based on provided appearance state and then shallow-merged over the first set of tokens.
  *
  * @param {TokensProp} defaultTokens - a set of tokens or tokens getter function which may be overridden
- * @param {TokensProp} [tokenOverrides] - optional set of tokens or tokens getter function to override the default
  * @param {AppearanceSet} [appearances] - optional appearance set to pass to tokens getter functions
+ * @param {TokensProp} [tokenOverrides] - optional set of tokens or tokens getter function to override the default
  * @returns {TokensSet} - object containing resolved tokens with overrides applied
  */
-export const resolveTokens = (defaultTokens, tokenOverrides, appearances = {}) => {
+export const resolveThemeTokens = (defaultTokens, appearances = {}, tokenOverrides) => {
   const resolve = (tokens) => (typeof tokens === 'function' ? tokens(appearances) : tokens)
   if (!tokenOverrides) return resolve(defaultTokens)
 
@@ -56,6 +65,27 @@ export const resolveTokens = (defaultTokens, tokenOverrides, appearances = {}) =
   )
 }
 
+/**
+ * Gives a prop types error if a set of resolved tokens doesn't match a provided prop
+ * types validator.
+ *
+ * In production, this is a no-op (PropTypes.checkPropTypes is automatically replaced
+ * with a no-op function).
+ *
+ * @param {TokensSet} themeTokens - object containing resolved theme tokens
+ * @param {function} validator - PropTypes validator function
+ * @param {string} componentName - identifier to display in PropType error messages
+ */
+export const validateThemeTokens = (themeTokens, validator, componentName) => {
+  PropTypes.checkPropTypes(
+    { tokens: validator },
+    { tokens: themeTokens },
+    'resolved token',
+    componentName
+  )
+  return themeTokens
+}
+
 /**
  * Merges variants over states. Must be merged in that order to allow static showcases of a state,
  * e.g. `<Button variant={{ pressed: true }} />` where button's pressed state is `false` by default.
@@ -68,6 +98,17 @@ export const resolveTokens = (defaultTokens, tokenOverrides, appearances = {}) =
 export const mergeAppearances = (variants = {}, states) =>
   states ? { ...states, ...variants } : variants
 
+/**
+ * Get a set of theme tokens by applying a theme's component rules based on a component's variants and state.
+ *
+ * This is used internally in `useThemeTokens` and `useThemeTokensCallback` and should not normally be called directly.
+ *
+ * @param {object} componentTheme - object containing a theme's `tokens` and `rules` for a component
+ * @param {object|function} [tokensProp] - UDS tokens prop containing theming overrides
+ * @param {object} [variants] - UDS variant prop containing the variant options for this component instance
+ * @param {object} [states] - object containing current state options for this component instance
+ * @returns {object} Set of resolved theme tokens
+ */
 export const getThemeTokens = (
   { rules = [], tokens: defaultThemeTokens = {} },
   tokensProp,
@@ -88,7 +129,7 @@ export const getThemeTokens = (
         : mergedTokens,
     defaultThemeTokens
   )
-  return resolveTokens(themeTokens, tokensProp, appearances)
+  return resolveThemeTokens(themeTokens, appearances, tokensProp)
 }
 
 export const toArray = (strOrArr) => (Array.isArray(strOrArr) ? strOrArr : [strOrArr])

package/src/ToggleSwitch/ToggleSwitch.jsx

@@ -21,8 +21,7 @@ const selectButtonTokens = (tokens) =>
   })
 
 // Map and rename icon-specific tokens to name used within Icon
-const selectIconTokens = ({ iconSize, iconColor, iconOpacity }) => ({
-  opacity: iconOpacity,
+const selectIconTokens = ({ iconSize, iconColor }) => ({
   size: iconSize,
   color: iconColor
 })
@@ -103,7 +102,7 @@ const ToggleSwitch = ({
         return (
           <View style={[staticStyles.track, trackStyles]}>
             <View style={[staticStyles.switch, switchStyles, switchPositionStyle]}>
-              {IconComponent && <IconComponent tokens={iconTokens} />}
+              {IconComponent && <IconComponent {...iconTokens} />}
             </View>
           </View>
         )
@@ -142,7 +141,7 @@ ToggleSwitch.propTypes = {
 
 const staticStyles = StyleSheet.create({
   track: {
-    flex: 1,
+    flexGrow: 1,
     alignSelf: 'stretch',
     flexDirection: 'row'
   },

package/src/Tooltip/Backdrop.jsx

@@ -0,0 +1,60 @@
+import { useEffect, useState } from 'react'
+import ReactDOM from 'react-dom'
+import PropTypes from 'prop-types'
+
+function createPortalNode(nodeId) {
+  const node = document.createElement('div')
+
+  node.id = nodeId
+
+  // we're mimicking React Native's Modal component, except for using an `absolute` position
+  // this way the backdrop stays in place when scrolling the window - that's why we need to
+  // position it at the scroll position when rendering
+  node.style.cssText = `
+  position: absolute; 
+  top: ${window.scrollY}px;
+  left: ${window.scrollX}px; 
+  right: 0; 
+  bottom: 0; 
+  z-index: 9999; 
+  pointer-events: none;
+  `
+
+  document.body.appendChild(node)
+
+  return node
+}
+
+function removePortalNode(nodeId) {
+  const node = document.getElementById(nodeId)
+
+  node.parentElement.removeChild(node)
+}
+
+/**
+ * The Web version of Backdrop utilizes React Portal for overlaying page content, so it is
+ * dependent on ReactDOM. Tooltip's closing is handled by the onBlur callback of the control.
+ */
+function Backdrop({ children }) {
+  const [portalNode, setPortalNode] = useState()
+
+  useEffect(() => {
+    const nodeId = `tooltip-backdrop-${Date.now()}`
+
+    const node = createPortalNode(nodeId)
+
+    setPortalNode(node)
+
+    return () => {
+      removePortalNode(nodeId)
+    }
+  }, [])
+
+  return portalNode ? ReactDOM.createPortal(children, portalNode) : null
+}
+
+Backdrop.propTypes = {
+  children: PropTypes.node
+}
+
+export default Backdrop

package/src/Tooltip/Backdrop.native.jsx

@@ -0,0 +1,33 @@
+import React from 'react'
+import { TouchableWithoutFeedback, Modal, StyleSheet, View } from 'react-native'
+import PropTypes from 'prop-types'
+
+/**
+ * The Native version of Backdrop utilizes React Native's Modal component for overlaying
+ * the app's content, since this is the only reliable to do it. The only drawback of this
+ * approach is that a press on the Backdrop will actually stop the press event from propagating,
+ * i.e. anything rendered beneath the Backdrop can't be pressed until the Backdrop is closed.
+ */
+function Backdrop({ onPress, children }) {
+  return (
+    <Modal transparent>
+      <TouchableWithoutFeedback onPress={onPress}>
+        <View style={staticStyles.backdrop}>{children}</View>
+      </TouchableWithoutFeedback>
+    </Modal>
+  )
+}
+
+export default Backdrop
+
+Backdrop.propTypes = {
+  onPress: PropTypes.func,
+  children: PropTypes.node
+}
+
+const staticStyles = StyleSheet.create({
+  backdrop: {
+    flexBasis: '100%',
+    backgroundColor: 'rgba(255, 255, 255, 0.5)' // to visually mark that the content beneath is not pressable
+  }
+})

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 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 = ({ 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.'
+  }
+}