@telus-uds/components-base 0.0.2-prerelease.3 → 0.0.2-prerelease.7

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,35 @@
+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 Checkbox } from './Checkbox'
 export { default as Divider } from './Divider'
 export { default as ExpandCollapse, Accordion } from './ExpandCollapse'
+export { default as Feedback } from './Feedback'
 export { default as FlexGrid } from './FlexGrid'
 export { default as Icon } from './Icon'
 export * from './Icon'
 export * from './Link'
+export { default as List } from './List'
 export { default as Pagination } from './Pagination'
+export { default as Radio } from './Radio'
+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 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 } 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/index.js

@@ -1,4 +1,11 @@
+export * from './a11y'
 export * from './animation'
 export * from './input'
+export * from './pressability'
 export * from './propTypes'
-export * from './spacing'
+
+export { default as info } from './info'
+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.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/platform/platform.web.js

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

package/src/utils/info/versions.js

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

package/src/utils/input.js

@@ -55,6 +55,7 @@ Consumers of this hook must be one of:
  *   currentValue: any
  *   setValue: (value: any) => void
  *   resetValue: () => void
+ *   isControlled: bool
  * }}
  */
 
@@ -81,7 +82,7 @@ export const useInputValue = (props = {}, hookName = 'useInputValue') => {
   )
   const resetValue = useCallback(() => setValue(initializedValue), [initializedValue, setValue])
 
-  return { currentValue, setValue, resetValue }
+  return { currentValue, setValue, resetValue, isControlled }
 }
 
 /**

package/src/utils/pressability.js

@@ -0,0 +1,92 @@
+import { Platform, StyleSheet } from 'react-native'
+import { pressProps } from './propTypes'
+
+// These roles should result in cursor: pointer but don't in current RNW releases
+const shouldUseCursor = ['checkbox', 'radio', 'switch']
+
+/**
+ * React Native Web has some built-in logic for applying cursor styles based on accessibility roles;
+ * however, it misses certain cases. This fills in known cases where widely used versions of RNW
+ * fail to apply an expected cursor style.
+ *
+ * @param {object} props
+ * @param {boolean} [props.inactive]
+ * @param {boolean} [props.disabled]
+ * @param {string} [props.accessibilityRole]
+ * @returns
+ */
+export const getCursorStyle = ({ inactive, disabled, accessibilityRole }) => {
+  if (Platform.OS !== 'web') return undefined
+
+  if (inactive || disabled) return staticStyles.notAllowed
+  if (shouldUseCursor.includes(accessibilityRole)) return staticStyles.pointer
+
+  return undefined // allows React Native Web's built-in logic to apply
+}
+
+/**
+ * @typedef {{ pressed: boolean, focused: boolean, hovered?: boolean }} PressableState
+ */
+
+/**
+ * Maps the state object given by the React Native `Pressable` component to the set of
+ * equivalent appearance names used in UDS.
+ *
+ * @param {PressableState} pressableState - state object passed by React Native's `<Pressable>` into
+ *   render functions passed to its `style` or `children` props.
+ * @param {object} [additionalState] - properties specific to the current component,
+ *   such as `inactive`, `selected`, etc.
+ * @returns {object}
+ */
+export const resolvePressableState = (
+  { pressed = false, focused = false, hovered = false } = {},
+  additionalState
+) => ({
+  ...additionalState,
+  focus: focused,
+  hover: hovered,
+  pressed
+})
+
+/**
+ * Takes a UDS `tokens` prop and, if it is a function, resolves it based on a state
+ * object passed from the React Native `Pressable` component and optional extra properties.
+ *
+ * @param {object|function} tokens - UDS system tokens prop
+ * @param {PressableState} pressableState - state object passed by React Native's `<Pressable>`
+ * @param {object} [additionalState] - properties specific to the current component
+ * @returns {object} - resolved tokens object
+ */
+export const resolvePressableTokens = (tokens, pressableState, additionalState) => {
+  if (typeof tokens !== 'function') return tokens
+  const udsPressableState = resolvePressableState(pressableState, additionalState)
+  return tokens(udsPressableState)
+}
+
+const staticStyles = StyleSheet.create(
+  Platform.select({
+    web: {
+      notAllowed: { cursor: 'not-allowed' },
+      pointer: { cursor: 'pointer' }
+    },
+    default: {}
+  })
+)
+
+/**
+ * From an object of props, extracts any platform-appropriate press handler functions and wraps
+ * them in a function that passes in some provided args. Allows components containing a Pressable
+ * to pass in press handlers that are then called with state or values that is otherwise internal.
+ */
+export const getPressHandlersWithArgs = (pressableProps = {}, args = []) => {
+  // Allow handlers to be passed down for blur, hover, focus, pressIn, etc
+  const pressHandlers = Object.fromEntries(
+    Object.entries(pressProps.selectHandlers(pressableProps)).map(([key, handler]) => ({
+      [key]: (...defaultArgs) => {
+        // Pass each handler data on this button and current selection
+        handler(...args, ...defaultArgs)
+      }
+    }))
+  )
+  return pressHandlers
+}

package/src/utils/propTypes.js

@@ -1,6 +1,24 @@
 import PropTypes from 'prop-types'
 import { Linking, Platform } from 'react-native'
-import { tokenKeys } from '@telus-uds/tools-theme'
+import { components as tokenKeys } from '@telus-uds/system-themes/schema'
+
+export const paddingProp = {
+  propType: PropTypes.shape({
+    paddingBottom: PropTypes.number,
+    paddingLeft: PropTypes.number,
+    paddingRight: PropTypes.number,
+    paddingTop: PropTypes.number
+  })
+}
+
+export const rectProp = {
+  propType: PropTypes.shape({
+    bottom: PropTypes.number,
+    left: PropTypes.number,
+    right: PropTypes.number,
+    top: PropTypes.number
+  })
+}
 
 /**
  * @typedef {{[key: string]: string|number|boolean}} AppearanceSet
@@ -29,7 +47,7 @@ const tokenValueType = PropTypes.oneOfType([tokenValue, PropTypes.objectOf(token
 const getTokenNames = (componentName) => {
   const componentTokenNames = tokenKeys[componentName]
   if (!componentTokenNames) {
-    throw new Error(`No "${componentName}" tokenKeys in @telus-uds/tools-theme`)
+    throw new Error(`No "${componentName}" tokenKeys in @telus-uds/system-themes/schema`)
   }
   return componentTokenNames
 }
@@ -59,14 +77,48 @@ export const selectTokens = (componentName, tokens) => {
  *
  * This prop is intended to be used as an 'escape hatch' for difficult or exceptional cases
  * where the main theming system doesn't apply. It is intentionally permissive about values.
+ *
+ * @param {...string} componentsNames - one or more ComponentName, which tokens keys are accepted
+ * @return {function} - a custom PropTypes validator
+ *
+ * @example
+ * Component.propTypes = {
+ *   // accepts all tokens keys defined in Component schema
+ *   tokens: getTokensPropType('Component')
+ * }
+ *
+ * Component.propTypes = {
+ *   // accepts all tokens keys defined in schemas for Component1 and Component2
+ *   tokens: getTokensPropType('Component1', 'Component2')
+ * }
  */
-export const getTokensPropType = (componentName) =>
-  PropTypes.oneOfType([
-    PropTypes.shape(
-      Object.fromEntries(getTokenNames(componentName).map((key) => [key, tokenValueType]))
-    ),
-    PropTypes.func // function that takes current appearances and returns above shape
-  ])
+export const getTokensPropType = (...componentsNames) => (props, propName, componentName) => {
+  PropTypes.checkPropTypes(
+    {
+      [propName]: PropTypes.oneOfType([PropTypes.object, PropTypes.func])
+    },
+    props,
+    propName,
+    componentName
+  )
+
+  if (typeof props[propName] !== 'function') {
+    PropTypes.checkPropTypes(
+      {
+        [propName]: PropTypes.exact(
+          Object.fromEntries(
+            componentsNames.flatMap((component) =>
+              getTokenNames(component).map((key) => [key, tokenValueType])
+            )
+          )
+        )
+      },
+      props,
+      propName,
+      componentName
+    )
+  }
+}
 
 function getPropSelector(propTypes, regexp) {
   const keys = Object.keys(propTypes)
@@ -152,7 +204,27 @@ export const a11yProps = {
         accessibilityElementsHidden: true
       }
     })
-  }
+  },
+  /**
+   * Generates an object of platform-appropriate a11y props describing an item that has an
+   * ordered position in a set. Examples of usage by accessibility tools includes screenreaders
+   * saying "Item X of Y" when this item is select.
+   *
+   * @param {number} itemsCount - the number of items in the set
+   * @param {number} index - the current item's index in the set
+   * @returns {object} - platform-applicable a11y props describing this position (if available)
+   */
+  getPositionInSet: (itemsCount, index) =>
+    Platform.select({
+      web: {
+        // accessibilityPosInSet etc exists in React Native Web main branch
+        // but not in a release compatible with Expo etc; just use `aria-*`
+        'aria-setsize': itemsCount,
+        'aria-posinset': index + 1
+      },
+      // No equivalents exist on the native side
+      default: {}
+    })
 }
 
 // Props related to HTML <a> anchor link attributes.
@@ -199,7 +271,7 @@ export const hrefAttrsProp = {
   })
 }
 
-const pressPropTypes = {
+const pressHandlerPropTypes = {
   onPress: PropTypes.func,
   onPressIn: PropTypes.func,
   onPressOut: PropTypes.func,
@@ -210,7 +282,18 @@ const pressPropTypes = {
       onFocus: PropTypes.func,
       onBlur: PropTypes.func
     },
-    default: {}
+    default: {
+      onLongPress: PropTypes.func
+    }
+  })
+}
+
+const pressPropTypes = {
+  ...pressHandlerPropTypes,
+  disabled: PropTypes.bool,
+  ...Platform.select({
+    hitSlop: PropTypes.number,
+    pressRetentionOffset: PropTypes.oneOfType([PropTypes.number, rectProp.propType])
   })
 }
 
@@ -222,7 +305,8 @@ export const pressProps = {
   /**
    * Filters a props object, returning only the platform-relevant press props defined above
    */
-  select: getPropSelector(pressPropTypes)
+  select: getPropSelector(pressPropTypes),
+  selectHandlers: getPropSelector(pressHandlerPropTypes)
 }
 
 const linkPropTypes = {

package/src/utils/useCopy.js

@@ -0,0 +1,13 @@
+/**
+ * Extract translations from a keyed dictionary for a given language.
+ * Returns a getter.
+ *
+ * @param {object} dictionary
+ * @param {'en'|'fr'} copy - language
+ * @return {function(string): string}
+ */
+function useCopy({ dictionary, copy }) {
+  return (key) => dictionary[copy][key]
+}
+
+export default useCopy

package/src/utils/useResponsiveProp.js

@@ -0,0 +1,50 @@
+import { viewports } from '@telus-uds/system-constants'
+import { useViewport } from '../ViewportProvider'
+
+const hasOwn = (objectProp, key) => Object.prototype.hasOwnProperty.call(objectProp, key)
+const hasResponsiveProperties = (objectProp) =>
+  viewports.keys.some((key) => hasOwn(objectProp, key))
+
+/**
+ * Resolves a prop which may be a responsive object with keys for viewports.
+ *
+ * Used internally in useResponsiveProp - see that for more details.
+ *
+ * @param {*} prop
+ * @param {"xs"|"sm"|"md"|"lg"|"xl"} viewport
+ * @param {*} [defaultValue]
+ * @returns {*}
+ */
+export const resolveResponsiveProp = (prop, viewport, defaultValue) => {
+  if (prop === undefined) return defaultValue
+  if (!prop || typeof prop !== 'object' || !hasResponsiveProperties(prop)) return prop
+
+  const value = viewports.keys.includes(viewport)
+    ? // If there's a current viewport, return the closest match at or below it
+      viewports.inherit(prop)[viewport]
+    : // If no current viewport is available, default to smallest viewport
+      prop[viewports.keys.find((key) => hasOwn(prop, key))]
+
+  return value === undefined ? defaultValue : value
+}
+
+/**
+ * Takes any value and, if that value is a responsive prop (an object with one or more
+ * keys matching system viewport names), returns the value corresponding to the largest
+ * viewport key smaller than the current screen's viewport.
+ *
+ * For example, if passed `{ sm: 4, lg: 8 }`, it will return 8 on `xl` and `lg` viewports,
+ * 4 on `md` and `sm` viewports, and `undefined` (or a provided `defaultValue`) on `xs` viewports.
+ *
+ * To generate propTypes for responsive props, see `responsiveProps` in `./utils/propTypes.js`.
+ *
+ * @param {*} prop - any value which may be an object with viewport keys
+ * @param {*} [defaultValue] - default value to provide if no matches found for the current viewport
+ * @returns {*}
+ */
+const useResponsiveProp = (prop, defaultValue) => {
+  const viewport = useViewport()
+  return resolveResponsiveProp(prop, viewport, defaultValue)
+}
+
+export default useResponsiveProp

package/src/utils/{spacing/useSpacingScale.js → useSpacingScale.js}

@@ -1,14 +1,27 @@
-import { useViewport } from '../../ViewportProvider'
-import { useThemeTokens } from '../../ThemeProvider'
-import { resolveSpacingValue, resolveSpacingOptions } from './utils'
+import { useViewport } from '../ViewportProvider'
+import { useThemeTokens } from '../ThemeProvider'
+import { resolveResponsiveProp } from './useResponsiveProp'
 /**
  * @typedef {import('@telus-uds/system-constants/viewports').Viewport} Viewport
- * @typedef {import('../propTypes.js').SpacingValue} SpacingValue
- * @typedef {import('../propTypes.js').SpacingIndex} SpacingIndex
- * @typedef {import('../propTypes.js').SpacingObject} SpacingObject
- * @typedef {import('../propTypes.js').SpacingOptions} SpacingOptions
+ * @typedef {import('./propTypes.js').SpacingValue} SpacingValue
+ * @typedef {import('./propTypes.js').SpacingIndex} SpacingIndex
+ * @typedef {import('./propTypes.js').SpacingObject} SpacingObject
+ * @typedef {import('./propTypes.js').SpacingOptions} SpacingOptions
  */
 
+const resolveSpacingOptions = (space) => {
+  if (!space?.options) return {}
+
+  const { size, variant, subtract = 0 } = space.options
+  const overridden = typeof size === 'number'
+
+  // Might need an option that adapts the size value by current user's system font scale, so that
+  // meaningful spacing between items doesn't disappear on the highest a11y font scale settings.
+  // https://github.com/telus/universal-design-system/issues/583
+
+  return { tokens: { size }, variant, overridden, subtract }
+}
+
 /**
  * Pass a {@link SpacingValue}, which is one of:
  *
@@ -82,11 +95,13 @@ const useSpacingScale = (spaceValue) => {
   // In future, may need to consider window height as well as width, particularly for native apps,
   // e.g. to ensure designs don't look lost on large, tall, not-so-wide portrait screens.
   const viewport = useViewport()
-
   const { tokens, variant, overridden, subtract = 0 } = resolveSpacingOptions(spaceValue)
-  const space = overridden ? null : resolveSpacingValue(spaceValue, viewport)
+  const space = !overridden && (spaceValue?.space ?? resolveResponsiveProp(spaceValue, viewport, 0))
 
-  const { size } = useThemeTokens('spacingScale', tokens, variant, { space, viewport })
+  const { size } = useThemeTokens('spacingScale', tokens, variant, {
+    space: typeof space === 'number' ? space : 0,
+    viewport
+  })
   return Math.max(size - subtract, 0)
 }
 

package/src/utils/useUniqueId.js

@@ -0,0 +1,14 @@
+import { useState } from 'react'
+
+let id = 0
+
+function useUniqueId(prefix = '') {
+  const [uniqueId] = useState(() => {
+    id += 1
+    return `${prefix}-${id}`
+  })
+
+  return uniqueId
+}
+
+export default useUniqueId

package/stories/A11yText/A11yText.stories.jsx

@@ -4,6 +4,7 @@ import { StyleSheet, Text, View } from 'react-native'
 
 import A11yText from '../../lib/A11yText'
 import { Button, Typography } from '../../lib'
+import { EachParentType, parentTypesParams } from '../supports'
 
 const defaultArgs = {
   text: 'This text is for screen readers,',
@@ -31,6 +32,10 @@ const Template = (args) => (
   </>
 )
 
+export const Default = (args) => <A11yText {...args} />
+Default.storyName = 'A11yText'
+Default.args = defaultArgs
+
 export const A11yTextInText = Template.bind({})
 A11yTextInText.args = defaultArgs
 
@@ -50,12 +55,13 @@ export const A11yTextInButton = (args) => (
 )
 A11yTextInButton.args = defaultArgs
 
-export const A11yTextInRow = (args) => (
-  <View style={styles.row}>
-    <Template {...args} />
-  </View>
+export const ParentTypes = (args) => (
+  <EachParentType {...args}>
+    {({ label }) => <Template {...args} key={label} text={label} />}
+  </EachParentType>
 )
-A11yTextInRow.args = defaultArgs
+ParentTypes.args = defaultArgs
+ParentTypes.parameters = parentTypesParams
 
 const styles = StyleSheet.create({
   // Use borders so any hairline gaps created by A11yText are visible

package/stories/ActivityIndicator/ActivityIndicator.stories.jsx

@@ -1,5 +1,7 @@
+/* eslint-disable react/no-multi-comp */
 import React from 'react'
 import { ActivityIndicator } from '../../lib'
+import { EachParentType, parentTypesParams } from '../supports'
 
 export default {
   title: 'Base/ActivityIndicator',
@@ -9,5 +11,12 @@ export default {
   }
 }
 
-export const Story = (args) => <ActivityIndicator {...args} />
-Story.storyName = 'ActivityIndicator'
+export const Default = (args) => <ActivityIndicator {...args} />
+Default.storyName = 'ActivityIndicator'
+
+export const ParentTypes = (args) => (
+  <EachParentType {...args}>
+    {({ label }) => <ActivityIndicator {...args} label={label} />}
+  </EachParentType>
+)
+ParentTypes.parameters = parentTypesParams