@eltonssouza/development-utility-kit 1.0.0

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

@@ -0,0 +1,494 @@
+---
+stack: typescript/angular-21
+versions_covered: "21.0.x — 21.x"
+last_validated: 2026-05-27
+validated_against: "sandbox — Angular 21.1.0 (current greenfield)"
+status: active
+pack_owner: "@elton"
+security_review: 2026-05-27
+next_review_due: 2027-05-27
+---
+
+# Angular 21 (TypeScript) — greenfield default
+
+Knowledge pack for greenfield Angular 21 projects. Default pack for any new frontend started on or after this pack's `last_validated` date. Covers zoneless apps with Signal Forms, Resource API, Server Components, and `@defer` blocks as first-class primitives. For maintained legacy projects on Angular 18 / 19, use the respective packs.
+
+## 1. When to use this pack
+
+- Project declares `Primary stack: Angular 21.x` (or `Frontend stack: Angular 21.x`) in `## Project Identity`.
+- `package.json` declares `"@angular/core": "^21.0.0"` (or higher within 21.x).
+- **DEFAULT for NEW projects (greenfield)** — `scaffold` agent selects this pack unless project explicitly pins an older major.
+- For Angular 18.x or 19.x projects in maintenance, use `angular-18.md` / `angular-19.md`. Do NOT use this pack to backport 21-only APIs (Signal Forms stable, Resource API stable, Server Components) onto those versions.
+
+## 2. Stack baseline (what this pack assumes)
+
+| Component | Version range | Notes |
+|---|---|---|
+| Angular | 21.0.x — 21.x | Current LTS at pack creation (release ~nov/2025). Standalone is the only supported mode (NgModule deprecated). |
+| Node.js | 22.x LTS | Required by Angular 21 toolchain. Node 20 EOL during 21.x lifetime. |
+| TypeScript | 5.6+ | Strict mode mandatory (`"strict": true`, `"noUncheckedIndexedAccess": true`). |
+| RxJS | 7.8.x | OPTIONAL — Resource API + Signals cover most cases. Keep for HTTP streams and event buses. |
+| UI library | Angular Material 21 (preferred greenfield) OR ng-bootstrap 19.x | Material aligns with M3 tokens and signal-based APIs in 21. |
+| Test framework | Jest 30.x + jest-preset-angular 14 | Karma is removed from `ng new` since 18; Jest is the canonical choice. |
+| Component testing | @testing-library/angular 18 | Signal-aware; works with `resource()` mocks. |
+| E2E | Playwright 1.52+ | `@playwright/test`. Replaces Protractor permanently. |
+| A11y testing | jest-axe 9.x + @axe-core/playwright 4.12+ | Per ADR-007 senior+ gate. |
+| Perf gate | @lhci/cli (Lighthouse CI) | Per ADR-007 thresholds. |
+| Builder | `application` (esbuild) | Default since 18, mandatory in 21. `browser` (webpack) builder removed. |
+| Change detection | **Zoneless** | Default for greenfield. `provideZonelessChangeDetection()` replaces `provideZoneChangeDetection()`. Zone.js NOT installed. |
+
+### Notable maturity vs Angular 19
+
+- **Signal Forms STABLE** — preferred over Reactive Forms for greenfield work.
+- **Resource API STABLE** — primary mechanism for declarative data fetching.
+- **`effect()` STABLE** — fully supported outside experimental flag.
+- **`output()` function is default** — `@Output` decorator deprecated; lint warns on use.
+- **Server Components STABLE** — SSR / hybrid rendering first-class.
+- **`linkedSignal()` mature** — derived state with explicit dependency tracking.
+- **`@defer` enriched** — supports `on viewport`, `on interaction`, `on idle`, `on hover`, `on timer`, `prefetch` triggers.
+- **Standalone-only** — NgModule path deprecated; new code rejects NgModule in code review.
+
+## 3. Project structure
+
+```
+frontend/
+├── src/
+│   ├── app/
+│   │   ├── core/                     ← auth, http interceptors, guards, singletons
+│   │   │   ├── auth/
+│   │   │   ├── interceptors/
+│   │   │   └── guards/
+│   │   ├── shared/                   ← reusable components, pipes, directives
+│   │   │   ├── components/
+│   │   │   └── pipes/
+│   │   ├── features/                 ← lazy-loaded feature areas
+│   │   │   ├── products/
+│   │   │   │   ├── product-list.component.ts
+│   │   │   │   ├── product-list.component.html
+│   │   │   │   ├── product-list.component.scss
+│   │   │   │   ├── product-form.component.ts
+│   │   │   │   ├── product-form.component.html
+│   │   │   │   ├── product-form.component.scss
+│   │   │   │   └── product.service.ts
+│   │   │   └── home/
+│   │   ├── app.config.ts             ← bootstrap providers (zoneless, router, http, etc.)
+│   │   ├── app.routes.ts             ← root routes (lazy via loadComponent)
+│   │   └── app.component.{ts,html,scss}
+│   ├── environments/
+│   │   ├── environment.ts
+│   │   └── environment.prod.ts
+│   ├── styles/                       ← global tokens, themes
+│   │   └── _tokens.scss
+│   ├── main.ts                       ← bootstrapApplication(AppComponent, appConfig)
+│   └── index.html
+├── angular.json                      ← builder: "@angular/build:application" (esbuild)
+├── tsconfig.json                     ← strict + noUncheckedIndexedAccess
+├── jest.config.ts
+├── playwright.config.ts
+├── lighthouserc.json
+└── package.json
+```
+
+## 4. Code patterns
+
+### 4.1 Component file layout (THREE FILES — HARD RULE, NON-NEGOTIABLE)
+
+Every component / directive / pipe with a template MUST have three physical files:
+
+- `name.component.ts` — logic only, uses `templateUrl` and `styleUrl` / `styleUrls`.
+- `name.component.html` — template.
+- `name.component.scss` — styles.
+
+NEVER inline `template:` or `styles:` / `styleUrls: ['...inline...']` inside the `.ts`. No size threshold, no "small component" exception, no presentation-only exception. `code-reviewer` / `tech-lead` reject merges that violate this.
+
+### 4.2 Component with `resource()` (data fetching — greenfield default)
+
+```typescript
+// product-list.component.ts
+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);
+
+  productsResource = resource({
+    loader: () => firstValueFrom(this.svc.list()),
+  });
+}
+```
+
+```html
+<!-- product-list.component.html -->
+@if (productsResource.isLoading()) {
+  <p>Loading...</p>
+} @else if (productsResource.error(); as err) {
+  <p class="error">Failed to load: {{ err.message }}</p>
+} @else {
+  <ul>
+    @for (p of productsResource.value(); track p.id) {
+      <li>{{ p.name }} — {{ p.price | currency }}</li>
+    }
+  </ul>
+}
+```
+
+**Rule**: never manage `isLoading` / `error` signals by hand for HTTP calls — `resource()` owns that lifecycle.
+
+### 4.3 Signal Forms (greenfield default — preferred over Reactive Forms)
+
+```typescript
+// product-form.component.ts
+import { Component, ChangeDetectionStrategy, output } from '@angular/core';
+import { signalForm, control } from '@angular/forms';
+import { required, maxLength, min } from '@angular/forms/validators';
+
+export interface Product {
+  name: string;
+  price: number;
+  stock: number;
+}
+
+@Component({
+  selector: 'app-product-form',
+  standalone: true,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  templateUrl: './product-form.component.html',
+  styleUrl: './product-form.component.scss',
+})
+export class ProductFormComponent {
+  saved = output<Product>();
+
+  form = signalForm({
+    name: control('', { validators: [required(), maxLength(120)] }),
+    price: control(0, { validators: [required(), min(0)] }),
+    stock: control(0, { validators: [required(), min(0)] }),
+  });
+
+  submit(): void {
+    if (this.form.valid()) {
+      this.saved.emit(this.form.value() as Product);
+    }
+  }
+}
+```
+
+**Rule**: `output()` function instead of `@Output()` decorator. Validators are functions returning `ValidatorFn` — typed end-to-end.
+
+### 4.4 `@defer` for lazy sections
+
+```html
+@defer (on viewport) {
+  <app-product-list />
+} @loading (minimum 200ms) {
+  <div class="skeleton">Loading list...</div>
+} @placeholder {
+  <div>Scroll to see products</div>
+} @error {
+  <div class="error">Failed to load the section.</div>
+}
+```
+
+**Rule**: use `@defer` for heavy, viewport-conditional sections. Route-level lazy is `loadComponent` (see 4.6). Combine both for max bundle savings.
+
+### 4.5 Server Component / SSR pattern
+
+```typescript
+// product-detail.component.ts
+import { Component, ChangeDetectionStrategy, input, resource } from '@angular/core';
+import { firstValueFrom } from 'rxjs';
+import { ProductService } from './product.service';
+import { inject } from '@angular/core';
+
+@Component({
+  selector: 'app-product-detail',
+  standalone: true,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  templateUrl: './product-detail.component.html',
+  styleUrl: './product-detail.component.scss',
+})
+export class ProductDetailComponent {
+  id = input.required<string>();
+  private svc = inject(ProductService);
+
+  productResource = resource({
+    request: () => ({ id: this.id() }),
+    loader: ({ request }) => firstValueFrom(this.svc.byId(request.id)),
+  });
+}
+```
+
+**Rule**: signal-based renders are SSR-friendly out of the box. For protected pages, validate the JWT on the server-side render boundary (interceptor running in server env) — never trust client-only auth in hybrid rendering.
+
+### 4.6 Lazy routes (`loadComponent`)
+
+```typescript
+// app.routes.ts
+import { Routes } from '@angular/router';
+
+export const routes: Routes = [
+  {
+    path: '',
+    loadComponent: () =>
+      import('./features/home/home.component').then(m => m.HomeComponent),
+  },
+  {
+    path: 'products',
+    loadComponent: () =>
+      import('./features/products/product-list.component').then(m => m.ProductListComponent),
+  },
+  {
+    path: 'products/:id',
+    loadComponent: () =>
+      import('./features/products/product-detail.component').then(m => m.ProductDetailComponent),
+  },
+];
+```
+
+### 4.7 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}` } }));
+};
+```
+
+```typescript
+// app.config.ts
+import { ApplicationConfig, provideZonelessChangeDetection } from '@angular/core';
+import { provideRouter } from '@angular/router';
+import { provideHttpClient, withInterceptors } from '@angular/common/http';
+import { routes } from './app.routes';
+import { authInterceptor } from './core/interceptors/auth.interceptor';
+
+export const appConfig: ApplicationConfig = {
+  providers: [
+    provideZonelessChangeDetection(),
+    provideRouter(routes),
+    provideHttpClient(withInterceptors([authInterceptor])),
+  ],
+};
+```
+
+**Rule**: zoneless is the default. `provideZoneChangeDetection()` only allowed during legacy migration with explicit ADR.
+
+### 4.8 Signal-based state — immutability
+
+```typescript
+import { signal } from '@angular/core';
+
+const items = signal<string[]>([]);
+
+// CORRECT — replace reference
+items.update(arr => [...arr, 'new']);
+
+// WRONG — mutates underlying array, breaks change detection guarantees
+items().push('new');
+```
+
+## 5. Testing
+
+### Unit (Jest 30 + Testing Library 18)
+
+```typescript
+// product-list.component.spec.ts
+import { render, screen } from '@testing-library/angular';
+import { of } from 'rxjs';
+import { ProductListComponent } from './product-list.component';
+import { ProductService } from './product.service';
+
+describe('ProductListComponent', () => {
+  it('renders products from resource', async () => {
+    const mockSvc = { list: () => of([{ id: '1', name: 'widget', price: 10 }]) };
+    await render(ProductListComponent, {
+      providers: [{ provide: ProductService, useValue: mockSvc }],
+    });
+    expect(await screen.findByText(/widget/)).toBeInTheDocument();
+  });
+});
+```
+
+### Signal Forms unit test
+
+```typescript
+import { ProductFormComponent } from './product-form.component';
+
+it('rejects invalid input', () => {
+  const c = new ProductFormComponent();
+  c.form.controls.name.setValue('');
+  c.form.controls.price.setValue(-5);
+  expect(c.form.valid()).toBe(false);
+});
+```
+
+### Accessibility (jest-axe — component level)
+
+```typescript
+import { render } from '@testing-library/angular';
+import { axe, toHaveNoViolations } from 'jest-axe';
+import { ProductFormComponent } from './product-form.component';
+
+expect.extend(toHaveNoViolations);
+
+it('has no a11y violations', async () => {
+  const { container } = await render(ProductFormComponent);
+  const results = await axe(container);
+  expect(results).toHaveNoViolations();
+});
+```
+
+### E2E (Playwright + axe)
+
+```typescript
+// e2e/products.spec.ts
+import { test, expect } from '@playwright/test';
+import AxeBuilder from '@axe-core/playwright';
+
+test('product list has no critical a11y violations', async ({ page }) => {
+  await page.goto('/products');
+  await expect(page.getByText(/widget/i)).toBeVisible();
+  const accessibilityScanResults = await new AxeBuilder({ page })
+    .withTags(['wcag2a', 'wcag2aa'])
+    .analyze();
+  expect(accessibilityScanResults.violations.filter(v => v.impact === 'critical' || v.impact === 'serious')).toEqual([]);
+});
+```
+
+### Lighthouse CI (perf gate per ADR-007)
+
+`lighthouserc.json` thresholds: performance >= 0.80, LCP <= 2500ms, CLS <= 0.1, TBT <= 300ms — `gate-keeper` fails the build below these.
+
+## 6. Build & run commands
+
+```bash
+npm install
+npm start                                          # esbuild dev server on http://localhost:4200
+npm run build -- --configuration=production        # production bundle (esbuild application builder)
+npm test -- --watchAll=false --coverage            # Jest with coverage
+npx playwright test                                # E2E suite
+npx playwright test --ui                           # interactive runner
+npx lhci autorun                                   # Lighthouse CI against built app
+npx eslint . --max-warnings 0                      # zero-warning policy
+npm audit --audit-level=high                       # CVE scan (0 HIGH, 0 CRITICAL per ADR-007)
+```
+
+## 7. Security (per ADR-007 + ADR-027 — MANDATORY section)
+
+### 7.1 Authentication & Authorization
+
+- **JWT** stored in memory (signal) or httpOnly cookie. NEVER `localStorage` for tokens — XSS risk.
+- **Functional HttpInterceptor** attaches `Authorization: Bearer ...` (see 4.7).
+- **`CanActivate` / `CanMatch` guards** for route-level auth + role checks. Use functional guards (`canActivateFn`).
+- **Server Components**: validate JWT on the server-render boundary; do NOT rely on client-only checks for SSR'd pages.
+- **Refresh tokens** rotated on every use; revoke on logout server-side.
+
+### 7.2 CORS
+
+Frontend does not configure CORS — backend owns it. Required: backend declares explicit `Access-Control-Allow-Origin` per environment, never `*` in production. Frontend asserts this in E2E by failing fast if cross-origin preflight fails.
+
+### 7.3 Validation & XSS
+
+- Angular template engine **auto-escapes** all interpolation by default — keep it that way.
+- **NEVER** use `[innerHTML]` with untrusted input. If unavoidable, sanitize via `DomSanitizer.bypassSecurityTrustHtml(...)` ONLY after `DOMPurify` cleaning.
+- **Signal Forms validators** are typed — invalid types fail at compile time, shrinking the exploit surface.
+- **URL params** treated as untrusted: validate shape (UUID regex, enum match) before dispatching.
+- **File upload**: enforce MIME + extension allowlist client-side AND server-side; never trust client MIME alone.
+
+### 7.4 Secrets management
+
+- NEVER commit secrets in `environment.ts` / `environment.prod.ts`.
+- Build-time env vars injected via CI (`process.env.X` replaced by build tooling); production secrets resolved via Vault / AWS Secrets Manager / Azure Key Vault and injected into the runtime container, not the bundle.
+- Local dev: `.env.local` in `.gitignore` OR `~/.secrets/<project>.env`.
+- API keys for third-party JS SDKs scoped (e.g. Stripe publishable key vs secret key) and origin-restricted in the vendor dashboard.
+
+### 7.5 Rate limiting
+
+Backend responsibility (Bucket4j on Spring Boot or equivalent). Frontend MUST:
+- Disable submit buttons during in-flight requests (`resource().isLoading()` driven).
+- Surface `429 Too Many Requests` with a respectful retry UI (countdown + retry-after).
+- Never bypass via parallel requests — orchestrate sequentially when the endpoint declares it.
+
+### 7.6 OWASP Top 10 mapping
+
+| OWASP | Mitigation in this stack |
+|---|---|
+| A01 Broken Access Control | `CanActivate` / `CanMatch` guards + role check; server enforces same — frontend is convenience, never the source of truth |
+| A02 Cryptographic Failures | HTTPS only (HSTS via backend); JWT signed RS256; Subresource Integrity (SRI) hashes on any CDN-loaded script |
+| A03 Injection / XSS | Template auto-escape; ban `[innerHTML]` with untrusted input; sanitize via DOMPurify + DomSanitizer when unavoidable |
+| A04 Insecure Design | Threat model documented per feature; Server Component boundaries explicit in ADR |
+| A05 Security Misconfiguration | CSP strict (no `unsafe-inline`, no `unsafe-eval`); `X-Frame-Options: DENY`; debug builds blocked from prod via env check |
+| A06 Vulnerable Components | `npm audit --audit-level=high` in CI; Renovate / Dependabot weekly bumps; npm provenance enforced for critical deps |
+| A07 Auth Failures | Backend rate limit + account lockout; frontend disables submit during request; MFA UI for critical flows |
+| A08 Data Integrity | SRI hashes on CDN scripts; supply chain via npm provenance + SBOM (CycloneDX); lockfile committed and verified in CI |
+| A09 Logging Failures | Browser logs scrubbed for PII; correlation ID propagated via header from interceptor; never log tokens or full request bodies |
+| A10 SSRF | N/A for pure client; Server Components with `fetch()` MUST validate target URL against allowlist before request |
+
+### 7.7 LGPD / GDPR specifics
+
+- **Opt-in cookies** — banner gates non-essential cookies; user choice persisted and respected by analytics modules (lazy-load analytics only after consent).
+- **PII tagging** — mark fields containing PII (email, CPF, phone) with a const map; logging interceptor strips tagged fields before sending to observability sink.
+- **Data subject access** — UI route `/account/data-export` triggers backend export; `account/delete` triggers soft-delete + audit log.
+- **Consent versioning** — track which consent version the user accepted; re-prompt on material policy changes.
+
+## 8. Anti-patterns (block in code-review)
+
+| Bad | Good | Why |
+|---|---|---|
+| Inline `template:` / `styles:` in `.ts` | Three separate files (`.ts` + `.html` + `.scss`) | HARD rule — non-negotiable, overrides any prior threshold-based policy |
+| `NgModule` | `standalone: true` components | NgModule deprecated in 21; new code must be standalone |
+| `any` in TypeScript | Explicit type or `unknown` + narrow | Strict mode mandatory — `any` defeats the type system |
+| `@Output() event = new EventEmitter()` | `event = output<T>()` | Decorator is deprecated; function form is typed and SSR-friendly |
+| Reactive Forms in new code | Signal Forms (`signalForm({...})`) | Signal Forms are stable in 21 and aligned with the rest of the stack |
+| Manual `isLoading` signal for HTTP | `resource({ loader })` | `resource()` owns lifecycle, error, refetch, abort |
+| `provideZoneChangeDetection()` in new project | `provideZonelessChangeDetection()` | Zoneless is the greenfield default |
+| `items().push(x)` (mutation) | `items.update(arr => [...arr, x])` | Mutation breaks signal change tracking |
+| `[innerHTML]="userInput"` | DomSanitizer + DOMPurify | XSS vector |
+| `ChangeDetectionStrategy.Default` | `ChangeDetectionStrategy.OnPush` | OnPush is mandatory — Default re-renders entire tree |
+| Routes-only lazy loading for heavy panels | `@defer (on viewport)` for sections, `loadComponent` for routes | Combine both for max bundle savings |
+| `browser` (webpack) builder | `application` (esbuild) builder | Webpack builder removed; esbuild is mandatory |
+| `localStorage.setItem('token', ...)` | In-memory signal OR httpOnly cookie | localStorage is XSS-accessible |
+| `@Autowired`-style field assignment via constructor without `inject()` for new code | `inject(Service)` | Functional `inject()` is idiomatic and works in interceptors/guards |
+| Eager loading every feature in `app.routes.ts` | `loadComponent: () => import(...)` | Bundle bloat — eager routes break LCP |
+
+## 9. Migration hints — Angular 21 → 22 (future)
+
+When `angular-22.md` lands, expect (subject to actual release notes):
+
+- TypeScript 5.7+ baseline.
+- Further evolutions of Server Components (likely streaming improvements and more `use server` directives).
+- Additional signal-based primitives (e.g. richer `linkedSignal`, async signals).
+- Possible deprecation of remaining Zone.js compat shims.
+- Stricter ESLint rules around `@Output` (likely removal) and NgModule (likely removal).
+- Use `migrator` agent — it knows both packs and proposes an ADR per cross.
+
+## 10. References
+
+- ADR-007 (Senior+ gate thresholds — a11y, Lighthouse, pyramid)
+- ADR-026 (Generic agents + stack packs architecture)
+- ADR-027 (Pack governance — frontmatter + security + CODEOWNERS)
+- ADR-029 (Canonical pack format — 10 sections)
+- Angular 21 release notes: https://blog.angular.dev/
+- Angular Update Guide: https://angular.dev/update-guide
+- Signal Forms spec: https://angular.dev/guide/signal-forms
+- Resource API spec: https://angular.dev/guide/signals/resource
+- Server Components spec: https://angular.dev/guide/ssr
+- Lighthouse CI: https://github.com/GoogleChrome/lighthouse-ci
+- OWASP Top 10 (2021): https://owasp.org/Top10/