@carbon/ibm-products/lib/global/js/utils/Wrap.js

Carbon for IBM Products

/**
 * Copyright IBM Corp. 2020, 2025
 *
 * This source code is licensed under the Apache-2.0 license found in the
 * LICENSE file in the root directory of this source tree.
 */

'use strict';

var _rollupPluginBabelHelpers = require('../../../_virtual/_rollupPluginBabelHelpers.js');
var React = require('react');
var index = require('../../../_virtual/index.js');

// Examine a flat array of children to decide whether it is effectively empty.
// If there are no children, or all the children are falsy, or all the non-falsy
// children are themselves Wrap components that are empty, then return true.
const isEmpty = children => {
  let result = true;
  React.Children.forEach(children, child => {
    if (child) {
      result &&= child?.type?.displayName === 'Wrap' && isEmpty(child?.props?.children);
    }
  });
  return result;
};
/**
 * A simple conditional wrapper that encloses its children in a <div> (or other
 * element if specified), passing any supplied attributes to the <div> (or other
 * element). The component renders nothing at all if there are no children or
 * the children are empty/falsy, or if all the non-falsy children are themselves
 * Wrap components that do not wish to render. This behavior can be overridden
 * by setting neverRender or alwaysRender to true. Note that if a ref is passed,
 * the ref.current will be set to the wrapper element if it renders, and will
 * remain undefined if it does not render.
 */
const Wrap = /*#__PURE__*/React.forwardRef((_ref, ref) => {
  let {
    // The component props, in alphabetical order (for consistency).

    alwaysRender,
    children,
    element: Wrapper = 'div',
    neverRender,
    className,
    title,
    // Collect any other property values passed in.
    ...rest
  } = _ref;
  return (neverRender || isEmpty(children)) && !alwaysRender ? null : /*#__PURE__*/React.createElement(Wrapper, _rollupPluginBabelHelpers.extends({
    className: className
  }, rest, {
    ref: ref,
    title: title
  }), children);
});
Wrap.displayName = 'Wrap';
Wrap.propTypes = {
  /**
   * Specify whether the wrapper element should render even if there are no
   * children or the children are themselves empty wrappers. Useful if there
   * are some conditions in which the wrapper element is still required. Note
   * that this prop takes precedence over neverRender if both are set to true.
   */
  alwaysRender: index.default.bool,
  /**
   * The content of the wrapper element. If no children are supplied, or the
   * resulting value(s) are falsy, or if all the non-falsy children are Wrap
   * components that decide not to render, nothing will be rendered in the DOM.
   */
  children: index.default.node,
  className: index.default.string,
  /**
   * The element name or component to use as a wrapper for the content.
   */
  element: index.default.elementType,
  /**
   * Specify whether nothing should be rendered even if there are children
   * in the content. Useful if there are some circumstances in which the
   * component should not render at all. Note that if alwaysRender is also
   * set to true then it will take precedence and the wrapper element and
   * content will be rendered.
   */
  neverRender: index.default.bool,
  /**
   * The title attribute the content.
   */
  title: index.default.string
};

exports.Wrap = Wrap;