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

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/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.14",
   "module": "fesm2022/dsivd-prestations-ng.mjs",
   "typings": "types/dsivd-prestations-ng.d.ts",
   "exports": {