@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/UPGRADING_V19.md
CHANGED
|
@@ -97,16 +97,9 @@ if you use oracle, you should replace `ojdbc10` by `ojdbc17` in your `pom.xml` a
|
|
|
97
97
|
With Spring Boot 4, Jackson 3 is now used instead of Jackson 2, so we need to replace the previous Jackson 2 classes.
|
|
98
98
|
Replace `com.fasterxml.jackson.databind.ObjectMapper` with `tools.jackson.databind.json.JsonMapper`.
|
|
99
99
|
|
|
100
|
-
###
|
|
101
|
-
|
|
102
|
-
- `ch.vd.cyberadminbe.jms` has been moved to `ch.vd.cyber.backofficebe.jms`
|
|
103
|
-
- `ch.vd.cyberadminbe.security` has been moved to `ch.vd.cyber.backofficebe.security`
|
|
104
|
-
- `ch.vd.cyberadminbe.editique` has been moved to `ch.vd.cyber.backofficebe.editique`
|
|
105
|
-
- `cyberadminbe.config.CyberAdminBeEsbHttpConfig` has been renamed to `backofficebe.config.BoCommonEsbHttpConfig`
|
|
100
|
+
### Brave Tracer
|
|
106
101
|
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
If you are using Brave Tracer (search `brave.Tracer` in the code, usually in backoffices), you need to replace it with
|
|
102
|
+
If you are using Brave Tracer (search `brave.Tracer` in the code), you need to replace it with
|
|
110
103
|
OpenTelemetry by adding the following dependencies (already included by `ch.vd.cyber:starter-bo-jdbc-jms` and `ch.vd.cyber:starter-prestation`):
|
|
111
104
|
|
|
112
105
|
```xml
|
|
@@ -123,6 +116,13 @@ OpenTelemetry by adding the following dependencies (already included by `ch.vd.c
|
|
|
123
116
|
|
|
124
117
|
And replace `brave.Tracer` imports by `io.micrometer.tracing.Tracer`;
|
|
125
118
|
|
|
119
|
+
### BO : Package renaming
|
|
120
|
+
|
|
121
|
+
- `ch.vd.cyberadminbe.jms` has been moved to `ch.vd.cyber.backofficebe.jms`
|
|
122
|
+
- `ch.vd.cyberadminbe.security` has been moved to `ch.vd.cyber.backofficebe.security`
|
|
123
|
+
- `ch.vd.cyberadminbe.editique` has been moved to `ch.vd.cyber.backofficebe.editique`
|
|
124
|
+
- `cyberadminbe.config.CyberAdminBeEsbHttpConfig` has been renamed to `backofficebe.config.BoCommonEsbHttpConfig`
|
|
125
|
+
|
|
126
126
|
#### BO : EsbMessageListenerWithSleuthIntegration
|
|
127
127
|
|
|
128
128
|
This base class has been moved from `ch.vd.cyber.sdk:cyberadmin-be` to `ch.vd.cyber.sdk:backoffice-be`
|
|
@@ -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`
|
|
@@ -308,8 +312,11 @@ ng update @angular/core@20 @angular/cli@20
|
|
|
308
312
|
- accept **"router-current-navigation"** by hitting "Space" key
|
|
309
313
|
- hit "Enter" key
|
|
310
314
|
|
|
311
|
-
🚨 **IMPORTANT: Search for every `@for` in your project and check that `track` statement is present
|
|
312
|
-
|
|
315
|
+
🚨 **IMPORTANT: Search for every `@for` in your project and check that `track` statement is present. Track by
|
|
316
|
+
`$index` the rows naming their fields with the index (`[name]="'children[' + $index + '].firstName'"`, every list of
|
|
317
|
+
the form): tracked by an identifier, a row whose item moves keeps the names of its former position and gets the
|
|
318
|
+
values and the errors of another row (`require-track-index`, since 19.2.0). Since 19.2.0, never track by object a list
|
|
319
|
+
of the form whose rows edit their item (see "The form of your pages is a signal").**
|
|
313
320
|
|
|
314
321
|
💡 **NB: When using `@angular/cdk` in your project**
|
|
315
322
|
|
|
@@ -366,6 +373,10 @@ ng update @dsivd/prestations-ng@latest
|
|
|
366
373
|
- accept **"router-current-navigation"** by hitting "Space" key
|
|
367
374
|
- hit "Enter" key
|
|
368
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
|
+
|
|
369
380
|
```bash
|
|
370
381
|
ng update @angular/cli@21
|
|
371
382
|
```
|
|
@@ -392,6 +403,55 @@ ng update ngx-matomo-client@9
|
|
|
392
403
|
|
|
393
404
|
💡 **NB: Upgrade all other libraries needed by your project (such as: primeng, lodash, ...) to their latest version compatible with angular 21**
|
|
394
405
|
|
|
406
|
+
### Instructions for your AI assistant (since 19.2.0)
|
|
407
|
+
|
|
408
|
+
The library ships [AI_GUIDELINES.md](AI_GUIDELINES.md): the rules an AI assistant (Claude Code, GitHub Copilot...)
|
|
409
|
+
follows in a project using it, for the version installed. Give them to your assistant now, so that it follows them
|
|
410
|
+
for the rest of this migration. The versions before 19.2.0 (e.g. 19.1.x) don't have the file: skip this step, and come
|
|
411
|
+
back to it once you upgrade to 19.2.0.
|
|
412
|
+
|
|
413
|
+
At the root of the project holding the front (not in the `front` folder):
|
|
414
|
+
|
|
415
|
+
1. For Claude Code, create the `.claude` folder and its `CLAUDE.md` file if they don't exist, and add the import of
|
|
416
|
+
the file, its path being relative to `CLAUDE.md`:
|
|
417
|
+
|
|
418
|
+
```text
|
|
419
|
+
@../front/node_modules/@dsivd/prestations-ng/AI_GUIDELINES.md
|
|
420
|
+
```
|
|
421
|
+
|
|
422
|
+
2. For the other assistants (GitHub Copilot, Codex, Cursor...), create the `AGENTS.md` file if it doesn't exist, and
|
|
423
|
+
add this sentence to it: they read `AGENTS.md`, but can't import a file.
|
|
424
|
+
|
|
425
|
+
```text
|
|
426
|
+
Before changing the front, read and follow `front/node_modules/@dsivd/prestations-ng/AI_GUIDELINES.md`:
|
|
427
|
+
the rules of the installed version of `@dsivd/prestations-ng`.
|
|
428
|
+
```
|
|
429
|
+
|
|
430
|
+
Then:
|
|
431
|
+
|
|
432
|
+
- The project is your repository or, in a repository holding several projects (e.g. `my-project-fo/front` and
|
|
433
|
+
`my-project-bo/front`), the folder of each one: each project gets its own `.claude/CLAUDE.md` and `AGENTS.md`, with
|
|
434
|
+
the rules of its version of `prestations-ng`. Claude Code loads `.claude/CLAUDE.md` when it's started in the
|
|
435
|
+
project or one of its folders (e.g. `front`) or, started at the root of the repository, as soon as it reads a file
|
|
436
|
+
of the project.
|
|
437
|
+
- If the project already has a `CLAUDE.md` at its root, add the import there rather than creating a second file:
|
|
438
|
+
`@front/node_modules/@dsivd/prestations-ng/AI_GUIDELINES.md`.
|
|
439
|
+
- A project with several fronts, or an Angular library shared by the fronts of the repository: both files in the
|
|
440
|
+
folder of each one, next to its `node_modules`, with `@../node_modules/@dsivd/prestations-ng/AI_GUIDELINES.md` and
|
|
441
|
+
`node_modules/@dsivd/prestations-ng/AI_GUIDELINES.md`.
|
|
442
|
+
- Keep the import in `.claude/CLAUDE.md` even with `AGENTS.md`: Claude Code reads `AGENTS.md` only in a folder
|
|
443
|
+
without `CLAUDE.md`, and not in every mode.
|
|
444
|
+
- An import loads nothing until the dependencies of its front are installed (`npm ci` after a clone): until then,
|
|
445
|
+
your assistant doesn't have the rules.
|
|
446
|
+
- Commit `.claude/CLAUDE.md` and `AGENTS.md`, so that the whole team gets the rules, but not the permissions each
|
|
447
|
+
developer grants to Claude Code for the project, which it keeps in `.claude/settings.local.json`: add
|
|
448
|
+
`**/.claude/settings.local.json` to the `.gitignore` of your repository.
|
|
449
|
+
- Refer to the file rather than copying it: the rules follow the version installed at each upgrade, those of
|
|
450
|
+
Renovate included, without changing your files.
|
|
451
|
+
|
|
452
|
+
💡 **NB: The rules describe the code once migrated. Your assistant follows the steps of this guide in order, without
|
|
453
|
+
anticipating the next ones: `AI_GUIDELINES.md` tells it so.**
|
|
454
|
+
|
|
395
455
|
### Quick fix
|
|
396
456
|
|
|
397
457
|
- In all custom components extending `FoehnInputComponent`, in `providers` providing `FoehnInputComponent` remove `multi: true,`.
|
|
@@ -1064,8 +1124,13 @@ npm install --save-dev eslint-plugin-simple-import-sort@13
|
|
|
1064
1124
|
npm install --save-dev eslint-config-prettier@10
|
|
1065
1125
|
npm install --save-dev eslint-plugin-import-x@4
|
|
1066
1126
|
npm install --save-dev prettier
|
|
1127
|
+
# only if your project has Vitest specs (see "Migrate to vitest")
|
|
1128
|
+
npm install --save-dev --save-exact @vitest/eslint-plugin@1.6.27
|
|
1067
1129
|
```
|
|
1068
1130
|
|
|
1131
|
+
`@vitest/eslint-plugin` 1.6.28 and later need TypeScript 6: with the TypeScript 5.9 of Angular 21, `npm install` fails
|
|
1132
|
+
with `ERESOLVE`. Keep 1.6.27 until your project moves to TypeScript 6.
|
|
1133
|
+
|
|
1069
1134
|
In your `front` folder, add a `.prettierrc` file with the following content:
|
|
1070
1135
|
|
|
1071
1136
|
```json
|
|
@@ -1140,6 +1205,12 @@ export default tseslint.config(
|
|
|
1140
1205
|
extends: [...prestationsNg.configs.templateRecommended],
|
|
1141
1206
|
},
|
|
1142
1207
|
|
|
1208
|
+
// ─── Vitest specs (only if your project has Vitest specs) ─────────────────
|
|
1209
|
+
{
|
|
1210
|
+
files: ['**/*.spec.ts'],
|
|
1211
|
+
extends: [...prestationsNg.configs.specTsRecommended],
|
|
1212
|
+
},
|
|
1213
|
+
|
|
1143
1214
|
// ─── Prettier (must be last — disables formatting rules) ───────────────────
|
|
1144
1215
|
prettier,
|
|
1145
1216
|
);
|
|
@@ -1150,6 +1221,11 @@ everything: the `eslint`, `typescript-eslint` and `angular-eslint` baselines, th
|
|
|
1150
1221
|
accessibility set, the naming and import conventions, and the rules written by the library
|
|
1151
1222
|
itself. You declare no `plugins` and list no rule.
|
|
1152
1223
|
|
|
1224
|
+
`specTsRecommended` is the `recommended` config of `@vitest/eslint-plugin`, which also counts the assertions
|
|
1225
|
+
made by the `HttpTestingController` (`expectOne`, `expectNone`, `verify`) and by helpers named `expect*`,
|
|
1226
|
+
`assert*` or `test*`. The `**/*.spec.ts` pattern does not reach the Cypress `*.spec.cy.ts` files. It needs
|
|
1227
|
+
`@vitest/eslint-plugin` only when you use it: the other configs work without it.
|
|
1228
|
+
|
|
1153
1229
|
The packages installed above are still required — the library's config imports them from your
|
|
1154
1230
|
`node_modules` rather than shipping its own copies. For the same reason, do **not** spread
|
|
1155
1231
|
`angular.configs.tsRecommended` or `angular.configs.templateRecommended` yourself: they are
|
|
@@ -1158,10 +1234,10 @@ fail outright.
|
|
|
1158
1234
|
|
|
1159
1235
|
#### prestations-ng ESLint rules
|
|
1160
1236
|
|
|
1161
|
-
The library ships **shareable custom configs** that are auto-updatable with the library version.
|
|
1162
|
-
rules are enabled today — `no-direct-signal-mutation
|
|
1163
|
-
|
|
1164
|
-
configs for a project that supplies its own style.
|
|
1237
|
+
The library ships **shareable custom configs** that are auto-updatable with the library version. Four
|
|
1238
|
+
rules are enabled today — `no-direct-signal-mutation`, `no-uninvoked-signal-in-template`, and, since 19.2.0,
|
|
1239
|
+
`require-model-change` and `no-item-track-in-form-list` — all documented in [the plugin guide](ESLINT_PLUGIN.md),
|
|
1240
|
+
alongside the leaner `tsRules` / `templateRules` configs for a project that supplies its own style.
|
|
1165
1241
|
|
|
1166
1242
|
One consequence to keep in mind:
|
|
1167
1243
|
|
|
@@ -1233,7 +1309,7 @@ In `front/src/`, remove the file `typings.d.ts` if it is still there.
|
|
|
1233
1309
|
{
|
|
1234
1310
|
"extends": "./tsconfig.json",
|
|
1235
1311
|
"compilerOptions": {
|
|
1236
|
-
"outDir": "
|
|
1312
|
+
"outDir": "./out-tsc/app",
|
|
1237
1313
|
"types": []
|
|
1238
1314
|
},
|
|
1239
1315
|
"include": ["src/**/*.ts"],
|
|
@@ -1430,17 +1506,101 @@ When using `IntelliJ`, you can run code inspection on your project to fix deprec
|
|
|
1430
1506
|
- IntelliJ window menu, go to: `Code > Analyze code > Run inspection by name...` (or **Ctrl+Alt+Maj+i**) and type `Deprecated symbol used`.
|
|
1431
1507
|
- Or select your project in your project panel and `right click` on it then `Analyze > Run inspection by name...` (or **Ctrl+Alt+Maj+i**) and type `Deprecated symbol used`.
|
|
1432
1508
|
|
|
1509
|
+
### `(modelChange)` is emitted only when the component writes its model
|
|
1510
|
+
|
|
1511
|
+
In v18, a `foehn-input-*` component emitted `modelChange` again each time the page gave it a model, the same value
|
|
1512
|
+
included: the form loaded from the backend, a prefill, a reset... (with `undefined` at the initialization). Since
|
|
1513
|
+
19.0.0, the model of the components is a signal (`model()`), and `modelChange` is emitted only when the component
|
|
1514
|
+
writes its model, with a new value:
|
|
1515
|
+
|
|
1516
|
+
- at each input of the user, at once (`userInput` comes after a debounce);
|
|
1517
|
+
- when the component corrects the model the page gave it, e.g. `''` replaced by `null` in the text fields, a NAVS
|
|
1518
|
+
formatted as `756.xxxx.xxxx.xx`, the default country of an address, the `defaultElementValue` of a `foehn-select`.
|
|
1519
|
+
|
|
1520
|
+
It is no longer emitted when the page changes the model itself, which `[(model)]` doesn't need. Search your templates
|
|
1521
|
+
for `(modelChange)` on a `foehn-` component: a handler which also had to react to a model set by the page (e.g. to
|
|
1522
|
+
fill another field once the form is loaded, often behind a guard on `undefined`) is no longer called for it. Do that
|
|
1523
|
+
work where the page writes the form: after its loading (`GesdemEventService.formInitializationObservable()`, which
|
|
1524
|
+
emits the loaded form), after a prefill, after a reset.
|
|
1525
|
+
|
|
1526
|
+
### Your components write a new model
|
|
1527
|
+
|
|
1528
|
+
In v18, `updateNgModel(value)` emitted `modelChange` whatever the value. Since 19.0.0, the model is a signal, which
|
|
1529
|
+
ignores the same value: `updateNgModel()` with the object or the array the model already holds changes nothing, and no
|
|
1530
|
+
`modelChange` is emitted. A component extending `FoehnInputComponent` which keeps its model in a field
|
|
1531
|
+
(`onModelChange()` → `this.items = value`), modifies it in place (`this.items[i] = item`, `push()`, `splice()`,
|
|
1532
|
+
`[(model)]="item.x"`) and gives it back (`updateNgModel(this.items)`, a `getValidValue()` returning `this.item`) no
|
|
1533
|
+
longer notifies its page: the `(modelChange)` handlers of the page aren't called, and since 19.2.0, its `patchForm()`
|
|
1534
|
+
neither. The data seems saved as long as the object modified in place is the one of the page, and is lost as soon as
|
|
1535
|
+
the component works on another one (e.g. an object it created or replaced itself).
|
|
1536
|
+
|
|
1537
|
+
Search your components extending `FoehnInputComponent` for a `getValidValue()` returning a field (`return this.items;`,
|
|
1538
|
+
`return this.item;`) and for the writes in place of their model, and give `updateNgModel()` a new object or array:
|
|
1539
|
+
|
|
1540
|
+
- a list reads its `model()` directly, replaces an item from its template with
|
|
1541
|
+
`(modelChange)="patchNgModel([i], $event)"`, and adds or removes one with a new array (`[...list, item]`,
|
|
1542
|
+
`filter()`);
|
|
1543
|
+
- a component wrapping a single `foehn-*` component, to which it gives its whole model, binds it with
|
|
1544
|
+
`[model]="model()" (modelChange)="updateNgModel($event)"`, without a copy;
|
|
1545
|
+
- a component editing an object as is reads its `model()` directly, and writes each field with
|
|
1546
|
+
`patchNgModel(['address', 'street'], $event)` (since 19.2.0-beta.22), which keeps the fields it doesn't display (an
|
|
1547
|
+
id, a tracking index). Override `emptyModel()` when the page can give no object;
|
|
1548
|
+
- a component transforming its model (e.g. a date in three fields) keeps its linked signals, and its
|
|
1549
|
+
`getValidValue()` builds a new value.
|
|
1550
|
+
|
|
1551
|
+
Before 19.2.0-beta.22, write `patchNgModel()` yourself:
|
|
1552
|
+
`this.updateNgModel(ObjectPathHelper.patch(this.model() ?? new Owner(), path, value))`. See "Creating a reusable
|
|
1553
|
+
component", "Editing an object field by field" and the list of vehicles in [GOOD_PRACTICES.md](GOOD_PRACTICES.md).
|
|
1554
|
+
|
|
1555
|
+
The inputs inherited from `FoehnInputComponent` (`name`, `label`, `required`, `disabled`...) are signals too: read
|
|
1556
|
+
`this.name()`. `` `${this.name}[${index}]` `` and `this.name + '[0]'` compile, but give the signal, not its value
|
|
1557
|
+
(`[Input Signal: vehicules]` in development), e.g. a prefix of errors which matches no error. `restrict-template-expressions`
|
|
1558
|
+
(`configs.tsRecommended`, since 19.2.0) reports the template literals.
|
|
1559
|
+
|
|
1433
1560
|
### Strict mode (optional when migrating large projects but recommended)
|
|
1434
1561
|
|
|
1435
1562
|
- In your `tsconfig.json` file, add `"strict": true` in `compilerOptions` and remove `alwaysStrict`, `noImplicitThis`, `strictBindCallApply` and `strictFunctionTypes` as they are already included in `strict` mode.
|
|
1436
1563
|
- In your `tsconfig.json` file, remove `useDefineForClassFields` from `compilerOptions`.
|
|
1437
1564
|
|
|
1438
|
-
|
|
1565
|
+
Without `useDefineForClassFields: false`, the class fields follow the standard semantics: they are initialized before
|
|
1566
|
+
the body of the constructor, so before the parameter properties, and a field declared again in a subclass overwrites
|
|
1567
|
+
the value set by the parent class. Two errors can appear:
|
|
1568
|
+
|
|
1569
|
+
- TS2729 (`Property 'x' is used before its initialization`): a field initializer uses a parameter property of the
|
|
1570
|
+
constructor. Use `inject()` in the initializer, or assign the field in the constructor. Don't move a
|
|
1571
|
+
`private readonly x = inject(X)` field above the public fields: the `@typescript-eslint/member-ordering` rule of
|
|
1572
|
+
`@dsivd/prestations-ng/eslint` wants the public fields first.
|
|
1573
|
+
|
|
1574
|
+
```diff
|
|
1575
|
+
- readonly items = toSignal(this.itemService.getItems(), { initialValue: [] });
|
|
1576
|
+
-
|
|
1577
|
+
- constructor(private readonly itemService: ItemService) {}
|
|
1578
|
+
+ readonly items = toSignal(inject(ItemService).getItems(), { initialValue: [] });
|
|
1579
|
+
```
|
|
1580
|
+
|
|
1581
|
+
```ts
|
|
1582
|
+
readonly items: Signal<Item[]>;
|
|
1583
|
+
|
|
1584
|
+
private readonly itemService = inject(ItemService);
|
|
1585
|
+
|
|
1586
|
+
constructor() {
|
|
1587
|
+
this.items = toSignal(this.itemService.getItems(), { initialValue: [] });
|
|
1588
|
+
}
|
|
1589
|
+
```
|
|
1590
|
+
|
|
1591
|
+
- TS2612 (`Property 'x' will overwrite the base property`): a subclass declares again a field of its parent class,
|
|
1592
|
+
e.g. to narrow its type. Add `declare` (`declare form: MyForm | null | undefined;`) or remove the declaration, but
|
|
1593
|
+
never add an initializer: it would overwrite the value set by the parent class.
|
|
1594
|
+
|
|
1595
|
+
Now fix your project until no more errors (unlike `tsc -b`, these commands write nothing):
|
|
1439
1596
|
|
|
1440
1597
|
```bash
|
|
1441
|
-
npx tsc -
|
|
1598
|
+
npx tsc -p tsconfig.app.json --noEmit
|
|
1599
|
+
npx tsc -p tsconfig.spec.json --noEmit
|
|
1442
1600
|
```
|
|
1443
1601
|
|
|
1602
|
+
`tsc` doesn't check the templates: the errors reported by `strictTemplates` appear when you build your application.
|
|
1603
|
+
|
|
1444
1604
|
and finally run the following commands to build, test and start your application:
|
|
1445
1605
|
|
|
1446
1606
|
```bash
|
|
@@ -1449,6 +1609,462 @@ npm run test
|
|
|
1449
1609
|
npm start
|
|
1450
1610
|
```
|
|
1451
1611
|
|
|
1612
|
+
### `foehn-list-summary` is now generic (since 19.2.0)
|
|
1613
|
+
|
|
1614
|
+
`FoehnListSummaryComponent` is now `FoehnListSummaryComponent<T extends FoehnListItem>` and `FoehnListItemDescription` now takes a type parameter: `FoehnListItemDescription<T>`.
|
|
1615
|
+
Using `FoehnListItemDescription` without its type parameter no longer compiles.
|
|
1616
|
+
|
|
1617
|
+
Replace every `FoehnListItemDescription` with `FoehnListItemDescription<MyItem>`, where `MyItem` is your class extending `FoehnListItem`. You can then drop the casts (or `any`) in `getFormattedValue` and `hideIfEmpty`:
|
|
1618
|
+
|
|
1619
|
+
Before:
|
|
1620
|
+
|
|
1621
|
+
```typescript
|
|
1622
|
+
getListItemsDescription(): FoehnListItemDescription[] {
|
|
1623
|
+
return [
|
|
1624
|
+
{
|
|
1625
|
+
label: 'Name',
|
|
1626
|
+
getFormattedValue: (item: FoehnListItem) =>
|
|
1627
|
+
(item as MyItem).name ?? '',
|
|
1628
|
+
},
|
|
1629
|
+
];
|
|
1630
|
+
}
|
|
1631
|
+
```
|
|
1632
|
+
|
|
1633
|
+
After:
|
|
1634
|
+
|
|
1635
|
+
```typescript
|
|
1636
|
+
getListItemsDescription(): FoehnListItemDescription<MyItem>[] {
|
|
1637
|
+
return [
|
|
1638
|
+
{
|
|
1639
|
+
label: 'Name',
|
|
1640
|
+
getFormattedValue: (item: MyItem) => item.name ?? '',
|
|
1641
|
+
},
|
|
1642
|
+
];
|
|
1643
|
+
}
|
|
1644
|
+
```
|
|
1645
|
+
|
|
1646
|
+
The same applies to the function passed to `getListItemTitle`, which now receives a `MyItem`.
|
|
1647
|
+
|
|
1648
|
+
Never bind the list with a one-way `[model]` alone (see also "Quick fix"): the component removes the items itself,
|
|
1649
|
+
and only its `modelChange` passes the new list to your form. A one-way `[model]` compiles without warning, but the
|
|
1650
|
+
removed item stays in the form and comes back when the form is saved. In a page, whose form is a signal since 19.2.0
|
|
1651
|
+
(see "The form of your pages is a signal"), write the list with `patchForm()`, the form guarded:
|
|
1652
|
+
|
|
1653
|
+
```html
|
|
1654
|
+
@if (form(); as form) {
|
|
1655
|
+
<foehn-list-summary
|
|
1656
|
+
name="items"
|
|
1657
|
+
[model]="form.items"
|
|
1658
|
+
(modelChange)="patchForm(['items'], $event)"
|
|
1659
|
+
(itemRemoved)="itemRemoved()"
|
|
1660
|
+
/>
|
|
1661
|
+
}
|
|
1662
|
+
```
|
|
1663
|
+
|
|
1664
|
+
### `FoehnListItem` has no `trackingIndex` (since 19.2.0)
|
|
1665
|
+
|
|
1666
|
+
The library tracks the rows of a list by their index (see `require-track-index` in [ESLINT_PLUGIN.md](ESLINT_PLUGIN.md)):
|
|
1667
|
+
`FoehnListItem.trackingIndex` is removed, and `AbstractListDetailPageComponent` no longer sets it on a new item
|
|
1668
|
+
(`getNextTrackingIndex()` is removed too). The id of a row of `foehn-list-summary` is `list-summary-<its position
|
|
1669
|
+
from 1>`.
|
|
1670
|
+
|
|
1671
|
+
- Track your lists by `$index`, not by `item.trackingIndex`.
|
|
1672
|
+
- The code reading `trackingIndex` on an item typed with `FoehnListItem`, or calling or overriding
|
|
1673
|
+
`getNextTrackingIndex()`, no longer compiles: remove it.
|
|
1674
|
+
- 🚨 Nothing reports a backend needing the field (e.g. a `@NotNull trackingIndex`, a list sorted by it): a new item
|
|
1675
|
+
now reaches it without one. Remove the field from the backend and from its data, or, to keep it, declare it in your
|
|
1676
|
+
item class and set it in `getNewListItem()`.
|
|
1677
|
+
|
|
1678
|
+
### `core-js` is no longer needed (since 19.2.0)
|
|
1679
|
+
|
|
1680
|
+
prestations-ng no longer imports `core-js` and no longer has it as a peer dependency. If your project does not
|
|
1681
|
+
import `core-js` itself, uninstall it:
|
|
1682
|
+
|
|
1683
|
+
```bash
|
|
1684
|
+
npm uninstall core-js
|
|
1685
|
+
```
|
|
1686
|
+
|
|
1687
|
+
Then, in your `angular.json` file, remove `"core-js/modules/es.array.includes"` from `"allowedCommonJsDependencies"`.
|
|
1688
|
+
The CommonJS dependencies of prestations-ng are now `"iban"` and `"dayjs"` (which also covers `dayjs/plugin/*` and
|
|
1689
|
+
`dayjs/locale/*`):
|
|
1690
|
+
|
|
1691
|
+
```json
|
|
1692
|
+
"allowedCommonJsDependencies": ["iban", "dayjs"]
|
|
1693
|
+
```
|
|
1694
|
+
|
|
1695
|
+
Also remove the packages that are no longer installed (`npm ls <package>` lists nothing).
|
|
1696
|
+
|
|
1697
|
+
### `reference` of your pages is a signal (since 19.2.0)
|
|
1698
|
+
|
|
1699
|
+
`reference` of `AbstractPageComponent` is now a `WritableSignal<string | null | undefined>`: read it with
|
|
1700
|
+
`reference()`, in the templates of your pages too, and write it with `reference.set()`. A template, a `computed()` or
|
|
1701
|
+
an `effect()` reading it follows the reference, also when your page sets it, without `markForCheck()`.
|
|
1702
|
+
|
|
1703
|
+
The `ng update` migration of 19.2.0 rewrites your pages (see "Run the migration" in "The form of your pages is a
|
|
1704
|
+
signal" below):
|
|
1705
|
+
|
|
1706
|
+
```diff
|
|
1707
|
+
- this.http.get<FoehnRecapSection[]>(`api/${this.reference}/pdf-sections`)
|
|
1708
|
+
+ this.http.get<FoehnRecapSection[]>(`api/${this.reference()}/pdf-sections`)
|
|
1709
|
+
```
|
|
1710
|
+
|
|
1711
|
+
```diff
|
|
1712
|
+
- this.reference = reference;
|
|
1713
|
+
+ this.reference.set(reference);
|
|
1714
|
+
```
|
|
1715
|
+
|
|
1716
|
+
In the templates, it reads it through a `@let reference = this.reference();`, so that the reads are unchanged
|
|
1717
|
+
(`[reference]="reference"`). It removes a field of a page declaring `reference` again (e.g. `reference: string;`),
|
|
1718
|
+
which would hide the signal, and lists such a field holding a value.
|
|
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
|
+
|
|
1748
|
+
For a code it doesn't migrate (a class it doesn't recognize as a page):
|
|
1749
|
+
|
|
1750
|
+
- in the templates, `no-uninvoked-signal-in-template` (`configs.templateRecommended` or `configs.templateRules`, see
|
|
1751
|
+
[ESLINT_PLUGIN.md](ESLINT_PLUGIN.md)) reports `reference` without parentheses, and `ng lint --fix` adds them;
|
|
1752
|
+
- in TypeScript, the compiler reports the writes (`this.reference = ...`) and the arguments typed `string`. With
|
|
1753
|
+
`configs.tsRecommended`, `no-uncalled-signals` reports `!this.reference`, `this.reference && ...`,
|
|
1754
|
+
`'...' + this.reference` and `this.reference?.length`, and `restrict-template-expressions` reports
|
|
1755
|
+
`` `${this.reference}` ``. Nothing reports a read where any value is accepted, e.g. in an array
|
|
1756
|
+
(`this.router.navigate([prefix, this.reference])`): list the reads which are not calls, and check each of them
|
|
1757
|
+
(the fields named `reference` of your other classes are listed too):
|
|
1758
|
+
|
|
1759
|
+
```bash
|
|
1760
|
+
grep -rnP "\bthis\.reference\b(?!\s*(\(|\.set\(|\.update\())" src --include=*.ts
|
|
1761
|
+
```
|
|
1762
|
+
|
|
1763
|
+
In an `effect()`, reading `this.reference()` runs the effect again when the reference changes: read it with
|
|
1764
|
+
`untracked(this.reference)` when the effect must not follow it.
|
|
1765
|
+
|
|
1766
|
+
### The form of your pages is a signal (since 19.2.0)
|
|
1767
|
+
|
|
1768
|
+
`form` of `AbstractPageComponent` is now a `WritableSignal<T | null | undefined>`: read it with `form()`, and never
|
|
1769
|
+
modify its value in place. Write it with `patchForm(path, value)`, which copies the objects along the path, or with
|
|
1770
|
+
`form.set()` / `form.update()` and a new object. A template, a `computed()` or an `effect()` reading it follows every
|
|
1771
|
+
input of the user, and no `markForCheck()` is needed after a write anymore.
|
|
1772
|
+
|
|
1773
|
+
#### Run the migration
|
|
1774
|
+
|
|
1775
|
+
`ng update @dsivd/prestations-ng` migrates your pages (the classes extending `AbstractPageComponent`,
|
|
1776
|
+
`AbstractMenuPageComponent`, `AbstractPageFromMenuComponent`, `AbstractListDetailPageComponent`, or one of your
|
|
1777
|
+
classes extending them) and their templates. It runs again at each beta of 19.2.0, which changes nothing once
|
|
1778
|
+
migrated. To run it by hand, e.g. on a branch updated meanwhile:
|
|
1779
|
+
|
|
1780
|
+
```bash
|
|
1781
|
+
ng update @dsivd/prestations-ng --migrate-only --from=19.1.0 --to=19.2.0
|
|
1782
|
+
```
|
|
1783
|
+
|
|
1784
|
+
Then format the files it changed (`prettier --write`), build, lint, and fix what it lists as "To check by hand"
|
|
1785
|
+
(see below).
|
|
1786
|
+
|
|
1787
|
+
In the templates, it reads the form through a `@let`, so that the reads and their narrowing (`@if (form)`) are
|
|
1788
|
+
unchanged, and writes the fields with `patchForm()`:
|
|
1789
|
+
|
|
1790
|
+
```diff
|
|
1791
|
+
+ @let form = this.form();
|
|
1792
|
+
@if (form) {
|
|
1793
|
+
- <foehn-input-text name="address.street" [(model)]="form.address.street" />
|
|
1794
|
+
+ <foehn-input-text name="address.street" [model]="form.address.street" (modelChange)="patchForm(['address', 'street'], $event)" />
|
|
1795
|
+
- @for (child of form.children; track child) {
|
|
1796
|
+
+ @for (child of form.children; track $index) {
|
|
1797
|
+
- <foehn-input-text [name]="'children[' + $index + '].firstName'" [(model)]="child.firstName" />
|
|
1798
|
+
+ <foehn-input-text [name]="'children[' + $index + '].firstName'" [model]="child.firstName" (modelChange)="patchForm(['children', $index, 'firstName'], $event)" />
|
|
1799
|
+
}
|
|
1800
|
+
}
|
|
1801
|
+
```
|
|
1802
|
+
|
|
1803
|
+
In the classes:
|
|
1804
|
+
|
|
1805
|
+
```diff
|
|
1806
|
+
- this.form = form;
|
|
1807
|
+
+ this.form.set(form);
|
|
1808
|
+
- this.form.firstName = info?.firstName ?? null;
|
|
1809
|
+
+ this.patchForm(['firstName'], info?.firstName ?? null);
|
|
1810
|
+
- this.form.children.push(child);
|
|
1811
|
+
+ this.patchForm(['children'], [...(this.form()!.children ?? []), child]);
|
|
1812
|
+
- if (this.form) {
|
|
1813
|
+
- this.http.post('api/check', this.form.amount);
|
|
1814
|
+
- this.pdf = this.gesdemService.pdf(this.form);
|
|
1815
|
+
+ if (this.form()) {
|
|
1816
|
+
+ this.http.post('api/check', this.form()!.amount);
|
|
1817
|
+
+ this.pdf = this.gesdemService.pdf(this.form()!);
|
|
1818
|
+
```
|
|
1819
|
+
|
|
1820
|
+
A read narrowed by a guard (`if (this.form)`, `this.form ? ... : ...`, `this.form && ...`,
|
|
1821
|
+
`if (!this.form) { return; }`) gets a `!`: TypeScript narrows `this.form`, but not the call `this.form()`. The same for
|
|
1822
|
+
`reference`, `itemToEdit` and `itemIndex`.
|
|
1823
|
+
|
|
1824
|
+
#### Check by hand
|
|
1825
|
+
|
|
1826
|
+
The migration leaves untouched, and lists with their file and line, what it can't rewrite. The compiler reports it
|
|
1827
|
+
too (`this.form.x` doesn't exist on a signal):
|
|
1828
|
+
|
|
1829
|
+
- the writes other than an assignment or a `push()` / `unshift()`: `+=`, `++`, `splice()`, `sort()`, a write inside
|
|
1830
|
+
an expression... Write a new value, e.g. `this.patchForm(['children'], children.filter((c) => c !== child))`;
|
|
1831
|
+
- the two-way bindings it can't follow: through a call or a pipe, or in a `*ngFor` over the form. Migrate the
|
|
1832
|
+
`*ngFor` to `@for` first (`ng generate @angular/core:control-flow`), then run the migration again;
|
|
1833
|
+
- the `getList()` of the detail pages which compute their list, see below.
|
|
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
|
+
|
|
1866
|
+
Also check:
|
|
1867
|
+
|
|
1868
|
+
- your specs, which the migration doesn't change: `component.form = x` becomes `component.form.set(x)`, and
|
|
1869
|
+
`component.form.x` becomes `component.form()!.x` (the compiler reports them);
|
|
1870
|
+
- the components receiving the form, or an object of it, as an input and modifying it: they modify the value of the
|
|
1871
|
+
signal in place, the page isn't notified. Give them an output, and let the page write with `patchForm()`;
|
|
1872
|
+
- the services and the methods receiving the form, or an object of it, as an argument and modifying it, e.g. an
|
|
1873
|
+
`enrichWithSessionInfoData(form)` filling it with the session in the callback of `prefillForm()`: the same, and
|
|
1874
|
+
neither the migration nor `no-direct-signal-mutation` follow the form into them. Let them return the values, and
|
|
1875
|
+
the page write them with `patchForm()` or `form.update()`;
|
|
1876
|
+
- the fields whose type differs from the model of their component, e.g. a date typed `number[] | null`: `[(model)]`
|
|
1877
|
+
didn't compare them, `patchForm()` does, and the build reports its `$event` (TS2345). Type the field as the model:
|
|
1878
|
+
`FoehnDateModel | null` for `foehn-input-date`, `FoehnDateTimeModel | null` for `foehn-input-date-time`;
|
|
1879
|
+
- the `markForCheck()` called after a write of the form or of the reference (zoneless): they are useless now, remove
|
|
1880
|
+
them, unless they notify another field. The migration lists those of a function writing the form or the reference,
|
|
1881
|
+
not those of a callback given to a service.
|
|
1882
|
+
|
|
1883
|
+
`no-direct-signal-mutation` reports the writes in place left (`this.form()!.x = 1`, `form.children.push(child)`),
|
|
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"`).
|
|
1886
|
+
|
|
1887
|
+
#### Lists of the form
|
|
1888
|
+
|
|
1889
|
+
`patchForm()` replaces each object along the path with a copy: a row of a `@for` tracked by its item (`track child`)
|
|
1890
|
+
is then destroyed and created again at each input, and the field being edited loses the focus. Track the rows of a
|
|
1891
|
+
list edited by its rows by `$index`, the index naming their fields (an identifier of the item, `track child.id`, only
|
|
1892
|
+
when they name nothing with it). The migration does it for the lists it migrates, and `no-item-track-in-form-list`
|
|
1893
|
+
and `require-track-index` (`configs.templateRecommended`) report the others.
|
|
1894
|
+
|
|
1895
|
+
#### Write your templates
|
|
1896
|
+
|
|
1897
|
+
```html
|
|
1898
|
+
@if (form(); as form) {
|
|
1899
|
+
<foehn-input-text
|
|
1900
|
+
name="firstName"
|
|
1901
|
+
[model]="form.firstName"
|
|
1902
|
+
(modelChange)="patchForm(['firstName'], $event)"
|
|
1903
|
+
/>
|
|
1904
|
+
}
|
|
1905
|
+
```
|
|
1906
|
+
|
|
1907
|
+
- The path is checked by TypeScript: a typo gives an error listing the valid keys. For a form serving several
|
|
1908
|
+
prestations, type the page with a union (`AbstractPageComponent<ApForm | AfForm>`): the paths of each of them are
|
|
1909
|
+
accepted.
|
|
1910
|
+
- `null` and `undefined` are accepted, as with `[(model)]`: the model of the `foehn-*` components can be.
|
|
1911
|
+
- Never a `[model]` alone on a field the user can change: what the user enters would never reach the form.
|
|
1912
|
+
`require-model-change` (`configs.templateRecommended`) reports it. A field always disabled
|
|
1913
|
+
(`[disabled]="true"`), only displayed, is bound with `[model]` alone.
|
|
1914
|
+
- `@let form = this.form();`, which the migration adds, is just as valid.
|
|
1915
|
+
- Outside a page, `ObjectPathHelper` writes a path of any object the same way: `patch(object, path, value)`, and
|
|
1916
|
+
`patchSignal(signal, path, value)` for a signal holding an object (e.g. the state of a component), typed with
|
|
1917
|
+
`ObjectPath<T>` and `ObjectPathValue<T, P>`. `getByKeys()` and `patchByKeys()` take keys known at runtime only
|
|
1918
|
+
(`'address.street'`), not checked by TypeScript.
|
|
1919
|
+
|
|
1920
|
+
#### Detail pages
|
|
1921
|
+
|
|
1922
|
+
`AbstractListDetailPageComponent` no longer modifies the list of the form in place:
|
|
1923
|
+
|
|
1924
|
+
| Before | Since 19.2.0 |
|
|
1925
|
+
| ---------------------------------------------- | ----------------------------------------------------------------------------------------- |
|
|
1926
|
+
| `getList(): Dog[] { return this.form.dogs; }` | `getListPath(): ObjectPath<MyForm> { return ['dogs']; }` (`getList()` is still available) |
|
|
1927
|
+
| `list`, `itemIndex`, `itemToEdit` | `list()`, `itemIndex()`, `itemToEdit()` |
|
|
1928
|
+
| `[(model)]="itemToEdit.name"` | `[model]="item.name" (modelChange)="patchItem(['name'], $event)"` |
|
|
1929
|
+
| `this.itemToEdit.site = null; ...` (in place) | `this.updateItem((item) => ({ ...item, site: null, ideNumber: null }))` |
|
|
1930
|
+
| `[(model)]="list[itemIndex]"` (the whole item) | `[model]="item" (modelChange)="setItem($event)"` |
|
|
1931
|
+
|
|
1932
|
+
The migration replaces a `getList()` returning a path of the form (`this.form.a.b`, `this.form?.a?.b ?? []`). A
|
|
1933
|
+
`getList()` choosing its list (e.g. according to the prestation) becomes a `getListPath()` choosing its path:
|
|
1934
|
+
|
|
1935
|
+
```ts
|
|
1936
|
+
getListPath(): ObjectPath<ApForm | AfForm> {
|
|
1937
|
+
return this.isAp()
|
|
1938
|
+
? ['diplomeData', 'diplomes']
|
|
1939
|
+
: ['formationData', 'diplomes'];
|
|
1940
|
+
}
|
|
1941
|
+
```
|
|
1942
|
+
|
|
1943
|
+
### `neverConnected` is provided with `NEVER_CONNECTED` (since 19.2.0)
|
|
1944
|
+
|
|
1945
|
+
`SessionInfo` reads the `NEVER_CONNECTED` token: a provider `{ provide: 'neverConnected', useValue: true }` is ignored
|
|
1946
|
+
without any error, and your application fetches the session and displays the connected user or the login button.
|
|
1947
|
+
`ng update @dsivd/prestations-ng` replaces it (see "Run the migration" above to run it by hand):
|
|
1948
|
+
|
|
1949
|
+
```diff
|
|
1950
|
+
- { provide: 'neverConnected', useValue: true },
|
|
1951
|
+
+ { provide: NEVER_CONNECTED, useValue: true },
|
|
1952
|
+
```
|
|
1953
|
+
|
|
1954
|
+
with `NEVER_CONNECTED` imported from `@dsivd/prestations-ng`. It lists the other uses of the string `'neverConnected'`
|
|
1955
|
+
it doesn't rewrite: search them in your providers, e.g. a value coming from a constant or a shared library.
|
|
1956
|
+
|
|
1957
|
+
### Zoneless (optional but recommended)
|
|
1958
|
+
|
|
1959
|
+
Since v19.2, prestations-ng does not need zone.js anymore: the state of its components is held by signals, which
|
|
1960
|
+
tell Angular when a component has to be refreshed. prestations-ng keeps working in an application using zone.js,
|
|
1961
|
+
so this step is optional, but a zoneless application is lighter, faster and easier to debug. See the
|
|
1962
|
+
[Angular zoneless guide](https://angular.dev/guide/zoneless).
|
|
1963
|
+
|
|
1964
|
+
In any case, if your code reads some fields of the prestations-ng components (e.g. through `viewChild()` or in
|
|
1965
|
+
your tests), check the fields that are now signals in the [CHANGELOG](CHANGELOG.md#1920---should-be-aligned-with-prestations-be-192x).
|
|
1966
|
+
|
|
1967
|
+
#### Enable the zoneless change detection
|
|
1968
|
+
|
|
1969
|
+
Zoneless is the default since Angular 21: `ng update` added `provideZoneChangeDetection()` to keep zone.js in your
|
|
1970
|
+
application. Replace it in your `app.config.ts` (`providePrestationsNgCore()` already provides
|
|
1971
|
+
`provideBrowserGlobalErrorListeners()`, which reports to your `ErrorHandler` the errors zone.js used to catch):
|
|
1972
|
+
|
|
1973
|
+
```diff
|
|
1974
|
+
export const appConfig: ApplicationConfig = {
|
|
1975
|
+
providers: [
|
|
1976
|
+
- provideZoneChangeDetection({ eventCoalescing: true }),
|
|
1977
|
+
+ provideZonelessChangeDetection(),
|
|
1978
|
+
providePrestationsNgCore(),
|
|
1979
|
+
...
|
|
1980
|
+
],
|
|
1981
|
+
};
|
|
1982
|
+
```
|
|
1983
|
+
|
|
1984
|
+
Remove `zone.js` and `zone.js/testing` from the `polyfills` of the `build` and `test` targets in your
|
|
1985
|
+
`angular.json` (and from your `polyfills.ts` file if you still have one): without them, the `TestBed` is zoneless
|
|
1986
|
+
too.
|
|
1987
|
+
|
|
1988
|
+
```diff
|
|
1989
|
+
"polyfills": [
|
|
1990
|
+
- "zone.js"
|
|
1991
|
+
],
|
|
1992
|
+
```
|
|
1993
|
+
|
|
1994
|
+
then uninstall zone.js:
|
|
1995
|
+
|
|
1996
|
+
```bash
|
|
1997
|
+
npm uninstall zone.js
|
|
1998
|
+
```
|
|
1999
|
+
|
|
2000
|
+
`zone.js` can stay in your `package-lock.json` as an optional peer dependency of `@angular/core`: this is expected. Check
|
|
2001
|
+
instead that the build of your application no longer outputs a `polyfills` chunk (unless you still have other
|
|
2002
|
+
polyfills, e.g. `@angular/localize/init`).
|
|
2003
|
+
|
|
2004
|
+
#### Check your components
|
|
2005
|
+
|
|
2006
|
+
Without zone.js, Angular refreshes a component only when it is notified that something changed:
|
|
2007
|
+
|
|
2008
|
+
- a listener of its template has been called (`(click)`, `(modelChange)`, `(userInput)`...), including the
|
|
2009
|
+
`[(model)]` two-way bindings
|
|
2010
|
+
- a signal read by its template has changed (`signal()`, `computed()`, `input()`, `model()`, `toSignal()`...)
|
|
2011
|
+
- `ChangeDetectorRef.markForCheck()` has been called, which is what the `async` pipe does when an observable emits
|
|
2012
|
+
|
|
2013
|
+
A field modified elsewhere (in a `subscribe()`, a `setTimeout()`, a `Promise`, a callback, an `effect()`...) is not
|
|
2014
|
+
displayed anymore until something else refreshes the component. Hold it in a signal (see
|
|
2015
|
+
[INTRODUCTION_ANGULAR_SIGNALS.md](INTRODUCTION_ANGULAR_SIGNALS.md)), as well as the fields read by the template that
|
|
2016
|
+
only a method called by a listener modifies: this method can later be called from elsewhere.
|
|
2017
|
+
|
|
2018
|
+
```diff
|
|
2019
|
+
- isLoading = true;
|
|
2020
|
+
+ readonly isLoading = signal(true);
|
|
2021
|
+
|
|
2022
|
+
ngOnInit(): void {
|
|
2023
|
+
this.myService.load().subscribe(() => {
|
|
2024
|
+
- this.isLoading = false;
|
|
2025
|
+
+ this.isLoading.set(false);
|
|
2026
|
+
});
|
|
2027
|
+
}
|
|
2028
|
+
```
|
|
2029
|
+
|
|
2030
|
+
```diff
|
|
2031
|
+
- @if (isLoading) {
|
|
2032
|
+
+ @if (isLoading()) {
|
|
2033
|
+
```
|
|
2034
|
+
|
|
2035
|
+
Pay attention to:
|
|
2036
|
+
|
|
2037
|
+
- your pages (`AbstractPageComponent` and its subclasses): since 19.2.0, `form` and `reference` are signals (see "The
|
|
2038
|
+
form of your pages is a signal" and "`reference` of your pages is a signal"). Write the form with `patchForm()`,
|
|
2039
|
+
never in place: no `markForCheck()` is needed after a write.
|
|
2040
|
+
|
|
2041
|
+
- the fields read by the template and set in `ngAfterViewInit()`, `ngAfterContentInit()` or `ngAfterViewChecked()`:
|
|
2042
|
+
derive them with `computed()` from `viewChild()` or `contentChild()` (see "Deriving a state from view queries"
|
|
2043
|
+
in [GOOD_PRACTICES.md](GOOD_PRACTICES.md)).
|
|
2044
|
+
|
|
2045
|
+
- `NgZone`: `onStable`, `onMicrotaskEmpty` and `onUnstable` never emit without zone.js, and `run()` or
|
|
2046
|
+
`runOutsideAngular()` are useless. To act on the rendered DOM (focus, scroll...), replace them, as well as the
|
|
2047
|
+
`setTimeout()` waiting for the view, by `afterNextRender()`. `AbstractMenuPageComponent.ngZone` is deprecated.
|
|
2048
|
+
|
|
2049
|
+
```diff
|
|
2050
|
+
- this.ngZone.onStable.pipe(first()).subscribe(() => this.focusFirstField());
|
|
2051
|
+
+ afterNextRender(() => this.focusFirstField(), { injector: this.injector });
|
|
2052
|
+
```
|
|
2053
|
+
|
|
2054
|
+
#### Check your tests
|
|
2055
|
+
|
|
2056
|
+
- `fakeAsync()`, `tick()`, `flush()` and `waitForAsync()` need zone.js: write `async` tests, with
|
|
2057
|
+
`vi.useFakeTimers()` and `await vi.advanceTimersByTimeAsync(ms)` to control the timers (see
|
|
2058
|
+
[Migrate to vitest](#migrate-to-vitest)).
|
|
2059
|
+
- `fixture.detectChanges()` only refreshes the views which have been notified, then checks that nothing changed
|
|
2060
|
+
meanwhile: a field modified without notification makes the test fail with the error `NG0100`
|
|
2061
|
+
(`ExpressionChangedAfterItHasBeenCheckedError`). Fix the component (signal, `markForCheck()`) rather than the
|
|
2062
|
+
test.
|
|
2063
|
+
- `await fixture.whenStable()` waits for the change detection and for the pending tasks of the application
|
|
2064
|
+
(e.g. the debounced `userInput` of the prestations-ng inputs), not for the timers, nor for the HTTP requests of a
|
|
2065
|
+
spec: `provideHttpClientTesting()` keeps them pending until the test answers them. Answer them first with
|
|
2066
|
+
`HttpTestingController` (`expectOne(...).flush(...)`), then `await fixture.whenStable()`.
|
|
2067
|
+
|
|
1452
2068
|
### Last but not least, check if your application is working!!!
|
|
1453
2069
|
|
|
1454
2070
|
#### Be sure your application gets a fresh start
|
|
@@ -1488,7 +2104,8 @@ See [getImtPortailApplications](https://dsigit.etat-de-vaud.ch/outils/git/projec
|
|
|
1488
2104
|
'project': 'cybersdk',
|
|
1489
2105
|
'name' : 'skeleton',
|
|
1490
2106
|
'gitUrl' : 'ssh://git@bitbucket.etat-de-vaud.ch/cybsdk/skeleton.git',
|
|
1491
|
-
|
|
2107
|
+
- 'jdk' : '21',
|
|
2108
|
+
+ 'jdk' : '25',
|
|
1492
2109
|
- 'node' : '20'
|
|
1493
2110
|
+ 'node' : '22'
|
|
1494
2111
|
],
|