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

package/src/Icon/Icon.jsx

@@ -1,73 +1,70 @@
-import React from 'react'
+import React, { forwardRef } from 'react'
 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 themeTokens = useThemeTokens('Icon', tokens, variant)
-  const iconContent = (
-    <IconSvg title={label} titleId={titleId} size={themeTokens.size} color={themeTokens.color} />
-  )
+const Icon = forwardRef(
+  (
+    { icon: IconComponent, accessibilityLabel, variant, tokens, scalesWithText = false, dataSet },
+    ref
+  ) => {
+    const themeTokens = useThemeTokens('Icon', tokens, variant)
 
-  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',
-        transform: [
-          themeTokens.scale ? `scale(${themeTokens.scale})` : '',
-          themeTokens.translateX ? `translateX(${themeTokens.translateX}px)` : '',
-          themeTokens.translateY ? `translateY(${themeTokens.translateY}px)` : ''
-        ]
-          .filter((exists) => exists)
-          .join(' ')
-      }}
-    >
-      {iconContent}
-    </View>
-  ) : (
-    iconContent
-  )
-}
+    const size = scalesWithText ? scaleWithText(themeTokens.size) : themeTokens.size
+
+    const iconContent = (
+      <IconComponent title={accessibilityLabel} size={size} color={themeTokens.color} />
+    )
+
+    return Platform.OS === 'web' ? (
+      <View
+        ref={ref}
+        // eslint-disable-next-line react-native/no-inline-styles
+        style={{
+          // 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.translateY ? `translateY(${themeTokens.translateY}px)` : ''
+          ]
+            .filter((exists) => exists)
+            .join(' ')
+        }}
+        dataSet={dataSet}
+      >
+        {iconContent}
+      </View>
+    ) : (
+      iconContent
+    )
+  }
+)
+Icon.displayName = 'Icon'
 
-// 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,68 @@
+import React, { forwardRef } 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 = forwardRef(
+  ({ space, iconPosition = 'left', icon: IconComponent, iconProps, children }, ref) => {
+    const iconContent = IconComponent && (
+      <Icon ref={ref} 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.displayName = 'IconText'
+
+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/IconButton/IconButton.jsx

@@ -0,0 +1,114 @@
+import React, { forwardRef } from 'react'
+import PropTypes from 'prop-types'
+import { Pressable, Platform, StyleSheet, View } from 'react-native'
+
+import { applyOuterBorder, useThemeTokensCallback, applyShadowToken } from '../ThemeProvider'
+import {
+  variantProp,
+  linkProps,
+  resolvePressableState,
+  hrefAttrsProp,
+  getTokensPropType,
+  selectTokens
+} from '../utils'
+import { a11yProps } from '../utils/propTypes'
+import Icon from '../Icon'
+
+const selectOuterStyle = ({
+  backgroundColor,
+  borderRadius,
+  outerBorderWidth,
+  outerBorderColor,
+  outerBorderGap,
+  shadow
+}) => [
+  {
+    backgroundColor,
+    ...applyShadowToken(shadow),
+    ...applyOuterBorder({ borderRadius, outerBorderWidth, outerBorderColor, outerBorderGap }),
+    ...Platform.select({ web: { outline: 'none', display: 'inline-flex' } })
+  },
+  staticStyles.outer
+]
+
+const selectInnerStyle = ({ borderColor, borderWidth = 0, borderRadius, padding = 0 }) => ({
+  // Inner borders animate with the icon and should be treated like a themable feature of the icon
+  borderColor,
+  borderRadius,
+  borderWidth,
+  padding: Math.max(0, padding - borderWidth) // Stable size as border changes
+})
+
+/**
+ * A pressable themeless base component that handles pressable states and passes tokens
+ * based on these to an outer border and a base Card component. Not intended to be used in
+ * apps or sites directly: build themed components on top of this.
+ */
+const IconButton = forwardRef(
+  (
+    {
+      tokens,
+      variant,
+      icon: IconComponent,
+      href,
+      hrefAttrs,
+      onPress,
+      accessibilityRole = href ? 'link' : 'button',
+      ...rest
+    },
+    ref
+  ) => {
+    const a11y = a11yProps.select({
+      ...rest,
+      accessibilityRole
+    })
+    const handlePress = linkProps.handleHref({ href, onPress })
+
+    const getTokens = useThemeTokensCallback('IconButton', tokens, variant)
+    const getOuterStyle = (pressableState) =>
+      selectOuterStyle(getTokens(resolvePressableState(pressableState)))
+
+    return (
+      <Pressable
+        ref={ref}
+        href={href}
+        onPress={handlePress}
+        hrefAttrs={hrefAttrs}
+        style={getOuterStyle}
+        {...a11y}
+      >
+        {(pressableState) => {
+          const themeTokens = getTokens(resolvePressableState(pressableState))
+          return (
+            <View style={selectInnerStyle(themeTokens)}>
+              <Icon
+                icon={IconComponent}
+                title={a11y.accessibilityLabel}
+                tokens={selectTokens('Icon', themeTokens, 'icon')}
+              />
+            </View>
+          )
+        }}
+      </Pressable>
+    )
+  }
+)
+IconButton.displayName = 'IconButton'
+
+IconButton.propTypes = {
+  ...a11yProps.types,
+  variant: variantProp.propType,
+  tokens: getTokensPropType('IconButton'),
+  icon: PropTypes.elementType.isRequired,
+  href: PropTypes.string,
+  hrefAttrs: PropTypes.shape(hrefAttrsProp.types),
+  onPress: PropTypes.func
+}
+
+const staticStyles = StyleSheet.create({
+  outer: {
+    alignSelf: 'flex-start'
+  }
+})
+
+export default IconButton

package/src/IconButton/index.js

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

package/src/InputLabel/InputLabel.jsx

@@ -1,4 +1,4 @@
-import React from 'react'
+import React, { forwardRef } from 'react'
 import { StyleSheet, Text, View } from 'react-native'
 import PropTypes from 'prop-types'
 
@@ -27,52 +27,71 @@ const selectHintStyles = ({
 
 const selectGapStyles = ({ gap }) => ({ marginRight: gap })
 
-function InputLabel({
-  label,
-  forId,
-  hint,
-  hintPosition = 'inline',
-  hintId,
-  tooltip,
-  tokens,
-  variant
-}) {
-  const themeTokens = useThemeTokens('InputLabel', tokens, variant)
+const InputLabel = forwardRef(
+  ({ label, forId, hint, hintPosition = 'inline', hintId, tooltip, tokens, variant }, ref) => {
+    const themeTokens = useThemeTokens('InputLabel', tokens, variant)
 
-  const hasTooltip = tooltip !== undefined
-  const isHintInline = hintPosition === 'inline'
+    const hasTooltip = tooltip !== undefined
+    const isHintInline = hintPosition === 'inline'
 
-  return (
-    <View style={[staticStyles.container, !isHintInline && staticStyles.containerWithHintBelow]}>
-      <Text
-        style={[selectLabelStyles(themeTokens), selectGapStyles(themeTokens), staticStyles.label]}
+    return (
+      <View
+        ref={ref}
+        style={[staticStyles.container, !isHintInline && staticStyles.containerWithHintBelow]}
       >
-        <LabelContent forId={forId}>{label}</LabelContent>
-      </Text>
-      {hint && isHintInline && (
         <Text
-          style={[selectHintStyles(themeTokens), hasTooltip && selectGapStyles(themeTokens)]}
-          nativeID={hintId}
+          style={[selectLabelStyles(themeTokens), selectGapStyles(themeTokens), staticStyles.label]}
         >
-          {hint}
+          <LabelContent forId={forId}>{label}</LabelContent>
         </Text>
-      )}
-      {hasTooltip && <Tooltip content={tooltip} />}
-      {hint && !isHintInline && (
-        <Text style={[selectHintStyles(themeTokens), staticStyles.hintBelow]} nativeID={hintId}>
-          {hint}
-        </Text>
-      )}
-    </View>
-  )
-}
+        {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.displayName = 'InputLabel'
 
 InputLabel.propTypes = {
+  /**
+   * The input label.
+   */
   label: PropTypes.string.isRequired,
+  /**
+   * The id attribute of the input which this label refers to.
+   */
   forId: 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']),
+  /**
+   * The id attribute passed down to the hint element.
+   */
   hintId: PropTypes.string,
+  /**
+   * Content of an optional `Tooltip`. If set, a tooltip button will be shown next to the label.
+   */
   tooltip: PropTypes.string,
   tokens: getTokensPropType('InputLabel'),
   variant: variantProp.propType
@@ -84,7 +103,7 @@ const staticStyles = StyleSheet.create({
   container: {
     display: 'flex',
     flexDirection: 'row',
-    alignItems: 'center'
+    alignItems: 'baseline'
   },
   containerWithHintBelow: {
     flexWrap: 'wrap'
@@ -95,5 +114,8 @@ const staticStyles = StyleSheet.create({
   hintBelow: {
     flexBasis: '100%',
     flexShrink: 0
+  },
+  tooltipAlign: {
+    alignSelf: 'center'
   }
 })

package/src/InputLabel/LabelContent.jsx

@@ -0,0 +1,21 @@
+import React, { forwardRef } from 'react'
+import PropTypes from 'prop-types'
+
+const LabelContent = forwardRef(({ children, forId }, ref) => (
+  <label ref={ref} htmlFor={forId} style={staticStyles.inheritCursor}>
+    {children}
+  </label>
+))
+LabelContent.displayName = 'LabelContent'
+
+LabelContent.propTypes = {
+  children: PropTypes.string,
+  forId: PropTypes.string
+}
+
+// Note that <label> is not React Native, so we can't use `StyleSheet.create` here
+const staticStyles = {
+  inheritCursor: { cursor: 'inherit' }
+}
+
+export default LabelContent

package/src/InputLabel/LabelContent.native.jsx

@@ -1,6 +1,15 @@
+import React, { forwardRef } from 'react'
+import PropTypes from 'prop-types'
+import { View } from 'react-native'
+
 // 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
+const LabelContent = forwardRef(({ children }, ref) =>
+  ref ? <View ref={ref}>{children}</View> : children
+)
+LabelContent.displayName = 'LabelContent'
+
+LabelContent.propTypes = {
+  children: PropTypes.node
 }
 
 export default LabelContent

package/src/InputSupports/InputSupports.jsx

@@ -0,0 +1,70 @@
+import React, { forwardRef } 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'
+
+const InputSupports = forwardRef(
+  ({ children, label, hint, hintPosition = 'inline', feedback, tooltip, validation }, ref) => {
+    const { space } = useThemeTokens('InputSupports')
+
+    const { inputId, hintId, feedbackId, a11yProps } = useInputSupports({
+      feedback,
+      hint,
+      label,
+      validation
+    })
+
+    return (
+      <StackView space={space} ref={ref}>
+        {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.displayName = 'InputSupports'
+
+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