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

package/src/Search/Search.jsx

@@ -0,0 +1,225 @@
+import React, { forwardRef, 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 = forwardRef(
+  (
+    {
+      initialValue = '',
+      placeholder = 'Search',
+      inactive,
+      onChange,
+      onSubmit,
+      onClear,
+      accessibilityLabel,
+      copy = 'en',
+      tokens,
+      variant
+    },
+    ref
+  ) => {
+    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 = (event) => {
+      if (onSubmit !== undefined) {
+        onSubmit(value, event)
+      }
+    }
+
+    const handleChange = (currentValue, event) => {
+      setValue(currentValue, event)
+
+      if (onChange !== undefined) onChange(currentValue, event)
+    }
+
+    const handleClear = (event) => {
+      setValue('', event)
+
+      if (onClear !== undefined) onClear('', event)
+      if (onChange !== undefined) onChange('', event)
+    }
+
+    const isEmpty = value === ''
+
+    return (
+      <View style={staticStyles.container}>
+        <TextInputBase
+          ref={ref}
+          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 {...selectIconTokens(getButtonTokens(buttonState))} />
+                )}
+              </ButtonBase>
+            )}
+            {SubmitButtonIcon && (
+              <ButtonBase
+                onPress={handleSubmit}
+                inactive={inactive}
+                accessibilityRole="button"
+                accessibilityLabel={getCopy('submitButtonAccessibilityLabel')}
+                tokens={(buttonState) =>
+                  selectButtonTokens(getButtonTokens({ ...buttonState, priority: 'high' }))
+                }
+              >
+                {(buttonState) => (
+                  <SubmitButtonIcon
+                    {...selectIconTokens(getButtonTokens({ ...buttonState, priority: 'high' }))}
+                  />
+                )}
+              </ButtonBase>
+            )}
+          </StackView>
+        </View>
+      </View>
+    )
+  }
+)
+Search.displayName = 'Search'
+
+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,
+  /**
+   * Select english or french copy for the accessible labels.
+   * You may also pass in a custom dictionary object.
+   */
+  copy: PropTypes.oneOfType([
+    PropTypes.oneOf(['en', 'fr']),
+    PropTypes.shape({
+      accessibilityLabel: PropTypes.string,
+      clearButtonAccessibilityLabel: PropTypes.string,
+      submitButtonAccessibilityLabel: PropTypes.string
+    })
+  ]),
+  tokens: getTokensPropType('Search'),
+  variant: variantProp.propType
+}
+
+export default Search
+
+const staticStyles = StyleSheet.create({
+  container: {
+    // No styles needed here except the View defaults (position: relative etc)
+  },
+  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/Picker.jsx

@@ -0,0 +1,74 @@
+import React, { forwardRef } from 'react'
+
+import PropTypes from 'prop-types'
+import { componentPropType } from '../utils'
+
+const Picker = forwardRef(
+  (
+    {
+      value,
+      onChange,
+      onFocus,
+      onBlur,
+      onMouseOver,
+      onMouseOut,
+      style,
+      inactive,
+      children,
+      placeholder,
+      nativeID,
+      testID,
+      ...rest
+    },
+    ref
+  ) => {
+    const { accessibilityLabel, accessibilityDescribedBy, accessibilityInvalid } = rest
+
+    return (
+      <select
+        ref={ref}
+        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, event)}
+        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>
+    )
+  }
+)
+Picker.displayName = 'Picker'
+
+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

@@ -1,4 +1,4 @@
-import React, { Children } from 'react'
+import React, { forwardRef, Children } from 'react'
 import PropTypes from 'prop-types'
 import { View, Platform } from 'react-native'
 import NativePicker from 'react-native-picker-select'
@@ -25,58 +25,65 @@ const selectAndroidContainerStyles = ({ paddingLeft = 0, paddingRight = 0, ...re
   ...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
-    }
+const Picker = forwardRef(
+  ({ value, onChange, onFocus, onBlur, style, inactive, children, placeholder, ...rest }, ref) => {
+    // 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
-  })
+      return child
+    })
 
-  const items = flatChildren.map(({ props }) => ({
-    label: props.children,
-    value: props.value
-  }))
+    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 : {}}
-    />
-  )
+    // Unlike other input components, react-native-picker-select doesn't pass an event to its change fn.
+    const handleChange = (newValue, index) => {
+      if (onChange)
+        onChange(newValue, {
+          // TODO: see if it's possible to pass a real React SyntheticEvent here. For now, just pass an
+          // object with a shape where if an onChange deconstructs `event.nativeEvent`, it won't crash.
+          nativeEvent: {
+            index,
+            value: newValue
+          }
+        })
+    }
 
-  return (
-    <>
-      {Platform.OS === 'android' ? (
-        <View style={selectAndroidContainerStyles(style)}>{picker}</View>
-      ) : (
-        picker
-      )}
-    </>
-  )
-}
+    const picker = (
+      <NativePicker
+        pickerProps={{ ref }}
+        touchableWrapperProps={a11yProps.select(rest)}
+        onOpen={onFocus}
+        onClose={onBlur}
+        disabled={inactive}
+        items={items}
+        value={value}
+        onValueChange={handleChange}
+        style={{
+          inputIOS: style,
+          inputAndroid: selectAndroidInputStyles(style)
+        }}
+        placeholder={placeholder !== undefined ? placeholder : {}}
+      />
+    )
+
+    return (
+      <>
+        {Platform.OS === 'android' ? (
+          <View style={selectAndroidContainerStyles(style)}>{picker}</View>
+        ) : (
+          picker
+        )}
+      </>
+    )
+  }
+)
+Picker.displayName = 'Picker'
 
 export default Picker