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

package/src/Icon/Icon.jsx

@@ -3,23 +3,34 @@ import { Platform, View } from 'react-native'
 import PropTypes from 'prop-types'
 
 import { useThemeTokens } from '../ThemeProvider'
-import { getTokensPropType, variantProp } from '../utils/propTypes'
+import { getTokensPropType, scaleWithText, variantProp } from '../utils'
 
-const Icon = ({ IconSvg, variant, label, titleId, tokens = {} }) => {
+const Icon = ({
+  icon: IconComponent,
+  accessibilityLabel,
+  variant,
+  tokens,
+  scalesWithText = false
+}) => {
   const themeTokens = useThemeTokens('Icon', tokens, variant)
+
+  const size = scalesWithText ? scaleWithText(themeTokens.size) : themeTokens.size
+
   const iconContent = (
-    <IconSvg title={label} titleId={titleId} size={themeTokens.size} color={themeTokens.color} />
+    <IconComponent title={accessibilityLabel} size={size} color={themeTokens.color} />
   )
 
   return Platform.OS === 'web' ? (
     <View
       // eslint-disable-next-line react-native/no-inline-styles
       style={{
-        // TODO: https://github.com/telus/universal-design-system/issues/487
-        transition: 'transform 200ms',
+        // TODO: systematise animations.
+        // https://github.com/telus/universal-design-system/issues/487
+        transition: 'transform 200ms, color 200ms',
         transform: [
           themeTokens.scale ? `scale(${themeTokens.scale})` : '',
-          themeTokens.translateX ? `translateX(${themeTokens.translateX}px)` : ''
+          themeTokens.translateX ? `translateX(${themeTokens.translateX}px)` : '',
+          themeTokens.translateY ? `translateY(${themeTokens.translateY}px)` : ''
         ]
           .filter((exists) => exists)
           .join(' ')
@@ -32,41 +43,26 @@ const Icon = ({ IconSvg, variant, label, titleId, tokens = {} }) => {
   )
 }
 
-// Auto-generated SVG icon components wrap Icon and pass through these props:
 export const iconComponentPropTypes = {
   variant: variantProp.propType,
   tokens: getTokensPropType('Icon'),
   /**
    * Descriptive label used in web SVG title tag for accessibility
    */
-  label: PropTypes.string,
-  /**
-   * On web, this unique id is applied to <SVG> title and aria-labelledby attr
-   */
-  titleId: PropTypes.string
-}
-
-// Auto-generated SVG icon components contain an inner SVG component taking these props:
-export const iconSvgPropTypes = {
-  title: iconComponentPropTypes.label,
-  titleId: iconComponentPropTypes.titleId,
-  /**
-   * The size of the SVG icon after resolving tokens
-   */
-  size: PropTypes.number,
+  accessibilityLabel: PropTypes.string,
   /**
-   * The color of the SVG icon after resolving tokens
+   * controls whether the icon size should be proportionate to any accessibility-related font scaling.
    */
-  color: PropTypes.string
+  scalesWithText: PropTypes.bool
 }
 
 Icon.propTypes = {
   ...iconComponentPropTypes,
   /**
-   * Function component containing this icon's SVG or native equivalent.
-   * UDS's SVGR config turns static SVG files into components that pass this to <Icon>.
+   * A valid UDS icon component imported from a UDS palette
+   * (e.g.) `import { MyIcon } from @telus-uds/palette-<brand>/build/web/icons`
    */
-  IconSvg: PropTypes.func.isRequired
+  icon: PropTypes.elementType.isRequired
 }
 
 export default Icon

package/src/Icon/IconText.jsx

@@ -0,0 +1,63 @@
+import React from 'react'
+import PropTypes from 'prop-types'
+import { Platform, View } from 'react-native'
+
+import Icon, { iconComponentPropTypes } from './Icon'
+import { getStackedContent } from '../StackView'
+import { spacingProps } from '../utils'
+
+/**
+ * Returns an icon and some text with a sized gap between them. This is a utility component
+ * intended for use when creating components, not intended for use in applications on its own.
+ *
+ * IconText does not wrap its children, so should be used either:
+ *  - inline within a <Text> element
+ *  - within a container with `flexDirection: 'row'`
+ */
+const IconText = ({ space, iconPosition = 'left', icon: IconComponent, iconProps, children }) => {
+  const iconContent = IconComponent && <Icon icon={IconComponent} scalesWithText {...iconProps} />
+
+  // Inline images on Android are always baseline-aligned which makes them look misaligned - offset it.
+  // See abandoned issue https://github.com/facebook/react-native/issues/6529
+  const size = iconProps?.tokens?.size
+  const iconAdjusted =
+    Platform.OS === 'android' && iconContent && size ? (
+      <View style={{ transform: [{ translateY: size * 0.2 }] }}>{iconContent}</View>
+    ) : (
+      iconContent
+    )
+
+  return getStackedContent(
+    iconPosition === 'left' ? [iconAdjusted, children] : [children, iconAdjusted],
+    { space, direction: 'row' }
+  )
+}
+
+IconText.propTypes = {
+  /**
+   * Amount of space to separate the text content and icon. Uses the themes's spacing scale
+   * (see useSpacingScale for more info).
+   */
+  space: spacingProps.types.spacingValue,
+  /**
+   * Whether the icon should be to the left of the content or the right of the content.
+   */
+  iconPosition: PropTypes.oneOf(['left', 'right']),
+  /**
+   * A valid UDS icon component imported from a UDS palette.
+   */
+  icon: PropTypes.func,
+  /**
+   * Props that will be passed to the icon component. By default the icon's `scalesWithText`
+   * prop will be set as "true" so that the icon continues to match the size of the text
+   * if users use accessibility settings to increase text size.
+   */
+  iconProps: PropTypes.exact(iconComponentPropTypes),
+  /**
+   * Content to be rendered alongside the Icon component. Usually this should be a
+   * `<Typography>` component, or a component that renders `<Text>`.
+   */
+  children: PropTypes.node
+}
+
+export default IconText

package/src/Icon/index.js

@@ -1,4 +1,5 @@
-import Icon, { iconComponentPropTypes, iconSvgPropTypes } from './Icon'
+import Icon, { iconComponentPropTypes } from './Icon'
+import IconText from './IconText'
 
 export default Icon
-export { iconComponentPropTypes, iconSvgPropTypes }
+export { iconComponentPropTypes, IconText }

package/src/InputLabel/InputLabel.jsx

@@ -0,0 +1,106 @@
+import React from 'react'
+import { StyleSheet, Text, View } from 'react-native'
+import PropTypes from 'prop-types'
+
+import { applyTextStyles, useThemeTokens } from '../ThemeProvider'
+import { getTokensPropType, selectTokens, variantProp } from '../utils'
+
+import LabelContent from './LabelContent'
+import Tooltip from '../Tooltip'
+
+const selectLabelStyles = (tokens) => applyTextStyles(selectTokens('Typography', tokens))
+
+const selectHintStyles = ({
+  hintColor,
+  hintFontName,
+  hintFontSize,
+  hintFontWeight,
+  hintLineHeight
+}) =>
+  applyTextStyles({
+    color: hintColor,
+    fontName: hintFontName,
+    fontSize: hintFontSize,
+    fontWeight: hintFontWeight,
+    lineHeight: hintLineHeight
+  })
+
+const selectGapStyles = ({ gap }) => ({ marginRight: gap })
+
+function InputLabel({
+  label,
+  forId,
+  hint,
+  hintPosition = 'inline',
+  hintId,
+  tooltip,
+  tokens,
+  variant
+}) {
+  const themeTokens = useThemeTokens('InputLabel', tokens, variant)
+
+  const hasTooltip = tooltip !== undefined
+  const isHintInline = hintPosition === 'inline'
+
+  return (
+    <View style={[staticStyles.container, !isHintInline && staticStyles.containerWithHintBelow]}>
+      <Text
+        style={[selectLabelStyles(themeTokens), selectGapStyles(themeTokens), staticStyles.label]}
+      >
+        <LabelContent forId={forId}>{label}</LabelContent>
+      </Text>
+      {hint && isHintInline && (
+        <Text
+          style={[selectHintStyles(themeTokens), hasTooltip && selectGapStyles(themeTokens)]}
+          nativeID={hintId}
+        >
+          {hint}
+        </Text>
+      )}
+      {hasTooltip && (
+        <View style={staticStyles.tooltipAlign}>
+          <Tooltip content={tooltip} />
+        </View>
+      )}
+      {hint && !isHintInline && (
+        <Text style={[selectHintStyles(themeTokens), staticStyles.hintBelow]} nativeID={hintId}>
+          {hint}
+        </Text>
+      )}
+    </View>
+  )
+}
+
+InputLabel.propTypes = {
+  label: PropTypes.string.isRequired,
+  forId: PropTypes.string,
+  hint: PropTypes.string,
+  hintPosition: PropTypes.oneOf(['inline', 'below']),
+  hintId: PropTypes.string,
+  tooltip: PropTypes.string,
+  tokens: getTokensPropType('InputLabel'),
+  variant: variantProp.propType
+}
+
+export default InputLabel
+
+const staticStyles = StyleSheet.create({
+  container: {
+    display: 'flex',
+    flexDirection: 'row',
+    alignItems: 'baseline'
+  },
+  containerWithHintBelow: {
+    flexWrap: 'wrap'
+  },
+  label: {
+    flexShrink: 0
+  },
+  hintBelow: {
+    flexBasis: '100%',
+    flexShrink: 0
+  },
+  tooltipAlign: {
+    alignSelf: 'center'
+  }
+})

package/src/InputLabel/LabelContent.jsx

@@ -0,0 +1,13 @@
+import React from 'react'
+import PropTypes from 'prop-types'
+
+function LabelContent({ children, forId }) {
+  return <label htmlFor={forId}>{children}</label>
+}
+
+export default LabelContent
+
+LabelContent.propTypes = {
+  children: PropTypes.string,
+  forId: PropTypes.string
+}

package/src/InputLabel/LabelContent.native.jsx

@@ -0,0 +1,6 @@
+// Since there's no equivalent for web's <label> element we're simply rendering whatever is passed to this component.
+function LabelContent({ children }) {
+  return children
+}
+
+export default LabelContent

package/src/InputLabel/index.js

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

package/src/InputSupports/InputSupports.jsx

@@ -0,0 +1,75 @@
+import React from 'react'
+
+import PropTypes from 'prop-types'
+import InputLabel from '../InputLabel'
+import Feedback from '../Feedback'
+import StackView from '../StackView'
+import { useThemeTokens } from '../ThemeProvider'
+import useInputSupports from './useInputSupports'
+
+function InputSupports({
+  children,
+  label,
+  hint,
+  hintPosition = 'inline',
+  feedback,
+  tooltip,
+  validation
+}) {
+  const { space } = useThemeTokens('InputSupports')
+
+  const { inputId, hintId, feedbackId, a11yProps } = useInputSupports({
+    feedback,
+    hint,
+    label,
+    validation
+  })
+
+  return (
+    <StackView space={space}>
+      {label && (
+        <InputLabel
+          label={label}
+          hint={hint}
+          hintPosition={hintPosition}
+          hintId={hintId}
+          tooltip={tooltip}
+          forId={inputId}
+        />
+      )}
+      {typeof children === 'function' ? children({ a11yProps, inputId }) : children}
+      {feedback && <Feedback id={feedbackId} title={feedback} validation={validation} />}
+    </StackView>
+  )
+}
+
+InputSupports.propTypes = {
+  children: PropTypes.oneOfType([PropTypes.func, PropTypes.node]),
+  /**
+   * The input label.
+   */
+  label: PropTypes.string,
+  /**
+   * A short description of the expected input.
+   */
+  hint: PropTypes.string,
+  /**
+   * Position of the hint relative to label.
+   */
+  hintPosition: PropTypes.oneOf(['inline', 'below']),
+  /**
+   * A detailed description of validation error/success or additional instructions.
+   * Visual variant is determined based on the `validation` prop.
+   */
+  feedback: PropTypes.string,
+  /**
+   * Content of an optional `Tooltip`. If set, a tooltip button will be shown next to the label.
+   */
+  tooltip: PropTypes.string,
+  /**
+   * Use to visually mark an input as valid or invalid.
+   */
+  validation: PropTypes.oneOf(['error', 'success'])
+}
+
+export default InputSupports

package/src/InputSupports/index.js

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

package/src/InputSupports/propTypes.js

@@ -0,0 +1,44 @@
+import PropTypes from 'prop-types'
+
+const inputSupportProps = {
+  types: {
+    /**
+     * The input label.
+     */
+    label: PropTypes.string,
+    /**
+     * A short description of the expected input.
+     */
+    hint: PropTypes.string,
+    /**
+     * Position of the hint relative to label. Use `below` to display a larger hint below the label.
+     */
+    hintPosition: PropTypes.oneOf(['inline', 'below']),
+    /**
+     * A detailed description of validation error/success or additional instructions.
+     * Visual variant is determined based on the `validation` prop.
+     */
+    feedback: PropTypes.string,
+    /**
+     * Content of an optional `Tooltip`. If set, a tooltip button will be shown next to the label.
+     */
+    tooltip: PropTypes.string,
+    /**
+     * Use to visually mark an input as valid or invalid.
+     */
+    validation: PropTypes.oneOf(['error', 'success'])
+  },
+  select: ({ label, hint, hintPosition, feedback, tooltip, validation, ...rest }) => ({
+    props: {
+      label,
+      hint,
+      hintPosition,
+      feedback,
+      tooltip,
+      validation
+    },
+    rest
+  })
+}
+
+export default inputSupportProps

package/src/InputSupports/useInputSupports.js

@@ -0,0 +1,30 @@
+import useUniqueId from '../utils/useUniqueId'
+
+const joinDefined = (array) => array.filter((item) => item !== undefined).join(' ')
+
+const useInputSupports = ({ label, feedback, validation, hint }) => {
+  const hasValidationError = validation === 'error'
+
+  const inputId = useUniqueId('input')
+  const hintId = useUniqueId('input-hint')
+  const feedbackId = useUniqueId('input-feedback')
+
+  const a11yProps = {
+    accessibilityLabel: label,
+    accessibilityHint: joinDefined([!hasValidationError && feedback, hint]), // native only -> replaced with describedBy on web
+    accessibilityDescribedBy: joinDefined([
+      !hasValidationError && feedback && feedbackId, // feedback receives a11yRole=alert on error, so there's no need to include it here
+      hint && hintId
+    ]),
+    accessibilityInvalid: hasValidationError
+  }
+
+  return {
+    inputId,
+    hintId,
+    feedbackId,
+    a11yProps
+  }
+}
+
+export default useInputSupports

package/src/Link/ChevronLink.jsx

@@ -1,16 +1,37 @@
 import React from 'react'
 import PropTypes from 'prop-types'
 
-import Link from './Link'
+import { useThemeTokensCallback } from '../ThemeProvider'
+import { selectTokens, getTokensPropType } from '../utils'
+import LinkBase from './LinkBase'
 
-const ChevronLink = ({ direction = 'right', children, variant = {}, ...linkProps }) => (
-  <Link variant={{ component: 'ChevronLink', ...variant }} iconPosition={direction} {...linkProps}>
-    {children}
-  </Link>
-)
+/**
+ * `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; variants passed to ChevronLink are forwarded to Link.
+ */
+const ChevronLink = ({ direction = 'right', children, tokens, variant, ...linkProps }) => {
+  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}>
+      {children}
+    </LinkBase>
+  )
+}
 ChevronLink.propTypes = {
-  ...Link.propTypes,
+  ...LinkBase.propTypes,
+  tokens: getTokensPropType('ChevronLink', 'Link'),
   direction: PropTypes.oneOf(['left', 'right'])
 }
 

package/src/Link/InlinePressable.jsx

@@ -0,0 +1,37 @@
+import React 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 = ({ children, style, ...props }) => (
+  <Pressable
+    style={(pressState) => [
+      staticStyles.inline,
+      typeof style === 'function' ? style(pressState) : style
+    ]}
+    {...props}
+  >
+    {(pressState) => (typeof children === 'function' ? children(pressState) : children)}
+  </Pressable>
+)
+
+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,73 @@
+/* eslint-disable camelcase */
+import React, { 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 = ({ onPress, children, style, ...rest }) => {
+  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}
+      {...pressablePropsToTouchable(rest)}
+    >
+      <Text style={currentStyle}>
+        {typeof children === 'function' ? children(pressState) : children}
+      </Text>
+    </TouchableWithoutFeedback>
+  )
+}
+
+export default InlinePressable

package/src/Link/Link.jsx

@@ -1,20 +1,24 @@
 import React 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>
-)
-
-Link.propTypes = {
-  ...LinkBase.propTypes
+const Link = ({
+  href,
+  children,
+  accessibilityRole = 'link',
+  variant = {},
+  tokens,
+  ...linkProps
+}) => {
+  const getTokens = useThemeTokensCallback('Link', tokens, variant)
+  return (
+    <LinkBase href={href} accessibilityRole={accessibilityRole} tokens={getTokens} {...linkProps}>
+      {children}
+    </LinkBase>
+  )
 }
 
+Link.propTypes = LinkBase.propTypes
+
 export default Link