@dsivd/prestations-ng 19.2.0-beta.20 → 19.2.0-beta.22

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (40) hide show
  1. package/ANGULAR_SIGNALS.md +4 -0
  2. package/CHANGELOG.md +113 -3
  3. package/CONTRIBUTING.md +2 -2
  4. package/ESLINT_PLUGIN.md +146 -28
  5. package/GOOD_PRACTICES.md +258 -58
  6. package/INTRODUCTION_ANGULAR_SIGNALS.md +29 -2
  7. package/UPGRADING_V19.md +233 -31
  8. package/eslint/configs/template-rules.mjs +5 -0
  9. package/eslint/configs/ts-recommended.mjs +4 -0
  10. package/eslint/form-reads.mjs +63 -0
  11. package/eslint/rules/index.mjs +4 -0
  12. package/eslint/rules/no-direct-signal-mutation.mjs +57 -19
  13. package/eslint/rules/no-item-track-in-form-list.mjs +172 -0
  14. package/eslint/rules/no-uninvoked-signal-in-template.mjs +8 -3
  15. package/eslint/rules/require-model-change.mjs +89 -0
  16. package/eslint/template-ast.mjs +12 -2
  17. package/fesm2022/dsivd-prestations-ng.mjs +948 -692
  18. package/fesm2022/dsivd-prestations-ng.mjs.map +1 -1
  19. package/package.json +1 -1
  20. package/schematics/migration-collection.json +5 -0
  21. package/schematics/ng-update/migrations/update-19_2_0/index.js +39 -0
  22. package/schematics/utility/form-signal/class-migration.js +671 -0
  23. package/schematics/utility/form-signal/edits.js +34 -0
  24. package/schematics/utility/form-signal/form-signal-migration.js +184 -0
  25. package/schematics/utility/form-signal/page-classes.js +129 -0
  26. package/schematics/utility/form-signal/template-migration.js +666 -0
  27. package/src/eslint/configs/template-rules.mjs +5 -0
  28. package/src/eslint/configs/ts-recommended.mjs +4 -0
  29. package/src/eslint/form-reads.mjs +63 -0
  30. package/src/eslint/rules/__tests__/no-direct-signal-mutation.test.mjs +58 -0
  31. package/src/eslint/rules/__tests__/no-item-track-in-form-list.test.mjs +234 -0
  32. package/src/eslint/rules/__tests__/no-uninvoked-signal-in-template.test.mjs +6 -0
  33. package/src/eslint/rules/__tests__/require-model-change.test.mjs +93 -0
  34. package/src/eslint/rules/index.mjs +4 -0
  35. package/src/eslint/rules/no-direct-signal-mutation.mjs +57 -19
  36. package/src/eslint/rules/no-item-track-in-form-list.mjs +172 -0
  37. package/src/eslint/rules/no-uninvoked-signal-in-template.mjs +8 -3
  38. package/src/eslint/rules/require-model-change.mjs +89 -0
  39. package/src/eslint/template-ast.mjs +12 -2
  40. package/types/dsivd-prestations-ng.d.ts +266 -35
package/GOOD_PRACTICES.md CHANGED
@@ -21,6 +21,7 @@
21
21
  - [The `<fieldset>` and `<legend>` tags](good-practices#the__code__lt_fieldset_gt___code__and__code__lt_legend_gt___code__tags)
22
22
  - [Screen reader (show / hide)](good-practices#screen_reader__show___hide_)
23
23
  - [A prestations-ng page](good-practices#a_prestations-ng_page)
24
+ - [Binding the fields of the form](good-practices#binding_the_fields_of_the_form)
24
25
  - [Zoneless application](good-practices#zoneless_application)
25
26
  - [Displaying an asynchronous state](good-practices#displaying_an_asynchronous_state)
26
27
  - [Deriving a state from view queries](good-practices#deriving_a_state_from_view_queries)
@@ -333,6 +334,7 @@ with text for visually impaired people.
333
334
  5. The first heading tag of your page must be an h2 (`<h2>`)
334
335
  6. Add `<foehn-navigation>`
335
336
  7. If you have several pages, use the `<foehn-page-counter>` component
337
+ 8. Bind the fields of the form with `[model]` and `(modelChange)="patchForm([...], $event)"` (see below)
336
338
 
337
339
  `page-one.component.ts`
338
340
 
@@ -386,7 +388,15 @@ export class PageOneComponent
386
388
  fromDictionary }}
387
389
  </h2>
388
390
 
391
+ <!-- point (8) -->
392
+ @if (form(); as form) {
393
+ <foehn-input-text
394
+ name="firstName"
395
+ [model]="form.firstName"
396
+ (modelChange)="patchForm(['firstName'], $event)"
397
+ />
389
398
  <!-- [YOUR FOEHN COMPONENTS HERE] -->
399
+ }
390
400
 
391
401
  <foehn-navigation
392
402
  id="navigation"
@@ -400,6 +410,46 @@ export class PageOneComponent
400
410
  </div>
401
411
  ```
402
412
 
413
+ ### Binding the fields of the form
414
+
415
+ The `form` of a page is a signal: read it with `form()`, and never modify its value in place. Write a field with
416
+ `patchForm(path, value)`, which copies the objects along the path: the templates, the `computed()` and the
417
+ `effect()` reading the form follow every input of the user.
418
+
419
+ ```html
420
+ @if (form(); as form) {
421
+ <foehn-input-text
422
+ name="address.street"
423
+ [model]="form.address.street"
424
+ (modelChange)="patchForm(['address', 'street'], $event)"
425
+ />
426
+ @for (child of form.children; track child.id) {
427
+ <foehn-input-text
428
+ [name]="'children[' + $index + '].firstName'"
429
+ [model]="child.firstName"
430
+ (modelChange)="patchForm(['children', $index, 'firstName'], $event)"
431
+ />
432
+ } }
433
+ ```
434
+
435
+ ```ts
436
+ readonly childrenCount = computed(() => this.form()?.children.length ?? 0);
437
+
438
+ addChild(): void {
439
+ this.patchForm(['children'], [...(this.form()?.children ?? []), new Child()]);
440
+ }
441
+ ```
442
+
443
+ - The path is checked by TypeScript (a typo gives an error listing the valid keys).
444
+ - Never a `[model]` alone on a field the user can change: what the user enters would never reach the form
445
+ (`require-model-change` reports it). A field always disabled (`[disabled]="true"`), only displayed, is bound with
446
+ `[model]` alone.
447
+ - Track the rows of a list edited by its rows by an identifier (`track child.id`) or by `$index`, never by the
448
+ item: `patchForm()` replaces it, the row would be created again and lose the focus (`no-item-track-in-form-list`
449
+ reports it).
450
+ - A detail page (`AbstractListDetailPageComponent`) gives the path of its list with `getListPath()`, and writes the
451
+ item edited with `patchItem()`, `updateItem()` or `setItem()`.
452
+
403
453
  ## Zoneless application
404
454
 
405
455
  > ℹ️ Since v19.2, prestations-ng no longer needs zone.js and we recommend that you make your
@@ -459,32 +509,20 @@ modifies: the listener notifies Angular, but the same method can later be called
459
509
  or an `effect()`, and the field would no longer be displayed. A signal notifies Angular whoever
460
510
  modifies it.
461
511
 
462
- In your pages (`AbstractPageComponent`), `form` can't be a signal. prestations-ng refreshes the page
463
- when it loads `form` and `reference`, but whenever your code modifies the form, call `markForCheck()`
464
- after the modifications, whoever calls the method (a listener, a callback, an `effect()`, ...):
512
+ In your pages (`AbstractPageComponent`), `form` and `reference` are signals too: write the form with `patchForm()`,
513
+ never in place, whoever calls the method (a listener, a callback, an `effect()`, ...). No `markForCheck()` is needed:
465
514
 
466
515
  ```ts
467
- private readonly changeDetectorRef = inject(ChangeDetectorRef);
468
-
469
516
  ngOnInit(): void {
470
517
  super.ngOnInit();
471
518
  this.sessionInfoWithApplicationService.prefillForm((info) => {
472
- if (this.form) {
473
- this.form.firstName = info?.firstName ?? null;
474
- this.form.lastName = info?.lastName ?? null;
475
- this.changeDetectorRef.markForCheck();
476
- }
519
+ this.patchForm(['firstName'], info?.firstName ?? null);
520
+ this.patchForm(['lastName'], info?.lastName ?? null);
477
521
  });
478
522
  }
479
523
  ```
480
524
 
481
- - Once after the last modification is enough: Angular refreshes the page later, with all the
482
- modifications of the method. After an `await`, or in another callback, call it again.
483
- - A signal modified next to the form doesn't replace it: `set()` notifies Angular only when the value
484
- changes (e.g. an amount recalculated identical), and only refreshes the views reading the signal.
485
-
486
- If a service fills the form for the page, the page must still be notified: let the service return an
487
- `Observable` (or take a callback), and call `markForCheck()` in the page.
525
+ See "Binding the fields of the form" above.
488
526
 
489
527
  ### Deriving a state from view queries
490
528
 
@@ -772,6 +810,10 @@ Your component must:
772
810
  > model: a plain field would not be displayed without zone.js, and a `signal()` filled by
773
811
  > `onModelChange` (called by an `effect()`) would follow the model only at the next change
774
812
  > detection.
813
+ > - `updateNgModel()` receives a **new** object or array, never the model modified in place: the
814
+ > model is a signal, which ignores the same object, so no `modelChange` would be emitted and the
815
+ > page would never get the change. `patchNgModel()` writes a field of the model, or an item of a
816
+ > list, in a new model (see "Editing an object field by field" and the list of vehicles below).
775
817
 
776
818
  `input-date.component.ts`
777
819
 
@@ -935,6 +977,78 @@ Each `foehn-input-*` used in your view must:
935
977
  />
936
978
  ```
937
979
 
980
+ ### Editing an object field by field
981
+
982
+ `foehn-input-date` **transforms** its model: its three text fields hold values the `number[]` can't
983
+ (a day without its month), so each of them is a linked signal, and `getValidValue()` builds the
984
+ model from them.
985
+
986
+ A component which **edits an object as is**, each field of the object bound to one of its
987
+ `foehn-input-*` (e.g. a section of the form with a dozen fields), doesn't spread the object in
988
+ signals: it reads its `model()`, and writes each field with `patchNgModel(path, value)`, which
989
+ gives a new object to `updateNgModel()`.
990
+
991
+ ```ts
992
+ export class Owner {
993
+ lastName: string | null = null;
994
+ address = new OwnerAddress();
995
+ }
996
+
997
+ export class OwnerAddress {
998
+ street: string | null = null;
999
+ }
1000
+ ```
1001
+
1002
+ `owner-input.component.ts`
1003
+
1004
+ ```ts
1005
+ export class OwnerInputComponent extends FoehnInputComponent<Owner> {
1006
+ // The owner patchNgModel() starts from as long as the page gives none
1007
+ protected override emptyModel(): Owner {
1008
+ return new Owner();
1009
+ }
1010
+
1011
+ handleUserInput(): void {
1012
+ this.handleChange(this.model() ?? null);
1013
+ }
1014
+ }
1015
+ ```
1016
+
1017
+ `owner-input.component.html`
1018
+
1019
+ ```html
1020
+ <foehn-input-text
1021
+ [id]="buildId() + '_lastName'"
1022
+ [name]="name() + '.lastName'"
1023
+ [label]="'owner.last-name' | fromDictionary"
1024
+ [model]="model()?.lastName"
1025
+ (modelChange)="patchNgModel(['lastName'], $event)"
1026
+ (userInput)="handleUserInput()"
1027
+ />
1028
+ <foehn-input-text
1029
+ [id]="buildId() + '_street'"
1030
+ [name]="name() + '.address.street'"
1031
+ [label]="'owner.street' | fromDictionary"
1032
+ [model]="model()?.address.street"
1033
+ (modelChange)="patchNgModel(['address', 'street'], $event)"
1034
+ (userInput)="handleUserInput()"
1035
+ />
1036
+ ```
1037
+
1038
+ - `patchNgModel()` copies the objects along the path and keeps the others, and gives the new
1039
+ object to `updateNgModel()`. The same value changes nothing, so no `modelChange` is emitted.
1040
+ - With `strictTemplates`, TypeScript checks the path and the type of the value (`$event`).
1041
+ - `emptyModel()` gives the object `patchNgModel()` starts from as long as the page gives none: a
1042
+ component whose model is always given doesn't override it. Without one, `patchNgModel()`
1043
+ throws, as it does when an object of the path is `null` or `undefined`: hence the class `Owner`
1044
+ creating its `address`.
1045
+ - Several fields at once: `updateNgModel()` with a new object, e.g.
1046
+ `{ ...this.model(), lastName, firstName }`. A value derived from the object: a `computed()`
1047
+ reading `model()`.
1048
+ - No linked signal and no `getValidValue()`: the component keeps no state of its own, each change
1049
+ goes at once to the model, which the template reads again. An object whose fields are emptied
1050
+ stays an object (point 8 doesn't apply).
1051
+
938
1052
  ### Displaying the global validation of the component
939
1053
 
940
1054
  - Add the code below in the HTML part of your component
@@ -997,7 +1111,7 @@ Each `foehn-input-*` used in your view must:
997
1111
 
998
1112
  > ⚠️ Don't forget to put a `track` with a unique identifier in the `@for` loop, otherwise the
999
1113
  > validation won't be displayed. When a unique identifier such as `id` isn't possible, track
1000
- > by object or, as a last resort, `track $index`.
1114
+ > by `$index`: never by object a list of the form whose rows edit their item (see "Binding the fields of the form").
1001
1115
 
1002
1116
  > ℹ️ In an Angular `@for` loop with a `FoehnInputComponent` component, if you validate your
1003
1117
  > form, the errors returned are synchronized with the index of your components repeated in the
@@ -1024,7 +1138,7 @@ your `AbstractPageComponent`. This method will contain the following code:
1024
1138
  * if an inventory item that was in error is removed, this prevents the error to be displayed
1025
1139
  * to the next item that has taken it's index
1026
1140
  */
1027
- this._gesdemService.validate(this.form).pipe(first()).subscribe();
1141
+ this._gesdemService.validate(this.form()).pipe(first()).subscribe();
1028
1142
  ```
1029
1143
 
1030
1144
  Here is an example of a form page containing this method (1):
@@ -1064,7 +1178,7 @@ export class YourPageComponent
1064
1178
  * if an inventory item that was in error is removed, this prevents the error to be displayed
1065
1179
  * to the next item that has taken it's index
1066
1180
  */
1067
- this._gesdemService.validate(this.form).pipe(first()).subscribe();
1181
+ this._gesdemService.validate(this.form()).pipe(first()).subscribe();
1068
1182
  }
1069
1183
  }
1070
1184
  ```
@@ -1091,7 +1205,18 @@ demande-page/
1091
1205
 
1092
1206
  **vehicule-item**
1093
1207
 
1094
- `vehicule-item.component.html` contains the button removing the item from the list (1).
1208
+ A vehicle of the list is a `Vehicule` of your form, here with a brand and a plate number:
1209
+
1210
+ ```ts
1211
+ export class Vehicule {
1212
+ brand: string | null = null;
1213
+ plateNumber: string | null = null;
1214
+ }
1215
+ ```
1216
+
1217
+ `vehicule-item.component.html` binds each field of the vehicle to its model, and writes it with
1218
+ `patchNgModel()` (1) (see "Editing an object field by field"). It contains the button removing the
1219
+ item from the list (2).
1095
1220
 
1096
1221
  ```html
1097
1222
  <div
@@ -1104,11 +1229,37 @@ demande-page/
1104
1229
  <foehn-validation-alerts [component]="this" />
1105
1230
 
1106
1231
  <div class="row d-flex align-items-end vehicule-infos">
1107
- <!-- ... your foehn-input-* components -->
1232
+ <div class="col-md-5">
1233
+ <!-- (1) the name of the field in the form, as in the errors of the backend: vehicules[0].brand -->
1234
+ <foehn-input-text
1235
+ [id]="buildId() + '_brand'"
1236
+ [name]="name() + '.brand'"
1237
+ [label]="'demande-page.vehicule-brand' | fromDictionary"
1238
+ [model]="model()?.brand"
1239
+ (modelChange)="patchNgModel(['brand'], $event)"
1240
+ (userInput)="handleUserInput()"
1241
+ [required]="true"
1242
+ />
1243
+ </div>
1244
+ <div class="col-md-5">
1245
+ <foehn-input-text
1246
+ [id]="buildId() + '_plateNumber'"
1247
+ [name]="name() + '.plateNumber'"
1248
+ [label]="'demande-page.vehicule-plate-number' | fromDictionary"
1249
+ [model]="model()?.plateNumber"
1250
+ (modelChange)="patchNgModel(['plateNumber'], $event)"
1251
+ (userInput)="handleUserInput()"
1252
+ [required]="true"
1253
+ />
1254
+ </div>
1108
1255
 
1109
1256
  <div class="col-md-2 mt-md-0 mt-xs-2">
1110
- <button class="btn btn-danger" (click)="removeVehicule()">
1111
- <!-- (1) -->
1257
+ <button
1258
+ class="btn btn-danger"
1259
+ type="button"
1260
+ (click)="removeVehicule()"
1261
+ >
1262
+ <!-- (2) -->
1112
1263
  {{ 'demande-page.vehicule-remove' | fromDictionary }}
1113
1264
  </button>
1114
1265
  </div>
@@ -1116,8 +1267,9 @@ demande-page/
1116
1267
  </div>
1117
1268
  ```
1118
1269
 
1119
- `vehicule-item.component.ts` contains the removal function, which sends the event up to its
1120
- parent (the list of items).
1270
+ `vehicule-item.component.ts` has nothing to do for its fields: `patchNgModel()` gives the list a
1271
+ new vehicle at each change, which keeps the fields the component doesn't display (e.g. an id). It
1272
+ contains the removal function, which sends the event up to its parent, the list of items (3).
1121
1273
 
1122
1274
  > 💡 `@Output() + EventEmitter` are replaced by the `output()` function.
1123
1275
 
@@ -1133,28 +1285,36 @@ parent (the list of items).
1133
1285
  ],
1134
1286
  imports: [
1135
1287
  FoehnValidationAlertsComponent,
1136
- // ... your foehn-input-*
1288
+ FoehnInputTextComponent,
1137
1289
  SdkDictionaryPipe,
1138
1290
  ],
1139
1291
  })
1140
1292
  export class VehiculeItemComponent extends FoehnInputComponent<Vehicule> {
1141
1293
  readonly removedVehicule = output<void>();
1142
1294
 
1295
+ handleUserInput(): void {
1296
+ this.handleChange(this.model() ?? null);
1297
+ }
1298
+
1143
1299
  removeVehicule(): void {
1300
+ // (3)
1144
1301
  this.removedVehicule.emit();
1145
1302
  }
1146
-
1147
- // ...code
1148
1303
  }
1149
1304
  ```
1150
1305
 
1306
+ > 💡 The list always gives a vehicle: no `emptyModel()` needed. A vehicle the user empties stays in
1307
+ > the list, with its errors, until it is removed with its button.
1308
+
1151
1309
  **vehicules-list**
1152
1310
 
1153
1311
  `vehicules-list.component.html` contains your `@for` loop (1) and your repeatable component (2), which
1154
1312
  must also send the event up.
1155
1313
 
1156
- > ⚠️ In the `@for` loop, don't forget to put a `track` (unique identifier), otherwise the
1157
- > validation won't be displayed. Here, for example, we track with `vehicule.id`.
1314
+ > ⚠️ In the `@for` loop, don't forget to put a `track`, otherwise the validation won't be
1315
+ > displayed: an identifier every item has, even a new one, or `$index` as here. Never the item
1316
+ > itself (`track vehicule`): each change replaces it with a new vehicle, so its row would be created
1317
+ > again at each input, and the field being edited would lose the focus.
1158
1318
 
1159
1319
  ```html
1160
1320
  <div
@@ -1187,19 +1347,19 @@ must also send the event up.
1187
1347
  ></small>
1188
1348
  }
1189
1349
 
1190
- <!-- (1) your @for loop + track (unique identifier) -->
1191
- @for (vehicule of vehicules(); track vehicule.id; let i = $index) {
1350
+ <!-- (1) your @for loop over the model + track -->
1351
+ @for (vehicule of model(); track $index; let i = $index) {
1192
1352
  <!-- (2) your reusable component -->
1193
1353
  <app-vehicule-item
1194
1354
  [name]="name() + '[' + i + ']'"
1195
1355
  [model]="vehicule"
1196
1356
  (modelChange)="updateVehiculesList($event, i)"
1197
- (userInput)="handleUserInput($event, i)"
1357
+ (userInput)="handleUserInput()"
1198
1358
  (removedVehicule)="handleRemovedVehicule(i)"
1199
1359
  />
1200
1360
  }
1201
1361
 
1202
- <button class="btn btn-primary mt-2" (click)="addVehicule()">
1362
+ <button class="btn btn-primary mt-2" type="button" (click)="addVehicule()">
1203
1363
  {{ 'demande-page.vehicule-add' | fromDictionary }}
1204
1364
  </button>
1205
1365
  </div>
@@ -1213,7 +1373,7 @@ must also send the event up.
1213
1373
 
1214
1374
  `vehicules-list.component.ts` in turn sends the event (1) up to the parent (`AbstractPageComponent`)
1215
1375
  and removes the item from the list (2). This is also where you can handle the addition of an
1216
- item (3).
1376
+ item (3). Each change writes a new list in the model (4).
1217
1377
 
1218
1378
  ```ts
1219
1379
  @Component({
@@ -1234,34 +1394,62 @@ item (3).
1234
1394
  export class VehiculesListComponent extends FoehnInputComponent<Vehicule[]> {
1235
1395
  readonly removedVehicule = output<void>(); // (1) event to send up to the parent
1236
1396
 
1237
- // Signal holding your repeatable items, derived from the model: it is replaced, never modified in place
1238
- readonly vehicules = linkedSignal(() => this.model() ?? []);
1239
-
1397
+ // Called by the (modelChange) of an item: the item is replaced in a new list
1240
1398
  updateVehiculesList(vehicule: Vehicule, index: number): void {
1241
- this.vehicules.update((vehicules) =>
1242
- vehicules.map((item, i) => (i === index ? vehicule : item)),
1243
- );
1244
- this.getValidValueAndUpdateNgModel(); // Update of your model
1399
+ this.patchNgModel([index], vehicule);
1400
+ }
1401
+
1402
+ handleUserInput(): void {
1403
+ const validValue = this.getValidValue(this.model() ?? []);
1404
+ if (typeof validValue !== 'undefined') {
1405
+ this.handleChange(validValue);
1406
+ }
1245
1407
  }
1246
1408
 
1247
1409
  handleRemovedVehicule(index: number): void {
1248
1410
  // (2) your function removing the item and sending the event
1249
- this.vehicules.update((vehicules) =>
1250
- vehicules.filter((_vehicule, i) => i !== index),
1251
- ); // removal of the item
1252
- this.getValidValueAndUpdateNgModel(); // Update of your model
1411
+ this.updateVehicules(
1412
+ (this.model() ?? []).filter((_vehicule, i) => i !== index),
1413
+ );
1253
1414
  this.removedVehicule.emit(); // (1) the event is sent up
1254
1415
  }
1255
1416
 
1256
1417
  addVehicule(): void {
1257
1418
  // (3) Handling of the addition of an item
1258
- // ...code
1419
+ this.updateVehicules([...(this.model() ?? []), new Vehicule()]);
1420
+ }
1421
+
1422
+ // (4) a new list, never the list of the model modified in place (push(), splice(), list[i] = ...)
1423
+ private updateVehicules(vehicules: Vehicule[]): void {
1424
+ const validValue = this.getValidValue(vehicules);
1425
+ if (typeof validValue !== 'undefined') {
1426
+ this.updateNgModel(validValue);
1427
+ }
1428
+ }
1429
+
1430
+ private getValidValue(
1431
+ vehicules: Vehicule[],
1432
+ ): Vehicule[] | null | undefined {
1433
+ if (vehicules.length) {
1434
+ return vehicules;
1435
+ }
1436
+ // An empty list is null once the model is known (point 8 of "Creating a reusable component")
1437
+ return this.model_ !== undefined ? null : undefined;
1259
1438
  }
1260
1439
  }
1261
1440
  ```
1262
1441
 
1442
+ > 🚨 Never modify the list of the model, or one of its items, in place and give it back to
1443
+ > `updateNgModel()`: the model is a signal, which ignores the same array. No `modelChange` is
1444
+ > emitted, so the page never gets the change: its `patchForm()` isn't called, and the form, modified
1445
+ > in place, notifies nothing.
1446
+ >
1447
+ > 💡 The list reads its `model()` directly, in the template and in the class: a copy in a
1448
+ > `linkedSignal()` would only duplicate it. The linked signals are for a component transforming its
1449
+ > model, as `foehn-input-date`.
1450
+ >
1263
1451
  > 💡 No need to define a dedicated `trackByFn` anymore: the new `@for` syntax directly uses
1264
- > the `track` expression (here `vehicule.id`).
1452
+ > the `track` expression (here `$index`).
1265
1453
 
1266
1454
  **demande-page**
1267
1455
 
@@ -1273,13 +1461,16 @@ the removal event (2).
1273
1461
  <!-- ... -->
1274
1462
  <h2>{{ 'demande-page.vehicules' | fromDictionary }}</h2>
1275
1463
 
1464
+ @if (form(); as form) {
1276
1465
  <app-vehicules-list
1277
- [(model)]="form.vehicules"
1466
+ [model]="form.vehicules"
1467
+ (modelChange)="patchForm(['vehicules'], $event)"
1278
1468
  name="vehicules"
1279
1469
  [label]="'demande-page.vehicules-list' | fromDictionary"
1280
1470
  [required]="true"
1281
1471
  (removedVehicule)="handleRemovedVehicule()"
1282
1472
  />
1473
+ }
1283
1474
  <!-- (1) Use of your list - (2) Call of the method saving the data in GESDEM to refresh the errors -->
1284
1475
 
1285
1476
  <foehn-navigation
@@ -1308,7 +1499,7 @@ export class DemandePageComponent
1308
1499
  * if an inventory item that was in error is removed, this prevents the error to be displayed
1309
1500
  * to the next item that has taken it's index
1310
1501
  */
1311
- this._gesdemService.save(this.form).pipe(first()).subscribe();
1502
+ this._gesdemService.save(this.form()).pipe(first()).subscribe();
1312
1503
  }
1313
1504
  }
1314
1505
  ```
@@ -1343,7 +1534,7 @@ What **not** to do:
1343
1534
  ```ts
1344
1535
  isAmountFilled(): boolean {
1345
1536
  // true after the input of '0', false once the form is loaded (0)
1346
- return !!this.form?.amount;
1537
+ return !!this.form()?.amount;
1347
1538
  }
1348
1539
  ```
1349
1540
 
@@ -1351,13 +1542,13 @@ What **to** do:
1351
1542
 
1352
1543
  ```ts
1353
1544
  isAmountFilled(): boolean {
1354
- const amount = this.form?.amount;
1545
+ const amount = this.form()?.amount;
1355
1546
  return amount !== null && amount !== undefined && amount !== '';
1356
1547
  }
1357
1548
 
1358
1549
  getTotal(): number {
1359
1550
  // Number() converts '12.50' as well as 12.5
1360
- return Number(this.form?.amount ?? 0) + Number(this.form?.fees ?? 0);
1551
+ return Number(this.form()?.amount ?? 0) + Number(this.form()?.fees ?? 0);
1361
1552
  }
1362
1553
  ```
1363
1554
 
@@ -1405,19 +1596,27 @@ export class BusinessForm {
1405
1596
  `page-1.html`
1406
1597
 
1407
1598
  ```html
1599
+ @if (form(); as form) {
1408
1600
  <foehn-input-text
1409
- [(model)]="form.identification.firstName"
1601
+ [model]="form.identification.firstName"
1602
+ (modelChange)="patchForm(['identification', 'firstName'], $event)"
1410
1603
  name="identification.firstName"
1411
1604
  />
1412
1605
  <!-- 2 levels of depth -->
1413
1606
 
1414
1607
  <foehn-input-text
1415
- [(model)]="form.identification.lastName"
1608
+ [model]="form.identification.lastName"
1609
+ (modelChange)="patchForm(['identification', 'lastName'], $event)"
1416
1610
  name="identification.lastName"
1417
1611
  />
1418
1612
 
1419
- <foehn-boolean-checkbox [(model)]="form.acceptCookies" name="acceptCookies" />
1613
+ <foehn-boolean-checkbox
1614
+ [model]="form.acceptCookies"
1615
+ (modelChange)="patchForm(['acceptCookies'], $event)"
1616
+ name="acceptCookies"
1617
+ />
1420
1618
  <!-- 1 level of depth -->
1619
+ }
1421
1620
  ```
1422
1621
 
1423
1622
  - On the back-end side, you can handle your errors with the annotations (`@NotEmpty`, `@NotNull`, ...),
@@ -1470,7 +1669,8 @@ HTML page and the names of your errors must match.
1470
1669
 
1471
1670
  ```html
1472
1671
  <foehn-input-text
1473
- [(model)]="form.identification.lastName"
1672
+ [model]="form.identification.lastName"
1673
+ (modelChange)="patchForm(['identification', 'lastName'], $event)"
1474
1674
  name="identification.lastName"
1475
1675
  />
1476
1676
  ```
@@ -349,8 +349,16 @@ readonly userResource = rxResource({
349
349
  params: () => this.userId(),
350
350
  stream: ({ params: id }) => this.userService.getUser(id), // Observable<User>
351
351
  });
352
+ ```
352
353
 
353
- // in the template: userResource.value(), userResource.isLoading(), userResource.error()
354
+ ```html
355
+ @if (userResource.hasValue()) {
356
+ <p>{{ userResource.value().name }}</p>
357
+ } @else if (userResource.isLoading()) {
358
+ <p>Loading...</p>
359
+ } @else if (userResource.error()) {
360
+ <p>The user could not be loaded</p>
361
+ }
354
362
  ```
355
363
 
356
364
  **Concrete example — before/after on an HTTP call handled by hand:**
@@ -376,9 +384,28 @@ readonly userResource = rxResource({
376
384
  params: () => this.userId(),
377
385
  stream: ({ params: id }) => this.userService.getUser(id),
378
386
  });
379
- // userResource.value(), userResource.isLoading(), userResource.error()
387
+ // userResource.hasValue() before userResource.value(), userResource.isLoading(), userResource.error()
380
388
  ```
381
389
 
390
+ ⚠️ **Before using a resource:**
391
+
392
+ - **`value()` throws while the resource is in error** (Angular 21): read it behind `hasValue()`, as above. Otherwise a failed request breaks the rendering of the whole template, its buttons included.
393
+ - **`params` returning `undefined` loads nothing**: the resource waits, e.g. until the reference of the demand is known (`params: () => this.reference() ?? undefined`).
394
+ - **`httpResource()`** (`@angular/common/http`) does the same for a plain GET, without a service. E.g. the sections of the verification page, loaded once the reference is known:
395
+
396
+ ```ts
397
+ readonly recapSections = httpResource<FoehnRecapSection[]>(
398
+ () => {
399
+ const reference = this.reference();
400
+ return reference ? `api/${reference}/pdf-sections` : undefined;
401
+ },
402
+ { defaultValue: [] },
403
+ );
404
+ ```
405
+
406
+ - **`resource()`, `rxResource()` and `httpResource()` are `@experimental` in Angular 21** (stable in Angular 22, with the same API).
407
+ - **In a spec**, a loading resource keeps `await fixture.whenStable()` waiting for its response: start the request with a first change detection (`fixture.detectChanges()` or `TestBed.tick()`), answer it with `HttpTestingController`, then `await fixture.whenStable()`.
408
+
382
409
  ### Should we drop the `async` pipe?
383
410
 
384
411
  No, it isn't deprecated. But the recommended trend for new code is to prefer `toSignal()` in most cases: