@flusys/ng-shared 1.1.0-beta → 1.1.0

package/README.md

@@ -9,6 +9,7 @@
 ## Package Information
 
 - **Package:** `@flusys/ng-shared`
+- **Version:** 1.1.0
 - **Dependencies:** ng-core
 - **Dependents:** ng-layout, ng-auth, ng-iam, ng-storage, flusysng
 - **Build Command:** `npm run build:ng-shared`
@@ -144,6 +145,7 @@ interface IFileUploadOptions {
 }
 
 interface IUploadedFile {
+  id?: string;         // File manager ID (UUID) - available when registered
   name: string;
   key: string;
   size: number;
@@ -178,7 +180,7 @@ FILE_TYPE_FILTERS.ALL        // [] (allows all)
 getAcceptString(['image/*'])           // 'image/*'
 isFileTypeAllowed(file, ['image/*'])   // true/false
 getFileIconClass('image/png')          // 'pi pi-image'
-formatFileSize('1024')                 // '1 KB'
+formatFileSize(1024)                   // '1 KB'
 ```
 
 ### Response Interfaces
@@ -310,12 +312,57 @@ 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).
 
+**ServiceName Type:**
+
+```typescript
+type ServiceName = 'auth' | 'administration' | 'iam' | 'storage' | 'formBuilder' | 'email';
+```
+
 **Define a service:**
 
 ```typescript
@@ -326,11 +373,29 @@ 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'
+    // 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
+
 **Endpoint mapping:**
 
 | Method         | HTTP | Endpoint                  | Response                 |
@@ -501,7 +566,7 @@ if (!platform.isServer) {
 
 ---
 
-## 4. Components
+## 5. Components
 
 ### IconComponent
 
@@ -517,7 +582,7 @@ Flexible icon renderer supporting PrimeNG icons, image files, and SVG.
 <!-- Image file -->
 <lib-icon icon="/assets/logo.png" [iconType]="IconTypeEnum.IMAGE_FILE_LINK" />
 
-<!-- SVG tag -->
+<!-- SVG tag (shows fallback icon - full SVG rendering coming soon) -->
 <lib-icon icon="<svg>...</svg>" [iconType]="IconTypeEnum.DIRECT_TAG_SVG" />
 ```
 
@@ -782,7 +847,7 @@ export class MyComponent {
 
 ---
 
-## 5. Directives
+## 6. Directives
 
 ### HasPermissionDirective
 
@@ -856,7 +921,7 @@ Prevents default browser behavior on specified events and emits the event.
 
 ---
 
-## 6. Guards
+## 7. Guards
 
 Route-level guards for permission-based access control. All guards deny access when permissions are not loaded (fail-closed).
 
@@ -904,7 +969,7 @@ AND logic - allows access only if user has ALL specified permissions.
 
 ---
 
-## 7. Utilities
+## 8. Utilities
 
 ### Permission Evaluator
 
@@ -927,9 +992,34 @@ hasAnyPermission(['user.view', 'user.delete'], userPermissions);  // true (has u
 hasAllPermissions(['user.view', 'user.delete'], userPermissions); // false (missing user.delete)
 ```
 
+### 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
 
@@ -965,9 +1055,78 @@ 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
 
@@ -991,7 +1150,7 @@ import { PrimeModule } from '@flusys/ng-shared';
 
 ---
 
-## 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.
 
@@ -1098,6 +1257,101 @@ interface IProfilePermissionProvider {
 }
 ```
 
+#### IAuthStateProvider / `AUTH_STATE_PROVIDER`
+
+Auth state access for feature packages (form-builder, etc.) that need to check authentication without depending on ng-auth directly.
+
+```typescript
+interface IAuthStateProvider {
+  /** Signal indicating if user is currently authenticated */
+  isAuthenticated: Signal<boolean>;
+
+  /** Initialize auth state (restore session from cookies/storage) */
+  initialize(): Observable<void>;
+}
+```
+
+**Usage:**
+
+```typescript
+import { AUTH_STATE_PROVIDER } from '@flusys/ng-shared';
+
+@Component({...})
+export class PublicFormComponent {
+  private readonly authState = inject(AUTH_STATE_PROVIDER);
+
+  ngOnInit() {
+    this.authState.initialize().subscribe(() => {
+      if (this.authState.isAuthenticated()) {
+        // User is logged in
+      }
+    });
+  }
+}
+```
+
+#### IUserListProvider / `USER_LIST_PROVIDER`
+
+Extends user list pages with extra columns, actions, and data enrichment. Optional provider.
+
+```typescript
+interface IUserListItem {
+  id: string;
+  name: string;
+  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';
+  permission?: string;
+  tooltip?: string;
+  disabled?: boolean | ((user: T) => boolean);
+  visible?: boolean | ((user: T) => boolean);
+}
+
+interface IUserListColumn {
+  field: string;
+  header: string;
+  width?: string;
+  sortable?: boolean;
+  templateType?: 'text' | 'badge' | 'date' | 'boolean' | 'custom';
+}
+
+interface IUserListProvider<T extends IUserListItem = IUserListItem> {
+  getExtraColumns?(): IUserListColumn[];
+  getExtraRowActions?(): IUserListAction<T>[];
+  getExtraToolbarActions?(): IUserListAction<T>[];
+  onRowAction?(actionId: string, user: T): void;
+  onToolbarAction?(actionId: string, selectedUsers: T[]): void;
+  enrichListData?(users: T[]): Observable<T[]>;
+}
+```
+
+**Usage:**
+
+```typescript
+// In app.config.ts
+providers: [
+  { provide: USER_LIST_PROVIDER, useClass: MyUserListProvider },
+]
+
+// Implementation
+@Injectable({ providedIn: 'root' })
+export class MyUserListProvider implements IUserListProvider {
+  getExtraRowActions() {
+    return [
+      { id: 'assign-role', label: 'Assign Role', icon: 'pi pi-users' },
+    ];
+  }
+}
+```
+
 ### Usage in Consuming Packages
 
 ```typescript
@@ -1211,12 +1465,31 @@ export const appConfig: ApplicationConfig = {
 
 | Service                        | Description                           |
 | ------------------------------ | ------------------------------------- |
-| `ApiResourceService<DTO, T>`   | Signal-based CRUD with resource() API |
+| `ApiResourceService<DTO, T>`   | Signal-based CRUD with resource() API (accepts optional `serviceName` for feature-specific URLs) |
 | `FileUrlService`               | Cloud storage URL fetching            |
 | `PermissionValidatorService`   | Permission state management           |
 | `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               |
@@ -1269,6 +1542,12 @@ export const appConfig: ApplicationConfig = {
 | `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           |
+| `ServiceName`       | `'auth' \| 'administration' \| 'iam' \| 'storage' \| 'formBuilder' \| 'email'` |
 
 ### Injection Tokens
 
@@ -1279,6 +1558,8 @@ export const appConfig: ApplicationConfig = {
 | `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) |
 
 ## See Also
 
@@ -1289,5 +1570,6 @@ export const appConfig: ApplicationConfig = {
 
 ---
 
-**Last Updated:** 2026-02-16
+**Last Updated:** 2026-02-23
+**Version:** 1.1.0
 **Angular Version:** 21