@carbon-labs/react-ui-shell 0.82.0 → 0.84.0

package/es/components/HeaderOverflowPanel.d.ts

@@ -0,0 +1,24 @@
+/**
+ * @license
+ *
+ * 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 React from 'react';
+export interface HeaderOverflowPanelProps {
+    /**
+     * Provide an optional class to be applied to the containing node
+     */
+    className?: string;
+    /**
+     * Custom children to be rendered within the popover of the Overflow panel menu
+     */
+    children?: React.ReactNode;
+    /**
+     * Provide the Overflow panel's label
+     */
+    label?: string;
+}
+export declare const HeaderOverflowPanel: React.ForwardRefExoticComponent<HeaderOverflowPanelProps & React.RefAttributes<HTMLDivElement>>;

package/es/components/HeaderOverflowPanel.js

@@ -0,0 +1,56 @@
+/**
+ * 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 'classnames';
+import PropTypes from 'prop-types';
+import React__default from 'react';
+import { usePrefix } from '../internal/usePrefix.js';
+import { HeaderPopover, HeaderPopoverButton, HeaderPopoverContent } from './HeaderPopover.js';
+import { OverflowMenuVertical } from '@carbon/icons-react';
+import { useMatchMedia } from '../internal/useMatchMedia.js';
+import { breakpoints } from '../node_modules/@carbon/layout/es/index.js';
+
+var _OverflowMenuVertical;
+const mdMediaQuery = `(max-width: ${breakpoints.md.width})`;
+const HeaderOverflowPanel = /*#__PURE__*/React__default.forwardRef(function HeaderOverflowPanel({
+  className: customClassName,
+  children,
+  label,
+  ...rest
+}, ref) {
+  const prefix = usePrefix();
+  const className = cx({
+    [`${prefix}--header-overflow-panel`]: true,
+    [customClassName]: !!customClassName
+  });
+  const isMd = useMatchMedia(mdMediaQuery);
+  return /*#__PURE__*/React__default.createElement(HeaderPopover, _extends({
+    ref: ref,
+    align: "bottom-end",
+    className: className
+  }, rest), /*#__PURE__*/React__default.createElement(HeaderPopoverButton, {
+    align: isMd ? 'bottom-end' : 'bottom',
+    label: label
+  }, _OverflowMenuVertical || (_OverflowMenuVertical = /*#__PURE__*/React__default.createElement(OverflowMenuVertical, null))), /*#__PURE__*/React__default.createElement(HeaderPopoverContent, null, /*#__PURE__*/React__default.createElement("ul", null, children)));
+});
+HeaderOverflowPanel.propTypes = {
+  /**
+   * Custom children to be rendered within the popover of the Profile menu
+   */
+  children: PropTypes.any,
+  /**
+   * Provide an optional class to be applied to the containing node
+   */
+  className: PropTypes.string,
+  /**
+   * Provide the Overflow panel's label
+   */
+  label: PropTypes.string
+};
+
+export { HeaderOverflowPanel };

package/es/components/Profile.js

@@ -30,7 +30,7 @@ const Profile = /*#__PURE__*/React__default.forwardRef(function Profile({
     align: "bottom-end",
     className: className
   }, rest), /*#__PURE__*/React__default.createElement(HeaderPopoverButton, {
-    align: "bottom",
+    align: "bottom-end",
     label: label
   }, IconElement), /*#__PURE__*/React__default.createElement(HeaderPopoverContent, null, children));
 });

package/es/components/SideNav.d.ts

@@ -38,6 +38,7 @@ export interface SideNavProps extends ComponentProps<'nav'>, TranslateWithId<Tra
     hideOverlay?: boolean;
     navType?: SIDE_NAV_TYPE;
     isTreeview?: boolean;
+    headerOverflowPanel?: boolean;
 }
 interface SideNavContextData {
     autoExpand?: boolean;
@@ -48,6 +49,7 @@ interface SideNavContextData {
     setIsTreeview?: (value: boolean) => void;
     currentPrimaryMenu?: string;
     setCurrentPrimaryMenu?: (value: string) => void;
+    headerOverflowPanel?: boolean;
 }
 export declare const SideNavContext: React.Context<SideNavContextData>;
 export declare const SideNav: React.ForwardRefExoticComponent<Omit<SideNavProps, "ref"> & React.RefAttributes<HTMLElement>>;

package/es/components/SideNav.js

@@ -68,6 +68,7 @@ function SideNavRenderFunction({
   isCollapsible = false,
   hideOverlay = false,
   translateWithId: t = defaultTranslateWithId,
+  headerOverflowPanel,
   ...other
 }, ref) {
   const [internalIsTreeview, setInternalIsTreeview] = useState(isTreeviewProp ?? false);
@@ -141,7 +142,7 @@ function SideNavRenderFunction({
   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) {
+      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 || item.closest(`.${prefix}--header-overflow-panel-secondary-container`)) {
         return;
       }
       item.tabIndex = -1;
@@ -168,7 +169,9 @@ function SideNavRenderFunction({
     }
   }, [prefix, internalIsTreeview, resetNodeTabIndices]);
   const smMediaQuery = `(min-width: ${breakpoints.sm.width})`;
-  const isSm = useMatchMedia(smMediaQuery);
+  const lgMediaQuery = `(min-width: ${breakpoints.lg.width})`;
+  const query = !headerOverflowPanel ? smMediaQuery : lgMediaQuery;
+  const isSm = useMatchMedia(query);
   useEffect(() => {
     if (sideNavRef.current) {
       const backButton = sideNavRef?.current.querySelector(`.${prefix}--side-nav__back-button`);
@@ -379,7 +382,6 @@ function SideNavRenderFunction({
       sideNavRef.current.focus();
     }
   });
-  const lgMediaQuery = `(min-width: ${breakpoints.lg.width})`;
   const isLg = useMatchMedia(lgMediaQuery);
 
   // ensure that changes are in sync with internal treeview prop
@@ -417,7 +419,8 @@ function SideNavRenderFunction({
       isTreeview: internalIsTreeview,
       setIsTreeview,
       currentPrimaryMenu,
-      setCurrentPrimaryMenu
+      setCurrentPrimaryMenu,
+      headerOverflowPanel
     }
   }, isFixedNav || hideOverlay || navType === SIDE_NAV_TYPE.RAIL_PANEL ? null :
   /*#__PURE__*/
@@ -458,84 +461,74 @@ SideNav.propTypes = {
    */
   addMouseListeners: PropTypes.bool,
   /**
-   * Optionally provide a custom class to apply to the underlying `<li>` node
+   * Optionally provide a custom class to apply to the `<nav>` element
    */
   className: PropTypes.string,
   /**
-   * If `true`, the SideNav will be open on initial render.
+   * Specify whether the `SideNav` starts expanded when initially rendered. Only applies when using the `SideNav` as an uncontrolled component.
    */
   defaultExpanded: PropTypes.bool,
   /**
-   * Specify the duration in milliseconds to delay before displaying the sidenavigation
+   * Specify the duration in milliseconds to delay before displaying the `SideNav`.
    */
   enterDelayMs: PropTypes.number,
   /**
-   * If `true`, the SideNav will be expanded, otherwise it will be collapsed.
-   * Using this prop causes SideNav to become a controled component.
+   * Control the expanded state of the `SideNav` externally. When provided, the `SideNav` becomes a controlled component and you must handle toggle events.
    */
   expanded: PropTypes.bool,
   /**
-   * If `true`, the overlay will be hidden. Defaults to `false`.
+   * Specify whether the `SideNav` is rendered inside a `HeaderOverflowPanel`. When `true`, adjusts the responsive behavior to work correctly within the overflow menu at mobile/tablet breakpoints.
+   */
+  headerOverflowPanel: PropTypes.bool,
+  /**
+   * If `true`, the backdrop overlay will be hidden at all breakpoints. By default, the overlay appears behind the `SideNav` on mobile and tablet (below `lg` breakpoint).
    */
   hideOverlay: PropTypes.bool,
   /**
-   * Specify the breakpoint at which the SideNav will be hidden.
-   * Can be one of `sm`, `md`, `lg`, `xlg`, or `max`.
-   * Only applies when `isRail` is `true`.
+   * Specify the breakpoint at which the `SideNav` will be hidden. Can be one of `sm`, `md`, `lg`, `xlg`, or `max`. Only applies when `isRail` is `true` or `navType` is `RAIL_PANEL`.
    */
   hideRailBreakpointDown: PropTypes.oneOf(['sm', 'md', 'lg', 'xlg', 'max']),
   /**
-   * Provide the `href` to the id of the element on your package that is the
-   * main content.
+   * Provide an `href` (typically an anchor like `#main-content`) to move focus to when closing the `SideNav` with the Escape key.
    */
   href: PropTypes.string,
   /**
-   * Optionally provide a custom class to apply to the underlying `<li>` node
+   * Specify whether the `SideNav` is the primary navigation controlled by the header. When `true`, the `SideNav` is part of the UI Shell header layout (full-width on desktop, collapses on mobile). Set to `false` for secondary navigation / rails, overflow panels, or standalone navigation that is independent of the header.
    */
   isChildOfHeader: PropTypes.bool,
   /**
-   * Specify whether the SideNav is collapsible at desktop
+   * Specify whether the `SideNav` can be toggled open/closed on desktop. When `true`, the `SideNav` starts collapsed and users can expand it. Requires `isChildOfHeader` to be `true` (default).
    */
   isCollapsible: PropTypes.bool,
   /**
-   * Specify if sideNav is standalone
+   * Specify if `SideNav` is standalone.
    */
   isFixedNav: PropTypes.bool,
   /**
-   * Specify if the sideNav will be persistent above the lg breakpoint
+   * Specify whether the `SideNav` is visible by default. When `false`, applies the hidden class which sets width to 0.
    */
   isPersistent: PropTypes.bool,
   /**
-   * Optional prop to display the side nav rail.
+   * Specify whether to display the `SideNav` rail variant. When `true`, the `SideNav` displays as a narrow rail (48px) that expands to full-width on hover.
    */
   isRail: PropTypes.bool,
   /**
-   * An optional listener that is called when the SideNav overlay is clicked
+   * An optional listener that is called when the `SideNav` overlay is clicked.
    *
    * @param {object} event
    */
   onOverlayClick: PropTypes.func,
   /**
-   * An optional listener that is called a callback to collapse the SideNav
+   * An optional listener that is called as a callback to collapse the `SideNav`.
    */
-
   onSideNavBlur: PropTypes.func,
   /**
-   * An optional listener that is called when an event that would cause
-   * toggling the SideNav occurs.
+   * An optional listener that is called when an event that would cause toggling the `SideNav` occurs.
    *
    * @param {object} event
    * @param {boolean} value
    */
   onToggle: PropTypes.func
-
-  /**
-   * Provide a custom function for translating all message ids within this
-   * component. This function will take in two arguments: the mesasge Id and the
-   * state of the component. From this, you should return a string representing
-   * the label you want displayed or read by screen readers.
-   */
-  // translateById: PropTypes.func,
 };
 
 export { SIDE_NAV_TYPE, SideNav, SideNavContext, translationIds };

package/es/components/SideNavMenu.js

@@ -25,6 +25,7 @@ import { useMatchMedia } from '../internal/useMatchMedia.js';
 
 var _ArrowLeft, _SharkFinIcon, _ChevronRight, _ChevronDown;
 const smMediaQuery = `(max-width: ${breakpoints.md.width})`;
+const mdMediaQuery = `(max-width: ${breakpoints.lg.width})`;
 const SideNavMenu = /*#__PURE__*/React__default.forwardRef(function SideNavMenu({
   backButtonRenderIcon = () => _ArrowLeft || (_ArrowLeft = /*#__PURE__*/React__default.createElement(ArrowLeft, {
     size: 16
@@ -50,7 +51,8 @@ const SideNavMenu = /*#__PURE__*/React__default.forwardRef(function SideNavMenu(
     expanded,
     navType,
     isRail,
-    setIsTreeview
+    setIsTreeview,
+    headerOverflowPanel
   } = useContext(SideNavContext);
   const sideNavExpanded = expanded;
   const prefix = usePrefix();
@@ -97,8 +99,6 @@ const SideNavMenu = /*#__PURE__*/React__default.forwardRef(function SideNavMenu(
     if (/*#__PURE__*/React__default.isValidElement(children)) {
       const props = children.props;
       if (props.isActive === true || props['aria-current']) {
-        // setActive(true);
-
         return true;
       }
     }
@@ -138,7 +138,7 @@ const SideNavMenu = /*#__PURE__*/React__default.forwardRef(function SideNavMenu(
     [`${prefix}--side-nav__submenu`]: true,
     [`${prefix}--side-nav__submenu--active`]: active || hasActiveDescendant && isExpanded
   });
-  const primaryClassNames = cx({
+  const secondaryClassNames = cx({
     [`${prefix}--side-nav__menu-secondary-wrapper`]: true,
     [`${prefix}--side-nav__menu-secondary-wrapper-expanded`]: isSideNavExpanded && isSecondaryOpen && currentPrimaryMenu === uniqueId
   });
@@ -301,7 +301,8 @@ const SideNavMenu = /*#__PURE__*/React__default.forwardRef(function SideNavMenu(
     }
   }, [sideNavExpanded]);
   const [openPopover, setOpenPopover] = React__default.useState(false);
-  const isSm = useMatchMedia(smMediaQuery);
+  const query = !headerOverflowPanel ? smMediaQuery : mdMediaQuery;
+  const isSm = useMatchMedia(query);
 
   // keeps the secondary open when moving from small to large breakpoints
   useEffect(() => {
@@ -355,8 +356,8 @@ const SideNavMenu = /*#__PURE__*/React__default.forwardRef(function SideNavMenu(
   })) : _ChevronDown || (_ChevronDown = /*#__PURE__*/React__default.createElement(ChevronDown, {
     size: 20
   })))), primary ? /*#__PURE__*/React__default.createElement(Layer, null, /*#__PURE__*/React__default.createElement("div", {
-    className: primaryClassNames
-  }, /*#__PURE__*/React__default.createElement(SideNavItems, {
+    className: secondaryClassNames
+  }, !headerOverflowPanel ? /*#__PURE__*/React__default.createElement(SideNavItems, {
     accessibilityLabel: {
       'aria-label': `${title} submenu`
     }
@@ -367,6 +368,15 @@ const SideNavMenu = /*#__PURE__*/React__default.forwardRef(function SideNavMenu(
     onClick: handleOnBackButtonClick,
     className: `${prefix}--side-nav__back-button`,
     renderIcon: backButtonRenderIcon
+  }, backButtonTitle), childrenToRender) : /*#__PURE__*/React__default.createElement("div", {
+    className: `${prefix}--header-overflow-panel-secondary-container`
+  }, /*#__PURE__*/React__default.createElement(Button, {
+    ref: backButtonRef,
+    kind: "ghost",
+    size: "md",
+    onClick: handleOnBackButtonClick,
+    className: `${prefix}--side-nav__back-button`,
+    renderIcon: backButtonRenderIcon
   }, backButtonTitle), childrenToRender))) : /*#__PURE__*/React__default.createElement("ul", {
     className: `${prefix}--side-nav__menu`,
     role: "group"

package/es/index.d.ts

@@ -18,5 +18,6 @@ export { SharkFinIcon } from './components/SharkFinIcon';
 export { HeaderDivider } from './components/HeaderDivider';
 export { TrialCountdown } from './components/TrialCountdown';
 export * as Profile from './components/Profile';
+export { HeaderOverflowPanel } from './components/HeaderOverflowPanel';
 export { SideNavSlot } from './components/SideNavSlot';
 export { SideNavTitle } from './components/SideNavTitle';

package/es/index.js

@@ -18,5 +18,6 @@ export { HeaderDivider } from './components/HeaderDivider.js';
 export { TrialCountdown } from './components/TrialCountdown.js';
 import * as Profile from './components/Profile.js';
 export { Profile };
+export { HeaderOverflowPanel } from './components/HeaderOverflowPanel.js';
 export { SideNavSlot } from './components/SideNavSlot.js';
 export { SideNavTitle } from './components/SideNavTitle.js';

package/lib/components/HeaderOverflowPanel.d.ts

@@ -0,0 +1,24 @@
+/**
+ * @license
+ *
+ * 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 React from 'react';
+export interface HeaderOverflowPanelProps {
+    /**
+     * Provide an optional class to be applied to the containing node
+     */
+    className?: string;
+    /**
+     * Custom children to be rendered within the popover of the Overflow panel menu
+     */
+    children?: React.ReactNode;
+    /**
+     * Provide the Overflow panel's label
+     */
+    label?: string;
+}
+export declare const HeaderOverflowPanel: React.ForwardRefExoticComponent<HeaderOverflowPanelProps & React.RefAttributes<HTMLDivElement>>;

package/lib/components/HeaderOverflowPanel.js

@@ -0,0 +1,58 @@
+/**
+ * Copyright IBM Corp. 2024
+ *
+ * This source code is licensed under the Apache-2.0 license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+'use strict';
+
+var _rollupPluginBabelHelpers = require('../_virtual/_rollupPluginBabelHelpers.js');
+var cx = require('classnames');
+var PropTypes = require('prop-types');
+var React__default = require('react');
+var usePrefix = require('../internal/usePrefix.js');
+var HeaderPopover = require('./HeaderPopover.js');
+var iconsReact = require('@carbon/icons-react');
+var useMatchMedia = require('../internal/useMatchMedia.js');
+var index = require('../node_modules/@carbon/layout/es/index.js');
+
+var _OverflowMenuVertical;
+const mdMediaQuery = `(max-width: ${index.breakpoints.md.width})`;
+const HeaderOverflowPanel = /*#__PURE__*/React__default.forwardRef(function HeaderOverflowPanel({
+  className: customClassName,
+  children,
+  label,
+  ...rest
+}, ref) {
+  const prefix = usePrefix.usePrefix();
+  const className = cx({
+    [`${prefix}--header-overflow-panel`]: true,
+    [customClassName]: !!customClassName
+  });
+  const isMd = useMatchMedia.useMatchMedia(mdMediaQuery);
+  return /*#__PURE__*/React__default.createElement(HeaderPopover.HeaderPopover, _rollupPluginBabelHelpers.extends({
+    ref: ref,
+    align: "bottom-end",
+    className: className
+  }, rest), /*#__PURE__*/React__default.createElement(HeaderPopover.HeaderPopoverButton, {
+    align: isMd ? 'bottom-end' : 'bottom',
+    label: label
+  }, _OverflowMenuVertical || (_OverflowMenuVertical = /*#__PURE__*/React__default.createElement(iconsReact.OverflowMenuVertical, null))), /*#__PURE__*/React__default.createElement(HeaderPopover.HeaderPopoverContent, null, /*#__PURE__*/React__default.createElement("ul", null, children)));
+});
+HeaderOverflowPanel.propTypes = {
+  /**
+   * Custom children to be rendered within the popover of the Profile menu
+   */
+  children: PropTypes.any,
+  /**
+   * Provide an optional class to be applied to the containing node
+   */
+  className: PropTypes.string,
+  /**
+   * Provide the Overflow panel's label
+   */
+  label: PropTypes.string
+};
+
+exports.HeaderOverflowPanel = HeaderOverflowPanel;

package/lib/components/Profile.js

@@ -32,7 +32,7 @@ const Profile = /*#__PURE__*/React__default.forwardRef(function Profile({
     align: "bottom-end",
     className: className
   }, rest), /*#__PURE__*/React__default.createElement(HeaderPopover.HeaderPopoverButton, {
-    align: "bottom",
+    align: "bottom-end",
     label: label
   }, IconElement), /*#__PURE__*/React__default.createElement(HeaderPopover.HeaderPopoverContent, null, children));
 });

package/lib/components/SideNav.d.ts

@@ -38,6 +38,7 @@ export interface SideNavProps extends ComponentProps<'nav'>, TranslateWithId<Tra
     hideOverlay?: boolean;
     navType?: SIDE_NAV_TYPE;
     isTreeview?: boolean;
+    headerOverflowPanel?: boolean;
 }
 interface SideNavContextData {
     autoExpand?: boolean;
@@ -48,6 +49,7 @@ interface SideNavContextData {
     setIsTreeview?: (value: boolean) => void;
     currentPrimaryMenu?: string;
     setCurrentPrimaryMenu?: (value: string) => void;
+    headerOverflowPanel?: boolean;
 }
 export declare const SideNavContext: React.Context<SideNavContextData>;
 export declare const SideNav: React.ForwardRefExoticComponent<Omit<SideNavProps, "ref"> & React.RefAttributes<HTMLElement>>;

package/lib/components/SideNav.js

@@ -70,6 +70,7 @@ function SideNavRenderFunction({
   isCollapsible = false,
   hideOverlay = false,
   translateWithId: t = defaultTranslateWithId,
+  headerOverflowPanel,
   ...other
 }, ref) {
   const [internalIsTreeview, setInternalIsTreeview] = React__default.useState(isTreeviewProp ?? false);
@@ -143,7 +144,7 @@ function SideNavRenderFunction({
   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) {
+      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 || item.closest(`.${prefix}--header-overflow-panel-secondary-container`)) {
         return;
       }
       item.tabIndex = -1;
@@ -170,7 +171,9 @@ function SideNavRenderFunction({
     }
   }, [prefix, internalIsTreeview, resetNodeTabIndices]);
   const smMediaQuery = `(min-width: ${index.breakpoints.sm.width})`;
-  const isSm = useMatchMedia.useMatchMedia(smMediaQuery);
+  const lgMediaQuery = `(min-width: ${index.breakpoints.lg.width})`;
+  const query = !headerOverflowPanel ? smMediaQuery : lgMediaQuery;
+  const isSm = useMatchMedia.useMatchMedia(query);
   React__default.useEffect(() => {
     if (sideNavRef.current) {
       const backButton = sideNavRef?.current.querySelector(`.${prefix}--side-nav__back-button`);
@@ -381,7 +384,6 @@ function SideNavRenderFunction({
       sideNavRef.current.focus();
     }
   });
-  const lgMediaQuery = `(min-width: ${index.breakpoints.lg.width})`;
   const isLg = useMatchMedia.useMatchMedia(lgMediaQuery);
 
   // ensure that changes are in sync with internal treeview prop
@@ -419,7 +421,8 @@ function SideNavRenderFunction({
       isTreeview: internalIsTreeview,
       setIsTreeview,
       currentPrimaryMenu,
-      setCurrentPrimaryMenu
+      setCurrentPrimaryMenu,
+      headerOverflowPanel
     }
   }, isFixedNav || hideOverlay || navType === SIDE_NAV_TYPE.RAIL_PANEL ? null :
   /*#__PURE__*/
@@ -460,84 +463,74 @@ SideNav.propTypes = {
    */
   addMouseListeners: PropTypes.bool,
   /**
-   * Optionally provide a custom class to apply to the underlying `<li>` node
+   * Optionally provide a custom class to apply to the `<nav>` element
    */
   className: PropTypes.string,
   /**
-   * If `true`, the SideNav will be open on initial render.
+   * Specify whether the `SideNav` starts expanded when initially rendered. Only applies when using the `SideNav` as an uncontrolled component.
    */
   defaultExpanded: PropTypes.bool,
   /**
-   * Specify the duration in milliseconds to delay before displaying the sidenavigation
+   * Specify the duration in milliseconds to delay before displaying the `SideNav`.
    */
   enterDelayMs: PropTypes.number,
   /**
-   * If `true`, the SideNav will be expanded, otherwise it will be collapsed.
-   * Using this prop causes SideNav to become a controled component.
+   * Control the expanded state of the `SideNav` externally. When provided, the `SideNav` becomes a controlled component and you must handle toggle events.
    */
   expanded: PropTypes.bool,
   /**
-   * If `true`, the overlay will be hidden. Defaults to `false`.
+   * Specify whether the `SideNav` is rendered inside a `HeaderOverflowPanel`. When `true`, adjusts the responsive behavior to work correctly within the overflow menu at mobile/tablet breakpoints.
+   */
+  headerOverflowPanel: PropTypes.bool,
+  /**
+   * If `true`, the backdrop overlay will be hidden at all breakpoints. By default, the overlay appears behind the `SideNav` on mobile and tablet (below `lg` breakpoint).
    */
   hideOverlay: PropTypes.bool,
   /**
-   * Specify the breakpoint at which the SideNav will be hidden.
-   * Can be one of `sm`, `md`, `lg`, `xlg`, or `max`.
-   * Only applies when `isRail` is `true`.
+   * Specify the breakpoint at which the `SideNav` will be hidden. Can be one of `sm`, `md`, `lg`, `xlg`, or `max`. Only applies when `isRail` is `true` or `navType` is `RAIL_PANEL`.
    */
   hideRailBreakpointDown: PropTypes.oneOf(['sm', 'md', 'lg', 'xlg', 'max']),
   /**
-   * Provide the `href` to the id of the element on your package that is the
-   * main content.
+   * Provide an `href` (typically an anchor like `#main-content`) to move focus to when closing the `SideNav` with the Escape key.
    */
   href: PropTypes.string,
   /**
-   * Optionally provide a custom class to apply to the underlying `<li>` node
+   * Specify whether the `SideNav` is the primary navigation controlled by the header. When `true`, the `SideNav` is part of the UI Shell header layout (full-width on desktop, collapses on mobile). Set to `false` for secondary navigation / rails, overflow panels, or standalone navigation that is independent of the header.
    */
   isChildOfHeader: PropTypes.bool,
   /**
-   * Specify whether the SideNav is collapsible at desktop
+   * Specify whether the `SideNav` can be toggled open/closed on desktop. When `true`, the `SideNav` starts collapsed and users can expand it. Requires `isChildOfHeader` to be `true` (default).
    */
   isCollapsible: PropTypes.bool,
   /**
-   * Specify if sideNav is standalone
+   * Specify if `SideNav` is standalone.
    */
   isFixedNav: PropTypes.bool,
   /**
-   * Specify if the sideNav will be persistent above the lg breakpoint
+   * Specify whether the `SideNav` is visible by default. When `false`, applies the hidden class which sets width to 0.
    */
   isPersistent: PropTypes.bool,
   /**
-   * Optional prop to display the side nav rail.
+   * Specify whether to display the `SideNav` rail variant. When `true`, the `SideNav` displays as a narrow rail (48px) that expands to full-width on hover.
    */
   isRail: PropTypes.bool,
   /**
-   * An optional listener that is called when the SideNav overlay is clicked
+   * An optional listener that is called when the `SideNav` overlay is clicked.
    *
    * @param {object} event
    */
   onOverlayClick: PropTypes.func,
   /**
-   * An optional listener that is called a callback to collapse the SideNav
+   * An optional listener that is called as a callback to collapse the `SideNav`.
    */
-
   onSideNavBlur: PropTypes.func,
   /**
-   * An optional listener that is called when an event that would cause
-   * toggling the SideNav occurs.
+   * An optional listener that is called when an event that would cause toggling the `SideNav` occurs.
    *
    * @param {object} event
    * @param {boolean} value
    */
   onToggle: PropTypes.func
-
-  /**
-   * Provide a custom function for translating all message ids within this
-   * component. This function will take in two arguments: the mesasge Id and the
-   * state of the component. From this, you should return a string representing
-   * the label you want displayed or read by screen readers.
-   */
-  // translateById: PropTypes.func,
 };
 
 exports.SIDE_NAV_TYPE = SIDE_NAV_TYPE;

package/lib/components/SideNavMenu.js

@@ -27,6 +27,7 @@ var useMatchMedia = require('../internal/useMatchMedia.js');
 
 var _ArrowLeft, _SharkFinIcon, _ChevronRight, _ChevronDown;
 const smMediaQuery = `(max-width: ${index.breakpoints.md.width})`;
+const mdMediaQuery = `(max-width: ${index.breakpoints.lg.width})`;
 const SideNavMenu = /*#__PURE__*/React__default.forwardRef(function SideNavMenu({
   backButtonRenderIcon = () => _ArrowLeft || (_ArrowLeft = /*#__PURE__*/React__default.createElement(iconsReact.ArrowLeft, {
     size: 16
@@ -52,7 +53,8 @@ const SideNavMenu = /*#__PURE__*/React__default.forwardRef(function SideNavMenu(
     expanded,
     navType,
     isRail,
-    setIsTreeview
+    setIsTreeview,
+    headerOverflowPanel
   } = React__default.useContext(SideNav.SideNavContext);
   const sideNavExpanded = expanded;
   const prefix = usePrefix.usePrefix();
@@ -99,8 +101,6 @@ const SideNavMenu = /*#__PURE__*/React__default.forwardRef(function SideNavMenu(
     if (/*#__PURE__*/React__default.isValidElement(children)) {
       const props = children.props;
       if (props.isActive === true || props['aria-current']) {
-        // setActive(true);
-
         return true;
       }
     }
@@ -140,7 +140,7 @@ const SideNavMenu = /*#__PURE__*/React__default.forwardRef(function SideNavMenu(
     [`${prefix}--side-nav__submenu`]: true,
     [`${prefix}--side-nav__submenu--active`]: active || hasActiveDescendant && isExpanded
   });
-  const primaryClassNames = cx({
+  const secondaryClassNames = cx({
     [`${prefix}--side-nav__menu-secondary-wrapper`]: true,
     [`${prefix}--side-nav__menu-secondary-wrapper-expanded`]: isSideNavExpanded && isSecondaryOpen && currentPrimaryMenu === uniqueId
   });
@@ -303,7 +303,8 @@ const SideNavMenu = /*#__PURE__*/React__default.forwardRef(function SideNavMenu(
     }
   }, [sideNavExpanded]);
   const [openPopover, setOpenPopover] = React__default.useState(false);
-  const isSm = useMatchMedia.useMatchMedia(smMediaQuery);
+  const query = !headerOverflowPanel ? smMediaQuery : mdMediaQuery;
+  const isSm = useMatchMedia.useMatchMedia(query);
 
   // keeps the secondary open when moving from small to large breakpoints
   React__default.useEffect(() => {
@@ -357,8 +358,8 @@ const SideNavMenu = /*#__PURE__*/React__default.forwardRef(function SideNavMenu(
   })) : _ChevronDown || (_ChevronDown = /*#__PURE__*/React__default.createElement(iconsReact.ChevronDown, {
     size: 20
   })))), primary ? /*#__PURE__*/React__default.createElement(react.Layer, null, /*#__PURE__*/React__default.createElement("div", {
-    className: primaryClassNames
-  }, /*#__PURE__*/React__default.createElement(SideNavItems.SideNavItems, {
+    className: secondaryClassNames
+  }, !headerOverflowPanel ? /*#__PURE__*/React__default.createElement(SideNavItems.SideNavItems, {
     accessibilityLabel: {
       'aria-label': `${title} submenu`
     }
@@ -369,6 +370,15 @@ const SideNavMenu = /*#__PURE__*/React__default.forwardRef(function SideNavMenu(
     onClick: handleOnBackButtonClick,
     className: `${prefix}--side-nav__back-button`,
     renderIcon: backButtonRenderIcon
+  }, backButtonTitle), childrenToRender) : /*#__PURE__*/React__default.createElement("div", {
+    className: `${prefix}--header-overflow-panel-secondary-container`
+  }, /*#__PURE__*/React__default.createElement(react.Button, {
+    ref: backButtonRef,
+    kind: "ghost",
+    size: "md",
+    onClick: handleOnBackButtonClick,
+    className: `${prefix}--side-nav__back-button`,
+    renderIcon: backButtonRenderIcon
   }, backButtonTitle), childrenToRender))) : /*#__PURE__*/React__default.createElement("ul", {
     className: `${prefix}--side-nav__menu`,
     role: "group"

package/lib/index.d.ts

@@ -18,5 +18,6 @@ export { SharkFinIcon } from './components/SharkFinIcon';
 export { HeaderDivider } from './components/HeaderDivider';
 export { TrialCountdown } from './components/TrialCountdown';
 export * as Profile from './components/Profile';
+export { HeaderOverflowPanel } from './components/HeaderOverflowPanel';
 export { SideNavSlot } from './components/SideNavSlot';
 export { SideNavTitle } from './components/SideNavTitle';

package/lib/index.js

@@ -19,6 +19,7 @@ var SharkFinIcon = require('./components/SharkFinIcon.js');
 var HeaderDivider = require('./components/HeaderDivider.js');
 var TrialCountdown = require('./components/TrialCountdown.js');
 var Profile = require('./components/Profile.js');
+var HeaderOverflowPanel = require('./components/HeaderOverflowPanel.js');
 var SideNavSlot = require('./components/SideNavSlot.js');
 var SideNavTitle = require('./components/SideNavTitle.js');
 
@@ -40,5 +41,6 @@ exports.SharkFinIcon = SharkFinIcon.SharkFinIcon;
 exports.HeaderDivider = HeaderDivider.HeaderDivider;
 exports.TrialCountdown = TrialCountdown.TrialCountdown;
 exports.Profile = Profile;
+exports.HeaderOverflowPanel = HeaderOverflowPanel.HeaderOverflowPanel;
 exports.SideNavSlot = SideNavSlot.SideNavSlot;
 exports.SideNavTitle = SideNavTitle.SideNavTitle;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@carbon-labs/react-ui-shell",
-  "version": "0.82.0",
+  "version": "0.84.0",
   "publishConfig": {
     "access": "public",
     "provenance": true
@@ -42,5 +42,5 @@
   "dependencies": {
     "@ibm/telemetry-js": "^1.10.2"
   },
-  "gitHead": "5520cf06630215524af572ddea13596eaf8a0811"
+  "gitHead": "a0eaa1502bff6b7ee998a43d67e260a4ede0e2eb"
 }

package/scss/styles/_header-overflow-panel.scss

@@ -0,0 +1,105 @@
+/**
+ * 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.
+ */
+
+@use '@carbon/styles/scss/spacing' as *;
+@use '@carbon/styles/scss/theme' as *;
+@use '@carbon/react/scss/utilities/convert' as convert;
+@use '@carbon/styles/scss/breakpoint' as *;
+@use '@carbon/styles/scss/type' as *;
+
+$prefix: 'cds' !default;
+
+@include breakpoint-up(lg) {
+  .#{$prefix}--header-overflow-panel {
+    display: none;
+  }
+}
+
+// COPIED FROM SIDE NAV BUT NOW AT LG BREAKPOINT
+@include breakpoint-down(lg) {
+  .#{$prefix}--header-overflow-panel
+    .#{$prefix}--side-nav--collapsible.#{$prefix}--side-nav--expanded {
+    inline-size: 100%;
+    max-inline-size: 100%;
+  }
+
+  .#{$prefix}--header-overflow-panel
+    .#{$prefix}--header-overflow-panel-secondary-container {
+    padding-block-start: $spacing-05;
+  }
+
+  .#{$prefix}--header-overflow-panel
+    .#{$prefix}--side-nav__menu-secondary-wrapper-expanded {
+    z-index: 1;
+    background-color: $background;
+    inline-size: 100%;
+    inset-inline-start: 0;
+  }
+
+  .#{$prefix}--header-overflow-panel
+    .#{$prefix}--side-nav__back-button.#{$prefix}--btn--ghost {
+    flex-direction: row-reverse;
+    justify-content: flex-end;
+    gap: 1rem;
+    inline-size: 100%;
+    max-inline-size: 100%;
+
+    &:focus {
+      box-shadow: inset 0 0 0 1px $focus;
+    }
+  }
+
+  .#{$prefix}--header-overflow-panel
+    .#{$prefix}--side-nav__back-button.#{$prefix}--btn--ghost:not([disabled]) {
+    svg {
+      align-self: center;
+      fill: $icon-interactive;
+    }
+
+    &:hover svg {
+      fill: $link-primary-hover;
+    }
+  }
+
+  .#{$prefix}--header-overflow-panel .#{$prefix}--side-nav__item {
+    .#{$prefix}--side-nav__link,
+    .#{$prefix}--side-nav__submenu {
+      block-size: $spacing-08;
+    }
+  }
+}
+
+@include breakpoint(md) {
+  .#{$prefix}--header-overflow-panel.#{$prefix}--popover--tab-tip.#{$prefix}--popover--bottom-end
+    .#{$prefix}--popover
+    > .#{$prefix}--header-action__content.#{$prefix}--popover-content {
+    inset-inline-end: -$spacing-09;
+  }
+}
+
+.#{$prefix}--header-overflow-panel .#{$prefix}--toggletip-content {
+  padding: 0;
+  background-color: $background;
+  block-size: 100vh;
+  border-block-end: 1px solid $border-subtle;
+  border-inline-start: 1px solid $border-subtle;
+  gap: 0;
+  inline-size: convert.to-rem(256px);
+  overflow-y: auto;
+
+  > * {
+    padding: $spacing-05;
+    outline: convert.to-rem(0.5px) solid $border-subtle;
+  }
+}
+
+.#{$prefix}--header-overflow-panel .#{$prefix}--side-nav__link-text {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  inline-size: 100%;
+}

package/scss/styles/_profile.scss

@@ -15,10 +15,12 @@
 $prefix: 'cds' !default;
 
 // profile
+
 .#{$prefix}--profile.#{$prefix}--popover--open {
   background-color: $background;
 }
 
+.#{$prefix}--header-overflow-panel .#{$prefix}--toggletip-content,
 .#{$prefix}--profile .#{$prefix}--toggletip-content {
   padding: 0;
   background-color: $background;
@@ -28,15 +30,21 @@ $prefix: 'cds' !default;
   inline-size: convert.to-rem(256px);
   max-block-size: 100vh;
   overflow-y: auto;
+}
 
-  > * {
+.#{$prefix}--header-overflow-panel,
+.#{$prefix}--profile {
+  .#{$prefix}--profile-user-info,
+  .#{$prefix}--profile-read-only,
+  .clabs--theme-settings {
     padding: $spacing-05;
-    outline: convert.to-rem(0.5px) solid $border-subtle;
+    border-block-end: convert.to-rem(0.5px) solid $border-subtle;
+    border-block-start: convert.to-rem(0.5px) solid $border-subtle;
   }
 }
 
 // user-info
-.#{$prefix}--profile .#{$prefix}--profile-user-info {
+.#{$prefix}--profile-user-info {
   display: flex;
 }
 

package/scss/styles/_side-nav.scss

@@ -133,7 +133,7 @@ div:has(.#{$prefix}--header)
       block-size: $spacing-08;
     }
 
-    .#{$prefix}--side-nav__icon {
+    .#{$prefix}--side-nav__menu-secondary-wrapper .#{$prefix}--side-nav__icon {
       margin-inline-end: convert.to-rem(14px);
     }
 

package/scss/ui-shell.scss

@@ -10,5 +10,6 @@
 @use 'styles/content';
 @use 'styles/shark-fin-icon.scss';
 @use 'styles/header-divider.scss';
+@use 'styles/header-overflow-panel.scss';
 @use 'styles/trial-countdown.scss';
 @use 'styles/profile.scss';