@telus-uds/components-base 2.0.0 → 2.0.2

package/src/Checkbox/CheckboxButton.jsx

@@ -0,0 +1,178 @@
+import React from 'react'
+import PropTypes from 'prop-types'
+import { Platform, StyleSheet, View } from 'react-native'
+
+import CheckboxInput from './CheckboxInput'
+import { applyShadowToken, useThemeTokens } from '../ThemeProvider'
+import {
+  a11yProps,
+  getTokensSetPropType,
+  selectSystemProps,
+  selectTokens,
+  viewProps
+} from '../utils'
+
+const [selectProps, selectedSystemPropTypes] = selectSystemProps([a11yProps, viewProps])
+
+const selectInputStyles = (
+  {
+    iconBackgroundColor,
+    inputBorderColor,
+    inputBorderRadius,
+    inputBorderWidth,
+    inputBackgroundColor,
+    inputHeight,
+    inputOutlineColor,
+    inputOutlineWidth,
+    inputOutlineOffset,
+    inputShadow,
+    inputWidth
+  },
+  isChecked
+) => ({
+  borderColor: inputBorderColor,
+  borderWidth: inputBorderWidth,
+  borderRadius: inputBorderRadius,
+  backgroundColor: isChecked ? iconBackgroundColor : inputBackgroundColor,
+  height: inputHeight,
+  width: inputWidth,
+  ...applyShadowToken(inputShadow),
+  ...Platform.select({
+    web: {
+      outlineStyle: 'solid',
+      outlineColor: inputOutlineColor,
+      outlineWidth: inputOutlineWidth,
+      outlineOffset: inputOutlineOffset
+    }
+  })
+})
+
+const selectIconTokens = ({ icon, iconColor, iconSize }) => ({
+  icon,
+  color: iconColor,
+  size: iconSize
+})
+
+const tokenKeys = [
+  'checkedBackgroundColor',
+  'checkedSize',
+  'inputBackgroundColor',
+  'inputBorderColor',
+  'inputBorderWidth',
+  'inputOutlineColor',
+  'inputOutlineWidth',
+  'inputSize',
+  'outerBorderColor',
+  'outerBorderWidth',
+  'outerBorderGap',
+  'inputSize'
+]
+
+export const selectCheckboxTokens = (themeTokens, prefix) =>
+  selectTokens(tokenKeys, themeTokens, prefix)
+
+/**
+ * The visual toggle of a checkbox input. Is not interactive on its own, should be used inside
+ * an interactive parent that passes down props when interacted with. Used in CheckboxCard
+ */
+const CheckboxButton = React.forwardRef(
+  (
+    {
+      isChecked,
+      tokens,
+      inactive,
+      defaultChecked,
+      inputId,
+      iconId,
+      isControlled,
+      handleChange,
+      name: inputName,
+      value,
+      ...rest
+    },
+    ref
+  ) => {
+    const { icon: IconComponent, ...stateTokens } = useThemeTokens('Checkbox', tokens, {
+      checked: isChecked
+    })
+    const iconTokens = selectIconTokens(stateTokens)
+
+    return (
+      <View {...selectProps(rest)}>
+        <View
+          style={[staticStyles.defaultInputStyles, selectInputStyles(stateTokens, isChecked)]}
+          testID={inputId}
+        >
+          <CheckboxInput
+            ref={ref}
+            checked={isChecked}
+            defaultChecked={defaultChecked}
+            disabled={inactive}
+            id={inputId}
+            isControlled={isControlled}
+            onChange={handleChange}
+            name={inputName}
+            value={value}
+          />
+          {isChecked && IconComponent && (
+            <View testID={iconId}>
+              <IconComponent {...iconTokens} />
+            </View>
+          )}
+        </View>
+      </View>
+    )
+  }
+)
+CheckboxButton.displayName = 'CheckboxButton'
+
+CheckboxButton.propTypes = {
+  ...selectedSystemPropTypes,
+  /**
+   * Use `checked` for controlled Checkbox. For uncontrolled Checkbox, use the `defaultChecked` prop.
+   */
+  isChecked: PropTypes.bool,
+  /**
+   * Checkbox tokens.
+   */
+  tokens: getTokensSetPropType(tokenKeys, { allowFunction: true }),
+  /**
+   * Whether the corresponding input is disabled or active.
+   */
+  inactive: PropTypes.bool,
+  /**
+   * Use `defaultChecked` to provide the initial value for an uncontrolled Checkbox.
+   */
+  defaultChecked: PropTypes.bool,
+  /**
+   * Checkbox input ID.
+   */
+  inputId: PropTypes.string,
+  /**
+   * Checkbox icon ID.
+   */
+  iconId: PropTypes.string,
+  /**
+   * Can control the checkbox on the card.
+   */
+  isControlled: PropTypes.bool,
+  /**
+   * Callback called when a controlled checkbox gets interacted with.
+   */
+  handleChange: PropTypes.func,
+  /**
+   * Associate this checkbox with a group (set as the name attribute).
+   */
+  name: PropTypes.string,
+  /**
+   * The value of the checkbox: true or false
+   */
+  value: PropTypes.bool
+}
+
+export default CheckboxButton
+
+const staticStyles = StyleSheet.create({
+  container: { flexDirection: 'row', alignItems: 'center' },
+  defaultInputStyles: { alignItems: 'center', justifyContent: 'center' }
+})

package/src/Checkbox/CheckboxGroup.jsx

@@ -1,4 +1,4 @@
-import React, { forwardRef } from 'react'
+import React from 'react'
 import PropTypes from 'prop-types'
 import ABBPropTypes from 'airbnb-prop-types'
 
@@ -72,7 +72,7 @@ const [selectItemProps, selectedItemPropTypes] = selectSystemProps([
  * />
  * ```
  */
-const CheckboxGroup = forwardRef(
+const CheckboxGroup = React.forwardRef(
   (
     {
       tokens,
@@ -98,10 +98,29 @@ const CheckboxGroup = forwardRef(
   ) => {
     const viewport = useViewport()
 
-    const { space, fieldSpace } = useThemeTokens('CheckboxGroup', tokens, variant, {
+    const {
+      space,
+      fieldSpace,
+      showIcon,
+      outlineWidth,
+      borderTopLeftRadius,
+      borderTopRightRadius,
+      borderBottomLeftRadius,
+      borderBottomRightRadius,
+      outlineOffset
+    } = useThemeTokens('CheckboxGroup', tokens, variant, {
       viewport
     })
 
+    const borderTokens = {
+      outlineWidth,
+      borderTopLeftRadius,
+      borderTopRightRadius,
+      borderBottomLeftRadius,
+      borderBottomRightRadius,
+      outlineOffset
+    }
+
     const { currentValues, toggleOneValue } = useMultipleInputValues({
       values: checkedIds,
       initialValues: initialCheckedIds,
@@ -152,8 +171,9 @@ const CheckboxGroup = forwardRef(
         feedback={feedback}
         inactive={inactive}
         validation={validation}
-        showIcon
         showErrorBorder
+        tokens={borderTokens}
+        showIcon={showIcon}
         {...selectProps(rest)}
       >
         {getStackedContent(checkboxes, { space, direction: 'column' })}

package/src/Checkbox/CheckboxInput.jsx

@@ -1,11 +1,23 @@
-import React, { forwardRef } from 'react'
+import React 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 CheckboxInput = React.forwardRef(
+  (
+    {
+      checked,
+      defaultChecked,
+      disabled = false,
+      id,
+      isControlled,
+      name,
+      onChange = () => {},
+      value
+    },
+    ref
+  ) => {
     const handleClick = (event) => {
       // Cancel the click dispatched via the label tag, since it's already wrapped
       // in <Pressable>
@@ -43,13 +55,4 @@ CheckboxInput.propTypes = {
   value: PropTypes.string
 }
 
-CheckboxInput.defaultProps = {
-  checked: undefined,
-  defaultChecked: undefined,
-  disabled: false,
-  name: undefined,
-  onChange: () => {},
-  value: undefined
-}
-
 export default CheckboxInput

package/src/CheckboxCard/CheckboxCard.jsx

@@ -0,0 +1,190 @@
+import React from 'react'
+import PropTypes from 'prop-types'
+import { StyleSheet, Text, View } from 'react-native'
+
+import { applyTextStyles, useTheme, useThemeTokensCallback } from '../ThemeProvider'
+import {
+  a11yProps,
+  focusHandlerProps,
+  getTokensPropType,
+  selectSystemProps,
+  selectTokens,
+  useInputValue,
+  useUniqueId,
+  variantProp,
+  viewProps
+} from '../utils'
+import { PressableCardBase, selectPressableCardTokens } from '../Card'
+import StackView from '../StackView'
+import CheckboxButton, { selectCheckboxTokens } from '../Checkbox/CheckboxButton'
+
+const [selectProps, selectedSystemPropTypes] = selectSystemProps([
+  a11yProps,
+  focusHandlerProps,
+  viewProps
+])
+
+const CheckboxCard = React.forwardRef(
+  (
+    {
+      tokens,
+      variant,
+      title,
+      children,
+      inactive,
+      defaultChecked,
+      checked,
+      name: inputName,
+      value,
+      id,
+      iconId,
+      onChange,
+      ...rest
+    },
+    ref
+  ) => {
+    const {
+      currentValue: isChecked,
+      setValue: setIsChecked,
+      isControlled
+    } = useInputValue({
+      value: checked,
+      initialValue: defaultChecked,
+      onChange
+    })
+
+    const handleChange = (event) => {
+      if (!inactive) {
+        setIsChecked(!isChecked, event)
+      }
+    }
+    const uniqueId = useUniqueId('CheckboxCard')
+    const inputId = id ?? uniqueId
+
+    const uniqueIconId = useUniqueId('CheckboxIcon')
+    const iconCheckboxId = iconId ?? uniqueIconId
+
+    const getTokens = useThemeTokensCallback('CheckboxCard', tokens, variant)
+    const getCardTokens = (cardState) => selectPressableCardTokens(getTokens(cardState))
+    const { themeOptions } = useTheme()
+
+    const selectedProps = selectProps({
+      accessibilityRole: 'checkbox',
+      accessibilityState: { checked: isChecked, disabled: inactive },
+      ...rest
+    })
+
+    return (
+      <PressableCardBase
+        ref={ref}
+        inactive={inactive}
+        checked={isChecked}
+        tokens={getCardTokens}
+        onPress={handleChange}
+        {...selectedProps}
+      >
+        {(cardState) => {
+          const { checkboxSpace, contentSpace, ...themeTokens } = getTokens(cardState)
+          const checkboxTokens = selectCheckboxTokens(themeTokens, 'checkbox')
+          const titleTokens = selectTokens('Typography', themeTokens)
+          const textStyle = applyTextStyles({ ...titleTokens, themeOptions })
+          return (
+            <StackView direction="row" space={checkboxSpace}>
+              <View style={[staticStyles.alignWithText, { height: textStyle.lineHeight }]}>
+                <CheckboxButton
+                  tokens={checkboxTokens}
+                  isControlled={isControlled}
+                  isChecked={isChecked}
+                  inactive={inactive}
+                  defaultChecked={defaultChecked}
+                  inputId={inputId}
+                  iconId={iconCheckboxId}
+                  handleChange={handleChange}
+                  name={inputName}
+                  value={value}
+                />
+              </View>
+              <StackView direction="column" space={contentSpace} tokens={{ flexShrink: 1 }}>
+                {title ? <Text style={textStyle}>{title}</Text> : null}
+                {typeof children === 'function' ? children(cardState, textStyle) : children}
+              </StackView>
+            </StackView>
+          )
+        }}
+      </PressableCardBase>
+    )
+  }
+)
+CheckboxCard.displayName = 'CheckboxCard'
+
+CheckboxCard.propTypes = {
+  ...selectedSystemPropTypes,
+  /**
+   * Content to be displayed at the top of the card alongside the checkbox
+   */
+  title: PropTypes.string,
+  /**
+   * Additional content to be displayed below the checkbox.
+   */
+  children: PropTypes.oneOfType([PropTypes.node, PropTypes.func]),
+  /**
+   * 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,
+  /**
+   * An optional checkboxdescription.
+   */
+  description: PropTypes.string,
+  /**
+   * Checkbox card ID.
+   */
+  id: PropTypes.string,
+  /**
+   * Checkbox icon ID.
+   */
+  iconId: PropTypes.string,
+  /**
+   * Whether the corresponding input is disabled or active.
+   */
+  inactive: PropTypes.bool,
+  /**
+   * The label.
+   */
+  label: PropTypes.string,
+  /**
+   * Associate this checkbox card 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 card gets interacted with.
+   */
+  onChange: PropTypes.func,
+  /**
+   * checkbox card tokens.
+   */
+  tokens: getTokensPropType('CheckboxCard'),
+  /**
+   * checkbox variant.
+   */
+  variant: variantProp.propType
+}
+
+export default CheckboxCard
+
+const staticStyles = StyleSheet.create({
+  alignWithText: {
+    justifyContent: 'center'
+  }
+})

package/src/CheckboxCard/index.js

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

package/src/CheckboxCardGroup/CheckboxCardGroup.jsx

@@ -0,0 +1,231 @@
+import React from 'react'
+import PropTypes from 'prop-types'
+
+import { useViewport } from '../ViewportProvider'
+import { useThemeTokens } from '../ThemeProvider'
+import {
+  a11yProps,
+  containUniqueFields,
+  focusHandlerProps,
+  getTokensPropType,
+  selectSystemProps,
+  useMultipleInputValues,
+  variantProp,
+  viewProps
+} from '../utils'
+import StackView, { StackWrap } from '../StackView'
+import CheckboxCard from '../CheckboxCard'
+import Fieldset from '../Fieldset'
+
+const [selectProps, selectedSystemPropTypes] = selectSystemProps([a11yProps, viewProps])
+const [selectItemProps, selectedItemPropTypes] = selectSystemProps([
+  a11yProps,
+  focusHandlerProps,
+  viewProps
+])
+
+const CheckboxCardGroup = React.forwardRef(
+  (
+    {
+      copy = 'en',
+      tokens,
+      checkboxCardTokens,
+      variant,
+      items = [],
+      legend,
+      tooltip,
+      hint,
+      hintPosition = 'inline',
+      validation,
+      feedback,
+      initialCheckedIds,
+      checkedIds,
+      onChange,
+      readOnly,
+      name: inputGroupName,
+      inactive,
+      ...rest
+    },
+    ref
+  ) => {
+    const viewport = useViewport()
+    const {
+      space,
+      fieldSpace,
+      direction,
+      showIcon,
+      outlineWidth,
+      borderTopLeftRadius,
+      borderTopRightRadius,
+      borderBottomLeftRadius,
+      borderBottomRightRadius,
+      outlineOffset
+    } = useThemeTokens('CheckboxCardGroup', tokens, variant, {
+      viewport
+    })
+
+    const borderTokens = {
+      outlineWidth,
+      borderTopLeftRadius,
+      borderTopRightRadius,
+      borderBottomLeftRadius,
+      borderBottomRightRadius,
+      outlineOffset
+    }
+
+    const { currentValues, toggleOneValue } = useMultipleInputValues({
+      value: checkedIds,
+      initialValues: initialCheckedIds,
+      onChange,
+      readOnly: readOnly || inactive
+    })
+
+    const StackContainer = direction === 'row' ? StackWrap : StackView
+    // Needs 'checkboxgroup' role on direct parent of checkboxes for MacOS Voiceover's numbering to work,
+    // and also needs 'checkboxgroup' role on fieldset for correct description on focusing the set.
+    // TODO: test this on more web screen readers.
+
+    const uniqueFields = ['id']
+    if (!containUniqueFields(items, uniqueFields)) {
+      throw new Error(`CheckboxCardGroup items must have unique ${uniqueFields.join(', ')}`)
+    }
+
+    return (
+      <Fieldset
+        copy={copy}
+        ref={ref}
+        name={inputGroupName}
+        legend={legend}
+        tooltip={tooltip}
+        hint={hint}
+        hintPosition={hintPosition}
+        space={fieldSpace}
+        feedback={feedback}
+        inactive={inactive || readOnly}
+        validation={validation}
+        tokens={borderTokens}
+        showErrorBorder
+        showIcon={showIcon}
+        accessibilityRole="checkbox"
+        {...selectProps(rest)}
+      >
+        {(checkboxCardProperties) => (
+          <StackContainer space={space} accessibilityRole="checkbox">
+            {items.map(({ title, content, id, onChange: itemOnChange, ...itemRest }, index) => {
+              const cardId = id || `CheckboxCard[${index}]`
+              const handleChange = (newCheckedState, event) => {
+                if (typeof itemOnChange === 'function') itemOnChange(newCheckedState, event)
+                toggleOneValue(cardId, event)
+              }
+
+              return (
+                <CheckboxCard
+                  key={cardId}
+                  id={cardId}
+                  checked={currentValues.includes(cardId)}
+                  onChange={handleChange}
+                  inactive={inactive}
+                  title={title}
+                  name={inputGroupName}
+                  tokens={checkboxCardTokens}
+                  variant={variant}
+                  readOnly={readOnly}
+                  {...selectItemProps(itemRest)}
+                  {...checkboxCardProperties}
+                >
+                  {content}
+                </CheckboxCard>
+              )
+            })}
+          </StackContainer>
+        )}
+      </Fieldset>
+    )
+  }
+)
+CheckboxCardGroup.displayName = 'CheckboxCardGroup'
+
+CheckboxCardGroup.propTypes = {
+  ...selectedSystemPropTypes,
+  /**
+   * Whether the English or French copy will be used (e.g. for accessibility labels).
+   */
+  copy: PropTypes.oneOf(['en', 'fr']),
+  /**
+   * Optional theme token overrides for the outer CheckboxCardGroup component
+   */
+  tokens: getTokensPropType('CheckboxCardGroup'),
+  /**
+   * Optional theme token overrides for each inner CheckboxCard component
+   */
+  checkboxCardTokens: getTokensPropType('CheckboxCard'),
+  /**
+   * Theme variants, shared between both CheckboxCardGroup and CheckboxCard
+   */
+  variant: variantProp.propType,
+  /**
+   * Array of objects containing specifics for each CheckboxCard to be rendered in the group.
+   */
+  items: PropTypes.arrayOf(
+    PropTypes.exact({
+      ...selectedItemPropTypes,
+      title: PropTypes.string,
+      content: PropTypes.node,
+      id: PropTypes.string,
+      onChange: PropTypes.func
+    })
+  ),
+  /**
+   * 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,
+  /**
+   * Position of the hint relative to label. Use `below` to display a larger hint below the label.
+   */
+  hintPosition: PropTypes.oneOf(['inline', 'below']),
+  /**
+   * 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 checkbox cards cannot be selected by the user and simply show their current state.
+   */
+  readOnly: PropTypes.bool,
+  /**
+   * If true, the checkbox card 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 checkbox input.
+   */
+  name: PropTypes.string
+}
+
+export default CheckboxCardGroup

package/src/CheckboxCardGroup/index.js

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