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

package/src/Card/PressableCardBase.jsx

@@ -0,0 +1,119 @@
+import React, { forwardRef } 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 = forwardRef(
+  (
+    {
+      children,
+      tokens,
+      checked,
+      validation,
+      inactive,
+      href,
+      hrefAttrs,
+      onPress,
+      accessibilityRole = href ? 'link' : undefined,
+      ...rest
+    },
+    ref
+  ) => {
+    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 = (event) => {
+      // The expected keyboard shortcut for selecting a focused item is the Space key
+      if (event?.key === ' ') handleChange(event)
+    }
+
+    return (
+      <Pressable
+        ref={ref}
+        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.displayName = 'PressableCardBase'
+
+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

@@ -1,6 +1,6 @@
-import React from 'react'
+import React, { forwardRef } from 'react'
 import PropTypes from 'prop-types'
-import { Pressable, StyleSheet, Text, View } from 'react-native'
+import { Platform, Pressable, StyleSheet, Text, View } from 'react-native'
 
 import CheckboxInput from './CheckboxInput'
 // @todo move `LabelContent` outside of the `InputLabel` and fix
@@ -32,12 +32,16 @@ const selectInputStyles = (
   borderWidth: inputBorderWidth,
   borderRadius: inputBorderRadius,
   backgroundColor: isChecked ? iconBackgroundColor : inputBackgroundColor,
-  outlineStyle: 'solid',
-  outlineColor: inputOutlineColor,
-  outlineWidth: inputOutlineWidth,
   height: inputHeight,
   width: inputWidth,
-  ...applyShadowToken(inputShadow)
+  ...applyShadowToken(inputShadow),
+  ...Platform.select({
+    web: {
+      outlineStyle: 'solid',
+      outlineColor: inputOutlineColor,
+      outlineWidth: inputOutlineWidth
+    }
+  })
 })
 const selectLabelStyles = ({
   labelColor,
@@ -56,13 +60,12 @@ const selectLabelStyles = ({
     lineHeight: labelLineHeight
   })
 })
-const selectContainerStyles = ({ containerMarginBottom }) => ({
-  marginBottom: containerMarginBottom
-})
-const selectIconTokens = ({ iconColor, iconSize }) => ({
+const selectIconTokens = ({ icon, iconColor, iconSize }) => ({
+  icon,
   color: iconColor,
   size: iconSize
 })
+
 const selectFeedbackTokens = ({ feedbackMarginBottom, feedbackMarginTop, feedbackPosition }) => ({
   feedbackPosition,
   feedbackMarginBottom,
@@ -104,115 +107,121 @@ const selectFeedbackTokens = ({ feedbackMarginBottom, feedbackMarginTop, feedbac
  * 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(
+const Checkbox = forwardRef(
+  (
     {
-      value: checked,
-      initialValue: defaultChecked,
-      onChange
+      checked,
+      defaultChecked,
+      error = false,
+      feedback,
+      id,
+      inactive,
+      label,
+      name,
+      onChange,
+      tokens,
+      value,
+      variant,
+      ...rest
     },
-    '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)
+    ref
+  ) => {
+    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 = (event) => {
+      if (!inactive) {
+        setIsChecked(!isChecked, event)
+      }
     }
-  }
-  const accessibilityProps = a11yProps.select(rest)
-  const uniqueId = useUniqueId('checkbox')
-  const inputId = id ?? uniqueId
+    const handleKeyDown = (event) => {
+      // The expected keyboard shortcut for activating a checkbox is the Space key
+      if (event?.key === ' ') handleChange(event)
+    }
+    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.wrapper} ref={ref}>
+        <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, 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" />
+              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>
-                {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>
-  )
-}
+              )
+            }}
+          </Pressable>
+          {Boolean(feedback) && (
+            <View style={styles.feedbackContainer}>
+              <Feedback
+                title={feedback}
+                variant={{ icon: error === true }}
+                validation={error === true ? 'error' : undefined}
+              />
+            </View>
+          )}
+        </StackView>
+      </View>
+    )
+  }
+)
+Checkbox.displayName = 'Checkbox'
 
 Checkbox.propTypes = {
   ...a11yProps.propTypes,

package/src/Checkbox/CheckboxGroup.jsx

@@ -0,0 +1,206 @@
+import React, { forwardRef } from 'react'
+import PropTypes from 'prop-types'
+import ABBPropTypes from 'airbnb-prop-types'
+
+import { useViewport } from '../ViewportProvider'
+import { useThemeTokens } from '../ThemeProvider'
+import { getTokensPropType, useMultipleInputValues, variantProp } from '../utils'
+import { getStackedContent } from '../StackView'
+import Checkbox from './Checkbox'
+import Fieldset from '../Fieldset'
+
+/**
+ * A group of Checkboxs that behave as a fieldset. Use when users select any number of choices from options.
+ *
+ * ## Component API
+ *
+ * Use the `items` prop to pass an array of objects describing each Checkbox in the group:
+ *
+ *  - `label`: main text passed to CheckboxGroup's `label` prop
+ *  - `id`: identifier used to store which CheckboxGroup is selected (uses `label` if undefinded)
+ *  - `onChange`: optional function called on selection, in addition to updating the group's selection state
+ *
+ * ### Controlled version
+ *
+ * If the selection state is controlled from outside, it needs to receive `checkedId` and `onChange` props.
+ *
+ * ### Uncontrolled version
+ *
+ * If the CheckboxGroup manages its own state, you can use `initialCheckedId` prop to provide the initial value.
+ * Whenever the radio card gets toggled, it calls the `onChange` callback with the new value (string).
+ *
+ * ### Use in forms
+ *
+ * For web forms, the `name` prop may be used to define the name of the group's `fieldset` and input elements.
+ *
+ * ### Validation
+ *
+ * Validation state may be set by passing 'error' or 'success' to the `validation` prop.
+ *
+ * ## A11y guidelines
+ *
+ * CheckboxGroup accepts all the common accessibility props, and controls the accessibility state
+ * of children like Checkbox and Feedback based on current state.
+ *
+ * @example
+ * ```jsx
+ * <CheckboxGroup
+ *   initialCheckedId="check1"
+ *   items={[
+ *     { label: 'Checkbox 1', id: 'check1' },
+ *     { label: 'Checkbox 2', id: 'check2' },
+ *     { label: 'Checkbox 3', id: 'check3' }
+ *   ]}
+ *   legend="Checkboxes"
+ *   hint="Choose from these options"
+ * />
+ * ```
+ */
+const CheckboxGroup = forwardRef(
+  (
+    {
+      tokens,
+      radioTokens,
+      variant,
+      items = [],
+      legend,
+      tooltip,
+      hint,
+      validation,
+      feedback,
+      initialCheckedIds,
+      checkedIds,
+      onChange,
+      readOnly,
+      name: inputGroupName,
+      inactive
+    },
+    ref
+  ) => {
+    const viewport = useViewport()
+
+    const { space, fieldSpace } = useThemeTokens('CheckboxGroup', tokens, variant, {
+      viewport
+    })
+
+    const { currentValues, toggleOneValue } = useMultipleInputValues({
+      values: checkedIds,
+      initialValues: initialCheckedIds,
+      onChange,
+      readOnly: readOnly || inactive
+    })
+    const checkboxes = items.map(({ label, id, onChange: itemOnChange, ref: itemRef }, index) => {
+      const checkboxId = id || `Checkbox[${index}]`
+      const handleChange = (newCheckedState, event) => {
+        if (typeof itemOnChange === 'function') itemOnChange(newCheckedState, event)
+        toggleOneValue(checkboxId, event)
+      }
+      return (
+        <Checkbox
+          ref={itemRef}
+          key={checkboxId}
+          id={checkboxId}
+          checked={currentValues.includes(checkboxId)}
+          onChange={handleChange}
+          inactive={inactive}
+          label={label}
+          name={inputGroupName}
+          tokens={radioTokens}
+          variant={variant}
+        />
+      )
+    })
+
+    return (
+      <Fieldset
+        ref={ref}
+        name={inputGroupName}
+        legend={legend}
+        tooltip={tooltip}
+        hint={hint}
+        space={fieldSpace}
+        feedback={feedback}
+        inactive={inactive}
+        validation={validation}
+      >
+        {getStackedContent(checkboxes, { space, direction: 'column' })}
+      </Fieldset>
+    )
+  }
+)
+CheckboxGroup.displayName = 'CheckboxGroup'
+
+CheckboxGroup.propTypes = {
+  /**
+   * Optional theme token overrides for the outer CheckboxGroup component
+   */
+  tokens: getTokensPropType('CheckboxGroup'),
+  /**
+   * Optional theme token overrides for each inner Checkbox component
+   */
+  radioTokens: getTokensPropType('Checkbox'),
+  /**
+   * Theme variants, shared between both CheckboxGroup and Checkbox
+   */
+  variant: variantProp.propType,
+  /**
+   * Array of objects containing specifics for each Checkbox to be rendered in the group.
+   */
+  items: PropTypes.arrayOf(
+    PropTypes.exact({
+      label: PropTypes.string,
+      id: PropTypes.string,
+      onChange: PropTypes.func,
+      ref: ABBPropTypes.ref()
+    })
+  ),
+  /**
+   * Main text used to describe this group, used in Fieldset's Legend element.
+   */
+  legend: PropTypes.string,
+  /**
+   * Optional additional text giving more detail to help a user make a choice.
+   */
+  hint: PropTypes.string,
+  /**
+   * Optional tooltip text content to include alongside the legend and hint.
+   */
+  tooltip: PropTypes.string,
+  /**
+   * Current validation status of the group, passed to the feedback element if there is one.
+   */
+  validation: PropTypes.oneOf(['error', 'success']),
+  /**
+   * If provided, a Feedback element is rendered containing this text.
+   */
+  feedback: PropTypes.string,
+  /**
+   * If provided, the checkboxed with this ids are selected on first render.
+   */
+  initialCheckedIds: PropTypes.arrayOf(PropTypes.string),
+  /**
+   * If not undefined, the checkboxes with these ids is selected, and the
+   * element's selection state will be controlled by its parent using the `onChange` function.
+   */
+  checkedIds: PropTypes.arrayOf(PropTypes.string),
+  /**
+   * Function to call on change in selection state. Is required if the selection state is controlled
+   * by a parent using checkedId and the input is not readOnly.
+   */
+  onChange: PropTypes.func,
+  /**
+   * If true, the radio cards cannot be selected by the user and simply show their current state.
+   */
+  readOnly: PropTypes.bool,
+  /**
+   * If true, the checkbox cannot be interacted with, elements are set as `disabled` and if the
+   * theme supports `inactive` appearances rules, these are applied.
+   */
+  inactive: PropTypes.bool,
+  /**
+   * On Web, this is passed to the `name` attribute of the fieldset and each radio input.
+   */
+  name: PropTypes.string
+}
+
+export default CheckboxGroup

package/src/Checkbox/index.js

@@ -1,3 +1,5 @@
 import Checkbox from './Checkbox'
 
 export default Checkbox
+
+export { default as CheckboxGroup } from './CheckboxGroup'

package/src/Divider/Divider.jsx

@@ -1,4 +1,4 @@
-import React from 'react'
+import React, { forwardRef } from 'react'
 import PropTypes from 'prop-types'
 import { View, StyleSheet, Platform } from 'react-native'
 import { useThemeTokens } from '../ThemeProvider'
@@ -45,7 +45,7 @@ import { getTokensPropType, variantProp, spacingProps } from '../utils'
  *
  * 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, space, tokens, testID }) => {
+const Divider = forwardRef(({ variant, vertical = false, space, tokens, testID }, ref) => {
   const { color, width } = useThemeTokens('Divider', tokens, variant)
 
   const borderStyles = vertical
@@ -68,7 +68,9 @@ const Divider = ({ variant, vertical = false, space, tokens, testID }) => {
       : // There are no such equivalent attributes for native
         {}
 
-  const divider = <View style={[styles.divider, borderStyles]} testID={testID} {...a11y} />
+  const divider = (
+    <View ref={ref} style={[styles.divider, borderStyles]} testID={testID} {...a11y} />
+  )
   if (!space) return divider
   const spacerProps = { space, direction: vertical ? 'row' : 'column' }
   return (
@@ -78,7 +80,8 @@ const Divider = ({ variant, vertical = false, space, tokens, testID }) => {
       <Spacer {...spacerProps} testID={testID ? `${testID}-Spacer-after` : undefined} />
     </>
   )
-}
+})
+Divider.displayName = 'Divider'
 
 Divider.propTypes = {
   tokens: getTokensPropType('Divider'),

package/src/ExpandCollapse/Accordion.jsx

@@ -1,10 +1,11 @@
-import React from 'react'
+import React, { forwardRef } from 'react'
 import ExpandCollapse from './ExpandCollapse'
 
 /**
  * 'Accordion' is a shorthand for an ExpandCollapse where only one item may be open at a time
  */
-const Accordion = (props) => <ExpandCollapse {...props} maxOpen={1} />
+const Accordion = forwardRef((props, ref) => <ExpandCollapse ref={ref} {...props} maxOpen={1} />)
+Accordion.displayName = 'Accordion'
 Accordion.propTypes = ExpandCollapse.propTypes
 
 export default Accordion