@telus-uds/components-base 0.0.2-prerelease.1 → 0.0.2-prerelease.10

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 = (event) => {
+    // The expected keyboard shortcut for selecting a focused item is the Space key
+    if (event?.key === ' ') handleChange(event)
+  }
+
+  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

@@ -0,0 +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 = (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}>
+      <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' }
+})

package/src/Checkbox/CheckboxGroup.jsx

@@ -0,0 +1,196 @@
+import React from 'react'
+import PropTypes from '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 = ({
+  tokens,
+  radioTokens,
+  variant,
+  items = [],
+  legend,
+  tooltip,
+  hint,
+  validation,
+  feedback,
+  initialCheckedIds,
+  checkedIds,
+  onChange,
+  readOnly,
+  name: inputGroupName,
+  inactive
+}) => {
+  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 }, index) => {
+    const checkboxId = id || `Checkbox[${index}]`
+    const handleChange = (newCheckedState, event) => {
+      if (typeof itemOnChange === 'function') itemOnChange(newCheckedState, event)
+      toggleOneValue(checkboxId, event)
+    }
+    return (
+      <Checkbox
+        key={checkboxId}
+        id={checkboxId}
+        checked={currentValues.includes(checkboxId)}
+        onChange={handleChange}
+        inactive={inactive}
+        label={label}
+        name={inputGroupName}
+        tokens={radioTokens}
+        variant={variant}
+      />
+    )
+  })
+
+  return (
+    <Fieldset
+      name={inputGroupName}
+      legend={legend}
+      tooltip={tooltip}
+      hint={hint}
+      space={fieldSpace}
+      feedback={feedback}
+      inactive={inactive}
+      validation={validation}
+    >
+      {getStackedContent(checkboxes, { space, direction: 'column' })}
+    </Fieldset>
+  )
+}
+
+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
+    })
+  ),
+  /**
+   * 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/CheckboxInput.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/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/index.js

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