SKILL: Angular 20+ Ecosystem Master Guide

This master skill document consolidates Angular Core, v20 Control Flow, Signals, CDK, Material 3, Router, Forms, Google Maps, NgRx Signals, and RxJS Patterns into a unified architecture reference.

---

🏗️ 1. Core Architecture: Standalone & Zone-less

Component Standards

• Standalone components only: Use standalone: true.
• OnPush Change Detection: Every component must use changeDetection: ChangeDetectionStrategy.OnPush.
• Signals-first: Use input(), output(), model(), viewChild(), and contentChild() (Angular 19+ syntax).
• Control Flow: Use @if, @for (item of items; track item.id), @switch, and @defer. Avoid *ngIf, *ngFor.

Dependency Injection

• Use inject(Type) instead of constructor injection for cleaner, more modern code.
• Provide global services/tokens in app.config.ts.

---

🚦 2. State Management: NgRx Signals

The signalStore Pattern

• Centralized State: Define a single signalStore per feature module or bounded context.
• withState: Initialize with plain objects (use null instead of undefined).
• withComputed: Derived state should be pure and reactive.
• withMethods: Handle business logic and state transitions.

Async Operations with rxMethod

• Use rxMethod for async side effects (API calls).
• Concurrency Control: Choose the right operator:
  • switchMap: For searches, filters (cancels previous).
  • exhaustMap: For form submissions (ignores concurrent clicks).
  • concatMap: For ordered sequential operations.
  • mergeMap: For independent parallel operations.
• Always use tapResponse from @ngrx/operators for structured error handling.

---

🧱 3. UI Component Layer: Angular Material 3 & CDK

Material Design 3 (M3)

• Token-based theming: Use M3 design tokens (--mat-sys-...) and CSS variables.
• Global Styles: Defined in styles.scss using the modern SASS mixins.
• Forms: Use <mat-form-field> with standard validation patterns.

Angular CDK (Component Dev Kit)

• A11y: Use A11yModule, FocusTrap, and LiveAnnouncer for accessible experiences.
• Overlays: Use OverlayModule for custom dialogs, tooltips, and floating UI.
• Virtual Scroll: Use CdkVirtualScrollViewport for large lists (>100 items).
• Drag & Drop: Use @angular/cdk/drag-drop for list reordering and board layouts.

---

🗺️ 4. Navigation & Mapping

Angular Router

• Lazy Loading: Always use loadChildren: () => import(...).
• Functional Guards: Replace class-based guards with functions using inject().
• Reactive Params: Convert route parameters to signals using toSignal(route.params).

Google Maps integration

• Lazy Loading: Load API script dynamically via a service.
• API Key Security: Store keys in environment.ts (never hardcode).
• Marker Clustering: Required for >50 markers to maintain performance.

---

🧪 5. RxJS & Signals Interop

The Boundary Pattern

• Infrastructure/Ports: Return Observables from repositories (for stream-based data).
• Application/Facade: Convert to Signals using toSignal().
• Cleanup: Use takeUntilDestroyed() or toSignal() to ensure automatic unsubscription.
• Expensive Streams: Use shareReplay({ bufferSize: 1, refCount: true }).

---

📋 6. Form Handling: Reactive & Typed

• Strictly Typed: Use FormGroup<T>, FormControl<T>.
• Validation: Show errors only after touched.
• Signals Sync: Update the store via onChanges or explicit submission methods.

---

♿ 7. Accessibility (A11y)

• WCAG 2.2 Level AA: Minimum requirement.
• Semantic HTML: Prioritize <nav>, <main>, <header>, <footer>.
• Keyboard Navigation: Ensure tabindex and focus management are solid.
• ARIA: Use aria-label, aria-describedby, and aria-live where native HTML is insufficient.

---

Note: This document is the source of truth for all Angular-related development in Black-Tortoise. Non-compliant code will be rejected by the CI pipeline.