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

package/es/components/SideNav.js

@@ -6,7 +6,7 @@
  */
 
 import { extends as _extends } from '../_virtual/_rollupPluginBabelHelpers.js';
-import React, { useRef, isValidElement, useEffect, 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';

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.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.js

@@ -0,0 +1,84 @@
+/**
+ * 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 { extends as _extends } from '../_virtual/_rollupPluginBabelHelpers.js';
+import cx from '../_virtual/index.js';
+import PropTypes from 'prop-types';
+import React, { useRef, useEffect } from 'react';
+import SideNavLinkText from '@carbon/react/lib/components/UIShell/SideNavLinkText';
+import Link from '@carbon/react/lib/components/UIShell/Link';
+import { usePrefix } from '@carbon/react/lib/internal/usePrefix';
+import { useMergedRefs } from '@carbon/react/lib/internal/useMergedRefs';
+
+const SideNavMenuItem = /*#__PURE__*/React.forwardRef(function SideNavMenuItem(props, ref) {
+  const prefix = usePrefix();
+  const {
+    children,
+    className: customClassName,
+    depth: propDepth,
+    as: Component = Link,
+    isActive,
+    ...rest
+  } = props;
+  const className = cx(`${prefix}--side-nav__menu-item`, customClassName);
+  const depth = propDepth;
+  const linkClassName = cx({
+    [`${prefix}--side-nav__link`]: true,
+    [`${prefix}--side-nav__link--current`]: isActive
+  });
+  const linkRef = useRef(null);
+  const itemRef = useMergedRefs([linkRef, ref]);
+  useEffect(() => {
+    const calcLinkOffset = () => {
+      return 4 + Math.max(0, depth - 1) * 1;
+    };
+    if (linkRef.current) {
+      linkRef.current.style.paddingLeft = `${calcLinkOffset()}rem`;
+    }
+  }, []);
+  return /*#__PURE__*/React.createElement("li", {
+    role: "treeitem",
+    "aria-selected": isActive ? 'true' : 'false',
+    className: className
+  }, /*#__PURE__*/React.createElement(Component, _extends({}, rest, {
+    className: linkClassName,
+    tabIndex: -1,
+    ref: itemRef
+  }), /*#__PURE__*/React.createElement(SideNavLinkText, null, children)));
+});
+SideNavMenuItem.displayName = 'SideNavMenuItem';
+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,
+  /**
+   * **Note:** this is controlled by the parent SideNavMenu component, do not set manually.
+   * SideNavMenu depth to determine spacing
+   */
+  depth: PropTypes.number,
+  /**
+   * Optionally provide an href for the underlying li`
+   */
+  href: 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
+   * `aria-current="page"`, as well.
+   */
+  isActive: PropTypes.bool,
+  /**
+   * Optional component to render instead of default Link
+   */
+  as: PropTypes.elementType
+};
+
+export { SideNavMenuItem };

package/es/index.d.ts

@@ -6,5 +6,8 @@
  * This source code is licensed under the Apache-2.0 license found in the
  * LICENSE file in the root directory of this source tree.
  */
-export { SideNav } from './components/SideNav.js';
+export { SideNav, SIDE_NAV_TYPE } from './components/SideNav.js';
+export { SideNavItems } from './components/SideNavItems.js';
+export { SideNavMenu } from './components/SideNavMenu.js';
+export { SideNavMenuItem } from './components/SideNavMenuItem.js';
 export { HeaderPanel } from './components/HeaderPanel';

package/es/index.js

@@ -5,5 +5,8 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-export { SideNav } from './components/SideNav.js';
+export { SIDE_NAV_TYPE, SideNav } from './components/SideNav.js';
+export { SideNavItems } from './components/SideNavItems.js';
+export { SideNavMenu } from './components/SideNavMenu.js';
+export { SideNavMenuItem } from './components/SideNavMenuItem.js';
 export { HeaderPanel } from './components/HeaderPanel.js';