@telus-uds/components-base 0.0.2-prerelease.4 → 0.0.2-prerelease.8

package/src/Tooltip/getTooltipPosition.js

@@ -0,0 +1,161 @@
+function normalizePosition(position) {
+  const { left, right, bottom, top, width, ...rest } = position
+
+  // adjust the coordinates so that it fits within the window
+  const normalized = {
+    left: Math.max(0, left),
+    right: Math.max(0, right),
+    top: Math.max(0, top),
+    bottom // since it's ok the make the document grow downwards - no need to normalize here
+  }
+
+  const getAbsoluteDiff = (value1, value2) => Math.abs(Math.abs(value1) - Math.abs(value2))
+
+  // adjust the width by whatever has been subtracted from left or right
+  normalized.width =
+    width -
+    Math.abs(getAbsoluteDiff(left, normalized.left) - getAbsoluteDiff(right, normalized.right))
+
+  if (normalized.top !== top) {
+    normalized.bottom += normalized.top - top
+  }
+
+  const isNormalized =
+    normalized.right !== right || normalized.left !== left || normalized.top !== top
+
+  return {
+    ...normalized,
+    ...rest,
+    isNormalized
+  }
+}
+
+function invertPosition(position) {
+  switch (position) {
+    case 'above':
+      return 'below'
+    case 'below':
+      return 'above'
+    case 'left':
+      return 'right'
+    default:
+      return 'left'
+  }
+}
+
+function findRectByPosition(position, rectsArray) {
+  return rectsArray.find(({ position: rectPosition }) => rectPosition === position)
+}
+
+/**
+ * Used for absolute positioning of the tooltip. Since the tooltip is always centered relatively
+ * to the control (button) and we have a limited set of positions, an easy and consistent way
+ * of positioning it is to check all of the possible positions and pick one that will be rendered
+ * within the window bounds. This way we can also rely on the tooltip being actually rendered
+ * before it is shown, which makes it account for the width being limiting in styles, custom font
+ * rendering, etc.
+ */
+function getTooltipPosition(
+  position,
+  { controlLayout, tooltipDimensions, windowDimensions, arrowWidth = 0, arrowOffset = 0 }
+) {
+  const { width: controlWidth, height: controlHeight, x: controlX, y: controlY } = controlLayout
+  const { width: tooltipWidth, height: tooltipHeight } = tooltipDimensions
+  const { width: windowWidth, height: windowHeight } = windowDimensions
+
+  const arrowSize = arrowWidth / 2 + arrowOffset
+
+  const horizontalBounds = {
+    left: controlX + controlWidth / 2 - tooltipWidth / 2,
+    right: windowWidth - (controlX + controlWidth / 2 + tooltipWidth / 2)
+  }
+
+  const verticalBounds = {
+    top: controlY + controlHeight / 2 - tooltipHeight / 2,
+    bottom: windowHeight - (controlY + controlHeight / 2 + tooltipHeight / 2)
+  }
+
+  // calculate absolute coordinates for each of the potential positions (relative to window)
+  const boundingRects = [
+    {
+      position: 'above',
+      ...horizontalBounds,
+      top: controlY - tooltipHeight - arrowSize,
+      bottom: windowHeight - (controlY - arrowSize)
+    },
+    {
+      position: 'right',
+      ...verticalBounds,
+      left: controlX + controlWidth + arrowSize,
+      right: windowWidth - (controlX + controlWidth + tooltipWidth + arrowSize)
+    },
+    {
+      position: 'below',
+      ...horizontalBounds,
+      top: controlY + controlHeight + arrowSize,
+      bottom: windowHeight - (controlY + controlHeight + tooltipHeight + arrowSize)
+    },
+    {
+      position: 'left',
+      ...verticalBounds,
+      left: controlX - tooltipWidth - arrowSize,
+      right: windowWidth - (controlX - arrowSize)
+    }
+  ].map((rect) => {
+    // an absolute value representing how much of the tooltip is overflowing the window on each side
+    const windowOverflow = Math.abs(
+      Math.min(rect.top, 0) -
+        Math.min(rect.left, 0) -
+        Math.min(rect.right, 0) -
+        Math.min(rect.bottom, 0)
+    )
+
+    return {
+      ...rect,
+      ...tooltipDimensions,
+      overflow: windowOverflow,
+      isNormalized: false
+    }
+  })
+
+  // the 'position' prop overrides the automatic positioning
+  if (position !== 'auto') {
+    let rect = findRectByPosition(position, boundingRects)
+
+    // check if the suggested 'position' fits in window
+    if (rect.overflow === 0) {
+      return rect
+    }
+
+    // otherwise try the inverted position (e.g. left -> right)
+    rect = findRectByPosition(invertPosition(position), boundingRects)
+
+    if (rect.overflow === 0) {
+      return rect
+    }
+  }
+
+  const inWindow = boundingRects.filter(({ overflow }) => overflow === 0)
+
+  // pick the first position that fits in window
+  // (these are sorted clockwise which makes them show where one would expect them to be)
+  if (inWindow.length > 0) {
+    return inWindow[0]
+  }
+
+  // if all positions would end up being out of window bounds, let's pick the one that is
+  // the least overflowing and normalize its position to fit within window bounds
+  boundingRects.sort(({ overflow: overflowA }, { overflow: overflowB }) => overflowA - overflowB)
+
+  const leastOverflowing = boundingRects[0]
+
+  // prefer 'below' over 'above', since we can always expand the document downwards,
+  // and 'above' might cause issues on small viewports with large tooltips
+  return normalizePosition(
+    leastOverflowing.position === 'above'
+      ? findRectByPosition('below', boundingRects)
+      : leastOverflowing
+  )
+}
+
+export default getTooltipPosition

package/src/Tooltip/index.js

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

package/src/TooltipButton/TooltipButton.jsx

@@ -0,0 +1,49 @@
+import React from 'react'
+import { View } from 'react-native'
+
+import PropTypes from 'prop-types'
+import { useThemeTokens, applyOuterBorder } from '../ThemeProvider'
+import { getTokensPropType, variantProp } from '../utils'
+import Icon from '../Icon'
+
+const selectInnerContainerStyles = ({ borderRadius, width }) => ({ borderRadius, width })
+
+const selectIconTokens = ({ iconSize, iconColor /* iconScale = 1 */ }) => ({
+  size: iconSize,
+  color: iconColor
+  // scale: iconScale TODO re-enable with icon component
+})
+
+/**
+ * `TooltipButton` is a helper component used as a default control for the `Tooltip` component.
+ * In fact though, it isn't actually a pressable - it's meant to be used as pressable's content.
+ * Due to this any interaction states (e.g. pressed, hover, etc.) has to be passed down to it as a prop.
+ */
+const TooltipButton = ({ pressableState, tokens, variant }) => {
+  const themeTokens = useThemeTokens('TooltipButton', tokens, variant, pressableState)
+
+  const { icon: IconComponent } = themeTokens
+
+  return (
+    <View style={applyOuterBorder(themeTokens)}>
+      <View style={selectInnerContainerStyles(themeTokens)}>
+        {IconComponent && <Icon icon={IconComponent} tokens={selectIconTokens(themeTokens)} />}
+      </View>
+    </View>
+  )
+}
+
+TooltipButton.propTypes = {
+  /**
+   * Used as appearances when resolving theme tokens.
+   */
+  pressableState: PropTypes.shape({
+    pressed: PropTypes.bool,
+    hover: PropTypes.bool,
+    focus: PropTypes.bool
+  }),
+  tokens: getTokensPropType('TooltipButton'),
+  variant: variantProp.propType
+}
+
+export default TooltipButton

package/src/TooltipButton/index.js

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

package/src/Typography/Typography.jsx

@@ -1,11 +1,11 @@
 import React from 'react'
 import PropTypes from 'prop-types'
-import { Platform, Text, View } from 'react-native'
+import { Text, View } from 'react-native'
 
 import { useThemeTokens } from '../ThemeProvider'
 import { useViewport } from '../ViewportProvider'
 import { applyTextStyles } from '../ThemeProvider/utils'
-import { a11yProps, variantProp, getTokensPropType } from '../utils/propTypes'
+import { a11yProps, variantProp, getTokensPropType, getMaxFontMultiplier } from '../utils'
 
 /**
  * If passed a string like 'h1', 'h2' etc, returns the heading number as a string,
@@ -16,27 +16,15 @@ function getHeadingLevel(heading) {
   return match && match[1]
 }
 
-/**
- * Enforces `fontScaleCap` theme tokens as the maximum font size text can become
- * after iOS or Android font scaling, to give consistent accessible maximum sizes
- * that don't make the content unusable
- */
-function getMaxFontMultiplier({ fontSize, fontScaleCap }) {
-  if (!fontScaleCap || !fontSize) return undefined
-  if (fontScaleCap <= fontSize) return 1
-  return fontScaleCap / fontSize
-}
-
 const selectTextStyles = ({
   fontWeight,
   fontSize,
   color,
   lineHeight,
   fontName,
-  marginTop,
-  marginBottom,
   textAlign,
-  textTransform
+  textTransform,
+  letterSpacing
 }) =>
   applyTextStyles({
     fontWeight,
@@ -44,10 +32,9 @@ const selectTextStyles = ({
     color,
     lineHeight,
     fontName,
-    marginTop,
-    marginBottom,
     textAlign,
-    textTransform
+    textTransform,
+    letterSpacing
   })
 
 // General-purpose flexible theme-neutral base component for text
@@ -64,17 +51,16 @@ const Typography = ({
   const viewport = useViewport()
   const themeTokens = useThemeTokens('Typography', tokens, variant, { viewport })
   const textProps = {
-    style: selectTextStyles(align ? { ...themeTokens, textAlign: align } : themeTokens)
+    style: selectTextStyles(align ? { ...themeTokens, textAlign: align } : themeTokens),
+    maxFontSizeMultiplier: getMaxFontMultiplier(themeTokens)
   }
-  if (Platform.OS !== 'web') textProps.maxFontSizeMultiplier = getMaxFontMultiplier(themeTokens)
 
   const headingLevel = getHeadingLevel(heading)
   const a11y = {
     ...a11yProps.select(rest),
     accessibilityRole,
-    // On React Native Web, `aria-level` controls which heading tag (h1, h2 etc) is used.
-    // Must be hyphenated, not camel case; `accessibilityLevel` only works on RNW >=0.15.1
-    [headingLevel && 'aria-level']: headingLevel
+    // On React Native Web, `accessibilityLevel` controls which heading tag (h1, h2 etc) is used.
+    ...(headingLevel && { accessibilityLevel: headingLevel })
   }
 
   return block ? (

package/src/ViewportProvider/ViewportProvider.jsx

@@ -0,0 +1,21 @@
+import React, { useState } from 'react'
+import PropTypes from 'prop-types'
+import { viewports } from '@telus-uds/system-constants'
+import { ViewportContext } from './useViewport'
+import useViewportListener from './useViewportListener'
+
+/**
+ * Provides an up-to-date viewport value from system-constants, available via the `useViewport` hook
+ */
+const ViewportProvider = ({ children }) => {
+  // Default to the smallest viewport for mobile-first SSR. On client side, this is updated
+  // by useViewportListener in a layout effect before anything is shown to the user.
+  const [viewport, setViewport] = useState(viewports.keys[0])
+  useViewportListener(setViewport)
+  return <ViewportContext.Provider value={viewport}>{children}</ViewportContext.Provider>
+}
+ViewportProvider.propTypes = {
+  children: PropTypes.node.isRequired
+}
+
+export default ViewportProvider

package/src/ViewportProvider/index.jsx

@@ -1,43 +1,4 @@
-import React, { createContext, useState, useEffect, useContext } from 'react'
-import PropTypes from 'prop-types'
-import { Dimensions } from 'react-native'
-import { viewports } from '@telus-uds/system-constants'
-
-// we are using Dimensions instead of useWindowDimensions
-// that's because useWindowDimensions forces context to update on
-// every pixel change on the browser, therefore we used Dimension to only enforce
-// context update on viewport changes
-const lookupViewport = () => viewports.select(Dimensions.get('window').width)
-
-export const ViewportContext = createContext({})
-
-/**
- * Provides an up-to-date viewport value from system-constants, available via the `useViewport` hook
- */
-const ViewportProvider = ({ children }) => {
-  // initialize with a function so we don't re-execute on each render
-  const [viewport, setViewport] = useState(lookupViewport)
-
-  useEffect(() => {
-    const onChange = ({ window }) => setViewport(viewports.select(window.width))
-
-    Dimensions.addEventListener('change', onChange)
-    // We might have missed an update between calling `get` in render and
-    // `addEventListener` in this handler, so we set it here. If there was
-    // no change, React will filter out this update as a no-op.
-    setViewport(lookupViewport())
-    return () => {
-      Dimensions.removeEventListener('change', onChange)
-    }
-  }, [])
-
-  return <ViewportContext.Provider value={viewport}>{children}</ViewportContext.Provider>
-}
-
-ViewportProvider.propTypes = {
-  children: PropTypes.node.isRequired
-}
+import ViewportProvider from './ViewportProvider'
 
 export default ViewportProvider
-
-export const useViewport = () => useContext(ViewportContext)
+export * from './useViewport'

package/src/ViewportProvider/useViewport.js

@@ -0,0 +1,5 @@
+import { createContext, useContext } from 'react'
+
+export const ViewportContext = createContext({})
+
+export const useViewport = () => useContext(ViewportContext)

package/src/ViewportProvider/useViewportListener.js

@@ -0,0 +1,43 @@
+import { useLayoutEffect } from 'react'
+import { Dimensions } from 'react-native'
+import { viewports } from '@telus-uds/system-constants'
+
+// 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(() => {
+    setViewport(lookupViewport())
+
+    const onChange = ({ window }) => setViewport(viewports.select(window.width))
+    const listener = Dimensions.addEventListener('change', onChange)
+
+    // From RN 0.65.0, Dimensions.removeEventListener is deprecated for `remove` on addEventListener return value;
+    // however, that is not available in RN <=0.64.X, therefore not in any Expo release as of 2021 (Expo SDK 43).
+    return listener?.remove || (() => Dimensions.removeEventListener('change', onChange))
+
+    // setViewport is a function from `useState` so it is stable and won't make the effect re-run
+  }, [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

@@ -1,21 +1,53 @@
+export { default as A11yText } from './A11yText'
 export { default as ActivityIndicator } from './ActivityIndicator'
 export { default as Box } from './Box'
 export * from './Button'
-export { default as Card } from './Card'
+export { default as Card, PressableCardBase } from './Card'
+export { default as Checkbox } from './Checkbox'
+export * from './Checkbox'
 export { default as Divider } from './Divider'
 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 Icon } from './Icon'
 export * from './Icon'
+export { default as InputLabel } from './InputLabel'
 export * from './Link'
+export { default as List } from './List'
+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 Radio } from './Radio'
+export * from './Radio'
+export { default as RadioCard } from './RadioCard'
+export * from './RadioCard'
+export { default as Search } from './Search'
+export { default as Select } from './Select'
 export { default as SideNav } from './SideNav'
+export { default as Skeleton } from './Skeleton'
+export { default as Spacer } from './Spacer'
+export { default as StackView } from './StackView'
+export * from './StackView'
+export { default as StepTracker } from './StepTracker'
+export { default as Tabs } from './Tabs'
+export { default as Tags } from './Tags'
+export * from './TextInput'
 export { default as ToggleSwitch } from './ToggleSwitch'
+export { default as Tooltip } from './Tooltip'
+export { default as TooltipButton } from './TooltipButton'
 export { default as Typography } from './Typography'
 
 export { default as A11yInfoProvider, useA11yInfo } from './A11yInfoProvider'
 export { default as BaseProvider } from './BaseProvider'
 export { default as ViewportProvider, useViewport } from './ViewportProvider'
-export { default as ThemeProvider, useTheme, useSetTheme } from './ThemeProvider'
+export {
+  default as ThemeProvider,
+  useTheme,
+  useSetTheme,
+  useThemeTokens,
+  getThemeTokens
+} from './ThemeProvider'
 
 export * from './utils'

package/src/utils/a11y/index.js

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

package/src/utils/a11y/textSize.js

@@ -0,0 +1,30 @@
+import { PixelRatio, Platform } from 'react-native'
+
+/**
+ * When a user increases text size using device accessibility settings, some elements
+ * should also scale, such as icons alongside text and space between paragraphs.
+ *
+ * @param {number} [value] - the value to multiply; defaults to system default font size
+ * @param {number} [maxScale] - the maximum multiplier to apply; defaults to no maximum
+ */
+export const scaleWithText = (value, maxScale = Infinity) => {
+  if (!value) return value
+  const scale = Math.min(PixelRatio.getFontScale(), maxScale) || 1
+  return value * scale
+}
+
+/**
+ * Native only, returns `undefined` on Web.
+ *
+ * Enforces `fontScaleCap` theme tokens as the maximum font size text can become
+ * after iOS or Android font scaling, to give consistent accessible maximum sizes
+ * that don't make the content unusable.
+ *
+ * The return value of this function can be used as a React Native `Text` element's
+ * `maxFontSizeMultiplier` prop value.
+ */
+export const getMaxFontMultiplier = ({ fontSize, fontScaleCap }) => {
+  if (Platform.OS === 'web' || !fontScaleCap || !fontSize) return undefined
+  if (fontScaleCap <= fontSize) return 1
+  return fontScaleCap / fontSize
+}

package/src/utils/children.jsx

@@ -0,0 +1,66 @@
+import React, { Children, Fragment } from 'react'
+import { Text } from 'react-native'
+
+/**
+ * Unpacks top-level fragments, so that common compositional patterns such as the following examples
+ * can be iterated as flat siblings (as if they were `<Child1 /><Child2 /><Child3 />`):
+ *
+ * - Setting `children` as a property wrapped in a fragment:
+ *
+ * ```jsx
+ * args.children = <><Child1 /><Child2 /><Child3 /></>
+ * ```
+ *
+ * - Defining `children` as a variable wrapped in a fragment:
+ *
+ * ```jsx
+ * const content = <><Child1 /><Child2 /><Child3 /></>
+ * if (someCondition) return <SomeWrapper>{content}</SomeWrapper>
+ * ```
+ *
+ * - Using fragments at the top level of a JSX block for conditional rendering:
+ *
+ * ```jsx
+ * <Child1 />
+ * {someCondition && (
+ *   <>
+ *     <Child2 />
+ *     <Child3 />
+ *   </>
+ * )}
+ * ```
+ *
+ * @param {ReactChildren} child
+ * @returns {ReactChildren}
+ */
+export const unpackFragment = (child) => {
+  // If this level is a set of top-level siblings rather than one child, check each in turn
+  if (Children.count(child) > 1) return Children.map(child, unpackFragment)
+
+  // When a fragment is found, unpack its children to the top level and check them
+  if (child?.type === Fragment) return unpackFragment(child.props?.children)
+
+  // Stop unpacking as soon as any non-fragment child is found
+  return child
+}
+
+/**
+ * React Native on Native crashes if text content is rendered outside `<Text>`, and on web,
+ * text style inheritance isn't as expected.
+ *
+ * Call this function on children that may contain text (strings or numbers) at the top level,
+ * and any that are found will be wrapped in a React Native `<Text>` element with supplied props.
+ *
+ * Note that this does not wrap strings that are nested children of the top level children:
+ * `wrapStringsInText(<View>Some text</View>)` will not wrap the inner text and will still crash,
+ * but `wrapStringsInText(<>{someString}{anotherString}</>)` will wrap the strings in the fragment.
+ *
+ * @param {ReactChildren} children
+ * @param {TextProps} props
+ * @returns {ReactChildren}
+ */
+export const wrapStringsInText = (children, props = {}) => {
+  return Children.map(unpackFragment(children), (child) =>
+    typeof child === 'string' || typeof child === 'number' ? <Text {...props}>{child}</Text> : child
+  )
+}

package/src/utils/index.js

@@ -1,4 +1,14 @@
+export * from './a11y'
 export * from './animation'
+export * from './children'
 export * from './input'
+export * from './pressability'
 export * from './propTypes'
-export * from './spacing'
+
+export { default as info } from './info'
+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 * from './useResponsiveProp'
+export { default as useUniqueId } from './useUniqueId'

package/src/utils/info/index.js

@@ -0,0 +1,8 @@
+import platform from './platform'
+import versions from './versions'
+
+// export an object accessed like info.platform.OS, info.version.uds, etc
+export default {
+  platform,
+  versions
+}

package/src/utils/info/platform/index.js

@@ -0,0 +1,11 @@
+import { Platform } from 'react-native'
+import fileSuffix from './platform'
+
+// Allows consuming libraries that might not have a direct dependency on
+// React Native to check what the current platform is.
+
+// Particularly useful for validating Jest config: it is possible for Jest to
+// get configured such that Platform.OS returns a different mocked value to the
+// OS being used to select files by platform suffix (e.g. .web, .native).
+
+export default { OS: Platform.OS, fileSuffix }

package/src/utils/info/platform/platform.android.js

@@ -0,0 +1 @@
+export default '.android'

package/src/utils/info/platform/platform.ios.js

@@ -0,0 +1 @@
+export default '.ios'

package/src/utils/info/platform/platform.js

@@ -0,0 +1 @@
+export default '.web (default)'

package/src/utils/info/platform/platform.native.js

@@ -0,0 +1,4 @@
+// This shouldn't ever be chosen, as the more specific '.ios' and '.android' are available.
+// If this gets picked, either an unsupported React Native platform is being used somehow
+// (e.g. a native Windows app), or there's a serious config problem somewhere.
+export default '.native'

package/src/utils/info/versions.js

@@ -0,0 +1,6 @@
+import pkgJson from '../../../package.json'
+
+// Add more versions if they are useful e.g. theme schema version
+export default {
+  uds: pkgJson.version
+}