@carbon-labs/react-ui-shell 0.7.0 → 0.9.0

package/es/components/SideNav.js

@@ -6,14 +6,14 @@
  */
 
 import { extends as _extends } from '../_virtual/_rollupPluginBabelHelpers.js';
-import React, { useRef, isValidElement, createContext } from 'react';
+import React, { createContext, useRef, isValidElement, useEffect } from 'react';
 import cx from '../_virtual/index.js';
 import PropTypes from 'prop-types';
 import { AriaLabelPropType } from '@carbon/react/lib/prop-types/AriaPropTypes';
 import { CARBON_SIDENAV_ITEMS } from './_utils.js';
 import { usePrefix } from '@carbon/react/lib/internal/usePrefix';
 import * as keys from '@carbon/react/lib/internal/keyboard/keys';
-import { match } from '@carbon/react/lib/internal/keyboard/match';
+import { match, matches } from '@carbon/react/lib/internal/keyboard/match';
 import { useMergedRefs } from '@carbon/react/lib/internal/useMergedRefs';
 import { useWindowEvent } from '@carbon/react/lib/internal/useEvent';
 import { useDelayedState } from '@carbon/react/lib/internal/useDelayedState';
@@ -121,6 +121,39 @@ function SideNavRenderFunction(_ref, ref) {
     return child;
   });
   const eventHandlers = {};
+  const treeWalkerRef = useRef(null);
+  useEffect(() => {
+    treeWalkerRef.current = treeWalkerRef.current ?? document.createTreeWalker(sideNavRef?.current, NodeFilter.SHOW_ELEMENT, {
+      acceptNode: function (node) {
+        if (!(node instanceof Element)) {
+          return NodeFilter.FILTER_SKIP;
+        }
+        if (node.classList.contains(`${prefix}--side-nav__divider`)) {
+          return NodeFilter.FILTER_REJECT;
+        }
+        if (node.matches(`li.${prefix}--side-nav__item`) || node.matches(`li.${prefix}--side-nav__menu-item`)) {
+          return NodeFilter.FILTER_ACCEPT;
+        }
+        return NodeFilter.FILTER_SKIP;
+      }
+    });
+    resetNodeTabIndices();
+    const firstElement = sideNavRef?.current?.querySelector('a, button');
+    if (firstElement) {
+      firstElement.tabIndex = 0;
+    }
+  }, [prefix]);
+
+  /**
+   * Returns the parent SideNavMenu, if node is actually inside one.
+   * @param node
+   * @returns parent side nav menu node
+   */
+  function parentSideNavMenu(node) {
+    const parentNode = node.parentElement?.closest(`.${prefix}--side-nav__item`);
+    if (parentNode) return parentNode;
+    return node;
+  }
   if (addFocusListeners) {
     eventHandlers.onFocus = event => {
       if (!event.currentTarget.contains(event.relatedTarget) && isRail) {
@@ -141,7 +174,94 @@ function SideNavRenderFunction(_ref, ref) {
       }
     };
     eventHandlers.onKeyDown = event => {
+      if (!treeWalkerRef.current) return;
+      const treeWalker = treeWalkerRef.current;
+      event.stopPropagation();
+
+      // stops page from scrolling
+      if (matches(event, [keys.ArrowUp, keys.ArrowDown, keys.Home, keys.End,
+      // @ts-ignore - `matches` doesn't like the object syntax without missing properties
+      {
+        code: 'KeyA'
+      }])) {
+        event.preventDefault();
+      }
+      treeWalker.currentNode = event.target.closest(`li`) ?? treeWalker?.currentNode;
+      let nextFocusNode = null;
+      if (match(event, keys.ArrowUp)) {
+        const parentNode = parentSideNavMenu(treeWalker.currentNode);
+        let previousSideNavMenu = parentNode?.previousElementSibling;
+
+        // skip the divider
+        if (previousSideNavMenu?.classList.contains(`${prefix}--side-nav__divider`)) {
+          previousSideNavMenu = previousSideNavMenu?.previousElementSibling;
+        }
+
+        // when previous sibling is open, go to its last item
+        if (previousSideNavMenu?.getAttribute('aria-expanded') == 'true') {
+          nextFocusNode = treeWalker.previousNode();
+        } else {
+          nextFocusNode = treeWalker.previousSibling();
+
+          // first item in the menu, go back up to SideNavMenu button
+          if (nextFocusNode == null) {
+            nextFocusNode = parentNode;
+          }
+        }
+      }
+      if (match(event, keys.ArrowDown)) {
+        if (treeWalker.currentNode.getAttribute('aria-expanded') == 'false') {
+          nextFocusNode = treeWalker.nextSibling();
+        } else {
+          nextFocusNode = treeWalker.nextNode();
+        }
+      }
+
+      // Home/End functionality
+      if (matches(event, [keys.Home, keys.End])) {
+        if (!sideNavRef?.current) {
+          return;
+        }
+        const allItems = Array.from(sideNavRef.current.querySelectorAll('a, button'));
+        if (match(event, keys.Home)) {
+          const firstElement = allItems[0];
+          if (firstElement) {
+            firstElement.tabIndex = 0;
+            firstElement?.focus();
+          }
+        }
+        if (match(event, keys.End)) {
+          const allItems = Array.from(sideNavRef.current.querySelectorAll('li'));
+          const lastVisibleItem = allItems.reverse().find(item => getComputedStyle(item).visibility !== 'hidden');
+          if (lastVisibleItem) {
+            const node = lastVisibleItem.querySelector('button') ?? lastVisibleItem.querySelector('a');
+            if (node) {
+              node.tabIndex = 0;
+              node?.focus();
+            }
+          }
+        }
+      }
+
+      // focus on the focusable element within the node
+      if (nextFocusNode && nextFocusNode !== event.target) {
+        resetNodeTabIndices();
+        if (nextFocusNode instanceof HTMLElement) {
+          const node = nextFocusNode.querySelector('button') ?? nextFocusNode.querySelector('a');
+          if (node) {
+            node.tabIndex = 0;
+            node?.focus();
+          }
+        }
+      }
+
+      // close menu
       if (match(event, keys.Escape)) {
+        if (expanded && !isFixedNav) {
+          if (onSideNavBlur) {
+            onSideNavBlur();
+          }
+        }
         handleToggle(event, false);
         if (href) {
           window.location.href = href;
@@ -167,12 +287,19 @@ function SideNavRenderFunction(_ref, ref) {
   }
   useWindowEvent('keydown', event => {
     const focusedElement = document.activeElement;
-    if (match(event, keys.Tab) && expanded && !isFixedNav && sideNavRef.current && focusedElement?.classList.contains(`${prefix}--header__menu-toggle`) && !focusedElement.closest('nav')) {
+
+    // going from header menu to sideNav
+    if (match(event, keys.Tab) && expanded && !isFixedNav && sideNavRef?.current && focusedElement?.classList.contains(`${prefix}--header__menu-toggle`) && !focusedElement.closest('nav')) {
       sideNavRef.current.focus();
     }
   });
   const lgMediaQuery = `(min-width: ${breakpoints.lg.width})`;
   const isLg = useMatchMedia(lgMediaQuery);
+  function resetNodeTabIndices() {
+    Array.prototype.forEach.call(sideNavRef?.current?.querySelectorAll('[tabIndex="0"]') ?? [], item => {
+      item.tabIndex = -1;
+    });
+  }
   return /*#__PURE__*/React.createElement(SideNavContext.Provider, {
     value: {
       isRail
@@ -184,6 +311,7 @@ function SideNavRenderFunction(_ref, ref) {
     className: overlayClassName,
     onClick: onOverlayClick
   }), /*#__PURE__*/React.createElement("nav", _extends({
+    role: "tree",
     tabIndex: -1,
     ref: navRef,
     className: `${prefix}--side-nav__navigation ${className}`,

package/es/components/SideNavItems.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Copyright IBM Corp. 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.
+ */
+import React from 'react';
+export interface SideNavItemsProps {
+    /**
+     * Provide a single icon as the child to `SideNavIcon` to render in the
+     * container
+     */
+    children: React.ReactNode;
+    /**
+     * Provide an optional class to be applied to the containing node
+     */
+    className?: 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?: boolean;
+}
+export declare const SideNavItems: React.FC<SideNavItemsProps>;

package/es/components/SideNavItems.js

@@ -0,0 +1,61 @@
+/**
+ * Copyright IBM Corp. 2024
+ *
+ * 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 cx from '../_virtual/index.js';
+import PropTypes from 'prop-types';
+import React from 'react';
+import { CARBON_SIDENAV_ITEMS } from './_utils.js';
+import { usePrefix } from '@carbon/react/lib/internal/usePrefix';
+
+const SideNavItems = _ref => {
+  let {
+    className: customClassName,
+    children,
+    isSideNavExpanded
+  } = _ref;
+  const prefix = usePrefix();
+  const className = cx([`${prefix}--side-nav__items`], customClassName);
+  const childrenWithExpandedState = React.Children.map(children, child => {
+    if (/*#__PURE__*/React.isValidElement(child)) {
+      // avoid spreading `isSideNavExpanded` to non-Carbon UI Shell children
+      const childJsxElement = child;
+      const childDisplayName = childJsxElement.type?.displayName ?? childJsxElement.type?.name;
+      const isCarbonSideNavItem = CARBON_SIDENAV_ITEMS.includes(childDisplayName);
+      const isSideNavMenu = childDisplayName === 'SideNavMenu';
+      return /*#__PURE__*/React.cloneElement(child, {
+        ...(isCarbonSideNavItem && {
+          isSideNavExpanded: isSideNavExpanded
+        }),
+        ...(isSideNavMenu && {
+          depth: 0
+        })
+      });
+    }
+  });
+  return /*#__PURE__*/React.createElement("ul", {
+    className: className
+  }, childrenWithExpandedState);
+};
+SideNavItems.displayName = 'SideNavItems';
+SideNavItems.propTypes = {
+  /**
+   * Provide a single icon as the child to `SideNavIcon` to render in the
+   * container
+   */
+  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
+};
+
+export { SideNavItems };

package/es/components/SideNavMenu.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Copyright IBM Corp. 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.
+ */
+import React from 'react';
+export interface SideNavMenuProps {
+    /**
+     * An optional CSS class to apply to the component.
+     */
+    className?: string;
+    /**
+     * The content to render within the SideNavMenu component.
+     */
+    children?: React.ReactNode;
+    /**
+     * Specifies whether the menu should be expanded by default.
+     */
+    defaultExpanded?: boolean;
+    /**
+     * **Note:** this is controlled by the parent SideNav component, do not set manually.
+     * SideNavMenu depth to determine spacing
+     */
+    depth?: number;
+    /**
+     * Indicates whether the SideNavMenu is active.
+     */
+    isActive?: boolean;
+    /**
+     * Specifies whether the SideNavMenu is in a large variation.
+     */
+    large?: boolean;
+    /**
+     * A custom icon to render next to the SideNavMenu title. This can be a function returning JSX or JSX itself.
+     */
+    renderIcon?: React.ComponentType;
+    /**
+     * Indicates if the side navigation container is expanded or collapsed.
+     */
+    isSideNavExpanded?: boolean;
+    /**
+     * The tabIndex for the button element.
+     * If not specified, the default validation will be applied.
+     */
+    tabIndex?: number;
+    title: string;
+}
+export declare const SideNavMenu: React.ForwardRefExoticComponent<SideNavMenuProps & React.RefAttributes<HTMLElement>>;

package/es/components/SideNavMenu.js

@@ -0,0 +1,274 @@
+/**
+ * Copyright IBM Corp. 2024
+ *
+ * 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 cx from '../_virtual/index.js';
+import PropTypes from 'prop-types';
+import React, { useContext, useState, useRef, useEffect } from 'react';
+import { CARBON_SIDENAV_ITEMS } from './_utils.js';
+import SideNavIcon from '@carbon/react/lib/components/UIShell/SideNavIcon';
+import { match } from '@carbon/react/lib/internal/keyboard/match';
+import { usePrefix } from '@carbon/react/lib/internal/usePrefix';
+import { SideNavContext } from './SideNav.js';
+import { useMergedRefs } from '@carbon/react/lib/internal/useMergedRefs';
+import * as keys from '@carbon/react/lib/internal/keyboard/keys';
+import { ChevronDown } from '../node_modules/@carbon/icons-react/es/generated/bucket-3.js';
+
+var _ChevronDown;
+const SideNavMenu = /*#__PURE__*/React.forwardRef(function SideNavMenu(_ref, ref) {
+  let {
+    className: customClassName,
+    children,
+    defaultExpanded = false,
+    depth: propDepth,
+    isActive = false,
+    large = false,
+    renderIcon: IconElement,
+    isSideNavExpanded,
+    tabIndex,
+    title
+  } = _ref;
+  const depth = propDepth;
+  const {
+    isRail
+  } = useContext(SideNavContext);
+  const prefix = usePrefix();
+  const [isExpanded, setIsExpanded] = useState(defaultExpanded);
+  const [active, setActive] = useState(isActive);
+  const [prevExpanded, setPrevExpanded] = useState(defaultExpanded);
+  const className = cx({
+    [`${prefix}--side-nav__item`]: true,
+    [`${prefix}--side-nav__item--active`]: active || hasActiveDescendant(children) && !isExpanded,
+    [`${prefix}--side-nav__item--icon`]: IconElement,
+    [`${prefix}--side-nav__item--large`]: large,
+    [customClassName]: !!customClassName
+  });
+  const buttonClassName = cx({
+    [`${prefix}--side-nav__submenu`]: true,
+    [`${prefix}--side-nav__submenu--active`]: active || hasActiveDescendant(children) && isExpanded
+  });
+  const buttonRef = useRef(null);
+  const listRef = useRef(null);
+  const menuRef = useMergedRefs([buttonRef, ref]);
+  if (!isSideNavExpanded && isExpanded && isRail) {
+    setIsExpanded(false);
+    setPrevExpanded(true);
+  } else if (isSideNavExpanded && prevExpanded && isRail) {
+    setIsExpanded(true);
+    setPrevExpanded(false);
+  }
+  let childrenToRender = children;
+
+  // modify nested SideNavMenus
+  childrenToRender = React.Children.map(children, child => {
+    if (/*#__PURE__*/React.isValidElement(child)) {
+      const childJsxElement = child;
+      const childDisplayName = childJsxElement.type?.displayName ?? childJsxElement.type?.name;
+      const isCarbonSideNavItem = CARBON_SIDENAV_ITEMS.includes(childDisplayName);
+      return /*#__PURE__*/React.cloneElement(child, {
+        ...(isCarbonSideNavItem && {
+          isSideNavExpanded: isSideNavExpanded
+        }),
+        ...{
+          depth: depth + 1
+        }
+      });
+    }
+    return child;
+  });
+  useEffect(() => {
+    if (depth === 0) return;
+    const calcButtonOffset = () => {
+      // menu with icon
+      if (children && IconElement) {
+        return depth + 3;
+      }
+
+      // menu without icon
+      if (children) {
+        return depth * 4;
+      }
+      return depth;
+    };
+    if (buttonRef.current) {
+      buttonRef.current.style.paddingLeft = `${calcButtonOffset()}rem`;
+    }
+  }, []);
+
+  /**
+   * Returns the parent SideNavMenu, if node is actually inside one.
+   * @param node
+   * @returns parent side nav menu node
+   */
+  function parentSideNavMenu(node) {
+    const parentNode = node.parentElement?.closest(`.${prefix}--side-nav__item`);
+    if (parentNode) return parentNode;
+    return node;
+  }
+  function handleKeyDown(event) {
+    if (match(event, keys.Escape)) {
+      setIsExpanded(false);
+    }
+    const node = event.target;
+    const isMenu = node.hasAttribute('aria-expanded');
+    const isExpanded = node.getAttribute('aria-expanded');
+    const parent = parentSideNavMenu(node);
+    if (match(event, keys.ArrowLeft)) {
+      event.stopPropagation();
+      if (isMenu) {
+        // collapse menu
+        if (isExpanded == 'true') {
+          setIsExpanded(false);
+
+          // go to previous level's side nav menu button
+        } else {
+          // since we're in a menu, it finds its own <li>, we go up one more
+          const previousMenu = parentSideNavMenu(parent);
+          const button = previousMenu.querySelector('button');
+          button.tabIndex = 0;
+          button?.focus();
+        }
+
+        // go to side nav menu button
+      } else if (parent) {
+        const button = parent.querySelector('button');
+        button.tabIndex = 0;
+        button?.focus();
+      }
+    }
+    if (match(event, keys.ArrowRight)) {
+      event.stopPropagation();
+
+      // expand menu
+      if (isMenu) {
+        setIsExpanded(true);
+
+        // if already expanded, focus on first element
+        if (isExpanded == 'true') {
+          let nextNode = node.nextElementSibling?.querySelector('a, button');
+          if (nextNode) {
+            nextNode.tabIndex = 0;
+            nextNode.focus();
+          }
+        }
+      }
+    }
+  }
+  return (
+    /*#__PURE__*/
+    // eslint-disable-next-line jsx-a11y/no-noninteractive-element-interactions
+    React.createElement("li", {
+      role: "treeitem",
+      "aria-expanded": isExpanded,
+      className: className,
+      ref: listRef,
+      onKeyDown: handleKeyDown
+    }, /*#__PURE__*/React.createElement("button", {
+      "aria-expanded": isExpanded,
+      className: buttonClassName,
+      onClick: () => {
+        setIsExpanded(!isExpanded);
+      },
+      ref: menuRef,
+      type: "button",
+      tabIndex: -1
+    }, IconElement && /*#__PURE__*/React.createElement(SideNavIcon, null, /*#__PURE__*/React.createElement(IconElement, null)), /*#__PURE__*/React.createElement("span", {
+      className: `${prefix}--side-nav__submenu-title`
+    }, title), /*#__PURE__*/React.createElement(SideNavIcon, {
+      className: `${prefix}--side-nav__submenu-chevron`,
+      small: true
+    }, _ChevronDown || (_ChevronDown = /*#__PURE__*/React.createElement(ChevronDown, {
+      size: 20
+    })))), /*#__PURE__*/React.createElement("ul", {
+      className: `${prefix}--side-nav__menu`,
+      role: "group"
+    }, childrenToRender))
+  );
+});
+SideNavMenu.displayName = 'SideNavMenu';
+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,
+  /**
+   * **Note:** this is controlled by the parent SideNav component, do not set manually.
+   * SideNavMenu depth to determine spacing
+   */
+  depth: PropTypes.number,
+  /**
+   * 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
+   */
+  // @ts-expect-error - PropTypes are unable to cover this case.
+  renderIcon: PropTypes.oneOfType([PropTypes.func, PropTypes.object]),
+  /**
+   * Optional prop to specify the tabIndex of the button. If undefined, it will be applied default validation
+   */
+  tabIndex: PropTypes.number,
+  /**
+   * Provide the text for the overall menu name
+   */
+  title: PropTypes.string.isRequired
+};
+
+/**
+Defining the children parameter with the type ReactNode | ReactNode[]. This allows for various possibilities:
+a single element, an array of elements, or null or undefined.
+**/
+function hasActiveDescendant(children) {
+  if (Array.isArray(children)) {
+    return children.some(child => {
+      if (! /*#__PURE__*/React.isValidElement(child)) {
+        return false;
+      }
+
+      /** Explicitly defining the expected prop types (isActive and 'aria-current) for the children to ensure type
+      safety when accessing their props.
+      **/
+      const props = child.props;
+      if (props.isActive === true || props['aria-current'] || props.children instanceof Array && hasActiveDescendant(props.children)) {
+        return true;
+      }
+      return false;
+    });
+  }
+
+  // We use React.isValidElement(child) to check if the child is a valid React element before accessing its props
+
+  if (/*#__PURE__*/React.isValidElement(children)) {
+    const props = children.props;
+    if (props.isActive === true || props['aria-current']) {
+      return true;
+    }
+  }
+  return false;
+}
+
+export { SideNavMenu };

package/es/components/SideNavMenuItem.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Copyright IBM Corp. 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.
+ */
+import React, { ElementType, ComponentProps } from 'react';
+import Link from '@carbon/react/lib/components/UIShell/Link';
+export interface SideNavMenuItemProps extends ComponentProps<typeof Link> {
+    /**
+     * Specify the children to be rendered inside of the `SideNavMenuItem`
+     */
+    children?: React.ReactNode;
+    /**
+     * Provide an optional class to be applied to the containing node
+     */
+    className?: string;
+    /**
+     * **Note:** this is controlled by the parent SideNavMenu component, do not set manually.
+     * SideNavMenu depth to determine spacing
+     */
+    depth?: number;
+    /**
+     * 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
+     * `aria-current="page"`, as well.
+     */
+    isActive?: boolean;
+    /**
+     * Optionally provide an href for the underlying li`
+     */
+    href?: string;
+    /**
+     * Optional component to render instead of default Link
+     */
+    as?: ElementType;
+}
+export declare const SideNavMenuItem: React.ForwardRefExoticComponent<Omit<SideNavMenuItemProps, "ref"> & React.RefAttributes<HTMLElement>>;