Copilot instructions

1---
2applyTo: "**/*.ts, **/*.html, **/*.scss"
3---
4 
5## Context
6 
7This instruction file applies to Angular frontend code. The project uses Angular 15+ with standalone components as the default architecture (NgModule is only used for legacy modules). New code targets Angular 16+ and should leverage the Signals API (`signal()`, `computed()`, `effect()`) for reactive state management. Components use `OnPush` change detection throughout. The design system uses SCSS with BEM naming conventions.
8 
9---
10 
11## Coding Standards
12 
13- **Standalone components:** All new components, directives, and pipes must use `standalone: true` — no NgModule declarations unless integrating with a legacy module
14- **Signals API:** Prefer `signal()`, `computed()`, and `effect()` over RxJS `BehaviorSubject` for local component state in Angular 16+
15- **`inject()` function:** Use `inject()` for service injection in standalone components — not constructor parameter injection
16- **Typed HTTP:** Always provide a type parameter to `HttpClient` methods: `http.get<Customer[]>('/api/customers')`
17- **Async pipe:** Use the `async` pipe in templates for Observables — never manually subscribe and unsubscribe in the component class unless the subscription has side effects that must be explicitly torn down
18- **`OnPush` strategy:** All components must declare `changeDetection: ChangeDetectionStrategy.OnPush`
19- **Reactive Forms:** Use `ReactiveFormsModule` and `FormBuilder` for any form with more than two fields or validation logic
20- **Lazy loading:** All feature routes must use `loadComponent()` (standalone) or `loadChildren()` (module-based) — no eagerly loaded feature routes
21- **No `any` type:** TypeScript `any` is forbidden — use `unknown` if the type is genuinely unknown, then narrow it
22- **No direct DOM:** Never use `ElementRef.nativeElement` for DOM manipulation — use Angular directives and renderer
23- **Accessibility:** All interactive elements (`button`, `input`, `select`, links) must have meaningful `aria-*` attributes or accessible labels
24- **No inline styles:** Never bind `[style]` or `[ngStyle]` inline — use CSS classes and `[ngClass]`
25 
26---
27 
28## Preferred Patterns
29 
30### Standalone Component
31 
32```typescript
33import { Component, ChangeDetectionStrategy, inject, signal, computed } from '@angular/core';
34import { CommonModule } from '@angular/common';
35import { CustomerService } from '../services/customer.service';
36import { Customer } from '../models/customer.model';
37 
38@Component({
39  selector: 'app-customer-list',
40  standalone: true,
41  imports: [CommonModule],
42  templateUrl: './customer-list.component.html',
43  styleUrl: './customer-list.component.scss',
44  changeDetection: ChangeDetectionStrategy.OnPush,
45})
46export class CustomerListComponent {
47  private readonly customerService = inject(CustomerService);
48 
49  readonly customers = signal<Customer[]>([]);
50  readonly isLoading = signal(false);
51  readonly activeCount = computed(() => this.customers().filter(c => c.active).length);
52 
53  ngOnInit(): void {
54    this.isLoading.set(true);
55    this.customerService.getAll().subscribe({
56      next: (data) => this.customers.set(data),
57      error: (err) => console.error('Failed to load customers', err),
58      complete: () => this.isLoading.set(false),
59    });
60  }
61}
62```
63 
64### Angular HttpClient Service
65 
66```typescript
67import { Injectable, inject } from '@angular/core';
68import { HttpClient, HttpParams } from '@angular/common/http';
69import { Observable } from 'rxjs';
70import { Customer, CreateCustomerRequest } from '../models/customer.model';
71 
72@Injectable({ providedIn: 'root' })
73export class CustomerService {
74  private readonly http = inject(HttpClient);
75  private readonly baseUrl = '/api/v1/customers';
76 
77  getAll(activeOnly?: boolean): Observable<Customer[]> {
78    const params = activeOnly ? new HttpParams().set('active', 'true') : undefined;
79    return this.http.get<Customer[]>(this.baseUrl, { params });
80  }
81 
82  getById(id: string): Observable<Customer> {
83    return this.http.get<Customer>(`${this.baseUrl}/${id}`);
84  }
85 
86  create(request: CreateCustomerRequest): Observable<Customer> {
87    return this.http.post<Customer>(this.baseUrl, request);
88  }
89 
90  update(id: string, request: Partial<CreateCustomerRequest>): Observable<Customer> {
91    return this.http.put<Customer>(`${this.baseUrl}/${id}`, request);
92  }
93}
94```
95 
96### Reactive Form
97 
98```typescript
99import { Component, ChangeDetectionStrategy, inject } from '@angular/core';
100import { ReactiveFormsModule, FormBuilder, Validators } from '@angular/forms';
101import { CommonModule } from '@angular/common';
102 
103@Component({
104  selector: 'app-customer-form',
105  standalone: true,
106  imports: [CommonModule, ReactiveFormsModule],
107  templateUrl: './customer-form.component.html',
108  changeDetection: ChangeDetectionStrategy.OnPush,
109})
110export class CustomerFormComponent {
111  private readonly fb = inject(FormBuilder);
112 
113  readonly form = this.fb.group({
114    firstName: ['', [Validators.required, Validators.maxLength(100)]],
115    lastName: ['', [Validators.required, Validators.maxLength(100)]],
116    email: ['', [Validators.required, Validators.email]],
117  });
118 
119  onSubmit(): void {
120    if (this.form.invalid) return;
121    // handle valid form
122  }
123}
124```
125 
126### Lazy Loading Route
127 
128```typescript
129// app.routes.ts
130export const APP_ROUTES: Routes = [
131  {
132    path: 'customers',
133    loadComponent: () =>
134      import('./features/customers/customer-list.component').then(m => m.CustomerListComponent),
135  },
136  {
137    path: 'orders',
138    loadChildren: () =>
139      import('./features/orders/orders.routes').then(m => m.ORDER_ROUTES),
140  },
141];
142```
143 
144### NgRx Store (when shared state is needed)
145 
146```typescript
147// State defined with createFeature — colocated in one file
148export const customerFeature = createFeature({
149  name: 'customers',
150  reducer: createReducer(
151    initialState,
152    on(CustomerActions.loadCustomers, state => ({ ...state, loading: true })),
153    on(CustomerActions.loadCustomersSuccess, (state, { customers }) =>
154      ({ ...state, customers, loading: false })),
155  ),
156});
157```
158 
159### Template: `*ngFor` with `trackBy`
160 
161```html
162<!-- CORRECT: always use trackBy to prevent unnecessary DOM re-renders -->
163<ul>
164  @for (customer of customers(); track customer.id) {
165    <li class="customer-list__item">{{ customer.firstName }} {{ customer.lastName }}</li>
166  }
167</ul>
168```
169 
170### SCSS — BEM Naming
171 
172```scss
173// customer-list.component.scss
174.customer-list {
175  display: flex;
176  flex-direction: column;
177  gap: var(--spacing-md);
178 
179  &__item {
180    padding: var(--spacing-sm);
181    border-bottom: 1px solid var(--color-border);
182  }
183 
184  &__item--active {
185    font-weight: 600;
186    color: var(--color-primary);
187  }
188 
189  &__empty-state {
190    text-align: center;
191    color: var(--color-text-muted);
192  }
193}
194```
195 
196---
197 
198## Anti-Patterns — Do NOT Generate
199 
200```typescript
201// WRONG: no type on HttpClient call
202this.http.get('/api/customers');
203 
204// WRONG: any type
205const data: any = response;
206 
207// WRONG: manual subscription without takeUntil / takeUntilDestroyed
208this.customerService.getAll().subscribe(data => this.customers = data);
209// use async pipe in template instead, or takeUntilDestroyed(this.destroyRef)
210 
211// WRONG: constructor injection in standalone component (use inject() instead)
212constructor(private customerService: CustomerService) {}
213 
214// WRONG: ElementRef DOM manipulation
215this.el.nativeElement.style.display = 'none';
216 
217// WRONG: Default change detection strategy
218@Component({ selector: 'app-foo', template: '' })
219// Missing changeDetection: ChangeDetectionStrategy.OnPush
220 
221// WRONG: eager route loading
222{ path: 'orders', component: OrderListComponent }
223 
224// WRONG: NgModule for new standalone features
225@NgModule({ declarations: [MyNewComponent], ... })
226```
227 
228```html
229<!-- WRONG: inline styles -->
230<div [style.color]="'red'">text</div>
231 
232<!-- WRONG: no trackBy / track in ngFor -->
233<li *ngFor="let item of items">{{ item.name }}</li>
234 
235<!-- WRONG: no aria label on icon-only button -->
236<button (click)="delete(item)"><mat-icon>delete</mat-icon></button>
237```
238 
239---
240 
241## Dependencies & Versions
242 
243| Library | Version | Notes |
244|---------|---------|-------|
245| Angular | 15+ (16+ for Signals) | `@angular/core`, `@angular/common` |
246| RxJS | 7.x | Used for HTTP streams and complex async |
247| NgRx | 17.x | Only for shared cross-feature state |
248| Angular Material | 16+ | UI component library |
249| TypeScript | 5.x | Strict mode enabled |
250 
251---
252 
253## Test Conventions
254 
255- Use `TestBed.configureTestingModule` with `imports: [ComponentUnderTest]` for standalone components
256- Mock services with `jasmine.createSpyObj('ServiceName', ['methodA', 'methodB'])`
257- Use `HttpClientTestingModule` and `HttpTestingController` for HTTP service tests
258- Use `fakeAsync` + `tick()` for async operations; `flush()` for Promises
259- Test `signal()` values by calling the signal as a function: `expect(component.customers()).toEqual([...])`
260- Each spec file mirrors the source file: `customer-list.component.spec.ts`
261- Test `OnPush` components by calling `fixture.detectChanges()` after state mutations
262