@flusys/ng-auth 1.0.0-beta → 1.0.0

package/README.md

@@ -324,7 +324,7 @@ provideHttpClient(
 Centralized endpoint definitions used by interceptors.
 
 ```typescript
-import { AUTH_ENDPOINTS, isAuthEndpoint, isEndpoint } from '@flusys/ng-auth';
+import { AUTH_ENDPOINTS, isEndpoint } from '@flusys/ng-auth';
 
 // Endpoint constants
 AUTH_ENDPOINTS.LOGIN          // '/auth/login'
@@ -334,8 +334,7 @@ AUTH_ENDPOINTS.REGISTER       // '/auth/register'
 AUTH_ENDPOINTS.SELECT         // '/auth/select'
 AUTH_ENDPOINTS.SWITCH_COMPANY // '/auth/switch-company'
 
-// Helper functions
-isAuthEndpoint(url);           // Check if URL is any auth endpoint
+// Helper function
 isEndpoint(url, endpoint);     // Check if URL matches specific endpoint
 ```
 
@@ -393,41 +392,106 @@ getCompanyBranches(companyId);        // User's permitted branches
 
 ## Pages
 
+All page components follow Angular 21 best practices:
+- `ChangeDetectionStrategy.OnPush` for optimal performance
+- Signal Forms (`@angular/forms/signals`) with validation
+- 100% responsive design (mobile-first with Tailwind)
+- Dark mode compatible (PrimeNG + Tailwind CSS variables)
+- `inject()` for dependency injection
+
 ### Authentication Pages
 
 **LoginPageComponent** (`/auth/login`)
 - Multi-step login: Step 1 = credentials, Step 2 = company/branch selection (if needed)
-- Visual step indicator
+- Visual step indicator (when company feature enabled)
+- Email verification step (when email not verified)
 - Auto-selects if only one company/branch available
 - Stores returnUrl for post-login redirect
+- Responsive form layout with mobile padding
 
 **RegisterPageComponent** (`/auth/register`)
 - User registration with optional company creation
-- Email/password validation
-- Terms acceptance
+- Two-column responsive grid layout
+- Email/password validation with signal forms
+- Company details section (when company feature enabled)
+
+**ForgotPasswordPageComponent** (`/auth/forgot-password`)
+- Email input with validation
+- Success state showing email sent confirmation
+
+**ResetPasswordPageComponent** (`/auth/reset-password`)
+- Password reset with token validation
+- Password confirmation matching
+- Success/invalid token states
+
+**VerifyEmailPageComponent** (`/auth/verify-email`)
+- Token verification with SSR support (TransferState)
+- Resend verification option
+- Success/failure states
+
+### Profile Page
+
+**ProfilePageComponent** (`/profile`)
+- Page title with description
+- Avatar section with initials fallback
+- Update name and phone
+- Upload profile picture (requires `PROFILE_UPLOAD_PROVIDER` from ng-storage)
+- Change password section with strength indicator
+- View company/branch info (if company feature enabled)
+- View roles/actions (requires `PROFILE_PERMISSION_PROVIDER` from ng-iam)
+- Responsive two-column layout on desktop
+
+**Optional Provider Dependencies:**
+
+| Provider | Source | Feature Enabled |
+|----------|--------|-----------------|
+| `PROFILE_UPLOAD_PROVIDER` | ng-storage via `provideStorageProviders()` | Profile picture upload |
+| `PROFILE_PERMISSION_PROVIDER` | ng-iam via `provideIamProviders()` | Roles/actions display |
+
+**Graceful Degradation:**
+- If provider not registered, feature shows "not enabled" message
+- If service disabled in config, section is hidden
+- No errors thrown for missing optional providers
 
 ### Administration Pages
 
 **AdministrationPageComponent** (`/administration`)
-- Tabbed interface: Users, Companies, Branches
-- Company/Branch tabs require company feature enabled
+- Page title "Administration" with dynamic subtitle
+- Horizontal scrolling tabs (hidden scrollbar on mobile)
+- Tabs: Users, Companies, Branches
+- Company/Branch tabs only visible when company feature enabled
 
 **User Management:**
 - `UserListComponent` - LazyLoad datatable with Edit, Delete, Permission actions
-- `UserFormComponent` - Create/edit user form
+- `UserFormComponent` - Create/edit user with auto company/branch assignment
+- Permission dialogs for company/branch assignments
 
 **Company Management:**
-- `CompanyListComponent` - Company CRUD
-- `CompanyFormComponent` - Create/edit company
+- `CompanyListComponent` - Company CRUD with View Branches action
+- `CompanyFormComponent` - Create/edit company with auto slug generation
 
 **Branch Management:**
-- `BranchListComponent` - Branch CRUD filtered by company
-- `BranchFormComponent` - Create/edit branch
+- `BranchListComponent` - Branch CRUD filtered by company dropdown
+- `BranchFormComponent` - Create/edit branch with company selection
+
+**Table Features (all list components):**
+- Responsive header (stacked on mobile)
+- Horizontal scroll wrapper (`overflow-x-auto`)
+- Conditional pagination (`[paginator]="total() > 0"`)
+- Striped rows (`p-datatable-striped`)
+- Lazy loading for performance
 
 ---
 
 ## Dialog Components
 
+Both dialog components use Angular 21 patterns:
+- `ChangeDetectionStrategy.OnPush`
+- `input.required<T>()` for required inputs
+- `output<void>()` for events
+- `effect()` for reactive data loading
+- Responsive breakpoints (`{ '960px': '90vw', '640px': '95vw' }`)
+
 ### UserCompanyPermissionDialogComponent
 
 Manages user-to-company assignments with checkboxes.
@@ -447,11 +511,21 @@ import { UserCompanyPermissionDialogComponent } from '@flusys/ng-auth';
 })
 ```
 
+**Inputs/Outputs:**
+```typescript
+readonly visible = input.required<boolean>();
+readonly user = input.required<IUser | null>();
+readonly closed = output<void>();
+readonly permissionsChanged = output<void>();
+```
+
 **Features:**
 - Shows all companies with checkboxes
 - Pre-checks assigned companies
 - Immediate save on toggle (no Save button)
 - Toast notifications for success/error
+- Loading spinner during data fetch
+- Disabled checkboxes while saving
 
 ### UserBranchPermissionDialogComponent
 
@@ -473,13 +547,14 @@ import { UserBranchPermissionDialogComponent } from '@flusys/ng-auth';
 ```
 
 **Features:**
-- Shows only companies where user has company-level permissions
-- User selects company → branches load
+- Company dropdown shows only user's permitted companies
+- Branch list loads on company selection
 - Immediate save on toggle
+- Contextual empty messages (no permissions vs no branches)
 - Scoped to user's permitted companies
 
 **Workflow:**
-1. Dialog opens → Loads user's permitted companies
+1. Dialog opens → Loads user's permitted companies via effect()
 2. User selects company → Loads branches for that company
 3. User toggles branch checkboxes → Immediately assigns/revokes
 
@@ -513,6 +588,21 @@ import { ADMINISTRATION_ROUTES } from '@flusys/ng-auth';
 }
 ```
 
+### PROFILE_ROUTES
+
+User profile page routes.
+
+```typescript
+import { PROFILE_ROUTES } from '@flusys/ng-auth';
+
+// Route: /profile
+{
+  path: 'profile',
+  canActivate: [authGuard],
+  children: PROFILE_ROUTES
+}
+```
+
 ---
 
 ## Setup
@@ -529,6 +619,8 @@ import {
   provideAuthLayoutIntegration,
   provideAuthProviders
 } from '@flusys/ng-auth';
+import { provideIamProviders } from '@flusys/ng-iam';
+import { provideStorageProviders } from '@flusys/ng-storage';
 
 export const appConfig: ApplicationConfig = {
   providers: [
@@ -542,7 +634,9 @@ export const appConfig: ApplicationConfig = {
     ),
     { provide: APP_CONFIG, useValue: DEFAULT_APP_CONFIG },
     ...provideAuthLayoutIntegration(),
-    ...provideAuthProviders()
+    ...provideAuthProviders(),
+    ...provideIamProviders(),      // Enables permissions display on profile page
+    ...provideStorageProviders(),  // Enables profile picture upload
   ]
 };
 ```
@@ -551,7 +645,7 @@ export const appConfig: ApplicationConfig = {
 
 ```typescript
 import { Routes } from '@angular/router';
-import { authGuard, guestGuard, AUTH_ROUTES, ADMINISTRATION_ROUTES } from '@flusys/ng-auth';
+import { authGuard, guestGuard, AUTH_ROUTES, ADMINISTRATION_ROUTES, PROFILE_ROUTES } from '@flusys/ng-auth';
 
 export const routes: Routes = [
   { path: 'auth', children: AUTH_ROUTES },
@@ -560,7 +654,8 @@ export const routes: Routes = [
     canActivate: [authGuard],
     children: [
       { path: 'dashboard', loadComponent: () => import('./dashboard.component') },
-      { path: 'administration', children: ADMINISTRATION_ROUTES }
+      { path: 'administration', children: ADMINISTRATION_ROUTES },
+      { path: 'profile', children: PROFILE_ROUTES }
     ]
   }
 ];
@@ -665,6 +760,67 @@ interface IUserBranchPermission { id: string; userId: string; branchId: string;
 
 ## Best Practices
 
+### Angular 21 Component Patterns
+
+All components in ng-auth follow these patterns:
+
+```typescript
+@Component({
+  selector: 'lib-example',
+  standalone: true,
+  changeDetection: ChangeDetectionStrategy.OnPush,  // Always OnPush
+  imports: [AngularModule, PrimeModule, FormField],
+  template: `...`
+})
+export class ExampleComponent {
+  // Dependency injection via inject()
+  private readonly service = inject(MyService);
+
+  // Signal-based state
+  readonly isLoading = signal(false);
+  readonly data = signal<IData | null>(null);
+
+  // Computed signals
+  readonly isValid = computed(() => this.data() !== null);
+
+  // Signal Forms
+  readonly formModel = signal<IFormModel>({ name: '', email: '' });
+  readonly formTree = form(this.formModel, (f) => {
+    required(f.name, { message: 'Name is required' });
+  });
+
+  // Error handling with proper typing
+  async onSubmit(): Promise<void> {
+    try {
+      // ...
+    } catch (error: unknown) {
+      const err = error as { error?: { message?: string } };
+      // Handle error
+    }
+  }
+}
+```
+
+### Responsive Design Patterns
+
+```html
+<!-- Responsive container -->
+<div class="flex flex-col sm:flex-row justify-between items-start sm:items-center gap-3 p-4">
+
+<!-- Two-column form grid -->
+<form class="grid grid-cols-1 md:grid-cols-2 gap-4">
+
+<!-- Right-aligned buttons -->
+<div class="flex justify-end gap-4 md:col-span-2 pt-4">
+
+<!-- Horizontally scrollable tabs -->
+<div class="scrollbar-hide flex gap-1 overflow-x-auto flex-nowrap">
+
+<!-- Responsive table wrapper -->
+<div class="overflow-x-auto">
+  <p-table [scrollable]="true" [paginator]="total() > 0">
+```
+
 ### Component Organization
 
 ```
@@ -675,7 +831,14 @@ projects/ng-auth/
 ├── pages/                         ← Route-specific pages
 │   ├── login/
 │   ├── register/
-│   └── users/
+│   ├── forgot-password/
+│   ├── reset-password/
+│   ├── verify-email/
+│   ├── profile/
+│   ├── administration/
+│   ├── users/
+│   ├── company/
+│   └── branch/
 ├── services/
 ├── guards/
 ├── interceptors/
@@ -704,6 +867,27 @@ const allCompanies = await companyApi.fetchList(); // Security risk
 - TokenRefreshInterceptor handles automatic refresh
 - Auto-persistence for company/branch selection
 
+### Type Safety
+
+Avoid `any` types - use explicit interfaces:
+
+```typescript
+// ✅ CORRECT - Explicit response type
+.subscribe({
+  next: (result: { message?: string }) => {
+    this.messageService.add({
+      severity: 'success',
+      detail: result.message,
+    });
+  },
+});
+
+// ❌ WRONG - Using any
+.subscribe({
+  next: (result: any) => { ... },
+});
+```
+
 ### Multi-Company Flow
 
 1. Login → Check if `requiresSelection: true`
@@ -760,6 +944,143 @@ providers: [
 
 ---
 
+## No-IAM Mode (Bypassing Permission Guards)
+
+When you don't use the `@flusys/ng-iam` module but your routes use `permissionGuard`, the guard will fail because no permissions are loaded.
+
+**Solution:** Set wildcard permissions in `PermissionValidatorService` after login.
+
+### How Permission Guard Works
+
+```
+Route with permissionGuard('user.view')
+    ↓
+permissionGuard() → inject(PermissionValidatorService)
+    ↓
+permissionValidator.isPermissionsLoaded() → false
+    ↓
+Redirect to '/' ❌
+```
+
+### Fix: Set Wildcard Permissions After Login
+
+#### Option 1: In Login Flow (Recommended)
+
+Update your login handling to set permissions after successful authentication:
+
+```typescript
+// login.component.ts or auth.service.ts
+import { PermissionValidatorService } from '@flusys/ng-shared';
+
+@Component({ ... })
+export class LoginComponent {
+  private readonly permissionValidator = inject(PermissionValidatorService);
+  private readonly authApi = inject(AuthApiService);
+  private readonly authState = inject(AuthStateService);
+
+  async onLogin(): Promise<void> {
+    const response = await firstValueFrom(this.authApi.login(credentials));
+    this.authState.setLoginState(response);
+
+    // When IAM is NOT used, grant all permissions via wildcard
+    this.permissionValidator.setPermissions(['*']);
+
+    // Navigate to dashboard
+    this.router.navigate(['/dashboard']);
+  }
+}
+```
+
+#### Option 2: In APP_INITIALIZER
+
+Set permissions at app startup:
+
+```typescript
+// app.config.ts
+import { APP_INITIALIZER } from '@angular/core';
+import { PermissionValidatorService } from '@flusys/ng-shared';
+
+export const appConfig: ApplicationConfig = {
+  providers: [
+    {
+      provide: APP_INITIALIZER,
+      useFactory: (permissionValidator: PermissionValidatorService) => {
+        return () => {
+          // Set wildcard permissions when IAM is disabled
+          permissionValidator.setPermissions(['*']);
+        };
+      },
+      deps: [PermissionValidatorService],
+      multi: true,
+    },
+    // ... other providers
+  ],
+};
+```
+
+#### Option 3: In AuthInitService (After Session Restore)
+
+If you restore sessions on page refresh, set permissions there:
+
+```typescript
+// After successful /auth/me response
+authInit.initialize().subscribe({
+  next: (user) => {
+    // Session restored, set wildcard permissions
+    permissionValidator.setPermissions(['*']);
+  },
+});
+```
+
+### Wildcard Permission Syntax
+
+The `permissionGuard` utilities support these patterns:
+
+| Pattern | Meaning |
+|---------|---------|
+| `*` | Full access to everything |
+| `user.*` | All user permissions |
+| `branch.*` | All branch permissions |
+
+### For Jest Tests
+
+Mock `PermissionValidatorService` in your test setup:
+
+```typescript
+import { PermissionValidatorService } from '@flusys/ng-shared';
+
+describe('MyComponent', () => {
+  beforeEach(async () => {
+    await TestBed.configureTestingModule({
+      imports: [MyComponent],
+      providers: [
+        {
+          provide: PermissionValidatorService,
+          useValue: {
+            permissions: () => ['*'],
+            isPermissionsLoaded: () => true,
+            hasPermission: () => true,
+            setPermissions: jest.fn(),
+            clearPermissions: jest.fn(),
+          },
+        },
+      ],
+    }).compileComponents();
+  });
+});
+```
+
+### For Template Permission Checks
+
+If using `*hasPermission` directive, it will also respect wildcard:
+
+```html
+<!-- This will show when permissions include '*' -->
+<button *hasPermission="'user.delete'">Delete User</button>
+```
+
+---
+
 ## See Also
 
 - [CORE-GUIDE.md](./CORE-GUIDE.md) - APP_CONFIG configuration
@@ -770,5 +1091,25 @@ providers: [
 
 ---
 
-**Last Updated:** 2026-02-15
+**Last Updated:** 2026-02-21
 **Angular Version:** 21
+
+## Component Checklist
+
+| Component | OnPush | Signal Forms | Responsive | Dark Mode |
+|-----------|--------|--------------|------------|-----------|
+| LoginPageComponent | ✅ | ✅ | ✅ | ✅ |
+| RegisterPageComponent | ✅ | ✅ | ✅ | ✅ |
+| ForgotPasswordPageComponent | ✅ | ✅ | ✅ | ✅ |
+| ResetPasswordPageComponent | ✅ | ✅ | ✅ | ✅ |
+| VerifyEmailPageComponent | ✅ | ✅ | ✅ | ✅ |
+| ProfilePageComponent | ✅ | ✅ | ✅ | ✅ |
+| AdministrationPageComponent | ✅ | N/A | ✅ | ✅ |
+| UserListComponent | ✅ | N/A | ✅ | ✅ |
+| UserFormComponent | ✅ | ✅ | ✅ | ✅ |
+| CompanyListComponent | ✅ | N/A | ✅ | ✅ |
+| CompanyFormComponent | ✅ | ✅ | ✅ | ✅ |
+| BranchListComponent | ✅ | N/A | ✅ | ✅ |
+| BranchFormComponent | ✅ | ✅ | ✅ | ✅ |
+| UserCompanyPermissionDialogComponent | ✅ | N/A | ✅ | ✅ |
+| UserBranchPermissionDialogComponent | ✅ | N/A | ✅ | ✅ |