@carbon-labs/react-ui-shell 0.15.0 → 0.17.0

package/README.md

@@ -1,5 +1,84 @@
 # @carbon-labs/react-ui-shell
 
+![npm version](https://img.shields.io/npm/v/@carbon-labs/react-ui-shell)
+![License](https://img.shields.io/github/license/carbon-design-system/carbon-labs)
+
+The `@carbon-labs/react-ui-shell` package extends UI Shell components from
+`@carbon/react`, providing additional enhancements while maintaining
+compatibility.
+
+## 📦 Getting started
+
+To install `@carbon-labs/react-ui-shell` in your project, you will need to run
+the following command using [npm](https://www.npmjs.com/):
+
+```bash
+npm install -S @carbon-labs/react-ui-shell @carbon/react
+```
+
+If you prefer [Yarn](https://yarnpkg.com/en/), use the following command
+instead:
+
+```bash
+yarn add @carbon-labs/react-ui-shell @carbon/react
+```
+
+## ⚡ Usage
+
+To use this package you will need to import components from both `@carbon/react`
+and `@carbon-labs/react-ui-shell`o compose the UI Shell. The following
+components are provided by `@carbon-labs/react-ui-shell`:
+
+- `SideNav`
+- `SideNavItems`
+- `SideNavMenu`
+- `SideNavMenuItem`
+- `HeaderPanel`
+
+```jsx
+import { SideNav } from '@carbon-labs/react-ui-shell/es/index';
+import { Header } from '@carbon/react';
+
+function MyComponent() {
+  return (
+    <Header>
+      <SideNav>...</SideNav>>
+    </Header>
+  );
+}
+```
+
+### SCSS
+
+Import the styles from `@carbon/react` and `@carbon-labs/react-ui-shell` in your
+stylesheet:
+
+```scss
+@use '@carbon/react' with (
+  $font-path: '@ibm/plex'
+);
+@use '@carbon-labs/react-ui-shell/scss/ui-shell';
+```
+
+### Storybook
+
+You can explore the available components, see different configuration options,
+and learn how to compose them in
+[Storybook](https://labs.carbondesignsystem.com/?path=/docs/react_components-uishell--overview).
+
+## 🙌 Contributing
+
+Want to contribute to `@carbon-labs`? Read through the Carbon Labs
+[contribution section](https://pages.github.ibm.com/carbon/ibm-products/contributing/carbon-labs/#carbon-labs-in-code)
+before diving into our developer guide:
+
+- [Developer Guide](https://github.com/carbon-design-system/carbon-labs/blob/main/docs/developing.md)
+
+## 📝 License
+
+Licensed under the
+[Apache 2.0 License](https://github.com/carbon-design-system/carbon-labs/blob/main/LICENSE).
+
 ## <picture><source height="20" width="20" media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/ibm-telemetry/telemetry-js/main/docs/images/ibm-telemetry-dark.svg"><source height="20" width="20" media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/ibm-telemetry/telemetry-js/main/docs/images/ibm-telemetry-light.svg"><img height="20" width="20" alt="IBM Telemetry" src="https://raw.githubusercontent.com/ibm-telemetry/telemetry-js/main/docs/images/ibm-telemetry-light.svg"></picture> IBM Telemetry
 
 This package uses IBM Telemetry to collect de-identified and anonymized metrics

package/es/components/SideNav.d.ts

@@ -34,10 +34,14 @@ export interface SideNavProps extends ComponentProps<'nav'>, TranslateWithId<Tra
     isCollapsible?: boolean;
     hideOverlay?: boolean;
     navType: SIDE_NAV_TYPE;
+    isTreeview: boolean;
 }
 interface SideNavContextData {
+    expanded?: boolean;
     isRail?: boolean;
     navType?: SIDE_NAV_TYPE;
+    isTreeview?: boolean;
+    setIsTreeview?: (value: boolean) => void;
 }
 export declare const SideNavContext: React.Context<SideNavContextData>;
 export declare const SideNav: React.ForwardRefExoticComponent<Omit<SideNavProps, "ref"> & React.RefAttributes<HTMLElement>>;

package/es/components/SideNav.js

@@ -6,13 +6,13 @@
  */
 
 import { extends as _extends } from '../_virtual/_rollupPluginBabelHelpers.js';
-import React, { createContext, useRef, isValidElement, useEffect } from 'react';
+import React, { createContext, useState, useRef, isValidElement, useEffect } from 'react';
 import cx from '../_virtual/index.js';
 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 { ArrowUp, ArrowDown, Home, End, Escape, Tab } from '../internal/keyboard/keys.js';
+import { Escape, ArrowUp, ArrowDown, Home, End, Tab } from '../internal/keyboard/keys.js';
 import { match, matches } from '../internal/keyboard/match.js';
 import { useMergedRefs } from '../internal/useMergedRefs.js';
 import { useWindowEvent } from '../internal/useEvent.js';
@@ -52,6 +52,7 @@ function SideNavRenderFunction(_ref, ref) {
     isFixedNav = false,
     isRail,
     isPersistent = true,
+    isTreeview: isTreeviewProp,
     navType = SIDE_NAV_TYPE.DEFAULT,
     addFocusListeners = true,
     addMouseListeners = true,
@@ -63,6 +64,7 @@ function SideNavRenderFunction(_ref, ref) {
     translateWithId: t = defaultTranslateWithId,
     ...other
   } = _ref;
+  const [internalIsTreeview, setInternalIsTreeview] = useState(isTreeviewProp ?? false);
   const prefix = usePrefix();
   const {
     current: controlled
@@ -114,7 +116,10 @@ function SideNavRenderFunction(_ref, ref) {
       // avoid spreading `isSideNavExpanded` to non-Carbon UI Shell children
       return /*#__PURE__*/React.cloneElement(childJsxElement, {
         ...(CARBON_SIDENAV_ITEMS.includes(childJsxElement.type?.displayName ?? childJsxElement.type?.name) ? {
-          isSideNavExpanded: currentExpansionState
+          isSideNavExpanded: currentExpansionState,
+          ...(childJsxElement.type?.displayName === 'SideNavItems' && {
+            accessibilityLabel: accessibilityLabel
+          })
         } : {})
       });
     }
@@ -123,26 +128,28 @@ function SideNavRenderFunction(_ref, ref) {
   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)) {
+    if (internalIsTreeview) {
+      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;
         }
-        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;
       }
-    });
-    resetNodeTabIndices();
-    const firstElement = sideNavRef?.current?.querySelector('a, button');
-    if (firstElement) {
-      firstElement.tabIndex = 0;
     }
-  }, [prefix]);
+  }, [prefix, internalIsTreeview]);
 
   /**
    * Returns the parent SideNavMenu, if node is actually inside one.
@@ -174,98 +181,111 @@ function SideNavRenderFunction(_ref, ref) {
       }
     };
     eventHandlers.onKeyDown = event => {
-      if (!treeWalkerRef.current) return;
-      const treeWalker = treeWalkerRef.current;
-      event.stopPropagation();
-
-      // stops page from scrolling
-      if (matches(event, [ArrowUp, ArrowDown, Home, 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, 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;
+      // close menu
+      if (match(event, Escape)) {
+        if (expanded && !isFixedNav) {
+          resetNodeTabIndices();
+          if (onSideNavBlur) {
+            onSideNavBlur();
           }
         }
-      }
-      if (match(event, ArrowDown)) {
-        if (treeWalker.currentNode.getAttribute('aria-expanded') == 'false') {
-          nextFocusNode = treeWalker.nextSibling();
-        } else {
-          nextFocusNode = treeWalker.nextNode();
+        handleToggle(event, false);
+        if (href) {
+          window.location.href = href;
         }
       }
 
-      // Home/End functionality
-      if (matches(event, [Home, End])) {
-        if (!sideNavRef?.current) {
-          return;
+      // Treeview keyboard navigation
+      if (treeWalkerRef?.current && internalIsTreeview) {
+        const treeWalker = treeWalkerRef.current;
+        event.stopPropagation();
+
+        // stops page from scrolling
+        if (matches(event, [ArrowUp, ArrowDown, Home, End,
+        // @ts-ignore - `matches` doesn't like the object syntax without missing properties
+        {
+          code: 'KeyA'
+        }])) {
+          event.preventDefault();
         }
-        const allItems = Array.from(sideNavRef.current.querySelectorAll('a, button'));
-        if (match(event, Home)) {
-          const firstElement = allItems[0];
-          if (firstElement) {
-            firstElement.tabIndex = 0;
-            firstElement?.focus();
+        treeWalker.currentNode = event.target.closest(`li`) ?? treeWalker?.currentNode;
+        let nextFocusNode = null;
+        if (match(event, 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') {
+            const allItems = previousSideNavMenu.querySelectorAll(`.${prefix}--side-nav__item`);
+            const lastMenu = allItems[allItems.length - 1];
+            if (lastMenu && lastMenu.getAttribute('aria-expanded') == 'false') {
+              nextFocusNode = lastMenu;
+            } else {
+              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, 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();
+        if (match(event, ArrowDown)) {
+          if (treeWalker.currentNode.getAttribute('aria-expanded') == 'false') {
+            nextFocusNode = treeWalker.nextSibling();
+            if (!nextFocusNode) {
+              const parent = parentSideNavMenu(treeWalker.currentNode);
+              nextFocusNode = parent?.nextElementSibling;
             }
+          } else {
+            nextFocusNode = treeWalker.nextNode();
           }
         }
-      }
 
-      // 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();
+        // Home/End functionality
+        if (matches(event, [Home, End])) {
+          if (!sideNavRef?.current) {
+            return;
+          }
+          const allItems = Array.from(sideNavRef.current.querySelectorAll('a, button'));
+          if (match(event, Home)) {
+            const firstElement = allItems[0];
+            if (firstElement) {
+              firstElement.tabIndex = 0;
+              firstElement?.focus();
+            }
+          }
+          if (match(event, 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();
+              }
+            }
           }
         }
-      }
 
-      // close menu
-      if (match(event, Escape)) {
-        if (expanded && !isFixedNav) {
-          if (onSideNavBlur) {
-            onSideNavBlur();
+        // 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();
+            }
           }
         }
-        handleToggle(event, false);
-        if (href) {
-          window.location.href = href;
-        }
       }
     };
   }
@@ -304,9 +324,27 @@ function SideNavRenderFunction(_ref, ref) {
       item.tabIndex = -1;
     });
   }
+
+  // ensure that changes are in sync with internal treeview prop
+  useEffect(() => {
+    if (isTreeviewProp !== undefined) {
+      setInternalIsTreeview(isTreeviewProp);
+    }
+  }, [isTreeviewProp]);
+
+  // prevent changes if prop is passed in
+  const setIsTreeview = value => {
+    if (isTreeviewProp === undefined) {
+      setInternalIsTreeview(value);
+    }
+  };
   return /*#__PURE__*/React.createElement(SideNavContext.Provider, {
     value: {
-      isRail
+      isRail,
+      navType,
+      expanded: expanded,
+      isTreeview: internalIsTreeview,
+      setIsTreeview
     }
   }, isFixedNav || hideOverlay ? null :
   /*#__PURE__*/
@@ -315,7 +353,7 @@ function SideNavRenderFunction(_ref, ref) {
     className: overlayClassName,
     onClick: onOverlayClick
   }), /*#__PURE__*/React.createElement("nav", _extends({
-    role: "tree",
+    role: 'navigation',
     tabIndex: -1,
     ref: navRef,
     className: `${prefix}--side-nav__navigation ${className}`,

package/es/components/SideNavItems.d.ts

@@ -6,6 +6,11 @@
  */
 import React from 'react';
 export interface SideNavItemsProps {
+    /**
+     * Object to provide an aria-label to the component when used in treeview,
+     * to ensure it meets a11y requirements.
+     */
+    accessibilityLabel: object;
     /**
      * Provide a single icon as the child to `SideNavIcon` to render in the
      * container

package/es/components/SideNavItems.js

@@ -5,18 +5,25 @@
  * LICENSE file in the root directory of this source tree.
  */
 
+import { extends as _extends } from '../_virtual/_rollupPluginBabelHelpers.js';
 import cx from '../_virtual/index.js';
 import PropTypes from 'prop-types';
-import React from 'react';
+import React, { useContext, useRef, useEffect } from 'react';
 import { CARBON_SIDENAV_ITEMS } from './_utils.js';
 import { usePrefix } from '../internal/usePrefix.js';
+import { SideNavContext } from './SideNav.js';
 
 const SideNavItems = _ref => {
   let {
     className: customClassName,
     children,
-    isSideNavExpanded
+    isSideNavExpanded,
+    accessibilityLabel: accessibilityLabel
   } = _ref;
+  const {
+    isTreeview
+  } = useContext(SideNavContext);
+  const listRef = useRef(null); // Adjust type if necessary
   const prefix = usePrefix();
   const className = cx([`${prefix}--side-nav__items`], customClassName);
   const childrenWithExpandedState = React.Children.map(children, child => {
@@ -36,9 +43,22 @@ const SideNavItems = _ref => {
       });
     }
   });
-  return /*#__PURE__*/React.createElement("ul", {
-    className: className
-  }, childrenWithExpandedState);
+  useEffect(() => {
+    // set SideNavLink's role without needing to extend original component
+    if (isTreeview && listRef.current) {
+      const sideNavItem = listRef.current.querySelectorAll(`.${prefix}--side-nav__item a`);
+      sideNavItem.forEach(e => {
+        if (!e.hasAttribute('role')) {
+          e.setAttribute('role', 'treeitem');
+        }
+      });
+    }
+  }, [isTreeview]);
+  return /*#__PURE__*/React.createElement("ul", _extends({}, isTreeview && accessibilityLabel, {
+    ref: listRef,
+    className: className,
+    role: isTreeview ? 'tree' : ''
+  }), childrenWithExpandedState);
 };
 SideNavItems.displayName = 'SideNavItems';
 SideNavItems.propTypes = {