@carbon-labs/react-ui-shell 0.6.0 → 0.8.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, { useRef, isValidElement, useEffect, createContext } 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/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/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>>;

package/lib/components/SideNav.js

@@ -142,6 +142,39 @@ function SideNavRenderFunction(_ref, ref) {
     return child;
   });
   const eventHandlers = {};
+  const treeWalkerRef = React.useRef(null);
+  React.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) {
@@ -162,7 +195,94 @@ function SideNavRenderFunction(_ref, ref) {
       }
     };
     eventHandlers.onKeyDown = event => {
+      if (!treeWalkerRef.current) return;
+      const treeWalker = treeWalkerRef.current;
+      event.stopPropagation();
+
+      // stops page from scrolling
+      if (match.matches(event, [keys__namespace.ArrowUp, keys__namespace.ArrowDown, keys__namespace.Home, keys__namespace.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.match(event, keys__namespace.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.match(event, keys__namespace.ArrowDown)) {
+        if (treeWalker.currentNode.getAttribute('aria-expanded') == 'false') {
+          nextFocusNode = treeWalker.nextSibling();
+        } else {
+          nextFocusNode = treeWalker.nextNode();
+        }
+      }
+
+      // Home/End functionality
+      if (match.matches(event, [keys__namespace.Home, keys__namespace.End])) {
+        if (!sideNavRef?.current) {
+          return;
+        }
+        const allItems = Array.from(sideNavRef.current.querySelectorAll('a, button'));
+        if (match.match(event, keys__namespace.Home)) {
+          const firstElement = allItems[0];
+          if (firstElement) {
+            firstElement.tabIndex = 0;
+            firstElement?.focus();
+          }
+        }
+        if (match.match(event, keys__namespace.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.match(event, keys__namespace.Escape)) {
+        if (expanded && !isFixedNav) {
+          if (onSideNavBlur) {
+            onSideNavBlur();
+          }
+        }
         handleToggle(event, false);
         if (href) {
           window.location.href = href;
@@ -188,12 +308,19 @@ function SideNavRenderFunction(_ref, ref) {
   }
   useEvent.useWindowEvent('keydown', event => {
     const focusedElement = document.activeElement;
-    if (match.match(event, keys__namespace.Tab) && expanded && !isFixedNav && sideNavRef.current && focusedElement?.classList.contains(`${prefix}--header__menu-toggle`) && !focusedElement.closest('nav')) {
+
+    // going from header menu to sideNav
+    if (match.match(event, keys__namespace.Tab) && expanded && !isFixedNav && sideNavRef?.current && focusedElement?.classList.contains(`${prefix}--header__menu-toggle`) && !focusedElement.closest('nav')) {
       sideNavRef.current.focus();
     }
   });
   const lgMediaQuery = `(min-width: ${index$1.breakpoints.lg.width})`;
   const isLg = useMatchMedia.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
@@ -205,6 +332,7 @@ function SideNavRenderFunction(_ref, ref) {
     className: overlayClassName,
     onClick: onOverlayClick
   }), /*#__PURE__*/React.createElement("nav", _rollupPluginBabelHelpers.extends({
+    role: "tree",
     tabIndex: -1,
     ref: navRef,
     className: `${prefix}--side-nav__navigation ${className}`,

package/lib/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/lib/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/lib/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>>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@carbon-labs/react-ui-shell",
-  "version": "0.6.0",
+  "version": "0.8.0",
   "publishConfig": {
     "access": "public",
     "provenance": true
@@ -33,5 +33,5 @@
   "dependencies": {
     "@ibm/telemetry-js": "^1.9.1"
   },
-  "gitHead": "615e563886e18b341199eea82182fecd16c8dfd1"
+  "gitHead": "5b474b82f13a6c1fec121c8729d208082140b9f5"
 }

package/scss/styles/_side-nav.scss

@@ -28,10 +28,30 @@ $prefix: 'cds' !default;
   inline-size: convert.to-rem(256px);
 }
 
+//----------------------------------------------------------------------------
+// Treeview Side-nav
+//----------------------------------------------------------------------------
+.#{$prefix}--side-nav__icon:not(.#{$prefix}--side-nav__submenu-chevron) {
+  margin-inline-end: $spacing-05;
+}
+
+.#{$prefix}--side-nav__submenu.#{$prefix}--side-nav__submenu--active {
+  > span {
+    color: $text-primary;
+    font-weight: 600;
+  }
+
+  .#{$prefix}--side-nav__submenu-chevron > svg {
+    fill: $icon-primary;
+  }
+}
+
 //----------------------------------------------------------------------------
 // Side-nav Panel
 //----------------------------------------------------------------------------
 .#{$prefix}--side-nav--panel {
+  z-index: 7999; /* needs to be below header */
+
   .#{$prefix}--side-nav__icon:not(.#{$prefix}--side-nav__submenu-chevron) {
     margin-inline-end: $spacing-05;
   }