@telus-uds/components-base 1.6.1 → 1.8.0

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'

package/src/utils/props/inputSupportsProps.js

@@ -2,6 +2,10 @@ import PropTypes from 'prop-types'
 
 export default {
   types: {
+    /**
+     * Whether the English or French copy will be used (e.g. for accessibility labels).
+     */
+    copy: PropTypes.oneOf(['en', 'fr']),
     /**
      * The input label.
      */
@@ -28,8 +32,9 @@ export default {
      */
     validation: PropTypes.oneOf(['error', 'success'])
   },
-  select: ({ label, hint, hintPosition, feedback, tooltip, validation }) => ({
+  select: ({ copy, label, hint, hintPosition, feedback, tooltip, validation }) => ({
     supportsProps: {
+      copy,
       label,
       hint,
       hintPosition,

package/src/utils/props/textInputProps.js

@@ -0,0 +1,178 @@
+import PropTypes from 'prop-types'
+import { Platform } from 'react-native'
+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,
+  inactive: 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/src/utils/props/textProps.js

@@ -0,0 +1,58 @@
+import PropTypes from 'prop-types'
+import { Platform } from 'react-native'
+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/src/utils/props/tokens.js

@@ -86,33 +86,35 @@ export const selectTokens = (specifier, tokens, prefix) => {
  *   tokens: getTokensPropType('Component1', 'Component2')
  * }
  */
-export const getTokensPropType = (...componentsNames) => (props, propName, componentName) => {
-  PropTypes.checkPropTypes(
-    {
-      [propName]: PropTypes.oneOfType([PropTypes.object, PropTypes.func])
-    },
-    props,
-    propName,
-    componentName
-  )
-
-  if (typeof props[propName] !== 'function') {
+export const getTokensPropType =
+  (...componentsNames) =>
+  (props, propName, componentName) => {
     PropTypes.checkPropTypes(
       {
-        [propName]: PropTypes.exact(
-          Object.fromEntries(
-            componentsNames.flatMap((component) =>
-              getTokenNames(component).map((key) => [key, tokenValueType])
-            )
-          )
-        )
+        [propName]: PropTypes.oneOfType([PropTypes.object, PropTypes.func])
       },
       props,
       propName,
       componentName
     )
+
+    if (typeof props[propName] !== 'function') {
+      PropTypes.checkPropTypes(
+        {
+          [propName]: PropTypes.exact(
+            Object.fromEntries(
+              componentsNames.flatMap((component) =>
+                getTokenNames(component).map((key) => [key, tokenValueType])
+              )
+            )
+          )
+        },
+        props,
+        propName,
+        componentName
+      )
+    }
   }
-}
 
 /**
  * Get a proptypes validator for a set of tokens that is not based on a component in the theme schema.

package/stories/Search/Search.stories.jsx

@@ -1,6 +1,7 @@
-import React from 'react'
+/* eslint-disable react/no-multi-comp */
+import React, { useRef, useState } from 'react'
 
-import { Search } from '../../src'
+import { Search, StackView, TextButton, Typography, List, ListItem } from '../../src'
 
 export default {
   title: 'Search',
@@ -17,3 +18,49 @@ Default.args = {}
 
 export const Inactive = Template.bind({})
 Inactive.args = { inactive: true }
+
+// Lots of smartphone brands. No need to make the file really long, let them sit on one line.
+// eslint-disable-next-line prettier/prettier
+const options = ['Acer', 'Aermoo', 'AGM', 'Alcatel', 'Allcall', 'Allview', 'Amigoo', 'Amoi', 'Apple', 'Archos', 'Asus', 'Axgio', 'Black Shark', 'BlackBerry', 'Blackview', 'BLU', 'Bluboo', 'BQ', 'Bsimb', 'Cagabi', 'Cat', 'Caterpillar', 'Centric', 'China Mobile', 'Cong', 'Coolpad', 'Cubot', 'Dakele', 'Doogee', 'Doopro', 'E&L', 'Ecoo', 'Elephone', 'Energizer', 'Energy', 'Essential', 'EStar', 'Faea', 'Fairphone', 'Geotel', 'Gigabyte', 'Gigaset', 'Gionee', 'Gome', 'Google', 'Goophone', 'Gretel', 'Hafury', 'Haier', 'Hike', 'HiSense', 'HomTom', 'Honor', 'HP', 'HTC', 'Huawei', 'I Kall', 'iiiF150', 'iLA', 'iMan', 'iNew', 'Infinix', 'InFocus', 'InnJoo', 'Innos', 'Intex', 'iOcean', 'iRULU', 'IUNI', 'iVooMi', 'Jesy', 'Jiake', 'Jiayu', 'Karbonn', 'Kazam', 'Keecoo', 'Kenxinda', 'KingSing', 'KingZone', 'Kodak', 'Kolina', 'Koolnee', 'Landvo', 'Laude', 'Lava', 'Leagoo', 'LeEco (LeTV)', 'Lenovo', 'Leotec', 'LeRee', 'LG', 'Ly', 'Lyf', 'M-Horse', 'M-Net', 'Mann', 'Maze', 'Meiigoo', 'Meitu', 'Meizu', 'Micromax', 'Microsoft', 'Mijue', 'Milai', 'Mlais', 'Morefine', 'Motorola', 'Mpie', 'Mstar', 'MyWigo', 'Neken', 'Neo', 'Newman', 'NO.1', 'Noa', 'Nokia', 'Nomu', 'Nubia', 'Nubia Red Magic', 'NZone', 'OnePlus', 'Oppo', 'Otium', 'Oukitel', 'Palm', 'Panasonic', 'Pantech', 'Pepsi', 'Phicomm', 'Philips', 'Phonemax', 'Plunk', 'POCO', 'Pomp', 'Poptel', 'PPTV', 'Prestigio', 'Qiku', 'Ramos', 'Razer', 'realme', 'Runbo', 'Samsung', 'Sharp', 'Silent Circle', 'Siswoo', 'Smartisan', 'Snopow', 'Sony', 'Sony Ericsson', 'Star', 'Swipe', 'TCL', 'Tengda', 'THL', 'Tianhe', 'Timmy', 'TP-Link', 'Ubro', 'Uhans', 'Uhappy', 'Uimi', 'Ukozi', 'Ulefone', 'UMi', 'UMiDIGI', 'Vargo', 'Vernee', 'ViewSonic', 'Vivo', 'VKworld', 'Voto', 'VPhone', 'Vsmart', 'Weimei', 'Wico', 'Wiko', 'Wileyfox', 'Wolder', 'Woxter', 'Xiaomi', 'Xolo', 'Yota Devices', 'YU', 'Zoji', 'Zopo', 'ZTE', 'Zuk']
+
+export const Controlled = (args) => {
+  const [value, setValue] = useState('')
+  const [searchedValue, setSearchedValue] = useState(null)
+  const searchRef = useRef()
+  const selectOption = (option) => {
+    setValue(option)
+    if (searchRef.current?.focus) searchRef.current?.focus()
+  }
+
+  return (
+    <StackView space={4}>
+      {searchedValue ? (
+        <>
+          <Typography>Search results page for {searchedValue}.</Typography>
+          <Typography>{searchedValue} phones are really good. You should buy one.</Typography>
+          <TextButton onPress={() => setSearchedValue(null)}>Go back</TextButton>
+        </>
+      ) : (
+        <>
+          <Search
+            {...args}
+            value={value}
+            onChange={setValue}
+            ref={searchRef}
+            onSubmit={setSearchedValue}
+          />
+          <List>
+            {options
+              .filter((option) => !value || option.toLowerCase().match(value.toLowerCase()))
+              .map((option) => (
+                <ListItem key={option}>
+                  <TextButton onPress={() => selectOption(option)}>{option}</TextButton>
+                </ListItem>
+              ))}
+          </List>
+        </>
+      )}
+    </StackView>
+  )
+}
+Controlled.args = {}

package/stories/Tabs/Tabs.stories.jsx

@@ -40,9 +40,10 @@ TabsWithHref.args = {
   ]
 }
 
-const loremIpsumArray = 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum. '
-  .repeat(5)
-  .split('. ')
+const loremIpsumArray =
+  'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum. '
+    .repeat(5)
+    .split('. ')
 
 export const TabsControlled = (args) => {
   const [page, setPage] = useState('1')