@dsivd/prestations-ng 19.2.0-beta.28 → 19.2.0-beta.29

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/AI_GUIDELINES.md CHANGED
@@ -47,7 +47,9 @@ Don't apply one before the step of the guide that brings it, unless asked.
47
47
  (`require-track-index`). Only a list whose rows name nothing with the index and keep a state of their own (a
48
48
  panel expanded, the focus, data loaded per item) while it can be reordered is tracked by an identifier of the item,
49
49
  unique and stable. Never by the item itself when it is replaced (`patchForm()`, a new model), nor by a field the
50
- row edits, nor by a `trackingIndex` kept by the project on its items (`FoehnListItem` has none).
50
+ row edits, nor by a `trackingIndex` kept by the project on its items (`FoehnListItem` has none). A page keeping the
51
+ errors of the server until its next save (a back office) renumbers them when it removes a row:
52
+ `ValidationHandlerService.removeListItemErrors('hearings[0].exchanges[1]')`, once per removal.
51
53
  Detail pages: `getListPath()`, `list()`, `itemToEdit()`, and `patchItem()`, `updateItem()` or `setItem()`.
52
54
  - The `modelChange` of a `foehn-*` component is emitted only when the component writes its model (an input of the
53
55
  user, a correction), never when the page changes it (form loaded, prefill, reset). React to the loaded form where
package/CHANGELOG.md CHANGED
@@ -39,7 +39,12 @@
39
39
  - `ng update` migration of 19.2.0: migrates your pages to their form and their reference held by signals, their
40
40
  classes and their templates (see the 🚨 entries below and
41
41
  [UPGRADING_V19.md](UPGRADING_V19.md#the-form-of-your-pages-is-a-signal-since-1920)). It lists what it can't
42
- migrate, and running it again changes nothing.
42
+ migrate, and running it again changes nothing. Since 19.2.0-beta.29, it also writes with `patchForm()` through a
43
+ getter of the page returning a path of the form (`this.step.motif = x`, `[(model)]="step.motif"` with
44
+ `get step() { return this.form.etape; }`, in the page or in a page it extends), and lists the writes through a
45
+ getter computing its value, the `effect()`s reading the form (directly or through a method: they run again at every
46
+ input of the user) and the methods writing the form called by the template outside an event (NG0600 while the view
47
+ is rendered).
43
48
  - 🚨 ESLint rules [`require-model-change`](ESLINT_PLUGIN.md#require-model-change) and
44
49
  [`no-item-track-in-form-list`](ESLINT_PLUGIN.md#no-item-track-in-form-list), in `configs.templateRules` and
45
50
  `configs.templateRecommended`: a one-way `[model]` reading the form without `(modelChange)` (the input of the user
@@ -109,6 +114,17 @@
109
114
  - [foehn-navigation.service.ts](projects/prestations-ng/src/foehn-navigation/foehn-navigation.service.ts)
110
115
  - new method `pendingNavigationDirection()`: direction of the navigation started with `next()` or `previous()`
111
116
  until it ends, `null` otherwise (also in 18.3.15)
117
+ - [form-error.helper.ts](projects/prestations-ng/src/validation/form-error.helper.ts) and
118
+ [validation-handler.service.ts](projects/prestations-ng/src/validation/validation-handler.service.ts) (since
119
+ 19.2.0-beta.29)
120
+ - new `FormErrorHelper.withoutListItem(errors, itemPath)`: the errors left once the item at `itemPath` (e.g.
121
+ `'hearings[0].exchanges[1]'`) is removed from its list, in a new array: its errors are dropped, and those of the
122
+ following items take the new index of their item, the items of their nested lists included
123
+ - new method `ValidationHandlerService.removeListItemErrors(itemPath)`: applies it to the errors given to
124
+ `updateErrors()` and publishes them. For a page keeping the errors of the server until its next save (e.g. a
125
+ back office) when it removes an item of a list whose fields are named with the index: the errors of the
126
+ following items would otherwise stay on their former index. No component of the library calls it. See
127
+ "Avoiding error display problems in a `@for` loop" in [GOOD_PRACTICES.md](GOOD_PRACTICES.md).
112
128
 
113
129
  ### Changed
114
130
 
@@ -239,6 +255,11 @@ Please check the [UPGRADING_V19.md](UPGRADING_V19.md) guide for more information
239
255
  TypeScript wrappers keeping the value: `this.form()!.name = value` and `(this.model() as Model).name = value` are
240
256
  now reported. In a template, it sees through `!` and the parentheses, and follows the alias of an `@if`:
241
257
  `[(model)]="form.name"` inside `@if (form(); as form)` is now reported.
258
+ - 🚨 ESLint rule [`no-direct-signal-mutation`](ESLINT_PLUGIN.md#getters-handing-out-the-value) (since
259
+ 19.2.0-beta.29) follows the getters of the class returning the value of a signal or a part of it, through its
260
+ inheritance chain: `this.step.motif = value` and `[(model)]="step.motif"` with
261
+ `get step() { return this.form()!.etape; }` are now reported, as `this.form().count++` in TypeScript. Write the form
262
+ with `patchForm()`. To turn it off: `'@dsivd/prestations-ng/no-direct-signal-mutation': 'off'`.
242
263
  - The lifecycle hooks that have nothing left to do are removed: `ngOnChanges()` of
243
264
  `foehn-agenda-timeslot-panel` and `foehn-table`, `ngAfterViewInit()` of `foehn-list-summary`, `ngOnInit()` of
244
265
  `foehn-radio` and `foehn-input-textarea`, `ngOnInit()` and `ngOnDestroy()` of `captcha`.
@@ -306,6 +327,10 @@ Please check the [UPGRADING_V19.md](UPGRADING_V19.md) guide for more information
306
327
 
307
328
  - `foehn-checkbox` and `foehn-agenda` track their rows by their index (since 19.2.0-beta.28), as the names of their
308
329
  fields: the checkboxes of elements reordered or replaced no longer share the control of the former ones.
330
+ - `foehn-agenda` follows its `disabled` input (since 19.2.0-beta.29), ignored until then: its time slots are disabled,
331
+ the navigation between the weeks stays usable. The time slot picked writes its model through `updateNgModel()`,
332
+ no longer with a two-way binding of its `model` (which bypassed the guard of a disabled component and the overrides
333
+ of `updateNgModel()`).
309
334
  - 🚨 `ObjectHelper.getNestedProperty()`, and the keys given as text to `elementValue`, `elementLabel`, `elementGroup`,
310
335
  `elementDisabled` and `elementSuggestionLabel` of `foehn-select`, `foehn-radio`, `foehn-checkbox` and the
311
336
  autocompletes, read the value at the path of the key (`'country.name'`): a value which is an object, or a getter of
package/CONTRIBUTING.md CHANGED
@@ -6,7 +6,7 @@
6
6
  - npm 10.2+
7
7
  - G++
8
8
 
9
- Chromium is downloaded by Puppeteer during `npm install`: it is used by the unit tests (through Playwright)
9
+ Chromium is downloaded by Puppeteer during `npm ci`: it is used by the unit tests (through Playwright)
10
10
  and by the e2e tests (Cypress).
11
11
 
12
12
  ## Developing using the Dev Tool
@@ -63,7 +63,7 @@ result.
63
63
 
64
64
  ### In **prestations-ng**
65
65
 
66
- - if it is the first time, execute `npm install` then `npm run build:lib` (at root level)
66
+ - if it is the first time, execute `npm ci` then `npm run build:lib` (at root level)
67
67
  - `cd dist/prestations-ng && npm link` (it's critical to link the content of `dist/prestations-ng`, not the root)
68
68
  - `cd ../.. && npm run build:lib:dev` (at root level)
69
69
 
@@ -102,7 +102,7 @@ run `npm run test:schematics` (at root level).
102
102
  ### Testing into a project such as **skeleton**
103
103
 
104
104
  - **In prestations-ng**:
105
- - if it is the first time, execute `npm install` then `npm run build:lib` (at root level)
105
+ - if it is the first time, execute `npm ci` then `npm run build:lib` (at root level)
106
106
  - `cd dist/prestations-ng && npm link` (it's critical to link the content of `dist/prestations-ng`, not the root)
107
107
  - `cd ../.. && npm run build:lib:dev` (at root level)
108
108
 
@@ -146,7 +146,10 @@ use the correct node version in the settings, otherwise it might fail. Same thin
146
146
  - **Make sure you have installed pre commit hook by running :** `npm run huskyInstall`
147
147
  - Remove unnecessary `console.log`
148
148
  - Update [CHANGELOG.md](CHANGELOG.md)
149
- - Have it up to date with `npm install`
149
+ - Install the dependencies of `package-lock.json` with `npm ci` after each pull or change of branch that changed it
150
+ (Renovate updates it every week): the tests and the lint then run on the versions Jenkins installs. Not with
151
+ `npm install` or `npm update`, which may rewrite the lock file: the dependencies are updated by the PRs of Renovate,
152
+ never in another change.
150
153
  - If you want to autofix lint/format errors in your code : `npm run format`
151
154
  - Run all tests `npm run validate`
152
155
  - Ensure the commit message contains a Jira reference
package/ESLINT_PLUGIN.md CHANGED
@@ -138,7 +138,8 @@ this.settings.update((current) => ({
138
138
  > component alone.
139
139
 
140
140
  All the assignment operators accepted by the Angular expression parser are covered: `=`,
141
- `+=`, `-=`, `*=`, `/=`, `%=`, `**=`, `&&=`, `||=`, `??=`.
141
+ `+=`, `-=`, `*=`, `/=`, `%=`, `**=`, `&&=`, `||=`, `??=`, and in TypeScript the increments
142
+ `++` and `--` (since 19.2.0-beta.29).
142
143
 
143
144
  The in-place mutators covered are those of `Array` — `push`, `pop`, `shift`, `unshift`,
144
145
  `splice`, `sort`, `reverse`, `fill`, `copyWithin` — and of `Map` / `Set` — `set`, `add`,
@@ -195,7 +196,8 @@ introduces the name — nothing is inferred from a naming convention. A variable
195
196
  for `reduce`, whose first parameter is the accumulator and not an element.
196
197
 
197
198
  **What it cannot follow** is a value crossing a function boundary — handed to a method,
198
- stored in a class field, returned and mutated elsewhere:
199
+ stored in a class field, returned by a method and mutated elsewhere (a getter is followed, see
200
+ below):
199
201
 
200
202
  ```ts
201
203
  // not reported: the rule cannot know what `sortInto` does
@@ -205,6 +207,56 @@ this.sortInto(this.settings().users);
205
207
  That needs interprocedural analysis, which ESLint does not provide; a full type checker
206
208
  would be required. It is the one remaining gap in detection.
207
209
 
210
+ #### Getters handing out the value
211
+
212
+ Since 19.2.0-beta.29, a getter of the class whose body is a single `return` of the value of
213
+ one of its signals, or of a part of it, is followed too: what it returns is that value. Such
214
+ getters are common in the pages, written before their form became a signal, and neither the
215
+ `ng update` migration nor the rule saw the writes through them until then:
216
+
217
+ ```ts
218
+ // in the page, or in an abstract page it extends
219
+ get step(): Step {
220
+ return this.form()!.etape;
221
+ }
222
+
223
+ // ✗ writes into the form, no notification
224
+ this.step.motif = value;
225
+ this.step.documents.push(document);
226
+
227
+ // ✓
228
+ this.patchForm(['etape', 'motif'], value);
229
+ this.patchForm(['etape', 'documents'], [...(this.step.documents ?? []), document]);
230
+ ```
231
+
232
+ ```angular-html
233
+ <!-- ✗ -->
234
+ <foehn-input-text name="motif" [(model)]="step.motif" />
235
+
236
+ <!-- ✓ -->
237
+ <foehn-input-text
238
+ name="motif"
239
+ [model]="step.motif"
240
+ (modelChange)="patchForm(['etape', 'motif'], $event)"
241
+ />
242
+ ```
243
+
244
+ The getter is resolved like the signals, through the inheritance chain (a getter of an
245
+ abstract page of your project is followed in its subclasses and their templates), and the
246
+ message names it with the signal: _Mutation of the value of the signal `form` through the
247
+ getter `step` detected_. A getter returning another such getter read further
248
+ (`get motif() { return this.step.motif; }`) is followed as well.
249
+
250
+ Left alone:
251
+
252
+ - the getter itself as the target (`this.step = value`, `[(step)]="step"`): it calls its
253
+ setter;
254
+ - a getter computing its value (`return this.form()?.etape ?? new Step();`, a copy, a
255
+ filter...) or made of more than a `return`: what it returns may not be the value of the
256
+ signal;
257
+ - a getter of a published library (its `.d.ts` has no body), and a name of the template
258
+ hiding the getter (`@for (step of steps; …)`).
259
+
208
260
  #### Only real signals are inspected
209
261
 
210
262
  The rule does not guess from the shape of a call. It reads the declaring class — the linted
package/GOOD_PRACTICES.md CHANGED
@@ -1236,6 +1236,26 @@ export class YourPageComponent
1236
1236
  It's up to you to decide how to call this method when the item is removed from
1237
1237
  your list.
1238
1238
 
1239
+ A page handling the errors itself (see "Manual handling" in "Form validation") and keeping those of the server
1240
+ until its next save, e.g. a back office, has no validation to call: when it removes an item, it renumbers the errors
1241
+ with `removeListItemErrors()` of `ValidationHandlerService`. The errors of the removed item are dropped, and those of
1242
+ the following items take the new index of their item, the items of their nested lists included
1243
+ (`FormErrorHelper.withoutListItem()` does the same on an array of errors):
1244
+
1245
+ ```ts
1246
+ private readonly validationHandlerService = inject(ValidationHandlerService);
1247
+
1248
+ removeExchange(hearingIndex: number, exchangeIndex: number): void {
1249
+ // ... remove the exchange from the model, in a new array
1250
+ this.validationHandlerService.removeListItemErrors(
1251
+ `hearings[${hearingIndex}].exchanges[${exchangeIndex}]`,
1252
+ );
1253
+ }
1254
+ ```
1255
+
1256
+ No component of the library calls it: call it once per removal, and not besides a code of yours renumbering the
1257
+ errors already, or they would move twice.
1258
+
1239
1259
  Here is an elegant way to handle your lists of items:
1240
1260
 
1241
1261
  - Structure of the folders and files
package/README.md CHANGED
@@ -8,17 +8,23 @@ The generated documentation of our entire library is available online at [https:
8
8
 
9
9
  The documentation is available online at [https://dsi-vd.github.io/prestations-ng/](https://dsi-vd.github.io/prestations-ng/)
10
10
 
11
- - If you're using **Angular 21**, use `@dsivd/prestations-ng` at version `^19`.
12
- - If you're using **Angular 19**, use `@dsivd/prestations-ng` at version `^18`.
13
- - If you're using **Angular 17**, use `@dsivd/prestations-ng` at version `^17`.
14
- - If you're using **Angular 15**, use `@dsivd/prestations-ng` at version `^16`.
15
- - If you're using **Angular 13**, use `@dsivd/prestations-ng` at version `^15`.
16
- - If you're using **Angular 12**, use `@dsivd/prestations-ng` at version `^14.5.0`.
17
- - If you're using **Angular 11**, use `@dsivd/prestations-ng` at version `^13` until `14.4.1`.
18
- - If you're using **Angular 9**, use `@dsivd/prestations-ng` at version `^11`.
19
- - If you're using **Angular 8**, use `@dsivd/prestations-ng` at version `^9`.
20
- - If you're using **Angular 6 or 7**, use `@dsivd/prestations-ng` at version `^8`.
21
- - If you're using **Angular 5**, use `prestations-ng` at version `^7`.
11
+ - If you're using **Angular 21**, use `@dsivd/prestations-ng` at version `19`.
12
+ - If you're using **Angular 19**, use `@dsivd/prestations-ng` at version `18`.
13
+ - If you're using **Angular 17**, use `@dsivd/prestations-ng` at version `17`.
14
+ - If you're using **Angular 15**, use `@dsivd/prestations-ng` at version `16`.
15
+ - If you're using **Angular 13**, use `@dsivd/prestations-ng` at version `15`.
16
+ - If you're using **Angular 12**, use `@dsivd/prestations-ng` at version `14`, from `14.5.0`.
17
+ - If you're using **Angular 11**, use `@dsivd/prestations-ng` at version `13`, or `14` until `14.4.1`.
18
+ - If you're using **Angular 9**, use `@dsivd/prestations-ng` at version `11`.
19
+ - If you're using **Angular 8**, use `@dsivd/prestations-ng` at version `9`.
20
+ - If you're using **Angular 6 or 7**, use `@dsivd/prestations-ng` at version `8`.
21
+ - If you're using **Angular 5**, use `prestations-ng` at version `7`.
22
+
23
+ These are the major versions to use. In your `package.json`, declare the library with a tilde (e.g.
24
+ `"@dsivd/prestations-ng": "~19.2.0"`): a minor version may break and goes with the same minor version of
25
+ `prestations-be` (see "Dependency on `prestations-be`" below), and a caret would let `npm install` or the lock file
26
+ maintenance of Renovate install the next one. `npm install @dsivd/prestations-ng@<version>` writes a caret, even over a
27
+ tilde: install a version with `npm install @dsivd/prestations-ng@~<version>`.
22
28
 
23
29
  The library also ships an ESLint plugin whose rules apply to your project: see
24
30
  [the plugin guide](ESLINT_PLUGIN.md).
@@ -44,7 +50,7 @@ Migration guides are available to provide an upgrade path from one major version
44
50
 
45
51
  `@dsivd/prestations-ng` is part of [PrestaKit](https://www.vd.ch/prestakit/) and depends on `prestations-be`.
46
52
 
47
- In order to use all the features of `@dsivd/prestation-ng`, you must use the same minor version of `prestations-be`, see [Notes about versioning in Prestakit](CHANGELOG.md#notes-about-versioning-in-prestakit)
53
+ In order to use all the features of `@dsivd/prestations-ng`, you must use the same minor version of `prestations-be`, see [Notes about versioning in Prestakit](README_COMMON.md#notes-about-versioning-in-prestakit)
48
54
 
49
55
  `prestations-be` is available on the DSI-VD Maven repository. An exemple of integration is available with [Eldorado](https://prestations.vd.ch/pub/101016).
50
56
 
package/UPGRADING_V19.md CHANGED
@@ -259,6 +259,10 @@ ng update @angular/core@19 @angular/cli@19
259
259
  ng update @dsivd/prestations-ng@18
260
260
  ```
261
261
 
262
+ 🚨 **WARNING: `ng update` keeps the prefix of the version declared in your `package.json`. If it declares
263
+ `@dsivd/prestations-ng` with a caret (e.g. `"^18.3.16"`), replace it with a tilde (`"~18.3.16"`), then run
264
+ `npm install`: a minor version may break, as it goes with the same minor version of `prestations-be`.**
265
+
262
266
  #### Switch to node 22+
263
267
 
264
268
  ##### If you are using our `slave-apps`
@@ -369,6 +373,10 @@ ng update @dsivd/prestations-ng@latest
369
373
  - accept **"router-current-navigation"** by hitting "Space" key
370
374
  - hit "Enter" key
371
375
 
376
+ 🚨 **WARNING: `ng update` keeps the prefix of the version declared in your `package.json`. If it declares
377
+ `@dsivd/prestations-ng` with a caret (e.g. `"^19.1.4"`), replace it with a tilde (`"~19.1.4"`), then run
378
+ `npm install`: a minor version may break, as it goes with the same minor version of `prestations-be`.**
379
+
372
380
  ```bash
373
381
  ng update @angular/cli@21
374
382
  ```
@@ -1709,6 +1717,34 @@ In the templates, it reads it through a `@let reference = this.reference();`, so
1709
1717
  (`[reference]="reference"`). It removes a field of a page declaring `reference` again (e.g. `reference: string;`),
1710
1718
  which would hide the signal, and lists such a field holding a value.
1711
1719
 
1720
+ The migration only adds the parentheses: the request still leaves when your code sends it, whatever the reference
1721
+ (`api/undefined/...` before the form is loaded), and isn't sent again when the reference changes. Turn a request built
1722
+ with the reference into a resource (see [AI_GUIDELINES.md](AI_GUIDELINES.md)), which waits for the reference and
1723
+ replaces the subscription, or the `async` pipe, and the fields that only served it. E.g. the sections of the
1724
+ verification page:
1725
+
1726
+ ```ts
1727
+ readonly recapSections = httpResource<FoehnRecapSection[]>(
1728
+ () => {
1729
+ const reference = this.reference();
1730
+ return reference ? `api/${reference}/pdf-sections` : undefined;
1731
+ },
1732
+ { defaultValue: [] },
1733
+ );
1734
+ ```
1735
+
1736
+ ```angular
1737
+ @if (recapSections.hasValue()) {
1738
+ @for (section of recapSections.value(); track $index) {
1739
+ <foehn-recap-section [data]="section" />
1740
+ }
1741
+ }
1742
+ ```
1743
+
1744
+ A request built by a method of a service: an `rxResource()` over it, whose `params` return `undefined` while the
1745
+ reference is missing. See "`rxResource()`" in [INTRODUCTION_ANGULAR_SIGNALS.md](INTRODUCTION_ANGULAR_SIGNALS.md),
1746
+ for your specs too.
1747
+
1712
1748
  For a code it doesn't migrate (a class it doesn't recognize as a page):
1713
1749
 
1714
1750
  - in the templates, `no-uninvoked-signal-in-template` (`configs.templateRecommended` or `configs.templateRules`, see
@@ -1796,6 +1832,37 @@ too (`this.form.x` doesn't exist on a signal):
1796
1832
  `*ngFor` to `@for` first (`ng generate @angular/core:control-flow`), then run the migration again;
1797
1833
  - the `getList()` of the detail pages which compute their list, see below.
1798
1834
 
1835
+ It follows the getters of the page returning a path of the form, declared by the page or by a page it extends
1836
+ (since 19.2.0-beta.29, also in a page migrated by an earlier beta):
1837
+
1838
+ ```diff
1839
+ get step(): Step {
1840
+ - return this.form.etape;
1841
+ + return this.form()!.etape;
1842
+ }
1843
+
1844
+ - this.step.motif = value;
1845
+ + this.patchForm(['etape', 'motif'], value);
1846
+ ```
1847
+
1848
+ ```diff
1849
+ - <foehn-input-text name="motif" [(model)]="step.motif" />
1850
+ + <foehn-input-text name="motif" [model]="step.motif" (modelChange)="patchForm(['etape', 'motif'], $event)" />
1851
+ ```
1852
+
1853
+ Since 19.2.0-beta.29, it also lists what the compiler doesn't report:
1854
+
1855
+ - the writes through a getter it can't rewrite, or through a getter computing its value
1856
+ (`return this.form?.etape ?? new Step();`): what such a getter returns may not be in the form. Write the form with
1857
+ `patchForm()`, the path of the field in full;
1858
+ - the `effect()`s reading the form, directly or through a method they call: the migration turns `this.form` into
1859
+ `this.form()` there too, and the effect then runs again at every input of the user. When the form isn't a trigger
1860
+ of the effect, read it with `untracked(this.form)`, or call the method in `untracked(() => this.applyResult(x))`;
1861
+ - the methods of the page writing the form or the reference called by its template outside an event
1862
+ (`@if (initDefaults())`, `[hidden]="!check()"`, `{{ total() }}`): a signal written while the view is rendered
1863
+ throws NG0600. Make them pure, and write the form where it is loaded (see "`(modelChange)` is emitted only when
1864
+ the component writes its model").
1865
+
1799
1866
  Also check:
1800
1867
 
1801
1868
  - your specs, which the migration doesn't change: `component.form = x` becomes `component.form.set(x)`, and
@@ -1814,7 +1881,8 @@ Also check:
1814
1881
  not those of a callback given to a service.
1815
1882
 
1816
1883
  `no-direct-signal-mutation` reports the writes in place left (`this.form()!.x = 1`, `form.children.push(child)`),
1817
- `[(model)]="form.x"` inside `@if (form(); as form)` included.
1884
+ `[(model)]="form.x"` inside `@if (form(); as form)` included, and since 19.2.0-beta.29 those through a getter of the
1885
+ page returning the form or a part of it (`this.step.motif = x`, `[(model)]="step.motif"`).
1818
1886
 
1819
1887
  #### Lists of the form
1820
1888
 
@@ -8,7 +8,7 @@ import {
8
8
  VIEW_QUERY,
9
9
  WRITABLE,
10
10
  } from "../signal-kinds.mjs";
11
- import { collectSignalKinds } from "../signal-names.mjs";
11
+ import { collectSignalAliases, collectSignalKinds } from "../signal-names.mjs";
12
12
  import {
13
13
  handlerExpressionOf,
14
14
  isComponentReceiver,
@@ -30,6 +30,10 @@ import {
30
30
  *
31
31
  * Only the signals the class really declares are inspected, resolved through the whole
32
32
  * inheritance chain, so a plain method (`this.getConfig().items.push(x)`) is left alone.
33
+ *
34
+ * A getter of the class returning the value of a signal, or a part of it
35
+ * (`get step() { return this.form()!.step; }`), hands out that value too: a write through
36
+ * it (`this.step.motif = x`, `[(model)]="step.motif"`) is reported as well.
33
37
  */
34
38
 
35
39
  // Kinds a mutation is not reported on: a view query hands out a DOM element or a component
@@ -201,6 +205,33 @@ function signalFactoryKind(node) {
201
205
  return callee?.type === "Identifier" ? factoryKind(callee.name) : undefined;
202
206
  }
203
207
 
208
+ // The value of a signal of the class: its kind, and the getter it was read through, if any.
209
+ const valueOf = (kind) => (kind ? { kind } : undefined);
210
+
211
+ /**
212
+ * The getter of the class a member chain reads first, `this.step` in `this.step.motif`,
213
+ * when it aliases the value of a signal. `undefined` for anything else.
214
+ */
215
+ function aliasReadOf(node, scopeContext) {
216
+ let current = node;
217
+ while (
218
+ current?.type === "MemberExpression" ||
219
+ TYPE_WRAPPERS.has(current?.type)
220
+ ) {
221
+ if (
222
+ current.type === "MemberExpression" &&
223
+ current.object.type === "ThisExpression"
224
+ ) {
225
+ const name = current.computed ? undefined : getCalledName(current);
226
+ const alias = name ? scopeContext.alias(name) : undefined;
227
+ return alias ? { ...alias, getter: name } : undefined;
228
+ }
229
+ current =
230
+ current.type === "MemberExpression" ? current.object : current.expression;
231
+ }
232
+ return undefined;
233
+ }
234
+
204
235
  function signalRootCallKind(node, scopeContext) {
205
236
  if (node.arguments.length !== 0) {
206
237
  return undefined;
@@ -233,14 +264,18 @@ function signalRootCallKind(node, scopeContext) {
233
264
  }
234
265
 
235
266
  /**
236
- * Kind of signal whose value an expression evaluates to, `undefined` when it is not one.
237
- * The expression may be the signal read itself (`this.model()`), a member of its value
238
- * (`this.model().items`), or a name bound to either.
267
+ * The value of a signal an expression evaluates to (`{ kind, getter? }`), `undefined` when
268
+ * it is not one. The expression may be the signal read itself (`this.model()`), a member of
269
+ * its value (`this.model().items`), a getter aliasing either (`this.step.items`), or a name
270
+ * bound to any of them.
239
271
  */
240
272
  function signalValueKind(node, scopeContext, seen = new Set()) {
241
273
  const base = baseOf(node);
242
274
  if (base?.type === "CallExpression") {
243
- return signalRootCallKind(base, scopeContext);
275
+ return valueOf(signalRootCallKind(base, scopeContext));
276
+ }
277
+ if (base?.type === "ThisExpression") {
278
+ return aliasReadOf(node, scopeContext);
244
279
  }
245
280
  return base?.type === "Identifier"
246
281
  ? boundNameSignalKind(base, scopeContext, seen)
@@ -314,7 +349,7 @@ function signalRootTemplateCallKind(node, templateContext) {
314
349
  return undefined;
315
350
  }
316
351
  return isComponentReceiver(callee.receiver)
317
- ? templateContext.memberKind(callee.name ?? "")
352
+ ? valueOf(templateContext.memberKind(callee.name ?? ""))
318
353
  : undefined;
319
354
  }
320
355
 
@@ -352,10 +387,19 @@ function boundTemplateExpression(read, templateContext) {
352
387
  }
353
388
 
354
389
  /**
355
- * Template counterpart of `signalValueKind`: the value a signal holds, a member of it, or
356
- * a template name bound to either.
390
+ * Template counterpart of `signalValueKind`: the value a signal holds, a member of it, a
391
+ * getter of the component aliasing either, or a template name bound to any of them.
392
+ *
393
+ * `assigned`: the expression is the target of an assignment (`step.motif = x`, or the
394
+ * expression of a two-way binding), so the getter itself as the whole target
395
+ * (`step = x`) calls its setter and mutates nothing.
357
396
  */
358
- function signalTemplateValueKind(node, templateContext, seen = new Set()) {
397
+ function signalTemplateValueKind(
398
+ node,
399
+ templateContext,
400
+ seen = new Set(),
401
+ assigned = false,
402
+ ) {
359
403
  const value = unwrapTemplate(node);
360
404
  if (value?.type === "Call" || value?.type === "SafeCall") {
361
405
  return signalRootTemplateCallKind(value, templateContext);
@@ -379,11 +423,15 @@ function signalTemplateValueKind(node, templateContext, seen = new Set()) {
379
423
  return undefined;
380
424
  }
381
425
  seen.add(base.name);
382
- return signalTemplateValueKind(
383
- boundTemplateExpression(base, templateContext),
384
- templateContext,
385
- seen,
386
- );
426
+ const bound = boundTemplateExpression(base, templateContext);
427
+ if (bound === undefined) {
428
+ // A member of the component, not shadowed by a name of the template.
429
+ const alias = templateContext.alias(base.name);
430
+ return alias && (value !== base || !assigned)
431
+ ? { ...alias, getter: base.name }
432
+ : undefined;
433
+ }
434
+ return signalTemplateValueKind(bound, templateContext, seen);
387
435
  }
388
436
 
389
437
  // Method a template call invokes, `undefined` when the name is not statically known.
@@ -413,6 +461,8 @@ export default {
413
461
  "In-place mutation of a signal's value detected. `{{method}}` changes the value without notifying the signal: use .update() with a new value instead.",
414
462
  readOnlyMutation:
415
463
  "Mutation of the value of {{kind}} detected, which notifies none of its dependents. {{advice}}.",
464
+ getterMutation:
465
+ "Mutation of the value of {{signal}} through the getter `{{getter}}` detected, which notifies none of its dependents. {{advice}}.",
416
466
  },
417
467
  },
418
468
 
@@ -422,18 +472,41 @@ export default {
422
472
  const declaringPath =
423
473
  resolveComponentPath(context.filename) ?? context.filename;
424
474
  const memberKinds = collectSignalKinds(declaringPath);
475
+ const aliases = collectSignalAliases(declaringPath);
425
476
 
426
477
  // `memberKinds` is undefined when the declaring file could not be read: its signals
427
478
  // are unknown, so fall back to treating every argument-less accessor as a writable
428
- // one. A false positive costs a disable comment; a missed mutation is silent.
479
+ // one. A false positive costs a disable comment; a missed mutation is silent. Its
480
+ // getters are unknown too: none is taken for an alias.
429
481
  const memberKind = (name) =>
430
482
  memberKinds ? memberKinds.get(name) : WRITABLE;
483
+ const alias = (name) => aliases?.get(name);
431
484
 
432
- const reportMutation = (node, kind, method) => {
485
+ const reportMutation = (node, value, method) => {
486
+ const kind = value?.kind;
433
487
  if (!kind || TOLERATED_KINDS.has(kind)) {
434
488
  return;
435
489
  }
436
- if (kind !== WRITABLE) {
490
+ if (value.getter) {
491
+ const [name, advice] =
492
+ kind === WRITABLE
493
+ ? [
494
+ "the signal",
495
+ method
496
+ ? `\`${method}\` changes it in place: write a new value with .set() or .update() instead (patchForm() for the form of a page)`
497
+ : "Write a new value with .set() or .update() instead (patchForm() for the form of a page)",
498
+ ]
499
+ : READ_ONLY_ADVICE[kind];
500
+ context.report({
501
+ node,
502
+ messageId: "getterMutation",
503
+ data: {
504
+ signal: `${name} \`${value.signal}\``,
505
+ getter: value.getter,
506
+ advice,
507
+ },
508
+ });
509
+ } else if (kind !== WRITABLE) {
437
510
  const [name, advice] = READ_ONLY_ADVICE[kind];
438
511
  context.report({
439
512
  node,
@@ -447,9 +520,9 @@ export default {
447
520
  }
448
521
  };
449
522
 
450
- const scopeContext = { memberKind, sourceCode: context.sourceCode };
523
+ const scopeContext = { memberKind, alias, sourceCode: context.sourceCode };
451
524
  // `@let` bindings, always declared before they are used.
452
- const templateContext = { memberKind, letBindings: new Map() };
525
+ const templateContext = { memberKind, alias, letBindings: new Map() };
453
526
 
454
527
  const checkTemplateInPlaceCall = (node) => {
455
528
  const method = templateMethodName(node.receiver);
@@ -471,6 +544,16 @@ export default {
471
544
  }
472
545
  },
473
546
 
547
+ // `this.model().count++` writes into the value, like `+= 1`.
548
+ UpdateExpression(node) {
549
+ if (node.argument.type === "MemberExpression") {
550
+ reportMutation(
551
+ node,
552
+ signalValueKind(node.argument.object, scopeContext),
553
+ );
554
+ }
555
+ },
556
+
474
557
  UnaryExpression(node) {
475
558
  // `delete model().users[0]` drops an entry of the value, notifying nothing.
476
559
  if (
@@ -519,7 +602,7 @@ export default {
519
602
  if (TEMPLATE_ASSIGNMENTS.has(node.operation)) {
520
603
  reportMutation(
521
604
  node,
522
- signalTemplateValueKind(node.left, templateContext),
605
+ signalTemplateValueKind(node.left, templateContext, new Set(), true),
523
606
  );
524
607
  }
525
608
  },
@@ -537,7 +620,7 @@ export default {
537
620
  const handler = handlerExpressionOf(node);
538
621
  reportMutation(
539
622
  handler,
540
- signalTemplateValueKind(handler, templateContext),
623
+ signalTemplateValueKind(handler, templateContext, new Set(), true),
541
624
  );
542
625
  },
543
626
  };