@telus-uds/components-base 1.2.0 → 1.3.0

package/lib/utils/props/clickProps.js

@@ -0,0 +1,36 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.default = void 0;
+
+var _propTypes = _interopRequireDefault(require("prop-types"));
+
+function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { default: obj }; }
+
+const clickHandlerMapping = {
+  onClick: 'onPress',
+  mouseDown: 'onPressIn',
+  mouseUp: 'onPressOut'
+};
+var _default = {
+  /**
+   * Web-oriented HTML click handlers that may be mapped to React Native press handlers
+   */
+  types: Object.fromEntries(Object.keys(clickHandlerMapping).map(mouseName => [mouseName, _propTypes.default.func])),
+
+  /**
+   * Takes a set of props and converts HTML mouse click oriented event handlers to closest
+   * equivalent React Native press event handler.
+   *
+   * Use this when a component that expects press-oriented props may need to support third-party
+   * web-oriented tooling that injects web-oriented event handlers directly. For example, for
+   * to support use with NextJS's 'next/link' component, which injects `onClick` prop into its child.
+   */
+  toPressProps: props => Object.fromEntries(Object.entries(props).map(([originalName, value]) => {
+    const translatedName = clickHandlerMapping[originalName];
+    return translatedName ? [translatedName, value] : [originalName, value];
+  }))
+};
+exports.default = _default;

package/lib/utils/props/componentPropType.js

@@ -0,0 +1,70 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.default = componentPropType;
+
+/**
+ * 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}
+ */
+function componentPropType(passedName) {
+  const passedNames = typeof passedName === 'string' ? [passedName] : passedName;
+
+  const checkProp = (props, propName, componentName) => {
+    var _props$propName$type, _props$propName$type2;
+
+    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 = props[propName].type) === null || _props$propName$type === void 0 ? void 0 : _props$propName$type.displayName) || ((_props$propName$type2 = props[propName].type) === null || _props$propName$type2 === void 0 ? void 0 : _props$propName$type2.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/utils/props/copyPropTypes.js

@@ -0,0 +1,14 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.default = void 0;
+
+var _propTypes = _interopRequireDefault(require("prop-types"));
+
+function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { default: obj }; }
+
+var _default = _propTypes.default.oneOf(['en', 'fr']);
+
+exports.default = _default;

package/lib/utils/props/getPropSelector.js

@@ -0,0 +1,13 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.default = getPropSelector;
+
+function getPropSelector(propTypes, regexp) {
+  const keys = Object.keys(propTypes);
+  return props => Object.entries(props).reduce((items, [key, value]) => keys.includes(key) || regexp && regexp.test(key) ? { ...items,
+    [key]: value
+  } : items, {});
+}

package/lib/utils/props/hrefAttrsProp.js

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

package/lib/utils/props/index.js

@@ -0,0 +1,149 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+var _exportNames = {
+  a11yProps: true,
+  clickProps: true,
+  copyPropTypes: true,
+  componentPropType: true,
+  hrefAttrsProp: true,
+  linkProps: true,
+  pressProps: true,
+  paddingProp: true,
+  rectProp: true,
+  responsiveProps: true,
+  spacingProps: true,
+  selectSystemProps: true,
+  variantProp: true,
+  viewProps: 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, "copyPropTypes", {
+  enumerable: true,
+  get: function () {
+    return _copyPropTypes.default;
+  }
+});
+Object.defineProperty(exports, "componentPropType", {
+  enumerable: true,
+  get: function () {
+    return _componentPropType.default;
+  }
+});
+Object.defineProperty(exports, "hrefAttrsProp", {
+  enumerable: true,
+  get: function () {
+    return _hrefAttrsProp.default;
+  }
+});
+Object.defineProperty(exports, "linkProps", {
+  enumerable: true,
+  get: function () {
+    return _linkProps.default;
+  }
+});
+Object.defineProperty(exports, "pressProps", {
+  enumerable: true,
+  get: function () {
+    return _pressProps.default;
+  }
+});
+Object.defineProperty(exports, "paddingProp", {
+  enumerable: true,
+  get: function () {
+    return _paddingProp.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, "spacingProps", {
+  enumerable: true,
+  get: function () {
+    return _spacingProps.default;
+  }
+});
+Object.defineProperty(exports, "selectSystemProps", {
+  enumerable: true,
+  get: function () {
+    return _selectSystemProps.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 _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 _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 _variantProp = _interopRequireDefault(require("./variantProp"));
+
+var _viewProps = _interopRequireDefault(require("./viewProps"));
+
+function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { default: obj }; }

package/lib/utils/props/linkProps.js

@@ -0,0 +1,64 @@
+"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(obj) { return obj && obj.__esModule ? obj : { default: obj }; }
+
+const linkPropTypes = { ..._pressProps.pressPropTypes,
+  href: _propTypes.default.string,
+  hrefAttrs: _propTypes.default.shape(_hrefAttrsProp.default.types),
+  ..._a11yProps.default.types
+};
+var _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 on Native and throw if not given `onPress` or `href`.
+   *
+   * @param {({ onPress?: () => void, href?: string })}
+   * @returns {(() => void)|undefined} Returns a press handler, or undefined on web if href
+   * string is provided. Expects calling component to use href string on web (e.g. in `<a>`).
+   */
+  handleHref: ({
+    onPress,
+    href
+  }) => {
+    if (!href && !onPress) {
+      throw new Error('handleHref requires either href or onPress');
+    }
+
+    return _Platform.default.select({
+      web: onPress,
+      default: (...args) => {
+        if (onPress) onPress(...args);
+        if (href) _Linking.default.openURL(href);
+      }
+    });
+  }
+};
+exports.default = _default;

package/lib/utils/props/paddingProp.js

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

package/lib/utils/props/pressProps.js

@@ -0,0 +1,57 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.default = exports.pressPropTypes = 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(obj) { return obj && obj.__esModule ? obj : { default: obj }; }
+
+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 = { ...pressHandlerPropTypes,
+  disabled: _propTypes.default.bool,
+  ..._Platform.default.select({
+    web: {},
+    default: {
+      hitSlop: _propTypes.default.number,
+      pressRetentionOffset: _propTypes.default.oneOfType([_propTypes.default.number, _rectProp.default.propType])
+    }
+  })
+};
+exports.pressPropTypes = pressPropTypes;
+var _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)
+};
+exports.default = _default;

package/lib/utils/props/rectProp.js

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

package/lib/utils/props/responsiveProps.js

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

package/lib/utils/props/selectSystemProps.js

@@ -0,0 +1,31 @@
+"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 === 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 ${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 ${propHelper}`);
+    }
+
+    return { ...acc,
+      ...propHelper.types
+    };
+  }, {});
+  return [selectProps, selectedPropTypes];
+}

package/lib/utils/props/spacingProps.js

@@ -0,0 +1,71 @@
+"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(obj) { return obj && obj.__esModule ? obj : { default: obj }; }
+
+/**
+ * @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 = {
+  scale: spacingScale,
+  types: {
+    spacingIndex: spacingIndexPropType,
+    spacingObject: spacingObjectPropType,
+    // Most spacing components and utilities take this prop / arg type:
+    spacingValue: _propTypes.default.oneOfType([spacingIndexPropType, spacingObjectPropType])
+  }
+};
+exports.default = _default;