@telus-uds/components-base 0.0.2-prerelease.9 → 1.0.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,6 +10,8 @@ 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'

package/src/utils/a11y/index.js

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

package/src/utils/a11y/semantics.js

@@ -0,0 +1,162 @@
+import { Platform } from 'react-native'
+/**
+ * @typedef {import('react-native').AccessibilityRole} AccessibilityRole
+ */
+
+/**
+ * This is based on the role-to-tag mapping that React Native Web uses to set HTML tags.
+ * It's not exported in any way from RNW, so we need to keep this up-to-date manually.
+ * https://github.com/necolas/react-native-web/blob/master/packages/react-native-web/src/modules/AccessibilityUtil/propsToAccessibilityComponent.js
+ *
+ * Note: every role in this list is a web-only aria-role. There is no overlap between _these_ web tags
+ * or roles and native accessibilityRoles. Only h1, h2, h3 etc map to an RN equivalent ("heading").
+ *
+ * - RN "summary" native role maps to "region" aria-role, but setting `<section>`/"region" does not
+ *   set React Native's "summary" role, which has a much narrower use case.
+ * - `<Header>`/"Banner" also do not map to RN's "heading". Only h1 / h2 etc map to RN "heading".
+ *
+ * Therefore, all of these tags / roles default to no accessibilityRole in native apps. This is not wrong:
+ * in general, RN accessibilityRoles tend to be more about interaction and less about semantics than web roles.
+ *
+ * RNW's one-way mapping of React Native accessibilityRoles to web aria-roles:
+ * https://github.com/necolas/react-native-web/blob/master/packages/react-native-web/src/modules/AccessibilityUtil/propsToAriaRole.js
+ */
+// Adding `/** @type {const} */ ({...})` denotes object content as `readonly` in many IDEs
+// eslint-disable-next-line prettier/prettier
+const rolesToTags = /** @type {const} */ ({
+  article: 'article',
+  banner: 'header',
+  blockquote: 'blockquote',
+  code: 'code',
+  complementary: 'aside',
+  contentinfo: 'footer',
+  deletion: 'del',
+  emphasis: 'em',
+  figure: 'figure',
+  insertion: 'ins',
+  form: 'form',
+  list: 'ul',
+  listitem: 'li',
+  main: 'main',
+  navigation: 'nav',
+  region: 'section',
+  strong: 'strong',
+
+  // Add special cases that are in RNW's function logic but not in its mapping object
+  label: 'label'
+  // eslint-disable-next-line prettier/prettier
+})
+
+// Invert React Native Web's mapping, so a tag gets the role that gets that tag
+export const tagsToRoles = Object.fromEntries(
+  Object.entries(rolesToTags).map(([key, value]) => [value, key])
+)
+
+/**
+ * Heading HTML tags map to the "heading" accessibilityRole in native apps, which is similar
+ * to headings on web but without the expectation of a hierarchy of headings within one screen.
+ */
+// eslint-disable-next-line prettier/prettier
+export const headingTags = /** @type {const} */ (['h1', 'h2', 'h3', 'h4', 'h5', 'h6'])
+/**
+ * @typedef {typeof headingTags[number]} HeadingTag
+ */
+
+/**
+ * All HTML tags that may be set via RNW accesibility props alone and therefore may be set using
+ * the getA11yPropsFromHtmlTag function without changing other behaviour.
+ *
+ * Of these, only headers (h1, h2, ...h5, h6) set a corresponding accessibilityRole in native apps ("heading").
+ */
+export const supportedTags = [...Object.keys(tagsToRoles), ...headingTags]
+/**
+ * Uses readonly mapping keys/values to generate static types for IDEs that support TS in JSDoc.
+ * @typedef {keyof rolesToTags} RoleWithTag
+ * @typedef {typeof rolesToTags[RoleWithTag] | typeof headingTags[number]} SupportedTag
+ */
+
+/**
+ * Subset of supported HTML tags that may be used with layout containers like Box.
+ *
+ * Of these, only headers (h1, h2, ...h5, h6) set a corresponding accessibilityRole in native apps ("heading").
+ */
+// eslint-disable-next-line prettier/prettier
+export const layoutTags = /** @type {const} */ ([
+  ...headingTags,
+  'article',
+  'aside',
+  'blockquote',
+  'footer',
+  'figure',
+  'form',
+  'header',
+  'ul',
+  'li',
+  'main',
+  'nav',
+  'section',
+  'label'
+  // eslint-disable-next-line prettier/prettier
+])
+/**
+ * @typedef {typeof layoutTags[number]} LayoutTag
+ */
+
+/**
+ * Subset of supported HTML tags that may be used with text elements like Typography.
+ *
+ * Of these, only headers (h1, h2, ...h5, h6) set a corresponding accessibilityRole in native apps ("heading").
+ */
+// eslint-disable-next-line prettier/prettier
+export const textTags = /** @type {const} */ ([
+  ...headingTags,
+  'blockquote',
+  'code',
+  'del',
+  'em',
+  'ins',
+  'li',
+  'strong',
+  'label'
+  // eslint-disable-next-line prettier/prettier
+])
+/**
+ * @typedef {typeof layoutTags[number]} TextTag
+ */
+
+/**
+ * If passed a heading tag string like 'h1', 'h2' etc, returns the heading number as a number
+ * ready for use in `accessibilityLevel` props and similar.
+ *
+ * @param {string} [tag] - HTML tag string; returns undefined if not a {@link HeadingTag}
+ * @returns {'1' | '2' | '3' | '4' | '5' | '6' | undefined}
+ */
+export const getHeadingLevel = (tag) => (headingTags.includes(tag) ? Number(tag[1]) : undefined)
+
+/**
+ * Takes a supported HTML tag, and returns the accessibility props that, on web, make React Native Web
+ * render that tag.
+ *
+ * For cross-platform apps, a second argument may be passed with an [accessibilityRole](https://reactnative.dev/docs/accessibility#accessibilityrole)
+ * to use in native apps. Heading tags (h1, h2, ...h5, h6) map to "heading" role by default;
+ * no other supported semantic HTML tags have an equivalent native accessibilityRole.
+ *
+ * @param {SupportedTag} tag - HTML tag to use on web
+ * @param {AccessibilityRole | null} [nativeRole] - optional accessibilityRole for native apps
+ * @returns {{ accessibilityRole: string, accessibilityLevel?: string } | undefined}
+ */
+export const getA11yPropsFromHtmlTag = (tag, nativeRole) => {
+  // Allow cross-platform apps to set accessibilityRoles alongside a web tag without conflict
+  if (nativeRole !== undefined && Platform.OS !== 'web') return { accessibilityRole: nativeRole }
+
+  if (tag) {
+    const accessibilityRole = tagsToRoles[tag]
+    if (accessibilityRole) return { accessibilityRole }
+
+    const accessibilityLevel = getHeadingLevel(tag)
+    if (accessibilityLevel) return { accessibilityRole: 'header', accessibilityLevel }
+  }
+  // If nothing matches or no tag supplied, return undefined and let component decide how to fall back.
+  // Note that return value may always be spread in objects (it is safe to spread undefined like { ...undefined })
+  return undefined
+}