@telus-uds/components-web 2.9.0 → 2.11.0

package/src/Listbox/GroupControl.jsx

@@ -1,64 +1,81 @@
 import React from 'react'
 import styled from 'styled-components'
 import PropTypes from 'prop-types'
-import { Icon, Spacer, useThemeTokens } from '@telus-uds/components-base'
+import { Icon, Spacer, useThemeTokens, useListboxContext } from '@telus-uds/components-base'
 
-const StyledControlWrapper = styled.div(({ focus, tokens }) => ({
-  fontFamily: `${tokens.groupFontName}${tokens.groupFontWeight}normal`,
-  fontSize: tokens.groupFontSize,
-  color: tokens.groupColor,
-  textDecoration: tokens.itemTextDecoration,
-  backgroundColor: tokens.groupBackgroundColor,
-  outline: tokens.itemOutline,
-  width: '100%',
-  display: 'flex',
-  justifyContent: 'space-between',
-  ...(focus
-    ? {
-        border: `${tokens.groupBorderWidth} solid ${tokens.groupBorderColor}`,
-        borderRadius: tokens.groupBorderRadius,
-        paddingLeft: `calc(${tokens.groupPaddingLeft}px - ${tokens.groupBorderWidth}px)`,
-        paddingRight: `calc(${tokens.groupPaddingRight}px - ${tokens.groupBorderWidth}px)`,
-        paddingTop: `calc(${tokens.groupPaddingTop}px - ${tokens.groupBorderWidth}px)`,
-        paddingBottom: `calc(${tokens.groupPaddingBottom}px - ${tokens.groupBorderWidth}px)`
-      }
-    : {
-        paddingLeft: tokens.groupPaddingLeft,
-        paddingRight: tokens.groupPaddingRight,
-        paddingTop: tokens.groupPaddingTop,
-        paddingBottom: tokens.groupPaddingBottom
-      })
-}))
+const StyledControlWrapper = styled.div(
+  ({
+    groupFontName,
+    groupFontWeight,
+    groupFontSize,
+    groupColor,
+    groupBackgroundColor,
+    groupBorderColor,
+    groupBorderWidth,
+    groupBorderRadius,
+    groupPaddingLeft,
+    groupPaddingRight,
+    groupPaddingTop,
+    groupPaddingBottom,
+    itemTextDecoration,
+    itemOutline,
+    groupHeight
+  }) => ({
+    fontFamily: `${groupFontName}${groupFontWeight}normal`,
+    fontSize: groupFontSize,
+    color: groupColor,
+    textDecoration: itemTextDecoration,
+    backgroundColor: groupBackgroundColor,
+    outline: itemOutline,
+    width: '100%',
+    height: groupHeight,
+    display: 'flex',
+    alignItems: 'center',
+    justifyContent: 'space-between',
+    boxSizing: 'border-box',
+    border: `${groupBorderWidth}px solid ${groupBorderColor}`,
+    borderRadius: groupBorderRadius,
+    paddingLeft: groupPaddingLeft - groupBorderWidth,
+    paddingRight: groupPaddingRight - groupBorderWidth,
+    paddingTop: groupPaddingTop - groupBorderWidth,
+    paddingBottom: groupPaddingBottom - groupBorderWidth
+  })
+)
 
-const GroupControl = ({ expanded, pressed, hover, focus, current, label }) => {
+const GroupControl = ({ expanded, pressed, hover, focus, label, id }) => {
+  const { selectedId, setSelectedId } = useListboxContext()
   const tokens = useThemeTokens(
-    'ListBox',
+    'Listbox',
     {},
     {},
     {
       expanded,
       pressed,
       hover,
-      current,
+      current: selectedId === id && id !== undefined,
       focus
     }
   )
 
   return (
-    <StyledControlWrapper {...{ focus, tokens }}>
+    <StyledControlWrapper onClick={() => setSelectedId(id)} {...tokens}>
       {label}
       <Spacer space={1} direction="row" />
-      <Icon icon={tokens.groupIcon} variant={{ size: 'micro' }} />
+      <Icon
+        icon={tokens.groupIcon}
+        tokens={{ color: tokens.groupColor }}
+        variant={{ size: 'micro' }}
+      />
     </StyledControlWrapper>
   )
 }
 
 GroupControl.propTypes = {
+  id: PropTypes.string,
   expanded: PropTypes.bool,
   pressed: PropTypes.bool,
   hover: PropTypes.bool,
   focus: PropTypes.bool,
-  current: PropTypes.bool,
   label: PropTypes.string
 }
 

package/src/Listbox/Listbox.jsx

@@ -1,11 +1,15 @@
 import React, { useCallback, useEffect, useRef, useState } from 'react'
 import PropTypes from 'prop-types'
 import styled from 'styled-components'
-import { ExpandCollapse, withLinkRouter } from '@telus-uds/components-base'
+import {
+  ExpandCollapse,
+  useThemeTokens,
+  withLinkRouter,
+  ListboxContext
+} from '@telus-uds/components-base'
 import ListboxGroup from './ListboxGroup'
 import ListboxItem from './ListboxItem'
 import DropdownOverlay from './ListboxOverlay'
-import resolveItemSelection from '../NavigationBar/resolveItemSelection'
 
 const StyledList = styled.ul({
   margin: 0,
@@ -26,12 +30,18 @@ const Listbox = ({
   items = [],
   firstItemRef = null, // focus will be moved to this one once within the menu
   parentRef = null, // to return focus to after leaving the last menu item
-  selectedId,
+  selectedId: defaultSelectedId,
   LinkRouter,
   itemRouterProps,
-  onClose
+  onClose,
+  variant,
+  tokens
 }) => {
-  const initialOpen = getInitialOpen(items, selectedId)
+  const initialOpen = getInitialOpen(items, defaultSelectedId)
+
+  const [selectedId, setSelectedId] = useState(defaultSelectedId)
+
+  const { minHeight, minWidth } = useThemeTokens('Listbox', variant, tokens)
 
   // We need to keep track of each item's ref in order to be able to
   // focus on a specific item via keyboard navigation
@@ -78,53 +88,52 @@ const Listbox = ({
   }, [onClose, handleKeydown])
 
   return (
-    <ExpandCollapse initialOpen={initialOpen} maxOpen={1}>
-      {(expandProps) => (
-        <StyledList role="listbox">
-          {items.map((item, index) => {
-            const { id, label, items: nestedItems } = item
-            const { itemId, selected } = resolveItemSelection(
-              { id, label, items: nestedItems },
-              selectedId
-            )
+    <ListboxContext.Provider value={{ selectedId, setSelectedId }}>
+      <ExpandCollapse initialOpen={initialOpen} maxOpen={1}>
+        {(expandProps) => (
+          <StyledList role="listbox" style={{ minHeight, minWidth }}>
+            {items.map((item, index) => {
+              const { id, label, items: nestedItems } = item
+              const itemId = id ?? label
 
-            // Give `firstItemRef` to the first focusable item
-            const itemRef =
-              (index === 0 && !itemId !== selectedId) || (index === 1 && items[0].id === selectedId)
-                ? firstItemRef
-                : (ref) => {
-                    itemRefs.current[index] = ref
-                    return ref
-                  }
+              // Give `firstItemRef` to the first focusable item
+              const itemRef =
+                (index === 0 && !itemId !== selectedId) ||
+                (index === 1 && items[0].id === selectedId)
+                  ? firstItemRef
+                  : (ref) => {
+                      itemRefs.current[index] = ref
+                      return ref
+                    }
 
-            return nestedItems ? (
-              <ListboxGroup
-                {...item}
-                selectedId={selectedId}
-                key={itemId}
-                expandProps={expandProps}
-                LinkRouter={LinkRouter}
-                itemRouterProps={itemRouterProps}
-                prevItemRef={itemRefs.current[index - 1] ?? null}
-                nextItemRef={itemRefs.current[index + 1] ?? null}
-                ref={itemRef}
-              />
-            ) : (
-              <ListboxItem
-                {...item}
-                selected={selected}
-                key={itemId}
-                LinkRouter={LinkRouter}
-                itemRouterProps={itemRouterProps}
-                prevItemRef={itemRefs.current[index - 1] ?? null}
-                nextItemRef={itemRefs.current[index + 1] ?? null}
-                ref={itemRef}
-              />
-            )
-          })}
-        </StyledList>
-      )}
-    </ExpandCollapse>
+              return nestedItems ? (
+                <ListboxGroup
+                  {...item}
+                  expandProps={expandProps}
+                  LinkRouter={LinkRouter}
+                  itemRouterProps={itemRouterProps}
+                  prevItemRef={itemRefs.current[index - 1] ?? null}
+                  nextItemRef={itemRefs.current[index + 1] ?? null}
+                  ref={itemRef}
+                  key={itemId}
+                />
+              ) : (
+                <ListboxItem
+                  {...item}
+                  key={itemId}
+                  id={itemId}
+                  LinkRouter={LinkRouter}
+                  itemRouterProps={itemRouterProps}
+                  prevItemRef={itemRefs.current[index - 1] ?? null}
+                  nextItemRef={itemRefs.current[index + 1] ?? null}
+                  ref={itemRef}
+                />
+              )
+            })}
+          </StyledList>
+        )}
+      </ExpandCollapse>
+    </ListboxContext.Provider>
   )
 }
 
@@ -139,7 +148,13 @@ Listbox.propTypes = {
    * the last menu item.
    */
   parentRef: PropTypes.object,
+  /**
+   * `Listbox` items
+   */
   items: PropTypes.array,
+  /**
+   * To select an item by default
+   */
   selectedId: PropTypes.string
 }
 

package/src/Listbox/ListboxGroup.jsx

@@ -1,7 +1,7 @@
 /* eslint-disable react/require-default-props */
 import React, { forwardRef } from 'react'
 import PropTypes from 'prop-types'
-import { ExpandCollapse, withLinkRouter } from '@telus-uds/components-base'
+import { ExpandCollapse, withLinkRouter, useListboxContext } from '@telus-uds/components-base'
 import styled from 'styled-components'
 import ListboxItem from './ListboxItem'
 import GroupControl from './GroupControl'
@@ -31,7 +31,6 @@ const ListboxGroup = forwardRef(
       id,
       label,
       items,
-      selectedId,
       LinkRouter,
       linkRouterProps,
       expandProps,
@@ -41,8 +40,9 @@ const ListboxGroup = forwardRef(
     },
     ref
   ) => {
-    // TODO: implement keyboard navigation via refs for grouped items separately here
+    const { selectedId } = useListboxContext()
 
+    // TODO: implement keyboard navigation via refs for grouped items separately here
     return (
       <StyledGroupWrapper role="option">
         <ExpandCollapse.Panel
@@ -52,34 +52,49 @@ const ListboxGroup = forwardRef(
             paddingLeft: 'none',
             paddingRight: 'none',
             paddingTop: 'none',
-            paddingBottom: 'none'
+            paddingBottom: 'none',
+            backgroundColor: 'transparent',
+            borderColor: 'transparent',
+            textLine: 'none',
+            borderWidth: 0
           }}
           // TODO refactor
           // eslint-disable-next-line react/no-unstable-nested-components
-          control={(controlProps) => <GroupControl {...controlProps} label={label} />}
+          control={(controlProps) => (
+            <GroupControl id={id ?? label} {...controlProps} label={label} />
+          )}
           {...expandProps}
           tokens={{
             contentPaddingLeft: 'none',
             contentPaddingRight: 'none',
             contentPaddingTop: 'none',
-            contentPaddingBottom: 'none'
+            contentPaddingBottom: 'none',
+            borderColor: 'transparent',
+            borderRadius: 0,
+            borderWidth: 0,
+            marginBottom: 0
           }}
           controlRef={ref}
         >
           <StyledList>
-            {items.map((item, index) => (
-              <ListboxItem
-                key={item.label}
-                {...item}
-                selected={item.id === selectedId}
-                isChild
-                LinkRouter={LinkRouter}
-                linkRouterProps={linkRouterProps}
-                {...(index === 0 && { prevItemRef })}
-                {...(index === items.length - 1 && { nextItemRef })}
-                {...(index === items.length - 1 && { onBlur: onLastItemBlur })}
-              />
-            ))}
+            {items.map((item, index) => {
+              return (
+                <ListboxItem
+                  key={item.label}
+                  id={item.id ?? item.label}
+                  {...item}
+                  selected={
+                    (item.id && item.id === selectedId) || (item.label && item.label === selectedId)
+                  }
+                  isChild
+                  LinkRouter={LinkRouter}
+                  linkRouterProps={linkRouterProps}
+                  {...(index === 0 && { prevItemRef })}
+                  {...(index === items.length - 1 && { nextItemRef })}
+                  {...(index === items.length - 1 && { onBlur: onLastItemBlur })}
+                />
+              )
+            })}
           </StyledList>
         </ExpandCollapse.Panel>
       </StyledGroupWrapper>

package/src/Listbox/ListboxItem.jsx

@@ -2,9 +2,13 @@
 import React, { forwardRef } from 'react'
 import PropTypes from 'prop-types'
 import styled from 'styled-components'
-import { selectSystemProps, withLinkRouter, useThemeTokens } from '@telus-uds/components-base'
+import {
+  selectSystemProps,
+  withLinkRouter,
+  useThemeTokensCallback,
+  PressableItem
+} from '@telus-uds/components-base'
 import { htmlAttrs } from '../utils'
-import PressableItem from './PressableItem'
 
 const [selectProps, selectedSystemPropTypes] = selectSystemProps([htmlAttrs])
 
@@ -17,36 +21,11 @@ const StyledItemContainer = styled.li({
   }
 })
 
-const getSelectedItemStyles = ({ tokens }) => ({
-  display: tokens.itemDisplay,
-  fontFamily: `${tokens.itemFontName}${tokens.itemFontWeight}normal`,
-  fontSize: tokens.itemFontSize,
-  paddingTop: tokens.itemPaddingTop,
-  paddingBottom: tokens.itemPaddingBottom,
-  paddingLeft: tokens.itemPaddingLeft,
-  paddingRight: tokens.itemPaddingRight,
-  color: tokens.itemColor,
-  textDecoration: tokens.itemTextDecoration,
-  backgroundColor: tokens.itemBackgroundColor,
-  outline: tokens.itemOutline,
-  borderWidth: tokens.itemBorderWidth,
-  width: '100%'
-})
-
-const SelectedItem = styled.div(({ isChild, tokens }) => ({
-  ...getSelectedItemStyles({ tokens }),
-  borderLeft: isChild
-    ? `${tokens.itemBorderLeftWidth}px solid ${tokens.itemBorderLeftColor}`
-    : 'none'
-}))
-
 const ListboxItem = forwardRef(
   (
     {
       href,
       label,
-      onPress,
-      selected = false,
       isChild = false,
       onBlur,
       nextItemRef,
@@ -55,32 +34,32 @@ const ListboxItem = forwardRef(
       variant = {},
       LinkRouter,
       linkRouterProps,
+      id,
+      onPress = () => {},
+
       ...rest
     },
     ref
   ) => {
-    const selectedProps = selectProps(rest)
-    const systemTokens = useThemeTokens('ListBox', tokens, variant, { isChild })
+    const selectedProps = selectProps({ href, ...rest })
 
+    const getTokens = useThemeTokensCallback('Listbox', tokens, variant, { isChild })
     return (
       <StyledItemContainer isChild={isChild} {...selectedProps} role="option">
-        {selected ? (
-          <SelectedItem isChild={isChild} tokens={systemTokens}>
-            {label}
-          </SelectedItem>
-        ) : (
-          <PressableItem
-            href={href}
-            isChild={isChild}
-            onPress={onPress}
-            onBlur={onBlur}
-            nextItemRef={nextItemRef}
-            prevItemRef={prevItemRef}
-            ref={ref}
-          >
-            {label}
-          </PressableItem>
-        )}
+        <PressableItem
+          href={href}
+          isChild={isChild}
+          onPress={onPress}
+          onBlur={onBlur}
+          nextItemRef={nextItemRef}
+          prevItemRef={prevItemRef}
+          ref={ref}
+          tokens={getTokens}
+          selectedProps={selectedProps}
+          id={id}
+        >
+          {label}
+        </PressableItem>
       </StyledItemContainer>
     )
   }
@@ -95,8 +74,7 @@ ListboxItem.propTypes = {
   label: PropTypes.node.isRequired,
   nextItemRef: PropTypes.object,
   prevItemRef: PropTypes.object,
-  onPress: PropTypes.func,
-  selected: PropTypes.bool
+  onPress: PropTypes.func
 }
 
 export default withLinkRouter(ListboxItem)

package/src/Listbox/ListboxOverlay.jsx

@@ -23,7 +23,7 @@ const paddingHorizontal = 0
 
 const DropdownOverlay = forwardRef(
   ({ children, isReady = false, overlaidPosition, maxWidth, minWidth, onLayout }, ref) => {
-    const systemTokens = useThemeTokens('ListBox', {}, {})
+    const systemTokens = useThemeTokens('Listbox', {}, {})
 
     return (
       <WebPortal>

package/src/NavigationBar/NavigationBar.jsx

@@ -198,6 +198,9 @@ NavigationBar.propTypes = {
    * Common navigation bar heading.
    */
   heading: PropTypes.string,
+  /**
+   * Sets the `headingLevel` of the `heading`
+   */
   headingLevel: PropTypes.oneOf(['h1', 'h2', 'h3', 'h4', 'h5', 'h6']),
   /**
    * Matches the `id` property of the item in `items` corresponding to the current page

package/src/OrderedList/Item.jsx

@@ -107,6 +107,9 @@ Item.propTypes = {
    * Item content
    */
   children: PropTypes.node.isRequired,
+  /**
+   * Defines the title of the `OrderedList.Item`
+   */
   title: PropTypes.string,
   /**
    * Item tokens

package/src/Paragraph/Paragraph.jsx

@@ -49,6 +49,9 @@ const Paragraph = ({ children, variant, tokens, testID, align, linesBetween = 1,
 Paragraph.propTypes = {
   ...selectedSystemPropTypes,
   children: PropTypes.node.isRequired,
+  /**
+   * Adds a `data-testid` attribute to the element for testing purposes
+   */
   testID: PropTypes.string,
   /**
    * Sets the alignment style for the paragraph. Same options as Typography's `align` prop.

package/src/PreviewCard/AuthorDate.jsx

@@ -24,7 +24,13 @@ const AuthorDate = ({ author, date }) => {
 }
 
 AuthorDate.propTypes = {
+  /**
+   * Name of the author
+   */
   author: PropTypes.string.isRequired,
+  /**
+   * Date of the post
+   */
   date: PropTypes.string.isRequired
 }
 

package/src/PriceLockup/PriceLockup.jsx

@@ -226,16 +226,53 @@ const PriceLockup = ({
 
 PriceLockup.propTypes = {
   ...selectedSystemPropTypes,
+  /**
+   * Size of the component
+   *
+   * Small for pricing in product catalogue pages, medium for pricing in product comparison cards and large for pricing in banners and promo cards
+   */
   size: PropTypes.oneOf(['small', 'medium', 'large']),
+  /**
+   * If currency symbol other than `$` to be used
+   */
   currencySymbol: PropTypes.string,
+  /**
+   * Shows additional info above the price
+   */
   topText: PropTypes.string,
+  /**
+   * Monetary value (including decimals separated by ".")
+   */
   price: PropTypes.string.isRequired,
+  /**
+   * Shows month/year unit
+   */
   rateText: PropTypes.string,
+  /**
+   * Shows additional info below the price with a `Divider`
+   */
   bottomText: PropTypes.string,
+  /**
+   * Displays which side the currency should apperar (left, right)
+   */
   signDirection: PropTypes.oneOf(['right', 'left']),
+  /**
+   * Shows additional link for context
+   */
   footnoteLinks: PropTypes.arrayOf(PropTypes.oneOfType([PropTypes.number, PropTypes.string])),
+  /**
+   * Function to be called when a footnote link is clicked
+   */
   onClickFootnote: PropTypes.func,
+  /**
+   * To show price savings comparison
+   */
   strikeThrough: PropTypes.bool,
+  /**
+   * To provide a11y text for `PriceLockup` component
+   *
+   * **Note:** a11yText will override strikethrough price, so it must include price (ie. "was 50 dollars per month")
+   */
   a11yText: PropTypes.string
 }
 

package/src/QuantitySelector/QuantitySelector.jsx

@@ -210,25 +210,64 @@ const dictionaryContentShape = PropTypes.shape({
 })
 
 QuantitySelector.propTypes = {
+  /**
+   * The id of the input field
+   */
   id: PropTypes.string,
+  /**
+   * The minimum number allowed
+   */
   minNumber: PropTypes.number,
+  /**
+   * The maximum number allowed
+   */
   maxNumber: PropTypes.number,
+  /**
+   * The callback function that is called when the value of the input field changes
+   */
   onChange: PropTypes.func,
+  /**
+   * The default value of the input field
+   */
   defaultValue: PropTypes.number,
+  /**
+   * The label of the input field
+   */
   label: PropTypes.string,
+  /**
+   * The hint of the input field
+   */
   hint: PropTypes.string,
+  /**
+   * The position of the hint. Could be shown along side the label or below it
+   */
   hintPosition: PropTypes.oneOf(['inline', 'below']),
+  /**
+   * Adds a question mark which will display a tooltip when clicked
+   */
   tooltip: PropTypes.string,
+  /**
+   * The accessibility label of the input field
+   */
   accessibilityLabel: PropTypes.string,
+  /**
+   * The dictionary object containing the content for the input field
+   */
   dictionary: PropTypes.shape({
     en: dictionaryContentShape,
     fr: dictionaryContentShape
   }),
+  /**
+   * The language to use for the copy.
+   */
   copy: PropTypes.oneOfType([PropTypes.oneOf(['en', 'fr'])]),
   variant: PropTypes.exact({
     alternative: PropTypes.bool
   }),
   tokens: PropTypes.oneOf([PropTypes.object, PropTypes.func]),
+  /**
+   * Sets `data-testid` attribute on the input field for testing purposes.
+   */
   testID: PropTypes.string
 }
 

package/src/Span/Span.jsx

@@ -27,6 +27,9 @@ const Span = ({ children, variant, tokens, testID, flex, ...rest }) => {
 Span.propTypes = {
   ...selectedSystemPropTypes,
   children: PropTypes.node.isRequired,
+  /**
+   * Adds `data-testid` attribute for testing
+   */
   testID: PropTypes.string,
   /**
    * Sets display to inline-flex so that children are laid out using the flex model.

package/src/Table/Table.jsx

@@ -87,6 +87,9 @@ const Table = ({ children, fullWidth = true, text = 'medium', tokens, variant, .
 Table.propTypes = {
   ...selectedSystemPropTypes,
   children: PropTypes.node,
+  /**
+   * Sets text style
+   */
   text: PropTypes.oneOf(['medium', 'small'])
 }