@telus-uds/components-web 1.2.0 → 1.4.0

package/src/ExpandCollapseMini/ExpandCollapseMini.jsx

@@ -0,0 +1,48 @@
+import React, { forwardRef } from 'react'
+import PropTypes from 'prop-types'
+import { ExpandCollapse, useThemeTokens } from '@telus-uds/components-base'
+import ExpandCollapseMiniControl from './ExpandCollapseMiniControl'
+
+const ExpandCollapseMini = forwardRef(({ children, onToggle, tokens, ...rest }, ref) => {
+  const { variant } = rest
+  const { borderWidth } = useThemeTokens('ExpandCollapseMini', tokens, variant)
+
+  const handleChange = (openPanels, event) => {
+    if (typeof onToggle === 'function') {
+      const isOpen = openPanels.length > 0
+      onToggle(event, isOpen)
+    }
+  }
+
+  return (
+    <ExpandCollapse tokens={{ borderWidth }} onChange={handleChange}>
+      {(expandProps) => (
+        <ExpandCollapse.Panel
+          {...expandProps}
+          panelId="ExpandCollapseMiniPanel"
+          controlTokens={{ icon: null }}
+          // TODO refactor
+          // eslint-disable-next-line react/no-unstable-nested-components
+          control={(pressableState) => (
+            <ExpandCollapseMiniControl pressableState={pressableState} {...rest} />
+          )}
+          controlRef={ref}
+        >
+          {children}
+        </ExpandCollapse.Panel>
+      )}
+    </ExpandCollapse>
+  )
+})
+ExpandCollapseMini.displayName = 'ExpandCollapseMini'
+
+ExpandCollapseMini.propTypes = {
+  ...ExpandCollapseMiniControl.propTypes,
+  onToggle: PropTypes.func,
+  children: PropTypes.node.isRequired
+}
+ExpandCollapseMini.defaultProps = {
+  onToggle: () => {}
+}
+
+export default ExpandCollapseMini

package/src/ExpandCollapseMini/ExpandCollapseMiniControl.jsx

@@ -0,0 +1,67 @@
+import React from 'react'
+import PropTypes from 'prop-types'
+import { selectSystemProps, Link, useThemeTokens } from '@telus-uds/components-base'
+import { htmlAttrs } from '../utils'
+
+const [selectProps, selectedSystemPropTypes] = selectSystemProps([htmlAttrs])
+
+// The ExpandCollapseControl has all the appropriate role, a11y, press handling etc
+// and a more appropriate press area, defer interaction handling to it.
+const presentationOnly = {
+  accessibilityRole: null, // Treat as regular flow content with the Control
+  pointerEvents: 'none', // Stop RNW from stopping clicks from bubbling to Control
+  focusable: false // Stop RNW from setting tabIndex={0}: focus goes to Control only
+}
+
+const ExpandCollapseMiniControl = ({
+  pressableState,
+  collapseTitle,
+  expandTitle = collapseTitle,
+  iconPosition = 'right',
+  tokens,
+  variant = {},
+  ...rest
+}) => {
+  const { expanded, hover } = pressableState || {}
+
+  const { size, icon } = useThemeTokens('ExpandCollapseMiniControl', tokens, variant, { expanded })
+
+  // Choose hover styles when any part of Control is hoverred
+  const appearance = { ...variant, hover }
+
+  const getTokens = (linkState) => {
+    const { hover: linkHover } = linkState || {}
+    const isHovered = hover || linkHover
+    if (isHovered) {
+      // Include vertical icon animation on hover alongside built-in Link theme, the size is size4
+      return { iconTranslateY: (expanded ? -1 : 1) * size }
+    }
+
+    return {}
+  }
+
+  return (
+    <Link
+      variant={appearance}
+      icon={icon}
+      iconPosition={iconPosition}
+      tokens={(linkState) => ({ ...getTokens(linkState), outerBorderWidth: 0 })}
+      {...presentationOnly}
+      {...selectProps(rest)}
+    >
+      {expanded ? expandTitle : collapseTitle}
+    </Link>
+  )
+}
+
+ExpandCollapseMiniControl.propTypes = {
+  ...selectedSystemPropTypes,
+  ...Link.propTypes,
+  onPress: PropTypes.func,
+  expandTitle: PropTypes.string.isRequired,
+  collapseTitle: PropTypes.string.isRequired,
+  pressableState: PropTypes.object,
+  variant: PropTypes.object
+}
+
+export default ExpandCollapseMiniControl

package/src/ExpandCollapseMini/index.js

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

package/src/Footnote/Footnote.jsx

@@ -0,0 +1,468 @@
+import React, { useRef, useEffect, useState, useCallback } from 'react'
+import PropTypes from 'prop-types'
+import styled, { createGlobalStyle } from 'styled-components'
+import {
+  Icon,
+  Portal,
+  selectSystemProps,
+  Typography,
+  useCopy,
+  useTheme,
+  useResponsiveProp,
+  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'
+
+const [selectProps, selectedSystemPropTypes] = selectSystemProps([htmlAttrs])
+
+const GlobalBodyScrollLock = createGlobalStyle({
+  'html, body': media().until('md').css({ overflow: 'hidden' })
+})
+
+const StyledFootnote = styled.div(
+  ({ footnoteBackground, isVisible, footnoteBorderTop }) => ({
+    position: 'fixed',
+    overflowY: 'scroll',
+    top: 0,
+    left: 0,
+    height: '100vh',
+    width: '100vw',
+    backgroundColor: footnoteBackground,
+    display: 'block',
+    boxShadow: '0 0 16px 0 rgba(0, 0, 0, 0.1)',
+    transform: 'translateY(100%)',
+    transition: 'transform 500ms ease-out',
+    '@media() (prefers-reduced-motion: reduce)': {
+      transition: 'none'
+    },
+    zIndex: 99999,
+    visibility: isVisible ? 'visible' : 'hidden',
+    ...media().from('md').css({
+      top: 'auto',
+      bottom: 0,
+      height: 'auto',
+      maxHeight: '50vh',
+      borderTop: footnoteBorderTop
+    })
+  }),
+  ({ isOpen }) => {
+    if (isOpen) {
+      return {
+        transform: 'translateY(0)'
+      }
+    }
+    return {}
+  }
+)
+
+const StyledFootnoteHeader = styled.div({
+  position: 'relative',
+  width: '100%'
+})
+
+const StyledHeader = styled.div(({ headerMargin }) => ({
+  alignItems: 'center',
+  display: 'flex',
+  flexDirection: 'row',
+  justifyContent: 'space-between',
+  margin: headerMargin
+}))
+
+const StyledFootnoteBody = styled.div(
+  {
+    overflow: 'auto',
+    transition: 'height 300ms ease-out, opacity 200ms ease-out',
+    transform: 'translateZ(0)',
+    '@media() (prefers-reduced-motion: reduce)': {
+      transition: 'height 1ms ease-out, opacity 1ms ease-out'
+    }
+  },
+  ({ footnoteBodyBackground, footnoteBodyPadding }) => ({
+    backgroundColor: footnoteBodyBackground,
+    padding: footnoteBodyPadding
+  }),
+  ({ headerHeight }) => ({
+    maxHeight: `calc(100vh - ${headerHeight}px)`,
+    ...media()
+      .from('md')
+      .css({
+        maxHeight: `calc(50vh - ${headerHeight}px)`
+      })
+  }),
+  ({ bodyHeight, isTextVisible }) => ({
+    height: bodyHeight,
+    opacity: isTextVisible ? 1 : 0
+  })
+)
+
+const List = styled(OrderedListBase)(({ listPaddingLeft }) => ({
+  listStylePosition: 'outside',
+  paddingLeft: listPaddingLeft
+}))
+
+const ListItem = styled(OrderedListBase.Item)(
+  ({
+    listItemMarkerFontSize,
+    listItemMarkerLineHeight,
+    listItemColor,
+    listItemFontSize,
+    listItemLineHeight,
+    listItemPaddingLeft
+  }) => ({
+    display: 'list-item',
+    '&::marker': {
+      fontFamily: 'HelveticaNow400normal',
+      fontSize: listItemMarkerFontSize,
+      lineHeight: listItemMarkerLineHeight,
+      textAlign: 'end !important'
+    },
+    color: listItemColor,
+    fontFamily: 'HelveticaNow400normal',
+    fontSize: listItemFontSize,
+    lineHeight: listItemLineHeight,
+    paddingLeft: listItemPaddingLeft
+  })
+)
+
+const CloseButton = styled.button(
+  ({ closeButtonBorder, closeButtonHeight, closeButtonMargin, closeButtonWidth }) => ({
+    alignItems: 'center',
+    borderRadius: '50%',
+    cursor: 'pointer',
+    display: 'flex',
+    justifyContent: 'center',
+    border: closeButtonBorder,
+    height: closeButtonHeight,
+    margin: closeButtonMargin,
+    width: closeButtonWidth
+  })
+)
+
+const ContentContainer = styled.div(
+  {
+    'margin-left': 'auto',
+    'margin-right': 'auto',
+    left: 0,
+    right: 0
+  },
+  ({ maxWidth }) => ({
+    width: maxWidth
+  })
+)
+
+const usePrevious = (value) => {
+  const ref = useRef()
+  useEffect(() => {
+    ref.current = value
+  })
+  if (ref.current) {
+    return ref.current
+  }
+  return {}
+}
+
+/**
+ * Use `Footnote` to display a single legal content.
+ *
+ * ## Usage Criteria
+ *
+ * - Use `Footnote` to display a single legal statement
+ * - Display on top of all UI, including other sticky elements such as Cart Summary
+ * - Dismiss by clicking on the close button, clicking anywhere outside of the `Footnote`, or by pressing the ESC key
+ * - Responsive display based on breakpoints
+ * - Use copy to set language, ‘en’ for English or ‘fr’ for French
+ *
+ * ## Accessibility requirements
+ *
+ * - Only one instance of `Footnote` should display at a time
+ * - Place `Footnote` as the last element in the body or main
+ * - When `Footnote` is open, the inert prop must be set on all children of body excluding the Footnote
+ * - 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 {
+    footnoteBackground,
+    footnoteBorderTopSizeMd,
+    footnoteBorderColorMd,
+    headerMargin,
+    footnoteBodyBackground,
+    footnoteBodyPaddingLeft,
+    footnoteBodyPaddingRight,
+    footnoteBodyPaddingTop,
+    footnoteBodyPaddingBottom,
+    listPaddingLeft,
+    listItemMarkerFontSize,
+    listItemMarkerLineHeight,
+    listItemColor,
+    listItemFontSize,
+    listItemLineHeight,
+    listItemPaddingLeft,
+    closeButtonBorderSize,
+    closeButtonBorderColor,
+    closeButtonHeight,
+    closeButtonMarginTop,
+    closeButtonMarginLeft,
+    closeButtonMarginRight,
+    closeButtonMarginBottom,
+    closeButtonWidth,
+    closeButtonIconSize
+  } = useThemeTokens('Footnote', tokens, variant)
+
+  const footnoteRef = useRef(null)
+  const headerRef = useRef(null)
+  const bodyRef = useRef(null)
+  const listRef = useRef(null)
+  const headingRef = useRef(null)
+  const [data, setData] = useState({ content: null, number: null })
+  const [headerHeight, setHeaderHeight] = useState('auto')
+  const [bodyHeight, setBodyHeight] = useState('auto')
+  const [isVisible, setIsVisible] = useState(false)
+  const [isTextVisible, setIsTextVisible] = useState(true)
+  const getCopy = useCopy({ dictionary, copy })
+
+  const prevProps = usePrevious(props)
+  const theme = useTheme()
+  const maxWidth = useResponsiveProp(theme.themeOptions?.contentMaxWidth)
+
+  const closeFootnote = useCallback(
+    (event, options) => {
+      onClose(event, options)
+    },
+    [onClose]
+  )
+
+  // Listen for ESCAPE, close button clicks, and clicks outside of the Footnote. Call onClose.
+  const handleClose = useCallback(
+    (event) => {
+      if (event.type === 'keydown') {
+        if (event.key === 'Escape' || event.key === 27) {
+          closeFootnote(event, { returnFocus: true })
+        }
+      } else if (
+        (event.type === 'click' || event.type === 'mousedown') &&
+        footnoteRef?.current &&
+        event.target &&
+        !footnoteRef?.current?.contains(event.target) &&
+        event.target.getAttribute('data-tds-id') !== 'footnote-link'
+      ) {
+        closeFootnote(event, { returnFocus: false })
+      } else if (
+        event.type === 'touchstart' &&
+        footnoteRef?.current &&
+        event.touches[0].target &&
+        !footnoteRef?.current?.contains(event.touches[0].target) &&
+        event.touches[0].target.getAttribute('data-tds-id') !== 'footnote-link'
+      ) {
+        closeFootnote(event, { returnFocus: false })
+      }
+    },
+    [closeFootnote]
+  )
+
+  const saveCurrentHeight = () => {
+    const oldHeight = listRef.current.offsetHeight
+    setBodyHeight(oldHeight)
+  }
+
+  const focusHeading = () => {
+    if (Boolean(content) && isVisible && headingRef && headingRef.current !== null) {
+      headingRef.current.focus()
+    }
+  }
+
+  const handleStyledFootnoteTransitionEnd = (event) => {
+    if (event.propertyName === 'transform' && !isOpen) {
+      setIsVisible(false)
+    } else {
+      focusHeading()
+    }
+  }
+
+  const handleTransitionEnd = (event) => {
+    event.persist()
+    if (event.propertyName === 'opacity' && !isTextVisible) {
+      setData({ content, number })
+      if (bodyHeight !== listRef.current.offsetHeight) {
+        // Set new height
+        setBodyHeight(listRef.current.offsetHeight)
+      } else {
+        setIsTextVisible(true)
+      }
+    } else {
+      setBodyHeight(listRef.current.offsetHeight)
+    }
+
+    if (event.propertyName === 'height' && !isTextVisible) {
+      setIsTextVisible(true)
+    }
+  }
+
+  const resetFootnote = () => {
+    // Reset footnote state if closed
+    if (!isOpen) {
+      setBodyHeight('auto')
+      setIsTextVisible(true)
+    }
+  }
+
+  // Set height of header on mount
+  useEffect(() => {
+    setHeaderHeight(headerRef.current?.offsetHeight)
+  }, [])
+
+  const preventDefault = (event) => {
+    if (!bodyRef.current.contains(event.touches[0].target)) {
+      event.preventDefault()
+    }
+  }
+
+  // Add listeners for mouse clicks outside of Footnote and for ESCAPE key presses
+  useEffect(() => {
+    if (isOpen) {
+      setIsVisible(true)
+      document.addEventListener('mousedown', handleClose)
+      window.addEventListener('click', handleClose)
+      window.addEventListener('keydown', handleClose)
+      window.addEventListener('touchstart', handleClose)
+      window.addEventListener('touchmove', preventDefault, { passive: false })
+    }
+    return () => {
+      if (isOpen) {
+        document.addEventListener('mousedown', handleClose)
+        window.removeEventListener('click', handleClose)
+        window.removeEventListener('keydown', handleClose)
+        window.removeEventListener('touchstart', handleClose)
+        window.removeEventListener('touchmove', preventDefault)
+      }
+    }
+  }, [handleClose, isOpen])
+
+  // Set data if opening a new footnote
+  useEffect(() => {
+    if (isOpen && !prevProps.isOpen) {
+      setData({ content, number })
+    }
+  }, [isOpen, prevProps.isOpen, content, number])
+
+  useEffect(() => {
+    if (isOpen && prevProps.isOpen && number !== prevProps.number) {
+      saveCurrentHeight()
+      setIsTextVisible(false)
+    }
+  }, [number, isOpen, prevProps.isOpen, prevProps.number])
+
+  // Reset footnote on close
+  useEffect(resetFootnote, [isOpen])
+
+  return (
+    <Portal>
+      <div {...selectProps(rest)}>
+        {isOpen && <GlobalBodyScrollLock />}
+        <StyledFootnote
+          ref={footnoteRef}
+          isOpen={isOpen}
+          isVisible={isVisible}
+          onTransitionEnd={handleStyledFootnoteTransitionEnd}
+          tabIndex={0}
+          footnoteBackground={footnoteBackground}
+          footnoteBorderTop={`${footnoteBorderTopSizeMd}px solid ${footnoteBorderColorMd}`}
+        >
+          <ContentContainer maxWidth={maxWidth}>
+            <StyledFootnoteHeader ref={headerRef}>
+              <StyledHeader ref={headingRef} headerMargin={headerMargin}>
+                <Typography block heading tabIndex={-1} variant={{ size: 'h4' }}>
+                  {getCopy('heading')}
+                </Typography>
+                <CloseButton
+                  closeButtonBorder={`${closeButtonBorderSize}px solid ${closeButtonBorderColor}`}
+                  closeButtonWidth={`${closeButtonWidth}px`}
+                  closeButtonHeight={`${closeButtonHeight}px`}
+                  closeButtonMargin={`${closeButtonMarginTop}px ${closeButtonMarginRight}px ${closeButtonMarginBottom}px ${closeButtonMarginLeft}px`}
+                  onClick={(event) => {
+                    closeFootnote(event, { returnFocus: true })
+                  }}
+                  aria-label={getCopy('close')}
+                >
+                  <Icon icon={Close} tokens={{ size: `${closeButtonIconSize}px` }} />
+                </CloseButton>
+              </StyledHeader>
+            </StyledFootnoteHeader>
+            <StyledFootnoteBody
+              ref={bodyRef}
+              bodyHeight={bodyHeight}
+              headerHeight={headerHeight}
+              isTextVisible={isTextVisible}
+              onTransitionEnd={handleTransitionEnd}
+              maxWidth={theme.contentMaxWidth}
+              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>
+              )}
+            </StyledFootnoteBody>
+          </ContentContainer>
+        </StyledFootnote>
+      </div>
+    </Portal>
+  )
+}
+
+const copyShape = PropTypes.shape({
+  close: PropTypes.string.isRequired,
+  heading: PropTypes.string.isRequired
+})
+
+Footnote.propTypes = {
+  ...selectedSystemPropTypes,
+  /**
+   * The content.
+   */
+  content: PropTypes.string,
+  /**
+   * 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`.
+   */
+  copy: PropTypes.oneOfType([PropTypes.oneOf(['en', 'fr']), copyShape]),
+  /**
+   * A boolean flag used hide or show the `Footnote`. Set to `true` to open the `Footnote`.
+   */
+  isOpen: PropTypes.bool,
+  /**
+   * The number, must match the number of the `FootnoteLink` that initiated the `Footnote`.
+   */
+  number: PropTypes.number,
+  /**
+   * A callback function to handle the closing of the footnote.
+   *
+   * @param {SyntheticEvent} event The React `SyntheticEvent`
+   * @param {Object} options Custom options
+   * @param {boolean} options.returnFocus Should the `Footnote` return focus on close
+   */
+  onClose: PropTypes.func.isRequired
+}
+
+Footnote.defaultProps = {
+  isOpen: false,
+  number: undefined,
+  content: undefined,
+  copy: 'en'
+}
+
+export default Footnote

package/src/Footnote/FootnoteLink.jsx

@@ -0,0 +1,120 @@
+import React from 'react'
+import PropTypes from 'prop-types'
+import styled from 'styled-components'
+import { 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'
+}))
+
+/**
+ * Use `FootnoteLink` to open `Footnote` component and display related legal content.
+ *
+ * ## Usage Criteria
+ *
+ * - Use FootnoteLink to open a Footnote component and display related legal content.
+ * - Avoid using FootnoteLink if there is only one annotation on a page. Consider including
+ *   the annotation as part of the content whenever possible.
+ */
+const FootnoteLink = ({
+  copy = 'en',
+  number = [],
+  onClick,
+  fontSize,
+  tokens,
+  variant = {},
+  ...rest
+}) => {
+  const { lineHeight, paddingLeft, paddingRight } = useThemeTokens('FootnoteLink', tokens, variant)
+  const numbers = Array.isArray(number) ? number : [number]
+  const refs = numbers.map(() => React.createRef())
+  const handleClick = (index) => {
+    onClick(numbers[index], refs[index])
+  }
+  const getCopy = useCopy({ dictionary, copy })
+
+  const handleOnClick = (event, index) => {
+    event.preventDefault()
+    event.stopPropagation()
+    handleClick(index)
+  }
+
+  const handleOnKeyDown = (event, index) => {
+    if (event.key === 'Enter' || event.key === 13) {
+      handleClick(index)
+    }
+  }
+
+  return (
+    <>
+      {numbers.map((num, index) => (
+        <StyledSup
+          onKeyDown={(event) => handleOnKeyDown(event, index)}
+          role="button"
+          aria-label={getCopy('a11yLabel')}
+          key={num}
+          ref={refs[index]}
+          onClick={(event) => handleOnClick(event, index)}
+          fontSize={fontSize}
+          lineHeight={lineHeight}
+          paddingLeft={paddingLeft}
+          paddingRight={paddingRight}
+          {...selectProps(rest)}
+        >
+          {`${num}${index !== numbers.length - 1 ? ',' : ''}`}
+        </StyledSup>
+      ))}
+    </>
+  )
+}
+
+const copyShape = PropTypes.shape({
+  a11yLabel: PropTypes.string.isRequired
+})
+
+FootnoteLink.propTypes = {
+  ...selectedSystemPropTypes,
+  /**
+   * 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 key `a11yLabel`.
+   */
+  copy: PropTypes.oneOfType([PropTypes.oneOf(['en', 'fr']), copyShape]),
+  /**
+   * The footnote number, or multiple numbers if passed as an array.
+   * If using an array, a comma-separated group of numbers will be rendered as superscript.
+   */
+  number: PropTypes.oneOfType([
+    PropTypes.number,
+    PropTypes.arrayOf(PropTypes.number),
+    PropTypes.string,
+    PropTypes.arrayOf(PropTypes.string)
+  ]).isRequired,
+  /**
+   * A callback function to handle the click of a FootnoteLink.
+   */
+  onClick: PropTypes.func.isRequired,
+  /**
+   * Override default `fontSize` to set specific font size value
+   */
+  fontSize: PropTypes.oneOfType([PropTypes.number, PropTypes.string])
+}
+
+FootnoteLink.defaultProps = {
+  copy: 'en',
+  fontSize: 'smaller'
+}
+
+export default FootnoteLink