@telus-uds/components-base 2.4.0 → 3.0.0

package/lib/esm/utils/children.js

@@ -0,0 +1,113 @@
+import React from 'react';
+import Text from "react-native-web/dist/exports/Text";
+import A11yText from '../A11yText';
+
+/**
+ * Unpacks top-level fragments, so that common compositional patterns such as the following examples
+ * can be iterated as flat siblings (as if they were `<Child1 /><Child2 /><Child3 />`):
+ *
+ * - Setting `children` as a property wrapped in a fragment:
+ *
+ * ```jsx
+ * args.children = <><Child1 /><Child2 /><Child3 /></>
+ * ```
+ *
+ * - Defining `children` as a variable wrapped in a fragment:
+ *
+ * ```jsx
+ * const content = <><Child1 /><Child2 /><Child3 /></>
+ * if (someCondition) return <SomeWrapper>{content}</SomeWrapper>
+ * ```
+ *
+ * - Using fragments at the top level of a JSX block for conditional rendering:
+ *
+ * ```jsx
+ * <Child1 />
+ * {someCondition && (
+ *   <>
+ *     <Child2 />
+ *     <Child3 />
+ *   </>
+ * )}
+ * ```
+ *
+ * @param {ReactChildren} child
+ * @returns {ReactChildren}
+ */
+import { jsx as _jsx } from "react/jsx-runtime";
+export const unpackFragment = child => {
+  // If this level is a set of top-level siblings rather than one child, check each in turn
+  if (React.Children.count(child) > 1) return React.Children.map(child, unpackFragment);
+
+  // When a fragment is found, unpack its children to the top level and check them
+  if (child?.type === React.Fragment) return unpackFragment(child.props?.children);
+
+  // Stop unpacking as soon as any non-fragment child is found
+  return child;
+};
+const isStringOrNumber = child => typeof child === 'string' || typeof child === 'number';
+// Wrap an A11yText with neighouring text strings so it doesn't split them into multiple <Text>s
+const isWrapable = child => isStringOrNumber(child) || child.type === A11yText || child.type?.name === 'FootnoteLink';
+const combineKeys = childrenArray => childrenArray.reduce((newKey, child) => `${newKey}${child.key || ''}`, '');
+
+// Group wrappable children for one `<Text>` parent, merging adjacent text nodes
+const wrapChild = (child, wrappedText) => {
+  const lastIndex = wrappedText.length - 1;
+  // If possible, simplify content by combining text nodes into one string.
+  // jest-native's `.toHaveTextContent` is buggy about array of text nodes in <Text> elements.
+  if (lastIndex >= 0 && isStringOrNumber(child) && isStringOrNumber(wrappedText[lastIndex])) {
+    /* eslint-disable-next-line no-param-reassign */
+    wrappedText[lastIndex] = `${wrappedText[lastIndex]}${child}`;
+  } else {
+    wrappedText.push(child);
+  }
+};
+
+/**
+ * React Native on Native crashes if text content is rendered outside `<Text>`, and on web,
+ * text style inheritance behaves differently with text compared to regular HTML.
+ *
+ * Call this function on children that may contain text (strings or numbers) at the top level,
+ * and any that are found will be wrapped in a React Native `<Text>` element with supplied props.
+ *
+ * Note that this does not wrap strings that are nested children of rendered top level children:
+ * `wrapStringsInText(<View>Some text</View>)` will not wrap the inner text and will still crash,
+ * but `wrapStringsInText(<>{someString}{anotherString}</>)` wraps the strings inside the fragment.
+ *
+ * @param {ReactChildren} children
+ * @param {TextProps} props
+ * @returns {ReactChildren}
+ */
+export const wrapStringsInText = function (children) {
+  let textProps = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : {};
+  const childrenArray = unpackFragment(React.Children.toArray(children));
+
+  // Group adjacent wrapable children together in one Text element to create as few Text elements
+  // as possible, e.g. give <X>Text {someString}</X> one Text, same as <X>{`Text ${someString}`}</X>
+  const wrapables = [[]];
+  let wrapablesIndex = 0;
+  childrenArray.forEach(child => {
+    if (isWrapable(child)) {
+      // Make this child a child of the current `Text`
+      wrapChild(child, wrapables[wrapablesIndex]);
+    } else {
+      // Close current `Text` and start a new one after this child
+      wrapables.push(child, []);
+      wrapablesIndex += 2;
+    }
+  });
+  const items = wrapables.reduce((flatChildren, group, index) => {
+    // Skip nullish children and empty arrays
+    if (!group || Array.isArray(group) && !group.length) return flatChildren;
+    return [...flatChildren, Array.isArray(group) && group.some(child => isStringOrNumber(child)) ?
+    /*#__PURE__*/
+    // Wrap text nodes and their wrappable neighbours in Text with as stable a key as possible.
+    // Avoid one-item arrays because jest-native's `.toHaveTextContent` is buggy
+    // and sometimes fails to match text content in arrays.
+    _jsx(Text, {
+      ...textProps,
+      children: group.length === 1 ? group[0] : group
+    }, combineKeys(group) || index) : group];
+  }, []);
+  return items.length === 1 ? items[0] : items;
+};

package/lib/esm/utils/input.js

@@ -0,0 +1,185 @@
+import { useCallback, useRef, useState } from 'react';
+/**
+ * @typedef {import('react').SyntheticEvent} Event
+ */
+
+const pluralHooks = ['useMultipleInputValues'];
+const validateProps = (_ref, _ref2, hookName) => {
+  let {
+    value,
+    onChange,
+    readOnly,
+    initialValue
+  } = _ref;
+  let {
+    isCurrentlyControlled,
+    isControlled
+  } = _ref2;
+  const s = pluralHooks.includes(hookName) ? 's' : '';
+  const usageError = error => {
+    // Errors inside hooks in React Native get incomplete stack traces pointing at parent component only.
+    // Help devs out by telling them exactly which hook threw the error as well as why.
+    throw new Error(`${hookName} ${error}.
+
+Consumers of this hook must be one of:
+1. An "uncontrolled" component responding directly to user actions, with an optional \`initialValue${s}\` but no \`value${s}\` prop,
+2. A "controlled" component where an always-defined \`value${s}\` prop is managed by an \`onChange\` handler, with no \`initialValue${s}\`,
+3. A "read-only" component, with \`readOnly\` prop set as \`true\`.
+`);
+  };
+  if (value && !onChange && !readOnly) {
+    usageError(`has \`value${s}\` prop without \`onChange\` or \`readOnly\``);
+  }
+  if (initialValue && value) {
+    usageError(`has both \`initialValue${s}\` and \`value${s}\``);
+  }
+  if (isControlled && !isCurrentlyControlled) {
+    usageError(`stopped receiving \`value${s}\` from parent after delegating state management`);
+  }
+  if (!isControlled && isCurrentlyControlled) {
+    usageError(`started receiving \`value${s}\` from parent after starting managing own state`);
+  }
+};
+
+/**
+ * Hook used for controlling the input state of input components that have a singular value.
+ * If `value` prop is passed in, this delegates state management to a parent using a passed-in `onChange` prop.
+ * If `value` prop is undefined, the hook manages its own state.
+ *
+ * TODO: when implementing full UDS forms, integrate validation support etc and test alongside common forms
+ * management tools such as Formik and React Hooks Form.
+ *
+ * @param {object} props
+ * @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
+ *
+ * @returns {{
+ *   currentValue: string|number|null
+ *   setValue: (newValue: string|number|null|(oldValue: string|number) => string|number, event: Event) => void
+ *   resetValue: () => void
+ *   isControlled: bool
+ * }}
+ */
+export const useInputValue = function () {
+  let props = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : {};
+  let hookName = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : 'useInputValue';
+  const isCurrentlyControlled = props.value !== undefined;
+  const [isControlled] = useState(isCurrentlyControlled);
+  validateProps(props, {
+    isControlled,
+    isCurrentlyControlled
+  }, hookName);
+  const {
+    value,
+    initialValue,
+    inputRef,
+    onChange,
+    readOnly = false
+  } = props;
+  const [ownValue, setOwnValue] = useState(!isControlled && initialValue);
+  const currentValue = isControlled ? value : ownValue;
+
+  // 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 valueRef = useRef({
+    initial: currentValue,
+    value: currentValue
+  });
+  // Make current value accessible inside useCallback without rememoizing every time the value changes
+  valueRef.current.value = currentValue;
+  const isDirty = currentValue !== valueRef.current.initial;
+  const setValue = useCallback((arg, event) => {
+    if (readOnly) return;
+    const newValue = typeof arg === 'function' ? arg(valueRef.current.value) : arg;
+    if (!isControlled) {
+      setOwnValue(newValue);
+      if (inputRef?.current) inputRef.current.value = 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);
+  }, [inputRef, isControlled, onChange, readOnly]);
+  const resetValue = useCallback(event => setValue(valueRef.current.initial, event), [setValue]);
+  return {
+    currentValue,
+    setValue,
+    resetValue,
+    isControlled,
+    isDirty
+  };
+};
+
+/**
+ * Hook used for controlling the input state of input components that have multiple named on/off states.
+ * If `values` are passed in, this delegates state management to a parent using a passed-in `onChange` prop.
+ * If `values` prop is not passed in, the hook manages its own state.
+ *
+ * TODO: when implementing full UDS forms, integrate validation support etc and test alongside common forms
+ * management tools such as Formik and React Hooks Form.
+ *
+ * @param {object} props
+ * @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
+ *
+ * @returns {{
+ *   currentValues: any
+ *   resetValues: () => void
+ *   setValues: (newValues: string[]|number[]|(oldValues: string[]|number[]) => string[]|number[], event: Event) => void
+ *   toggleOneValue: (value: string|number) => void
+ *   unsetValues: () => void
+ * }}
+ */
+export const useMultipleInputValues = function () {
+  let {
+    values,
+    initialValues,
+    maxValues,
+    onChange,
+    readOnly
+  } = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : {};
+  const {
+    currentValue,
+    setValue,
+    resetValue
+  } = useInputValue({
+    readOnly,
+    onChange,
+    value: values,
+    // if we're controlling our own state, always start with an array
+    initialValue: initialValues ?? (values === undefined ? [] : undefined)
+  }, 'useMultipleInputValues');
+  const enforceMaxValues = useCallback(newValues => {
+    if (!maxValues) return newValues;
+    const excess = newValues.length - maxValues;
+    return excess > 0 ? newValues.slice(excess) : newValues;
+  }, [maxValues]);
+  const currentValues = enforceMaxValues(currentValue);
+  const setValues = useCallback((newValues, event) => {
+    const validNewValues = enforceMaxValues(newValues);
+    setValue(validNewValues, event);
+  }, [setValue, enforceMaxValues]);
+  const resetValues = resetValue;
+  const unsetValues = useCallback(event => setValues([], event), [setValues]);
+  const toggleOneValue = useCallback((newValue, event) => {
+    if (readOnly) return;
+    // 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]);
+  return {
+    currentValues,
+    resetValues,
+    setValues,
+    toggleOneValue,
+    unsetValues
+  };
+};

package/lib/esm/utils/props/componentPropType.js

@@ -0,0 +1,49 @@
+/**
+ * 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/lib/esm/utils/props/selectSystemProps.js

@@ -0,0 +1,23 @@
+// 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/lib/esm/utils/ssr-media-query/create-stylesheet/create-stylesheet-mobile.js

@@ -0,0 +1,48 @@
+import mediaQuery from 'css-mediaquery';
+import Dimensions from "react-native-web/dist/exports/Dimensions";
+import { isMediaOrPseudo, isMedia } from '../utils/common';
+const createStyleSheet = stylesWithQuery => {
+  if (!stylesWithQuery) return {
+    ids: {},
+    styles: {},
+    fullStyles: {}
+  };
+  let cleanStyles;
+  const ids = {};
+  Object.keys(stylesWithQuery).forEach(key => {
+    if (!stylesWithQuery?.[key]) return;
+    const mediaQueriesAndPseudoClasses = Object.keys(stylesWithQuery[key]).filter(isMediaOrPseudo);
+    cleanStyles = JSON.parse(JSON.stringify(stylesWithQuery));
+    mediaQueriesAndPseudoClasses.forEach(str => {
+      if (isMedia(str)) {
+        const mqStr = str.replace('@media', '');
+        const {
+          width,
+          height
+        } = Dimensions.get('window');
+        const isMatchingMediaQuery = mediaQuery.match(mqStr, {
+          width,
+          height,
+          orientation: width > height ? 'landscape' : 'portrait',
+          'aspect-ratio': width / height
+        });
+        if (isMatchingMediaQuery) {
+          cleanStyles = {
+            ...cleanStyles,
+            [key]: {
+              ...cleanStyles[key],
+              ...stylesWithQuery[key][str]
+            }
+          };
+        }
+      }
+      delete cleanStyles[key][str];
+    });
+  });
+  return {
+    ids,
+    styles: cleanStyles,
+    fullStyles: stylesWithQuery
+  };
+};
+export default createStyleSheet;

package/lib/esm/utils/ssr-media-query/create-stylesheet/index.js

@@ -0,0 +1,35 @@
+import { addCss } from '../utils/inject';
+import createDeclarationBlock from '../utils/create-declaration-block';
+import hash from '../hash';
+import { isMediaOrPseudo, deepClone, createCssRule, sanitizeStyle } from '../utils/common';
+const createStyleSheet = stylesWithQuery => {
+  if (!stylesWithQuery) return {
+    ids: {},
+    styles: {},
+    fullStyles: {}
+  };
+  let ids = {};
+  const cleanStyles = deepClone(stylesWithQuery);
+  Object.keys(stylesWithQuery).forEach(key => {
+    if (!stylesWithQuery?.[key]) return;
+    const mediaQueriesAndPseudoClasses = Object.keys(stylesWithQuery[key]).filter(isMediaOrPseudo);
+    mediaQueriesAndPseudoClasses.forEach(query => {
+      const sanitizedStyle = sanitizeStyle(stylesWithQuery[key][query]);
+      const css = createDeclarationBlock(sanitizedStyle);
+      const stringHash = `rnmq-${hash(`${key}${query}${css}`)}`;
+      const rule = createCssRule(query, stringHash, css);
+      addCss(`${stringHash}`, rule);
+      delete cleanStyles[key][query];
+      ids = {
+        ...ids,
+        [key]: `${ids?.[key] ? `${ids[key]} ` : ''}${stringHash}`
+      };
+    });
+  });
+  return {
+    ids,
+    styles: cleanStyles,
+    fullStyles: stylesWithQuery
+  };
+};
+export default createStyleSheet;

package/lib/esm/utils/ssr-media-query/utils/inject.js

@@ -0,0 +1,37 @@
+import React from 'react';
+import Platform from "react-native-web/dist/exports/Platform";
+const rules = {};
+let styleSheet;
+if (typeof window !== 'undefined' && typeof document !== 'undefined') {
+  styleSheet = (() => {
+    const style = document.createElement('style');
+    style.id = 'RNMQCSS';
+    style.appendChild(document.createTextNode(''));
+    document.head.appendChild(style);
+    return style.sheet;
+  })();
+}
+export const hasCss = (id, text) => {
+  return !!rules[id] && !!rules[id].text?.includes?.(text);
+};
+export const addCss = (id, text) => {
+  if (!hasCss(id, text)) {
+    rules[id] = rules?.[id] || {};
+    rules[id].text = (rules[id]?.text || '') + text;
+    if (styleSheet) {
+      styleSheet.insertRule(text, Object.keys(rules).length - 1);
+    }
+  }
+};
+export const flush = () => {
+  if (Platform.OS === 'web') {
+    return /*#__PURE__*/React.createElement('style', {
+      id: 'rnmq',
+      key: 'rnmq',
+      dangerouslySetInnerHTML: {
+        __html: Object.keys(rules).map(key => rules[key].text).join('\n')
+      }
+    });
+  }
+  return {};
+};

package/lib/esm/utils/useHash.js

@@ -0,0 +1,38 @@
+import { useEffect, useState } from 'react';
+const doAction = (action, event) => typeof action === 'function' && action(window?.location?.hash, event);
+
+/**
+ * @typedef {import('react').SyntheticEvent} SyntheticEvent
+ */
+
+/**
+ * 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, event?: SyntheticEvent) => void} action - a function to act on the current hash on load and when it changes
+ * @returns
+ */
+const useHash = function (action) {
+  let isReady = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : 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 = event => doAction(action, event);
+    window.addEventListener('hashchange', handleChange);
+    return () => window.removeEventListener('hashchange', handleChange);
+  }, [action]);
+};
+export default useHash;