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

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

@@ -1,4 +1,4 @@
-import React from 'react'
+import React, { forwardRef } from 'react'
 import {
   StyleSheet,
   TouchableWithoutFeedback,
@@ -79,7 +79,7 @@ const selectCloseIconProps = ({ closeIconSize, closeIconColor }) => ({
  * - Don’t use modals to reinforce or repeat information already available in the parent page or view
  * - Don’t use modals consecutively
  */
-const Modal = ({ children, isOpen, onClose, maxWidth, tokens, variant, copy }) => {
+const Modal = forwardRef(({ children, isOpen, onClose, maxWidth, tokens, variant, copy }, ref) => {
   const viewport = useViewport()
   const themeTokens = useThemeTokens('Modal', tokens, variant, { viewport, maxWidth })
 
@@ -108,7 +108,11 @@ const Modal = ({ children, isOpen, onClose, maxWidth, tokens, variant, copy }) =
           style={[staticStyles.sizingContainer, selectContainerStyles(themeTokens)]}
           pointerEvents="box-none" // don't capture backdrop press events
         >
-          <View style={[staticStyles.modal, selectModalStyles(themeTokens)]} onKeyUp={handleKeyUp}>
+          <View
+            ref={ref}
+            style={[staticStyles.modal, selectModalStyles(themeTokens)]}
+            onKeyUp={handleKeyUp}
+          >
             <View
               style={[
                 staticStyles.closeButtonContainer,
@@ -137,7 +141,8 @@ const Modal = ({ children, isOpen, onClose, maxWidth, tokens, variant, copy }) =
       </View>
     </NativeModal>
   )
-}
+})
+Modal.displayName = 'Modal'
 
 Modal.propTypes = {
   children: PropTypes.oneOfType([PropTypes.node, PropTypes.arrayOf(PropTypes.node)]),

package/src/Notification/Notification.jsx

@@ -1,4 +1,4 @@
-import React, { useState } from 'react'
+import React, { forwardRef, useState } from 'react'
 import { StyleSheet, Text, View } from 'react-native'
 
 import PropTypes from 'prop-types'
@@ -42,7 +42,7 @@ const selectDismissButtonContainerStyles = ({ dismissButtonGap }) => ({
  * - Show system notifications at the top of the page, below the navigation, and expands the full-width of the viewport
  * - When showing multiple notifications, show them in order of importance from top to bottom
  * - Use variants to visually show the type of message contained within the Notification.
- * The icon and colour will indicate meaning and importance
+ * - The icon and colour will indicate meaning and importance
  *
  * ### Variants
  * - Use `variant.style` to set the visual style of the notification
@@ -81,54 +81,69 @@ const selectDismissButtonContainerStyles = ({ dismissButtonGap }) => ({
  * Use full-width `Notifications` to show system-based messages coming from the application, not in response to user action.
  * Show system notifications at the top of the page, below the navigation, and expands the full-width of the viewport
  */
-const Notification = ({ children, system, dismissible, copy = 'en', tokens, variant }) => {
-  const [isDismissed, setIsDismissed] = useState(false)
-  const themeTokens = useThemeTokens('Notification', tokens, variant, { system })
-  const getCopy = useCopy({ dictionary, copy })
-
-  if (isDismissed) {
-    return null
-  }
-
-  const textStyles = selectTextStyles(themeTokens)
-
-  const content =
-    typeof children === 'string' ? <Text style={textStyles}>{children}</Text> : children
-
-  const { icon: IconComponent, dismissIcon: DismissIconComponent } = themeTokens
-
-  const onDismissPress = () => setIsDismissed(true)
-
-  // TODO: replace the dismiss button with IconButton when implemented (https://github.com/telus/universal-design-system/issues/281)
-  return (
-    <View style={[staticStyles.container, selectContainerStyles(themeTokens)]}>
-      {IconComponent && (
-        <View style={selectIconContainerStyles(themeTokens)}>
-          <IconComponent {...selectIconProps(themeTokens)} />
+const Notification = forwardRef(
+  ({ children, system, dismissible, copy = 'en', tokens, variant }, ref) => {
+    const [isDismissed, setIsDismissed] = useState(false)
+    const themeTokens = useThemeTokens('Notification', tokens, variant, { system })
+    const getCopy = useCopy({ dictionary, copy })
+
+    if (isDismissed) {
+      return null
+    }
+
+    const textStyles = selectTextStyles(themeTokens)
+
+    const content =
+      typeof children === 'string' ? <Text style={textStyles}>{children}</Text> : children
+
+    const { icon: IconComponent, dismissIcon: DismissIconComponent } = themeTokens
+
+    const onDismissPress = () => setIsDismissed(true)
+
+    // TODO: replace the dismiss button with IconButton when implemented (https://github.com/telus/universal-design-system/issues/281)
+    return (
+      <View ref={ref} style={[staticStyles.container, selectContainerStyles(themeTokens)]}>
+        {IconComponent && (
+          <View style={selectIconContainerStyles(themeTokens)}>
+            <IconComponent {...selectIconProps(themeTokens)} />
+          </View>
+        )}
+        <View style={staticStyles.contentContainer}>
+          {content && typeof content === 'function' ? content({ textStyles, variant }) : content}
         </View>
-      )}
-      <View style={staticStyles.contentContainer}>
-        {content && typeof content === 'function' ? content({ textStyles, variant }) : content}
+        {dismissible && DismissIconComponent && (
+          <View style={selectDismissButtonContainerStyles(themeTokens)}>
+            <ButtonBase
+              onPress={onDismissPress}
+              accessibilityRole="button"
+              accessibilityLabel={getCopy('dismiss')}
+            >
+              {() => <DismissIconComponent {...selectDismissIconProps(themeTokens)} />}
+            </ButtonBase>
+          </View>
+        )}
       </View>
-      {dismissible && DismissIconComponent && (
-        <View style={selectDismissButtonContainerStyles(themeTokens)}>
-          <ButtonBase
-            onPress={onDismissPress}
-            accessibilityRole="button"
-            accessibilityLabel={getCopy('dismiss')}
-          >
-            {() => <DismissIconComponent {...selectDismissIconProps(themeTokens)} />}
-          </ButtonBase>
-        </View>
-      )}
-    </View>
-  )
-}
+    )
+  }
+)
+Notification.displayName = 'Notification'
 
 Notification.propTypes = {
+  /**
+   * Content of the `Notification`.
+   */
   children: PropTypes.oneOfType([PropTypes.string, PropTypes.node, PropTypes.func]),
+  /**
+   * Use `system` prop to set the visual style of the notification and denote an announcement from the system or application
+   */
   system: PropTypes.bool,
+  /**
+   * Use the `dismissible` prop to allow users to dismiss the Notification at any time.
+   */
   dismissible: PropTypes.bool,
+  /**
+   * Select english or french copy for the accessible label of the dismiss button.
+   */
   copy: PropTypes.oneOfType([
     PropTypes.oneOf(['en', 'fr']),
     PropTypes.shape({ dismiss: PropTypes.string })

package/src/Pagination/PageButton.jsx

@@ -1,4 +1,4 @@
-import React from 'react'
+import React, { forwardRef } from 'react'
 import PropTypes from 'prop-types'
 
 import ButtonBase from '../Button/ButtonBase'
@@ -8,7 +8,6 @@ import {
   copyPropTypes,
   getTokensPropType,
   hrefAttrsProp,
-  linkProps,
   selectTokens,
   variantProp
 } from '../utils'
@@ -16,51 +15,59 @@ import {
 import useCopy from '../utils/useCopy'
 import dictionary from './dictionary'
 
-function PageButton({ label, onPress, href, isActive, copy, variant, tokens, ...props }) {
-  const getTokens = useThemeTokensCallback('PaginationPageButton', tokens, variant)
+const PageButton = forwardRef(
+  ({ label, onPress, href, isActive, copy, variant, tokens, ...props }, ref) => {
+    const getTokens = useThemeTokensCallback('PaginationPageButton', tokens, variant)
 
-  const getCopy = useCopy({ dictionary, copy })
+    const getCopy = useCopy({ dictionary, copy })
 
-  const getButtonTokens = (buttonState) => selectTokens('Button', getTokens(buttonState))
+    const getButtonTokens = (buttonState) => selectTokens('Button', getTokens(buttonState))
 
-  const activeProps = isActive
-    ? {
-        selected: true,
-        ...a11yProps.nonFocusableProps,
-        // a brute fix for the focus state being stuck on an active item since it becomes non-focusable
-        // (see https://github.com/telus/universal-design-system/pull/577#issuecomment-931344107)
-        key: 'active-item'
-      }
-    : {}
+    const activeProps = isActive
+      ? {
+          selected: true,
+          ...a11yProps.nonFocusableProps,
+          // a brute fix for the focus state being stuck on an active item since it becomes non-focusable
+          // (see https://github.com/telus/universal-design-system/pull/577#issuecomment-931344107)
+          key: 'active-item'
+        }
+      : {}
 
-  const accessibilityRole = href !== undefined ? 'link' : 'button'
-  const activeLabel = isActive ? ` ${getCopy('currentLabel')}` : ''
-  const accessibilityLabel = `${getCopy('goToLabel')} ${label}${activeLabel}`
+    const accessibilityRole = href !== undefined ? 'link' : 'button'
+    const activeLabel = isActive ? ` ${getCopy('currentLabel')}` : ''
+    const accessibilityLabel = `${getCopy('goToLabel')} ${label}${activeLabel}`
 
-  const { hrefAttrs, rest } = hrefAttrsProp.bundle(props)
-  const buttonProps = {
-    accessibilityRole,
-    accessibilityLabel,
-    onPress,
-    href,
-    hrefAttrs,
-    ...rest
-  }
+    const { hrefAttrs, rest } = hrefAttrsProp.bundle(props)
+    const buttonProps = {
+      accessibilityRole,
+      accessibilityLabel,
+      onPress,
+      href,
+      hrefAttrs,
+      ...rest
+    }
 
-  return (
-    <ButtonBase {...buttonProps} tokens={getButtonTokens} {...activeProps}>
-      {label}
-    </ButtonBase>
-  )
-}
+    return (
+      <ButtonBase ref={ref} {...buttonProps} tokens={getButtonTokens} {...activeProps}>
+        {label}
+      </ButtonBase>
+    )
+  }
+)
+PageButton.displayName = 'PageButton'
 
 PageButton.propTypes = {
+  // Spreading any props into a secondary component accessed like Pagination.PageButton
+  // crashes a Docusaurus props table, but only in production, not in development
+  onPress: PropTypes.func,
+  href: PropTypes.string,
+  // If the above is fixed, the above can be replaced with this which includes full a11y etc:
+  // ...linkProps.types,
   label: PropTypes.string,
   isActive: PropTypes.bool,
   copy: copyPropTypes,
   variant: variantProp.propType,
-  tokens: getTokensPropType('PaginationPageButton'),
-  ...linkProps.types
+  tokens: getTokensPropType('PaginationPageButton')
 }
 
 export default PageButton

package/src/Pagination/Pagination.jsx

@@ -1,4 +1,4 @@
-import React from 'react'
+import React, { forwardRef } from 'react'
 import { View, Text, StyleSheet } from 'react-native'
 
 import { componentPropType, copyPropTypes, getTokensPropType, variantProp } from '../utils'
@@ -19,99 +19,95 @@ const selectTextStyles = ({ color, fontName, fontSize, fontWeight, lineHeight })
     lineHeight
   })
 
-function Pagination({
-  children,
-  copy = 'en',
-  variant,
-  tokens,
-  sideButtonVariant,
-  sideButtonTokens
-}) {
-  const viewport = useViewport()
-  const { truncateAbove, gap, ...themeTokens } = useThemeTokens('Pagination', tokens, variant, {
-    viewport
-  })
-
-  const items = React.Children.toArray(children)
-
-  const {
-    isItemActive,
-    getItemProps,
-    showPrevious,
-    showNext,
-    nextItemProps,
-    previousItemProps,
-    shouldRenderButton,
-    shouldRenderEllipsis
-  } = usePagination({
-    items,
-    truncateAbove
-  })
-
-  const ellipsisTextStyles = selectTextStyles(themeTokens)
-
-  if (items.length === 0) {
-    return null
-  }
-
-  // TODO: replace with a spacing component when https://github.com/telus/universal-design-system/pull/531 is implemented
-  // concatenate all items to easily wrap them in identical spacing components
-  const buttons = [
-    showPrevious && (
-      <SideButton
-        {...previousItemProps}
-        direction="previous"
-        copy={copy}
-        variant={sideButtonVariant}
-        tokens={sideButtonTokens}
-      />
-    ),
-    ...items.map((child, itemIndex) => {
-      const buttonLabel = `${itemIndex + 1}`
-      const itemProps = getItemProps(itemIndex)
-
-      if (shouldRenderButton(itemIndex)) {
-        return (
-          <PageButton
-            {...itemProps}
-            label={buttonLabel}
-            copy={copy}
-            isActive={isItemActive(itemIndex)}
-          />
-        )
-      }
-
-      if (shouldRenderEllipsis(itemIndex)) {
-        return <Text style={ellipsisTextStyles}>...</Text>
-      }
-
+const Pagination = forwardRef(
+  ({ children, copy = 'en', variant, tokens, sideButtonVariant, sideButtonTokens }, ref) => {
+    const viewport = useViewport()
+    const { truncateAbove, gap, ...themeTokens } = useThemeTokens('Pagination', tokens, variant, {
+      viewport
+    })
+
+    const items = React.Children.toArray(children)
+
+    const {
+      isItemActive,
+      getItemProps,
+      showPrevious,
+      showNext,
+      nextItemProps,
+      previousItemProps,
+      shouldRenderButton,
+      shouldRenderEllipsis
+    } = usePagination({
+      items,
+      truncateAbove
+    })
+
+    const ellipsisTextStyles = selectTextStyles(themeTokens)
+
+    if (items.length === 0) {
       return null
-    }),
-    showNext && (
-      <SideButton
-        {...nextItemProps}
-        direction="next"
-        copy={copy}
-        variant={sideButtonVariant}
-        tokens={sideButtonTokens}
-      />
+    }
+
+    // TODO: replace with a spacing component when https://github.com/telus/universal-design-system/pull/531 is implemented
+    // concatenate all items to easily wrap them in identical spacing components
+    const buttons = [
+      showPrevious && (
+        <SideButton
+          {...previousItemProps}
+          direction="previous"
+          copy={copy}
+          variant={sideButtonVariant}
+          tokens={sideButtonTokens}
+        />
+      ),
+      ...items.map((child, itemIndex) => {
+        const buttonLabel = `${itemIndex + 1}`
+        const itemProps = getItemProps(itemIndex)
+
+        if (shouldRenderButton(itemIndex)) {
+          return (
+            <PageButton
+              {...itemProps}
+              label={buttonLabel}
+              copy={copy}
+              isActive={isItemActive(itemIndex)}
+            />
+          )
+        }
+
+        if (shouldRenderEllipsis(itemIndex)) {
+          return <Text style={ellipsisTextStyles}>...</Text>
+        }
+
+        return null
+      }),
+      showNext && (
+        <SideButton
+          {...nextItemProps}
+          direction="next"
+          copy={copy}
+          variant={sideButtonVariant}
+          tokens={sideButtonTokens}
+        />
+      )
+    ]
+
+    return (
+      <View style={staticStyles.container} ref={ref}>
+        {buttons
+          // keep the keys in-line with the page numbers regardless of which buttons are actually rendered
+          .map((element, index) => [element, `page-${index + 1}`])
+          .filter(([element]) => element !== null)
+          .map(([element, key]) => (
+            <Box right={gap} key={key}>
+              {element}
+            </Box>
+          ))}
+      </View>
     )
-  ]
-
-  return (
-    <View style={staticStyles.container}>
-      {buttons
-        // keep the keys in-line with the page numbers regardless of which buttons are actually rendered
-        .map((element, index) => [element, `page-${index + 1}`])
-        .filter(([element]) => element !== null)
-        .map(([element, key]) => (
-          <Box right={gap} key={key}>
-            {element}
-          </Box>
-        ))}
-    </View>
-  )
-}
+  }
+)
+PageButton.displayName = 'PageButton'
 
 Pagination.PageButton = PageButton