@dsivd/prestations-ng 19.2.0-beta.13 → 19.2.0-beta.15

package/GOOD_PRACTICES.md

@@ -33,6 +33,7 @@
     - [Example with foehn-input-date of prestations-ng](good-practices#example_with_foehn-input-date_of_prestations-ng)
     - [Displaying the global validation of the component](good-practices#displaying_the_global_validation_of_the_component)
     - [Avoiding error display problems in a `@for` loop](good-practices#avoiding_error_display_problems_in_a__code__for__code__loop)
+- [Types of the form fields](good-practices#types_of_the_form_fields)
 - [Form validation](good-practices#form_validation)
     - [Standard handling](good-practices#standard_handling)
     - [Manual handling](good-practices#manual_handling)
@@ -471,6 +472,9 @@ ngOnInit(): void {
 }
 ```
 
+If a service fills the form for the page, the page must still be notified: let the service return an
+`Observable` (or take a callback), and call `markForCheck()` in the page.
+
 ### Deriving a state from view queries
 
 > ⚠️ A field read by the template and modified in `ngAfterViewInit()`, `ngAfterContentInit()` or
@@ -552,8 +556,20 @@ it('should display the details', async () => {
 });
 ```
 
-`await fixture.whenStable()` also waits for the pending tasks, such as the HTTP requests: the test
-doesn't end before them (otherwise `NG0205: Injector has already been destroyed`).
+`await fixture.whenStable()` also waits for the pending tasks of the application, such as the debounced
+`userInput` of the prestations-ng inputs: the test doesn't end before them (otherwise
+`NG0205: Injector has already been destroyed`). But it doesn't wait for the HTTP requests of a spec:
+`provideHttpClientTesting()` keeps them pending until the test answers them. Answer them first with
+`HttpTestingController`, then `await fixture.whenStable()`:
+
+```ts
+it('should display the reference of the demand', async () => {
+    httpMock.expectOne('api/demande/1').flush({ reference: 'DEM-1' });
+    await fixture.whenStable();
+
+    expect(fixture.nativeElement.textContent).toContain('DEM-1');
+});
+```
 
 Keep `fixture.detectChanges()` for:
 
@@ -1269,6 +1285,59 @@ export class DemandePageComponent
 }
 ```
 
+## Types of the form fields
+
+> ℹ️ `AbstractPageComponent` replaces `form` with the JSON sent by the backend, as is: at runtime, a field has
+> the type of the JSON written from the Java model, whatever its TypeScript type says.
+
+Give the Java field the type matching the model of the component:
+
+| Component                                                          | TypeScript model     | Java field                             |
+| ------------------------------------------------------------------ | -------------------- | -------------------------------------- |
+| `foehn-input-text`, `foehn-input-textarea`, `foehn-input-email`... | `string`             | `String`                               |
+| `foehn-input-time`                                                 | `string`             | `String` with `@ValidStringTime`       |
+| `foehn-input-date`                                                 | `(number \| null)[]` | `LenientLocalDate`                     |
+| `foehn-input-date-time`                                            | `(number \| null)[]` | `LenientLocalDateTime`                 |
+| `foehn-boolean-checkbox`, `foehn-boolean-radio`                    | `boolean`            | `Boolean`                              |
+| `foehn-input-number`                                               | `string`             | `Integer`, `BigDecimal`... (see below) |
+
+> ⚠️ The model of `foehn-input-number` is a `string`: the component keeps the input as typed (decimal comma,
+> leading zeros, number of decimals). But the Java field is a number (`Integer`, `BigDecimal`), which is
+> written as a number in the JSON. The field holds `'0'` after the input of the user, and `0` once the form
+> comes back from the backend. The same happens with any component whose model is a `string` bound to a Java
+> field which isn't a `String`.
+
+Never test such a field by its truthiness (`!!value`, `if (value)`, `value || ...`): `'0'` is true, `0` is
+false.
+
+What **not** to do:
+
+```ts
+isAmountFilled(): boolean {
+    // true after the input of '0', false once the form is loaded (0)
+    return !!this.form?.amount;
+}
+```
+
+What **to** do:
+
+```ts
+isAmountFilled(): boolean {
+    const amount = this.form?.amount;
+    return amount !== null && amount !== undefined && amount !== '';
+}
+
+getTotal(): number {
+    // Number() converts '12.50' as well as 12.5
+    return Number(this.form?.amount ?? 0) + Number(this.form?.fees ?? 0);
+}
+```
+
+> ⚠️ The values of the elements of `foehn-select` and `foehn-checkbox` must have the type of the Java field:
+> they are compared to the model with `===`. With `'1'` as value of an element and `1` sent by the backend
+> (`Integer`), no element is selected anymore once the form is loaded, and the component warns that the saved
+> value no longer exists in the list.
+
 ## Form validation
 
 > ℹ️ When your form is saved in GESDEM, the `AbstractPageComponent` handles the

package/INTRODUCTION_ANGULAR_SIGNALS.md

@@ -338,7 +338,7 @@ It's the most telling example to show the team: **the signal drives the user inp
 
 ### `rxResource()` — asynchronous calls driven by a signal, with loading/error state included
 
-An alternative to `toSignal()` when you also want state tracking (loading, error, reload) without coding it by hand. `rxResource()` accepts an `Observable` as data source, and is triggered again automatically when the signals the `request` depends on change.
+An alternative to `toSignal()` when you also want state tracking (loading, error, reload) without coding it by hand. `rxResource()` accepts an `Observable` as data source, and is triggered again automatically when the signals read by its `params` function change.
 
 ```ts
 import { rxResource } from '@angular/core/rxjs-interop';
@@ -346,8 +346,8 @@ import { rxResource } from '@angular/core/rxjs-interop';
 readonly userId = input.required<string>();
 
 readonly userResource = rxResource({
-  request: () => this.userId(),
-  loader: ({ request: id }) => this.userService.getUser(id), // Observable<User>
+  params: () => this.userId(),
+  stream: ({ params: id }) => this.userService.getUser(id), // Observable<User>
 });
 
 // in the template: userResource.value(), userResource.isLoading(), userResource.error()
@@ -373,8 +373,8 @@ ngOnInit(): void {
 ```ts
 // 🟢 After: rxResource(), loading/error included, automatic re-fetch if userId() changes
 readonly userResource = rxResource({
-  request: () => this.userId(),
-  loader: ({ request: id }) => this.userService.getUser(id),
+  params: () => this.userId(),
+  stream: ({ params: id }) => this.userService.getUser(id),
 });
 // userResource.value(), userResource.isLoading(), userResource.error()
 ```
@@ -423,6 +423,50 @@ The `async` pipe stays fully legitimate when the `Observable` is consumed **only
 
     It also applies between layers: a service can compose entirely in RxJS (`debounceTime`, `retry`, `combineLatest`...) and stay testable independently of any component — it's the consuming component, "at the edge", that converts to a signal when displaying.
 
+### And the `BehaviorSubject`s?
+
+> 🎤 a `BehaviorSubject` holds a current value like a signal, but it is also a stream: we don't convert them systematically, we look at what it represents and who consumes it.
+
+It becomes a `signal()` when it is a **private state**, written with `next()` and read with `getValue()` or `| async`, without any operator behind it:
+
+```ts
+// 🔴 A state kept in a BehaviorSubject
+private readonly selectedTab = new BehaviorSubject<Tab>('summary');
+
+// 🟢 The same state in a signal: readable in a computed(), no subscription
+private readonly selectedTab = signal<Tab>('summary');
+```
+
+It stays in RxJS when:
+
+- it is the **source of an RxJS chain** (`switchMap` to an HTTP call, `debounceTime`, `combineLatest`...): as a signal, it would have to go back through `toObservable()`, which emits later (through an `effect()`) and only the last value of several writes in a row. A useless round trip, and the timing changes
+- it carries **events**, not a state: a signal ignores a value equal to the current one (`Object.is`) and merges the writes in a row
+- it is part of the **public API** of a library or a shared service: replacing the `Observable` breaks its consumers. If they need a signal, add one next to it (`toSignal()` in the service) rather than replacing it
+- some code relies on the **synchronous notification**: `subscribe()` is called at each `next()`, right away, whereas an `effect()` runs later, once for several writes
+
+```ts
+// 🔴 An event turned into a signal: the second reload triggers nothing
+private readonly reloadTrigger = signal(true);
+
+reload(): void {
+  this.reloadTrigger.set(true); // same value as before: no notification
+}
+
+// 🟢 An event stays a stream: each next() counts
+private readonly reloadTrigger = new Subject<void>();
+
+readonly alerts$ = this.reloadTrigger.pipe(
+  startWith(undefined),
+  switchMap(() => this.alertService.getAlerts()),
+);
+
+reload(): void {
+  this.reloadTrigger.next();
+}
+```
+
+> ⚠️ In a zoneless application, the `BehaviorSubject` itself is not the problem: a `subscribe()` writing a field read by the template, without notifying Angular, is. Fix the consumer with `toSignal()` or `| async` (see "Displaying an asynchronous state" in [GOOD_PRACTICES.md](GOOD_PRACTICES.md)).
+
 ---
 
 ## 7. Pitfall #1: mutation vs reassignment
@@ -501,3 +545,4 @@ export class ContactListComponent {
 - I never mutate a signal value in place anymore — always `.set()`/`.update()` with a new reference
 - I know when to use `untracked()` in an `effect()`
 - I don't try to replace all my RxJS with signals — I keep RxJS for composed async (HTTP, debounce, switchMap...) and I only convert to a signal at the edge, with `toSignal()`/`toObservable()`/`rxResource()`
+- I only turn a `BehaviorSubject` into a signal when it is a private state without operators — the sources of RxJS chains, the events and the public APIs stay in RxJS

package/UPGRADING_V19.md

@@ -1593,7 +1593,7 @@ then uninstall zone.js:
 npm uninstall zone.js
 ```
 
-`zone.js` stays in your `package-lock.json` as an optional peer dependency of `@angular/core`: this is expected. Check
+`zone.js` can stay in your `package-lock.json` as an optional peer dependency of `@angular/core`: this is expected. Check
 instead that the build of your application no longer outputs a `polyfills` chunk (unless you still have other
 polyfills, e.g. `@angular/localize/init`).
 
@@ -1671,7 +1671,9 @@ Pay attention to:
   (`ExpressionChangedAfterItHasBeenCheckedError`). Fix the component (signal, `markForCheck()`) rather than the
   test.
 - `await fixture.whenStable()` waits for the change detection and for the pending tasks of the application
-  (e.g. the debounced `userInput` of the prestations-ng inputs), not for the timers.
+  (e.g. the debounced `userInput` of the prestations-ng inputs), not for the timers, nor for the HTTP requests of a
+  spec: `provideHttpClientTesting()` keeps them pending until the test answers them. Answer them first with
+  `HttpTestingController` (`expectOne(...).flush(...)`), then `await fixture.whenStable()`.
 
 ### Last but not least, check if your application is working!!!
 

package/package.json

@@ -39,7 +39,7 @@
   "ng-update": {
     "migrations": "./schematics/migration-collection.json"
   },
-  "version": "19.2.0-beta.13",
+  "version": "19.2.0-beta.15",
   "module": "fesm2022/dsivd-prestations-ng.mjs",
   "typings": "types/dsivd-prestations-ng.d.ts",
   "exports": {