📝 docs(shell): update READMEs for shell and connectivity libraries

- Expand core-connectivity README with usage examples and API docs
- Add TabsCollapsedService documentation to shell-common README
- Update shell-layout README with responsive behavior documentation
- Update library-reference.md with current library descriptions

.gitignore

@@ -80,3 +80,6 @@ CLAUDE.md
 *.pyc
 .vite
 reports/
+
+# Local iPad dev setup (proxy)
+/local-dev/

apps/isa-app/src/page/customer/components/kundenkarte/kundenkarte.component.ts

@@ -9,8 +9,7 @@ import { DecimalPipe } from '@angular/common';
 import { Component, Input, OnInit, inject } from '@angular/core';
 import { IconComponent } from '@shared/components/icon';
 import { BonusCardInfoDTO } from '@generated/swagger/crm-api';
-import { injectTabId } from '@isa/core/tabs';
-import { NavigationStateService } from '@isa/core/navigation';
+import { injectTabId, TabService } from '@isa/core/tabs';
 import { Router } from '@angular/router';
 import { CustomerSearchNavigation } from '@shared/services/navigation';
 
@@ -47,7 +46,7 @@ import { CustomerSearchNavigation } from '@shared/services/navigation';
 export class KundenkarteComponent implements OnInit {
   #tabId = injectTabId();
   #router = inject(Router);
-  #navigationState = inject(NavigationStateService);
+  #tabService = inject(TabService);
   #customerNavigationService = inject(CustomerSearchNavigation);
 
   @Input() cardDetails: BonusCardInfoDTO;
@@ -69,13 +68,12 @@ export class KundenkarteComponent implements OnInit {
       return;
     }
 
-    this.#navigationState.preserveContext(
-      {
+    this.#tabService.patchTabMetadata(tabId, {
+      'select-customer': {
         returnUrl: `/${tabId}/reward`,
         autoTriggerContinueFn: true,
       },
-      'select-customer',
-    );
+    });
 
     await this.#router.navigate(
       this.#customerNavigationService.detailsRoute({

apps/isa-app/src/page/customer/customer-page.component.ts

@@ -1,5 +1,11 @@
-import { Component, ChangeDetectionStrategy } from '@angular/core';
+import {
+  Component,
+  ChangeDetectionStrategy,
+  OnDestroy,
+  inject,
+} from '@angular/core';
 import { ActivatedRoute } from '@angular/router';
+import { TabService } from '@isa/core/tabs';
 import { map } from 'rxjs/operators';
 
 @Component({
@@ -9,8 +15,17 @@ import { map } from 'rxjs/operators';
   changeDetection: ChangeDetectionStrategy.OnPush,
   standalone: false,
 })
-export class CustomerComponent {
+export class CustomerComponent implements OnDestroy {
+  private _tabService = inject(TabService);
   processId$ = this._activatedRoute.data.pipe(map((data) => data.processId));
 
   constructor(private _activatedRoute: ActivatedRoute) {}
+
+  ngOnDestroy() {
+    const tab = this._tabService.activatedTab();
+    // #5512 Always clear preserved select-customer context if navigating out of customer area
+    this._tabService.patchTabMetadata(tab.id, {
+      'select-customer': null,
+    });
+  }
 }

apps/isa-app/src/page/customer/customer-search/details-main-view/details-main-view.component.ts

@@ -49,9 +49,14 @@ import {
   NavigateAfterRewardSelection,
   RewardSelectionPopUpService,
 } from '@isa/checkout/shared/reward-selection-dialog';
-import { NavigationStateService } from '@isa/core/navigation';
+import { TabService } from '@isa/core/tabs';
 import { ShippingAddressDTO as CrmShippingAddressDTO } from '@generated/swagger/crm-api';
 
+interface SelectCustomerContext {
+  returnUrl?: string;
+  autoTriggerContinueFn?: boolean;
+}
+
 export interface CustomerDetailsViewMainState {
   isBusy: boolean;
   shoppingCart: ShoppingCartDTO;
@@ -80,7 +85,7 @@ export class CustomerDetailsViewMainComponent
   private _router = inject(Router);
   private _activatedRoute = inject(ActivatedRoute);
   private _genderSettings = inject(GenderSettingsService);
-  private _navigationState = inject(NavigationStateService);
+  private _tabService = inject(TabService);
   private _onDestroy$ = new Subject<void>();
 
   customerService = inject(CrmCustomerService);
@@ -97,18 +102,19 @@ export class CustomerDetailsViewMainComponent
     map(([fetchingCustomer, fetchingList]) => fetchingCustomer || fetchingList),
   );
 
-  async getReturnUrlFromContext(): Promise<string | null> {
-    // Get from preserved context (survives intermediate navigations, auto-scoped to tab)
-    const context = await this._navigationState.restoreContext<{
-      returnUrl?: string;
-    }>('select-customer');
+  getReturnUrlFromContext(): string | null {
+    // Get from preserved context (survives intermediate navigations, scoped to tab)
+    const context = this._tabService.activatedTab()?.metadata?.[
+      'select-customer'
+    ] as SelectCustomerContext | undefined;
 
     return context?.returnUrl ?? null;
   }
 
-  async checkHasReturnUrl(): Promise<void> {
-    const hasContext =
-      await this._navigationState.hasPreservedContext('select-customer');
+  checkHasReturnUrl(): void {
+    const hasContext = !!this._tabService.activatedTab()?.metadata?.[
+      'select-customer'
+    ];
     this.hasReturnUrl.set(hasContext);
   }
 
@@ -321,24 +327,23 @@ export class CustomerDetailsViewMainComponent
 
   ngOnInit() {
     // Check if we have a return URL context
-    this.checkHasReturnUrl().then(async () => {
-      // Check if we should auto-trigger continue() (only from Kundenkarte)
-      const context = await this._navigationState.restoreContext<{
-        returnUrl?: string;
-        autoTriggerContinueFn?: boolean;
-      }>('select-customer');
+    this.checkHasReturnUrl();
 
-      if (context?.autoTriggerContinueFn) {
-        // Clear the autoTriggerContinueFn flag immediately (preserves returnUrl automatically)
-        await this._navigationState.patchContext(
-          { autoTriggerContinueFn: undefined },
-          'select-customer',
-        );
+    // Check if we should auto-trigger continue() (only from Kundenkarte)
+    const tab = this._tabService.activatedTab();
+    const context = tab?.metadata?.['select-customer'] as
+      | SelectCustomerContext
+      | undefined;
 
-        // Auto-trigger continue() ONLY when coming from Kundenkarte
-        this.continue();
-      }
-    });
+    if (context?.autoTriggerContinueFn && tab) {
+      // Clear the autoTriggerContinueFn flag immediately (preserves returnUrl)
+      this._tabService.patchTabMetadata(tab.id, {
+        'select-customer': { ...context, autoTriggerContinueFn: undefined },
+      });
+
+      // Auto-trigger continue() ONLY when coming from Kundenkarte
+      this.continue();
+    }
 
     this.processId$
       .pipe(
@@ -436,10 +441,18 @@ export class CustomerDetailsViewMainComponent
 
     // #5262 Check for reward selection flow before navigation
     if (this.hasReturnUrl()) {
-      // Restore from preserved context (auto-scoped to current tab) and clean up
-      const context = await this._navigationState.restoreAndClearContext<{
-        returnUrl?: string;
-      }>('select-customer');
+      // Restore from preserved context (scoped to current tab) and clean up
+      const tab = this._tabService.activatedTab();
+      const context = tab?.metadata?.['select-customer'] as
+        | SelectCustomerContext
+        | undefined;
+
+      // Clear the context
+      if (tab) {
+        this._tabService.patchTabMetadata(tab.id, {
+          'select-customer': null,
+        });
+      }
 
       if (context?.returnUrl) {
         await this._router.navigateByUrl(context.returnUrl);

apps/isa-app/src/page/customer/customer-search/kundenkarte-main-view/kundenkarte-main-view.component.ts

@@ -10,7 +10,7 @@ import {
 import { CustomerSearchStore } from '../store';
 import { ActivatedRoute, Router } from '@angular/router';
 import { map } from 'rxjs/operators';
-import { NavigationStateService } from '@isa/core/navigation';
+import { TabService } from '@isa/core/tabs';
 import { CustomerSearchNavigation } from '@shared/services/navigation';
 import { AsyncPipe } from '@angular/common';
 import { CustomerMenuComponent } from '../../components/customer-menu';
@@ -51,7 +51,7 @@ export class KundenkarteMainViewComponent implements OnDestroy {
   #cardTransactionsResource = inject(CustomerCardTransactionsResource);
   elementRef = inject(ElementRef);
   #router = inject(Router);
-  #navigationState = inject(NavigationStateService);
+  #tabService = inject(TabService);
   #customerNavigationService = inject(CustomerSearchNavigation);
 
   /**
@@ -120,13 +120,12 @@ export class KundenkarteMainViewComponent implements OnDestroy {
     }
 
     // Preserve context for auto-triggering continue() in details view
-    this.#navigationState.preserveContext(
-      {
+    this.#tabService.patchTabMetadata(tabId, {
+      'select-customer': {
         returnUrl: `/${tabId}/reward`,
         autoTriggerContinueFn: true,
       },
-      'select-customer',
-    );
+    });
 
     // Navigate to customer details - will auto-trigger continue()
     await this.#router.navigate(

apps/isa-app/src/ui/modal/dialog/dialog-modal.component.html

@@ -1,16 +1,43 @@
 @if (modalRef.data.subtitle; as subtitle) {
   <h2 class="subtitle">{{ subtitle }}</h2>
 }
-@if (modalRef.data.content; as content) {
-  <p class="content">
-    {{ content }}
-  </p>
+
+<!-- QR Code Display Mode -->
+@if (shouldShowQrCode(); as showQr) {
+  @if (parsedContent(); as parsed) {
+    @if (parsed.textBefore) {
+      <p class="content">{{ parsed.textBefore }}</p>
+    }
+
+    <div class="qr-code-container">
+      <qrcode
+        [qrdata]="parsed.url!"
+        [width]="200"
+        [errorCorrectionLevel]="'M'"
+        [margin]="2"
+      ></qrcode>
+    </div>
+
+    @if (parsed.textAfter) {
+      <p class="content">{{ parsed.textAfter }}</p>
+    }
+  }
+} @else {
+  <!-- Default Text Display Mode -->
+  @if (modalRef.data.content; as content) {
+    <p class="content">
+      {{ content }}
+    </p>
+  }
 }
 
 @if (modalRef.data.actions; as actions) {
   <div class="actions">
     @for (action of actions; track action) {
-      <button [class.selected]="action.selected" (click)="handleCommand(action.command)">
+      <button
+        [class.selected]="action.selected"
+        (click)="handleCommand(action.command)"
+      >
         {{ action.label }}
       </button>
     }

apps/isa-app/src/ui/modal/dialog/dialog-modal.component.scss

@@ -15,11 +15,15 @@
   @apply text-lg text-center whitespace-pre-wrap mb-8 px-16;
 }
 
+.qr-code-container {
+  @apply flex flex-col items-center justify-center mb-8;
+}
+
 .actions {
   @apply text-center mb-8;
 
   button {
-    @apply border-2 border-solid border-brand bg-white text-brand rounded-full py-3 px-6 font-bold text-lg outline-none self-end whitespace-nowrap ml-4;
+    @apply border-2 border-solid border-brand bg-white text-brand rounded-full py-3 px-6 font-bold text-lg outline-none self-end whitespace-nowrap;
 
     &.selected {
       @apply bg-brand text-white;

apps/isa-app/src/ui/modal/dialog/dialog-modal.component.ts

@@ -1,7 +1,8 @@
-import { Component, OnInit } from '@angular/core';
+import { Component, computed, OnInit } from '@angular/core';
 import { CommandService } from '@core/command';
 import { UiModalRef } from '../defs/modal-ref';
 import { DialogModel } from './dialog.model';
+import { parseDialogContentForUrl } from './dialog.helper';
 
 @Component({
   selector: 'ui-dialog-modal',
@@ -10,6 +11,26 @@ import { DialogModel } from './dialog.model';
   standalone: false,
 })
 export class UiDialogModalComponent implements OnInit {
+  /**
+   * Parsed content with URL extracted for QR code display.
+   * Only relevant when showUrlAsQrCode is true.
+   */
+  readonly parsedContent = computed(() => {
+    const data = this.modalRef.data;
+    if (!data.showUrlAsQrCode) {
+      return null;
+    }
+    return parseDialogContentForUrl(data.content);
+  });
+
+  /**
+   * Whether to show the QR code instead of the URL text.
+   */
+  readonly shouldShowQrCode = computed(() => {
+    const parsed = this.parsedContent();
+    return parsed !== null && parsed.url !== null;
+  });
+
   constructor(
     public modalRef: UiModalRef<any, DialogModel<any>>,
     private _command: CommandService,

apps/isa-app/src/ui/modal/dialog/dialog.helper.ts

@@ -0,0 +1,48 @@
+import { ParsedDialogContent } from './dialog.model';
+
+/**
+ * Regular expression to match URLs in text.
+ * Matches http:// and https:// URLs.
+ */
+const URL_REGEX = /https?:\/\/[^\s]+/i;
+
+/**
+ * Parses the dialog content and extracts the first URL.
+ * Splits the content into text before the URL, the URL itself, and text after.
+ *
+ * @param content - The dialog content string to parse
+ * @returns ParsedDialogContent with the split content
+ */
+export const parseDialogContentForUrl = (
+  content: string | undefined,
+): ParsedDialogContent => {
+  if (!content) {
+    return { textBefore: '', url: null, textAfter: '' };
+  }
+
+  const match = content.match(URL_REGEX);
+
+  if (!match || match.index === undefined) {
+    return { textBefore: content, url: null, textAfter: '' };
+  }
+
+  const url = match[0];
+  const urlIndex = match.index;
+  const textBefore = content.substring(0, urlIndex).trim();
+  const textAfter = content.substring(urlIndex + url.length).trim();
+
+  return { textBefore, url, textAfter };
+};
+
+/**
+ * Checks if the given content contains a URL.
+ *
+ * @param content - The content string to check
+ * @returns true if a URL is found, false otherwise
+ */
+export const contentHasUrl = (content: string | undefined): boolean => {
+  if (!content) {
+    return false;
+  }
+  return URL_REGEX.test(content);
+};

apps/isa-app/src/ui/modal/dialog/dialog.model.spec.ts

@@ -0,0 +1,152 @@
+import { contentHasUrl, parseDialogContentForUrl } from './dialog.helper';
+import { ParsedDialogContent } from './dialog.model';
+
+describe('parseDialogContentForUrl', () => {
+  it('should return empty result for undefined content', () => {
+    const result = parseDialogContentForUrl(undefined);
+
+    expect(result).toEqual<ParsedDialogContent>({
+      textBefore: '',
+      url: null,
+      textAfter: '',
+    });
+  });
+
+  it('should return empty result for empty string', () => {
+    const result = parseDialogContentForUrl('');
+
+    expect(result).toEqual<ParsedDialogContent>({
+      textBefore: '',
+      url: null,
+      textAfter: '',
+    });
+  });
+
+  it('should return content as textBefore when no URL is found', () => {
+    const content = 'This is some text without a URL';
+
+    const result = parseDialogContentForUrl(content);
+
+    expect(result).toEqual<ParsedDialogContent>({
+      textBefore: content,
+      url: null,
+      textAfter: '',
+    });
+  });
+
+  it('should extract https URL from content', () => {
+    const content = 'Text before https://example.com text after';
+
+    const result = parseDialogContentForUrl(content);
+
+    expect(result).toEqual<ParsedDialogContent>({
+      textBefore: 'Text before',
+      url: 'https://example.com',
+      textAfter: 'text after',
+    });
+  });
+
+  it('should extract http URL from content', () => {
+    const content = 'Text before http://example.com text after';
+
+    const result = parseDialogContentForUrl(content);
+
+    expect(result).toEqual<ParsedDialogContent>({
+      textBefore: 'Text before',
+      url: 'http://example.com',
+      textAfter: 'text after',
+    });
+  });
+
+  it('should handle URL at the beginning of content', () => {
+    const content = 'https://example.com/path text after';
+
+    const result = parseDialogContentForUrl(content);
+
+    expect(result).toEqual<ParsedDialogContent>({
+      textBefore: '',
+      url: 'https://example.com/path',
+      textAfter: 'text after',
+    });
+  });
+
+  it('should handle URL at the end of content', () => {
+    const content = 'Text before https://example.com/path';
+
+    const result = parseDialogContentForUrl(content);
+
+    expect(result).toEqual<ParsedDialogContent>({
+      textBefore: 'Text before',
+      url: 'https://example.com/path',
+      textAfter: '',
+    });
+  });
+
+  it('should handle real-world content with newlines', () => {
+    const content = `Punkte: 80500
+Um alle Vorteile der Kundenkarte nutzen zu können, ist eine Verknüpfung zu einem Online-Konto notwendig. Kund:innen können sich über den QR-Code selbstständig anmelden oder die Kundenkarte dem bestehendem Konto hinzufügen. Bereits gesammelte Punkte werden übernommen.
+https://h-k.me/QOHNTFVA`;
+
+    const result = parseDialogContentForUrl(content);
+
+    expect(result.url).toBe('https://h-k.me/QOHNTFVA');
+    expect(result.textBefore).toContain('Punkte: 80500');
+    expect(result.textBefore).toContain(
+      'Bereits gesammelte Punkte werden übernommen.',
+    );
+    expect(result.textAfter).toBe('');
+  });
+
+  it('should extract only the first URL when multiple URLs are present', () => {
+    const content = 'First https://first.com then https://second.com';
+
+    const result = parseDialogContentForUrl(content);
+
+    expect(result).toEqual<ParsedDialogContent>({
+      textBefore: 'First',
+      url: 'https://first.com',
+      textAfter: 'then https://second.com',
+    });
+  });
+
+  it('should handle URLs with paths and query parameters', () => {
+    const content =
+      'Visit https://example.com/path?query=value&foo=bar for more';
+
+    const result = parseDialogContentForUrl(content);
+
+    expect(result.url).toBe('https://example.com/path?query=value&foo=bar');
+    expect(result.textBefore).toBe('Visit');
+    expect(result.textAfter).toBe('for more');
+  });
+});
+
+describe('contentHasUrl', () => {
+  it('should return false for undefined content', () => {
+    expect(contentHasUrl(undefined)).toBe(false);
+  });
+
+  it('should return false for empty string', () => {
+    expect(contentHasUrl('')).toBe(false);
+  });
+
+  it('should return false for content without URL', () => {
+    expect(contentHasUrl('This is text without a URL')).toBe(false);
+  });
+
+  it('should return true for content with https URL', () => {
+    expect(contentHasUrl('Check out https://example.com')).toBe(true);
+  });
+
+  it('should return true for content with http URL', () => {
+    expect(contentHasUrl('Check out http://example.com')).toBe(true);
+  });
+
+  it('should return true for real-world content', () => {
+    const content = `Punkte: 80500
+Um alle Vorteile der Kundenkarte nutzen zu können...
+https://h-k.me/QOHNTFVA`;
+
+    expect(contentHasUrl(content)).toBe(true);
+  });
+});

apps/isa-app/src/ui/modal/dialog/dialog.model.ts

@@ -1,4 +1,7 @@
-import { DialogSettings, KeyValueDTOOfStringAndString } from '@generated/swagger/crm-api';
+import {
+  DialogSettings,
+  KeyValueDTOOfStringAndString,
+} from '@generated/swagger/crm-api';
 
 export interface DialogModel<T = any> {
   actions?: Array<KeyValueDTOOfStringAndString>;
@@ -14,4 +17,21 @@ export interface DialogModel<T = any> {
    * default: true
    */
   handleCommand?: boolean;
+  /**
+   * If true, URLs in the content will be displayed as QR codes.
+   * default: false
+   */
+  showUrlAsQrCode?: boolean;
+}
+
+/**
+ * Result of parsing content for URLs
+ */
+export interface ParsedDialogContent {
+  /** Text before the URL */
+  textBefore: string;
+  /** The extracted URL (if any) */
+  url: string | null;
+  /** Text after the URL */
+  textAfter: string;
 }

apps/isa-app/src/ui/modal/dialog/open-dialog.interceptor.ts

@@ -13,6 +13,7 @@ import { Observable, throwError } from 'rxjs';
 import { catchError, tap } from 'rxjs/operators';
 import { DialogModel } from './dialog.model';
 import { ToasterService } from '@shared/shell';
+import { contentHasUrl } from './dialog.helper';
 
 @Injectable()
 export class OpenDialogInterceptor implements HttpInterceptor {
@@ -21,7 +22,10 @@ export class OpenDialogInterceptor implements HttpInterceptor {
     private _toast: ToasterService,
   ) {}
 
-  intercept(req: HttpRequest<any>, next: HttpHandler): Observable<HttpEvent<any>> {
+  intercept(
+    req: HttpRequest<any>,
+    next: HttpHandler,
+  ): Observable<HttpEvent<any>> {
     return next.handle(req).pipe(
       tap((response) => {
         if (response instanceof HttpResponse) {
@@ -59,9 +63,17 @@ export class OpenDialogInterceptor implements HttpInterceptor {
   }
 
   openDialog(model: DialogModel<any>) {
+    // Auto-detect URLs and enable QR code display if URL is found
+    // Can be overridden by explicitly setting showUrlAsQrCode in the model
+    const showUrlAsQrCode =
+      model.showUrlAsQrCode ?? contentHasUrl(model.content);
+
     this._modal.open({
       content: UiDialogModalComponent,
-      data: model,
+      data: {
+        ...model,
+        showUrlAsQrCode,
+      },
       title: model.title,
       config: {
         canClose: (model.settings & 1) === 1,

apps/isa-app/src/ui/modal/modal.module.ts

@@ -2,7 +2,6 @@ import { OverlayModule } from '@angular/cdk/overlay';
 import { CommonModule } from '@angular/common';
 import { ModuleWithProviders, NgModule } from '@angular/core';
 import { UiModalComponent } from './modal.component';
-import { UiModalService } from './modal.service';
 import { UiDebugModalComponent } from './debug-modal/debug-modal.component';
 import { UiMessageModalComponent } from './message-modal.component';
 import { UiIconModule } from '@ui/icon';
@@ -10,9 +9,10 @@ import { UiDialogModalComponent } from './dialog/dialog-modal.component';
 import { HTTP_INTERCEPTORS } from '@angular/common/http';
 import { OpenDialogInterceptor } from './dialog/open-dialog.interceptor';
 import { UiPromptModalComponent } from './prompt-modal';
+import { QRCodeComponent } from 'angularx-qrcode';
 
 @NgModule({
-  imports: [CommonModule, OverlayModule, UiIconModule],
+  imports: [CommonModule, OverlayModule, UiIconModule, QRCodeComponent],
   declarations: [
     UiModalComponent,
     UiDebugModalComponent,

docs/library-reference.md

@@ -1,6 +1,6 @@
 # Library Reference Guide
 
-> **Last Updated:** 2025-12-03
+> **Last Updated:** 2025-12-10
 > **Angular Version:** 20.3.6
 > **Nx Version:** 21.3.2
 > **Total Libraries:** 81
@@ -90,7 +90,7 @@ Reusable title management patterns for Angular applications with reactive update
 
 ---
 
-## Core Libraries (7 libraries)
+## Core Libraries (6 libraries)
 
 ### `@isa/core/auth`
 Type-safe role-based authorization utilities with Angular signals integration for the ISA Frontend application.
@@ -103,7 +103,7 @@ A lightweight, type-safe configuration management system for Angular application
 **Location:** `libs/core/config/`
 
 ### `@isa/core/connectivity`
-This library was generated with [Nx](https://nx.dev).
+**Type:** Util Library
 
 **Location:** `libs/core/connectivity/`
 
@@ -112,11 +112,6 @@ A structured, high-performance logging library for Angular applications with hie
 
 **Location:** `libs/core/logging/`
 
-### `@isa/core/navigation`
-A reusable Angular library providing **context preservation** for multi-step navigation flows with automatic tab-scoped storage.
-
-**Location:** `libs/core/navigation/`
-
 ### `@isa/core/storage`
 A powerful, type-safe storage library for Angular applications built on top of NgRx Signals. This library provides seamless integration between NgRx Signal Stores and various storage backends including localStorage, sessionStorage, IndexedDB, and server-side user state.
 
@@ -435,7 +430,7 @@ A lightweight Zod utility library for safe parsing with automatic fallback to or
 
 ---
 
-## Shell Domain (5 libraries)
+## Shell Domain (6 libraries)
 
 ### `@isa/shell/common`
 **Type:** Util Library
@@ -453,7 +448,7 @@ A lightweight Zod utility library for safe parsing with automatic fallback to or
 **Location:** `libs/shell/layout/`
 
 ### `@isa/shell/navigation`
-This library was generated with [Nx](https://nx.dev).
+Collapsible navigation menu components for the application shell sidebar.
 
 **Location:** `libs/shell/navigation/`
 
@@ -462,6 +457,11 @@ This library was generated with [Nx](https://nx.dev).
 
 **Location:** `libs/shell/notifications/`
 
+### `@isa/shell/tabs`
+UI components for displaying and managing browser-like tabs in the application shell.
+
+**Location:** `libs/shell/tabs/`
+
 ---
 
 ## How to Use This Guide

generated/swagger/oms-api/src/models/display-order-item-dto.ts

@@ -1,5 +1,6 @@
 /* tslint:disable */
 import { EntityDTOBaseOfDisplayOrderItemDTOAndIOrderItem } from './entity-dtobase-of-display-order-item-dtoand-iorder-item';
+import { KeyValueDTOOfStringAndString } from './key-value-dtoof-string-and-string';
 import { LoyaltyDTO } from './loyalty-dto';
 import { DisplayOrderDTO } from './display-order-dto';
 import { PriceDTO } from './price-dto';
@@ -9,6 +10,11 @@ import { QuantityUnitType } from './quantity-unit-type';
 import { DisplayOrderItemSubsetDTO } from './display-order-item-subset-dto';
 export interface DisplayOrderItemDTO extends EntityDTOBaseOfDisplayOrderItemDTOAndIOrderItem{
 
+  /**
+   * Mögliche Aktionen
+   */
+  actions?: Array<KeyValueDTOOfStringAndString>;
+
   /**
    * Bemerkung des Auftraggebers
    */

generated/swagger/oms-api/src/models/display-order-item-subset-dto.ts

@@ -1,10 +1,16 @@
 /* tslint:disable */
 import { EntityDTOBaseOfDisplayOrderItemSubsetDTOAndIOrderItemStatus } from './entity-dtobase-of-display-order-item-subset-dtoand-iorder-item-status';
+import { KeyValueDTOOfStringAndString } from './key-value-dtoof-string-and-string';
 import { DateRangeDTO } from './date-range-dto';
 import { DisplayOrderItemDTO } from './display-order-item-dto';
 import { OrderItemProcessingStatusValue } from './order-item-processing-status-value';
 export interface DisplayOrderItemSubsetDTO extends EntityDTOBaseOfDisplayOrderItemSubsetDTOAndIOrderItemStatus{
 
+  /**
+   * Mögliche Aktionen
+   */
+  actions?: Array<KeyValueDTOOfStringAndString>;
+
   /**
    * Abholfachnummer
    */
@@ -40,6 +46,11 @@ export interface DisplayOrderItemSubsetDTO extends EntityDTOBaseOfDisplayOrderIt
    */
   estimatedShippingDate?: string;
 
+  /**
+   * Zusätzliche Markierungen (z.B. Abo, ...)
+   */
+  features?: {[key: string]: string};
+
   /**
    * Bestellposten
    */

generated/swagger/oms-api/src/models/receipt-dto.ts

@@ -118,6 +118,11 @@ export interface ReceiptDTO extends EntityDTOBaseOfReceiptDTOAndIReceipt{
    */
   receiptNumber?: string;
 
+  /**
+   * Subtype of the receipt / Beleg-Unterart
+   */
+  receiptSubType?: string;
+
   /**
    * Belegtext
    */

libs/checkout/data-access/src/lib/helpers/get-shopping-cart-item-key.helper.ts

@@ -4,12 +4,13 @@ import {
 } from '@isa/checkout/data-access';
 
 /**
- * Creates a unique key for an item based on EAN, destination, and orderItemType.
+ * Creates a unique key for an item based on EAN, targetBranchId, and orderItemType.
  * Items are only considered identical if all three match.
  */
 export const getItemKey = (item: ShoppingCartItem): string => {
   const ean = item.product.ean ?? 'no-ean';
-  const destinationId = item.destination?.data?.id ?? 'no-destination';
+  const targetBranchId =
+    item.destination?.data?.targetBranch?.id ?? 'no-target-branch-id';
   const orderType = getOrderTypeFeature(item.features) ?? 'no-orderType';
-  return `${ean}|${destinationId}|${orderType}`;
+  return `${ean}|${targetBranchId}|${orderType}`;
 };

libs/checkout/feature/reward-catalog/src/lib/reward-action/reward-action.component.ts

@@ -11,14 +11,13 @@ import {
   ShoppingCartFacade,
   SelectedRewardShoppingCartResource,
 } from '@isa/checkout/data-access';
-import { injectTabId } from '@isa/core/tabs';
+import { injectTabId, TabService } from '@isa/core/tabs';
 import { StatefulButtonComponent, StatefulButtonState } from '@isa/ui/buttons';
 import { PurchaseOptionsModalService } from '@modal/purchase-options';
 import { firstValueFrom } from 'rxjs';
 import { Router } from '@angular/router';
 import { getRouteToCustomer } from '../helpers';
 import { PrimaryCustomerCardResource } from '@isa/crm/data-access';
-import { NavigationStateService } from '@isa/core/navigation';
 
 @Component({
   selector: 'reward-action',
@@ -32,7 +31,7 @@ export class RewardActionComponent {
   #store = inject(RewardCatalogStore);
   #tabId = injectTabId();
 
-  #navigationState = inject(NavigationStateService);
+  #tabService = inject(TabService);
   #purchasingOptionsModal = inject(PurchaseOptionsModalService);
   #shoppingCartFacade = inject(ShoppingCartFacade);
   #checkoutMetadataService = inject(CheckoutMetadataService);
@@ -122,12 +121,9 @@ export class RewardActionComponent {
       const route = getRouteToCustomer(tabId);
 
       // Preserve context: Store current reward page URL to return to after customer selection
-      await this.#navigationState.preserveContext(
-        {
-          returnUrl: this.#router.url,
-        },
-        'select-customer',
-      );
+      this.#tabService.patchTabMetadata(tabId, {
+        'select-customer': { returnUrl: this.#router.url },
+      });
 
       await this.#router.navigate(route.path, {
         queryParams: route.queryParams,

libs/checkout/feature/reward-catalog/src/lib/reward-catalog.component.ts

@@ -73,9 +73,6 @@ export class RewardCatalogComponent {
   #filterService = inject(FilterService);
 
   displayStockFilterSwitch = computed(() => {
-    if (this.isCallCenter) {
-      return [];
-    }
     const stockInput = this.#filterService
       .inputs()
       ?.filter((input) => input.target === 'filter')

libs/checkout/feature/reward-catalog/src/lib/reward-header/reward-start-card/reward-start-card.component.ts

@@ -1,9 +1,8 @@
 import { ChangeDetectionStrategy, Component, inject } from '@angular/core';
 import { ButtonComponent } from '@isa/ui/buttons';
-import { injectTabId } from '@isa/core/tabs';
+import { injectTabId, TabService } from '@isa/core/tabs';
 import { Router } from '@angular/router';
 import { getRouteToCustomer } from '../../helpers';
-import { NavigationStateService } from '@isa/core/navigation';
 
 @Component({
   selector: 'reward-start-card',
@@ -13,7 +12,7 @@ import { NavigationStateService } from '@isa/core/navigation';
   imports: [ButtonComponent],
 })
 export class RewardStartCardComponent {
-  readonly #navigationState = inject(NavigationStateService);
+  readonly #tabService = inject(TabService);
   readonly #router = inject(Router);
 
   tabId = injectTabId();
@@ -22,19 +21,19 @@ export class RewardStartCardComponent {
    * Called when "Kund*in auswählen" button is clicked.
    * Preserves the current URL as returnUrl before navigating to customer search.
    */
-  async onSelectCustomer() {
+  onSelectCustomer() {
     const customerRoute = getRouteToCustomer(this.tabId());
+    const tabId = this.#tabService.activatedTabId();
 
     // Preserve context: Store current reward page URL to return to after customer selection
-    await this.#navigationState.preserveContext(
-      {
-        returnUrl: this.#router.url,
-      },
-      'select-customer',
-    );
+    if (tabId) {
+      this.#tabService.patchTabMetadata(tabId, {
+        'select-customer': { returnUrl: this.#router.url },
+      });
+    }
 
     // Navigate to customer search
-    await this.#router.navigate(customerRoute.path, {
+    this.#router.navigate(customerRoute.path, {
       queryParams: customerRoute.queryParams,
     });
   }

libs/checkout/feature/reward-order-confirmation/src/lib/order-confirmation-header/order-confirmation-header.component.ts

@@ -49,7 +49,7 @@ export class OrderConfirmationHeaderComponent {
     if (!orders || orders.length === 0) {
       return '';
     }
-    return orders
+    const formattedDates = orders
       .map((order) => {
         if (!order.orderDate) {
           return null;
@@ -60,7 +60,8 @@ export class OrderConfirmationHeaderComponent {
         );
         return formatted ? `${formatted} Uhr` : null;
       })
-      .filter(Boolean)
-      .join('; ');
+      .filter(Boolean);
+
+    return [...new Set(formattedDates)].join('; ');
   });
 }

libs/checkout/feature/reward-shopping-cart/src/lib/billing-and-shipping-address-card/billing-and-shipping-address-card.component.ts

@@ -14,8 +14,8 @@ import { isaActionEdit } from '@isa/icons';
 import { IconButtonComponent } from '@isa/ui/buttons';
 import { provideIcons } from '@ng-icons/core';
 import { AddressComponent } from '@isa/shared/address';
-import { injectTabId } from '@isa/core/tabs';
-import { NavigationStateService } from '@isa/core/navigation';
+import { injectTabId, TabService } from '@isa/core/tabs';
+import { Router } from '@angular/router';
 
 @Component({
   selector: 'checkout-billing-and-shipping-address-card',
@@ -26,7 +26,8 @@ import { NavigationStateService } from '@isa/core/navigation';
   providers: [provideIcons({ isaActionEdit })],
 })
 export class BillingAndShippingAddressCardComponent {
-  #navigationState = inject(NavigationStateService);
+  #tabService = inject(TabService);
+  #router = inject(Router);
   #shippingAddressResource = inject(SelectedCustomerShippingAddressResource);
   #payerAddressResource = inject(SelectedCustomerPayerAddressResource);
 
@@ -45,18 +46,19 @@ export class BillingAndShippingAddressCardComponent {
     return this.#customerResource.value();
   });
 
-  async navigateToCustomer() {
+  navigateToCustomer() {
     const customerId = this.customer()?.id;
-    if (!customerId) return;
+    const tabId = this.tabId();
+    if (!customerId || !tabId) return;
 
-    const returnUrl = `/${this.tabId()}/reward/cart`;
+    const returnUrl = `/${tabId}/reward/cart`;
 
-    // Preserve context across intermediate navigations (auto-scoped to active tab)
-    await this.#navigationState.navigateWithPreservedContext(
-      ['/', 'kunde', this.tabId(), 'customer', 'search', customerId],
-      { returnUrl },
-      'select-customer',
-    );
+    // Preserve context across intermediate navigations (scoped to active tab)
+    this.#tabService.patchTabMetadata(tabId, {
+      'select-customer': { returnUrl },
+    });
+
+    this.#router.navigate(['/', 'kunde', tabId, 'customer', 'search', customerId]);
   }
 
   payer = computed(() => {

libs/checkout/feature/reward-shopping-cart/src/lib/reward-shopping-cart-item/reward-shopping-cart-item-quantity-control.component.ts

@@ -66,7 +66,8 @@ export class RewardShoppingCartItemQuantityControlComponent {
     if (
       orderType === OrderTypeFeature.Delivery ||
       orderType === OrderTypeFeature.DigitalShipping ||
-      orderType === OrderTypeFeature.B2BShipping
+      orderType === OrderTypeFeature.B2BShipping ||
+      orderType === OrderTypeFeature.Pickup
     ) {
       return 999;
     }

libs/checkout/feature/reward-shopping-cart/src/lib/reward-shopping-cart-item/reward-shopping-cart-item.component.html

@@ -37,11 +37,20 @@
   </div>
 </div>
 
-@if (quantityControl.maxQuantity() < 2 && !isDownload()) {
-  <div
-    class="text-isa-accent-red isa-text-body-2-bold flex flex-row items-center gap-2"
-  >
-    <ng-icon name="isaOtherInfo" size="1.5rem"></ng-icon>
-    <div>Geringer Bestand - Artikel holen vor Abschluss</div>
-  </div>
+@if (!isDownload()) {
+  @if (showLowStockMessage()) {
+    <div
+      class="text-isa-accent-red isa-text-body-2-bold flex flex-row items-center gap-2"
+    >
+      <ng-icon name="isaOtherInfo" size="1.5rem"></ng-icon>
+      <div>{{ inStock() }} Exemplare sofort lieferbar</div>
+    </div>
+  } @else if (quantityControl.maxQuantity() < 2) {
+    <div
+      class="text-isa-accent-red isa-text-body-2-bold flex flex-row items-center gap-2"
+    >
+      <ng-icon name="isaOtherInfo" size="1.5rem"></ng-icon>
+      <div>Geringer Bestand - Artikel holen vor Abschluss</div>
+    </div>
+  }
 }

libs/checkout/feature/reward-shopping-cart/src/lib/reward-shopping-cart-item/reward-shopping-cart-item.component.ts

@@ -72,9 +72,20 @@ export class RewardShoppingCartItemComponent {
     hasOrderTypeFeature(this.item().features, ['Download']),
   );
 
+  isAbholung = computed(() =>
+    hasOrderTypeFeature(this.item().features, ['Abholung']),
+  );
+
+  inStock = computed(() => this.item().availability?.inStock ?? 0);
+
+  showLowStockMessage = computed(() => {
+    return this.isAbholung() && this.inStock() < 2;
+  });
+
   async updatePurchaseOption() {
     const shoppingCartItemId = this.itemId();
     const shoppingCartId = this.shoppingCartId();
+    const branch = this.item().destination?.data?.targetBranch?.data;
 
     if (this.isBusy() || !shoppingCartId || !shoppingCartItemId) {
       return;
@@ -90,6 +101,8 @@ export class RewardShoppingCartItemComponent {
         useRedemptionPoints: true,
         disabledPurchaseOptions: ['b2b-delivery'],
         hideDisabledPurchaseOptions: true,
+        pickupBranch: branch,
+        inStoreBranch: branch,
       });
 
       await firstValueFrom(ref.afterClosed$);

libs/checkout/shared/reward-selection-dialog/src/lib/reward-selection-dialog/reward-selection-error/reward-selection-error.component.css

@@ -1,3 +1,3 @@
 :host {
-  @apply text-isa-accent-red isa-text-body-2-bold flex flex-row gap-2 items-center;
+  @apply text-isa-accent-red isa-text-body-2-bold flex flex-col gap-2 items-start;
 }

libs/checkout/shared/reward-selection-dialog/src/lib/reward-selection-dialog/reward-selection-error/reward-selection-error.component.html

@@ -1,8 +1,10 @@
 @if (store.totalLoyaltyPointsNeeded() > store.customerRewardPoints()) {
-  <ng-icon
-    class="w-6 h-6 inline-flex items-center justify-center"
-    size="1.5rem"
-    name="isaOtherInfo"
-  ></ng-icon>
-  <span>Lesepunkte reichen nicht für alle Artikel</span>
+  <div class="flex flex-row gap-2 items-center">
+    <ng-icon
+      class="w-6 h-6 inline-flex items-center justify-center"
+      size="1.5rem"
+      name="isaOtherInfo"
+    ></ng-icon>
+    <span>Lesepunkte reichen nicht für alle Artikel</span>
+  </div>
 }

libs/checkout/shared/reward-selection-dialog/src/lib/reward-selection-dialog/reward-selection-items/reward-selection-item/reward-selection-inputs/reward-selection-inputs.component.ts

@@ -41,10 +41,7 @@ export class RewardSelectionInputsComponent {
 
   hasCorrectOrderType = computed(() => {
     const item = this.rewardSelectionItem().item;
-    return hasOrderTypeFeature(item.features, [
-      OrderTypeFeature.InStore,
-      OrderTypeFeature.Pickup,
-    ]);
+    return hasOrderTypeFeature(item.features, [OrderTypeFeature.InStore]);
   });
 
   hasStock = computed(() => {

libs/checkout/shared/reward-selection-dialog/src/lib/reward-selection-dialog/reward-selection-items/reward-selection-item/reward-selection-item.component.html

@@ -27,3 +27,16 @@
 
   <lib-reward-selection-inputs></lib-reward-selection-inputs>
 </div>
+
+@if (showLowStockMessage()) {
+  <div
+    class="flex flex-row gap-2 items-center text-isa-accent-red isa-text-body-2-bold"
+  >
+    <ng-icon
+      class="w-6 h-6 inline-flex items-center justify-center"
+      size="1.5rem"
+      name="isaOtherInfo"
+    ></ng-icon>
+    <span>{{ inStock() }} Exemplare sofort lieferbar</span>
+  </div>
+}

libs/checkout/shared/reward-selection-dialog/src/lib/reward-selection-dialog/reward-selection-items/reward-selection-item/reward-selection-item.component.ts

@@ -1,8 +1,18 @@
-import { ChangeDetectionStrategy, Component, input } from '@angular/core';
+import {
+  ChangeDetectionStrategy,
+  Component,
+  computed,
+  input,
+} from '@angular/core';
 import { ProductImageDirective } from '@isa/shared/product-image';
 import { ProductRouterLinkDirective } from '@isa/shared/product-router-link';
 import { RewardSelectionInputsComponent } from './reward-selection-inputs/reward-selection-inputs.component';
-import { RewardSelectionItem } from '@isa/checkout/data-access';
+import {
+  hasOrderTypeFeature,
+  RewardSelectionItem,
+} from '@isa/checkout/data-access';
+import { NgIcon, provideIcons } from '@ng-icons/core';
+import { isaOtherInfo } from '@isa/icons';
 
 @Component({
   selector: 'lib-reward-selection-item',
@@ -13,8 +23,24 @@ import { RewardSelectionItem } from '@isa/checkout/data-access';
     ProductImageDirective,
     ProductRouterLinkDirective,
     RewardSelectionInputsComponent,
+    NgIcon,
   ],
+  providers: [provideIcons({ isaOtherInfo })],
 })
 export class RewardSelectionItemComponent {
   rewardSelectionItem = input.required<RewardSelectionItem>();
+
+  inStock = computed(
+    () => this.rewardSelectionItem().item?.availability?.inStock ?? 0,
+  );
+
+  isAbholung = computed(() =>
+    hasOrderTypeFeature(this.rewardSelectionItem()?.item?.features, [
+      'Abholung',
+    ]),
+  );
+
+  showLowStockMessage = computed(() => {
+    return this.isAbholung() && this.inStock() < 2;
+  });
 }

libs/common/data-access/src/lib/operators/catch-response-args-error.ts

@@ -34,8 +34,15 @@ export const catchResponseArgsErrorPipe = <T>(): OperatorFunction<T, T> =>
       return throwError(() => err);
     }),
     mergeMap((response) => {
-      if (isResponseArgs(response) && response.error === true) {
-        return throwError(() => new ResponseArgsError(response));
+      if (isResponseArgs(response)) {
+        // Treat as error if error flag is true OR if invalidProperties has entries
+        const hasInvalidProps =
+          response.invalidProperties &&
+          Object.keys(response.invalidProperties).length > 0;
+
+        if (response.error === true || hasInvalidProps) {
+          return throwError(() => new ResponseArgsError(response));
+        }
       }
 
       return [response];

libs/core/connectivity/README.md

@@ -1,7 +1,95 @@
-# core-connectivity
+# @isa/core/connectivity
 
-This library was generated with [Nx](https://nx.dev).
+> **Type:** Util Library
+> **Domain:** Core
+> **Path:** `libs/core/connectivity`
 
-## Running unit tests
+## Overview
 
-Run `nx test core-connectivity` to execute the unit tests.
+Network connectivity monitoring service that tracks browser online/offline status using the Navigator API.
+
+## Features
+
+- Real-time network status detection
+- Observable and Signal-based APIs
+- Immediate emission on subscription
+- Shared replay for multiple subscribers
+
+## Installation
+
+```typescript
+import {
+  NetworkStatusService,
+  NetworkStatus,
+  injectNetworkStatus$,
+  injectNetworkStatus
+} from '@isa/core/connectivity';
+```
+
+## Usage
+
+### As Observable
+
+```typescript
+@Component({...})
+export class MyComponent {
+  networkService = inject(NetworkStatusService);
+
+  constructor() {
+    this.networkService.status$.subscribe(status => {
+      console.log('Network status:', status); // 'online' | 'offline'
+    });
+  }
+}
+```
+
+### Using Injection Functions
+
+```typescript
+@Component({...})
+export class MyComponent {
+  // As Observable
+  networkStatus$ = injectNetworkStatus$();
+
+  // As Signal
+  networkStatus = injectNetworkStatus();
+
+  isOffline = computed(() => this.networkStatus() === 'offline');
+}
+```
+
+## API
+
+### NetworkStatusService
+
+| Member | Type | Description |
+|--------|------|-------------|
+| `status$` | `Observable<NetworkStatus>` | Emits network status changes |
+
+### Types
+
+```typescript
+type NetworkStatus = 'online' | 'offline';
+```
+
+### Injection Functions
+
+| Function | Returns | Description |
+|----------|---------|-------------|
+| `injectNetworkStatus$()` | `Observable<NetworkStatus>` | Observable of network status |
+| `injectNetworkStatus()` | `Signal<NetworkStatus \| undefined>` | Signal of network status |
+
+## Dependencies
+
+**External:**
+- `rxjs` - Observable streams
+
+## Testing
+
+```bash
+npx nx test core-connectivity
+```
+
+## Related Libraries
+
+- [`@isa/shell/layout`](../../shell/layout) - Uses for network status banner

libs/core/connectivity/src/lib/network-status.service.ts

@@ -1,5 +1,6 @@
 import { inject, Injectable } from '@angular/core';
 import { toSignal } from '@angular/core/rxjs-interop';
+import { logger } from '@isa/core/logging';
 import {
   map,
   Observable,
@@ -7,22 +8,56 @@ import {
   merge,
   startWith,
   shareReplay,
+  tap,
 } from 'rxjs';
 
+/** Network connectivity status values. */
 export type NetworkStatus = 'online' | 'offline';
 
+/**
+ * Service for monitoring browser network connectivity status.
+ *
+ * Listens to browser online/offline events and provides a reactive
+ * observable that emits the current network status. The observable
+ * is shared and replays the latest value to new subscribers.
+ *
+ * @example
+ * ```typescript
+ * readonly networkService = inject(NetworkStatusService);
+ *
+ * // Subscribe to status changes
+ * this.networkService.status$.subscribe(status => {
+ *   console.log('Network status:', status);
+ * });
+ * ```
+ */
 @Injectable({ providedIn: 'root' })
 export class NetworkStatusService {
+  #logger = logger({ service: 'NetworkStatusService' });
+
+  /**
+   * Observable that emits current network status ('online' | 'offline').
+   * Emits immediately on subscription with current state.
+   */
   readonly status$: Observable<NetworkStatus> = merge(
     fromEvent(window, 'online'),
     fromEvent(window, 'offline'),
   ).pipe(
     startWith(null), // emit immediately
     map((): NetworkStatus => (navigator.onLine ? 'online' : 'offline')),
+    tap((status) => this.#logger.debug('Network status changed', () => ({ status }))),
     shareReplay({ bufferSize: 1, refCount: true }),
   );
 }
 
+/**
+ * Injection function to get the network status observable.
+ * @returns Observable of network status
+ */
 export const injectNetworkStatus$ = () => inject(NetworkStatusService).status$;
 
+/**
+ * Injection function to get network status as a signal.
+ * @returns Signal of network status (undefined initially until first emission)
+ */
 export const injectNetworkStatus = () => toSignal(injectNetworkStatus$());

libs/core/navigation/README.md

@@ -1,855 +0,0 @@
-# @isa/core/navigation
-
-A reusable Angular library providing **context preservation** for multi-step navigation flows with automatic tab-scoped storage.
-
-## Overview
-
-`@isa/core/navigation` solves the problem of **lost navigation state** during intermediate navigations. Unlike Angular's router state which is lost after intermediate navigations, this library persists navigation context in **tab metadata** with automatic cleanup when tabs close.
-
-### The Problem It Solves
-
-```typescript
-// ❌ Problem: Router state is lost during intermediate navigations
-await router.navigate(['/customer/search'], {
-  state: { returnUrl: '/reward/cart' }  // Works for immediate navigation
-});
-
-// After intermediate navigations:
-// /customer/search → /customer/details → /add-shipping-address
-// ⚠️ The returnUrl is LOST!
-```
-
-### The Solution
-
-```typescript
-// ✅ Solution: Context preservation survives intermediate navigations
-navState.preserveContext({ returnUrl: '/reward/cart' });
-// Context persists in tab metadata, automatically cleaned up when tab closes
-
-// After multiple intermediate navigations:
-const context = navState.restoreAndClearContext();
-// ✅ returnUrl is PRESERVED!
-```
-
-## Features
-
-- ✅ **Survives Intermediate Navigations** - State persists across multiple navigation steps
-- ✅ **Automatic Tab Scoping** - Contexts automatically isolated per tab using `TabService`
-- ✅ **Automatic Cleanup** - Contexts cleared automatically when tabs close (no manual cleanup needed)
-- ✅ **Hierarchical Scoping** - Combine tab ID with custom scopes (e.g., `"customer-details"`)
-- ✅ **Type-Safe** - Full TypeScript generics support
-- ✅ **Simple API** - No context IDs to track, scope is the identifier
-- ✅ **Auto-Restore on Refresh** - Contexts survive page refresh (via TabService UserStorage persistence)
-- ✅ **Map-Based Storage** - One context per scope for clarity
-- ✅ **Platform-Agnostic** - Works with Angular Universal (SSR)
-- ✅ **Zero URL Pollution** - No query parameters needed
-
-## Installation
-
-This library is part of the ISA Frontend monorepo. Import from the path alias:
-
-```typescript
-import { NavigationStateService } from '@isa/core/navigation';
-```
-
-## Quick Start
-
-### Basic Flow
-
-```typescript
-import { Component, inject } from '@angular/core';
-import { Router } from '@angular/router';
-import { NavigationStateService } from '@isa/core/navigation';
-
-@Component({
-  selector: 'app-cart',
-  template: `<button (click)="editCustomer()">Edit Customer</button>`
-})
-export class CartComponent {
-  private router = inject(Router);
-  private navState = inject(NavigationStateService);
-
-  async editCustomer() {
-    // Start flow - preserve context (auto-scoped to active tab)
-    this.navState.preserveContext({
-      returnUrl: '/reward/cart',
-      customerId: 123
-    });
-
-    await this.router.navigate(['/customer/search']);
-  }
-}
-
-@Component({
-  selector: 'app-customer-details',
-  template: `<button (click)="complete()">Complete</button>`
-})
-export class CustomerDetailsComponent {
-  private router = inject(Router);
-  private navState = inject(NavigationStateService);
-
-  async complete() {
-    // End flow - restore and auto-cleanup (auto-scoped to active tab)
-    const context = this.navState.restoreAndClearContext<{ returnUrl: string }>();
-
-    if (context?.returnUrl) {
-      await this.router.navigateByUrl(context.returnUrl);
-    }
-  }
-}
-```
-
-### Simplified Navigation
-
-Use `navigateWithPreservedContext()` to combine navigation + context preservation:
-
-```typescript
-async editCustomer() {
-  // Navigate and preserve in one call
-  const { success } = await this.navState.navigateWithPreservedContext(
-    ['/customer/search'],
-    { returnUrl: '/reward/cart', customerId: 123 }
-  );
-}
-```
-
-## Core API
-
-### Context Management
-
-#### `preserveContext<T>(state, customScope?)`
-
-Save navigation context that survives intermediate navigations.
-
-```typescript
-// Default tab scope
-navState.preserveContext({
-  returnUrl: '/reward/cart',
-  selectedItems: [1, 2, 3]
-});
-
-// Custom scope within tab
-navState.preserveContext(
-  { customerId: 42 },
-  'customer-details'  // Stored as 'customer-details' in active tab's metadata
-);
-```
-
-**Parameters:**
-- `state`: The data to preserve (any object)
-- `customScope` (optional): Custom scope within the tab (e.g., `'customer-details'`)
-
-**Storage Location:**
-- Stored in active tab's metadata at: `tab.metadata['navigation-contexts'][scopeKey]`
-- Default scope: `'default'`
-- Custom scope: `customScope` value
-
----
-
-#### `patchContext<T>(partialState, customScope?)`
-
-Partially update preserved context without replacing the entire context.
-
-This method merges partial state with the existing context, preserving properties you don't specify. Properties explicitly set to `undefined` will be removed from the context.
-
-```typescript
-// Existing context: { returnUrl: '/cart', autoTriggerContinueFn: true, customerId: 123 }
-
-// Clear one property while preserving others
-await navState.patchContext(
-  { autoTriggerContinueFn: undefined },
-  'select-customer'
-);
-// Result: { returnUrl: '/cart', customerId: 123 }
-
-// Update one property while preserving others
-await navState.patchContext(
-  { customerId: 456 },
-  'select-customer'
-);
-// Result: { returnUrl: '/cart', customerId: 456 }
-
-// Add new property to existing context
-await navState.patchContext(
-  { selectedTab: 'details' },
-  'select-customer'
-);
-// Result: { returnUrl: '/cart', customerId: 456, selectedTab: 'details' }
-```
-
-**Parameters:**
-- `partialState`: Partial state object to merge (set properties to `undefined` to remove them)
-- `customScope` (optional): Custom scope within the tab
-
-**Use Cases:**
-- Clear trigger flags while preserving flow data
-- Update specific properties without affecting others
-- Remove properties from context
-- Add properties to existing context
-
-**Comparison with `preserveContext`:**
-- `preserveContext`: Replaces entire context (overwrites all properties)
-- `patchContext`: Merges with existing context (updates only specified properties)
-
-```typescript
-// ❌ preserveContext - must manually preserve existing properties
-const context = await navState.restoreContext();
-await navState.preserveContext({
-  returnUrl: context?.returnUrl, // Must specify
-  customerId: context?.customerId, // Must specify
-  autoTriggerContinueFn: undefined, // Clear this
-});
-
-// ✅ patchContext - automatically preserves unspecified properties
-await navState.patchContext({
-  autoTriggerContinueFn: undefined, // Only specify what changes
-});
-```
-
----
-
-#### `restoreContext<T>(customScope?)`
-
-Retrieve preserved context **without** removing it.
-
-```typescript
-// Default tab scope
-const context = navState.restoreContext<{ returnUrl: string }>();
-if (context?.returnUrl) {
-  console.log('Return URL:', context.returnUrl);
-}
-
-// Custom scope
-const context = navState.restoreContext<{ customerId: number }>('customer-details');
-```
-
-**Parameters:**
-- `customScope` (optional): Custom scope to retrieve from (defaults to 'default')
-
-**Returns:** The preserved data, or `null` if not found
-
----
-
-#### `restoreAndClearContext<T>(customScope?)`
-
-Retrieve preserved context **and automatically remove** it (recommended for cleanup).
-
-```typescript
-// Default tab scope
-const context = navState.restoreAndClearContext<{ returnUrl: string }>();
-if (context?.returnUrl) {
-  await router.navigateByUrl(context.returnUrl);
-}
-
-// Custom scope
-const context = navState.restoreAndClearContext<{ customerId: number }>('customer-details');
-```
-
-**Parameters:**
-- `customScope` (optional): Custom scope to retrieve from (defaults to 'default')
-
-**Returns:** The preserved data, or `null` if not found
-
----
-
-#### `clearPreservedContext(customScope?)`
-
-Manually remove a context without retrieving its data.
-
-```typescript
-// Clear default tab scope
-navState.clearPreservedContext();
-
-// Clear custom scope
-navState.clearPreservedContext('customer-details');
-```
-
----
-
-#### `hasPreservedContext(customScope?)`
-
-Check if a context exists.
-
-```typescript
-// Check default tab scope
-if (navState.hasPreservedContext()) {
-  const context = navState.restoreContext();
-}
-
-// Check custom scope
-if (navState.hasPreservedContext('customer-details')) {
-  const context = navState.restoreContext('customer-details');
-}
-```
-
----
-
-### Navigation Helpers
-
-#### `navigateWithPreservedContext(commands, state, customScope?, extras?)`
-
-Navigate and preserve context in one call.
-
-```typescript
-const { success } = await navState.navigateWithPreservedContext(
-  ['/customer/search'],
-  { returnUrl: '/reward/cart' },
-  'customer-flow',  // optional customScope
-  { queryParams: { foo: 'bar' } }  // optional NavigationExtras
-);
-
-// Later...
-const context = navState.restoreAndClearContext('customer-flow');
-```
-
----
-
-### Cleanup Methods
-
-#### `clearScopeContexts()`
-
-Clear all contexts for the active tab (both default and custom scopes).
-
-```typescript
-// Clear all contexts for active tab
-const cleared = this.navState.clearScopeContexts();
-console.log(`Cleaned up ${cleared} contexts`);
-```
-
-**Returns:** Number of contexts cleared
-
-**Note:** This is typically not needed because contexts are **automatically cleaned up when the tab closes**. Use this only for explicit cleanup during the tab's lifecycle.
-
----
-
-## Usage Patterns
-
-### Pattern 1: Multi-Step Flow with Intermediate Navigations
-
-**Problem:** You need to return to a page after multiple intermediate navigations.
-
-```typescript
-// Component A: Start of flow
-export class RewardCartComponent {
-  navState = inject(NavigationStateService);
-  router = inject(Router);
-
-  async selectCustomer() {
-    // Preserve returnUrl (auto-scoped to tab)
-    this.navState.preserveContext({
-      returnUrl: '/reward/cart'
-    });
-
-    await this.router.navigate(['/customer/search']);
-  }
-}
-
-// Component B: Intermediate navigation
-export class CustomerSearchComponent {
-  router = inject(Router);
-
-  async viewDetails(customerId: number) {
-    await this.router.navigate(['/customer/details', customerId]);
-    // Context still persists!
-  }
-}
-
-// Component C: Another intermediate navigation
-export class CustomerDetailsComponent {
-  router = inject(Router);
-
-  async addShippingAddress() {
-    await this.router.navigate(['/add-shipping-address']);
-    // Context still persists!
-  }
-}
-
-// Component D: End of flow
-export class FinalStepComponent {
-  navState = inject(NavigationStateService);
-  router = inject(Router);
-
-  async complete() {
-    // Restore context (auto-scoped to tab) and navigate back
-    const context = this.navState.restoreAndClearContext<{ returnUrl: string }>();
-
-    if (context?.returnUrl) {
-      await this.router.navigateByUrl(context.returnUrl);
-    }
-  }
-}
-```
-
----
-
-### Pattern 2: Multiple Flows in Same Tab
-
-Use custom scopes to manage different flows within the same tab.
-
-```typescript
-export class ComplexPageComponent {
-  navState = inject(NavigationStateService);
-
-  async startCustomerFlow() {
-    // Store context for customer flow
-    this.navState.preserveContext(
-      { returnUrl: '/dashboard', step: 1 },
-      'customer-flow'
-    );
-    // Stored in active tab metadata under scope 'customer-flow'
-  }
-
-  async startProductFlow() {
-    // Store context for product flow
-    this.navState.preserveContext(
-      { returnUrl: '/dashboard', selectedProducts: [1, 2] },
-      'product-flow'
-    );
-    // Stored in active tab metadata under scope 'product-flow'
-  }
-
-  async completeCustomerFlow() {
-    // Restore from customer flow
-    const context = this.navState.restoreAndClearContext('customer-flow');
-  }
-
-  async completeProductFlow() {
-    // Restore from product flow
-    const context = this.navState.restoreAndClearContext('product-flow');
-  }
-}
-```
-
----
-
-### Pattern 3: Complex Context Data
-
-```typescript
-interface CheckoutContext {
-  returnUrl: string;
-  selectedItems: number[];
-  customerId: number;
-  shippingAddressId?: number;
-  metadata: {
-    source: 'reward' | 'checkout';
-    timestamp: number;
-  };
-}
-
-// Save
-navState.preserveContext<CheckoutContext>({
-  returnUrl: '/reward/cart',
-  selectedItems: [1, 2, 3],
-  customerId: 456,
-  metadata: {
-    source: 'reward',
-    timestamp: Date.now()
-  }
-});
-
-// Restore with type safety
-const context = navState.restoreAndClearContext<CheckoutContext>();
-if (context) {
-  console.log('Items:', context.selectedItems);
-  console.log('Customer:', context.customerId);
-}
-```
-
----
-
-### Pattern 4: No Manual Cleanup Needed
-
-```typescript
-export class TabAwareComponent {
-  navState = inject(NavigationStateService);
-
-  async startFlow() {
-    // Set context
-    this.navState.preserveContext({ returnUrl: '/home' });
-
-    // No need to clear in ngOnDestroy!
-    // Context is automatically cleaned up when tab closes
-  }
-
-  // ❌ NOT NEEDED:
-  // ngOnDestroy() {
-  //   this.navState.clearScopeContexts();
-  // }
-}
-```
-
----
-
-## Architecture
-
-### How It Works
-
-```mermaid
-graph LR
-    A[NavigationStateService] --> B[NavigationContextService]
-    B --> C[TabService]
-    C --> D[Tab Metadata Storage]
-    D --> E[UserStorage Persistence]
-
-    style A fill:#e1f5ff
-    style B fill:#e1f5ff
-    style C fill:#fff4e1
-    style D fill:#e8f5e9
-    style E fill:#f3e5f5
-```
-
-1. **Context Storage**: Contexts are stored in **tab metadata** using `TabService`
-2. **Automatic Scoping**: Active tab ID determines storage location automatically
-3. **Hierarchical Keys**: Scopes are organized as `tab.metadata['navigation-contexts'][customScope]`
-4. **Automatic Cleanup**: Contexts removed automatically when tabs close (via tab lifecycle)
-5. **Persistent Across Refresh**: Tab metadata persists via UserStorage, so contexts survive page refresh
-6. **Map-Based**: One context per scope for clarity
-
-### Tab Metadata Structure
-
-```typescript
-// Example: Tab with ID 123
-tab.metadata = {
-  'navigation-contexts': {
-    'default': {
-      data: { returnUrl: '/cart', selectedItems: [1, 2, 3] },
-      createdAt: 1234567890000
-    },
-    'customer-details': {
-      data: { customerId: 42, step: 2 },
-      createdAt: 1234567891000
-    },
-    'product-flow': {
-      data: { productIds: [100, 200], source: 'recommendation' },
-      createdAt: 1234567892000
-    }
-  },
-  // ... other tab metadata
-}
-```
-
-### Storage Layers
-
-```
-┌─────────────────────────────────────┐
-│  NavigationStateService (Public API)│
-└──────────────┬──────────────────────┘
-               │
-               ▼
-┌─────────────────────────────────────┐
-│  NavigationContextService (Storage) │
-└──────────────┬──────────────────────┘
-               │
-               ▼
-┌─────────────────────────────────────┐
-│  TabService.patchTabMetadata()      │
-└──────────────┬──────────────────────┘
-               │
-               ▼
-┌─────────────────────────────────────┐
-│  Tab Metadata Storage (In-Memory)   │
-└──────────────┬──────────────────────┘
-               │
-               ▼
-┌─────────────────────────────────────┐
-│  UserStorage (SessionStorage)       │
-│  (Automatic Persistence)             │
-└─────────────────────────────────────┘
-```
-
-### Integration with TabService
-
-This library **requires** `@isa/core/tabs` for automatic tab scoping:
-
-```typescript
-import { TabService } from '@isa/core/tabs';
-
-// NavigationContextService uses:
-const tabId = this.tabService.activatedTabId();  // Returns: number | null
-
-if (tabId !== null) {
-  // Store in: tab.metadata['navigation-contexts'][customScope]
-  this.tabService.patchTabMetadata(tabId, {
-    'navigation-contexts': {
-      [customScope]: { data, createdAt }
-    }
-  });
-}
-```
-
-**When no tab is active** (tabId = null):
-- Operations throw an error to prevent data loss
-- This ensures contexts are always properly scoped to a tab
-
----
-
-## Migration Guide
-
-### From SessionStorage to Tab Metadata
-
-This library previously used SessionStorage for context persistence. It has been refactored to use tab metadata for better integration with the tab lifecycle and automatic cleanup.
-
-### What Changed
-
-**Storage Location:**
-- **Before**: SessionStorage with key `'isa:navigation:context-map'`
-- **After**: Tab metadata at `tab.metadata['navigation-contexts']`
-
-**Cleanup:**
-- **Before**: Manual cleanup required + automatic expiration after 24 hours
-- **After**: Automatic cleanup when tab closes (no manual cleanup needed)
-
-**Scope Keys:**
-- **Before**: `"123"` (tab ID), `"123-customer-details"` (tab ID + custom scope)
-- **After**: `"default"`, `"customer-details"` (custom scope only, tab ID implicit from storage location)
-
-**TTL Parameter:**
-- **Before**: `preserveContext(data, customScope, ttl)` - TTL respected
-- **After**: `preserveContext(data, customScope, ttl)` - TTL parameter ignored (kept for compatibility)
-
-### What Stayed the Same
-
-✅ **Public API**: All public methods remain unchanged
-✅ **Type Safety**: Full TypeScript support with generics
-✅ **Hierarchical Scoping**: Custom scopes still work the same way
-✅ **Usage Patterns**: All existing code continues to work
-✅ **Persistence**: Contexts still survive page refresh (via TabService UserStorage)
-
-### Benefits of Tab Metadata Approach
-
-1. **Automatic Cleanup**: No need to manually clear contexts or worry about stale data
-2. **Better Integration**: Seamless integration with tab lifecycle management
-3. **Simpler Mental Model**: Contexts are "owned" by tabs, not global storage
-4. **No TTL Management**: Tab lifecycle handles cleanup automatically
-5. **Safer**: Impossible to leak contexts across unrelated tabs
-
-### Migration Steps
-
-**No action required!** The public API is unchanged. Your existing code will continue to work:
-
-```typescript
-// ✅ This code works exactly the same before and after migration
-navState.preserveContext({ returnUrl: '/cart' });
-const context = navState.restoreAndClearContext<{ returnUrl: string }>();
-```
-
-**Optional: Remove manual cleanup code**
-
-If you have manual cleanup in `ngOnDestroy`, you can safely remove it:
-
-```typescript
-// Before (still works, but unnecessary):
-ngOnDestroy() {
-  this.navState.clearScopeContexts();
-}
-
-// After (automatic cleanup):
-ngOnDestroy() {
-  // No cleanup needed - tab lifecycle handles it!
-}
-```
-
-**Note on TTL parameter**
-
-If you were using the TTL parameter, be aware it's now ignored:
-
-```typescript
-// Before: TTL respected
-navState.preserveContext({ data: 'foo' }, undefined, 60000);  // Expires in 1 minute
-
-// After: TTL ignored (context lives until tab closes)
-navState.preserveContext({ data: 'foo' }, undefined, 60000);  // Ignored parameter
-```
-
----
-
-## Testing
-
-### Mocking NavigationStateService
-
-```typescript
-import { ComponentFixture, TestBed } from '@angular/core/testing';
-import { NavigationStateService } from '@isa/core/navigation';
-import { describe, it, expect, beforeEach, vi } from 'vitest';
-
-describe('MyComponent', () => {
-  let component: MyComponent;
-  let fixture: ComponentFixture<MyComponent>;
-  let navStateMock: any;
-
-  beforeEach(async () => {
-    navStateMock = {
-      preserveContext: vi.fn(),
-      restoreContext: vi.fn().mockReturnValue({ returnUrl: '/test' }),
-      restoreAndClearContext: vi.fn().mockReturnValue({ returnUrl: '/test' }),
-      clearPreservedContext: vi.fn().mockReturnValue(true),
-      hasPreservedContext: vi.fn().mockReturnValue(true),
-    };
-
-    await TestBed.configureTestingModule({
-      imports: [MyComponent],
-      providers: [
-        { provide: NavigationStateService, useValue: navStateMock }
-      ]
-    }).compileComponents();
-
-    fixture = TestBed.createComponent(MyComponent);
-    component = fixture.componentInstance;
-  });
-
-  it('should preserve context when navigating', async () => {
-    await component.startFlow();
-
-    expect(navStateMock.preserveContext).toHaveBeenCalledWith({
-      returnUrl: '/reward/cart'
-    });
-  });
-
-  it('should restore context and navigate back', async () => {
-    navStateMock.restoreAndClearContext.mockReturnValue({ returnUrl: '/cart' });
-
-    await component.complete();
-
-    expect(navStateMock.restoreAndClearContext).toHaveBeenCalled();
-    // Assert navigation occurred
-  });
-});
-```
-
----
-
-## Best Practices
-
-### ✅ Do
-
-- **Use `restoreAndClearContext()`** for automatic cleanup when completing flows
-- **Use custom scopes** for multiple concurrent flows in the same tab
-- **Leverage type safety** with TypeScript generics (`<T>`)
-- **Trust automatic cleanup** - no need to manually clear contexts when tabs close
-- **Check for null** when restoring contexts (they may not exist)
-
-### ❌ Don't
-
-- **Don't store large objects** - keep contexts lean (return URLs, IDs, simple flags)
-- **Don't use for persistent data** - use NgRx or services for long-lived state
-- **Don't rely on TTL** - the TTL parameter is ignored in the current implementation
-- **Don't manually clear in ngOnDestroy** - tab lifecycle handles it automatically
-- **Don't store sensitive data** - contexts may be visible in browser dev tools
-
-### When to Use Navigation Context
-
-✅ **Good Use Cases:**
-- Return URLs for multi-step flows
-- Wizard/multi-step form state
-- Temporary search filters or selections
-- Flow-specific context (customer ID during checkout)
-
-❌ **Bad Use Cases:**
-- User preferences (use NgRx or services)
-- Authentication tokens (use dedicated auth service)
-- Large datasets (use data services with caching)
-- Cross-tab communication (use BroadcastChannel or shared services)
-
----
-
-## Configuration
-
-### Constants
-
-All configuration is in `navigation-context.constants.ts`:
-
-```typescript
-// Metadata key for storing contexts in tab metadata
-export const NAVIGATION_CONTEXT_METADATA_KEY = 'navigation-contexts';
-```
-
-**Note:** Previous SessionStorage constants (`DEFAULT_CONTEXT_TTL`, `CLEANUP_INTERVAL`, `NAVIGATION_CONTEXT_STORAGE_KEY`) have been removed as they are no longer needed with tab metadata storage.
-
----
-
-## API Reference Summary
-
-| Method | Parameters | Returns | Purpose |
-|--------|-----------|---------|---------|
-| `preserveContext(state, customScope?)` | state: T, customScope?: string | void | Save context |
-| `patchContext(partialState, customScope?)` | partialState: Partial<T>, customScope?: string | void | Merge partial updates |
-| `restoreContext(customScope?)` | customScope?: string | T \| null | Get context (keep) |
-| `restoreAndClearContext(customScope?)` | customScope?: string | T \| null | Get + remove |
-| `clearPreservedContext(customScope?)` | customScope?: string | boolean | Remove context |
-| `hasPreservedContext(customScope?)` | customScope?: string | boolean | Check exists |
-| `navigateWithPreservedContext(...)` | commands, state, customScope?, extras? | Promise<{success}> | Navigate + preserve |
-| `clearScopeContexts()` | none | number | Bulk cleanup (rarely needed) |
-
----
-
-## Troubleshooting
-
-### Context Not Found After Refresh
-
-**Problem**: Context is `null` after page refresh.
-
-**Solution**: Ensure `TabService` is properly initialized and the tab ID is restored from UserStorage. Contexts rely on tab metadata which persists via UserStorage.
-
-### Context Cleared Unexpectedly
-
-**Problem**: Context disappears before you retrieve it.
-
-**Solution**: Check if you're using `restoreAndClearContext()` multiple times. This method removes the context after retrieval. Use `restoreContext()` if you need to access it multiple times.
-
-### "No active tab" Error
-
-**Problem**: Getting error "No active tab - cannot set navigation context".
-
-**Solution**: Ensure `TabService` has an active tab before using navigation context. This typically happens during app initialization before tabs are ready.
-
-### Context Not Isolated Between Tabs
-
-**Problem**: Contexts from one tab appearing in another.
-
-**Solution**: This should not happen with tab metadata storage. If you see this, it may indicate a TabService issue. Check that `TabService.activatedTabId()` returns the correct tab ID.
-
----
-
-## Running Tests
-
-```bash
-# Run tests
-npx nx test core-navigation
-
-# Run tests with coverage
-npx nx test core-navigation --coverage.enabled=true
-
-# Run tests without cache (CI)
-npx nx test core-navigation --skip-cache
-```
-
-**Test Results:**
-- 79 tests passing
-- 2 test files (navigation-state.service.spec.ts, navigation-context.service.spec.ts)
-
----
-
-## CI/CD Integration
-
-This library generates JUnit and Cobertura reports for Azure Pipelines:
-
-- **JUnit Report**: `testresults/junit-core-navigation.xml`
-- **Cobertura Report**: `coverage/libs/core/navigation/cobertura-coverage.xml`
-
----
-
-## Contributing
-
-This library follows the ISA Frontend monorepo conventions:
-
-- **Path Alias**: `@isa/core/navigation`
-- **Testing Framework**: Vitest with Angular Testing Utilities
-- **Code Style**: ESLint + Prettier
-- **Test Coverage**: Required for all public APIs
-- **Dependencies**: Requires `@isa/core/tabs` for tab scoping
-
----
-
-## License
-
-Internal ISA Frontend monorepo library.

libs/core/navigation/eslint.config.cjs

@@ -1,34 +0,0 @@
-const nx = require('@nx/eslint-plugin');
-const baseConfig = require('../../../eslint.config.js');
-
-module.exports = [
-  ...baseConfig,
-  ...nx.configs['flat/angular'],
-  ...nx.configs['flat/angular-template'],
-  {
-    files: ['**/*.ts'],
-    rules: {
-      '@angular-eslint/directive-selector': [
-        'error',
-        {
-          type: 'attribute',
-          prefix: 'core',
-          style: 'camelCase',
-        },
-      ],
-      '@angular-eslint/component-selector': [
-        'error',
-        {
-          type: 'element',
-          prefix: 'core',
-          style: 'kebab-case',
-        },
-      ],
-    },
-  },
-  {
-    files: ['**/*.html'],
-    // Override or add rules here
-    rules: {},
-  },
-];

libs/core/navigation/project.json

@@ -1,20 +0,0 @@
-{
-  "name": "core-navigation",
-  "$schema": "../../../node_modules/nx/schemas/project-schema.json",
-  "sourceRoot": "libs/core/navigation/src",
-  "prefix": "core",
-  "projectType": "library",
-  "tags": ["skip:ci"],
-  "targets": {
-    "test": {
-      "executor": "@nx/vite:test",
-      "outputs": ["{options.reportsDirectory}"],
-      "options": {
-        "reportsDirectory": "../../../coverage/libs/core/navigation"
-      }
-    },
-    "lint": {
-      "executor": "@nx/eslint:lint"
-    }
-  }
-}

libs/core/navigation/src/index.ts

@@ -1,5 +0,0 @@
-export * from './lib/navigation-state.types';
-export * from './lib/navigation-state.service';
-export * from './lib/navigation-context.types';
-export * from './lib/navigation-context.service';
-export * from './lib/navigation-context.constants';

libs/core/navigation/src/lib/navigation-context.constants.ts

@@ -1,22 +0,0 @@
-/**
- * Constants for navigation context storage in tab metadata.
- * Navigation contexts are stored directly in tab metadata instead of sessionStorage,
- * providing automatic cleanup when tabs are closed and better integration with the tab system.
- */
-
-/**
- * Key used to store navigation contexts in tab metadata.
- * Contexts are stored as: tab.metadata[NAVIGATION_CONTEXT_METADATA_KEY][customScope]
- *
- * @example
- * ```typescript
- * // Structure in tab metadata:
- * tab.metadata = {
- *   'navigation-contexts': {
- *     'default': { data: { returnUrl: '/cart' }, createdAt: 123 },
- *     'customer-details': { data: { customerId: 42 }, createdAt: 456 }
- *   }
- * }
- * ```
- */
-export const NAVIGATION_CONTEXT_METADATA_KEY = 'navigation-contexts';

libs/core/navigation/src/lib/navigation-context.service.spec.ts

@@ -1,668 +0,0 @@
-import { TestBed } from '@angular/core/testing';
-import { describe, it, expect, beforeEach, vi, afterEach } from 'vitest';
-import { signal } from '@angular/core';
-import { NavigationContextService } from './navigation-context.service';
-import { TabService } from '@isa/core/tabs';
-import { ReturnUrlContext } from './navigation-context.types';
-import { NAVIGATION_CONTEXT_METADATA_KEY } from './navigation-context.constants';
-
-describe('NavigationContextService', () => {
-  let service: NavigationContextService;
-  let tabServiceMock: {
-    activatedTabId: ReturnType<typeof signal<number | null>>;
-    entityMap: ReturnType<typeof vi.fn>;
-    patchTabMetadata: ReturnType<typeof vi.fn>;
-  };
-
-  beforeEach(() => {
-    // Create mock TabService with signals and methods
-    tabServiceMock = {
-      activatedTabId: signal<number | null>(null),
-      entityMap: vi.fn(),
-      patchTabMetadata: vi.fn(),
-    };
-
-    TestBed.configureTestingModule({
-      providers: [
-        NavigationContextService,
-        { provide: TabService, useValue: tabServiceMock },
-      ],
-    });
-
-    service = TestBed.inject(NavigationContextService);
-  });
-
-  afterEach(() => {
-    vi.clearAllMocks();
-  });
-
-  it('should be created', () => {
-    expect(service).toBeTruthy();
-  });
-
-  describe('setContext', () => {
-    it('should set context in tab metadata', async () => {
-      // Arrange
-      const tabId = 123;
-      tabServiceMock.activatedTabId.set(tabId);
-      tabServiceMock.entityMap.mockReturnValue({
-        [tabId]: {
-          id: tabId,
-          name: 'Test Tab',
-          metadata: {},
-        },
-      });
-
-      const data: ReturnUrlContext = { returnUrl: '/test-page' };
-
-      // Act
-      await service.setContext(data);
-
-      // Assert
-      expect(tabServiceMock.patchTabMetadata).toHaveBeenCalledWith(
-        tabId,
-        expect.objectContaining({
-          [NAVIGATION_CONTEXT_METADATA_KEY]: expect.objectContaining({
-            default: expect.objectContaining({
-              data,
-              createdAt: expect.any(Number),
-            }),
-          }),
-        }),
-      );
-    });
-
-    it('should set context with custom scope', async () => {
-      // Arrange
-      const tabId = 123;
-      const customScope = 'customer-details';
-      tabServiceMock.activatedTabId.set(tabId);
-      tabServiceMock.entityMap.mockReturnValue({
-        [tabId]: {
-          id: tabId,
-          name: 'Test Tab',
-          metadata: {},
-        },
-      });
-
-      const data = { customerId: 42 };
-
-      // Act
-      await service.setContext(data, customScope);
-
-      // Assert
-      expect(tabServiceMock.patchTabMetadata).toHaveBeenCalledWith(
-        tabId,
-        expect.objectContaining({
-          [NAVIGATION_CONTEXT_METADATA_KEY]: expect.objectContaining({
-            [customScope]: expect.objectContaining({
-              data,
-              createdAt: expect.any(Number),
-            }),
-          }),
-        }),
-      );
-    });
-
-    it('should throw error when no active tab', async () => {
-      // Arrange
-      tabServiceMock.activatedTabId.set(null);
-
-      // Act & Assert
-      await expect(service.setContext({ returnUrl: '/test' })).rejects.toThrow(
-        'No active tab - cannot set navigation context',
-      );
-    });
-
-    it('should merge with existing contexts', async () => {
-      // Arrange
-      const tabId = 123;
-      tabServiceMock.activatedTabId.set(tabId);
-
-      const existingContexts = {
-        'existing-scope': {
-          data: { existingData: 'value' },
-          createdAt: Date.now() - 1000,
-        },
-      };
-
-      tabServiceMock.entityMap.mockReturnValue({
-        [tabId]: {
-          id: tabId,
-          name: 'Test Tab',
-          metadata: {
-            [NAVIGATION_CONTEXT_METADATA_KEY]: existingContexts,
-          },
-        },
-      });
-
-      const newData = { returnUrl: '/new-page' };
-
-      // Act
-      await service.setContext(newData);
-
-      // Assert
-      expect(tabServiceMock.patchTabMetadata).toHaveBeenCalledWith(
-        tabId,
-        expect.objectContaining({
-          [NAVIGATION_CONTEXT_METADATA_KEY]: expect.objectContaining({
-            'existing-scope': existingContexts['existing-scope'],
-            default: expect.objectContaining({
-              data: newData,
-            }),
-          }),
-        }),
-      );
-    });
-
-    it('should accept TTL parameter for backward compatibility', async () => {
-      // Arrange
-      const tabId = 123;
-      tabServiceMock.activatedTabId.set(tabId);
-      tabServiceMock.entityMap.mockReturnValue({
-        [tabId]: {
-          id: tabId,
-          name: 'Test Tab',
-          metadata: {},
-        },
-      });
-
-      // Act
-      await service.setContext({ returnUrl: '/test' }, undefined, 60000);
-
-      // Assert - TTL is ignored but method should still work
-      expect(tabServiceMock.patchTabMetadata).toHaveBeenCalled();
-    });
-  });
-
-  describe('getContext', () => {
-    it('should return null when no active tab', async () => {
-      // Arrange
-      tabServiceMock.activatedTabId.set(null);
-
-      // Act
-      const result = await service.getContext();
-
-      // Assert
-      expect(result).toBeNull();
-    });
-
-    it('should return null when context does not exist', async () => {
-      // Arrange
-      const tabId = 123;
-      tabServiceMock.activatedTabId.set(tabId);
-      tabServiceMock.entityMap.mockReturnValue({
-        [tabId]: {
-          id: tabId,
-          name: 'Test Tab',
-          metadata: {},
-        },
-      });
-
-      // Act
-      const result = await service.getContext();
-
-      // Assert
-      expect(result).toBeNull();
-    });
-
-    it('should retrieve context from default scope', async () => {
-      // Arrange
-      const tabId = 123;
-      const data: ReturnUrlContext = { returnUrl: '/test-page' };
-      tabServiceMock.activatedTabId.set(tabId);
-      tabServiceMock.entityMap.mockReturnValue({
-        [tabId]: {
-          id: tabId,
-          name: 'Test Tab',
-          metadata: {
-            [NAVIGATION_CONTEXT_METADATA_KEY]: {
-              default: {
-                data,
-                createdAt: Date.now(),
-              },
-            },
-          },
-        },
-      });
-
-      // Act
-      const result = await service.getContext<ReturnUrlContext>();
-
-      // Assert
-      expect(result).toEqual(data);
-    });
-
-    it('should retrieve context from custom scope', async () => {
-      // Arrange
-      const tabId = 123;
-      const customScope = 'checkout-flow';
-      const data = { step: 2, productId: 456 };
-      tabServiceMock.activatedTabId.set(tabId);
-      tabServiceMock.entityMap.mockReturnValue({
-        [tabId]: {
-          id: tabId,
-          name: 'Test Tab',
-          metadata: {
-            [NAVIGATION_CONTEXT_METADATA_KEY]: {
-              [customScope]: {
-                data,
-                createdAt: Date.now(),
-              },
-            },
-          },
-        },
-      });
-
-      // Act
-      const result = await service.getContext(customScope);
-
-      // Assert
-      expect(result).toEqual(data);
-    });
-
-    it('should return null when tab not found', async () => {
-      // Arrange
-      const tabId = 123;
-      tabServiceMock.activatedTabId.set(tabId);
-      tabServiceMock.entityMap.mockReturnValue({});
-
-      // Act
-      const result = await service.getContext();
-
-      // Assert
-      expect(result).toBeNull();
-    });
-
-    it('should handle invalid metadata gracefully', async () => {
-      // Arrange
-      const tabId = 123;
-      tabServiceMock.activatedTabId.set(tabId);
-      tabServiceMock.entityMap.mockReturnValue({
-        [tabId]: {
-          id: tabId,
-          name: 'Test Tab',
-          metadata: {
-            [NAVIGATION_CONTEXT_METADATA_KEY]: 'invalid', // Invalid type
-          },
-        },
-      });
-
-      // Act
-      const result = await service.getContext();
-
-      // Assert
-      expect(result).toBeNull();
-    });
-  });
-
-  describe('getAndClearContext', () => {
-    it('should return null when no active tab', async () => {
-      // Arrange
-      tabServiceMock.activatedTabId.set(null);
-
-      // Act
-      const result = await service.getAndClearContext();
-
-      // Assert
-      expect(result).toBeNull();
-    });
-
-    it('should retrieve and remove context from default scope', async () => {
-      // Arrange
-      const tabId = 123;
-      const data: ReturnUrlContext = { returnUrl: '/test-page' };
-      tabServiceMock.activatedTabId.set(tabId);
-      tabServiceMock.entityMap.mockReturnValue({
-        [tabId]: {
-          id: tabId,
-          name: 'Test Tab',
-          metadata: {
-            [NAVIGATION_CONTEXT_METADATA_KEY]: {
-              default: {
-                data,
-                createdAt: Date.now(),
-              },
-            },
-          },
-        },
-      });
-
-      // Act
-      const result = await service.getAndClearContext<ReturnUrlContext>();
-
-      // Assert
-      expect(result).toEqual(data);
-      expect(tabServiceMock.patchTabMetadata).toHaveBeenCalledWith(tabId, {
-        [NAVIGATION_CONTEXT_METADATA_KEY]: {},
-      });
-    });
-
-    it('should retrieve and remove context from custom scope', async () => {
-      // Arrange
-      const tabId = 123;
-      const customScope = 'wizard-flow';
-      const data = { currentStep: 3 };
-      const otherScopeData = { otherData: 'value' };
-
-      tabServiceMock.activatedTabId.set(tabId);
-      tabServiceMock.entityMap.mockReturnValue({
-        [tabId]: {
-          id: tabId,
-          name: 'Test Tab',
-          metadata: {
-            [NAVIGATION_CONTEXT_METADATA_KEY]: {
-              [customScope]: {
-                data,
-                createdAt: Date.now(),
-              },
-              'other-scope': {
-                data: otherScopeData,
-                createdAt: Date.now(),
-              },
-            },
-          },
-        },
-      });
-
-      // Act
-      const result = await service.getAndClearContext(customScope);
-
-      // Assert
-      expect(result).toEqual(data);
-      expect(tabServiceMock.patchTabMetadata).toHaveBeenCalledWith(tabId, {
-        [NAVIGATION_CONTEXT_METADATA_KEY]: {
-          'other-scope': expect.objectContaining({
-            data: otherScopeData,
-          }),
-        },
-      });
-    });
-
-    it('should return null when context not found', async () => {
-      // Arrange
-      const tabId = 123;
-      tabServiceMock.activatedTabId.set(tabId);
-      tabServiceMock.entityMap.mockReturnValue({
-        [tabId]: {
-          id: tabId,
-          name: 'Test Tab',
-          metadata: {},
-        },
-      });
-
-      // Act
-      const result = await service.getAndClearContext();
-
-      // Assert
-      expect(result).toBeNull();
-      expect(tabServiceMock.patchTabMetadata).not.toHaveBeenCalled();
-    });
-  });
-
-  describe('clearContext', () => {
-    it('should return true when context exists and is cleared', async () => {
-      // Arrange
-      const tabId = 123;
-      const data = { returnUrl: '/test' };
-      tabServiceMock.activatedTabId.set(tabId);
-      tabServiceMock.entityMap.mockReturnValue({
-        [tabId]: {
-          id: tabId,
-          name: 'Test Tab',
-          metadata: {
-            [NAVIGATION_CONTEXT_METADATA_KEY]: {
-              default: { data, createdAt: Date.now() },
-            },
-          },
-        },
-      });
-
-      // Act
-      const result = await service.clearContext();
-
-      // Assert
-      expect(result).toBe(true);
-    });
-
-    it('should return false when context not found', async () => {
-      // Arrange
-      const tabId = 123;
-      tabServiceMock.activatedTabId.set(tabId);
-      tabServiceMock.entityMap.mockReturnValue({
-        [tabId]: {
-          id: tabId,
-          name: 'Test Tab',
-          metadata: {},
-        },
-      });
-
-      // Act
-      const result = await service.clearContext();
-
-      // Assert
-      expect(result).toBe(false);
-    });
-  });
-
-  describe('clearScope', () => {
-    it('should clear all contexts for active tab', async () => {
-      // Arrange
-      const tabId = 123;
-      const contexts = {
-        default: { data: { url: '/test' }, createdAt: Date.now() },
-        'scope-1': { data: { value: 1 }, createdAt: Date.now() },
-        'scope-2': { data: { value: 2 }, createdAt: Date.now() },
-      };
-
-      tabServiceMock.activatedTabId.set(tabId);
-      tabServiceMock.entityMap.mockReturnValue({
-        [tabId]: {
-          id: tabId,
-          name: 'Test Tab',
-          metadata: {
-            [NAVIGATION_CONTEXT_METADATA_KEY]: contexts,
-          },
-        },
-      });
-
-      // Act
-      const clearedCount = await service.clearScope();
-
-      // Assert
-      expect(clearedCount).toBe(3);
-      expect(tabServiceMock.patchTabMetadata).toHaveBeenCalledWith(tabId, {
-        [NAVIGATION_CONTEXT_METADATA_KEY]: {},
-      });
-    });
-
-    it('should return 0 when no contexts exist', async () => {
-      // Arrange
-      const tabId = 123;
-      tabServiceMock.activatedTabId.set(tabId);
-      tabServiceMock.entityMap.mockReturnValue({
-        [tabId]: {
-          id: tabId,
-          name: 'Test Tab',
-          metadata: {},
-        },
-      });
-
-      // Act
-      const clearedCount = await service.clearScope();
-
-      // Assert
-      expect(clearedCount).toBe(0);
-      expect(tabServiceMock.patchTabMetadata).not.toHaveBeenCalled();
-    });
-
-    it('should return 0 when no active tab', async () => {
-      // Arrange
-      tabServiceMock.activatedTabId.set(null);
-
-      // Act
-      const clearedCount = await service.clearScope();
-
-      // Assert
-      expect(clearedCount).toBe(0);
-    });
-  });
-
-  describe('clearAll', () => {
-    it('should clear all contexts for active tab', async () => {
-      // Arrange
-      const tabId = 123;
-      const contexts = {
-        default: { data: { url: '/test' }, createdAt: Date.now() },
-      };
-
-      tabServiceMock.activatedTabId.set(tabId);
-      tabServiceMock.entityMap.mockReturnValue({
-        [tabId]: {
-          id: tabId,
-          name: 'Test Tab',
-          metadata: {
-            [NAVIGATION_CONTEXT_METADATA_KEY]: contexts,
-          },
-        },
-      });
-
-      // Act
-      await service.clearAll();
-
-      // Assert
-      expect(tabServiceMock.patchTabMetadata).toHaveBeenCalledWith(tabId, {
-        [NAVIGATION_CONTEXT_METADATA_KEY]: {},
-      });
-    });
-  });
-
-  describe('hasContext', () => {
-    it('should return true when context exists', async () => {
-      // Arrange
-      const tabId = 123;
-      const data = { returnUrl: '/test' };
-      tabServiceMock.activatedTabId.set(tabId);
-      tabServiceMock.entityMap.mockReturnValue({
-        [tabId]: {
-          id: tabId,
-          name: 'Test Tab',
-          metadata: {
-            [NAVIGATION_CONTEXT_METADATA_KEY]: {
-              default: { data, createdAt: Date.now() },
-            },
-          },
-        },
-      });
-
-      // Act
-      const result = await service.hasContext();
-
-      // Assert
-      expect(result).toBe(true);
-    });
-
-    it('should return false when context does not exist', async () => {
-      // Arrange
-      const tabId = 123;
-      tabServiceMock.activatedTabId.set(tabId);
-      tabServiceMock.entityMap.mockReturnValue({
-        [tabId]: {
-          id: tabId,
-          name: 'Test Tab',
-          metadata: {},
-        },
-      });
-
-      // Act
-      const result = await service.hasContext();
-
-      // Assert
-      expect(result).toBe(false);
-    });
-
-    it('should check custom scope', async () => {
-      // Arrange
-      const tabId = 123;
-      const customScope = 'wizard';
-      const data = { step: 1 };
-      tabServiceMock.activatedTabId.set(tabId);
-      tabServiceMock.entityMap.mockReturnValue({
-        [tabId]: {
-          id: tabId,
-          name: 'Test Tab',
-          metadata: {
-            [NAVIGATION_CONTEXT_METADATA_KEY]: {
-              [customScope]: { data, createdAt: Date.now() },
-            },
-          },
-        },
-      });
-
-      // Act
-      const result = await service.hasContext(customScope);
-
-      // Assert
-      expect(result).toBe(true);
-    });
-  });
-
-  describe('getContextCount', () => {
-    it('should return total number of contexts for active tab', async () => {
-      // Arrange
-      const tabId = 123;
-      const contexts = {
-        default: { data: { url: '/test' }, createdAt: Date.now() },
-        'scope-1': { data: { value: 1 }, createdAt: Date.now() },
-        'scope-2': { data: { value: 2 }, createdAt: Date.now() },
-      };
-
-      tabServiceMock.activatedTabId.set(tabId);
-      tabServiceMock.entityMap.mockReturnValue({
-        [tabId]: {
-          id: tabId,
-          name: 'Test Tab',
-          metadata: {
-            [NAVIGATION_CONTEXT_METADATA_KEY]: contexts,
-          },
-        },
-      });
-
-      // Act
-      const count = await service.getContextCount();
-
-      // Assert
-      expect(count).toBe(3);
-    });
-
-    it('should return 0 when no contexts exist', async () => {
-      // Arrange
-      const tabId = 123;
-      tabServiceMock.activatedTabId.set(tabId);
-      tabServiceMock.entityMap.mockReturnValue({
-        [tabId]: {
-          id: tabId,
-          name: 'Test Tab',
-          metadata: {},
-        },
-      });
-
-      // Act
-      const count = await service.getContextCount();
-
-      // Assert
-      expect(count).toBe(0);
-    });
-
-    it('should return 0 when no active tab', async () => {
-      // Arrange
-      tabServiceMock.activatedTabId.set(null);
-
-      // Act
-      const count = await service.getContextCount();
-
-      // Assert
-      expect(count).toBe(0);
-    });
-  });
-});

libs/core/navigation/src/lib/navigation-context.service.ts

@@ -1,442 +0,0 @@
-import { Injectable, inject } from '@angular/core';
-import { TabService } from '@isa/core/tabs';
-import { logger } from '@isa/core/logging';
-import {
-  NavigationContext,
-  NavigationContextData,
-  NavigationContextsMetadataSchema,
-} from './navigation-context.types';
-import { NAVIGATION_CONTEXT_METADATA_KEY } from './navigation-context.constants';
-
-/**
- * Service for managing navigation context using tab metadata storage.
- *
- * This service provides a type-safe approach to preserving navigation state
- * across intermediate navigations, solving the problem of lost router state
- * in multi-step flows.
- *
- * Key Features:
- * - Stores contexts in tab metadata (automatic cleanup when tab closes)
- * - Type-safe with Zod validation
- * - Scoped to individual tabs (no cross-tab pollution)
- * - Simple API with hierarchical scoping support
- *
- * Storage Architecture:
- * - Contexts stored at: `tab.metadata[NAVIGATION_CONTEXT_METADATA_KEY]`
- * - Structure: `{ [customScope]: { data, createdAt } }`
- * - No manual cleanup needed (handled by tab lifecycle)
- *
- * @example
- * ```typescript
- * // Start of flow - preserve context (auto-scoped to active tab)
- * contextService.setContext({
- *   returnUrl: '/original-page',
- *   customerId: 123
- * });
- *
- * // ... intermediate navigations happen ...
- *
- * // End of flow - restore and cleanup
- * const context = contextService.getAndClearContext<{ returnUrl: string }>();
- * if (context?.returnUrl) {
- *   await router.navigateByUrl(context.returnUrl);
- * }
- * ```
- */
-@Injectable({ providedIn: 'root' })
-export class NavigationContextService {
-  readonly #tabService = inject(TabService);
-  readonly #log = logger(() => ({ module: 'navigation-context' }));
-
-  /**
-   * Get the navigation contexts map from tab metadata.
-   *
-   * @param tabId The tab ID to get contexts for
-   * @returns Record of scope keys to contexts, or empty object if not found
-   */
-  #getContextsMap(tabId: number): Record<string, NavigationContext> {
-    const tab = this.#tabService.entityMap()[tabId];
-    if (!tab) {
-      this.#log.debug('Tab not found', () => ({ tabId }));
-      return {};
-    }
-
-    const contextsMap = tab.metadata[NAVIGATION_CONTEXT_METADATA_KEY];
-    if (!contextsMap) {
-      return {};
-    }
-
-    // Validate with Zod schema
-    const result = NavigationContextsMetadataSchema.safeParse(contextsMap);
-    if (!result.success) {
-      this.#log.warn('Invalid contexts map in tab metadata', () => ({
-        tabId,
-        validationErrors: result.error.errors,
-      }));
-      return {};
-    }
-
-    return result.data as Record<string, NavigationContext>;
-  }
-
-  /**
-   * Save the navigation contexts map to tab metadata.
-   *
-   * @param tabId The tab ID to save contexts to
-   * @param contextsMap The contexts map to save
-   */
-  #saveContextsMap(
-    tabId: number,
-    contextsMap: Record<string, NavigationContext>,
-  ): void {
-    this.#tabService.patchTabMetadata(tabId, {
-      [NAVIGATION_CONTEXT_METADATA_KEY]: contextsMap,
-    });
-  }
-
-  /**
-   * Set a context in the active tab's metadata.
-   *
-   * Creates or overwrites a navigation context and persists it to tab metadata.
-   * The context will automatically be cleaned up when the tab is closed.
-   *
-   * @template T The type of data being stored in the context
-   * @param data The navigation data to preserve
-   * @param customScope Optional custom scope (defaults to 'default')
-   * @param _ttl Optional TTL parameter (kept for API compatibility but ignored)
-   *
-   * @example
-   * ```typescript
-   * // Set context for default scope
-   * contextService.setContext({ returnUrl: '/products', selectedIds: [1, 2, 3] });
-   *
-   * // Set context for custom scope
-   * contextService.setContext({ customerId: 42 }, 'customer-details');
-   * ```
-   */
-  async setContext<T extends NavigationContextData>(
-    data: T,
-    customScope?: string,
-    // eslint-disable-next-line @typescript-eslint/no-unused-vars
-    _ttl?: number, // Kept for API compatibility but ignored
-  ): Promise<void> {
-    const tabId = this.#tabService.activatedTabId();
-    if (tabId === null) {
-      throw new Error('No active tab - cannot set navigation context');
-    }
-
-    const scopeKey = customScope || 'default';
-    const context: NavigationContext = {
-      data,
-      createdAt: Date.now(),
-    };
-
-    const contextsMap = this.#getContextsMap(tabId);
-    contextsMap[scopeKey] = context;
-    this.#saveContextsMap(tabId, contextsMap);
-
-    this.#log.debug('Context set in tab metadata', () => ({
-      tabId,
-      scopeKey,
-      dataKeys: Object.keys(data),
-      totalContexts: Object.keys(contextsMap).length,
-    }));
-  }
-
-  /**
-   * Patch a context in the active tab's metadata.
-   *
-   * Merges partial data with the existing context, preserving unspecified properties.
-   * Properties explicitly set to `undefined` will be removed from the context.
-   * If the context doesn't exist, creates a new one (behaves like setContext).
-   *
-   * @template T The type of data being patched
-   * @param partialData The partial navigation data to merge
-   * @param customScope Optional custom scope (defaults to 'default')
-   *
-   * @example
-   * ```typescript
-   * // Clear one property while preserving others
-   * contextService.patchContext({ autoTriggerContinueFn: undefined }, 'select-customer');
-   *
-   * // Update one property while preserving others
-   * contextService.patchContext({ selectedTab: 'details' }, 'customer-flow');
-   * ```
-   */
-  async patchContext<T extends NavigationContextData>(
-    partialData: Partial<T>,
-    customScope?: string,
-  ): Promise<void> {
-    const tabId = this.#tabService.activatedTabId();
-    if (tabId === null) {
-      throw new Error('No active tab - cannot patch navigation context');
-    }
-
-    const scopeKey = customScope || 'default';
-    const existingContext = await this.getContext<T>(customScope);
-
-    const mergedData = {
-      ...(existingContext ?? {}),
-      ...partialData,
-    };
-
-    // Remove properties explicitly set to undefined
-    const removedKeys: string[] = [];
-    Object.keys(mergedData).forEach((key) => {
-      if (mergedData[key] === undefined) {
-        removedKeys.push(key);
-        delete mergedData[key];
-      }
-    });
-
-    const contextsMap = this.#getContextsMap(tabId);
-    const context: NavigationContext = {
-      data: mergedData,
-      createdAt:
-        existingContext && contextsMap[scopeKey]
-          ? contextsMap[scopeKey].createdAt
-          : Date.now(),
-    };
-
-    contextsMap[scopeKey] = context;
-    this.#saveContextsMap(tabId, contextsMap);
-
-    this.#log.debug('Context patched in tab metadata', () => ({
-      tabId,
-      scopeKey,
-      patchedKeys: Object.keys(partialData),
-      removedKeys,
-      totalDataKeys: Object.keys(mergedData),
-      wasUpdate: existingContext !== null,
-      totalContexts: Object.keys(contextsMap).length,
-    }));
-  }
-
-  /**
-   * Get a context from the active tab's metadata without removing it.
-   *
-   * Retrieves a preserved navigation context by scope.
-   *
-   * @template T The expected type of the context data
-   * @param customScope Optional custom scope (defaults to 'default')
-   * @returns The context data, or null if not found
-   *
-   * @example
-   * ```typescript
-   * // Get context for default scope
-   * const context = contextService.getContext<{ returnUrl: string }>();
-   *
-   * // Get context for custom scope
-   * const context = contextService.getContext<{ customerId: number }>('customer-details');
-   * ```
-   */
-  async getContext<T extends NavigationContextData = NavigationContextData>(
-    customScope?: string,
-  ): Promise<T | null> {
-    const tabId = this.#tabService.activatedTabId();
-    if (tabId === null) {
-      this.#log.debug('No active tab - cannot get context');
-      return null;
-    }
-
-    const scopeKey = customScope || 'default';
-    const contextsMap = this.#getContextsMap(tabId);
-    const context = contextsMap[scopeKey];
-
-    if (!context) {
-      this.#log.debug('Context not found', () => ({ tabId, scopeKey }));
-      return null;
-    }
-
-    this.#log.debug('Context retrieved', () => ({
-      tabId,
-      scopeKey,
-      dataKeys: Object.keys(context.data),
-    }));
-
-    return context.data as T;
-  }
-
-  /**
-   * Get a context from the active tab's metadata and remove it.
-   *
-   * Retrieves a preserved navigation context and removes it from the metadata.
-   * Use this when completing a flow to clean up automatically.
-   *
-   * @template T The expected type of the context data
-   * @param customScope Optional custom scope (defaults to 'default')
-   * @returns The context data, or null if not found
-   *
-   * @example
-   * ```typescript
-   * // Get and clear context for default scope
-   * const context = contextService.getAndClearContext<{ returnUrl: string }>();
-   * if (context?.returnUrl) {
-   *   await router.navigateByUrl(context.returnUrl);
-   * }
-   *
-   * // Get and clear context for custom scope
-   * const context = contextService.getAndClearContext<{ customerId: number }>('customer-details');
-   * ```
-   */
-  async getAndClearContext<
-    T extends NavigationContextData = NavigationContextData,
-  >(customScope?: string): Promise<T | null> {
-    const tabId = this.#tabService.activatedTabId();
-    if (tabId === null) {
-      this.#log.debug('No active tab - cannot get and clear context');
-      return null;
-    }
-
-    const scopeKey = customScope || 'default';
-    const contextsMap = this.#getContextsMap(tabId);
-    const context = contextsMap[scopeKey];
-
-    if (!context) {
-      this.#log.debug('Context not found for clearing', () => ({
-        tabId,
-        scopeKey,
-      }));
-      return null;
-    }
-
-    // Remove from map
-    delete contextsMap[scopeKey];
-    this.#saveContextsMap(tabId, contextsMap);
-
-    this.#log.debug('Context retrieved and cleared', () => ({
-      tabId,
-      scopeKey,
-      dataKeys: Object.keys(context.data),
-      remainingContexts: Object.keys(contextsMap).length,
-    }));
-
-    return context.data as T;
-  }
-
-  /**
-   * Clear a specific context from the active tab's metadata.
-   *
-   * Removes a context without returning its data.
-   * Useful for explicit cleanup without needing the data.
-   *
-   * @param customScope Optional custom scope (defaults to 'default')
-   * @returns true if context was found and cleared, false otherwise
-   *
-   * @example
-   * ```typescript
-   * // Clear context for default scope
-   * contextService.clearContext();
-   *
-   * // Clear context for custom scope
-   * contextService.clearContext('customer-details');
-   * ```
-   */
-  async clearContext(customScope?: string): Promise<boolean> {
-    const result = await this.getAndClearContext(customScope);
-    return result !== null;
-  }
-
-  /**
-   * Clear all contexts for the active tab.
-   *
-   * Removes all contexts from the active tab's metadata.
-   * Useful for cleanup when a workflow is cancelled or completed.
-   *
-   * @returns The number of contexts cleared
-   *
-   * @example
-   * ```typescript
-   * // Clear all contexts for active tab
-   * const cleared = contextService.clearScope();
-   * console.log(`Cleared ${cleared} contexts`);
-   * ```
-   */
-  async clearScope(): Promise<number> {
-    const tabId = this.#tabService.activatedTabId();
-    if (tabId === null) {
-      this.#log.warn('Cannot clear scope: no active tab');
-      return 0;
-    }
-
-    const contextsMap = this.#getContextsMap(tabId);
-    const contextCount = Object.keys(contextsMap).length;
-
-    if (contextCount === 0) {
-      return 0;
-    }
-
-    // Clear entire metadata key
-    this.#tabService.patchTabMetadata(tabId, {
-      [NAVIGATION_CONTEXT_METADATA_KEY]: {},
-    });
-
-    this.#log.debug('Tab scope cleared', () => ({
-      tabId,
-      clearedCount: contextCount,
-    }));
-
-    return contextCount;
-  }
-
-  /**
-   * Clear all contexts from the active tab (alias for clearScope).
-   *
-   * This method is kept for backward compatibility with the previous API.
-   * It clears all contexts for the active tab only, not globally.
-   *
-   * @example
-   * ```typescript
-   * contextService.clearAll();
-   * ```
-   */
-  async clearAll(): Promise<void> {
-    await this.clearScope();
-    this.#log.debug('All contexts cleared for active tab');
-  }
-
-  /**
-   * Check if a context exists for the active tab.
-   *
-   * @param customScope Optional custom scope (defaults to 'default')
-   * @returns true if context exists, false otherwise
-   *
-   * @example
-   * ```typescript
-   * // Check default scope
-   * if (contextService.hasContext()) {
-   *   const context = contextService.getContext();
-   * }
-   *
-   * // Check custom scope
-   * if (contextService.hasContext('customer-details')) {
-   *   const context = contextService.getContext('customer-details');
-   * }
-   * ```
-   */
-  async hasContext(customScope?: string): Promise<boolean> {
-    const context = await this.getContext(customScope);
-    return context !== null;
-  }
-
-  /**
-   * Get the current context count for the active tab (for debugging/monitoring).
-   *
-   * @returns The total number of contexts in the active tab's metadata
-   *
-   * @example
-   * ```typescript
-   * const count = await contextService.getContextCount();
-   * console.log(`Active tab has ${count} contexts`);
-   * ```
-   */
-  async getContextCount(): Promise<number> {
-    const tabId = this.#tabService.activatedTabId();
-    if (tabId === null) {
-      return 0;
-    }
-
-    const contextsMap = this.#getContextsMap(tabId);
-    return Object.keys(contextsMap).length;
-  }
-}

libs/core/navigation/src/lib/navigation-context.types.ts

@@ -1,102 +0,0 @@
-import { z } from 'zod';
-
-/**
- * Base interface for navigation context data.
- * Extend this interface for type-safe context preservation.
- *
- * @example
- * ```typescript
- * interface MyFlowContext extends NavigationContextData {
- *   returnUrl: string;
- *   selectedItems: number[];
- * }
- * ```
- */
-export interface NavigationContextData {
-  [key: string]: unknown;
-}
-
-/**
- * Navigation context stored in tab metadata.
- * Represents a single preserved navigation state with metadata.
- * Stored at: tab.metadata[NAVIGATION_CONTEXT_METADATA_KEY][customScope]
- */
-export interface NavigationContext {
-  /** The preserved navigation state/data */
-  data: NavigationContextData;
-  /** Timestamp when context was created (for debugging and monitoring) */
-  createdAt: number;
-  /**
-   * Optional expiration timestamp (reserved for future TTL implementation)
-   * @deprecated Currently unused - contexts are cleaned up automatically when tabs close
-   */
-  expiresAt?: number;
-}
-
-/**
- * Zod schema for navigation context data validation.
- */
-export const NavigationContextDataSchema = z.record(z.string(), z.unknown());
-
-/**
- * Zod schema for navigation context validation.
- */
-export const NavigationContextSchema = z.object({
-  data: NavigationContextDataSchema,
-  createdAt: z.number().positive(),
-  expiresAt: z.number().positive().optional(),
-});
-
-/**
- * Zod schema for navigation contexts stored in tab metadata.
- * Structure: { [customScope: string]: NavigationContext }
- *
- * @example
- * ```typescript
- * {
- *   "default": { data: { returnUrl: '/cart' }, createdAt: 123, expiresAt: 456 },
- *   "customer-details": { data: { customerId: 42 }, createdAt: 123 }
- * }
- * ```
- */
-export const NavigationContextsMetadataSchema = z.record(
-  z.string(),
-  NavigationContextSchema
-);
-
-/**
- * Common navigation context for "return URL" pattern.
- * Used when navigating through a flow and needing to return to the original location.
- *
- * @example
- * ```typescript
- * navContextService.preserveContext({
- *   returnUrl: '/original-page'
- * });
- * ```
- */
-export interface ReturnUrlContext extends NavigationContextData {
-  returnUrl: string;
-}
-
-/**
- * Extended context with additional flow metadata.
- * Useful for complex multi-step flows that need to preserve additional state.
- *
- * @example
- * ```typescript
- * interface CheckoutFlowContext extends FlowContext {
- *   returnUrl: string;
- *   selectedProductIds: number[];
- *   shippingAddressId?: number;
- * }
- * ```
- */
-export interface FlowContext extends NavigationContextData {
-  /** Step identifier for multi-step flows */
-  currentStep?: string;
-  /** Total number of steps (if known) */
-  totalSteps?: number;
-  /** Flow-specific metadata */
-  metadata?: Record<string, unknown>;
-}

libs/core/navigation/src/lib/navigation-state.service.spec.ts

@@ -1,227 +0,0 @@
-import { TestBed } from '@angular/core/testing';
-import { Location } from '@angular/common';
-import { Router } from '@angular/router';
-import { describe, it, expect, beforeEach, vi } from 'vitest';
-import { NavigationStateService } from './navigation-state.service';
-import { NavigationContextService } from './navigation-context.service';
-import { ReturnUrlContext } from './navigation-context.types';
-
-describe('NavigationStateService', () => {
-  let service: NavigationStateService;
-  let locationMock: { getState: ReturnType<typeof vi.fn> };
-  let routerMock: { navigate: ReturnType<typeof vi.fn> };
-  let contextServiceMock: {
-    setContext: ReturnType<typeof vi.fn>;
-    getContext: ReturnType<typeof vi.fn>;
-    getAndClearContext: ReturnType<typeof vi.fn>;
-    clearContext: ReturnType<typeof vi.fn>;
-    hasContext: ReturnType<typeof vi.fn>;
-    clearScope: ReturnType<typeof vi.fn>;
-  };
-
-  beforeEach(() => {
-    locationMock = {
-      getState: vi.fn(),
-    };
-
-    routerMock = {
-      navigate: vi.fn(),
-    };
-
-    contextServiceMock = {
-      setContext: vi.fn().mockResolvedValue(undefined),
-      getContext: vi.fn().mockResolvedValue(null),
-      getAndClearContext: vi.fn().mockResolvedValue(null),
-      clearContext: vi.fn().mockResolvedValue(false),
-      hasContext: vi.fn().mockResolvedValue(false),
-      clearScope: vi.fn().mockResolvedValue(0),
-    };
-
-    TestBed.configureTestingModule({
-      providers: [
-        NavigationStateService,
-        { provide: Location, useValue: locationMock },
-        { provide: Router, useValue: routerMock },
-        { provide: NavigationContextService, useValue: contextServiceMock },
-      ],
-    });
-
-    service = TestBed.inject(NavigationStateService);
-  });
-
-  it('should be created', () => {
-    expect(service).toBeTruthy();
-  });
-
-  // Context Preservation Methods Tests
-
-  describe('preserveContext', () => {
-    it('should call contextService.setContext with correct parameters', async () => {
-      const data: ReturnUrlContext = { returnUrl: '/test-page' };
-      const scopeKey = 'process-123';
-
-      await service.preserveContext(data, scopeKey);
-
-      expect(contextServiceMock.setContext).toHaveBeenCalledWith(data, scopeKey);
-    });
-
-    it('should work without scope key', async () => {
-      const data: ReturnUrlContext = { returnUrl: '/test-page' };
-
-      await service.preserveContext(data);
-
-      expect(contextServiceMock.setContext).toHaveBeenCalledWith(data, undefined);
-    });
-  });
-
-  describe('restoreContext', () => {
-    it('should call contextService.getContext with correct parameters', async () => {
-      const expectedData: ReturnUrlContext = { returnUrl: '/test-page' };
-      contextServiceMock.getContext.mockResolvedValue(expectedData);
-
-      const result = await service.restoreContext<ReturnUrlContext>('scope-123');
-
-      expect(contextServiceMock.getContext).toHaveBeenCalledWith('scope-123');
-      expect(result).toEqual(expectedData);
-    });
-
-    it('should return null when context not found', async () => {
-      contextServiceMock.getContext.mockResolvedValue(null);
-
-      const result = await service.restoreContext();
-
-      expect(result).toBeNull();
-    });
-
-    it('should work without parameters', async () => {
-      const expectedData: ReturnUrlContext = { returnUrl: '/test-page' };
-      contextServiceMock.getContext.mockResolvedValue(expectedData);
-
-      const result = await service.restoreContext<ReturnUrlContext>();
-
-      expect(contextServiceMock.getContext).toHaveBeenCalledWith(undefined);
-      expect(result).toEqual(expectedData);
-    });
-  });
-
-  describe('restoreAndClearContext', () => {
-    it('should call contextService.getAndClearContext with correct parameters', async () => {
-      const expectedData: ReturnUrlContext = { returnUrl: '/test-page' };
-      contextServiceMock.getAndClearContext.mockResolvedValue(expectedData);
-
-      const result = await service.restoreAndClearContext<ReturnUrlContext>('scope-123');
-
-      expect(contextServiceMock.getAndClearContext).toHaveBeenCalledWith('scope-123');
-      expect(result).toEqual(expectedData);
-    });
-
-    it('should return null when context not found', async () => {
-      contextServiceMock.getAndClearContext.mockResolvedValue(null);
-
-      const result = await service.restoreAndClearContext();
-
-      expect(result).toBeNull();
-    });
-  });
-
-  describe('clearPreservedContext', () => {
-    it('should call contextService.clearContext and return result', async () => {
-      contextServiceMock.clearContext.mockResolvedValue(true);
-
-      const result = await service.clearPreservedContext('scope-123');
-
-      expect(contextServiceMock.clearContext).toHaveBeenCalledWith('scope-123');
-      expect(result).toBe(true);
-    });
-
-    it('should return false when context not found', async () => {
-      contextServiceMock.clearContext.mockResolvedValue(false);
-
-      const result = await service.clearPreservedContext();
-
-      expect(result).toBe(false);
-    });
-  });
-
-  describe('hasPreservedContext', () => {
-    it('should call contextService.hasContext and return result', async () => {
-      contextServiceMock.hasContext.mockResolvedValue(true);
-
-      const result = await service.hasPreservedContext('scope-123');
-
-      expect(contextServiceMock.hasContext).toHaveBeenCalledWith('scope-123');
-      expect(result).toBe(true);
-    });
-
-    it('should return false when context not found', async () => {
-      contextServiceMock.hasContext.mockResolvedValue(false);
-
-      const result = await service.hasPreservedContext();
-
-      expect(result).toBe(false);
-    });
-  });
-
-  describe('navigateWithPreservedContext', () => {
-    it('should preserve context and navigate', async () => {
-      const data: ReturnUrlContext = { returnUrl: '/reward/cart', customerId: 123 };
-      const commands = ['/customer/search'];
-      const scopeKey = 'process-123';
-
-      routerMock.navigate.mockResolvedValue(true);
-
-      const result = await service.navigateWithPreservedContext(commands, data, scopeKey);
-
-      expect(contextServiceMock.setContext).toHaveBeenCalledWith(data, scopeKey);
-      expect(routerMock.navigate).toHaveBeenCalledWith(commands, {
-        state: data,
-      });
-      expect(result).toEqual({ success: true });
-    });
-
-    it('should merge navigation extras', async () => {
-      const data: ReturnUrlContext = { returnUrl: '/test' };
-      const commands = ['/page'];
-      const extras = { queryParams: { foo: 'bar' } };
-
-      routerMock.navigate.mockResolvedValue(true);
-
-      await service.navigateWithPreservedContext(commands, data, undefined, extras);
-
-      expect(routerMock.navigate).toHaveBeenCalledWith(commands, {
-        queryParams: { foo: 'bar' },
-        state: data,
-      });
-    });
-
-    it('should return false when navigation fails', async () => {
-      const data: ReturnUrlContext = { returnUrl: '/test' };
-      const commands = ['/page'];
-
-      routerMock.navigate.mockResolvedValue(false);
-
-      const result = await service.navigateWithPreservedContext(commands, data);
-
-      expect(result).toEqual({ success: false });
-    });
-  });
-
-  describe('clearScopeContexts', () => {
-    it('should call contextService.clearScope and return count', async () => {
-      contextServiceMock.clearScope.mockResolvedValue(3);
-
-      const result = await service.clearScopeContexts();
-
-      expect(contextServiceMock.clearScope).toHaveBeenCalled();
-      expect(result).toBe(3);
-    });
-
-    it('should return 0 when no contexts cleared', async () => {
-      contextServiceMock.clearScope.mockResolvedValue(0);
-
-      const result = await service.clearScopeContexts();
-
-      expect(result).toBe(0);
-    });
-  });
-});

libs/core/navigation/src/lib/navigation-state.service.ts

@@ -1,331 +0,0 @@
-import { Injectable, inject } from '@angular/core';
-import { Router, NavigationExtras } from '@angular/router';
-import { NavigationContextService } from './navigation-context.service';
-import { NavigationContextData } from './navigation-context.types';
-
-/**
- * Service for managing navigation context preservation across multi-step flows.
- *
- * This service provides automatic context preservation using tab metadata,
- * allowing navigation state to survive intermediate navigations. Contexts are
- * automatically scoped to the active tab and cleaned up when the tab closes.
- *
- * ## Context Preservation for Multi-Step Flows
- *
- * @example
- * ```typescript
- * // Start of flow - preserve context (automatically scoped to active tab)
- * await navigationStateService.preserveContext({
- *   returnUrl: '/reward/cart',
- *   customerId: 123
- * });
- *
- * // ... multiple intermediate navigations happen ...
- * await router.navigate(['/customer/details']);
- * await router.navigate(['/add-shipping-address']);
- *
- * // End of flow - restore and cleanup (auto-scoped to active tab)
- * const context = await navigationStateService.restoreAndClearContext<{ returnUrl: string }>();
- * if (context?.returnUrl) {
- *   await router.navigateByUrl(context.returnUrl);
- * }
- * ```
- *
- * ## Simplified Navigation with Context
- *
- * @example
- * ```typescript
- * // Navigate and preserve context in one call
- * const { success } = await navigationStateService.navigateWithPreservedContext(
- *   ['/customer/search'],
- *   { returnUrl: '/reward/cart' }
- * );
- *
- * // Later, restore and navigate back
- * const context = await navigationStateService.restoreAndClearContext<{ returnUrl: string }>();
- * if (context?.returnUrl) {
- *   await router.navigateByUrl(context.returnUrl);
- * }
- * ```
- *
- * ## Automatic Tab Cleanup
- *
- * @example
- * ```typescript
- * ngOnDestroy() {
- *   // Clean up all contexts when tab closes (auto-uses active tab ID)
- *   this.navigationStateService.clearScopeContexts();
- * }
- * ```
- *
- * Key Features:
- * - ✅ Automatic tab scoping using TabService
- * - ✅ Stored in tab metadata (automatic cleanup when tab closes)
- * - ✅ Type-safe with TypeScript generics and Zod validation
- * - ✅ Automatic cleanup with restoreAndClearContext()
- * - ✅ Support for multiple custom scopes per tab
- * - ✅ No manual expiration management needed
- * - ✅ Platform-agnostic (works with SSR)
- */
-@Injectable({ providedIn: 'root' })
-export class NavigationStateService {
-  readonly #router = inject(Router);
-  readonly #contextService = inject(NavigationContextService);
-
-  // Context Preservation Methods
-
-  /**
-   * Preserve navigation state for multi-step flows.
-   *
-   * This method stores navigation context in tab metadata, allowing it to
-   * persist across intermediate navigations within a flow. Contexts are automatically
-   * scoped to the active tab, with optional custom scope for different flows.
-   *
-   * Use this when starting a flow that will have intermediate navigations
-   * before returning to the original location.
-   *
-   * @template T The type of state data being preserved
-   * @param state The navigation state to preserve
-   * @param customScope Optional custom scope within the tab (e.g., 'customer-details')
-   *
-   * @example
-   * ```typescript
-   * // Preserve context for default tab scope
-   * await navigationStateService.preserveContext({ returnUrl: '/products' });
-   *
-   * // Preserve context for custom scope within tab
-   * await navigationStateService.preserveContext({ customerId: 42 }, 'customer-details');
-   *
-   * // ... multiple intermediate navigations ...
-   *
-   * // Restore at end of flow
-   * const context = await navigationStateService.restoreContext<{ returnUrl: string }>();
-   * if (context?.returnUrl) {
-   *   await router.navigateByUrl(context.returnUrl);
-   * }
-   * ```
-   */
-  async preserveContext<T extends NavigationContextData>(
-    state: T,
-    customScope?: string,
-  ): Promise<void> {
-    await this.#contextService.setContext(state, customScope);
-  }
-
-  /**
-   * Patch preserved navigation state.
-   *
-   * Merges partial state with existing preserved context, keeping unspecified properties intact.
-   * This is useful when you need to update or clear specific properties without replacing
-   * the entire context. Properties set to `undefined` will be removed.
-   *
-   * Use cases:
-   * - Clear a trigger flag while preserving return URL
-   * - Update one property in a multi-property context
-   * - Remove specific properties from context
-   *
-   * @template T The type of state data being patched
-   * @param partialState The partial state to merge (properties set to undefined will be removed)
-   * @param customScope Optional custom scope within the tab
-   *
-   * @example
-   * ```typescript
-   * // Clear the autoTriggerContinueFn flag while preserving returnUrl
-   * await navigationStateService.patchContext(
-   *   { autoTriggerContinueFn: undefined },
-   *   'select-customer'
-   * );
-   *
-   * // Update selectedTab while keeping other properties
-   * await navigationStateService.patchContext(
-   *   { selectedTab: 'rewards' },
-   *   'customer-flow'
-   * );
-   *
-   * // Add a new property to existing context
-   * await navigationStateService.patchContext(
-   *   { shippingAddressId: 123 },
-   *   'checkout-flow'
-   * );
-   * ```
-   */
-  async patchContext<T extends NavigationContextData>(
-    partialState: Partial<T>,
-    customScope?: string,
-  ): Promise<void> {
-    await this.#contextService.patchContext(partialState, customScope);
-  }
-
-  /**
-   * Restore preserved navigation state.
-   *
-   * Retrieves a previously preserved navigation context for the active tab scope,
-   * or a custom scope if specified.
-   *
-   * This method does NOT remove the context - use clearPreservedContext() or
-   * restoreAndClearContext() for automatic cleanup.
-   *
-   * @template T The expected type of the preserved state
-   * @param customScope Optional custom scope (defaults to active tab scope)
-   * @returns The preserved state, or null if not found
-   *
-   * @example
-   * ```typescript
-   * // Restore from default tab scope
-   * const context = navigationStateService.restoreContext<{ returnUrl: string }>();
-   * if (context?.returnUrl) {
-   *   console.log('Returning to:', context.returnUrl);
-   * }
-   *
-   * // Restore from custom scope
-   * const context = navigationStateService.restoreContext<{ customerId: number }>('customer-details');
-   * ```
-   */
-  async restoreContext<T extends NavigationContextData = NavigationContextData>(
-    customScope?: string,
-  ): Promise<T | null> {
-    return await this.#contextService.getContext<T>(customScope);
-  }
-
-  /**
-   * Restore and automatically clear preserved navigation state.
-   *
-   * Retrieves a preserved navigation context and removes it from tab metadata in one operation.
-   * Use this when completing a flow to clean up automatically.
-   *
-   * @template T The expected type of the preserved state
-   * @param customScope Optional custom scope (defaults to active tab scope)
-   * @returns The preserved state, or null if not found
-   *
-   * @example
-   * ```typescript
-   * // Restore and clear from default tab scope
-   * const context = await navigationStateService.restoreAndClearContext<{ returnUrl: string }>();
-   * if (context?.returnUrl) {
-   *   await router.navigateByUrl(context.returnUrl);
-   * }
-   *
-   * // Restore and clear from custom scope
-   * const context = await navigationStateService.restoreAndClearContext<{ customerId: number }>('customer-details');
-   * ```
-   */
-  async restoreAndClearContext<
-    T extends NavigationContextData = NavigationContextData,
-  >(customScope?: string): Promise<T | null> {
-    return await this.#contextService.getAndClearContext<T>(customScope);
-  }
-
-  /**
-   * Clear a preserved navigation context.
-   *
-   * Removes a context from tab metadata without returning its data.
-   * Use this for explicit cleanup when you no longer need the preserved state.
-   *
-   * @param customScope Optional custom scope (defaults to active tab scope)
-   * @returns true if context was found and cleared, false otherwise
-   *
-   * @example
-   * ```typescript
-   * // Clear default tab scope context
-   * await navigationStateService.clearPreservedContext();
-   *
-   * // Clear custom scope context
-   * await navigationStateService.clearPreservedContext('customer-details');
-   * ```
-   */
-  async clearPreservedContext(customScope?: string): Promise<boolean> {
-    return await this.#contextService.clearContext(customScope);
-  }
-
-  /**
-   * Check if a preserved context exists.
-   *
-   * @param customScope Optional custom scope (defaults to active tab scope)
-   * @returns true if context exists, false otherwise
-   *
-   * @example
-   * ```typescript
-   * // Check default tab scope
-   * if (navigationStateService.hasPreservedContext()) {
-   *   const context = navigationStateService.restoreContext();
-   * }
-   *
-   * // Check custom scope
-   * if (navigationStateService.hasPreservedContext('customer-details')) {
-   *   const context = navigationStateService.restoreContext('customer-details');
-   * }
-   * ```
-   */
-  async hasPreservedContext(customScope?: string): Promise<boolean> {
-    return await this.#contextService.hasContext(customScope);
-  }
-
-  /**
-   * Navigate while preserving context state.
-   *
-   * Convenience method that combines navigation with context preservation.
-   * The context will be stored in tab metadata and available throughout the
-   * navigation flow and any intermediate navigations. Context is automatically
-   * scoped to the active tab.
-   *
-   * @param commands Navigation commands (same as Router.navigate)
-   * @param state The state to preserve
-   * @param customScope Optional custom scope within the tab
-   * @param extras Optional navigation extras
-   * @returns Promise resolving to navigation success status
-   *
-   * @example
-   * ```typescript
-   * // Navigate and preserve context
-   * const { success } = await navigationStateService.navigateWithPreservedContext(
-   *   ['/customer/search'],
-   *   { returnUrl: '/reward/cart', customerId: 123 }
-   * );
-   *
-   * // Later, retrieve and navigate back
-   * const context = await navigationStateService.restoreAndClearContext<{ returnUrl: string }>();
-   * if (context?.returnUrl) {
-   *   await router.navigateByUrl(context.returnUrl);
-   * }
-   * ```
-   */
-  async navigateWithPreservedContext<T extends NavigationContextData>(
-    commands: unknown[],
-    state: T,
-    customScope?: string,
-    extras?: NavigationExtras,
-  ): Promise<{ success: boolean }> {
-    await this.preserveContext(state, customScope);
-
-    // Also pass state via router for immediate access
-    const navigationExtras: NavigationExtras = {
-      ...extras,
-      state,
-    };
-
-    const success = await this.#router.navigate(commands, navigationExtras);
-
-    return { success };
-  }
-
-  /**
-   * Clear all preserved contexts for the active tab.
-   *
-   * Removes all contexts for the active tab (both default and custom scopes).
-   * Useful for cleanup when a tab is closed.
-   *
-   * @returns The number of contexts cleared
-   *
-   * @example
-   * ```typescript
-   * // Clear all contexts for active tab
-   * ngOnDestroy() {
-   *   const cleared = this.navigationStateService.clearScopeContexts();
-   *   console.log(`Cleared ${cleared} contexts`);
-   * }
-   * ```
-   */
-  async clearScopeContexts(): Promise<number> {
-    return await this.#contextService.clearScope();
-  }
-}

libs/core/navigation/src/lib/navigation-state.types.ts

@@ -1,23 +0,0 @@
-/**
- * Type definition for navigation state that can be passed through Angular Router.
- * Use generic type parameter to ensure type safety for your specific state shape.
- *
- * @example
- * ```typescript
- * interface MyNavigationState extends NavigationState {
- *   returnUrl: string;
- *   customerId: number;
- * }
- * ```
- */
-export interface NavigationState {
-  [key: string]: unknown;
-}
-
-/**
- * Common navigation state for "return URL" pattern.
- * Used when navigating to a page and needing to return to the previous location.
- */
-export interface ReturnUrlNavigationState extends NavigationState {
-  returnUrl: string;
-}

libs/core/navigation/src/test-setup.ts

@@ -1,13 +0,0 @@
-import '@angular/compiler';
-import '@analogjs/vitest-angular/setup-zone';
-
-import {
-  BrowserTestingModule,
-  platformBrowserTesting,
-} from '@angular/platform-browser/testing';
-import { getTestBed } from '@angular/core/testing';
-
-getTestBed().initTestEnvironment(
-  BrowserTestingModule,
-  platformBrowserTesting(),
-);

libs/core/navigation/tsconfig.json

@@ -1,30 +0,0 @@
-{
-  "extends": "../../../tsconfig.base.json",
-  "compilerOptions": {
-    "importHelpers": true,
-    "moduleResolution": "bundler",
-    "strict": true,
-    "noImplicitOverride": true,
-    "noPropertyAccessFromIndexSignature": true,
-    "noImplicitReturns": true,
-    "noFallthroughCasesInSwitch": true,
-    "module": "preserve"
-  },
-  "angularCompilerOptions": {
-    "enableI18nLegacyMessageIdFormat": false,
-    "strictInjectionParameters": true,
-    "strictInputAccessModifiers": true,
-    "typeCheckHostBindings": true,
-    "strictTemplates": true
-  },
-  "files": [],
-  "include": [],
-  "references": [
-    {
-      "path": "./tsconfig.lib.json"
-    },
-    {
-      "path": "./tsconfig.spec.json"
-    }
-  ]
-}

libs/core/navigation/tsconfig.lib.json

@@ -1,27 +0,0 @@
-{
-  "extends": "./tsconfig.json",
-  "compilerOptions": {
-    "outDir": "../../../dist/out-tsc",
-    "declaration": true,
-    "declarationMap": true,
-    "inlineSources": true,
-    "types": []
-  },
-  "exclude": [
-    "src/**/*.spec.ts",
-    "src/test-setup.ts",
-    "jest.config.ts",
-    "src/**/*.test.ts",
-    "vite.config.ts",
-    "vite.config.mts",
-    "vitest.config.ts",
-    "vitest.config.mts",
-    "src/**/*.test.tsx",
-    "src/**/*.spec.tsx",
-    "src/**/*.test.js",
-    "src/**/*.spec.js",
-    "src/**/*.test.jsx",
-    "src/**/*.spec.jsx"
-  ],
-  "include": ["src/**/*.ts"]
-}

libs/core/navigation/tsconfig.spec.json

@@ -1,29 +0,0 @@
-{
-  "extends": "./tsconfig.json",
-  "compilerOptions": {
-    "outDir": "../../../dist/out-tsc",
-    "types": [
-      "vitest/globals",
-      "vitest/importMeta",
-      "vite/client",
-      "node",
-      "vitest"
-    ]
-  },
-  "include": [
-    "vite.config.ts",
-    "vite.config.mts",
-    "vitest.config.ts",
-    "vitest.config.mts",
-    "src/**/*.test.ts",
-    "src/**/*.spec.ts",
-    "src/**/*.test.tsx",
-    "src/**/*.spec.tsx",
-    "src/**/*.test.js",
-    "src/**/*.spec.js",
-    "src/**/*.test.jsx",
-    "src/**/*.spec.jsx",
-    "src/**/*.d.ts"
-  ],
-  "files": ["src/test-setup.ts"]
-}

libs/core/navigation/vite.config.mts

@@ -1,33 +0,0 @@
-/// <reference types='vitest' />
-import { defineConfig } from 'vite';
-import angular from '@analogjs/vite-plugin-angular';
-import { nxViteTsPaths } from '@nx/vite/plugins/nx-tsconfig-paths.plugin';
-import { nxCopyAssetsPlugin } from '@nx/vite/plugins/nx-copy-assets.plugin';
-
-export default
-// @ts-expect-error - Vitest reporter tuple types have complex inference issues, but config works correctly at runtime
-defineConfig(() => ({
-  root: __dirname,
-  cacheDir: '../../../node_modules/.vite/libs/core/navigation',
-  plugins: [angular(), nxViteTsPaths(), nxCopyAssetsPlugin(['*.md'])],
-  // Uncomment this if you are using workers.
-  // worker: {
-  //  plugins: [ nxViteTsPaths() ],
-  // },
-  test: {
-    watch: false,
-    globals: true,
-    environment: 'jsdom',
-    include: ['{src,tests}/**/*.{test,spec}.{js,mjs,cjs,ts,mts,cts,jsx,tsx}'],
-    setupFiles: ['src/test-setup.ts'],
-    reporters: [
-      'default',
-      ['junit', { outputFile: '../../../testresults/junit-core-navigation.xml' }],
-    ],
-    coverage: {
-      reportsDirectory: '../../../coverage/libs/core/navigation',
-      provider: 'v8' as const,
-      reporter: ['text', 'cobertura'],
-    },
-  },
-}));

libs/core/tabs/src/lib/tab.injector.ts

@@ -34,10 +34,14 @@ export function injectTabId() {
  * If the current tab ID is a reserved process ID, generates a new ID using Date.now().
  */
 function getNavigableTabId(
-  activeTabId: number | null,
+  activeTabId: number | null | undefined,
   reservedIds: Set<number>,
 ): number {
-  if (activeTabId === null || reservedIds.has(activeTabId)) {
+  if (
+    activeTabId === undefined ||
+    activeTabId === null ||
+    reservedIds.has(activeTabId)
+  ) {
     return Date.now();
   }
   return activeTabId;

libs/crm/data-access/src/lib/resources/customer-bon-check.resource.ts

@@ -2,6 +2,7 @@ import { Injectable, inject, resource, signal, computed } from '@angular/core';
 import { logger } from '@isa/core/logging';
 import { CustomerBonRedemptionFacade } from '../facades/customer-bon-redemption.facade';
 import { LoyaltyBonResponse } from '@generated/swagger/crm-api';
+import { ResponseArgsError } from '@isa/common/data-access';
 
 /**
  * Resource for checking/validating Bon numbers.
@@ -47,8 +48,24 @@ export class CustomerBonCheckResource {
       this.#logger.debug('Bon checked', () => ({
         bonNr,
         found: !!response?.result,
+        hasInvalidProperties:
+          !!response?.invalidProperties &&
+          Object.keys(response.invalidProperties).length > 0,
       }));
 
+      // Check for invalidProperties even when error is false
+      // Backend may return { error: false, invalidProperties: {...} } for validation issues
+      if (
+        response?.invalidProperties &&
+        Object.keys(response.invalidProperties).length > 0
+      ) {
+        this.#logger.warn('Bon check has invalid properties', () => ({
+          bonNr,
+          invalidProperties: response.invalidProperties,
+        }));
+        throw new ResponseArgsError(response);
+      }
+
       return response?.result;
     },
     defaultValue: undefined,

libs/crm/data-access/src/lib/services/crm-search.service.ts

@@ -224,15 +224,10 @@ export class CrmSearchService {
       req$ = req$.pipe(takeUntilAborted(abortSignal));
     }
 
-    try {
-      const res = await firstValueFrom(req$);
-      this.#logger.debug('Successfully fetched current booking partner store');
+    const res = await firstValueFrom(req$);
+    this.#logger.debug('Successfully fetched current booking partner store');
 
-      return res?.result;
-    } catch (error) {
-      this.#logger.error('Error fetching current booking partner store', error);
-      return undefined;
-    }
+    return res?.result;
   }
 
   async addBooking(

libs/crm/feature/customer-bon-redemption/src/lib/crm-feature-customer-bon-redemption/components/bon-details-display/bon-details-display.component.html

@@ -8,13 +8,15 @@
     aria-label="Bon Details"
   >
     <div class="flex justify-between items-center py-1">
-      <span class="isa-text-body-2-regular text-isa-neutral-600">Bon Datum</span>
+      <span class="isa-text-body-2-regular text-isa-neutral-600"
+        >Bon Datum</span
+      >
       <span
         class="isa-text-body-2-bold text-isa-black"
         data-what="bon-date"
         [attr.data-which]="bon.bonNumber"
       >
-        {{ bon.date }}
+        {{ bon.date | date: 'dd.MM.yyyy' }}
       </span>
     </div>
 

libs/crm/feature/customer-bon-redemption/src/lib/crm-feature-customer-bon-redemption/crm-feature-customer-bon-redemption.component.ts

@@ -114,12 +114,7 @@ export class CrmFeatureCustomerBonRedemptionComponent {
       }
       // Handle API errors
       else if (error) {
-        let errorMsg = 'Bon-Validierung fehlgeschlagen';
-        if (error instanceof ResponseArgsError) {
-          errorMsg = error.message || errorMsg;
-        } else if (error instanceof Error) {
-          errorMsg = error.message;
-        }
+        const errorMsg = this.#extractErrorMessage(error);
         this.store.setError(errorMsg);
       }
     });
@@ -224,4 +219,23 @@ export class CrmFeatureCustomerBonRedemptionComponent {
     this.store.reset();
     this.#bonCheckResource.reset();
   }
+
+  /**
+   * Extract error message from various error types.
+   * ResponseArgsError already formats invalidProperties into a readable message.
+   */
+  #extractErrorMessage(error: unknown): string {
+    const defaultMsg = 'Bon-Validierung fehlgeschlagen';
+    const actualError = (error as { cause?: unknown })?.cause ?? error;
+
+    if (actualError instanceof ResponseArgsError) {
+      return actualError.message || defaultMsg;
+    }
+
+    if (actualError instanceof Error) {
+      return actualError.message || defaultMsg;
+    }
+
+    return defaultMsg;
+  }
 }

libs/crm/feature/customer-loyalty-cards/src/lib/components/customer-card-points-summary/customer-card-points-summary.component.spec.ts

@@ -51,7 +51,7 @@ describe('CustomerCardPointsSummaryComponent', () => {
   });
 
   describe('formattedPoints computed signal', () => {
-    it('should display points from primary card', () => {
+    it('should display points from first card', () => {
       fixture.componentRef.setInput('cards', mockCards);
       fixture.detectChanges();
 
@@ -77,7 +77,7 @@ describe('CustomerCardPointsSummaryComponent', () => {
       expect(component.formattedPoints()).toBe('123.456');
     });
 
-    it('should display 0 when no primary card exists', () => {
+    it('should display points from first card regardless of isPrimary flag', () => {
       const cardsWithoutPrimary: BonusCardInfo[] = [
         {
           code: 'CARD-1',
@@ -93,7 +93,7 @@ describe('CustomerCardPointsSummaryComponent', () => {
       fixture.componentRef.setInput('cards', cardsWithoutPrimary);
       fixture.detectChanges();
 
-      expect(component.formattedPoints()).toBe('0');
+      expect(component.formattedPoints()).toBe('1.500');
     });
 
     it('should display 0 when cards array is empty', () => {
@@ -122,14 +122,14 @@ describe('CustomerCardPointsSummaryComponent', () => {
       expect(component.formattedPoints()).toBe('0');
     });
 
-    it('should only use primary card points, not sum of all cards', () => {
+    it('should only use first card points, not sum of all cards', () => {
       const multipleCards: BonusCardInfo[] = [
         {
           code: 'CARD-1',
           firstName: 'John',
           lastName: 'Doe',
           isActive: true,
-          isPrimary: true,
+          isPrimary: false,
           totalPoints: 1000,
           cardNumber: '1234-5678-9012-3456',
         } as BonusCardInfo,
@@ -138,7 +138,7 @@ describe('CustomerCardPointsSummaryComponent', () => {
           firstName: 'John',
           lastName: 'Doe',
           isActive: true,
-          isPrimary: false,
+          isPrimary: true,
           totalPoints: 500,
           cardNumber: '9876-5432-1098-7654',
         } as BonusCardInfo,
@@ -147,7 +147,7 @@ describe('CustomerCardPointsSummaryComponent', () => {
       fixture.componentRef.setInput('cards', multipleCards);
       fixture.detectChanges();
 
-      // Should be 1000, not 1500
+      // Should be 1000 (first card), not 500 (primary) or 1500 (sum)
       expect(component.formattedPoints()).toBe('1.000');
     });
   });

libs/crm/feature/customer-loyalty-cards/src/lib/components/customer-card-points-summary/customer-card-points-summary.component.ts

@@ -36,12 +36,11 @@ export class CustomerCardPointsSummaryComponent {
   readonly navigateToPraemienshop = output<void>();
 
   /**
-   * Total points from primary card, formatted with thousands separator.
+   * Total points from first card, formatted with thousands separator.
    */
   readonly formattedPoints = computed(() => {
     const cards = this.cards();
-    const primaryCard = cards.find((c) => c.isPrimary);
-    const points = primaryCard?.totalPoints ?? 0;
+    const points = cards?.[0]?.totalPoints ?? 0;
 
     // Format with German thousands separator (dot)
     return points.toLocaleString('de-DE');

libs/oms/data-access/src/lib/helpers/return-process/index.ts

@@ -10,6 +10,7 @@ export * from './get-receipt-item-quantity.helper';
 export * from './get-return-info.helper';
 export * from './get-return-process-questions.helper';
 export * from './get-tolino-questions.helper';
+export * from './is-task-type.helper';
 export * from './receipt-item-has-category.helper';
 export * from './return-details-mapping.helper';
 export * from './return-receipt-values-mapping.helper';

libs/oms/data-access/src/lib/helpers/return-process/is-task-type.helper.spec.ts

@@ -0,0 +1,88 @@
+import { TaskActionTypes } from '../../models';
+import { isTaskType } from './is-task-type.helper';
+
+describe('isTaskType', () => {
+  describe('OK type matching', () => {
+    it('should return true when comparing OK with OK', () => {
+      expect(isTaskType('OK', TaskActionTypes.OK)).toBe(true);
+    });
+
+    it('should return true when comparing RETOURE_OK with OK', () => {
+      expect(isTaskType('RETOURE_OK', TaskActionTypes.OK)).toBe(true);
+    });
+
+    it('should return true when comparing OK with RETOURE_OK', () => {
+      expect(isTaskType('OK', TaskActionTypes.RETOURE_OK)).toBe(true);
+    });
+
+    it('should return true when comparing RETOURE_OK with RETOURE_OK', () => {
+      expect(isTaskType('RETOURE_OK', TaskActionTypes.RETOURE_OK)).toBe(true);
+    });
+  });
+
+  describe('NOK type matching', () => {
+    it('should return true when comparing NOK with NOK', () => {
+      expect(isTaskType('NOK', TaskActionTypes.NOK)).toBe(true);
+    });
+
+    it('should return true when comparing RETOURE_NOK with NOK', () => {
+      expect(isTaskType('RETOURE_NOK', TaskActionTypes.NOK)).toBe(true);
+    });
+
+    it('should return true when comparing NOK with RETOURE_NOK', () => {
+      expect(isTaskType('NOK', TaskActionTypes.RETOURE_NOK)).toBe(true);
+    });
+
+    it('should return true when comparing RETOURE_NOK with RETOURE_NOK', () => {
+      expect(isTaskType('RETOURE_NOK', TaskActionTypes.RETOURE_NOK)).toBe(true);
+    });
+  });
+
+  describe('UNKNOWN type matching', () => {
+    it('should return true when comparing UNKNOWN with UNKNOWN', () => {
+      expect(isTaskType('UNKNOWN', TaskActionTypes.UNKNOWN)).toBe(true);
+    });
+
+    it('should return true when comparing RETOURE_UNKNOWN with UNKNOWN', () => {
+      expect(isTaskType('RETOURE_UNKNOWN', TaskActionTypes.UNKNOWN)).toBe(true);
+    });
+
+    it('should return true when comparing UNKNOWN with RETOURE_UNKNOWN', () => {
+      expect(isTaskType('UNKNOWN', TaskActionTypes.RETOURE_UNKNOWN)).toBe(true);
+    });
+
+    it('should return true when comparing RETOURE_UNKNOWN with RETOURE_UNKNOWN', () => {
+      expect(
+        isTaskType('RETOURE_UNKNOWN', TaskActionTypes.RETOURE_UNKNOWN),
+      ).toBe(true);
+    });
+  });
+
+  describe('non-matching types', () => {
+    it('should return false when comparing OK with NOK', () => {
+      expect(isTaskType('OK', TaskActionTypes.NOK)).toBe(false);
+    });
+
+    it('should return false when comparing RETOURE_OK with UNKNOWN', () => {
+      expect(isTaskType('RETOURE_OK', TaskActionTypes.UNKNOWN)).toBe(false);
+    });
+
+    it('should return false when comparing NOK with OK', () => {
+      expect(isTaskType('NOK', TaskActionTypes.OK)).toBe(false);
+    });
+  });
+
+  describe('falsy values', () => {
+    it('should return false when value is undefined', () => {
+      expect(isTaskType(undefined, TaskActionTypes.OK)).toBe(false);
+    });
+
+    it('should return false when value is null', () => {
+      expect(isTaskType(null, TaskActionTypes.OK)).toBe(false);
+    });
+
+    it('should return false when value is empty string', () => {
+      expect(isTaskType('', TaskActionTypes.OK)).toBe(false);
+    });
+  });
+});

libs/oms/data-access/src/lib/helpers/return-process/is-task-type.helper.ts

@@ -0,0 +1,34 @@
+import { TaskActionTypeType } from '../../models';
+
+/**
+ * Checks if a task action type value matches a given type, including its RETOURE_ variant.
+ *
+ * This helper normalizes both values by stripping the 'RETOURE_' prefix before comparison,
+ * allowing flexible matching between base types and their return variants.
+ *
+ * @param value - The task action type value to check (can be a base type or RETOURE_ variant)
+ * @param type - The task action type to compare against (can be a base type or RETOURE_ variant)
+ * @returns `true` if the normalized values match, `false` otherwise
+ *
+ * @example
+ * // All of these return true:
+ * isTaskType('OK', TaskActionTypes.OK)              // 'OK' === 'OK'
+ * isTaskType('RETOURE_OK', TaskActionTypes.OK)      // 'OK' === 'OK'
+ * isTaskType('OK', TaskActionTypes.RETOURE_OK)      // 'OK' === 'OK'
+ * isTaskType('RETOURE_OK', TaskActionTypes.RETOURE_OK) // 'OK' === 'OK'
+ *
+ * @example
+ * // Returns false:
+ * isTaskType('OK', TaskActionTypes.NOK)             // 'OK' !== 'NOK'
+ * isTaskType('RETOURE_OK', TaskActionTypes.UNKNOWN) // 'OK' !== 'UNKNOWN'
+ * isTaskType(undefined, TaskActionTypes.OK)         // value is falsy
+ */
+export const isTaskType = (
+  value: TaskActionTypeType | string | undefined | null,
+  type: TaskActionTypeType,
+): boolean => {
+  if (!value) return false;
+  const normalizedValue = value.replace('RETOURE_', '');
+  const normalizedType = type.replace('RETOURE_', '');
+  return normalizedValue === normalizedType;
+};

libs/oms/data-access/src/lib/models/task-action-type.ts

@@ -2,8 +2,11 @@ import { KeyValueDTOOfStringAndString } from '@generated/swagger/oms-api';
 
 export const TaskActionTypes = {
   OK: 'OK',
+  RETOURE_OK: 'RETOURE_OK',
   NOK: 'NOK',
+  RETOURE_NOK: 'RETOURE_NOK',
   UNKNOWN: 'UNKNOWN',
+  RETOURE_UNKNOWN: 'RETOURE_UNKNOWN',
 } as const;
 
 export type TaskActionTypeType =
@@ -13,6 +16,6 @@ export interface TaskActionType {
   type: TaskActionTypeType;
   taskId: number;
   receiptItemId?: number;
-  updateTo?: Exclude<TaskActionTypeType, 'UNKNOWN'>;
+  updateTo?: Exclude<TaskActionTypeType, 'UNKNOWN' | 'RETOURE_UNKNOWN'>;
   actions?: Array<KeyValueDTOOfStringAndString>;
 }

libs/oms/data-access/src/lib/services/return-task-list.service.ts

@@ -1,6 +1,11 @@
 import { inject, Injectable } from '@angular/core';
 import { map, Observable, throwError } from 'rxjs';
-import { ReceiptItemTaskListItem, TaskActionTypeType } from '../models';
+import {
+  ReceiptItemTaskListItem,
+  TaskActionTypes,
+  TaskActionTypeType,
+} from '../models';
+import { isTaskType } from '../helpers';
 import { QueryTokenInput, QueryTokenSchema } from '../schemas';
 import { ZodError } from 'zod';
 import { ReturnParseQueryTokenError } from '../errors';
@@ -98,7 +103,7 @@ export class ReturnTaskListService {
    * @throws Error when the update operation fails or returns an error
    */
   updateTaskType(updateTask: {
-    type: Exclude<TaskActionTypeType, 'UNKNOWN'>;
+    type: Exclude<TaskActionTypeType, 'UNKNOWN' | 'RETOURE_UNKNOWN'>;
     taskId: number;
   }) {
     try {
@@ -127,18 +132,18 @@ export class ReturnTaskListService {
    * @private
    */
   private _updateTaskRequestHelper(updateTask: {
-    type: Exclude<TaskActionTypeType, 'UNKNOWN'>;
+    type: Exclude<TaskActionTypeType, 'UNKNOWN' | 'RETOURE_UNKNOWN'>;
     taskId: number;
   }): Observable<ResponseArgsOfReceiptItemTaskListItemDTO> {
     if (!updateTask?.taskId) {
       return throwError(() => new Error('Task ID missing'));
     }
 
-    if (updateTask.type === 'OK') {
+    if (isTaskType(updateTask.type, TaskActionTypes.OK)) {
       return this.#receiptService.ReceiptSetReceiptItemTaskToOK(
         updateTask.taskId,
       );
-    } else if (updateTask.type === 'NOK') {
+    } else if (isTaskType(updateTask.type, TaskActionTypes.NOK)) {
       return this.#receiptService.ReceiptSetReceiptItemTaskToNOK(
         updateTask.taskId,
       );

libs/oms/feature/return-details/src/lib/return-details-order-group-item-controls/return-details-order-group-item-controls.component.html

@@ -5,8 +5,8 @@
     <ui-dropdown
       class="quantity-dropdown"
       [disabled]="!canReturnReceiptItem()"
-      [value]="selectedQuantity()"
-      (valueChange)="setQuantity($event)"
+      [ngModel]="selectedQuantity()"
+      (ngModelChange)="setQuantity($event)"
     >
       @for (quantity of quantityDropdownValues(); track quantity) {
         <ui-dropdown-option [value]="quantity">{{
@@ -17,11 +17,11 @@
   }
 
   <ui-dropdown
-    label="Produktart"
+    [label]="dropdownLabel()"
     class="product-dropdown"
     [disabled]="!canReturnReceiptItem()"
-    [value]="productCategory()"
-    (valueChange)="setProductCategory($event)"
+    [ngModel]="productCategory()"
+    (ngModelChange)="setProductCategory($event)"
   >
     @for (kv of availableCategories; track kv.key) {
       <ui-dropdown-option [value]="kv.key">{{ kv.value }}</ui-dropdown-option>
@@ -31,7 +31,7 @@
 
 @if (canReturnReceiptItem()) {
   @if (!canReturnResource.isLoading() && selectable()) {
-    <ui-checkbox appearance="bullet">
+    <ui-checkbox class="min-w-12" appearance="bullet">
       <input
         type="checkbox"
         [ngModel]="selected()"

libs/oms/feature/return-details/src/lib/return-details-order-group-item-controls/return-details-order-group-item-controls.component.ts

@@ -5,27 +5,27 @@ import {
   inject,
   input,
   signal,
-} from "@angular/core";
-import { provideLoggerContext } from "@isa/core/logging";
+} from '@angular/core';
+import { provideLoggerContext } from '@isa/core/logging';
 import {
   canReturnReceiptItem,
   ProductCategory,
   ReceiptItem,
   ReturnDetailsService,
   ReturnDetailsStore,
-} from "@isa/oms/data-access";
-import { IconButtonComponent } from "@isa/ui/buttons";
+} from '@isa/oms/data-access';
+import { IconButtonComponent } from '@isa/ui/buttons';
 import {
   CheckboxComponent,
   DropdownButtonComponent,
   DropdownOptionComponent,
-} from "@isa/ui/input-controls";
-import { FormsModule } from "@angular/forms";
+} from '@isa/ui/input-controls';
+import { FormsModule } from '@angular/forms';
 
 @Component({
-  selector: "oms-feature-return-details-order-group-item-controls",
-  templateUrl: "./return-details-order-group-item-controls.component.html",
-  styleUrls: ["./return-details-order-group-item-controls.component.scss"],
+  selector: 'oms-feature-return-details-order-group-item-controls',
+  templateUrl: './return-details-order-group-item-controls.component.html',
+  styleUrls: ['./return-details-order-group-item-controls.component.scss'],
   changeDetection: ChangeDetectionStrategy.OnPush,
   standalone: true,
   imports: [
@@ -37,7 +37,7 @@ import { FormsModule } from "@angular/forms";
   ],
   providers: [
     provideLoggerContext({
-      component: "ReturnDetailsOrderGroupItemControlsComponent",
+      component: 'ReturnDetailsOrderGroupItemControlsComponent',
     }),
   ],
 })
@@ -89,6 +89,13 @@ export class ReturnDetailsOrderGroupItemControlsComponent {
 
   canReturnReceiptItem = computed(() => canReturnReceiptItem(this.item()));
 
+  dropdownLabel = computed(() => {
+    const category = this.productCategory();
+    return !!category && category !== ProductCategory.Unknown
+      ? category
+      : 'Produktart';
+  });
+
   setProductCategory(category: ProductCategory | undefined) {
     if (!category) {
       category = ProductCategory.Unknown;

libs/oms/feature/return-details/src/lib/return-details-order-group-item/return-details-order-group-item.component.html

@@ -57,21 +57,25 @@
   </div>
   <div class="text-isa-neutral-900 flex flex-col gap-2" uiItemRowProdcutInfo>
     <div class="flex flex-row gap-2 items-center justify-start">
-      <ng-icon [name]="i.product.format | lowercase"></ng-icon>
+      @if (!!i?.product?.format) {
+        <ng-icon [name]="i.product.format | lowercase"></ng-icon>
+      }
       <span class="isa-text-body-2-bold truncate">
-        {{ i.product.formatDetail }}
+        {{ i?.product?.formatDetail }}
       </span>
     </div>
     <div
       class="text-isa-neutral-600 isa-text-body-2-regular"
       data-what="product-info"
-      [attr.data-which]="i.product.ean"
+      [attr.data-which]="i?.product?.ean"
     >
-      {{ i.product.manufacturer }} | {{ i.product.ean }}
-    </div>
-    <div class="text-isa-neutral-600 isa-text-body-2-regular">
-      {{ i.product.publicationDate | date: 'dd. MMM yyyy' }}
+      {{ i?.product?.manufacturer }} | {{ i?.product?.ean }}
     </div>
+    @if (!!i?.product?.publicationDate) {
+      <div class="text-isa-neutral-600 isa-text-body-2-regular">
+        {{ i.product.publicationDate | date: 'dd. MMM yyyy' }}
+      </div>
+    }
   </div>
   <oms-feature-return-details-order-group-item-controls [item]="i">
   </oms-feature-return-details-order-group-item-controls>

libs/oms/shared/task-list/src/lib/return-task-list/return-task-list-item/return-task-list-item.component.html

@@ -8,7 +8,7 @@
 @let taskItem = item();
 @let taskActionType = type();
 
-@if (taskActionType === 'UNKNOWN') {
+@if (isTaskType(taskActionType, TaskActionTypes.UNKNOWN)) {
   <div
     data-what="task-list"
     data-which="processing-comment"
@@ -51,14 +51,21 @@
   </div>
 }
 
-@if (taskActionType === 'UNKNOWN' && !taskItem?.completed) {
+@if (
+  isTaskType(taskActionType, TaskActionTypes.UNKNOWN) && !taskItem?.completed
+) {
   <div class="task-unknown-actions">
     <button
       class="flex items-center"
       type="button"
       uiButton
       color="secondary"
-      (click)="onActionClick({ type: taskActionType, updateTo: 'OK' })"
+      (click)="
+        onActionClick({
+          type: taskActionType,
+          updateTo: TaskActionTypes.RETOURE_OK,
+        })
+      "
       data-what="button"
       data-which="resellable"
     >
@@ -69,7 +76,12 @@
       type="button"
       uiButton
       color="secondary"
-      (click)="onActionClick({ type: taskActionType, updateTo: 'NOK' })"
+      (click)="
+        onActionClick({
+          type: taskActionType,
+          updateTo: TaskActionTypes.RETOURE_NOK,
+        })
+      "
       data-what="button"
       data-which="damaged"
     >

libs/oms/shared/task-list/src/lib/return-task-list/return-task-list-item/return-task-list-item.component.ts

@@ -9,9 +9,11 @@ import {
 } from '@angular/core';
 import { isaActionCheck, isaActionPrinter } from '@isa/icons';
 import {
+  isTaskType,
   Product,
   ReceiptItemTaskListItem,
   TaskActionType,
+  TaskActionTypes,
   TaskActionTypeType,
 } from '@isa/oms/data-access';
 import { ReturnProductInfoComponent } from '@isa/oms/shared/product-info';
@@ -37,6 +39,8 @@ import { NgIconComponent, provideIcons } from '@ng-icons/core';
   encapsulation: ViewEncapsulation.None,
 })
 export class ReturnTaskListItemComponent {
+  readonly TaskActionTypes = TaskActionTypes;
+  readonly isTaskType = isTaskType;
   appearance = input<'main' | 'review'>('main');
   item = input.required<ReceiptItemTaskListItem>();
   action = output<TaskActionType>();

libs/oms/shared/task-list/src/lib/return-task-list/return-task-list.component.ts

@@ -10,12 +10,13 @@ import {
 } from '@angular/core';
 import { ReturnTaskListItemComponent } from './return-task-list-item/return-task-list-item.component';
 import {
+  isTaskType,
   PrintTolinoReturnReceiptService,
   QueryTokenInput,
-  ReceiptItemTaskListItem,
   ReturnTaskListService,
   ReturnTaskListStore,
   TaskActionType,
+  TaskActionTypes,
   TaskActionTypeType,
 } from '@isa/oms/data-access';
 import { IconButtonComponent } from '@isa/ui/buttons';
@@ -86,7 +87,9 @@ export class ReturnTaskListComponent {
       const appearance = this.appearance();
       if (processId) {
         const filter: Record<string, unknown> =
-          appearance === 'review' ? { eob: true } : { completed: false };
+          appearance === 'review'
+            ? { eob: true, tasktype: '!retoure_loyalty' }
+            : { completed: false, tasktype: '!retoure_loyalty' };
         const queryToken: QueryTokenInput = {
           filter,
         };
@@ -113,7 +116,7 @@ export class ReturnTaskListComponent {
       );
     }
 
-    if (action.type === 'UNKNOWN' && !!action.updateTo) {
+    if (isTaskType(action.type, TaskActionTypes.UNKNOWN) && !!action.updateTo) {
       return await this.updateTask({
         taskId: action.taskId,
         updateTo: action.updateTo,
@@ -149,7 +152,7 @@ export class ReturnTaskListComponent {
     updateTo,
   }: {
     taskId: number;
-    updateTo: Exclude<TaskActionTypeType, 'UNKNOWN'>;
+    updateTo: Exclude<TaskActionTypeType, 'UNKNOWN' | 'RETOURE_UNKNOWN'>;
   }) {
     try {
       const processId = this.processId();

libs/remission/feature/remission-return-receipt-details/src/lib/remission-return-receipt-details.component.html

@@ -63,6 +63,18 @@
     }
   </div>
 }
+
+<button
+  type="button"
+  uiButton
+  color="tertiary"
+  size="large"
+  (click)="abortRemission()"
+  class="fixed right-[15rem] bottom-6"
+>
+  Warenbegleitschein abbrechen
+</button>
+
 @if (!returnLoading() && !returnData()?.completed) {
   <lib-remission-return-receipt-complete
     [returnId]="returnId()"

libs/remission/feature/remission-return-receipt-details/src/lib/remission-return-receipt-details.component.ts

@@ -17,6 +17,7 @@ import {
   getPackageNumbersFromReturn,
   getReceiptItemsFromReturn,
   getReceiptNumberFromReturn,
+  RemissionStore,
 } from '@isa/remission/data-access';
 import { EmptyStateComponent } from '@isa/ui/empty-state';
 import { EMPTY_WBS_DESCRIPTION, EMPTY_WBS_TITLE } from './constants';
@@ -24,6 +25,8 @@ import {
   RemissionReturnReceiptActionsComponent,
   RemissionReturnReceiptCompleteComponent,
 } from '@isa/remission/shared/return-receipt-actions';
+import { Router } from '@angular/router';
+import { injectTabId } from '@isa/core/tabs';
 
 @Component({
   selector: 'remi-remission-return-receipt-details',
@@ -53,6 +56,15 @@ export class RemissionReturnReceiptDetailsComponent {
   /** Angular Location service for navigation */
   location = inject(Location);
 
+  /** Remission store for managing remission state */
+  #store = inject(RemissionStore);
+
+  /** Angular Router for navigation */
+  #router = inject(Router);
+
+  /** Injects the current activated tab ID as a signal. */
+  #tabId = injectTabId();
+
   /**
    * Required input for the return ID.
    * Automatically coerced to a number from string input.
@@ -111,4 +123,9 @@ export class RemissionReturnReceiptDetailsComponent {
     const returnData = this.returnData();
     return getPackageNumbersFromReturn(returnData!) !== '';
   });
+
+  async abortRemission() {
+    this.#store.clearState();
+    await this.#router.navigate(['/', this.#tabId(), 'remission']);
+  }
 }

libs/shared/filter/src/lib/controls-panel/controls-panel.component.html

@@ -12,7 +12,7 @@
     ></filter-search-bar-input>
   }
 
-  <div class="flex flex-row gap-4 items-center">
+  <div class="flex flex-row gap-4 items-center flex-wrap justify-end">
     <ng-content></ng-content>
 
     @for (switchFilter of switchFilters(); track switchFilter.filter.key) {

libs/shared/filter/src/lib/inputs/checkbox-input/checkbox-input.component.scss

@@ -1,3 +1,3 @@
 .filter-checkbox-input {
-  @apply inline-block w-full p-6 text-isa-neutral-900;
+  @apply inline-block w-full p-6 text-isa-neutral-900 overflow-scroll max-h-96;
 }

libs/shared/filter/src/lib/menus/filter-menu/filter-menu-button.component.html

@@ -20,11 +20,13 @@
   cdkConnectedOverlay
   [cdkConnectedOverlayOrigin]="trigger"
   [cdkConnectedOverlayOpen]="open()"
+  [cdkConnectedOverlayPositions]="overlayPositions"
   [cdkConnectedOverlayHasBackdrop]="true"
   cdkConnectedOverlayBackdropClass="cdk-overlay-transparent-backdrop"
   [cdkConnectedOverlayScrollStrategy]="scrollStrategy"
-  [cdkConnectedOverlayOffsetX]="-10"
-  [cdkConnectedOverlayOffsetY]="18"
+  [cdkConnectedOverlayFlexibleDimensions]="true"
+  [cdkConnectedOverlayGrowAfterOpen]="true"
+  [cdkConnectedOverlayPush]="true"
   cdkConnectedOverlayWidth="18.375rem"
   (backdropClick)="toggle()"
 >

libs/shared/filter/src/lib/menus/filter-menu/filter-menu-button.component.ts

@@ -2,13 +2,13 @@ import { Overlay, OverlayModule } from '@angular/cdk/overlay';
 import {
   ChangeDetectionStrategy,
   Component,
-  computed,
   inject,
   input,
   model,
   output,
 } from '@angular/core';
 import { IconButtonComponent } from '@isa/ui/buttons';
+import { DROPDOWN_OVERLAY_POSITIONS } from '@isa/ui/layout';
 import { FilterMenuComponent } from './filter-menu.component';
 import { FilterService } from '../../core';
 
@@ -30,6 +30,9 @@ export class FilterMenuButtonComponent {
 
   selectedFilters = this.#filter.selectedFilterCount;
 
+  /** Standard overlay positions for the filter menu panel */
+  readonly overlayPositions = DROPDOWN_OVERLAY_POSITIONS;
+
   /**
    * Tracks the open state of the filter menu.
    */

libs/shared/filter/src/lib/menus/filter-menu/filter-menu.component.html

@@ -45,10 +45,7 @@
     <span> {{ input!.label }} </span>
   </button>
 
-  <filter-input-renderer
-    class="overflow-scroll"
-    [filterInput]="input!"
-  ></filter-input-renderer>
+  <filter-input-renderer [filterInput]="input!"></filter-input-renderer>
 }
 
 <filter-actions

libs/shared/filter/src/lib/menus/filter-menu/filter-menu.component.scss

@@ -2,6 +2,6 @@
   @apply inline-flex flex-col;
   @apply bg-isa-white;
   @apply rounded-[1.25rem];
-  @apply min-w-[14.3125rem] max-w-[18.375rem] max-h-[33.5rem];
+  @apply min-w-[14.3125rem] max-w-[18.375rem];
   @apply shadow-overlay;
 }

libs/shared/filter/src/lib/menus/input-menu/input-menu.component.html

@@ -1,7 +1,4 @@
-<filter-input-renderer
-  class="overflow-scroll"
-  [filterInput]="filterInput()"
-></filter-input-renderer>
+<filter-input-renderer [filterInput]="filterInput()"></filter-input-renderer>
 <filter-actions
   [inputKey]="filterInput().key"
   [canApply]="canApply()"

libs/shared/filter/src/lib/menus/input-menu/input-menu.component.scss

@@ -1,4 +1,4 @@
 :host {
   @apply inline-flex flex-col;
-  @apply shadow-overlay bg-isa-white rounded-[1.25rem] max-h-[32.3rem];
+  @apply shadow-overlay bg-isa-white rounded-[1.25rem];
 }

libs/shared/filter/src/lib/order-by/order-by-toolbar.component.html

@@ -15,6 +15,8 @@
       </div>
       @if (orderBy.currentDir) {
         <ng-icon [name]="orderBy.currentDir" size="1.25rem"></ng-icon>
+      } @else {
+        <div class="w-5 h-5"></div>
       }
     </button>
   }

libs/shared/filter/src/lib/order-by/order-by-toolbar.component.scss

@@ -1,3 +1,7 @@
 :host {
   @apply inline-flex flex-col;
 }
+
+.ui-toolbar {
+  @apply gap-0;
+}

libs/shell/common/README.md

@@ -83,6 +83,37 @@ type FontSize = 'small' | 'medium' | 'large';
 // Maps to: 14px | 16px | 18px
 ```
 
+### TabsCollapsedService
+
+Controls the collapsed/expanded state of the shell tabs bar.
+
+```typescript
+import { TabsCollapsedService } from '@isa/shell/common';
+
+@Component({...})
+export class MyComponent {
+  tabsCollapsed = inject(TabsCollapsedService);
+
+  // Read state (readonly signal)
+  isCollapsed = this.tabsCollapsed.get;
+
+  // Toggle collapsed state
+  toggleTabs() {
+    this.tabsCollapsed.toggle();
+  }
+
+  // Set specific state
+  expandTabs() {
+    this.tabsCollapsed.set(false);
+  }
+}
+```
+
+**API:**
+- `get` - Readonly signal of collapsed state (`boolean`)
+- `toggle()` - Toggles collapsed/expanded state
+- `set(state: boolean)` - Sets collapsed state (no-op if already equal)
+
 ### NotificationsService
 
 Manages application notifications with read status tracking.
@@ -177,6 +208,7 @@ import {
   NavigationService,
   FontSizeService,
   FontSize,
+  TabsCollapsedService,
   NotificationsService,
   Notification
 } from '@isa/shell/common';
@@ -195,7 +227,8 @@ npx nx test shell-common
 
 ## Related Libraries
 
-- [`@isa/shell/header`](../header) - Uses all services
-- [`@isa/shell/layout`](../layout) - Uses NavigationService
+- [`@isa/shell/header`](../header) - Uses NavigationService, FontSizeService, NotificationsService
+- [`@isa/shell/layout`](../layout) - Uses NavigationService, FontSizeService, TabsCollabsedService
+- [`@isa/shell/tabs`](../tabs) - Uses TabsCollabsedService
 - [`@isa/shell/notifications`](../notifications) - Uses NotificationsService
 - [`@isa/shell/navigation`](../navigation) - Uses NavigationService

libs/shell/common/src/index.ts

@@ -1,3 +1,4 @@
 export * from './lib/navigation.service';
 export * from './lib/font-size.service';
 export * from './lib/notifications.service';
+export * from './lib/tabs-collapsed.service';

libs/shell/common/src/lib/font-size.service.ts

@@ -9,14 +9,40 @@ import {
 } from '@angular/core';
 import { logger } from '@isa/core/logging';
 
+/** Available font size options for the application. */
 export type FontSize = 'small' | 'medium' | 'large';
 
+/** Mapping of font size names to pixel values. */
 const FONT_SIZE_PX_MAP: Record<FontSize, number> = {
   small: 14,
   medium: 16,
   large: 18,
 };
 
+/**
+ * Service for managing application-wide font size.
+ *
+ * Provides reactive font size state with automatic DOM updates.
+ * The font size is applied to the document root element, enabling
+ * rem-based scaling throughout the application.
+ *
+ * @example
+ * ```typescript
+ * readonly fontSizeService = inject(FontSizeService);
+ *
+ * // Get current font size
+ * const size = this.fontSizeService.get(); // 'small' | 'medium' | 'large'
+ *
+ * // Get pixel value
+ * const px = this.fontSizeService.getPx(); // 14 | 16 | 18
+ *
+ * // Set font size
+ * this.fontSizeService.set('large');
+ *
+ * // Convert rem to pixels
+ * const pixels = this.fontSizeService.remToPx(2); // 32 (when medium)
+ * ```
+ */
 @Injectable({ providedIn: 'root' })
 export class FontSizeService {
   #logger = logger({ service: 'FontSizeService' });
@@ -26,17 +52,29 @@ export class FontSizeService {
 
   #renderer = inject(RendererFactory2).createRenderer(this.#document, null);
 
+  /** Readonly signal exposing the current font size name. */
   readonly get = this.#state.asReadonly();
 
+  /** Computed signal returning the current font size in pixels. */
   readonly getPx = computed(() => FONT_SIZE_PX_MAP[this.#state()]);
 
+  /**
+   * Sets the application font size.
+   * @param size - The font size to apply ('small', 'medium', or 'large')
+   */
   set(size: FontSize): void {
     this.#logger.debug('Font size changed', () => ({ size }));
     this.#state.set(size);
   }
 
+  /**
+   * Converts rem units to pixels based on current font size.
+   * @param rem - The value in rem units
+   * @returns The equivalent value in pixels
+   */
   readonly remToPx = (rem: number) => rem * this.getPx();
 
+  /** Effect that applies the font size to the document root element. */
   readonly fontSizeEffect = effect(() => {
     const fontSize = this.#state();
     this.#renderer.setStyle(

libs/shell/common/src/lib/navigation.service.ts

@@ -1,18 +1,45 @@
 import { Injectable, signal } from '@angular/core';
 import { logger } from '@isa/core/logging';
 
+/**
+ * Service for managing the navigation sidebar visibility state.
+ *
+ * Controls whether the sidebar navigation panel is open or closed,
+ * primarily used for responsive mobile/tablet layouts where the
+ * navigation can be toggled via a hamburger menu.
+ *
+ * @example
+ * ```typescript
+ * readonly navigationService = inject(NavigationService);
+ *
+ * // Check if navigation is open
+ * const isOpen = this.navigationService.get();
+ *
+ * // Toggle navigation
+ * this.navigationService.toggle();
+ *
+ * // Explicitly set state
+ * this.navigationService.set(false); // Close navigation
+ * ```
+ */
 @Injectable({ providedIn: 'root' })
 export class NavigationService {
   #logger = logger({ service: 'NavigationService' });
   #state = signal<boolean>(false);
 
+  /** Readonly signal exposing the current navigation open/closed state. */
   readonly get = this.#state.asReadonly();
 
+  /** Toggles the navigation state between open and closed. */
   toggle(): void {
     this.#state.update((state) => !state);
     this.#logger.debug('Navigation toggled', () => ({ isOpen: this.#state() }));
   }
 
+  /**
+   * Sets the navigation visibility state.
+   * @param state - True to open navigation, false to close
+   */
   set(state: boolean): void {
     this.#logger.debug('Navigation state set', () => ({ state }));
     this.#state.set(state);

libs/shell/common/src/lib/notifications.service.ts

@@ -1,47 +1,103 @@
 import { computed, Injectable, signal } from '@angular/core';
 import { logger } from '@isa/core/logging';
 
+/** Unix timestamp in milliseconds. */
 type Timestamp = number;
 
+/** Unique identifier for a notification. */
 type NotificationId = string | number;
 
+/**
+ * Represents an in-app notification.
+ *
+ * Notifications are displayed in the notifications panel and can be
+ * grouped, marked as read, and trigger actions when clicked.
+ */
 export type Notification = {
+  /** Unique identifier for this notification. */
   id: NotificationId;
+  /** Group name for categorizing notifications (e.g., 'orders', 'system'). */
   group: string;
+  /** Short title displayed prominently. */
   title: string;
+  /** Detailed message content. */
   message: string;
+  /** Action to perform when notification is clicked. */
   action: NotificationAction;
+  /** Timestamp when marked as read (undefined if unread). */
   markedAsRead?: Timestamp;
+  /** Creation timestamp for sorting. */
   timestamp: Timestamp;
 };
 
+/** Base properties for notification actions. */
 export type NotificationActionBase = {
+  /** Button label text. */
   label: string;
+  /** Action type discriminator. */
   type: 'navigate' | 'callback';
 };
 
+/** Navigation action that routes to an internal or external URL. */
 export type NotificationActionNavigate = NotificationActionBase & {
   type: 'navigate';
+  /** Whether the route is internal (Angular router) or external (new tab). */
   target: 'internal' | 'external';
+  /** The route path or URL to navigate to. */
   route: string;
 };
 
+/** Callback action that executes a function. */
 export type NotificationActionCallback = NotificationActionBase & {
   type: 'callback';
+  /** Function to execute when action is triggered. */
   callback: () => void;
 };
 
+/** Union type for all notification action types. */
 export type NotificationAction =
   | NotificationActionNavigate
   | NotificationActionCallback;
 
+/**
+ * Service for managing in-app notifications.
+ *
+ * Provides a centralized store for notifications with support for
+ * adding, removing, grouping, and tracking read/unread state.
+ *
+ * @example
+ * ```typescript
+ * readonly notifications = inject(NotificationsService);
+ *
+ * // Add a notification
+ * this.notifications.add({
+ *   id: 'order-123',
+ *   group: 'orders',
+ *   title: 'New Order',
+ *   message: 'Order #123 has been placed',
+ *   timestamp: Date.now(),
+ *   action: { type: 'navigate', target: 'internal', route: '/orders/123', label: 'View' }
+ * });
+ *
+ * // Get unread count
+ * const unread = this.notifications.unreadCount();
+ *
+ * // Mark as read
+ * this.notifications.markAsRead('order-123');
+ * ```
+ */
 @Injectable({ providedIn: 'root' })
 export class NotificationsService {
   #logger = logger({ service: 'NotificationsService' });
   #state = signal<Notification[]>([]);
 
+  /** Readonly signal exposing all current notifications. */
   readonly get = this.#state.asReadonly();
 
+  /**
+   * Adds a new notification to the store.
+   * @param notification - The notification to add
+   */
   add(notification: Notification): void {
     this.#logger.debug('Notification added', () => ({
       id: notification.id,
@@ -50,6 +106,10 @@ export class NotificationsService {
     this.#state.update((notifications) => [...notifications, notification]);
   }
 
+  /**
+   * Removes a notification by its ID.
+   * @param id - The notification ID to remove
+   */
   remove(id: NotificationId): void {
     this.#logger.debug('Notification removed', () => ({ id }));
     this.#state.update((notifications) =>
@@ -57,11 +117,16 @@ export class NotificationsService {
     );
   }
 
+  /** Removes all notifications from the store. */
   clear(): void {
     this.#logger.debug('All notifications cleared');
     this.#state.set([]);
   }
 
+  /**
+   * Marks a specific notification as read.
+   * @param id - The notification ID to mark as read
+   */
   markAsRead(id: NotificationId): void {
     this.#logger.debug('Notification marked as read', () => ({ id }));
     this.#state.update((notifications) =>
@@ -73,6 +138,7 @@ export class NotificationsService {
     );
   }
 
+  /** Marks all notifications as read. */
   markAllAsRead(): void {
     this.#logger.debug('All notifications marked as read');
     this.#state.update((notifications) =>
@@ -83,6 +149,7 @@ export class NotificationsService {
     );
   }
 
+  /** Computed signal returning the count of unread notifications. */
   readonly unreadCount = computed(() =>
     this.#state().filter((notification) => !notification.markedAsRead).length,
   );

libs/shell/common/src/lib/tabs-collapsed.service.ts

@@ -0,0 +1,53 @@
+import { Injectable, signal } from '@angular/core';
+import { logger } from '@isa/core/logging';
+
+/**
+ * Service for managing the collapsed/expanded state of the shell tabs bar.
+ *
+ * The tabs bar can switch between compact (collapsed) and expanded modes
+ * based on user proximity. This service provides a centralized state
+ * that can be accessed by both the tabs component and the shell layout.
+ *
+ * @example
+ * ```typescript
+ * readonly tabsCollapsed = inject(TabsCollapsedService);
+ *
+ * // Read current state
+ * const isCollapsed = this.tabsCollapsed.get();
+ *
+ * // Set state
+ * this.tabsCollapsed.set(true);
+ *
+ * // Toggle state
+ * this.tabsCollapsed.toggle();
+ * ```
+ */
+@Injectable({ providedIn: 'root' })
+export class TabsCollapsedService {
+  #logger = logger({ service: 'TabsService' });
+  #state = signal<boolean>(false);
+
+  /** Readonly signal exposing the current collapsed state. */
+  readonly get = this.#state.asReadonly();
+
+  /** Toggles the collapsed state between true and false. */
+  toggle(): void {
+    this.#state.update((state) => !state);
+    this.#logger.debug('Tabs toggled', () => ({ isOpen: this.#state() }));
+  }
+
+  /**
+   * Sets the collapsed state to a specific value.
+   * No-op if the state is already equal to the provided value.
+   *
+   * @param state - The new collapsed state (true = collapsed, false = expanded)
+   */
+  set(state: boolean): void {
+    if (this.#state() === state) {
+      return;
+    }
+
+    this.#logger.debug('Tabs state set', () => ({ state }));
+    this.#state.set(state);
+  }
+}

libs/shell/header/src/lib/components/font-size-selector/font-size-selector.component.ts

@@ -10,12 +10,28 @@ import { NgIcon, provideIcons } from '@ng-icons/core';
 import { isaNavigationFontsize } from '@isa/icons';
 import { FontSize, FontSizeService } from '@isa/shell/common';
 
+/** Configuration for a font size option in the selector. */
 interface FontSizeOption {
+  /** The font size value ('small', 'medium', 'large'). */
   value: FontSize;
+  /** Accessible label for screen readers. */
   label: string;
+  /** Icon size for visual representation. */
   iconSize: string;
 }
 
+/**
+ * Font size selector component for accessibility settings.
+ *
+ * Displays three font size options (small, medium, large) with visual
+ * icons indicating the relative size. Includes an animated indicator
+ * that slides to show the currently selected option.
+ *
+ * @example
+ * ```html
+ * <shell-font-size-selector />
+ * ```
+ */
 @Component({
   selector: 'shell-font-size-selector',
   templateUrl: './font-size-selector.component.html',
@@ -31,24 +47,32 @@ interface FontSizeOption {
 export class ShellFontSizeSelectorComponent {
   #logger = logger({ component: 'ShellFontSizeSelectorComponent' });
 
+  /** Font size service for reading and updating the current size. */
   readonly fontSizeService = inject(FontSizeService);
 
+  /** Available font size options with labels and icon sizes. */
   readonly fontSizeOptions: FontSizeOption[] = [
     { value: 'small', label: 'Kleine Schriftgröße', iconSize: '0.63rem' },
     { value: 'medium', label: 'Mittlere Schriftgröße', iconSize: '1rem' },
     { value: 'large', label: 'Große Schriftgröße', iconSize: '1.3rem' },
   ];
 
+  /** Pixel offsets for the sliding indicator animation. */
   readonly #offsetMap: Record<FontSize, number> = {
     small: 0,
     medium: 3,
     large: 6,
   };
 
+  /** Computed offset position for the sliding indicator. */
   readonly indicatorOffset = computed(
     () => this.#offsetMap[this.fontSizeService.get()],
   );
 
+  /**
+   * Handles font size selection changes.
+   * @param size - The newly selected font size
+   */
   onFontSizeChange(size: FontSize): void {
     this.#logger.debug('Font size changed', () => ({ size }));
     this.fontSizeService.set(size);

libs/shell/header/src/lib/components/logout-button.component.ts

@@ -5,6 +5,17 @@ import { AuthService } from '@isa/core/auth';
 import { NgIcon, provideIcons } from '@ng-icons/core';
 import { isaNavigationLogout } from '@isa/icons';
 
+/**
+ * Logout button component for the header.
+ *
+ * Displays a logout icon button that triggers user logout when clicked.
+ * Includes "NEU" label to indicate the new shell interface.
+ *
+ * @example
+ * ```html
+ * <shell-logout-button />
+ * ```
+ */
 @Component({
   selector: 'shell-logout-button',
   template: `<ui-info-button
@@ -24,6 +35,7 @@ export class ShellLogoutButtonComponent {
   #logger = logger({ component: 'ShellLogoutButtonComponent' });
   #authService = inject(AuthService);
 
+  /** Logs out the current user via the AuthService. */
   logout(): void {
     this.#logger.info('User logging out');
     this.#authService.logout();

libs/shell/header/src/lib/components/navigation-toggle.component.ts

@@ -14,6 +14,17 @@ import {
 } from '@isa/ui/buttons';
 import { provideIcons } from '@ng-icons/core';
 
+/**
+ * Navigation toggle button (hamburger menu) for tablet/mobile layouts.
+ *
+ * Toggles the sidebar navigation visibility. The icon changes between
+ * a hamburger menu icon (closed) and close icon (open) based on state.
+ *
+ * @example
+ * ```html
+ * <shell-navigation-toggle />
+ * ```
+ */
 @Component({
   selector: 'shell-navigation-toggle',
   template: `<ui-icon-button
@@ -33,20 +44,24 @@ import { provideIcons } from '@ng-icons/core';
 export class ShellNavigationToggleComponent {
   #logger = logger({ component: 'ShellNavigationToggleComponent' });
 
+  /** Navigation service for controlling sidebar visibility. */
   readonly navigationService = inject(NavigationService);
 
   readonly IconButtonColor = IconButtonColor;
   readonly IconButtonSize = IconButtonSize;
 
+  /** Computed icon name based on navigation state. */
   iconName = computed(() => {
     const open = this.navigationService.get();
     return open ? 'isaActionClose' : 'isaNavigationSidemenu';
   });
 
+  /** Computed ARIA label for accessibility. */
   ariaLabel = computed(() =>
     this.navigationService.get() ? 'Menü schließen' : 'Menü öffnen',
   );
 
+  /** Toggles the navigation sidebar visibility. */
   toggle(): void {
     this.navigationService.toggle();
     this.#logger.debug('Navigation toggled', () => ({

libs/shell/header/src/lib/components/notifications-toggle/notifications-toggle.component.ts

@@ -17,6 +17,18 @@ import {
 import { NotificationsService } from '@isa/shell/common';
 import { ShellNotificationsComponent } from '@isa/shell/notifications';
 
+/**
+ * Notifications toggle button with dropdown panel.
+ *
+ * Displays a bell icon that shows unread indicator when there are
+ * unread notifications. Clicking opens an overlay panel with the
+ * full notifications list.
+ *
+ * @example
+ * ```html
+ * <shell-notifications-toggle />
+ * ```
+ */
 @Component({
   selector: 'shell-notifications-toggle',
   templateUrl: './notifications-toggle.component.html',
@@ -33,10 +45,13 @@ export class ShellNotificationsToggleComponent {
   readonly IconButtonColor = IconButtonColor;
   readonly IconButtonSize = IconButtonSize;
 
+  /** Notifications service for accessing notification state. */
   readonly notificationsService = inject(NotificationsService);
 
+  /** Whether the notifications panel overlay is currently open. */
   isOpen = signal(false);
 
+  /** CDK overlay positions for the notifications panel. */
   readonly positions: ConnectedPosition[] = [
     // Bottom right
     { originX: 'end', originY: 'bottom', overlayX: 'end', overlayY: 'top' },
@@ -48,6 +63,7 @@ export class ShellNotificationsToggleComponent {
     { originX: 'start', originY: 'bottom', overlayX: 'end', overlayY: 'bottom' },
   ];
 
+  /** Toggles the notifications panel visibility. */
   toggle(): void {
     this.isOpen.update((open) => !open);
     this.#logger.debug('Notifications panel toggled', () => ({
@@ -55,23 +71,28 @@ export class ShellNotificationsToggleComponent {
     }));
   }
 
+  /** Closes the notifications panel. */
   close(): void {
     this.isOpen.set(false);
     this.#logger.debug('Notifications panel closed');
   }
 
+  /** Whether there are any notifications. */
   hasNotifications = computed(() => this.notificationsService.get().length > 0);
 
+  /** Whether there are unread notifications. */
   unreadNotifications = computed(
     () => this.notificationsService.unreadCount() > 0,
   );
 
+  /** Icon name based on unread notification state. */
   icon = computed(() =>
     this.unreadNotifications()
       ? 'isaNavigationMessageUnread'
       : 'isaNavigationMessage',
   );
 
+  /** ARIA label for accessibility based on current state. */
   ariaLabel = computed(() => {
     if (!this.hasNotifications()) return 'Keine Benachrichtigungen';
     return this.isOpen() ? 'Benachrichtigungen schließen' : 'Benachrichtigungen öffnen';

libs/shell/header/src/lib/shell-header.component.ts

@@ -5,6 +5,22 @@ import { ShellFontSizeSelectorComponent } from './components/font-size-selector/
 import { ShellLogoutButtonComponent } from './components/logout-button.component';
 import { ShellNotificationsToggleComponent } from './components/notifications-toggle/notifications-toggle.component';
 
+/**
+ * Application header component for the shell layout.
+ *
+ * Displays the main header bar with:
+ * - Navigation toggle (hamburger menu on tablet/mobile)
+ * - Font size selector for accessibility
+ * - Notifications toggle with unread indicator
+ * - Logout button
+ *
+ * The navigation toggle is only visible on tablet breakpoint and below.
+ *
+ * @example
+ * ```html
+ * <shell-header />
+ * ```
+ */
 @Component({
   selector: 'shell-header',
   templateUrl: './shell-header.component.html',
@@ -18,5 +34,6 @@ import { ShellNotificationsToggleComponent } from './components/notifications-to
   ],
 })
 export class ShellHeaderComponent {
+  /** Signal indicating if the viewport is at or below tablet breakpoint. */
   readonly isTablet = breakpoint(Breakpoint.Tablet);
 }

libs/shell/layout/README.md

@@ -6,13 +6,17 @@
 
 ## Overview
 
-Root layout component for the application shell. Provides the main structural wrapper including network status banner and header.
+Root layout component for the application shell. Provides the main structural wrapper including network status banner, header with tabs, navigation sidebar, and content projection.
 
 ## Features
 
 - Network status banner with offline/online state transitions
-- Header integration via `@isa/shell/header`
-- Content projection for main page content
+- Header integration with tabs bar
+- Collapsible sidebar navigation
+- Responsive layout with tablet/mobile breakpoint handling
+- Dynamic positioning based on header and navigation sizes
+- Click-outside-to-close navigation on mobile
+- Font size scaling support
 
 ## Installation
 
@@ -47,12 +51,22 @@ Root layout wrapper that structures the application shell.
 **Template Structure:**
 ```html
 <shell-network-status-banner />
-<shell-header />
+<header>
+  <shell-header />
+  <shell-tabs />
+</header>
+<shell-navigation />
 <main>
   <ng-content></ng-content>
 </main>
 ```
 
+**Features:**
+- Responsive navigation visibility (auto-hide on tablet breakpoint)
+- Click-outside-to-close behavior for mobile navigation
+- Dynamic positioning based on header and navigation sizes
+- Scroll-to-close navigation on mobile
+
 ### NetworkStatusBannerComponent
 
 **Selector:** `shell-network-status-banner`
@@ -67,17 +81,48 @@ Displays connectivity status banners for network state changes.
 **Exported Constants:**
 - `ONLINE_BANNER_DISPLAY_DURATION_MS` - Banner display duration (2500ms)
 
+## Layout Structure
+
+```
+┌──────────────────────────────────────────────┐
+│  Network Status Banner (conditional)          │
+├──────────────────────────────────────────────┤
+│  Header                                       │
+│  ┌────────────────────────────────────────┐  │
+│  │  Shell Header (logo, actions)          │  │
+│  ├────────────────────────────────────────┤  │
+│  │  Shell Tabs (tab carousel)             │  │
+│  └────────────────────────────────────────┘  │
+├─────────┬────────────────────────────────────┤
+│ Nav     │  Main Content                      │
+│ Sidebar │  <ng-content>                      │
+│         │                                    │
+│         │                                    │
+└─────────┴────────────────────────────────────┘
+```
+
+## Responsive Behavior
+
+| Viewport | Navigation | Tabs |
+|----------|------------|------|
+| Desktop | Always visible sidebar | Full tabs |
+| Tablet/Mobile | Toggle via hamburger menu | Compact mode |
+
 ## Accessibility
 
 - Uses `text-isa-neutral-900` host class for proper contrast
 - Network status banner announces connectivity changes
+- Semantic `<header>` and `<main>` landmarks
 
 ## Dependencies
 
 **Internal:**
 - `@isa/shell/header` - Header component
+- `@isa/shell/navigation` - Navigation sidebar
+- `@isa/shell/tabs` - Tabs carousel
+- `@isa/shell/common` - NavigationService, FontSizeService, TabsCollabsedService
 - `@isa/core/connectivity` - Network status service
-- `@isa/core/logging` - Logger factory
+- `@isa/ui/layout` - Breakpoint utilities, UiElementSizeObserverDirective
 
 ## Testing
 
@@ -88,4 +133,7 @@ npx nx test shell-layout
 ## Related Libraries
 
 - [`@isa/shell/header`](../header) - Header component
+- [`@isa/shell/navigation`](../navigation) - Navigation sidebar
+- [`@isa/shell/tabs`](../tabs) - Tabs carousel
+- [`@isa/shell/common`](../common) - Shared shell services
 - [`@isa/core/connectivity`](../../core/connectivity) - Network status service

libs/shell/layout/src/lib/shell-layout.component.css

@@ -4,24 +4,37 @@
 
 header {
   @apply fixed flex flex-col gap-2 top-0 inset-x-0 z-fixed bg-isa-white;
+  transition: all 0.3s ease;
+}
+
+main {
+  transition: margin-top 0.3s ease;
+}
+
+shell-navigation {
+  transition: top 0.3s ease;
 }
 
 shell-navigation {
   @apply fixed bottom-4 left-0 z-fixed;
 }
 
-/* Slide animation for navigation - tablet only */
-@media (max-width: 1023px) {
+shell-navigation {
+  transform: translateX(-100%);
+}
+
+shell-navigation.nav-visible {
+  animation: slideInFromLeft 0.3s ease-out forwards;
+}
+
+shell-navigation.nav-hidden {
+  animation: slideOutToLeft 0.3s ease-in forwards;
+}
+
+@screen desktop-small {
   shell-navigation {
-    transform: translateX(-100%);
-  }
-
-  shell-navigation.nav-visible {
-    animation: slideInFromLeft 0.3s ease-out forwards;
-  }
-
-  shell-navigation.nav-hidden {
-    animation: slideOutToLeft 0.3s ease-in forwards;
+    transform: translateX(0);
+    animation: none;
   }
 }
 

libs/shell/layout/src/lib/shell-layout.component.html

@@ -1,23 +1,34 @@
 <shell-network-status-banner />
 
-<header #headerSizeObserver="uiElementSizeObserver" uiElementSizeObserver>
+<header
+  class="bg-isa-white"
+  [class.h-[6.125rem]]="tabsCollapsed.get()"
+  [class.h-[8rem]]="!tabsCollapsed.get()"
+  uiElementSizeObserver
+  #headerSizeObserver="uiElementSizeObserver"
+>
   <shell-header />
   <shell-tabs class="px-4" />
 </header>
 
 <shell-navigation
+  [style.top.px]="headerSizeObserver.size().height + fontSizeService.getPx()"
   [class.nav-visible]="renderNavigation() && tablet()"
   [class.nav-hidden]="!renderNavigation() && tablet()"
-  [style.top.px]="headerSizeObserver.size().height + fontSizeService.getPx() * 1.5"
-  #navigationSizeObserver="uiElementSizeObserver"
   uiElementSizeObserver
+  #navigationSizeObserver="uiElementSizeObserver"
 />
 
 <main
   [style.marginTop.px]="
-    headerSizeObserver.size().height + fontSizeService.getPx() * 1.5
+    headerSizeObserver.size().height + fontSizeService.getPx()
   "
-  [style.marginLeft.px]="mainMarginLeft()"
+  [style.margin-left.px]="
+    tablet()
+      ? '0'
+      : navigationSizeObserver.size().width + fontSizeService.getPx()
+  "
+  (scroll)="onMainScroll()"
 >
   <ng-content></ng-content>
 </main>

libs/shell/layout/src/lib/shell-layout.component.ts

@@ -2,11 +2,17 @@ import {
   ChangeDetectionStrategy,
   Component,
   computed,
+  ElementRef,
+  HostListener,
   inject,
-  viewChild,
 } from '@angular/core';
+import { logger } from '@isa/core/logging';
 import { NetworkStatusBannerComponent } from './components/network-status-banner.component';
-import { NavigationService, FontSizeService } from '@isa/shell/common';
+import {
+  NavigationService,
+  FontSizeService,
+  TabsCollapsedService,
+} from '@isa/shell/common';
 import { ShellHeaderComponent } from '@isa/shell/header';
 import { ShellNavigationComponent } from '@isa/shell/navigation';
 import { ShellTabsComponent } from '@isa/shell/tabs';
@@ -16,7 +22,23 @@ import {
   UiElementSizeObserverDirective,
 } from '@isa/ui/layout';
 
-
+/**
+ * Root layout component for the application shell.
+ *
+ * Composes the header, navigation, tabs, and main content area into a
+ * responsive layout. Handles:
+ * - Responsive navigation visibility (auto-hide on tablet breakpoint)
+ * - Click-outside-to-close behavior for mobile navigation
+ * - Dynamic positioning based on header and navigation sizes
+ * - Font size scaling for accessibility
+ *
+ * @example
+ * ```html
+ * <shell-layout>
+ *   <router-outlet />
+ * </shell-layout>
+ * ```
+ */
 @Component({
   selector: 'shell-layout',
   standalone: true,
@@ -29,18 +51,26 @@ import {
     ShellNavigationComponent,
     ShellTabsComponent,
     UiElementSizeObserverDirective,
-  ]
+  ],
 })
 export class ShellLayoutComponent {
+  #logger = logger({ component: 'ShellLayoutComponent' });
   #navigationService = inject(NavigationService);
+  #elementRef = inject(ElementRef);
 
+  /** Service for managing tabs collapsed state. */
+  readonly tabsCollapsed = inject(TabsCollapsedService);
+
+  /** Service for managing font size scaling. */
   readonly fontSizeService = inject(FontSizeService);
 
+  /** Signal indicating if the viewport is at or below tablet breakpoint. */
   readonly tablet = breakpoint(Breakpoint.Tablet);
 
-  private readonly navigationSizeObserverRef =
-    viewChild<UiElementSizeObserverDirective>('navigationSizeObserver');
-
+  /**
+   * Computed signal determining if navigation should be rendered.
+   * Always visible on desktop; toggled visibility on tablet/mobile.
+   */
   readonly renderNavigation = computed(() => {
     const tablet = this.tablet();
 
@@ -51,18 +81,29 @@ export class ShellLayoutComponent {
     return this.#navigationService.get();
   });
 
-  readonly mainMarginLeft = computed(() => {
-    // On tablet, navigation overlaps content (no margin)
-    if (this.tablet()) {
-      return 0;
-    }
+  /**
+   * Handles clicks outside the navigation to close it on tablet/mobile.
+   * Ignores clicks on the navigation toggle button.
+   */
+  @HostListener('document:click', ['$event'])
+  onDocumentClick(event: MouseEvent): void {
+    if (!this.tablet() || !this.#navigationService.get()) return;
 
-    // On desktop, add margin to account for navigation width
-    const navSize = this.navigationSizeObserverRef()?.size();
-    if (navSize) {
-      return navSize.width + this.fontSizeService.getPx() * 1.5;
-    }
+    const target = event.target as HTMLElement;
+    const nav = this.#elementRef.nativeElement.querySelector('shell-navigation');
+    const toggleBtn = target.closest('[data-which="navigation-toggle"]');
 
-    return 0;
-  });
+    if (toggleBtn) return;
+
+    if (nav && !nav.contains(target)) {
+      this.#navigationService.set(false);
+    }
+  }
+
+  /** Closes navigation on main content scroll (tablet/mobile only). */
+  onMainScroll(): void {
+    if (!this.tablet() || !this.#navigationService.get()) return;
+    this.#logger.debug('Closing navigation on scroll');
+    this.#navigationService.set(false);
+  }
 }

libs/shell/navigation/src/lib/components/navigation-group/navigation-group.component.html

@@ -1,4 +1,10 @@
-<div class="flex flex-col h-14 items-start self-stretch px-4">
+<div
+  class="flex flex-col h-14 items-start self-stretch px-4"
+  data-what="navigation-group"
+  [attr.data-which]="group().label"
+  role="group"
+  [attr.aria-label]="group().label"
+>
   <div
     class="isa-text-caption-caps flex h-6 flex-col justify-center flex-[1_0_0] self-stretch"
   >

libs/shell/navigation/src/lib/components/navigation-group/navigation-group.component.ts

@@ -2,6 +2,17 @@ import { ChangeDetectionStrategy, Component, input } from '@angular/core';
 import { NavigationGroup } from '../../types';
 import { ShellNavigationItemComponent } from '../navigation-item/navigation-item.component';
 
+/**
+ * Navigation group component that renders a labeled section with navigation items.
+ *
+ * Groups navigation items under a common label (e.g., "Kunden", "Filiale").
+ * Each group displays its label as a header followed by its child items.
+ *
+ * @example
+ * ```html
+ * <shell-navigation-group [group]="navigationGroup" />
+ * ```
+ */
 @Component({
   selector: 'shell-navigation-group',
   templateUrl: './navigation-group.component.html',
@@ -10,5 +21,6 @@ import { ShellNavigationItemComponent } from '../navigation-item/navigation-item
   imports: [ShellNavigationItemComponent],
 })
 export class ShellNavigationGroupComponent {
+  /** The navigation group configuration with label and items. */
   readonly group = input.required<NavigationGroup>();
 }

libs/shell/navigation/src/lib/components/navigation-item/navigation-item.component.css

@@ -10,7 +10,7 @@ button {
     font-weight 0.15s ease-out;
 }
 
-a.active,
+a.active:not(.hide-active),
 a:hover,
 a:focus,
 button:hover,
@@ -18,7 +18,7 @@ button:focus {
   @apply bg-isa-neutral-200;
 }
 
-a.active .label {
+a.active:not(.hide-active) .label {
   @apply isa-text-body-1-semibold;
 }
 
@@ -28,7 +28,7 @@ a.active .label {
   opacity: 0;
 }
 
-a.active .active-bar {
+a.active:not(.hide-active) .active-bar {
   animation: barReveal 0.25s ease-out forwards;
 }
 
@@ -70,12 +70,36 @@ a.active .active-bar {
   opacity: 0;
 }
 
+.indicator-dot {
+  @apply absolute -top-1 -right-1 size-2 rounded-full bg-isa-accent-red;
+  animation: pulse-in 0.3s ease-out;
+}
+
+.indicator-dot-centered {
+  @apply size-1 rounded-full bg-isa-accent-red;
+  animation: pulse-in 0.3s ease-out;
+}
+
+@keyframes pulse-in {
+  0% {
+    transform: scale(0);
+    opacity: 0;
+  }
+  50% {
+    transform: scale(1.4);
+  }
+  100% {
+    transform: scale(1);
+    opacity: 1;
+  }
+}
+
 @media (prefers-reduced-motion: reduce) {
   .chevron {
     transition: none;
   }
 
-  a.active .active-bar {
+  a.active:not(.hide-active) .active-bar {
     animation: none;
     transform: scaleX(1);
     opacity: 1;
@@ -84,4 +108,9 @@ a.active .active-bar {
   .sub-items {
     transition: none;
   }
+
+  .indicator-dot,
+  .indicator-dot-centered {
+    animation: none;
+  }
 }

libs/shell/navigation/src/lib/components/navigation-item/navigation-item.component.html

@@ -2,9 +2,11 @@
   <a
     class="relative flex flex-row h-14 px-6 items-center justify-start gap-2 self-stretch"
     routerLinkActive="active"
+    [class.hide-active]="expanded() && hasActiveChild()"
     [routerLink]="r.route"
     [queryParams]="r.queryParams"
     [queryParamsHandling]="r.queryParamsHandling"
+    (click)="hasChildren() && expanded.set(true); closeNavigation()"
     data-what="navigation-item"
     [attr.data-which]="item().label"
     [attr.aria-label]="'Navigate to ' + item().label"
@@ -43,14 +45,21 @@
   <div
     class="active-bar absolute right-0 top-0 bottom-0 w-[0.375rem] bg-isa-neutral-700 rounded-full"
   ></div>
-  <div class="size-6 grow-0" [innerHTML]="sanitizedHtml()"></div>
+  <div class="relative size-6 grow-0 flex items-center justify-center">
+    @if (item().icon) {
+      <div [innerHTML]="sanitizedHtml()"></div>
+    }
+    @if (showIndicator()) {
+      <span [class]="item().icon ? 'indicator-dot' : 'indicator-dot-centered'"></span>
+    }
+  </div>
   <div class="label grow">
     {{ item().label }}
   </div>
   @if (hasChildren()) {
     <button
       type="button"
-      (click)="$event.stopPropagation(); toggleExpand()"
+      (click)="$event.stopPropagation(); $event.preventDefault(); toggleExpand()"
       data-what="navigation-chevron"
       [attr.data-which]="item().label"
       [attr.aria-expanded]="expanded()"

libs/shell/navigation/src/lib/components/navigation-item/navigation-item.component.ts

@@ -14,11 +14,31 @@ import {
 import { NavigationItem } from '../../types';
 import { DomSanitizer } from '@angular/platform-browser';
 import { isaActionChevronRight } from '@isa/icons';
+import { NavigationService } from '@isa/shell/common';
 import { NgIcon, provideIcons } from '@ng-icons/core';
 import { NgTemplateOutlet } from '@angular/common';
 import { RouterLink, RouterLinkActive } from '@angular/router';
 import { ShellNavigationSubItemComponent } from '../navigation-sub-item/navigation-sub-item.component';
 
+/**
+ * Navigation item component for the shell sidebar.
+ *
+ * Renders a single navigation item with optional icon, expandable submenu,
+ * and activity indicator. Supports both direct navigation routes and
+ * expandable groups with child routes.
+ *
+ * Features:
+ * - Icon display with sanitized SVG content
+ * - Expandable/collapsible submenu for child routes
+ * - Activity indicators (red dot) that bubble up from children when collapsed
+ * - Auto-expansion when a child route becomes active
+ * - Dynamic route resolution (supports factory functions and signals)
+ *
+ * @example
+ * ```html
+ * <shell-navigation-item [item]="navigationItem" />
+ * ```
+ */
 @Component({
   selector: 'shell-navigation-item',
   templateUrl: './navigation-item.component.html',
@@ -40,13 +60,18 @@ import { ShellNavigationSubItemComponent } from '../navigation-sub-item/navigati
 export class ShellNavigationItemComponent {
   #injector = inject(Injector);
   #sanitizer = inject(DomSanitizer);
+  #navigationService = inject(NavigationService);
 
+  /** Query for all child sub-item components. */
   readonly subItems = viewChildren(ShellNavigationSubItemComponent);
 
+  /** Whether the submenu is currently expanded. */
   expanded = signal(false);
 
+  /** The navigation item configuration to render. */
   readonly item = input.required<NavigationItem>();
 
+  /** Sanitized HTML content for the icon SVG. */
   sanitizedHtml = computed(() => {
     const icon = this.item().icon;
 
@@ -57,14 +82,72 @@ export class ShellNavigationItemComponent {
     return this.#sanitizer.bypassSecurityTrustHtml(icon);
   });
 
+  /** Whether this item has child routes. */
   hasChildren = computed(() => {
     return (this.item().childRoutes?.length ?? 0) > 0;
   });
 
+  /** Whether any child route is currently active. */
+  hasActiveChild = computed(() => {
+    return this.subItems().some((subItem) => subItem.isActive());
+  });
+
+  /**
+   * Resolves the indicator value, handling factory functions and signals.
+   * Returns the current indicator state (truthy = show red dot).
+   */
+  readonly resolvedIndicator = computed(() => {
+    const indicator = this.item().indicator;
+    if (typeof indicator === 'function') {
+      const result = runInInjectionContext(this.#injector, () => indicator());
+      return isSignal(result) ? result() : result;
+    }
+    return indicator;
+  });
+
+  /** Whether any child has an active indicator. */
+  readonly hasChildIndicator = computed(() => {
+    return this.subItems().some((subItem) => subItem.resolvedIndicator());
+  });
+
+  /**
+   * Determines if the indicator dot should be shown.
+   * Shows if this item has an indicator, or if a child has one and the menu is collapsed.
+   */
+  readonly showIndicator = computed(() => {
+    return this.resolvedIndicator() || (this.hasChildIndicator() && !this.expanded());
+  });
+
+  /** Toggles the expanded state of the submenu. */
   toggleExpand(): void {
     this.expanded.update((value) => !value);
   }
 
+  /** Closes the navigation sidebar (used on tablet/mobile after selection). */
+  closeNavigation(): void {
+    this.#navigationService.set(false);
+  }
+
+  /**
+   * Resolves the first child route for fallback navigation.
+   * Used when the item has no direct route but has child routes.
+   */
+  readonly firstChildRoute = computed(() => {
+    const childRoutes = this.item().childRoutes;
+    if (!childRoutes?.length) return undefined;
+
+    const firstChild = childRoutes[0];
+    if (typeof firstChild === 'function') {
+      const result = runInInjectionContext(this.#injector, () => firstChild());
+      return isSignal(result) ? result() : result;
+    }
+    return firstChild;
+  });
+
+  /**
+   * Resolves the navigation route, handling factory functions and signals.
+   * Falls back to the first child route if no direct route is defined.
+   */
   readonly route = computed(() => {
     const route = this.item().route;
 
@@ -73,13 +156,12 @@ export class ShellNavigationItemComponent {
       return isSignal(result) ? result() : result;
     }
 
-    return route;
+    return route ?? this.firstChildRoute();
   });
 
   constructor() {
     // Auto-expand when a child route becomes active.
-    // This is a valid effect use case: one-way sync of UI state based on router state.
-    // It only expands (never auto-collapses), preserving user's manual toggle preference.
+    // Valid effect: one-way sync of UI state from router state (only expands, never auto-collapses).
     effect(() => {
       const subItems = this.subItems();
       if (!subItems.length) return;