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

package/src/Link/LinkBase.jsx

@@ -1,4 +1,4 @@
-import React from 'react'
+import React, { forwardRef } from 'react'
 import PropTypes from 'prop-types'
 import { Text, Platform, StyleSheet } from 'react-native'
 import {
@@ -11,27 +11,28 @@ import {
 import { resolvePressableTokens } from '../utils/pressability'
 
 import InlinePressable from './InlinePressable'
-import { applyTextStyles } from '../ThemeProvider'
+import { applyTextStyles, applyOuterBorder } from '../ThemeProvider'
 import { IconText, iconComponentPropTypes } from '../Icon'
 
 const selectOuterBorderStyles = ({
   outerBorderColor,
   outerBorderWidth,
   outerBorderGap,
-  outerBorderRadius,
+  borderRadius,
   outerBorderOutline
 }) =>
   // A view wrapper with a border on native messes up inline text alignment
   // so for now make focus styles strictly web-only
   Platform.OS === 'web'
     ? {
-        margin: -1 * (outerBorderGap + outerBorderWidth) || 0,
-        padding: outerBorderGap,
         // Allow theme to define outline, or, turn off outline and use border if rounded corners required
         outline: outerBorderOutline,
-        borderWidth: outerBorderWidth,
-        borderColor: outerBorderColor,
-        borderRadius: outerBorderRadius,
+        ...applyOuterBorder({
+          outerBorderColor,
+          outerBorderWidth,
+          outerBorderGap,
+          borderRadius
+        }),
         // Stops focus ring stretching horizontally if parent has display: block
         // width: fit-content isn't supported on Firefox; can't cascade props like CSS `width: fit-content; width: --moz-fit-content;`
         display: 'inline-flex'
@@ -87,68 +88,78 @@ const selectIconTokens = ({ color, iconSize, iconTranslateX, iconTranslateY }) =
  *   dropped in favour of investigating if a full-featured CSS-in-JS package could or
  *   should be used more widely (e.g. styled components)
  */
-const LinkBase = ({
-  href,
-  onPress,
-  icon,
-  iconPosition = icon ? 'left' : undefined,
-  iconProps,
-  variant,
-  tokens = {},
-  children,
-  accessibilityRole = 'link',
-  ...props
-}) => {
-  const { hrefAttrs, rest } = hrefAttrsProp.bundle(props)
-  const linkPropSet = linkProps.select({
-    accessibilityRole,
-    href,
-    onPress: linkProps.handleHref({ href, onPress }),
-    ...hrefAttrsProp.spread(hrefAttrs),
-    ...rest
-  })
+const LinkBase = forwardRef(
+  (
+    {
+      href,
+      onPress,
+      icon,
+      iconPosition = icon ? 'left' : undefined,
+      iconProps,
+      variant,
+      tokens = {},
+      children,
+      accessibilityRole = 'link',
+      dataSet,
+      ...props
+    },
+    ref
+  ) => {
+    const { hrefAttrs, rest } = hrefAttrsProp.bundle(props)
+    const linkPropSet = linkProps.select({
+      accessibilityRole,
+      href,
+      onPress: linkProps.handleHref({ href, onPress }),
+      hrefAttrs,
+      ...rest
+    })
 
-  const resolveTokens = (pressState) => resolvePressableTokens(tokens, pressState, { iconPosition })
+    const resolveLinkTokens = (pressState) =>
+      resolvePressableTokens(tokens, pressState, { iconPosition })
 
-  // On web, this makes focus rings wrap only the link, not the entire block
-  const blockLeftStyle = Platform.OS === 'web' && staticStyles.blockLeft
+    // On web, this makes focus rings wrap only the link, not the entire block
+    const blockLeftStyle = Platform.OS === 'web' && staticStyles.blockLeft
 
-  return (
-    <InlinePressable
-      {...linkPropSet}
-      style={(linkState) => {
-        const themeTokens = resolveTokens(linkState)
-        const outerBorderStyles = selectOuterBorderStyles(themeTokens)
-        const hasIcon = Boolean(icon || themeTokens.icon)
-        return [outerBorderStyles, blockLeftStyle, hasIcon && staticStyles.rowContainer]
-      }}
-    >
-      {(linkState) => {
-        const themeTokens = resolveTokens(linkState)
-        const textStyles = selectTextStyles(themeTokens)
-        const iconTokens = selectIconTokens(themeTokens)
+    return (
+      <InlinePressable
+        {...linkPropSet}
+        ref={ref}
+        dataSet={dataSet}
+        style={(linkState) => {
+          const themeTokens = resolveLinkTokens(linkState)
+          const outerBorderStyles = selectOuterBorderStyles(themeTokens)
+          const hasIcon = Boolean(icon || themeTokens.icon)
+          return [outerBorderStyles, blockLeftStyle, hasIcon && staticStyles.rowContainer]
+        }}
+      >
+        {(linkState) => {
+          const themeTokens = resolveLinkTokens(linkState)
+          const textStyles = selectTextStyles(themeTokens)
+          const iconTokens = selectIconTokens(themeTokens)
 
-        // TODO: may need to apply some smarter text inheritance here if inline to avoid native
-        // issues like double-application of line heights breaking align-items: baseline
-        const blockTextStyles = selectBlockStyles(themeTokens)
+          // TODO: may need to apply some smarter text inheritance here if inline to avoid native
+          // issues like double-application of line heights breaking align-items: baseline
+          const blockTextStyles = selectBlockStyles(themeTokens)
 
-        const IconComponent = icon || themeTokens.icon
-        const { iconSpace } = themeTokens
+          const IconComponent = icon || themeTokens.icon
+          const { iconSpace } = themeTokens
 
-        return (
-          <IconText
-            icon={IconComponent}
-            iconPosition={iconPosition}
-            space={iconSpace}
-            iconProps={{ ...iconProps, tokens: iconTokens }}
-          >
-            <Text style={[textStyles, blockTextStyles, staticStyles.baseline]}>{children}</Text>
-          </IconText>
-        )
-      }}
-    </InlinePressable>
-  )
-}
+          return (
+            <IconText
+              icon={IconComponent}
+              iconPosition={iconPosition}
+              space={iconSpace}
+              iconProps={{ ...iconProps, tokens: iconTokens }}
+            >
+              <Text style={[textStyles, blockTextStyles, staticStyles.baseline]}>{children}</Text>
+            </IconText>
+          )
+        }}
+      </InlinePressable>
+    )
+  }
+)
+LinkBase.displayName = 'LinkBase'
 
 LinkBase.propTypes = {
   ...a11yProps.types,
@@ -170,7 +181,7 @@ LinkBase.propTypes = {
   iconPosition: PropTypes.oneOf(['left', 'right']),
   /**
    * On Web if href is passed, React Native Web maps this object's props to
-   * `rel`, `target` and (>= RNW 0.15.0) `download` attrs.
+   * `rel`, `target` and `download` attrs.
    */
   hrefAttrs: PropTypes.shape(hrefAttrsProp.types)
 }

package/src/Link/TextButton.jsx

@@ -1,4 +1,4 @@
-import React from 'react'
+import React, { forwardRef } from 'react'
 import PropTypes from 'prop-types'
 
 import { useThemeTokensCallback } from '../ThemeProvider'
@@ -9,28 +9,35 @@ import LinkBase from './LinkBase'
  * Link but has the accessibility role of a `Button`. It should be used for actions that
  * take place on the current page, or for navigation within an app.
  */
-const TextButton = ({
-  onPress,
-  children,
-  variant,
-  tokens,
-  // TODO: this may need to use `link` role on Web in the case of being passed both `href` and
-  // `onPress` in an omniplatform app that uses React Navigation's useLinkProps for internal nav.
-  accessibilityRole = 'button',
-  ...linkProps
-}) => {
-  const getTokens = useThemeTokensCallback('Link', tokens, variant)
-  return (
-    <LinkBase
-      onPress={onPress}
-      accessibilityRole={accessibilityRole}
-      tokens={getTokens}
-      {...linkProps}
-    >
-      {children}
-    </LinkBase>
-  )
-}
+const TextButton = forwardRef(
+  (
+    {
+      onPress,
+      children,
+      variant,
+      tokens,
+      // TODO: this may need to use `link` role on Web in the case of being passed both `href` and
+      // `onPress` in an omniplatform app that uses React Navigation's useLinkProps for internal nav.
+      accessibilityRole = 'button',
+      ...linkProps
+    },
+    ref
+  ) => {
+    const getTokens = useThemeTokensCallback('Link', tokens, variant)
+    return (
+      <LinkBase
+        onPress={onPress}
+        accessibilityRole={accessibilityRole}
+        tokens={getTokens}
+        ref={ref}
+        {...linkProps}
+      >
+        {children}
+      </LinkBase>
+    )
+  }
+)
+TextButton.displayName = 'TextButton'
 
 TextButton.propTypes = {
   ...LinkBase.propTypes,

package/src/List/List.jsx

@@ -1,4 +1,4 @@
-import React, { cloneElement, Children } from 'react'
+import React, { cloneElement, forwardRef, Children } from 'react'
 import { View, Platform } from 'react-native'
 import PropTypes from 'prop-types'
 import { getTokensPropType, variantProp, componentPropType } from '../utils'
@@ -9,7 +9,7 @@ import ListItem from './ListItem'
  * A Unordered List component has a child a ListItem that
  * allows icon, dividers and customized typography
  */
-const List = ({ children, showDivider, tokens, variant, ...rest }) => {
+const List = forwardRef(({ children, showDivider, tokens, variant, ...rest }, ref) => {
   const accessibilityRole = Platform.select({ web: 'list', default: 'none' })
   const a11y = a11yProps.select(rest)
   const items = Children.map(children, (child, index) => {
@@ -25,11 +25,12 @@ const List = ({ children, showDivider, tokens, variant, ...rest }) => {
   })
 
   return (
-    <View accessibilityRole={accessibilityRole} {...a11y}>
+    <View ref={ref} accessibilityRole={accessibilityRole} {...a11y}>
       {items}
     </View>
   )
-}
+})
+List.displayName = 'List'
 
 List.Item = ListItem
 

package/src/List/ListItem.jsx

@@ -1,4 +1,4 @@
-import React from 'react'
+import React, { forwardRef } from 'react'
 import { View, Platform, Text, StyleSheet } from 'react-native'
 import PropTypes from 'prop-types'
 import { useThemeTokens, applyTextStyles } from '../ThemeProvider'
@@ -48,104 +48,96 @@ const selectDividerStyles = ({ dividerColor, dividerSize, interItemMarginWithDiv
 /**
  * ListItem is responsible for rendering icon or a bullet as side item
  */
-const ListItem = ({
-  tokens,
-  variant,
-  icon,
-  iconColor,
-  iconSize,
-  showDivider,
-  children,
-  isLastItem
-}) => {
-  const themeTokens = useThemeTokens('List', tokens, variant)
-
-  const itemStyles = selectItemStyles(themeTokens)
-  const itemBlockStyles = selectItemBlockStyles(themeTokens)
-  const dividerStyles = selectDividerStyles(themeTokens)
-  const itemBulletContainerStyles = selectBulletContainerStyles(themeTokens)
-  const itemBulletStyles = selectBulletStyles(themeTokens)
-  const iconTokens = selectItemIconTokens(themeTokens)
-  const sideItemContainerStyles = selectSideItemContainerStyles(themeTokens)
-  const accessibilityRole = Platform.select({ web: 'listitem', default: 'item' })
-
-  const areChildrenStrings = () => {
-    if (Array.isArray(children)) {
-      return children.every((child) => typeof child === 'string')
+const ListItem = forwardRef(
+  ({ tokens, variant, icon, iconColor, iconSize, showDivider, children, isLastItem }, ref) => {
+    const themeTokens = useThemeTokens('List', tokens, variant)
+
+    const itemStyles = selectItemStyles(themeTokens)
+    const itemBlockStyles = selectItemBlockStyles(themeTokens)
+    const dividerStyles = selectDividerStyles(themeTokens)
+    const itemBulletContainerStyles = selectBulletContainerStyles(themeTokens)
+    const itemBulletStyles = selectBulletStyles(themeTokens)
+    const iconTokens = selectItemIconTokens(themeTokens)
+    const sideItemContainerStyles = selectSideItemContainerStyles(themeTokens)
+    const accessibilityRole = Platform.select({ web: 'listitem', default: 'item' })
+
+    const areChildrenStrings = () => {
+      if (Array.isArray(children)) {
+        return children.every((child) => typeof child === 'string')
+      }
+
+      return typeof children === 'string'
     }
 
-    return typeof children === 'string'
-  }
-
-  const renderItem = () => {
-    if (areChildrenStrings()) {
-      return <Text style={itemStyles}>{children}</Text>
-    }
+    const renderItem = () => {
+      if (areChildrenStrings()) {
+        return <Text style={itemStyles}>{children}</Text>
+      }
 
-    return <View>{children}</View>
-  }
-
-  /**
-   * Function responsible returning styling, in case the item is the last shouldn't
-   * add extra margin on the bottom, if "showDivider" is true it should add a divider
-   * and custom margin and padding, otherwise just adds a margin to the bottom
-   */
-  const getContainerStyle = () => {
-    if (isLastItem) {
-      return undefined
+      return <View style={staticStyles.wrap}>{children}</View>
     }
 
-    if (showDivider) {
-      return dividerStyles
+    /**
+     * Function responsible returning styling, in case the item is the last shouldn't
+     * add extra margin on the bottom, if "showDivider" is true it should add a divider
+     * and custom margin and padding, otherwise just adds a margin to the bottom
+     */
+    const getContainerStyle = () => {
+      if (isLastItem) {
+        return undefined
+      }
+
+      if (showDivider) {
+        return dividerStyles
+      }
+
+      return itemBlockStyles
     }
 
-    return itemBlockStyles
-  }
-
-  /**
-   * Renders item bullet or Icon in case it's defined
-   * in case children are string the icon is centered otherwise
-   * it will align itself at start of the container
-   */
-  const renderMarker = () => {
-    const IconComponent = icon || <></>
+    /**
+     * Renders item bullet or Icon in case it's defined
+     * in case children are string the icon is centered otherwise
+     * it will align itself at start of the container
+     */
+    const renderMarker = () => {
+      const IconComponent = icon || <></>
+
+      if (icon) {
+        return (
+          <View
+            style={[
+              sideItemContainerStyles,
+              areChildrenStrings() ? staticStyles.centeredIcons : undefined
+            ]}
+          >
+            <IconComponent
+              size={iconSize || iconTokens.size}
+              color={iconColor || iconTokens.color}
+            />
+          </View>
+        )
+      }
 
-    if (icon) {
       return (
-        <View
-          style={[
-            sideItemContainerStyles,
-            areChildrenStrings() ? staticStyles.centeredIcons : undefined
-          ]}
-        >
-          <IconComponent
-            tokens={{
-              ...iconTokens,
-              size: iconSize || iconTokens.size,
-              color: iconColor || iconTokens.color
-            }}
-          />
+        <View style={[sideItemContainerStyles, itemBulletContainerStyles]}>
+          <View style={itemBulletStyles} testID="unordered-item-bullet" />
         </View>
       )
     }
 
     return (
-      <View style={[sideItemContainerStyles, itemBulletContainerStyles]}>
-        <View style={itemBulletStyles} testID="unordered-item-bullet" />
+      <View
+        ref={ref}
+        style={[staticStyles.itemContainer, getContainerStyle()]}
+        accessibilityRole={accessibilityRole}
+      >
+        {renderMarker()}
+        {renderItem()}
       </View>
     )
   }
-
-  return (
-    <View
-      style={[staticStyles.itemContainer, getContainerStyle()]}
-      accessibilityRole={accessibilityRole}
-    >
-      {renderMarker()}
-      {renderItem()}
-    </View>
-  )
-}
+)
+ListItem.displayName = 'ListItem'
 
 const staticStyles = StyleSheet.create({
   itemContainer: {
@@ -153,6 +145,9 @@ const staticStyles = StyleSheet.create({
   },
   centeredIcons: {
     justifyContent: 'center'
+  },
+  wrap: {
+    flex: 1
   }
 })
 

package/src/Modal/Modal.jsx

@@ -0,0 +1,190 @@
+import React, { forwardRef } from 'react'
+import {
+  StyleSheet,
+  TouchableWithoutFeedback,
+  View,
+  Modal as NativeModal,
+  Platform
+} from 'react-native'
+
+import PropTypes from 'prop-types'
+import { applyShadowToken, useThemeTokens } from '../ThemeProvider'
+import { getTokensPropType, useCopy, copyPropTypes, variantProp } from '../utils'
+import { useViewport } from '../ViewportProvider'
+import ButtonBase from '../Button/ButtonBase'
+import dictionary from './dictionary'
+
+const selectContainerStyles = ({
+  containerPaddingLeft,
+  containerPaddingRight,
+  containerPaddingTop,
+  containerPaddingBottom,
+  maxWidth,
+  height
+}) => ({
+  height,
+  maxWidth,
+  paddingLeft: containerPaddingLeft,
+  paddingRight: containerPaddingRight,
+  paddingTop: containerPaddingTop,
+  paddingBottom: containerPaddingBottom
+})
+
+const selectModalStyles = ({
+  backgroundColor,
+  borderRadius,
+  height,
+  paddingLeft,
+  paddingRight,
+  paddingTop,
+  paddingBottom,
+  shadow
+}) => ({
+  backgroundColor,
+  borderRadius,
+  height,
+  paddingLeft,
+  paddingRight,
+  paddingTop,
+  paddingBottom,
+  ...applyShadowToken(shadow)
+})
+
+const selectBackdropStyles = ({ backdropColor, backdropOpacity }) => ({
+  backgroundColor: backdropColor,
+  opacity: backdropOpacity
+})
+
+const selectCloseButtonContainerStyles = ({ paddingRight, paddingTop }) => ({
+  paddingRight,
+  paddingTop
+})
+
+const selectCloseIconProps = ({ closeIconSize, closeIconColor }) => ({
+  size: closeIconSize,
+  color: closeIconColor
+})
+
+/**
+ * A modal window is a secondary window that opens on top of the main one.
+ * Users have to interact with it before they can carry out their task and return to the main window.
+ * Use to reveal additional information to a user after they have performed an explicit interaction.
+ * They are a strongly discouraged pattern; it's preferred to have all relevant information within a page,
+ * and irrelevant information either linked externally or omitted.
+ *
+ * - Must only appear after a customer interaction, not on page load or any other circumstance
+ * - Open a modal based on explicit customer action e.g. clicking on a button/link/form field
+ * - Only one modal should be "current" at any time
+ * - Read [WebAIM's documentation](https://www.w3.org/TR/wai-aria-practices/examples/dialog-modal/dialog.html) to create accessible modals
+ * - Don’t use modals to reinforce or repeat information already available in the parent page or view
+ * - Don’t use modals consecutively
+ */
+const Modal = forwardRef(({ children, isOpen, onClose, maxWidth, tokens, variant, copy }, ref) => {
+  const viewport = useViewport()
+  const themeTokens = useThemeTokens('Modal', tokens, variant, { viewport, maxWidth })
+
+  const { closeIcon: CloseIconComponent } = themeTokens
+
+  const getCopy = useCopy({ dictionary, copy })
+  const closeLabel = getCopy('closeButton')
+
+  const handleClose = () => {
+    if (typeof onClose === 'function') onClose()
+  }
+
+  const handleKeyUp = (event) => {
+    if (event.key === 'Escape') onClose()
+  }
+
+  if (!isOpen) {
+    return null
+  }
+
+  // TODO: replace the close button with IconButton when implemented (https://github.com/telus/universal-design-system/issues/281)
+  return (
+    <NativeModal transparent>
+      <View style={[staticStyles.positioningContainer]}>
+        <View
+          style={[staticStyles.sizingContainer, selectContainerStyles(themeTokens)]}
+          pointerEvents="box-none" // don't capture backdrop press events
+        >
+          <View
+            ref={ref}
+            style={[staticStyles.modal, selectModalStyles(themeTokens)]}
+            onKeyUp={handleKeyUp}
+          >
+            <View
+              style={[
+                staticStyles.closeButtonContainer,
+                selectCloseButtonContainerStyles(themeTokens)
+              ]}
+            >
+              <ButtonBase
+                onPress={handleClose}
+                accessibilityRole="button"
+                accessibilityLabel={closeLabel}
+              >
+                {
+                  // TODO: add close button interactive states after IconButton is done
+                  () => <CloseIconComponent {...selectCloseIconProps(themeTokens)} />
+                }
+              </ButtonBase>
+            </View>
+            {children}
+          </View>
+        </View>
+        {/* when a modal becomes open its first focusable element is being automatically focused */}
+        {/* and we prefer the close button over backdrop */}
+        <TouchableWithoutFeedback onPress={handleClose}>
+          <View style={[staticStyles.backdrop, selectBackdropStyles(themeTokens)]} />
+        </TouchableWithoutFeedback>
+      </View>
+    </NativeModal>
+  )
+})
+Modal.displayName = 'Modal'
+
+Modal.propTypes = {
+  children: PropTypes.oneOfType([PropTypes.node, PropTypes.arrayOf(PropTypes.node)]),
+  copy: copyPropTypes,
+  isOpen: PropTypes.bool,
+  onClose: PropTypes.func,
+  maxWidth: PropTypes.bool,
+  tokens: getTokensPropType('Modal'),
+  variant: variantProp.propType
+}
+
+export default Modal
+
+const staticStyles = StyleSheet.create({
+  backdrop: {
+    position: 'absolute',
+    top: 0,
+    left: 0,
+    right: 0,
+    bottom: 0,
+    zIndex: -1,
+    ...Platform.select({
+      web: {
+        cursor: 'pointer'
+      }
+    })
+  },
+  positioningContainer: {
+    flexBasis: '100%',
+    alignItems: 'center',
+    justifyContent: 'center'
+  },
+  sizingContainer: {
+    maxHeight: '100%', // so that the container can expand up to the full viewport height
+    width: '100%' // ensure that the modal actually expands to the set maxWidth
+  },
+  modal: {
+    maxHeight: '100%' // so that the modal can expand vertically up to the  sizing container's height (exclusive of its vertical padding)
+  },
+  closeButtonContainer: {
+    position: 'absolute',
+    top: 0,
+    right: 0
+  }
+})

package/src/Modal/dictionary.js

@@ -0,0 +1,9 @@
+export default {
+  en: {
+    // English text from TDS Community `Modal`
+    closeButton: 'Close'
+  },
+  fr: {
+    closeButton: 'Fermer'
+  }
+}

package/src/Modal/index.js

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