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

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

package/src/Tabs/ScrollViewEnd.jsx

@@ -0,0 +1,53 @@
+import React, { forwardRef, useCallback, useEffect } from 'react'
+import PropTypes from 'prop-types'
+import { ScrollView } from 'react-native'
+import debounce from 'lodash.debounce'
+
+const DEBOUNCE_MS = 100
+
+/**
+ * A wrapper for ScrollView that supports an `onScrollEnd` function.
+ *
+ * React Native Web hasn't got around to implementing any scroll end handlers yet,
+ * so we need to work around it with debouncing on `onScroll`. See:
+ * https://github.com/necolas/react-native-web/issues/1021
+ */
+const ScrollViewEnd = forwardRef(({ onScrollEnd, onScroll, ...props }, ref) => {
+  // Return debounced function directly from useCallback so it has .cancel method etc.
+  // Linter complains this stops it automatically scanning the deps, but we can check them manually.
+  // eslint-disable-next-line react-hooks/exhaustive-deps
+  const debounceScrollEnd = useCallback(
+    debounce((event) => onScrollEnd(event), DEBOUNCE_MS),
+    [onScrollEnd]
+  )
+
+  // Call any onScroll handler immediately, and any onScrollEnd handler after 100ms of no scrolling
+  const handleScroll = (event) => {
+    if (typeof onScroll === 'function') onScroll(event)
+    if (typeof onScrollEnd === 'function') debounceScrollEnd(event)
+  }
+
+  // Cancel any lingering debounce timeouts on dismount
+  useEffect(() => debounceScrollEnd.cancel)
+
+  return (
+    <ScrollView
+      ref={ref}
+      {...props}
+      onScroll={handleScroll}
+      scrollEventThrottle={DEBOUNCE_MS / 2}
+    />
+  )
+})
+ScrollViewEnd.displayName = 'ScrollViewEnd'
+
+ScrollViewEnd.propTypes = {
+  onScrollEnd: PropTypes.func.isRequired,
+  onScroll: PropTypes.func
+}
+
+ScrollViewEnd.defaultProps = {
+  onScroll: null
+}
+
+export default ScrollViewEnd

package/src/Tabs/ScrollViewEnd.native.jsx

@@ -0,0 +1,24 @@
+import React, { forwardRef } from 'react'
+import PropTypes from 'prop-types'
+import { ScrollView } from 'react-native'
+
+/**
+ * A wrapper for ScrollView that supports an `onScrollEnd` function.
+ *
+ * React Native has two scroll end handlers, we want to treat them both the same.
+ */
+const ScrollViewEnd = forwardRef(({ onScrollEnd, ...props }, ref) => (
+  <ScrollView
+    ref={ref}
+    {...props}
+    onScrollEndDrag={onScrollEnd}
+    onMomentumScrollEnd={onScrollEnd}
+  />
+))
+ScrollViewEnd.displayName = 'ScrollViewEnd'
+
+ScrollViewEnd.propTypes = {
+  onScrollEnd: PropTypes.func.isRequired
+}
+
+export default ScrollViewEnd

package/src/Tabs/Tabs.jsx

@@ -0,0 +1,89 @@
+import React, { useCallback } from 'react'
+import PropTypes from 'prop-types'
+
+import { useThemeTokens } from '../ThemeProvider'
+import StackView from '../StackView'
+import { getTokensPropType, variantProp, useHash, useInputValue } from '../utils'
+import HorizontalScroll, { selectHorizontalScrollTokens } from './HorizontalScroll'
+import TabsItem from './TabsItem'
+import TabsScrollButton from './TabsScrollButton'
+import { useItemPositions } from './itemPositions'
+
+/**
+ * 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 = ({
+  tokens,
+  itemTokens,
+  scrollButtonTokens,
+  variant,
+  value,
+  initialValue,
+  onChange,
+  items = []
+}) => {
+  const { space, ...themeTokens } = useThemeTokens('Tabs', tokens, variant)
+  const { currentValue, setValue } = useInputValue({ value, initialValue, onChange })
+
+  const [itemPositions, isPositioningReady] = useItemPositions()
+
+  useHash(
+    useCallback(
+      (hash) => {
+        const hashItem = hash && items.find(({ href }) => hash === href)
+        const hashId = hashItem && (hashItem.id || hashItem.label)
+        if (hashId) setTimeout(setValue(hashId), 500)
+      },
+      [items, setValue]
+    ),
+    isPositioningReady
+  )
+
+  return (
+    <HorizontalScroll
+      ScrollButton={TabsScrollButton}
+      itemPositions={itemPositions}
+      tokens={selectHorizontalScrollTokens(themeTokens)}
+      scrollButtonTokens={scrollButtonTokens}
+      accessibilityRole="tablist"
+    >
+      <StackView space={space} direction="row">
+        {items.map(({ href, label, id }, index) => {
+          const itemId = id ?? label
+          const isSelected = Boolean(currentValue && currentValue === itemId)
+          const handlePress = () => setValue(itemId)
+          return (
+            <TabsItem
+              key={itemId}
+              href={href}
+              variant={variant}
+              tokens={itemTokens}
+              onPress={handlePress}
+              selected={isSelected}
+              itemPositions={itemPositions}
+              index={index}
+            >
+              {label}
+            </TabsItem>
+          )
+        })}
+      </StackView>
+    </HorizontalScroll>
+  )
+}
+
+Tabs.propTypes = {
+  items: PropTypes.arrayOf(
+    PropTypes.shape({ href: PropTypes.string, label: PropTypes.string, id: PropTypes.string })
+  ),
+  value: PropTypes.string,
+  initialValue: PropTypes.string,
+  onChange: PropTypes.func,
+  tokens: getTokensPropType('Tabs'),
+  itemTokens: getTokensPropType('TabsItem'),
+  scrollButtonTokens: getTokensPropType('TabsScrollButton'),
+  variant: variantProp.propType
+}
+
+export default Tabs

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