@telus-uds/components-base 1.2.0 → 1.3.0

package/src/utils/propTypes.js

@@ -1,561 +0,0 @@
-import PropTypes from 'prop-types'
-import { Linking, Platform } from 'react-native'
-import { components as tokenKeys } from '@telus-uds/system-theme-tokens'
-import a11yPropTypes from './a11y/propTypes'
-
-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.
-   *
-   * Contains an object with keys that correspond to the current component theme's allowed
-   * appearances and values that correspond to the allowed values of that component.
-   *
-   * Since the particular keys and values depend on which theme is currently active,
-   * the exact shape of variant props is not enforced using PropTypes.
-   */
-  propType: PropTypes.objectOf(
-    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)])
-
-export const getTokenNames = (componentName) => {
-  const componentTokenSchema = tokenKeys[componentName]
-  if (!componentTokenSchema) {
-    throw new Error(`No "${componentName}" tokenKeys in @telus-uds/system-theme-tokens`)
-  }
-  return Object.keys(componentTokenSchema)
-}
-
-/**
- * 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 = (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.
- *
- * 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 = (...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)
-  return (props) =>
-    Object.entries(props).reduce(
-      (items, [key, value]) =>
-        keys.includes(key) || (regexp && regexp.test(key))
-          ? {
-              ...items,
-              [key]: value
-            }
-          : items,
-      {}
-    )
-}
-
-export const a11yProps = {
-  /**
-   * Proptypes for recognised React Native accessiblity (a11y) props.
-   * Spread this in the propTypes of components that accept React Native a11y props.
-   */
-  types: a11yPropTypes,
-  /**
-   * Filters a props object, returning only recognised React Native accessiblity (a11y) props.
-   *
-   * Where components accept React Native a11y props, pass { ...rest } from its props to this,
-   * then spread the returned object into the component's props (usually its outer container).
-   */
-  select: getPropSelector(a11yPropTypes, /^aria-/),
-  /**
-   * 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
-    ...Platform.select({
-      web: {
-        accessibilityHidden: true // web screenreaders
-      },
-      android: {
-        importantForAccessibility: 'no-hide-descendants'
-      },
-      ios: {
-        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.
-const targetValues = ['_self', '_blank', '_parent', '_top']
-export const hrefAttrsProp = {
-  types: {
-    // React Native Web >= 0.15.0 supports hrefAttrs prop with only these properties
-    // and passes them to <a> if an element has a href prop or accessibilityRole "link"
-    download: PropTypes.string,
-    rel: PropTypes.string,
-    target: PropTypes.oneOf(targetValues)
-  },
-  /**
-   * Takes a props object, bundles any hrefAttrs props present into one object
-   * and returns that keyed as `hrefAttrs` and non-hrefAttrs props keyed as `rest`
-   */
-  bundle: ({ download, rel, target, ...rest }) => ({
-    hrefAttrs: {
-      download,
-      rel,
-      target
-    },
-    rest
-  })
-}
-
-const pressHandlerPropTypes = {
-  onPress: PropTypes.func,
-  onPressIn: PropTypes.func,
-  onPressOut: PropTypes.func,
-  ...Platform.select({
-    web: {
-      onMouseEnter: PropTypes.func,
-      onMouseLeave: PropTypes.func,
-      onFocus: PropTypes.func,
-      onBlur: PropTypes.func
-    },
-    default: {
-      onLongPress: PropTypes.func
-    }
-  })
-}
-
-const pressPropTypes = {
-  ...pressHandlerPropTypes,
-  disabled: PropTypes.bool,
-  ...Platform.select({
-    web: {},
-    default: {
-      hitSlop: PropTypes.number,
-      pressRetentionOffset: PropTypes.oneOfType([PropTypes.number, rectProp.propType])
-    }
-  })
-}
-
-export const pressProps = {
-  /**
-   * Proptypes for clickable or pressable components, including web-only props
-   */
-  types: pressPropTypes,
-  /**
-   * Filters a props object, returning only the platform-relevant press props defined above
-   */
-  select: getPropSelector(pressPropTypes),
-  selectHandlers: getPropSelector(pressHandlerPropTypes)
-}
-
-const clickHandlerMapping = {
-  onClick: 'onPress',
-  mouseDown: 'onPressIn',
-  mouseUp: 'onPressOut'
-}
-
-export const clickProps = {
-  /**
-   * Web-oriented HTML click handlers that may be mapped to React Native press handlers
-   */
-  types: Object.fromEntries(
-    Object.keys(clickHandlerMapping).map((mouseName) => [mouseName, PropTypes.func])
-  ),
-  /**
-   * Takes a set of props and converts HTML mouse click oriented event handlers to closest
-   * equivalent React Native press event handler.
-   *
-   * Use this when a component that expects press-oriented props may need to support third-party
-   * web-oriented tooling that injects web-oriented event handlers directly. For example, for
-   * to support use with NextJS's 'next/link' component, which injects `onClick` prop into its child.
-   */
-  toPressProps: (props) =>
-    Object.fromEntries(
-      Object.entries(props).map(([originalName, value]) => {
-        const translatedName = clickHandlerMapping[originalName]
-        return translatedName ? [translatedName, value] : [originalName, value]
-      })
-    )
-}
-
-const linkPropTypes = {
-  ...pressPropTypes,
-  href: PropTypes.string,
-  hrefAttrs: PropTypes.shape(hrefAttrsProp.types),
-  ...a11yPropTypes
-}
-
-export const linkProps = {
-  /**
-   * Proptypes for components that, on Web, can output <a href="..."> link elements
-   */
-  types: linkPropTypes,
-  /**
-   * Filters a props object, returning only the platform-relevant link props defined above
-   */
-  select: getPropSelector(linkPropTypes),
-  /**
-   * 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 }) => {
-    if (!href && !onPress) {
-      throw new Error('handleHref requires either href or onPress')
-    }
-    return Platform.select({
-      web: onPress,
-      default: (...args) => {
-        if (onPress) onPress(...args)
-        if (href) Linking.openURL(href)
-      }
-    })
-  }
-}
-
-const viewPropTypes = {
-  pointerEvents: PropTypes.oneOf(['all', 'none', 'box-only', 'box-none']),
-  onLayout: PropTypes.func,
-  nativeID: PropTypes.string,
-  testID: PropTypes.string,
-  dataSet: PropTypes.object
-}
-
-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 type, based on their `name` or `displayName` properties.
- * Use an array of strings for `passedName` to accept more than one component type.
- * For an array the validation fails on the first occurrence of an invalid element.
- *
- * @param {string|string[]} passedName
- * @return {function}
- */
-export const componentPropType = (passedName) => {
-  const passedNames = typeof passedName === 'string' ? [passedName] : passedName
-
-  const checkProp = (props, propName, componentName) => {
-    if (props[propName] === undefined || props[propName] === null) {
-      return undefined
-    }
-
-    if (Array.isArray(props[propName])) {
-      // Iterates through every child and try to find the first element that does not match the passed name
-      // https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean
-      return props[propName]
-        .map((_, index) => checkProp(props[propName], index, componentName))
-        .find(Boolean)
-    }
-
-    const nameInProp = props[propName].type?.displayName || props[propName].type?.name
-    if (!nameInProp || !passedNames.includes(nameInProp)) {
-      const propDescription = nameInProp ? `Component ${nameInProp}` : typeof props[propName]
-      return new Error(
-        `${componentName}: ${propDescription} was passed to \`${propName}\` prop; should be ${passedNames.join(
-          ' or '
-        )}`
-      )
-    }
-    return undefined
-  }
-
-  const checkRequired = (props, propName, componentName) => {
-    if (props[propName] === undefined) {
-      return new Error(
-        `The prop \`${propName}\` is marked as required in \`${componentName}\`, but its value is ${props[propName]}.`
-      )
-    }
-    return undefined
-  }
-
-  const createValidate = (isRequired) => {
-    if (isRequired) {
-      return (props, propName, componentName) => {
-        const checkForError = checkProp(props, propName, componentName)
-
-        if (checkForError) {
-          return checkForError
-        }
-
-        return checkRequired(props, propName, componentName)
-      }
-    }
-
-    return checkProp
-  }
-
-  const validate = createValidate()
-  validate.isRequired = createValidate(true)
-
-  return validate
-}
-
-export const copyPropTypes = PropTypes.oneOf(['en', 'fr'])