@codex-ts/core-lib 1.1.5 → 2.0.0

package/README.md

@@ -1,63 +1,392 @@
 # CoreLib
 
-This project was generated using [Angular CLI](https://github.com/angular/angular-cli) version 19.2.0.
+Reusable Angular library for enterprise applications, providing dynamic forms, CRUD services, and Keycloak-based authentication.
 
-## Code scaffolding
+---
 
-Angular CLI includes powerful code scaffolding tools. To generate a new component, run:
+## Overview
+
+CoreLib offers:
+- Abstract components for forms, lists, and dashboards
+- Generic CRUD services
+- Strongly-typed models and enums
+- Keycloak authentication and route protection
+- Signal-based error handling and state management
+- Built-in error pages and components
+- Utilities for state management and notifications
+
+---
+
+## Installation
 
 ```bash
-ng generate component component-name
+npm install @codex-ts/core-lib
 ```
 
-For a complete list of available schematics (such as `components`, `directives`, or `pipes`), run:
+**Peer dependencies** (install in your app if not present):
+- `@angular/core`, `@angular/common`, `@ngx-formly/core`, `primeng`, `rxjs`, `keycloak-js`
 
-```bash
-ng generate --help
+---
+
+## Setup
+
+### Configuring Keycloak with Environment Properties
+
+You can configure Keycloak using environment-specific properties to avoid hardcoding sensitive values.
+
+**Option 1: Using Angular's environment.ts**
+
+Set your Keycloak config in `src/environments/environment.ts`:
+
+```typescript
+// environment.ts
+export const environment = {
+  production: false,
+  keycloak: {
+    authServerUrl: 'https://<keycloak-server>/auth',
+    realm: '<realm>',
+    clientId: '<client-id>',
+    options: {
+      loginRedirect: '/dashboard',
+      bearerToken: true,
+      excludedUrls: ['/assets', '/public'],
+      roles: ['user', 'admin'],
+      tokenValidityThreshold: 60
+    }
+  }
+};
 ```
 
-## Building
+Then provide it in your app module:
 
-To build the library, run:
+```typescript
+import { environment } from '../environments/environment';
+import { KEYCLOAK_CONFIG } from '@codex-ts/core-lib';
 
-```bash
-ng build core-lib
+providers: [
+  {
+    provide: KEYCLOAK_CONFIG,
+    useValue: environment.keycloak
+  }
+]
 ```
 
-This command will compile your project, and the build artifacts will be placed in the `dist/` directory.
+**Option 2: Using Runtime Environment (e.g., assets/config.json)**
 
-### Publishing the Library
+1. Create a `config.json` file in your `assets` folder with Keycloak settings.
+2. Load it at app startup and provide it to `KEYCLOAK_CONFIG` using an `APP_INITIALIZER`.
 
-Once the project is built, you can publish your library by following these steps:
+Example:
 
-1. Navigate to the `dist` directory:
-   ```bash
-   cd dist/core-lib
-   ```
+```typescript
+// assets/config.json
+{
+  "authServerUrl": "https://<keycloak-server>/auth",
+  "realm": "<realm>",
+  "clientId": "<client-id>",
+  "options": {
+    "loginRedirect": "/dashboard",
+    "bearerToken": true
+  }
+}
+```
 
-2. Run the `npm publish` command to publish your library to the npm registry:
-   ```bash
-   npm publish
-   ```
+```typescript
+// app.module.ts
+import { HttpClient } from '@angular/common/http';
+import { APP_INITIALIZER } from '@angular/core';
+import { KEYCLOAK_CONFIG } from '@codex-ts/core-lib';
 
-## Running unit tests
+export function loadConfig(http: HttpClient) {
+  return () => http.get('/assets/config.json')
+    .toPromise()
+    .then(config => {
+      (window as any).keycloakConfig = config;
+    });
+}
 
-To execute unit tests with the [Karma](https://karma-runner.github.io) test runner, use the following command:
+providers: [
+  {
+    provide: APP_INITIALIZER,
+    useFactory: loadConfig,
+    deps: [HttpClient],
+    multi: true
+  },
+  {
+    provide: KEYCLOAK_CONFIG,
+    useFactory: () => (window as any).keycloakConfig
+  }
+]
+```
 
-```bash
-ng test
+This allows you to change Keycloak settings without rebuilding the app.
+
+### 1. Import the Library Module
+
+```typescript
+import { CoreLibModule } from '@codex-ts/core-lib';
+
+@NgModule({
+  imports: [CoreLibModule, ...]
+})
+export class AppModule {}
 ```
 
-## Running end-to-end tests
+### 2. Configure Keycloak
 
-For end-to-end (e2e) testing, run:
+Provide Keycloak configuration in your app module:
 
-```bash
-ng e2e
+```typescript
+import { KEYCLOAK_CONFIG } from '@codex-ts/core-lib';
+
+providers: [
+  {
+    provide: KEYCLOAK_CONFIG,
+    useValue: {
+      authServerUrl: 'https://<keycloak-server>/auth',
+      realm: '<realm>',
+      clientId: '<client-id>',
+      options: {
+        loginRedirect: '/dashboard',
+        bearerToken: true,
+        excludedUrls: ['/assets', '/public'],
+        roles: ['user', 'admin'],
+        tokenValidityThreshold: 60
+      }
+    }
+  }
+]
 ```
 
-Angular CLI does not come with an end-to-end testing framework by default. You can choose one that suits your needs.
+### 3. Register Interceptor and Guard
+
+```typescript
+import { HTTP_INTERCEPTORS } from '@angular/common/http';
+import { KeycloakAuthInterceptor, KeycloakAuthGuard } from '@codex-ts/core-lib';
+
+providers: [
+  { provide: HTTP_INTERCEPTORS, useClass: KeycloakAuthInterceptor, multi: true },
+  KeycloakAuthGuard
+]
+```
+
+### 4. Protect Routes
+
+```typescript
+{
+  path: 'secure',
+  component: SecureComponent,
+  canActivate: [KeycloakAuthGuard],
+  data: { roles: ['admin'] }
+}
+```
+
+---
+
+## Usage
+
+- Use provided base components and services for forms, lists, and CRUD operations.
+- Inject `KeycloakService` to access authentication state, user info, and roles.
+
+```typescript
+constructor(private keycloak: KeycloakService) {}
+
+ngOnInit() {
+  if (this.keycloak.isAuthenticated$()) {
+    // User is authenticated
+  }
+}
+```
+
+---
+
+## KeycloakService API
+
+- `initialize()`: Initializes Keycloak.
+- `login()`, `logout()`: Triggers login/logout.
+- `getToken()`: Gets current access token.
+- `getRoles()`, `hasRole(role)`: Role management.
+- `userProfile$`: Observable for user profile.
+
+**Example:**
+
+```typescript
+if (this.keycloak.hasRole('admin')) {
+  // Show admin features
+}
+```
+
+---
+
+## Troubleshooting
+
+- Ensure Keycloak server is reachable.
+- Check DI configuration for KEYCLOAK_CONFIG.
+- Use browser console for error logs from KeycloakService.
+
+---
+
+## Contributing
+
+- Fork, branch, and submit PRs.
+- Write unit tests for new features.
+
+---
+
+## License
+
+MIT
+
+---
+
+## Error Handling
+
+CoreLib provides a comprehensive, signal-based error handling system:
+
+### Features
+- Centralized error state management using Angular signals
+- Built-in error pages for common scenarios (404, 401, etc.)
+- Dynamic error messages and status codes
+- Automatic cleanup on navigation
+- Toast notifications for non-critical errors
+
+### Usage Example
+
+```typescript
+// 1. Error Service in your components/services
+constructor(private readonly errorService: BaseErrorService) {}
+
+try {
+  // Your code
+} catch (error) {
+  this.errorService.handleError(error);
+}
+
+// 2. React to errors in components
+export class YourComponent {
+  private readonly errorService = inject(ERROR_SERVICE);
+  readonly error = this.errorService.error;
+
+  get errorMessage(): string {
+    return this.error()?.message ?? "Default message";
+  }
+}
+```
+
+### Error Types
+- HTTP errors (401, 403, 404, 500, etc.)
+- Connection errors
+- Client-side errors
+- Application-specific errors
+
+### Built-in Error Pages
+- NotFoundComponent (404)
+- UnauthorizedComponent (401/403)
+- All error pages use signals for dynamic content
+
+### Benefits
+- Single source of truth for error handling
+- Reactive updates with signals
+- Consistent error handling across the application
+- Improved debugging with error context
+- Clean separation of error handling logic
+
+---
+
+## Task Management Implementation Example
+
+This section demonstrates how to use `core-lib` to implement a typical task management module in your Angular application.
+
+### Structure
+
+- **Dashboard Component**: Extends `BaseTaskDashboardComponent` from core-lib for listing and managing tasks.
+- **Details Component**: Extends `BaseFormComponent` or `BaseTaskDetailsComponent` for task details and editing.
+- **Models**: Define task models extending `BaseTaskModel` and related interfaces.
+- **Service**: Implements CRUD operations by extending `BaseCrudService`.
+
+### Example
+
+#### 1. Task Model
+
+```typescript
+import { BaseTaskModel } from '@codex-ts/core-lib';
+
+export interface CustomerServiceTask extends BaseTaskModel {
+  // Add custom fields here
+  status: string;
+  assignedTo: string;
+}
+```
+
+#### 2. Task Service
+
+```typescript
+import { Injectable } from '@angular/core';
+import { BaseCrudService } from '@codex-ts/core-lib';
+import { CustomerServiceTask } from './models/customer-service-task.model';
+
+@Injectable({ providedIn: 'root' })
+export class CustomerServiceTaskService extends BaseCrudService<CustomerServiceTask> {
+  constructor(/* inject dependencies */) {
+    super(/* pass dependencies and resource path */);
+  }
+}
+```
+
+#### 3. Dashboard Component
+
+```typescript
+import { Component } from '@angular/core';
+import { BaseTaskDashboardComponent } from '@codex-ts/core-lib';
+import { CustomerServiceTaskService } from './customer-service-task.service';
+import { CustomerServiceTask } from './models/customer-service-task.model';
+
+@Component({
+  selector: 'app-customer-service-task-dashboard',
+  templateUrl: './customer-service-task-dashboard.component.html'
+})
+export class CustomerServiceTaskDashboardComponent
+  extends BaseTaskDashboardComponent<CustomerServiceTask> {
+  constructor(protected customerServiceTaskService: CustomerServiceTaskService) {
+    super(customerServiceTaskService);
+  }
+}
+```
+
+#### 4. Details Component
+
+```typescript
+import { Component } from '@angular/core';
+import { BaseFormComponent } from '@codex-ts/core-lib';
+import { CustomerServiceTaskService } from './customer-service-task.service';
+import { CustomerServiceTask } from './models/customer-service-task.model';
+
+@Component({
+  selector: 'app-customer-task-details',
+  templateUrl: './customer-task-details.component.html'
+})
+export class CustomerTaskDetailsComponent
+  extends BaseFormComponent<CustomerServiceTask> {
+  constructor(protected customerServiceTaskService: CustomerServiceTaskService) {
+    super(customerServiceTaskService);
+  }
+}
+```
+
+#### 5. Routing and Guards
+
+Protect routes using `KeycloakAuthGuard` and specify roles as needed:
+
+```typescript
+{
+  path: 'tasks',
+  component: CustomerServiceTaskDashboardComponent,
+  canActivate: [KeycloakAuthGuard],
+  data: { roles: ['admin', 'user'] }
+}
+```
 
-## Additional Resources
+### Notes
 
-For more information on using the Angular CLI, including detailed command references, visit the [Angular CLI Overview and Command Reference](https://angular.dev/tools/cli) page.
+- Use the provided base components and services for rapid development and consistency.
+- Extend models and services as needed for your domain.