@telus-uds/components-base 0.0.2-prerelease.6 → 1.0.0

package/src/Checkbox/CheckboxInput.jsx

@@ -0,0 +1,55 @@
+import React, { forwardRef } from 'react'
+import PropTypes from 'prop-types'
+
+/**
+ * On Web we need to include an actual input but hide it.
+ */
+const CheckboxInput = forwardRef(
+  ({ checked, defaultChecked, disabled, id, isControlled, name, onChange, value }, ref) => {
+    const handleClick = (event) => {
+      // Cancel the click dispatched via the label tag, since it's already wrapped
+      // in <Pressable>
+      event.preventDefault()
+      event.stopPropagation()
+    }
+
+    return (
+      <input
+        checked={isControlled ? checked : undefined}
+        defaultChecked={isControlled ? undefined : defaultChecked}
+        disabled={disabled}
+        hidden
+        id={id}
+        name={name}
+        onChange={onChange}
+        onClick={handleClick}
+        ref={ref}
+        type="checkbox"
+        value={value}
+      />
+    )
+  }
+)
+CheckboxInput.displayName = 'CheckboxInput'
+
+CheckboxInput.propTypes = {
+  checked: PropTypes.bool,
+  defaultChecked: PropTypes.bool,
+  disabled: PropTypes.bool,
+  id: PropTypes.string.isRequired,
+  isControlled: PropTypes.bool.isRequired,
+  name: PropTypes.string,
+  onChange: PropTypes.func,
+  value: PropTypes.string
+}
+
+CheckboxInput.defaultProps = {
+  checked: undefined,
+  defaultChecked: undefined,
+  disabled: false,
+  name: undefined,
+  onChange: () => {},
+  value: undefined
+}
+
+export default CheckboxInput

package/src/Checkbox/CheckboxInput.native.jsx

@@ -0,0 +1,6 @@
+/**
+ * There's no checkbox input on native platforms, so this is a noop.
+ */
+const CheckboxInput = () => null
+
+export default CheckboxInput

package/src/Checkbox/index.js

@@ -0,0 +1,5 @@
+import Checkbox from './Checkbox'
+
+export default Checkbox
+
+export { default as CheckboxGroup } from './CheckboxGroup'

package/src/Divider/Divider.jsx

@@ -1,4 +1,4 @@
-import React from 'react'
+import React, { forwardRef } from 'react'
 import PropTypes from 'prop-types'
 import { View, StyleSheet, Platform } from 'react-native'
 import { useThemeTokens } from '../ThemeProvider'
@@ -45,7 +45,7 @@ import { getTokensPropType, variantProp, spacingProps } from '../utils'
  *
  * For accessibility purposes a divider component will be described with ARIA attributes, i.e. `role="separator"` and `aria-orientation="vertical/horizontal"`.
  */
-const Divider = ({ variant, vertical = false, space, tokens, testID }) => {
+const Divider = forwardRef(({ variant, vertical = false, space, tokens, testID }, ref) => {
   const { color, width } = useThemeTokens('Divider', tokens, variant)
 
   const borderStyles = vertical
@@ -68,7 +68,9 @@ const Divider = ({ variant, vertical = false, space, tokens, testID }) => {
       : // There are no such equivalent attributes for native
         {}
 
-  const divider = <View style={[styles.divider, borderStyles]} testID={testID} {...a11y} />
+  const divider = (
+    <View ref={ref} style={[styles.divider, borderStyles]} testID={testID} {...a11y} />
+  )
   if (!space) return divider
   const spacerProps = { space, direction: vertical ? 'row' : 'column' }
   return (
@@ -78,7 +80,8 @@ const Divider = ({ variant, vertical = false, space, tokens, testID }) => {
       <Spacer {...spacerProps} testID={testID ? `${testID}-Spacer-after` : undefined} />
     </>
   )
-}
+})
+Divider.displayName = 'Divider'
 
 Divider.propTypes = {
   tokens: getTokensPropType('Divider'),

package/src/ExpandCollapse/Accordion.jsx

@@ -1,10 +1,11 @@
-import React from 'react'
+import React, { forwardRef } from 'react'
 import ExpandCollapse from './ExpandCollapse'
 
 /**
  * 'Accordion' is a shorthand for an ExpandCollapse where only one item may be open at a time
  */
-const Accordion = (props) => <ExpandCollapse {...props} maxOpen={1} />
+const Accordion = forwardRef((props, ref) => <ExpandCollapse ref={ref} {...props} maxOpen={1} />)
+Accordion.displayName = 'Accordion'
 Accordion.propTypes = ExpandCollapse.propTypes
 
 export default Accordion

package/src/ExpandCollapse/Control.jsx

@@ -1,4 +1,4 @@
-import React from 'react'
+import React, { forwardRef } from 'react'
 import { Pressable, View } from 'react-native'
 import PropTypes from 'prop-types'
 
@@ -47,51 +47,48 @@ function selectIconTokens(tokens) {
   }
 }
 
-const ExpandCollapseControl = ({
-  onPress,
-  isExpanded,
-  children,
-  tokens,
-  accessibilityRole = 'button',
-  variant,
-  rest
-}) => {
-  const getTokens = useThemeTokensCallback('ExpandCollapseControl', tokens, variant)
+const ExpandCollapseControl = forwardRef(
+  ({ onPress, isExpanded, children, tokens, accessibilityRole = 'button', variant, rest }, ref) => {
+    const getTokens = useThemeTokensCallback('ExpandCollapseControl', tokens, variant)
 
-  const a11y = a11yProps.select({ ...rest, accessibilityRole })
-  a11y.accessibilityState = {
-    ...(a11y.accessibilityState || {}),
-    expanded: isExpanded
-  }
+    const a11y = a11yProps.select({ ...rest, accessibilityRole })
+    a11y.accessibilityState = {
+      ...(a11y.accessibilityState || {}),
+      expanded: isExpanded
+    }
 
-  const getControlState = ({ pressed, hovered, focused }) => ({
-    pressed,
-    hover: hovered,
-    focus: focused,
-    expanded: isExpanded
-  })
-  const getControlTokens = (pressableState) => getTokens(getControlState(pressableState))
-  const getPressableStyle = (pressableState) =>
-    selectContainerStyles(getControlTokens(pressableState))
+    const getControlState = ({ pressed, hovered, focused }) => ({
+      pressed,
+      hover: hovered,
+      focus: focused,
+      expanded: isExpanded
+    })
+    const getControlTokens = (pressableState) => getTokens(getControlState(pressableState))
+    const getPressableStyle = (pressableState) =>
+      selectContainerStyles(getControlTokens(pressableState))
 
-  return (
-    <Pressable {...a11y} onPress={onPress} style={getPressableStyle}>
-      {(pressableState) => {
-        const { icon: IconComponent, ...themeTokens } = getControlTokens(pressableState)
-        return (
-          <>
-            {IconComponent && (
-              <View style={selectIconContainerStyles(themeTokens)}>
-                <IconComponent tokens={selectIconTokens(themeTokens)} />
-              </View>
-            )}
-            {typeof children === 'function' ? children(getControlState(pressableState)) : children}
-          </>
-        )
-      }}
-    </Pressable>
-  )
-}
+    return (
+      <Pressable ref={ref} {...a11y} onPress={onPress} style={getPressableStyle}>
+        {(pressableState) => {
+          const { icon: IconComponent, ...themeTokens } = getControlTokens(pressableState)
+          return (
+            <>
+              {IconComponent && (
+                <View style={selectIconContainerStyles(themeTokens)}>
+                  <IconComponent {...selectIconTokens(themeTokens)} />
+                </View>
+              )}
+              {typeof children === 'function'
+                ? children(getControlState(pressableState))
+                : children}
+            </>
+          )
+        }}
+      </Pressable>
+    )
+  }
+)
+ExpandCollapseControl.displayName = 'ExpandCollapseControl'
 
 ExpandCollapseControl.propTypes = {
   ...a11yProps.propTypes,

package/src/ExpandCollapse/ExpandCollapse.jsx

@@ -1,4 +1,4 @@
-import React from 'react'
+import React, { forwardRef } from 'react'
 import { View } from 'react-native'
 import PropTypes from 'prop-types'
 
@@ -20,29 +20,32 @@ function selectBorderStyles(tokens) {
  * <ExpandCollapse.Panel> children, and assign the panels explicit `panelId` props. The panels may be
  * nested (they do not need to be direct children), and non-interactive items may be included too.
  */
-const ExpandCollapse = ({ children, tokens, variant, maxOpen, open, initialOpen, onChange }) => {
-  const {
-    currentValues: openIds,
-    toggleOneValue: onToggle,
-    resetValues,
-    setValues,
-    unsetValues
-  } = useMultipleInputValues({
-    maxValues: maxOpen,
-    values: open,
-    initialValues: initialOpen,
-    onChange
-  })
-  const themeTokens = useThemeTokens('ExpandCollapse', tokens, variant)
+const ExpandCollapse = forwardRef(
+  ({ children, tokens, variant, maxOpen, open, initialOpen, onChange }, ref) => {
+    const {
+      currentValues: openIds,
+      toggleOneValue: onToggle,
+      resetValues,
+      setValues,
+      unsetValues
+    } = useMultipleInputValues({
+      maxValues: maxOpen,
+      values: open,
+      initialValues: initialOpen,
+      onChange
+    })
+    const themeTokens = useThemeTokens('ExpandCollapse', tokens, variant)
 
-  return (
-    <View style={selectBorderStyles(themeTokens)}>
-      {typeof children === 'function'
-        ? children({ openIds, onToggle, resetValues, setValues, unsetValues })
-        : children}
-    </View>
-  )
-}
+    return (
+      <View ref={ref} style={selectBorderStyles(themeTokens)}>
+        {typeof children === 'function'
+          ? children({ openIds, onToggle, resetValues, setValues, unsetValues })
+          : children}
+      </View>
+    )
+  }
+)
+ExpandCollapse.displayName = 'ExpandCollapse'
 
 ExpandCollapse.propTypes = {
   variant: variantProp.propType,

package/src/ExpandCollapse/Panel.jsx

@@ -1,4 +1,4 @@
-import React, { useState } from 'react'
+import React, { forwardRef, useState } from 'react'
 import { Animated, Platform, StyleSheet, View } from 'react-native'
 import PropTypes from 'prop-types'
 
@@ -30,78 +30,84 @@ const selectContainerStyles = ({
  * The panel does not need to be a direct child of the `<ExpandCollapse>` (unless this is required
  * by the chosen accessibility props for a particular accessibility tools).
  */
-const ExpandCollapsePanel = ({
-  openIds = [],
-  panelId,
-  onToggle,
-  onPress,
-  control,
-  controlTokens,
-  children,
-  tokens,
-  variant,
-  ...rest
-}) => {
-  const [containerHeight, setContainerHeight] = useState(null)
-  const isExpanded = openIds.includes(panelId)
+const ExpandCollapsePanel = forwardRef(
+  (
+    {
+      openIds = [],
+      panelId,
+      onToggle,
+      onPress,
+      control,
+      controlTokens,
+      children,
+      tokens,
+      variant,
+      ...rest
+    },
+    ref
+  ) => {
+    const [containerHeight, setContainerHeight] = useState(null)
+    const isExpanded = openIds.includes(panelId)
 
-  const a11y = a11yProps.select(rest)
-  a11y.accessibilityState = {
-    ...(a11y.accessibilityState || {}),
-    expanded: isExpanded
-  }
+    const a11y = a11yProps.select(rest)
+    a11y.accessibilityState = {
+      ...(a11y.accessibilityState || {}),
+      expanded: isExpanded
+    }
 
-  const themeTokens = useThemeTokens('ExpandCollapsePanel', tokens, variant, {
-    expanded: isExpanded
-  })
+    const themeTokens = useThemeTokens('ExpandCollapsePanel', tokens, variant, {
+      expanded: isExpanded
+    })
 
-  const handleControlPress = () => {
-    onToggle(panelId)
-    if (onPress) onPress(panelId)
-  }
+    const handleControlPress = (event) => {
+      onToggle(panelId, event)
+      if (onPress) onPress(panelId, event)
+    }
 
-  const onContainerLayout = (event) => {
-    if (containerHeight === null) {
-      const { layout: { height = 0 } = {} } = event.nativeEvent
-      setContainerHeight(height)
+    const onContainerLayout = (event) => {
+      if (containerHeight === null) {
+        const { layout: { height = 0 } = {} } = event.nativeEvent
+        setContainerHeight(height)
+      }
     }
-  }
-  const animatedStyles = useVerticalExpandAnimation({
-    containerHeight,
-    isExpanded,
-    tokens: themeTokens
-  })
+    const animatedStyles = useVerticalExpandAnimation({
+      containerHeight,
+      isExpanded,
+      tokens: themeTokens
+    })
 
-  // on web we can hide the contents until we have the container measured and avoid occasional jitter
-  // this won't work on native platforms
-  const overflowContainerStyles =
-    containerHeight === null && Platform.OS === 'web'
-      ? { height: 0, visibility: 'hidden' }
-      : undefined
+    // on web we can hide the contents until we have the container measured and avoid occasional jitter
+    // this won't work on native platforms
+    const overflowContainerStyles =
+      containerHeight === null && Platform.OS === 'web'
+        ? { height: 0, visibility: 'hidden' }
+        : undefined
 
-  const focusabilityProps = isExpanded ? {} : a11yProps.nonFocusableProps
+    const focusabilityProps = isExpanded ? {} : a11yProps.nonFocusableProps
 
-  return (
-    <View style={selectGroupStyles(themeTokens)}>
-      <ExpandCollapseControl
-        {...a11y}
-        isExpanded={isExpanded}
-        tokens={controlTokens}
-        onPress={handleControlPress}
-      >
-        {control}
-      </ExpandCollapseControl>
-      <View style={overflowContainerStyles} {...focusabilityProps}>
-        <Animated.View
-          onLayout={onContainerLayout}
-          style={[staticStyles.itemsContainer, animatedStyles]}
+    return (
+      <View ref={ref} style={selectGroupStyles(themeTokens)}>
+        <ExpandCollapseControl
+          {...a11y}
+          isExpanded={isExpanded}
+          tokens={controlTokens}
+          onPress={handleControlPress}
         >
-          <View style={selectContainerStyles(themeTokens)}>{children}</View>
-        </Animated.View>
+          {control}
+        </ExpandCollapseControl>
+        <View style={overflowContainerStyles} {...focusabilityProps}>
+          <Animated.View
+            onLayout={onContainerLayout}
+            style={[staticStyles.itemsContainer, animatedStyles]}
+          >
+            <View style={selectContainerStyles(themeTokens)}>{children}</View>
+          </Animated.View>
+        </View>
       </View>
-    </View>
-  )
-}
+    )
+  }
+)
+ExpandCollapsePanel.displayName = 'ExpandCollapsePanel'
 
 ExpandCollapsePanel.propTypes = {
   variant: variantProp.propType,

package/src/Feedback/Feedback.jsx

@@ -1,4 +1,4 @@
-import React from 'react'
+import React, { forwardRef } from 'react'
 import { StyleSheet, Text, View } from 'react-native'
 import PropTypes from 'prop-types'
 
@@ -40,40 +40,46 @@ const selectIconContainerStyles = ({ iconGap }) => ({
  * ### Accessibility
  * All accessibility props set on this component will be applied to the outer container.
  */
-const Feedback = ({ title, children, tokens, variant, ...rest }) => {
-  const themeTokens = useThemeTokens('Feedback', tokens, variant)
-  const { space } = themeTokens
+const Feedback = forwardRef(
+  ({ title, children, id, validation, tokens, variant, ...rest }, ref) => {
+    const themeTokens = useThemeTokens('Feedback', tokens, { ...variant, validation })
+    const { space } = themeTokens
 
-  const { icon: IconComponent } = themeTokens
+    const { icon: IconComponent } = themeTokens
 
-  const titleTextStyles = selectTitleTextStyles(themeTokens)
-  const contentTextStyles = selectContentTextStyles(themeTokens)
+    const titleTextStyles = selectTitleTextStyles(themeTokens)
+    const contentTextStyles = selectContentTextStyles(themeTokens)
 
-  const content =
-    typeof children === 'string' ? <Text style={contentTextStyles}>{children}</Text> : children
+    const content =
+      typeof children === 'string' ? <Text style={contentTextStyles}>{children}</Text> : children
 
-  const accessibilityProps = a11yProps.select(rest)
+    const accessibilityProps = a11yProps.select({
+      accessibilityRole: validation === 'error' ? 'alert' : undefined,
+      ...rest
+    })
 
-  return (
-    <View style={selectStyles(themeTokens)} {...accessibilityProps}>
-      <StackView space={space}>
-        {title !== undefined && (
-          <View style={staticStyles.title}>
-            {IconComponent && (
-              <View style={selectIconContainerStyles(themeTokens)}>
-                <IconComponent tokens={selectIconTokens(themeTokens)} />
-              </View>
-            )}
-            <Text style={titleTextStyles}>{title}</Text>
-          </View>
-        )}
-        {content && typeof content === 'function'
-          ? content({ textStyles: contentTextStyles, variant })
-          : content}
-      </StackView>
-    </View>
-  )
-}
+    return (
+      <View ref={ref} style={selectStyles(themeTokens)} {...accessibilityProps} nativeID={id}>
+        <StackView space={space}>
+          {title !== undefined && (
+            <View style={staticStyles.title}>
+              {IconComponent && (
+                <View style={selectIconContainerStyles(themeTokens)}>
+                  <IconComponent {...selectIconTokens(themeTokens)} />
+                </View>
+              )}
+              <Text style={titleTextStyles}>{title}</Text>
+            </View>
+          )}
+          {content && typeof content === 'function'
+            ? content({ textStyles: contentTextStyles, variant })
+            : content}
+        </StackView>
+      </View>
+    )
+  }
+)
+Feedback.displayName = 'Feedback'
 
 Feedback.propTypes = {
   /**
@@ -84,6 +90,12 @@ Feedback.propTypes = {
    * Feedback content rendered below the title. A render function `({textStyles, variant}) => {}` is supported.
    */
   children: PropTypes.oneOfType([PropTypes.string, PropTypes.node, PropTypes.func]),
+  /**
+   * Use to visually mark the Feedback as valid or invalid.
+   */
+  validation: PropTypes.oneOf(['error', 'success']),
+  /** @ignore */
+  id: PropTypes.string,
   tokens: getTokensPropType('Feedback'),
   variant: variantProp.propType
 }

package/src/Fieldset/Fieldset.jsx

@@ -0,0 +1,136 @@
+import React, { forwardRef } from 'react'
+import PropTypes from 'prop-types'
+
+import Feedback from '../Feedback'
+import { spacingProps } from '../utils'
+import FieldsetContainer from './FieldsetContainer'
+import { getStackedContent } from '../StackView'
+import InputLabel from '../InputLabel'
+import useInputSupports from '../InputSupports/useInputSupports'
+import Legend from './Legend'
+
+/**
+ * An alternative to InputSupports for groups of input elements that, on web, are to be
+ * wrapped in a `<fieldset>` tag, with label content displated in a `<legend>` tag.
+ *
+ * Follows the same theming and most of the same props as InputSupports.
+ */
+const Fieldset = forwardRef(
+  (
+    {
+      space,
+      feedback,
+      feedbackPosition = 'top',
+      validation,
+      legend,
+      hint,
+      hintPosition,
+      tooltip,
+      inactive,
+      accessibilityRole,
+      name: fieldsetName,
+      children
+    },
+    ref
+  ) => {
+    // Skips `inputId` because a fieldset' legend describes multiple inputs
+    const { hintId, feedbackId, a11yProps } = useInputSupports({
+      feedback,
+      hint,
+      label: legend,
+      validation
+    })
+
+    const legendContent = legend && (
+      <Legend>
+        <InputLabel
+          label={legend}
+          hint={hint}
+          hintPosition={hintPosition}
+          hintId={hintId}
+          tooltip={tooltip}
+        />
+      </Legend>
+    )
+    const feedbackContent = feedback && (
+      <Feedback id={feedbackId} title={feedback} validation={validation} />
+    )
+
+    // Some accessibility patterns depend on elements being direct children, e.g. fieldset -> legend,
+    // and on MacOS voiceover, radiogroup -> radio. To allow elements to be direct children of the
+    // fieldset as much as possible, but also allow different spacing within content and between
+    // fieldset / feedback / etc, wrap resolved children in a fragment, and stack with `preserveFragments`.
+    const childContent = <>{typeof children === 'function' ? children({ a11yProps }) : children}</>
+    const orderedContent =
+      feedbackPosition === 'bottom'
+        ? [legendContent, feedbackContent, childContent]
+        : [legendContent, childContent, feedbackContent]
+    const stackedContent = getStackedContent(orderedContent, { space, preserveFragments: true })
+
+    return (
+      <FieldsetContainer
+        ref={ref}
+        inactive={inactive}
+        accessibilityRole={accessibilityRole}
+        name={fieldsetName}
+      >
+        {stackedContent}
+      </FieldsetContainer>
+    )
+  }
+)
+Fieldset.displayName = 'Fieldset'
+
+Fieldset.propTypes = {
+  children: PropTypes.oneOfType([PropTypes.func, PropTypes.node]),
+  /**
+   * 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.
+   */
+  accessibilityRole: PropTypes.string,
+  /**
+   * The amout of space between legend, feedback and content; according  to the theme's spacing scale.
+   * Either a number corresponding to a position on the theme's spacing scale (1 is smallest, 2 is second smallest, etc),
+   * or, a SpacingObject with viewport keys and options (see `useSpacingScale` for details).
+   */
+  space: spacingProps.types.spacingValue,
+  /**
+   * The text for the fieldset's legend, describing the fieldset content.
+   */
+  legend: PropTypes.string,
+  /**
+   * A short description of the expected input.
+   */
+  hint: PropTypes.string,
+  /**
+   * Position of the hint relative to label.
+   */
+  hintPosition: PropTypes.oneOf(['inline', 'below']),
+  /**
+   * A detailed description of validation error/success or additional instructions.
+   * Visual variant is determined based on the `validation` prop.
+   */
+  feedback: PropTypes.string,
+  /**
+   * Position of the feedback block relative to the fieldset's content.
+   */
+  feedbackPosition: PropTypes.oneOf(['above', 'below']),
+  /**
+   * If true, the fieldset is treated as inactive (setting `disabled` attribute on web).
+   */
+  inactive: PropTypes.bool,
+  /**
+   * Content of an optional `Tooltip`. If set, a tooltip button will be shown next to the label.
+   */
+  tooltip: PropTypes.string,
+  /**
+   * On web, this is passed to the `<fieldset>`'s `name` attribute.
+   */
+  name: PropTypes.string,
+  /**
+   * Use to visually mark an input as valid or invalid.
+   */
+  validation: PropTypes.oneOf(['error', 'success'])
+}
+
+export default Fieldset