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

package/src/FlexGrid/Row/Row.jsx

@@ -1,4 +1,4 @@
-import React from 'react'
+import React, { forwardRef } from 'react'
 import PropTypes from 'prop-types'
 import { View, StyleSheet } from 'react-native'
 import { viewports } from '@telus-uds/system-constants'
@@ -52,56 +52,63 @@ const distributeStyles = (distribute) => {
   }
 }
 
-const Row = ({
-  horizontalAlign,
-  verticalAlign,
-  distribute,
-  xsReverse,
-  smReverse,
-  mdReverse,
-  lgReverse,
-  xlReverse,
-  children,
-  ...rest
-}) => {
-  const viewPort = useViewport()
-  const reverseLevel = applyInheritance([xsReverse, smReverse, mdReverse, lgReverse, xlReverse])
+const Row = forwardRef(
+  (
+    {
+      horizontalAlign,
+      verticalAlign,
+      distribute,
+      xsReverse,
+      smReverse,
+      mdReverse,
+      lgReverse,
+      xlReverse,
+      children,
+      ...rest
+    },
+    ref
+  ) => {
+    const viewPort = useViewport()
+    const reverseLevel = applyInheritance([xsReverse, smReverse, mdReverse, lgReverse, xlReverse])
 
-  let flexDirection = ''
+    let flexDirection = ''
 
-  if (viewPort === viewports.xs) {
-    flexDirection = reverseLevel[0] ? 'row-reverse' : 'row'
-  }
-  if (viewPort === viewports.sm) {
-    flexDirection = reverseLevel[1] ? 'row-reverse' : 'row'
-  }
-  if (viewPort === viewports.md) {
-    flexDirection = reverseLevel[2] ? 'row-reverse' : 'row'
-  }
-  if (viewPort === viewports.lg) {
-    flexDirection = reverseLevel[3] ? 'row-reverse' : 'row'
-  }
-  if (viewPort === viewports.xl) {
-    flexDirection = reverseLevel[4] ? 'row-reverse' : 'row'
-  }
+    if (viewPort === viewports.xs) {
+      flexDirection = reverseLevel[0] ? 'row-reverse' : 'row'
+    }
+    if (viewPort === viewports.sm) {
+      flexDirection = reverseLevel[1] ? 'row-reverse' : 'row'
+    }
+    if (viewPort === viewports.md) {
+      flexDirection = reverseLevel[2] ? 'row-reverse' : 'row'
+    }
+    if (viewPort === viewports.lg) {
+      flexDirection = reverseLevel[3] ? 'row-reverse' : 'row'
+    }
+    if (viewPort === viewports.xl) {
+      flexDirection = reverseLevel[4] ? 'row-reverse' : 'row'
+    }
 
-  return (
-    <View
-      {...rest}
-      style={[
-        styles.row,
-        {
-          flexDirection,
-          ...horizontalAlignStyles(horizontalAlign),
-          ...verticalAlignStyles(verticalAlign),
-          ...distributeStyles(distribute)
-        }
-      ]}
-    >
-      {children}
-    </View>
-  )
-}
+    return (
+      <View
+        ref={ref}
+        {...rest}
+        style={[
+          styles.row,
+          {
+            flexDirection,
+            ...horizontalAlignStyles(horizontalAlign),
+            ...verticalAlignStyles(verticalAlign),
+            ...distributeStyles(distribute)
+          }
+        ]}
+      >
+        {children}
+      </View>
+    )
+  }
+)
+Row.displayName = 'Row'
 
 const styles = StyleSheet.create({
   row: {

package/src/HorizontalScroll/HorizontalScroll.jsx

@@ -0,0 +1,168 @@
+import React, { forwardRef, 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 = forwardRef(
+  ({ ScrollButton, tokens, itemPositions, children, ...rest }, ref) => {
+    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 ref={ref} 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>
+    )
+  }
+)
+HorizontalScroll.displayName = 'HorizontalScroll'
+
+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/HorizontalScroll/HorizontalScrollButton.jsx

@@ -0,0 +1,105 @@
+import React, { forwardRef } 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 HorizontalScrollButton = forwardRef(
+  ({ direction = 'next', icon, onPress, offset, variant, tokens, copy }, ref) => {
+    const getTokens = useThemeTokensCallback('HorizontalScrollButton', 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
+        ref={ref}
+        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>
+    )
+  }
+)
+HorizontalScrollButton.displayName = 'HorizontalScrollButton'
+
+const staticStyles = StyleSheet.create({
+  absolute: {
+    position: 'absolute'
+  },
+  previous: {
+    left: 0
+  },
+  next: {
+    right: 0
+  }
+})
+
+HorizontalScrollButton.propTypes = {
+  tokens: getTokensPropType('HorizontalScrollButton'),
+  variant: variantProp.propType,
+  copy: copyPropTypes,
+  direction: PropTypes.oneOf(['previous', 'next']),
+  offset: PropTypes.number,
+  icon: PropTypes.elementType,
+  onPress: PropTypes.func.isRequired
+}
+
+export default HorizontalScrollButton

package/src/HorizontalScroll/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/HorizontalScroll/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/HorizontalScroll/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/HorizontalScroll/index.js

@@ -0,0 +1,17 @@
+import HorizontalScroll, { selectHorizontalScrollTokens } from './HorizontalScroll'
+import {
+  useItemPositions,
+  getItemPositionScrollTarget,
+  getItemPositionLayoutHandler,
+  itemPositionsPropType
+} from './itemPositions'
+
+export default HorizontalScroll
+export { default as HorizontalScrollButton } from './HorizontalScrollButton'
+export const horizontalScrollUtils = {
+  selectHorizontalScrollTokens,
+  useItemPositions,
+  getItemPositionScrollTarget,
+  getItemPositionLayoutHandler,
+  itemPositionsPropType
+}

package/src/HorizontalScroll/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
+})