@telus-uds/components-base 1.73.0 → 1.75.0

package/src/Footnote/Footnote.jsx

@@ -0,0 +1,316 @@
+import React, { useEffect, useState, useCallback } from 'react'
+import PropTypes from 'prop-types'
+import {
+  StyleSheet,
+  Text,
+  Dimensions,
+  TouchableWithoutFeedback,
+  Modal,
+  View,
+  SafeAreaView,
+  ScrollView
+} from 'react-native'
+
+import defaultDictionary from './dictionary'
+import { getTokensPropType, htmlAttrs, selectSystemProps, useCopy, viewProps } from '../utils'
+import { useViewport } from '../ViewportProvider'
+import { useTheme, useThemeTokens } from '../ThemeProvider'
+import Typography from '../Typography'
+import Icon from '../Icon'
+import OrderedList from '../OrderedList'
+
+const [selectProps, selectedSystemPropTypes] = selectSystemProps([htmlAttrs, viewProps])
+
+const selectFootnoteStyle = ({
+  screenHeight,
+  footnoteBackground,
+  isVisible,
+  footnoteBorderTopSizeMd,
+  footnoteBorderColorMd
+}) => ({
+  left: 0,
+  backgroundColor: footnoteBackground,
+  display: isVisible ? 'flex' : 'none',
+  height: screenHeight,
+  borderTopColor: footnoteBorderColorMd,
+  borderTopWidth: footnoteBorderTopSizeMd
+})
+
+const selectFootnoteHeaderContentStyle = ({
+  footnoteHeaderPaddingTop,
+  footnoteHeaderPaddingBottom,
+  footnoteHeaderPaddingRight,
+  footnoteHeaderPaddingLeft,
+  headerMargin
+}) => ({
+  paddingTop: footnoteHeaderPaddingTop,
+  paddingBottom: footnoteHeaderPaddingBottom,
+  paddingRight: footnoteHeaderPaddingRight,
+  paddingLeft: footnoteHeaderPaddingLeft,
+  marginRight: headerMargin
+})
+
+const selectFootnoteCloseButtonStyle = ({
+  closeButtonBorderSize,
+  closeButtonBorderColor,
+  closeButtonHeight,
+  closeButtonBackgroundColor,
+  closeButtonMarginTop,
+  closeButtonMarginRight,
+  closeButtonMarginBottom,
+  closeButtonMarginLeft,
+  closeButtonWidth
+}) => ({
+  backgroundColor: closeButtonBackgroundColor,
+  borderWidth: closeButtonBorderSize,
+  borderColor: closeButtonBorderColor,
+  height: closeButtonHeight,
+  marginTop: closeButtonMarginTop,
+  marginRight: closeButtonMarginRight,
+  marginBottom: closeButtonMarginBottom,
+  marginLeft: closeButtonMarginLeft,
+  width: closeButtonWidth
+})
+
+const selectFootnoteBodyStyle = ({
+  maxWidth,
+  footnoteBodyBackground,
+  footnoteBodyPaddingTop,
+  footnoteBodyPaddingRight,
+  footnoteBodyPaddingBottom,
+  footnoteBodyPaddingLeft,
+  screenWidth
+}) => ({
+  maxWidth,
+  backgroundColor: footnoteBodyBackground,
+  paddingTop: footnoteBodyPaddingTop,
+  paddingRight: footnoteBodyPaddingRight * 2,
+  paddingBottom: footnoteBodyPaddingBottom,
+  paddingLeft: footnoteBodyPaddingLeft,
+  width: screenWidth
+})
+
+const selectCustomContentFontStyle = ({
+  listItemColor,
+  listItemFontSize,
+  listItemLineHeight,
+  listItemPaddingLeft,
+  listItemFontName,
+  listItemFontWeight
+}) => ({
+  fontSize: listItemFontSize,
+  lineHeight: listItemLineHeight * listItemFontSize,
+  paddingLeft: listItemPaddingLeft,
+  color: listItemColor,
+  fontName: listItemFontName,
+  fontWeight: listItemFontWeight
+})
+
+/**
+ * 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`
+ * - 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 = ({
+  copy = 'en',
+  number = undefined,
+  content = undefined,
+  onClose,
+  isOpen = false,
+  tokens,
+  variant = {},
+  dictionary = defaultDictionary,
+  ...rest
+}) => {
+  const viewport = useViewport()
+
+  const themeTokens = useThemeTokens('Footnote', tokens, variant, { viewport })
+  const themeOptions = useTheme()
+
+  const getCopy = useCopy({ dictionary, copy })
+
+  const [isVisible, setIsVisible] = useState(false)
+
+  const screenHeight = Dimensions.get('screen').height
+  const screenWidth = Dimensions.get('screen').width
+
+  const getFootnoteBodyContent = useCallback(() => {
+    if (!number || !content) {
+      return null
+    }
+
+    if (React.isValidElement(content)) {
+      return <View style={selectCustomContentFontStyle(themeTokens)}>{content}</View>
+    }
+
+    return (
+      // TODO: Extract the OrderedList.Item from the array when the issue #4361 is fixed
+      <OrderedList start={number}>
+        {[
+          <OrderedList.Item key={number}>
+            <Text style={selectCustomContentFontStyle(themeTokens)}>{content}</Text>
+          </OrderedList.Item>
+        ]}
+      </OrderedList>
+    )
+  }, [content, number, themeTokens])
+
+  useEffect(() => {
+    if (isOpen) {
+      setIsVisible(true)
+    }
+  }, [isOpen])
+
+  const closeFootnote = useCallback(
+    (event, options) => {
+      onClose(event, options)
+      setIsVisible(false)
+    },
+    [onClose]
+  )
+
+  const handleClose = (event) => closeFootnote(event, { returnFocus: true })
+
+  return (
+    <View {...selectProps(rest)}>
+      <Modal visible={isVisible} animationType="slide">
+        <SafeAreaView style={staticStyles.container}>
+          <ScrollView
+            style={selectFootnoteStyle({
+              screenHeight,
+              isVisible,
+              ...themeTokens
+            })}
+          >
+            <View style={staticStyles.content}>
+              <View
+                style={[selectFootnoteHeaderContentStyle(themeTokens), staticStyles.headerContent]}
+              >
+                <Typography
+                  tokens={{
+                    fontSize: themeTokens?.headerFontSize,
+                    lineHeight: themeTokens?.headerLineHeight
+                  }}
+                  variant={{ size: 'h4' }}
+                >
+                  {getCopy('heading')}
+                </Typography>
+                <TouchableWithoutFeedback
+                  onPress={handleClose}
+                  accessibilityLabel={getCopy('close')}
+                >
+                  <View
+                    style={[selectFootnoteCloseButtonStyle(themeTokens), staticStyles.closeButton]}
+                  >
+                    <Icon
+                      icon={themeTokens?.closeIcon}
+                      tokens={{ size: themeTokens?.closeButtonIconSize }}
+                    />
+                  </View>
+                </TouchableWithoutFeedback>
+              </View>
+              <View
+                style={selectFootnoteBodyStyle({
+                  maxWidth: themeOptions.contentMaxWidth,
+                  screenWidth,
+                  ...themeTokens
+                })}
+              >
+                {getFootnoteBodyContent()}
+              </View>
+            </View>
+          </ScrollView>
+        </SafeAreaView>
+      </Modal>
+    </View>
+  )
+}
+
+const copyShape = PropTypes.shape({
+  close: PropTypes.string.isRequired,
+  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,
+  tokens: getTokensPropType('Footnote'),
+  /**
+   * The content.
+   */
+  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`.
+   */
+  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,
+  /**
+   * Override the default dictionary, by passing the complete dictionary object for `en` and `fr`
+   */
+  dictionary: PropTypes.shape({
+    en: dictionaryContentShape,
+    fr: dictionaryContentShape
+  })
+}
+
+export default Footnote
+
+const staticStyles = StyleSheet.create({
+  container: {
+    flex: 1
+  },
+  content: {
+    marginLeft: 'auto',
+    marginRight: 'auto',
+    left: 0,
+    right: 0,
+    maxWidth: 1200,
+    paddingBottom: 100
+  },
+  headerContent: {
+    alignItems: 'center',
+    display: 'flex',
+    flexDirection: 'row',
+    justifyContent: 'space-between'
+  },
+  closeButton: {
+    alignItems: 'center',
+    borderRadius: 50,
+    display: 'flex',
+    justifyContent: 'center'
+  }
+})

package/src/Footnote/FootnoteLink.jsx

@@ -0,0 +1,95 @@
+import React from 'react'
+import PropTypes from 'prop-types'
+import { View, StyleSheet, Platform, TouchableWithoutFeedback } from 'react-native'
+import dictionary from './dictionary'
+import { htmlAttrs, selectSystemProps, useCopy, viewProps, wrapStringsInText } from '../utils'
+import { applyTextStyles, useThemeTokens } from '../ThemeProvider'
+
+const [selectProps, selectedSystemPropTypes] = selectSystemProps([htmlAttrs, viewProps])
+
+// The top property varies between devices due to how devices render the viewport.
+const selectTextStyle = ({ fontSize, lineHeight }) => ({
+  fontSize,
+  lineHeight: lineHeight !== 1 ? lineHeight : fontSize * 2,
+  ...Platform.select({
+    ios: {
+      top: -fontSize / 2
+    },
+    android: {
+      top: fontSize / 4
+    },
+    web: {
+      top: -fontSize / 2.8
+    }
+  })
+})
+
+const FootnoteLink = ({ copy = 'en', content = [], onClick, tokens, variant = {}, ...rest }) => {
+  const themeTokens = useThemeTokens('FootnoteLink', tokens, variant)
+  const textStyles = applyTextStyles(themeTokens)
+
+  const numbers = Array.isArray(content) ? content : [content]
+  const refs = numbers.map(() => React.createRef())
+
+  const handleOnClick = (index) => {
+    onClick(numbers[index], refs[index])
+  }
+  const getCopy = useCopy({ dictionary, copy })
+
+  return (
+    <>
+      {numbers.map((num, index) => (
+        <View
+          accessibilityLabel={getCopy('a11yLabel')}
+          key={num}
+          ref={refs[index]}
+          {...selectProps(rest)}
+        >
+          <TouchableWithoutFeedback onPress={handleOnClick} accessibilityRole="button">
+            {wrapStringsInText(`${num}${index !== numbers.length - 1 ? ',' : ''}`, {
+              style: {
+                ...textStyles,
+                ...staticStyles.text,
+                ...selectTextStyle(themeTokens)
+              }
+            })}
+          </TouchableWithoutFeedback>
+        </View>
+      ))}
+    </>
+  )
+}
+
+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.
+   */
+  content: 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
+}
+
+export default FootnoteLink
+
+const staticStyles = StyleSheet.create({
+  text: {
+    position: 'relative',
+    textDecorationLine: 'underline'
+  }
+})

package/src/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/src/Footnote/index.js

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