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

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

@@ -56,13 +56,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,
@@ -145,20 +144,20 @@ const Checkbox = ({
       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
 
-  // @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}
+          onKeyDown={handleKeyDown}
           onPress={handleChange}
           accessibilityRole="checkbox"
           accessibilityState={{ checked: isChecked, disabled: inactive }}
@@ -169,7 +168,7 @@ const Checkbox = ({
             const iconTokens = selectIconTokens(stateTokens)
 
             return (
-              <View style={[staticStyles.container, selectContainerStyles(stateTokens)]}>
+              <View style={staticStyles.container}>
                 <View
                   style={StyleSheet.flatten([
                     staticStyles.defaultInputStyles,
@@ -188,7 +187,7 @@ const Checkbox = ({
                     value={value}
                   />
                   {isChecked && IconComponent && (
-                    <IconComponent tokens={iconTokens} testID="Checkbox-Icon" />
+                    <IconComponent {...iconTokens} testID="Checkbox-Icon" />
                   )}
                 </View>
                 {Boolean(label) && (

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 = (...args) => {
+      if (typeof itemOnChange === 'function') itemOnChange(...args)
+      toggleOneValue(checkboxId)
+    }
+    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}
+      status={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/index.js

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

package/src/ExpandCollapse/Control.jsx

@@ -82,7 +82,7 @@ const ExpandCollapseControl = ({
           <>
             {IconComponent && (
               <View style={selectIconContainerStyles(themeTokens)}>
-                <IconComponent tokens={selectIconTokens(themeTokens)} />
+                <IconComponent {...selectIconTokens(themeTokens)} />
               </View>
             )}
             {typeof children === 'function' ? children(getControlState(pressableState)) : children}

package/src/Feedback/Feedback.jsx

@@ -64,7 +64,7 @@ const Feedback = ({ title, children, id, validation, tokens, variant, ...rest })
           <View style={staticStyles.title}>
             {IconComponent && (
               <View style={selectIconContainerStyles(themeTokens)}>
-                <IconComponent tokens={selectIconTokens(themeTokens)} />
+                <IconComponent {...selectIconTokens(themeTokens)} />
               </View>
             )}
             <Text style={titleTextStyles}>{title}</Text>

package/src/Fieldset/Fieldset.jsx

@@ -0,0 +1,129 @@
+import React from 'react'
+import PropTypes from 'prop-types'
+
+import Feedback from '../Feedback'
+import { spacingProps } from '../utils'
+import FieldsetContainer from './FieldsetContainer'
+import { getStackedContent } from '../StackView'
+import InputLabel from '../InputLabel'
+import useInputSupports from '../InputSupports/useInputSupports'
+import Legend from './Legend'
+
+/**
+ * An alternative to InputSupports for groups of input elements that, on web, are to be
+ * wrapped in a `<fieldset>` tag, with label content displated in a `<legend>` tag.
+ *
+ * Follows the same theming and most of the same props as InputSupports.
+ */
+const Fieldset = ({
+  space,
+  feedback,
+  feedbackPosition = 'top',
+  validation,
+  legend,
+  hint,
+  hintPosition,
+  tooltip,
+  inactive,
+  accessibilityRole,
+  name: fieldsetName,
+  children
+}) => {
+  // Skips `inputId` because a fieldset' legend describes multiple inputs
+  const { hintId, feedbackId, a11yProps } = useInputSupports({
+    feedback,
+    hint,
+    label: legend,
+    validation
+  })
+
+  const legendContent = legend && (
+    <Legend>
+      <InputLabel
+        label={legend}
+        hint={hint}
+        hintPosition={hintPosition}
+        hintId={hintId}
+        tooltip={tooltip}
+      />
+    </Legend>
+  )
+  const feedbackContent = feedback && (
+    <Feedback id={feedbackId} title={feedback} validation={validation} />
+  )
+
+  // Some accessibility patterns depend on elements being direct children, e.g. fieldset -> legend,
+  // and on MacOS voiceover, radiogroup -> radio. To allow elements to be direct children of the
+  // fieldset as much as possible, but also allow different spacing within content and between
+  // fieldset / feedback / etc, wrap resolved children in a fragment, and stack with `preserveFragments`.
+  const childContent = <>{typeof children === 'function' ? children({ a11yProps }) : children}</>
+  const orderedContent =
+    feedbackPosition === 'bottom'
+      ? [legendContent, feedbackContent, childContent]
+      : [legendContent, childContent, feedbackContent]
+  const stackedContent = getStackedContent(orderedContent, { space, preserveFragments: true })
+
+  return (
+    <FieldsetContainer
+      inactive={inactive}
+      accessibilityRole={accessibilityRole}
+      name={fieldsetName}
+    >
+      {stackedContent}
+    </FieldsetContainer>
+  )
+}
+
+Fieldset.propTypes = {
+  children: PropTypes.oneOfType([PropTypes.func, PropTypes.node]),
+  /**
+   * The accessibility role of the `<fieldset>` element itself. Other React Native accessibility
+   * props are not supported because there is not an appropriate counterpart for Fieldsets.
+   */
+  accessibilityRole: PropTypes.string,
+  /**
+   * The amout of space between legend, feedback and content; according  to the theme's spacing scale.
+   * Either a number corresponding to a position on the theme's spacing scale (1 is smallest, 2 is second smallest, etc),
+   * or, a SpacingObject with viewport keys and options (see `useSpacingScale` for details).
+   */
+  space: spacingProps.types.spacingValue,
+  /**
+   * The text for the fieldset's legend, describing the fieldset content.
+   */
+  legend: PropTypes.string,
+  /**
+   * A short description of the expected input.
+   */
+  hint: PropTypes.string,
+  /**
+   * Position of the hint relative to label.
+   */
+  hintPosition: PropTypes.oneOf(['inline', 'below']),
+  /**
+   * A detailed description of validation error/success or additional instructions.
+   * Visual variant is determined based on the `validation` prop.
+   */
+  feedback: PropTypes.string,
+  /**
+   * Position of the feedback block relative to the fieldset's content.
+   */
+  feedbackPosition: PropTypes.oneOf(['above', 'below']),
+  /**
+   * If true, the fieldset is treated as inactive (setting `disabled` attribute on web).
+   */
+  inactive: PropTypes.bool,
+  /**
+   * Content of an optional `Tooltip`. If set, a tooltip button will be shown next to the label.
+   */
+  tooltip: PropTypes.string,
+  /**
+   * On web, this is passed to the `<fieldset>`'s `name` attribute.
+   */
+  name: PropTypes.string,
+  /**
+   * Use to visually mark an input as valid or invalid.
+   */
+  validation: PropTypes.oneOf(['error', 'success'])
+}
+
+export default Fieldset

package/src/Fieldset/FieldsetContainer.jsx

@@ -0,0 +1,22 @@
+import React from 'react'
+import PropTypes from 'prop-types'
+
+import cssReset from './cssReset'
+
+/**
+ * On Web, wraps children with a HTML `<fieldset>` and sets its attributes as necessary.
+ */
+const FieldsetContainer = ({ children, inactive, accessibilityRole, name: fieldsetName }) => (
+  <fieldset disabled={inactive} style={cssReset} role={accessibilityRole} name={fieldsetName}>
+    {children}
+  </fieldset>
+)
+
+FieldsetContainer.propTypes = {
+  accessibilityRole: PropTypes.string,
+  children: PropTypes.node,
+  inactive: PropTypes.bool,
+  name: PropTypes.string
+}
+
+export default FieldsetContainer

package/src/Fieldset/FieldsetContainer.native.jsx

@@ -0,0 +1,16 @@
+import React from 'react'
+import PropTypes from 'prop-types'
+import { View } from 'react-native'
+
+// No equivalent of `<fieldset>` on native, so just apply accessibility role to container.
+// If a11y testing finds any additional handling is needed at the container level, add it here.
+const FieldsetContainer = ({ children, accessibilityRole }) => (
+  <View accessibilityRole={accessibilityRole}>{children}</View>
+)
+
+FieldsetContainer.propTypes = {
+  children: PropTypes.node,
+  accessibilityRole: PropTypes.string
+}
+
+export default FieldsetContainer

package/src/Fieldset/Legend.jsx

@@ -0,0 +1,16 @@
+import React from 'react'
+import PropTypes from 'prop-types'
+
+import cssReset from './cssReset'
+
+/**
+ * On Web, wraps children in HTML `<legend>` tag.
+ * On Native, `<legend>` does not exist, wraps in a width 100% block to follow <legend>'s behaviour in a flex.
+ */
+const Legend = ({ children }) => <legend style={cssReset}>{children}</legend>
+
+Legend.propTypes = {
+  children: PropTypes.node
+}
+
+export default Legend

package/src/Fieldset/Legend.native.jsx

@@ -0,0 +1,22 @@
+import React from 'react'
+import { View, StyleSheet } from 'react-native'
+import PropTypes from 'prop-types'
+
+/**
+ * On Web, wraps children in HTML `<legend>` tag.
+ * On Native, `<legend>` does not exist, wraps in a width 100% block to follow <legend>'s behaviour in a flex.
+ */
+const Legend = ({ children }) => <View style={staticStyles.stretch}>{children}</View>
+
+Legend.propTypes = {
+  children: PropTypes.node
+}
+
+const staticStyles = StyleSheet.create({
+  stretch: {
+    width: '100%',
+    flexGrow: 1
+  }
+})
+
+export default Legend

package/src/Fieldset/cssReset.js

@@ -0,0 +1,14 @@
+// React Native Web has no built-in `fieldset` or `legend` support.
+// This reset makes them consistent with other RNW views.
+// Can't use RN stylesheets because it's not an RN element (RNW's createElement tooling is unstable).
+// Using CSS `all` doesn't work well as an inline style.
+// https://github.com/necolas/react-native-web/issues/1385
+export default {
+  margin: 'unset',
+  padding: 'unset',
+  float: 'unset',
+  border: 'unset',
+  width: 'unset',
+  display: 'flex',
+  flexDirection: 'column'
+}

package/src/Fieldset/index.js

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