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

package/src/StackView/StackWrapBox.jsx

@@ -1,13 +1,17 @@
-import React from 'react'
+import React, { forwardRef } from 'react'
 import PropTypes from 'prop-types'
 import { View } from 'react-native'
 
 import {
   spacingProps,
   a11yProps,
+  getTokensPropType,
   responsiveProps,
   useSpacingScale,
-  useResponsiveProp
+  useResponsiveProp,
+  viewProps,
+  getA11yPropsFromHtmlTag,
+  layoutTags
 } from '../utils'
 import { useThemeTokens } from '../ThemeProvider'
 import { useViewport } from '../ViewportProvider'
@@ -41,36 +45,53 @@ const spaceSides = {
  * Unlike the cleaner and more side-effect-free CSS gap StackWrap implementation, this renders a Box (View)
  * between the container and the stacked children, and requires a negative margin on the container.
  */
-const StackWrapBox = ({
-  space = 1,
-  gap = space,
-  direction: directionProp = 'row',
-  children,
-  tokens,
-  variant,
-  ...rest
-}) => {
-  const viewport = useViewport()
-  const direction = useResponsiveProp(directionProp, 'row')
-  const themeTokens = useThemeTokens('StackView', tokens, variant, { viewport })
-  const flexStyles = selectFlexStyles(themeTokens)
-  const a11y = a11yProps.select({ ...rest })
+const StackWrapBox = forwardRef(
+  (
+    {
+      space = 1,
+      gap = space,
+      direction: directionProp = 'row',
+      children,
+      tokens,
+      variant,
+      tag,
+      accessibilityRole,
+      ...rest
+    },
+    ref
+  ) => {
+    const viewport = useViewport()
+    const direction = useResponsiveProp(directionProp, 'row')
+    const themeTokens = useThemeTokens('StackView', tokens, variant, { viewport })
+    const flexStyles = selectFlexStyles(themeTokens)
+    const props = {
+      ...getA11yPropsFromHtmlTag(tag, accessibilityRole),
+      ...a11yProps.select(rest),
+      ...viewProps.select(rest)
+    }
 
-  // Mimic CSS `gap` using box spacing on the side after a wrapped row then offsetting it on the last row.
-  const gapSize = useSpacingScale(gap)
-  const offsetStyle = { [offsetSides[direction]]: -1 * gapSize }
-  const boxProps = { [gapSides[direction]]: gap, [spaceSides[direction]]: space }
-  const content = getStackedContent(children, { direction, space: 0, box: boxProps })
+    // Mimic CSS `gap` using box spacing on the side after a wrapped row then offsetting it on the last row.
+    const gapSize = useSpacingScale(gap)
+    const offsetStyle = { [offsetSides[direction]]: -1 * gapSize }
+    const boxProps = { [gapSides[direction]]: gap, [spaceSides[direction]]: space }
+    const content = getStackedContent(children, { direction, space: 0, box: boxProps })
 
-  return (
-    <View {...a11y} style={[flexStyles, staticStyles.wrap, staticStyles[direction], offsetStyle]}>
-      {content}
-    </View>
-  )
-}
+    return (
+      <View
+        ref={ref}
+        {...props}
+        style={[flexStyles, staticStyles.wrap, staticStyles[direction], offsetStyle]}
+      >
+        {content}
+      </View>
+    )
+  }
+)
+StackWrapBox.displayName = 'StackWrapBox'
 
 StackWrapBox.propTypes = {
   ...a11yProps.propTypes,
+  tokens: getTokensPropType('StackView'),
   /**
    * Sets the `flexDirection` of the container
    */
@@ -78,11 +99,24 @@ StackWrapBox.propTypes = {
     PropTypes.oneOf(['column', 'row', 'row-reverse', 'column-reverse'])
   ),
   /**
-   * The size of the spacer according to the theme's spacing scale.
+   * The size of the space between items 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 size of the space between lines of content, according to the theme's spacing scale. By default, matches `space`.
+   * 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).
+   */
+  gap: spacingProps.types.spacingValue,
+  /**
+   * Optional semantic HTML tag, to apply to the container on web. Does not change styling.
+   *
+   * In native apps, if a header tag is provided ("h1", "h2" etc) and accessibilityRole prop
+   * is not defined, the accessibilityRole will default to "heading".
+   */
+  tag: PropTypes.oneOf(layoutTags),
   /**
    * A StackWrap may take any children, but will have no effect if it is only passed one child or is passed children
    * wrapped in a component. If necessary, children may be wrapped in one React Fragment.

package/src/StackView/StackWrapGap.jsx

@@ -1,8 +1,14 @@
-import React from 'react'
+import React, { forwardRef } from 'react'
 import { View } from 'react-native'
 
 import StackWrapBox from './StackWrapBox'
-import { a11yProps, useSpacingScale, useResponsiveProp } from '../utils'
+import {
+  a11yProps,
+  useSpacingScale,
+  useResponsiveProp,
+  viewProps,
+  getA11yPropsFromHtmlTag
+} from '../utils'
 import { useThemeTokens } from '../ThemeProvider'
 import { useViewport } from '../ViewportProvider'
 import getStackedContent from './getStackedContent'
@@ -18,31 +24,47 @@ import { staticStyles, selectFlexStyles } from './common'
  * - The `space` between items is the same as the `gap` between wrapped rows (this is the
  *   default if `gap` prop is undefined)
  */
-const StackWrapGap = ({
-  space = 1,
-  tokens,
-  variant,
-  direction: directionProp = 'row',
-  children,
-  ...rest
-}) => {
-  const viewport = useViewport()
-  const direction = useResponsiveProp(directionProp, 'row')
-  const themeTokens = useThemeTokens('StackView', tokens, variant, { viewport })
-  const flexStyles = selectFlexStyles(themeTokens)
-  const a11y = a11yProps.select({ ...rest })
+const StackWrapGap = forwardRef(
+  (
+    {
+      space = 1,
+      tokens,
+      variant,
+      direction: directionProp = 'row',
+      children,
+      tag,
+      accessibilityRole,
+      ...rest
+    },
+    ref
+  ) => {
+    const viewport = useViewport()
+    const direction = useResponsiveProp(directionProp, 'row')
+    const themeTokens = useThemeTokens('StackView', tokens, variant, { viewport })
+    const flexStyles = selectFlexStyles(themeTokens)
+    const props = {
+      ...getA11yPropsFromHtmlTag(tag, accessibilityRole),
+      ...a11yProps.select(rest),
+      ...viewProps.select(rest)
+    }
 
-  const size = useSpacingScale(space)
-  const gapStyle = { gap: size }
+    const size = useSpacingScale(space)
+    const gapStyle = { gap: size }
 
-  const content = getStackedContent(children, { direction, space: 0 })
+    const content = getStackedContent(children, { direction, space: 0 })
 
-  return (
-    <View {...a11y} style={[flexStyles, staticStyles.wrap, staticStyles[direction], gapStyle]}>
-      {content}
-    </View>
-  )
-}
+    return (
+      <View
+        ref={ref}
+        {...props}
+        style={[flexStyles, staticStyles.wrap, staticStyles[direction], gapStyle]}
+      >
+        {content}
+      </View>
+    )
+  }
+)
+StackWrapGap.displayName = 'StackWrapGap'
 
 StackWrapGap.propTypes = StackWrapBox.propTypes
 

package/src/StackView/common.jsx

@@ -1,9 +1,10 @@
 import { StyleSheet } from 'react-native'
 
-export const selectFlexStyles = ({ alignItems, justifyContent, flexGrow }) => ({
+export const selectFlexStyles = ({ alignItems, justifyContent, flexGrow, flexShrink }) => ({
   alignItems,
   justifyContent,
-  flexGrow
+  flexGrow,
+  flexShrink
 })
 
 export const staticStyles = StyleSheet.create({

package/src/StackView/getStackedContent.jsx

@@ -23,17 +23,23 @@ import Spacer from '../Spacer'
  *  - `direction`: if 'row' or 'row-reverse', applies space horizontally, if 'column' or 'column-reverse', applies space vertically
  *  - `box`: if truthy, wraps each valid child in a Box component; if an object, passes it to Box as props
  *  - `divider`: if truthy, inserts Divider components; if an object, passes it to Divider as props
+ *  - `preserveFragments`: if true, adds no space between top-level elements that were passed inside a nested fragment
  * @param {SpacingValue} [options.space]
  * @param {boolean | object} [options.divider]
  * @param {"row" | "column" | "row-reverse" | "column-reverse"} [options.direction]
+ * @param {boolean} [options.preserveFragments]
  * @returns {ReactElement[]}
  */
-const getStackedContent = (children, { divider, space, direction = 'column', box }) => {
+const getStackedContent = (
+  children,
+  { divider, space, direction = 'column', box, preserveFragments = false }
+) => {
   const boxProps = box && typeof box === 'object' ? box : { space }
   const dividerProps = divider && typeof divider === 'object' ? divider : {}
 
   // Avoid surprises if children contains comments, nulls, or is a variable wrapped as a fragment
-  const validChildren = Children.toArray(unpackFragment(children)).filter(Boolean)
+  const topLevelChildren = preserveFragments ? children : unpackFragment(children)
+  const validChildren = Children.toArray(topLevelChildren).filter(Boolean)
   const content = validChildren.reduce((newChildren, child, index) => {
     const boxID = `Stack-Box-${index}`
     const item = box ? (

package/src/StepTracker/Step.jsx

@@ -0,0 +1,202 @@
+import React from 'react'
+import PropTypes from 'prop-types'
+import { StyleSheet, Text, View } from 'react-native'
+
+import StackView from '../StackView'
+import Icon from '../Icon'
+import { getTokensPropType, variantProp } from '../utils'
+import { applyTextStyles } from '../ThemeProvider'
+
+const selectCompletedIconTokens = ({ completedIconColor, completedIconSize }) => ({
+  size: completedIconSize,
+  color: completedIconColor
+})
+const selectConnectorStyles = (
+  {
+    connectorColor,
+    connectorHeight,
+    connectorMinWidth,
+    connectorCompletedHeight,
+    connectorCompletedColor
+  },
+  isCompleted
+) => ({
+  backgroundColor: connectorColor,
+  height: connectorHeight,
+  minWidth: connectorMinWidth,
+  ...(isCompleted && { height: connectorCompletedHeight, backgroundColor: connectorCompletedColor })
+})
+const selectCurrentInnerStyles = ({ knobCurrentInnerColor, knobCurrentInnerSize }) => ({
+  backgroundColor: knobCurrentInnerColor,
+  borderRadius: knobCurrentInnerSize / 2,
+  height: knobCurrentInnerSize,
+  width: knobCurrentInnerSize
+})
+const selectKnobStyles = (
+  {
+    knobBackgroundColor,
+    knobBorderColor,
+    knobBorderWidth,
+    knobCompletedBackgroundColor,
+    knobCompletedBorderColor,
+    knobCompletedPaddingLeft,
+    knobCompletedPaddingTop,
+    knobCurrentBackgroundColor,
+    knobCurrentBorderColor,
+    knobCurrentBorderWidth,
+    knobCurrentPaddingLeft,
+    knobCurrentPaddingTop,
+    knobSize
+  },
+  isCompleted,
+  isCurrent
+) => ({
+  backgroundColor: knobBackgroundColor,
+  borderColor: knobBorderColor,
+  borderRadius: knobSize / 2,
+  borderWidth: knobBorderWidth,
+  height: knobSize,
+  width: knobSize,
+  ...(isCompleted && {
+    backgroundColor: knobCompletedBackgroundColor,
+    borderColor: knobCompletedBorderColor,
+    paddingLeft: knobCompletedPaddingLeft,
+    paddingTop: knobCompletedPaddingTop
+  }),
+  ...(isCurrent && {
+    backgroundColor: knobCurrentBackgroundColor,
+    borderColor: knobCurrentBorderColor,
+    borderWidth: knobCurrentBorderWidth,
+    paddingLeft: knobCurrentPaddingLeft,
+    paddingTop: knobCurrentPaddingTop
+  })
+})
+const selectLabelContainerStyles = ({
+  labelDirection,
+  labelGap,
+  labelMarginTop,
+  labelPaddingLeft,
+  labelPaddingRight
+}) => ({
+  marginTop: labelMarginTop,
+  paddingLeft: labelPaddingLeft,
+  paddingRight: labelPaddingRight,
+  flexDirection: labelDirection,
+  gap: labelGap
+})
+const selectLabelStyles = (
+  {
+    labelColor,
+    labelCurrentColor,
+    labelCurrentFontWeight,
+    labelFontSize,
+    labelFontWeight,
+    labelFontName,
+    labelLineHeight
+  },
+  isCurrent
+) =>
+  applyTextStyles({
+    color: isCurrent ? labelCurrentColor : labelColor,
+    fontSize: labelFontSize,
+    lineHeight: labelLineHeight,
+    fontWeight: isCurrent ? labelCurrentFontWeight : labelFontWeight,
+    fontName: labelFontName
+  })
+const getStepTestID = (isCompleted, isCurrent) => {
+  let testID = 'StepTracker-Step'
+  if (isCompleted) {
+    testID += '-Completed'
+  } else if (isCurrent) {
+    testID += '-Current'
+  }
+
+  return testID
+}
+
+/**
+ * A single step of a StepTracker.
+ */
+const Step = ({ label, name, status = 0, stepCount = 0, stepIndex = 0, tokens }) => {
+  const { completedIcon, showStepLabel, showStepName, ...themeTokens } = tokens
+  const isFirst = stepIndex === 0
+  const isLast = stepIndex === stepCount - 1
+  const isCompleted = status > stepIndex
+  const isCurrent = status === stepIndex
+  const isActive = isCompleted || isCurrent
+
+  return (
+    <StackView
+      space={0}
+      tokens={{ alignItems: 'stretch', flexGrow: 1 }}
+      accessibilityLabel={label}
+      accessibilityLevel={2}
+      accessibilityCurrent={status === stepIndex ? 'true' : 'false'}
+    >
+      <StackView direction="row" space={0} tokens={{ alignItems: 'center', flexGrow: 0 }}>
+        <View
+          style={[staticStyles.connector, !isFirst && selectConnectorStyles(themeTokens, isActive)]}
+        />
+        <View
+          style={[staticStyles.knob, selectKnobStyles(themeTokens, isCompleted, isCurrent)]}
+          testID={getStepTestID(isCompleted, isCurrent)}
+        >
+          {isCompleted && completedIcon && (
+            <Icon icon={completedIcon} tokens={selectCompletedIconTokens(themeTokens)} />
+          )}
+          {isCurrent && <View style={selectCurrentInnerStyles(themeTokens)} />}
+        </View>
+        <View
+          style={[
+            staticStyles.connector,
+            !isLast && selectConnectorStyles(themeTokens, isCompleted)
+          ]}
+        />
+      </StackView>
+      {showStepLabel && (
+        <View style={[staticStyles.stepLabelContainer, selectLabelContainerStyles(tokens)]}>
+          {showStepName && (
+            <Text style={[staticStyles.centeredText, selectLabelStyles(tokens, isCurrent)]}>
+              {name}
+            </Text>
+          )}
+          <StackView direction="row">
+            <Text
+              style={[
+                staticStyles.centeredText,
+                tokens.labelDirection === 'column' && staticStyles.wrappingLabel,
+                selectLabelStyles(tokens, isCurrent)
+              ]}
+            >
+              {label}
+            </Text>
+          </StackView>
+        </View>
+      )}
+    </StackView>
+  )
+}
+
+Step.propTypes = {
+  label: PropTypes.string.isRequired,
+  name: PropTypes.string.isRequired,
+  status: PropTypes.number.isRequired,
+  stepCount: PropTypes.number.isRequired,
+  stepIndex: PropTypes.number.isRequired,
+  tokens: getTokensPropType('StepTracker'),
+  variant: variantProp.propType
+}
+
+export default Step
+
+const staticStyles = StyleSheet.create({
+  centeredText: { textAlign: 'center' },
+  connector: { flex: 1, height: 1 },
+  completedKnob: {
+    backgroundColor: 'transparent',
+    textAlign: 'center'
+  },
+  knob: { borderWidth: 1 },
+  stepLabelContainer: { justifyContent: 'center' },
+  wrappingLabel: { width: 0, flex: 1 }
+})

package/src/StepTracker/StepTracker.jsx

@@ -0,0 +1,174 @@
+import React, { forwardRef } from 'react'
+import PropTypes from 'prop-types'
+import { StyleSheet, Text, View } from 'react-native'
+
+import StackView from '../StackView'
+import { applyTextStyles, useThemeTokens } from '../ThemeProvider'
+import { getTokensPropType, variantProp } from '../utils'
+import { a11yProps } from '../utils/propTypes'
+import { useViewport } from '../ViewportProvider'
+import useCopy from '../utils/useCopy'
+
+import Step from './Step'
+import defaultDictionary from './dictionary'
+
+const selectContainerStyles = ({
+  containerPaddingBottom,
+  containerPaddingLeft,
+  containerPaddingRight,
+  containerPaddingTop
+}) => ({
+  paddingBottom: containerPaddingBottom,
+  paddingLeft: containerPaddingLeft,
+  paddingRight: containerPaddingRight,
+  paddingTop: containerPaddingTop
+})
+const selectStepTrackerLabelContainerStyles = ({ labelMarginTop }) => ({
+  marginTop: labelMarginTop
+})
+const selectStepTrackerLabelStyles = ({
+  labelColor,
+  labelFontSize,
+  labelFontWeight,
+  labelFontName,
+  labelLineHeight
+}) =>
+  applyTextStyles({
+    color: labelColor,
+    fontSize: labelFontSize,
+    lineHeight: labelLineHeight,
+    fontWeight: labelFontWeight,
+    fontName: labelFontName
+  })
+
+/**
+ * StepTracker component shows the current position in a sequence of steps.
+ *
+ * ## Component API
+ *
+ * - `current` prop allows to control the current step, 0-based number;
+ * - use `copy` and `dictionary` props to internationalize the labels;
+ * - `steps` is and array of strings defining step titles;
+ * - tokens and variant props define the appearance of the `StepTracker`:
+ *
+ * ## Usability and A11y guidelines
+ *
+ * Keep in mind that in its current implementation this is not an interactive
+ * component and can’t be used to navigate between steps. The application
+ * must provide its own navigation mechanism and state control. That is the
+ * main reason the component assumes the `progressbar` role in terms of
+ * accessibility. This also makes it extremely important to make sure you
+ * set a11y on controls used to modify the state of the step tracker.
+ *
+ * You can pass standard a11y props to the `StepTracker` component, including
+ * the ones that are specific to the `progressbar` role. By default the
+ * following props are used:
+ *
+ * - `accessibilityRole` (`role`): `progressbar`,
+ * - `accessibilityLabel` (`aria-label`): `Step I of N: <Current Step Label>`,
+ * - `accessibilityLevel` (`aria-level`): 1,
+ * - `accessibilityValue.min` (`aria-valuemin`): `0`,
+ * - `accessibilityValue.max` (`aria-valuemax`): `steps.length - 1`,
+ * - `accessibilityValue.now` (`aria-valuenow`): `current`,
+ * - `accessibilityValue.text` (`aria-valuetext`): `<Current Step Label>`,
+ *
+ */
+const StepTracker = forwardRef(
+  (
+    {
+      current = 0,
+      copy = 'en',
+      dictionary = defaultDictionary,
+      steps = [],
+      tokens,
+      variant,
+      ...rest
+    },
+    ref
+  ) => {
+    const viewport = useViewport()
+    const { showStepTrackerLabel, ...themeTokens } = useThemeTokens(
+      'StepTracker',
+      tokens,
+      variant,
+      {
+        viewport
+      }
+    )
+    const getCopy = useCopy({ dictionary, copy })
+    const stepTrackerLabel = getCopy('stepTrackerLabel')
+      .replace('%{stepNumber}', current < steps.length ? current + 1 : steps.length)
+      .replace('%{stepCount}', steps.length)
+      .replace('%{stepLabel}', current < steps.length ? steps[current] : steps[steps.length - 1])
+    if (!steps.length) return null
+    const accessibilityProps = {
+      accessibilityLabel: stepTrackerLabel,
+      accessibilityLevel: 1,
+      accessibilityRole: 'progressbar',
+      accessibilityValue: {
+        min: 0,
+        max: steps.length - 1,
+        now: current,
+        text: steps[current]
+      },
+      ...a11yProps.select(rest)
+    }
+
+    return (
+      <View ref={ref} style={selectContainerStyles(themeTokens)} {...accessibilityProps}>
+        <StackView space={0}>
+          <View style={staticStyles.stepsContainer}>
+            {steps.map((label, index) => {
+              return (
+                <Step
+                  status={current}
+                  key={label}
+                  label={label}
+                  name={getCopy('stepLabel').replace('%{stepNumber}', index + 1)}
+                  stepIndex={index}
+                  stepCount={steps.length}
+                  tokens={themeTokens}
+                />
+              )
+            })}
+          </View>
+          {showStepTrackerLabel && (
+            <View
+              style={[
+                staticStyles.stepTrackerLabelContainer,
+                selectStepTrackerLabelContainerStyles(themeTokens)
+              ]}
+            >
+              <Text style={selectStepTrackerLabelStyles(themeTokens)}>{stepTrackerLabel}</Text>
+            </View>
+          )}
+        </StackView>
+      </View>
+    )
+  }
+)
+StepTracker.displayName = 'StepTracker'
+
+StepTracker.propTypes = {
+  current: PropTypes.number,
+  copy: PropTypes.oneOf(['en', 'fr']),
+  dictionary: PropTypes.shape({
+    en: PropTypes.shape({ stepLabel: PropTypes.string, stepTrackerLabel: PropTypes.string }),
+    fr: PropTypes.shape({ stepLabel: PropTypes.string, stepTrackerLabel: PropTypes.string })
+  }),
+  steps: PropTypes.arrayOf(PropTypes.string),
+  tokens: getTokensPropType('StepTracker'),
+  variant: variantProp.propType
+}
+
+export default StepTracker
+
+const staticStyles = StyleSheet.create({
+  stepsContainer: {
+    alignItems: 'flex-start',
+    flexDirection: 'row',
+    justifyContent: 'space-evenly',
+    flexGrow: 1
+  },
+  stepTrackerLabelContainer: { textAlign: 'center', flexDirection: 'row', justifyContent: 'center' }
+})

package/src/StepTracker/dictionary.js

@@ -0,0 +1,10 @@
+export default {
+  en: {
+    stepLabel: 'Step %{stepNumber}',
+    stepTrackerLabel: 'Step %{stepNumber} of %{stepCount}: %{stepLabel}'
+  },
+  fr: {
+    stepLabel: 'Étape %{stepNumber}',
+    stepTrackerLabel: 'Étape %{stepNumber} sur %{stepCount}: %{stepLabel}'
+  }
+}

package/src/StepTracker/index.js

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