@telus-uds/components-base 1.60.0 → 1.61.0

package/src/Autocomplete/Autocomplete.jsx

@@ -0,0 +1,411 @@
+/* eslint-disable react/require-default-props */
+import React, { forwardRef, useRef, useState } from 'react'
+import PropTypes from 'prop-types'
+import { Dimensions, Platform, View, StyleSheet } from 'react-native'
+import throttle from 'lodash.throttle'
+import matchAll from 'string.prototype.matchall'
+import {
+  inputSupportsProps,
+  selectSystemProps,
+  textInputProps,
+  textInputHandlerProps,
+  useCopy,
+  htmlAttrs,
+  useOverlaidPosition,
+  useSafeLayoutEffect
+} from '../utils'
+import { useThemeTokens } from '../ThemeProvider'
+import Listbox from '../Listbox'
+import Typography from '../Typography'
+import { TextInput } from '../TextInput'
+import InputSupports from '../InputSupports'
+import Loading from './Loading'
+import Suggestions from './Suggestions'
+import {
+  DEFAULT_MAX_SUGGESTIONS,
+  DEFAULT_MIN_TO_SUGGESTION,
+  INPUT_LEFT_PADDING,
+  MIN_LISTBOX_WIDTH
+} from './constants'
+import dictionary from './dictionary'
+
+const staticStyles = StyleSheet.create({
+  container: {
+    zIndex: 100,
+    flexDirection: 'column',
+    justifyContent: 'flex-start',
+    flexGrow: 0,
+    flexShrink: 0
+  }
+})
+
+const [selectProps, selectedSystemPropTypes] = selectSystemProps([
+  htmlAttrs,
+  inputSupportsProps,
+  textInputHandlerProps,
+  textInputProps
+])
+
+// Returns JSX to display a bold string `str` with unbolded occurrences of the
+// `substring` based in the array of `matchIndexes` provided
+const highlightAllMatches = (str, substring = '', matchIndexes = [], resultsTextColor) => (
+  // Wrapping all in bold
+  <Typography variant={{ bold: false }} tokens={{ color: resultsTextColor }}>
+    {matchIndexes.reduce(
+      (acc, matchIndex, index) => [
+        ...acc,
+        // Add a piece of the string up to the first occurrence of the substring
+        index === 0 && (str.slice(0, matchIndex) ?? ''),
+        // Unbold the occurrence of the substring (while keeping the original casing)
+        <Typography key={matchIndex} variant={{ bold: true }} tokens={{ color: resultsTextColor }}>
+          {str.slice(matchIndex, matchIndex + substring.length)}
+        </Typography>,
+        // Add the rest of the string until the next occurrence or the end of it
+        str.slice(matchIndex + substring.length, matchIndexes[index + 1] ?? str.length)
+      ],
+      []
+    )}
+  </Typography>
+)
+const highlight = (items = [], text = '', color) =>
+  items.reduce((acc, item) => {
+    const matches = Array.from(
+      matchAll(
+        item.label.toLowerCase(),
+        text.toLowerCase().replace(/[/\-\\^$*+?.()|[\]{}]/g, '\\$&')
+      )
+    )?.map(({ index }) => index)
+
+    if (matches?.length) {
+      return [...acc, { ...item, label: highlightAllMatches(item.label, text, matches, color) }]
+    }
+
+    return [...acc, item]
+  }, [])
+
+const Autocomplete = forwardRef(
+  (
+    {
+      children,
+      copy = 'en',
+      fullWidth = true,
+      initialItems,
+      initialValue,
+      isLoading = false,
+      items,
+      maxSuggestions = DEFAULT_MAX_SUGGESTIONS,
+      minToSuggestion = DEFAULT_MIN_TO_SUGGESTION,
+      noResults,
+      onChange,
+      onClear,
+      onSelect,
+      readOnly,
+      validation,
+      value,
+      helpText = '',
+      ...rest
+    },
+    ref
+  ) => {
+    const { color: resultsTextColor } = useThemeTokens('Search', {}, { focus: true })
+    // The wrapped input is mostly responsible for controlled vs uncontrolled handling,
+    // but we also need to adjust suggestions based on the mode:
+    // - in controlled mode we rely entirely on the suggestions passed via the `items` prop,
+    // - in uncontrolled mode we filter the suggestions ourselves based on the `initialItems`
+    //   prop and the text entered
+    const isControlled = value !== undefined
+
+    // We need to store current items for uncontrolled usage
+    const [currentItems, setCurrentItems] = useState(initialItems)
+
+    // We need to store the current value as well to be able to highlight it
+    const [currentValue, setCurrentValue] = useState(value ?? initialValue)
+    const inputTokens = { paddingLeft: INPUT_LEFT_PADDING }
+
+    // Setting up the overlay
+    const openOverlayRef = useRef()
+    const [isExpanded, setIsExpanded] = useState((value ?? initialValue)?.length >= minToSuggestion)
+    const [isFocused, setisFocused] = useState(false)
+    const [sourceLayout, setSourceLayout] = useState(null)
+
+    const { supportsProps, ...selectedProps } = selectProps(rest)
+    const { hint, label: inputLabel } = supportsProps
+    const hintExpansionEnabled = isFocused && helpText && !currentValue
+    const {
+      overlaidPosition,
+      sourceRef: inputRef,
+      // targetRef,
+      onTargetLayout,
+      isReady
+    } = useOverlaidPosition({
+      isShown: isExpanded || hintExpansionEnabled,
+      offsets: {
+        vertical: Platform.OS !== 'web' && (hint || inputLabel) ? 28 : 4
+      }
+    })
+    const targetRef = useRef(null)
+    // We limit the number of suggestions displayed to avoid huge lists
+    // TODO: add a way to make the `Listbox` occupy fixed height and be scrollable
+    // within that height, which will unlock similar behaviour for `AutoComplete` as well
+    const itemsToSuggest = (data = []) =>
+      maxSuggestions ? data.slice(0, maxSuggestions) : [...data]
+
+    const getCopy = useCopy({ dictionary, copy })
+    // Tracking input width changes to resize the listbox overlay accordingly
+    const [inputWidth, setInputWidth] = useState()
+    useSafeLayoutEffect(() => {
+      if (Platform.OS === 'web') {
+        const updateInputWidth = () => {
+          setInputWidth(inputRef?.current?.clientWidth + 4) // adding back all the input borders / outlines
+          setIsExpanded(false) // close the suggestions while the input is changing
+        }
+
+        const throttledUpdateInputWidth = throttle(updateInputWidth, 100, { leading: false })
+
+        updateInputWidth()
+
+        Dimensions.addEventListener('change', throttledUpdateInputWidth)
+
+        return () => {
+          Dimensions.removeEventListener('change', throttledUpdateInputWidth)
+        }
+      }
+      setInputWidth(sourceLayout?.width)
+      return () => {}
+    }, [inputRef, sourceLayout])
+
+    const handleMeasure = (event) => {
+      onTargetLayout(event)
+      if (Platform.OS !== 'web') {
+        inputRef?.current?.measureInWindow((x, y, width) => {
+          setInputWidth(width)
+        })
+      }
+    }
+
+    const handleChange = (newValue) => {
+      onChange?.(newValue || '')
+      setCurrentValue(newValue)
+      setIsExpanded(newValue?.length >= minToSuggestion)
+      if (!isControlled && initialItems !== undefined) {
+        setCurrentItems(
+          initialItems.filter(({ label }) =>
+            label?.toLowerCase()?.includes(newValue?.toLowerCase())
+          )
+        )
+      }
+    }
+    const handleSelect = (selectedId) => {
+      onSelect?.(selectedId)
+      const { label: newValue, nested } = (isControlled ? items : currentItems)?.find(
+        ({ id }) => id === selectedId
+      )
+      if (!nested) {
+        onChange?.(newValue)
+        setIsExpanded(false)
+      }
+      setCurrentValue(newValue)
+      if (!isControlled && inputRef?.current) inputRef.current.value = newValue
+    }
+
+    const handleClose = (event) => {
+      if (event.type === 'keydown') {
+        if (event.key === 'Escape' || event.key === 27) {
+          setIsExpanded(false)
+        } else if (event.key === 'ArrowDown' && isExpanded && !isLoading && targetRef?.current) {
+          targetRef.current.focus()
+        }
+      } else if (
+        event.type === 'click' &&
+        openOverlayRef?.current &&
+        event.target &&
+        !openOverlayRef?.current?.contains(event.target)
+      ) {
+        setIsExpanded(false)
+      } else if (
+        event.type === 'touchstart' &&
+        openOverlayRef?.current &&
+        event.touches[0].target &&
+        !openOverlayRef?.current?.contains(event.touches[0].target)
+      ) {
+        setIsExpanded(false)
+      } else if (Platform.OS === 'web') {
+        // needed for dropdown to be collapsed when clicking outside on web
+        setIsExpanded(false)
+      }
+    }
+    const itemsToShow = currentValue
+      ? itemsToSuggest(
+          highlight(isControlled ? items : currentItems, currentValue, resultsTextColor)
+        )
+      : []
+    const helpTextToShow = isFocused && !currentValue ? helpText : noResults ?? getCopy('noResults')
+
+    return (
+      <View style={staticStyles.container}>
+        <InputSupports
+          {...supportsProps}
+          accessibilityAutoComplete="list"
+          accessibilityControls="autocomplete"
+          accessibilityExpanded={isExpanded}
+          accessibilityRole="combobox"
+          {...selectedProps}
+          validation={validation}
+          ref={ref}
+        >
+          {({ inputId, ...props }) => {
+            if (typeof children === 'function')
+              return children({
+                inputId,
+                inputRef,
+                onChange: handleChange,
+                onKeyPress: handleClose,
+                readOnly,
+                tokens: inputTokens,
+                ...selectedProps,
+                ...props,
+                ...(isControlled ? { value } : { initialValue })
+              })
+
+            return (
+              <TextInput
+                onChange={handleChange}
+                onFocus={() => {
+                  setisFocused(true)
+                }}
+                onBlur={() => {
+                  setisFocused(false)
+                }}
+                onClear={onClear}
+                onKeyPress={handleClose}
+                readOnly={readOnly}
+                ref={inputRef}
+                {...(Platform.OS !== 'web'
+                  ? { onLayout: (event) => setSourceLayout(event.nativeEvent.layout) }
+                  : {})}
+                tokens={inputTokens}
+                validation={validation}
+                {...selectedProps}
+                {...props}
+                {...(isControlled ? { value } : { initialValue })}
+              />
+            )
+          }}
+        </InputSupports>
+        {(isExpanded || hintExpansionEnabled) && (
+          <>
+            <Listbox.Overlay
+              overlaidPosition={overlaidPosition}
+              isReady={isReady}
+              minWidth={fullWidth ? inputWidth : MIN_LISTBOX_WIDTH}
+              maxWidth={inputWidth}
+              onLayout={handleMeasure}
+              ref={openOverlayRef}
+            >
+              {isLoading ? (
+                <Loading label={getCopy('loading')} />
+              ) : (
+                <Suggestions
+                  hasResults={getCopy('hasResults')}
+                  id="autocomplete"
+                  items={itemsToShow}
+                  noResults={helpTextToShow}
+                  onClose={handleClose}
+                  onSelect={handleSelect}
+                  parentRef={inputRef}
+                  ref={targetRef}
+                />
+              )}
+            </Listbox.Overlay>
+            {targetRef?.current && (
+              <View
+                // This catches and shifts focus to other interactive elements.
+                onFocus={() => targetRef?.current?.focus()}
+                tabIndex={0}
+              />
+            )}
+          </>
+        )}
+      </View>
+    )
+  }
+)
+Autocomplete.displayName = 'Autocomplete'
+
+// If a language dictionary entry is provided, it must contain every key
+const dictionaryContentShape = PropTypes.shape({
+  hasResults: PropTypes.string.isRequired,
+  loading: PropTypes.string.isRequired,
+  noResults: PropTypes.string.isRequired
+})
+
+Autocomplete.propTypes = {
+  ...selectedSystemPropTypes,
+  /**
+   * Can be used to provide a function that renders a custom input:
+   * <Autocomplete items={items} value={currentValue}>
+   *   {({ inputId, inputRef, onChange, onKeyPress, readOnly, tokens, value }) => (
+   *     <Search
+   *       nativeID={inputId}
+   *       ref={inputRef}
+   *       onChange={onChange}
+   *       onKeyPress={onKeyPress}
+   *       readOnly={readOnly}
+   *       tokens={tokens}
+   *       value={value}
+   *     />
+   *   )}
+   * </Autocomplete>
+   */
+  children: PropTypes.func,
+  /**
+   * Copy language identifier
+   */
+  copy: PropTypes.oneOfType([PropTypes.oneOf(['en', 'fr']), dictionaryContentShape]),
+  /**
+   * Set to true in order to display the loading indicator instead of results
+   */
+  isLoading: PropTypes.bool,
+  /**
+   * List of items to display as suggestions
+   */
+  items: PropTypes.arrayOf(PropTypes.shape({ id: PropTypes.string, label: PropTypes.string })),
+  /**
+   * Label to display alongside the spinner when in a loading state
+   */
+  loadingLabel: PropTypes.string,
+  /**
+   * Minimum number of characters typed for a list of suggestions to appear
+   */
+  minToSuggestion: PropTypes.number,
+  /**
+   * Maximum number of suggestions provided at the same time
+   */
+  maxSuggestions: PropTypes.number,
+  /**
+   * Text or JSX to render when no results are available
+   */
+  noResults: PropTypes.node,
+  /**
+   * Help text to display when the input is focused and empty
+   */
+  helpText: PropTypes.string,
+  /**
+   * Handler function to be called when the input value changes
+   */
+  onChange: PropTypes.func,
+  /**
+   * Handler function to be called when the clear button (appears if the handler is passed) is pressed
+   */
+  onClear: PropTypes.func,
+  /**
+   * Callback function to be called when an item is selected from the list
+   */
+  onSelect: PropTypes.func,
+  /**
+   * Input value for controlled usage
+   */
+  value: PropTypes.string
+}
+
+export default Autocomplete

package/src/Autocomplete/Loading.jsx

@@ -0,0 +1,18 @@
+import React from 'react'
+import PropTypes from 'prop-types'
+import ActivityIndicator from '../ActivityIndicator'
+import Typography from '../Typography'
+import Box from '../Box'
+import StackView from '../StackView'
+
+const Loading = ({ label }) => (
+  <Box space={3}>
+    <StackView direction="row" space={2} tokens={{ alignItems: 'center' }}>
+      <ActivityIndicator variant={{ size: 'large' }} />
+      <Typography>{label}</Typography>
+    </StackView>
+  </Box>
+)
+Loading.propTypes = { label: PropTypes.string }
+
+export default Loading

package/src/Autocomplete/Suggestions.jsx

@@ -0,0 +1,54 @@
+import React, { forwardRef } from 'react'
+import PropTypes from 'prop-types'
+import A11yText from '../A11yText'
+import Typography from '../Typography'
+import Box from '../Box'
+import Listbox from '../Listbox'
+
+const Suggestions = forwardRef(
+  ({ hasResults, items = [], noResults, onClose, onSelect, parentRef }, ref) => {
+    const pressableItems = items.map(({ id, ...rest }) => ({
+      id,
+      onPress: () => onSelect(id),
+      ...rest
+    }))
+    if (items?.length)
+      return (
+        <>
+          <A11yText accessibilityLiveRegion="polite" text={hasResults} />
+          <Listbox
+            items={pressableItems}
+            firstItemRef={ref}
+            parentRef={parentRef}
+            onClose={onClose}
+          />
+        </>
+      )
+
+    return (
+      <Box space={3}>
+        {typeof noResults === 'string' ? (
+          <>
+            <Typography accessibilityLiveRegion="polite" variant={{ size: 'small' }}>
+              {noResults}
+            </Typography>
+          </>
+        ) : (
+          noResults
+        )}
+      </Box>
+    )
+  }
+)
+Suggestions.displayName = 'Suggestions'
+Suggestions.propTypes = {
+  hasResults: PropTypes.string.isRequired,
+  items: PropTypes.arrayOf(PropTypes.shape({ id: PropTypes.string, label: PropTypes.node }))
+    .isRequired,
+  noResults: PropTypes.node.isRequired,
+  onClose: PropTypes.func.isRequired,
+  onSelect: PropTypes.func.isRequired,
+  parentRef: PropTypes.object.isRequired
+}
+
+export default Suggestions

package/src/Autocomplete/constants.js

@@ -0,0 +1,4 @@
+export const DEFAULT_MIN_TO_SUGGESTION = 1
+export const DEFAULT_MAX_SUGGESTIONS = 5
+export const INPUT_LEFT_PADDING = 16
+export const MIN_LISTBOX_WIDTH = 288

package/src/Autocomplete/dictionary.js

@@ -0,0 +1,12 @@
+export default {
+  en: {
+    hasResults: 'Some results are available',
+    loading: 'Searching...',
+    noResults: 'No results found'
+  },
+  fr: {
+    hasResults: 'Quelques suggestions sont disponible',
+    loading: 'Recherche...',
+    noResults: 'Aucun résultat trouvé'
+  }
+}

package/src/Autocomplete/index.js

@@ -0,0 +1,3 @@
+import Autocomplete from './Autocomplete'
+
+export default Autocomplete

package/src/Listbox/GroupControl.jsx

@@ -0,0 +1,93 @@
+import React from 'react'
+import PropTypes from 'prop-types'
+import { View, StyleSheet, Text } from 'react-native'
+import { useThemeTokens } from '../ThemeProvider'
+import Icon from '../Icon'
+import Spacer from '../Spacer'
+import { useListboxContext } from './ListboxContext'
+
+const styles = StyleSheet.create({
+  controlWrapper: {
+    width: '100%',
+    flex: 1,
+    alignItems: 'center',
+    flexDirection: 'row',
+    justifyContent: 'space-between',
+    boxSizing: 'border-box'
+  }
+})
+
+const GroupControl = ({ expanded, pressed, hover, focus, label, id }) => {
+  const { selectedId, setSelectedId } = useListboxContext()
+  const tokens = useThemeTokens(
+    'Listbox',
+    {},
+    {},
+    {
+      expanded,
+      pressed,
+      hover,
+      current: selectedId === id && id !== undefined,
+      focus
+    }
+  )
+  const {
+    groupFontName,
+    groupFontWeight,
+    groupFontSize,
+    groupColor,
+    groupBackgroundColor,
+    groupBorderColor,
+    groupBorderWidth,
+    groupBorderRadius,
+    groupPaddingLeft,
+    groupPaddingRight,
+    groupPaddingTop,
+    groupPaddingBottom,
+    itemTextDecoration,
+    itemOutline,
+    groupHeight
+  } = tokens
+  return (
+    <View
+      onPress={() => setSelectedId(id)}
+      style={[
+        styles.controlWrapper,
+        {
+          fontFamily: `${groupFontName}${groupFontWeight}normal`,
+          fontSize: groupFontSize,
+          color: groupColor,
+          textDecoration: itemTextDecoration,
+          backgroundColor: groupBackgroundColor,
+          outline: itemOutline,
+          height: groupHeight,
+          border: `${groupBorderWidth}px solid ${groupBorderColor}`,
+          borderRadius: groupBorderRadius,
+          paddingLeft: groupPaddingLeft - groupBorderWidth,
+          paddingRight: groupPaddingRight - groupBorderWidth,
+          paddingTop: groupPaddingTop - groupBorderWidth,
+          paddingBottom: groupPaddingBottom - groupBorderWidth
+        }
+      ]}
+    >
+      <Text>{label}</Text>
+      <Spacer space={1} direction="row" />
+      <Icon
+        icon={tokens.groupIcon}
+        tokens={{ color: tokens.groupColor }}
+        variant={{ size: 'micro' }}
+      />
+    </View>
+  )
+}
+
+GroupControl.propTypes = {
+  id: PropTypes.string,
+  expanded: PropTypes.bool,
+  pressed: PropTypes.bool,
+  hover: PropTypes.bool,
+  focus: PropTypes.bool,
+  label: PropTypes.string
+}
+
+export default GroupControl