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

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,191 @@
+import React 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 = ({
+  tokens,
+  variant,
+  title,
+  children,
+  inactive,
+  defaultChecked,
+  checked,
+  name: inputName,
+  value,
+  id,
+  onChange,
+  ...rest
+}) => {
+  const { currentValue: isChecked, setValue: setIsChecked, isControlled } = useInputValue({
+    value: checked,
+    initialValue: defaultChecked,
+    onChange
+  })
+  const handleChange = () => {
+    if (!inactive && !isChecked) {
+      setIsChecked(true)
+    }
+  }
+  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
+      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}>
+              {title && <Text style={textStyle}>{title}</Text>}
+              {typeof children === 'function' ? children(cardState, textStyle) : children}
+            </StackView>
+          </StackView>
+        )
+      }}
+    </PressableCardBase>
+  )
+}
+
+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,211 @@
+import React 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 = ({
+  tokens,
+  radioCardTokens,
+  variant,
+  items = [],
+  legend,
+  tooltip,
+  hint,
+  validation,
+  feedback,
+  initialCheckedId,
+  checkedId,
+  onChange,
+  readOnly,
+  name: inputGroupName,
+  inactive
+}) => {
+  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
+      name={inputGroupName}
+      legend={legend}
+      tooltip={tooltip}
+      hint={hint}
+      space={fieldSpace}
+      feedback={feedback}
+      inactive={inactive || readOnly}
+      status={validation}
+      accessibilityRole="radiogroup"
+    >
+      {({ a11yProps }) => (
+        <StackContainer space={space} accessibilityRole="radiogroup">
+          {items.map(({ title, content, id, onChange: itemOnChange }, index) => {
+            const cardId = id || `RadioCard[${index}]`
+            const handleChange = (...args) => {
+              if (typeof itemOnChange === 'function') itemOnChange(...args)
+              setValue(cardId)
+            }
+            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.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'

package/src/Search/Search.jsx

@@ -0,0 +1,204 @@
+import React, { useState } from 'react'
+import { View, StyleSheet } from 'react-native'
+
+import PropTypes from 'prop-types'
+import { useThemeTokens, useThemeTokensCallback } from '../ThemeProvider'
+import { getTokensPropType, selectTokens, useSpacingScale, variantProp } from '../utils'
+import TextInputBase from '../TextInput/TextInputBase'
+import ButtonBase from '../Button/ButtonBase'
+import StackView from '../StackView'
+import useCopy from '../utils/useCopy'
+import dictionary from './dictionary'
+
+const selectInputTokens = ({ searchTokens, buttonTokens, buttonsGapSize }) => {
+  const { paddingRight: inputPaddingRight, clearButtonIcon, submitButtonIcon } = searchTokens
+  const { paddingLeft = 0, paddingRight = 0, iconSize = 0 } = buttonTokens
+
+  const buttonWidth = paddingLeft + paddingRight + iconSize
+
+  const paddingWithButtons =
+    inputPaddingRight +
+    (submitButtonIcon ? buttonWidth : 0) +
+    (clearButtonIcon ? buttonsGapSize + buttonWidth : 0)
+
+  return { ...selectTokens('TextInput', searchTokens), paddingRight: paddingWithButtons }
+}
+const selectButtonTokens = (tokens) => selectTokens('Button', tokens)
+
+const selectIconsContainerStyle = ({ paddingRight }) => ({ paddingRight })
+const selectIconTokens = ({ iconSize, iconColor }) => ({ color: iconColor, size: iconSize })
+
+/**
+ * The `Search` component is a combination of a `TextInput` and 2 different kinds of custom buttons.
+ * Use `Search` to feature autocomplete interactions.
+ *
+ * This component includes a clear button, which will appear as text is entered and pressing it will
+ * cause the input's internal state value to be set to an empty string.
+ *
+ * This component may only be used as uncontrolled, as the search value is managed within an internal state.
+ * You can use the `onChange` prop to react to value changes and the `onSubmit` prop to react on search submission.
+ *
+ * Use the following props to supply additional accessibility labels for the input - `accessibilityLabel`,
+ * clear button - `clearButtonAccessibilityLabel`, and submit button - `submitButtonAccessibilityLabel`.
+ */
+const Search = ({
+  initialValue = '',
+  placeholder = 'Search',
+  inactive,
+  onChange,
+  onSubmit,
+  onClear,
+  accessibilityLabel,
+  copy = 'en',
+  tokens,
+  variant
+}) => {
+  const [value, setValue] = useState(initialValue)
+  const themeTokens = useThemeTokens('Search', tokens, variant)
+  const buttonTokens = useThemeTokens('SearchButton', tokens, variant)
+
+  const getThemeTokens = useThemeTokensCallback('Search', tokens, variant)
+  const getButtonTokens = useThemeTokensCallback('SearchButton', tokens, variant)
+
+  // TODO: support overriding the a11y props using a custom dictionary
+  const getCopy = useCopy({ dictionary, copy })
+
+  const {
+    placeholderColor,
+    buttonsGap,
+    clearButtonIcon: ClearButtonIcon,
+    submitButtonIcon: SubmitButtonIcon
+  } = themeTokens
+
+  // get the actual gap value for the current viewport
+  const buttonsGapSize = useSpacingScale(buttonsGap)
+
+  const handleSubmit = () => {
+    if (onSubmit !== undefined) {
+      onSubmit(value)
+    }
+  }
+
+  const handleChange = (currentValue) => {
+    setValue(currentValue)
+
+    if (onChange !== undefined) onChange(currentValue)
+  }
+
+  const handleClear = () => {
+    setValue('')
+
+    if (onClear !== undefined) onClear()
+    if (onChange !== undefined) onChange('')
+  }
+
+  const isEmpty = value === ''
+
+  return (
+    <View>
+      <TextInputBase
+        tokens={(appearances) =>
+          selectInputTokens({
+            searchTokens: getThemeTokens(appearances),
+            buttonTokens,
+            buttonsGapSize,
+            isEmpty
+          })
+        }
+        placeholder={placeholder}
+        placeholderTextColor={placeholderColor}
+        inactive={inactive}
+        enablesReturnKeyAutomatically
+        returnKeyType="search"
+        value={value}
+        onChange={handleChange}
+        onSubmitEditing={handleSubmit}
+        accessibilityLabel={accessibilityLabel || getCopy('accessibilityLabel')}
+      />
+      <View style={[staticStyles.iconsContainer, selectIconsContainerStyle(themeTokens)]}>
+        <StackView direction="row" space={buttonsGap}>
+          {ClearButtonIcon && !isEmpty && (
+            <ButtonBase
+              onPress={handleClear}
+              inactive={inactive}
+              accessibilityRole="button"
+              accessibilityLabel={getCopy('clearButtonAccessibilityLabel')}
+              tokens={(appearances) => selectButtonTokens(getButtonTokens(appearances))}
+            >
+              {(buttonState) => (
+                <ClearButtonIcon tokens={selectIconTokens(getButtonTokens(buttonState))} />
+              )}
+            </ButtonBase>
+          )}
+          {SubmitButtonIcon && (
+            <ButtonBase
+              onPress={handleSubmit}
+              inactive={inactive}
+              accessibilityRole="button"
+              accessibilityLabel={getCopy('submitButtonAccessibilityLabel')}
+              tokens={(buttonState) =>
+                selectButtonTokens(getButtonTokens({ ...buttonState, priority: 'high' }))
+              }
+            >
+              {(buttonState) => (
+                <SubmitButtonIcon
+                  tokens={selectIconTokens(getButtonTokens({ ...buttonState, priority: 'high' }))}
+                />
+              )}
+            </ButtonBase>
+          )}
+        </StackView>
+      </View>
+    </View>
+  )
+}
+
+Search.propTypes = {
+  /**
+   * Use this to set the initial value of the search input.
+   * Updating `initialValue` will **not** update the actual value.
+   */
+  initialValue: PropTypes.string,
+  /**
+   * Label rendered in the search input when it has no value.
+   */
+  placeholder: PropTypes.string,
+  /**
+   * Disables all user interactions with the search input.
+   */
+  inactive: PropTypes.bool,
+  /**
+   * Use to react upon search input's value changes.
+   * Will receive the searched value as an argument.
+   */
+  onChange: PropTypes.func,
+  /**
+   * Triggered when the search input is submitted,
+   * either by pressing the submit button, "Enter" key on web,
+   * or "Search" key in a mobile keyboard.
+   */
+  onSubmit: PropTypes.func,
+  /**
+   * Triggered when the clear button is pressed.
+   */
+  onClear: PropTypes.func,
+  /**
+   * Use to provide an accessible label for the input (visually hidden).
+   */
+  accessibilityLabel: PropTypes.string,
+  copy: PropTypes.oneOfType([PropTypes.oneOf(['en', 'fr']), PropTypes.object]),
+  tokens: getTokensPropType('Search'),
+  variant: variantProp.propType
+}
+
+export default Search
+
+const staticStyles = StyleSheet.create({
+  iconsContainer: {
+    position: 'absolute',
+    right: 0,
+    top: 0,
+    bottom: 0,
+    justifyContent: 'center'
+  }
+})

package/src/Search/dictionary.js

@@ -0,0 +1,12 @@
+export default {
+  en: {
+    accessibilityLabel: 'Search',
+    clearButtonAccessibilityLabel: 'Clear',
+    submitButtonAccessibilityLabel: 'Search'
+  },
+  fr: {
+    accessibilityLabel: 'Chercher',
+    clearButtonAccessibilityLabel: 'Effacer',
+    submitButtonAccessibilityLabel: 'Chercher'
+  }
+}

package/src/Search/index.js

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

package/src/Select/Select.jsx

@@ -2,7 +2,7 @@ import React, { useState } from 'react'
 
 import { View, Platform, StyleSheet } from 'react-native'
 import PropTypes from 'prop-types'
-import { applyTextStyles, useThemeTokens } from '../ThemeProvider'
+import { applyTextStyles, useThemeTokens, applyOuterBorder } from '../ThemeProvider'
 import { componentPropType, getTokensPropType, useInputValue, variantProp } from '../utils'
 import Picker from './Picker'
 import InputSupports from '../InputSupports'
@@ -78,27 +78,17 @@ const selectInputStyles = (
 
 const selectOuterBorderStyles = ({
   outerBackgroundColor,
-  outerBorderWidth = 0,
+  outerBorderWidth,
   outerBorderColor,
-  outerBorderRadius = 0
-}) => {
-  // Use negative margins so that the outer border doesn't expand the input's bounding box
-  const margin = -1 * outerBorderWidth
-
-  // Account for the border width since we style it as an outline
-  const borderRadius = outerBorderRadius + outerBorderWidth
-
-  return {
-    background: outerBackgroundColor,
-    borderWidth: outerBorderWidth,
-    borderColor: outerBorderColor,
-    borderRadius,
-    marginTop: margin,
-    marginBottom: margin,
-    marginLeft: margin,
-    marginRight: margin
-  }
-}
+  borderRadius
+}) => ({
+  background: outerBackgroundColor,
+  ...applyOuterBorder({
+    outerBorderColor,
+    outerBorderWidth,
+    borderRadius
+  })
+})
 
 const selectIconTokens = ({ iconSize, iconColor }) => ({
   size: iconSize,
@@ -231,7 +221,7 @@ const Select = ({
                 pointerEvents="none"
                 style={[staticStyles.iconContainer, selectIconContainerStyles(themeTokens)]}
               >
-                <IconComponent tokens={selectIconTokens(themeTokens)} />
+                <IconComponent {...selectIconTokens(themeTokens)} />
               </View>
             )}
         </View>