@carbon-labs/react-ui-shell 0.19.0 → 0.21.0

package/README.md

@@ -31,6 +31,7 @@ components are provided by `@carbon-labs/react-ui-shell`:
 
 - `SideNav`
 - `SideNavItems`
+- `SideNavLink`
 - `SideNavMenu`
 - `SideNavMenuItem`
 - `HeaderPanel`

package/es/components/SideNav.js

@@ -158,7 +158,9 @@ function SideNavRenderFunction(_ref, ref) {
    */
   function parentSideNavMenu(node) {
     const parentNode = node.parentElement?.closest(`.${prefix}--side-nav__item`);
-    if (parentNode) return parentNode;
+    if (parentNode) {
+      return parentNode;
+    }
     return node;
   }
   if (addFocusListeners) {
@@ -340,9 +342,9 @@ function SideNavRenderFunction(_ref, ref) {
   };
   return /*#__PURE__*/React.createElement(SideNavContext.Provider, {
     value: {
+      expanded,
       isRail,
       navType,
-      expanded: expanded,
       isTreeview: internalIsTreeview,
       setIsTreeview
     }

package/es/components/SideNavLink.d.ts

@@ -0,0 +1,57 @@
+/**
+ * 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 { ComponentType, ElementType, ForwardedRef, ReactNode, WeakValidationMap } from 'react';
+import { LinkProps } from './Link';
+export type SideNavLinkProps<E extends ElementType> = LinkProps<E> & {
+    /**
+     * Required props for the accessibility label
+     */
+    'aria-label'?: string;
+    /**
+     * Required props for the accessibility label
+     */
+    'aria-labelledby'?: string;
+    /**
+     * Specify the text content for the link
+     */
+    children?: ReactNode;
+    /**
+     * Provide an optional class to be applied to the containing node
+     */
+    className?: string;
+    /**
+     * Specify whether the link is the current page
+     */
+    isActive?: boolean;
+    /**
+     * 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;
+    /**
+     * Specify if this is a large variation of the SideNavLink
+     */
+    large?: boolean;
+    /**
+     * Provide an icon to render in the side navigation link. Should be a React class.
+     */
+    renderIcon?: ComponentType;
+    /**
+     * Optional prop to specify the tabIndex of the button. If undefined, it will be applied default validation
+     */
+    tabIndex?: number;
+};
+export interface SideNavLinkComponent {
+    <E extends ElementType = 'a'>(props: SideNavLinkProps<E> & {
+        ref?: ForwardedRef<ElementType>;
+    }): JSX.Element | null;
+    displayName?: string;
+    propTypes?: WeakValidationMap<SideNavLinkProps<any>>;
+}
+export declare const SideNavLink: SideNavLinkComponent;
+export declare const createCustomSideNavLink: (element: any) => (props: any) => import("react/jsx-runtime").JSX.Element;
+export default SideNavLink;

package/es/components/SideNavLink.js

@@ -0,0 +1,92 @@
+/**
+ * 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, { forwardRef, useContext } from 'react';
+import Link, { LinkPropTypes } from './Link.js';
+import { SideNavItem, SideNavLinkText, SideNavIcon } from '@carbon/react';
+import { usePrefix } from '../internal/usePrefix.js';
+import { SideNavContext } from './SideNav.js';
+import { SideNavLinkPopover } from './SideNavLinkPopover.js';
+
+const SideNavLink = /*#__PURE__*/forwardRef(function SideNavLink(_ref, ref) {
+  let {
+    children,
+    className: customClassName,
+    renderIcon: IconElement,
+    isActive,
+    isSideNavExpanded,
+    large = false,
+    tabIndex,
+    ...rest
+  } = _ref;
+  const {
+    expanded,
+    isRail,
+    navType
+  } = useContext(SideNavContext);
+  const prefix = usePrefix();
+  const className = cx({
+    [`${prefix}--side-nav__link`]: true,
+    [`${prefix}--side-nav__link--current`]: isActive,
+    [customClassName]: !!customClassName
+  });
+  const SideNavLinkIcon = IconElement && /*#__PURE__*/React.createElement(SideNavIcon, {
+    small: true
+  }, /*#__PURE__*/React.createElement(IconElement, null));
+  if (!expanded && navType === 'panel') {
+    return /*#__PURE__*/React.createElement(SideNavLinkPopover, _extends({
+      align: "right",
+      label: children
+    }, rest), SideNavLinkIcon);
+  }
+  return /*#__PURE__*/React.createElement(SideNavItem, {
+    large: large
+  }, /*#__PURE__*/React.createElement(Link, _extends({}, rest, {
+    className: className,
+    ref: ref,
+    tabIndex: tabIndex === undefined ? !isSideNavExpanded && !isRail ? -1 : 0 : tabIndex
+  }), SideNavLinkIcon, /*#__PURE__*/React.createElement(SideNavLinkText, null, children)));
+});
+SideNavLink.displayName = 'SideNavLink';
+SideNavLink.propTypes = {
+  ...LinkPropTypes,
+  /**
+   * Specify the text content for the link
+   */
+  children: PropTypes.node,
+  /**
+   * Provide an optional class to be applied to the containing node
+   */
+  className: PropTypes.string,
+  /**
+   * Specify whether the link is 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 SideNavLink
+   */
+  large: PropTypes.bool,
+  /**
+   * Provide an icon to render in the side navigation link. Should be a React class.
+   */
+  // @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
+};
+
+export { SideNavLink, SideNavLink as default };

package/es/components/SideNavLinkPopover.d.ts

@@ -0,0 +1,135 @@
+/**
+ * Copyright IBM Corp. 2016, 2023
+ *
+ * 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 PropTypes from 'prop-types';
+import React, { ReactNode } from 'react';
+import { IconButtonAlignment, ButtonSize } from '@carbon/react';
+interface IconButtonProps extends React.ButtonHTMLAttributes<HTMLButtonElement> {
+    /**
+     * Specify how the trigger should align with the tooltip
+     */
+    align?: IconButtonAlignment;
+    /**
+     * **Experimental**: Will attempt to automatically align the tooltip
+     */
+    autoAlign?: boolean;
+    /**
+     * Optionally specify an href for your IconButton to become an `<a>` element
+     */
+    href?: string;
+    /**
+     * Provide an icon or asset to be rendered inside of the IconButton
+     */
+    children?: ReactNode;
+    /**
+     * Specify an optional className to be added to your Button
+     */
+    className?: string;
+    /**
+     * Determines whether the tooltip should close when inner content is activated (click, Enter or Space)
+     */
+    closeOnActivation?: boolean;
+    /**
+     * Specify whether the tooltip should be open when it first renders
+     */
+    defaultOpen?: boolean;
+    /**
+     * Specify whether the Button should be disabled, or not
+     */
+    disabled?: boolean;
+    /**
+     * Specify the duration in milliseconds to delay before displaying the tooltip
+     */
+    enterDelayMs?: number;
+    /**
+     * Specify whether the IconButton is currently selected
+     */
+    isSelected?: boolean;
+    /**
+     * Provide the label to be rendered inside of the Tooltip. The label will use
+     * `aria-labelledby` and will fully describe the child node that is provided.
+     * This means that if you have text in the child node it will not be
+     * announced to the screen reader.
+     */
+    label: ReactNode;
+    /**
+     * Specify the duration in milliseconds to delay before hiding the tooltip
+     */
+    leaveDelayMs?: number;
+    /**
+     * Specify the size of the Button. Defaults to `md`.
+     */
+    size?: ButtonSize;
+    /**
+     * Specify an optional className to be added to your Tooltip wrapper
+     */
+    wrapperClasses?: string;
+}
+export declare function SideNavLinkPopover({ className, children, ...rest }: IconButtonProps): import("react/jsx-runtime").JSX.Element;
+export declare namespace SideNavLinkPopover {
+    var propTypes: {
+        /**
+         * Specify how the trigger should align with the tooltip
+         */
+        align: PropTypes.Requireable<string>;
+        /**
+         * **Experimental**: Will attempt to automatically align the tooltip
+         */
+        autoAlign: PropTypes.Requireable<boolean>;
+        /**
+         * Provide an icon or asset to be rendered inside of the IconButton
+         */
+        children: PropTypes.Requireable<PropTypes.ReactNodeLike>;
+        /**
+         * Specify an optional className to be added to your Button
+         */
+        className: PropTypes.Requireable<string>;
+        /**
+         * Determines whether the tooltip should close when inner content is activated (click, Enter or Space)
+         */
+        closeOnActivation: PropTypes.Requireable<boolean>;
+        /**
+         * Specify whether the tooltip should be open when it first renders
+         */
+        defaultOpen: PropTypes.Requireable<boolean>;
+        /**
+         * Specify whether the Button should be disabled, or not
+         */
+        disabled: PropTypes.Requireable<boolean>;
+        /**
+         * Specify the duration in milliseconds to delay before displaying the tooltip
+         */
+        enterDelayMs: PropTypes.Requireable<number>;
+        /**
+         * Optionally specify an href for your IconButton to become an `<a>` element
+         */
+        href: PropTypes.Requireable<string>;
+        /**
+         * Specify whether the IconButton is currently selected
+         */
+        isSelected: PropTypes.Requireable<boolean>;
+        /**
+         * Provide the label to be rendered inside of the Tooltip. The label will use
+         * `aria-labelledby` and will fully describe the child node that is provided.
+         * This means that if you have text in the child node it will not be
+         * announced to the screen reader.
+         */
+        label: PropTypes.Validator<NonNullable<PropTypes.ReactNodeLike>>;
+        /**
+         * Specify the duration in milliseconds to delay before hiding the tooltip
+         */
+        leaveDelayMs: PropTypes.Requireable<number>;
+        /**
+         * Specify the size of the Button. Defaults to `md`.
+         */
+        size: PropTypes.Requireable<string>;
+        /**
+         * Specify an optional className to be added to your Tooltip wrapper
+         */
+        wrapperClasses: PropTypes.Requireable<string>;
+    };
+}
+export default SideNavLinkPopover;

package/es/components/SideNavLinkPopover.js

@@ -0,0 +1,90 @@
+/**
+ * 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 from 'react';
+import { IconButton } from '@carbon/react';
+import { usePrefix } from '../internal/usePrefix.js';
+
+function SideNavLinkPopover(_ref) {
+  let {
+    className,
+    children,
+    ...rest
+  } = _ref;
+  const prefix = usePrefix();
+  return /*#__PURE__*/React.createElement(IconButton, _extends({
+    className: cx(className, `${prefix}--side-nav-link-popover`),
+    kind: "ghost"
+  }, rest), children);
+}
+SideNavLinkPopover.propTypes = {
+  /**
+   * Specify how the trigger should align with the tooltip
+   */
+  align: PropTypes.oneOf(['top', 'top-start', 'top-end', 'bottom', 'bottom-start', 'bottom-end', 'left', 'left-end', 'left-start', 'right', 'right-end', 'right-start']),
+  /**
+   * **Experimental**: Will attempt to automatically align the tooltip
+   */
+  autoAlign: PropTypes.bool,
+  /**
+   * Provide an icon or asset to be rendered inside of the IconButton
+   */
+  children: PropTypes.node,
+  /**
+   * Specify an optional className to be added to your Button
+   */
+  className: PropTypes.string,
+  /**
+   * Determines whether the tooltip should close when inner content is activated (click, Enter or Space)
+   */
+  closeOnActivation: PropTypes.bool,
+  /**
+   * Specify whether the tooltip should be open when it first renders
+   */
+  defaultOpen: PropTypes.bool,
+  /**
+   * Specify whether the Button should be disabled, or not
+   */
+  disabled: PropTypes.bool,
+  /**
+   * Specify the duration in milliseconds to delay before displaying the tooltip
+   */
+  enterDelayMs: PropTypes.number,
+  /**
+   * Optionally specify an href for your IconButton to become an `<a>` element
+   */
+  href: PropTypes.string,
+  /**
+   * Specify whether the IconButton is currently selected
+   */
+
+  isSelected: PropTypes.bool,
+  /**
+   * Provide the label to be rendered inside of the Tooltip. The label will use
+   * `aria-labelledby` and will fully describe the child node that is provided.
+   * This means that if you have text in the child node it will not be
+   * announced to the screen reader.
+   */
+  label: PropTypes.node.isRequired,
+  /**
+   * Specify the duration in milliseconds to delay before hiding the tooltip
+   */
+  leaveDelayMs: PropTypes.number,
+  /**
+   * Specify the size of the Button. Defaults to `md`.
+   */
+  size: PropTypes.oneOf(['sm', 'md', 'lg']),
+  /**
+   * Specify an optional className to be added to your Tooltip wrapper
+   */
+  wrapperClasses: PropTypes.string
+};
+
+export { SideNavLinkPopover, SideNavLinkPopover as default };

package/es/components/SideNavMenu.js

@@ -96,23 +96,6 @@ const SideNavMenu = /*#__PURE__*/React.forwardRef(function SideNavMenu(_ref, ref
 
     // if depth is more than 0, that means its nested, thus we set treeview mode
     setIsTreeview?.(true);
-    if (isTreeview) {
-      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`;
-      }
-    }
   }, [isTreeview]);
 
   /**

package/es/components/SideNavMenuItem.d.ts

@@ -4,7 +4,7 @@
  * 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 React, { ElementType, ComponentProps, ComponentType } from 'react';
 import Link from './Link';
 export interface SideNavMenuItemProps extends ComponentProps<typeof Link> {
     /**
@@ -15,11 +15,6 @@ export interface SideNavMenuItemProps extends ComponentProps<typeof Link> {
      * 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
@@ -34,5 +29,9 @@ export interface SideNavMenuItemProps extends ComponentProps<typeof Link> {
      * Optional component to render instead of default Link
      */
     as?: ElementType;
+    /**
+     * Provide an icon to render in the side navigation link. Should be a React class.
+     */
+    renderIcon?: ComponentType;
 }
 export declare const SideNavMenuItem: React.ForwardRefExoticComponent<Omit<SideNavMenuItemProps, "ref"> & React.RefAttributes<HTMLElement>>;

package/es/components/SideNavMenuItem.js

@@ -8,11 +8,10 @@
 import { extends as _extends } from '../_virtual/_rollupPluginBabelHelpers.js';
 import cx from '../_virtual/index.js';
 import PropTypes from 'prop-types';
-import React, { useContext, useRef, useEffect } from 'react';
-import { SideNavLinkText } from '@carbon/react';
+import React, { useContext } from 'react';
+import { SideNavIcon, SideNavLinkText } from '@carbon/react';
 import Link from './Link.js';
 import { usePrefix } from '../internal/usePrefix.js';
-import { useMergedRefs } from '../internal/useMergedRefs.js';
 import { SideNavContext } from './SideNav.js';
 
 const SideNavMenuItem = /*#__PURE__*/React.forwardRef(function SideNavMenuItem(props, ref) {
@@ -20,30 +19,19 @@ const SideNavMenuItem = /*#__PURE__*/React.forwardRef(function SideNavMenuItem(p
   const {
     children,
     className: customClassName,
-    depth: propDepth,
     as: Component = Link,
     isActive,
+    renderIcon: IconElement,
     ...rest
   } = props;
   const {
     isTreeview
   } = useContext(SideNavContext);
   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`;
-    }
-  }, [isTreeview]);
   return /*#__PURE__*/React.createElement("li", {
     className: className
   }, /*#__PURE__*/React.createElement(Component, _extends({}, rest, {
@@ -51,11 +39,17 @@ const SideNavMenuItem = /*#__PURE__*/React.forwardRef(function SideNavMenuItem(p
     role: isTreeview ? 'treeitem' : undefined,
     className: linkClassName,
     tabIndex: isTreeview ? -1 : 0,
-    ref: itemRef
-  }), /*#__PURE__*/React.createElement(SideNavLinkText, null, children)));
+    ref: ref
+  }), IconElement && /*#__PURE__*/React.createElement(SideNavIcon, {
+    small: true
+  }, /*#__PURE__*/React.createElement(IconElement, null)), /*#__PURE__*/React.createElement(SideNavLinkText, null, children)));
 });
 SideNavMenuItem.displayName = 'SideNavMenuItem';
 SideNavMenuItem.propTypes = {
+  /**
+   * Optional component to render instead of default Link
+   */
+  as: PropTypes.elementType,
   /**
    * Specify the children to be rendered inside of the `SideNavMenuItem`
    */
@@ -64,11 +58,6 @@ SideNavMenuItem.propTypes = {
    * 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`
    */
@@ -80,9 +69,9 @@ SideNavMenuItem.propTypes = {
    */
   isActive: PropTypes.bool,
   /**
-   * Optional component to render instead of default Link
+   * Provide an icon to render in the side navigation link. Should be a React class.
    */
-  as: PropTypes.elementType
+  renderIcon: PropTypes.oneOfType([PropTypes.func, PropTypes.object])
 };
 
 export { SideNavMenuItem };

package/es/index.d.ts

@@ -8,6 +8,8 @@
  */
 export { SideNav, SIDE_NAV_TYPE } from './components/SideNav.js';
 export { SideNavItems } from './components/SideNavItems.js';
+export { SideNavLink } from './components/SideNavLink.js';
+export { SideNavLinkPopover } from './components/SideNavLinkPopover.js';
 export { SideNavMenu } from './components/SideNavMenu.js';
 export { SideNavMenuItem } from './components/SideNavMenuItem.js';
 export { HeaderPanel } from './components/HeaderPanel';

package/es/index.js

@@ -7,6 +7,8 @@
 
 export { SIDE_NAV_TYPE, SideNav } from './components/SideNav.js';
 export { SideNavItems } from './components/SideNavItems.js';
+export { SideNavLink } from './components/SideNavLink.js';
+export { SideNavLinkPopover } from './components/SideNavLinkPopover.js';
 export { SideNavMenu } from './components/SideNavMenu.js';
 export { SideNavMenuItem } from './components/SideNavMenuItem.js';
 export { HeaderPanel } from './components/HeaderPanel.js';

package/lib/components/SideNav.js

@@ -160,7 +160,9 @@ function SideNavRenderFunction(_ref, ref) {
    */
   function parentSideNavMenu(node) {
     const parentNode = node.parentElement?.closest(`.${prefix}--side-nav__item`);
-    if (parentNode) return parentNode;
+    if (parentNode) {
+      return parentNode;
+    }
     return node;
   }
   if (addFocusListeners) {
@@ -342,9 +344,9 @@ function SideNavRenderFunction(_ref, ref) {
   };
   return /*#__PURE__*/React.createElement(SideNavContext.Provider, {
     value: {
+      expanded,
       isRail,
       navType,
-      expanded: expanded,
       isTreeview: internalIsTreeview,
       setIsTreeview
     }

package/lib/components/SideNavLink.d.ts

@@ -0,0 +1,57 @@
+/**
+ * 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 { ComponentType, ElementType, ForwardedRef, ReactNode, WeakValidationMap } from 'react';
+import { LinkProps } from './Link';
+export type SideNavLinkProps<E extends ElementType> = LinkProps<E> & {
+    /**
+     * Required props for the accessibility label
+     */
+    'aria-label'?: string;
+    /**
+     * Required props for the accessibility label
+     */
+    'aria-labelledby'?: string;
+    /**
+     * Specify the text content for the link
+     */
+    children?: ReactNode;
+    /**
+     * Provide an optional class to be applied to the containing node
+     */
+    className?: string;
+    /**
+     * Specify whether the link is the current page
+     */
+    isActive?: boolean;
+    /**
+     * 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;
+    /**
+     * Specify if this is a large variation of the SideNavLink
+     */
+    large?: boolean;
+    /**
+     * Provide an icon to render in the side navigation link. Should be a React class.
+     */
+    renderIcon?: ComponentType;
+    /**
+     * Optional prop to specify the tabIndex of the button. If undefined, it will be applied default validation
+     */
+    tabIndex?: number;
+};
+export interface SideNavLinkComponent {
+    <E extends ElementType = 'a'>(props: SideNavLinkProps<E> & {
+        ref?: ForwardedRef<ElementType>;
+    }): JSX.Element | null;
+    displayName?: string;
+    propTypes?: WeakValidationMap<SideNavLinkProps<any>>;
+}
+export declare const SideNavLink: SideNavLinkComponent;
+export declare const createCustomSideNavLink: (element: any) => (props: any) => import("react/jsx-runtime").JSX.Element;
+export default SideNavLink;

package/lib/components/SideNavLink.js

@@ -0,0 +1,97 @@
+/**
+ * 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';
+
+Object.defineProperty(exports, '__esModule', { value: true });
+
+var _rollupPluginBabelHelpers = require('../_virtual/_rollupPluginBabelHelpers.js');
+var index = require('../_virtual/index.js');
+var PropTypes = require('prop-types');
+var React = require('react');
+var Link = require('./Link.js');
+var react = require('@carbon/react');
+var usePrefix = require('../internal/usePrefix.js');
+var SideNav = require('./SideNav.js');
+var SideNavLinkPopover = require('./SideNavLinkPopover.js');
+
+const SideNavLink = /*#__PURE__*/React.forwardRef(function SideNavLink(_ref, ref) {
+  let {
+    children,
+    className: customClassName,
+    renderIcon: IconElement,
+    isActive,
+    isSideNavExpanded,
+    large = false,
+    tabIndex,
+    ...rest
+  } = _ref;
+  const {
+    expanded,
+    isRail,
+    navType
+  } = React.useContext(SideNav.SideNavContext);
+  const prefix = usePrefix.usePrefix();
+  const className = index.default({
+    [`${prefix}--side-nav__link`]: true,
+    [`${prefix}--side-nav__link--current`]: isActive,
+    [customClassName]: !!customClassName
+  });
+  const SideNavLinkIcon = IconElement && /*#__PURE__*/React.createElement(react.SideNavIcon, {
+    small: true
+  }, /*#__PURE__*/React.createElement(IconElement, null));
+  if (!expanded && navType === 'panel') {
+    return /*#__PURE__*/React.createElement(SideNavLinkPopover.SideNavLinkPopover, _rollupPluginBabelHelpers.extends({
+      align: "right",
+      label: children
+    }, rest), SideNavLinkIcon);
+  }
+  return /*#__PURE__*/React.createElement(react.SideNavItem, {
+    large: large
+  }, /*#__PURE__*/React.createElement(Link.default, _rollupPluginBabelHelpers.extends({}, rest, {
+    className: className,
+    ref: ref,
+    tabIndex: tabIndex === undefined ? !isSideNavExpanded && !isRail ? -1 : 0 : tabIndex
+  }), SideNavLinkIcon, /*#__PURE__*/React.createElement(react.SideNavLinkText, null, children)));
+});
+SideNavLink.displayName = 'SideNavLink';
+SideNavLink.propTypes = {
+  ...Link.LinkPropTypes,
+  /**
+   * Specify the text content for the link
+   */
+  children: PropTypes.node,
+  /**
+   * Provide an optional class to be applied to the containing node
+   */
+  className: PropTypes.string,
+  /**
+   * Specify whether the link is 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 SideNavLink
+   */
+  large: PropTypes.bool,
+  /**
+   * Provide an icon to render in the side navigation link. Should be a React class.
+   */
+  // @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
+};
+
+exports.SideNavLink = SideNavLink;
+exports.default = SideNavLink;

package/lib/components/SideNavLinkPopover.d.ts

@@ -0,0 +1,135 @@
+/**
+ * Copyright IBM Corp. 2016, 2023
+ *
+ * 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 PropTypes from 'prop-types';
+import React, { ReactNode } from 'react';
+import { IconButtonAlignment, ButtonSize } from '@carbon/react';
+interface IconButtonProps extends React.ButtonHTMLAttributes<HTMLButtonElement> {
+    /**
+     * Specify how the trigger should align with the tooltip
+     */
+    align?: IconButtonAlignment;
+    /**
+     * **Experimental**: Will attempt to automatically align the tooltip
+     */
+    autoAlign?: boolean;
+    /**
+     * Optionally specify an href for your IconButton to become an `<a>` element
+     */
+    href?: string;
+    /**
+     * Provide an icon or asset to be rendered inside of the IconButton
+     */
+    children?: ReactNode;
+    /**
+     * Specify an optional className to be added to your Button
+     */
+    className?: string;
+    /**
+     * Determines whether the tooltip should close when inner content is activated (click, Enter or Space)
+     */
+    closeOnActivation?: boolean;
+    /**
+     * Specify whether the tooltip should be open when it first renders
+     */
+    defaultOpen?: boolean;
+    /**
+     * Specify whether the Button should be disabled, or not
+     */
+    disabled?: boolean;
+    /**
+     * Specify the duration in milliseconds to delay before displaying the tooltip
+     */
+    enterDelayMs?: number;
+    /**
+     * Specify whether the IconButton is currently selected
+     */
+    isSelected?: boolean;
+    /**
+     * Provide the label to be rendered inside of the Tooltip. The label will use
+     * `aria-labelledby` and will fully describe the child node that is provided.
+     * This means that if you have text in the child node it will not be
+     * announced to the screen reader.
+     */
+    label: ReactNode;
+    /**
+     * Specify the duration in milliseconds to delay before hiding the tooltip
+     */
+    leaveDelayMs?: number;
+    /**
+     * Specify the size of the Button. Defaults to `md`.
+     */
+    size?: ButtonSize;
+    /**
+     * Specify an optional className to be added to your Tooltip wrapper
+     */
+    wrapperClasses?: string;
+}
+export declare function SideNavLinkPopover({ className, children, ...rest }: IconButtonProps): import("react/jsx-runtime").JSX.Element;
+export declare namespace SideNavLinkPopover {
+    var propTypes: {
+        /**
+         * Specify how the trigger should align with the tooltip
+         */
+        align: PropTypes.Requireable<string>;
+        /**
+         * **Experimental**: Will attempt to automatically align the tooltip
+         */
+        autoAlign: PropTypes.Requireable<boolean>;
+        /**
+         * Provide an icon or asset to be rendered inside of the IconButton
+         */
+        children: PropTypes.Requireable<PropTypes.ReactNodeLike>;
+        /**
+         * Specify an optional className to be added to your Button
+         */
+        className: PropTypes.Requireable<string>;
+        /**
+         * Determines whether the tooltip should close when inner content is activated (click, Enter or Space)
+         */
+        closeOnActivation: PropTypes.Requireable<boolean>;
+        /**
+         * Specify whether the tooltip should be open when it first renders
+         */
+        defaultOpen: PropTypes.Requireable<boolean>;
+        /**
+         * Specify whether the Button should be disabled, or not
+         */
+        disabled: PropTypes.Requireable<boolean>;
+        /**
+         * Specify the duration in milliseconds to delay before displaying the tooltip
+         */
+        enterDelayMs: PropTypes.Requireable<number>;
+        /**
+         * Optionally specify an href for your IconButton to become an `<a>` element
+         */
+        href: PropTypes.Requireable<string>;
+        /**
+         * Specify whether the IconButton is currently selected
+         */
+        isSelected: PropTypes.Requireable<boolean>;
+        /**
+         * Provide the label to be rendered inside of the Tooltip. The label will use
+         * `aria-labelledby` and will fully describe the child node that is provided.
+         * This means that if you have text in the child node it will not be
+         * announced to the screen reader.
+         */
+        label: PropTypes.Validator<NonNullable<PropTypes.ReactNodeLike>>;
+        /**
+         * Specify the duration in milliseconds to delay before hiding the tooltip
+         */
+        leaveDelayMs: PropTypes.Requireable<number>;
+        /**
+         * Specify the size of the Button. Defaults to `md`.
+         */
+        size: PropTypes.Requireable<string>;
+        /**
+         * Specify an optional className to be added to your Tooltip wrapper
+         */
+        wrapperClasses: PropTypes.Requireable<string>;
+    };
+}
+export default SideNavLinkPopover;

package/lib/components/SideNavLinkPopover.js

@@ -0,0 +1,95 @@
+/**
+ * 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';
+
+Object.defineProperty(exports, '__esModule', { value: true });
+
+var _rollupPluginBabelHelpers = require('../_virtual/_rollupPluginBabelHelpers.js');
+var index = require('../_virtual/index.js');
+var PropTypes = require('prop-types');
+var React = require('react');
+var react = require('@carbon/react');
+var usePrefix = require('../internal/usePrefix.js');
+
+function SideNavLinkPopover(_ref) {
+  let {
+    className,
+    children,
+    ...rest
+  } = _ref;
+  const prefix = usePrefix.usePrefix();
+  return /*#__PURE__*/React.createElement(react.IconButton, _rollupPluginBabelHelpers.extends({
+    className: index.default(className, `${prefix}--side-nav-link-popover`),
+    kind: "ghost"
+  }, rest), children);
+}
+SideNavLinkPopover.propTypes = {
+  /**
+   * Specify how the trigger should align with the tooltip
+   */
+  align: PropTypes.oneOf(['top', 'top-start', 'top-end', 'bottom', 'bottom-start', 'bottom-end', 'left', 'left-end', 'left-start', 'right', 'right-end', 'right-start']),
+  /**
+   * **Experimental**: Will attempt to automatically align the tooltip
+   */
+  autoAlign: PropTypes.bool,
+  /**
+   * Provide an icon or asset to be rendered inside of the IconButton
+   */
+  children: PropTypes.node,
+  /**
+   * Specify an optional className to be added to your Button
+   */
+  className: PropTypes.string,
+  /**
+   * Determines whether the tooltip should close when inner content is activated (click, Enter or Space)
+   */
+  closeOnActivation: PropTypes.bool,
+  /**
+   * Specify whether the tooltip should be open when it first renders
+   */
+  defaultOpen: PropTypes.bool,
+  /**
+   * Specify whether the Button should be disabled, or not
+   */
+  disabled: PropTypes.bool,
+  /**
+   * Specify the duration in milliseconds to delay before displaying the tooltip
+   */
+  enterDelayMs: PropTypes.number,
+  /**
+   * Optionally specify an href for your IconButton to become an `<a>` element
+   */
+  href: PropTypes.string,
+  /**
+   * Specify whether the IconButton is currently selected
+   */
+
+  isSelected: PropTypes.bool,
+  /**
+   * Provide the label to be rendered inside of the Tooltip. The label will use
+   * `aria-labelledby` and will fully describe the child node that is provided.
+   * This means that if you have text in the child node it will not be
+   * announced to the screen reader.
+   */
+  label: PropTypes.node.isRequired,
+  /**
+   * Specify the duration in milliseconds to delay before hiding the tooltip
+   */
+  leaveDelayMs: PropTypes.number,
+  /**
+   * Specify the size of the Button. Defaults to `md`.
+   */
+  size: PropTypes.oneOf(['sm', 'md', 'lg']),
+  /**
+   * Specify an optional className to be added to your Tooltip wrapper
+   */
+  wrapperClasses: PropTypes.string
+};
+
+exports.SideNavLinkPopover = SideNavLinkPopover;
+exports.default = SideNavLinkPopover;

package/lib/components/SideNavMenu.js

@@ -98,23 +98,6 @@ const SideNavMenu = /*#__PURE__*/React.forwardRef(function SideNavMenu(_ref, ref
 
     // if depth is more than 0, that means its nested, thus we set treeview mode
     setIsTreeview?.(true);
-    if (isTreeview) {
-      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`;
-      }
-    }
   }, [isTreeview]);
 
   /**

package/lib/components/SideNavMenuItem.d.ts

@@ -4,7 +4,7 @@
  * 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 React, { ElementType, ComponentProps, ComponentType } from 'react';
 import Link from './Link';
 export interface SideNavMenuItemProps extends ComponentProps<typeof Link> {
     /**
@@ -15,11 +15,6 @@ export interface SideNavMenuItemProps extends ComponentProps<typeof Link> {
      * 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
@@ -34,5 +29,9 @@ export interface SideNavMenuItemProps extends ComponentProps<typeof Link> {
      * Optional component to render instead of default Link
      */
     as?: ElementType;
+    /**
+     * Provide an icon to render in the side navigation link. Should be a React class.
+     */
+    renderIcon?: ComponentType;
 }
 export declare const SideNavMenuItem: React.ForwardRefExoticComponent<Omit<SideNavMenuItemProps, "ref"> & React.RefAttributes<HTMLElement>>;

package/lib/components/SideNavMenuItem.js

@@ -14,7 +14,6 @@ var React = require('react');
 var react = require('@carbon/react');
 var Link = require('./Link.js');
 var usePrefix = require('../internal/usePrefix.js');
-var useMergedRefs = require('../internal/useMergedRefs.js');
 var SideNav = require('./SideNav.js');
 
 const SideNavMenuItem = /*#__PURE__*/React.forwardRef(function SideNavMenuItem(props, ref) {
@@ -22,30 +21,19 @@ const SideNavMenuItem = /*#__PURE__*/React.forwardRef(function SideNavMenuItem(p
   const {
     children,
     className: customClassName,
-    depth: propDepth,
     as: Component = Link.default,
     isActive,
+    renderIcon: IconElement,
     ...rest
   } = props;
   const {
     isTreeview
   } = React.useContext(SideNav.SideNavContext);
   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`;
-    }
-  }, [isTreeview]);
   return /*#__PURE__*/React.createElement("li", {
     className: className
   }, /*#__PURE__*/React.createElement(Component, _rollupPluginBabelHelpers.extends({}, rest, {
@@ -53,11 +41,17 @@ const SideNavMenuItem = /*#__PURE__*/React.forwardRef(function SideNavMenuItem(p
     role: isTreeview ? 'treeitem' : undefined,
     className: linkClassName,
     tabIndex: isTreeview ? -1 : 0,
-    ref: itemRef
-  }), /*#__PURE__*/React.createElement(react.SideNavLinkText, null, children)));
+    ref: ref
+  }), IconElement && /*#__PURE__*/React.createElement(react.SideNavIcon, {
+    small: true
+  }, /*#__PURE__*/React.createElement(IconElement, null)), /*#__PURE__*/React.createElement(react.SideNavLinkText, null, children)));
 });
 SideNavMenuItem.displayName = 'SideNavMenuItem';
 SideNavMenuItem.propTypes = {
+  /**
+   * Optional component to render instead of default Link
+   */
+  as: PropTypes.elementType,
   /**
    * Specify the children to be rendered inside of the `SideNavMenuItem`
    */
@@ -66,11 +60,6 @@ SideNavMenuItem.propTypes = {
    * 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`
    */
@@ -82,9 +71,9 @@ SideNavMenuItem.propTypes = {
    */
   isActive: PropTypes.bool,
   /**
-   * Optional component to render instead of default Link
+   * Provide an icon to render in the side navigation link. Should be a React class.
    */
-  as: PropTypes.elementType
+  renderIcon: PropTypes.oneOfType([PropTypes.func, PropTypes.object])
 };
 
 exports.SideNavMenuItem = SideNavMenuItem;

package/lib/index.d.ts

@@ -8,6 +8,8 @@
  */
 export { SideNav, SIDE_NAV_TYPE } from './components/SideNav.js';
 export { SideNavItems } from './components/SideNavItems.js';
+export { SideNavLink } from './components/SideNavLink.js';
+export { SideNavLinkPopover } from './components/SideNavLinkPopover.js';
 export { SideNavMenu } from './components/SideNavMenu.js';
 export { SideNavMenuItem } from './components/SideNavMenuItem.js';
 export { HeaderPanel } from './components/HeaderPanel';

package/lib/index.js

@@ -9,6 +9,8 @@
 
 var SideNav = require('./components/SideNav.js');
 var SideNavItems = require('./components/SideNavItems.js');
+var SideNavLink = require('./components/SideNavLink.js');
+var SideNavLinkPopover = require('./components/SideNavLinkPopover.js');
 var SideNavMenu = require('./components/SideNavMenu.js');
 var SideNavMenuItem = require('./components/SideNavMenuItem.js');
 var HeaderPanel = require('./components/HeaderPanel.js');
@@ -18,6 +20,8 @@ var HeaderPanel = require('./components/HeaderPanel.js');
 exports.SIDE_NAV_TYPE = SideNav.SIDE_NAV_TYPE;
 exports.SideNav = SideNav.SideNav;
 exports.SideNavItems = SideNavItems.SideNavItems;
+exports.SideNavLink = SideNavLink.SideNavLink;
+exports.SideNavLinkPopover = SideNavLinkPopover.SideNavLinkPopover;
 exports.SideNavMenu = SideNavMenu.SideNavMenu;
 exports.SideNavMenuItem = SideNavMenuItem.SideNavMenuItem;
 exports.HeaderPanel = HeaderPanel.HeaderPanel;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@carbon-labs/react-ui-shell",
-  "version": "0.19.0",
+  "version": "0.21.0",
   "publishConfig": {
     "access": "public",
     "provenance": true
@@ -33,5 +33,5 @@
   "dependencies": {
     "@ibm/telemetry-js": "^1.9.1"
   },
-  "gitHead": "91dde120d99da5e4454f7411733aeabe037e222f"
+  "gitHead": "30877a143d6909d98efd0ec5e6aef7fbf2b074be"
 }

package/scss/styles/_side-nav.scss

@@ -38,6 +38,7 @@ div:has(.#{$prefix}--header)
 //----------------------------------------------------------------------------
 // Treeview Side-nav
 //----------------------------------------------------------------------------
+
 .#{$prefix}--side-nav__icon:not(.#{$prefix}--side-nav__submenu-chevron) {
   margin-inline-end: $spacing-05;
 }
@@ -62,10 +63,69 @@ div:has(.#{$prefix}--header)
   }
 }
 
+// SideNavMenu
+// Level 2
+// without icon
+.#{$prefix}--side-nav__submenu
+  + .#{$prefix}--side-nav__menu
+  > .#{$prefix}--side-nav__item
+  .#{$prefix}--side-nav__submenu {
+  padding-inline-start: $spacing-10;
+}
+
+// with icon
+.#{$prefix}--side-nav__submenu
+  + .#{$prefix}--side-nav__menu
+  > .#{$prefix}--side-nav__item--icon
+  .#{$prefix}--side-nav__submenu {
+  padding-inline-start: $spacing-09;
+}
+
+// Nested SideNavMenuItem
+// Level 2
+// without icon
+.#{$prefix}--side-nav__item.#{$prefix}--side-nav__item--icon
+  a.#{$prefix}--side-nav__link {
+  padding-inline-start: $spacing-10;
+}
+
+// with icon
+.#{$prefix}--side-nav__item.#{$prefix}--side-nav__item--icon
+  a.#{$prefix}--side-nav__link:has(.#{$prefix}--side-nav__icon) {
+  padding-inline-start: $spacing-09;
+}
+
+// Level 3
+// without icon parent
+.#{$prefix}--side-nav__menu
+  .#{$prefix}--side-nav__menu
+  a.#{$prefix}--side-nav__link {
+  padding-inline-start: $spacing-11;
+}
+
+// with icon parent
+.#{$prefix}--side-nav__menu
+  .#{$prefix}--side-nav__item.#{$prefix}--side-nav__item--icon
+  a.#{$prefix}--side-nav__link {
+  padding-inline-start: $spacing-12;
+}
+
+//----------------------------------------------------------------------------
 // Side-nav Panel
 //----------------------------------------------------------------------------
 .#{$prefix}--side-nav--panel {
   z-index: 7999; /* needs to be below header */
+  overflow: visible;
+
+  .#{$prefix}--side-nav__items {
+    display: flex;
+    flex-direction: column;
+  }
+
+  .#{$prefix}--side-nav__items,
+  .#{$prefix}--side-nav__items:hover {
+    overflow: visible;
+  }
 
   .#{$prefix}--side-nav__icon:not(.#{$prefix}--side-nav__submenu-chevron) {
     margin-inline-end: $spacing-05;
@@ -82,6 +142,7 @@ div:has(.#{$prefix}--header)
     padding-inline-start: $spacing-10;
   }
 
+  // Side Nav Toggle
   .#{$prefix}--side-nav__toggle {
     @include button-reset.reset($width: true);
     @include type-style('heading-compact-01');
@@ -110,4 +171,15 @@ div:has(.#{$prefix}--header)
 
     text-align: start;
   }
+
+  // Side Nav Link Popover
+  .#{$prefix}--side-nav-link-popover.#{$prefix}--btn--icon-only {
+    padding: 0;
+    block-size: $spacing-07;
+    min-block-size: initial;
+
+    .#{$prefix}--side-nav__icon:not(.#{$prefix}--side-nav__submenu-chevron) {
+      margin-inline-end: 0;
+    }
+  }
 }