@telus-uds/components-base 1.8.3 → 1.9.0

package/lib-module/utils/props/handlerProps.js

@@ -0,0 +1,65 @@
+import PropTypes from 'prop-types';
+export const focusHandlerProps = {
+  types: {
+    /**
+     * onBlur handler
+     */
+    onBlur: PropTypes.func,
+
+    /**
+     * onFocus handler
+     */
+    onFocus: PropTypes.func
+  },
+  select: _ref => {
+    let {
+      onBlur,
+      onFocus
+    } = _ref;
+    return {
+      onBlur,
+      onFocus
+    };
+  }
+};
+export const textInputHandlerProps = {
+  types: {
+    /**
+     * onChange handler
+     */
+    onChange: PropTypes.func,
+
+    /**
+     * onChangeText handler
+     */
+    onChangeText: PropTypes.func,
+
+    /**
+     * onSubmit handler
+     */
+    onSubmit: PropTypes.func,
+
+    /**
+     * onSubmitEditing handler
+     */
+    onSubmitEditing: PropTypes.func
+  },
+  select: _ref2 => {
+    let {
+      onChange,
+      onChangeText,
+      onSubmit,
+      onSubmitEditing
+    } = _ref2;
+    return {
+      onChange,
+      onChangeText,
+      onSubmit,
+      onSubmitEditing
+    };
+  }
+};
+export default {
+  focusHandlerProps,
+  textInputHandlerProps
+};

package/lib-module/utils/props/hrefAttrsProp.js

@@ -0,0 +1,33 @@
+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: _ref => {
+    let {
+      download,
+      rel,
+      target,
+      ...rest
+    } = _ref;
+    return {
+      hrefAttrs: {
+        download,
+        rel,
+        target
+      },
+      rest
+    };
+  }
+};

package/lib-module/utils/props/index.js

@@ -0,0 +1,19 @@
+export * from './tokens';
+export * from './handlerProps';
+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 inputSupportsProps } from './inputSupportsProps';
+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 textInputProps } from './textInputProps';
+export { default as textProps } from './textProps';
+export { default as variantProp } from './variantProp';
+export { default as viewProps } from './viewProps';

package/lib-module/utils/props/inputSupportsProps.js

@@ -0,0 +1,62 @@
+import PropTypes from 'prop-types';
+export default {
+  types: {
+    /**
+     * Whether the English or French copy will be used (e.g. for accessibility labels).
+     */
+    copy: PropTypes.oneOf(['en', 'fr']),
+
+    /**
+     * The input label.
+     */
+    label: PropTypes.string,
+
+    /**
+     * A short description of the expected input.
+     */
+    hint: PropTypes.string,
+
+    /**
+     * Position of the hint relative to label. Use `below` to display a larger hint below the label.
+     */
+    hintPosition: PropTypes.oneOf(['inline', 'below']),
+
+    /**
+     * A detailed description of validation error/success or additional instructions.
+     * Visual variant is determined based on the `validation` prop.
+     */
+    feedback: PropTypes.string,
+
+    /**
+     * Content of an optional `Tooltip`. If set, a tooltip button will be shown next to the label.
+     */
+    tooltip: PropTypes.string,
+
+    /**
+     * Use to visually mark an input as valid or invalid.
+     */
+    validation: PropTypes.oneOf(['error', 'success'])
+  },
+  select: _ref => {
+    let {
+      copy,
+      label,
+      hint,
+      hintPosition,
+      feedback,
+      tooltip,
+      validation
+    } = _ref;
+    return {
+      supportsProps: {
+        copy,
+        label,
+        hint,
+        hintPosition,
+        feedback,
+        tooltip,
+        validation
+      }
+    };
+  }
+};

package/lib-module/utils/props/linkProps.js

@@ -0,0 +1,44 @@
+import Linking from "react-native-web/dist/exports/Linking";
+import Platform from "react-native-web/dist/exports/Platform";
+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 that open links on Native.
+   *
+   * @param {({ onPress?: () => void, href?: string })}
+   * @returns {(() => void)|undefined} Returns a press handler, or undefined on web if no press
+   * handler is provided (expects calling component to render as `<a href={href}>` on web).
+   */
+  handleHref: _ref => {
+    let {
+      onPress,
+      href
+    } = _ref;
+    return Platform.select({
+      web: onPress,
+      default: function () {
+        if (onPress) onPress(...arguments);
+        if (href) Linking.openURL(href);
+      }
+    });
+  }
+};

package/lib-module/utils/props/paddingProp.js

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

package/lib-module/utils/props/pressProps.js

@@ -0,0 +1,42 @@
+import Platform from "react-native-web/dist/exports/Platform";
+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/lib-module/utils/props/rectProp.js

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

package/lib-module/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/lib-module/utils/props/selectSystemProps.js

@@ -0,0 +1,24 @@
+// 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 === null || propHelper === void 0 ? void 0 : propHelper.select) !== 'function') {
+      throw new Error("An invalid system prop helper has been passed to 'selectSystemProps': prop selector ('.select') is missing in ".concat(propHelper));
+    }
+
+    return { ...acc,
+      ...propHelper.select(props)
+    };
+  }, {});
+
+  const selectedPropTypes = systemPropHelpers.reduce((acc, propHelper) => {
+    if (!(propHelper !== null && propHelper !== void 0 && propHelper.types)) {
+      throw new Error("An invalid system prop helper has been passed to 'selectSystemProps': types selector ('.types') is missing in ".concat(propHelper));
+    }
+
+    return { ...acc,
+      ...propHelper.types
+    };
+  }, {});
+  return [selectProps, selectedPropTypes];
+}

package/lib-module/utils/props/spacingProps.js

@@ -0,0 +1,56 @@
+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])
+  }
+};

package/lib-module/utils/props/textInputProps.js

@@ -0,0 +1,201 @@
+import PropTypes from 'prop-types';
+import Platform from "react-native-web/dist/exports/Platform";
+import getPropSelector from './getPropSelector'; // This file contains common props for components that render a React Native TextInput
+// It excludes interaction handler functions which are in `./handlerProps.js`
+
+/**
+ * TextInput (web and native) supports some common React Native props
+ * shared with React Native's Text component.
+ */
+
+const textProps = {
+  maxFontSizeMultiplier: PropTypes.number,
+  nativeId: PropTypes.string,
+  onLayout: PropTypes.func
+};
+/**
+ * UDS text inputs accept props related to UDS's useInputValue hook
+ */
+
+const inputValueProps = {
+  value: PropTypes.string,
+  initialValue: PropTypes.string,
+  readOnly: PropTypes.bool,
+  inactive: PropTypes.bool
+};
+/**
+ * This collection adds props that can be passed through to both React Native's
+ * and React Native Web's implementations of the React Native TextInput component.
+ */
+
+const crossPlatform = { ...textProps,
+  ...inputValueProps,
+
+  /**
+   * Web and Android; 'off' disables device autocomplete, other strings are platform-specific.
+   * Valid values on Native: https://reactnative.dev/docs/textinput#autocomplete-android
+   * Valid values on Web: https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/autocomplete
+   */
+  autoComplete: PropTypes.string,
+
+  /**
+   * On Native, default is `true`, passing `false` disables autoCorrect.
+   * On web, only supported by Safari and expects "on" or "off" strings.
+   */
+  autoCorrect: PropTypes.oneOf([true, false, 'on', 'off']),
+
+  /**
+   * Focuses the element on mount. On Web, only the first form element with autoFocus is focussed.
+   */
+  autoFocus: PropTypes.bool,
+
+  /**
+   * Default is `true` for single line, `false` for multi-line
+   */
+  blurOnSubmit: PropTypes.bool,
+
+  /**
+   * iOS and Web only, no effect on Android
+   */
+  clearTextOnFocus: PropTypes.bool,
+
+  /**
+   * Default is `true`. On web, this works by mapping to input's `readonly` attribute
+   */
+  editable: PropTypes.bool,
+
+  /**
+   * See documentation for allowed values (varies between Web, Android and iOS) and important notes:
+   * - Native: https://reactnative.dev/docs/textinput#keyboardtype
+   * - Web: equivalent to `inputmode` but see https://necolas.github.io/react-native-web/docs/text-input/
+   */
+  keyboardType: PropTypes.string,
+
+  /**
+   * Uses native tools (no flicker) to cap the maximum number of characters.
+   * On Web, works via `maxlength` attr.
+   */
+  maxLength: PropTypes.number,
+
+  /**
+   * If passed as true, the text input can be multiple lines.
+   *
+   * > It is important to note that this aligns the text to the top on iOS, and centers it on Android.
+   * > Use with textAlignVertical set to top for the same behavior in both platforms.
+   */
+  multiline: PropTypes.bool,
+
+  /**
+   * Web and Android only, requires `multiline` to be `true`.
+   */
+  numberOfLines: PropTypes.number,
+
+  /**
+   * Text to display when no value set.
+   * Accesibility guidelines recommend using labels to describe the input and using
+   * placeholders rarely and sparingly to prompt a particular format.
+   */
+  placeholder: PropTypes.string,
+
+  /**
+   * Sets placeholder colour. On Web, uses `::placeholder { color: ... }` selector.
+   */
+  placeholderTextColor: PropTypes.string,
+
+  /**
+   * One of a subset of platform-specific options that controls labelling and presentation
+   * in on-screen keyboards and accessibility tools. Uses `enterkeyhint` attr on Web.
+   *
+   * 'done', 'go', 'next', 'search', and 'send' are available for Web, Android and iOS.
+   */
+  returnKeyType: PropTypes.string,
+
+  /**
+   * Obscures passwords and similar. Equivalent to type="password" on Web.
+   * Does not work if multiline is true.
+   */
+  secureTextEntry: PropTypes.bool,
+
+  /**
+   * If true, all text will automatically be selected on focus.
+   */
+  selectTextOnFocus: PropTypes.bool,
+
+  /**
+   * Web and iOS. On iOS, default inherits from `autoCorrect`.
+   * On Web, equivalent to `spellcheck` attr.
+   */
+  spellCheck: PropTypes.bool
+};
+/**
+ * These web-only props all control HTML `input` attributes of the same name.
+ * Refer to general HTML documentation for more details.
+ */
+
+const webOnly = {
+  disabled: PropTypes.bool,
+  dir: PropTypes.oneOf(['auto', 'ltr', 'rtl']),
+  lang: PropTypes.string,
+
+  /**
+   * Sets the HTML input `pattern` attr. Not supported by React Native Web, but is supported by UDS.
+   * Must also pass in a ref and check validity by calling the HTML element's checkValidity method:
+   * https://developer.mozilla.org/en-US/docs/Web/API/HTMLInputElement/checkValidity
+   */
+  pattern: PropTypes.string
+};
+/**
+ * These props are supported in React Native but not React Native Web.
+ *
+ * React Native text inputs can be quirky, so a full set of props should be allowed to handle edge cases.
+ * Refer to React Native documentation for details, allowed values, and Android/iOS support and versions:
+ * https://reactnative.dev/docs/textinput
+ *
+ * Beware that many React Native text input props apply via complicated logic that chooses a built-in
+ * native component based on the values of multiple boolean flags, and may sometimes appear to pick an
+ * option that is inappropriate for one flag based on the values of one or more other other flags.
+ */
+
+const nativeOnly = {
+  caretHidden: PropTypes.bool,
+  clearButtonMode: PropTypes.string,
+  contextMenuHidden: PropTypes.bool,
+  dataDetectorTypes: PropTypes.string,
+  disableFullscreenUI: PropTypes.bool,
+  enablesReturnKeyAutomatically: PropTypes.bool,
+  importantForAutofill: PropTypes.string,
+  inlineImageLeft: PropTypes.string,
+  keyboardAppearance: PropTypes.string,
+  returnKeyLabel: PropTypes.string,
+  rejectResponderTermination: PropTypes.bool,
+  scrollEnabled: PropTypes.bool,
+  selection: PropTypes.object,
+  selectionColor: PropTypes.string,
+  showSoftInputOnFocus: PropTypes.bool,
+  textAlign: PropTypes.string,
+  textContentType: PropTypes.string,
+  passwordRules: PropTypes.string,
+  textBreakStrategy: PropTypes.string,
+  underlineColorAndroid: PropTypes.string
+};
+export default {
+  /**
+   * Subset of proptypes that can be passed down to a React Native or React Native Web
+   * `TextInput` component. Allow regardless of platform, so cross-platform apps don't warn.
+   */
+  types: { ...crossPlatform,
+    ...webOnly,
+    ...nativeOnly
+  },
+
+  /**
+   * Filters a props object. Return only platform-appropriate TextInput props, native inputs
+   * may throw errors on receiving unknown props.
+   */
+  select: getPropSelector({ ...crossPlatform,
+    ...Platform.select({
+      web: webOnly,
+      default: nativeOnly
+    })
+  })
+};

package/lib-module/utils/props/textProps.js

@@ -0,0 +1,59 @@
+import PropTypes from 'prop-types';
+import Platform from "react-native-web/dist/exports/Platform";
+import getPropSelector from './getPropSelector'; // These are the props accepted specifically on React Native (Web) `Text` elements.
+// They are generally concerned with the behaviour of multiline text.
+
+const crossPlatform = {
+  /**
+   * Truncates text after this many lines with an ellipsis at the end.
+   * On native, ellipsis behaviour may be changed with `ellipsizeMode` prop.
+   */
+  numberOfLines: PropTypes.number,
+
+  /**
+   * Default is true on web and false on native
+   */
+  selectable: PropTypes.bool
+};
+/**
+ * See React Native docs for latest details on these.
+ * https://reactnative.dev/docs/text
+ */
+
+const nativeOnly = {
+  ellipsizeMode: PropTypes.string,
+  maxFontSizeMultiplier: PropTypes.number,
+  minimumFontScale: PropTypes.number,
+  onTextLayout: PropTypes.func,
+  suppressHighlighting: PropTypes.bool,
+  textBreakStrategy: PropTypes.string
+};
+/**
+ * These set HTML attributes of the same name.
+ */
+
+const webOnly = {
+  dir: PropTypes.oneOf(['auto', 'ltr', 'rtl']),
+  lang: PropTypes.string
+};
+export default {
+  /**
+   * Set of prop types specific to React Native and React Native Web `Text`,
+   * which largely revolve around the behaviour of multiline non-pressable text.
+   */
+  types: { ...crossPlatform,
+    ...webOnly,
+    ...nativeOnly
+  },
+
+  /**
+   * Filters a props object, returning only props specific to `Text` elements
+   * on the current platform. Does not include props applicable to `Text` and `View`.
+   */
+  select: getPropSelector({ ...crossPlatform,
+    ...Platform.select({
+      web: webOnly,
+      default: nativeOnly
+    })
+  })
+};