@eltonssouza/development-utility-kit 1.0.0

package/.claude/stacks/typescript/angular-18.md

@@ -0,0 +1,420 @@
+---
+stack: typescript/angular-18
+versions_covered: "18.0.x — 18.2.x"
+last_validated: 2026-05-27
+validated_against: "sandbox — Angular 18.2.5 (legacy maintenance)"
+status: active
+pack_owner: "@elton"
+security_review: 2026-05-27
+next_review_due: 2027-05-27
+---
+
+# Angular 18
+
+Knowledge pack for projects on Angular 18.x (released May 2024). Covers projects in legacy maintenance that have not yet migrated to Angular 19 (`angular-19.md`) or the harness default Angular 21 (`angular-21.md`). Standalone-first, Signals stable, new control flow stable; NO Signal Forms (only in 19+), NO Resource API (only in 19+).
+
+## 1. When to use this pack
+
+- Project declares `Frontend stack: Angular 18.x` in CLAUDE.md `## Project Identity`.
+- `frontend/package.json` declares `@angular/core: ^18.0.0` through `^18.2.x`.
+- **Greenfield: prefer `angular-21.md`** (harness default). For Angular 19 use `angular-19.md`.
+- This pack exists for **maintained legacy** — apps in production not yet migrated.
+
+## 2. Stack baseline (what this pack assumes)
+
+| Component | Version range | Notes |
+|---|---|---|
+| Angular | 18.0.x — 18.2.x | Released May 2024; LTS window short — plan upgrade |
+| Node | 20.11+ (LTS) | Node 22 also supported |
+| TypeScript | 5.4.x | Strict mode mandatory |
+| RxJS | 7.8.x | Still required for HTTP / streams |
+| ng-bootstrap | 17.x | NOT all components yet Signal-native |
+| Jest | 29.x via jest-preset-angular 14 | Karma deprecated |
+| @testing-library/angular | 17.x | Render API + userEvent |
+| Playwright | 1.45+ | E2E + Chrome DevTools Protocol |
+| @axe-core/playwright | 4.10+ | A11y on E2E flows |
+| jest-axe | 9.x | A11y per component |
+| @lhci/cli | 0.14+ | Lighthouse CI thresholds per ADR-007 |
+| Zone.js | 0.14.x (still required) | Zoneless is EXPERIMENTAL in 18 — do NOT enable in prod |
+
+**Key differences vs Angular 21:**
+- Standalone is default, BUT NgModules still work (legacy apps may mix).
+- Signals stable, but `effect()` still in **developer preview**.
+- New control flow (`@if`, `@for`, `@switch`) stable since 17, mature in 18.
+- **NO Signal Forms** — must use Reactive Forms (typed FormGroup).
+- **NO Resource API** — must use RxJS + signal bridge (`toSignal`).
+- `output()` function still optional — `@Output()` decorator still common.
+- `inject()` preferred over constructor injection but both valid.
+
+## 3. Project structure
+
+```
+frontend/
+├── src/app/
+│   ├── core/                     ← auth, http interceptors, guards, singletons
+│   │   ├── auth/
+│   │   ├── interceptors/
+│   │   └── guards/
+│   ├── shared/                   ← reusable standalone components, pipes, directives
+│   ├── features/                 ← lazy-loaded feature folders
+│   │   └── products/
+│   │       ├── product-list.component.ts
+│   │       ├── product-list.component.html
+│   │       ├── product-list.component.scss
+│   │       └── product.service.ts
+│   ├── app.config.ts             ← root ApplicationConfig (providers)
+│   ├── app.routes.ts             ← root routing with loadComponent
+│   └── app.component.{ts,html,scss}
+├── src/environments/
+│   ├── environment.ts
+│   └── environment.prod.ts
+├── src/styles/
+└── angular.json
+```
+
+## 4. Code patterns
+
+### THREE SEPARATE FILES (HARD RULE — harness universal)
+
+Every component WITH a template uses 3 physical files: `name.component.ts`, `name.component.html`, `name.component.scss`. **NEVER** inline `template:` or `styles:` / `styleUrls: ['...inline...']` in the `.ts`. No size threshold, no exception. Violation = hard block in `code-reviewer` / `tech-lead`.
+
+### Standalone component with Signal state
+
+```typescript
+// product-list.component.ts
+import { Component, signal, ChangeDetectionStrategy, inject, OnInit } from '@angular/core';
+import { CommonModule } from '@angular/common';
+import { ProductService, Product } from './product.service';
+
+@Component({
+  selector: 'app-product-list',
+  standalone: true,
+  imports: [CommonModule],
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  templateUrl: './product-list.component.html',
+  styleUrl: './product-list.component.scss',
+})
+export class ProductListComponent implements OnInit {
+  private svc = inject(ProductService);
+
+  readonly products = signal<Product[]>([]);
+  readonly loading = signal(false);
+  readonly error = signal<string | null>(null);
+
+  ngOnInit(): void {
+    this.loading.set(true);
+    this.svc.list().subscribe({
+      next: (data) => { this.products.set(data); this.loading.set(false); },
+      error: (e) => { this.error.set(e.message); this.loading.set(false); },
+    });
+  }
+}
+```
+
+**Rule**: `inject()` over constructor injection; `OnPush` always; `signal()` for local state; never expose `WritableSignal` publicly — wrap or use `asReadonly()`.
+
+### Template using new control flow
+
+```html
+<!-- product-list.component.html -->
+@if (loading()) {
+  <p>Loading...</p>
+} @else if (error()) {
+  <p class="error">{{ error() }}</p>
+} @else {
+  <ul>
+    @for (p of products(); track p.id) {
+      <li>{{ p.name }} — {{ p.price | currency }}</li>
+    } @empty {
+      <li>No products.</li>
+    }
+  </ul>
+}
+```
+
+**Rule**: prefer `@if` / `@for` / `@switch` over `*ngIf` / `*ngFor` (faster, type-narrowing, no extra imports). `track` is **mandatory** on `@for`.
+
+### Reactive Forms (Signal Forms only in 19+)
+
+```typescript
+// product-form.component.ts
+import { FormBuilder, Validators, ReactiveFormsModule } from '@angular/forms';
+
+@Component({
+  selector: 'app-product-form',
+  standalone: true,
+  imports: [ReactiveFormsModule],
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  templateUrl: './product-form.component.html',
+  styleUrl: './product-form.component.scss',
+})
+export class ProductFormComponent {
+  private fb = inject(FormBuilder);
+
+  readonly form = this.fb.nonNullable.group({
+    name: ['', [Validators.required, Validators.maxLength(120)]],
+    email: ['', [Validators.required, Validators.email]],
+    price: [0, [Validators.required, Validators.min(0)]],
+  });
+
+  submit(): void {
+    if (this.form.invalid) { this.form.markAllAsTouched(); return; }
+    const payload = this.form.getRawValue();
+    // ...dispatch
+  }
+}
+```
+
+**Rule**: always `fb.nonNullable.group(...)` for typed forms; never `any`; mark all touched on invalid submit.
+
+### Lazy routing
+
+```typescript
+// app.routes.ts
+import { Routes } from '@angular/router';
+
+export const routes: Routes = [
+  { path: '', pathMatch: 'full', redirectTo: 'products' },
+  {
+    path: 'products',
+    loadComponent: () =>
+      import('./features/products/product-list.component').then(m => m.ProductListComponent),
+  },
+  {
+    path: 'admin',
+    canMatch: [adminGuard],
+    loadChildren: () => import('./features/admin/admin.routes').then(m => m.routes),
+  },
+];
+```
+
+**Rule**: every feature lazy-loaded via `loadComponent` or `loadChildren`. Never eager-import features into root.
+
+### HttpClient + functional interceptor
+
+```typescript
+// core/interceptors/auth.interceptor.ts
+import { HttpInterceptorFn } from '@angular/common/http';
+import { inject } from '@angular/core';
+import { AuthService } from '../auth/auth.service';
+
+export const authInterceptor: HttpInterceptorFn = (req, next) => {
+  const token = inject(AuthService).token();
+  if (!token) return next(req);
+  return next(req.clone({ setHeaders: { Authorization: `Bearer ${token}` } }));
+};
+
+// app.config.ts
+import { ApplicationConfig } from '@angular/core';
+import { provideHttpClient, withInterceptors } from '@angular/common/http';
+import { provideRouter, withComponentInputBinding } from '@angular/router';
+
+export const appConfig: ApplicationConfig = {
+  providers: [
+    provideHttpClient(withInterceptors([authInterceptor])),
+    provideRouter(routes, withComponentInputBinding()),
+  ],
+};
+```
+
+**Rule**: functional interceptors (`HttpInterceptorFn`) over class-based; typed `HttpClient<T>`; never raw `fetch()` in Angular code.
+
+### Bridging RxJS to Signals (`toSignal`)
+
+```typescript
+import { toSignal } from '@angular/core/rxjs-interop';
+
+readonly user = toSignal(this.authService.user$, { initialValue: null });
+```
+
+**Rule**: prefer `toSignal` to bridge existing `Observable` services into Signal-based components.
+
+## 5. Testing
+
+### Unit + component (Jest + Testing Library)
+
+```typescript
+import { render, screen } from '@testing-library/angular';
+import userEvent from '@testing-library/user-event';
+import { ProductListComponent } from './product-list.component';
+
+describe('ProductListComponent', () => {
+  test('renders product names', async () => {
+    await render(ProductListComponent, {
+      providers: [{ provide: ProductService, useValue: { list: () => of([{ id: '1', name: 'widget', price: 10 }]) } }],
+    });
+    expect(await screen.findByText('widget')).toBeInTheDocument();
+  });
+
+  test('shows error on failure', async () => {
+    await render(ProductListComponent, {
+      providers: [{ provide: ProductService, useValue: { list: () => throwError(() => new Error('boom')) } }],
+    });
+    expect(await screen.findByText(/boom/)).toBeInTheDocument();
+  });
+});
+```
+
+### A11y per component (jest-axe — ADR-007)
+
+```typescript
+import { axe, toHaveNoViolations } from 'jest-axe';
+expect.extend(toHaveNoViolations);
+
+test('no a11y violations', async () => {
+  const { container } = await render(ProductListComponent, { providers: [/* ... */] });
+  expect(await axe(container)).toHaveNoViolations();
+});
+```
+
+### E2E (Playwright) + @axe-core/playwright
+
+```typescript
+import { test, expect } from '@playwright/test';
+import AxeBuilder from '@axe-core/playwright';
+
+test('product list is accessible', async ({ page }) => {
+  await page.goto('/products');
+  await expect(page.getByRole('list')).toBeVisible();
+  const results = await new AxeBuilder({ page }).analyze();
+  const serious = results.violations.filter(v => v.impact === 'serious' || v.impact === 'critical');
+  expect(serious).toEqual([]);
+});
+```
+
+### Lighthouse CI
+
+`lighthouserc.json` thresholds per ADR-007: performance ≥ 0.80, LCP ≤ 2500ms, CLS ≤ 0.1, TBT ≤ 300ms.
+
+## 6. Build & run commands
+
+```bash
+npm install
+npm start                                          # ng serve, port 4200
+npm run build -- --configuration=production        # prod build (AOT + budget)
+npm test -- --watchAll=false --coverage            # Jest with coverage
+npx playwright test                                # E2E
+npx playwright test --ui                           # E2E debug
+npx lhci autorun                                   # Lighthouse CI thresholds
+npm run lint                                       # ESLint --max-warnings 0
+npm audit --audit-level=high                       # CVE scan
+```
+
+## 7. Security (per ADR-007 + ADR-027 — MANDATORY)
+
+### 7.1 Authentication & Authorization
+
+- **JWT validation** via functional `HttpInterceptorFn` injecting Authorization header.
+- **Route guards**: `CanActivate` / `CanMatch` functional guards with `inject()`.
+- **Token storage**: prefer `HttpOnly Secure SameSite=Lax` cookies (set by backend). Fall back to `sessionStorage` for short-lived tokens; NEVER `localStorage` for tokens (XSS-readable).
+- **Refresh token**: rotate on every use; revoke on logout.
+
+```typescript
+export const authGuard: CanMatchFn = () => {
+  const auth = inject(AuthService);
+  const router = inject(Router);
+  return auth.isAuthenticated() ? true : router.parseUrl('/login');
+};
+```
+
+### 7.2 CORS
+
+CORS is backend-side. Frontend uses absolute URLs from `environment.apiBaseUrl`. Backend MUST explicit-list `https://app.example.com` — NEVER `*` in production. Reference companion backend pack.
+
+### 7.3 Validation & XSS
+
+- Angular **auto-escapes** by default in interpolation (`{{ }}`) and property binding.
+- **NEVER use `[innerHTML]`** with user content unless sanitized via `DomSanitizer.sanitize(SecurityContext.HTML, value)`.
+- **NEVER use `bypassSecurityTrustHtml`** unless absolutely necessary + reviewed by `security-engineer`.
+- Reactive Forms validators on every input. Backend re-validates (defense in depth).
+- File uploads: validate MIME type + size client-side AND server-side.
+
+### 7.4 Secrets management
+
+- **NEVER** commit secrets in `environment.ts` / `environment.prod.ts`.
+- Use build-time substitution: `environment.prod.ts` reads from CI env vars (`API_BASE_URL`, etc.) injected during `ng build`.
+- Public values only (API base URL, feature flags). API keys, tokens, secrets stay server-side.
+- Per-developer config: `environment.local.ts` in `.gitignore`.
+
+### 7.5 Rate limiting
+
+Frontend cannot enforce rate limiting — it lives in backend / API gateway. Frontend MUST handle 429 responses gracefully:
+
+```typescript
+catchError((err: HttpErrorResponse) => {
+  if (err.status === 429) {
+    this.toast.warning(`Too many requests. Retry after ${err.headers.get('Retry-After')}s.`);
+  }
+  return throwError(() => err);
+})
+```
+
+### 7.6 OWASP Top 10 mapping
+
+| OWASP | Mitigation in Angular 18 |
+|---|---|
+| A01 Broken Access Control | Route guards (`CanMatch`/`CanActivate`); UI gating + backend re-check; never trust client RBAC alone |
+| A02 Cryptographic Failures | HTTPS only (HSTS via backend); JWT signed RS256; NEVER store tokens in `localStorage` |
+| A03 Injection | Angular auto-escape; `DomSanitizer` for trusted HTML; never string-build URLs without `encodeURIComponent` |
+| A04 Insecure Design | Threat model per feature; PII flows reviewed by `security-engineer` |
+| A05 Security Misconfiguration | Strict CSP via meta tag or backend header; `Content-Security-Policy: default-src 'self'` |
+| A06 Vulnerable Components | `npm audit --audit-level=high` in CI; Renovate/Dependabot; remove unused deps |
+| A07 Auth Failures | Short-lived access tokens; refresh rotation; auto-logout on 401; MFA flow |
+| A08 Data Integrity | Subresource Integrity (SRI) on external scripts; webpack output integrity hashes |
+| A09 Logging Failures | Never `console.log` PII or tokens; production builds strip `console.*` via `terserOptions.compress.drop_console` |
+| A10 SSRF | N/A frontend; backend enforces outbound allowlist |
+
+### 7.7 LGPD / GDPR specifics
+
+- **Cookie consent**: opt-in banner before any non-essential cookie (analytics, ads). Default reject.
+- **PII in logs**: never `console.log` user objects; redact email/CPF/phone via a logging wrapper.
+- **Data subject access**: page that requests user data export from backend; render machine-readable JSON download.
+- **Right to deletion**: UI to request deletion; backend soft-deletes + audits.
+- **Analytics**: anonymize IP; respect `Do Not Track` header.
+
+## 8. Anti-patterns (block in code-review)
+
+| Bad | Good | Why |
+|---|---|---|
+| `template:` inline | separate `.html` via `templateUrl` | HARD RULE — harness universal |
+| `styles:` inline | separate `.scss` via `styleUrl` | HARD RULE — harness universal |
+| NgModule for new feature | standalone component | Angular 18 is standalone-first |
+| `any` in TS | explicit type or generic | TS strict mode mandatory |
+| field injection (`@Inject()` on property) | `inject()` in field initializer OR constructor | testable + immutable |
+| `ChangeDetectionStrategy.Default` | `OnPush` always | perf + predictability |
+| `signal().push(item)` mutation | `signal.update(arr => [...arr, item])` | signals require new ref |
+| `[innerHTML]="userContent"` | `DomSanitizer.sanitize(SecurityContext.HTML, value)` | XSS vector |
+| `localStorage.setItem('token', ...)` | HttpOnly cookie OR `sessionStorage` short-lived | XSS-readable storage |
+| `*ngIf` / `*ngFor` in new code | `@if` / `@for` | Faster + type-narrowing |
+| `@for` without `track` | `@for (... ; track item.id)` | Compile error in 18, mandatory |
+| Reactive Forms without `nonNullable` | `fb.nonNullable.group(...)` | typed forms, no `null \| undefined` |
+| `Subject` without `takeUntilDestroyed()` | `takeUntilDestroyed()` (Angular 16+) | memory leaks |
+| direct `fetch()` call | `HttpClient` typed | misses interceptors, retries, error handling |
+| eager-loaded feature in root | `loadComponent` / `loadChildren` lazy | bundle size |
+| Zoneless enabled in prod | keep Zone.js | zoneless is EXPERIMENTAL in 18 |
+
+## 9. Migration hints — Angular 18 → 19
+
+When migrating a project from this pack to `angular-19.md`:
+
+- **Signal Forms** arrive — alternative to Reactive Forms (opt-in, not breaking).
+- **Resource API** (`resource()`) — async data loading as a signal, replaces many `toSignal(httpService.get(...))` patterns.
+- **`linkedSignal()`** — derived state that can be reset, replaces some `computed` + `effect` patterns.
+- **`effect()` goes stable** — safe to use broadly.
+- **`output()` function** preferred over `@Output()` decorator (cleaner API, no decorator metadata).
+- **Incremental hydration** for SSR — opt-in via `withIncrementalHydration()`.
+- Zoneless leaves dev-preview in 19 — still opt-in; evaluate carefully.
+- **Hot Module Replacement** for templates becomes stable.
+- Use `migrator` agent — it knows both packs and proposes ADR per major cross.
+- Run `ng update @angular/core@19 @angular/cli@19` and review the generated migration log.
+
+## 10. References
+
+- ADR-007 (Senior+ gate thresholds — a11y, Lighthouse, pyramid)
+- ADR-026 (Generic agents + packs architecture)
+- ADR-027 (Pack governance — frontmatter, security review cadence)
+- ADR-029 (Canonical pack format)
+- Angular 18 release notes: https://blog.angular.dev/angular-v18-is-now-available-e79d5ac0affe
+- Angular Update Guide: https://angular.dev/update-guide
+- OWASP Top 10 (2021): https://owasp.org/Top10/
+- ng-bootstrap 17 docs: https://ng-bootstrap.github.io/