@eltonssouza/development-utility-kit 1.0.0

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

@@ -0,0 +1,397 @@
+---
+stack: typescript/angular-19
+versions_covered: "19.0.x — 19.2.x"
+last_validated: 2026-05-27
+validated_against: "sandbox — Angular 19.1.3 (mid-cycle maintenance)"
+status: active
+pack_owner: "@elton"
+security_review: 2026-05-27
+next_review_due: 2027-05-27
+---
+
+# Angular 19.x (TypeScript 5.5)
+
+Knowledge pack for projects on Angular 19.x (released Nov/2024). Covers projects in **legacy maintenance** mode — new features should target `angular-21.md`. Angular 19 introduced Resource API, Signal Forms (preview), `linkedSignal()`, stable `effect()`, and the `output()` function.
+
+## 1. When to use this pack
+
+- Project declares `Frontend stack: Angular 19.x` in `## Project Identity`.
+- `package.json` declares `@angular/core: ^19.0.0` through `^19.2.x`.
+- For Angular 18 projects: use `angular-18.md`.
+- For Angular 21+ greenfield: use `angular-21.md`. This pack is for **maintained legacy** that has not yet jumped to 21.
+
+## 2. Stack baseline (what this pack assumes)
+
+| Component | Version range | Notes |
+|---|---|---|
+| Angular | 19.0.x — 19.2.x | Released Nov/2024; LTS through May/2026 |
+| Node.js | 20.x LTS (min) / 22.x LTS preferred | Node 18 dropped in Angular 19 |
+| TypeScript | 5.5.x — 5.6.x | TS 5.7 not yet supported in 19 |
+| RxJS | 7.8.x | RxJS only for HTTP/streams; signals for local state |
+| ng-bootstrap | 18.x | Compatible with Angular 19 |
+| Jest | 29.x + jest-preset-angular 14.x | Karma deprecated; Jest is default |
+| @testing-library/angular | 17.x | Component testing — query by role/text |
+| Playwright | 1.48+ | E2E + browser-based a11y scan |
+| @axe-core/playwright | 4.10+ | E2E a11y per ADR-007 |
+| jest-axe | 9.x | Component-level a11y per ADR-007 |
+| @lhci/cli | 0.14+ | Lighthouse budget per ADR-007 |
+| Zone.js | OPTIONAL (zoneless viable in 19) | Zoneless more stable than 18 — evaluate per project |
+
+## 3. Project structure
+
+```
+frontend/
+├── src/app/
+│   ├── core/              ← auth, http interceptors, guards (CanMatchFn)
+│   ├── shared/            ← reusable standalone components, pipes, directives
+│   ├── features/          ← lazy-loaded feature folders (each with routes.ts)
+│   └── app.routes.ts
+├── src/environments/      ← environment.ts, environment.prod.ts
+├── src/styles/            ← global tokens, theme.scss
+├── src/assets/
+└── angular.json
+```
+
+**Rules**: 3 physical files per component (TS + HTML + SCSS — see §4). Standalone is default; NgModules forbidden for new code. Lazy load every feature.
+
+## 4. Code patterns
+
+### Component — 3 separate files (HARD RULE, ADR-008+)
+
+`product-list.component.ts`:
+
+```typescript
+import { Component, ChangeDetectionStrategy, inject, resource } from '@angular/core';
+import { CommonModule } from '@angular/common';
+import { firstValueFrom } from 'rxjs';
+import { ProductService } 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 {
+  private svc = inject(ProductService);
+
+  // Resource API (NEW in 19) — automatic loading/error state
+  productsResource = resource({
+    loader: () => firstValueFrom(this.svc.list()),
+  });
+}
+```
+
+`product-list.component.html`:
+
+```html
+@if (productsResource.isLoading()) {
+  <p>Loading...</p>
+} @else if (productsResource.error()) {
+  <p class="error">{{ productsResource.error()?.message }}</p>
+} @else {
+  <ul>
+    @for (p of productsResource.value(); track p.id) {
+      <li>{{ p.name }}</li>
+    } @empty {
+      <li>No products.</li>
+    }
+  </ul>
+}
+```
+
+`product-list.component.scss`:
+
+```scss
+.error { color: var(--color-error); }
+```
+
+**Rule**: NEVER inline `template:` or `styles:` in the `.ts`. No size threshold. No "small component" exception. `code-reviewer` / `tech-lead` blocks the merge on violation.
+
+### Resource API (NEW in 19)
+
+```typescript
+// reactive params + auto reload when params change
+productsResource = resource({
+  request: () => ({ category: this.category() }),
+  loader: ({ request }) => firstValueFrom(this.svc.list(request.category)),
+});
+
+// rxResource for cold observables
+detail = rxResource({
+  request: () => this.id(),
+  loader: ({ request }) => this.svc.get(request),
+});
+```
+
+**Rule**: prefer `resource()` over manual `signal<{loading,data,error}>` shapes. Replaces ad-hoc loading flags.
+
+### Signal Forms (NEW in 19 — preview)
+
+```typescript
+import { signalForm, control } from '@angular/forms';
+import { required, maxLength, email } from '@angular/forms/validators';
+
+form = signalForm({
+  name: control('', { validators: [required, maxLength(120)] }),
+  email: control('', { validators: [required, email] }),
+});
+
+submit() {
+  if (this.form.valid()) {
+    this.svc.create(this.form.value()).subscribe();
+  }
+}
+```
+
+**Note**: Signal Forms API still evolving in 19. Projects may prefer typed Reactive Forms (`FormBuilder.nonNullable.group`) until 21 stabilizes. Document trade-off in the project's `tech-debt.md`.
+
+### Output function (NEW in 19) — replaces `@Output` decorator
+
+```typescript
+// ❌ Legacy
+@Output() saved = new EventEmitter<Product>();
+
+// ✅ Angular 19
+saved = output<Product>();
+
+// emit:
+this.saved.emit(product);
+```
+
+Migration tool: `ng generate @angular/core:output-migration`.
+
+### linkedSignal — derived but mutable
+
+```typescript
+// derived value that can be overridden by user
+total = linkedSignal(() => this.items().reduce((s, i) => s + i.price, 0));
+
+// allow manual override:
+overrideTotal(v: number) { this.total.set(v); }
+```
+
+### Effect (stable in 19)
+
+```typescript
+constructor() {
+  effect(() => {
+    console.log('Cart size:', this.items().length);
+  });
+}
+```
+
+**Rule**: never trigger HTTP in `effect()` — use Resource API. Effects for logging, persistence, DOM side effects only.
+
+### Service with typed HttpClient + interceptor
+
+```typescript
+@Injectable({ providedIn: 'root' })
+export class ProductService {
+  private http = inject(HttpClient);
+  private base = '/api/v1/products';
+
+  list(category?: string): Observable<Product[]> {
+    const params = category ? new HttpParams().set('category', category) : undefined;
+    return this.http.get<Product[]>(this.base, { params });
+  }
+
+  create(req: CreateProductRequest): Observable<Product> {
+    return this.http.post<Product>(this.base, req);
+  }
+}
+
+// core/auth.interceptor.ts (functional)
+export const authInterceptor: HttpInterceptorFn = (req, next) => {
+  const token = inject(AuthStore).token();
+  return token ? next(req.clone({ setHeaders: { Authorization: `Bearer ${token}` } })) : next(req);
+};
+```
+
+### Guards (CanMatchFn — functional)
+
+```typescript
+export const authGuard: CanMatchFn = () => {
+  const auth = inject(AuthStore);
+  const router = inject(Router);
+  return auth.isLoggedIn() || router.createUrlTree(['/login']);
+};
+
+// app.routes.ts
+{
+  path: 'admin',
+  canMatch: [authGuard],
+  loadChildren: () => import('./features/admin/admin.routes'),
+}
+```
+
+## 5. Testing
+
+### Component (Jest + Testing Library)
+
+```typescript
+import { render, screen } from '@testing-library/angular';
+import { of } from 'rxjs';
+import { ProductListComponent } from './product-list.component';
+import { ProductService } from './product.service';
+
+test('resource loads and renders products', async () => {
+  await render(ProductListComponent, {
+    providers: [
+      { provide: ProductService, useValue: { list: () => of([{ id: '1', name: 'widget' }]) } },
+    ],
+  });
+  expect(await screen.findByText('widget')).toBeVisible();
+});
+```
+
+### A11y component (jest-axe — per ADR-007)
+
+```typescript
+import { axe, toHaveNoViolations } from 'jest-axe';
+expect.extend(toHaveNoViolations);
+
+test('has no a11y violations', async () => {
+  const { container } = await render(ProductListComponent, { providers: [...] });
+  expect(await axe(container)).toHaveNoViolations();
+});
+```
+
+Threshold: 0 `serious` / 0 `critical` (ADR-007).
+
+### E2E (Playwright + axe-core)
+
+```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();
+  expect(results.violations.filter(v => ['serious', 'critical'].includes(v.impact!))).toEqual([]);
+});
+```
+
+### Pyramid ratio (ADR-007)
+
+E2E ≤ 30% of total tests (hard-fail above; ideal ≤ 15%). `auto-test-guard` counts and blocks on violation.
+
+## 6. Build & run commands
+
+```bash
+npm install
+npm start                                          # ng serve, port 4200
+npm run build -- --configuration=production        # prod build
+npm test -- --watchAll=false --coverage            # Jest + coverage
+npx playwright test                                # E2E
+npx playwright test --ui                           # E2E with UI
+npx lhci autorun                                   # Lighthouse budget
+npx ng update @angular/core@19 @angular/cli@19     # safe within-major updates
+npm audit --audit-level=high                       # CVE scan
+```
+
+## 7. Security (per ADR-007 + ADR-027)
+
+### 7.1 Authentication & Authorization
+
+- **JWT** stored in `httpOnly` cookie (preferred) OR in-memory signal (NEVER `localStorage` for tokens — XSS-vulnerable).
+- **Functional `HttpInterceptorFn`** attaches `Authorization: Bearer <token>` per request.
+- **Route guards**: `CanMatchFn` for lazy-load gates (prevents bundle download for unauthorized users); `CanActivateFn` for runtime checks.
+- **Refresh token flow**: silent renewal via interceptor on 401 + retry.
+
+### 7.2 CORS
+
+Backend responsibility — Angular only consumes. NEVER request `*` from backend. Allowed origins must be the production app's origin only.
+
+### 7.3 Validation & XSS
+
+- Angular auto-escapes interpolation `{{ value }}` — safe by default.
+- **NEVER** `[innerHTML]="userInput"` without `DomSanitizer.bypassSecurityTrustHtml(...)` (and even then, audit the source).
+- **NEVER** `eval()` or `Function()` with user input.
+- Signal Forms validators are typed natively in 19 — fewer cast errors.
+- Sanitize file uploads on the backend (MIME + extension + content scan).
+
+### 7.4 Secrets management
+
+- NEVER commit API keys, OAuth client secrets, or tokens to `src/environments/*.ts`.
+- Use build-time injection via CI env vars: `ng build --define environment.apiKey="$API_KEY"`.
+- For runtime config: `/assets/config.json` fetched on bootstrap (not committed).
+- Local dev: `environment.local.ts` in `.gitignore`.
+
+### 7.5 Rate limiting
+
+Backend responsibility. Frontend SHOULD debounce search inputs and disable submit buttons during in-flight requests to avoid spamming:
+
+```typescript
+search = signal('');
+debouncedSearch = toSignal(toObservable(this.search).pipe(debounceTime(300)));
+```
+
+### 7.6 OWASP Top 10 mapping
+
+| OWASP | Mitigation in this stack |
+|---|---|
+| A01 Broken Access Control | Route guards (`CanMatchFn`) + backend re-checks; never trust frontend RBAC |
+| A02 Cryptographic Failures | TLS 1.3; tokens in `httpOnly` cookies or memory; no plaintext in `localStorage` |
+| A03 Injection | Angular auto-escape; `DomSanitizer` for trusted HTML; backend parameterized queries |
+| A04 Insecure Design | ADR for new auth/payment flows; threat-model lazy routes |
+| A05 Security Misconfiguration | CSP header from backend; `ng build --configuration=production` strips dev hooks |
+| A06 Vulnerable Components | `npm audit --audit-level=high` in CI; Renovate/Dependabot; `ng update` per minor |
+| A07 Auth Failures | Generic error messages; rate-limit handled by backend; MFA flow respects standard `oauth2-pkce` |
+| A08 Data Integrity | SRI for CDN scripts; signed build artifacts; verify lockfile in CI |
+| A09 Logging Failures | Browser console scrubbed in prod; never log JWT/PII; structured logs forwarded to backend |
+| A10 SSRF | N/A frontend-direct; ensure backend allowlists outbound URLs |
+
+### 7.7 LGPD specifics
+
+- Cookie consent banner before any non-essential cookie/analytics.
+- Right to deletion: UI flow that triggers backend soft-delete + email confirmation.
+- Data subject access: profile page exports user data as JSON via signed link.
+- PII fields tagged in forms (e.g. `data-pii="true"`) so analytics can suppress them.
+
+## 8. Anti-patterns (block in code-review)
+
+| ❌ Bad | ✅ Good | Why |
+|---|---|---|
+| `template: '<div>...'` or `styles: [...]` inline in `.ts` | 3 separate files (`.ts` + `.html` + `.scss`) | Hard rule — non-negotiable (ADR-008) |
+| `@Output() x = new EventEmitter()` (new code) | `x = output<T>()` | Function API; decorator deprecated in roadmap |
+| `any` in TypeScript | Explicit type or `unknown` + narrow | TS strict mode |
+| Manual `loading`/`error`/`data` signals | `resource()` / `rxResource()` | Built-in state machine |
+| NgModule for new feature | `standalone: true` component + `loadChildren` route | Standalone is default since 17 |
+| `ChangeDetectionStrategy.Default` | `ChangeDetectionStrategy.OnPush` | Required for signal-based change detection |
+| `signal().push(item)` (mutation) | `signal.update(arr => [...arr, item])` | Signals require new reference |
+| `[innerHTML]="userInput"` raw | `DomSanitizer.sanitize(SecurityContext.HTML, x)` | XSS risk |
+| Token in `localStorage` | `httpOnly` cookie or in-memory signal | XSS-stealable |
+| RxJS for local component state | Signals | RxJS overhead unnecessary for state |
+| `*ngIf` / `*ngFor` (legacy) | `@if` / `@for` (built-in control flow) | Type-safer + tree-shakable |
+| Zone.js for greenfield (in 19) | Evaluate zoneless (`provideExperimentalZonelessChangeDetection`) | Smaller bundle, more stable in 19 |
+| `effect()` triggering HTTP | `resource()` / explicit `subscribe` | Effects are for side effects, not data fetch |
+
+## 9. Migration hints — Angular 19 → 21
+
+When migrating a project from this pack to `angular-21.md`:
+
+- **Skip Angular 20** (released ~May/2025) if practical — jumping 19 → 21 is supported via two consecutive `ng update` runs. Read each release's breaking changes.
+- **Resource API matures** — `request` / `loader` signatures stabilize; some 19-preview options may rename.
+- **Signal Forms** leave preview — APIs from 19 may need rename (`signalForm` → final shape). Run `ng update` migration schematics.
+- **Server Components** exit experimental — may be adopted for new pages.
+- **esbuild builder** becomes default for all new projects (already opt-in in 19).
+- **Zoneless** likely default in 21 — audit any code relying on `NgZone.run`.
+- **TypeScript** moves to 5.7+ — review `tsconfig.strict` deltas.
+- Use the `migrator` agent — it knows both packs and produces an ADR per major cross.
+
+## 10. References
+
+- ADR-007 (Senior+ gate thresholds — a11y, Lighthouse, pyramid)
+- ADR-026 (Generic agents + packs architecture)
+- ADR-027 (This pack's governance — frontmatter, security review cadence)
+- ADR-029 (Canonical pack format)
+- Angular 19 release notes: https://blog.angular.dev/meet-angular-v19-7b29dfd05b84
+- Angular Update Guide: https://update.angular.io/
+- Signal Forms RFC: https://github.com/angular/angular/discussions/53485
+- Resource API docs: https://angular.dev/guide/signals/resource
+- OWASP Top 10 (2021): https://owasp.org/Top10/
+- OWASP Angular Cheat Sheet: https://cheatsheetseries.owasp.org/cheatsheets/AngularJS_Security_Cheat_Sheet.html