@dsivd/prestations-ng 19.2.0-beta.28 → 19.2.0-beta.29
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/AI_GUIDELINES.md +3 -1
- package/CHANGELOG.md +26 -1
- package/CONTRIBUTING.md +7 -4
- package/ESLINT_PLUGIN.md +54 -2
- package/GOOD_PRACTICES.md +20 -0
- package/README.md +18 -12
- package/UPGRADING_V19.md +69 -1
- package/eslint/rules/no-direct-signal-mutation.mjs +104 -21
- package/eslint/signal-names.mjs +127 -21
- package/fesm2022/dsivd-prestations-ng.mjs +60 -5
- package/fesm2022/dsivd-prestations-ng.mjs.map +1 -1
- package/package.json +1 -1
- package/schematics/ng-update/migrations/update-19_2_0/index.js +3 -2
- package/schematics/utility/form-signal/class-migration.js +130 -6
- package/schematics/utility/form-signal/form-members.js +318 -0
- package/schematics/utility/form-signal/form-signal-migration.js +10 -3
- package/schematics/utility/form-signal/page-classes.js +11 -1
- package/schematics/utility/form-signal/template-migration.js +119 -10
- package/src/eslint/rules/__tests__/no-direct-signal-mutation.test.mjs +142 -0
- package/src/eslint/rules/no-direct-signal-mutation.mjs +104 -21
- package/src/eslint/signal-names.mjs +127 -21
- package/types/dsivd-prestations-ng.d.ts +19 -1
package/AI_GUIDELINES.md
CHANGED
|
@@ -47,7 +47,9 @@ Don't apply one before the step of the guide that brings it, unless asked.
|
|
|
47
47
|
(`require-track-index`). Only a list whose rows name nothing with the index and keep a state of their own (a
|
|
48
48
|
panel expanded, the focus, data loaded per item) while it can be reordered is tracked by an identifier of the item,
|
|
49
49
|
unique and stable. Never by the item itself when it is replaced (`patchForm()`, a new model), nor by a field the
|
|
50
|
-
row edits, nor by a `trackingIndex` kept by the project on its items (`FoehnListItem` has none).
|
|
50
|
+
row edits, nor by a `trackingIndex` kept by the project on its items (`FoehnListItem` has none). A page keeping the
|
|
51
|
+
errors of the server until its next save (a back office) renumbers them when it removes a row:
|
|
52
|
+
`ValidationHandlerService.removeListItemErrors('hearings[0].exchanges[1]')`, once per removal.
|
|
51
53
|
Detail pages: `getListPath()`, `list()`, `itemToEdit()`, and `patchItem()`, `updateItem()` or `setItem()`.
|
|
52
54
|
- The `modelChange` of a `foehn-*` component is emitted only when the component writes its model (an input of the
|
|
53
55
|
user, a correction), never when the page changes it (form loaded, prefill, reset). React to the loaded form where
|
package/CHANGELOG.md
CHANGED
|
@@ -39,7 +39,12 @@
|
|
|
39
39
|
- `ng update` migration of 19.2.0: migrates your pages to their form and their reference held by signals, their
|
|
40
40
|
classes and their templates (see the 🚨 entries below and
|
|
41
41
|
[UPGRADING_V19.md](UPGRADING_V19.md#the-form-of-your-pages-is-a-signal-since-1920)). It lists what it can't
|
|
42
|
-
migrate, and running it again changes nothing.
|
|
42
|
+
migrate, and running it again changes nothing. Since 19.2.0-beta.29, it also writes with `patchForm()` through a
|
|
43
|
+
getter of the page returning a path of the form (`this.step.motif = x`, `[(model)]="step.motif"` with
|
|
44
|
+
`get step() { return this.form.etape; }`, in the page or in a page it extends), and lists the writes through a
|
|
45
|
+
getter computing its value, the `effect()`s reading the form (directly or through a method: they run again at every
|
|
46
|
+
input of the user) and the methods writing the form called by the template outside an event (NG0600 while the view
|
|
47
|
+
is rendered).
|
|
43
48
|
- 🚨 ESLint rules [`require-model-change`](ESLINT_PLUGIN.md#require-model-change) and
|
|
44
49
|
[`no-item-track-in-form-list`](ESLINT_PLUGIN.md#no-item-track-in-form-list), in `configs.templateRules` and
|
|
45
50
|
`configs.templateRecommended`: a one-way `[model]` reading the form without `(modelChange)` (the input of the user
|
|
@@ -109,6 +114,17 @@
|
|
|
109
114
|
- [foehn-navigation.service.ts](projects/prestations-ng/src/foehn-navigation/foehn-navigation.service.ts)
|
|
110
115
|
- new method `pendingNavigationDirection()`: direction of the navigation started with `next()` or `previous()`
|
|
111
116
|
until it ends, `null` otherwise (also in 18.3.15)
|
|
117
|
+
- [form-error.helper.ts](projects/prestations-ng/src/validation/form-error.helper.ts) and
|
|
118
|
+
[validation-handler.service.ts](projects/prestations-ng/src/validation/validation-handler.service.ts) (since
|
|
119
|
+
19.2.0-beta.29)
|
|
120
|
+
- new `FormErrorHelper.withoutListItem(errors, itemPath)`: the errors left once the item at `itemPath` (e.g.
|
|
121
|
+
`'hearings[0].exchanges[1]'`) is removed from its list, in a new array: its errors are dropped, and those of the
|
|
122
|
+
following items take the new index of their item, the items of their nested lists included
|
|
123
|
+
- new method `ValidationHandlerService.removeListItemErrors(itemPath)`: applies it to the errors given to
|
|
124
|
+
`updateErrors()` and publishes them. For a page keeping the errors of the server until its next save (e.g. a
|
|
125
|
+
back office) when it removes an item of a list whose fields are named with the index: the errors of the
|
|
126
|
+
following items would otherwise stay on their former index. No component of the library calls it. See
|
|
127
|
+
"Avoiding error display problems in a `@for` loop" in [GOOD_PRACTICES.md](GOOD_PRACTICES.md).
|
|
112
128
|
|
|
113
129
|
### Changed
|
|
114
130
|
|
|
@@ -239,6 +255,11 @@ Please check the [UPGRADING_V19.md](UPGRADING_V19.md) guide for more information
|
|
|
239
255
|
TypeScript wrappers keeping the value: `this.form()!.name = value` and `(this.model() as Model).name = value` are
|
|
240
256
|
now reported. In a template, it sees through `!` and the parentheses, and follows the alias of an `@if`:
|
|
241
257
|
`[(model)]="form.name"` inside `@if (form(); as form)` is now reported.
|
|
258
|
+
- 🚨 ESLint rule [`no-direct-signal-mutation`](ESLINT_PLUGIN.md#getters-handing-out-the-value) (since
|
|
259
|
+
19.2.0-beta.29) follows the getters of the class returning the value of a signal or a part of it, through its
|
|
260
|
+
inheritance chain: `this.step.motif = value` and `[(model)]="step.motif"` with
|
|
261
|
+
`get step() { return this.form()!.etape; }` are now reported, as `this.form().count++` in TypeScript. Write the form
|
|
262
|
+
with `patchForm()`. To turn it off: `'@dsivd/prestations-ng/no-direct-signal-mutation': 'off'`.
|
|
242
263
|
- The lifecycle hooks that have nothing left to do are removed: `ngOnChanges()` of
|
|
243
264
|
`foehn-agenda-timeslot-panel` and `foehn-table`, `ngAfterViewInit()` of `foehn-list-summary`, `ngOnInit()` of
|
|
244
265
|
`foehn-radio` and `foehn-input-textarea`, `ngOnInit()` and `ngOnDestroy()` of `captcha`.
|
|
@@ -306,6 +327,10 @@ Please check the [UPGRADING_V19.md](UPGRADING_V19.md) guide for more information
|
|
|
306
327
|
|
|
307
328
|
- `foehn-checkbox` and `foehn-agenda` track their rows by their index (since 19.2.0-beta.28), as the names of their
|
|
308
329
|
fields: the checkboxes of elements reordered or replaced no longer share the control of the former ones.
|
|
330
|
+
- `foehn-agenda` follows its `disabled` input (since 19.2.0-beta.29), ignored until then: its time slots are disabled,
|
|
331
|
+
the navigation between the weeks stays usable. The time slot picked writes its model through `updateNgModel()`,
|
|
332
|
+
no longer with a two-way binding of its `model` (which bypassed the guard of a disabled component and the overrides
|
|
333
|
+
of `updateNgModel()`).
|
|
309
334
|
- 🚨 `ObjectHelper.getNestedProperty()`, and the keys given as text to `elementValue`, `elementLabel`, `elementGroup`,
|
|
310
335
|
`elementDisabled` and `elementSuggestionLabel` of `foehn-select`, `foehn-radio`, `foehn-checkbox` and the
|
|
311
336
|
autocompletes, read the value at the path of the key (`'country.name'`): a value which is an object, or a getter of
|
package/CONTRIBUTING.md
CHANGED
|
@@ -6,7 +6,7 @@
|
|
|
6
6
|
- npm 10.2+
|
|
7
7
|
- G++
|
|
8
8
|
|
|
9
|
-
Chromium is downloaded by Puppeteer during `npm
|
|
9
|
+
Chromium is downloaded by Puppeteer during `npm ci`: it is used by the unit tests (through Playwright)
|
|
10
10
|
and by the e2e tests (Cypress).
|
|
11
11
|
|
|
12
12
|
## Developing using the Dev Tool
|
|
@@ -63,7 +63,7 @@ result.
|
|
|
63
63
|
|
|
64
64
|
### In **prestations-ng**
|
|
65
65
|
|
|
66
|
-
- if it is the first time, execute `npm
|
|
66
|
+
- if it is the first time, execute `npm ci` then `npm run build:lib` (at root level)
|
|
67
67
|
- `cd dist/prestations-ng && npm link` (it's critical to link the content of `dist/prestations-ng`, not the root)
|
|
68
68
|
- `cd ../.. && npm run build:lib:dev` (at root level)
|
|
69
69
|
|
|
@@ -102,7 +102,7 @@ run `npm run test:schematics` (at root level).
|
|
|
102
102
|
### Testing into a project such as **skeleton**
|
|
103
103
|
|
|
104
104
|
- **In prestations-ng**:
|
|
105
|
-
- if it is the first time, execute `npm
|
|
105
|
+
- if it is the first time, execute `npm ci` then `npm run build:lib` (at root level)
|
|
106
106
|
- `cd dist/prestations-ng && npm link` (it's critical to link the content of `dist/prestations-ng`, not the root)
|
|
107
107
|
- `cd ../.. && npm run build:lib:dev` (at root level)
|
|
108
108
|
|
|
@@ -146,7 +146,10 @@ use the correct node version in the settings, otherwise it might fail. Same thin
|
|
|
146
146
|
- **Make sure you have installed pre commit hook by running :** `npm run huskyInstall`
|
|
147
147
|
- Remove unnecessary `console.log`
|
|
148
148
|
- Update [CHANGELOG.md](CHANGELOG.md)
|
|
149
|
-
-
|
|
149
|
+
- Install the dependencies of `package-lock.json` with `npm ci` after each pull or change of branch that changed it
|
|
150
|
+
(Renovate updates it every week): the tests and the lint then run on the versions Jenkins installs. Not with
|
|
151
|
+
`npm install` or `npm update`, which may rewrite the lock file: the dependencies are updated by the PRs of Renovate,
|
|
152
|
+
never in another change.
|
|
150
153
|
- If you want to autofix lint/format errors in your code : `npm run format`
|
|
151
154
|
- Run all tests `npm run validate`
|
|
152
155
|
- Ensure the commit message contains a Jira reference
|
package/ESLINT_PLUGIN.md
CHANGED
|
@@ -138,7 +138,8 @@ this.settings.update((current) => ({
|
|
|
138
138
|
> component alone.
|
|
139
139
|
|
|
140
140
|
All the assignment operators accepted by the Angular expression parser are covered: `=`,
|
|
141
|
-
`+=`, `-=`, `*=`, `/=`, `%=`, `**=`, `&&=`, `||=`,
|
|
141
|
+
`+=`, `-=`, `*=`, `/=`, `%=`, `**=`, `&&=`, `||=`, `??=`, and in TypeScript the increments
|
|
142
|
+
`++` and `--` (since 19.2.0-beta.29).
|
|
142
143
|
|
|
143
144
|
The in-place mutators covered are those of `Array` — `push`, `pop`, `shift`, `unshift`,
|
|
144
145
|
`splice`, `sort`, `reverse`, `fill`, `copyWithin` — and of `Map` / `Set` — `set`, `add`,
|
|
@@ -195,7 +196,8 @@ introduces the name — nothing is inferred from a naming convention. A variable
|
|
|
195
196
|
for `reduce`, whose first parameter is the accumulator and not an element.
|
|
196
197
|
|
|
197
198
|
**What it cannot follow** is a value crossing a function boundary — handed to a method,
|
|
198
|
-
stored in a class field, returned and mutated elsewhere
|
|
199
|
+
stored in a class field, returned by a method and mutated elsewhere (a getter is followed, see
|
|
200
|
+
below):
|
|
199
201
|
|
|
200
202
|
```ts
|
|
201
203
|
// not reported: the rule cannot know what `sortInto` does
|
|
@@ -205,6 +207,56 @@ this.sortInto(this.settings().users);
|
|
|
205
207
|
That needs interprocedural analysis, which ESLint does not provide; a full type checker
|
|
206
208
|
would be required. It is the one remaining gap in detection.
|
|
207
209
|
|
|
210
|
+
#### Getters handing out the value
|
|
211
|
+
|
|
212
|
+
Since 19.2.0-beta.29, a getter of the class whose body is a single `return` of the value of
|
|
213
|
+
one of its signals, or of a part of it, is followed too: what it returns is that value. Such
|
|
214
|
+
getters are common in the pages, written before their form became a signal, and neither the
|
|
215
|
+
`ng update` migration nor the rule saw the writes through them until then:
|
|
216
|
+
|
|
217
|
+
```ts
|
|
218
|
+
// in the page, or in an abstract page it extends
|
|
219
|
+
get step(): Step {
|
|
220
|
+
return this.form()!.etape;
|
|
221
|
+
}
|
|
222
|
+
|
|
223
|
+
// ✗ writes into the form, no notification
|
|
224
|
+
this.step.motif = value;
|
|
225
|
+
this.step.documents.push(document);
|
|
226
|
+
|
|
227
|
+
// ✓
|
|
228
|
+
this.patchForm(['etape', 'motif'], value);
|
|
229
|
+
this.patchForm(['etape', 'documents'], [...(this.step.documents ?? []), document]);
|
|
230
|
+
```
|
|
231
|
+
|
|
232
|
+
```angular-html
|
|
233
|
+
<!-- ✗ -->
|
|
234
|
+
<foehn-input-text name="motif" [(model)]="step.motif" />
|
|
235
|
+
|
|
236
|
+
<!-- ✓ -->
|
|
237
|
+
<foehn-input-text
|
|
238
|
+
name="motif"
|
|
239
|
+
[model]="step.motif"
|
|
240
|
+
(modelChange)="patchForm(['etape', 'motif'], $event)"
|
|
241
|
+
/>
|
|
242
|
+
```
|
|
243
|
+
|
|
244
|
+
The getter is resolved like the signals, through the inheritance chain (a getter of an
|
|
245
|
+
abstract page of your project is followed in its subclasses and their templates), and the
|
|
246
|
+
message names it with the signal: _Mutation of the value of the signal `form` through the
|
|
247
|
+
getter `step` detected_. A getter returning another such getter read further
|
|
248
|
+
(`get motif() { return this.step.motif; }`) is followed as well.
|
|
249
|
+
|
|
250
|
+
Left alone:
|
|
251
|
+
|
|
252
|
+
- the getter itself as the target (`this.step = value`, `[(step)]="step"`): it calls its
|
|
253
|
+
setter;
|
|
254
|
+
- a getter computing its value (`return this.form()?.etape ?? new Step();`, a copy, a
|
|
255
|
+
filter...) or made of more than a `return`: what it returns may not be the value of the
|
|
256
|
+
signal;
|
|
257
|
+
- a getter of a published library (its `.d.ts` has no body), and a name of the template
|
|
258
|
+
hiding the getter (`@for (step of steps; …)`).
|
|
259
|
+
|
|
208
260
|
#### Only real signals are inspected
|
|
209
261
|
|
|
210
262
|
The rule does not guess from the shape of a call. It reads the declaring class — the linted
|
package/GOOD_PRACTICES.md
CHANGED
|
@@ -1236,6 +1236,26 @@ export class YourPageComponent
|
|
|
1236
1236
|
It's up to you to decide how to call this method when the item is removed from
|
|
1237
1237
|
your list.
|
|
1238
1238
|
|
|
1239
|
+
A page handling the errors itself (see "Manual handling" in "Form validation") and keeping those of the server
|
|
1240
|
+
until its next save, e.g. a back office, has no validation to call: when it removes an item, it renumbers the errors
|
|
1241
|
+
with `removeListItemErrors()` of `ValidationHandlerService`. The errors of the removed item are dropped, and those of
|
|
1242
|
+
the following items take the new index of their item, the items of their nested lists included
|
|
1243
|
+
(`FormErrorHelper.withoutListItem()` does the same on an array of errors):
|
|
1244
|
+
|
|
1245
|
+
```ts
|
|
1246
|
+
private readonly validationHandlerService = inject(ValidationHandlerService);
|
|
1247
|
+
|
|
1248
|
+
removeExchange(hearingIndex: number, exchangeIndex: number): void {
|
|
1249
|
+
// ... remove the exchange from the model, in a new array
|
|
1250
|
+
this.validationHandlerService.removeListItemErrors(
|
|
1251
|
+
`hearings[${hearingIndex}].exchanges[${exchangeIndex}]`,
|
|
1252
|
+
);
|
|
1253
|
+
}
|
|
1254
|
+
```
|
|
1255
|
+
|
|
1256
|
+
No component of the library calls it: call it once per removal, and not besides a code of yours renumbering the
|
|
1257
|
+
errors already, or they would move twice.
|
|
1258
|
+
|
|
1239
1259
|
Here is an elegant way to handle your lists of items:
|
|
1240
1260
|
|
|
1241
1261
|
- Structure of the folders and files
|
package/README.md
CHANGED
|
@@ -8,17 +8,23 @@ The generated documentation of our entire library is available online at [https:
|
|
|
8
8
|
|
|
9
9
|
The documentation is available online at [https://dsi-vd.github.io/prestations-ng/](https://dsi-vd.github.io/prestations-ng/)
|
|
10
10
|
|
|
11
|
-
- If you're using **Angular 21**, use `@dsivd/prestations-ng` at version
|
|
12
|
-
- If you're using **Angular 19**, use `@dsivd/prestations-ng` at version
|
|
13
|
-
- If you're using **Angular 17**, use `@dsivd/prestations-ng` at version
|
|
14
|
-
- If you're using **Angular 15**, use `@dsivd/prestations-ng` at version
|
|
15
|
-
- If you're using **Angular 13**, use `@dsivd/prestations-ng` at version
|
|
16
|
-
- If you're using **Angular 12**, use `@dsivd/prestations-ng` at version
|
|
17
|
-
- If you're using **Angular 11**, use `@dsivd/prestations-ng` at version
|
|
18
|
-
- If you're using **Angular 9**, use `@dsivd/prestations-ng` at version
|
|
19
|
-
- If you're using **Angular 8**, use `@dsivd/prestations-ng` at version
|
|
20
|
-
- If you're using **Angular 6 or 7**, use `@dsivd/prestations-ng` at version
|
|
21
|
-
- If you're using **Angular 5**, use `prestations-ng` at version
|
|
11
|
+
- If you're using **Angular 21**, use `@dsivd/prestations-ng` at version `19`.
|
|
12
|
+
- If you're using **Angular 19**, use `@dsivd/prestations-ng` at version `18`.
|
|
13
|
+
- If you're using **Angular 17**, use `@dsivd/prestations-ng` at version `17`.
|
|
14
|
+
- If you're using **Angular 15**, use `@dsivd/prestations-ng` at version `16`.
|
|
15
|
+
- If you're using **Angular 13**, use `@dsivd/prestations-ng` at version `15`.
|
|
16
|
+
- If you're using **Angular 12**, use `@dsivd/prestations-ng` at version `14`, from `14.5.0`.
|
|
17
|
+
- If you're using **Angular 11**, use `@dsivd/prestations-ng` at version `13`, or `14` until `14.4.1`.
|
|
18
|
+
- If you're using **Angular 9**, use `@dsivd/prestations-ng` at version `11`.
|
|
19
|
+
- If you're using **Angular 8**, use `@dsivd/prestations-ng` at version `9`.
|
|
20
|
+
- If you're using **Angular 6 or 7**, use `@dsivd/prestations-ng` at version `8`.
|
|
21
|
+
- If you're using **Angular 5**, use `prestations-ng` at version `7`.
|
|
22
|
+
|
|
23
|
+
These are the major versions to use. In your `package.json`, declare the library with a tilde (e.g.
|
|
24
|
+
`"@dsivd/prestations-ng": "~19.2.0"`): a minor version may break and goes with the same minor version of
|
|
25
|
+
`prestations-be` (see "Dependency on `prestations-be`" below), and a caret would let `npm install` or the lock file
|
|
26
|
+
maintenance of Renovate install the next one. `npm install @dsivd/prestations-ng@<version>` writes a caret, even over a
|
|
27
|
+
tilde: install a version with `npm install @dsivd/prestations-ng@~<version>`.
|
|
22
28
|
|
|
23
29
|
The library also ships an ESLint plugin whose rules apply to your project: see
|
|
24
30
|
[the plugin guide](ESLINT_PLUGIN.md).
|
|
@@ -44,7 +50,7 @@ Migration guides are available to provide an upgrade path from one major version
|
|
|
44
50
|
|
|
45
51
|
`@dsivd/prestations-ng` is part of [PrestaKit](https://www.vd.ch/prestakit/) and depends on `prestations-be`.
|
|
46
52
|
|
|
47
|
-
In order to use all the features of `@dsivd/
|
|
53
|
+
In order to use all the features of `@dsivd/prestations-ng`, you must use the same minor version of `prestations-be`, see [Notes about versioning in Prestakit](README_COMMON.md#notes-about-versioning-in-prestakit)
|
|
48
54
|
|
|
49
55
|
`prestations-be` is available on the DSI-VD Maven repository. An exemple of integration is available with [Eldorado](https://prestations.vd.ch/pub/101016).
|
|
50
56
|
|
package/UPGRADING_V19.md
CHANGED
|
@@ -259,6 +259,10 @@ ng update @angular/core@19 @angular/cli@19
|
|
|
259
259
|
ng update @dsivd/prestations-ng@18
|
|
260
260
|
```
|
|
261
261
|
|
|
262
|
+
🚨 **WARNING: `ng update` keeps the prefix of the version declared in your `package.json`. If it declares
|
|
263
|
+
`@dsivd/prestations-ng` with a caret (e.g. `"^18.3.16"`), replace it with a tilde (`"~18.3.16"`), then run
|
|
264
|
+
`npm install`: a minor version may break, as it goes with the same minor version of `prestations-be`.**
|
|
265
|
+
|
|
262
266
|
#### Switch to node 22+
|
|
263
267
|
|
|
264
268
|
##### If you are using our `slave-apps`
|
|
@@ -369,6 +373,10 @@ ng update @dsivd/prestations-ng@latest
|
|
|
369
373
|
- accept **"router-current-navigation"** by hitting "Space" key
|
|
370
374
|
- hit "Enter" key
|
|
371
375
|
|
|
376
|
+
🚨 **WARNING: `ng update` keeps the prefix of the version declared in your `package.json`. If it declares
|
|
377
|
+
`@dsivd/prestations-ng` with a caret (e.g. `"^19.1.4"`), replace it with a tilde (`"~19.1.4"`), then run
|
|
378
|
+
`npm install`: a minor version may break, as it goes with the same minor version of `prestations-be`.**
|
|
379
|
+
|
|
372
380
|
```bash
|
|
373
381
|
ng update @angular/cli@21
|
|
374
382
|
```
|
|
@@ -1709,6 +1717,34 @@ In the templates, it reads it through a `@let reference = this.reference();`, so
|
|
|
1709
1717
|
(`[reference]="reference"`). It removes a field of a page declaring `reference` again (e.g. `reference: string;`),
|
|
1710
1718
|
which would hide the signal, and lists such a field holding a value.
|
|
1711
1719
|
|
|
1720
|
+
The migration only adds the parentheses: the request still leaves when your code sends it, whatever the reference
|
|
1721
|
+
(`api/undefined/...` before the form is loaded), and isn't sent again when the reference changes. Turn a request built
|
|
1722
|
+
with the reference into a resource (see [AI_GUIDELINES.md](AI_GUIDELINES.md)), which waits for the reference and
|
|
1723
|
+
replaces the subscription, or the `async` pipe, and the fields that only served it. E.g. the sections of the
|
|
1724
|
+
verification page:
|
|
1725
|
+
|
|
1726
|
+
```ts
|
|
1727
|
+
readonly recapSections = httpResource<FoehnRecapSection[]>(
|
|
1728
|
+
() => {
|
|
1729
|
+
const reference = this.reference();
|
|
1730
|
+
return reference ? `api/${reference}/pdf-sections` : undefined;
|
|
1731
|
+
},
|
|
1732
|
+
{ defaultValue: [] },
|
|
1733
|
+
);
|
|
1734
|
+
```
|
|
1735
|
+
|
|
1736
|
+
```angular
|
|
1737
|
+
@if (recapSections.hasValue()) {
|
|
1738
|
+
@for (section of recapSections.value(); track $index) {
|
|
1739
|
+
<foehn-recap-section [data]="section" />
|
|
1740
|
+
}
|
|
1741
|
+
}
|
|
1742
|
+
```
|
|
1743
|
+
|
|
1744
|
+
A request built by a method of a service: an `rxResource()` over it, whose `params` return `undefined` while the
|
|
1745
|
+
reference is missing. See "`rxResource()`" in [INTRODUCTION_ANGULAR_SIGNALS.md](INTRODUCTION_ANGULAR_SIGNALS.md),
|
|
1746
|
+
for your specs too.
|
|
1747
|
+
|
|
1712
1748
|
For a code it doesn't migrate (a class it doesn't recognize as a page):
|
|
1713
1749
|
|
|
1714
1750
|
- in the templates, `no-uninvoked-signal-in-template` (`configs.templateRecommended` or `configs.templateRules`, see
|
|
@@ -1796,6 +1832,37 @@ too (`this.form.x` doesn't exist on a signal):
|
|
|
1796
1832
|
`*ngFor` to `@for` first (`ng generate @angular/core:control-flow`), then run the migration again;
|
|
1797
1833
|
- the `getList()` of the detail pages which compute their list, see below.
|
|
1798
1834
|
|
|
1835
|
+
It follows the getters of the page returning a path of the form, declared by the page or by a page it extends
|
|
1836
|
+
(since 19.2.0-beta.29, also in a page migrated by an earlier beta):
|
|
1837
|
+
|
|
1838
|
+
```diff
|
|
1839
|
+
get step(): Step {
|
|
1840
|
+
- return this.form.etape;
|
|
1841
|
+
+ return this.form()!.etape;
|
|
1842
|
+
}
|
|
1843
|
+
|
|
1844
|
+
- this.step.motif = value;
|
|
1845
|
+
+ this.patchForm(['etape', 'motif'], value);
|
|
1846
|
+
```
|
|
1847
|
+
|
|
1848
|
+
```diff
|
|
1849
|
+
- <foehn-input-text name="motif" [(model)]="step.motif" />
|
|
1850
|
+
+ <foehn-input-text name="motif" [model]="step.motif" (modelChange)="patchForm(['etape', 'motif'], $event)" />
|
|
1851
|
+
```
|
|
1852
|
+
|
|
1853
|
+
Since 19.2.0-beta.29, it also lists what the compiler doesn't report:
|
|
1854
|
+
|
|
1855
|
+
- the writes through a getter it can't rewrite, or through a getter computing its value
|
|
1856
|
+
(`return this.form?.etape ?? new Step();`): what such a getter returns may not be in the form. Write the form with
|
|
1857
|
+
`patchForm()`, the path of the field in full;
|
|
1858
|
+
- the `effect()`s reading the form, directly or through a method they call: the migration turns `this.form` into
|
|
1859
|
+
`this.form()` there too, and the effect then runs again at every input of the user. When the form isn't a trigger
|
|
1860
|
+
of the effect, read it with `untracked(this.form)`, or call the method in `untracked(() => this.applyResult(x))`;
|
|
1861
|
+
- the methods of the page writing the form or the reference called by its template outside an event
|
|
1862
|
+
(`@if (initDefaults())`, `[hidden]="!check()"`, `{{ total() }}`): a signal written while the view is rendered
|
|
1863
|
+
throws NG0600. Make them pure, and write the form where it is loaded (see "`(modelChange)` is emitted only when
|
|
1864
|
+
the component writes its model").
|
|
1865
|
+
|
|
1799
1866
|
Also check:
|
|
1800
1867
|
|
|
1801
1868
|
- your specs, which the migration doesn't change: `component.form = x` becomes `component.form.set(x)`, and
|
|
@@ -1814,7 +1881,8 @@ Also check:
|
|
|
1814
1881
|
not those of a callback given to a service.
|
|
1815
1882
|
|
|
1816
1883
|
`no-direct-signal-mutation` reports the writes in place left (`this.form()!.x = 1`, `form.children.push(child)`),
|
|
1817
|
-
`[(model)]="form.x"` inside `@if (form(); as form)` included.
|
|
1884
|
+
`[(model)]="form.x"` inside `@if (form(); as form)` included, and since 19.2.0-beta.29 those through a getter of the
|
|
1885
|
+
page returning the form or a part of it (`this.step.motif = x`, `[(model)]="step.motif"`).
|
|
1818
1886
|
|
|
1819
1887
|
#### Lists of the form
|
|
1820
1888
|
|
|
@@ -8,7 +8,7 @@ import {
|
|
|
8
8
|
VIEW_QUERY,
|
|
9
9
|
WRITABLE,
|
|
10
10
|
} from "../signal-kinds.mjs";
|
|
11
|
-
import { collectSignalKinds } from "../signal-names.mjs";
|
|
11
|
+
import { collectSignalAliases, collectSignalKinds } from "../signal-names.mjs";
|
|
12
12
|
import {
|
|
13
13
|
handlerExpressionOf,
|
|
14
14
|
isComponentReceiver,
|
|
@@ -30,6 +30,10 @@ import {
|
|
|
30
30
|
*
|
|
31
31
|
* Only the signals the class really declares are inspected, resolved through the whole
|
|
32
32
|
* inheritance chain, so a plain method (`this.getConfig().items.push(x)`) is left alone.
|
|
33
|
+
*
|
|
34
|
+
* A getter of the class returning the value of a signal, or a part of it
|
|
35
|
+
* (`get step() { return this.form()!.step; }`), hands out that value too: a write through
|
|
36
|
+
* it (`this.step.motif = x`, `[(model)]="step.motif"`) is reported as well.
|
|
33
37
|
*/
|
|
34
38
|
|
|
35
39
|
// Kinds a mutation is not reported on: a view query hands out a DOM element or a component
|
|
@@ -201,6 +205,33 @@ function signalFactoryKind(node) {
|
|
|
201
205
|
return callee?.type === "Identifier" ? factoryKind(callee.name) : undefined;
|
|
202
206
|
}
|
|
203
207
|
|
|
208
|
+
// The value of a signal of the class: its kind, and the getter it was read through, if any.
|
|
209
|
+
const valueOf = (kind) => (kind ? { kind } : undefined);
|
|
210
|
+
|
|
211
|
+
/**
|
|
212
|
+
* The getter of the class a member chain reads first, `this.step` in `this.step.motif`,
|
|
213
|
+
* when it aliases the value of a signal. `undefined` for anything else.
|
|
214
|
+
*/
|
|
215
|
+
function aliasReadOf(node, scopeContext) {
|
|
216
|
+
let current = node;
|
|
217
|
+
while (
|
|
218
|
+
current?.type === "MemberExpression" ||
|
|
219
|
+
TYPE_WRAPPERS.has(current?.type)
|
|
220
|
+
) {
|
|
221
|
+
if (
|
|
222
|
+
current.type === "MemberExpression" &&
|
|
223
|
+
current.object.type === "ThisExpression"
|
|
224
|
+
) {
|
|
225
|
+
const name = current.computed ? undefined : getCalledName(current);
|
|
226
|
+
const alias = name ? scopeContext.alias(name) : undefined;
|
|
227
|
+
return alias ? { ...alias, getter: name } : undefined;
|
|
228
|
+
}
|
|
229
|
+
current =
|
|
230
|
+
current.type === "MemberExpression" ? current.object : current.expression;
|
|
231
|
+
}
|
|
232
|
+
return undefined;
|
|
233
|
+
}
|
|
234
|
+
|
|
204
235
|
function signalRootCallKind(node, scopeContext) {
|
|
205
236
|
if (node.arguments.length !== 0) {
|
|
206
237
|
return undefined;
|
|
@@ -233,14 +264,18 @@ function signalRootCallKind(node, scopeContext) {
|
|
|
233
264
|
}
|
|
234
265
|
|
|
235
266
|
/**
|
|
236
|
-
*
|
|
237
|
-
* The expression may be the signal read itself (`this.model()`), a member of
|
|
238
|
-
* (`this.model().items`),
|
|
267
|
+
* The value of a signal an expression evaluates to (`{ kind, getter? }`), `undefined` when
|
|
268
|
+
* it is not one. The expression may be the signal read itself (`this.model()`), a member of
|
|
269
|
+
* its value (`this.model().items`), a getter aliasing either (`this.step.items`), or a name
|
|
270
|
+
* bound to any of them.
|
|
239
271
|
*/
|
|
240
272
|
function signalValueKind(node, scopeContext, seen = new Set()) {
|
|
241
273
|
const base = baseOf(node);
|
|
242
274
|
if (base?.type === "CallExpression") {
|
|
243
|
-
return signalRootCallKind(base, scopeContext);
|
|
275
|
+
return valueOf(signalRootCallKind(base, scopeContext));
|
|
276
|
+
}
|
|
277
|
+
if (base?.type === "ThisExpression") {
|
|
278
|
+
return aliasReadOf(node, scopeContext);
|
|
244
279
|
}
|
|
245
280
|
return base?.type === "Identifier"
|
|
246
281
|
? boundNameSignalKind(base, scopeContext, seen)
|
|
@@ -314,7 +349,7 @@ function signalRootTemplateCallKind(node, templateContext) {
|
|
|
314
349
|
return undefined;
|
|
315
350
|
}
|
|
316
351
|
return isComponentReceiver(callee.receiver)
|
|
317
|
-
? templateContext.memberKind(callee.name ?? "")
|
|
352
|
+
? valueOf(templateContext.memberKind(callee.name ?? ""))
|
|
318
353
|
: undefined;
|
|
319
354
|
}
|
|
320
355
|
|
|
@@ -352,10 +387,19 @@ function boundTemplateExpression(read, templateContext) {
|
|
|
352
387
|
}
|
|
353
388
|
|
|
354
389
|
/**
|
|
355
|
-
* Template counterpart of `signalValueKind`: the value a signal holds, a member of it,
|
|
356
|
-
* a template name bound to
|
|
390
|
+
* Template counterpart of `signalValueKind`: the value a signal holds, a member of it, a
|
|
391
|
+
* getter of the component aliasing either, or a template name bound to any of them.
|
|
392
|
+
*
|
|
393
|
+
* `assigned`: the expression is the target of an assignment (`step.motif = x`, or the
|
|
394
|
+
* expression of a two-way binding), so the getter itself as the whole target
|
|
395
|
+
* (`step = x`) calls its setter and mutates nothing.
|
|
357
396
|
*/
|
|
358
|
-
function signalTemplateValueKind(
|
|
397
|
+
function signalTemplateValueKind(
|
|
398
|
+
node,
|
|
399
|
+
templateContext,
|
|
400
|
+
seen = new Set(),
|
|
401
|
+
assigned = false,
|
|
402
|
+
) {
|
|
359
403
|
const value = unwrapTemplate(node);
|
|
360
404
|
if (value?.type === "Call" || value?.type === "SafeCall") {
|
|
361
405
|
return signalRootTemplateCallKind(value, templateContext);
|
|
@@ -379,11 +423,15 @@ function signalTemplateValueKind(node, templateContext, seen = new Set()) {
|
|
|
379
423
|
return undefined;
|
|
380
424
|
}
|
|
381
425
|
seen.add(base.name);
|
|
382
|
-
|
|
383
|
-
|
|
384
|
-
|
|
385
|
-
|
|
386
|
-
|
|
426
|
+
const bound = boundTemplateExpression(base, templateContext);
|
|
427
|
+
if (bound === undefined) {
|
|
428
|
+
// A member of the component, not shadowed by a name of the template.
|
|
429
|
+
const alias = templateContext.alias(base.name);
|
|
430
|
+
return alias && (value !== base || !assigned)
|
|
431
|
+
? { ...alias, getter: base.name }
|
|
432
|
+
: undefined;
|
|
433
|
+
}
|
|
434
|
+
return signalTemplateValueKind(bound, templateContext, seen);
|
|
387
435
|
}
|
|
388
436
|
|
|
389
437
|
// Method a template call invokes, `undefined` when the name is not statically known.
|
|
@@ -413,6 +461,8 @@ export default {
|
|
|
413
461
|
"In-place mutation of a signal's value detected. `{{method}}` changes the value without notifying the signal: use .update() with a new value instead.",
|
|
414
462
|
readOnlyMutation:
|
|
415
463
|
"Mutation of the value of {{kind}} detected, which notifies none of its dependents. {{advice}}.",
|
|
464
|
+
getterMutation:
|
|
465
|
+
"Mutation of the value of {{signal}} through the getter `{{getter}}` detected, which notifies none of its dependents. {{advice}}.",
|
|
416
466
|
},
|
|
417
467
|
},
|
|
418
468
|
|
|
@@ -422,18 +472,41 @@ export default {
|
|
|
422
472
|
const declaringPath =
|
|
423
473
|
resolveComponentPath(context.filename) ?? context.filename;
|
|
424
474
|
const memberKinds = collectSignalKinds(declaringPath);
|
|
475
|
+
const aliases = collectSignalAliases(declaringPath);
|
|
425
476
|
|
|
426
477
|
// `memberKinds` is undefined when the declaring file could not be read: its signals
|
|
427
478
|
// are unknown, so fall back to treating every argument-less accessor as a writable
|
|
428
|
-
// one. A false positive costs a disable comment; a missed mutation is silent.
|
|
479
|
+
// one. A false positive costs a disable comment; a missed mutation is silent. Its
|
|
480
|
+
// getters are unknown too: none is taken for an alias.
|
|
429
481
|
const memberKind = (name) =>
|
|
430
482
|
memberKinds ? memberKinds.get(name) : WRITABLE;
|
|
483
|
+
const alias = (name) => aliases?.get(name);
|
|
431
484
|
|
|
432
|
-
const reportMutation = (node,
|
|
485
|
+
const reportMutation = (node, value, method) => {
|
|
486
|
+
const kind = value?.kind;
|
|
433
487
|
if (!kind || TOLERATED_KINDS.has(kind)) {
|
|
434
488
|
return;
|
|
435
489
|
}
|
|
436
|
-
if (
|
|
490
|
+
if (value.getter) {
|
|
491
|
+
const [name, advice] =
|
|
492
|
+
kind === WRITABLE
|
|
493
|
+
? [
|
|
494
|
+
"the signal",
|
|
495
|
+
method
|
|
496
|
+
? `\`${method}\` changes it in place: write a new value with .set() or .update() instead (patchForm() for the form of a page)`
|
|
497
|
+
: "Write a new value with .set() or .update() instead (patchForm() for the form of a page)",
|
|
498
|
+
]
|
|
499
|
+
: READ_ONLY_ADVICE[kind];
|
|
500
|
+
context.report({
|
|
501
|
+
node,
|
|
502
|
+
messageId: "getterMutation",
|
|
503
|
+
data: {
|
|
504
|
+
signal: `${name} \`${value.signal}\``,
|
|
505
|
+
getter: value.getter,
|
|
506
|
+
advice,
|
|
507
|
+
},
|
|
508
|
+
});
|
|
509
|
+
} else if (kind !== WRITABLE) {
|
|
437
510
|
const [name, advice] = READ_ONLY_ADVICE[kind];
|
|
438
511
|
context.report({
|
|
439
512
|
node,
|
|
@@ -447,9 +520,9 @@ export default {
|
|
|
447
520
|
}
|
|
448
521
|
};
|
|
449
522
|
|
|
450
|
-
const scopeContext = { memberKind, sourceCode: context.sourceCode };
|
|
523
|
+
const scopeContext = { memberKind, alias, sourceCode: context.sourceCode };
|
|
451
524
|
// `@let` bindings, always declared before they are used.
|
|
452
|
-
const templateContext = { memberKind, letBindings: new Map() };
|
|
525
|
+
const templateContext = { memberKind, alias, letBindings: new Map() };
|
|
453
526
|
|
|
454
527
|
const checkTemplateInPlaceCall = (node) => {
|
|
455
528
|
const method = templateMethodName(node.receiver);
|
|
@@ -471,6 +544,16 @@ export default {
|
|
|
471
544
|
}
|
|
472
545
|
},
|
|
473
546
|
|
|
547
|
+
// `this.model().count++` writes into the value, like `+= 1`.
|
|
548
|
+
UpdateExpression(node) {
|
|
549
|
+
if (node.argument.type === "MemberExpression") {
|
|
550
|
+
reportMutation(
|
|
551
|
+
node,
|
|
552
|
+
signalValueKind(node.argument.object, scopeContext),
|
|
553
|
+
);
|
|
554
|
+
}
|
|
555
|
+
},
|
|
556
|
+
|
|
474
557
|
UnaryExpression(node) {
|
|
475
558
|
// `delete model().users[0]` drops an entry of the value, notifying nothing.
|
|
476
559
|
if (
|
|
@@ -519,7 +602,7 @@ export default {
|
|
|
519
602
|
if (TEMPLATE_ASSIGNMENTS.has(node.operation)) {
|
|
520
603
|
reportMutation(
|
|
521
604
|
node,
|
|
522
|
-
signalTemplateValueKind(node.left, templateContext),
|
|
605
|
+
signalTemplateValueKind(node.left, templateContext, new Set(), true),
|
|
523
606
|
);
|
|
524
607
|
}
|
|
525
608
|
},
|
|
@@ -537,7 +620,7 @@ export default {
|
|
|
537
620
|
const handler = handlerExpressionOf(node);
|
|
538
621
|
reportMutation(
|
|
539
622
|
handler,
|
|
540
|
-
signalTemplateValueKind(handler, templateContext),
|
|
623
|
+
signalTemplateValueKind(handler, templateContext, new Set(), true),
|
|
541
624
|
);
|
|
542
625
|
},
|
|
543
626
|
};
|