@dsivd/prestations-ng 19.2.0-beta.27 → 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 +30 -9
- package/ANGULAR_SIGNALS.md +2 -2
- package/CHANGELOG.md +51 -3
- package/CONTRIBUTING.md +54 -12
- package/ESLINT_PLUGIN.md +110 -13
- package/GOOD_PRACTICES.md +34 -10
- package/README.md +18 -12
- package/UPGRADING_V19.md +154 -7
- package/eslint/configs/template-rules.mjs +3 -0
- package/eslint/rules/index.mjs +2 -0
- package/eslint/rules/no-direct-signal-mutation.mjs +104 -21
- package/eslint/rules/no-item-track-in-form-list.mjs +4 -3
- package/eslint/rules/require-track-index.mjs +162 -0
- package/eslint/signal-names.mjs +127 -21
- package/fesm2022/dsivd-prestations-ng.mjs +68 -22
- package/fesm2022/dsivd-prestations-ng.mjs.map +1 -1
- package/package.json +1 -1
- package/schematics/migration-collection.json +1 -1
- package/schematics/ng-update/migrations/update-19_2_0/index.js +15 -3
- 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 +13 -75
- package/schematics/utility/form-signal/page-classes.js +11 -1
- package/schematics/utility/form-signal/template-migration.js +119 -10
- package/schematics/utility/never-connected-migration.js +87 -0
- package/schematics/utility/typescript-files.js +95 -0
- package/src/eslint/configs/template-rules.mjs +3 -0
- package/src/eslint/rules/__tests__/no-direct-signal-mutation.test.mjs +142 -0
- package/src/eslint/rules/__tests__/require-track-index.test.mjs +106 -0
- package/src/eslint/rules/index.mjs +2 -0
- package/src/eslint/rules/no-direct-signal-mutation.mjs +104 -21
- package/src/eslint/rules/no-item-track-in-form-list.mjs +4 -3
- package/src/eslint/rules/require-track-index.mjs +162 -0
- package/src/eslint/signal-names.mjs +127 -21
- package/types/dsivd-prestations-ng.d.ts +19 -3
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`
|
|
@@ -308,10 +312,11 @@ ng update @angular/core@20 @angular/cli@20
|
|
|
308
312
|
- accept **"router-current-navigation"** by hitting "Space" key
|
|
309
313
|
- hit "Enter" key
|
|
310
314
|
|
|
311
|
-
🚨 **IMPORTANT: Search for every `@for` in your project and check that `track` statement is present
|
|
312
|
-
|
|
313
|
-
|
|
314
|
-
|
|
315
|
+
🚨 **IMPORTANT: Search for every `@for` in your project and check that `track` statement is present. Track by
|
|
316
|
+
`$index` the rows naming their fields with the index (`[name]="'children[' + $index + '].firstName'"`, every list of
|
|
317
|
+
the form): tracked by an identifier, a row whose item moves keeps the names of its former position and gets the
|
|
318
|
+
values and the errors of another row (`require-track-index`, since 19.2.0). Since 19.2.0, never track by object a list
|
|
319
|
+
of the form whose rows edit their item (see "The form of your pages is a signal").**
|
|
315
320
|
|
|
316
321
|
💡 **NB: When using `@angular/cdk` in your project**
|
|
317
322
|
|
|
@@ -368,6 +373,10 @@ ng update @dsivd/prestations-ng@latest
|
|
|
368
373
|
- accept **"router-current-navigation"** by hitting "Space" key
|
|
369
374
|
- hit "Enter" key
|
|
370
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
|
+
|
|
371
380
|
```bash
|
|
372
381
|
ng update @angular/cli@21
|
|
373
382
|
```
|
|
@@ -394,6 +403,55 @@ ng update ngx-matomo-client@9
|
|
|
394
403
|
|
|
395
404
|
💡 **NB: Upgrade all other libraries needed by your project (such as: primeng, lodash, ...) to their latest version compatible with angular 21**
|
|
396
405
|
|
|
406
|
+
### Instructions for your AI assistant (since 19.2.0)
|
|
407
|
+
|
|
408
|
+
The library ships [AI_GUIDELINES.md](AI_GUIDELINES.md): the rules an AI assistant (Claude Code, GitHub Copilot...)
|
|
409
|
+
follows in a project using it, for the version installed. Give them to your assistant now, so that it follows them
|
|
410
|
+
for the rest of this migration. The versions before 19.2.0 (e.g. 19.1.x) don't have the file: skip this step, and come
|
|
411
|
+
back to it once you upgrade to 19.2.0.
|
|
412
|
+
|
|
413
|
+
At the root of the project holding the front (not in the `front` folder):
|
|
414
|
+
|
|
415
|
+
1. For Claude Code, create the `.claude` folder and its `CLAUDE.md` file if they don't exist, and add the import of
|
|
416
|
+
the file, its path being relative to `CLAUDE.md`:
|
|
417
|
+
|
|
418
|
+
```text
|
|
419
|
+
@../front/node_modules/@dsivd/prestations-ng/AI_GUIDELINES.md
|
|
420
|
+
```
|
|
421
|
+
|
|
422
|
+
2. For the other assistants (GitHub Copilot, Codex, Cursor...), create the `AGENTS.md` file if it doesn't exist, and
|
|
423
|
+
add this sentence to it: they read `AGENTS.md`, but can't import a file.
|
|
424
|
+
|
|
425
|
+
```text
|
|
426
|
+
Before changing the front, read and follow `front/node_modules/@dsivd/prestations-ng/AI_GUIDELINES.md`:
|
|
427
|
+
the rules of the installed version of `@dsivd/prestations-ng`.
|
|
428
|
+
```
|
|
429
|
+
|
|
430
|
+
Then:
|
|
431
|
+
|
|
432
|
+
- The project is your repository or, in a repository holding several projects (e.g. `my-project-fo/front` and
|
|
433
|
+
`my-project-bo/front`), the folder of each one: each project gets its own `.claude/CLAUDE.md` and `AGENTS.md`, with
|
|
434
|
+
the rules of its version of `prestations-ng`. Claude Code loads `.claude/CLAUDE.md` when it's started in the
|
|
435
|
+
project or one of its folders (e.g. `front`) or, started at the root of the repository, as soon as it reads a file
|
|
436
|
+
of the project.
|
|
437
|
+
- If the project already has a `CLAUDE.md` at its root, add the import there rather than creating a second file:
|
|
438
|
+
`@front/node_modules/@dsivd/prestations-ng/AI_GUIDELINES.md`.
|
|
439
|
+
- A project with several fronts, or an Angular library shared by the fronts of the repository: both files in the
|
|
440
|
+
folder of each one, next to its `node_modules`, with `@../node_modules/@dsivd/prestations-ng/AI_GUIDELINES.md` and
|
|
441
|
+
`node_modules/@dsivd/prestations-ng/AI_GUIDELINES.md`.
|
|
442
|
+
- Keep the import in `.claude/CLAUDE.md` even with `AGENTS.md`: Claude Code reads `AGENTS.md` only in a folder
|
|
443
|
+
without `CLAUDE.md`, and not in every mode.
|
|
444
|
+
- An import loads nothing until the dependencies of its front are installed (`npm ci` after a clone): until then,
|
|
445
|
+
your assistant doesn't have the rules.
|
|
446
|
+
- Commit `.claude/CLAUDE.md` and `AGENTS.md`, so that the whole team gets the rules, but not the permissions each
|
|
447
|
+
developer grants to Claude Code for the project, which it keeps in `.claude/settings.local.json`: add
|
|
448
|
+
`**/.claude/settings.local.json` to the `.gitignore` of your repository.
|
|
449
|
+
- Refer to the file rather than copying it: the rules follow the version installed at each upgrade, those of
|
|
450
|
+
Renovate included, without changing your files.
|
|
451
|
+
|
|
452
|
+
💡 **NB: The rules describe the code once migrated. Your assistant follows the steps of this guide in order, without
|
|
453
|
+
anticipating the next ones: `AI_GUIDELINES.md` tells it so.**
|
|
454
|
+
|
|
397
455
|
### Quick fix
|
|
398
456
|
|
|
399
457
|
- In all custom components extending `FoehnInputComponent`, in `providers` providing `FoehnInputComponent` remove `multi: true,`.
|
|
@@ -1603,6 +1661,20 @@ removed item stays in the form and comes back when the form is saved. In a page,
|
|
|
1603
1661
|
}
|
|
1604
1662
|
```
|
|
1605
1663
|
|
|
1664
|
+
### `FoehnListItem` has no `trackingIndex` (since 19.2.0)
|
|
1665
|
+
|
|
1666
|
+
The library tracks the rows of a list by their index (see `require-track-index` in [ESLINT_PLUGIN.md](ESLINT_PLUGIN.md)):
|
|
1667
|
+
`FoehnListItem.trackingIndex` is removed, and `AbstractListDetailPageComponent` no longer sets it on a new item
|
|
1668
|
+
(`getNextTrackingIndex()` is removed too). The id of a row of `foehn-list-summary` is `list-summary-<its position
|
|
1669
|
+
from 1>`.
|
|
1670
|
+
|
|
1671
|
+
- Track your lists by `$index`, not by `item.trackingIndex`.
|
|
1672
|
+
- The code reading `trackingIndex` on an item typed with `FoehnListItem`, or calling or overriding
|
|
1673
|
+
`getNextTrackingIndex()`, no longer compiles: remove it.
|
|
1674
|
+
- 🚨 Nothing reports a backend needing the field (e.g. a `@NotNull trackingIndex`, a list sorted by it): a new item
|
|
1675
|
+
now reaches it without one. Remove the field from the backend and from its data, or, to keep it, declare it in your
|
|
1676
|
+
item class and set it in `getNewListItem()`.
|
|
1677
|
+
|
|
1606
1678
|
### `core-js` is no longer needed (since 19.2.0)
|
|
1607
1679
|
|
|
1608
1680
|
prestations-ng no longer imports `core-js` and no longer has it as a peer dependency. If your project does not
|
|
@@ -1645,6 +1717,34 @@ In the templates, it reads it through a `@let reference = this.reference();`, so
|
|
|
1645
1717
|
(`[reference]="reference"`). It removes a field of a page declaring `reference` again (e.g. `reference: string;`),
|
|
1646
1718
|
which would hide the signal, and lists such a field holding a value.
|
|
1647
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
|
+
|
|
1648
1748
|
For a code it doesn't migrate (a class it doesn't recognize as a page):
|
|
1649
1749
|
|
|
1650
1750
|
- in the templates, `no-uninvoked-signal-in-template` (`configs.templateRecommended` or `configs.templateRules`, see
|
|
@@ -1732,6 +1832,37 @@ too (`this.form.x` doesn't exist on a signal):
|
|
|
1732
1832
|
`*ngFor` to `@for` first (`ng generate @angular/core:control-flow`), then run the migration again;
|
|
1733
1833
|
- the `getList()` of the detail pages which compute their list, see below.
|
|
1734
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
|
+
|
|
1735
1866
|
Also check:
|
|
1736
1867
|
|
|
1737
1868
|
- your specs, which the migration doesn't change: `component.form = x` becomes `component.form.set(x)`, and
|
|
@@ -1750,14 +1881,16 @@ Also check:
|
|
|
1750
1881
|
not those of a callback given to a service.
|
|
1751
1882
|
|
|
1752
1883
|
`no-direct-signal-mutation` reports the writes in place left (`this.form()!.x = 1`, `form.children.push(child)`),
|
|
1753
|
-
`[(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"`).
|
|
1754
1886
|
|
|
1755
1887
|
#### Lists of the form
|
|
1756
1888
|
|
|
1757
1889
|
`patchForm()` replaces each object along the path with a copy: a row of a `@for` tracked by its item (`track child`)
|
|
1758
1890
|
is then destroyed and created again at each input, and the field being edited loses the focus. Track the rows of a
|
|
1759
|
-
list edited by its rows by an identifier of the item
|
|
1760
|
-
lists it migrates, and `no-item-track-in-form-list`
|
|
1891
|
+
list edited by its rows by `$index`, the index naming their fields (an identifier of the item, `track child.id`, only
|
|
1892
|
+
when they name nothing with it). The migration does it for the lists it migrates, and `no-item-track-in-form-list`
|
|
1893
|
+
and `require-track-index` (`configs.templateRecommended`) report the others.
|
|
1761
1894
|
|
|
1762
1895
|
#### Write your templates
|
|
1763
1896
|
|
|
@@ -1807,6 +1940,20 @@ getListPath(): ObjectPath<ApForm | AfForm> {
|
|
|
1807
1940
|
}
|
|
1808
1941
|
```
|
|
1809
1942
|
|
|
1943
|
+
### `neverConnected` is provided with `NEVER_CONNECTED` (since 19.2.0)
|
|
1944
|
+
|
|
1945
|
+
`SessionInfo` reads the `NEVER_CONNECTED` token: a provider `{ provide: 'neverConnected', useValue: true }` is ignored
|
|
1946
|
+
without any error, and your application fetches the session and displays the connected user or the login button.
|
|
1947
|
+
`ng update @dsivd/prestations-ng` replaces it (see "Run the migration" above to run it by hand):
|
|
1948
|
+
|
|
1949
|
+
```diff
|
|
1950
|
+
- { provide: 'neverConnected', useValue: true },
|
|
1951
|
+
+ { provide: NEVER_CONNECTED, useValue: true },
|
|
1952
|
+
```
|
|
1953
|
+
|
|
1954
|
+
with `NEVER_CONNECTED` imported from `@dsivd/prestations-ng`. It lists the other uses of the string `'neverConnected'`
|
|
1955
|
+
it doesn't rewrite: search them in your providers, e.g. a value coming from a constant or a shared library.
|
|
1956
|
+
|
|
1810
1957
|
### Zoneless (optional but recommended)
|
|
1811
1958
|
|
|
1812
1959
|
Since v19.2, prestations-ng does not need zone.js anymore: the state of its components is held by signals, which
|
|
@@ -20,6 +20,9 @@ const templateRules = (plugin) => [
|
|
|
20
20
|
// loses the focus at every input
|
|
21
21
|
'@dsivd/prestations-ng/require-model-change': 'error',
|
|
22
22
|
'@dsivd/prestations-ng/no-item-track-in-form-list': 'error',
|
|
23
|
+
// The rows naming their fields with their index keep these names
|
|
24
|
+
// only when tracked by $index
|
|
25
|
+
'@dsivd/prestations-ng/require-track-index': 'error',
|
|
23
26
|
},
|
|
24
27
|
},
|
|
25
28
|
];
|
package/eslint/rules/index.mjs
CHANGED
|
@@ -2,10 +2,12 @@ import noDirectSignalMutation from './no-direct-signal-mutation.mjs';
|
|
|
2
2
|
import noItemTrackInFormList from './no-item-track-in-form-list.mjs';
|
|
3
3
|
import noUninvokedSignalInTemplate from './no-uninvoked-signal-in-template.mjs';
|
|
4
4
|
import requireModelChange from './require-model-change.mjs';
|
|
5
|
+
import requireTrackIndex from './require-track-index.mjs';
|
|
5
6
|
|
|
6
7
|
export default {
|
|
7
8
|
'no-direct-signal-mutation': noDirectSignalMutation,
|
|
8
9
|
'no-item-track-in-form-list': noItemTrackInFormList,
|
|
9
10
|
'no-uninvoked-signal-in-template': noUninvokedSignalInTemplate,
|
|
10
11
|
'require-model-change': requireModelChange,
|
|
12
|
+
'require-track-index': requireTrackIndex,
|
|
11
13
|
};
|
|
@@ -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
|
};
|
|
@@ -11,8 +11,9 @@ import { astOf, resolveRoot } from "../form-reads.mjs";
|
|
|
11
11
|
* `FoehnInputComponent` writes a new list in its model, its items replaced (`updateNgModel()`).
|
|
12
12
|
* A row tracked by its item is then destroyed and created again at every input, and the field
|
|
13
13
|
* being edited loses the focus; two items equal by value (e.g. two empty strings) even collide.
|
|
14
|
-
* Track the rows by `$index
|
|
15
|
-
*
|
|
14
|
+
* Track the rows by `$index`: an identifier of the item (`track child.id`), which the copy keeps,
|
|
15
|
+
* only when the rows name nothing with their index (see `require-track-index`, which reports
|
|
16
|
+
* these lists too when they do).
|
|
16
17
|
*
|
|
17
18
|
* A row edits its item when one of its elements has a `model` read from it
|
|
18
19
|
* (`[model]="child.firstName"`, `[(model)]="child"`), or read from the list at the index of
|
|
@@ -108,7 +109,7 @@ export default {
|
|
|
108
109
|
schema: [],
|
|
109
110
|
messages: {
|
|
110
111
|
itemTrack:
|
|
111
|
-
"The rows of this list are tracked by their item ('track {{item}}'): writing an item replaces it, so its row is created again and the field being edited loses the focus. Track the rows by $index
|
|
112
|
+
"The rows of this list are tracked by their item ('track {{item}}'): writing an item replaces it, so its row is created again and the field being edited loses the focus. Track the rows by $index (by an identifier of the item only when the rows name nothing with their index).",
|
|
112
113
|
trackByIndex: "Track the rows by $index",
|
|
113
114
|
},
|
|
114
115
|
},
|