feat(application-header): show tooltip on icon-only header items

Action and account items now show a tooltip with the title when only the
icon is visible. The tooltip reuses the existing title via SiTooltipService
and adds no extra aria roles.

Author: spike-rabbit

api-goldens/element-ng/application-header/index.api.md

@@ -6,6 +6,7 @@
 
 import { ActivatedRoute } from '@angular/router';
 import * as _angular_core from '@angular/core';
+import { ElementRef } from '@angular/core';
 import { HeaderWithDropdowns } from '@siemens/element-ng/header-dropdown';
 import { Injector } from '@angular/core';
 import { IsActiveMatchOptions } from '@angular/router';
@@ -15,6 +16,7 @@ import { OnDestroy } from '@angular/core';
 import { OnInit } from '@angular/core';
 import * as _siemens_element_ng_application_header from '@siemens/element-ng/application-header';
 import * as _siemens_element_translate_ng_translate from '@siemens/element-translate-ng/translate';
+import { Signal } from '@angular/core';
 import { SiHeaderDropdownTriggerDirective } from '@siemens/element-ng/header-dropdown';
 import { SimpleChanges } from '@angular/core';
 import { Subject } from 'rxjs';

projects/element-ng/application-header/si-application-header.component.spec.ts

@@ -13,7 +13,9 @@ import {
   SiHeaderDropdownTriggerDirective
 } from '@siemens/element-ng/header-dropdown';
 import { runOnPushChangeDetection } from '@siemens/element-ng/test-helpers';
+import { SiTooltipDirective } from '@siemens/element-ng/tooltip';
 import { BehaviorSubject, Observable } from 'rxjs';
+import { page } from 'vitest/browser';
 
 import { SiLaunchpadFactoryComponent } from './launchpad/si-launchpad-factory.component';
 import { SiApplicationHeaderComponent } from './si-application-header.component';
@@ -331,6 +333,98 @@ describe('SiApplicationHeaderComponent', () => {
     });
   });
 
+  describe('with icon-only action items', () => {
+    @Component({
+      imports: [
+        SiApplicationHeaderComponent,
+        SiHeaderActionItemComponent,
+        SiHeaderActionsDirective,
+        SiHeaderCollapsibleActionsComponent
+      ],
+      template: `
+        <si-application-header expandBreakpoint="never">
+          <si-header-actions>
+            <si-header-collapsible-actions>
+              <button type="button" si-header-action-item icon="fake-icon">Action 1</button>
+            </si-header-collapsible-actions>
+          </si-header-actions>
+        </si-application-header>
+      `,
+      changeDetection: ChangeDetectionStrategy.OnPush
+    })
+    class TestHostComponent {}
+
+    let fixture: ComponentFixture<TestHostComponent>;
+    let button: HTMLButtonElement;
+
+    beforeEach(async () => {
+      fixture = TestBed.createComponent(TestHostComponent);
+      loader = TestbedHarnessEnvironment.loader(fixture);
+      headerHarness = await loader.getHarness(SiApplicationHeaderHarness);
+      button = fixture.nativeElement.querySelector('button[si-header-action-item]');
+      vi.spyOn(button, 'matches').mockImplementation(selector => selector === ':focus-visible');
+      fixture.detectChanges();
+    });
+
+    it('should show a tooltip with the title when only the icon is visible', async () => {
+      button.dispatchEvent(new FocusEvent('focus'));
+      await fixture.whenStable();
+      await expect.element(page.getByRole('tooltip', { name: 'Action 1' })).toBeInTheDocument();
+    });
+
+    it('should not show a tooltip when the title is visible', async () => {
+      await headerHarness.openCollapsibleActions();
+      await fixture.whenStable();
+      button.dispatchEvent(new FocusEvent('focus'));
+      await fixture.whenStable();
+      await expect.element(page.getByRole('tooltip')).not.toBeInTheDocument();
+    });
+  });
+
+  describe('with icon-only action item and custom tooltip', () => {
+    @Component({
+      imports: [
+        SiApplicationHeaderComponent,
+        SiHeaderActionItemComponent,
+        SiHeaderActionsDirective,
+        SiHeaderCollapsibleActionsComponent,
+        SiTooltipDirective
+      ],
+      template: `
+        <si-application-header expandBreakpoint="never">
+          <si-header-actions>
+            <si-header-collapsible-actions>
+              <button type="button" si-header-action-item icon="fake-icon" siTooltip="Custom">
+                Action 1
+              </button>
+            </si-header-collapsible-actions>
+          </si-header-actions>
+        </si-application-header>
+      `,
+      changeDetection: ChangeDetectionStrategy.OnPush
+    })
+    class TestHostComponent {}
+
+    let fixture: ComponentFixture<TestHostComponent>;
+    let button: HTMLButtonElement;
+
+    beforeEach(async () => {
+      fixture = TestBed.createComponent(TestHostComponent);
+      loader = TestbedHarnessEnvironment.loader(fixture);
+      headerHarness = await loader.getHarness(SiApplicationHeaderHarness);
+      button = fixture.nativeElement.querySelector('button[si-header-action-item]');
+      vi.spyOn(button, 'matches').mockImplementation(selector => selector === ':focus-visible');
+      fixture.detectChanges();
+    });
+
+    it('should keep the custom tooltip instead of the title', async () => {
+      button.dispatchEvent(new FocusEvent('focus'));
+      await fixture.whenStable();
+      await expect.element(page.getByRole('tooltip', { name: 'Custom' })).toBeInTheDocument();
+      await expect.element(page.getByRole('tooltip', { name: 'Action 1' })).not.toBeInTheDocument();
+    });
+  });
+
   describe('with launchpad', () => {
     @Component({
       imports: [

projects/element-ng/application-header/si-header-account-item.component.html

@@ -5,7 +5,7 @@
   [initials]="initials()"
   [imageUrl]="imageUrl()"
 />
-<div class="item-title" aria-hidden="true" [class.d-none]="visuallyHideTitle">
+<div class="item-title" aria-hidden="true" [class.d-none]="visuallyHideTitle()">
   {{ name() }}
 </div>
 @if (badgeValue()) {

projects/element-ng/application-header/si-header-account-item.component.ts

@@ -5,6 +5,7 @@
 import { ChangeDetectionStrategy, Component, input } from '@angular/core';
 import { SiAvatarComponent } from '@siemens/element-ng/avatar';
 import { SiIconComponent } from '@siemens/element-ng/icon';
+import { SiTooltipService } from '@siemens/element-ng/tooltip';
 
 import { SiHeaderActionIconItemBase } from './si-header-action-item-icon-base.directive';
 
@@ -15,6 +16,7 @@ import { SiHeaderActionIconItemBase } from './si-header-action-item-icon-base.di
   imports: [SiAvatarComponent, SiIconComponent],
   templateUrl: './si-header-account-item.component.html',
   styleUrl: './si-header-account-item.component.scss',
+  providers: [SiTooltipService],
   changeDetection: ChangeDetectionStrategy.OnPush,
   host: {
     class: 'header-item focus-inside px-4 py-0',
@@ -28,4 +30,6 @@ export class SiHeaderAccountItemComponent extends SiHeaderActionIconItemBase {
   readonly initials = input<string>();
   /** URL to an image which should be shown instead of the initials. */
   readonly imageUrl = input<string>();
+
+  protected readonly itemTitle = this.name;
 }

projects/element-ng/application-header/si-header-action-item-icon-base.directive.ts

@@ -2,7 +2,20 @@
  * Copyright (c) Siemens 2016 - 2026
  * SPDX-License-Identifier: MIT
  */
-import { computed, Directive, input, OnChanges, OnInit, SimpleChanges } from '@angular/core';
+import {
+  computed,
+  Directive,
+  effect,
+  EffectCleanupRegisterFn,
+  ElementRef,
+  inject,
+  input,
+  OnChanges,
+  OnInit,
+  Signal,
+  SimpleChanges
+} from '@angular/core';
+import { SiTooltipDirective, SiTooltipService } from '@siemens/element-ng/tooltip';
 
 import { SiHeaderActionItemBase } from './si-header-action-item.base';
 
@@ -23,6 +36,12 @@ export abstract class SiHeaderActionIconItemBase
    */
   readonly badge = input<number | boolean | undefined | null>();
 
+  protected abstract readonly itemTitle: Signal<string | ElementRef<Element>>;
+
+  private readonly tooltipService = inject(SiTooltipService);
+  private readonly elementRef = inject<ElementRef<HTMLElement>>(ElementRef);
+  private readonly existingTooltip = inject(SiTooltipDirective, { optional: true, host: true });
+
   protected readonly badgeDot = computed(() =>
     typeof this.badge() === 'boolean' ? (this.badge() as boolean) : false
   );
@@ -33,6 +52,27 @@ export abstract class SiHeaderActionIconItemBase
       : undefined;
   });
 
+  constructor() {
+    super();
+    effect(onCleanup => this.setupTooltip(onCleanup));
+  }
+
+  private setupTooltip(onCleanup: EffectCleanupRegisterFn): void {
+    const hasActiveTooltip =
+      !!this.existingTooltip &&
+      !this.existingTooltip.isDisabled() &&
+      !!this.existingTooltip.siTooltip();
+    if (this.visuallyHideTitle() && !hasActiveTooltip) {
+      const tooltipRef = this.tooltipService.createTooltip({
+        element: this.elementRef,
+        placement: 'auto',
+        tooltip: this.itemTitle,
+        tooltipContext: () => undefined
+      });
+      onCleanup(() => tooltipRef.destroy());
+    }
+  }
+
   ngOnChanges(changes: SimpleChanges<this>): void {
     if (changes.badge) {
       if (changes.badge.currentValue && !changes.badge.previousValue) {
@@ -43,7 +83,5 @@ export abstract class SiHeaderActionIconItemBase
     }
   }
 
-  protected get visuallyHideTitle(): boolean {
-    return !this.collapsibleActions?.mobileExpanded();
-  }
+  protected readonly visuallyHideTitle = computed(() => !this.collapsibleActions?.mobileExpanded());
 }

projects/element-ng/application-header/si-header-action-item.component.html

@@ -3,7 +3,7 @@
   <span class="badge-text">{{ badgeValue() }}</span>
 }
 <ng-content select="si-avatar" />
-<div class="item-title" [class.visually-hidden]="visuallyHideTitle">
+<div #itemTitle class="item-title" [class.visually-hidden]="visuallyHideTitle()">
   <ng-content />
 </div>
 @if (dropdownTrigger) {

projects/element-ng/application-header/si-header-action-item.component.ts

@@ -2,8 +2,9 @@
  * Copyright (c) Siemens 2016 - 2026
  * SPDX-License-Identifier: MIT
  */
-import { ChangeDetectionStrategy, Component, input } from '@angular/core';
+import { ChangeDetectionStrategy, Component, ElementRef, input, viewChild } from '@angular/core';
 import { SiIconComponent } from '@siemens/element-ng/icon';
+import { SiTooltipService } from '@siemens/element-ng/tooltip';
 
 import { SiHeaderActionIconItemBase } from './si-header-action-item-icon-base.directive';
 
@@ -13,6 +14,7 @@ import { SiHeaderActionIconItemBase } from './si-header-action-item-icon-base.di
   selector: 'button[si-header-action-item], a[si-header-action-item]',
   imports: [SiIconComponent],
   templateUrl: './si-header-action-item.component.html',
+  providers: [SiTooltipService],
   changeDetection: ChangeDetectionStrategy.OnPush,
   host: {
     class: 'header-item focus-inside',
@@ -22,4 +24,6 @@ import { SiHeaderActionIconItemBase } from './si-header-action-item-icon-base.di
 export class SiHeaderActionItemComponent extends SiHeaderActionIconItemBase {
   /** The icon to be shown. */
   readonly icon = input.required<string>();
+
+  protected readonly itemTitle = viewChild.required<ElementRef<HTMLElement>>('itemTitle');
 }