@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.
Files changed (39) hide show
  1. package/ANGULAR_SIGNALS.md +4 -0
  2. package/CHANGELOG.md +98 -3
  3. package/CONTRIBUTING.md +2 -2
  4. package/ESLINT_PLUGIN.md +103 -8
  5. package/GOOD_PRACTICES.md +79 -29
  6. package/UPGRADING_V19.md +187 -31
  7. package/eslint/configs/template-rules.mjs +5 -0
  8. package/eslint/configs/ts-recommended.mjs +4 -0
  9. package/eslint/form-reads.mjs +63 -0
  10. package/eslint/rules/index.mjs +4 -0
  11. package/eslint/rules/no-direct-signal-mutation.mjs +57 -19
  12. package/eslint/rules/no-item-track-in-form-list.mjs +99 -0
  13. package/eslint/rules/no-uninvoked-signal-in-template.mjs +8 -3
  14. package/eslint/rules/require-model-change.mjs +89 -0
  15. package/eslint/template-ast.mjs +12 -2
  16. package/fesm2022/dsivd-prestations-ng.mjs +907 -692
  17. package/fesm2022/dsivd-prestations-ng.mjs.map +1 -1
  18. package/package.json +1 -1
  19. package/schematics/migration-collection.json +5 -0
  20. package/schematics/ng-update/migrations/update-19_2_0/index.js +39 -0
  21. package/schematics/utility/form-signal/class-migration.js +396 -0
  22. package/schematics/utility/form-signal/edits.js +34 -0
  23. package/schematics/utility/form-signal/form-signal-migration.js +184 -0
  24. package/schematics/utility/form-signal/page-classes.js +129 -0
  25. package/schematics/utility/form-signal/template-migration.js +666 -0
  26. package/src/eslint/configs/template-rules.mjs +5 -0
  27. package/src/eslint/configs/ts-recommended.mjs +4 -0
  28. package/src/eslint/form-reads.mjs +63 -0
  29. package/src/eslint/rules/__tests__/no-direct-signal-mutation.test.mjs +58 -0
  30. package/src/eslint/rules/__tests__/no-item-track-in-form-list.test.mjs +127 -0
  31. package/src/eslint/rules/__tests__/no-uninvoked-signal-in-template.test.mjs +6 -0
  32. package/src/eslint/rules/__tests__/require-model-change.test.mjs +93 -0
  33. package/src/eslint/rules/index.mjs +4 -0
  34. package/src/eslint/rules/no-direct-signal-mutation.mjs +57 -19
  35. package/src/eslint/rules/no-item-track-in-form-list.mjs +99 -0
  36. package/src/eslint/rules/no-uninvoked-signal-in-template.mjs +8 -3
  37. package/src/eslint/rules/require-model-change.mjs +89 -0
  38. package/src/eslint/template-ast.mjs +12 -2
  39. 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. Two
1178
- rules are enabled today — `no-direct-signal-mutation` and `no-uninvoked-signal-in-template` — and both
1179
- are documented in [the plugin guide](ESLINT_PLUGIN.md), alongside the leaner `tsRules` / `templateRules`
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
- Bind the list with `[(model)]`, never with a one-way `[model]` (see also "Quick fix"): the component removes the
1555
- items itself, and only a two-way binding passes the new list to your form. A one-way `[model]` compiles without
1556
- warning, but the removed item stays in the form and comes back when the form is saved. With the strict mode, guard
1557
- the form rather than binding `[model]="form?.items"`:
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
- [(model)]="form.items"
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` can't be a signal. prestations-ng refreshes them
1669
- when it sets `form` and `reference`, but whenever your code modifies the form, call `markForCheck()` once after the
1670
- modifications, whoever calls the method: a listener, an asynchronous callback (e.g. the one given to
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
+ }
@@ -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 { handlerExpressionOf, isComponentReceiver } from "../template-ast.mjs";
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 (current?.type === "MemberExpression") {
155
- current = current.object;
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` is only bound inside its own block, which the ancestor walk
306
- * enforces exactly; a `@let` is looked up by name, its declaration always preceding its
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 (current.type === "ForLoopBlock" && current.item?.name === read.name) {
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
- if (node?.type === "Call" || node?.type === "SafeCall") {
325
- return signalRootTemplateCallKind(node, templateContext);
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(node?.type)) {
363
+ if (!TEMPLATE_MEMBER_READS.has(value?.type)) {
328
364
  return undefined;
329
365
  }
330
366
 
331
- // Property and index reads are walked through; anything else roots a value of its own.
332
- let base = node;
333
- while (TEMPLATE_MEMBER_READS.has(base.receiver?.type)) {
334
- base = base.receiver;
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
- if (!node.name?.endsWith("Change")) {
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 { handlerExpressionOf, isComponentReceiver } from "../template-ast.mjs";
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
- if (node.name?.endsWith("Change")) {
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
  },