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

package/src/HorizontalScroll/HorizontalScrollButton.jsx

@@ -0,0 +1,108 @@
+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 HorizontalScrollButton = ({
+  direction = 'next',
+  icon,
+  onPress,
+  offset,
+  variant,
+  tokens,
+  copy
+}) => {
+  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
+      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
+  }
+})
+
+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
+})

package/src/Icon/Icon.jsx

@@ -3,23 +3,34 @@ import { Platform, View } from 'react-native'
 import PropTypes from 'prop-types'
 
 import { useThemeTokens } from '../ThemeProvider'
-import { getTokensPropType, variantProp } from '../utils/propTypes'
+import { getTokensPropType, scaleWithText, variantProp } from '../utils'
 
-const Icon = ({ IconSvg, variant, label, titleId, tokens = {} }) => {
+const Icon = ({
+  icon: IconComponent,
+  accessibilityLabel,
+  variant,
+  tokens,
+  scalesWithText = false
+}) => {
   const themeTokens = useThemeTokens('Icon', tokens, variant)
+
+  const size = scalesWithText ? scaleWithText(themeTokens.size) : themeTokens.size
+
   const iconContent = (
-    <IconSvg title={label} titleId={titleId} size={themeTokens.size} color={themeTokens.color} />
+    <IconComponent title={accessibilityLabel} size={size} color={themeTokens.color} />
   )
 
   return Platform.OS === 'web' ? (
     <View
       // eslint-disable-next-line react-native/no-inline-styles
       style={{
-        // TODO: https://github.com/telus/universal-design-system/issues/487
-        transition: 'transform 200ms',
+        // 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.translateX ? `translateX(${themeTokens.translateX}px)` : '',
+          themeTokens.translateY ? `translateY(${themeTokens.translateY}px)` : ''
         ]
           .filter((exists) => exists)
           .join(' ')
@@ -32,41 +43,26 @@ const Icon = ({ IconSvg, variant, label, titleId, tokens = {} }) => {
   )
 }
 
-// Auto-generated SVG icon components wrap Icon and pass through these props:
 export const iconComponentPropTypes = {
   variant: variantProp.propType,
   tokens: getTokensPropType('Icon'),
   /**
    * Descriptive label used in web SVG title tag for accessibility
    */
-  label: PropTypes.string,
-  /**
-   * On web, this unique id is applied to <SVG> title and aria-labelledby attr
-   */
-  titleId: PropTypes.string
-}
-
-// Auto-generated SVG icon components contain an inner SVG component taking these props:
-export const iconSvgPropTypes = {
-  title: iconComponentPropTypes.label,
-  titleId: iconComponentPropTypes.titleId,
-  /**
-   * The size of the SVG icon after resolving tokens
-   */
-  size: PropTypes.number,
+  accessibilityLabel: PropTypes.string,
   /**
-   * The color of the SVG icon after resolving tokens
+   * controls whether the icon size should be proportionate to any accessibility-related font scaling.
    */
-  color: PropTypes.string
+  scalesWithText: PropTypes.bool
 }
 
 Icon.propTypes = {
   ...iconComponentPropTypes,
   /**
-   * Function component containing this icon's SVG or native equivalent.
-   * UDS's SVGR config turns static SVG files into components that pass this to <Icon>.
+   * A valid UDS icon component imported from a UDS palette
+   * (e.g.) `import { MyIcon } from @telus-uds/palette-<brand>/build/web/icons`
    */
-  IconSvg: PropTypes.func.isRequired
+  icon: PropTypes.elementType.isRequired
 }
 
 export default Icon

package/src/Icon/IconText.jsx

@@ -0,0 +1,63 @@
+import React from 'react'
+import PropTypes from 'prop-types'
+import { Platform, View } from 'react-native'
+
+import Icon, { iconComponentPropTypes } from './Icon'
+import { getStackedContent } from '../StackView'
+import { spacingProps } from '../utils'
+
+/**
+ * Returns an icon and some text with a sized gap between them. This is a utility component
+ * intended for use when creating components, not intended for use in applications on its own.
+ *
+ * IconText does not wrap its children, so should be used either:
+ *  - 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
+    )
+
+  return getStackedContent(
+    iconPosition === 'left' ? [iconAdjusted, children] : [children, iconAdjusted],
+    { space, direction: 'row' }
+  )
+}
+
+IconText.propTypes = {
+  /**
+   * Amount of space to separate the text content and icon. Uses the themes's spacing scale
+   * (see useSpacingScale for more info).
+   */
+  space: spacingProps.types.spacingValue,
+  /**
+   * Whether the icon should be to the left of the content or the right of the content.
+   */
+  iconPosition: PropTypes.oneOf(['left', 'right']),
+  /**
+   * A valid UDS icon component imported from a UDS palette.
+   */
+  icon: PropTypes.func,
+  /**
+   * Props that will be passed to the icon component. By default the icon's `scalesWithText`
+   * prop will be set as "true" so that the icon continues to match the size of the text
+   * if users use accessibility settings to increase text size.
+   */
+  iconProps: PropTypes.exact(iconComponentPropTypes),
+  /**
+   * Content to be rendered alongside the Icon component. Usually this should be a
+   * `<Typography>` component, or a component that renders `<Text>`.
+   */
+  children: PropTypes.node
+}
+
+export default IconText

package/src/Icon/index.js

@@ -1,4 +1,5 @@
-import Icon, { iconComponentPropTypes, iconSvgPropTypes } from './Icon'
+import Icon, { iconComponentPropTypes } from './Icon'
+import IconText from './IconText'
 
 export default Icon
-export { iconComponentPropTypes, iconSvgPropTypes }
+export { iconComponentPropTypes, IconText }

package/src/IconButton/IconButton.jsx

@@ -0,0 +1,107 @@
+import React from 'react'
+import PropTypes from 'prop-types'
+import { Pressable, Platform, StyleSheet, View } from 'react-native'
+
+import { applyOuterBorder, useThemeTokensCallback, applyShadowToken } from '../ThemeProvider'
+import {
+  variantProp,
+  linkProps,
+  resolvePressableState,
+  hrefAttrsProp,
+  getTokensPropType,
+  selectTokens
+} from '../utils'
+import { a11yProps } from '../utils/propTypes'
+import Icon from '../Icon'
+
+const selectOuterStyle = ({
+  backgroundColor,
+  borderRadius,
+  outerBorderWidth,
+  outerBorderColor,
+  outerBorderGap,
+  shadow
+}) => [
+  {
+    backgroundColor,
+    ...applyShadowToken(shadow),
+    ...applyOuterBorder({ borderRadius, outerBorderWidth, outerBorderColor, outerBorderGap }),
+    ...Platform.select({ web: { outline: 'none', display: 'inline-flex' } })
+  },
+  staticStyles.outer
+]
+
+const selectInnerStyle = ({ borderColor, borderWidth = 0, borderRadius, padding = 0 }) => ({
+  // Inner borders animate with the icon and should be treated like a themable feature of the icon
+  borderColor,
+  borderRadius,
+  borderWidth,
+  padding: Math.max(0, padding - borderWidth) // Stable size as border changes
+})
+
+/**
+ * A pressable themeless base component that handles pressable states and passes tokens
+ * 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 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>
+  )
+}
+
+IconButton.propTypes = {
+  ...a11yProps.types,
+  variant: variantProp.propType,
+  tokens: getTokensPropType('IconButton'),
+  icon: PropTypes.elementType.isRequired,
+  href: PropTypes.string,
+  hrefAttrs: PropTypes.shape(hrefAttrsProp.types),
+  onPress: PropTypes.func
+}
+
+const staticStyles = StyleSheet.create({
+  outer: {
+    alignSelf: 'flex-start'
+  }
+})
+
+export default IconButton

package/src/IconButton/index.js

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