front-end-dev-standards 1.0.0 → 1.1.0

package/standards/angular.md

@@ -1,234 +0,0 @@
-# Angular Standards
-
-> Company-wide Angular conventions for AI-assisted and human-written code.
-> Target: Angular 20+ (standalone-first, signals-first).
-
----
-
-## Core Principles
-
-1. **Standalone only** — no `NgModule` for new features.
-2. **Signals first** — prefer `signal()`, `computed()`, `effect()` over RxJS for local state.
-3. **Functional DI** — use `inject()` instead of constructor injection.
-4. **OnPush everywhere** — default change detection strategy for all components.
-5. **Typed everything** — strict TypeScript, typed reactive forms, typed HTTP responses.
-
----
-
-## Components
-
-### Required Pattern
-
-```typescript
-import { ChangeDetectionStrategy, Component, inject, signal } from '@angular/core';
-import { EmployeeService } from '../services/employee.service';
-import { Employee } from '../models/employee.model';
-
-@Component({
-  selector: 'app-employee-list',
-  imports: [/* standalone imports only */],
-  templateUrl: './employee-list.component.html',
-  styleUrl: './employee-list.component.scss',
-  changeDetection: ChangeDetectionStrategy.OnPush,
-})
-export class EmployeeListComponent {
-  private readonly employeeService = inject(EmployeeService);
-
-  readonly employees = signal<Employee[]>([]);
-  readonly loading = signal(false);
-  readonly error = signal<string | null>(null);
-}
-```
-
-### Rules
-
-| Do | Don't |
-|---|---|
-| Standalone components | `NgModule`-based components |
-| `inject()` for DI | Constructor injection |
-| `signal()` / `computed()` for state | `BehaviorSubject` for simple UI state |
-| `ChangeDetectionStrategy.OnPush` | Default change detection |
-| `input()` / `output()` signal APIs | `@Input()` / `@Output()` decorators (legacy) |
-| `host: { class: '...' }` or `:host` in SCSS | Inline styles unless dynamic |
-| Separate `.html`, `.scss`, `.ts` files | Inline templates for complex UI |
-
-### File Naming
-
-```
-employee-list.component.ts
-employee-list.component.html
-employee-list.component.scss
-employee-list.component.spec.ts
-```
-
-Selector prefix: `app-` (application) or feature prefix e.g. `hr-` for HRMS.
-
----
-
-## Services
-
-```typescript
-import { Injectable, inject } from '@angular/core';
-import { HttpClient } from '@angular/common/http';
-import { Observable } from 'rxjs';
-import { Employee } from '../models/employee.model';
-
-@Injectable({ providedIn: 'root' })
-export class EmployeeService {
-  private readonly http = inject(HttpClient);
-  private readonly baseUrl = '/api/employees';
-
-  getAll(): Observable<Employee[]> {
-    return this.http.get<Employee[]>(this.baseUrl);
-  }
-}
-```
-
-### Rules
-
-- Use `providedIn: 'root'` unless scoped to a route or component.
-- Return typed `Observable<T>` or use `httpResource()` for signal-based HTTP (Angular 19+).
-- Keep services thin — business logic belongs in dedicated use-case/domain services when complex.
-- No `HttpClient` calls directly from components.
-
----
-
-## Routing
-
-```typescript
-import { Routes } from '@angular/router';
-
-export const EMPLOYEE_ROUTES: Routes = [
-  {
-    path: '',
-    loadComponent: () =>
-      import('./pages/employee-list/employee-list.page').then(m => m.EmployeeListPage),
-  },
-  {
-    path: ':id',
-    loadComponent: () =>
-      import('./pages/employee-detail/employee-detail.page').then(m => m.EmployeeDetailPage),
-  },
-];
-```
-
-### Rules
-
-- Lazy-load feature routes with `loadComponent`.
-- Use functional guards: `canActivate: [authGuard]`.
-- Route data and params via `input()` bindings where supported.
-- One `*.routes.ts` file per feature.
-
----
-
-## Forms
-
-Use **Typed Reactive Forms** exclusively for non-trivial forms.
-
-```typescript
-import { FormControl, FormGroup, ReactiveFormsModule, Validators } from '@angular/forms';
-
-interface EmployeeForm {
-  firstName: FormControl<string>;
-  lastName: FormControl<string>;
-  email: FormControl<string>;
-}
-
-@Component({
-  imports: [ReactiveFormsModule],
-  changeDetection: ChangeDetectionStrategy.OnPush,
-})
-export class EmployeeFormComponent {
-  readonly form = new FormGroup<EmployeeForm>({
-    firstName: new FormControl('', { nonNullable: true, validators: [Validators.required] }),
-    lastName: new FormControl('', { nonNullable: true, validators: [Validators.required] }),
-    email: new FormControl('', { nonNullable: true, validators: [Validators.required, Validators.email] }),
-  });
-}
-```
-
-### Rules
-
-| Do | Don't |
-|---|---|
-| Typed `FormGroup<T>` | Untyped forms |
-| `nonNullable: true` on controls | Nullable controls without reason |
-| Reactive forms for complex UI | Template-driven forms for multi-field forms |
-| Angular Material form controls | Custom unstyled inputs in enterprise apps |
-
----
-
-## State Management
-
-**Default:** component-level signals + services.
-
-**Use NgRx / SignalStore when:**
-
-- State is shared across multiple features.
-- Complex async orchestration is required.
-- Time-travel debugging or audit trails are needed.
-
-```typescript
-import { signalStore, withState, withMethods } from '@ngrx/signals';
-
-export const EmployeeStore = signalStore(
-  { providedIn: 'root' },
-  withState({ employees: [] as Employee[], loading: false }),
-  withMethods(/* ... */),
-);
-```
-
----
-
-## HTTP & Error Handling
-
-```typescript
-// Interceptor pattern — centralized error handling
-export const errorInterceptor: HttpInterceptorFn = (req, next) => {
-  return next(req).pipe(
-    catchError((error: HttpErrorResponse) => {
-      // log, toast, rethrow
-      return throwError(() => error);
-    }),
-  );
-};
-```
-
-- Always type HTTP responses: `http.get<Employee[]>()`.
-- Use functional interceptors (`HttpInterceptorFn`).
-- Display user-friendly errors via a shared `NotificationService`.
-
----
-
-## Angular Material
-
-- Use Material 3 theming (`@angular/material`).
-- Prefer CDK utilities (Overlay, A11y, DragDrop) over third-party equivalents.
-- Wrap Material components in feature-specific wrappers when repeated patterns emerge.
-
-```typescript
-import { MatButtonModule } from '@angular/material/button';
-import { MatTableModule } from '@angular/material/table';
-```
-
----
-
-## Performance
-
-- `track` in `@for` loops: `@for (item of items(); track item.id)`.
-- Avoid unnecessary subscriptions — use `async` pipe or signals.
-- Lazy load routes and heavy components.
-- Use `NgOptimizedImage` for static images.
-
----
-
-## Anti-Patterns (Never Generate)
-
-- ❌ `NgModule` declarations for new code
-- ❌ Constructor-based dependency injection
-- ❌ `BehaviorSubject` for simple component state
-- ❌ `any` type without explicit justification
-- ❌ Direct DOM manipulation (`document.querySelector`)
-- ❌ Business logic inside components (beyond UI orchestration)
-- ❌ Unsubscribed manual subscriptions
-- ❌ Default change detection on presentational components

package/standards/architecture.md

@@ -1,263 +0,0 @@
-# Architecture Standards
-
-> Feature-based, domain-driven frontend architecture for enterprise Angular applications.
-
----
-
-## High-Level Structure
-
-```
-src/
-├── app/
-│   ├── core/                    # Singleton services, guards, interceptors (app-wide)
-│   │   ├── auth/
-│   │   ├── interceptors/
-│   │   ├── guards/
-│   │   └── services/
-│   ├── shared/                  # Reusable UI components, pipes, directives
-│   │   ├── components/
-│   │   ├── directives/
-│   │   ├── pipes/
-│   │   └── models/
-│   ├── features/                # Business feature modules (lazy-loaded)
-│   │   ├── employees/
-│   │   │   ├── components/
-│   │   │   ├── pages/
-│   │   │   ├── services/
-│   │   │   ├── models/
-│   │   │   ├── employees.routes.ts
-│   │   │   └── index.ts
-│   │   └── payroll/
-│   ├── layout/                  # Shell, header, sidebar, footer
-│   ├── app.config.ts
-│   ├── app.routes.ts
-│   └── app.ts
-├── environments/
-└── styles/
-    ├── _variables.scss
-    ├── _mixins.scss
-    └── styles.scss
-```
-
----
-
-## Layer Responsibilities
-
-### Core Layer
-
-**Purpose:** Application-wide infrastructure used once.
-
-| Contains | Does NOT contain |
-|---|---|
-| Auth service & guards | Feature-specific business logic |
-| HTTP interceptors | UI components |
-| Global error handler | Feature models |
-| App initializer | |
-
-```
-core/
-  auth/
-    auth.service.ts
-    auth.guard.ts
-  interceptors/
-    auth.interceptor.ts
-    error.interceptor.ts
-  services/
-    notification.service.ts
-```
-
-### Shared Layer
-
-**Purpose:** Reusable, presentation-focused building blocks with no feature coupling.
-
-```
-shared/
-  components/
-    confirm-dialog/
-    data-table/
-    page-header/
-  models/
-    api-response.model.ts
-    pagination.model.ts
-```
-
-**Rules:**
-
-- Shared components must not import from `features/`.
-- Inputs/outputs only — no direct service calls to feature services.
-- Document inputs with JSDoc when non-obvious.
-
-### Features Layer
-
-**Purpose:** Self-contained business capabilities.
-
-Each feature is a vertical slice:
-
-```
-features/employees/
-  components/          # Feature-specific presentational components
-    employee-card/
-    employee-form/
-  pages/               # Routable smart components (containers)
-    employee-list/
-    employee-detail/
-  services/            # Feature API & state services
-    employee.service.ts
-  models/              # Feature domain types
-    employee.model.ts
-    employee-filter.model.ts
-  employees.routes.ts  # Feature routing
-  index.ts             # Public API barrel (optional)
-```
-
----
-
-## Smart vs Presentational Components
-
-### Presentational (Dumb)
-
-- Receives data via `input()`.
-- Emits events via `output()`.
-- No injected feature services.
-- OnPush change detection.
-
-```typescript
-@Component({
-  selector: 'app-employee-card',
-  changeDetection: ChangeDetectionStrategy.OnPush,
-})
-export class EmployeeCardComponent {
-  readonly employee = input.required<Employee>();
-  readonly selected = output<Employee>();
-}
-```
-
-### Smart (Container / Page)
-
-- Injects services.
-- Manages state with signals.
-- Passes data down to presentational components.
-
-```typescript
-@Component({
-  selector: 'app-employee-list-page',
-  changeDetection: ChangeDetectionStrategy.OnPush,
-})
-export class EmployeeListPage {
-  private readonly employeeService = inject(EmployeeService);
-  readonly employees = signal<Employee[]>([]);
-}
-```
-
-**Naming:** routable components use `.page.ts` suffix or live in `pages/` folder.
-
----
-
-## Data Flow
-
-```
-┌─────────────┐     HTTP/API     ┌─────────────┐
-│   Service   │ ◄──────────────► │   Backend   │
-└──────┬──────┘                  └─────────────┘
-       │ signal / observable
-       ▼
-┌─────────────┐   inputs/outputs  ┌──────────────────┐
-│  Page/Smart │ ────────────────► │ Presentational   │
-│  Component  │                   │ Component        │
-└─────────────┘                   └──────────────────┘
-```
-
-- Unidirectional data flow.
-- Pages orchestrate; components render.
-- No two sibling components communicating directly — go through parent or a store.
-
----
-
-## API Integration
-
-### Model Conventions
-
-```typescript
-/** Domain entity returned by GET /api/employees */
-export interface Employee {
-  id: string;
-  firstName: string;
-  lastName: string;
-  email: string;
-  departmentId: string;
-  createdAt: string; // ISO 8601 from API; map to Date in mappers if needed
-}
-
-/** Payload for POST /api/employees */
-export interface CreateEmployeeRequest {
-  firstName: string;
-  lastName: string;
-  email: string;
-  departmentId: string;
-}
-```
-
-- Separate **entity**, **request DTO**, and **response wrapper** types.
-- Map API shapes to view models in services when UI needs differ from API.
-
-### Environment Configuration
-
-```typescript
-// environments/environment.ts
-export const environment = {
-  production: false,
-  apiBaseUrl: 'http://localhost:8080/api',
-};
-```
-
-Never hardcode API URLs in services.
-
----
-
-## Cross-Cutting Concerns
-
-| Concern | Location |
-|---|---|
-| Authentication | `core/auth/` |
-| Authorization guards | `core/guards/` |
-| HTTP headers / tokens | `core/interceptors/auth.interceptor.ts` |
-| Global errors | `core/interceptors/error.interceptor.ts` + `NotificationService` |
-| Logging | `core/services/logger.service.ts` |
-| Feature flags | `core/services/feature-flag.service.ts` |
-
----
-
-## Barrel Exports
-
-Use `index.ts` sparingly at feature boundaries only:
-
-```typescript
-// features/employees/index.ts
-export { EMPLOYEE_ROUTES } from './employees.routes';
-export type { Employee } from './models/employee.model';
-```
-
-Do not create deep barrel files that cause circular dependencies.
-
----
-
-## Dependency Rules
-
-```
-features/  ──►  shared/  ──►  (no upward imports)
-    │              │
-    └──────►  core/  ◄──────┘
-
-features/  ──X──►  other features/   (use shared events, routing, or stores instead)
-```
-
-Enforce with ESLint boundary rules when available.
-
----
-
-## Scalability Guidelines
-
-1. **New feature = new folder** under `features/` with its own routes.
-2. **Promote to shared** only after reuse in 2+ features.
-3. **Split features** when a folder exceeds ~15 components or multiple unrelated domains.
-4. **Co-locate tests** next to source files (`*.spec.ts`).

package/standards/coding-style.md

@@ -1,223 +0,0 @@
-# Coding Style Standards
-
-> TypeScript and Angular style conventions for consistent, review-friendly code.
-
----
-
-## TypeScript
-
-### Strict Mode
-
-Always enable strict compiler options:
-
-```json
-{
-  "compilerOptions": {
-    "strict": true,
-    "noImplicitOverride": true,
-    "noPropertyAccessFromIndexSignature": true,
-    "noImplicitReturns": true,
-    "noFallthroughCasesInSwitch": true
-  }
-}
-```
-
-### Type Rules
-
-| Rule | Example |
-|---|---|
-| Prefer `interface` for object shapes | `interface Employee { id: string }` |
-| Use `type` for unions/intersections | `type Status = 'active' \| 'inactive'` |
-| Never use `any` | Use `unknown` + type guards |
-| Explicit return types on public methods | `getEmployee(id: string): Observable<Employee>` |
-| Use `readonly` for immutable properties | `readonly id = input.required<string>()` |
-| Use `const` by default | `const items = signal<T[]>([])` |
-
-### Naming Conventions
-
-| Element | Convention | Example |
-|---|---|---|
-| Classes | PascalCase | `EmployeeService` |
-| Interfaces | PascalCase (no `I` prefix) | `Employee`, not `IEmployee` |
-| Files | kebab-case | `employee-list.component.ts` |
-| Variables / functions | camelCase | `getEmployeeById` |
-| Constants | SCREAMING_SNAKE_CASE | `MAX_RETRY_COUNT` |
-| Signals | noun or adjective | `loading`, `employees`, `isValid` |
-| Boolean signals | `is/has/can` prefix | `isLoading`, `hasError` |
-| Observables | `$` suffix (when used) | `employees$` |
-| Private fields | `private readonly` | `private readonly http = inject(HttpClient)` |
-
----
-
-## Angular Style
-
-### Import Order
-
-1. Angular core/common
-2. Angular feature modules (router, forms, material)
-3. RxJS
-4. Third-party libraries
-5. Application core
-6. Application shared
-7. Feature-relative imports
-
-```typescript
-import { ChangeDetectionStrategy, Component, inject, signal } from '@angular/core';
-import { RouterLink } from '@angular/router';
-import { MatButtonModule } from '@angular/material/button';
-
-import { EmployeeService } from '../../services/employee.service';
-import { Employee } from '../../models/employee.model';
-```
-
-### Member Order (inside classes)
-
-1. `inject()` / DI fields
-2. `input()` / `output()` declarations
-3. Public signals / computed
-4. Protected template-facing members
-5. Constructor (avoid — use inject)
-6. Lifecycle hooks (alphabetical)
-7. Public methods
-8. Private methods
-
-### Template Style
-
-```html
-<!-- Use native control flow -->
-@if (loading()) {
-  <app-loading-spinner />
-} @else if (error(); as message) {
-  <app-error-banner [message]="message" />
-} @else {
-  <ul>
-    @for (employee of employees(); track employee.id) {
-      <li>{{ employee.firstName }} {{ employee.lastName }}</li>
-    } @empty {
-      <li>No employees found.</li>
-    }
-  </ul>
-}
-```
-
-| Do | Don't |
-|---|---|
-| `@if`, `@for`, `@switch` | `*ngIf`, `*ngFor`, `*ngSwitch` |
-| `track` in `@for` | `@for` without track |
-| Async pipe or signals in template | Manual subscribe + field assignment |
-| `[class.active]="isActive()"` | `[ngClass]` for simple cases |
-
-### SCSS Style
-
-- Use component-scoped styles (`styleUrl`).
-- Use design tokens / variables from `styles/_variables.scss`.
-- BEM-like naming for complex components: `.employee-card__title`.
-- No `!important` unless overriding third-party styles.
-
-```scss
-:host {
-  display: block;
-}
-
-.employee-card {
-  &__title {
-    font-weight: 600;
-  }
-}
-```
-
----
-
-## Comments & Documentation
-
-### When to Comment
-
-- **Do** explain *why* for non-obvious business rules.
-- **Do** use JSDoc on public service methods and shared component inputs.
-- **Don't** comment obvious code.
-
-```typescript
-/**
- * Fetches employees filtered by department.
- * API returns inactive employees unless `includeInactive` is true.
- */
-getByDepartment(departmentId: string, includeInactive = false): Observable<Employee[]> {
-  // ...
-}
-```
-
-### TODO Format
-
-```typescript
-// TODO(HRMS-1234): Replace mock data with API call after backend deploy
-```
-
----
-
-## Error Handling
-
-```typescript
-async loadEmployees(): Promise<void> {
-  this.loading.set(true);
-  this.error.set(null);
-
-  try {
-    const data = await firstValueFrom(this.employeeService.getAll());
-    this.employees.set(data);
-  } catch (err) {
-    this.error.set('Failed to load employees. Please try again.');
-    console.error('[EmployeeListPage]', err);
-  } finally {
-    this.loading.set(false);
-  }
-}
-```
-
-- Always handle errors at the page/smart component level.
-- Log with context prefix: `[ClassName]`.
-- Never swallow errors silently.
-
----
-
-## Formatting
-
-Use Prettier with project defaults:
-
-```json
-{
-  "printWidth": 100,
-  "singleQuote": true,
-  "trailingComma": "all",
-  "tabWidth": 2
-}
-```
-
-Run `prettier --write .` before committing.
-
----
-
-## Git Commit Messages
-
-Follow Conventional Commits:
-
-```
-feat(employees): add employee list page with pagination
-fix(auth): redirect to login on 401 response
-refactor(shared): extract confirm dialog to shared components
-test(employees): add unit tests for EmployeeService
-docs: update architecture standards
-```
-
----
-
-## Code Review Checklist
-
-- [ ] Standalone component with explicit `imports`
-- [ ] OnPush change detection
-- [ ] `inject()` instead of constructor DI
-- [ ] Signals for local state
-- [ ] Typed forms / typed HTTP
-- [ ] No `any` types
-- [ ] Tests for services and complex components
-- [ ] No hardcoded URLs or secrets
-- [ ] Accessibility: labels, ARIA, keyboard navigation