@telus-uds/components-base 1.6.1 → 1.8.0

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

@@ -0,0 +1,194 @@
+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,
+  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/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.8.0",
   "description": "Base components",
   "keywords": [
     "base"
@@ -31,8 +31,7 @@
     "build:code": "yarn build:main && yarn build:module",
     "build:docs": "babel-node --plugins=@nearform/babel-plugin-react-docgen generate-component-docs.js",
     "storybook": "start-storybook",
-    "dev": "yarn build:code --watch",
-    "release": "standard-version"
+    "dev": "yarn build:code --watch"
   },
   "bugs": {
     "url": "https://github.com/telus/universal-design-system/issues"
@@ -50,6 +49,12 @@
     "react-native-web": "^0.17.0"
   },
   "devDependencies": {
+    "@storybook/addon-a11y": "^6.5.6",
+    "@storybook/addon-essentials": "^6.5.6",
+    "@storybook/cli": "^6.5.6",
+    "@storybook/react": "^6.5.6",
+    "@storybook/builder-webpack5": "^6.5.6",
+    "@storybook/manager-webpack5": "^6.5.6",
     "@telus-uds/browserslist-config": "^1.0.1",
     "@testing-library/jest-native": "^4.0.1",
     "@testing-library/react-hooks": "^7.0.1",
@@ -59,7 +64,7 @@
   "dependencies": {
     "airbnb-prop-types": "^2.16.0",
     "@telus-uds/system-constants": "^1.0.2",
-    "@telus-uds/system-theme-tokens": "^1.5.0",
+    "@telus-uds/system-theme-tokens": "^2.0.0",
     "lodash.debounce": "^4.0.8",
     "lodash.merge": "^4.6.2",
     "prop-types": "^15.7.2",

package/src/Button/ButtonGroup.jsx

@@ -5,6 +5,7 @@ import { Platform } from 'react-native'
 
 import ButtonBase from './ButtonBase'
 import { StackWrap } from '../StackView'
+import Fieldset from '../Fieldset'
 import { useViewport } from '../ViewportProvider'
 import { useThemeTokens, useThemeTokensCallback } from '../ThemeProvider'
 import {
@@ -41,6 +42,13 @@ const ButtonGroup = forwardRef(
       onChange,
       readOnly = false,
       inactive = false,
+      legend,
+      tooltip,
+      hint,
+      validation,
+      feedback,
+      name: inputGroupName,
+      copy,
       accessibilityRole = maxValues === 1
         ? 'radiogroup' // radiogroup is cross-platform; only web aria has generic groups
         : Platform.select({ web: 'group', default: 'none' }),
@@ -51,7 +59,7 @@ const ButtonGroup = forwardRef(
     const viewport = useViewport()
     const themeTokens = useThemeTokens('ButtonGroup', tokens, variant, { viewport })
     const stackTokens = selectTokens('StackView', themeTokens)
-    const { direction, space } = themeTokens
+    const { direction, space, fieldSpace } = themeTokens
 
     const getButtonTokens = useThemeTokensCallback('ButtonGroupItem', tokens, variant)
 
@@ -74,53 +82,73 @@ const ButtonGroup = forwardRef(
       throw new Error(`ButtonGroup items must have unique ${uniqueFields.join(', ')}`)
     }
 
+    // Some web screenreaders e.g. MacOS Voiceover don't handle radiogroups properly unless radio is direct child of radiogroup
+    const innerRole =
+      Platform.OS === 'web' && accessibilityRole === 'radiogroup' ? accessibilityRole : undefined
+
     return (
-      <StackWrap
+      <Fieldset
         {...systemProps}
-        space={space}
-        direction={direction}
-        tokens={stackTokens}
         ref={ref}
+        name={inputGroupName}
+        legend={legend}
+        tooltip={tooltip}
+        hint={hint}
+        space={fieldSpace}
+        feedback={feedback}
+        readOnly={readOnly}
+        inactive={inactive}
+        validation={validation}
+        accessibilityRole={accessibilityRole}
+        {...selectProps(rest)}
       >
-        {items.map(
-          ({ label, id = label, accessibilityLabel, ref: itemRef, ...itemRest }, index) => {
-            const isSelected = currentValues.includes(id)
+        <StackWrap
+          accessibilityRole={innerRole}
+          space={space}
+          direction={direction}
+          tokens={stackTokens}
+          ref={ref}
+        >
+          {items.map(
+            ({ label, id = label, accessibilityLabel, ref: itemRef, ...itemRest }, index) => {
+              const isSelected = currentValues.includes(id)
 
-            // Pass an object of relevant component state as first argument for any passed-in press handlers
-            const pressHandlers = getPressHandlersWithArgs(rest, [{ id, label, currentValues }])
+              // Pass an object of relevant component state as first argument for any passed-in press handlers
+              const pressHandlers = getPressHandlersWithArgs(rest, [{ id, label, currentValues }])
 
-            const handlePress = (event) => {
-              if (pressHandlers.onPress) pressHandlers.onPress(event)
-              toggleOneValue(id, event)
-            }
+              const handlePress = (event) => {
+                if (pressHandlers.onPress) pressHandlers.onPress(event)
+                toggleOneValue(id, event)
+              }
 
-            const itemA11y = {
-              accessibilityState: { checked: isSelected },
-              accessibilityRole: itemA11yRole,
-              accessibilityLabel,
-              ...a11yProps.getPositionInSet(items.length, index)
-            }
+              const itemA11y = {
+                accessibilityState: { checked: isSelected },
+                accessibilityRole: itemA11yRole,
+                accessibilityLabel,
+                ...a11yProps.getPositionInSet(items.length, index)
+              }
 
-            // Ensure button is direct child of group as MacOS voiceover only applies "X of Y" to
-            // "radio" if it's a direct child of "radiogroup", even if aria-posinset etc exists
-            return (
-              <ButtonBase
-                ref={itemRef}
-                key={id}
-                {...pressHandlers}
-                onPress={handlePress}
-                tokens={getButtonTokens}
-                selected={isSelected}
-                inactive={inactive}
-                {...itemA11y}
-                {...selectItemProps(itemRest)}
-              >
-                {label}
-              </ButtonBase>
-            )
-          }
-        )}
-      </StackWrap>
+              // Ensure button is direct child of group as MacOS voiceover only applies "X of Y" to
+              // "radio" if it's a direct child of "radiogroup", even if aria-posinset etc exists
+              return (
+                <ButtonBase
+                  ref={itemRef}
+                  key={id}
+                  {...pressHandlers}
+                  onPress={handlePress}
+                  tokens={getButtonTokens}
+                  selected={isSelected}
+                  inactive={inactive}
+                  {...itemA11y}
+                  {...selectItemProps(itemRest)}
+                >
+                  {label}
+                </ButtonBase>
+              )
+            }
+          )}
+        </StackWrap>
+      </Fieldset>
     )
   }
 )
@@ -180,7 +208,44 @@ ButtonGroup.propTypes = {
    * 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)
+  initialValues: PropTypes.arrayOf(PropTypes.string),
+  /**
+   * Main text used to describe this group, used in Fieldset's Legend element.
+   */
+  legend: PropTypes.string,
+  /**
+   * Optional additional text giving more detail to help a user make a choice.
+   */
+  hint: PropTypes.string,
+  /**
+   * Optional tooltip text content to include alongside the legend and hint.
+   */
+  tooltip: PropTypes.string,
+  /**
+   * Current validation status of the group, passed to the feedback element if there is one.
+   */
+  validation: PropTypes.oneOf(['error', 'success']),
+  /**
+   * If provided, a Feedback element is rendered containing this text.
+   */
+  feedback: PropTypes.string,
+  /**
+   * If true, the buttons cannot be selected by the user and simply show their current state.
+   */
+  readOnly: PropTypes.bool,
+  /**
+   * If true, the buttons cannot be interacted with, elements are set as `disabled` and if the
+   * theme supports `inactive` appearances rules, these are applied.
+   */
+  inactive: PropTypes.bool,
+  /**
+   * On Web, this is passed to the `name` attribute of the fieldset.
+   */
+  name: PropTypes.string,
+  /**
+   * Sets the language of microcopy in subcomponents (e.g. Tooltip's default accessibility label).
+   */
+  copy: PropTypes.oneOf(['en', 'fr'])
 }
 
 export default ButtonGroup

package/src/Checkbox/Checkbox.jsx

@@ -137,7 +137,11 @@ const Checkbox = forwardRef(
     },
     ref
   ) => {
-    const { currentValue: isChecked, setValue: setIsChecked, isControlled } = useInputValue(
+    const {
+      currentValue: isChecked,
+      setValue: setIsChecked,
+      isControlled
+    } = useInputValue(
       {
         value: checked,
         initialValue: defaultChecked,
@@ -152,9 +156,8 @@ const Checkbox = forwardRef(
       ...variant
     })
     const defaultTokens = getTokens()
-    const { feedbackMarginBottom, feedbackMarginTop, feedbackPosition } = selectFeedbackTokens(
-      defaultTokens
-    )
+    const { feedbackMarginBottom, feedbackMarginTop, feedbackPosition } =
+      selectFeedbackTokens(defaultTokens)
     const styles = StyleSheet.create({
       feedbackContainer: { marginTop: feedbackMarginTop, marginBottom: feedbackMarginBottom }
     })

package/src/Checkbox/CheckboxGroup.jsx

@@ -219,16 +219,16 @@ CheckboxGroup.propTypes = {
    */
   onChange: PropTypes.func,
   /**
-   * If true, the radio cards cannot be selected by the user and simply show their current state.
+   * If true, the checkboxes cannot be selected by the user and simply show their current state.
    */
   readOnly: PropTypes.bool,
   /**
-   * If true, the checkbox cannot be interacted with, elements are set as `disabled` and if the
+   * If true, the checkboxes cannot be interacted with, elements are set as `disabled` and if the
    * theme supports `inactive` appearances rules, these are applied.
    */
   inactive: PropTypes.bool,
   /**
-   * On Web, this is passed to the `name` attribute of the fieldset and each radio input.
+   * On Web, this is passed to the `name` attribute of the fieldset and each checkbox input.
    */
   name: PropTypes.string
 }

package/src/ExpandCollapse/Panel.jsx

@@ -79,7 +79,8 @@ const ExpandCollapsePanel = forwardRef(
         setContainerHeight(height)
       }
     }
-    const animatedStyles = useVerticalExpandAnimation({
+
+    const [animatedStyles, animatedRef] = useVerticalExpandAnimation({
       containerHeight,
       isExpanded,
       tokens: themeTokens
@@ -105,6 +106,7 @@ const ExpandCollapsePanel = forwardRef(
           {control}
         </ExpandCollapseControl>
         <Animated.View
+          ref={animatedRef}
           style={[overflowContainerStyles, animatedStyles, staticStyles.itemsContainer]}
           {...focusabilityProps}
         >

package/src/Fieldset/Fieldset.jsx

@@ -18,6 +18,7 @@ import Legend from './Legend'
 const Fieldset = forwardRef(
   (
     {
+      copy = 'en',
       space,
       feedback,
       feedbackPosition = 'top',
@@ -44,6 +45,7 @@ const Fieldset = forwardRef(
     const legendContent = legend && (
       <Legend>
         <InputLabel
+          copy={copy}
           label={legend}
           hint={hint}
           hintPosition={hintPosition}
@@ -83,6 +85,10 @@ Fieldset.displayName = 'Fieldset'
 
 Fieldset.propTypes = {
   children: PropTypes.oneOfType([PropTypes.func, PropTypes.node]),
+  /**
+   * Whether the English or French copy will be used (e.g. for accessibility labels).
+   */
+  copy: PropTypes.oneOf(['en', 'fr']),
   /**
    * The accessibility role of the `<fieldset>` element itself. Other React Native accessibility
    * props are not supported because there is not an appropriate counterpart for Fieldsets.

package/src/InputLabel/InputLabel.jsx

@@ -38,7 +38,18 @@ const selectGapStyles = ({ gap }) => ({ marginRight: gap })
 
 const InputLabel = forwardRef(
   (
-    { label, forId, hint, hintPosition = 'inline', hintId, tooltip, tokens, variant, ...rest },
+    {
+      copy = 'en',
+      label,
+      forId,
+      hint,
+      hintPosition = 'inline',
+      hintId,
+      tooltip,
+      tokens,
+      variant,
+      ...rest
+    },
     ref
   ) => {
     const themeTokens = useThemeTokens('InputLabel', tokens, variant)
@@ -77,7 +88,7 @@ const InputLabel = forwardRef(
                 { height: themeTokens.fontSize * themeTokens.lineHeight }
               ]}
             >
-              <Tooltip content={tooltip} />
+              <Tooltip content={tooltip} copy={copy} />
             </View>
           )}
         </View>
@@ -94,6 +105,10 @@ InputLabel.displayName = 'InputLabel'
 
 InputLabel.propTypes = {
   ...selectedSystemPropTypes,
+  /**
+   * Whether the English or French copy will be used (e.g. for accessibility labels).
+   */
+  copy: PropTypes.oneOf(['en', 'fr']),
   /**
    * The input label.
    */

package/src/InputSupports/InputSupports.jsx

@@ -8,7 +8,10 @@ import { useThemeTokens } from '../ThemeProvider'
 import useInputSupports from './useInputSupports'
 
 const InputSupports = forwardRef(
-  ({ children, label, hint, hintPosition = 'inline', feedback, tooltip, validation }, ref) => {
+  (
+    { children, copy = 'en', label, hint, hintPosition = 'inline', feedback, tooltip, validation },
+    ref
+  ) => {
     const { space } = useThemeTokens('InputSupports')
 
     const { inputId, hintId, feedbackId, a11yProps } = useInputSupports({
@@ -22,6 +25,7 @@ const InputSupports = forwardRef(
       <StackView space={space} ref={ref}>
         {label && (
           <InputLabel
+            copy={copy}
             label={label}
             hint={hint}
             hintPosition={hintPosition}
@@ -40,6 +44,10 @@ InputSupports.displayName = 'InputSupports'
 
 InputSupports.propTypes = {
   children: PropTypes.oneOfType([PropTypes.func, PropTypes.node]),
+  /**
+   * Whether the English or French copy will be used (e.g. for accessibility labels).
+   */
+  copy: PropTypes.oneOf(['en', 'fr']),
   /**
    * The input label.
    */