@carbon-labs/react-ui-shell 0.72.0 → 0.74.0

package/es/components/Profile.js

@@ -19,14 +19,15 @@ const Profile = /*#__PURE__*/React__default.forwardRef(function Profile({
   children,
   renderIcon: IconElement,
   ...rest
-}) {
+}, ref) {
   const prefix = usePrefix();
   const className = cx({
     [`${prefix}--profile`]: true,
     [customClassName]: !!customClassName
   });
   return /*#__PURE__*/React__default.createElement(HeaderPopover, _extends({
-    align: "bottom-right",
+    ref: ref,
+    align: "bottom-end",
     className: className
   }, rest), /*#__PURE__*/React__default.createElement(HeaderPopoverButton, {
     align: "bottom",
@@ -58,13 +59,14 @@ const ProfileUserInfo = /*#__PURE__*/React__default.forwardRef(function ProfileU
   name,
   email,
   ...rest
-}) {
+}, ref) {
   const prefix = usePrefix();
   const className = cx({
     [`${prefix}--profile-user-info`]: true,
     [customClassName]: !!customClassName
   });
   return /*#__PURE__*/React__default.createElement("div", {
+    ref: ref,
     className: className
   }, /*#__PURE__*/React__default.createElement(UserAvatar, _extends({
     size: "lg",
@@ -95,13 +97,14 @@ ProfileUserInfo.propTypes = {
 const ProfileReadOnly = /*#__PURE__*/React__default.forwardRef(function ProfileReadOnly({
   className: customClassName,
   items
-}) {
+}, ref) {
   const prefix = usePrefix();
   const className = cx({
     [`${prefix}--profile-read-only`]: true,
     [customClassName]: !!customClassName
   });
   return /*#__PURE__*/React__default.createElement("div", {
+    ref: ref,
     className: className
   }, items?.map((item, index) => /*#__PURE__*/React__default.createElement("div", {
     className: `${prefix}--profile-read-only__items`,

package/es/components/SideNav.d.ts

@@ -9,12 +9,14 @@ import { TranslateWithId } from '../types/common';
 export declare enum SIDE_NAV_TYPE {
     DEFAULT = "default",
     RAIL = "rail",
-    PANEL = "panel"
+    RAIL_PANEL = "panel"
 }
 export type TranslationKey = keyof typeof translationIds;
 export declare const translationIds: {
     readonly 'collapse.sidenav': "collapse.sidenav";
     readonly 'expand.sidenav': "expand.sidenav";
+    readonly 'enable.autoexpand': "enable.autoexpand";
+    readonly 'disable.autoexpand': "disable.autoexpand";
 };
 export interface SideNavProps extends ComponentProps<'nav'>, TranslateWithId<TranslationKey> {
     expanded?: boolean;
@@ -38,6 +40,7 @@ export interface SideNavProps extends ComponentProps<'nav'>, TranslateWithId<Tra
     isTreeview?: boolean;
 }
 interface SideNavContextData {
+    autoExpand?: boolean;
     expanded?: boolean;
     isRail?: boolean;
     navType?: SIDE_NAV_TYPE;

package/es/components/SideNav.js

@@ -6,7 +6,7 @@
  */
 
 import { extends as _extends } from '../_virtual/_rollupPluginBabelHelpers.js';
-import React__default, { createContext, useState, useRef, isValidElement, useEffect } from 'react';
+import React__default, { createContext, useState, useRef, isValidElement, useCallback, useEffect } from 'react';
 import cx from 'classnames';
 import PropTypes from 'prop-types';
 import { AriaLabelPropType } from '../prop-types/AriaPropTypes.js';
@@ -19,22 +19,28 @@ import { useWindowEvent } from '../internal/useEvent.js';
 import { useDelayedState } from '../internal/useDelayedState.js';
 import { breakpoints } from '../node_modules/@carbon/layout/es/index.js';
 import { useMatchMedia } from '../internal/useMatchMedia.js';
-import { SidePanelClose, SidePanelOpen } from '@carbon/icons-react';
+import { PinFilled, Pin, SidePanelClose, SidePanelOpen } from '@carbon/icons-react';
 import { SideNavToggle } from './SideNavToggle.js';
+import { SideNavDivider } from '@carbon/react';
 
+var _SideNavDivider;
 let SIDE_NAV_TYPE = /*#__PURE__*/function (SIDE_NAV_TYPE) {
   SIDE_NAV_TYPE["DEFAULT"] = "default";
   SIDE_NAV_TYPE["RAIL"] = "rail";
-  SIDE_NAV_TYPE["PANEL"] = "panel";
+  SIDE_NAV_TYPE["RAIL_PANEL"] = "panel";
   return SIDE_NAV_TYPE;
 }({});
 const translationIds = {
   'collapse.sidenav': 'collapse.sidenav',
-  'expand.sidenav': 'expand.sidenav'
+  'expand.sidenav': 'expand.sidenav',
+  'enable.autoexpand': 'enable.autoexpand',
+  'disable.autoexpand': 'disable.autoexpand'
 };
 const defaultTranslations = {
-  [translationIds['collapse.sidenav']]: 'Collapse',
-  [translationIds['expand.sidenav']]: 'Expand'
+  [translationIds['collapse.sidenav']]: 'Unpin',
+  [translationIds['expand.sidenav']]: 'Pin open',
+  [translationIds['enable.autoexpand']]: 'Enable auto-expand',
+  [translationIds['disable.autoexpand']]: 'Disable auto-expand'
 };
 const defaultTranslateWithId = id => defaultTranslations[id];
 const SideNavContext = /*#__PURE__*/createContext({});
@@ -69,13 +75,16 @@ function SideNavRenderFunction({
   const {
     current: controlled
   } = useRef(expandedProp !== undefined);
+  const [autoExpand, setAutoExpand] = useState(false);
   const [expandedState, setExpandedState] = useDelayedState(defaultExpanded);
   const [expandedViaHoverState, setExpandedViaHoverState] = useDelayedState(defaultExpanded);
+  const [pinned, setPinned] = useState(false);
   const expanded = controlled ? expandedProp : expandedState;
   const sideNavRef = useRef(null);
   const navRef = useMergedRefs([sideNavRef, ref]);
   const [currentPrimaryMenu, setCurrentPrimaryMenu] = useState();
-  const sideNavToggleText = expandedState ? t('collapse.sidenav') : t('expand.sidenav');
+  const pinText = pinned ? t('collapse.sidenav') : t('expand.sidenav');
+  const autoExpandText = autoExpand ? t('disable.autoexpand') : t('enable.autoexpand');
   const handleToggle = (event, value = !expanded) => {
     if (!controlled) {
       setExpandedState(value, enterDelayMs);
@@ -96,8 +105,9 @@ function SideNavRenderFunction({
     [`${prefix}--side-nav--expanded`]: expanded || expandedViaHoverState,
     [`${prefix}--side-nav--collapsed`]: !expanded && isFixedNav,
     [`${prefix}--side-nav--hide-rail-breakpoint-down-${hideRailBreakpointDown}`]: hideRailBreakpointDown,
-    [`${prefix}--side-nav--rail`]: isRail,
-    [`${prefix}--side-nav--panel`]: navType === SIDE_NAV_TYPE.PANEL,
+    [`${prefix}--side-nav--rail`]: isRail || autoExpand,
+    [`${prefix}--side-nav--panel`]: navType === SIDE_NAV_TYPE.RAIL_PANEL,
+    [`${prefix}--side-nav--pinned`]: pinned,
     [`${prefix}--side-nav--ux`]: isChildOfHeader,
     [`${prefix}--side-nav--hidden`]: !isPersistent,
     [`${prefix}--side-nav--collapsible`]: isCollapsible,
@@ -128,6 +138,15 @@ function SideNavRenderFunction({
     return child;
   });
   const eventHandlers = {};
+  const resetNodeTabIndices = useCallback(() => {
+    const items = sideNavRef?.current?.querySelectorAll('[tabIndex="0"]') ?? [];
+    items.forEach(item => {
+      if (item.classList.contains(`${prefix}--side-nav__toggle`) || item.classList.contains(`${prefix}--side-nav__back-button`) || item.closest(`.${prefix}--side-nav__slot-item`) || item.classList.contains(`${prefix}--side-nav__link`) && item.closest('ul')?.getAttribute('aria-label') === ariaLabel) {
+        return;
+      }
+      item.tabIndex = -1;
+    });
+  }, [prefix, ariaLabel]);
   const treeWalkerRef = useRef(null);
   useEffect(() => {
     if (internalIsTreeview) {
@@ -147,7 +166,7 @@ function SideNavRenderFunction({
       });
       resetNodeTabIndices();
     }
-  }, [prefix, internalIsTreeview]);
+  }, [prefix, internalIsTreeview, resetNodeTabIndices]);
   const smMediaQuery = `(min-width: ${breakpoints.sm.width})`;
   const isSm = useMatchMedia(smMediaQuery);
   useEffect(() => {
@@ -156,7 +175,7 @@ function SideNavRenderFunction({
       const slotElement = sideNavRef?.current.querySelector(`.${prefix}--side-nav__slot`);
       const firstElement = sideNavRef?.current?.querySelector('a, button');
       const currentElement = sideNavRef?.current?.querySelector(`.cds--side-nav__link--current`);
-      if (navType == SIDE_NAV_TYPE.PANEL || expanded) {
+      if (navType == SIDE_NAV_TYPE.RAIL_PANEL || expanded) {
         if (isSm && backButton) {
           backButton.tabIndex = 0;
           const firstElementAfterBack = backButton.nextElementSibling?.querySelector('a, button');
@@ -176,7 +195,7 @@ function SideNavRenderFunction({
         }
       }
     }
-  }, [expanded]);
+  }, [expanded, currentPrimaryMenu, isSm, navType, prefix]);
 
   /**
    * Returns the parent SideNavMenu, if node is actually inside one.
@@ -192,12 +211,12 @@ function SideNavRenderFunction({
   }
   if (addFocusListeners) {
     eventHandlers.onFocus = event => {
-      if (!event.currentTarget.contains(event.relatedTarget) && isRail) {
+      if (!event.currentTarget.contains(event.relatedTarget) && (isRail || autoExpand)) {
         handleToggle(event, true);
       }
     };
     eventHandlers.onBlur = event => {
-      if (navType === SIDE_NAV_TYPE.PANEL) {
+      if (navType === SIDE_NAV_TYPE.RAIL_PANEL) {
         return;
       }
       if (!event.currentTarget.contains(event.relatedTarget)) {
@@ -325,7 +344,7 @@ function SideNavRenderFunction({
       }
     };
   }
-  if (addMouseListeners && isRail) {
+  if (addMouseListeners && !pinned && (isRail || autoExpand)) {
     eventHandlers.onMouseEnter = () => {
       handleToggle(true, true);
     };
@@ -335,6 +354,9 @@ function SideNavRenderFunction({
       handleToggle(false, false);
     };
     eventHandlers.onClick = () => {
+      if (autoExpand) {
+        return;
+      }
       //if delay is enabled, and user intentionally clicks it to see it expanded immediately
       setExpandedState(true);
       setExpandedViaHoverState(true);
@@ -345,7 +367,7 @@ function SideNavRenderFunction({
     const target = event.target;
     const isNavItemClick = target.closest(`.${prefix}--side-nav a, .${prefix}--side-nav button`);
     const isInRail = isNavItemClick?.closest(`.${prefix}--side-nav--rail`);
-    if (isNavItemClick && !isNavItemClick.classList.contains(`${prefix}--side-nav__submenu`) && !isNavItemClick.classList.contains(`${prefix}--side-nav__back-button`)) {
+    if (isNavItemClick && !isNavItemClick.classList.contains(`${prefix}--side-nav__submenu`) && !isNavItemClick.classList.contains(`${prefix}--side-nav__back-button`) && !isNavItemClick.classList.contains(`${prefix}--side-nav__toggle`)) {
       isInRail ? handleToggle(false, false) : onSideNavBlur?.();
     }
   });
@@ -359,15 +381,6 @@ function SideNavRenderFunction({
   });
   const lgMediaQuery = `(min-width: ${breakpoints.lg.width})`;
   const isLg = useMatchMedia(lgMediaQuery);
-  function resetNodeTabIndices() {
-    const items = sideNavRef?.current?.querySelectorAll('[tabIndex="0"]') ?? [];
-    items.forEach(item => {
-      if (item.classList.contains(`${prefix}--side-nav__toggle`) || item.classList.contains(`${prefix}--side-nav__back-button`) || item.closest(`.${prefix}--side-nav__slot-item`) || item.classList.contains(`${prefix}--side-nav__link`) && item.closest('ul')?.getAttribute('aria-label') === ariaLabel) {
-        return;
-      }
-      item.tabIndex = -1;
-    });
-  }
 
   // ensure that changes are in sync with internal treeview prop
   useEffect(() => {
@@ -382,13 +395,22 @@ function SideNavRenderFunction({
       setInternalIsTreeview(value);
     }
   };
-  const SideNavToggleButton = /*#__PURE__*/React__default.createElement(SideNavToggle, {
-    className: !expandedState ? `${prefix}--side-nav__toggle--collapsed` : '',
-    renderIcon: expandedState ? SidePanelClose : SidePanelOpen,
-    onClick: () => setExpandedState(!expandedState)
-  }, sideNavToggleText);
+  const handlePinClick = () => {
+    setPinned(!pinned);
+    if (!autoExpand) {
+      setExpandedState(!pinned);
+    }
+  };
+  const handleAutoExpand = () => {
+    if (pinned) {
+      return;
+    }
+    setExpandedState(!autoExpand);
+    setAutoExpand(!autoExpand);
+  };
   return /*#__PURE__*/React__default.createElement(SideNavContext.Provider, {
     value: {
+      autoExpand,
       expanded,
       isRail,
       navType,
@@ -397,7 +419,7 @@ function SideNavRenderFunction({
       currentPrimaryMenu,
       setCurrentPrimaryMenu
     }
-  }, isFixedNav || hideOverlay || navType === SIDE_NAV_TYPE.PANEL ? null :
+  }, isFixedNav || hideOverlay || navType === SIDE_NAV_TYPE.RAIL_PANEL ? null :
   /*#__PURE__*/
   // eslint-disable-next-line jsx-a11y/click-events-have-key-events, jsx-a11y/no-static-element-interactions
   React__default.createElement("div", {
@@ -408,10 +430,17 @@ function SideNavRenderFunction({
     tabIndex: -1,
     ref: navRef,
     className: `${prefix}--side-nav__navigation ${className}`,
-    inert: !isRail && navType !== SIDE_NAV_TYPE.PANEL && !(expanded || isLg) ? -1 : undefined
-  }, accessibilityLabel, eventHandlers, other), childrenToRender, navType === SIDE_NAV_TYPE.PANEL && (expandedState ? SideNavToggleButton : /*#__PURE__*/React__default.createElement("div", {
+    inert: !isRail && navType !== SIDE_NAV_TYPE.RAIL_PANEL && !(expanded || isLg) ? -1 : undefined
+  }, accessibilityLabel, eventHandlers, other), childrenToRender, navType === SIDE_NAV_TYPE.RAIL_PANEL && /*#__PURE__*/React__default.createElement("ul", {
     className: `${prefix}--side-nav__toggle-container`
-  }, SideNavToggleButton))));
+  }, _SideNavDivider || (_SideNavDivider = /*#__PURE__*/React__default.createElement(SideNavDivider, null)), /*#__PURE__*/React__default.createElement(SideNavToggle, {
+    onClick: handlePinClick,
+    renderIcon: pinned ? PinFilled : Pin
+  }, pinText), /*#__PURE__*/React__default.createElement(SideNavToggle, {
+    disabled: pinned,
+    renderIcon: expandedState ? SidePanelClose : SidePanelOpen,
+    onClick: handleAutoExpand
+  }, autoExpandText))));
 }
 const SideNav = /*#__PURE__*/React__default.forwardRef(SideNavRenderFunction);
 SideNav.displayName = 'SideNav';

package/es/components/SideNavLink.js

@@ -12,7 +12,7 @@ import React__default, { 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 { SideNavContext, SIDE_NAV_TYPE } from './SideNav.js';
 import { SideNavLinkPopover } from './SideNavLinkPopover.js';
 
 const SideNavLink = /*#__PURE__*/forwardRef(function SideNavLink({
@@ -39,7 +39,7 @@ const SideNavLink = /*#__PURE__*/forwardRef(function SideNavLink({
   const SideNavLinkIcon = IconElement && /*#__PURE__*/React__default.createElement(SideNavIcon, {
     small: true
   }, /*#__PURE__*/React__default.createElement(IconElement, null));
-  if (!expanded && navType === 'panel') {
+  if (!expanded && navType === SIDE_NAV_TYPE.RAIL_PANEL) {
     return /*#__PURE__*/React__default.createElement(SideNavLinkPopover, _extends({
       align: "right",
       label: children

package/es/components/SideNavMenu.js

@@ -62,6 +62,7 @@ const SideNavMenu = /*#__PURE__*/React__default.forwardRef(function SideNavMenu(
   const [prevExpanded, setPrevExpanded] = useState(defaultExpanded);
   const [isSecondaryOpen, setSecondaryOpen] = useState(defaultExpanded);
   const {
+    autoExpand,
     currentPrimaryMenu,
     setCurrentPrimaryMenu
   } = useContext(SideNavContext);
@@ -148,7 +149,7 @@ const SideNavMenu = /*#__PURE__*/React__default.forwardRef(function SideNavMenu(
     return false;
   }
   useEffect(() => {
-    if (navType == SIDE_NAV_TYPE.PANEL) {
+    if (navType == SIDE_NAV_TYPE.RAIL_PANEL) {
       // grab first link to redirect if clicked when not expanded
       if (!firstLink?.current && listRef?.current) {
         const firstLinkElement = listRef.current.querySelector(`.${prefix}--side-nav__menu-item a`);
@@ -282,7 +283,7 @@ const SideNavMenu = /*#__PURE__*/React__default.forwardRef(function SideNavMenu(
   }, [currentPrimaryMenu]);
   // reset to opened/collapsed menu state when Panel SideNav is toggled
   useEffect(() => {
-    if (navType == SIDE_NAV_TYPE.PANEL && !sideNavExpanded) {
+    if (navType == SIDE_NAV_TYPE.RAIL_PANEL && !sideNavExpanded) {
       setIsExpanded(false);
     }
 
@@ -319,7 +320,7 @@ const SideNavMenu = /*#__PURE__*/React__default.forwardRef(function SideNavMenu(
       }
 
       // only when sidenav is panel view
-      if (navType == SIDE_NAV_TYPE.PANEL && !isExpanded && firstLink.current && !sideNavExpanded) {
+      if (navType == SIDE_NAV_TYPE.RAIL_PANEL && !isExpanded && firstLink.current && !sideNavExpanded) {
         setOpenPopover(!openPopover);
         // window.location.href = firstLink.current;
       } else if (isSm || !primary || currentPrimaryMenu !== uniqueId) {
@@ -332,7 +333,7 @@ const SideNavMenu = /*#__PURE__*/React__default.forwardRef(function SideNavMenu(
     ref: menuRef,
     type: "button",
     tabIndex: isTreeview ? -1 : 0
-  }, IconElement && /*#__PURE__*/React__default.createElement(SideNavIcon, null, /*#__PURE__*/React__default.createElement(IconElement, null)), !sideNavExpanded && navType == SIDE_NAV_TYPE.PANEL && /*#__PURE__*/React__default.createElement("div", {
+  }, IconElement && /*#__PURE__*/React__default.createElement(SideNavIcon, null, /*#__PURE__*/React__default.createElement(IconElement, null)), !autoExpand && !sideNavExpanded && navType == SIDE_NAV_TYPE.RAIL_PANEL && /*#__PURE__*/React__default.createElement("div", {
     className: `${prefix}--side-nav--panel-submenu-caret-container`
   }, /*#__PURE__*/React__default.createElement("div", {
     className: `${prefix}--side-nav--panel-submenu-caret`
@@ -362,7 +363,7 @@ const SideNavMenu = /*#__PURE__*/React__default.forwardRef(function SideNavMenu(
     className: `${prefix}--side-nav__menu`,
     role: "group"
   }, childrenToRender));
-  return navType == SIDE_NAV_TYPE.PANEL && !sideNavExpanded ? /*#__PURE__*/React__default.createElement(SideNavFlyoutMenu, {
+  return navType == SIDE_NAV_TYPE.RAIL_PANEL && !sideNavExpanded ? /*#__PURE__*/React__default.createElement(SideNavFlyoutMenu, {
     selected: active,
     className: `${prefix}--side-nav-flyout-menu`,
     title: title,

package/es/components/SideNavToggle.d.ts

@@ -4,29 +4,54 @@
  * 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, { ReactNode } from 'react';
-interface SideNavToggleProps {
+import PropTypes from 'prop-types';
+import { ComponentType, ElementType, ForwardedRef, ReactNode } from 'react';
+import { LinkProps } from './Link';
+export type SideNavToggleProps<E extends ElementType> = LinkProps<E> & {
     /**
-     * Specify an optional className to be applied to the button node
+     * Required props for the accessibility label
      */
-    className?: string;
+    'aria-label'?: string;
+    /**
+     * Required props for the accessibility label
+     */
+    'aria-labelledby'?: string;
     /**
      * Specify the text content for the link
      */
-    children: ReactNode;
+    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;
     /**
-     * Provide an optional function to be called when the item is clicked.
+     * Specify if this is a large variation of the SideNavLink
      */
-    onClick?: (event: React.MouseEvent<HTMLButtonElement>) => void;
+    large?: boolean;
     /**
-     * A custom icon to render next to the SideNavToggle title. This can be a function returning JSX or JSX itself.
+     * Provide an icon to render in the side navigation link. Should be a React class.
      */
-    renderIcon?: React.ComponentType;
+    renderIcon?: ComponentType;
     /**
-     * The tabIndex for the button element.
-     * If not specified, the default validation will be applied.
+     * Optional prop to specify the tabIndex of the button. If undefined, it will be applied default validation
      */
     tabIndex?: number;
+};
+export interface SideNavLinkComponent {
+    (props: SideNavToggleProps<'button'> & {
+        ref?: ForwardedRef<HTMLButtonElement>;
+    }): JSX.Element | null;
+    displayName?: string;
+    propTypes?: Partial<Record<keyof SideNavToggleProps<any>, PropTypes.Validator<any>>>;
 }
-export declare const SideNavToggle: React.ForwardRefExoticComponent<SideNavToggleProps & React.RefAttributes<HTMLElement>>;
+export declare const SideNavToggle: SideNavLinkComponent;
 export default SideNavToggle;

package/es/components/SideNavToggle.js

@@ -8,47 +8,79 @@
 import { extends as _extends } from '../_virtual/_rollupPluginBabelHelpers.js';
 import cx from 'classnames';
 import PropTypes from 'prop-types';
-import React__default from 'react';
-import { SideNavIcon } from '@carbon/react';
+import React__default, { forwardRef, useContext } from 'react';
+import { LinkPropTypes } from './Link.js';
+import { SideNavItem, SideNavLinkText, SideNavIcon } from '@carbon/react';
 import { usePrefix } from '../internal/usePrefix.js';
+import { SideNavContext, SIDE_NAV_TYPE } from './SideNav.js';
+import { SideNavLinkPopover } from './SideNavLinkPopover.js';
 
-const SideNavToggle = /*#__PURE__*/React__default.forwardRef(function SideNavToggle({
+const SideNavToggle = /*#__PURE__*/forwardRef(function SideNavToggle({
+  children,
   className: customClassName,
+  disabled,
   renderIcon: IconElement,
+  large = false,
   tabIndex,
-  children,
   ...rest
 }, ref) {
+  const {
+    expanded,
+    navType
+  } = useContext(SideNavContext);
   const prefix = usePrefix();
-  return /*#__PURE__*/React__default.createElement("button", _extends({
-    className: cx(customClassName, {
-      [`${prefix}--side-nav__toggle`]: true
-    }),
+  const className = cx({
+    [`${prefix}--side-nav__toggle`]: true,
+    [`${prefix}--side-nav__toggle--disabled`]: disabled,
+    [customClassName]: !!customClassName
+  });
+  const SideNavLinkIcon = IconElement && /*#__PURE__*/React__default.createElement(SideNavIcon, {
+    small: true
+  }, /*#__PURE__*/React__default.createElement(IconElement, null));
+  if (!expanded && navType === SIDE_NAV_TYPE.RAIL_PANEL) {
+    return /*#__PURE__*/React__default.createElement(SideNavLinkPopover, _extends({
+      align: "right",
+      className: className,
+      label: children
+    }, rest), SideNavLinkIcon);
+  }
+  return /*#__PURE__*/React__default.createElement(SideNavItem, {
+    large: large
+  }, /*#__PURE__*/React__default.createElement("button", _extends({
+    className: className,
     ref: ref,
     type: "button",
-    tabIndex: tabIndex ?? 0
-  }, rest), IconElement && /*#__PURE__*/React__default.createElement(SideNavIcon, null, /*#__PURE__*/React__default.createElement(IconElement, null)), /*#__PURE__*/React__default.createElement("span", {
-    className: `${prefix}--side-nav__toggle-text`
-  }, children));
+    tabIndex: tabIndex ?? 0,
+    disabled: disabled
+  }, rest), SideNavLinkIcon, /*#__PURE__*/React__default.createElement(SideNavLinkText, null, children)));
 });
 SideNavToggle.displayName = 'SideNavToggle';
 SideNavToggle.propTypes = {
+  ...LinkPropTypes,
   /**
-   * Specify the text content for the toggle
+   * Specify the text content for the link
    */
   children: PropTypes.node,
   /**
-   * Specify an optional className to be applied to the button node
+   * Provide an optional class to be applied to the containing node
    */
   className: PropTypes.string,
   /**
-   * Provide an optional function to be called when clicked
+   * 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
    */
-  onClick: PropTypes.func,
+  large: PropTypes.bool,
   /**
-   * Pass in a custom icon to render next to the `SideNavToggle` title
+   * 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

package/lib/components/Profile.js

@@ -21,14 +21,15 @@ const Profile = /*#__PURE__*/React__default.forwardRef(function Profile({
   children,
   renderIcon: IconElement,
   ...rest
-}) {
+}, ref) {
   const prefix = usePrefix.usePrefix();
   const className = cx({
     [`${prefix}--profile`]: true,
     [customClassName]: !!customClassName
   });
   return /*#__PURE__*/React__default.createElement(HeaderPopover.HeaderPopover, _rollupPluginBabelHelpers.extends({
-    align: "bottom-right",
+    ref: ref,
+    align: "bottom-end",
     className: className
   }, rest), /*#__PURE__*/React__default.createElement(HeaderPopover.HeaderPopoverButton, {
     align: "bottom",
@@ -60,13 +61,14 @@ const ProfileUserInfo = /*#__PURE__*/React__default.forwardRef(function ProfileU
   name,
   email,
   ...rest
-}) {
+}, ref) {
   const prefix = usePrefix.usePrefix();
   const className = cx({
     [`${prefix}--profile-user-info`]: true,
     [customClassName]: !!customClassName
   });
   return /*#__PURE__*/React__default.createElement("div", {
+    ref: ref,
     className: className
   }, /*#__PURE__*/React__default.createElement(UserAvatar.UserAvatar, _rollupPluginBabelHelpers.extends({
     size: "lg",
@@ -97,13 +99,14 @@ ProfileUserInfo.propTypes = {
 const ProfileReadOnly = /*#__PURE__*/React__default.forwardRef(function ProfileReadOnly({
   className: customClassName,
   items
-}) {
+}, ref) {
   const prefix = usePrefix.usePrefix();
   const className = cx({
     [`${prefix}--profile-read-only`]: true,
     [customClassName]: !!customClassName
   });
   return /*#__PURE__*/React__default.createElement("div", {
+    ref: ref,
     className: className
   }, items?.map((item, index) => /*#__PURE__*/React__default.createElement("div", {
     className: `${prefix}--profile-read-only__items`,

package/lib/components/SideNav.d.ts

@@ -9,12 +9,14 @@ import { TranslateWithId } from '../types/common';
 export declare enum SIDE_NAV_TYPE {
     DEFAULT = "default",
     RAIL = "rail",
-    PANEL = "panel"
+    RAIL_PANEL = "panel"
 }
 export type TranslationKey = keyof typeof translationIds;
 export declare const translationIds: {
     readonly 'collapse.sidenav': "collapse.sidenav";
     readonly 'expand.sidenav': "expand.sidenav";
+    readonly 'enable.autoexpand': "enable.autoexpand";
+    readonly 'disable.autoexpand': "disable.autoexpand";
 };
 export interface SideNavProps extends ComponentProps<'nav'>, TranslateWithId<TranslationKey> {
     expanded?: boolean;
@@ -38,6 +40,7 @@ export interface SideNavProps extends ComponentProps<'nav'>, TranslateWithId<Tra
     isTreeview?: boolean;
 }
 interface SideNavContextData {
+    autoExpand?: boolean;
     expanded?: boolean;
     isRail?: boolean;
     navType?: SIDE_NAV_TYPE;

package/lib/components/SideNav.js

@@ -23,20 +23,26 @@ var index = require('../node_modules/@carbon/layout/es/index.js');
 var useMatchMedia = require('../internal/useMatchMedia.js');
 var iconsReact = require('@carbon/icons-react');
 var SideNavToggle = require('./SideNavToggle.js');
+var react = require('@carbon/react');
 
+var _SideNavDivider;
 let SIDE_NAV_TYPE = /*#__PURE__*/function (SIDE_NAV_TYPE) {
   SIDE_NAV_TYPE["DEFAULT"] = "default";
   SIDE_NAV_TYPE["RAIL"] = "rail";
-  SIDE_NAV_TYPE["PANEL"] = "panel";
+  SIDE_NAV_TYPE["RAIL_PANEL"] = "panel";
   return SIDE_NAV_TYPE;
 }({});
 const translationIds = {
   'collapse.sidenav': 'collapse.sidenav',
-  'expand.sidenav': 'expand.sidenav'
+  'expand.sidenav': 'expand.sidenav',
+  'enable.autoexpand': 'enable.autoexpand',
+  'disable.autoexpand': 'disable.autoexpand'
 };
 const defaultTranslations = {
-  [translationIds['collapse.sidenav']]: 'Collapse',
-  [translationIds['expand.sidenav']]: 'Expand'
+  [translationIds['collapse.sidenav']]: 'Unpin',
+  [translationIds['expand.sidenav']]: 'Pin open',
+  [translationIds['enable.autoexpand']]: 'Enable auto-expand',
+  [translationIds['disable.autoexpand']]: 'Disable auto-expand'
 };
 const defaultTranslateWithId = id => defaultTranslations[id];
 const SideNavContext = /*#__PURE__*/React__default.createContext({});
@@ -71,13 +77,16 @@ function SideNavRenderFunction({
   const {
     current: controlled
   } = React__default.useRef(expandedProp !== undefined);
+  const [autoExpand, setAutoExpand] = React__default.useState(false);
   const [expandedState, setExpandedState] = useDelayedState.useDelayedState(defaultExpanded);
   const [expandedViaHoverState, setExpandedViaHoverState] = useDelayedState.useDelayedState(defaultExpanded);
+  const [pinned, setPinned] = React__default.useState(false);
   const expanded = controlled ? expandedProp : expandedState;
   const sideNavRef = React__default.useRef(null);
   const navRef = useMergedRefs.useMergedRefs([sideNavRef, ref]);
   const [currentPrimaryMenu, setCurrentPrimaryMenu] = React__default.useState();
-  const sideNavToggleText = expandedState ? t('collapse.sidenav') : t('expand.sidenav');
+  const pinText = pinned ? t('collapse.sidenav') : t('expand.sidenav');
+  const autoExpandText = autoExpand ? t('disable.autoexpand') : t('enable.autoexpand');
   const handleToggle = (event, value = !expanded) => {
     if (!controlled) {
       setExpandedState(value, enterDelayMs);
@@ -98,8 +107,9 @@ function SideNavRenderFunction({
     [`${prefix}--side-nav--expanded`]: expanded || expandedViaHoverState,
     [`${prefix}--side-nav--collapsed`]: !expanded && isFixedNav,
     [`${prefix}--side-nav--hide-rail-breakpoint-down-${hideRailBreakpointDown}`]: hideRailBreakpointDown,
-    [`${prefix}--side-nav--rail`]: isRail,
-    [`${prefix}--side-nav--panel`]: navType === SIDE_NAV_TYPE.PANEL,
+    [`${prefix}--side-nav--rail`]: isRail || autoExpand,
+    [`${prefix}--side-nav--panel`]: navType === SIDE_NAV_TYPE.RAIL_PANEL,
+    [`${prefix}--side-nav--pinned`]: pinned,
     [`${prefix}--side-nav--ux`]: isChildOfHeader,
     [`${prefix}--side-nav--hidden`]: !isPersistent,
     [`${prefix}--side-nav--collapsible`]: isCollapsible,
@@ -130,6 +140,15 @@ function SideNavRenderFunction({
     return child;
   });
   const eventHandlers = {};
+  const resetNodeTabIndices = React__default.useCallback(() => {
+    const items = sideNavRef?.current?.querySelectorAll('[tabIndex="0"]') ?? [];
+    items.forEach(item => {
+      if (item.classList.contains(`${prefix}--side-nav__toggle`) || item.classList.contains(`${prefix}--side-nav__back-button`) || item.closest(`.${prefix}--side-nav__slot-item`) || item.classList.contains(`${prefix}--side-nav__link`) && item.closest('ul')?.getAttribute('aria-label') === ariaLabel) {
+        return;
+      }
+      item.tabIndex = -1;
+    });
+  }, [prefix, ariaLabel]);
   const treeWalkerRef = React__default.useRef(null);
   React__default.useEffect(() => {
     if (internalIsTreeview) {
@@ -149,7 +168,7 @@ function SideNavRenderFunction({
       });
       resetNodeTabIndices();
     }
-  }, [prefix, internalIsTreeview]);
+  }, [prefix, internalIsTreeview, resetNodeTabIndices]);
   const smMediaQuery = `(min-width: ${index.breakpoints.sm.width})`;
   const isSm = useMatchMedia.useMatchMedia(smMediaQuery);
   React__default.useEffect(() => {
@@ -158,7 +177,7 @@ function SideNavRenderFunction({
       const slotElement = sideNavRef?.current.querySelector(`.${prefix}--side-nav__slot`);
       const firstElement = sideNavRef?.current?.querySelector('a, button');
       const currentElement = sideNavRef?.current?.querySelector(`.cds--side-nav__link--current`);
-      if (navType == SIDE_NAV_TYPE.PANEL || expanded) {
+      if (navType == SIDE_NAV_TYPE.RAIL_PANEL || expanded) {
         if (isSm && backButton) {
           backButton.tabIndex = 0;
           const firstElementAfterBack = backButton.nextElementSibling?.querySelector('a, button');
@@ -178,7 +197,7 @@ function SideNavRenderFunction({
         }
       }
     }
-  }, [expanded]);
+  }, [expanded, currentPrimaryMenu, isSm, navType, prefix]);
 
   /**
    * Returns the parent SideNavMenu, if node is actually inside one.
@@ -194,12 +213,12 @@ function SideNavRenderFunction({
   }
   if (addFocusListeners) {
     eventHandlers.onFocus = event => {
-      if (!event.currentTarget.contains(event.relatedTarget) && isRail) {
+      if (!event.currentTarget.contains(event.relatedTarget) && (isRail || autoExpand)) {
         handleToggle(event, true);
       }
     };
     eventHandlers.onBlur = event => {
-      if (navType === SIDE_NAV_TYPE.PANEL) {
+      if (navType === SIDE_NAV_TYPE.RAIL_PANEL) {
         return;
       }
       if (!event.currentTarget.contains(event.relatedTarget)) {
@@ -327,7 +346,7 @@ function SideNavRenderFunction({
       }
     };
   }
-  if (addMouseListeners && isRail) {
+  if (addMouseListeners && !pinned && (isRail || autoExpand)) {
     eventHandlers.onMouseEnter = () => {
       handleToggle(true, true);
     };
@@ -337,6 +356,9 @@ function SideNavRenderFunction({
       handleToggle(false, false);
     };
     eventHandlers.onClick = () => {
+      if (autoExpand) {
+        return;
+      }
       //if delay is enabled, and user intentionally clicks it to see it expanded immediately
       setExpandedState(true);
       setExpandedViaHoverState(true);
@@ -347,7 +369,7 @@ function SideNavRenderFunction({
     const target = event.target;
     const isNavItemClick = target.closest(`.${prefix}--side-nav a, .${prefix}--side-nav button`);
     const isInRail = isNavItemClick?.closest(`.${prefix}--side-nav--rail`);
-    if (isNavItemClick && !isNavItemClick.classList.contains(`${prefix}--side-nav__submenu`) && !isNavItemClick.classList.contains(`${prefix}--side-nav__back-button`)) {
+    if (isNavItemClick && !isNavItemClick.classList.contains(`${prefix}--side-nav__submenu`) && !isNavItemClick.classList.contains(`${prefix}--side-nav__back-button`) && !isNavItemClick.classList.contains(`${prefix}--side-nav__toggle`)) {
       isInRail ? handleToggle(false, false) : onSideNavBlur?.();
     }
   });
@@ -361,15 +383,6 @@ function SideNavRenderFunction({
   });
   const lgMediaQuery = `(min-width: ${index.breakpoints.lg.width})`;
   const isLg = useMatchMedia.useMatchMedia(lgMediaQuery);
-  function resetNodeTabIndices() {
-    const items = sideNavRef?.current?.querySelectorAll('[tabIndex="0"]') ?? [];
-    items.forEach(item => {
-      if (item.classList.contains(`${prefix}--side-nav__toggle`) || item.classList.contains(`${prefix}--side-nav__back-button`) || item.closest(`.${prefix}--side-nav__slot-item`) || item.classList.contains(`${prefix}--side-nav__link`) && item.closest('ul')?.getAttribute('aria-label') === ariaLabel) {
-        return;
-      }
-      item.tabIndex = -1;
-    });
-  }
 
   // ensure that changes are in sync with internal treeview prop
   React__default.useEffect(() => {
@@ -384,13 +397,22 @@ function SideNavRenderFunction({
       setInternalIsTreeview(value);
     }
   };
-  const SideNavToggleButton = /*#__PURE__*/React__default.createElement(SideNavToggle.SideNavToggle, {
-    className: !expandedState ? `${prefix}--side-nav__toggle--collapsed` : '',
-    renderIcon: expandedState ? iconsReact.SidePanelClose : iconsReact.SidePanelOpen,
-    onClick: () => setExpandedState(!expandedState)
-  }, sideNavToggleText);
+  const handlePinClick = () => {
+    setPinned(!pinned);
+    if (!autoExpand) {
+      setExpandedState(!pinned);
+    }
+  };
+  const handleAutoExpand = () => {
+    if (pinned) {
+      return;
+    }
+    setExpandedState(!autoExpand);
+    setAutoExpand(!autoExpand);
+  };
   return /*#__PURE__*/React__default.createElement(SideNavContext.Provider, {
     value: {
+      autoExpand,
       expanded,
       isRail,
       navType,
@@ -399,7 +421,7 @@ function SideNavRenderFunction({
       currentPrimaryMenu,
       setCurrentPrimaryMenu
     }
-  }, isFixedNav || hideOverlay || navType === SIDE_NAV_TYPE.PANEL ? null :
+  }, isFixedNav || hideOverlay || navType === SIDE_NAV_TYPE.RAIL_PANEL ? null :
   /*#__PURE__*/
   // eslint-disable-next-line jsx-a11y/click-events-have-key-events, jsx-a11y/no-static-element-interactions
   React__default.createElement("div", {
@@ -410,10 +432,17 @@ function SideNavRenderFunction({
     tabIndex: -1,
     ref: navRef,
     className: `${prefix}--side-nav__navigation ${className}`,
-    inert: !isRail && navType !== SIDE_NAV_TYPE.PANEL && !(expanded || isLg) ? -1 : undefined
-  }, accessibilityLabel, eventHandlers, other), childrenToRender, navType === SIDE_NAV_TYPE.PANEL && (expandedState ? SideNavToggleButton : /*#__PURE__*/React__default.createElement("div", {
+    inert: !isRail && navType !== SIDE_NAV_TYPE.RAIL_PANEL && !(expanded || isLg) ? -1 : undefined
+  }, accessibilityLabel, eventHandlers, other), childrenToRender, navType === SIDE_NAV_TYPE.RAIL_PANEL && /*#__PURE__*/React__default.createElement("ul", {
     className: `${prefix}--side-nav__toggle-container`
-  }, SideNavToggleButton))));
+  }, _SideNavDivider || (_SideNavDivider = /*#__PURE__*/React__default.createElement(react.SideNavDivider, null)), /*#__PURE__*/React__default.createElement(SideNavToggle.SideNavToggle, {
+    onClick: handlePinClick,
+    renderIcon: pinned ? iconsReact.PinFilled : iconsReact.Pin
+  }, pinText), /*#__PURE__*/React__default.createElement(SideNavToggle.SideNavToggle, {
+    disabled: pinned,
+    renderIcon: expandedState ? iconsReact.SidePanelClose : iconsReact.SidePanelOpen,
+    onClick: handleAutoExpand
+  }, autoExpandText))));
 }
 const SideNav = /*#__PURE__*/React__default.forwardRef(SideNavRenderFunction);
 SideNav.displayName = 'SideNav';

package/lib/components/SideNavLink.js

@@ -43,7 +43,7 @@ const SideNavLink = /*#__PURE__*/React__default.forwardRef(function SideNavLink(
   const SideNavLinkIcon = IconElement && /*#__PURE__*/React__default.createElement(react.SideNavIcon, {
     small: true
   }, /*#__PURE__*/React__default.createElement(IconElement, null));
-  if (!expanded && navType === 'panel') {
+  if (!expanded && navType === SideNav.SIDE_NAV_TYPE.RAIL_PANEL) {
     return /*#__PURE__*/React__default.createElement(SideNavLinkPopover.SideNavLinkPopover, _rollupPluginBabelHelpers.extends({
       align: "right",
       label: children

package/lib/components/SideNavMenu.js

@@ -64,6 +64,7 @@ const SideNavMenu = /*#__PURE__*/React__default.forwardRef(function SideNavMenu(
   const [prevExpanded, setPrevExpanded] = React__default.useState(defaultExpanded);
   const [isSecondaryOpen, setSecondaryOpen] = React__default.useState(defaultExpanded);
   const {
+    autoExpand,
     currentPrimaryMenu,
     setCurrentPrimaryMenu
   } = React__default.useContext(SideNav.SideNavContext);
@@ -150,7 +151,7 @@ const SideNavMenu = /*#__PURE__*/React__default.forwardRef(function SideNavMenu(
     return false;
   }
   React__default.useEffect(() => {
-    if (navType == SideNav.SIDE_NAV_TYPE.PANEL) {
+    if (navType == SideNav.SIDE_NAV_TYPE.RAIL_PANEL) {
       // grab first link to redirect if clicked when not expanded
       if (!firstLink?.current && listRef?.current) {
         const firstLinkElement = listRef.current.querySelector(`.${prefix}--side-nav__menu-item a`);
@@ -284,7 +285,7 @@ const SideNavMenu = /*#__PURE__*/React__default.forwardRef(function SideNavMenu(
   }, [currentPrimaryMenu]);
   // reset to opened/collapsed menu state when Panel SideNav is toggled
   React__default.useEffect(() => {
-    if (navType == SideNav.SIDE_NAV_TYPE.PANEL && !sideNavExpanded) {
+    if (navType == SideNav.SIDE_NAV_TYPE.RAIL_PANEL && !sideNavExpanded) {
       setIsExpanded(false);
     }
 
@@ -321,7 +322,7 @@ const SideNavMenu = /*#__PURE__*/React__default.forwardRef(function SideNavMenu(
       }
 
       // only when sidenav is panel view
-      if (navType == SideNav.SIDE_NAV_TYPE.PANEL && !isExpanded && firstLink.current && !sideNavExpanded) {
+      if (navType == SideNav.SIDE_NAV_TYPE.RAIL_PANEL && !isExpanded && firstLink.current && !sideNavExpanded) {
         setOpenPopover(!openPopover);
         // window.location.href = firstLink.current;
       } else if (isSm || !primary || currentPrimaryMenu !== uniqueId) {
@@ -334,7 +335,7 @@ const SideNavMenu = /*#__PURE__*/React__default.forwardRef(function SideNavMenu(
     ref: menuRef,
     type: "button",
     tabIndex: isTreeview ? -1 : 0
-  }, IconElement && /*#__PURE__*/React__default.createElement(react.SideNavIcon, null, /*#__PURE__*/React__default.createElement(IconElement, null)), !sideNavExpanded && navType == SideNav.SIDE_NAV_TYPE.PANEL && /*#__PURE__*/React__default.createElement("div", {
+  }, IconElement && /*#__PURE__*/React__default.createElement(react.SideNavIcon, null, /*#__PURE__*/React__default.createElement(IconElement, null)), !autoExpand && !sideNavExpanded && navType == SideNav.SIDE_NAV_TYPE.RAIL_PANEL && /*#__PURE__*/React__default.createElement("div", {
     className: `${prefix}--side-nav--panel-submenu-caret-container`
   }, /*#__PURE__*/React__default.createElement("div", {
     className: `${prefix}--side-nav--panel-submenu-caret`
@@ -364,7 +365,7 @@ const SideNavMenu = /*#__PURE__*/React__default.forwardRef(function SideNavMenu(
     className: `${prefix}--side-nav__menu`,
     role: "group"
   }, childrenToRender));
-  return navType == SideNav.SIDE_NAV_TYPE.PANEL && !sideNavExpanded ? /*#__PURE__*/React__default.createElement(SideNavFlyoutMenu.SideNavFlyoutMenu, {
+  return navType == SideNav.SIDE_NAV_TYPE.RAIL_PANEL && !sideNavExpanded ? /*#__PURE__*/React__default.createElement(SideNavFlyoutMenu.SideNavFlyoutMenu, {
     selected: active,
     className: `${prefix}--side-nav-flyout-menu`,
     title: title,

package/lib/components/SideNavToggle.d.ts

@@ -4,29 +4,54 @@
  * 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, { ReactNode } from 'react';
-interface SideNavToggleProps {
+import PropTypes from 'prop-types';
+import { ComponentType, ElementType, ForwardedRef, ReactNode } from 'react';
+import { LinkProps } from './Link';
+export type SideNavToggleProps<E extends ElementType> = LinkProps<E> & {
     /**
-     * Specify an optional className to be applied to the button node
+     * Required props for the accessibility label
      */
-    className?: string;
+    'aria-label'?: string;
+    /**
+     * Required props for the accessibility label
+     */
+    'aria-labelledby'?: string;
     /**
      * Specify the text content for the link
      */
-    children: ReactNode;
+    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;
     /**
-     * Provide an optional function to be called when the item is clicked.
+     * Specify if this is a large variation of the SideNavLink
      */
-    onClick?: (event: React.MouseEvent<HTMLButtonElement>) => void;
+    large?: boolean;
     /**
-     * A custom icon to render next to the SideNavToggle title. This can be a function returning JSX or JSX itself.
+     * Provide an icon to render in the side navigation link. Should be a React class.
      */
-    renderIcon?: React.ComponentType;
+    renderIcon?: ComponentType;
     /**
-     * The tabIndex for the button element.
-     * If not specified, the default validation will be applied.
+     * Optional prop to specify the tabIndex of the button. If undefined, it will be applied default validation
      */
     tabIndex?: number;
+};
+export interface SideNavLinkComponent {
+    (props: SideNavToggleProps<'button'> & {
+        ref?: ForwardedRef<HTMLButtonElement>;
+    }): JSX.Element | null;
+    displayName?: string;
+    propTypes?: Partial<Record<keyof SideNavToggleProps<any>, PropTypes.Validator<any>>>;
 }
-export declare const SideNavToggle: React.ForwardRefExoticComponent<SideNavToggleProps & React.RefAttributes<HTMLElement>>;
+export declare const SideNavToggle: SideNavLinkComponent;
 export default SideNavToggle;

package/lib/components/SideNavToggle.js

@@ -13,46 +13,78 @@ var _rollupPluginBabelHelpers = require('../_virtual/_rollupPluginBabelHelpers.j
 var cx = require('classnames');
 var PropTypes = require('prop-types');
 var React__default = 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 SideNavToggle = /*#__PURE__*/React__default.forwardRef(function SideNavToggle({
+  children,
   className: customClassName,
+  disabled,
   renderIcon: IconElement,
+  large = false,
   tabIndex,
-  children,
   ...rest
 }, ref) {
+  const {
+    expanded,
+    navType
+  } = React__default.useContext(SideNav.SideNavContext);
   const prefix = usePrefix.usePrefix();
-  return /*#__PURE__*/React__default.createElement("button", _rollupPluginBabelHelpers.extends({
-    className: cx(customClassName, {
-      [`${prefix}--side-nav__toggle`]: true
-    }),
+  const className = cx({
+    [`${prefix}--side-nav__toggle`]: true,
+    [`${prefix}--side-nav__toggle--disabled`]: disabled,
+    [customClassName]: !!customClassName
+  });
+  const SideNavLinkIcon = IconElement && /*#__PURE__*/React__default.createElement(react.SideNavIcon, {
+    small: true
+  }, /*#__PURE__*/React__default.createElement(IconElement, null));
+  if (!expanded && navType === SideNav.SIDE_NAV_TYPE.RAIL_PANEL) {
+    return /*#__PURE__*/React__default.createElement(SideNavLinkPopover.SideNavLinkPopover, _rollupPluginBabelHelpers.extends({
+      align: "right",
+      className: className,
+      label: children
+    }, rest), SideNavLinkIcon);
+  }
+  return /*#__PURE__*/React__default.createElement(react.SideNavItem, {
+    large: large
+  }, /*#__PURE__*/React__default.createElement("button", _rollupPluginBabelHelpers.extends({
+    className: className,
     ref: ref,
     type: "button",
-    tabIndex: tabIndex ?? 0
-  }, rest), IconElement && /*#__PURE__*/React__default.createElement(react.SideNavIcon, null, /*#__PURE__*/React__default.createElement(IconElement, null)), /*#__PURE__*/React__default.createElement("span", {
-    className: `${prefix}--side-nav__toggle-text`
-  }, children));
+    tabIndex: tabIndex ?? 0,
+    disabled: disabled
+  }, rest), SideNavLinkIcon, /*#__PURE__*/React__default.createElement(react.SideNavLinkText, null, children)));
 });
 SideNavToggle.displayName = 'SideNavToggle';
 SideNavToggle.propTypes = {
+  ...Link.LinkPropTypes,
   /**
-   * Specify the text content for the toggle
+   * Specify the text content for the link
    */
   children: PropTypes.node,
   /**
-   * Specify an optional className to be applied to the button node
+   * Provide an optional class to be applied to the containing node
    */
   className: PropTypes.string,
   /**
-   * Provide an optional function to be called when clicked
+   * 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
    */
-  onClick: PropTypes.func,
+  large: PropTypes.bool,
   /**
-   * Pass in a custom icon to render next to the `SideNavToggle` title
+   * 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@carbon-labs/react-ui-shell",
-  "version": "0.72.0",
+  "version": "0.74.0",
   "publishConfig": {
     "access": "public",
     "provenance": true
@@ -42,5 +42,5 @@
   "dependencies": {
     "@ibm/telemetry-js": "^1.9.1"
   },
-  "gitHead": "97cdff827945118076e8326b994e16ca6d036501"
+  "gitHead": "fd1fd1e946fc16c0cac7e637512ce1423085b9d9"
 }

package/scss/styles/_content.scss

@@ -19,9 +19,21 @@ div:has(.#{$prefix}--side-nav--panel) ~ .#{$prefix}--content {
   transition: $fast-02 motion(exit, productive);
 }
 
-.#{$prefix}--side-nav--panel.#{$prefix}--side-nav--expanded
+.#{$prefix}--side-nav--panel:not(
+    .#{$prefix}--side-nav--rail
+  ).#{$prefix}--side-nav--expanded
   ~ .#{$prefix}--content,
-div:has(.#{$prefix}--side-nav--panel.#{$prefix}--side-nav--expanded)
+.#{$prefix}--side-nav--panel.#{$prefix}--side-nav--pinned.#{$prefix}--side-nav--expanded
+  ~ .#{$prefix}--content,
+div:has(
+    .#{$prefix}--side-nav--panel:not(
+        .#{$prefix}--side-nav--rail
+      ).#{$prefix}--side-nav--expanded
+  )
+  ~ .#{$prefix}--content,
+div:has(
+    .#{$prefix}--side-nav--panel.#{$prefix}--side-nav--pinned.#{$prefix}--side-nav--expanded
+  )
   ~ .#{$prefix}--content {
   margin-inline-start: convert.to-rem(256px);
   transition: $moderate-01 motion(standard, productive);

package/scss/styles/_side-nav.scss

@@ -350,6 +350,7 @@ div:has(.#{$prefix}--header)
     display: flex;
     overflow: visible;
     flex-direction: column;
+    padding-block-end: $spacing-11;
   }
 
   .#{$prefix}--side-nav__items,
@@ -374,14 +375,14 @@ div:has(.#{$prefix}--header)
 
   // Side Nav Toggle
   .#{$prefix}--side-nav__toggle {
-    @include button-reset.reset($width: true);
-    @include type-style('heading-compact-01');
+    @include button-reset.reset($width: false);
+    @include type-style('label-01');
     @include focus-outline('reset');
 
     display: flex;
     align-items: center;
     padding: 0 $spacing-05;
-    block-size: $spacing-09;
+    block-size: $spacing-07;
     color: $text-secondary;
     transition: color $duration-fast-02, background-color $duration-fast-02,
       outline $duration-fast-02;
@@ -396,6 +397,15 @@ div:has(.#{$prefix}--header)
     }
   }
 
+  .#{$prefix}--side-nav__toggle--disabled {
+    color: $text-disabled;
+    pointer-events: none;
+
+    svg {
+      fill: $icon-disabled;
+    }
+  }
+
   .#{$prefix}--side-nav__toggle-text {
     @include text-overflow();
 
@@ -562,6 +572,10 @@ div:has(.#{$prefix}--header)
   .#{$prefix}--side-nav__item {
     overflow: visible;
   }
+
+  .#{$prefix}--side-nav__toggle {
+    inline-size: 100%;
+  }
 }
 
 .#{$prefix}--side-nav__toggle-container {
@@ -569,10 +583,7 @@ div:has(.#{$prefix}--header)
   background: $background;
   inline-size: 100%;
   inset-block-end: 0;
-
-  .#{$prefix}--side-nav__toggle.#{$prefix}--side-nav__toggle--collapsed:hover {
-    background: $background-hover;
-  }
+  white-space: nowrap;
 }
 
 //----------------------------------------------------------------------------
@@ -588,6 +599,11 @@ div:has(.#{$prefix}--header)
   box-shadow: $spacing-02 0 convert.to-rem(6px) convert.to-rem(-3px) $shadow;
 }
 
+.#{$prefix}--side-nav--rail.#{$prefix}--side-nav--expanded.#{$prefix}--side-nav--pinned {
+  border-inline-end: 1px solid $border-subtle;
+  box-shadow: none;
+}
+
 @each $breakpoint in ('sm', 'md', 'lg', 'xlg', 'max') {
   .#{$prefix}--side-nav--rail.#{$prefix}--side-nav--hide-rail-breakpoint-down-#{$breakpoint} {
     @include breakpoint-down($breakpoint) {