@carbon/react 1.29.1 → 1.30.0

package/es/components/UIShell/SideNav.js

@@ -12,11 +12,13 @@ import PropTypes from 'prop-types';
 import { AriaLabelPropType } from '../../prop-types/AriaPropTypes.js';
 import { CARBON_SIDENAV_ITEMS } from './_utils.js';
 import { usePrefix } from '../../internal/usePrefix.js';
+import { useMergedRefs } from '../../internal/useMergedRefs.js';
+import { useWindowEvent } from '../../internal/useEvent.js';
 import { match } from '../../internal/keyboard/match.js';
-import { Escape } from '../../internal/keyboard/keys.js';
+import { Tab, Escape } from '../../internal/keyboard/keys.js';
 
+// TO-DO: comment back in when footer is added for rails
 // import SideNavFooter from './SideNavFooter';
-
 function SideNavRenderFunction(_ref, ref) {
   let {
     expanded: expandedProp,
@@ -29,12 +31,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();
@@ -44,27 +48,26 @@ function SideNavRenderFunction(_ref, ref) {
   const [expandedState, setExpandedState] = useState(defaultExpanded);
   const [expandedViaHoverState, setExpandedViaHoverState] = useState(defaultExpanded);
   const expanded = controlled ? expandedProp : expandedState;
-
+  const sideNavRef = useRef(null);
+  const navRef = 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');
@@ -81,56 +84,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.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__*/isValidElement(child)) {
-        var _childJsxElement$type, _childJsxElement$type2;
-
-        const childJsxElement = child; // avoid spreading `isSideNavExpanded` to non-Carbon UI Shell children
-
-        return /*#__PURE__*/React__default.cloneElement(childJsxElement, { ...(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.cloneElement(childJsxElement, {
+          ...(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(event, Escape)) {
         handleToggle(event, false);
+        if (href) {
+          window.location.href = href;
+        }
       }
     };
   }
-
   if (addMouseListeners && isRail) {
     eventHandlers.onMouseEnter = () => handleToggle(true, true);
-
     eventHandlers.onMouseLeave = () => handleToggle(false, false);
   }
-
+  useWindowEvent('keydown', event => {
+    const focusedElement = document.activeElement;
+    if (match(event, Tab) && expanded && !isFixedNav && sideNavRef.current && focusedElement?.classList.contains(`${prefix}--header__menu-toggle`) && !focusedElement.closest('nav')) {
+      sideNavRef.current.focus();
+    }
+  });
   return /*#__PURE__*/React__default.createElement(React__default.Fragment, null, isFixedNav ? null :
   /*#__PURE__*/
   // eslint-disable-next-line jsx-a11y/click-events-have-key-events, jsx-a11y/no-static-element-interactions
@@ -138,11 +146,11 @@ function SideNavRenderFunction(_ref, ref) {
     className: overlayClassName,
     onClick: onOverlayClick
   }), /*#__PURE__*/React__default.createElement("nav", _extends({
-    ref: ref,
+    tabIndex: -1,
+    ref: navRef,
     className: `${prefix}--side-nav__navigation ${className}`
   }, accessibilityLabel, eventHandlers, other), childrenToRender));
 }
-
 const SideNav = /*#__PURE__*/React__default.forwardRef(SideNavRenderFunction);
 SideNav.displayName = 'SideNav';
 SideNav.propTypes = {
@@ -150,60 +158,59 @@ SideNav.propTypes = {
    * Required props for accessibility label on the underlying menu
    */
   ...AriaLabelPropType,
-
   /**
    * Specify whether focus and blur listeners are added. They are by default.
    */
   addFocusListeners: PropTypes.bool,
-
   /**
    * Specify whether mouse entry/exit listeners are added. They are by default.
    */
   addMouseListeners: PropTypes.bool,
-
   /**
    * Optionally provide a custom class to apply to the underlying `<li>` node
    */
   className: PropTypes.string,
-
   /**
    * If `true`, the SideNav will be open on initial render.
    */
   defaultExpanded: PropTypes.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.bool,
-
+  /**
+   * Provide the `href` to the id of the element on your package that is the
+   * main content.
+   */
+  href: PropTypes.string,
   /**
    * Optionally provide a custom class to apply to the underlying `<li>` node
    */
   isChildOfHeader: PropTypes.bool,
-
   /**
    * Specify if sideNav is standalone
    */
   isFixedNav: PropTypes.bool,
-
   /**
    * Specify if the sideNav will be persistent above the lg breakpoint
    */
   isPersistent: PropTypes.bool,
-
   /**
    * Optional prop to display the side nav rail.
    */
   isRail: PropTypes.bool,
-
   /**
    * An optional listener that is called when the SideNav overlay is clicked
    *
    * @param {object} event
    */
   onOverlayClick: PropTypes.func,
+  /**
+   * An optional listener that is called a callback to collapse the SideNav
+   */
 
+  onSideNavBlur: PropTypes.func,
   /**
    * An optional listener that is called when an event that would cause
    * toggling the SideNav occurs.
@@ -212,6 +219,7 @@ SideNav.propTypes = {
    * @param {boolean} value
    */
   onToggle: PropTypes.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
@@ -219,8 +227,8 @@ SideNav.propTypes = {
    * the label you want displayed or read by screen readers.
    */
   // translateById: PropTypes.func,
-
 };
+
 var SideNav$1 = SideNav;
 
 export { SideNav$1 as default };

package/es/components/UIShell/SideNavDetails.js

@@ -27,19 +27,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.node,
-
   /**
    * Optionally provide a custom class to apply to the underlying `<li>` node
    */
   className: PropTypes.string,
-
   /**
    * Provide the text that will be rendered as the title in the component
    */

package/es/components/UIShell/SideNavDivider.js

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

package/es/components/UIShell/SideNavFooter.js

@@ -12,12 +12,12 @@ import PropTypes from 'prop-types';
 import { usePrefix } from '../../internal/usePrefix.js';
 
 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,
@@ -44,7 +44,6 @@ function SideNavFooter(_ref) {
     className: `${prefix}--assistive-text`
   }, assistiveText)));
 }
-
 SideNavFooter.displayName = 'SideNavFooter';
 SideNavFooter.propTypes = {
   /**
@@ -53,12 +52,10 @@ SideNavFooter.propTypes = {
    */
   assistiveText: PropTypes.string.isRequired,
   className: PropTypes.string,
-
   /**
    * Specify whether the side navigation is expanded or collapsed
    */
   expanded: PropTypes.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/es/components/UIShell/SideNavHeader.js

@@ -23,25 +23,21 @@ const SideNavHeader = _ref => {
     className: className
   }, /*#__PURE__*/React__default.createElement(SideNavIcon, null, /*#__PURE__*/React__default.createElement(IconElement, null)), children);
 };
-
 SideNavHeader.displayName = 'SideNavHeader';
 SideNavHeader.propTypes = {
   /**
    * The child nodes to be rendered
    */
   children: PropTypes.node,
-
   /**
    * Provide an optional class to be applied to the containing node
    */
   className: PropTypes.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.bool,
-
   /**
    * Provide an icon to render in the header of the side navigation. Should be
    * a React class.

package/es/components/UIShell/SideNavIcon.js

@@ -26,19 +26,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.node.isRequired,
-
   /**
    * Provide an optional class to be applied to the containing node
    */
   className: PropTypes.string,
-
   /**
    * Specify whether the icon should be placed in a smaller bounding box
    */

package/es/components/UIShell/SideNavItem.js

@@ -26,19 +26,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.node.isRequired,
-
   /**
    * Provide an optional class to be applied to the containing node
    */
   className: PropTypes.string,
-
   /**
    * Specify if this is a large variation of the SideNavItem
    */

package/es/components/UIShell/SideNavItems.js

@@ -21,10 +21,9 @@ const SideNavItems = _ref => {
   const className = cx([`${prefix}--side-nav__items`], customClassName);
   const childrenWithExpandedState = React__default.Children.map(children, child => {
     if ( /*#__PURE__*/React__default.isValidElement(child)) {
-      var _child$type;
-
       // avoid spreading `isSideNavExpanded` to non-Carbon UI Shell children
-      return /*#__PURE__*/React__default.cloneElement(child, { ...(CARBON_SIDENAV_ITEMS.includes((_child$type = child.type) === null || _child$type === void 0 ? void 0 : _child$type.displayName) ? {
+      return /*#__PURE__*/React__default.cloneElement(child, {
+        ...(CARBON_SIDENAV_ITEMS.includes(child.type?.displayName) ? {
           isSideNavExpanded
         } : {})
       });
@@ -34,7 +33,6 @@ const SideNavItems = _ref => {
     className: className
   }, childrenWithExpandedState);
 };
-
 SideNavItems.displayName = 'SideNavItems';
 SideNavItems.propTypes = {
   /**
@@ -42,12 +40,10 @@ SideNavItems.propTypes = {
    * container
    */
   children: PropTypes.node.isRequired,
-
   /**
    * Provide an optional class to be applied to the containing node
    */
   className: PropTypes.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/es/components/UIShell/SideNavLink.js

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

package/es/components/UIShell/SideNavLinkText.js

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

package/es/components/UIShell/SideNavMenu.js

@@ -36,7 +36,6 @@ const SideNavMenu = /*#__PURE__*/React__default.forwardRef(function SideNavMenu(
     [`${prefix}--side-nav__item--large`]: large,
     [customClassName]: !!customClassName
   });
-
   if (isSideNavExpanded === false && isExpanded === true) {
     setIsExpanded(false);
     setPrevExpanded(true);
@@ -44,7 +43,6 @@ const SideNavMenu = /*#__PURE__*/React__default.forwardRef(function SideNavMenu(
     setIsExpanded(true);
     setPrevExpanded(false);
   }
-
   return (
     /*#__PURE__*/
     // eslint-disable-next-line jsx-a11y/no-noninteractive-element-interactions
@@ -82,47 +80,39 @@ SideNavMenu.propTypes = {
    * Provide <SideNavMenuItem>'s inside of the `SideNavMenu`
    */
   children: PropTypes.node,
-
   /**
    * Provide an optional class to be applied to the containing node
    */
   className: PropTypes.string,
-
   /**
    * Specify whether the menu should default to expanded. By default, it will
    * be closed.
    */
   defaultExpanded: PropTypes.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.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.bool,
-
   /**
    * Specify if this is a large variation of the SideNavMenu
    */
   large: PropTypes.bool,
-
   /**
    * Pass in a custom icon to render next to the `SideNavMenu` title
    */
   renderIcon: PropTypes.oneOfType([PropTypes.func, PropTypes.object]),
-
   /**
    * Provide the text for the overall menu name
    */
   title: PropTypes.string.isRequired
 };
-
 function hasActiveChild(children) {
   // if we have children, either a single or multiple, find if it is active
   if (Array.isArray(children)) {
@@ -130,28 +120,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;
 
 export { SideNavMenu, SideNavMenu$1 as default };

package/es/components/UIShell/SideNavMenuItem.js

@@ -39,12 +39,10 @@ SideNavMenuItem.propTypes = {
    * Specify the children to be rendered inside of the `SideNavMenuItem`
    */
   children: PropTypes.node,
-
   /**
    * Provide an optional class to be applied to the containing node
    */
   className: PropTypes.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/es/components/UIShell/SideNavSwitcher.js

@@ -22,8 +22,8 @@ const SideNavSwitcher = /*#__PURE__*/React__default.forwardRef(function SideNavS
     onChange,
     options
   } = props;
-  const className = cx(`${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(`${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.createElement("div", {
     className: className
   }, /*#__PURE__*/React__default.createElement("label", {
@@ -57,19 +57,16 @@ SideNavSwitcher.propTypes = {
    * Provide an optional class to be applied to the containing node
    */
   className: PropTypes.string,
-
   /**
    * Provide the label for the switcher. This will be the first visible option
    * when someone views this control
    */
   labelText: PropTypes.string.isRequired,
-
   /**
    * Provide a callback function that is called whenever the switcher value is
    * updated
    */
   onChange: PropTypes.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/es/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/es/components/UIShell/SkipToContent.js

@@ -13,10 +13,10 @@ import { usePrefix } from '../../internal/usePrefix.js';
 
 function SkipToContent(_ref) {
   let {
-    children,
+    children = 'Skip to main content',
     className: customClassName,
-    href,
-    tabIndex,
+    href = '#main-content',
+    tabIndex = 0,
     ...rest
   } = _ref;
   const prefix = usePrefix();
@@ -27,29 +27,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.string.isRequired,
+  children: PropTypes.string,
   className: PropTypes.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.string.isRequired,
-
+  href: PropTypes.string,
   /**
    * Optionally override the default tabindex of 0
    */
   tabIndex: PropTypes.string
 };
-SkipToContent.defaultProps = {
-  children: 'Skip to main content',
-  href: '#main-content',
-  tabIndex: '0'
-};
 
 export { SkipToContent as default };