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

package/src/Button/ButtonGroup.jsx

@@ -1,24 +1,23 @@
 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 { useThemeTokens, useThemeTokensCallback } from '../ThemeProvider'
+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
-})
+import { getPressHandlersWithArgs } from '../utils/pressability'
 
 const ButtonGroup = ({
   variant,
-  buttonVariant = {},
   tokens,
   items = [],
   values,
@@ -28,13 +27,16 @@ const ButtonGroup = ({
   readOnly = false,
   inactive = false,
   accessibilityRole = maxValues === 1
-    ? 'radioGroup' // radioGroup is cross-platform; only web aria has generic groups
+    ? 'radiogroup' // radiogroup is cross-platform; only web aria has generic groups
     : Platform.select({ web: 'group', default: 'none' }),
   ...rest
 }) => {
   const viewport = useViewport()
   const themeTokens = useThemeTokens('ButtonGroup', tokens, variant, { viewport })
-  const containerStyles = selectContainerStyles(themeTokens)
+  const stackTokens = selectTokens('StackView', themeTokens)
+  const { direction, space } = themeTokens
+
+  const getButtonTokens = useThemeTokensCallback('ButtonGroupItem', tokens, variant)
 
   const { currentValues, toggleOneValue } = useMultipleInputValues({
     initialValues,
@@ -48,23 +50,16 @@ const ButtonGroup = ({
     accessibilityRole,
     ...rest
   })
-  const itemA11yRole = a11y.accessibilityRole === 'radioGroup' ? 'radio' : 'checkbox'
+  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
-        const pressHandlers = Object.fromEntries(
-          Object.entries(pressProps.select(rest)).map(([key, handler]) => ({
-            [key]: (args) => {
-              // Pass each handler data on this button and current selection
-              handler({ id, label, currentValues }, ...args)
-            }
-          }))
-        )
+        // Pass an object of relevant component state as first argument for any passed-in press handlers
+        const pressHandlers = getPressHandlersWithArgs(rest, [{ id, label, currentValues }])
+
         const handlePress = () => {
           if (pressHandlers.onPress) pressHandlers.onPress()
           toggleOneValue(id)
@@ -74,28 +69,17 @@ const ButtonGroup = ({
           accessibilityState: { checked: isSelected },
           accessibilityRole: itemA11yRole,
           accessibilityLabel,
-          ...Platform.select({
-            web: {
-              // accessibilityPosInSet etc exists in React Native Web main branch
-              // but not in a release compatible with Expo etc; just use `aria-*`
-              'aria-setsize': items.length,
-              'aria-posinset': index + 1
-            },
-            default: {}
-          })
+          ...a11yProps.getPositionInSet(items.length, index)
         }
 
         // 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}
+            tokens={getButtonTokens}
             selected={isSelected}
             inactive={inactive}
             {...itemA11y}
@@ -104,7 +88,7 @@ const ButtonGroup = ({
           </ButtonBase>
         )
       })}
-    </View>
+    </StackWrap>
   )
 }
 
@@ -113,7 +97,6 @@ ButtonGroup.propTypes = {
   ...pressProps.propTypes,
   tokens: getTokensPropType('ButtonGroup'),
   variant: variantProp.propType,
-  buttonVariant: variantProp.propType,
   /**
    * The maximum number of items a user may select at once. Defaults to 1 and behaves
    * like radio buttons. To have no limit and allow any number of selections, pass `null`.

package/src/Button/ButtonLink.jsx

@@ -1,21 +1,31 @@
 import React from 'react'
 import ButtonBase from './ButtonBase'
-import buttonPropTypes from './propTypes'
+import buttonPropTypes, { textAndA11yText } from './propTypes'
 import { a11yProps, hrefAttrsProp, linkProps } from '../utils/propTypes'
+import { useThemeTokensCallback } from '../ThemeProvider'
 
 /**
  * `ButtonLink` is a component with the semantics and behaviour of a link, but with the visual appearance of a button.
  * ButtonLink is a block-level component and should not be used inline.
  */
-const ButtonLink = ({ accessibilityRole = 'link', ...props }) => {
+const ButtonLink = ({ accessibilityRole = 'link', tokens, variant, ...props }) => {
   const { hrefAttrs, rest } = hrefAttrsProp.bundle(props)
-  return <ButtonBase accessibilityRole={accessibilityRole} hrefAttrs={hrefAttrs} {...rest} />
+  const getTokens = useThemeTokensCallback('Button', tokens, variant)
+  return (
+    <ButtonBase
+      accessibilityRole={accessibilityRole}
+      tokens={getTokens}
+      hrefAttrs={hrefAttrs}
+      {...rest}
+    />
+  )
 }
 
 ButtonLink.propTypes = {
   ...a11yProps.types,
   ...buttonPropTypes,
-  ...linkProps.types
+  ...linkProps.types,
+  children: textAndA11yText
 }
 
 export default ButtonLink

package/src/Button/propTypes.js

@@ -1,5 +1,11 @@
 import PropTypes from 'prop-types'
+import ABBPropTypes from 'airbnb-prop-types'
 import { variantProp } from '../utils/propTypes'
+import A11yText from '../A11yText'
+
+export const textAndA11yText = ABBPropTypes.childrenOf(
+  PropTypes.oneOfType([ABBPropTypes.elementType(A11yText), PropTypes.string])
+)
 
 const buttonPropTypes = {
   /**
@@ -12,10 +18,14 @@ const buttonPropTypes = {
    */
   disabled: PropTypes.bool,
   /**
-   * Button's children must be either a text string, or a render function which is passed an object of
+   * Button's children must be either:
+   *  - One or more text strings and / or A11yText components
+   *  - A render function with contents that responds to current button state by being passed an object of:
+   * ```
    * { hovered<bool>, focused<bool>, pressed<bool>, inactive<bool>, selected<bool>, textStyles<RNStyle> }
+   * ```
    */
-  children: PropTypes.oneOfType([PropTypes.string, PropTypes.func]).isRequired,
+  children: PropTypes.oneOfType([PropTypes.func, textAndA11yText]).isRequired,
   /**
    * Function called when the button is pressed. Required unless the button has a href.
    */

package/src/Card/Card.jsx

@@ -1,34 +1,11 @@
 import React from 'react'
 import PropTypes from 'prop-types'
-import { View } from 'react-native'
 
-import { applyShadowToken, useThemeTokens } from '../ThemeProvider'
+import { useThemeTokens } from '../ThemeProvider'
 import { getTokensPropType, variantProp } from '../utils'
 import { useViewport } from '../ViewportProvider'
 import { a11yProps } from '../utils/propTypes'
-
-// Ensure explicit selection of tokens
-const selectStyles = ({
-  backgroundColor,
-  borderColor,
-  borderRadius,
-  borderWidth,
-  paddingBottom,
-  paddingLeft,
-  paddingRight,
-  paddingTop,
-  shadow
-}) => ({
-  backgroundColor,
-  borderColor,
-  borderRadius,
-  borderWidth,
-  paddingBottom,
-  paddingLeft,
-  paddingRight,
-  paddingTop,
-  ...applyShadowToken(shadow)
-})
+import CardBase from './CardBase'
 
 /**
  * A basic card component, unstyled by default.
@@ -81,13 +58,10 @@ const selectStyles = ({
 const Card = ({ children, tokens, variant, ...rest }) => {
   const viewport = useViewport()
   const themeTokens = useThemeTokens('Card', tokens, variant, { viewport })
-  const cardStyle = selectStyles(themeTokens)
-  const a11y = a11yProps.select(rest)
-
   return (
-    <View style={cardStyle} {...a11y}>
+    <CardBase tokens={themeTokens} {...rest}>
       {children}
-    </View>
+    </CardBase>
   )
 }
 

package/src/Card/CardBase.jsx

@@ -0,0 +1,57 @@
+import React from 'react'
+import PropTypes from 'prop-types'
+import { View } from 'react-native'
+
+import { applyShadowToken } from '../ThemeProvider'
+import { getTokensPropType } from '../utils'
+import { a11yProps, viewProps } from '../utils/propTypes'
+
+// Ensure explicit selection of tokens
+const selectStyles = ({
+  flex,
+  backgroundColor,
+  borderColor,
+  borderRadius,
+  borderWidth,
+  paddingBottom,
+  paddingLeft,
+  paddingRight,
+  paddingTop,
+  minWidth,
+  shadow
+}) => ({
+  flex,
+  backgroundColor,
+  borderColor,
+  borderRadius,
+  borderWidth,
+  paddingBottom,
+  paddingLeft,
+  paddingRight,
+  paddingTop,
+  minWidth,
+  ...applyShadowToken(shadow)
+})
+
+/**
+ * A themeless base component for Card which components can apply theme tokens to. Not
+ * intended to be used in apps or sites directly: build themed components on top of this.
+ */
+const CardBase = ({ children, tokens, ...rest }) => {
+  const cardStyle = selectStyles(typeof tokens === 'function' ? tokens() : tokens)
+  const props = { ...a11yProps.select(rest), ...viewProps.select(rest) }
+
+  return (
+    <View style={cardStyle} {...props}>
+      {children}
+    </View>
+  )
+}
+
+CardBase.propTypes = {
+  children: PropTypes.node,
+  tokens: getTokensPropType('Card'),
+  ...a11yProps.types
+}
+
+export default CardBase

package/src/Card/PressableCardBase.jsx

@@ -0,0 +1,112 @@
+import React from 'react'
+import PropTypes from 'prop-types'
+import { Pressable, Platform } from 'react-native'
+
+import { useViewport } from '../ViewportProvider'
+import { applyOuterBorder, validateThemeTokens } from '../ThemeProvider'
+import {
+  resolvePressableState,
+  resolvePressableTokens,
+  selectTokens,
+  getTokenNames,
+  getTokensSetPropType,
+  variantProp,
+  linkProps
+} from '../utils'
+import { a11yProps } from '../utils/propTypes'
+import CardBase from './CardBase'
+
+const tokenKeys = [
+  ...getTokenNames('Card'),
+
+  // Outer border tokens. TODO: centralise common token sets like these as part of
+  // https://github.com/telus/universal-design-system/issues/782
+  'outerBorderColor',
+  'outerBorderWidth',
+  'outerBorderGap'
+]
+export const selectPressableCardTokens = (tokens) =>
+  Object.fromEntries(tokenKeys.map((key) => [key, tokens[key]]))
+
+/**
+ * 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 PressableCardBase = ({
+  children,
+  tokens,
+  checked,
+  validation,
+  inactive,
+  href,
+  hrefAttrs,
+  onPress,
+  accessibilityRole = href ? 'link' : undefined,
+  ...rest
+}) => {
+  const viewport = useViewport()
+  const a11y = a11yProps.select({
+    ...rest,
+    accessibilityRole
+  })
+  const additionalState = { checked, validation, inactive, viewport }
+
+  const getCardState = (pressableState) => resolvePressableState(pressableState, additionalState)
+  const getTokens = (pressableState) =>
+    validateThemeTokens(
+      resolvePressableTokens(tokens, pressableState, additionalState),
+      getTokensSetPropType(tokenKeys, { requireAll: true }),
+      'PressableCard'
+    )
+
+  const getCardTokens = (pressableState) => selectTokens('Card', getTokens(pressableState))
+  const getOuterBorderStyle = (pressableState) => {
+    const {
+      flex,
+      minWidth,
+      outerBorderColor,
+      outerBorderGap = 0,
+      outerBorderWidth = 0,
+      borderRadius
+    } = getTokens(pressableState)
+    return {
+      flex,
+      minWidth: minWidth + outerBorderGap + outerBorderWidth,
+      ...applyOuterBorder({ outerBorderColor, outerBorderGap, outerBorderWidth, borderRadius }),
+      ...Platform.select({ web: { outline: 'none' } })
+    }
+  }
+
+  const handleChange = linkProps.handleHref({ href, onPress })
+  const handleKeyDown = (e) => {
+    // The expected keyboard shortcut for selecting a focused item is the Space key
+    if (e?.key === ' ') handleChange()
+  }
+
+  return (
+    <Pressable
+      href={href}
+      onPress={handleChange}
+      onKeyDown={handleKeyDown}
+      hrefAttrs={hrefAttrs}
+      style={getOuterBorderStyle}
+      {...a11y}
+    >
+      {(pressableState) => (
+        <CardBase tokens={getCardTokens(pressableState)}>
+          {typeof children === 'function' ? children(getCardState(pressableState)) : children}
+        </CardBase>
+      )}
+    </Pressable>
+  )
+}
+
+PressableCardBase.propTypes = {
+  children: PropTypes.oneOfType([PropTypes.func, PropTypes.node]),
+  tokens: getTokensSetPropType(tokenKeys, { requireAll: true, allowFunction: true }),
+  variant: variantProp.propType,
+  ...a11yProps.types
+}
+
+export default PressableCardBase

package/src/Card/index.js

@@ -1,3 +1,6 @@
 import Card from './Card'
 
 export default Card
+
+export { default as PressableCardBase } from './PressableCardBase'
+export * from './PressableCardBase'

package/src/Checkbox/Checkbox.jsx

@@ -0,0 +1,274 @@
+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 selectIconTokens = ({ icon, iconColor, iconSize }) => ({
+  icon,
+  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 handleKeyDown = (e) => {
+    // The expected keyboard shortcut for activating a checkbox is the Space key
+    if (e?.key === ' ') handleChange()
+  }
+  const accessibilityProps = a11yProps.select(rest)
+  const uniqueId = useUniqueId('checkbox')
+  const inputId = id ?? uniqueId
+
+  return (
+    <View style={staticStyles.wrapper}>
+      <StackView direction={feedbackPosition === 'top' ? 'column-reverse' : 'column'} space={0}>
+        <Pressable
+          disabled={inactive}
+          onKeyDown={handleKeyDown}
+          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}>
+                <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 {...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' }
+})