@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.
- package/AI_GUIDELINES.md +152 -0
- package/ANGULAR_SIGNALS.md +6 -2
- package/CHANGELOG.md +476 -0
- package/CONTRIBUTING.md +128 -8
- package/ESLINT_PLUGIN.md +262 -30
- package/GOOD_PRACTICES.md +983 -388
- package/INTRODUCTION_ANGULAR_SIGNALS.md +227 -155
- package/README.md +22 -12
- package/UPGRADING_V18.md +5 -5
- package/UPGRADING_V19.md +636 -19
- package/eslint/configs/spec-ts-recommended.mjs +34 -0
- package/eslint/configs/template-recommended.mjs +2 -0
- package/eslint/configs/template-rules.mjs +14 -2
- package/eslint/configs/ts-recommended.mjs +11 -0
- package/eslint/configs/ts-rules.mjs +6 -2
- package/eslint/form-reads.mjs +63 -0
- package/eslint/index.mjs +17 -0
- package/eslint/rules/index.mjs +6 -0
- package/eslint/rules/no-direct-signal-mutation.mjs +162 -41
- package/eslint/rules/no-item-track-in-form-list.mjs +173 -0
- package/eslint/rules/no-uninvoked-signal-in-template.mjs +8 -3
- package/eslint/rules/require-model-change.mjs +89 -0
- package/eslint/rules/require-track-index.mjs +162 -0
- package/eslint/signal-names.mjs +127 -21
- package/eslint/template-ast.mjs +12 -2
- package/fesm2022/dsivd-prestations-ng.mjs +2889 -2061
- package/fesm2022/dsivd-prestations-ng.mjs.map +1 -1
- package/package.json +1 -2
- package/schematics/migration-collection.json +5 -0
- package/schematics/ng-add/index.js +2 -4
- package/schematics/ng-update/migrations/update-13_2_0/index.js +7 -2
- package/schematics/ng-update/migrations/update-19_2_0/index.js +52 -0
- package/schematics/utility/add-allowed-common-js-dependencies.js +39 -29
- package/schematics/utility/form-signal/class-migration.js +795 -0
- package/schematics/utility/form-signal/edits.js +34 -0
- package/schematics/utility/form-signal/form-members.js +318 -0
- package/schematics/utility/form-signal/form-signal-migration.js +134 -0
- package/schematics/utility/form-signal/page-classes.js +139 -0
- package/schematics/utility/form-signal/template-migration.js +775 -0
- package/schematics/utility/never-connected-migration.js +87 -0
- package/schematics/utility/remove-emit-decorator-metadata.js +8 -9
- package/schematics/utility/typescript-files.js +95 -0
- package/src/eslint/configs/__tests__/configs.test.mjs +61 -2
- package/src/eslint/configs/spec-ts-recommended.mjs +34 -0
- package/src/eslint/configs/template-recommended.mjs +2 -0
- package/src/eslint/configs/template-rules.mjs +14 -2
- package/src/eslint/configs/ts-recommended.mjs +11 -0
- package/src/eslint/configs/ts-rules.mjs +6 -2
- package/src/eslint/form-reads.mjs +63 -0
- package/src/eslint/index.mjs +17 -0
- package/src/eslint/rules/__tests__/no-direct-signal-mutation.test.mjs +200 -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/__tests__/require-track-index.test.mjs +106 -0
- package/src/eslint/rules/index.mjs +6 -0
- package/src/eslint/rules/no-direct-signal-mutation.mjs +162 -41
- package/src/eslint/rules/no-item-track-in-form-list.mjs +173 -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/rules/require-track-index.mjs +162 -0
- package/src/eslint/signal-names.mjs +127 -21
- package/src/eslint/template-ast.mjs +12 -2
- package/types/dsivd-prestations-ng.d.ts +719 -243
- 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
|
|
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
|
|
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
|
-
-
|
|
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,
|
|
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.
|
|
109
|
-
this.
|
|
112
|
+
this.settings().property = value;
|
|
113
|
+
this.settings().items.splice(index, 1);
|
|
110
114
|
|
|
111
115
|
// ✓
|
|
112
|
-
this.
|
|
113
|
-
this.
|
|
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)="
|
|
122
|
-
<button (click)="
|
|
123
|
-
<input [(ngModel)]="
|
|
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)="
|
|
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.
|
|
143
|
-
Object.assign(this.
|
|
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.
|
|
169
|
+
const users = this.settings().users;
|
|
154
170
|
users.push(user);
|
|
155
171
|
|
|
156
172
|
// ✗ the element parameter of an iteration callback
|
|
157
|
-
this.
|
|
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
|
|
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 =
|
|
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.
|
|
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
|
|
215
|
-
|
|
|
216
|
-
| `this.getConfig().items.push(item)`
|
|
217
|
-
| `map.get(key).files.push(file)`
|
|
218
|
-
| `component.
|
|
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.
|