@telus-uds/components-base 0.0.2-prerelease.7 → 1.0.1

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,43 +40,46 @@ const selectIconContainerStyles = ({ iconGap }) => ({
  * ### Accessibility
  * All accessibility props set on this component will be applied to the outer container.
  */
-const Feedback = ({ title, children, id, validation, tokens, variant, ...rest }) => {
-  const themeTokens = useThemeTokens('Feedback', tokens, { ...variant, validation })
-  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({
-    accessibilityRole: validation === 'error' ? 'alert' : undefined,
-    ...rest
-  })
+    const accessibilityProps = a11yProps.select({
+      accessibilityRole: validation === 'error' ? 'alert' : undefined,
+      ...rest
+    })
 
-  return (
-    <View style={selectStyles(themeTokens)} {...accessibilityProps} nativeID={id}>
-      <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 = {
   /**

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

package/src/Fieldset/FieldsetContainer.jsx

@@ -0,0 +1,31 @@
+import React, { forwardRef } from 'react'
+import PropTypes from 'prop-types'
+
+import cssReset from './cssReset'
+
+/**
+ * On Web, wraps children with a HTML `<fieldset>` and sets its attributes as necessary.
+ */
+const FieldsetContainer = forwardRef(
+  ({ children, inactive, accessibilityRole, name: fieldsetName }, ref) => (
+    <fieldset
+      ref={ref}
+      disabled={inactive}
+      style={cssReset}
+      role={accessibilityRole}
+      name={fieldsetName}
+    >
+      {children}
+    </fieldset>
+  )
+)
+FieldsetContainer.displayName = 'FieldsetContainer'
+
+FieldsetContainer.propTypes = {
+  accessibilityRole: PropTypes.string,
+  children: PropTypes.node,
+  inactive: PropTypes.bool,
+  name: PropTypes.string
+}
+
+export default FieldsetContainer

package/src/Fieldset/FieldsetContainer.native.jsx

@@ -0,0 +1,19 @@
+import React, { forwardRef } from 'react'
+import PropTypes from 'prop-types'
+import { View } from 'react-native'
+
+// No equivalent of `<fieldset>` on native, so just apply accessibility role to container.
+// If a11y testing finds any additional handling is needed at the container level, add it here.
+const FieldsetContainer = forwardRef(({ children, accessibilityRole }, ref) => (
+  <View ref={ref} accessibilityRole={accessibilityRole}>
+    {children}
+  </View>
+))
+FieldsetContainer.displayName = 'FieldsetContainer'
+
+FieldsetContainer.propTypes = {
+  children: PropTypes.node,
+  accessibilityRole: PropTypes.string
+}
+
+export default FieldsetContainer

package/src/Fieldset/Legend.jsx

@@ -0,0 +1,21 @@
+import React, { forwardRef } from 'react'
+import PropTypes from 'prop-types'
+
+import cssReset from './cssReset'
+
+/**
+ * On Web, wraps children in HTML `<legend>` tag.
+ * On Native, `<legend>` does not exist, wraps in a width 100% block to follow <legend>'s behaviour in a flex.
+ */
+const Legend = forwardRef(({ children }, ref) => (
+  <legend ref={ref} style={cssReset}>
+    {children}
+  </legend>
+))
+Legend.displayName = 'Legend'
+
+Legend.propTypes = {
+  children: PropTypes.node
+}
+
+export default Legend

package/src/Fieldset/Legend.native.jsx

@@ -0,0 +1,27 @@
+import React, { forwardRef } from 'react'
+import { View, StyleSheet } from 'react-native'
+import PropTypes from 'prop-types'
+
+/**
+ * On Web, wraps children in HTML `<legend>` tag.
+ * On Native, `<legend>` does not exist, wraps in a width 100% block to follow <legend>'s behaviour in a flex.
+ */
+const Legend = forwardRef(({ children }, ref) => (
+  <View ref={ref} style={staticStyles.stretch}>
+    {children}
+  </View>
+))
+Legend.displayName = 'Legend'
+
+Legend.propTypes = {
+  children: PropTypes.node
+}
+
+const staticStyles = StyleSheet.create({
+  stretch: {
+    width: '100%',
+    flexGrow: 1
+  }
+})
+
+export default Legend

package/src/Fieldset/cssReset.js

@@ -0,0 +1,14 @@
+// React Native Web has no built-in `fieldset` or `legend` support.
+// This reset makes them consistent with other RNW views.
+// Can't use RN stylesheets because it's not an RN element (RNW's createElement tooling is unstable).
+// Using CSS `all` doesn't work well as an inline style.
+// https://github.com/necolas/react-native-web/issues/1385
+export default {
+  margin: 'unset',
+  padding: 'unset',
+  float: 'unset',
+  border: 'unset',
+  width: 'unset',
+  display: 'flex',
+  flexDirection: 'column'
+}

package/src/Fieldset/index.js

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