feat(launchpad): implement spatial arrow navigation

Author: dauriamarco

projects/element-ng/application-header/launchpad/si-launchpad-factory.component.html

@@ -59,6 +59,7 @@
                     [preserveFragment]="app.extras?.preserveFragment"
                     [skipLocationChange]="app.extras?.skipLocationChange"
                     [replaceUrl]="app.extras?.replaceUrl"
+                    (keydown)="handleAppsNavigation($event, $event.currentTarget)"
                     (favoriteChange)="toggleFavorite(app, $event)"
                   >
                     <span app-name>{{ app.name | translate }}</span>
@@ -77,6 +78,7 @@
                     [external]="app.external"
                     [iconUrl]="app.iconUrl"
                     [iconClass]="app.iconClass"
+                    (keydown)="handleAppsNavigation($event, $event.currentTarget)"
                     (favoriteChange)="toggleFavorite(app, $event)"
                   >
                     <span app-name>{{ app.name | translate }}</span>

projects/element-ng/application-header/launchpad/si-launchpad-factory.component.ts

@@ -13,6 +13,7 @@ import {
   output
 } from '@angular/core';
 import { ActivatedRoute, RouterLink, RouterLinkActive } from '@angular/router';
+import { correctKeyRTL } from '@siemens/element-ng/common';
 import { addIcons, elementCancel, elementDown2, SiIconComponent } from '@siemens/element-ng/icon';
 import { SiLinkModule } from '@siemens/element-ng/link';
 import { SiTranslatePipe, t, TranslatableString } from '@siemens/element-translate-ng/translate';
@@ -139,6 +140,10 @@ export class SiLaunchpadFactoryComponent {
   protected readonly activatedRoute = inject(ActivatedRoute, { optional: true });
   private header = inject(SiApplicationHeaderComponent);
 
+  // Navigation constants for keyboard arrow navigation
+  private readonly rowTolerance = 10;
+  private readonly leftTolerance = 20;
+
   protected closeLaunchpad(): void {
     this.header.closeLaunchpad();
   }
@@ -154,4 +159,119 @@ export class SiLaunchpadFactoryComponent {
   protected isCategories(items: App[] | AppCategory[]): items is AppCategory[] {
     return items.some(item => 'apps' in item);
   }
+
+  protected handleAppsNavigation(event: KeyboardEvent, element: EventTarget | null): void {
+    const correctedKey = correctKeyRTL(event.key);
+
+    if (
+      !['ArrowLeft', 'ArrowRight', 'ArrowUp', 'ArrowDown'].includes(correctedKey) ||
+      !element ||
+      !(element instanceof HTMLElement)
+    ) {
+      return;
+    }
+
+    const appContainer = element.closest('.d-flex');
+    if (!appContainer) return;
+
+    const enabledApps = Array.from(
+      appContainer.querySelectorAll(':scope > a[si-launchpad-app]')
+    ) as HTMLElement[];
+
+    const currentIndex = enabledApps.indexOf(element);
+    if (currentIndex === -1) return;
+
+    let targetIndex: number;
+
+    if (correctedKey === 'ArrowLeft' || correctedKey === 'ArrowRight') {
+      // Horizontal navigation within the same row
+      const direction = correctedKey === 'ArrowLeft' ? -1 : 1;
+      targetIndex = (currentIndex + direction + enabledApps.length) % enabledApps.length;
+    } else {
+      // Vertical navigation between rows
+      targetIndex = this.getVerticalTargetIndex(
+        enabledApps,
+        currentIndex,
+        correctedKey === 'ArrowUp'
+      );
+    }
+
+    enabledApps[targetIndex]?.focus();
+    event.preventDefault();
+  }
+
+  private getVerticalTargetIndex(apps: HTMLElement[], currentIndex: number, isUp: boolean): number {
+    // Cache all bounding rects to avoid multiple expensive DOM calls
+    const appRects = apps.map(app => ({
+      element: app,
+      rect: app.getBoundingClientRect()
+    }));
+
+    const currentRect = appRects[currentIndex].rect;
+
+    // Check if layout is single column (mobile/narrow screen)
+    const alignedApps = appRects.filter(
+      ({ rect }) => Math.abs(rect.left - currentRect.left) <= this.leftTolerance
+    );
+
+    // Single column: use sequential navigation
+    if (alignedApps.length >= apps.length) {
+      const direction = isUp ? -1 : 1;
+      const targetIndex = currentIndex + direction;
+
+      return targetIndex < 0 ? apps.length - 1 : targetIndex >= apps.length ? 0 : targetIndex;
+    }
+
+    // Grid layout: use spatial navigation
+    const currentRowKey = Math.round(currentRect.top / this.rowTolerance) * this.rowTolerance;
+
+    // Group apps by rows (excluding current app for target selection)
+    const rowGroups = new Map<number, typeof appRects>();
+    let hasMultipleRows = false;
+
+    appRects.forEach((appRect, index) => {
+      const rowKey = Math.round(appRect.rect.top / this.rowTolerance) * this.rowTolerance;
+
+      if (rowKey !== currentRowKey) {
+        hasMultipleRows = true;
+      }
+
+      if (index !== currentIndex) {
+        if (!rowGroups.has(rowKey)) {
+          rowGroups.set(rowKey, []);
+        }
+        rowGroups.get(rowKey)!.push(appRect);
+      }
+    });
+
+    // Single row: no vertical movement
+    if (!hasMultipleRows) {
+      return currentIndex;
+    }
+
+    // Find target row and closest app
+    const sortedRowKeys = Array.from(rowGroups.keys()).sort((a, b) => a - b);
+    const currentRowIndex = sortedRowKeys.indexOf(currentRowKey);
+
+    const targetRowKey = isUp
+      ? currentRowIndex > 0
+        ? sortedRowKeys[currentRowIndex - 1]
+        : sortedRowKeys[sortedRowKeys.length - 1]
+      : currentRowIndex < sortedRowKeys.length - 1
+        ? sortedRowKeys[currentRowIndex + 1]
+        : sortedRowKeys[0];
+
+    const targetRowApps = rowGroups.get(targetRowKey) ?? [];
+
+    if (targetRowApps.length === 0) return currentIndex;
+
+    // Find closest app horizontally in target row
+    const closestApp = targetRowApps.reduce((closest, app) =>
+      Math.abs(app.rect.left - currentRect.left) < Math.abs(closest.rect.left - currentRect.left)
+        ? app
+        : closest
+    );
+
+    return apps.indexOf(closestApp.element);
+  }
 }

projects/element-ng/application-header/launchpad/si-launchpad-navigation.spec.ts

@@ -0,0 +1,135 @@
+/**
+ * Copyright (c) Siemens 2016 - 2025
+ * SPDX-License-Identifier: MIT
+ */
+import { Component, provideZonelessChangeDetection } from '@angular/core';
+import { ComponentFixture, TestBed } from '@angular/core/testing';
+
+import { SiApplicationHeaderComponent } from '../si-application-header.component';
+import { SiLaunchpadFactoryComponent } from './si-launchpad-factory.component';
+
+describe('SiLaunchpadFactory - Keyboard Navigation', () => {
+  @Component({
+    imports: [SiLaunchpadFactoryComponent],
+    template: `<si-launchpad-factory [apps]="[]" />`
+  })
+  class TestHostComponent {}
+
+  let fixture: ComponentFixture<TestHostComponent>;
+  let component: SiLaunchpadFactoryComponent;
+
+  beforeEach(() => {
+    TestBed.configureTestingModule({
+      imports: [TestHostComponent],
+      providers: [
+        { provide: SiApplicationHeaderComponent, useValue: {} },
+        provideZonelessChangeDetection()
+      ]
+    });
+
+    fixture = TestBed.createComponent(TestHostComponent);
+    component = fixture.debugElement.children[0].componentInstance;
+  });
+
+  const createMockApps = (positions: { top: number; left: number }[]): HTMLElement[] => {
+    return positions.map(({ top, left }) => {
+      const app = document.createElement('a');
+      spyOn(app, 'getBoundingClientRect').and.returnValue({
+        top,
+        left,
+        width: 100,
+        height: 60
+      } as DOMRect);
+      return app;
+    });
+  };
+
+  describe('getVerticalTargetIndex', () => {
+    describe('single column layout', () => {
+      const testCases: [number, boolean, number, string][] = [
+        [2, false, 3, 'down to next'],
+        [2, true, 1, 'up to previous'],
+        [5, false, 0, 'down wrap to first'],
+        [0, true, 5, 'up wrap to last']
+      ];
+
+      testCases.forEach(([from, isUp, expected, description]) => {
+        it(`should navigate from ${from} ${isUp ? 'up' : 'down'} (${description})`, () => {
+          const mockApps = createMockApps([
+            { top: 0, left: 10 },
+            { top: 80, left: 10 },
+            { top: 160, left: 10 },
+            { top: 240, left: 10 },
+            { top: 320, left: 10 },
+            { top: 400, left: 10 }
+          ]);
+
+          const result = (component as any).getVerticalTargetIndex(mockApps, from, isUp);
+          expect(result).toBe(expected);
+        });
+      });
+    });
+
+    describe('grid layout (2x3)', () => {
+      const gridPositions = [
+        { top: 50, left: 10 },
+        { top: 50, left: 130 },
+        { top: 50, left: 250 }, // Row 0
+        { top: 130, left: 10 },
+        { top: 130, left: 130 },
+        { top: 130, left: 250 } // Row 1
+      ];
+
+      const gridTestCases: [number, boolean, number, string][] = [
+        [4, true, 1, 'up from row 1 to row 0'],
+        [1, false, 4, 'down from row 0 to row 1'],
+        [2, false, 5, 'down with exact alignment'],
+        [1, true, 4, 'up wrap to bottom row'],
+        [4, false, 1, 'down wrap to top row']
+      ];
+
+      gridTestCases.forEach(([from, isUp, expected, description]) => {
+        it(`should navigate from ${from} ${isUp ? 'up' : 'down'} (${description})`, () => {
+          const mockApps = createMockApps(gridPositions);
+          const result = (component as any).getVerticalTargetIndex(mockApps, from, isUp);
+          expect(result).toBe(expected);
+        });
+      });
+
+      it('should stay in place for single row', () => {
+        const singleRowApps = createMockApps([
+          { top: 50, left: 10 },
+          { top: 50, left: 130 },
+          { top: 50, left: 250 }
+        ]);
+
+        const result = (component as any).getVerticalTargetIndex(singleRowApps, 1, false);
+        expect(result).toBe(1);
+      });
+    });
+
+    describe('tolerance handling', () => {
+      it('should detect single column within leftTolerance (20px)', () => {
+        const mockApps = createMockApps([
+          { top: 0, left: 10 },
+          { top: 80, left: 25 },
+          { top: 160, left: 15 }
+        ]);
+
+        const result = (component as any).getVerticalTargetIndex(mockApps, 1, false);
+        expect(result).toBe(2); // Sequential navigation
+      });
+
+      it('should detect same row within rowTolerance (10px)', () => {
+        const mockApps = createMockApps([
+          { top: 50, left: 10 },
+          { top: 50, left: 130 },
+          { top: 50, left: 250 }
+        ]);
+
+        const result = (component as any).getVerticalTargetIndex(mockApps, 1, false);
+        expect(result).toBe(1); // No movement
+      });
+    });
+  });
+});