@telus-uds/components-web 1.4.0 → 1.6.0

package/src/Modal/ModalContent.jsx

@@ -0,0 +1,161 @@
+/* eslint-disable react/jsx-filename-extension */
+import React, { useState } from 'react'
+import {
+  Box,
+  Button,
+  Spacer,
+  TextButton,
+  Typography,
+  useThemeTokens,
+  useViewport
+} from '@telus-uds/components-base'
+import styled from 'styled-components'
+import PropTypes from 'prop-types'
+
+const StyledModalContent = styled.div`
+  display: flex;
+  flex-direction: column;
+  min-height: 100%;
+`
+
+const StyledHeading = styled.header`
+  display: flex;
+  flex-direction: column;
+  padding-right: ${({ paddingRight }) => paddingRight}px;
+`
+
+const StyledSubHeading = styled.div`
+  margin-top: ${({ marginTop }) => marginTop}px;
+`
+
+const StyledFooter = styled.footer(
+  ({
+    hasBorder,
+    viewport,
+    paddingLeft,
+    paddingRight,
+    paddingTop,
+    marginLeft,
+    marginRight,
+    borderColor,
+    gap
+  }) => ({
+    display: 'flex',
+    flexDirection: viewport === 'xs' || viewport === 'sm' ? 'column' : 'row',
+    alignItems: 'center',
+    gap: `${gap}px`,
+    marginLeft: `calc(-1 * ${marginLeft}px)`,
+    marginRight: `calc(-1 * ${marginRight}px)`,
+    paddingLeft: `${paddingLeft}px`,
+    paddingRight: `${paddingRight}px`,
+    paddingTop: `${paddingTop}px`,
+    borderTop: hasBorder ? `1px solid ${borderColor}` : 'none'
+  })
+)
+
+const ModalContent = ({
+  heading,
+  headingLevel = 'h3',
+  subHeading,
+  subHeadingSize = 'medium',
+  bodyText,
+  confirmButtonText,
+  confirmButtonVariant = { priority: 'high' },
+  onConfirm,
+  tokens,
+  variant,
+  cancelButtonText,
+  cancelButtonType: CancelButton = TextButton,
+  onCancel
+}) => {
+  const { headingColor, cancelButtonColor, ...themeTokens } = useThemeTokens(
+    'Modal',
+    tokens,
+    variant
+  )
+  const [scrollContainerHeight, setScrollContainerHeight] = useState(0)
+  const [scrollContentHeight, setScrollContentHeight] = useState(0)
+  const viewport = useViewport()
+
+  const handleContainerLayout = ({
+    nativeEvent: {
+      layout: { height }
+    }
+  }) => setScrollContainerHeight(height)
+  const onContentSizeChange = (_, height) => setScrollContentHeight(height)
+  const isContentOverflowing = scrollContentHeight > scrollContainerHeight
+
+  const hasConfirmButton = confirmButtonText !== undefined && onConfirm !== undefined
+  const hasCancelButton = cancelButtonText !== undefined && onCancel !== undefined
+  const hasHeadingSection = Boolean(heading || subHeading)
+
+  return (
+    <StyledModalContent>
+      {hasHeadingSection && (
+        <StyledHeading paddingRight={themeTokens.headingPaddingRight}>
+          {heading && (
+            <Typography
+              variant={{ size: headingLevel }}
+              tokens={{ color: headingColor }}
+              heading={headingLevel}
+            >
+              {heading}
+            </Typography>
+          )}
+          {subHeading && (
+            <StyledSubHeading marginTop={themeTokens.subHeadingMarginTop}>
+              <Typography variant={{ size: subHeadingSize }}>{subHeading}</Typography>
+            </StyledSubHeading>
+          )}
+          {Boolean(bodyText && hasHeadingSection) && <Spacer space={3} />}
+        </StyledHeading>
+      )}
+      {bodyText && (
+        <Box
+          scroll={{ onContentSizeChange, showsVerticalScrollIndicator: true }}
+          onLayout={handleContainerLayout}
+        >
+          <Typography>{bodyText}</Typography>
+        </Box>
+      )}
+      {(hasConfirmButton || hasCancelButton) && (
+        <StyledFooter {...themeTokens} hasBorder={isContentOverflowing} viewport={viewport}>
+          {hasConfirmButton && (
+            <Button
+              variant={confirmButtonVariant}
+              tokens={{ width: viewport === 'xs' || viewport === 'sm' ? '100%' : undefined }}
+              onPress={onConfirm}
+            >
+              {confirmButtonText}
+            </Button>
+          )}
+          <div>
+            {hasCancelButton && (
+              <CancelButton tokens={{ color: cancelButtonColor }} onPress={onCancel}>
+                {cancelButtonText}
+              </CancelButton>
+            )}
+          </div>
+        </StyledFooter>
+      )}
+    </StyledModalContent>
+  )
+}
+
+ModalContent.propTypes = {
+  tokens: PropTypes.object,
+  variant: PropTypes.object,
+  heading: PropTypes.string,
+  headingLevel: PropTypes.oneOf(['h3', 'h4']),
+  subHeading: PropTypes.string,
+  subHeadingSize: PropTypes.oneOf(['small', 'medium', 'large']),
+  bodyText: PropTypes.string,
+  confirmButtonText: PropTypes.string,
+  confirmButtonVariant: PropTypes.object,
+  onConfirm: PropTypes.func,
+  cancelButtonText: PropTypes.string,
+  cancelButtonType: PropTypes.elementType, // TODO: figure out a way of passing an icon to the TextButton
+  onCancel: PropTypes.func
+}
+
+export default ModalContent

package/src/Modal/index.js

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

package/src/Paragraph/Paragraph.jsx

@@ -0,0 +1,79 @@
+import React from 'react'
+import PropTypes from 'prop-types'
+import styled from 'styled-components'
+import { selectSystemProps } from '@telus-uds/components-base'
+
+import { htmlAttrs, useTypographyTheme } from '../utils'
+
+const [selectProps, selectedSystemPropTypes] = selectSystemProps([htmlAttrs])
+
+const StyledParagraph = styled.p`
+  ${({ align }) => (align ? `text-align: ${align};` : '')}
+  ${({ linesBetween }) => `
+    margin-block-start: ${linesBetween}em;
+    margin-block-end: ${linesBetween}em;
+  `}
+  &:first-child {
+    margin-block-start: 0em;
+  }
+  &:last-child {
+    margin-block-end: 0em;
+  }
+`
+
+/**
+* Block text as an HTML ```<p>``` element.
+	*
+	* ##Usage criteria
+	*
+	* - All body text should be contained in a **Paragraph**, regardless of length.
+	* - If the Paragraph is on a dark background, variant **{ invert: true }** must be used to maintain sufficient colour
+	contrast.
+	* - All Allium Typography variants other than header size variants are supported.
+	*/
+const Paragraph = ({ children, variant, tokens, testID, align, linesBetween = 1, ...rest }) => {
+  const style = useTypographyTheme(variant, tokens)
+  return (
+    <StyledParagraph
+      linesBetween={linesBetween}
+      data-testid={testID}
+      align={align}
+      style={style}
+      {...selectProps(rest)}
+    >
+      {children}
+    </StyledParagraph>
+  )
+}
+
+Paragraph.propTypes = {
+  ...selectedSystemPropTypes,
+  children: PropTypes.node.isRequired,
+  testID: PropTypes.string,
+  /**
+   * Sets the alignment style for the paragraph. Same options as Typography's `align` prop.
+   * 'justify' should be avoided as it usually reduces ease of reading.
+   */
+  align: PropTypes.oneOf(['auto', 'left', 'right', 'center', 'justify']),
+  /**
+   * How much space between consecutive paragraphs, or between a paragraph and its siblings, in CSS
+   * `em` units: 1 gives space equal to one line of paragraph text, 0.5 would be half a line, etc.
+   * @default 1
+   */
+  linesBetween: PropTypes.number,
+  /**
+   * Paragraph takes the same tokens overrides as Typography
+   */
+  tokens: PropTypes.oneOf([PropTypes.object, PropTypes.func]),
+  /**
+   * Paragraph takes any of Typography's theme variants except for header sizes
+   */
+  variant: PropTypes.exact({
+    bold: PropTypes.bool,
+    colour: PropTypes.oneOf(['secondary', 'tertiary']),
+    inverse: PropTypes.bool,
+    size: PropTypes.oneOf(['micro', 'small', 'large'])
+  })
+}
+
+export default Paragraph

package/src/Paragraph/index.js

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

package/src/Table/Body.jsx

@@ -0,0 +1,12 @@
+import React from 'react'
+import PropTypes from 'prop-types'
+
+const Body = ({ children }) => {
+  return <tbody>{children}</tbody>
+}
+
+Body.propTypes = {
+  children: PropTypes.node
+}
+
+export default Body

package/src/Table/Cell.jsx

@@ -0,0 +1,148 @@
+import React from 'react'
+import PropTypes from 'prop-types'
+import styled, { css } from 'styled-components'
+import { Typography, useThemeTokens } from '@telus-uds/components-base'
+import { useTableContext } from './Table'
+
+const stickyStyles = css`
+  position: sticky;
+  left: 0; // needed for sticky to work
+  z-index: 2;
+  clip-path: inset(0 -8px 0 0); // use clip path to cut off the shadow rendered below
+
+  &::before {
+    // use a pseudo element for the sticky shadow, since we already use shadows for inner cells border
+    content: '';
+    box-shadow: ${({ cellStickyShadow }) => cellStickyShadow};
+    position: absolute;
+    top: 0;
+    left: 0;
+    right: 0;
+    bottom: 0;
+    pointer-events: none;
+  }
+`
+const sharedStyles = css`
+  ${({
+    isSticky,
+    cellBoxShadowColor,
+    align,
+    cellPaddingTop,
+    cellPaddingRight,
+    cellPaddingBottom,
+    cellPaddingLeft
+  }) => css`
+    ${isSticky ? stickyStyles : undefined};
+    box-shadow: inset 0 -1px 0 ${cellBoxShadowColor};
+    text-align: ${align};
+    padding: ${cellPaddingTop}px ${cellPaddingRight}px ${cellPaddingBottom}px ${cellPaddingLeft}px;
+  `}
+`
+const StyledHeading = styled.th`
+  ${sharedStyles};
+  ${({ cellHeadingBackground, cellHeadingBoxShadowColor }) => `
+  background-color: ${cellHeadingBackground};
+  box-shadow: inset 0 1px 0 ${cellHeadingBoxShadowColor}, inset 0 -1px 0 ${cellHeadingBoxShadowColor};`}
+`
+
+const StyledSubHeading = styled.th`
+  ${sharedStyles};
+  background-color: ${({ cellSubheadingBackground }) => cellSubheadingBackground};
+`
+
+const StyledCell = styled.td`
+  ${sharedStyles};
+  background-color: ${({ cellBackground }) => cellBackground};
+`
+
+const StyledRowHeading = styled.th`
+  ${sharedStyles};
+  background-color: ${({ cellRowHeadingBackground }) => cellRowHeadingBackground};
+`
+
+const Cell = ({ children, type = 'default', isFirstInRow, align = 'left' }) => {
+  const { text, isScrollable: isTableScrollable, variant, tokens } = useTableContext()
+  const {
+    cellHeadingBackground,
+    cellHeadingBoxShadowColor,
+    cellBoxShadowColor,
+    cellSubheadingBackground,
+    cellBackground,
+    cellRowHeadingBackground,
+    cellStickyShadow,
+    cellPaddingTop,
+    cellPaddingRight,
+    cellPaddingLeft,
+    cellPaddingBottom
+  } = useThemeTokens('Table', tokens, variant)
+  const sharedProps = {
+    align,
+    isSticky: isTableScrollable && isFirstInRow,
+    cellStickyShadow,
+    cellPaddingTop,
+    cellPaddingRight,
+    cellPaddingLeft,
+    cellPaddingBottom,
+    cellBoxShadowColor
+  }
+
+  switch (type) {
+    case 'heading':
+      return (
+        <StyledHeading
+          scope="col"
+          cellHeadingBackground={cellHeadingBackground}
+          cellHeadingBoxShadowColor={cellHeadingBoxShadowColor}
+          {...sharedProps}
+        >
+          <Typography variant={{ size: 'h4' }}>{children}</Typography>
+        </StyledHeading>
+      )
+    case 'subHeading':
+      return (
+        <StyledSubHeading
+          scope="col"
+          cellSubheadingBackground={cellSubheadingBackground}
+          {...sharedProps}
+        >
+          <Typography variant={{ size: 'h5' }}>{children}</Typography>
+        </StyledSubHeading>
+      )
+    case 'rowHeading':
+      return (
+        <StyledRowHeading
+          scope="row"
+          cellRowHeadingBackground={cellRowHeadingBackground}
+          {...sharedProps}
+        >
+          <Typography variant={{ size: text === 'small' ? 'h5' : 'h4' }}>{children}</Typography>
+        </StyledRowHeading>
+      )
+
+    default:
+      return (
+        <StyledCell cellBackground={cellBackground} {...sharedProps}>
+          <Typography variant={{ size: text }}>{children}</Typography>
+        </StyledCell>
+      )
+  }
+}
+
+Cell.propTypes = {
+  children: PropTypes.node,
+  /**
+   * Defines the visual styles of a cell, and whether it should be a `td` or `th` element
+   */
+  type: PropTypes.oneOf(['default', 'heading', 'subHeading', 'rowHeading']),
+  /**
+   * @ignore
+   * Used internally for making the first column sticky
+   */
+  isFirstInRow: PropTypes.bool,
+  /**
+   * Defines the text alignment within the cell
+   */
+  align: PropTypes.oneOf(['left', 'center', 'right'])
+}
+
+export default Cell

package/src/Table/Header.jsx

@@ -0,0 +1,17 @@
+import React, { cloneElement } from 'react'
+import PropTypes from 'prop-types'
+import Row from './Row'
+
+const Header = ({ children }) => {
+  return (
+    <thead>
+      <Row>{React.Children.map(children, (child) => cloneElement(child, { type: 'heading' }))}</Row>
+    </thead>
+  )
+}
+
+Header.propTypes = {
+  children: PropTypes.node
+}
+
+export default Header

package/src/Table/Row.jsx

@@ -0,0 +1,18 @@
+import React, { cloneElement } from 'react'
+import PropTypes from 'prop-types'
+
+const Row = ({ children }) => {
+  return (
+    <tr>
+      {React.Children.map(children, (child, index) =>
+        cloneElement(child, { isFirstInRow: index === 0 })
+      )}
+    </tr>
+  )
+}
+
+Row.propTypes = {
+  children: PropTypes.node
+}
+
+export default Row

package/src/Table/SubHeading.jsx

@@ -0,0 +1,17 @@
+import React, { cloneElement } from 'react'
+import PropTypes from 'prop-types'
+import Row from './Row'
+
+const Header = ({ children }) => {
+  return (
+    <Row>
+      {React.Children.map(children, (child) => cloneElement(child, { type: 'subHeading' }))}
+    </Row>
+  )
+}
+
+Header.propTypes = {
+  children: PropTypes.node
+}
+
+export default Header

package/src/Table/Table.jsx

@@ -0,0 +1,90 @@
+import React, { useContext, useRef, useState } from 'react'
+import PropTypes from 'prop-types'
+import styled from 'styled-components'
+import { selectSystemProps, useSafeLayoutEffect, useThemeTokens } from '@telus-uds/components-base'
+import throttle from 'lodash.throttle'
+import { htmlAttrs } from '../utils'
+
+const [selectProps, selectedSystemPropTypes] = selectSystemProps([htmlAttrs])
+
+const StyledContainer = styled.div`
+  overflow: auto;
+  padding-bottom: ${(props) => (props.isScrollable ? props.tablePaddingBottom : 0)};
+`
+
+const StyledTable = styled.table`
+  margin: 0;
+  padding: 0;
+`
+
+const TableContext = React.createContext({})
+
+export const useTableContext = () => useContext(TableContext)
+
+/**
+ * Use `Table` to display tabular data.
+ *
+ * - Takes an optional `spacing` variant (compact)
+ * - Available in 2 text styles (medium, small)
+ * - When `Table` exceeds viewport, the first column becomes sticky, enabling horizontal scrolling
+ * - Right-align prices and numbers that display decimal points
+ *
+ * ### Building up a `Table`
+ * - Use `Table.Header` and `Table.Body` as direct children of `Table`
+ * - Use `Table.SubHeading` to render an intermediate data heading row
+ * - Use `Table.Row` and `Table.Cell` to build up the tabular data
+ * - Use `Cell`'s `type` prop to visually mark it as a row heading (`type="rowHeading"`)
+ */
+const Table = ({ children, text = 'medium', tokens, variant, ...rest }) => {
+  const { tablePaddingBottom } = useThemeTokens('Table', tokens, variant)
+  const containerRef = useRef()
+  const tableRef = useRef()
+
+  const [containerWidth, setContainerWidth] = useState(0)
+  const [tableWidth, setTableWidth] = useState(0)
+
+  useSafeLayoutEffect(() => {
+    const updateDimensions = () => {
+      setContainerWidth(containerRef.current.clientWidth)
+      setTableWidth(tableRef.current.clientWidth)
+    }
+
+    const throttledUpdateDimensions = throttle(updateDimensions, 100, { leading: false })
+
+    updateDimensions()
+
+    // a pretty naive way of repeating the measurement after the fonts are loaded
+    window.addEventListener('load', updateDimensions)
+    window.addEventListener('resize', throttledUpdateDimensions)
+
+    return () => {
+      window.removeEventListener('load', updateDimensions)
+      window.removeEventListener('resize', throttledUpdateDimensions)
+    }
+  }, [])
+
+  const isScrollable = tableWidth > containerWidth
+
+  return (
+    <StyledContainer
+      ref={containerRef}
+      isScrollable={isScrollable}
+      tablePaddingBottom={`${tablePaddingBottom}px`}
+      {...selectProps(rest)}
+    >
+      <TableContext.Provider value={{ text, isScrollable, tokens, variant }}>
+        <StyledTable cellSpacing={0} ref={tableRef}>
+          {children}
+        </StyledTable>
+      </TableContext.Provider>
+    </StyledContainer>
+  )
+}
+
+Table.propTypes = {
+  ...selectedSystemPropTypes,
+  children: PropTypes.node,
+  text: PropTypes.oneOf(['medium', 'small'])
+}
+
+export default Table

package/src/Table/index.js

@@ -0,0 +1,14 @@
+import Table from './Table'
+import Header from './Header'
+import Body from './Body'
+import Row from './Row'
+import SubHeading from './SubHeading'
+import Cell from './Cell'
+
+Table.Header = Header
+Table.Body = Body
+Table.Row = Row
+Table.SubHeading = SubHeading
+Table.Cell = Cell
+
+export default Table