@dsivd/prestations-ng 19.2.0-beta.21 → 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.
- package/CHANGELOG.md +16 -1
- package/ESLINT_PLUGIN.md +48 -25
- package/GOOD_PRACTICES.md +179 -29
- package/INTRODUCTION_ANGULAR_SIGNALS.md +29 -2
- package/UPGRADING_V19.md +47 -1
- package/eslint/rules/no-item-track-in-form-list.mjs +85 -12
- package/fesm2022/dsivd-prestations-ng.mjs +43 -2
- package/fesm2022/dsivd-prestations-ng.mjs.map +1 -1
- package/package.json +1 -1
- package/schematics/utility/form-signal/class-migration.js +290 -15
- package/src/eslint/rules/__tests__/no-item-track-in-form-list.test.mjs +107 -0
- package/src/eslint/rules/no-item-track-in-form-list.mjs +85 -12
- package/types/dsivd-prestations-ng.d.ts +116 -84
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/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.
|
|
111
|
-
this.
|
|
110
|
+
this.settings().property = value;
|
|
111
|
+
this.settings().items.splice(index, 1);
|
|
112
112
|
|
|
113
113
|
// ✓
|
|
114
|
-
this.
|
|
115
|
-
ObjectPathHelper.patchSignal(this.
|
|
116
|
-
this.
|
|
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)="
|
|
125
|
-
<button (click)="
|
|
126
|
-
<input [(ngModel)]="
|
|
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)="
|
|
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.
|
|
146
|
-
Object.assign(this.
|
|
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.
|
|
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.
|
|
166
|
+
const users = this.settings().users;
|
|
161
167
|
users.push(user);
|
|
162
168
|
|
|
163
169
|
// ✗ the element parameter of an iteration callback
|
|
164
|
-
this.
|
|
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
|
|
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 =
|
|
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.
|
|
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
|
|
227
|
-
|
|
|
228
|
-
| `this.getConfig().items.push(item)`
|
|
229
|
-
| `map.get(key).files.push(file)`
|
|
230
|
-
| `component.
|
|
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"`)
|
|
375
|
-
the
|
|
376
|
-
|
|
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
|
-
`
|
|
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
|
-
|
|
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
|
|
1149
|
-
|
|
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`
|
|
1158
|
-
|
|
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
|
-
|
|
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
|
|
1195
|
-
>
|
|
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
|
|
1229
|
-
@for (vehicule of
|
|
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(
|
|
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
|
-
//
|
|
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.
|
|
1280
|
-
|
|
1281
|
-
|
|
1282
|
-
|
|
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.
|
|
1288
|
-
|
|
1289
|
-
);
|
|
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
|
-
|
|
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 `
|
|
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
|
-
|
|
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
|
|
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.
|