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

package/src/Tabs/Tabs.jsx

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

package/src/Tabs/TabsItem.jsx

@@ -0,0 +1,212 @@
+import React, { forwardRef, useEffect } from 'react'
+import PropTypes from 'prop-types'
+import { Platform, Pressable, StyleSheet, Text, View } from 'react-native'
+
+import { applyTextStyles, useThemeTokensCallback } from '../ThemeProvider'
+import {
+  resolvePressableTokens,
+  selectTokens,
+  variantProp,
+  getTokensPropType,
+  linkProps,
+  a11yProps
+} from '../utils'
+import Spacer from '../Spacer'
+import { horizontalScrollUtils } from '../HorizontalScroll'
+
+const { itemPositionsPropType, getItemPositionLayoutHandler } = horizontalScrollUtils
+
+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: 'transparent',
+    borderLeftColor: 'transparent',
+    borderRightColor: '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 = forwardRef(
+  (
+    {
+      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
+    },
+    ref
+  ) => {
+    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
+        ref={ref}
+        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.displayName = 'TabsItem'
+
+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/index.js

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

package/src/Tags/Tags.jsx

@@ -0,0 +1,219 @@
+import React, { forwardRef } from 'react'
+import PropTypes from 'prop-types'
+import ABBPropTypes from 'airbnb-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 = forwardRef(
+  (
+    {
+      variant,
+      tokens,
+      items = [],
+      values,
+      initialValues,
+      maxValues,
+      onChange,
+      readOnly = false,
+      inactive = false,
+      accessibilityRole = Platform.select({ web: 'group', default: 'none' }),
+      ...rest
+    },
+    ref
+  ) => {
+    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 ref={ref} {...a11y} space={space} direction={direction} tokens={stackTokens}>
+        {items.map(({ label, id = label, accessibilityLabel, ref: itemRef }, 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 = (event) => {
+            if (pressHandlers.onPress) pressHandlers.onPress()
+            toggleOneValue(id, event)
+          }
+
+          const itemA11y = {
+            accessibilityState: { checked: isSelected },
+            accessibilityRole: itemA11yRole,
+            accessibilityLabel,
+            ...a11yProps.getPositionInSet(items.length, index)
+          }
+
+          return (
+            <ButtonBase
+              ref={itemRef}
+              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.displayName = 'Tags'
+
+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,
+      /**
+       * An optional ref for one individual Tag button in the tags
+       */
+      ref: ABBPropTypes.ref()
+    })
+  ),
+  /**
+   * 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

package/src/TextInput/TextArea.jsx

@@ -0,0 +1,79 @@
+import React, { forwardRef, useState } from 'react'
+
+import { Platform } from 'react-native'
+import { getTokensPropType, variantProp } from '../utils'
+import InputSupports from '../InputSupports'
+import TextInputBase from './TextInputBase'
+import { useThemeTokens } from '../ThemeProvider'
+import inputSupportProps from '../InputSupports/propTypes'
+import textInputPropTypes from './propTypes'
+
+/**
+ * Use to collect long-form information such as product feedback or support queries.
+ * Due to React Native's implementation of `TextInput` it's not possible to access the current value by passing a ref.
+ * The `TextArea` height will automatically increase when new lines are added - this behavior can be limited within the theme.
+ *
+ * ## Controlled component
+ * If it is required that the state of the `TextArea` be controlled by the application or other external methods,
+ * `value` and `onChange` props must be passed to the `TextArea`.
+ * If the `TextArea` value should not be changed by user input, a `readOnly` prop must be provided.
+ *
+ * ## Uncontrolled component
+ * If it is not necessary to control the `TextArea` state, you can create one without a value prop.
+ * In this case its value can be accessed within the `onChange` callback.
+ *
+ * ## Getting feedback for entered values
+ * Use the `feedback` prop to give the user feedback regarding their input.
+ * You can affirm that the user's input was correct, or highlight errors that must be corrected, using the `validation` prop.
+ * Keep feedback text as brief as possible, should be limited to text and links.
+ *
+ * ## Supplying a hint
+ * Use the `hint` prop to succinctly clarify attributes of the expected input data, such as the expected format,
+ * or an indicator that the field is optional.
+ * It is a more usable and accessible option than the HTML `placeholder` attribute.
+ */
+const TextArea = forwardRef(({ tokens, variant = {}, ...remainingProps }, ref) => {
+  const themeTokens = useThemeTokens('TextArea', tokens, variant)
+  const [inputHeight, setInputHeight] = useState()
+
+  // adjust the text area's height as new lines are added to the content
+  const onHeightChange = ({
+    nativeEvent: {
+      contentSize: { height }
+    }
+  }) => {
+    // on native this is happens out of the box
+    if (Platform.OS === 'web') {
+      setInputHeight(height)
+    }
+  }
+
+  const { props: supportsProps, rest } = inputSupportProps.select(remainingProps)
+
+  const inputProps = {
+    ...rest,
+    variant: { ...variant, validation: supportsProps.validation },
+    multiline: true,
+    onContentSizeChange: onHeightChange,
+    height: inputHeight,
+    tokens: themeTokens
+  }
+
+  return (
+    <InputSupports {...supportsProps}>
+      {({ a11yProps, inputId }) => (
+        <TextInputBase ref={ref} {...inputProps} {...a11yProps} nativeID={inputId} />
+      )}
+    </InputSupports>
+  )
+})
+TextArea.displayName = 'TextArea'
+
+TextArea.propTypes = {
+  ...inputSupportProps.types,
+  ...textInputPropTypes,
+  tokens: getTokensPropType('TextArea', 'TextInput'), // TODO: support both TextArea and TextInput tokens
+  variant: variantProp.propType
+}
+
+export default TextArea