@flusys/ng-shared 3.0.0-rc → 3.0.1

package/README.md

@@ -9,6 +9,7 @@
 ## Package Information
 
 - **Package:** `@flusys/ng-shared`
+- **Version:** 3.0.1
 - **Dependencies:** ng-core
 - **Dependents:** ng-layout, ng-auth, ng-iam, ng-storage, flusysng
 - **Build Command:** `npm run build:ng-shared`
@@ -37,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
 
@@ -73,8 +74,14 @@ interface IPagination {
   currentPage: number;
 }
 
-interface ISort { [key: string]: 'ASC' | 'DESC' }
-interface IFilter { [key: string]: any }
+interface ISort {
+  [key: string]: "ASC" | "DESC";
+}
+
+// Filter supports primitives and arrays for multi-value filtering
+interface IFilter {
+  [key: string]: string | number | boolean | null | undefined | string[] | number[];
+}
 
 interface IFilterData {
   filter?: IFilter;
@@ -86,15 +93,17 @@ interface IFilterData {
 }
 ```
 
+**Note:** `IFilter` supports array values (`string[]`, `number[]`) for multi-value filtering (e.g., filtering by multiple status values or IDs).
+
 #### IDeleteData
 
 Delete request payload matching backend DeleteDto.
 
 ```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;
 }
 ```
@@ -117,7 +126,6 @@ interface IUserSelectFilter {
   page: number;
   pageSize: number;
   search: string;
-  [key: string]: unknown;
 }
 
 type LoadUsersFn = (filter: IUserSelectFilter) => Observable<IListResponse<IUserBasicInfo>>;
@@ -144,6 +152,7 @@ interface IFileUploadOptions {
 }
 
 interface IUploadedFile {
+  id?: string; // File manager ID (UUID) - available when registered
   name: string;
   key: string;
   size: number;
@@ -156,7 +165,6 @@ interface IFileSelectFilter {
   search: string;
   contentTypes?: string[];
   folderId?: string;
-  [key: string]: unknown;
 }
 
 type LoadFilesFn = (filter: IFileSelectFilter) => Observable<IListResponse<IFileBasicInfo>>;
@@ -167,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
@@ -234,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
 
@@ -267,6 +275,14 @@ interface IFileData {
   thumbnailUrl?: string;
   createdAt: Date;
 }
+
+// File URL service response DTO
+interface FilesResponseDto {
+  id: string;
+  name: string;
+  contentType: string;
+  url: string | null;
+}
 ```
 
 ### Permission Interfaces
@@ -276,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[];
 }
 
@@ -310,58 +326,149 @@ enum IconTypeEnum {
 
 ---
 
-## 3. Services
+## 3. Constants
+
+### Permission Constants
+
+Centralized permission codes for type-safe permission checks. Single source of truth to prevent typos.
+
+```typescript
+import { PERMISSIONS, USER_PERMISSIONS, ROLE_PERMISSIONS } from '@flusys/ng-shared';
+
+// Use constants instead of strings
+*hasPermission="PERMISSIONS.USER.READ"
+
+// Individual permission groups available:
+USER_PERMISSIONS     // { CREATE, READ, UPDATE, DELETE }
+COMPANY_PERMISSIONS  // { CREATE, READ, UPDATE, DELETE }
+BRANCH_PERMISSIONS   // { CREATE, READ, UPDATE, DELETE }
+ACTION_PERMISSIONS   // { CREATE, READ, UPDATE, DELETE }
+ROLE_PERMISSIONS     // { CREATE, READ, UPDATE, DELETE }
+ROLE_ACTION_PERMISSIONS   // { READ, ASSIGN }
+USER_ROLE_PERMISSIONS     // { READ, ASSIGN }
+USER_ACTION_PERMISSIONS   // { READ, ASSIGN }
+COMPANY_ACTION_PERMISSIONS // { READ, ASSIGN }
+FILE_PERMISSIONS     // { CREATE, READ, UPDATE, DELETE }
+FOLDER_PERMISSIONS   // { CREATE, READ, UPDATE, DELETE }
+STORAGE_CONFIG_PERMISSIONS  // { CREATE, READ, UPDATE, DELETE }
+EMAIL_CONFIG_PERMISSIONS    // { CREATE, READ, UPDATE, DELETE }
+EMAIL_TEMPLATE_PERMISSIONS  // { CREATE, READ, UPDATE, DELETE }
+FORM_PERMISSIONS     // { CREATE, READ, UPDATE, DELETE }
+
+// Aggregated object with all permissions
+PERMISSIONS.USER.READ     // 'user.read'
+PERMISSIONS.ROLE.CREATE   // 'role.create'
+PERMISSIONS.FILE.DELETE   // 'file.delete'
+```
+
+**Type:** `PermissionCode` - Union type of all valid permission code strings.
+
+---
+
+## 4. Services
 
 ### ApiResourceService
 
-Signal-based CRUD service using Angular 21 `resource()` API. All endpoints use POST (RPC-style).
+Signal-based CRUD service using Angular 21 `resource()` API with **lazy initialization**. All endpoints use POST (RPC-style).
+
+**ServiceName Type:**
+
+```typescript
+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) {
-    super('users', http); // Base URL: APP_CONFIG.apiBaseUrl + '/users'
+    // Option 1: Use global apiBaseUrl (default)
+    super("users", http);
+    // Base URL: APP_CONFIG.apiBaseUrl + '/users'
+
+    // Option 2: Use feature-specific service URL (recommended)
+    super("users", http, "administration");
+    // Base URL: APP_CONFIG.services.administration.baseUrl + '/users'
   }
 }
 ```
 
+**Constructor Parameters:**
+
+| Parameter       | Type          | Required | Description                                      |
+| --------------- | ------------- | -------- | ------------------------------------------------ |
+| `moduleApiName` | `string`      | Yes      | API path segment (e.g., 'users', 'file-manager') |
+| `http`          | `HttpClient`  | Yes      | Angular HttpClient instance                      |
+| `serviceName`   | `ServiceName` | No       | Feature service name for URL resolution          |
+
+**Service URL Resolution:**
+
+- If `serviceName` is provided, uses `getServiceUrl(config, serviceName)` to resolve the base URL
+- Falls back to `APP_CONFIG.apiBaseUrl` if service not found or `serviceName` not provided
+
+**Lazy Initialization:**
+
+The list resource is **lazy-initialized** to avoid unnecessary HTTP requests on service construction. The resource is only created when first needed:
+
+```typescript
+// Resource is NOT created until one of these is called:
+userService.fetchList("", { pagination: { currentPage: 0, pageSize: 10 } });
+// OR
+userService.initListResource(); // Explicit initialization
+```
+
+**Internal resource structure:**
+
+```typescript
+private _listResource: ResourceRef<IListResponse<InterfaceT> | undefined> | null = null;
+private _resourceInitialized = false;
+private readonly _resourceInitSignal = signal(false);
+
+// Initialize the list resource (called automatically by fetchList)
+initListResource(): void {
+  if (this._resourceInitialized) return;
+  this._resourceInitialized = true;
+  this._resourceInitSignal.set(true);
+  // Creates the resource with linkedSignal for data, isLoading, etc.
+}
+```
+
 **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 });
@@ -424,18 +531,18 @@ 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
 
-Signal-based permission state management. Used by `HasPermissionDirective`, permission guards, and IAM.
+Signal-based permission state management. Used by `HasPermissionDirective`, permission guards, and IAM. Supports **wildcard permissions**.
 
 ```typescript
 import { PermissionValidatorService } from '@flusys/ng-shared';
@@ -453,8 +560,8 @@ export class MyComponent {
       // User has permission
     }
 
-    // Check loaded state
-    if (this.permissionValidator.isPermissionsLoaded()) {
+    // Check loaded state (signal-based)
+    if (this.permissionValidator.isLoaded()) {
       // Permissions have been loaded
     }
   }
@@ -463,25 +570,41 @@ export class MyComponent {
 
 **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  |
+| 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:**
+
+The `hasPermission()` method uses the permission evaluator utility which supports wildcards:
+
+```typescript
+// Exact match
+hasPermission("user.read"); // true if permissions include 'user.read'
+
+// Global wildcard
+hasPermission("user.read"); // true if permissions include '*'
+
+// Module wildcard
+hasPermission("user.read"); // true if permissions include 'user.*'
+```
 
 ### CookieService
 
 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)
 ```
@@ -491,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) {
@@ -501,7 +624,7 @@ if (!platform.isServer) {
 
 ---
 
-## 4. Components
+## 5. Components
 
 ### IconComponent
 
@@ -532,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);
@@ -559,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`)
 
@@ -585,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);
@@ -622,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 {
@@ -642,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`)
 
@@ -665,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);
@@ -694,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[])
 
@@ -744,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);
@@ -767,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`)
 
@@ -782,7 +847,7 @@ export class MyComponent {
 
 ---
 
-## 5. Directives
+## 6. Directives
 
 ### HasPermissionDirective
 
@@ -792,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],
@@ -806,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" },
     ],
   };
 }
@@ -824,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
@@ -850,13 +914,12 @@ 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)" />
 ```
 
 ---
 
-## 6. Guards
+## 7. Guards
 
 Route-level guards for permission-based access control. All guards deny access when permissions are not loaded (fail-closed).
 
@@ -865,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")] },
 ];
 ```
 
@@ -904,42 +972,103 @@ AND logic - allows access only if user has ALL specified permissions.
 
 ---
 
-## 7. Utilities
+## 8. Utilities
 
 ### Permission Evaluator
 
-Pure functions for permission logic evaluation. Used internally by `HasPermissionDirective` and guards.
+Pure functions for permission logic evaluation. Used internally by `HasPermissionDirective` and guards. **Supports wildcard permissions.**
 
 ```typescript
-import { evaluatePermission, evaluateLogicNode, hasAnyPermission, hasAllPermissions } 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'];
+// Low-level hasPermission check with wildcard support
+hasPermission("user.view", userPermissions); // true (exact match)
+hasPermission("admin.manage", userPermissions); // true (matches 'admin.*')
+hasPermission("settings.view", ["*"]); // true (global wildcard)
 
 // Evaluate string or ILogicNode
-evaluatePermission('user.view', userPermissions);     // true
-evaluatePermission(null, userPermissions);             // false
+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)
+// Simple OR/AND checks (also support wildcards)
+hasAnyPermission(["user.view", "user.delete"], userPermissions); // true (has user.view)
+hasAllPermissions(["user.view", "user.delete"], userPermissions); // false (missing user.delete)
+```
+
+**Wildcard Rules:**
+
+| Pattern     | Matches                                 |
+| ----------- | --------------------------------------- |
+| `*`         | All permissions (global wildcard)       |
+| `module.*`  | All permissions starting with `module.` |
+| `user.read` | Exact match only                        |
+
+**Implementation Details:**
+
+```typescript
+export function hasPermission(requiredPermission: string, userPermissions: string[]): boolean {
+  // Exact match
+  if (userPermissions.includes(requiredPermission)) return true;
+
+  // Wildcard matching
+  for (const permission of userPermissions) {
+    // Global wildcard
+    if (permission === "*") return true;
+
+    // Module wildcard (e.g., 'user.*' matches 'user.read')
+    if (permission.endsWith(".*")) {
+      const prefix = permission.slice(0, -1); // 'user.'
+      if (requiredPermission.startsWith(prefix)) return true;
+    }
+  }
+
+  return false;
+}
+```
+
+### Scroll Pagination
+
+Utility for lazy-loading dropdowns with scroll detection.
+
+```typescript
+import { checkScrollPagination, ScrollPaginationConfig } from '@flusys/ng-shared';
+
+// In a component
+onScroll(event: Event): void {
+  const nextPagination = checkScrollPagination(event, {
+    pagination: this.pagination(),
+    total: this.total(),
+    isLoading: this.isLoading(),
+    threshold: 50, // pixels from bottom (default: 50)
+  });
+  if (nextPagination) {
+    this.onPagination.emit(nextPagination);
+  }
+}
 ```
 
+**Interface:** `ScrollPaginationConfig` - `{ threshold?, pagination, total, isLoading }`
+
+**Returns:** `IPagination | null` - Next page pagination or null if not needed.
+
 ---
 
-## 8. Classes
+## 9. Classes
 
 ### BaseFormControl
 
 Abstract base class for custom form controls. Implements both `ControlValueAccessor` (reactive forms) and `FormValueControl` (signal forms).
 
 ```typescript
-import { BaseFormControl, provideValueAccessor } from '@flusys/ng-shared';
+import { BaseFormControl, provideValueAccessor } from "@flusys/ng-shared";
 
 @Component({
-  selector: 'my-select',
+  selector: "my-select",
   providers: [provideValueAccessor(MySelectComponent)],
 })
 export class MySelectComponent extends BaseFormControl<string | null> {
@@ -965,17 +1094,87 @@ export class MySelectComponent extends BaseFormControl<string | null> {
 
 **Helper:** `provideValueAccessor(ComponentClass)` - Factory for `NG_VALUE_ACCESSOR` provider
 
+### BaseFormPage
+
+Abstract directive for form page components (create/edit).
+
+```typescript
+import { BaseFormPage } from '@flusys/ng-shared';
+
+@Component({ ... })
+export class ProductFormComponent extends BaseFormPage<IProduct, IProductFormModel> {
+  private readonly productService = inject(ProductApiService);
+  private readonly _formModel = signal<IProductFormModel>({ name: '', price: 0 });
+  readonly formModel = this._formModel.asReadonly();
+
+  getFormModel(): Signal<IProductFormModel> { return this.formModel; }
+  getResourceRoute(): string { return '/products'; }
+  getResourceName(): string { return 'Product'; }
+  isFormValid(): boolean { return this.formModel().name.trim().length > 0; }
+
+  loadItem(id: string): void {
+    this.productService.findById(id).subscribe(res => {
+      if (res.success && res.data) {
+        this.existingItem.set(res.data);
+        this._formModel.set({ name: res.data.name, price: res.data.price });
+      }
+    });
+  }
+
+  createItem(model: IProductFormModel): Observable<unknown> {
+    return this.productService.insert(model);
+  }
+
+  updateItem(model: IProductFormModel): Observable<unknown> {
+    return this.productService.update({ id: this.existingItem()!.id, ...model });
+  }
+}
+```
+
+**Signals:** `isLoading`, `existingItem`, `isEditMode` (computed)
+
+**Methods:** `onSubmit()`, `onCancel()`, `showSuccess()`, `showError()`, `showValidationError()`
+
+### BaseListPage
+
+Abstract directive for list page components with pagination and CRUD operations.
+
+```typescript
+import { BaseListPage } from '@flusys/ng-shared';
+
+@Component({ ... })
+export class UserListComponent extends BaseListPage<IUser> {
+  private readonly userService = inject(UserApiService);
+
+  getResourceRoute(): string { return '/users'; }
+  getDeleteConfirmMessage(user: IUser): string { return `Delete "${user.name}"?`; }
+
+  async loadData(): Promise<void> {
+    this.isLoading.set(true);
+    const res = await this.userService.findByIdAsync(...);
+    this.items.set(res.data ?? []);
+    this.total.set(res.meta?.total ?? 0);
+    this.isLoading.set(false);
+  }
+}
+```
+
+**Signals:** `items`, `isLoading`, `total`, `pageSize`, `first`, `currentPage` (computed), `showCompanyInfo` (computed)
+
+**Methods:** `onCreate()`, `onEdit(id)`, `onPageChange(event)`, `onDelete()`, `onDeleteAsync()`, `showSuccess()`, `showError()`, `showInfo()`, `showWarn()`
+
 ---
 
-## 9. Modules
+## 10. Modules
 
 ### AngularModule
 
 Re-exports common Angular modules for convenience.
 
 ```typescript
-import { AngularModule } from '@flusys/ng-shared';
-// Includes: CommonModule, FormsModule, ReactiveFormsModule, RouterLink, RouterOutlet, + directives
+import { AngularModule } from "@flusys/ng-shared";
+// Includes: CommonModule, FormsModule, ReactiveFormsModule, RouterLink, RouterOutlet,
+// RouterLinkActive, NgOptimizedImage, NgComponentOutlet, + directives (IsEmptyImageDirective, PreventDefaultDirective)
 // Providers: DatePipe
 ```
 
@@ -984,14 +1183,22 @@ import { AngularModule } from '@flusys/ng-shared';
 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)
+import { PrimeModule } from "@flusys/ng-shared";
+// Includes 30 modules:
+// - Layout: AccordionModule, CardModule, DividerModule, PanelModule, SplitterModule, TabsModule, ToolbarModule
+// - Form: AutoCompleteModule, CheckboxModule, DatePickerModule, InputTextModule, InputTextareaModule,
+//         MultiSelectModule, RadioButtonModule, SelectModule, ToggleSwitchModule
+// - Button: ButtonModule, SpeedDialModule, SplitButtonModule
+// - Data: PaginatorModule, TableModule, TreeTableModule
+// - Overlay: DialogModule, DrawerModule, PopoverModule, TooltipModule
+// - File: FileUploadModule
+// - Media: ImageModule
+// - Misc: BadgeModule, TagModule
 ```
 
 ---
 
-## 10. Provider Interfaces (Package Independence)
+## 11. Provider Interfaces (Package Independence)
 
 ng-shared defines **provider interfaces** to enable feature packages (ng-iam, ng-storage) to access auth functionality without direct dependencies.
 
@@ -1012,50 +1219,65 @@ 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>>;
 }
 ```
 
+**Token Error Message:** `'USER_PROVIDER not configured. Please provide an implementation in app.config.ts'`
+
 #### ICompanyApiProvider / `COMPANY_API_PROVIDER`
 
 Company list access for IAM company selection.
 
 ```typescript
-interface ICompanyBasicInfo { id: string; name: string; slug?: string }
+interface 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>>;
 }
 ```
 
+**Token Error Message:** `'COMPANY_API_PROVIDER not configured. Please provide an implementation in app.config.ts'`
+
 #### IUserPermissionProvider / `USER_PERMISSION_PROVIDER`
 
 User permission queries for IAM.
 
 ```typescript
+interface IUserBranchPermission {
+  branchId: string;
+  branchName: string;
+  permissions: string[];
+}
+
 interface IUserPermissionProvider {
-  getUserBranchPermissions(userId: string): Observable<ISingleResponse<any>>;
+  getUserBranchPermissions(userId: string): Observable<ISingleResponse<IUserBranchPermission[]>>;
 }
 ```
 
+**Token Error Message:** `'USER_PERMISSION_PROVIDER not configured. Please provide an implementation in app.config.ts'`
+
 #### IProfileUploadProvider / `PROFILE_UPLOAD_PROVIDER`
 
-Profile picture upload for ng-auth profile page. Implemented by ng-storage.
+Profile picture upload for ng-auth profile page. 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
+  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
 }
 
@@ -1067,16 +1289,13 @@ interface IProfileUploadOptions {
 }
 
 interface IProfileUploadProvider {
-  uploadProfilePicture(
-    file: File,
-    options?: IProfileUploadOptions
-  ): Observable<ISingleResponse<IProfileUploadResult>>;
+  uploadProfilePicture(file: File, options?: IProfileUploadOptions): Observable<ISingleResponse<IProfileUploadResult>>;
 }
 ```
 
 #### IProfilePermissionProvider / `PROFILE_PERMISSION_PROVIDER`
 
-User permission queries for ng-auth profile page. Implemented by ng-iam.
+User permission queries for ng-auth profile page. Implemented by ng-iam. **Optional token** - use with `inject(..., { optional: true })`.
 
 ```typescript
 interface IProfileRoleInfo {
@@ -1112,6 +1331,8 @@ interface IAuthStateProvider {
 }
 ```
 
+**Token Error Message:** `'AUTH_STATE_PROVIDER not configured. Please provide an implementation in app.config.ts'`
+
 **Usage:**
 
 ```typescript
@@ -1133,7 +1354,7 @@ export class PublicFormComponent {
 
 #### IUserListProvider / `USER_LIST_PROVIDER`
 
-Extends user list pages with extra columns, actions, and data enrichment. Optional provider.
+Extends user list pages with extra columns, actions, and data enrichment. **Optional token** - use with `inject(..., { optional: true })`.
 
 ```typescript
 interface IUserListItem {
@@ -1142,14 +1363,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);
@@ -1161,7 +1381,16 @@ interface IUserListColumn {
   header: string;
   width?: string;
   sortable?: boolean;
-  templateType?: 'text' | 'badge' | 'date' | 'boolean' | 'custom';
+  templateType?: "text" | "badge" | "date" | "boolean" | "custom";
+}
+
+interface IUserListFilter {
+  page?: number;
+  pageSize?: number;
+  search?: string;
+  isActive?: boolean;
+  companyId?: string;
+  branchId?: string;
 }
 
 interface IUserListProvider<T extends IUserListItem = IUserListItem> {
@@ -1178,17 +1407,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" }];
   }
 }
 ```
@@ -1196,13 +1421,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 ?? []);
     });
   }
@@ -1213,7 +1438,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: [
@@ -1236,8 +1461,9 @@ export const appConfig: ApplicationConfig = {
 
 - **Extend `ApiResourceService`** for new services (signal-based)
 - Use reactive signals (`data`, `isLoading`, `total`) in templates
-- Use `fetchList()` to trigger queries, `reload()` to refresh
+- Use `fetchList()` to trigger queries (also initializes resource), `reload()` to refresh
 - Use async methods (`insertAsync`, `updateAsync`) for one-off operations
+- Resource is lazy-initialized - no HTTP requests until first `fetchList()` or `initListResource()`
 
 ### File URLs
 
@@ -1263,6 +1489,7 @@ export const appConfig: ApplicationConfig = {
 - Use permission guards for route-level access control
 - Use `PermissionValidatorService` for programmatic checks in services
 - Permissions follow fail-closed model: no access by default
+- Wildcards supported: `*` (all), `module.*` (module-scoped)
 
 ---
 
@@ -1298,89 +1525,142 @@ export const appConfig: ApplicationConfig = {
 
 **Solution:** ng-shared must NEVER import from ng-layout. Move shared components to ng-shared, layout-specific components to ng-layout.
 
+### Provider Token Errors
+
+**Problem:** `'XXX_PROVIDER not configured'` error at runtime.
+
+**Solution:** Ensure the provider is registered in `app.config.ts`:
+
+```typescript
+// Required providers
+providers: [
+  { provide: USER_PROVIDER, useClass: AuthUserProvider },
+  { provide: COMPANY_API_PROVIDER, useClass: AuthCompanyApiProvider },
+  { provide: USER_PERMISSION_PROVIDER, useClass: AuthUserPermissionProvider },
+  { provide: AUTH_STATE_PROVIDER, useClass: AuthStateProviderAdapter },
+];
+
+// OR use the convenience function
+providers: [...provideAuthProviders()];
+```
+
+### Permissions Not Working
+
+**Problem:** `hasPermission()` returns false even though user should have access.
+
+**Solution:**
+
+1. Check if permissions are loaded: `permissionValidator.isLoaded()`
+2. Verify permission codes match exactly (case-sensitive)
+3. For wildcard access, ensure user has `*` or `module.*` in their permissions
+
 ---
 
 ## API Reference
 
 ### Services
 
-| Service                        | Description                           |
-| ------------------------------ | ------------------------------------- |
-| `ApiResourceService<DTO, T>`   | Signal-based CRUD with resource() API |
-| `FileUrlService`               | Cloud storage URL fetching            |
-| `PermissionValidatorService`   | Permission state management           |
-| `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                  |
+
+### Constants
+
+| Constant            | Description                                           |
+| ------------------- | ----------------------------------------------------- |
+| `PERMISSIONS`       | Aggregated permission codes by module                 |
+| `USER_PERMISSIONS`  | `{ CREATE, READ, UPDATE, DELETE }` for users          |
+| `ROLE_PERMISSIONS`  | `{ CREATE, READ, UPDATE, DELETE }` for roles          |
+| `FILE_PERMISSIONS`  | `{ CREATE, READ, UPDATE, DELETE }` for files          |
+| `FILE_TYPE_FILTERS` | Predefined MIME type arrays (IMAGES, DOCUMENTS, etc.) |
 
 ### Components
 
-| Component                  | Selector               | Description               |
-| -------------------------- | ---------------------- | ------------------------- |
-| `IconComponent`            | `lib-icon`             | Flexible icon renderer    |
-| `LazySelectComponent`      | `lib-lazy-select`      | Lazy-loading dropdown     |
-| `LazyMultiSelectComponent` | `lib-lazy-multi-select`| Lazy-loading multi-select |
-| `UserSelectComponent`      | `lib-user-select`      | Single user selector      |
-| `UserMultiSelectComponent` | `lib-user-multi-select`| Multiple user selector    |
-| `FileUploaderComponent`    | `lib-file-uploader`    | Drag & drop file upload   |
-| `FileSelectorDialogComponent` | `lib-file-selector-dialog` | File browser dialog |
+| 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     |
-| `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            |
-| `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           |
+| 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'` |
 
 ### 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) |
-| `AUTH_STATE_PROVIDER`      | `IAuthStateProvider`      | Auth state for feature packages |
-| `USER_LIST_PROVIDER`       | `IUserListProvider`       | User list extensions (optional) |
+| 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                  |
 
 ## See Also
 
@@ -1391,5 +1671,6 @@ export const appConfig: ApplicationConfig = {
 
 ---
 
-**Last Updated:** 2026-02-21
+**Last Updated:** 2026-02-25
+**Version:** 3.0.1
 **Angular Version:** 21