@flusys/ng-shared 1.0.0-beta → 1.1.1-beta

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "@flusys/ng-shared",
-  "version": "1.0.0-beta",
+  "version": "1.1.1-beta",
   "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.0-beta",
+    "@flusys/ng-core": "^1.1.1-beta",
     "@primeuix/themes": "^1.0.0",
     "primeicons": "^7.0.0",
     "primeng": "^21.0.0"

package/types/flusys-ng-shared.d.ts

@@ -6,40 +6,44 @@ import * as i2 from '@angular/forms';
 import { ControlValueAccessor } from '@angular/forms';
 import * as i3 from '@angular/router';
 import { CanActivateFn } from '@angular/router';
-import * as i1$1 from 'primeng/inputtext';
-import * as i2$1 from 'primeng/tag';
-import * as i3$1 from 'primeng/selectbutton';
-import * as i4 from 'primeng/password';
-import * as i5 from 'primeng/button';
-import * as i6 from 'primeng/tooltip';
-import * as i7 from 'primeng/checkbox';
+import * as i1$1 from 'primeng/autocomplete';
+import * as i2$1 from 'primeng/avatar';
+import * as i3$1 from 'primeng/button';
+import * as i4 from 'primeng/card';
+import * as i5 from 'primeng/checkbox';
 import { CheckboxChangeEvent } from 'primeng/checkbox';
-import * as i8 from 'primeng/steps';
-import * as i9 from 'primeng/ripple';
-import * as i10 from 'primeng/panel';
-import * as i11 from 'primeng/paginator';
-import * as i12 from 'primeng/table';
-import * as i13 from 'primeng/inputnumber';
-import * as i14 from 'primeng/textarea';
-import * as i15 from 'primeng/progressbar';
-import * as i16 from 'primeng/fileupload';
-import * as i17 from 'primeng/card';
-import * as i18 from 'primeng/select';
-import * as i19 from 'primeng/inputicon';
-import * as i20 from 'primeng/iconfield';
+import * as i6 from 'primeng/confirmdialog';
+import * as i7 from 'primeng/datepicker';
+import * as i8 from 'primeng/dialog';
+import * as i9 from 'primeng/divider';
+import * as i10 from 'primeng/fileupload';
+import * as i11 from 'primeng/iconfield';
+import * as i12 from 'primeng/image';
+import * as i13 from 'primeng/inputicon';
+import * as i14 from 'primeng/inputnumber';
+import * as i15 from 'primeng/inputtext';
+import * as i16 from 'primeng/listbox';
+import * as i17 from 'primeng/multiselect';
+import * as i18 from 'primeng/paginator';
+import * as i19 from 'primeng/panel';
+import * as i20 from 'primeng/password';
 import * as i21 from 'primeng/popover';
-import * as i22 from 'primeng/listbox';
+import * as i22 from 'primeng/progressbar';
 import * as i23 from 'primeng/radiobutton';
-import * as i24 from 'primeng/toggleswitch';
-import * as i25 from 'primeng/image';
-import * as i26 from 'primeng/datepicker';
-import * as i27 from 'primeng/splitbutton';
-import * as i28 from 'primeng/divider';
-import * as i29 from 'primeng/multiselect';
-import * as i30 from 'primeng/autocomplete';
+import * as i24 from 'primeng/ripple';
+import * as i25 from 'primeng/selectbutton';
+import * as i26 from 'primeng/select';
+import * as i27 from 'primeng/skeleton';
+import * as i28 from 'primeng/splitbutton';
+import * as i29 from 'primeng/steps';
+import * as i30 from 'primeng/table';
 import * as i31 from 'primeng/tabs';
-import * as i32 from 'primeng/dialog';
-import * as i33 from 'primeng/treetable';
+import * as i32 from 'primeng/tag';
+import * as i33 from 'primeng/textarea';
+import * as i34 from 'primeng/toast';
+import * as i35 from 'primeng/toggleswitch';
+import * as i36 from 'primeng/tooltip';
+import * as i37 from 'primeng/treetable';
 import * as _flusys_ng_shared from '@flusys/ng-shared';
 import { HttpClient, HttpParams, HttpHeaders } from '@angular/common/http';
 import { ApiLoaderService } from '@flusys/ng-core';
@@ -457,6 +461,7 @@ interface IFileUploadOptions {
  * Uploaded file response
  */
 interface IUploadedFile {
+    id?: string;
     name: string;
     key: string;
     size: number;
@@ -512,6 +517,249 @@ declare function getFileIconClass(contentType: string): string;
  */
 declare function formatFileSize(sizeInKb: string | number): string;
 
+/**
+ * User role info for profile display
+ */
+interface IProfileRoleInfo {
+    id: string;
+    name: string;
+    description?: string | null;
+}
+/**
+ * User action info for profile display
+ */
+interface IProfileActionInfo {
+    id: string;
+    name: string;
+    code: string;
+    description?: string | null;
+}
+/**
+ * Profile Permission Provider Interface
+ *
+ * Abstracts permission data access for profile page.
+ * Implemented by ng-iam, consumed by ng-auth profile page.
+ * Optional injection - if not provided, permissions section is hidden.
+ *
+ * @example
+ * // In profile component
+ * private readonly permissionProvider = inject(PROFILE_PERMISSION_PROVIDER, { optional: true });
+ *
+ * ngOnInit() {
+ *   if (this.permissionProvider) {
+ *     this.loadPermissions();
+ *   }
+ * }
+ */
+interface IProfilePermissionProvider {
+    /**
+     * Get user's assigned roles
+     * @param userId User ID
+     * @param branchId Optional branch ID for branch-scoped roles
+     */
+    getUserRoles(userId: string, branchId?: string): Observable<ISingleResponse<IProfileRoleInfo[]>>;
+    /**
+     * Get user's direct actions
+     * @param userId User ID
+     * @param branchId Optional branch ID for branch-scoped actions
+     */
+    getUserActions(userId: string, branchId?: string): Observable<ISingleResponse<IProfileActionInfo[]>>;
+}
+
+/**
+ * Uploaded file result with file manager ID
+ */
+interface IProfileUploadResult {
+    /** File manager ID (UUID) for storing in profilePictureId */
+    id: string;
+    /** Original file name */
+    name: string;
+    /** Storage key/path */
+    key: string;
+    /** File size in bytes */
+    size: number;
+    /** MIME type */
+    contentType: string;
+}
+/**
+ * Profile Upload Options
+ */
+interface IProfileUploadOptions {
+    /** Folder path for organizing uploads */
+    folderPath?: string;
+    /** Enable image compression */
+    compress?: boolean;
+    /** Max width for image compression */
+    maxWidth?: number;
+    /** Max height for image compression */
+    maxHeight?: number;
+}
+/**
+ * Profile Upload Provider Interface
+ *
+ * Provides file upload functionality for profile pictures.
+ * Implemented by ng-storage, consumed by ng-auth profile page.
+ *
+ * This interface enables ng-auth to use storage functionality
+ * without directly depending on ng-storage package.
+ */
+interface IProfileUploadProvider {
+    /**
+     * Upload profile picture and register in file manager
+     * Returns file manager ID (UUID) for storing in user.profilePictureId
+     *
+     * @param file - File to upload
+     * @param options - Upload options (compression, folder, etc.)
+     * @returns Observable with upload result including file manager ID
+     */
+    uploadProfilePicture(file: File, options?: IProfileUploadOptions): Observable<ISingleResponse<IProfileUploadResult>>;
+}
+
+/**
+ * Base user interface for list operations
+ * Extends this with app-specific user fields
+ */
+interface IUserListItem {
+    id: string;
+    name: string;
+    email: string;
+    phone?: string;
+    isActive?: boolean;
+    [key: string]: unknown;
+}
+/**
+ * User list action definition
+ * @template T User type, defaults to IUserListItem
+ */
+interface IUserListAction<T = IUserListItem> {
+    /** Unique action identifier */
+    id: string;
+    /** Display label */
+    label: string;
+    /** PrimeNG icon class (e.g., 'pi pi-pencil') */
+    icon?: string;
+    /** Severity for styling (e.g., 'primary', 'danger', 'warning') */
+    severity?: 'primary' | 'secondary' | 'success' | 'info' | 'warn' | 'danger' | 'help' | 'contrast';
+    /** Permission code required (checked via hasPermission) */
+    permission?: string;
+    /** Tooltip text */
+    tooltip?: string;
+    /** Whether action is disabled */
+    disabled?: boolean | ((user: T) => boolean);
+    /** Whether action is visible */
+    visible?: boolean | ((user: T) => boolean);
+}
+/**
+ * Extra column definition for user list
+ */
+interface IUserListColumn {
+    /** Column field name */
+    field: string;
+    /** Column header label */
+    header: string;
+    /** Column width */
+    width?: string;
+    /** Whether column is sortable */
+    sortable?: boolean;
+    /** Whether column is filterable */
+    filterable?: boolean;
+    /** Custom template type for rendering */
+    templateType?: 'text' | 'badge' | 'date' | 'boolean' | 'custom';
+}
+/**
+ * User List Provider Interface
+ *
+ * Allows consuming applications to extend user list pages with:
+ * - Extra columns
+ * - Extra row actions
+ * - Extra toolbar actions
+ * - Custom data enrichment
+ *
+ * This follows the Provider Interface Pattern:
+ * - ng-shared defines the interface (this file)
+ * - Consuming apps (via ng-iam or app-specific) implement the interface
+ * - ng-auth user list optionally injects and uses the implementation
+ *
+ * @template T User type, defaults to IUserListItem
+ *
+ * @example
+ * // 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' },
+ *     ];
+ *   }
+ * }
+ */
+interface IUserListProvider<T extends IUserListItem = IUserListItem> {
+    /**
+     * Get extra columns to display in user list
+     * @returns Array of extra column definitions
+     */
+    getExtraColumns?(): IUserListColumn[];
+    /**
+     * Get extra row-level actions (per-user actions)
+     * Displayed in actions column for each row
+     * @returns Array of action definitions
+     */
+    getExtraRowActions?(): IUserListAction<T>[];
+    /**
+     * Get extra toolbar actions
+     * Displayed in toolbar above the list
+     * @returns Array of action definitions
+     */
+    getExtraToolbarActions?(): IUserListAction<T>[];
+    /**
+     * Handle row action click
+     * @param actionId Action identifier
+     * @param user User data from the row
+     */
+    onRowAction?(actionId: string, user: T): void;
+    /**
+     * Handle toolbar action click
+     * @param actionId Action identifier
+     * @param selectedUsers Currently selected users (for bulk actions)
+     */
+    onToolbarAction?(actionId: string, selectedUsers: T[]): void;
+    /**
+     * Enrich user list data with extra fields
+     * Called after data is loaded from API
+     * @param users List of users from API
+     * @returns Observable of enriched users
+     */
+    enrichListData?(users: T[]): Observable<T[]>;
+    /**
+     * Get extra filters for user list
+     * @returns Array of filter definitions
+     */
+    getExtraFilters?(): IUserListFilter[];
+}
+/**
+ * Extra filter definition for user list
+ */
+interface IUserListFilter {
+    /** Filter field name */
+    field: string;
+    /** Filter label */
+    label: string;
+    /** Filter type */
+    type: 'text' | 'dropdown' | 'multiselect' | 'date' | 'boolean';
+    /** Options for dropdown/multiselect */
+    options?: {
+        label: string;
+        value: string | number | boolean;
+    }[];
+    /** Placeholder text */
+    placeholder?: string;
+}
+
 declare enum ContactTypeEnum {
     PHONE = 1,
     EMAIL = 2
@@ -570,14 +818,16 @@ declare class FileUrlService {
     fileUrlSignal(fileId: string | null | undefined): _angular_core.Signal<string | null>;
     /**
      * Fetch file URLs from backend and update cache.
-     * Returns Observable of fetched files.
+     * Skips IDs already in cache to prevent duplicate calls.
+     * Returns Observable of fetched files (including cached ones).
      */
-    fetchFileUrls(fileIds: string[]): Observable<FilesResponseDto[]>;
+    fetchFileUrls(fileIds: string[], forceRefresh?: boolean): Observable<FilesResponseDto[]>;
     /**
      * Fetch a single file URL.
+     * Uses cache if available to prevent duplicate calls.
      * Returns Observable of file info or null if not found.
      */
-    fetchSingleFileUrl(fileId: string): Observable<FilesResponseDto | null>;
+    fetchSingleFileUrl(fileId: string, forceRefresh?: boolean): Observable<FilesResponseDto | null>;
     /**
      * Clear the URL cache.
      * Useful on logout or when switching contexts.
@@ -784,7 +1034,7 @@ declare class AngularModule {
 
 declare class PrimeModule {
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<PrimeModule, never>;
-    static ɵmod: _angular_core.ɵɵNgModuleDeclaration<PrimeModule, never, never, [typeof i1$1.InputTextModule, typeof i2$1.TagModule, typeof i3$1.SelectButtonModule, typeof i4.PasswordModule, typeof i5.ButtonModule, typeof i6.TooltipModule, typeof i7.CheckboxModule, typeof i8.StepsModule, typeof i9.RippleModule, typeof i10.PanelModule, typeof i11.PaginatorModule, typeof i12.TableModule, typeof i13.InputNumberModule, typeof i14.TextareaModule, typeof i15.ProgressBarModule, typeof i16.FileUploadModule, typeof i17.CardModule, typeof i18.SelectModule, typeof i19.InputIconModule, typeof i20.IconFieldModule, typeof i21.PopoverModule, typeof i22.ListboxModule, typeof i23.RadioButtonModule, typeof i24.ToggleSwitchModule, typeof i25.ImageModule, typeof i26.DatePickerModule, typeof i27.SplitButtonModule, typeof i28.DividerModule, typeof i29.MultiSelectModule, typeof i30.AutoCompleteModule, typeof i31.TabsModule, typeof i32.DialogModule, typeof i33.TreeTableModule]>;
+    static ɵmod: _angular_core.ɵɵNgModuleDeclaration<PrimeModule, never, never, [typeof i1$1.AutoCompleteModule, typeof i2$1.AvatarModule, typeof i3$1.ButtonModule, typeof i4.CardModule, typeof i5.CheckboxModule, typeof i6.ConfirmDialogModule, typeof i7.DatePickerModule, typeof i8.DialogModule, typeof i9.DividerModule, typeof i10.FileUploadModule, typeof i11.IconFieldModule, typeof i12.ImageModule, typeof i13.InputIconModule, typeof i14.InputNumberModule, typeof i15.InputTextModule, typeof i16.ListboxModule, typeof i17.MultiSelectModule, typeof i18.PaginatorModule, typeof i19.PanelModule, typeof i20.PasswordModule, typeof i21.PopoverModule, typeof i22.ProgressBarModule, typeof i23.RadioButtonModule, typeof i24.RippleModule, typeof i25.SelectButtonModule, typeof i26.SelectModule, typeof i27.SkeletonModule, typeof i28.SplitButtonModule, typeof i29.StepsModule, typeof i30.TableModule, typeof i31.TabsModule, typeof i32.TagModule, typeof i33.TextareaModule, typeof i34.ToastModule, typeof i35.ToggleSwitchModule, typeof i36.TooltipModule, typeof i37.TreeTableModule]>;
     static ɵinj: _angular_core.ɵɵInjectorDeclaration<PrimeModule>;
 }
 
@@ -1457,6 +1707,36 @@ declare const USER_PERMISSION_PROVIDER: InjectionToken<IUserPermissionProvider>;
  * Provides auth state access for feature packages (form-builder, etc.)
  */
 declare const AUTH_STATE_PROVIDER: InjectionToken<IAuthStateProvider>;
+/**
+ * Profile Permission Provider Token
+ *
+ * Provides user permission data for profile display.
+ * Optional - if not configured, profile permissions section is hidden.
+ * Use with `inject(PROFILE_PERMISSION_PROVIDER, { optional: true })`.
+ */
+declare const PROFILE_PERMISSION_PROVIDER: InjectionToken<IProfilePermissionProvider>;
+/**
+ * Profile Upload Provider Token
+ *
+ * Provides file upload functionality for profile pictures.
+ * Optional - if not configured or storage not enabled, upload section is hidden.
+ * Use with `inject(PROFILE_UPLOAD_PROVIDER, { optional: true })`.
+ */
+declare const PROFILE_UPLOAD_PROVIDER: InjectionToken<IProfileUploadProvider>;
+/**
+ * User List Provider Token
+ *
+ * Provides extra actions, columns, and data enrichment for user list.
+ * Optional - if not configured, default user list behavior is used.
+ * Use with `inject(USER_LIST_PROVIDER, { optional: true })`.
+ *
+ * @example
+ * // In app.config.ts
+ * providers: [
+ *   { provide: USER_LIST_PROVIDER, useClass: MyUserListProvider },
+ * ]
+ */
+declare const USER_LIST_PROVIDER: InjectionToken<IUserListProvider<IUserListItem>>;
 
 /**
  * Permission Guard
@@ -1525,5 +1805,5 @@ declare function hasAnyPermission(permissionCodes: string[], permissions: string
 /** Check if user has ALL of the specified permissions (AND logic) */
 declare function hasAllPermissions(permissionCodes: string[], permissions: string[]): boolean;
 
-export { AUTH_STATE_PROVIDER, AngularModule, ApiResourceService, ApiResourceService as ApiService, COMPANY_API_PROVIDER, ContactTypeEnum, CookieService, EditModeElementChangerDirective, FILE_TYPE_FILTERS, FileSelectorDialogComponent, FileUploaderComponent, FileUrlService, HasPermissionDirective, IconComponent, IconTypeEnum, IsEmptyImageDirective, LazyMultiSelectComponent, LazySelectComponent, PermissionValidatorService, PlatformService, PreventDefaultDirective, PrimeModule, USER_PERMISSION_PROVIDER, USER_PROVIDER, UserMultiSelectComponent, UserSelectComponent, allPermissionsGuard, anyPermissionGuard, evaluateLogicNode, evaluatePermission, formatFileSize, getAcceptString, getFileIconClass, hasAllPermissions, hasAnyPermission, isFileTypeAllowed, permissionGuard };
-export type { ApiResponse, DeleteType, FilesResponseDto, GetFileUrlsFn, GetFilesRequestDto, IActionNode, IActivatable, IApiService, IAuthStateProvider, IBaseEntity, IBulkMeta, IBulkResponse, ICompanyApiProvider, ICompanyBasicInfo, IDeleteData, IDropDown, IErrorResponse, IFileBasicInfo, IFileData, IFileSelectFilter, IFileUploadOptions, IFilter, IFilterData, IGroupNode, IListResponse, ILoggedUserInfo, ILogicNode, ILoginResponse, ILoginUserData, IMessageResponse, IMetadata, IOrderable, IPagination, IPaginationMeta, IRefreshTokenResponse, IRequestMeta, ISingleResponse, ISoftDeletable, ISort, ITimestampable, IUploadedFile, IUserBasicInfo, IUserBranchPayload, IUserCompanyPayload, IUserPermissionProvider, IUserProvider, IUserSelectFilter, IValidationError, LoadFilesFn, LoadUsersFn, UploadFileFn };
+export { AUTH_STATE_PROVIDER, AngularModule, ApiResourceService, ApiResourceService as ApiService, COMPANY_API_PROVIDER, ContactTypeEnum, CookieService, EditModeElementChangerDirective, FILE_TYPE_FILTERS, FileSelectorDialogComponent, FileUploaderComponent, FileUrlService, HasPermissionDirective, IconComponent, IconTypeEnum, IsEmptyImageDirective, LazyMultiSelectComponent, LazySelectComponent, PROFILE_PERMISSION_PROVIDER, PROFILE_UPLOAD_PROVIDER, PermissionValidatorService, PlatformService, PreventDefaultDirective, PrimeModule, USER_LIST_PROVIDER, USER_PERMISSION_PROVIDER, USER_PROVIDER, UserMultiSelectComponent, UserSelectComponent, allPermissionsGuard, anyPermissionGuard, evaluateLogicNode, evaluatePermission, formatFileSize, getAcceptString, getFileIconClass, hasAllPermissions, hasAnyPermission, isFileTypeAllowed, permissionGuard };
+export type { ApiResponse, DeleteType, FilesResponseDto, GetFileUrlsFn, GetFilesRequestDto, IActionNode, IActivatable, IApiService, IAuthStateProvider, IBaseEntity, IBulkMeta, IBulkResponse, ICompanyApiProvider, ICompanyBasicInfo, IDeleteData, IDropDown, IErrorResponse, IFileBasicInfo, IFileData, IFileSelectFilter, IFileUploadOptions, IFilter, IFilterData, IGroupNode, IListResponse, ILoggedUserInfo, ILogicNode, ILoginResponse, ILoginUserData, IMessageResponse, IMetadata, IOrderable, IPagination, IPaginationMeta, IProfileActionInfo, IProfilePermissionProvider, IProfileRoleInfo, IProfileUploadOptions, IProfileUploadProvider, IProfileUploadResult, IRefreshTokenResponse, IRequestMeta, ISingleResponse, ISoftDeletable, ISort, ITimestampable, IUploadedFile, IUserBasicInfo, IUserBranchPayload, IUserCompanyPayload, IUserListAction, IUserListColumn, IUserListFilter, IUserListItem, IUserListProvider, IUserPermissionProvider, IUserProvider, IUserSelectFilter, IValidationError, LoadFilesFn, LoadUsersFn, UploadFileFn };