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

package/src/Tabs/TabsItem.jsx

@@ -0,0 +1,204 @@
+import React, { useEffect } from 'react'
+import PropTypes from 'prop-types'
+import { Platform, Pressable, StyleSheet, Text, View } from 'react-native'
+import system from '@telus-uds/system-themes/src/tokens/rn'
+
+import { applyTextStyles, useThemeTokensCallback } from '../ThemeProvider'
+import {
+  resolvePressableTokens,
+  selectTokens,
+  variantProp,
+  getTokensPropType,
+  linkProps,
+  a11yProps
+} from '../utils'
+import Spacer from '../Spacer'
+import { itemPositionsPropType, getItemPositionLayoutHandler } from './itemPositions'
+
+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: system.color.transparent,
+    borderLeftColor: system.color.transparent,
+    borderRightColor: system.color.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 = ({
+  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
+}) => {
+  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
+      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.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/TabsScrollButton.jsx

@@ -0,0 +1,100 @@
+import React from 'react'
+import PropTypes from 'prop-types'
+import { Pressable, StyleSheet } from 'react-native'
+
+import { useThemeTokensCallback } from '../ThemeProvider'
+import {
+  resolvePressableTokens,
+  selectTokens,
+  variantProp,
+  getTokensPropType,
+  useCopy,
+  copyPropTypes,
+  a11yProps
+} from '../utils'
+import Icon from '../Icon'
+import Typography from '../Typography'
+import dictionary from './dictionary'
+
+const selectButtonStyles = (
+  { borderRadius, backgroundColor, borderColor, borderWidth, padding },
+  direction
+) => [
+  staticStyles.absolute,
+  staticStyles[direction],
+  {
+    borderRadius,
+    backgroundColor,
+    borderColor,
+    borderWidth,
+    padding
+  }
+]
+
+/**
+ * Button within a Tabs component showing users that content is available to the left or
+ * right, scrolling a screen's worth of content left or right when pressed.
+ *
+ * This is rendered automatically by `Tabs` and isn't intended be used directly.
+ *
+ * @TODO when IconButton is complete and stable revisit this and update interaction state styles.
+ */
+const TabsScrollButton = ({ direction = 'next', icon, onPress, offset, variant, tokens, copy }) => {
+  const getTokens = useThemeTokensCallback('TabsScrollButton', tokens, variant)
+  const resolveButtonTokens = (pressableState) => resolvePressableTokens(getTokens, pressableState)
+  const getPressableStyle = (pressableState) => [
+    selectButtonStyles(resolveButtonTokens(pressableState), direction),
+    { marginTop: -1 * (offset || 0) }
+  ]
+
+  const getCopy = useCopy({ dictionary, copy })
+  const label = direction === 'previous' ? getCopy('previousText') : getCopy('nextText')
+
+  return (
+    <Pressable
+      style={getPressableStyle}
+      onPress={onPress}
+      accessibilityLabel={label}
+      accessibilityRole="button"
+      // For keyboard-tab or screenreader-swipe navigation, users can just go through all items
+      {...a11yProps.nonFocusableProps}
+    >
+      {(pressableState) => {
+        const iconTokens = selectTokens('Icon', resolveButtonTokens(pressableState), 'icon')
+        return icon ? (
+          <Icon icon={icon} tokens={iconTokens} />
+        ) : (
+          <Typography
+            tokens={{ fontSize: iconTokens.size, lineHeight: 1, color: iconTokens.color }}
+          >
+            {direction === 'next' ? '→' : '←'}
+          </Typography>
+        )
+      }}
+    </Pressable>
+  )
+}
+
+const staticStyles = StyleSheet.create({
+  absolute: {
+    position: 'absolute'
+  },
+  previous: {
+    left: 0
+  },
+  next: {
+    right: 0
+  }
+})
+
+TabsScrollButton.propTypes = {
+  tokens: getTokensPropType('TabsScrollButton'),
+  variant: variantProp.propType,
+  copy: copyPropTypes,
+  direction: PropTypes.oneOf(['previous', 'next']),
+  offset: PropTypes.number,
+  icon: PropTypes.elementType,
+  onPress: PropTypes.func.isRequired
+}
+
+export default TabsScrollButton

package/src/Tabs/dictionary.js

@@ -0,0 +1,11 @@
+export default {
+  en: {
+    // English text from TDS Community `Tabs`
+    previousLabel: 'Move menu to the left',
+    nextLabel: 'Move menu to the right'
+  },
+  fr: {
+    previousLabel: 'Déplacer le menu vers la gauche',
+    nextLabel: 'Déplacer le menu vers la droite'
+  }
+}

package/src/Tabs/index.js

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

package/src/Tabs/itemPositions.js

@@ -0,0 +1,101 @@
+import { useRef, useState } from 'react'
+import PropTypes from 'prop-types'
+
+// Utilities to assist scrolling a parent so that it snaps neatly to an appropriate child.
+
+/**
+ * @typedef ItemPositionPosition
+ * @property {number} [ItemPositionItem.start] - optional theme scale variants e.g. compact, wide
+ * @property {number} [ItemPositionItem.end] - optional override to force a particular pixel size
+ *
+ * @typedef {Object.<number, ItemPositionItem>} ItemPositionPositions - ref object of start/end coordinates
+ *
+ * @typedef ItemPositions
+ * @property {number} ItemPositions.contentWidth - current width of potentially-overflowing content inside scrollable
+ * @property {number} ItemPositions.containerWidth - current width of non-overflowing outer scroll container
+ * @property {number} ItemPositions.scrollOffset - current x position of the left edge of the visible section of the scrollable content
+ * @property {ItemPositionPositions} ItemPositions.positions - `{ start, end }` coordinates of each scrollable content item, by index
+ * @property {(targetX: number) => void)} ItemPositions.scrollTo - function to scroll to a co-ordinate, applying scrolling logic
+ * @property {() => void)} ItemPositions.setIsReady - function to call when layout has been calculated and itemPositions data is ready
+ */
+
+/**
+ * Takes a desired scroll target coordinate and returns a valid coordinate
+ * that, when not scrolling to one end or another, snaps to the start of an item,
+ * making sure any "scroll back" button doesn't overlap the first item.
+ *
+ * @param {number} x - the intended coordinate to scroll to
+ * @param {number} scrollMax - the highest posible coordinate to scroll to
+ * @param {ItemPositionPositions} positions - positions list from `useItemPositions` ref
+ * @param {number} [buttonClearance] - offset to allow space for a button
+ * @returns {number}
+ */
+export const getItemPositionScrollTarget = (x, scrollMax, positions, buttonClearance = 0) => {
+  if (x <= 0) return 0
+  if (x >= scrollMax) return scrollMax
+
+  // If not scrolling all the way to the start or end, stop
+  // where the first item is not coverred by the scroll previous button
+  const targetItem = Object.values(positions).find(({ start, end }) => start <= x && end > x)
+
+  // If there's no target item we're landing at a gap between items
+  const targetX = targetItem ? targetItem.start : x
+  return Math.max(0, targetX - buttonClearance)
+}
+
+/**
+ * Returns a handler for React Native's `onLayout` which updates the values of
+ * the ref object returned from `useItemPositions`.
+ *
+ * @param {ItemPositionPositions} positions
+ * @param {number} index
+ * @returns {function}
+ */
+export const getItemPositionLayoutHandler = (positions, index) => {
+  const handleLayout = ({
+    nativeEvent: {
+      layout: { width, x }
+    }
+  }) => {
+    /* eslint-disable-next-line no-param-reassign */
+    positions[index] = { start: x, end: x + width }
+  }
+  return handleLayout
+}
+
+/**
+ * Wrapper for `useRef` which gives a mutable object in which item start/end coordinates,
+ * scrollTo method and content/container widths may be set and updated without causing a re-render.
+ *
+ * @returns {[ItemPositions, isReady: bool]} tuple array of:
+ *  - current ref object `{ positions, contentWidth, containerWidth, scrollOffset, scrollTo, setIsReady }`
+ *  - boolean that updates to `true` (causing a re-render) after the first time `setIsReady` is called
+ */
+export const useItemPositions = () => {
+  const [isReady, setIsReady] = useState(false)
+  return [
+    useRef({
+      positions: {},
+      scrollTo: () => {},
+      contentWidth: 0,
+      containerWidth: 0,
+      scrollOffset: 0,
+      setIsReady
+    }).current,
+    isReady
+  ]
+}
+
+/**
+ * PropType for the ref object returned by `useItemPositions`
+ */
+export const itemPositionsPropType = PropTypes.exact({
+  positions: PropTypes.objectOf(
+    PropTypes.shape({ start: PropTypes.number, end: PropTypes.number })
+  ),
+  scrollTo: PropTypes.func,
+  contentWidth: PropTypes.number,
+  containerWidth: PropTypes.number,
+  scrollOffset: PropTypes.number,
+  setIsReady: PropTypes.func
+})

package/src/Tags/Tags.jsx

@@ -0,0 +1,207 @@
+import React from 'react'
+import PropTypes from 'prop-types'
+import { Platform, Text, View } from 'react-native'
+
+import ButtonBase from '../Button/ButtonBase'
+import Icon from '../Icon'
+import { StackWrap, getStackedContent } from '../StackView'
+import { useViewport } from '../ViewportProvider'
+import { useThemeTokens, useThemeTokensCallback } from '../ThemeProvider'
+import {
+  a11yProps,
+  pressProps,
+  variantProp,
+  getTokensPropType,
+  selectTokens
+} from '../utils/propTypes'
+import { useMultipleInputValues } from '../utils/input'
+import { getPressHandlersWithArgs } from '../utils/pressability'
+
+const selectIconTextTokens = ({
+  icon,
+  iconPosition,
+  iconSpace,
+  iconSize,
+  iconColor,
+  iconBackground,
+  iconBorderRadius,
+  iconAlignSelf,
+  iconPadding,
+  iconTranslateX,
+  iconTranslateY
+}) => ({
+  icon,
+  iconPosition,
+  iconSpace,
+  iconWrapperStyle: {
+    backgroundColor: iconBackground,
+    borderRadius: iconBorderRadius,
+    alignSelf: iconAlignSelf,
+    padding: iconPadding,
+    ...Platform.select({
+      // TODO: https://github.com/telus/universal-design-system/issues/487
+      web: { transition: 'color 200ms, background 200ms' }
+    })
+  },
+  iconTokens: {
+    size: iconSize,
+    color: iconColor,
+    translateX: iconTranslateX,
+    translateY: iconTranslateY
+  }
+})
+
+const Tags = ({
+  variant,
+  tokens,
+  items = [],
+  values,
+  initialValues,
+  maxValues,
+  onChange,
+  readOnly = false,
+  inactive = false,
+  accessibilityRole = Platform.select({ web: 'group', default: 'none' }),
+  ...rest
+}) => {
+  const viewport = useViewport()
+  const themeTokens = useThemeTokens('Tags', tokens, variant, { viewport })
+  const stackTokens = selectTokens('StackView', themeTokens)
+  const { direction, space } = themeTokens
+
+  const getItemTokens = useThemeTokensCallback('TagsItem', tokens, variant)
+  const getButtonTokens = (buttonState) => selectTokens('Button', getItemTokens(buttonState))
+
+  const { currentValues, toggleOneValue } = useMultipleInputValues({
+    initialValues,
+    values,
+    maxValues,
+    onChange,
+    readOnly
+  })
+
+  const a11y = a11yProps.select({
+    accessibilityRole,
+    ...rest
+  })
+  const itemA11yRole = 'checkbox'
+
+  return (
+    <StackWrap {...a11y} space={space} direction={direction} tokens={stackTokens}>
+      {items.map(({ label, id = label, accessibilityLabel }, index) => {
+        const isSelected = currentValues.includes(id)
+
+        // Pass an object of relevant component state as first argument for any passed-in press handlers
+        const pressHandlers = getPressHandlersWithArgs(rest, [{ id, label, currentValues }])
+
+        const handlePress = () => {
+          if (pressHandlers.onPress) pressHandlers.onPress()
+          toggleOneValue(id)
+        }
+
+        const itemA11y = {
+          accessibilityState: { checked: isSelected },
+          accessibilityRole: itemA11yRole,
+          accessibilityLabel,
+          ...a11yProps.getPositionInSet(items.length, index)
+        }
+
+        return (
+          <ButtonBase
+            key={id}
+            {...pressHandlers}
+            onPress={handlePress}
+            tokens={getButtonTokens}
+            selected={isSelected}
+            inactive={inactive}
+            {...itemA11y}
+          >
+            {({ textStyles, ...buttonState }) => {
+              // TODO: once Icon/IconButton designs are stable, see if this sort of styling around
+              // an icon should go in Icon itself, or possibly via an IconText token set. Related issues:
+              // - Icon: https://github.com/telus/universal-design-system/issues/327
+              // - IconButton: https://github.com/telus/universal-design-system/issues/281
+              // - Token sets: https://github.com/telus/universal-design-system/issues/782
+
+              const itemTokens = getItemTokens(buttonState)
+
+              const {
+                iconTokens,
+                iconPosition,
+                iconSpace,
+                iconWrapperStyle,
+                icon: IconComponent
+              } = selectIconTextTokens(itemTokens)
+
+              const iconContent = IconComponent ? (
+                <View style={iconWrapperStyle}>
+                  <Icon icon={IconComponent} tokens={iconTokens} />
+                </View>
+              ) : null
+              const textContent = <Text style={textStyles}>{label}</Text>
+
+              return getStackedContent(
+                iconPosition === 'left' ? [iconContent, textContent] : [textContent, iconContent],
+                { space: iconSpace, direction: 'row' }
+              )
+            }}
+          </ButtonBase>
+        )
+      })}
+    </StackWrap>
+  )
+}
+
+Tags.propTypes = {
+  ...a11yProps.propTypes,
+  ...pressProps.propTypes,
+  tokens: getTokensPropType('Tags'),
+  variant: variantProp.propType,
+  /**
+   * If provided, sets a maximum number of items a user may select at once.
+   */
+  maxValues: PropTypes.number,
+  /**
+   * The options a user may select
+   */
+  items: PropTypes.arrayOf(
+    PropTypes.shape({
+      /**
+       * The text displayed to the user in the button, describing this option,
+       * passed to the button as its child.
+       */
+      label: PropTypes.string.isRequired,
+      /**
+       * An optional accessibility label may be passed to ButtonGroup Buttons
+       * which is applied as normal for a React Native accessibilityLabel prop.
+       */
+      accessibilityLabel: PropTypes.string,
+      /**
+       * An optional unique string may be provided to identify this option,
+       * which will be used in code and passed to any onChange function.
+       * If not provided, the label is used.
+       */
+      id: PropTypes.string
+    })
+  ),
+  /**
+   * If provided, this function is called when the current selection is changed
+   * and is passed an array of the `id`s of all currently selected `items`.
+   */
+  onChange: PropTypes.func,
+  /**
+   * If the selected item(s) in the button group are to be controlled externally by
+   * a parent component, pass an array of strings as well as an `onChange` handler.
+   * Passing an array for "values" makes the ButtonGroup a "controlled" component that
+   * expects its state to be handled via `onChange` and so doesn't handle it itself.
+   */
+  values: PropTypes.arrayOf(PropTypes.string),
+  /**
+   * If `values` is not passed, making the ButtonGroup an "uncontrolled" component
+   * managing its own selected state, a default set of selections may be provided.
+   * Changing the `initialValues` does not change the user's selections.
+   */
+  initialValues: PropTypes.arrayOf(PropTypes.string)
+}
+
+export default Tags

package/src/Tags/index.js

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