@flusys/ng-shared 4.0.2 → 4.1.1

package/README.md

@@ -1,1814 +1,530 @@
-# @flusys/ng-shared Package Guide
+# @flusys/ng-shared
 
-## Overview
-
-`@flusys/ng-shared` provides reusable components, directives, API services, and utilities used across all FLUSYS applications. This package extends ng-core with UI components, API integration patterns, and provider interfaces for package independence.
-
-**Key Principle:** ng-shared depends only on ng-core, never on ng-layout or feature packages.
-
-## Package Information
+> Shared utilities, response interfaces, provider interfaces, base classes, and reusable UI components for the FLUSYS Angular platform.
 
-- **Package:** `@flusys/ng-shared`
-- **Version:** 4.0.2
-- **Dependencies:** ng-core
-- **Dependents:** ng-layout, ng-auth, ng-iam, ng-storage, flusysng
-- **Build Command:** `npm run build:ng-shared`
+[![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)
 
 ---
 
-## 1. Interfaces
+## 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)
 
-### Data Interfaces
-
-#### IBaseEntity
-
-Base entity interface matching backend Identity entity.
+---
 
-```typescript
-interface IBaseEntity {
-  id: string;
-  createdAt: Date;
-  updatedAt: Date;
-  deletedAt?: Date | null;
-  createdById?: string | null;
-  updatedById?: string | null;
-  deletedById?: string | null;
-}
-```
+## Overview
 
-**Entity Mixins:**
+`@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.
 
-| Interface        | Fields                               | Purpose              |
-| ---------------- | ------------------------------------ | -------------------- |
-| `ISoftDeletable` | `deletedAt?: Date \| null`           | Soft delete support  |
-| `ITimestampable` | `createdAt, updatedAt`               | Timestamp tracking   |
-| `IActivatable`   | `isActive: boolean`                  | Active status toggle |
-| `IOrderable`     | `serial?: number \| null`            | Ordering/sorting     |
-| `IMetadata`      | `metadata?: Record<string, unknown>` | JSON metadata field  |
+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.
 
-#### ILoggedUserInfo
+---
 
-Current logged-in user info with optional company context.
+## Features
 
-```typescript
-interface ILoggedUserInfo {
-  id: string;
-  email: string;
-  name?: string;
-  phone?: string;
-  profilePictureId?: string;
-  companyId?: string;
-  branchId?: string;
-  companyLogoId?: string;
-  branchLogoId?: string;
-}
-```
+- ✅ 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
 
-#### IFilterData
+---
 
-Filter, pagination, and sort payload for list queries.
+## Compatibility
 
-```typescript
-interface IPagination {
-  pageSize: number;
-  currentPage: number;
-}
+| Package | Version |
+|---------|---------|
+| Angular | 21+ |
+| @flusys/ng-core | 4.x |
+| PrimeNG | 18+ |
 
-interface ISort {
-  [key: string]: "ASC" | "DESC";
-}
+---
 
-// Filter supports primitives and arrays for multi-value filtering
-interface IFilter {
-  [key: string]: string | number | boolean | null | undefined | string[] | number[];
-}
+## Installation
 
-interface IFilterData {
-  filter?: IFilter;
-  pagination?: IPagination;
-  select?: string[];
-  sort?: ISort;
-  withDeleted?: boolean;
-  extraKey?: string[];
-}
+```bash
+npm install @flusys/ng-shared @flusys/ng-core
 ```
 
-**Note:** `IFilter` supports array values (`string[]`, `number[]`) for multi-value filtering (e.g., filtering by multiple status values or IDs).
-
-#### IDeleteData
+---
 
-Delete request payload matching backend DeleteDto.
+## Quick Start
 
 ```typescript
-type DeleteType = "delete" | "restore" | "permanent";
+// app.config.ts
+import { provideHttpClient, withInterceptors } from '@angular/common/http';
+import { APP_CONFIG } from '@flusys/ng-core';
+import { environment } from './environments/environment';
 
-interface IDeleteData {
-  id: string | string[]; // Single or batch delete
-  type: DeleteType;
-}
+export const appConfig: ApplicationConfig = {
+  providers: [
+    { provide: APP_CONFIG, useValue: environment },
+    provideHttpClient(),
+    // Feature providers register against ng-shared tokens (see below)
+  ],
+};
 ```
 
-#### IDropDown
+---
 
-Simple dropdown item for select components.
+## Response Interfaces
 
-```typescript
-interface IDropDown {
-  label: string;
-  value: string;
-}
-```
+All FLUSYS backend responses conform to one of four shapes:
 
-#### User Select Interfaces
+### ISingleResponse\<T\>
 
 ```typescript
-interface IUserSelectFilter {
-  page: number;
-  pageSize: number;
-  search: string;
+interface ISingleResponse<T> {
+  data: T;
 }
-
-type LoadUsersFn = (filter: IUserSelectFilter) => Observable<IListResponse<IUserBasicInfo>>;
 ```
 
-#### File Select Interfaces
+### IListResponse\<T\>
 
 ```typescript
-interface IFileBasicInfo {
-  id: string;
-  name: string;
-  contentType: string;
-  size: string;
-  url: string | null;
-}
-
-interface IFileUploadOptions {
-  storageConfigId?: string;
-  folderPath?: string;
-  maxWidth?: number;
-  maxHeight?: number;
-  quality?: number;
-  compress?: boolean;
-}
-
-interface IUploadedFile {
-  id?: string; // File manager ID (UUID) - available when registered
-  name: string;
-  key: string;
-  size: number;
-  contentType: string;
-}
-
-interface IFileSelectFilter {
+interface IListResponse<T> {
+  data: T[];
+  total: number;
   page: number;
   pageSize: number;
-  search: string;
-  contentTypes?: string[];
-  folderId?: string;
 }
-
-type LoadFilesFn = (filter: IFileSelectFilter) => Observable<IListResponse<IFileBasicInfo>>;
-type UploadFileFn = (file: File, options?: IFileUploadOptions) => Observable<ISingleResponse<IUploadedFile>>;
-type GetFileUrlsFn = (fileIds: string[]) => Observable<ISingleResponse<IFileBasicInfo[]>>;
 ```
 
-**File Type Filters (Constants):**
+### IBulkResponse\<T\>
 
 ```typescript
-import { FILE_TYPE_FILTERS, getAcceptString, isFileTypeAllowed, getFileIconClass, formatFileSize } from "@flusys/ng-shared";
-
-FILE_TYPE_FILTERS.IMAGES; // ['image/jpeg', 'image/png', 'image/gif', 'image/webp', 'image/svg+xml']
-FILE_TYPE_FILTERS.DOCUMENTS; // ['application/pdf', 'application/msword', ...]
-FILE_TYPE_FILTERS.VIDEOS; // ['video/mp4', 'video/webm', ...]
-FILE_TYPE_FILTERS.AUDIO; // ['audio/mpeg', 'audio/wav', ...]
-FILE_TYPE_FILTERS.ALL; // [] (allows all)
-
-getAcceptString(["image/*"]); // 'image/*'
-isFileTypeAllowed(file, ["image/*"]); // true/false
-getFileIconClass("image/png"); // 'pi pi-image'
-formatFileSize(1024); // '1 KB'
+interface IBulkResponse<T> {
+  data: T[];
+  successCount: number;
+  failureCount: number;
+  errors?: string[];
+}
 ```
 
-### Response Interfaces
-
-Type-safe interfaces matching FLUSYS_NEST backend response DTOs.
+### IMessageResponse
 
 ```typescript
-// Single item response (POST /resource/insert, /update, /get/:id)
-interface ISingleResponse<T> {
-  success: boolean;
-  message: string;
-  data?: T;
-  _meta?: IRequestMeta;
-}
-
-// List response with pagination (POST /resource/get-all)
-interface IListResponse<T> {
-  success: boolean;
-  message: string;
-  data?: T[];
-  meta: IPaginationMeta;
-  _meta?: IRequestMeta;
-}
-
-// Bulk operation response (POST /resource/insert-many, /update-many)
-interface IBulkResponse<T> {
-  success: boolean;
-  message: string;
-  data?: T[];
-  meta: IBulkMeta;
-  _meta?: IRequestMeta;
-}
-
-// Message-only response (POST /resource/delete, /logout)
 interface IMessageResponse {
-  success: boolean;
-  message: string;
-  _meta?: IRequestMeta;
-}
-
-// Error response (validation errors, exceptions)
-interface IErrorResponse {
-  success: false;
   message: string;
-  code?: string;
-  errors?: IValidationError[];
-  _meta?: IRequestMeta;
 }
-
-// Union type
-type ApiResponse<T> = ISingleResponse<T> | IListResponse<T> | IBulkResponse<T> | IMessageResponse | IErrorResponse;
 ```
 
-**Metadata types:**
-
-| Interface          | Fields                                                |
-| ------------------ | ----------------------------------------------------- |
-| `IRequestMeta`     | `requestId?, timestamp?, responseTime?`               |
-| `IPaginationMeta`  | `total, page, pageSize, count, hasMore?, totalPages?` |
-| `IBulkMeta`        | `count, failed?, total?`                              |
-| `IValidationError` | `field, message, constraint?`                         |
-
-### Auth & Storage Response Types
+### IErrorResponse
 
 ```typescript
-interface ILoginResponse {
-  success: boolean;
-  message: string;
-  data: { accessToken: string; refreshToken: string; user: ILoginUserData };
-}
-
-interface IRefreshTokenResponse {
-  success: boolean;
+interface IErrorResponse {
+  statusCode: number;
   message: string;
-  data: { accessToken: string; refreshToken?: string };
-}
-
-interface IFileData {
-  id: string;
-  name: string;
-  originalName: string;
-  contentType: string;
-  size: number;
-  key: string;
-  url?: string;
-  thumbnailUrl?: string;
-  createdAt: Date;
-}
-
-// File URL service response DTO
-interface FilesResponseDto {
-  id: string;
-  name: string;
-  contentType: string;
-  url: string | null;
+  error?: string;
 }
 ```
 
-### Permission Interfaces
-
-Discriminated union for building complex permission logic trees.
+### IListParams (Common Request Shape)
 
 ```typescript
-// Single permission check
-interface IActionNode {
-  type: "action";
-  actionId: string;
-}
-
-// Group with AND/OR logic
-interface IGroupNode {
-  type: "group";
-  operator: "AND" | "OR";
-  children: ILogicNode[];
+interface IListParams {
+  page?: number;
+  pageSize?: number;
+  search?: string;
+  sortBy?: string;
+  sortOrder?: 'ASC' | 'DESC';
+  filters?: Record<string, unknown>;
 }
-
-// Union type
-type ILogicNode = IActionNode | IGroupNode;
 ```
 
 ---
 
-## 2. Enums
+## Provider Interface Pattern
 
-```typescript
-enum ContactTypeEnum {
-  PHONE = 1,
-  EMAIL = 2,
-}
+Feature packages never import each other directly. Instead, `ng-shared` defines **injection token interfaces** that decouple consumers from providers.
 
-enum IconTypeEnum {
-  PRIMENG_ICON = 1,
-  IMAGE_FILE_LINK = 2,
-  DIRECT_TAG_SVG = 3,
-}
 ```
-
----
-
-## 3. Constants
-
-### Permission Constants
-
-Centralized permission codes for type-safe permission checks. Single source of truth to prevent typos.
-
-```typescript
-import { PERMISSIONS, USER_PERMISSIONS, ROLE_PERMISSIONS } from '@flusys/ng-shared';
-
-// Use constants instead of strings
-*hasPermission="PERMISSIONS.USER.READ"
-
-// Individual permission groups available:
-USER_PERMISSIONS     // { CREATE, READ, UPDATE, DELETE }
-COMPANY_PERMISSIONS  // { CREATE, READ, UPDATE, DELETE }
-BRANCH_PERMISSIONS   // { CREATE, READ, UPDATE, DELETE }
-ACTION_PERMISSIONS   // { CREATE, READ, UPDATE, DELETE }
-ROLE_PERMISSIONS     // { CREATE, READ, UPDATE, DELETE }
-ROLE_ACTION_PERMISSIONS   // { READ, ASSIGN }
-USER_ROLE_PERMISSIONS     // { READ, ASSIGN }
-USER_ACTION_PERMISSIONS   // { READ, ASSIGN }
-COMPANY_ACTION_PERMISSIONS // { READ, ASSIGN }
-FILE_PERMISSIONS     // { CREATE, READ, UPDATE, DELETE }
-FOLDER_PERMISSIONS   // { CREATE, READ, UPDATE, DELETE }
-STORAGE_CONFIG_PERMISSIONS  // { CREATE, READ, UPDATE, DELETE }
-EMAIL_CONFIG_PERMISSIONS    // { CREATE, READ, UPDATE, DELETE }
-EMAIL_TEMPLATE_PERMISSIONS  // { CREATE, READ, UPDATE, DELETE }
-FORM_PERMISSIONS     // { CREATE, READ, UPDATE, DELETE }
-
-// Aggregated object with all permissions
-PERMISSIONS.USER.READ     // 'user.read'
-PERMISSIONS.ROLE.CREATE   // 'role.create'
-PERMISSIONS.FILE.DELETE   // 'file.delete'
+ng-auth          ──implements──► USER_PROVIDER token  ◄──injects── ng-iam
+                 ──implements──► COMPANY_PROVIDER      ◄──injects── ng-storage
+ng-storage       ──implements──► FILE_PROVIDER         ◄──injects── ng-shared components
 ```
 
-**Type:** `PermissionCode` - Union type of all valid permission code strings.
-
----
-
-## 4. Services
-
-### ApiResourceService
+### Injection Tokens
 
-Signal-based CRUD service using Angular 21 `resource()` API with **lazy initialization**. All endpoints use POST (RPC-style).
+| 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` |
 
-**ServiceName Type:**
+### USER_PROVIDER
 
 ```typescript
-type ServiceName = "auth" | "administration" | "iam" | "storage" | "formBuilder" | "email";
-```
+interface IUserProvider {
+  user: Signal<ICurrentUser | null>;
+  isAuthenticated: Signal<boolean>;
+}
 
-**Define a service:**
+// Consuming (in ng-iam)
+import { USER_PROVIDER, IUserProvider } from '@flusys/ng-shared';
 
-```typescript
-import { Injectable } from "@angular/core";
-import { HttpClient } from "@angular/common/http";
-import { ApiResourceService } from "@flusys/ng-shared";
-
-@Injectable({ providedIn: "root" })
-export class UserService extends ApiResourceService<UserDto, IUser> {
-  constructor(http: HttpClient) {
-    // Option 1: Use global apiBaseUrl (default)
-    super("users", http);
-    // Base URL: APP_CONFIG.apiBaseUrl + '/users'
-
-    // Option 2: Use feature-specific service URL (recommended)
-    super("users", http, "administration");
-    // Base URL: APP_CONFIG.services.administration.baseUrl + '/users'
+@Injectable({ providedIn: 'root' })
+export class IamService {
+  private userProvider = inject<IUserProvider>(USER_PROVIDER);
+
+  getCurrentUserId(): string | null {
+    return this.userProvider.user()?.id ?? null;
   }
 }
 ```
 
-**Constructor Parameters:**
-
-| Parameter       | Type          | Required | Description                                      |
-| --------------- | ------------- | -------- | ------------------------------------------------ |
-| `moduleApiName` | `string`      | Yes      | API path segment (e.g., 'users', 'file-manager') |
-| `http`          | `HttpClient`  | Yes      | Angular HttpClient instance                      |
-| `serviceName`   | `ServiceName` | No       | Feature service name for URL resolution          |
-
-**Service URL Resolution:**
-
-- If `serviceName` is provided, uses `getServiceUrl(config, serviceName)` to resolve the base URL
-- Falls back to `APP_CONFIG.apiBaseUrl` if service not found or `serviceName` not provided
-
-**Lazy Initialization:**
-
-The list resource is **lazy-initialized** to avoid unnecessary HTTP requests on service construction. The resource is only created when first needed:
+### COMPANY_PROVIDER
 
 ```typescript
-// Resource is NOT created until one of these is called:
-userService.fetchList("", { pagination: { currentPage: 0, pageSize: 10 } });
-// OR
-userService.initListResource(); // Explicit initialization
+interface ICompanyProvider {
+  company: Signal<ICompany | null>;
+  branch: Signal<IBranch | null>;
+  companyId: Signal<string | null>;
+}
 ```
 
-**Internal resource structure:**
+### FILE_PROVIDER
 
 ```typescript
-private _listResource: ResourceRef<IListResponse<InterfaceT> | undefined> | null = null;
-private _resourceInitialized = false;
-private readonly _resourceInitSignal = signal(false);
-
-// Initialize the list resource (called automatically by fetchList)
-initListResource(): void {
-  if (this._resourceInitialized) return;
-  this._resourceInitialized = true;
-  this._resourceInitSignal.set(true);
-  // Creates the resource with linkedSignal for data, isLoading, etc.
+interface IFileProvider {
+  getFileUrl(fileId: string): Observable<string | null>;
+  uploadFile(file: File, folder?: string): Observable<IUploadedFile>;
 }
 ```
 
-**Endpoint mapping:**
+---
 
-| Method                   | HTTP | Endpoint                  | Response             |
-| ------------------------ | ---- | ------------------------- | -------------------- |
-| `insert(dto)`            | POST | `/{resource}/insert`      | `ISingleResponse<T>` |
-| `insertMany(dtos)`       | POST | `/{resource}/insert-many` | `IBulkResponse<T>`   |
-| `findById(id, select?)`  | POST | `/{resource}/get/:id`     | `ISingleResponse<T>` |
-| `getAll(search, filter)` | POST | `/{resource}/get-all?q=`  | `IListResponse<T>`   |
-| `update(dto)`            | POST | `/{resource}/update`      | `ISingleResponse<T>` |
-| `updateMany(dtos)`       | POST | `/{resource}/update-many` | `IBulkResponse<T>`   |
-| `delete(deleteDto)`      | POST | `/{resource}/delete`      | `IMessageResponse`   |
+## Base Classes
 
-All methods above return `Observable`. Async (Promise) variants are also available: `insertAsync`, `insertManyAsync`, `findByIdAsync`, `updateAsync`, `updateManyAsync`, `deleteAsync`.
+### ApiResourceService
 
-**Reactive signals:**
+Generic typed CRUD service that maps to FLUSYS POST-only RPC endpoints. Extend this to create a fully-typed API service in seconds.
 
-| Signal       | Type                          | Description             |
-| ------------ | ----------------------------- | ----------------------- |
-| `isLoading`  | `Signal<boolean>`             | Whether data is loading |
-| `data`       | `Signal<T[]>`                 | Current list data       |
-| `total`      | `Signal<number>`              | Total item count        |
-| `pageInfo`   | `Signal<IPaginationMeta>`     | Pagination metadata     |
-| `hasMore`    | `Signal<boolean>`             | More pages available    |
-| `searchTerm` | `WritableSignal<string>`      | Current search term     |
-| `filterData` | `WritableSignal<IFilterData>` | Filter/pagination state |
+```typescript
+import { ApiResourceService } from '@flusys/ng-shared';
 
-**List management:**
+@Injectable({ providedIn: 'root' })
+export class ProductApiService extends ApiResourceService<Product, CreateProductDto, UpdateProductDto> {
+  protected override resource = 'product';
+}
 
-```typescript
-// Trigger data fetch (updates searchTerm and filterData signals, resource auto-reloads)
-userService.fetchList("search term", { pagination: { currentPage: 0, pageSize: 10 } });
-
-// Pagination helpers
-userService.setPagination({ currentPage: 1, pageSize: 20 });
-userService.nextPage();
-userService.resetPagination();
-userService.reload();
+// 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>>
 ```
 
-**Component usage:**
+### BaseListPage
 
-```typescript
-@Component({...})
-export class UserListComponent {
-  private readonly userService = inject(UserService);
+Scaffold for list pages with built-in pagination, search, and loading state using signals.
 
-  readonly users = this.userService.data;           // Signal<IUser[]>
-  readonly isLoading = this.userService.isLoading;   // Signal<boolean>
-  readonly total = this.userService.total;           // Signal<number>
+```typescript
+import { BaseListPage } from '@flusys/ng-shared';
 
-  constructor() {
-    this.userService.fetchList('', { pagination: { currentPage: 0, pageSize: 10 } });
-  }
+@Component({
+  selector: 'app-product-list',
+  templateUrl: './product-list.component.html',
+})
+export class ProductListComponent extends BaseListPage<Product> {
+  protected apiService = inject(ProductApiService);
 
-  async createUser(dto: UserDto) {
-    await this.userService.insertAsync(dto);
-    this.userService.reload(); // Refresh list
-  }
+  // Inherited signals:
+  // items        Signal<Product[]>
+  // total        Signal<number>
+  // page         Signal<number>
+  // pageSize     Signal<number>
+  // isLoading    Signal<boolean>
+  // searchQuery  Signal<string>
 }
 ```
 
-> **Note:** `ApiService` is exported as an alias for `ApiResourceService` for backward compatibility.
-
-### FileUrlService
-
-Fetches file URLs from the backend. Supports presigned URLs for cloud storage (S3, Azure).
+### BaseFormPage
 
-**CRITICAL:** Never construct file URLs manually. Always use this service.
+Scaffold for create/edit forms with validation state and submission handling.
 
 ```typescript
-import { FileUrlService } from '@flusys/ng-shared';
-
-@Component({...})
-export class ProductComponent {
-  private readonly fileUrlService = inject(FileUrlService);
+import { BaseFormPage } from '@flusys/ng-shared';
 
-  loadImage(fileId: string) {
-    // Fetch from backend: POST /file-manager/get-files
-    this.fileUrlService.fetchSingleFileUrl(fileId).subscribe(file => {
-      this.imageUrl.set(file?.url ?? null);
-    });
-  }
+@Component({
+  selector: 'app-product-form',
+  templateUrl: './product-form.component.html',
+})
+export class ProductFormComponent extends BaseFormPage<Product> {
+  protected apiService = inject(ProductApiService);
 
-  loadMultiple(fileIds: string[]) {
-    this.fileUrlService.fetchFileUrls(fileIds).subscribe(files => {
-      // files: FilesResponseDto[] with { id, name, contentType, url }
-    });
-  }
+  // Inherited signals:
+  // isSaving     Signal<boolean>
+  // isEditMode   Signal<boolean>
+  // formErrors   Signal<Record<string, string>>
 }
 ```
 
-**Methods:**
+---
 
-| Method                       | Returns                                | Description                       |
-| ---------------------------- | -------------------------------------- | --------------------------------- |
-| `getFileUrl(fileId)`         | `string \| null`                       | Get cached URL (synchronous)      |
-| `fileUrlSignal(fileId)`      | `Signal<string \| null>`               | Computed signal from cache        |
-| `fetchFileUrls(fileIds[])`   | `Observable<FilesResponseDto[]>`       | Fetch from backend, updates cache |
-| `fetchSingleFileUrl(fileId)` | `Observable<FilesResponseDto \| null>` | Fetch single file                 |
-| `clearCache()`               | `void`                                 | Clear all cached URLs             |
-| `removeFromCache(fileId)`    | `void`                                 | Remove specific entry from cache  |
+## Services
 
-### PermissionValidatorService
+### FileUrlService
 
-Signal-based permission state management. Used by `HasPermissionDirective`, permission guards, and IAM. Supports **wildcard permissions**.
+**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.
 
 ```typescript
-import { PermissionValidatorService } from '@flusys/ng-shared';
-
-@Component({...})
-export class MyComponent {
-  private readonly permissionValidator = inject(PermissionValidatorService);
-
-  ngOnInit() {
-    // Set permissions (typically done by IAM PermissionStateService)
-    this.permissionValidator.setPermissions(['user.view', 'user.create']);
+import { FileUrlService } from '@flusys/ng-shared';
 
-    // Check single permission
-    if (this.permissionValidator.hasPermission('user.view')) {
-      // User has permission
-    }
+@Component({ ... })
+export class AvatarComponent {
+  private fileUrlService = inject(FileUrlService);
+  avatarUrl = signal<string | null>(null);
 
-    // Check loaded state (signal-based)
-    if (this.permissionValidator.isLoaded()) {
-      // Permissions have been loaded
-    }
+  async loadAvatar(fileId: string): Promise<void> {
+    const file = await this.fileUrlService.fetchSingleFileUrl(fileId);
+    this.avatarUrl.set(file?.url ?? null);
   }
 }
 ```
 
-**Methods:**
-
-| Method                    | Returns   | Description                                  |
-| ------------------------- | --------- | -------------------------------------------- |
-| `setPermissions(codes[])` | `void`    | Replace all permissions                      |
-| `clearPermissions()`      | `void`    | Clear all permissions                        |
-| `hasPermission(code)`     | `boolean` | Check single permission (supports wildcards) |
-| `isPermissionsLoaded()`   | `boolean` | **Deprecated** - Use `isLoaded()` signal     |
-
-**Signals:**
-
-| Signal        | Type               | Description                       |
-| ------------- | ------------------ | --------------------------------- |
-| `permissions` | `Signal<string[]>` | Readonly current permissions      |
-| `isLoaded`    | `Signal<boolean>`  | Whether permissions have been set |
-
-**Wildcard Support:**
-
-The `hasPermission()` method uses the permission evaluator utility which supports wildcards:
-
 ```typescript
-// Exact match
-hasPermission("user.read"); // true if permissions include 'user.read'
+// ❌ WRONG — never construct file URLs manually
+const url = `${apiBaseUrl}/storage/${fileId}`;
 
-// Global wildcard
-hasPermission("user.read"); // true if permissions include '*'
-
-// Module wildcard
-hasPermission("user.read"); // true if permissions include 'user.*'
+// ✅ CORRECT — always use FileUrlService
+const file = await this.fileUrlService.fetchSingleFileUrl(fileId);
+const url = file?.url ?? null;
 ```
 
-### CookieService
-
-SSR-aware cookie reading service.
-
-```typescript
-import { CookieService } from "@flusys/ng-shared";
+**Methods:**
 
-const cookies = inject(CookieService).get(); // Returns document.cookie (browser) or request header cookie (server)
-```
+| Method | Description |
+|--------|-------------|
+| `fetchSingleFileUrl(fileId)` | Fetch presigned URL for a single file |
+| `fetchMultipleFileUrls(fileIds)` | Batch fetch presigned URLs |
+| `clearCache(fileId?)` | Invalidate cached URL(s) |
 
-### PlatformService
+### PermissionValidatorService
 
-SSR environment detection service.
+Client-side permission evaluation without direct ng-iam dependency.
 
 ```typescript
-import { PlatformService } from "@flusys/ng-shared";
+import { PermissionValidatorService } from '@flusys/ng-shared';
+
+@Component({ ... })
+export class MyComponent {
+  private permValidator = inject(PermissionValidatorService);
 
-const platform = inject(PlatformService);
-if (!platform.isServer) {
-  // Browser-only code (localStorage, window, etc.)
+  canEdit = computed(() =>
+    this.permValidator.hasPermission('product:update')
+  );
 }
 ```
 
 ---
 
-## 5. Components
-
-### IconComponent
+## Reusable Components
 
-Flexible icon renderer supporting PrimeNG icons, image files, and SVG.
+### LazySelectComponent
 
-- **Selector:** `lib-icon`
-- **Inputs:** `icon` (required string), `iconType` (optional `IconTypeEnum`, default: `PRIMENG_ICON`)
+Virtualized dropdown with server-side search. Ideal for large datasets.
 
 ```html
-<!-- PrimeNG icon (default) -->
-<lib-icon icon="pi pi-user" />
-
-<!-- Image file -->
-<lib-icon icon="/assets/logo.png" [iconType]="IconTypeEnum.IMAGE_FILE_LINK" />
-
-<!-- SVG tag (shows fallback icon - full SVG rendering coming soon) -->
-<lib-icon icon="<svg>...</svg>" [iconType]="IconTypeEnum.DIRECT_TAG_SVG" />
+<flusys-lazy-select
+  [apiService]="productApiService"
+  [labelField]="'name'"
+  [valueField]="'id'"
+  [(ngModel)]="selectedProductId"
+  placeholder="Search products..."
+/>
 ```
 
-### LazySelectComponent
-
-Single-select dropdown with lazy loading, search, and scroll pagination.
+### FileSelectorDialogComponent
 
-- **Selector:** `lib-lazy-select`
-- **Extends:** `BaseFormControl<string | null>`
-- **Supports:** Template-driven, reactive forms, signal forms
+File picker dialog that integrates with `@flusys/ng-storage`.
 
-```typescript
-@Component({
-  imports: [LazySelectComponent],
-  template: ` <lib-lazy-select [(value)]="selectedId" [selectDataList]="items()" [optionLabel]="'label'" [optionValue]="'value'" [isEditMode]="true" [isLoading]="loading()" [total]="total()" [pagination]="pagination()" [placeHolder]="'Select item'" (onSearch)="handleSearch($event)" (onPagination)="handlePagination($event)" /> `,
-})
-export class MyComponent {
-  readonly selectedId = signal<string | null>(null);
-  readonly items = signal<IDropDown[]>([]);
-  readonly loading = signal(false);
-  readonly total = signal<number | undefined>(undefined);
-  readonly pagination = signal<IPagination>({ currentPage: 0, pageSize: 20 });
-}
+```html
+<flusys-file-selector
+  [accept]="'image/*'"
+  [maxSize]="5242880"
+  (fileSelected)="onFileSelected($event)"
+/>
 ```
 
-**Inputs:**
+---
 
-| Input            | Type                  | Description                                   |
-| ---------------- | --------------------- | --------------------------------------------- |
-| `selectDataList` | `Array<IDropDown>`    | Dropdown options (required)                   |
-| `optionLabel`    | `string`              | Label field name (required)                   |
-| `optionValue`    | `string`              | Value field name (required)                   |
-| `isEditMode`     | `boolean`             | Enable/disable editing (required)             |
-| `isLoading`      | `boolean`             | Loading state (required)                      |
-| `total`          | `number \| undefined` | Total items for pagination                    |
-| `pagination`     | `IPagination`         | Current pagination state                      |
-| `placeHolder`    | `string`              | Placeholder text (default: `'Select Option'`) |
+## Directives
 
-**Model:** `value` - Two-way bound selected value (`string | null`)
+### HasPermissionDirective
 
-**Outputs:** `onSearch` (debounced 500ms), `onPagination` (scroll-triggered)
+Structural directive that removes elements from the DOM if the user lacks the required permission:
 
-### LazyMultiSelectComponent
+```html
+<!-- Single permission -->
+<button *hasPermission="'product:delete'">Delete</button>
 
-Multi-select dropdown with lazy loading, search, select-all, and scroll pagination.
+<!-- Multiple permissions (AND logic) -->
+<div *hasPermission="['product:update', 'product:read']">Edit Panel</div>
 
-- **Selector:** `lib-lazy-multi-select`
-- **Extends:** `BaseFormControl<string[] | null>`
-- **Supports:** Template-driven, reactive forms, signal forms
+<!-- OR logic -->
+<div *hasPermission="'product:update'" [permissionOr]="true">Edit Panel</div>
 
-```typescript
-@Component({
-  imports: [LazyMultiSelectComponent],
-  template: ` <lib-lazy-multi-select [(value)]="selectedIds" [selectDataList]="items()" [isEditMode]="true" [isLoading]="loading()" [total]="total()" [pagination]="pagination()" [placeHolder]="'Select items'" (onSearch)="handleSearch($event)" (onPagination)="handlePagination($event)" /> `,
-})
-export class MyComponent {
-  readonly selectedIds = signal<string[] | null>(null);
-}
+<!-- Show fallback content -->
+<button *hasPermission="'admin:manage'; else noAccess">Admin</button>
+<ng-template #noAccess>
+  <span>No access</span>
+</ng-template>
 ```
 
-**Inputs:** `selectDataList`, `isEditMode`, `isLoading`, `total`, `pagination`, `placeHolder` (same as `LazySelectComponent`). Does not have `optionLabel`/`optionValue` (uses `IDropDown.label`/`IDropDown.value` directly).
-
-**Model:** `value` - Two-way bound selected values (`string[] | null`)
+---
 
-**Computed signals:** `selectedValueDisplay` (display text), `isSelectAll` (all items selected)
+## Pipes
 
-### UserSelectComponent
+### TranslatePipe
 
-Single user selection with lazy loading. Uses `USER_PROVIDER` internally or accepts custom `loadUsers` function.
+Translate i18n keys with optional parameter interpolation:
 
-- **Selector:** `lib-user-select`
-- **Supports:** Template-driven, reactive forms, signal forms
+```html
+<!-- Basic translation -->
+<span>{{ 'common.save' | translate }}</span>
 
-```typescript
-@Component({
-  imports: [UserSelectComponent],
-  template: `
-    <!-- Simple usage - uses USER_PROVIDER internally -->
-    <lib-user-select [(value)]="selectedUserId" [isEditMode]="true" />
-
-    <!-- With custom loadUsers function -->
-    <lib-user-select [(value)]="selectedUserId" [isEditMode]="true" [loadUsers]="customLoadUsers" />
-  `,
-})
-export class MyComponent {
-  readonly selectedUserId = signal<string | null>(null);
-}
+<!-- With parameters -->
+<span>{{ 'pagination.showing' | translate: { from: 1, to: 10, total: 100 } }}</span>
 ```
 
-**Inputs:**
-
-| Input               | Type                      | Default         | Description                  |
-| ------------------- | ------------------------- | --------------- | ---------------------------- |
-| `isEditMode`        | `boolean`                 | required        | Enable/disable editing       |
-| `placeHolder`       | `string`                  | `'Select User'` | Placeholder text             |
-| `filterActive`      | `boolean`                 | `true`          | Filter active users only     |
-| `additionalFilters` | `Record<string, unknown>` | `{}`            | Extra filter params          |
-| `pageSize`          | `number`                  | `20`            | Page size for pagination     |
-| `loadUsers`         | `LoadUsersFn`             | -               | Custom user loading function |
-
-**Model:** `value` - Two-way bound selected user ID (`string | null`)
+The pipe automatically subscribes to language change events and re-renders on switch.
 
-**Outputs:** `userSelected` (IUserBasicInfo | null), `onError` (Error)
-
-### UserMultiSelectComponent
+---
 
-Multiple user selection with lazy loading. Uses `USER_PROVIDER` internally or accepts custom `loadUsers` function.
+## Guards
 
-- **Selector:** `lib-user-multi-select`
-- **Supports:** Template-driven, reactive forms, signal forms
+| 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 |
 
 ```typescript
-@Component({
-  imports: [UserMultiSelectComponent],
-  template: ` <lib-user-multi-select [(value)]="selectedUserIds" [isEditMode]="true" /> `,
-})
-export class MyComponent {
-  readonly selectedUserIds = signal<string[] | null>(null);
-}
+// app.routes.ts
+export const routes: Routes = [
+  {
+    path: 'products',
+    canActivate: [AuthenticatedGuard],
+    loadComponent: () => import('./pages/product-list.component'),
+  },
+  {
+    path: 'admin',
+    canActivate: [PermissionGuard],
+    data: { permission: 'admin:manage' },
+    loadComponent: () => import('./pages/admin.component'),
+  },
+];
 ```
 
-**Inputs:** Same as `UserSelectComponent`.
-
-**Model:** `value` - Two-way bound selected user IDs (`string[] | null`)
-
-**Outputs:** `usersSelected` (IUserBasicInfo[]), `onError` (Error)
+---
 
-### FileUploaderComponent
+## Modules
 
-Drag & drop file upload with type filtering. Pass your own `uploadFile` function.
+### AngularModule
 
-- **Selector:** `lib-file-uploader`
+Pre-aggregated Angular common imports for use in components:
 
 ```typescript
+import { AngularModule } from '@flusys/ng-shared';
+
 @Component({
-  imports: [FileUploaderComponent],
-  template: `
-    <!-- Single image upload -->
-    <lib-file-uploader [uploadFile]="uploadFile" [acceptTypes]="['image/*']" [multiple]="false" (fileUploaded)="onFileUploaded($event)" />
-
-    <!-- Multiple document upload -->
-    <lib-file-uploader [uploadFile]="uploadFile" [acceptTypes]="FILE_TYPE_FILTERS.DOCUMENTS" [multiple]="true" [maxFiles]="5" (filesUploaded)="onFilesUploaded($event)" />
-  `,
+  imports: [AngularModule],
+  // Includes: CommonModule, FormsModule, ReactiveFormsModule, RouterModule, etc.
 })
-export class MyComponent {
-  readonly uploadService = inject(UploadService);
-
-  readonly uploadFile: UploadFileFn = (file, options) => this.uploadService.uploadSingleFile(file, options);
-}
+export class MyComponent {}
 ```
 
-**Inputs:**
-
-| Input           | Type                 | Default  | Description                     |
-| --------------- | -------------------- | -------- | ------------------------------- |
-| `uploadFile`    | `UploadFileFn`       | required | Upload function                 |
-| `acceptTypes`   | `string[]`           | `[]`     | Allowed MIME types              |
-| `multiple`      | `boolean`            | `false`  | Allow multiple files            |
-| `maxFiles`      | `number`             | `10`     | Max files for multiple          |
-| `maxSizeMb`     | `number`             | `10`     | Max file size in MB             |
-| `uploadOptions` | `IFileUploadOptions` | `{}`     | Upload options                  |
-| `disabled`      | `boolean`            | `false`  | Disable uploader                |
-| `showPreview`   | `boolean`            | `true`   | Show selected files preview     |
-| `autoUpload`    | `boolean`            | `true`   | Upload immediately on selection |
-
-**Outputs:** `fileUploaded` (IUploadedFile), `filesUploaded` (IUploadedFile[]), `onError` (Error), `fileSelected` (File[])
-
-### FileSelectorDialogComponent
-
-Dialog to browse and select existing files with filtering.
+### PrimeModule
 
-- **Selector:** `lib-file-selector-dialog`
+Pre-aggregated PrimeNG component imports:
 
 ```typescript
+import { PrimeModule } from '@flusys/ng-shared';
+
 @Component({
-  imports: [FileSelectorDialogComponent],
-  template: ` <lib-file-selector-dialog [(visible)]="showFileSelector" [loadFiles]="loadFiles" [acceptTypes]="['image/*']" [multiple]="false" (fileSelected)="onFileSelected($event)" /> `,
+  imports: [PrimeModule],
+  // Includes: ButtonModule, TableModule, DialogModule, InputTextModule, etc.
 })
-export class MyComponent {
-  readonly showFileSelector = signal(false);
-  readonly fileService = inject(FileManagerApiService);
-
-  readonly loadFiles: LoadFilesFn = (filter) =>
-    this.fileService.getAll(filter.search, {
-      pagination: { currentPage: filter.page, pageSize: filter.pageSize },
-    });
-}
+export class MyComponent {}
 ```
 
-**Inputs:**
-
-| Input          | Type          | Default         | Description              |
-| -------------- | ------------- | --------------- | ------------------------ |
-| `loadFiles`    | `LoadFilesFn` | required        | File loading function    |
-| `header`       | `string`      | `'Select File'` | Dialog header            |
-| `acceptTypes`  | `string[]`    | `[]`            | Allowed MIME types       |
-| `multiple`     | `boolean`     | `false`         | Allow multiple selection |
-| `maxSelection` | `number`      | `10`            | Max files for multiple   |
-| `pageSize`     | `number`      | `20`            | Page size for pagination |
-
-**Model:** `visible` - Two-way bound dialog visibility (`boolean`)
-
-**Outputs:** `fileSelected` (IFileBasicInfo), `filesSelected` (IFileBasicInfo[]), `closed` (void), `onError` (Error)
-
 ---
 
-## 6. Directives
-
-### HasPermissionDirective
+## Troubleshooting
 
-Structural directive for permission-based rendering. Fail-closed: hides content when permissions not loaded.
+**`No provider for USER_PROVIDER`**
 
-- **Selector:** `[hasPermission]`
-- **Input:** `hasPermission` - `string | ILogicNode | null`
+You need to register the auth providers in `app.config.ts`:
 
 ```typescript
-import { HasPermissionDirective, ILogicNode } from "@flusys/ng-shared";
-
-@Component({
-  imports: [HasPermissionDirective],
-  template: `
-    <!-- Simple permission check -->
-    <button *hasPermission="'user.create'">Create User</button>
-
-    <!-- Complex AND/OR logic -->
-    <div *hasPermission="editLogic">Edit Panel</div>
-  `,
-})
-export class MyComponent {
-  readonly editLogic: ILogicNode = {
-    type: "group",
-    operator: "AND",
-    children: [
-      { type: "action", actionId: "user.view" },
-      { type: "action", actionId: "user.update" },
-    ],
-  };
-}
-```
-
-### EditModeElementChangerDirective
-
-Toggles readonly/disabled state for form controls based on edit mode. Supports `<input>`, `<p-select>`, and `<p-calendar>`.
-
-- **Selector:** `[appEditModeElementChanger]`
-- **Input:** `isEditMode` (required boolean)
+import { provideAuthProviders } from '@flusys/ng-auth';
 
-```html
-<input [appEditModeElementChanger] [isEditMode]="isEditing()" /> <p-select [appEditModeElementChanger] [isEditMode]="isEditing()" />
+providers: [
+  ...provideAuthProviders(),
+]
 ```
 
-### IsEmptyImageDirective
+**`FileUrlService returns null for valid fileId`**
 
-Automatically replaces broken or empty image `src` with a default fallback image.
+The file may not exist or the storage module isn't registered:
 
-- **Selector:** `img` (applies to all `<img>` elements)
-- **Input:** `src` (standard img src)
-- **Default image:** `lib/assets/images/default/default-image.jpg`
-
-```html
-<img [src]="imageUrl()" alt="Product" />
-<!-- Falls back to default image on error or empty src -->
+```typescript
+// Ensure storage is enabled in APP_CONFIG
+services: {
+  storage: { enabled: true }
+}
 ```
 
-### PreventDefaultDirective
+**`TranslatePipe shows raw key (e.g., "common.save")`**
 
-Prevents default browser behavior on specified events and emits the event.
+Localization isn't initialized or the key doesn't exist in translation files. Provide `TRANSLATE_ADAPTER` in `app.config.ts` via `provideLocalization()`.
 
-- **Selector:** `[appPreventDefault]`
-- **Inputs:** `eventType` (`'click' | 'keydown' | 'keyup'`, default: `'click'`), `preventKey` (optional key filter)
-- **Output:** `action` - Emits the prevented event
+**`HasPermissionDirective always hides content`**
 
-```html
-<a href="#" appPreventDefault (action)="handleClick($event)">Click me</a> <input appPreventDefault eventType="keydown" preventKey="Enter" (action)="onEnter($event)" />
-```
+`PermissionValidatorService` has no data — ensure `ng-iam` is enabled and permissions are loaded after login.
 
 ---
 
-## 7. Guards
-
-Route-level guards for permission-based access control. All guards deny access when permissions are not loaded (fail-closed).
-
-### permissionGuard
-
-Single permission or complex logic check.
-
-```typescript
-import { permissionGuard } from "@flusys/ng-shared";
-
-const routes: Routes = [
-  // Simple permission
-  { path: "users", canActivate: [permissionGuard("user.view")] },
-
-  // Complex logic (ILogicNode)
-  {
-    path: "admin",
-    canActivate: [
-      permissionGuard({
-        type: "group",
-        operator: "AND",
-        children: [
-          { type: "action", actionId: "admin.view" },
-          { type: "action", actionId: "admin.manage" },
-        ],
-      }),
-    ],
-  },
-
-  // Custom redirect on deny
-  { path: "settings", canActivate: [permissionGuard("settings.view", "/access-denied")] },
-];
-```
-
-### anyPermissionGuard
-
-OR logic - allows access if user has ANY of the specified permissions.
-
-```typescript
-{ path: 'reports', canActivate: [anyPermissionGuard(['report.view', 'report.export'])] }
-```
-
-### allPermissionsGuard
-
-AND logic - allows access only if user has ALL specified permissions.
-
-```typescript
-{ path: 'admin', canActivate: [allPermissionsGuard(['admin.view', 'admin.manage'])] }
-```
-
----
-
-## 8. Utilities
-
-### Permission Evaluator
-
-Pure functions for permission logic evaluation. Used internally by `HasPermissionDirective` and guards. **Supports wildcard permissions.**
-
-```typescript
-import { evaluatePermission, evaluateLogicNode, hasAnyPermission, hasAllPermissions, hasPermission } from "@flusys/ng-shared";
-
-const userPermissions = ["user.view", "user.create", "admin.*"];
-
-// Low-level hasPermission check with wildcard support
-hasPermission("user.view", userPermissions); // true (exact match)
-hasPermission("admin.manage", userPermissions); // true (matches 'admin.*')
-hasPermission("settings.view", ["*"]); // true (global wildcard)
-
-// Evaluate string or ILogicNode
-evaluatePermission("user.view", userPermissions); // true
-evaluatePermission(null, userPermissions); // false
-
-// Evaluate ILogicNode tree recursively
-evaluateLogicNode(logicNode, userPermissions);
-
-// Simple OR/AND checks (also support wildcards)
-hasAnyPermission(["user.view", "user.delete"], userPermissions); // true (has user.view)
-hasAllPermissions(["user.view", "user.delete"], userPermissions); // false (missing user.delete)
-```
-
-**Wildcard Rules:**
-
-| Pattern     | Matches                                 |
-| ----------- | --------------------------------------- |
-| `*`         | All permissions (global wildcard)       |
-| `module.*`  | All permissions starting with `module.` |
-| `user.read` | Exact match only                        |
-
-**Implementation Details:**
-
-```typescript
-export function hasPermission(requiredPermission: string, userPermissions: string[]): boolean {
-  // Exact match
-  if (userPermissions.includes(requiredPermission)) return true;
-
-  // Wildcard matching
-  for (const permission of userPermissions) {
-    // Global wildcard
-    if (permission === "*") return true;
-
-    // Module wildcard (e.g., 'user.*' matches 'user.read')
-    if (permission.endsWith(".*")) {
-      const prefix = permission.slice(0, -1); // 'user.'
-      if (requiredPermission.startsWith(prefix)) return true;
-    }
-  }
-
-  return false;
-}
-```
-
-### Scroll Pagination
-
-Utility for lazy-loading dropdowns with scroll detection.
-
-```typescript
-import { checkScrollPagination, ScrollPaginationConfig } from '@flusys/ng-shared';
-
-// In a component
-onScroll(event: Event): void {
-  const nextPagination = checkScrollPagination(event, {
-    pagination: this.pagination(),
-    total: this.total(),
-    isLoading: this.isLoading(),
-    threshold: 50, // pixels from bottom (default: 50)
-  });
-  if (nextPagination) {
-    this.onPagination.emit(nextPagination);
-  }
-}
-```
-
-**Interface:** `ScrollPaginationConfig` - `{ threshold?, pagination, total, isLoading }`
-
-**Returns:** `IPagination | null` - Next page pagination or null if not needed.
-
----
-
-## 9. Classes
-
-### BaseFormControl
-
-Abstract base class for custom form controls. Implements both `ControlValueAccessor` (reactive forms) and `FormValueControl` (signal forms).
-
-```typescript
-import { BaseFormControl, provideValueAccessor } from "@flusys/ng-shared";
-
-@Component({
-  selector: "my-select",
-  providers: [provideValueAccessor(MySelectComponent)],
-})
-export class MySelectComponent extends BaseFormControl<string | null> {
-  override readonly value = model<string | null>(null);
-
-  constructor() {
-    super();
-    this.initializeFormControl(); // Required for ControlValueAccessor sync
-  }
-}
-
-// Usage in all form patterns:
-// Template-driven: <my-select [(value)]="selectedId" />
-// Reactive forms:  <my-select [formControl]="myControl" />
-// Signal forms:    <my-select [formField]="formTree.myField" />
-```
-
-**Abstract property:** `value: ModelSignal<T>` - Must override with `model<T>()`
-
-**Models:** `disabled` (boolean), `touched` (boolean)
-
-**Methods:** `initializeFormControl()` (call in constructor), `markAsTouched()` (call on blur)
-
-**Helper:** `provideValueAccessor(ComponentClass)` - Factory for `NG_VALUE_ACCESSOR` provider
-
-### BaseFormPage
-
-Abstract directive for form page components (create/edit).
-
-```typescript
-import { BaseFormPage } from '@flusys/ng-shared';
-
-@Component({ ... })
-export class ProductFormComponent extends BaseFormPage<IProduct, IProductFormModel> {
-  private readonly productService = inject(ProductApiService);
-  private readonly _formModel = signal<IProductFormModel>({ name: '', price: 0 });
-  readonly formModel = this._formModel.asReadonly();
-
-  getFormModel(): Signal<IProductFormModel> { return this.formModel; }
-  getResourceRoute(): string { return '/products'; }
-  getResourceName(): string { return 'Product'; }
-  isFormValid(): boolean { return this.formModel().name.trim().length > 0; }
-
-  loadItem(id: string): void {
-    this.productService.findById(id).subscribe(res => {
-      if (res.success && res.data) {
-        this.existingItem.set(res.data);
-        this._formModel.set({ name: res.data.name, price: res.data.price });
-      }
-    });
-  }
-
-  createItem(model: IProductFormModel): Observable<unknown> {
-    return this.productService.insert(model);
-  }
-
-  updateItem(model: IProductFormModel): Observable<unknown> {
-    return this.productService.update({ id: this.existingItem()!.id, ...model });
-  }
-}
-```
-
-**Signals:** `isLoading`, `existingItem`, `isEditMode` (computed)
-
-**Methods:** `onSubmit()`, `onCancel()`, `showSuccess()`, `showError()`, `showValidationError()`
-
-### BaseListPage
-
-Abstract directive for list page components with pagination and CRUD operations.
-
-```typescript
-import { BaseListPage } from '@flusys/ng-shared';
-
-@Component({ ... })
-export class UserListComponent extends BaseListPage<IUser> {
-  private readonly userService = inject(UserApiService);
-
-  getResourceRoute(): string { return '/users'; }
-  getDeleteConfirmMessage(user: IUser): string { return `Delete "${user.name}"?`; }
-
-  async loadData(): Promise<void> {
-    this.isLoading.set(true);
-    const res = await this.userService.findByIdAsync(...);
-    this.items.set(res.data ?? []);
-    this.total.set(res.meta?.total ?? 0);
-    this.isLoading.set(false);
-  }
-}
-```
-
-**Signals:** `items`, `isLoading`, `total`, `pageSize`, `first`, `currentPage` (computed), `showCompanyInfo` (computed)
-
-**Methods:** `onCreate()`, `onEdit(id)`, `onPageChange(event)`, `onDelete()`, `onDeleteAsync()`, `showSuccess()`, `showError()`, `showInfo()`, `showWarn()`
-
----
-
-## 10. Modules
-
-### AngularModule
-
-Re-exports common Angular modules for convenience.
-
-```typescript
-import { AngularModule } from "@flusys/ng-shared";
-// Includes: CommonModule, FormsModule, ReactiveFormsModule, RouterLink, RouterOutlet,
-// RouterLinkActive, NgOptimizedImage, NgComponentOutlet, + directives (IsEmptyImageDirective, PreventDefaultDirective)
-// Providers: DatePipe
-```
-
-### PrimeModule
-
-Re-exports PrimeNG component modules for convenience.
-
-```typescript
-import { PrimeModule } from "@flusys/ng-shared";
-// Includes 30 modules:
-// - Layout: AccordionModule, CardModule, DividerModule, PanelModule, SplitterModule, TabsModule, ToolbarModule
-// - Form: AutoCompleteModule, CheckboxModule, DatePickerModule, InputTextModule, InputTextareaModule,
-//         MultiSelectModule, RadioButtonModule, SelectModule, ToggleSwitchModule
-// - Button: ButtonModule, SpeedDialModule, SplitButtonModule
-// - Data: PaginatorModule, TableModule, TreeTableModule
-// - Overlay: DialogModule, DrawerModule, PopoverModule, TooltipModule
-// - File: FileUploadModule
-// - Media: ImageModule
-// - Misc: BadgeModule, TagModule
-```
-
----
-
-## 11. Provider Interfaces (Package Independence)
-
-ng-shared defines **provider interfaces** to enable feature packages (ng-iam, ng-storage) to access auth functionality without direct dependencies.
-
-### Architecture
-
-```
-ng-shared (defines interfaces + tokens)
-    |
-ng-auth (implements interfaces with adapters)
-    |
-ng-iam/ng-storage (consume interfaces via DI)
-```
-
-### Available Providers
-
-#### IUserProvider / `USER_PROVIDER`
-
-User list access for IAM user selection.
-
-```typescript
-interface IUserBasicInfo {
-  id: string;
-  name: string;
-  email: string;
-}
-
-interface IUserProvider {
-  getUsers(filter?: { page?: number; pageSize?: number; search?: string; companyId?: string; branchId?: string }): Observable<IListResponse<IUserBasicInfo>>;
-}
-```
-
-**Token Error Message:** `'USER_PROVIDER not configured. Please provide an implementation in app.config.ts'`
-
-#### ICompanyApiProvider / `COMPANY_API_PROVIDER`
-
-Company list access for IAM company selection.
-
-```typescript
-interface ICompanyBasicInfo {
-  id: string;
-  name: string;
-  slug?: string;
-}
-
-interface ICompanyApiProvider {
-  getCompanies(filter?: { page?: number; pageSize?: number; search?: string }): Observable<IListResponse<ICompanyBasicInfo>>;
-}
-```
-
-**Token Error Message:** `'COMPANY_API_PROVIDER not configured. Please provide an implementation in app.config.ts'`
-
-#### IUserPermissionProvider / `USER_PERMISSION_PROVIDER`
-
-User permission queries for IAM.
-
-```typescript
-interface IUserBranchPermission {
-  branchId: string;
-  branchName: string;
-  permissions: string[];
-}
-
-interface IUserPermissionProvider {
-  getUserBranchPermissions(userId: string): Observable<ISingleResponse<IUserBranchPermission[]>>;
-}
-```
-
-**Token Error Message:** `'USER_PERMISSION_PROVIDER not configured. Please provide an implementation in app.config.ts'`
-
-#### IFileProvider / `FILE_PROVIDER`
-
-File operations provider for file selection and upload. Implemented by ng-storage. **Optional token** - use with `inject(..., { optional: true })`.
-
-```typescript
-interface IFileProvider {
-  loadFiles(filter: IFileSelectFilter): Observable<IListResponse<IFileBasicInfo>>;
-  uploadFile(file: File, options?: IFileUploadOptions): Observable<ISingleResponse<IUploadedFile>>;
-  uploadMultipleFiles?(files: File[], options?: IFileUploadOptions): Observable<ISingleResponse<IUploadedFile[]>>;
-  getFileUrls?(fileIds: string[]): Observable<ISingleResponse<IFileBasicInfo[]>>;
-  loadFolders?(filter: ISelectFilter): Observable<IListResponse<IFolderBasicInfo>>;
-  loadStorageConfigs?(filter: ISelectFilter): Observable<IListResponse<IStorageConfigBasicInfo>>;
-}
-```
-
-#### IProfilePermissionProvider / `PROFILE_PERMISSION_PROVIDER`
-
-User permission queries for ng-auth profile page. Implemented by ng-iam. **Optional token** - use with `inject(..., { optional: true })`.
-
-```typescript
-interface IProfileRoleInfo {
-  id: string;
-  name: string;
-  description?: string | null;
-}
-
-interface IProfileActionInfo {
-  id: string;
-  code: string;
-  name: string;
-  description?: string | null;
-}
-
-interface IProfilePermissionProvider {
-  getUserRoles(userId: string, branchId?: string): Observable<ISingleResponse<IProfileRoleInfo[]>>;
-  getUserActions(userId: string, branchId?: string): Observable<ISingleResponse<IProfileActionInfo[]>>;
-}
-```
-
-#### IAuthStateProvider / `AUTH_STATE_PROVIDER`
-
-Auth state access for feature packages (form-builder, etc.) that need to check authentication without depending on ng-auth directly.
-
-```typescript
-interface IAuthStateProvider {
-  /** Signal indicating if user is currently authenticated */
-  isAuthenticated: Signal<boolean>;
-
-  /** Initialize auth state (restore session from cookies/storage) */
-  initialize(): Observable<void>;
-}
-```
-
-**Token Error Message:** `'AUTH_STATE_PROVIDER not configured. Please provide an implementation in app.config.ts'`
-
-**Usage:**
-
-```typescript
-import { AUTH_STATE_PROVIDER } from '@flusys/ng-shared';
-
-@Component({...})
-export class PublicFormComponent {
-  private readonly authState = inject(AUTH_STATE_PROVIDER);
-
-  ngOnInit() {
-    this.authState.initialize().subscribe(() => {
-      if (this.authState.isAuthenticated()) {
-        // User is logged in
-      }
-    });
-  }
-}
-```
-
-#### IUserListProvider / `USER_LIST_PROVIDER`
-
-Extends user list pages with extra columns, actions, and data enrichment. **Optional token** - use with `inject(..., { optional: true })`.
-
-```typescript
-interface IUserListItem {
-  id: string;
-  name: string;
-  email: string;
-  phone?: string;
-  isActive?: boolean;
-}
-
-interface IUserListAction<T = IUserListItem> {
-  id: string;
-  label: string;
-  icon?: string;
-  severity?: "primary" | "secondary" | "success" | "info" | "warn" | "danger";
-  permission?: string;
-  tooltip?: string;
-  disabled?: boolean | ((user: T) => boolean);
-  visible?: boolean | ((user: T) => boolean);
-}
-
-interface IUserListColumn {
-  field: string;
-  header: string;
-  width?: string;
-  sortable?: boolean;
-  templateType?: "text" | "badge" | "date" | "boolean" | "custom";
-}
-
-interface IUserListFilter {
-  page?: number;
-  pageSize?: number;
-  search?: string;
-  isActive?: boolean;
-  companyId?: string;
-  branchId?: string;
-}
-
-interface IUserListProvider<T extends IUserListItem = IUserListItem> {
-  getExtraColumns?(): IUserListColumn[];
-  getExtraRowActions?(): IUserListAction<T>[];
-  getExtraToolbarActions?(): IUserListAction<T>[];
-  onRowAction?(actionId: string, user: T): void;
-  onToolbarAction?(actionId: string, selectedUsers: T[]): void;
-  enrichListData?(users: T[]): Observable<T[]>;
-}
-```
-
-**Usage:**
-
-```typescript
-// In app.config.ts
-providers: [{ provide: USER_LIST_PROVIDER, useClass: MyUserListProvider }];
-
-// Implementation
-@Injectable({ providedIn: "root" })
-export class MyUserListProvider implements IUserListProvider {
-  getExtraRowActions() {
-    return [{ id: "assign-role", label: "Assign Role", icon: "pi pi-users" }];
-  }
-}
-```
-
-### Usage in Consuming Packages
-
-```typescript
-import { USER_PROVIDER } from "@flusys/ng-shared";
-
-export class UserSelectorComponent {
-  private readonly userProvider = inject(USER_PROVIDER);
-
-  loadUsers() {
-    this.userProvider.getUsers({ page: 0, pageSize: 50 }).subscribe((response) => {
-      this.users.set(response.data ?? []);
-    });
-  }
-}
-```
-
-### Wiring in App
-
-```typescript
-// app.config.ts
-import { provideAuthProviders } from "@flusys/ng-auth";
-
-export const appConfig: ApplicationConfig = {
-  providers: [
-    ...provideAuthProviders(), // Registers all auth adapters for provider tokens
-  ],
-};
-```
-
-### See Also
-
-- [AUTH-GUIDE.md](AUTH-GUIDE.md) - Adapter implementations
-- [IAM-GUIDE.md](IAM-GUIDE.md) - IAM usage examples
-- [../CLAUDE.md](../CLAUDE.md) - Complete pattern documentation
-
----
-
-## Best Practices
-
-### API Services
-
-- **Extend `ApiResourceService`** for new services (signal-based)
-- Use reactive signals (`data`, `isLoading`, `total`) in templates
-- Use `fetchList()` to trigger queries (also initializes resource), `reload()` to refresh
-- Use async methods (`insertAsync`, `updateAsync`) for one-off operations
-- Resource is lazy-initialized - no HTTP requests until first `fetchList()` or `initListResource()`
-
-### File URLs
-
-- **Always use `FileUrlService`** - never construct URLs manually
-- Use `fetchSingleFileUrl()` for one-off fetches, `fetchFileUrls()` for batches
-- Use `fileUrlSignal()` for reactive template bindings
-
-### Components
-
-- Use `AngularModule` and `PrimeModule` for common imports
-- Use signal inputs via `input()` and `input.required()`
-- Components use `lib-` prefix for selectors
-
-### Directives
-
-- Directives use `app` prefix for selectors (`appPreventDefault`, `appEditModeElementChanger`)
-- Exception: `HasPermissionDirective` uses `[hasPermission]`
-- Exception: `IsEmptyImageDirective` uses `img` selector (auto-applies to all images)
-
-### Permissions
-
-- Use `HasPermissionDirective` for template-level permission checks
-- Use permission guards for route-level access control
-- Use `PermissionValidatorService` for programmatic checks in services
-- Permissions follow fail-closed model: no access by default
-- Wildcards supported: `*` (all), `module.*` (module-scoped)
-
----
-
-## Common Issues
-
-### ApiResourceService Not Updating UI
-
-**Problem:** UI doesn't update after operations.
-
-**Solution:** Use signal syntax in templates:
-
-```html
-<!-- Correct -->
-<div>{{ users() }}</div>
-
-<!-- Wrong -->
-<div>{{ users }}</div>
-```
-
-### FileUrlService Returns Error
-
-**Problem:** File URL fetching fails.
-
-**Solution:**
-
-1. Ensure storage service is enabled in environment config
-2. Verify file ID exists in database
-3. Check storage provider configuration (local/S3/Azure)
-
-### Circular Dependency with ng-layout
-
-**Problem:** Build fails with circular dependency.
-
-**Solution:** ng-shared must NEVER import from ng-layout. Move shared components to ng-shared, layout-specific components to ng-layout.
-
-### Provider Token Errors
-
-**Problem:** `'XXX_PROVIDER not configured'` error at runtime.
-
-**Solution:** Ensure the provider is registered in `app.config.ts`:
-
-```typescript
-// Required providers
-providers: [
-  { provide: USER_PROVIDER, useClass: AuthUserProvider },
-  { provide: COMPANY_API_PROVIDER, useClass: AuthCompanyApiProvider },
-  { provide: USER_PERMISSION_PROVIDER, useClass: AuthUserPermissionProvider },
-  { provide: AUTH_STATE_PROVIDER, useClass: AuthStateProviderAdapter },
-];
-
-// OR use the convenience function
-providers: [...provideAuthProviders()];
-```
-
-### Permissions Not Working
-
-**Problem:** `hasPermission()` returns false even though user should have access.
-
-**Solution:**
-
-1. Check if permissions are loaded: `permissionValidator.isLoaded()`
-2. Verify permission codes match exactly (case-sensitive)
-3. For wildcard access, ensure user has `*` or `module.*` in their permissions
-
----
-
-## API Reference
-
-### Services
-
-| Service                      | Description                                                                              |
-| ---------------------------- | ---------------------------------------------------------------------------------------- |
-| `ApiResourceService<DTO, T>` | Signal-based CRUD with resource() API (lazy-initialized, accepts optional `serviceName`) |
-| `FileUrlService`             | Cloud storage URL fetching                                                               |
-| `PermissionValidatorService` | Permission state management with wildcards                                               |
-| `CookieService`              | SSR-aware cookie reading                                                                 |
-| `PlatformService`            | SSR environment detection                                                                |
-
-### Classes
-
-| Class                | Description                                        |
-| -------------------- | -------------------------------------------------- |
-| `ApiResourceService` | Signal-based CRUD base class (alias: `ApiService`) |
-| `BaseFormControl`    | Abstract base for custom form controls             |
-| `BaseFormPage`       | Abstract directive for create/edit pages           |
-| `BaseListPage`       | Abstract directive for list pages                  |
-
-### Constants
-
-| Constant            | Description                                           |
-| ------------------- | ----------------------------------------------------- |
-| `PERMISSIONS`       | Aggregated permission codes by module                 |
-| `USER_PERMISSIONS`  | `{ CREATE, READ, UPDATE, DELETE }` for users          |
-| `ROLE_PERMISSIONS`  | `{ CREATE, READ, UPDATE, DELETE }` for roles          |
-| `FILE_PERMISSIONS`  | `{ CREATE, READ, UPDATE, DELETE }` for files          |
-| `FILE_TYPE_FILTERS` | Predefined MIME type arrays (IMAGES, DOCUMENTS, etc.) |
-
-### Components
-
-| Component                     | Selector                   | Description               |
-| ----------------------------- | -------------------------- | ------------------------- |
-| `IconComponent`               | `lib-icon`                 | Flexible icon renderer    |
-| `LazySelectComponent`         | `lib-lazy-select`          | Lazy-loading dropdown     |
-| `LazyMultiSelectComponent`    | `lib-lazy-multi-select`    | Lazy-loading multi-select |
-| `UserSelectComponent`         | `lib-user-select`          | Single user selector      |
-| `UserMultiSelectComponent`    | `lib-user-multi-select`    | Multiple user selector    |
-| `FileUploaderComponent`       | `lib-file-uploader`        | Drag & drop file upload   |
-| `FileSelectorDialogComponent` | `lib-file-selector-dialog` | File browser dialog       |
-
-### Directives
-
-| Directive                         | Selector                      | Description                       |
-| --------------------------------- | ----------------------------- | --------------------------------- |
-| `HasPermissionDirective`          | `[hasPermission]`             | Permission-based rendering        |
-| `EditModeElementChangerDirective` | `[appEditModeElementChanger]` | Toggle edit mode on form controls |
-| `IsEmptyImageDirective`           | `img`                         | Image fallback on error/empty     |
-| `PreventDefaultDirective`         | `[appPreventDefault]`         | Prevent default event behavior    |
-
-### Guards
-
-| Guard                 | Description                           |
-| --------------------- | ------------------------------------- |
-| `permissionGuard`     | Single permission or ILogicNode check |
-| `anyPermissionGuard`  | OR logic (any of listed permissions)  |
-| `allPermissionsGuard` | AND logic (all of listed permissions) |
-
-### Interfaces
-
-| Interface               | Description                                                                    |
-| ----------------------- | ------------------------------------------------------------------------------ |
-| `IBaseEntity`           | Base entity with ID and timestamps                                             |
-| `ILoggedUserInfo`       | Current user info with company ctx                                             |
-| `IFilterData`           | Filter, pagination, sort payload                                               |
-| `IFilter`               | Filter object (supports arrays)                                                |
-| `IDeleteData`           | Delete request payload                                                         |
-| `IDropDown`             | Simple label/value pair                                                        |
-| `ISingleResponse<T>`    | Single item response                                                           |
-| `IListResponse<T>`      | List with pagination                                                           |
-| `IBulkResponse<T>`      | Bulk operation response                                                        |
-| `IMessageResponse`      | Message-only response                                                          |
-| `IErrorResponse`        | Error with validation details                                                  |
-| `ILogicNode`            | Permission logic tree (AND/OR nodes)                                           |
-| `IUserSelectFilter`     | User select filter params                                                      |
-| `LoadUsersFn`           | User loading function type                                                     |
-| `IFileBasicInfo`        | Basic file info for selectors                                                  |
-| `IFolderBasicInfo`      | Folder info for selectors                                                      |
-| `IStorageConfigBasicInfo` | Storage config info for selectors                                            |
-| `IFileUploadOptions`    | Upload options (compression, etc.)                                             |
-| `IUploadedFile`         | Uploaded file response                                                         |
-| `IFileSelectFilter`     | File select filter params                                                      |
-| `ISelectFilter`         | Filter params for folder/config selectors                                      |
-| `LoadFilesFn`           | File loading function type                                                     |
-| `UploadFileFn`          | Single file upload function type                                               |
-| `UploadMultipleFilesFn` | Multiple files upload function type                                            |
-| `IFileProvider`         | File operations provider interface                                             |
-| `FilesResponseDto`      | File URL service response                                                      |
-| `IAuthStateProvider`    | Auth state provider interface                                                  |
-| `IUserListProvider`     | User list extensions provider                                                  |
-| `IUserListItem`         | Base user for list operations                                                  |
-| `IUserListAction`       | User list action definition                                                    |
-| `IUserListColumn`       | Extra column for user list                                                     |
-| `IUserListFilter`       | User list filter parameters                                                    |
-| `IUserBranchPermission` | User permissions per branch                                                    |
-| `ServiceName`           | `'auth' \| 'administration' \| 'iam' \| 'storage' \| 'formBuilder' \| 'email'` |
-
-### Injection Tokens
-
-| Token                         | Interface                    | Optional | Description                           |
-| ----------------------------- | ---------------------------- | -------- | ------------------------------------- |
-| `USER_PROVIDER`               | `IUserProvider`              | No       | User list for IAM                     |
-| `COMPANY_API_PROVIDER`        | `ICompanyApiProvider`        | No       | Company list for IAM                  |
-| `USER_PERMISSION_PROVIDER`    | `IUserPermissionProvider`    | No       | User permission queries               |
-| `AUTH_STATE_PROVIDER`         | `IAuthStateProvider`         | No       | Auth state for feature packages       |
-| `FILE_PROVIDER`               | `IFileProvider`              | Yes      | File operations (ng-storage)          |
-| `PROFILE_PERMISSION_PROVIDER` | `IProfilePermissionProvider` | Yes      | User permissions for profile (ng-iam) |
-| `USER_LIST_PROVIDER`          | `IUserListProvider`          | Yes      | User list extensions                  |
-
----
-
-## 10. Translation & Localization
-
-### Overview
-
-The ng-shared package provides optional localization support via two modes:
-
-1. **Fallback-Only Mode** - Hardcoded fallback messages (no API)
-2. **Full API Mode** - Dynamic translations from API with fallback safety net
-
-### Fallback-Only Mode
-
-Use when you want simple hardcoded translations without a localization system:
-
-```typescript
-// app.config.ts
-import { provideFallbackLocalization } from '@flusys/ng-shared';
-
-export const appConfig: ApplicationConfig = {
-  providers: [
-    // ... other providers
-    ...provideFallbackLocalization(),  // ← One-liner setup
-  ],
-};
-```
-
-**What it provides:**
-- `FALLBACK_MESSAGES_REGISTRY` - Token for storing hardcoded messages
-- `TRANSLATE_ADAPTER` - Fallback implementation that reads from registry
-- Works with route resolvers that register fallback messages
-
-**Message flow:**
-```
-Route with resolveTranslationModule({
-  modules: ['email'],
-  fallbackMessages: EMAIL_MESSAGES
-})
-    ↓
-Resolver registers in FALLBACK_MESSAGES_REGISTRY
-    ↓
-TRANSLATE_ADAPTER reads from registry
-    ↓
-Components/TranslatePipe render values
-```
-
-### Full API Mode
-
-Use when you need dynamic translations, language switching, and management UI:
-
-```typescript
-// app.config.ts
-import { provideLocalization, getLocalizationConfig } from '@flusys/ng-localization';
-
-export const appConfig: ApplicationConfig = {
-  providers: [
-    // ... other providers
-    ...provideLocalization(
-      getLocalizationConfig({
-        defaultLanguageCode: 'en',
-        enableLayoutSelector: true,  // Show language switcher
-      })
-    ),
-  ],
-};
-```
-
-**What it provides:**
-- `LocalizationStateService` - Manages current language and translations
-- `LocalizationApiService` - Fetches translations from backend
-- `TranslateService` - Registered as `TRANSLATE_ADAPTER`
-- Language selector component (if `enableLayoutSelector: true`)
-- Management pages for languages and translations
-
-### Route Resolver Setup
-
-All routes should use `resolveTranslationModule` with fallback messages:
-
-```typescript
-// email.routes.ts
-import { resolveTranslationModule, EMAIL_MESSAGES, SHARED_MESSAGES } from '@flusys/ng-shared';
-
-export const EMAIL_ROUTES: Routes = [
-  {
-    path: '',
-    resolve: {
-      translations: resolveTranslationModule({
-        modules: ['email'],
-        fallbackMessages: { ...EMAIL_MESSAGES, ...SHARED_MESSAGES }
-      })
-    },
-    // ... route definition
-  }
-];
-```
-
-### TranslatePipe Usage
-
-Works identically in both modes:
-
-```typescript
-// Template
-<h1>{{ 'email.title' | translate }}</h1>
-<p>{{ 'email.message' | translate: { count: itemCount } }}</p>
-
-// Component
-const title = this.translateAdapter.translate('email.title');
-```
-
-### Configuration (Full API Mode Only)
-
-```typescript
-interface ILocalizationConfig {
-  defaultLanguageCode: string;        // Required: 'en', 'ar', etc.
-  loadStrategy?: 'all' | 'modules';   // Default: 'modules'
-  initialModules?: string[];          // Default: []
-  enableLayoutSelector?: boolean;     // Default: false
-}
-```
-
-### Key Files
-
-| File | Purpose |
-|------|---------|
-| `providers/fallback-localization.providers.ts` | Fallback mode setup |
-| `resolvers/translation-module.resolver.ts` | Route resolver for both modes |
-| `pipes/translate.pipe.ts` | Translation pipe |
-
-### When to Use Each Mode
-
-**Use Fallback-Only:**
-- Simple applications with static content
-- No language switching needed
-- No translation management UI
-- Lightweight setup
-
-**Use Full API:**
-- Multi-language support required
-- User can switch languages
-- Admin manages translations
-- Real-time translation updates
-- Translation management UI needed
-
-## See Also
-
-- **[CORE-GUIDE.md](./CORE-GUIDE.md)** - Configuration, interceptors
-- **[LAYOUT-GUIDE.md](./LAYOUT-GUIDE.md)** - Layout system
-- **[AUTH-GUIDE.md](./AUTH-GUIDE.md)** - Auth adapters for provider interfaces
-- **[IAM-GUIDE.md](./IAM-GUIDE.md)** - IAM permission usage
-
----
+## License
 
-**Last Updated:** 2026-03-01
-**Version:** 3.0.1
-**Angular Version:** 21
+MIT © FLUSYS