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

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 (39) hide show
  1. package/ANGULAR_SIGNALS.md +4 -0
  2. package/CHANGELOG.md +98 -3
  3. package/CONTRIBUTING.md +2 -2
  4. package/ESLINT_PLUGIN.md +103 -8
  5. package/GOOD_PRACTICES.md +79 -29
  6. package/UPGRADING_V19.md +187 -31
  7. package/eslint/configs/template-rules.mjs +5 -0
  8. package/eslint/configs/ts-recommended.mjs +4 -0
  9. package/eslint/form-reads.mjs +63 -0
  10. package/eslint/rules/index.mjs +4 -0
  11. package/eslint/rules/no-direct-signal-mutation.mjs +57 -19
  12. package/eslint/rules/no-item-track-in-form-list.mjs +99 -0
  13. package/eslint/rules/no-uninvoked-signal-in-template.mjs +8 -3
  14. package/eslint/rules/require-model-change.mjs +89 -0
  15. package/eslint/template-ast.mjs +12 -2
  16. package/fesm2022/dsivd-prestations-ng.mjs +907 -692
  17. package/fesm2022/dsivd-prestations-ng.mjs.map +1 -1
  18. package/package.json +1 -1
  19. package/schematics/migration-collection.json +5 -0
  20. package/schematics/ng-update/migrations/update-19_2_0/index.js +39 -0
  21. package/schematics/utility/form-signal/class-migration.js +396 -0
  22. package/schematics/utility/form-signal/edits.js +34 -0
  23. package/schematics/utility/form-signal/form-signal-migration.js +184 -0
  24. package/schematics/utility/form-signal/page-classes.js +129 -0
  25. package/schematics/utility/form-signal/template-migration.js +666 -0
  26. package/src/eslint/configs/template-rules.mjs +5 -0
  27. package/src/eslint/configs/ts-recommended.mjs +4 -0
  28. package/src/eslint/form-reads.mjs +63 -0
  29. package/src/eslint/rules/__tests__/no-direct-signal-mutation.test.mjs +58 -0
  30. package/src/eslint/rules/__tests__/no-item-track-in-form-list.test.mjs +127 -0
  31. package/src/eslint/rules/__tests__/no-uninvoked-signal-in-template.test.mjs +6 -0
  32. package/src/eslint/rules/__tests__/require-model-change.test.mjs +93 -0
  33. package/src/eslint/rules/index.mjs +4 -0
  34. package/src/eslint/rules/no-direct-signal-mutation.mjs +57 -19
  35. package/src/eslint/rules/no-item-track-in-form-list.mjs +99 -0
  36. package/src/eslint/rules/no-uninvoked-signal-in-template.mjs +8 -3
  37. package/src/eslint/rules/require-model-change.mjs +89 -0
  38. package/src/eslint/template-ast.mjs +12 -2
  39. package/types/dsivd-prestations-ng.d.ts +234 -35
@@ -866,6 +866,10 @@ this.address.update((current) => ({
866
866
  ...current,
867
867
  locality: { ...current.locality, name: 'newName' },
868
868
  }));
869
+
870
+ // đŸŸĸ The same with prestations-ng, at any depth: the objects along the path are copied,
871
+ // the path is checked by TypeScript, and the signal notifies only when the value changes
872
+ ObjectPathHelper.patchSignal(this.address, ['locality', 'name'], 'newName');
869
873
  ```
870
874
 
871
875
  #### 8b. Two-way binding directly on an array element inside `@for`
package/CHANGELOG.md CHANGED
@@ -10,10 +10,43 @@
10
10
 
11
11
  ### Added
12
12
 
13
+ - [object-path.helper.ts](projects/prestations-ng/src/helpers/object-path.helper.ts)
14
+ - New `ObjectPathHelper`: reads and writes a value at a path of any object, without modifying it: a write copies
15
+ the objects and arrays along the path (with their prototype), keeps the others as they are, and gives the object
16
+ itself when the value is already there.
17
+ - `get(object, path)`, `patch(object, path, value)` and `patchSignal(signal, path, value)` (for a signal holding
18
+ an object: its readers are notified only when the value changes) take a path checked by TypeScript, typed with
19
+ the new `ObjectPath<T>` (`['address', 'street']`, `['children', 0, 'firstName']`, the paths of each member of a
20
+ union) and `ObjectPathValue<T, P>`.
21
+ - `getByKeys(object, keys)` and `patchByKeys(object, keys, value)` take keys known at runtime only
22
+ (`'address.street'`, or a list of keys), not checked.
23
+ - `patchForm()`, `patchItem()`, `PendingUploadService`, the custom errors of the street of `foehn-input-address`
24
+ and the elements of `foehn-select`, `foehn-radio`, `foehn-checkbox` and the autocompletes use it.
25
+ - `ng update` migration of 19.2.0: migrates your pages to their form and their reference held by signals, their
26
+ classes and their templates (see the 🚨 entries below and
27
+ [UPGRADING_V19.md](UPGRADING_V19.md#the-form-of-your-pages-is-a-signal-since-1920)). It lists what it can't
28
+ migrate, and running it again changes nothing.
29
+ - 🚨 ESLint rules [`require-model-change`](ESLINT_PLUGIN.md#require-model-change) and
30
+ [`no-item-track-in-form-list`](ESLINT_PLUGIN.md#no-item-track-in-form-list), in `configs.templateRules` and
31
+ `configs.templateRecommended`: a one-way `[model]` reading the form without `(modelChange)` (the input of the user
32
+ is lost; a component always disabled, `foehn-input-hidden`, `foehn-table` and a component listening to
33
+ `(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).
35
+
13
36
  - [foehn-date-model.type.ts](projects/prestations-ng/src/foehn-input-date/foehn-date-model.type.ts)
14
37
  - New `FoehnDateModel` type, the model of `foehn-input-date` (`(number | null)[]`, the JSON of a
15
38
  `LenientLocalDate` of prestations-be), to type the date fields of your forms, e.g.
16
39
  `birthDate: FoehnDateModel | null = null;`.
40
+ - `DateHelper.isValid()`, `isToday()` and `toDayjsFromNumberArray()` accept it, `null` and `undefined`
41
+ included: no cast in a strict project. A date with a part not entered is still neither valid nor today, and
42
+ gives `null`.
43
+ - [foehn-date-time-model.type.ts](projects/prestations-ng/src/foehn-input-date-time/foehn-date-time-model.type.ts)
44
+ - New `FoehnDateTimeModel` type, the model of `foehn-input-date-time` (`(number | null)[]`: year, month, day,
45
+ hour, minute, the JSON of a `LenientLocalDateTime` of prestations-be).
46
+ - The `displayDate` pipe, `DateHelper.toDateFromNumberArray()`, `arrayToDisplayDateDMY()`, `isValid()` and
47
+ `isToday()` accept it, as well as a `FoehnDateModel`. The new `DateHelper.hasTime()` tells whether a date-time
48
+ has its time entered.
49
+ `DateHelper.leftPad()` accepts `null` and `undefined` (it already returned `''`).
17
50
  - [eslint/configs/spec-ts-recommended.mjs](projects/prestations-ng/src/eslint/configs/spec-ts-recommended.mjs)
18
51
  - New `prestationsNg.configs.specTsRecommended` ESLint config for the Vitest specs, to use in the `extends` of a
19
52
  `**/*.spec.ts` block: the `recommended` config of `@vitest/eslint-plugin`, which also counts the assertions of
@@ -143,6 +176,31 @@ Please check the [UPGRADING_V19.md](UPGRADING_V19.md) guide for more information
143
176
  - `epayment-form` (`SdkEpaymentComponent`): `failureModalDisplayed`, `redirectModalDisplayed`
144
177
  - `captcha` (`SdkRecaptchaComponent`): `isLoaded`, `hasLoadingError`
145
178
  - `redirector` (`RedirectComponent`): `counter`
179
+ - 🚨 `AbstractPageComponent`: `reference` is now a signal. Read it with `reference()` in your pages and their
180
+ templates, and write it with `reference.set()`. A template, a `computed()` or an `effect()` reading it follows the
181
+ reference, also when your page sets it, without `markForCheck()`. A page declaring its own `reference` field no
182
+ longer compiles: remove it. The `ng update` migration rewrites your pages, see
183
+ [UPGRADING_V19.md](UPGRADING_V19.md#reference-of-your-pages-is-a-signal-since-1920).
184
+ - 🚨 ESLint: `configs.tsRecommended` enables `@typescript-eslint/restrict-template-expressions`. A template literal
185
+ only takes strings, numbers, booleans, `null`, `undefined`, `any` and `RegExp`: a signal not called
186
+ (`` `api/${this.reference}` ``) or an object turned into text by its `toString()` is reported. See
187
+ [ESLINT_PLUGIN.md](ESLINT_PLUGIN.md#the-typescript-counterpart).
188
+ - 🚨 `AbstractPageComponent`: `form` is now a signal (`WritableSignal<T | null | undefined>`). Read it with `form()`,
189
+ never modify its value in place: write it with the new `patchForm(path, value)`
190
+ (`[model]="form.firstName" (modelChange)="patchForm(['firstName'], $event)"`), `form.set()` or `form.update()`. A
191
+ template, a `computed()` or an `effect()` reading it follows every input of the user, and no `markForCheck()` is
192
+ needed after a write anymore. The `ng update` migration rewrites your pages, see
193
+ [UPGRADING_V19.md](UPGRADING_V19.md#the-form-of-your-pages-is-a-signal-since-1920).
194
+ - 🚨 `AbstractListDetailPageComponent`: the abstract `getListPath()` (the path of the list in the form) replaces the
195
+ abstract `getList()`, which reads the list at that path. `list`, `itemIndex` and `itemToEdit` are now signals. The
196
+ item edited is written with the new `patchItem(path, value)`, `updateItem(update)` (several fields in one write)
197
+ and `setItem(item)`. A new item is added without modifying the list of the form in place.
198
+ - `PendingUploadService` writes the documents uploaded with the form into a new form, instead of modifying the form
199
+ in place.
200
+ - 🚨 ESLint rule [`no-direct-signal-mutation`](ESLINT_PLUGIN.md#no-direct-signal-mutation) sees through the
201
+ TypeScript wrappers keeping the value: `this.form()!.name = value` and `(this.model() as Model).name = value` are
202
+ now reported. In a template, it sees through `!` and the parentheses, and follows the alias of an `@if`:
203
+ `[(model)]="form.name"` inside `@if (form(); as form)` is now reported.
146
204
  - The lifecycle hooks that have nothing left to do are removed: `ngOnChanges()` of
147
205
  `foehn-agenda-timeslot-panel` and `foehn-table`, `ngAfterViewInit()` of `foehn-list-summary`, `ngOnInit()` of
148
206
  `foehn-radio` and `foehn-input-textarea`, `ngOnInit()` and `ngOnDestroy()` of `captcha`.
@@ -163,6 +221,14 @@ Please check the [UPGRADING_V19.md](UPGRADING_V19.md) guide for more information
163
221
  now documented in
164
222
  [UPGRADING_V19.md](UPGRADING_V19.md#modelchange-is-emitted-only-when-the-component-writes-its-model), and on the
165
223
  Lifecycle page of the documentation, which said the opposite.
224
+ - 🚨 The `onModelChange()` methods which were not the hook of `FoehnInputComponent` are removed or renamed (they are
225
+ not called by the model anymore):
226
+ - `foehn-date-picker-button`: `model_`, `onModelChange()` and `updateNgModel()` are removed, they had no effect
227
+ (`model_` was never read).
228
+ - `foehn-date-picker`: `model_` is removed (never read), `onModelChange()` is now private (`syncWithModel()`).
229
+ - `numberCurrencyFormatter`: `onModelChange()` is now private (`formatModel()`), and the directive no longer
230
+ listens to the `modelChange` of its host: its `effect()` already formats every model, the ones written by the
231
+ host were formatted twice.
166
232
  - `SdkDictionaryService.getKeySync()` reads a signal: a `computed()` or a template calling it is refreshed
167
233
  when the dictionary is (re)loaded, e.g. when the language changes.
168
234
  - `foehn-autocomplete` and `foehn-multiselect-autocomplete`: the value to display, its reset, the default
@@ -183,9 +249,28 @@ Please check the [UPGRADING_V19.md](UPGRADING_V19.md) guide for more information
183
249
 
184
250
  - `AbstractMenuPageComponent.ngZone` is no longer used and will be removed: `NgZone.onStable` never emits
185
251
  without zone.js.
186
-
187
- ### Fixed
188
-
252
+ - `ObjectHelper.getNestedProperty(obj, key)` will be removed: use `ObjectPathHelper.getByKeys(obj, key)`, which it
253
+ now calls (see Fixed).
254
+
255
+ ### Fixed
256
+
257
+ - 🚨 `ObjectHelper.getNestedProperty()`, and the keys given as text to `elementValue`, `elementLabel`, `elementGroup`,
258
+ `elementDisabled` and `elementSuggestionLabel` of `foehn-select`, `foehn-radio`, `foehn-checkbox` and the
259
+ autocompletes, read the value at the path of the key (`'country.name'`): a value which is an object, or a getter of
260
+ a class, is no longer `undefined`, and a nested key is no longer looked up in another nested object holding the same
261
+ key (`'country.name'` gave the `name` of the first nested object having one). A value `null` is no longer
262
+ `undefined` either: an element `{ value: null }` is now selected by a model `null` (e.g. sent by the backend), no
263
+ longer by a model `undefined` (e.g. a field missing from the JSON), and choosing it writes `null` into the model, no
264
+ longer `undefined`.
265
+ - 🚨 `DateHelper.isValid()` also checks the time of a date-time (5 parts or more, e.g. the model of
266
+ `foehn-input-date-time`), as `LenientLocalDateTime.isValid()` of prestations-be: an hour (0 to 23) and a minute (0
267
+ to 59) are required. It only checked the date: a date-time without its time, or at 25:00, was valid. Check your
268
+ calls on a date-time. `isToday()` still considers only the date.
269
+ - The `displayDate` pipe, `DateHelper.toDateFromNumberArray()` and `arrayToDisplayDateDMY()` no longer give a wrong
270
+ date for a date with a part not entered (e.g. a draft saved with an incomplete date): `[2020, null, null]` was
271
+ displayed `30.11.2019`, it now gives nothing. A date-time without its time gives only the date (it displayed
272
+ `00:00:00`), and an empty array gives nothing (it threw an error). `DateHelper.isToday()`: a date which does not
273
+ exist is no longer today (the 30.02.2026 was the 02.03.2026).
189
274
  - `AbstractPageComponent` and `AbstractPageFromMenuComponent`: a second click on "next" or "transmit" while the next
190
275
  page is loading (lazy loaded route, resolver, async guard) no longer saves again and skips the next page:
191
276
  `send()`, `sendAndTransmit()` and `transmit()` are ignored until the navigation to the next page ends. Pages
@@ -226,6 +311,11 @@ Please check the [UPGRADING_V19.md](UPGRADING_V19.md) guide for more information
226
311
  component (e.g. prefilled with `SessionInfoWithApplicationService.prefillForm()` for a connected user) is no
227
312
  longer overwritten by the model with the default country only; the default country and the clean-up of the model
228
313
  are applied after the next rendering, from the latest model.
314
+ - `foehn-input-address` in Switzerland only (`isOnlySwiss`): an address given by the page without country after the
315
+ initialization of the component (e.g. a form loaded from the backend) gets the Swiss country again, as in v18: it
316
+ kept `country: null` until the user changed a field. The default country is checked again for every model given by
317
+ the page, and written only when it changes the model: an identical model is no longer written back (one
318
+ `modelChange` less), and an address without any value to display is left as it is.
229
319
  - `foehn-input-address`: the streets and the street numbers of an address given by the page are loaded again, as in
230
320
  v18. Since 19.0.0, they were only loaded once the user chose a locality and a street (the autocompletes no longer
231
321
  emit `modelChange` for a model given by the page), and a locality given with its `zipCodeId` only (without
@@ -295,6 +385,11 @@ Please check the [UPGRADING_V19.md](UPGRADING_V19.md) guide for more information
295
385
  - `foehn-feedback-notification`: an error of `api/feedbacknotification/queryparams/{reference}` is logged and the
296
386
  links are displayed without the feedback url, it reached the `ErrorHandler` as unhandled.
297
387
  - The npm package no longer contains its own archive (`dsivd-prestations-ng-<version>.tgz`).
388
+ - ESLint rules [`no-direct-signal-mutation`](ESLINT_PLUGIN.md#no-direct-signal-mutation) and
389
+ [`no-uninvoked-signal-in-template`](ESLINT_PLUGIN.md#no-uninvoked-signal-in-template): an explicit `(xChange)`
390
+ handler is no longer taken for the target of a two-way binding `[(x)]`. `no-direct-signal-mutation` reported
391
+ `(modelChange)="updateModel()"` in a template shared by several components (its component file not found), and
392
+ `no-uninvoked-signal-in-template` let `(valueChange)="mySignal"` through.
298
393
 
299
394
  ## [19.1.1]
300
395
 
package/CONTRIBUTING.md CHANGED
@@ -236,8 +236,8 @@ mechanism inherited from zone.js:
236
236
  object. No copy is then needed "so that the change detection sees a new reference".
237
237
  - Asynchronous work: set a signal in the callback, or convert the `Observable` with `toSignal()` where it is
238
238
  displayed. The services keep returning `Observable`s.
239
- - `markForCheck()` only for a state that can't be a signal (e.g. the `form` of `AbstractPageComponent`, written by
240
- the projects).
239
+ - `markForCheck()` only for a state that can't be a signal (e.g. the plain fields that the pages of the projects set
240
+ when their form is loaded: `AbstractPageComponent` marks the page then).
241
241
  - Act on the rendered DOM (focus, scroll, measure) with `afterNextRender(..., { injector })`, never with
242
242
  `setTimeout()` or `NgZone`.
243
243
  - `effect()` as a last resort, with `untracked()` for what isn't a trigger. Never use it to copy a signal into another
package/ESLINT_PLUGIN.md CHANGED
@@ -48,12 +48,12 @@ from the config. Inline templates written in a `@Component` are covered too, thr
48
48
 
49
49
  ## The configs
50
50
 
51
- | Config | Target | Contents |
52
- | ----------------------------- | ----------- | -------------------------------------------------------------- |
53
- | `configs.tsRecommended` | `**/*.ts` | the baselines, the house style, and `tsRules` |
54
- | `configs.templateRecommended` | `**/*.html` | the baselines, the house style, and `templateRules` |
55
- | `configs.tsRules` | `**/*.ts` | `no-direct-signal-mutation` |
56
- | `configs.templateRules` | `**/*.html` | `no-direct-signal-mutation`, `no-uninvoked-signal-in-template` |
51
+ | Config | Target | Contents |
52
+ | ----------------------------- | ----------- | -------------------------------------------------------------------------------------------------------------------- |
53
+ | `configs.tsRecommended` | `**/*.ts` | the baselines, the house style, and `tsRules` |
54
+ | `configs.templateRecommended` | `**/*.html` | the baselines, the house style, and `templateRules` |
55
+ | `configs.tsRules` | `**/*.ts` | `no-direct-signal-mutation` |
56
+ | `configs.templateRules` | `**/*.html` | `no-direct-signal-mutation`, `no-uninvoked-signal-in-template`, `require-model-change`, `no-item-track-in-form-list` |
57
57
 
58
58
  The `*Recommended` presets are what a project normally extends. On top of the rules written
59
59
  here they bring:
@@ -61,8 +61,10 @@ here they bring:
61
61
  - the baselines — `eslint.configs.recommended`, `typescript-eslint` recommended and
62
62
  stylistic, `angular-eslint` recommended, and for templates its accessibility set;
63
63
  - the house style — naming and selector conventions, import ordering
64
- (`simple-import-sort`, `import-x`), rxjs conventions, and the signal rules of
65
- `angular-eslint` (`no-uncalled-signals`, `prefer-signals`, `prefer-signal-model`).
64
+ (`simple-import-sort`, `import-x`), rxjs conventions, the signal rules of
65
+ `angular-eslint` (`no-uncalled-signals`, `prefer-signals`, `prefer-signal-model`), and
66
+ `@typescript-eslint/restrict-template-expressions` (see
67
+ [The TypeScript counterpart](#the-typescript-counterpart)).
66
68
 
67
69
  Use `tsRules` / `templateRules` instead when a project supplies its own style and only wants
68
70
  the rules of this library. They register the plugin and nothing else, so you keep control of
@@ -110,6 +112,7 @@ this.model().items.splice(index, 1);
110
112
 
111
113
  // ✓
112
114
  this.model.update((current) => ({ ...current, property: value }));
115
+ ObjectPathHelper.patchSignal(this.model, ['deep', 'property'], value); // at any depth
113
116
  this.model.update((current) => ({
114
117
  ...current,
115
118
  items: current.items.filter((_, i) => i !== index),
@@ -143,6 +146,10 @@ delete this.model().users[0];
143
146
  Object.assign(this.model(), { property: value });
144
147
  ```
145
148
 
149
+ 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,
151
+ `[(ngModel)]="form()!.name"` and `(form()).name = value`.
152
+
146
153
  #### Names bound to the value
147
154
 
148
155
  A mutation is rarely written on the signal read itself. The rule follows the value through
@@ -164,6 +171,11 @@ this.model().users.forEach((user) => (user.done = true));
164
171
  <button (click)="user.tags.push(tag)">â€Ļ</button>
165
172
  }
166
173
 
174
+ <!-- ✗ the alias of an @if, bound only inside its own branch -->
175
+ @if (form(); as form) {
176
+ <foehn-input-text name="name" [(model)]="form.name" />
177
+ }
178
+
167
179
  <!-- ✗ a @let -->
168
180
  @let users = model().users;
169
181
  <button (click)="users.push(user)">â€Ļ</button>
@@ -295,6 +307,77 @@ found without declaring anything.
295
307
  | `[(value)]="mySignal"` | a writable signal is two-way bound **without** parentheses, Angular calls `.set()` itself |
296
308
  | `#ref`, `@for` items, `@if â€Ļ as`, `@let`, `let-x`, `$index`â€Ļ | template-local names shadow the class members |
297
309
 
310
+ ### `require-model-change`
311
+
312
+ Reports a `foehn-*` component given a field of the form of the page with a one-way `[model]`
313
+ and no `(modelChange)`. The component changes its own model only: what the user enters never
314
+ reaches the form, and is lost when the form is saved.
315
+
316
+ Applies to **templates only**.
317
+
318
+ ```html
319
+ <!-- ✗ the input of the user is lost -->
320
+ <foehn-input-text [model]="form.firstName" />
321
+
322
+ <!-- ✓ -->
323
+ <foehn-input-text
324
+ [model]="form.firstName"
325
+ (modelChange)="patchForm(['firstName'], $event)"
326
+ />
327
+ ```
328
+
329
+ Only the models read from the form are checked: `form()`, `form.firstName`, and the names
330
+ bound to it by `@if (form(); as form)`, `@let form = this.form()` or
331
+ `@for (child of form.children; â€Ļ)`. A one-way `[model]` is legitimate elsewhere (a table
332
+ displaying a list, a menu...). `[(model)]` declares both bindings and is never reported.
333
+
334
+ Not reported either, as the input of the user can't be lost:
335
+
336
+ - a component always disabled, `disabled="true"` or `[disabled]="true"` (a disabled component
337
+ doesn't write its model), unless it is given `updateModelWhenDisabled`;
338
+ - `foehn-input-hidden` and `foehn-table`, which never write their model;
339
+ - a component listening to `(userInput)`, whose handler writes the form.
340
+
341
+ A `[disabled]` depending on a condition is reported: once the component is enabled, the input of
342
+ the user would be lost. A bare `disabled` is reported too: it gives `''`, which doesn't disable
343
+ the component.
344
+
345
+ ```html
346
+ <!-- ✓ displayed only -->
347
+ <foehn-input-text [model]="form.reference" [disabled]="true" />
348
+ ```
349
+
350
+ ### `no-item-track-in-form-list`
351
+
352
+ Reports a `@for` over a list of the form whose rows edit their item, tracked by the item
353
+ itself (`track child`, `track $any(child)`). Writing a field of an item with `patchForm()`
354
+ or `patchItem()` replaces the item with a copy: its row is destroyed and created again at
355
+ every input, and the field being edited loses the focus.
356
+
357
+ Applies to **templates only**.
358
+
359
+ ```html
360
+ <!-- ✗ the field loses the focus at every input -->
361
+ @for (child of form.children; track child) {
362
+ <foehn-input-text
363
+ [model]="child.firstName"
364
+ (modelChange)="patchForm(['children', $index, 'firstName'], $event)"
365
+ />
366
+ }
367
+
368
+ <!-- ✓ -->
369
+ @for (child of form.children; track child.id) { â€Ļ } @for (child of
370
+ form.children; track $index) { â€Ļ }
371
+ ```
372
+
373
+ 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).
377
+
378
+ > 💡 The control flow migration of Angular turns a `*ngFor` without `trackBy` into
379
+ > `track <item>`: after it, check the lists of the form.
380
+
298
381
  ## The TypeScript counterpart
299
382
 
300
383
  `@angular-eslint/no-uncalled-signals` covers the same class of bug **in TypeScript**, using
@@ -310,3 +393,15 @@ are complementary, not redundant.
310
393
 
311
394
  It only reports signals used in logic positions (`if`, `!x`, `&&`, `===`, `.length`â€Ļ), not a
312
395
  bare `const x = mySignal`.
396
+
397
+ Nor a template literal: `` `api/${this.reference}/pdf-sections` `` compiles, and gives the
398
+ signal itself as text (`[Signal: â€Ļ]`, or the source of a function in production) instead of
399
+ its value. `configs.tsRecommended` also enables
400
+ `@typescript-eslint/restrict-template-expressions`, which only lets strings, numbers,
401
+ booleans, `null`, `undefined`, `any` and `RegExp` into a template literal: a signal not
402
+ called is reported, as is an object turned into text by its `toString()`. With
403
+ `configs.tsRules` you enable it yourself (it requires type information too):
404
+
405
+ ```ts
406
+ '@typescript-eslint/restrict-template-expressions': 'error',
407
+ ```
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
 
@@ -997,7 +1035,7 @@ Each `foehn-input-*` used in your view must:
997
1035
 
998
1036
  > âš ī¸ Don't forget to put a `track` with a unique identifier in the `@for` loop, otherwise the
999
1037
  > 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`.
1038
+ > by `$index`: never by object a list of the form whose rows edit their item (see "Binding the fields of the form").
1001
1039
 
1002
1040
  > â„šī¸ In an Angular `@for` loop with a `FoehnInputComponent` component, if you validate your
1003
1041
  > form, the errors returned are synchronized with the index of your components repeated in the
@@ -1024,7 +1062,7 @@ your `AbstractPageComponent`. This method will contain the following code:
1024
1062
  * if an inventory item that was in error is removed, this prevents the error to be displayed
1025
1063
  * to the next item that has taken it's index
1026
1064
  */
1027
- this._gesdemService.validate(this.form).pipe(first()).subscribe();
1065
+ this._gesdemService.validate(this.form()).pipe(first()).subscribe();
1028
1066
  ```
1029
1067
 
1030
1068
  Here is an example of a form page containing this method (1):
@@ -1064,7 +1102,7 @@ export class YourPageComponent
1064
1102
  * if an inventory item that was in error is removed, this prevents the error to be displayed
1065
1103
  * to the next item that has taken it's index
1066
1104
  */
1067
- this._gesdemService.validate(this.form).pipe(first()).subscribe();
1105
+ this._gesdemService.validate(this.form()).pipe(first()).subscribe();
1068
1106
  }
1069
1107
  }
1070
1108
  ```
@@ -1273,13 +1311,16 @@ the removal event (2).
1273
1311
  <!-- ... -->
1274
1312
  <h2>{{ 'demande-page.vehicules' | fromDictionary }}</h2>
1275
1313
 
1314
+ @if (form(); as form) {
1276
1315
  <app-vehicules-list
1277
- [(model)]="form.vehicules"
1316
+ [model]="form.vehicules"
1317
+ (modelChange)="patchForm(['vehicules'], $event)"
1278
1318
  name="vehicules"
1279
1319
  [label]="'demande-page.vehicules-list' | fromDictionary"
1280
1320
  [required]="true"
1281
1321
  (removedVehicule)="handleRemovedVehicule()"
1282
1322
  />
1323
+ }
1283
1324
  <!-- (1) Use of your list - (2) Call of the method saving the data in GESDEM to refresh the errors -->
1284
1325
 
1285
1326
  <foehn-navigation
@@ -1308,7 +1349,7 @@ export class DemandePageComponent
1308
1349
  * if an inventory item that was in error is removed, this prevents the error to be displayed
1309
1350
  * to the next item that has taken it's index
1310
1351
  */
1311
- this._gesdemService.save(this.form).pipe(first()).subscribe();
1352
+ this._gesdemService.save(this.form()).pipe(first()).subscribe();
1312
1353
  }
1313
1354
  }
1314
1355
  ```
@@ -1343,7 +1384,7 @@ What **not** to do:
1343
1384
  ```ts
1344
1385
  isAmountFilled(): boolean {
1345
1386
  // true after the input of '0', false once the form is loaded (0)
1346
- return !!this.form?.amount;
1387
+ return !!this.form()?.amount;
1347
1388
  }
1348
1389
  ```
1349
1390
 
@@ -1351,13 +1392,13 @@ What **to** do:
1351
1392
 
1352
1393
  ```ts
1353
1394
  isAmountFilled(): boolean {
1354
- const amount = this.form?.amount;
1395
+ const amount = this.form()?.amount;
1355
1396
  return amount !== null && amount !== undefined && amount !== '';
1356
1397
  }
1357
1398
 
1358
1399
  getTotal(): number {
1359
1400
  // Number() converts '12.50' as well as 12.5
1360
- return Number(this.form?.amount ?? 0) + Number(this.form?.fees ?? 0);
1401
+ return Number(this.form()?.amount ?? 0) + Number(this.form()?.fees ?? 0);
1361
1402
  }
1362
1403
  ```
1363
1404
 
@@ -1405,19 +1446,27 @@ export class BusinessForm {
1405
1446
  `page-1.html`
1406
1447
 
1407
1448
  ```html
1449
+ @if (form(); as form) {
1408
1450
  <foehn-input-text
1409
- [(model)]="form.identification.firstName"
1451
+ [model]="form.identification.firstName"
1452
+ (modelChange)="patchForm(['identification', 'firstName'], $event)"
1410
1453
  name="identification.firstName"
1411
1454
  />
1412
1455
  <!-- 2 levels of depth -->
1413
1456
 
1414
1457
  <foehn-input-text
1415
- [(model)]="form.identification.lastName"
1458
+ [model]="form.identification.lastName"
1459
+ (modelChange)="patchForm(['identification', 'lastName'], $event)"
1416
1460
  name="identification.lastName"
1417
1461
  />
1418
1462
 
1419
- <foehn-boolean-checkbox [(model)]="form.acceptCookies" name="acceptCookies" />
1463
+ <foehn-boolean-checkbox
1464
+ [model]="form.acceptCookies"
1465
+ (modelChange)="patchForm(['acceptCookies'], $event)"
1466
+ name="acceptCookies"
1467
+ />
1420
1468
  <!-- 1 level of depth -->
1469
+ }
1421
1470
  ```
1422
1471
 
1423
1472
  - On the back-end side, you can handle your errors with the annotations (`@NotEmpty`, `@NotNull`, ...),
@@ -1470,7 +1519,8 @@ HTML page and the names of your errors must match.
1470
1519
 
1471
1520
  ```html
1472
1521
  <foehn-input-text
1473
- [(model)]="form.identification.lastName"
1522
+ [model]="form.identification.lastName"
1523
+ (modelChange)="patchForm(['identification', 'lastName'], $event)"
1474
1524
  name="identification.lastName"
1475
1525
  />
1476
1526
  ```