diff --git a/custom-words.txt b/custom-words.txt index aaf6cc11e..bf86d41e9 100644 --- a/custom-words.txt +++ b/custom-words.txt @@ -1,7 +1,6 @@ # Custom dictionary for spellchecking. Before adding a word here, consider whether you can put # it in a single (`) or multiline (```) code snippet instead, as they are automatically ignored # by the spellchecker. Please keep the list sorted alphabetically. - AndroidX AOSP Bitwarden @@ -60,6 +59,7 @@ precompiler proxied recompositions refactorings +Rickabaugh roadmap roadmaps rollout @@ -96,4 +96,4 @@ YubiKeys # Forbidden words !auto-fill -!auto-filled +!auto-filled \ No newline at end of file diff --git a/docs/architecture/adr/0028-ngrx-signals.md b/docs/architecture/adr/0028-ngrx-signals.md new file mode 100644 index 000000000..b51d146db --- /dev/null +++ b/docs/architecture/adr/0028-ngrx-signals.md @@ -0,0 +1,109 @@ +--- +adr: "0028" +status: "Proposed" +date: 2025-07-08 +tags: [client] +--- + +# 0028 - Adopt `@ngrx/signals` for Component State Stores + + + +## Prior Reading + +- [ADR 0027 - Adopt Angular Signals for Component State](./0027-angular-signals.md) +- [Angular Signals](https://angular.dev/guide/signals) +- [NgRx Docs](https://ngrx.io/guide/signals) + +## Context and Problem Statement + +Building on [ADR 0027 - Adopt Angular Signals for Component State](./0027-angular-signals.md) +decision to adopt Angular signals for component state, this ADR addresses state management patterns +across our application on the component level. + +The DIRT team frequently interacts with multiple services on the domain layer and exposes this data +to various components. Current implementation shows duplicate patterns for managing service data, +transforming it for UI consumption, and sharing it between components. + +### Problem + +We need a standardized approach to manage cross-component state that leverages Angular signals while +reducing code duplication and improving developer experience. + +### Context + +@ngrx/signals provides a signal store that captures these repeating patterns and centralizes state +management in a way that complements our existing signal adoption + +## Considered Options + +- **Continue with Angular Signals only** + - Maintain current approach using signals within individual components + - Does not provide the state management features and cross-component patterns that @ngrx/signals + offers through the signal store +- **Alternative state management solutions** + - Explore other state management libraries + - Existing options like the original NgRx store involve significant boilerplate, don’t leverage + signals, and lack team support +- **Adopt @ngrx/signals package** + - Implement the signal store to capture repeating patterns and manage state across components + - Builds upon our existing signal adoption + +## Decision Outcome + +Chosen option: **Adopt @ngrx/signals for state management on the component level** + +The benefits significantly outweigh the costs of learning curve and dependency addition. The +potential negatives can be addressed through phased implementation and clear documentation. + +### Positive Consequences + +- Improved developer experience +- Captures repeating patterns (huge bonus) +- Creates single source of truth from services to UI layer +- Builds existing signal adoption + +### Negative Consequences + +- Learning curve (though minimal compared to other state management solutions like NgRx store) +- Potential confusion if different state management patterns emerge or exist in the code-base +- May require refactoring existing service-level shared data patterns +- Need to establish organization-level guidance/examples (not just team-level) +- Introduces another dependency +- Limited debugging tools + +### Plan + +**Learning curve mitigation:** Presentation on the @ngrx/signals package for detailed +tutorial/documentation (refinement if needed) + +**Pattern standardization:** Establish guidelines for when to use different state management +approaches and document existing state management patterns + +**Phased implementation:** Start with DIRT proof of concept, then expand to organization level with +clear folder structure and guidelines + +**Refactoring support:** Use current proof of concept as a template for migration patterns + +**Limited debugging:** Current NgRx DevTools don’t fully support signal stores; Expose manual +debugging through a feature until NgRx team releases updated tooling + +## Guidelines + +**When to use a signal store:** Cross-component state management, service data aggregation, +repeating UI patterns + +**Security considerations:** Do not store decrypted sensitive data in signal stores; use for UI +state, metadata, and non-sensitive application data only + +**Data types:** Suitable for display preferences, loading state, filtered/sorted lists, navigation +state - not for decrypted vault data + +**Team coordination:** Coordinate with security experts for any questions about data classification + +## Further reading + +- [NgRx Signal Store POC](https://github.com/bitwarden/clients/pull/15186) +- [The new NGRX Signal Store for Angular: 3+n Flavors - ANGULARarchitects](https://www.angulararchitects.io/en/blog/the-new-ngrx-signal-store-for-angular-2-1-flavors/) +- [Rethinking Reactivity w/ Alex Rickabaugh | Dec '23 | AngularNation.net](https://www.youtube.com/watch?v=_yMrnSa2cTI) +- [NgRx Signals Introduction Slides](https://docs.google.com/presentation/d/1vHVLlSmc51emZS6t_9MwEoH7FBp-yVovMgNPSOqaP_k/edit?usp=drive_link)