@dsivd/prestations-ng 19.2.0-beta.21 → 19.2.0-beta.23

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.
package/CHANGELOG.md CHANGED
@@ -22,6 +22,12 @@
22
22
  (`'address.street'`, or a list of keys), not checked.
23
23
  - `patchForm()`, `patchItem()`, `PendingUploadService`, the custom errors of the street of `foehn-input-address`
24
24
  and the elements of `foehn-select`, `foehn-radio`, `foehn-checkbox` and the autocompletes use it.
25
+ - `FoehnInputComponent.patchNgModel(path, value)` (since 19.2.0-beta.22): writes a value at a typed path of the
26
+ model, in a new model given to `updateNgModel()`, e.g.
27
+ `[model]="model()?.lastName" (modelChange)="patchNgModel(['lastName'], $event)"` in a component editing an object
28
+ as is, or `patchNgModel([index], item)` in a list. The new protected `emptyModel()` gives the model it starts from
29
+ when the page gives none (none by default: `patchNgModel()` then throws). See "Editing an object field by field" in
30
+ [GOOD_PRACTICES.md](GOOD_PRACTICES.md).
25
31
  - `ng update` migration of 19.2.0: migrates your pages to their form and their reference held by signals, their
26
32
  classes and their templates (see the 🚨 entries below and
27
33
  [UPGRADING_V19.md](UPGRADING_V19.md#the-form-of-your-pages-is-a-signal-since-1920)). It lists what it can't
@@ -31,7 +37,8 @@
31
37
  `configs.templateRecommended`: a one-way `[model]` reading the form without `(modelChange)` (the input of the user
32
38
  is lost; a component always disabled, `foehn-input-hidden`, `foehn-table` and a component listening to
33
39
  `(userInput)` excepted), and a `@for` over a list of the form tracked by its item while its rows edit it (the field loses the focus
34
- at every input).
40
+ at every input). Since 19.2.0-beta.22, `no-item-track-in-form-list` also reports the list held by the `model` of a
41
+ component, and a row reading its item at its index (`[model]="model()[i]"`).
35
42
 
36
43
  - [foehn-date-model.type.ts](projects/prestations-ng/src/foehn-input-date/foehn-date-model.type.ts)
37
44
  - New `FoehnDateModel` type, the model of `foehn-input-date` (`(number | null)[]`, the JSON of a
@@ -216,11 +223,19 @@ Please check the [UPGRADING_V19.md](UPGRADING_V19.md) guide for more information
216
223
  - If one of your components reads the value of `model_`, not only `model_ !== undefined`: it is `undefined` as
217
224
  long as the model of the page has had no value to display, and `null` once the page sets it back to
218
225
  `undefined`.
226
+ - `FoehnInputComponent.buildId()` and `buildChildId()` return a `string`, no longer `string | null`: the `name` of a
227
+ component is required. Remove the `?? ''` written after them for the strict mode, which the build now reports
228
+ (NG8102).
219
229
  - `modelChange` of the `foehn-input-*` components is emitted only when the component writes its model (an input of
220
230
  the user, a correction of the model given by the page), not when the page changes the model: true since 19.0.0,
221
231
  now documented in
222
232
  [UPGRADING_V19.md](UPGRADING_V19.md#modelchange-is-emitted-only-when-the-component-writes-its-model), and on the
223
233
  Lifecycle page of the documentation, which said the opposite.
234
+ - `updateNgModel()` with the object or the array the model already holds emits no `modelChange` (the model is a
235
+ signal): true since 19.0.0, now documented in
236
+ [UPGRADING_V19.md](UPGRADING_V19.md#your-components-write-a-new-model). A component modifying its model in place
237
+ and giving it back no longer notifies its page. The list of vehicles of [GOOD_PRACTICES.md](GOOD_PRACTICES.md) now
238
+ shows a complete item, its fields in linked signals, and a list which reads its `model()` and writes a new array.
224
239
  - 🚨 The `onModelChange()` methods which were not the hook of `FoehnInputComponent` are removed or renamed (they are
225
240
  not called by the model anymore):
226
241
  - `foehn-date-picker-button`: `model_`, `onModelChange()` and `updateNgModel()` are removed, they had no effect
package/CONTRIBUTING.md CHANGED
@@ -18,6 +18,14 @@ in an actual prestation: the Dev Tool.
18
18
  To start the Dev Tool, run `npm start`. This will ensure that modifications
19
19
  in both the Dev Tool and the library reload the page.
20
20
 
21
+ ### GitHub Pages documentation
22
+
23
+ Official and beta documentation share the root `404.html` on GitHub Pages.
24
+ Each documentation publication updates that fallback and adds URL restoration
25
+ to both available app indexes, so deep links return to the correct app. Keep
26
+ the fallback and restoration script in sync when changing the publishing flow.
27
+ GitHub Pages still returns HTTP 404 for the initial deep-link request.
28
+
21
29
  ## Testing the library in integration
22
30
 
23
31
  Since version `8`, we can't use native symlink to integrate `prestations-ng` to
package/ESLINT_PLUGIN.md CHANGED
@@ -107,13 +107,13 @@ in a two-way binding.
107
107
 
108
108
  ```ts
109
109
  // ✗ mutates the object inside the signal, no notification
110
- this.model().property = value;
111
- this.model().items.splice(index, 1);
110
+ this.settings().property = value;
111
+ this.settings().items.splice(index, 1);
112
112
 
113
113
  // ✓
114
- this.model.update((current) => ({ ...current, property: value }));
115
- ObjectPathHelper.patchSignal(this.model, ['deep', 'property'], value); // at any depth
116
- this.model.update((current) => ({
114
+ this.settings.update((current) => ({ ...current, property: value }));
115
+ ObjectPathHelper.patchSignal(this.settings, ['deep', 'property'], value); // at any depth
116
+ this.settings.update((current) => ({
117
117
  ...current,
118
118
  items: current.items.filter((_, i) => i !== index),
119
119
  }));
@@ -121,14 +121,20 @@ this.model.update((current) => ({
121
121
 
122
122
  ```html
123
123
  <!-- ✗ -->
124
- <button (click)="model().property = value">…</button>
125
- <button (click)="model().items.splice(index, 1)">…</button>
126
- <input [(ngModel)]="model().property" />
124
+ <button (click)="settings().property = value">…</button>
125
+ <button (click)="settings().items.splice(index, 1)">…</button>
126
+ <input [(ngModel)]="settings().property" />
127
127
 
128
128
  <!-- ✓ -->
129
- <button (click)="model.update((v) => ({ ...v, property: value }))">…</button>
129
+ <button (click)="settings.update((v) => ({ ...v, property: value }))">…</button>
130
130
  ```
131
131
 
132
+ > 💡 The `model` of a component extending `FoehnInputComponent` is the exception: write it
133
+ > with `updateNgModel()` and a new value, or a value at a path with
134
+ > `this.patchNgModel(['deep', 'property'], value)`, never with `set()`, `update()` or
135
+ > `patchSignal()`: `updateNgModel()` also updates `model_`, and leaves the model of a disabled
136
+ > component alone.
137
+
132
138
  All the assignment operators accepted by the Angular expression parser are covered: `=`,
133
139
  `+=`, `-=`, `*=`, `/=`, `%=`, `**=`, `&&=`, `||=`, `??=`.
134
140
 
@@ -142,12 +148,12 @@ Two other ways of writing into the value are covered, in TypeScript — the Angu
142
148
  parser accepts neither:
143
149
 
144
150
  ```ts
145
- delete this.model().users[0];
146
- Object.assign(this.model(), { property: value });
151
+ delete this.settings().users[0];
152
+ Object.assign(this.settings(), { property: value });
147
153
  ```
148
154
 
149
155
  The TypeScript wrappers which keep the value are seen through: `this.form()!.name = value`
150
- and `(this.model() as Model).name = value` are reported as well, as are, in a template,
156
+ and `(this.settings() as Settings).name = value` are reported as well, as are, in a template,
151
157
  `[(ngModel)]="form()!.name"` and `(form()).name = value`.
152
158
 
153
159
  #### Names bound to the value
@@ -157,16 +163,16 @@ the bindings it can resolve exactly, and only those:
157
163
 
158
164
  ```ts
159
165
  // ✗ a variable written once
160
- const users = this.model().users;
166
+ const users = this.settings().users;
161
167
  users.push(user);
162
168
 
163
169
  // ✗ the element parameter of an iteration callback
164
- this.model().users.forEach((user) => (user.done = true));
170
+ this.settings().users.forEach((user) => (user.done = true));
165
171
  ```
166
172
 
167
173
  ```angular-html
168
174
  <!-- ✗ a @for item, bound only inside its own block -->
169
- @for (user of model().users; track user.id) {
175
+ @for (user of settings().users; track user.id) {
170
176
  <input [(ngModel)]="user.done" />
171
177
  <button (click)="user.tags.push(tag)">…</button>
172
178
  }
@@ -177,7 +183,7 @@ this.model().users.forEach((user) => (user.done = true));
177
183
  }
178
184
 
179
185
  <!-- ✗ a @let -->
180
- @let users = model().users;
186
+ @let users = settings().users;
181
187
  <button (click)="users.push(user)">…</button>
182
188
  ```
183
189
 
@@ -191,7 +197,7 @@ stored in a class field, returned and mutated elsewhere:
191
197
 
192
198
  ```ts
193
199
  // not reported: the rule cannot know what `sortInto` does
194
- this.sortInto(this.model().users);
200
+ this.sortInto(this.settings().users);
195
201
  ```
196
202
 
197
203
  That needs interprocedural analysis, which ESLint does not provide; a full type checker
@@ -223,11 +229,11 @@ the normal way to use one. `.required` variants included.
223
229
 
224
230
  Anything that is not a declared signal is left alone as well:
225
231
 
226
- | Expression | Why |
227
- | ------------------------------------ | ------------------------------------------------------------ |
228
- | `this.getConfig().items.push(item)` | `getConfig()` is a plain method, not a signal |
229
- | `map.get(key).files.push(file)` | the call takes arguments, so it is not a signal read |
230
- | `component.model().items.push(item)` | reached through a foreign receiver, not the component itself |
232
+ | Expression | Why |
233
+ | --------------------------------------- | ------------------------------------------------------------ |
234
+ | `this.getConfig().items.push(item)` | `getConfig()` is a plain method, not a signal |
235
+ | `map.get(key).files.push(file)` | the call takes arguments, so it is not a signal read |
236
+ | `component.settings().items.push(item)` | reached through a foreign receiver, not the component itself |
231
237
 
232
238
  Because the rule knows a real signal from an ordinary method, `set` / `add` / `delete` are
233
239
  safe to report: `byId().set(k, v)` mutates the `Map` inside the signal, while `byId.set(m)`
@@ -370,10 +376,27 @@ Applies to **templates only**.
370
376
  form.children; track $index) { … }
371
377
  ```
372
378
 
379
+ The list held by the `model` of a component is reported alike: a component extending
380
+ `FoehnInputComponent` writes a new list in its model, its items replaced (see the list of
381
+ vehicles in [GOOD_PRACTICES.md](GOOD_PRACTICES.md)). Two items equal by value, e.g. two
382
+ empty strings, even collide.
383
+
384
+ ```html
385
+ <!-- ✗ in the template of a component extending FoehnInputComponent<string[]> -->
386
+ @for (text of model(); track text; let i = $index) {
387
+ <foehn-input-textarea
388
+ [model]="model()[i]"
389
+ (modelChange)="updateItem(i, $event)"
390
+ />
391
+ }
392
+ ```
393
+
373
394
  A row edits its item when one of its elements has a `model` read from it
374
- (`[model]="child.firstName"`, `[(model)]="child"`). A list only displayed, or not read from
375
- the form, is left alone. The rule suggests `track $index` (an identifier of the item is
376
- often better: it keeps the row of an item when the list is reordered).
395
+ (`[model]="child.firstName"`, `[(model)]="child"`), or read from the list at the index of
396
+ the row (`[model]="model()[i]"`, `let i = $index`). A list only displayed, or read neither
397
+ from the form nor from the model, is left alone. The rule suggests `track $index` (an
398
+ identifier of the item is often better: it keeps the row of an item when the list is
399
+ reordered).
377
400
 
378
401
  > 💡 The control flow migration of Angular turns a `*ngFor` without `trackBy` into
379
402
  > `track <item>`: after it, check the lists of the form.
package/GOOD_PRACTICES.md CHANGED
@@ -810,6 +810,10 @@ Your component must:
810
810
  > model: a plain field would not be displayed without zone.js, and a `signal()` filled by
811
811
  > `onModelChange` (called by an `effect()`) would follow the model only at the next change
812
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).
813
817
 
814
818
  `input-date.component.ts`
815
819
 
@@ -973,6 +977,78 @@ Each `foehn-input-*` used in your view must:
973
977
  />
974
978
  ```
975
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
+
976
1052
  ### Displaying the global validation of the component
977
1053
 
978
1054
  - Add the code below in the HTML part of your component
@@ -1129,7 +1205,18 @@ demande-page/
1129
1205
 
1130
1206
  **vehicule-item**
1131
1207
 
1132
- `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).
1133
1220
 
1134
1221
  ```html
1135
1222
  <div
@@ -1142,11 +1229,37 @@ demande-page/
1142
1229
  <foehn-validation-alerts [component]="this" />
1143
1230
 
1144
1231
  <div class="row d-flex align-items-end vehicule-infos">
1145
- <!-- ... 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>
1146
1255
 
1147
1256
  <div class="col-md-2 mt-md-0 mt-xs-2">
1148
- <button class="btn btn-danger" (click)="removeVehicule()">
1149
- <!-- (1) -->
1257
+ <button
1258
+ class="btn btn-danger"
1259
+ type="button"
1260
+ (click)="removeVehicule()"
1261
+ >
1262
+ <!-- (2) -->
1150
1263
  {{ 'demande-page.vehicule-remove' | fromDictionary }}
1151
1264
  </button>
1152
1265
  </div>
@@ -1154,8 +1267,9 @@ demande-page/
1154
1267
  </div>
1155
1268
  ```
1156
1269
 
1157
- `vehicule-item.component.ts` contains the removal function, which sends the event up to its
1158
- 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).
1159
1273
 
1160
1274
  > 💡 `@Output() + EventEmitter` are replaced by the `output()` function.
1161
1275
 
@@ -1171,28 +1285,36 @@ parent (the list of items).
1171
1285
  ],
1172
1286
  imports: [
1173
1287
  FoehnValidationAlertsComponent,
1174
- // ... your foehn-input-*
1288
+ FoehnInputTextComponent,
1175
1289
  SdkDictionaryPipe,
1176
1290
  ],
1177
1291
  })
1178
1292
  export class VehiculeItemComponent extends FoehnInputComponent<Vehicule> {
1179
1293
  readonly removedVehicule = output<void>();
1180
1294
 
1295
+ handleUserInput(): void {
1296
+ this.handleChange(this.model() ?? null);
1297
+ }
1298
+
1181
1299
  removeVehicule(): void {
1300
+ // (3)
1182
1301
  this.removedVehicule.emit();
1183
1302
  }
1184
-
1185
- // ...code
1186
1303
  }
1187
1304
  ```
1188
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
+
1189
1309
  **vehicules-list**
1190
1310
 
1191
1311
  `vehicules-list.component.html` contains your `@for` loop (1) and your repeatable component (2), which
1192
1312
  must also send the event up.
1193
1313
 
1194
- > ⚠️ In the `@for` loop, don't forget to put a `track` (unique identifier), otherwise the
1195
- > 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.
1196
1318
 
1197
1319
  ```html
1198
1320
  <div
@@ -1225,19 +1347,19 @@ must also send the event up.
1225
1347
  ></small>
1226
1348
  }
1227
1349
 
1228
- <!-- (1) your @for loop + track (unique identifier) -->
1229
- @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) {
1230
1352
  <!-- (2) your reusable component -->
1231
1353
  <app-vehicule-item
1232
1354
  [name]="name() + '[' + i + ']'"
1233
1355
  [model]="vehicule"
1234
1356
  (modelChange)="updateVehiculesList($event, i)"
1235
- (userInput)="handleUserInput($event, i)"
1357
+ (userInput)="handleUserInput()"
1236
1358
  (removedVehicule)="handleRemovedVehicule(i)"
1237
1359
  />
1238
1360
  }
1239
1361
 
1240
- <button class="btn btn-primary mt-2" (click)="addVehicule()">
1362
+ <button class="btn btn-primary mt-2" type="button" (click)="addVehicule()">
1241
1363
  {{ 'demande-page.vehicule-add' | fromDictionary }}
1242
1364
  </button>
1243
1365
  </div>
@@ -1251,7 +1373,7 @@ must also send the event up.
1251
1373
 
1252
1374
  `vehicules-list.component.ts` in turn sends the event (1) up to the parent (`AbstractPageComponent`)
1253
1375
  and removes the item from the list (2). This is also where you can handle the addition of an
1254
- item (3).
1376
+ item (3). Each change writes a new list in the model (4).
1255
1377
 
1256
1378
  ```ts
1257
1379
  @Component({
@@ -1272,34 +1394,62 @@ item (3).
1272
1394
  export class VehiculesListComponent extends FoehnInputComponent<Vehicule[]> {
1273
1395
  readonly removedVehicule = output<void>(); // (1) event to send up to the parent
1274
1396
 
1275
- // Signal holding your repeatable items, derived from the model: it is replaced, never modified in place
1276
- readonly vehicules = linkedSignal(() => this.model() ?? []);
1277
-
1397
+ // Called by the (modelChange) of an item: the item is replaced in a new list
1278
1398
  updateVehiculesList(vehicule: Vehicule, index: number): void {
1279
- this.vehicules.update((vehicules) =>
1280
- vehicules.map((item, i) => (i === index ? vehicule : item)),
1281
- );
1282
- 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
+ }
1283
1407
  }
1284
1408
 
1285
1409
  handleRemovedVehicule(index: number): void {
1286
1410
  // (2) your function removing the item and sending the event
1287
- this.vehicules.update((vehicules) =>
1288
- vehicules.filter((_vehicule, i) => i !== index),
1289
- ); // removal of the item
1290
- this.getValidValueAndUpdateNgModel(); // Update of your model
1411
+ this.updateVehicules(
1412
+ (this.model() ?? []).filter((_vehicule, i) => i !== index),
1413
+ );
1291
1414
  this.removedVehicule.emit(); // (1) the event is sent up
1292
1415
  }
1293
1416
 
1294
1417
  addVehicule(): void {
1295
1418
  // (3) Handling of the addition of an item
1296
- // ...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;
1297
1438
  }
1298
1439
  }
1299
1440
  ```
1300
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
+ >
1301
1451
  > 💡 No need to define a dedicated `trackByFn` anymore: the new `@for` syntax directly uses
1302
- > the `track` expression (here `vehicule.id`).
1452
+ > the `track` expression (here `$index`).
1303
1453
 
1304
1454
  **demande-page**
1305
1455
 
@@ -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:
package/UPGRADING_V19.md CHANGED
@@ -1465,6 +1465,37 @@ fill another field once the form is loaded, often behind a guard on `undefined`)
1465
1465
  work where the page writes the form: after its loading (`GesdemEventService.formInitializationObservable()`, which
1466
1466
  emits the loaded form), after a prefill, after a reset.
1467
1467
 
1468
+ ### Your components write a new model
1469
+
1470
+ In v18, `updateNgModel(value)` emitted `modelChange` whatever the value. Since 19.0.0, the model is a signal, which
1471
+ ignores the same value: `updateNgModel()` with the object or the array the model already holds changes nothing, and no
1472
+ `modelChange` is emitted. A component extending `FoehnInputComponent` which keeps its model in a field
1473
+ (`onModelChange()` → `this.items = value`), modifies it in place (`this.items[i] = item`, `push()`, `splice()`,
1474
+ `[(model)]="item.x"`) and gives it back (`updateNgModel(this.items)`, a `getValidValue()` returning `this.item`) no
1475
+ longer notifies its page: the `(modelChange)` handlers of the page aren't called, and since 19.2.0, its `patchForm()`
1476
+ neither. The data seems saved as long as the object modified in place is the one of the page, and is lost as soon as
1477
+ the component works on another one (e.g. an object it created or replaced itself).
1478
+
1479
+ Search your components extending `FoehnInputComponent` for a `getValidValue()` returning a field (`return this.items;`,
1480
+ `return this.item;`) and for the writes in place of their model, and give `updateNgModel()` a new object or array:
1481
+
1482
+ - a list reads its `model()` directly, replaces an item with `patchNgModel([index], item)`, and adds or removes one
1483
+ with a new array (`[...list, item]`, `filter()`);
1484
+ - a component editing an object as is reads its `model()` directly, and writes each field with
1485
+ `patchNgModel(['address', 'street'], $event)` (since 19.2.0-beta.22), which keeps the fields it doesn't display (an
1486
+ id, a tracking index). Override `emptyModel()` when the page can give no object;
1487
+ - a component transforming its model (e.g. a date in three fields) keeps its linked signals, and its
1488
+ `getValidValue()` builds a new value.
1489
+
1490
+ Before 19.2.0-beta.22, write `patchNgModel()` yourself:
1491
+ `this.updateNgModel(ObjectPathHelper.patch(this.model() ?? new Owner(), path, value))`. See "Creating a reusable
1492
+ component", "Editing an object field by field" and the list of vehicles in [GOOD_PRACTICES.md](GOOD_PRACTICES.md).
1493
+
1494
+ The inputs inherited from `FoehnInputComponent` (`name`, `label`, `required`, `disabled`...) are signals too: read
1495
+ `this.name()`. `` `${this.name}[${index}]` `` and `this.name + '[0]'` compile, but give the signal, not its value
1496
+ (`[Input Signal: vehicules]` in development), e.g. a prefix of errors which matches no error. `restrict-template-expressions`
1497
+ (`configs.tsRecommended`, since 19.2.0) reports the template literals.
1498
+
1468
1499
  ### Strict mode (optional when migrating large projects but recommended)
1469
1500
 
1470
1501
  - In your `tsconfig.json` file, add `"strict": true` in `compilerOptions` and remove `alwaysStrict`, `noImplicitThis`, `strictBindCallApply` and `strictFunctionTypes` as they are already included in `strict` mode.
@@ -1677,10 +1708,16 @@ In the classes:
1677
1708
  + this.patchForm(['children'], [...(this.form()!.children ?? []), child]);
1678
1709
  - if (this.form) {
1679
1710
  - this.http.post('api/check', this.form.amount);
1711
+ - this.pdf = this.gesdemService.pdf(this.form);
1680
1712
  + if (this.form()) {
1681
1713
  + this.http.post('api/check', this.form()!.amount);
1714
+ + this.pdf = this.gesdemService.pdf(this.form()!);
1682
1715
  ```
1683
1716
 
1717
+ A read narrowed by a guard (`if (this.form)`, `this.form ? ... : ...`, `this.form && ...`,
1718
+ `if (!this.form) { return; }`) gets a `!`: TypeScript narrows `this.form`, but not the call `this.form()`. The same for
1719
+ `reference`, `itemToEdit` and `itemIndex`.
1720
+
1684
1721
  #### Check by hand
1685
1722
 
1686
1723
  The migration leaves untouched, and lists with their file and line, what it can't rewrite. The compiler reports it
@@ -1698,7 +1735,16 @@ Also check:
1698
1735
  `component.form.x` becomes `component.form()!.x` (the compiler reports them);
1699
1736
  - the components receiving the form, or an object of it, as an input and modifying it: they modify the value of the
1700
1737
  signal in place, the page isn't notified. Give them an output, and let the page write with `patchForm()`;
1701
- - the `markForCheck()` called after a write of the form (zoneless): they are useless now, remove them.
1738
+ - the services and the methods receiving the form, or an object of it, as an argument and modifying it, e.g. an
1739
+ `enrichWithSessionInfoData(form)` filling it with the session in the callback of `prefillForm()`: the same, and
1740
+ neither the migration nor `no-direct-signal-mutation` follow the form into them. Let them return the values, and
1741
+ the page write them with `patchForm()` or `form.update()`;
1742
+ - the fields whose type differs from the model of their component, e.g. a date typed `number[] | null`: `[(model)]`
1743
+ didn't compare them, `patchForm()` does, and the build reports its `$event` (TS2345). Type the field as the model:
1744
+ `FoehnDateModel | null` for `foehn-input-date`, `FoehnDateTimeModel | null` for `foehn-input-date-time`;
1745
+ - the `markForCheck()` called after a write of the form or of the reference (zoneless): they are useless now, remove
1746
+ them, unless they notify another field. The migration lists those of a function writing the form or the reference,
1747
+ not those of a callback given to a service.
1702
1748
 
1703
1749
  `no-direct-signal-mutation` reports the writes in place left (`this.form()!.x = 1`, `form.children.push(child)`),
1704
1750
  `[(model)]="form.x"` inside `@if (form(); as form)` included.