sxhundred/ISA-Frontend
1
0
Fork 0
mirror of https://dev.azure.com/hugendubel/ISA/_git/ISA-Frontend synced 2025-12-28 22:42:11 +01:00
Code Issues Packages Projects Releases Wiki Activity

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

Browse Source 
- 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
This commit is contained in:
Lorenz Hilpert
2025-12-10 20:40:12 +01:00
parent 609a7ed6dd
commit 0a1f25a1ee
4 changed files with 190 additions and 21 deletions
Download Patch File Download Diff File Expand all files Collapse all files

20
docs/library-reference.md
View File

@@ -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

96
libs/core/connectivity/README.md
View File

@@ -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

37
libs/shell/common/README.md
View File

@@ -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

58
libs/shell/layout/README.md
View File

@@ -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