@telus-uds/components-base 0.0.2-prerelease.5 → 0.0.2-prerelease.9

package/src/Checkbox/CheckboxGroup.jsx

@@ -0,0 +1,196 @@
+import React from 'react'
+import PropTypes from 'prop-types'
+
+import { useViewport } from '../ViewportProvider'
+import { useThemeTokens } from '../ThemeProvider'
+import { getTokensPropType, useMultipleInputValues, variantProp } from '../utils'
+import { getStackedContent } from '../StackView'
+import Checkbox from './Checkbox'
+import Fieldset from '../Fieldset'
+
+/**
+ * A group of Checkboxs that behave as a fieldset. Use when users select any number of choices from options.
+ *
+ * ## Component API
+ *
+ * Use the `items` prop to pass an array of objects describing each Checkbox in the group:
+ *
+ *  - `label`: main text passed to CheckboxGroup's `label` prop
+ *  - `id`: identifier used to store which CheckboxGroup is selected (uses `label` if undefinded)
+ *  - `onChange`: optional function called on selection, in addition to updating the group's selection state
+ *
+ * ### Controlled version
+ *
+ * If the selection state is controlled from outside, it needs to receive `checkedId` and `onChange` props.
+ *
+ * ### Uncontrolled version
+ *
+ * If the CheckboxGroup manages its own state, you can use `initialCheckedId` prop to provide the initial value.
+ * Whenever the radio card gets toggled, it calls the `onChange` callback with the new value (string).
+ *
+ * ### Use in forms
+ *
+ * For web forms, the `name` prop may be used to define the name of the group's `fieldset` and input elements.
+ *
+ * ### Validation
+ *
+ * Validation state may be set by passing 'error' or 'success' to the `validation` prop.
+ *
+ * ## A11y guidelines
+ *
+ * CheckboxGroup accepts all the common accessibility props, and controls the accessibility state
+ * of children like Checkbox and Feedback based on current state.
+ *
+ * @example
+ * ```jsx
+ * <CheckboxGroup
+ *   initialCheckedId="check1"
+ *   items={[
+ *     { label: 'Checkbox 1', id: 'check1' },
+ *     { label: 'Checkbox 2', id: 'check2' },
+ *     { label: 'Checkbox 3', id: 'check3' }
+ *   ]}
+ *   legend="Checkboxes"
+ *   hint="Choose from these options"
+ * />
+ * ```
+ */
+const CheckboxGroup = ({
+  tokens,
+  radioTokens,
+  variant,
+  items = [],
+  legend,
+  tooltip,
+  hint,
+  validation,
+  feedback,
+  initialCheckedIds,
+  checkedIds,
+  onChange,
+  readOnly,
+  name: inputGroupName,
+  inactive
+}) => {
+  const viewport = useViewport()
+
+  const { space, fieldSpace } = useThemeTokens('CheckboxGroup', tokens, variant, {
+    viewport
+  })
+
+  const { currentValues, toggleOneValue } = useMultipleInputValues({
+    values: checkedIds,
+    initialValues: initialCheckedIds,
+    onChange,
+    readOnly: readOnly || inactive
+  })
+  const checkboxes = items.map(({ label, id, onChange: itemOnChange }, index) => {
+    const checkboxId = id || `Checkbox[${index}]`
+    const handleChange = (...args) => {
+      if (typeof itemOnChange === 'function') itemOnChange(...args)
+      toggleOneValue(checkboxId)
+    }
+    return (
+      <Checkbox
+        key={checkboxId}
+        id={checkboxId}
+        checked={currentValues.includes(checkboxId)}
+        onChange={handleChange}
+        inactive={inactive}
+        label={label}
+        name={inputGroupName}
+        tokens={radioTokens}
+        variant={variant}
+      />
+    )
+  })
+
+  return (
+    <Fieldset
+      name={inputGroupName}
+      legend={legend}
+      tooltip={tooltip}
+      hint={hint}
+      space={fieldSpace}
+      feedback={feedback}
+      inactive={inactive}
+      status={validation}
+    >
+      {getStackedContent(checkboxes, { space, direction: 'column' })}
+    </Fieldset>
+  )
+}
+
+CheckboxGroup.propTypes = {
+  /**
+   * Optional theme token overrides for the outer CheckboxGroup component
+   */
+  tokens: getTokensPropType('CheckboxGroup'),
+  /**
+   * Optional theme token overrides for each inner Checkbox component
+   */
+  radioTokens: getTokensPropType('Checkbox'),
+  /**
+   * Theme variants, shared between both CheckboxGroup and Checkbox
+   */
+  variant: variantProp.propType,
+  /**
+   * Array of objects containing specifics for each Checkbox to be rendered in the group.
+   */
+  items: PropTypes.arrayOf(
+    PropTypes.exact({
+      label: PropTypes.string,
+      id: PropTypes.string,
+      onChange: PropTypes.func
+    })
+  ),
+  /**
+   * 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 provided, the checkboxed with this ids are selected on first render.
+   */
+  initialCheckedIds: PropTypes.arrayOf(PropTypes.string),
+  /**
+   * If not undefined, the checkboxes with these ids is selected, and the
+   * element's selection state will be controlled by its parent using the `onChange` function.
+   */
+  checkedIds: PropTypes.arrayOf(PropTypes.string),
+  /**
+   * Function to call on change in selection state. Is required if the selection state is controlled
+   * by a parent using checkedId and the input is not readOnly.
+   */
+  onChange: PropTypes.func,
+  /**
+   * If true, the radio cards 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
+   * 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.
+   */
+  name: PropTypes.string
+}
+
+export default CheckboxGroup

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/ExpandCollapse/Control.jsx

@@ -82,7 +82,7 @@ const ExpandCollapseControl = ({
           <>
             {IconComponent && (
               <View style={selectIconContainerStyles(themeTokens)}>
-                <IconComponent tokens={selectIconTokens(themeTokens)} />
+                <IconComponent {...selectIconTokens(themeTokens)} />
               </View>
             )}
             {typeof children === 'function' ? children(getControlState(pressableState)) : children}

package/src/Feedback/Feedback.jsx

@@ -1,9 +1,10 @@
 import React from 'react'
-import { Text, View, StyleSheet } from 'react-native'
+import { StyleSheet, Text, View } from 'react-native'
 import PropTypes from 'prop-types'
 
 import { applyTextStyles, useThemeTokens } from '../ThemeProvider'
 import { a11yProps, getTokensPropType, selectTokens, variantProp } from '../utils'
+import StackView from '../StackView'
 
 const selectStyles = (tokens) => selectTokens('Feedback', tokens)
 
@@ -39,8 +40,9 @@ 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 Feedback = ({ title, children, id, validation, tokens, variant, ...rest }) => {
+  const themeTokens = useThemeTokens('Feedback', tokens, { ...variant, validation })
+  const { space } = themeTokens
 
   const { icon: IconComponent } = themeTokens
 
@@ -50,27 +52,28 @@ const Feedback = ({ title, children, tokens, variant, ...rest }) => {
   const content =
     typeof children === 'string' ? <Text style={contentTextStyles}>{children}</Text> : children
 
-  const accessibilityProps = a11yProps.select(rest)
-
-  // TODO: use Stack to separate the title from content (space 2)
+  const accessibilityProps = a11yProps.select({
+    accessibilityRole: validation === 'error' ? 'alert' : undefined,
+    ...rest
+  })
 
   return (
-    <View style={selectStyles(themeTokens)} {...accessibilityProps}>
-      {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 })
-      ) : (
-        <View>{content}</View>
-      )}
+    <View 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>
   )
 }
@@ -84,6 +87,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,129 @@
+import React 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 = ({
+  space,
+  feedback,
+  feedbackPosition = 'top',
+  validation,
+  legend,
+  hint,
+  hintPosition,
+  tooltip,
+  inactive,
+  accessibilityRole,
+  name: fieldsetName,
+  children
+}) => {
+  // 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
+      inactive={inactive}
+      accessibilityRole={accessibilityRole}
+      name={fieldsetName}
+    >
+      {stackedContent}
+    </FieldsetContainer>
+  )
+}
+
+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,22 @@
+import React 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 = ({ children, inactive, accessibilityRole, name: fieldsetName }) => (
+  <fieldset disabled={inactive} style={cssReset} role={accessibilityRole} name={fieldsetName}>
+    {children}
+  </fieldset>
+)
+
+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,16 @@
+import React 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 = ({ children, accessibilityRole }) => (
+  <View accessibilityRole={accessibilityRole}>{children}</View>
+)
+
+FieldsetContainer.propTypes = {
+  children: PropTypes.node,
+  accessibilityRole: PropTypes.string
+}
+
+export default FieldsetContainer

package/src/Fieldset/Legend.jsx

@@ -0,0 +1,16 @@
+import React 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 = ({ children }) => <legend style={cssReset}>{children}</legend>
+
+Legend.propTypes = {
+  children: PropTypes.node
+}
+
+export default Legend

package/src/Fieldset/Legend.native.jsx

@@ -0,0 +1,22 @@
+import React 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 = ({ children }) => <View style={staticStyles.stretch}>{children}</View>
+
+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

package/src/Icon/Icon.jsx

@@ -3,20 +3,30 @@ import { Platform, View } from 'react-native'
 import PropTypes from 'prop-types'
 
 import { useThemeTokens } from '../ThemeProvider'
-import { getTokensPropType, variantProp } from '../utils/propTypes'
+import { getTokensPropType, scaleWithText, variantProp } from '../utils'
 
-const Icon = ({ IconSvg, variant, label, titleId, tokens = {} }) => {
+const Icon = ({
+  icon: IconComponent,
+  accessibilityLabel,
+  variant,
+  tokens,
+  scalesWithText = false
+}) => {
   const themeTokens = useThemeTokens('Icon', tokens, variant)
+
+  const size = scalesWithText ? scaleWithText(themeTokens.size) : themeTokens.size
+
   const iconContent = (
-    <IconSvg title={label} titleId={titleId} size={themeTokens.size} color={themeTokens.color} />
+    <IconComponent title={accessibilityLabel} size={size} color={themeTokens.color} />
   )
 
   return Platform.OS === 'web' ? (
     <View
       // eslint-disable-next-line react-native/no-inline-styles
       style={{
-        // TODO: https://github.com/telus/universal-design-system/issues/487
-        transition: 'transform 200ms',
+        // TODO: systematise animations.
+        // https://github.com/telus/universal-design-system/issues/487
+        transition: 'transform 200ms, color 200ms',
         transform: [
           themeTokens.scale ? `scale(${themeTokens.scale})` : '',
           themeTokens.translateX ? `translateX(${themeTokens.translateX}px)` : '',
@@ -33,41 +43,26 @@ const Icon = ({ IconSvg, variant, label, titleId, tokens = {} }) => {
   )
 }
 
-// Auto-generated SVG icon components wrap Icon and pass through these props:
 export const iconComponentPropTypes = {
   variant: variantProp.propType,
   tokens: getTokensPropType('Icon'),
   /**
    * Descriptive label used in web SVG title tag for accessibility
    */
-  label: PropTypes.string,
-  /**
-   * On web, this unique id is applied to <SVG> title and aria-labelledby attr
-   */
-  titleId: PropTypes.string
-}
-
-// Auto-generated SVG icon components contain an inner SVG component taking these props:
-export const iconSvgPropTypes = {
-  title: iconComponentPropTypes.label,
-  titleId: iconComponentPropTypes.titleId,
-  /**
-   * The size of the SVG icon after resolving tokens
-   */
-  size: PropTypes.number,
+  accessibilityLabel: PropTypes.string,
   /**
-   * The color of the SVG icon after resolving tokens
+   * controls whether the icon size should be proportionate to any accessibility-related font scaling.
    */
-  color: PropTypes.string
+  scalesWithText: PropTypes.bool
 }
 
 Icon.propTypes = {
   ...iconComponentPropTypes,
   /**
-   * Function component containing this icon's SVG or native equivalent.
-   * UDS's SVGR config turns static SVG files into components that pass this to <Icon>.
+   * A valid UDS icon component imported from a UDS palette
+   * (e.g.) `import { MyIcon } from @telus-uds/palette-<brand>/build/web/icons`
    */
-  IconSvg: PropTypes.func.isRequired
+  icon: PropTypes.elementType.isRequired
 }
 
 export default Icon