@telus-uds/components-web 1.2.0 → 1.4.0

package/lib-module/Footnote/Footnote.js

@@ -0,0 +1,541 @@
+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';
+import { jsx as _jsx } from "react/jsx-runtime";
+import { jsxs as _jsxs } from "react/jsx-runtime";
+const [selectProps, selectedSystemPropTypes] = selectSystemProps([htmlAttrs]);
+const GlobalBodyScrollLock = /*#__PURE__*/createGlobalStyle({
+  'html, body': media().until('md').css({
+    overflow: 'hidden'
+  })
+});
+const StyledFootnote = /*#__PURE__*/styled.div.withConfig({
+  displayName: "Footnote__StyledFootnote",
+  componentId: "components-web__sc-1563bo5-0"
+})(_ref => {
+  let {
+    footnoteBackground,
+    isVisible,
+    footnoteBorderTop
+  } = _ref;
+  return {
+    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
+    })
+  };
+}, _ref2 => {
+  let {
+    isOpen
+  } = _ref2;
+
+  if (isOpen) {
+    return {
+      transform: 'translateY(0)'
+    };
+  }
+
+  return {};
+});
+const StyledFootnoteHeader = /*#__PURE__*/styled.div.withConfig({
+  displayName: "Footnote__StyledFootnoteHeader",
+  componentId: "components-web__sc-1563bo5-1"
+})({
+  position: 'relative',
+  width: '100%'
+});
+const StyledHeader = /*#__PURE__*/styled.div.withConfig({
+  displayName: "Footnote__StyledHeader",
+  componentId: "components-web__sc-1563bo5-2"
+})(_ref3 => {
+  let {
+    headerMargin
+  } = _ref3;
+  return {
+    alignItems: 'center',
+    display: 'flex',
+    flexDirection: 'row',
+    justifyContent: 'space-between',
+    margin: headerMargin
+  };
+});
+const StyledFootnoteBody = /*#__PURE__*/styled.div.withConfig({
+  displayName: "Footnote__StyledFootnoteBody",
+  componentId: "components-web__sc-1563bo5-3"
+})({
+  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'
+  }
+}, _ref4 => {
+  let {
+    footnoteBodyBackground,
+    footnoteBodyPadding
+  } = _ref4;
+  return {
+    backgroundColor: footnoteBodyBackground,
+    padding: footnoteBodyPadding
+  };
+}, _ref5 => {
+  let {
+    headerHeight
+  } = _ref5;
+  return {
+    maxHeight: `calc(100vh - ${headerHeight}px)`,
+    ...media().from('md').css({
+      maxHeight: `calc(50vh - ${headerHeight}px)`
+    })
+  };
+}, _ref6 => {
+  let {
+    bodyHeight,
+    isTextVisible
+  } = _ref6;
+  return {
+    height: bodyHeight,
+    opacity: isTextVisible ? 1 : 0
+  };
+});
+const List = /*#__PURE__*/styled(OrderedListBase).withConfig({
+  displayName: "Footnote__List",
+  componentId: "components-web__sc-1563bo5-4"
+})(_ref7 => {
+  let {
+    listPaddingLeft
+  } = _ref7;
+  return {
+    listStylePosition: 'outside',
+    paddingLeft: listPaddingLeft
+  };
+});
+const ListItem = /*#__PURE__*/styled(OrderedListBase.Item).withConfig({
+  displayName: "Footnote__ListItem",
+  componentId: "components-web__sc-1563bo5-5"
+})(_ref8 => {
+  let {
+    listItemMarkerFontSize,
+    listItemMarkerLineHeight,
+    listItemColor,
+    listItemFontSize,
+    listItemLineHeight,
+    listItemPaddingLeft
+  } = _ref8;
+  return {
+    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 = /*#__PURE__*/styled.button.withConfig({
+  displayName: "Footnote__CloseButton",
+  componentId: "components-web__sc-1563bo5-6"
+})(_ref9 => {
+  let {
+    closeButtonBorder,
+    closeButtonHeight,
+    closeButtonMargin,
+    closeButtonWidth
+  } = _ref9;
+  return {
+    alignItems: 'center',
+    borderRadius: '50%',
+    cursor: 'pointer',
+    display: 'flex',
+    justifyContent: 'center',
+    border: closeButtonBorder,
+    height: closeButtonHeight,
+    margin: closeButtonMargin,
+    width: closeButtonWidth
+  };
+});
+const ContentContainer = /*#__PURE__*/styled.div.withConfig({
+  displayName: "Footnote__ContentContainer",
+  componentId: "components-web__sc-1563bo5-7"
+})({
+  'margin-left': 'auto',
+  'margin-right': 'auto',
+  left: 0,
+  right: 0
+}, _ref10 => {
+  let {
+    maxWidth
+  } = _ref10;
+  return {
+    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 => {
+  var _theme$themeOptions;
+
+  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 = theme.themeOptions) === null || _theme$themeOptions === void 0 ? void 0 : _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 => {
+    var _footnoteRef$current, _footnoteRef$current2;
+
+    if (event.type === 'keydown') {
+      if (event.key === 'Escape' || event.key === 27) {
+        closeFootnote(event, {
+          returnFocus: true
+        });
+      }
+    } else if ((event.type === 'click' || event.type === 'mousedown') && footnoteRef !== null && footnoteRef !== void 0 && footnoteRef.current && event.target && !(footnoteRef !== null && footnoteRef !== void 0 && (_footnoteRef$current = footnoteRef.current) !== null && _footnoteRef$current !== void 0 && _footnoteRef$current.contains(event.target)) && event.target.getAttribute('data-tds-id') !== 'footnote-link') {
+      closeFootnote(event, {
+        returnFocus: false
+      });
+    } else if (event.type === 'touchstart' && footnoteRef !== null && footnoteRef !== void 0 && footnoteRef.current && event.touches[0].target && !(footnoteRef !== null && footnoteRef !== void 0 && (_footnoteRef$current2 = footnoteRef.current) !== null && _footnoteRef$current2 !== void 0 && _footnoteRef$current2.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(() => {
+    var _headerRef$current;
+
+    setHeaderHeight((_headerRef$current = headerRef.current) === null || _headerRef$current === void 0 ? void 0 : _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 /*#__PURE__*/_jsx(Portal, {
+    children: /*#__PURE__*/_jsxs("div", { ...selectProps(rest),
+      children: [isOpen && /*#__PURE__*/_jsx(GlobalBodyScrollLock, {}), /*#__PURE__*/_jsx(StyledFootnote, {
+        ref: footnoteRef,
+        isOpen: isOpen,
+        isVisible: isVisible,
+        onTransitionEnd: handleStyledFootnoteTransitionEnd,
+        tabIndex: 0,
+        footnoteBackground: footnoteBackground,
+        footnoteBorderTop: `${footnoteBorderTopSizeMd}px solid ${footnoteBorderColorMd}`,
+        children: /*#__PURE__*/_jsxs(ContentContainer, {
+          maxWidth: maxWidth,
+          children: [/*#__PURE__*/_jsx(StyledFootnoteHeader, {
+            ref: headerRef,
+            children: /*#__PURE__*/_jsxs(StyledHeader, {
+              ref: headingRef,
+              headerMargin: headerMargin,
+              children: [/*#__PURE__*/_jsx(Typography, {
+                block: true,
+                heading: true,
+                tabIndex: -1,
+                variant: {
+                  size: 'h4'
+                },
+                children: getCopy('heading')
+              }), /*#__PURE__*/_jsx(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'),
+                children: /*#__PURE__*/_jsx(Icon, {
+                  icon: Close,
+                  tokens: {
+                    size: `${closeButtonIconSize}px`
+                  }
+                })
+              })]
+            })
+          }), /*#__PURE__*/_jsx(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`,
+            children: data.number && data.content && /*#__PURE__*/_jsx(List, {
+              start: data.number,
+              ref: listRef,
+              listPaddingLeft: listPaddingLeft,
+              children: /*#__PURE__*/_jsx(ListItem, {
+                listItemMarkerFontSize: listItemMarkerFontSize,
+                listItemMarkerLineHeight: listItemMarkerLineHeight,
+                listItemColor: listItemColor,
+                listItemFontSize: listItemFontSize,
+                listItemLineHeight: listItemLineHeight,
+                listItemPaddingLeft: listItemPaddingLeft,
+                children: /*#__PURE__*/_jsx(Typography, {
+                  children: renderStructuredContent(data.content)
+                })
+              })
+            })
+          })]
+        })
+      })]
+    })
+  });
+};
+
+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/lib-module/Footnote/FootnoteLink.js

@@ -0,0 +1,130 @@
+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';
+import { jsx as _jsx } from "react/jsx-runtime";
+import { Fragment as _Fragment } from "react/jsx-runtime";
+const [selectProps, selectedSystemPropTypes] = selectSystemProps([htmlAttrs]);
+const StyledSup = /*#__PURE__*/styled.sup.withConfig({
+  displayName: "FootnoteLink__StyledSup",
+  componentId: "components-web__sc-17nd7xo-0"
+})(_ref => {
+  let {
+    fontSize = 'smaller',
+    lineHeight,
+    paddingLeft,
+    paddingRight
+  } = _ref;
+  return {
+    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 = _ref2 => {
+  let {
+    copy = 'en',
+    number = [],
+    onClick,
+    fontSize,
+    tokens,
+    variant = {},
+    ...rest
+  } = _ref2;
+  const {
+    lineHeight,
+    paddingLeft,
+    paddingRight
+  } = useThemeTokens('FootnoteLink', tokens, variant);
+  const numbers = Array.isArray(number) ? number : [number];
+  const refs = numbers.map(() => /*#__PURE__*/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 /*#__PURE__*/_jsx(_Fragment, {
+    children: numbers.map((num, index) => /*#__PURE__*/_jsx(StyledSup, {
+      onKeyDown: event => handleOnKeyDown(event, index),
+      role: "button",
+      "aria-label": getCopy('a11yLabel'),
+      ref: refs[index],
+      onClick: event => handleOnClick(event, index),
+      fontSize: fontSize,
+      lineHeight: lineHeight,
+      paddingLeft: paddingLeft,
+      paddingRight: paddingRight,
+      ...selectProps(rest),
+      children: `${num}${index !== numbers.length - 1 ? ',' : ''}`
+    }, num))
+  });
+};
+
+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;

package/lib-module/Footnote/dictionary.js

@@ -0,0 +1,12 @@
+export default {
+  en: {
+    a11yLabel: 'Read legal footnote',
+    close: 'close',
+    heading: 'Terms and conditions'
+  },
+  fr: {
+    a11yLabel: 'Lire la note de bas de page légale',
+    close: 'fermer',
+    heading: 'Modalités et conditions'
+  }
+};

package/lib-module/Footnote/index.js

@@ -0,0 +1,4 @@
+import Footnote from './Footnote';
+import FootnoteLink from './FootnoteLink';
+Footnote.Link = FootnoteLink;
+export default Footnote;