@telus-uds/components-web 1.9.0 → 1.11.0

package/src/Disclaimer/Disclaimer.jsx

@@ -0,0 +1,39 @@
+import React from 'react'
+import PropTypes from 'prop-types'
+import styled from 'styled-components'
+import { applyTextStyles, selectSystemProps, useThemeTokens } from '@telus-uds/components-base'
+import { htmlAttrs } from '../utils'
+
+const [selectProps, selectedSystemPropTypes] = selectSystemProps([htmlAttrs])
+
+const StyledDisclaimer = styled.p(({ fontName, fontWeight, fontSize, ...tokens }) => {
+  const { fontFamily } = applyTextStyles({ fontName, fontWeight })
+  return {
+    fontSize: `${fontSize}px`,
+    fontFamily,
+    ...tokens
+  }
+})
+
+/**
+ * Use Disclaimer to display singular legal statement and must be displayed
+ * immediately adjacent to the related, originating content.
+ */
+const Disclaimer = ({ children, ...rest }) => {
+  const themeTokens = useThemeTokens('Disclaimer')
+  return (
+    <StyledDisclaimer {...selectProps(rest)} {...themeTokens}>
+      {children}
+    </StyledDisclaimer>
+  )
+}
+
+Disclaimer.propTypes = {
+  ...selectedSystemPropTypes,
+  /**
+   * The content
+   */
+  children: PropTypes.node.isRequired
+}
+
+export default Disclaimer

package/src/Disclaimer/index.js

@@ -0,0 +1 @@
+export { default } from './Disclaimer'

package/src/Footnote/Footnote.jsx

@@ -12,10 +12,9 @@ import {
   useThemeTokens
 } from '@telus-uds/components-base'
 
-import Close from '../../__fixtures__/icons/Close'
 import OrderedListBase from '../OrderedList/OrderedListBase'
 import { htmlAttrs, media, renderStructuredContent } from '../utils'
-import dictionary from './dictionary'
+import defaultDictionary from './dictionary'
 
 const [selectProps, selectedSystemPropTypes] = selectSystemProps([htmlAttrs])
 
@@ -154,6 +153,10 @@ const ContentContainer = styled.div(
   })
 )
 
+const StyledCustomContentContainer = styled.div(({ color }) => ({
+  color,
+  fontFamily: 'HelveticaNow400normal'
+}))
 const usePrevious = (value) => {
   const ref = useRef()
   useEffect(() => {
@@ -184,7 +187,17 @@ const usePrevious = (value) => {
  * - When `Footnote` is closed, focus must return to the initiating element
  */
 const Footnote = (props) => {
-  const { copy, number, content, onClose, isOpen, tokens, variant = {}, ...rest } = props
+  const {
+    copy,
+    number,
+    content,
+    onClose,
+    isOpen,
+    tokens,
+    variant = {},
+    dictionary = defaultDictionary,
+    ...rest
+  } = props
   const {
     footnoteBackground,
     footnoteBorderTopSizeMd,
@@ -210,13 +223,14 @@ const Footnote = (props) => {
     closeButtonMarginRight,
     closeButtonMarginBottom,
     closeButtonWidth,
-    closeButtonIconSize
+    closeButtonIconSize,
+    closeIcon
   } = useThemeTokens('Footnote', tokens, variant)
 
   const footnoteRef = useRef(null)
   const headerRef = useRef(null)
   const bodyRef = useRef(null)
-  const listRef = useRef(null)
+  const contentRef = useRef(null)
   const headingRef = useRef(null)
   const [data, setData] = useState({ content: null, number: null })
   const [headerHeight, setHeaderHeight] = useState('auto')
@@ -265,7 +279,7 @@ const Footnote = (props) => {
   )
 
   const saveCurrentHeight = () => {
-    const oldHeight = listRef.current.offsetHeight
+    const oldHeight = contentRef.current.offsetHeight
     setBodyHeight(oldHeight)
   }
 
@@ -287,14 +301,14 @@ const Footnote = (props) => {
     event.persist()
     if (event.propertyName === 'opacity' && !isTextVisible) {
       setData({ content, number })
-      if (bodyHeight !== listRef.current.offsetHeight) {
+      if (bodyHeight !== contentRef.current.offsetHeight) {
         // Set new height
-        setBodyHeight(listRef.current.offsetHeight)
+        setBodyHeight(contentRef.current.offsetHeight)
       } else {
         setIsTextVisible(true)
       }
     } else {
-      setBodyHeight(listRef.current.offsetHeight)
+      setBodyHeight(contentRef.current.offsetHeight)
     }
 
     if (event.propertyName === 'height' && !isTextVisible) {
@@ -359,6 +373,41 @@ const Footnote = (props) => {
   // Reset footnote on close
   useEffect(resetFootnote, [isOpen])
 
+  const getFootnoteBodyContent = useCallback(() => {
+    if (!data.number || !data.content) {
+      return null
+    }
+    if (React.isValidElement(data.content)) {
+      return (
+        <StyledCustomContentContainer ref={contentRef}>{data.content}</StyledCustomContentContainer>
+      )
+    }
+    return (
+      <List start={data.number} ref={contentRef} listPaddingLeft={listPaddingLeft}>
+        <ListItem
+          listItemMarkerFontSize={listItemMarkerFontSize}
+          listItemMarkerLineHeight={listItemMarkerLineHeight}
+          listItemColor={listItemColor}
+          listItemFontSize={listItemFontSize}
+          listItemLineHeight={listItemLineHeight}
+          listItemPaddingLeft={listItemPaddingLeft}
+        >
+          <Typography>{renderStructuredContent(data.content)}</Typography>
+        </ListItem>
+      </List>
+    )
+  }, [
+    data.content,
+    data.number,
+    listItemColor,
+    listItemFontSize,
+    listItemLineHeight,
+    listItemMarkerFontSize,
+    listItemMarkerLineHeight,
+    listItemPaddingLeft,
+    listPaddingLeft
+  ])
+
   return (
     <Portal>
       <div {...selectProps(rest)}>
@@ -388,7 +437,7 @@ const Footnote = (props) => {
                   }}
                   aria-label={getCopy('close')}
                 >
-                  <Icon icon={Close} tokens={{ size: `${closeButtonIconSize}px` }} />
+                  <Icon icon={closeIcon} tokens={{ size: `${closeButtonIconSize}px` }} />
                 </CloseButton>
               </StyledHeader>
             </StyledFootnoteHeader>
@@ -402,20 +451,7 @@ const Footnote = (props) => {
               footnoteBodyBackground={footnoteBodyBackground}
               footnoteBodyPadding={`${footnoteBodyPaddingTop}px ${footnoteBodyPaddingRight}px ${footnoteBodyPaddingBottom}px ${footnoteBodyPaddingLeft}px`}
             >
-              {data.number && data.content && (
-                <List start={data.number} ref={listRef} listPaddingLeft={listPaddingLeft}>
-                  <ListItem
-                    listItemMarkerFontSize={listItemMarkerFontSize}
-                    listItemMarkerLineHeight={listItemMarkerLineHeight}
-                    listItemColor={listItemColor}
-                    listItemFontSize={listItemFontSize}
-                    listItemLineHeight={listItemLineHeight}
-                    listItemPaddingLeft={listItemPaddingLeft}
-                  >
-                    <Typography>{renderStructuredContent(data.content)}</Typography>
-                  </ListItem>
-                </List>
-              )}
+              {getFootnoteBodyContent()}
             </StyledFootnoteBody>
           </ContentContainer>
         </StyledFootnote>
@@ -429,12 +465,19 @@ const copyShape = PropTypes.shape({
   heading: PropTypes.string.isRequired
 })
 
+// If a language dictionary entry is provided, it must contain every key
+const dictionaryContentShape = PropTypes.shape({
+  a11yLabel: PropTypes.string.isRequired,
+  close: PropTypes.string.isRequired,
+  heading: PropTypes.string.isRequired
+})
+
 Footnote.propTypes = {
   ...selectedSystemPropTypes,
   /**
    * The content.
    */
-  content: PropTypes.string,
+  content: PropTypes.oneOfType([PropTypes.string, PropTypes.element]),
   /**
    * Use the `copy` prop to either select provided English or French copy by passing 'en' or 'fr' respectively.
    * To provide your own, pass a JSON object with the keys `heading` and `close`.
@@ -455,7 +498,14 @@ Footnote.propTypes = {
    * @param {Object} options Custom options
    * @param {boolean} options.returnFocus Should the `Footnote` return focus on close
    */
-  onClose: PropTypes.func.isRequired
+  onClose: PropTypes.func.isRequired,
+  /**
+   * Override the default dictionary, by passing the complete dictionary object for `en` and `fr`
+   */
+  dictionary: PropTypes.shape({
+    en: dictionaryContentShape,
+    fr: dictionaryContentShape
+  })
 }
 
 Footnote.defaultProps = {

package/src/Footnote/FootnoteLink.jsx

@@ -1,24 +1,36 @@
 import React from 'react'
 import PropTypes from 'prop-types'
 import styled from 'styled-components'
-import { selectSystemProps, useCopy, useThemeTokens } from '@telus-uds/components-base'
+import {
+  applyTextStyles,
+  selectSystemProps,
+  useCopy,
+  useThemeTokens
+} from '@telus-uds/components-base'
 import dictionary from './dictionary'
 import { htmlAttrs } from '../utils'
 
 const [selectProps, selectedSystemPropTypes] = selectSystemProps([htmlAttrs])
 
-const StyledSup = styled.sup(({ fontSize = 'smaller', lineHeight, paddingLeft, paddingRight }) => ({
-  border: 0,
-  color: 'inherit',
-  cursor: 'pointer',
-  fontSize,
-  lineHeight,
-  margin: 0,
-  paddingVertical: 0,
-  paddingLeft,
-  paddingRight,
-  textDecoration: 'underline'
-}))
+const StyledSup = styled.sup(
+  ({ fontSize, lineHeight, paddingLeft, paddingRight, ...fontNameAndWeight }) => {
+    return {
+      border: 0,
+      color: 'inherit',
+      cursor: 'pointer',
+      // we want to fallback on 'smaller' but have a valid size when a custom font size is provided.
+      fontSize: fontSize ? `${fontSize}px` : 'smaller',
+      lineHeight,
+      margin: 0,
+      paddingVertical: 0,
+      paddingLeft,
+      paddingRight,
+      textDecoration: 'underline',
+      // apply font family
+      ...applyTextStyles(fontNameAndWeight)
+    }
+  }
+)
 
 /**
  * Use `FootnoteLink` to open `Footnote` component and display related legal content.
@@ -38,7 +50,7 @@ const FootnoteLink = ({
   variant = {},
   ...rest
 }) => {
-  const { lineHeight, paddingLeft, paddingRight } = useThemeTokens('FootnoteLink', tokens, variant)
+  const themeTokens = useThemeTokens('FootnoteLink', tokens, variant)
   const numbers = Array.isArray(number) ? number : [number]
   const refs = numbers.map(() => React.createRef())
   const handleClick = (index) => {
@@ -68,11 +80,9 @@ const FootnoteLink = ({
           key={num}
           ref={refs[index]}
           onClick={(event) => handleOnClick(event, index)}
-          fontSize={fontSize}
-          lineHeight={lineHeight}
-          paddingLeft={paddingLeft}
-          paddingRight={paddingRight}
           {...selectProps(rest)}
+          {...themeTokens}
+          fontSize={fontSize}
         >
           {`${num}${index !== numbers.length - 1 ? ',' : ''}`}
         </StyledSup>

package/src/NavigationBar/NavigationBar.jsx

@@ -0,0 +1,217 @@
+import React, { forwardRef, useEffect, useRef, useState } from 'react'
+import PropTypes from 'prop-types'
+import {
+  selectSystemProps,
+  StackView,
+  Typography,
+  useResponsiveProp,
+  withLinkRouter
+} from '@telus-uds/components-base'
+import styled from 'styled-components'
+import { htmlAttrs } from '../utils'
+import NavigationItem from './NavigationItem'
+import NavigationSubMenu from './NavigationSubMenu'
+import collapseItems from './collapseItems'
+
+const [selectProps, selectedSystemPropTypes] = selectSystemProps([htmlAttrs])
+
+const Heading = styled.div({
+  alignItems: 'center',
+  display: 'flex',
+  flex: 1,
+  justifyContent: 'flex-start',
+  '> *': { display: 'contents', letterSpacing: 0 }
+})
+
+/**
+ * NavigationBar can be used to allow customers to consistently navigate across
+ * key pages within a specific product line
+ */
+const NavigationBar = forwardRef(
+  (
+    {
+      accessibilityRole = 'navigation',
+      heading,
+      headingLevel = 'h1',
+      items,
+      onChange = () => {},
+      selectedId,
+      LinkRouter,
+      linkRouterProps,
+      ...rest
+    },
+    ref
+  ) => {
+    const direction = useResponsiveProp({ xs: 'column', sm: 'row' })
+    const itemsForViewport = useResponsiveProp({ xs: collapseItems(items, selectedId), lg: items })
+    const openOverlayRef = useRef(null)
+    const [openSubMenuId, setOpenSubMenuId] = useState(null)
+    const handleSubMenuClose = (event) => {
+      if (event.type === 'keydown') {
+        if (event.key === 'Escape' || event.key === 27) {
+          setOpenSubMenuId(null)
+        }
+      } else if (
+        event.type === 'click' &&
+        openOverlayRef?.current &&
+        event.target &&
+        !openOverlayRef?.current?.contains(event.target)
+      ) {
+        setOpenSubMenuId(null)
+      } else if (
+        event.type === 'touchstart' &&
+        openOverlayRef?.current &&
+        event.touches[0].target &&
+        !openOverlayRef?.current?.contains(event.touches[0].target)
+      ) {
+        setOpenSubMenuId(null)
+      }
+    }
+
+    // Add listeners for mouse clicks outside and for ESCAPE key presses
+    // TODO: create a custom hook for that and use here and in the Footnote
+    useEffect(() => {
+      if (openSubMenuId !== null) {
+        window.addEventListener('click', handleSubMenuClose)
+        window.addEventListener('keydown', handleSubMenuClose)
+        window.addEventListener('touchstart', handleSubMenuClose)
+      }
+      return () => {
+        if (openSubMenuId !== null) {
+          window.removeEventListener('click', handleSubMenuClose)
+          window.removeEventListener('keydown', handleSubMenuClose)
+          window.removeEventListener('touchstart', handleSubMenuClose)
+        }
+      }
+    }, [openSubMenuId])
+
+    return (
+      <StackView
+        accessibilityRole={accessibilityRole}
+        direction={direction}
+        ref={ref}
+        space={2}
+        tokens={{
+          alignItems: direction === 'column' ? 'flex-start' : 'center',
+          justifyContent: 'flex-end'
+        }}
+        {...selectProps(rest)}
+      >
+        {heading && (
+          <Heading>
+            <Typography variant={{ size: 'h5' }} heading={headingLevel}>
+              {heading}
+            </Typography>
+          </Heading>
+        )}
+        {itemsForViewport?.map(
+          (
+            {
+              href,
+              label,
+              id,
+              onClick,
+              ref: itemRef,
+              LinkRouter: ItemLinkRouter = LinkRouter,
+              linkRouterProps: itemLinkRouterProps,
+              items: nestedItems,
+              ...itemRest
+            },
+            index
+          ) => {
+            const itemId = id ?? label
+            const handleClick = (event) => {
+              if (nestedItems) {
+                setOpenSubMenuId(openSubMenuId !== itemId ? itemId : null)
+              }
+              onClick?.(event)
+              onChange?.(itemId, event)
+            }
+
+            const ItemComponent = nestedItems ? NavigationSubMenu : NavigationItem
+            const isOpen = itemId === openSubMenuId
+
+            return (
+              <ItemComponent
+                ref={itemRef}
+                key={itemId}
+                href={href}
+                onClick={handleClick}
+                // TODO: refactor to pass selected ID via context
+                selectedId={selectedId}
+                index={index}
+                LinkRouter={ItemLinkRouter}
+                linkRouterProps={{ ...linkRouterProps, ...itemLinkRouterProps }}
+                items={nestedItems}
+                selected={itemId === selectedId}
+                {...itemRest}
+                {...(nestedItems && { isOpen })}
+                {...(nestedItems && isOpen && { openOverlayRef })}
+              >
+                {label}
+              </ItemComponent>
+            )
+          }
+        )}
+      </StackView>
+    )
+  }
+)
+
+NavigationBar.displayName = 'NavigationBar'
+
+NavigationBar.propTypes = {
+  ...selectedSystemPropTypes,
+  ...withLinkRouter.propTypes,
+  /**
+   * NavigationBar pages
+   *
+   * Each `item` object must contain:
+   *  - `heading` - user-facing text in the tab link
+   *  - `href` - the URL of the page linked to. Do not use hash links, for content within a page, use `Tabs`.
+   *  - `id` - a stable, unique identifier of the page within the set. Not written into the HTML.
+   */
+  items: PropTypes.arrayOf(
+    PropTypes.shape({
+      label: PropTypes.string.isRequired,
+      href: PropTypes.string,
+      id: PropTypes.string.isRequired,
+      onClick: PropTypes.func,
+      selected: PropTypes.bool,
+      LinkRouter: withLinkRouter.propTypes?.LinkRouter,
+      linkRouterProps: withLinkRouter.propTypes?.linkRouterProps,
+      // One layer of nested links is allowed
+      items: PropTypes.arrayOf(
+        PropTypes.shape({
+          label: PropTypes.string.isRequired,
+          href: PropTypes.string,
+          id: PropTypes.string.isRequired,
+          onClick: PropTypes.func,
+          selected: PropTypes.bool,
+          LinkRouter: withLinkRouter.propTypes?.LinkRouter,
+          linkRouterProps: withLinkRouter.propTypes?.linkRouterProps
+        })
+      )
+    })
+  ).isRequired,
+  /**
+   * Common navigation bar heading.
+   */
+  heading: PropTypes.string,
+  headingLevel: PropTypes.oneOf(['h1', 'h2', 'h3', 'h4', 'h5', 'h6']),
+  /**
+   * Matches the `id` property of the item in `items` corresponding to the current page
+   */
+  selectedId: PropTypes.string.isRequired,
+  /**
+   * Optional function to be called on pressing a link
+   */
+  onChange: PropTypes.func
+}
+NavigationBar.defaultProps = {
+  heading: undefined,
+  headingLevel: 'h1',
+  onChange: () => {}
+}
+
+export default NavigationBar

package/src/NavigationBar/NavigationItem.jsx

@@ -0,0 +1,83 @@
+import React, { forwardRef } from 'react'
+import PropTypes from 'prop-types'
+import {
+  Button,
+  selectSystemProps,
+  useResponsiveProp,
+  useViewport,
+  withLinkRouter,
+  useThemeTokensCallback
+} from '@telus-uds/components-base'
+import styled from 'styled-components'
+import { htmlAttrs } from '../utils'
+
+const [selectProps, selectedSystemPropTypes] = selectSystemProps([htmlAttrs])
+
+const defaultMaxWidth = 192
+
+const ItemContainer = styled.div(({ targetWidth }) => ({
+  display: 'flex',
+  flexDirection: 'column',
+  justifyContent: 'center',
+  maxWidth: `${Math.max(defaultMaxWidth, targetWidth ?? 0)}px`,
+  flexGrow: targetWidth ? 1 : 0,
+  flexShrink: 1
+}))
+
+/**
+ * NavigationItem within a NavigationBar component.
+ *
+ * This is rendered automatically by `NavigationBar` and isn't intended be used directly.
+ */
+const NavigationItem = forwardRef(
+  (
+    {
+      accessibilityRole = 'link', // @todo switch to 'button' for dropdowns
+      children,
+      id,
+      onClick: handleClick = () => {},
+      selected,
+      accessibilityState = { current: selected ? 'page' : false },
+      href,
+      tokens,
+      variant = {},
+      ...rest
+    },
+    ref
+  ) => {
+    const selectedProps = selectProps(rest)
+    const targetWidth = useResponsiveProp({ xs: 288, lg: null })
+    const viewport = useViewport()
+    const getTokens = useThemeTokensCallback('NavigationBar', tokens, variant)
+    const getStateTokens = (state) => getTokens({ ...state, viewport })
+
+    return (
+      <ItemContainer targetWidth={targetWidth}>
+        <Button
+          accessibilityRole={accessibilityRole}
+          accessibilityState={accessibilityState}
+          onPress={handleClick}
+          ref={ref}
+          tokens={getStateTokens}
+          variant={{ selected }}
+          href={href}
+          {...selectedProps}
+        >
+          {children}
+        </Button>
+      </ItemContainer>
+    )
+  }
+)
+NavigationItem.displayName = 'NavigationItem'
+
+NavigationItem.propTypes = {
+  ...selectedSystemPropTypes,
+  ...withLinkRouter.propTypes,
+  onClick: PropTypes.func,
+  selected: PropTypes.bool,
+  children: PropTypes.oneOfType([PropTypes.string, PropTypes.func]).isRequired
+}
+NavigationItem.defaultProps = { onClick: () => {}, selected: false }
+
+export default withLinkRouter(NavigationItem)