From 6afdc06f9eafa9c16e7e6fac41e77937bdff2fd8 Mon Sep 17 00:00:00 2001
From: Patrick Pircher <patrick.pircher@ibm.com>
Date: Wed, 29 Jul 2026 16:27:10 +0200
Subject: [PATCH 1/5] feat: implement remaining UIShell sub-components

Adds HeaderMenu/HeaderMenuItem (dropdown submenus in the top Header nav),
HeaderPanel and the top-level Switcher/SwitcherItem/SwitcherDivider (app
switcher panel), SideNavHeader/SideNavDetails/SideNavIcon, and
HeaderSideNavItems (mirrors header items into the side nav). Also adds
HeaderContainer, a stateful wrapper that manages isSideNavExpanded and
collapses it on Escape so consumers no longer have to manage that state
themselves.

Closes #638

Signed-off-by: Patrick Pircher <patrick.pircher@ibm.com>
---
 .parity-check-data.json                       |   2 +-
 carbon-components-ember/package.json          |  11 ++
 .../src/components/ui-shell.gts               |  15 +-
 .../components/ui-shell/-header-container.gts |  49 ++++++
 .../src/components/ui-shell/-header.gts       |   3 +
 .../ui-shell/-header/-menu-item.gts           |  30 ++++
 .../src/components/ui-shell/-header/-menu.gts |  55 ++++++
 .../components/ui-shell/-header/-panel.gts    |  32 ++++
 .../ui-shell/-header/-side-nav-items.gts      |  23 +++
 .../src/components/ui-shell/-nav.gts          |   5 +-
 .../src/components/ui-shell/-sidenav.gts      |  15 +-
 .../components/ui-shell/-sidenav/-details.gts |  22 +++
 .../components/ui-shell/-sidenav/-header.gts  |  24 +++
 .../components/ui-shell/-sidenav/-icon.gts    |  22 +++
 .../src/components/ui-shell/-switcher.gts     |  27 +++
 .../ui-shell/-switcher/-divider.gts           |  13 ++
 .../components/ui-shell/-switcher/-item.gts   |  29 ++++
 .../app/templates/2-components/ui-shell.md    | 157 ++++++++++++++++++
 test-app/tests/components/ui-shell-test.gts   | 129 ++++++++++++++
 19 files changed, 657 insertions(+), 6 deletions(-)
 create mode 100644 carbon-components-ember/src/components/ui-shell/-header-container.gts
 create mode 100644 carbon-components-ember/src/components/ui-shell/-header/-menu-item.gts
 create mode 100644 carbon-components-ember/src/components/ui-shell/-header/-menu.gts
 create mode 100644 carbon-components-ember/src/components/ui-shell/-header/-panel.gts
 create mode 100644 carbon-components-ember/src/components/ui-shell/-header/-side-nav-items.gts
 create mode 100644 carbon-components-ember/src/components/ui-shell/-sidenav/-details.gts
 create mode 100644 carbon-components-ember/src/components/ui-shell/-sidenav/-header.gts
 create mode 100644 carbon-components-ember/src/components/ui-shell/-sidenav/-icon.gts
 create mode 100644 carbon-components-ember/src/components/ui-shell/-switcher.gts
 create mode 100644 carbon-components-ember/src/components/ui-shell/-switcher/-divider.gts
 create mode 100644 carbon-components-ember/src/components/ui-shell/-switcher/-item.gts

diff --git a/.parity-check-data.json b/.parity-check-data.json
index 011dd1a60..37a94d95b 100644
--- a/.parity-check-data.json
+++ b/.parity-check-data.json
@@ -572,7 +572,7 @@
     },
     "UIShell": {
       "lastCheckedCommit": "5102bd860864c2580048183ffaf50d1ffd4400b5",
-      "lastSyncedCommit": "N/A",
+      "lastSyncedCommit": "5102bd860864c2580048183ffaf50d1ffd4400b5",
       "hasChanges": false,
       "changeCount": 0,
       "lastUpdate": null
diff --git a/carbon-components-ember/package.json b/carbon-components-ember/package.json
index d4d2dc17b..7cf59f98c 100644
--- a/carbon-components-ember/package.json
+++ b/carbon-components-ember/package.json
@@ -2968,15 +2968,26 @@
       "./components/carbon/tooltip.js": "./dist/_app_/components/carbon/tooltip.js",
       "./components/carbon/tree-view.js": "./dist/_app_/components/carbon/tree-view.js",
       "./components/carbon/ui-shell.js": "./dist/_app_/components/carbon/ui-shell.js",
+      "./components/carbon/ui-shell/-header-container.js": "./dist/_app_/components/carbon/ui-shell/-header-container.js",
       "./components/carbon/ui-shell/-header.js": "./dist/_app_/components/carbon/ui-shell/-header.js",
       "./components/carbon/ui-shell/-header/-global-action.js": "./dist/_app_/components/carbon/ui-shell/-header/-global-action.js",
+      "./components/carbon/ui-shell/-header/-menu-item.js": "./dist/_app_/components/carbon/ui-shell/-header/-menu-item.js",
+      "./components/carbon/ui-shell/-header/-menu.js": "./dist/_app_/components/carbon/ui-shell/-header/-menu.js",
+      "./components/carbon/ui-shell/-header/-panel.js": "./dist/_app_/components/carbon/ui-shell/-header/-panel.js",
+      "./components/carbon/ui-shell/-header/-side-nav-items.js": "./dist/_app_/components/carbon/ui-shell/-header/-side-nav-items.js",
       "./components/carbon/ui-shell/-nav.js": "./dist/_app_/components/carbon/ui-shell/-nav.js",
       "./components/carbon/ui-shell/-nav/-item.js": "./dist/_app_/components/carbon/ui-shell/-nav/-item.js",
       "./components/carbon/ui-shell/-sidenav.js": "./dist/_app_/components/carbon/ui-shell/-sidenav.js",
+      "./components/carbon/ui-shell/-sidenav/-details.js": "./dist/_app_/components/carbon/ui-shell/-sidenav/-details.js",
       "./components/carbon/ui-shell/-sidenav/-divider.js": "./dist/_app_/components/carbon/ui-shell/-sidenav/-divider.js",
       "./components/carbon/ui-shell/-sidenav/-footer.js": "./dist/_app_/components/carbon/ui-shell/-sidenav/-footer.js",
+      "./components/carbon/ui-shell/-sidenav/-header.js": "./dist/_app_/components/carbon/ui-shell/-sidenav/-header.js",
+      "./components/carbon/ui-shell/-sidenav/-icon.js": "./dist/_app_/components/carbon/ui-shell/-sidenav/-icon.js",
       "./components/carbon/ui-shell/-sidenav/-menu.js": "./dist/_app_/components/carbon/ui-shell/-sidenav/-menu.js",
       "./components/carbon/ui-shell/-sidenav/-sub-menu.js": "./dist/_app_/components/carbon/ui-shell/-sidenav/-sub-menu.js",
+      "./components/carbon/ui-shell/-switcher.js": "./dist/_app_/components/carbon/ui-shell/-switcher.js",
+      "./components/carbon/ui-shell/-switcher/-divider.js": "./dist/_app_/components/carbon/ui-shell/-switcher/-divider.js",
+      "./components/carbon/ui-shell/-switcher/-item.js": "./dist/_app_/components/carbon/ui-shell/-switcher/-item.js",
       "./components/carbon/unordered-list.js": "./dist/_app_/components/carbon/unordered-list.js",
       "./helpers/carbon/default-to.js": "./dist/_app_/helpers/carbon/default-to.js",
       "./helpers/carbon/generic.js": "./dist/_app_/helpers/carbon/generic.js",
diff --git a/carbon-components-ember/src/components/ui-shell.gts b/carbon-components-ember/src/components/ui-shell.gts
index e718bb61b..df6d6d15d 100644
--- a/carbon-components-ember/src/components/ui-shell.gts
+++ b/carbon-components-ember/src/components/ui-shell.gts
@@ -1,6 +1,8 @@
 import { default as Header } from './ui-shell/-header.gts';
 import { default as Sidenav } from './ui-shell/-sidenav.gts';
 import { default as Nav } from './ui-shell/-nav.gts';
+import { default as Switcher } from './ui-shell/-switcher.gts';
+import { default as HeaderContainer } from './ui-shell/-header-container.gts';
 import Component from '@glimmer/component';
 import UIShellHeader from './ui-shell/-header.gts';
 import { hash } from '@ember/helper';
@@ -12,6 +14,8 @@ export interface UIShellSignature {
         Header: typeof UIShellHeader;
         Sidenav: typeof Sidenav;
         Nav: typeof Nav;
+        Switcher: typeof Switcher;
+        HeaderContainer: typeof HeaderContainer;
       },
     ];
     content: [];
@@ -20,7 +24,16 @@ export interface UIShellSignature {
 
 export default class UIShell extends Component<UIShellSignature> {
   <template>
-    {{yield (hash Header=Header Sidenav=Sidenav Nav=Nav) to='shell'}}
+    {{yield
+      (hash
+        Header=Header
+        Sidenav=Sidenav
+        Nav=Nav
+        Switcher=Switcher
+        HeaderContainer=HeaderContainer
+      )
+      to='shell'
+    }}
     <main id='main-content' class='cds--content'>
       {{yield to='content'}}
     </main>
diff --git a/carbon-components-ember/src/components/ui-shell/-header-container.gts b/carbon-components-ember/src/components/ui-shell/-header-container.gts
new file mode 100644
index 000000000..4b4ede8fb
--- /dev/null
+++ b/carbon-components-ember/src/components/ui-shell/-header-container.gts
@@ -0,0 +1,49 @@
+import Component from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import { registerDestructor } from '@ember/destroyable';
+import { hash } from '@ember/helper';
+
+export interface UIShellHeaderContainerSignature {
+  Args: {
+    isSideNavExpanded?: boolean;
+  };
+  Blocks: {
+    default: [
+      {
+        isSideNavExpanded: boolean;
+        onClickSideNavExpand: () => void;
+      },
+    ];
+  };
+}
+
+export default class UIShellHeaderContainer extends Component<UIShellHeaderContainerSignature> {
+  @tracked isSideNavExpanded = this.args.isSideNavExpanded ?? false;
+
+  constructor(owner: any, args: UIShellHeaderContainerSignature['Args']) {
+    super(owner, args);
+    window.addEventListener('keydown', this.handleWindowKeydown);
+    registerDestructor(this, () => {
+      window.removeEventListener('keydown', this.handleWindowKeydown);
+    });
+  }
+
+  handleWindowKeydown = (event: KeyboardEvent) => {
+    if (event.key === 'Escape') {
+      this.isSideNavExpanded = false;
+    }
+  };
+
+  onClickSideNavExpand = () => {
+    this.isSideNavExpanded = !this.isSideNavExpanded;
+  };
+
+  <template>
+    {{yield
+      (hash
+        isSideNavExpanded=this.isSideNavExpanded
+        onClickSideNavExpand=this.onClickSideNavExpand
+      )
+    }}
+  </template>
+}
diff --git a/carbon-components-ember/src/components/ui-shell/-header.gts b/carbon-components-ember/src/components/ui-shell/-header.gts
index a04003c5e..ce4edf770 100644
--- a/carbon-components-ember/src/components/ui-shell/-header.gts
+++ b/carbon-components-ember/src/components/ui-shell/-header.gts
@@ -4,6 +4,7 @@ import { on } from '@ember/modifier';
 import { fn } from '@ember/helper';
 import Component from '@glimmer/component';
 import UIShellHeaderGlobalAction from './-header/-global-action.gts';
+import UIShellHeaderPanel from './-header/-panel.gts';
 
 export interface UIShellHeaderSignature {
   Args: {
@@ -15,6 +16,7 @@ export interface UIShellHeaderSignature {
   Blocks: {
     header: [];
     headerGlobal: [typeof UIShellHeaderGlobalAction];
+    headerPanel: [typeof UIShellHeaderPanel];
   };
 }
 
@@ -48,6 +50,7 @@ export default class UIShellHeader extends Component<UIShellHeaderSignature> {
       <div class='cds--header__global'>
         {{yield UIShellHeaderGlobalAction to='headerGlobal'}}
       </div>
+      {{yield UIShellHeaderPanel to='headerPanel'}}
     </header>
   </template>
 }
diff --git a/carbon-components-ember/src/components/ui-shell/-header/-menu-item.gts b/carbon-components-ember/src/components/ui-shell/-header/-menu-item.gts
new file mode 100644
index 000000000..e893405a0
--- /dev/null
+++ b/carbon-components-ember/src/components/ui-shell/-header/-menu-item.gts
@@ -0,0 +1,30 @@
+import Component from '@glimmer/component';
+
+export interface UIShellHeaderMenuItemSignature {
+  Element: HTMLAnchorElement;
+  Args: {
+    isActive?: boolean;
+  };
+  Blocks: {
+    default: [];
+  };
+}
+
+export default class UIShellHeaderMenuItem extends Component<UIShellHeaderMenuItemSignature> {
+  <template>
+    <li>
+      <a
+        class='cds--header__menu-item
+          {{if @isActive "cds--header__menu-item--current"}}'
+        href='#'
+        tabindex='0'
+        aria-current='{{if @isActive "page"}}'
+        ...attributes
+      >
+        <span class='cds--text-truncate--end'>
+          {{yield}}
+        </span>
+      </a>
+    </li>
+  </template>
+}
diff --git a/carbon-components-ember/src/components/ui-shell/-header/-menu.gts b/carbon-components-ember/src/components/ui-shell/-header/-menu.gts
new file mode 100644
index 000000000..d6193cc0b
--- /dev/null
+++ b/carbon-components-ember/src/components/ui-shell/-header/-menu.gts
@@ -0,0 +1,55 @@
+import Component from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import { on } from '@ember/modifier';
+import { ChevronDown } from '../../../icons.ts';
+import UIShellHeaderMenuItem from './-menu-item.gts';
+
+export interface UIShellHeaderMenuSignature {
+  Element: HTMLLIElement;
+  Args: {
+    'aria-label'?: string;
+    'aria-labelledby'?: string;
+    menuLinkName: string;
+    isActive?: boolean;
+  };
+  Blocks: {
+    default: [typeof UIShellHeaderMenuItem];
+  };
+}
+
+export default class UIShellHeaderMenu extends Component<UIShellHeaderMenuSignature> {
+  @tracked expanded = false;
+
+  toggleExpanded = () => {
+    this.expanded = !this.expanded;
+  };
+
+  <template>
+    <li
+      class='cds--header__submenu
+        {{if @isActive "cds--header__menu-item--current"}}'
+      ...attributes
+    >
+      <a
+        aria-haspopup='menu'
+        aria-expanded='{{if this.expanded "true" "false"}}'
+        aria-label={{@aria-label}}
+        aria-labelledby={{@aria-labelledby}}
+        class='cds--header__menu-item cds--header__menu-title'
+        href='#'
+        tabindex='0'
+        {{on 'click' this.toggleExpanded}}
+      >
+        {{@menuLinkName}}
+        <ChevronDown @svgClass='cds--header__menu-arrow' />
+      </a>
+      <ul
+        aria-label={{@aria-label}}
+        aria-labelledby={{@aria-labelledby}}
+        class='cds--header__menu'
+      >
+        {{yield UIShellHeaderMenuItem}}
+      </ul>
+    </li>
+  </template>
+}
diff --git a/carbon-components-ember/src/components/ui-shell/-header/-panel.gts b/carbon-components-ember/src/components/ui-shell/-header/-panel.gts
new file mode 100644
index 000000000..69385f0f7
--- /dev/null
+++ b/carbon-components-ember/src/components/ui-shell/-header/-panel.gts
@@ -0,0 +1,32 @@
+import Component from '@glimmer/component';
+import { on } from '@ember/modifier';
+
+export interface UIShellHeaderPanelSignature {
+  Element: HTMLDivElement;
+  Args: {
+    expanded?: boolean;
+    onToggle?: (value: boolean) => void;
+  };
+  Blocks: {
+    default: [];
+  };
+}
+
+export default class UIShellHeaderPanel extends Component<UIShellHeaderPanelSignature> {
+  handleKeydown = (event: KeyboardEvent) => {
+    if (event.key === 'Escape') {
+      this.args.onToggle?.(false);
+    }
+  };
+
+  <template>
+    <div
+      class='cds--header-panel
+        {{if @expanded "cds--header-panel--expanded"}}'
+      {{on 'keydown' this.handleKeydown}}
+      ...attributes
+    >
+      {{yield}}
+    </div>
+  </template>
+}
diff --git a/carbon-components-ember/src/components/ui-shell/-header/-side-nav-items.gts b/carbon-components-ember/src/components/ui-shell/-header/-side-nav-items.gts
new file mode 100644
index 000000000..d24664173
--- /dev/null
+++ b/carbon-components-ember/src/components/ui-shell/-header/-side-nav-items.gts
@@ -0,0 +1,23 @@
+import Component from '@glimmer/component';
+
+export interface UIShellHeaderSideNavItemsSignature {
+  Element: HTMLUListElement;
+  Args: {
+    hasDivider?: boolean;
+  };
+  Blocks: {
+    default: [];
+  };
+}
+
+export default class UIShellHeaderSideNavItems extends Component<UIShellHeaderSideNavItemsSignature> {
+  <template>
+    <ul
+      class='cds--side-nav__header-navigation
+        {{if @hasDivider "cds--side-nav__header-divider"}}'
+      ...attributes
+    >
+      {{yield}}
+    </ul>
+  </template>
+}
diff --git a/carbon-components-ember/src/components/ui-shell/-nav.gts b/carbon-components-ember/src/components/ui-shell/-nav.gts
index c7193bf78..f48b4bd40 100644
--- a/carbon-components-ember/src/components/ui-shell/-nav.gts
+++ b/carbon-components-ember/src/components/ui-shell/-nav.gts
@@ -1,10 +1,11 @@
 import Component from '@glimmer/component';
 import UIShellNavItem from '../../components/ui-shell/-nav/-item.gts';
+import UIShellHeaderMenu from '../../components/ui-shell/-header/-menu.gts';
 
 export interface Signature {
   Element: null;
   Blocks: {
-    default: [typeof UIShellNavItem];
+    default: [typeof UIShellNavItem, typeof UIShellHeaderMenu];
   };
 }
 
@@ -12,7 +13,7 @@ export default class InnerClass extends Component<Signature> {
   <template>
     <nav aria-label='IBM [Platform]' class='cds--header__nav'>
       <ul class='cds--header__menu-bar'>
-        {{yield UIShellNavItem}}
+        {{yield UIShellNavItem UIShellHeaderMenu}}
       </ul>
     </nav>
   </template>
diff --git a/carbon-components-ember/src/components/ui-shell/-sidenav.gts b/carbon-components-ember/src/components/ui-shell/-sidenav.gts
index 7b6ced226..714572ab0 100644
--- a/carbon-components-ember/src/components/ui-shell/-sidenav.gts
+++ b/carbon-components-ember/src/components/ui-shell/-sidenav.gts
@@ -4,6 +4,10 @@ import Component from '@glimmer/component';
 import NavMenuComponent, { type SubMenu } from './-sidenav/-menu.gts';
 import Divider from './-sidenav/-divider.gts';
 import Footer from './-sidenav/-footer.gts';
+import SideNavHeader from './-sidenav/-header.gts';
+import SideNavDetails from './-sidenav/-details.gts';
+import SideNavIcon from './-sidenav/-icon.gts';
+import HeaderSideNavItems from './-header/-side-nav-items.gts';
 import { fn } from '@ember/helper';
 import { stylesheet } from 'astroturf';
 import type Icon from '../icon';
@@ -22,7 +26,14 @@ export interface UIShellNavSignature {
     transitionTo: (menu: MenuItem | SubMenu) => void;
   };
   Blocks: {
-    default: [typeof NavMenuComponent, typeof Divider];
+    default: [
+      typeof NavMenuComponent,
+      typeof Divider,
+      typeof SideNavHeader,
+      typeof SideNavDetails,
+      typeof SideNavIcon,
+      typeof HeaderSideNavItems,
+    ];
     content: [];
     footer: [typeof Footer];
   };
@@ -51,7 +62,7 @@ export default class UIShellNav extends Component<UIShellNavSignature> {
     >
       <ul class='cds--side-nav__items'>
         {{#unless @menuItems}}
-          {{yield Menu Divider}}
+          {{yield Menu Divider SideNavHeader SideNavDetails SideNavIcon HeaderSideNavItems}}
         {{/unless}}
         {{#each @menuItems as |menu|}}
           <Menu
diff --git a/carbon-components-ember/src/components/ui-shell/-sidenav/-details.gts b/carbon-components-ember/src/components/ui-shell/-sidenav/-details.gts
new file mode 100644
index 000000000..b44a7eaa8
--- /dev/null
+++ b/carbon-components-ember/src/components/ui-shell/-sidenav/-details.gts
@@ -0,0 +1,22 @@
+import Component from '@glimmer/component';
+
+export interface UIShellSideNavDetailsSignature {
+  Element: HTMLDivElement;
+  Args: {
+    title: string;
+  };
+  Blocks: {
+    default: [];
+  };
+}
+
+export default class UIShellSideNavDetails extends Component<UIShellSideNavDetailsSignature> {
+  <template>
+    <div class='cds--side-nav__details' ...attributes>
+      <h2 class='cds--side-nav__title' title={{@title}}>
+        {{@title}}
+      </h2>
+      {{yield}}
+    </div>
+  </template>
+}
diff --git a/carbon-components-ember/src/components/ui-shell/-sidenav/-header.gts b/carbon-components-ember/src/components/ui-shell/-sidenav/-header.gts
new file mode 100644
index 000000000..465bc5924
--- /dev/null
+++ b/carbon-components-ember/src/components/ui-shell/-sidenav/-header.gts
@@ -0,0 +1,24 @@
+import Component from '@glimmer/component';
+import UIShellSideNavIcon from './-icon.gts';
+import type Icon from '../../icon.gts';
+
+export interface UIShellSideNavHeaderSignature {
+  Element: HTMLElement;
+  Args: {
+    icon: typeof Icon;
+  };
+  Blocks: {
+    default: [];
+  };
+}
+
+export default class UIShellSideNavHeader extends Component<UIShellSideNavHeaderSignature> {
+  <template>
+    <header class='cds--side-nav__header' ...attributes>
+      <UIShellSideNavIcon>
+        <this.args.icon />
+      </UIShellSideNavIcon>
+      {{yield}}
+    </header>
+  </template>
+}
diff --git a/carbon-components-ember/src/components/ui-shell/-sidenav/-icon.gts b/carbon-components-ember/src/components/ui-shell/-sidenav/-icon.gts
new file mode 100644
index 000000000..4d8117097
--- /dev/null
+++ b/carbon-components-ember/src/components/ui-shell/-sidenav/-icon.gts
@@ -0,0 +1,22 @@
+import Component from '@glimmer/component';
+
+export interface UIShellSideNavIconSignature {
+  Element: HTMLDivElement;
+  Args: {
+    small?: boolean;
+  };
+  Blocks: {
+    default: [];
+  };
+}
+
+export default class UIShellSideNavIcon extends Component<UIShellSideNavIconSignature> {
+  <template>
+    <div
+      class='cds--side-nav__icon {{if @small "cds--side-nav__icon--small"}}'
+      ...attributes
+    >
+      {{yield}}
+    </div>
+  </template>
+}
diff --git a/carbon-components-ember/src/components/ui-shell/-switcher.gts b/carbon-components-ember/src/components/ui-shell/-switcher.gts
new file mode 100644
index 000000000..722952629
--- /dev/null
+++ b/carbon-components-ember/src/components/ui-shell/-switcher.gts
@@ -0,0 +1,27 @@
+import Component from '@glimmer/component';
+import UIShellSwitcherItem from './-switcher/-item.gts';
+import UIShellSwitcherDivider from './-switcher/-divider.gts';
+
+export interface UIShellSwitcherSignature {
+  Element: HTMLUListElement;
+  Args: {
+    'aria-label'?: string;
+    'aria-labelledby'?: string;
+  };
+  Blocks: {
+    default: [typeof UIShellSwitcherItem, typeof UIShellSwitcherDivider];
+  };
+}
+
+export default class UIShellSwitcher extends Component<UIShellSwitcherSignature> {
+  <template>
+    <ul
+      class='cds--switcher'
+      aria-label={{@aria-label}}
+      aria-labelledby={{@aria-labelledby}}
+      ...attributes
+    >
+      {{yield UIShellSwitcherItem UIShellSwitcherDivider}}
+    </ul>
+  </template>
+}
diff --git a/carbon-components-ember/src/components/ui-shell/-switcher/-divider.gts b/carbon-components-ember/src/components/ui-shell/-switcher/-divider.gts
new file mode 100644
index 000000000..6bda17870
--- /dev/null
+++ b/carbon-components-ember/src/components/ui-shell/-switcher/-divider.gts
@@ -0,0 +1,13 @@
+import Component from '@glimmer/component';
+
+export interface UIShellSwitcherDividerSignature {
+  Element: HTMLLIElement;
+}
+
+export default class UIShellSwitcherDivider extends Component<UIShellSwitcherDividerSignature> {
+  <template>
+    <li ...attributes>
+      <hr class='cds--switcher__item--divider' />
+    </li>
+  </template>
+}
diff --git a/carbon-components-ember/src/components/ui-shell/-switcher/-item.gts b/carbon-components-ember/src/components/ui-shell/-switcher/-item.gts
new file mode 100644
index 000000000..b02e3c033
--- /dev/null
+++ b/carbon-components-ember/src/components/ui-shell/-switcher/-item.gts
@@ -0,0 +1,29 @@
+import Component from '@glimmer/component';
+
+export interface UIShellSwitcherItemSignature {
+  Element: HTMLAnchorElement;
+  Args: {
+    'aria-label'?: string;
+    isSelected?: boolean;
+    href?: string;
+  };
+  Blocks: {
+    default: [];
+  };
+}
+
+export default class UIShellSwitcherItem extends Component<UIShellSwitcherItemSignature> {
+  <template>
+    <li class='cds--switcher__item'>
+      <a
+        class='cds--switcher__item-link
+          {{if @isSelected "cds--switcher__item-link--selected"}}'
+        href={{if @href @href '#'}}
+        aria-label={{@aria-label}}
+        ...attributes
+      >
+        {{yield}}
+      </a>
+    </li>
+  </template>
+}
diff --git a/docs-app/app/templates/2-components/ui-shell.md b/docs-app/app/templates/2-components/ui-shell.md
index 8d101a9b9..587489785 100644
--- a/docs-app/app/templates/2-components/ui-shell.md
+++ b/docs-app/app/templates/2-components/ui-shell.md
@@ -80,6 +80,163 @@ navigation items, and a `footer` named block that yields a `Footer` toggle
 control for expanding/collapsing the rail — wire both to the same
 `@open`/`@onToggle` state used by the `Header`'s menu button.
 
+## Header dropdown menus
+
+The `Nav` block yields a second component, `Menu` (`HeaderMenu`), for
+top-level items that expand to show a list of `HeaderMenuItem`s.
+
+```gjs live preview
+import { UIShell } from 'carbon-components-ember/components';
+import { ThemeSupport } from 'docs-support';
+
+<template>
+  <ThemeSupport />
+  <div
+    style='position: relative; height: 14rem; overflow: hidden; transform: translate(0); border: 1px solid var(--cds-border-subtle-01, #e0e0e0);'
+  >
+    <UIShell>
+      <:shell as |s|>
+        <s.Header @title='IBM' @subtitle='Platform'>
+          <:header>
+            <s.Nav as |Item Menu|>
+              <Item>Link 1</Item>
+              <Menu @menuLinkName='Link 2' as |MenuItem|>
+                <MenuItem @isActive={{true}}>Sub-link 1</MenuItem>
+                <MenuItem>Sub-link 2</MenuItem>
+              </Menu>
+            </s.Nav>
+          </:header>
+        </s.Header>
+      </:shell>
+      <:content></:content>
+    </UIShell>
+  </div>
+</template>
+```
+
+## Header panel and switcher
+
+`Header` yields a `HeaderPanel` component into the `headerPanel` named
+block for building panels such as an application switcher — toggle its
+`@expanded` argument from a `GlobalAction`'s `onClick`. The top-level
+`UIShell` yields a `Switcher` component (with `Item` and `Divider`) for
+rendering the switcher's contents.
+
+```gjs live preview
+import { UIShell } from 'carbon-components-ember/components';
+import { UserAvatar } from 'carbon-components-ember/icons';
+import { ThemeSupport } from 'docs-support';
+import { cell } from 'ember-resources';
+
+const switcherOpen = cell(false);
+const toggleSwitcher = () => (switcherOpen.current = !switcherOpen.current);
+
+<template>
+  <ThemeSupport />
+  <div
+    style='position: relative; height: 14rem; overflow: hidden; transform: translate(0); border: 1px solid var(--cds-border-subtle-01, #e0e0e0);'
+  >
+    <UIShell>
+      <:shell as |s|>
+        <s.Header @title='IBM' @subtitle='Platform'>
+          <:headerGlobal as |GlobalAction|>
+            <GlobalAction
+              @aria-label='App switcher'
+              @icon={{UserAvatar}}
+              @onClick={{toggleSwitcher}}
+            />
+          </:headerGlobal>
+          <:headerPanel as |HeaderPanel|>
+            <HeaderPanel @expanded={{switcherOpen.current}} @onToggle={{toggleSwitcher}}>
+              <s.Switcher @aria-label='App switcher' as |Item Divider|>
+                <Item @isSelected={{true}}>App 1</Item>
+                <Item>App 2</Item>
+                <Divider />
+                <Item>App 3</Item>
+              </s.Switcher>
+            </HeaderPanel>
+          </:headerPanel>
+        </s.Header>
+      </:shell>
+      <:content></:content>
+    </UIShell>
+  </div>
+</template>
+```
+
+## Side navigation header, details, and mirrored header items
+
+The `Sidenav` block also yields `SideNavHeader` (an icon + heading for the
+rail), `SideNavDetails` (a titled block, useful for account info), and
+`HeaderSideNavItems` (mirrors top `Header` nav items into the rail for
+smaller viewports).
+
+```gjs live preview
+import { UIShell } from 'carbon-components-ember/components';
+import { UserAvatar } from 'carbon-components-ember/icons';
+import { ThemeSupport } from 'docs-support';
+
+<template>
+  <ThemeSupport />
+  <div
+    style='position: relative; height: 20rem; overflow: hidden; transform: translate(0); border: 1px solid var(--cds-border-subtle-01, #e0e0e0);'
+  >
+    <UIShell>
+      <:shell as |s|>
+        <s.Sidenav @open={{true}}>
+          <:default as |_Menu _Divider SideNavHeader SideNavDetails _SideNavIcon HeaderSideNavItems|>
+            <SideNavHeader @icon={{UserAvatar}}>IBM</SideNavHeader>
+            <SideNavDetails @title='Account'>
+              <p>jane.doe@example.com</p>
+            </SideNavDetails>
+            <HeaderSideNavItems @hasDivider={{true}}>
+              <li>Mirrored link 1</li>
+              <li>Mirrored link 2</li>
+            </HeaderSideNavItems>
+          </:default>
+        </s.Sidenav>
+      </:shell>
+      <:content></:content>
+    </UIShell>
+  </div>
+</template>
+```
+
+## HeaderContainer
+
+`HeaderContainer` (yielded from the top-level `shell` block) manages the
+`isSideNavExpanded` state for you and collapses it when the user presses
+<kbd>Escape</kbd>, so you don't have to keep your own `@open`/`@onToggle`
+cell. It yields `isSideNavExpanded` and `onClickSideNavExpand` for wiring up
+the `Header`'s menu toggle and the `Sidenav`'s `@open` argument.
+
+```gjs live preview
+import { UIShell } from 'carbon-components-ember/components';
+import { ThemeSupport } from 'docs-support';
+
+<template>
+  <ThemeSupport />
+  <div
+    style='position: relative; height: 14rem; overflow: hidden; transform: translate(0); border: 1px solid var(--cds-border-subtle-01, #e0e0e0);'
+  >
+    <UIShell>
+      <:shell as |s|>
+        <s.HeaderContainer as |c|>
+          <s.Header
+            @title='IBM'
+            @subtitle='Platform'
+            @open={{c.isSideNavExpanded}}
+            @onToggle={{c.onClickSideNavExpand}}
+          />
+          <s.Sidenav @open={{c.isSideNavExpanded}} />
+        </s.HeaderContainer>
+      </:shell>
+      <:content></:content>
+    </UIShell>
+  </div>
+</template>
+```
+
 ## API Reference
 
 <details>
diff --git a/test-app/tests/components/ui-shell-test.gts b/test-app/tests/components/ui-shell-test.gts
index 1d17f1089..9c09f730d 100644
--- a/test-app/tests/components/ui-shell-test.gts
+++ b/test-app/tests/components/ui-shell-test.gts
@@ -1,6 +1,7 @@
 import { module, test } from 'qunit';
 import { setupRenderingTest } from 'ember-qunit';
 import { render, click } from '@ember/test-helpers';
+import { on } from '@ember/modifier';
 import UIShell from 'carbon-components-ember/components/ui-shell';
 import { Notification } from 'carbon-components-ember/icons';
 import { cell } from 'ember-resources';
@@ -140,6 +141,134 @@ module('Integration | Component | UIShell', (hooks) => {
     assert.dom('.cds--side-nav__menu').doesNotExist();
   });
 
+  test('nav renders a HeaderMenu that expands to show HeaderMenuItems', async function (assert) {
+    await render(
+      <template>
+        <UIShell>
+          <:shell as |s|>
+            <s.Header @title='IBM' @subtitle='Platform'>
+              <:header>
+                <s.Nav as |Item Menu|>
+                  <Item>Link 1</Item>
+                  <Menu @menuLinkName='Link 2' as |MenuItem|>
+                    <MenuItem>Sub-link 1</MenuItem>
+                    <MenuItem @isActive={{true}}>Sub-link 2</MenuItem>
+                  </Menu>
+                </s.Nav>
+              </:header>
+            </s.Header>
+          </:shell>
+          <:content></:content>
+        </UIShell>
+      </template>,
+    );
+
+    assert.dom('.cds--header__submenu').exists();
+    assert.dom('.cds--header__menu-title').hasAria('expanded', 'false');
+    assert.dom('.cds--header__menu .cds--header__menu-item').exists({ count: 2 });
+    assert
+      .dom('.cds--header__menu .cds--header__menu-item--current')
+      .exists({ count: 1 });
+
+    await click('.cds--header__menu-title');
+    assert.dom('.cds--header__menu-title').hasAria('expanded', 'true');
+  });
+
+  test('header panel renders content and toggles the expanded class', async function (assert) {
+    await render(
+      <template>
+        <UIShell>
+          <:shell as |s|>
+            <s.Header @title='IBM' @subtitle='Platform'>
+              <:headerPanel as |Panel|>
+                <Panel @expanded={{true}}>Panel content</Panel>
+              </:headerPanel>
+            </s.Header>
+          </:shell>
+          <:content></:content>
+        </UIShell>
+      </template>,
+    );
+
+    assert.dom('.cds--header-panel').hasClass('cds--header-panel--expanded');
+    assert.dom('.cds--header-panel').hasText('Panel content');
+  });
+
+  test('switcher renders items and a divider', async function (assert) {
+    await render(
+      <template>
+        <UIShell>
+          <:shell as |s|>
+            <s.Switcher @aria-label='App switcher' as |Item Divider|>
+              <Item @isSelected={{true}}>App 1</Item>
+              <Divider />
+              <Item>App 2</Item>
+            </s.Switcher>
+          </:shell>
+          <:content></:content>
+        </UIShell>
+      </template>,
+    );
+
+    assert.dom('.cds--switcher').exists();
+    assert.dom('.cds--switcher__item').exists({ count: 2 });
+    assert
+      .dom('.cds--switcher__item-link--selected')
+      .hasText('App 1');
+    assert.dom('.cds--switcher__item--divider').exists();
+  });
+
+  test('sidenav renders SideNavHeader, SideNavDetails and HeaderSideNavItems', async function (assert) {
+    await render(
+      <template>
+        <UIShell>
+          <:shell as |s|>
+            <s.Sidenav @open={{true}}>
+              <:default as |_Menu _Divider SideNavHeader SideNavDetails _SideNavIcon HeaderSideNavItems|>
+                <SideNavHeader @icon={{Notification}}>IBM</SideNavHeader>
+                <SideNavDetails @title='Account'>
+                  <p>Account details</p>
+                </SideNavDetails>
+                <HeaderSideNavItems @hasDivider={{true}}>
+                  <li>Mirrored link</li>
+                </HeaderSideNavItems>
+              </:default>
+            </s.Sidenav>
+          </:shell>
+          <:content></:content>
+        </UIShell>
+      </template>,
+    );
+
+    assert.dom('.cds--side-nav__header').exists();
+    assert.dom('.cds--side-nav__header .cds--side-nav__icon').exists();
+    assert.dom('.cds--side-nav__details .cds--side-nav__title').hasText('Account');
+    assert
+      .dom('.cds--side-nav__header-navigation.cds--side-nav__header-divider')
+      .exists();
+  });
+
+  test('HeaderContainer yields expansion state and a toggle action', async function (assert) {
+    await render(
+      <template>
+        <UIShell>
+          <:shell as |s|>
+            <s.HeaderContainer as |c|>
+              <button type='button' {{on 'click' c.onClickSideNavExpand}}>
+                {{if c.isSideNavExpanded 'expanded' 'collapsed'}}
+              </button>
+            </s.HeaderContainer>
+          </:shell>
+          <:content></:content>
+        </UIShell>
+      </template>,
+    );
+
+    assert.dom('button').hasText('collapsed');
+    await click('button');
+    assert.dom('button').hasText('expanded');
+  });
+
   test('sidenav footer toggles open state', async function (assert) {
     const open = cell(false);
     const onToggle = (value: boolean) => (open.current = value);

From c2bd259e32e4ec8461daef6eb4d6905077febd7a Mon Sep 17 00:00:00 2001
From: Patrick Pircher <patrick.pircher@ibm.com>
Date: Sat, 1 Aug 2026 14:43:38 +0200
Subject: [PATCH 2/5] fix(ui-shell): resolve template-lint errors in header
 menu and panel

The header submenu trigger anchor uses aria-haspopup/aria-expanded,
which template-lint flags because <a href="#"> resolves to an
implicit generic role rather than link (matches existing precedent in
select.gts). The header panel's keydown listener sits on a
non-interactive div, matching the same disable used in toggletip,
tooltip, and tree-view for Escape-key handling.

Signed-off-by: Patrick Pircher <patrick.pircher@ibm.com>
---
 .../src/components/ui-shell/-header/-menu.gts                    | 1 +
 .../src/components/ui-shell/-header/-panel.gts                   | 1 +
 2 files changed, 2 insertions(+)

diff --git a/carbon-components-ember/src/components/ui-shell/-header/-menu.gts b/carbon-components-ember/src/components/ui-shell/-header/-menu.gts
index d6193cc0b..f11a3fc2c 100644
--- a/carbon-components-ember/src/components/ui-shell/-header/-menu.gts
+++ b/carbon-components-ember/src/components/ui-shell/-header/-menu.gts
@@ -30,6 +30,7 @@ export default class UIShellHeaderMenu extends Component<UIShellHeaderMenuSignat
         {{if @isActive "cds--header__menu-item--current"}}'
       ...attributes
     >
+      {{! template-lint-disable no-unsupported-role-attributes }}
       <a
         aria-haspopup='menu'
         aria-expanded='{{if this.expanded "true" "false"}}'
diff --git a/carbon-components-ember/src/components/ui-shell/-header/-panel.gts b/carbon-components-ember/src/components/ui-shell/-header/-panel.gts
index 69385f0f7..f5eb90caa 100644
--- a/carbon-components-ember/src/components/ui-shell/-header/-panel.gts
+++ b/carbon-components-ember/src/components/ui-shell/-header/-panel.gts
@@ -20,6 +20,7 @@ export default class UIShellHeaderPanel extends Component<UIShellHeaderPanelSign
   };
 
   <template>
+    {{! template-lint-disable no-invalid-interactive }}
     <div
       class='cds--header-panel
         {{if @expanded "cds--header-panel--expanded"}}'

From 587eeeb5fa0d736dd1d35311a8f48daa71f82aa7 Mon Sep 17 00:00:00 2001
From: Patrick Pircher <patrick.pircher@ibm.com>
Date: Mon, 3 Aug 2026 14:10:27 +0200
Subject: [PATCH 3/5] fix(ui-shell): render menu toggle icon and center header
 action icons
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The header menu toggle used <Icon @icon='menu'/>, a string-keyed lookup
into IconMap via registerIcon(), but nothing in the codebase ever calls
registerIcon() since the per-icon-component refactor — so the toggle
button rendered no icon at all. Use the real Menu/Close icon components
instead, matching how every other icon in ui-shell is rendered.

HeaderGlobalAction's button was also missing the cds--btn--icon-only
class that Carbon's CSS requires to center an icon-only button
(.cds--header__action alone is only display:inline-flex, with no
align-items/justify-content), so global action icons rendered flush to
the left instead of centered.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Signed-off-by: Patrick Pircher <patrick.pircher@ibm.com>
---
 .../src/components/ui-shell/-header.gts                   | 8 ++++++--
 .../src/components/ui-shell/-header/-global-action.gts    | 2 +-
 2 files changed, 7 insertions(+), 3 deletions(-)

diff --git a/carbon-components-ember/src/components/ui-shell/-header.gts b/carbon-components-ember/src/components/ui-shell/-header.gts
index ce4edf770..e241ab1b7 100644
--- a/carbon-components-ember/src/components/ui-shell/-header.gts
+++ b/carbon-components-ember/src/components/ui-shell/-header.gts
@@ -1,4 +1,4 @@
-import { default as Icon } from '../../components/icon.gts';
+import { Close, Menu } from '../../icons.ts';
 import { default as not } from 'ember-truth-helpers/helpers/not';
 import { on } from '@ember/modifier';
 import { fn } from '@ember/helper';
@@ -35,7 +35,11 @@ export default class UIShellHeader extends Component<UIShellHeaderSignature> {
           type='button'
           {{on 'click' (fn @onToggle (not @open))}}
         >
-          <Icon @icon={{if @open 'close' 'menu'}} />
+          {{#if @open}}
+            <Close @size={{20}} />
+          {{else}}
+            <Menu @size={{20}} />
+          {{/if}}
         </button>
       {{/if}}
       <a class='cds--header__name' href='#'>
diff --git a/carbon-components-ember/src/components/ui-shell/-header/-global-action.gts b/carbon-components-ember/src/components/ui-shell/-header/-global-action.gts
index 6207d85f4..4909bd586 100644
--- a/carbon-components-ember/src/components/ui-shell/-header/-global-action.gts
+++ b/carbon-components-ember/src/components/ui-shell/-header/-global-action.gts
@@ -16,7 +16,7 @@ export default class UIShellHeaderGlobalAction extends Component<UIShellHeaderGl
     <button
       aria-label={{@aria-label}}
       title={{@aria-label}}
-      class='cds--header__action'
+      class='cds--header__action cds--btn--icon-only'
       type='button'
       {{on 'click' @onClick}}
       ...attributes

From 58c683154e48404124d736680cc8dc412fad2bf5 Mon Sep 17 00:00:00 2001
From: Patrick Pircher <patrick.pircher@ibm.com>
Date: Mon, 3 Aug 2026 14:24:01 +0200
Subject: [PATCH 4/5] test(ui-shell): cover menu-toggle icon render and global
 action centering

Add assertions for the two symptoms fixed in 587eeeb5 so a regression
fails a test instead of only being caught visually: the menu toggle
renders an svg that swaps between Menu/Close based on @open, and
HeaderGlobalAction's button carries cds--btn--icon-only and renders
its icon.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Signed-off-by: Patrick Pircher <patrick.pircher@ibm.com>
---
 test-app/tests/components/ui-shell-test.gts | 18 +++++++++++++++++-
 1 file changed, 17 insertions(+), 1 deletion(-)

diff --git a/test-app/tests/components/ui-shell-test.gts b/test-app/tests/components/ui-shell-test.gts
index 9c09f730d..ab1a0497f 100644
--- a/test-app/tests/components/ui-shell-test.gts
+++ b/test-app/tests/components/ui-shell-test.gts
@@ -1,6 +1,6 @@
 import { module, test } from 'qunit';
 import { setupRenderingTest } from 'ember-qunit';
-import { render, click } from '@ember/test-helpers';
+import { render, click, find, waitUntil } from '@ember/test-helpers';
 import { on } from '@ember/modifier';
 import UIShell from 'carbon-components-ember/components/ui-shell';
 import { Notification } from 'carbon-components-ember/icons';
@@ -50,8 +50,19 @@ module('Integration | Component | UIShell', (hooks) => {
     );
 
     assert.dom('.cds--header__menu-toggle').exists();
+    await waitUntil(() => find('.cds--header__menu-toggle svg'));
+    assert.dom('.cds--header__menu-toggle svg').exists();
+    const beforeIcon = find('.cds--header__menu-toggle svg')?.innerHTML;
+
     await click('.cds--header__menu-toggle');
     assert.true(open.current);
+    await waitUntil(() => find('.cds--header__menu-toggle svg'));
+    const afterIcon = find('.cds--header__menu-toggle svg')?.innerHTML;
+    assert.notStrictEqual(
+      beforeIcon,
+      afterIcon,
+      'icon swaps between Menu and Close based on @open',
+    );
   });
 
   test('header global action renders a button and calls onClick', async function (assert) {
@@ -78,6 +89,11 @@ module('Integration | Component | UIShell', (hooks) => {
     );
 
     assert.dom('.cds--header__global .cds--header__action').exists();
+    assert
+      .dom('.cds--header__global .cds--header__action')
+      .hasClass('cds--btn--icon-only');
+    await waitUntil(() => find('.cds--header__global .cds--header__action svg'));
+    assert.dom('.cds--header__global .cds--header__action svg').exists();
     await click('.cds--header__global .cds--header__action');
     assert.true(clicked.current);
   });

From 1e2e34d9593d5c18b26bd8dfeb61467772f11986 Mon Sep 17 00:00:00 2001
From: Patrick Pircher <patrick.pircher@ibm.com>
Date: Mon, 3 Aug 2026 14:37:56 +0200
Subject: [PATCH 5/5] fix(ui-shell): add cds--btn class to header global action
 button

Without cds--btn, Carbon's icon fill-color rule
(.cds--btn.cds--btn--icon-only.cds--header__action svg) never matches,
so the icon never gets the intended icon-secondary/icon-primary color
or hover feedback.

Signed-off-by: Patrick Pircher <patrick.pircher@ibm.com>
---
 .../src/components/ui-shell/-header/-global-action.gts          | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/carbon-components-ember/src/components/ui-shell/-header/-global-action.gts b/carbon-components-ember/src/components/ui-shell/-header/-global-action.gts
index 4909bd586..e1f98a35f 100644
--- a/carbon-components-ember/src/components/ui-shell/-header/-global-action.gts
+++ b/carbon-components-ember/src/components/ui-shell/-header/-global-action.gts
@@ -16,7 +16,7 @@ export default class UIShellHeaderGlobalAction extends Component<UIShellHeaderGl
     <button
       aria-label={{@aria-label}}
       title={{@aria-label}}
-      class='cds--header__action cds--btn--icon-only'
+      class='cds--header__action cds--btn cds--btn--icon-only'
       type='button'
       {{on 'click' @onClick}}
       ...attributes