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

package/README.md

@@ -110,6 +110,77 @@ interface IDropDown {
 }
 ```
 
+#### User Select Interfaces
+
+```typescript
+interface IUserSelectFilter {
+  page: number;
+  pageSize: number;
+  search: string;
+  [key: string]: unknown;
+}
+
+type LoadUsersFn = (filter: IUserSelectFilter) => Observable<IListResponse<IUserBasicInfo>>;
+```
+
+#### File Select Interfaces
+
+```typescript
+interface IFileBasicInfo {
+  id: string;
+  name: string;
+  contentType: string;
+  size: string;
+  url: string | null;
+}
+
+interface IFileUploadOptions {
+  storageConfigId?: string;
+  folderPath?: string;
+  maxWidth?: number;
+  maxHeight?: number;
+  quality?: number;
+  compress?: boolean;
+}
+
+interface IUploadedFile {
+  name: string;
+  key: string;
+  size: number;
+  contentType: string;
+}
+
+interface IFileSelectFilter {
+  page: number;
+  pageSize: number;
+  search: string;
+  contentTypes?: string[];
+  folderId?: string;
+  [key: string]: unknown;
+}
+
+type LoadFilesFn = (filter: IFileSelectFilter) => Observable<IListResponse<IFileBasicInfo>>;
+type UploadFileFn = (file: File, options?: IFileUploadOptions) => Observable<ISingleResponse<IUploadedFile>>;
+type GetFileUrlsFn = (fileIds: string[]) => Observable<ISingleResponse<IFileBasicInfo[]>>;
+```
+
+**File Type Filters (Constants):**
+
+```typescript
+import { FILE_TYPE_FILTERS, getAcceptString, isFileTypeAllowed, getFileIconClass, formatFileSize } from '@flusys/ng-shared';
+
+FILE_TYPE_FILTERS.IMAGES     // ['image/jpeg', 'image/png', 'image/gif', 'image/webp', 'image/svg+xml']
+FILE_TYPE_FILTERS.DOCUMENTS  // ['application/pdf', 'application/msword', ...]
+FILE_TYPE_FILTERS.VIDEOS     // ['video/mp4', 'video/webm', ...]
+FILE_TYPE_FILTERS.AUDIO      // ['audio/mpeg', 'audio/wav', ...]
+FILE_TYPE_FILTERS.ALL        // [] (allows all)
+
+getAcceptString(['image/*'])           // 'image/*'
+isFileTypeAllowed(file, ['image/*'])   // true/false
+getFileIconClass('image/png')          // 'pi pi-image'
+formatFileSize(1024)                   // '1 KB'
+```
+
 ### Response Interfaces
 
 Type-safe interfaces matching FLUSYS_NEST backend response DTOs.
@@ -446,7 +517,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" />
 ```
 
@@ -539,6 +610,176 @@ export class MyComponent {
 
 **Computed signals:** `selectedValueDisplay` (display text), `isSelectAll` (all items selected)
 
+### UserSelectComponent
+
+Single user selection with lazy loading. Uses `USER_PROVIDER` internally or accepts custom `loadUsers` function.
+
+- **Selector:** `lib-user-select`
+- **Supports:** Template-driven, reactive forms, signal forms
+
+```typescript
+@Component({
+  imports: [UserSelectComponent],
+  template: `
+    <!-- Simple usage - uses USER_PROVIDER internally -->
+    <lib-user-select
+      [(value)]="selectedUserId"
+      [isEditMode]="true"
+    />
+
+    <!-- With custom loadUsers function -->
+    <lib-user-select
+      [(value)]="selectedUserId"
+      [isEditMode]="true"
+      [loadUsers]="customLoadUsers"
+    />
+  `,
+})
+export class MyComponent {
+  readonly selectedUserId = signal<string | null>(null);
+}
+```
+
+**Inputs:**
+
+| Input | Type | Default | Description |
+| ----- | ---- | ------- | ----------- |
+| `isEditMode` | `boolean` | required | Enable/disable editing |
+| `placeHolder` | `string` | `'Select User'` | Placeholder text |
+| `filterActive` | `boolean` | `true` | Filter active users only |
+| `additionalFilters` | `Record<string, unknown>` | `{}` | Extra filter params |
+| `pageSize` | `number` | `20` | Page size for pagination |
+| `loadUsers` | `LoadUsersFn` | - | Custom user loading function |
+
+**Model:** `value` - Two-way bound selected user ID (`string | null`)
+
+**Outputs:** `userSelected` (IUserBasicInfo | null), `onError` (Error)
+
+### UserMultiSelectComponent
+
+Multiple user selection with lazy loading. Uses `USER_PROVIDER` internally or accepts custom `loadUsers` function.
+
+- **Selector:** `lib-user-multi-select`
+- **Supports:** Template-driven, reactive forms, signal forms
+
+```typescript
+@Component({
+  imports: [UserMultiSelectComponent],
+  template: `
+    <lib-user-multi-select
+      [(value)]="selectedUserIds"
+      [isEditMode]="true"
+    />
+  `,
+})
+export class MyComponent {
+  readonly selectedUserIds = signal<string[] | null>(null);
+}
+```
+
+**Inputs:** Same as `UserSelectComponent`.
+
+**Model:** `value` - Two-way bound selected user IDs (`string[] | null`)
+
+**Outputs:** `usersSelected` (IUserBasicInfo[]), `onError` (Error)
+
+### FileUploaderComponent
+
+Drag & drop file upload with type filtering. Pass your own `uploadFile` function.
+
+- **Selector:** `lib-file-uploader`
+
+```typescript
+@Component({
+  imports: [FileUploaderComponent],
+  template: `
+    <!-- Single image upload -->
+    <lib-file-uploader
+      [uploadFile]="uploadFile"
+      [acceptTypes]="['image/*']"
+      [multiple]="false"
+      (fileUploaded)="onFileUploaded($event)"
+    />
+
+    <!-- Multiple document upload -->
+    <lib-file-uploader
+      [uploadFile]="uploadFile"
+      [acceptTypes]="FILE_TYPE_FILTERS.DOCUMENTS"
+      [multiple]="true"
+      [maxFiles]="5"
+      (filesUploaded)="onFilesUploaded($event)"
+    />
+  `,
+})
+export class MyComponent {
+  readonly uploadService = inject(UploadService);
+
+  readonly uploadFile: UploadFileFn = (file, options) =>
+    this.uploadService.uploadSingleFile(file, options);
+}
+```
+
+**Inputs:**
+
+| Input | Type | Default | Description |
+| ----- | ---- | ------- | ----------- |
+| `uploadFile` | `UploadFileFn` | required | Upload function |
+| `acceptTypes` | `string[]` | `[]` | Allowed MIME types |
+| `multiple` | `boolean` | `false` | Allow multiple files |
+| `maxFiles` | `number` | `10` | Max files for multiple |
+| `maxSizeMb` | `number` | `10` | Max file size in MB |
+| `uploadOptions` | `IFileUploadOptions` | `{}` | Upload options |
+| `disabled` | `boolean` | `false` | Disable uploader |
+| `showPreview` | `boolean` | `true` | Show selected files preview |
+| `autoUpload` | `boolean` | `true` | Upload immediately on selection |
+
+**Outputs:** `fileUploaded` (IUploadedFile), `filesUploaded` (IUploadedFile[]), `onError` (Error), `fileSelected` (File[])
+
+### FileSelectorDialogComponent
+
+Dialog to browse and select existing files with filtering.
+
+- **Selector:** `lib-file-selector-dialog`
+
+```typescript
+@Component({
+  imports: [FileSelectorDialogComponent],
+  template: `
+    <lib-file-selector-dialog
+      [(visible)]="showFileSelector"
+      [loadFiles]="loadFiles"
+      [acceptTypes]="['image/*']"
+      [multiple]="false"
+      (fileSelected)="onFileSelected($event)"
+    />
+  `,
+})
+export class MyComponent {
+  readonly showFileSelector = signal(false);
+  readonly fileService = inject(FileManagerApiService);
+
+  readonly loadFiles: LoadFilesFn = (filter) =>
+    this.fileService.getAll(filter.search, {
+      pagination: { currentPage: filter.page, pageSize: filter.pageSize },
+    });
+}
+```
+
+**Inputs:**
+
+| Input | Type | Default | Description |
+| ----- | ---- | ------- | ----------- |
+| `loadFiles` | `LoadFilesFn` | required | File loading function |
+| `header` | `string` | `'Select File'` | Dialog header |
+| `acceptTypes` | `string[]` | `[]` | Allowed MIME types |
+| `multiple` | `boolean` | `false` | Allow multiple selection |
+| `maxSelection` | `number` | `10` | Max files for multiple |
+| `pageSize` | `number` | `20` | Page size for pagination |
+
+**Model:** `visible` - Two-way bound dialog visibility (`boolean`)
+
+**Outputs:** `fileSelected` (IFileBasicInfo), `filesSelected` (IFileBasicInfo[]), `closed` (void), `onError` (Error)
+
 ---
 
 ## 5. Directives
@@ -805,6 +1046,153 @@ interface IUserPermissionProvider {
 }
 ```
 
+#### IProfileUploadProvider / `PROFILE_UPLOAD_PROVIDER`
+
+Profile picture upload for ng-auth profile page. Implemented by ng-storage.
+
+```typescript
+interface IProfileUploadResult {
+  id: string;          // File manager ID (UUID)
+  name: string;        // Original file name
+  key: string;         // Storage key/path
+  size: number;        // File size in bytes
+  contentType: string; // MIME type
+}
+
+interface IProfileUploadOptions {
+  folderPath?: string;
+  compress?: boolean;
+  maxWidth?: number;
+  maxHeight?: number;
+}
+
+interface IProfileUploadProvider {
+  uploadProfilePicture(
+    file: File,
+    options?: IProfileUploadOptions
+  ): Observable<ISingleResponse<IProfileUploadResult>>;
+}
+```
+
+#### IProfilePermissionProvider / `PROFILE_PERMISSION_PROVIDER`
+
+User permission queries for ng-auth profile page. Implemented by ng-iam.
+
+```typescript
+interface IProfileRoleInfo {
+  id: string;
+  name: string;
+  description?: string | null;
+}
+
+interface IProfileActionInfo {
+  id: string;
+  code: string;
+  name: string;
+  description?: string | null;
+}
+
+interface IProfilePermissionProvider {
+  getUserRoles(userId: string, branchId?: string): Observable<ISingleResponse<IProfileRoleInfo[]>>;
+  getUserActions(userId: string, branchId?: string): Observable<ISingleResponse<IProfileActionInfo[]>>;
+}
+```
+
+#### 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
@@ -931,6 +1319,10 @@ export const appConfig: ApplicationConfig = {
 | `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
 
@@ -964,6 +1356,19 @@ export const appConfig: ApplicationConfig = {
 | `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           |
 
 ### Injection Tokens
 
@@ -972,6 +1377,10 @@ export const appConfig: ApplicationConfig = {
 | `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) |
 
 ## See Also
 
@@ -982,5 +1391,5 @@ export const appConfig: ApplicationConfig = {
 
 ---
 
-**Last Updated:** 2026-02-15
+**Last Updated:** 2026-02-18
 **Angular Version:** 21