@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.
- package/ANGULAR_SIGNALS.md +4 -0
- package/CHANGELOG.md +113 -3
- package/CONTRIBUTING.md +2 -2
- package/ESLINT_PLUGIN.md +146 -28
- package/GOOD_PRACTICES.md +258 -58
- package/INTRODUCTION_ANGULAR_SIGNALS.md +29 -2
- package/UPGRADING_V19.md +233 -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 +172 -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 +948 -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 +671 -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 +234 -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 +172 -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 +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.
|
|
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
|
|
|
@@ -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
|
-
|
|
1555
|
-
|
|
1556
|
-
|
|
1557
|
-
|
|
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
|
-
[
|
|
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`
|
|
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
|
-
```
|
|
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
|
+
}
|
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);
|