@flusys/ng-shared 4.1.1 → 5.0.0

package/README.md

@@ -1,75 +1,9 @@
 # @flusys/ng-shared
 
-> Shared utilities, response interfaces, provider interfaces, base classes, and reusable UI components for the FLUSYS Angular platform.
+Shared utilities, provider tokens, base page classes, and reusable components for the FLUSYS Angular platform.
 
 [![npm version](https://img.shields.io/npm/v/@flusys/ng-shared.svg)](https://www.npmjs.com/package/@flusys/ng-shared)
-[![Angular](https://img.shields.io/badge/Angular-21-red.svg)](https://angular.io)
-[![TypeScript](https://img.shields.io/badge/TypeScript-5.x-blue.svg)](https://www.typescriptlang.org)
-[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
-
----
-
-## Table of Contents
-
-- [Overview](#overview)
-- [Features](#features)
-- [Compatibility](#compatibility)
-- [Installation](#installation)
-- [Quick Start](#quick-start)
-- [Response Interfaces](#response-interfaces)
-- [Provider Interface Pattern](#provider-interface-pattern)
-  - [Injection Tokens](#injection-tokens)
-  - [USER_PROVIDER](#user_provider)
-  - [COMPANY_PROVIDER](#company_provider)
-  - [FILE_PROVIDER](#file_provider)
-- [Base Classes](#base-classes)
-  - [ApiResourceService](#apiresourceservice)
-  - [BaseListPage](#baselistpage)
-  - [BaseFormPage](#baseformpage)
-- [Services](#services)
-  - [FileUrlService](#fileurlservice)
-  - [PermissionValidatorService](#permissionvalidatorservice)
-- [Reusable Components](#reusable-components)
-- [Directives](#directives)
-- [Pipes](#pipes)
-- [Guards](#guards)
-- [Modules](#modules)
-- [Troubleshooting](#troubleshooting)
-- [License](#license)
-
----
-
-## Overview
-
-`@flusys/ng-shared` is the second layer in the FLUSYS Angular dependency hierarchy. It depends on `@flusys/ng-core` and provides everything that feature packages (`ng-auth`, `ng-iam`, `ng-storage`, etc.) need to function **independently** of each other.
-
-The cornerstone of `ng-shared` is the **Provider Interface Pattern**: injection tokens that define contracts between feature packages. `ng-auth` provides implementations; `ng-iam`, `ng-storage`, and other packages inject the interfaces — never the concrete implementations.
-
----
-
-## Features
-
-- ✅ Typed response interfaces (`ISingleResponse`, `IListResponse`, `IBulkResponse`, `IMessageResponse`)
-- ✅ Provider Interface Pattern — `USER_PROVIDER`, `COMPANY_PROVIDER`, `FILE_PROVIDER`
-- ✅ `ApiResourceService` — typed CRUD service base class
-- ✅ `BaseListPage` / `BaseFormPage` — page scaffolding with signal state
-- ✅ `FileUrlService` — safe presigned URL fetching (never construct URLs manually)
-- ✅ `PermissionValidatorService` — client-side permission evaluation
-- ✅ `LazySelectComponent` — virtualized dropdown with server-side search
-- ✅ `FileSelectorDialogComponent` — file picker dialog
-- ✅ `HasPermissionDirective` — structural directive for permission-gated content
-- ✅ `TranslatePipe` — i18n pipe with parameter interpolation
-- ✅ `AngularModule` / `PrimeModule` — pre-aggregated Angular and PrimeNG imports
-
----
-
-## Compatibility
-
-| Package | Version |
-|---------|---------|
-| Angular | 21+ |
-| @flusys/ng-core | 4.x |
-| PrimeNG | 18+ |
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
 ---
 
@@ -81,449 +15,146 @@ npm install @flusys/ng-shared @flusys/ng-core
 
 ---
 
-## Quick Start
-
-```typescript
-// app.config.ts
-import { provideHttpClient, withInterceptors } from '@angular/common/http';
-import { APP_CONFIG } from '@flusys/ng-core';
-import { environment } from './environments/environment';
-
-export const appConfig: ApplicationConfig = {
-  providers: [
-    { provide: APP_CONFIG, useValue: environment },
-    provideHttpClient(),
-    // Feature providers register against ng-shared tokens (see below)
-  ],
-};
-```
-
----
-
-## Response Interfaces
-
-All FLUSYS backend responses conform to one of four shapes:
-
-### ISingleResponse\<T\>
-
-```typescript
-interface ISingleResponse<T> {
-  data: T;
-}
-```
-
-### IListResponse\<T\>
-
-```typescript
-interface IListResponse<T> {
-  data: T[];
-  total: number;
-  page: number;
-  pageSize: number;
-}
-```
-
-### IBulkResponse\<T\>
-
-```typescript
-interface IBulkResponse<T> {
-  data: T[];
-  successCount: number;
-  failureCount: number;
-  errors?: string[];
-}
-```
-
-### IMessageResponse
-
-```typescript
-interface IMessageResponse {
-  message: string;
-}
-```
-
-### IErrorResponse
-
-```typescript
-interface IErrorResponse {
-  statusCode: number;
-  message: string;
-  error?: string;
-}
-```
-
-### IListParams (Common Request Shape)
-
-```typescript
-interface IListParams {
-  page?: number;
-  pageSize?: number;
-  search?: string;
-  sortBy?: string;
-  sortOrder?: 'ASC' | 'DESC';
-  filters?: Record<string, unknown>;
-}
-```
-
----
-
-## Provider Interface Pattern
-
-Feature packages never import each other directly. Instead, `ng-shared` defines **injection token interfaces** that decouple consumers from providers.
-
-```
-ng-auth          ──implements──► USER_PROVIDER token  ◄──injects── ng-iam
-                 ──implements──► COMPANY_PROVIDER      ◄──injects── ng-storage
-ng-storage       ──implements──► FILE_PROVIDER         ◄──injects── ng-shared components
-```
-
-### Injection Tokens
+## 1. ApiResourceService — Signal-Driven CRUD
 
-| Token | Interface | Provided By | Used By |
-|-------|-----------|-------------|---------|
-| `USER_PROVIDER` | `IUserProvider` | `ng-auth` | `ng-iam`, `ng-storage` |
-| `COMPANY_PROVIDER` | `ICompanyProvider` | `ng-auth` | `ng-storage`, `ng-notification` |
-| `FILE_PROVIDER` | `IFileProvider` | `ng-storage` | `ng-shared` components |
-| `LAYOUT_AUTH_STATE` | `ILayoutAuthState` | `ng-auth` | `ng-layout` |
-| `LAYOUT_AUTH_API` | `ILayoutAuthApi` | `ng-auth` | `ng-layout` |
-| `LAYOUT_NOTIFICATION_BELL` | `INotificationBellProvider` | `ng-notification` | `ng-layout` |
-| `LAYOUT_LANGUAGE_SELECTOR` | `ILanguageSelectorProvider` | `ng-localization` | `ng-layout` |
-
-### USER_PROVIDER
+Extend this class to get a reactive list resource backed by `resource()`, with pagination, search, and all standard POST-only RPC endpoints.
 
 ```typescript
-interface IUserProvider {
-  user: Signal<ICurrentUser | null>;
-  isAuthenticated: Signal<boolean>;
-}
+import { Injectable, inject } from '@angular/core';
+import { HttpClient } from '@angular/common/http';
+import { ApiResourceService } from '@flusys/ng-shared';
 
-// Consuming (in ng-iam)
-import { USER_PROVIDER, IUserProvider } from '@flusys/ng-shared';
+export interface IProduct { id: string; name: string; price: number; }
+export interface IProductDto { name: string; price: number; }
 
 @Injectable({ providedIn: 'root' })
-export class IamService {
-  private userProvider = inject<IUserProvider>(USER_PROVIDER);
-
-  getCurrentUserId(): string | null {
-    return this.userProvider.user()?.id ?? null;
+export class ProductService extends ApiResourceService<IProductDto, IProduct> {
+  constructor() {
+    super('products', inject(HttpClient), 'administration'); // moduleApiName, http, serviceName (key in APP_CONFIG.services)
   }
 }
 ```
 
-### COMPANY_PROVIDER
+Using the reactive list in a component:
 
 ```typescript
-interface ICompanyProvider {
-  company: Signal<ICompany | null>;
-  branch: Signal<IBranch | null>;
-  companyId: Signal<string | null>;
-}
-```
-
-### FILE_PROVIDER
-
-```typescript
-interface IFileProvider {
-  getFileUrl(fileId: string): Observable<string | null>;
-  uploadFile(file: File, folder?: string): Observable<IUploadedFile>;
-}
-```
-
----
-
-## Base Classes
-
-### ApiResourceService
-
-Generic typed CRUD service that maps to FLUSYS POST-only RPC endpoints. Extend this to create a fully-typed API service in seconds.
+@Component({ ... })
+export class ProductListComponent {
+  private readonly svc = inject(ProductService);
 
-```typescript
-import { ApiResourceService } from '@flusys/ng-shared';
+  readonly items   = this.svc.data;      // Signal<IProduct[]>
+  readonly total   = this.svc.total;     // Signal<number>
+  readonly loading = this.svc.isLoading; // Signal<boolean>
 
-@Injectable({ providedIn: 'root' })
-export class ProductApiService extends ApiResourceService<Product, CreateProductDto, UpdateProductDto> {
-  protected override resource = 'product';
-}
+  ngOnInit() { this.svc.fetchList(); }
 
-// Automatically provides:
-// - getAll(params): Observable<IListResponse<Product>>
-// - getById(id): Observable<ISingleResponse<Product>>
-// - insert(dto): Observable<ISingleResponse<Product>>
-// - update(dto): Observable<ISingleResponse<Product>>
-// - delete(id): Observable<IMessageResponse>
-// - bulkDelete(ids): Observable<IBulkResponse<Product>>
-```
+  onSearch(q: string) { this.svc.fetchList(q); }
 
-### BaseListPage
+  onPageChange(page: number, size: number) {
+    this.svc.setPagination({ currentPage: page, pageSize: size });
+  }
 
-Scaffold for list pages with built-in pagination, search, and loading state using signals.
+  async onCreate(dto: IProductDto) {
+    await this.svc.insert(dto);
+    this.svc.reload();
+  }
 
-```typescript
-import { BaseListPage } from '@flusys/ng-shared';
-
-@Component({
-  selector: 'app-product-list',
-  templateUrl: './product-list.component.html',
-})
-export class ProductListComponent extends BaseListPage<Product> {
-  protected apiService = inject(ProductApiService);
-
-  // Inherited signals:
-  // items        Signal<Product[]>
-  // total        Signal<number>
-  // page         Signal<number>
-  // pageSize     Signal<number>
-  // isLoading    Signal<boolean>
-  // searchQuery  Signal<string>
+  async onDelete(id: string) {
+    await this.svc.delete({ id });
+    this.svc.reload();
+  }
 }
 ```
 
-### BaseFormPage
-
-Scaffold for create/edit forms with validation state and submission handling.
-
-```typescript
-import { BaseFormPage } from '@flusys/ng-shared';
-
-@Component({
-  selector: 'app-product-form',
-  templateUrl: './product-form.component.html',
-})
-export class ProductFormComponent extends BaseFormPage<Product> {
-  protected apiService = inject(ProductApiService);
-
-  // Inherited signals:
-  // isSaving     Signal<boolean>
-  // isEditMode   Signal<boolean>
-  // formErrors   Signal<Record<string, string>>
-}
-```
+Available CRUD methods: `insert`, `insertMany`, `findById`, `findByIds`, `getAll`, `getByFilter`, `update`, `updateMany`, `bulkUpsert`, `delete`.
 
 ---
 
-## Services
-
-### FileUrlService
+## 2. FileUrlService — Presigned URL Fetching
 
-**CRITICAL:** Always use `FileUrlService` to fetch file URLs. Never construct URLs manually. FLUSYS supports S3, Azure, and SFTP with presigned URLs that expire — only the backend knows the current URL.
+Never construct file URLs manually. `FileUrlService` handles S3/Azure presigned URLs, caching, and deduplication.
 
 ```typescript
 import { FileUrlService } from '@flusys/ng-shared';
 
 @Component({ ... })
 export class AvatarComponent {
-  private fileUrlService = inject(FileUrlService);
-  avatarUrl = signal<string | null>(null);
+  private readonly fileUrlService = inject(FileUrlService);
+  readonly avatarUrl = signal<string | null>(null);
 
-  async loadAvatar(fileId: string): Promise<void> {
-    const file = await this.fileUrlService.fetchSingleFileUrl(fileId);
-    this.avatarUrl.set(file?.url ?? null);
+  ngOnInit() {
+    this.fileUrlService.fetchSingleFileUrl('file-id-123').subscribe(file => {
+      this.avatarUrl.set(file?.url ?? null);
+    });
   }
-}
-```
-
-```typescript
-// ❌ WRONG — never construct file URLs manually
-const url = `${apiBaseUrl}/storage/${fileId}`;
-
-// ✅ CORRECT — always use FileUrlService
-const file = await this.fileUrlService.fetchSingleFileUrl(fileId);
-const url = file?.url ?? null;
-```
-
-**Methods:**
-
-| Method | Description |
-|--------|-------------|
-| `fetchSingleFileUrl(fileId)` | Fetch presigned URL for a single file |
-| `fetchMultipleFileUrls(fileIds)` | Batch fetch presigned URLs |
-| `clearCache(fileId?)` | Invalidate cached URL(s) |
-
-### PermissionValidatorService
-
-Client-side permission evaluation without direct ng-iam dependency.
-
-```typescript
-import { PermissionValidatorService } from '@flusys/ng-shared';
 
-@Component({ ... })
-export class MyComponent {
-  private permValidator = inject(PermissionValidatorService);
+  // Batch fetch — only requests IDs not already cached
+  loadMultiple(ids: string[]) {
+    this.fileUrlService.fetchFileUrls(ids).subscribe(files => { /* ... */ });
+  }
 
-  canEdit = computed(() =>
-    this.permValidator.hasPermission('product:update')
-  );
+  // Synchronous read from cache after a prior fetch
+  getCachedUrl(id: string): string | null {
+    return this.fileUrlService.getFileUrl(id);
+  }
 }
 ```
 
 ---
 
-## Reusable Components
-
-### LazySelectComponent
-
-Virtualized dropdown with server-side search. Ideal for large datasets.
-
-```html
-<flusys-lazy-select
-  [apiService]="productApiService"
-  [labelField]="'name'"
-  [valueField]="'id'"
-  [(ngModel)]="selectedProductId"
-  placeholder="Search products..."
-/>
-```
-
-### FileSelectorDialogComponent
-
-File picker dialog that integrates with `@flusys/ng-storage`.
-
-```html
-<flusys-file-selector
-  [accept]="'image/*'"
-  [maxSize]="5242880"
-  (fileSelected)="onFileSelected($event)"
-/>
-```
-
----
-
-## Directives
-
-### HasPermissionDirective
-
-Structural directive that removes elements from the DOM if the user lacks the required permission:
-
-```html
-<!-- Single permission -->
-<button *hasPermission="'product:delete'">Delete</button>
-
-<!-- Multiple permissions (AND logic) -->
-<div *hasPermission="['product:update', 'product:read']">Edit Panel</div>
+## 3. PermissionValidatorService + HasPermissionDirective
 
-<!-- OR logic -->
-<div *hasPermission="'product:update'" [permissionOr]="true">Edit Panel</div>
+```typescript
+const pv = inject(PermissionValidatorService);
 
-<!-- Show fallback content -->
-<button *hasPermission="'admin:manage'; else noAccess">Admin</button>
-<ng-template #noAccess>
-  <span>No access</span>
-</ng-template>
+pv.hasPermission('user.create');   // true
+pv.hasPermission('report.export'); // true — wildcard match
+pv.isPermissionsLoaded();          // boolean
 ```
 
----
-
-## Pipes
-
-### TranslatePipe
-
-Translate i18n keys with optional parameter interpolation:
-
 ```html
-<!-- Basic translation -->
-<span>{{ 'common.save' | translate }}</span>
-
-<!-- With parameters -->
-<span>{{ 'pagination.showing' | translate: { from: 1, to: 10, total: 100 } }}</span>
+<!-- Removes element from DOM when permission fails -->
+<button *hasPermission="'user.create'">Create User</button>
 ```
 
-The pipe automatically subscribes to language change events and re-renders on switch.
-
 ---
 
-## Guards
-
-| Guard | Description |
-|-------|-------------|
-| `AuthenticatedGuard` | Redirects unauthenticated users to `/auth/login` |
-| `GuestGuard` | Redirects authenticated users away from auth pages |
-| `PermissionGuard` | Blocks route if user lacks required permission |
+## 4. Permission Guards
 
 ```typescript
-// app.routes.ts
+import { permissionGuard, anyPermissionGuard, allPermissionsGuard } from '@flusys/ng-shared';
+
 export const routes: Routes = [
   {
-    path: 'products',
-    canActivate: [AuthenticatedGuard],
-    loadComponent: () => import('./pages/product-list.component'),
+    path: 'users',
+    canActivate: [permissionGuard('user.view')],                          // single
+    loadComponent: () => import('./user-list.component'),
+  },
+  {
+    path: 'reports',
+    canActivate: [anyPermissionGuard(['report.view', 'report.export'])],  // OR
+    loadComponent: () => import('./reports.component'),
   },
   {
     path: 'admin',
-    canActivate: [PermissionGuard],
-    data: { permission: 'admin:manage' },
-    loadComponent: () => import('./pages/admin.component'),
+    canActivate: [allPermissionsGuard(['admin.view', 'admin.manage'])],   // AND
+    loadComponent: () => import('./admin.component'),
   },
 ];
 ```
 
----
-
-## Modules
-
-### AngularModule
-
-Pre-aggregated Angular common imports for use in components:
-
-```typescript
-import { AngularModule } from '@flusys/ng-shared';
-
-@Component({
-  imports: [AngularModule],
-  // Includes: CommonModule, FormsModule, ReactiveFormsModule, RouterModule, etc.
-})
-export class MyComponent {}
-```
-
-### PrimeModule
-
-Pre-aggregated PrimeNG component imports:
-
-```typescript
-import { PrimeModule } from '@flusys/ng-shared';
-
-@Component({
-  imports: [PrimeModule],
-  // Includes: ButtonModule, TableModule, DialogModule, InputTextModule, etc.
-})
-export class MyComponent {}
-```
+All three guards redirect to `/` by default. Pass a second argument to change it: `permissionGuard('user.view', '/access-denied')`.
 
 ---
 
-## Troubleshooting
-
-**`No provider for USER_PROVIDER`**
-
-You need to register the auth providers in `app.config.ts`:
-
-```typescript
-import { provideAuthProviders } from '@flusys/ng-auth';
-
-providers: [
-  ...provideAuthProviders(),
-]
-```
-
-**`FileUrlService returns null for valid fileId`**
+## 5. TranslatePipe
 
-The file may not exist or the storage module isn't registered:
+```html
+{{ 'shared.save' | translate }}
 
-```typescript
-// Ensure storage is enabled in APP_CONFIG
-services: {
-  storage: { enabled: true }
-}
+{{ 'pagination.showing' | translate: { from: 1, to: 10 } }}
 ```
 
-**`TranslatePipe shows raw key (e.g., "common.save")`**
-
-Localization isn't initialized or the key doesn't exist in translation files. Provide `TRANSLATE_ADAPTER` in `app.config.ts` via `provideLocalization()`.
-
-**`HasPermissionDirective always hides content`**
-
-`PermissionValidatorService` has no data — ensure `ng-iam` is enabled and permissions are loaded after login.
-
----
 
 ## License