@telus-uds/components-base 1.19.0 → 1.21.0

package/src/MultiSelectFilter/MultiSelectFilter.jsx

@@ -0,0 +1,227 @@
+import React, { forwardRef, useState } from 'react'
+import PropTypes from 'prop-types'
+
+import { useThemeTokensCallback } from '../ThemeProvider'
+import {
+  containUniqueFields,
+  getTokensPropType,
+  getPressHandlersWithArgs,
+  selectTokens,
+  useCopy,
+  useMultipleInputValues,
+  variantProp
+} from '../utils'
+import dictionary from './dictionary'
+
+import Box from '../Box'
+import { Button, ButtonDropdown } from '../Button'
+import { CheckboxGroup } from '../Checkbox'
+import Divider from '../Divider'
+import FlexGrid from '../FlexGrid'
+import Modal from '../Modal'
+import Spacer from '../Spacer'
+import StackView from '../StackView'
+import Typography from '../Typography'
+import { TextButton } from '../Link'
+
+const { Col, Row } = FlexGrid
+
+const MultiSelectFilter = forwardRef(
+  (
+    {
+      label,
+      id = label,
+      variant,
+      tokens,
+      items = [],
+      values,
+      initialValues,
+      maxValues,
+      onChange,
+      copy = 'en',
+      readOnly = false,
+      inactive = false,
+      rowLimit = 12,
+      ...rest
+    },
+    ref
+  ) => {
+    const { currentValues, setValues } = useMultipleInputValues({
+      initialValues,
+      values,
+      maxValues,
+      onChange,
+      readOnly
+    })
+
+    const getItemTokens = useThemeTokensCallback('ButtonDropdown', tokens, variant)
+    const getButtonTokens = (buttonState) => selectTokens('Button', getItemTokens(buttonState))
+    const getCopy = useCopy({ dictionary, copy })
+
+    const [isOpen, setIsOpen] = useState(false)
+    const [checkedIds, setCheckedIds] = useState(currentValues ?? [])
+
+    const colSize = items.length > rowLimit ? 2 : 1
+    const isSelected = currentValues.length > 0
+
+    const uniqueFields = ['id', 'label']
+    if (!containUniqueFields(items, uniqueFields)) {
+      throw new Error(`MultiSelectFilter items must have unique ${uniqueFields.join(', ')}`)
+    }
+
+    // Pass an object of relevant component state as first argument for any passed-in press handlers
+    const pressHandlers = getPressHandlersWithArgs(rest, [{ id, label, currentValues }])
+
+    const handleChange = (event) => {
+      if (pressHandlers.onPress) pressHandlers?.onPress(event)
+      setIsOpen(true)
+    }
+
+    const onApply = (e) => {
+      setValues(e)
+      setIsOpen(false)
+    }
+
+    return (
+      <>
+        <Modal
+          isOpen={isOpen}
+          onClose={() => setIsOpen(false)}
+          variant={{ width: colSize > 1 ? 'size576' : 's' }}
+        >
+          <Row>
+            <Typography variant={{ size: 'h4' }}>
+              {getCopy('filterByLabel').replace(/%\{filterCategory\}/g, label.toLowerCase())}
+            </Typography>
+          </Row>
+          <Spacer space={4} />
+          <Spacer space={1} />
+          <Box scroll={true}>
+            <Row distribute="between">
+              {[...Array(colSize).keys()].map((i) => (
+                <Col xs={12 / colSize} key={i}>
+                  <CheckboxGroup
+                    items={items.slice(i * rowLimit, (i + 1) * rowLimit)}
+                    checkedIds={checkedIds}
+                    onChange={(e) => setCheckedIds(e, i)}
+                  />
+                  <Spacer size={4} />
+                </Col>
+              ))}
+            </Row>
+          </Box>
+          <Divider
+            variant={{ width: 'full', color: 'E3E6E8', decorative: true, weight: 'thin' }}
+            space={4}
+          />
+          <Row>
+            <StackView direction="row" space={3} tokens={{ alignItems: 'center' }}>
+              <Button
+                onPress={() => onApply(checkedIds)}
+                variant={{ size: 'small', priority: 'high' }}
+              >
+                {getCopy('applyButtonLabel')}
+              </Button>
+              <Box>
+                <TextButton onPress={() => setCheckedIds([])}>
+                  {getCopy('clearButtonLabel')}
+                </TextButton>
+              </Box>
+            </StackView>
+          </Row>
+        </Modal>
+        <ButtonDropdown
+          ref={ref}
+          key={id}
+          {...pressHandlers}
+          value={isOpen}
+          selected={isSelected}
+          label={label}
+          onChange={handleChange}
+          tokens={getButtonTokens}
+          inactive={inactive}
+        />
+      </>
+    )
+  }
+)
+MultiSelectFilter.displayName = 'MultiSelectFilter'
+
+MultiSelectFilter.propTypes = {
+  /**
+   * The text displayed to the user in a ButtonDropdown.
+   */
+  label: PropTypes.string.isRequired,
+  /**
+   * An optional unique string may be provided to identify the ButtonDropdown.
+   * If not provided, the label is used.
+   */
+  id: PropTypes.string,
+  /**
+   * Sets the variant for ButtonDropdown element.
+   */
+  variant: variantProp.propType,
+  /**
+   * Sets the tokens for ButtonDropdown element.
+   */
+  tokens: getTokensPropType('ButtonDropdown'),
+  /**
+   * The options a user may select.
+   */
+  items: PropTypes.arrayOf(
+    PropTypes.shape({
+      /**
+       * The text displayed to the user with a checkbox, describing this option.
+       */
+      label: PropTypes.string.isRequired,
+      /**
+       * An optional unique string may be provided to identify this option.
+       * If not provided, the label is used.
+       */
+      id: PropTypes.string
+    })
+  ),
+  /**
+   * If the selected item(s) in the checkbox group(s) are to be controlled externally by
+   * a parent component, pass an array of strings as well as an `onChange` handler.
+   * Passing an array for "values" makes the MultiSelectFilter a "controlled" component that
+   * expects its state to be handled via `onChange` and so doesn't handle it itself.
+   */
+  values: PropTypes.arrayOf(PropTypes.string),
+  /**
+   * If `values` is not passed, making the MultiSelectFilter an "uncontrolled" component
+   * managing its own selected state, a default set of selections may be provided.
+   * Changing the `initialValues` does not change the user's selections.
+   */
+  initialValues: PropTypes.arrayOf(PropTypes.string),
+  /**
+   * If provided, sets a maximum number of items a user may select at once.
+   */
+  maxValues: PropTypes.number,
+  /**
+   * If provided, this function is called when the current selection is changed
+   * and is passed an array of the `id`s of all currently selected `items`.
+   */
+  onChange: PropTypes.func,
+  /**
+   * Select English or French copy for the accessible label.
+   */
+  copy: PropTypes.oneOf(['en', 'fr']),
+  /**
+   * If true, the ButtonDropdown cannot be selected by the user and simply show their current state.
+   */
+  readOnly: PropTypes.string,
+  /**
+   * If true, the MultiSelectFilter cannot be interacted with, ButtonDropdown is
+   * set as `disabled` and if the theme supports `inactive` appearances rules, these
+   * are applied.
+   */
+  inactive: PropTypes.string,
+  /**
+   * Sets the maximum number of items in one column. If number of items are more
+   * than the `rowLimit`, they will be rendered in 2 columns.
+   */
+  rowLimit: PropTypes.number
+}
+
+export default MultiSelectFilter

package/src/MultiSelectFilter/dictionary.js

@@ -0,0 +1,12 @@
+export default {
+  en: {
+    filterByLabel: 'Filter by %{filterCategory}:',
+    applyButtonLabel: 'Apply',
+    clearButtonLabel: 'Clear'
+  },
+  fr: {
+    filterByLabel: 'Filtrer par %{filterCategory}:',
+    applyButtonLabel: 'Appliquer',
+    clearButtonLabel: 'Effacer'
+  }
+}

package/src/MultiSelectFilter/index.js

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

package/src/Search/Search.jsx

@@ -108,7 +108,8 @@ const Search = forwardRef(
 
     const handleClear = (event) => {
       setValue('', event)
-      if (onClear !== undefined) onClear('', event)
+      onClear?.('', event)
+      ref?.current?.focus()
     }
 
     const handleFocus = (event) => {

package/src/Select/Picker.native.jsx

@@ -6,28 +6,43 @@ 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,
+import {
+  ANDROID_HEIGHT_OFFSET,
+  ANDROID_HORIZONTAL_PADDING_OFFSET,
+  ANDROID_DEFAULT_PADDING
+} from './constants'
+
+// Styling of the native input is very limited, most of the styles have to be applied to an additional View
+const selectAndroidInputStyles = ({ height = 0, color }) => ({
+  height,
+  paddingBottom: 0,
+  paddingTop: 0,
   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,
+// 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 = ANDROID_DEFAULT_PADDING,
+  paddingRight = ANDROID_DEFAULT_PADDING,
   ...rest
+}) => ({
+  ...rest,
+  paddingLeft:
+    paddingLeft > ANDROID_HORIZONTAL_PADDING_OFFSET
+      ? paddingLeft - ANDROID_HORIZONTAL_PADDING_OFFSET
+      : ANDROID_DEFAULT_PADDING,
+  paddingRight:
+    paddingRight > ANDROID_HORIZONTAL_PADDING_OFFSET
+      ? paddingRight - ANDROID_HORIZONTAL_PADDING_OFFSET
+      : ANDROID_DEFAULT_PADDING,
+  paddingBottom: ANDROID_DEFAULT_PADDING,
+  paddingTop: ANDROID_DEFAULT_PADDING,
+  height: rest.height + ANDROID_HEIGHT_OFFSET
 })
 
 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
+    // 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

package/src/Select/Select.jsx

@@ -16,6 +16,8 @@ import {
 import Picker from './Picker'
 import InputSupports from '../InputSupports'
 
+import { ANDROID_VALIDATION_ICON_CONTAINER_OFFSET } from './constants'
+
 const [selectProps, selectedSystemPropTypes] = selectSystemProps([
   a11yProps,
   inputSupportsProps,
@@ -133,7 +135,11 @@ const selectValidationIconContainerStyles = ({
   paddingBottom
 }) => ({
   paddingRight: icon ? paddingRight + iconSize : paddingRight,
-  paddingBottom
+  ...(Platform.OS === 'android'
+    ? {
+        paddingBottom: paddingBottom + ANDROID_VALIDATION_ICON_CONTAINER_OFFSET
+      }
+    : { paddingBottom })
 })
 
 /**

package/src/Select/constants.js

@@ -0,0 +1,5 @@
+// Because Android
+export const ANDROID_VALIDATION_ICON_CONTAINER_OFFSET = 5
+export const ANDROID_HEIGHT_OFFSET = 12
+export const ANDROID_HORIZONTAL_PADDING_OFFSET = 8
+export const ANDROID_DEFAULT_PADDING = 0

package/src/StepTracker/Step.jsx

@@ -138,7 +138,11 @@ const Step = ({ label, name, status = 0, stepCount = 0, stepIndex = 0, tokens, .
       accessibilityCurrent={status === stepIndex}
       {...selectProps(rest)}
     >
-      <StackView direction="row" space={0} tokens={{ alignItems: 'center', flexGrow: 0 }}>
+      <StackView
+        direction="row"
+        space={0}
+        tokens={{ alignItems: 'center', flexGrow: 0, justifyContent: 'center' }}
+      >
         <View
           style={[staticStyles.connector, !isFirst && selectConnectorStyles(themeTokens, isActive)]}
         />

package/src/TextInput/TextInput.jsx

@@ -1,4 +1,5 @@
 import React, { forwardRef } from 'react'
+import PropTypes from 'prop-types'
 import {
   a11yProps,
   focusHandlerProps,
@@ -63,6 +64,10 @@ TextInput.displayName = 'TextInput'
 TextInput.propTypes = {
   ...selectedSystemPropTypes,
   ...textInputPropTypes,
+  /**
+   * A callback which if provided will get a clear button rendered and will be called whenever that button gets pressed.
+   */
+  onClear: PropTypes.func,
   tokens: getTokensPropType('TextInput'),
   variant: variantProp.propType
 }

package/src/TextInput/TextInputBase.jsx

@@ -1,19 +1,22 @@
-import React, { forwardRef, useEffect, useState } from 'react'
+import React, { forwardRef, useEffect, useRef, useState } from 'react'
 import PropTypes from 'prop-types'
 import { Platform, StyleSheet, TextInput as NativeTextInput, View } from 'react-native'
 import { applyTextStyles, useTheme, useThemeTokens, applyOuterBorder } from '../ThemeProvider'
 import StackView from '../StackView'
+import IconButton from '../IconButton'
 import {
   a11yProps,
   getTokensPropType,
   selectSystemProps,
   textInputHandlerProps,
   textInputProps,
+  useCopy,
   useInputValue,
   useSpacingScale,
   variantProp,
   viewProps
 } from '../utils'
+import dictionary from './dictionary'
 
 const [selectProps, selectedSystemPropTypes] = selectSystemProps([
   a11yProps,
@@ -133,12 +136,14 @@ const TextInputBase = forwardRef(
   (
     {
       buttons = [],
+      copy = 'en',
       height,
       inactive,
       initialValue,
       onBlur,
       onChange,
       onChangeText,
+      onClear,
       onFocus,
       onMouseOut,
       onMouseOver,
@@ -171,14 +176,18 @@ const TextInputBase = forwardRef(
       if (typeof onMouseOut === 'function') onMouseOut(event)
     }
 
-    const { currentValue, setValue, isControlled } = useInputValue({
+    const defaultRef = useRef()
+    const inputRef = ref ?? defaultRef
+
+    const { currentValue, resetValue, setValue, isControlled, isDirty } = useInputValue({
       value,
       initialValue,
+      inputRef,
       onChange,
       readOnly
     })
 
-    const element = ref?.current
+    const element = inputRef?.current
     useEffect(() => {
       if (Platform.OS === 'web' && pattern && element) {
         // React Native Web doesn't support `pattern`, so we have to attach it via a ref,
@@ -197,7 +206,25 @@ const TextInputBase = forwardRef(
 
     const themeTokens = useThemeTokens('TextInput', tokens, variant, states)
 
-    const { icon: IconComponent, buttonsGap } = themeTokens
+    const { buttonsGap, clearButtonIcon: ClearButtonIcon, icon: IconComponent } = themeTokens
+    const buttonsGapSize = useSpacingScale(buttonsGap)
+    const getCopy = useCopy({ dictionary, copy })
+    if (onClear && isDirty) {
+      const handleClear = (event) => {
+        onClear?.(event)
+        resetValue(event)
+        inputRef?.current?.focus()
+      }
+      buttons?.unshift(
+        <IconButton
+          accessibilityLabel={getCopy('clearButtonAccessibilityLabel')}
+          icon={ClearButtonIcon}
+          key="clear"
+          onPress={handleClear}
+          variant={{ compact: true }}
+        />
+      )
+    }
 
     const inputProps = {
       ...selectProps(rest),
@@ -213,15 +240,12 @@ const TextInputBase = forwardRef(
       value: isControlled ? currentValue : undefined
     }
 
-    // Get the actual gap value for the current viewport
-    const buttonsGapSize = useSpacingScale(buttonsGap)
-
     const { themeOptions } = useTheme()
     const nativeInputStyle = selectInputStyles({ ...themeTokens, height }, themeOptions, inactive)
 
     return (
       <View style={selectOuterBorderStyles(themeTokens)}>
-        <NativeTextInput ref={ref} style={nativeInputStyle} {...inputProps} />
+        <NativeTextInput ref={inputRef} style={nativeInputStyle} {...inputProps} />
         {IconComponent && (
           <View
             pointerEvents="none" // avoid hijacking input press events
@@ -249,12 +273,23 @@ TextInputBase.displayName = 'TextInputBase'
 TextInputBase.propTypes = {
   ...selectedSystemPropTypes,
   buttons: PropTypes.arrayOf(PropTypes.node),
+  /**
+   * Select English or French copy for the accessible labels.
+   * You may also pass in a custom dictionary object.
+   */
+  copy: PropTypes.oneOfType([
+    PropTypes.oneOf(['en', 'fr']),
+    PropTypes.shape({
+      clearButtonAccessibilityLabel: PropTypes.string
+    })
+  ]),
   height: PropTypes.number,
   inactive: PropTypes.bool,
   initialValue: PropTypes.string,
   onBlur: PropTypes.func,
   onChange: PropTypes.func,
   onChangeText: PropTypes.func,
+  onClear: PropTypes.func,
   onFocus: PropTypes.func,
   onMouseOut: PropTypes.func,
   onMouseOver: PropTypes.func,

package/src/TextInput/dictionary.js

@@ -0,0 +1,8 @@
+export default {
+  en: {
+    clearButtonAccessibilityLabel: 'Clear'
+  },
+  fr: {
+    clearButtonAccessibilityLabel: 'Effacer'
+  }
+}

package/src/ThemeProvider/ThemeProvider.jsx

@@ -8,14 +8,22 @@ export const uninitialisedError = new Error('Theme context used outside of Theme
 export const ThemeContext = createContext(uninitialisedError)
 export const ThemeSetterContext = createContext(uninitialisedError)
 
-const ThemeProvider = ({
-  children,
-  defaultTheme,
+// These options default to `true` in v1.x to match legacy defaults and avoid breaking changes.
+// This should change in future major releases to become "opt-in" legacy support.
+const defaultThemeOptions = {
   // TODO: switch `forceAbsoluteFontSizing` to be false by default in the next major version
-  themeOptions = { forceAbsoluteFontSizing: true }
-}) => {
+  forceAbsoluteFontSizing: true,
+  // TODO: switch `forceZIndex` to be false by default in the next major version
+  forceZIndex: true,
+  // TODO: switch `enableHelmetSSR` to be false by default in the next major version
+  enableHelmetSSR: true
+}
+
+const ThemeProvider = ({ children, defaultTheme, themeOptions = {} }) => {
   const [theme, setTheme] = useState(defaultTheme)
 
+  const appliedThemeOptions = { ...defaultThemeOptions, ...themeOptions }
+
   // Validate the theme tokens version on every render.
   // This will intentionally break the application when attempting to use an invalid theme.
   // This will surface an incompatibility quickly rather than allowing the potential for strange bugs due to missing or incompatible tokens.
@@ -23,7 +31,9 @@ const ThemeProvider = ({
 
   return (
     <ThemeSetterContext.Provider value={setTheme}>
-      <ThemeContext.Provider value={{ ...theme, themeOptions }}>{children}</ThemeContext.Provider>
+      <ThemeContext.Provider value={{ ...theme, themeOptions: appliedThemeOptions }}>
+        {children}
+      </ThemeContext.Provider>
     </ThemeSetterContext.Provider>
   )
 }
@@ -43,9 +53,16 @@ ThemeProvider.propTypes = {
    *   relative sizing (in `rem`, scales depending on the browser settings)
    * - `contentMaxWidth`: allows configuration of the content max width to be used in components
    *   such as Footnote and Notification to avoid content to stretch width more then the page's width
+   * - `forceZIndex`: available on web only, when set to false, sets zIndex on `View` to be `auto`
+   *   and when true, sets zIndex to be `0` (the default from `react-native-web`)
+   * - `enableHelmetSSR`: on Web SSR, allows React Helmet to run during server-side rendering. This should be
+   *   disabled unless a web app has been specifically configured to stop React Helmet accumulating
+   *   instances (which may cause a memory leak). See React Helmet's docs: https://github.com/nfl/react-helmet
    */
   themeOptions: PropTypes.shape({
     forceAbsoluteFontSizing: PropTypes.bool,
+    forceZIndex: PropTypes.bool,
+    enableHelmetSSR: PropTypes.bool,
     contentMaxWidth: responsiveProps.getTypeOptionallyByViewport(PropTypes.number)
   })
 }

package/src/ThemeProvider/utils/styles.js

@@ -45,7 +45,9 @@ export function applyTextStyles({
     // Don't set undefined font families. May need some validation here that the font is available.
     // Android doesn't recognise font weights natively so apply custom font weights via `fontFamily`.
     styles.fontFamily = `${fontName}${fontWeight}${fontStyle}`
-  } else if (fontWeight) {
+  }
+
+  if (fontWeight) {
     // If using system default font, apply the font weight directly.
     // Font weight support in Android is limited to 'bold' or anything else === 'normal'.
     styles.fontWeight = Platform.OS === 'android' && Number(fontWeight) > 400 ? 'bold' : fontWeight

package/src/index.js

@@ -21,6 +21,7 @@ export { default as InputSupports } from './InputSupports'
 export * from './Link'
 export { default as List, ListItem, ListBase } from './List'
 export { default as Modal } from './Modal'
+export { default as MultiSelectFilter } from './MultiSelectFilter'
 export { default as Notification } from './Notification'
 export { default as Pagination } from './Pagination'
 export { default as Progress } from './Progress'
@@ -50,6 +51,7 @@ export { default as Typography } from './Typography'
 
 export { default as A11yInfoProvider, useA11yInfo } from './A11yInfoProvider'
 export { default as BaseProvider } from './BaseProvider'
+export { useHydrationContext } from './BaseProvider/HydrationContext'
 export { default as ViewportProvider, useViewport, ViewportContext } from './ViewportProvider'
 export {
   default as ThemeProvider,

package/src/utils/BaseView/BaseView.jsx

@@ -0,0 +1,38 @@
+import React, { forwardRef } from 'react'
+import { View as NativeView, StyleSheet } from 'react-native'
+import PropTypes from 'prop-types'
+import { useTheme } from '../../ThemeProvider'
+
+/**
+ * Identical to React Native's View and supporting all the same props, but with:
+ *  - a zIndex: 'auto' style added to prevent unexpectedly causing children to overlap other elements from other stacking contexts
+ */
+const BaseView = forwardRef(({ children, style, ...rest }, ref) => {
+  const { themeOptions } = useTheme()
+  const styleProp = Array.isArray(style) ? [...style] : [style]
+
+  if (!themeOptions.forceZIndex) {
+    styleProp.unshift(styles.resetZIndex)
+  }
+
+  return (
+    <NativeView {...rest} style={styleProp} ref={ref}>
+      {children}
+    </NativeView>
+  )
+})
+
+BaseView.displayName = 'BaseView'
+
+const styles = StyleSheet.create({
+  resetZIndex: {
+    zIndex: 'auto'
+  }
+})
+
+BaseView.propTypes = {
+  children: PropTypes.node,
+  style: PropTypes.oneOfType([PropTypes.object, PropTypes.array])
+}
+
+export default BaseView

package/src/utils/BaseView/BaseView.native.jsx

@@ -0,0 +1,6 @@
+import { View as BaseView } from 'react-native'
+
+/**
+ * Android crashes on non-standard style properties like `zIndex` so adding a `BaseView` for native platforms
+ */
+export default BaseView

package/src/utils/BaseView/index.js

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

package/src/utils/index.js

@@ -17,3 +17,4 @@ export { default as useUniqueId } from './useUniqueId'
 export { default as withLinkRouter } from './withLinkRouter'
 export * from './ssr'
 export { default as containUniqueFields } from './containUniqueFields'
+export { default as BaseView } from './BaseView'