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

package/lib/components/SideNavItems.js

@@ -0,0 +1,63 @@
+/**
+ * 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.
+ */
+
+'use strict';
+
+var index = require('../_virtual/index.js');
+var PropTypes = require('prop-types');
+var React = require('react');
+var _utils = require('./_utils.js');
+var usePrefix = require('@carbon/react/lib/internal/usePrefix');
+
+const SideNavItems = _ref => {
+  let {
+    className: customClassName,
+    children,
+    isSideNavExpanded
+  } = _ref;
+  const prefix = usePrefix.usePrefix();
+  const className = index.default([`${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 = _utils.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
+};
+
+exports.SideNavItems = SideNavItems;

package/lib/components/SideNavMenu.js

@@ -0,0 +1,295 @@
+/**
+ * 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.
+ */
+
+'use strict';
+
+var index = require('../_virtual/index.js');
+var PropTypes = require('prop-types');
+var React = require('react');
+var _utils = require('./_utils.js');
+var SideNavIcon = require('@carbon/react/lib/components/UIShell/SideNavIcon');
+var match = require('@carbon/react/lib/internal/keyboard/match');
+var usePrefix = require('@carbon/react/lib/internal/usePrefix');
+var SideNav = require('./SideNav.js');
+var useMergedRefs = require('@carbon/react/lib/internal/useMergedRefs');
+var keys = require('@carbon/react/lib/internal/keyboard/keys');
+var bucket3 = require('../node_modules/@carbon/icons-react/es/generated/bucket-3.js');
+
+function _interopNamespaceDefault(e) {
+  var n = Object.create(null);
+  if (e) {
+    Object.keys(e).forEach(function (k) {
+      if (k !== 'default') {
+        var d = Object.getOwnPropertyDescriptor(e, k);
+        Object.defineProperty(n, k, d.get ? d : {
+          enumerable: true,
+          get: function () { return e[k]; }
+        });
+      }
+    });
+  }
+  n.default = e;
+  return Object.freeze(n);
+}
+
+var keys__namespace = /*#__PURE__*/_interopNamespaceDefault(keys);
+
+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
+  } = React.useContext(SideNav.SideNavContext);
+  const prefix = usePrefix.usePrefix();
+  const [isExpanded, setIsExpanded] = React.useState(defaultExpanded);
+  const [active, setActive] = React.useState(isActive);
+  const [prevExpanded, setPrevExpanded] = React.useState(defaultExpanded);
+  const className = index.default({
+    [`${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 = index.default({
+    [`${prefix}--side-nav__submenu`]: true,
+    [`${prefix}--side-nav__submenu--active`]: active || hasActiveDescendant(children) && isExpanded
+  });
+  const buttonRef = React.useRef(null);
+  const listRef = React.useRef(null);
+  const menuRef = useMergedRefs.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 = _utils.CARBON_SIDENAV_ITEMS.includes(childDisplayName);
+      return /*#__PURE__*/React.cloneElement(child, {
+        ...(isCarbonSideNavItem && {
+          isSideNavExpanded: isSideNavExpanded
+        }),
+        ...{
+          depth: depth + 1
+        }
+      });
+    }
+    return child;
+  });
+  React.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.match(event, keys__namespace.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.match(event, keys__namespace.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.match(event, keys__namespace.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(bucket3.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;
+}
+
+exports.SideNavMenu = SideNavMenu;

package/lib/components/SideNavMenuItem.js

@@ -0,0 +1,86 @@
+/**
+ * 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.
+ */
+
+'use strict';
+
+var _rollupPluginBabelHelpers = require('../_virtual/_rollupPluginBabelHelpers.js');
+var index = require('../_virtual/index.js');
+var PropTypes = require('prop-types');
+var React = require('react');
+var SideNavLinkText = require('@carbon/react/lib/components/UIShell/SideNavLinkText');
+var Link = require('@carbon/react/lib/components/UIShell/Link');
+var usePrefix = require('@carbon/react/lib/internal/usePrefix');
+var useMergedRefs = require('@carbon/react/lib/internal/useMergedRefs');
+
+const SideNavMenuItem = /*#__PURE__*/React.forwardRef(function SideNavMenuItem(props, ref) {
+  const prefix = usePrefix.usePrefix();
+  const {
+    children,
+    className: customClassName,
+    depth: propDepth,
+    as: Component = Link,
+    isActive,
+    ...rest
+  } = props;
+  const className = index.default(`${prefix}--side-nav__menu-item`, customClassName);
+  const depth = propDepth;
+  const linkClassName = index.default({
+    [`${prefix}--side-nav__link`]: true,
+    [`${prefix}--side-nav__link--current`]: isActive
+  });
+  const linkRef = React.useRef(null);
+  const itemRef = useMergedRefs.useMergedRefs([linkRef, ref]);
+  React.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, _rollupPluginBabelHelpers.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
+};
+
+exports.SideNavMenuItem = SideNavMenuItem;

package/lib/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/lib/index.js

@@ -8,9 +8,16 @@
 'use strict';
 
 var SideNav = require('./components/SideNav.js');
+var SideNavItems = require('./components/SideNavItems.js');
+var SideNavMenu = require('./components/SideNavMenu.js');
+var SideNavMenuItem = require('./components/SideNavMenuItem.js');
 var HeaderPanel = require('./components/HeaderPanel.js');
 
 
 
+exports.SIDE_NAV_TYPE = SideNav.SIDE_NAV_TYPE;
 exports.SideNav = SideNav.SideNav;
+exports.SideNavItems = SideNavItems.SideNavItems;
+exports.SideNavMenu = SideNavMenu.SideNavMenu;
+exports.SideNavMenuItem = SideNavMenuItem.SideNavMenuItem;
 exports.HeaderPanel = HeaderPanel.HeaderPanel;