Cline

Add as custom prompt to Roocode you can completely replace the system prompt for this mode (aside from the role definition and custom instructions) by creating a file at .roo/system-prompt-codershortrules in your workspace. You are Roo, a highly skilled software engineer with extensive knowledge in many programming languages, frameworks, design patterns, and best practices. Use tools one at a time to complete tasks step-by-step. Wait for user confirmation after each tool use. Tools read_file: Read file contents. Use for analyzing code, text files, or configs. Output includes line numbers. Extracts text from PDFs and DOCX. Not for other binary files. Parameters: path (required) search_files: Search files in a directory using regex. Shows matches with context. Useful for finding code patterns or specific content. Parameters: path (required), regex (required), file_pattern (optional) list_files: List files and directories. Can be recursive. Don’t use to check if files you created exist; user will confirm. Parameters: path (required), recursive (optional) list_code_definition_names: List top-level code definitions (classes, functions, etc.) in a directory. Helps understand codebase structure. Parameters: path (required) apply_diff: Replace code in a file using a search and replace block. Must match existing content exactly. Use read_file first if unsure. Parameters: path (required), diff (required), start_line (required), end_line (required) Diff Format: text Wrap Copy <<<<<<< SEARCH [exact content] ======= [new content] >>>>>>> REPLACE write_to_file: Write full content to a file. Overwrites if exists, creates if not. MUST provide COMPLETE file content, not partial updates. MUST include app 3 parameters, path, content, and line_count Parameters: path (required), content (required), line_count (required) execute_command: Run CLI commands. Explain what the command does. Prefer complex commands over scripts. Commands run in the current directory. To run in a different directory, use cd path && command. Parameters: command (required) ask_followup_question: Ask the user a question to get more information. Use when you need clarification or details. Parameters: question (required) attempt_completion: Present the task result to the user. Optionally provide a CLI command to demo the result. Don’t use it until previous tool uses are confirmed successful. Parameters: result (required), command (optional) Tool Use Formatting IMPORTANT REPLACE tool_name with the tool you want to use, for example read_file. IMPORTANT REPLACE parameter_name with the parameter name, for example path. Format tool use with XML tags, e.g.: text Wrap Copy value1 value2 Guidelines Choose the right tool for the task. Use one tool at a time. Format tool use correctly. Wait for user confirmation after each tool use. Don’t assume tool success; wait for user feedback. Rules pass correct paths to tools. Don’t use ~ or $HOME. Tailor commands to the user's system. Prefer other editing tools over write_to_file for changes. Provide complete file content when using write_to_file. Don’t ask unnecessary questions; use tools to get information. Don’t be conversational; be direct and technical. Consider environment_details for context. ALWAYS replace tool_name, parameter_name, and parameter_value with actual values. Objective Break task into steps. Use tools to accomplish each step. Wait for user confirmation after each tool use. Use attempt_completion when task is complete.

# 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

# State Management Standards for Clean Code This document outlines coding standards for state management within Clean Code principles. It provides specific guidelines and examples to ensure code related to state is maintainable, readable, performant, and secure. These standards are designed to work with the latest recommended practices and features within the Clean Code ecosystem. ## 1. Principles of Clean State Management Clean state management is about structuring your application's data in a way that's predictable, manageable, and testable. It involves making state changes explicit, limiting side effects, and ensuring data consistency. Applying clean code principles to state enhances maintainability, reduces bugs, and improves collaborative development. * **Single Source of Truth:** Ensure each piece of data has one authoritative source. This prevents inconsistencies and simplifies debugging. * **Immutability:** Favor immutable data structures. Immutable data makes state changes more predictable and helps prevent unintended side effects. * **Explicit State Transitions:** State transitions should be clear and well-defined, making it easier to understand how the application evolves over time. * **Separation of Concerns:** Keep state management logic separate from UI components or business logic. This enhances modularity and testability. * **Minimal Global State:** Limit the use of global state. Widespread global state can make it difficult to track dependencies and lead to unexpected behavior. ## 2. Architectural Patterns for State Management Choosing the right architecture for state management depends on the complexity of the application. Here are a few common patterns and guidelines: ### 2.1 Local State Managing state within a single component should be a default option. You typically use local state for isolated functionalities that don't necessitate sharing state or reactivity beyond the component’s scope. * **Do This:** Use local state for isolated component features. * **Don't Do This:** Share local state directly between unrelated components. """javascript // Example React local state using useState import React, { useState } from 'react'; function Counter() { const [count, setCount] = useState(0); return ( <div> <p>Count: {count}</p> <button onClick={() => setCount(count + 1)}>Increment</button> </div> ); } """ ### 2.2 Redux Pattern (Centralized State) The Redux pattern emphasizes a single store for application state, using reducers to handle actions and state transitions immutably. * **Do This:** * Use Redux or similar libraries for complex, application-wide state. * Define actions as plain objects with a "type" field. * Use pure functions as reducers to ensure predictable state transitions. * Selectors should cache results to prevent unnecessary re-renders. * **Don't Do This:** * Mutate the state directly in reducers. * Perform asynchronous operations directly in reducers. * Overuse Redux for simple components with minimal state. """javascript // Example Redux setup // Action const INCREMENT = 'INCREMENT'; const DECREMENT = 'DECREMENT'; const increment = () => ({ type: INCREMENT }); const decrement = () => ({ type: DECREMENT }); // Reducer const initialState = { count: 0 }; const counterReducer = (state = initialState, action) => { switch (action.type) { case INCREMENT: return { ...state, count: state.count + 1 }; case DECREMENT: return { ...state, count: state.count - 1 }; default: return state; } }; // Store creation import { createStore } from 'redux'; const store = createStore(counterReducer); // Component integration (React example) import { useSelector, useDispatch } from 'react-redux'; function CounterComponent() { const count = useSelector(state => state.count); const dispatch = useDispatch(); return ( <div> <p>Count: {count}</p> <button onClick={() => dispatch(increment())}>Increment</button> <button onClick={() => dispatch(decrement())}>Decrement</button> </div> ); } """ ### 2.3 Context API (Scoped State) Context API provides a way to pass data through the component tree without having to pass props manually at every level. While it is simpler than Redux it is still intended for scenarios that benefit from shared state. * **Do This:** * Use Context API for theming, user authentication, or other application-wide configurations. * Use "useContext" hook to consume context values. * Combine Context API with "useReducer" for complex state logic. * **Don't Do This:** * Use Context API as a general replacement for prop drilling in scenarios where component composition is better suited. * Overuse Context API resulting in unnecessary re-renders. """javascript // Example Context API setup import React, { createContext, useContext, useState } from 'react'; // Create Context const ThemeContext = createContext(); // Context Provider function ThemeProvider({ children }) { const [theme, setTheme] = useState('light'); const toggleTheme = () => { setTheme(prevTheme => (prevTheme === 'light' ? 'dark' : 'light')); }; return ( <ThemeContext.Provider value={{ theme, toggleTheme }}> {children} </ThemeContext.Provider> ); } // Custom Hook to consume Context function useTheme() { return useContext(ThemeContext); } // Component using Context function ThemeToggler() { const { theme, toggleTheme } = useTheme(); return ( <button onClick={toggleTheme}> Toggle Theme (Current: {theme}) </button> ); } // Usage in App function App() { return ( <ThemeProvider> <div> <ThemeToggler /> </div> </ThemeProvider> ); } """ ### 2.4 Observable Pattern (Reactive State) The observable pattern, often implemented with libraries like RxJS, is used for handling asynchronous data streams and complex event-driven applications. * **Do This:** * Use RxJS or similar libraries for handling asynchronous data streams. * Structure application logic as a pipeline of observable transformations. * Use subjects to bridge different parts of the application. * **Don't Do This:** * Overuse RxJS for simple event handling. * Introduce memory leaks by not unsubscribing from observables. * Create overly complex observable chains that are hard to understand. """javascript // Example RxJS setup import { fromEvent, interval } from 'rxjs'; import { map, filter, scan, takeUntil } from 'rxjs/operators'; // Example: Click counter observable const button = document.getElementById('myButton'); const click$ = fromEvent(button, 'click'); const counter$ = click$.pipe( map(() => 1), scan((acc, value) => acc + value, 0) ); counter$.subscribe(count => { console.log("Button clicked ${count} times"); }); // Example: Auto-incrementing counter that stops after 5 seconds const interval$ = interval(1000); const stop$ = fromEvent(document.getElementById('stopButton'), 'click'); interval$.pipe( takeUntil(stop$) // Stop the interval when the stop button is clicked ).subscribe(val => console.log("Interval value: ${val}")); """ ### 2.5 State Machines State machines are useful for managing complex state transitions with clearly defined states and transitions. * **Do This:** * Use state machines for scenarios with clearly defined states and transitions. * Model state transitions explicitly, reducing possible unexpected states. * Ensure state machines are well-documented, especially for complex systems. * **Don't Do This:** * Overuse state machines for simple state management. * Create monolithic state machines that are difficult to understand. """javascript // Example: JavaScript state machine using XState import { createMachine, interpret } from 'xstate'; // Define the state machine const trafficLightMachine = createMachine({ id: 'trafficLight', initial: 'green', states: { green: { after: { 5000: 'yellow' // After 5 seconds, transition to yellow } }, yellow: { after: { 1000: 'red' // After 1 second, transition to red } }, red: { after: { 6000: 'green' // After 6 seconds, transition to green } } } }); // Interpret the state machine const trafficService = interpret(trafficLightMachine).start(); trafficService.onTransition(state => { console.log("Traffic light is now ${state.value}"); }); // Example usage (simulating events or external triggers) // trafficService.send('TIMER'); """ ## 3. Implementing Immutability Immutability ensures that once an object is created, its state cannot be changed. This helps prevent accidental state mutations, making it easier to track and manage state changes, which aids in debugging and improves performance in certain scenarios. * **Do This:** * Use immutable data structures and operations. * Make copies of objects or arrays before modifying them. * Employ libraries like Immutable.js for more complex scenarios. * **Don't Do This:** * Directly modify object properties or array elements. * Assume that passing an object or array creates a new copy. ### 3.1 JavaScript Immutability Techniques """javascript // Immutable Object Update const originalObject = { name: 'John', age: 30 }; const updatedObject = { ...originalObject, age: 31 }; // Create a new object // Immutable Array Update const originalArray = [1, 2, 3]; const updatedArray = [...originalArray, 4]; // Create a new array const removedArray = originalArray.filter(item => item !== 2); // Create new array without '2' console.log(originalObject); // { name: 'John', age: 30 } console.log(updatedObject); // { name: 'John', age: 31 } console.log(originalArray); // [1, 2, 3] console.log(updatedArray); // [1, 2, 3, 4] console.log(removedArray); // [1, 3] """ ### 3.2 Immutable.js Immutable.js provides persistent immutable data structures, improving performance and simplifying state management for complex applications. """javascript import { Map, List } from 'immutable'; // Immutable Map const originalMap = Map({ name: 'John', age: 30 }); const updatedMap = originalMap.set('age', 31); // Immutable List const originalList = List([1, 2, 3]); const updatedList = originalList.push(4); console.log(originalMap.toJS()); // { name: 'John', age: 30 } console.log(updatedMap.toJS()); // { name: 'John', age: 31 } console.log(originalList.toJS()); // [1, 2, 3] console.log(updatedList.toJS()); // [1, 2, 3, 4] """ ## 4. Handling Side Effects Side effects are operations that affect the state of the application outside of the current function or component. Properly managing side effects is crucial for maintaining predictable and testable code. * **Do This:** * Isolate side effects in dedicated functions or modules. * Use effect hooks (e.g., "useEffect" in React) to manage side effects in components. * Handle errors gracefully when performing side effects. * **Don't Do This:** * Perform side effects directly within reducers or pure functions. * Ignore potential errors in side effect operations. ### 4.1 Managing Effects with "useEffect" """javascript import React, { useState, useEffect } from 'react'; function DataFetcher({ url }) { const [data, setData] = useState(null); const [loading, setLoading] = useState(true); const [error, setError] = useState(null); useEffect(() => { const fetchData = async () => { try { const response = await fetch(url); if (!response.ok) { throw new Error("HTTP error! status: ${response.status}"); } const result = await response.json(); setData(result); } catch (e) { setError(e); } finally { setLoading(false); } }; fetchData(); // Cleanup function (optional) return () => { // Cancel any pending requests or subscriptions }; }, [url]); // Dependency array: effect runs only when 'url' changes if (loading) return <p>Loading...</p>; if (error) return <p>Error: {error.message}</p>; if (!data) return <p>No data available.</p>; return ( <pre>{JSON.stringify(data, null, 2)}</pre> ); } """ ### 4.2 Using Thunks with Redux Thunks allow you to perform asynchronous operations in Redux actions. """javascript // Example Redux Thunk Action const fetchDataRequest = () => ({ type: 'FETCH_DATA_REQUEST' }); const fetchDataSuccess = (data) => ({ type: 'FETCH_DATA_SUCCESS', payload: data }); const fetchDataFailure = (error) => ({ type: 'FETCH_DATA_FAILURE', payload: error }); // Async action using Redux Thunk const fetchData = (url) => { return async (dispatch) => { dispatch(fetchDataRequest()); try { const response = await fetch(url); if (!response.ok) { throw new Error("HTTP error! status: ${response.status}"); } const data = await response.json(); dispatch(fetchDataSuccess(data)); } catch (error) { dispatch(fetchDataFailure(error.message)); } }; }; // Usage in Component import { useDispatch } from 'react-redux'; function DataFetchButton({ url }) { const dispatch = useDispatch(); return ( <button onClick={() => dispatch(fetchData(url))}> Fetch Data </button> ); } """ ## 5. Testing State Management Testing state management involves verifying that state transitions occur correctly and that side effects are handled properly. * **Do This:** * Write unit tests for reducers to verify state transitions. * Use mock stores and actions to test components connected to Redux. * Test side effects by mocking external dependencies. * **Don't Do This:** * Omit testing for state management logic. * Write integration tests without proper unit testing. ### 5.1 Testing Reducers """javascript // Reducer Test Example (Jest) import counterReducer from './counterReducer'; // Assuming counterReducer.js import { INCREMENT, DECREMENT } from './actions'; describe('counterReducer', () => { it('should return the initial state', () => { expect(counterReducer(undefined, {})).toEqual({ count: 0 }); }); it('should handle INCREMENT', () => { expect(counterReducer({ count: 0 }, { type: INCREMENT })).toEqual({ count: 1 }); }); it('should handle DECREMENT', () => { expect(counterReducer({ count: 1 }, { type: DECREMENT })).toEqual({ count: 0 }); }); }); """ ### 5.2 Testing React Components with Redux """javascript // Component Test Example (React Testing Library and Redux Mock Store) import React from 'react'; import { render, fireEvent } from '@testing-library/react'; import { Provider } from 'react-redux'; import configureStore from 'redux-mock-store'; import CounterComponent from './CounterComponent'; // Assuming CounterComponent.js const mockStore = configureStore([]); describe('CounterComponent', () => { let store; let component; beforeEach(() => { store = mockStore({ count: 0 }); store.dispatch = jest.fn(); // Mock dispatch function component = render( <Provider store={store}> <CounterComponent /> </Provider> ); }); it('should display the initial count', () => { expect(component.getByText('Count: 0')).toBeInTheDocument(); }); it('should dispatch increment action when increment button is clicked', () => { fireEvent.click(component.getByText('Increment')); expect(store.dispatch).toHaveBeenCalledWith({ type: 'INCREMENT' }); }); }); """ ## 6. Security Considerations for State Management Security is a critical aspect of state management. Properly securing the state ensures that sensitive data is protected from unauthorized access and tampering. * **Do This:** * Protect sensitive data in the state with encryption. * Validate data received from external sources before storing it in the state. * Sanitize user input to prevent XSS. * **Don't Do This:** * Store sensitive data in plain text in the state. * Trust data received from external sources without validation. * Expose sensitive data in logs or error messages. ### 6.1 Data Validation """javascript // Example Data Validation const validateData = (data) => { if (typeof data.email !== 'string' || !data.email.includes('@')) { throw new Error('Invalid email format'); } if (typeof data.age !== 'number' || data.age < 0 || data.age > 120) { throw new Error('Invalid age'); } return data; }; // Usage in Reducer const userReducer = (state = {}, action) => { switch (action.type) { case 'UPDATE_USER': try { const validatedData = validateData(action.payload); return { ...state, ...validatedData }; } catch (error) { console.error('Data validation failed:', error.message); return state; } default: return state; } }; """ ### 6.2 Encryption Encrypting sensitive data ensures that even if the state is compromised, the data remains unreadable without the decryption key. """javascript // Example Encryption (using CryptoJS) import CryptoJS from 'crypto-js'; const encryptData = (data, key) => { const encrypted = CryptoJS.AES.encrypt(JSON.stringify(data), key).toString(); return encrypted; }; const decryptData = (encryptedData, key) => { const bytes = CryptoJS.AES.decrypt(encryptedData, key); try { const decrypted = JSON.parse(bytes.toString(CryptoJS.enc.Utf8)); return decrypted; } catch (e) { console.error("Decryption error", e); return null; // Or handle the error as appropriate } }; // Example usage const sensitiveData = { creditCardNumber: '1234-5678-9012-3456' }; const encryptionKey = 'my-secret-key'; const encryptedData = encryptData(sensitiveData, encryptionKey); console.log('Encrypted:', encryptedData); const decryptedData = decryptData(encryptedData, encryptionKey); console.log('Decrypted:', decryptedData); """ ## 7. Optimizing Performance Efficient state management is crucial for optimizing application performance, especially in complex applications with frequent state updates. * **Do This:** * Use memoization techniques to prevent unnecessary re-renders. * Implement lazy loading for components that rely on large state objects. * Batch state updates to minimize the number of renders. * **Don't Do This:** * Update the state unnecessarily. * Cause components to re-render frequently with negligible impact. ### 7.1 Memoization Memoization prevents re-renders by caching the results of expensive calculations or component renders. """javascript import React, { useState, useMemo } from 'react'; function ExpensiveComponent({ data }) { // Simulate an expensive computation const computedValue = useMemo(() => { console.log('Computing expensive value...'); // Complex calculation based on data return data.map(item => item * 2).reduce((acc, val) => acc + val, 0); }, [data]); // Only recompute if 'data' changes return ( <div> <p>Computed Value: {computedValue}</p> </div> ); } function ParentComponent() { const [count, setCount] = useState(0); const data = [1, 2, 3, 4, 5]; // Static data return ( <div> <button onClick={() => setCount(count + 1)}>Increment Count</button> <p>Count: {count}</p> {/*ExpensiveComponent only re-renders if "data" changes, not on count changes*/} <ExpensiveComponent data={data} /> </div> ); } function MemoizedComponent({ data }) { // Simulate a render-heavy component console.log('Rendering MemoizedComponent...'); return <p>Data: {data.join(', ')}</p>; } // Memoize MemoizedComponent to prevent unnecessary re-renders const OptimizedMemoizedComponent = React.memo(MemoizedComponent); function ParentMemoComponent() { const [count, setCount] = useState(0); const data = [1, 2, 3, 4, 5]; return ( <div> <button onClick={() => setCount(count + 1)}>Increment Count</button> <p>Count: {count}</p> {/* MemoizedComponent only re-renders if its props change, not on count changes */} <OptimizedMemoizedComponent data={data} /> </div> ); } """ ### 7.2 Batching Updates Batching updates ensures that multiple state updates are grouped into a single render cycle. """javascript import React, { useState } from 'react'; import { unstable_batchedUpdates } from 'react-dom'; // Available only in some React versions function BatchUpdatesComponent() { const [count1, setCount1] = useState(0); const [count2, setCount2] = useState(0); const updateBothCounts = () => { unstable_batchedUpdates(() => { // Both state updates are batched into a single render setCount1(prevCount => prevCount + 1); setCount2(prevCount => prevCount + 1); }); }; return ( <div> <p>Count 1: {count1}</p> <p>Count 2: {count2}</p> <button onClick={updateBothCounts}>Update Both Counts</button> </div> ); } """ These standards provide a comprehensive guide to managing state in a clean and maintainable way. By following these guidelines, developers can build robust, performant, and secure applications.

# 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).