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

package/src/utils/info/platform/platform.js

@@ -0,0 +1 @@
+export default '.web (default)'

package/src/utils/info/platform/platform.native.js

@@ -0,0 +1,4 @@
+// This shouldn't ever be chosen, as the more specific '.ios' and '.android' are available.
+// If this gets picked, either an unsupported React Native platform is being used somehow
+// (e.g. a native Windows app), or there's a serious config problem somewhere.
+export default '.native'

package/src/utils/info/versions.js

@@ -0,0 +1,6 @@
+import pkgJson from '../../../package.json'
+
+// Add more versions if they are useful e.g. theme schema version
+export default {
+  uds: pkgJson.version
+}

package/src/utils/input.js

@@ -1,4 +1,4 @@
-import { useCallback, useState } from 'react'
+import { useCallback, useRef, useState } from 'react'
 
 const pluralHooks = ['useMultipleInputValues']
 
@@ -44,17 +44,20 @@ 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
  * }}
  */
 
@@ -69,19 +72,23 @@ 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, event) => {
       if (readOnly) return
-      if (onChange) onChange(newValue)
+      const newValue = typeof arg === 'function' ? arg(valueRef.current.value) : arg
       if (!isControlled) setOwnValue(newValue)
+      // Call onChange handler if there's something for it to handle (event or a changed value)
+      if (onChange && (event || valueRef.current.value !== newValue)) onChange(newValue, event)
     },
     [isControlled, onChange, readOnly]
   )
-  const resetValue = useCallback(() => setValue(initializedValue), [initializedValue, setValue])
+  const resetValue = useCallback((event) => setValue(valueRef.current.initial, event), [setValue])
 
-  return { currentValue, setValue, resetValue }
+  return { currentValue, setValue, resetValue, isControlled }
 }
 
 /**
@@ -93,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
  * }}
@@ -137,23 +146,26 @@ export const useMultipleInputValues = ({
   )
   const currentValues = enforceMaxValues(currentValue)
 
-  const setValues = useCallback((newValues) => setValue(enforceMaxValues(newValues)), [
-    setValue,
-    enforceMaxValues
-  ])
+  const setValues = useCallback(
+    (newValues, event) => {
+      const validNewValues = enforceMaxValues(newValues)
+      setValue(validNewValues, event)
+    },
+    [setValue, enforceMaxValues]
+  )
 
   const resetValues = resetValue
-  const unsetValues = useCallback(() => setValues([]), [setValues])
+  const unsetValues = useCallback((event) => setValues([], event), [setValues])
   const toggleOneValue = useCallback(
-    (newValue) => {
+    (newValue, event) => {
       if (readOnly) return
-      setValues(
-        // This will only work with primitive values (e.g. strings, numbers), swap for .some() and
-        // a deepEqual() function if there's any use case for toggling stored objects or arrays.
-        currentValues.includes(newValue)
-          ? currentValues.filter((oldValue) => oldValue !== newValue)
-          : [...currentValues, newValue]
-      )
+      // This will only work with primitive values (e.g. strings, numbers), swap for .some() and
+      // a deepEqual() function if there's any use case for toggling stored objects or arrays.
+      const newValues = currentValues.includes(newValue)
+        ? currentValues.filter((oldValue) => oldValue !== newValue)
+        : [...currentValues, newValue]
+
+      setValues(newValues, event)
     },
     [currentValues, readOnly, setValues]
   )

package/src/utils/pressability.js

@@ -0,0 +1,96 @@
+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']
+
+/**
+ * React Native Web has some built-in logic for applying cursor styles based on accessibility roles;
+ * however, it misses certain cases. This fills in known cases where widely used versions of RNW
+ * fail to apply an expected cursor style.
+ *
+ * @param {object} props
+ * @param {boolean} [props.inactive]
+ * @param {boolean} [props.disabled]
+ * @param {string} [props.accessibilityRole]
+ * @returns
+ */
+export const getCursorStyle = ({ inactive, disabled, accessibilityRole }) => {
+  if (Platform.OS !== 'web') return undefined
+
+  if (inactive || disabled) return staticStyles.notAllowed
+  if (shouldUseCursor.includes(accessibilityRole)) return staticStyles.pointer
+
+  return undefined // allows React Native Web's built-in logic to apply
+}
+
+/**
+ * @typedef {{ pressed: boolean, focused: boolean, hovered?: boolean }} PressableState
+ */
+
+/**
+ * Maps the state object given by the React Native `Pressable` component to the set of
+ * equivalent appearance names used in UDS.
+ *
+ * @param {PressableState} pressableState - state object passed by React Native's `<Pressable>` into
+ *   render functions passed to its `style` or `children` props.
+ * @param {object} [additionalState] - properties specific to the current component,
+ *   such as `inactive`, `selected`, etc.
+ * @returns {object}
+ */
+export const resolvePressableState = (
+  { pressed = false, focused = false, hovered = false } = {},
+  additionalState
+) => ({
+  ...additionalState,
+  focus: focused,
+  hover: hovered,
+  pressed
+})
+
+/**
+ * Takes a UDS `tokens` prop and, if it is a function, resolves it based on a state
+ * object passed from the React Native `Pressable` component and optional extra properties.
+ *
+ * @param {object|function} tokens - UDS system tokens prop
+ * @param {PressableState} pressableState - state object passed by React Native's `<Pressable>`
+ * @param {object} [additionalState] - properties specific to the current component
+ * @returns {object} - resolved tokens object
+ */
+export const resolvePressableTokens = (tokens, pressableState, additionalState) => {
+  if (typeof tokens !== 'function') return tokens
+  const udsPressableState = resolvePressableState(pressableState, additionalState)
+  return tokens(udsPressableState)
+}
+
+const staticStyles = StyleSheet.create(
+  Platform.select({
+    web: {
+      notAllowed: { cursor: 'not-allowed' },
+      pointer: { cursor: 'pointer' }
+    },
+    default: {}
+  })
+)
+
+/**
+ * From an object of props, extracts any platform-appropriate press handler functions and wraps
+ * them in a function that passes in some provided args. Allows components containing a Pressable
+ * to pass in press handlers that are then called with state or values that is otherwise internal.
+ */
+export const getPressHandlersWithArgs = (pressableProps = {}, args = []) => {
+  // Allow handlers to be passed down for blur, hover, focus, pressIn, etc
+  const pressHandlers = Object.fromEntries(
+    Object.entries(pressProps.selectHandlers(pressableProps)).map(([key, handler]) => ({
+      [key]: (...defaultArgs) => {
+        // Pass each handler data on this button and current selection
+        handler(...args, ...defaultArgs)
+      }
+    }))
+  )
+  return pressHandlers
+}