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

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/Group.jsx

@@ -0,0 +1,15 @@
+import React from 'react'
+import PropTypes from 'prop-types'
+
+import { componentPropType } from '../utils'
+
+const Group = ({ children, label }) => {
+  return <optgroup label={label}>{children}</optgroup>
+}
+
+export default Group
+
+Group.propTypes = {
+  children: componentPropType('Item'),
+  label: PropTypes.string.isRequired
+}

package/src/Select/Group.native.jsx

@@ -0,0 +1,14 @@
+import PropTypes from 'prop-types'
+
+import { componentPropType } from '../utils'
+
+const Group = ({ children }) => {
+  return children
+}
+
+export default Group
+
+Group.propTypes = {
+  children: componentPropType('Item'),
+  label: PropTypes.string.isRequired
+}

package/src/Select/Item.jsx

@@ -0,0 +1,11 @@
+import React from 'react'
+import PropTypes from 'prop-types'
+
+const Item = ({ children, value }) => <option value={value}>{children}</option>
+
+export default Item
+
+Item.propTypes = {
+  children: PropTypes.string.isRequired,
+  value: PropTypes.string.isRequired
+}

package/src/Select/Item.native.jsx

@@ -0,0 +1,10 @@
+import PropTypes from 'prop-types'
+
+const Item = () => null
+
+export default Item
+
+Item.propTypes = {
+  children: PropTypes.string.isRequired,
+  value: PropTypes.string.isRequired
+}

package/src/Select/Picker.jsx

@@ -0,0 +1,67 @@
+import React from 'react'
+
+import PropTypes from 'prop-types'
+import { componentPropType } from '../utils'
+
+const Picker = ({
+  value,
+  onChange,
+  onFocus,
+  onBlur,
+  onMouseOver,
+  onMouseOut,
+  style,
+  inactive,
+  children,
+  placeholder,
+  nativeID,
+  testID,
+  ...rest
+}) => {
+  const { accessibilityLabel, accessibilityDescribedBy, accessibilityInvalid } = rest
+
+  return (
+    <select
+      style={style}
+      onMouseOver={onMouseOver}
+      onMouseOut={onMouseOut}
+      onFocus={onFocus}
+      onBlur={onBlur}
+      disabled={inactive}
+      value={value || (placeholder !== undefined ? placeholder.value : undefined)}
+      onChange={(event) => onChange(event.target.value)}
+      id={nativeID}
+      aria-label={accessibilityLabel}
+      aria-describedby={accessibilityDescribedBy}
+      aria-invalid={accessibilityInvalid}
+      data-testid={testID}
+    >
+      {placeholder !== undefined && (
+        <option value={placeholder.value} disabled hidden>
+          {placeholder.label}
+        </option>
+      )}
+      {children}
+    </select>
+  )
+}
+
+export default Picker
+
+Picker.propTypes = {
+  value: PropTypes.string,
+  onChange: PropTypes.func,
+  onFocus: PropTypes.func,
+  onBlur: PropTypes.func,
+  onMouseOver: PropTypes.func,
+  onMouseOut: PropTypes.func,
+  style: PropTypes.object,
+  inactive: PropTypes.bool,
+  children: componentPropType(['Item', 'Group']),
+  placeholder: PropTypes.shape({
+    value: PropTypes.string,
+    label: PropTypes.string
+  }),
+  nativeID: PropTypes.string,
+  testID: PropTypes.string
+}

package/src/Select/Picker.native.jsx

@@ -0,0 +1,95 @@
+import React, { Children } from 'react'
+import PropTypes from 'prop-types'
+import { View, Platform } from 'react-native'
+import NativePicker from 'react-native-picker-select'
+
+import { a11yProps, componentPropType } from '../utils'
+import Group from './Group'
+
+// styling of the native input is very limited, most of the styles have to be applied to an additional View
+const selectAndroidInputStyles = ({
+  height = 0,
+  paddingBottom = 0,
+  paddingTop = 0,
+  borderWidth = 0,
+  color
+}) => ({
+  height: height - paddingTop - paddingBottom - 2 * borderWidth,
+  color
+})
+
+// the native input has a side padding of 8px, which can't be adjusted, so we have to account for that in the container
+const selectAndroidContainerStyles = ({ paddingLeft = 0, paddingRight = 0, ...rest }) => ({
+  paddingLeft: paddingLeft > 8 ? paddingLeft - 8 : 0,
+  paddingRight: paddingRight > 8 ? paddingRight - 8 : 0,
+  ...rest
+})
+
+const Picker = ({
+  value,
+  onChange,
+  onFocus,
+  onBlur,
+  style,
+  inactive,
+  children,
+  placeholder,
+  ...rest
+}) => {
+  // ungroup items, since there's no way to support groups on native
+  const flatChildren = Children.toArray(children).flatMap((child) => {
+    if (child.type === Group) {
+      return child.props.children
+    }
+
+    return child
+  })
+
+  const items = flatChildren.map(({ props }) => ({
+    label: props.children,
+    value: props.value
+  }))
+
+  const picker = (
+    <NativePicker
+      touchableWrapperProps={a11yProps.select(rest)}
+      onOpen={onFocus}
+      onClose={onBlur}
+      disabled={inactive}
+      items={items}
+      value={value}
+      onValueChange={onChange}
+      style={{
+        inputIOS: style,
+        inputAndroid: selectAndroidInputStyles(style)
+      }}
+      placeholder={placeholder !== undefined ? placeholder : {}}
+    />
+  )
+
+  return (
+    <>
+      {Platform.OS === 'android' ? (
+        <View style={selectAndroidContainerStyles(style)}>{picker}</View>
+      ) : (
+        picker
+      )}
+    </>
+  )
+}
+
+export default Picker
+
+Picker.propTypes = {
+  value: PropTypes.string,
+  onChange: PropTypes.func,
+  onFocus: PropTypes.func,
+  onBlur: PropTypes.func,
+  style: PropTypes.object,
+  inactive: PropTypes.bool,
+  children: componentPropType(['Item', 'Group']),
+  placeholder: PropTypes.shape({
+    value: PropTypes.string,
+    label: PropTypes.string
+  })
+}

package/src/Select/Select.jsx

@@ -0,0 +1,255 @@
+import React, { useState } from 'react'
+
+import { View, Platform, StyleSheet } from 'react-native'
+import PropTypes from 'prop-types'
+import { applyTextStyles, useThemeTokens, applyOuterBorder } from '../ThemeProvider'
+import { componentPropType, getTokensPropType, useInputValue, variantProp } from '../utils'
+import Picker from './Picker'
+import InputSupports from '../InputSupports'
+import inputSupportsProps from '../InputSupports/propTypes'
+
+const selectInputStyles = (
+  {
+    backgroundColor,
+    color,
+    borderWidth = 0,
+    borderColor,
+    borderRadius,
+    paddingTop,
+    paddingBottom,
+    paddingLeft = 0,
+    paddingRight,
+    fontName,
+    fontSize,
+    fontWeight,
+    lineHeight,
+    icon,
+    iconSize = 0,
+    validationIcon,
+    validationIconSize = 0,
+    height
+  },
+  inactive
+) => {
+  // Subtract border width from padding so overall input width/height doesn't
+  // jump around if the border width changes (avoiding NaN and negative padding)
+  const offsetBorder = (value) =>
+    typeof value === 'number' ? Math.max(0, value - borderWidth) : value
+
+  const textStyles = applyTextStyles({ fontName, fontSize, lineHeight, fontWeight })
+
+  const webStyles = Platform.select({
+    web: {
+      appearance: 'none',
+      WebkitAppearance: 'none', // since iOS Safari needs a prefix
+      outline: 'none',
+      cursor: inactive ? 'not-allowed' : undefined,
+      opacity: inactive ? 1 : undefined // override Chrome's default fadeout of a disabled select
+    }
+  })
+
+  let paddingWithIcons = paddingRight
+
+  if (Platform.OS !== 'android') {
+    if (icon) {
+      paddingWithIcons += iconSize
+    }
+
+    if (validationIcon) {
+      paddingWithIcons += validationIconSize
+    }
+  }
+
+  return {
+    backgroundColor,
+    color,
+    borderWidth,
+    borderColor,
+    borderRadius,
+    paddingLeft: offsetBorder(paddingLeft),
+    paddingRight: offsetBorder(paddingWithIcons),
+    paddingTop: offsetBorder(paddingTop),
+    paddingBottom: offsetBorder(paddingBottom),
+    height,
+    ...textStyles,
+    ...webStyles
+  }
+}
+
+const selectOuterBorderStyles = ({
+  outerBackgroundColor,
+  outerBorderWidth,
+  outerBorderColor,
+  borderRadius
+}) => ({
+  background: outerBackgroundColor,
+  ...applyOuterBorder({
+    outerBorderColor,
+    outerBorderWidth,
+    borderRadius
+  })
+})
+
+const selectIconTokens = ({ iconSize, iconColor }) => ({
+  size: iconSize,
+  color: iconColor
+})
+
+const selectIconContainerStyles = ({ paddingRight, paddingBottom }) => ({
+  paddingRight,
+  paddingBottom
+})
+
+const selectValidationIconTokens = ({ validationIconSize, validationIconColor }) => ({
+  size: validationIconSize,
+  color: validationIconColor
+})
+
+const selectValidationIconContainerStyles = ({
+  icon,
+  iconSize = 0,
+  paddingRight = 0,
+  paddingBottom
+}) => ({
+  paddingRight: icon ? paddingRight + iconSize : paddingRight,
+  paddingBottom
+})
+
+/**
+ * A basic form single-choice select component. Use in forms or individually to receive user's input.
+ *
+ * ## Usage criteria
+ * - Include a `placeholder` to provide instructions such as "Please select..." as an unselectable option (recommended)
+ * - Use when options are between 7-15 (recommended)
+ * - For options are 6 and under, use `Radio` groups or `ButtonGroup`.
+ * - For options 15 and above, look for alternatives (e.g grouping into categories, or input field with auto-complete etc.)
+ *
+ * ## Controlled component
+ * If it is required that the state of the `Select` be controlled by the application or other external methods,
+ * `value` and `onChange` props must be passed to the `Select`.
+ * If the `Select` value should not be changed by user input, a `readOnly` prop must be provided.
+ *
+ * ## Uncontrolled component
+ * If it is not necessary to control the `Select` state, you can create one without a value prop.
+ * In this case its value can be accessed within the `onChange` callback. Use the `initialValue` prop to set the
+ * default value for an uncontrolled `Select`.
+ *
+ * ## Getting feedback for entered values
+ * Use the `feedback` prop to give the user feedback regarding their selection.
+ * You can affirm that the user's selection was correct, or highlight errors that must be corrected, using the `validation` prop.
+ * Keep feedback text as brief as possible, should be limited to text and links.
+ *
+ * ## Using a tooltip
+ * When a more in-depth explanation is needed to fill out a `Select` properly, the tooltip prop may be used.
+ *
+ * ## Grouping options
+ * `Select` supports option groups. Use a `Select.Group` component to render an `<optgroup>` element with its items.
+ * NOTE: this does not work on native platforms - the grouped items will be shown at the same level as the non-grouped items.
+ *
+ */
+const Select = ({
+  value,
+  initialValue,
+  onChange,
+  children,
+  inactive,
+  readOnly,
+  placeholder,
+  validation,
+  tokens,
+  variant,
+  testID,
+  ...rest
+}) => {
+  const { currentValue, setValue } = useInputValue({
+    value,
+    initialValue,
+    onChange,
+    readOnly
+  })
+
+  const [isFocused, setIsFocused] = useState(false)
+  const handleFocus = () => setIsFocused(true)
+  const handleBlur = () => setIsFocused(false)
+
+  const [isHovered, setIsHovered] = useState(false)
+  const handleMouseOver = () => setIsHovered(true)
+  const handleMouseOut = () => setIsHovered(false)
+
+  const { props: supportsProps } = inputSupportsProps.select(rest)
+
+  const themeTokens = useThemeTokens('Select', tokens, variant, {
+    focus: isFocused,
+    hover: isHovered,
+    inactive,
+    validation
+  })
+
+  const { icon: IconComponent, validationIcon: ValidationIconComponent } = themeTokens
+
+  return (
+    <InputSupports {...supportsProps}>
+      {({ a11yProps, inputId }) => (
+        <View style={selectOuterBorderStyles(themeTokens)}>
+          <Picker
+            style={selectInputStyles(themeTokens, inactive)}
+            onFocus={handleFocus}
+            onBlur={handleBlur}
+            onMouseOver={handleMouseOver}
+            onMouseOut={handleMouseOut}
+            onChange={setValue}
+            value={currentValue}
+            inactive={inactive}
+            placeholder={placeholder !== undefined ? { label: placeholder, value: '' } : undefined}
+            {...a11yProps}
+            nativeID={inputId}
+            testID={testID}
+          >
+            {children}
+          </Picker>
+          {ValidationIconComponent && (
+            <View
+              pointerEvents="none"
+              style={[staticStyles.iconContainer, selectValidationIconContainerStyles(themeTokens)]}
+            >
+              <ValidationIconComponent tokens={selectValidationIconTokens(themeTokens)} />
+            </View>
+          )}
+          {IconComponent &&
+            Platform.OS !== 'android' && ( // we can't hide the default caret of a native picker on android
+              <View
+                pointerEvents="none"
+                style={[staticStyles.iconContainer, selectIconContainerStyles(themeTokens)]}
+              >
+                <IconComponent {...selectIconTokens(themeTokens)} />
+              </View>
+            )}
+        </View>
+      )}
+    </InputSupports>
+  )
+}
+
+Select.propTypes = {
+  ...inputSupportsProps.types,
+  initialValue: PropTypes.string,
+  value: PropTypes.string,
+  onChange: PropTypes.func,
+  children: componentPropType(['Item', 'Group']),
+  inactive: PropTypes.bool,
+  readOnly: PropTypes.bool,
+  placeholder: PropTypes.string,
+  tokens: getTokensPropType('Select'),
+  variant: variantProp.propType,
+  testID: PropTypes.string
+}
+
+export default Select
+
+const staticStyles = StyleSheet.create({
+  iconContainer: {
+    position: 'absolute',
+    right: 0,
+    bottom: 0
+  }
+})

package/src/Select/index.js

@@ -0,0 +1,8 @@
+import Select from './Select'
+import Group from './Group'
+import Item from './Item'
+
+Select.Group = Group
+Select.Item = Item
+
+export default Select