@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.
- package/ANGULAR_SIGNALS.md +4 -0
- package/CHANGELOG.md +113 -3
- package/CONTRIBUTING.md +2 -2
- package/ESLINT_PLUGIN.md +146 -28
- package/GOOD_PRACTICES.md +258 -58
- package/INTRODUCTION_ANGULAR_SIGNALS.md +29 -2
- package/UPGRADING_V19.md +233 -31
- package/eslint/configs/template-rules.mjs +5 -0
- package/eslint/configs/ts-recommended.mjs +4 -0
- package/eslint/form-reads.mjs +63 -0
- package/eslint/rules/index.mjs +4 -0
- package/eslint/rules/no-direct-signal-mutation.mjs +57 -19
- package/eslint/rules/no-item-track-in-form-list.mjs +172 -0
- package/eslint/rules/no-uninvoked-signal-in-template.mjs +8 -3
- package/eslint/rules/require-model-change.mjs +89 -0
- package/eslint/template-ast.mjs +12 -2
- package/fesm2022/dsivd-prestations-ng.mjs +948 -692
- package/fesm2022/dsivd-prestations-ng.mjs.map +1 -1
- package/package.json +1 -1
- package/schematics/migration-collection.json +5 -0
- package/schematics/ng-update/migrations/update-19_2_0/index.js +39 -0
- package/schematics/utility/form-signal/class-migration.js +671 -0
- package/schematics/utility/form-signal/edits.js +34 -0
- package/schematics/utility/form-signal/form-signal-migration.js +184 -0
- package/schematics/utility/form-signal/page-classes.js +129 -0
- package/schematics/utility/form-signal/template-migration.js +666 -0
- package/src/eslint/configs/template-rules.mjs +5 -0
- package/src/eslint/configs/ts-recommended.mjs +4 -0
- package/src/eslint/form-reads.mjs +63 -0
- package/src/eslint/rules/__tests__/no-direct-signal-mutation.test.mjs +58 -0
- package/src/eslint/rules/__tests__/no-item-track-in-form-list.test.mjs +234 -0
- package/src/eslint/rules/__tests__/no-uninvoked-signal-in-template.test.mjs +6 -0
- package/src/eslint/rules/__tests__/require-model-change.test.mjs +93 -0
- package/src/eslint/rules/index.mjs +4 -0
- package/src/eslint/rules/no-direct-signal-mutation.mjs +57 -19
- package/src/eslint/rules/no-item-track-in-form-list.mjs +172 -0
- package/src/eslint/rules/no-uninvoked-signal-in-template.mjs +8 -3
- package/src/eslint/rules/require-model-change.mjs +89 -0
- package/src/eslint/template-ast.mjs +12 -2
- package/types/dsivd-prestations-ng.d.ts +266 -35
package/ANGULAR_SIGNALS.md
CHANGED
|
@@ -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
|
-
|
|
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
|
|
240
|
-
the
|
|
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,
|
|
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.
|
|
109
|
-
this.
|
|
110
|
+
this.settings().property = value;
|
|
111
|
+
this.settings().items.splice(index, 1);
|
|
110
112
|
|
|
111
113
|
// ✓
|
|
112
|
-
this.
|
|
113
|
-
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) => ({
|
|
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)="
|
|
122
|
-
<button (click)="
|
|
123
|
-
<input [(ngModel)]="
|
|
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)="
|
|
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.
|
|
143
|
-
Object.assign(this.
|
|
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.
|
|
166
|
+
const users = this.settings().users;
|
|
154
167
|
users.push(user);
|
|
155
168
|
|
|
156
169
|
// ✗ the element parameter of an iteration callback
|
|
157
|
-
this.
|
|
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
|
|
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 =
|
|
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.
|
|
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
|
|
215
|
-
|
|
|
216
|
-
| `this.getConfig().items.push(item)`
|
|
217
|
-
| `map.get(key).files.push(file)`
|
|
218
|
-
| `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 |
|
|
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
|
+
```
|