@telus-uds/components-base 1.16.0 → 1.18.0

package/src/List/List.jsx

@@ -1,18 +1,16 @@
 import React, { cloneElement, forwardRef, Children } from 'react'
 import { View, Platform } from 'react-native'
 import PropTypes from 'prop-types'
-import {
-  a11yProps,
-  componentPropType,
-  getTokensPropType,
-  selectSystemProps,
-  variantProp,
-  viewProps
-} from '../utils'
-import ListItem from './ListItem'
+import { a11yProps, getTokensPropType, selectSystemProps, variantProp, viewProps } from '../utils'
 
 const [selectProps, selectedSystemPropTypes] = selectSystemProps([a11yProps, viewProps])
 
+const isListItem = (element) => {
+  const elementName = element?.type?.displayName || element?.type?.name
+  // Match our own ListItem, and also, custom list items
+  return Boolean(elementName.match(/Item/))
+}
+
 /**
  * An unordered List component has a child a ListItem that
  * allows icon, dividers and customized typography
@@ -31,9 +29,7 @@ const List = forwardRef(
   ) => {
     const items = Children.map(children, (child, index) => {
       // Pass ListItem-specific props to children (by name so teams can add their own ListItems)
-      const isListItem = (componentName) => Boolean(componentName === ListItem.displayName)
-
-      if (isListItem(child?.type?.displayName) || isListItem(child?.type?.name)) {
+      if (isListItem(child)) {
         return cloneElement(child, {
           showDivider,
           isLastItem: index + 1 === Children.count(children),
@@ -58,7 +54,7 @@ List.propTypes = {
   ...selectedSystemPropTypes,
   tokens: getTokensPropType('List'),
   variant: variantProp.propType,
-  children: componentPropType('ListItem'),
+  children: PropTypes.node,
   /**
    * In case it is not the last item allow display divider
    */

package/src/List/PressableListItemBase.jsx

@@ -9,12 +9,13 @@ import {
   clickProps,
   linkProps,
   hrefAttrsProp,
+  selectTokens,
   withLinkRouter
 } from '../utils'
 
 import ListItemBase from './ListItemBase'
-import ListItemContent, { tokenTypes as contentTokenTypes } from './ListItemContent'
-import ListItemMark, { tokenTypes as markTokenTypes } from './ListItemMark'
+import ListItemContent from './ListItemContent'
+import ListItemMark from './ListItemMark'
 
 const selectPressableStyles = ({
   backgroundColor,
@@ -39,8 +40,10 @@ const PressableListItemBase = forwardRef(
     const { hrefAttrs, rest: listItemProps } = hrefAttrsProp.bundle(props)
     const handlePress = linkProps.handleHref({ href, onPress })
 
+    const listItemTokens = selectTokens('List', typeof tokens === 'function' ? tokens() : tokens)
+
     return (
-      <ListItemBase ref={listItemRef} tokens={tokens()} {...listItemProps}>
+      <ListItemBase ref={listItemRef} tokens={listItemTokens} {...listItemProps}>
         {({ isLastItem }) => {
           const getTokens = (pressableState) =>
             resolvePressableTokens(tokens, pressableState, { last: isLastItem })
@@ -81,18 +84,13 @@ const staticStyles = StyleSheet.create({
   itemContainer: {
     flexDirection: 'row',
     flex: 1
-  },
-  tokens: {
-    ...contentTokenTypes,
-    ...markTokenTypes
   }
 })
 
 PressableListItemBase.propTypes = {
+  ...withLinkRouter.propTypes,
   href: PropTypes.string,
   onPress: PropTypes.func,
-  // TODO - type this better, maybe import the subcomponent token types and run it through util
-  // eslint-disable-next-line react/forbid-prop-types
   tokens: PropTypes.any,
   icon: PropTypes.elementType,
   children: PropTypes.oneOfType([PropTypes.node, PropTypes.func]),

package/src/QuickLinks/QuickLinks.jsx

@@ -0,0 +1,61 @@
+import React, { forwardRef } from 'react'
+import PropTypes from 'prop-types'
+
+import { useThemeTokens } from '../ThemeProvider'
+import { useViewport } from '../ViewportProvider'
+import { getTokensPropType, variantProp } from '../utils'
+
+import List from '../List'
+import StackWrap from '../StackView/StackWrap'
+import QuickLinksCard from './QuickLinksCard'
+
+/**
+ * QuickLinks renders a list of interactive items. How it renders these items depends on theme options:
+ *  - If the theme returns `list` token as true, it renders an ordered list based on List
+ *  - If the theme returns `button` token as true and `list` as false, it renders a wrapping horizontal bar of buttons
+ *  - If the theme returns `card` token as true, it wraps the above with a `Card`.
+ */
+const QuickLinks = forwardRef(
+  ({ tokens, variant, listTokens, cardTokens, children, tag = 'ul', ...rest }, ref) => {
+    const viewport = useViewport()
+    const { dividers, list, card, stackSpace, stackGap, stackJustify } = useThemeTokens(
+      'QuickLinks',
+      tokens,
+      variant,
+      {
+        viewport
+      }
+    )
+
+    const content = (list && (
+      <List ref={ref} tokens={listTokens} showDivider={dividers} tag={tag} {...rest}>
+        {children}
+      </List>
+    )) || (
+      <StackWrap
+        space={stackSpace}
+        gap={stackGap}
+        tokens={{ justifyContent: stackJustify }}
+        tag={tag}
+        {...rest}
+      >
+        {children}
+      </StackWrap>
+    )
+
+    return card ? <QuickLinksCard tokens={cardTokens}>{content}</QuickLinksCard> : content
+  }
+)
+
+QuickLinks.displayName = 'QuickLinks'
+
+QuickLinks.propTypes = {
+  tokens: getTokensPropType('QuickLinks'),
+  cardTokens: getTokensPropType('Card'),
+  listTokens: getTokensPropType('QuickLinksList'),
+  tag: PropTypes.string,
+  variant: variantProp.propType,
+  children: PropTypes.node
+}
+
+export default QuickLinks

package/src/QuickLinks/QuickLinksCard.jsx

@@ -0,0 +1,26 @@
+import React from 'react'
+import PropTypes from 'prop-types'
+
+import { useThemeTokens } from '../ThemeProvider'
+import { getTokensPropType, variantProp } from '../utils'
+import CardBase from '../Card/CardBase'
+
+/**
+ * Private subcomponent for use within QuickLinks.
+ *
+ * Restyled Card with identical behaviour to Card, but themed according to the
+ * QuickLinksCard theme rather than the Card theme.
+ */
+const QuickLinksList = ({ tokens, variant, children }) => {
+  const themeTokens = useThemeTokens('QuickLinksCard', tokens, variant)
+
+  return <CardBase tokens={themeTokens}>{children}</CardBase>
+}
+
+QuickLinksList.propTypes = {
+  tokens: getTokensPropType('QuickLinksCard'),
+  variant: variantProp.propType,
+  children: PropTypes.node
+}
+
+export default QuickLinksList

package/src/QuickLinks/QuickLinksItem.jsx

@@ -0,0 +1,46 @@
+import React, { forwardRef } from 'react'
+import PropTypes from 'prop-types'
+
+import { getTokensPropType, variantProp, withLinkRouter } from '../utils'
+import { useViewport } from '../ViewportProvider'
+import { useThemeTokens, useThemeTokensCallback } from '../ThemeProvider'
+
+import PressableListItemBase from '../List/PressableListItemBase'
+import ButtonBase from '../Button/ButtonBase'
+
+/**
+ * Public component exported as QuickLinks.Item, for use as children of QuickLinks.
+ *
+ * Receives props injected by QuickLinks and renders the appropriate child component.
+ */
+const QuickLinksItem = forwardRef(({ tokens, variant, children, ...rest }, ref) => {
+  const viewport = useViewport()
+  const { list } = useThemeTokens('QuickLinks', tokens, variant, { viewport })
+
+  const themeName = list ? 'QuickLinksList' : 'QuickLinksButton'
+
+  const getTokens = useThemeTokensCallback(themeName, tokens, variant)
+
+  return list ? (
+    <PressableListItemBase ref={ref} tokens={getTokens} {...rest}>
+      {children}
+    </PressableListItemBase>
+  ) : (
+    <ButtonBase ref={ref} tokens={getTokens} {...rest}>
+      {children}
+    </ButtonBase>
+  )
+})
+
+QuickLinksItem.displayName = 'QuickLinksItem'
+
+QuickLinksItem.propTypes = {
+  ...withLinkRouter.propTypes,
+  ...PressableListItemBase.propTypes,
+  ...ButtonBase.propTypes,
+  tokens: getTokensPropType('QuickLinksList', 'QuickLinksButton'),
+  variant: variantProp.propType,
+  children: PropTypes.node
+}
+
+export default withLinkRouter(QuickLinksItem)

package/src/QuickLinks/index.js

@@ -0,0 +1,6 @@
+import QuickLinks from './QuickLinks'
+import QuickLinksItem from './QuickLinksItem'
+
+QuickLinks.Item = QuickLinksItem
+
+export default QuickLinks

package/src/StackView/StackWrap.jsx

@@ -1,14 +1,16 @@
-import React, { forwardRef } from 'react'
+import React, { forwardRef, useState } from 'react'
 import { Platform } from 'react-native'
 
+import useSafeLayoutEffect from '../utils/useSafeLayoutEffect'
 import StackWrapBox from './StackWrapBox'
 import StackWrapGap from './StackWrapGap'
 
 // In Jest/CI/SSR, global CSS isn't always available and doesn't always have .supports method
-const cssSupports = (...args) =>
+const cssSupports = (property, value) =>
+  Platform.OS === 'web' &&
   typeof window !== 'undefined' &&
   typeof window.CSS?.supports === 'function' &&
-  window.CSS.supports(...args)
+  window.CSS.supports(property, value)
 
 // CSS.supports needs an example of the type of value you intend to use.
 // Will be an integer appended `px` after hooks and JSX styles are resolved.
@@ -22,19 +24,24 @@ const exampleGapValue = '1px'
  * If a different spacing is desired between wrapped lines, pass a spacing value to the `gap` prop.
  */
 const StackWrap = forwardRef((props, ref) => {
+  const [canUseCSSGap, setCanUseCSSGap] = useState(false)
   const { space } = props
   // Don't apply separate gap if `null` or `undefined`, so can be unset in Storybook etc
   const gap = props.gap ?? space
-
-  const canUseCSSGap = Platform.OS === 'web' && gap === space && cssSupports('gap', exampleGapValue)
-
-  return canUseCSSGap ? (
-    // If possible, use the cleaner implementation that applies CSS `gap` styles to the container.
-    <StackWrapGap ref={ref} {...props} />
-  ) : (
-    // Else, use the fallback implementation which renders a `Box` component around each child.
-    <StackWrapBox ref={ref} {...props} />
-  )
+  const gapEqualsSpace = gap === space
+
+  // If possible, use the cleaner implementation that applies CSS `gap` styles to the container,
+  // preserving direct parent-child relationships between the container and each item, which
+  // can result in clearer descriptions on some screen readers (e.g. radio "X of Y" on MacOS).
+  // Else, use the fallback implementation which renders a `Box` component around each child.
+  const Component = canUseCSSGap ? StackWrapGap : StackWrapBox
+  // In SSR, the type of implementation must match the server during hydration, but
+  // the server can't know if gap is supported, so never use it until after hydration.
+  useSafeLayoutEffect(() => {
+    setCanUseCSSGap(gapEqualsSpace && cssSupports('gap', exampleGapValue))
+  }, [gapEqualsSpace])
+
+  return <Component ref={ref} {...props} />
 })
 StackWrap.displayName = 'StackWrap'
 

package/src/Timeline/Timeline.jsx

@@ -0,0 +1,148 @@
+import PropTypes from 'prop-types'
+import React, { forwardRef } from 'react'
+import { View } from 'react-native'
+
+import { useThemeTokens } from '../ThemeProvider'
+import {
+  getTokensPropType,
+  variantProp,
+  a11yProps,
+  viewProps,
+  selectSystemProps,
+  getA11yPropsFromHtmlTag,
+  layoutTags
+} from '../utils'
+import { useViewport } from '../ViewportProvider'
+
+const selectDotStyles = ({ dotWidth, timelineColor, dotBorderWidth, dotColor }) => ({
+  width: dotWidth,
+  height: dotWidth,
+  borderRadius: dotWidth / 2,
+  backgroundColor: dotColor,
+  borderWidth: dotBorderWidth,
+  borderColor: timelineColor
+})
+
+const selectConnectorStyles = ({ timelineColor, connectorHeight, connectorWidth }) => ({
+  width: connectorWidth,
+  height: connectorHeight,
+  backgroundColor: timelineColor
+})
+
+const selectTimelineContainerStyle = ({ timelineContainerDirection }) => ({
+  flexDirection: timelineContainerDirection
+})
+
+const selectLineItemStyles = ({
+  lineItemAlign,
+  lineItemDirection,
+  lineItemMarginBottom,
+  lineItemMarginRight
+}) => ({
+  alignItems: lineItemAlign,
+  flexDirection: lineItemDirection,
+  marginBottom: lineItemMarginBottom,
+  marginRight: lineItemMarginRight,
+  overflow: 'hidden'
+})
+
+const selectLineItemContainer = ({ lineItemContainerDirection, lineContainerFlexSize }) => ({
+  flexDirection: lineItemContainerDirection,
+  flex: lineContainerFlexSize
+})
+
+const selectItemContentStyles = (
+  { itemContentFlexSize, itemContentMarginBottom, itemContentMarginRight },
+  isLastChild
+) => {
+  return {
+    flex: itemContentFlexSize,
+    marginBottom: !isLastChild && itemContentMarginBottom,
+    marginRight: !isLastChild && itemContentMarginRight
+  }
+}
+
+const [selectProps, selectedSystemPropTypes] = selectSystemProps([a11yProps, viewProps])
+
+/**
+ * Timeline is a component that displays either a horizontal or vertical list of the
+ * children components passed by props
+ *
+ * ## Component API
+ *
+ * - `horizontal` In order to display the Component list horizontally
+ *
+ *
+ * ## A11y guidelines
+ * Timeline link supports all the common a11y props.
+ */
+const Timeline = forwardRef(
+  (
+    { tokens, variant = {}, children, accessibilityLabel, tag = 'ul', childrenTag = 'li', ...rest },
+    ref
+  ) => {
+    const viewport = useViewport()
+    const themeTokens = useThemeTokens('Timeline', tokens, variant, { viewport })
+
+    const containerProps = {
+      ...selectProps(rest),
+      ...getA11yPropsFromHtmlTag(tag, rest.accessibilityRole || 'list'),
+      accessibilityLabel
+    }
+
+    return (
+      <View {...containerProps} ref={ref} style={selectTimelineContainerStyle(themeTokens)}>
+        {children.map((child, index) => {
+          const childrenProps = {
+            ...getA11yPropsFromHtmlTag(childrenTag, child?.props?.accessibilityRole || 'listitem')
+          }
+
+          return (
+            <View
+              style={selectLineItemContainer(themeTokens)}
+              // eslint-disable-next-line react/no-array-index-key
+              key={`timeline-${index}-${child.displayName}`}
+              {...childrenProps}
+            >
+              <View style={selectLineItemStyles(themeTokens)}>
+                <View style={selectDotStyles(themeTokens)} />
+                <View style={selectConnectorStyles(themeTokens)} />
+              </View>
+              <View style={selectItemContentStyles(themeTokens, index + 1 === children.length)}>
+                {child}
+              </View>
+            </View>
+          )
+        })}
+      </View>
+    )
+  }
+)
+
+Timeline.displayName = 'Timeline'
+
+Timeline.propTypes = {
+  ...selectedSystemPropTypes,
+  tokens: getTokensPropType('Timeline'),
+  variant: variantProp.propType,
+  /**
+   * A list of components that will be rendered either horizontally or vertically
+   */
+  children: PropTypes.arrayOf(PropTypes.node).isRequired,
+  /**
+   * A required accessibility label that needs to be passed to be used on List
+   * which is applied as normal for a React Native accessibilityLabel prop.
+   */
+  accessibilityLabel: PropTypes.string.isRequired,
+  /**
+   * Sets the HTML tag of the outer container and the children. By default `'li'` for the children
+   * and `'ul'` for the container
+   *
+   * If either `tag` or `childrenTag` is overridden, the other should be too, to avoid producing invalid HTML.
+   *
+   */
+  tag: PropTypes.oneOf(layoutTags),
+  childrenTag: PropTypes.oneOf(layoutTags)
+}
+
+export default Timeline

package/src/Timeline/index.js

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

package/src/ViewportProvider/useViewportListener.js

@@ -1,28 +1,20 @@
-import { useLayoutEffect } from 'react'
 import { Dimensions } from 'react-native'
 import { viewports } from '@telus-uds/system-constants'
 
+import useSafeLayoutEffect from '../utils/useSafeLayoutEffect'
+
 // Use Dimensions instead of useWindowDimensions because useWindowDimensions forces context
 // to update on every pixel change during window resize; but we only want rerenders to occur
 // when a viewport threshold has been crossed.
 const lookupViewport = () => viewports.select(Dimensions.get('window').width)
 
-/**
- * In SSR, React gets spooked if it sees `useLayoutEffect` and fires warnings assuming the
- * developer doesn't realise the effect won't run: https://reactjs.org/link/uselayouteffect-ssr
- *
- * To avoid these warnings while still conforming to the rules of hooks, always use this
- * explicitly no-op hook, instead of the useLayoutEffect that is implicitly no-op on SSR.
- */
-const useViewportListenerSSR = () => {}
-
 /**
  * When client-side rendering, immediately set the viewport to the correct value as a layout effect so
  * if the viewport isn't the smallest, any SSR-rendered components rerender correctly before anything
  * is shown to the user. Then bind events to update the viewport if it changes.
  */
-const useViewportListenerCSR = (setViewport) => {
-  useLayoutEffect(() => {
+const useViewportListener = (setViewport) => {
+  useSafeLayoutEffect(() => {
     setViewport(lookupViewport())
 
     const onChange = ({ window }) => setViewport(viewports.select(window.width))
@@ -41,8 +33,4 @@ const useViewportListenerCSR = (setViewport) => {
   }, [setViewport])
 }
 
-// Window is a defined global object in both Web and Native client-side, and undefined in SSR
-const isSSR = typeof window === 'undefined'
-const useViewportListener = isSSR ? useViewportListenerSSR : useViewportListenerCSR
-
 export default useViewportListener

package/src/index.js

@@ -24,6 +24,7 @@ export { default as Modal } from './Modal'
 export { default as Notification } from './Notification'
 export { default as Pagination } from './Pagination'
 export { default as Progress } from './Progress'
+export { default as QuickLinks } from './QuickLinks'
 export { default as Radio } from './Radio'
 export * from './Radio'
 export { default as RadioCard } from './RadioCard'
@@ -40,6 +41,7 @@ export { default as StepTracker } from './StepTracker'
 export { default as Tabs } from './Tabs'
 export { default as Tags } from './Tags'
 export * from './TextInput'
+export { default as Timeline } from './Timeline'
 export * from './ToggleSwitch'
 export { default as Tooltip } from './Tooltip'
 export { default as TooltipButton } from './TooltipButton'
@@ -60,3 +62,4 @@ export {
 } from './ThemeProvider'
 
 export * from './utils'
+export { Portal } from '@gorhom/portal'

package/src/utils/animation/useVerticalExpandAnimation.js

@@ -1,6 +1,8 @@
-import { useEffect, useLayoutEffect, useRef, useState } from 'react'
+import { useEffect, useRef, useState } from 'react'
 import { Animated, Easing, Platform } from 'react-native'
 
+import useSafeLayoutEffect from '../useSafeLayoutEffect'
+
 // TODO: systematise animations
 // https://github.com/telus/universal-design-system/issues/487
 function useVerticalExpandAnimation({ containerHeight, isExpanded, tokens }) {
@@ -13,7 +15,7 @@ function useVerticalExpandAnimation({ containerHeight, isExpanded, tokens }) {
 
   const { expandDuration, collapseDuration } = tokens
 
-  useLayoutEffect(() => {
+  useSafeLayoutEffect(() => {
     if (expandStateChanged) {
       setIsAnimating(true)
       setWasExpanded(isExpanded)

package/src/utils/index.js

@@ -10,6 +10,7 @@ export { default as useCopy } from './useCopy'
 export { default as useHash } from './useHash'
 export { default as useSpacingScale } from './useSpacingScale'
 export { default as useResponsiveProp } from './useResponsiveProp'
+export { default as useSafeLayoutEffect } from './useSafeLayoutEffect'
 export { default as useScrollBlocking } from './useScrollBlocking'
 export * from './useResponsiveProp'
 export { default as useUniqueId } from './useUniqueId'

package/src/utils/useSafeLayoutEffect.js

@@ -0,0 +1,31 @@
+import { useLayoutEffect, useCallback } from 'react'
+import { useHydrationContext } from '../BaseProvider/HydrationContext'
+
+const isSSR = typeof window === 'undefined'
+const noop = () => {}
+
+/**
+ * useSafeLayoutEffect is a alternative to useLayoutEffect that avoids SSR hydration problems:
+ *  - In a client-side render, it uses useLayoutEffect to avoid flashing the pre-render UI to the user.
+ *  - During hydration from SSR, the provided function is skipped to avoid mismatches from server content.
+ *  - In SSR, it is a no-op function to avoid warnings about using useLayoutEffect in SSR
+ */
+const useSafeLayoutEffect = isSSR
+  ? noop // avoid React's fussy warnings by ensuring to never call useLayoutEffect on server
+  : (fn, deps = []) => {
+      const isHydrating = useHydrationContext()
+
+      // Callback updates and effect re-runs when deps array content changes, like useEffect.
+      /* eslint-disable-next-line react-hooks/exhaustive-deps */
+      const callback = useCallback(fn, deps)
+
+      useLayoutEffect(() => {
+        // Do nothing before hydrating server-generated content, like useEffect. When hydration completes,
+        // useHydrationContext provides false, re-rendering this hook and re-running the effect.
+        if (isHydrating) return noop
+        // If there's no hydration in progress, behave like useLayoutEffect.
+        return callback()
+      }, [isHydrating, callback])
+    }
+
+export default useSafeLayoutEffect