@flusys/ng-shared 1.1.1-beta → 1.2.0-rc.1

package/README.md

@@ -1,1293 +1,165 @@
-# @flusys/ng-shared Package Guide
+# @flusys/ng-shared
 
-## Overview
+Shared utilities, provider tokens, base page classes, and reusable components for the FLUSYS Angular platform.
 
-`@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
-
-- **Package:** `@flusys/ng-shared`
-- **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)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
 ---
 
-## 1. Interfaces
-
-### 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;
-}
-```
-
-**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  |
-
-#### ILoggedUserInfo
+## Installation
 
-Current logged-in user info with optional company context.
-
-```typescript
-interface ILoggedUserInfo {
-  id: string;
-  email: string;
-  name?: string;
-  phone?: string;
-  profilePictureId?: string;
-  companyId?: string;
-  branchId?: string;
-  companyLogoId?: string;
-  branchLogoId?: string;
-}
-```
-
-#### IFilterData
-
-Filter, pagination, and sort payload for list queries.
-
-```typescript
-interface IPagination {
-  pageSize: number;
-  currentPage: number;
-}
-
-interface ISort { [key: string]: 'ASC' | 'DESC' }
-interface IFilter { [key: string]: any }
-
-interface IFilterData {
-  filter?: IFilter;
-  pagination?: IPagination;
-  select?: string[];
-  sort?: ISort;
-  withDeleted?: boolean;
-  extraKey?: string[];
-}
+```bash
+npm install @flusys/ng-shared @flusys/ng-core
 ```
 
-#### IDeleteData
-
-Delete request payload matching backend DeleteDto.
-
-```typescript
-type DeleteType = 'delete' | 'restore' | 'permanent';
-
-interface IDeleteData {
-  id: string | string[];  // Single or batch delete
-  type: DeleteType;
-}
-```
-
-#### IDropDown
-
-Simple dropdown item for select components.
+---
 
-```typescript
-interface IDropDown {
-  label: string;
-  value: string;
-}
-```
+## 1. ApiResourceService — Signal-Driven CRUD
 
-#### User Select Interfaces
+Extend this class to get a reactive list resource backed by `resource()`, with pagination, search, and all standard POST-only RPC endpoints.
 
 ```typescript
-interface IUserSelectFilter {
-  page: number;
-  pageSize: number;
-  search: string;
-  [key: string]: unknown;
-}
+import { Injectable, inject } from "@angular/core";
+import { HttpClient } from "@angular/common/http";
+import { ApiResourceService } from "@flusys/ng-shared";
 
-type LoadUsersFn = (filter: IUserSelectFilter) => Observable<IListResponse<IUserBasicInfo>>;
-```
-
-#### File Select Interfaces
-
-```typescript
-interface IFileBasicInfo {
+export interface IProduct {
   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 {
-  name: string;
-  key: string;
-  size: number;
-  contentType: string;
-}
-
-interface IFileSelectFilter {
-  page: number;
-  pageSize: number;
-  search: string;
-  contentTypes?: string[];
-  folderId?: string;
-  [key: string]: unknown;
-}
-
-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):**
-
-```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'
-```
-
-### Response Interfaces
-
-Type-safe interfaces matching FLUSYS_NEST backend response DTOs.
-
-```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
-
-```typescript
-interface ILoginResponse {
-  success: boolean;
-  message: string;
-  data: { accessToken: string; refreshToken: string; user: ILoginUserData };
+  price: number;
 }
-
-interface IRefreshTokenResponse {
-  success: boolean;
-  message: string;
-  data: { accessToken: string; refreshToken?: string };
-}
-
-interface IFileData {
-  id: string;
+export interface IProductDto {
   name: string;
-  originalName: string;
-  contentType: string;
-  size: number;
-  key: string;
-  url?: string;
-  thumbnailUrl?: string;
-  createdAt: Date;
-}
-```
-
-### Permission Interfaces
-
-Discriminated union for building complex permission logic trees.
-
-```typescript
-// Single permission check
-interface IActionNode {
-  type: 'action';
-  actionId: string;
-}
-
-// Group with AND/OR logic
-interface IGroupNode {
-  type: 'group';
-  operator: 'AND' | 'OR';
-  children: ILogicNode[];
-}
-
-// Union type
-type ILogicNode = IActionNode | IGroupNode;
-```
-
----
-
-## 2. Enums
-
-```typescript
-enum ContactTypeEnum {
-  PHONE = 1,
-  EMAIL = 2,
+  price: number;
 }
 
-enum IconTypeEnum {
-  PRIMENG_ICON = 1,
-  IMAGE_FILE_LINK = 2,
-  DIRECT_TAG_SVG = 3,
-}
-```
-
----
-
-## 3. Services
-
-### ApiResourceService
-
-Signal-based CRUD service using Angular 21 `resource()` API. All endpoints use POST (RPC-style).
-
-**Define a service:**
-
-```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) {
-    super('users', http); // Base URL: APP_CONFIG.apiBaseUrl + '/users'
+@Injectable({ providedIn: "root" })
+export class ProductService extends ApiResourceService<IProductDto, IProduct> {
+  constructor() {
+    super("products", "administration"); // moduleApiName, http, serviceName (key in APP_CONFIG.services)
   }
 }
 ```
 
-**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`      |
-
-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      |
-| `filterData` | `WritableSignal<IFilterData>` | Filter/pagination state |
-
-**List management:**
+Using the reactive list in a component:
 
 ```typescript
-// Trigger data fetch (updates searchTerm and filterData signals, resource auto-reloads)
-userService.fetchList('search term', { pagination: { currentPage: 0, pageSize: 10 } });
+@Component({ ... })
+export class ProductListComponent {
+  private readonly svc = inject(ProductService);
 
-// Pagination helpers
-userService.setPagination({ currentPage: 1, pageSize: 20 });
-userService.nextPage();
-userService.resetPagination();
-userService.reload();
-```
+  readonly items   = this.svc.data;      // Signal<IProduct[]>
+  readonly total   = this.svc.total;     // Signal<number>
+  readonly loading = this.svc.isLoading; // Signal<boolean>
 
-**Component usage:**
+  ngOnInit() { this.svc.fetchList(); }
 
-```typescript
-@Component({...})
-export class UserListComponent {
-  private readonly userService = inject(UserService);
+  onSearch(q: string) { this.svc.fetchList(q); }
 
-  readonly users = this.userService.data;           // Signal<IUser[]>
-  readonly isLoading = this.userService.isLoading;   // Signal<boolean>
-  readonly total = this.userService.total;           // Signal<number>
+  onPageChange(page: number, size: number) {
+    this.svc.setPagination({ currentPage: page, pageSize: size });
+  }
 
-  constructor() {
-    this.userService.fetchList('', { pagination: { currentPage: 0, pageSize: 10 } });
+  async onCreate(dto: IProductDto) {
+    await this.svc.insert(dto);
+    this.svc.reload();
   }
 
-  async createUser(dto: UserDto) {
-    await this.userService.insertAsync(dto);
-    this.userService.reload(); // Refresh list
+  async onDelete(id: string) {
+    await this.svc.delete({ id });
+    this.svc.reload();
   }
 }
 ```
 
-> **Note:** `ApiService` is exported as an alias for `ApiResourceService` for backward compatibility.
+Available CRUD methods: `insert`, `insertMany`, `findById`, `findByIds`, `getAll`, `getByFilter`, `update`, `updateMany`, `bulkUpsert`, `delete`.
 
-### FileUrlService
+---
 
-Fetches file URLs from the backend. Supports presigned URLs for cloud storage (S3, Azure).
+## 2. FileUrlService — Presigned URL Fetching
 
-**CRITICAL:** Never construct file URLs manually. Always use this service.
+Never construct file URLs manually. `FileUrlService` handles S3/Azure presigned URLs, caching, and deduplication.
 
 ```typescript
 import { FileUrlService } from '@flusys/ng-shared';
 
-@Component({...})
-export class ProductComponent {
+@Component({ ... })
+export class AvatarComponent {
   private readonly fileUrlService = inject(FileUrlService);
+  readonly avatarUrl = signal<string | null>(null);
 
-  loadImage(fileId: string) {
-    // Fetch from backend: POST /file-manager/get-files
-    this.fileUrlService.fetchSingleFileUrl(fileId).subscribe(file => {
-      this.imageUrl.set(file?.url ?? null);
+  ngOnInit() {
+    this.fileUrlService.fetchSingleFileUrl('file-id-123').subscribe(file => {
+      this.avatarUrl.set(file?.url ?? null);
     });
   }
 
-  loadMultiple(fileIds: string[]) {
-    this.fileUrlService.fetchFileUrls(fileIds).subscribe(files => {
-      // files: FilesResponseDto[] with { id, name, contentType, url }
-    });
+  // Batch fetch — only requests IDs not already cached
+  loadMultiple(ids: string[]) {
+    this.fileUrlService.fetchFileUrls(ids).subscribe(files => { /* ... */ });
   }
-}
-```
-
-**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   |
-
-### PermissionValidatorService
-
-Signal-based permission state management. Used by `HasPermissionDirective`, permission guards, and IAM.
-
-```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']);
-
-    // Check single permission
-    if (this.permissionValidator.hasPermission('user.view')) {
-      // User has permission
-    }
-
-    // Check loaded state
-    if (this.permissionValidator.isPermissionsLoaded()) {
-      // Permissions have been loaded
-    }
+  // Synchronous read from cache after a prior fetch
+  getCachedUrl(id: string): string | null {
+    return this.fileUrlService.getFileUrl(id);
   }
 }
 ```
 
-**Methods:**
-
-| Method                       | Returns   | Description                        |
-| ---------------------------- | --------- | ---------------------------------- |
-| `setPermissions(codes[])`    | `void`    | Replace all permissions            |
-| `clearPermissions()`         | `void`    | Clear all permissions              |
-| `hasPermission(code)`        | `boolean` | Check single permission            |
-| `isPermissionsLoaded()`      | `boolean` | Whether permissions have been set  |
-
-**Signals:**
-
-| Signal        | Type               | Description                    |
-| ------------- | ------------------ | ------------------------------ |
-| `permissions` | `Signal<string[]>` | Readonly current permissions   |
-
-### CookieService
-
-SSR-aware cookie reading service.
-
-```typescript
-import { CookieService } from '@flusys/ng-shared';
-
-const cookies = inject(CookieService).get(); // Returns document.cookie (browser) or request header cookie (server)
-```
-
-### PlatformService
-
-SSR environment detection service.
-
-```typescript
-import { PlatformService } from '@flusys/ng-shared';
-
-const platform = inject(PlatformService);
-if (!platform.isServer) {
-  // Browser-only code (localStorage, window, etc.)
-}
-```
-
 ---
 
-## 4. Components
-
-### IconComponent
-
-Flexible icon renderer supporting PrimeNG icons, image files, and SVG.
-
-- **Selector:** `lib-icon`
-- **Inputs:** `icon` (required string), `iconType` (optional `IconTypeEnum`, default: `PRIMENG_ICON`)
-
-```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 -->
-<lib-icon icon="<svg>...</svg>" [iconType]="IconTypeEnum.DIRECT_TAG_SVG" />
-```
-
-### LazySelectComponent
-
-Single-select dropdown with lazy loading, search, and scroll pagination.
-
-- **Selector:** `lib-lazy-select`
-- **Extends:** `BaseFormControl<string | null>`
-- **Supports:** Template-driven, reactive forms, signal forms
+## 3. PermissionValidatorService + HasPermissionDirective
 
 ```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 });
-}
-```
-
-**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'`) |
-
-**Model:** `value` - Two-way bound selected value (`string | null`)
-
-**Outputs:** `onSearch` (debounced 500ms), `onPagination` (scroll-triggered)
-
-### LazyMultiSelectComponent
-
-Multi-select dropdown with lazy loading, search, select-all, and scroll pagination.
-
-- **Selector:** `lib-lazy-multi-select`
-- **Extends:** `BaseFormControl<string[] | null>`
-- **Supports:** Template-driven, reactive forms, signal forms
+const pv = inject(PermissionValidatorService);
 
-```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);
-}
-```
-
-**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)
-
-### UserSelectComponent
-
-Single user selection with lazy loading. Uses `USER_PROVIDER` internally or accepts custom `loadUsers` function.
-
-- **Selector:** `lib-user-select`
-- **Supports:** Template-driven, reactive forms, signal forms
-
-```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);
-}
+pv.hasPermission("user.create"); // true
+pv.hasPermission("report.export"); // true — wildcard match
+pv.isPermissionsLoaded(); // boolean
 ```
 
-**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`)
-
-**Outputs:** `userSelected` (IUserBasicInfo | null), `onError` (Error)
-
-### UserMultiSelectComponent
-
-Multiple user selection with lazy loading. Uses `USER_PROVIDER` internally or accepts custom `loadUsers` function.
-
-- **Selector:** `lib-user-multi-select`
-- **Supports:** Template-driven, reactive forms, signal forms
-
-```typescript
-@Component({
-  imports: [UserMultiSelectComponent],
-  template: `
-    <lib-user-multi-select
-      [(value)]="selectedUserIds"
-      [isEditMode]="true"
-    />
-  `,
-})
-export class MyComponent {
-  readonly selectedUserIds = signal<string[] | null>(null);
-}
-```
-
-**Inputs:** Same as `UserSelectComponent`.
-
-**Model:** `value` - Two-way bound selected user IDs (`string[] | null`)
-
-**Outputs:** `usersSelected` (IUserBasicInfo[]), `onError` (Error)
-
-### FileUploaderComponent
-
-Drag & drop file upload with type filtering. Pass your own `uploadFile` function.
-
-- **Selector:** `lib-file-uploader`
-
-```typescript
-@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)"
-    />
-  `,
-})
-export class MyComponent {
-  readonly uploadService = inject(UploadService);
-
-  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 |
-
-**Outputs:** `fileUploaded` (IUploadedFile), `filesUploaded` (IUploadedFile[]), `onError` (Error), `fileSelected` (File[])
-
-### FileSelectorDialogComponent
-
-Dialog to browse and select existing files with filtering.
-
-- **Selector:** `lib-file-selector-dialog`
-
-```typescript
-@Component({
-  imports: [FileSelectorDialogComponent],
-  template: `
-    <lib-file-selector-dialog
-      [(visible)]="showFileSelector"
-      [loadFiles]="loadFiles"
-      [acceptTypes]="['image/*']"
-      [multiple]="false"
-      (fileSelected)="onFileSelected($event)"
-    />
-  `,
-})
-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 },
-    });
-}
-```
-
-**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)
-
----
-
-## 5. Directives
-
-### HasPermissionDirective
-
-Structural directive for permission-based rendering. Fail-closed: hides content when permissions not loaded.
-
-- **Selector:** `[hasPermission]`
-- **Input:** `hasPermission` - `string | ILogicNode | null`
-
-```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)
-
-```html
-<input [appEditModeElementChanger] [isEditMode]="isEditing()" />
-<p-select [appEditModeElementChanger] [isEditMode]="isEditing()" />
-```
-
-### IsEmptyImageDirective
-
-Automatically replaces broken or empty image `src` with a default fallback image.
-
-- **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 -->
-```
-
-### PreventDefaultDirective
-
-Prevents default browser behavior on specified events and emits the event.
-
-- **Selector:** `[appPreventDefault]`
-- **Inputs:** `eventType` (`'click' | 'keydown' | 'keyup'`, default: `'click'`), `preventKey` (optional key filter)
-- **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)" />
+<!-- Removes element from DOM when permission fails -->
+<button *hasPermission="'user.create'">Create User</button>
 ```
 
 ---
 
-## 6. 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')] },
+## 4. Permission Guards
+
+```typescript
+import { permissionGuard, anyPermissionGuard, allPermissionsGuard } from "@flusys/ng-shared";
+
+export const routes: Routes = [
+  {
+    path: "users",
+    canActivate: [permissionGuard("user.view")], // single
+    loadComponent: () => import("./user-list.component"),
+  },
+  {
+    path: "reports",
+    canActivate: [anyPermissionGuard(["report.view", "report.export"])], // OR
+    loadComponent: () => import("./reports.component"),
+  },
+  {
+    path: "admin",
+    canActivate: [allPermissionsGuard(["admin.view", "admin.manage"])], // AND
+    loadComponent: () => import("./admin.component"),
+  },
 ];
 ```
 
-### 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'])] }
-```
+All three guards redirect to `/` by default. Pass a second argument to change it: `permissionGuard('user.view', '/access-denied')`.
 
 ---
 
-## 7. Utilities
-
-### Permission Evaluator
-
-Pure functions for permission logic evaluation. Used internally by `HasPermissionDirective` and guards.
-
-```typescript
-import { evaluatePermission, evaluateLogicNode, hasAnyPermission, hasAllPermissions } from '@flusys/ng-shared';
-
-const userPermissions = ['user.view', 'user.create'];
-
-// Evaluate string or ILogicNode
-evaluatePermission('user.view', userPermissions);     // true
-evaluatePermission(null, userPermissions);             // false
-
-// Evaluate ILogicNode tree recursively
-evaluateLogicNode(logicNode, userPermissions);
-
-// Simple OR/AND checks
-hasAnyPermission(['user.view', 'user.delete'], userPermissions);  // true (has user.view)
-hasAllPermissions(['user.view', 'user.delete'], userPermissions); // false (missing user.delete)
-```
-
----
-
-## 8. 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
-
----
-
-## 9. Modules
-
-### AngularModule
-
-Re-exports common Angular modules for convenience.
-
-```typescript
-import { AngularModule } from '@flusys/ng-shared';
-// Includes: CommonModule, FormsModule, ReactiveFormsModule, RouterLink, RouterOutlet, + directives
-// Providers: DatePipe
-```
-
-### PrimeModule
-
-Re-exports PrimeNG component modules for convenience.
-
-```typescript
-import { PrimeModule } from '@flusys/ng-shared';
-// Includes: Button, Table, Card, Dialog, InputText, Select, MultiSelect,
-// DatePicker, Checkbox, FileUpload, Image, Tag, Tabs, TreeTable, and more (27 modules)
-```
-
----
-
-## 10. 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>>;
-}
-```
-
-#### 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>>;
-}
-```
-
-#### IUserPermissionProvider / `USER_PERMISSION_PROVIDER`
-
-User permission queries for IAM.
-
-```typescript
-interface IUserPermissionProvider {
-  getUserBranchPermissions(userId: string): Observable<ISingleResponse<any>>;
-}
-```
-
-#### IProfileUploadProvider / `PROFILE_UPLOAD_PROVIDER`
-
-Profile picture upload for ng-auth profile page. Implemented by ng-storage.
-
-```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>>;
-}
-```
-
-#### IProfilePermissionProvider / `PROFILE_PERMISSION_PROVIDER`
-
-User permission queries for ng-auth profile page. Implemented by ng-iam.
-
-```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[]>>;
-}
-```
-
-### 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, `reload()` to refresh
-- Use async methods (`insertAsync`, `updateAsync`) for one-off operations
-
-### 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
-
----
-
-## Common Issues
-
-### ApiResourceService Not Updating UI
-
-**Problem:** UI doesn't update after operations.
-
-**Solution:** Use signal syntax in templates:
+## 5. TranslatePipe
 
 ```html
-<!-- Correct -->
-<div>{{ users() }}</div>
-
-<!-- Wrong -->
-<div>{{ users }}</div>
+{{ 'shared.save' | translate }} {{ 'pagination.showing' | translate: { from: 1, to: 10 } }}
 ```
 
-### 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.
-
----
-
-## API Reference
-
-### Services
-
-| Service                        | Description                           |
-| ------------------------------ | ------------------------------------- |
-| `ApiResourceService<DTO, T>`   | Signal-based CRUD with resource() API |
-| `FileUrlService`               | Cloud storage URL fetching            |
-| `PermissionValidatorService`   | Permission state management           |
-| `CookieService`                | SSR-aware cookie reading              |
-| `PlatformService`              | SSR environment detection             |
-
-### 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     |
-| `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            |
-
-### Injection Tokens
-
-| Token                      | Interface                 | Description                  |
-| -------------------------- | ------------------------- | ---------------------------- |
-| `USER_PROVIDER`            | `IUserProvider`           | User list for IAM            |
-| `COMPANY_API_PROVIDER`     | `ICompanyApiProvider`     | Company list for IAM         |
-| `USER_PERMISSION_PROVIDER` | `IUserPermissionProvider` | User permission queries      |
-| `PROFILE_UPLOAD_PROVIDER`  | `IProfileUploadProvider`  | Profile picture upload (ng-storage) |
-| `PROFILE_PERMISSION_PROVIDER` | `IProfilePermissionProvider` | User permissions for profile (ng-iam) |
-
-## 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-02-16
-**Angular Version:** 21
+MIT © FLUSYS