@telus-uds/components-base 0.0.2-prerelease.6 → 1.0.0

package/src/Card/CardBase.jsx

@@ -0,0 +1,58 @@
+import React, { forwardRef } 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 = forwardRef(({ children, tokens, dataSet, ...rest }, ref) => {
+  const cardStyle = selectStyles(typeof tokens === 'function' ? tokens() : tokens)
+  const props = { ...a11yProps.select(rest), ...viewProps.select(rest) }
+
+  return (
+    <View style={cardStyle} dataSet={dataSet} ref={ref} {...props}>
+      {children}
+    </View>
+  )
+})
+CardBase.displayName = 'CardBase'
+
+CardBase.propTypes = {
+  children: PropTypes.node,
+  tokens: getTokensPropType('Card'),
+  ...a11yProps.types
+}
+
+export default CardBase

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

@@ -0,0 +1,284 @@
+import React, { forwardRef } from 'react'
+import PropTypes from 'prop-types'
+import { Platform, 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,
+  height: inputHeight,
+  width: inputWidth,
+  ...applyShadowToken(inputShadow),
+  ...Platform.select({
+    web: {
+      outlineStyle: 'solid',
+      outlineColor: inputOutlineColor,
+      outlineWidth: inputOutlineWidth
+    }
+  })
+})
+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 = forwardRef(
+  (
+    {
+      checked,
+      defaultChecked,
+      error = false,
+      feedback,
+      id,
+      inactive,
+      label,
+      name,
+      onChange,
+      tokens,
+      value,
+      variant,
+      ...rest
+    },
+    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 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
+
+    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}>
+                  <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.displayName = 'Checkbox'
+
+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/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