@telus-uds/components-base 0.0.2-prerelease.3 → 0.0.2-prerelease.7

package/src/Checkbox/Checkbox.jsx

@@ -0,0 +1,275 @@
+import React from 'react'
+import PropTypes from 'prop-types'
+import { Pressable, StyleSheet, Text, View } from 'react-native'
+
+import CheckboxInput from './CheckboxInput'
+// @todo move `LabelContent` outside of the `InputLabel` and fix
+// the issue with the cursor not being pointer on Web
+import CheckboxLabel from '../InputLabel/LabelContent'
+import Feedback from '../Feedback'
+import StackView from '../StackView'
+import { applyShadowToken, applyTextStyles, useThemeTokensCallback } from '../ThemeProvider'
+import { getTokensPropType, useInputValue, variantProp } from '../utils'
+import { a11yProps } from '../utils/propTypes'
+import useUniqueId from '../utils/useUniqueId'
+
+const selectInputStyles = (
+  {
+    iconBackgroundColor,
+    inputBorderColor,
+    inputBorderRadius,
+    inputBorderWidth,
+    inputBackgroundColor,
+    inputHeight,
+    inputOutlineColor,
+    inputOutlineWidth,
+    inputShadow,
+    inputWidth
+  },
+  isChecked
+) => ({
+  borderColor: inputBorderColor,
+  borderWidth: inputBorderWidth,
+  borderRadius: inputBorderRadius,
+  backgroundColor: isChecked ? iconBackgroundColor : inputBackgroundColor,
+  outlineStyle: 'solid',
+  outlineColor: inputOutlineColor,
+  outlineWidth: inputOutlineWidth,
+  height: inputHeight,
+  width: inputWidth,
+  ...applyShadowToken(inputShadow)
+})
+const selectLabelStyles = ({
+  labelColor,
+  labelFontName,
+  labelFontSize,
+  labelFontWeight,
+  labelMarginLeft,
+  labelLineHeight
+}) => ({
+  marginLeft: labelMarginLeft,
+  ...applyTextStyles({
+    color: labelColor,
+    fontName: labelFontName,
+    fontWeight: labelFontWeight,
+    fontSize: labelFontSize,
+    lineHeight: labelLineHeight
+  })
+})
+const selectContainerStyles = ({ containerMarginBottom }) => ({
+  marginBottom: containerMarginBottom
+})
+const selectIconTokens = ({ iconColor, iconSize }) => ({
+  color: iconColor,
+  size: iconSize
+})
+const selectFeedbackTokens = ({ feedbackMarginBottom, feedbackMarginTop, feedbackPosition }) => ({
+  feedbackPosition,
+  feedbackMarginBottom,
+  feedbackMarginTop
+})
+
+/**
+ * Basic Checkbox component.
+ *
+ * ## Component API
+ *
+ * Use `label` prop to provide a label for the checkbox.
+ * For a disabled `Checkbox` set the `inactive` prop to `true`.
+ *
+ * ### Controlled version
+ *
+ * If the checkbox is controlled from outside, it needs to receive `checked` and `onChange` props.
+ *
+ * ### Uncontrolled version
+ *
+ * In case of uncontrolled checkbox you can use `defaultChecked` prop to provide the initial value.
+ * Whenever the checkbox gets toggled, it calls the `onChange` callback with the new value (boolean).
+ *
+ * ### Using within forms
+ *
+ * You can pass `name` and `value` props if you need a particular checkbox to be a part of a group of
+ * checkboxes on a form.
+ *
+ * ### Validation and feedback
+ *
+ * You can use the `feedback` prop to provide a comment related to the checkbox element. If the comment
+ * is related to a validation error, the checkbox and the feedback can be styled accordingly by setting
+ * the `error` prop to `true` (can also be done without feedback).
+ *
+ * ## A11y guidelines
+ *
+ * Checkbox component accepts all the common accessibility props, but also sets some defaults, including
+ * accessibility role `'checkbox'` and accessibility state that depends on the other props (`checked`, `inactive`)
+ * or the internal state in case of uncontrolled checkbox.
+ *
+ */
+const Checkbox = ({
+  checked,
+  defaultChecked,
+  error = false,
+  feedback,
+  id,
+  inactive,
+  label,
+  name,
+  onChange,
+  tokens,
+  value,
+  variant,
+  ...rest
+}) => {
+  const { currentValue: isChecked, setValue: setIsChecked, isControlled } = useInputValue(
+    {
+      value: checked,
+      initialValue: defaultChecked,
+      onChange
+    },
+    'useCheckboxValue'
+  )
+  const getTokens = useThemeTokensCallback('Checkbox', tokens, {
+    checked: isChecked,
+    inactive,
+    error,
+    ...variant
+  })
+  const defaultTokens = getTokens()
+  const { feedbackMarginBottom, feedbackMarginTop, feedbackPosition } = selectFeedbackTokens(
+    defaultTokens
+  )
+  const styles = StyleSheet.create({
+    feedbackContainer: { marginTop: feedbackMarginTop, marginBottom: feedbackMarginBottom }
+  })
+  const handleChange = () => {
+    if (!inactive) {
+      setIsChecked(!isChecked)
+    }
+  }
+  const accessibilityProps = a11yProps.select(rest)
+  const uniqueId = useUniqueId('checkbox')
+  const inputId = id ?? uniqueId
+
+  // @todo our current version of React Native Web doesn't include
+  // keyboard support on `Pressable` (which starts with 0.15.3), so
+  // the complete accessibility of the `Checkbox` component on Web
+  // (namely, change on key pressed) is pending RNW upgrade
+  // (see https://github.com/necolas/react-native-web/issues/1950)
+  return (
+    <View style={staticStyles.wrapper}>
+      <StackView direction={feedbackPosition === 'top' ? 'column-reverse' : 'column'} space={0}>
+        <Pressable
+          disabled={inactive}
+          onPress={handleChange}
+          accessibilityRole="checkbox"
+          accessibilityState={{ checked: isChecked, disabled: inactive }}
+          {...accessibilityProps}
+        >
+          {({ focused: focus, hovered: hover, pressed }) => {
+            const { icon: IconComponent, ...stateTokens } = getTokens({ focus, hover, pressed })
+            const iconTokens = selectIconTokens(stateTokens)
+
+            return (
+              <View style={[staticStyles.container, selectContainerStyles(stateTokens)]}>
+                <View
+                  style={StyleSheet.flatten([
+                    staticStyles.defaultInputStyles,
+                    selectInputStyles(stateTokens, isChecked)
+                  ])}
+                  testID="Checkbox-Input"
+                >
+                  {/* Add a real input on Web, skip on native platforms */}
+                  <CheckboxInput
+                    checked={isChecked}
+                    defaultChecked={defaultChecked}
+                    disabled={inactive}
+                    id={inputId}
+                    isControlled={isControlled}
+                    name={name}
+                    value={value}
+                  />
+                  {isChecked && IconComponent && (
+                    <IconComponent tokens={iconTokens} testID="Checkbox-Icon" />
+                  )}
+                </View>
+                {Boolean(label) && (
+                  <Text style={selectLabelStyles(stateTokens)}>
+                    <CheckboxLabel forId={inputId}>{label}</CheckboxLabel>
+                  </Text>
+                )}
+              </View>
+            )
+          }}
+        </Pressable>
+        {Boolean(feedback) && (
+          <View style={styles.feedbackContainer}>
+            <Feedback
+              title={feedback}
+              variant={{ icon: error === true }}
+              validation={error === true ? 'error' : undefined}
+            />
+          </View>
+        )}
+      </StackView>
+    </View>
+  )
+}
+
+Checkbox.propTypes = {
+  ...a11yProps.propTypes,
+  /**
+   * Use `checked` for controlled Checkbox. For uncontrolled Checkbox, use the `defaultChecked` prop.
+   */
+  checked: PropTypes.bool,
+  /**
+   * Use `defaultChecked` to provide the initial value for an uncontrolled Checkbox.
+   */
+  defaultChecked: PropTypes.bool,
+  /**
+   * A detailed description of related validation error or additional instructions (depending on the `error` prop).
+   */
+  feedback: PropTypes.string,
+  /**
+   * Checkbox ID.
+   */
+  id: PropTypes.string,
+  /**
+   * Whether the corresponding input is disabled or active.
+   */
+  inactive: PropTypes.bool,
+  /**
+   * The label.
+   */
+  label: PropTypes.string,
+  /**
+   * Associate this checkbox with a group (set as the name attribute).
+   */
+  name: PropTypes.string,
+  /**
+   * Whether the underlying input triggered a validation error or not.
+   */
+  error: PropTypes.bool,
+  /**
+   * The value. Must be unique within the group.
+   */
+  value: PropTypes.oneOfType([PropTypes.string, PropTypes.number, PropTypes.bool]),
+  /**
+   * Callback called when a controlled checkbox gets interacted with.
+   */
+  onChange: PropTypes.func,
+  /**
+   * Checkbox tokens.
+   */
+  tokens: getTokensPropType('Checkbox'),
+  /**
+   * Checkbox variant.
+   */
+  variant: variantProp.propType
+}
+
+export default Checkbox
+
+const staticStyles = StyleSheet.create({
+  wrapper: { backgroundColor: 'transparent' },
+  container: { flexDirection: 'row', alignItems: 'center' },
+  defaultInputStyles: { alignItems: 'center', justifyContent: 'center' }
+})

package/src/Checkbox/CheckboxInput.native.jsx

@@ -0,0 +1,6 @@
+/**
+ * There's no checkbox input on native platforms, so this is a noop.
+ */
+const CheckboxInput = () => null
+
+export default CheckboxInput

package/src/Checkbox/CheckboxInput.web.jsx

@@ -0,0 +1,55 @@
+import React, { forwardRef } from 'react'
+import PropTypes from 'prop-types'
+
+/**
+ * On Web we need to include an actual input but hide it.
+ */
+const CheckboxInput = forwardRef(
+  ({ checked, defaultChecked, disabled, id, isControlled, name, onChange, value }, ref) => {
+    const handleClick = (event) => {
+      // Cancel the click dispatched via the label tag, since it's already wrapped
+      // in <Pressable>
+      event.preventDefault()
+      event.stopPropagation()
+    }
+
+    return (
+      <input
+        checked={isControlled ? checked : undefined}
+        defaultChecked={isControlled ? undefined : defaultChecked}
+        disabled={disabled}
+        hidden
+        id={id}
+        name={name}
+        onChange={onChange}
+        onClick={handleClick}
+        ref={ref}
+        type="checkbox"
+        value={value}
+      />
+    )
+  }
+)
+CheckboxInput.displayName = 'CheckboxInput'
+
+CheckboxInput.propTypes = {
+  checked: PropTypes.bool,
+  defaultChecked: PropTypes.bool,
+  disabled: PropTypes.bool,
+  id: PropTypes.string.isRequired,
+  isControlled: PropTypes.bool.isRequired,
+  name: PropTypes.string,
+  onChange: PropTypes.func,
+  value: PropTypes.string
+}
+
+CheckboxInput.defaultProps = {
+  checked: undefined,
+  defaultChecked: undefined,
+  disabled: false,
+  name: undefined,
+  onChange: () => {},
+  value: undefined
+}
+
+export default CheckboxInput

package/src/Checkbox/index.js

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

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,108 @@
+import React from 'react'
+import { StyleSheet, Text, View } from 'react-native'
+import PropTypes from 'prop-types'
+
+import { applyTextStyles, useThemeTokens } from '../ThemeProvider'
+import { a11yProps, getTokensPropType, selectTokens, variantProp } from '../utils'
+import StackView from '../StackView'
+
+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, id, validation, tokens, variant, ...rest }) => {
+  const themeTokens = useThemeTokens('Feedback', tokens, { ...variant, validation })
+  const { space } = themeTokens
+
+  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({
+    accessibilityRole: validation === 'error' ? 'alert' : undefined,
+    ...rest
+  })
+
+  return (
+    <View style={selectStyles(themeTokens)} {...accessibilityProps} nativeID={id}>
+      <StackView space={space}>
+        {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 })
+          : content}
+      </StackView>
+    </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]),
+  /**
+   * Use to visually mark the Feedback as valid or invalid.
+   */
+  validation: PropTypes.oneOf(['error', 'success']),
+  /** @ignore */
+  id: PropTypes.string,
+  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

@@ -3,23 +3,28 @@ 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 = ({ IconSvg, variant, label, titleId, 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} />
+    <IconSvg title={label} titleId={titleId} 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(' ')

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 { 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 && <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 IconText from './IconText'
 
 export default Icon
-export { iconComponentPropTypes, iconSvgPropTypes }
+export { iconComponentPropTypes, iconSvgPropTypes, IconText }