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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (40) hide show
  1. package/ANGULAR_SIGNALS.md +4 -0
  2. package/CHANGELOG.md +113 -3
  3. package/CONTRIBUTING.md +2 -2
  4. package/ESLINT_PLUGIN.md +146 -28
  5. package/GOOD_PRACTICES.md +258 -58
  6. package/INTRODUCTION_ANGULAR_SIGNALS.md +29 -2
  7. package/UPGRADING_V19.md +233 -31
  8. package/eslint/configs/template-rules.mjs +5 -0
  9. package/eslint/configs/ts-recommended.mjs +4 -0
  10. package/eslint/form-reads.mjs +63 -0
  11. package/eslint/rules/index.mjs +4 -0
  12. package/eslint/rules/no-direct-signal-mutation.mjs +57 -19
  13. package/eslint/rules/no-item-track-in-form-list.mjs +172 -0
  14. package/eslint/rules/no-uninvoked-signal-in-template.mjs +8 -3
  15. package/eslint/rules/require-model-change.mjs +89 -0
  16. package/eslint/template-ast.mjs +12 -2
  17. package/fesm2022/dsivd-prestations-ng.mjs +948 -692
  18. package/fesm2022/dsivd-prestations-ng.mjs.map +1 -1
  19. package/package.json +1 -1
  20. package/schematics/migration-collection.json +5 -0
  21. package/schematics/ng-update/migrations/update-19_2_0/index.js +39 -0
  22. package/schematics/utility/form-signal/class-migration.js +671 -0
  23. package/schematics/utility/form-signal/edits.js +34 -0
  24. package/schematics/utility/form-signal/form-signal-migration.js +184 -0
  25. package/schematics/utility/form-signal/page-classes.js +129 -0
  26. package/schematics/utility/form-signal/template-migration.js +666 -0
  27. package/src/eslint/configs/template-rules.mjs +5 -0
  28. package/src/eslint/configs/ts-recommended.mjs +4 -0
  29. package/src/eslint/form-reads.mjs +63 -0
  30. package/src/eslint/rules/__tests__/no-direct-signal-mutation.test.mjs +58 -0
  31. package/src/eslint/rules/__tests__/no-item-track-in-form-list.test.mjs +234 -0
  32. package/src/eslint/rules/__tests__/no-uninvoked-signal-in-template.test.mjs +6 -0
  33. package/src/eslint/rules/__tests__/require-model-change.test.mjs +93 -0
  34. package/src/eslint/rules/index.mjs +4 -0
  35. package/src/eslint/rules/no-direct-signal-mutation.mjs +57 -19
  36. package/src/eslint/rules/no-item-track-in-form-list.mjs +172 -0
  37. package/src/eslint/rules/no-uninvoked-signal-in-template.mjs +8 -3
  38. package/src/eslint/rules/require-model-change.mjs +89 -0
  39. package/src/eslint/template-ast.mjs +12 -2
  40. package/types/dsivd-prestations-ng.d.ts +266 -35
@@ -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,50 @@
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
+ - `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).
31
+ - `ng update` migration of 19.2.0: migrates your pages to their form and their reference held by signals, their
32
+ classes and their templates (see the 🚨 entries below and
33
+ [UPGRADING_V19.md](UPGRADING_V19.md#the-form-of-your-pages-is-a-signal-since-1920)). It lists what it can't
34
+ migrate, and running it again changes nothing.
35
+ - 🚨 ESLint rules [`require-model-change`](ESLINT_PLUGIN.md#require-model-change) and
36
+ [`no-item-track-in-form-list`](ESLINT_PLUGIN.md#no-item-track-in-form-list), in `configs.templateRules` and
37
+ `configs.templateRecommended`: a one-way `[model]` reading the form without `(modelChange)` (the input of the user
38
+ is lost; a component always disabled, `foehn-input-hidden`, `foehn-table` and a component listening to
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
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]"`).
42
+
13
43
  - [foehn-date-model.type.ts](projects/prestations-ng/src/foehn-input-date/foehn-date-model.type.ts)
14
44
  - New `FoehnDateModel` type, the model of `foehn-input-date` (`(number | null)[]`, the JSON of a
15
45
  `LenientLocalDate` of prestations-be), to type the date fields of your forms, e.g.
16
46
  `birthDate: FoehnDateModel | null = null;`.
47
+ - `DateHelper.isValid()`, `isToday()` and `toDayjsFromNumberArray()` accept it, `null` and `undefined`
48
+ included: no cast in a strict project. A date with a part not entered is still neither valid nor today, and
49
+ gives `null`.
50
+ - [foehn-date-time-model.type.ts](projects/prestations-ng/src/foehn-input-date-time/foehn-date-time-model.type.ts)
51
+ - New `FoehnDateTimeModel` type, the model of `foehn-input-date-time` (`(number | null)[]`: year, month, day,
52
+ hour, minute, the JSON of a `LenientLocalDateTime` of prestations-be).
53
+ - The `displayDate` pipe, `DateHelper.toDateFromNumberArray()`, `arrayToDisplayDateDMY()`, `isValid()` and
54
+ `isToday()` accept it, as well as a `FoehnDateModel`. The new `DateHelper.hasTime()` tells whether a date-time
55
+ has its time entered.
56
+ `DateHelper.leftPad()` accepts `null` and `undefined` (it already returned `''`).
17
57
  - [eslint/configs/spec-ts-recommended.mjs](projects/prestations-ng/src/eslint/configs/spec-ts-recommended.mjs)
18
58
  - New `prestationsNg.configs.specTsRecommended` ESLint config for the Vitest specs, to use in the `extends` of a
19
59
  `**/*.spec.ts` block: the `recommended` config of `@vitest/eslint-plugin`, which also counts the assertions of
@@ -143,6 +183,31 @@ Please check the [UPGRADING_V19.md](UPGRADING_V19.md) guide for more information
143
183
  - `epayment-form` (`SdkEpaymentComponent`): `failureModalDisplayed`, `redirectModalDisplayed`
144
184
  - `captcha` (`SdkRecaptchaComponent`): `isLoaded`, `hasLoadingError`
145
185
  - `redirector` (`RedirectComponent`): `counter`
186
+ - 🚨 `AbstractPageComponent`: `reference` is now a signal. Read it with `reference()` in your pages and their
187
+ templates, and write it with `reference.set()`. A template, a `computed()` or an `effect()` reading it follows the
188
+ reference, also when your page sets it, without `markForCheck()`. A page declaring its own `reference` field no
189
+ longer compiles: remove it. The `ng update` migration rewrites your pages, see
190
+ [UPGRADING_V19.md](UPGRADING_V19.md#reference-of-your-pages-is-a-signal-since-1920).
191
+ - 🚨 ESLint: `configs.tsRecommended` enables `@typescript-eslint/restrict-template-expressions`. A template literal
192
+ only takes strings, numbers, booleans, `null`, `undefined`, `any` and `RegExp`: a signal not called
193
+ (`` `api/${this.reference}` ``) or an object turned into text by its `toString()` is reported. See
194
+ [ESLINT_PLUGIN.md](ESLINT_PLUGIN.md#the-typescript-counterpart).
195
+ - 🚨 `AbstractPageComponent`: `form` is now a signal (`WritableSignal<T | null | undefined>`). Read it with `form()`,
196
+ never modify its value in place: write it with the new `patchForm(path, value)`
197
+ (`[model]="form.firstName" (modelChange)="patchForm(['firstName'], $event)"`), `form.set()` or `form.update()`. A
198
+ template, a `computed()` or an `effect()` reading it follows every input of the user, and no `markForCheck()` is
199
+ needed after a write anymore. The `ng update` migration rewrites your pages, see
200
+ [UPGRADING_V19.md](UPGRADING_V19.md#the-form-of-your-pages-is-a-signal-since-1920).
201
+ - 🚨 `AbstractListDetailPageComponent`: the abstract `getListPath()` (the path of the list in the form) replaces the
202
+ abstract `getList()`, which reads the list at that path. `list`, `itemIndex` and `itemToEdit` are now signals. The
203
+ item edited is written with the new `patchItem(path, value)`, `updateItem(update)` (several fields in one write)
204
+ and `setItem(item)`. A new item is added without modifying the list of the form in place.
205
+ - `PendingUploadService` writes the documents uploaded with the form into a new form, instead of modifying the form
206
+ in place.
207
+ - 🚨 ESLint rule [`no-direct-signal-mutation`](ESLINT_PLUGIN.md#no-direct-signal-mutation) sees through the
208
+ TypeScript wrappers keeping the value: `this.form()!.name = value` and `(this.model() as Model).name = value` are
209
+ now reported. In a template, it sees through `!` and the parentheses, and follows the alias of an `@if`:
210
+ `[(model)]="form.name"` inside `@if (form(); as form)` is now reported.
146
211
  - The lifecycle hooks that have nothing left to do are removed: `ngOnChanges()` of
147
212
  `foehn-agenda-timeslot-panel` and `foehn-table`, `ngAfterViewInit()` of `foehn-list-summary`, `ngOnInit()` of
148
213
  `foehn-radio` and `foehn-input-textarea`, `ngOnInit()` and `ngOnDestroy()` of `captcha`.
@@ -158,11 +223,27 @@ Please check the [UPGRADING_V19.md](UPGRADING_V19.md) guide for more information
158
223
  - If one of your components reads the value of `model_`, not only `model_ !== undefined`: it is `undefined` as
159
224
  long as the model of the page has had no value to display, and `null` once the page sets it back to
160
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).
161
229
  - `modelChange` of the `foehn-input-*` components is emitted only when the component writes its model (an input of
162
230
  the user, a correction of the model given by the page), not when the page changes the model: true since 19.0.0,
163
231
  now documented in
164
232
  [UPGRADING_V19.md](UPGRADING_V19.md#modelchange-is-emitted-only-when-the-component-writes-its-model), and on the
165
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.
239
+ - 🚨 The `onModelChange()` methods which were not the hook of `FoehnInputComponent` are removed or renamed (they are
240
+ not called by the model anymore):
241
+ - `foehn-date-picker-button`: `model_`, `onModelChange()` and `updateNgModel()` are removed, they had no effect
242
+ (`model_` was never read).
243
+ - `foehn-date-picker`: `model_` is removed (never read), `onModelChange()` is now private (`syncWithModel()`).
244
+ - `numberCurrencyFormatter`: `onModelChange()` is now private (`formatModel()`), and the directive no longer
245
+ listens to the `modelChange` of its host: its `effect()` already formats every model, the ones written by the
246
+ host were formatted twice.
166
247
  - `SdkDictionaryService.getKeySync()` reads a signal: a `computed()` or a template calling it is refreshed
167
248
  when the dictionary is (re)loaded, e.g. when the language changes.
168
249
  - `foehn-autocomplete` and `foehn-multiselect-autocomplete`: the value to display, its reset, the default
@@ -183,9 +264,28 @@ Please check the [UPGRADING_V19.md](UPGRADING_V19.md) guide for more information
183
264
 
184
265
  - `AbstractMenuPageComponent.ngZone` is no longer used and will be removed: `NgZone.onStable` never emits
185
266
  without zone.js.
186
-
187
- ### Fixed
188
-
267
+ - `ObjectHelper.getNestedProperty(obj, key)` will be removed: use `ObjectPathHelper.getByKeys(obj, key)`, which it
268
+ now calls (see Fixed).
269
+
270
+ ### Fixed
271
+
272
+ - 🚨 `ObjectHelper.getNestedProperty()`, and the keys given as text to `elementValue`, `elementLabel`, `elementGroup`,
273
+ `elementDisabled` and `elementSuggestionLabel` of `foehn-select`, `foehn-radio`, `foehn-checkbox` and the
274
+ autocompletes, read the value at the path of the key (`'country.name'`): a value which is an object, or a getter of
275
+ a class, is no longer `undefined`, and a nested key is no longer looked up in another nested object holding the same
276
+ key (`'country.name'` gave the `name` of the first nested object having one). A value `null` is no longer
277
+ `undefined` either: an element `{ value: null }` is now selected by a model `null` (e.g. sent by the backend), no
278
+ longer by a model `undefined` (e.g. a field missing from the JSON), and choosing it writes `null` into the model, no
279
+ longer `undefined`.
280
+ - 🚨 `DateHelper.isValid()` also checks the time of a date-time (5 parts or more, e.g. the model of
281
+ `foehn-input-date-time`), as `LenientLocalDateTime.isValid()` of prestations-be: an hour (0 to 23) and a minute (0
282
+ to 59) are required. It only checked the date: a date-time without its time, or at 25:00, was valid. Check your
283
+ calls on a date-time. `isToday()` still considers only the date.
284
+ - The `displayDate` pipe, `DateHelper.toDateFromNumberArray()` and `arrayToDisplayDateDMY()` no longer give a wrong
285
+ date for a date with a part not entered (e.g. a draft saved with an incomplete date): `[2020, null, null]` was
286
+ displayed `30.11.2019`, it now gives nothing. A date-time without its time gives only the date (it displayed
287
+ `00:00:00`), and an empty array gives nothing (it threw an error). `DateHelper.isToday()`: a date which does not
288
+ exist is no longer today (the 30.02.2026 was the 02.03.2026).
189
289
  - `AbstractPageComponent` and `AbstractPageFromMenuComponent`: a second click on "next" or "transmit" while the next
190
290
  page is loading (lazy loaded route, resolver, async guard) no longer saves again and skips the next page:
191
291
  `send()`, `sendAndTransmit()` and `transmit()` are ignored until the navigation to the next page ends. Pages
@@ -226,6 +326,11 @@ Please check the [UPGRADING_V19.md](UPGRADING_V19.md) guide for more information
226
326
  component (e.g. prefilled with `SessionInfoWithApplicationService.prefillForm()` for a connected user) is no
227
327
  longer overwritten by the model with the default country only; the default country and the clean-up of the model
228
328
  are applied after the next rendering, from the latest model.
329
+ - `foehn-input-address` in Switzerland only (`isOnlySwiss`): an address given by the page without country after the
330
+ initialization of the component (e.g. a form loaded from the backend) gets the Swiss country again, as in v18: it
331
+ kept `country: null` until the user changed a field. The default country is checked again for every model given by
332
+ the page, and written only when it changes the model: an identical model is no longer written back (one
333
+ `modelChange` less), and an address without any value to display is left as it is.
229
334
  - `foehn-input-address`: the streets and the street numbers of an address given by the page are loaded again, as in
230
335
  v18. Since 19.0.0, they were only loaded once the user chose a locality and a street (the autocompletes no longer
231
336
  emit `modelChange` for a model given by the page), and a locality given with its `zipCodeId` only (without
@@ -295,6 +400,11 @@ Please check the [UPGRADING_V19.md](UPGRADING_V19.md) guide for more information
295
400
  - `foehn-feedback-notification`: an error of `api/feedbacknotification/queryparams/{reference}` is logged and the
296
401
  links are displayed without the feedback url, it reached the `ErrorHandler` as unhandled.
297
402
  - The npm package no longer contains its own archive (`dsivd-prestations-ng-<version>.tgz`).
403
+ - ESLint rules [`no-direct-signal-mutation`](ESLINT_PLUGIN.md#no-direct-signal-mutation) and
404
+ [`no-uninvoked-signal-in-template`](ESLINT_PLUGIN.md#no-uninvoked-signal-in-template): an explicit `(xChange)`
405
+ handler is no longer taken for the target of a two-way binding `[(x)]`. `no-direct-signal-mutation` reported
406
+ `(modelChange)="updateModel()"` in a template shared by several components (its component file not found), and
407
+ `no-uninvoked-signal-in-template` let `(valueChange)="mySignal"` through.
298
408
 
299
409
  ## [19.1.1]
300
410
 
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
@@ -105,12 +107,13 @@ in a two-way binding.
105
107
 
106
108
  ```ts
107
109
  // ✗ mutates the object inside the signal, no notification
108
- this.model().property = value;
109
- this.model().items.splice(index, 1);
110
+ this.settings().property = value;
111
+ this.settings().items.splice(index, 1);
110
112
 
111
113
  // ✓
112
- this.model.update((current) => ({ ...current, property: value }));
113
- 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) => ({
114
117
  ...current,
115
118
  items: current.items.filter((_, i) => i !== index),
116
119
  }));
@@ -118,14 +121,20 @@ this.model.update((current) => ({
118
121
 
119
122
  ```html
120
123
  <!-- ✗ -->
121
- <button (click)="model().property = value">…</button>
122
- <button (click)="model().items.splice(index, 1)">…</button>
123
- <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" />
124
127
 
125
128
  <!-- ✓ -->
126
- <button (click)="model.update((v) => ({ ...v, property: value }))">…</button>
129
+ <button (click)="settings.update((v) => ({ ...v, property: value }))">…</button>
127
130
  ```
128
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
+
129
138
  All the assignment operators accepted by the Angular expression parser are covered: `=`,
130
139
  `+=`, `-=`, `*=`, `/=`, `%=`, `**=`, `&&=`, `||=`, `??=`.
131
140
 
@@ -139,10 +148,14 @@ Two other ways of writing into the value are covered, in TypeScript — the Angu
139
148
  parser accepts neither:
140
149
 
141
150
  ```ts
142
- delete this.model().users[0];
143
- Object.assign(this.model(), { property: value });
151
+ delete this.settings().users[0];
152
+ Object.assign(this.settings(), { property: value });
144
153
  ```
145
154
 
155
+ The TypeScript wrappers which keep the value are seen through: `this.form()!.name = value`
156
+ and `(this.settings() as Settings).name = value` are reported as well, as are, in a template,
157
+ `[(ngModel)]="form()!.name"` and `(form()).name = value`.
158
+
146
159
  #### Names bound to the value
147
160
 
148
161
  A mutation is rarely written on the signal read itself. The rule follows the value through
@@ -150,22 +163,27 @@ the bindings it can resolve exactly, and only those:
150
163
 
151
164
  ```ts
152
165
  // ✗ a variable written once
153
- const users = this.model().users;
166
+ const users = this.settings().users;
154
167
  users.push(user);
155
168
 
156
169
  // ✗ the element parameter of an iteration callback
157
- this.model().users.forEach((user) => (user.done = true));
170
+ this.settings().users.forEach((user) => (user.done = true));
158
171
  ```
159
172
 
160
173
  ```angular-html
161
174
  <!-- ✗ a @for item, bound only inside its own block -->
162
- @for (user of model().users; track user.id) {
175
+ @for (user of settings().users; track user.id) {
163
176
  <input [(ngModel)]="user.done" />
164
177
  <button (click)="user.tags.push(tag)">…</button>
165
178
  }
166
179
 
180
+ <!-- ✗ the alias of an @if, bound only inside its own branch -->
181
+ @if (form(); as form) {
182
+ <foehn-input-text name="name" [(model)]="form.name" />
183
+ }
184
+
167
185
  <!-- ✗ a @let -->
168
- @let users = model().users;
186
+ @let users = settings().users;
169
187
  <button (click)="users.push(user)">…</button>
170
188
  ```
171
189
 
@@ -179,7 +197,7 @@ stored in a class field, returned and mutated elsewhere:
179
197
 
180
198
  ```ts
181
199
  // not reported: the rule cannot know what `sortInto` does
182
- this.sortInto(this.model().users);
200
+ this.sortInto(this.settings().users);
183
201
  ```
184
202
 
185
203
  That needs interprocedural analysis, which ESLint does not provide; a full type checker
@@ -211,11 +229,11 @@ the normal way to use one. `.required` variants included.
211
229
 
212
230
  Anything that is not a declared signal is left alone as well:
213
231
 
214
- | Expression | Why |
215
- | ------------------------------------ | ------------------------------------------------------------ |
216
- | `this.getConfig().items.push(item)` | `getConfig()` is a plain method, not a signal |
217
- | `map.get(key).files.push(file)` | the call takes arguments, so it is not a signal read |
218
- | `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 |
219
237
 
220
238
  Because the rule knows a real signal from an ordinary method, `set` / `add` / `delete` are
221
239
  safe to report: `byId().set(k, v)` mutates the `Map` inside the signal, while `byId.set(m)`
@@ -295,6 +313,94 @@ found without declaring anything.
295
313
  | `[(value)]="mySignal"` | a writable signal is two-way bound **without** parentheses, Angular calls `.set()` itself |
296
314
  | `#ref`, `@for` items, `@if … as`, `@let`, `let-x`, `$index`… | template-local names shadow the class members |
297
315
 
316
+ ### `require-model-change`
317
+
318
+ Reports a `foehn-*` component given a field of the form of the page with a one-way `[model]`
319
+ and no `(modelChange)`. The component changes its own model only: what the user enters never
320
+ reaches the form, and is lost when the form is saved.
321
+
322
+ Applies to **templates only**.
323
+
324
+ ```html
325
+ <!-- ✗ the input of the user is lost -->
326
+ <foehn-input-text [model]="form.firstName" />
327
+
328
+ <!-- ✓ -->
329
+ <foehn-input-text
330
+ [model]="form.firstName"
331
+ (modelChange)="patchForm(['firstName'], $event)"
332
+ />
333
+ ```
334
+
335
+ Only the models read from the form are checked: `form()`, `form.firstName`, and the names
336
+ bound to it by `@if (form(); as form)`, `@let form = this.form()` or
337
+ `@for (child of form.children; …)`. A one-way `[model]` is legitimate elsewhere (a table
338
+ displaying a list, a menu...). `[(model)]` declares both bindings and is never reported.
339
+
340
+ Not reported either, as the input of the user can't be lost:
341
+
342
+ - a component always disabled, `disabled="true"` or `[disabled]="true"` (a disabled component
343
+ doesn't write its model), unless it is given `updateModelWhenDisabled`;
344
+ - `foehn-input-hidden` and `foehn-table`, which never write their model;
345
+ - a component listening to `(userInput)`, whose handler writes the form.
346
+
347
+ A `[disabled]` depending on a condition is reported: once the component is enabled, the input of
348
+ the user would be lost. A bare `disabled` is reported too: it gives `''`, which doesn't disable
349
+ the component.
350
+
351
+ ```html
352
+ <!-- ✓ displayed only -->
353
+ <foehn-input-text [model]="form.reference" [disabled]="true" />
354
+ ```
355
+
356
+ ### `no-item-track-in-form-list`
357
+
358
+ Reports a `@for` over a list of the form whose rows edit their item, tracked by the item
359
+ itself (`track child`, `track $any(child)`). Writing a field of an item with `patchForm()`
360
+ or `patchItem()` replaces the item with a copy: its row is destroyed and created again at
361
+ every input, and the field being edited loses the focus.
362
+
363
+ Applies to **templates only**.
364
+
365
+ ```html
366
+ <!-- ✗ the field loses the focus at every input -->
367
+ @for (child of form.children; track child) {
368
+ <foehn-input-text
369
+ [model]="child.firstName"
370
+ (modelChange)="patchForm(['children', $index, 'firstName'], $event)"
371
+ />
372
+ }
373
+
374
+ <!-- ✓ -->
375
+ @for (child of form.children; track child.id) { … } @for (child of
376
+ form.children; track $index) { … }
377
+ ```
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
+
394
+ A row edits its item when one of its elements has a `model` read from it
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).
400
+
401
+ > 💡 The control flow migration of Angular turns a `*ngFor` without `trackBy` into
402
+ > `track <item>`: after it, check the lists of the form.
403
+
298
404
  ## The TypeScript counterpart
299
405
 
300
406
  `@angular-eslint/no-uncalled-signals` covers the same class of bug **in TypeScript**, using
@@ -310,3 +416,15 @@ are complementary, not redundant.
310
416
 
311
417
  It only reports signals used in logic positions (`if`, `!x`, `&&`, `===`, `.length`…), not a
312
418
  bare `const x = mySignal`.
419
+
420
+ Nor a template literal: `` `api/${this.reference}/pdf-sections` `` compiles, and gives the
421
+ signal itself as text (`[Signal: …]`, or the source of a function in production) instead of
422
+ its value. `configs.tsRecommended` also enables
423
+ `@typescript-eslint/restrict-template-expressions`, which only lets strings, numbers,
424
+ booleans, `null`, `undefined`, `any` and `RegExp` into a template literal: a signal not
425
+ called is reported, as is an object turned into text by its `toString()`. With
426
+ `configs.tsRules` you enable it yourself (it requires type information too):
427
+
428
+ ```ts
429
+ '@typescript-eslint/restrict-template-expressions': 'error',
430
+ ```