@telus-uds/components-base 2.0.0 → 2.0.2

package/src/ActivityIndicator/index.jsx

@@ -9,12 +9,21 @@ import Spinner from './Spinner'
  * `ActivityIndicator` renders a visual loading state.
  * It does not handle positioning or layout of that visual loader.
  */
-const ActivityIndicator = ({ variant, tokens, label, isStatic = false }) => {
+const ActivityIndicator = React.forwardRef(({ variant, tokens, label, isStatic = false }, ref) => {
   const { size, color, thickness } = useThemeTokens('ActivityIndicator', tokens, variant)
   return (
-    <Spinner size={size} color={color} thickness={thickness} label={label} isStatic={isStatic} />
+    <Spinner
+      ref={ref}
+      size={size}
+      color={color}
+      thickness={thickness}
+      label={label}
+      isStatic={isStatic}
+    />
   )
-}
+})
+
+ActivityIndicator.displayName = 'ActivityIndicator'
 
 ActivityIndicator.propTypes = {
   variant: variantProp.propType,

package/src/Autocomplete/Autocomplete.jsx

@@ -0,0 +1,486 @@
+import React 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 = React.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 = '',
+      loadingLabel,
+      ...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] = React.useState(initialItems)
+
+    const [otherItems, setOtherItems] = React.useState(items)
+
+    // We need to store the current value as well to be able to highlight it
+    const [currentValue, setCurrentValue] = React.useState(value ?? initialValue)
+    const inputTokens = { paddingLeft: INPUT_LEFT_PADDING }
+
+    // Setting up the overlay
+    const openOverlayRef = React.useRef()
+    const [isExpanded, setIsExpanded] = React.useState(
+      (value ?? initialValue)?.length >= minToSuggestion
+    )
+    const [isFocused, setisFocused] = React.useState(false)
+    const [sourceLayout, setSourceLayout] = React.useState(null)
+
+    // When it's nested, selected value
+    const [nestedSelectedValue, setNestedSelectedValue] = React.useState(null)
+
+    const [isInputVisible, setIsInputVisible] = React.useState(true)
+
+    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 = React.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] = React.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 })
+
+        throttledUpdateInputWidth()
+
+        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,
+        title
+      } = (isControlled ? items : currentItems)?.find(({ id }) => id === selectedId)
+      if (title) return
+      if (!nested) {
+        setNestedSelectedValue(null)
+        onChange?.(newValue)
+        setIsExpanded(false)
+      }
+      setCurrentValue(newValue)
+      if (!isControlled && inputRef?.current) inputRef.current.value = newValue
+
+      if (nested) setNestedSelectedValue(newValue)
+
+      inputRef.current.focus()
+    }
+
+    /**
+     * When an item that is nested equal "true" is selected this useEffect is executed.
+     * The nested item is added to the item list at the top, the if validates it doesn't exist
+     * within the list, if doesn't exist the nested item is added to the top of the list,
+     * the nested item is added with an id equal "0"
+     */
+    React.useEffect(() => {
+      if (nestedSelectedValue && !items.find((item) => item.id === 0)) {
+        const tmpItems = [...items]
+        tmpItems.unshift({ label: nestedSelectedValue, title: true, id: 0 })
+        setOtherItems(
+          tmpItems.map((item) => {
+            return {
+              ...item,
+              nestedChild: item.id !== 0
+            }
+          })
+        )
+      }
+    }, [nestedSelectedValue, items])
+
+    React.useEffect(() => {
+      if (Platform.OS === 'ios' || Platform.OS === 'android') {
+        return undefined
+      }
+
+      const observer = new IntersectionObserver((entries) => {
+        const [entry] = entries
+        setIsInputVisible(entry.isIntersecting)
+        if (!entry.isIntersecting) {
+          setIsExpanded(false)
+        }
+      })
+
+      const currentInputRef = inputRef.current
+
+      if (currentInputRef) {
+        observer.observe(currentInputRef)
+      }
+
+      return () => {
+        if (currentInputRef) {
+          observer.unobserve(currentInputRef)
+        }
+      }
+    }, [inputRef])
+
+    const handleClose = (event) => {
+      if (
+        (event.type === 'keydown' && (event.key === 'Escape' || event.key === '27')) ||
+        (event.type === 'click' && !openOverlayRef?.current?.contains(event.target)) ||
+        (event.type === 'touchstart' &&
+          openOverlayRef?.current &&
+          event.touches[0].target &&
+          !openOverlayRef?.current?.contains(event.touches[0].target))
+      ) {
+        setIsExpanded(false)
+        setNestedSelectedValue(null)
+      } else if (
+        event.type === 'keydown' &&
+        (event.key === 'ArrowDown' || event.key === 'Tab') &&
+        isExpanded &&
+        !isLoading &&
+        targetRef?.current
+      ) {
+        event.preventDefault()
+        targetRef.current.focus()
+      }
+    }
+    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)
+                        const { y, height } = event.nativeEvent.layout
+                        if (y >= 0 && height > 0) {
+                          setIsInputVisible(true)
+                        } else {
+                          setIsInputVisible(false)
+                          setIsExpanded(false)
+                        }
+                      }
+                    }
+                  : {})}
+                tokens={inputTokens}
+                validation={validation}
+                {...selectedProps}
+                {...props}
+                {...(isControlled ? { value } : { initialValue })}
+              />
+            )
+          }}
+        </InputSupports>
+        {(isExpanded || hintExpansionEnabled) && isInputVisible && (
+          <>
+            <Listbox.Overlay
+              overlaidPosition={overlaidPosition}
+              isReady={isReady}
+              minWidth={fullWidth ? inputWidth : MIN_LISTBOX_WIDTH}
+              maxWidth={inputWidth}
+              onLayout={handleMeasure}
+              ref={openOverlayRef}
+            >
+              {isLoading ? (
+                <Loading label={loadingLabel ?? getCopy('loading')} />
+              ) : (
+                <Suggestions
+                  hasResults={getCopy('hasResults')}
+                  id="autocomplete"
+                  items={
+                    nestedSelectedValue
+                      ? itemsToSuggest(highlight(otherItems, nestedSelectedValue, resultsTextColor))
+                      : 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,21 @@
+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 = React.forwardRef(({ label }, ref) => (
+  <Box space={3} ref={ref}>
+    <StackView direction="row" space={2} tokens={{ alignItems: 'center' }}>
+      <ActivityIndicator variant={{ size: 'large' }} />
+      <Typography>{label}</Typography>
+    </StackView>
+  </Box>
+))
+
+Loading.displayName = 'Loading'
+
+Loading.propTypes = { label: PropTypes.string }
+
+export default Loading

package/src/Autocomplete/Suggestions.jsx

@@ -0,0 +1,54 @@
+import React 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 = React.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/Badge/Badge.jsx

@@ -0,0 +1,76 @@
+import React from 'react'
+import { View, StyleSheet } from 'react-native'
+import PropTypes from 'prop-types'
+import { useThemeTokens } from '../ThemeProvider'
+import Typography from '../Typography'
+import { htmlAttrs, selectSystemProps, getTokensPropType, variantProp, viewProps } from '../utils'
+
+const fontSizeMapping = {
+  12: 'micro',
+  14: 'small',
+  16: 'h6'
+}
+
+const [selectProps, selectedSystemPropTypes] = selectSystemProps([htmlAttrs, viewProps])
+
+const selectContainerBackground = ({ backgroundColor }) => ({ backgroundColor })
+
+const selectContainerBorder = ({ borderWidth, borderColor, borderRadius }) => ({
+  borderWidth,
+  borderColor,
+  borderRadius
+})
+
+const selectContainerPadding = ({ paddingTop, paddingRight, paddingBottom, paddingLeft }) => ({
+  paddingTop,
+  paddingRight,
+  paddingBottom,
+  paddingLeft
+})
+
+const getTypographyTokens = ({ fontName, fontWeight, color }) => ({ fontName, fontWeight, color })
+
+const getTypographyVariant = ({ fontSize }) => ({ size: fontSizeMapping[fontSize] })
+
+const Badge = React.forwardRef(({ children, tokens, variant = {}, ...rest }, ref) => {
+  const themeTokens = useThemeTokens('Badge', tokens, variant)
+
+  return (
+    <View
+      ref={ref}
+      style={[
+        staticStyles.container,
+        selectContainerBackground(themeTokens),
+        selectContainerBorder(themeTokens),
+        selectContainerPadding(themeTokens)
+      ]}
+      {...selectProps(rest)}
+    >
+      <Typography
+        tokens={getTypographyTokens(themeTokens)}
+        variant={getTypographyVariant(themeTokens)}
+      >
+        {children}
+      </Typography>
+    </View>
+  )
+})
+
+Badge.propTypes = {
+  ...selectedSystemPropTypes,
+  children: PropTypes.node,
+  tokens: getTokensPropType('Badge'),
+  variant: variantProp.propType
+}
+
+Badge.displayName = 'Badge'
+
+export default Badge
+
+const staticStyles = StyleSheet.create({
+  container: {
+    display: 'flex',
+    justifyContent: 'center',
+    alignSelf: 'flex-start'
+  }
+})

package/src/Badge/index.js

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