@telus-uds/components-base 1.6.1 → 1.7.0

package/lib-module/utils/props/textInputProps.js

@@ -0,0 +1,193 @@
+import PropTypes from 'prop-types';
+import Platform from "react-native-web/dist/exports/Platform";
+import getPropSelector from './getPropSelector'; // This file contains common props for components that render a React Native TextInput
+// It excludes interaction handler functions which are in `./handlerProps.js`
+
+/**
+ * TextInput (web and native) supports some common React Native props
+ * shared with React Native's Text component.
+ */
+
+const textProps = {
+  maxFontSizeMultiplier: PropTypes.number,
+  nativeId: PropTypes.string,
+  onLayout: PropTypes.func
+};
+/**
+ * UDS text inputs accept props related to UDS's useInputValue hook
+ */
+
+const inputValueProps = {
+  value: PropTypes.string,
+  initialValue: PropTypes.string,
+  readOnly: PropTypes.bool
+};
+/**
+ * This collection adds props that can be passed through to both React Native's
+ * and React Native Web's implementations of the React Native TextInput component.
+ */
+
+const crossPlatform = { ...textProps,
+  ...inputValueProps,
+
+  /**
+   * Web and Android; 'off' disables device autocomplete, other strings are platform-specific.
+   * Valid values on Native: https://reactnative.dev/docs/textinput#autocomplete-android
+   * Valid values on Web: https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/autocomplete
+   */
+  autoComplete: PropTypes.string,
+
+  /**
+   * On Native, default is `true`, passing `false` disables autoCorrect.
+   * On web, only supported by Safari and expects "on" or "off" strings.
+   */
+  autoCorrect: PropTypes.oneOf([true, false, 'on', 'off']),
+
+  /**
+   * Focuses the element on mount. On Web, only the first form element with autoFocus is focussed.
+   */
+  autoFocus: PropTypes.bool,
+
+  /**
+   * Default is `true` for single line, `false` for multi-line
+   */
+  blurOnSubmit: PropTypes.bool,
+
+  /**
+   * iOS and Web only, no effect on Android
+   */
+  clearTextOnFocus: PropTypes.bool,
+
+  /**
+   * Default is `true`. On web, this works by mapping to input's `readonly` attribute
+   */
+  editable: PropTypes.bool,
+
+  /**
+   * See documentation for allowed values (varies between Web, Android and iOS) and important notes:
+   * - Native: https://reactnative.dev/docs/textinput#keyboardtype
+   * - Web: equivalent to `inputmode` but see https://necolas.github.io/react-native-web/docs/text-input/
+   */
+  keyboardType: PropTypes.string,
+
+  /**
+   * Uses native tools (no flicker) to cap the maximum number of characters.
+   * On Web, works via `maxlength` attr.
+   */
+  maxLength: PropTypes.number,
+
+  /**
+   * If passed as true, the text input can be multiple lines.
+   *
+   * > It is important to note that this aligns the text to the top on iOS, and centers it on Android.
+   * > Use with textAlignVertical set to top for the same behavior in both platforms.
+   */
+  multiline: PropTypes.bool,
+
+  /**
+   * Web and Android only, requires `multiline` to be `true`.
+   */
+  numberOfLines: PropTypes.number,
+
+  /**
+   * Text to display when no value set.
+   * Accesibility guidelines recommend using labels to describe the input and using
+   * placeholders rarely and sparingly to prompt a particular format.
+   */
+  placeholder: PropTypes.string,
+
+  /**
+   * Sets placeholder colour. On Web, uses `::placeholder { color: ... }` selector.
+   */
+  placeholderTextColor: PropTypes.string,
+
+  /**
+   * One of a subset of platform-specific options that controls labelling and presentation
+   * in on-screen keyboards and accessibility tools. Uses `enterkeyhint` attr on Web.
+   *
+   * 'done', 'go', 'next', 'search', and 'send' are available for Web, Android and iOS.
+   */
+  returnKeyType: PropTypes.string,
+
+  /**
+   * Obscures passwords and similar. Equivalent to type="password" on Web.
+   * Does not work if multiline is true.
+   */
+  secureTextEntry: PropTypes.bool,
+
+  /**
+   * If true, all text will automatically be selected on focus.
+   */
+  selectTextOnFocus: PropTypes.bool,
+
+  /**
+   * Web and iOS. On iOS, default inherits from `autoCorrect`.
+   * On Web, equivalent to `spellcheck` attr.
+   */
+  spellCheck: PropTypes.bool
+};
+/**
+ * These web-only props all control HTML `input` attributes of the same name.
+ * Refer to general HTML documentation for more details.
+ */
+
+const webOnly = {
+  disabled: PropTypes.bool,
+  dir: PropTypes.oneOf(['auto', 'ltr', 'rtl']),
+  lang: PropTypes.string
+};
+/**
+ * These props are supported in React Native but not React Native Web.
+ *
+ * React Native text inputs can be quirky, so a full set of props should be allowed to handle edge cases.
+ * Refer to React Native documentation for details, allowed values, and Android/iOS support and versions:
+ * https://reactnative.dev/docs/textinput
+ *
+ * Beware that many React Native text input props apply via complicated logic that chooses a built-in
+ * native component based on the values of multiple boolean flags, and may sometimes appear to pick an
+ * option that is inappropriate for one flag based on the values of one or more other other flags.
+ */
+
+const nativeOnly = {
+  caretHidden: PropTypes.bool,
+  clearButtonMode: PropTypes.string,
+  contextMenuHidden: PropTypes.bool,
+  dataDetectorTypes: PropTypes.string,
+  disableFullscreenUI: PropTypes.bool,
+  enablesReturnKeyAutomatically: PropTypes.bool,
+  importantForAutofill: PropTypes.string,
+  inlineImageLeft: PropTypes.string,
+  keyboardAppearance: PropTypes.string,
+  returnKeyLabel: PropTypes.string,
+  rejectResponderTermination: PropTypes.bool,
+  scrollEnabled: PropTypes.bool,
+  selection: PropTypes.object,
+  selectionColor: PropTypes.string,
+  showSoftInputOnFocus: PropTypes.bool,
+  textAlign: PropTypes.string,
+  textContentType: PropTypes.string,
+  passwordRules: PropTypes.string,
+  textBreakStrategy: PropTypes.string,
+  underlineColorAndroid: PropTypes.string
+};
+export default {
+  /**
+   * Subset of proptypes that can be passed down to a React Native or React Native Web
+   * `TextInput` component. Allow regardless of platform, so cross-platform apps don't warn.
+   */
+  types: { ...crossPlatform,
+    ...webOnly,
+    ...nativeOnly
+  },
+
+  /**
+   * Filters a props object. Return only platform-appropriate TextInput props, native inputs
+   * may throw errors on receiving unknown props.
+   */
+  select: getPropSelector({ ...crossPlatform,
+    ...Platform.select({
+      web: webOnly,
+      default: nativeOnly
+    })
+  })
+};

package/lib-module/utils/props/textProps.js

@@ -0,0 +1,59 @@
+import PropTypes from 'prop-types';
+import Platform from "react-native-web/dist/exports/Platform";
+import getPropSelector from './getPropSelector'; // These are the props accepted specifically on React Native (Web) `Text` elements.
+// They are generally concerned with the behaviour of multiline text.
+
+const crossPlatform = {
+  /**
+   * Truncates text after this many lines with an ellipsis at the end.
+   * On native, ellipsis behaviour may be changed with `ellipsizeMode` prop.
+   */
+  numberOfLines: PropTypes.number,
+
+  /**
+   * Default is true on web and false on native
+   */
+  selectable: PropTypes.bool
+};
+/**
+ * See React Native docs for latest details on these.
+ * https://reactnative.dev/docs/text
+ */
+
+const nativeOnly = {
+  ellipsizeMode: PropTypes.string,
+  maxFontSizeMultiplier: PropTypes.number,
+  minimumFontScale: PropTypes.number,
+  onTextLayout: PropTypes.func,
+  suppressHighlighting: PropTypes.bool,
+  textBreakStrategy: PropTypes.string
+};
+/**
+ * These set HTML attributes of the same name.
+ */
+
+const webOnly = {
+  dir: PropTypes.oneOf(['auto', 'ltr', 'rtl']),
+  lang: PropTypes.string
+};
+export default {
+  /**
+   * Set of prop types specific to React Native and React Native Web `Text`,
+   * which largely revolve around the behaviour of multiline non-pressable text.
+   */
+  types: { ...crossPlatform,
+    ...webOnly,
+    ...nativeOnly
+  },
+
+  /**
+   * Filters a props object, returning only props specific to `Text` elements
+   * on the current platform. Does not include props applicable to `Text` and `View`.
+   */
+  select: getPropSelector({ ...crossPlatform,
+    ...Platform.select({
+      web: webOnly,
+      default: nativeOnly
+    })
+  })
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@telus-uds/components-base",
-  "version": "1.6.1",
+  "version": "1.7.0",
   "description": "Base components",
   "keywords": [
     "base"

package/src/List/ListItem.jsx

@@ -22,8 +22,7 @@ const selectBulletStyles = ({ itemBulletWidth, itemBulletHeight, itemBulletColor
 
 const selectBulletContainerStyles = ({ itemBulletContainerWidth, itemBulletContainerAlign }) => ({
   width: itemBulletContainerWidth,
-  alignItems: itemBulletContainerAlign,
-  justifyContent: itemBulletContainerAlign
+  alignItems: itemBulletContainerAlign
 })
 
 const selectItemIconTokens = ({ itemIconSize, itemIconColor }) => ({
@@ -31,12 +30,15 @@ const selectItemIconTokens = ({ itemIconSize, itemIconColor }) => ({
   color: itemIconColor
 })
 
-const selectCommonIconStyles = ({ iconMarginTop }) => ({
-  marginTop: iconMarginTop
+const selectSideItemContainerStyles = ({ listGutter, iconMarginTop }) => ({
+  marginTop: iconMarginTop,
+  marginRight: listGutter
 })
 
-const selectSideItemContainerStyles = ({ listGutter }) => ({
-  marginRight: listGutter
+// Align bullets with the top line of text the same way icons are aligned
+const selectBulletPositioningStyles = ({ itemIconSize }) => ({
+  width: itemIconSize,
+  height: itemIconSize
 })
 
 const selectItemStyles = ({ itemFontWeight, itemFontSize, itemLineHeight, itemFontName }) =>
@@ -73,8 +75,8 @@ const ListItem = forwardRef(
     const dividerStyles = selectDividerStyles(themeTokens)
     const itemBulletContainerStyles = selectBulletContainerStyles(themeTokens)
     const itemBulletStyles = selectBulletStyles(themeTokens)
+    const itemBulletPositioningStyles = selectBulletPositioningStyles(themeTokens)
     const iconTokens = selectItemIconTokens(themeTokens)
-    const commonIconStyles = selectCommonIconStyles(themeTokens)
     const sideItemContainerStyles = selectSideItemContainerStyles(themeTokens)
     const accessibilityRole = Platform.select({ web: 'listitem', default: 'item' })
 
@@ -109,7 +111,7 @@ const ListItem = forwardRef(
 
       if (icon) {
         return (
-          <View style={[sideItemContainerStyles, commonIconStyles]}>
+          <View style={sideItemContainerStyles}>
             <IconComponent
               size={iconSize || iconTokens.size}
               color={iconColor || iconTokens.color}
@@ -120,7 +122,9 @@ const ListItem = forwardRef(
 
       return (
         <View style={[sideItemContainerStyles, itemBulletContainerStyles]}>
-          <View style={itemBulletStyles} testID="unordered-item-bullet" />
+          <View style={[staticStyles.bulletPositioning, itemBulletPositioningStyles]}>
+            <View style={itemBulletStyles} testID="unordered-item-bullet" />
+          </View>
         </View>
       )
     }
@@ -146,6 +150,10 @@ const staticStyles = StyleSheet.create({
   },
   wrap: {
     flex: 1
+  },
+  bulletPositioning: {
+    alignItems: 'center',
+    justifyContent: 'center'
   }
 })
 

package/src/Search/Search.jsx

@@ -1,4 +1,4 @@
-import React, { forwardRef, useState } from 'react'
+import React, { forwardRef } from 'react'
 import { View, StyleSheet } from 'react-native'
 
 import PropTypes from 'prop-types'
@@ -8,7 +8,10 @@ import {
   getTokensPropType,
   selectSystemProps,
   selectTokens,
+  useInputValue,
   useSpacingScale,
+  textInputHandlerProps,
+  textInputProps,
   variantProp,
   viewProps
 } from '../utils'
@@ -18,7 +21,11 @@ import StackView from '../StackView'
 import useCopy from '../utils/useCopy'
 import dictionary from './dictionary'
 
-const [selectProps, selectedSystemPropTypes] = selectSystemProps([a11yProps, viewProps])
+const [selectContainerProps, selectedContainerPropTypes] = selectSystemProps([a11yProps, viewProps])
+const [selectInputProps, selectedInputPropTypes] = selectSystemProps([
+  textInputHandlerProps,
+  textInputProps
+])
 
 const selectInputTokens = ({ searchTokens, buttonTokens, buttonsGapSize }) => {
   const { paddingRight: inputPaddingRight, clearButtonIcon, submitButtonIcon } = searchTokens
@@ -54,8 +61,9 @@ const selectIconTokens = ({ iconSize, iconColor }) => ({ color: iconColor, size:
 const Search = forwardRef(
   (
     {
-      initialValue = '',
-      placeholder = 'Search',
+      initialValue,
+      value,
+      placeholder,
       inactive,
       onChange,
       onSubmit,
@@ -68,7 +76,12 @@ const Search = forwardRef(
     },
     ref
   ) => {
-    const [value, setValue] = useState(initialValue)
+    const { currentValue = '', setValue } = useInputValue({
+      value,
+      initialValue,
+      onChange
+    })
+
     const themeTokens = useThemeTokens('Search', tokens, variant)
     const buttonTokens = useThemeTokens('SearchButton', tokens, variant)
 
@@ -90,28 +103,26 @@ const Search = forwardRef(
 
     const handleSubmit = (event) => {
       if (onSubmit !== undefined) {
-        onSubmit(value, event)
+        onSubmit(currentValue, 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 === ''
+    const isEmpty = currentValue === ''
+
+    // Accessibility label should always be present and correctly localised
+    const a11yLabelText = accessibilityLabel || getCopy('accessibilityLabel')
+    // Placeholder is optional and may be unset by passing an empty string
+    const placeholderText = placeholder ?? a11yLabelText
 
     return (
-      <View style={staticStyles.container} {...selectProps(rest)}>
+      <View style={staticStyles.container} {...selectContainerProps(rest)}>
         <TextInputBase
+          {...selectInputProps(rest)}
           ref={ref}
           tokens={(appearances) =>
             selectInputTokens({
@@ -121,15 +132,15 @@ const Search = forwardRef(
               isEmpty
             })
           }
-          placeholder={placeholder}
+          placeholder={placeholderText}
           placeholderTextColor={placeholderColor}
           inactive={inactive}
           enablesReturnKeyAutomatically
           returnKeyType="search"
-          value={value}
-          onChange={handleChange}
+          value={currentValue}
+          onChange={setValue}
           onSubmitEditing={handleSubmit}
-          accessibilityLabel={accessibilityLabel || getCopy('accessibilityLabel')}
+          accessibilityLabel={a11yLabelText}
         />
         <View style={[staticStyles.iconsContainer, selectIconsContainerStyle(themeTokens)]}>
           <StackView direction="row" space={buttonsGap}>
@@ -172,7 +183,8 @@ const Search = forwardRef(
 Search.displayName = 'Search'
 
 Search.propTypes = {
-  ...selectedSystemPropTypes,
+  ...selectedContainerPropTypes,
+  ...selectedInputPropTypes,
   /**
    * Use this to set the initial value of the search input.
    * Updating `initialValue` will **not** update the actual value.

package/src/TextInput/TextArea.jsx

@@ -8,6 +8,7 @@ import {
   inputSupportsProps,
   selectSystemProps,
   textInputHandlerProps,
+  textInputProps,
   variantProp,
   viewProps
 } from '../utils'
@@ -21,6 +22,7 @@ const [selectProps, selectedSystemPropTypes] = selectSystemProps([
   focusHandlerProps,
   inputSupportsProps,
   textInputHandlerProps,
+  textInputProps,
   viewProps
 ])
 

package/src/TextInput/TextInput.jsx

@@ -7,6 +7,7 @@ import {
   inputSupportsProps,
   selectSystemProps,
   textInputHandlerProps,
+  textInputProps,
   variantProp,
   viewProps
 } from '../utils'
@@ -19,6 +20,7 @@ const [selectProps, selectedSystemPropTypes] = selectSystemProps([
   focusHandlerProps,
   inputSupportsProps,
   textInputHandlerProps,
+  textInputProps,
   viewProps
 ])
 

package/src/TextInput/TextInputBase.jsx

@@ -8,6 +8,7 @@ import {
   getTokensPropType,
   selectSystemProps,
   textInputHandlerProps,
+  textInputProps,
   useInputValue,
   variantProp,
   viewProps
@@ -16,6 +17,7 @@ import {
 const [selectProps, selectedSystemPropTypes] = selectSystemProps([
   a11yProps,
   textInputHandlerProps,
+  textInputProps,
   viewProps
 ])
 

package/src/Typography/Typography.jsx

@@ -13,6 +13,7 @@ import {
   headingTags,
   selectSystemProps,
   textTags,
+  textProps,
   viewProps,
   getA11yPropsFromHtmlTag
 } from '../utils'
@@ -20,7 +21,8 @@ import {
  * @typedef {import('../utils/a11y/semantics').TextTag} TextTag
  */
 
-const [selectProps, selectedSystemPropTypes] = selectSystemProps([a11yProps, viewProps])
+const [selectContainerProps, selectedContainerPropTypes] = selectSystemProps([a11yProps, viewProps])
+const [selectTextProps, selectedTextPropTypes] = selectSystemProps([textProps])
 
 const selectTextStyles = ({
   fontWeight,
@@ -62,23 +64,24 @@ const Typography = forwardRef(
   ) => {
     const viewport = useViewport()
     const themeTokens = useThemeTokens('Typography', tokens, variant, { viewport })
-    const textProps = {
+    const resolvedTextProps = {
+      ...selectTextProps(rest),
       style: selectTextStyles(align ? { ...themeTokens, textAlign: align } : themeTokens),
       dataSet,
       maxFontSizeMultiplier: getMaxFontMultiplier(themeTokens)
     }
 
-    const selectedProps = selectProps({
+    const containerProps = {
       ...getA11yPropsFromHtmlTag(tag, accessibilityRole),
-      ...rest
-    })
+      ...selectContainerProps(rest)
+    }
 
     return block ? (
-      <View ref={ref} {...selectedProps}>
-        <Text {...textProps}>{children}</Text>
+      <View ref={ref} {...containerProps}>
+        <Text {...resolvedTextProps}>{children}</Text>
       </View>
     ) : (
-      <Text ref={ref} {...textProps} {...selectedProps}>
+      <Text ref={ref} {...containerProps} {...resolvedTextProps}>
         {children}
       </Text>
     )
@@ -87,7 +90,8 @@ const Typography = forwardRef(
 Typography.displayName = 'Typography'
 
 Typography.propTypes = {
-  ...selectedSystemPropTypes,
+  ...selectedContainerPropTypes,
+  ...selectedTextPropTypes,
   tokens: getTokensPropType('Typography'),
   variant: variantProp.propType,
   /**

package/src/index.js

@@ -50,7 +50,10 @@ export {
   useTheme,
   useSetTheme,
   useThemeTokens,
-  getThemeTokens
+  getThemeTokens,
+  applyOuterBorder,
+  applyTextStyles,
+  applyShadowToken
 } from './ThemeProvider'
 
 export * from './utils'

package/src/utils/input.js

@@ -1,4 +1,7 @@
 import { useCallback, useRef, useState } from 'react'
+/**
+ * @typedef {import('react').SyntheticEvent} Event
+ */
 
 const pluralHooks = ['useMultipleInputValues']
 
@@ -51,16 +54,13 @@ Consumers of this hook must be one of:
  *
  * @param {string} hookName - optional, used for tailoring error messages
  *
- * @typedef {(oldValue: string|number|null) => string|number|null} UpdaterFunction - `setValue` takes a value or
- *          a function returning a new value from the old value
  * @returns {{
  *   currentValue: string|number|null
- *   setValue: (newValue: string|number|null|UpdaterFunction) => void
+ *   setValue: (newValue: string|number|null|(oldValue: string|number) => string|number, event: Event) => void
  *   resetValue: () => void
  *   isControlled: bool
  * }}
  */
-
 export const useInputValue = (props = {}, hookName = 'useInputValue') => {
   const isCurrentlyControlled = props.value !== undefined
   const [isControlled] = useState(isCurrentlyControlled)
@@ -108,12 +108,10 @@ export const useInputValue = (props = {}, hookName = 'useInputValue') => {
  *
  * @param {string} componentName - optional, used in error messages
  *
- * @typedef {(oldValues: string[]|number[]) => string[]|number[]} UpdaterFunction - `setValues` takes values or
- *          a function returning new values from old values
  * @returns {{
  *   currentValues: any
  *   resetValues: () => void
- *   setValues: (newValues: string[]|number[]|UpdaterFunction) => void
+ *   setValues: (newValues: string[]|number[]|(oldValues: string[]|number[]) => string[]|number[], event: Event) => void
  *   toggleOneValue: (value: string|number) => void
  *   unsetValues: () => void
  * }}

package/src/utils/props/index.js

@@ -13,5 +13,7 @@ export { default as rectProp } from './rectProp'
 export { default as responsiveProps } from './responsiveProps'
 export { default as spacingProps } from './spacingProps'
 export { default as selectSystemProps } from './selectSystemProps'
+export { default as textInputProps } from './textInputProps'
+export { default as textProps } from './textProps'
 export { default as variantProp } from './variantProp'
 export { default as viewProps } from './viewProps'