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

package/src/Radio/RadioGroup.jsx

@@ -0,0 +1,209 @@
+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, useInputValue, variantProp } from '../utils'
+import { getStackedContent } from '../StackView'
+import Radio from './Radio'
+import Fieldset from '../Fieldset'
+
+/**
+ * A group of Radios that behave as a radio group. Use when users select a single choice from mutually
+ * exclusive options.
+ *
+ * ## Component API
+ *
+ * Use the `items` prop to pass an array of objects describing each Radio in the group:
+ *
+ *  - `label`: main text passed to Radio's `label` prop
+ *  - `id`: identifier used to store which Radio 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 RadioGroup 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
+ *
+ * RadioGroup accepts all the common accessibility props, but also sets accessibility role `'radiogroup'`
+ * and controls the accessibility state of children like Radio and Feedback based on current state.
+ *
+ * @example
+ * ```jsx
+ * <RadioGroup
+ *   initialCheckedId="radio1"
+ *   items={[
+ *     { label: 'Radio 1', id: 'radio1' },
+ *     { label: 'Radio 2', id: 'radio2' },
+ *     { label: 'Radio 3', id: 'radio3' }
+ *   ]}
+ *   legend="Radios"
+ *   hint="Choose one option"
+ * />
+ * ```
+ */
+const RadioGroup = forwardRef(
+  (
+    {
+      tokens,
+      radioTokens,
+      variant,
+      items = [],
+      legend,
+      tooltip,
+      hint,
+      validation,
+      feedback,
+      initialCheckedId,
+      checkedId,
+      onChange,
+      readOnly,
+      name: inputGroupName,
+      inactive
+    },
+    ref
+  ) => {
+    const viewport = useViewport()
+
+    const { space, fieldSpace } = useThemeTokens('RadioGroup', tokens, variant, {
+      viewport
+    })
+
+    const { currentValue, setValue } = useInputValue({
+      value: checkedId,
+      initialValue: initialCheckedId,
+      onChange,
+      readOnly: readOnly || inactive
+    })
+    const radios = items.map(({ label, id, onChange: itemOnChange, ref: itemRef }, index) => {
+      const radioId = id || `Radio[${index}]`
+      const isChecked = currentValue === radioId
+      const handleChange = (newCheckedState, event) => {
+        if (typeof itemOnChange === 'function') itemOnChange(newCheckedState, event)
+        if (newCheckedState) setValue(radioId, event)
+      }
+      return (
+        <Radio
+          ref={itemRef}
+          key={radioId}
+          id={radioId}
+          checked={isChecked}
+          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}
+        accessibilityRole="radiogroup"
+      >
+        {getStackedContent(radios, { space, direction: 'column' })}
+      </Fieldset>
+    )
+  }
+)
+RadioGroup.displayName = 'RadioGroup'
+
+RadioGroup.propTypes = {
+  /**
+   * Optional theme token overrides for the outer RadioGroup component
+   */
+  tokens: getTokensPropType('RadioGroup'),
+  /**
+   * Optional theme token overrides for each inner Radio component
+   */
+  radioTokens: getTokensPropType('Radio'),
+  /**
+   * Theme variants, shared between both RadioGroup and Radio
+   */
+  variant: variantProp.propType,
+  /**
+   * Array of objects containing specifics for each Radio 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 radio card with this id is selected on first render.
+   */
+  initialCheckedId: PropTypes.string,
+  /**
+   * If not undefined, the radio card with this id is selected (or none is selected if `null`), and the
+   * element's selection state will be controlled by its parent using the `onChange` function.
+   */
+  checkedId: 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 radio 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 radio input.
+   */
+  name: PropTypes.string
+}
+
+export default RadioGroup

package/src/Radio/index.js

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

package/src/RadioCard/RadioCard.jsx

@@ -0,0 +1,198 @@
+import React, { forwardRef } from 'react'
+import PropTypes from 'prop-types'
+import { StyleSheet, Text, View } from 'react-native'
+
+import { useThemeTokensCallback, applyTextStyles } from '../ThemeProvider'
+import {
+  getTokensPropType,
+  variantProp,
+  selectTokens,
+  useInputValue,
+  a11yProps,
+  useUniqueId
+} from '../utils'
+import { PressableCardBase, selectPressableCardTokens } from '../Card'
+import StackView from '../StackView'
+import RadioButton, { selectRadioButtonTokens } from '../Radio/RadioButton'
+
+/**
+ * A Card that behaves like a radio button. Use when users select a single choice from mutually exclusive options
+ * with need to show additional information for each option. The whole card is interactive as one item.
+ *
+ * ## Component API
+ *
+ * Use `title` prop to provide a main description, and `children` for additional content. Avoid including
+ * interactive elements within the RadioCard content.
+ *
+ * For a disabled `RadioCard`, set the `inactive` prop to `true`.
+ *
+ * ### Controlled version
+ *
+ * If the radio card is controlled from outside, it needs to receive `checked` and `onChange` props.
+ *
+ * ### Uncontrolled version
+ *
+ * In case of uncontrolled radio card you can use `defaultChecked` prop to provide the initial value.
+ * Whenever the radio card 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 radio card to be a part of a radio group
+ * on a form.
+ *
+ * ### Validation
+ *
+ * You can mark a radio card as failing validation by setting the `error` prop to `true`.
+ *
+ * ## A11y guidelines
+ *
+ * Radio card accepts all the common accessibility props, but also sets some defaults, including
+ * accessibility role `'radio'` and accessibility state that depends on the other props (`checked`, `inactive`)
+ * or the internal state in case of uncontrolled radio button.
+ */
+const RadioCard = forwardRef(
+  (
+    {
+      tokens,
+      variant,
+      title,
+      children,
+      inactive,
+      defaultChecked,
+      checked,
+      name: inputName,
+      value,
+      id,
+      onChange,
+      ...rest
+    },
+    ref
+  ) => {
+    const { currentValue: isChecked, setValue: setIsChecked, isControlled } = useInputValue({
+      value: checked,
+      initialValue: defaultChecked,
+      onChange
+    })
+    const handleChange = (event) => {
+      if (!inactive && !isChecked) {
+        setIsChecked(true, event)
+      }
+    }
+    const a11y = a11yProps.select(rest)
+    const uniqueId = useUniqueId('RadioCard')
+    const inputId = id ?? uniqueId
+
+    const getTokens = useThemeTokensCallback('RadioCard', tokens, variant)
+    const getCardTokens = (cardState) => selectPressableCardTokens(getTokens(cardState))
+
+    return (
+      <PressableCardBase
+        ref={ref}
+        inactive={inactive}
+        checked={isChecked}
+        tokens={getCardTokens}
+        onPress={handleChange}
+        accessibilityRole="radio"
+        accessibilityState={{ checked: isChecked, disabled: inactive }}
+        {...a11y}
+      >
+        {(cardState) => {
+          const { radioSpace, contentSpace, ...themeTokens } = getTokens(cardState)
+          const radioTokens = selectRadioButtonTokens(themeTokens, 'radio')
+          const titleTokens = selectTokens('Typography', themeTokens)
+          const textStyle = applyTextStyles(titleTokens)
+          return (
+            <StackView direction="row" space={radioSpace}>
+              <View style={[staticStyles.alignWithText, { height: textStyle.lineHeight }]}>
+                <RadioButton
+                  tokens={radioTokens}
+                  isControlled={isControlled}
+                  isChecked={isChecked}
+                  inactive={inactive}
+                  defaultChecked={defaultChecked}
+                  inputId={inputId}
+                  handleChange={handleChange}
+                  name={inputName}
+                  value={value}
+                />
+              </View>
+              <StackView direction="column" space={contentSpace} tokens={{ flexShrink: 1 }}>
+                {title && <Text style={textStyle}>{title}</Text>}
+                {typeof children === 'function' ? children(cardState, textStyle) : children}
+              </StackView>
+            </StackView>
+          )
+        }}
+      </PressableCardBase>
+    )
+  }
+)
+RadioCard.displayName = 'RadioCard'
+
+RadioCard.propTypes = {
+  ...a11yProps.propTypes,
+  /**
+   * Content to be displayed at the top of the card alongside the radio button
+   */
+  title: PropTypes.string,
+  /**
+   * Additional content to be displayed below the button.
+   */
+  children: PropTypes.oneOfType([PropTypes.node, PropTypes.func]),
+  /**
+   * Use `checked` for controlled Radio. For uncontrolled Radio, use the `defaultChecked` prop.
+   */
+  checked: PropTypes.bool,
+  /**
+   * Use `defaultChecked` to provide the initial value for an uncontrolled Radio.
+   */
+  defaultChecked: PropTypes.bool,
+  /**
+   * An optional radio button description.
+   */
+  description: PropTypes.string,
+  /**
+   * Radio card button ID.
+   */
+  id: PropTypes.string,
+  /**
+   * Whether the corresponding input is disabled or active.
+   */
+  inactive: PropTypes.bool,
+  /**
+   * The label.
+   */
+  label: PropTypes.string,
+  /**
+   * Associate this radio 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 radio card gets interacted with.
+   */
+  onChange: PropTypes.func,
+  /**
+   * Radio card tokens.
+   */
+  tokens: getTokensPropType('RadioCard'),
+  /**
+   * Radio variant.
+   */
+  variant: variantProp.propType
+}
+
+const staticStyles = StyleSheet.create({
+  alignWithText: {
+    justifyContent: 'center'
+  }
+})
+
+export default RadioCard

package/src/RadioCard/RadioCardGroup.jsx

@@ -0,0 +1,218 @@
+import React, { forwardRef } from 'react'
+import PropTypes from 'prop-types'
+
+import { useViewport } from '../ViewportProvider'
+import { useThemeTokens } from '../ThemeProvider'
+import { getTokensPropType, useInputValue, variantProp } from '../utils'
+import StackView, { StackWrap } from '../StackView'
+import RadioCard from './RadioCard'
+import Fieldset from '../Fieldset'
+
+/**
+ * A group of Cards that behave as a radio button group. Use when users select a single choice from mutually
+ * exclusive options with need to show additional information for each option. The whole cards are each
+ * interactive as one item.
+ *
+ * ## Component API
+ *
+ * Use the `items` prop to pass an array of objects describing each RadioCard in the group:
+ *
+ *  - `title`: main text passed to RadioCard's `title` prop
+ *  - `content`: React content passed to RadioCard's `children` prop
+ *  - `id`: identifier used to store which RadioCard is selected (uses `title` 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 RadioCardGroup 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
+ *
+ * RadioCardGroup accepts all the common accessibility props, but also sets accessibility role `'radiogroup'`
+ * and controls the accessibility state of children like RadioCard and Feedback based on current state.
+ *
+ * @example
+ * ```jsx
+ * <RadioCardGroup
+ *   initialCheckedId="card1"
+ *   items={[
+ *     { title: 'Card 1', id: 'card1', content: <Typography>More info</Typography> },
+ *     { title: 'Card 2', id: 'card2', content: <Typography>Extra content</Typography> },
+ *     { title: 'Card 3', id: 'card3', content: <Typography>More content</Typography> }
+ *   ]}
+ *   legend="Cards"
+ *   hint="Choose a card to select"
+ * />
+ * ```
+ */
+const RadioCardGroup = forwardRef(
+  (
+    {
+      tokens,
+      radioCardTokens,
+      variant,
+      items = [],
+      legend,
+      tooltip,
+      hint,
+      validation,
+      feedback,
+      initialCheckedId,
+      checkedId,
+      onChange,
+      readOnly,
+      name: inputGroupName,
+      inactive
+    },
+    ref
+  ) => {
+    const viewport = useViewport()
+    const { space, fieldSpace, direction } = useThemeTokens('RadioCardGroup', tokens, variant, {
+      viewport
+    })
+
+    const { currentValue, setValue } = useInputValue({
+      value: checkedId,
+      initialValue: initialCheckedId,
+      onChange,
+      readOnly: readOnly || inactive
+    })
+
+    const StackContainer = direction === 'row' ? StackWrap : StackView
+    // Needs 'radiogroup' role on direct parent of radios for MacOS Voiceover's numbering to work,
+    // and also needs 'radiogroup' role on fieldset for correct description on focusing the set.
+    // TODO: test this on more web screen readers.
+    return (
+      <Fieldset
+        ref={ref}
+        name={inputGroupName}
+        legend={legend}
+        tooltip={tooltip}
+        hint={hint}
+        space={fieldSpace}
+        feedback={feedback}
+        inactive={inactive || readOnly}
+        validation={validation}
+        accessibilityRole="radiogroup"
+      >
+        {({ a11yProps }) => (
+          <StackContainer space={space} accessibilityRole="radiogroup">
+            {items.map(({ title, content, id, onChange: itemOnChange }, index) => {
+              const cardId = id || `RadioCard[${index}]`
+              const handleChange = (newCheckedState, event) => {
+                if (typeof itemOnChange === 'function') itemOnChange(newCheckedState, event)
+                if (newCheckedState) setValue(cardId, event)
+              }
+              return (
+                <RadioCard
+                  key={cardId}
+                  id={cardId}
+                  checked={currentValue === cardId}
+                  onChange={handleChange}
+                  inactive={inactive}
+                  title={title}
+                  name={inputGroupName}
+                  tokens={radioCardTokens}
+                  variant={variant}
+                  readOnly={readOnly}
+                  {...a11yProps}
+                >
+                  {content}
+                </RadioCard>
+              )
+            })}
+          </StackContainer>
+        )}
+      </Fieldset>
+    )
+  }
+)
+RadioCardGroup.displayName = 'RadioCardGroup'
+
+RadioCardGroup.propTypes = {
+  /**
+   * Optional theme token overrides for the outer RadioCardGroup component
+   */
+  tokens: getTokensPropType('RadioCardGroup'),
+  /**
+   * Optional theme token overrides for each inner RadioCard component
+   */
+  radioCardTokens: getTokensPropType('RadioCard'),
+  /**
+   * Theme variants, shared between both RadioCardGroup and RadioCard
+   */
+  variant: variantProp.propType,
+  /**
+   * Array of objects containing specifics for each RadioCard to be rendered in the group.
+   */
+  items: PropTypes.arrayOf(
+    PropTypes.exact({
+      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,
+  /**
+   * 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 radio card with this id is selected on first render.
+   */
+  initialCheckedId: PropTypes.string,
+  /**
+   * If not undefined, the radio card with this id is selected (or none is selected if `null`), and the
+   * element's selection state will be controlled by its parent using the `onChange` function.
+   */
+  checkedId: 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 radio 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 radio input.
+   */
+  name: PropTypes.string
+}
+
+export default RadioCardGroup

package/src/RadioCard/index.js

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