@flusys/ng-auth 1.1.0-beta → 1.1.0

package/README.md

@@ -5,6 +5,7 @@
 `@flusys/ng-auth` provides complete authentication functionality including login, registration, token management, company/branch selection, user administration, and permission handling.
 
 **Package:** `@flusys/ng-auth`
+**Version:** 1.1.0
 **Dependencies:** ng-core, ng-shared, ng-layout
 **Build:** `npm run build:ng-auth`
 
@@ -27,7 +28,9 @@
 │  Guards                                                      │
 │  ├── authGuard           (requires authentication)          │
 │  ├── guestGuard          (allows only unauthenticated)      │
-│  └── companyFeatureGuard (requires company feature enabled) │
+│  ├── companyFeatureGuard (requires company feature enabled) │
+│  ├── emailFeatureGuard   (requires email service enabled)   │
+│  └── signUpFeatureGuard  (requires sign-up enabled)         │
 ├─────────────────────────────────────────────────────────────┤
 │  Interceptors                                                │
 │  ├── authInterceptor     (adds JWT + tenant headers)        │
@@ -273,7 +276,39 @@ import { companyFeatureGuard } from '@flusys/ng-auth';
 }
 ```
 
-**Checks:** `services.auth.enabled` in APP_CONFIG. Redirects to `/` if disabled.
+**Checks:** `enableCompanyFeature` in APP_CONFIG. Redirects to `/` if disabled.
+
+### emailFeatureGuard
+
+Protects email-related routes (forgot-password, reset-password, verify-email).
+
+```typescript
+import { emailFeatureGuard } from '@flusys/ng-auth';
+
+{
+  path: 'auth/forgot-password',
+  canActivate: [emailFeatureGuard, guestGuard],
+  loadComponent: () => import('./forgot-password.component')
+}
+```
+
+**Checks:** `services.email.enabled` in APP_CONFIG. Redirects to `/auth/login` if disabled.
+
+### signUpFeatureGuard
+
+Protects registration route when sign-up is disabled.
+
+```typescript
+import { signUpFeatureGuard } from '@flusys/ng-auth';
+
+{
+  path: 'auth/register',
+  canActivate: [signUpFeatureGuard, guestGuard],
+  loadComponent: () => import('./register.component')
+}
+```
+
+**Checks:** `enableSignUp` in APP_CONFIG (defaults to `true`). Redirects to `/auth/login` if `false`.
 
 ---
 
@@ -324,7 +359,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 +369,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,27 +427,61 @@ 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
+- **Conditional UI based on config:**
+  - "Forgot password?" link hidden when `services.email.enabled: false`
+  - "Sign Up" link hidden when `enableSignUp: false`
 
 **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)
+- **Default company/branch support:**
+  - When `defaultCompanySlug` is set: pre-fills company code field and makes it readonly
+  - When `defaultBranchSlug` is set: pre-fills branch code field and makes it readonly
+  - "Create new company" option hidden when defaults are configured
+
+**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
+- 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:**
 
@@ -430,25 +498,42 @@ getCompanyBranches(companyId);        // User's permitted branches
 ### 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.
@@ -468,11 +553,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
 
@@ -494,13 +589,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
 
@@ -706,6 +802,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
 
 ```
@@ -716,7 +873,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/
@@ -745,6 +909,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`
@@ -801,6 +986,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
@@ -811,5 +1133,26 @@ providers: [
 
 ---
 
-**Last Updated:** 2026-02-16
+**Last Updated:** 2026-02-23
+**Version:** 1.1.0
 **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 | ✅ | ✅ |