@telus-uds/components-base 0.0.2-prerelease.4 → 0.0.2-prerelease.8

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/Divider/Divider.jsx

@@ -2,7 +2,12 @@ import React from 'react'
 import PropTypes from 'prop-types'
 import { View, StyleSheet, Platform } from 'react-native'
 import { useThemeTokens } from '../ThemeProvider'
-import { getTokensPropType, variantProp } from '../utils/propTypes'
+import Spacer from '../Spacer'
+import { getTokensPropType, variantProp, spacingProps } from '../utils'
+/**
+ * @typedef {import('../utils/propTypes.js').SpacingIndex} SpacingIndex
+ * @typedef {import('../utils/propTypes.js').SpacingObject} SpacingObject
+ */
 
 /**
  * A basic divider component, horizontal by default. Color and thickness can be controlled by theme.
@@ -16,11 +21,31 @@ import { getTokensPropType, variantProp } from '../utils/propTypes'
  *
  * In a flexbox row, vertical dividers will automatically size to their parent height.
  *
+ * ## Space
+ *
+ * Use this to create **space either side of the divider**. For simple cases, pass a number referring to
+ * a position on the theme's spacing scale; for example, this will put a Spacer of the smallest supported
+ * size either side of the divider:
+ *
+ * ```jsx
+ * <Divider space={1} />
+ * ```
+ *
+ * `space` prop uses `useSpacingScale` and may accept a {@link SpacingObject} or a {@link SpacingIndex} number.
+ *
+ * To **reduce the length of a divider** as well as creating space between it and its neighbours, wrap it in
+ * a `Box` component. For example, this will have the second-smallest theme-supported spacing value between
+ * the dividing line and its neighbours, and will shorten the line at either end by the same amount:
+ *
+ * ```jsx
+ * <Box space={2}><Divider /></Box>
+ * ```
+ *
  * ## Accessibility
  *
  * 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, tokens, testID }) => {
+const Divider = ({ variant, vertical = false, space, tokens, testID }) => {
   const { color, width } = useThemeTokens('Divider', tokens, variant)
 
   const borderStyles = vertical
@@ -43,11 +68,21 @@ const Divider = ({ variant, vertical = false, tokens, testID }) => {
       : // There are no such equivalent attributes for native
         {}
 
-  return <View style={[styles.divider, borderStyles]} testID={testID} {...a11y} />
+  const divider = <View style={[styles.divider, borderStyles]} testID={testID} {...a11y} />
+  if (!space) return divider
+  const spacerProps = { space, direction: vertical ? 'row' : 'column' }
+  return (
+    <>
+      <Spacer {...spacerProps} testID={testID ? `${testID}-Spacer-before` : undefined} />
+      {divider}
+      <Spacer {...spacerProps} testID={testID ? `${testID}-Spacer-after` : undefined} />
+    </>
+  )
 }
 
 Divider.propTypes = {
   tokens: getTokensPropType('Divider'),
+  space: spacingProps.types.spacingValue,
   variant: variantProp.propType,
   /**
    * By default, the divider is a horizontal line the full width of its parent.

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

@@ -0,0 +1,108 @@
+import React from 'react'
+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)
+
+const selectTitleTextStyles = ({ titleFontSize, ...tokens }) =>
+  applyTextStyles(selectTokens('Typography', { ...tokens, fontSize: titleFontSize }))
+const selectContentTextStyles = ({ contentFontSize, ...tokens }) =>
+  applyTextStyles(selectTokens('Typography', { ...tokens, fontSize: contentFontSize }))
+
+const selectIconTokens = ({ iconSize, iconColor }) => ({
+  size: iconSize,
+  color: iconColor
+})
+
+const selectIconContainerStyles = ({ iconGap }) => ({
+  paddingRight: iconGap
+})
+
+/**
+ * A feedback box commonly used with form fields.
+ *
+ * ### Standalone usage
+ * While its primary use is to facilitate feedback states for other form components such as `TextInput`,
+ * you may use it standalone.
+ *
+ * ### Complex content
+ * You may pass any React tree as the children of this component, bear in mind that a render function
+ * is better suited for styling children based on Feedback's variant.
+ *
+ * ### Using a render function
+ * When a function is passed for rendering content, it will receive the feedback text styles and
+ * variant as arguments.
+ *
+ * ### 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 { icon: IconComponent } = themeTokens
+
+  const titleTextStyles = selectTitleTextStyles(themeTokens)
+  const contentTextStyles = selectContentTextStyles(themeTokens)
+
+  const content =
+    typeof children === 'string' ? <Text style={contentTextStyles}>{children}</Text> : children
+
+  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 {...selectIconTokens(themeTokens)} />
+              </View>
+            )}
+            <Text style={titleTextStyles}>{title}</Text>
+          </View>
+        )}
+        {content && typeof content === 'function'
+          ? content({ textStyles: contentTextStyles, variant })
+          : content}
+      </StackView>
+    </View>
+  )
+}
+
+Feedback.propTypes = {
+  /**
+   * Emphasized summary of the feedback. If an icon is set, it is rendered next to the title.
+   */
+  title: PropTypes.string,
+  /**
+   * 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
+}
+
+export default Feedback
+
+const staticStyles = StyleSheet.create({
+  title: {
+    display: 'flex',
+    flexDirection: 'row',
+    alignItems: 'center'
+  }
+})

package/src/Feedback/index.js

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

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