@dsivd/prestations-ng 19.2.0-beta.20 → 19.2.0-beta.21
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/ANGULAR_SIGNALS.md +4 -0
- package/CHANGELOG.md +98 -3
- package/CONTRIBUTING.md +2 -2
- package/ESLINT_PLUGIN.md +103 -8
- package/GOOD_PRACTICES.md +79 -29
- package/UPGRADING_V19.md +187 -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 +99 -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 +907 -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 +396 -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 +127 -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 +99 -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 +234 -35
package/UPGRADING_V19.md
CHANGED
|
@@ -309,7 +309,9 @@ ng update @angular/core@20 @angular/cli@20
|
|
|
309
309
|
- hit "Enter" key
|
|
310
310
|
|
|
311
311
|
🚨 **IMPORTANT: Search for every `@for` in your project and check that `track` statement is present and has a unique identifier.
|
|
312
|
-
When a unique identifier such as `id` is not possible, track by object or as a last resort use `track $index
|
|
312
|
+
When a unique identifier such as `id` is not possible, track by object or as a last resort use `track $index`. Since
|
|
313
|
+
19.2.0, never track by object a list of the form whose rows edit their item: track it by `id` or by `$index` (see
|
|
314
|
+
"The form of your pages is a signal").**
|
|
313
315
|
|
|
314
316
|
💡 **NB: When using `@angular/cdk` in your project**
|
|
315
317
|
|
|
@@ -1174,10 +1176,10 @@ fail outright.
|
|
|
1174
1176
|
|
|
1175
1177
|
#### prestations-ng ESLint rules
|
|
1176
1178
|
|
|
1177
|
-
The library ships **shareable custom configs** that are auto-updatable with the library version.
|
|
1178
|
-
rules are enabled today — `no-direct-signal-mutation
|
|
1179
|
-
|
|
1180
|
-
configs for a project that supplies its own style.
|
|
1179
|
+
The library ships **shareable custom configs** that are auto-updatable with the library version. Four
|
|
1180
|
+
rules are enabled today — `no-direct-signal-mutation`, `no-uninvoked-signal-in-template`, and, since 19.2.0,
|
|
1181
|
+
`require-model-change` and `no-item-track-in-form-list` — all documented in [the plugin guide](ESLINT_PLUGIN.md),
|
|
1182
|
+
alongside the leaner `tsRules` / `templateRules` configs for a project that supplies its own style.
|
|
1181
1183
|
|
|
1182
1184
|
One consequence to keep in mind:
|
|
1183
1185
|
|
|
@@ -1551,16 +1553,17 @@ getListItemsDescription(): FoehnListItemDescription<MyItem>[] {
|
|
|
1551
1553
|
|
|
1552
1554
|
The same applies to the function passed to `getListItemTitle`, which now receives a `MyItem`.
|
|
1553
1555
|
|
|
1554
|
-
|
|
1555
|
-
|
|
1556
|
-
|
|
1557
|
-
|
|
1556
|
+
Never bind the list with a one-way `[model]` alone (see also "Quick fix"): the component removes the items itself,
|
|
1557
|
+
and only its `modelChange` passes the new list to your form. A one-way `[model]` compiles without warning, but the
|
|
1558
|
+
removed item stays in the form and comes back when the form is saved. In a page, whose form is a signal since 19.2.0
|
|
1559
|
+
(see "The form of your pages is a signal"), write the list with `patchForm()`, the form guarded:
|
|
1558
1560
|
|
|
1559
1561
|
```html
|
|
1560
|
-
@if (form) {
|
|
1562
|
+
@if (form(); as form) {
|
|
1561
1563
|
<foehn-list-summary
|
|
1562
1564
|
name="items"
|
|
1563
|
-
[
|
|
1565
|
+
[model]="form.items"
|
|
1566
|
+
(modelChange)="patchForm(['items'], $event)"
|
|
1564
1567
|
(itemRemoved)="itemRemoved()"
|
|
1565
1568
|
/>
|
|
1566
1569
|
}
|
|
@@ -1585,6 +1588,176 @@ The CommonJS dependencies of prestations-ng are now `"iban"` and `"dayjs"` (whic
|
|
|
1585
1588
|
|
|
1586
1589
|
Also remove the packages that are no longer installed (`npm ls <package>` lists nothing).
|
|
1587
1590
|
|
|
1591
|
+
### `reference` of your pages is a signal (since 19.2.0)
|
|
1592
|
+
|
|
1593
|
+
`reference` of `AbstractPageComponent` is now a `WritableSignal<string | null | undefined>`: read it with
|
|
1594
|
+
`reference()`, in the templates of your pages too, and write it with `reference.set()`. A template, a `computed()` or
|
|
1595
|
+
an `effect()` reading it follows the reference, also when your page sets it, without `markForCheck()`.
|
|
1596
|
+
|
|
1597
|
+
The `ng update` migration of 19.2.0 rewrites your pages (see "Run the migration" in "The form of your pages is a
|
|
1598
|
+
signal" below):
|
|
1599
|
+
|
|
1600
|
+
```diff
|
|
1601
|
+
- this.http.get<FoehnRecapSection[]>(`api/${this.reference}/pdf-sections`)
|
|
1602
|
+
+ this.http.get<FoehnRecapSection[]>(`api/${this.reference()}/pdf-sections`)
|
|
1603
|
+
```
|
|
1604
|
+
|
|
1605
|
+
```diff
|
|
1606
|
+
- this.reference = reference;
|
|
1607
|
+
+ this.reference.set(reference);
|
|
1608
|
+
```
|
|
1609
|
+
|
|
1610
|
+
In the templates, it reads it through a `@let reference = this.reference();`, so that the reads are unchanged
|
|
1611
|
+
(`[reference]="reference"`). It removes a field of a page declaring `reference` again (e.g. `reference: string;`),
|
|
1612
|
+
which would hide the signal, and lists such a field holding a value.
|
|
1613
|
+
|
|
1614
|
+
For a code it doesn't migrate (a class it doesn't recognize as a page):
|
|
1615
|
+
|
|
1616
|
+
- in the templates, `no-uninvoked-signal-in-template` (`configs.templateRecommended` or `configs.templateRules`, see
|
|
1617
|
+
[ESLINT_PLUGIN.md](ESLINT_PLUGIN.md)) reports `reference` without parentheses, and `ng lint --fix` adds them;
|
|
1618
|
+
- in TypeScript, the compiler reports the writes (`this.reference = ...`) and the arguments typed `string`. With
|
|
1619
|
+
`configs.tsRecommended`, `no-uncalled-signals` reports `!this.reference`, `this.reference && ...`,
|
|
1620
|
+
`'...' + this.reference` and `this.reference?.length`, and `restrict-template-expressions` reports
|
|
1621
|
+
`` `${this.reference}` ``. Nothing reports a read where any value is accepted, e.g. in an array
|
|
1622
|
+
(`this.router.navigate([prefix, this.reference])`): list the reads which are not calls, and check each of them
|
|
1623
|
+
(the fields named `reference` of your other classes are listed too):
|
|
1624
|
+
|
|
1625
|
+
```bash
|
|
1626
|
+
grep -rnP "\bthis\.reference\b(?!\s*(\(|\.set\(|\.update\())" src --include=*.ts
|
|
1627
|
+
```
|
|
1628
|
+
|
|
1629
|
+
In an `effect()`, reading `this.reference()` runs the effect again when the reference changes: read it with
|
|
1630
|
+
`untracked(this.reference)` when the effect must not follow it.
|
|
1631
|
+
|
|
1632
|
+
### The form of your pages is a signal (since 19.2.0)
|
|
1633
|
+
|
|
1634
|
+
`form` of `AbstractPageComponent` is now a `WritableSignal<T | null | undefined>`: read it with `form()`, and never
|
|
1635
|
+
modify its value in place. Write it with `patchForm(path, value)`, which copies the objects along the path, or with
|
|
1636
|
+
`form.set()` / `form.update()` and a new object. A template, a `computed()` or an `effect()` reading it follows every
|
|
1637
|
+
input of the user, and no `markForCheck()` is needed after a write anymore.
|
|
1638
|
+
|
|
1639
|
+
#### Run the migration
|
|
1640
|
+
|
|
1641
|
+
`ng update @dsivd/prestations-ng` migrates your pages (the classes extending `AbstractPageComponent`,
|
|
1642
|
+
`AbstractMenuPageComponent`, `AbstractPageFromMenuComponent`, `AbstractListDetailPageComponent`, or one of your
|
|
1643
|
+
classes extending them) and their templates. It runs again at each beta of 19.2.0, which changes nothing once
|
|
1644
|
+
migrated. To run it by hand, e.g. on a branch updated meanwhile:
|
|
1645
|
+
|
|
1646
|
+
```bash
|
|
1647
|
+
ng update @dsivd/prestations-ng --migrate-only --from=19.1.0 --to=19.2.0
|
|
1648
|
+
```
|
|
1649
|
+
|
|
1650
|
+
Then format the files it changed (`prettier --write`), build, lint, and fix what it lists as "To check by hand"
|
|
1651
|
+
(see below).
|
|
1652
|
+
|
|
1653
|
+
In the templates, it reads the form through a `@let`, so that the reads and their narrowing (`@if (form)`) are
|
|
1654
|
+
unchanged, and writes the fields with `patchForm()`:
|
|
1655
|
+
|
|
1656
|
+
```diff
|
|
1657
|
+
+ @let form = this.form();
|
|
1658
|
+
@if (form) {
|
|
1659
|
+
- <foehn-input-text name="address.street" [(model)]="form.address.street" />
|
|
1660
|
+
+ <foehn-input-text name="address.street" [model]="form.address.street" (modelChange)="patchForm(['address', 'street'], $event)" />
|
|
1661
|
+
- @for (child of form.children; track child) {
|
|
1662
|
+
+ @for (child of form.children; track $index) {
|
|
1663
|
+
- <foehn-input-text [name]="'children[' + $index + '].firstName'" [(model)]="child.firstName" />
|
|
1664
|
+
+ <foehn-input-text [name]="'children[' + $index + '].firstName'" [model]="child.firstName" (modelChange)="patchForm(['children', $index, 'firstName'], $event)" />
|
|
1665
|
+
}
|
|
1666
|
+
}
|
|
1667
|
+
```
|
|
1668
|
+
|
|
1669
|
+
In the classes:
|
|
1670
|
+
|
|
1671
|
+
```diff
|
|
1672
|
+
- this.form = form;
|
|
1673
|
+
+ this.form.set(form);
|
|
1674
|
+
- this.form.firstName = info?.firstName ?? null;
|
|
1675
|
+
+ this.patchForm(['firstName'], info?.firstName ?? null);
|
|
1676
|
+
- this.form.children.push(child);
|
|
1677
|
+
+ this.patchForm(['children'], [...(this.form()!.children ?? []), child]);
|
|
1678
|
+
- if (this.form) {
|
|
1679
|
+
- this.http.post('api/check', this.form.amount);
|
|
1680
|
+
+ if (this.form()) {
|
|
1681
|
+
+ this.http.post('api/check', this.form()!.amount);
|
|
1682
|
+
```
|
|
1683
|
+
|
|
1684
|
+
#### Check by hand
|
|
1685
|
+
|
|
1686
|
+
The migration leaves untouched, and lists with their file and line, what it can't rewrite. The compiler reports it
|
|
1687
|
+
too (`this.form.x` doesn't exist on a signal):
|
|
1688
|
+
|
|
1689
|
+
- the writes other than an assignment or a `push()` / `unshift()`: `+=`, `++`, `splice()`, `sort()`, a write inside
|
|
1690
|
+
an expression... Write a new value, e.g. `this.patchForm(['children'], children.filter((c) => c !== child))`;
|
|
1691
|
+
- the two-way bindings it can't follow: through a call or a pipe, or in a `*ngFor` over the form. Migrate the
|
|
1692
|
+
`*ngFor` to `@for` first (`ng generate @angular/core:control-flow`), then run the migration again;
|
|
1693
|
+
- the `getList()` of the detail pages which compute their list, see below.
|
|
1694
|
+
|
|
1695
|
+
Also check:
|
|
1696
|
+
|
|
1697
|
+
- your specs, which the migration doesn't change: `component.form = x` becomes `component.form.set(x)`, and
|
|
1698
|
+
`component.form.x` becomes `component.form()!.x` (the compiler reports them);
|
|
1699
|
+
- the components receiving the form, or an object of it, as an input and modifying it: they modify the value of the
|
|
1700
|
+
signal in place, the page isn't notified. Give them an output, and let the page write with `patchForm()`;
|
|
1701
|
+
- the `markForCheck()` called after a write of the form (zoneless): they are useless now, remove them.
|
|
1702
|
+
|
|
1703
|
+
`no-direct-signal-mutation` reports the writes in place left (`this.form()!.x = 1`, `form.children.push(child)`),
|
|
1704
|
+
`[(model)]="form.x"` inside `@if (form(); as form)` included.
|
|
1705
|
+
|
|
1706
|
+
#### Lists of the form
|
|
1707
|
+
|
|
1708
|
+
`patchForm()` replaces each object along the path with a copy: a row of a `@for` tracked by its item (`track child`)
|
|
1709
|
+
is then destroyed and created again at each input, and the field being edited loses the focus. Track the rows of a
|
|
1710
|
+
list edited by its rows by an identifier of the item (`track child.id`), or by `$index`. The migration does it for the
|
|
1711
|
+
lists it migrates, and `no-item-track-in-form-list` (`configs.templateRecommended`) reports the others.
|
|
1712
|
+
|
|
1713
|
+
#### Write your templates
|
|
1714
|
+
|
|
1715
|
+
```html
|
|
1716
|
+
@if (form(); as form) {
|
|
1717
|
+
<foehn-input-text
|
|
1718
|
+
name="firstName"
|
|
1719
|
+
[model]="form.firstName"
|
|
1720
|
+
(modelChange)="patchForm(['firstName'], $event)"
|
|
1721
|
+
/>
|
|
1722
|
+
}
|
|
1723
|
+
```
|
|
1724
|
+
|
|
1725
|
+
- The path is checked by TypeScript: a typo gives an error listing the valid keys. For a form serving several
|
|
1726
|
+
prestations, type the page with a union (`AbstractPageComponent<ApForm | AfForm>`): the paths of each of them are
|
|
1727
|
+
accepted.
|
|
1728
|
+
- `null` and `undefined` are accepted, as with `[(model)]`: the model of the `foehn-*` components can be.
|
|
1729
|
+
- Never a `[model]` alone on a field the user can change: what the user enters would never reach the form.
|
|
1730
|
+
`require-model-change` (`configs.templateRecommended`) reports it. A field always disabled
|
|
1731
|
+
(`[disabled]="true"`), only displayed, is bound with `[model]` alone.
|
|
1732
|
+
- `@let form = this.form();`, which the migration adds, is just as valid.
|
|
1733
|
+
- Outside a page, `ObjectPathHelper` writes a path of any object the same way: `patch(object, path, value)`, and
|
|
1734
|
+
`patchSignal(signal, path, value)` for a signal holding an object (e.g. the state of a component), typed with
|
|
1735
|
+
`ObjectPath<T>` and `ObjectPathValue<T, P>`. `getByKeys()` and `patchByKeys()` take keys known at runtime only
|
|
1736
|
+
(`'address.street'`), not checked by TypeScript.
|
|
1737
|
+
|
|
1738
|
+
#### Detail pages
|
|
1739
|
+
|
|
1740
|
+
`AbstractListDetailPageComponent` no longer modifies the list of the form in place:
|
|
1741
|
+
|
|
1742
|
+
| Before | Since 19.2.0 |
|
|
1743
|
+
| ---------------------------------------------- | ----------------------------------------------------------------------------------------- |
|
|
1744
|
+
| `getList(): Dog[] { return this.form.dogs; }` | `getListPath(): ObjectPath<MyForm> { return ['dogs']; }` (`getList()` is still available) |
|
|
1745
|
+
| `list`, `itemIndex`, `itemToEdit` | `list()`, `itemIndex()`, `itemToEdit()` |
|
|
1746
|
+
| `[(model)]="itemToEdit.name"` | `[model]="item.name" (modelChange)="patchItem(['name'], $event)"` |
|
|
1747
|
+
| `this.itemToEdit.site = null; ...` (in place) | `this.updateItem((item) => ({ ...item, site: null, ideNumber: null }))` |
|
|
1748
|
+
| `[(model)]="list[itemIndex]"` (the whole item) | `[model]="item" (modelChange)="setItem($event)"` |
|
|
1749
|
+
|
|
1750
|
+
The migration replaces a `getList()` returning a path of the form (`this.form.a.b`, `this.form?.a?.b ?? []`). A
|
|
1751
|
+
`getList()` choosing its list (e.g. according to the prestation) becomes a `getListPath()` choosing its path:
|
|
1752
|
+
|
|
1753
|
+
```ts
|
|
1754
|
+
getListPath(): ObjectPath<ApForm | AfForm> {
|
|
1755
|
+
return this.isAp()
|
|
1756
|
+
? ['diplomeData', 'diplomes']
|
|
1757
|
+
: ['formationData', 'diplomes'];
|
|
1758
|
+
}
|
|
1759
|
+
```
|
|
1760
|
+
|
|
1588
1761
|
### Zoneless (optional but recommended)
|
|
1589
1762
|
|
|
1590
1763
|
Since v19.2, prestations-ng does not need zone.js anymore: the state of its components is held by signals, which
|
|
@@ -1665,26 +1838,9 @@ only a method called by a listener modifies: this method can later be called fro
|
|
|
1665
1838
|
|
|
1666
1839
|
Pay attention to:
|
|
1667
1840
|
|
|
1668
|
-
- your pages (`AbstractPageComponent` and its subclasses): `form`
|
|
1669
|
-
|
|
1670
|
-
|
|
1671
|
-
`SessionInfoWithApplicationService.prefillForm()` or a `subscribe()` of your own service), an `effect()`... A
|
|
1672
|
-
signal modified next to the form doesn't replace it: `set()` notifies Angular only when the value changes.
|
|
1673
|
-
|
|
1674
|
-
```ts
|
|
1675
|
-
private readonly changeDetectorRef = inject(ChangeDetectorRef);
|
|
1676
|
-
|
|
1677
|
-
ngOnInit(): void {
|
|
1678
|
-
super.ngOnInit();
|
|
1679
|
-
this.sessionInfoWithApplicationService.prefillForm((info) => {
|
|
1680
|
-
if (this.form) {
|
|
1681
|
-
this.form.firstName = info?.firstName ?? null;
|
|
1682
|
-
this.form.lastName = info?.lastName ?? null;
|
|
1683
|
-
this.changeDetectorRef.markForCheck();
|
|
1684
|
-
}
|
|
1685
|
-
});
|
|
1686
|
-
}
|
|
1687
|
-
```
|
|
1841
|
+
- your pages (`AbstractPageComponent` and its subclasses): since 19.2.0, `form` and `reference` are signals (see "The
|
|
1842
|
+
form of your pages is a signal" and "`reference` of your pages is a signal"). Write the form with `patchForm()`,
|
|
1843
|
+
never in place: no `markForCheck()` is needed after a write.
|
|
1688
1844
|
|
|
1689
1845
|
- the fields read by the template and set in `ngAfterViewInit()`, `ngAfterContentInit()` or `ngAfterViewChecked()`:
|
|
1690
1846
|
derive them with `computed()` from `viewChild()` or `contentChild()` (see "Deriving a state from view queries"
|
|
@@ -15,6 +15,11 @@ const templateRules = (plugin) => [
|
|
|
15
15
|
// template visitor, and each fires on its own kind of file.
|
|
16
16
|
'@dsivd/prestations-ng/no-direct-signal-mutation': 'error',
|
|
17
17
|
'@dsivd/prestations-ng/no-uninvoked-signal-in-template': 'error',
|
|
18
|
+
// The form of the pages is a signal: a one-way [model] without
|
|
19
|
+
// (modelChange) loses the input, and a row tracked by its item
|
|
20
|
+
// loses the focus at every input
|
|
21
|
+
'@dsivd/prestations-ng/require-model-change': 'error',
|
|
22
|
+
'@dsivd/prestations-ng/no-item-track-in-form-list': 'error',
|
|
18
23
|
},
|
|
19
24
|
},
|
|
20
25
|
];
|
|
@@ -73,6 +73,10 @@ const tsRecommended = (plugin) => [
|
|
|
73
73
|
],
|
|
74
74
|
'@typescript-eslint/member-ordering': 'error',
|
|
75
75
|
'@typescript-eslint/no-base-to-string': 'warn',
|
|
76
|
+
// a template literal only takes strings, numbers, booleans, null,
|
|
77
|
+
// undefined, any and RegExp: also reports a signal not called
|
|
78
|
+
// (`${this.reference}`), which no-uncalled-signals skips there
|
|
79
|
+
'@typescript-eslint/restrict-template-expressions': 'error',
|
|
76
80
|
// stylistic enables no-inferrable-types with default options (ignoreParameters: false);
|
|
77
81
|
// override here to allow typed parameters explicitly
|
|
78
82
|
'@typescript-eslint/no-inferrable-types': [
|
|
@@ -0,0 +1,63 @@
|
|
|
1
|
+
import { isComponentReceiver } from "./template-ast.mjs";
|
|
2
|
+
|
|
3
|
+
/**
|
|
4
|
+
* Where a template expression reads its value from: the form of the page (a signal since
|
|
5
|
+
* 19.2.0), through the names bound by `@if (form(); as form)`, `@let form = this.form()` and
|
|
6
|
+
* `@for (child of form.children)`.
|
|
7
|
+
*/
|
|
8
|
+
|
|
9
|
+
const MEMBER_READS = new Set([
|
|
10
|
+
"PropertyRead",
|
|
11
|
+
"SafePropertyRead",
|
|
12
|
+
"KeyedRead",
|
|
13
|
+
"SafeKeyedRead",
|
|
14
|
+
]);
|
|
15
|
+
|
|
16
|
+
export const astOf = (expression) =>
|
|
17
|
+
expression?.type === "ASTWithSource" ? expression.ast : expression;
|
|
18
|
+
|
|
19
|
+
/**
|
|
20
|
+
* The root of an expression: a member of the component (`{ member }`), or the item of an
|
|
21
|
+
* enclosing `@for` (`{ forBlock }`). A name bound by `@if … as` is followed to its expression,
|
|
22
|
+
* evaluated outside its block (in `@if (form(); as form)`, `form()` is the member).
|
|
23
|
+
* `undefined` for anything else (a literal, a call with arguments...).
|
|
24
|
+
*/
|
|
25
|
+
export function resolveRoot(expression, node) {
|
|
26
|
+
let base = expression;
|
|
27
|
+
while (MEMBER_READS.has(base?.type) && MEMBER_READS.has(base.receiver?.type)) {
|
|
28
|
+
base = base.receiver;
|
|
29
|
+
}
|
|
30
|
+
if (base?.type === "Call" || base?.type === "SafeCall") {
|
|
31
|
+
base = base.receiver;
|
|
32
|
+
}
|
|
33
|
+
const receiver = base?.receiver;
|
|
34
|
+
if (receiver?.type === "Call" || receiver?.type === "SafeCall") {
|
|
35
|
+
return resolveRoot(receiver, node);
|
|
36
|
+
}
|
|
37
|
+
if (!MEMBER_READS.has(base?.type) || !isComponentReceiver(receiver)) {
|
|
38
|
+
return undefined;
|
|
39
|
+
}
|
|
40
|
+
for (let current = node; current; current = current.parent) {
|
|
41
|
+
if (current.type === "ForLoopBlock" && current.item?.name === base.name) {
|
|
42
|
+
return { forBlock: current };
|
|
43
|
+
}
|
|
44
|
+
if (
|
|
45
|
+
current.type === "IfBlockBranch" &&
|
|
46
|
+
current.expressionAlias?.name === base.name
|
|
47
|
+
) {
|
|
48
|
+
return resolveRoot(astOf(current.expression), current.parent);
|
|
49
|
+
}
|
|
50
|
+
}
|
|
51
|
+
return { member: base.name };
|
|
52
|
+
}
|
|
53
|
+
|
|
54
|
+
/**
|
|
55
|
+
* Whether an expression reads the form of the page, directly or through a template name.
|
|
56
|
+
*/
|
|
57
|
+
export function readsForm(expression, node) {
|
|
58
|
+
const root = resolveRoot(expression, node);
|
|
59
|
+
if (root?.forBlock) {
|
|
60
|
+
return readsForm(astOf(root.forBlock.expression), root.forBlock.parent);
|
|
61
|
+
}
|
|
62
|
+
return root?.member === "form";
|
|
63
|
+
}
|
package/eslint/rules/index.mjs
CHANGED
|
@@ -1,7 +1,11 @@
|
|
|
1
1
|
import noDirectSignalMutation from './no-direct-signal-mutation.mjs';
|
|
2
|
+
import noItemTrackInFormList from './no-item-track-in-form-list.mjs';
|
|
2
3
|
import noUninvokedSignalInTemplate from './no-uninvoked-signal-in-template.mjs';
|
|
4
|
+
import requireModelChange from './require-model-change.mjs';
|
|
3
5
|
|
|
4
6
|
export default {
|
|
5
7
|
'no-direct-signal-mutation': noDirectSignalMutation,
|
|
8
|
+
'no-item-track-in-form-list': noItemTrackInFormList,
|
|
6
9
|
'no-uninvoked-signal-in-template': noUninvokedSignalInTemplate,
|
|
10
|
+
'require-model-change': requireModelChange,
|
|
7
11
|
};
|
|
@@ -9,7 +9,11 @@ import {
|
|
|
9
9
|
WRITABLE,
|
|
10
10
|
} from "../signal-kinds.mjs";
|
|
11
11
|
import { collectSignalKinds } from "../signal-names.mjs";
|
|
12
|
-
import {
|
|
12
|
+
import {
|
|
13
|
+
handlerExpressionOf,
|
|
14
|
+
isComponentReceiver,
|
|
15
|
+
isTwoWayBinding,
|
|
16
|
+
} from "../template-ast.mjs";
|
|
13
17
|
|
|
14
18
|
/**
|
|
15
19
|
* ESLint rule to detect mutations of the value held by a signal.
|
|
@@ -17,7 +21,8 @@ import { handlerExpressionOf, isComponentReceiver } from "../template-ast.mjs";
|
|
|
17
21
|
* Suggests using .update() or .set() instead.
|
|
18
22
|
*
|
|
19
23
|
* Applies to TypeScript files and to Angular templates, where the mutation is also
|
|
20
|
-
* hidden in every two-way binding on a call result: [(ngModel)]="model().property"
|
|
24
|
+
* hidden in every two-way binding on a call result: [(ngModel)]="model().property", or on
|
|
25
|
+
* a name bound to it: [(model)]="form.property" inside @if (form(); as form).
|
|
21
26
|
*
|
|
22
27
|
* No signal's value is to be mutated, whatever its kind — a mutation notifies none of its
|
|
23
28
|
* dependents. A view query is the single exception: it hands out a DOM element or a
|
|
@@ -106,6 +111,9 @@ const TEMPLATE_MEMBER_READS = new Set([
|
|
|
106
111
|
"SafeKeyedRead",
|
|
107
112
|
]);
|
|
108
113
|
|
|
114
|
+
// Template wrappers that leave the value as is: `form()!`, `(form())`.
|
|
115
|
+
const TEMPLATE_WRAPPERS = new Set(["NonNullAssert", "ParenthesizedExpression"]);
|
|
116
|
+
|
|
109
117
|
// ── TypeScript ───────────────────────────────────────────────────────────────
|
|
110
118
|
|
|
111
119
|
function getCalledName(callee) {
|
|
@@ -140,9 +148,18 @@ function isObjectAssign(callee) {
|
|
|
140
148
|
);
|
|
141
149
|
}
|
|
142
150
|
|
|
151
|
+
// TypeScript wrappers that leave the value as is: `form()!`, `form() as Form`...
|
|
152
|
+
const TYPE_WRAPPERS = new Set([
|
|
153
|
+
"TSNonNullExpression",
|
|
154
|
+
"TSAsExpression",
|
|
155
|
+
"TSSatisfiesExpression",
|
|
156
|
+
"TSTypeAssertion",
|
|
157
|
+
]);
|
|
158
|
+
|
|
143
159
|
/**
|
|
144
160
|
* What a member chain is rooted at, the property and index reads stripped away:
|
|
145
161
|
* - `model().deep.property` => the `model()` call
|
|
162
|
+
* - `model()!.deep.property` => the `model()` call (a type wrapper keeps the value)
|
|
146
163
|
* - `users[0].name` => the `users` name
|
|
147
164
|
*
|
|
148
165
|
* Only reads are walked through. A chain rooted at anything else — `items().filter(f)`,
|
|
@@ -151,8 +168,12 @@ function isObjectAssign(callee) {
|
|
|
151
168
|
*/
|
|
152
169
|
function baseOf(node) {
|
|
153
170
|
let current = node;
|
|
154
|
-
while (
|
|
155
|
-
current
|
|
171
|
+
while (
|
|
172
|
+
current?.type === "MemberExpression" ||
|
|
173
|
+
TYPE_WRAPPERS.has(current?.type)
|
|
174
|
+
) {
|
|
175
|
+
current =
|
|
176
|
+
current.type === "MemberExpression" ? current.object : current.expression;
|
|
156
177
|
}
|
|
157
178
|
return current;
|
|
158
179
|
}
|
|
@@ -297,18 +318,32 @@ function signalRootTemplateCallKind(node, templateContext) {
|
|
|
297
318
|
: undefined;
|
|
298
319
|
}
|
|
299
320
|
|
|
321
|
+
// The expression itself, a type wrapper stripped away: `form()!` is the `form()` call.
|
|
322
|
+
function unwrapTemplate(node) {
|
|
323
|
+
let current = node;
|
|
324
|
+
while (TEMPLATE_WRAPPERS.has(current?.type)) {
|
|
325
|
+
current = current.expression;
|
|
326
|
+
}
|
|
327
|
+
return current;
|
|
328
|
+
}
|
|
329
|
+
|
|
300
330
|
/**
|
|
301
331
|
* Expression a template name is bound to, `undefined` when the name is a component
|
|
302
332
|
* member. Mutating through such a name mutates whatever the expression yields:
|
|
303
|
-
* `@for (user of model().users)` hands out the elements of the signal's array
|
|
333
|
+
* `@for (user of model().users)` hands out the elements of the signal's array, and
|
|
334
|
+
* `@if (model(); as value)` the value of the signal itself.
|
|
304
335
|
*
|
|
305
|
-
* The item of a `@for`
|
|
306
|
-
*
|
|
307
|
-
* uses.
|
|
336
|
+
* The item of a `@for` and the alias of an `@if` are only bound inside their own block,
|
|
337
|
+
* which the ancestor walk enforces exactly, the nearest one shadowing the others; a `@let`
|
|
338
|
+
* is looked up by name, its declaration always preceding its uses.
|
|
308
339
|
*/
|
|
309
340
|
function boundTemplateExpression(read, templateContext) {
|
|
310
341
|
for (let current = read; current; current = current.parent) {
|
|
311
|
-
if (
|
|
342
|
+
if (
|
|
343
|
+
(current.type === "ForLoopBlock" && current.item?.name === read.name) ||
|
|
344
|
+
(current.type === "IfBlockBranch" &&
|
|
345
|
+
current.expressionAlias?.name === read.name)
|
|
346
|
+
) {
|
|
312
347
|
return current.expression?.ast ?? current.expression;
|
|
313
348
|
}
|
|
314
349
|
}
|
|
@@ -321,19 +356,21 @@ function boundTemplateExpression(read, templateContext) {
|
|
|
321
356
|
* a template name bound to either.
|
|
322
357
|
*/
|
|
323
358
|
function signalTemplateValueKind(node, templateContext, seen = new Set()) {
|
|
324
|
-
|
|
325
|
-
|
|
359
|
+
const value = unwrapTemplate(node);
|
|
360
|
+
if (value?.type === "Call" || value?.type === "SafeCall") {
|
|
361
|
+
return signalRootTemplateCallKind(value, templateContext);
|
|
326
362
|
}
|
|
327
|
-
if (!TEMPLATE_MEMBER_READS.has(
|
|
363
|
+
if (!TEMPLATE_MEMBER_READS.has(value?.type)) {
|
|
328
364
|
return undefined;
|
|
329
365
|
}
|
|
330
366
|
|
|
331
|
-
// Property and index reads are walked through
|
|
332
|
-
|
|
333
|
-
|
|
334
|
-
|
|
367
|
+
// Property and index reads are walked through, as are the type wrappers; anything else
|
|
368
|
+
// roots a value of its own.
|
|
369
|
+
let base = value;
|
|
370
|
+
while (TEMPLATE_MEMBER_READS.has(unwrapTemplate(base.receiver)?.type)) {
|
|
371
|
+
base = unwrapTemplate(base.receiver);
|
|
335
372
|
}
|
|
336
|
-
const receiver = base.receiver;
|
|
373
|
+
const receiver = unwrapTemplate(base.receiver);
|
|
337
374
|
|
|
338
375
|
if (receiver?.type === "Call" || receiver?.type === "SafeCall") {
|
|
339
376
|
return signalRootTemplateCallKind(receiver, templateContext);
|
|
@@ -492,8 +529,9 @@ export default {
|
|
|
492
529
|
|
|
493
530
|
BoundEvent(node) {
|
|
494
531
|
// `[(x)]="model().property"` makes Angular assign into the value of the signal.
|
|
495
|
-
// Reporting on the BoundEvent handler reports the binding exactly once.
|
|
496
|
-
|
|
532
|
+
// Reporting on the BoundEvent handler reports the binding exactly once. An
|
|
533
|
+
// explicit `(xChange)="…"` handler is a statement, checked as any other.
|
|
534
|
+
if (!isTwoWayBinding(node)) {
|
|
497
535
|
return;
|
|
498
536
|
}
|
|
499
537
|
const handler = handlerExpressionOf(node);
|
|
@@ -0,0 +1,99 @@
|
|
|
1
|
+
import { isComponentReceiver } from "../template-ast.mjs";
|
|
2
|
+
import { astOf, readsForm, resolveRoot } from "../form-reads.mjs";
|
|
3
|
+
|
|
4
|
+
/**
|
|
5
|
+
* ESLint rule: a `@for` over a list of the form of the page whose rows edit their
|
|
6
|
+
* item must not track the rows by the item itself (`track child`).
|
|
7
|
+
*
|
|
8
|
+
* The form is never modified in place: writing a field of an item (`patchForm()`,
|
|
9
|
+
* `patchItem()`) replaces the item with a copy. A row tracked by its item is then destroyed and
|
|
10
|
+
* created again at every input, and the field being edited loses the focus. Track the rows by
|
|
11
|
+
* `$index`, or by an identifier of the item (`track child.id`), which the copy keeps.
|
|
12
|
+
*
|
|
13
|
+
* A row edits its item when one of its elements has a `model` read from it
|
|
14
|
+
* (`[model]="child.firstName"`, `[(model)]="child"`). A list only displayed is left alone.
|
|
15
|
+
* `$any(child)` counts as `child`.
|
|
16
|
+
*/
|
|
17
|
+
|
|
18
|
+
/**
|
|
19
|
+
* Whether the track expression of a `@for` is its item itself.
|
|
20
|
+
*/
|
|
21
|
+
function tracksItemItself(forBlock) {
|
|
22
|
+
let track = astOf(forBlock.trackBy);
|
|
23
|
+
if (
|
|
24
|
+
track?.type === "Call" &&
|
|
25
|
+
track.receiver?.name === "$any" &&
|
|
26
|
+
track.args?.length === 1
|
|
27
|
+
) {
|
|
28
|
+
track = track.args[0];
|
|
29
|
+
}
|
|
30
|
+
return (
|
|
31
|
+
track?.type === "PropertyRead" &&
|
|
32
|
+
isComponentReceiver(track.receiver) &&
|
|
33
|
+
track.name === forBlock.item?.name
|
|
34
|
+
);
|
|
35
|
+
}
|
|
36
|
+
|
|
37
|
+
export default {
|
|
38
|
+
meta: {
|
|
39
|
+
type: "problem",
|
|
40
|
+
docs: {
|
|
41
|
+
description:
|
|
42
|
+
"Disallow tracking by the item itself the rows of a @for editing a list of the form",
|
|
43
|
+
category: "Possible Errors",
|
|
44
|
+
recommended: true,
|
|
45
|
+
},
|
|
46
|
+
hasSuggestions: true,
|
|
47
|
+
schema: [],
|
|
48
|
+
messages: {
|
|
49
|
+
itemTrack:
|
|
50
|
+
"The rows of this list of the form are tracked by their item ('track {{item}}'): writing a field replaces the item, so its row is created again and the field being edited loses the focus. Track the rows by $index or by an identifier of the item.",
|
|
51
|
+
trackByIndex: "Track the rows by $index",
|
|
52
|
+
},
|
|
53
|
+
},
|
|
54
|
+
|
|
55
|
+
create(context) {
|
|
56
|
+
const candidates = [];
|
|
57
|
+
const editingBlocks = new Set();
|
|
58
|
+
|
|
59
|
+
return {
|
|
60
|
+
ForLoopBlock(node) {
|
|
61
|
+
if (
|
|
62
|
+
tracksItemItself(node) &&
|
|
63
|
+
readsForm(astOf(node.expression), node.parent)
|
|
64
|
+
) {
|
|
65
|
+
candidates.push(node);
|
|
66
|
+
}
|
|
67
|
+
},
|
|
68
|
+
Element(node) {
|
|
69
|
+
const model = node.inputs?.find((input) => input.name === "model");
|
|
70
|
+
const root = model && resolveRoot(astOf(model.value), node);
|
|
71
|
+
if (root?.forBlock) {
|
|
72
|
+
editingBlocks.add(root.forBlock);
|
|
73
|
+
}
|
|
74
|
+
},
|
|
75
|
+
"Program:exit"() {
|
|
76
|
+
for (const forBlock of candidates) {
|
|
77
|
+
if (!editingBlocks.has(forBlock)) {
|
|
78
|
+
continue;
|
|
79
|
+
}
|
|
80
|
+
const { start, end } = astOf(forBlock.trackBy).sourceSpan;
|
|
81
|
+
context.report({
|
|
82
|
+
messageId: "itemTrack",
|
|
83
|
+
data: { item: forBlock.item.name },
|
|
84
|
+
loc: {
|
|
85
|
+
start: context.sourceCode.getLocFromIndex(start),
|
|
86
|
+
end: context.sourceCode.getLocFromIndex(end),
|
|
87
|
+
},
|
|
88
|
+
suggest: [
|
|
89
|
+
{
|
|
90
|
+
messageId: "trackByIndex",
|
|
91
|
+
fix: (fixer) => fixer.replaceTextRange([start, end], "$index"),
|
|
92
|
+
},
|
|
93
|
+
],
|
|
94
|
+
});
|
|
95
|
+
}
|
|
96
|
+
},
|
|
97
|
+
};
|
|
98
|
+
},
|
|
99
|
+
};
|
|
@@ -1,6 +1,10 @@
|
|
|
1
1
|
import { resolveComponentPath } from "../component-path.mjs";
|
|
2
2
|
import { collectSignalNames } from "../signal-names.mjs";
|
|
3
|
-
import {
|
|
3
|
+
import {
|
|
4
|
+
handlerExpressionOf,
|
|
5
|
+
isComponentReceiver,
|
|
6
|
+
isTwoWayBinding,
|
|
7
|
+
} from "../template-ast.mjs";
|
|
4
8
|
|
|
5
9
|
/**
|
|
6
10
|
* ESLint rule to detect signals referenced without being called in a template.
|
|
@@ -98,8 +102,9 @@ export default {
|
|
|
98
102
|
BoundEvent(node) {
|
|
99
103
|
// `[(x)]="expr"` generates a BoundEvent `xChange` whose handler IS the written
|
|
100
104
|
// target. Its span is the one of the twin BoundAttribute expression: marking
|
|
101
|
-
// the span neutralizes both copies at once.
|
|
102
|
-
|
|
105
|
+
// the span neutralizes both copies at once. An explicit `(xChange)="…"` handler
|
|
106
|
+
// is a statement, checked as any other.
|
|
107
|
+
if (isTwoWayBinding(node)) {
|
|
103
108
|
markHandled(handlerExpressionOf(node));
|
|
104
109
|
}
|
|
105
110
|
},
|