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

package/src/StackView/getStackedContent.jsx

@@ -0,0 +1,112 @@
+import React, { Children, Fragment } from 'react'
+
+import Box from '../Box'
+import Divider from '../Divider'
+import Spacer from '../Spacer'
+
+/**
+ * @typedef {import('react').ReactChildren} ReactChildren
+ * @typedef {import('react').ReactElement} ReactElement
+ * @typedef {import('../utils/propTypes.js').SpacingValue} SpacingValue
+ */
+
+/**
+ * Takes valid React Children and inserts a specified amount of space between each valid (not nullish) top
+ * level element, according to the provided `options`.
+ *
+ * Returns an array of the original elements plus inserted spacing elements.
+ * This array of elements is keyed and may be used as a component's `children` without mapping.
+ *
+ * @param {ReactChildren} children
+ * @param {object} [options] -
+ *  - `space`: amount of space to insert using the theme spacing scale (see `useSpacingScale`)
+ *  - `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, 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 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 ? (
+      // If wrapped in Box, that Box needs a key.
+      // If possible, use an existing content key; use an index-based key only if necessary.
+      <Box {...boxProps} key={child.key || boxID} testID={boxID}>
+        {child}
+      </Box>
+    ) : (
+      child
+    )
+    if (!index || (!space && !divider)) return [...newChildren, item]
+
+    const testID = `Stack-${divider ? 'Divider' : 'Spacer'}-${index}`
+    const commonProps = { testID, key: testID, space }
+    const separator = divider ? (
+      <Divider vertical={direction.startsWith('row')} {...dividerProps} {...commonProps} />
+    ) : (
+      <Spacer direction={direction.startsWith('row') ? 'row' : 'column'} {...commonProps} />
+    )
+    return [...newChildren, separator, item]
+  }, [])
+
+  return content
+}
+
+/**
+ * Unpacks top-level fragments, so that common compositional patterns such as the following examples
+ * can be iterated as flat siblings (as if they were `<Child1 /><Child2 /><Child3 />`):
+ *
+ * - Setting `children` as a property wrapped in a fragment:
+ *
+ * ```jsx
+ * args.children = <><Child1 /><Child2 /><Child3 /></>
+ * ```
+ *
+ * - Defining `children` as a variable wrapped in a fragment:
+ *
+ * ```jsx
+ * const content = <><Child1 /><Child2 /><Child3 /></>
+ * if (someCondition) return <SomeWrapper>{content}</SomeWrapper>
+ * ```
+ *
+ * - Using fragments at the top level of a JSX block for conditional rendering:
+ *
+ * ```jsx
+ * <Child1 />
+ * {someCondition && (
+ *   <>
+ *     <Child2 />
+ *     <Child3 />
+ *   </>
+ * )}
+ * ```
+ *
+ * @param {ReactChildren} child
+ * @returns {ReactChildren}
+ */
+const unpackFragment = (child) => {
+  // If this level is a set of top-level siblings rather than one child, check each in turn
+  if (Children.count(child) > 1) return Children.map(child, unpackFragment)
+
+  // When a fragment is found, unpack its children to the top level and check them
+  if (child?.type === Fragment) return unpackFragment(child.props?.children)
+
+  // Stop unpacking as soon as any non-fragment child is found
+  return child
+}
+
+export default getStackedContent

package/src/StackView/index.js

@@ -0,0 +1,6 @@
+import StackView from './StackView'
+import StackWrap from './StackWrap'
+
+export default StackView
+export { StackWrap }
+export { default as getStackedContent } from './getStackedContent'

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,163 @@
+import React 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 = ({
+  current = 0,
+  copy = 'en',
+  dictionary = defaultDictionary,
+  steps = [],
+  tokens,
+  variant,
+  ...rest
+}) => {
+  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 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.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

package/src/Tabs/HorizontalScroll.jsx

@@ -0,0 +1,165 @@
+import React, { useEffect, useRef, useState } from 'react'
+import PropTypes from 'prop-types'
+import { Platform, StyleSheet, View } from 'react-native'
+
+import { validateThemeTokens, resolveThemeTokens } from '../ThemeProvider'
+import { getTokensSetPropType, selectTokens, a11yProps } from '../utils'
+import ScrollViewEnd from './ScrollViewEnd'
+import { getItemPositionScrollTarget, itemPositionsPropType } from './itemPositions'
+
+const tokenKeys = [
+  'nextIcon',
+  'previousIcon',
+  'gutter',
+  'borderBottomWidth',
+  'borderBottomColor',
+  'buttonClearance'
+]
+export const selectHorizontalScrollTokens = (themeTokens, prefix) =>
+  selectTokens(tokenKeys, themeTokens, prefix)
+
+/**
+ * Base component that scrolls horizontally and displays left and right buttons if
+ * there is content to the left and the right which can be scrolled to.
+ *
+ * @TODO revist `ScrollButton` after IconButton is stable.
+ */
+const HorizontalScroll = ({ ScrollButton, tokens, itemPositions, children, ...rest }) => {
+  const {
+    nextIcon,
+    previousIcon,
+    gutter,
+    borderBottomWidth,
+    borderBottomColor,
+    buttonClearance = 0
+  } = validateThemeTokens(
+    resolveThemeTokens(tokens),
+    // Allow missing icons
+    getTokensSetPropType(tokenKeys, { partial: true }),
+    'HorizontalScroll'
+  )
+
+  const [containerWidth, setContainerWidth] = useState(0)
+  const [contentWidth, setContentWidth] = useState(0)
+  const handleContentWidth = (width) => setContentWidth(width)
+  const handleContainerLayout = ({
+    nativeEvent: {
+      layout: { width }
+    }
+  }) => setContainerWidth(width)
+
+  // Update the scroll position only when scrolling actions ends to minimally rerender
+  // and update which buttons are conditionally rendered.
+  const [scrollOffset, setScrollOffset] = useState(0)
+  const handleScrollEnd = ({
+    nativeEvent: {
+      contentOffset: { x }
+    }
+  }) => {
+    setScrollOffset(x)
+  }
+
+  const scrollMax = Math.max(0, contentWidth - containerWidth)
+  const showNextButton = scrollOffset < scrollMax
+  const showPreviousButton = scrollOffset > 0
+
+  const scrollRef = useRef(null)
+  const scrollTo = (targetX) => {
+    if (typeof scrollRef.current?.scrollTo === 'function') {
+      const x = getItemPositionScrollTarget(
+        targetX,
+        scrollMax,
+        itemPositions.positions,
+        buttonClearance
+      )
+      scrollRef.current.scrollTo({ x, animated: true })
+
+      if (Platform.OS === 'android') {
+        // React Native calls onScrollMomentumEnd after scrollTo for iOS, but not Android.
+        // See https://github.com/facebook/react-native/issues/26661
+        // There's also no callback for when scrollTo finishes.
+        setTimeout(() => setScrollOffset(x), 300)
+      }
+    }
+  }
+  // Make scrollTo and relevant co-ordinates available to any component with an interest in itemPositions.
+  // ItemPositions is a mutable ref object intended to have its properties mutated without any rerenders.
+  /* eslint-disable-next-line no-param-reassign */
+  itemPositions.scrollTo = scrollTo
+  /* eslint-disable-next-line no-param-reassign */
+  itemPositions.containerWidth = containerWidth
+  /* eslint-disable-next-line no-param-reassign */
+  itemPositions.contentWidth = contentWidth
+  /* eslint-disable-next-line no-param-reassign */
+  itemPositions.scrollOffset = scrollOffset
+
+  const hasWidths = itemPositions.contentWidth > 0 && itemPositions.contentWidth > 0
+  useEffect(() => {
+    if (hasWidths) itemPositions.setIsReady(true)
+    // itemPositions is a ref object so this should occur only when elements' widths are set in state
+  }, [hasWidths, itemPositions])
+
+  // When scrolling, allow clearance around scroll buttons, so e.g. this...
+  // (<-) Item 5   Item 6   Item 7   Item 8   It(->)
+  // ...doesn't scroll like this with Item 9 never being properly visible:
+  // (<-)em 9   Item 10  Item 11  Item 12  Item (->)
+  const scrollDistance = containerWidth - buttonClearance * 2
+  const scrollNext = () => scrollTo(scrollOffset + scrollDistance)
+  const scrollPrevious = () => scrollTo(scrollOffset - scrollDistance)
+
+  const a11y = a11yProps.select(rest)
+
+  // On Web, being scrollable in one direction prevents overflow: visible in the other direction.
+  // Apply a fixed margin gutter that tab highlight effects can overhang without getting trimmed.
+  return (
+    <View style={staticStyles.container}>
+      <ScrollViewEnd
+        onScrollEnd={handleScrollEnd}
+        ref={scrollRef}
+        horizontal
+        onContentSizeChange={handleContentWidth}
+        onLayout={handleContainerLayout}
+        showsHorizontalScrollIndicator={false}
+        contentContainerStyle={[
+          staticStyles.scrollContainer,
+          { marginBottom: gutter, borderBottomWidth, borderBottomColor }
+        ]}
+        {...a11y}
+      >
+        {children}
+      </ScrollViewEnd>
+      {showPreviousButton && (
+        <ScrollButton
+          icon={previousIcon}
+          onPress={scrollPrevious}
+          offset={gutter}
+          direction="previous"
+        />
+      )}
+      {showNextButton && (
+        <ScrollButton icon={nextIcon} onPress={scrollNext} offset={gutter} direction="next" />
+      )}
+    </View>
+  )
+}
+
+const staticStyles = StyleSheet.create({
+  scrollContainer: {
+    // Gives inner container width from content, allowing it to exceed its container's width
+    alignSelf: 'flex-start',
+    flexGrow: 1
+  },
+  container: {
+    // Vertically center the ScrollButtons buttons
+    justifyContent: 'center'
+  }
+})
+
+HorizontalScroll.propTypes = {
+  itemPositions: itemPositionsPropType,
+  ScrollButton: PropTypes.elementType,
+  tokens: getTokensSetPropType(tokenKeys, { allowFunction: true }),
+  children: PropTypes.node
+}
+
+export default HorizontalScroll