@telus-uds/components-base 0.0.2-prerelease.6 → 1.0.0

package/src/Link/ChevronLink.jsx

@@ -1,34 +1,47 @@
-import React from 'react'
+import React, { forwardRef } from 'react'
 import PropTypes from 'prop-types'
 
-import { useThemeTokens } from '../ThemeProvider'
-import Link from './Link'
+import { useThemeTokensCallback } from '../ThemeProvider'
+import { selectTokens, getTokensPropType } from '../utils'
+import LinkBase from './LinkBase'
 
 /**
  * `ChevronLink` is a convenience wrapper around the `Link` component to enable "directional" links.
  * It effectively pre-binds left and right icons, and a directional translation of the icon on hover.
  *
- * ChevronLink is not intended to be deeply themable. If you have a use case outside of the above you are better off constructing theme variants of `Link`.
- * In that vein, note that the `tokens` and `variant` system props for `ChevronLink` are passed directly to the underlying `Link` component: ChevronLink itself does not support further customisation using these system props.
+ * ChevronLink is not intended to be deeply themable; variants passed to ChevronLink are forwarded to Link.
  */
-const ChevronLink = ({ direction = 'right', children, tokens, ...linkProps }) => {
-  const { iconDisplace, leftIcon, rightIcon } = useThemeTokens('ChevronLink', {}, {})
-  const icon = direction === 'right' ? rightIcon : leftIcon
-  const tokensCallback = (linkState) => ({
-    ...(typeof tokens === 'function' ? tokens(linkState) : tokens),
-    iconGapBefore: 0,
-    iconGapAfter: 0,
-    iconTranslateX: linkState.hover ? iconDisplace * (direction === 'right' ? 1 : -1) : 0
-  })
-  return (
-    <Link iconPosition={direction} icon={icon} {...linkProps} tokens={tokensCallback}>
-      {children}
-    </Link>
-  )
-}
+const ChevronLink = forwardRef(
+  ({ direction = 'right', children, tokens, variant, dataSet, ...linkProps }, ref) => {
+    const getChevronTokens = useThemeTokensCallback('ChevronLink', tokens, variant)
+    const applyChevronTokens = (linkState) => {
+      const { leftIcon, rightIcon, iconDisplace, ...otherTokens } = getChevronTokens(linkState)
+      return {
+        ...selectTokens('Link', otherTokens),
+        icon: direction === 'right' ? rightIcon : leftIcon,
+        iconTranslateX: iconDisplace * (direction === 'right' ? 1 : -1) || 0
+      }
+    }
+
+    const getTokens = useThemeTokensCallback('Link', applyChevronTokens, variant)
+    return (
+      <LinkBase
+        {...linkProps}
+        iconPosition={direction}
+        tokens={getTokens}
+        dataSet={dataSet}
+        ref={ref}
+      >
+        {children}
+      </LinkBase>
+    )
+  }
+)
 
+ChevronLink.displayName = 'ChevronLink'
 ChevronLink.propTypes = {
-  ...Link.propTypes,
+  ...LinkBase.propTypes,
+  tokens: getTokensPropType('ChevronLink', 'Link'),
   direction: PropTypes.oneOf(['left', 'right'])
 }
 

package/src/Link/InlinePressable.jsx

@@ -0,0 +1,39 @@
+import React, { forwardRef } from 'react'
+import { Pressable, StyleSheet } from 'react-native'
+
+/**
+ * @typedef {import('react-native').PressableProps} PressableProps
+ */
+
+/**
+ * InlinePressable is an alternative to React Native's Pressable that works better when nested
+ * inline inside Text. It accepts the same props as React Native's Pressable.
+ *
+ * On Web it simply passes its props to Pressable and defaults to `inline-flex` instead of `flex`.
+ *
+ * @param {PressableProps} PressableProps
+ */
+// React Native exports prop Types but not propTypes, use JSDoc types here rather than duplicate RN
+// eslint-disable-next-line react/prop-types
+const InlinePressable = forwardRef(({ children, style, ...props }, ref) => (
+  <Pressable
+    ref={ref}
+    style={(pressState) => [
+      staticStyles.inline,
+      typeof style === 'function' ? style(pressState) : style
+    ]}
+    {...props}
+  >
+    {(pressState) => (typeof children === 'function' ? children(pressState) : children)}
+  </Pressable>
+))
+InlinePressable.displayName = 'InlinePressable'
+
+const staticStyles = StyleSheet.create({
+  inline: {
+    // Stop Pressable defaulting to (block) flex
+    display: 'inline-flex'
+  }
+})
+
+export default InlinePressable

package/src/Link/InlinePressable.native.jsx

@@ -0,0 +1,75 @@
+/* eslint-disable camelcase */
+import React, { forwardRef, useState } from 'react'
+import { Text, TouchableWithoutFeedback } from 'react-native'
+
+/**
+ * @typedef {import('react-native').PressableProps} PressableProps
+ */
+
+// TouchableWithoutFeedback and Pressable have similar but not identical props APIs
+const pressablePropsToTouchable = ({
+  unstable_pressDelay,
+  android_disableSound,
+  android_ripple, // Unsupported, discard it
+  ...props
+}) => ({
+  ...props,
+  touchSoundDisabled: android_disableSound,
+  delayPressIn: unstable_pressDelay
+})
+
+/**
+ * InlinePressable is an alternative to React Native's Pressable that works better when nested
+ * inline inside Text. It accepts the same props as React Native's Pressable.
+ *
+ * There are a lot of React Native bugs around Views/Pressables nested in Text, e.g.:
+ *
+ * - https://github.com/facebook/react-native/issues/23601#issuecomment-468069822
+ * - https://github.com/facebook/react-native/issues/30375
+ * - https://github.com/facebook/react-native/issues/31955
+ *
+ * On Native, these can be avoided using a `Text` wrapped in a `TouchableWithoutFeedback`; the latter
+ * injects additional handlers such as onPressIn to `Text`, resulting in a tree that is purely `Text`.
+ *
+ * Note that this should only be used on Native, not Web, because React Navigation's Web navigation
+ * functions don't work in Touchables (but do work in Pressable) due to different event handling.
+ *
+ * @param {PressableProps} PressableProps
+ */
+// React Native exports prop Types but not propTypes, use JSDoc types here rather than duplicate RN
+// eslint-disable-next-line react/prop-types
+const InlinePressable = forwardRef(({ onPress, children, style, ...rest }, ref) => {
+  const [isFocused, setIsFocused] = useState(false)
+  const handleFocus = () => setIsFocused(true)
+  const handleBlur = () => setIsFocused(false)
+
+  const [isPressed, setIsPressed] = useState(false)
+  const handlePressIn = () => setIsPressed(true)
+  const handlePressOut = () => setIsPressed(false)
+
+  const pressState = {
+    pressed: isPressed,
+    focus: isFocused, // limited support on native
+    hover: false // not yet supported on native
+  }
+  const currentStyle = typeof style === 'function' ? style(pressState) : style
+
+  return (
+    <TouchableWithoutFeedback
+      onPress={onPress}
+      onPressIn={handlePressIn}
+      onPressOut={handlePressOut}
+      onFocus={handleFocus}
+      onBlur={handleBlur}
+      ref={ref}
+      {...pressablePropsToTouchable(rest)}
+    >
+      <Text style={currentStyle}>
+        {typeof children === 'function' ? children(pressState) : children}
+      </Text>
+    </TouchableWithoutFeedback>
+  )
+})
+InlinePressable.displayName = 'InlinePressable'
+
+export default InlinePressable

package/src/Link/Link.jsx

@@ -1,20 +1,30 @@
-import React from 'react'
+import React, { forwardRef } from 'react'
 
+import { useThemeTokensCallback } from '../ThemeProvider'
 import LinkBase from './LinkBase'
 
-const Link = ({ href, children, accessibilityRole = 'link', variant = {}, ...linkProps }) => (
-  <LinkBase
-    href={href}
-    accessibilityRole={accessibilityRole}
-    variant={{ component: 'Link', ...variant }}
-    {...linkProps}
-  >
-    {children}
-  </LinkBase>
+const Link = forwardRef(
+  (
+    { href, children, accessibilityRole = 'link', variant = {}, tokens, dataSet, ...linkProps },
+    ref
+  ) => {
+    const getTokens = useThemeTokensCallback('Link', tokens, variant)
+    return (
+      <LinkBase
+        href={href}
+        accessibilityRole={accessibilityRole}
+        tokens={getTokens}
+        ref={ref}
+        dataSet={dataSet}
+        {...linkProps}
+      >
+        {children}
+      </LinkBase>
+    )
+  }
 )
+Link.displayName = 'Link'
 
-Link.propTypes = {
-  ...LinkBase.propTypes
-}
+Link.propTypes = LinkBase.propTypes
 
 export default Link

package/src/Link/LinkBase.jsx

@@ -1,14 +1,6 @@
-import React, { useState } from 'react'
+import React, { forwardRef } from 'react'
 import PropTypes from 'prop-types'
-import {
-  Text,
-  Platform,
-  StyleSheet,
-  Pressable,
-  PixelRatio,
-  View,
-  TouchableWithoutFeedback
-} from 'react-native'
+import { Text, Platform, StyleSheet } from 'react-native'
 import {
   a11yProps,
   hrefAttrsProp,
@@ -16,40 +8,47 @@ import {
   linkProps,
   getTokensPropType
 } from '../utils/propTypes'
+import { resolvePressableTokens } from '../utils/pressability'
 
-import { useThemeTokens, applyTextStyles } from '../ThemeProvider'
-
-const selectContentStyles = ({ color }) => ({
-  color
-})
+import InlinePressable from './InlinePressable'
+import { applyTextStyles, applyOuterBorder } from '../ThemeProvider'
+import { IconText, iconComponentPropTypes } from '../Icon'
 
 const selectOuterBorderStyles = ({
   outerBorderColor,
   outerBorderWidth,
   outerBorderGap,
-  outerBorderRadius,
+  borderRadius,
   outerBorderOutline
 }) =>
   // A view wrapper with a border on native messes up inline text alignment
   // so for now make focus styles strictly web-only
   Platform.OS === 'web'
     ? {
-        margin: -1 * (outerBorderGap + outerBorderWidth) || 0,
-        padding: outerBorderGap,
         // Allow theme to define outline, or, turn off outline and use border if rounded corners required
         outline: outerBorderOutline,
-        borderWidth: outerBorderWidth,
-        borderColor: outerBorderColor,
-        borderRadius: outerBorderRadius,
+        ...applyOuterBorder({
+          outerBorderColor,
+          outerBorderWidth,
+          outerBorderGap,
+          borderRadius
+        }),
         // Stops focus ring stretching horizontally if parent has display: block
         // width: fit-content isn't supported on Firefox; can't cascade props like CSS `width: fit-content; width: --moz-fit-content;`
         display: 'inline-flex'
       }
     : {}
 
-const selectTextStyles = ({ textLine, textLineStyle }) => ({
+const selectTextStyles = ({ color, textLine, textLineStyle }) => ({
+  color,
   textDecorationLine: textLine,
-  textDecorationStyle: textLineStyle
+  textDecorationStyle: textLineStyle,
+  ...Platform.select({
+    web: {
+      // TODO: https://github.com/telus/universal-design-system/issues/487
+      transition: 'color 200ms'
+    }
+  })
 })
 
 const selectBlockStyles = ({ blockFontWeight, blockFontSize, blockLineHeight, blockFontName }) =>
@@ -60,20 +59,11 @@ const selectBlockStyles = ({ blockFontWeight, blockFontSize, blockLineHeight, bl
     fontName: blockFontName
   })
 
-const selectIconStyles = ({
-  iconSize,
-  iconGapBefore,
-  iconGapAfter,
-  iconScale,
-  iconTranslateX,
-  iconTranslateY
-}) => ({
-  scale: iconScale,
+const selectIconTokens = ({ color, iconSize, iconTranslateX, iconTranslateY }) => ({
+  color,
   translateX: iconTranslateX,
   translateY: iconTranslateY,
-  size: iconSize,
-  gapBefore: iconGapBefore,
-  gapAfter: iconGapAfter
+  size: iconSize
 })
 
 /**
@@ -98,143 +88,78 @@ const selectIconStyles = ({
  *   dropped in favour of investigating if a full-featured CSS-in-JS package could or
  *   should be used more widely (e.g. styled components)
  */
-const LinkBase = ({
-  href,
-  onPress,
-  icon,
-  iconPosition = icon ? 'left' : undefined,
-  iconVariant,
-  variant,
-  tokens,
-  children,
-  accessibilityRole = 'link',
-  ...props
-}) => {
-  const handlePress = linkProps.handleHref({ href, onPress })
-
-  const [isFocused, setIsFocused] = useState(false)
-  const handleFocus = () => setIsFocused(true)
-  const handleBlur = () => setIsFocused(false)
-
-  const [isHovered, setIsHovered] = useState(false)
-  const handleHoverIn = () => setIsHovered(true)
-  const handleHoverOut = () => setIsHovered(false)
-
-  const [isPressed, setIsPressed] = useState(false)
-  const handlePressIn = () => setIsPressed(true)
-  const handlePressOut = () => setIsPressed(false)
-
-  const { hrefAttrs, rest } = hrefAttrsProp.bundle(props)
-  const linkPropSet = linkProps.select({
-    accessibilityRole,
-    href,
-    onPress: handlePress,
-    onPressIn: handlePressIn,
-    onPressOut: handlePressOut,
-    onFocus: handleFocus,
-    onBlur: handleBlur,
-    onMouseEnter: handleHoverIn,
-    onMouseLeave: handleHoverOut,
-    ...hrefAttrsProp.spread(hrefAttrs),
-    ...rest
-  })
-
-  const themeTokens = useThemeTokens('Link', tokens, variant, {
-    focus: isFocused,
-    hover: isHovered,
-    pressed: isPressed,
-    iconPosition
-  })
-  const IconComponent = icon || themeTokens.icon
-  const hasIcon = !!IconComponent
-
-  const textStyles = selectTextStyles(themeTokens)
-  const outerBorderStyles = selectOuterBorderStyles(themeTokens)
-  const contentStyles = selectContentStyles(themeTokens)
-  const blockStyles = selectBlockStyles(themeTokens)
-  const iconStyles = selectIconStyles(themeTokens)
-
-  // TODO: re-apply support for inline links
-  const isNested = false
+const LinkBase = forwardRef(
+  (
+    {
+      href,
+      onPress,
+      icon,
+      iconPosition = icon ? 'left' : undefined,
+      iconProps,
+      variant,
+      tokens = {},
+      children,
+      accessibilityRole = 'link',
+      dataSet,
+      ...props
+    },
+    ref
+  ) => {
+    const { hrefAttrs, rest } = hrefAttrsProp.bundle(props)
+    const linkPropSet = linkProps.select({
+      accessibilityRole,
+      href,
+      onPress: linkProps.handleHref({ href, onPress }),
+      hrefAttrs,
+      ...rest
+    })
+
+    const resolveLinkTokens = (pressState) =>
+      resolvePressableTokens(tokens, pressState, { iconPosition })
+
+    // On web, this makes focus rings wrap only the link, not the entire block
+    const blockLeftStyle = Platform.OS === 'web' && staticStyles.blockLeft
 
-  // On web, this makes focus rings wrap only the link, not the entire block
-  const blockLeftStyle = Platform.OS === 'web' && staticStyles.blockLeft
-
-  // Apply typographic text styles if not inheriting, and block positioning if a block
-  const blockTextStyles = !isNested && blockStyles
-
-  if (!hasIcon) {
-    // onPressIn / onPressOut only work if on TouchableWithoutFeedback, onFocus only works if on Text
-    const { onPress: _onPress, onPressIn, onPressOut, ...textProps } = linkPropSet
     return (
-      // TouchableWithoutFeedback modifies its child so this stack is all (touchable) Text: no Views
-      <TouchableWithoutFeedback onPressIn={onPressIn} onPressOut={onPressOut} onPress={_onPress}>
-        <Text
-          {...textProps}
-          style={[outerBorderStyles, blockLeftStyle, contentStyles, blockTextStyles, textStyles]}
-        >
-          {children}
-        </Text>
-      </TouchableWithoutFeedback>
+      <InlinePressable
+        {...linkPropSet}
+        ref={ref}
+        dataSet={dataSet}
+        style={(linkState) => {
+          const themeTokens = resolveLinkTokens(linkState)
+          const outerBorderStyles = selectOuterBorderStyles(themeTokens)
+          const hasIcon = Boolean(icon || themeTokens.icon)
+          return [outerBorderStyles, blockLeftStyle, hasIcon && staticStyles.rowContainer]
+        }}
+      >
+        {(linkState) => {
+          const themeTokens = resolveLinkTokens(linkState)
+          const textStyles = selectTextStyles(themeTokens)
+          const iconTokens = selectIconTokens(themeTokens)
+
+          // TODO: may need to apply some smarter text inheritance here if inline to avoid native
+          // issues like double-application of line heights breaking align-items: baseline
+          const blockTextStyles = selectBlockStyles(themeTokens)
+
+          const IconComponent = icon || themeTokens.icon
+          const { iconSpace } = themeTokens
+
+          return (
+            <IconText
+              icon={IconComponent}
+              iconPosition={iconPosition}
+              space={iconSpace}
+              iconProps={{ ...iconProps, tokens: iconTokens }}
+            >
+              <Text style={[textStyles, blockTextStyles, staticStyles.baseline]}>{children}</Text>
+            </IconText>
+          )
+        }}
+      </InlinePressable>
     )
   }
-
-  // Scale icon with text, but with a cap so text isn't squashed at large scales
-  const iconScale = Math.min(PixelRatio.getFontScale(), 2)
-
-  const iconTokens = {
-    size: iconStyles.size ? iconStyles.size * iconScale : undefined,
-    color: contentStyles.color ?? undefined,
-    scale: iconStyles.scale ?? undefined,
-    translateX: iconStyles.translateX ?? undefined,
-    translateY: iconStyles.translateY ?? undefined
-  }
-
-  const iconContent = <IconComponent tokens={iconTokens} variant={iconVariant} />
-
-  const iconBlock = isNested ? (
-    // TODO: when reimplementing inline support, insert an appropriate space character
-    // based on the value of gapBefore and gapAfter on native (no inline margins/padding)
-    iconContent
-  ) : (
-    <View
-      style={[
-        iconPosition === 'left' && { marginRight: iconStyles.gapAfter * iconScale },
-        iconPosition === 'right' && { marginLeft: iconStyles.gapBefore * iconScale }
-      ]}
-    >
-      {iconContent}
-    </View>
-  )
-
-  // TODO: this doesn't work well when nested inline but does allow block-links to have icons align
-  // properly on Android which purely inline links can't do. Add an isNested case that is similar to
-  // https://github.com/telus/universal-design-system/pull/233
-  return (
-    <Pressable
-      {...linkPropSet}
-      style={[outerBorderStyles, blockLeftStyle, staticStyles.rowContainer]}
-    >
-      {iconPosition === 'left' && iconBlock}
-      <Text
-        style={[
-          contentStyles,
-          blockTextStyles,
-          textStyles,
-          Platform.select({
-            web: {
-              // TODO: https://github.com/telus/universal-design-system/issues/487
-              transition: 'color 200ms'
-            }
-          })
-        ]}
-      >
-        {children}
-      </Text>
-      {iconPosition === 'right' && iconBlock}
-    </Pressable>
-  )
-}
+)
+LinkBase.displayName = 'LinkBase'
 
 LinkBase.propTypes = {
   ...a11yProps.types,
@@ -244,7 +169,7 @@ LinkBase.propTypes = {
   /**
    * Optional variant that may be passed down to the link's icon if there is one
    */
-  iconVariant: variantProp.propType,
+  iconProps: PropTypes.exact(iconComponentPropTypes),
   /**
    * A function component for an SVG icon to render inside the link. Inherits size and color from
    * the link and any Typography the link is nested inside.
@@ -256,7 +181,7 @@ LinkBase.propTypes = {
   iconPosition: PropTypes.oneOf(['left', 'right']),
   /**
    * On Web if href is passed, React Native Web maps this object's props to
-   * `rel`, `target` and (>= RNW 0.15.0) `download` attrs.
+   * `rel`, `target` and `download` attrs.
    */
   hrefAttrs: PropTypes.shape(hrefAttrsProp.types)
 }
@@ -269,6 +194,9 @@ const staticStyles = StyleSheet.create({
     flexDirection: 'row',
     alignItems: 'center',
     justifyContent: 'flex-start'
+  },
+  baseline: {
+    alignSelf: 'baseline'
   }
 })
 

package/src/Link/TextButton.jsx

@@ -1,24 +1,43 @@
-import React from 'react'
+import React, { forwardRef } from 'react'
 import PropTypes from 'prop-types'
 
+import { useThemeTokensCallback } from '../ThemeProvider'
 import LinkBase from './LinkBase'
 
-const TextButton = ({
-  onPress,
-  children,
-  variant = {},
-  accessibilityRole = 'button',
-  ...linkProps
-}) => (
-  <LinkBase
-    onPress={onPress}
-    accessibilityRole={accessibilityRole}
-    variant={{ component: 'TextButton', ...variant }}
-    {...linkProps}
-  >
-    {children}
-  </LinkBase>
+/**
+ * `TextButton` is a button that looks like a Link. It uses the same theming and variants as
+ * Link but has the accessibility role of a `Button`. It should be used for actions that
+ * take place on the current page, or for navigation within an app.
+ */
+const TextButton = forwardRef(
+  (
+    {
+      onPress,
+      children,
+      variant,
+      tokens,
+      // TODO: this may need to use `link` role on Web in the case of being passed both `href` and
+      // `onPress` in an omniplatform app that uses React Navigation's useLinkProps for internal nav.
+      accessibilityRole = 'button',
+      ...linkProps
+    },
+    ref
+  ) => {
+    const getTokens = useThemeTokensCallback('Link', tokens, variant)
+    return (
+      <LinkBase
+        onPress={onPress}
+        accessibilityRole={accessibilityRole}
+        tokens={getTokens}
+        ref={ref}
+        {...linkProps}
+      >
+        {children}
+      </LinkBase>
+    )
+  }
 )
+TextButton.displayName = 'TextButton'
 
 TextButton.propTypes = {
   ...LinkBase.propTypes,
@@ -26,6 +45,8 @@ TextButton.propTypes = {
 }
 
 // Remove incompatible Link prop (if this build includes propTypes)
+// TODO: test if this works with web navigation in omniplatform React Navigation
+// https://github.com/telus/universal-design-system/issues/665
 // eslint-disable-next-line react/forbid-foreign-prop-types
 if (TextButton.propTypes?.href) delete TextButton.propTypes.href
 

package/src/Link/index.js

@@ -1,5 +1,6 @@
 import ChevronLink from './ChevronLink'
 import Link from './Link'
+import LinkBase from './LinkBase'
 import TextButton from './TextButton'
 
-export { ChevronLink, Link, TextButton }
+export { ChevronLink, Link, LinkBase, TextButton }