@telus-uds/components-base 2.5.0 → 3.0.0

package/lib/cjs/utils/props/handlerProps.js

@@ -0,0 +1,111 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.textInputHandlerProps = exports.focusHandlerProps = void 0;
+var _propTypes = _interopRequireDefault(require("prop-types"));
+var _Platform = _interopRequireDefault(require("react-native-web/dist/cjs/exports/Platform"));
+var _getPropSelector = _interopRequireDefault(require("./getPropSelector"));
+function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
+const focusHandlerProps = exports.focusHandlerProps = {
+  types: {
+    /**
+     * onBlur handler
+     */
+    onBlur: _propTypes.default.func,
+    /**
+     * onFocus handler
+     */
+    onFocus: _propTypes.default.func
+  }
+};
+focusHandlerProps.select = (0, _getPropSelector.default)(focusHandlerProps.types);
+const textInputHandlerProps = exports.textInputHandlerProps = {
+  types: {
+    /**
+     * onChange handler
+     */
+    onChange: _propTypes.default.func,
+    /**
+     * onChangeText handler
+     */
+    onChangeText: _propTypes.default.func,
+    /**
+     * onClear handler
+     */
+    onClear: _propTypes.default.func,
+    /**
+     * onSubmit handler
+     */
+    onSubmit: _propTypes.default.func,
+    /**
+     * onSubmitEditing handler
+     */
+    onSubmitEditing: _propTypes.default.func,
+    /**
+     * onContentSizeChange handler
+     */
+    onContentSizeChange: _propTypes.default.func,
+    /**
+     * onEndEditing handler
+     */
+    onEndEditing: _propTypes.default.func,
+    /**
+     * onScroll handler
+     */
+    onScroll: _propTypes.default.func,
+    /**
+     * onSelectionChange handler
+     */
+    onSelectionChange: _propTypes.default.func,
+    /**
+     * onKeyPress handler
+     */
+    onKeyPress: _propTypes.default.func,
+    /**
+     * onKeyUp handler (only supported on Web)
+     */
+    onKeyUp: _propTypes.default.func,
+    /**
+     * onKeyDown handler (only supported on Web)
+     */
+    onMouseOver: _propTypes.default.func,
+    /**
+     * onKeyDown handler (only supported on Web)
+     */
+    onMouseOut: _propTypes.default.func
+  }
+};
+const selectTextInputHandlers = (0, _getPropSelector.default)(textInputHandlerProps.types);
+textInputHandlerProps.select = props => {
+  // Support for onKeyPress/onKeyUp/onKeyDown is inconsistent between React Native and React Native Web
+  const {
+    onKeyPress,
+    onKeyUp,
+    onKeyDown,
+    ...resolvedProps
+  } = selectTextInputHandlers(props);
+  if (onKeyPress || onKeyUp || onKeyDown) {
+    if (_Platform.default.OS !== 'web') {
+      // React Native only supports onKeyPress. Call any key handlers supplied in expected order.
+      resolvedProps.onKeyPress = event => {
+        if (typeof onKeyDown === 'function') onKeyDown(event);
+        if (typeof onKeyPress === 'function') onKeyPress(event);
+        if (typeof onKeyUp === 'function') onKeyUp(event);
+      };
+    } else {
+      // React Native Web supports onKeyUp the normal way.
+      if (onKeyUp) resolvedProps.onKeyUp = onKeyUp;
+      // React Native Web doesn't support the `onKeyDown` prop name, but maps a supplied onKeyPress handler
+      // to the onKeyDown event and calls it with a keydown event. Make React Native Web call either or both.
+      if (onKeyPress || onKeyDown) {
+        resolvedProps.onKeyPress = event => {
+          if (typeof onKeyDown === 'function') onKeyDown(event);
+          if (typeof onKeyPress === 'function') onKeyPress(event);
+        };
+      }
+    }
+  }
+  return resolvedProps;
+};

package/lib/cjs/utils/props/hrefAttrsProp.js

@@ -0,0 +1,39 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.default = void 0;
+var _propTypes = _interopRequireDefault(require("prop-types"));
+function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
+// Props related to HTML <a> anchor link attributes.
+const targetValues = ['_self', '_blank', '_parent', '_top'];
+var _default = exports.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.default.string,
+    rel: _propTypes.default.string,
+    target: _propTypes.default.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/cjs/utils/props/index.js

@@ -0,0 +1,176 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+var _exportNames = {
+  a11yProps: true,
+  clickProps: true,
+  copyPropTypes: true,
+  componentPropType: true,
+  hrefAttrsProp: true,
+  inputSupportsProps: true,
+  linkProps: true,
+  pressProps: true,
+  paddingProp: true,
+  rectProp: true,
+  responsiveProps: true,
+  spacingProps: true,
+  selectSystemProps: true,
+  textInputProps: true,
+  textProps: true,
+  variantProp: true,
+  viewProps: true,
+  contentfulProps: true
+};
+Object.defineProperty(exports, "a11yProps", {
+  enumerable: true,
+  get: function () {
+    return _a11yProps.default;
+  }
+});
+Object.defineProperty(exports, "clickProps", {
+  enumerable: true,
+  get: function () {
+    return _clickProps.default;
+  }
+});
+Object.defineProperty(exports, "componentPropType", {
+  enumerable: true,
+  get: function () {
+    return _componentPropType.default;
+  }
+});
+Object.defineProperty(exports, "contentfulProps", {
+  enumerable: true,
+  get: function () {
+    return _contentfulProps.default;
+  }
+});
+Object.defineProperty(exports, "copyPropTypes", {
+  enumerable: true,
+  get: function () {
+    return _copyPropTypes.default;
+  }
+});
+Object.defineProperty(exports, "hrefAttrsProp", {
+  enumerable: true,
+  get: function () {
+    return _hrefAttrsProp.default;
+  }
+});
+Object.defineProperty(exports, "inputSupportsProps", {
+  enumerable: true,
+  get: function () {
+    return _inputSupportsProps.default;
+  }
+});
+Object.defineProperty(exports, "linkProps", {
+  enumerable: true,
+  get: function () {
+    return _linkProps.default;
+  }
+});
+Object.defineProperty(exports, "paddingProp", {
+  enumerable: true,
+  get: function () {
+    return _paddingProp.default;
+  }
+});
+Object.defineProperty(exports, "pressProps", {
+  enumerable: true,
+  get: function () {
+    return _pressProps.default;
+  }
+});
+Object.defineProperty(exports, "rectProp", {
+  enumerable: true,
+  get: function () {
+    return _rectProp.default;
+  }
+});
+Object.defineProperty(exports, "responsiveProps", {
+  enumerable: true,
+  get: function () {
+    return _responsiveProps.default;
+  }
+});
+Object.defineProperty(exports, "selectSystemProps", {
+  enumerable: true,
+  get: function () {
+    return _selectSystemProps.default;
+  }
+});
+Object.defineProperty(exports, "spacingProps", {
+  enumerable: true,
+  get: function () {
+    return _spacingProps.default;
+  }
+});
+Object.defineProperty(exports, "textInputProps", {
+  enumerable: true,
+  get: function () {
+    return _textInputProps.default;
+  }
+});
+Object.defineProperty(exports, "textProps", {
+  enumerable: true,
+  get: function () {
+    return _textProps.default;
+  }
+});
+Object.defineProperty(exports, "variantProp", {
+  enumerable: true,
+  get: function () {
+    return _variantProp.default;
+  }
+});
+Object.defineProperty(exports, "viewProps", {
+  enumerable: true,
+  get: function () {
+    return _viewProps.default;
+  }
+});
+var _tokens = require("./tokens");
+Object.keys(_tokens).forEach(function (key) {
+  if (key === "default" || key === "__esModule") return;
+  if (Object.prototype.hasOwnProperty.call(_exportNames, key)) return;
+  if (key in exports && exports[key] === _tokens[key]) return;
+  Object.defineProperty(exports, key, {
+    enumerable: true,
+    get: function () {
+      return _tokens[key];
+    }
+  });
+});
+var _handlerProps = require("./handlerProps");
+Object.keys(_handlerProps).forEach(function (key) {
+  if (key === "default" || key === "__esModule") return;
+  if (Object.prototype.hasOwnProperty.call(_exportNames, key)) return;
+  if (key in exports && exports[key] === _handlerProps[key]) return;
+  Object.defineProperty(exports, key, {
+    enumerable: true,
+    get: function () {
+      return _handlerProps[key];
+    }
+  });
+});
+var _a11yProps = _interopRequireDefault(require("./a11yProps"));
+var _clickProps = _interopRequireDefault(require("./clickProps"));
+var _copyPropTypes = _interopRequireDefault(require("./copyPropTypes"));
+var _componentPropType = _interopRequireDefault(require("./componentPropType"));
+var _hrefAttrsProp = _interopRequireDefault(require("./hrefAttrsProp"));
+var _inputSupportsProps = _interopRequireDefault(require("./inputSupportsProps"));
+var _linkProps = _interopRequireDefault(require("./linkProps"));
+var _pressProps = _interopRequireDefault(require("./pressProps"));
+var _paddingProp = _interopRequireDefault(require("./paddingProp"));
+var _rectProp = _interopRequireDefault(require("./rectProp"));
+var _responsiveProps = _interopRequireDefault(require("./responsiveProps"));
+var _spacingProps = _interopRequireDefault(require("./spacingProps"));
+var _selectSystemProps = _interopRequireDefault(require("./selectSystemProps"));
+var _textInputProps = _interopRequireDefault(require("./textInputProps"));
+var _textProps = _interopRequireDefault(require("./textProps"));
+var _variantProp = _interopRequireDefault(require("./variantProp"));
+var _viewProps = _interopRequireDefault(require("./viewProps"));
+var _contentfulProps = _interopRequireDefault(require("./contentfulProps"));
+function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }

package/lib/cjs/utils/props/inputSupportsProps.js

@@ -0,0 +1,87 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.default = void 0;
+var _propTypes = _interopRequireDefault(require("prop-types"));
+function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
+var _default = exports.default = {
+  types: {
+    /**
+     * Whether the English or French copy will be used (e.g. for accessibility labels).
+     */
+    copy: _propTypes.default.oneOf(['en', 'fr']),
+    /**
+     * The input label.
+     */
+    label: _propTypes.default.string,
+    /**
+     * A short description of the expected input.
+     */
+    hint: _propTypes.default.string,
+    /**
+     * Position of the hint relative to label. Use `below` to display a larger hint below the label.
+     */
+    hintPosition: _propTypes.default.oneOf(['inline', 'below']),
+    /**
+     * A detailed description of validation error/success or additional instructions.
+     * Visual variant is determined based on the `validation` prop.
+     */
+    feedback: _propTypes.default.string,
+    /**
+     * Tokens to be passed to the feedback component.
+     */
+    feedbackTokens: _propTypes.default.object,
+    /**
+     * Props to be passed to the feedback component.
+     */
+    feedbackProps: _propTypes.default.object,
+    /**
+     * Content of an optional `Tooltip`. If set, a tooltip button will be shown next to the label.
+     */
+    tooltip: _propTypes.default.string,
+    /**
+     * Use to visually mark an input as valid or invalid.
+     */
+    validation: _propTypes.default.oneOf(['error', 'success']),
+    /**
+     * The text value from an input field.
+     */
+    inputValue: _propTypes.default.string,
+    /**
+     * Max number of characters allowed id an input text.
+     */
+    maxCharacterAllowed: _propTypes.default.number
+  },
+  select: _ref => {
+    let {
+      copy,
+      label,
+      hint,
+      hintPosition,
+      feedback,
+      feedbackTokens,
+      feedbackProps,
+      tooltip,
+      validation,
+      inputValue,
+      maxCharacterAllowed
+    } = _ref;
+    return {
+      supportsProps: {
+        copy,
+        label,
+        hint,
+        hintPosition,
+        feedback,
+        feedbackTokens,
+        feedbackProps,
+        tooltip,
+        validation,
+        inputValue,
+        maxCharacterAllowed
+      }
+    };
+  }
+};

package/lib/cjs/utils/props/linkProps.js

@@ -0,0 +1,50 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.default = void 0;
+var _Linking = _interopRequireDefault(require("react-native-web/dist/cjs/exports/Linking"));
+var _Platform = _interopRequireDefault(require("react-native-web/dist/cjs/exports/Platform"));
+var _propTypes = _interopRequireDefault(require("prop-types"));
+var _pressProps = require("./pressProps");
+var _a11yProps = _interopRequireDefault(require("./a11yProps"));
+var _hrefAttrsProp = _interopRequireDefault(require("./hrefAttrsProp"));
+var _getPropSelector = _interopRequireDefault(require("./getPropSelector"));
+function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
+const linkPropTypes = {
+  ..._pressProps.pressPropTypes,
+  href: _propTypes.default.string,
+  hrefAttrs: _propTypes.default.shape(_hrefAttrsProp.default.types),
+  ..._a11yProps.default.types
+};
+var _default = exports.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: (0, _getPropSelector.default)(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.default.select({
+      web: onPress,
+      default: function () {
+        if (onPress) onPress(...arguments);
+        if (href) _Linking.default.openURL(href);
+      }
+    });
+  }
+};

package/lib/cjs/utils/props/paddingProp.js

@@ -0,0 +1,16 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.default = void 0;
+var _propTypes = _interopRequireDefault(require("prop-types"));
+function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
+var _default = exports.default = {
+  propType: _propTypes.default.shape({
+    paddingBottom: _propTypes.default.number,
+    paddingLeft: _propTypes.default.number,
+    paddingRight: _propTypes.default.number,
+    paddingTop: _propTypes.default.number
+  })
+};

package/lib/cjs/utils/props/pressProps.js

@@ -0,0 +1,49 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.pressPropTypes = exports.default = void 0;
+var _Platform = _interopRequireDefault(require("react-native-web/dist/cjs/exports/Platform"));
+var _propTypes = _interopRequireDefault(require("prop-types"));
+var _rectProp = _interopRequireDefault(require("./rectProp"));
+var _getPropSelector = _interopRequireDefault(require("./getPropSelector"));
+function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
+const pressHandlerPropTypes = {
+  onPress: _propTypes.default.func,
+  onPressIn: _propTypes.default.func,
+  onPressOut: _propTypes.default.func,
+  ..._Platform.default.select({
+    web: {
+      onMouseEnter: _propTypes.default.func,
+      onMouseLeave: _propTypes.default.func,
+      onFocus: _propTypes.default.func,
+      onBlur: _propTypes.default.func
+    },
+    default: {
+      onLongPress: _propTypes.default.func
+    }
+  })
+};
+const pressPropTypes = exports.pressPropTypes = {
+  ...pressHandlerPropTypes,
+  disabled: _propTypes.default.bool,
+  ..._Platform.default.select({
+    web: {},
+    default: {
+      hitSlop: _propTypes.default.number,
+      pressRetentionOffset: _propTypes.default.oneOfType([_propTypes.default.number, _rectProp.default.propType])
+    }
+  })
+};
+var _default = exports.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: (0, _getPropSelector.default)(pressPropTypes),
+  selectHandlers: (0, _getPropSelector.default)(pressHandlerPropTypes)
+};

package/lib/cjs/utils/props/rectProp.js

@@ -0,0 +1,16 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.default = void 0;
+var _propTypes = _interopRequireDefault(require("prop-types"));
+function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
+var _default = exports.default = {
+  propType: _propTypes.default.shape({
+    bottom: _propTypes.default.number,
+    left: _propTypes.default.number,
+    right: _propTypes.default.number,
+    top: _propTypes.default.number
+  })
+};

package/lib/cjs/utils/props/responsiveProps.js

@@ -0,0 +1,35 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.default = void 0;
+var _propTypes = _interopRequireDefault(require("prop-types"));
+function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
+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
+ */
+var _default = exports.default = {
+  getByViewport,
+  getTypeByViewport: propType => _propTypes.default.shape(getByViewport(propType)),
+  getTypeOptionallyByViewport: propType => _propTypes.default.oneOfType([propType, _propTypes.default.shape(getByViewport(propType))])
+};

package/lib/cjs/utils/props/selectSystemProps.js

@@ -0,0 +1,29 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.default = selectSystemProps;
+// Returns a selector for requested prop kinds as well as the propTypes for
+// those props merged into one object
+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/cjs/utils/props/spacingProps.js

@@ -0,0 +1,63 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.default = void 0;
+var _propTypes = _interopRequireDefault(require("prop-types"));
+var _responsiveProps = _interopRequireDefault(require("./responsiveProps"));
+var _variantProp = _interopRequireDefault(require("./variantProp"));
+function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
+/**
+ * @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.default.oneOf(spacingScale);
+const spacingObjectPropType = _propTypes.default.shape({
+  ..._responsiveProps.default.getByViewport(spacingIndexPropType),
+  space: spacingIndexPropType,
+  options: _propTypes.default.shape({
+    variant: _variantProp.default.propType,
+    size: _propTypes.default.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.
+ */
+var _default = exports.default = {
+  scale: spacingScale,
+  types: {
+    spacingIndex: spacingIndexPropType,
+    spacingObject: spacingObjectPropType,
+    // Most spacing components and utilities take this prop / arg type:
+    spacingValue: _propTypes.default.oneOfType([spacingIndexPropType, spacingObjectPropType])
+  }
+};