@flusys/ng-shared 3.0.0 → 4.0.0-lts

package/README.md

@@ -9,7 +9,7 @@
 ## Package Information
 
 - **Package:** `@flusys/ng-shared`
-- **Version:** 3.0.0
+- **Version:** 4.0.0-rc
 - **Dependencies:** ng-core
 - **Dependents:** ng-layout, ng-auth, ng-iam, ng-storage, flusysng
 - **Build Command:** `npm run build:ng-shared`
@@ -38,13 +38,13 @@ interface IBaseEntity {
 
 **Entity Mixins:**
 
-| 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  |
+| 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  |
 
 #### ILoggedUserInfo
 
@@ -74,7 +74,9 @@ interface IPagination {
   currentPage: number;
 }
 
-interface ISort { [key: string]: 'ASC' | 'DESC' }
+interface ISort {
+  [key: string]: "ASC" | "DESC";
+}
 
 // Filter supports primitives and arrays for multi-value filtering
 interface IFilter {
@@ -98,10 +100,10 @@ interface IFilterData {
 Delete request payload matching backend DeleteDto.
 
 ```typescript
-type DeleteType = 'delete' | 'restore' | 'permanent';
+type DeleteType = "delete" | "restore" | "permanent";
 
 interface IDeleteData {
-  id: string | string[];  // Single or batch delete
+  id: string | string[]; // Single or batch delete
   type: DeleteType;
 }
 ```
@@ -124,7 +126,6 @@ interface IUserSelectFilter {
   page: number;
   pageSize: number;
   search: string;
-  [key: string]: unknown;
 }
 
 type LoadUsersFn = (filter: IUserSelectFilter) => Observable<IListResponse<IUserBasicInfo>>;
@@ -151,7 +152,7 @@ interface IFileUploadOptions {
 }
 
 interface IUploadedFile {
-  id?: string;         // File manager ID (UUID) - available when registered
+  id?: string; // File manager ID (UUID) - available when registered
   name: string;
   key: string;
   size: number;
@@ -164,7 +165,6 @@ interface IFileSelectFilter {
   search: string;
   contentTypes?: string[];
   folderId?: string;
-  [key: string]: unknown;
 }
 
 type LoadFilesFn = (filter: IFileSelectFilter) => Observable<IListResponse<IFileBasicInfo>>;
@@ -175,18 +175,18 @@ type GetFileUrlsFn = (fileIds: string[]) => Observable<ISingleResponse<IFileBasi
 **File Type Filters (Constants):**
 
 ```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'
+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'
 ```
 
 ### Response Interfaces
@@ -242,12 +242,12 @@ type ApiResponse<T> = ISingleResponse<T> | IListResponse<T> | IBulkResponse<T> |
 
 **Metadata types:**
 
-| Interface          | Fields                                       |
-| ------------------ | -------------------------------------------- |
-| `IRequestMeta`     | `requestId?, timestamp?, responseTime?`      |
+| Interface          | Fields                                                |
+| ------------------ | ----------------------------------------------------- |
+| `IRequestMeta`     | `requestId?, timestamp?, responseTime?`               |
 | `IPaginationMeta`  | `total, page, pageSize, count, hasMore?, totalPages?` |
-| `IBulkMeta`        | `count, failed?, total?`                     |
-| `IValidationError` | `field, message, constraint?`                |
+| `IBulkMeta`        | `count, failed?, total?`                              |
+| `IValidationError` | `field, message, constraint?`                         |
 
 ### Auth & Storage Response Types
 
@@ -292,14 +292,14 @@ Discriminated union for building complex permission logic trees.
 ```typescript
 // Single permission check
 interface IActionNode {
-  type: 'action';
+  type: "action";
   actionId: string;
 }
 
 // Group with AND/OR logic
 interface IGroupNode {
-  type: 'group';
-  operator: 'AND' | 'OR';
+  type: "group";
+  operator: "AND" | "OR";
   children: ILogicNode[];
 }
 
@@ -374,25 +374,25 @@ Signal-based CRUD service using Angular 21 `resource()` API with **lazy initiali
 **ServiceName Type:**
 
 ```typescript
-type ServiceName = 'auth' | 'administration' | 'iam' | 'storage' | 'formBuilder' | 'email';
+type ServiceName = "auth" | "administration" | "iam" | "storage" | "formBuilder" | "email";
 ```
 
 **Define a service:**
 
 ```typescript
-import { Injectable } from '@angular/core';
-import { HttpClient } from '@angular/common/http';
-import { ApiResourceService } from '@flusys/ng-shared';
+import { Injectable } from "@angular/core";
+import { HttpClient } from "@angular/common/http";
+import { ApiResourceService } from "@flusys/ng-shared";
 
-@Injectable({ providedIn: 'root' })
+@Injectable({ providedIn: "root" })
 export class UserService extends ApiResourceService<UserDto, IUser> {
   constructor(http: HttpClient) {
     // Option 1: Use global apiBaseUrl (default)
-    super('users', http);
+    super("users", http);
     // Base URL: APP_CONFIG.apiBaseUrl + '/users'
 
     // Option 2: Use feature-specific service URL (recommended)
-    super('users', http, 'administration');
+    super("users", http, "administration");
     // Base URL: APP_CONFIG.services.administration.baseUrl + '/users'
   }
 }
@@ -400,13 +400,14 @@ export class UserService extends ApiResourceService<UserDto, IUser> {
 
 **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 |
+| 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
 
@@ -416,7 +417,7 @@ The list resource is **lazy-initialized** to avoid unnecessary HTTP requests on
 
 ```typescript
 // Resource is NOT created until one of these is called:
-userService.fetchList('', { pagination: { currentPage: 0, pageSize: 10 } });
+userService.fetchList("", { pagination: { currentPage: 0, pageSize: 10 } });
 // OR
 userService.initListResource(); // Explicit initialization
 ```
@@ -439,35 +440,35 @@ initListResource(): void {
 
 **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`      |
+| 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`   |
 
 All methods above return `Observable`. Async (Promise) variants are also available: `insertAsync`, `insertManyAsync`, `findByIdAsync`, `updateAsync`, `updateManyAsync`, `deleteAsync`.
 
 **Reactive signals:**
 
-| 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      |
+| 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 |
 
 **List management:**
 
 ```typescript
 // Trigger data fetch (updates searchTerm and filterData signals, resource auto-reloads)
-userService.fetchList('search term', { pagination: { currentPage: 0, pageSize: 10 } });
+userService.fetchList("search term", { pagination: { currentPage: 0, pageSize: 10 } });
 
 // Pagination helpers
 userService.setPagination({ currentPage: 1, pageSize: 20 });
@@ -530,14 +531,14 @@ export class ProductComponent {
 
 **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   |
+| 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  |
 
 ### PermissionValidatorService
 
@@ -569,18 +570,18 @@ export class MyComponent {
 
 **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 |
+| 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   |
+| Signal        | Type               | Description                       |
+| ------------- | ------------------ | --------------------------------- |
+| `permissions` | `Signal<string[]>` | Readonly current permissions      |
 | `isLoaded`    | `Signal<boolean>`  | Whether permissions have been set |
 
 **Wildcard Support:**
@@ -589,13 +590,13 @@ The `hasPermission()` method uses the permission evaluator utility which support
 
 ```typescript
 // Exact match
-hasPermission('user.read')  // true if permissions include 'user.read'
+hasPermission("user.read"); // true if permissions include 'user.read'
 
 // Global wildcard
-hasPermission('user.read')  // true if permissions include '*'
+hasPermission("user.read"); // true if permissions include '*'
 
 // Module wildcard
-hasPermission('user.read')  // true if permissions include 'user.*'
+hasPermission("user.read"); // true if permissions include 'user.*'
 ```
 
 ### CookieService
@@ -603,7 +604,7 @@ hasPermission('user.read')  // true if permissions include 'user.*'
 SSR-aware cookie reading service.
 
 ```typescript
-import { CookieService } from '@flusys/ng-shared';
+import { CookieService } from "@flusys/ng-shared";
 
 const cookies = inject(CookieService).get(); // Returns document.cookie (browser) or request header cookie (server)
 ```
@@ -613,7 +614,7 @@ const cookies = inject(CookieService).get(); // Returns document.cookie (browser
 SSR environment detection service.
 
 ```typescript
-import { PlatformService } from '@flusys/ng-shared';
+import { PlatformService } from "@flusys/ng-shared";
 
 const platform = inject(PlatformService);
 if (!platform.isServer) {
@@ -654,21 +655,7 @@ Single-select dropdown with lazy loading, search, and scroll pagination.
 ```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)"
-    />
-  `,
+  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);
@@ -681,16 +668,16 @@ export class MyComponent {
 
 **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'`) |
+| 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'`) |
 
 **Model:** `value` - Two-way bound selected value (`string | null`)
 
@@ -707,19 +694,7 @@ Multi-select dropdown with lazy loading, search, select-all, and scroll paginati
 ```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)"
-    />
-  `,
+  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);
@@ -744,17 +719,10 @@ Single user selection with lazy loading. Uses `USER_PROVIDER` internally or acce
   imports: [UserSelectComponent],
   template: `
     <!-- Simple usage - uses USER_PROVIDER internally -->
-    <lib-user-select
-      [(value)]="selectedUserId"
-      [isEditMode]="true"
-    />
+    <lib-user-select [(value)]="selectedUserId" [isEditMode]="true" />
 
     <!-- With custom loadUsers function -->
-    <lib-user-select
-      [(value)]="selectedUserId"
-      [isEditMode]="true"
-      [loadUsers]="customLoadUsers"
-    />
+    <lib-user-select [(value)]="selectedUserId" [isEditMode]="true" [loadUsers]="customLoadUsers" />
   `,
 })
 export class MyComponent {
@@ -764,14 +732,14 @@ export class MyComponent {
 
 **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 |
+| 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`)
 
@@ -787,12 +755,7 @@ Multiple user selection with lazy loading. Uses `USER_PROVIDER` internally or ac
 ```typescript
 @Component({
   imports: [UserMultiSelectComponent],
-  template: `
-    <lib-user-multi-select
-      [(value)]="selectedUserIds"
-      [isEditMode]="true"
-    />
-  `,
+  template: ` <lib-user-multi-select [(value)]="selectedUserIds" [isEditMode]="true" /> `,
 })
 export class MyComponent {
   readonly selectedUserIds = signal<string[] | null>(null);
@@ -816,44 +779,32 @@ Drag & drop file upload with type filtering. Pass your own `uploadFile` function
   imports: [FileUploaderComponent],
   template: `
     <!-- Single image upload -->
-    <lib-file-uploader
-      [uploadFile]="uploadFile"
-      [acceptTypes]="['image/*']"
-      [multiple]="false"
-      (fileUploaded)="onFileUploaded($event)"
-    />
+    <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)"
-    />
+    <lib-file-uploader [uploadFile]="uploadFile" [acceptTypes]="FILE_TYPE_FILTERS.DOCUMENTS" [multiple]="true" [maxFiles]="5" (filesUploaded)="onFilesUploaded($event)" />
   `,
 })
 export class MyComponent {
   readonly uploadService = inject(UploadService);
 
-  readonly uploadFile: UploadFileFn = (file, options) =>
-    this.uploadService.uploadSingleFile(file, options);
+  readonly uploadFile: UploadFileFn = (file, options) => this.uploadService.uploadSingleFile(file, options);
 }
 ```
 
 **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 |
+| 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[])
 
@@ -866,15 +817,7 @@ Dialog to browse and select existing files with filtering.
 ```typescript
 @Component({
   imports: [FileSelectorDialogComponent],
-  template: `
-    <lib-file-selector-dialog
-      [(visible)]="showFileSelector"
-      [loadFiles]="loadFiles"
-      [acceptTypes]="['image/*']"
-      [multiple]="false"
-      (fileSelected)="onFileSelected($event)"
-    />
-  `,
+  template: ` <lib-file-selector-dialog [(visible)]="showFileSelector" [loadFiles]="loadFiles" [acceptTypes]="['image/*']" [multiple]="false" (fileSelected)="onFileSelected($event)" /> `,
 })
 export class MyComponent {
   readonly showFileSelector = signal(false);
@@ -889,14 +832,14 @@ 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 |
+| 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`)
 
@@ -914,7 +857,7 @@ Structural directive for permission-based rendering. Fail-closed: hides content
 - **Input:** `hasPermission` - `string | ILogicNode | null`
 
 ```typescript
-import { HasPermissionDirective, ILogicNode } from '@flusys/ng-shared';
+import { HasPermissionDirective, ILogicNode } from "@flusys/ng-shared";
 
 @Component({
   imports: [HasPermissionDirective],
@@ -928,11 +871,11 @@ import { HasPermissionDirective, ILogicNode } from '@flusys/ng-shared';
 })
 export class MyComponent {
   readonly editLogic: ILogicNode = {
-    type: 'group',
-    operator: 'AND',
+    type: "group",
+    operator: "AND",
     children: [
-      { type: 'action', actionId: 'user.view' },
-      { type: 'action', actionId: 'user.update' },
+      { type: "action", actionId: "user.view" },
+      { type: "action", actionId: "user.update" },
     ],
   };
 }
@@ -946,8 +889,7 @@ Toggles readonly/disabled state for form controls based on edit mode. Supports `
 - **Input:** `isEditMode` (required boolean)
 
 ```html
-<input [appEditModeElementChanger] [isEditMode]="isEditing()" />
-<p-select [appEditModeElementChanger] [isEditMode]="isEditing()" />
+<input [appEditModeElementChanger] [isEditMode]="isEditing()" /> <p-select [appEditModeElementChanger] [isEditMode]="isEditing()" />
 ```
 
 ### IsEmptyImageDirective
@@ -972,8 +914,7 @@ Prevents default browser behavior on specified events and emits the event.
 - **Output:** `action` - Emits the prevented event
 
 ```html
-<a href="#" appPreventDefault (action)="handleClick($event)">Click me</a>
-<input appPreventDefault eventType="keydown" preventKey="Enter" (action)="onEnter($event)" />
+<a href="#" appPreventDefault (action)="handleClick($event)">Click me</a> <input appPreventDefault eventType="keydown" preventKey="Enter" (action)="onEnter($event)" />
 ```
 
 ---
@@ -987,24 +928,29 @@ Route-level guards for permission-based access control. All guards deny access w
 Single permission or complex logic check.
 
 ```typescript
-import { permissionGuard } from '@flusys/ng-shared';
+import { permissionGuard } from "@flusys/ng-shared";
 
 const routes: Routes = [
   // Simple permission
-  { path: 'users', canActivate: [permissionGuard('user.view')] },
+  { 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' },
+  {
+    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')] },
+  { path: "settings", canActivate: [permissionGuard("settings.view", "/access-denied")] },
 ];
 ```
 
@@ -1033,34 +979,34 @@ AND logic - allows access only if user has ALL specified permissions.
 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';
+import { evaluatePermission, evaluateLogicNode, hasAnyPermission, hasAllPermissions, hasPermission } from "@flusys/ng-shared";
 
-const userPermissions = ['user.view', 'user.create', 'admin.*'];
+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)
+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
+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)
+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 |
+| Pattern     | Matches                                 |
+| ----------- | --------------------------------------- |
+| `*`         | All permissions (global wildcard)       |
+| `module.*`  | All permissions starting with `module.` |
+| `user.read` | Exact match only                        |
 
 **Implementation Details:**
 
@@ -1072,10 +1018,10 @@ export function hasPermission(requiredPermission: string, userPermissions: strin
   // Wildcard matching
   for (const permission of userPermissions) {
     // Global wildcard
-    if (permission === '*') return true;
+    if (permission === "*") return true;
 
     // Module wildcard (e.g., 'user.*' matches 'user.read')
-    if (permission.endsWith('.*')) {
+    if (permission.endsWith(".*")) {
       const prefix = permission.slice(0, -1); // 'user.'
       if (requiredPermission.startsWith(prefix)) return true;
     }
@@ -1119,10 +1065,10 @@ onScroll(event: Event): void {
 Abstract base class for custom form controls. Implements both `ControlValueAccessor` (reactive forms) and `FormValueControl` (signal forms).
 
 ```typescript
-import { BaseFormControl, provideValueAccessor } from '@flusys/ng-shared';
+import { BaseFormControl, provideValueAccessor } from "@flusys/ng-shared";
 
 @Component({
-  selector: 'my-select',
+  selector: "my-select",
   providers: [provideValueAccessor(MySelectComponent)],
 })
 export class MySelectComponent extends BaseFormControl<string | null> {
@@ -1226,7 +1172,7 @@ export class UserListComponent extends BaseListPage<IUser> {
 Re-exports common Angular modules for convenience.
 
 ```typescript
-import { AngularModule } from '@flusys/ng-shared';
+import { AngularModule } from "@flusys/ng-shared";
 // Includes: CommonModule, FormsModule, ReactiveFormsModule, RouterLink, RouterOutlet,
 // RouterLinkActive, NgOptimizedImage, NgComponentOutlet, + directives (IsEmptyImageDirective, PreventDefaultDirective)
 // Providers: DatePipe
@@ -1237,7 +1183,7 @@ import { AngularModule } from '@flusys/ng-shared';
 Re-exports PrimeNG component modules for convenience.
 
 ```typescript
-import { PrimeModule } from '@flusys/ng-shared';
+import { PrimeModule } from "@flusys/ng-shared";
 // Includes 30 modules:
 // - Layout: AccordionModule, CardModule, DividerModule, PanelModule, SplitterModule, TabsModule, ToolbarModule
 // - Form: AutoCompleteModule, CheckboxModule, DatePickerModule, InputTextModule, InputTextareaModule,
@@ -1273,13 +1219,14 @@ ng-iam/ng-storage (consume interfaces via DI)
 User list access for IAM user selection.
 
 ```typescript
-interface IUserBasicInfo { id: string; name: string; email: string }
+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>>;
+  getUsers(filter?: { page?: number; pageSize?: number; search?: string; companyId?: string; branchId?: string }): Observable<IListResponse<IUserBasicInfo>>;
 }
 ```
 
@@ -1290,12 +1237,14 @@ interface IUserProvider {
 Company list access for IAM company selection.
 
 ```typescript
-interface ICompanyBasicInfo { id: string; name: string; slug?: string }
+interface ICompanyBasicInfo {
+  id: string;
+  name: string;
+  slug?: string;
+}
 
 interface ICompanyApiProvider {
-  getCompanies(filter?: {
-    page?: number; pageSize?: number; search?: string;
-  }): Observable<IListResponse<ICompanyBasicInfo>>;
+  getCompanies(filter?: { page?: number; pageSize?: number; search?: string }): Observable<IListResponse<ICompanyBasicInfo>>;
 }
 ```
 
@@ -1319,31 +1268,18 @@ interface IUserPermissionProvider {
 
 **Token Error Message:** `'USER_PERMISSION_PROVIDER not configured. Please provide an implementation in app.config.ts'`
 
-#### IProfileUploadProvider / `PROFILE_UPLOAD_PROVIDER`
+#### IFileProvider / `FILE_PROVIDER`
 
-Profile picture upload for ng-auth profile page. Implemented by ng-storage. **Optional token** - use with `inject(..., { optional: true })`.
+File operations provider for file selection and upload. Implemented by ng-storage. **Optional token** - use with `inject(..., { optional: true })`.
 
 ```typescript
-interface IProfileUploadResult {
-  id: string;          // File manager ID (UUID)
-  name: string;        // Original file name
-  key: string;         // Storage key/path
-  size: number;        // File size in bytes
-  contentType: string; // MIME type
-}
-
-interface IProfileUploadOptions {
-  folderPath?: string;
-  compress?: boolean;
-  maxWidth?: number;
-  maxHeight?: number;
-}
-
-interface IProfileUploadProvider {
-  uploadProfilePicture(
-    file: File,
-    options?: IProfileUploadOptions
-  ): Observable<ISingleResponse<IProfileUploadResult>>;
+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>>;
 }
 ```
 
@@ -1417,14 +1353,13 @@ interface IUserListItem {
   email: string;
   phone?: string;
   isActive?: boolean;
-  [key: string]: unknown;
 }
 
 interface IUserListAction<T = IUserListItem> {
   id: string;
   label: string;
   icon?: string;
-  severity?: 'primary' | 'secondary' | 'success' | 'info' | 'warn' | 'danger';
+  severity?: "primary" | "secondary" | "success" | "info" | "warn" | "danger";
   permission?: string;
   tooltip?: string;
   disabled?: boolean | ((user: T) => boolean);
@@ -1436,7 +1371,7 @@ interface IUserListColumn {
   header: string;
   width?: string;
   sortable?: boolean;
-  templateType?: 'text' | 'badge' | 'date' | 'boolean' | 'custom';
+  templateType?: "text" | "badge" | "date" | "boolean" | "custom";
 }
 
 interface IUserListFilter {
@@ -1446,7 +1381,6 @@ interface IUserListFilter {
   isActive?: boolean;
   companyId?: string;
   branchId?: string;
-  [key: string]: unknown;
 }
 
 interface IUserListProvider<T extends IUserListItem = IUserListItem> {
@@ -1463,17 +1397,13 @@ interface IUserListProvider<T extends IUserListItem = IUserListItem> {
 
 ```typescript
 // In app.config.ts
-providers: [
-  { provide: USER_LIST_PROVIDER, useClass: MyUserListProvider },
-]
+providers: [{ provide: USER_LIST_PROVIDER, useClass: MyUserListProvider }];
 
 // Implementation
-@Injectable({ providedIn: 'root' })
+@Injectable({ providedIn: "root" })
 export class MyUserListProvider implements IUserListProvider {
   getExtraRowActions() {
-    return [
-      { id: 'assign-role', label: 'Assign Role', icon: 'pi pi-users' },
-    ];
+    return [{ id: "assign-role", label: "Assign Role", icon: "pi pi-users" }];
   }
 }
 ```
@@ -1481,13 +1411,13 @@ export class MyUserListProvider implements IUserListProvider {
 ### Usage in Consuming Packages
 
 ```typescript
-import { USER_PROVIDER } from '@flusys/ng-shared';
+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.userProvider.getUsers({ page: 0, pageSize: 50 }).subscribe((response) => {
       this.users.set(response.data ?? []);
     });
   }
@@ -1498,7 +1428,7 @@ export class UserSelectorComponent {
 
 ```typescript
 // app.config.ts
-import { provideAuthProviders } from '@flusys/ng-auth';
+import { provideAuthProviders } from "@flusys/ng-auth";
 
 export const appConfig: ApplicationConfig = {
   providers: [
@@ -1598,12 +1528,10 @@ providers: [
   { 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(),
-]
+providers: [...provideAuthProviders()];
 ```
 
 ### Permissions Not Working
@@ -1622,107 +1550,255 @@ providers: [
 
 ### 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             |
+| 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            |
+| 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 |
+| 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 |
+| 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          |
+| 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      |
+| `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)  |
+| 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        |
-| `IFileUploadOptions`| Upload options (compression, etc.)   |
-| `IUploadedFile`     | Uploaded file response               |
-| `IFileSelectFilter` | File select filter params            |
-| `LoadFilesFn`       | File loading function type           |
-| `UploadFileFn`      | File upload function type            |
-| `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'` |
+| 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 |
-| `PROFILE_UPLOAD_PROVIDER`  | `IProfileUploadProvider`  | Yes | Profile picture upload (ng-storage) |
-| `PROFILE_PERMISSION_PROVIDER` | `IProfilePermissionProvider` | Yes | User permissions for profile (ng-iam) |
-| `USER_LIST_PROVIDER`       | `IUserListProvider`       | Yes | User list extensions         |
+| 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
 
@@ -1733,6 +1809,6 @@ providers: [
 
 ---
 
-**Last Updated:** 2026-02-25
-**Version:** 3.0.0
+**Last Updated:** 2026-03-01
+**Version:** 3.0.1
 **Angular Version:** 21