@tungvivas/angular-vibe-kit 0.1.0

package/practices/v14-15.md

@@ -0,0 +1,133 @@
+# Angular Best Practices — v14 / v15 (NgModule Era)
+
+> Framework-level patterns only. This file describes HOW to write idiomatic
+> Angular 14/15 — syntax, DI, components, RxJS. It does NOT dictate folder
+> structure, state-management choice, or naming — those are project decisions
+> recorded in `docs/PROJECT-RULES.md` (inferred from the codebase).
+>
+> When the project already follows a correct pattern, follow the project.
+> When it is below standard, apply this standard to NEW code only.
+
+---
+
+## Module System
+- **NgModule is the norm.** Each feature has a `*.module.ts` and a `*-routing.module.ts`.
+- Standalone components exist (v14 preview, v15 stable) but the ecosystem and most projects are module-based — do not force standalone unless the project already uses it.
+- Feature modules are lazy-loaded via `loadChildren`.
+
+```typescript
+@NgModule({
+  declarations: [UserListComponent, UserCardComponent],
+  imports: [CommonModule, UserRoutingModule, ReactiveFormsModule],
+})
+export class UserModule {}
+```
+
+## Component Pattern
+- `changeDetection: ChangeDetectionStrategy.OnPush` on every component.
+- Smart (container) vs dumb (presentational) split.
+- Inputs/outputs with `@Input()` / `@Output()`.
+
+```typescript
+@Component({
+  selector: 'app-user-list',
+  templateUrl: './user-list.component.html',
+  changeDetection: ChangeDetectionStrategy.OnPush,
+})
+export class UserListComponent implements OnInit, OnDestroy {
+  users: User[] = [];
+  isLoading = false;
+  error: string | null = null;
+  private destroy$ = new Subject<void>();
+
+  constructor(private userService: UserService) {}
+
+  ngOnInit(): void { this.loadUsers(); }
+  ngOnDestroy(): void { this.destroy$.next(); this.destroy$.complete(); }
+}
+```
+
+## Template Syntax — Structural Directives
+- Use `*ngIf`, `*ngFor`, `[ngSwitch]`. (Built-in `@if/@for` does NOT exist yet.)
+- Always use `trackBy` with `*ngFor` for lists.
+
+```html
+<app-spinner *ngIf="isLoading"></app-spinner>
+<div *ngIf="error as msg" class="error">{{ msg }}</div>
+<app-user-card
+  *ngFor="let user of users; trackBy: trackById"
+  [user]="user"
+  (delete)="onDelete($event)">
+</app-user-card>
+```
+
+## Services & Dependency Injection
+- **Constructor injection** — `inject()` is not yet idiomatic here.
+- `@Injectable({ providedIn: 'root' })` for singletons.
+- HttpClient lives ONLY in services. Services return `Observable<T>`, never subscribe internally.
+
+```typescript
+@Injectable({ providedIn: 'root' })
+export class UserService {
+  private baseUrl = `${environment.apiUrl}/users`;
+  constructor(private http: HttpClient) {}
+
+  getAll(params?: UserFilterParams): Observable<ApiResponse<User[]>> {
+    return this.http.get<ApiResponse<User[]>>(this.baseUrl, { params: { ...params } });
+  }
+}
+```
+
+## HTTP
+- `HttpClientModule` imported in `CoreModule` / `AppModule`.
+- Class-based interceptors registered with `HTTP_INTERCEPTORS` multi-provider.
+- Auth interceptor attaches `Authorization`; error interceptor maps errors.
+
+```typescript
+@Injectable()
+export class AuthInterceptor implements HttpInterceptor {
+  constructor(private auth: AuthService) {}
+  intercept(req: HttpRequest<unknown>, next: HttpHandler): Observable<HttpEvent<unknown>> {
+    const token = this.auth.accessToken;
+    return token
+      ? next.handle(req.clone({ setHeaders: { Authorization: `Bearer ${token}` } }))
+      : next.handle(req);
+  }
+}
+```
+
+## Routing
+- Lazy load feature modules with `loadChildren: () => import('...').then(m => m.UserModule)`.
+- Class-based guards implementing `CanActivate`.
+
+## Reactive / RxJS
+- No Signals. State is plain class fields + RxJS (`BehaviorSubject` for shared state).
+- Tear down subscriptions with `takeUntil(this.destroy$)` and the OnDestroy pattern.
+- Prefer the `async` pipe in templates over manual subscribe.
+- Avoid `toPromise()` (deprecated) — use `firstValueFrom()` / `lastValueFrom()`.
+
+## Forms
+- Reactive Forms (`FormBuilder`) for validated forms. Template-driven only for trivial cases.
+- Show validation messages when control is `touched` and invalid.
+
+## TypeScript
+- No `any`. Interfaces/types for models. Mirror backend DTOs in `*.model.ts`.
+
+## Testing
+- Unit (service): `HttpClientTestingModule` + `HttpTestingController`.
+- Component: `TestBed.configureTestingModule` + mocked service.
+- E2E: Protractor is legacy/EOL — prefer Cypress or Playwright.
+- Runner: Karma/Jasmine by default; Jest if the project added it.
+
+## Security
+- Tokens in memory or httpOnly cookie — NOT localStorage.
+- No hardcoded API URL — use `environment`.
+
+---
+
+## Notes vs Newer Versions
+- No `@if/@for` control flow — use `*ngIf/*ngFor`.
+- No `inject()` idiom — use constructor injection.
+- No Signals — use RxJS + `BehaviorSubject`.
+- No `@defer` — lazy-load at the route/module level instead.
+- No `takeUntilDestroyed` — use the `Subject` + `takeUntil` + `ngOnDestroy` pattern.

package/practices/v16.md

@@ -0,0 +1,127 @@
+# Angular Best Practices — v16 (Signals Preview Era)
+
+> Framework-level patterns only. This file describes HOW to write idiomatic
+> Angular 16 — syntax, DI, components, RxJS/Signals. It does NOT dictate folder
+> structure, state-management choice, or naming — those are project decisions
+> recorded in `docs/PROJECT-RULES.md` (inferred from the codebase).
+>
+> When the project already follows a correct pattern, follow the project.
+> When it is below standard, apply this standard to NEW code only.
+
+---
+
+## Module System
+- **Transitional release.** Standalone is stable and recommended for new code, but many v16 projects are still NgModule-based.
+- If the project is standalone → use `bootstrapApplication` + standalone components.
+- If the project is module-based → keep adding to modules; introduce standalone only where it does not conflict.
+
+## Component Pattern
+- `changeDetection: ChangeDetectionStrategy.OnPush` on every component.
+- Smart vs dumb split.
+- **Required inputs** available: `@Input({ required: true }) user!: User;`.
+- `DestroyRef` + `takeUntilDestroyed()` introduced — use them for teardown.
+
+```typescript
+@Component({
+  selector: 'app-user-list',
+  standalone: true,
+  imports: [CommonModule, UserCardComponent],
+  templateUrl: './user-list.component.html',
+  changeDetection: ChangeDetectionStrategy.OnPush,
+})
+export class UserListComponent {
+  private userService = inject(UserService);
+  private destroyRef = inject(DestroyRef);
+
+  // Signals are in developer preview in v16 — fine to use for local state.
+  users = signal<User[]>([]);
+  isLoading = signal(false);
+}
+```
+
+## Template Syntax — Structural Directives
+- Use `*ngIf`, `*ngFor` (+ `trackBy`), `[ngSwitch]`. The `@if/@for` built-in control flow does NOT exist yet (that is v17).
+
+```html
+<app-spinner *ngIf="isLoading()"></app-spinner>
+<app-user-card
+  *ngFor="let user of users(); trackBy: trackById"
+  [user]="user"
+  (delete)="onDelete($event)">
+</app-user-card>
+```
+
+## Services & Dependency Injection
+- **`inject()` function is idiomatic in v16** — prefer it over constructor injection for new code.
+- `@Injectable({ providedIn: 'root' })` for singletons.
+- HttpClient only in services; services return `Observable<T>` and never subscribe.
+
+```typescript
+@Injectable({ providedIn: 'root' })
+export class UserService {
+  private http = inject(HttpClient);
+  private baseUrl = `${environment.apiUrl}/users`;
+
+  getAll(params?: UserFilterParams): Observable<ApiResponse<User[]>> {
+    return this.http.get<ApiResponse<User[]>>(this.baseUrl, { params: { ...params } });
+  }
+}
+```
+
+## HTTP
+- `provideHttpClient(withInterceptors([...]))` available for standalone apps (functional interceptors).
+- Module-based apps still use `HttpClientModule` + class interceptors via `HTTP_INTERCEPTORS`.
+- Avoid `toPromise()` — use `firstValueFrom()`.
+
+## Routing
+- Lazy load with `loadComponent()` (standalone) or `loadChildren()` (modules).
+- Functional guards (`CanActivateFn`) are available and preferred for new code.
+
+## Reactive / RxJS / Signals
+- **Signals are developer preview** — safe for local component state; teams may still prefer RxJS for shared state.
+- `computed()` for derived state. `effect()` for side effects.
+- Subscriptions: `takeUntilDestroyed(this.destroyRef)`.
+- Prefer the `async` pipe over manual subscribe.
+
+```typescript
+private loadUsers(): void {
+  this.isLoading.set(true);
+  this.userService.getAll()
+    .pipe(takeUntilDestroyed(this.destroyRef))
+    .subscribe({
+      next: (res) => { this.users.set(res.data); this.isLoading.set(false); },
+      error: () => { this.isLoading.set(false); },
+    });
+}
+```
+
+## Forms
+- Reactive Forms (`FormBuilder` / `NonNullableFormBuilder`) for validated forms.
+- Show validation messages when control is `touched` and invalid.
+
+## TypeScript
+- No `any`. Interfaces/types for models, mirror backend DTOs in `*.model.ts`.
+
+## Testing
+- Unit (service): `HttpClientTestingModule` + `HttpTestingController`.
+- Component: `TestBed` + mocked service.
+- E2E: Cypress or Playwright.
+- Runner: Karma/Jasmine by default; Jest if the project added it.
+
+## Security
+- Tokens in memory or httpOnly cookie — NOT localStorage.
+- No hardcoded API URL — use `environment`.
+
+---
+
+## Breaking Changes / Notes vs v14-15
+- **`inject()`** is now idiomatic (over constructor injection).
+- **`DestroyRef` + `takeUntilDestroyed()`** replace the `Subject + takeUntil + ngOnDestroy` boilerplate.
+- **Required inputs** `@Input({ required: true })`.
+- **Signals** available (developer preview) for local state.
+- **Functional interceptors/guards** available for standalone apps.
+
+## Notes vs v17
+- No `@if/@for/@switch` built-in control flow yet — still `*ngIf/*ngFor`.
+- No `@defer` blocks.
+- Standalone not yet the CLI default.

package/practices/v17.md

@@ -0,0 +1,166 @@
+# Angular Best Practices — v17 (Modern Era)
+
+> Framework-level patterns only. This file describes HOW to write idiomatic
+> Angular 17 — syntax, DI, components, RxJS. It does NOT dictate folder
+> structure, state-management choice, or naming — those are project decisions
+> recorded in `docs/PROJECT-RULES.md` (inferred from the codebase).
+>
+> Read this together with the project's own rules. When the project already
+> follows a correct pattern, follow the project. When the project is below
+> standard, apply this standard to NEW code only (see Coexistence in PROJECT-RULES.md).
+
+---
+
+## Module System
+- **Standalone components by default** — `standalone: true`. No NgModule for new code.
+- Bootstrap via `bootstrapApplication(AppComponent, appConfig)` in `main.ts`.
+- Providers configured in `app.config.ts` (`provideRouter`, `provideHttpClient`, etc.).
+- NgModule still supported — if the project is module-based, do not migrate; add new features as standalone where it does not conflict.
+
+## Component Pattern
+- `changeDetection: ChangeDetectionStrategy.OnPush` on every component.
+- Smart (page/container) components own data + side effects; presentational (dumb) components only render and emit.
+- Keep templates in separate `.html` files for non-trivial components.
+
+```typescript
+@Component({
+  selector: 'app-user-list',
+  standalone: true,
+  imports: [UserCardComponent, MatPaginatorModule],
+  templateUrl: './user-list.component.html',
+  changeDetection: ChangeDetectionStrategy.OnPush,
+})
+export class UserListComponent {
+  private userService = inject(UserService);
+  private destroyRef = inject(DestroyRef);
+
+  users = signal<User[]>([]);
+  isLoading = signal(false);
+  error = signal<string | null>(null);
+}
+```
+
+## Template Syntax — Built-in Control Flow (new in v17)
+- Use `@if`, `@else`, `@for`, `@switch` — the new built-in control flow.
+- `@for` **requires** `track`: `@for (user of users(); track user.id) { ... }`.
+- Prefer `@defer` for heavy/below-the-fold blocks.
+
+```html
+@if (isLoading()) {
+  <app-spinner />
+} @else if (error()) {
+  <app-error [message]="error()!" />
+} @else {
+  @for (user of users(); track user.id) {
+    <app-user-card [user]="user" (delete)="onDelete($event)" />
+  } @empty {
+    <app-empty-state message="No users yet" />
+  }
+}
+```
+
+- `*ngIf` / `*ngFor` still work but prefer the new syntax for new code. Do not mass-migrate legacy templates.
+
+## Services & Dependency Injection
+- Use the `inject()` function instead of constructor injection for new code.
+- `@Injectable({ providedIn: 'root' })` for singleton services.
+- HttpClient lives ONLY in services — never call HTTP from a component.
+- Services return `Observable<T>` — never subscribe inside a service.
+
+```typescript
+@Injectable({ providedIn: 'root' })
+export class UserService {
+  private http = inject(HttpClient);
+  private baseUrl = `${environment.apiUrl}/users`;
+
+  getAll(params?: UserFilterParams): Observable<ApiResponse<User[]>> {
+    return this.http.get<ApiResponse<User[]>>(this.baseUrl, { params: { ...params } });
+  }
+  getById(id: number): Observable<ApiResponse<User>> {
+    return this.http.get<ApiResponse<User>>(`${this.baseUrl}/${id}`);
+  }
+  create(payload: CreateUserRequest): Observable<ApiResponse<User>> {
+    return this.http.post<ApiResponse<User>>(this.baseUrl, payload);
+  }
+}
+```
+
+## HTTP
+- Configure with `provideHttpClient(withInterceptors([...]))` — functional interceptors.
+- Auth: a functional interceptor attaches the `Authorization` header.
+- Errors: an error interceptor maps HTTP errors to user-facing messages; components show them.
+- Never use `toPromise()` (removed) — use `firstValueFrom()` if a promise is truly needed.
+
+```typescript
+export const authInterceptor: HttpInterceptorFn = (req, next) => {
+  const token = inject(AuthService).accessToken();
+  return token
+    ? next(req.clone({ setHeaders: { Authorization: `Bearer ${token}` } }))
+    : next(req);
+};
+```
+
+## Routing
+- Lazy-load every feature route with `loadComponent()` / `loadChildren()`.
+- Functional guards: `CanActivateFn`. Functional resolvers: `ResolveFn`.
+
+```typescript
+export const routes: Routes = [
+  { path: 'login', loadComponent: () => import('./features/auth/pages/login/login.component').then(m => m.LoginComponent) },
+  {
+    path: '',
+    canActivate: [authGuard],
+    children: [
+      { path: 'users', loadComponent: () => import('./features/user/pages/user-list/user-list.component').then(m => m.UserListComponent) },
+    ],
+  },
+];
+```
+
+## Reactive / RxJS / Signals
+- **Signals** for component state (`signal`, `computed`, `effect`). `computed()` for derived state — never duplicate state.
+- For subscriptions, always tear down with `takeUntilDestroyed(destroyRef)`.
+- Prefer the `async` pipe in templates over manual `subscribe`.
+- `toSignal()` / `toObservable()` bridge RxJS and signals when needed.
+
+```typescript
+private loadUsers(): void {
+  this.isLoading.set(true);
+  this.userService.getAll()
+    .pipe(takeUntilDestroyed(this.destroyRef))
+    .subscribe({
+      next: (res) => { this.users.set(res.data); this.isLoading.set(false); },
+      error: () => { this.error.set('Could not load users'); this.isLoading.set(false); },
+    });
+}
+```
+
+## Forms
+- Reactive Forms (`FormBuilder` / `NonNullableFormBuilder`) for anything with validation.
+- Template-driven only for 1–2 trivial fields.
+- Show validation messages when a control is `touched` and invalid.
+
+## TypeScript
+- No `any`. Use `interface`/`type`, `unknown` + narrowing for untrusted input.
+- Mirror backend DTOs in `*.model.ts` (e.g. `ApiResponse<T>`, `PaginationResponse<T>`).
+- `readonly` for inputs that never change.
+
+## Testing
+- Unit (service): `HttpClientTestingModule` + `HttpTestingController`. Test success + error + empty per method.
+- Component: `TestBed` + mocked service (`jasmine.createSpyObj` or `jest.fn()`). Test render, interaction, loading, error states.
+- E2E: Playwright for critical flows (login, CRUD).
+- Runner: Jest or Karma/Jasmine — follow whatever the project already uses.
+
+## Security
+- Tokens in memory or httpOnly cookie — NOT localStorage.
+- Never hardcode the API URL — use `environment`.
+- Guard routes that require auth.
+
+---
+
+## Breaking Changes vs v16
+- **Built-in control flow** `@if/@for/@switch` introduced (stable). `@for` requires `track`.
+- **`@defer`** blocks introduced for lazy view loading.
+- Standalone is the default in the CLI scaffolding.
+- Vite + esbuild is the default dev/build pipeline.
+- `toPromise()` fully removed — use `firstValueFrom()`.

package/practices/v18-19.md

@@ -0,0 +1,121 @@
+# Angular Best Practices — v18 / v19 (Signal-First Era)
+
+> Framework-level patterns only. This file describes HOW to write idiomatic
+> Angular 18/19 — syntax, DI, components, Signals. It does NOT dictate folder
+> structure, state-management choice, or naming — those are project decisions
+> recorded in `docs/PROJECT-RULES.md` (inferred from the codebase).
+>
+> When the project already follows a correct pattern, follow the project.
+> When it is below standard, apply this standard to NEW code only.
+
+---
+
+## Module System
+- **Standalone everywhere.** In v19 standalone is the implicit default (`standalone: true` no longer needs to be written, though being explicit is fine).
+- Bootstrap with `bootstrapApplication(AppComponent, appConfig)`.
+- Providers in `app.config.ts`. Do not add NgModules for new code.
+
+## Component Pattern
+- `ChangeDetectionStrategy.OnPush` everywhere (or run zoneless — see below).
+- **Signal-based inputs/outputs** are idiomatic:
+  - `input()` / `input.required()` instead of `@Input()`.
+  - `output()` instead of `@Output()`.
+  - `model()` for two-way binding.
+  - `viewChild()` / `contentChild()` signal queries.
+
+```typescript
+@Component({
+  selector: 'app-user-card',
+  imports: [],
+  templateUrl: './user-card.component.html',
+  changeDetection: ChangeDetectionStrategy.OnPush,
+})
+export class UserCardComponent {
+  user = input.required<User>();
+  delete = output<number>();
+  onDeleteClick(): void { this.delete.emit(this.user().id); }
+}
+```
+
+## Template Syntax — Built-in Control Flow
+- `@if`, `@else`, `@for` (with required `track`), `@switch`, `@defer`, `@empty`, `@placeholder`.
+- These are the default and `*ngIf/*ngFor` are effectively legacy — use the block syntax for all new templates.
+
+```html
+@if (isLoading()) {
+  <app-spinner />
+} @else {
+  @for (user of users(); track user.id) {
+    <app-user-card [user]="user" (delete)="onDelete($event)" />
+  } @empty {
+    <app-empty-state message="No users yet" />
+  }
+}
+```
+
+## Services & Dependency Injection
+- `inject()` everywhere. Constructor injection is legacy.
+- `@Injectable({ providedIn: 'root' })` for singletons.
+- HttpClient only in services; services return `Observable<T>` and never subscribe.
+
+## HTTP
+- `provideHttpClient(withInterceptors([...]))` with functional interceptors.
+- `httpResource()` (v19+, experimental) for declarative resource fetching where it fits — otherwise plain HttpClient.
+- Never use `toPromise()` — use `firstValueFrom()`.
+
+```typescript
+export const authInterceptor: HttpInterceptorFn = (req, next) => {
+  const token = inject(AuthService).accessToken();
+  return token
+    ? next(req.clone({ setHeaders: { Authorization: `Bearer ${token}` } }))
+    : next(req);
+};
+```
+
+## Routing
+- Lazy-load with `loadComponent()` / `loadChildren()`.
+- Functional guards (`CanActivateFn`) and resolvers (`ResolveFn`).
+
+## Reactive / Signals (signal-first)
+- **Signals are the primary state primitive.** `signal`, `computed`, `effect`, `linkedSignal` (v19), `resource()` / `rxResource()` (v19, experimental).
+- Bridge with `toSignal()` / `toObservable()`.
+- Subscriptions (when still needed): `takeUntilDestroyed(destroyRef)`.
+- Prefer the `async` pipe / signal reads in templates over manual subscribe.
+- **Zoneless** change detection is available (experimental via `provideExperimentalZonelessChangeDetection()`). If the project enables it, do NOT rely on `setTimeout`/zone-triggered CD — drive updates through signals.
+
+```typescript
+export class UserListComponent {
+  private userService = inject(UserService);
+  private destroyRef = inject(DestroyRef);
+
+  users = signal<User[]>([]);
+  isLoading = signal(false);
+  userCount = computed(() => this.users().length);
+}
+```
+
+## Forms
+- Reactive Forms (`NonNullableFormBuilder`) for validated forms.
+- Show validation messages when a control is `touched` and invalid.
+
+## TypeScript
+- No `any`. Interfaces/types for models, mirror backend DTOs in `*.model.ts`. `readonly` where applicable.
+
+## Testing
+- Unit (service): `HttpClientTestingModule` + `HttpTestingController` (or `provideHttpClientTesting()`).
+- Component: `TestBed` + mocked service; assert signal values and rendered output.
+- E2E: Playwright.
+- Runner: Jest or Karma/Jasmine — follow the project. (Web Test Runner / Vitest also appear in newer setups.)
+
+## Security
+- Tokens in memory or httpOnly cookie — NOT localStorage.
+- No hardcoded API URL — use `environment`.
+
+---
+
+## Breaking Changes / Notes vs v17
+- **Signal inputs/outputs**: `input()`, `input.required()`, `output()`, `model()`, signal queries (`viewChild()`/`contentChild()`). Developer preview in v17.1–v18; **production-ready as of v19**. Preferred over decorators for new code on v19; on v18 confirm the team accepts the preview API.
+- **`linkedSignal()`** (introduced v19, experimental) and **`resource()` / `rxResource()` / `httpResource()`** (experimental — `httpResource` from v19.2) for derived & async state. Treat all as experimental on v18-19.
+- **Zoneless** change detection available but **experimental** — `provideExperimentalZonelessChangeDetection()` (becomes stable `provideZonelessChangeDetection()` in v20).
+- **Standalone is the implicit default since v19** (`standalone: true` optional). On v18 and earlier `standalone` defaults to `false` — must be set explicitly.
+- Event replay / incremental hydration (`@defer`-powered) is **developer preview** here (graduates to stable in v20) — relevant only with SSR.