@dsivd/prestations-ng 19.2.0-beta.3 → 19.2.0-beta.30

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 (65) hide show
  1. package/AI_GUIDELINES.md +152 -0
  2. package/ANGULAR_SIGNALS.md +6 -2
  3. package/CHANGELOG.md +476 -0
  4. package/CONTRIBUTING.md +128 -8
  5. package/ESLINT_PLUGIN.md +262 -30
  6. package/GOOD_PRACTICES.md +983 -388
  7. package/INTRODUCTION_ANGULAR_SIGNALS.md +227 -155
  8. package/README.md +22 -12
  9. package/UPGRADING_V18.md +5 -5
  10. package/UPGRADING_V19.md +636 -19
  11. package/eslint/configs/spec-ts-recommended.mjs +34 -0
  12. package/eslint/configs/template-recommended.mjs +2 -0
  13. package/eslint/configs/template-rules.mjs +14 -2
  14. package/eslint/configs/ts-recommended.mjs +11 -0
  15. package/eslint/configs/ts-rules.mjs +6 -2
  16. package/eslint/form-reads.mjs +63 -0
  17. package/eslint/index.mjs +17 -0
  18. package/eslint/rules/index.mjs +6 -0
  19. package/eslint/rules/no-direct-signal-mutation.mjs +162 -41
  20. package/eslint/rules/no-item-track-in-form-list.mjs +173 -0
  21. package/eslint/rules/no-uninvoked-signal-in-template.mjs +8 -3
  22. package/eslint/rules/require-model-change.mjs +89 -0
  23. package/eslint/rules/require-track-index.mjs +162 -0
  24. package/eslint/signal-names.mjs +127 -21
  25. package/eslint/template-ast.mjs +12 -2
  26. package/fesm2022/dsivd-prestations-ng.mjs +2889 -2061
  27. package/fesm2022/dsivd-prestations-ng.mjs.map +1 -1
  28. package/package.json +1 -2
  29. package/schematics/migration-collection.json +5 -0
  30. package/schematics/ng-add/index.js +2 -4
  31. package/schematics/ng-update/migrations/update-13_2_0/index.js +7 -2
  32. package/schematics/ng-update/migrations/update-19_2_0/index.js +52 -0
  33. package/schematics/utility/add-allowed-common-js-dependencies.js +39 -29
  34. package/schematics/utility/form-signal/class-migration.js +795 -0
  35. package/schematics/utility/form-signal/edits.js +34 -0
  36. package/schematics/utility/form-signal/form-members.js +318 -0
  37. package/schematics/utility/form-signal/form-signal-migration.js +134 -0
  38. package/schematics/utility/form-signal/page-classes.js +139 -0
  39. package/schematics/utility/form-signal/template-migration.js +775 -0
  40. package/schematics/utility/never-connected-migration.js +87 -0
  41. package/schematics/utility/remove-emit-decorator-metadata.js +8 -9
  42. package/schematics/utility/typescript-files.js +95 -0
  43. package/src/eslint/configs/__tests__/configs.test.mjs +61 -2
  44. package/src/eslint/configs/spec-ts-recommended.mjs +34 -0
  45. package/src/eslint/configs/template-recommended.mjs +2 -0
  46. package/src/eslint/configs/template-rules.mjs +14 -2
  47. package/src/eslint/configs/ts-recommended.mjs +11 -0
  48. package/src/eslint/configs/ts-rules.mjs +6 -2
  49. package/src/eslint/form-reads.mjs +63 -0
  50. package/src/eslint/index.mjs +17 -0
  51. package/src/eslint/rules/__tests__/no-direct-signal-mutation.test.mjs +200 -0
  52. package/src/eslint/rules/__tests__/no-item-track-in-form-list.test.mjs +234 -0
  53. package/src/eslint/rules/__tests__/no-uninvoked-signal-in-template.test.mjs +6 -0
  54. package/src/eslint/rules/__tests__/require-model-change.test.mjs +93 -0
  55. package/src/eslint/rules/__tests__/require-track-index.test.mjs +106 -0
  56. package/src/eslint/rules/index.mjs +6 -0
  57. package/src/eslint/rules/no-direct-signal-mutation.mjs +162 -41
  58. package/src/eslint/rules/no-item-track-in-form-list.mjs +173 -0
  59. package/src/eslint/rules/no-uninvoked-signal-in-template.mjs +8 -3
  60. package/src/eslint/rules/require-model-change.mjs +89 -0
  61. package/src/eslint/rules/require-track-index.mjs +162 -0
  62. package/src/eslint/signal-names.mjs +127 -21
  63. package/src/eslint/template-ast.mjs +12 -2
  64. package/types/dsivd-prestations-ng.d.ts +719 -243
  65. package/dsivd-prestations-ng-19.2.0-beta.3.tgz +0 -0
package/CONTRIBUTING.md CHANGED
@@ -4,9 +4,11 @@
4
4
 
5
5
  - Node 22.18+
6
6
  - npm 10.2+
7
- - Chrome or Chromium
8
7
  - G++
9
8
 
9
+ Chromium is downloaded by Puppeteer during `npm ci`: it is used by the unit tests (through Playwright)
10
+ and by the e2e tests (Cypress).
11
+
10
12
  ## Developing using the Dev Tool
11
13
 
12
14
  Since version `8`, `prestations-ng` has a standalone application that allows
@@ -16,6 +18,43 @@ in an actual prestation: the Dev Tool.
16
18
  To start the Dev Tool, run `npm start`. This will ensure that modifications
17
19
  in both the Dev Tool and the library reload the page.
18
20
 
21
+ ### GitHub Pages documentation
22
+
23
+ Each release publishes the Dev Tool on GitHub Pages, in the place given by the **NPM_TAG** of the Jenkins build and by
24
+ its version:
25
+
26
+ | Place | Release |
27
+ | --------------------------- | ----------------------------------------------------------------------------- |
28
+ | `/prestations-ng/` | STABLE, from master or from the release branch of the current minor version |
29
+ | `/prestations-ng/beta/` | NEXT |
30
+ | `/prestations-ng/lts/` | LTS |
31
+ | `/prestations-ng/lts/beta/` | NEXT of the LTS line, older than the beta in place (created by the first one) |
32
+
33
+ The documentation of a release never replaces a more recent one: a patch of an older minor version (e.g. 19.1.4 once
34
+ 19.2.0 is published) or a beta of a release branch other than the LTS one publishes nothing. Whatever the released
35
+ branch, Jenkins runs the scripts of `build-scripts/github-pages` of master (see `jenkins/Release.groovy`): they must
36
+ keep working with the Node version and the dependencies of the oldest branch still released.
37
+
38
+ Each publication:
39
+
40
+ - records its version in a `versions.json` written next to each `index.html`. The version switcher of the Dev Tool
41
+ (`src/app/core/version-switcher`), placed in the empty language column of the header, lists the other documentations,
42
+ except a beta whose version is published, and keeps the page displayed. `npm start` serves a demo `versions.json`
43
+ (`src/dev-assets`), where the local app is labelled `Local`;
44
+ - updates the shared `404.html` and adds the URL restoration to the index of each documentation, so deep links return
45
+ to the correct one. GitHub Pages still returns HTTP 404 for the initial deep-link request. Keep the places of
46
+ `github-pages.js`, the fallback and the restoration script in sync.
47
+
48
+ To publish the documentation of a checkout by hand (e.g. a branch without a release), from its root, with its
49
+ `node_modules` installed and the rights to push to the GitHub repository:
50
+
51
+ ```bash
52
+ git fetch origin master
53
+ mkdir -p node_modules/.cache/github-pages-scripts
54
+ git archive FETCH_HEAD build-scripts/github-pages | tar -x -C node_modules/.cache/github-pages-scripts
55
+ node node_modules/.cache/github-pages-scripts/build-scripts/github-pages/publish-doc.js STABLE # or LTS, NEXT
56
+ ```
57
+
19
58
  ## Testing the library in integration
20
59
 
21
60
  Since version `8`, we can't use native symlink to integrate `prestations-ng` to
@@ -24,7 +63,7 @@ result.
24
63
 
25
64
  ### In **prestations-ng**
26
65
 
27
- - 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)
28
67
  - `cd dist/prestations-ng && npm link` (it's critical to link the content of `dist/prestations-ng`, not the root)
29
68
  - `cd ../.. && npm run build:lib:dev` (at root level)
30
69
 
@@ -63,7 +102,7 @@ run `npm run test:schematics` (at root level).
63
102
  ### Testing into a project such as **skeleton**
64
103
 
65
104
  - **In prestations-ng**:
66
- - 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)
67
106
  - `cd dist/prestations-ng && npm link` (it's critical to link the content of `dist/prestations-ng`, not the root)
68
107
  - `cd ../.. && npm run build:lib:dev` (at root level)
69
108
 
@@ -92,9 +131,10 @@ This project uses a set of scripts to lint and format the code, along with pre-c
92
131
 
93
132
  Important scripts are :
94
133
 
95
- - `npm run lint` : run ESLint and Prettier on all files
134
+ - `npm run lint` : run ESLint and Prettier on all files, and check the types of the TypeScript files compiled by no
135
+ build (`lint:types`: `cypress/`, which Cypress only transpiles, and the configuration files of `tsconfig.config.json`)
96
136
  - `npm run format`: run ESLint and Prettier on all files and fix errors automatically
97
- - `npm run validate`: clean and run all tests
137
+ - `npm run validate`: clean, lint and run all tests
98
138
 
99
139
  **Husky** is used as a pre-commit hook to automatically output linting and formatting errors for staged files before committing.
100
140
  In the end, this utilitary calls `npm run lint-staged` which you can also call yourself of course. To have this pre-commit hook,
@@ -106,7 +146,10 @@ use the correct node version in the settings, otherwise it might fail. Same thin
106
146
  - **Make sure you have installed pre commit hook by running :** `npm run huskyInstall`
107
147
  - Remove unnecessary `console.log`
108
148
  - Update [CHANGELOG.md](CHANGELOG.md)
109
- - 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.
110
153
  - If you want to autofix lint/format errors in your code : `npm run format`
111
154
  - Run all tests `npm run validate`
112
155
  - Ensure the commit message contains a Jira reference
@@ -127,7 +170,11 @@ Please make sure you have followed the **Before committing** section so you will
127
170
  The library ships its own ESLint plugin (see [ESLINT_PLUGIN.md](ESLINT_PLUGIN.md)). Its rules
128
171
  reach every consuming project through shareable configs, so **adding a rule breaks the lint of
129
172
  those projects on their next `npm update`**. That is the intent, but it makes the checklist
130
- below mandatory:
173
+ below mandatory.
174
+
175
+ First check that no rule covers the case already: the rules of the plugin (extend one, or keep
176
+ the messages of overlapping rules consistent), those of `@angular-eslint`, `typescript-eslint`
177
+ and ESLint (enable it in a config of `configs/` rather than writing a new one).
131
178
 
132
179
  1. Write the rule in `projects/prestations-ng/src/eslint/rules/<rule-name>.mjs`
133
180
  2. Register it in `rules/index.mjs`, keyed by its public kebab-case name
@@ -163,12 +210,14 @@ Please use the dedicated Jenkins build:
163
210
  - Choose **STABLE** in **NPM_TAG** when certain that your release is stable otherwise choose **NEXT** which will publish a **v1.2.3-BETA** on NPM
164
211
  - Check **RUN_TEST** if you wish to validate the library's test (can take a while)
165
212
 
213
+ The release also publishes its documentation (see [GitHub Pages documentation](#github-pages-documentation)).
214
+
166
215
  Alternatively, you can manually publish the package. Although this method is not recommended.
167
216
 
168
217
  - Ensure you can push to the npm registry: `npm adduser --registry=https://registry.npmjs.org --scope=@dsivd`
169
218
  - Update the version number in `package.json` either manually or with `npm version`
170
219
  - Commit and tag the version change
171
- - Package a new version of the library with `npm package`
220
+ - Package a new version of the library with `npm run package`
172
221
  - Publish the package:
173
222
  - `npm run publish:stable` for stable version (released to everybody)
174
223
  - `npm run publish:next` for next version (development only)
@@ -218,6 +267,77 @@ export NODE_OPTIONS=--max_old_space_size=4096
218
267
 
219
268
  Use at your own risks.
220
269
 
270
+ ## Writing signal-first code
271
+
272
+ The library is zoneless: Angular refreshes a component when a signal read by its template changes, or when the
273
+ component is notified (see "Zoneless application" in [GOOD_PRACTICES.md](GOOD_PRACTICES.md) and
274
+ [ANGULAR_SIGNALS.md](ANGULAR_SIGNALS.md)). Write the code as it would be written today with signals, not around a
275
+ mechanism inherited from zone.js:
276
+
277
+ - State read by a template: a `signal()`. State derived from other signals (inputs, model, view queries): a
278
+ `computed()`, or a `linkedSignal()` when it can also be changed locally. Don't keep a signal in sync from
279
+ `ngOnChanges()`, `onModelChange()`, an `effect()` or a `setTimeout()` when it can be derived.
280
+ - React to a signal input with `computed()` or `linkedSignal()`, not with `ngOnChanges()`.
281
+ - Never mutate a value held by a signal or bound to an input (`push()`, `splice()`, `sort()`): write a new array or
282
+ object. No copy is then needed "so that the change detection sees a new reference".
283
+ - Asynchronous work: data read by a GET is an `httpResource()`, or an `rxResource()` over the method of a service
284
+ (Angular 21 has the API of Angular 22, where they are stable), read behind `hasValue()`. Otherwise set a signal in
285
+ the callback, or convert the `Observable` with `toSignal()` where it is displayed. The services keep returning
286
+ `Observable`s.
287
+ - `markForCheck()` only for a state that can't be a signal (e.g. the plain fields that the pages of the projects set
288
+ when their form is loaded: `AbstractPageComponent` marks the page then).
289
+ - Act on the rendered DOM (focus, scroll, measure) with `afterNextRender(..., { injector })`, never with
290
+ `setTimeout()` or `NgZone`.
291
+ - `effect()` as a last resort, with `untracked()` for what isn't a trigger. Never use it to copy a signal into another
292
+ one.
293
+ - Track the short asynchronous work the tests must wait for (e.g. a debounce) with `PendingTasks`.
294
+ - Before fixing existing code, read the history of the mechanism you touch (`git log -S`, `git blame`): many
295
+ `setTimeout()`, copies, `ngOnChanges()` and `NgZone` are workarounds from the zone.js era whose reason is gone. If
296
+ the code wouldn't be written this way today, rewrite it rather than patching around it.
297
+ - A public field of a component that becomes a signal changes how the projects read it: list it in the CHANGELOG
298
+ (_read-only_ for a `computed()`), with 🚨 when an input or an output changes.
299
+
300
+ ## Unit testing
301
+
302
+ The unit tests run with [Vitest](https://vitest.dev/) through the `@angular/build:unit-test` builder of the
303
+ Angular CLI, in the browser mode of Vitest: [Playwright](https://playwright.dev/) drives the headless Chromium
304
+ downloaded by Puppeteer (another browser can be used by setting the `CHROME_BIN` environment variable).
305
+ Neither the library nor the Dev Tool uses zone.js: the tests are **zoneless** too.
306
+
307
+ | Command | Tests |
308
+ | ------------------------- | ---------------------------------------------------------------- |
309
+ | `npm run test:lib` | library (`projects/prestations-ng/src/**/*.spec.ts`) |
310
+ | `npm run test:devtool` | Dev Tool (`src/**/*.spec.ts`) |
311
+ | `npm run test:schematics` | schematics, in Node.js (`projects/prestations-ng/schematics`) |
312
+ | `npm run test:eslint` | ESLint plugin, in Node.js (`projects/prestations-ng/src/eslint`) |
313
+ | `npm test` | builds the library, then runs all of the above |
314
+
315
+ - `ng test prestations-ng` without `--no-watch` runs the tests in watch mode.
316
+ - Only some specs: `ng test prestations-ng --no-watch --include=foehn-table` (folder or file, relative to
317
+ `projects/prestations-ng/src`), and `--filter="FoehnTableComponent"` to filter by test name.
318
+ - The configuration is in `angular.json` (`test` targets), in the `vitest-base.config.mts` file of each project and in
319
+ the `vitest-base.config.mts` file they share, at the root.
320
+ The coverage of the library is written in `projects/prestations-ng/coverage` (read by SonarQube).
321
+ - The configuration files of the tools (`.mjs`/`.mts`, e.g. `eslint.config.mjs`, `vitest-base.config.*`) are listed in
322
+ `tsconfig.config.json`, referenced by `tsconfig.json`: the IDE checks them with the options of the project instead of
323
+ its default ones. Add any new configuration file to its `files`.
324
+
325
+ ### Writing zoneless tests
326
+
327
+ - Use `vi` (`vi.spyOn()`, `vi.fn()`...), the Jest-like API of Vitest. Unlike `spyOn()` in Jasmine,
328
+ `vi.spyOn()` calls the original method: add `.mockReturnValue(...)` or `.mockImplementation(...)` to stub it.
329
+ The spies are restored before each test.
330
+ - `fakeAsync()`, `tick()`, `flush()` and `waitForAsync()` require zone.js: use `async` tests with
331
+ `await fixture.whenStable()`, or `vi.useFakeTimers()` and `await vi.advanceTimersByTimeAsync(ms)`.
332
+ - `fixture.whenStable()` waits for the change detection and the Angular pending tasks (e.g. the debounced
333
+ `userInput` of the inputs), not for the timers, nor for the HTTP requests of a spec: `provideHttpClientTesting()`
334
+ keeps them pending until the test answers them with `HttpTestingController`. Answer them first, then
335
+ `await fixture.whenStable()`.
336
+ - A loading resource (`httpResource()`, `rxResource()`) is a pending task: start its request with `TestBed.tick()`,
337
+ answer it, then `await fixture.whenStable()`.
338
+ - Without zone.js, `fixture.detectChanges()` only refreshes the views that have been notified. A test (or a test
339
+ host component) changing the state of a component must use signals, as the components do.
340
+
221
341
  ## E2E testing
222
342
 
223
343
  `Protractor` is no longer included in new Angular projects as of Angular 12.
package/ESLINT_PLUGIN.md CHANGED
@@ -48,12 +48,12 @@ from the config. Inline templates written in a `@Component` are covered too, thr
48
48
 
49
49
  ## The configs
50
50
 
51
- | Config | Target | Contents |
52
- | ----------------------------- | ----------- | -------------------------------------------------------------- |
53
- | `configs.tsRecommended` | `**/*.ts` | the baselines, the house style, and `tsRules` |
54
- | `configs.templateRecommended` | `**/*.html` | the baselines, the house style, and `templateRules` |
55
- | `configs.tsRules` | `**/*.ts` | `no-direct-signal-mutation` |
56
- | `configs.templateRules` | `**/*.html` | `no-direct-signal-mutation`, `no-uninvoked-signal-in-template` |
51
+ | Config | Target | Contents |
52
+ | ----------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
53
+ | `configs.tsRecommended` | `**/*.ts` | the baselines, the house style, and `tsRules` |
54
+ | `configs.templateRecommended` | `**/*.html` | the baselines, the house style, and `templateRules` |
55
+ | `configs.tsRules` | `**/*.ts` | `no-direct-signal-mutation` |
56
+ | `configs.templateRules` | `**/*.html` | `no-direct-signal-mutation`, `no-uninvoked-signal-in-template`, `require-model-change`, `no-item-track-in-form-list`, `require-track-index` |
57
57
 
58
58
  The `*Recommended` presets are what a project normally extends. On top of the rules written
59
59
  here they bring:
@@ -61,8 +61,12 @@ here they bring:
61
61
  - the baselines — `eslint.configs.recommended`, `typescript-eslint` recommended and
62
62
  stylistic, `angular-eslint` recommended, and for templates its accessibility set;
63
63
  - the house style — naming and selector conventions, import ordering
64
- (`simple-import-sort`, `import-x`), rxjs conventions, and the signal rules of
65
- `angular-eslint` (`no-uncalled-signals`, `prefer-signals`, `prefer-signal-model`).
64
+ (`simple-import-sort`, `import-x`), rxjs conventions, the signal rules of
65
+ `angular-eslint` (`no-uncalled-signals`, `prefer-signals`, `prefer-signal-model`),
66
+ `@typescript-eslint/restrict-template-expressions` (see
67
+ [The TypeScript counterpart](#the-typescript-counterpart)), and
68
+ `@typescript-eslint/no-useless-constructor` (see
69
+ [A constructor only calling `super()`](#a-constructor-only-calling-super)).
66
70
 
67
71
  Use `tsRules` / `templateRules` instead when a project supplies its own style and only wants
68
72
  the rules of this library. They register the plugin and nothing else, so you keep control of
@@ -105,12 +109,13 @@ in a two-way binding.
105
109
 
106
110
  ```ts
107
111
  // ✗ mutates the object inside the signal, no notification
108
- this.model().property = value;
109
- this.model().items.splice(index, 1);
112
+ this.settings().property = value;
113
+ this.settings().items.splice(index, 1);
110
114
 
111
115
  // ✓
112
- this.model.update((current) => ({ ...current, property: value }));
113
- this.model.update((current) => ({
116
+ this.settings.update((current) => ({ ...current, property: value }));
117
+ ObjectPathHelper.patchSignal(this.settings, ['deep', 'property'], value); // at any depth
118
+ this.settings.update((current) => ({
114
119
  ...current,
115
120
  items: current.items.filter((_, i) => i !== index),
116
121
  }));
@@ -118,16 +123,23 @@ this.model.update((current) => ({
118
123
 
119
124
  ```html
120
125
  <!-- ✗ -->
121
- <button (click)="model().property = value">…</button>
122
- <button (click)="model().items.splice(index, 1)">…</button>
123
- <input [(ngModel)]="model().property" />
126
+ <button (click)="settings().property = value">…</button>
127
+ <button (click)="settings().items.splice(index, 1)">…</button>
128
+ <input [(ngModel)]="settings().property" />
124
129
 
125
130
  <!-- ✓ -->
126
- <button (click)="model.update((v) => ({ ...v, property: value }))">…</button>
131
+ <button (click)="settings.update((v) => ({ ...v, property: value }))">…</button>
127
132
  ```
128
133
 
134
+ > 💡 The `model` of a component extending `FoehnInputComponent` is the exception: write it
135
+ > with `updateNgModel()` and a new value, or a value at a path with
136
+ > `this.patchNgModel(['deep', 'property'], value)`, never with `set()`, `update()` or
137
+ > `patchSignal()`: `updateNgModel()` also updates `model_`, and leaves the model of a disabled
138
+ > component alone.
139
+
129
140
  All the assignment operators accepted by the Angular expression parser are covered: `=`,
130
- `+=`, `-=`, `*=`, `/=`, `%=`, `**=`, `&&=`, `||=`, `??=`.
141
+ `+=`, `-=`, `*=`, `/=`, `%=`, `**=`, `&&=`, `||=`, `??=`, and in TypeScript the increments
142
+ `++` and `--` (since 19.2.0-beta.29).
131
143
 
132
144
  The in-place mutators covered are those of `Array` — `push`, `pop`, `shift`, `unshift`,
133
145
  `splice`, `sort`, `reverse`, `fill`, `copyWithin` — and of `Map` / `Set` — `set`, `add`,
@@ -139,10 +151,14 @@ Two other ways of writing into the value are covered, in TypeScript — the Angu
139
151
  parser accepts neither:
140
152
 
141
153
  ```ts
142
- delete this.model().users[0];
143
- Object.assign(this.model(), { property: value });
154
+ delete this.settings().users[0];
155
+ Object.assign(this.settings(), { property: value });
144
156
  ```
145
157
 
158
+ The TypeScript wrappers which keep the value are seen through: `this.form()!.name = value`
159
+ and `(this.settings() as Settings).name = value` are reported as well, as are, in a template,
160
+ `[(ngModel)]="form()!.name"` and `(form()).name = value`.
161
+
146
162
  #### Names bound to the value
147
163
 
148
164
  A mutation is rarely written on the signal read itself. The rule follows the value through
@@ -150,22 +166,27 @@ the bindings it can resolve exactly, and only those:
150
166
 
151
167
  ```ts
152
168
  // ✗ a variable written once
153
- const users = this.model().users;
169
+ const users = this.settings().users;
154
170
  users.push(user);
155
171
 
156
172
  // ✗ the element parameter of an iteration callback
157
- this.model().users.forEach((user) => (user.done = true));
173
+ this.settings().users.forEach((user) => (user.done = true));
158
174
  ```
159
175
 
160
176
  ```angular-html
161
177
  <!-- ✗ a @for item, bound only inside its own block -->
162
- @for (user of model().users; track user.id) {
178
+ @for (user of settings().users; track user.id) {
163
179
  <input [(ngModel)]="user.done" />
164
180
  <button (click)="user.tags.push(tag)">…</button>
165
181
  }
166
182
 
183
+ <!-- ✗ the alias of an @if, bound only inside its own branch -->
184
+ @if (form(); as form) {
185
+ <foehn-input-text name="name" [(model)]="form.name" />
186
+ }
187
+
167
188
  <!-- ✗ a @let -->
168
- @let users = model().users;
189
+ @let users = settings().users;
169
190
  <button (click)="users.push(user)">…</button>
170
191
  ```
171
192
 
@@ -175,16 +196,67 @@ introduces the name — nothing is inferred from a naming convention. A variable
175
196
  for `reduce`, whose first parameter is the accumulator and not an element.
176
197
 
177
198
  **What it cannot follow** is a value crossing a function boundary — handed to a method,
178
- 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):
179
201
 
180
202
  ```ts
181
203
  // not reported: the rule cannot know what `sortInto` does
182
- this.sortInto(this.model().users);
204
+ this.sortInto(this.settings().users);
183
205
  ```
184
206
 
185
207
  That needs interprocedural analysis, which ESLint does not provide; a full type checker
186
208
  would be required. It is the one remaining gap in detection.
187
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
+
188
260
  #### Only real signals are inspected
189
261
 
190
262
  The rule does not guess from the shape of a call. It reads the declaring class — the linted
@@ -211,11 +283,11 @@ the normal way to use one. `.required` variants included.
211
283
 
212
284
  Anything that is not a declared signal is left alone as well:
213
285
 
214
- | Expression | Why |
215
- | ------------------------------------ | ------------------------------------------------------------ |
216
- | `this.getConfig().items.push(item)` | `getConfig()` is a plain method, not a signal |
217
- | `map.get(key).files.push(file)` | the call takes arguments, so it is not a signal read |
218
- | `component.model().items.push(item)` | reached through a foreign receiver, not the component itself |
286
+ | Expression | Why |
287
+ | --------------------------------------- | ------------------------------------------------------------ |
288
+ | `this.getConfig().items.push(item)` | `getConfig()` is a plain method, not a signal |
289
+ | `map.get(key).files.push(file)` | the call takes arguments, so it is not a signal read |
290
+ | `component.settings().items.push(item)` | reached through a foreign receiver, not the component itself |
219
291
 
220
292
  Because the rule knows a real signal from an ordinary method, `set` / `add` / `delete` are
221
293
  safe to report: `byId().set(k, v)` mutates the `Map` inside the signal, while `byId.set(m)`
@@ -295,6 +367,139 @@ found without declaring anything.
295
367
  | `[(value)]="mySignal"` | a writable signal is two-way bound **without** parentheses, Angular calls `.set()` itself |
296
368
  | `#ref`, `@for` items, `@if … as`, `@let`, `let-x`, `$index`… | template-local names shadow the class members |
297
369
 
370
+ ### `require-model-change`
371
+
372
+ Reports a `foehn-*` component given a field of the form of the page with a one-way `[model]`
373
+ and no `(modelChange)`. The component changes its own model only: what the user enters never
374
+ reaches the form, and is lost when the form is saved.
375
+
376
+ Applies to **templates only**.
377
+
378
+ ```html
379
+ <!-- ✗ the input of the user is lost -->
380
+ <foehn-input-text [model]="form.firstName" />
381
+
382
+ <!-- ✓ -->
383
+ <foehn-input-text
384
+ [model]="form.firstName"
385
+ (modelChange)="patchForm(['firstName'], $event)"
386
+ />
387
+ ```
388
+
389
+ Only the models read from the form are checked: `form()`, `form.firstName`, and the names
390
+ bound to it by `@if (form(); as form)`, `@let form = this.form()` or
391
+ `@for (child of form.children; …)`. A one-way `[model]` is legitimate elsewhere (a table
392
+ displaying a list, a menu...). `[(model)]` declares both bindings and is never reported.
393
+
394
+ Not reported either, as the input of the user can't be lost:
395
+
396
+ - a component always disabled, `disabled="true"` or `[disabled]="true"` (a disabled component
397
+ doesn't write its model), unless it is given `updateModelWhenDisabled`;
398
+ - `foehn-input-hidden` and `foehn-table`, which never write their model;
399
+ - a component listening to `(userInput)`, whose handler writes the form.
400
+
401
+ A `[disabled]` depending on a condition is reported: once the component is enabled, the input of
402
+ the user would be lost. A bare `disabled` is reported too: it gives `''`, which doesn't disable
403
+ the component.
404
+
405
+ ```html
406
+ <!-- ✓ displayed only -->
407
+ <foehn-input-text [model]="form.reference" [disabled]="true" />
408
+ ```
409
+
410
+ ### `no-item-track-in-form-list`
411
+
412
+ Reports a `@for` over a list of the form whose rows edit their item, tracked by the item
413
+ itself (`track child`, `track $any(child)`). Writing a field of an item with `patchForm()`
414
+ or `patchItem()` replaces the item with a copy: its row is destroyed and created again at
415
+ every input, and the field being edited loses the focus.
416
+
417
+ Applies to **templates only**.
418
+
419
+ ```html
420
+ <!-- ✗ the field loses the focus at every input -->
421
+ @for (child of form.children; track child) {
422
+ <foehn-input-text
423
+ [model]="child.firstName"
424
+ (modelChange)="patchForm(['children', $index, 'firstName'], $event)"
425
+ />
426
+ }
427
+
428
+ <!-- ✓ -->
429
+ @for (child of form.children; track $index) { … }
430
+ ```
431
+
432
+ The list held by the `model` of a component is reported alike: a component extending
433
+ `FoehnInputComponent` writes a new list in its model, its items replaced (see the list of
434
+ vehicles in [GOOD_PRACTICES.md](GOOD_PRACTICES.md)). Two items equal by value, e.g. two
435
+ empty strings, even collide.
436
+
437
+ ```html
438
+ <!-- ✗ in the template of a component extending FoehnInputComponent<string[]> -->
439
+ @for (text of model(); track text; let i = $index) {
440
+ <foehn-input-textarea
441
+ [model]="model()[i]"
442
+ (modelChange)="updateItem(i, $event)"
443
+ />
444
+ }
445
+ ```
446
+
447
+ A row edits its item when one of its elements has a `model` read from it
448
+ (`[model]="child.firstName"`, `[(model)]="child"`), or read from the list at the index of
449
+ the row (`[model]="model()[i]"`, `let i = $index`). A list only displayed, or read neither
450
+ from the form nor from the model, is left alone. The rule suggests `track $index`: the rows
451
+ of a list of the form name their fields with their index, which an identifier of the item
452
+ would break (see [`require-track-index`](#require-track-index), which reports these lists too:
453
+ the same `track` gets both messages, fixed by the same suggestion).
454
+
455
+ > 💡 The control flow migration of Angular turns a `*ngFor` without `trackBy` into
456
+ > `track <item>`: after it, check the lists of the form.
457
+
458
+ ### `require-track-index`
459
+
460
+ Reports a `@for` whose rows name their fields with the index of the row
461
+ (`[name]="'children[' + $index + '].firstName'"`, `name="child{{ i }}"`), or the errors of the
462
+ row (the `errorPrefix` of `foehn-error-pill`), tracked by anything else than `$index`. The
463
+ names of the fields follow the paths of the errors of GESDEM (`children[1].firstName`). Tracked
464
+ by an identifier of the item, a row whose item moves (an item removed before it, an item
465
+ inserted, the list sorted) is kept with its fields renamed: `foehn-form` keeps them registered
466
+ under their former names, so the row taking one of these names shares their `FormControl`, and
467
+ the errors, read by name when they are emitted, stay those of the former position. Tracked by
468
+ `$index`, a row never changes its names: only its item changes.
469
+
470
+ Applies to **templates only**. Suggests `track $index`.
471
+
472
+ ```html
473
+ <!-- ✗ an item removed before a child: the values and the errors of the rows get mixed up -->
474
+ @for (child of form.children; track child.id) {
475
+ <foehn-input-text
476
+ [name]="'children[' + $index + '].firstName'"
477
+ [model]="child.firstName"
478
+ (modelChange)="patchForm(['children', $index, 'firstName'], $event)"
479
+ />
480
+ }
481
+
482
+ <!-- ✓ -->
483
+ @for (child of form.children; track $index) {
484
+ <foehn-input-text
485
+ [name]="'children[' + $index + '].firstName'"
486
+ [model]="child.firstName"
487
+ (modelChange)="patchForm(['children', $index, 'firstName'], $event)"
488
+ />
489
+ }
490
+ ```
491
+
492
+ The index is `$index` or an alias of it (`let i = $index`), of the innermost `@for`
493
+ declaring the name: a name built with the index of an enclosing `@for`
494
+ (`'groups[' + g + '].children[' + $index + ']'`, `let g = $index`) reports that one too.
495
+ A name that doesn't depend on the position of the row (`'child-' + child.id`, a static
496
+ `name`) is left alone.
497
+
498
+ Limitations: a name built in the class of the component from the index (a method receiving
499
+ the item and looking up its index) isn't seen. The rule doesn't tell a list that never moves
500
+ (e.g. replaced as a whole) from one that does: tracking such a list by `$index` changes
501
+ nothing, the rows keep their names.
502
+
298
503
  ## The TypeScript counterpart
299
504
 
300
505
  `@angular-eslint/no-uncalled-signals` covers the same class of bug **in TypeScript**, using
@@ -310,3 +515,30 @@ are complementary, not redundant.
310
515
 
311
516
  It only reports signals used in logic positions (`if`, `!x`, `&&`, `===`, `.length`…), not a
312
517
  bare `const x = mySignal`.
518
+
519
+ Nor a template literal: `` `api/${this.reference}/pdf-sections` `` compiles, and gives the
520
+ signal itself as text (`[Signal: …]`, or the source of a function in production) instead of
521
+ its value. `configs.tsRecommended` also enables
522
+ `@typescript-eslint/restrict-template-expressions`, which only lets strings, numbers,
523
+ booleans, `null`, `undefined`, `any` and `RegExp` into a template literal: a signal not
524
+ called is reported, as is an object turned into text by its `toString()`. With
525
+ `configs.tsRules` you enable it yourself (it requires type information too):
526
+
527
+ ```ts
528
+ '@typescript-eslint/restrict-template-expressions': 'error',
529
+ ```
530
+
531
+ ## A constructor only calling `super()`
532
+
533
+ `configs.tsRecommended` enables `@typescript-eslint/no-useless-constructor`: a constructor
534
+ which only passes its parameters to `super()` is reported, typically the
535
+ `constructor() { super(); }` left once the services are injected with `inject()`. Remove it:
536
+ the class inherits the constructor of its parent. A `protected` or `private` constructor is
537
+ not reported, nor one giving other arguments to its parent (`super(Type.SUBSIDY)`).
538
+
539
+ When the removal gives `Cannot assign a 'protected' constructor type to a 'public'
540
+ constructor type` (TS2322 on the `component` of a route, TS2345 on
541
+ `TestBed.createComponent()`), the parent declares a `protected constructor()`, which the
542
+ class now inherits. Remove that one too when the parent is `abstract`: it already can't be
543
+ instantiated. Otherwise keep the constructor of the class, with an `eslint-disable-next-line`
544
+ saying why.