@telus-uds/components-base 1.0.1 → 1.3.0

package/src/utils/props/a11yProps.js

@@ -0,0 +1,151 @@
+import PropTypes from 'prop-types'
+import { Platform } from 'react-native'
+import getPropSelector from './getPropSelector'
+
+// React Native exports a11y prop definitions as TypeScript Interfaces, but no longer exports PropTypes
+// so we have to define them ourselves.
+const nativeA11yPropTypes = {
+  accessible: PropTypes.bool,
+  focusable: PropTypes.bool,
+
+  accessibilityElementsHidden: PropTypes.bool,
+  accessibilityHint: PropTypes.string, // react-native-web ignores `accessibilityHint`
+  accessibilityIgnoresInvertColors: PropTypes.bool,
+  accessibilityLabel: PropTypes.string,
+  accessibilityRole: PropTypes.string,
+  accessibilityActions: PropTypes.arrayOf(
+    PropTypes.shape({
+      name: PropTypes.string.isRequired,
+      label: PropTypes.string
+    })
+  ),
+  accessibilityLiveRegion: PropTypes.oneOf(['none', 'polite', 'assertive']),
+  accessibilityState: PropTypes.shape({
+    disabled: PropTypes.bool,
+    selected: PropTypes.bool,
+    checked: PropTypes.oneOf([true, false, 'mixed']),
+    busy: PropTypes.bool,
+    expanded: PropTypes.bool
+  }),
+  accessibilityValue: PropTypes.shape({
+    min: PropTypes.number,
+    max: PropTypes.number,
+    now: PropTypes.number,
+    text: PropTypes.string
+  }),
+  accessibilityViewIsModal: PropTypes.bool,
+  importantForAccessibility: PropTypes.oneOf(['auto', 'yes', 'no', 'no-hide-descendants']),
+  onAccessibilityAction: PropTypes.func,
+  onAccessibilityEscape: PropTypes.func,
+  onAccessibilityTap: PropTypes.func
+}
+
+const a11yPropTypes = {
+  ...nativeA11yPropTypes,
+  // React Native Web adds many a11y props that alias aria-* attributes
+  // Types based on https://necolas.github.io/react-native-web/docs/accessibility/
+  accessibilityActiveDescendant: PropTypes.string,
+  accessibilityAtomic: PropTypes.bool,
+  accessibilityAutoComplete: PropTypes.string,
+  accessibilityBusy: PropTypes.bool,
+  accessibilityChecked: PropTypes.oneOf([true, false, 'mixed']),
+  accessibilityColumnCount: PropTypes.number,
+  accessibilityColumnIndex: PropTypes.number,
+  accessibilityColumnSpan: PropTypes.number,
+  accessibilityControls: PropTypes.oneOfType([
+    PropTypes.string,
+    PropTypes.arrayOf(PropTypes.string)
+  ]),
+  accessibilityCurrent: PropTypes.oneOf([true, false, 'page', 'step', 'location', 'date', 'time']),
+  accessibilityDescribedBy: PropTypes.oneOfType([
+    PropTypes.string,
+    PropTypes.arrayOf(PropTypes.string)
+  ]),
+  accessibilityDetails: PropTypes.string,
+  accessibilityDisabled: PropTypes.bool,
+  accessibilityErrorMessage: PropTypes.string,
+  accessibilityExpanded: PropTypes.bool,
+  accessibilityFlowTo: PropTypes.oneOfType([PropTypes.string, PropTypes.arrayOf(PropTypes.string)]),
+  accessibilityHasPopup: PropTypes.string,
+  accessibilityHidden: PropTypes.bool,
+  accessibilityInvalid: PropTypes.bool,
+  accessibilityKeyShortcuts: PropTypes.string,
+  accessibilityLabelledBy: PropTypes.oneOfType([
+    PropTypes.string,
+    PropTypes.arrayOf(PropTypes.string)
+  ]),
+  accessibilityLevel: PropTypes.number,
+  accessibilityModal: PropTypes.bool,
+  accessibilityMultiline: PropTypes.bool,
+  accessibilityMultiSelectable: PropTypes.bool,
+  accessibilityOrientation: PropTypes.oneOf(['horizontal', 'vertical']),
+  accessibilityOwns: PropTypes.oneOfType([PropTypes.string, PropTypes.arrayOf(PropTypes.string)]),
+  accessibilityPlaceholder: PropTypes.string,
+  accessibilityPosInSet: PropTypes.number,
+  accessibilityPressed: PropTypes.bool,
+  accessibilityReadOnly: PropTypes.bool,
+  accessibilityRequired: PropTypes.bool,
+  accessibilityRoleDescription: PropTypes.string,
+  accessibilityRowCount: PropTypes.number,
+  accessibilityRowIndex: PropTypes.number,
+  accessibilityRowSpan: PropTypes.number,
+  accessibilitySelected: PropTypes.bool,
+  accessibilitySetSize: PropTypes.number,
+  accessibilitySort: PropTypes.oneOf(['ascending', 'descending', 'none', 'other']),
+  accessibilityValueMax: PropTypes.number,
+  accessibilityValueMin: PropTypes.number,
+  accessibilityValueNow: PropTypes.number,
+  accessibilityValueText: PropTypes.string
+}
+
+export default {
+  /**
+   * 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: {}
+    })
+}

package/src/utils/props/clickProps.js

@@ -0,0 +1,31 @@
+import PropTypes from 'prop-types'
+
+const clickHandlerMapping = {
+  onClick: 'onPress',
+  mouseDown: 'onPressIn',
+  mouseUp: 'onPressOut'
+}
+
+export default {
+  /**
+   * 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]
+      })
+    )
+}

package/src/utils/props/componentPropType.js

@@ -0,0 +1,67 @@
+/**
+ * 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 default function 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
+}

package/src/utils/props/copyPropTypes.js

@@ -0,0 +1,3 @@
+import PropTypes from 'prop-types'
+
+export default PropTypes.oneOf(['en', 'fr'])

package/src/utils/props/getPropSelector.js

@@ -0,0 +1,14 @@
+export default 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,
+      {}
+    )
+}

package/src/utils/props/hrefAttrsProp.js

@@ -0,0 +1,25 @@
+import PropTypes from 'prop-types'
+
+// Props related to HTML <a> anchor link attributes.
+const targetValues = ['_self', '_blank', '_parent', '_top']
+export default {
+  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
+  })
+}

package/src/utils/props/index.js

@@ -0,0 +1,15 @@
+export * from './tokens'
+export { default as a11yProps } from './a11yProps'
+export { default as clickProps } from './clickProps'
+export { default as copyPropTypes } from './copyPropTypes'
+export { default as componentPropType } from './componentPropType'
+export { default as hrefAttrsProp } from './hrefAttrsProp'
+export { default as linkProps } from './linkProps'
+export { default as pressProps } from './pressProps'
+export { default as paddingProp } from './paddingProp'
+export { default as rectProp } from './rectProp'
+export { default as responsiveProps } from './responsiveProps'
+export { default as spacingProps } from './spacingProps'
+export { default as selectSystemProps } from './selectSystemProps'
+export { default as variantProp } from './variantProp'
+export { default as viewProps } from './viewProps'

package/src/utils/props/linkProps.js

@@ -0,0 +1,43 @@
+import { Linking, Platform } from 'react-native'
+import PropTypes from 'prop-types'
+import { pressPropTypes } from './pressProps'
+import a11yProps from './a11yProps'
+import hrefAttrsProp from './hrefAttrsProp'
+import getPropSelector from './getPropSelector'
+
+const linkPropTypes = {
+  ...pressPropTypes,
+  href: PropTypes.string,
+  hrefAttrs: PropTypes.shape(hrefAttrsProp.types),
+  ...a11yProps.types
+}
+
+export default {
+  /**
+   * 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)
+      }
+    })
+  }
+}

package/src/utils/props/paddingProp.js

@@ -0,0 +1,10 @@
+import PropTypes from 'prop-types'
+
+export default {
+  propType: PropTypes.shape({
+    paddingBottom: PropTypes.number,
+    paddingLeft: PropTypes.number,
+    paddingRight: PropTypes.number,
+    paddingTop: PropTypes.number
+  })
+}

package/src/utils/props/pressProps.js

@@ -0,0 +1,45 @@
+import { Platform } from 'react-native'
+import PropTypes from 'prop-types'
+import rectProp from './rectProp'
+import getPropSelector from './getPropSelector'
+
+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
+    }
+  })
+}
+
+export const pressPropTypes = {
+  ...pressHandlerPropTypes,
+  disabled: PropTypes.bool,
+  ...Platform.select({
+    web: {},
+    default: {
+      hitSlop: PropTypes.number,
+      pressRetentionOffset: PropTypes.oneOfType([PropTypes.number, rectProp.propType])
+    }
+  })
+}
+
+export default {
+  /**
+   * 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)
+}

package/src/utils/props/rectProp.js

@@ -0,0 +1,10 @@
+import PropTypes from 'prop-types'
+
+export default {
+  propType: PropTypes.shape({
+    bottom: PropTypes.number,
+    left: PropTypes.number,
+    right: PropTypes.number,
+    top: PropTypes.number
+  })
+}

package/src/utils/props/responsiveProps.js

@@ -0,0 +1,30 @@
+import PropTypes from 'prop-types'
+
+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 default {
+  getByViewport,
+  getTypeByViewport: (propType) => PropTypes.shape(getByViewport(propType)),
+  getTypeOptionallyByViewport: (propType) =>
+    PropTypes.oneOfType([propType, PropTypes.shape(getByViewport(propType))])
+}

package/src/utils/props/selectSystemProps.js

@@ -0,0 +1,25 @@
+// Returns a selector for requested prop kinds as well as the propTypes for
+// those props merged into one object
+export default function selectSystemProps(systemPropHelpers) {
+  const selectProps = (props) =>
+    systemPropHelpers.reduce((acc, propHelper) => {
+      if (typeof propHelper?.select !== 'function') {
+        throw new Error(
+          `An invalid system prop helper has been passed to 'selectSystemProps': prop selector ('.select') is missing in ${propHelper}`
+        )
+      }
+
+      return { ...acc, ...propHelper.select(props) }
+    }, {})
+  const selectedPropTypes = systemPropHelpers.reduce((acc, propHelper) => {
+    if (!propHelper?.types) {
+      throw new Error(
+        `An invalid system prop helper has been passed to 'selectSystemProps': types selector ('.types') is missing in ${propHelper}`
+      )
+    }
+
+    return { ...acc, ...propHelper.types }
+  }, {})
+
+  return [selectProps, selectedPropTypes]
+}

package/src/utils/props/spacingProps.js

@@ -0,0 +1,58 @@
+import PropTypes from 'prop-types'
+import responsiveProps from './responsiveProps'
+import variantProp from './variantProp'
+
+/**
+ * @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 default {
+  scale: spacingScale,
+  types: {
+    spacingIndex: spacingIndexPropType,
+    spacingObject: spacingObjectPropType,
+
+    // Most spacing components and utilities take this prop / arg type:
+    spacingValue: PropTypes.oneOfType([spacingIndexPropType, spacingObjectPropType])
+  }
+}