@carbon/ibm-products 1.0.0-rc.1 → 1.1.0

package/lib/global/js/utils/props-helper.js

@@ -0,0 +1,304 @@
+"use strict";
+
+var _interopRequireDefault = require("@babel/runtime/helpers/interopRequireDefault");
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.prepareProps = exports.isRequiredIf = exports.getDeprecatedArgTypes = exports.extractShapesArray = exports.deprecatePropUsage = exports.deprecateProp = exports.allPropTypes = void 0;
+
+var _slicedToArray2 = _interopRequireDefault(require("@babel/runtime/helpers/slicedToArray"));
+
+var _toConsumableArray2 = _interopRequireDefault(require("@babel/runtime/helpers/toConsumableArray"));
+
+var _defineProperty2 = _interopRequireDefault(require("@babel/runtime/helpers/defineProperty"));
+
+var _react = _interopRequireDefault(require("react"));
+
+var _propTypes = _interopRequireDefault(require("prop-types"));
+
+var _unwrapIfFragment = _interopRequireDefault(require("./unwrap-if-fragment"));
+
+var _pconsole = _interopRequireDefault(require("./pconsole"));
+
+function ownKeys(object, enumerableOnly) { var keys = Object.keys(object); if (Object.getOwnPropertySymbols) { var symbols = Object.getOwnPropertySymbols(object); if (enumerableOnly) { symbols = symbols.filter(function (sym) { return Object.getOwnPropertyDescriptor(object, sym).enumerable; }); } keys.push.apply(keys, symbols); } return keys; }
+
+function _objectSpread(target) { for (var i = 1; i < arguments.length; i++) { var source = arguments[i] != null ? arguments[i] : {}; if (i % 2) { ownKeys(Object(source), true).forEach(function (key) { (0, _defineProperty2.default)(target, key, source[key]); }); } else if (Object.getOwnPropertyDescriptors) { Object.defineProperties(target, Object.getOwnPropertyDescriptors(source)); } else { ownKeys(Object(source)).forEach(function (key) { Object.defineProperty(target, key, Object.getOwnPropertyDescriptor(source, key)); }); } } return target; }
+
+// helper functions for component props
+
+/**
+ * Prepare a set of props, or prop types or default props, merging values
+ * from one or more sets and optionally blocking keys which should not be
+ * passed. Returns the prepared set of props. Does not modify any of the
+ * objects passed.
+ *
+ * @param {{} | '' | ['']} values One or more sets of keys and values to be
+ * merged, or names of keys to be blocked. Each parameter that is an object is
+ * treated as keys and values to be merged, and each parameter that is a string
+ * or an array of strings is treated as keys to be blocked.
+ *
+ * Examples:
+ *   const props = { a: 3, c: 4, d: 5 };
+ *
+ *   * prepareProps(props) -> { a: 3, c: 4, d: 5 }
+ *   * prepareProps(props, 'c') -> { a: 3, d: 5 }
+ *   * prepareProps(props, ['a', 'c', 'e']) -> { d: 5 }
+ *
+ *   * prepareProps({ a: 1, b: 2 }, props) -> { a: 3, b: 2, c: 4, d: 5 }
+ *   * prepareProps({ a: 1, b: 2 }, props, ['a', 'c']) -> { b: 2, d: 5 }
+ *
+ *   * prepareProps(props, { c: 6 }) -> { a: 3, c: 6, d: 5 }
+ *   * prepareProps(props, 'a', { c: 6 }) -> { c: 6, d: 5 }
+ */
+var prepareProps = function prepareProps() {
+  // Convert any string or array arg into an object with nulls as values
+  var toNulls = function toNulls(arg) {
+    return typeof arg === 'string' ? (0, _defineProperty2.default)({}, arg, null) : Array.isArray(arg) ? Object.fromEntries(arg.map(function (key) {
+      return [key, null];
+    })) : arg;
+  }; // Merge all the args from left to right
+
+
+  for (var _len = arguments.length, values = new Array(_len), _key = 0; _key < _len; _key++) {
+    values[_key] = arguments[_key];
+  }
+
+  var merged = Object.assign.apply(Object, [{}].concat((0, _toConsumableArray2.default)(values.map(toNulls)))); // Now strip any keys whose final value is null
+
+  return Object.entries(merged).reduce(function (result, _ref2) {
+    var _ref3 = (0, _slicedToArray2.default)(_ref2, 2),
+        key = _ref3[0],
+        value = _ref3[1];
+
+    if (value !== null) {
+      result[key] = value;
+    }
+
+    return result;
+  }, {});
+}; // Determine whether a named prop in a set of props has been given a value.
+// null and undefined do not count as values, but anything else does. If the
+// prop is 'children', then an array of null/undefined also does not count as
+// a value, but anything else does.
+
+
+exports.prepareProps = prepareProps;
+
+var propHasValue = function propHasValue(props, propName) {
+  var result = props[propName] !== null && props[propName] !== undefined;
+
+  if (result && propName === 'children' && Array.isArray(props[propName])) {
+    result = false;
+
+    for (var i = 0; !result && i < props[propName].length; i++) {
+      result = props[propName][i] !== null && props[propName][i] !== undefined;
+    }
+  }
+
+  return result;
+};
+/**
+ * A prop-types type checker that marks a particular usage of a prop as
+ * deprecated. The deprecation message is reported if the deprecated validator
+ * matches the supplied value.
+ * @param {} validator The prop-types validator for the prop usage that is
+ * currently supported. If the deprecated validator does not match the supplied
+ * value and this validator produces type checking errors they will be reported
+ * as usual.
+ * @param {} deprecated The prop-types validator for the prop usage that is
+ * now deprecated. If the deprecated validator matches the supplied value the
+ * deprecation warning message is reported but the value is considered valid.
+ * @param {*} additionalInfo One or more sentences to be appended to the
+ * deprecation message to explain why the prop usage is deprecated and/or what
+ * should be used instead.
+ * @returns Any type checking error reported by the validator, or null.
+ */
+
+
+var deprecatePropUsage = function deprecatePropUsage(validator, deprecated, additionalInfo) {
+  return function (props, propName, comp, loc, propFullName, secret) {
+    if (propHasValue(props, propName) && deprecated(props, propName, comp, loc, propFullName, secret) === null) {
+      _pconsole.default.warn("The usage of the ".concat(loc, " `").concat(propFullName || propName, "` of `").concat(comp, "` has been changed and support for the old usage will soon be removed. ").concat(additionalInfo));
+
+      return null;
+    } else {
+      return validator(props, propName, comp, loc, propFullName, secret);
+    }
+  };
+};
+/**
+ * A prop-types type checker that marks a prop as deprecated.
+ * @param {} validator The prop-types validator for the prop as it should be
+ * used if it weren't deprecated. If this validator produces type checking
+ * errors they will be reported as usual.
+ * @param {*} additionalInfo One or more sentences to be appended to the
+ * deprecation message to explain why the prop is deprecated and/or what should
+ * be used instead.
+ * @returns Any type checking error reported by the validator, or null.
+ */
+
+
+exports.deprecatePropUsage = deprecatePropUsage;
+
+var deprecateProp = function deprecateProp(validator, additionalInfo) {
+  return function (props, propName, comp, loc, propFullName, secret) {
+    if (propHasValue(props, propName)) {
+      _pconsole.default.warn("The ".concat(loc, " `").concat(propFullName || propName, "` of `").concat(comp, "` has been deprecated and will soon be removed. ").concat(additionalInfo));
+    }
+
+    return validator(props, propName, comp, loc, propFullName, secret);
+  };
+};
+/**
+ * A function that returns a storybook argTypes object configured to remove deprecated
+ * props from the storybook controls
+ */
+
+
+exports.deprecateProp = deprecateProp;
+
+var getDeprecatedArgTypes = function getDeprecatedArgTypes(deprecatedProps) {
+  var keys = Object.keys(deprecatedProps);
+  return keys.reduce(function (acc, cur) {
+    return acc[cur] = {
+      table: {
+        disable: true
+      }
+    }, acc;
+  }, {});
+};
+/**
+ * Takes items as fragment, node or array
+ * @param {node || array} items - which may have shape to extract
+ * @returns Array of items
+ */
+
+
+exports.getDeprecatedArgTypes = getDeprecatedArgTypes;
+
+var extractShapesArray = function extractShapesArray(items) {
+  var _items$, _items$2;
+
+  // unwrap if items or the first index looks like a React element or fragment
+  if (items && (items !== null && items !== void 0 && (_items$ = items[0]) !== null && _items$ !== void 0 && _items$.props || (items === null || items === void 0 ? void 0 : (_items$2 = items[0]) === null || _items$2 === void 0 ? void 0 : _items$2.type) === _react.default.Fragment || items.type === _react.default.Fragment)) {
+    var unwrappedItems = (0, _unwrapIfFragment.default)(items);
+    return unwrappedItems.map(function (item) {
+      return _objectSpread({
+        key: item.key
+      }, item.props);
+    });
+  }
+
+  return Array.isArray(items) ? items : [];
+};
+/**
+ * A prop-types validation function that takes an array of type checkers and
+ * requires prop values to satisfy all of the type checkers. This can be useful
+ * to combine custom validation functions with regular prop types, or for
+ * combining inherited prop-types from another component with tighter
+ * requirements.
+ *
+ * Examples:
+ *
+ * MyComponent.propTypes = {
+ *
+ *   foo: allPropTypes([
+ *     customValidationFunction,
+ *     PropTypes.arrayOf(
+ *       PropTypes.shape({
+ *         text: PropType.string
+ *       })
+ *     )
+ *   ]),
+ *
+ *   kind: allPropTypes([
+ *     Button.propTypes.kind,
+ *     PropTypes.oneOf(['primary', 'secondary'])
+ *   ]),
+ *
+ * }
+ */
+
+
+exports.extractShapesArray = extractShapesArray;
+
+var allPropTypes = _pconsole.default.shimIfProduction(function (arrayOfTypeCheckers) {
+  if (!Array.isArray(arrayOfTypeCheckers)) {
+    _pconsole.default.error('Warning: Invalid argument supplied to allPropTypes, expected an instance of array.');
+
+    return _pconsole.default.noop;
+  }
+
+  for (var i = 0; i < arrayOfTypeCheckers.length; i++) {
+    if (typeof arrayOfTypeCheckers[i] !== 'function') {
+      _pconsole.default.error("Invalid argument supplied to allPropTypes. Expected an array of check functions, but received ".concat(arrayOfTypeCheckers[i], " at index ").concat(i, "."));
+
+      return _pconsole.default.noop;
+    }
+  }
+
+  var checkType = function checkType() {
+    for (var _len2 = arguments.length, args = new Array(_len2), _key2 = 0; _key2 < _len2; _key2++) {
+      args[_key2] = arguments[_key2];
+    }
+
+    var error = null;
+    arrayOfTypeCheckers.some(function (checker) {
+      return error = checker.apply(void 0, args);
+    });
+    return error;
+  };
+
+  checkType.isRequired = function (props, propName, comp, loc, propFullName, secret) {
+    var prop = propFullName || propName;
+    return props[prop] == null ? new Error("The ".concat(loc, " `").concat(prop, "` is marked as required in `").concat(comp || '<<anonymous>>', "`, but its value is `").concat(props[prop] === null ? 'null' : 'undefined', "`.")) : checkType(props, prop, comp, loc, propFullName, secret);
+  };
+
+  return checkType;
+});
+/**
+ * A prop-types validation function that takes a type checkers and a condition
+ * function and invokes either the type checker or the isRequired variant of
+ * the type checker according to whether the condition function returns false
+ * or true when called with the full set of props. This can be useful to make
+ * a prop conditionally required. The function also has a decorate function
+ * which can be used to add isRequiredIf to any existing type which already has
+ * an isRequired variant, and this is automatically applied to the simple type
+ * checkers in PropTypes when this props-helper module is imported. The second
+ * example produces better results with DocGen and Storybook.
+ *
+ * Examples:
+ *
+ * MyComponent1.propTypes = {
+ *   showFoo: PropTypes.bool,
+ *   fooLabel: isRequiredIf(PropTypes.string, ({ showFoo }) => showFoo),
+ * }
+ *
+ * MyComponent2.propTypes = {
+ *   showBar: PropTypes.bool,
+ *   barLabel: PropTypes.string.isRequired.if(({ showBar }) => showBar),
+ * }
+ *
+ */
+
+
+exports.allPropTypes = allPropTypes;
+
+var isRequiredIf = function isRequiredIf(checker, conditionFn) {
+  return function (props, propName, componentName, location, propFullName, secret) {
+    return (conditionFn(props) ? checker.isRequired : checker)(props, propName, componentName, location, propFullName, secret);
+  };
+};
+
+exports.isRequiredIf = isRequiredIf;
+
+isRequiredIf.decorate = function (checker) {
+  checker.isRequired.if = _pconsole.default.isProduction ? _pconsole.default.noop : isRequiredIf.bind(null, checker);
+};
+
+for (var checker in _propTypes.default) {
+  if (_propTypes.default[checker].isRequired) {
+    isRequiredIf.decorate(_propTypes.default[checker]);
+  }
+}

package/lib/global/js/utils/scrollableAncestor.js

@@ -0,0 +1,48 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.scrollableAncestor = void 0;
+var windowExists = typeof window !== "undefined"; // determine whether the target is scrollable
+
+var scrollable = function scrollable(target) {
+  var style = window.getComputedStyle(target);
+  return /(auto|scroll|hidden)/.test(style.overflow);
+};
+
+var scrollableAncestorInner = function scrollableAncestorInner(target) {
+  if (target.parentNode && target.parentNode !== document) {
+    if (scrollable(target.parentNode)) {
+      return target.parentNode;
+    } else {
+      return scrollableAncestorInner(target.parentNode);
+    }
+  } else {
+    return document.scrollingElement;
+  }
+};
+/**
+ * Walks up the parent nodes to identify the first scrollable ancestor
+ *
+ * @param {HTMLElement} target
+ * @returns {HTMLElement}
+ */
+
+
+var scrollableAncestor = function scrollableAncestor(target) {
+  if (!windowExists || !target) {
+    return null;
+  } // based on https://stackoverflow.com/questions/35939886/find-first-scrollable-parent
+
+
+  var style = window.getComputedStyle(target);
+
+  if (!target || style.position === 'fixed') {
+    return document.scrollingElement;
+  }
+
+  return scrollableAncestorInner(target);
+};
+
+exports.scrollableAncestor = scrollableAncestor;

package/lib/global/js/utils/story-helper.js

@@ -0,0 +1,100 @@
+"use strict";
+
+var _interopRequireDefault = require("@babel/runtime/helpers/interopRequireDefault");
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.prepareStory = exports.getStoryTitle = exports.getStoryId = exports.CodesandboxLink = void 0;
+
+var _react = _interopRequireDefault(require("react"));
+
+var _propTypes = _interopRequireDefault(require("prop-types"));
+
+var _csf = require("@storybook/csf");
+
+var _packageSettings = _interopRequireDefault(require("../package-settings"));
+
+var _storyStructure = require("../../../../../core/story-structure");
+
+//
+// Copyright IBM Corp. 2021, 2021
+//
+// This source code is licensed under the Apache-2.0 license found in the
+// LICENSE file in the root directory of this source tree.
+//
+
+/**
+ * A helper function to return the structured story title for a component.
+ * @param {string} componentName The name of the component.
+ * @returns The structured story title.
+ */
+var getStoryTitle = function getStoryTitle(componentName) {
+  var title = // if the component isn't in the master structure, put it in a lost+found section
+  (0, _storyStructure.getPathForComponent)('c', componentName) || "Cloud & Cognitive/Lost + found/".concat(componentName); // add a canary tag if the component is public but not normally enabled
+
+  return !_packageSettings.default.isComponentEnabled(componentName, true) && _packageSettings.default.isComponentPublic(componentName, true) ? "".concat(title, "#canary") : title;
+};
+/**
+ * A helper function to return the slug (structured path name reduced to lower
+ * case text and hyphens) which identifies individual story instances.
+ * @param {string} componentName The name of the component.
+ * @param {string} scenario The scenario name, also as a slug.
+ * @returns The story id.
+ */
+
+
+exports.getStoryTitle = getStoryTitle;
+
+var getStoryId = function getStoryId(componentName, scenario) {
+  return "".concat((0, _csf.sanitize)(getStoryTitle(componentName)), "--").concat(scenario);
+};
+/**
+ * A helper function to prepare storybook stories for export. This function
+ * binds the template, adds the supplied fields, and also inserts a sequence
+ * number so that stories can then be sorted into declared order reliably.
+ * @param template the story template render function
+ * @param options an object containing fields to be added to the bound
+ * template, such as `args`, `storyName`, etc.
+ * @returns A bound template with the option fields applied.
+ */
+
+
+exports.getStoryId = getStoryId;
+var sequence = 0;
+var bindTarget = {};
+
+var prepareStory = function prepareStory(template, options) {
+  var _result$parameters, _result$parameters2, _result$parameters2$c;
+
+  var result = Object.assign(template.bind(bindTarget), options);
+  (_result$parameters = result.parameters) !== null && _result$parameters !== void 0 ? _result$parameters : result.parameters = {};
+  (_result$parameters2$c = (_result$parameters2 = result.parameters).ccsSettings) !== null && _result$parameters2$c !== void 0 ? _result$parameters2$c : _result$parameters2.ccsSettings = {};
+  result.parameters.ccsSettings.sequence = sequence++;
+  return result;
+};
+/**
+ * A helper component that returns a codesandbox link to an example codesandbox for the component.
+ * The link URL is based on the example directory name and the standard codesandbox URL for package examples.
+ */
+
+
+exports.prepareStory = prepareStory;
+
+var CodesandboxLink = function CodesandboxLink(_ref) {
+  var exampleDirectory = _ref.exampleDirectory;
+  return /*#__PURE__*/_react.default.createElement("a", {
+    href: "https://codesandbox.io/s/github/carbon-design-system/ibm-cloud-cognitive/tree/main/examples/cloud-cognitive/".concat(exampleDirectory)
+  }, /*#__PURE__*/_react.default.createElement("img", {
+    alt: "Edit on CodeSandbox",
+    src: "https://codesandbox.io/static/img/play-codesandbox.svg"
+  }));
+};
+
+exports.CodesandboxLink = CodesandboxLink;
+CodesandboxLink.propTypes = {
+  /**
+   * directory withing examples codesandbox will be found
+   */
+  exampleDirectory: _propTypes.default.string
+};