@carbon/react 1.29.1 → 1.30.0

package/lib/components/UIShell/SideNav.js

@@ -16,6 +16,8 @@ var PropTypes = require('prop-types');
 var AriaPropTypes = require('../../prop-types/AriaPropTypes.js');
 var _utils = require('./_utils.js');
 var usePrefix = require('../../internal/usePrefix.js');
+var useMergedRefs = require('../../internal/useMergedRefs.js');
+var useEvent = require('../../internal/useEvent.js');
 var match = require('../../internal/keyboard/match.js');
 var keys = require('../../internal/keyboard/keys.js');
 
@@ -25,8 +27,8 @@ var React__default = /*#__PURE__*/_interopDefaultLegacy(React);
 var cx__default = /*#__PURE__*/_interopDefaultLegacy(cx);
 var PropTypes__default = /*#__PURE__*/_interopDefaultLegacy(PropTypes);
 
+// TO-DO: comment back in when footer is added for rails
 // import SideNavFooter from './SideNavFooter';
-
 function SideNavRenderFunction(_ref, ref) {
   let {
     expanded: expandedProp,
@@ -39,12 +41,14 @@ function SideNavRenderFunction(_ref, ref) {
     className: customClassName,
     // TO-DO: comment back in when footer is added for rails
     // translateById: t = (id) => translations[id],
+    href,
     isFixedNav = false,
     isRail,
     isPersistent = true,
     addFocusListeners = true,
     addMouseListeners = true,
     onOverlayClick,
+    onSideNavBlur,
     ...other
   } = _ref;
   const prefix = usePrefix.usePrefix();
@@ -54,27 +58,26 @@ function SideNavRenderFunction(_ref, ref) {
   const [expandedState, setExpandedState] = React.useState(defaultExpanded);
   const [expandedViaHoverState, setExpandedViaHoverState] = React.useState(defaultExpanded);
   const expanded = controlled ? expandedProp : expandedState;
-
+  const sideNavRef = React.useRef(null);
+  const navRef = useMergedRefs.useMergedRefs([sideNavRef, ref]);
   const handleToggle = function (event) {
     let value = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : !expanded;
-
     if (!controlled) {
       setExpandedState(value);
     }
-
     if (onToggle) {
       onToggle(event, value);
     }
-
     if (controlled || isRail) {
       setExpandedViaHoverState(value);
     }
   };
-
   const accessibilityLabel = {
     'aria-label': ariaLabel,
     'aria-labelledby': ariaLabelledBy
-  }; // TO-DO: comment back in when footer is added for rails
+  };
+
+  // TO-DO: comment back in when footer is added for rails
   // const assistiveText = expanded
   //   ? t('carbon.sidenav.state.open')
   //   : t('carbon.sidenav.state.closed');
@@ -91,56 +94,61 @@ function SideNavRenderFunction(_ref, ref) {
     [`${prefix}--side-nav__overlay`]: true,
     [`${prefix}--side-nav__overlay-active`]: expanded || expandedViaHoverState
   });
-  let childrenToRender = children; // if a rail, pass the expansion state as a prop, so children can update themselves to match
+  let childrenToRender = children;
 
+  // if a rail, pass the expansion state as a prop, so children can update themselves to match
   if (isRail) {
     childrenToRender = React__default["default"].Children.map(children, child => {
       // if we are controlled, check for if we have hovered over or the expanded state, else just use the expanded state (uncontrolled)
       const currentExpansionState = controlled ? expandedViaHoverState || expanded : expanded;
-
       if ( /*#__PURE__*/React.isValidElement(child)) {
-        var _childJsxElement$type, _childJsxElement$type2;
-
-        const childJsxElement = child; // avoid spreading `isSideNavExpanded` to non-Carbon UI Shell children
-
-        return /*#__PURE__*/React__default["default"].cloneElement(childJsxElement, { ...(_utils.CARBON_SIDENAV_ITEMS.includes(((_childJsxElement$type = childJsxElement.type) === null || _childJsxElement$type === void 0 ? void 0 : _childJsxElement$type.displayName) ?? ((_childJsxElement$type2 = childJsxElement.type) === null || _childJsxElement$type2 === void 0 ? void 0 : _childJsxElement$type2.name)) ? {
+        const childJsxElement = child;
+        // avoid spreading `isSideNavExpanded` to non-Carbon UI Shell children
+        return /*#__PURE__*/React__default["default"].cloneElement(childJsxElement, {
+          ...(_utils.CARBON_SIDENAV_ITEMS.includes(childJsxElement.type?.displayName ?? childJsxElement.type?.name) ? {
             isSideNavExpanded: currentExpansionState
           } : {})
         });
       }
-
       return child;
     });
   }
-
   const eventHandlers = {};
-
   if (addFocusListeners) {
     eventHandlers.onFocus = event => {
       if (!event.currentTarget.contains(event.relatedTarget)) {
         handleToggle(event, true);
       }
     };
-
     eventHandlers.onBlur = event => {
       if (!event.currentTarget.contains(event.relatedTarget)) {
         handleToggle(event, false);
       }
+      if (!event.currentTarget.contains(event.relatedTarget) && expanded) {
+        if (onSideNavBlur) {
+          onSideNavBlur();
+        }
+      }
     };
-
     eventHandlers.onKeyDown = event => {
       if (match.match(event, keys.Escape)) {
         handleToggle(event, false);
+        if (href) {
+          window.location.href = href;
+        }
       }
     };
   }
-
   if (addMouseListeners && isRail) {
     eventHandlers.onMouseEnter = () => handleToggle(true, true);
-
     eventHandlers.onMouseLeave = () => handleToggle(false, false);
   }
-
+  useEvent.useWindowEvent('keydown', event => {
+    const focusedElement = document.activeElement;
+    if (match.match(event, keys.Tab) && expanded && !isFixedNav && sideNavRef.current && focusedElement?.classList.contains(`${prefix}--header__menu-toggle`) && !focusedElement.closest('nav')) {
+      sideNavRef.current.focus();
+    }
+  });
   return /*#__PURE__*/React__default["default"].createElement(React__default["default"].Fragment, null, isFixedNav ? null :
   /*#__PURE__*/
   // eslint-disable-next-line jsx-a11y/click-events-have-key-events, jsx-a11y/no-static-element-interactions
@@ -148,11 +156,11 @@ function SideNavRenderFunction(_ref, ref) {
     className: overlayClassName,
     onClick: onOverlayClick
   }), /*#__PURE__*/React__default["default"].createElement("nav", _rollupPluginBabelHelpers["extends"]({
-    ref: ref,
+    tabIndex: -1,
+    ref: navRef,
     className: `${prefix}--side-nav__navigation ${className}`
   }, accessibilityLabel, eventHandlers, other), childrenToRender));
 }
-
 const SideNav = /*#__PURE__*/React__default["default"].forwardRef(SideNavRenderFunction);
 SideNav.displayName = 'SideNav';
 SideNav.propTypes = {
@@ -160,60 +168,59 @@ SideNav.propTypes = {
    * Required props for accessibility label on the underlying menu
    */
   ...AriaPropTypes.AriaLabelPropType,
-
   /**
    * Specify whether focus and blur listeners are added. They are by default.
    */
   addFocusListeners: PropTypes__default["default"].bool,
-
   /**
    * Specify whether mouse entry/exit listeners are added. They are by default.
    */
   addMouseListeners: PropTypes__default["default"].bool,
-
   /**
    * Optionally provide a custom class to apply to the underlying `<li>` node
    */
   className: PropTypes__default["default"].string,
-
   /**
    * If `true`, the SideNav will be open on initial render.
    */
   defaultExpanded: PropTypes__default["default"].bool,
-
   /**
    * If `true`, the SideNav will be expanded, otherwise it will be collapsed.
    * Using this prop causes SideNav to become a controled component.
    */
   expanded: PropTypes__default["default"].bool,
-
+  /**
+   * Provide the `href` to the id of the element on your package that is the
+   * main content.
+   */
+  href: PropTypes__default["default"].string,
   /**
    * Optionally provide a custom class to apply to the underlying `<li>` node
    */
   isChildOfHeader: PropTypes__default["default"].bool,
-
   /**
    * Specify if sideNav is standalone
    */
   isFixedNav: PropTypes__default["default"].bool,
-
   /**
    * Specify if the sideNav will be persistent above the lg breakpoint
    */
   isPersistent: PropTypes__default["default"].bool,
-
   /**
    * Optional prop to display the side nav rail.
    */
   isRail: PropTypes__default["default"].bool,
-
   /**
    * An optional listener that is called when the SideNav overlay is clicked
    *
    * @param {object} event
    */
   onOverlayClick: PropTypes__default["default"].func,
+  /**
+   * An optional listener that is called a callback to collapse the SideNav
+   */
 
+  onSideNavBlur: PropTypes__default["default"].func,
   /**
    * An optional listener that is called when an event that would cause
    * toggling the SideNav occurs.
@@ -222,6 +229,7 @@ SideNav.propTypes = {
    * @param {boolean} value
    */
   onToggle: PropTypes__default["default"].func
+
   /**
    * Provide a custom function for translating all message ids within this
    * component. This function will take in two arguments: the mesasge Id and the
@@ -229,8 +237,8 @@ SideNav.propTypes = {
    * the label you want displayed or read by screen readers.
    */
   // translateById: PropTypes.func,
-
 };
+
 var SideNav$1 = SideNav;
 
 exports["default"] = SideNav$1;

package/lib/components/UIShell/SideNavDetails.js

@@ -37,19 +37,16 @@ const SideNavDetails = _ref => {
     title: title
   }, title), children);
 };
-
 SideNavDetails.propTypes = {
   /**
    * Provide optional children to render in `SideNavDetails`. Useful for
    * rendering the `SideNavSwitcher` component.
    */
   children: PropTypes__default["default"].node,
-
   /**
    * Optionally provide a custom class to apply to the underlying `<li>` node
    */
   className: PropTypes__default["default"].string,
-
   /**
    * Provide the text that will be rendered as the title in the component
    */

package/lib/components/UIShell/SideNavDivider.js

@@ -31,7 +31,6 @@ function SideNavDivider(_ref) {
     className: classNames
   });
 }
-
 SideNavDivider.propTypes = {
   /**
    * Provide an optional class to be applied to the containing node

package/lib/components/UIShell/SideNavFooter.js

@@ -22,12 +22,12 @@ var React__default = /*#__PURE__*/_interopDefaultLegacy(React);
 var PropTypes__default = /*#__PURE__*/_interopDefaultLegacy(PropTypes);
 
 var _Close, _ChevronRight;
+
 /**
  * SideNavFooter is used for rendering the button at the bottom of the side
  * navigation that is a part of the UI Shell. It is responsible for handling the
  * user interaction to expand or collapse the side navigation.
  */
-
 function SideNavFooter(_ref) {
   let {
     assistiveText,
@@ -54,7 +54,6 @@ function SideNavFooter(_ref) {
     className: `${prefix}--assistive-text`
   }, assistiveText)));
 }
-
 SideNavFooter.displayName = 'SideNavFooter';
 SideNavFooter.propTypes = {
   /**
@@ -63,12 +62,10 @@ SideNavFooter.propTypes = {
    */
   assistiveText: PropTypes__default["default"].string.isRequired,
   className: PropTypes__default["default"].string,
-
   /**
    * Specify whether the side navigation is expanded or collapsed
    */
   expanded: PropTypes__default["default"].bool.isRequired,
-
   /**
    * Provide a function that is called when the toggle button is interacted
    * with. Useful for controlling the expansion state of the side navigation.

package/lib/components/UIShell/SideNavHeader.js

@@ -33,25 +33,21 @@ const SideNavHeader = _ref => {
     className: className
   }, /*#__PURE__*/React__default["default"].createElement(SideNavIcon["default"], null, /*#__PURE__*/React__default["default"].createElement(IconElement, null)), children);
 };
-
 SideNavHeader.displayName = 'SideNavHeader';
 SideNavHeader.propTypes = {
   /**
    * The child nodes to be rendered
    */
   children: PropTypes__default["default"].node,
-
   /**
    * Provide an optional class to be applied to the containing node
    */
   className: PropTypes__default["default"].string,
-
   /**
    * Property to indicate if the side nav container is open (or not). Use to
    * keep local state and styling in step with the SideNav expansion state.
    */
   isSideNavExpanded: PropTypes__default["default"].bool,
-
   /**
    * Provide an icon to render in the header of the side navigation. Should be
    * a React class.

package/lib/components/UIShell/SideNavIcon.js

@@ -36,19 +36,16 @@ function SideNavIcon(_ref) {
     className: className
   }, children);
 }
-
 SideNavIcon.propTypes = {
   /**
    * Provide a single icon as the child to `SideNavIcon` to render in the
    * container
    */
   children: PropTypes__default["default"].node.isRequired,
-
   /**
    * Provide an optional class to be applied to the containing node
    */
   className: PropTypes__default["default"].string,
-
   /**
    * Specify whether the icon should be placed in a smaller bounding box
    */

package/lib/components/UIShell/SideNavItem.js

@@ -36,19 +36,16 @@ function SideNavItem(_ref) {
     className: className
   }, children);
 }
-
 SideNavItem.propTypes = {
   /**
    * Provide a single icon as the child to `SideNavItem` to render in the
    * container
    */
   children: PropTypes__default["default"].node.isRequired,
-
   /**
    * Provide an optional class to be applied to the containing node
    */
   className: PropTypes__default["default"].string,
-
   /**
    * Specify if this is a large variation of the SideNavItem
    */

package/lib/components/UIShell/SideNavItems.js

@@ -31,10 +31,9 @@ const SideNavItems = _ref => {
   const className = cx__default["default"]([`${prefix}--side-nav__items`], customClassName);
   const childrenWithExpandedState = React__default["default"].Children.map(children, child => {
     if ( /*#__PURE__*/React__default["default"].isValidElement(child)) {
-      var _child$type;
-
       // avoid spreading `isSideNavExpanded` to non-Carbon UI Shell children
-      return /*#__PURE__*/React__default["default"].cloneElement(child, { ...(_utils.CARBON_SIDENAV_ITEMS.includes((_child$type = child.type) === null || _child$type === void 0 ? void 0 : _child$type.displayName) ? {
+      return /*#__PURE__*/React__default["default"].cloneElement(child, {
+        ...(_utils.CARBON_SIDENAV_ITEMS.includes(child.type?.displayName) ? {
           isSideNavExpanded
         } : {})
       });
@@ -44,7 +43,6 @@ const SideNavItems = _ref => {
     className: className
   }, childrenWithExpandedState);
 };
-
 SideNavItems.displayName = 'SideNavItems';
 SideNavItems.propTypes = {
   /**
@@ -52,12 +50,10 @@ SideNavItems.propTypes = {
    * container
    */
   children: PropTypes__default["default"].node.isRequired,
-
   /**
    * Provide an optional class to be applied to the containing node
    */
   className: PropTypes__default["default"].string,
-
   /**
    * Property to indicate if the side nav container is open (or not). Use to
    * keep local state and styling in step with the SideNav expansion state.

package/lib/components/UIShell/SideNavLink.js

@@ -50,33 +50,29 @@ const SideNavLink = /*#__PURE__*/React__default["default"].forwardRef(function S
   }, /*#__PURE__*/React__default["default"].createElement(IconElement, null)), /*#__PURE__*/React__default["default"].createElement(SideNavLinkText["default"], null, children)));
 });
 SideNavLink.displayName = 'SideNavLink';
-SideNavLink.propTypes = { ...Link.LinkPropTypes,
-
+SideNavLink.propTypes = {
+  ...Link.LinkPropTypes,
   /**
    * Specify the text content for the link
    */
   children: PropTypes__default["default"].node.isRequired,
-
   /**
    * Provide an optional class to be applied to the containing node
    */
   className: PropTypes__default["default"].string,
-
   /**
    * Specify whether the link is the current page
    */
   isActive: PropTypes__default["default"].bool,
-
   /**
    * Specify if this is a large variation of the SideNavLink
    */
   large: PropTypes__default["default"].bool,
-
   /**
    * Provide an icon to render in the side navigation link. Should be a React class.
    */
   renderIcon: PropTypes__default["default"].oneOfType([PropTypes__default["default"].func, PropTypes__default["default"].object])
-}; // eslint-disable-next-line react/display-name
+};
 var SideNavLink$1 = SideNavLink;
 
 exports["default"] = SideNavLink$1;

package/lib/components/UIShell/SideNavLinkText.js

@@ -33,13 +33,11 @@ function SideNavLinkText(_ref) {
     className: className
   }), children);
 }
-
 SideNavLinkText.propTypes = {
   /**
    * Provide the content for the link text
    */
   children: PropTypes__default["default"].node.isRequired,
-
   /**
    * Provide an optional class to be applied to the containing node
    */

package/lib/components/UIShell/SideNavMenu.js

@@ -46,7 +46,6 @@ const SideNavMenu = /*#__PURE__*/React__default["default"].forwardRef(function S
     [`${prefix}--side-nav__item--large`]: large,
     [customClassName]: !!customClassName
   });
-
   if (isSideNavExpanded === false && isExpanded === true) {
     setIsExpanded(false);
     setPrevExpanded(true);
@@ -54,7 +53,6 @@ const SideNavMenu = /*#__PURE__*/React__default["default"].forwardRef(function S
     setIsExpanded(true);
     setPrevExpanded(false);
   }
-
   return (
     /*#__PURE__*/
     // eslint-disable-next-line jsx-a11y/no-noninteractive-element-interactions
@@ -92,47 +90,39 @@ SideNavMenu.propTypes = {
    * Provide <SideNavMenuItem>'s inside of the `SideNavMenu`
    */
   children: PropTypes__default["default"].node,
-
   /**
    * Provide an optional class to be applied to the containing node
    */
   className: PropTypes__default["default"].string,
-
   /**
    * Specify whether the menu should default to expanded. By default, it will
    * be closed.
    */
   defaultExpanded: PropTypes__default["default"].bool,
-
   /**
    * Specify whether the `SideNavMenu` is "active". `SideNavMenu` should be
    * considered active if one of its menu items are a link for the current
    * page.
    */
   isActive: PropTypes__default["default"].bool,
-
   /**
    * Property to indicate if the side nav container is open (or not). Use to
    * keep local state and styling in step with the SideNav expansion state.
    */
   isSideNavExpanded: PropTypes__default["default"].bool,
-
   /**
    * Specify if this is a large variation of the SideNavMenu
    */
   large: PropTypes__default["default"].bool,
-
   /**
    * Pass in a custom icon to render next to the `SideNavMenu` title
    */
   renderIcon: PropTypes__default["default"].oneOfType([PropTypes__default["default"].func, PropTypes__default["default"].object]),
-
   /**
    * Provide the text for the overall menu name
    */
   title: PropTypes__default["default"].string.isRequired
 };
-
 function hasActiveChild(children) {
   // if we have children, either a single or multiple, find if it is active
   if (Array.isArray(children)) {
@@ -140,28 +130,22 @@ function hasActiveChild(children) {
       if (!child.props) {
         return false;
       }
-
       if (child.props.isActive === true) {
         return true;
       }
-
       if (child.props['aria-current']) {
         return true;
       }
-
       return false;
     });
   }
-
   if (children.props) {
     if (children.props.isActive === true || children.props['aria-current']) {
       return true;
     }
   }
-
   return false;
 }
-
 var SideNavMenu$1 = SideNavMenu;
 
 exports.SideNavMenu = SideNavMenu;

package/lib/components/UIShell/SideNavMenuItem.js

@@ -49,12 +49,10 @@ SideNavMenuItem.propTypes = {
    * Specify the children to be rendered inside of the `SideNavMenuItem`
    */
   children: PropTypes__default["default"].node,
-
   /**
    * Provide an optional class to be applied to the containing node
    */
   className: PropTypes__default["default"].string,
-
   /**
    * Optionally specify whether the link is "active". An active link is one that
    * has an href that is the same as the current page. Can also pass in

package/lib/components/UIShell/SideNavSwitcher.js

@@ -32,8 +32,8 @@ const SideNavSwitcher = /*#__PURE__*/React__default["default"].forwardRef(functi
     onChange,
     options
   } = props;
-  const className = cx__default["default"](`${prefix}--side-nav__switcher`, customClassName); // Note for usage around `onBlur`: https://github.com/evcohen/eslint-plugin-jsx-a11y/blob/master/docs/rules/no-onchange.md
-
+  const className = cx__default["default"](`${prefix}--side-nav__switcher`, customClassName);
+  // Note for usage around `onBlur`: https://github.com/evcohen/eslint-plugin-jsx-a11y/blob/master/docs/rules/no-onchange.md
   return /*#__PURE__*/React__default["default"].createElement("div", {
     className: className
   }, /*#__PURE__*/React__default["default"].createElement("label", {
@@ -67,19 +67,16 @@ SideNavSwitcher.propTypes = {
    * Provide an optional class to be applied to the containing node
    */
   className: PropTypes__default["default"].string,
-
   /**
    * Provide the label for the switcher. This will be the first visible option
    * when someone views this control
    */
   labelText: PropTypes__default["default"].string.isRequired,
-
   /**
    * Provide a callback function that is called whenever the switcher value is
    * updated
    */
   onChange: PropTypes__default["default"].func,
-
   /**
    * Provide an array of options to be rendered in the switcher as an
    * `<option>`. The text value will be what is displayed to the user and is set

package/lib/components/UIShell/SkipToContent.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Copyright IBM Corp. 2016, 2023
+ *
+ * This source code is licensed under the Apache-2.0 license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+import { ComponentProps } from 'react';
+import PropTypes from 'prop-types';
+type SkipToContentProps = Omit<ComponentProps<'a'>, 'children'> & {
+    children?: string | undefined;
+};
+declare function SkipToContent({ children, className: customClassName, href, tabIndex, ...rest }: SkipToContentProps): JSX.Element;
+declare namespace SkipToContent {
+    var propTypes: {
+        /**
+         * A ReactNode to display in the SkipToContent `a` tag.
+         * `'Skip to main content'` by default.
+         */
+        children: PropTypes.Requireable<string>;
+        className: PropTypes.Requireable<string>;
+        /**
+         * Provide the `href` to the id of the element on your package that is the
+         * main content. `#main-content` by default.
+         */
+        href: PropTypes.Requireable<string>;
+        /**
+         * Optionally override the default tabindex of 0
+         */
+        tabIndex: PropTypes.Requireable<string>;
+    };
+}
+export default SkipToContent;

package/lib/components/UIShell/SkipToContent.js

@@ -23,10 +23,10 @@ var PropTypes__default = /*#__PURE__*/_interopDefaultLegacy(PropTypes);
 
 function SkipToContent(_ref) {
   let {
-    children,
+    children = 'Skip to main content',
     className: customClassName,
-    href,
-    tabIndex,
+    href = '#main-content',
+    tabIndex = 0,
     ...rest
   } = _ref;
   const prefix = usePrefix.usePrefix();
@@ -37,29 +37,22 @@ function SkipToContent(_ref) {
     tabIndex: tabIndex
   }), children);
 }
-
 SkipToContent.propTypes = {
   /**
-   * Provide text to display in the SkipToContent `a` tag
+   * A ReactNode to display in the SkipToContent `a` tag.
+   * `'Skip to main content'` by default.
    */
-  children: PropTypes__default["default"].string.isRequired,
+  children: PropTypes__default["default"].string,
   className: PropTypes__default["default"].string,
-
   /**
    * Provide the `href` to the id of the element on your package that is the
-   * main content.
+   * main content. `#main-content` by default.
    */
-  href: PropTypes__default["default"].string.isRequired,
-
+  href: PropTypes__default["default"].string,
   /**
    * Optionally override the default tabindex of 0
    */
   tabIndex: PropTypes__default["default"].string
 };
-SkipToContent.defaultProps = {
-  children: 'Skip to main content',
-  href: '#main-content',
-  tabIndex: '0'
-};
 
 exports["default"] = SkipToContent;