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

package/src/Pagination/PageButton.jsx

@@ -1,15 +1,13 @@
-import React from 'react'
-import { Text } from 'react-native'
+import React, { forwardRef } from 'react'
 import PropTypes from 'prop-types'
 
 import ButtonBase from '../Button/ButtonBase'
-import { applyTextStyles, useThemeTokensCallback } from '../ThemeProvider'
+import { useThemeTokensCallback } from '../ThemeProvider'
 import {
   a11yProps,
   copyPropTypes,
   getTokensPropType,
   hrefAttrsProp,
-  linkProps,
   selectTokens,
   variantProp
 } from '../utils'
@@ -17,64 +15,59 @@ import {
 import useCopy from '../utils/useCopy'
 import dictionary from './dictionary'
 
-const selectTextStyles = ({ color, fontName, fontSize, fontWeight, lineHeight, textLine }) =>
-  applyTextStyles({
-    color,
-    fontName,
-    fontSize,
-    fontWeight,
-    lineHeight,
-    textDecorationLine: textLine
-  })
+const PageButton = forwardRef(
+  ({ label, onPress, href, isActive, copy, variant, tokens, ...props }, ref) => {
+    const getTokens = useThemeTokensCallback('PaginationPageButton', tokens, variant)
 
-function PageButton({ label, onPress, href, isActive, copy, variant, tokens, ...props }) {
-  const getTokens = useThemeTokensCallback('PaginationPageButton', tokens, variant)
+    const getCopy = useCopy({ dictionary, copy })
 
-  const getCopy = useCopy({ dictionary, copy })
+    const getButtonTokens = (buttonState) => selectTokens('Button', getTokens(buttonState))
 
-  const getButtonTokens = (buttonState) => selectTokens('Button', getTokens(buttonState))
-  const getTextStyles = (buttonState) => selectTextStyles(getTokens(buttonState))
+    const activeProps = isActive
+      ? {
+          selected: true,
+          ...a11yProps.nonFocusableProps,
+          // a brute fix for the focus state being stuck on an active item since it becomes non-focusable
+          // (see https://github.com/telus/universal-design-system/pull/577#issuecomment-931344107)
+          key: 'active-item'
+        }
+      : {}
 
-  const activeProps = isActive
-    ? {
-        selected: true,
-        ...a11yProps.nonFocusableProps,
-        // a brute fix for the focus state being stuck on an active item since it becomes non-focusable
-        // (see https://github.com/telus/universal-design-system/pull/577#issuecomment-931344107)
-        key: 'active-item'
-      }
-    : {}
+    const accessibilityRole = href !== undefined ? 'link' : 'button'
+    const activeLabel = isActive ? ` ${getCopy('currentLabel')}` : ''
+    const accessibilityLabel = `${getCopy('goToLabel')} ${label}${activeLabel}`
 
-  const accessibilityRole = href !== undefined ? 'link' : 'button'
-  const activeLabel = isActive ? ` ${getCopy('currentLabel')}` : ''
-  const accessibilityLabel = `${getCopy('goToLabel')} ${label}${activeLabel}`
+    const { hrefAttrs, rest } = hrefAttrsProp.bundle(props)
+    const buttonProps = {
+      accessibilityRole,
+      accessibilityLabel,
+      onPress,
+      href,
+      hrefAttrs,
+      ...rest
+    }
 
-  const { hrefAttrs, rest } = hrefAttrsProp.bundle(props)
-  const buttonProps = {
-    accessibilityRole,
-    accessibilityLabel,
-    onPress,
-    href,
-    hrefAttrs,
-    ...rest
+    return (
+      <ButtonBase ref={ref} {...buttonProps} tokens={getButtonTokens} {...activeProps}>
+        {label}
+      </ButtonBase>
+    )
   }
-
-  return (
-    <ButtonBase {...buttonProps} tokens={getButtonTokens} {...activeProps}>
-      {(buttonState) => {
-        return <Text style={getTextStyles(buttonState)}>{label}</Text>
-      }}
-    </ButtonBase>
-  )
-}
+)
+PageButton.displayName = 'PageButton'
 
 PageButton.propTypes = {
+  // Spreading any props into a secondary component accessed like Pagination.PageButton
+  // crashes a Docusaurus props table, but only in production, not in development
+  onPress: PropTypes.func,
+  href: PropTypes.string,
+  // If the above is fixed, the above can be replaced with this which includes full a11y etc:
+  // ...linkProps.types,
   label: PropTypes.string,
   isActive: PropTypes.bool,
   copy: copyPropTypes,
   variant: variantProp.propType,
-  tokens: getTokensPropType('PaginationPageButton'),
-  ...linkProps.types
+  tokens: getTokensPropType('PaginationPageButton')
 }
 
 export default PageButton

package/src/Pagination/Pagination.jsx

@@ -1,4 +1,4 @@
-import React from 'react'
+import React, { forwardRef } from 'react'
 import { View, Text, StyleSheet } from 'react-native'
 
 import { componentPropType, copyPropTypes, getTokensPropType, variantProp } from '../utils'
@@ -19,99 +19,95 @@ const selectTextStyles = ({ color, fontName, fontSize, fontWeight, lineHeight })
     lineHeight
   })
 
-function Pagination({
-  children,
-  copy = 'en',
-  variant,
-  tokens,
-  sideButtonVariant,
-  sideButtonTokens
-}) {
-  const viewport = useViewport()
-  const { truncateAbove, gap, ...themeTokens } = useThemeTokens('Pagination', tokens, variant, {
-    viewport
-  })
-
-  const items = React.Children.toArray(children)
-
-  const {
-    isItemActive,
-    getItemProps,
-    showPrevious,
-    showNext,
-    nextItemProps,
-    previousItemProps,
-    shouldRenderButton,
-    shouldRenderEllipsis
-  } = usePagination({
-    items,
-    truncateAbove
-  })
-
-  const ellipsisTextStyles = selectTextStyles(themeTokens)
-
-  if (items.length === 0) {
-    return null
-  }
-
-  // TODO: replace with a spacing component when https://github.com/telus/universal-design-system/pull/531 is implemented
-  // concatenate all items to easily wrap them in identical spacing components
-  const buttons = [
-    showPrevious && (
-      <SideButton
-        {...previousItemProps}
-        direction="previous"
-        copy={copy}
-        variant={sideButtonVariant}
-        tokens={sideButtonTokens}
-      />
-    ),
-    ...items.map((child, itemIndex) => {
-      const buttonLabel = `${itemIndex + 1}`
-      const itemProps = getItemProps(itemIndex)
-
-      if (shouldRenderButton(itemIndex)) {
-        return (
-          <PageButton
-            {...itemProps}
-            label={buttonLabel}
-            copy={copy}
-            isActive={isItemActive(itemIndex)}
-          />
-        )
-      }
-
-      if (shouldRenderEllipsis(itemIndex)) {
-        return <Text style={ellipsisTextStyles}>...</Text>
-      }
-
+const Pagination = forwardRef(
+  ({ children, copy = 'en', variant, tokens, sideButtonVariant, sideButtonTokens }, ref) => {
+    const viewport = useViewport()
+    const { truncateAbove, gap, ...themeTokens } = useThemeTokens('Pagination', tokens, variant, {
+      viewport
+    })
+
+    const items = React.Children.toArray(children)
+
+    const {
+      isItemActive,
+      getItemProps,
+      showPrevious,
+      showNext,
+      nextItemProps,
+      previousItemProps,
+      shouldRenderButton,
+      shouldRenderEllipsis
+    } = usePagination({
+      items,
+      truncateAbove
+    })
+
+    const ellipsisTextStyles = selectTextStyles(themeTokens)
+
+    if (items.length === 0) {
       return null
-    }),
-    showNext && (
-      <SideButton
-        {...nextItemProps}
-        direction="next"
-        copy={copy}
-        variant={sideButtonVariant}
-        tokens={sideButtonTokens}
-      />
+    }
+
+    // TODO: replace with a spacing component when https://github.com/telus/universal-design-system/pull/531 is implemented
+    // concatenate all items to easily wrap them in identical spacing components
+    const buttons = [
+      showPrevious && (
+        <SideButton
+          {...previousItemProps}
+          direction="previous"
+          copy={copy}
+          variant={sideButtonVariant}
+          tokens={sideButtonTokens}
+        />
+      ),
+      ...items.map((child, itemIndex) => {
+        const buttonLabel = `${itemIndex + 1}`
+        const itemProps = getItemProps(itemIndex)
+
+        if (shouldRenderButton(itemIndex)) {
+          return (
+            <PageButton
+              {...itemProps}
+              label={buttonLabel}
+              copy={copy}
+              isActive={isItemActive(itemIndex)}
+            />
+          )
+        }
+
+        if (shouldRenderEllipsis(itemIndex)) {
+          return <Text style={ellipsisTextStyles}>...</Text>
+        }
+
+        return null
+      }),
+      showNext && (
+        <SideButton
+          {...nextItemProps}
+          direction="next"
+          copy={copy}
+          variant={sideButtonVariant}
+          tokens={sideButtonTokens}
+        />
+      )
+    ]
+
+    return (
+      <View style={staticStyles.container} ref={ref}>
+        {buttons
+          // keep the keys in-line with the page numbers regardless of which buttons are actually rendered
+          .map((element, index) => [element, `page-${index + 1}`])
+          .filter(([element]) => element !== null)
+          .map(([element, key]) => (
+            <Box right={gap} key={key}>
+              {element}
+            </Box>
+          ))}
+      </View>
     )
-  ]
-
-  return (
-    <View style={staticStyles.container}>
-      {buttons
-        // keep the keys in-line with the page numbers regardless of which buttons are actually rendered
-        .map((element, index) => [element, `page-${index + 1}`])
-        .filter(([element]) => element !== null)
-        .map(([element, key]) => (
-          <Box right={gap} key={key}>
-            {element}
-          </Box>
-        ))}
-    </View>
-  )
-}
+  }
+)
+PageButton.displayName = 'PageButton'
 
 Pagination.PageButton = PageButton
 

package/src/Pagination/SideButton.jsx

@@ -1,82 +1,80 @@
-import React from 'react'
-import { StyleSheet, View, Text, PixelRatio } from 'react-native'
+import React, { forwardRef } from 'react'
+import { Text } from 'react-native'
 
 import PropTypes from 'prop-types'
 
 import ButtonBase from '../Button/ButtonBase'
-import { applyTextStyles, useThemeTokensCallback } from '../ThemeProvider'
+import { IconText } from '../Icon'
+import { useThemeTokensCallback } from '../ThemeProvider'
 import { useViewport } from '../ViewportProvider'
 import { copyPropTypes, hrefAttrsProp, linkProps, selectTokens } from '../utils'
 
 import dictionary from './dictionary'
 import useCopy from '../utils/useCopy'
 
-const selectTextStyles = ({ color, fontName, fontSize, fontWeight, lineHeight }) =>
-  applyTextStyles({
-    color,
-    fontName,
-    fontSize,
-    fontWeight,
-    lineHeight
-  })
-
 const selectIconTokens = ({ color, iconSize, iconDisplace }, direction) => {
-  // Scale icon with text, but with a cap so text isn't squashed at large scales
-  const iconScale = Math.min(PixelRatio.getFontScale(), 2)
-
   return {
     color,
-    size: iconSize * iconScale,
+    size: iconSize,
     translateX: iconDisplace * (direction === 'previous' ? -1 : 1)
   }
 }
 
-function SideButton({ direction = 'previous', onPress, href, copy, variant, tokens, ...props }) {
-  const viewport = useViewport()
-  const buttonVariant = { direction, viewport, ...variant }
-  const getTokens = useThemeTokensCallback('PaginationSideButton', tokens, buttonVariant)
-
-  const getCopy = useCopy({ dictionary, copy })
-
-  const { icon: IconComponent } = getTokens(tokens, buttonVariant)
-
-  const getButtonTokens = (buttonState) => selectTokens('Button', getTokens(buttonState))
-  const getIconTokens = (buttonState) => selectIconTokens(getTokens(buttonState), direction)
-  const getTextStyles = (buttonState) => selectTextStyles(getTokens(buttonState))
-
-  const label = direction === 'previous' ? getCopy('previousText') : getCopy('nextText')
-  const showLabel = viewport !== 'sm' && viewport !== 'xs'
-
-  const accessibilityLabel =
-    direction === 'previous' ? getCopy('previousLabel') : getCopy('nextLabel')
-  const accessibilityRole = href !== undefined ? 'link' : 'button'
+const directionToSide = {
+  previous: 'left',
+  next: 'right'
+}
 
-  const { hrefAttrs, rest } = hrefAttrsProp.bundle(props)
-  const buttonProps = {
-    accessibilityRole,
-    accessibilityLabel,
-    onPress,
-    href,
-    hrefAttrs,
-    ...rest
+const SideButton = forwardRef(
+  ({ direction = 'previous', onPress, href, copy, variant, tokens, ...props }, ref) => {
+    const viewport = useViewport()
+    const buttonVariant = { direction, viewport, ...variant }
+    const getTokens = useThemeTokensCallback('PaginationSideButton', tokens, buttonVariant)
+
+    const getCopy = useCopy({ dictionary, copy })
+
+    const { icon } = getTokens(tokens, buttonVariant)
+
+    const getButtonTokens = (buttonState) => selectTokens('Button', getTokens(buttonState))
+    const getIconTokens = (buttonState) => selectIconTokens(getTokens(buttonState), direction)
+
+    const label = direction === 'previous' ? getCopy('previousText') : getCopy('nextText')
+    const showLabel = viewport !== 'sm' && viewport !== 'xs'
+
+    const accessibilityLabel =
+      direction === 'previous' ? getCopy('previousLabel') : getCopy('nextLabel')
+    const accessibilityRole = href !== undefined ? 'link' : 'button'
+
+    const { hrefAttrs, rest } = hrefAttrsProp.bundle(props)
+    const buttonProps = {
+      accessibilityRole,
+      accessibilityLabel,
+      onPress,
+      href,
+      hrefAttrs,
+      ...rest
+    }
+
+    return (
+      <ButtonBase ref={ref} {...buttonProps} tokens={getButtonTokens}>
+        {({ textStyles, ...buttonState }) => {
+          const iconProps = { tokens: getIconTokens(buttonState) }
+          return (
+            <IconText
+              icon={icon}
+              space={1}
+              iconPosition={directionToSide[direction]}
+              iconProps={iconProps}
+            >
+              {showLabel && <Text style={textStyles}>{label}</Text>}
+            </IconText>
+          )
+        }}
+      </ButtonBase>
+    )
   }
-
-  return (
-    <ButtonBase {...buttonProps} tokens={getButtonTokens}>
-      {(buttonState) => (
-        <View style={staticStyles.contentContainer}>
-          {direction === 'previous' && IconComponent && (
-            <IconComponent tokens={getIconTokens(buttonState)} />
-          )}
-          {showLabel && <Text style={getTextStyles(buttonState)}>{label}</Text>}
-          {direction === 'next' && IconComponent && (
-            <IconComponent tokens={getIconTokens(buttonState)} />
-          )}
-        </View>
-      )}
-    </ButtonBase>
-  )
-}
+)
+SideButton.displayName = 'SideButton'
 
 SideButton.propTypes = {
   direction: PropTypes.oneOf(['previous', 'next']),
@@ -85,9 +83,3 @@ SideButton.propTypes = {
 }
 
 export default SideButton
-
-const staticStyles = StyleSheet.create({
-  contentContainer: {
-    flexDirection: 'row'
-  }
-})

package/src/Progress/Progress.jsx

@@ -0,0 +1,78 @@
+import React, { forwardRef } from 'react'
+import PropTypes from 'prop-types'
+import { View } from 'react-native'
+
+import { a11yProps } from '../utils/propTypes'
+import { useThemeTokens } from '../ThemeProvider'
+import { getTokensPropType, variantProp } from '../utils'
+
+const selectProgressStyles = ({
+  backgroundColor,
+  borderWidth,
+  borderColor,
+  borderRadius,
+  height
+}) => ({
+  backgroundColor,
+  borderWidth,
+  borderColor,
+  borderRadius,
+  height
+})
+
+/**
+ * The `Progress` is a container for displaying one or several `ProgressBar`s.
+ *
+ * ## Props
+ *
+ * - Use `children` prop to pass one or multiple `ProgressBar`s. Note that in case of stacked progress bars
+ *   each next will be displayed on top of the previous one.
+ *
+ * ## Tokens
+ *
+ * - Use the following tokens to customize the appearance:
+ *   - `backgroundColor` for the background color of the progress container,
+ *   - `borderColor` to control the color of the border,
+ *   - `borderRadius` for the rounded corners,
+ *   - `borderWidth` to change the border width.
+ *   - `height` to control the height of the progress bars displayed within the progress bar container.
+ *
+ * ## Variants
+ *
+ * - Use the `size` variant to control the height of your progress bars:  passing `'mini'` will make your
+ *   progress bar container narrower.
+ *
+ * ## Usability and A11y guidelines
+ *
+ * `Progress` component accepts the standard accessibility properties, however it's more important to make sure
+ * its children (instances of `ProgressBar`) receive the accessibility properties specific to the `progressbar`
+ * role.
+ *
+ */
+const Progress = forwardRef(({ children, tokens, variant, ...rest }, ref) => {
+  const themeTokens = useThemeTokens('Progress', tokens, variant)
+
+  return (
+    <View ref={ref} style={selectProgressStyles(themeTokens)} {...a11yProps.select(rest)}>
+      {children}
+    </View>
+  )
+})
+Progress.displayName = 'Progress'
+
+Progress.propTypes = {
+  /**
+   * Use the `children` prop to supply one or several `ProgressBar`s.
+   */
+  children: PropTypes.node.isRequired,
+  /**
+   * Progress tokens.
+   */
+  tokens: getTokensPropType('Progress'),
+  /**
+   * Progress variant.
+   */
+  variant: variantProp.propType
+}
+
+export default Progress

package/src/Progress/ProgressBar.jsx

@@ -0,0 +1,123 @@
+import React, { forwardRef } from 'react'
+import PropTypes from 'prop-types'
+import { Platform, StyleSheet, View } from 'react-native'
+
+import ProgressBarBackground from './ProgressBarBackground'
+import { a11yProps } from '../utils/propTypes'
+import { useThemeTokens } from '../ThemeProvider'
+import { getTokensPropType, variantProp } from '../utils'
+
+const selectBarStyles = (
+  { backgroundColor, borderRadius, outlineWidth, outlineColor },
+  percentage
+) => ({
+  backgroundColor,
+  borderRadius,
+  outlineWidth,
+  outlineColor,
+  width: `${percentage}%`
+})
+
+/**
+ * The `ProgressBar` is a visual representation of linear progression.
+ * It provides simple but important information at a quick glance.
+ *
+ * ## Props
+ *
+ * - Use `percentage` prop to indicate completion
+ *
+ * ## Tokens
+ *
+ * - Use the following tokens to customize the appearance:
+ *   - `backgroundColor` for the background color of the progress bar,
+ *   - `borderRadius` for the rounded corners,
+ *   - `outlineColor` to control the color of the border (outline),
+ *   - `outlineWidth` to change the outline width.
+ *
+ * ## Variants
+ *
+ * - Use the following variants to render specific types of progress bars:
+ *   - `negative`: set to `true` if you wish to use the negative theming for progress bar filling,
+ *   - `inactive`: set to `true` if you wish to style the progress bar as inactive.
+ *
+ * ## Usability and A11y guidelines
+ *
+ * `ProgressBar` component accepts all the standard accessibility properties including the ones that
+ * are specific to the `progressbar` role. By default the following props are used:
+ *
+ * - `accessibilityRole` (`role`): `progressbar`,
+ * - `accessibilityValue.min` (`aria-valuemin`): `0`,
+ * - `accessibilityValue.max` (`aria-valuemax`): `100`,
+ * - `accessibilityValue.now` (`aria-valuenow`): `percentage`,
+ * - `accessibilityValue.text` (`aria-valuetext`): `%{percentage}%`,
+ *
+ */
+const ProgressBar = forwardRef(
+  ({ children = null, percentage = 0, tokens, variant, ...rest }, ref) => {
+    const themeTokens = useThemeTokens('ProgressBar', tokens, variant)
+    if (percentage < 0) {
+      throw new Error('ProgressBar: `percentage` must be a positive number')
+    } else if (percentage > 100) {
+      throw new Error('ProgressBar: `percentage` cannot exceed 100')
+    }
+    const accessibilityProps = {
+      accessibilityRole: 'progressbar',
+      accessibilityValue: {
+        min: 0,
+        max: 100,
+        now: percentage,
+        text: `${percentage}%`
+      },
+      ...a11yProps.select(rest)
+    }
+
+    return percentage > 0 ? (
+      <View
+        ref={ref}
+        style={[staticStyles.bar, selectBarStyles(themeTokens, percentage)]}
+        {...accessibilityProps}
+      >
+        {children ?? <ProgressBarBackground variant={variant} />}
+      </View>
+    ) : null
+  }
+)
+ProgressBar.displayName = 'ProgressBar'
+
+ProgressBar.propTypes = {
+  /**
+   * Optional children that can be used to customize the progress bar filling.
+   */
+  children: PropTypes.node,
+  /**
+   * Accessibility label for the progress bar.
+   */
+  accessibilityLabel: PropTypes.string.isRequired,
+  /**
+   * Percentage of completion.
+   */
+  percentage: PropTypes.number,
+  /**
+   * Progress bar tokens.
+   */
+  tokens: getTokensPropType('ProgressBar'),
+  /**
+   * Progress bar variant.
+   */
+  variant: variantProp.propType
+}
+
+export default ProgressBar
+
+const staticStyles = StyleSheet.create({
+  bar: {
+    height: '100%',
+    overflow: 'hidden',
+    position: 'absolute',
+    ...Platform.select({
+      web: {
+        outlineStyle: 'solid'
+      }
+    })
+  }
+})