Cline

# Angular Guidelines Use this guidelines when working with Angular related code. ## 1. Core Architecture - **Standalone Components:** Components, directives, and pipes are standalone by default. The `standalone: true` flag is no longer required and should be omitted in new code (Angular v17+ and above). - **Strong Typing:** TypeScript types, interfaces, and models provide type safety throughout the codebase - **Single Responsibility:** Each component and service has a single, well-defined responsibility - **Rule of One:** Files focus on a single concept or functionality - **Reactive State:** Signals provide reactive and efficient state management - **Dependency Injection:** Angular's DI system manages service instances - **Function-Based DI:** Use function-based dependency injection with the `inject()` function instead of constructor-based injection in all new code. Example: ```typescript import { inject } from "@angular/core"; import { HttpClient } from "@angular/common/http"; export class MyService { private readonly http = inject(HttpClient); // ... } ``` - **Lazy Loading:** Deferrable Views and route-level lazy loading with `loadComponent` improve performance - **Directive Composition:** The Directive Composition API enables reusable component behavior - **Standalone APIs Only:** Do not use NgModules, CommonModule, or RouterModule. Import only required standalone features/components. - **No Legacy Modules:** Do not use or generate NgModules for new features. Migrate existing modules to standalone APIs when possible. ## 2. Angular Style Guide Patterns - **Code Size:** Files are limited to 400 lines of code - **Single Purpose Files:** Each file defines one entity (component, service, etc.) - **Naming Conventions:** Symbols have consistent, descriptive names - **Folder Structure:** Code is organized by feature-based folders - **File Separation:** Templates and styles exist in their own files for components - **Property Decoration:** Input and output properties have proper decoration - **Component Selectors:** Component selectors use custom prefixes and kebab-case (e.g., `app-feature-name`) - **No CommonModule or RouterModule Imports:** Do not import CommonModule or RouterModule in standalone components. Import only the required standalone components, directives, or pipes. ## 3. Input Signal Patterns - **Signal-Based Inputs:** The `input()` function creates InputSignals: ```typescript // Current pattern readonly value = input(0); // Creates InputSignal // Legacy pattern @Input() value = 0; ``` - **Required Inputs:** The `input.required()` function marks inputs as mandatory: ```typescript readonly value = input.required<number>(); ``` - **Input Transformations:** Transformations convert input values: ```typescript readonly disabled = input(false, { transform: booleanAttribute }); readonly value = input(0, { transform: numberAttribute }); ``` - **Two-Way Binding:** Model inputs enable two-way binding: ```typescript readonly value = model(0); // Creates a model input with change propagation // Model values update with .set() or .update() increment(): void { this.value.update(v => v + 1); } ``` - **Input Aliases:** Aliases provide alternative input names: ```typescript readonly value = input(0, { alias: "sliderValue" }); ``` ## 3a. Typed Reactive Forms - **Typed Forms:** Always use strictly typed reactive forms by defining an interface for the form values and using `FormGroup<MyFormType>`, `FormBuilder.group<MyFormType>()`, and `FormControl<T>()`. - **Non-Nullable Controls:** Prefer `nonNullable: true` for controls to avoid null issues and improve type safety. - **Patch and Get Values:** Use `patchValue` and `getRawValue()` to work with typed form values. - **Reference:** See the [Angular Typed Forms documentation](https://angular.dev/guide/forms/typed-forms) for details and examples. ## 4. Component Patterns - **Naming Pattern:** Components follow consistent naming - `feature.type.ts` (e.g., `hero-list.component.ts`) - **Template Extraction:** Non-trivial templates exist in separate `.html` files - **Style Extraction:** Styles exist in separate `.css/.scss` files - **Signal-Based Inputs:** Components use the `input()` function for inputs - **Two-Way Binding:** Components use the `model()` function for two-way binding - **Lifecycle Hooks:** Components implement appropriate lifecycle hook interfaces (OnInit, OnDestroy, etc.) - **Element Selectors:** Components use element selectors (`selector: 'app-hero-detail'`) - **Logic Delegation:** Services contain complex logic - **Input Initialization:** Inputs have default values or are marked as required - **Lazy Loading:** The `@defer` directive loads heavy components or features - **Error Handling:** Try-catch blocks handle errors - **Modern Control Flow:** Templates use `@if`, `@for`, `@switch` instead of structural directives - **State Representation:** Components implement loading and error states - **Derived State:** The `computed()` function calculates derived state - **No NgModules:** Do not use or reference NgModules in new code. ## 5. Styling Patterns - **Component Encapsulation:** Components use scoped styles with proper encapsulation - **CSS Methodology:** BEM methodology guides CSS class naming when not using Angular Material - **Component Libraries:** Angular Material or other component libraries provide consistent UI elements - **Theming:** Color systems and theming enable consistent visual design - **Accessibility:** Components follow a11y standards - **Dark Mode:** Components support dark mode where appropriate ## 5a. Angular Material and Angular CDK Usage - **Standard UI Library:** Use Angular Material v3 for all standard UI components (buttons, forms, navigation, dialogs, etc.) to ensure consistency, accessibility, and alignment with Angular best practices. - **Component Development:** Build new UI components and features using Angular Material components as the foundation. Only create custom components when Material does not provide a suitable solution. - **Behavioral Primitives:** Use Angular CDK for advanced behaviors (drag-and-drop, overlays, accessibility, virtual scrolling, etc.) and for building custom components that require low-level primitives. - **Theming:** Leverage Angular Material's theming system for consistent color schemes, dark mode support, and branding. Define and use custom themes in `styles.scss` or feature-level styles as needed. - **Accessibility:** All UI components must meet accessibility (a11y) standards. Prefer Material components for built-in a11y support. When using CDK or custom components, follow WCAG and ARIA guidelines. - **Best Practices:** - Prefer Material's layout and typography utilities for spacing and text. - Use Material icons and fonts for visual consistency. - Avoid mixing multiple UI libraries in the same project. - Reference the [Angular Material documentation](https://material.angular.io) for usage patterns and updates. - **CDK Utilities:** Use Angular CDK utilities for custom behaviors, overlays, accessibility, and testing harnesses. - **Migration:** For legacy or custom components, migrate to Angular Material/CDK where feasible. ## 5b. Template Patterns - **Modern Control Flow:** Use the new Angular control flow syntax: `@if`, `@for`, `@switch` in templates. Do not use legacy structural directives such as `*ngIf`, `*ngFor`, or `*ngSwitch`. - **No Legacy Structural Directives:** Remove or migrate any usage of `*ngIf`, `*ngFor`, or `*ngSwitch` to the new control flow syntax in all new code. Legacy code should be migrated when touched. - **Referencing Conditional Results:** When using `@if`, reference the result using the `as` keyword, e.g. `@if (user(); as u) { ... }`. This is the recommended pattern for accessing the value inside the block. See the [Angular documentation](https://angular.dev/guide/templates/control-flow#referencing-the-conditional-expressions-result) for details. ## 6. Service and DI Patterns - **Service Declaration:** Services use the `@Injectable()` decorator with `providedIn: 'root'` for singletons - **Data Services:** Data services handle API calls and data operations - **Error Handling:** Services include error handling - **DI Hierarchy:** Services follow the Angular DI hierarchy - **Service Contracts:** Interfaces define service contracts - **Focused Responsibilities:** Services focus on specific tasks - **Function-Based DI:** Use function-based dependency injection with the `inject()` function instead of constructor-based injection in all new code. Example: ```typescript import { inject } from "@angular/core"; import { HttpClient } from "@angular/common/http"; export class MyService { private readonly http = inject(HttpClient); // ... } ``` ## 7. Directive and Pipe Patterns - **Attribute Directives:** Directives handle presentation logic without templates - **Host Property:** The `host` property manages bindings and listeners: ```typescript @Directive({ selector: '[appHighlight]', host: { // Host bindings '[class.highlighted]': 'isHighlighted', '[style.color]': 'highlightColor', // Host listeners '(click)': 'onClick($event)', '(mouseenter)': 'onMouseEnter()', '(mouseleave)': 'onMouseLeave()', // Static properties 'role': 'button', '[attr.aria-label]': 'ariaLabel' } }) ``` - **Selector Prefixes:** Directive selectors use custom prefixes - **Pure Pipes:** Pipes are pure when possible for better performance - **Pipe Naming:** Pipes follow camelCase naming conventions ## 8. State Management Patterns - **Signals:** Signals serve as the primary state management solution - **Component Inputs:** Signal inputs with `input()` handle component inputs - **Two-Way Binding:** Model inputs with `model()` enable two-way binding - **Local State:** Writable signals with `signal()` manage local component state - **Derived State:** Computed signals with `computed()` calculate derived state - **Side Effects:** The `effect()` function handles side effects - **Error Handling:** Signal computations include error handling - **Signal Conversion:** The `toSignal()` and `toObservable()` functions enable interoperability with RxJS ## 9. Testing Patterns - **Test Coverage:** Tests cover components and services - **Unit Tests:** Focused unit tests verify services, pipes, and components - **Component Testing:** TestBed and component harnesses test components - **Mocking:** Tests use mocking techniques for dependencies - **Test Organization:** Tests follow the AAA pattern (Arrange, Act, Assert) - **Test Naming:** Tests have descriptive names that explain the expected behavior - **Playwright Usage:** Playwright handles E2E testing with fixtures and test isolation - **Test Environment:** Test environments match production as closely as possible ## 10. Performance Patterns - **Change Detection:** Components use OnPush change detection strategy - **Lazy Loading:** Routes and components load lazily - **Virtual Scrolling:** Virtual scrolling renders long lists efficiently - **Memoization:** Memoization optimizes expensive computations - **Bundle Size:** Bundle size monitoring and optimization reduce load times - **Server-Side Rendering:** SSR improves initial load performance - **Web Workers:** Web workers handle intensive operations ## 11. Security Patterns - **XSS Prevention:** User input undergoes sanitization - **CSRF Protection:** CSRF tokens secure forms - **Content Security Policy:** CSP headers restrict content sources - **Authentication:** Secure authentication protects user accounts - **Authorization:** Authorization checks control access - **Sensitive Data:** Client-side code excludes sensitive data ## 12. Accessibility Patterns - **ARIA Attributes:** ARIA attributes enhance accessibility - **Keyboard Navigation:** Interactive elements support keyboard access - **Color Contrast:** UI elements maintain proper color contrast ratios - **Screen Readers:** Components work with screen readers - **Focus Management:** Focus management guides user interaction - **Alternative Text:** Images include alt text

# NgRx Signals Patterns This document outlines the state management patterns used in our Angular applications with NgRx Signals Store. ## 1. NgRx Signals Architecture - **Component-Centric Design:** Stores are designed around component requirements - **Hierarchical State:** State is organized in hierarchical structures - **Computed State:** Derived state uses computed values - **Declarative Updates:** State updates use patchState for immutability - **Store Composition:** Stores compose using features and providers - **Reactivity:** UIs build on automatic change detection - **Signal Interoperability:** Signals integrate with existing RxJS-based systems - **SignalMethod & RxMethod:** Use `signalMethod` for lightweight, signal-driven side effects; use `rxMethod` for Observable-based side effects and RxJS integration. When a service returns an Observable, always use `rxMethod` for side effects instead of converting to Promise or using async/await. ## 2. Signal Store Structure - **Store Creation:** The `signalStore` function creates stores - **Protected State:** Signal Store state is protected by default (`{ protectedState: true }`) - **State Definition:** Initial state shape is defined with `withState<StateType>({...})` - Root level state is always an object: `withState({ users: [], count: 0 })` - Arrays are contained within objects: `withState({ items: [] })` - **Dependency Injection:** Stores are injectable with `{ providedIn: 'root' }` or feature/component providers - **Store Features:** Built-in features (`withEntities`, `withHooks`, `signalStoreFeature`) handle cross-cutting concerns and enable store composition - **State Interface:** State interfaces provide strong typing - **Private Members:** Prefix all internal state, computed signals, and methods with an underscore (`_`). Ensure unique member names across state, computed, and methods. ```typescript withState({ count: 0, _internalCount: 0 }); withComputed(({ count, _internalCount }) => ({ doubleCount: computed(() => count() * 2), _doubleInternal: computed(() => _internalCount() * 2), })); ``` - **Member Integrity:** Store members have unique names across state, computed, and methods - **Initialization:** State initializes with meaningful defaults - **Collection Management:** The `withEntities` feature manages collections. Prefer atomic entity operations (`addEntity`, `updateEntity`, `removeEntity`, `setAllEntities`) over bulk state updates. Use `entityConfig` and `selectId` for entity identification. - **Entity Adapter Configuration:** Use `entityConfig` to configure the entity adapter for each store. Always specify the `entity` type, `collection` name, and a `selectId` function for unique entity identification. Pass the config to `withEntities<T>(entityConfig)` for strong typing and consistent entity management. ```typescript const userEntityConfig = entityConfig({ entity: type<User>(), collection: "users", selectId: (user: User) => user.id, }); export const UserStore = signalStore( { providedIn: "root" }, withState(initialState), withEntities(userEntityConfig), // ... ); ``` - **Custom Store Properties:** Use `withProps` to add static properties, observables, and dependencies. Expose observables with `toObservable`. ```typescript // Signal store structure example import { signalStore, withState, withComputed, withMethods, patchState, type, } from "@ngrx/signals"; import { withEntities, entityConfig } from "@ngrx/signals/entities"; import { computed, inject } from "@angular/core"; import { UserService } from "./user.service"; import { User } from "./user.model"; import { setAllEntities } from "@ngrx/signals/entities"; export interface UserState { selectedUserId: string | null; loading: boolean; error: string | null; } const initialState: UserState = { selectedUserId: null, loading: false, error: null, }; const userEntityConfig = entityConfig({ entity: type<User>(), collection: "users", selectId: (user: User) => user.id, }); export const UserStore = signalStore( { providedIn: "root" }, withState(initialState), withEntities(userEntityConfig), withComputed(({ usersEntities, usersEntityMap, selectedUserId }) => ({ selectedUser: computed(() => { const id = selectedUserId(); return id ? usersEntityMap()[id] : undefined; }), totalUserCount: computed(() => usersEntities().length), })), withMethods((store, userService = inject(UserService)) => ({ loadUsers: rxMethod<void>( pipe( switchMap(() => { patchState(store, { loading: true, error: null }); return userService.getUsers().pipe( tapResponse({ next: (users) => patchState(store, setAllEntities(users, userEntityConfig), { loading: false, }), error: () => patchState(store, { loading: false, error: "Failed to load users", }), }), ); }), ), ), selectUser(userId: string | null): void { patchState(store, { selectedUserId: userId }); }, })), ); ``` ## 3. Signal Store Methods - **Method Definition:** Methods are defined within `withMethods` - **Dependency Injection:** The `inject()` function accesses services within `withMethods` - **Method Organization:** Methods are grouped by domain functionality - **Method Naming:** Methods have clear, action-oriented names - **State Updates:** `patchState(store, newStateSlice)` or `patchState(store, (currentState) => newStateSlice)` updates state immutably - **Async Operations:** Methods handle async operations and update loading/error states - **Computed Properties:** `withComputed` defines derived state - **RxJS Integration:** `rxMethod` integrates RxJS streams. Use `rxMethod` for all store methods that interact with Observable-based APIs or services. Avoid using async/await with Observables in store methods. ```typescript // Signal store method patterns import { signalStore, withState, withMethods, patchState } from "@ngrx/signals"; import { inject } from "@angular/core"; import { TodoService } from "./todo.service"; import { Todo } from "./todo.model"; export interface TodoState { todos: Todo[]; loading: boolean; } export const TodoStore = signalStore( { providedIn: "root" }, withState<TodoState>({ todos: [], loading: false }), withMethods((store, todoService = inject(TodoService)) => ({ addTodo(todo: Todo): void { patchState(store, (state) => ({ todos: [...state.todos, todo], })); }, loadTodosSimple: rxMethod<void>( pipe( switchMap(() => { patchState(store, { loading: true }); return todoService.getTodos().pipe( tapResponse({ next: (todos) => patchState(store, { todos, loading: false }), error: () => patchState(store, { loading: false }), }), ); }), ), ), })), ); ``` ## 4. Entity Management - **Entity Configuration:** Entity configurations include ID selectors - **Collection Operations:** Entity operations handle CRUD operations - **Entity Relationships:** Computed properties manage entity relationships - **Entity Updates:** Prefer atomic entity operations (`addEntity`, `updateEntity`, `removeEntity`, `setAllEntities`) over bulk state updates. Use `entityConfig` and `selectId` for entity identification. ```typescript // Entity management patterns const userEntityConfig = entityConfig({ entity: type<User>(), collection: "users", selectId: (user: User) => user.id, }); export const UserStore = signalStore( withEntities(userEntityConfig), withMethods((store) => ({ addUser: signalMethod<User>((user) => { patchState(store, addEntity(user, userEntityConfig)); }), updateUser: signalMethod<{ id: string; changes: Partial<User> }>( ({ id, changes }) => { patchState(store, updateEntity({ id, changes }, userEntityConfig)); }, ), removeUser: signalMethod<string>((id) => { patchState(store, removeEntity(id, userEntityConfig)); }), setUsers: signalMethod<User[]>((users) => { patchState(store, setAllEntities(users, userEntityConfig)); }), })), ); ``` ## 5. Component Integration ### Component State Access - **Signal Properties:** Components access signals directly in templates - **OnPush Strategy:** Signal-based components use OnPush change detection - **Store Injection:** Components inject store services with the `inject` function - **Default Values:** Signals have default values - **Computed Values:** Components derive computed values from signals - **Signal Effects:** Component effects handle side effects ```typescript // Component integration patterns @Component({ standalone: true, imports: [UserListComponent], template: ` @if (userStore.users().length > 0) { <app-user-list [users]="userStore.users()"></app-user-list> } @else { <p>No users loaded yet.</p> } <div>Selected user: {{ selectedUserName() }}</div> `, changeDetection: ChangeDetectionStrategy.OnPush, }) export class UsersContainerComponent implements OnInit { readonly userStore = inject(UserStore); selectedUserName = computed(() => { const user = this.userStore.selectedUser(); return user ? user.name : "None"; }); constructor() { effect(() => { const userId = this.userStore.selectedUserId(); if (userId) { console.log(`User selected: ${userId}`); } }); } ngOnInit() { this.userStore.loadUsers(); } } ``` ### Signal Store Hooks - **Lifecycle Hooks:** The `withHooks` feature adds lifecycle hooks to stores - **Initialization:** The `onInit` hook initializes stores - **Cleanup:** The `onDestroy` hook cleans up resources - **State Synchronization:** Hooks synchronize state between stores ```typescript // Signal store hooks patterns export const UserStore = signalStore( withState<UserState>({ /* initial state */ }), withMethods(/* store methods */), withHooks({ onInit: (store) => { // Initialize the store store.loadUsers(); // Return cleanup function if needed return () => { // Cleanup code }; }, }), ); ``` ## 6. Advanced Signal Patterns ### Signal Store Features - **Feature Creation:** The `signalStoreFeature` function creates reusable features - **Generic Feature Types:** Generic type parameters enhance feature reusability ```typescript function withMyFeature<T>(config: Config<T>) { return signalStoreFeature(/*...*/); } ``` - **Feature Composition:** Multiple features compose together - **Cross-Cutting Concerns:** Features handle logging, undo/redo, and other concerns - **State Slices:** Features define and manage specific state slices ```typescript // Signal store feature patterns export function withUserFeature() { return signalStoreFeature( withState<UserFeatureState>({ /* feature state */ }), withComputed((state) => ({ /* computed properties */ })), withMethods((store) => ({ /* methods */ })), ); } // Using the feature export const AppStore = signalStore( withUserFeature(), withOtherFeature(), withMethods((store) => ({ /* app-level methods */ })), ); ``` ### Signals and RxJS Integration - **Signal Conversion:** `toSignal()` and `toObservable()` convert between Signals and Observables - **Effects:** Angular's `effect()` function reacts to signal changes - **RxJS Method:** `rxMethod<T>(pipeline)` handles Observable-based side effects. Always prefer `rxMethod` for Observable-based service calls in stores. Do not convert Observables to Promises for store logic. - Accepts input values, Observables, or Signals - Manages subscription lifecycle automatically - **Reactive Patterns:** Signals combine with RxJS for complex asynchronous operations ```typescript // Signal and RxJS integration patterns import { signalStore, withState, withMethods, patchState } from "@ngrx/signals"; import { rxMethod } from "@ngrx/signals/rxjs-interop"; import { tapResponse } from "@ngrx/operators"; import { pipe, switchMap } from "rxjs"; import { inject } from "@angular/core"; import { HttpClient } from "@angular/common/http"; import { User } from "./user.model"; export interface UserState { users: User[]; loading: boolean; error: string | null; } export const UserStore = signalStore( { providedIn: "root" }, withState({ users: [], loading: false, error: null }), withMethods((store, http = inject(HttpClient)) => ({ loadUsers: rxMethod<void>( pipe( switchMap(() => { patchState(store, { loading: true, error: null }); return http.get<User[]>("/api/users").pipe( tapResponse({ next: (users) => patchState(store, { users, loading: false }), error: () => patchState(store, { loading: false, error: "Failed to load users", }), }), ); }), ), ), })), ); ``` ### Signal Method for Side Effects The `signalMethod` function manages side effects driven by Angular Signals within Signal Store: - **Input Flexibility:** The processor function accepts static values or Signals - **Automatic Cleanup:** The underlying effect cleans up when the store is destroyed - **Explicit Tracking:** Only the input signal passed to the processor function is tracked - **Lightweight:** Smaller bundle size compared to `rxMethod` ```typescript // Signal method patterns import { signalStore, withState, withMethods, patchState } from '@ngrx/signals'; import { signalMethod } from '@ngrx/signals'; import { inject } from '@angular/core'; import { Logger } from './logger'; interface UserPreferencesState { theme: 'light' | 'dark'; sendNotifications: boolean; const initialState: UserPreferencesState = { theme: 'light', sendNotifications: true, }; export const PreferencesStore = signalStore( { providedIn: 'root' }, withState(initialState), withProps(() => ({ logger: inject(Logger), })); withMethods((store) => ({ setSendNotifications(enabled: boolean): void { patchState(store, { sendNotifications: enabled }); }, // Signal method reacts to theme changes logThemeChange: signalMethod<'light' | 'dark'>((theme) => { store.logger.log(`Theme changed to: ${theme}`); }), setTheme(newTheme: 'light' | 'dark'): void { patchState(store, { theme: newTheme }); }, })), ); ``` ## 7. Custom Store Properties - **Custom Properties:** The `withProps` feature adds static properties, observables, and dependencies - **Observable Exposure:** `toObservable` within `withProps` exposes state as observables ```typescript withProps(({ isLoading }) => ({ isLoading$: toObservable(isLoading), })); ``` - **Dependency Grouping:** `withProps` groups dependencies for use across store features ```typescript withProps(() => ({ booksService: inject(BooksService), logger: inject(Logger), })); ``` ## 8. Project Organization ### Store Organization - **File Location:** Store definitions (`*.store.ts`) exist in dedicated files - **Naming Convention:** Stores follow the naming pattern `FeatureNameStore` - **Model Co-location:** State interfaces and models exist near store definitions - **Provider Functions:** Provider functions (`provideFeatureNameStore()`) encapsulate store providers ```typescript // Provider function pattern import { Provider } from "@angular/core"; import { UserStore } from "./user.store"; export function provideUserSignalStore(): Provider { return UserStore; } ``` ### Store Hierarchy - **Parent-Child Relationships:** Stores have clear relationships - **State Sharing:** Related components share state - **State Ownership:** Each state slice has a clear owner - **Store Composition:** Complex UIs compose multiple stores

# NgRx Signals Testing Guidelines These guidelines outline best practices for testing NgRx Signals Stores in Angular applications. ## 1. General Testing Patterns - **Public API Testing:** Tests interact with stores through their public API - **TestBed Usage:** Angular's `TestBed` instantiates and injects Signal Stores - **Dependency Mocking:** Tests mock store dependencies - **Store Mocking:** Component tests mock stores - **State and Computed Testing:** Tests assert on signal and computed property values - **Method Testing:** Tests trigger methods and assert on resulting state - **Protected State Access:** The `unprotected` utility from `@ngrx/signals/testing` accesses protected state - **Integration Testing:** Tests cover stores and components together - **Custom Extension Testing:** Tests verify custom store features ## 2. Example: Store Testing ```typescript import { TestBed } from "@angular/core/testing"; import { unprotected } from "@ngrx/signals/testing"; describe("CounterStore", () => { it("recomputes doubleCount on count changes", () => { const counterStore = TestBed.inject(CounterStore); patchState(unprotected(counterStore), { count: 10 }); expect(counterStore.doubleCount()).toBe(20); }); }); ``` --- Follow these patterns for all NgRx Signals Store tests. Use Jasmine, Angular’s latest APIs, and strong typing. For more, see the official NgRx Signals documentation.

# Angular Material Theming Guidelines (v3) These guidelines define how to implement, structure, and maintain themes using Angular Material v3 in this project. They are based on the official [Angular Material Theming Guide](https://material.angular.io/guide/theming) and tailored for consistency, scalability, and maintainability. --- ## 1. Theme Structure & Organization - **Central Theme File:** - Define all theme configuration in a single SCSS file (e.g., `src/theme/_theme-colors.scss`). - Import this file in `src/styles.scss`. - **No Inline Styles:** - Do not use inline styles or hardcoded colors in components. Always use theme variables. - **Feature-Level Theming:** - For feature-specific overrides, create a dedicated SCSS partial (e.g., `feature/_feature-theme.scss`) and import it in the main theme file. ## 2. Color System - **Material Color Palettes:** - Use Material color palettes (`mat-palette`) for primary, accent, and warn colors. - Define palettes for both light and dark themes. - **Custom Colors:** - Define custom palettes using `mat-palette` and reference them via theme variables. - **Surface & Background:** - Use Material surface and background tokens for backgrounds, cards, and containers. ## 3. Theme Definition & Application - **Create Themes:** - Use `mat-light-theme` and `mat-dark-theme` to define light and dark themes. - Example: ```scss $my-primary: mat-palette($mat-indigo); $my-accent: mat-palette($mat-pink, A200, A100, A400); $my-warn: mat-palette($mat-red); $my-theme: mat-light-theme( ( color: ( primary: $my-primary, accent: $my-accent, warn: $my-warn, ), ) ); ``` - **Apply Themes Globally:** - Use `@include angular-material-theme($my-theme);` in your global styles. - **Dark Mode:** - Define a dark theme and apply it using a CSS class (e.g., `.dark-theme`). - Example: ```scss .dark-theme { @include angular-material-theme($my-dark-theme); } ``` - Toggle dark mode by adding/removing the class on the root element. ## 4. Typography - **Material Typography Config:** - Use `mat-typography-config` to define custom typography. - Apply with `@include angular-material-typography($my-typography);`. - **Consistent Font Usage:** - Use theme typography variables in all components. ## 5. Component Theming - **Theming Mixins:** - Use Angular Material theming mixins for custom components. - Example: ```scss @use "@angular/material" as mat; @include mat.button-theme($my-theme); ``` - **Custom Component Themes:** - For custom components, define and use your own theming mixins that accept a theme config. ## 6. SCSS Usage & Best Practices - **@use Syntax:** - Use the `@use` rule for all Angular Material imports (not `@import`). - **No Direct Color Usage:** - Never use raw color values. Always use theme variables or palette functions. - **Variables Naming:** - Name theme variables descriptively (e.g., `$app-primary`, `$app-accent`). - **No !important:** - Avoid `!important` in theme styles. ## 7. Do's and Don'ts **Do:** - Centralize all theming logic in SCSS theme files - Use Material mixins and tokens for all component theming - Support both light and dark themes - Use CSS classes to toggle themes - Document custom palettes and typography in the theme file **Don't:** - Hardcode colors or typography in components - Use inline styles for theming - Use legacy `@import` for Material SCSS - Mix multiple theme definitions in a single file ## 8. Integration & Maintenance - **Import Order:** - Always import theme files before component styles in `styles.scss`. - **Upgrades:** - Review the [Angular Material changelog](https://github.com/angular/components/blob/main/CHANGELOG.md) for theming changes on upgrades. - **Documentation:** - Document all customizations and overrides in the theme file. --- For more details, see the [official Angular Material Theming Guide](https://material.angular.io/guide/theming).

# Core Architecture Standards for Angular This document outlines the core architectural standards for Angular applications. It provides guidelines for project structure, fundamental patterns, and organization principles to ensure maintainability, scalability, and performance. ## 1. Project Structure and Organization ### 1.1. Feature-Based Modules **Standard:** Organize the application into feature-based modules. Each module encapsulates a specific feature or business capability. **Do This:** Create a directory for each feature module under the "src/app" directory. **Don't Do This:** Avoiding creating a monolithic "app.module.ts" containing all components, services, and dependencies. **Why:** Feature-based modules promote modularity, improve separation of concerns, and enable lazy loading, resulting in faster initial load times and improved maintainability. **Example:** """ src/ app/ auth/ // Authentication feature module auth.module.ts auth-routing.module.ts components/ login/ login.component.ts login.component.html register/ register.component.ts register.component.html services/ auth.service.ts dashboard/ // Dashboard feature module dashboard.module.ts dashboard-routing.module.ts components/ overview/ overview.component.ts overview.component.html shared/ // Shared module for reusable components, services, and pipes shared.module.ts components/ data-table/ data-table.component.ts data-table.component.html services/ data.service.ts app.component.ts app.module.ts app-routing.module.ts """ ### 1.2. Core Module **Standard:** Create a "core" module for application-wide services and singleton components. **Do This:** Place services that need to be instantiated only once (e.g., authentication service, configuration service) and singleton components (e.g., "AppComponent") in the "core" module. Import the "core" module only into the "AppModule". **Don't Do This:** Import "core" module into other feature modules. This can lead to multiple instances of singleton services. **Why:** The "core" module ensures that certain services and components are instantiated only once and provides a clear separation of concerns. **Example:** """ src/ app/ core/ core.module.ts services/ auth.service.ts config.service.ts app.module.ts """ """typescript // core.module.ts import { NgModule, Optional, SkipSelf } from '@angular/core'; import { AuthService } from './services/auth.service'; import { CommonModule } from '@angular/common'; import { ConfigService } from './services/config.service'; @NgModule({ imports: [CommonModule], providers: [AuthService, ConfigService], }) export class CoreModule { constructor(@Optional() @SkipSelf() parentModule: CoreModule) { if (parentModule) { throw new Error('CoreModule is already loaded. Import it in the AppModule only.'); } } } """ """typescript // app.module.ts import { NgModule } from '@angular/core'; import { BrowserModule } from '@angular/platform-browser'; import { CoreModule } from './core/core.module'; import { AppComponent } from './app.component'; @NgModule({ declarations: [AppComponent], imports: [BrowserModule, CoreModule], bootstrap: [AppComponent], }) export class AppModule {} """ ### 1.3. Shared Module **Standard**: Create a "shared" module for reusable components, directives, and pipes. **Do This**: Place components, directives, pipes, and modules that reused across multiple feature modules in "shared" module. Export all symbols that should be accessible from other modules. **Don't Do This**: Import feature-specific services into "shared" module. Place components that are only used by one feature module in "shared" module. **Why:** The "shared" module promotes code reuse and consistency across the application. **Example:** """ src/ app/ shared/ shared.module.ts components/ data-table/ data-table.component.ts data-table.component.html directives/ highlight.directive.ts pipes/ truncate.pipe.ts """ """typescript // shared.module.ts import { NgModule } from '@angular/core'; import { CommonModule } from '@angular/common'; import { DataTableComponent } from './components/data-table/data-table.component'; import { HighlightDirective } from './directives/highlight.directive'; import { TruncatePipe } from './pipes/truncate.pipe'; @NgModule({ declarations: [DataTableComponent, HighlightDirective, TruncatePipe], imports: [CommonModule], exports: [DataTableComponent, HighlightDirective, TruncatePipe, CommonModule], // Export CommonModule for *ngIf, *ngFor etc. }) export class SharedModule {} """ ### 1.4. Lazy Loading Modules **Standard:** Use lazy loading for feature modules to improve initial load time. **Do This:** Configure routes for feature modules to be loaded lazily using "loadChildren". **Don't Do This:** Load all modules eagerly, which can significantly increase the initial load time of the application. **Why:** Lazy loading reduces the initial bundle size by loading modules on demand, improving the user experience. **Example:** """typescript // app-routing.module.ts import { NgModule } from '@angular/core'; import { RouterModule, Routes } from '@angular/router'; const routes: Routes = [ { path: 'auth', loadChildren: () => import('./auth/auth.module').then((m) => m.AuthModule), }, { path: 'dashboard', loadChildren: () => import('./dashboard/dashboard.module').then((m) => m.DashboardModule), }, { path: '', redirectTo: 'dashboard', pathMatch: 'full', }, ]; @NgModule({ imports: [RouterModule.forRoot(routes)], exports: [RouterModule], }) export class AppRoutingModule {} """ ### 1.5. Folder Structure Conventions **Standard:** Follow consistent folder structure conventions within each module. **Do This:** Create subfolders for components, services, models, and pipes within each module. **Don't Do This:** Mix file types in a single folder, which reduces readability and maintainability. **Example:** """ src/ app/ auth/ components/ login/ login.component.ts login.component.html login.component.scss register/ register.component.ts register.component.html register.component.scss services/ auth.service.ts models/ user.model.ts auth.module.ts auth-routing.module.ts """ ### 1.6. Naming Conventions **Standard:** Use consistent naming conventions for files and classes. **Do This:** * Components: "ComponentNameComponent" (e.g., "LoginComponent") * Services: "ServiceNameService" (e.g., "AuthService") * Modules: "ModuleNameModule" (e.g., "AuthModule") * Models: "ModelNameModel" (e.g., "UserModel") * Files: "component-name.component.ts", "service-name.service.ts", "module-name.module.ts", "model-name.model.ts" **Don't Do This:** Use inconsistent or ambiguous names, which makes it harder to understand the purpose of the file or class. **Why:** Consistent naming conventions improve code readability and make it easier to locate files and classes. For example, VS Code and other IDEs provide suggestions based on these patterns. ## 2. Architectural Patterns ### 2.1. Smart vs. Dumb Components **Standard:** Distinguish between smart (container) and dumb (presentational) components. **Do This:** Smart components should handle data fetching, state management, and business logic. Dumb components should focus on rendering data and emitting events. Use "@Input()" and "@Output()" to pass data between them. **Don't Do This:** Performing data fetching or complex business logic inside dumb components. This tightly couples the component to specific data sources, making it less reusable. **Why:** This pattern promotes reusability, testability, and separation of concerns. Smart components act as orchestrators while dumb components are reusable views. **Example:** """typescript // Smart component (e.g., UserListComponent) import { Component, OnInit } from '@angular/core'; import { UserService } from '../user.service'; import { User } from '../user.model'; @Component({ selector: 'app-user-list', templateUrl: './user-list.component.html', styleUrls: ['./user-list.component.scss'], }) export class UserListComponent implements OnInit { users: User[] = []; constructor(private userService: UserService) {} ngOnInit(): void { this.userService.getUsers().subscribe((users) => { this.users = users; }); } onDelete(userId: number): void { this.userService.deleteUser(userId).subscribe(() => { this.users = this.users.filter((user) => user.id !== userId); }); } } """ """html <!-- Dumb component (e.g., UserItemComponent) --> <div class="user-item"> <span>{{ user.name }}</span> <button (click)="delete.emit(user.id)">Delete</button> </div> """ """typescript // Dumb component (e.g., UserItemComponent) import { Component, Input, Output, EventEmitter } from '@angular/core'; import { User } from '../user.model'; @Component({ selector: 'app-user-item', templateUrl: './user-item.component.html', styleUrls: ['./user-item.component.scss'], }) export class UserItemComponent { @Input() user!: User; @Output() delete = new EventEmitter<number>(); } """ ### 2.2. Services for Business Logic **Standard:** Encapsulate business logic in services. **Do This:** Create services to handle data fetching, data manipulation, and complex calculations. Inject these services into components that need to access the business logic. **Don't Do This:** Placing business logic directly in components. This makes components harder to test and reduces reusability. **Why:** Services promote code reusability, testability, and separation of concerns. They also make it easier to manage and maintain the application's business logic. **Example:** """typescript // user.service.ts import { Injectable } from '@angular/core'; import { HttpClient } from '@angular/common/http'; import { Observable } from 'rxjs'; import { User } from './user.model'; @Injectable({ providedIn: 'root', }) export class UserService { private apiUrl = '/api/users'; constructor(private http: HttpClient) {} getUsers(): Observable<User[]> { return this.http.get<User[]>(this.apiUrl); } deleteUser(userId: number): Observable<void> { return this.http.delete<void>("${this.apiUrl}/${userId}"); } } """ ### 2.3. State Management **Standard:** Choose an appropriate state management solution based on application complexity. **Do This:** For simple applications, use "@Input()" and "@Output()" (as detailed above). For complex applications, consider using NgRx, Akita, or a similar state management library. Alternatively, consider a service-based state management approach for less complex applications. **Don't Do This:** Directly modifying the state in multiple components, leading to unpredictable behavior and difficulties in debugging. **Why:** A state management solution provides a predictable way to manage application state, making it easier to reason about and debug the application. **Example (Service-based state management):** """typescript //Simple example for smaller projects. // counter.service.ts import { Injectable } from '@angular/core'; import { BehaviorSubject } from 'rxjs'; @Injectable({ providedIn: 'root' }) export class CounterService { private counter = new BehaviorSubject<number>(0); public counter$ = this.counter.asObservable(); increment() { this.counter.next(this.counter.value + 1); } decrement() { this.counter.next(this.counter.value - 1); } } """ ### 2.4. Interceptors **Standard:** Use interceptors to handle cross-cutting concerns such as authentication, logging, and error handling. **Do This:** Create interceptors to add headers, log requests, and handle errors globally. Register the interceptors in the "AppModule". **Don't Do This:** Implementing these concerns directly in each service method, leading to code duplication and maintenance issues. **Why:** Interceptors provide a centralized way to handle cross-cutting concerns, reducing code duplication and improving maintainability. **Example:** """typescript // auth.interceptor.ts import { Injectable } from '@angular/core'; import { HttpInterceptor, HttpRequest, HttpHandler, HttpEvent } from '@angular/common/http'; import { Observable } from 'rxjs'; import { AuthService } from './auth.service'; @Injectable() export class AuthInterceptor implements HttpInterceptor { constructor(private authService: AuthService) {} intercept(request: HttpRequest<any>, next: HttpHandler): Observable<HttpEvent<any>> { const token = this.authService.getToken(); if (token) { const authRequest = request.clone({ setHeaders: { Authorization: "Bearer ${token}", }, }); return next.handle(authRequest); } return next.handle(request); } } """ """typescript // app.module.ts import { NgModule } from '@angular/core'; import { BrowserModule } from '@angular/platform-browser'; import { HttpClientModule, HTTP_INTERCEPTORS } from '@angular/common/http'; import { AuthInterceptor } from './auth.interceptor'; import { AppComponent } from './app.component'; @NgModule({ declarations: [AppComponent], imports: [BrowserModule, HttpClientModule], providers: [ { provide: HTTP_INTERCEPTORS, useClass: AuthInterceptor, multi: true, }, ], bootstrap: [AppComponent], }) export class AppModule {} """ ### 2.5. Reactive Programming with RxJS **Standard:** Embrace reactive programming using RxJS for handling asynchronous operations. **Do This:** Use RxJS operators to transform, filter, and combine streams of data. Leverage the "async" pipe in templates for automatic subscription management. **Don't Do This:** Subscribing to observables directly in components without properly unsubscribing, leading to memory leaks. **Why:** RxJS provides a powerful way to handle asynchronous operations and data streams, improving the responsiveness and maintainability of the application. **Example:** """typescript // user.service.ts import { Injectable } from '@angular/core'; import { HttpClient } from '@angular/common/http'; import { Observable } from 'rxjs'; import { map } from 'rxjs/operators'; import { User } from './user.model'; @Injectable({ providedIn: 'root', }) export class UserService { private apiUrl = '/api/users'; constructor(private http: HttpClient) {} getUsers(): Observable<User[]> { return this.http.get<User[]>(this.apiUrl).pipe( map((users) => { return users.map((user) => ({ ...user, name: user.name.toUpperCase(), })); }) ); } } """ """html <!-- user-list.component.html --> <ul> <li *ngFor="let user of users$ | async">{{ user.name }}</li> </ul> """ """typescript // user-list.component.ts import { Component, OnInit } from '@angular/core'; import { UserService } from '../user.service'; import { Observable } from 'rxjs'; import { User } from '../user.model'; @Component({ selector: 'app-user-list', templateUrl: './user-list.component.html', styleUrls: ['./user-list.component.scss'], }) export class UserListComponent implements OnInit { users$!: Observable<User[]>; constructor(private userService: UserService) {} ngOnInit(): void { this.users$ = this.userService.getUsers(); } } """ ### 2.6. Dependency Injection **Standard:** Use Angular's dependency injection (DI) system to manage dependencies. **Do This:** Inject services and other dependencies into components, directives, and other services using the constructor. **Don't Do This:** Creating instances of service classes directly using the "new" keyword, avoiding the benefits of DI like testability and configuration. **Why:** DI promotes loose coupling, testability, and reusability. It also simplifies the management of dependencies. **Example:** """typescript // login.component.ts import { Component } from '@angular/core'; import { AuthService } from '../auth.service'; @Component({ selector: 'app-login', templateUrl: './login.component.html', styleUrls: ['./login.component.scss'], }) export class LoginComponent { constructor(private authService: AuthService) {} login(): void { this.authService.login('username', 'password'); } } """ ## 3. Error Handling ### 3.1. Centralized Error Handling **Standard:** Implement centralized error handling using interceptors or a global error handler. **Do This:** Create an error handler service that logs errors and displays user-friendly messages. Use interceptors to catch HTTP errors and forward them to the error handler. Consider using "ErrorHandler" for uncaught exceptions. **Don't Do This:** Handling errors directly in each component or service method, leads to error-handling logic scattered throughout the application, making it difficult to maintain. **Why:** Centralized error handling improves the user experience and simplifies error logging and debugging. **Example:** """typescript // error.interceptor.ts import { Injectable } from '@angular/core'; import { HttpInterceptor, HttpRequest, HttpHandler, HttpEvent, HttpErrorResponse } from '@angular/common/http'; import { Observable, throwError } from 'rxjs'; import { catchError } from 'rxjs/operators'; import { ErrorHandlerService } from './error-handler.service'; @Injectable() export class ErrorInterceptor implements HttpInterceptor { constructor(private errorHandlerService: ErrorHandlerService) {} intercept(request: HttpRequest<any>, next: HttpHandler): Observable<HttpEvent<any>> { return next.handle(request).pipe( catchError((error: HttpErrorResponse) => { this.errorHandlerService.handleError(error); return throwError(error); }) ); } } """ """typescript // error-handler.service.ts import { Injectable } from '@angular/core'; @Injectable({ providedIn: 'root', }) export class ErrorHandlerService { handleError(error: any): void { console.error('An error occurred:', error); // Display a user-friendly message alert('An error occurred. Please try again later.'); } } """ ## 4. Code Reusability ### 4.1. Custom Components **Standard:** Create custom components for reusable UI elements. **Do This:** Create components for common UI patterns like data tables, forms, and dialogs. Make these components configurable using "@Input()" and "@Output()". **Don't Do This:** Duplicating UI code across multiple components, making it harder to maintain consistency and introduce changes. **Why:** Custom components promote code reuse and improve the consistency of the user interface. **Example:** (See "shared.module.ts" example above.) ## 5. Security ### 5.1. Input Validation **Standard:** Validate user inputs on both the client and server sides. **Do This:** Use Angular's reactive forms to validate user inputs. Also, implement server-side validation to prevent malicious data from being stored in the database. **Don't Do This:** Relying solely on client-side validation, as it can be bypassed by malicious users. **Why:** Input validation protects the application from security vulnerabilities such as cross-site scripting (XSS) and SQL injection. ### 5.2. Authentication and Authorization **Standard:** Implement secure authentication and authorization mechanisms. **Do This:** Use JSON Web Tokens (JWT) for authentication. Implement role-based access control (RBAC) to authorize users based on their roles. **Don't Do This:** Storing sensitive information in local storage or cookies without proper encryption, because this exposes the application to security risks. **Why:** Secure authentication and authorization protect the application from unauthorized access and data breaches. ## 6. Performance Optimization ### 6.1. Change Detection **Standard:** Optimize change detection using "OnPush" strategy. **Do This:** Use "ChangeDetectionStrategy.OnPush" for components that only depend on their inputs. This reduces the number of change detection cycles and improves performance. **Don't Do This:** Relying solely on the default change detection strategy ("Default"), especially for complex components with many bindings, leading to performance issues. **Why:** "OnPush" change detection improves performance by only checking for changes when the input references change. """typescript import { Component, Input, ChangeDetectionStrategy } from '@angular/core'; @Component({ selector: 'app-user-profile', templateUrl: './user-profile.component.html', styleUrls: ['./user-profile.component.scss'], changeDetection: ChangeDetectionStrategy.OnPush, }) export class UserProfileComponent { @Input() user!: User; } """ ### 6.2. TrackBy Function **Standard:** Use "trackBy" function with "*ngFor" to improve performance when rendering lists. **Do This:** Provide a "trackBy" function that returns a unique identifier for each item in the list. This prevents Angular from re-rendering the entire list when only a few items have changed. **Don't Do This:** Omitting "trackBy" for large lists, potentially causing performance issues due to unnecessary DOM updates. **Why:** "trackBy" improves performance by only re-rendering items that have actually changed. """html <ul> <li *ngFor="let item of items; trackBy: trackByFn">{{ item.name }}</li> </ul> """ """typescript trackByFn(index: number, item: any): any { return item.id; } """ ### 6.3. Ahead-of-Time (AOT) Compilation **Standard:** Use AOT compilation to improve application startup time. **Do This:** Enable AOT compilation in the "angular.json" file. **Don't Do This:** Relying solely on Just-in-Time (JIT) compilation (mostly for development), resulting in slower startup times for production deployments. **Why:** AOT compilation compiles the application during the build process, resulting in smaller bundle sizes and faster startup times. ### 6.4 Imagemin and lazy loading **Standard**: Configure your image assets using "imagemin" when using the CLI to ensure all images are properly compressed. **Standard**: Be sure to lazy load all images. **Why**: Properly configured media assets ensure delivery of applications with the smallest footprint and allow users to stream in images as the images come into proper view.