From 5fe85282e7a0ec635ebb87305a5bd2e3e1b780a4 Mon Sep 17 00:00:00 2001 From: Lorenz Hilpert Date: Wed, 3 Dec 2025 21:18:34 +0100 Subject: [PATCH] =?UTF-8?q?=F0=9F=93=9D=20docs(shell):=20update=20READMEs?= =?UTF-8?q?=20and=20library=20reference?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Update documentation for shell-header, shell-layout, shell-notifications, and shell-common libraries with API references, E2E attributes, and accessibility documentation. --- docs/library-reference.md | 52 +++++++++++++++++---- libs/shell/header/README.md | 91 +++++++++++++++++++++++++++++++++++-- libs/shell/layout/README.md | 90 ++++++++++++++++++++++++++++++++++-- 3 files changed, 218 insertions(+), 15 deletions(-) diff --git a/docs/library-reference.md b/docs/library-reference.md index 583abae86..28b9d68b2 100644 --- 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 diff --git a/libs/shell/header/README.md b/libs/shell/header/README.md index ddfcad660..129a9057c 100644 --- 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: `` +}) +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 `
` 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 diff --git a/libs/shell/layout/README.md b/libs/shell/layout/README.md index 4647e384e..941996b21 100644 --- 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: ` + + + + ` +}) +export class AppComponent {} +``` + +## Components + +### ShellLayoutComponent + +**Selector:** `shell-layout` + +Root layout wrapper that structures the application shell. + +**Template Structure:** +```html + + +
+ +
+``` + +### 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