front-end-dev-standards 1.0.0 → 1.1.0

package/standards//360/237/205/260/357/270/217 angular.md"

@@ -0,0 +1,571 @@
+# Angular Engineering Standards
+
+Version: 1.0
+Target Framework: Angular 20+
+Architecture: Standalone + Signals First
+Applies To: All HRMS Frontend Applications
+
+---
+
+# 1. Engineering Principles
+
+## Core Principles
+
+1. Standalone Components Only
+2. Signals First State Management
+3. Functional Dependency Injection
+4. OnPush Change Detection Everywhere
+5. Strict TypeScript
+6. Accessibility by Default
+7. Performance First
+8. Testable Code
+9. Feature-Based Architecture
+10. Security by Design
+
+---
+
+# 2. Project Structure
+
+## Feature Based Structure
+
+```
+src/
+├── app/
+│   ├── core/
+│   │   ├── services/
+│   │   ├── interceptors/
+│   │   ├── guards/
+│   │   └── models/
+│   │
+│   ├── shared/
+│   │   ├── ui/
+│   │   ├── pipes/
+│   │   ├── directives/
+│   │   └── utils/
+│   │
+│   ├── features/
+│   │   ├── attendance/
+│   │   ├── payroll/
+│   │   ├── recruitment/
+│   │   └── timesheet/
+│   │
+│   └── app.routes.ts
+```
+
+## Rules
+
+* Organize by feature, never by file type.
+* Features must not import from other features directly.
+* Shared code belongs in shared/.
+* Global services belong in core/.
+
+---
+
+# 3. Component Standards
+
+## Required Component Pattern
+
+```typescript
+@Component({
+  selector: 'hr-timesheet-calendar',
+  standalone: true,
+  imports: [],
+  templateUrl: './timesheet-calendar.component.html',
+  styleUrl: './timesheet-calendar.component.scss',
+  changeDetection: ChangeDetectionStrategy.OnPush,
+})
+export class TimesheetCalendarComponent {
+  private readonly service = inject(TimesheetService);
+
+  readonly loading = signal(false);
+}
+```
+
+## Rules
+
+### Must
+
+* Standalone Components
+* OnPush Strategy
+* Signals for Local State
+* inject() for DI
+* Strongly Typed APIs
+* Accessibility Attributes
+
+### Must Not
+
+* Constructor Injection
+* Any Type
+* Business Logic in Components
+* Direct DOM Manipulation
+* Nested Subscriptions
+
+---
+
+# 4. Signals Standards
+
+## Default State Pattern
+
+```typescript
+readonly loading = signal(false);
+readonly employees = signal<Employee[]>([]);
+
+readonly activeEmployees = computed(() =>
+  this.employees().filter(e => e.active)
+);
+```
+
+## Rules
+
+Use Signals For:
+
+* UI State
+* Form State
+* Loading State
+* Selection State
+
+Use RxJS For:
+
+* HTTP Streams
+* WebSockets
+* Event Streams
+* Complex Async Flows
+
+Avoid:
+
+```typescript
+new BehaviorSubject()
+```
+
+for local component state.
+
+---
+
+# 5. Dependency Injection
+
+## Required
+
+```typescript
+private readonly employeeService = inject(EmployeeService);
+```
+
+## Forbidden
+
+```typescript
+constructor(
+ private employeeService: EmployeeService
+) {}
+```
+
+---
+
+# 6. Routing Standards
+
+## Route File
+
+```
+attendance.routes.ts
+timesheet.routes.ts
+payroll.routes.ts
+```
+
+## Rules
+
+* Lazy Load Every Feature
+* Use Functional Guards
+* No Eager Feature Loading
+* One Routes File Per Feature
+
+Example:
+
+```typescript
+{
+  path: '',
+  loadComponent: () =>
+    import('./pages/list.page')
+      .then(m => m.ListPage)
+}
+```
+
+---
+
+# 7. Form Standards
+
+## Mandatory
+
+* Typed Reactive Forms
+* Form Validation
+* Error Messaging
+* Accessibility Labels
+
+## Example
+
+```typescript
+readonly form = new FormGroup<EmployeeForm>({
+  firstName: new FormControl('', {
+    nonNullable: true,
+    validators: [Validators.required]
+  })
+});
+```
+
+## Forbidden
+
+* Template Driven Forms
+* Untyped Forms
+* Any Casts
+
+---
+
+# 8. Service Standards
+
+## Responsibilities
+
+Services:
+
+* API Calls
+* Data Transformation
+* Business Rules
+* State Coordination
+
+Components:
+
+* UI Logic Only
+
+---
+
+# 9. HTTP Standards
+
+## Requirements
+
+* Typed Responses
+* Interceptors
+* Error Handling
+* Request Timeouts
+
+Example
+
+```typescript
+this.http.get<Employee[]>('/api/employees');
+```
+
+Never:
+
+```typescript
+this.http.get<any>();
+```
+
+---
+
+# 10. Error Handling
+
+## Rules
+
+All API errors must be handled through:
+
+```typescript
+NotificationService
+```
+
+Never:
+
+```typescript
+console.error(error);
+```
+
+without user feedback.
+
+---
+
+# 11. Angular Material Standards
+
+## Approved Libraries
+
+* Angular Material
+* Angular CDK
+
+## Avoid
+
+* Bootstrap
+* jQuery Plugins
+* Random UI Libraries
+
+Material should be the primary design system.
+
+---
+
+# 12. Styling Standards
+
+## Preferred
+
+SCSS
+
+```scss
+:host {
+  display: block;
+}
+```
+
+## Naming
+
+Use BEM
+
+```scss
+.employee-card {}
+
+.employee-card__title {}
+
+.employee-card--selected {}
+```
+
+Avoid:
+
+```scss
+.red-box {}
+.bigText {}
+```
+
+---
+
+# 13. Accessibility Standards
+
+Every component must support:
+
+* Keyboard Navigation
+* Screen Readers
+* Focus States
+* ARIA Labels
+
+Example
+
+```html
+<button
+  aria-label="Submit Timesheet">
+</button>
+```
+
+Accessibility is not optional.
+
+---
+
+# 14. Security Standards
+
+## Mandatory
+
+* Sanitize HTML
+* Validate Inputs
+* Escape User Content
+* Use Angular Security APIs
+
+Never:
+
+```typescript
+element.innerHTML = userInput;
+```
+
+Never bypass Angular sanitization without review.
+
+---
+
+# 15. Performance Standards
+
+## Required
+
+* OnPush
+* Lazy Loading
+* Signals
+* track in @for
+* NgOptimizedImage
+
+Example
+
+```html
+@for(item of items(); track item.id)
+```
+
+Avoid:
+
+```html
+*ngFor="let item of items"
+```
+
+without tracking.
+
+---
+
+# 16. Testing Standards
+
+Coverage Target:
+
+* Minimum 80%
+
+Required:
+
+* Component Tests
+* Service Tests
+* Guard Tests
+
+Tools:
+
+* Jasmine
+* Karma
+* Angular Testing Utilities
+
+---
+
+# 17. Logging Standards
+
+Use:
+
+```typescript
+LoggerService
+```
+
+Never:
+
+```typescript
+console.log()
+```
+
+in production code.
+
+---
+
+# 18. Naming Conventions
+
+## Components
+
+```
+employee-list.component.ts
+```
+
+## Services
+
+```
+employee.service.ts
+```
+
+## Models
+
+```
+employee.model.ts
+```
+
+## Interfaces
+
+```typescript
+interface Employee {}
+```
+
+No "IEmployee".
+
+---
+
+# 19. Git Standards
+
+Branch Names
+
+```
+feature/timesheet-calendar
+bugfix/attendance-submit
+hotfix/login-issue
+```
+
+Commit Format
+
+```
+feat(timesheet): add weekly preview panel
+
+fix(attendance): resolve clock-in issue
+
+refactor(payroll): simplify calculations
+```
+
+---
+
+# 20. Code Review Checklist
+
+Before Merge:
+
+* No any types
+* No console logs
+* No constructor injection
+* OnPush enabled
+* Signals used where appropriate
+* Tests passing
+* Accessibility verified
+* Mobile responsive
+* Security reviewed
+
+---
+
+# 21. AI Generated Code Rules
+
+AI-generated code must:
+
+* Follow Angular Standards
+* Use Signals
+* Use inject()
+* Use Standalone Components
+* Include Types
+* Include Error Handling
+* Include Loading States
+* Include Accessibility Attributes
+
+Reject generated code that violates standards.
+
+---
+
+# 22. Anti-Patterns
+
+Never Generate:
+
+❌ NgModules
+
+❌ Constructor Injection
+
+❌ Default Change Detection
+
+❌ any Type
+
+❌ BehaviorSubject for UI State
+
+❌ Direct DOM Manipulation
+
+❌ Business Logic in Components
+
+❌ Untyped Forms
+
+❌ Manual Subscription Management
+
+❌ console.log in Production
+
+❌ jQuery
+
+❌ Inline CSS for Complex UI
+
+❌ Feature-to-Feature Coupling
+
+❌ Hardcoded API URLs
+
+❌ Magic Strings
+
+❌ Duplicate Logic
+
+---
+
+# 23. Definition of Done
+
+A feature is complete only if:
+
+* Functionality works
+* Unit Tests pass
+* Accessibility verified
+* Responsive verified
+* Error handling implemented
+* Loading states implemented
+* Types are strict
+* Security reviewed
+* Code review approved
+* Documentation updated
+* SonarQube quality gate passed