@telus-uds/components-base 0.0.2-prerelease.6 → 1.0.0

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,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

@@ -0,0 +1,102 @@
+import React, { forwardRef, 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 = 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
+    })
+
+    const items = flatChildren.map(({ props }) => ({
+      label: props.children,
+      value: props.value
+    }))
+
+    // 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
+          }
+        })
+    }
+
+    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
+
+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,298 @@
+import React, { forwardRef, 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 = forwardRef(
+  (
+    {
+      value,
+      initialValue,
+      onChange,
+      children,
+      inactive,
+      readOnly,
+      placeholder,
+      validation,
+      tokens,
+      variant,
+      testID,
+      ...rest
+    },
+    ref
+  ) => {
+    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
+              ref={ref}
+              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.displayName = 'Select'
+
+Select.propTypes = {
+  ...inputSupportsProps.types,
+  /**
+   * Initial value for the uncontrolled version.
+   */
+  initialValue: PropTypes.string,
+  /**
+   * Current value to be set as selected.
+   */
+  value: PropTypes.string,
+  /**
+   * Callback to be called when the value changes.
+   */
+  onChange: PropTypes.func,
+  /**
+   * An array of items or item groups to be used as options.
+   */
+  children: componentPropType(['Item', 'Group']),
+  /**
+   * Whether the select is disabled.
+   */
+  inactive: PropTypes.bool,
+  /**
+   * Whether the select is read-only.
+   */
+  readOnly: PropTypes.bool,
+  /**
+   * A placeholder to provide instructions (such as "Please select...")
+   * as an unselectable option
+   */
+  placeholder: PropTypes.string,
+  /**
+   * Select tokens.
+   */
+  tokens: getTokensPropType('Select'),
+  /**
+   * Select variant.
+   */
+  variant: variantProp.propType,
+  /**
+   * Dedicated ID for testing.
+   */
+  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

package/src/SideNav/Item.jsx

@@ -1,4 +1,4 @@
-import React from 'react'
+import React, { forwardRef } from 'react'
 import { Pressable } from 'react-native'
 import PropTypes from 'prop-types'
 
@@ -37,54 +37,61 @@ function selectItemStyles({
 
  This component can only be accessed as a name-spaced component: `SideNav.Item`.
  */
-const Item = ({
-  children,
-  itemId,
-  groupId,
-  onPress,
-  isActive = false,
-  isExpanded = false,
-  tokens,
-  variant,
-  href,
-  accessibilityRole = 'link',
-  testID,
-  ...props
-}) => {
-  const handlePress = () => onPress(itemId, groupId)
+const Item = forwardRef(
+  (
+    {
+      children,
+      itemId,
+      groupId,
+      onPress,
+      isActive = false,
+      isExpanded = false,
+      tokens,
+      variant,
+      href,
+      accessibilityRole = 'link',
+      testID,
+      ...props
+    },
+    ref
+  ) => {
+    const handlePress = () => onPress(itemId, groupId)
 
-  const { hrefAttrs, rest } = hrefAttrsProp.bundle(props)
-  const linkPropSet = linkProps.select({
-    accessibilityRole,
-    href,
-    onPress: handlePress,
-    ...hrefAttrsProp.spread(hrefAttrs),
-    ...rest
-  })
+    const { hrefAttrs, rest } = hrefAttrsProp.bundle(props)
+    const linkPropSet = linkProps.select({
+      accessibilityRole,
+      href,
+      onPress: handlePress,
+      hrefAttrs,
+      ...rest
+    })
 
-  const getTokens = useThemeTokensCallback('SideNavItem', tokens, variant)
-  const getAppearanceState = ({ hovered }) => ({
-    hover: hovered,
-    active: isActive,
-    expanded: isExpanded
-  })
-  const getPressableStyle = (pressableState) =>
-    selectItemStyles(getTokens(getAppearanceState(pressableState)))
+    const getTokens = useThemeTokensCallback('SideNavItem', tokens, variant)
+    const getAppearanceState = ({ hovered }) => ({
+      hover: hovered,
+      active: isActive,
+      expanded: isExpanded
+    })
+    const getPressableStyle = (pressableState) =>
+      selectItemStyles(getTokens(getAppearanceState(pressableState)))
 
-  return (
-    <Pressable
-      style={getPressableStyle}
-      {...linkPropSet}
-      accessibilityState={{ selected: isActive }}
-      testID={testID}
-    >
-      {(pressableState) => {
-        const themeTokens = getTokens(getAppearanceState(pressableState))
-        return <ItemContent tokens={themeTokens}>{children}</ItemContent>
-      }}
-    </Pressable>
-  )
-}
+    return (
+      <Pressable
+        ref={ref}
+        style={getPressableStyle}
+        {...linkPropSet}
+        accessibilityState={{ selected: isActive }}
+        testID={testID}
+      >
+        {(pressableState) => {
+          const themeTokens = getTokens(getAppearanceState(pressableState))
+          return <ItemContent tokens={themeTokens}>{children}</ItemContent>
+        }}
+      </Pressable>
+    )
+  }
+)
+Item.displayName = 'Item'
 
 Item.propTypes = {
   /**
@@ -105,7 +112,7 @@ Item.propTypes = {
   href: PropTypes.string,
   /**
    * On Web if href is passed, React Native Web maps this object's props to
-   * `rel`, `target` and (>= RNW 0.15.0) `download` attrs.
+   * `rel`, `target` and `download` attrs.
    */
   hrefAttrs: PropTypes.shape(hrefAttrsProp.types),
   /**