@telus-uds/components-base 1.0.1 → 1.3.0

package/src/utils/props/tokens.js

@@ -0,0 +1,150 @@
+import PropTypes from 'prop-types'
+import { components as tokenKeys } from '@telus-uds/system-theme-tokens'
+
+// 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
+}

package/src/utils/props/variantProp.js

@@ -0,0 +1,20 @@
+import PropTypes from 'prop-types'
+
+/**
+ * @typedef {{[key: string]: string|number|boolean}} AppearanceSet
+ * @typedef {AppearanceSet} VariantProp
+ */
+export default {
+  /**
+   * '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])
+  )
+}

package/src/utils/props/viewProps.js

@@ -0,0 +1,23 @@
+import PropTypes from 'prop-types'
+import getPropSelector from './getPropSelector'
+
+const viewPropTypes = {
+  pointerEvents: PropTypes.oneOf(['all', 'none', 'box-only', 'box-none']),
+  onLayout: PropTypes.func,
+  nativeID: PropTypes.string,
+  testID: PropTypes.string,
+  dataSet: PropTypes.object
+}
+
+export default {
+  /**
+   * 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)
+}

package/src/utils/useResponsiveProp.js

@@ -36,7 +36,7 @@ export const resolveResponsiveProp = (prop, viewport, defaultValue) => {
  * 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`.
+ * To generate propTypes for responsive props, see `responsiveProps` in `./utils/props/responsiveProps.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

package/src/utils/useSpacingScale.js

@@ -3,10 +3,10 @@ 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('./props/spacingProps.js').SpacingValue} SpacingValue
+ * @typedef {import('./props/spacingProps.js').SpacingIndex} SpacingIndex
+ * @typedef {import('./props/spacingProps.js').SpacingObject} SpacingObject
+ * @typedef {import('./props/spacingProps.js').SpacingOptions} SpacingOptions
  */
 
 const resolveSpacingOptions = (space) => {

package/src/utils/withLinkRouter.jsx

@@ -0,0 +1,68 @@
+import React, { forwardRef } from 'react'
+import PropTypes from 'prop-types'
+
+// Prototype-safe alternative to (linter-forbidden) someObject.hasOwnProperty()
+const hasOwnProperty = (object, prop) => Object.prototype.hasOwnProperty.call(object, prop)
+
+/**
+ * Higher-order component that has no effect unless an additional prop `LinkRouter` is passed.
+ * This may be used to provide custom wrappers for integrations with third party libraries.
+ *
+ * If LinkRouter is passed, LinkRouter is rendered in place of the main component and is passed:
+ *
+ *  - `linkRouterProps`: an optional object passed alongside LinkRouter, for props needed by the wrapper
+ *    that are not valid props for the wrapped component.
+ *  - `Component`: automatically provided, the original component to render inside the wrapper.
+ *  - `ref`: forwarded `ref` passed down to `Component`
+ *  - All other props passed to the outer component
+ *
+ * @example A LinkRouter component to be used with link-like components might look like:
+ *
+ * ```jsx
+ * const LinkLinkRouter = forwardRef(({ Component, linkRouterProps: { to, options }, href, ...rest }, ref) => {
+ *   const { href: resolvedHref, onClick } = useSomeRouterHook({ to, href, options })
+ *   return <Component href={resolvedHref} onPress={onClick} {...rest} />
+ * })
+ * ```
+ *
+ * Any component that takes href and onPress props may then use this wrapper:
+ *
+ * ```jsx
+ * <Link href={href} LinkRouter={LinkLinkRouter} linkRouterProps={{ to, options }}>Some link</Link>
+ * <IconButton icon={SomeIcon} LinkRouter={LinkLinkRouter} linkRouterProps={{ to, options }} ref={iconRef} />
+ * ```
+ */
+const withLinkRouter = (Component) => {
+  const wrappedComponent = forwardRef(({ LinkRouter, linkRouterProps, ...props }, ref) => {
+    if (!LinkRouter) return <Component {...props} ref={ref} />
+    return (
+      <LinkRouter linkRouterProps={linkRouterProps} Component={Component} ref={ref} {...props} />
+    )
+  })
+
+  // Ensure the returned component has appropriate outer properties set:
+  /* eslint-disable-next-line react/forbid-foreign-prop-types */
+  const { displayName, name, propTypes, ...otherProperties } = Component
+
+  // Apply unique component name as a displayName
+  wrappedComponent.displayName = Component.displayName || Component.name
+
+  // Apply proptypes including wrapper props - is safely { ...undefined, ...undefined } in prod
+  wrappedComponent.propTypes = { ...Component.propTypes, ...withLinkRouter.propTypes }
+
+  // Forward any other properties explicitly set e.g. Component.SubComponent
+  Object.keys(otherProperties).forEach((key) => {
+    // Skip internal React properties from wrappedComponent's forwardRef (render, $$typeof, etc)
+    if (hasOwnProperty(Component, key) && !hasOwnProperty(wrappedComponent, key)) {
+      wrappedComponent[key] = Component[key]
+    }
+  })
+  return wrappedComponent
+}
+
+withLinkRouter.propTypes = {
+  LinkRouter: PropTypes.elementType,
+  linkRouterProps: PropTypes.object
+}
+
+export default withLinkRouter

package/stories/A11yText/A11yText.stories.jsx

@@ -12,7 +12,7 @@ const defaultArgs = {
 }
 
 export default {
-  title: 'Base/A11yText',
+  title: 'A11yText',
   component: A11yText,
   parameters: defaultArgs
 }

package/stories/ActivityIndicator/ActivityIndicator.stories.jsx

@@ -4,7 +4,7 @@ import { ActivityIndicator } from '../../src'
 import { EachParentType, parentTypesParams } from '../supports'
 
 export default {
-  title: 'Base/ActivityIndicator',
+  title: 'ActivityIndicator',
   component: ActivityIndicator,
   args: {
     label: 'loading...'

package/stories/Box/Box.stories.jsx

@@ -12,7 +12,7 @@ import {
 } from '../supports'
 
 export default {
-  title: 'Base/Box',
+  title: 'Box',
   component: Box
 }
 

package/stories/Button/Button.stories.jsx

@@ -10,7 +10,7 @@ Default.storyName = 'Button'
 const defaultLabel = "I'm a button"
 
 export default {
-  title: 'Base/Button',
+  title: 'Button',
   component: Button,
   args: {
     // eslint-disable-next-line no-console

package/stories/Button/ButtonGroup.stories.jsx

@@ -22,7 +22,7 @@ const defaultControlledArgs = {
 }
 
 export default {
-  title: 'Base/ButtonGroup',
+  title: 'ButtonGroup',
   component: ButtonGroup,
   args: {
     ...defaultArgs

package/stories/Button/ButtonLink.stories.jsx

@@ -3,7 +3,7 @@ import { ButtonLink } from '../../src'
 import { Container, useVariants } from '../supports'
 
 export default {
-  title: 'Base/ButtonLink',
+  title: 'ButtonLink',
   component: ButtonLink,
   args: {
     children: "I'm a button link",

package/stories/Card/Card.stories.jsx

@@ -6,7 +6,7 @@ import { Card } from '../../src'
 import { Container, useVariants, EachParentType, parentTypesParams } from '../supports'
 
 export default {
-  title: 'Base/Card',
+  title: 'Card',
   component: Card
 }
 

package/stories/Checkbox/Checkbox.stories.jsx

@@ -5,7 +5,7 @@ import { Checkbox, CheckboxGroup, Typography } from '../../src'
 import { Container, EachParentType, parentTypesParams } from '../supports'
 
 export default {
-  title: 'Base/Checkbox',
+  title: 'Checkbox',
   component: Checkbox,
   argTypes: {
     checked: {

package/stories/Divider/Divider.stories.jsx

@@ -5,7 +5,7 @@ import { Divider, Typography } from '../../src'
 import { EachParentType, parentTypesParams } from '../supports'
 
 export default {
-  title: 'Base/Divider',
+  title: 'Divider',
   component: Divider
 }
 

package/stories/ExpandCollapse/ExpandCollapse.stories.jsx

@@ -6,7 +6,7 @@ import { Container, EachParentType, parentTypesParams } from '../supports'
 import { useMultipleInputValues } from '../../src/utils'
 
 export default {
-  title: 'Base/ExpandCollapse',
+  title: 'ExpandCollapse',
   component: ExpandCollapse,
   args: {
     children: () => {}

package/stories/Feedback/Feedback.stories.jsx

@@ -5,7 +5,7 @@ import { Feedback, Typography, TextInput } from '../../src'
 import { Container } from '../supports'
 
 export default {
-  title: 'Base/Feedback',
+  title: 'Feedback',
   component: Feedback
 }
 

package/stories/FlexGrid/01 FlexGrid.stories.jsx

@@ -7,7 +7,7 @@ import { Placeholder, EachParentType, parentTypesParams } from '../supports'
 const { Row, Col } = FlexGrid
 
 export default {
-  title: 'Base/FlexGrid/FlexGrid',
+  title: 'FlexGrid/FlexGrid',
   component: FlexGrid
 }
 

package/stories/FlexGrid/02 Row.stories.jsx

@@ -6,7 +6,7 @@ import { Placeholder } from '../supports'
 const { Row, Col } = FlexGrid
 
 export default {
-  title: 'Base/FlexGrid/Row',
+  title: 'FlexGrid/Row',
   component: Row
 }
 

package/stories/FlexGrid/03 Col.stories.jsx

@@ -6,7 +6,7 @@ import { Placeholder } from '../supports'
 const { Row, Col } = FlexGrid
 
 export default {
-  title: 'Base/FlexGrid/Col',
+  title: 'FlexGrid/Col',
   component: Col,
   argTypes: {
     xs: {

package/stories/Icon/Icon.stories.jsx

@@ -7,7 +7,7 @@ import { Container, useVariants, EachIcon, EachParentType, parentTypesParams } f
 import { Icon, StackWrap, Tooltip } from '../../src'
 
 export default {
-  title: 'Base/Icon',
+  title: 'Icon',
   component: Icon,
   argTypes: {
     label: {

package/stories/IconButton/IconButton.stories.jsx

@@ -8,7 +8,7 @@ import { Box, IconButton, StackView } from '../../src'
 import { useVariants, EachParentType, parentTypesParams } from '../supports'
 
 export default {
-  title: 'Base/IconButton',
+  title: 'IconButton',
   component: IconButton
 }
 

package/stories/InputLabel/InputLabel.stories.jsx

@@ -4,7 +4,7 @@ import React from 'react'
 import InputLabel from '../../src/InputLabel/InputLabel'
 
 export default {
-  title: 'Base/InputLabel',
+  title: 'InputLabel',
   component: InputLabel
 }
 

package/stories/Link/ChevronLink.stories.jsx

@@ -5,7 +5,7 @@ import { ChevronLink } from '../../src'
 import { Container, EachParentType, parentTypesParams, useVariants } from '../supports'
 
 export default {
-  title: 'Base/ChevronLink',
+  title: 'ChevronLink',
   component: ChevronLink,
   args: {
     href: 'https://example.com'

package/stories/Link/Link.stories.jsx

@@ -8,7 +8,7 @@ import { Link, Typography, variantProp } from '../../src'
 import { Container, EachIcon, EachParentType, parentTypesParams, useVariants } from '../supports'
 
 export default {
-  title: 'Base/Link',
+  title: 'Link',
   component: Link,
   args: {
     href: `https://telus.com/?unvisited:${Date.now()}`,

package/stories/Link/TextButton.stories.jsx

@@ -10,7 +10,7 @@ import { TextButton, variantProp } from '../../src'
 import { Container, EachParentType, useVariants, parentTypesParams } from '../supports'
 
 export default {
-  title: 'Base/TextButton',
+  title: 'TextButton',
   component: TextButton,
   args: {
     // eslint-disable-next-line no-console

package/stories/List/List.stories.jsx

@@ -9,7 +9,7 @@ import { useVariants, Container } from '../supports'
 import { List, Typography } from '../../src'
 
 export default {
-  title: 'Base/List',
+  title: 'List',
   component: List
 }
 

package/stories/Modal/Modal.stories.jsx

@@ -3,7 +3,7 @@ import React, { useState } from 'react'
 import { Button, Modal, Spacer, Typography } from '../../src'
 
 export default {
-  title: 'Base/Modal',
+  title: 'Modal',
   component: Modal
 }
 

package/stories/Notification/Notification.stories.jsx

@@ -6,7 +6,7 @@ import { Link, Notification, Typography } from '../../src'
 import { Container } from '../supports'
 
 export default {
-  title: 'Base/Notification',
+  title: 'Notification',
   component: Notification
 }
 

package/stories/Pagination/Pagination.stories.jsx

@@ -6,7 +6,7 @@ import { Pagination, Typography } from '../../src'
 import { Container, EachParentType, parentTypesParams } from '../supports'
 
 export default {
-  title: 'Base/Pagination',
+  title: 'Pagination',
   component: Pagination
 }
 

package/stories/Progress/Progress.stories.jsx

@@ -5,7 +5,7 @@ import { Progress, StackView, Typography } from '../../src'
 import { Container, EachParentType, parentTypesParams } from '../supports'
 
 export default {
-  title: 'Base/Progress',
+  title: 'Progress',
   component: Progress.Bar,
   args: { accessibilityLabel: 'Progress Bar' }
 }

package/stories/Radio/Radio.stories.jsx

@@ -5,7 +5,7 @@ import { Radio, RadioGroup, Typography } from '../../src'
 import { Container, EachParentType, parentTypesParams } from '../supports'
 
 export default {
-  title: 'Base/Radio',
+  title: 'Radio',
   component: Radio,
   argTypes: {
     checked: {

package/stories/RadioCard/RadioCard.stories.jsx

@@ -5,7 +5,7 @@ import { RadioCard, RadioCardGroup, Typography } from '../../src'
 import { Container, EachParentType, parentTypesParams } from '../supports'
 
 export default {
-  title: 'Base/RadioCard',
+  title: 'RadioCard',
   component: RadioCard
 }
 

package/stories/Search/Search.stories.jsx

@@ -3,7 +3,7 @@ import React from 'react'
 import { Search } from '../../src'
 
 export default {
-  title: 'Base/Search',
+  title: 'Search',
   component: Search
 }
 

package/stories/Select/Select.stories.jsx

@@ -4,7 +4,7 @@ import { Text } from 'react-native'
 import { Select } from '../../src'
 
 export default {
-  title: 'Base/Select',
+  title: 'Select',
   component: Select
 }
 

package/stories/SideNav/SideNav.stories.jsx

@@ -5,7 +5,7 @@ import { SideNav } from '../../src'
 import { EachParentType, parentTypesParams } from '../supports'
 
 export default {
-  title: 'Base/SideNav',
+  title: 'SideNav',
   component: SideNav
 }
 

package/stories/SideNav/SideNavItem.stories.jsx

@@ -2,7 +2,7 @@ import React from 'react'
 import { SideNav } from '../../src'
 
 export default {
-  title: 'Base/SideNav/Item',
+  title: 'SideNav/Item',
   component: SideNav.Item
 }
 

package/stories/SideNav/SideNavItemsGroup.stories.jsx

@@ -2,7 +2,7 @@ import React from 'react'
 import { SideNav } from '../../src'
 
 export default {
-  title: 'Base/SideNav/Items Group',
+  title: 'SideNav/Items Group',
   component: SideNav.ItemsGroup
 }
 

package/stories/Skeleton/Skeleton.stories.jsx

@@ -6,7 +6,7 @@ import StackView from '../../src/StackView'
 import { Skeleton } from '../../src'
 
 export default {
-  title: 'Base/Skeleton',
+  title: 'Skeleton',
   component: Skeleton
 }
 

package/stories/Spacer/Spacer.stories.jsx

@@ -6,7 +6,7 @@ import { Spacer, Typography } from '../../src'
 import { Container } from '../supports'
 
 export default {
-  title: 'Base/Spacer',
+  title: 'Spacer',
   component: Spacer
 }
 

package/stories/StackView/StackView.stories.jsx

@@ -6,7 +6,7 @@ import { View } from 'react-native'
 import { StackView, Card, Typography, Button } from '../../src'
 
 export default {
-  title: 'Base/StackView',
+  title: 'StackView',
   component: StackView
 }
 

package/stories/StackView/StackWrap.stories.jsx

@@ -5,7 +5,7 @@ import { StyleSheet, View } from 'react-native'
 import { StackWrap, Button } from '../../src'
 
 export default {
-  title: 'Base/StackWrap',
+  title: 'StackWrap',
   component: StackWrap
 }