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

package/src/Box/Box.jsx

@@ -99,6 +99,7 @@ const Box = ({
   variant,
   tokens,
   scroll,
+  testID,
   ...rest
 }) => {
   const a11y = a11yProps.select(rest)
@@ -116,13 +117,13 @@ const Box = ({
     const scrollProps = typeof scroll === 'object' ? scroll : {}
     scrollProps.contentContainerStyle = [styles, scrollProps.contentContainerStyle]
     return (
-      <ScrollView {...scrollProps} {...a11y}>
+      <ScrollView {...scrollProps} {...a11y} testID={testID}>
         {children}
       </ScrollView>
     )
   }
   return (
-    <View {...a11y} style={styles}>
+    <View {...a11y} style={styles} testID={testID}>
       {children}
     </View>
   )
@@ -142,6 +143,7 @@ Box.propTypes = {
   ]),
   variant: variantProp.propType,
   tokens: getTokensPropType('Box'),
+  testID: PropTypes.string,
   children: PropTypes.node.isRequired
 }
 

package/src/Button/ButtonBase.jsx

@@ -18,6 +18,7 @@ const getOuterBorderOffset = ({ outerBorderGap = 0, outerBorderWidth = 0 }) =>
   outerBorderGap + outerBorderWidth
 
 const selectOuterContainerStyles = ({
+  alignSelf,
   opacity,
   outerBorderColor,
   outerBorderWidth,
@@ -25,6 +26,7 @@ const selectOuterContainerStyles = ({
   outerBorderRadius = 0,
   outerBackgroundColor
 }) => ({
+  alignSelf,
   padding: outerBorderGap,
   borderWidth: outerBorderWidth,
   borderColor: outerBorderColor,
@@ -33,25 +35,12 @@ const selectOuterContainerStyles = ({
   opacity
 })
 
-const selectOuterWidthStyles = ({
-  outerBorderGap,
-  outerBorderWidth,
-  width,
-  // TODO: make margin the responsibility of a parent
-  // https://github.com/telus/universal-design-system/issues/525
-  marginTop = 0,
-  marginBottom = 0,
-  marginLeft = 0,
-  marginRight = 0
-}) => {
+const selectOuterWidthStyles = ({ outerBorderGap, outerBorderWidth, width }) => {
   // The inner container's bounding box is the bounding box of the button overall
   // so this many device pixels will sit outside of the overall bounding box
   const outerBorderOffset = getOuterBorderOffset({ outerBorderGap, outerBorderWidth })
   const widthStyles = {
-    marginTop: marginTop - outerBorderOffset,
-    marginBottom: marginBottom - outerBorderOffset,
-    marginLeft: marginLeft - outerBorderOffset,
-    marginRight: marginRight - outerBorderOffset
+    margin: 0 - outerBorderOffset
   }
 
   if (!width) {
@@ -59,9 +48,8 @@ const selectOuterWidthStyles = ({
       ...widthStyles,
       // Wrap content, stopping a flex parent's default align-items: stretch stretching focus ring beyond content
       ...Platform.select({
-        web: { width: 'fit-content' },
-        // No fit-content or inline-block in RN. TODO: we might need to provide a prop to allow flex-end or center
-        native: { alignSelf: 'flex-start' }
+        // width: fit-content isn't supported on Firefox; can't cascade props like CSS `width: fit-content; width: --moz-fit-content;`
+        web: { display: 'inline-flex' }
       })
     }
   }

package/src/Button/ButtonGroup.jsx

@@ -1,21 +1,20 @@
 import React from 'react'
 import PropTypes from 'prop-types'
-import { View, Platform } from 'react-native'
+import { Platform } from 'react-native'
 
 import ButtonBase from './ButtonBase'
+import { StackWrap } from '../StackView'
 import { useViewport } from '../ViewportProvider'
 import { useThemeTokens } from '../ThemeProvider'
-import { a11yProps, pressProps, variantProp, getTokensPropType } from '../utils/propTypes'
+import {
+  a11yProps,
+  pressProps,
+  variantProp,
+  getTokensPropType,
+  selectTokens
+} from '../utils/propTypes'
 import { useMultipleInputValues } from '../utils/input'
 
-const selectContainerStyles = ({ direction }) => ({
-  flexDirection: direction
-})
-
-const selectItemTokens = ({ gap }, index) => ({
-  marginLeft: index && gap
-})
-
 const ButtonGroup = ({
   variant,
   buttonVariant = {},
@@ -34,7 +33,8 @@ const ButtonGroup = ({
 }) => {
   const viewport = useViewport()
   const themeTokens = useThemeTokens('ButtonGroup', tokens, variant, { viewport })
-  const containerStyles = selectContainerStyles(themeTokens)
+  const stackTokens = selectTokens('StackView', themeTokens)
+  const { direction, space } = themeTokens
 
   const { currentValues, toggleOneValue } = useMultipleInputValues({
     initialValues,
@@ -51,9 +51,8 @@ const ButtonGroup = ({
   const itemA11yRole = a11y.accessibilityRole === 'radioGroup' ? 'radio' : 'checkbox'
 
   return (
-    <View style={containerStyles} {...a11y}>
+    <StackWrap {...a11y} space={space} direction={direction} tokens={stackTokens}>
       {items.map(({ label, id = label, accessibilityLabel }, index) => {
-        const itemTokens = selectItemTokens(themeTokens, index)
         const isSelected = currentValues.includes(id)
 
         // Allow handlers to be passed down for blur, hover, focus, pressIn, etc
@@ -87,15 +86,12 @@ const ButtonGroup = ({
 
         // Ensure button is direct child of group as MacOS voiceover only applies "X of Y" to
         // "radio" if it's a direct child of "radiogroup", even if aria-posinset etc exists
-        // See also: TODO: make margin the responsibility of a parent
-        // https://github.com/telus/universal-design-system/issues/525
         return (
           <ButtonBase
             key={id}
             {...pressHandlers}
             onPress={handlePress}
             variant={{ component: 'ButtonGroup', ...buttonVariant }}
-            tokens={itemTokens}
             selected={isSelected}
             inactive={inactive}
             {...itemA11y}
@@ -104,7 +100,7 @@ const ButtonGroup = ({
           </ButtonBase>
         )
       })}
-    </View>
+    </StackWrap>
   )
 }
 

package/src/Divider/Divider.jsx

@@ -2,7 +2,12 @@ import React from 'react'
 import PropTypes from 'prop-types'
 import { View, StyleSheet, Platform } from 'react-native'
 import { useThemeTokens } from '../ThemeProvider'
-import { getTokensPropType, variantProp } from '../utils/propTypes'
+import Spacer from '../Spacer'
+import { getTokensPropType, variantProp, spacingProps } from '../utils'
+/**
+ * @typedef {import('../utils/propTypes.js').SpacingIndex} SpacingIndex
+ * @typedef {import('../utils/propTypes.js').SpacingObject} SpacingObject
+ */
 
 /**
  * A basic divider component, horizontal by default. Color and thickness can be controlled by theme.
@@ -16,11 +21,31 @@ import { getTokensPropType, variantProp } from '../utils/propTypes'
  *
  * In a flexbox row, vertical dividers will automatically size to their parent height.
  *
+ * ## Space
+ *
+ * Use this to create **space either side of the divider**. For simple cases, pass a number referring to
+ * a position on the theme's spacing scale; for example, this will put a Spacer of the smallest supported
+ * size either side of the divider:
+ *
+ * ```jsx
+ * <Divider space={1} />
+ * ```
+ *
+ * `space` prop uses `useSpacingScale` and may accept a {@link SpacingObject} or a {@link SpacingIndex} number.
+ *
+ * To **reduce the length of a divider** as well as creating space between it and its neighbours, wrap it in
+ * a `Box` component. For example, this will have the second-smallest theme-supported spacing value between
+ * the dividing line and its neighbours, and will shorten the line at either end by the same amount:
+ *
+ * ```jsx
+ * <Box space={2}><Divider /></Box>
+ * ```
+ *
  * ## Accessibility
  *
  * For accessibility purposes a divider component will be described with ARIA attributes, i.e. `role="separator"` and `aria-orientation="vertical/horizontal"`.
  */
-const Divider = ({ variant, vertical = false, tokens, testID }) => {
+const Divider = ({ variant, vertical = false, space, tokens, testID }) => {
   const { color, width } = useThemeTokens('Divider', tokens, variant)
 
   const borderStyles = vertical
@@ -43,11 +68,21 @@ const Divider = ({ variant, vertical = false, tokens, testID }) => {
       : // There are no such equivalent attributes for native
         {}
 
-  return <View style={[styles.divider, borderStyles]} testID={testID} {...a11y} />
+  const divider = <View style={[styles.divider, borderStyles]} testID={testID} {...a11y} />
+  if (!space) return divider
+  const spacerProps = { space, direction: vertical ? 'row' : 'column' }
+  return (
+    <>
+      <Spacer {...spacerProps} testID={testID ? `${testID}-Spacer-before` : undefined} />
+      {divider}
+      <Spacer {...spacerProps} testID={testID ? `${testID}-Spacer-after` : undefined} />
+    </>
+  )
 }
 
 Divider.propTypes = {
   tokens: getTokensPropType('Divider'),
+  space: spacingProps.types.spacingValue,
   variant: variantProp.propType,
   /**
    * By default, the divider is a horizontal line the full width of its parent.

package/src/Feedback/Feedback.jsx

@@ -0,0 +1,99 @@
+import React from 'react'
+import { Text, View, StyleSheet } from 'react-native'
+import PropTypes from 'prop-types'
+
+import { applyTextStyles, useThemeTokens } from '../ThemeProvider'
+import { a11yProps, getTokensPropType, selectTokens, variantProp } from '../utils'
+
+const selectStyles = (tokens) => selectTokens('Feedback', tokens)
+
+const selectTitleTextStyles = ({ titleFontSize, ...tokens }) =>
+  applyTextStyles(selectTokens('Typography', { ...tokens, fontSize: titleFontSize }))
+const selectContentTextStyles = ({ contentFontSize, ...tokens }) =>
+  applyTextStyles(selectTokens('Typography', { ...tokens, fontSize: contentFontSize }))
+
+const selectIconTokens = ({ iconSize, iconColor }) => ({
+  size: iconSize,
+  color: iconColor
+})
+
+const selectIconContainerStyles = ({ iconGap }) => ({
+  paddingRight: iconGap
+})
+
+/**
+ * A feedback box commonly used with form fields.
+ *
+ * ### Standalone usage
+ * While its primary use is to facilitate feedback states for other form components such as `TextInput`,
+ * you may use it standalone.
+ *
+ * ### Complex content
+ * You may pass any React tree as the children of this component, bear in mind that a render function
+ * is better suited for styling children based on Feedback's variant.
+ *
+ * ### Using a render function
+ * When a function is passed for rendering content, it will receive the feedback text styles and
+ * variant as arguments.
+ *
+ * ### Accessibility
+ * All accessibility props set on this component will be applied to the outer container.
+ */
+const Feedback = ({ title, children, tokens, variant, ...rest }) => {
+  const themeTokens = useThemeTokens('Feedback', tokens, variant)
+
+  const { icon: IconComponent } = themeTokens
+
+  const titleTextStyles = selectTitleTextStyles(themeTokens)
+  const contentTextStyles = selectContentTextStyles(themeTokens)
+
+  const content =
+    typeof children === 'string' ? <Text style={contentTextStyles}>{children}</Text> : children
+
+  const accessibilityProps = a11yProps.select(rest)
+
+  // TODO: use Stack to separate the title from content (space 2)
+
+  return (
+    <View style={selectStyles(themeTokens)} {...accessibilityProps}>
+      {title !== undefined && (
+        <View style={staticStyles.title}>
+          {IconComponent && (
+            <View style={selectIconContainerStyles(themeTokens)}>
+              <IconComponent tokens={selectIconTokens(themeTokens)} />
+            </View>
+          )}
+          <Text style={titleTextStyles}>{title}</Text>
+        </View>
+      )}
+      {content && typeof content === 'function' ? (
+        content({ textStyles: contentTextStyles, variant })
+      ) : (
+        <View>{content}</View>
+      )}
+    </View>
+  )
+}
+
+Feedback.propTypes = {
+  /**
+   * Emphasized summary of the feedback. If an icon is set, it is rendered next to the title.
+   */
+  title: PropTypes.string,
+  /**
+   * Feedback content rendered below the title. A render function `({textStyles, variant}) => {}` is supported.
+   */
+  children: PropTypes.oneOfType([PropTypes.string, PropTypes.node, PropTypes.func]),
+  tokens: getTokensPropType('Feedback'),
+  variant: variantProp.propType
+}
+
+export default Feedback
+
+const staticStyles = StyleSheet.create({
+  title: {
+    display: 'flex',
+    flexDirection: 'row',
+    alignItems: 'center'
+  }
+})

package/src/Feedback/index.js

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

package/src/Icon/Icon.jsx

@@ -19,7 +19,8 @@ const Icon = ({ IconSvg, variant, label, titleId, tokens = {} }) => {
         transition: 'transform 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(' ')

package/src/InputLabel/InputLabel.jsx

@@ -0,0 +1,99 @@
+import React from 'react'
+import { View, Text, StyleSheet } from 'react-native'
+import PropTypes from 'prop-types'
+
+import { applyTextStyles, useThemeTokens } from '../ThemeProvider'
+import { getTokensPropType, selectTokens, variantProp } from '../utils'
+
+import LabelContent from './LabelContent'
+
+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)
+
+  // TODO: use the actual Tooltip component here
+  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>
+      )}
+      {tooltip && <Text>?</Text>}
+      {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: 'center'
+  },
+  containerWithHintBelow: {
+    flexWrap: 'wrap'
+  },
+  label: {
+    flexShrink: 0
+  },
+  hintBelow: {
+    flexBasis: '100%',
+    flexShrink: 0
+  }
+})

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/LabelContent.web.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/index.js

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

package/src/Link/LinkBase.jsx

@@ -40,7 +40,10 @@ const selectOuterBorderStyles = ({
         outline: outerBorderOutline,
         borderWidth: outerBorderWidth,
         borderColor: outerBorderColor,
-        borderRadius: outerBorderRadius
+        borderRadius: outerBorderRadius,
+        // 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'
       }
     : {}
 
@@ -62,10 +65,12 @@ const selectIconStyles = ({
   iconGapBefore,
   iconGapAfter,
   iconScale,
-  iconTranslateX
+  iconTranslateX,
+  iconTranslateY
 }) => ({
   scale: iconScale,
   translateX: iconTranslateX,
+  translateY: iconTranslateY,
   size: iconSize,
   gapBefore: iconGapBefore,
   gapAfter: iconGapAfter
@@ -181,7 +186,8 @@ const LinkBase = ({
     size: iconStyles.size ? iconStyles.size * iconScale : undefined,
     color: contentStyles.color ?? undefined,
     scale: iconStyles.scale ?? undefined,
-    translateX: iconStyles.translateX ?? undefined
+    translateX: iconStyles.translateX ?? undefined,
+    translateY: iconStyles.translateY ?? undefined
   }
 
   const iconContent = <IconComponent tokens={iconTokens} variant={iconVariant} />

package/src/Spacer/Spacer.jsx

@@ -0,0 +1,91 @@
+import React from 'react'
+import PropTypes from 'prop-types'
+import { StyleSheet, View } from 'react-native'
+
+import { useSpacingScale, spacingProps } from '../utils'
+/**
+ * @typedef {import('../utils/propTypes.js').SpacingValue} SpacingValue
+ * @typedef {import('../utils/propTypes.js').SpacingObject} SpacingObject
+ */
+
+const selectSizeStyle = (size, direction) => ({
+  // Only apply space in one direction at a time, else large spacers will increase the
+  // 'across' size of the parent and mess up siblings with styles like `alignItems: stretch`.
+  [direction === 'row' ? 'width' : 'height']: size
+})
+
+/**
+ * An empty element used to create a gap between components that is sized according to the theme spacing scale,
+ * passing its `space` prop ({@link SpacingValue}) to `useSpacingScale`.
+ *
+ * ## Simple spacing
+ *
+ * For most simple uses, pass a number to Spacer's `space` prop referring to an index in the theme's
+ * spacing scale. For example, for a spacer of the theme's smallest non-zero spacing size:
+ *
+ * ```jsx
+ * <Spacer space={1} />
+ * ```
+ *
+ * ## Responsive spacing
+ *
+ * Different spacing scale sizes may be chosen for different viewports by passing `space` a {@link SpacingObject}
+ * using keys for the viewports at and above which certain spacing indexes should apply.
+ *
+ * This can be useful when a Spacer is inside a layout with a shape that changes between viewports.
+ *
+ * For example, a spacer might need no width below 'md' viewport because the items it separates will be on separate lines,
+ * but may need a visible size above that viewport, and a wider size at the highest viewport:
+ *
+ * ```jsx
+ * <Spacer space={{ xs: 0, md: 2, xl: 3 }} />
+ * ```
+ *
+ * Note that themes may also define viewport-specific behaviour for indexes on the spacing scale. These viewport
+ * props should only be used where necessary to achieve a certain responsive layoutm and shouldn't be used to replace
+ * or deviate from responsive spacing behaviour in a theme that is intended to apply universally.
+ *
+ * ## More options
+ *
+ * See `useSpacingScale` hook for more options that may be used with the `space` prop.
+ *
+ * ## Accessibility
+ *
+ * Spacer has no content and is ignored by tools such as screen readers. Use `Divider` for
+ * separations between elements that may be treated as semantically meaningful on web.
+ */
+const Spacer = ({ space = 1, direction = 'column', testID }) => {
+  const size = useSpacingScale(space)
+  const sizeStyle = selectSizeStyle(size, direction)
+  return <View testID={testID} style={[staticStyles.stretch, sizeStyle]} />
+}
+
+Spacer.propTypes = {
+  /**
+   * The size of the spacer according to the theme's spacing scale.
+   * Either a number corresponding to a position on the theme's spacing scale (1 is smallest, 2 is second smallest, etc),
+   * or, a SpacingObject with viewport keys and options (see `useSpacingScale` for details).
+   */
+  space: spacingProps.types.spacingValue,
+  /**
+   * The spacer applies space in only one direction, which is controlled by the `direction` prop:
+   *
+   * - `'column'` (default) applies space vertically; has a fixed height and not width.
+   * - `'row'` applies space horizontally; has a fixed width and not height.
+   */
+  direction: PropTypes.oneOf(['column', 'row']),
+  /**
+   * @ignore
+   * In tests, the only way to select Spacers is with testID prop and getByTestId, since they have no content,
+   * no accessibility role, and there is no equivalent of nextSibling in React Native Testing Library.
+   */
+  testID: PropTypes.string
+}
+
+const staticStyles = StyleSheet.create({
+  stretch: {
+    alignSelf: 'stretch'
+  }
+})
+
+export default Spacer

package/src/Spacer/index.js

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