@flusys/ng-shared 1.0.1 → 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;
@@ -310,7 +312,46 @@ 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
 
@@ -525,7 +566,7 @@ if (!platform.isServer) {
 
 ---
 
-## 4. Components
+## 5. Components
 
 ### IconComponent
 
@@ -806,7 +847,7 @@ export class MyComponent {
 
 ---
 
-## 5. Directives
+## 6. Directives
 
 ### HasPermissionDirective
 
@@ -880,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).
 
@@ -928,7 +969,7 @@ AND logic - allows access only if user has ALL specified permissions.
 
 ---
 
-## 7. Utilities
+## 8. Utilities
 
 ### Permission Evaluator
 
@@ -951,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
 
@@ -989,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
 
@@ -1015,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.
 
@@ -1336,6 +1471,25 @@ export const appConfig: ApplicationConfig = {
 | `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               |
@@ -1416,5 +1570,6 @@ export const appConfig: ApplicationConfig = {
 
 ---
 
-**Last Updated:** 2026-02-22
+**Last Updated:** 2026-02-23
+**Version:** 1.1.0
 **Angular Version:** 21

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "@flusys/ng-shared",
-  "version": "1.0.1",
+  "version": "1.1.0",
   "description": "Shared components and utilities for FLUSYS Angular packages",
   "license": "MIT",
   "peerDependencies": {
     "@angular/common": ">=21.0.0",
     "@angular/core": ">=21.0.0",
     "@angular/forms": ">=21.0.0",
-    "@flusys/ng-core": ">=1.0.1",
+    "@flusys/ng-core": ">=1.1.0",
     "@primeuix/themes": ">=1.0.0",
     "primeicons": ">=7.0.0",
     "primeng": ">=21.0.0"