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

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

package/src/Tabs/Tabs.jsx

@@ -0,0 +1,97 @@
+import React, { forwardRef, useCallback } from 'react'
+import PropTypes from 'prop-types'
+import ABBPropTypes from 'airbnb-prop-types'
+
+import { useThemeTokens } from '../ThemeProvider'
+import StackView from '../StackView'
+import { getTokensPropType, variantProp, useHash, useInputValue } from '../utils'
+import HorizontalScroll, {
+  horizontalScrollUtils,
+  HorizontalScrollButton
+} from '../HorizontalScroll'
+import TabsItem from './TabsItem'
+
+const { selectHorizontalScrollTokens, useItemPositions } = horizontalScrollUtils
+
+/**
+ * Tabs renders a horizontally-scrolling menu of selectable buttons which may link
+ * to a page or control what content is displayed on this page.
+ */
+const Tabs = forwardRef(
+  (
+    { tokens, itemTokens, scrollButtonTokens, variant, value, initialValue, onChange, items = [] },
+    ref
+  ) => {
+    const { space, ...themeTokens } = useThemeTokens('Tabs', tokens, variant)
+    const { currentValue, setValue } = useInputValue({ value, initialValue, onChange })
+
+    const [itemPositions, isPositioningReady] = useItemPositions()
+
+    useHash(
+      useCallback(
+        (hash, event) => {
+          const hashItem = hash && items.find(({ href }) => hash === href)
+          const hashId = hashItem && (hashItem.id || hashItem.label)
+          if (hashId) setTimeout(setValue(hashId, event), 500)
+        },
+        [items, setValue]
+      ),
+      isPositioningReady
+    )
+
+    return (
+      <HorizontalScroll
+        ref={ref}
+        ScrollButton={HorizontalScrollButton}
+        itemPositions={itemPositions}
+        tokens={selectHorizontalScrollTokens(themeTokens)}
+        scrollButtonTokens={scrollButtonTokens}
+        accessibilityRole="tablist"
+      >
+        <StackView space={space} direction="row">
+          {items.map(({ href, label, id, ref: itemRef }, index) => {
+            const itemId = id ?? label
+            const isSelected = Boolean(currentValue && currentValue === itemId)
+            const handlePress = (event) => setValue(itemId, event)
+            return (
+              <TabsItem
+                ref={itemRef}
+                key={itemId}
+                href={href}
+                variant={variant}
+                tokens={itemTokens}
+                onPress={handlePress}
+                selected={isSelected}
+                itemPositions={itemPositions}
+                index={index}
+              >
+                {label}
+              </TabsItem>
+            )
+          })}
+        </StackView>
+      </HorizontalScroll>
+    )
+  }
+)
+Tabs.displayName = 'Tabs'
+
+Tabs.propTypes = {
+  items: PropTypes.arrayOf(
+    PropTypes.shape({
+      href: PropTypes.string,
+      label: PropTypes.string,
+      id: PropTypes.string,
+      ref: ABBPropTypes.ref()
+    })
+  ),
+  value: PropTypes.string,
+  initialValue: PropTypes.string,
+  onChange: PropTypes.func,
+  tokens: getTokensPropType('Tabs'),
+  itemTokens: getTokensPropType('TabsItem'),
+  scrollButtonTokens: getTokensPropType('HorizontalScrollButton'),
+  variant: variantProp.propType
+}
+
+export default Tabs

package/src/Tabs/TabsItem.jsx

@@ -0,0 +1,212 @@
+import React, { forwardRef, useEffect } from 'react'
+import PropTypes from 'prop-types'
+import { Platform, Pressable, StyleSheet, Text, View } from 'react-native'
+
+import { applyTextStyles, useThemeTokensCallback } from '../ThemeProvider'
+import {
+  resolvePressableTokens,
+  selectTokens,
+  variantProp,
+  getTokensPropType,
+  linkProps,
+  a11yProps
+} from '../utils'
+import Spacer from '../Spacer'
+import { horizontalScrollUtils } from '../HorizontalScroll'
+
+const { itemPositionsPropType, getItemPositionLayoutHandler } = horizontalScrollUtils
+
+const selectHighlightBarStyles = ({
+  highlightColor,
+  highlightBarBorderRadius = 0,
+  highlightBarBorderWidth = 0,
+  highlightBarHeight = 0
+}) => ({
+  backgroundColor: highlightColor,
+  borderColor: highlightColor,
+  height: highlightBarHeight + highlightBarBorderWidth * 2,
+  borderRadius: highlightBarBorderRadius,
+  borderWidth: highlightBarBorderWidth,
+  bottom: -1 * (highlightBarHeight + highlightBarBorderWidth),
+  left: -1 * highlightBarBorderWidth,
+  right: -1 * highlightBarBorderWidth,
+  zIndex: 1 + highlightBarBorderWidth
+})
+
+const selectHighlightTriangleStyles = ({ highlightColor, highlightTriangleSize }) => ({
+  container: {
+    bottom: 0 - highlightTriangleSize * 2
+  },
+  triangle: {
+    height: 0,
+    width: 0,
+    borderWidth: highlightTriangleSize,
+    borderTopColor: highlightColor,
+    borderBottomColor: 'transparent',
+    borderLeftColor: 'transparent',
+    borderRightColor: 'transparent'
+  }
+})
+
+const selectContainerStyles = ({
+  backgroundColor,
+  borderColor,
+  borderWidth = 0,
+  borderRadius,
+  paddingHorizontal = 0,
+  paddingVertical = 0
+}) => ({
+  backgroundColor,
+  borderColor,
+  borderWidth,
+  borderRadius,
+  paddingHorizontal: paddingHorizontal - borderWidth,
+  paddingVertical: paddingVertical - borderWidth
+})
+
+/**
+ * Item within a Tabs component representing one tab of content. May be rendered as a link
+ * or as a "menuitem" button depending on whether 'href' is passed.
+ *
+ * This is rendered automatically by `Tabs` and isn't intended be used directly.
+ */
+const TabsItem = forwardRef(
+  (
+    {
+      onPress,
+      href,
+      variant,
+      tokens,
+      selected,
+      itemPositions,
+      index,
+      children,
+      accessibilityRole = href ? 'link' : 'tab',
+      accessibilityState = Platform.OS === 'web' && accessibilityRole === 'link'
+        ? // Web links can't be aria-selected but can be aria-current
+          { current: selected ? 'page' : false }
+        : { selected },
+      ...rest
+    },
+    ref
+  ) => {
+    const getTokens = useThemeTokensCallback('TabsItem', tokens, variant)
+    const resolveTokens = (pressableState) =>
+      resolvePressableTokens(getTokens, pressableState, { selected })
+
+    const getPressableStyle = (pressableState) => {
+      const { maxWidth } = resolveTokens(pressableState)
+      return [{ maxWidth }, Platform.OS === 'web' && { outline: 'none' }]
+    }
+
+    const handleLayout = getItemPositionLayoutHandler(itemPositions.positions, index)
+
+    // On press, update the selection, call any press handler, and open any href in platform-appropriate way
+    const openHref = href && linkProps.handleHref({ href })
+    const handlePress =
+      onPress || openHref
+        ? () => {
+            if (onPress) onPress()
+            if (openHref) openHref()
+          }
+        : undefined
+
+    const a11y = {
+      accessibilityRole,
+      accessibilityState,
+      ...a11yProps.select(rest)
+    }
+
+    useEffect(() => {
+      // If this is selected while off-screen, scroll it into view
+      if (selected) {
+        const position = itemPositions.positions[index]
+        const scrollEnd = itemPositions.scrollOffset + itemPositions.containerWidth
+        if (
+          // is off the right edge, or
+          (scrollEnd && position?.end > scrollEnd) ||
+          // is off the left edge
+          (typeof position?.start === 'number' && position.start < itemPositions.scrollOffset)
+        ) {
+          itemPositions.scrollTo(position.start)
+        }
+      }
+      // itemPositions is a ref object so this should only re-run when `selected` (or `index`) change
+    }, [selected, index, itemPositions])
+
+    return (
+      <Pressable
+        ref={ref}
+        onPress={handlePress}
+        href={href}
+        style={getPressableStyle}
+        onLayout={handleLayout}
+        {...a11y}
+      >
+        {(pressableState) => {
+          const { space, textAlign, ...themeTokens } = resolveTokens(pressableState)
+
+          const hasHighlightBar = Boolean(themeTokens.highlightBarHeight)
+          const highlightBarStyle = hasHighlightBar && selectHighlightBarStyles(themeTokens)
+
+          const hasHighlightTriangle = Boolean(themeTokens.highlightTriangleSize)
+          const highlightTriangleStyle =
+            hasHighlightTriangle && selectHighlightTriangleStyles(themeTokens)
+
+          const containerStyles = selectContainerStyles(themeTokens)
+          const textStyles = applyTextStyles({
+            ...selectTokens('Typography', themeTokens),
+            textAlign
+          })
+
+          return (
+            <View style={staticStyles.container}>
+              <View style={containerStyles}>
+                <Text style={textStyles}>{children}</Text>
+              </View>
+              <Spacer space={space} />
+              {hasHighlightBar && <View style={[staticStyles.absolute, highlightBarStyle]} />}
+              {hasHighlightTriangle && (
+                <View style={[staticStyles.absolute, highlightTriangleStyle.container]}>
+                  <View style={highlightTriangleStyle.triangle} />
+                </View>
+              )}
+            </View>
+          )
+        }}
+      </Pressable>
+    )
+  }
+)
+TabsItem.displayName = 'TabsItem'
+
+TabsItem.propTypes = {
+  ...a11yProps.propTypes,
+  tokens: getTokensPropType('TabsItem'),
+  variant: variantProp.propType,
+  onPress: PropTypes.func,
+  href: PropTypes.string,
+  index: PropTypes.number,
+  selected: PropTypes.bool,
+  itemPositions: itemPositionsPropType,
+  children: PropTypes.string
+}
+
+const staticStyles = StyleSheet.create({
+  center: {
+    alignItems: 'center'
+  },
+  absolute: {
+    position: 'absolute',
+    alignItems: 'center',
+    left: 0,
+    right: 0
+  },
+  container: {
+    flexGrow: 1,
+    alignItems: 'center',
+    justifyContent: 'center'
+  }
+})
+
+export default TabsItem

package/src/Tabs/index.js

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