📝 docs(shell): update READMEs and library reference

Update documentation for shell-header, shell-layout, shell-notifications, and shell-common libraries with API references, E2E attributes, and accessibility documentation.
2025-12-31 09:37:15 +01:00 · 2025-12-03 21:18:34 +01:00
parent 9a8eac3f9a
commit 5fe85282e7
3 changed files with 218 additions and 15 deletions
--- a/docs/library-reference.md
+++ b/docs/library-reference.md
@@ -1,11 +1,11 @@
 # Library Reference Guide

-> **Last Updated:** 2025-11-28
+> **Last Updated:** 2025-12-03
 > **Angular Version:** 20.3.6
 > **Nx Version:** 21.3.2
-> **Total Libraries:** 75
+> **Total Libraries:** 81

-All 75 libraries in the monorepo have comprehensive README.md documentation located at `libs/[domain]/[layer]/[feature]/README.md`.
+All 81 libraries in the monorepo have comprehensive README.md documentation located at `libs/[domain]/[layer]/[feature]/README.md`.

 **IMPORTANT: Always use the `docs-researcher` subagent** to retrieve and analyze library documentation. This keeps the main context clean and prevents pollution.

@@ -66,7 +66,7 @@ A comprehensive loyalty rewards catalog feature for Angular applications support

 ---

-## Common Libraries (3 libraries)
+## Common Libraries (4 libraries)

 ### `@isa/common/data-access`
 A foundational data access library providing core utilities, error handling, RxJS operators, response models, and advanced batching infrastructure for Angular applications.
@@ -83,6 +83,11 @@ A comprehensive print management library for Angular applications providing prin

 **Location:** `libs/common/print/`

+### `@isa/common/title-management`
+Reusable title management patterns for Angular applications with reactive updates and tab integration.
+
+**Location:** `libs/common/title-management/`
+
 ---

 ## Core Libraries (7 libraries)
@@ -92,16 +97,16 @@ Type-safe role-based authorization utilities with Angular signals integration fo

 **Location:** `libs/core/auth/`

-### `@isa/core/connectivity`
-Network connectivity status service providing reactive online/offline observables for monitoring network state across the application.
-
-**Location:** `libs/core/connectivity/`
-
 ### `@isa/core/config`
 A lightweight, type-safe configuration management system for Angular applications with runtime validation and nested object access.

 **Location:** `libs/core/config/`

+### `@isa/core/connectivity`
+This library was generated with [Nx](https://nx.dev).
+
+**Location:** `libs/core/connectivity/`
+
 ### `@isa/core/logging`
 A structured, high-performance logging library for Angular applications with hierarchical context support and flexible sink architecture.

@@ -430,6 +435,35 @@ A lightweight Zod utility library for safe parsing with automatic fallback to or

 ---

+## Shell Domain (5 libraries)
+
+### `@isa/shell/common`
+**Type:** Util Library
+
+**Location:** `libs/shell/common/`
+
+### `@isa/shell/header`
+**Type:** Feature Library
+
+**Location:** `libs/shell/header/`
+
+### `@isa/shell/layout`
+**Type:** Feature Library
+
+**Location:** `libs/shell/layout/`
+
+### `@isa/shell/navigation`
+This library was generated with [Nx](https://nx.dev).
+
+**Location:** `libs/shell/navigation/`
+
+### `@isa/shell/notifications`
+**Type:** Feature Library
+
+**Location:** `libs/shell/notifications/`
+
+---
+
 ## How to Use This Guide

 1. **Quick Lookup**: Use this guide to find the purpose of any library in the monorepo
--- a/libs/shell/header/README.md
+++ b/libs/shell/header/README.md
@@ -1,7 +1,92 @@
 # shell-header

-This library was generated with [Nx](https://nx.dev).
+> **Type:** Feature Library
+> **Domain:** Shell
+> **Path:** `libs/shell/header`

-## Running unit tests
+## Overview

-Run `nx test shell-header` to execute the unit tests.
+Application header component providing navigation, accessibility controls, and user actions. Displays on tablet/desktop viewports as the primary toolbar.
+
+## Features
+
+- Navigation toggle button (tablet/desktop responsive)
+- Font size selector for accessibility
+- Logout button with authentication integration
+- Notifications toggle with overlay panel
+
+## Installation
+
+```typescript
+import { ShellHeaderComponent } from '@isa/shell/header';
+```
+
+## Usage
+
+```typescript
+@Component({
+  selector: 'app-layout',
+  standalone: true,
+  imports: [ShellHeaderComponent],
+  template: `<shell-header />`
+})
+export class AppLayoutComponent {}
+```
+
+## Components
+
+### ShellHeaderComponent
+
+**Selector:** `shell-header`
+
+Main header container that orchestrates sub-components based on viewport breakpoint.
+
+### Internal Components
+
+| Component | Selector | Purpose |
+|-----------|----------|---------|
+| `ShellNavigationToggleComponent` | `shell-navigation-toggle` | Toggles navigation drawer state |
+| `ShellFontSizeSelectorComponent` | `shell-font-size-selector` | Accessibility font size control |
+| `ShellLogoutButtonComponent` | `shell-logout-button` | Triggers user logout |
+| `ShellNotificationsToggleComponent` | `shell-notifications-toggle` | Opens notifications panel overlay |
+
+## E2E Testing
+
+| Element | data-what | data-which | Purpose |
+|---------|-----------|------------|---------|
+| Header | `header` | `shell-header` | Main header container |
+| Navigation toggle | `button` | `navigation-toggle` | Menu button |
+| Font size selector | `fieldset` | `font-size-selector` | Font size controls |
+| Logout button | `button` | `logout-button` | Logout action |
+| Notifications toggle | `button` | `notifications-toggle` | Notifications trigger |
+| Notifications panel | `panel` | `notifications-panel` | Notifications overlay |
+
+## Accessibility
+
+- Semantic `<header>` with `role="banner"`
+- Dynamic `aria-label` and `aria-expanded` on toggle buttons
+- Font size selector uses `role="radiogroup"`
+- Notifications panel uses `role="dialog"` with `aria-haspopup`
+
+## Dependencies
+
+**Internal:**
+- `@isa/shell/common` - Navigation, font size, notifications services
+- `@isa/shell/notifications` - Notifications panel component
+- `@isa/ui/buttons` - IconButtonComponent, InfoButtonComponent
+- `@isa/ui/layout` - Breakpoint utilities
+- `@isa/core/auth` - AuthService
+- `@isa/core/logging` - Logger factory
+- `@isa/icons` - Navigation icons
+
+## Testing
+
+```bash
+npx nx test shell-header
+```
+
+## Related Libraries
+
+- [`@isa/shell/layout`](../layout) - Parent layout component
+- [`@isa/shell/common`](../common) - Shared shell services
+- [`@isa/shell/notifications`](../notifications) - Notifications display
--- a/libs/shell/layout/README.md
+++ b/libs/shell/layout/README.md
@@ -1,7 +1,91 @@
 # shell-layout

-This library was generated with [Nx](https://nx.dev).
+> **Type:** Feature Library
+> **Domain:** Shell
+> **Path:** `libs/shell/layout`

-## Running unit tests
+## Overview

-Run `nx test shell-layout` to execute the unit tests.
+Root layout component for the application shell. Provides the main structural wrapper including network status banner and header.
+
+## Features
+
+- Network status banner with offline/online state transitions
+- Header integration via `@isa/shell/header`
+- Content projection for main page content
+
+## Installation
+
+```typescript
+import { ShellLayoutComponent } from '@isa/shell/layout';
+```
+
+## Usage
+
+```typescript
+@Component({
+  selector: 'app-root',
+  standalone: true,
+  imports: [ShellLayoutComponent],
+  template: `
+    <shell-layout>
+      <router-outlet />
+    </shell-layout>
+  `
+})
+export class AppComponent {}
+```
+
+## Components
+
+### ShellLayoutComponent
+
+**Selector:** `shell-layout`
+
+Root layout wrapper that structures the application shell.
+
+**Template Structure:**
+```html
+<shell-network-status-banner />
+<shell-header />
+<main>
+  <ng-content></ng-content>
+</main>
+```
+
+### NetworkStatusBannerComponent
+
+**Selector:** `shell-network-status-banner`
+
+Displays connectivity status banners for network state changes.
+
+**Behavior:**
+- **Offline:** Persistent red banner when network connection is lost
+- **Online:** Green success banner on reconnection, auto-dismisses after 2.5 seconds
+- Only shows after actual state change (not on initial load when online)
+
+**Exported Constants:**
+- `ONLINE_BANNER_DISPLAY_DURATION_MS` - Banner display duration (2500ms)
+
+## Accessibility
+
+- Uses `text-isa-neutral-900` host class for proper contrast
+- Network status banner announces connectivity changes
+
+## Dependencies
+
+**Internal:**
+- `@isa/shell/header` - Header component
+- `@isa/core/connectivity` - Network status service
+- `@isa/core/logging` - Logger factory
+
+## Testing
+
+```bash
+npx nx test shell-layout
+```
+
+## Related Libraries
+
+- [`@isa/shell/header`](../header) - Header component
+- [`@isa/core/connectivity`](../../core/connectivity) - Network status service