@instructure/ui-prop-types/es/Children.js

/*
 * The MIT License (MIT)
 *
 * Copyright (c) 2015 - present Instructure, Inc.
 *
 * Permission is hereby granted, free of charge, to any person obtaining a copy
 * of this software and associated documentation files (the "Software"), to deal
 * in the Software without restriction, including without limitation the rights
 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
 * copies of the Software, and to permit persons to whom the Software is
 * furnished to do so, subject to the following conditions:
 *
 * The above copyright notice and this permission notice shall be included in all
 * copies or substantial portions of the Software.
 *
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 * SOFTWARE.
 */
import React from 'react';
import { makeRequirable } from './makeRequirable';
var Children = {
  /**
   * Validate that the children of a component are one of the specified types.
   *
   * ```js
   *  import { Children } from '@instructure/ui-prop-types'
   *
   *  class Example extends Component {
   *    static propTypes = {
   *      children: Children.oneOf([Foo, Bar, Baz])
   *    }
   *
   *    render () {
   *      return <div>{this.props.children}</div>
   *    }
   *  }
   * ```
   *
   * This will allow children such as:
   *
   * ```jsx
   *  <Example>
   *    <Foo />
   *  </Example>
   * ```
   *
   *  OR
   *
   * ```jsx
   *  <Example>
   *    <Bar />
   *    <Foo />
   *  </Example>
   * ```
   *
   * But will fail on something like:
   *
   * ```jsx
   *  <Example>
   *    <h1>Example</h1>
   *    <Foo />
   *  </Example>
   * ```
   * @returns {Error} if validation failed
   */
  oneOf: function oneOf(validTypes) {
    function validator(props, propName, componentName) {
      var children = React.Children.toArray(props[propName]);
      var validTypeNames = validTypes.map(function (type) {
        return type ? getDisplayName(type) : type;
      });

      for (var i = 0; i < children.length; i++) {
        var child = children[i];

        if (child && child.type) {
          var childName = getDisplayName(child.type);

          if (validTypeNames.indexOf(childName) < 0) {
            return new Error("Expected one of ".concat(validTypeNames.join(', '), " in ").concat(componentName, " but found '").concat(childName, "'"));
          }
        } else if (child) {
          return new Error("Expected one of ".concat(validTypeNames.join(', '), " in ").concat(componentName, " but found an element with unknown type: ").concat(child));
        }
      }
    }

    validator.isRequired = makeRequirable(validator);
    return validator;
  },

  /**
   * Ensures that there is exactly one of each specified child
   *
   * ```js
   *  import { Children } from '@instructure/ui-prop-types'
   *
   *  class Example extends Component {
   *    static propTypes = {
   *      children: Children.oneOfEach([Foo, Bar, Baz])
   *    }
   *
   *    render () {
   *      return <div>{this.props.children}</div>
  *    }
  *  }
  * ```
  *
  * This will enforce the following:
  *
  * ```jsx
  *  <Example>
  *    <Foo />
  *    <Bar />
  *    <Baz />
  *  </Example>
  * ```
  * An error will be thrown
  *  - If any of the children are not provided (ex. Foo, Bar, but missing Baz)
  *  - If multiple children of the same type are provided (ex. Foo, Foo, Bar, and Baz)
  *
  * @param {Array} validTypes - Array of child types
  * @returns {Error} if validation failed
  */
  oneOfEach: function oneOfEach(validTypes) {
    return function (props, propName, componentName) {
      var children = React.Children.toArray(props[propName]);
      var instanceCount = {};
      var validTypeNames = validTypes.map(function (type) {
        var typeName = getDisplayName(type);
        instanceCount[typeName] = 0;
        return typeName;
      });

      for (var i = 0; i < children.length; i++) {
        var child = children[i];

        if (child && child.type) {
          var childName = getDisplayName(child.type);

          if (validTypeNames.indexOf(childName) < 0) {
            return new Error("Expected one of ".concat(validTypeNames.join(', '), " in ").concat(componentName, " but found '").concat(childName, "'"));
          }

          instanceCount[childName] = (instanceCount[childName] || 0) + 1;
        } else if (child) {
          return new Error("Expected one of ".concat(validTypeNames.join(', '), " in ").concat(componentName, " but found an element of unknown type: ").concat(child));
        }
      }

      var errors = [];
      Object.keys(instanceCount).forEach(function (childName) {
        if (instanceCount[childName] > 1) {
          errors.push("".concat(instanceCount[childName], " children of type ").concat(childName));
        }

        if (instanceCount[childName] === 0) {
          errors.push("0 children of type ".concat(childName));
        }
      });

      if (errors.length > 0) {
        return new Error("Expected exactly one of each ".concat(validTypeNames.join(', '), " in ").concat(componentName, " but found:\n  ").concat(errors.join('\n')));
      }
    };
  },

  /**
   * Validate the type and order of children for a component.
   *
   * ```js
   *  import { Children } from '@instructure/ui-prop-types'
   *
   *  class Example extends Component {
   *    static propTypes = {
   *      children: Children.enforceOrder([Foo, Bar, Baz])
   *    }
   *
   *    render () {
   *      return <div>{this.props.children}</div>
  *    }
  *  }
  * ```
  *
  * This will enforce the following:
  *
  * ```jsx
  *  <Example>
  *    <Foo />
  *    <Bar />
  *    <Baz />
  *  </Example>
  * ```
  *
  * This validator will also allow various permutations of the order.
  *
  * ```js
  *  import { Children } from '@instructure/ui-prop-types'
  *
  *  class Example extends Component {
  *    static propTypes = {
  *      children: Children.enforceOrder(
  *        [Foo, Bar, Baz],
  *        [Foo, Bar],
  *        [Bar, Baz],
  *      )
  *    }
  *
  *    render () {
  *      return <div>{this.props.children}</div>
  *    }
  *  }
  * ```
  *
  * This will enforce one of the following:
  *
  * ```jsx
  *  <Example>
  *    <Foo />
  *    <Bar />
  *    <Baz />
  *  </Example>
  * ```
  *
  *  OR
  *
  * ```jsx
  *  <Example>
  *    <Foo />
  *    <Bar />
  *  </Example>
  * ```
  *
  *  OR
  *
  * ```jsx
  *  <Example>
  *    <Bar />
  *    <Baz />
  *  </Example>
  * ```
  *
  * @param {...Array} validTypeGroups One or more Arrays of valid types
  * @returns {Error} if validation failed
  */
  enforceOrder: function enforceOrder() {
    for (var _len = arguments.length, validTypeGroups = new Array(_len), _key = 0; _key < _len; _key++) {
      validTypeGroups[_key] = arguments[_key];
    }

    function validateTypes(childNames, typeNames) {
      for (var i = 0; i < childNames.length; i++) {
        if (childNames[i] !== typeNames[i]) {
          return false;
        }
      }

      return true;
    }

    function formatGroupTypes(componentName, typeGroups) {
      return typeGroups.map(function (types) {
        return formatTypes(componentName, types);
      }).join('\n\n');
    }

    function formatTypes(componentName, types) {
      var children = types.map(function (type) {
        if (type) {
          return getDisplayName(type);
        } else {
          return '??';
        }
      }).map(function (name) {
        return "  <".concat(name, " />");
      }).join('\n');
      return "<".concat(componentName, ">\n").concat(children, "\n</").concat(componentName, ">");
    }

    function validator(props, propName, componentName) {
      var childNames = React.Children.toArray(props[propName]).map(function (child) {
        if (child && child.type) {
          return getDisplayName(child.type);
        } else if (child) {
          return null;
        }
      }); // Validate each group, if any of them are valid we're done

      for (var i = 0; i < validTypeGroups.length; i++) {
        var validTypeNames = validTypeGroups[i].map(function (type) {
          if (type) {
            return getDisplayName(type);
          } else {
            return '??';
          }
        });

        if (validateTypes(childNames, validTypeNames)) {
          return;
        }
      } // If we make it through the loop then children are not valid


      return new Error("Expected children of ".concat(componentName, " in one of the following formats:\n  ").concat(formatGroupTypes(componentName, validTypeGroups), "\n\n\n  Instead of:\n  ").concat(formatTypes(componentName, childNames)));
    }

    validator.isRequired = makeRequirable(validator);
    return validator;
  }
}; // TODO: Remove when we further break up ui-utils and bringing this in no longer creates
// a circular dep

var getDisplayName = function getDisplayName(Component) {
  return typeof Component === 'string' ? Component : Component.displayName || Component.name;
};

export default Children;
export {
/**
 * ---
 * category: utilities/PropTypes
 * ---
 * @module Children
 */
Children };