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

package/src/utils/input.js

@@ -1,4 +1,4 @@
-import { useCallback, useState } from 'react'
+import { useCallback, useRef, useState } from 'react'
 
 const pluralHooks = ['useMultipleInputValues']
 
@@ -44,16 +44,18 @@ Consumers of this hook must be one of:
  * management tools such as Formik and React Hooks Form.
  *
  * @param {object} props
- * @param {any} [props.value] - for a controlled input, the active values as set by a parent
- * @param {any} [props.initialValue] - for an uncontrolled input, the default active values
+ * @param {string|number|null} [props.value] - for a controlled input, the active values as set by a parent
+ * @param {string|number} [props.initialValue] - for an uncontrolled input, the default active values
  * @param {function} [props.onChange] - function called when values change (required for controlled inputs)
  * @param {boolean} [props.readOnly] - if true, stops the input values from changing
  *
  * @param {string} hookName - optional, used for tailoring error messages
  *
+ * @typedef {(oldValue: string|number|null) => string|number|null} UpdaterFunction - `setValue` takes a value or
+ *          a function returning a new value from the old value
  * @returns {{
- *   currentValue: any
- *   setValue: (value: any) => void
+ *   currentValue: string|number|null
+ *   setValue: (newValue: string|number|null|UpdaterFunction) => void
  *   resetValue: () => void
  *   isControlled: bool
  * }}
@@ -70,17 +72,21 @@ export const useInputValue = (props = {}, hookName = 'useInputValue') => {
 
   // Store the first valid value, for resetting input to default. If behaviour like Formik's `enableReinitialize`
   // is needed, add useEffect calling a set fn if !deepEqual(initializedValues, initialValues)
-  const [initializedValue] = useState(currentValue)
+  const valueRef = useRef({ initial: currentValue, value: currentValue })
+  // Make current value accessible inside useCallback without rememoizing every time the value changes
+  valueRef.current.value = currentValue
 
   const setValue = useCallback(
-    (newValue) => {
+    (arg) => {
       if (readOnly) return
-      if (onChange) onChange(newValue)
+      const newValue = typeof arg === 'function' ? arg(valueRef.current.value) : arg
+      // Only call onChange if the value actually changed
+      if (onChange && valueRef.current.value !== newValue) onChange(newValue)
       if (!isControlled) setOwnValue(newValue)
     },
     [isControlled, onChange, readOnly]
   )
-  const resetValue = useCallback(() => setValue(initializedValue), [initializedValue, setValue])
+  const resetValue = useCallback(() => setValue(valueRef.current.initial), [setValue])
 
   return { currentValue, setValue, resetValue, isControlled }
 }
@@ -94,18 +100,20 @@ export const useInputValue = (props = {}, hookName = 'useInputValue') => {
  * management tools such as Formik and React Hooks Form.
  *
  * @param {object} props
- * @param {any[]} [props.values] - for a controlled input, the active values as set by a parent
- * @param {any[]} [props.initialValues] - for an uncontrolled input, the default active values
+ * @param {string[]|number[]} [props.values] - for a controlled input, the active values as set by a parent
+ * @param {string[]|number[]} [props.initialValues] - for an uncontrolled input, the default active values
  * @param {number?} [props.maxValues] - maximum number of values that may be selected at once (no limit if null)
  * @param {function} [props.onChange] - function called when values change (required for controlled inputs)
  * @param {boolean} [props.readOnly] - if true, stops the input values from changing
  *
  * @param {string} componentName - optional, used in error messages
  *
+ * @typedef {(oldValues: string[]|number[]) => string[]|number[]} UpdaterFunction - `setValues` takes values or
+ *          a function returning new values from old values
  * @returns {{
  *   currentValues: any
  *   resetValues: () => void
- *   setValues: (newValues: any[]) => void
+ *   setValues: (newValues: string[]|number[]|UpdaterFunction) => void
  *   toggleOneValue: (value: string|number) => void
  *   unsetValues: () => void
  * }}

package/src/utils/pressability.js

@@ -1,6 +1,10 @@
 import { Platform, StyleSheet } from 'react-native'
 import { pressProps } from './propTypes'
 
+/**
+ * @typedef {import('react').ReactNode} ReactNode
+ */
+
 // These roles should result in cursor: pointer but don't in current RNW releases
 const shouldUseCursor = ['checkbox', 'radio', 'switch']
 

package/src/utils/propTypes.js

@@ -39,12 +39,18 @@ export const variantProp = {
   )
 }
 
-// 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(...)' ... })
-const tokenValue = 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/system-themes/schema`)
@@ -54,14 +60,40 @@ const getTokenNames = (componentName) => {
 
 /**
  * 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
 }
 
@@ -120,6 +152,41 @@ export const getTokensPropType = (...componentsNames) => (props, propName, compo
   }
 }
 
+/**
+ * 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) =>
@@ -138,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,
 
@@ -191,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: {
@@ -248,26 +313,6 @@ 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.
-     */
   })
 }
 
@@ -345,6 +390,25 @@ export const linkProps = {
   }
 }
 
+const viewPropTypes = {
+  pointerEvents: PropTypes.oneOf(['all', 'none', 'box-only', 'box-none']),
+  onLayout: PropTypes.func,
+  nativeID: PropTypes.string
+}
+
+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,

package/src/utils/useCopy.js

@@ -1,13 +1,39 @@
+export const DEFAULT_COPY = 'en'
+
 /**
  * Extract translations from a keyed dictionary for a given language.
  * Returns a getter.
  *
- * @param {object} dictionary
- * @param {'en'|'fr'} copy - language
+ * @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 }) {
-  return (key) => dictionary[copy][key]
+function useCopy({ dictionary, copy = DEFAULT_COPY }) {
+  if (typeof copy === 'string') {
+    return (key) => dictionary[copy][key]
+  }
+
+  // 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,34 @@
+import { useEffect, useState } from 'react'
+
+const doAction = (action) => typeof action === 'function' && action(window?.location?.hash)
+
+/**
+ * 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) => 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 = () => doAction(action)
+    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/stories/A11yText/A11yText.stories.jsx

@@ -1,6 +1,6 @@
 /* eslint-disable react/no-multi-comp */
 import React from 'react'
-import { StyleSheet, Text, View } from 'react-native'
+import { StyleSheet, View } from 'react-native'
 
 import A11yText from '../../lib/A11yText'
 import { Button, Typography } from '../../lib'
@@ -44,13 +44,9 @@ A11yTextAsHeading.args = { ...defaultArgs, heading: true }
 
 export const A11yTextInButton = (args) => (
   <Button onPress={() => {}}>
-    {({ textStyles }) => (
-      <>
-        <A11yText {...args} />
-        <Text style={textStyles}>A11yText sandwich</Text>
-        <A11yText {...args} />
-      </>
-    )}
+    <A11yText {...args} />
+    A11yText sandwich
+    <A11yText {...args} />
   </Button>
 )
 A11yTextInButton.args = defaultArgs

package/stories/Checkbox/Checkbox.stories.jsx

@@ -1,7 +1,7 @@
 /* eslint-disable react/no-multi-comp */
 import React from 'react'
 
-import { Checkbox, Typography } from '../../lib'
+import { Checkbox, CheckboxGroup, Typography } from '../../lib'
 import { Container, EachParentType, parentTypesParams } from '../supports'
 
 export default {
@@ -55,6 +55,29 @@ WithFeedback.args = {
   feedback: 'Something happened'
 }
 
+export const CheckboxGroupStory = (args) => <CheckboxGroup {...args} />
+CheckboxGroupStory.storyName = 'CheckboxGroup'
+CheckboxGroupStory.args = {
+  items: [
+    {
+      label: 'Checkbox 1'
+    },
+    {
+      label: 'Checkbox 2'
+    },
+    {
+      label: 'Checkbox 3'
+    },
+    {
+      label: 'Checkbox 4'
+    }
+  ],
+  legend: 'Choose checkboxes.',
+  hint: 'Of the checkboxes below, choose some.',
+  tooltip: 'Decide which checkboxes you like best, then press them.',
+  name: 'example'
+}
+
 export const ParentTypes = (args) => (
   <EachParentType componentThemeName="Checkbox" {...args}>
     {({ label, variant }) => (

package/stories/Icon/Icon.stories.jsx

@@ -1,12 +1,13 @@
 /* eslint-disable react/no-multi-comp */
 import React from 'react'
 import { StyleSheet, Text } from 'react-native'
-import AccessibleIcon from '../../__fixtures__/accessible.icon.svg'
+import AccessibleIcon from '../../__fixtures__/Accessible'
+import { Icon } from '../../lib'
 import { Container, useVariants, EachParentType, parentTypesParams } from '../supports'
 
 export default {
   title: 'Base/Icon',
-  component: AccessibleIcon,
+  component: Icon,
   argTypes: {
     label: {
       type: {
@@ -30,21 +31,21 @@ export default {
   }
 }
 
-export const ExampleIcon = (args) => <AccessibleIcon {...args} />
+export const ExampleIcon = (args) => <Icon icon={AccessibleIcon} {...args} />
 
 export const IconVariants = (args) => {
   const variants = useVariants('Icon')
   return variants.map(([key, value, label]) => (
     <Container key={label} dark={value === 'white'}>
       <Text style={styles.subtle}>{label}</Text>
-      <AccessibleIcon {...args} variant={{ [key]: value }} />
+      <Icon icon={AccessibleIcon} {...args} variant={{ [key]: value }} />
     </Container>
   ))
 }
 
 export const ParentTypes = (args) => (
   <EachParentType {...args}>
-    {({ label }) => <AccessibleIcon {...args} label={label} />}
+    {({ label }) => <Icon icon={AccessibleIcon} {...args} label={label} />}
   </EachParentType>
 )
 ParentTypes.parameters = parentTypesParams

package/stories/Modal/Modal.stories.jsx

@@ -0,0 +1,29 @@
+import React, { useState } from 'react'
+
+import { Button, Modal, Spacer, Typography } from '../../lib'
+
+export default {
+  title: 'Base/Modal',
+  component: Modal
+}
+
+export const Default = (args) => {
+  const [isOpen, setIsOpen] = useState(false)
+  const [isMaxWidthOpen, setIsMaxWidthOpen] = useState(false)
+
+  return (
+    <>
+      <Button onPress={() => setIsOpen(true)}>Open modal</Button>
+      <Modal {...args} isOpen={isOpen} onClose={() => setIsOpen(false)}>
+        <Typography>Test content</Typography>
+      </Modal>
+      <Spacer space={3} />
+      <Button onPress={() => setIsMaxWidthOpen(true)}>Open maxWidth modal</Button>
+      <Modal {...args} isOpen={isMaxWidthOpen} onClose={() => setIsMaxWidthOpen(false)} maxWidth>
+        <Typography variant={{ size: 'h2' }}>Test heading</Typography>
+        <Typography>Test content</Typography>
+      </Modal>
+    </>
+  )
+}
+Default.storyName = 'Modal'

package/stories/Notification/Notification.stories.jsx

@@ -0,0 +1,82 @@
+/* eslint-disable react/no-multi-comp */
+import React from 'react'
+import { Text } from 'react-native'
+
+import { Link, Notification, Typography } from '../../lib'
+import { Container } from '../supports'
+
+export default {
+  title: 'Base/Notification',
+  component: Notification
+}
+
+const Template = (args) => <Notification {...args} />
+
+export const Default = Template.bind({})
+Default.args = {
+  children: 'Your password was updated successfully.'
+}
+
+export const Variants = () => {
+  const variants = [{}, { style: 'success' }, { style: 'warning' }, { style: 'error' }]
+  const propSets = [
+    {},
+    { system: true },
+    { dismissible: true },
+    { system: true, dismissible: true }
+  ]
+
+  const combinations = variants.flatMap((variant) => {
+    return propSets.map((propSet) => ({ variant, ...propSet }))
+  })
+
+  return combinations.map((props) => {
+    const label = [
+      props.variant.style ?? 'default',
+      props.system && 'system',
+      props.dismissible && 'dismissible'
+    ]
+      .filter((value) => value)
+      .join(' ')
+
+    return (
+      <Container key={label}>
+        <Text>{label}</Text>
+        <Notification {...props}>
+          Tip: These services are best suited for large business organizations. Order products and
+          services at TELUS.com.
+        </Notification>
+      </Container>
+    )
+  })
+}
+
+export const ContentTypes = () => {
+  return (
+    <>
+      <Container>
+        <Notification>A regular string content.</Notification>
+      </Container>
+      <Container>
+        <Notification>
+          <Typography>
+            Text components content. <Link href="https://telus.com/uds">Combined with a link.</Link>
+          </Typography>
+        </Notification>
+      </Container>
+      <Container>
+        <Notification variant={{ customVariant: true }}>
+          {({ textStyles, variant }) => (
+            <Text style={textStyles}>
+              A render function, to apply component styles and variant ({Object.keys(variant)[0]})
+              to Text and{' '}
+              <Link href="https://telus.com/uds" tokens={{ color: textStyles.color }}>
+                Link
+              </Link>
+            </Text>
+          )}
+        </Notification>
+      </Container>
+    </>
+  )
+}

package/stories/Progress/Progress.stories.jsx

@@ -0,0 +1,93 @@
+/* eslint-disable react/no-multi-comp */
+import React from 'react'
+
+import { Progress, StackView, Typography } from '../../lib'
+import { Container, EachParentType, parentTypesParams } from '../supports'
+
+export default {
+  title: 'Base/Progress',
+  component: Progress.Bar,
+  args: { accessibilityLabel: 'Progress Bar' }
+}
+
+export const Default = (args) => (
+  <Progress>
+    <Progress.Bar {...args} />
+  </Progress>
+)
+Default.storyName = 'Example'
+Default.args = { percentage: 50 }
+Default.argTypes = {
+  percentage: { control: { type: 'range', min: 0, max: 100 } }
+}
+
+export const Variants = () => (
+  <Container>
+    <StackView>
+      <Progress>
+        <Progress.Bar
+          percentage={25}
+          variant={{ inactive: true }}
+          accessibilityLabel="Inactive progress bar"
+        />
+      </Progress>
+      <Progress>
+        <Progress.Bar
+          percentage={50}
+          variant={{ negative: true }}
+          accessibilityLabel="Negative progress bar"
+        />
+      </Progress>
+      <Progress>
+        <Progress.Bar percentage={75} accessibilityLabel="Progress bar" />
+      </Progress>
+      <Progress variant={{ size: 'mini' }}>
+        <Progress.Bar
+          percentage={25}
+          variant={{ inactive: true }}
+          accessibilityLabel="Inactive progress bar"
+        />
+      </Progress>
+      <Progress variant={{ size: 'mini' }}>
+        <Progress.Bar
+          percentage={50}
+          variant={{ negative: true }}
+          accessibilityLabel="Negative progress bar"
+        />
+      </Progress>
+      <Progress variant={{ size: 'mini' }}>
+        <Progress.Bar
+          percentage={75}
+          variant={{ size: 'mini' }}
+          accessibilityLabel="Minimal progress bar"
+        />
+      </Progress>
+    </StackView>
+  </Container>
+)
+
+export const StackedBars = () => (
+  <Progress>
+    <Progress.Bar
+      percentage={75}
+      variant={{ inactive: true }}
+      accessibilityLabel="Stacked inactive progress bar"
+    />
+    <Progress.Bar percentage={50} accessibilityLabel="Stacked progress bar" />
+  </Progress>
+)
+
+export const ParentTypes = (args) => (
+  <EachParentType componentThemeName="ProgressBar" {...args}>
+    {({ label, variant }) => (
+      <Container key={label}>
+        <Typography>{`${label} `}</Typography>
+        <Progress>
+          <Progress.Bar {...args} variant={variant} accessibilityLabel={label} />
+        </Progress>
+      </Container>
+    )}
+  </EachParentType>
+)
+ParentTypes.parameters = parentTypesParams
+ParentTypes.args = { percentage: 75 }