@dsivd/prestations-ng 19.2.0-beta.20 → 19.2.0-beta.22

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (40) hide show
  1. package/ANGULAR_SIGNALS.md +4 -0
  2. package/CHANGELOG.md +113 -3
  3. package/CONTRIBUTING.md +2 -2
  4. package/ESLINT_PLUGIN.md +146 -28
  5. package/GOOD_PRACTICES.md +258 -58
  6. package/INTRODUCTION_ANGULAR_SIGNALS.md +29 -2
  7. package/UPGRADING_V19.md +233 -31
  8. package/eslint/configs/template-rules.mjs +5 -0
  9. package/eslint/configs/ts-recommended.mjs +4 -0
  10. package/eslint/form-reads.mjs +63 -0
  11. package/eslint/rules/index.mjs +4 -0
  12. package/eslint/rules/no-direct-signal-mutation.mjs +57 -19
  13. package/eslint/rules/no-item-track-in-form-list.mjs +172 -0
  14. package/eslint/rules/no-uninvoked-signal-in-template.mjs +8 -3
  15. package/eslint/rules/require-model-change.mjs +89 -0
  16. package/eslint/template-ast.mjs +12 -2
  17. package/fesm2022/dsivd-prestations-ng.mjs +948 -692
  18. package/fesm2022/dsivd-prestations-ng.mjs.map +1 -1
  19. package/package.json +1 -1
  20. package/schematics/migration-collection.json +5 -0
  21. package/schematics/ng-update/migrations/update-19_2_0/index.js +39 -0
  22. package/schematics/utility/form-signal/class-migration.js +671 -0
  23. package/schematics/utility/form-signal/edits.js +34 -0
  24. package/schematics/utility/form-signal/form-signal-migration.js +184 -0
  25. package/schematics/utility/form-signal/page-classes.js +129 -0
  26. package/schematics/utility/form-signal/template-migration.js +666 -0
  27. package/src/eslint/configs/template-rules.mjs +5 -0
  28. package/src/eslint/configs/ts-recommended.mjs +4 -0
  29. package/src/eslint/form-reads.mjs +63 -0
  30. package/src/eslint/rules/__tests__/no-direct-signal-mutation.test.mjs +58 -0
  31. package/src/eslint/rules/__tests__/no-item-track-in-form-list.test.mjs +234 -0
  32. package/src/eslint/rules/__tests__/no-uninvoked-signal-in-template.test.mjs +6 -0
  33. package/src/eslint/rules/__tests__/require-model-change.test.mjs +93 -0
  34. package/src/eslint/rules/index.mjs +4 -0
  35. package/src/eslint/rules/no-direct-signal-mutation.mjs +57 -19
  36. package/src/eslint/rules/no-item-track-in-form-list.mjs +172 -0
  37. package/src/eslint/rules/no-uninvoked-signal-in-template.mjs +8 -3
  38. package/src/eslint/rules/require-model-change.mjs +89 -0
  39. package/src/eslint/template-ast.mjs +12 -2
  40. package/types/dsivd-prestations-ng.d.ts +266 -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
 
@@ -1463,6 +1465,37 @@ fill another field once the form is loaded, often behind a guard on `undefined`)
1463
1465
  work where the page writes the form: after its loading (`GesdemEventService.formInitializationObservable()`, which
1464
1466
  emits the loaded form), after a prefill, after a reset.
1465
1467
 
1468
+ ### Your components write a new model
1469
+
1470
+ In v18, `updateNgModel(value)` emitted `modelChange` whatever the value. Since 19.0.0, the model is a signal, which
1471
+ ignores the same value: `updateNgModel()` with the object or the array the model already holds changes nothing, and no
1472
+ `modelChange` is emitted. A component extending `FoehnInputComponent` which keeps its model in a field
1473
+ (`onModelChange()` → `this.items = value`), modifies it in place (`this.items[i] = item`, `push()`, `splice()`,
1474
+ `[(model)]="item.x"`) and gives it back (`updateNgModel(this.items)`, a `getValidValue()` returning `this.item`) no
1475
+ longer notifies its page: the `(modelChange)` handlers of the page aren't called, and since 19.2.0, its `patchForm()`
1476
+ neither. The data seems saved as long as the object modified in place is the one of the page, and is lost as soon as
1477
+ the component works on another one (e.g. an object it created or replaced itself).
1478
+
1479
+ Search your components extending `FoehnInputComponent` for a `getValidValue()` returning a field (`return this.items;`,
1480
+ `return this.item;`) and for the writes in place of their model, and give `updateNgModel()` a new object or array:
1481
+
1482
+ - a list reads its `model()` directly, replaces an item with `patchNgModel([index], item)`, and adds or removes one
1483
+ with a new array (`[...list, item]`, `filter()`);
1484
+ - a component editing an object as is reads its `model()` directly, and writes each field with
1485
+ `patchNgModel(['address', 'street'], $event)` (since 19.2.0-beta.22), which keeps the fields it doesn't display (an
1486
+ id, a tracking index). Override `emptyModel()` when the page can give no object;
1487
+ - a component transforming its model (e.g. a date in three fields) keeps its linked signals, and its
1488
+ `getValidValue()` builds a new value.
1489
+
1490
+ Before 19.2.0-beta.22, write `patchNgModel()` yourself:
1491
+ `this.updateNgModel(ObjectPathHelper.patch(this.model() ?? new Owner(), path, value))`. See "Creating a reusable
1492
+ component", "Editing an object field by field" and the list of vehicles in [GOOD_PRACTICES.md](GOOD_PRACTICES.md).
1493
+
1494
+ The inputs inherited from `FoehnInputComponent` (`name`, `label`, `required`, `disabled`...) are signals too: read
1495
+ `this.name()`. `` `${this.name}[${index}]` `` and `this.name + '[0]'` compile, but give the signal, not its value
1496
+ (`[Input Signal: vehicules]` in development), e.g. a prefix of errors which matches no error. `restrict-template-expressions`
1497
+ (`configs.tsRecommended`, since 19.2.0) reports the template literals.
1498
+
1466
1499
  ### Strict mode (optional when migrating large projects but recommended)
1467
1500
 
1468
1501
  - In your `tsconfig.json` file, add `"strict": true` in `compilerOptions` and remove `alwaysStrict`, `noImplicitThis`, `strictBindCallApply` and `strictFunctionTypes` as they are already included in `strict` mode.
@@ -1551,16 +1584,17 @@ getListItemsDescription(): FoehnListItemDescription<MyItem>[] {
1551
1584
 
1552
1585
  The same applies to the function passed to `getListItemTitle`, which now receives a `MyItem`.
1553
1586
 
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"`:
1587
+ Never bind the list with a one-way `[model]` alone (see also "Quick fix"): the component removes the items itself,
1588
+ and only its `modelChange` passes the new list to your form. A one-way `[model]` compiles without warning, but the
1589
+ 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
1590
+ (see "The form of your pages is a signal"), write the list with `patchForm()`, the form guarded:
1558
1591
 
1559
1592
  ```html
1560
- @if (form) {
1593
+ @if (form(); as form) {
1561
1594
  <foehn-list-summary
1562
1595
  name="items"
1563
- [(model)]="form.items"
1596
+ [model]="form.items"
1597
+ (modelChange)="patchForm(['items'], $event)"
1564
1598
  (itemRemoved)="itemRemoved()"
1565
1599
  />
1566
1600
  }
@@ -1585,6 +1619,191 @@ The CommonJS dependencies of prestations-ng are now `"iban"` and `"dayjs"` (whic
1585
1619
 
1586
1620
  Also remove the packages that are no longer installed (`npm ls <package>` lists nothing).
1587
1621
 
1622
+ ### `reference` of your pages is a signal (since 19.2.0)
1623
+
1624
+ `reference` of `AbstractPageComponent` is now a `WritableSignal<string | null | undefined>`: read it with
1625
+ `reference()`, in the templates of your pages too, and write it with `reference.set()`. A template, a `computed()` or
1626
+ an `effect()` reading it follows the reference, also when your page sets it, without `markForCheck()`.
1627
+
1628
+ The `ng update` migration of 19.2.0 rewrites your pages (see "Run the migration" in "The form of your pages is a
1629
+ signal" below):
1630
+
1631
+ ```diff
1632
+ - this.http.get<FoehnRecapSection[]>(`api/${this.reference}/pdf-sections`)
1633
+ + this.http.get<FoehnRecapSection[]>(`api/${this.reference()}/pdf-sections`)
1634
+ ```
1635
+
1636
+ ```diff
1637
+ - this.reference = reference;
1638
+ + this.reference.set(reference);
1639
+ ```
1640
+
1641
+ In the templates, it reads it through a `@let reference = this.reference();`, so that the reads are unchanged
1642
+ (`[reference]="reference"`). It removes a field of a page declaring `reference` again (e.g. `reference: string;`),
1643
+ which would hide the signal, and lists such a field holding a value.
1644
+
1645
+ For a code it doesn't migrate (a class it doesn't recognize as a page):
1646
+
1647
+ - in the templates, `no-uninvoked-signal-in-template` (`configs.templateRecommended` or `configs.templateRules`, see
1648
+ [ESLINT_PLUGIN.md](ESLINT_PLUGIN.md)) reports `reference` without parentheses, and `ng lint --fix` adds them;
1649
+ - in TypeScript, the compiler reports the writes (`this.reference = ...`) and the arguments typed `string`. With
1650
+ `configs.tsRecommended`, `no-uncalled-signals` reports `!this.reference`, `this.reference && ...`,
1651
+ `'...' + this.reference` and `this.reference?.length`, and `restrict-template-expressions` reports
1652
+ `` `${this.reference}` ``. Nothing reports a read where any value is accepted, e.g. in an array
1653
+ (`this.router.navigate([prefix, this.reference])`): list the reads which are not calls, and check each of them
1654
+ (the fields named `reference` of your other classes are listed too):
1655
+
1656
+ ```bash
1657
+ grep -rnP "\bthis\.reference\b(?!\s*(\(|\.set\(|\.update\())" src --include=*.ts
1658
+ ```
1659
+
1660
+ In an `effect()`, reading `this.reference()` runs the effect again when the reference changes: read it with
1661
+ `untracked(this.reference)` when the effect must not follow it.
1662
+
1663
+ ### The form of your pages is a signal (since 19.2.0)
1664
+
1665
+ `form` of `AbstractPageComponent` is now a `WritableSignal<T | null | undefined>`: read it with `form()`, and never
1666
+ modify its value in place. Write it with `patchForm(path, value)`, which copies the objects along the path, or with
1667
+ `form.set()` / `form.update()` and a new object. A template, a `computed()` or an `effect()` reading it follows every
1668
+ input of the user, and no `markForCheck()` is needed after a write anymore.
1669
+
1670
+ #### Run the migration
1671
+
1672
+ `ng update @dsivd/prestations-ng` migrates your pages (the classes extending `AbstractPageComponent`,
1673
+ `AbstractMenuPageComponent`, `AbstractPageFromMenuComponent`, `AbstractListDetailPageComponent`, or one of your
1674
+ classes extending them) and their templates. It runs again at each beta of 19.2.0, which changes nothing once
1675
+ migrated. To run it by hand, e.g. on a branch updated meanwhile:
1676
+
1677
+ ```bash
1678
+ ng update @dsivd/prestations-ng --migrate-only --from=19.1.0 --to=19.2.0
1679
+ ```
1680
+
1681
+ Then format the files it changed (`prettier --write`), build, lint, and fix what it lists as "To check by hand"
1682
+ (see below).
1683
+
1684
+ In the templates, it reads the form through a `@let`, so that the reads and their narrowing (`@if (form)`) are
1685
+ unchanged, and writes the fields with `patchForm()`:
1686
+
1687
+ ```diff
1688
+ + @let form = this.form();
1689
+ @if (form) {
1690
+ - <foehn-input-text name="address.street" [(model)]="form.address.street" />
1691
+ + <foehn-input-text name="address.street" [model]="form.address.street" (modelChange)="patchForm(['address', 'street'], $event)" />
1692
+ - @for (child of form.children; track child) {
1693
+ + @for (child of form.children; track $index) {
1694
+ - <foehn-input-text [name]="'children[' + $index + '].firstName'" [(model)]="child.firstName" />
1695
+ + <foehn-input-text [name]="'children[' + $index + '].firstName'" [model]="child.firstName" (modelChange)="patchForm(['children', $index, 'firstName'], $event)" />
1696
+ }
1697
+ }
1698
+ ```
1699
+
1700
+ In the classes:
1701
+
1702
+ ```diff
1703
+ - this.form = form;
1704
+ + this.form.set(form);
1705
+ - this.form.firstName = info?.firstName ?? null;
1706
+ + this.patchForm(['firstName'], info?.firstName ?? null);
1707
+ - this.form.children.push(child);
1708
+ + this.patchForm(['children'], [...(this.form()!.children ?? []), child]);
1709
+ - if (this.form) {
1710
+ - this.http.post('api/check', this.form.amount);
1711
+ - this.pdf = this.gesdemService.pdf(this.form);
1712
+ + if (this.form()) {
1713
+ + this.http.post('api/check', this.form()!.amount);
1714
+ + this.pdf = this.gesdemService.pdf(this.form()!);
1715
+ ```
1716
+
1717
+ A read narrowed by a guard (`if (this.form)`, `this.form ? ... : ...`, `this.form && ...`,
1718
+ `if (!this.form) { return; }`) gets a `!`: TypeScript narrows `this.form`, but not the call `this.form()`. The same for
1719
+ `reference`, `itemToEdit` and `itemIndex`.
1720
+
1721
+ #### Check by hand
1722
+
1723
+ The migration leaves untouched, and lists with their file and line, what it can't rewrite. The compiler reports it
1724
+ too (`this.form.x` doesn't exist on a signal):
1725
+
1726
+ - the writes other than an assignment or a `push()` / `unshift()`: `+=`, `++`, `splice()`, `sort()`, a write inside
1727
+ an expression... Write a new value, e.g. `this.patchForm(['children'], children.filter((c) => c !== child))`;
1728
+ - the two-way bindings it can't follow: through a call or a pipe, or in a `*ngFor` over the form. Migrate the
1729
+ `*ngFor` to `@for` first (`ng generate @angular/core:control-flow`), then run the migration again;
1730
+ - the `getList()` of the detail pages which compute their list, see below.
1731
+
1732
+ Also check:
1733
+
1734
+ - your specs, which the migration doesn't change: `component.form = x` becomes `component.form.set(x)`, and
1735
+ `component.form.x` becomes `component.form()!.x` (the compiler reports them);
1736
+ - the components receiving the form, or an object of it, as an input and modifying it: they modify the value of the
1737
+ signal in place, the page isn't notified. Give them an output, and let the page write with `patchForm()`;
1738
+ - the services and the methods receiving the form, or an object of it, as an argument and modifying it, e.g. an
1739
+ `enrichWithSessionInfoData(form)` filling it with the session in the callback of `prefillForm()`: the same, and
1740
+ neither the migration nor `no-direct-signal-mutation` follow the form into them. Let them return the values, and
1741
+ the page write them with `patchForm()` or `form.update()`;
1742
+ - the fields whose type differs from the model of their component, e.g. a date typed `number[] | null`: `[(model)]`
1743
+ didn't compare them, `patchForm()` does, and the build reports its `$event` (TS2345). Type the field as the model:
1744
+ `FoehnDateModel | null` for `foehn-input-date`, `FoehnDateTimeModel | null` for `foehn-input-date-time`;
1745
+ - the `markForCheck()` called after a write of the form or of the reference (zoneless): they are useless now, remove
1746
+ them, unless they notify another field. The migration lists those of a function writing the form or the reference,
1747
+ not those of a callback given to a service.
1748
+
1749
+ `no-direct-signal-mutation` reports the writes in place left (`this.form()!.x = 1`, `form.children.push(child)`),
1750
+ `[(model)]="form.x"` inside `@if (form(); as form)` included.
1751
+
1752
+ #### Lists of the form
1753
+
1754
+ `patchForm()` replaces each object along the path with a copy: a row of a `@for` tracked by its item (`track child`)
1755
+ is then destroyed and created again at each input, and the field being edited loses the focus. Track the rows of a
1756
+ list edited by its rows by an identifier of the item (`track child.id`), or by `$index`. The migration does it for the
1757
+ lists it migrates, and `no-item-track-in-form-list` (`configs.templateRecommended`) reports the others.
1758
+
1759
+ #### Write your templates
1760
+
1761
+ ```html
1762
+ @if (form(); as form) {
1763
+ <foehn-input-text
1764
+ name="firstName"
1765
+ [model]="form.firstName"
1766
+ (modelChange)="patchForm(['firstName'], $event)"
1767
+ />
1768
+ }
1769
+ ```
1770
+
1771
+ - The path is checked by TypeScript: a typo gives an error listing the valid keys. For a form serving several
1772
+ prestations, type the page with a union (`AbstractPageComponent<ApForm | AfForm>`): the paths of each of them are
1773
+ accepted.
1774
+ - `null` and `undefined` are accepted, as with `[(model)]`: the model of the `foehn-*` components can be.
1775
+ - Never a `[model]` alone on a field the user can change: what the user enters would never reach the form.
1776
+ `require-model-change` (`configs.templateRecommended`) reports it. A field always disabled
1777
+ (`[disabled]="true"`), only displayed, is bound with `[model]` alone.
1778
+ - `@let form = this.form();`, which the migration adds, is just as valid.
1779
+ - Outside a page, `ObjectPathHelper` writes a path of any object the same way: `patch(object, path, value)`, and
1780
+ `patchSignal(signal, path, value)` for a signal holding an object (e.g. the state of a component), typed with
1781
+ `ObjectPath<T>` and `ObjectPathValue<T, P>`. `getByKeys()` and `patchByKeys()` take keys known at runtime only
1782
+ (`'address.street'`), not checked by TypeScript.
1783
+
1784
+ #### Detail pages
1785
+
1786
+ `AbstractListDetailPageComponent` no longer modifies the list of the form in place:
1787
+
1788
+ | Before | Since 19.2.0 |
1789
+ | ---------------------------------------------- | ----------------------------------------------------------------------------------------- |
1790
+ | `getList(): Dog[] { return this.form.dogs; }` | `getListPath(): ObjectPath<MyForm> { return ['dogs']; }` (`getList()` is still available) |
1791
+ | `list`, `itemIndex`, `itemToEdit` | `list()`, `itemIndex()`, `itemToEdit()` |
1792
+ | `[(model)]="itemToEdit.name"` | `[model]="item.name" (modelChange)="patchItem(['name'], $event)"` |
1793
+ | `this.itemToEdit.site = null; ...` (in place) | `this.updateItem((item) => ({ ...item, site: null, ideNumber: null }))` |
1794
+ | `[(model)]="list[itemIndex]"` (the whole item) | `[model]="item" (modelChange)="setItem($event)"` |
1795
+
1796
+ The migration replaces a `getList()` returning a path of the form (`this.form.a.b`, `this.form?.a?.b ?? []`). A
1797
+ `getList()` choosing its list (e.g. according to the prestation) becomes a `getListPath()` choosing its path:
1798
+
1799
+ ```ts
1800
+ getListPath(): ObjectPath<ApForm | AfForm> {
1801
+ return this.isAp()
1802
+ ? ['diplomeData', 'diplomes']
1803
+ : ['formationData', 'diplomes'];
1804
+ }
1805
+ ```
1806
+
1588
1807
  ### Zoneless (optional but recommended)
1589
1808
 
1590
1809
  Since v19.2, prestations-ng does not need zone.js anymore: the state of its components is held by signals, which
@@ -1665,26 +1884,9 @@ only a method called by a listener modifies: this method can later be called fro
1665
1884
 
1666
1885
  Pay attention to:
1667
1886
 
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
- ```
1887
+ - your pages (`AbstractPageComponent` and its subclasses): since 19.2.0, `form` and `reference` are signals (see "The
1888
+ form of your pages is a signal" and "`reference` of your pages is a signal"). Write the form with `patchForm()`,
1889
+ never in place: no `markForCheck()` is needed after a write.
1688
1890
 
1689
1891
  - the fields read by the template and set in `ngAfterViewInit()`, `ngAfterContentInit()` or `ngAfterViewChecked()`:
1690
1892
  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);