@telus-uds/components-base 0.0.2-prerelease.9 → 1.1.0

package/src/Tooltip/Tooltip.jsx

@@ -1,4 +1,4 @@
-import React, { useEffect, useRef, useState } from 'react'
+import React, { forwardRef, useEffect, useRef, useState } from 'react'
 import { Dimensions, Platform, Pressable, StyleSheet, Text, View } from 'react-native'
 
 import PropTypes from 'prop-types'
@@ -99,157 +99,161 @@ const defaultControl = (pressableState, variant) => (
  * - You may use one when the information is useful only to a small percentage of users (ie. tech savvy people wouldn't need this info).
  * - Tooltips may also be useful when vertical space is an issue.
  */
-const Tooltip = ({ children, content, position = 'auto', copy = 'en', tokens, variant }) => {
-  const [isOpen, setIsOpen] = useState(false)
+const Tooltip = forwardRef(
+  ({ children, content, position = 'auto', copy = 'en', tokens, variant }, ref) => {
+    const [isOpen, setIsOpen] = useState(false)
 
-  const controlRef = useRef()
-  const [controlLayout, setControlLayout] = useState(null)
-  const [tooltipDimensions, setTooltipDimensions] = useState(null)
-  const [windowDimensions, setWindowDimensions] = useState(Dimensions.get('window'))
-  const [tooltipPosition, setTooltipPosition] = useState(null)
+    const controlRef = useRef()
+    const [controlLayout, setControlLayout] = useState(null)
+    const [tooltipDimensions, setTooltipDimensions] = useState(null)
+    const [windowDimensions, setWindowDimensions] = useState(Dimensions.get('window'))
+    const [tooltipPosition, setTooltipPosition] = useState(null)
 
-  const getCopy = useCopy({ dictionary, copy })
-  const themeTokens = useThemeTokens('Tooltip', tokens, variant)
+    const getCopy = useCopy({ dictionary, copy })
+    const themeTokens = useThemeTokens('Tooltip', tokens, variant)
 
-  const { arrowWidth, arrowOffset } = themeTokens
+    const { arrowWidth, arrowOffset } = themeTokens
 
-  useEffect(() => {
-    const subscription = Dimensions.addEventListener('change', ({ window }) => {
-      setWindowDimensions(window)
-    })
+    useEffect(() => {
+      const subscription = Dimensions.addEventListener('change', ({ window }) => {
+        setWindowDimensions(window)
+      })
 
-    return () => subscription?.remove()
-  })
+      return () => subscription?.remove()
+    })
 
-  const toggleIsOpen = () => setIsOpen(!isOpen)
-  const close = () => setIsOpen(false)
+    const toggleIsOpen = () => setIsOpen(!isOpen)
+    const close = () => setIsOpen(false)
 
-  const getPressableState = ({ pressed, hovered, focused }) => ({
-    pressed,
-    hover: hovered,
-    focus: focused
-  })
+    const getPressableState = ({ pressed, hovered, focused }) => ({
+      pressed,
+      hover: hovered,
+      focus: focused
+    })
 
-  const onTooltipLayout = ({
-    nativeEvent: {
-      layout: { width, height }
-    }
-  }) => {
-    if (
-      tooltipDimensions === null ||
-      tooltipDimensions.width !== width ||
-      tooltipDimensions.height !== height
-    ) {
-      setTooltipDimensions({
-        width: Platform.select({
-          web: width + 0.3, // avoids often unnecessary line breaks due to subpixel rendering of fonts
-          native: width
-        }),
-        height
-      })
+    const onTooltipLayout = ({
+      nativeEvent: {
+        layout: { width, height }
+      }
+    }) => {
+      if (
+        tooltipDimensions === null ||
+        tooltipDimensions.width !== width ||
+        tooltipDimensions.height !== height
+      ) {
+        setTooltipDimensions({
+          width: Platform.select({
+            web: width + 0.3, // avoids often unnecessary line breaks due to subpixel rendering of fonts
+            native: width
+          }),
+          height
+        })
+      }
     }
-  }
 
-  useEffect(() => {
-    if (isOpen) {
-      controlRef.current.measureInWindow((x, y, width, height) => {
-        setControlLayout({ x, y, width, height })
-      })
-    } else {
-      setControlLayout(null)
-      setTooltipDimensions(null)
-      setTooltipPosition(null)
-    }
-  }, [isOpen])
+    useEffect(() => {
+      if (isOpen) {
+        controlRef.current.measureInWindow((x, y, width, height) => {
+          setControlLayout({ x, y, width, height })
+        })
+      } else {
+        setControlLayout(null)
+        setTooltipDimensions(null)
+        setTooltipPosition(null)
+      }
+    }, [isOpen])
 
-  useEffect(() => {
-    setIsOpen(false)
-  }, [windowDimensions])
+    useEffect(() => {
+      setIsOpen(false)
+    }, [windowDimensions])
 
-  useEffect(() => {
-    if (
-      (tooltipPosition !== null && !tooltipPosition?.isNormalized) ||
-      !isOpen ||
-      controlLayout === null ||
-      tooltipDimensions == null
-    ) {
-      return
-    }
+    useEffect(() => {
+      if (
+        (tooltipPosition !== null && !tooltipPosition?.isNormalized) ||
+        !isOpen ||
+        controlLayout === null ||
+        tooltipDimensions == null
+      ) {
+        return
+      }
 
-    const updatedPosition = getTooltipPosition(position, {
-      controlLayout,
+      const updatedPosition = getTooltipPosition(position, {
+        controlLayout,
+        tooltipDimensions,
+        windowDimensions,
+        arrowWidth,
+        arrowOffset
+      })
+
+      // avoid ending up in an infinite normalization loop
+      if (tooltipPosition?.isNormalized && updatedPosition.isNormalized) {
+        return
+      }
+
+      setTooltipPosition(updatedPosition)
+    }, [
+      isOpen,
+      position,
       tooltipDimensions,
+      controlLayout,
       windowDimensions,
       arrowWidth,
-      arrowOffset
-    })
+      arrowOffset,
+      tooltipPosition
+    ])
 
-    // avoid ending up in an infinite normalization loop
-    if (tooltipPosition?.isNormalized && updatedPosition.isNormalized) {
-      return
-    }
+    const control = children !== undefined ? children : defaultControl
+    const pressableStyles =
+      control === defaultControl ? Platform.select({ web: { outline: 'none' } }) : undefined
+    const pressableHitSlop =
+      control === defaultControl ? { top: 10, bottom: 10, left: 10, right: 10 } : undefined
 
-    setTooltipPosition(updatedPosition)
-  }, [
-    isOpen,
-    position,
-    tooltipDimensions,
-    controlLayout,
-    windowDimensions,
-    arrowWidth,
-    arrowOffset,
-    tooltipPosition
-  ])
-
-  const control = children !== undefined ? children : defaultControl
-  const pressableStyles =
-    control === defaultControl ? Platform.select({ web: { outline: 'none' } }) : undefined
-  const pressableHitSlop =
-    control === defaultControl ? { top: 10, bottom: 10, left: 10, right: 10 } : undefined
-
-  return (
-    <View style={staticStyles.container}>
-      <Pressable
-        onPress={toggleIsOpen}
-        ref={controlRef}
-        onBlur={close}
-        style={pressableStyles}
-        hitSlop={pressableHitSlop}
-        accessibilityLabel={getCopy('a11yText')}
-        accessibilityRole="button"
-      >
-        {typeof control === 'function'
-          ? (pressableState) => control(getPressableState(pressableState), variant)
-          : control}
-      </Pressable>
-      {isOpen && (
-        <Backdrop onPress={close}>
-          <View
-            style={[
-              staticStyles.tooltip,
-              selectTooltipShadowStyles(themeTokens), // applied separately so that it doesn't cover the arrow
-              tooltipPosition && selectTooltipPositionStyles(tooltipPosition),
-              (tooltipPosition === null || tooltipPosition?.isNormalized) &&
-                staticStyles.tooltipHidden // visually hide the tooltip until we have a final measurement
-            ]}
-            onLayout={onTooltipLayout}
-            accessibilityRole="alert"
-          >
+    return (
+      <View style={staticStyles.container}>
+        <Pressable
+          onPress={toggleIsOpen}
+          ref={controlRef}
+          onBlur={close}
+          style={pressableStyles}
+          hitSlop={pressableHitSlop}
+          accessibilityLabel={getCopy('a11yText')}
+          accessibilityRole="button"
+        >
+          {typeof control === 'function'
+            ? (pressableState) => control(getPressableState(pressableState), variant)
+            : control}
+        </Pressable>
+        {isOpen && (
+          <Backdrop onPress={close}>
             <View
+              ref={ref}
               style={[
-                staticStyles.arrow,
-                tooltipPosition && selectArrowStyles(themeTokens, tooltipPosition)
+                staticStyles.tooltip,
+                selectTooltipShadowStyles(themeTokens), // applied separately so that it doesn't cover the arrow
+                tooltipPosition && selectTooltipPositionStyles(tooltipPosition),
+                (tooltipPosition === null || tooltipPosition?.isNormalized) &&
+                  staticStyles.tooltipHidden // visually hide the tooltip until we have a final measurement
               ]}
-            />
-            <View style={selectTooltipStyles(themeTokens)}>
-              <Text style={selectTextStyles(themeTokens)}>{content}</Text>
+              onLayout={onTooltipLayout}
+              accessibilityRole="alert"
+            >
+              <View
+                style={[
+                  staticStyles.arrow,
+                  tooltipPosition && selectArrowStyles(themeTokens, tooltipPosition)
+                ]}
+              />
+              <View style={selectTooltipStyles(themeTokens)}>
+                <Text style={selectTextStyles(themeTokens)}>{content}</Text>
+              </View>
             </View>
-          </View>
-        </Backdrop>
-      )}
-    </View>
-  )
-}
+          </Backdrop>
+        )}
+      </View>
+    )
+  }
+)
+Tooltip.displayName = 'Tooltip'
 
 Tooltip.propTypes = {
   /**

package/src/Typography/Typography.jsx

@@ -1,20 +1,22 @@
-import React from 'react'
+import React, { forwardRef } from 'react'
 import PropTypes from 'prop-types'
 import { Text, View } from 'react-native'
 
 import { useThemeTokens } from '../ThemeProvider'
 import { useViewport } from '../ViewportProvider'
 import { applyTextStyles } from '../ThemeProvider/utils'
-import { a11yProps, variantProp, getTokensPropType, getMaxFontMultiplier } from '../utils'
-
+import {
+  a11yProps,
+  variantProp,
+  getTokensPropType,
+  getMaxFontMultiplier,
+  headingTags,
+  textTags,
+  getA11yPropsFromHtmlTag
+} from '../utils'
 /**
- * If passed a string like 'h1', 'h2' etc, returns the heading number as a string,
- * else returns false
+ * @typedef {import('../utils/a11y/semantics').TextTag} TextTag
  */
-function getHeadingLevel(heading) {
-  const match = typeof heading === 'string' && heading.match(/^h(\d)$/)
-  return match && match[1]
-}
 
 const selectTextStyles = ({
   fontWeight,
@@ -38,50 +40,71 @@ const selectTextStyles = ({
   })
 
 // General-purpose flexible theme-neutral base component for text
-const Typography = ({
-  children,
-  variant,
-  heading,
-  block = false,
-  align = undefined,
-  accessibilityRole = heading ? 'header' : 'text',
-  tokens,
-  ...rest
-}) => {
-  const viewport = useViewport()
-  const themeTokens = useThemeTokens('Typography', tokens, variant, { viewport })
-  const textProps = {
-    style: selectTextStyles(align ? { ...themeTokens, textAlign: align } : themeTokens),
-    maxFontSizeMultiplier: getMaxFontMultiplier(themeTokens)
-  }
+const Typography = forwardRef(
+  (
+    {
+      children,
+      variant,
+      heading,
+      tag = typeof heading === 'string' ? heading : undefined,
+      accessibilityRole = heading === true ? 'header' : undefined,
+      block = false,
+      align = undefined,
+      tokens,
+      dataSet,
+      ...rest
+    },
+    ref
+  ) => {
+    const viewport = useViewport()
+    const themeTokens = useThemeTokens('Typography', tokens, variant, { viewport })
+    const textProps = {
+      style: selectTextStyles(align ? { ...themeTokens, textAlign: align } : themeTokens),
+      dataSet,
+      maxFontSizeMultiplier: getMaxFontMultiplier(themeTokens)
+    }
 
-  const headingLevel = getHeadingLevel(heading)
-  const a11y = {
-    ...a11yProps.select(rest),
-    accessibilityRole,
-    // On React Native Web, `accessibilityLevel` controls which heading tag (h1, h2 etc) is used.
-    ...(headingLevel && { accessibilityLevel: headingLevel })
-  }
+    const a11y = {
+      ...getA11yPropsFromHtmlTag(tag, accessibilityRole),
+      ...a11yProps.select(rest)
+    }
 
-  return block ? (
-    <View {...a11y}>
-      <Text {...textProps}>{children}</Text>
-    </View>
-  ) : (
-    <Text {...textProps} {...a11y}>
-      {children}
-    </Text>
-  )
-}
+    return block ? (
+      <View ref={ref} {...a11y}>
+        <Text {...textProps}>{children}</Text>
+      </View>
+    ) : (
+      <Text ref={ref} {...textProps} {...a11y}>
+        {children}
+      </Text>
+    )
+  }
+)
+Typography.displayName = 'Typography'
 
 Typography.propTypes = {
   ...a11yProps.types,
   tokens: getTokensPropType('Typography'),
   variant: variantProp.propType,
   /**
-   * If truthy, will render a heading; if a html heading tag is provided, uses that tag on Web
+   * Renders the text as a semantic heading. If a html heading tag is provided, uses that tag on Web.
+   *
+   * Does not affect styling: <Typography heading="h2"> will render a <h2> that looks like plain text.
+   * Use both `heading` and `variant` props to render semantic headings that look like headings.
+   *
+   * In native apps, if this is `true` or any html heading tag string and accessibilityRole prop
+   * is not defined, the accessibilityRole will default to "heading".
+   */
+  heading: PropTypes.oneOf([...headingTags, true]),
+  /**
+   * Optional semantic HTML tag, to apply to the text on web. Does not change styling.
+   *
+   * `tag` and `heading` props set the same thing, so shouldn't be used together (`tag` overrides `heading`).
+   *
+   * In native apps, if a header tag is provided ("h1", "h2" etc) and accessibilityRole prop
+   * is not defined, the accessibilityRole will default to "heading".
    */
-  heading: PropTypes.oneOf([true, 'h1', 'h2', 'h3', 'h4', 'h5', 'h6']),
+  tag: PropTypes.oneOf(textTags),
   /**
    * If true, forces the element to behave as a View block even if nested in other text
    */

package/src/index.js

@@ -10,12 +10,14 @@ export { default as ExpandCollapse, Accordion } from './ExpandCollapse'
 export { default as Feedback } from './Feedback'
 export { default as Fieldset } from './Fieldset'
 export { default as FlexGrid } from './FlexGrid'
+export { default as HorizontalScroll } from './HorizontalScroll'
+export * from './HorizontalScroll'
 export { default as Icon } from './Icon'
 export * from './Icon'
 export { default as IconButton } from './IconButton'
 export { default as InputLabel } from './InputLabel'
 export * from './Link'
-export { default as List } from './List'
+export { default as List, ListItem, ListBase } from './List'
 export { default as Modal } from './Modal'
 export { default as Notification } from './Notification'
 export { default as Pagination } from './Pagination'

package/src/utils/a11y/index.js

@@ -1 +1,2 @@
 export * from './textSize'
+export * from './semantics'

package/src/utils/a11y/propTypes.js

@@ -0,0 +1,61 @@
+import PropTypes from 'prop-types'
+
+import nativePropTypes from './propTypes.native'
+
+export default {
+  ...nativePropTypes,
+  // React Native Web adds many a11y props that alias aria-* attributes
+  // Types based on https://necolas.github.io/react-native-web/docs/accessibility/
+  accessibilityActiveDescendant: PropTypes.string,
+  accessibilityAtomic: PropTypes.bool,
+  accessibilityAutoComplete: PropTypes.string,
+  accessibilityBusy: PropTypes.bool,
+  accessibilityChecked: PropTypes.oneOf([true, false, 'mixed']),
+  accessibilityColumnCount: PropTypes.number,
+  accessibilityColumnIndex: PropTypes.number,
+  accessibilityColumnSpan: PropTypes.number,
+  accessibilityControls: PropTypes.oneOfType([
+    PropTypes.string,
+    PropTypes.arrayOf(PropTypes.string)
+  ]),
+  accessibilityCurrent: PropTypes.oneOf([true, false, 'page', 'step', 'location', 'date', 'time']),
+  accessibilityDescribedBy: PropTypes.oneOfType([
+    PropTypes.string,
+    PropTypes.arrayOf(PropTypes.string)
+  ]),
+  accessibilityDetails: PropTypes.string,
+  accessibilityDisabled: PropTypes.bool,
+  accessibilityErrorMessage: PropTypes.string,
+  accessibilityExpanded: PropTypes.bool,
+  accessibilityFlowTo: PropTypes.oneOfType([PropTypes.string, PropTypes.arrayOf(PropTypes.string)]),
+  accessibilityHasPopup: PropTypes.string,
+  accessibilityHidden: PropTypes.bool,
+  accessibilityInvalid: PropTypes.bool,
+  accessibilityKeyShortcuts: PropTypes.string,
+  accessibilityLabelledBy: PropTypes.oneOfType([
+    PropTypes.string,
+    PropTypes.arrayOf(PropTypes.string)
+  ]),
+  accessibilityLevel: PropTypes.number,
+  accessibilityModal: PropTypes.bool,
+  accessibilityMultiline: PropTypes.bool,
+  accessibilityMultiSelectable: PropTypes.bool,
+  accessibilityOrientation: PropTypes.oneOf(['horizontal', 'vertical']),
+  accessibilityOwns: PropTypes.oneOfType([PropTypes.string, PropTypes.arrayOf(PropTypes.string)]),
+  accessibilityPlaceholder: PropTypes.string,
+  accessibilityPosInSet: PropTypes.number,
+  accessibilityPressed: PropTypes.bool,
+  accessibilityReadOnly: PropTypes.bool,
+  accessibilityRequired: PropTypes.bool,
+  accessibilityRoleDescription: PropTypes.string,
+  accessibilityRowCount: PropTypes.number,
+  accessibilityRowIndex: PropTypes.number,
+  accessibilityRowSpan: PropTypes.number,
+  accessibilitySelected: PropTypes.bool,
+  accessibilitySetSize: PropTypes.number,
+  accessibilitySort: PropTypes.oneOf(['ascending', 'descending', 'none', 'other']),
+  accessibilityValueMax: PropTypes.number,
+  accessibilityValueMin: PropTypes.number,
+  accessibilityValueNow: PropTypes.number,
+  accessibilityValueText: PropTypes.string
+}

package/src/utils/a11y/propTypes.native.js

@@ -0,0 +1,39 @@
+import PropTypes from 'prop-types'
+
+// React Native exports a11y prop definitions as TypeScript Interfaces, but no longer exports PropTypes
+// so we have to define them ourselves.
+export default {
+  accessible: PropTypes.bool,
+  focusable: PropTypes.bool,
+
+  accessibilityElementsHidden: PropTypes.bool,
+  accessibilityHint: PropTypes.string, // react-native-web ignores `accessibilityHint`
+  accessibilityIgnoresInvertColors: PropTypes.bool,
+  accessibilityLabel: PropTypes.string,
+  accessibilityRole: PropTypes.string,
+  accessibilityActions: PropTypes.arrayOf(
+    PropTypes.shape({
+      name: PropTypes.string.isRequired,
+      label: PropTypes.string
+    })
+  ),
+  accessibilityLiveRegion: PropTypes.oneOf(['none', 'polite', 'assertive']),
+  accessibilityState: PropTypes.shape({
+    disabled: PropTypes.bool,
+    selected: PropTypes.bool,
+    checked: PropTypes.oneOf([true, false, 'mixed']),
+    busy: PropTypes.bool,
+    expanded: PropTypes.bool
+  }),
+  accessibilityValue: PropTypes.shape({
+    min: PropTypes.number,
+    max: PropTypes.number,
+    now: PropTypes.number,
+    text: PropTypes.string
+  }),
+  accessibilityViewIsModal: PropTypes.bool,
+  importantForAccessibility: PropTypes.oneOf(['auto', 'yes', 'no', 'no-hide-descendants']),
+  onAccessibilityAction: PropTypes.func,
+  onAccessibilityEscape: PropTypes.func,
+  onAccessibilityTap: PropTypes.func
+}