@telus-uds/components-base 0.0.2-prerelease.1 → 0.0.2-prerelease.5

package/src/Pagination/PageButton.jsx

@@ -0,0 +1,80 @@
+import React from 'react'
+import { Text } from 'react-native'
+import PropTypes from 'prop-types'
+
+import ButtonBase from '../Button/ButtonBase'
+import { applyTextStyles, useThemeTokensCallback } from '../ThemeProvider'
+import {
+  a11yProps,
+  copyPropTypes,
+  getTokensPropType,
+  hrefAttrsProp,
+  linkProps,
+  selectTokens,
+  variantProp
+} from '../utils'
+
+import useCopy from './useCopy'
+import dictionary from './dictionary'
+
+const selectTextStyles = ({ color, fontName, fontSize, fontWeight, lineHeight, textLine }) =>
+  applyTextStyles({
+    color,
+    fontName,
+    fontSize,
+    fontWeight,
+    lineHeight,
+    textDecorationLine: textLine
+  })
+
+function PageButton({ label, onPress, href, isActive, copy, variant, tokens, ...props }) {
+  const getTokens = useThemeTokensCallback('PaginationPageButton', tokens, variant)
+
+  const getCopy = useCopy({ dictionary, copy })
+
+  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 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
+  }
+
+  return (
+    <ButtonBase {...buttonProps} tokens={getButtonTokens} {...activeProps}>
+      {(buttonState) => {
+        return <Text style={getTextStyles(buttonState)}>{label}</Text>
+      }}
+    </ButtonBase>
+  )
+}
+
+PageButton.propTypes = {
+  label: PropTypes.string,
+  isActive: PropTypes.bool,
+  copy: copyPropTypes,
+  variant: variantProp.propType,
+  tokens: getTokensPropType('PaginationPageButton'),
+  ...linkProps.types
+}
+
+export default PageButton

package/src/Pagination/Pagination.jsx

@@ -0,0 +1,135 @@
+import React from 'react'
+import { View, Text, StyleSheet } from 'react-native'
+
+import { componentPropType, copyPropTypes, getTokensPropType, variantProp } from '../utils'
+import { applyTextStyles, useThemeTokens } from '../ThemeProvider'
+import { useViewport } from '../ViewportProvider'
+import Box from '../Box'
+
+import usePagination from './usePagination'
+import PageButton from './PageButton'
+import SideButton from './SideButton'
+
+const selectTextStyles = ({ color, fontName, fontSize, fontWeight, lineHeight }) =>
+  applyTextStyles({
+    color,
+    fontName,
+    fontSize,
+    fontWeight,
+    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>
+      }
+
+      return null
+    }),
+    showNext && (
+      <SideButton
+        {...nextItemProps}
+        direction="next"
+        copy={copy}
+        variant={sideButtonVariant}
+        tokens={sideButtonTokens}
+      />
+    )
+  ]
+
+  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>
+  )
+}
+
+Pagination.PageButton = PageButton
+
+Pagination.propTypes = {
+  children: componentPropType('PageButton'),
+  copy: copyPropTypes,
+  variant: variantProp.propType,
+  tokens: getTokensPropType('Pagination'),
+  sideButtonVariant: variantProp.propType,
+  sideButtonTokens: getTokensPropType('PaginationSideButton')
+}
+
+const staticStyles = StyleSheet.create({
+  container: {
+    flexDirection: 'row',
+    flexWrap: 'wrap',
+    alignItems: 'center'
+  }
+})
+
+export default Pagination

package/src/Pagination/SideButton.jsx

@@ -0,0 +1,93 @@
+import React from 'react'
+import { StyleSheet, View, Text, PixelRatio } from 'react-native'
+
+import PropTypes from 'prop-types'
+
+import ButtonBase from '../Button/ButtonBase'
+import { applyTextStyles, useThemeTokensCallback } from '../ThemeProvider'
+import { useViewport } from '../ViewportProvider'
+import { copyPropTypes, hrefAttrsProp, linkProps, selectTokens } from '../utils'
+
+import dictionary from './dictionary'
+import useCopy from './useCopy'
+
+const selectTextStyles = ({ color, fontName, fontSize, fontWeight, lineHeight }) =>
+  applyTextStyles({
+    color,
+    fontName,
+    fontSize,
+    fontWeight,
+    lineHeight
+  })
+
+const selectIconTokens = ({ color, iconSize, iconTranslateX }) => {
+  // 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,
+    translateX: iconTranslateX
+  }
+}
+
+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))
+  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 { hrefAttrs, rest } = hrefAttrsProp.bundle(props)
+  const buttonProps = {
+    accessibilityRole,
+    accessibilityLabel,
+    onPress,
+    href,
+    hrefAttrs,
+    ...rest
+  }
+
+  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.propTypes = {
+  direction: PropTypes.oneOf(['previous', 'next']),
+  copy: copyPropTypes,
+  ...linkProps.types
+}
+
+export default SideButton
+
+const staticStyles = StyleSheet.create({
+  contentContainer: {
+    flexDirection: 'row'
+  }
+})

package/src/Pagination/dictionary.js

@@ -0,0 +1,18 @@
+export default {
+  en: {
+    goToLabel: 'Go to page number',
+    currentLabel: '(current)',
+    previousLabel: 'Go to previous page',
+    previousText: 'Previous',
+    nextLabel: 'Go to next page',
+    nextText: 'Next'
+  },
+  fr: {
+    goToLabel: 'Aller au page n°',
+    currentLabel: '(page actuelle)',
+    previousLabel: 'Aller au page précédent',
+    previousText: 'Précédent',
+    nextLabel: 'Aller au prochain page',
+    nextText: 'Suivant'
+  }
+}

package/src/Pagination/index.js

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

package/src/Pagination/useCopy.js

@@ -0,0 +1,7 @@
+function useCopy({ dictionary, copy }) {
+  const getCopy = (key) => dictionary[copy][key]
+
+  return getCopy
+}
+
+export default useCopy

package/src/Pagination/usePagination.js

@@ -0,0 +1,69 @@
+/**
+ * Handles configurable truncating of pagination items.
+ *
+ * @param {object} props
+ * @param {React.Element[]} items
+ * @param {number} truncateAbove
+ */
+function usePagination({ items, truncateAbove }) {
+  const activeItemIndex = Math.max(
+    items.findIndex((item) => item.props.isActive),
+    0 // default to the first item if none is marked as active
+  )
+
+  const getItemProps = (index) => {
+    const { onPress, href, hrefAttrs, variant, tokens } = items[index]?.props ?? {}
+    return { onPress, href, hrefAttrs, variant, tokens }
+  }
+
+  const windowSize = truncateAbove > 4 ? 3 : 1
+  const truncateEnabled = items.length > truncateAbove
+
+  const truncateWindowStart = windowSize
+  const truncateWindowEnd = items.length - 1 - windowSize
+
+  // basically how many items next to the currently active one do we want to render
+  const activeWindowStart = activeItemIndex - (windowSize - 1) / 2
+  const activeWindowEnd = activeItemIndex + (windowSize - 1) / 2
+
+  const isFirstActive = activeItemIndex === 0
+  const isLastActive = activeItemIndex === items.length - 1
+
+  // start truncating when the active item is within the truncate window
+  const isLeftTruncated = truncateEnabled && activeItemIndex >= truncateWindowStart
+  const isRightTruncated = truncateEnabled && activeItemIndex <= truncateWindowEnd
+
+  function shouldRenderEllipsis(itemIndex) {
+    const isNextToFirst = itemIndex === 1
+    const isNextToLast = itemIndex === items.length - 2
+
+    return (isLeftTruncated && isNextToFirst) || (isRightTruncated && isNextToLast)
+  }
+
+  function shouldRenderButton(itemIndex) {
+    const isFirst = itemIndex === 0
+    const isLast = itemIndex === items.length - 1
+    const isInActiveWindow = itemIndex >= activeWindowStart && itemIndex <= activeWindowEnd
+
+    return (
+      isFirst ||
+      isLast ||
+      isInActiveWindow ||
+      (!isLeftTruncated && itemIndex <= truncateWindowStart) ||
+      (!isRightTruncated && itemIndex >= truncateWindowEnd)
+    )
+  }
+
+  return {
+    showPrevious: !isFirstActive,
+    showNext: !isLastActive,
+    shouldRenderButton,
+    shouldRenderEllipsis,
+    isItemActive: (itemIndex) => itemIndex === activeItemIndex,
+    getItemProps,
+    nextItemProps: getItemProps(activeItemIndex + 1),
+    previousItemProps: getItemProps(activeItemIndex - 1)
+  }
+}
+
+export default usePagination

package/src/SideNav/Item.jsx

@@ -62,14 +62,14 @@ const Item = ({
     ...rest
   })
 
-  const getTokens = useThemeTokensCallback('SideNavItem')
+  const getTokens = useThemeTokensCallback('SideNavItem', tokens, variant)
   const getAppearanceState = ({ hovered }) => ({
     hover: hovered,
     active: isActive,
     expanded: isExpanded
   })
   const getPressableStyle = (pressableState) =>
-    selectItemStyles(getTokens(tokens, variant, getAppearanceState(pressableState)))
+    selectItemStyles(getTokens(getAppearanceState(pressableState)))
 
   return (
     <Pressable
@@ -79,7 +79,7 @@ const Item = ({
       testID={testID}
     >
       {(pressableState) => {
-        const themeTokens = getTokens(tokens, variant, getAppearanceState(pressableState))
+        const themeTokens = getTokens(getAppearanceState(pressableState))
         return <ItemContent tokens={themeTokens}>{children}</ItemContent>
       }}
     </Pressable>

package/src/SideNav/ItemsGroup.jsx

@@ -28,25 +28,23 @@ const ItemsGroup = ({
   onToggle
 }) => {
   // A SideNav control uses the same style and theme as SideNavItem, with a 'parent' variant,
-  // plus control-specific tokens from the SideNavItemsGroup theme.
+  // plus control-specific tokens from the SideNavItemsGroup theme (e.g. open/close icon, etc).
   const getAppearance = (appearance) => ({ ...variant, ...appearance, active: isActive })
   const getItemAppearance = (appearance) => ({ ...getAppearance(appearance), type: 'parent' })
 
-  // TODO: refactor useThemeTokensCallback return so it has the same shape as tokens prop functions
-  // https://github.com/telus/universal-design-system/issues/588
-  const getGroupTokens = useThemeTokensCallback('SideNavItemsGroup')
-  const panelTokensGetterProp = (appearance) =>
-    selectTokens('ExpandCollapsePanel', getGroupTokens(tokens, getAppearance(appearance)))
+  const getGroupTokens = useThemeTokensCallback('SideNavItemsGroup', tokens, variant)
+  const getPanelTokens = (appearance) =>
+    selectTokens('ExpandCollapsePanel', getGroupTokens(getAppearance(appearance)))
 
-  const getItemTokens = useThemeTokensCallback('SideNavItem')
-  const controlTokensGetterProp = (appearance) =>
+  const getItemTokens = useThemeTokensCallback('SideNavItem', itemTokens, variant)
+  const getControlTokens = (appearance) =>
     selectTokens('ExpandCollapseControl', {
-      ...getItemTokens(itemTokens, getItemAppearance(appearance)),
-      ...getGroupTokens(tokens, getAppearance(appearance))
+      ...getItemTokens(getItemAppearance(appearance)), // main style from SideNavItem
+      ...getGroupTokens(getAppearance(appearance)) // control-specific tokens like icon etc
     })
 
   const controlContent = (controlState) => {
-    const currentItemTokens = getItemTokens(itemTokens, getItemAppearance(controlState))
+    const currentItemTokens = getItemTokens(getItemAppearance(controlState))
     return <ItemContent tokens={currentItemTokens}>{label}</ItemContent>
   }
 
@@ -55,8 +53,8 @@ const ItemsGroup = ({
       openIds={openGroups}
       panelId={groupId}
       onToggle={onToggle}
-      tokens={panelTokensGetterProp}
-      controlTokens={controlTokensGetterProp}
+      tokens={getPanelTokens}
+      controlTokens={getControlTokens}
       control={controlContent}
       accessibilityState={{ active: isActive }} // ExpandCollapse.Panel handles expanded state
     >

package/src/Spacer/Spacer.jsx

@@ -0,0 +1,91 @@
+import React from 'react'
+import PropTypes from 'prop-types'
+import { StyleSheet, View } from 'react-native'
+
+import { useSpacingScale, spacingProps } from '../utils'
+/**
+ * @typedef {import('../utils/propTypes.js').SpacingValue} SpacingValue
+ * @typedef {import('../utils/propTypes.js').SpacingObject} SpacingObject
+ */
+
+const selectSizeStyle = (size, direction) => ({
+  // Only apply space in one direction at a time, else large spacers will increase the
+  // 'across' size of the parent and mess up siblings with styles like `alignItems: stretch`.
+  [direction === 'row' ? 'width' : 'height']: size
+})
+
+/**
+ * An empty element used to create a gap between components that is sized according to the theme spacing scale,
+ * passing its `space` prop ({@link SpacingValue}) to `useSpacingScale`.
+ *
+ * ## Simple spacing
+ *
+ * For most simple uses, pass a number to Spacer's `space` prop referring to an index in the theme's
+ * spacing scale. For example, for a spacer of the theme's smallest non-zero spacing size:
+ *
+ * ```jsx
+ * <Spacer space={1} />
+ * ```
+ *
+ * ## Responsive spacing
+ *
+ * Different spacing scale sizes may be chosen for different viewports by passing `space` a {@link SpacingObject}
+ * using keys for the viewports at and above which certain spacing indexes should apply.
+ *
+ * This can be useful when a Spacer is inside a layout with a shape that changes between viewports.
+ *
+ * For example, a spacer might need no width below 'md' viewport because the items it separates will be on separate lines,
+ * but may need a visible size above that viewport, and a wider size at the highest viewport:
+ *
+ * ```jsx
+ * <Spacer space={{ xs: 0, md: 2, xl: 3 }} />
+ * ```
+ *
+ * Note that themes may also define viewport-specific behaviour for indexes on the spacing scale. These viewport
+ * props should only be used where necessary to achieve a certain responsive layoutm and shouldn't be used to replace
+ * or deviate from responsive spacing behaviour in a theme that is intended to apply universally.
+ *
+ * ## More options
+ *
+ * See `useSpacingScale` hook for more options that may be used with the `space` prop.
+ *
+ * ## Accessibility
+ *
+ * Spacer has no content and is ignored by tools such as screen readers. Use `Divider` for
+ * separations between elements that may be treated as semantically meaningful on web.
+ */
+const Spacer = ({ space = 1, direction = 'column', testID }) => {
+  const size = useSpacingScale(space)
+  const sizeStyle = selectSizeStyle(size, direction)
+  return <View testID={testID} style={[staticStyles.stretch, sizeStyle]} />
+}
+
+Spacer.propTypes = {
+  /**
+   * The size of the spacer 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 spacer applies space in only one direction, which is controlled by the `direction` prop:
+   *
+   * - `'column'` (default) applies space vertically; has a fixed height and not width.
+   * - `'row'` applies space horizontally; has a fixed width and not height.
+   */
+  direction: PropTypes.oneOf(['column', 'row']),
+  /**
+   * @ignore
+   * In tests, the only way to select Spacers is with testID prop and getByTestId, since they have no content,
+   * no accessibility role, and there is no equivalent of nextSibling in React Native Testing Library.
+   */
+  testID: PropTypes.string
+}
+
+const staticStyles = StyleSheet.create({
+  stretch: {
+    alignSelf: 'stretch'
+  }
+})
+
+export default Spacer

package/src/Spacer/index.js

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

package/src/StackView/StackView.jsx

@@ -0,0 +1,103 @@
+import React from 'react'
+import PropTypes from 'prop-types'
+import { View } from 'react-native'
+
+import Divider from '../Divider'
+import { spacingProps, a11yProps } from '../utils'
+import { useThemeTokens } from '../ThemeProvider'
+import getStackedContent from './getStackedContent'
+import { staticStyles, selectFlexStyles } from './common'
+
+/**
+ * StackView evenly spaces its children, by default placing `Spacer` components between them.
+ *
+ * ## Spacing
+ *
+ * StackView takes the same spacing props as `Spacer` and passes them directly to the layout components
+ * it uses for spacing.
+ *
+ * ## Direction
+ *
+ * Use `direction` to control how the children are stacked:
+ *
+ * - `'column'` (default) stacks and spaces the children vertically.
+ * - `'row'` stacks and spaces the children horizontally.
+ * - `'column-reverse'` acts the same as `'column'`, but reverses the direction.
+ * - `'row-reverse'` acts the same as `'row'`, but reverses the direction.
+ *
+ * ## Theming, alignment and justification
+ *
+ * `StackView` is a pure layout component and has no theme styles beyond a small set of layout styles
+ * (`alignItems`, `justifyContent`, `flexGrow`) which may be set using the `tokens` prop.
+ *
+ * All other styling such as borders, background colours, padding etc should be applied by wrapping
+ * the `StackView` in other components. For example, a `StackView` may be the child of a `Card`.
+ *
+ * ## Separator options
+ *
+ * By default, StackView inserts a `<Spacer>` component between each rendered child.
+ *
+ * With the `divider` prop, it instead renders a `Divider` instead of a `Spacer`. The gap between
+ * items will be double what it would be without this prop plus the width of the divider.
+ *
+ * ## Accessibility
+ *
+ * `StackView` may take any React Native accessibility props and applies them to the outer `View`.
+ * It applies no accessibility props of its own, unless `divider` prop is passed (`Divider` has a
+ * semantic role but only on web, not within native apps).
+ */
+const StackView = ({
+  space = 1,
+  divider,
+  direction = 'column',
+  inherit,
+  children,
+  variant,
+  tokens,
+  ...rest
+}) => {
+  const a11y = a11yProps.select({ ...rest })
+  const content = getStackedContent(children, { direction, divider, space })
+  const themeTokens = useThemeTokens('StackView', tokens, variant)
+  const flexStyles = selectFlexStyles(themeTokens)
+
+  return inherit ? (
+    content
+  ) : (
+    <View {...a11y} style={[flexStyles, staticStyles[direction]]}>
+      {content}
+    </View>
+  )
+}
+
+StackView.propTypes = {
+  ...a11yProps.propTypes,
+  /**
+   * Sets the `flexDirection` of the container and, if `divider` is used, gives the Divider the appropriate direction.
+   */
+  direction: PropTypes.oneOf(['column', 'row', 'column-reverse', 'row-reverse']),
+  /**
+   * If true, renders a UDS `Divider` component between each item. If an object is passed,
+   * this object is passes as props to each Divider.
+   */
+  divider: PropTypes.oneOfType([PropTypes.bool, PropTypes.shape(Divider.propTypes)]),
+  /**
+   * If true, does not render any container and returns an array of spaced children, inheriting
+   * flex styles from the StackView's parent. That parent must have a `flexDirection` style corresponding
+   * to the StackView's `direction` prop for `divider` prop to behave correctly.
+   */
+  inherit: PropTypes.bool,
+  /**
+   * The size of the spacer 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,
+  /**
+   * A StackView 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.
+   */
+  children: PropTypes.node
+}
+
+export default StackView