@telus-uds/components-base 0.0.2-prerelease.1 → 0.0.2-prerelease.10

package/src/utils/propTypes.js

@@ -1,7 +1,29 @@
 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-theme-tokens'
 
+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
+ * @typedef {AppearanceSet} VariantProp
+ */
 export const variantProp = {
   /**
    * 'variant' is an optional object prop on all themable components.
@@ -17,29 +39,70 @@ export const variantProp = {
   )
 }
 
-const tokenValueType = PropTypes.oneOfType([PropTypes.string, PropTypes.number, PropTypes.bool])
+// Tokens can be primitive values (e.g. `'rgba(0,0,0,0'`, `12`), or objects of such values,
+// such as tokens that describe shadow (e.g. shadow: { inset: true, color: 'rgba(...)' ... }),
+// or components (e.g. Icon tokens)
+const tokenValue = PropTypes.oneOfType([
+  PropTypes.string,
+  PropTypes.number,
+  PropTypes.bool,
+  PropTypes.elementType
+])
+const tokenValueType = PropTypes.oneOfType([tokenValue, PropTypes.objectOf(tokenValue)])
 
-const getTokenNames = (componentName) => {
+export 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-theme-tokens`)
   }
   return componentTokenNames
 }
 
 /**
  * Returns the subset of a set of tokens that may be accepted by the `tokens` prop of a named component
+ * or by a provided array of tokens. A prefix may be provided, for example:
+ *
+ * @example
+ * ```jsx
+ * // returns tokens from `themeTokens` that exist in the theme schema for `Button`.
+ * selectTokens('Button', themeTokens)
+ * ```
+ *
+ * @example
+ * ```jsx
+ * // returns `{ backgroundColor, width }` where the values of those keys come from
+ * // the source object's `{ containerBackgroundColor, containerWidth }` properties.
+ * selectTokens(['backgroundColor', 'width'], themeTokens, 'container')
+ * ```
+ *
+ * @example
+ * ```jsx
+ * // returns tokens that are defined in the `Button` theme schema, from tokens with
+ * // a prefix `'button'` e.g. a token `buttonBorderWidth` outputs as `borderWidth`.
+ * selectTokens('Button', themeTokens, 'button')
+ * ```
+ *
+ * @param {string[]|string} specifier - a name of a component in the theme schema, or an array of token names
+ * @param {object} tokens - a source object of theme tokens
+ * @param {string} [prefix] - if provided, matches keys in the source object with this as the first camelCase item
+ * @returns {object} - subset of theme tokens
  */
-export const selectTokens = (componentName, tokens) => {
-  const tokenNames = getTokenNames(componentName)
-  const filteredTokens = Object.entries(tokens).reduce(
-    (validTokens, [key, value]) =>
-      tokenNames.includes(key) ? { ...validTokens, [key]: value } : validTokens,
-    {}
-  )
+export const selectTokens = (specifier, tokens, prefix) => {
+  const tokenNames = typeof specifier === 'string' ? getTokenNames(specifier) : specifier
+  const filteredTokens = tokenNames.reduce((validTokens, key) => {
+    const prefixedKey = prefix ? `${prefix}${key[0].toUpperCase()}${key.slice(1)}` : key
+    const token = tokens[prefixedKey]
+    return token !== undefined ? { ...validTokens, [key]: token } : validTokens
+  }, {})
   return filteredTokens
 }
 
+/**
+ * @typedef {string|number|boolean|{[key: string]:string|number|boolean}} TokenValue
+ * @typedef {{[key: string]: TokenValue}} TokensSet
+ * @typedef {(AppearanceSet) => TokensSet} TokensGetter
+ * @typedef {TokensSet|TokensGetter} TokensProp
+ */
 /**
  * 'tokens' is an optional object prop on all themable components. Its keys must match the
  * token keys in the component's theme schema.
@@ -47,16 +110,82 @@ 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.
  *
- * Be careful about passing a token key with value `undefined`, as this will override any tokens from
- * the theme. If a key is set on a `tokens` prop object, tokens from the theme will be overridden.
+ * @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
+    )
+  }
+}
+
+/**
+ * Get a proptypes validator for a set of tokens that is not based on a component in the theme schema.
+ *
+ * For example, for a set of tokens used in a common style, or for a set of tokens required by
+ * a themeless component whose tokens are set by a parent but requires tokens of a certain shape.
+ *
+ * By default, requires an object with a complete set of tokens (allowing `null`, but not `undefined`).
+ *
+ * @param {string[]} componentTokenKeys - array of strings of token names
+ * @param {object} [options]
+ * @param {boolean} [options.partial] - if true, allows tokens to be undefined
+ * @param {boolean} [options.allowFunction] - if true, allows functions as well as tokens objects
+ * @returns
+ */
+export const getTokensSetPropType = (
+  componentTokenKeys,
+  { partial = false, allowFunction = false } = {}
+) => {
+  const tokensObjectValidator = PropTypes.exact(
+    Object.fromEntries(
+      componentTokenKeys.map((key) => [
+        key,
+        partial
+          ? tokenValueType
+          : // Some theme tokens can validly resolve to `null`, but .isRequired treats null as undefined
+            (props, propName, ...args) =>
+              props[propName] !== null && tokenValueType.isRequired(props, propName, ...args)
+      ])
+    )
+  )
+  return allowFunction
+    ? PropTypes.oneOfType([tokensObjectValidator, PropTypes.func])
+    : tokensObjectValidator
+}
 
 function getPropSelector(propTypes, regexp) {
   const keys = Object.keys(propTypes)
@@ -76,7 +205,6 @@ function getPropSelector(propTypes, regexp) {
 // React Native exports a11y prop definitions as TypeScript Interfaces, but no longer exports PropTypes
 // so we have to define them ourselves.
 const a11yPropTypes = {
-  // react-native-web >= 0.15.0 ignores `accessible` and looks for `focusable`
   accessible: PropTypes.bool,
   focusable: PropTypes.bool,
 
@@ -129,10 +257,9 @@ export const a11yProps = {
    * Use this to disable focus for elements which are visually hidden but still rendered.
    */
   nonFocusableProps: {
-    focusable: false, // for android, and for keyboard nav in web (RNW >= 0.15.x)
+    focusable: false, // for android, and for keyboard nav in web
     ...Platform.select({
       web: {
-        accessible: false, // workaround for web keyboard nav in RNW < 0.15.x
         accessibilityHidden: true // web screenreaders
       },
       android: {
@@ -142,7 +269,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.
@@ -166,30 +313,10 @@ export const hrefAttrsProp = {
       target
     },
     rest
-  }),
-  /**
-   * Takes a hrefAttrs object and returns an object that can be spread into Pressable props
-   * in a way that handles compatibility before and after React Native Web 0.15.0
-   */
-  spread: (hrefAttrs) => ({
-    /**
-     * React Native Web >= 0.15.0 supports hrefAttrs prop but requires React 17
-     * so is incompatible with Expo until July 2021
-     */
-    hrefAttrs,
-    /**
-     * React Native Web < 0.15.0 uses `target` and `rel` props.
-     * React Native Web >= 0.15.0 ignores these and reads hrefAttrs only.
-     */
-    rel: hrefAttrs?.rel,
-    target: hrefAttrs?.target
-    /**
-     * Don't spread hrefAttrs.download, RNW <0.15.0 doesn't support it.
-     */
   })
 }
 
-const pressPropTypes = {
+const pressHandlerPropTypes = {
   onPress: PropTypes.func,
   onPressIn: PropTypes.func,
   onPressOut: PropTypes.func,
@@ -200,7 +327,21 @@ const pressPropTypes = {
       onFocus: PropTypes.func,
       onBlur: PropTypes.func
     },
-    default: {}
+    default: {
+      onLongPress: PropTypes.func
+    }
+  })
+}
+
+const pressPropTypes = {
+  ...pressHandlerPropTypes,
+  disabled: PropTypes.bool,
+  ...Platform.select({
+    web: {},
+    default: {
+      hitSlop: PropTypes.number,
+      pressRetentionOffset: PropTypes.oneOfType([PropTypes.number, rectProp.propType])
+    }
   })
 }
 
@@ -212,7 +353,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 = {
@@ -232,38 +374,126 @@ export const linkProps = {
    */
   select: getPropSelector(linkPropTypes),
   /**
-   * Turn hrefs into press handlers on Native and throw if not given `onPress` xor `href`.
+   * Turn hrefs into press handlers on Native and throw if not given `onPress` or `href`.
    *
    * @param {({ onPress?: () => void, href?: string })}
    * @returns {(() => void)|undefined} Returns a press handler, or undefined on web if href
    * string is provided. Expects calling component to use href string on web (e.g. in `<a>`).
    */
   handleHref: ({ onPress, href }) => {
-    // TODO: revisit this when integrating routing packages
-    // https://github.com/telus/universal-design-system/issues/24
-    if (href && onPress) {
-      throw new Error("handleHref currently doesn't support both href and onPress")
-    }
     if (!href && !onPress) {
       throw new Error('handleHref requires either href or onPress')
     }
-    return Platform.OS !== 'web' && href ? () => Linking.openURL(href) : onPress
+    return Platform.select({
+      web: onPress,
+      default: (...args) => {
+        if (onPress) onPress(...args)
+        if (href) Linking.openURL(href)
+      }
+    })
   }
 }
 
-export const levelsPropType = PropTypes.oneOf([0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11])
+const viewPropTypes = {
+  pointerEvents: PropTypes.oneOf(['all', 'none', 'box-only', 'box-none']),
+  onLayout: PropTypes.func,
+  nativeID: PropTypes.string
+}
 
-export const responsivePropTypeFactory = (propType) =>
-  PropTypes.oneOfType([
-    propType,
-    PropTypes.shape({
-      xs: propType,
-      sm: propType,
-      md: propType,
-      lg: propType,
-      xl: propType
-    })
-  ])
+export const viewProps = {
+  /**
+   * Subset of `View` proptypes that could conceivably be needed on any component
+   * that renders a single View.
+   */
+  types: viewPropTypes,
+  /**
+   * Filters a props object, returning only cross-platform View props that are potentially
+   * relevant to any basic layout component that renders one View.
+   */
+  select: getPropSelector(viewPropTypes)
+}
+
+const getByViewport = (propType) => ({
+  xs: propType,
+  sm: propType,
+  md: propType,
+  lg: propType,
+  xl: propType
+})
+/**
+ * Utilities for props that allow different values to be applied at different viewports.
+ *
+ * These should apply viewport inheritance such that if a viewport is undefined, the value is
+ * taken from the next smallest viewport for which a value is available. For example, a
+ * responsive prop { xs: 2, lg: 3 } should apply 2 at sizes sm and md, and 3 at size xl.
+ *
+ * @property {Function} getByViewport - returns an object where each each viewport has a key
+ *   containing the provided argument.
+ * @property {Function} getTypeByViewport - returns a PropTypes shape validator for an object where
+ *   each viewport has a key containing the provided proptype.
+ * @property {Function} getTypeOptionallyByViewport - returns a PropTypes validator that accepts
+ *   either the provided proptype on its own, or the output of getTypeByViewport
+ */
+export const responsiveProps = {
+  getByViewport,
+  getTypeByViewport: (propType) => PropTypes.shape(getByViewport(propType)),
+  getTypeOptionallyByViewport: (propType) =>
+    PropTypes.oneOfType([propType, PropTypes.shape(getByViewport(propType))])
+}
+
+/**
+ * @typedef {0|1|2|3|4|5|6|7|8|9|10|11} SpacingIndex - value used to select a size on the spacing scale
+ *
+ * @typedef SpacingOptions
+ * @property {VariantProp} [SpacingOptions.variant] - optional theme scale variants e.g. compact, wide
+ * @property {number} [SpacingOptions.size] - optional override to force a particular pixel size
+ * @property {number} [SpacingOptions.subtract] - optional number to subtract from final pixel size
+ *
+ * @typedef SpacingObject
+ * @property {SpacingIndex} [SpacingObject.xs] - space scale index to use above xs viewport
+ * @property {SpacingIndex} [SpacingObject.sm] - space scale index to use above sm viewport
+ * @property {SpacingIndex} [SpacingObject.md] - space scale index to use above md viewport
+ * @property {SpacingIndex} [SpacingObject.lg] - space scale index to use above lg viewport
+ * @property {SpacingIndex} [SpacingObject.xl] - space scale index to use above xl viewport
+ * @property {SpacingIndex} [SpacingObject.space] - space scale index to use at all viewports
+ * @property {SpacingOptions} [SpacingObject.options] - optional options for this spacing
+ *
+ * @typedef {SpacingIndex|SpacingObject} SpacingValue
+ */
+const spacingScale = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11]
+const spacingIndexPropType = PropTypes.oneOf(spacingScale)
+const spacingObjectPropType = PropTypes.shape({
+  ...responsiveProps.getByViewport(spacingIndexPropType),
+  space: spacingIndexPropType,
+  options: PropTypes.shape({
+    variant: variantProp.propType,
+    size: PropTypes.number
+  })
+})
+/**
+ * Components and utilities that assign fixed space between components use a theme-defined spacing scale.
+ *
+ * They typically take one or more props of the {@link SpacingValue} type and turn it into a pixel size value
+ * using the hook `useSpacingScale`, which resolves any options or responsive behaviour and returns the
+ * appropriate value from the theme spacing scale.
+ *
+ * - see /ADRs/inter-component-spacing/README.md - ADR on this structure
+ * - see /src/utils/spacing/useSpacingScale.js - hook that processes spacing values
+ * - @see {@link SpacingIndex} - themes provide spacing scales of up to 12 sizes with optional theme rules.
+ * - @see {@link SpacingValue} - either a simple number referencing an index position on the spacing
+ *   scale, or an object with an optional `options` key and one or more spacing indexes keyed either by
+ *   viewports or `space` to apply at all viewports.
+ */
+export const spacingProps = {
+  scale: spacingScale,
+  types: {
+    spacingIndex: spacingIndexPropType,
+    spacingObject: spacingObjectPropType,
+
+    // Most spacing components and utilities take this prop / arg type:
+    spacingValue: PropTypes.oneOfType([spacingIndexPropType, spacingObjectPropType])
+  }
+}
 
 /**
  * Returns a prop type validator which checks whether a prop is either a component or an array of components of a given
@@ -347,3 +577,5 @@ export const componentPropType = (passedName, checkDisplayName = false) => {
 
   return validate
 }
+
+export const copyPropTypes = PropTypes.oneOf(['en', 'fr'])

package/src/utils/useCopy.js

@@ -0,0 +1,39 @@
+export const DEFAULT_COPY = 'en'
+
+/**
+ * Extract translations from a keyed dictionary for a given language.
+ * Returns a getter.
+ *
+ * @example
+ * const getCopy = useCopy({
+ *   copy: 'en',
+ *   dictionary: {
+ *     en: { label: 'english label' },
+ *     fr: { label: 'french label' }
+ *   }
+ * })
+ *
+ * getCopy('label') => 'english label'
+ *
+ * @description The entire dictionary may be overridden by simply passing a single language object as `copy`:
+ * @example
+ * const getCopy = useCopy({
+ *   copy: { label: 'custom label' }
+ * })
+ *
+ * getCopy('label') => 'custom label'
+ *
+ * @param {object} [dictionary]
+ * @param {'en'|'fr'|object} copy - language
+ * @return {function(string): string}
+ */
+function useCopy({ dictionary, copy = DEFAULT_COPY }) {
+  if (typeof copy === 'string') {
+    return (key) => (key ? dictionary[copy][key] : dictionary[copy])
+  }
+
+  // support overriding the entire copy dictionary with an object for a single language
+  return (key) => copy[key]
+}
+
+export default useCopy

package/src/utils/useHash.js

@@ -0,0 +1,39 @@
+import { useEffect, useState } from 'react'
+
+const doAction = (action, event) =>
+  typeof action === 'function' && action(window?.location?.hash, event)
+
+/**
+ * @typedef {import('react').SyntheticEvent} SyntheticEvent
+ */
+
+/**
+ * Calls a function (passing it the current hash) based on the current hash state on mount,
+ * and binds it to call it again any time the hash changes.
+ *
+ * Consider using `useCallback` on the function to minimise adding and removing of event listeners.
+ *
+ * On Native, this is replaced with a harmless no-op function as there is no direct equivalent.
+ *
+ * @param {(hash: string, event?: SyntheticEvent) => void} action - a function to act on the current hash on load and when it changes
+ * @returns
+ */
+const useHash = (action, isReady = true) => {
+  const [isDone, setIsDone] = useState(false)
+  // Do the action just once when ready after component mount, from hash on page load
+  const isToDo = isReady && !isDone
+  useEffect(() => {
+    if (isToDo) {
+      setIsDone(true)
+      doAction(action)
+    }
+  }, [isToDo, action])
+
+  // Bind the action for each hash change; do re-bind if the function changes.
+  useEffect(() => {
+    const handleChange = (event) => doAction(action, event)
+    window.addEventListener('hashchange', handleChange)
+    return () => window.removeEventListener('hashchange', handleChange)
+  }, [action])
+}
+export default useHash

package/src/utils/useHash.native.js

@@ -0,0 +1,6 @@
+/**
+ * No URL hashes on Native, so do a no-op. Remembering scenes for reloads
+ * is handled at OS level and deep links have completely different usage.
+ */
+const useHash = () => {}
+export default useHash

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