@dsivd/prestations-ng 19.2.0-beta.2 → 19.2.0-beta.21

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (55) hide show
  1. package/ANGULAR_SIGNALS.md +4 -0
  2. package/CHANGELOG.md +396 -0
  3. package/CONTRIBUTING.md +74 -4
  4. package/ESLINT_PLUGIN.md +103 -8
  5. package/GOOD_PRACTICES.md +731 -380
  6. package/INTRODUCTION_ANGULAR_SIGNALS.md +199 -154
  7. package/UPGRADING_V18.md +5 -5
  8. package/UPGRADING_V19.md +439 -18
  9. package/eslint/configs/spec-ts-recommended.mjs +34 -0
  10. package/eslint/configs/template-recommended.mjs +2 -0
  11. package/eslint/configs/template-rules.mjs +11 -2
  12. package/eslint/configs/ts-recommended.mjs +6 -0
  13. package/eslint/configs/ts-rules.mjs +6 -2
  14. package/eslint/form-reads.mjs +63 -0
  15. package/eslint/index.mjs +17 -0
  16. package/eslint/rules/index.mjs +4 -0
  17. package/eslint/rules/no-direct-signal-mutation.mjs +58 -20
  18. package/eslint/rules/no-item-track-in-form-list.mjs +99 -0
  19. package/eslint/rules/no-uninvoked-signal-in-template.mjs +8 -3
  20. package/eslint/rules/require-model-change.mjs +89 -0
  21. package/eslint/template-ast.mjs +12 -2
  22. package/fesm2022/dsivd-prestations-ng.mjs +2766 -2073
  23. package/fesm2022/dsivd-prestations-ng.mjs.map +1 -1
  24. package/package.json +1 -2
  25. package/schematics/migration-collection.json +5 -0
  26. package/schematics/ng-add/index.js +2 -4
  27. package/schematics/ng-update/migrations/update-13_2_0/index.js +7 -2
  28. package/schematics/ng-update/migrations/update-19_2_0/index.js +39 -0
  29. package/schematics/utility/add-allowed-common-js-dependencies.js +39 -29
  30. package/schematics/utility/form-signal/class-migration.js +396 -0
  31. package/schematics/utility/form-signal/edits.js +34 -0
  32. package/schematics/utility/form-signal/form-signal-migration.js +184 -0
  33. package/schematics/utility/form-signal/page-classes.js +129 -0
  34. package/schematics/utility/form-signal/template-migration.js +666 -0
  35. package/schematics/utility/remove-emit-decorator-metadata.js +8 -9
  36. package/src/eslint/configs/__tests__/configs.test.mjs +46 -2
  37. package/src/eslint/configs/spec-ts-recommended.mjs +34 -0
  38. package/src/eslint/configs/template-recommended.mjs +2 -0
  39. package/src/eslint/configs/template-rules.mjs +11 -2
  40. package/src/eslint/configs/ts-recommended.mjs +6 -0
  41. package/src/eslint/configs/ts-rules.mjs +6 -2
  42. package/src/eslint/form-reads.mjs +63 -0
  43. package/src/eslint/index.mjs +17 -0
  44. package/src/eslint/rules/__tests__/no-direct-signal-mutation.test.mjs +58 -0
  45. package/src/eslint/rules/__tests__/no-item-track-in-form-list.test.mjs +127 -0
  46. package/src/eslint/rules/__tests__/no-uninvoked-signal-in-template.test.mjs +6 -0
  47. package/src/eslint/rules/__tests__/require-model-change.test.mjs +93 -0
  48. package/src/eslint/rules/index.mjs +4 -0
  49. package/src/eslint/rules/no-direct-signal-mutation.mjs +58 -20
  50. package/src/eslint/rules/no-item-track-in-form-list.mjs +99 -0
  51. package/src/eslint/rules/no-uninvoked-signal-in-template.mjs +8 -3
  52. package/src/eslint/rules/require-model-change.mjs +89 -0
  53. package/src/eslint/template-ast.mjs +12 -2
  54. package/types/dsivd-prestations-ng.d.ts +652 -240
  55. package/dsivd-prestations-ng-19.2.0-beta.2.tgz +0 -0
package/UPGRADING_V18.md CHANGED
@@ -51,10 +51,8 @@ Fix application.properties :
51
51
 
52
52
  ```diff
53
53
  logging.config=${ch.vd.configDir}/logback-spring.xml
54
- + # Restore sleuth traces at the same position as in spring boot 2
55
- + logging.pattern.level=%5p [${spring.application.name:},%X{traceId:-},%X{spanId:-}]
56
- + # remove sleuth traces added by spring boot 3
57
- + logging.pattern.correlation=
54
+ + # Restore sleuth traces at the same position as in spring boot 2, bien laisser l'espace à la fin de la ligne
55
+ + logging.pattern.correlation=[${spring.application.name:},%X{traceId:-},%X{spanId:-}]
58
56
  + logging.include-application-name=false
59
57
  ```
60
58
 
@@ -350,7 +348,9 @@ repository. The subfolder name must correspond to the deployUnit name.
350
348
  Define `deployUnit.groupId` et `deployUnit.name` in your moved base properties file.
351
349
 
352
350
  In the helm folder, add a subfolder with the deployUnit name and fill it with a values.yaml file (copy-paste-replace
353
- from another similar)
351
+ from another similar, take care that there is a `environment: {{ get .Properties.rftoolkit "environment" }}` (with the
352
+ right application name, the right number of replicas, the right management port, the right liveness and readiness
353
+ probes, the right resources, etc.).
354
354
  NB : if your application is using a `${ch.vd.dataDir}` that must survive a restart, your can mount a persistent
355
355
  volume by adding `dataDirSize: 10Mi` (pick the right size) in the values.yaml file.
356
356
 
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
- ### BO : Package renaming
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
- ### BO : Brave Tracer
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`
@@ -309,7 +309,9 @@ ng update @angular/core@20 @angular/cli@20
309
309
  - hit "Enter" key
310
310
 
311
311
  🚨 **IMPORTANT: Search for every `@for` in your project and check that `track` statement is present and has a unique identifier.
312
- When a unique identifier such as `id` is not possible, track by object or as a last resort use `track $index`.**
312
+ When a unique identifier such as `id` is not possible, track by object or as a last resort use `track $index`. Since
313
+ 19.2.0, never track by object a list of the form whose rows edit their item: track it by `id` or by `$index` (see
314
+ "The form of your pages is a signal").**
313
315
 
314
316
  💡 **NB: When using `@angular/cdk` in your project**
315
317
 
@@ -1064,8 +1066,13 @@ npm install --save-dev eslint-plugin-simple-import-sort@13
1064
1066
  npm install --save-dev eslint-config-prettier@10
1065
1067
  npm install --save-dev eslint-plugin-import-x@4
1066
1068
  npm install --save-dev prettier
1069
+ # only if your project has Vitest specs (see "Migrate to vitest")
1070
+ npm install --save-dev --save-exact @vitest/eslint-plugin@1.6.27
1067
1071
  ```
1068
1072
 
1073
+ `@vitest/eslint-plugin` 1.6.28 and later need TypeScript 6: with the TypeScript 5.9 of Angular 21, `npm install` fails
1074
+ with `ERESOLVE`. Keep 1.6.27 until your project moves to TypeScript 6.
1075
+
1069
1076
  In your `front` folder, add a `.prettierrc` file with the following content:
1070
1077
 
1071
1078
  ```json
@@ -1140,6 +1147,12 @@ export default tseslint.config(
1140
1147
  extends: [...prestationsNg.configs.templateRecommended],
1141
1148
  },
1142
1149
 
1150
+ // ─── Vitest specs (only if your project has Vitest specs) ─────────────────
1151
+ {
1152
+ files: ['**/*.spec.ts'],
1153
+ extends: [...prestationsNg.configs.specTsRecommended],
1154
+ },
1155
+
1143
1156
  // ─── Prettier (must be last — disables formatting rules) ───────────────────
1144
1157
  prettier,
1145
1158
  );
@@ -1150,6 +1163,11 @@ everything: the `eslint`, `typescript-eslint` and `angular-eslint` baselines, th
1150
1163
  accessibility set, the naming and import conventions, and the rules written by the library
1151
1164
  itself. You declare no `plugins` and list no rule.
1152
1165
 
1166
+ `specTsRecommended` is the `recommended` config of `@vitest/eslint-plugin`, which also counts the assertions
1167
+ made by the `HttpTestingController` (`expectOne`, `expectNone`, `verify`) and by helpers named `expect*`,
1168
+ `assert*` or `test*`. The `**/*.spec.ts` pattern does not reach the Cypress `*.spec.cy.ts` files. It needs
1169
+ `@vitest/eslint-plugin` only when you use it: the other configs work without it.
1170
+
1153
1171
  The packages installed above are still required — the library's config imports them from your
1154
1172
  `node_modules` rather than shipping its own copies. For the same reason, do **not** spread
1155
1173
  `angular.configs.tsRecommended` or `angular.configs.templateRecommended` yourself: they are
@@ -1158,10 +1176,10 @@ fail outright.
1158
1176
 
1159
1177
  #### prestations-ng ESLint rules
1160
1178
 
1161
- The library ships **shareable custom configs** that are auto-updatable with the library version. Two
1162
- rules are enabled today — `no-direct-signal-mutation` and `no-uninvoked-signal-in-template` — and both
1163
- are documented in [the plugin guide](ESLINT_PLUGIN.md), alongside the leaner `tsRules` / `templateRules`
1164
- configs for a project that supplies its own style.
1179
+ The library ships **shareable custom configs** that are auto-updatable with the library version. Four
1180
+ rules are enabled today — `no-direct-signal-mutation`, `no-uninvoked-signal-in-template`, and, since 19.2.0,
1181
+ `require-model-change` and `no-item-track-in-form-list` — all documented in [the plugin guide](ESLINT_PLUGIN.md),
1182
+ alongside the leaner `tsRules` / `templateRules` configs for a project that supplies its own style.
1165
1183
 
1166
1184
  One consequence to keep in mind:
1167
1185
 
@@ -1233,7 +1251,7 @@ In `front/src/`, remove the file `typings.d.ts` if it is still there.
1233
1251
  {
1234
1252
  "extends": "./tsconfig.json",
1235
1253
  "compilerOptions": {
1236
- "outDir": "../out-tsc/app",
1254
+ "outDir": "./out-tsc/app",
1237
1255
  "types": []
1238
1256
  },
1239
1257
  "include": ["src/**/*.ts"],
@@ -1430,17 +1448,67 @@ When using `IntelliJ`, you can run code inspection on your project to fix deprec
1430
1448
  - IntelliJ window menu, go to: `Code > Analyze code > Run inspection by name...` (or **Ctrl+Alt+Maj+i**) and type `Deprecated symbol used`.
1431
1449
  - 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
1450
 
1451
+ ### `(modelChange)` is emitted only when the component writes its model
1452
+
1453
+ In v18, a `foehn-input-*` component emitted `modelChange` again each time the page gave it a model, the same value
1454
+ included: the form loaded from the backend, a prefill, a reset... (with `undefined` at the initialization). Since
1455
+ 19.0.0, the model of the components is a signal (`model()`), and `modelChange` is emitted only when the component
1456
+ writes its model, with a new value:
1457
+
1458
+ - at each input of the user, at once (`userInput` comes after a debounce);
1459
+ - when the component corrects the model the page gave it, e.g. `''` replaced by `null` in the text fields, a NAVS
1460
+ formatted as `756.xxxx.xxxx.xx`, the default country of an address, the `defaultElementValue` of a `foehn-select`.
1461
+
1462
+ It is no longer emitted when the page changes the model itself, which `[(model)]` doesn't need. Search your templates
1463
+ for `(modelChange)` on a `foehn-` component: a handler which also had to react to a model set by the page (e.g. to
1464
+ fill another field once the form is loaded, often behind a guard on `undefined`) is no longer called for it. Do that
1465
+ work where the page writes the form: after its loading (`GesdemEventService.formInitializationObservable()`, which
1466
+ emits the loaded form), after a prefill, after a reset.
1467
+
1433
1468
  ### Strict mode (optional when migrating large projects but recommended)
1434
1469
 
1435
1470
  - 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
1471
  - In your `tsconfig.json` file, remove `useDefineForClassFields` from `compilerOptions`.
1437
1472
 
1438
- Now fix your project until no more errors:
1473
+ Without `useDefineForClassFields: false`, the class fields follow the standard semantics: they are initialized before
1474
+ the body of the constructor, so before the parameter properties, and a field declared again in a subclass overwrites
1475
+ the value set by the parent class. Two errors can appear:
1476
+
1477
+ - TS2729 (`Property 'x' is used before its initialization`): a field initializer uses a parameter property of the
1478
+ constructor. Use `inject()` in the initializer, or assign the field in the constructor. Don't move a
1479
+ `private readonly x = inject(X)` field above the public fields: the `@typescript-eslint/member-ordering` rule of
1480
+ `@dsivd/prestations-ng/eslint` wants the public fields first.
1481
+
1482
+ ```diff
1483
+ - readonly items = toSignal(this.itemService.getItems(), { initialValue: [] });
1484
+ -
1485
+ - constructor(private readonly itemService: ItemService) {}
1486
+ + readonly items = toSignal(inject(ItemService).getItems(), { initialValue: [] });
1487
+ ```
1488
+
1489
+ ```ts
1490
+ readonly items: Signal<Item[]>;
1491
+
1492
+ private readonly itemService = inject(ItemService);
1493
+
1494
+ constructor() {
1495
+ this.items = toSignal(this.itemService.getItems(), { initialValue: [] });
1496
+ }
1497
+ ```
1498
+
1499
+ - TS2612 (`Property 'x' will overwrite the base property`): a subclass declares again a field of its parent class,
1500
+ e.g. to narrow its type. Add `declare` (`declare form: MyForm | null | undefined;`) or remove the declaration, but
1501
+ never add an initializer: it would overwrite the value set by the parent class.
1502
+
1503
+ Now fix your project until no more errors (unlike `tsc -b`, these commands write nothing):
1439
1504
 
1440
1505
  ```bash
1441
- npx tsc -b --noEmit
1506
+ npx tsc -p tsconfig.app.json --noEmit
1507
+ npx tsc -p tsconfig.spec.json --noEmit
1442
1508
  ```
1443
1509
 
1510
+ `tsc` doesn't check the templates: the errors reported by `strictTemplates` appear when you build your application.
1511
+
1444
1512
  and finally run the following commands to build, test and start your application:
1445
1513
 
1446
1514
  ```bash
@@ -1449,6 +1517,358 @@ npm run test
1449
1517
  npm start
1450
1518
  ```
1451
1519
 
1520
+ ### `foehn-list-summary` is now generic (since 19.2.0)
1521
+
1522
+ `FoehnListSummaryComponent` is now `FoehnListSummaryComponent<T extends FoehnListItem>` and `FoehnListItemDescription` now takes a type parameter: `FoehnListItemDescription<T>`.
1523
+ Using `FoehnListItemDescription` without its type parameter no longer compiles.
1524
+
1525
+ 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`:
1526
+
1527
+ Before:
1528
+
1529
+ ```typescript
1530
+ getListItemsDescription(): FoehnListItemDescription[] {
1531
+ return [
1532
+ {
1533
+ label: 'Name',
1534
+ getFormattedValue: (item: FoehnListItem) =>
1535
+ (item as MyItem).name ?? '',
1536
+ },
1537
+ ];
1538
+ }
1539
+ ```
1540
+
1541
+ After:
1542
+
1543
+ ```typescript
1544
+ getListItemsDescription(): FoehnListItemDescription<MyItem>[] {
1545
+ return [
1546
+ {
1547
+ label: 'Name',
1548
+ getFormattedValue: (item: MyItem) => item.name ?? '',
1549
+ },
1550
+ ];
1551
+ }
1552
+ ```
1553
+
1554
+ The same applies to the function passed to `getListItemTitle`, which now receives a `MyItem`.
1555
+
1556
+ Never bind the list with a one-way `[model]` alone (see also "Quick fix"): the component removes the items itself,
1557
+ and only its `modelChange` passes the new list to your form. A one-way `[model]` compiles without warning, but the
1558
+ 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
1559
+ (see "The form of your pages is a signal"), write the list with `patchForm()`, the form guarded:
1560
+
1561
+ ```html
1562
+ @if (form(); as form) {
1563
+ <foehn-list-summary
1564
+ name="items"
1565
+ [model]="form.items"
1566
+ (modelChange)="patchForm(['items'], $event)"
1567
+ (itemRemoved)="itemRemoved()"
1568
+ />
1569
+ }
1570
+ ```
1571
+
1572
+ ### `core-js` is no longer needed (since 19.2.0)
1573
+
1574
+ prestations-ng no longer imports `core-js` and no longer has it as a peer dependency. If your project does not
1575
+ import `core-js` itself, uninstall it:
1576
+
1577
+ ```bash
1578
+ npm uninstall core-js
1579
+ ```
1580
+
1581
+ Then, in your `angular.json` file, remove `"core-js/modules/es.array.includes"` from `"allowedCommonJsDependencies"`.
1582
+ The CommonJS dependencies of prestations-ng are now `"iban"` and `"dayjs"` (which also covers `dayjs/plugin/*` and
1583
+ `dayjs/locale/*`):
1584
+
1585
+ ```json
1586
+ "allowedCommonJsDependencies": ["iban", "dayjs"]
1587
+ ```
1588
+
1589
+ Also remove the packages that are no longer installed (`npm ls <package>` lists nothing).
1590
+
1591
+ ### `reference` of your pages is a signal (since 19.2.0)
1592
+
1593
+ `reference` of `AbstractPageComponent` is now a `WritableSignal<string | null | undefined>`: read it with
1594
+ `reference()`, in the templates of your pages too, and write it with `reference.set()`. A template, a `computed()` or
1595
+ an `effect()` reading it follows the reference, also when your page sets it, without `markForCheck()`.
1596
+
1597
+ The `ng update` migration of 19.2.0 rewrites your pages (see "Run the migration" in "The form of your pages is a
1598
+ signal" below):
1599
+
1600
+ ```diff
1601
+ - this.http.get<FoehnRecapSection[]>(`api/${this.reference}/pdf-sections`)
1602
+ + this.http.get<FoehnRecapSection[]>(`api/${this.reference()}/pdf-sections`)
1603
+ ```
1604
+
1605
+ ```diff
1606
+ - this.reference = reference;
1607
+ + this.reference.set(reference);
1608
+ ```
1609
+
1610
+ In the templates, it reads it through a `@let reference = this.reference();`, so that the reads are unchanged
1611
+ (`[reference]="reference"`). It removes a field of a page declaring `reference` again (e.g. `reference: string;`),
1612
+ which would hide the signal, and lists such a field holding a value.
1613
+
1614
+ For a code it doesn't migrate (a class it doesn't recognize as a page):
1615
+
1616
+ - in the templates, `no-uninvoked-signal-in-template` (`configs.templateRecommended` or `configs.templateRules`, see
1617
+ [ESLINT_PLUGIN.md](ESLINT_PLUGIN.md)) reports `reference` without parentheses, and `ng lint --fix` adds them;
1618
+ - in TypeScript, the compiler reports the writes (`this.reference = ...`) and the arguments typed `string`. With
1619
+ `configs.tsRecommended`, `no-uncalled-signals` reports `!this.reference`, `this.reference && ...`,
1620
+ `'...' + this.reference` and `this.reference?.length`, and `restrict-template-expressions` reports
1621
+ `` `${this.reference}` ``. Nothing reports a read where any value is accepted, e.g. in an array
1622
+ (`this.router.navigate([prefix, this.reference])`): list the reads which are not calls, and check each of them
1623
+ (the fields named `reference` of your other classes are listed too):
1624
+
1625
+ ```bash
1626
+ grep -rnP "\bthis\.reference\b(?!\s*(\(|\.set\(|\.update\())" src --include=*.ts
1627
+ ```
1628
+
1629
+ In an `effect()`, reading `this.reference()` runs the effect again when the reference changes: read it with
1630
+ `untracked(this.reference)` when the effect must not follow it.
1631
+
1632
+ ### The form of your pages is a signal (since 19.2.0)
1633
+
1634
+ `form` of `AbstractPageComponent` is now a `WritableSignal<T | null | undefined>`: read it with `form()`, and never
1635
+ modify its value in place. Write it with `patchForm(path, value)`, which copies the objects along the path, or with
1636
+ `form.set()` / `form.update()` and a new object. A template, a `computed()` or an `effect()` reading it follows every
1637
+ input of the user, and no `markForCheck()` is needed after a write anymore.
1638
+
1639
+ #### Run the migration
1640
+
1641
+ `ng update @dsivd/prestations-ng` migrates your pages (the classes extending `AbstractPageComponent`,
1642
+ `AbstractMenuPageComponent`, `AbstractPageFromMenuComponent`, `AbstractListDetailPageComponent`, or one of your
1643
+ classes extending them) and their templates. It runs again at each beta of 19.2.0, which changes nothing once
1644
+ migrated. To run it by hand, e.g. on a branch updated meanwhile:
1645
+
1646
+ ```bash
1647
+ ng update @dsivd/prestations-ng --migrate-only --from=19.1.0 --to=19.2.0
1648
+ ```
1649
+
1650
+ Then format the files it changed (`prettier --write`), build, lint, and fix what it lists as "To check by hand"
1651
+ (see below).
1652
+
1653
+ In the templates, it reads the form through a `@let`, so that the reads and their narrowing (`@if (form)`) are
1654
+ unchanged, and writes the fields with `patchForm()`:
1655
+
1656
+ ```diff
1657
+ + @let form = this.form();
1658
+ @if (form) {
1659
+ - <foehn-input-text name="address.street" [(model)]="form.address.street" />
1660
+ + <foehn-input-text name="address.street" [model]="form.address.street" (modelChange)="patchForm(['address', 'street'], $event)" />
1661
+ - @for (child of form.children; track child) {
1662
+ + @for (child of form.children; track $index) {
1663
+ - <foehn-input-text [name]="'children[' + $index + '].firstName'" [(model)]="child.firstName" />
1664
+ + <foehn-input-text [name]="'children[' + $index + '].firstName'" [model]="child.firstName" (modelChange)="patchForm(['children', $index, 'firstName'], $event)" />
1665
+ }
1666
+ }
1667
+ ```
1668
+
1669
+ In the classes:
1670
+
1671
+ ```diff
1672
+ - this.form = form;
1673
+ + this.form.set(form);
1674
+ - this.form.firstName = info?.firstName ?? null;
1675
+ + this.patchForm(['firstName'], info?.firstName ?? null);
1676
+ - this.form.children.push(child);
1677
+ + this.patchForm(['children'], [...(this.form()!.children ?? []), child]);
1678
+ - if (this.form) {
1679
+ - this.http.post('api/check', this.form.amount);
1680
+ + if (this.form()) {
1681
+ + this.http.post('api/check', this.form()!.amount);
1682
+ ```
1683
+
1684
+ #### Check by hand
1685
+
1686
+ The migration leaves untouched, and lists with their file and line, what it can't rewrite. The compiler reports it
1687
+ too (`this.form.x` doesn't exist on a signal):
1688
+
1689
+ - the writes other than an assignment or a `push()` / `unshift()`: `+=`, `++`, `splice()`, `sort()`, a write inside
1690
+ an expression... Write a new value, e.g. `this.patchForm(['children'], children.filter((c) => c !== child))`;
1691
+ - the two-way bindings it can't follow: through a call or a pipe, or in a `*ngFor` over the form. Migrate the
1692
+ `*ngFor` to `@for` first (`ng generate @angular/core:control-flow`), then run the migration again;
1693
+ - the `getList()` of the detail pages which compute their list, see below.
1694
+
1695
+ Also check:
1696
+
1697
+ - your specs, which the migration doesn't change: `component.form = x` becomes `component.form.set(x)`, and
1698
+ `component.form.x` becomes `component.form()!.x` (the compiler reports them);
1699
+ - the components receiving the form, or an object of it, as an input and modifying it: they modify the value of the
1700
+ signal in place, the page isn't notified. Give them an output, and let the page write with `patchForm()`;
1701
+ - the `markForCheck()` called after a write of the form (zoneless): they are useless now, remove them.
1702
+
1703
+ `no-direct-signal-mutation` reports the writes in place left (`this.form()!.x = 1`, `form.children.push(child)`),
1704
+ `[(model)]="form.x"` inside `@if (form(); as form)` included.
1705
+
1706
+ #### Lists of the form
1707
+
1708
+ `patchForm()` replaces each object along the path with a copy: a row of a `@for` tracked by its item (`track child`)
1709
+ is then destroyed and created again at each input, and the field being edited loses the focus. Track the rows of a
1710
+ list edited by its rows by an identifier of the item (`track child.id`), or by `$index`. The migration does it for the
1711
+ lists it migrates, and `no-item-track-in-form-list` (`configs.templateRecommended`) reports the others.
1712
+
1713
+ #### Write your templates
1714
+
1715
+ ```html
1716
+ @if (form(); as form) {
1717
+ <foehn-input-text
1718
+ name="firstName"
1719
+ [model]="form.firstName"
1720
+ (modelChange)="patchForm(['firstName'], $event)"
1721
+ />
1722
+ }
1723
+ ```
1724
+
1725
+ - The path is checked by TypeScript: a typo gives an error listing the valid keys. For a form serving several
1726
+ prestations, type the page with a union (`AbstractPageComponent<ApForm | AfForm>`): the paths of each of them are
1727
+ accepted.
1728
+ - `null` and `undefined` are accepted, as with `[(model)]`: the model of the `foehn-*` components can be.
1729
+ - Never a `[model]` alone on a field the user can change: what the user enters would never reach the form.
1730
+ `require-model-change` (`configs.templateRecommended`) reports it. A field always disabled
1731
+ (`[disabled]="true"`), only displayed, is bound with `[model]` alone.
1732
+ - `@let form = this.form();`, which the migration adds, is just as valid.
1733
+ - Outside a page, `ObjectPathHelper` writes a path of any object the same way: `patch(object, path, value)`, and
1734
+ `patchSignal(signal, path, value)` for a signal holding an object (e.g. the state of a component), typed with
1735
+ `ObjectPath<T>` and `ObjectPathValue<T, P>`. `getByKeys()` and `patchByKeys()` take keys known at runtime only
1736
+ (`'address.street'`), not checked by TypeScript.
1737
+
1738
+ #### Detail pages
1739
+
1740
+ `AbstractListDetailPageComponent` no longer modifies the list of the form in place:
1741
+
1742
+ | Before | Since 19.2.0 |
1743
+ | ---------------------------------------------- | ----------------------------------------------------------------------------------------- |
1744
+ | `getList(): Dog[] { return this.form.dogs; }` | `getListPath(): ObjectPath<MyForm> { return ['dogs']; }` (`getList()` is still available) |
1745
+ | `list`, `itemIndex`, `itemToEdit` | `list()`, `itemIndex()`, `itemToEdit()` |
1746
+ | `[(model)]="itemToEdit.name"` | `[model]="item.name" (modelChange)="patchItem(['name'], $event)"` |
1747
+ | `this.itemToEdit.site = null; ...` (in place) | `this.updateItem((item) => ({ ...item, site: null, ideNumber: null }))` |
1748
+ | `[(model)]="list[itemIndex]"` (the whole item) | `[model]="item" (modelChange)="setItem($event)"` |
1749
+
1750
+ The migration replaces a `getList()` returning a path of the form (`this.form.a.b`, `this.form?.a?.b ?? []`). A
1751
+ `getList()` choosing its list (e.g. according to the prestation) becomes a `getListPath()` choosing its path:
1752
+
1753
+ ```ts
1754
+ getListPath(): ObjectPath<ApForm | AfForm> {
1755
+ return this.isAp()
1756
+ ? ['diplomeData', 'diplomes']
1757
+ : ['formationData', 'diplomes'];
1758
+ }
1759
+ ```
1760
+
1761
+ ### Zoneless (optional but recommended)
1762
+
1763
+ Since v19.2, prestations-ng does not need zone.js anymore: the state of its components is held by signals, which
1764
+ tell Angular when a component has to be refreshed. prestations-ng keeps working in an application using zone.js,
1765
+ so this step is optional, but a zoneless application is lighter, faster and easier to debug. See the
1766
+ [Angular zoneless guide](https://angular.dev/guide/zoneless).
1767
+
1768
+ In any case, if your code reads some fields of the prestations-ng components (e.g. through `viewChild()` or in
1769
+ your tests), check the fields that are now signals in the [CHANGELOG](CHANGELOG.md#1920---should-be-aligned-with-prestations-be-192x).
1770
+
1771
+ #### Enable the zoneless change detection
1772
+
1773
+ Zoneless is the default since Angular 21: `ng update` added `provideZoneChangeDetection()` to keep zone.js in your
1774
+ application. Replace it in your `app.config.ts` (`providePrestationsNgCore()` already provides
1775
+ `provideBrowserGlobalErrorListeners()`, which reports to your `ErrorHandler` the errors zone.js used to catch):
1776
+
1777
+ ```diff
1778
+ export const appConfig: ApplicationConfig = {
1779
+ providers: [
1780
+ - provideZoneChangeDetection({ eventCoalescing: true }),
1781
+ + provideZonelessChangeDetection(),
1782
+ providePrestationsNgCore(),
1783
+ ...
1784
+ ],
1785
+ };
1786
+ ```
1787
+
1788
+ Remove `zone.js` and `zone.js/testing` from the `polyfills` of the `build` and `test` targets in your
1789
+ `angular.json` (and from your `polyfills.ts` file if you still have one): without them, the `TestBed` is zoneless
1790
+ too.
1791
+
1792
+ ```diff
1793
+ "polyfills": [
1794
+ - "zone.js"
1795
+ ],
1796
+ ```
1797
+
1798
+ then uninstall zone.js:
1799
+
1800
+ ```bash
1801
+ npm uninstall zone.js
1802
+ ```
1803
+
1804
+ `zone.js` can stay in your `package-lock.json` as an optional peer dependency of `@angular/core`: this is expected. Check
1805
+ instead that the build of your application no longer outputs a `polyfills` chunk (unless you still have other
1806
+ polyfills, e.g. `@angular/localize/init`).
1807
+
1808
+ #### Check your components
1809
+
1810
+ Without zone.js, Angular refreshes a component only when it is notified that something changed:
1811
+
1812
+ - a listener of its template has been called (`(click)`, `(modelChange)`, `(userInput)`...), including the
1813
+ `[(model)]` two-way bindings
1814
+ - a signal read by its template has changed (`signal()`, `computed()`, `input()`, `model()`, `toSignal()`...)
1815
+ - `ChangeDetectorRef.markForCheck()` has been called, which is what the `async` pipe does when an observable emits
1816
+
1817
+ A field modified elsewhere (in a `subscribe()`, a `setTimeout()`, a `Promise`, a callback, an `effect()`...) is not
1818
+ displayed anymore until something else refreshes the component. Hold it in a signal (see
1819
+ [INTRODUCTION_ANGULAR_SIGNALS.md](INTRODUCTION_ANGULAR_SIGNALS.md)), as well as the fields read by the template that
1820
+ only a method called by a listener modifies: this method can later be called from elsewhere.
1821
+
1822
+ ```diff
1823
+ - isLoading = true;
1824
+ + readonly isLoading = signal(true);
1825
+
1826
+ ngOnInit(): void {
1827
+ this.myService.load().subscribe(() => {
1828
+ - this.isLoading = false;
1829
+ + this.isLoading.set(false);
1830
+ });
1831
+ }
1832
+ ```
1833
+
1834
+ ```diff
1835
+ - @if (isLoading) {
1836
+ + @if (isLoading()) {
1837
+ ```
1838
+
1839
+ Pay attention to:
1840
+
1841
+ - your pages (`AbstractPageComponent` and its subclasses): since 19.2.0, `form` and `reference` are signals (see "The
1842
+ form of your pages is a signal" and "`reference` of your pages is a signal"). Write the form with `patchForm()`,
1843
+ never in place: no `markForCheck()` is needed after a write.
1844
+
1845
+ - the fields read by the template and set in `ngAfterViewInit()`, `ngAfterContentInit()` or `ngAfterViewChecked()`:
1846
+ derive them with `computed()` from `viewChild()` or `contentChild()` (see "Deriving a state from view queries"
1847
+ in [GOOD_PRACTICES.md](GOOD_PRACTICES.md)).
1848
+
1849
+ - `NgZone`: `onStable`, `onMicrotaskEmpty` and `onUnstable` never emit without zone.js, and `run()` or
1850
+ `runOutsideAngular()` are useless. To act on the rendered DOM (focus, scroll...), replace them, as well as the
1851
+ `setTimeout()` waiting for the view, by `afterNextRender()`. `AbstractMenuPageComponent.ngZone` is deprecated.
1852
+
1853
+ ```diff
1854
+ - this.ngZone.onStable.pipe(first()).subscribe(() => this.focusFirstField());
1855
+ + afterNextRender(() => this.focusFirstField(), { injector: this.injector });
1856
+ ```
1857
+
1858
+ #### Check your tests
1859
+
1860
+ - `fakeAsync()`, `tick()`, `flush()` and `waitForAsync()` need zone.js: write `async` tests, with
1861
+ `vi.useFakeTimers()` and `await vi.advanceTimersByTimeAsync(ms)` to control the timers (see
1862
+ [Migrate to vitest](#migrate-to-vitest)).
1863
+ - `fixture.detectChanges()` only refreshes the views which have been notified, then checks that nothing changed
1864
+ meanwhile: a field modified without notification makes the test fail with the error `NG0100`
1865
+ (`ExpressionChangedAfterItHasBeenCheckedError`). Fix the component (signal, `markForCheck()`) rather than the
1866
+ test.
1867
+ - `await fixture.whenStable()` waits for the change detection and for the pending tasks of the application
1868
+ (e.g. the debounced `userInput` of the prestations-ng inputs), not for the timers, nor for the HTTP requests of a
1869
+ spec: `provideHttpClientTesting()` keeps them pending until the test answers them. Answer them first with
1870
+ `HttpTestingController` (`expectOne(...).flush(...)`), then `await fixture.whenStable()`.
1871
+
1452
1872
  ### Last but not least, check if your application is working!!!
1453
1873
 
1454
1874
  #### Be sure your application gets a fresh start
@@ -1488,7 +1908,8 @@ See [getImtPortailApplications](https://dsigit.etat-de-vaud.ch/outils/git/projec
1488
1908
  'project': 'cybersdk',
1489
1909
  'name' : 'skeleton',
1490
1910
  'gitUrl' : 'ssh://git@bitbucket.etat-de-vaud.ch/cybsdk/skeleton.git',
1491
- 'jdk' : '21',
1911
+ - 'jdk' : '21',
1912
+ + 'jdk' : '25',
1492
1913
  - 'node' : '20'
1493
1914
  + 'node' : '22'
1494
1915
  ],
@@ -0,0 +1,34 @@
1
+ /**
2
+ * The house preset of the Vitest specs: the recommended rules of `@vitest/eslint-plugin`, with the
3
+ * assertions also made by the helpers of the specs and by the `HttpTestingController`.
4
+ *
5
+ * Meant for the `extends` of a `**\/*.spec.ts` block (the Cypress `*.spec.cy.ts` files are not
6
+ * Vitest specs).
7
+ *
8
+ * @param {import('@vitest/eslint-plugin').default} vitest the `@vitest/eslint-plugin` module
9
+ * @returns {import('typescript-eslint').ConfigArray}
10
+ */
11
+ const specTsRecommended = (vitest) => [
12
+ vitest.configs.recommended,
13
+ {
14
+ name: 'prestations-ng/spec-ts-recommended',
15
+ rules: {
16
+ 'vitest/expect-expect': [
17
+ 'error',
18
+ {
19
+ assertFunctionNames: [
20
+ 'expect',
21
+ 'expect*',
22
+ 'assert*',
23
+ 'test*',
24
+ '*.expectOne',
25
+ '*.expectNone',
26
+ '*.verify',
27
+ ],
28
+ },
29
+ ],
30
+ },
31
+ },
32
+ ];
33
+
34
+ export default specTsRecommended;
@@ -8,6 +8,8 @@ import templateRules from './template-rules.mjs';
8
8
  *
9
9
  * Meant for the `extends` of a `**\/*.html` block. It brings its own parser and plugins,
10
10
  * so do not spread `angular.configs.templateRecommended` alongside it.
11
+ *
12
+ * @returns {import('typescript-eslint').ConfigArray}
11
13
  */
12
14
  const templateRecommended = (plugin) => [
13
15
  ...angular.configs.templateRecommended,
@@ -1,7 +1,11 @@
1
1
  import templateBase from './template-base.mjs';
2
2
 
3
- // Only the rules written by this library. `templateRecommended` includes it, alongside
4
- // the house style; use this layer directly to opt out of the latter.
3
+ /**
4
+ * Only the rules written by this library. `templateRecommended` includes it, alongside
5
+ * the house style; use this layer directly to opt out of the latter.
6
+ *
7
+ * @returns {import('typescript-eslint').ConfigArray}
8
+ */
5
9
  const templateRules = (plugin) => [
6
10
  templateBase(plugin),
7
11
  {
@@ -11,6 +15,11 @@ const templateRules = (plugin) => [
11
15
  // template visitor, and each fires on its own kind of file.
12
16
  '@dsivd/prestations-ng/no-direct-signal-mutation': 'error',
13
17
  '@dsivd/prestations-ng/no-uninvoked-signal-in-template': 'error',
18
+ // The form of the pages is a signal: a one-way [model] without
19
+ // (modelChange) loses the input, and a row tracked by its item
20
+ // loses the focus at every input
21
+ '@dsivd/prestations-ng/require-model-change': 'error',
22
+ '@dsivd/prestations-ng/no-item-track-in-form-list': 'error',
14
23
  },
15
24
  },
16
25
  ];
@@ -14,6 +14,8 @@ import tsRules from './ts-rules.mjs';
14
14
  * Meant for the `extends` of a `**\/*.ts` block. It brings its own parser and plugins,
15
15
  * so do not spread `angular.configs.tsRecommended` alongside it — declaring the same
16
16
  * plugin twice from two different copies makes ESLint fail outright.
17
+ *
18
+ * @returns {import('typescript-eslint').ConfigArray}
17
19
  */
18
20
  const tsRecommended = (plugin) => [
19
21
  eslint.configs.recommended,
@@ -71,6 +73,10 @@ const tsRecommended = (plugin) => [
71
73
  ],
72
74
  '@typescript-eslint/member-ordering': 'error',
73
75
  '@typescript-eslint/no-base-to-string': 'warn',
76
+ // a template literal only takes strings, numbers, booleans, null,
77
+ // undefined, any and RegExp: also reports a signal not called
78
+ // (`${this.reference}`), which no-uncalled-signals skips there
79
+ '@typescript-eslint/restrict-template-expressions': 'error',
74
80
  // stylistic enables no-inferrable-types with default options (ignoreParameters: false);
75
81
  // override here to allow typed parameters explicitly
76
82
  '@typescript-eslint/no-inferrable-types': [