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

package/src/Modal/Modal.jsx

@@ -0,0 +1,185 @@
+import React 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 = ({ children, isOpen, onClose, maxWidth, tokens, variant, copy }) => {
+  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 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.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

package/src/Notification/Notification.jsx

@@ -0,0 +1,161 @@
+import React, { useState } from 'react'
+import { StyleSheet, Text, View } from 'react-native'
+
+import PropTypes from 'prop-types'
+import { applyTextStyles, useThemeTokens } from '../ThemeProvider'
+import { getTokensPropType, selectTokens, variantProp } from '../utils'
+import ButtonBase from '../Button/ButtonBase'
+import useCopy from '../utils/useCopy'
+import dictionary from './dictionary'
+
+const selectContainerStyles = (tokens) => ({ ...tokens })
+
+const selectTextStyles = (tokens) => applyTextStyles(selectTokens('Typography', tokens))
+
+const selectIconProps = ({ iconSize, iconColor }) => ({
+  size: iconSize,
+  color: iconColor
+})
+
+const selectIconContainerStyles = ({ iconGap }) => ({
+  paddingRight: iconGap
+})
+
+const selectDismissIconProps = ({ dismissIconSize, dismissIconColor }) => ({
+  size: dismissIconSize,
+  color: dismissIconColor
+})
+
+const selectDismissButtonContainerStyles = ({ dismissButtonGap }) => ({
+  paddingLeft: dismissButtonGap
+})
+
+/**
+ * A banner that highlights important messages:
+ * - Status message to show there is an error or outage of services
+ * - Confirmation message in response to user action
+ * - Account information letting the user know they have almost used all their data
+ *
+ * ## Usage criteria
+ * - Use simple text content only, such as bold test or links. Don’t use other complex components or paragraphs
+ * - Show notifications before the content that the message is related to, otherwise show at the top of the main content
+ * - 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
+ *
+ * ### Variants
+ * - Use `variant.style` to set the visual style of the notification
+ * - Use `dismissible` prop to enable dismissible functionality
+ * - Use `system` prop to set the visual style of the notification and denote an announcement from the system or application
+ *
+ * ### When to use the system prop?
+ * - Use `system` to show system-based messages coming from the application
+ * - Don’t use `system` when the message is in response to user action
+ *
+ * ## Variants
+ *
+ * #### Success
+ * Use the success variant to provide feedback of a successful operation. The message will include an icon to indicate meaning and importance.
+ *
+ * #### Warning
+ * Use the warning variant to provide feedback of a warning; users would still be able to proceed forward.
+ * The message will include an icon to indicate meaning and importance.
+ *
+ * #### Error
+ * Use the error variant to provide feedback of a failed operation. The message will include an icon to indicate meaning and importance.
+ *
+ * #### Dismissible
+ * Dismissible notifications should only be used for default or success notifications where there is no action needed from the user.
+ * If the information is passive then it should be dismissible as indicated by an interactive close button on the far right.
+ * If the notification requires an action then make the option(s) clear with a `ChevronLink` or `Link`.
+ *
+ * Use the `dismissible` prop to allow users to dismiss the Notification at any time. Once dismissed, the Notification is removed from the DOM.
+ *
+ * Please note:
+ *
+ * - Default and Success variants are dismissible
+ * - Error and Warning variants are not dismissible
+ *
+ * #### System message
+ * 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)} />
+        </View>
+      )}
+      <View style={staticStyles.contentContainer}>
+        {content && typeof content === 'function' ? content({ textStyles, variant }) : content}
+      </View>
+      {dismissible && DismissIconComponent && (
+        <View style={selectDismissButtonContainerStyles(themeTokens)}>
+          <ButtonBase
+            onPress={onDismissPress}
+            accessibilityRole="button"
+            accessibilityLabel={getCopy('dismiss')}
+          >
+            {() => <DismissIconComponent {...selectDismissIconProps(themeTokens)} />}
+          </ButtonBase>
+        </View>
+      )}
+    </View>
+  )
+}
+
+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 })
+  ]),
+  tokens: getTokensPropType('Notification'),
+  variant: variantProp.propType
+}
+
+export default Notification
+
+const staticStyles = StyleSheet.create({
+  container: {
+    flexDirection: 'row'
+  },
+  contentContainer: {
+    flex: 1
+  }
+})

package/src/Notification/dictionary.js

@@ -0,0 +1,8 @@
+export default {
+  en: {
+    dismiss: 'Close'
+  },
+  fr: {
+    dismiss: 'Fermer'
+  }
+}

package/src/Notification/index.js

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

package/src/Pagination/PageButton.jsx

@@ -0,0 +1,70 @@
+import React from 'react'
+import PropTypes from 'prop-types'
+
+import ButtonBase from '../Button/ButtonBase'
+import { useThemeTokensCallback } from '../ThemeProvider'
+import {
+  a11yProps,
+  copyPropTypes,
+  getTokensPropType,
+  hrefAttrsProp,
+  selectTokens,
+  variantProp
+} from '../utils'
+
+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 getCopy = useCopy({ dictionary, copy })
+
+  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 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
+  }
+
+  return (
+    <ButtonBase {...buttonProps} tokens={getButtonTokens} {...activeProps}>
+      {label}
+    </ButtonBase>
+  )
+}
+
+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')
+}
+
+export default PageButton

package/src/Pagination/Pagination.jsx

@@ -0,0 +1,135 @@
+import React from 'react'
+import { View, Text, StyleSheet } from 'react-native'
+
+import { componentPropType, copyPropTypes, getTokensPropType, variantProp } from '../utils'
+import { applyTextStyles, useThemeTokens } from '../ThemeProvider'
+import { useViewport } from '../ViewportProvider'
+import Box from '../Box'
+
+import usePagination from './usePagination'
+import PageButton from './PageButton'
+import SideButton from './SideButton'
+
+const selectTextStyles = ({ color, fontName, fontSize, fontWeight, lineHeight }) =>
+  applyTextStyles({
+    color,
+    fontName,
+    fontSize,
+    fontWeight,
+    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>
+      }
+
+      return null
+    }),
+    showNext && (
+      <SideButton
+        {...nextItemProps}
+        direction="next"
+        copy={copy}
+        variant={sideButtonVariant}
+        tokens={sideButtonTokens}
+      />
+    )
+  ]
+
+  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>
+  )
+}
+
+Pagination.PageButton = PageButton
+
+Pagination.propTypes = {
+  children: componentPropType('PageButton'),
+  copy: copyPropTypes,
+  variant: variantProp.propType,
+  tokens: getTokensPropType('Pagination'),
+  sideButtonVariant: variantProp.propType,
+  sideButtonTokens: getTokensPropType('PaginationSideButton')
+}
+
+const staticStyles = StyleSheet.create({
+  container: {
+    flexDirection: 'row',
+    flexWrap: 'wrap',
+    alignItems: 'center'
+  }
+})
+
+export default Pagination

package/src/Pagination/SideButton.jsx

@@ -0,0 +1,82 @@
+import React from 'react'
+import { Text } from 'react-native'
+
+import PropTypes from 'prop-types'
+
+import ButtonBase from '../Button/ButtonBase'
+import { IconText } from '../Icon'
+import { useThemeTokensCallback } from '../ThemeProvider'
+import { useViewport } from '../ViewportProvider'
+import { copyPropTypes, hrefAttrsProp, linkProps, selectTokens } from '../utils'
+
+import dictionary from './dictionary'
+import useCopy from '../utils/useCopy'
+
+const selectIconTokens = ({ color, iconSize, iconDisplace }, direction) => {
+  return {
+    color,
+    size: iconSize,
+    translateX: iconDisplace * (direction === 'previous' ? -1 : 1)
+  }
+}
+
+const directionToSide = {
+  previous: 'left',
+  next: 'right'
+}
+
+function SideButton({ direction = 'previous', onPress, href, copy, variant, tokens, ...props }) {
+  const viewport = useViewport()
+  const buttonVariant = { direction, viewport, ...variant }
+  const getTokens = useThemeTokensCallback('PaginationSideButton', tokens, buttonVariant)
+
+  const getCopy = useCopy({ dictionary, copy })
+
+  const { icon } = getTokens(tokens, buttonVariant)
+
+  const getButtonTokens = (buttonState) => selectTokens('Button', getTokens(buttonState))
+  const getIconTokens = (buttonState) => selectIconTokens(getTokens(buttonState), direction)
+
+  const label = direction === 'previous' ? getCopy('previousText') : getCopy('nextText')
+  const showLabel = viewport !== 'sm' && viewport !== 'xs'
+
+  const accessibilityLabel =
+    direction === 'previous' ? getCopy('previousLabel') : getCopy('nextLabel')
+  const accessibilityRole = href !== undefined ? 'link' : 'button'
+
+  const { hrefAttrs, rest } = hrefAttrsProp.bundle(props)
+  const buttonProps = {
+    accessibilityRole,
+    accessibilityLabel,
+    onPress,
+    href,
+    hrefAttrs,
+    ...rest
+  }
+
+  return (
+    <ButtonBase {...buttonProps} tokens={getButtonTokens}>
+      {({ textStyles, ...buttonState }) => {
+        const iconProps = { tokens: getIconTokens(buttonState) }
+        return (
+          <IconText
+            icon={icon}
+            space={1}
+            iconPosition={directionToSide[direction]}
+            iconProps={iconProps}
+          >
+            {showLabel && <Text style={textStyles}>{label}</Text>}
+          </IconText>
+        )
+      }}
+    </ButtonBase>
+  )
+}
+
+SideButton.propTypes = {
+  direction: PropTypes.oneOf(['previous', 'next']),
+  copy: copyPropTypes,
+  ...linkProps.types
+}
+
+export default SideButton

package/src/Pagination/dictionary.js

@@ -0,0 +1,18 @@
+export default {
+  en: {
+    goToLabel: 'Go to page number',
+    currentLabel: '(current)',
+    previousLabel: 'Go to previous page',
+    previousText: 'Previous',
+    nextLabel: 'Go to next page',
+    nextText: 'Next'
+  },
+  fr: {
+    goToLabel: 'Aller au page n°',
+    currentLabel: '(page actuelle)',
+    previousLabel: 'Aller au page précédent',
+    previousText: 'Précédent',
+    nextLabel: 'Aller au prochain page',
+    nextText: 'Suivant'
+  }
+}

package/src/Pagination/index.js

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