@flusys/ng-shared 0.1.0-beta.1 → 0.1.0-beta.2

package/README.md

@@ -0,0 +1,987 @@
+# @flusys/ng-shared Package Guide
+
+## Overview
+
+`@flusys/ng-shared` provides reusable components, directives, API services, and utilities used across all FLUSYS applications. This package extends ng-core with UI components, API integration patterns, and provider interfaces for package independence.
+
+**Key Principle:** ng-shared depends only on ng-core, never on ng-layout or feature packages.
+
+## Package Information
+
+- **Package:** `@flusys/ng-shared`
+- **Dependencies:** ng-core
+- **Dependents:** ng-layout, ng-auth, ng-iam, ng-storage, flusysng
+- **Build Command:** `npm run build:ng-shared`
+
+---
+
+## 1. Interfaces
+
+### Data Interfaces
+
+#### IBaseEntity
+
+Base entity interface matching backend Identity entity.
+
+```typescript
+interface IBaseEntity {
+  id: string;
+  createdAt: Date;
+  updatedAt: Date;
+  deletedAt?: Date | null;
+  createdById?: string | null;
+  updatedById?: string | null;
+  deletedById?: string | null;
+}
+```
+
+**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  |
+
+#### ILoggedUserInfo
+
+Current logged-in user info with optional company context.
+
+```typescript
+interface ILoggedUserInfo {
+  id: string;
+  email: string;
+  name?: string;
+  phone?: string;
+  profilePictureId?: string;
+  companyId?: string;
+  branchId?: string;
+  companyLogoId?: string;
+  branchLogoId?: string;
+}
+```
+
+#### IFilterData
+
+Filter, pagination, and sort payload for list queries.
+
+```typescript
+interface IPagination {
+  pageSize: number;
+  currentPage: number;
+}
+
+interface ISort { [key: string]: 'ASC' | 'DESC' }
+interface IFilter { [key: string]: any }
+
+interface IFilterData {
+  filter?: IFilter;
+  pagination?: IPagination;
+  select?: string[];
+  sort?: ISort;
+  withDeleted?: boolean;
+  extraKey?: string[];
+}
+```
+
+#### IDeleteData
+
+Delete request payload matching backend DeleteDto.
+
+```typescript
+type DeleteType = 'delete' | 'restore' | 'permanent';
+
+interface IDeleteData {
+  id: string | string[];  // Single or batch delete
+  type: DeleteType;
+}
+```
+
+#### IDropDown
+
+Simple dropdown item for select components.
+
+```typescript
+interface IDropDown {
+  label: string;
+  value: string;
+}
+```
+
+### Response Interfaces
+
+Type-safe interfaces matching FLUSYS_NEST backend response DTOs.
+
+```typescript
+// Single item response (POST /resource/insert, /update, /get/:id)
+interface ISingleResponse<T> {
+  success: boolean;
+  message: string;
+  data?: T;
+  _meta?: IRequestMeta;
+}
+
+// List response with pagination (POST /resource/get-all)
+interface IListResponse<T> {
+  success: boolean;
+  message: string;
+  data?: T[];
+  meta: IPaginationMeta;
+  _meta?: IRequestMeta;
+}
+
+// Bulk operation response (POST /resource/insert-many, /update-many)
+interface IBulkResponse<T> {
+  success: boolean;
+  message: string;
+  data?: T[];
+  meta: IBulkMeta;
+  _meta?: IRequestMeta;
+}
+
+// Message-only response (POST /resource/delete, /logout)
+interface IMessageResponse {
+  success: boolean;
+  message: string;
+  _meta?: IRequestMeta;
+}
+
+// Error response (validation errors, exceptions)
+interface IErrorResponse {
+  success: false;
+  message: string;
+  code?: string;
+  errors?: IValidationError[];
+  _meta?: IRequestMeta;
+}
+
+// Union type
+type ApiResponse<T> = ISingleResponse<T> | IListResponse<T> | IBulkResponse<T> | IMessageResponse | IErrorResponse;
+```
+
+**Metadata types:**
+
+| Interface          | Fields                                       |
+| ------------------ | -------------------------------------------- |
+| `IRequestMeta`     | `requestId?, timestamp?, responseTime?`      |
+| `IPaginationMeta`  | `total, page, pageSize, count, hasMore?, totalPages?` |
+| `IBulkMeta`        | `count, failed?, total?`                     |
+| `IValidationError` | `field, message, constraint?`                |
+
+### Auth & Storage Response Types
+
+```typescript
+interface ILoginResponse {
+  success: boolean;
+  message: string;
+  data: { accessToken: string; refreshToken: string; user: ILoginUserData };
+}
+
+interface IRefreshTokenResponse {
+  success: boolean;
+  message: string;
+  data: { accessToken: string; refreshToken?: string };
+}
+
+interface IFileData {
+  id: string;
+  name: string;
+  originalName: string;
+  contentType: string;
+  size: number;
+  key: string;
+  url?: string;
+  thumbnailUrl?: string;
+  createdAt: Date;
+}
+```
+
+### Permission Interfaces
+
+Discriminated union for building complex permission logic trees.
+
+```typescript
+// Single permission check
+interface IActionNode {
+  type: 'action';
+  actionId: string;
+}
+
+// Group with AND/OR logic
+interface IGroupNode {
+  type: 'group';
+  operator: 'AND' | 'OR';
+  children: ILogicNode[];
+}
+
+// Union type
+type ILogicNode = IActionNode | IGroupNode;
+```
+
+---
+
+## 2. Enums
+
+```typescript
+enum ContactTypeEnum {
+  PHONE = 1,
+  EMAIL = 2,
+}
+
+enum IconTypeEnum {
+  PRIMENG_ICON = 1,
+  IMAGE_FILE_LINK = 2,
+  DIRECT_TAG_SVG = 3,
+}
+```
+
+---
+
+## 3. Services
+
+### ApiResourceService
+
+Signal-based CRUD service using Angular 21 `resource()` API. All endpoints use POST (RPC-style).
+
+**Define a service:**
+
+```typescript
+import { Injectable } from '@angular/core';
+import { HttpClient } from '@angular/common/http';
+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'
+  }
+}
+```
+
+**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`      |
+
+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      |
+| `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 } });
+
+// Pagination helpers
+userService.setPagination({ currentPage: 1, pageSize: 20 });
+userService.nextPage();
+userService.resetPagination();
+userService.reload();
+```
+
+**Component usage:**
+
+```typescript
+@Component({...})
+export class UserListComponent {
+  private readonly userService = inject(UserService);
+
+  readonly users = this.userService.data;           // Signal<IUser[]>
+  readonly isLoading = this.userService.isLoading;   // Signal<boolean>
+  readonly total = this.userService.total;           // Signal<number>
+
+  constructor() {
+    this.userService.fetchList('', { pagination: { currentPage: 0, pageSize: 10 } });
+  }
+
+  async createUser(dto: UserDto) {
+    await this.userService.insertAsync(dto);
+    this.userService.reload(); // Refresh list
+  }
+}
+```
+
+> **Note:** `ApiService` is exported as an alias for `ApiResourceService` for backward compatibility.
+
+### FileUrlService
+
+Fetches file URLs from the backend. Supports presigned URLs for cloud storage (S3, Azure).
+
+**CRITICAL:** Never construct file URLs manually. Always use this service.
+
+```typescript
+import { FileUrlService } from '@flusys/ng-shared';
+
+@Component({...})
+export class ProductComponent {
+  private readonly fileUrlService = inject(FileUrlService);
+
+  loadImage(fileId: string) {
+    // Fetch from backend: POST /file-manager/get-files
+    this.fileUrlService.fetchSingleFileUrl(fileId).subscribe(file => {
+      this.imageUrl.set(file?.url ?? null);
+    });
+  }
+
+  loadMultiple(fileIds: string[]) {
+    this.fileUrlService.fetchFileUrls(fileIds).subscribe(files => {
+      // files: FilesResponseDto[] with { id, name, contentType, url }
+    });
+  }
+}
+```
+
+**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   |
+
+### PermissionValidatorService
+
+Signal-based permission state management. Used by `HasPermissionDirective`, permission guards, and IAM.
+
+```typescript
+import { PermissionValidatorService } from '@flusys/ng-shared';
+
+@Component({...})
+export class MyComponent {
+  private readonly permissionValidator = inject(PermissionValidatorService);
+
+  ngOnInit() {
+    // Set permissions (typically done by IAM PermissionStateService)
+    this.permissionValidator.setPermissions(['user.view', 'user.create']);
+
+    // Check single permission
+    if (this.permissionValidator.hasPermission('user.view')) {
+      // User has permission
+    }
+
+    // Check loaded state
+    if (this.permissionValidator.isPermissionsLoaded()) {
+      // Permissions have been loaded
+    }
+  }
+}
+```
+
+**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  |
+
+**Signals:**
+
+| Signal        | Type               | Description                    |
+| ------------- | ------------------ | ------------------------------ |
+| `permissions` | `Signal<string[]>` | Readonly current permissions   |
+
+### CookieService
+
+SSR-aware cookie reading service.
+
+```typescript
+import { CookieService } from '@flusys/ng-shared';
+
+const cookies = inject(CookieService).get(); // Returns document.cookie (browser) or request header cookie (server)
+```
+
+### PlatformService
+
+SSR environment detection service.
+
+```typescript
+import { PlatformService } from '@flusys/ng-shared';
+
+const platform = inject(PlatformService);
+if (!platform.isServer) {
+  // Browser-only code (localStorage, window, etc.)
+}
+```
+
+---
+
+## 4. Components
+
+### IconComponent
+
+Flexible icon renderer supporting PrimeNG icons, image files, and SVG.
+
+- **Selector:** `lib-icon`
+- **Inputs:** `icon` (required string), `iconType` (optional `IconTypeEnum`, default: `PRIMENG_ICON`)
+
+```html
+<!-- PrimeNG icon (default) -->
+<lib-icon icon="pi pi-user" />
+
+<!-- Image file -->
+<lib-icon icon="/assets/logo.png" [iconType]="IconTypeEnum.IMAGE_FILE_LINK" />
+
+<!-- SVG tag -->
+<lib-icon icon="<svg>...</svg>" [iconType]="IconTypeEnum.DIRECT_TAG_SVG" />
+```
+
+### LazySelectComponent
+
+Single-select dropdown with lazy loading, search, and scroll pagination.
+
+- **Selector:** `lib-lazy-select`
+- **Extends:** `BaseFormControl<string | null>`
+- **Supports:** Template-driven, reactive forms, signal forms
+
+```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)"
+    />
+  `,
+})
+export class MyComponent {
+  readonly selectedId = signal<string | null>(null);
+  readonly items = signal<IDropDown[]>([]);
+  readonly loading = signal(false);
+  readonly total = signal<number | undefined>(undefined);
+  readonly pagination = signal<IPagination>({ currentPage: 0, pageSize: 20 });
+}
+```
+
+**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'`) |
+
+**Model:** `value` - Two-way bound selected value (`string | null`)
+
+**Outputs:** `onSearch` (debounced 500ms), `onPagination` (scroll-triggered)
+
+### LazyMultiSelectComponent
+
+Multi-select dropdown with lazy loading, search, select-all, and scroll pagination.
+
+- **Selector:** `lib-lazy-multi-select`
+- **Extends:** `BaseFormControl<string[] | null>`
+- **Supports:** Template-driven, reactive forms, signal forms
+
+```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)"
+    />
+  `,
+})
+export class MyComponent {
+  readonly selectedIds = signal<string[] | null>(null);
+}
+```
+
+**Inputs:** `selectDataList`, `isEditMode`, `isLoading`, `total`, `pagination`, `placeHolder` (same as `LazySelectComponent`). Does not have `optionLabel`/`optionValue` (uses `IDropDown.label`/`IDropDown.value` directly).
+
+**Model:** `value` - Two-way bound selected values (`string[] | null`)
+
+**Computed signals:** `selectedValueDisplay` (display text), `isSelectAll` (all items selected)
+
+---
+
+## 5. Directives
+
+### HasPermissionDirective
+
+Structural directive for permission-based rendering. Fail-closed: hides content when permissions not loaded.
+
+- **Selector:** `[hasPermission]`
+- **Input:** `hasPermission` - `string | ILogicNode | null`
+
+```typescript
+import { HasPermissionDirective, ILogicNode } from '@flusys/ng-shared';
+
+@Component({
+  imports: [HasPermissionDirective],
+  template: `
+    <!-- Simple permission check -->
+    <button *hasPermission="'user.create'">Create User</button>
+
+    <!-- Complex AND/OR logic -->
+    <div *hasPermission="editLogic">Edit Panel</div>
+  `,
+})
+export class MyComponent {
+  readonly editLogic: ILogicNode = {
+    type: 'group',
+    operator: 'AND',
+    children: [
+      { type: 'action', actionId: 'user.view' },
+      { type: 'action', actionId: 'user.update' },
+    ],
+  };
+}
+```
+
+### EditModeElementChangerDirective
+
+Toggles readonly/disabled state for form controls based on edit mode. Supports `<input>`, `<p-select>`, and `<p-calendar>`.
+
+- **Selector:** `[appEditModeElementChanger]`
+- **Input:** `isEditMode` (required boolean)
+
+```html
+<input [appEditModeElementChanger] [isEditMode]="isEditing()" />
+<p-select [appEditModeElementChanger] [isEditMode]="isEditing()" />
+```
+
+### IsEmptyImageDirective
+
+Automatically replaces broken or empty image `src` with a default fallback image.
+
+- **Selector:** `img` (applies to all `<img>` elements)
+- **Input:** `src` (standard img src)
+- **Default image:** `lib/assets/images/default/default-image.jpg`
+
+```html
+<img [src]="imageUrl()" alt="Product" />
+<!-- Falls back to default image on error or empty src -->
+```
+
+### PreventDefaultDirective
+
+Prevents default browser behavior on specified events and emits the event.
+
+- **Selector:** `[appPreventDefault]`
+- **Inputs:** `eventType` (`'click' | 'keydown' | 'keyup'`, default: `'click'`), `preventKey` (optional key filter)
+- **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)" />
+```
+
+---
+
+## 6. Guards
+
+Route-level guards for permission-based access control. All guards deny access when permissions are not loaded (fail-closed).
+
+### permissionGuard
+
+Single permission or complex logic check.
+
+```typescript
+import { permissionGuard } from '@flusys/ng-shared';
+
+const routes: Routes = [
+  // Simple permission
+  { 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' },
+    ],
+  })] },
+
+  // Custom redirect on deny
+  { path: 'settings', canActivate: [permissionGuard('settings.view', '/access-denied')] },
+];
+```
+
+### anyPermissionGuard
+
+OR logic - allows access if user has ANY of the specified permissions.
+
+```typescript
+{ path: 'reports', canActivate: [anyPermissionGuard(['report.view', 'report.export'])] }
+```
+
+### allPermissionsGuard
+
+AND logic - allows access only if user has ALL specified permissions.
+
+```typescript
+{ path: 'admin', canActivate: [allPermissionsGuard(['admin.view', 'admin.manage'])] }
+```
+
+---
+
+## 7. Utilities
+
+### Permission Evaluator
+
+Pure functions for permission logic evaluation. Used internally by `HasPermissionDirective` and guards.
+
+```typescript
+import { evaluatePermission, evaluateLogicNode, hasAnyPermission, hasAllPermissions } from '@flusys/ng-shared';
+
+const userPermissions = ['user.view', 'user.create'];
+
+// Evaluate string or ILogicNode
+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)
+```
+
+---
+
+## 8. 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';
+
+@Component({
+  selector: 'my-select',
+  providers: [provideValueAccessor(MySelectComponent)],
+})
+export class MySelectComponent extends BaseFormControl<string | null> {
+  override readonly value = model<string | null>(null);
+
+  constructor() {
+    super();
+    this.initializeFormControl(); // Required for ControlValueAccessor sync
+  }
+}
+
+// Usage in all form patterns:
+// Template-driven: <my-select [(value)]="selectedId" />
+// Reactive forms:  <my-select [formControl]="myControl" />
+// Signal forms:    <my-select [formField]="formTree.myField" />
+```
+
+**Abstract property:** `value: ModelSignal<T>` - Must override with `model<T>()`
+
+**Models:** `disabled` (boolean), `touched` (boolean)
+
+**Methods:** `initializeFormControl()` (call in constructor), `markAsTouched()` (call on blur)
+
+**Helper:** `provideValueAccessor(ComponentClass)` - Factory for `NG_VALUE_ACCESSOR` provider
+
+---
+
+## 9. Modules
+
+### AngularModule
+
+Re-exports common Angular modules for convenience.
+
+```typescript
+import { AngularModule } from '@flusys/ng-shared';
+// Includes: CommonModule, FormsModule, ReactiveFormsModule, RouterLink, RouterOutlet, + directives
+// Providers: DatePipe
+```
+
+### PrimeModule
+
+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)
+```
+
+---
+
+## 10. Provider Interfaces (Package Independence)
+
+ng-shared defines **provider interfaces** to enable feature packages (ng-iam, ng-storage) to access auth functionality without direct dependencies.
+
+### Architecture
+
+```
+ng-shared (defines interfaces + tokens)
+    |
+ng-auth (implements interfaces with adapters)
+    |
+ng-iam/ng-storage (consume interfaces via DI)
+```
+
+### Available Providers
+
+#### IUserProvider / `USER_PROVIDER`
+
+User list access for IAM user selection.
+
+```typescript
+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>>;
+}
+```
+
+#### ICompanyApiProvider / `COMPANY_API_PROVIDER`
+
+Company list access for IAM company selection.
+
+```typescript
+interface ICompanyBasicInfo { id: string; name: string; slug?: string }
+
+interface ICompanyApiProvider {
+  getCompanies(filter?: {
+    page?: number; pageSize?: number; search?: string;
+  }): Observable<IListResponse<ICompanyBasicInfo>>;
+}
+```
+
+#### IUserPermissionProvider / `USER_PERMISSION_PROVIDER`
+
+User permission queries for IAM.
+
+```typescript
+interface IUserPermissionProvider {
+  getUserBranchPermissions(userId: string): Observable<ISingleResponse<any>>;
+}
+```
+
+### Usage in Consuming Packages
+
+```typescript
+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.users.set(response.data ?? []);
+    });
+  }
+}
+```
+
+### Wiring in App
+
+```typescript
+// app.config.ts
+import { provideAuthProviders } from '@flusys/ng-auth';
+
+export const appConfig: ApplicationConfig = {
+  providers: [
+    ...provideAuthProviders(), // Registers all auth adapters for provider tokens
+  ],
+};
+```
+
+### See Also
+
+- [AUTH-GUIDE.md](AUTH-GUIDE.md) - Adapter implementations
+- [IAM-GUIDE.md](IAM-GUIDE.md) - IAM usage examples
+- [../CLAUDE.md](../CLAUDE.md) - Complete pattern documentation
+
+---
+
+## Best Practices
+
+### API Services
+
+- **Extend `ApiResourceService`** for new services (signal-based)
+- Use reactive signals (`data`, `isLoading`, `total`) in templates
+- Use `fetchList()` to trigger queries, `reload()` to refresh
+- Use async methods (`insertAsync`, `updateAsync`) for one-off operations
+
+### File URLs
+
+- **Always use `FileUrlService`** - never construct URLs manually
+- Use `fetchSingleFileUrl()` for one-off fetches, `fetchFileUrls()` for batches
+- Use `fileUrlSignal()` for reactive template bindings
+
+### Components
+
+- Use `AngularModule` and `PrimeModule` for common imports
+- Use signal inputs via `input()` and `input.required()`
+- Components use `lib-` prefix for selectors
+
+### Directives
+
+- Directives use `app` prefix for selectors (`appPreventDefault`, `appEditModeElementChanger`)
+- Exception: `HasPermissionDirective` uses `[hasPermission]`
+- Exception: `IsEmptyImageDirective` uses `img` selector (auto-applies to all images)
+
+### Permissions
+
+- Use `HasPermissionDirective` for template-level permission checks
+- Use permission guards for route-level access control
+- Use `PermissionValidatorService` for programmatic checks in services
+- Permissions follow fail-closed model: no access by default
+
+---
+
+## Common Issues
+
+### ApiResourceService Not Updating UI
+
+**Problem:** UI doesn't update after operations.
+
+**Solution:** Use signal syntax in templates:
+
+```html
+<!-- Correct -->
+<div>{{ users() }}</div>
+
+<!-- Wrong -->
+<div>{{ users }}</div>
+```
+
+### FileUrlService Returns Error
+
+**Problem:** File URL fetching fails.
+
+**Solution:**
+
+1. Ensure storage service is enabled in environment config
+2. Verify file ID exists in database
+3. Check storage provider configuration (local/S3/Azure)
+
+### Circular Dependency with ng-layout
+
+**Problem:** Build fails with circular dependency.
+
+**Solution:** ng-shared must NEVER import from ng-layout. Move shared components to ng-shared, layout-specific components to ng-layout.
+
+---
+
+## 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             |
+
+### 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 |
+
+### Directives
+
+| 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      |
+
+### Guards
+
+| 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) |
+
+### 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      |
+
+## See Also
+
+- **[CORE-GUIDE.md](./CORE-GUIDE.md)** - Configuration, interceptors
+- **[LAYOUT-GUIDE.md](./LAYOUT-GUIDE.md)** - Layout system
+- **[AUTH-GUIDE.md](./AUTH-GUIDE.md)** - Auth adapters for provider interfaces
+- **[IAM-GUIDE.md](./IAM-GUIDE.md)** - IAM permission usage
+
+---
+
+**Last Updated:** 2026-02-07
+**Package Version:** 1.0.0
+**Angular Version:** 21

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flusys/ng-shared",
-  "version": "0.1.0-beta.1",
+  "version": "0.1.0-beta.2",
   "description": "Shared components and utilities for FLUSYS Angular packages",
   "license": "MIT",
   "peerDependencies": {