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

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/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/Icon/Icon.jsx

@@ -1,47 +1,49 @@
-import React from 'react'
+import React, { forwardRef } from 'react'
 import { Platform, View } from 'react-native'
 import PropTypes from 'prop-types'
 
 import { useThemeTokens } from '../ThemeProvider'
 import { getTokensPropType, scaleWithText, variantProp } from '../utils'
 
-const Icon = ({
-  icon: IconComponent,
-  accessibilityLabel,
-  variant,
-  tokens,
-  scalesWithText = false
-}) => {
-  const themeTokens = useThemeTokens('Icon', tokens, variant)
+const Icon = forwardRef(
+  (
+    { icon: IconComponent, accessibilityLabel, variant, tokens, scalesWithText = false, dataSet },
+    ref
+  ) => {
+    const themeTokens = useThemeTokens('Icon', tokens, variant)
 
-  const size = scalesWithText ? scaleWithText(themeTokens.size) : themeTokens.size
+    const size = scalesWithText ? scaleWithText(themeTokens.size) : themeTokens.size
 
-  const iconContent = (
-    <IconComponent title={accessibilityLabel} size={size} color={themeTokens.color} />
-  )
+    const iconContent = (
+      <IconComponent title={accessibilityLabel} size={size} color={themeTokens.color} />
+    )
 
-  return Platform.OS === 'web' ? (
-    <View
-      // eslint-disable-next-line react-native/no-inline-styles
-      style={{
-        // TODO: systematise animations.
-        // https://github.com/telus/universal-design-system/issues/487
-        transition: 'transform 200ms, color 200ms',
-        transform: [
-          themeTokens.scale ? `scale(${themeTokens.scale})` : '',
-          themeTokens.translateX ? `translateX(${themeTokens.translateX}px)` : '',
-          themeTokens.translateY ? `translateY(${themeTokens.translateY}px)` : ''
-        ]
-          .filter((exists) => exists)
-          .join(' ')
-      }}
-    >
-      {iconContent}
-    </View>
-  ) : (
-    iconContent
-  )
-}
+    return Platform.OS === 'web' ? (
+      <View
+        ref={ref}
+        // eslint-disable-next-line react-native/no-inline-styles
+        style={{
+          // TODO: systematise animations.
+          // https://github.com/telus/universal-design-system/issues/487
+          transition: 'transform 200ms, color 200ms',
+          transform: [
+            themeTokens.scale ? `scale(${themeTokens.scale})` : '',
+            themeTokens.translateX ? `translateX(${themeTokens.translateX}px)` : '',
+            themeTokens.translateY ? `translateY(${themeTokens.translateY}px)` : ''
+          ]
+            .filter((exists) => exists)
+            .join(' ')
+        }}
+        dataSet={dataSet}
+      >
+        {iconContent}
+      </View>
+    ) : (
+      iconContent
+    )
+  }
+)
+Icon.displayName = 'Icon'
 
 export const iconComponentPropTypes = {
   variant: variantProp.propType,

package/src/Icon/IconText.jsx

@@ -1,4 +1,4 @@
-import React from 'react'
+import React, { forwardRef } from 'react'
 import PropTypes from 'prop-types'
 import { Platform, View } from 'react-native'
 
@@ -14,24 +14,29 @@ import { spacingProps } from '../utils'
  *  - inline within a <Text> element
  *  - within a container with `flexDirection: 'row'`
  */
-const IconText = ({ space, iconPosition = 'left', icon: IconComponent, iconProps, children }) => {
-  const iconContent = IconComponent && <Icon icon={IconComponent} scalesWithText {...iconProps} />
-
-  // Inline images on Android are always baseline-aligned which makes them look misaligned - offset it.
-  // See abandoned issue https://github.com/facebook/react-native/issues/6529
-  const size = iconProps?.tokens?.size
-  const iconAdjusted =
-    Platform.OS === 'android' && iconContent && size ? (
-      <View style={{ transform: [{ translateY: size * 0.2 }] }}>{iconContent}</View>
-    ) : (
-      iconContent
+const IconText = forwardRef(
+  ({ space, iconPosition = 'left', icon: IconComponent, iconProps, children }, ref) => {
+    const iconContent = IconComponent && (
+      <Icon ref={ref} icon={IconComponent} scalesWithText {...iconProps} />
     )
 
-  return getStackedContent(
-    iconPosition === 'left' ? [iconAdjusted, children] : [children, iconAdjusted],
-    { space, direction: 'row' }
-  )
-}
+    // Inline images on Android are always baseline-aligned which makes them look misaligned - offset it.
+    // See abandoned issue https://github.com/facebook/react-native/issues/6529
+    const size = iconProps?.tokens?.size
+    const iconAdjusted =
+      Platform.OS === 'android' && iconContent && size ? (
+        <View style={{ transform: [{ translateY: size * 0.2 }] }}>{iconContent}</View>
+      ) : (
+        iconContent
+      )
+
+    return getStackedContent(
+      iconPosition === 'left' ? [iconAdjusted, children] : [children, iconAdjusted],
+      { space, direction: 'row' }
+    )
+  }
+)
+IconText.displayName = 'IconText'
 
 IconText.propTypes = {
   /**

package/src/IconButton/IconButton.jsx

@@ -1,4 +1,4 @@
-import React from 'react'
+import React, { forwardRef } from 'react'
 import PropTypes from 'prop-types'
 import { Pressable, Platform, StyleSheet, View } from 'react-native'
 
@@ -44,49 +44,56 @@ const selectInnerStyle = ({ borderColor, borderWidth = 0, borderRadius, padding
  * based on these to an outer border and a base Card component. Not intended to be used in
  * apps or sites directly: build themed components on top of this.
  */
-const IconButton = ({
-  tokens,
-  variant,
-  icon: IconComponent,
-  href,
-  hrefAttrs,
-  onPress,
-  accessibilityRole = href ? 'link' : 'button',
-  ...rest
-}) => {
-  const a11y = a11yProps.select({
-    ...rest,
-    accessibilityRole
-  })
-  const handlePress = linkProps.handleHref({ href, onPress })
+const IconButton = forwardRef(
+  (
+    {
+      tokens,
+      variant,
+      icon: IconComponent,
+      href,
+      hrefAttrs,
+      onPress,
+      accessibilityRole = href ? 'link' : 'button',
+      ...rest
+    },
+    ref
+  ) => {
+    const a11y = a11yProps.select({
+      ...rest,
+      accessibilityRole
+    })
+    const handlePress = linkProps.handleHref({ href, onPress })
 
-  const getTokens = useThemeTokensCallback('IconButton', tokens, variant)
-  const getOuterStyle = (pressableState) =>
-    selectOuterStyle(getTokens(resolvePressableState(pressableState)))
+    const getTokens = useThemeTokensCallback('IconButton', tokens, variant)
+    const getOuterStyle = (pressableState) =>
+      selectOuterStyle(getTokens(resolvePressableState(pressableState)))
 
-  return (
-    <Pressable
-      href={href}
-      onPress={handlePress}
-      hrefAttrs={hrefAttrs}
-      style={getOuterStyle}
-      {...a11y}
-    >
-      {(pressableState) => {
-        const themeTokens = getTokens(resolvePressableState(pressableState))
-        return (
-          <View style={selectInnerStyle(themeTokens)}>
-            <Icon
-              icon={IconComponent}
-              title={a11y.accessibilityLabel}
-              tokens={selectTokens('Icon', themeTokens, 'icon')}
-            />
-          </View>
-        )
-      }}
-    </Pressable>
-  )
-}
+    return (
+      <Pressable
+        ref={ref}
+        href={href}
+        onPress={handlePress}
+        hrefAttrs={hrefAttrs}
+        style={getOuterStyle}
+        {...a11y}
+      >
+        {(pressableState) => {
+          const themeTokens = getTokens(resolvePressableState(pressableState))
+          return (
+            <View style={selectInnerStyle(themeTokens)}>
+              <Icon
+                icon={IconComponent}
+                title={a11y.accessibilityLabel}
+                tokens={selectTokens('Icon', themeTokens, 'icon')}
+              />
+            </View>
+          )
+        }}
+      </Pressable>
+    )
+  }
+)
+IconButton.displayName = 'IconButton'
 
 IconButton.propTypes = {
   ...a11yProps.types,

package/src/InputLabel/InputLabel.jsx

@@ -1,4 +1,4 @@
-import React from 'react'
+import React, { forwardRef } from 'react'
 import { StyleSheet, Text, View } from 'react-native'
 import PropTypes from 'prop-types'
 
@@ -27,56 +27,71 @@ const selectHintStyles = ({
 
 const selectGapStyles = ({ gap }) => ({ marginRight: gap })
 
-function InputLabel({
-  label,
-  forId,
-  hint,
-  hintPosition = 'inline',
-  hintId,
-  tooltip,
-  tokens,
-  variant
-}) {
-  const themeTokens = useThemeTokens('InputLabel', tokens, variant)
+const InputLabel = forwardRef(
+  ({ label, forId, hint, hintPosition = 'inline', hintId, tooltip, tokens, variant }, ref) => {
+    const themeTokens = useThemeTokens('InputLabel', tokens, variant)
 
-  const hasTooltip = tooltip !== undefined
-  const isHintInline = hintPosition === 'inline'
+    const hasTooltip = tooltip !== undefined
+    const isHintInline = hintPosition === 'inline'
 
-  return (
-    <View style={[staticStyles.container, !isHintInline && staticStyles.containerWithHintBelow]}>
-      <Text
-        style={[selectLabelStyles(themeTokens), selectGapStyles(themeTokens), staticStyles.label]}
+    return (
+      <View
+        ref={ref}
+        style={[staticStyles.container, !isHintInline && staticStyles.containerWithHintBelow]}
       >
-        <LabelContent forId={forId}>{label}</LabelContent>
-      </Text>
-      {hint && isHintInline && (
         <Text
-          style={[selectHintStyles(themeTokens), hasTooltip && selectGapStyles(themeTokens)]}
-          nativeID={hintId}
+          style={[selectLabelStyles(themeTokens), selectGapStyles(themeTokens), staticStyles.label]}
         >
-          {hint}
+          <LabelContent forId={forId}>{label}</LabelContent>
         </Text>
-      )}
-      {hasTooltip && (
-        <View style={staticStyles.tooltipAlign}>
-          <Tooltip content={tooltip} />
-        </View>
-      )}
-      {hint && !isHintInline && (
-        <Text style={[selectHintStyles(themeTokens), staticStyles.hintBelow]} nativeID={hintId}>
-          {hint}
-        </Text>
-      )}
-    </View>
-  )
-}
+        {hint && isHintInline && (
+          <Text
+            style={[selectHintStyles(themeTokens), hasTooltip && selectGapStyles(themeTokens)]}
+            nativeID={hintId}
+          >
+            {hint}
+          </Text>
+        )}
+        {hasTooltip && (
+          <View style={staticStyles.tooltipAlign}>
+            <Tooltip content={tooltip} />
+          </View>
+        )}
+        {hint && !isHintInline && (
+          <Text style={[selectHintStyles(themeTokens), staticStyles.hintBelow]} nativeID={hintId}>
+            {hint}
+          </Text>
+        )}
+      </View>
+    )
+  }
+)
+InputLabel.displayName = 'InputLabel'
 
 InputLabel.propTypes = {
+  /**
+   * The input label.
+   */
   label: PropTypes.string.isRequired,
+  /**
+   * The id attribute of the input which this label refers to.
+   */
   forId: PropTypes.string,
+  /**
+   * A short description of the expected input.
+   */
   hint: PropTypes.string,
+  /**
+   * Position of the hint relative to label. Use `below` to display a larger hint below the label.
+   */
   hintPosition: PropTypes.oneOf(['inline', 'below']),
+  /**
+   * The id attribute passed down to the hint element.
+   */
   hintId: PropTypes.string,
+  /**
+   * Content of an optional `Tooltip`. If set, a tooltip button will be shown next to the label.
+   */
   tooltip: PropTypes.string,
   tokens: getTokensPropType('InputLabel'),
   variant: variantProp.propType